@astryxdesign/core 0.7.5 → 0.7.6-canary.00507ba

package/src/Drawer/Drawer.spec.md

@@ -1,19 +1,18 @@
 ---
 schema_version: 3
-template_version: 5
+template_version: 7
 kind: component
 id: component:Drawer
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: 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/Drawer/DrawerHeader.test.tsx,
     packages/core/src/Layer/useLayerDismissal.test.tsx,
     packages/core/src/Layer/layerDismissalFamilies.test.tsx,
     .github/scripts/modal-close-visibility.js,
@@ -22,7 +21,7 @@ verified_by:
   ]
 modules: []
 families: [family:overlay-dismissal]
-design_specs: []
+design_specs: [design:reduced-motion]
 architecture:
   [
     architecture:component-theming-surface,
@@ -32,24 +31,24 @@ architecture:
     architecture:react-component-runtime,
   ]
 contributing: []
-system_specs: [spec:AST-027/DEC-3]
+system_specs: [spec:AST-027/DEC-3, spec:AST-094]
 ---
 
 # Drawer component contract
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Current Core surface    | `@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`.                                                                                 |
-| 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         | 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 | Drawer is a Core component imported from `@astryxdesign/core/Drawer` (DEC-3). 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; FR16 records container padding.                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| 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.                                                                                                                                                                           |
-| Record context          | `component:Drawer` FR1–FR16 and AR1–AR6 are draft candidate statements. Linked records govern only within their own declared authority and scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| 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 summarizes the draft body below; it does not change this record's declared authority.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -58,17 +57,17 @@ 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 draft records the viewport-only Core component: its shared layer
+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: `not yet released` in Core.
-- Compatibility class: additive in Core (root and `./Drawer` subpath exports);
-  `@astryxdesign/lab`, which publishes only canary builds, does not export
-  Drawer.
+- Released default preserved: `yes`.
+- Compatibility class: records shipped behavior; no public change. Core
+  exports Drawer from the root and the `./Drawer` subpath; `@astryxdesign/lab`
+  does not.
 - Container padding (FR16, DEC-2): the `padding` prop or a theme's `padding` on
   `drawer` insets the Content area through container tokens. With neither set
   the inset is `--spacing-4`, as in Dialog; `padding={0}` keeps a full-bleed
@@ -80,12 +79,32 @@ does not revive a regional, pane-scoped, or container-targeted Drawer model.
 - 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: no codemod, because `@astryxdesign/lab` publishes only
-  canary builds. Canary callers import Drawer and DrawerHeader from
-  `@astryxdesign/core/Drawer` instead of `@astryxdesign/lab`.
+- 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-runtime` INV14 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-motion` DR1 forbids the travel and DR3 allows no
+  animated property; a touch user gets no opacity fade, which DR2 calls for.
+- **A tap during the entrance is not held.** Under a finger, a scrim tap that
+  lands while the drawer is still entering closes an `info` drawer, and a tap
+  or drag reaches the panel. `spec:AST-094` FR35 holds pointer input until the
+  entrance finishes.
+- **A consumer `onCancel` never runs.** Drawer sets its own `onCancel` after
+  the caller's props, so a caller's `onCancel` is dropped.
+  `architecture:public-component-api` INV5 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-padding`
+  does not name Drawer among its container publishers.
+
 ## Ownership boundary
 
 **Owns**
@@ -100,8 +119,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 - 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
   lifetime. Escape and platform-close routing belong to the shared owner; paint
   order in both presentations belongs to the browser top layer.
@@ -116,45 +133,45 @@ Consumer migration instructions belong in consumer docs and release notes.
   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.
-- Button painting for the `DrawerHeader` close action — delegated to
-  `component:Button`; header row layout is delegated to `LayoutHeader`.
+- `DrawerHeader`, its title row, close action, and targets — owned by
+  `component: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` | draft 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` | draft 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` | draft 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` | draft 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` | draft Core 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` | draft 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` | draft Core 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` | draft Core 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`       | 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   | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Basis                                                            | Draft review state                                                                                       |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| 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                         | Verified current behavior; no new behavior decided                                                       |
-| 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                        | Verified current behavior                                                                                |
-| 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                            | Verified current behavior                                                                                |
-| FR4  | Visibility through Drawer-owned behavior MUST follow `isOpen`. Uncanceled Escape routed by the shared stack and uncanceled modal-backdrop activation request `false` when `purpose` allows (FR15), 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                        | Verified for Drawer-owned paths; direct native mutation through the public ref is outside this guarantee |
-| FR5  | At open time, `hasScrim={true}` MUST select native `showModal()` with `aria-modal`, a focus trap, body scroll locking, and a visible backdrop; `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                     | Initial modes verified; live presentation changes unsupported                                            |
-| FR6  | An uncanceled modal root/backdrop click (`target === currentTarget` while live `hasScrim` is true) MUST request close when `purpose` is `info`, and MUST NOT for `form` or `required`. 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                                              | Verified current behavior                                                                                |
-| FR7  | Drawer MUST NOT render a close control of its own. `DrawerHeader` MUST render a close action with an accessible name only when `onOpenChange` is passed and call it with `false` without taking open-state ownership. It renders its title as an h2 and neither moves focus on mount nor names the Drawer.                                                                                                                                                                                                                           | DEC-1; close-control and `DrawerHeader.test.tsx` suites          | Owner decision (DEC-1); pending approval                                                                 |
-| 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.                        | Current presence hook and focus tests                            | Verified for completed controlled close                                                                  |
-| 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       | Observable outcome verified                                                                              |
-| 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                            | Verified current behavior                                                                                |
-| FR11 | At this commit, `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`, `onCancel`, and, for a modal `required` drawer, `role="alertdialog"`. A consumer `onKeyDown` that prevents default cancels shared-stack Escape dismissal for the press. | Current source and focused keyboard tests                        | Recorded current behavior; not a stable compatibility decision                                           |
-| FR12 | At this commit, the painted root dialog emits the documented `drawer` target and `side` selector axis and applies the container-padding reset. `DrawerHeader` emits `drawer-header`, `drawer-header-start-content`, `drawer-header-title-block`, `drawer-header-end-content`, and `drawer-header-close-icon`, mirroring `DialogHeader`. 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             | Current reachability only; no target-admission decision                                                  |
-| 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                                                      |
+| 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`. Uncanceled Escape routed by the shared stack and uncanceled modal-backdrop activation request `false` when `purpose` allows (FR15), 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, body scroll locking, and a visible backdrop; `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 modal root/backdrop click (`target === currentTarget` while live `hasScrim` is true) MUST request close when `purpose` is `info`, and MUST NOT for `form` or `required`. 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                                              |
+| 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.                                                                         | 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        |
 
 ### Allowed variation
 
@@ -236,31 +253,34 @@ Consumer prop syntax and examples remain in `Drawer.doc.mjs`.
 - **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. When
-  rendered, the `DrawerHeader` close action keeps its translated accessible name
-  and Button-owned keyboard/focus behavior in both presentations.
+- **AR5 — Close affordance.** Drawer provides no close control of its own; the
+  `DrawerHeader` close action's name and behavior are owned by
+  `component:DrawerHeader`.
 - **AR6 — Direction and motion.** Logical inset placement and slide-direction
   mirroring follow DOM directionality from the nearest effective `dir` attribute,
   including an explicit local override or an inherited direction. As required by
   `design:bidirectionality`, a region whose direction differs from its ancestor
   describes that direction in DOM `dir`; a CSS-only `direction` declaration is
-  not a supported substitute. Motion reduces under `prefers-reduced-motion`
-  without changing the final state.
+  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-motion` DR2) 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: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                |
+| 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, 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`, and
-`DrawerHeader` carries its five `drawer-header` targets. No separate Drawer target
-is currently reachable for Content region or Modal scrim. This draft does not
-decide future target qualification.
+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
 
@@ -276,13 +296,12 @@ decide future target qualification.
   FR11 records current DOM/ref/event reachability without making a stable
   compatibility decision.
 - `architecture:react-component-runtime` owns effect/resource cleanup, native-host
-  synchronization, and node/lifecycle safety. This draft records Drawer-owned
+  synchronization, and node/lifecycle safety. This record covers Drawer-owned
   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.
+  anatomy mapping; this record covers 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.
+  It does not yet admit Drawer's Content area as a container publisher (FR16).
 - `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
@@ -292,17 +311,26 @@ decide future target qualification.
 
 | Contract        | Verification                                                                                                              | Representative states                                                                                                   | Mutation or failure expectation                                                                                                                                                                    | Audit section                |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1–FR7         | `Drawer.test.tsx` render, initial-mode, click, sizing, side, and control suites plus `DrawerHeader.test.tsx`              | 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`      |
+| 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` |
 | 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`, `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`       |
+| 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` |
 
+Read from source, with no focused test yet:
+
+- FR1: not reserving layout space or reflowing the page.
+- FR5: body 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
@@ -345,6 +373,9 @@ decide future target qualification.
 - 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?
+- How `DrawerHeader`'s `endContentEdgeCompensation` axis values map onto
+  `endContentEdge` treatment values is carried in `component: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

package/src/Drawer/Drawer.test.tsx

@@ -60,6 +60,19 @@ afterEach(() => {
 });
 
 describe('Drawer', () => {
+  it('clips its panel with `clip`, not `hidden`: the panel is no scroll container', () => {
+    // `hidden` clips exactly as well, so it reads as a harmless tidy-up, but it
+    // makes the panel a scroll container, and in Chromium its overscroll
+    // containment then holds a drag on the page beside a non-modal drawer
+    // (__tests__/DrawerNonModalPageScroll.a11y.chromium.spec.ts).
+    render(
+      <Drawer isOpen onOpenChange={() => {}} label="Details" hasScrim={false}>
+        Content
+      </Drawer>,
+    );
+    expect(getComputedStyle(screen.getByRole('dialog')).overflow).toBe('clip');
+  });
+
   it('renders children when open', () => {
     render(
       <Drawer isOpen onOpenChange={() => {}} label="Host details">
@@ -240,6 +253,28 @@ describe('Drawer', () => {
       expect(cancelEvent.defaultPrevented).toBe(true);
     });
 
+    // A file input fires a bubbling `cancel` at itself when its picker is
+    // dismissed (Escape, or Cancel in the chooser). It reaches the <dialog>
+    // like a close request but is not one.
+    it('stays open when a file picker inside it is dismissed', () => {
+      const handleOpenChange = vi.fn();
+      render(
+        <Drawer isOpen onOpenChange={handleOpenChange} label="Details">
+          <input type="file" aria-label="Picture" />
+        </Drawer>,
+      );
+      const fromPicker = new Event('cancel', {bubbles: true, cancelable: true});
+      screen.getByLabelText('Picture').dispatchEvent(fromPicker);
+      expect(handleOpenChange).not.toHaveBeenCalled();
+      expect(fromPicker.defaultPrevented).toBe(false);
+      // Its own close request still closes it.
+      screen
+        .getByRole('dialog')
+        .dispatchEvent(new Event('cancel', {cancelable: true}));
+      expect(handleOpenChange).toHaveBeenCalledTimes(1);
+      expect(handleOpenChange).toHaveBeenCalledWith(false);
+    });
+
     it('ignores other keys', () => {
       const handleOpenChange = vi.fn();
       render(

package/src/Drawer/Drawer.tsx

@@ -52,6 +52,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Drawer/Drawer.doc.mjs (props table, features, usage)
  * - /packages/core/src/Drawer/Drawer.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/Drawer/__tests__/DrawerNonModalPageScroll.a11y.chromium.spec.ts (the page beside a non-modal drawer scrolls)
  * - /packages/core/src/Drawer/Drawer.spec.md (component contract)
  * - /packages/core/src/Drawer/index.ts (exports if types change)
  * - /packages/cli/assets/templates/blocks/components/Drawer/ (showcase blocks)
@@ -121,8 +122,13 @@ const styles = stylex.create({
     flexDirection: 'column',
     backgroundColor: colorVars['--color-background-surface'],
     boxShadow: shadowVars['--shadow-high'],
-    overflow: 'hidden',
-    overscrollBehavior: 'contain',
+    // `clip`, not `hidden`: `hidden` makes the panel a scroll container, and
+    // Chromium then holds a finger's drag on the page beside an open
+    // non-modal drawer in that container's overscroll containment, so the
+    // page stops scrolling. `clip` clips the off-screen panel the same way
+    // without a scroll container (MobileNav's dialog does the same). The
+    // content area keeps its own scrolling and containment.
+    overflow: 'clip',
     outline: 'none',
     // Full-height side panel, pinned across the block axis.
     insetBlockStart: 0,
@@ -496,6 +502,11 @@ export function Drawer({
   // same top-most/IME rules as the shared Escape listener.
   const handleCancel = useCallback(
     (event: React.SyntheticEvent<HTMLDialogElement>) => {
+      // A cancel that bubbles up from inside (a dismissed file picker) is not
+      // a close request; the platform's is fired at the dialog itself.
+      if (event.target !== event.currentTarget) {
+        return;
+      }
       event.preventDefault();
       if (shouldDismissOnCloseRequest() && allowEscape) {
         handleDismiss();