Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(Tokenizer): the sheet presentation edits a draft that Save commits (#9630)

Xinzi Zhou98f48789dcb5
diff --git a/docs/specs/components/Tokenizer/Tokenizer.spec.md b/docs/specs/components/Tokenizer/Tokenizer.spec.md
index a8484c39d0..5364397429 100644
--- a/docs/specs/components/Tokenizer/Tokenizer.spec.md
+++ b/docs/specs/components/Tokenizer/Tokenizer.spec.md
@@ -15,6 +15,9 @@ verified_by:
packages/core/src/Tokenizer/Tokenizer.test.tsx,
packages/core/src/Tokenizer/Tokenizer.ssr.test.tsx,
packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx,
+ packages/lab/src/MobileTokenizer/MobileTokenizer.test.tsx,
+ packages/lab/src/internal/MobileSheetConfirmation.test.tsx,
+ packages/lab/src/internal/useDismissSearchOnTouchDrag.test.tsx,
packages/core/src/Tokenizer/Tokenizer.props-type.test.tsx,
packages/core/src/PowerSearch/PowerSearch.test.tsx,
packages/core/src/internal/tokenizer-presentation.test.ts,
@@ -53,15 +56,15 @@ system_specs:
# Tokenizer component contract
-| Area | Contract |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract | One optional `experimental` prop object whose `presentation` option selects the surface (DEC-3); the stable props, exports, and syntax are unchanged, and `TokenizerProps` stays an interface whose `ref` is `Ref<HTMLInputElement>`; only with `experimental` passed does the component accept a wider `ref`. The existing `hasEntriesOnFocus` mode has a defined post-selection lifecycle (DEC-2). |
-| Behavior | A committed empty-query bootstrap choice keeps remaining eligible loaded choices open, filters committed IDs, and advances the active option; terminal states close safely. The `bottom-sheet` presentation replaces the inline combobox with a trigger that opens one searchable modal sheet of checkbox rows (FR16–FR24). |
-| End-user impact | People selecting several loaded values can continue without reopening the menu, while disabled, loading, exhausted, and dismissed states remain non-interactive. On a compact touch screen, an opted-in field offers thumb-sized rows and a search field the keyboard does not cover. |
-| Builder impact | None for existing callers. A caller opts into the touch surface with `experimental={{presentation: 'adaptive'}}` or `'bottom-sheet'`, accepting that the option may change or be removed in a patch release. |
-| Compatibility/readiness | Omitting `experimental`, and the default `hasEntriesOnFocus={false}` path, keep today's inline combobox and direct single-select BaseTypeahead unchanged. DEC-2 is current and owner-approved with implementation and exact-head evidence pending; DEC-3 is current and implemented, with the implementation gap that the sheet presentation is not yet exposed: `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| Review checks | Reject implementations that filter by label instead of ID, reorder eligible choices, lose focus or a valid active descendant, refetch unnecessarily, or let disabled, exhausted, dismissed, or stale-loading states remain interactive or reopen. Reject a sheet presentation that switches without `experimental`, moves an existing row on toggle, or clears every token without confirmation. |
-| Governing rules | This canonical `component:Tokenizer` record: [FR13–FR24](#behavioral-and-layout-contract), [AR5–AR6](#accessibility-contract), [DEC-2](#dec-2--focus-bootstrap-supports-consecutive-committed-selections), and [DEC-3](#dec-3--the-touch-sheet-presentation-is-an-experimental-option). |
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | One optional `experimental` prop object whose `presentation` option selects the surface (DEC-3), a sheet that edits a draft committed by Save (DEC-4); the stable props, exports, and syntax are unchanged, and `TokenizerProps` stays an interface whose `ref` is `Ref<HTMLInputElement>`; only with `experimental` passed does the component accept a wider `ref`. The existing `hasEntriesOnFocus` mode has a defined post-selection lifecycle (DEC-2). |
+| Behavior | A committed empty-query bootstrap choice keeps remaining eligible loaded choices open, filters committed IDs, and advances the active option; terminal states close safely. The `bottom-sheet` presentation replaces the inline combobox with a trigger that opens one searchable modal sheet of checkbox rows that edit a draft committed by Save (FR16–FR24, FR26, FR27). |
+| End-user impact | People selecting several loaded values can continue without reopening the menu, while disabled, loading, exhausted, and dismissed states remain non-interactive. On a compact touch screen, an opted-in field offers thumb-sized rows and a search field the keyboard does not cover. |
+| Builder impact | None for existing callers. A caller opts into the touch surface with `experimental={{presentation: 'adaptive'}}` or `'bottom-sheet'`, accepting that the option may change or be removed in a patch release. |
+| Compatibility/readiness | Omitting `experimental`, and the default `hasEntriesOnFocus={false}` path, keep today's inline combobox and direct single-select BaseTypeahead unchanged. DEC-2 is current and owner-approved with implementation and exact-head evidence pending; DEC-3 is current and implemented, with the implementation gap that the sheet presentation is not yet exposed: `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. DEC-4 is current with the implementation gap that Core's sheet commits each edit at once; the draft, Save, pinned footer, and discard confirmation of FR18, FR19, FR22–FR24, FR26, and FR27 are verified in the Lab prototype. |
+| Review checks | Reject implementations that filter by label instead of ID, reorder eligible choices, lose focus or a valid active descendant, refetch unnecessarily, or let disabled, exhausted, dismissed, or stale-loading states remain interactive or reopen. Reject a sheet presentation that switches without `experimental`, moves an existing row on toggle, clears every token without confirmation, changes `value` before Save, closes a changed draft without asking, or hides Clear all or Save while the person searches. |
+| Governing rules | This canonical `component:Tokenizer` record: [FR13–FR27](#behavioral-and-layout-contract), [AR5–AR6](#accessibility-contract), [DEC-2](#dec-2--focus-bootstrap-supports-consecutive-committed-selections), [DEC-3](#dec-3--the-touch-sheet-presentation-is-an-experimental-option), and [DEC-4](#dec-4--the-sheet-edits-a-draft-that-save-commits). |
## Intent
@@ -146,7 +149,9 @@ Consumer migration instructions belong in consumer docs and release notes.
query of its own.
- The sheet's dialog, scrim, gestures, snap behavior, and dismissal paths —
owned by `component:BottomSheet` and `family:overlay-dismissal`; its
- on-screen keyboard behavior — owned by `spec:AST-099`.
+ on-screen keyboard behavior — owned by `spec:AST-099`. This record owns
+ only which touch on the results moves focus off the sheet's search field
+ (FR18), not what the keyboard does when it does.
## Public concepts
@@ -194,36 +199,39 @@ it does not become an element or geometry escape hatch.
Each requirement identifies its basis. This current record defines the approved
package-internal contract while implementation and focused verification remain
pending. FR1–FR15 and FR25 describe the `popover` presentation, the inline combobox;
-FR16–FR24 describe the `experimental.presentation` option and its sheet
-presentation, which has no inline combobox, suggestion menu, or end lane.
-
-| 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 | `experimental.presentation` selects the surface. `popover`, the value when `experimental` or the option is omitted, is the inline combobox with its anchored suggestion menu, unchanged. `bottom-sheet` is the trigger and modal sheet of FR17–FR24 on every device. `adaptive` 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. `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 trigger 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 trigger keeps the 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 trigger, 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 control holds focus — 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 from the Lab prototype | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| FR17 | In the sheet presentation the control surface is one button, named by the field label, with `aria-haspopup="dialog"` and `aria-expanded`. It shows the selected tokens without remove controls, or the placeholder when empty, wraps tokens onto further lines, and keeps the inline field's block size for its `size` step. Activating it opens one tall modal BottomSheet named by the field label; the suggestion popover, inline input, and end lane do not render. 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; Lab touch-flow evidence; `spec:AST-085` | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| FR18 | The sheet is a single surface: a search row at the top using the panel search field the selection controls share, a scrolling list of rows, and, while the query is empty, a footer with Clear all and Done. There is no second sheet. 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`). Done closes the sheet; swipe, scrim, and Escape dismissal follow BottomSheet `purpose="info"`; each of those closes 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. | DEC-3; Lab touch-flow evidence; `component:BottomSheet` | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| FR19 | Each row is a `checkbox` named by the item label whose `aria-checked` mirrors membership in `value`. Activating an unchecked row commits an `add` change; a checked row commits a `remove` change; both apply immediately and are announced with the inline field's words through the sheet's own live region (AR6). Row order is stable while the sheet is open: the items selected when it opened, in `value` order, then 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; Lab touch-flow evidence | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| 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; Lab touch-flow evidence; `family:input-fields` | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| 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; Lab touch-flow evidence | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| FR22 | With `hasCreate`, a non-empty trimmed query that matches no selected id, no 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 commits a `create` change whose item has the text as both id and label, 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 at `maxEntries`. | DEC-3; Lab touch-flow evidence; `hasCreate` contract of the inline field | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| FR23 | At `maxEntries`, 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`). | DEC-3; Lab touch-flow evidence; `spec:AST-085` | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| FR24 | Clear all is disabled while `value` 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 an AlertDialog confirmation naming the field; confirming commits `[]` with a `remove` change naming the last selected item, closes the confirmation, and — once the confirmation has closed — moves focus to the sheet's search field, the destination this record names (`spec:AST-085/FR4`): the clear is spent, and the search field is where the next selection starts (WCAG 2.2 SC 2.4.3 through `spec:AST-020/FR1`), and announces "All items removed" inside the sheet (AR6); cancelling changes nothing and focus returns to Clear all. | DEC-3; Lab touch-flow evidence | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
-| 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 |
+FR16–FR24, FR26, and FR27 describe the `experimental.presentation` option
+and its sheet presentation, which has no inline combobox, suggestion menu, or
+end lane.
+
+| 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 | `experimental.presentation` selects the surface. `popover`, the value when `experimental` or the option is omitted, is the inline combobox with its anchored suggestion menu, unchanged. `bottom-sheet` is the trigger and modal sheet of FR17–FR24, FR26, and FR27 on every device. `adaptive` 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. `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 trigger 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 trigger keeps the 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 trigger, 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 control holds focus — 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 from the Lab prototype | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| FR17 | In the sheet presentation the control surface is one button, named by the field label, with `aria-haspopup="dialog"` and `aria-expanded`. It shows the selected tokens without remove controls, or the placeholder when empty, wraps tokens onto further lines, and 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 it opens one tall modal BottomSheet named by the field label; the suggestion popover, inline input, and end lane do not render. 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; Lab touch-flow evidence; `spec:AST-085` | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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 off it without clearing the query — a focus rule of the sheet's, so the rows the person reaches for come into view; 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; Lab touch-flow evidence; `component:BottomSheet` | Implementation gap: Core's sheet does not match this row yet — its footer renders only while the query is empty, its closing action is Done, its search field is the borderless panel field, and a results drag does not move focus off the search; the row's behavior is the Lab prototype's, verified in `packages/lab/src/MobileTokenizer/MobileTokenizer.test.tsx`. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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; Lab touch-flow evidence | Implementation gap: Core's sheet does not match this row yet — a toggle commits an `add` or `remove` change through `onChange` at once; the row's behavior is the Lab prototype's, verified in `packages/lab/src/MobileTokenizer/MobileTokenizer.test.tsx`. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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; Lab touch-flow evidence; `family:input-fields` | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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; Lab touch-flow evidence | Verified current behavior through the internal entry. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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; Lab touch-flow evidence; `hasCreate` contract of the inline field | Implementation gap: Core's sheet does not match this row yet — the Add action commits a `create` change through `onChange` at once; the row's behavior is the Lab prototype's, verified in `packages/lab/src/MobileTokenizer/MobileTokenizer.test.tsx`. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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; Lab touch-flow evidence; `spec:AST-085` | Implementation gap: Core's sheet does not match this row yet — the limit is read against `value`, since there is no draft, and Save does not exist; the row's behavior is the Lab prototype's, verified in `packages/lab/src/MobileTokenizer/MobileTokenizer.test.tsx`. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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, moves focus to the sheet's search field, the destination this record names (`spec:AST-085/FR4`): the clear is spent, and the search field is where the next selection starts (WCAG 2.2 SC 2.4.3 through `spec:AST-020/FR1`), and announces "All items removed" inside the sheet (AR6); cancelling changes nothing and focus returns to Clear all. Clear all stays visible and reachable while searching, since the footer is pinned (FR18). | DEC-3; Lab touch-flow evidence | Implementation gap: Core's sheet does not match this row yet — confirming commits `[]` through `onChange` at once, the confirmation is an AlertDialog, and Clear all leaves with the footer while searching; the row's behavior is the Lab prototype's, verified in `packages/lab/src/MobileTokenizer/MobileTokenizer.test.tsx`. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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; the Lab prototype's draft and Save | Implementation gap: Core's sheet does not match this row yet — there is no draft: every edit commits through `onChange` at once and the closing action is Done; the row's behavior is the Lab prototype's, verified in `packages/lab/src/MobileTokenizer/MobileTokenizer.test.tsx`. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
+| 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; the Lab prototype's discard confirmation | Implementation gap: Core's sheet does not match this row yet — a dismissal always closes, and the sheet's confirmation is an AlertDialog with a ghost safe action and no scrim dismissal; the Lab prototype's confirmation has the shape, order, and focus of this row but renders its two actions as plain buttons, so the action-group sentence is met by neither yet; the row's behavior is the Lab prototype's, verified in `packages/lab/src/MobileTokenizer/MobileTokenizer.test.tsx`. Implementation gap: the sheet presentation is implemented but not yet exposed; `TokenizerProps` offers no `experimental.presentation` while its user experience is being finished, and every field renders the popover presentation. |
### Allowed variation
@@ -247,9 +255,9 @@ presentation, which has no inline combobox, suggestion menu, or end lane.
mechanism. That mechanism must preserve FR13–FR15, must not become public API,
and must not change direct single-select BaseTypeahead behavior.
- **AV7 — Sheet surface composition.** The sheet presentation may compose
- BottomSheet, the shared panel search field, EmptyState, AlertDialog, and the
- checkbox indicator in any internal structure, and may load that surface on
- demand, provided FR16–FR24, AR6, and PR6 hold and the structure stays within
+ BottomSheet, the shared panel search field, EmptyState, a confirmation
+ dialog, and the checkbox indicator in any internal structure, and may load
+ that surface on demand, provided FR16–FR24, FR26, FR27, AR6, and PR6 hold and the structure stays within
`architecture:component-style-authoring` INV7 — minimal DOM, content
rendered once; at rest, a pointer-specific presentation is a change of
attributes and styles on the same elements; open, in INV7's words, "the
@@ -280,10 +288,10 @@ presentation, which has no inline combobox, suggestion menu, or end lane.
| LTR or RTL | Physical proximity selects an edge only for a narrower surface; logical start wins ties and full-width placement. | Collision may move the final rendered surface. |
| SSR, hydration, or unmount | No server geometry read occurs; first client open prepares normally; unmount clears identities and pending show work. | Hydration timing may vary. |
| Sheet presentation, closed | The trigger shows the tokens or placeholder at the inline field's height for its `size`, `aria-expanded="false"`; no sheet content is interactive. | Token wrapping and placeholder text may vary. |
-| Sheet presentation, open | One tall modal sheet named by the label: search on top, stable-order checkbox rows, Clear all and Done while the query is empty. Focus is on the sheet's panel, not the search field. | Row count, batches, and empty states may vary. |
-| Sheet presentation, searching | The footer is absent; the list is busy until the search settles; rows filter to the query; the create row leads when `hasCreate` applies; a dead end shows the no-results empty state. | Debounce and result cap follow the props. |
+| Sheet presentation, open | One tall modal sheet named by the label: a bordered search field on top, stable-order checkbox rows editing a draft, and Clear all and Save pinned below in every state. Focus is on the sheet's panel, not the search field. | Row count, batches, and empty states may vary. |
+| Sheet presentation, searching | The footer stays pinned below the list with Clear all and Save; the list is busy until the search settles; rows filter to the query; the create row leads when `hasCreate` applies; a dead end shows the no-results empty state. | Debounce and result cap follow the props. |
| Sheet presentation, at `maxEntries` | Unchecked rows are `aria-disabled` and inert; checked rows toggle; no create row. | The disabled representation follows `spec:AST-085`. |
-| Sheet presentation, dismissed | After a swipe, scrim, Escape, or Done close the query is empty and reported, so the next open lists the bootstrap set; focus is back on the trigger. A close forced by disabling keeps the query. | A dismissal that keeps a typed query for the next open, or that leaves focus on the page body, fails. |
+| Sheet presentation, dismissed | After Save, a clean swipe, scrim, or Escape close, or a confirmed discard, the query is empty and reported, so the next open lists the bootstrap set; focus is back on the trigger; only Save changed `value`. A close forced by disabling keeps the query and drops the draft. | A dismissal that keeps a typed query for the next open, or that leaves focus on the page body, fails. |
| Sheet presentation, `adaptive` resolution | Server and hydrating renders are the inline field; a compact coarse-pointer client swaps to the trigger in the first render after hydration, focus undisturbed, the box kept except an inline input row the tokens had wrapped. While closed the surface follows the shared compact-touch query; an open surface keeps its presentation until it closes. | The query is shared, not Tokenizer-owned. |
### Transformation and precedence order
@@ -400,18 +408,19 @@ presentation.
The first six rows describe the `popover` presentation; the sheet rows describe
the sheet presentation.
-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------- | ------------------- |
-| Outer field/control surface | Contains tokens, input, and end controls; remains the full-width placement and safe fallback anchor. | Current Tokenizer source | Prominent | FR1–FR4, FR7, FR9 |
-| Token chips | Present selected values and removal; an activated token/control may become the per-open opening control. | Token component or custom renderer | Prominent | FR6, FR8, AR2–AR3 |
-| Search input | Remains one mounted combobox node and is the add/search opening control while geometrically usable. | Current Tokenizer/BaseTypeahead source | Prominent | FR1, FR5, FR7–FR8 |
-| Suggestion menu | Retains current outer-field anchoring and exact preferred `menuWidth`; focus bootstrap keeps only eligible choices and a valid active option. | Current BaseTypeahead source | Prominent | FR2, FR13–FR15, AR5 |
-| Overflow placeholder/layer | Preserves a usable outer-field fallback while live content may reparent or collapse. | Current Tokenizer/Layer composition | Supporting | FR3, FR7–FR8 |
-| Dependent narrower surface | Uses the descriptor only after its owning component resolves a width narrower than the field. | Consuming component plus Layer | Prominent | FR9–FR12 |
-| Sheet trigger | The field's control surface in the sheet presentation: tokens or placeholder, the inline field's size step, opens the sheet. | Tokenizer source; Token | Prominent | FR17, AR6 |
-| Sheet search row | The shared panel search field at the top of the sheet; filters rows and the create row. | Shared panel search field | Prominent | FR18, FR20, FR22 |
-| Sheet rows | Full-width checkbox rows with a trailing indicator; stable order while open; disabled at the limit. | Tokenizer source; checkbox indicator | Prominent | FR19, FR21, FR23 |
-| Sheet footer | Equal-width large Clear all and Done while the query is empty; Clear all confirms through an AlertDialog. | Button; AlertDialog | Supporting | FR18, FR24 |
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------- | ---------------------- |
+| Outer field/control surface | Contains tokens, input, and end controls; remains the full-width placement and safe fallback anchor. | Current Tokenizer source | Prominent | FR1–FR4, FR7, FR9 |
+| Token chips | Present selected values and removal; an activated token/control may become the per-open opening control. | Token component or custom renderer | Prominent | FR6, FR8, AR2–AR3 |
+| Search input | Remains one mounted combobox node and is the add/search opening control while geometrically usable. | Current Tokenizer/BaseTypeahead source | Prominent | FR1, FR5, FR7–FR8 |
+| Suggestion menu | Retains current outer-field anchoring and exact preferred `menuWidth`; focus bootstrap keeps only eligible choices and a valid active option. | Current BaseTypeahead source | Prominent | FR2, FR13–FR15, AR5 |
+| Overflow placeholder/layer | Preserves a usable outer-field fallback while live content may reparent or collapse. | Current Tokenizer/Layer composition | Supporting | FR3, FR7–FR8 |
+| Dependent narrower surface | Uses the descriptor only after its owning component resolves a width narrower than the field. | Consuming component plus Layer | Prominent | FR9–FR12 |
+| Sheet trigger | The field's control surface in the sheet presentation: tokens or placeholder, the inline field's size step, opens the sheet. | Tokenizer source; Token | Prominent | FR17, AR6 |
+| Sheet search row | The shared panel search field at the top of the sheet, drawn as a bordered input box and fixed above the scrolling list; filters rows and the create row. | Shared panel search field | Prominent | FR18, FR20, FR22 |
+| Sheet rows | Full-width checkbox rows with a trailing indicator, editing the sheet's draft; stable order while open; disabled at the limit. | Tokenizer source; checkbox indicator | Prominent | FR19, FR21, FR23, FR26 |
+| Sheet footer | Equal-width large Clear all and Save, pinned below the list in every state; Clear all confirms through the sheet's confirmation; Save commits the draft. | Button; the sheet's confirmation dialog | Supporting | FR18, FR24, FR26 |
+| Sheet confirmation | One dialog shape for Clear all and for discarding a changed draft: title, description, and one action group (`family:action-groups`) of two separated full-width actions — the destructive action then the safe action in reading order, the safe action focused first. | Dialog; Button | Supporting | FR24, FR27 |
This contract adds no target, state, or visual styling contract. The sheet
presentation exposes the field's existing `tokenizer` target on the trigger;
@@ -466,18 +475,18 @@ become Tokenizer policy.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1–FR3 | Existing Tokenizer/BaseTypeahead unit tests plus source inspection | empty, tokens, remove, clear, max, wrapping, both overflow modes | Input remounts, suggestion menu changes anchor/width semantics, or overflow ownership is misstated. | `audit:Tokenizer/current` |
-| FR4–FR8 | Focused descriptor identity/capture tests when implemented | add, default/custom token edit, max, hidden layer, reparent, stale node, unmount, SSR | Descriptor leaks publicly, captures a transient result/pointer, misses custom controls, or uses unusable geometry. | `audit:Tokenizer/opening-anchor` |
-| FR9–FR12 | Layer unit tests and real-Chromium geometry checks when implemented | full/equal/narrow surface, start/end/tie, LTR/RTL, collision, stale fallback | Full-width follows inner input, tie is physical, collision runs early, or stale identity flashes. | `audit:Tokenizer/placement` |
-| FR13–FR15, AR5 | Focused Tokenizer/BaseTypeahead tests and exact-head Chromium interaction evidence | pointer/keyboard commit, first/middle/last choice, rejected/deferred control, loading, disabled, max, exhaustion, Escape, Tab, outside focus | Selected values remain available, order changes, focus leaves the combobox, active descendant names no option, stale work reopens, or a terminal state stays interactive. | `audit:Tokenizer/multi-select` |
-| PR1–PR5 | Instrumented reads, pending-frame cleanup tests, and first-frame Chromium capture | open, close before frame, reopen opposite side, resize while open | Render-time/repeated reads, observer/pointer tracking, uncancelled frame, or first-frame jump occurs. | `audit:Tokenizer/performance` |
-| AR1–AR5 | Existing interaction suites plus focused pointer/keyboard/browser checks; native-disabled assertions pending conformance (`spec:AST-085`) | add/edit, focus/refocus, overflow, disabled, dismissal, retained bootstrap selection | Modality changes placement, semantics/focus regress, active descendant becomes invalid, or visible placement is wrong before fallback. | `audit:Tokenizer/accessibility` |
-| AR7 | Focused Tokenizer tests, inline and sheet, and the PowerSearch test | inline Clear all; a localized catalog; a Clear all confirmed in the sheet counted across every live region; PowerSearch's own words | The inline Clear all is silent, speaks words other than its catalog message, a sheet Clear all is announced twice, or PowerSearch speaks Tokenizer's words. | `audit:Tokenizer/accessibility` |
-| FR16–FR24, AR6, PR6 | Focused Tokenizer sheet tests with the compact-touch query stubbed both ways, a server-render-then-hydrate test, plus real-engine touch evidence | default popover, forced sheet, adaptive both ways, `adaptive` server-rendered as the combobox and hydrated without a recoverable error, then the trigger on a coarse-pointer client with the body still active, with `hasAutoFocus` the autofocused input's focus on the trigger after the swap and no `onBlur`/`onFocus` reported, the trigger's box against the hydrating field's at 390 and 414px, base props and ref on the trigger, the trigger's description in the inline input's order — a disabled trigger with `disabledMessage`, `description` and a status exposing the caller's ids, the description, the status message and the reason before the count and the tokens —, inert-prop warning, pending search, in-sheet announcements of toggles, busy start, result count and the rendered empty outcome, the confirmed Clear all announced once the confirmation has closed, a below-threshold query, a rejecting source, focus on the panel at open, the query cleared by a swipe, scrim, or Escape close, focus after a presentation change with the sheet closed, focus after the create row, focus after a confirmed Clear all, a spent Clear all focusable with `aria-disabled` and no action, focus after a settled search removes the focused row, no busy feedback or busy-start announcement on open with an instant source, only the search field — no list, no message, no announcement — for an empty query with nothing to list (a search-only source, nothing selected), and the list once a query finds items, element counts under a fine and a coarse pointer at rest and open (Chromium, Experimental stories: adaptive 154/120 at rest — the closed trigger in place of the inline field, a different element that stays under the fine count — and 157/165 open at the query "e" with no footer, the coarse total reconciled as rest − the re-hosted surfaces host + the dialog of 47 by part, forced sheet 114/114 and 165/165; the two owner exceptions DEC-3 records beyond the FR60 allowance, with before and after counts), no confirmation dialog in the DOM while none is pending, the query kept across a disabled-forced close, `aria-setsize`/`aria-posinset` on each row's `listitem` and the next batch on focus reaching the last rendered row, open/toggle/reopen order, create, batches, limit, Clear all, disabled while open, focus return | A field without `experimental` changes, a toggle moves a row, Clear all skips confirmation, the limit disables checked rows, or the popover bundle carries the sheet. | `audit:Tokenizer/sheet` |
-| FR25 | `Tokenizer.test.tsx` press-inside case; `component:BaseTypeahead` FR12's verification | Press in the input, press elsewhere | A press in the input that closes the list, or a press elsewhere that leaves it open, fails. | — |
-| Record structure | `scripts/check-knowledge.mjs` | Template-v3 current record and current-only frontmatter links | Invalid metadata, authority, or relationship references fail repository validation. | `audit:Tokenizer/knowledge` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1–FR3 | Existing Tokenizer/BaseTypeahead unit tests plus source inspection | empty, tokens, remove, clear, max, wrapping, both overflow modes | Input remounts, suggestion menu changes anchor/width semantics, or overflow ownership is misstated. | `audit:Tokenizer/current` |
+| FR4–FR8 | Focused descriptor identity/capture tests when implemented | add, default/custom token edit, max, hidden layer, reparent, stale node, unmount, SSR | Descriptor leaks publicly, captures a transient result/pointer, misses custom controls, or uses unusable geometry. | `audit:Tokenizer/opening-anchor` |
+| FR9–FR12 | Layer unit tests and real-Chromium geometry checks when implemented | full/equal/narrow surface, start/end/tie, LTR/RTL, collision, stale fallback | Full-width follows inner input, tie is physical, collision runs early, or stale identity flashes. | `audit:Tokenizer/placement` |
+| FR13–FR15, AR5 | Focused Tokenizer/BaseTypeahead tests and exact-head Chromium interaction evidence | pointer/keyboard commit, first/middle/last choice, rejected/deferred control, loading, disabled, max, exhaustion, Escape, Tab, outside focus | Selected values remain available, order changes, focus leaves the combobox, active descendant names no option, stale work reopens, or a terminal state stays interactive. | `audit:Tokenizer/multi-select` |
+| PR1–PR5 | Instrumented reads, pending-frame cleanup tests, and first-frame Chromium capture | open, close before frame, reopen opposite side, resize while open | Render-time/repeated reads, observer/pointer tracking, uncancelled frame, or first-frame jump occurs. | `audit:Tokenizer/performance` |
+| AR1–AR5 | Existing interaction suites plus focused pointer/keyboard/browser checks; native-disabled assertions pending conformance (`spec:AST-085`) | add/edit, focus/refocus, overflow, disabled, dismissal, retained bootstrap selection | Modality changes placement, semantics/focus regress, active descendant becomes invalid, or visible placement is wrong before fallback. | `audit:Tokenizer/accessibility` |
+| AR7 | Focused Tokenizer tests, inline and sheet, and the PowerSearch test | inline Clear all; a localized catalog; a Clear all confirmed in the sheet counted across every live region; PowerSearch's own words | The inline Clear all is silent, speaks words other than its catalog message, a sheet Clear all is announced twice, or PowerSearch speaks Tokenizer's words. | `audit:Tokenizer/accessibility` |
+| FR16–FR24, FR26, FR27, AR6, PR6 | Focused Tokenizer sheet tests with the compact-touch query stubbed both ways, a server-render-then-hydrate test, the Lab prototype's MobileTokenizer tests for the draft, Save, pinned footer, discard confirmation, and results-drag rows, plus real-engine touch evidence | default popover, forced sheet, adaptive both ways, `adaptive` server-rendered as the combobox and hydrated without a recoverable error, then the trigger on a coarse-pointer client with the body still active, with `hasAutoFocus` the autofocused input's focus on the trigger after the swap and no `onBlur`/`onFocus` reported, the trigger's box against the hydrating field's at 390 and 414px, base props and ref on the trigger, the trigger's description in the inline input's order — a disabled trigger with `disabledMessage`, `description` and a status exposing the caller's ids, the description, the status message and the reason before the count and the tokens —, inert-prop warning, pending search, in-sheet announcements of toggles, busy start, result count and the rendered empty outcome, the confirmed Clear all announced once the confirmation has closed, a below-threshold query, a rejecting source, focus on the panel at open, the query cleared by a swipe, scrim, or Escape close, focus after a presentation change with the sheet closed, focus after the create row, focus after a confirmed Clear all, a spent Clear all focusable with `aria-disabled` and no action, focus after a settled search removes the focused row, no busy feedback or busy-start announcement on open with an instant source, only the search field — no list, no message, no announcement — for an empty query with nothing to list (a search-only source, nothing selected), and the list once a query finds items, element counts under a fine and a coarse pointer at rest and open (Chromium, Experimental stories: adaptive 154/120 at rest — the closed trigger in place of the inline field, a different element that stays under the fine count — and 157/165 open at the query "e" with no footer, the coarse total reconciled as rest − the re-hosted surfaces host + the dialog of 47 by part, forced sheet 114/114 and 165/165; the two owner exceptions DEC-3 records beyond the FR60 allowance, with before and after counts), no confirmation dialog in the DOM while none is pending, the query kept across a disabled-forced close, `aria-setsize`/`aria-posinset` on each row's `listitem` and the next batch on focus reaching the last rendered row, open/toggle/reopen order, create, batches, limit, Clear all, disabled while open, focus return, `value` unchanged through toggles, create, and Clear all until Save, Save with an unchanged draft reporting nothing and with a changed one reporting the whole draft and the last holding edit, a clean dismissal closing directly, a dirty dismissal asking — Keep editing back to the search field, Discard changes closing without a report —, the footer present while searching, Save disabled over the limit, a results drag moving focus off the search with the query kept | A field without `experimental` changes, a toggle moves a row, a toggle, the create row, or a confirmed Clear all changes `value` before Save, Save reports more than one change or reports when the draft is unchanged, a swipe, scrim, or Escape closes a changed draft without the discard confirmation or asks on an unchanged one, Save or Clear all leaves while the query is non-empty, Clear all skips confirmation, the limit disables checked rows, or the popover bundle carries the sheet. | `audit:Tokenizer/sheet` |
+| FR25 | `Tokenizer.test.tsx` press-inside case; `component:BaseTypeahead` FR12's verification | Press in the input, press elsewhere | A press in the input that closes the list, or a press elsewhere that leaves it open, fails. | — |
+| Record structure | `scripts/check-knowledge.mjs` | Template-v3 current record and current-only frontmatter links | Invalid metadata, authority, or relationship references fail repository validation. | `audit:Tokenizer/knowledge` |
## Decision log
@@ -548,11 +557,12 @@ targets while the option is experimental (`spec:AST-017/FR27`); sheet targets
follow the option's promotion.
The sheet surface is one tall modal BottomSheet opened by a trigger that shows
-the selected tokens: a search row on top, checkbox rows whose order is fixed
-while the sheet is open and regrouped selected-first on the next open,
-progressive rendering of long lists, a create row with a trailing Add action,
-and a footer with a confirmed Clear all and Done. The sheet is a standalone
-BottomSheet driven by `isOpen`. Rejected: switching surfaces automatically on
+the selected tokens in the inline field's box: a bordered search field on top,
+checkbox rows whose order is fixed while the sheet is open and regrouped
+selected-first on the next open, progressive rendering of long lists, a create
+row with a trailing Add action, and a pinned footer with a confirmed Clear all
+and Save; the rows edit a draft that Save commits (DEC-4). The sheet is a
+standalone BottomSheet driven by `isOpen`. Rejected: switching surfaces automatically on
`pointer: coarse` without an opt-in (changes stable behavior). Rejected: a
top-level stable `presentation` prop before the surface has consumer evidence.
Rejected: separate manage and add sheets (two near-duplicate lists; the person
@@ -575,15 +585,14 @@ has more elements than the open popover menu it replaces under a fine pointer,
because it is a different surface, not the same one restyled: a full-height modal with a
panel and handle, a search field with its clear action, a list whose rows are
checkbox rows with an indicator and a position, a footer with Clear all and
-Done, and the sheet's own live region, in place of an anchored listbox of
+Save, and the sheet's own live region, in place of an anchored listbox of
plain options; the Clear all confirmation is in the DOM only from the Clear
all press until it closes. Measured in Chromium 149 on the
Experimental: adaptive story (five tokens selected), elements under `body`,
fine = desktop 1280×800 `pointer: fine`, coarse = iPhone 13 profile
`pointer: coarse`. At rest: 154 fine / 120 coarse (the trigger with its tokens
is smaller than the inline field with its token remove actions and input).
-Open, at the query "e" — a searching state, so the footer is not rendered
-(FR18): 157 fine — the inline field with its anchored menu open on the one
+Open, at the query "e" — a searching state: 157 fine — the inline field with its anchored menu open on the one
story item matching "e", plus the two shared page live regions the first
announcement creates — and 165 coarse. The coarse total reconciles exactly:
120 at rest, minus the 2 elements of the app-global surfaces host (the
@@ -592,14 +601,47 @@ the sheet's dialog of 47 — BottomSheet's dialog, panel, handle and edge tint
7; the sheet body 2; the search row with its clear action 19; the list 16
(the list element, its scroll host, and two checkbox rows of 7 with indicator
and position); the sheet's live region 1; the re-hosted surfaces host 2. A
-pending Clear all confirmation adds 20 while it is open; the footer, shown
-only while the query is empty, adds 9. The forced `bottom-sheet` presentation
+pending Clear all confirmation adds 20 while it is open; the footer adds 9
+(the counts above are of the implementation as it stands, whose footer
+renders only while the query is empty; with the pinned footer of FR18 the open
+coarse count includes those 9 in every state, and the counts are re-measured
+when the implementation matches). The forced `bottom-sheet` presentation
renders the same elements under either pointer (114 at rest, 165 open at "e",
its dialog 53 with the story's create row of 6). At rest the coarse pointer
never has more elements than the fine one: nothing of the sheet is in the DOM
until a press. The exception covers the closed `adaptive` trigger and the open sheet; its
counts are re-measured when either surface changes.
+### DEC-4 — The sheet edits a draft that Save commits
+
+**Reference:** `component:Tokenizer/DEC-4`
+**Decider:** `imdreamrunner`, `2026-11-02`
+
+Implementation gap: Core's sheet commits each edit at once and closes with
+Done; the draft, Save, the pinned footer, and the discard confirmation are the
+Lab prototype's behavior, which this record states as the contract
+(FR18, FR19, FR22–FR24, FR26, FR27). The hold-back of DEC-3 stands until the
+implementation matches.
+
+The sheet edits a draft: every row toggle, create, and Clear all changes the
+selection the sheet shows, and `value` changes once, when Save reports the
+draft through `onChange` with the last net edit as its `change` (FR26). A
+dismissal with a changed draft asks before discarding; a clean one closes
+(FR27). The footer with Clear all and Save is pinned below the list in every
+state, so the actions do not leave while the person searches, and the search
+field is a bordered input fixed above the list, so the sheet reads as a form:
+a field, a list, two actions. On a touch screen a direct drag on the results
+moves focus off the search field without clearing the query, so the rows the
+person reaches for come into view (the keyboard follows, `spec:AST-099`). The closed trigger is the inline field's own box,
+so a page that uses the inline field on desktop and the sheet on touch shows
+one field. Rejected: committing each toggle at once (a mis-tap is live before
+the person has seen the result, a dismissal has nothing to discard, and a
+caller observing `onChange` sees a burst of partial selections). Rejected: a
+footer only while the query is empty (Save and Clear all vanish exactly when
+the person has been typing). Rejected: a Done that closes without a draft
+(the sheet then has no way to abandon an edit). Rejected: clearing the query
+on a results drag (the person loses the search they made to reach those rows).
+
## Open questions
- Should the sheet rows and trigger honor `renderItem` and `renderToken`, or