An open source design system that's fully customizable and agent ready
TypeScript
feat(Tokenizer): presentation is a stable prop, and adaptive is its default (#9796)
Xinzi Zhoudcf3d6f86713
diff --git a/.changeset/tokenizer-presentation-codemod.md b/.changeset/tokenizer-presentation-codemod.mdnew file mode 100644index 0000000000..5a02647a57--- /dev/null+++ b/.changeset/tokenizer-presentation-codemod.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[feat] `astryx upgrade` gains the `promote-tokenizer-presentation` codemod, which rewrites a static `experimental={{presentation: x}}` on Tokenizer to the stable `presentation={x}` and leaves a TODO where it cannot prove the rewrite. The Tokenizer blocks and page templates that show a prop the bottom sheet does not render (`hasClear`, `endContent`, `tokenOverflowBehavior`, `hasEntriesOnFocus`, `renderToken`) pass `presentation="popover"`, so they keep the inline field on phones under the new `'adaptive'` default.++@imdreamrunnerdiff --git a/.changeset/tokenizer-presentation-stable.md b/.changeset/tokenizer-presentation-stable.mdnew file mode 100644index 0000000000..be5417f1fc--- /dev/null+++ b/.changeset/tokenizer-presentation-stable.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[feat] Tokenizer's `presentation` prop is stable, and its default is `'adaptive'`. `presentation` takes `'popover' | 'bottom-sheet' | 'adaptive'`, typed by the new exported `TokenizerPresentation`. The API change is additive: the prop is new and optional, no existing prop, type or export is removed or narrowed (`TokenizerProps['ref']` keeps its input type, and the component also accepts a ref typed `Ref<HTMLInputElement | HTMLButtonElement>`), and `experimental={{presentation: x}}` keeps working as a deprecated experimental alias that `astryx upgrade` rewrites to `presentation={x}`; when both are set, `presentation` wins and the field warns once in development. The behavior changes only on compact coarse-pointer screens (phones), which is what `'adaptive'` is for: there a Tokenizer with no `presentation` shows a trigger that opens the bottom sheet, the sheet edits a draft so `onChange` reports once, on Save, `ref` receives the trigger button, and `renderItem`, `renderToken`, `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`, `tokenOverflowBehavior` and `hasAutoFocus` are not rendered, with one development warning that names them. With a mouse or trackpad, on a screen that is not compact, in the server render and while hydrating, nothing changes. Pass `presentation="popover"` to keep the previous behavior on every device. Shipping this default in a patch is a product decision of the engineering owner, agreed with the owner of the compatibility policy.++@imdreamrunnerdiff --git a/apps/sandbox/src/app/(sandbox)/pages/tap-targets/page.tsx b/apps/sandbox/src/app/(sandbox)/pages/tap-targets/page.tsxindex 19bca803d2..9a965e0a81 100644--- a/apps/sandbox/src/app/(sandbox)/pages/tap-targets/page.tsx+++ b/apps/sandbox/src/app/(sandbox)/pages/tap-targets/page.tsx@@ -316,6 +316,7 @@ export default function TapTargetsPage() {value={tokens}onChange={setTokens}hasClear+ presentation="popover"/></MeasuredOverlay></VStack>@@ -333,6 +334,7 @@ export default function TapTargetsPage() {value={tokensB}onChange={setTokensB}hasClear+ presentation="popover"/></MeasuredOverlay></VStack>diff --git a/apps/storybook/stories/Tokenizer.stories.tsx b/apps/storybook/stories/Tokenizer.stories.tsxindex dc25854701..c833852ad3 100644--- a/apps/storybook/stories/Tokenizer.stories.tsx+++ b/apps/storybook/stories/Tokenizer.stories.tsx@@ -144,6 +144,7 @@ export const WithClear: Story = {args: {...Default.args,hasClear: true,+ presentation: 'popover',},name: 'With Clear All Button',};@@ -253,6 +254,7 @@ export const WithEntriesOnFocus: Story = {value={value}onChange={items => setValue(items)}hasEntriesOnFocus+ presentation="popover"/>);},@@ -281,6 +283,7 @@ export const OverflowInline: Story = {value={value}onChange={items => setValue(items)}tokenOverflowBehavior="unfocusedInline"+ presentation="popover"/><p style={{marginTop: 8}}>This text will shift down when the tokenizer expands on focus.@@ -313,6 +316,7 @@ export const OverflowLayer: Story = {value={value}onChange={items => setValue(items)}tokenOverflowBehavior="unfocusedLayer"+ presentation="popover"/><p style={{marginTop: 8}}>This text should not shift when the tokenizer expands on focus.@@ -337,6 +341,7 @@ export const WithEndContent: Story = {value={value}onChange={items => setValue(items)}endContent={<Button label="Apply" variant="primary" size="sm" />}+ presentation="popover"/>);},@@ -399,6 +404,7 @@ export const SizeVariants: Story = {placeholder="Small size"size="sm"hasClear+ presentation="popover"/><Tokenizerlabel="Medium (32px)"@@ -408,6 +414,7 @@ export const SizeVariants: Story = {placeholder="Medium size (default)"size="md"hasClear+ presentation="popover"/><Tokenizerlabel="Large (36px)"@@ -417,6 +424,7 @@ export const SizeVariants: Story = {placeholder="Large size"size="lg"hasClear+ presentation="popover"/></div>);@@ -437,6 +445,7 @@ export const CreatableWithSearch: Story = {hasCreatehasEntriesOnFocusplaceholder="Search or type a new name..."+ presentation="popover"/>);},@@ -507,6 +516,7 @@ export const Loading: Story = {onChange={items => setValue(items)}hasClearendContent={<span>{value.length} selected</span>}+ presentation="popover"/>);},@@ -538,6 +548,7 @@ export const LogicalOrder: Story = {label: 'Team Members',placeholder: 'Add more...',hasClear: true,+ presentation: 'popover',},name: 'Logical order',};@@ -559,6 +570,7 @@ export const RtlEndLane: Story = {value={[users[0]]}onChange={() => {}}hasClear+ presentation="popover"/>),args: {@@ -587,6 +599,7 @@ export const LongTokenEndLane: Story = {value={[longToken]}onChange={() => {}}hasClear+ presentation="popover"/><Tokenizer{...args}@@ -598,6 +611,7 @@ export const LongTokenEndLane: Story = {renderToken={(item, onRemove) => (<Token label={item.label} onRemove={onRemove} />)}+ presentation="popover"/></div>),@@ -643,6 +657,7 @@ export const CaretPlacement: Story = {label: 'Team Members',placeholder: 'Add more...',hasClear: true,+ presentation: 'popover',},name: 'Caret placement',play: async ({canvasElement}) => {@@ -840,14 +855,14 @@ const sheetTagSource: SearchSource = {};/**- * The experimental touch surface, forced on every device so it is reviewable- * on a laptop: `experimental.presentation="bottom-sheet"`. The trigger shows+ * The touch surface, forced on every device so it is reviewable on a laptop:+ * `presentation="bottom-sheet"`. The trigger shows* the selected tokens; tapping it opens one tall sheet with the search row on* top, checkbox rows that keep their place while the sheet is open, a Create* row for typed text, and a pinned footer with a confirmed Clear all beside* Save, which commits the draft; `onChange` fires once, on Save.*/-export const ExperimentalBottomSheet: Story = {+export const SheetPresentation: Story = {render: args => {const [value, setValue] = useState<SearchableItem[]>([sheetTags[0],@@ -862,7 +877,7 @@ export const ExperimentalBottomSheet: Story = {hasCreatemaxMenuItems={1000}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>);},@@ -870,15 +885,15 @@ export const ExperimentalBottomSheet: Story = {label: 'Tags',placeholder: 'Add tags',},- name: 'Experimental: bottom sheet',+ name: 'Bottom sheet',};/**- * `experimental.presentation="adaptive"`: the sheet on a compact+ * `presentation="adaptive"`, the default: the sheet on a compact* coarse-pointer screen (narrow the viewport and emulate touch), otherwise the* inline combobox — the same resolution Selector uses.*/-export const ExperimentalAdaptive: Story = {+export const AdaptivePresentation: Story = {render: args => {// Enough tokens to wrap the inline field's row on a phone, so the box// the trigger keeps at the swap is the wrapped one (FR16, FR17).@@ -897,7 +912,7 @@ export const ExperimentalAdaptive: Story = {onChange={items => setValue(items)}maxMenuItems={1000}debounceMs={0}- experimental={{presentation: 'adaptive'}}+ presentation="adaptive"/>);},@@ -905,7 +920,7 @@ export const ExperimentalAdaptive: Story = {label: 'Tags',placeholder: 'Add tags',},- name: 'Experimental: adaptive',+ name: 'Adaptive (default)',};/**@@ -913,7 +928,7 @@ export const ExperimentalAdaptive: Story = {* trigger stays focusable and does not open; at `maxEntries` the sheet's* unchecked rows are inert while checked rows still toggle.*/-export const ExperimentalBottomSheetStates: Story = {+export const SheetPresentationStates: Story = {render: args => {const [value, setValue] = useState<SearchableItem[]>([sheetTags[0],@@ -928,7 +943,7 @@ export const ExperimentalBottomSheetStates: Story = {value={[sheetTags[0], sheetTags[1]]}onChange={() => {}}isDisabled- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/><Tokenizer{...args}@@ -937,7 +952,7 @@ export const ExperimentalBottomSheetStates: Story = {value={[]}onChange={() => {}}isDisabled- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/><Tokenizer{...args}@@ -947,7 +962,7 @@ export const ExperimentalBottomSheetStates: Story = {onChange={items => setValue(items)}maxEntries={2}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/></div>);@@ -955,5 +970,5 @@ export const ExperimentalBottomSheetStates: Story = {args: {placeholder: 'Add tags',},- name: 'Experimental: bottom sheet states',+ name: 'Bottom sheet states',};diff --git a/docs/specs/components/Tokenizer/Tokenizer.spec.md b/docs/specs/components/Tokenizer/Tokenizer.spec.mdindex 05598c90f8..ffe25bdfd7 100644--- a/docs/specs/components/Tokenizer/Tokenizer.spec.md+++ b/docs/specs/components/Tokenizer/Tokenizer.spec.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: imdreamrunner-approved_at: 2026-10-23+approved_at: 2026-11-03owners: [cixzhang]review_triggers: [public-api, behavior, layout, accessibility]verified_by:@@ -19,6 +19,7 @@ verified_by: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/PowerSearch/PowerSearch.test.tsx,packages/core/src/Typeahead/Typeahead.test.tsx,packages/core/src/Layer/useLayer.test.tsx,@@ -40,7 +41,9 @@ system_specs:spec:AST-003/FR18,spec:AST-009/FR8,spec:AST-012/FR9,+ spec:AST-017/FR3,spec:AST-017/FR21,+ spec:AST-017/FR23,spec:AST-017/FR60,spec:AST-020/FR1,spec:AST-056/FR3,@@ -55,15 +58,15 @@ system_specs:# Tokenizer component contract-| 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. 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 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). |+| 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. `experimental.presentation` stays as a deprecated experimental alias. 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 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, 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, and the props of the inline combobox 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](#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-is-a-stable-presentation-and-adaptive-is-the-default), and [DEC-4](#dec-4--the-sheet-edits-a-draft-that-save-commits). |## Intent@@ -74,12 +77,11 @@ open a related surface from the control where the task began.This record preserves shipped Tokenizer facts and defines three component-ownedcontracts: one package-internal opening-control descriptor for Core peers, the-post-selection lifecycle of an empty-query bootstrap menu, and an experimental-touch presentation 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. The-dependent [PowerSearch draft](https://github.com/meta/astryx/pull/5804)-remains evidence for the need, not authority for this record.+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@@ -92,15 +94,35 @@ remains evidence for the need, not authority for this record.- Controlled/uncontrolled ownership is unchanged. Retention follows committedcontrolled values; a proposed value that the caller has not accepted remainsavailable.-- Experimental surface (DEC-3): the touch sheet presentation is the- `presentation` option inside the optional `experimental` prop object, outside- the stable compatibility promise (`spec:AST-017/FR21`). Omitting `experimental`,- or omitting `presentation` inside it, keeps the inline combobox and its- anchored suggestion menu on every device. Changes to the option ship as- `[experimental]` patch releases (`spec:AST-017/FR22`).-- Migration decision: none. Existing callers that omit `hasEntriesOnFocus`, typed- search selection, explicit dismissal, disabled state, maximum-entry state, and- source-loading behavior retain their prior boundaries.+- Stable presentation (DEC-3): `presentation` is a stable prop, a promotion+ (`spec:AST-017/FR23`). The API change is additive: the prop is new and+ optional, and no existing prop, type, or export is removed or narrowed. `experimental.presentation`,+ its earlier spelling, stays a deprecated experimental alias with the same+ values, outside the stable compatibility promise (`spec:AST-017/FR21`);+ `presentation` wins when both are set, and the field warns once in+ development about the pair (`spec:AST-017/FR29`). `astryx upgrade` rewrites+ a static `experimental={{presentation: x}}` to `presentation={x}`.+- Default change (DEC-3): `presentation` defaults to `adaptive`, a change of+ the released `popover` default, and the behavior changes only on compact+ coarse-pointer screens, which is what `adaptive` is for. With a fine+ pointer, on a screen that is not compact, on the server, and while+ hydrating, a field without `presentation` renders the inline combobox+ exactly as before (`spec:AST-017/FR59`). On a compact coarse-pointer screen+ it renders the sheet: `onChange` fires once on Save in place of once per+ selection, `ref` receives the trigger button, and the props of the inline+ combobox are not rendered. `presentation="popover"` keeps the previous+ behavior everywhere, and the codemod is available for the alias. 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 of `spec:AST-017` (DEC-3).+- Migration decision: `presentation="popover"` restores the previous surface,+ input, `onChange` timing, and `ref` element on every device — the restoring+ input `spec:AST-017/DEC-23` and `architecture:public-component-api/INV16`+ name. No codemod adds it, because adding it to every Tokenizer would opt+ every caller out of the new default. Existing callers that omit+ `hasEntriesOnFocus`, 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.@@ -158,12 +180,14 @@ Consumer migration instructions belong in consumer docs and release notes.## Public concepts-One public concept is introduced, as an experimental surface: the optional-`experimental` prop object and its `presentation` option, `'popover' |-'bottom-sheet' | 'adaptive'` (DEC-3). The option type is inlined on the prop;-no experimental hook or type is exported. Declarations carry `@experimental`-and consumer docs carry `stability: 'experimental'` metadata. Existing-consumer props and usage remain in `Tokenizer.doc.mjs`. The existing+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). Its earlier spelling, `presentation` inside the optional+`experimental` prop object, stays as a deprecated experimental alias:+declarations carry `@experimental` and `@deprecated`, and consumer docs carry+`stability: 'experimental'` metadata and name the stable prop. Existing consumer props and+usage remain in `Tokenizer.doc.mjs`. The existing`hasEntriesOnFocus` mode includes the component-owned post-selection behaviorin FR13–FR15.@@ -171,19 +195,19 @@ In the sheet presentation the trigger is the control: `ref`, `id`, `data-*`,`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 `onFocus`, `onBlur`, and `onKeyDown` report its events. The-`ref` type follows the opt-in. 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 is where the widening lives:-with `experimental` passed, `ref` accepts `Ref<HTMLInputElement |-HTMLButtonElement>` and receives the trigger button in the sheet presentation-and the combobox input otherwise. 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. Theprops that describe the inline combobox have no surface in the sheetpresentation: `renderItem`, `renderToken`, `endContent`, `hasClear` (thesheet's own Clear all replaces it), `hasEntriesOnFocus` (the sheet alwayslists the bootstrap set), `menuWidth`, `tokenOverflowBehavior`, and`hasAutoFocus`. Passing one of them with the sheet presentation emits one-development-mode warning naming the prop, so it is not silently dropped+development-mode warning naming the prop and `presentation="popover"`, so it+is not silently dropped(`architecture:public-component-api/INV3`); every other prop keeps itsmeaning.@@ -197,39 +221,39 @@ it does not become an element or geometry escape hatch.Each requirement identifies its basis. This current record defines the approvedpackage-internal contract while implementation and focused verification remainpending. FR1–FR15 and FR25 describe the `popover` presentation, the inline combobox;-FR16–FR24, FR26, and FR27 describe the `experimental.presentation` option-and its sheet presentation, which has no inline combobox, suggestion menu, or+FR16–FR24, FR26, and FR27 describe the `presentation` prop and its sheet+presentation, which has no inline combobox, suggestion menu, orend 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 | Verified current behavior. |-| 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; 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, 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; touch-flow evidence | Verified current behavior. |-| FR25 | The result list follows `component:BaseTypeahead` FR12: a press on the field's input or its buttons, or in the list, keeps it open, and a press anywhere else closes it. | `component:BaseTypeahead` FR12 | Verified current behavior |-| FR26 | One open sheet edits one draft. The draft starts as `value` when the sheet opens and takes every row toggle, create, and Clear all (FR19, FR22, FR24); `value` and `onChange` are untouched while the sheet is open. Save closes the sheet; with an unchanged draft it reports nothing, and with a changed one it reports the whole draft once through `onChange(items, change)`, where `change` names the last edit that still holds: the last toggle, create, or clear when its item is in the draft and was not selected at open (`add`, or `create` for an item created in this sheet) or was selected at open and is not in the draft (`remove`); otherwise, when the last edit was a removal and some item selected at open is gone, a `remove` naming one such item; otherwise an `add` (`create` when the last edit created that item) naming an item in the draft that was not selected at open; otherwise a `remove` naming an item gone since open. A field that is disabled when Save fires reports nothing. A toggle is announced when it happens (AR6), not again on Save. | DEC-4 | Verified current behavior. |-| FR27 | Swipe, scrim, and Escape dismissal of the sheet close it directly while the draft equals the selection at open. While the draft differs, they open a discard confirmation inside the sheet — "Discard changes?", "Your changes to {label} haven't been saved." — with Discard changes as the destructive action and Keep editing as the safe one, which is focused first; Discard changes closes the sheet without reporting the draft, and Keep editing closes the confirmation and moves focus to the search field so editing resumes where the sheet's own reading order starts (`spec:AST-085/FR4`). The sheet's confirmations (this one and Clear all's, FR24) are one modal dialog shape: a title, a description, and two full-width large actions stacked in reading order — the destructive action, then the safe action, which takes focus first; the two actions are one action group (`family:action-groups`) while keeping their separated, full-width, stacked look; scrim and Escape take the safe action. A close the field forces (becoming disabled, FR17) asks nothing and reports nothing: the draft is dropped. | DEC-4 | Verified current behavior, with one implementation gap: the confirmation's two actions are separated Buttons, not yet one action group (`family:action-groups`). |+| ID | Invariant | Basis | Status |+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1 | Tokenizer MUST keep one native combobox input mounted across token addition, removal, clear, ordinary wrapping, and maximum-entry states. Reaching `maxEntries` may make the input zero-width, transparent, and out of flow, but MUST NOT replace its identity. | Current source and tests | Verified current behavior |+| FR2 | Tokenizer's suggestion menu MUST remain associated with the outer field/control surface. Existing `menuWidth` behavior remains an exact preferred pixel width plus the outer field's minimum width; it is not a maximum. | Current BaseTypeahead/Tokenizer source and docs | Verified current behavior; preserve |+| FR3 | `unfocusedInline` MAY replace direct token layout with OverflowList while blurred. `unfocusedLayer` MAY keep the real wrapper/input mounted in a context layer while an ordinary-flow placeholder represents the collapsed field. | Current source, tests, and stories | Verified current behavior |+| FR4 | Tokenizer MUST provide Core peers one package-internal descriptor with stable identities for its outer field/control surface and active opening control. Layer consumes the descriptor; public consumers cannot observe or configure it. | Approved package-internal contract; #5804 evidence; `spec:AST-002/DEC-1` | Current contract; implementation pending |+| FR5 | Add/search opens MUST identify the stable inner input as the opening control before the result row disappears. Selection, query clearing, result removal, refocus, or later input collapse MUST NOT substitute the transient result row or a pointer coordinate. | Current selection order plus approved descriptor contract | Current contract; implementation pending |+| FR6 | Edit opens MUST capture the actual activated token/control before state removes or replaces it. The Tokenizer-owned capture path MUST include custom `renderToken` output when activation originates from an identifiable descendant control; it MUST NOT require a new public ref contract. | Current owned wrapper plus approved capture contract | Current contract; implementation pending |+| FR7 | A non-null element is usable only while connected, rendered, and geometrically meaningful for the open being prepared. A disconnected, stale, hidden-layer, zero-width, or otherwise unusable opening control MUST fall back safely to the outer field at logical start before show. | Current max/overflow states plus approved safety rule | Current contract; implementation pending |+| FR8 | The descriptor MUST remain valid across focus movement, token add/remove/clear, wrapping, and `unfocusedLayer` reparenting. It MUST clear on unmount, perform no DOM work during SSR, and never retain an element beyond the open preparation that uses it. | Approved identity/lifetime contract | Current contract; implementation pending |+| FR9 | A consuming surface MUST resolve its preferred width before choosing horizontal placement. A surface at least as wide as the outer field MUST use outer-field logical-start alignment. Only a surface narrower than the outer field may use opening-control geometry. | Approved conditional-placement contract | Current contract; implementation pending |+| FR10 | For a narrower surface, Layer MUST compare the opening control with the outer field's physical start/end geometry, choose the nearer physical edge, map that result to logical start/end, and use logical start on a tie. Viewport collision runs last. | Approved Layer-consumer contract | Current contract; implementation pending |+| FR11 | Opening placement MUST be modality-neutral and latched for one open lifetime. Pointer, keyboard, touch, and programmatic activation of the same control MUST produce the same preferred edge. Pointer movement, later focus movement, resize, or target collapse MUST NOT recompute it. | `architecture:interaction-modality` plus approved stability contract | Current contract; implementation pending |+| FR12 | Placement state MUST commit while the surface is hidden, and Layer MUST show it on the next animation frame only after anchor, alignment, and width styles exist. A stale or invalid descriptor MUST never cause a visible wrong-position or first-frame flash. | Approved no-flash contract | Current contract; implementation pending |+| FR13 | Tokenizer MUST exclude every choice whose `SearchableItem.id` is already present in its committed `value` from displayed bootstrap and search cohorts, including results that settle after the controlled value changes. A caller-rejected proposed value remains eligible because it was not committed. Distinct IDs remain eligible even when their labels match. | Approved Tokenizer multi-selection contract | Current contract; implementation and verification pending |+| FR14 | With `hasEntriesOnFocus` enabled, committing a choice from the current settled empty-query bootstrap cohort MUST keep the input focused and the popup open when another eligible loaded choice remains. The active option advances to the next remaining choice in displayed order; when the committed choice was last, the nearest preceding choice becomes active. `aria-activedescendant` MUST reference that rendered option. | Approved rapid multi-select lifecycle | Current contract; implementation and verification pending |+| FR15 | The retained popup MUST close and clear its active descendant when no eligible loaded choice remains, `maxEntries` is reached, the control becomes disabled, focus leaves, or the person dismisses it. Disabled Tokenizer remains non-interactive. Pending or stale source work MUST NOT reopen a terminal popup or expose stale choices; loading has no selectable placeholder and its busy state clears when work is cancelled or settles. | Approved terminal-state safety boundary | Current contract; implementation and verification pending |+| FR16 | `presentation` selects the surface. `adaptive`, the value when `presentation` is omitted, resolves to `bottom-sheet` on compact coarse-pointer screens and to `popover` otherwise, through the one touch-presentation rule `spec:AST-094/FR13` owns, as the selection controls do; with a fine pointer or on a screen that is not compact it renders exactly the `popover` presentation. `popover` is the inline combobox with its anchored suggestion menu on every device, unchanged. `bottom-sheet` is the trigger and modal sheet of FR17–FR24, FR26, and FR27 on every device. The deprecated `experimental.presentation` takes the same values and applies when `presentation` is omitted; when both are set, `presentation` wins and the field warns once in development. `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 | Verified current behavior. |+| 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; 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, 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; 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@@ -268,29 +292,29 @@ end lane.### 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 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: 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 | 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. |+| 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 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: 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 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@@ -325,9 +349,10 @@ end lane.- **PR5 — CSS owns ongoing geometry.** Container resize, outer-field movement,writing-direction layout, and final collision remain CSS/Layer work after theone-time semantic choice.-- **PR6 — The sheet surface is opt-in cost.** A field in the `popover`- presentation does not load the sheet surface's code; the surface loads on- demand only while a field resolves to `bottom-sheet`, renders nothing on the+- **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 to `bottom-sheet`, renders nothing on theserver or during the hydrating render, and renders its long lists in batches(FR21).@@ -426,9 +451,8 @@ the sheet presentation.This contract adds no target, state, or visual styling contract. The sheetpresentation exposes the field's existing `tokenizer` target on the trigger;-the sheet's own parts carry no Tokenizer theming targets while the option is-experimental (DEC-3), and are themed through the targets of the components-they compose.+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@@ -447,10 +471,8 @@ they compose.size, end-control, disabled-reason, and status-placement policy. Tokenizerkeeps its component-local token/input and source-loading behavior inside thatboundary.-- The PowerSearch contract at- [#5804](https://github.com/meta/astryx/pull/5804) depends on the approved- descriptor and owns its own editor width policy. It is dependent draft evidence,- not authority for Tokenizer.+- `component:PowerSearch` depends on the approved descriptor and owns its own+ editor width policy; it is not authority for Tokenizer.### Required implementation and browser evidence@@ -477,18 +499,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, 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 | 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` |+| 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, the deprecated `experimental.presentation` and its precedence warning, 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 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, the Adaptive (default) and Bottom sheet 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 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@@ -530,25 +552,36 @@ popup or make stale choices interactive. This decision adds no public API, doesnot require a refetch, and does not change typed-query selection or directsingle-select BaseTypeahead behavior.-### DEC-3 — The touch sheet presentation is an experimental option+### DEC-3 — The touch sheet is a stable presentation, and adaptive is the default**Reference:** `component:Tokenizer/DEC-3`-**Decider:** `imdreamrunner`, `2026-10-23`--Tokenizer offers its touch surface through the `presentation` option of the-optional `experimental` prop object, with the values `popover`, `bottom-sheet`,-and `adaptive` that the selection controls use. The option is marked-`@experimental` in declarations and `stability: 'experimental'` in authored-docs, so it may change or be removed in a patch release (`spec:AST-017/FR21`).-Omitting `experimental` keeps the inline combobox on every device. `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. 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 while the option is experimental (`spec:AST-017/FR27`); sheet targets-follow the option's promotion.+**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 earlier+spelling, `experimental.presentation`, stays as a deprecated experimental+alias so a released call keeps working (`spec:AST-017/FR23`). 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 that showsthe selected tokens in the inline field's box: a bordered search field on top,@@ -556,10 +589,7 @@ checkbox rows whose order is fixed while the sheet is open and regroupedselected-first on the next open, progressive rendering of long lists, a createrow with a trailing Add action, and a pinned footer with a confirmed Clear alland 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+standalone BottomSheet driven by `isOpen`. Rejected: separate manage and add sheets (two near-duplicate lists; the personloses their place). Rejected: hosting the one sheet in a BottomSheetSwitcher.**INV7 owner exception** (`architecture:component-style-authoring` INV7;@@ -582,7 +612,7 @@ checkbox rows with an indicator and a position, a footer with Clear all andSave, and the sheet's own live region, in place of an anchored listbox ofplain options; the Clear all confirmation is in the DOM only from the Clearall press until it closes. Measured in Chromium 149 on the-Experimental: adaptive story (five tokens selected), elements under `body`,+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 / 120 coarse (the trigger with its tokensis smaller than the inline field with its token remove actions and input).diff --git a/packages/cli/assets/codemods/transforms/next/__tests__/promote-tokenizer-presentation.test.mjs b/packages/cli/assets/codemods/transforms/next/__tests__/promote-tokenizer-presentation.test.mjsnew file mode 100644index 0000000000..4de725009c--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/__tests__/promote-tokenizer-presentation.test.mjs@@ -0,0 +1,99 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import transform from '../promote-tokenizer-presentation.mjs';++async function applyTransform(source) {+ const jscodeshift = (await import('jscodeshift')).default;+ const j = jscodeshift.withParser('tsx');+ const api = {jscodeshift: j, stats: () => {}, report: () => {}};+ return transform({source, path: 'test.tsx'}, api) ?? source;+}++/** Collapse whitespace so assertions ignore the printer's line breaks. */+const flat = text => text.replace(/\s+/g, ' ');++describe('promote-tokenizer-presentation', () => {+ it('moves a static presentation out of experimental and drops the emptied object', async () => {+ const output = flat(+ await applyTransform(`import {Tokenizer} from '@astryxdesign/core';+const a = <Tokenizer label="Tags" experimental={{presentation: 'adaptive'}} />;+const b = <Tokenizer label="Tags" experimental={{'presentation': 'bottom-sheet' as const}} />;`),+ );+ expect(output).not.toContain('experimental');+ expect(output).toContain(+ '<Tokenizer label="Tags" presentation="adaptive" />',+ );+ expect(output).toContain(+ '<Tokenizer label="Tags" presentation="bottom-sheet" />',+ );+ });++ it('moves an expression and a shorthand key as an expression', async () => {+ const output = flat(+ await applyTransform(`import {Tokenizer as Tags} from '@astryxdesign/core/Tokenizer';+const a = <Tags label="Tags" experimental={{presentation: isPhone ? 'bottom-sheet' : 'popover'}} />;+const b = <Tags label="Tags" experimental={{presentation}} />;`),+ );+ expect(output).toContain(+ "presentation={isPhone ? 'bottom-sheet' : 'popover'}",+ );+ expect(output).toContain(+ '<Tags label="Tags" presentation={presentation} />',+ );+ expect(output).not.toContain('experimental');+ });++ it('keeps other experimental keys beside the moved prop', async () => {+ const output = flat(+ await applyTransform(`import * as Core from '@astryxdesign/core';+const a = <Core.Tokenizer label="Tags" experimental={{presentation: 'adaptive', other: true}} />;`),+ );+ expect(output).toContain(+ 'experimental={{ other: true }} presentation="adaptive"',+ );+ });++ it('leaves a TODO and the deprecated spelling where it cannot prove the rewrite', async () => {+ const source = `import {Tokenizer} from '@astryxdesign/core';+const a = <Tokenizer label="Tags" experimental={options} />;+const b = <Tokenizer label="Tags" experimental={{presentation: 'adaptive'}} {...rest} />;+const c = <Tokenizer label="Tags" presentation="popover" experimental={{presentation: 'adaptive'}} />;+const d = <Tokenizer label="Tags" experimental={{...base, presentation: 'adaptive'}} />;`;+ const output = await applyTransform(source);+ expect(output.match(/TODO\(astryx upgrade\)/g)).toHaveLength(4);+ expect(flat(output)).toContain("experimental={{presentation: 'adaptive'}}");+ expect(flat(output)).toContain('experimental={options}');+ });++ it('moves the value past a spread that comes before experimental', async () => {+ const output = flat(+ await applyTransform(`import {Tokenizer} from '@astryxdesign/core';+const a = <Tokenizer {...args} label="Tags" experimental={{presentation: 'bottom-sheet'}} />;`),+ );+ expect(output).toContain(+ '<Tokenizer {...args} label="Tags" presentation="bottom-sheet" />',+ );+ expect(output).not.toContain('TODO');+ });++ it('changes nothing without an experimental presentation or outside core', async () => {+ const source = `import {Tokenizer} from '@astryxdesign/core';+import {Tokenizer as Other} from 'some-other-library';+const a = <Tokenizer label="Tags" presentation="popover" />;+const b = <Tokenizer label="Tags" experimental={{}} />;+const c = <Other label="Tags" experimental={{presentation: 'adaptive'}} />;+const d = <Selector experimental={{presentation: 'adaptive'}} />;`;+ expect(await applyTransform(source)).toBe(source);+ });++ it('is idempotent and prints parseable source', async () => {+ const once =+ await applyTransform(`import {Tokenizer} from '@astryxdesign/core';+const a = <Tokenizer label="Tags" experimental={{presentation: 'adaptive'}} />;+const b = <Tokenizer label="Tags" experimental={options} />;`);+ expect(await applyTransform(once)).toBe(once);+ const jscodeshift = (await import('jscodeshift')).default;+ expect(() => jscodeshift.withParser('tsx')(once)).not.toThrow();+ });+});diff --git a/packages/cli/assets/codemods/transforms/next/index.mjs b/packages/cli/assets/codemods/transforms/next/index.mjsindex 2af3bdfcf0..49c8efb0df 100644--- a/packages/cli/assets/codemods/transforms/next/index.mjs+++ b/packages/cli/assets/codemods/transforms/next/index.mjs@@ -7,4 +7,14 @@* this file into the resolved version folder.*/-export default [];+import promoteTokenizerPresentation, {+ meta as promoteTokenizerPresentationMeta,+} from './promote-tokenizer-presentation.mjs';++export default [+ {+ name: 'promote-tokenizer-presentation',+ transform: promoteTokenizerPresentation,+ meta: promoteTokenizerPresentationMeta,+ },+];diff --git a/packages/cli/assets/codemods/transforms/next/promote-tokenizer-presentation.mjs b/packages/cli/assets/codemods/transforms/next/promote-tokenizer-presentation.mjsnew file mode 100644index 0000000000..c02bceb86a--- /dev/null+++ b/packages/cli/assets/codemods/transforms/next/promote-tokenizer-presentation.mjs@@ -0,0 +1,174 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Codemod: move Tokenizer's experimental presentation to the stable prop+ *+ * `experimental={{presentation: x}}` on a Tokenizer becomes+ * `presentation={x}`, or `presentation="x"` for a string. Other keys stay in+ * the `experimental` object, and an object left empty is removed. The+ * deprecated spelling selects the same surface, so the result renders the+ * same. Built on the shared `transformProp` helper, so it does not follow+ * variables, helpers, wrappers, or types. Where it cannot prove the result it+ * keeps the deprecated spelling, which still works, and leaves a TODO: an+ * `experimental` value that is not an object literal, a spread or computed+ * key in it, a Tokenizer that already passes `presentation`, and a spread of+ * props after `experimental`, which could set `presentation` over the moved+ * value. A spread before `experimental` is safe: the moved attribute takes+ * `experimental`'s place, so it still wins over the spread, as the+ * experimental value did, and before this release a spread's `presentation`+ * did nothing. Each TODO is added once, so a second run changes+ * nothing.+ */++import {transformProp} from '../../transform-prop.mjs';++export const meta = {+ title: "Move Tokenizer's experimental presentation to presentation",+ description:+ 'Rewrites `experimental={{presentation: x}}` on Tokenizer to the stable ' ++ '`presentation={x}`. Keeps the deprecated spelling, which still works, ' ++ 'with a TODO where the experimental value is not an object literal, ' ++ 'where the Tokenizer already passes presentation, and where it spreads ' ++ 'props after experimental.',+};++const CORE_IMPORT_RE = /^@(astryxdesign|xds)\/core(?:\/|$)/;+const COMPONENT_PROPS = new Map([['Tokenizer', new Set(['experimental'])]]);++const TODO_COMMENT =+ ' TODO(astryx upgrade): experimental.presentation is deprecated. Pass ' ++ 'presentation instead; this one was left unchanged because the codemod ' ++ 'could not prove the rewrite. ';++const TYPE_WRAPPERS = new Set([+ 'TSAsExpression',+ 'TSSatisfiesExpression',+ 'TSTypeAssertion',+ 'TSNonNullExpression',+ 'TypeCastExpression',+ 'ParenthesizedExpression',+]);++/** @param {any} node */+function unwrap(node) {+ let current = node;+ while (current && TYPE_WRAPPERS.has(current.type)) {+ current = current.expression;+ }+ return current;+}++/** The static key of an object entry, or null. @param {any} entry */+function keyName(entry) {+ if (+ (entry.type !== 'ObjectProperty' && entry.type !== 'Property') ||+ entry.computed+ ) {+ return null;+ }+ const key = entry.key;+ if (key.type === 'Identifier') {+ return key.name;+ }+ if (+ (key.type === 'StringLiteral' || key.type === 'Literal') &&+ typeof key.value === 'string'+ ) {+ return key.value;+ }+ return null;+}++/** @param {any} j @param {any} node @param {string} text */+function addComment(j, node, text) {+ node.comments ??= [];+ if (node.comments.some((/** @type {any} */ c) => c.value === text)) {+ return false;+ }+ node.comments.push(j.commentBlock(text, true, false));+ return true;+}++/**+ * @param {import('../../../../authoring/codemod/type').AstryxCodemodFile} file+ * @param {import('../../../../authoring/codemod/type').CodemodTransformApi} api+ * @returns {string | null | undefined}+ */+export default function transformer(file, api) {+ const j = api.jscodeshift;+ const root = j(file.source);+ let hasChanges = false;++ transformProp(+ root,+ j,+ {+ matchesImport: source => CORE_IMPORT_RE.test(source),+ components: COMPONENT_PROPS,+ },+ propPath => {+ const opening = propPath.parent?.node;+ const attributes = opening?.attributes ?? [];+ const prop = propPath.node;+ const value =+ prop.value?.type === 'JSXExpressionContainer'+ ? unwrap(prop.value.expression)+ : null;+ const entries =+ value?.type === 'ObjectExpression' ? value.properties : [];+ const presentationEntries = entries.filter(+ (/** @type {any} */ entry) => keyName(entry) === 'presentation',+ );+ const hasUnprovenEntry = entries.some(+ (/** @type {any} */ entry) => keyName(entry) == null,+ );+ if (+ value?.type === 'ObjectExpression' &&+ presentationEntries.length === 0 &&+ !hasUnprovenEntry+ ) {+ return;+ }+ const isProvable =+ value?.type === 'ObjectExpression' &&+ presentationEntries.length === 1 &&+ !hasUnprovenEntry &&+ !attributes.some(+ (/** @type {any} */ a, /** @type {number} */ index) =>+ (a.type === 'JSXSpreadAttribute' &&+ index > attributes.indexOf(prop)) ||+ (a.type === 'JSXAttribute' && a.name?.name === 'presentation'),+ );+ if (!isProvable) {+ hasChanges = addComment(j, prop, TODO_COMMENT) || hasChanges;+ return;+ }++ const entry = presentationEntries[0];+ const entryValue = entry.value;+ const literal = unwrap(entryValue);+ const attributeValue =+ (literal?.type === 'StringLiteral' || literal?.type === 'Literal') &&+ typeof literal.value === 'string'+ ? j.stringLiteral(literal.value)+ : j.jsxExpressionContainer(entryValue);+ const presentation = j.jsxAttribute(+ j.jsxIdentifier('presentation'),+ attributeValue,+ );+ value.properties = entries.filter((/** @type {any} */ e) => e !== entry);+ const index = opening.attributes.indexOf(prop);+ if (value.properties.length === 0) {+ opening.attributes.splice(index, 1, presentation);+ } else {+ opening.attributes.splice(index + 1, 0, presentation);+ }+ hasChanges = true;+ },+ );++ if (!hasChanges) return undefined;+ // `auto` keeps every reprinted string's own quotes and writes the new+ // attribute string in double quotes, as JSX attributes are written.+ return root.toSource({quote: 'auto'});+}diff --git a/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerClear.tsx b/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerClear.tsxindex a3943bf9e1..4884c4417f 100644--- a/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerClear.tsx+++ b/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerClear.tsx@@ -38,6 +38,7 @@ export default function TokenizerClear() {value={value}onChange={items => setValue(items)}hasClear+ presentation="popover"/></Stack></div>diff --git a/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerCreatable.tsx b/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerCreatable.tsxindex 42012ef16f..d8d004a63d 100644--- a/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerCreatable.tsx+++ b/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerCreatable.tsx@@ -59,6 +59,7 @@ export default function TokenizerCreatable() {hasCreatehasEntriesOnFocusplaceholder="Search or type a new name..."+ presentation="popover"/></Stack></Stack>diff --git a/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerEndContent.tsx b/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerEndContent.tsxindex b4547edb77..a21ce0df4e 100644--- a/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerEndContent.tsx+++ b/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerEndContent.tsx@@ -40,6 +40,7 @@ export default function TokenizerEndContent() {value={value}onChange={items => setValue(items)}endContent={<Button label="Apply" variant="primary" size="sm" />}+ presentation="popover"/></Stack></div>diff --git a/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerOverflow.tsx b/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerOverflow.tsxindex 39291741bb..bfaa5fb995 100644--- a/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerOverflow.tsx+++ b/packages/cli/assets/templates/blocks/components/Tokenizer/TokenizerOverflow.tsx@@ -41,6 +41,7 @@ export default function TokenizerOverflow() {value={inlineValue}onChange={items => setInlineValue(items)}tokenOverflowBehavior="unfocusedInline"+ presentation="popover"/></Stack><Stack direction="vertical" gap={1}>@@ -54,6 +55,7 @@ export default function TokenizerOverflow() {value={layerValue}onChange={items => setLayerValue(items)}tokenOverflowBehavior="unfocusedLayer"+ presentation="popover"/></Stack></Stack>diff --git a/packages/cli/assets/templates/pages/table-inbox/page.tsx b/packages/cli/assets/templates/pages/table-inbox/page.tsxindex dce203341d..822482978c 100644--- a/packages/cli/assets/templates/pages/table-inbox/page.tsx+++ b/packages/cli/assets/templates/pages/table-inbox/page.tsx@@ -1874,6 +1874,10 @@ function ComposeWindow({)}</>}+ // The recipient rows read as one header, so all three stay+ // inline fields on every device; the sheet has no end lane+ // for the Cc and Bcc buttons.+ presentation="popover"/>{hasCc ? (<Tokenizer@@ -1884,6 +1888,7 @@ function ComposeWindow({value={cc}onChange={items => setCc(items)}hasCreate+ presentation="popover"/>) : null}{hasBcc ? (@@ -1895,6 +1900,7 @@ function ComposeWindow({value={bcc}onChange={items => setBcc(items)}hasCreate+ presentation="popover"/>) : null}<TextInputdiff --git a/packages/cli/assets/templates/pages/work-item-detail/page.tsx b/packages/cli/assets/templates/pages/work-item-detail/page.tsxindex 94f9d150ea..21f00ff4d5 100644--- a/packages/cli/assets/templates/pages/work-item-detail/page.tsx+++ b/packages/cli/assets/templates/pages/work-item-detail/page.tsx@@ -463,6 +463,7 @@ function PageHeader({onRemove={onRemove}/>)}+ presentation="popover"/></HStack></VStack>diff --git a/packages/core/api-report.md b/packages/core/api-report.mdindex 722ccccdc3..e0c9dcfd88 100644--- a/packages/core/api-report.md+++ b/packages/core/api-report.md@@ -2611,7 +2611,7 @@ component Token(props: TokenProps)prop xstyle?: StyleXStylesinherits AriaAttributes, DOMAttributes, HTMLAttributescomponent Tokenizer(props: TokenizerProps)- overload <T extends SearchableItem>(props: Omit<TokenizerProps<T>, 'ref' | 'experimental'> & { experimental: NonNullable<TokenizerProps<T>['experimental']>; ref?: React.Ref<HTMLInputElement | HTMLButtonElement> }) => React.JSX.Element @experimental+ overload <T extends SearchableItem>(props: Omit<TokenizerProps<T>, 'ref'> & { ref?: React.Ref<HTMLInputElement | HTMLButtonElement> }) => React.JSX.Elementprop containerClassName?: stringprop containerStyle?: CSSPropertiesprop containerXstyle?: StyleXStyles@@ -2623,7 +2623,7 @@ component Tokenizer(props: TokenizerProps)prop disabledMessage?: stringprop emptySearchText?: ReactNode = 'No results found'prop endContent?: ReactNode- prop experimental?: { presentation?: 'popover' | 'bottom-sheet' | 'adaptive' } @experimental+ prop experimental?: { presentation?: TokenizerPresentation } @experimentalprop handleRef?: React.Ref<TokenizerHandle>prop hasAutoFocus?: boolean = falseprop hasClear?: boolean = false@@ -2646,6 +2646,7 @@ component Tokenizer(props: TokenizerProps)prop onFocus?: (e: React.FocusEvent) => voidprop onKeyDown?: React.KeyboardEventHandler<HTMLElement>prop placeholder?: string+ prop presentation?: TokenizerPresentation = 'adaptive'prop ref?: React.Ref<HTMLInputElement>prop renderItem?: (item: T) => ReactNodeprop renderToken?: (item: T, onRemove: () => void) => ReactNode@@ -5664,6 +5665,7 @@ interface TokenizerHandleblur: () => voidfocus: () => voidtype TokenizerOverflowBehavior = 'none' | 'unfocusedInline' | 'unfocusedLayer'+type TokenizerPresentation = AdaptivePresentationinterface TokenizerProps<T extends SearchableItem> extends Omit<FieldInputBaseProps<HTMLInputElement>, 'onChange' | 'onFocus' | 'onBlur' | 'onKeyDown'> (props of Tokenizer)type TokenizerSize = 'sm' | 'md' | 'lg'interface TokenizerStatus@@ -8918,6 +8920,7 @@ Tokenizer (.)TokenizerChange (.)TokenizerHandle (.)TokenizerOverflowBehavior (.)+TokenizerPresentation (.)TokenizerProps (.)TokenizerSize (.)TokenizerStatus (.)diff --git a/packages/core/src/Field/__tests__/SearchKeyboard.interaction.browser.spec.ts b/packages/core/src/Field/__tests__/SearchKeyboard.interaction.browser.spec.tsindex 3bb5d5df49..f41e73b25f 100644--- a/packages/core/src/Field/__tests__/SearchKeyboard.interaction.browser.spec.ts+++ b/packages/core/src/Field/__tests__/SearchKeyboard.interaction.browser.spec.ts@@ -2,8 +2,8 @@/*** @file SearchKeyboard.interaction.browser.spec.ts- * @input Storybook stories of Typeahead, Tokenizer, Selector, MultiSelector- * and CommandPaletteInput+ * @input Storybook stories of Typeahead, Tokenizer (its inline field and its+ * sheet), Selector, MultiSelector and CommandPaletteInput* @output On a touch-emulated phone, the search input that a tap focuses* carries `enterkeyhint="search"` and `autocorrect="off"`* @position Search keyboard evidence in the interaction lane. jsdom has no@@ -39,13 +39,27 @@ test('a tap on Typeahead focuses a field that asks for the Search key and no autawait expectSearchKeyboard(page.getByRole('combobox'));});-test('a tap on Tokenizer focuses a field that asks for the Search key and no autocorrection', async ({+test('a tap on the inline Tokenizer focuses a field that asks for the Search key and no autocorrection', async ({page,}) => {- await openStory(page, storybook(), 'core-tokenizer--default');+ // The story pins `presentation="popover"`, so the phone keeps the inline field.+ await openStory(page, storybook(), 'core-tokenizer--with-end-content');await expectSearchKeyboard(page.getByRole('combobox'));});+test("a tap in the search field of Tokenizer's sheet focuses a field that asks for the Search key and no autocorrection", async ({+ page,+}) => {+ // The default presentation is the sheet on a phone.+ await openStory(page, storybook(), 'core-tokenizer--default');+ const trigger = page.getByRole('button', {name: /^Team Members/});+ await expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');+ await trigger.tap();+ await expectSearchKeyboard(+ page.getByRole('dialog').getByLabel('Search Team Members', {exact: true}),+ );+});+test("a tap in Selector's search row focuses a field that asks for the Search key and no autocorrection", async ({page,}) => {diff --git a/packages/core/src/PowerSearch/PowerSearch.tsx b/packages/core/src/PowerSearch/PowerSearch.tsxindex db55054d30..ef7595faf9 100644--- a/packages/core/src/PowerSearch/PowerSearch.tsx+++ b/packages/core/src/PowerSearch/PowerSearch.tsx@@ -1635,6 +1635,7 @@ export function PowerSearch({containerClassName={className}containerStyle={style}data-testid={testId}+ presentation="popover"/></TokenizerItemRemovableContext></TokenizerClearAllMessageContext>diff --git a/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx b/packages/core/src/PowerSearch/PowerSearchValueEditor.tsxindex 2759e54485..eeebcc85fe 100644--- a/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx+++ b/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx@@ -268,7 +268,7 @@ function StringListEditor({hasCreate={hasCreate}maxMenuItems={maxMenuItems}width={isSheet ? '100%' : undefined}- experimental={isSheet ? {presentation: 'bottom-sheet'} : undefined}+ presentation={isSheet ? 'bottom-sheet' : 'popover'}/>);}@@ -815,6 +815,7 @@ function EnumListEditor({// all of them instead of BaseTypeahead's 10-suggestion default, which// would silently drop valid choices with no way to reach them.maxMenuItems={items.length}+ presentation="popover"/>);}@@ -892,7 +893,7 @@ function EntityListEditor({debounceMs={operatorValue.searchSource ? 150 : 0}maxMenuItems={maxMenuItems}width={isSheet ? '100%' : undefined}- experimental={isSheet ? {presentation: 'bottom-sheet'} : undefined}+ presentation={isSheet ? 'bottom-sheet' : 'popover'}/>);}diff --git a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsxindex b27ea3680d..fc0cb8b75e 100644--- a/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx+++ b/packages/core/src/Table/plugins/filtering/useTableFiltering.tsx@@ -820,6 +820,7 @@ function StringListFilterControl({}}size={size}hasClear={hasClear}+ presentation="popover"/>);}diff --git a/packages/core/src/Tokenizer/Tokenizer.composites.test.tsx b/packages/core/src/Tokenizer/Tokenizer.composites.test.tsxnew file mode 100644index 0000000000..27dc7c6326--- /dev/null+++ b/packages/core/src/Tokenizer/Tokenizer.composites.test.tsx@@ -0,0 +1,153 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+/**+ * @file Tokenizer.composites.test.tsx+ * @input Uses vitest, Testing Library, PowerSearch, PowerSearchValueEditor,+ * and Table's filtering plugin under a compact coarse-pointer `matchMedia`+ * @output Proves Core's composites that render Tokenizer as an inline field+ * pin its `popover` presentation, so the `adaptive` default does not turn+ * them into a sheet trigger on a phone: PowerSearch's field and its list+ * value editors, and Table's list filter. PowerSearch's own sheet still asks+ * the list editors for Tokenizer's sheet.+ * @position Core tests; validates the `presentation` call sites in+ * PowerSearch.tsx, PowerSearchValueEditor.tsx, and useTableFiltering.tsx+ */+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import {useState} from 'react';+import {render, screen} from '@testing-library/react';+import {PowerSearch} from '../PowerSearch/PowerSearch';+import {PowerSearchValueEditor} from '../PowerSearch/PowerSearchValueEditor';+import type {InternalConfig} from '../PowerSearch/useInternalConfig';+import type {PowerSearchConfig} from '../PowerSearch/types';+import {Table} from '../Table/Table';+import {useTableFiltering} from '../Table/plugins/filtering/useTableFiltering';+import type {TableFilterState} from '../Table/plugins/filtering/useTableFiltering';+import type {TableColumn} from '../Table/types';++const config: PowerSearchConfig = {+ name: 'issues',+ fields: [+ {+ key: 'tags',+ label: 'Tags',+ defaultOperator: 'include',+ operators: [+ {key: 'include', label: 'include', value: {type: 'string_list'}},+ ],+ },+ ],+};++const stubConfig = {+ fields: [],+ fieldsByKey: new Map(),+} as unknown as InternalConfig;++// The Tokenizer's sheet trigger is a button that opens a dialog; none of+// these fields renders another one at rest.+const sheetTriggers = () =>+ document.querySelectorAll('button[aria-haspopup="dialog"]');++beforeEach(() => {+ // A phone: every compact coarse-pointer query matches.+ vi.stubGlobal(+ 'matchMedia',+ vi.fn().mockImplementation((query: string) => ({+ matches: true,+ media: query,+ onchange: null,+ addEventListener: vi.fn(),+ removeEventListener: vi.fn(),+ addListener: vi.fn(),+ removeListener: vi.fn(),+ dispatchEvent: vi.fn(),+ })),+ );+});+afterEach(() => vi.unstubAllGlobals());++describe('Tokenizer in Core composites on a compact coarse-pointer screen', () => {+ it("keeps PowerSearch's popover field an inline combobox", () => {+ render(+ <PowerSearch+ config={config}+ filters={[]}+ onChange={() => {}}+ experimental={{presentation: 'popover'}}+ />,+ );+ expect(screen.getByRole('combobox')).toBeInTheDocument();+ expect(sheetTriggers()).toHaveLength(0);+ });++ it.each([+ ['string_list', {type: 'string_list'}],+ [+ 'entity_list',+ {+ type: 'entity_list',+ searchSource: {search: () => [], bootstrap: () => []},+ },+ ],+ ['enum_list', {type: 'enum_list', values: [{value: 'a', label: 'A'}]}],+ ] as const)(+ 'keeps the %s value editor of the popover an inline combobox',+ (_name, operatorValue) => {+ render(+ <PowerSearchValueEditor+ operatorValue={operatorValue as never}+ filterValue={undefined}+ onChange={() => {}}+ config={stubConfig}+ />,+ );+ expect(screen.getByRole('combobox')).toBeInTheDocument();+ expect(sheetTriggers()).toHaveLength(0);+ },+ );++ it("still opens Tokenizer's sheet from PowerSearch's sheet value step", () => {+ render(+ <PowerSearchValueEditor+ operatorValue={{type: 'string_list'}}+ filterValue={undefined}+ onChange={() => {}}+ config={stubConfig}+ presentation="bottom-sheet"+ fieldLabel="Tags"+ />,+ );+ expect(screen.queryByRole('combobox')).toBeNull();+ expect(sheetTriggers()).toHaveLength(1);+ });++ it("keeps Table's list filter an inline combobox", () => {+ interface Row extends Record<string, unknown> {+ id: string;+ tags: string;+ }+ const columns: TableColumn<Row>[] = [+ {key: 'tags', header: 'Tags', filter: 'tags'},+ ];+ function FilterTable() {+ const [filters, setFilters] = useState<TableFilterState>({});+ const filterPlugin = useTableFiltering<Row>({+ filters,+ onFilterChange: (key, value) =>+ setFilters(prev => ({...prev, [key]: value ?? undefined})),+ variant: 'inline',+ searchConfig: config,+ });+ return (+ <Table+ data={[{id: '1', tags: 'bug'}]}+ columns={columns}+ idKey="id"+ plugins={{filter: filterPlugin}}+ />+ );+ }+ render(<FilterTable />);+ expect(screen.getByRole('combobox')).toBeInTheDocument();+ expect(sheetTriggers()).toHaveLength(0);+ });+});diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjsindex 17a60d4835..eb9d27b32c 100644--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs@@ -292,12 +292,19 @@ export const docs = {type: 'CSSProperties',description: 'Inline styles for the visual control box.',},+ {+ name: 'presentation',+ type: "'popover' | 'bottom-sheet' | 'adaptive'",+ description:+ 'How the field presents its choices. adaptive (the default) uses the bottom sheet on compact touch screens and the popover otherwise, resolved the same way Selector resolves it; the server render and the hydrating render are the popover. popover is the inline combobox with its anchored suggestion menu on every device. bottom-sheet replaces it on every device with a trigger showing the selected tokens that opens one tall modal sheet: a search row on top, full-width checkbox rows that keep their place while the sheet is open, a Create row with hasCreate, and a footer pinned in every state with a confirmed Clear all and Save; the sheet edits a draft, so onChange fires once, when Save commits it, and a swipe, scrim or Escape close of a changed draft asks before discarding. In the sheet presentation the trigger is the control: ref, id, aria-* and data-* reach it, and ref receives the trigger button there, so type it Ref<HTMLInputElement | HTMLButtonElement>, which the component accepts (TokenizerProps keeps its released input ref type). renderItem, renderToken, endContent, hasClear, hasEntriesOnFocus, menuWidth, tokenOverflowBehavior and hasAutoFocus have no surface in the sheet, and the field warns once in development when they are passed. Pass presentation="popover" to keep the inline field and those props on every device.',+ default: "'adaptive'",+ },{name: 'experimental',type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",stability: 'experimental',description:- "Experimental options: anything in this object may change or be removed in a patch release, and omitting it keeps the stable behavior. presentation (default 'popover') chooses how the field presents its choices. popover is the inline combobox with its anchored suggestion menu. bottom-sheet replaces it with a trigger showing the selected tokens that opens one tall modal sheet: a search row on top, full-width checkbox rows that keep their place while the sheet is open, a Create row with hasCreate, and a footer pinned in every state with a confirmed Clear all and Save; the sheet edits a draft, so onChange fires once, when Save commits it, and a swipe, scrim or Escape close of a changed draft asks before discarding. adaptive uses the bottom sheet on compact touch screens and the popover otherwise, resolved the same way Selector resolves it. In the sheet presentation the trigger is the control (ref, id, aria-* and data-* reach it; with experimental passed, ref also accepts a Ref<HTMLInputElement | HTMLButtonElement> — an input-only ref still type-checks against that wider type, but with adaptive or bottom-sheet it receives the trigger button at runtime, so type the ref for both elements; TokenizerProps keeps its released ref type and gains only the optional experimental), and renderItem, renderToken, endContent, hasClear, hasEntriesOnFocus, menuWidth, tokenOverflowBehavior and hasAutoFocus have no surface to act on; the field warns once in development when they are passed. For example: <Tokenizer label=\"Tags\" searchSource={tagSource} value={tags} onChange={setTags} hasCreate experimental={{presentation: 'adaptive'}} />.",+ 'Experimental options: anything in this object may change or be removed in a patch release. Deprecated: experimental.presentation is the earlier spelling of presentation; use presentation. It still works with the same values, and presentation wins when both are set.',},],theming: {@@ -638,12 +645,19 @@ export const docsZh = {type: 'CSSProperties',description: '可视控件框的内联样式。',},+ {+ name: 'presentation',+ type: "'popover' | 'bottom-sheet' | 'adaptive'",+ description:+ '字段如何呈现选项。adaptive(默认)在紧凑触摸屏上使用底部面板,其他情况使用 popover,解析方式与 Selector 相同;服务端渲染和水合期间的渲染均为 popover。popover 在所有设备上为内联组合框及其锚定建议菜单。bottom-sheet 在所有设备上改为一个显示已选标记的触发按钮,点按后打开一个高的模态底部面板——顶部为搜索行,下方为整行复选框行(面板打开期间位置保持不变),hasCreate 时有「创建」行,底部固定显示需确认的「全部清除」和「保存」;面板编辑的是草稿,onChange 仅在「保存」提交时触发一次,草稿有改动时滑动、点击遮罩或按 Escape 关闭会先询问是否放弃。在底部面板呈现中,触发按钮即为控件:ref、id、aria-* 和 data-* 都作用于它,ref 在该呈现中收到的是触发按钮,因此请将其类型声明为组件所接受的 Ref<HTMLInputElement | HTMLButtonElement>(TokenizerProps 保留已发布的输入框 ref 类型)。renderItem、renderToken、endContent、hasClear、hasEntriesOnFocus、menuWidth、tokenOverflowBehavior 和 hasAutoFocus 在底部面板中没有作用对象,传入时开发模式下会警告一次。传入 presentation="popover" 可在所有设备上保留内联字段和这些属性。',+ default: "'adaptive'",+ },{name: 'experimental',type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",stability: 'experimental',description:- "实验性选项:此对象中的任何内容都可能在补丁版本中更改或移除;省略它即保持稳定行为。presentation(默认 'popover')决定字段如何呈现选项:popover 为内联组合框及其锚定建议菜单;bottom-sheet 改为一个显示已选标记的触发按钮,点按后打开一个高的模态底部面板——顶部为搜索行,下方为整行复选框行(面板打开期间位置保持不变),hasCreate 时有「创建」行,底部固定显示需确认的「全部清除」和「保存」;面板编辑的是草稿,onChange 仅在「保存」提交时触发一次,草稿有改动时滑动、点击遮罩或按 Escape 关闭会先询问是否放弃;adaptive 在紧凑触摸屏上使用底部面板,其他情况使用 popover,解析方式与 Selector 相同。在底部面板呈现中,触发按钮即为控件(ref、id、aria-* 和 data-* 都作用于它;传入 experimental 后,ref 也接受 Ref<HTMLInputElement | HTMLButtonElement>——仅为输入框类型的 ref 在这个更宽的类型下仍能通过类型检查,但在 adaptive 或 bottom-sheet 下运行时收到的是触发按钮,因此请为两种元素声明 ref 的类型;TokenizerProps 保留已发布的 ref 类型,仅新增可选的 experimental);renderItem、renderToken、endContent、hasClear、hasEntriesOnFocus、menuWidth、tokenOverflowBehavior 和 hasAutoFocus 没有作用对象,传入时开发模式下会警告一次。例如:<Tokenizer label=\"标签\" searchSource={tagSource} value={tags} onChange={setTags} hasCreate experimental={{presentation: 'adaptive'}} />。",+ '实验性选项:此对象中的任何内容都可能在补丁版本中更改或移除。已弃用:experimental.presentation 是 presentation 的旧写法,请改用 presentation。它仍以相同的取值生效,两者同时设置时以 presentation 为准。',},],theming: {@@ -844,7 +858,9 @@ export const docsDense = {'Icon at input start, before tokens. Icon name, SVG component, or ReactNode.',endContent: 'Content at input row end. For buttons, counts, controls.',handleRef: 'Imperative handle for focus() and blur() control.',+ presentation:+ "'adaptive' (default: sheet on compact touch, else popover; SSR/hydration render popover) | 'popover' (inline combobox, every device) | 'bottom-sheet' (trigger + one searchable modal sheet of checkbox rows editing a draft that Save commits; onChange fires once, on Save). Sheet: ref reaches the trigger button; renderItem/renderToken/endContent/hasClear/hasEntriesOnFocus/menuWidth/tokenOverflowBehavior/hasAutoFocus inert (dev warning). presentation=\"popover\" keeps them on every device.",experimental:- "Experimental; may change in a patch. presentation: 'popover' (default, inline combobox) | 'bottom-sheet' (trigger + one searchable modal sheet of checkbox rows editing a draft that Save commits; onChange fires once, on Save) | 'adaptive' (sheet on compact touch, else popover).",+ 'Experimental; may change in a patch. Deprecated presentation: old spelling of presentation; presentation wins if both set.',},};diff --git a/packages/core/src/Tokenizer/Tokenizer.props-type.test.tsx b/packages/core/src/Tokenizer/Tokenizer.props-type.test.tsxindex 5e7ca712b5..251b93f9c2 100644--- a/packages/core/src/Tokenizer/Tokenizer.props-type.test.tsx+++ b/packages/core/src/Tokenizer/Tokenizer.props-type.test.tsx@@ -3,13 +3,14 @@* @file Tokenizer.props-type.test.tsx* @input Uses vitest, TokenizerProps and Tokenizer* @output Type-level proof that the exported `TokenizerProps` stays an- * interface callers can extend and `Omit` (its `ref` typed for the combobox- * input as released), and that only the experimental opt-in admits a `ref`- * that also accepts the sheet presentation's trigger button+ * interface callers can extend and `Omit`, with its released input `ref`+ * type, that the component also accepts a ref typed for both controls it+ * can reach (the combobox input and the sheet trigger), and that+ * `presentation` takes exactly its three values* @position Core type tests; checked by `tsc`, with `@ts-expect-error`* marking the shapes that must keep failing*/-import {createRef, type ComponentProps} from 'react';+import {createRef, type ComponentProps, type Ref} from 'react';import {describe, it, expect} from 'vitest';import type {SearchableItem} from '../Typeahead/types';import {Tokenizer, type TokenizerProps} from './Tokenizer';@@ -52,6 +53,18 @@ void same;const inputRef = createRef<HTMLInputElement>();const wideRef = createRef<HTMLInputElement | HTMLButtonElement>();+// TokenizerProps keeps its released ref type, so a wrapper that forwards it+// to an input still compiles.+const refType: TokenizerProps<Item>['ref'] extends+ Ref<HTMLInputElement> | undefined+ ? true+ : never = true;+void refType;+function ForwardingField({ref}: Pick<TokenizerProps<Item>, 'ref'>) {+ return <input ref={ref} />;+}+void ForwardingField;+export function compiles() {return (<>@@ -67,9 +80,9 @@ export function compiles() {value={[]}onChange={() => {}}ref={inputRef}- experimental={{presentation: 'adaptive'}}+ presentation="popover"/>- {/* The stable shape: ref is the combobox input's. */}+ {/* An input-typed ref still type-checks. */}<Tokenizerlabel="Tags"searchSource={source}@@ -77,38 +90,44 @@ export function compiles() {onChange={() => {}}ref={inputRef}/>- {/* The experimental opt-in admits the wider ref. */}+ {/* A ref typed for both controls. */}<Tokenizerlabel="Tags"searchSource={source}value={[]}onChange={() => {}}ref={wideRef}- experimental={{presentation: 'adaptive'}}+ presentation="adaptive"/>- {/* An input-typed ref is still fine with the opt-in. */}<Tokenizerlabel="Tags"searchSource={source}value={[]}onChange={() => {}}- ref={inputRef}- experimental={{}}+ presentation="bottom-sheet"/>- {/* @ts-expect-error -- without experimental, ref keeps the released input-only type */}+ {/* The deprecated spelling still compiles. */}<Tokenizerlabel="Tags"searchSource={source}value={[]}onChange={() => {}}- ref={wideRef}+ experimental={{presentation: 'adaptive'}}+ />+ <Tokenizer+ label="Tags"+ searchSource={source}+ value={[]}+ onChange={() => {}}+ // @ts-expect-error -- presentation takes only its three values+ presentation="sheet"/></>);}describe('Tokenizer props type', () => {- it('keeps TokenizerProps an interface that extends and Omit-wraps (type-checked above)', () => {+ it('keeps TokenizerProps an interface that extends and Omit-wraps with its released ref, and accepts presentation and a ref for both controls (type-checked above)', () => {expect(typeof compiles).toBe('function');});});diff --git a/packages/core/src/Tokenizer/Tokenizer.ssr.test.tsx b/packages/core/src/Tokenizer/Tokenizer.ssr.test.tsxindex 64a91b1b28..045c7f1be1 100644--- a/packages/core/src/Tokenizer/Tokenizer.ssr.test.tsx+++ b/packages/core/src/Tokenizer/Tokenizer.ssr.test.tsx@@ -3,7 +3,8 @@* @file Tokenizer.ssr.test.tsx* @input Uses vitest, react-dom/server, react-dom/client, Tokenizer* @output Proof of component:Tokenizer FR16's server and hydration path for- * `adaptive`: the server renders the inline combobox, the client hydrates+ * the default `adaptive`: the server renders the inline combobox, the+ * client hydrates* it without a recoverable error, a coarse-pointer client swaps to the* trigger in the first post-hydration render, and focus is undisturbed* @position Core Tokenizer tests. Each case hydrates a fresh module graph and@@ -15,6 +16,7 @@ import {afterEach, describe, expect, it, vi} from 'vitest';import {hydrateRoot} from 'react-dom/client';import {renderToString} from 'react-dom/server';import type {SearchableItem, SearchSource} from '../Typeahead/types';+import type {TokenizerPresentation} from './Tokenizer';// The Tokenizer entry each case imports and its on-demand sheet, loaded// while this file is collected, which is untimed: a first load transforms// their whole module graph, which takes seconds, and many times that on a@@ -64,6 +66,7 @@ function stubCoarsePointer(matches: boolean) {}interface HydrationOptions {+ presentation?: TokenizerPresentation;hasAutoFocus?: boolean;onFocus?: () => void;onBlur?: () => void;@@ -99,7 +102,7 @@ async function hydrateFreshTokenizer(hasAutoFocus={options.hasAutoFocus}onFocus={options.onFocus}onBlur={options.onBlur}- experimental={{presentation: 'adaptive'}}+ presentation={options.presentation}/>);// The server has no matchMedia: the resolver answers `popover`.@@ -149,7 +152,7 @@ async function hydrateFreshTokenizer(return {...result, consoleErrors};}-describe('Tokenizer — SSR with experimental.presentation: adaptive (FR16)', () => {+describe('Tokenizer — SSR with the default presentation, adaptive (FR16)', () => {it('server-renders the inline combobox, hydrates it without a recoverable error, and swaps to the trigger on a coarse-pointer client with focus undisturbed', async () => {const result = await serverRenderThenHydrate(true);// The server markup is the inline field: a combobox input, no trigger.@@ -192,4 +195,16 @@ describe('Tokenizer — SSR with experimental.presentation: adaptive (FR16)', ()expect(result.trigger).toBeNull();expect(result.activeElement).toBe(document.body);}, 30000);++ it('server-renders the same markup as presentation="popover", which stays inline on a coarse-pointer client', async () => {+ const byDefault = await serverRenderThenHydrate(false);+ const popover = await serverRenderThenHydrate(true, {+ presentation: 'popover',+ });+ expect(popover.html).toBe(byDefault.html);+ expect(popover.recoverableErrors).toEqual([]);+ expect(popover.consoleErrors).toEqual([]);+ expect(popover.combobox).not.toBeNull();+ expect(popover.trigger).toBeNull();+ }, 30000);});diff --git a/packages/core/src/Tokenizer/Tokenizer.tsx b/packages/core/src/Tokenizer/Tokenizer.tsxindex 5b4d9a1293..0dca4c455f 100644--- a/packages/core/src/Tokenizer/Tokenizer.tsx+++ b/packages/core/src/Tokenizer/Tokenizer.tsx@@ -8,8 +8,8 @@* useAdaptivePresentation, and TokenizerBottomSheet (lazy)* @output Exports Tokenizer multi-select typeahead component* @position Composed component; forwards DOM ref and exposes focus control via- * handleRef. The experimental `presentation` option swaps the inline- * combobox for a trigger that opens TokenizerBottomSheet.+ * handleRef. The `presentation` prop swaps the inline combobox for a+ * trigger that opens TokenizerBottomSheet.** SYNC: When modified, update:* - /packages/core/src/Tokenizer/index.ts@@ -51,9 +51,13 @@ import {useMergedRefs} from '../hooks/useMergedRefs';import {TokenizerClearAllMessageContext} from './TokenizerClearAllMessageContext';import {TokenizerItemRemovableContext} from './TokenizerItemRemovableContext';import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';-import {useAdaptivePresentation} from '../hooks/useAdaptivePresentation';+import {+ type AdaptivePresentation,+ useAdaptivePresentation,+} from '../hooks/useAdaptivePresentation';import {useIsHydrating} from '../hooks/useIsHydrating';import {VisuallyHidden} from '../VisuallyHidden';+import {useDevWarning} from '../hooks/useDevWarning';import {warnOnce} from '../utils/devWarning';import type {SizeValue} from '../utils/types';import {BaseTypeahead} from '../Typeahead/BaseTypeahead';@@ -296,62 +300,74 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<onFocus?: (e: React.FocusEvent) => void;/** Fires when focus leaves the tokenizer entirely. */onBlur?: (e: React.FocusEvent) => void;- /** Ref forwarded to the combobox input. */+ /**+ * How the field presents its choices.+ * - `'popover'`: the inline combobox with its anchored suggestion menu, on+ * every device.+ * - `'bottom-sheet'`: a trigger showing the selected tokens that opens one+ * tall modal sheet: a search row on top, full-width checkbox rows that+ * keep their place while the sheet is open, a create row with+ * `hasCreate`, and a footer pinned in every state with a confirmed Clear+ * all and Save. The sheet edits a draft: `onChange` fires once, when Save+ * commits it, and a swipe, scrim or Escape close of a changed draft asks+ * before discarding. Suited to compact touch screens, where the inline+ * combobox competes with the software keyboard.+ * - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,+ * otherwise the popover — the same resolution Selector uses. The server+ * render and the hydrating render are the popover.+ *+ * In the sheet presentation the trigger is the control: `ref`, `id`,+ * `aria-*`, and `data-*` reach it. `renderItem`, `renderToken`,+ * `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`,+ * `tokenOverflowBehavior`, and `hasAutoFocus` have no surface to act on+ * and warn once in development. Pass `'popover'` to keep the inline field+ * and those props on every device.+ * @default 'adaptive'+ */+ presentation?: TokenizerPresentation;+ /**+ * Ref forwarded to the control: the combobox input in the popover+ * presentation, the trigger button in the sheet presentation. This type+ * keeps its released input element; the component itself also accepts a+ * `Ref<HTMLInputElement | HTMLButtonElement>`, the type to use where the+ * sheet can present.+ */ref?: React.Ref<HTMLInputElement>;/** Imperative handle ref for focus/blur control. */handleRef?: React.Ref<TokenizerHandle>;/*** Experimental options, outside the stable compatibility promise: anything- * in this object may change or be removed in a patch release. Omit it for- * the stable behavior.+ * in this object may change or be removed in a patch release.* @experimental*/experimental?: {/**- * How the field presents its choices.- * - `'popover'`: the inline combobox with its anchored suggestion menu —- * the stable behavior.- * - `'bottom-sheet'`: a trigger showing the selected tokens that opens one- * tall modal sheet: a search row on top, full-width checkbox rows that- * keep their place while the sheet is open, a create row with- * `hasCreate`, and a footer pinned in every state with a confirmed Clear- * all and Save. The sheet edits a draft: `onChange` fires once, when Save- * commits it, and a swipe, scrim or Escape close of a changed draft asks- * before discarding. Suited to compact touch screens, where the inline- * combobox competes with the software keyboard.- * - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,- * otherwise the popover — the same resolution Selector uses.- *- * In the sheet presentation the trigger is the control: `ref`, `id`,- * `aria-*`, and `data-*` reach it. `renderItem`, `renderToken`,- * `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`,- * `tokenOverflowBehavior`, and `hasAutoFocus` have no surface to act on- * and warn once in development.+ * The earlier spelling of `presentation`, with the same values. The+ * top-level `presentation` wins when both are set.* @experimental- * @default 'popover'+ * @deprecated Use the stable `presentation` prop.*/- presentation?: 'popover' | 'bottom-sheet' | 'adaptive';+ presentation?: TokenizerPresentation;};}+/** How Tokenizer presents its choices; see `TokenizerProps.presentation`. */+export type TokenizerPresentation = AdaptivePresentation;+/**- * The props the experimental opt-in admits. `experimental` is present, and- * `ref` also accepts the sheet presentation's trigger button, the control it- * stands for there. Only the overload below reaches this type. `TokenizerProps`- * stays the component's declared props type: it is an interface, so- * `interface X extends TokenizerProps<T>`, `Omit<TokenizerProps<T>, …>` and- * `ComponentProps<typeof Tokenizer>` keep their released shapes.+ * The props the component accepts: `TokenizerProps`, whose `ref` keeps its+ * released input type, with a `ref` that also accepts the sheet+ * presentation's trigger button. `TokenizerProps` stays the declared props+ * type, so `interface X extends TokenizerProps<T>`, `Omit<TokenizerProps<T>,+ * …>` and `ComponentProps<typeof Tokenizer>` keep their released shapes.*/-type TokenizerExperimentalProps<T extends SearchableItem> = Omit<+type TokenizerAcceptedProps<T extends SearchableItem> = Omit<TokenizerProps<T>,- 'ref' | 'experimental'+ 'ref'> & {- /** @experimental */- experimental: NonNullable<TokenizerProps<T>['experimental']>;/*** Ref forwarded to the control: the combobox input in the popover* presentation, the trigger button in the sheet presentation.- * @experimental*/ref?: React.Ref<HTMLInputElement | HTMLButtonElement>;};@@ -722,11 +738,11 @@ function EndLane({}// Keep this overload first. TypeScript resolves `ComponentProps<typeof-// Tokenizer>` against the last overload, so that type stays the stable props.-// A call that passes `experimental` matches this one and may pass the wider-// `ref`.+// Tokenizer>` against the last overload, so that type stays the released+// props. Every call matches this one, so a ref typed for both controls is+// accepted.export function Tokenizer<T extends SearchableItem>(- props: TokenizerExperimentalProps<T>,+ props: TokenizerAcceptedProps<T>,): React.JSX.Element;export function Tokenizer<T extends SearchableItem>(props: TokenizerProps<T>,@@ -776,12 +792,13 @@ export function Tokenizer<T extends SearchableItem>({ref,handleRef,onKeyDown,+ presentation: presentationProp,experimental,id: idProp,'aria-describedby': ariaDescribedByProp,'aria-labelledby': ariaLabelledByProp,...restProps-}: TokenizerProps<T> | TokenizerExperimentalProps<T>): React.JSX.Element {+}: TokenizerProps<T> | TokenizerAcceptedProps<T>): React.JSX.Element {const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});const {rest, container} = useFieldInputStyling('Tokenizer', restProps, {containerXstyle,@@ -807,11 +824,16 @@ export function Tokenizer<T extends SearchableItem>({const inputRef = useRef<HTMLInputElement>(null);const wrapperRef = useRef<HTMLDivElement>(null);- // Experimental presentation (`component:Tokenizer` DEC-3). `adaptive`- // resolves through the policy the selection controls share; an open sheet- // keeps its presentation until it closes, so a resolution change mid-task- // cannot pull the surface out from under the person.- const presentation = experimental?.presentation ?? 'popover';+ // `adaptive` resolves through the policy the selection controls share. An+ // open sheet keeps its presentation until it closes. A resolution change+ // during a task does not replace the open surface.+ const presentation =+ presentationProp ?? experimental?.presentation ?? 'adaptive';+ useDevWarning(+ 'Tokenizer',+ '`presentation` and `experimental.presentation` are both set; `presentation` wins. Remove `experimental.presentation`.',+ presentationProp !== undefined && experimental?.presentation !== undefined,+ );const resolvedPresentation = useAdaptivePresentation(presentation);const [isSheetOpen, setIsSheetOpen] = useState(false);// Latched for the sheet's lifetime: a sheet stays presented after it closes@@ -931,7 +953,7 @@ export function Tokenizer<T extends SearchableItem>({inertSheetProps.length === 1 ? 'has' : 'have'} no surface in the bottom-sheet presentation and ${inertSheetProps.length === 1 ? 'is' : 'are'- } not rendered there.`,+ } not rendered there. Pass \`presentation="popover"\` to keep the inline field on every device.`,);// eslint-disable-next-line @eslint-react/exhaustive-deps -- keyed by the joined names}, [inertSheetPropsKey]);@@ -1466,8 +1488,8 @@ export function Tokenizer<T extends SearchableItem>({{...rest}ref={useMergedRefs(inputRef,- // With `experimental`, the ref type admits the trigger too; in- // this presentation it receives the input.+ // The ref type admits the sheet's trigger too; in this+ // presentation it receives the input.ref as React.Ref<HTMLInputElement> | undefined,handOffFocusRef,)}diff --git a/packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx b/packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsxindex d561b409f3..23f1318cd4 100644--- a/packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx+++ b/packages/core/src/Tokenizer/TokenizerBottomSheet.test.tsx@@ -1,10 +1,9 @@// Copyright (c) Meta Platforms, Inc. and affiliates./*** @file TokenizerBottomSheet.test.tsx- * @input Uses vitest, Testing Library, Tokenizer with- * `experimental.presentation`- * @output Tests for the experimental sheet presentation: the presentation- * resolution (`component:Tokenizer` FR16) and the single-sheet touch flow+ * @input Uses vitest, Testing Library, Tokenizer with `presentation`+ * @output Tests for the sheet presentation: the presentation resolution and+ * its default (`component:Tokenizer` FR16) and the single-sheet touch flow* (FR17–FR24, AR6)* @position Core tests; validates Tokenizer.tsx and TokenizerBottomSheet.tsx*/@@ -28,7 +27,11 @@ import {} from '@testing-library/react';import {createRef, useState} from 'react';import * as stylex from '@stylexjs/stylex';-import {Tokenizer, type TokenizerChange} from './Tokenizer';+import {+ Tokenizer,+ type TokenizerChange,+ type TokenizerProps,+} from './Tokenizer';import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';import {__resetDevWarnings} from '../utils/devWarning';import {colorVars, sizeVars, spacingVars} from '../theme/tokens.stylex';@@ -93,7 +96,7 @@ function Harness({setValue(items);spy?.(items, change);}}- experimental={{presentation}}+ presentation={presentation}{...props}/>);@@ -161,39 +164,66 @@ beforeEach(() => {});afterEach(() => vi.unstubAllGlobals());-describe('Tokenizer experimental.presentation (FR16)', () => {- it('keeps the inline combobox when experimental is omitted', () => {- render(- <Tokenizer- label="Tags"- searchSource={source}- value={[ITEMS[0]]}- onChange={() => {}}- />,- );+describe('Tokenizer presentation (FR16)', () => {+ const plain = (props: Partial<TokenizerProps<SearchableItem>> = {}) => (+ <Tokenizer+ label="Tags"+ searchSource={source}+ value={[ITEMS[0]]}+ onChange={() => {}}+ {...props}+ />+ );++ it('keeps the inline combobox by default on a screen that is not compact coarse-pointer', () => {+ render(plain());expect(screen.getByRole('combobox')).toBeInTheDocument();expect(screen.queryByRole('button', {name: 'Tags'}),).not.toBeInTheDocument();});- it('keeps the inline combobox for an empty experimental object and for popover', () => {- const {unmount} = render(- <Tokenizer- label="Tags"- searchSource={source}- value={[]}- onChange={() => {}}- experimental={{}}- />,- );- expect(screen.getByRole('combobox')).toBeInTheDocument();- unmount();- render(<Harness presentation="popover" />);+ it('defaults to adaptive: the sheet trigger on a compact coarse-pointer screen', () => {+ stubMatchMedia(() => true);+ render(plain());+ expect(screen.queryByRole('combobox')).not.toBeInTheDocument();+ expect(openTrigger()).toHaveAttribute('aria-haspopup', 'dialog');+ });++ it('keeps the inline combobox with presentation="popover" on a compact coarse-pointer screen', () => {+ stubMatchMedia(() => true);+ const {unmount} = render(<Harness presentation="popover" />);expect(screen.getByRole('combobox')).toBeInTheDocument();expect(screen.queryByRole('button', {name: 'Tags'}),).not.toBeInTheDocument();+ unmount();+ // An empty experimental object leaves the default in place.+ render(plain({experimental: {}}));+ expect(screen.queryByRole('combobox')).not.toBeInTheDocument();+ });++ it('still honors the deprecated experimental.presentation, and presentation wins over it with one development warning', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const {unmount} = render(+ plain({experimental: {presentation: 'bottom-sheet'}}),+ );+ expect(screen.queryByRole('combobox')).not.toBeInTheDocument();+ expect(openTrigger()).toBeInTheDocument();+ expect(warn).not.toHaveBeenCalled();+ unmount();+ render(+ plain({+ presentation: 'popover',+ experimental: {presentation: 'bottom-sheet'},+ }),+ );+ expect(screen.getByRole('combobox')).toBeInTheDocument();+ expect(warn).toHaveBeenCalledTimes(1);+ expect(String(warn.mock.calls[0][0])).toContain(+ '`presentation` and `experimental.presentation` are both set',+ );+ warn.mockRestore();});it('forces the sheet trigger for bottom-sheet on every device', async () => {@@ -510,7 +540,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}maxMenuItems={120}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(screen.getByRole('button', {name: 'Items'}));@@ -613,7 +643,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}debounceMs={0}onChangeQuery={onChangeQuery}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -644,7 +674,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}debounceMs={0}emptySearchText="Nothing here"- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);expect(@@ -677,7 +707,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[]}onChange={() => {}}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -925,7 +955,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}debounceMs={0}maxMenuItems={5}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -971,7 +1001,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {debounceMs={0}maxMenuItems={2}hasCreate- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -1079,7 +1109,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={value}onChange={items => setValue(items)}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>);}@@ -1162,7 +1192,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange: () => {},onChangeQuery,debounceMs: 0,- experimental: {presentation: 'bottom-sheet' as const},+ presentation: 'bottom-sheet' as const,};const {rerender} = render(<Tokenizer {...props} />);fireEvent.click(openTrigger());@@ -1193,7 +1223,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange: () => {},debounceMs: 0,minQueryLength: 3,- experimental: {presentation: 'bottom-sheet' as const},+ presentation: 'bottom-sheet' as const,};const {rerender} = render(<Tokenizer {...props} />);fireEvent.click(openTrigger());@@ -1249,7 +1279,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[ITEMS[0]]}onChange={() => {}}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);const trigger = openTrigger();@@ -1267,7 +1297,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}debounceMs={0}isDisabled- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);expect(trigger).toHaveAttribute('aria-expanded', 'false');@@ -1288,7 +1318,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[ITEMS[0]]}onChange={() => {}}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);expect(trigger).toHaveAttribute('aria-expanded', 'false');@@ -1309,7 +1339,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {status={{type: 'error', message: 'Pick at least three'}}isDisableddisabledMessage="Locked while syncing"- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/></>,);@@ -1382,7 +1412,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {ref={ref}onFocus={onFocus}onKeyDown={onKeyDown}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);const trigger = openTrigger();@@ -1415,7 +1445,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {debounceMs={0}onFocus={onFocus}onBlur={onBlur}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/><button type="button">Elsewhere</button></>,@@ -1466,7 +1496,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {debounceMs={0}onFocus={onFocus}onBlur={onBlur}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/><button type="button">Elsewhere</button></>,@@ -1510,7 +1540,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}debounceMs={0}onClick={onClick}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);const trigger = openTrigger();@@ -1538,7 +1568,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}hasClearmenuWidth={320}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);expect(warn).toHaveBeenCalledTimes(1);@@ -1553,7 +1583,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}hasClearmenuWidth={320}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);expect(warn).toHaveBeenCalledTimes(1);@@ -1601,7 +1631,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[]}onChange={() => {}}hasCreate- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -1775,7 +1805,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[]}onChange={() => {}}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -1845,7 +1875,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {).not.toBeInTheDocument();});- it('types ref for the control it reaches: the input without experimental, input or trigger with it', () => {+ it('gives ref the control it reaches: the input in the popover presentation, the trigger in the sheet', () => {const inputRef = createRef<HTMLInputElement>();const {unmount} = render(<Tokenizer@@ -1866,7 +1896,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[]}onChange={() => {}}ref={wideRef}- experimental={{presentation: 'popover'}}+ presentation="popover"/>,);expect(wideRef.current).toBe(screen.getByRole('combobox'));@@ -1877,7 +1907,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[]}onChange={() => {}}ref={wideRef}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);expect(wideRef.current).toBe(openTrigger());@@ -1895,7 +1925,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {debounceMs={0}minQueryLength={3}hasCreate- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -1950,7 +1980,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {<span aria-hidden="true"> (decorative)</span></p>}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -2046,7 +2076,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[]}onChange={() => {}}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -2114,7 +2144,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}debounceMs={0}minQueryLength={3}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -2180,7 +2210,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChangeQuery={onChangeQuery}debounceMs={0}hasCreate- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -2273,7 +2303,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {debounceMs={0}minQueryLength={3}hasCreate- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -2327,7 +2357,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}onChangeQuery={setQuery}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/><output data-testid="mirror">{query}</output></>@@ -2371,7 +2401,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {searchSource={source}value={[ITEMS[0]]}onChange={() => {}}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -2449,7 +2479,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {value={[]}onChange={() => {}}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(openTrigger());@@ -2485,8 +2515,15 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {dispatchEvent: vi.fn(),}));vi.stubGlobal('matchMedia', matchMedia);- // The default popover, with and without the experimental object: no- // query is evaluated and no listener is registered.+ // A fixed presentation evaluates no query and registers no listener.+ render(<Harness presentation="popover" />);+ render(<Harness presentation="bottom-sheet" />);+ expect(+ matchMedia.mock.calls.filter(([q]) => q === COMPACT_TOUCH_QUERY),+ ).toHaveLength(0);+ expect(added.filter(q => q === COMPACT_TOUCH_QUERY)).toHaveLength(0);+ // Only adaptive reads the policy, and subscribes once: by default and+ // when it is passed.const {unmount} = render(<Tokenizerlabel="Tags"@@ -2495,16 +2532,10 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}/>,);- render(<Harness presentation="popover" />);- render(<Harness presentation="bottom-sheet" />);- expect(- matchMedia.mock.calls.filter(([q]) => q === COMPACT_TOUCH_QUERY),- ).toHaveLength(0);- expect(added.filter(q => q === COMPACT_TOUCH_QUERY)).toHaveLength(0);+ expect(added.filter(q => q === COMPACT_TOUCH_QUERY)).toHaveLength(1);unmount();- // Only adaptive reads the policy, and subscribes once.render(<Harness presentation="adaptive" />);- expect(added.filter(q => q === COMPACT_TOUCH_QUERY)).toHaveLength(1);+ expect(added.filter(q => q === COMPACT_TOUCH_QUERY)).toHaveLength(2);});it('moves focus to the sheet panel on open, not the search field (FR18)', async () => {@@ -2650,7 +2681,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {isDisabled={isDisabled}disabledMessage="You need the Editor role"ref={ref}- experimental={{presentation: 'popover'}}+ presentation="popover"/>);const {rerender} = render(field(false));@@ -2684,7 +2715,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}onFocus={onFocus}ref={() => {}}- experimental={{presentation: 'popover'}}+ presentation="popover"/>,);const input = screen.getByRole('combobox');@@ -2700,7 +2731,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}onFocus={onFocus}ref={() => {}}- experimental={{presentation: 'popover'}}+ presentation="popover"/>,);expect(input).toHaveFocus();@@ -2715,7 +2746,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}onFocus={onFocus}ref={() => {}}- experimental={{presentation: 'popover'}}+ presentation="popover"/>,);expect(document.body).toHaveFocus();@@ -2730,7 +2761,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}htmlName="tags"status={{type: 'error', message: 'Pick at least three'}}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);const hidden = container.querySelectorAll('input[type="hidden"]');@@ -2756,7 +2787,7 @@ describe('Tokenizer sheet presentation (single-sheet touch flow)', () => {onChange={() => {}}htmlName="tags"isDisabled={isDisabled}- experimental={{presentation}}+ presentation={presentation}/></form>);@@ -2992,7 +3023,7 @@ describe('Tokenizer sheet under the BottomSheet stack (component:BottomSheet FR8value={value}onChange={items => setValue(items)}debounceMs={0}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/></BottomSheet></>diff --git a/packages/core/src/Tokenizer/TokenizerBottomSheet.tsx b/packages/core/src/Tokenizer/TokenizerBottomSheet.tsxindex 5d3755e159..e43d93f792 100644--- a/packages/core/src/Tokenizer/TokenizerBottomSheet.tsx+++ b/packages/core/src/Tokenizer/TokenizerBottomSheet.tsx@@ -8,7 +8,7 @@* EmptyState, AlertDialog, Icon, Spinner, Text, useBusyAnnouncement, and* the i18n translator* @output Exports TokenizerBottomSheet — the touch surface of- * `Tokenizer experimental.presentation="bottom-sheet"`: one tall modal sheet+ * `Tokenizer presentation="bottom-sheet"`: one tall modal sheet* with a search row on top, stable-order checkbox rows, progressive* long-list rendering, an optional create row, and a confirmed Clear all* @position Internal presentation surface of Tokenizer. Loaded on demand bydiff --git a/packages/core/src/Tokenizer/index.ts b/packages/core/src/Tokenizer/index.tsindex f168f53c98..1e331dd1b6 100644--- a/packages/core/src/Tokenizer/index.ts+++ b/packages/core/src/Tokenizer/index.ts@@ -16,6 +16,7 @@ export type {TokenizerProps,TokenizerSize,TokenizerOverflowBehavior,+ TokenizerPresentation,TokenizerChange,TokenizerHandle,TokenizerStatus,diff --git a/packages/core/src/__tests__/slotPresence.controls.test.tsx b/packages/core/src/__tests__/slotPresence.controls.test.tsxindex 20d8160ade..1fc5616536 100644--- a/packages/core/src/__tests__/slotPresence.controls.test.tsx+++ b/packages/core/src/__tests__/slotPresence.controls.test.tsx@@ -161,7 +161,7 @@ describe('Tokenizer startIcon follows isRenderable', () => {],['the bottom-sheet trigger',- {value: [token], experimental: {presentation: 'bottom-sheet'}},+ {value: [token], presentation: 'bottom-sheet'},],];diff --git a/packages/core/src/hooks/useAnnounceRenderedText.adopters.test.tsx b/packages/core/src/hooks/useAnnounceRenderedText.adopters.test.tsxindex 516c0d1738..05be2b8cf2 100644--- a/packages/core/src/hooks/useAnnounceRenderedText.adopters.test.tsx+++ b/packages/core/src/hooks/useAnnounceRenderedText.adopters.test.tsx@@ -196,7 +196,7 @@ const ADOPTERS: Record<string, () => Promise<void>> = {onChange={() => {}}debounceMs={0}emptySearchText={<em>Nothing called that</em>}- experimental={{presentation: 'bottom-sheet'}}+ presentation="bottom-sheet"/>,);fireEvent.click(screen.getByRole('button', {name: 'Tags'}));