diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.md index 2337776fbf560..28bfd7ec63cea 100644 --- a/packages/core/src/BottomSheet/BottomSheet.spec.md +++ b/packages/core/src/BottomSheet/BottomSheet.spec.md @@ -9,7 +9,7 @@ superseded_by: null approved_by: cixzhang approved_at: 2026-10-24 owners: [cixzhang] -review_triggers: [theming, layout, public-api] +review_triggers: [theming, layout, public-api, behavior, accessibility] verified_by: [ packages/core/src/BottomSheet/BottomSheet.test.tsx, @@ -30,7 +30,15 @@ architecture: architecture:layer-runtime, ] contributing: [] -system_specs: [spec:AST-025, spec:AST-099] +system_specs: + [ + spec:AST-025, + spec:AST-099, + spec:AST-027/FR8, + spec:AST-017/FR7, + spec:AST-017/FR25, + spec:AST-020, + ] --- # BottomSheet component contract @@ -39,20 +47,52 @@ system_specs: [spec:AST-025, spec:AST-099] BottomSheet presents caller-provided content in a panel that rises from the bottom edge. This record covers consumer anatomy, the native dialog every sheet -renders, keyboard-reachable scrolling, theming reachability, and the Content -area's container padding. Where the shipped sheet does not yet meet a -requirement, the row carries a present-tense implementation gap note. +renders, keyboard-reachable scrolling, theming reachability, the Content area's +container padding, and how standalone sheets relate to one another: modal +sheets form one stack per document ordered by when they opened, a sheet that +closes in the same update another opens is replaced by it with one handoff +motion, and non-modal sheets are hosted in the browser's top layer (DEC-2). +Multi-step flows are written as one standalone sheet per step driven by one +state value; `BottomSheetSwitcher` is the deprecated predecessor of that +pattern (`component:BottomSheetSwitcher` DEP-0015). Where the shipped sheet +does not yet meet a requirement, the row carries a present-tense implementation +gap note. ## Compatibility and migration - Released default preserved: `yes`; with no `padding` prop and no theme padding, the Content area insets by `--spacing-4` on every logical edge, and `padding={0}` keeps an unpadded Content area -- Compatibility class: records the shipped anatomy, padded Content area, and - native dialog; no public prop, default, or export changes -- Controlled/uncontrolled behavior: unchanged -- Migration decision: none; the precedence rule under Transformation and - precedence order is the whole contract +- Compatibility class: no public prop, type, default, or export changes. + Stacking, the replace handoff, and non-modal top-layer hosting are behavior + of the existing component, tagged `[feat]` (`spec:AST-017/FR7`: a compatible + capability) and admissible in a patch under `spec:AST-017/FR25` as + additive — no released contract described two presented sheets, so the stack + gives behavior to a state no contract covered — and as + implementation-equivalent for a sheet on its own: a modal sheet presented on + its own behaves as released (focus on open wherever the engine's + `showModal()` focusing steps put it — in Chromium the panel, a + `data-autofocus` descendant notwithstanding; in Firefox the first focusable + control in the content), and a non-modal sheet on its own keeps its + documented contract (no scrim, no scroll lock, page interactive, dismissal + by `purpose`, `finalFocusRef` focused after every close, the element focused + when it was shown focused again when it closes while focus is inside it, and + focus on open where that engine's `show()` focusing steps put it — the panel + in Chromium, the first control in Firefox, likewise) + while its host changes from `show()` with a page-level `z-index` to the top + layer with none (FR11). One exception, visual only: under + `prefers-reduced-motion: reduce` a lone sheet's entrance and exit follow + FR15 (no transform travel; a cross-fade on a coarse pointer or after a + touch drag's release, an immediate change otherwise) where the released + motion ran its transforms shortened — a motion change under a preference, + no change to any state, event, or focus outcome. Two modal sheets open at + once stack (FR5) instead of presenting as unrelated dialogs that each dim + the page +- Controlled/uncontrolled behavior: unchanged; `isOpen` stays fully controlled, + and a sheet never writes another sheet's state (FR8) +- Migration decision: none for callers of BottomSheet. Flows written with + `BottomSheetSwitcher` migrate to standalone steps under + `component:BottomSheetSwitcher` DEP-0015 Consumer migration instructions belong in consumer docs and release notes. @@ -68,6 +108,12 @@ Consumer migration instructions belong in consumer docs and release notes. - Standalone sheet presentation, including its optional native-dialog Scrim. - The native dialog every sheet renders, standalone or switcher-managed (`component:BottomSheetSwitcher` DEC-1). +- The stack of presented modal sheets in one document: their order, which one + is on top, how far a covered sheet recedes, which backdrop paints the one + scrim, and the native top-layer order that realizes it (FR5–FR7, DEC-2). +- The replace handoff between a sheet closing and a sheet opening in the same + update (FR9–FR10). +- The top-layer hosting of a non-modal sheet (FR11). **Does not own / non-goals** @@ -76,28 +122,53 @@ Consumer migration instructions belong in consumer docs and release notes. `main`. - The presentation lifecycle of its dialog and the flow's scrim ownership when the sheet participates in a BottomSheetSwitcher — owned by BottomSheetSwitcher - (`component:BottomSheetSwitcher` DEC-1). -- Shared layer hosting or dismissal policy. + (`component:BottomSheetSwitcher` DEC-1). The flow as a whole is one level of + the stack (FR12). +- Shared layer hosting or dismissal policy. The Escape and platform-close order + is `family:overlay-dismissal`'s; the stack only tells it which sheet can + take a close request (FR7). +- Which `Dialog`, `Drawer`, `Popover`, or other layer paints above a sheet; + those keep their own hosting (`architecture:layer-runtime`). A `Dialog` + opened from a sheet is not a stack level. ## Public concepts -No new public concept is introduced. Consumer props and usage remain documented -in `BottomSheet.doc.mjs`. +No new public concept is introduced. Stacking and the replace handoff are +behavior of the existing `isOpen` / `onOpenChange` contract: a sheet opened +while another modal sheet is open stacks on it; a sheet that closes in the same +update as one other sheet opens, from a control inside it, is replaced by it. +There is no stack component, context, or opt-in prop. Consumer props and usage +remain documented in `BottomSheet.doc.mjs`. ## Behavioral and layout contract -| ID | Invariant | Basis | -| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation. | Current source, docs, and tests | -| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target. | Current source, docs, and tests | -| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; tests | -| FR4 | The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher. | `architecture:container-padding` | +| ID | Invariant | Basis | +| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation. | Current source, docs, and tests | +| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target. | Current source, docs, and tests | +| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; tests | +| FR4 | The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher. | `architecture:container-padding` | +| FR5 | Modal sheets presented in one document form one stack ordered by open order: the sheet opened most recently is on top; sheets opening in one update are ordered by tree order (a sheet before the sheets rendered in its content, siblings in source order), and the first painted frame already shows that order. Only sheets of one document stack. Implementation gap: on current `main` two open modal sheets are unrelated native dialogs ordered by effect timing, and a deep link that opens a sheet and a sheet in its content in one update paints the inner sheet beneath its parent. | DEC-2 | +| FR6 | A covered modal sheet stays mounted with its state, recedes behind the top sheet, and is blocked: the browser's modal rules block it, and when it contains no presented sheet it is also `inert` and `aria-hidden`. Exactly one backdrop is visible for a stack — the bottom open sheet's — and a change of scrim owner lands with no transition, so the page dim is constant through a push, a pop, and a handoff. Implementation gap: on current `main` every open modal sheet paints its own backdrop and nothing recedes. | DEC-2 | +| FR7 | Escape, a scrim tap, a swipe, and a platform close request reach only the top sheet of a stack, through that sheet's own `onOpenChange` and `purpose`; a covered sheet, and a replaced sheet during its handoff, report themselves absent to the shared `family:overlay-dismissal` stack while that lasts, so the order among sheets is the sheet stack's and the shared stack stays one registry. Implementation gap: on current `main` a covered sheet reports itself present (its dialog is open) and the shared dismissal stack ranks tree depth first, so a covered sheet nested in another sheet's content receives Escape ahead of a later sheet opened outside it. | DEC-2; `family:overlay-dismissal/FR2`, `/FR3` | +| FR8 | A sheet rendered in another sheet's content is presented only while its host is open: it leaves the top layer with its host and is presented again, on top, if its own `isOpen` is still true when the host reopens. Its `isOpen` is never written by the host. Implementation gap: on current `main` a nested sheet stays open in the top layer with no visible box when its host closes from code. | DEC-2 | +| FR9 | Closing the top sheet returns focus into the sheet it reveals: to the element that opened the closing sheet when that element is inside the revealed sheet, else to the revealed sheet's panel; an explicit `finalFocusRef` outside the revealed sheet yields to its panel in the same way. The last sheet of a stack keeps the standalone rule: `finalFocusRef`, else the opener. Closing every sheet of a stack in one update returns focus once, to the bottom sheet's `finalFocusRef` or opener, after the last dialog has closed. A close driven by the stack itself never moves focus. Implementation gap: on current `main` closing several sheets in one update leaves focus on `body`. | DEC-2 | +| FR10 | When exactly one standalone sheet closes and exactly one opens in the same update, both of one document and one modality, the closing sheet was the top sheet of its group — its document's modal stack, or, for non-modal sheets, the one open non-modal sheet (FR11) — with the opening sheet set aside, neither dialog contains the other, and the actor — the control last pressed, or, with no fresh press, the element focused when the update began — is inside the closing sheet's dialog or is none (no fresh press, and nothing or only the document body focused, as when code changes the step while focus has fallen to the body), the opening sheet replaces the closing one: it enters above the retained sheet; a retained sheet whose top edge is above the entering sheet's resting top edge moves down to meet it at the same time; the retained sheet fades only after both motions complete; it is `inert` and `aria-hidden` from the first frame and takes no dismissal request; the scrim owner is FR6's, the bottom open sheet: when the retained sheet is that owner (a replace at the bottom of the stack) its backdrop keeps the one visible scrim until it leaves and the entering sheet's backdrop takes over with no transition, and when the replace runs above a covered sheet that sheet stays the owner and the retained sheet's backdrop is transparent throughout, so it only fades; focus moves into the entering sheet; and the entering sheet adopts the retained sheet's focus-return target, so closing the flow returns focus to its first opener. A close and an open that fail any condition — different updates, a covered sheet closing, several sheets changing, a sheet closing with its host, or a control outside the closing sheet acting — keep the ordinary push and pop motion and their own focus return. Implementation gap: on current `main` a same-update close and open is a pop beneath a push. | DEC-2 | +| FR11 | A non-modal sheet (`hasScrim={false}`) is presented in the browser's top layer as a manual popover with no backdrop, no scroll lock, and no focus trap, and carries no page-level `z-index`; where the Popover API is absent it is presented with `show()` in page stacking order as a reduced fallback. A non-modal sheet shown while a modal dialog that does not contain it is open (a modal sheet, a `Dialog`) is inert under that modal, so it does not enter the top layer yet — there it would paint above the modal while a press on it lands on the modal — and is presented with `show()` beneath the modal, with no page-level `z-index`; a modal on its way out (inert, hidden) counts as gone. Once no such modal is open the sheet enters the top layer as a manual popover, a top-layer toast viewport re-entering above it (FR14), so page content never paints over an interactive non-modal sheet (`spec:AST-027` FR8). A non-modal sheet rendered inside the modal's content is not inert and enters the top layer at once. Non-modal sheets never stack, recede, or own a scrim, and never pair with a modal sheet; because they never stack, the one open non-modal sheet of a document is always the top of its own group, so two non-modal sheets replace each other under FR10 — the closing one being that top — with no backdrop. On a lone open, focus goes where the engine's own `show()` focusing steps would put it when they enter the sheet, and no `data-autofocus` preference is added over them (the released behavior, kept, and the same rule as a modal sheet's `showModal()`): in Chromium the panel, whose focusing steps take the first focusable area including a `tabindex="-1"` container; in Firefox the first focusable control in the content, which is the `data-autofocus` field only when it comes first; in WebKit wherever its `show()` lands. Where the manual-popover host's own focusing steps would land elsewhere than that engine's `show()` (Chromium's `showPopover()` lands on the first control), focus arrives where `show()` would have put it without passing through any control — no control receives a focus or a blur on the way, so a field validating on blur does not fire on open; when the sheet is replacing the sheet the person was in, it takes focus, and a `data-autofocus` descendant then wins (AR4). On close an explicit `finalFocusRef` is focused wherever focus is, and otherwise the element focused when the sheet was shown is focused again only while focus is still inside the sheet — the native dialog's own return rule, kept. Implementation gap: on current `main` a non-modal sheet is presented with `show()` and a page-level `z-index: 1000`; its focus on open (the engine's `show()` focusing steps, which land on the panel in Chromium and on the first control in Firefox) and its focus return (`finalFocusRef` after every exit, the native return to the element focused at `show()` while focus is inside) already match this row. | DEC-2; `spec:AST-027/FR8`; `architecture:layer-runtime` | +| FR12 | A modal `BottomSheetSwitcher` flow is one level of the stack: the dialog of its active step is the flow's level, keeps the flow's rank across the flow's own handoffs, recedes and is blocked when covered, yields its backdrop to the stack's scrim owner, stands down from dismissal while covered, and returns focus by FR9. A standalone sheet rendered in a step's content stacks above the flow and leaves with the step (FR8). A switcher step is never paired under FR10. Implementation gap: on current `main` a switcher flow and a standalone sheet open together are unrelated dialogs. | DEC-2; `component:BottomSheetSwitcher/DEC-1` | +| FR13 | Every open scrim sheet supplies its dialog as a passive global outlet for app-global surfaces such as toasts (`spec:AST-003` FR18: each active native modal, a covered sheet included), and a modal `BottomSheetSwitcher` flow supplies its active step's dialog — the one its host dialog resolves to, following each handoff; the retained step's dialog, inert and fading, never hosts. Among sheets, the latest outlet — the one a global host renders into — follows the stack's order, not the order the sheets were supplied in: the top sheet is the latest, so a toast lands in the top sheet and never in a covered, inert one, and when the top sheet closes the sheet it reveals is the latest again and takes the host back. A sheet is raised only among sheet outlets: an outlet supplied later by another modal (a `Dialog` opened from a sheet) stays above every sheet until it closes. A sheet, or a flow, stops supplying as soon as it starts closing, and a native `close` event that fires while its dialog is open again (the stack re-showing it, or a reopen during its exit) does not take its outlet away. Implementation gap: on current `main` the latest outlet is the one supplied last, so a sheet re-shown or revealed by its stack is not it, and a switcher flow supplies no outlet, so a toast raised from a step lands behind the flow. | DEC-2; `spec:AST-003/FR16`, `/FR18`; `architecture:layer-runtime`; `component:BottomSheetSwitcher/FR10` | +| FR14 | When a non-modal sheet enters the top layer, a top-layer toast viewport shown before it leaves and re-enters the top layer in place, keeping focus inside it, so toasts paint above the sheet. Implementation gap: on current `main` a non-modal sheet is not a top-layer surface (`show()` under a page-level `z-index`, beneath the popover viewport), so the toast viewport's re-entry above a non-modal sheet has nothing to answer. | DEC-2; `architecture:layer-runtime` | +| FR15 | Under `prefers-reduced-motion: reduce` the recede, the return from receded, a push's entrance, a pop's exit and the replace handoff — and a `BottomSheetSwitcher` step's, which shares the sheet panel's motion — follow `design:reduced-motion`, keyed on its queries (`prefers-reduced-motion: reduce`, with `pointer: coarse` for the cross-fade): no transform motion runs (DR1) — a covered sheet appears in its receded place and size the frame the push lands and returns the same way, the entering sheet appears in its final place, the retained sheet does not align down; on a coarse pointer the entering sheet fades in and the leaving or retained sheet fades out where it is, opacity only, in 200 ms or less (DR2); a dismissal the release of a touch drag started (a swipe past the dismiss line) fades out in place the same way on every pointer (DR2's drag-release clause); on any other pointer every other change is immediate (DR3); the handoff's steps run in the released order, so the retained sheet is hidden and its dialog closed once its fade ends. The constant page dim through a push, a pop and a handoff (FR6) holds as it does with motion. Implementation gap: on current `main` there is no recede or handoff between standalone sheets, and the shipped sheet's own entrance and exit under reduced motion run their transforms shortened on every pointer and do not cross-fade on a coarse pointer. | DEC-2; `design:reduced-motion` | ### Allowed variation - Caller-provided children may vary without becoming BottomSheet-owned anatomy. - Height, snap points, motion phase, and standalone versus switcher hosting may vary without changing the four-part anatomy recorded here. +- The recede geometry of a covered sheet (its scale and offset per depth), the + handoff motion curve, and the order in which the entering and alignment + motions of a replace complete may vary under theme motion tokens while FR6 + and FR10's ordering and inertness hold. ### Representative states @@ -107,12 +178,34 @@ in `BottomSheet.doc.mjs`. - A switcher-managed sheet renders the same panel anatomy in its own dialog while BottomSheetSwitcher coordinates that dialog's lifecycle and the flow's one Scrim (`component:BottomSheetSwitcher` DEC-1). +- Stacked: two or more modal sheets presented in one document; the top sheet is + interactive, each covered sheet is receded and blocked, one Scrim is visible. +- Replacing: a retained sheet and an entering sheet both presented through the + handoff, the retained one inert — still painting the Scrim when it is the + bottom open sheet (FR6), transparent when a covered sheet beneath owns it — + then only the entering sheet. +- Non-modal: a sheet presented as a manual popover in the top layer with no + Scrim; the page remains interactive. +- Reduced motion: the Stacked and Replacing states above with no transform + motion — the covered sheet in its receded place at once, the entering and + leaving sheets cross-fading on a coarse pointer and changing at once on any + other, except a dismissal a touch drag's release started, which fades out in + place on every pointer (FR15, `design:reduced-motion`). ### Transformation and precedence order - Content area inset: the `padding` prop, then the theme's `padding` properties on `bottom-sheet`, then `--spacing-4` on every logical edge. -- No new height, gesture, or motion precedence rule is introduced. +- Stack order: open order, then tree order for sheets opening in one update + (FR5). A sheet that closes and reopens takes a new place on top. +- Native top-layer order is derived from the stack order, not trusted: where + the order the dialogs were shown in diverges from the stack order, the + stack order holds in the first painted frame (FR5), and no dialog below the + first divergence is presented again — a sheet whose place is already right + fires no native `close`. +- A same-update close and open is tested against FR10 in that order of + conditions; the first failing condition makes it a push and a pop. +- No new height or gesture precedence rule is introduced. ### Performance and resources @@ -132,6 +225,15 @@ in `BottomSheet.doc.mjs`. each is an open gap. - Elements a presenting component adds beyond this frame are its own to justify. +- **PR1 — One stack per document.** Sheets rendered by every copy of the + package loaded on a page, and by every React root on it, form one stack per + document: their order is their open order, whichever copy or root rendered + them. No public API reaches the ordering. +- **PR2 — No per-level backdrop cost.** A stack paints one visible backdrop + whatever its depth — the scrim owner's, the bottom open sheet's under FR6 — + and every other backdrop in the stack, a covered sheet's or a sheet's above + the owner, is transparent, not removed (a switcher flow's dialogs likewise, + `component:BottomSheetSwitcher` FR10). ## Accessibility contract @@ -143,15 +245,57 @@ in `BottomSheet.doc.mjs`. - **AR2 — Focus continuity.** Content, overflow, or eligibility changes MUST NOT move focus. Pointer/programmatic body focus never delegates. A focused body losing overflow remains programmatically focusable. +- **AR3 — Covered and replaced sheets are not exposed.** A covered sheet that + contains no presented sheet, and a replaced sheet through its handoff, are + `inert` and `aria-hidden="true"`; the top or entering sheet is the only + exposed dialog. A covered sheet that contains the top sheet is left alone, + because the top sheet's modality already excludes it (FR6, FR10). Each + sheet keeps its own role and accessible name; a non-modal sheet's manual + popover host changes neither. Implementation gap: on current `main` a + covered sheet is exposed as an open dialog. +- **AR4 — Focus follows the person through a stack.** Opening the top sheet + moves focus into it; a replace moves focus into the entering step whatever + the native host did; a pop returns focus into the revealed sheet; the last + close and a close of the whole stack return focus by FR9. A sheet opened on + its own, modal or not, focuses wherever the engine's native focusing steps + land when the released host presents it, with no `data-autofocus` + preference added (the released behavior): in Chromium the panel, in Firefox + the first focusable control in the content (a `data-autofocus` field when + it comes first), in WebKit wherever its steps land; a non-modal sheet's + manual-popover host lands where that engine's `show()` would have (FR11). The one deliberate + exception is a sheet entering as a replacement (FR10), whose focus is + placed after the native focusing steps because they may have left it in the + replaced sheet, or on the entering panel: there a `data-autofocus` descendant is focused first, else + the panel, so a step flow that opens on a field keeps the keyboard on it. Implementation gap: on current `main` a pop returns focus to the + element the closing dialog recorded, which may be inside a sheet that is + itself closing. + +- **AR5 — What assistive technology perceives of a push, a pop, and a + replace.** The stack adds no announcement of its own to a push or a pop: + it fires no live region, so focus entering the top sheet (push) or + returning into the revealed sheet (pop, FR9) is what a screen reader + reports, and the covered sheet is hidden meanwhile (AR3). Messages the + sheets' own content owes are not the stack's and are delivered by their + owners' rules — a message pending in a closing sheet reaches the person + through the sheet revealed beneath it (`spec:AST-086` FR14). A replace is perceived as focus + entering the new step: focus lands on the entering step's `data-autofocus` + field or else its panel (AR4), so the entering dialog's accessible name is + announced as focus enters it, and the retained step is hidden from the + first frame of the handoff (AR3); the stack announces nothing of the + retained step's leaving. Implementation gap: on current `main` a covered sheet stays + exposed and a flow's steps are not standalone sheets, so a push is + perceived as a second open dialog. ## Design relationships -| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract | -| ---------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ | -| Sheet panel | Presents the painted bottom-edge surface and owns panel geometry and motion. | Current source and public docs | Prominent | FR1, FR2 | -| Content area | Provides the scrolling, inset area for caller-provided sheet content. | Current source and tests | Prominent | FR1, FR2, FR4 | -| Handle | Presents the decorative grab affordance and owns the panel's drag interaction region. | Current source and tests | Supporting | FR1, FR2 | -| Scrim | Dims and blocks the page in a scrim-backed host. | Current source and public docs | Supporting | FR1, FR2 | +| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ | +| Sheet panel | Presents the painted bottom-edge surface and owns panel geometry and motion. | Current source and public docs | Prominent | FR1, FR2 | +| Content area | Provides the scrolling, inset area for caller-provided sheet content. | Current source and tests | Prominent | FR1, FR2, FR4 | +| Handle | Presents the decorative grab affordance and owns the panel's drag interaction region. | Current source and tests | Supporting | FR1, FR2 | +| Scrim | Dims and blocks the page in a scrim-backed host; one is visible for a stack. | Current source and public docs | Supporting | FR1, FR2, FR6 | +| Covered sheet | Recedes behind the top sheet (a small scale-down and upward offset per depth, the second step shared by every deeper sheet) and is blocked. | DEC-2 | Supporting | FR6 | +| Replaced sheet | Holds its place or aligns down to the entering sheet, then fades; keeps the Scrim until it leaves when it is the bottom open sheet (FR6). | DEC-2 | Supporting | FR10 | Content area, Handle, and Scrim are stable visible parts, but no current public target reaches them. Their `none` dispositions record factual reachability, not @@ -194,20 +338,39 @@ a decision that they must remain unthemeable. automatic keyboard-owner selection, and focus continuity. - BottomSheet's on-screen keyboard behavior is owned by `spec:AST-099`. - `family:overlay-dismissal` owns shared Escape and platform-close ordering. A - standalone BottomSheet registers with the shared stack while it is presented; - a switcher-hosted sheet is covered by BottomSheetSwitcher's registration. + standalone BottomSheet registers with the shared stack while it is presented + and reports itself absent while covered or replaced (FR7); a switcher-hosted + sheet is covered by BottomSheetSwitcher's registration. +- `spec:AST-027` FR8 owns top-layer hosting for non-modal surfaces; a + standalone non-modal sheet's manual-popover host satisfies it (FR11), and no + page-level band remains on that path. +- `architecture:layer-runtime` owns the private outlet registry and the toast + viewport's hosting; FR13 and FR14 here own only how sheets take part in + them (which sheet is the latest outlet, and the toast viewport's re-entry + above a non-modal sheet), + and that record states the shipped behavior once it ships. +- `spec:AST-017` FR7 gives stacking, the replace handoff, and the non-modal + host their `[feat]` tag and FR25 admits them in a patch (additive and + implementation-equivalent); FR26–FR29 govern the switcher's deprecation + under `component:BottomSheetSwitcher` DEP-0015. +- `component:BottomSheetSwitcher` DEC-1 owns a flow's own handoff and the + presentation of its step dialogs; FR12 here owns only the flow's place as a + level of the stack. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------- | -| FR1 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites | Modal, non-modal, and switcher presentations | Removing a documented part fails existing content, structure, or dismissal assertions. | `audit:BottomSheet/anatomy` | -| FR2 | Panel target assertion, source inspection, and theming target inventories | Sheet panel, Content area, Handle, and Scrim | Removing the panel target or documenting an unshipped child target fails evidence or inventory. | `audit:BottomSheet/theming` | -| FR3, AR1–AR2 | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` | -| Layout evidence | `BottomSheetPanel.test.tsx` | Floating Handle and scrolling Content area | Reordering or merging the stable parts fails existing panel structure and style assertions. | `audit:BottomSheet/anatomy` | -| FR4 | `BottomSheetPanel.test.tsx` container padding tests; `derivedVarRegistry.test.ts` | default, `padding` prop, theme `padding`, lone padded Section child | The published inset differs from the applied padding, or a lone padded Section changes geometry. | `audit:BottomSheet/anatomy` | -| Element jobs | Open-sheet element count test against the named job list | modal and non-modal sheet, scrim and no scrim | An element in the open sheet's frame with no named job, or a named job with no element | -| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:BottomSheet/theming` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | +| FR1 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites | Modal, non-modal, and switcher presentations | Removing a documented part fails existing content, structure, or dismissal assertions. | `audit:BottomSheet/anatomy` | +| FR2 | Panel target assertion, source inspection, and theming target inventories | Sheet panel, Content area, Handle, and Scrim | Removing the panel target or documenting an unshipped child target fails evidence or inventory. | `audit:BottomSheet/theming` | +| FR3, AR1–AR2 | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` | +| Layout evidence | `BottomSheetPanel.test.tsx` | Floating Handle and scrolling Content area | Reordering or merging the stable parts fails existing panel structure and style assertions. | `audit:BottomSheet/anatomy` | +| FR4 | `BottomSheetPanel.test.tsx` container padding tests; `derivedVarRegistry.test.ts` | default, `padding` prop, theme `padding`, lone padded Section child | The published inset differs from the applied padding, or a lone padded Section changes geometry. | `audit:BottomSheet/anatomy` | +| Element jobs | Open-sheet element count test against the named job list | modal and non-modal sheet, scrim and no scrim | An element in the open sheet's frame with no named job, or a named job with no element | | +| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:BottomSheet/theming` | +| FR5–FR9, FR12–FR15, AR3–AR5 | Stacking unit suite (jsdom, native dialog methods stubbed); real-browser per-frame sampling of transforms, backdrop opacity, hit-testing, and focus on the stacking stories in Chromium, WebKit, and real Safari; a real-browser accessibility-tree check (`spec:AST-020`, `spec:AST-009` FR3) that a lone sheet, a stack of two and three, and a replace handoff expose exactly one `dialog`, the top or entering sheet, with its name, while covered and replaced sheets are hidden, that the stack renders no live region of its own, and that focus enters the entering step's `data-autofocus` field or panel on a replace; a real-browser run with reduced motion emulated on a fine and on a coarse pointer, sampling per frame that no transform animates, that the covered sheet is in its receded place from the frame the push lands, that on a coarse pointer the entering and leaving sheets change opacity only within 200 ms and on a fine pointer at once, that a swipe dismissal fades out in place on a fine pointer, that the dim is constant and that the handoff still completes | siblings, separate components, nested in content, inside a switcher step, a switcher flow as a level, out-of-tree-order opens, same-update deep link, depth 1–3, Escape/scrim/swipe/platform close, covered close, close of the whole stack, focus after each pop, two package copies, a second document | A covered or replaced sheet is exposed in the accessibility tree, the top sheet is exposed without role `dialog` or its name, a covered sheet stays interactive, a second backdrop paints, the dim dips or doubles on a handoff, a dismissal reaches a covered sheet, a nested sheet's state is written or it stays open invisibly, or focus lands on `body` after a pop or a close of the whole stack. Implementation gap: the suite does not exist on current `main`. | `audit:BottomSheet/behavior` | +| FR10–FR11 | Replace unit suite (jsdom); real-browser parity of the standalone flow against the switcher's handoff — per-frame transforms, opacity, page dim, focus, settled pixels — in Chromium and WebKit, and real Safari for hosting, dim, toast order, and focus; a per-engine lone-open focus probe in Chromium, Firefox and WebKit comparing the sheet's focus on open against that engine's bare `show()` and `showModal()` on the same markup, and recording the focus and blur events the sheet's first control receives on open (none) | push, pop, different updates, covered close, nested, a replace above a covered sheet (the bottom sheet keeps the scrim, the retained sheet only fades), switcher flow, a lone sheet; handoff in both completion orders; reversal mid-handoff in both directions and both tree orders; unrelated owners from a page control; non-modal replace, reversal, `show()` fallback; a non-modal sheet opened from a modal sheet or a `Dialog` and rendered outside it (while the modal is open, and once it has closed, with positioned page content), one opened in the update that closes a modal sheet, and one rendered inside the modal's content | A replace is recognized for unrelated owners or missed for a real step flow, the retained sheet is exposed or dismissable, the scrim dips, the replaced step stays on screen after a reversal, focus does not enter the step or return to the flow's opener, a non-modal sheet carries a page-level `z-index`, a toast paints under a non-modal sheet, or a lone sheet's focus on open, modal or not, differs from where that engine's released native host (`showModal()`, or `show()` for a non-modal sheet) puts it — in Chromium the panel, with a ring only after keyboard input and a `data-autofocus` field left unfocused; in Firefox the first focusable control — a control inside the sheet receives a focus or a blur on a lone open that `show()` would not have given it, or a replacement entry fails to focus its `data-autofocus` field. A non-modal sheet rendered outside an open modal paints above it while a press lands on the modal, or stays beneath page content once that modal has gone. Implementation gap: the suite does not exist on current `main`. | `audit:BottomSheet/behavior` | +| FR13–FR14 | Toast viewport hosting suite (jsdom, native dialog methods and popover state stubbed); real-browser hit-testing of a toast raised from the top sheet, from a Dialog opened from a sheet after an inner sheet closed, from a sheet re-shown by a reversal, and over a non-modal sheet | a lone sheet; a stack of two; sheet → Dialog → sheet → close the inner sheet; a reversal and a reopen during exit, with the stale native `close`; a non-modal sheet shown after the viewport; a modal switcher flow alone, through a handoff and its close; a flow stacked over a standalone sheet and a standalone sheet over a flow; a non-modal flow | A toast renders in a covered or inert sheet, a Dialog opened from a sheet loses the toast to the sheet beneath it, a re-shown sheet loses its outlet to the stale `close`, a toast raised from a switcher step lands behind the flow or in its retained step, or a toast paints beneath a non-modal sheet. Implementation gap: on current `main` the suite covers the lone sheet and Dialogs only. | `audit:BottomSheet/behavior` | Existing tests directly assert the Sheet panel target, Content area placement, Handle structure, and scrim behavior. Source and public target metadata confirm @@ -230,6 +393,45 @@ A real flow-root content box supplies the hook's observation seam while preservi representative margin, float, percentage-height, flex/grid-child, and hug-height behavior. +### DEC-2 — Sheets stack by open order and replace on a same-update switch + +**Reference:** `component:BottomSheet/DEC-2` +**Decider:** imdreamrunner, 2026-10-23 + +Every modal sheet keeps its own open state and its own native dialog. A sheet +opened while another modal sheet is open stacks on top of it: the stack is +ordered by open order with tree order deciding ties within one update, exactly +one backdrop is visible, covered sheets recede and are blocked, dismissal +reaches only the top sheet, and the native top layer is put in that order +before the first paint when the browser's own order would differ (FR5–FR7). +A sheet rendered in another sheet's content is part of it: it leaves and +returns with its host and its state stays the caller's (FR8). When the top +sheet closes in the same update that one other standalone sheet of the same +modality opens, from a control inside the closing sheet, the opening sheet +replaces it with the one handoff a step flow needs — entering above, the +retained sheet aligning down when taller and fading after both motions, one +steady scrim, focus into the entering step, the first opener kept for the +flow's close — so a multi-step flow is one standalone sheet per step and one +state value (FR10). Non-modal sheets are hosted in the top layer as manual +popovers, never stack, and replace each other the same way (FR11). A +`BottomSheetSwitcher` flow is one level (FR12). The ordering is one per +document across package copies and React roots (PR1), because the coordinated +thing — a document's top layer — is wider than any React tree. Nothing here is +public API; a lone modal sheet never notices the stack. +Rejected: an ordered list of steps on the switcher (`activeSheets`), because +it changes the switcher's public contract, requires every level of a flow to +live under one switcher, and cannot order a sheet opened from elsewhere. +Rejected: a `` provider or shared dialog that composes +levels, because a React context cannot reach a second root, a second copy of +the package, or a widget mounted outside it, while module-level singletons +already own document-wide facts here (the dismissal stack, the modal outlet +registry); the only scoping a provider adds is a "same level" boundary, which +FR10's actor condition supplies without a wrapper. +Rejected: a `stacked` or `replaces` prop to opt a sheet in, because a lone +sheet is unaffected and one state value already says what a flow means. +Rejected: a page-level `z-index` on a non-modal sheet to order a replace, +because `spec:AST-027` forbids a new band; the top layer orders it. + ## Open questions - **OQ1 — Should Content area, Handle, or Scrim gain a stable public theming diff --git a/packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md b/packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md index 37f9f488039bf..ea12679596e1c 100644 --- a/packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md +++ b/packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md @@ -27,7 +27,14 @@ architecture: architecture:public-component-api, ] contributing: [] -system_specs: [spec:AST-002, spec:AST-027] +system_specs: + [ + spec:AST-002, + spec:AST-027, + spec:AST-017/FR26, + spec:AST-017/FR28, + spec:AST-017/FR29, + ] --- # BottomSheetSwitcher component contract @@ -36,9 +43,21 @@ system_specs: [spec:AST-002, spec:AST-027] BottomSheetSwitcher coordinates a mutually exclusive sequence of BottomSheet children, each presented in its own native dialog (DEC-1), without adding a -prop or changing a default. Where the shipped switcher does not yet meet a -requirement, the row carries a present-tense implementation gap note. The -modality, identifier, and theming questions below stay open. +prop or changing a default. Its public lifecycle state is `deprecated` +(`spec:AST-017` FR26, DEC-3, DEP-0015): it is supported and maintained, every +requirement in this record stays in force, and the replacement — one standalone +`BottomSheet` per step driven by one state value, which `component:BottomSheet` +FR10 replaces in place when the step changes from inside the open step — is +what maintained docs, templates, stories, and agent guidance teach. Removal +happens only in a future declared minor through a `[breaking]` change. +Implementation gap: on current `main` no declaration carries `@deprecated`, the +switcher's consumer docs and `component:BottomSheet`'s consumer doc recommend +the switcher for multi-step flows, and the CLI block templates and Lab's +`MobileTokenizer` use it. Lab's `MobilePowerSearch` uses the switcher +and is migrated by its own change. Where the shipped +switcher does not yet meet a requirement, the row carries a present-tense +implementation gap note. The modality, identifier, and theming questions below +stay open. ## Compatibility and migration @@ -48,12 +67,45 @@ modality, identifier, and theming questions below stay open. motion a handoff follows `design:reduced-motion` (FR3), a visual-only motion change under `spec:AST-017` FR3. The element the `ref` resolves to, and that it changes on a handoff, is implementation rather than public - contract (DEC-2) + contract (DEC-2). A switcher flow presented on its own behaves as released, + with one fix: a toast raised from a step renders above the flow and can be + pressed (FR10, `component:BottomSheet` FR13), where it rendered behind the + flow before. + A switcher flow presented while other sheets are open is one level of the + stack `component:BottomSheet` FR12 describes; that is behavior of the stack, + not a change to the switcher's own contract +- Lifecycle: `deprecated` (DEC-3, DEP-0015). Deprecation adds no production + runtime behavior and no warning in a rendered application (`spec:AST-017` + FR29); the `@deprecated` metadata lives on the TypeScript declarations of + `BottomSheetSwitcher`, `BottomSheetSwitcherProps`, and `BottomSheet`'s + `sheetId`, and the consumer docs carry the replacement route (FR29a, FR29b). + Implementation gap: on current `main` the declarations carry no + `@deprecated` and the consumer docs carry no replacement route - Controlled/uncontrolled behavior: `activeSheet` remains fully controlled -- Migration decision: none +- Migration decision: DEC-3; the migration is DEP-0015's Consumer migration instructions belong in consumer docs and release notes. +### DEP-0015 — Deprecate `BottomSheetSwitcher` in favour of standalone step sheets + +| Field | Value | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id | `DEP-0015` | +| cleanup | none yet; the removal is decided for a future declared minor | +| package | `@astryxdesign/core` | +| surface | `BottomSheetSwitcher`, `BottomSheetSwitcherProps`, and the `sheetId` prop of `BottomSheet` | +| old contract | A multi-step flow is a `BottomSheetSwitcher` whose `activeSheet` names one nested `BottomSheet` by `sheetId`; stepping runs the handoff of FR2–FR3 and FR8 | +| replacement | One standalone `BottomSheet` per step with `isOpen={step === id}`, driven by one state value; closing the open step and opening the next in the same update, from a control inside the open step (or from code while focus is in it), runs the same handoff (`component:BottomSheet` FR10), for modal and `hasScrim={false}` flows alike. A step changed by a control outside the flow's sheets — a page control beside a non-modal flow, or code acting while focus is on a page control — is a close and an open with their own push and pop motion, where the switcher ran its handoff on any `activeSheet` change; code acting while focus is in the step or on the document body still runs the handoff (`component:BottomSheet` FR10's actor is inside the step, or none) | +| direct authority | DEC-3 here; `component:BottomSheet` DEC-2 and FR10 own the replacement's behavior. Owners: `cixzhang`, `imdreamrunner` | +| warning | `@deprecated` on the declarations; consumer docs, templates, stories, and release notes name the replacement. No runtime warning (`spec:AST-017` FR29) | +| migration | Ordered and testable, per flow: (1) replace `activeSheet` / `onActiveSheetChange` with one `step` value; (2) give each step `isOpen={step === 'id'}` and `onOpenChange={isOpen => !isOpen && setStep(current => (current === 'id' ? null : current))}` in place of `sheetId="id"`; (3) remove the wrapper, moving its `hasScrim` onto every step; (4) keep the step controls as they are (`setStep('next')`); (5) a flow stepped by a control outside its sheets (a page control beside a non-modal flow, or code acting while focus is on a page control) gets push and pop motion in place of the handoff — move such a control into the step, or accept the motion; code acting while focus is in the step or on the body keeps the handoff; (6) the switcher's other props: `onCancel` becomes a guarded `onOpenChange` on each step — one that ignores `false` while the flow must stay open — which keeps the step's dialog role; a standalone sheet reports Escape, the platform close, the scrim tap, and the swipe all as `onOpenChange(false)` with no reason, so the guard holds the step open against all of them while it applies, where the switcher's `onCancel` vetoed only the cancel request; a veto of Escape alone has no equivalent, and the only per-path lever is `purpose` (`form` keeps Escape and blocks the scrim tap and the swipe; `required` blocks all three and exposes the step as an `alertdialog`); there is no per-event veto; a consumer `aria-label` / `aria-labelledby` becomes each step's `label`, which names its dialog; `ref`, `id`, `data-testid`, `className`, `style`, `xstyle`, and the other dialog props have no dialog-level equivalent — a standalone sheet's `ref` and base props reach its panel `
` and its dialog is implementation — so a test or an anchor that needs the dialog queries the panel's `closest('dialog')`, and dialog-level styling is dropped | +| codemod | None; the rewrite moves state the caller owns and is short enough to read | +| downstream | The maintained published surfaces migrate in the deprecation patch (`spec:AST-017` FR29c): the CLI block templates and the stories. `@astryxdesign/lab` is marked `private` and is published to npm only under the `@canary` dist-tag, never as a stable `latest` release; `spec:AST-017` calls it "the private canary-only Lab package" (FR27), lists private packages among its non-goals, puts them outside the published compatibility promise (FR2), and says canary-only surfaces carry no stable compatibility promise, which this record reads as FR29c's "maintained Astryx packages" not reaching Lab, so Lab's migration is optional under it: Lab's `MobileTokenizer` migrates with the patch; Lab's `MobilePowerSearch` keeps the switcher until its own change migrates it, and the switcher keeps working for it. Whether `spec:AST-017` is read that way is its owner's to settle. The switcher's own stories remain as its labelled reference. Implementation gap: on current `main` the templates and `MobileTokenizer` use the switcher | +| transition | no prior transition | +| state | `deprecated`: supported, documented with its replacement, unchanged at runtime — the deprecation patch `spec:AST-017` FR28 requires before a removal, projected through declarations and docs (FR29a, FR29b). Implementation gap: on current `main` the declarations, consumer docs, CLI block templates, and Lab consumers do not yet carry or use the replacement, so the state is not yet realized | +| open decision | Which declared minor removes the surface, and whether a renamed compatibility export precedes the removal; either is a `[breaking]` change of a declared minor (`spec:AST-017` FR28, FR31) | +| target plan | Removal in a future declared minor through a `[breaking]` Changeset; no release is named | + ## Ownership boundary **Owns** @@ -75,32 +127,35 @@ Consumer migration instructions belong in consumer docs and release notes. local visual styling — owned by `component:BottomSheet`. - Page-level stacking or clipping escape — owned by `architecture:layer-runtime` and `spec:AST-027`. -- An ordered visible sheet stack — proposed separately by open `BottomSheetStack` - work and not part of this component. +- The stack of presented sheets, its order, its one visible scrim, and the + replace handoff between standalone sheets — owned by `component:BottomSheet` + DEC-2. A switcher flow takes part as one level (FR10 here, FR12 there); it + does not order itself against other sheets. ## 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). | 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` | deprecated (DEP-0015) | 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` | deprecated (DEP-0015) | 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` | deprecated (DEP-0015) | 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 | deprecated (DEP-0015) | 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` | deprecated (DEP-0015) | 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. | 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. Under reduced motion the handoff follows `design:reduced-motion`: no transform motion runs, and the sheets cross-fade (DR2) or change at once (DR3) in the same order. Implementation gap: under reduced motion the shipped switcher still runs the entering and alignment transforms, shortened, and does not fade the entering sheet in on a coarse pointer. | Current source and transition tests; `design:reduced-motion` DR2, DR3 | -| 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 | +| 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. Under reduced motion the handoff follows `design:reduced-motion`: no transform motion runs, and the sheets cross-fade (DR2) or change at once (DR3) in the same order. Implementation gap: under reduced motion the shipped switcher still runs the entering and alignment transforms, shortened, and does not fade the entering sheet in on a coarse pointer. | Current source and transition tests; `design:reduced-motion` DR2, DR3 | +| 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 | +| FR10 | Presented while other modal sheets are open, a modal switcher flow is one level of the `component:BottomSheet` stack: the active step's dialog is the level and keeps the flow's place across the flow's own handoffs; when covered, the flow's dialogs recede and are blocked as covered sheets are, its backdrop is transparent while a lower sheet owns the one scrim, and its dismissal registration stands down; when it closes over a lower sheet, focus returns into that sheet by `component:BottomSheet` FR9. A modal flow's host dialog is a passive global outlet for toasts like a standalone scrim sheet's, following each handoff and ranked among sheets by the stack (`component:BottomSheet` FR13). Under reduced motion a flow's steps move as `component:BottomSheet` FR15 says, the same panel motion as standalone sheets (FR3). A standalone sheet rendered in a step's content stacks above the flow and leaves with the step. A step is never paired in a replace with a standalone sheet. Implementation gap: on current `main` a switcher flow and a standalone sheet open together are unrelated dialogs, each painting its backdrop, and a switcher flow supplies no toast outlet (no step calls into the outlet registry, and `architecture:layer-runtime` lists a scrim switcher among the modals toasts stay behind), so a toast raised from a step lands behind the flow and a press on it hits the step. | `component:BottomSheet` DEC-2, FR12 | +| 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 @@ -112,14 +167,15 @@ Consumer migration instructions belong in consumer docs and release notes. ### Representative states -| 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. | 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. | +| 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 when the flow owns it — transparent while a lower sheet owns the stack's scrim (FR10, `component:BottomSheet` FR6). | 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. | 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. | +| Stacked | The flow is covered by, or covers, standalone modal sheets: as a covered level its dialogs recede and are blocked and one scrim is visible for the whole stack (FR10). | Recede geometry under `component:BottomSheet` DEC-2. | ### Transformation and precedence order @@ -193,16 +249,25 @@ Consumer migration instructions belong in consumer docs and release notes. - `architecture:public-component-api` and `spec:AST-002` own the released prop, DOM, ref, and compatibility surface. - `spec:AST-027` identifies the non-modal `show()` plus page-level `z-index` path - as a migration gap, not an exception. + as a migration gap, not an exception. The standalone sheet's non-modal path + is hosted in the top layer (`component:BottomSheet` FR11); the switcher's + own non-modal flow wrapper keeps the gap, which its deprecation leaves to be + closed by removal rather than by re-hosting. +- `spec:AST-017` FR26, FR28, and FR29 govern the lifecycle state, the + deprecation patch, and the no-runtime-warning rule that DEP-0015 follows. +- `component:BottomSheet` DEC-2 owns the stack a flow takes part in and the + replacement pattern the deprecation points to. ## 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 handoff under reduced motion on a coarse and a fine pointer | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks.; under reduced motion, a handoff that moves a sheet, or on a coarse pointer does not cross-fade | `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` | +| 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 handoff under reduced motion on a coarse and a fine pointer | A child becomes interactive at the wrong time, a retained child disappears early, a second backdrop paints, or a sheet dialog's lifecycle breaks. Under reduced motion, a handoff that moves a sheet, or on a coarse pointer does not cross-fade. | `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` | +| FR10 | `component:BottomSheet`'s stacking suite (the switcher-as-a-level cases); real-browser dim and recede sampling of a flow stacked over, and under, a standalone sheet | switcher base covered by a standalone sheet, switcher on top of a standalone sheet, a sheet in a step's content, flow closing over a lower sheet | Two backdrops paint, the covered level does not recede, a covered flow takes Escape, or focus lands on `body` when the flow closes over a sheet. Implementation gap: the suite does not exist on current `main`. | `audit:BottomSheetSwitcher/behavior` | +| DEP-0015 | Declaration and consumer-doc inspection (the switcher's and `component:BottomSheet`'s consumer doc); `@deprecated` metadata on the three declarations; CLI template and story sources | the switcher's declarations, docs, templates, and stories, and BottomSheet's consumer doc | A declaration lacks `@deprecated`, a maintained template, story or BottomSheet's consumer doc teaches the switcher as the multi-step route, or a production runtime branch, log, or output changes with the deprecation. Implementation gap: on current `main` every declaration lacks `@deprecated`, BottomSheet's consumer doc recommends the switcher for multi-step flows, and the templates teach the switcher. | `audit:BottomSheetSwitcher/api` | ## Decision log @@ -260,6 +325,39 @@ visual output and no public API surface changes. Rejected: classifying the moving ref as a breaking change, because no public API, documented interaction, or visual output changes. +### DEC-3 — The switcher is deprecated in favour of standalone step sheets + +**Reference:** `component:BottomSheetSwitcher/DEC-3` +**Decider:** imdreamrunner, 2026-10-23 + +A multi-step flow is written as one standalone `BottomSheet` per step driven +by one state value; closing the open step and opening the next in the same +update, from a control inside the open step or from code while focus is in +it, runs the handoff the switcher runs between its steps +(`component:BottomSheet` FR10), with no `sheetId` and no wrapper, for modal +and non-modal flows alike. The one case the replacement treats differently is +a step changed by a control outside the flow's sheets — a page control +beside a non-modal flow, or code acting while focus is on a page control — +which the switcher hands off and the standalone sheets close and open with +their own motion, because from outside the sheets a close and an open are two +sheets' own changes, not one person's move between steps; code acting while +focus is in the step or on the document body keeps the handoff +(`component:BottomSheet` FR10: the actor is inside the step, or none). The switcher therefore has no +job of its own left +and is `deprecated` (DEP-0015): it keeps working as released, every +requirement of this record stays in force, its declarations carry +`@deprecated`, maintained docs and templates teach the replacement, and no +production runtime behavior changes. The removal is a `[breaking]` change of a +future declared minor (`spec:AST-017` FR28, FR31) and is not decided here. +Rejected: keeping the switcher as the one supported flow API, because the +same handoff then needs two implementations and callers must choose between +two mental models for one UI. +Rejected: removing the switcher in the same release that ships the +replacement, because a patch cannot carry a `[breaking]` change +(`spec:AST-017` FR25, FR31) and released flows must keep working. +Rejected: a development-mode warning on render, because a whole-component +deprecation projects through its declarations and docs (`spec:AST-017` FR29). + ## Open questions - **OQ1 — Should modality and scrim paint remain coupled behind `hasScrim`, or