@astryxdesign/core 0.7.3 → 0.7.4-canary.1a552f2

package/src/BottomSheet/BottomSheetSwitcher.spec.md

@@ -13,6 +13,7 @@ review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx,
+    packages/core/src/BottomSheet/__tests__/BottomSheetNativeModal.a11y.browser.spec.ts,
     apps/storybook/stories/BottomSheetSwitcher.stories.tsx,
     scripts/check-knowledge.mjs,
   ]
@@ -57,8 +58,6 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - The presentation lifecycle of every directly nested BottomSheet child's native
   dialog: which is presented, retained during a handoff, or closed.
-  Implementation gap: the switcher renders one dialog of its own and hosts
-  every child as a panel inside it; no child owns a dialog yet.
 - Which child sheet is active, retained during a handoff, or hidden.
 - Which sheet dialog hosts the flow (its ref, `id`, and dismissal
   registration) and which paints the flow's one scrim, plus
@@ -79,27 +78,27 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept             | Closed values or states                              | Meaning                                                                                                                                                                                                                                                                                                                     | Availability by variant/orientation/state                                      | Default                                | Owner                                                                     | Stability | Invalid-value behavior                                                                     |
-| ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
-| Active sheet        | `null` or one nested BottomSheet `sheetId`           | Selects the only interactive child, or closes the flow                                                                                                                                                                                                                                                                      | All presentations                                                              | `null` is closed; the prop is required | `component:BottomSheetSwitcher`                                           | released  | A non-matching or duplicate id is not given a safe public fallback by the current contract |
-| Shared presentation | `true` / `false` through `hasScrim`                  | Selects the current modal scrim-backed host or non-modal no-scrim host                                                                                                                                                                                                                                                      | Entire flow                                                                    | `true`                                 | `component:BottomSheetSwitcher`                                           | released  | Boolean only                                                                               |
-| Child identity      | Non-empty `sheetId` on each direct BottomSheet child | Associates controlled selection, labeling, purpose, and transition state with a child                                                                                                                                                                                                                                       | Direct nested BottomSheet children                                             | none                                   | `component:BottomSheet`                                                   | released  | Empty ids warn and stay hidden; duplicate-id behavior is not specified                     |
-| Dismissal request   | `onActiveSheetChange(null)`                          | Reports an allowed implicit close without taking control from the caller                                                                                                                                                                                                                                                    | Escape/platform close, scrim click, or swipe according to active child purpose | none                                   | `component:BottomSheetSwitcher`; `family:overlay-dismissal` owns ordering | released  | The caller may retain its controlled value                                                 |
-| Dialog surface      | inherited dialog props plus `ref` and `onCancel`     | Dialog props and handlers, `onCancel` included, reach every sheet dialog; `ref`, `id`, and `data-testid` resolve to the host dialog, which is never null for an object ref while a sheet is mounted (DEC-2). Implementation gap: every dialog prop, `ref`, `id`, and `data-testid` reaches the switcher's one shared dialog | Entire flow                                                                    | none                                   | `component:BottomSheetSwitcher`                                           | released  | Component-owned semantics and handlers retain precedence                                   |
+| Concept             | Closed values or states                              | Meaning                                                                                                                                                                                                      | Availability by variant/orientation/state                                      | Default                                | Owner                                                                     | Stability | Invalid-value behavior                                                                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
+| Active sheet        | `null` or one nested BottomSheet `sheetId`           | Selects the only interactive child, or closes the flow                                                                                                                                                       | All presentations                                                              | `null` is closed; the prop is required | `component:BottomSheetSwitcher`                                           | released  | A non-matching or duplicate id is not given a safe public fallback by the current contract |
+| Shared presentation | `true` / `false` through `hasScrim`                  | Selects the current modal scrim-backed host or non-modal no-scrim host                                                                                                                                       | Entire flow                                                                    | `true`                                 | `component:BottomSheetSwitcher`                                           | released  | Boolean only                                                                               |
+| Child identity      | Non-empty `sheetId` on each direct BottomSheet child | Associates controlled selection, labeling, purpose, and transition state with a child                                                                                                                        | Direct nested BottomSheet children                                             | none                                   | `component:BottomSheet`                                                   | released  | Empty ids warn and stay hidden; duplicate-id behavior is not specified                     |
+| Dismissal request   | `onActiveSheetChange(null)`                          | Reports an allowed implicit close without taking control from the caller                                                                                                                                     | Escape/platform close, scrim click, or swipe according to active child purpose | none                                   | `component:BottomSheetSwitcher`; `family:overlay-dismissal` owns ordering | released  | The caller may retain its controlled value                                                 |
+| Dialog surface      | inherited dialog props plus `ref` and `onCancel`     | Dialog props and handlers, `onCancel` included, reach every sheet dialog; `ref`, `id`, and `data-testid` resolve to the host dialog, which is never null for an object ref while a sheet is mounted (DEC-2). | Entire flow                                                                    | none                                   | `component:BottomSheetSwitcher`                                           | released  | Component-owned semantics and handlers retain precedence                                   |
 
 ## Behavioral and layout contract
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                                                    |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| FR1 | Zero or one child sheet is interactive for each controlled `activeSheet` value; all other children are hidden or retained inert and `aria-hidden` during a transition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source, docs, and tests                          |
-| FR2 | Each child sheet owns one native dialog. Opening a sheet presents its dialog once; a handoff presents the entering sheet's dialog above the retained one and closes the retained dialog only after its panel has faded. Returning to a sheet whose dialog is still open beneath a newer one re-presents it so the interactive sheet is the topmost layer. Implementation gap: the switcher presents one shared dialog once per flow and hosts every child as a panel inside it; a handoff swaps panels in that dialog, and no dialog is re-presented.                                                                                                                                                                                                                                                                                                                                       | DEC-1                                                    |
-| FR3 | During a handoff, the entering sheet is above the retained sheet. A taller retained sheet aligns down to a shorter entering sheet, and the retained sheet fades only after required transform motion completes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and transition tests                      |
-| FR4 | Closing retains the outgoing sheet through its exit, then closes the dialog. A modal flow restores focus to the element captured when that modal flow opened.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and focus tests                           |
-| FR5 | `hasScrim=true` uses `showModal()`, a native backdrop, and native focus containment, and locks page scroll: the page does not scroll while a modal flow is presented; the lock is held continuously across a handoff, never released and re-acquired between steps; it still holds beneath a `Dialog` opened from a step; it is released after the flow's exit (DEC-1). `hasScrim=false` uses `show()` without a backdrop or scroll lock and leaves the page interactive. In a non-modal flow the sheet dialogs order themselves with local values inside the switcher's isolated flow wrapper (DEC-1); the page-level value that wrapper carries remains a `spec:AST-027` conformance gap. Implementation gap: a script focus trap runs on top of the modal dialog's native containment; a non-modal flow is one shared dialog carrying the page-level value itself, with no flow wrapper. | DEC-1; `spec:AST-027` FR2, FR4, FR8                      |
-| FR6 | The active child purpose governs implicit dismissal: `info` allows Escape, scrim click, and swipe; `form` allows Escape; `required` blocks all three and exposes `alertdialog`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current BottomSheet docs and switcher tests              |
-| FR7 | While visible, the switcher participates in `family:overlay-dismissal`; one Escape or platform close request reaches only the topmost present layer, and descendants receive a deeper logical layer scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `family:overlay-dismissal` and the audit regression test |
-| FR8 | One backdrop paints the flow's scrim at a time: the retained sheet's dialog keeps it through a handoff and the entering dialog takes it over without a fade when the retained dialog closes. A stale gesture from an outgoing sheet cannot change the flow's scrim, and unmounting a retained sheet cannot keep its dialog open or the flow's modal layer held. Implementation gap: the one backdrop is the shared dialog's, so no takeover between dialogs happens.                                                                                                                                                                                                                                                                                                                                                                                                                        | DEC-1; current tests                                     |
-| FR9 | The switcher forwards neutral dialog attributes, styling inputs, and composed handlers, `onCancel` included, to every sheet dialog, so a handler fires for whichever sheet dialog raises the event; renders `id` and `data-testid` on the host dialog only, so each appears once in the document; attaches its ref to the host dialog; and preserves its owned ARIA and dismissal behavior. An object ref's `current` is never `null` while a sheet is mounted. A callback ref follows React's semantics on a handoff: a cleanup it returned runs when it detaches from the old host; a callback ref without a cleanup is called with `null` on detach, then with the new host. Implementation gap: every forwarded input, `ref`, `id`, and `data-testid` reaches the one shared dialog, which never changes on a handoff.                                                                  | DEC-1, DEC-2; `architecture:public-component-api` INV8   |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                                                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| FR1 | Zero or one child sheet is interactive for each controlled `activeSheet` value; all other children are hidden or retained inert and `aria-hidden` during a transition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Current source, docs, and tests                          |
+| FR2 | Each child sheet owns one native dialog. Opening a sheet presents its dialog once; a handoff presents the entering sheet's dialog above the retained one and closes the retained dialog only after its panel has faded. Returning to a sheet whose dialog is still open beneath a newer one re-presents it so the interactive sheet is the topmost layer.                                                                                                                                                                                                                                                                                                                                   | DEC-1                                                    |
+| FR3 | During a handoff, the entering sheet is above the retained sheet. A taller retained sheet aligns down to a shorter entering sheet, and the retained sheet fades only after required transform motion completes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and transition tests                      |
+| FR4 | Closing retains the outgoing sheet through its exit, then closes the dialog. A modal flow restores focus to the element captured when that modal flow opened.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Current source and focus tests                           |
+| FR5 | `hasScrim=true` uses `showModal()`, a native backdrop, and native focus containment, and locks page scroll: the page does not scroll while a modal flow is presented; the lock is held continuously across a handoff, never released and re-acquired between steps; it still holds beneath a `Dialog` opened from a step; it is released after the flow's exit (DEC-1). `hasScrim=false` uses `show()` without a backdrop or scroll lock and leaves the page interactive. In a non-modal flow the sheet dialogs order themselves with local values inside the switcher's isolated flow wrapper (DEC-1); the page-level value that wrapper carries remains a `spec:AST-027` conformance gap. | DEC-1; `spec:AST-027` FR2, FR4, FR8                      |
+| FR6 | The active child purpose governs implicit dismissal: `info` allows Escape, scrim click, and swipe; `form` allows Escape; `required` blocks all three and exposes `alertdialog`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current BottomSheet docs and switcher tests              |
+| FR7 | While visible, the switcher participates in `family:overlay-dismissal`; one Escape or platform close request reaches only the topmost present layer, and descendants receive a deeper logical layer scope.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `family:overlay-dismissal` and the audit regression test |
+| FR8 | One backdrop paints the flow's scrim at a time: the retained sheet's dialog keeps it through a handoff and the entering dialog takes it over without a fade when the retained dialog closes. A stale gesture from an outgoing sheet cannot change the flow's scrim, and unmounting a retained sheet cannot keep its dialog open or the flow's modal layer held.                                                                                                                                                                                                                                                                                                                             | DEC-1; current tests                                     |
+| FR9 | The switcher forwards neutral dialog attributes, styling inputs, and composed handlers, `onCancel` included, to every sheet dialog, so a handler fires for whichever sheet dialog raises the event; renders `id` and `data-testid` on the host dialog only, so each appears once in the document; attaches its ref to the host dialog; and preserves its owned ARIA and dismissal behavior. An object ref's `current` is never `null` while a sheet is mounted. A callback ref follows React's semantics on a handoff: a cleanup it returned runs when it detaches from the old host; a callback ref without a cleanup is called with `null` on detach, then with the new host.             | DEC-1, DEC-2; `architecture:public-component-api` INV8   |
 
 ### Allowed variation
 
@@ -111,17 +110,13 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ### Representative states
 
-Where a state names a sheet's own dialog, the retained dialog, or the flow
-wrapper, the shipped switcher meets it with its one shared dialog instead; FR2
-and FR5 record that implementation gap.
-
 | State      | Required invariant                                                                                                                                                               | Allowed variation                                                                        |
 | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | Closed     | Every sheet dialog is closed and no child is interactive.                                                                                                                        | Child panels may remain mounted but hidden.                                              |
 | First open | Matching child is visible and interactive in its own dialog.                                                                                                                     | Child-owned height and content.                                                          |
 | Handoff    | Entering child is interactive in its own dialog; retained child's dialog stays open, inert, and hidden from accessibility APIs until it fades, and keeps painting the one scrim. | Alignment offset depends on measured panel geometry.                                     |
 | Closing    | Outgoing child is retained inert while exit motion completes; modal focus and scroll ownership remain until close.                                                               | Theme-controlled duration.                                                               |
-| Modal      | Native modal host, backdrop, native focus containment, and the page scroll lock are active. Implementation gap: a script focus trap runs on top of the native containment.       | Active child's `purpose` controls implicit dismissal.                                    |
+| Modal      | Native modal host, backdrop, native focus containment, and the page scroll lock are active.                                                                                      | Active child's `purpose` controls implicit dismissal.                                    |
 | Non-modal  | Native non-modal host has no backdrop or scroll lock and background content remains interactive.                                                                                 | The current clipping/stacking limitation is a conformance gap, not an allowed exception. |
 
 ### Transformation and precedence order
@@ -140,8 +135,7 @@ and FR5 record that implementation gap.
   Native modality holds across a modal flow's child handoffs because a sheet
   dialog is modal throughout, and the one page scroll lock is held for the
   whole flow rather than per step. A non-modal flow paints no backdrop and
-  holds no lock. Implementation gap: one shared dialog is presented
-  throughout, so a handoff has one dialog open, not two.
+  holds no lock.
 - **PR2 — Stable child registration.** Parent rerenders and changing consumer ref
   identities do not unregister a mounted child or cancel an active handoff.
 
@@ -157,11 +151,11 @@ and FR5 record that implementation gap.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                                                                                                           | Representation authority                                         | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | -------------- | ------------------ |
-| Shared dialog    | Transparent host for the flow's interaction and accessibility boundary, one per child sheet (DEC-1). Implementation gap: one such host serves the whole flow | Current source and public docs; DEC-1 for the per-sheet clause   | Structural     | FR2, FR5, AR1      |
-| Sheet panels     | Delegate visible panel, content, handle, and gesture presentation to BottomSheet                                                                             | `component:BottomSheet` as observational context                 | Prominent      | FR1, FR3           |
-| Scrim            | Optional native backdrop that dims and blocks the page in modal presentation; one sheet dialog paints it at a time (DEC-1)                                   | Current source and public docs; DEC-1 for the one-painter clause | Supporting     | FR5, FR8           |
+| Anatomy or state | Design requirement                                                                                                         | Representation authority                                         | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------- | ------------------ |
+| Sheet dialogs    | Transparent per-sheet hosts; the active sheet's is the flow's interaction and accessibility boundary (DEC-1)               | Current source and public docs; DEC-1 for the per-sheet clause   | Structural     | FR2, FR5, AR1      |
+| Sheet panels     | Delegate visible panel, content, handle, and gesture presentation to BottomSheet                                           | `component:BottomSheet` as observational context                 | Prominent      | FR1, FR3           |
+| Scrim            | Optional native backdrop that dims and blocks the page in modal presentation; one sheet dialog paints it at a time (DEC-1) | Current source and public docs; DEC-1 for the one-painter clause | Supporting     | FR5, FR8           |
 
 ### Theming anatomy
 
@@ -169,9 +163,9 @@ and FR5 record that implementation gap.
 
 ```json
 {
-  "Shared dialog": {
+  "Sheet dialogs": {
     "none": {
-      "reason": "intentional: The transparent dialog is hosting, positioning, event, and focus machinery rather than a stable painted part."
+      "reason": "intentional: The transparent dialogs are hosting, positioning, event, and focus machinery rather than a stable painted part."
     }
   },
   "Sheet panels": {
@@ -179,7 +173,7 @@ and FR5 record that implementation gap.
   },
   "Scrim": {
     "none": {
-      "reason": "reachability-gap: The switcher-coordinated native backdrop paints the scrim but has no current public theming target."
+      "reason": "reachability-gap: The native backdrop of the sheet dialog that owns the scrim paints it but has no current public theming target."
     }
   }
 }
@@ -199,12 +193,12 @@ and FR5 record that implementation gap.
 
 ## Verification map
 
-| Contract         | Verification                                                                                                            | Representative states                                                                                                  | Mutation or failure expectation                                                                                                                                              | Audit section                             |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
-| FR1–FR4, FR8     | `BottomSheetSwitcher.test.tsx`                                                                                          | closed, first open, handoffs in either completion order, rapid replacement, unmount, close                             | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks.                            | `audit:BottomSheetSwitcher/behavior`      |
-| FR5–FR7, AR1–AR3 | `BottomSheetSwitcher.test.tsx`; `BottomSheetNativeModal.a11y.browser.spec.ts` (implementation gap: not yet in the tree) | modal/non-modal, info/form/required, nested layer, IME, focus return, scroll lock in engines, non-modal local ordering | Modality, dismissal order, naming, inertness, scroll lock, or focus behavior diverges, or a sheet dialog takes a page-level z-index.                                         | `audit:BottomSheetSwitcher/accessibility` |
-| FR9              | `BottomSheetSwitcher.test.tsx`; export checks                                                                           | ref across open/handoff/close/unmount, callback-ref cleanup, `id` once, DOM/ARIA/data/events, class, style, xstyle     | A supported input is dropped or duplicated, an object ref is null while a sheet is mounted or skips a cleanup, or an input overrides component-owned semantics accidentally. | `audit:BottomSheetSwitcher/api`           |
-| Theming anatomy  | `scripts/check-knowledge.mjs`; theming tests                                                                            | dialog, delegated sheet panel, scrim                                                                                   | A non-painting host gains a target, a delegated panel loses its owner, or the scrim gap disappears without review.                                                           | `audit:BottomSheetSwitcher/theming`       |
+| Contract         | Verification                                                                  | Representative states                                                                                                  | Mutation or failure expectation                                                                                                                                              | Audit section                             |
+| ---------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| FR1–FR4, FR8     | `BottomSheetSwitcher.test.tsx`                                                | closed, first open, handoffs in either completion order, rapid replacement, unmount, close                             | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks.                            | `audit:BottomSheetSwitcher/behavior`      |
+| FR5–FR7, AR1–AR3 | `BottomSheetSwitcher.test.tsx`; `BottomSheetNativeModal.a11y.browser.spec.ts` | modal/non-modal, info/form/required, nested layer, IME, focus return, scroll lock in engines, non-modal local ordering | Modality, dismissal order, naming, inertness, scroll lock, or focus behavior diverges, or a sheet dialog takes a page-level z-index.                                         | `audit:BottomSheetSwitcher/accessibility` |
+| FR9              | `BottomSheetSwitcher.test.tsx`; export checks                                 | ref across open/handoff/close/unmount, callback-ref cleanup, `id` once, DOM/ARIA/data/events, class, style, xstyle     | A supported input is dropped or duplicated, an object ref is null while a sheet is mounted or skips a cleanup, or an input overrides component-owned semantics accidentally. | `audit:BottomSheetSwitcher/api`           |
+| Theming anatomy  | `scripts/check-knowledge.mjs`; theming tests                                  | dialog, delegated sheet panel, scrim                                                                                   | A non-painting host gains a target, a delegated panel loses its owner, or the scrim gap disappears without review.                                                           | `audit:BottomSheetSwitcher/theming`       |
 
 ## Decision log