@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f899313

package/src/MultiSelector/MultiSelector.spec.md

@@ -1,24 +1,24 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:MultiSelector
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
 review_triggers: [public-api, behavior, theming, accessibility]
 verified_by:
   [
     packages/core/src/MultiSelector/MultiSelector.test.tsx,
-    packages/core/src/BottomSheet/BottomSheet.test.tsx,
-    packages/core/src/CheckboxInput/CheckboxInput.test.tsx,
-    packages/core/src/Divider/Divider.test.tsx,
-    packages/core/src/Field/Field.test.tsx,
-    packages/core/src/Icon/Icon.test.tsx,
-    packages/core/src/Text/Text.test.tsx,
+    packages/core/src/MultiSelector/MultiSelector.fr10.test.tsx,
+    packages/core/src/MultiSelector/MultiSelector.focusableDisabled.test.tsx,
+    packages/core/src/MultiSelector/CreateRow.a11y.chromium.spec.ts,
+    packages/core/src/MultiSelector/OptionActions.a11y.chromium.spec.ts,
+    packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
     scripts/check-knowledge.mjs,
   ]
 modules: []
@@ -31,45 +31,52 @@ architecture:
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: [spec:AST-011/DEC-1, spec:AST-079/DEC-1]
+system_specs:
+  [
+    spec:AST-001,
+    spec:AST-011/DEC-1,
+    spec:AST-055,
+    spec:AST-056,
+    spec:AST-058,
+    spec:AST-079/DEC-1,
+    spec:AST-085,
+    spec:AST-086,
+    spec:AST-102,
+  ]
 ---
 
 # MultiSelector component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | None changes. MultiSelector takes `options`, controlled `value` and `onChange`, `changeAction`, display and format props, `hasSearch`, `hasSelectAll`, `hasCreate`, `isReadOnly`, `isDisabled` and `disabledMessage`, `isLoading`, `presentation`, `renderTrigger`, `handleRef`, `onOpenChange`, field props, and `container*` and `control*` styling. |
+| Behavior                | A combobox trigger opens a listbox (or a grid once an option carries an action) in a pointer popup or a bottom sheet; options toggle without closing; search filters with announced counts; a create row can mint the typed query; read-only and disabled states stay focusable.                                                                       |
+| End-user impact         | People pick several values by pointer or keyboard, search long lists, and hear counts and changes; disabled and read-only fields stay reachable and explain themselves. The field does not grow with a set text size.                                                                                                                                  |
+| Builder impact          | Builders style the field through `container*` and `control*`, may render their own trigger, and receive creations through `onChange`.                                                                                                                                                                                                                  |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Loading read as no options, the zero-option popup, and the fixed field height are listed under Current-state impact.                                                                                                                                                                         |
+| Review checks           | Reject a second panel tree per presentation, a lost target, an editable read-only field, native `disabled`, a caller handler reached while disabled, or a create row offered for an exact match.                                                                                                                                                       |
+| Governing rules         | `family:input-fields`; `spec:AST-001` FR3, FR4, FR6; `spec:AST-011` DEC-1; `spec:AST-055`; `spec:AST-056`; `spec:AST-058`; `spec:AST-085`; `spec:AST-086`; `spec:AST-102` FR4; `architecture:component-theming-surface`.                                                                                                                               |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
 MultiSelector renders a multi-selection control with an optional standalone Field
 shell and one shared panel content tree in either an anchored pointer popup or a
 touch-oriented BottomSheet. It also supports a read-only state that preserves and
 submits the selected values without exposing that panel or an editing affordance.
-This draft records current consumer anatomy, theming ownership, and read-only
-behavior.
 
 ## Compatibility and migration
 
-- Released default preserved: `yes`
-- `isReadOnly` is additive and defaults to `false`. It preserves selected values,
-  focus, and form participation while removing selection-surface and editing
-  affordances. `isDisabled` takes precedence when both are set.
-- Existing DOM, styling, targets, and public API remain unchanged when the prop is
-  omitted.
-- `renderTrigger`, `handleRef`, and `onOpenChange` are additive and absent by
-  default. When omitted, DOM, styling, targets, keyboard behavior, and public
-  API remain unchanged. With `renderTrigger`, the caller-rendered control replaces
-  the Field shell and Trigger by the caller's choice, not as a change to the
-  released default.
-- `hasCreate` is additive and off by default. `onChange` gains an optional
-  second argument, a `MultiSelectorChange` descriptor, passed only for a
-  creation; a one-argument handler keeps working. When `hasCreate` is omitted,
-  DOM, styling, targets, keyboard behavior, announcements, and the callback's
-  calls are unchanged.
-- Controlled/uncontrolled behavior: unchanged. Open state stays owned by the
-  component; `handleRef` drives it and `onOpenChange` reports it.
-- 0.7.0 removes the `multi-selector-clear-icon` alias; the shared clear glyph
-  remains available through `input-clear-icon`.
-- Migration decision: replace the removed theme key and CSS class with
-  `input-clear-icon` and `.astryx-input-clear-icon`, or run
-  `astryx upgrade --from 0.6.3 --apply --path .`
+- Released default preserved: yes
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
+- Controlled/uncontrolled behavior: `value` is controlled; open state is the
+  component's, driven by `handleRef` and reported by `onOpenChange`
+- Migration decision: none; the removed `multi-selector-clear-icon` alias is
+  replaced by the shared `input-clear-icon` target (FR6)
 
 Consumer migration instructions belong in consumer docs and release notes.
 
@@ -77,9 +84,9 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- The painted Trigger and its current `multi-selector` target.
+- The painted Trigger and its `multi-selector` target.
 - Indicator icon, Search row, Option row, Section heading, Empty state, and
-  Pointer popup presentation through the other six current MultiSelector targets.
+  Pointer popup presentation through the other six MultiSelector targets.
 - One shared panel-content tree containing optional search, option, divider,
   section, and empty-state content regardless of which presentation hosts it.
 
@@ -104,30 +111,33 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-This table names the additive concept introduced by `spec:AST-011`. Complete prop
-syntax and examples remain in `MultiSelector.doc.mjs`.
+Complete prop syntax and examples remain in `MultiSelector.doc.mjs`.
 
-| Concept         | Closed values or states         | Meaning                                                                                             | Availability                                                | Default | Owner  | Stability | Invalid-value behavior                                       |
-| --------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------- | ------ | --------- | ------------------------------------------------------------ |
-| read-only state | `false`, `true`                 | Preserves and submits values without selection affordance                                           | Closed trigger                                              | `false` | Caller | additive  | Boolean normalization                                        |
-| anchored mode   | `renderTrigger` absent, present | Caller-rendered control replaces Field shell and Trigger; panel anchored to it and named by `label` | Pointer popup and Touch sheet                               | absent  | Caller | additive  | Render prop must return the control carrying the given props |
-| create row      | `hasCreate` `false`, `true`     | First row minting the typed query, reported through `onChange` as `{type: 'create', query}`         | Search mode, query matching no option label, options loaded | `false` | Caller | additive  | Without `hasSearch`: development warning, nothing offered    |
+| Concept         | Closed values or states         | Meaning                                                                                             | Availability                                                 | Default | Owner  | Stability | Invalid-value behavior                                        |
+| --------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------- | ------ | --------- | ------------------------------------------------------------- |
+| read-only state | `false`, `true`                 | Preserves and submits values without selection affordance                                           | Closed trigger                                               | `false` | Caller | stable    | Boolean normalization                                         |
+| anchored mode   | `renderTrigger` absent, present | Caller-rendered control replaces Field shell and Trigger; panel anchored to it and named by `label` | Pointer popup and Touch sheet                                | absent  | Caller | stable    | Render prop must return the control carrying the given props  |
+| create row      | `hasCreate` `false`, `true`     | First row minting the typed query, reported through `onChange` as `{type: 'create', query}`         | Search mode, query matching no option label, not `isLoading` | `false` | Caller | stable    | Without `hasSearch`: development warning, nothing offered     |
+| option action   | `action` absent, present        | The option's secondary control as one node; the popup is a grid of rows pairing option and action   | Pointer popup and Touch sheet                                | absent  | Caller | stable    | `null` is none; a control without a name warns in development |
 
 ## Behavioral and layout contract
 
-| ID            | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Basis                                                                                             | Draft review state                                 |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| FR1           | The current standalone presentation contains a Field and painted Trigger; the supported InputGroup path renders the same Trigger without a Field. Optional start content, clear action, status icon, or Indicator icon follows supplied props and state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current source, docs, and tests                                                                   | Verified current behavior; no new behavior decided |
-| FR2           | The shared panel content contains the optional Search row, zero or more Option rows, optional public Option dividers and Section headings, and an Empty state when the applicable result set is empty and the value is not loading.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source, docs, and tests                                                                   | Verified current behavior; no new behavior decided |
-| FR3           | Trigger, Indicator icon, Search row, Option row, Section heading, Empty state, and Pointer popup carry the seven current non-deprecated MultiSelector targets documented in `MultiSelector.doc.mjs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Current source, docs, and tests                                                                   | Verified current behavior; no target change        |
-| FR4           | When present, Field, shared clear actions, option checkbox indicators, public Option dividers, general icons, Touch sheet heading, and Touch sheet retain their Field, CheckboxInput, Divider, Icon, Text, and BottomSheet theming owners.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current composition and owners                                                                    | Verified current behavior; no target change        |
-| FR5           | Pointer popup and Touch sheet are separate surface anatomy rows, but both host the same `panelContent` tree; the Touch sheet additionally renders its Heading. Changing presentation does not create a second search, option, divider, section, or empty-state content model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests                                                                          | Verified current behavior; no normalization        |
-| FR6           | Clear glyphs delegate exclusively to the shared `input-clear-icon` target; removed per-component aliases do not claim anatomy.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current public target metadata                                                                    | Verified canonical ownership                       |
-| FR7           | While `isReadOnly` is true, selected values remain focusable and form-submittable, while the selection surface, clear action, disclosure indicator, and every value-change path are unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `spec:AST-011`, docs, and tests                                                                   | Accepted read-only behavior                        |
-| FR8           | With `renderTrigger`, the caller-rendered control receives `ref`, `id`, `onClick`, `onKeyDown`, `onFocus`, `aria-haspopup`, `aria-expanded`, `aria-controls`, and `aria-busy`; the panel is anchored to it, focus returns to it on close, the listbox is named by `label`, and the listbox takes focus and owns the keyboard on open. No Field, status, clear action, spinner, or indicator renders. `handleRef` exposes `open`, `close`, `toggle`, `isOpen`; `onOpenChange` fires on every open and close.                                                                                                                                                                                                                                                                                                                                                                                                                                    | DEC-1, docs, and tests                                                                            | Proposed; awaiting owner approval                  |
-| FR9           | With `hasSearch` and `hasCreate`, once options have loaded, a `Create "<query>"` row leads the list when the trimmed query equals no option label under the search's own case-insensitive matching. Picking it, or Enter with nothing highlighted, calls `onChange` with the query appended to the value and a `{type: 'create', query}` descriptor, clears the search, and announces the creation; every other change passes no descriptor. The row has no checkbox, is never selected, is excluded from select-all and from `renderOption`, and is announced instead of the empty message when it is the only result. While `isLoading`, no row is offered and Enter commits nothing. `hasCreate` without `hasSearch` warns in development and offers nothing.                                                                                                                                                                               | `spec:AST-056` FR5 / DEC-3, `component:Tokenizer` `hasCreate`, docs, and tests                    | Proposed; awaiting owner approval                  |
-| option action | `action` absent, present                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | The option's secondary control as one node; the popup is a grid of rows pairing option and action | Pointer popup and Touch sheet                      | absent | Caller | additive | `null` is none; a control without a name warns in development |
-| FR10          | Once any declared option — at any depth of sections, before any query filters it — carries an `action`, the popup is a `role="grid"` and stays one while mounted; the trigger advertises `aria-haspopup="grid"` (the bottom sheet keeps `dialog`). Each option, the select-all row included, is a `role="row"` carrying the option's id, `aria-selected` and `aria-disabled`, with exactly two `gridcell` children: the option's content, then its action or an empty cell. A section is a `rowgroup` named by its title. Pressing the option cell toggles; pressing the action fires the caller's control and nothing else. Up/Down move rows onto the option cell; the inline-end arrow moves to the action cell and the inline-start arrow back, following visual direction under RTL; Enter on the action cell activates the control. `aria-activedescendant` names the row or the action cell. No control inside the popup is a tab stop. | `spec:AST-058` FR1–FR8, AR1–AR4                                                                   | Proposed; awaiting owner approval                  |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Basis                                                                     |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
+| FR1  | The current standalone presentation contains a Field and painted Trigger; the supported InputGroup path renders the same Trigger without a Field. Optional start content, clear action, status icon, or Indicator icon follows supplied props and state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source, docs, and tests                                           |
+| FR2  | The shared panel content contains the optional Search row, zero or more Option rows, optional public Option dividers and Section headings, and an Empty state when the applicable result set is empty and the value is not loading. Option-source pending MUST be supplied independently and MUST NOT be inferred from input `isLoading` (`spec:AST-001` FR4), and with zero provided options and no pending state the field MUST be read-only with no selectable option, stating so without opening a popup (`spec:AST-001` FR3, FR6). Implementation gap: no explicit pending state exists; `isLoading` is read as options not yet arrived, so it withholds the Empty state, the create row (FR9), and search announcements (FR14); and a field with zero options keeps an actionable trigger that opens a listbox showing `emptyText`.                                                                                            | Current source, docs, and tests; `spec:AST-001` FR3, FR4, FR6             |
+| FR3  | Trigger, Indicator icon, Search row, Option row, Section heading, Empty state, and Pointer popup carry the seven current non-deprecated MultiSelector targets documented in `MultiSelector.doc.mjs`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Current source, docs, and tests                                           |
+| FR4  | When present, Field, shared clear actions, option checkbox indicators, public Option dividers, general icons, Touch sheet heading, and Touch sheet retain their Field, CheckboxInput, Divider, Icon, Text, and BottomSheet theming owners.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Current composition and owners                                            |
+| FR5  | Pointer popup and Touch sheet are separate surface anatomy rows, but both host the same `panelContent` tree; the Touch sheet additionally renders its Heading. Changing presentation does not create a second search, option, divider, section, or empty-state content model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests                                                  |
+| FR6  | Clear glyphs delegate exclusively to the shared `input-clear-icon` target; removed per-component aliases do not claim anatomy.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Current public target metadata                                            |
+| FR7  | While `isReadOnly` is true, selected values remain focusable and form-submittable, while the selection surface, clear action, disclosure indicator, and every value-change path are unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `spec:AST-011` DEC-1; current docs and tests                              |
+| FR8  | With `renderTrigger`, the caller-rendered control receives `ref`, `id`, `onClick`, `onKeyDown`, `onFocus`, `aria-haspopup`, `aria-expanded`, `aria-controls`, and `aria-busy`; the panel is anchored to it, focus returns to it on close, the listbox is named by `label`, and on open the search input takes focus with `hasSearch`, and otherwise the listbox, which then owns the keyboard. No Field, status, clear action, spinner, or indicator renders. `handleRef` exposes `open`, `close`, `toggle`, `isOpen`; `onOpenChange` fires on every open and close.                                                                                                                                                                                                                                                                                                                                                                 | `spec:AST-055` FR1–FR7, AR1–AR4; DEC-1; current docs and tests            |
+| FR9  | With `hasSearch` and `hasCreate`, while `isLoading` is not set, a `Create "<query>"` row leads the list when the trimmed query equals no option label under the search's own case-insensitive matching. Picking it, or Enter with nothing highlighted, calls `onChange` with the query appended to the value and a `{type: 'create', query}` descriptor, clears the search, and announces the creation; every other change passes no descriptor. The row has no checkbox, is never selected, is excluded from select-all and from `renderOption`, and is announced instead of the empty message when it is the only result. While `isLoading`, no row is offered and Enter commits nothing. `hasCreate` without `hasSearch` warns in development and offers nothing. Withholding the row while `isLoading` is the FR2 gap.                                                                                                           | Current behavior; `spec:AST-056` FR5 and DEC-3                            |
+| FR10 | Once any declared option — at any depth of sections, before any query filters it — carries an `action`, the popup is a `role="grid"` and stays one while mounted; the trigger advertises `aria-haspopup="grid"` (the bottom sheet keeps `dialog`). Each option, the select-all row included, is a `role="row"` carrying the option's id, `aria-selected` and `aria-disabled`, with exactly two `gridcell` children: the option's content, then its action or an empty cell. A section is a `rowgroup` named by its title. Pressing the option cell toggles; pressing the action fires the caller's control and nothing else. Up/Down move rows onto the option cell; the inline-end arrow moves to the action cell and the inline-start arrow back, following visual direction under RTL; Enter on the action cell activates the control. `aria-activedescendant` names the row or the action cell. No action control is a tab stop. | `spec:AST-058` FR1–FR8, AR1–AR4                                           |
+| FR11 | No surface renders native `disabled`. A disabled trigger keeps its tab stop with `aria-disabled`; no press opens it or reaches a caller or ancestor handler, and no key opens it or reaches a caller handler; it submits no value; a `disabledMessage` Tooltip is linked from the trigger through `aria-describedby`; and only `isDisabled` takes disabled paint. While busy (`isLoading` or a pending `changeAction`) the trigger shows a Spinner and `aria-busy`, keeps its ordinary paint, and announces each busy start once.                                                                                                                                                                                                                                                                                                                                                                                                    | `spec:AST-085` FR1–FR6; `spec:AST-086` FR8; `family:input-fields` FR4–FR6 |
+| FR12 | ArrowDown on the focused trigger opens the list; ArrowDown and ArrowUp move the highlight; Home and End jump to the first and last option without search, while with search they move the caret and PageDown and PageUp jump the highlight; Enter toggles the highlighted option except during input-method composition; Escape closes; Tab closes and moves focus on, except that while a query shows the search's clear button, forward Tab moves to that button and keeps the list open; with `hasClear` and without `hasSearch`, Delete or Backspace on the focused, closed trigger clears every value when one is selected.                                                                                                                                                                                                                                                                                                     | Current source and tests                                                  |
+| FR13 | The field has no root styling props: `control*` reaches the bordered control box around the trigger and `container*` the Field box (`family:input-fields` FR10); a press on the control box outside the trigger opens it; a caller `onClick` runs after the built-in toggle and a caller `onKeyDown` after the built-in keyboard model, and is skipped for keys that model handles and cancels; a caller `aria-describedby` joins the field description and a caller `aria-labelledby` follows the field's own name. With `renderTrigger`, `container*` and `control*` have no effect and warn. The trigger height is the shared element size for its size and MUST grow with a set text size (`spec:AST-102` FR4). Implementation gap: the height is fixed.                                                                                                                                                                         | `family:input-fields` FR10; `spec:AST-102` FR4; current tests             |
+| FR14 | Each toggle, select-all, or clear announces politely: the all-selected message when every option ends selected, the cleared message when none does, and otherwise the selection count. Once a person searches, the match count (or the empty-results message, or the create row's label when it is the only result) is announced politely; no search result is announced while `isLoading` (the FR2 gap). With `htmlName` the field submits one entry per selected value.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `spec:AST-086`; current tests                                             |
 
 ### Allowed variation
 
@@ -156,11 +166,15 @@ syntax and examples remain in `MultiSelector.doc.mjs`.
 
 ### Transformation and precedence order
 
-- No new search, selection, presentation, or styling precedence rule is introduced.
+- **ORD1 — Change.** Toggle, select-all, clear, or create → `onChange` (with a
+  descriptor only for a creation) → `changeAction` with the optimistic value.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- **PR1 — Bounded resources.** The component adds no event listener or
+  observer of its own; its timers are an animation frame that moves focus as
+  the panel opens and the typeahead reset timeout. Announcements use the shared
+  polite channel.
 
 ## Accessibility contract
 
@@ -178,17 +192,18 @@ this state.
 
 With `renderTrigger`, the caller's control carries `aria-haspopup`, `aria-expanded`,
 and `aria-controls` for the listbox, the listbox carries `aria-label` from
-`label` instead of `aria-labelledby` the trigger, and the listbox is the
-focused element that owns arrow, Enter, Escape, and typeahead keys while open,
-so an anchor that cannot take focus still leaves a keyboard path.
+`label` instead of `aria-labelledby` the trigger, and on open the search input
+(with `hasSearch`) or the listbox takes focus and owns arrow, Enter, Escape, and
+typeahead keys while open, so an anchor that cannot take focus still leaves a
+keyboard path.
 
-The create row is a `role="option"` with `aria-selected="false"` and no checkbox
-indicator. When it is the only result, the polite live region announces its
+The create row is a `role="option"`, or a `role="row"` with an empty action
+cell in a grid (FR10), with `aria-selected="false"` and no checkbox indicator. When it is the only result, the polite live region announces its
 label rather than the empty-search message, so what is announced matches what is
 on screen; picking it announces the creation. The result count and the create
-row's label come from the search's own `useAnnounce({hasReplace: true})`
-instance, so a newer one replaces one not yet spoken (`spec:AST-086` FR9), and
-selection messages keep their own instance.
+row's label come from the search's own replacing announcer, so a newer one
+replaces one not yet spoken (`spec:AST-086` FR9), and selection messages keep
+their own announcer.
 
 ## Design relationships
 
@@ -208,7 +223,7 @@ selection messages keep their own instance.
 | Option checkbox indicator     | Presents the option's selected, unselected, or indeterminate state through CheckboxInput.         | CheckboxInput component        | Supporting        | FR2, FR4           |
 | Option divider                | Separates adjacent groups when a public divider entry is present in the options data.             | Divider component              | Supporting        | FR2, FR4           |
 | Section heading               | Labels a visible group of option rows.                                                            | Current source and public docs | Supporting        | FR2, FR3           |
-| Empty state                   | Presents no-options or no-results content when the panel has no selectable rows to show.          | Current source and public docs | Prominent         | FR2, FR3           |
+| Empty state                   | Presents no-results content when a search leaves no rows; the no-options content is the FR2 gap.  | Current source and public docs | Prominent         | FR2, FR3           |
 | Pointer popup                 | Paints the anchored pointer surface around the shared panel content.                              | Current source and public docs | Prominent         | FR3, FR5           |
 | Touch sheet heading           | Names the bottom-sheet presentation above the shared panel content.                               | Text component                 | Prominent         | FR4, FR5           |
 | Touch sheet                   | Paints the BottomSheet surface around the same shared panel content.                              | BottomSheet component          | Prominent         | FR4, FR5           |
@@ -282,8 +297,10 @@ empty-state content remains one shared tree.
 
 ## Family and system relationships
 
-- `architecture:public-component-api` and `spec:AST-011/DEC-1` own the additive
+- `architecture:public-component-api` and `spec:AST-011/DEC-1` own the
   read-only API and its cross-input meaning.
+- `spec:AST-055` owns the caller-rendered trigger (FR8).
+- `spec:AST-001` owns option-source pending state (FR2).
 - `architecture:component-theming-surface` owns anatomy qualification, local
   target mapping, delegation, and exclusion of removed aliases.
 - `architecture:layer-runtime` owns the current Popover host and the distinction
@@ -296,56 +313,46 @@ empty-state content remains one shared tree.
 
 ## Verification map
 
-| Contract            | Verification                                                                                                                             | Representative states                                                                                                                                                                                                                              | Mutation or failure expectation                                                                                                                                                                                                                                                | Audit section                       |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- |
-| FR1, FR2            | `MultiSelector.test.tsx` render, search, divider, grouping, status, select-all, and empty-state suites plus InputGroup source inspection | Standalone/InputGroup, search, divided, selected, empty, status                                                                                                                                                                                    | Removing a documented part or misreporting Field presence conflicts with existing structure, content assertions, or source.                                                                                                                                                    | `audit:MultiSelector/anatomy`       |
-| FR3, FR6            | Component target suites, source inspection, and public target inventory                                                                  | All seven canonical local targets and shared clear-icon delegation                                                                                                                                                                                 | A current target is missed, invented, moved, or the clear glyph stops delegating to `input-clear-icon`.                                                                                                                                                                        | `audit:MultiSelector/theming`       |
-| FR4                 | Composed owner source/tests for Field, CheckboxInput, Divider, Icon, Text, and BottomSheet                                               | Field omission/presence, clear actions, checkbox, divider, icons, heading, sheet                                                                                                                                                                   | A shared part gains the wrong local owner or its documented owner no longer renders it.                                                                                                                                                                                        | `audit:MultiSelector/theming`       |
-| FR5                 | `MultiSelector.test.tsx` presentation suites and `panelContent` source inspection                                                        | Explicit popover, explicit sheet, adaptive touch                                                                                                                                                                                                   | A presentation stops using its owner or receives a divergent panel-content implementation.                                                                                                                                                                                     | `audit:MultiSelector/overlay`       |
-| FR7                 | read-only interaction, form, ARIA, and theme-state tests                                                                                 | search/non-search, clearable, open→read-only, disabled precedence                                                                                                                                                                                  | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent.                                                                                                                                                                   | `audit:MultiSelector/accessibility` |
-| FR8                 | `MultiSelector.test.tsx` "trigger render prop" suite                                                                                     | External trigger closed/open; handle open/close; disabled; listbox focus                                                                                                                                                                           | Field chrome renders with a trigger, the control lacks disclosure state, the listbox is unnamed, or the handle opens a disabled selector.                                                                                                                                      | `audit:MultiSelector/accessibility` |
-| FR9                 | `MultiSelector.test.tsx` "hasCreate" suite; `CreateRow.a11y.chromium.spec.ts` appear/disappear cycle                                     | Create row offered, committed by click/Enter with descriptor, skipped on a case-insensitive exact match, offered for a label the filter cannot surface, absent while loading, beside select-all; toggle without descriptor; warning without search | The row appears while loading or for an existing label, reports without a descriptor, keeps the search text, is silently inert without search, or the live region says "no results" beside a create row.                                                                       | `audit:MultiSelector/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                            | Canonical anatomy and current local targets                                                                                                                                                                                                        | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.                                                                                                                                                                                     | `audit:MultiSelector/theming`       |
-| FR10                | `MultiSelector.test.tsx` "option actions (grid)" suite; `OptionActions.a11y.chromium.spec.ts`; `Selector.test.tsx` non-adoption case     | No action; `action: null`; action inside a section; filtered out; removed later; options after loading; click cell vs action; disabled option with action; arrows LTR/RTL; search Left/Right; hover; Tab; unnamed control                          | A grid with no declared action, a listbox with one, a role that follows the filtered view, a row with other than two cells, a `group` in a grid, a toggle on an action press, an action unreachable by arrow, a tab stop inside the popup, or an action absent at rest, fails. | `audit:MultiSelector/accessibility` |
-
-Existing component tests directly assert the Trigger, Indicator icon, Search row,
-Option row, Section heading, Empty state, and Pointer popup targets. Presentation
-tests directly distinguish the Popover and BottomSheet branches. Source inspection
-distinguishes standalone Field presence from InputGroup omission and confirms that both surface branches receive the same `panelContent`, while the touch branch
-adds Heading; Divider, Text, BottomSheet, and other shared primitive tests provide
-owner evidence rather than new MultiSelector targets.
+| Contract            | Verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Representative states                                             | Mutation or failure expectation                                                                                                                                                                                                                                                                                        | Audit section                       |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| FR1, FR2            | `MultiSelector.test.tsx` render, labels, count, sections, list-structure, search-affordance, select-all, and empty-state cases; "keeps a standalone secondary trigger out of the group geometry"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Standalone and grouped; search; sections; select-all; empty       | A missing Field, trigger part, search row, option, divider, heading, or empty state fails; the no-options cases assert the current FR2 gap pending conformance. Evidence gap: no test asserts that the InputGroup path omits the Field.                                                                                | `audit:MultiSelector/anatomy`       |
+| FR3, FR6            | `MultiSelector.test.tsx` theme-target cases (empty state, clear icon, indicator icon, disabled state, option row, popup); `themingTargets.test.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Every local target; shared clear glyph                            | A missing or moved target, or a clear glyph with a component alias, fails. Evidence gap: no test asserts the `multi-selector-search` or section-heading targets.                                                                                                                                                       | `audit:MultiSelector/theming`       |
+| FR4                 | `MultiSelector.test.tsx` "routes the clear glyph through the shared clear button" and statusVariant cases                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Shared clear and status                                           | A clear or status that leaves its shared owner fails. Evidence gap: no test asserts the CheckboxInput, Divider, Text, and BottomSheet delegation beyond rendering.                                                                                                                                                     | `audit:MultiSelector/theming`       |
+| FR5                 | `MultiSelector.test.tsx` "uses a bottom sheet and stays open while toggling options", "uses a bottom sheet for adaptive presentation on compact touch", "moves keyboard focus into a bottom-sheet listbox"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Popover and sheet                                                 | A sheet that closes on a toggle or lacks the listbox fails. Evidence gap: no test asserts that both presentations host one panel tree.                                                                                                                                                                                 | `audit:MultiSelector/behavior`      |
+| FR7                 | `MultiSelector.test.tsx` isReadOnly cases; "a read-only selector advertises no panel on the caller's control"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Read-only with loading; pointer, keyboard, typeahead              | A read-only field that opens or changes fails. Evidence gap: no test asserts read-only form submission or `aria-readonly`.                                                                                                                                                                                             | `audit:MultiSelector/behavior`      |
+| FR8                 | `MultiSelector.test.tsx` trigger render prop, read-only, and focus-return cases; `MultiSelector.fr10.test.tsx` renderTrigger cases                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Caller control closed and open; handle; disabled; focus return    | A caller control that does not open the panel, name the listbox, or get focus back, or a handle that opens a disabled selector, fails.                                                                                                                                                                                 | `audit:MultiSelector/behavior`      |
+| FR9                 | `MultiSelector.test.tsx` hasCreate cases; `CreateRow.a11y.chromium.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Create offered, committed, skipped, absent while loading; warning | A create row for an exact match, while loading, or without search, or a creation without its descriptor, fails.                                                                                                                                                                                                        | `audit:MultiSelector/behavior`      |
+| FR10                | `MultiSelector.test.tsx` option-actions (grid), ring-under-mixed-input, and create-row-in-grid cases; `OptionActions.a11y.chromium.spec.ts`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Listbox and grid; RTL; search; hover; Tab                         | A grid without actions, a listbox with them, a wrong cell activation, reversed RTL arrows, or an action control as a tab stop fails.                                                                                                                                                                                   | `audit:MultiSelector/accessibility` |
+| FR11                | `MultiSelector.focusableDisabled.test.tsx` cases; `MultiSelector.test.tsx` disabledMessage cases, "trigger keeps its tab stop when disabled (spec:AST-085 FR1)", "shows no disabled focus ring after a pointer pick (spec:AST-085 FR6)", "shows loading state with a spinner and aria-busy", "is excluded from form data when disabled"; `BusyOwnerAnnouncement.test.tsx` MultiSelector cases                                                                                                                                                                                                                                                                                                         | Disabled with and without a reason; loading; pending Action       | Native `disabled`, an open or caller handler while disabled, a value submitted while disabled, an unlinked reason, or a missing busy announcement fails. Evidence gap: no test asserts the busy-only paint.                                                                                                            | `audit:MultiSelector/accessibility` |
+| FR12                | `MultiSelector.test.tsx` keyboard cases ("supports keyboard navigation with ArrowDown/ArrowUp", "End/Home jump the highlight to the last/first option (non-search)", "PageDown/PageUp jump the highlight to the last/first filtered option", "Home/End move the search caret, not the option highlight", "toggles item with Enter key", "does not toggle the highlighted option on a composing Enter (IME)", "closes on Escape", "closes combobox on Tab and moves focus to next element", "opens the listbox with ArrowDown from a focused trigger", the Delete and Backspace clear cases), and "tabs from the search input to the clear button (keeping the popup open) when a query is showing it" | Current source and tests                                          | A key that does the wrong move, a composing Enter that toggles, or a clear with nothing selected fails.                                                                                                                                                                                                                | `audit:MultiSelector/accessibility` |
+| FR13                | `MultiSelector.fr10.test.tsx` cases; `MultiSelector.test.tsx` caller aria-labelledby cases                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Control box; caller handlers; renderTrigger                       | A root styling prop, `control*` off the control box, a caller handler before the built-in one, or a lost caller name or description fails. Evidence gap: no test asserts that a caller `onKeyDown` is skipped for a key the built-in model cancels, or the trigger height or its growth with text size (the FR13 gap). | `audit:MultiSelector/layout`        |
+| FR14, ORD1          | `MultiSelector.test.tsx` announcements, result-announcement, count-text, and form-participation cases; hasCreate announcement cases                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Toggle, select-all, clear; search counts; loading; form           | A missing or wrong announcement, a search-result announcement while loading, or a wrong form entry fails. Evidence gap: no test asserts the `onChange`-before-`changeAction` order.                                                                                                                                    | `audit:MultiSelector/behavior`      |
+| PR1                 | Evidence gap: no test asserts the absence of listeners or the timer bounds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | —                                                                 | —                                                                                                                                                                                                                                                                                                                      | `audit:MultiSelector/behavior`      |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Canonical anatomy and targets                                     | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                                                                                                  | `audit:MultiSelector/theming`       |
+
+## Current-state impact
+
+- **Loading read as no options (FR2).** `isLoading` withholds the Empty state,
+  the create row, and search announcements, so a person searching while the
+  field reports loading sees and hears nothing, against `spec:AST-001` FR4.
+- **Zero options (FR2).** A field with no options keeps an actionable trigger
+  that opens a "No options" list instead of a read-only no-choice state,
+  against `spec:AST-001` FR3 and FR6.
+- **Fixed field height (FR13).** The trigger holds the shared element height
+  instead of growing with a set text size, against `spec:AST-102` FR4.
 
 ## Decision log
 
-- **DEC-1 — Anchored mode through `renderTrigger` + `handleRef`, not a controlled
-  `isOpen`.** A picker anchored in a row the caller owns (a link row whose
-  opener is a presentational glyph) cannot host the Field shell or a nested
-  button. The caller renders the control and spreads the given props; the
-  component keeps owning open state, and `handleRef`/`onOpenChange` open it
-  from a keystroke elsewhere and report every change — the rule already written
-  on `ComplexSelectorHandle`. Rejected: an `anchorRef` plus controlled
-  `isOpen`, which mirrors open state in the parent and reintroduces the focus
-  pitfalls that rule names.
+- **DEC-1 — Anchored mode opens through `handleRef`, not a controlled
+  `isOpen`.** The caller-rendered trigger itself follows `spec:AST-055`. The
+  component keeps owning open state, and `handleRef`/`onOpenChange` open it from
+  a keystroke elsewhere and report every change — the rule already written on
+  `ComplexSelectorHandle`. Rejected: an `anchorRef` plus controlled `isOpen`,
+  which mirrors open state in the parent and reintroduces the focus pitfalls
+  that rule names.
 
   **Decider:** `cixzhang`, 2026-10-03
 
-- **DEC-2 — The create row is one switch reporting through `onChange`.** The
-  row exists only while a query does, so it is enabled by `hasCreate` alone
-  and reported on the channel the caller already listens to, with a
-  descriptor naming the creation and the typed text already in the value, so
-  adding the option and accepting the value are one update (`spec:AST-056`
-  DEC-3; the shape `Tokenizer` ships). The duplicate rule is the search's own
-  matching rule at full equality: a label the filter shows as an exact match
-  is never offered for creation, and one the filter cannot surface for the
-  query is never a dead end. Nothing is offered while options are loading,
-  because a label a moment from arriving is not new. Rejected: a `hasCreate` +
-  `onCreate` pair (three silently inert half-configurations); offering the
-  row while loading (mints duplicates); a diacritic-folding duplicate rule
-  beside a case-only filter (hides `Café` from `CAFE` and refuses to create
-  it — the two rules widen together under `spec:AST-056` FR4 or not at all).
-
-  **Decider:** pending owner review
-
 ## Open questions
 
 None.

package/src/MultiSelector/MultiSelector.tsx

@@ -1215,11 +1215,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // (spec:AST-086 FR8).
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the trigger container (which already exists)
-  // and the trigger button stays perceivable via aria-disabled instead of the
-  // disabled attribute. Activation is blocked by the isDisabled guards in
-  // useMultiCombobox (onTriggerClick / onKeyDown).
+  // Disabled-reason tooltip listeners attach to the existing trigger container.
+  // The trigger stays focusable via aria-disabled. Trigger guards and the value
+  // commit guards below block activation, including from an already-open panel.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -1626,6 +1624,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // Clear all selected values. Shared by the clear button and the keyboard
   // Delete/Backspace path so clearing is reachable without a mouse.
   const clearValues = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
     onChange([]);
     announceSelection([]);
     if (changeAction) {
@@ -1635,6 +1636,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       });
     }
   }, [
+    isDisabled,
     onChange,
     changeAction,
     startTransition,
@@ -1663,6 +1665,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
 
   const handleToggle = useCallback(
     (itemValue: string) => {
+      if (isDisabled) {
+        return;
+      }
       const newValue = optimisticValue.includes(itemValue)
         ? optimisticValue.filter(v => v !== itemValue)
         : [...optimisticValue, itemValue];
@@ -1677,6 +1682,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       }
     },
     [
+      isDisabled,
       optimisticValue,
       onChange,
       changeAction,
@@ -1711,6 +1717,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       : false;
 
   const handleSelectAll = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
     let newValue: string[];
     if (allEnabledSelected) {
       // Deselect all enabled items, keep disabled items that are selected
@@ -1736,6 +1745,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       });
     }
   }, [
+    isDisabled,
     allEnabledSelected,
     enabledItems,
     optimisticValue,
@@ -1752,6 +1762,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // the option the caller adds is visible.
   const commitCreate = useCallback(
     (query: string) => {
+      if (isDisabled) {
+        return;
+      }
       const newValue = optimisticValue.includes(query)
         ? optimisticValue
         : [...optimisticValue, query];
@@ -1766,6 +1779,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       }
     },
     [
+      isDisabled,
       optimisticValue,
       onChange,
       changeAction,