Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(lab): Drawer is a container, like Dialog (#6885)

Xinzi Zhou7189141b9325
diff --git a/.changeset/lab-drawer-container-padding.md b/.changeset/lab-drawer-container-padding.md
new file mode 100644
index 0000000000..b1c4dbec64
--- /dev/null
+++ b/.changeset/lab-drawer-container-padding.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Drawer is a container, like Dialog. A new `padding` prop takes a spacing step, and a theme's `padding` on `drawer` pads the drawer's scrolling content area through container tokens instead of padding the panel. The padded content area publishes its inset, so a Section that is the drawer's only child, and bleed children such as Table and Divider, align against it, and a Layout inside picks the value up for its header, content, and footer regions. With neither set, the inset is `--spacing-4`, as in Dialog; pass `padding={0}` for a full-bleed content area. The block-end safe-area inset is preserved in every mode.
+
+@imdreamrunner
diff --git a/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx
index 26ac2bb80c..8c03fa6a42 100644
--- a/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/pages/component-scores/page.tsx
@@ -12,7 +12,7 @@
import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
import * as stylex from '@stylexjs/stylex';
-import {VStack, HStack} from '@astryxdesign/core/Layout';
+import {Layout, LayoutContent, VStack, HStack} from '@astryxdesign/core/Layout';
import {Text, Heading} from '@astryxdesign/core/Text';
import {TextInput} from '@astryxdesign/core/TextInput';
import {Button} from '@astryxdesign/core/Button';
@@ -32,12 +32,8 @@ import {MetadataList, MetadataListItem} from '@astryxdesign/core/MetadataList';
import {Section} from '@astryxdesign/core/Section';
import {Table, proportional, pixel} from '@astryxdesign/core/Table';
import type {TableColumn, TablePlugin} from '@astryxdesign/core/Table';
-import {
- colorVars,
- radiusVars,
- spacingVars,
-} from '@astryxdesign/core/theme/tokens.stylex';
-import {Drawer, Stat} from '@astryxdesign/lab';
+import {colorVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';
+import {Drawer, DrawerHeader, Stat} from '@astryxdesign/lab';
import {
AUDIT_PROMPT,
@@ -385,14 +381,8 @@ function AuditDetails({
entry.rubricVersion !== currentRubricVersion;
return (
- <VStack gap={5} padding={5}>
- <VStack gap={2} xstyle={styles.drawerHeader}>
- <Heading level={2} tabIndex={-1} data-autofocus>
- {row.component}
- </Heading>
- <Text type="supporting" color="secondary">
- {row.package} component audit
- </Text>
+ <VStack gap={5}>
+ <VStack gap={2}>
<HStack gap={2} vAlign="center" wrap="wrap">
<Badge
variant={
@@ -601,6 +591,7 @@ export default function ComponentScoresPage() {
const [selectedRowId, setSelectedRowId] = useState<string | null>(null);
const [isAuditPanelOpen, setIsAuditPanelOpen] = useState(false);
const drawerRef = useRef<HTMLDialogElement>(null);
+ const auditContentRef = useRef<HTMLDivElement>(null);
const auditTriggerRef = useRef<HTMLElement | null>(null);
const filterInputRef = useRef<HTMLInputElement>(null);
@@ -666,9 +657,10 @@ export default function ComponentScoresPage() {
const frame = window.requestAnimationFrame(() => {
const dialog = drawerRef.current;
- const scrollContainer = dialog?.firstElementChild;
- if (scrollContainer instanceof HTMLElement) {
- scrollContainer.scrollTop = 0;
+ // The Layout's content region is the scroller; the drawer keeps its
+ // header pinned above it.
+ if (auditContentRef.current) {
+ auditContentRef.current.scrollTop = 0;
}
dialog?.querySelector<HTMLElement>('[data-autofocus]')?.focus();
});
@@ -1046,12 +1038,31 @@ export default function ComponentScoresPage() {
: 'Component audit details'
}
hasScrim={false}
- hasCloseButton
width={560}>
{selectedRow ? (
- <AuditDetails
- row={selectedRow}
- currentRubricVersion={ledger?.rubricVersion ?? null}
+ <Layout
+ header={
+ <DrawerHeader
+ // The title is the focus target on open and on row switch,
+ // so the changed audit is announced.
+ title={
+ <span tabIndex={-1} data-autofocus>
+ {selectedRow.component}
+ </span>
+ }
+ subtitle={selectedRow.package + ' component audit'}
+ onOpenChange={setIsAuditPanelOpen}
+ hasDivider
+ />
+ }
+ content={
+ <LayoutContent ref={auditContentRef}>
+ <AuditDetails
+ row={selectedRow}
+ currentRubricVersion={ledger?.rubricVersion ?? null}
+ />
+ </LayoutContent>
+ }
/>
) : null}
</Drawer>
@@ -1067,9 +1078,6 @@ const styles = stylex.create({
backgroundColor: colorVars['--color-neutral'],
borderRadius: radiusVars['--radius-inner'],
},
- drawerHeader: {
- paddingInlineEnd: spacingVars['--spacing-10'],
- },
tabularValue: {
fontVariantNumeric: 'tabular-nums',
},
diff --git a/apps/sandbox/src/app/(sandbox)/templates/page.tsx b/apps/sandbox/src/app/(sandbox)/templates/page.tsx
index bdc8488f95..daa752ac65 100644
--- a/apps/sandbox/src/app/(sandbox)/templates/page.tsx
+++ b/apps/sandbox/src/app/(sandbox)/templates/page.tsx
@@ -20,7 +20,7 @@ import {Card} from '@astryxdesign/core/Card';
import {Code} from '@astryxdesign/core/Code';
import {Divider} from '@astryxdesign/core/Divider';
import {Grid} from '@astryxdesign/core/Grid';
-import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {HStack, Layout, LayoutContent, VStack} from '@astryxdesign/core/Layout';
import {Link} from '@astryxdesign/core/Link';
import {MetadataList, MetadataListItem} from '@astryxdesign/core/MetadataList';
import {MoreMenu} from '@astryxdesign/core/MoreMenu';
@@ -30,14 +30,10 @@ import {Table, pixel, proportional} from '@astryxdesign/core/Table';
import type {TableColumn, TablePlugin} from '@astryxdesign/core/Table';
import {Heading, Text} from '@astryxdesign/core/Text';
import {TextInput} from '@astryxdesign/core/TextInput';
-import {
- colorVars,
- radiusVars,
- spacingVars,
-} from '@astryxdesign/core/theme/tokens.stylex';
+import {colorVars, radiusVars} from '@astryxdesign/core/theme/tokens.stylex';
import {Toolbar} from '@astryxdesign/core/Toolbar';
import {useToast} from '@astryxdesign/core/Toast';
-import {Drawer, Stat} from '@astryxdesign/lab';
+import {Drawer, DrawerHeader, Stat} from '@astryxdesign/lab';
import {
TEMPLATE_AUDIT_CATEGORIES,
@@ -352,11 +348,8 @@ function TemplateAuditDetails({row}: {row: TemplateRow}) {
);
return (
- <VStack gap={5} padding={5}>
- <VStack gap={2} xstyle={styles.drawerHeader}>
- <Heading level={2} tabIndex={-1} data-autofocus>
- {row.name}
- </Heading>
+ <VStack gap={5}>
+ <VStack gap={2}>
<HStack gap={2} vAlign="center" wrap="wrap">
<Badge
label={row.type}
@@ -571,6 +564,7 @@ export default function TemplatesPage() {
const [selectedRowId, setSelectedRowId] = useState<string | null>(null);
const [isAuditPanelOpen, setIsAuditPanelOpen] = useState(false);
const drawerRef = useRef<HTMLDialogElement>(null);
+ const auditContentRef = useRef<HTMLDivElement>(null);
const auditTriggerRef = useRef<HTMLElement | null>(null);
const filterInputRef = useRef<HTMLInputElement>(null);
@@ -636,9 +630,10 @@ export default function TemplatesPage() {
}
const frame = window.requestAnimationFrame(() => {
const dialog = drawerRef.current;
- const scrollContainer = dialog?.firstElementChild;
- if (scrollContainer instanceof HTMLElement) {
- scrollContainer.scrollTop = 0;
+ // The Layout's content region is the scroller; the drawer keeps its
+ // header pinned above it.
+ if (auditContentRef.current) {
+ auditContentRef.current.scrollTop = 0;
}
dialog?.querySelector<HTMLElement>('[data-autofocus]')?.focus();
});
@@ -988,9 +983,29 @@ export default function TemplatesPage() {
: 'Template audit details'
}
hasScrim={false}
- hasCloseButton
width={560}>
- {selectedRow ? <TemplateAuditDetails row={selectedRow} /> : null}
+ {selectedRow ? (
+ <Layout
+ header={
+ <DrawerHeader
+ // The title is the focus target on open and on row switch,
+ // so the changed audit is announced.
+ title={
+ <span tabIndex={-1} data-autofocus>
+ {selectedRow.name}
+ </span>
+ }
+ onOpenChange={setIsAuditPanelOpen}
+ hasDivider
+ />
+ }
+ content={
+ <LayoutContent ref={auditContentRef}>
+ <TemplateAuditDetails row={selectedRow} />
+ </LayoutContent>
+ }
+ />
+ ) : null}
</Drawer>
</>
);
@@ -1007,9 +1022,6 @@ const styles = stylex.create({
backgroundColor: colorVars['--color-neutral'],
borderRadius: radiusVars['--radius-inner'],
},
- drawerHeader: {
- paddingInlineEnd: spacingVars['--spacing-10'],
- },
tabularValue: {
fontVariantNumeric: 'tabular-nums',
},
diff --git a/apps/storybook/stories/Drawer.stories.tsx b/apps/storybook/stories/Drawer.stories.tsx
index 8fe7dcdd09..17b0a63899 100644
--- a/apps/storybook/stories/Drawer.stories.tsx
+++ b/apps/storybook/stories/Drawer.stories.tsx
@@ -5,10 +5,13 @@ import {useState} from 'react';
import {Drawer, DrawerHeader} from '@astryxdesign/lab';
import {Button} from '@astryxdesign/core/Button';
import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+import {Divider} from '@astryxdesign/core/Divider';
import {Heading} from '@astryxdesign/core/Heading';
+import {Layout, LayoutContent, LayoutFooter} from '@astryxdesign/core/Layout';
import {Section} from '@astryxdesign/core/Section';
import {VStack, HStack} from '@astryxdesign/core/Stack';
import {Text} from '@astryxdesign/core/Text';
+import {Theme, defineTheme} from '@astryxdesign/core/theme';
const meta: Meta<typeof Drawer> = {
title: 'Lab/Drawer',
@@ -63,26 +66,32 @@ export const Showcase: Story = {
onOpenChange={setIsOpen}
label="Deployment details"
width={400}>
- <DrawerHeader
- title="web-prod-04"
- subtitle="us-east-1, deployed 12 min ago"
- onOpenChange={setIsOpen}
- hasDivider
+ <Layout
+ header={
+ <DrawerHeader
+ title="web-prod-04"
+ subtitle="us-east-1, deployed 12 min ago"
+ onOpenChange={setIsOpen}
+ hasDivider
+ />
+ }
+ content={
+ <LayoutContent>
+ <VStack gap={4}>
+ <VStack gap={2}>
+ <Text type="label">Status</Text>
+ <Text type="body">
+ Healthy - all 6 instances passing readiness checks.
+ </Text>
+ </VStack>
+ <VStack gap={2}>
+ <Text type="label">Build</Text>
+ <Text type="body">#4821 - main @ 03536f1</Text>
+ </VStack>
+ </VStack>
+ </LayoutContent>
+ }
/>
- <Section padding={4}>
- <VStack gap={4}>
- <VStack gap={2}>
- <Text type="label">Status</Text>
- <Text type="body">
- Healthy - all 6 instances passing readiness checks.
- </Text>
- </VStack>
- <VStack gap={2}>
- <Text type="label">Build</Text>
- <Text type="body">#4821 - main @ 03536f1</Text>
- </VStack>
- </VStack>
- </Section>
</Drawer>
</>
);
@@ -413,13 +422,19 @@ export const Scrim: Story = {
label="Non-modal details"
hasScrim={false}>
{/* No scrim to click, so the header's close button is the visible exit. */}
- <DrawerHeader title="Non-modal" onOpenChange={setOpenWithout} />
- <Section padding={4}>
- <Text type="body">
- No scrim, no focus trap. The page behind keeps working while this
- stays open.
- </Text>
- </Section>
+ <Layout
+ header={
+ <DrawerHeader title="Non-modal" onOpenChange={setOpenWithout} />
+ }
+ content={
+ <LayoutContent>
+ <Text type="body">
+ No scrim, no focus trap. The page behind keeps working while
+ this stays open.
+ </Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
</>
);
@@ -452,35 +467,181 @@ export const Purpose: Story = {
label={`Purpose: ${purpose ?? 'info'}`}
purpose={purpose ?? 'info'}>
{purpose === 'required' ? (
- <>
- <DrawerHeader title="Accept the terms" />
- <Section padding={4}>
- <VStack gap={4}>
+ <Layout
+ header={<DrawerHeader title="Accept the terms" />}
+ content={
+ <LayoutContent>
+ <VStack gap={4}>
+ <Text type="body">
+ Escape and the scrim do nothing. Only this button closes
+ the drawer.
+ </Text>
+ <Button label="Accept" data-autofocus onClick={close} />
+ </VStack>
+ </LayoutContent>
+ }
+ />
+ ) : (
+ <Layout
+ header={
+ <DrawerHeader
+ title={purpose === 'form' ? 'Edit details' : 'Details'}
+ onOpenChange={isOpen => !isOpen && close()}
+ />
+ }
+ content={
+ <LayoutContent>
<Text type="body">
- Escape and the scrim do nothing. Only this button closes the
- drawer.
+ {purpose === 'form'
+ ? 'Escape or the close button closes; a scrim click does not.'
+ : 'Escape, a scrim click, or the close button closes.'}
</Text>
- <Button label="Accept" data-autofocus onClick={close} />
- </VStack>
- </Section>
- </>
- ) : (
- <>
+ </LayoutContent>
+ }
+ />
+ )}
+ </Drawer>
+ </>
+ );
+ },
+};
+
+/**
+ * A Layout as the drawer's child, exactly as inside a Dialog: the Layout
+ * escapes the content area's container padding and redistributes it to its
+ * regions, so the DrawerHeader slot, the scrolling LayoutContent, and the
+ * pinned LayoutFooter share one content line and full-bleed dividers.
+ */
+export const LayoutComposition: Story = {
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <Button label="Open with Layout" onClick={() => setIsOpen(true)} />
+ <Drawer
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Deployment details"
+ width={400}>
+ <Layout
+ header={
<DrawerHeader
- title={purpose === 'form' ? 'Edit details' : 'Details'}
- onOpenChange={isOpen => !isOpen && close()}
+ title="web-prod-04"
+ subtitle="us-east-1, deployed 12 min ago"
+ onOpenChange={setIsOpen}
+ hasDivider
/>
- <Section padding={4}>
- <Text type="body">
- {purpose === 'form'
- ? 'Escape or the close button closes; a scrim click does not.'
- : 'Escape, a scrim click, or the close button closes.'}
- </Text>
- </Section>
- </>
- )}
+ }
+ content={
+ <LayoutContent>
+ <VStack gap={4}>
+ {REGIONS.map(region => (
+ <VStack gap={2} key={region}>
+ <Text type="label">{region}</Text>
+ <Text type="body">
+ Healthy - all instances passing readiness checks.
+ </Text>
+ </VStack>
+ ))}
+ </VStack>
+ </LayoutContent>
+ }
+ footer={
+ <LayoutFooter hasDivider>
+ <HStack gap={2} hAlign="end">
+ <Button
+ label="Cancel"
+ variant="secondary"
+ onClick={() => setIsOpen(false)}
+ />
+ <Button
+ label="Redeploy"
+ variant="primary"
+ onClick={() => setIsOpen(false)}
+ />
+ </HStack>
+ </LayoutFooter>
+ }
+ />
+ </Drawer>
+ </>
+ );
+ },
+};
+
+/**
+ * The `padding` prop insets plain content on the spacing scale, like Dialog.
+ * Without it the inset is `--spacing-4` (16px); this story sets 6 (24px), and
+ * `padding={0}` gives a full-bleed content area. The inset is published as
+ * container geometry: the Divider is a bleed child and stretches edge to edge
+ * through it, and a Section child would escape it the same way.
+ */
+export const ContainerPadding: Story = {
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <Button label="Open padded drawer" onClick={() => setIsOpen(true)} />
+ <Drawer
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Run summary"
+ width={400}
+ padding={6}>
+ <VStack gap={4}>
+ <Heading level={2}>Run summary</Heading>
+ <Text type="body">
+ Plain children sit inside the drawer&apos;s own padding - no
+ Section wrapper needed.
+ </Text>
+ <Divider isFullBleed />
+ <Text type="body">
+ The divider above opts into bleed (isFullBleed): it compensates
+ against the published inset and reaches both panel edges.
+ </Text>
+ <Button label="Close" onClick={() => setIsOpen(false)} />
+ </VStack>
</Drawer>
</>
);
},
};
+
+const paddedDrawerTheme = defineTheme({
+ name: 'drawer-padding-demo',
+ components: {
+ drawer: {
+ base: {padding: '24px'},
+ },
+ },
+});
+
+/**
+ * A theme's `padding` on `drawer` reaches the content area through the
+ * `--astryx-drawer-padding` container tokens (the drawer itself gets no
+ * padding prop here). A lone Section child would escape the themed inset and
+ * apply its own padding, exactly as it would inside a Dialog.
+ */
+export const ThemedPadding: Story = {
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <Theme theme={paddedDrawerTheme}>
+ <Button label="Open themed drawer" onClick={() => setIsOpen(true)} />
+ <Drawer
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Run summary"
+ width={400}>
+ <VStack gap={4}>
+ <Heading level={2}>Run summary</Heading>
+ <Text type="body">
+ The theme sets drawer padding to 24px; this text is inset by it.
+ </Text>
+ <Button label="Close" onClick={() => setIsOpen(false)} />
+ </VStack>
+ </Drawer>
+ </Theme>
+ );
+ },
+};
diff --git a/packages/core/src/Layout/container.stylex.ts b/packages/core/src/Layout/container.stylex.ts
index aa0cf16f2b..011092f0b3 100644
--- a/packages/core/src/Layout/container.stylex.ts
+++ b/packages/core/src/Layout/container.stylex.ts
@@ -4,7 +4,8 @@
* @file container.stylex.ts
* @input Uses @stylexjs/stylex, spacing from theme
* @output StyleX utility for layout container styling
- * @position Layout utility; used by Card, Section, Dialog, and BottomSheet
+ * @position Layout utility; used by Card, Section, Dialog, BottomSheet, and the
+ * Lab Drawer
*
* ## Public API for themes
*
@@ -18,9 +19,10 @@
* --astryx-card-padding-block-end
*
* Read order per level: `var(--astryx-…, <next level>)`, terminating at
- * `--spacing-4`. Same pattern for section and dialog. Bottom-sheet keeps its
- * released unpadded default: its edges terminate at 0px and its Layout insets
- * at no value, so an unthemed sheet changes nothing for descendants.
+ * `--spacing-4`. Same pattern for section, dialog, and the Lab drawer.
+ * Bottom-sheet keeps its released unpadded default: its edges terminate at 0px
+ * and its Layout insets at no value, so an unthemed sheet changes nothing for
+ * descendants.
*
* ```ts
* components: {
@@ -28,6 +30,7 @@
* section: { base: { padding: '12px 20px' } }, // → directional tokens
* dialog: { base: { padding: '16px' } },
* 'bottom-sheet': { base: { padding: '16px' } },
+ * drawer: { base: { padding: '16px' } },
* }
* ```
*
@@ -80,8 +83,8 @@ const baseStyles = stylex.create({
/**
* Component-scoped padding tokens.
*
- * Each container component (card, section, dialog, bottom-sheet) has public CSS custom
- * properties that themes can set. The pipeline emits the `--astryx-*` names,
+ * Each container component (card, section, dialog, bottom-sheet, drawer) has
+ * public CSS custom properties that themes can set. The pipeline emits the `--astryx-*` names,
* which the component reads via `var(--astryx-…, …)`:
*
* --astryx-card-padding (shorthand — all sides)
@@ -157,6 +160,17 @@ const bottomSheetInlineEnd = `var(--astryx-bottom-sheet-padding-inline-end, ${bo
const bottomSheetBlockStart = `var(--astryx-bottom-sheet-padding-block-start, ${bottomSheetShorthand})`;
const bottomSheetBlockEnd = `var(--astryx-bottom-sheet-padding-block-end, ${bottomSheetShorthand})`;
+// Drawer (Lab) padding chains: --astryx-* then the next specificity level,
+// terminating at --spacing-4 like Dialog. Built as chained const strings (no
+// function calls) so StyleX can statically analyze them; see naming.ts for the
+// prefix policy.
+const drawerShorthand = `var(--astryx-drawer-padding, ${SP4})`;
+const drawerInline = `var(--astryx-drawer-padding-inline, ${drawerShorthand})`;
+const drawerInlineStart = `var(--astryx-drawer-padding-inline-start, ${drawerInline})`;
+const drawerInlineEnd = `var(--astryx-drawer-padding-inline-end, ${drawerInline})`;
+const drawerBlockStart = `var(--astryx-drawer-padding-block-start, ${drawerShorthand})`;
+const drawerBlockEnd = `var(--astryx-drawer-padding-block-end, ${drawerShorthand})`;
+
const cardDefaultPaddingStyles = stylex.create({
containerPaddingInlineStart: {
'--container-padding-inline-start': cardInlineStart,
@@ -265,6 +279,33 @@ const bottomSheetDefaultPaddingStyles = stylex.create({
},
});
+const drawerDefaultPaddingStyles = stylex.create({
+ containerPaddingInlineStart: {
+ '--container-padding-inline-start': drawerInlineStart,
+ },
+ containerPaddingInlineEnd: {
+ '--container-padding-inline-end': drawerInlineEnd,
+ },
+ containerPaddingBlockStart: {
+ '--container-padding-block-start': drawerBlockStart,
+ },
+ containerPaddingBlockEnd: {
+ '--container-padding-block-end': drawerBlockEnd,
+ },
+ layoutPaddingOuterX: {
+ '--layout-padding-outer-x': drawerInlineStart,
+ },
+ layoutPaddingOuterY: {
+ '--layout-padding-outer-y': drawerBlockStart,
+ },
+ layoutPaddingInnerX: {
+ '--layout-padding-inner-x': drawerInlineStart,
+ },
+ layoutPaddingInnerY: {
+ '--layout-padding-inner-y': drawerBlockStart,
+ },
+});
+
/**
* Map from component name to its theme default padding styles.
* Each component reads from its own public CSS custom property.
@@ -274,6 +315,7 @@ const themeDefaultStyles = {
section: sectionDefaultPaddingStyles,
dialog: dialogDefaultPaddingStyles,
'bottom-sheet': bottomSheetDefaultPaddingStyles,
+ drawer: drawerDefaultPaddingStyles,
};
export type ContainerComponent = keyof typeof themeDefaultStyles;
@@ -482,7 +524,7 @@ export interface ContainerOptions {
/**
* When set to a component name ('card' | 'section' | 'dialog' |
- * 'bottom-sheet'), internal layout
+ * 'bottom-sheet' | 'drawer'), internal layout
* padding variables cascade from the component-specific public CSS
* container tokens (set by theme pipeline from `padding` shorthand)
* instead of being set to explicit spacing token values.
@@ -490,8 +532,8 @@ export interface ContainerOptions {
* This allows themes to override container padding via component-specific
* public CSS custom properties without touching internal vars.
*
- * Used by Card, Section, Dialog, and BottomSheet when no explicit padding
- * prop is provided.
+ * Used by Card, Section, Dialog, BottomSheet, and the Lab Drawer when no
+ * explicit padding prop is provided.
* @default undefined (uses explicit spacing token values)
*/
useThemeDefault?: ContainerComponent;
diff --git a/packages/core/src/theme/defineTheme.test.ts b/packages/core/src/theme/defineTheme.test.ts
index bd9363ef7b..c7642ba895 100644
--- a/packages/core/src/theme/defineTheme.test.ts
+++ b/packages/core/src/theme/defineTheme.test.ts
@@ -1063,6 +1063,24 @@ describe('container padding mapping', () => {
expect(css).not.toMatch(/(^|[\s{;])padding:\s*24px 20px/);
});
+ it('maps drawer padding to its container tokens', () => {
+ const theme = defineTheme({
+ name: 'test',
+ components: {
+ drawer: {
+ base: {padding: '24px 20px'},
+ },
+ },
+ });
+ const css = generateThemeTestCSS(theme);
+ expect(css).toContain('--astryx-drawer-padding-inline: 20px');
+ expect(css).toContain('--astryx-drawer-padding-block-start: 24px');
+ expect(css).toContain('--astryx-drawer-padding-block-end: 24px');
+ // The panel is the overlay boundary; the value reaches the content area
+ // through the token, never as padding on the panel itself.
+ expect(css).not.toMatch(/(^|[\s{;])padding:\s*24px 20px/);
+ });
+
it('does NOT map padding on non-container components', () => {
const theme = defineTheme({
name: 'test',
diff --git a/packages/core/src/theme/derivedVarRegistry.test.ts b/packages/core/src/theme/derivedVarRegistry.test.ts
index c9848dfe02..c55ed55f6e 100644
--- a/packages/core/src/theme/derivedVarRegistry.test.ts
+++ b/packages/core/src/theme/derivedVarRegistry.test.ts
@@ -223,6 +223,10 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
Chat: 'chat',
ContextMenu: 'context-menu',
Dialog: 'dialog',
+ // The Drawer doc file lives in packages/lab/src/Drawer, outside this
+ // package's scan; the mapping keeps the registry orphan check honest and
+ // defineTheme.test.ts pins the expansion.
+ Drawer: 'drawer',
DropdownMenu: 'dropdown-menu',
Field: 'field',
HoverCard: 'hover-card',
diff --git a/packages/core/src/theme/derivedVarRegistry.ts b/packages/core/src/theme/derivedVarRegistry.ts
index b6e9841a33..77e554c972 100644
--- a/packages/core/src/theme/derivedVarRegistry.ts
+++ b/packages/core/src/theme/derivedVarRegistry.ts
@@ -59,6 +59,10 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
{property: 'borderRadius', vars: ['--_dialog-radius']},
{property: 'padding', expand: 'container'},
],
+ // Drawer lives in @astryxdesign/lab; its doc source of truth is
+ // packages/lab/src/Drawer/Drawer.doc.mjs, outside this package's consistency
+ // scan. defineTheme.test.ts pins the expansion instead.
+ drawer: [{property: 'padding', expand: 'container'}],
'context-menu': [
{property: 'borderRadius', vars: ['--_dropdown-menu-radius']},
{property: 'padding', vars: ['--_dropdown-menu-padding']},
diff --git a/packages/lab/blocks/DrawerFullWidthMobile.doc.mjs b/packages/lab/blocks/DrawerFullWidthMobile.doc.mjs
index 8af96825b5..613f9f277e 100644
--- a/packages/lab/blocks/DrawerFullWidthMobile.doc.mjs
+++ b/packages/lab/blocks/DrawerFullWidthMobile.doc.mjs
@@ -10,5 +10,12 @@ export default {
exampleFor: 'Drawer',
isReady: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Drawer', 'Button', 'Section', 'DrawerHeader', 'Text'],
+ componentsUsed: [
+ 'Drawer',
+ 'Button',
+ 'Layout',
+ 'LayoutContent',
+ 'DrawerHeader',
+ 'Text',
+ ],
};
diff --git a/packages/lab/blocks/DrawerFullWidthMobile.tsx b/packages/lab/blocks/DrawerFullWidthMobile.tsx
index ec073e9ff5..043e7a5559 100644
--- a/packages/lab/blocks/DrawerFullWidthMobile.tsx
+++ b/packages/lab/blocks/DrawerFullWidthMobile.tsx
@@ -11,7 +11,7 @@
import {useState} from 'react';
import {Drawer, DrawerHeader} from '@astryxdesign/lab';
import {Button} from '@astryxdesign/core/Button';
-import {Section} from '@astryxdesign/core/Section';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';
export default function DrawerFullWidthMobile() {
@@ -26,12 +26,16 @@ export default function DrawerFullWidthMobile() {
label="Wide panel"
width={560}
isFullWidthOnMobile>
- <DrawerHeader title="Wide panel" onOpenChange={setIsOpen} />
- <Section padding={4}>
- <Text type="body">
- A wide panel on desktop, the full viewport width on mobile.
- </Text>
- </Section>
+ <Layout
+ header={<DrawerHeader title="Wide panel" onOpenChange={setIsOpen} />}
+ content={
+ <LayoutContent>
+ <Text type="body">
+ A wide panel on desktop, the full viewport width on mobile.
+ </Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
</>
);
diff --git a/packages/lab/blocks/DrawerMobileReveal.doc.mjs b/packages/lab/blocks/DrawerMobileReveal.doc.mjs
index 008a28c08a..3f2a7573ec 100644
--- a/packages/lab/blocks/DrawerMobileReveal.doc.mjs
+++ b/packages/lab/blocks/DrawerMobileReveal.doc.mjs
@@ -10,5 +10,12 @@ export default {
exampleFor: 'Drawer',
isReady: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Drawer', 'Button', 'Section', 'DrawerHeader', 'Text'],
+ componentsUsed: [
+ 'Drawer',
+ 'Button',
+ 'Layout',
+ 'LayoutContent',
+ 'DrawerHeader',
+ 'Text',
+ ],
};
diff --git a/packages/lab/blocks/DrawerMobileReveal.tsx b/packages/lab/blocks/DrawerMobileReveal.tsx
index 7f004e303f..fd702c013b 100644
--- a/packages/lab/blocks/DrawerMobileReveal.tsx
+++ b/packages/lab/blocks/DrawerMobileReveal.tsx
@@ -11,7 +11,7 @@
import {useState} from 'react';
import {Drawer, DrawerHeader} from '@astryxdesign/lab';
import {Button} from '@astryxdesign/core/Button';
-import {Section} from '@astryxdesign/core/Section';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';
export default function DrawerMobileReveal() {
@@ -25,12 +25,18 @@ export default function DrawerMobileReveal() {
onOpenChange={setIsOpen}
label="Mobile reveal"
width={360}>
- <DrawerHeader title="Mobile reveal" onOpenChange={setIsOpen} />
- <Section padding={4}>
- <Text type="body">
- The page remains visible beside the drawer on mobile.
- </Text>
- </Section>
+ <Layout
+ header={
+ <DrawerHeader title="Mobile reveal" onOpenChange={setIsOpen} />
+ }
+ content={
+ <LayoutContent>
+ <Text type="body">
+ The page remains visible beside the drawer on mobile.
+ </Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
</>
);
diff --git a/packages/lab/blocks/DrawerScrim.doc.mjs b/packages/lab/blocks/DrawerScrim.doc.mjs
index 81e20f931d..e54fb9f659 100644
--- a/packages/lab/blocks/DrawerScrim.doc.mjs
+++ b/packages/lab/blocks/DrawerScrim.doc.mjs
@@ -13,7 +13,8 @@ export default {
componentsUsed: [
'Drawer',
'Button',
- 'Section',
+ 'Layout',
+ 'LayoutContent',
'HStack',
'DrawerHeader',
'Text',
diff --git a/packages/lab/blocks/DrawerScrim.tsx b/packages/lab/blocks/DrawerScrim.tsx
index 338621ed47..2b9fd3f9c8 100644
--- a/packages/lab/blocks/DrawerScrim.tsx
+++ b/packages/lab/blocks/DrawerScrim.tsx
@@ -11,7 +11,7 @@
import {useState} from 'react';
import {Drawer, DrawerHeader} from '@astryxdesign/lab';
import {Button} from '@astryxdesign/core/Button';
-import {Section} from '@astryxdesign/core/Section';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
import {HStack} from '@astryxdesign/core/Stack';
import {Text} from '@astryxdesign/core/Text';
@@ -32,24 +32,36 @@ export default function DrawerScrim() {
isOpen={openModal}
onOpenChange={setOpenModal}
label="Edit details">
- <DrawerHeader title="Edit details" onOpenChange={setOpenModal} />
- <Section padding={4}>
- <Text type="body">
- The scrim blocks the page behind this modal drawer.
- </Text>
- </Section>
+ <Layout
+ header={
+ <DrawerHeader title="Edit details" onOpenChange={setOpenModal} />
+ }
+ content={
+ <LayoutContent>
+ <Text type="body">
+ The scrim blocks the page behind this modal drawer.
+ </Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
<Drawer
isOpen={openPanel}
onOpenChange={setOpenPanel}
label="Inspector"
hasScrim={false}>
- <DrawerHeader title="Inspector" onOpenChange={setOpenPanel} />
- <Section padding={4}>
- <Text type="body">
- The page behind this non-modal drawer stays interactive.
- </Text>
- </Section>
+ <Layout
+ header={
+ <DrawerHeader title="Inspector" onOpenChange={setOpenPanel} />
+ }
+ content={
+ <LayoutContent>
+ <Text type="body">
+ The page behind this non-modal drawer stays interactive.
+ </Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
</>
);
diff --git a/packages/lab/blocks/DrawerShowcase.doc.mjs b/packages/lab/blocks/DrawerShowcase.doc.mjs
index 102054d941..7ac637de68 100644
--- a/packages/lab/blocks/DrawerShowcase.doc.mjs
+++ b/packages/lab/blocks/DrawerShowcase.doc.mjs
@@ -11,5 +11,12 @@ export default {
isReady: true,
isShowcase: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Drawer', 'Button', 'Section', 'DrawerHeader', 'Text'],
+ componentsUsed: [
+ 'Drawer',
+ 'Button',
+ 'Layout',
+ 'LayoutContent',
+ 'DrawerHeader',
+ 'Text',
+ ],
};
diff --git a/packages/lab/blocks/DrawerShowcase.tsx b/packages/lab/blocks/DrawerShowcase.tsx
index 3a87d8b744..5189045d00 100644
--- a/packages/lab/blocks/DrawerShowcase.tsx
+++ b/packages/lab/blocks/DrawerShowcase.tsx
@@ -11,7 +11,7 @@
import {useState} from 'react';
import {Drawer, DrawerHeader} from '@astryxdesign/lab';
import {Button} from '@astryxdesign/core/Button';
-import {Section} from '@astryxdesign/core/Section';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';
export default function DrawerShowcase() {
@@ -25,12 +25,16 @@ export default function DrawerShowcase() {
onOpenChange={setIsOpen}
label="Details"
width={360}>
- <DrawerHeader title="Details" onOpenChange={setIsOpen} />
- <Section padding={4}>
- <Text type="body">
- Close with Escape, the scrim, or the close button.
- </Text>
- </Section>
+ <Layout
+ header={<DrawerHeader title="Details" onOpenChange={setIsOpen} />}
+ content={
+ <LayoutContent>
+ <Text type="body">
+ Close with Escape, the scrim, or the close button.
+ </Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
</>
);
diff --git a/packages/lab/blocks/DrawerStart.doc.mjs b/packages/lab/blocks/DrawerStart.doc.mjs
index be20dcd7e5..abc878553b 100644
--- a/packages/lab/blocks/DrawerStart.doc.mjs
+++ b/packages/lab/blocks/DrawerStart.doc.mjs
@@ -10,5 +10,12 @@ export default {
exampleFor: 'Drawer',
isReady: true,
aspectRatio: 16 / 9,
- componentsUsed: ['Drawer', 'Button', 'Section', 'DrawerHeader', 'Text'],
+ componentsUsed: [
+ 'Drawer',
+ 'Button',
+ 'Layout',
+ 'LayoutContent',
+ 'DrawerHeader',
+ 'Text',
+ ],
};
diff --git a/packages/lab/blocks/DrawerStart.tsx b/packages/lab/blocks/DrawerStart.tsx
index dcef9ac986..60833fd45e 100644
--- a/packages/lab/blocks/DrawerStart.tsx
+++ b/packages/lab/blocks/DrawerStart.tsx
@@ -11,7 +11,7 @@
import {useState} from 'react';
import {Drawer, DrawerHeader} from '@astryxdesign/lab';
import {Button} from '@astryxdesign/core/Button';
-import {Section} from '@astryxdesign/core/Section';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
import {Text} from '@astryxdesign/core/Text';
export default function DrawerStart() {
@@ -25,12 +25,16 @@ export default function DrawerStart() {
onOpenChange={setIsOpen}
label="Navigation"
side="start">
- <DrawerHeader title="Navigation" onOpenChange={setIsOpen} />
- <Section padding={4}>
- <Text type="body">
- The start edge follows the page's writing direction.
- </Text>
- </Section>
+ <Layout
+ header={<DrawerHeader title="Navigation" onOpenChange={setIsOpen} />}
+ content={
+ <LayoutContent>
+ <Text type="body">
+ The start edge follows the page's writing direction.
+ </Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
</>
);
diff --git a/packages/lab/blocks/DrawerWidths.doc.mjs b/packages/lab/blocks/DrawerWidths.doc.mjs
index f083c66cb2..b527c6e4a9 100644
--- a/packages/lab/blocks/DrawerWidths.doc.mjs
+++ b/packages/lab/blocks/DrawerWidths.doc.mjs
@@ -13,7 +13,8 @@ export default {
componentsUsed: [
'Drawer',
'Button',
- 'Section',
+ 'Layout',
+ 'LayoutContent',
'HStack',
'DrawerHeader',
'Text',
diff --git a/packages/lab/blocks/DrawerWidths.tsx b/packages/lab/blocks/DrawerWidths.tsx
index b41c524b6c..7bfcef7182 100644
--- a/packages/lab/blocks/DrawerWidths.tsx
+++ b/packages/lab/blocks/DrawerWidths.tsx
@@ -11,7 +11,7 @@
import {useState} from 'react';
import {Drawer, DrawerHeader} from '@astryxdesign/lab';
import {Button} from '@astryxdesign/core/Button';
-import {Section} from '@astryxdesign/core/Section';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
import {HStack} from '@astryxdesign/core/Stack';
import {Text} from '@astryxdesign/core/Text';
@@ -36,12 +36,18 @@ export default function DrawerWidths() {
onOpenChange={setIsOpen}
label="Width budget"
width={width}>
- <DrawerHeader title="Width budget" onOpenChange={setIsOpen} />
- <Section padding={4}>
- <Text type="body">
- Width: {typeof width === 'number' ? `${width}px` : width}
- </Text>
- </Section>
+ <Layout
+ header={
+ <DrawerHeader title="Width budget" onOpenChange={setIsOpen} />
+ }
+ content={
+ <LayoutContent>
+ <Text type="body">
+ Width: {typeof width === 'number' ? `${width}px` : width}
+ </Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
</>
);
diff --git a/packages/lab/src/Drawer/Drawer.doc.mjs b/packages/lab/src/Drawer/Drawer.doc.mjs
index 9bd4d62fda..ee69a8ad4b 100644
--- a/packages/lab/src/Drawer/Drawer.doc.mjs
+++ b/packages/lab/src/Drawer/Drawer.doc.mjs
@@ -19,13 +19,13 @@ const anatomy = [
name: 'Content area',
required: true,
description:
- 'Full-bleed scrollable region that receives children; compose your own header, body, and footer inside it.',
+ 'Scrollable container that receives children; compose the header, body, and footer inside it with a Layout, as in Dialog. Inset by --spacing-4 (16px) by default; the padding prop or a theme sets a different container inset.',
},
{
name: 'Header',
required: false,
description:
- 'DrawerHeader, composed first in the content area: a title row with optional subtitle and start/end content. Pass it onOpenChange to show a close button, as with DialogHeader.',
+ 'DrawerHeader, composed in a Layout header slot as DialogHeader is in Dialog: a title row with optional subtitle and start/end content. Pass it onOpenChange to show a close button, as with DialogHeader.',
},
{
name: 'Scrim',
@@ -82,6 +82,7 @@ export const docs = {
},
},
theming: {
+ container: true,
targets: [
{className: 'astryx-drawer', visualProps: ['side']},
{className: 'astryx-drawer-header'},
@@ -90,9 +91,10 @@ export const docs = {
{className: 'astryx-drawer-header-end-content'},
{className: 'astryx-drawer-header-close-icon'},
],
+ derived: [{property: 'padding', expand: 'container'}],
},
description:
- 'Side panel that floats above page content, using the native <dialog> element. Slides in from the inline start or end edge; full height, never reflows the layout underneath.',
+ "Side panel that floats above page content, using the native <dialog> element. Slides in from the inline start or end edge; full height, never reflows the layout underneath. Like Dialog, it is a container: set padding (or a theme's drawer padding) and a lone Section child or bleed children such as Table and Divider align against that inset. The default inset is --spacing-4 (16px), as in Dialog.",
props: [
{
name: 'isOpen',
@@ -157,11 +159,17 @@ export const docs = {
'Configures implicit dismissal, matching Dialog. info: Escape and a scrim click close. form: Escape closes, a scrim click does not. required: neither closes (Escape is consumed) and a modal drawer is exposed as an alertdialog, so give its content a way out. A non-modal drawer has no scrim, so form and info behave the same.',
default: "'info'",
},
+ {
+ name: 'padding',
+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+ description:
+ "Internal padding of the drawer content using the spacing scale, matching Dialog. When omitted, uses the theme default for drawers: --spacing-4 (16px) unless the theme sets padding on drawer. Pass 0 for a full-bleed content area. A lone Section child escapes the padding, bleed children such as Table and Divider compensate against it, and a Layout picks it up for its regions. The content area's block-end edge adds the home-indicator safe area on top in every mode.",
+ },
],
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 (unless purpose is required) 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 the header, body, and footer. Start with DrawerHeader, a title row that shows a close button when you pass it onOpenChange, like DialogHeader; follow it with the body, for example Section padding={4}. Drawer renders no close button of its own, so give every drawer a visible way to close, especially a non-modal one, which has no scrim to click. 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), and the scrim is the panel\'s native ::backdrop. DrawerHeader exposes astryx-drawer-header targets for its row, slots, and close icon.',
+ '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 (unless purpose is required) 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\nLike Dialog, the drawer is a container: its content area is inset by --spacing-4 (16px) by default, by the padding prop, or by a theme\'s padding on drawer. Compose the header, body, and footer the way Dialog does, with a Layout: DrawerHeader in the header slot (it shows a close button when you pass it onOpenChange, like DialogHeader), the body in LayoutContent, and actions in LayoutFooter. The Layout redistributes the inset to those regions so they line up on one content line, and the header is not inset twice. A lone Section child also escapes the inset. Drawer renders no close button of its own, so give every drawer a visible way to close, especially a non-modal one, which has no scrim to click. 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), and the scrim is the panel\'s native ::backdrop. DrawerHeader exposes astryx-drawer-header targets for its row, slots, and close icon.',
bestPractices: [
{
guidance: true,
@@ -227,10 +235,14 @@ export const docs = {
onOpenChange={setIsOpen}
label="Details"
width={360}>
- <DrawerHeader title="Details" onOpenChange={setIsOpen} />
- <Section padding={4}>
- <Text type="body">Close with Escape, the scrim, or the close button.</Text>
- </Section>
+ <Layout
+ header={<DrawerHeader title="Details" onOpenChange={setIsOpen} />}
+ content={
+ <LayoutContent>
+ <Text type="body">Close with Escape, the scrim, or the close button.</Text>
+ </LayoutContent>
+ }
+ />
</Drawer>
</>
// Modal by default: the scrim dims the page and focus is trapped. Escape, a
@@ -305,8 +317,10 @@ const [openPanel, setOpenPanel] = useState(false);
onOpenChange={setOpenPanel}
label="Details"
hasScrim={false}>
- <DrawerHeader title="Details" onOpenChange={setOpenPanel} />
- <DetailsPanel />
+ <Layout
+ header={<DrawerHeader title="Details" onOpenChange={setOpenPanel} />}
+ content={<LayoutContent><DetailsPanel /></LayoutContent>}
+ />
</Drawer>
</>`,
},
@@ -327,13 +341,13 @@ export const docsZh = {
name: 'Content area',
required: true,
description:
- '不带内边距的可滚动区域,承载 children;页眉、正文、页脚在其中自行组合。',
+ '承载 children 的可滚动容器;像 Dialog 一样在其中用 Layout 组合页眉、正文和页脚。默认带有 --spacing-4(16px)的内边距;padding 属性或主题的 drawer padding 可设置其他容器内边距。',
},
{
name: 'Header',
required: false,
description:
- 'DrawerHeader,放在内容区域最前面:包含标题,以及可选的副标题和首尾内容。传入 onOpenChange 即显示关闭按钮,与 DialogHeader 相同。',
+ 'DrawerHeader,像 Dialog 中的 DialogHeader 一样放在 Layout 的 header 插槽:包含标题,以及可选的副标题和首尾内容。传入 onOpenChange 即显示关闭按钮,与 DialogHeader 相同。',
},
{
name: 'Scrim',
@@ -343,7 +357,7 @@ export const docsZh = {
},
],
description:
- '浮在页面内容之上的侧边面板,用于检查器和详情视图——"点击表格行查看详情"的模式。与停靠面板不同,它覆盖在布局之上,不会挤压页面。桌面端按 width 设定宽度,宽度小于 640px 时保留 56px 的底层页面,并且不超过 width 上限。按 Escape 关闭抽屉(purpose 为 required 时除外),焦点返回到打开它的元素。滑入/滑出动画遵循 prefers-reduced-motion。堆叠约定:同级抽屉后开的在上层,Escape 只关闭最上层的,关闭顺序由内向外——请以同级方式渲染,切勿嵌套。\n\n内容区域不带内边距:页眉、正文、页脚由你自行组合。先放 DrawerHeader——传入 onOpenChange 时显示关闭按钮的标题行,与 DialogHeader 相同;再放正文,例如 Section padding={4}。Drawer 本身不渲染关闭按钮,所以每个抽屉都要提供可见的关闭方式,非模态抽屉尤其如此,因为它没有可点击的遮罩。在打开时应获得焦点的控件上加 data-autofocus。\n\n如何选择:居中的决定或短表单用 Dialog;保持页面可见的全高侧边详情用 Drawer;触屏上的块轴面板用 BottomSheet;内容应当把页面挤开重排时用停靠面板(布局分栏),而不是浮层。\n\n主题化:面板是唯一的稳定目标(astryx-drawer,data-side 反映 side 值),遮罩是面板的原生 ::backdrop。DrawerHeader 为其标题行、插槽和关闭图标提供 astryx-drawer-header 系列目标。',
+ '浮在页面内容之上的侧边面板,用于检查器和详情视图——"点击表格行查看详情"的模式。与停靠面板不同,它覆盖在布局之上,不会挤压页面。桌面端按 width 设定宽度,宽度小于 640px 时保留 56px 的底层页面,并且不超过 width 上限。按 Escape 关闭抽屉(purpose 为 required 时除外),焦点返回到打开它的元素。滑入/滑出动画遵循 prefers-reduced-motion。堆叠约定:同级抽屉后开的在上层,Escape 只关闭最上层的,关闭顺序由内向外——请以同级方式渲染,切勿嵌套。\n\n与 Dialog 一样,Drawer 是一个容器:内容区域默认带有 --spacing-4(16px)的内边距,也可以由 padding 属性或主题中 drawer 的 padding 设置。像 Dialog 一样用 Layout 组合页眉、正文和页脚:DrawerHeader 放在 header 插槽(传入 onOpenChange 时显示关闭按钮,与 DialogHeader 相同),正文放在 LayoutContent,操作放在 LayoutFooter。Layout 会把内边距分配给这些区域,使它们对齐在同一条内容线上,页眉也不会被重复缩进。作为唯一子元素的 Section 同样会越出该内边距。Drawer 本身不渲染关闭按钮,所以每个抽屉都要提供可见的关闭方式,非模态抽屉尤其如此,因为它没有可点击的遮罩。在打开时应获得焦点的控件上加 data-autofocus。\n\n如何选择:居中的决定或短表单用 Dialog;保持页面可见的全高侧边详情用 Drawer;触屏上的块轴面板用 BottomSheet;内容应当把页面挤开重排时用停靠面板(布局分栏),而不是浮层。\n\n主题化:面板是唯一的稳定目标(astryx-drawer,data-side 反映 side 值),遮罩是面板的原生 ::backdrop。DrawerHeader 为其标题行、插槽和关闭图标提供 astryx-drawer-header 系列目标。',
bestPractices: [
{
guidance: true,
@@ -401,11 +415,11 @@ export const docsZh = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
description:
- 'side panel floating over content (native <dialog>): start/end edge, full height',
+ 'side panel floating over content (native <dialog>): start/end edge, full height, Dialog-like container padding (--spacing-4 by default; padding prop or theme drawer padding)',
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 (not when purpose=required); focus restores to the opener. Siblings stack last-opened on top; never nest. Slide animation respects prefers-reduced-motion. Compose header/body/footer in the full-bleed scroll area: DrawerHeader first (close button only when given onOpenChange, like DialogHeader), then the body (e.g. Section padding={4}); no built-in close button, so every drawer needs a visible exit; data-autofocus picks the focus target. purpose matches Dialog: info = Escape + scrim click, form = Escape only, required = neither (modal → alertdialog). 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; DrawerHeader has astryx-drawer-header targets.',
+ "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 (not when purpose=required); focus restores to the opener. Siblings stack last-opened on top; never nest. Slide animation respects prefers-reduced-motion. Dialog-like container: content area inset = --spacing-4 (16px) by default, or the padding prop / a theme's drawer padding (padding={0} = full bleed). Compose like Dialog: Layout with DrawerHeader in the header slot (close button only when given onOpenChange), LayoutContent, LayoutFooter; Layout redistributes the inset so regions line up and the header is not inset twice; a lone Section escapes the inset. No built-in close button, so every drawer needs a visible exit; data-autofocus picks the focus target. purpose matches Dialog: info = Escape + scrim click, form = Escape only, required = neither (modal → alertdialog). 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; DrawerHeader has astryx-drawer-header targets.",
bestPractices: [
{
guidance: true,
diff --git a/packages/lab/src/Drawer/Drawer.spec.md b/packages/lab/src/Drawer/Drawer.spec.md
index 713741e351..0a352547d0 100644
--- a/packages/lab/src/Drawer/Drawer.spec.md
+++ b/packages/lab/src/Drawer/Drawer.spec.md
@@ -26,6 +26,7 @@ design_specs: []
architecture:
[
architecture:component-theming-surface,
+ architecture:container-padding,
architecture:layer-runtime,
architecture:public-component-api,
architecture:react-component-runtime,
@@ -40,13 +41,13 @@ system_specs: [spec:AST-027/DEC-3]
| Area | Contract |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Current Lab surface | Public-API change aligning Drawer with Dialog (DEC-1). At this commit, the experimental `@astryxdesign/lab` root exports `Drawer`, `DrawerProps`, `DrawerHeader`, and `DrawerHeaderProps`. `DrawerProps` extends `BaseProps<HTMLDialogElement>`, separately declares `ref`, requires `isOpen`, `onOpenChange`, `label`, and `children`, accepts `purpose` (`required`, `form`, or `info`; default `info`), and no longer accepts `hasCloseButton`. This records current reachability, not a stable compatibility promise. |
+| Current Lab surface | Public-API change aligning Drawer with Dialog (DEC-1). At this commit, the experimental `@astryxdesign/lab` root exports `Drawer`, `DrawerProps`, `DrawerHeader`, and `DrawerHeaderProps`. `DrawerProps` extends `BaseProps<HTMLDialogElement>`, separately declares `ref`, requires `isOpen`, `onOpenChange`, `label`, and `children`, accepts `purpose` (`required`, `form`, or `info`; default `info`), accepts an optional `padding` spacing step (FR16), and no longer accepts `hasCloseButton`. This records current reachability, not a stable compatibility promise. |
| Behavior | Drawer-owned visibility is controlled by the caller for a viewport-relative, full-height logical-side overlay. `hasScrim` at native open selects `showModal()` or a manual Popover API host; changing it while open is unsupported. The shared layer dismissal stack gates Escape and platform close for the full rendered lifetime, and `purpose` decides, as in Dialog, whether Escape, platform close, and scrim click request close. Drawer renders no close control of its own; `DrawerHeader` renders one only when given `onOpenChange`. The browser top layer owns paint order in both presentations, exit renders current children, and completed close returns focus to the element focused at open. |
| End-user impact | Drawers no longer paint a floating top-trailing close button; a close button appears in a `DrawerHeader` title row where the caller composes one. `form` drawers ignore scrim clicks, and `required` drawers ignore Escape, platform close, and scrim clicks; a modal `required` drawer is announced as an alert dialog. Layer behavior (shared topmost/IME Escape, top-layer paint order, one dismissal per request, focus return) is unchanged. |
-| Builder impact | Remove `hasCloseButton`. For a visible close action, compose `<DrawerHeader title onOpenChange>` first in the content, as with `DialogHeader`; callers that passed `hasCloseButton={false}` need no change beyond removing the prop. Set `purpose` where Dialog would. State and content remain caller-owned; Drawer renders the caller's current children during exit. Sibling composition remains current consumer guidance, and a consumer `onKeyDown` that prevents default still cancels Escape dismissal. |
+| Builder impact | Remove `hasCloseButton`. For a visible close action, compose `<DrawerHeader title onOpenChange>` in a `Layout` header slot, as `DialogHeader` is composed in Dialog; set `padding={0}` for a full-bleed drawer, since the default inset is now `--spacing-4`; callers that passed `hasCloseButton={false}` need no change beyond removing the prop. Set `purpose` where Dialog would. State and content remain caller-owned; Drawer renders the caller's current children during exit. Sibling composition remains current consumer guidance, and a consumer `onKeyDown` that prevents default still cancels Escape dismissal. |
| Compatibility/readiness | Breaking Lab API change: removes `hasCloseButton` and the built-in close button, adds `purpose` and `DrawerHeader`. Drawer remains experimental in Lab, this record remains `draft`, and its candidate statements require approval. FR13–FR14 record shared-family and top-layer conformance; FR7 and FR15 record the Dialog alignment. |
| Review checks | Reject regional, docked, or block-axis models; claims that modality and scrim are currently independent; reintroduction of a Drawer-local Escape registry, a page-level z-index band, or a Drawer-owned close button; a dismissal policy that diverges from Dialog's `purpose`; claims that mixed-presentation or nested stacking is guaranteed beyond the shared stack's contract; or claims of stable API/theming compatibility. |
-| Record context | `component:Drawer` FR1–FR15 and AR1–AR6 are draft candidate statements. Linked records govern only within their own declared authority and scope. |
+| Record context | `component:Drawer` FR1–FR16 and AR1–AR6 are draft candidate statements. Linked records govern only within their own declared authority and scope. |
This table summarizes the draft body below; it does not change this record's declared authority.
@@ -69,12 +70,18 @@ regional, pane-scoped, or container-targeted Drawer model.
- Compatibility class: breaking change inside Lab. `hasCloseButton` and the
built-in close button are removed; `purpose` and `DrawerHeader` are added. Root
element, styling inputs, and controlled ownership remain unchanged.
+- Container padding (FR16, DEC-2): a new `padding` prop, and a theme's
+ `padding` on `drawer` insets the Content area through container tokens. With
+ neither set the inset is `--spacing-4`, as in Dialog, so a drawer without an
+ explicit `padding` is now padded; `padding={0}` keeps a full-bleed Content
+ area. The block-end safe-area inset is kept in every mode.
- Controlled/uncontrolled behavior: unchanged for Drawer-owned paths; callers
provide `isOpen`, while direct native mutation through the public dialog ref is
outside that guarantee.
- Migration decision: Drawer is unreleased Lab, so no codemod. Callers remove
- `hasCloseButton` and compose `DrawerHeader` with `onOpenChange` where they
- relied on the built-in button.
+ `hasCloseButton`, compose `DrawerHeader` with `onOpenChange` in a `Layout`
+ header slot where they relied on the built-in button, and pass `padding={0}`
+ where they need a full-bleed Content area.
Consumer migration instructions belong in consumer docs and release notes.
@@ -89,6 +96,9 @@ Consumer migration instructions belong in consumer docs and release notes.
- Drawer-local focus entry/return, the `purpose` dismissal policy, uncanceled
backdrop-click handling, and retention of its host through controlled exit
while rendering current caller-owned children.
+- The Content area's container padding, published per
+ `architecture:container-padding`; the root dialog remains the overlay
+ boundary owner.
- `DrawerHeader`: a title row with optional subtitle and start/end content, and a
close action rendered only when `onOpenChange` is passed.
- Registering the layer with the shared dismissal stack for its rendered
@@ -112,16 +122,17 @@ Consumer migration instructions belong in consumer docs and release notes.
Consumer prop syntax and examples remain in `Drawer.doc.mjs`.
-| Concept | Closed values or states | Meaning | Availability by state | Default | Owner | Stability | Invalid-value behavior |
-| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------- | ------------------ | ----------------------------------------------------- | ----------------------------------------------------- |
-| visibility | open, closed | whether caller-controlled Drawer presentation is requested | all presentations | caller-controlled | `component:Drawer` | experimental Lab contract | required controlled value |
-| logical edge | inline start, inline end | viewport edge from which the panel enters and exits | open and exiting | inline end | `component:Drawer` | experimental Lab contract | closed type rejects other values |
-| presentation | modal with scrim, non-modal without scrim | native host mode and associated document semantics | chosen when the native host opens; live changes are unsupported | modal with scrim | `component:Drawer` | experimental Lab contract | one current boolean selects the initial mode |
-| inline-size budget | pixel number or valid CSS length | desktop inline size and reveal-mode mobile cap | desktop and mobile page-reveal mode | `400px` | `component:Drawer` | experimental Lab contract | invalid CSS lengths are unsupported |
-| mobile coverage | page reveal, full viewport | whether narrow viewports retain a visible page strip | viewports at or below the mobile boundary | 56px page reveal | `component:Drawer` | experimental Lab contract | closed boolean |
-| dismissal purpose | info, form, required | which implicit requests close: `info` allows Escape, platform close, and scrim click; `form` allows Escape and platform close; `required` allows none | all presentations; scrim click applies to modal only | info | `component:Drawer` | experimental Lab contract matching `component:Dialog` | closed type rejects other values |
-| header close action | rendered, absent | whether `DrawerHeader` renders its close button | wherever `DrawerHeader` is composed | absent unless `onOpenChange` is passed | `component:Drawer` | experimental Lab contract | an omitted callback renders no button |
-| sibling order | earlier opened, later opened, exiting, closed | shared-stack Escape eligibility and browser top-layer paint order | sibling Drawers in either presentation | later opened is topmost | `component:Drawer` | experimental Lab contract | nested composition is outside the documented contract |
+| Concept | Closed values or states | Meaning | Availability by state | Default | Owner | Stability | Invalid-value behavior |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------- | ------------------ | ----------------------------------------------------- | ----------------------------------------------------- |
+| visibility | open, closed | whether caller-controlled Drawer presentation is requested | all presentations | caller-controlled | `component:Drawer` | experimental Lab contract | required controlled value |
+| logical edge | inline start, inline end | viewport edge from which the panel enters and exits | open and exiting | inline end | `component:Drawer` | experimental Lab contract | closed type rejects other values |
+| presentation | modal with scrim, non-modal without scrim | native host mode and associated document semantics | chosen when the native host opens; live changes are unsupported | modal with scrim | `component:Drawer` | experimental Lab contract | one current boolean selects the initial mode |
+| inline-size budget | pixel number or valid CSS length | desktop inline size and reveal-mode mobile cap | desktop and mobile page-reveal mode | `400px` | `component:Drawer` | experimental Lab contract | invalid CSS lengths are unsupported |
+| mobile coverage | page reveal, full viewport | whether narrow viewports retain a visible page strip | viewports at or below the mobile boundary | 56px page reveal | `component:Drawer` | experimental Lab contract | closed boolean |
+| dismissal purpose | info, form, required | which implicit requests close: `info` allows Escape, platform close, and scrim click; `form` allows Escape and platform close; `required` allows none | all presentations; scrim click applies to modal only | info | `component:Drawer` | experimental Lab contract matching `component:Dialog` | closed type rejects other values |
+| header close action | rendered, absent | whether `DrawerHeader` renders its close button | wherever `DrawerHeader` is composed | absent unless `onOpenChange` is passed | `component:Drawer` | experimental Lab contract | an omitted callback renders no button |
+| content inset | spacing step, theme `drawer` padding, or the default | container padding of the scrolling Content area, published to descendants per `architecture:container-padding` | all presentations | `--spacing-4`, as in Dialog | `component:Drawer` | experimental Lab contract matching `component:Dialog` | closed numeric type rejects other values |
+| sibling order | earlier opened, later opened, exiting, closed | shared-stack Escape eligibility and browser top-layer paint order | sibling Drawers in either presentation | later opened is topmost | `component:Drawer` | experimental Lab contract | nested composition is outside the documented contract |
## Behavioral and layout contract
@@ -142,6 +153,7 @@ Consumer prop syntax and examples remain in `Drawer.doc.mjs`.
| FR13 | Drawer MUST join the shared dismissal stack for its full rendered lifetime, provide logical depth to descendant layers, route platform close through the same topmost/IME decision, and preserve consumer `preventDefault()` ownership. | Shared family contract and focused tests | Verified current conformance |
| FR14 | Non-modal Drawer MUST use a manual Popover API host so cross-surface order comes from the browser top layer rather than a page-level z-index band. The reduced fallback may use `dialog.show()` only below the Popover API support floor. | Current source, browser guard, and `spec:AST-027` | Verified current conformance |
| FR15 | `purpose` MUST match `component:Dialog`. `info` (default) lets Escape, platform close, and a modal scrim click request close; `form` lets Escape and platform close request close and ignores scrim clicks; `required` lets none request close, registers with the shared stack as `block` so the request does not reach a lower layer, and exposes a modal drawer as `role="alertdialog"`. Without a scrim, `form` and `info` behave the same. | DEC-1; purpose suite; `family:overlay-dismissal` Escape behavior | Owner decision (DEC-1); pending approval |
+| FR16 | The Content area pads caller content by the drawer's container inset, `--spacing-4` by default as in Dialog, and publishes the applied inset to descendants as a container publisher. Its block-end edge applies the container inset plus the home-indicator safe area while publishing the inset alone, so a bleed child subtracts only the inset and the safe area survives below it. The root dialog keeps the container-padding reset (FR12). | `architecture:container-padding`; container padding suite | Candidate (DEC-2); prototype pending owner approval |
### Allowed variation
@@ -175,6 +187,9 @@ Consumer prop syntax and examples remain in `Drawer.doc.mjs`.
### Transformation and precedence order
+- **ORD0 — Content inset.** The `padding` prop, then the theme's `padding`
+ properties on `drawer`, then `--spacing-4`, as in Dialog. The block-end
+ safe-area inset is added after that resolution in every mode.
- **ORD1 — Open.** Resolve the current logical edge and width, retain the rendered
panel, capture the currently focused element, use current `hasScrim` to select
the native host, then honor a rendered autofocus destination.
@@ -234,7 +249,7 @@ Consumer prop syntax and examples remain in `Drawer.doc.mjs`.
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------- | ------------------ |
| Panel | Paints the full-height side surface and owns edge, width, border, shadow, and motion. | Current source and public docs | Prominent | FR1–FR3, FR9, FR12 |
-| Content region | Provides full-height scrolling for caller-owned inspector content. | Current source and public docs | Prominent | FR4, AV1 |
+| Content region | Provides full-height scrolling and the container inset for caller-owned inspector content. | Current source and public docs | Prominent | FR4, FR16, AV1 |
| Header | `DrawerHeader` supplies the title row and, when given `onOpenChange`, the close action. | `component:Button`, `LayoutHeader` | Supporting | FR7, FR12, AR5 |
| Modal scrim | At initial modal open, communicates the scrim-backed presentation and provides root-click activation behind the panel. | Current source and public docs | Supporting | FR5, FR6, AR2 |
| Page reveal | Preserves overlay context on narrow viewports unless full coverage is requested. | Current public docs | Supporting | FR3 |
@@ -259,6 +274,9 @@ decide future target qualification.
visible close and focus-handoff outcomes.
- `architecture:component-theming-surface` owns target qualification and future
anatomy mapping; this draft records the existing `drawer` target only.
+- `architecture:container-padding` owns the shared container inset protocol.
+ Admitting the Content area as a container publisher (FR16) amends that
+ `current` record — an owner-approved change outside this draft.
- `spec:AST-027/DEC-3` requires equivalent floating interactions to use an
applicable native top-layer host. Modal `showModal()` and non-modal manual
Popover hosting satisfy that cross-surface route; the documented reduced
@@ -276,6 +294,7 @@ decide future target qualification.
| FR14 | Drawer source plus `spec:AST-027` impact inventory and native-host browser guard | modal host, manual-popover host, reduced fallback | Non-modal presentation returns to a page-level band or loses native-host ordering. | `audit:Drawer/layers` |
| FR15 | `Drawer.test.tsx` purpose suite | `info`, `form`, `required`; modal and non-modal; a sibling behind a required drawer | A `form` drawer closes on a scrim click, a `required` drawer closes or lets Escape reach the drawer behind it, or its role semantics drift. | `audit:Drawer/behavior` |
| FR12 | source, `Drawer.doc.mjs`, `DrawerHeader.doc.mjs`, the `DrawerHeader` target test, and current target discovery | start/end root Panel and inherited container context | Current root target/axis or padding reset changes, or the record claims an unreachable child target or decides future admission. | `audit:Drawer/theming` |
+| FR16 | `Drawer.test.tsx` container padding suites; `defineTheme.test.ts` drawer mapping; browser evidence | default, `padding` prop, theme `padding`, lone padded Section child, Layout composition | The published inset differs from the applied padding, the default drawer changes geometry, or the block-end safe area is lost or double-subtracted. | `audit:Drawer/theming` |
| AR6 | side tests and source inspection plus Storybook ancestor-RTL audit | settled `end` placement under ancestor RTL; transform mirroring and reduced motion source-inspected | Audited settled placement or source-inspected ancestor mirroring/reduced-motion behavior changes without corresponding evidence. | `audit:Drawer/accessibility` |
## Decision log
@@ -290,11 +309,27 @@ decide future target qualification.
Rejected: keeping the built-in button and hiding it only for `required`;
reusing `DialogHeader`; removing the button with no header.
+- **DEC-2 — Drawer is a container, like Dialog** (owner decision,
+ 2026-10-08). The scrolling Content area becomes a container publisher with
+ Dialog's contract: a `padding` prop on Dialog's spacing-step scale, theme
+ `padding` on `drawer` expanded to `--astryx-drawer-padding*` container
+ tokens, and a `--spacing-4` default that the edge and Layout inset chains
+ share, exactly as in Dialog. Headers compose as in Dialog: `DrawerHeader`
+ sits in a `Layout` header slot, and the Layout redistributes the inset to its
+ regions, so the header is not inset twice. The block-end edge adds the
+ home-indicator safe area on top of the inset in every mode. Rejected
+ candidates: padding the panel root (the panel is the overlay boundary, and
+ padding there bleeds under the anchored-side border); keeping the released
+ full-bleed default, as BottomSheet does (diverges from Dialog).
+
## Open questions
- Should `DrawerHeader` supply a default focus target and name the Drawer through
`aria-labelledby`, as `DialogHeader` does for Dialog? Today `label` is required
and focus entry uses `data-autofocus`.
+- Should an explicit `padding` prop keep adding the block-end safe area
+ (DEC-2), or adopt Dialog's fullscreen rule, where an explicit value replaces
+ the safe-area fallback entirely?
Regional placement, independent modality/scrim axes, and block-axis sheets
are outside the current component boundary. Any future proposal for them requires
diff --git a/packages/lab/src/Drawer/Drawer.test.tsx b/packages/lab/src/Drawer/Drawer.test.tsx
index 5e4bd2347e..e3350f1678 100644
--- a/packages/lab/src/Drawer/Drawer.test.tsx
+++ b/packages/lab/src/Drawer/Drawer.test.tsx
@@ -925,4 +925,115 @@ describe('Drawer', () => {
);
});
});
+
+ describe('container padding', () => {
+ // StyleX lowers the block edges to their physical properties. block-end is
+ // asserted separately: its applied edge composes the safe-area inset.
+ const EDGES = [
+ ['inline-start', 'padding-inline-start'],
+ ['inline-end', 'padding-inline-end'],
+ ['block-start', 'padding-top'],
+ ] as const;
+ // StyleX strips the space after the var() fallback comma.
+ const SAFE_AREA_BLOCK_END =
+ 'calc(var(--container-padding-block-end,0px) + env(safe-area-inset-bottom,0px))';
+
+ function renderWithPadding(padding?: 0 | 2) {
+ render(
+ <Drawer
+ isOpen
+ onOpenChange={() => {}}
+ label="Details"
+ padding={padding}>
+ <span data-testid="drawer-child">Content</span>
+ </Drawer>,
+ );
+ // The content area is the child's parent: the scrolling box inside the
+ // panel, not the panel itself.
+ return getComputedStyle(
+ screen.getByTestId('drawer-child').parentElement!,
+ );
+ }
+
+ it("defaults to Dialog's --spacing-4 inset and publishes the theme chain", () => {
+ const computed = renderWithPadding();
+ for (const [edge, property] of EDGES) {
+ const published = computed
+ .getPropertyValue(`--container-padding-${edge}`)
+ .replace(/\s+/g, '');
+ expect(published, edge).toContain(
+ `var(--astryx-drawer-padding-${edge}`,
+ );
+ // No theme padding resolves to --spacing-4, as in Dialog.
+ expect(published, edge).toContain(
+ 'var(--astryx-drawer-padding,var(--spacing-4))',
+ );
+ // Applied padding reads the published value, so bleed children
+ // subtract exactly the inset they sit in.
+ expect(computed.getPropertyValue(property), edge).toBe(
+ `var(--container-padding-${edge})`,
+ );
+ }
+ // block-end publishes the same chain, while the APPLIED edge adds the
+ // home-indicator safe area on top of the container inset.
+ const publishedEnd = computed
+ .getPropertyValue('--container-padding-block-end')
+ .replace(/\s+/g, '');
+ expect(publishedEnd).toContain('var(--astryx-drawer-padding-block-end');
+ expect(publishedEnd).toContain(
+ 'var(--astryx-drawer-padding,var(--spacing-4))',
+ );
+ expect(computed.getPropertyValue('padding-bottom')).toBe(
+ SAFE_AREA_BLOCK_END,
+ );
+ // The Layout insets read the same chain, so a Layout inside the drawer
+ // lines its regions up on the drawer's inset, as in Dialog.
+ for (const name of [
+ '--layout-padding-outer-x',
+ '--layout-padding-outer-y',
+ '--layout-padding-inner-x',
+ '--layout-padding-inner-y',
+ ]) {
+ const value = computed.getPropertyValue(name).replace(/\s+/g, '');
+ expect(value, name).toContain(
+ 'var(--astryx-drawer-padding,var(--spacing-4))',
+ );
+ }
+ });
+
+ it.each([0, 2] as const)(
+ 'applies and publishes an explicit padding step (%s)',
+ padding => {
+ const computed = renderWithPadding(padding);
+ const expected = `var(--spacing-${padding})`;
+ for (const [edge, property] of EDGES) {
+ expect(
+ computed.getPropertyValue(`--container-padding-${edge}`),
+ edge,
+ ).toBe(expected);
+ expect(computed.getPropertyValue(property), edge).toBe(expected);
+ }
+ expect(computed.getPropertyValue('--container-padding-block-end')).toBe(
+ expected,
+ );
+ expect(computed.getPropertyValue('padding-bottom')).toBe(
+ SAFE_AREA_BLOCK_END,
+ );
+ expect(computed.getPropertyValue('--layout-padding-inner-x')).toBe(
+ expected,
+ );
+ },
+ );
+
+ it('keeps the panel itself unpadded and free of a padding attribute', () => {
+ renderWithPadding(2);
+ const dialog = screen.getByRole('dialog');
+ expect(dialog.hasAttribute('padding')).toBe(false);
+ expect(
+ getComputedStyle(dialog).getPropertyValue(
+ '--container-padding-inline-start',
+ ),
+ ).toBe('0px');
+ });
+ });
});
diff --git a/packages/lab/src/Drawer/Drawer.tsx b/packages/lab/src/Drawer/Drawer.tsx
index 23954d8394..db62d84f66 100644
--- a/packages/lab/src/Drawer/Drawer.tsx
+++ b/packages/lab/src/Drawer/Drawer.tsx
@@ -4,7 +4,7 @@
/**
* @file Drawer.tsx
- * @input Uses React, StyleX, theme tokens and text defaults, the Dialog purpose type, shared focus/dismissal/depth primitives, scroll locking/dialog presence, BaseProps, merged refs/props, themeProps
+ * @input Uses React, StyleX, theme tokens and text defaults, the Dialog purpose type, shared focus/dismissal/depth primitives, container padding lowering, scroll locking/dialog presence, BaseProps, merged refs/props, themeProps
* @output Exports Drawer component and DrawerProps
* @position Lab implementation; consumed by index.ts, tested by Drawer.test.tsx, demonstrated in Storybook
*
@@ -40,6 +40,14 @@
* `DrawerHeader` with `onOpenChange` for a visible close action, as with
* `DialogHeader`.
*
+ * The scrolling content area is the drawer's container, like Dialog's inner
+ * box: the `padding` prop, else the theme's `padding` on `drawer`, insets it
+ * through container tokens, defaulting to `--spacing-4` like Dialog, and the
+ * applied inset is published so a lone Section child escapes it and a Layout
+ * redistributes it to its regions. Compose `DrawerHeader` inside a `Layout`, as
+ * `DialogHeader` is composed in Dialog, so the header is not padded twice. The
+ * root dialog stays the overlay boundary (`overlayPaddingReset`).
+ *
* SYNC: When modified, update these files to stay in sync:
* - /packages/lab/src/Drawer/Drawer.doc.mjs (props table, features, usage)
* - /packages/lab/src/Drawer/Drawer.test.tsx (tests for new/changed behavior)
@@ -72,7 +80,15 @@ import {
mergeProps,
themeProps,
} from '@astryxdesign/core/utils';
-import {overlayPaddingReset} from '@astryxdesign/core/Layout';
+import {container, overlayPaddingReset} from '@astryxdesign/core/Layout';
+import {
+ containerPaddingBlockEndVarStyles,
+ containerPaddingBlockStartVarStyles,
+ containerPaddingInlineVarStyles,
+ paddingStyles,
+ spacingStepToToken,
+} from '@astryxdesign/core/Layout/padding.stylex';
+import type {SpacingStep, SpacingToken} from '@astryxdesign/core/Layout';
import {useDrawerDialogPresence} from './useDrawerDialogPresence';
// =============================================================================
@@ -222,11 +238,12 @@ const styles = stylex.create({
},
},
},
- // Scrollable content area — full-bleed; consumers compose their own
- // header/body/footer padding.
+ // Scrollable content area, and the drawer's container: it carries the
+ // container padding (--spacing-4 unless the `padding` prop or the theme sets
+ // it, as in Dialog) and publishes it, so a lone Section child escapes it
+ // exactly as in Dialog and a Layout picks it up for its regions.
// touch-action + overscroll containment keep momentum scrolling inside
- // the panel on touch devices; the safe-area inset keeps the last row of
- // content clear of the home indicator.
+ // the panel on touch devices.
content: {
flexGrow: 1,
minHeight: 0,
@@ -235,8 +252,27 @@ const styles = stylex.create({
overflowX: 'hidden',
overscrollBehavior: 'contain',
touchAction: 'pan-y',
- paddingBlockEnd: 'env(safe-area-inset-bottom, 0px)',
outline: 'none',
+ // The scrolling area paints the surface itself, covering the panel's whole
+ // inner box. Without it the panel's edge is not uniform: a theme that packs
+ // an inset ring into --shadow-high (the bundled themes all add one in dark
+ // mode) draws that ring just inside the dialog, where an opaque content
+ // wrapper such as Section paints over it — so the ring shows only in the
+ // gap below where the content ends, and the panel's edges appear to change
+ // partway down. Painting the surface here hides the ring evenly, leaving
+ // the anchored-side border as the drawer's one edge (same treatment as
+ // BottomSheetPanel's body, #5305).
+ backgroundColor: colorVars['--color-background-surface'],
+ },
+ // Block-end inset of the content area = container padding + the home
+ // indicator's safe area, so the last row of content stays clear of the
+ // indicator in every padding mode. Applied after container()'s own padding so this
+ // composed value wins on the block-end edge; the published
+ // --container-padding-block-end keeps the safe area OUT, so a bleed child
+ // subtracts only the container inset and the safe area survives below it.
+ contentSafeArea: {
+ paddingBlockEnd:
+ 'calc(var(--container-padding-block-end, 0px) + env(safe-area-inset-bottom, 0px))',
},
});
@@ -329,6 +365,17 @@ export interface DrawerProps extends BaseProps<HTMLDialogElement> {
*/
purpose?: DialogPurpose;
+ /**
+ * Internal padding of the drawer content using the spacing scale, matching
+ * Dialog. Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8,
+ * 10. When omitted, uses the theme default for drawers (`--spacing-4`, 16px,
+ * unless the theme sets `padding` on `drawer`), as Dialog does. Pass `0` for
+ * a full-bleed content area. The content area is a container: a Section that
+ * is its only child escapes the padding, bleed children such as Table and
+ * Divider compensate against it, and a Layout picks it up for its regions.
+ */
+ padding?: SpacingStep;
+
/**
* Drawer content. Rendered inside a full-height scrollable area.
* Focus the element with `data-autofocus` on open, if present.
@@ -361,6 +408,11 @@ export interface DrawerProps extends BaseProps<HTMLDialogElement> {
* close the drawer, and `DrawerHeader` renders a close button when given
* `onOpenChange`.
*
+ * Like Dialog, the drawer is a container: `padding` (or a theme's `padding`
+ * on `drawer`) insets the content area, a lone Section child escapes that
+ * inset, and a Layout inside picks it up for its header, content, and footer
+ * regions. The default inset is `--spacing-4`, matching Dialog.
+ *
* @example
* ```
* const [selected, setSelected] = useState(null);
@@ -369,8 +421,10 @@ export interface DrawerProps extends BaseProps<HTMLDialogElement> {
* isOpen={selected != null}
* onOpenChange={handleOpenChange}
* label={`Details: ${selected?.name}`}>
- * <DrawerHeader title={selected?.name} onOpenChange={handleOpenChange} />
- * <HostDetails host={selected} />
+ * <Layout
+ * header={<DrawerHeader title={selected?.name} onOpenChange={handleOpenChange} />}
+ * content={<LayoutContent><HostDetails host={selected} /></LayoutContent>}
+ * />
* </Drawer>
* ```
*/
@@ -383,6 +437,7 @@ export function Drawer({
label,
hasScrim = true,
purpose = 'info',
+ padding,
children,
xstyle,
className,
@@ -400,6 +455,12 @@ export function Drawer({
// Derive dismissal behavior from purpose, as Dialog does.
const allowEscape = purpose !== 'required';
const allowScrimClick = purpose === 'info';
+ // Same lowering as Dialog: with no padding prop the content area reads the
+ // theme's --astryx-drawer-padding chain (--spacing-4 when unset), else the
+ // explicit step.
+ const usesThemePadding = padding == null;
+ const effectivePadding = padding ?? 4;
+ const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;
// Whether the panel paints: true while open and for the whole slide-out.
const [isRendered, setIsRendered] = useState(isOpen);
@@ -519,7 +580,34 @@ export function Drawer({
<LayerDepthProvider>
{/* Scrollable content area — tabIndex so the dialog's focusing steps
land on the panel body rather than the first button inside. */}
- <div tabIndex={-1} {...stylex.props(styles.content)}>
+ <div
+ tabIndex={-1}
+ {...stylex.props(
+ styles.content,
+ ...container(
+ usesThemePadding
+ ? {useThemeDefault: 'drawer'}
+ : {
+ paddingInnerX: paddingToken,
+ paddingInnerY: paddingToken,
+ paddingOuterX: paddingToken,
+ paddingOuterY: paddingToken,
+ },
+ ),
+ !usesThemePadding &&
+ effectivePadding !== 4 &&
+ paddingStyles[effectivePadding],
+ !usesThemePadding &&
+ effectivePadding !== 4 &&
+ containerPaddingInlineVarStyles[effectivePadding],
+ !usesThemePadding &&
+ effectivePadding !== 4 &&
+ containerPaddingBlockStartVarStyles[effectivePadding],
+ !usesThemePadding &&
+ effectivePadding !== 4 &&
+ containerPaddingBlockEndVarStyles[effectivePadding],
+ styles.contentSafeArea,
+ )}>
{children}
</div>
</LayerDepthProvider>
diff --git a/packages/lab/src/Drawer/DrawerHeader.doc.mjs b/packages/lab/src/Drawer/DrawerHeader.doc.mjs
index 78449ecf4b..b65206347b 100644
--- a/packages/lab/src/Drawer/DrawerHeader.doc.mjs
+++ b/packages/lab/src/Drawer/DrawerHeader.doc.mjs
@@ -18,7 +18,7 @@ export const docs = {
'Header for drawers with a title, optional subtitle, close button, and start/end content slots. Same API as DialogHeader.',
usage: {
description:
- 'Compose DrawerHeader first inside a Drawer for a title row and, when you pass onOpenChange, a close button. Drawer renders no close button of its own. Unlike DialogHeader it does not take focus on open (Drawer uses data-autofocus) and does not name the drawer (Drawer label does).',
+ 'Compose DrawerHeader in the header slot of a Layout inside the Drawer, as DialogHeader is composed in Dialog, for a title row and, when you pass onOpenChange, a close button. The Layout keeps the header on the drawer inset instead of padding it twice. Drawer renders no close button of its own. Unlike DialogHeader it does not take focus on open (Drawer uses data-autofocus) and does not name the drawer (Drawer label does).',
anatomy: [
{
name: 'Header row',
@@ -89,7 +89,7 @@ export const docs = {
name: 'hasDivider',
type: 'boolean',
description:
- "Adds a border at the bottom edge. Defaults to the parent Layout's defaultHasDividers; directly inside a Drawer there is none.",
+ "Adds a border at the bottom edge. Defaults to the parent Layout's defaultHasDividers.",
},
],
playground: {
@@ -114,6 +114,7 @@ export const docs = {
code: `
import {useState} from 'react';
import {Drawer, DrawerHeader} from '@astryxdesign/lab';
+import {Layout, LayoutContent} from '@astryxdesign/core/Layout';
function Inspector() {
const [isOpen, setIsOpen] = useState(true);
@@ -121,7 +122,10 @@ function Inspector() {
// Passing onOpenChange renders a close button that calls it with false.
return (
<Drawer isOpen={isOpen} onOpenChange={setIsOpen} label="Details">
- <DrawerHeader title="Details" onOpenChange={setIsOpen} />
+ <Layout
+ header={<DrawerHeader title="Details" onOpenChange={setIsOpen} />}
+ content={<LayoutContent>Content</LayoutContent>}
+ />
</Drawer>
);
}
@@ -151,7 +155,7 @@ export const docsZh = {
'抽屉头部,包含标题、可选副标题、关闭按钮以及首尾内容插槽;API 与 DialogHeader 相同。',
usage: {
description:
- '在 Drawer 中最先放置 DrawerHeader,提供标题行;传入 onOpenChange 时显示关闭按钮。Drawer 本身不渲染关闭按钮。与 DialogHeader 不同,它不会在打开时获得焦点(Drawer 使用 data-autofocus),也不为抽屉命名(由 Drawer 的 label 命名)。',
+ '像 Dialog 中的 DialogHeader 一样,把 DrawerHeader 放在 Drawer 内 Layout 的 header 插槽,提供标题行;传入 onOpenChange 时显示关闭按钮。Layout 让页眉对齐抽屉的内边距,而不是重复缩进。Drawer 本身不渲染关闭按钮。与 DialogHeader 不同,它不会在打开时获得焦点(Drawer 使用 data-autofocus),也不为抽屉命名(由 Drawer 的 label 命名)。',
anatomy: [
{
name: 'Header row',
@@ -218,7 +222,7 @@ export const docsZh = {
name: 'hasDivider',
type: 'boolean',
description:
- '在底部边缘添加分隔线。默认取父级 Layout 的 defaultHasDividers;直接放在 Drawer 中时没有分隔线。',
+ '在底部边缘添加分隔线。默认取父级 Layout 的 defaultHasDividers。',
},
],
theming: {
@@ -240,7 +244,7 @@ export const docsDense = {
'drawer header w/ title, optional subtitle, close button, start/end content slots; same API as DialogHeader',
usage: {
description:
- 'first child of Drawer; close button only when given onOpenChange (Drawer has none built in); no focus on open (Drawer uses data-autofocus); does not name the drawer (Drawer label does)',
+ 'header slot of a Layout inside Drawer, like DialogHeader in Dialog; close button only when given onOpenChange (Drawer has none built in); no focus on open (Drawer uses data-autofocus); does not name the drawer (Drawer label does)',
anatomy: [
{
name: 'Header row',
@@ -282,7 +286,6 @@ export const docsDense = {
endContent: 'content after title, before close button',
endContentEdgeCompensation:
'end-content slot axes: inline | block | all; omit=automatic close-action compensation',
- hasDivider:
- 'bottom border; default = parent Layout defaultHasDividers (none directly in Drawer)',
+ hasDivider: 'bottom border; default = parent Layout defaultHasDividers',
},
};