An open source design system that's fully customizable and agent ready
TypeScript
docs(lab): close the Drawer docsite gap ahead of promotion (#6770)
Xinzi Zhou7218530af1b0
diff --git a/.github/scripts/modal-close-visibility.js b/.github/scripts/modal-close-visibility.jsindex 2b24bd2fe9..adca982beb 100644--- a/.github/scripts/modal-close-visibility.js+++ b/.github/scripts/modal-close-visibility.js@@ -16,14 +16,15 @@* layer can paint back inside a transformed ancestor for one frame (#5549).* It must be hidden before the next paint.* 3. The non-modal Popover host must preserve `<dialog>`'s observable `close`- * event so ref/onClose consumers keep their focus-restoration contract, and- * must dispatch it after the drawer's own focus restore: native close events- * are task-queued, so a consumer close listener that retargets focus- * (master-detail row switching) always had the last word.+ * event so ref/onClose consumers keep their focus-restoration contract. The+ * companion ordering — the event dispatches after the drawer's own focus+ * restore, so a close listener that retargets focus (master-detail row+ * switching) has the last word — is covered at unit level: Drawer.test.tsx+ * "dispatches the synthetic close after focus restore so a close listener+ * owns final focus".* 4. A closing top drawer stays on the shared dismissal stack until its visual* exit completes, so a second Escape cannot dismiss the drawer below it.- * 5. After a completed exit, focus rests on the element focused at open — or on- * the element a consumer close listener chose instead (contract 3).+ * 5. After a completed exit, focus rests on the element focused at open.** None of these orderings exists in jsdom: it runs no CSS transition and has no* top layer. Runs in Chromium by default; `--browser webkit` runs the same@@ -72,15 +73,12 @@ const TARGETS = [{component: 'Drawer (non-modal)',story: 'lab-drawer--row-inspector',- openButton: 'web-01 / us-east-1',+ openButton: 'Open drawer',host: 'popover',transformAncestor: true,mustBeHiddenAfterClose: true,mustDispatchClose: true,- // Exercises contract 3's ordering: the drawer restores web-01 (its- // trigger), then this listener must win with the latest selected row.- closeListenerFocus: 'web-02 / us-east-1',- finalFocus: 'web-02 / us-east-1',+ finalFocus: 'Open drawer',},{component: 'Drawer (stacked exit)',@@ -249,22 +247,6 @@ async function probe(page, target) {{timeout: 5000},);- if (target.closeListenerFocus) {- await page.evaluate(- ({selector, focusLabel}) => {- const dialog = document.querySelector(selector);- const retarget = [...document.querySelectorAll('button')].find(- button => (button.textContent || '').trim() === focusLabel,- );- if (!(dialog instanceof HTMLElement) || !retarget) {- throw new Error('close-listener focus fixture not found');- }- dialog.addEventListener('close', () => retarget.focus(), {once: true});- },- {selector: hostSelector, focusLabel: target.closeListenerFocus},- );- }-let stackedExitOwned = true;if (target.stackedExit) {const outer = page.getByRole('dialog', {name: target.outerLabel});diff --git a/apps/storybook/stories/Drawer.stories.tsx b/apps/storybook/stories/Drawer.stories.tsxindex 2ca2c12c65..1da908a44e 100644--- a/apps/storybook/stories/Drawer.stories.tsx+++ b/apps/storybook/stories/Drawer.stories.tsx@@ -51,12 +51,6 @@ const meta: Meta<typeof Drawer> = {export default meta;type Story = StoryObj<typeof Drawer>;-const HOSTS = [- {id: 'web-01', region: 'us-east-1', status: 'Healthy', cpu: '32%'},- {id: 'web-02', region: 'us-east-1', status: 'Healthy', cpu: '41%'},- {id: 'worker-01', region: 'eu-west-1', status: 'Degraded', cpu: '87%'},-];-const REGIONS = ['us-east-1', 'eu-west-1', 'ap-south-1'];export const Showcase: Story = {@@ -97,46 +91,31 @@ export const Showcase: Story = {},};+/**+ * Non-modal inspector: no scrim, no focus trap, and the page behind stays+ * interactive. In a real master-detail flow, derive the open state from the+ * selection (`isOpen={selected != null}`) and clear it in `onOpenChange`.+ */export const RowInspector: Story = {render: () => {- const [selected, setSelected] = useState(HOSTS[0]);const [isOpen, setIsOpen] = useState(false);return (<>- <VStack gap={1}>- {HOSTS.map(host => (- <Button- key={host.id}- variant="ghost"- label={`${host.id} / ${host.region}`}- onClick={() => {- setSelected(host);- setIsOpen(true);- }}- />- ))}- </VStack>+ <Button label="Open drawer" onClick={() => setIsOpen(true)} /><DrawerisOpen={isOpen}onOpenChange={setIsOpen}- label={`Host details: ${selected.id}`}+ label="Details"hasScrim={false}width={360}><Section padding={4}><VStack gap={4}><VStack gap={1}>- <Heading level={3}>{selected.id}</Heading>+ <Heading level={3}>Details</Heading><Text type="supporting" color="secondary">- {selected.region}+ The page behind stays interactive.</Text></VStack>- <Divider />- <VStack gap={2}>- <Text type="label">Status</Text>- <Text type="body">{selected.status}</Text>- <Text type="label">CPU</Text>- <Text type="body">{selected.cpu}</Text>- </VStack><Buttonlabel="Close inspector"variant="secondary"diff --git a/packages/lab/src/Drawer/Drawer.doc.mjs b/packages/lab/src/Drawer/Drawer.doc.mjsindex 769558faf6..7e31c6f6ad 100644--- a/packages/lab/src/Drawer/Drawer.doc.mjs+++ b/packages/lab/src/Drawer/Drawer.doc.mjs@@ -1,4 +1,40 @@// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Drawer.doc.mjs+ * @input Drawer props, panel anatomy, overlay playground config, and story-aligned examples+ * @output Consumer documentation and examples for Drawer+ * @position CLI and rendered component documentation+ */++/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Panel',+ required: true,+ description:+ 'The root <dialog> element: a full-height surface anchored to the inline start or end edge, flush with three viewport edges (square corners).',+ },+ {+ name: 'Content area',+ required: true,+ description:+ 'Full-bleed scrollable region that receives children; compose your own header, body, and footer inside it.',+ },+ {+ name: 'Close button',+ required: false,+ description:+ 'Built-in dismissal affordance floating in the top-trailing corner; pass hasCloseButton={false} when the content provides its own.',+ },+ {+ name: 'Scrim',+ required: false,+ description:+ 'Backdrop that dims and blocks the page behind a modal drawer (hasScrim, the default); a non-modal drawer renders none.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {@@ -18,6 +54,33 @@ export const docs = {'dialog','side drawer',],+ // No isInline docs-preview prop (the drawer has no inline containment), so+ // this is the overlay preview: closed on load with an open trigger, knobs+ // live, and opening renders the real top-layer drawer — see+ // ComponentPlaygroundConfig.overlay (#3657).+ playground: {+ overlay: true,+ defaults: {+ isOpen: false,+ label: 'Details',+ children: {+ __element: 'Section',+ props: {padding: 4},+ children: {+ __element: 'VStack',+ props: {gap: 2},+ children: [+ {__element: 'Heading', props: {level: 3}, children: 'Details'},+ {+ __element: 'Text',+ props: {type: 'body'},+ children: 'Adjust the properties below, then open the preview.',+ },+ ],+ },+ },+ },+ },theming: {targets: [{className: 'astryx-drawer', visualProps: ['side']}],},@@ -89,8 +152,9 @@ export const docs = {},],usage: {+ anatomy,description:- 'A side panel that floats above page content for inspectors and detail views: the "click a table row, see its details" pattern. Unlike a docked panel it overlays the layout instead of reflowing it. Works on desktop and touch: the width budget applies on desktop and the panel preserves a 56px page reveal below 640px without exceeding the width budget. Escape closes the drawer and focus returns to the element that opened it. Entry/exit slide animation respects prefers-reduced-motion. Stacking contract: sibling drawers stack last-opened on top, Escape closes only the topmost, and closing peels innermost-first; render them as siblings, never nested.',+ 'A side panel that floats above page content for inspectors and detail views: the "click a table row, see its details" pattern. Unlike a docked panel it overlays the layout instead of reflowing it. Works on desktop and touch: the width budget applies on desktop and the panel preserves a 56px page reveal below 640px without exceeding the width budget. Escape closes the drawer and focus returns to the element that opened it. Entry/exit slide animation respects prefers-reduced-motion. Stacking contract: sibling drawers stack last-opened on top, Escape closes only the topmost, and closing peels innermost-first; render them as siblings, never nested.\n\nThe content area is full-bleed: compose your own header, body, and footer. A plain recipe is all a drawer needs — Section padding={4} wrapping a VStack with a Heading, body content, and trailing actions; there is no DrawerHeader sub-component. The built-in close button floats above the content in the top-trailing corner, so leave it clearance in a custom header row, or pass hasCloseButton={false} when the content provides its own dismissal. Put data-autofocus on the control that should receive focus on open.\n\nChoosing a surface: use Dialog for a centered decision or short form, Drawer for full-height side detail that keeps the page in sight, BottomSheet for block-axis sheets on touch, and a docked panel (a layout column) when content should reflow the page instead of floating over it.\n\nTheming: the panel is the single stable target (astryx-drawer, with data-side reflecting side). The scrim is the panel\'s native ::backdrop, and the built-in close button is a ghost Button reachable through the astryx-button target.',bestPractices: [{guidance: true,@@ -135,6 +199,73 @@ export const docs = {],},examples: [+ {+ label: 'Non-modal inspector (page stays interactive)',+ code: `const [isOpen, setIsOpen] = useState(false);+<>+ <Button label="Open drawer" onClick={() => setIsOpen(true)} />+ <Drawer+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ label="Details"+ hasScrim={false}+ width={360}>+ <Section padding={4}>+ <VStack gap={2}>+ <Heading level={3}>Details</Heading>+ <Text type="body">The page behind stays interactive.</Text>+ <Button+ label="Close"+ variant="secondary"+ onClick={() => setIsOpen(false)}+ />+ </VStack>+ </Section>+ </Drawer>+</>+// Non-modal: no scrim, no focus trap. In a real master-detail flow, derive+// the open state from the selection — isOpen={selected != null} — and clear+// the selection in onOpenChange.`,+ },+ {+ label: 'Slide in from the start edge',+ code: `const [isOpen, setIsOpen] = useState(false);+<Drawer+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ label="Navigation"+ side="start">+ <NavPanel />+</Drawer>+// 'start' is left in LTR and mirrors under RTL; 'end' (the default) is the+// inspector convention.`,+ },+ {+ label: 'Width budget: pixels or any CSS length',+ code: `const [isOpen, setIsOpen] = useState(false);+<Drawer+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ label="Details"+ width="50%">+ <DetailsPanel />+</Drawer>+// A number is pixels (width={320}); a string is any CSS length ('32rem',+// '50%'). The budget also caps the drawer on mobile.`,+ },+ {+ label: 'Mobile: the 56px page reveal (default)',+ code: `const [isOpen, setIsOpen] = useState(false);+<Drawer+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ label="Filters"+ width={360}>+ <FilterControls />+</Drawer>+// Below 640px the panel preserves a 56px reveal of the page behind (still+// capped by width), so the drawer reads as an overlay, not a navigation.`,+ },{label: 'Wide desktop panel, full-width on mobile',code: `const [isOpen, setIsOpen] = useState(false);@@ -146,6 +277,26 @@ export const docs = {isFullWidthOnMobile><FilterControls /></Drawer>`,+ },+ {+ label: 'Modal or non-modal (hasScrim)',+ code: `const [openModal, setOpenModal] = useState(false);+const [openPanel, setOpenPanel] = useState(false);+<>+ {/* Modal (default): the scrim dims the page, focus is trapped, and a+ scrim click closes. */}+ <Drawer isOpen={openModal} onOpenChange={setOpenModal} label="Edit details">+ <EditForm />+ </Drawer>+ {/* Non-modal: no scrim, no focus trap; the page behind stays interactive. */}+ <Drawer+ isOpen={openPanel}+ onOpenChange={setOpenPanel}+ label="Details"+ hasScrim={false}>+ <DetailsPanel />+ </Drawer>+</>`,},{label: 'Stacked drill-in (siblings, not nested)',@@ -175,8 +326,34 @@ const [lineItem, setLineItem] = useState(null);/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */export const docsZh = {usage: {+ anatomy: [+ {+ name: 'Panel',+ required: true,+ description:+ '根 <dialog> 元素:锚定于行内起始或结束边缘的全高表面,与三个视口边缘齐平(直角)。',+ },+ {+ name: 'Content area',+ required: true,+ description:+ '不带内边距的可滚动区域,承载 children;页眉、正文、页脚在其中自行组合。',+ },+ {+ name: 'Close button',+ required: false,+ description:+ '内置关闭按钮,悬浮在顶部尾随角;内容自带关闭操作时用 hasCloseButton={false} 移除。',+ },+ {+ name: 'Scrim',+ required: false,+ description:+ '模态抽屉(hasScrim,默认开启)背后调暗并阻止页面交互的背景层;非模态抽屉没有。',+ },+ ],description:- '浮在页面内容之上的侧边面板,用于检查器和详情视图——"点击表格行查看详情"的模式。与停靠面板不同,它覆盖在布局之上,不会挤压页面。桌面端按 width 设定宽度,宽度小于 640px 时保留 56px 的底层页面,并且不超过 width 上限。按 Escape 关闭抽屉,焦点返回到打开它的元素。滑入/滑出动画遵循 prefers-reduced-motion。堆叠约定:同级抽屉后开的在上层,Escape 只关闭最上层的,关闭顺序由内向外——请以同级方式渲染,切勿嵌套。',+ '浮在页面内容之上的侧边面板,用于检查器和详情视图——"点击表格行查看详情"的模式。与停靠面板不同,它覆盖在布局之上,不会挤压页面。桌面端按 width 设定宽度,宽度小于 640px 时保留 56px 的底层页面,并且不超过 width 上限。按 Escape 关闭抽屉,焦点返回到打开它的元素。滑入/滑出动画遵循 prefers-reduced-motion。堆叠约定:同级抽屉后开的在上层,Escape 只关闭最上层的,关闭顺序由内向外——请以同级方式渲染,切勿嵌套。\n\n内容区域不带内边距:页眉、正文、页脚由你自行组合。一个简单的配方即可——用 Section padding={4} 包裹 VStack,内含 Heading、正文与末尾操作;没有 DrawerHeader 子组件。内置关闭按钮悬浮在顶部尾随角上方,请在自定义页眉行中为它留出空间,或在内容自带关闭操作时传 hasCloseButton={false}。在打开时应获得焦点的控件上加 data-autofocus。\n\n如何选择:居中的决定或短表单用 Dialog;保持页面可见的全高侧边详情用 Drawer;触屏上的块轴面板用 BottomSheet;内容应当把页面挤开重排时用停靠面板(布局分栏),而不是浮层。\n\n主题化:面板是唯一的稳定目标(astryx-drawer,data-side 反映 side 值);遮罩是面板的原生 ::backdrop;内置关闭按钮是 ghost 变体的 Button,可通过 astryx-button 目标定制。',bestPractices: [{guidance: true,@@ -227,8 +404,9 @@ export const docsDense = {description:'side panel floating over content (native <dialog>): start/end edge, full height',usage: {+ anatomy,description:- 'Overlay side panel for inspectors and detail views; floats over content, never reflows it. width = desktop budget; 56px page reveal below 640px, capped by width (isFullWidthOnMobile for all of it). Escape closes topmost; focus restores to the opener. Siblings stack last-opened on top; never nest. Slide animation respects prefers-reduced-motion.',+ 'Overlay side panel for inspectors and detail views; floats over content, never reflows it. width = desktop budget; 56px page reveal below 640px, capped by width (isFullWidthOnMobile for all of it). Escape closes topmost; focus restores to the opener. Siblings stack last-opened on top; never nest. Slide animation respects prefers-reduced-motion. Compose header/body/footer yourself in the full-bleed scroll area (Section padding={4} + VStack; no DrawerHeader; built-in close button floats top-trailing, hasCloseButton={false} to remove; data-autofocus picks the focus target). Choose: Dialog for centered decisions/short forms, Drawer for full-height side detail, BottomSheet for block-axis sheets, docked layout column to reflow instead of float. Theming: single target astryx-drawer (data-side); scrim is its ::backdrop; close button is a ghost Button (astryx-button).',bestPractices: [{guidance: true,