An open source design system that's fully customizable and agent ready
TypeScript
refactor(Layer): one presentation hold keeps a layer's chosen presentation until its close settles (#8587)
Cindy Zhang6422a1db4c02
diff --git a/.changeset/popover-presentation-hold.md b/.changeset/popover-presentation-hold.mdnew file mode 100644index 0000000000..6f434d0fde--- /dev/null+++ b/.changeset/popover-presentation-hold.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[chore] Internal: Popover keeps its chosen presentation (the sheet or the anchored layer, the touch grow or the pointer entrance) from the open until its close settles through the layer runtime's one presentation hold (Layer/presentationHold.ts). No behavior change.++@cixzhangdiff --git a/docs/architecture/layer-runtime.md b/docs/architecture/layer-runtime.mdindex 17dfb41865..6b215ab979 100644--- a/docs/architecture/layer-runtime.md+++ b/docs/architecture/layer-runtime.md@@ -39,6 +39,7 @@ verified_by:packages/core/src/Layer/layerClickBoundary.test.tsx,packages/core/src/Layer/layerDismissalInvariants.test.tsx,packages/core/src/Layer/layerExitCopy.test.ts,+ packages/core/src/Layer/presentationHold.test.tsx,packages/core/src/Layer/__tests__/layerExitCopy.interaction.browser.spec.ts,packages/core/src/Popover/Popover.test.tsx,packages/core/src/DropdownMenu/DropdownMenu.test.tsx,@@ -660,11 +661,12 @@ migration, verification, and completion criteria for these gaps. This record musbe updated only as that work ships.INV14 and INV15 are not met yet, and `spec:AST-003` does not cover them. The-runtime owns the shared exit copy (INV13, `placeLayerExitCopy`); no shared-presentation hold, runtime backdrop tint or lift module exists, Dialog, Drawer,-BottomSheet, Lightbox, MobileNav, ToastViewport, and Selector each build their-own top-layer mounting, exit, or backdrop, and Popover builds its own-presentation hold for its sheet presentation.+runtime owns the shared exit copy (INV13, `placeLayerExitCopy`) and the shared+presentation hold (`Layer/presentationHold.ts`), which Popover uses for its+sheet and anchored presentations; no runtime backdrop tint or lift module+exists, and Dialog, Drawer, BottomSheet, Lightbox, MobileNav, ToastViewport,+and Selector each build their own top-layer mounting, exit, backdrop, or+presentation hold.BottomSheet's own includes its sheet stack's mounting — the re-show thatkeeps a document's sheets in open order, a step dialog's modal present, andthe non-modal sheet's popover host — alongside its scrim; the ordering rules@@ -776,6 +778,8 @@ it on the surface inside the layer and run no layout while it plays.layer's keep-open `pointerup`, so the seam never stops the native event.- `Layer/layerExitCopy.ts` owns the exit copy a touch presentation's close playson.+- `Layer/presentationHold.ts` owns the presentation hold: a layer's chosen+ presentation, held from the open until its close settles (INV14).- `Layer/layerStack.ts`, `Layer/useLayerDismissal.ts`, and`Layer/LayerDepthContext.tsx` own current registration, presence, ordering, andEscape/platform routing.diff --git a/docs/specs/components/Popover/Popover.spec.md b/docs/specs/components/Popover/Popover.spec.mdindex 0e95bfe438..83c0e91205 100644--- a/docs/specs/components/Popover/Popover.spec.md+++ b/docs/specs/components/Popover/Popover.spec.md@@ -193,7 +193,7 @@ table owns their semantic effect.| FR6 | Component anatomy contains the caller trigger and content, one painted Popover surface, and the optional fallback close control. Popover owns no Header, Body, or separate shared-hook surface part. | Current source, docs target inventory, and tests | Accepted anatomy; stale consumer anatomy corrected by this contract || FR7 | The painted surface has one broad canonical target, `popover`; composed components may add one authoritative component-specific refinement target. | Owner direction on 2026-08-31 plus current target inventory | Accepted canonical contract; covered by focused target tests || FR8 | The surface padding is one spacing-scale rung applied on the painted surface. Popover defaults to step 3 (the released inset); `0` paints a flush surface; a direct `usePopover` composition paints none unless it asks for a rung. The rung sits where a theme's `padding` on the `popover` target replaces it. | PR #6683 and its Popover tests; `architecture:container-padding/INV8` (padding alone does not enroll) | Pending owner review (DEC-4); implemented and covered by the Popover surface-padding suite |-| FR9 | Under a finger, Popover grows from its trigger on `--duration-medium-min`, the Storybook step nearest iOS's 206 ms growth, with `--ease-entrance` (`spec:AST-094` FR45), and shrinks back on the theme's exit duration and easing. A touch while it grows is ignored (FR35). Dismissal and a mouse's entrance are unchanged. | `spec:AST-094` FR31, FR35 | Implemented; gap: the open-to-close latch waits for the shared presentation hold |+| FR9 | Under a finger, Popover grows from its trigger on `--duration-medium-min`, the Storybook step nearest iOS's 206 ms growth, with `--ease-entrance` (`spec:AST-094` FR45), and shrinks back on the theme's exit duration and easing. A touch while it grows is ignored (FR35). Dismissal and a mouse's entrance are unchanged. | `spec:AST-094` FR31, FR35 | Implemented |### Allowed variationdiff --git a/docs/specs/components/PowerSearch/PowerSearch.spec.md b/docs/specs/components/PowerSearch/PowerSearch.spec.mdindex 64db1861ca..0c5978a422 100644--- a/docs/specs/components/PowerSearch/PowerSearch.spec.md+++ b/docs/specs/components/PowerSearch/PowerSearch.spec.md@@ -259,7 +259,7 @@ FR10–FR21 govern. FR25 governs a date-only value in both, and FR26 a date-and-| FR7 | In the `popover` presentation, width and preferred-edge selection MUST still yield to the layer runtime's viewport collision handling so the editor remains horizontally visible within the runtime's existing safe area. | `architecture:layer-runtime` | Accepted contract; implementation pending || FR8 | In the `popover` presentation, the width and alignment change MUST NOT alter editor content, field/operator/value state, vertical placement, focus movement, selection, dismissal, or screen-reader semantics. | Compatibility and accessibility requirement | Accepted contract; implementation pending || FR9 | In the `popover` presentation, the opening-control descriptor owned by `component:Tokenizer/DEC-1` and consumed by PowerSearch MUST remain package-internal. PowerSearch MUST NOT add a public width, maximum-width, input-ref, or positioning prop for this behavior. | `component:Tokenizer/DEC-1`, `architecture:public-component-api`, and `component:PowerSearch/DEC-1` | Accepted contract; implementation pending |-| FR10 | `presentation` selects the surface. `adaptive`, the value when `presentation` is omitted, resolves to `bottom-sheet` on compact coarse-pointer screens and to `popover` otherwise, through the same shared resolution the selection controls use (`component:Selector/FR4`); with a fine pointer or on a screen that is not compact it renders exactly the `popover` presentation. `popover` is the tokenizer field with its typeahead and editor popover on every device, unchanged except as FR19 (no mount announcement) states. `bottom-sheet` is the trigger and sheet flow of FR11–FR21 on every device. That resolution answers `popover` on the server and during the hydrating render, so an `adaptive` field server-renders as, and hydrates without a mismatch as, the popover presentation's tokenizer field; on a compact coarse-pointer screen the first client render after hydration swaps it to the trigger. Focus follows the resolution rule below: before any interaction nothing in the field has focus and nothing moves, except that with `hasAutoFocus` the server markup's `autofocus` has focused the combobox input, and the swap then moves focus to the trigger within the same visit — the caller is told of neither a blur nor a new focus. The two closed fields share the field's wrapper, border, and minimum height for the size, and show the same tokens, but their row counts may differ: the popover field's editable tokens each carry a 16 px remove control the trigger's display-only tokens do not (FR11), so the trigger's tokens can wrap into fewer rows (seven filters in a 326 px field take seven rows editable and six as display-only tokens), and the popover field also carries its inline combobox input after the tokens, which may take a row of its own — the swap then changes the field's height by those rows (none on the measured story at 390 px, one token row at 414 px). A resolution change while the flow is open takes effect after it closes and focus has returned to the trigger (the focus the close reports, FR11) — the presentation hold `architecture:layer-runtime/INV14` assigns to the layer runtime; INV14 gap: the runtime does not yet provide one (its record names INV14 as ownership not yet met), so until it does the field keeps its own hold, to be replaced by the runtime's when it exists; when the new presentation is `popover`, focus then moves to the tokenizer's combobox input as the same visit — no `onBlur` and no second `onFocus` reaches the caller. A resolution change while the flow is closed takes effect at once; when focus is anywhere inside the closed field — the trigger, the combobox input, a token or its remove control, the clear control, or an interactive `endContent` — and the focused element does not survive the switch, focus moves to the other presentation's primary control (the combobox input, or the trigger) as a continuation of the same visit — no `onBlur` and no `onFocus` reaches the caller for the hand-off; when the focused element survives, or focus is outside the field, focus stays where it is. When the switch to the sheet presentation happens while the popover presentation's editor popover is open, the popover and its focused control unmount with the tokenizer field, and focus moves to the trigger. Focus never lands on the page body. | DEC-3; touch-flow evidence | Current contract; verified by focused sheet tests and real-engine touch evidence. |+| FR10 | `presentation` selects the surface. `adaptive`, the value when `presentation` is omitted, resolves to `bottom-sheet` on compact coarse-pointer screens and to `popover` otherwise, through the same shared resolution the selection controls use (`component:Selector/FR4`); with a fine pointer or on a screen that is not compact it renders exactly the `popover` presentation. `popover` is the tokenizer field with its typeahead and editor popover on every device, unchanged except as FR19 (no mount announcement) states. `bottom-sheet` is the trigger and sheet flow of FR11–FR21 on every device. That resolution answers `popover` on the server and during the hydrating render, so an `adaptive` field server-renders as, and hydrates without a mismatch as, the popover presentation's tokenizer field; on a compact coarse-pointer screen the first client render after hydration swaps it to the trigger. Focus follows the resolution rule below: before any interaction nothing in the field has focus and nothing moves, except that with `hasAutoFocus` the server markup's `autofocus` has focused the combobox input, and the swap then moves focus to the trigger within the same visit — the caller is told of neither a blur nor a new focus. The two closed fields share the field's wrapper, border, and minimum height for the size, and show the same tokens, but their row counts may differ: the popover field's editable tokens each carry a 16 px remove control the trigger's display-only tokens do not (FR11), so the trigger's tokens can wrap into fewer rows (seven filters in a 326 px field take seven rows editable and six as display-only tokens), and the popover field also carries its inline combobox input after the tokens, which may take a row of its own — the swap then changes the field's height by those rows (none on the measured story at 390 px, one token row at 414 px). A resolution change while the flow is open takes effect after it closes and focus has returned to the trigger (the focus the close reports, FR11) — the presentation hold `architecture:layer-runtime/INV14` assigns to the layer runtime; INV14 gap: the runtime provides that hold (`Layer/presentationHold.ts`), but the field still keeps its own, to be replaced by the runtime's; when the new presentation is `popover`, focus then moves to the tokenizer's combobox input as the same visit — no `onBlur` and no second `onFocus` reaches the caller. A resolution change while the flow is closed takes effect at once; when focus is anywhere inside the closed field — the trigger, the combobox input, a token or its remove control, the clear control, or an interactive `endContent` — and the focused element does not survive the switch, focus moves to the other presentation's primary control (the combobox input, or the trigger) as a continuation of the same visit — no `onBlur` and no `onFocus` reaches the caller for the hand-off; when the focused element survives, or focus is outside the field, focus stays where it is. When the switch to the sheet presentation happens while the popover presentation's editor popover is open, the popover and its focused control unmount with the tokenizer field, and focus moves to the trigger. Focus never lands on the page body. | DEC-3; touch-flow evidence | Current contract; verified by focused sheet tests and real-engine touch evidence. || FR11 | In the sheet presentation the field's control is one trigger: a button with `aria-haspopup="dialog"` and `aria-expanded`, whose accessible name is the field label followed by the trigger's visible text — the placeholder while no filter exists, otherwise the text of the filter tokens — so the name contains what is visible and exposes the selected filters. The tokens are display-only — each is the token's static structure (`component:Token/FR2`): no remove control, no click of its own, no inner control inside the trigger button — and the tokens, the placeholder, and the empty space around them belong to the trigger: a tap on any of them opens the flow. Tokens wrap onto further lines; the trigger does not reserve a row of its own once a token exists. A placeholder longer than the trigger stays on one line and ends in an ellipsis inside the trigger: it never runs under the result count or past the field's border. The trigger's tokens are the popover presentation's tokens, the same component and the same words for a value, and a `date_absolute` value reads as the sheet's date editor shows it (FR17): a date-only value as its day in `timezoneID`, else the UTC day, and a value whose operator sets `isDateOnly: false` as its date and time in `timezoneID`, else the viewer's zone. A `components[type].Token` override renders on the trigger in place of PowerSearch's token, receiving the props the popover presentation hands it — `config`, `filter`, `field`, `operator`, `maxLength`, `isDisabled` — with `onClick` and `onRemove` undefined, as the popover hands them for a read-only filter: the trigger's tokens are display-only, and the override formats its own value. `startIcon` renders in the trigger's lane. The result count and `endContent` render in the field's end lane, outside the trigger button and after it: an interactive `endContent` keeps its own tab stop, its own taps, and its own accessible name, and a tap on it does not open the flow, so a caller's control is never nested inside the component's button and the end lane's text is not part of the trigger's name. `size` sizes the trigger field and its tokens as it sizes the tokenizer field; `statusVariant` places `status.message` as the popover presentation places it; `hasAutoFocus` focuses the trigger on mount. `onFocus` fires when focus enters the field from outside and `onBlur` when it leaves the field: opening the flow moves focus into a sheet, outside the field, so `onBlur` fires, and the close that returns focus to the trigger fires `onFocus` — as the popover presentation fires them around its editor. While disabled the trigger stays focusable with `aria-disabled="true"`, never carries the native `disabled` attribute, does not open, and shows `disabledMessage` as the field does (`spec:AST-085/FR1`, `FR2`). When the component becomes disabled with the flow open, every open sheet of the flow closes and focus moves to the trigger, the destination this record names (`spec:AST-085/FR4`). | DEC-3; touch-flow evidence; `spec:AST-085`; WCAG 2.5.3 | Current contract; verified by focused sheet tests and real-engine touch evidence. || FR12 | Opening the flow from a field with at least one filter, or from a read-only field, shows the Filters sheet, a tall modal sheet named "Filters". Its header — a heading and, while the field is interactive and at least one filter exists, an Add filter button at the medium size whose hit area is at least 44 px tall — and its footer — Done, which applies the sheet's draft (FR15b), and, while `hasClear` is set, the field is interactive, and at least one editable filter exists, Clear all — stay fixed while only the rows between them scroll, the scroll viewport reaching the sheet's edge so its scrollbar does too, with the rows' text on the header's inset. One row per filter shows "{field label} {operator label}" (one catalog message, so a locale can reorder it) and, in bold, the value as the trigger's token shows it — the same formatter, so the same words, with the token's width budget lifted: the row never truncates a single value and never collapses a list to its "{n} items" count — with the token's summaries resolved from the catalog (`@astryx.powersearch.valueEditor.dateRange`, `itemsCount`, `filtersCount`, ICU plurals): an `integer` or `float` value reads as the token's own text (`String(value)`: `2.3456`, `1e+21`, `1e-7`, and `0` for negative zero) wherever the locale writes numbers with the token's numerals — Latin digits and a `.` decimal mark — and elsewhere with the locale's digits and decimal mark, no grouping and no rounding; a `string_list`, `enum_list`, or `entity_list` value reads as all of its items joined by the locale's narrow conjunction list (`Intl.ListFormat`, `{type: 'conjunction', style: 'narrow'}` — "Open, Closed" in English, "高、中" in Simplified Chinese and Japanese, "A, B und C" in German); a date-only `date_absolute` value reads as its day in `timezoneID`, else the UTC day, with no time, and one whose operator sets `isDateOnly: false` as its date and time in `timezoneID`, else the viewer's zone, a `date_range` as "date range", a `nested` value as "{n} filters", and a `date_relative` value as the value step's choice row reads it ("3 days ago", FR20) when a choice matches the stored value, otherwise as stored. A row's label and value are one catalog message, "{label} {value}", the same message the removal announcement of AR6 uses, with the value segment bold. A filter the field can edit is a row button that opens the value step on it, with a trailing remove action — an icon button at the medium size named "Remove {field label} filter", its hit area at least 44 px square, that removes it from the draft (FR15b) without opening the step — except that a filter whose operator takes an `empty` value (a one-tap boolean filter) is a row whose tap removes it, with the same trailing remove action, since it has no value to edit; a read-only filter, or every filter while the field is read-only, is a plain row with no remove action, as the popover gives such a token no remove control. A `nested` filter's row is a row button like any other; its step edits the group with the popover presentation's built-in nested editor (FR14). An editable filter whose field or operator the config no longer has — which the trigger still shows as a token — lists as a row button reading the field's label when the config still has the field and the raw key for whatever is gone — "{field key} {operator key}" when both are, "{field label} {operator key}" when only the operator is — that opens the step's "This filter is no longer available" state (FR14), its trailing remove action still the removal path; it is a plain row while the filter, or the field, is read-only. With no filter in the draft the body is one empty state: a heading — "No filters applied" while the field has none, "No filters" while the draft is empty but the field's filters are still applied (Done replaces them) — a line of guidance, and, while the field is interactive, a centered primary Add filter action that is then the sheet's only Add filter (the header shows none), so the single thing to do is the only visible action; the footer stays, with Done alone, while the draft differs from the applied filters (an emptied draft still has removals to apply), and is absent otherwise. Done closes the flow. Clear all opens a confirmation above the sheet — a dialog titled "Clear all filters?" with "Clear filters" and "Keep filters" — and only confirming removes the editable filters from the draft, recorded as `('remove', <index of the first removed filter>)` with `kept`, the read-only filters in their order, as the list (FR15b): read-only filters are the consumer's, not the person's, so Clear all leaves them in place, as the popover presentation's Clear all does (FR23); the Filters sheet stays open for further editing and focus returns to it (FR16). After the flow closes focus returns to the trigger. | DEC-3; touch-flow evidence; the read-only filter contract (`isReadOnly`, FR22); DEC-4 | Current contract; verified by focused sheet tests and real-engine touch evidence. || FR13 | Add filter — from the Filters sheet's Add filter action, or directly when an interactive field with no filter opens — is a tall modal sheet named "Add filter" opened above the Filters sheet, which stays open beneath it (FR15a), so the sheet has no Back action: dismissing it — Escape, a scrim tap, a swipe — reveals Filters again, or closes the flow when Add filter was the entry point, in which case its fixed footer holds Done. Its header — the heading and, when one shows, the search field — stays fixed while the rows scroll. Without a content-search field it lists the visible fields grouped by `group`, each group a named list: the ungrouped fields first, under the heading "General", then each group under its name in order of first appearance, each a row button with the field's icon, a trailing chevron — or, for a field whose only operator takes an `empty` value, a trailing plus, since choosing it adds the filter at once (FR15) — and, once the field count reaches eight, a "Search filters" field above the list that matches labels and `typeaheadAliases` case-insensitively, caps a non-empty query's matches at `maxSearchResults`, and shows the empty state "No filters match your search" when nothing matches. With a `contentSearchFieldKey` whose default operator takes a `string` value it shows instead a "Search" searchbox using `placeholder`, with the same suggestions the popover presentation's typeahead offers listed inline as row buttons ("Search results"): fields, field-and-operator pairs, value matches, and a leading free-text item for the content field; Enter commits the first suggestion, ArrowDown and ArrowUp move between the search and the rows — arrow movement across independently focusable controls, recorded here as this record's exception to `spec:AST-020/FR15`, which adopts arrow keys for a single composite only: the searchbox-to-list continuity is what the popover presentation's combobox gives the same suggestions, and the rows stay in the Tab order as well — an IME-composing Enter does nothing, and a query with no suggestion shows the empty state "No results found" — the searchbox's `aria-controls` names the results list, or that message while nothing lists, so it always names an element; the field list's "No filters match your search" likewise shows only for a non-empty query that matches nothing, never for a config with no field. Each of the two is a compact empty state with a search icon, that title, and the description "Try a different search.", mounted only while the Add filter sheet is the open one. Neither search field takes focus when the sheet opens: the sheet opens with focus on its panel and the software keyboard stays down until the person taps the search; a direct vertical touch drag on the rows while a search field has focus blurs it, so the keyboard leaves and the rows can be read. A suggestion that carries a value adds the filter to the draft (FR15b), recorded as `('add', draft.length)`, announces `Added {label}` inside the Filters sheet (AR6), and shows Filters as FR15a states; any other suggestion or field row opens the value step with that field and operator, above Add filter. Every visible field lists, a field whose every operator is `nested` included: the value step edits every operator's value (FR14). | DEC-3; touch-flow evidence; current typeahead source | Current contract; verified by focused sheet tests and real-engine touch evidence. |diff --git a/docs/specs/components/Tokenizer/Tokenizer.spec.md b/docs/specs/components/Tokenizer/Tokenizer.spec.mdindex 2518720201..3a95bb8aad 100644--- a/docs/specs/components/Tokenizer/Tokenizer.spec.md+++ b/docs/specs/components/Tokenizer/Tokenizer.spec.md@@ -224,35 +224,35 @@ FR16–FR24, FR26, and FR27 describe the `presentation` prop and its sheetpresentation, which has no inline combobox or suggestion menu; its end laneholds only `endContent` (FR17).-| ID | Invariant | Basis | Status |-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| FR1 | Tokenizer MUST keep one native combobox input mounted across token addition, removal, clear, ordinary wrapping, and maximum-entry states. Reaching `maxEntries` may make the input zero-width, transparent, and out of flow, but MUST NOT replace its identity. | Current source and tests | Verified current behavior |-| FR2 | Tokenizer's suggestion menu MUST remain associated with the outer field/control surface. Existing `menuWidth` behavior remains an exact preferred pixel width plus the outer field's minimum width; it is not a maximum. | Current BaseTypeahead/Tokenizer source and docs | Verified current behavior; preserve |-| FR3 | `unfocusedInline` MAY replace direct token layout with OverflowList while blurred. `unfocusedLayer` MAY keep the real wrapper/input mounted in a context layer while an ordinary-flow placeholder represents the collapsed field. | Current source, tests, and stories | Verified current behavior |-| FR4 | Tokenizer MUST provide Core peers one package-internal descriptor with stable identities for its outer field/control surface and active opening control. Layer consumes the descriptor; public consumers cannot observe or configure it. | Approved package-internal contract; #5804 evidence; `spec:AST-002/DEC-1` | Current contract; implementation pending |-| FR5 | Add/search opens MUST identify the stable inner input as the opening control before the result row disappears. Selection, query clearing, result removal, refocus, or later input collapse MUST NOT substitute the transient result row or a pointer coordinate. | Current selection order plus approved descriptor contract | Current contract; implementation pending |-| FR6 | Edit opens MUST capture the actual activated token/control before state removes or replaces it. The Tokenizer-owned capture path MUST include custom `renderToken` output when activation originates from an identifiable descendant control; it MUST NOT require a new public ref contract. | Current owned wrapper plus approved capture contract | Current contract; implementation pending |-| FR7 | A non-null element is usable only while connected, rendered, and geometrically meaningful for the open being prepared. A disconnected, stale, hidden-layer, zero-width, or otherwise unusable opening control MUST fall back safely to the outer field at logical start before show. | Current max/overflow states plus approved safety rule | Current contract; implementation pending |-| FR8 | The descriptor MUST remain valid across focus movement, token add/remove/clear, wrapping, and `unfocusedLayer` reparenting. It MUST clear on unmount, perform no DOM work during SSR, and never retain an element beyond the open preparation that uses it. | Approved identity/lifetime contract | Current contract; implementation pending |-| FR9 | A consuming surface MUST resolve its preferred width before choosing horizontal placement. A surface at least as wide as the outer field MUST use outer-field logical-start alignment. Only a surface narrower than the outer field may use opening-control geometry. | Approved conditional-placement contract | Current contract; implementation pending |-| FR10 | For a narrower surface, Layer MUST compare the opening control with the outer field's physical start/end geometry, choose the nearer physical edge, map that result to logical start/end, and use logical start on a tie. Viewport collision runs last. | Approved Layer-consumer contract | Current contract; implementation pending |-| FR11 | Opening placement MUST be modality-neutral and latched for one open lifetime. Pointer, keyboard, touch, and programmatic activation of the same control MUST produce the same preferred edge. Pointer movement, later focus movement, resize, or target collapse MUST NOT recompute it. | `architecture:interaction-modality` plus approved stability contract | Current contract; implementation pending |-| FR12 | Placement state MUST commit while the surface is hidden, and Layer MUST show it on the next animation frame only after anchor, alignment, and width styles exist. A stale or invalid descriptor MUST never cause a visible wrong-position or first-frame flash. | Approved no-flash contract | Current contract; implementation pending |-| FR13 | Tokenizer MUST exclude every choice whose `SearchableItem.id` is already present in its committed `value` from displayed bootstrap and search cohorts, including results that settle after the controlled value changes. A caller-rejected proposed value remains eligible because it was not committed. Distinct IDs remain eligible even when their labels match. | Approved Tokenizer multi-selection contract | Current contract; implementation and verification pending |-| FR14 | With `hasEntriesOnFocus` enabled, committing a choice from the current settled empty-query bootstrap cohort MUST keep the input focused and the popup open when another eligible loaded choice remains. The active option advances to the next remaining choice in displayed order; when the committed choice was last, the nearest preceding choice becomes active. `aria-activedescendant` MUST reference that rendered option. | Approved rapid multi-select lifecycle | Current contract; implementation and verification pending |-| FR15 | The retained popup MUST close and clear its active descendant when no eligible loaded choice remains, `maxEntries` is reached, the control becomes disabled, focus leaves, or the person dismisses it. Disabled Tokenizer remains non-interactive. Pending or stale source work MUST NOT reopen a terminal popup or expose stale choices; loading has no selectable placeholder and its busy state clears when work is cancelled or settles. | Approved terminal-state safety boundary | Current contract; implementation and verification pending |-| FR16 | `presentation` selects the surface. `adaptive`, the value when `presentation` is omitted, resolves to `bottom-sheet` on compact coarse-pointer screens and to `popover` otherwise, through the one touch-presentation rule `spec:AST-094/FR13` owns, as the selection controls do; with a fine pointer or on a screen that is not compact it renders exactly the `popover` presentation. `popover` is the inline combobox with its anchored suggestion menu on every device, unchanged. `bottom-sheet` is the trigger and modal sheet of FR17–FR24, FR26, and FR27 on every device. `adaptive` renders on the server, and hydrates, as the inline field, because the resolver answers `popover` where there is no `matchMedia` and in the hydrating render; on a compact coarse-pointer client the field swaps to the sheet field in the first render after hydration; nothing is focused before interaction, so focus is undisturbed (`document.activeElement` stays the body), except with `hasAutoFocus`, whose server-rendered `autofocus` focuses the inline input on load: then the swap moves that focus to the trigger — the same element and visit for the caller, so no `onBlur`/`onFocus` pair is reported. The sheet field keeps the inline field's box — the same width, top, label, and `size` block size — except the inline input's own row: when the tokens leave the input no room on their row, the inline field wraps the input onto a row of its own, and the sheet field, which has no input, drops that row (one `md` row, 27px, on a 390 and a 414px phone with five tokens); with room for the input beside the tokens, nothing shifts. A resolution change while the sheet is open takes effect after it closes and focus has returned to the trigger — the presentation hold `architecture:layer-runtime/INV14` assigns to the layer runtime; INV14 gap: the runtime does not yet provide one (its record names INV14 as ownership not yet met), so until it does the field keeps its own hold, to be replaced by the runtime's when it exists. Whenever the presentation changes while its field holds focus — on its control, a token's remove, the inline Clear all, or the sheet field's `endContent` — then, or while the sheet is closed, focus moves to the new presentation's control, the combobox input or the trigger, so it never lands on the page body (`spec:AST-085/FR4`). | DEC-3; touch-flow evidence | Verified current behavior. |-| FR17 | In the sheet presentation the field's control is one button, named by the field label, with `aria-haspopup="dialog"` and `aria-expanded`, inside the field's control box. The box shows the selected tokens, or the placeholder when empty, wraps tokens onto further lines, and keeps `endContent` at its inline end, where token rows and the placeholder stop short of it. The default tokens are display-only, with no remove control; `renderToken` renders the tokens instead when given, and a control inside a custom token acts at once, as in the inline field: its remove commits `onChange` and moves focus to the trigger. A tap on a token, the placeholder, or the empty space opens the sheet; `endContent` and a custom token's own controls act without opening it, and follow the trigger in the focus order. The box is the inline field's control box: the shared input box — its 1px border, focus ring, surface and radius — the inline field's token inset and row gap, and the `size` block size, so before the sheet opens the field looks the same as the inline field; the touch-sized targets belong to the sheet's rows and actions, not to the closed field. Activating the trigger opens one tall modal BottomSheet named by the field label; the suggestion popover and inline input do not render, and the end lane holds `endContent` only, with no clear button and no busy indicator. While disabled the trigger stays focusable with `aria-disabled="true"`, does not open, and shows `disabledMessage` as the inline field does (`spec:AST-085/FR1`); a field that becomes disabled while its sheet is open closes the sheet and returns focus to the trigger (`spec:AST-085/FR2`). | DEC-3; touch-flow evidence; `spec:AST-085` | Verified current behavior. |-| FR18 | The sheet is a single surface: a search field at the top, a scrolling list of rows, and a footer with Clear all and Save pinned below the list. There is no second sheet. The search field is the shared panel search field drawn as a bordered input box (the input border and surface, element radius, the `lg` input height — 36px — above the sheet's 44px rows) rather than the borderless field a dropdown panel draws; it does not scroll with the list. The footer is rendered in every state of the sheet — while searching, while pending, with an empty query — so Clear all and Save are reachable without clearing the query. On open, focus moves to the sheet's panel, not the search field, so the reading order starts at the top of the sheet and the on-screen keyboard rises only when the person reaches for the search (WCAG 2.2 SC 2.4.3 Focus Order and 3.2.1 On Focus through `spec:AST-020/FR1`). Save commits the draft and closes the sheet (FR26); swipe, scrim, and Escape dismissal follow BottomSheet `purpose="info"` and close directly while the draft is unchanged, and ask first while it is changed (FR27). Each close the person makes — Save, a clean dismissal, a confirmed discard — clears the query and reports it through `onChangeQuery`, so the next open lists the bootstrap set, while a close the field forces (becoming disabled, FR17) keeps the query, since nothing the person did changed it; focus returns to the trigger after the sheet closes. While the search field holds focus on a touch screen, a direct vertical finger drag on the results of at least 8px moves focus from it to the sheet's panel, without clearing the query — a focus rule of the sheet's, so the rows the person reaches for come into view and focus never rests on the page body behind the open modal (`spec:AST-085/FR4`); what the on-screen keyboard does when the field loses focus is `spec:AST-099`'s. A tap, a shorter move, a multi-touch gesture, and a scroll event the list fires on its own (filtering can clamp its scroll position while the person is typing) leave focus where it is. | DEC-3; touch-flow evidence; `component:BottomSheet` | Verified current behavior. |-| FR19 | Each row is a `checkbox` named by the item label whose `aria-checked` mirrors membership in the sheet's draft (FR26): the selection the person is editing, which starts as `value` when the sheet opens. Activating an unchecked row adds the item to the draft; a checked row removes it; both apply to the draft at once and are announced with the inline field's words through the sheet's own live region (AR6); `value` and `onChange` are untouched until Save. Row order is stable while the sheet is open: the items selected when it opened, in `value` order, then draft-selected items absent from the results, then the results in source order; a toggle never moves an existing row. The next open takes a fresh snapshot. The query filters the selected rows by case-insensitive label substring. A row renders an item without its `action` and warns once in development that the sheet does not render it, as the inline panel does (`spec:AST-058/FR9`). | DEC-3; touch-flow evidence | Verified current behavior. |-| FR20 | An empty query lists the source's bootstrap set, capped at `maxMenuItems` as the inline field caps its focus bootstrap (the prop keeps its meaning in the sheet), requested at once on open and on clearing the query, so an instant source shows no busy feedback and announces no busy start; a query shorter than `minQueryLength` is not searched: it lists only the selected rows it matches and, with `hasCreate`, the create row, with no busy feedback, no empty state, and no outcome announcement, as the inline field shows nothing for such a query; otherwise the source is searched `debounceMs` after the query change and the results are capped at `maxMenuItems`. `onChangeQuery` fires on every query change. From open, and from each query change, until that search settles, the list is pending: it shows named busy feedback above any rows still listed from the previous search, the list element carries the busy semantics (`aria-busy`), since the sheet has no combobox (`family:input-fields/FR7`, which places busy semantics on the list a presentation without a combobox updates), and no empty state shows; when the settled search removes the row that holds focus, focus moves to the search field (`spec:AST-085/FR4`). Once settled, the outcome is announced through the sheet's live region (AR6): the result count for a searched query, or the rendered text of the empty state when it shows (`spec:AST-056/FR3`). A source that rejects settles the search to no results, as the inline field does. With no rows and no create row, a searched query shows the `emptySearchText` empty state (its default message when omitted); an empty query shows no list, no message, and announces nothing — only the search field, above the footer — as the inline field opens no menu and reports nothing for a bootstrap set that is empty: nothing has failed, and typing is what finds items (a search-only source, `bootstrap: () => []`, is such a source). | DEC-3; touch-flow evidence; `family:input-fields` | Verified current behavior. |-| FR21 | Long lists render progressively: 50 rows at a time, the next batch when the list scrolls within 200px of its end, with the window reset to the first batch on open and on each query change. The rendered and total counts are exposed as `data-rendered-count` and `data-total-count` on the list, and the rows sit in a `list` whose `listitem` wrappers carry `aria-setsize` with the total and `aria-posinset` with the row's position — the `checkbox` role itself admits neither — so a person moving through the rows can learn that more exist before the list has scrolled; whether a screen reader speaks the position ("n of total") from the focused checkbox depends on the screen reader (`spec:AST-009/FR8`), and the accessibility tree proves the `list`, `listitem`, `aria-setsize`, and `aria-posinset` exposure; focus reaching the last rendered row renders the next batch (WCAG 2.2 SC 1.3.1 Info and Relationships and 4.1.2 Name, Role, Value through `spec:AST-020/FR1`). | DEC-3; touch-flow evidence | Verified current behavior. |-| FR22 | With `hasCreate`, a non-empty trimmed query that matches no draft-selected id, no draft-selected label, and no result label (case-insensitive) adds a create row above the list showing `Create "{text}"` with a trailing Add action named `Add {text}`. Activating it adds to the draft an item with the text as both id and label — reported by Save as a `create` when that create is the last edit that still holds (FR26) — announces it, clears the query, and moves focus to the sheet's search field, since the row it was on is gone. The create row is absent while the draft is at `maxEntries`. | DEC-3; touch-flow evidence; `hasCreate` contract of the inline field | Verified current behavior. |-| FR23 | `maxEntries` is enforced on the draft: while the draft holds `maxEntries` items, unchecked rows carry `aria-disabled="true"`, stay focusable, and ignore activation; checked rows remain toggleable so the person can make room (`spec:AST-085/FR1`). While the draft holds more than `maxEntries` — a `value` over the limit when the sheet opened, or `maxEntries` lowered while the sheet is open — Save is `aria-disabled`, still in the focus order, with a tooltip naming the limit ("Select up to {count} items"), and does nothing until the draft is within it. | DEC-3; touch-flow evidence; `spec:AST-085` | Verified current behavior. |-| FR24 | Clear all is disabled while the draft is empty: `aria-disabled`, still in the focus order, with a tooltip saying nothing is selected, and a click opens nothing (`spec:AST-085/FR1`). Otherwise it opens the sheet's confirmation (FR27) naming the field, with Cancel as the safe action and Clear selection as the destructive one; confirming empties the draft — recorded as a removal of the draft's last item, which Save names in its `remove` when the clear is the last edit that holds (FR26); `value` is untouched until Save, so a discard restores it — closes the confirmation, and, once the confirmation has closed, returns focus to Clear all, which is now `aria-disabled` and still in the focus order, so it keeps focus as a control that becomes disabled does (`spec:AST-085/FR4`, WCAG 2.2 SC 2.4.3 through `spec:AST-020/FR1`); focus never moves to the search field, which would raise the on-screen keyboard over the rows just cleared; and announces "All items removed" inside the sheet (AR6); cancelling changes nothing and focus returns to Clear all the same way. Clear all stays visible and reachable while searching, since the footer is pinned (FR18). | DEC-3; touch-flow evidence | Verified current behavior. |-| FR25 | The result list follows `component:BaseTypeahead` FR12: a press on the field's input or its buttons, or in the list, keeps it open, and a press anywhere else closes it. | `component:BaseTypeahead` FR12 | Verified current behavior |-| FR26 | One open sheet edits one draft. The draft starts as `value` when the sheet opens and takes every row toggle, create, and Clear all (FR19, FR22, FR24); `value` and `onChange` are untouched while the sheet is open. Save closes the sheet; with an unchanged draft it reports nothing, and with a changed one it reports the whole draft once through `onChange(items, change)`, where `change` names the last edit that still holds: the last toggle, create, or clear when its item is in the draft and was not selected at open (`add`, or `create` for an item created in this sheet) or was selected at open and is not in the draft (`remove`); otherwise, when the last edit was a removal and some item selected at open is gone, a `remove` naming one such item; otherwise an `add` (`create` when the last edit created that item) naming an item in the draft that was not selected at open; otherwise a `remove` naming an item gone since open. A field that is disabled when Save fires reports nothing. A toggle is announced when it happens (AR6), not again on Save. | DEC-4 | Verified current behavior. |-| FR27 | Swipe, scrim, and Escape dismissal of the sheet close it directly while the draft equals the selection at open. While the draft differs, they open a discard confirmation inside the sheet — "Discard changes?", "Your changes to {label} haven't been saved." — with Discard changes as the destructive action and Keep editing as the safe one, which is focused first; Discard changes closes the sheet without reporting the draft, and Keep editing closes the confirmation and moves focus to the search field so editing resumes where the sheet's own reading order starts (`spec:AST-085/FR4`). The sheet's confirmations (this one and Clear all's, FR24) are one modal dialog shape: a title, a description, and two full-width large actions stacked in reading order — the destructive action, then the safe action, which takes focus first; the two actions are one action group (`family:action-groups`) while keeping their separated, full-width, stacked look; scrim and Escape take the safe action. A close the field forces (becoming disabled, FR17) asks nothing and reports nothing: the draft is dropped. | DEC-4 | Verified current behavior, with one implementation gap: the confirmation's two actions are separated Buttons, not yet one action group (`family:action-groups`). |+| ID | Invariant | Basis | Status |+| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Tokenizer MUST keep one native combobox input mounted across token addition, removal, clear, ordinary wrapping, and maximum-entry states. Reaching `maxEntries` may make the input zero-width, transparent, and out of flow, but MUST NOT replace its identity. | Current source and tests | Verified current behavior |+| FR2 | Tokenizer's suggestion menu MUST remain associated with the outer field/control surface. Existing `menuWidth` behavior remains an exact preferred pixel width plus the outer field's minimum width; it is not a maximum. | Current BaseTypeahead/Tokenizer source and docs | Verified current behavior; preserve |+| FR3 | `unfocusedInline` MAY replace direct token layout with OverflowList while blurred. `unfocusedLayer` MAY keep the real wrapper/input mounted in a context layer while an ordinary-flow placeholder represents the collapsed field. | Current source, tests, and stories | Verified current behavior |+| FR4 | Tokenizer MUST provide Core peers one package-internal descriptor with stable identities for its outer field/control surface and active opening control. Layer consumes the descriptor; public consumers cannot observe or configure it. | Approved package-internal contract; #5804 evidence; `spec:AST-002/DEC-1` | Current contract; implementation pending |+| FR5 | Add/search opens MUST identify the stable inner input as the opening control before the result row disappears. Selection, query clearing, result removal, refocus, or later input collapse MUST NOT substitute the transient result row or a pointer coordinate. | Current selection order plus approved descriptor contract | Current contract; implementation pending |+| FR6 | Edit opens MUST capture the actual activated token/control before state removes or replaces it. The Tokenizer-owned capture path MUST include custom `renderToken` output when activation originates from an identifiable descendant control; it MUST NOT require a new public ref contract. | Current owned wrapper plus approved capture contract | Current contract; implementation pending |+| FR7 | A non-null element is usable only while connected, rendered, and geometrically meaningful for the open being prepared. A disconnected, stale, hidden-layer, zero-width, or otherwise unusable opening control MUST fall back safely to the outer field at logical start before show. | Current max/overflow states plus approved safety rule | Current contract; implementation pending |+| FR8 | The descriptor MUST remain valid across focus movement, token add/remove/clear, wrapping, and `unfocusedLayer` reparenting. It MUST clear on unmount, perform no DOM work during SSR, and never retain an element beyond the open preparation that uses it. | Approved identity/lifetime contract | Current contract; implementation pending |+| FR9 | A consuming surface MUST resolve its preferred width before choosing horizontal placement. A surface at least as wide as the outer field MUST use outer-field logical-start alignment. Only a surface narrower than the outer field may use opening-control geometry. | Approved conditional-placement contract | Current contract; implementation pending |+| FR10 | For a narrower surface, Layer MUST compare the opening control with the outer field's physical start/end geometry, choose the nearer physical edge, map that result to logical start/end, and use logical start on a tie. Viewport collision runs last. | Approved Layer-consumer contract | Current contract; implementation pending |+| FR11 | Opening placement MUST be modality-neutral and latched for one open lifetime. Pointer, keyboard, touch, and programmatic activation of the same control MUST produce the same preferred edge. Pointer movement, later focus movement, resize, or target collapse MUST NOT recompute it. | `architecture:interaction-modality` plus approved stability contract | Current contract; implementation pending |+| FR12 | Placement state MUST commit while the surface is hidden, and Layer MUST show it on the next animation frame only after anchor, alignment, and width styles exist. A stale or invalid descriptor MUST never cause a visible wrong-position or first-frame flash. | Approved no-flash contract | Current contract; implementation pending |+| FR13 | Tokenizer MUST exclude every choice whose `SearchableItem.id` is already present in its committed `value` from displayed bootstrap and search cohorts, including results that settle after the controlled value changes. A caller-rejected proposed value remains eligible because it was not committed. Distinct IDs remain eligible even when their labels match. | Approved Tokenizer multi-selection contract | Current contract; implementation and verification pending |+| FR14 | With `hasEntriesOnFocus` enabled, committing a choice from the current settled empty-query bootstrap cohort MUST keep the input focused and the popup open when another eligible loaded choice remains. The active option advances to the next remaining choice in displayed order; when the committed choice was last, the nearest preceding choice becomes active. `aria-activedescendant` MUST reference that rendered option. | Approved rapid multi-select lifecycle | Current contract; implementation and verification pending |+| FR15 | The retained popup MUST close and clear its active descendant when no eligible loaded choice remains, `maxEntries` is reached, the control becomes disabled, focus leaves, or the person dismisses it. Disabled Tokenizer remains non-interactive. Pending or stale source work MUST NOT reopen a terminal popup or expose stale choices; loading has no selectable placeholder and its busy state clears when work is cancelled or settles. | Approved terminal-state safety boundary | Current contract; implementation and verification pending |+| FR16 | `presentation` selects the surface. `adaptive`, the value when `presentation` is omitted, resolves to `bottom-sheet` on compact coarse-pointer screens and to `popover` otherwise, through the one touch-presentation rule `spec:AST-094/FR13` owns, as the selection controls do; with a fine pointer or on a screen that is not compact it renders exactly the `popover` presentation. `popover` is the inline combobox with its anchored suggestion menu on every device, unchanged. `bottom-sheet` is the trigger and modal sheet of FR17–FR24, FR26, and FR27 on every device. `adaptive` renders on the server, and hydrates, as the inline field, because the resolver answers `popover` where there is no `matchMedia` and in the hydrating render; on a compact coarse-pointer client the field swaps to the sheet field in the first render after hydration; nothing is focused before interaction, so focus is undisturbed (`document.activeElement` stays the body), except with `hasAutoFocus`, whose server-rendered `autofocus` focuses the inline input on load: then the swap moves that focus to the trigger — the same element and visit for the caller, so no `onBlur`/`onFocus` pair is reported. The sheet field keeps the inline field's box — the same width, top, label, and `size` block size — except the inline input's own row: when the tokens leave the input no room on their row, the inline field wraps the input onto a row of its own, and the sheet field, which has no input, drops that row (one `md` row, 27px, on a 390 and a 414px phone with five tokens); with room for the input beside the tokens, nothing shifts. A resolution change while the sheet is open takes effect after it closes and focus has returned to the trigger — the presentation hold `architecture:layer-runtime/INV14` assigns to the layer runtime; INV14 gap: the runtime provides that hold (`Layer/presentationHold.ts`), but the field still keeps its own, to be replaced by the runtime's. Whenever the presentation changes while its field holds focus — on its control, a token's remove, the inline Clear all, or the sheet field's `endContent` — then, or while the sheet is closed, focus moves to the new presentation's control, the combobox input or the trigger, so it never lands on the page body (`spec:AST-085/FR4`). | DEC-3; touch-flow evidence | Verified current behavior. |+| FR17 | In the sheet presentation the field's control is one button, named by the field label, with `aria-haspopup="dialog"` and `aria-expanded`, inside the field's control box. The box shows the selected tokens, or the placeholder when empty, wraps tokens onto further lines, and keeps `endContent` at its inline end, where token rows and the placeholder stop short of it. The default tokens are display-only, with no remove control; `renderToken` renders the tokens instead when given, and a control inside a custom token acts at once, as in the inline field: its remove commits `onChange` and moves focus to the trigger. A tap on a token, the placeholder, or the empty space opens the sheet; `endContent` and a custom token's own controls act without opening it, and follow the trigger in the focus order. The box is the inline field's control box: the shared input box — its 1px border, focus ring, surface and radius — the inline field's token inset and row gap, and the `size` block size, so before the sheet opens the field looks the same as the inline field; the touch-sized targets belong to the sheet's rows and actions, not to the closed field. Activating the trigger opens one tall modal BottomSheet named by the field label; the suggestion popover and inline input do not render, and the end lane holds `endContent` only, with no clear button and no busy indicator. While disabled the trigger stays focusable with `aria-disabled="true"`, does not open, and shows `disabledMessage` as the inline field does (`spec:AST-085/FR1`); a field that becomes disabled while its sheet is open closes the sheet and returns focus to the trigger (`spec:AST-085/FR2`). | DEC-3; touch-flow evidence; `spec:AST-085` | Verified current behavior. |+| FR18 | The sheet is a single surface: a search field at the top, a scrolling list of rows, and a footer with Clear all and Save pinned below the list. There is no second sheet. The search field is the shared panel search field drawn as a bordered input box (the input border and surface, element radius, the `lg` input height — 36px — above the sheet's 44px rows) rather than the borderless field a dropdown panel draws; it does not scroll with the list. The footer is rendered in every state of the sheet — while searching, while pending, with an empty query — so Clear all and Save are reachable without clearing the query. On open, focus moves to the sheet's panel, not the search field, so the reading order starts at the top of the sheet and the on-screen keyboard rises only when the person reaches for the search (WCAG 2.2 SC 2.4.3 Focus Order and 3.2.1 On Focus through `spec:AST-020/FR1`). Save commits the draft and closes the sheet (FR26); swipe, scrim, and Escape dismissal follow BottomSheet `purpose="info"` and close directly while the draft is unchanged, and ask first while it is changed (FR27). Each close the person makes — Save, a clean dismissal, a confirmed discard — clears the query and reports it through `onChangeQuery`, so the next open lists the bootstrap set, while a close the field forces (becoming disabled, FR17) keeps the query, since nothing the person did changed it; focus returns to the trigger after the sheet closes. While the search field holds focus on a touch screen, a direct vertical finger drag on the results of at least 8px moves focus from it to the sheet's panel, without clearing the query — a focus rule of the sheet's, so the rows the person reaches for come into view and focus never rests on the page body behind the open modal (`spec:AST-085/FR4`); what the on-screen keyboard does when the field loses focus is `spec:AST-099`'s. A tap, a shorter move, a multi-touch gesture, and a scroll event the list fires on its own (filtering can clamp its scroll position while the person is typing) leave focus where it is. | DEC-3; touch-flow evidence; `component:BottomSheet` | Verified current behavior. |+| FR19 | Each row is a `checkbox` named by the item label whose `aria-checked` mirrors membership in the sheet's draft (FR26): the selection the person is editing, which starts as `value` when the sheet opens. Activating an unchecked row adds the item to the draft; a checked row removes it; both apply to the draft at once and are announced with the inline field's words through the sheet's own live region (AR6); `value` and `onChange` are untouched until Save. Row order is stable while the sheet is open: the items selected when it opened, in `value` order, then draft-selected items absent from the results, then the results in source order; a toggle never moves an existing row. The next open takes a fresh snapshot. The query filters the selected rows by case-insensitive label substring. A row renders an item without its `action` and warns once in development that the sheet does not render it, as the inline panel does (`spec:AST-058/FR9`). | DEC-3; touch-flow evidence | Verified current behavior. |+| FR20 | An empty query lists the source's bootstrap set, capped at `maxMenuItems` as the inline field caps its focus bootstrap (the prop keeps its meaning in the sheet), requested at once on open and on clearing the query, so an instant source shows no busy feedback and announces no busy start; a query shorter than `minQueryLength` is not searched: it lists only the selected rows it matches and, with `hasCreate`, the create row, with no busy feedback, no empty state, and no outcome announcement, as the inline field shows nothing for such a query; otherwise the source is searched `debounceMs` after the query change and the results are capped at `maxMenuItems`. `onChangeQuery` fires on every query change. From open, and from each query change, until that search settles, the list is pending: it shows named busy feedback above any rows still listed from the previous search, the list element carries the busy semantics (`aria-busy`), since the sheet has no combobox (`family:input-fields/FR7`, which places busy semantics on the list a presentation without a combobox updates), and no empty state shows; when the settled search removes the row that holds focus, focus moves to the search field (`spec:AST-085/FR4`). Once settled, the outcome is announced through the sheet's live region (AR6): the result count for a searched query, or the rendered text of the empty state when it shows (`spec:AST-056/FR3`). A source that rejects settles the search to no results, as the inline field does. With no rows and no create row, a searched query shows the `emptySearchText` empty state (its default message when omitted); an empty query shows no list, no message, and announces nothing — only the search field, above the footer — as the inline field opens no menu and reports nothing for a bootstrap set that is empty: nothing has failed, and typing is what finds items (a search-only source, `bootstrap: () => []`, is such a source). | DEC-3; touch-flow evidence; `family:input-fields` | Verified current behavior. |+| FR21 | Long lists render progressively: 50 rows at a time, the next batch when the list scrolls within 200px of its end, with the window reset to the first batch on open and on each query change. The rendered and total counts are exposed as `data-rendered-count` and `data-total-count` on the list, and the rows sit in a `list` whose `listitem` wrappers carry `aria-setsize` with the total and `aria-posinset` with the row's position — the `checkbox` role itself admits neither — so a person moving through the rows can learn that more exist before the list has scrolled; whether a screen reader speaks the position ("n of total") from the focused checkbox depends on the screen reader (`spec:AST-009/FR8`), and the accessibility tree proves the `list`, `listitem`, `aria-setsize`, and `aria-posinset` exposure; focus reaching the last rendered row renders the next batch (WCAG 2.2 SC 1.3.1 Info and Relationships and 4.1.2 Name, Role, Value through `spec:AST-020/FR1`). | DEC-3; touch-flow evidence | Verified current behavior. |+| FR22 | With `hasCreate`, a non-empty trimmed query that matches no draft-selected id, no draft-selected label, and no result label (case-insensitive) adds a create row above the list showing `Create "{text}"` with a trailing Add action named `Add {text}`. Activating it adds to the draft an item with the text as both id and label — reported by Save as a `create` when that create is the last edit that still holds (FR26) — announces it, clears the query, and moves focus to the sheet's search field, since the row it was on is gone. The create row is absent while the draft is at `maxEntries`. | DEC-3; touch-flow evidence; `hasCreate` contract of the inline field | Verified current behavior. |+| FR23 | `maxEntries` is enforced on the draft: while the draft holds `maxEntries` items, unchecked rows carry `aria-disabled="true"`, stay focusable, and ignore activation; checked rows remain toggleable so the person can make room (`spec:AST-085/FR1`). While the draft holds more than `maxEntries` — a `value` over the limit when the sheet opened, or `maxEntries` lowered while the sheet is open — Save is `aria-disabled`, still in the focus order, with a tooltip naming the limit ("Select up to {count} items"), and does nothing until the draft is within it. | DEC-3; touch-flow evidence; `spec:AST-085` | Verified current behavior. |+| FR24 | Clear all is disabled while the draft is empty: `aria-disabled`, still in the focus order, with a tooltip saying nothing is selected, and a click opens nothing (`spec:AST-085/FR1`). Otherwise it opens the sheet's confirmation (FR27) naming the field, with Cancel as the safe action and Clear selection as the destructive one; confirming empties the draft — recorded as a removal of the draft's last item, which Save names in its `remove` when the clear is the last edit that holds (FR26); `value` is untouched until Save, so a discard restores it — closes the confirmation, and, once the confirmation has closed, returns focus to Clear all, which is now `aria-disabled` and still in the focus order, so it keeps focus as a control that becomes disabled does (`spec:AST-085/FR4`, WCAG 2.2 SC 2.4.3 through `spec:AST-020/FR1`); focus never moves to the search field, which would raise the on-screen keyboard over the rows just cleared; and announces "All items removed" inside the sheet (AR6); cancelling changes nothing and focus returns to Clear all the same way. Clear all stays visible and reachable while searching, since the footer is pinned (FR18). | DEC-3; touch-flow evidence | Verified current behavior. |+| FR25 | The result list follows `component:BaseTypeahead` FR12: a press on the field's input or its buttons, or in the list, keeps it open, and a press anywhere else closes it. | `component:BaseTypeahead` FR12 | Verified current behavior |+| FR26 | One open sheet edits one draft. The draft starts as `value` when the sheet opens and takes every row toggle, create, and Clear all (FR19, FR22, FR24); `value` and `onChange` are untouched while the sheet is open. Save closes the sheet; with an unchanged draft it reports nothing, and with a changed one it reports the whole draft once through `onChange(items, change)`, where `change` names the last edit that still holds: the last toggle, create, or clear when its item is in the draft and was not selected at open (`add`, or `create` for an item created in this sheet) or was selected at open and is not in the draft (`remove`); otherwise, when the last edit was a removal and some item selected at open is gone, a `remove` naming one such item; otherwise an `add` (`create` when the last edit created that item) naming an item in the draft that was not selected at open; otherwise a `remove` naming an item gone since open. A field that is disabled when Save fires reports nothing. A toggle is announced when it happens (AR6), not again on Save. | DEC-4 | Verified current behavior. |+| FR27 | Swipe, scrim, and Escape dismissal of the sheet close it directly while the draft equals the selection at open. While the draft differs, they open a discard confirmation inside the sheet — "Discard changes?", "Your changes to {label} haven't been saved." — with Discard changes as the destructive action and Keep editing as the safe one, which is focused first; Discard changes closes the sheet without reporting the draft, and Keep editing closes the confirmation and moves focus to the search field so editing resumes where the sheet's own reading order starts (`spec:AST-085/FR4`). The sheet's confirmations (this one and Clear all's, FR24) are one modal dialog shape: a title, a description, and two full-width large actions stacked in reading order — the destructive action, then the safe action, which takes focus first; the two actions are one action group (`family:action-groups`) while keeping their separated, full-width, stacked look; scrim and Escape take the safe action. A close the field forces (becoming disabled, FR17) asks nothing and reports nothing: the draft is dropped. | DEC-4 | Verified current behavior, with one implementation gap: the confirmation's two actions are separated Buttons, not yet one action group (`family:action-groups`). |### Allowed variationdiff --git a/packages/core/src/Layer/presentationHold.test.tsx b/packages/core/src/Layer/presentationHold.test.tsxnew file mode 100644index 0000000000..ef2d0a17ea--- /dev/null+++ b/packages/core/src/Layer/presentationHold.test.tsx@@ -0,0 +1,80 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {act, renderHook} from '@testing-library/react';+import {describe, expect, it} from 'vitest';+import * as core from '../index';+import {createPresentationHold, usePresentationHold} from './presentationHold';++const here = path.dirname(fileURLToPath(import.meta.url));++describe('createPresentationHold', () => {+ it('holds what the opening chose until it is released', () => {+ const hold = createPresentationHold<'touch' | 'pointer'>();+ expect(hold.isHeld()).toBe(false);+ expect(hold.current()).toBeUndefined();+ hold.take('touch');+ expect(hold.current()).toBe('touch');+ expect(hold.isHeld()).toBe(true);+ hold.release();+ expect(hold.isHeld()).toBe(false);+ expect(hold.current()).toBeUndefined();+ });++ it('holds a false choice as held', () => {+ const hold = createPresentationHold<boolean>();+ hold.take(false);+ expect(hold.isHeld()).toBe(true);+ expect(hold.current()).toBe(false);+ });+});++describe('usePresentationHold', () => {+ it('holds the presentation from the render that opens it, whatever it becomes, until release', () => {+ const {result, rerender} = renderHook(+ (props: {isOpen: boolean; presentation: string}) =>+ usePresentationHold(props),+ {initialProps: {isOpen: false, presentation: 'sheet'}},+ );+ expect(result.current).toMatchObject({presentation: null, isHeld: false});+ rerender({isOpen: true, presentation: 'sheet'});+ expect(result.current).toMatchObject({presentation: 'sheet', isHeld: true});+ // The screen stops being compact while it is open: the hold keeps the+ // opening's choice, and keeps it through the close.+ rerender({isOpen: true, presentation: 'anchored'});+ expect(result.current.presentation).toBe('sheet');+ rerender({isOpen: false, presentation: 'anchored'});+ expect(result.current).toMatchObject({presentation: 'sheet', isHeld: true});+ act(() => result.current.release());+ expect(result.current).toMatchObject({presentation: null, isHeld: false});+ // The next opening chooses again.+ rerender({isOpen: true, presentation: 'anchored'});+ expect(result.current.presentation).toBe('anchored');+ });++ it('keeps release stable across renders', () => {+ const {result, rerender} = renderHook(+ (props: {isOpen: boolean}) =>+ usePresentationHold({...props, presentation: 1}),+ {initialProps: {isOpen: true}},+ );+ const first = result.current.release;+ rerender({isOpen: false});+ expect(result.current.release).toBe(first);+ });++ it('stays internal: not exported from the package or the Layer barrel', () => {+ expect(core).not.toHaveProperty('usePresentationHold');+ expect(core).not.toHaveProperty('createPresentationHold');+ const barrel = fs.readFileSync(path.join(here, 'index.ts'), 'utf8');+ expect(barrel).not.toMatch(/presentationHold/);+ const pkg = JSON.parse(+ fs.readFileSync(path.join(here, '../../package.json'), 'utf8'),+ ) as {exports: Record<string, unknown>};+ expect(+ Object.keys(pkg.exports).filter(key => key.includes('presentationHold')),+ ).toEqual([]);+ });+});diff --git a/packages/core/src/Layer/presentationHold.ts b/packages/core/src/Layer/presentationHold.tsnew file mode 100644index 0000000000..6830eb9539--- /dev/null+++ b/packages/core/src/Layer/presentationHold.ts@@ -0,0 +1,96 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file presentationHold.ts+ * @input Whether a layer is open, and the presentation an opening would+ * choose now+ * @output createPresentationHold (an imperative hold, for code that decides+ * at an open event) and usePresentationHold (the same hold taken during+ * render): the presentation the opening chose, held until the component+ * releases it+ * @position The layer runtime's presentation hold: it keeps a layer's chosen+ * presentation from the open until its close settles. Internal to core: not+ * exported from the package or any barrel (presentationHold.test.tsx locks+ * that). Not the input hold (inputHold.ts), which drops input while a+ * presentation animates.+ *+ * A layer that can present more than one way (a popover that is a sheet on a+ * phone, a touch grow or a pointer entrance) chooses as it opens, and its+ * close has to play out in the same presentation even when what it would+ * choose has changed meanwhile (a phone rotated past the compact width, a+ * pointer that changed). One job: take the choice at the opening, hold it,+ * and let it go when the component says its close has settled (its+ * `<dialog>`'s `close` event, its exit animation's end). The component+ * decides when that is; the hold decides nothing about timing.+ *+ * SYNC: When modified, update presentationHold.test.tsx.+ */++import {useCallback, useState} from 'react';++/** An imperative presentation hold. */+export interface PresentationHold<P> {+ /** Takes the opening's choice, replacing any held one. */+ take(presentation: P): void;+ /** The held choice, or undefined when nothing is held. */+ current(): P | undefined;+ /** Whether a choice is held. */+ isHeld(): boolean;+ /** Lets the held choice go (the close has settled). */+ release(): void;+}++/** A presentation hold for code that chooses at an open event. */+export function createPresentationHold<P>(): PresentationHold<P> {+ let held: {readonly value: P} | null = null;+ return {+ take(presentation) {+ held = {value: presentation};+ },+ current: () => held?.value,+ isHeld: () => held != null,+ release() {+ held = null;+ },+ };+}++/** What `usePresentationHold` returns. */+export interface PresentationHoldState<P> {+ /** The opening's choice while it is held; null when nothing is held. */+ readonly presentation: P | null;+ /** True from the opening render until `release()`. */+ readonly isHeld: boolean;+ /** Lets the held choice go (the close has settled). Stable. */+ readonly release: () => void;+}++/**+ * The presentation hold, taken during render: the render in which `isOpen`+ * turns on already holds `presentation` as it is then, and it stays held,+ * whatever `presentation` becomes, until `release()`. A component calls+ * `release()` when its close has settled (it may do so during render, as it+ * would set any of its own state).+ */+export function usePresentationHold<P>({+ isOpen,+ presentation,+}: {+ isOpen: boolean;+ presentation: P;+}): PresentationHoldState<P> {+ const [held, setHeld] = useState<{readonly value: P} | null>(null);+ let current = held;+ if (isOpen && held == null) {+ current = {value: presentation};+ setHeld(current);+ }+ const release = useCallback(() => setHeld(null), []);+ return {+ presentation: current == null ? null : current.value,+ isHeld: current != null,+ release,+ };+}diff --git a/packages/core/src/Popover/Popover.tsx b/packages/core/src/Popover/Popover.tsxindex 382dc44060..c481bbedc4 100644--- a/packages/core/src/Popover/Popover.tsx+++ b/packages/core/src/Popover/Popover.tsx@@ -60,6 +60,7 @@ import {devWarn} from '../utils/devWarning';import {matchesMediaQuery, watchMediaQuery} from '../utils/coarsePointer';import type {BaseProps} from '../BaseProps';import {FALLBACK_CLOSE_SELECTOR, usePopoverInternal} from './usePopover';+import {usePresentationHold} from '../Layer/presentationHold';import {usePopoverSurfaceMotion} from './PopoverTouch';import {FOCUSABLE_SELECTOR,@@ -612,18 +613,17 @@ export function Popover({// A controlled popover opens on the surface its presentation resolves to// as it opens, and keeps that surface until it closes: a phone rotated past// the compact width while the sheet is open keeps its sheet.- const [controlledSurface, setControlledSurface] = useState<- 'popover' | 'bottom-sheet' | null- >(null);- // The latch is set during render, as the controlled `isOpen` turns on or- // off, so the open surface is known in the same render that opens it.- if (isControlled) {- if (isOpen !== true && controlledSurface != null) {- setControlledSurface(null);- } else if (isOpen === true && controlledSurface == null) {- setControlledSurface(popover.isOpen ? 'popover' : resolvedPresentation);- }+ // The layer runtime's presentation hold (Layer/presentationHold), taken+ // during render as the controlled `isOpen` turns on, so the open surface is+ // known in the same render that opens it, and let go as it turns off.+ const surfaceHold = usePresentationHold<'popover' | 'bottom-sheet'>({+ isOpen: isControlled && isOpen === true,+ presentation: popover.isOpen ? 'popover' : resolvedPresentation,+ });+ if (isControlled && isOpen !== true && surfaceHold.isHeld) {+ surfaceHold.release();}+ const controlledSurface = surfaceHold.presentation;const isSheetOpen = isControlled? isOpen === true && controlledSurface === 'bottom-sheet': isSheetOpenState;@@ -637,12 +637,16 @@ export function Popover({// stopped being compact, it stays through its exit, so the exit plays out// and its dialog hands focus back to the trigger (component:Popover AR4),// and gives way to the anchored layer once its dialog has closed.- const [hasSheetBeenOpen, setHasSheetBeenOpen] = useState(false);+ // The sheet's presentation hold: from the render that opens it until its+ // dialog has closed.+ const sheetHold = usePresentationHold({+ isOpen: isSheetOpen,+ presentation: true,+ });+ const hasSheetBeenOpen = sheetHold.isHeld;+ const releaseSheet = sheetHold.release;// The trigger's text, which names a sheet that has no `label` (DEC-8).const [triggerText, setTriggerText] = useState('');- if (isSheetOpen && !hasSheetBeenOpen) {- setHasSheetBeenOpen(true);- }const isSheetMounted =isSheetOpen ||hasSheetBeenOpen ||@@ -722,14 +726,14 @@ export function Popover({}const dialog = sheetPanelRef.current?.closest('dialog');if (dialog == null || !dialog.open) {- // eslint-disable-next-line @eslint-react/set-state-in-effect -- syncs with the sheet's <dialog>: it is already closed, so its close event has fired and its exit is over; unmount it- setHasSheetBeenOpen(false);+ // The sheet's <dialog> is already closed, so its close event has fired+ // and its exit is over: unmount it.+ releaseSheet();return;}- const handleClose = () => setHasSheetBeenOpen(false);- dialog.addEventListener('close', handleClose);- return () => dialog.removeEventListener('close', handleClose);- }, [hasSheetBeenOpen, isSheetOpen]);+ dialog.addEventListener('close', releaseSheet);+ return () => dialog.removeEventListener('close', releaseSheet);+ }, [hasSheetBeenOpen, isSheetOpen, releaseSheet]);// An open on a compact touch screen shows the sheet at once: its module// loads as soon as the sheet can be the surface, with nothing rendered.useEffect(() => {diff --git a/packages/core/src/Popover/usePopoverSurfaceMotion.ts b/packages/core/src/Popover/usePopoverSurfaceMotion.tsindex 025f3b933b..d3e5885a0d 100644--- a/packages/core/src/Popover/usePopoverSurfaceMotion.ts+++ b/packages/core/src/Popover/usePopoverSurfaceMotion.ts@@ -4,7 +4,8 @@/*** @file usePopoverSurfaceMotion.ts- * @input React, the shared touch resolver and popoverSurfaceMotion+ * @input React, the shared touch resolver, the layer runtime's presentation+ * hold and popoverSurfaceMotion* @output Exports `usePopoverSurfaceMotion`, the calls Popover makes as it* opens and as it starts to close. Under a finger they present and dismiss* the popover the UIKit way; a mouse keeps the layer's own entrance.@@ -23,7 +24,8 @@* - /packages/core/src/Popover/usePopoverSurfaceMotion.test.tsx*/-import {useCallback, useEffect, useMemo, useRef} from 'react';+import {useCallback, useEffect, useMemo, useRef, useState} from 'react';+import {createPresentationHold} from '../Layer/presentationHold';import {isCoarsePointer} from '../utils/coarsePointer';import {createPopoverSurfaceMotion,@@ -64,7 +66,9 @@ export function usePopoverSurfaceMotion(): PopoverSurfaceMotionCalls {entrance: HTMLElement | null;motion: PopoverSurfaceMotion;} | null>(null);- const isTouchPresentationRef = useRef(false);+ // Whether the presentation in progress is the touch one, held from the+ // open until its close begins (Layer/presentationHold).+ const [touchHold] = useState(() => createPresentationHold<boolean>());const release = useCallback(() => {motionRef.current?.motion.dispose();@@ -100,7 +104,7 @@ export function usePopoverSurfaceMotion(): PopoverSurfaceMotionCalls {}const isTouch =source != null && isCoarsePointer(layer.ownerDocument.defaultView);- isTouchPresentationRef.current = isTouch;+ touchHold.take(isTouch);if (!isTouch || source == null) {// A fine pointer animates nothing here, so nothing is created for// it, and nothing is promoted to the compositor. A motion this layer@@ -114,14 +118,15 @@ export function usePopoverSurfaceMotion(): PopoverSurfaceMotionCalls {source: boxOf(source),}));},- [motionFor, release],+ [motionFor, release, touchHold],);const closeStart = useCallback(() => {- if (isTouchPresentationRef.current) {+ if (touchHold.current() === true) {motionRef.current?.motion.exit();}- }, []);+ touchHold.release();+ }, [touchHold]);return useMemo(() => ({present, closeStart}), [present, closeStart]);}