Skip to content

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

TypeScript

docs(spec): combobox over a caller-rendered field (AST-075) (#7353)

Christopher Chedeaudb3a2e7fdfce
diff --git a/docs/specs/AST-075-owned-field-combobox/spec.md b/docs/specs/AST-075-owned-field-combobox/spec.md
new file mode 100644
index 0000000000..a197f61a7e
--- /dev/null
+++ b/docs/specs/AST-075-owned-field-combobox/spec.md
@@ -0,0 +1,184 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-075
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-15
+phase: accepted
+owners: [vjeux]
+affects_architecture:
+ [architecture:interaction-modality, architecture:public-component-api]
+affects_families: [family:input-fields, family:overlay-dismissal]
+affects_contributing: []
+affects_consumer_docs:
+ [BaseTypeahead, Typeahead, ChatComposerInput, useCombobox, useMultiCombobox]
+---
+
+# Combobox over a caller-rendered field system spec
+
+## Intent
+
+A person picks from a filtered list while focus stays in a text field the
+product renders itself: a chat composer's textarea, a search field above an
+emoji grid, a settings search whose results replace a page section, an "add
+people" field whose matches list inline in a dialog. Astryx gives that field the
+combobox semantics and keyboard model it gives its own typeahead input. The
+product supplies the field, the rows, and where the list renders, and composes
+the behavior from hooks; every such field behaves and announces the same way.
+
+## Non-goals
+
+- The field's shell and appearance, the rows' appearance, and where the list
+ renders (a layer or the page's flow) stay with the caller.
+- Searching, filtering, debouncing, and asynchronous sources stay with the
+ caller.
+- Finding the query inside the field's text, such as text after a trigger
+ character in a composer, stays with the caller.
+- Comboboxes whose focus sits on a button (`Selector`, `MultiSelector`) or that
+ live in a modal command surface (`CommandPalette`) keep their own records; this
+ spec does not set one interaction model for every combobox.
+- Equivalent internal implementations remain valid when they satisfy this
+ contract.
+
+## Requirements
+
+- **FR1 — Focus stays in the field.** Moving the active option MUST NOT move DOM
+ focus out of the field. The field MUST name the active option through
+ `aria-activedescendant`, which references a rendered option, and MUST carry no
+ `aria-activedescendant` while no option is active.
+- **FR2 — Expanded state follows the list.** While the list is shown, the field
+ MUST expose `aria-expanded="true"` and an `aria-controls` that names the
+ listbox. While it is not shown, the field MUST expose `aria-expanded="false"`
+ and MUST NOT reference an element that is not rendered. A `textarea` field
+ (FR3) exposes `aria-controls` the same way and carries no `aria-expanded`.
+- **FR3 — Roles.** The field MUST expose an accessible name. An `input` or a
+ contenteditable field MUST expose `role="combobox"`. A `textarea`, which
+ admits no explicit role, keeps its implicit `textbox` role and MUST expose
+ `aria-autocomplete="list"`. The list MUST be a named
+ `listbox` whose rows are `option`s, with `aria-selected="true"` on the active
+ one. The listbox MAY render anywhere in the document, including the page's
+ flow. Controls that are not options MUST render outside the listbox.
+- **FR4 — Keys.** While the list is shown, ArrowDown and ArrowUp MUST move the
+ active option, Enter on an active option MUST pick it and only then stop the
+ field's own Enter, and Escape MUST hide the list without dismissing an
+ enclosing layer in the same press (`family:overlay-dismissal`). While the list
+ is hidden, ArrowDown in a single-line `input` field MUST show the list when it
+ has options, as `component:BaseTypeahead` does for its own input; in a
+ multi-line field (a `textarea` or a contenteditable element) every key MUST
+ reach the field and its surroundings unchanged, so the arrows keep moving the
+ caret between lines. While the list is shown, Home and End are outside this
+ requirement until OQ2 is ruled, and every other key MUST reach the field
+ unchanged.
+- **FR5 — Input method.** A key MUST NOT activate a combobox command, including
+ Escape's dismissal (`family:overlay-dismissal`), while an input-method
+ composition is active.
+- **FR6 — Pointer.** Moving the pointer over an option MUST make it active
+ without moving DOM focus. Pressing an option MUST pick it, and the field MUST
+ keep focus through the press.
+- **FR7 — Result count.** When the options change for a new query, the number of
+ options, or that there are none, MUST be announced politely through the shared
+ announcer rather than a live region per field.
+- **FR8 — The hooks are discoverable as hooks.** Each public hook that
+ implements this contract MUST be returned by `astryx hook <name>` and
+ `astryx search` with its parameters, its return fields, and the requirements
+ above it satisfies, so a product finds it without first finding a component
+ that uses it.
+
+### Platform support
+
+- Supported feature/engine floor: the repository's supported engines; no new CSS
+ or DOM feature.
+- Unsupported behavior: none; screen readers announce `aria-activedescendant` on
+ a contenteditable combobox unevenly, and FR1 still holds there.
+- Browser evidence: Chromium accessibility-tree receipts for FR1–FR3 and real
+ keyboard and pointer input for FR4–FR6, with screen-reader claims bounded by
+ `spec:AST-009`.
+
+## Current-state impact
+
+- `component:BaseTypeahead` meets AR1–AR5 for the input it renders; this
+ contract carries the same obligations to a field the caller renders.
+- `component:ChatComposerInput` exposes combobox semantics for its trigger menu
+ inside its own contenteditable field only, through an internal hook.
+- `useCombobox` (exported from `@astryxdesign/core/Selector`) already tracks the
+ active option, opens and closes, and handles the keys for Selector and
+ CommandPalette; `useMultiCombobox` (exported from
+ `@astryxdesign/core/MultiSelector`) does the same for MultiSelector. Both take
+ their own component's option type, leave the ARIA wiring to the caller, and do
+ not yet guard keys during an input-method composition (FR5).
+- `useTypeahead` already ignores keys during an input-method composition, and
+ `useAnnounce` is the shared announcer FR7 names.
+- Both combobox hooks ship hook docs that `astryx hook` and `astryx search`
+ return, but neither yet names the requirements above it satisfies (FR8).
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR3 | Chromium accessibility-tree binding under `spec:AST-021`; unit tests | input, textarea, contenteditable; list in a layer and in flow | focus leaves the field, a stale `aria-activedescendant` or `aria-controls` remains, or axe reports `aria-allowed-role` or `aria-allowed-attr` on the field |
+| FR4, FR6 | real keyboard and pointer input in Chromium | arrows, Enter, Escape inside a dialog, hover and press; ArrowDown on a hidden list in an `input` and in a `textarea` | a key or press picks, dismisses, or blurs the field at the wrong time |
+| FR5 | composition event tests | candidate selection confirmed with Enter | Enter during composition picks an option |
+| FR7 | shared announcer tests | results, none, a new query | no announcement, or an announcement from a per-field live region |
+| FR8 | CLI hook discovery tests over core's exported hooks | each public hook named in DEC-2; a hook exported from a component's entry point | a combobox hook is exported without a hook doc, or `astryx hook <name>` denies it exists |
+
+## Decision log
+
+### DEC-1 — The caller renders the field and the list; Astryx owns the semantics and the keys
+
+**Reference:** `spec:AST-075/DEC-1`
+**Decider:** `cixzhang`, `2026-10-15`
+
+A product that already renders a composer, a search field, or a dialog field
+cannot adopt the typeahead without replacing that field and moving its list into
+a layer, so it wires the combobox pattern by hand, and each copy differs in the
+details FR1–FR7 fix. With the field and the list left to the caller and the
+semantics owned by Astryx, every such surface meets one tested contract.
+
+Rejected: requiring the product's field to be the typeahead's own input — a textarea or contenteditable composer cannot be one, and an in-flow list is not a layer.
+
+### DEC-2 — The contract ships as composable hooks, built on `useCombobox`
+
+**Reference:** `spec:AST-075/DEC-2`
+**Decider:** `cixzhang`, `2026-10-15`
+
+A product builds a combobox over its own field by composing hooks, the same way
+Astryx builds its own: `useCombobox` for the active option, the expanded state
+and the keys, generalized from Selector's option type to any option list and to
+a field the caller renders; the input-method guard `useTypeahead` already
+applies; and `useAnnounce` for the result count. Astryx's own comboboxes compose
+the same hooks, so one tested implementation backs every surface this spec
+covers, and each hook is documented as a hook (FR8). Generalizing
+`useCombobox` keeps its released options and return fields working unchanged
+for existing callers; the new inputs are optional additions. A component stays
+the convenient path for the common case; the hooks are the path for every other
+field.
+
+Rejected: a new component, or `BaseTypeahead` accepting a caller's field, which
+keeps the behavior locked inside one component's markup.
+
+### DEC-3 — A hidden list reopens on ArrowDown in a single-line field only
+
+**Reference:** `spec:AST-075/DEC-3`
+**Decider:** `cixzhang`, `2026-10-15`
+
+In a single-line field the arrows have no caret work to do, so ArrowDown
+reopens a hidden list, the keyboard model Astryx's own typeahead input already
+gives. In a multi-line field the arrows move the caret between lines, which a
+person writing a message needs, so they reach the field while the list is
+hidden.
+
+Rejected: leaving every key to every field while the list is hidden, which
+leaves a single-line search field with no keyboard way back to its list but
+typing.
+
+## Open questions
+
+- **OQ2 — Home and End** (`human-design`): in a field the caller renders, they
+ either keep moving the caret or move to the first and last option, as
+ `component:BaseTypeahead` FR5 does for its own input.
+- **OQ3 — A two-dimensional list** (`human-api`): whether a grid of options,
+ such as an emoji picker, belongs to this contract or to a separate one.