An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 3 kind: component id: component:Tokenizer authority: current archive_reason: null superseded_by: null approved_by: imdreamrunner approved_at: 2026-11-03 owners: [cixzhang] review_triggers: [public-api, behavior, layout, accessibility] 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/core/src/internal/SheetConfirmation.test.tsx, packages/core/src/internal/useDismissSearchOnTouchDrag.test.tsx, packages/core/src/internal/sheetDraft.test.ts, packages/core/src/Tokenizer/Tokenizer.props-type.test.tsx, packages/core/src/Tokenizer/Tokenizer.composites.test.tsx, packages/core/src/Tokenizer/tests/TokenizerSheetField.a11y.chromium.spec.ts, packages/core/src/PowerSearch/PowerSearch.test.tsx, packages/core/src/Typeahead/Typeahead.test.tsx, packages/core/src/Layer/useLayer.test.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [family:input-fields, family:overlay-dismissal] design_specs: [] architecture: [ architecture:interaction-modality, architecture:layer-runtime, architecture:public-component-api, ] contributing: [contributing:api-conventions] system_specs: [ spec:AST-002/DEC-1, spec:AST-003/FR18, spec:AST-009/FR8, spec:AST-012/FR9, spec:AST-017/FR3, spec:AST-017/FR22, spec:AST-017/FR23, spec:AST-017/FR60, spec:AST-020/FR1, spec:AST-056/FR3, spec:AST-058/FR9, spec:AST-085/FR1, spec:AST-085/FR4, spec:AST-085/FR5, spec:AST-086/FR14, spec:AST-094/FR13,
]
Tokenizer component contract
| Area | Contract |
|---|---|
| Public contract | A stable presentation prop, 'popover' | 'bottom-sheet' | 'adaptive' with adaptive the default, selects the surface (DEC-3); the sheet edits a draft committed by Save (DEC-4). TokenizerProps stays an interface whose ref keeps its released Ref<HTMLInputElement> type; the component also accepts Ref<HTMLInputElement | HTMLButtonElement>, because the ref reaches the sheet's trigger. 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 sheet presentation — bottom-sheet, and the default adaptive on a compact coarse-pointer screen — replaces the inline combobox with a field whose trigger 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, the field offers thumb-sized rows and a search field the keyboard does not cover. |
| Builder impact | None with a fine pointer or on a screen that is not compact. On a compact coarse-pointer screen a Tokenizer without presentation opens the sheet: onChange fires on Save, ref reaches the trigger, endContent and renderToken render as in the inline field, and the inline combobox's other props (renderItem, hasClear, hasEntriesOnFocus, menuWidth, tokenOverflowBehavior, hasAutoFocus) are not rendered. presentation="popover" keeps the inline combobox on every device. |
| Compatibility/readiness | The stable prop and its adaptive default ship together in a patch as [feat] (Compatibility and migration, DEC-3). With a fine pointer, on a screen that is not compact, on the server, and while hydrating, a field without presentation is the inline combobox, unchanged; the default hasEntriesOnFocus={false} path keeps 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. DEC-4 is current and implemented; the confirmation's actions are not yet one action group (FR27). |
| 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 a fine pointer or a screen that is not compact gets by default, that presentation="popover" does not prevent, that 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, AR5–AR6, DEC-2, DEC-3, and DEC-4. |
Intent
Tokenizer lets a person build and edit a set of searchable values as removable tokens around one stable combobox input. It owns the field surface, token/input layout, suggestion-menu relationship, and the package-internal identity needed to open a related surface from the control where the task began.
This record preserves shipped Tokenizer facts and defines three component-owned
contracts: one package-internal opening-control descriptor for Core peers, the
post-selection lifecycle of an empty-query bootstrap menu, and a touch
presentation, the default on compact coarse-pointer screens, in which a trigger
opens one searchable modal bottom sheet in place of the inline combobox. The descriptor lets Layer prepare placement without
exposing DOM refs, pointer coordinates, or width policy to consumers. component:PowerSearch consumes the descriptor; it is not authority for this
record.
Compatibility and migration
- The stable public API and the default
hasEntriesOnFocus={false}path are unchanged. - Compatibility class: intentional behavior correction for the existing opt-in
hasEntriesOnFocusmode. A committed selection from its current empty-query bootstrap cohort keeps the remaining eligible loaded choices available instead of closing the menu after every choice. - Controlled/uncontrolled ownership is unchanged. Retention follows committed controlled values; a proposed value that the caller has not accepted remains available.
- Stable presentation (DEC-3):
presentationis a stable prop, promoted from the experimental option (spec:AST-017/FR23). The API change is additive: the prop is new and optional, and no existing stable prop, type, or export is removed or narrowed. The experimental spelling,presentationinside theexperimentalprop, is removed and not kept as an alias: it was outside the stable compatibility promise, so its removal is an[experimental]patch change whose note names the replacement (spec:AST-017/FR22). For callers of that spelling,astryx upgraderewrites static uses and leaves a TODO where it cannot prove the rewrite, such as on a Tokenizer that spreads props (spec:AST-017/FR23). - Default change (DEC-3):
presentationdefaults toadaptive, a change of the releasedpopoverdefault, and the behavior changes only on compact coarse-pointer screens, which is whatadaptiveis for. With a fine pointer, on a screen that is not compact, on the server, and while hydrating, a field withoutpresentationrenders the inline combobox exactly as before (spec:AST-017/FR59). On a compact coarse-pointer screen it renders the sheet:onChangefires once on Save in place of once per selection,refreceives the trigger button, and the inline combobox's props other thanendContentandrenderTokenare not rendered.presentation="popover"keeps the previous behavior everywhere. The stable prop and this default ship together in a patch as[feat]: that release tier is a product decision of the engineering owner, with the agreement of the owner ofspec:AST-017(DEC-3). - Migration decision:
presentation="popover"restores the previous surface, input,onChangetiming, andrefelement on every device — the restoring inputspec:AST-017/DEC-23andarchitecture:public-component-api/INV16name. No codemod adds it, because adding it to every Tokenizer would opt every caller out of the new default. Existing callers that omithasEntriesOnFocus, typed search selection, explicit dismissal, disabled state, maximum-entry state, and source-loading behavior retain their prior boundaries.
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The token collection, stable native search input, and painted outer field/control surface that contains them.
- The lifecycle of Tokenizer's own focus-bootstrapped suggestion menu after a committed selection, including selected-value exclusion, next-option choice, focus continuity, and terminal close states.
- The active opening control for a task initiated within Tokenizer: the inner input for add/search work or the actual activated token/control for edit work.
- The identity, usability, lifetime, and safe fallback semantics of those elements in one package-internal descriptor.
- Tokenizer's current suggestion-menu width and minimum-anchor-width behavior.
- Token wrapping and the
none,unfocusedInline, andunfocusedLayeroverflow presentations. - The touch sheet presentation: its trigger, the single searchable sheet, the in-session row order, progressive long-list rendering, the create row, the confirmed Clear all, the draft with Save and the guard that asks before a changed draft is discarded (FR26, FR27, DEC-4), and which Tokenizer props the sheet honors.
Does not own / non-goals
- General BaseTypeahead selection policy. Direct single-select BaseTypeahead and Typeahead keep their select-clear-close-refocus lifecycle.
- A new rule for typed-query selection or a requirement to refetch suggestions after each Tokenizer selection.
- General anchor positioning, top-layer hosting, viewport collision, generated
anchor names, or prepared-placement lifecycle — owned by
architecture:layer-runtime. - PowerSearch editor sizing, including its proposed 400–720 CSS px range — owned
by
component:PowerSearchif that draft is approved. - A public input ref, opening-control ref, anchor descriptor, maximum menu width, coordinate, placement, or pointer-tracking API.
- A change to released
menuWidthsemantics. It remains an exact preferred pixel width whose rendered menu does not shrink below the Tokenizer outer field. - Consumer-provided token content and visuals. Tokenizer owns only the capture boundary needed to identify the control that activated an internal open.
- The compact-touch resolution rule behind
adaptive, owned byspec:AST-094/FR13(a touch presentation applies under a coarse primary pointer, after hydration; compact isspec:AST-012/FR9). Tokenizer resolvesadaptivewith that one rule, as the selection controls do; it adds no query of its own. - The sheet's dialog, scrim, gestures, snap behavior, and dismissal paths —
owned by
component:BottomSheetandfamily:overlay-dismissal; its on-screen keyboard behavior — owned byspec:AST-099. This record owns which touch on the results moves focus off the sheet's search field and where it goes (FR18), not what the keyboard does when it does, and what the sheet does with a dismissal while its draft is changed (FR27), not the gesture or its paths.
Public concepts
One stable public concept is introduced: the presentation prop, with the
values 'popover' | 'bottom-sheet' | 'adaptive' and adaptive the default,
typed by the exported TokenizerPresentation, the selection controls' value
set (DEC-3). Existing consumer props and
usage remain in Tokenizer.doc.mjs. The existing
hasEntriesOnFocus mode includes the component-owned post-selection behavior
in FR13–FR15.
In the sheet presentation the field's control box holds the trigger button, the tokens, and endContent, and carries the tokenizer theming target, its data-* state attributes, and the focus ring (:focus-within), as the inline field's box does. The trigger is the control: ref, id, the caller's data-* and aria-*, and the other base props reach it (family:input-fields/FR10,
architecture:public-component-api/INV8), handleRef.focus() and blur()
act on it, and onKeyDown reports its events. onFocus and onBlur report focus entering and leaving the field's box, which also holds endContent and a custom token's controls, as the inline field reports its wrapper. The
exported TokenizerProps remains an interface and keeps ref?: Ref<HTMLInputElement> as released, so interface X extends TokenizerProps<T>
and Omit<TokenizerProps<T>, …> wrappers keep compiling; the component's own
parameter type also accepts Ref<HTMLInputElement | HTMLButtonElement>. The
ref receives the trigger button in the sheet presentation and the combobox
input otherwise, so a ref typed for both elements describes what it holds. In the sheet
presentation endContent renders at the field's inline end and renderToken
renders the field's tokens, as in the inline field. The props that describe
only the inline combobox have no surface in the sheet presentation:
renderItem, hasClear (the sheet's own Clear all replaces it), hasEntriesOnFocus (the sheet always
lists the bootstrap set), menuWidth, tokenOverflowBehavior (the field
wraps its tokens), and hasAutoFocus. Passing one of them with the sheet presentation emits one
development-mode warning naming the prop and presentation="popover", so it
is not silently dropped
(architecture:public-component-api/INV3); every other prop keeps its
meaning.
The descriptor is package-internal. It must be absent from exported
TokenizerProps, public barrels, generated declarations, consumer docs, CLI
output, and Changesets. Current handleRef remains the public focus/blur handle;
it does not become an element or geometry escape hatch.
Behavioral and layout contract
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, FR26, and FR27 describe the presentation prop and its sheet
presentation, which has no inline combobox or suggestion menu; its end lane
holds 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 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 variation
- AV1 — Token presentation. Default Token controls and custom
renderTokencontent may differ visually. The opening-control capture boundary remains Tokenizer-owned when an identifiable descendant control initiates activation. - AV2 — Overflow presentation. Tokens may wrap normally, truncate while
unfocused, or move with the live input into
unfocusedLayer. These modes may change element geometry but not descriptor identity or fallback order. - AV3 — Internal representation. The descriptor may use refs, elements, callback registration, or an equivalent Core-private representation. It must preserve FR4–FR8 and stay out of public declarations.
- AV4 — Layer mechanism. Layer may realize the latched edge through a zero-size marker, separate size and position anchors, or another internal mechanism that satisfies FR9–FR12 and current Layer architecture.
- AV5 — Responsive movement. CSS may follow outer-field movement, container resize, writing direction, and collision while open. JavaScript does not remeasure or select a new preferred edge until the next open.
- AV6 — Internal retention mechanism. Tokenizer and BaseTypeahead may retain, project, or otherwise coordinate the settled cohort through a package-private 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, 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-authoringINV7 — 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 open layer under a coarse pointer has at most as many elements as under a fine pointer (beyond that, only by the open-layer allowancespec:AST-017FR60 and DEC-29 set)". The closedadaptivesheet field (different elements, which no allowance covers) and the open sheet (more than the five extra elements FR60 allows) are owner exceptions DEC-3 records, beyond that allowance, with their before and after counts.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Empty field | The mounted inner input is the opening control; a full-width menu stays aligned to the outer field. | Placeholder and bootstrap results may vary. |
| Focus bootstrap, choices remain | A committed selection is removed from the displayed cohort; the input and popup remain active on the next valid remaining choice. | Internal cohort storage and projection may vary. |
| Focus bootstrap, selected choice was last | The nearest preceding remaining choice becomes active without changing the displayed order. | Option identity representation may vary. |
| Focus bootstrap, no choices or max reached | The popup closes and no active descendant remains; pending work cannot reopen it. | Source cancellation mechanism may vary. |
| Source pending or replaced | Busy semantics identify pending work; stale work cannot add choices or reopen a terminal popup. | A settled current cohort may be retained internally. |
| Disabled | No choice can be committed; an open popup closes and clears its active descendant while disabled-reason focusability remains available where configured. | The disabled representation follows spec:AST-085. |
| One or many tokens | The same input remains after tokens and moves with wrapping; full-width placement does not follow that movement. | Token labels, wrapping rows, and custom content may vary. |
At maxEntries |
The input identity remains mounted but its zero-width/hidden box is unusable as geometry; opening falls back to the outer field. | Search remains unavailable under current behavior. |
| Token removal or clear | Input identity survives and current refocus behavior remains. | Token count and input position change. |
unfocusedInline |
Blurred OverflowList and focused direct-token layouts resolve the same live input identity; a collapsed input is not used as geometry. | Visible token count may vary with width. |
unfocusedLayer, focused |
The live wrapper/input may be reparented into the context layer without descriptor churn. | Corrective portal location may vary. |
unfocusedLayer, unfocused |
The hidden-layer input is unusable for a new open; the ordinary-flow outer-field fallback is used. | Placeholder token count may vary. |
| Default or custom token edit | The actual activated token/control is captured before edit state changes; if no usable descendant control exists, input then outer-field fallback applies. | Custom token markup may vary. |
| 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 field box shows the tokens or placeholder, and any endContent, at the inline field's height for its size; the trigger has 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: 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 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 (the default) |
Server and hydrating renders are the inline field; a compact coarse-pointer client swaps to the sheet field 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
- ORD1 — Surface width. Resolve the consuming component's preferred surface width. Tokenizer contributes no PowerSearch width value.
- ORD2 — Full-width decision. If the preferred surface width is greater than or equal to the outer field width, use the outer field and logical start. Do not read or apply opening-control geometry to choose an edge.
- ORD3 — Opening control. For a narrower surface, use the actual captured token/control when available; otherwise use the stable inner input; otherwise use the outer field at logical start.
- ORD4 — Edge selection. Compare the usable control with the outer field's physical start and end, choose the nearer edge, and map it to logical start/end. A tie resolves to logical start.
- ORD5 — Hidden commit. Commit width mode, anchor, and alignment while hidden; show on the next animation frame and latch the result until close.
- ORD6 — Collision. Apply Layer's CSS-owned viewport and safe-area collision behavior last. Collision does not reopen the semantic edge decision.
Performance and resources
- PR1 — No render-time measurement. Neither Tokenizer nor a descriptor consumer may read geometry during React render.
- PR2 — One read batch per open. Open preparation reads the outer field and, only when needed, the opening control in one batched read phase. Instrumented verification must fail on a second preparation batch for the same open.
- PR3 — Hidden preparation. Anchor, width mode, and alignment commit while the surface is hidden; show occurs on the next animation frame. Close or unmount before that frame cancels the pending show.
- PR4 — No continuous tracking. The contract adds no pointer tracking, always-on ResizeObserver, global resize listener, or repeated geometry read.
- PR5 — CSS owns ongoing geometry. Container resize, outer-field movement, writing-direction layout, and final collision remain CSS/Layer work after the one-time semantic choice.
- PR6 — The sheet surface costs only where it presents. A field that
resolves to
popover— by default, every field with a fine pointer or on a screen that is not compact — does not load the sheet surface's code; the surface loads on demand only while a field resolves tobottom-sheet, renders nothing on the server or during the hydrating render, and renders its long lists in batches (FR21).
Accessibility contract
AR1–AR5 and AR7 describe the popover presentation; AR6 describes the sheet
presentation.
- AR1 — Modality equivalence. The same input or token/control produces the same preferred placement for pointer, touch, keyboard, and programmatic activation. No pointer coordinate participates.
- AR2 — Semantic stability. The descriptor and placement work MUST NOT change Tokenizer's field, group, combobox, listbox, option, token, announcement, disabled, focus, or dismissal semantics.
- AR3 — Focus stability. Existing focus/refocus behavior survives add, remove, clear, overflow expansion/collapse, and related-surface open/close.
- AR4 — No visible placement error. A person MUST NOT see a surface first paint at an outer-start or stale position and then jump to its resolved edge. Invalid identity falls back before show rather than flashing or showing wrong.
- AR5 — Retained combobox semantics. While a focus-bootstrapped menu remains
open after selection, DOM focus MUST stay on the combobox,
aria-expandedMUST remain true, andaria-activedescendantMUST name the rendered next valid option. Closing for dismissal, disabled, maximum, or exhaustion MUST remove the active descendant. Selected and disabled options are never interactive. - AR6 — Sheet semantics. In the sheet presentation the trigger is a button
named by the field label with
aria-haspopup="dialog"andaria-expanded, and its accessible description is everything the inline input's is, in the inline input's order — the caller'saria-describedbyids, the fielddescription, the status message, and thedisabledMessagereason when disabled (a disabled control exposes its description and its reason on itself,spec:AST-085/FR5) — followed by the selected count and the selected token labels, so the selection the sighted person sees is exposed to assistive technology as the trigger's description; the labels are the rendered tokens themselves, each referenced by id fromaria-describedbyafter a hidden count, so no label renders twice (architecture:component-style-authoringINV7); a custom token fromrenderTokencan hold controls whose names would join the description, and the caller's markup cannot be referenced without them, so each custom token is described instead by a copy of its item label carrying thehiddenattribute, whicharia-describedbyreads and the accessibility tree leaves out, so each label is in the accessibility tree once (the INV7 exception below records the copies); whether a screen reader reads a description with the button depends on the screen reader (spec:AST-009/FR8), and the DOM and accessibility tree prove thearia-describedbyexposure (WCAG 2.2 SC 1.3.1 and 4.1.2 throughspec:AST-020/FR1); the sheet is a modal dialog named by the field label; the search field is namedSearch {label}with a named clear action; each row is acheckboxnamed by its item label witharia-checked, toggled by tap or click and by Space and Enter, the activation keys of the native button it is rendered on (spec:AST-020/FR15; WCAG 2.2 SC 2.1.1 and 4.1.2); disabled rows and a disabled trigger usearia-disabledand keep their focus order; while the sheet is open, additions, removals, a confirmed Clear all ("All items removed", made once the confirmation has closed, since a message sent while the confirmation covers the sheet is not heard —spec:AST-086/FR14), the search's busy start, and how each search ended — the result count for a non-empty query, or the empty state's text when it shows, both from the search's ownuseAnnounce({hasReplace: true})instance (spec:AST-086/FR9, FR13), so a newer one replaces one not yet spoken — are announced once per occasion from inside the sheet throughuseAnnounce, whichspec:AST-086/FR14routes into the persistent polite container of the sheet's own dialog while it is open, because the shared page-body channel is not exposed behind a native modal; the container follows FR3, FR5, and FR6 of that record (WCAG 2.2 SC 4.1.3 throughspec:AST-020/FR1). After the sheet closes focus returns to the trigger and the field's announcements follow the same FR14 route from wherever the field renders. - AR7 — Clear all is announced. In the
popoverpresentation, the field's Clear all, which empties every token at once and moves focus to the input, announces "All items removed" (@astryx.tokenizer.allRemoved, the words of the sheet's Clear all in AR6) the same way the field announces a token added or removed: politely, through the shared channel (spec:AST-086/FR2, FR5). It is announced once per Clear all (spec:AST-086/FR6); a Clear all confirmed in the sheet is announced by the sheet alone (AR6), and the field stays silent for it (WCAG 2.2 SC 4.1.3 throughspec:AST-020/FR9). A component that composes Tokenizer and words its own Clear all announces its own words instead (component:PowerSearch). In thepopoverpresentation, a component that composes Tokenizer and locks some tokens keeps them: Clear all removes only the other tokens and shows only while one exists, and Backspace removes nothing while the last token is locked (component:PowerSearchFR23).
Design relationships
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 field | The field's control box in the sheet presentation, with the inline field's size step, theming target, and focus ring: the trigger button, the tokens (default or renderToken) or the placeholder, and endContent in the end lane; the trigger 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 field's control box, as the inline field does;
the sheet's own parts carry no Tokenizer theming targets (DEC-3), and are
themed through the targets of the components they compose.
Family and system relationships
family:overlay-dismissalcontinues to own shared Escape and platform-close ordering for Tokenizer's BaseTypeahead/Layer surfaces.architecture:layer-runtimeowns generated anchor names, anchor composition, prepared placement, top-layer hosting, viewport collision, visibility reconciliation, and cleanup. Tokenizer supplies identity, not Layer mechanics.architecture:interaction-modalityowns shared modality state. Opening placement deliberately does not branch on that state.architecture:public-component-apiandspec:AST-002/DEC-1keep derivable geometry and package-peer identity out of Tokenizer's public API.- The current Typeahead draft records BaseTypeahead's layer delegation but does not own Tokenizer's token/input identity or the approved descriptor.
family:input-fieldsowns family-wide state display, behavior, appearance, size, end-control, disabled-reason, and status-placement policy. Tokenizer keeps its component-local token/input and source-loading behavior inside that boundary.component:PowerSearchdepends on the approved descriptor and owns its own editor width policy; it is not authority for Tokenizer.
Required implementation and browser evidence
The post-selection lifecycle must update the owning source, focused tests, consumer docs, and Changeset together. Exact-head browser evidence must exercise:
- Pointer and keyboard selection from a settled focus-bootstrap cohort, with the committed value removed, the popup still open, input focus preserved, and the next remaining option active.
- The fallback when the committed option was last, plus terminal closure for no
remaining choice and
maxEntries. - Escape, Tab or outside focus departure, transition to the disabled state, and pending or stale source settlement without a later reopen.
- The unchanged path when
hasEntriesOnFocusis off and direct single-select BaseTypeahead selection still closes.
The separate opening-control descriptor remains pending. When that descriptor and its Layer consumer ship, they must add screenshotable full/equal/narrow-width, wrapped-token, overflow-layer, LTR/RTL, collision, stale-fallback, and first-paint evidence. Instrumented verification must prove one geometry-read batch per open. PowerSearch's separate evidence owns its editor dimensions; those dimensions never 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, FR26, FR27, AR6, PR6 | Focused Tokenizer sheet tests with the compact-touch query stubbed both ways, a server-render-then-hydrate test, the sheet's draft, Save, pinned footer, discard confirmation and results-drag tests with the draft rule's unit tests, plus real-engine touch evidence | the default resolving both ways, popover kept on a compact coarse-pointer screen, Core's composites that render Tokenizer inline — PowerSearch's field and list value editors and Table's list filter — staying inline on a compact coarse-pointer screen, forced sheet, adaptive server-rendered as the combobox with the same markup as popover and hydrated without a recoverable error, then the sheet field 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 sheet field'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, the Adaptive (default) and Bottom sheet stories: adaptive 154/121 at rest — the closed sheet field in place of the inline field, different elements that stay under the fine count — and 157/166 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 115/115 and 166/166; 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 with a fine pointer or on a screen that is not compact changes by default, presentation="popover" presents the sheet, a Core composite's inline Tokenizer becomes a sheet trigger, 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
DEC-1 — Opening control is package-internal and read once per open
Reference: component:Tokenizer/DEC-1
Decider: cixzhang, 2026-08-31
Tokenizer provides Core peers a package-internal descriptor for stable outer-field and active opening-control identities. A consuming surface resolves its preferred width first: a surface at least as wide as the field aligns to the outer field at logical start; only a narrower surface may choose the nearer outer physical edge from a usable opening control, with logical start as the tie and safe fallback. The choice is modality-neutral and latched for one open lifetime.
Open preparation reads the outer field and, only when needed, the opening control in one batch, commits width mode, anchor, and alignment while hidden, shows on the next animation frame, and performs no continuous tracking. Tokenizer's public API remains unchanged. Implementation must provide real-Chromium open-state evidence for full-width and narrower placement, LTR and RTL, constrained collision, stale fallback, and the first paint without a visible jump.
DEC-2 — Focus bootstrap supports consecutive committed selections
Reference: component:Tokenizer/DEC-2
Decider: cixzhang, 2026-09-19
When hasEntriesOnFocus is enabled, committing a choice from the current settled
empty-query bootstrap cohort keeps the popup open with the remaining eligible
loaded choices. Committed values are excluded by SearchableItem.id; distinct
items with the same label remain eligible. The option after the committed choice
in displayed order becomes active; when there is no following choice, the nearest preceding choice becomes active. Input focus and valid combobox/listbox
ARIA relationships remain intact.
The popup closes and clears its active descendant when no eligible loaded choice
remains, maxEntries is reached, the control becomes disabled, focus leaves, or
the person dismisses it. Pending or stale source work cannot reopen a terminal
popup or make stale choices interactive. This decision adds no public API, does
not require a refetch, and does not change typed-query selection or direct
single-select BaseTypeahead behavior.
DEC-3 — The touch sheet is a stable presentation, and adaptive is the default
Reference: component:Tokenizer/DEC-3
Decider: imdreamrunner, 2026-11-03
Tokenizer offers its touch surface through a stable presentation prop, with
the values popover, bottom-sheet, and adaptive that the selection
controls use, and adaptive is the default: the sheet on a compact
coarse-pointer screen, where the inline combobox competes with the software
keyboard, and the inline combobox everywhere else. A caller's explicit value
wins on every device, and popover keeps the inline combobox, its
per-selection onChange, and its input ref (architecture:public-component-api
INV16). adaptive resolves through the shared compact coarse-pointer policy,
so a Tokenizer and a Selector on the same page switch together. The value set
is the selection controls' AdaptivePresentation, because Tokenizer picks
several items from a searchable list as MultiSelector does. The stable
prop and the adaptive default ship together in a patch release: the API
change is additive, the behavior changes only on compact coarse-pointer
screens, and presentation="popover" keeps the previous behavior everywhere.
That release tier is the engineering owner's product decision, made with the
agreement of cixzhang, an owner of spec:AST-017. Rejected:
keeping popover as the default, because a phone then gets the inline
combobox under the software keyboard unless the caller opts in
(component:Selector DEC-1 rejects the same default for the same reason).
Rejected: the date and time fields' PickerPresentation value set with
adaptive-bottom-sheet (its native-picker axis has no counterpart here). The
sheet's parts expose no Tokenizer theming targets; they are themed through the
components they compose.
The sheet surface is one tall modal BottomSheet opened by a trigger in the inline field's box, which shows the selected tokens and keeps endContent: 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: separate manage and add sheets (two near-duplicate lists; the person
loses their place). Rejected: hosting the one sheet in a BottomSheetSwitcher.
INV7 owner exception (architecture:component-style-authoring INV7;
spec:AST-017/FR60), in three parts, all beyond the FR60/DEC-29 allowance — which admits an open layer five extra elements and a closed control none — and recorded here with their measured counts as FR60 asks. The closed field under adaptive. INV7's
surface budget says a pointer-specific presentation is a change of attributes
and styles on the same elements; under adaptive on a compact coarse-pointer
client the closed field instead renders different elements — the field box holding the trigger button and the selected tokens — in place of the inline combobox input,
its token remove actions, and its overflow handling, because the touch surface
is a sheet opened by a button, not a menu anchored to an input (DEC-3, FR16).
The swap removes elements rather than adding them: at rest 154 elements under a fine pointer against 121 under a coarse one, measured as below, so the coarse
pointer stays under the fine count at rest. The open layer. The open sheet
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
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
Adaptive (default) story (five tokens selected), elements under body,
fine = desktop 1280×800 pointer: fine, coarse = iPhone 13 profile
pointer: coarse. At rest: 154 fine / 121 coarse (the field box with its trigger and tokens is smaller than the inline field with its token remove actions and input).
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 166 coarse. The coarse total reconciles exactly:
121 at rest, minus the 2 elements of the app-global surfaces host (the
toast host the open modal re-hosts inside itself, spec:AST-003/FR18), plus
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, pinned
in every state (FR18), adds 9, so the open coarse count at the query "e" is 175 with it; the counts are re-measured when either surface changes. The forced bottom-sheet presentation
renders the same elements under either pointer (115 at rest, 175 open at "e",
its dialog 62 with the create row of 6 and the pinned footer of 9). At rest the coarse pointer
never has more elements than the fine one: nothing of the sheet is in the DOM
until a press. Custom-token label copies. With renderToken, the closed sheet field renders one extra element per selected token: a hidden span holding the item label, which the trigger's description references in place of the caller's token markup (AR6). The copy is outside the accessibility tree, so its label is announced once. Measured in Chromium 149 on the Bottom sheet with end content and custom tokens story (four tokens) at 390px: 153 elements under body at rest, four of them the copies, and each label once in the story's accessibility tree. The exception covers the closed adaptive trigger, the open sheet, and the custom-token copies; 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
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 sheet field 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 honor
renderItem, or stay with the default row rendering they have now? Today they stay with the default, as the Public concepts section records. - The opening-control descriptor implementation remains pending; the post-selection lifecycle has no unresolved decision.
Content boundary
This file does not duplicate consumer prop tables, usage examples, search
algorithms, implementation code, current audit results, PowerSearch editor sizing,
shared Layer mechanics, BottomSheet's own dialog and gesture contract, or the
sheet's on-screen keyboard behavior (spec:AST-099). Consumer docs and release
notes project only the approved component behavior.