An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Drawer authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-30 owners: [cixzhang, imdreamrunner] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/Drawer/Drawer.test.tsx, packages/core/src/Layer/useLayerDismissal.test.tsx, packages/core/src/Layer/layerDismissalFamilies.test.tsx, .github/scripts/modal-close-visibility.js, apps/storybook/rtl-audit/rtl-audit.mjs, scripts/check-knowledge.mjs, packages/core/src/tests/modalBackdrop.test.tsx, packages/core/src/tests/ModalBackdrop.a11y.browser.spec.ts, ] modules: [] families: [family:overlay-dismissal] design_specs: [design:reduced-motion] architecture: [ architecture:component-theming-surface, architecture:container-padding, architecture:layer-runtime, architecture:public-component-api, architecture:react-component-runtime, ] contributing: []
system_specs: [spec:AST-027/DEC-3, spec:AST-094]
Drawer component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | @astryxdesign/core exports Drawer, DrawerProps, DrawerHeader, and DrawerHeaderProps from the package root and the ./Drawer subpath (DEC-3); @astryxdesign/lab does not export them. DrawerProps extends BaseProps<HTMLDialogElement>, separately declares ref, requires isOpen, onOpenChange, label, and children, accepts purpose (required, form, or info; default info), an optional padding spacing step (FR16), and an optional experimental object (DEC-4), and has no hasCloseButton. Stable API admission and compatibility belong to architecture:public-component-api; DrawerHeader is recorded in component:DrawerHeader. |
| 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. 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 | A drawer paints no close control of its own; 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. Shared topmost/IME Escape routing, top-layer paint order, one dismissal per request, and focus return apply in both presentations. |
| Builder impact | Import from @astryxdesign/core/Drawer or the Core root. For a visible close action, compose <DrawerHeader title onOpenChange> in a Layout header slot, as DialogHeader is composed in Dialog. The Content area is inset by --spacing-4 by default; padding={0} gives a full-bleed Content area. Set purpose where Dialog would. State and content remain caller-owned; Drawer renders the caller's current children during exit. Sibling composition is current consumer guidance, and a consumer onKeyDown that prevents default cancels Escape dismissal. |
| Compatibility/readiness | Records shipped behavior; no public change. Drawer is a Core component imported from @astryxdesign/core/Drawer (DEC-3). Five implementation gaps, listed under Current-state impact. |
| 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; a surviving @astryxdesign/lab export; or claims of stable API/theming compatibility that architecture:public-component-api has not admitted. |
| Governing rules | family:overlay-dismissal; architecture:layer-runtime; architecture:container-padding; spec:AST-027/DEC-3; design:reduced-motion. |
This table is a review projection; the body below is authoritative.
Intent
Drawer presents contextual details or controls in a full-height side panel that floats over the current page without reflowing it. It supports modal inspection with a scrim and non-modal master-detail inspection that leaves the page behind available.
This record covers the viewport-only Core component: its shared layer lifecycle, its Dialog-aligned close control and dismissal policy (DEC-1), and its container padding (DEC-2). It introduces no scope concept. In particular, it does not revive a regional, pane-scoped, or container-targeted Drawer model.
Compatibility and migration
- Released default preserved:
yes. - Compatibility class: records shipped behavior; no public change. Core
exports Drawer from the root and the
./Drawersubpath;@astryxdesign/labdoes not. - Container padding (FR16, DEC-2): the
paddingprop or a theme'spaddingondrawerinsets the Content area through container tokens. With neither set the inset is--spacing-4, as in Dialog;padding={0}keeps a full-bleed Content area. The block-end safe-area inset applies in every mode. - Experimental surface (DEC-4): full-viewport mobile coverage is the
isFullWidthOnMobileoption inside the optionalexperimentalprop object, outside the stable compatibility promise (spec:AST-017/FR21). Omittingexperimentalkeeps the 56px page reveal. - 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: none.
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Drawer builds its own top layer, exit, and backdrop. Drawer mounts its own
modal and popover hosts, runs its own exit hold, and paints its own scrim.
architecture:layer-runtimeINV14 has a layer use the runtime's top-layer mounting, presentation hold, exit copy, and backdrop tint. - Reduced motion keeps a 0.01 s slide on every pointer. Under reduced
motion the slide and the scrim transition still run for 0.01 s. For a fine
pointer,
design:reduced-motionDR1 forbids the travel and DR3 allows no animated property; a touch user gets no opacity fade, which DR2 calls for. - A finger is held during the entrance only under a coarse primary
pointer. There, a tap or a drag that lands while the drawer is still
entering reaches nothing, and around a non-modal drawer only one on the
panel is held. Where the primary pointer is fine and the screen also takes
touch (a touchscreen laptop), a finger's scrim tap during the entrance
closes an
infodrawer, and a tap or drag reaches the panel.spec:AST-094FR35 holds pointer input until the entrance finishes. - A consumer
onCancelnever runs. Drawer sets its ownonCancelafter the caller's props, so a caller'sonCancelis dropped.architecture:public-component-apiINV5 has accepted event inputs reach the element. - The container-padding record does not list Drawer. Drawer's Content
area publishes its inset (FR16, DEC-2), but
architecture:container-paddingdoes not name Drawer among its container publishers.
Ownership boundary
Owns
- The viewport-relative side-panel surface, logical edge, inline-size budget, and entry/exit motion.
- The modal scrim's appearance (FR20).
- The current presentation input: its value at native open selects
showModal()or the manual Popover API host. Changing it while open is unsupported. - Drawer-local focus entry/return, the
purposedismissal 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. - Registering the layer with the shared dismissal stack for its rendered lifetime. Escape and platform-close routing belong to the shared owner; paint order in both presentations belongs to the browser top layer.
Does not own / non-goals
- Caller-provided forms, inspectors, footers, or other content.
DrawerHeaderis optional composition, not required anatomy. - Block-axis sheets — owned by
component:BottomSheet. - Persistent panels that reserve layout space or push page content.
- Regional or pane-scoped placement, a caller-supplied container, or independent modality and scrim axes. Those are not current Drawer concepts.
- Cross-family Escape and platform-close ordering — owned by
family:overlay-dismissal; Drawer participates through the shared owner. DrawerHeader, its title row, close action, and targets — owned bycomponent:DrawerHeader.
Public concepts
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 |
Core 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 |
Core 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 |
Core 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 |
Core 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 (DEC-4) | 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 |
Core contract matching 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:DrawerHeader |
Core 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 |
Core contract matching 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 |
Core contract | nested composition is outside the documented contract |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Drawer MUST remain a viewport-relative, full-block-size overlay on the logical inline-start or inline-end edge and MUST NOT reserve layout space or reflow the page beneath it. | Current source, docs, stories, and tests |
| FR2 | The logical edge selected for an open Drawer MUST remain latched through its exit even when caller state changes the live edge prop during close. | Current exit-side test and implementation |
| FR3 | The desktop inline-size budget MUST accept pixel numbers or CSS lengths and remain bounded by the viewport. At or below 640px, page-reveal mode MUST preserve 56px and use width as a cap; full-mobile mode MUST override width with 100dvw. |
Current docs, styles, and width tests |
| FR4 | Visibility through Drawer-owned behavior MUST follow isOpen, from the render after hydration on (FR17). Uncanceled Escape routed by the shared stack and uncanceled modal-backdrop activation request false when purpose allows (FR15) and the press closes no layer open above the drawer (FR6), and a DrawerHeader close action requests false through the callback it is given; Drawer prevents its handled native cancel event from closing the dialog directly. During controlled exit, Drawer keeps its host and content region mounted while rendering the caller's current children. |
Current prop contract and lifecycle tests |
| FR5 | At open time, hasScrim={true} MUST select native showModal() with aria-modal, a focus trap, page scroll locking, and a visible backdrop; under the lock, pull-to-refresh and the page's bounce stop, because a scroll lock under a modal holds the page (spec:AST-094 FR19), as behind a UIKit modal presentation; hasScrim={false} MUST select a manual Popover API host that leaves the page behind interactive. Changing hasScrim while open is not a supported native-mode transition. |
Current source, docs, and initial-mode tests |
| FR6 | An uncanceled press on the modal backdrop that starts and ends there (target === currentTarget for the pointer-down, the pointer-up, and the click, while live hasScrim is true; family:overlay-dismissal FR10) MUST request close when purpose is info, unless the press light-dismisses a layer open above the drawer, which consumes it (family:overlay-dismissal FR11), and MUST NOT for form or required; a press that crosses the drawer's edge either way MUST NOT request close. Descendant clicks and dialog-root clicks while live hasScrim is false MUST NOT request close, and non-modal presentation MUST NOT install an invisible outside-pointer dismissal plane. |
Current click tests; useBackdropPress.test.tsx |
| FR7 | Drawer MUST NOT render a close control of its own. A visible close action is caller composition, normally DrawerHeader with onOpenChange (component:DrawerHeader FR3), which requests false through that callback without taking open-state ownership. |
DEC-1; close-control suite |
| FR8 | Opening MUST present the native host, capture the element focused before opening, and attempt to focus the first rendered [data-autofocus] descendant, if any. After a completed controlled close releases the native host, Drawer MUST attempt to restore focus to the captured element. The non-modal host's synthetic close event MUST dispatch after that restore attempt — matching the task-queued native dialog.close() event — so a consumer close listener keeps the last word on final focus. When an open Drawer unmounts, it MUST return focus to the captured element if focus would otherwise be lost (left on the page body or on a node that left the document); a development-only simulated unmount is not a removal. |
Current presence hook and focus tests |
| FR9 | Closing MUST retain the panel host, content region, edge, and native presentation while the exit remains visible and continue rendering the caller's current children. The transform transition is authoritative, a computed-duration backstop prevents a lost event from stranding the host, and native release and React hiding land together so no frame paints outside the top layer. |
Current lifecycle tests and browser close-visibility guard |
| FR10 | Sibling Drawers MUST be composed as siblings. The last-opened present sibling owns the first Escape request through the shared stack; a closing sibling retains that ownership through its visible exit, and reopening registers a new active cycle so one request never closes two surfaces. Paint order in both presentations follows the browser top layer's chronological order. | Current docs, shared stack, and tests |
| FR11 | DrawerProps extends BaseProps<HTMLDialogElement> and separately declares ref. The root filters open, merges xstyle, className, and style, forwards remaining unclaimed props, composes consumer onClick, forwards consumer onKeyDown ahead of the shared document-level Escape owner, and owns aria-label, aria-modal, and, for a modal required drawer, role="alertdialog". Implementation gap: a consumer onCancel is dropped (Current-state impact). A consumer onKeyDown that prevents default cancels shared-stack Escape dismissal for the press. |
Current source and focused keyboard tests |
| FR12 | The painted root dialog emits the documented drawer target and side selector axis and applies the container-padding reset. DrawerHeader's targets are owned by component:DrawerHeader FR5. No separate Drawer target is currently emitted for content or scrim; future target qualification remains owned by architecture:component-theming-surface. |
Current source, docs, and structural target metadata |
| 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 |
| 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 |
| FR15 | purpose takes the same values and default as Dialog's prop. 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 |
| 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 would; architecture:container-padding does not yet admit Drawer as one (Current-state impact). 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 |
| FR17 | A Drawer open on the server renders closed until hydration (no open styles, no aria-modal, the markup of a closed Drawer) and opens in the render after hydration, the first that can enter its native host; it never claims a modality it does not have (spec:AST-020 FR1, WCAG 2.2 SC 4.1.2). The server and hydrating renders produce the same markup (spec:AST-013 FR9), and the open after hydration is settled, with no entry motion; later opens and closes animate as usual (spec:AST-013 FR13). |
spec:AST-020 FR1 |
| FR18 | While a modal Drawer (hasScrim) is open it supplies its <dialog> as the passive global outlet, so app-global surfaces such as toasts render inside it, paint above it, and stay operable and reachable by keyboard; it stops supplying when it starts to close, so they return to their place and are not carried out with the exit. Moving them keeps toast entries, timers, and focus handoff (spec:AST-003 FR18, FR19). A non-modal Drawer supplies no outlet (architecture:layer-runtime). |
spec:AST-003 FR18 |
| FR19 | When a non-modal Drawer (hasScrim={false}) enters the top layer through showPopover(), a top-layer toast viewport shown before it leaves and re-enters the top layer in place, keeping focus inside it, so toasts paint above the drawer; the drawer supplies no outlet, and its close moves and re-enters nothing (architecture:layer-runtime). |
architecture:layer-runtime |
| FR20 | Drawer's scrim is the theme's --color-overlay dim with no blur, on every pointer; under forced colors the drawer keeps a visible edge. |
Owner decision, 2026-10-25: the overlay stays theme-controlled and unblurred on every pointer. |
Allowed variation
- AV1 — Caller content. Any renderable inspector/detail content may occupy the
scrolling content region without becoming Drawer-owned anatomy. Drawer renders
current
children; callers decide whether the underlying data remains available during exit. - AV2 — Inline size. Consumers may choose the desktop budget within valid CSS
and viewport constraints. It remains the cap in mobile page-reveal mode, while
full-mobile mode uses
100dvwinstead. - AV3 — Presentation. The value at native open selects the modal dialog or
the non-modal popover host. Changing
hasScrimwhile open is unsupported. - AV4 — Close control. Callers choose whether to render a close action,
normally
DrawerHeaderwithonOpenChange, or their own control. - AV6 — Dismissal purpose. Callers choose
info,form, orrequired. - AV5 — Motion duration. Themes may alter the transform transition duration; close timing follows computed CSS and reduced-motion preferences.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Closed | no native presentation or visible panel | caller content may remain mounted in React |
| Modal inspector | opened with hasScrim true via showModal() with scrim, modal semantics, focus trap, and body lock |
edge, width, caller content, autofocus destination, header close action, and purpose |
| Non-modal master-detail inspector | opened with hasScrim false via the manual popover host; no scrim, aria-modal, or body lock; the page behind stays interactive |
edge, width, caller content, header close action, and purpose |
| Required modal drawer | Escape, platform close, and scrim click do not close; exposed as alertdialog; a lower layer does not receive the Escape |
caller-provided way out |
| Narrow viewport with page reveal | panel does not exceed its width cap and preserves 56px of the page |
requested width below the cap |
| Narrow full-coverage viewport | panel uses 100dvw, overriding the requested width |
caller content |
| Two sibling Drawers | later-opened open Drawer paints above through the browser top layer and owns the first Escape request through the shared stack | edge, width, caller content, and either presentation composed as siblings |
| Exiting Drawer | panel host, content region, logical edge, native presentation, and stack registration remain while the exit is visible; current children render | caller-controlled child data and motion duration |
Transformation and precedence order
- ORD0 — Content inset. The
paddingprop, then the theme'spaddingproperties ondrawer, 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
hasScrimto select the native host, then honor a rendered autofocus destination. - ORD2 — Close. During controlled close, Drawer keeps its panel and
caller-provided content visible through the exit animation. Transition
completion or the computed-duration backstop releases the native host and hides
React output together, so presentation ends without an intermediate visible
frame; Drawer then attempts to restore focus to the previously focused element
when available. The non-modal host's synthetic
closeevent dispatches only after that restore attempt, so a consumer close listener that retargets focus observes the same last-word ordering as the task-queued native event. - ORD3 — Sibling order. Sibling order comes from the shared dismissal stack and the browser top layer: the last-opened present sibling is frontmost and handles Escape first in both presentations. Descendant overlays remain governed by their own component and family contracts rather than Drawer nesting.
Performance and resources
- PR1 — Exit-only resources. Transition listeners and the backstop timer exist only while close is waiting for the visible transform exit and are removed on completion, interruption, or unmount.
- PR2 — Presentation cleanup. Native presentation and any active body scroll lock exist only for their active states and are released on controlled close, unmount, or hidden Activity cleanup.
- PR3 — Viewport-relative sizing. Drawer derives sizing from
width, the experimentalexperimental.isFullWidthOnMobileoption (DEC-4), and the viewport; callers do not supply a regional measurement target.
Accessibility contract
- AR1 — Name.
labelis a required string forwarded toaria-label; caller content is not used as an implicit name. Current code does not reject an empty or whitespace-only value. - AR2 — Modal truthfulness. At open time,
hasScrim={true}uses native modal dialog state andaria-modal;hasScrim={false}uses the non-modal popover host and omitsaria-modal. A modalrequireddrawer usesrole="alertdialog". ChanginghasScrimwhile open is not a supported transition. - AR3 — Keyboard dismissal. Escape requests close only for the topmost
registered layer through the shared stack and only when
purposeallows; arequireddrawer consumes it. A consumeronKeyDownthat prevents default cancels that dismissal, and unrelated keys do not dismiss. - AR4 — Focus lifecycle. Focus enters visible Drawer content through the documented autofocus/native path and, after a completed controlled close, Drawer attempts to restore focus to the element that was active when the Drawer opened.
- AR5 — Close affordance. Drawer provides no close control of its own; the
DrawerHeaderclose action's name and behavior are owned bycomponent:DrawerHeader. - AR6 — Direction and motion. Logical inset placement and slide-direction
mirroring follow DOM directionality from the nearest effective
dirattribute, including an explicit local override or an inherited direction. As required bydesign:bidirectionality, a region whose direction differs from its ancestor describes that direction in DOMdir; a CSS-onlydirectiondeclaration is not a supported substitute. Under reduced motion the entrance and exit are an opacity-only fade of 200 ms or less on a coarse pointer (design:reduced-motionDR2) and immediate otherwise (DR3), without changing the final state, apart from the reduced-motion gap (Current-state impact).
Design relationships
| 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 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:DrawerHeader |
Supporting | FR7, 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, FR20, AR2 |
| Page reveal | Preserves overlay context on narrow viewports unless full coverage is requested. | Current public docs | Supporting | FR3 |
The root Panel carries the current drawer target and reflects side;
DrawerHeader's targets are owned by component:DrawerHeader. No separate
Drawer target is reachable for Content region or Modal scrim, and future target
qualification is not decided here. No anatomy-theming map is recorded yet; the
block is optional during migration, so the map is deferred.
Family and system relationships
family:overlay-dismissalowns cross-component Escape and platform-close ordering. Drawer participates through the shared owner for its rendered lifetime and supplies logical depth to descendant layers.architecture:layer-runtimeowns the distinction between native modal hosting, non-modal dialog presentation, top-layer behavior, and shared layer plumbing. Drawer's content root applies the shared private text baseline and layer content boundary, as in Dialog: surface-scoped ancestor membership stops at the drawer, while ordinary application contexts keep flowing to its content.architecture:public-component-apiowns stable API admission and compatibility. FR11 records current DOM/ref/event reachability without making a stable compatibility decision.architecture:react-component-runtimeowns effect/resource cleanup, native-host synchronization, and node/lifecycle safety. This record covers Drawer-owned visible close and focus-handoff outcomes.architecture:component-theming-surfaceowns target qualification and future anatomy mapping; this record covers the existingdrawertarget only.architecture:container-paddingowns the shared container inset protocol. It does not yet admit Drawer's Content area as a container publisher (FR16).spec:AST-027/DEC-3requires equivalent floating interactions to use an applicable native top-layer host. ModalshowModal()and non-modal manual Popover hosting satisfy that cross-surface route; the documented reduced fallback remains below the Popover API support floor.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR7 | Drawer.test.tsx render, initial-mode, click, sizing, side, and control suites |
closed/open, both edges, initial modal/non-modal modes, mobile widths | Layout reflows; an initial mode gains the wrong semantics; uncanceled root-click or full-mobile sizing becomes nondeterministic. | audit:Drawer/behavior |
| FR11 | Drawer source and focused keyboard composition/cancellation tests | filtered open, merged styling/ref, forwarded unclaimed props, owned ARIA/cancel, composed click, forwarded keydown |
Current forwarding changes without review or shared-stack Escape ignores documented consumer cancellation. | audit:Drawer/public-api |
| FR8, AR1–AR5 | Drawer.test.tsx label forwarding, autofocus, close, and focus-return suites plus the browser guard's final-focus checks |
initial modal/non-modal modes, autofocus target, connected previously focused element, close listener retargeting focus | Focus moves before presentation, completed controlled close fails to restore focus, the synthetic close overrides a consumer listener's focus target, or label forwarding/dismissal naming breaks. | audit:Drawer/accessibility |
| FR8 (unmount) | Drawer.test.tsx "Drawer unmounting while open" suite; DrawerUnmountFocus.a11y.chromium.spec.ts (click and Enter) |
non-modal and modal drawer rendered only while open and removed by its own control; removed with its view; focus moved outside first; StrictMode remount | Focus left on the page body after an open drawer unmounts, focus pulled back from where the user moved it, or a StrictMode remount that moves focus fails. | audit:Drawer/accessibility |
| FR9, PR1–PR2 | close timing tests, browser close-visibility guard, and presence-hook source inspection | controlled close, transform end, unrelated transition, lost-event backstop | Native presentation ends before visible exit, the host is stranded, cleanup paths retain resources, or an intermediate frame paints outside native presentation. | audit:Drawer/motion |
| FR10, FR13, AR3 | Drawer shared-stack suites plus useLayerDismissal and family tests |
siblings, closing top, reopen, unmount, nested descendant | One Escape closes two surfaces, a closing host drops ownership, or a reopened sibling keeps stale order. | audit:Drawer/layers |
| 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, 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 | DrawerDirection.test.tsx DOM-direction and closed/entry parity suites plus exact-head Storybook RTL evidence |
start/end; self-applied, inherited, and nested opposite dir; closed and opening transforms |
Any effective DOM direction or local override moves the panel from a different edge than its logical placement, or closed and opening transforms diverge. | audit:Drawer/accessibility |
| FR17 | Drawer.ssr.test.tsx |
Open on the server; hydration; a closed Drawer's markup | An open server render with aria-modal, open styles, or markup unlike a closed one, a hydration error, no showModal() after hydration, an entry motion on the open right after hydration, or none on a later open fails. |
audit:Drawer/accessibility |
| FR18 | ToastViewport.modalHost.test.tsx "ToastViewport above a Drawer" suite; DrawerToastOutlet.a11y.chromium.spec.ts (hit testing, click and Tab at desktop and phone widths) |
modal drawer opened over a page toast; toast raised from inside the drawer; drawer closing; drawer without a scrim | A toast viewport left outside an open modal drawer, a toast carried out with the closing drawer, a remounted toast row, or a non-modal drawer that takes the viewport fails. | audit:Drawer/accessibility |
| FR19 | ToastViewport.modalHost.test.tsx "ToastViewport above a Drawer" non-modal case; DrawerToastOutlet.a11y.chromium.spec.ts non-modal case |
a toast shown before a scrimless drawer opens over its corner; the drawer closing | A toast the scrimless drawer covers, a viewport moved into the drawer, or a re-entry on close fails. | audit:Drawer/accessibility |
| FR20 | modalBackdrop.test.tsx; ModalBackdrop.a11y.browser.spec.ts in Chromium and WebKit |
A finger at phone width; a mouse at desktop width; forced colors under either pointer | A backdrop-filter on the scrim at either width, or no visible edge in forced colors, fails. |
audit:Drawer/theming |
Read from source, with no focused test yet:
- FR1: not reserving layout space or reflowing the page.
- FR5: page scroll locking for a modal drawer.
- FR9: the computed-duration backstop.
- FR13: logical depth for descendant layers, and platform-close routing.
- FR14: the
dialog.show()fallback below the Popover API support floor. - PR1–PR2: listener, timer, presentation, and scroll-lock cleanup.
Decision log
DEC-1 — The close control and dismissal policy match Dialog (owner decision, 2026-10-01). Drawer renders no built-in close button and has no
hasCloseButton; it takes Dialog'spurposevalues and default; andDrawerHeaderhasDialogHeader's API, rendering a close action only whenonOpenChangeis passed. A Drawer-owned header, rather thanDialogHeader, keeps Drawer's focus entry (data-autofocusafter native presentation) andlabelnaming and avoidsdialog-headertheme targets. Rejected: a built-in button hidden only forrequired; reusingDialogHeader.DEC-2 — Drawer is a container, like Dialog (owner decision, 2026-10-08). The scrolling Content area is a container publisher with Dialog's contract: a
paddingprop on Dialog's spacing-step scale, themepaddingondrawerexpanded to--astryx-drawer-padding*container tokens, and a--spacing-4default shared by the edge and Layout inset chains.DrawerHeadersits in aLayoutheader 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: padding the panel root (the overlay boundary); a full-bleed default (diverges from Dialog).DEC-3 — Drawer is a Core component (owner decision, 2026-10-08).
Drawer,DrawerHeader, and their prop types ship from@astryxdesign/core/Drawerand the Core root, and their docsite demos are Core blocks.@astryxdesign/labdoes not export them.DEC-4 — Full-viewport mobile coverage is experimental (owner decision, 2026-10-15).
isFullWidthOnMobilelives inside the optionalexperimentalprop object, marked@experimentalin declarations andstability: 'experimental'in authored docs, so it may change or be removed in a patch release (spec:AST-017/FR21). Omittingexperimentalkeeps the 56px page reveal. Rejected: a top-level stableisFullWidthOnMobileprop.
Open questions
- Should
DrawerHeadersupply a default focus target and name the Drawer througharia-labelledby, asDialogHeaderdoes for Dialog? Todaylabelis required and focus entry usesdata-autofocus. - Should an explicit
paddingprop 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? - How
DrawerHeader'sendContentEdgeCompensationaxis values map ontoendContentEdgetreatment values is carried incomponent:DrawerHeader's open questions.
Regional placement, independent modality/scrim axes, and block-axis sheets are outside the current component boundary. Any future proposal for them requires fresh public-API and design authority.
Content boundary
This file does not duplicate consumer prop tables or examples, shared dismissal-stack internals, transition algorithms, current audit scores, implementation steps, or shared family/system rules. It links to their owners.