An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): Typeahead, BaseTypeahead, and TypeaheadItem record their shipped contract as current (#9277)
Cindy Zhange30ffbfbe218
diff --git a/docs/specs/components/Typeahead/BaseTypeahead.spec.md b/docs/specs/components/Typeahead/BaseTypeahead.spec.mdindex ffb498b6ac..4d8c2bb250 100644--- a/docs/specs/components/Typeahead/BaseTypeahead.spec.md+++ b/docs/specs/components/Typeahead/BaseTypeahead.spec.md@@ -1,20 +1,21 @@---schema_version: 3-template_version: 4+template_version: 7kind: componentid: component:BaseTypeahead-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-11-01owners: [cixzhang]review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by:[packages/core/src/Typeahead/BaseTypeahead.test.tsx,+ packages/core/src/Typeahead/BaseTypeahead.incremental.test.tsx,packages/core/src/Typeahead/Typeahead.test.tsx,- packages/core/src/Tokenizer/Tokenizer.test.tsx,+ packages/core/src/Typeahead/BaseTypeahead.emptyState.a11y.chromium.spec.ts,packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]@@ -28,11 +29,26 @@ architecture:architecture:layer-runtime,]contributing: []-system_specs: []+system_specs:+ [spec:AST-020/FR15, spec:AST-058, spec:AST-085, spec:AST-086, spec:AST-092]---# BaseTypeahead component contract+## Contract at a glance++| Area | Contract |+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | None changes. BaseTypeahead takes a search source, controlled `value` and `onChange`, `hasEntriesOnFocus`, `minQueryLength`, debounce, result cap, `renderItem`, `size`, popup width, disabled props, and BaseProps for the input. |+| Behavior | A bare combobox input searches after a grapheme threshold and debounce, rejects stale responses, and shows a named listbox of options with keyboard and pointer selection; a completed empty search shows a message (today a disabled option, the FR4 gap). |+| End-user impact | People find and pick a result by typing; screen-reader users hear result counts. An Escape-dismissed list can reopen when a late response lands, and a natively disabled input loses its Tab stop. |+| Builder impact | Direct callers own the visible wrapper, label, and focus ring; Typeahead and Tokenizer compose it. |+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The empty-search option, the Escape reopen, caller handlers while disabled, native `disabled`, and the result content order are listed under Current-state impact. |+| Review checks | Reject stale results replacing newer ones, an invalid listbox, a busy state without one Spinner, dropped BaseProps, or a popup past the viewport gutters. |+| Governing rules | `spec:AST-020` FR15; `spec:AST-085` FR1, FR2; `spec:AST-058` FR7, FR9; `spec:AST-086`; `spec:AST-092`; `family:overlay-dismissal`; `architecture:public-component-api`; `architecture:layer-runtime`. |++This table is a review projection; the body below is authoritative.+## IntentBaseTypeahead is the exported combobox engine beneath Typeahead and Tokenizer. It@@ -41,17 +57,14 @@ styled result listbox, loading feedback, and selection callbacks. A direct callesupplies the visible input wrapper, accessible name, and selected-valuepresentation.-This draft records verified shipped or audit-remediated behavior. It does not-approve a new prop, default, compatibility promise, visual treatment, or-ownership boundary.-## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: patch corrections preserve the existing public surface-- Controlled/uncontrolled behavior: controlled `value` remains unchanged-- Migration decision: none; unresolved public-surface cleanup requires a- separate compatibility decision+- Compatibility class: records shipped behavior; no public prop, default,+ export, or DOM change+- Controlled/uncontrolled behavior: `value` is controlled; query text is+ internal+- Migration decision: none; public-surface cleanup is OQ1 and OQ2Consumer migration instructions belong in consumer docs and release notes.@@ -77,34 +90,34 @@ Consumer migration instructions belong in consumer docs and release notes.## Public concepts-| Concept | Closed values or states | Meaning | Availability by state | Default | Owner | Stability | Invalid-value behavior |-| --------------- | ---------------------------------------- | ------------------------------------------------------------ | -------------------------- | -------------------------------- | ---------------------------- | --------- | ------------------------------------------------------------------------------- |-| selection | `T` or `null` | Caller-controlled selected result | all states | required | `component:BaseTypeahead` | released | caller retains control |-| search source | `search`, `bootstrap`, optional `cancel` | Supplies query and focus results | enabled input | required | `component:BaseTypeahead` | released | rejected work clears current results |-| focus bootstrap | on or off | Offers bootstrap results before query input | empty focused input | off | `component:BaseTypeahead` | released | off keeps the menu closed |-| query threshold | non-negative number | Minimum visible-character count before search | non-empty query | `1` | `component:BaseTypeahead` | released | below threshold cancels work and closes results |-| debounce | milliseconds | Delays query search | typed query | `150` | `component:BaseTypeahead` | released | non-positive runs immediately |-| result cap | number | Limits fetched results shown | completed search/bootstrap | `10` | `component:BaseTypeahead` | released | source order is preserved |-| result content | default, `renderItem`, or `item.element` | Chooses content inside the stable option row | result present | default TypeaheadItem | caller and component | released | `item.element` takes precedence |-| disabled state | native or focusable-disabled | Blocks query mutation; native disabled blocks all activation | disabled | native disabled | component and caller wrapper | released | a list open before focusable-disabled applied picks nothing and can still close |-| popup width | intrinsic or fixed pixels | Sets result popup width before viewport clamping | popup present | intrinsic, at least anchor width | `component:BaseTypeahead` | released | viewport fit wins |-| size | `sm`, `md`, `lg` | Selects option-row padding | popup options | `md` | `component:BaseTypeahead` | released | TypeScript rejects other values |+| Concept | Closed values or states | Meaning | Availability by state | Default | Owner | Stability | Invalid-value behavior |+| --------------- | ---------------------------------------- | ------------------------------------------------------------ | -------------------------- | -------------------------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------------------- |+| selection | `T` or `null` | Caller-controlled selected result | all states | required | `component:BaseTypeahead` | stable | caller retains control |+| search source | `search`, `bootstrap`, optional `cancel` | Supplies query and focus results | enabled input | required | `component:BaseTypeahead` | stable | rejected work clears current results |+| focus bootstrap | on or off | Offers bootstrap results before query input | empty focused input | off | `component:BaseTypeahead` | stable | off keeps the menu closed |+| query threshold | non-negative number | Minimum visible-character count before search | non-empty query | `1` | `component:BaseTypeahead` | stable | below threshold cancels work and closes results |+| debounce | milliseconds | Delays query search | typed query | `150` | `component:BaseTypeahead` | stable | non-positive runs immediately |+| result cap | number | Limits fetched results shown | completed search/bootstrap | `10` | `component:BaseTypeahead` | stable | source order is preserved |+| result content | default, `renderItem`, or `item.element` | Chooses content inside the stable option row | result present | default TypeaheadItem | caller and component | stable | `item.element` takes precedence, except that a caller `renderItem` replaces it (the ORD1 gap) |+| disabled state | native or focusable-disabled | Blocks query mutation; native disabled blocks all activation | disabled | native disabled | component and caller wrapper | stable | a list open before focusable-disabled applied picks nothing and can still close |+| popup width | intrinsic or fixed pixels | Sets result popup width before viewport clamping | popup present | intrinsic, at least anchor width | `component:BaseTypeahead` | stable | viewport fit wins |+| size | `sm`, `md`, `lg` | Selects option-row padding | popup options | `md` | `component:BaseTypeahead` | stable | TypeScript rejects other values |## Behavioral and layout contract-Draft requirements identify their observational or current-authority basis.--| ID | Candidate invariant | Basis | Draft review state |-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |-| FR1 | The input is controlled by internal query state while `value` is caller-controlled; selecting a result calls `onChange(item)`, clears query/results, closes the popup, and returns focus to the input. | Current source and tests | verified shipped behavior |-| FR2 | Search starts only at the grapheme-count threshold, uses the configured debounce, and never presents an empty result for a query that was not searched. | Public API, current i18n character utility, tests | verified audit remediation |-| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Escape hides the current popup but does not invalidate pending work, so a late response currently reopens it (retained violation). | Current source, focused retained-red probe, and tests | verified shipped behavior |-| FR4 | The popup is a named listbox whose result rows are options. A completed empty search renders one disabled option so the listbox retains a valid owned child. | APG combobox pattern, axe, tests | verified audit remediation |-| FR5 | Arrow keys wrap the highlight; Home/End move to the first/last option; Enter selects; Escape and Tab hide the current popup; IME-owned key events do not activate combobox commands. Escape dismissal is not durable while source work remains pending (FR3). | Current source and tests | verified shipped behavior; Escape gap retained |-| FR6 | Pending asynchronous source work sets `aria-busy` and renders one named Spinner unless the composed wrapper owns the busy indicator lane. | Current source, input-family FR7, tests | verified shipped behavior |-| FR7 | Supported BaseProps DOM, ARIA, data, class, style, event, and `xstyle` inputs reach the combobox input while component-owned role, state, value, and behavior remain authoritative. | `architecture:public-component-api/INV5–INV7`, tests | verified audit remediation |-| FR8 | The popup remains within the inline viewport at 320 CSS px, including long default results and a requested width larger than the available viewport. | WCAG 1.4.10, real Chromium | verified audit remediation |-| FR9 | Native disabled removes ordinary focus and activation. Focusable-disabled uses `aria-disabled` plus `readOnly` and blocks text/query mutation, opening the list, and selection by Enter or a press, including from a list that was open before it applied; that list can still close (`spec:AST-085` FR2). | Current source and tests | verified shipped behavior |+| ID | Invariant | Basis |+| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |+| FR1 | The input is controlled by internal query state while `value` is caller-controlled; selecting a result calls `onChange(item)`, clears query/results, closes the popup, and returns focus to the input. | Current source and tests |+| FR2 | Search starts only at the grapheme-count threshold, uses the configured debounce, and never presents an empty result for a query that was not searched. | Current source and tests |+| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Escape hides the current popup without invalidating pending work, so a late response reopens it. Lists for a query that is no longer current, including partial lists, are dropped (`spec:AST-092` FR4). ArrowDown on a closed field after the source was replaced searches the replacement instead of showing the old list. | Current source and tests; `spec:AST-092` FR4 |+| FR4 | The popup is a named listbox whose result rows are options, and no active descendant is set while no option shows. A completed empty search's message MUST be presentational and announced as `spec:AST-056` AR1 requires (`spec:AST-058` FR7). Implementation gap: the message renders as one disabled option. | APG combobox pattern; `spec:AST-058` FR7; current source and tests |+| FR5 | Arrow keys wrap the highlight; Home/End move to the first/last option; Enter selects; Escape and Tab hide the current popup, Tab moving focus on; IME-owned key events do not activate combobox commands. Escape dismissal is not durable while source work remains pending (FR3). | `spec:AST-020` FR15; current source and tests |+| FR6 | Pending asynchronous source work sets `aria-busy` and renders one Spinner unless the composed wrapper owns the busy indicator lane; each busy transition is reported once. | `family:input-fields`; `spec:AST-086`; current tests |+| FR7 | Supported BaseProps DOM, ARIA, data, class, style, event, and `xstyle` inputs reach the combobox input while component-owned role, state, value, and behavior stay authoritative; an omitted legacy alias keeps its native equivalent and a defined one overrides it. A direct caller's `onKeyDown` runs before the built-in key handling, and `preventDefault()` in it skips that handling (`architecture:public-component-api` INV7); Typeahead and Tokenizer use it for their own Escape and Backspace handling, and run their callers' `onKeyDown` after the built-in handling (`component:Typeahead` FR9). | `architecture:public-component-api` INV5–INV7; current tests |+| FR8 | The popup stays within the inline viewport at 320 CSS px, including long default results and a requested width larger than the available viewport. | Current source |+| FR9 | A disabled input MUST stay focusable with `aria-disabled` (`spec:AST-085` FR1), and caller handlers other than focus and blur MUST NOT run while disabled (FR2). Focusable-disabled uses `aria-disabled` plus `readOnly` and blocks text and query mutation, opening the list, and selection by Enter or a press, including from a list that was open before it applied; that list can still close, and search work in flight when it applies is dropped. Typeahead always uses focusable-disabled, and Tokenizer does except in `unfocusedLayer` mode without a `disabledMessage`, where the input is still natively `disabled`. Implementation gap: the default disabled mode is native `disabled`, which removes the Tab stop, and a focusable-disabled input still runs caller `onClick`, `onPointerDown`, and key handlers. | `spec:AST-085` FR1, FR2; current source and tests |+| FR10 | A search source may show partial lists for a query through `context.update` before `search()` settles; the typeahead follows `spec:AST-092` FR1–FR10: it shows a partial list at once and stays busy until the final list, keeps shown rows and the highlight in place as later lists append, keeps an option's id while its item stays, announces once per query when it settles, keeps the last non-empty list when the answer fails, and warns in development when a later list moves shown rows. | `spec:AST-092` |+| FR11 | The typeahead panel has not adopted the option-action grid: a result's `action` is not rendered, the row shows without it, and a development warning reports it once (`spec:AST-058` FR9). | `spec:AST-058` FR9; current source |### Allowed variation@@ -116,22 +129,23 @@ Draft requirements identify their observational or current-authority basis.### Representative states-| State | Required invariant | Allowed variation |-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |-| rest | named combobox is closed and not busy | caller-owned wrapper and label |-| focused bootstrap | popup opens only when enabled and results exist | synchronous or asynchronous source |-| query pending | combobox is busy and duplicate stale work is rejected | direct or wrapper-owned Spinner |-| results | one highlighted option and valid active descendant | grouped/default/custom content |-| completed empty | one disabled empty option; no active descendant | caller-supplied empty text |-| selected result | matching option exposes `aria-selected=true` | generic check presentation |-| disabled | native disabled blocks activation; focusable-disabled blocks query mutation, opening and picking, also from an already-open list | native or focusable-disabled semantics |-| dismissed pending | Escape hides the popup; a late pending response currently reopens it | source completion timing |-| narrow viewport | popup and result content remain inside two viewport gutters | intrinsic or requested width |+| State | Required invariant | Allowed variation |+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |+| rest | named combobox is closed and not busy | caller-owned wrapper and label |+| focused bootstrap | popup opens only when enabled and results exist | synchronous or asynchronous source |+| query pending | combobox is busy and duplicate stale work is rejected | direct or wrapper-owned Spinner |+| results | one highlighted option and valid active descendant | grouped/default/custom content |+| completed empty | a presentational message and no active descendant; today one disabled option, the FR4 gap | caller-supplied empty text |+| selected result | matching option exposes `aria-selected=true` | generic check presentation |+| disabled | focusable with `aria-disabled`; no query change, opening, or picking; an already-open list can still close; today native `disabled` by default, the FR9 gap | with or without a disabled reason |+| dismissed pending | Escape hides the popup; a late pending response currently reopens it | source completion timing |+| narrow viewport | popup and result content remain inside two viewport gutters | intrinsic or requested width |### Transformation and precedence order- **ORD1 — Result content.** `item.element` → caller `renderItem` →- TypeaheadItem.+ TypeaheadItem. Implementation gap: a caller `renderItem` replaces+ `item.element`, which only the default TypeaheadItem renders.- **ORD2 — Input props.** Consumer rest props → defined legacy aliases (`inputId`,`ariaDescribedBy`, `ariaLabelledBy`, `inputTabIndex`) → component-ownedsemantics and handlers → component styles → consumer class/style escape@@ -139,10 +153,10 @@ Draft requirements identify their observational or current-authority basis.### Performance and resources-- **PR1 — Search lifetime.** One generation counter rejects stale responses,- including responses from a source that has since been replaced; debounce- timers and optional source cancellation are cleared on replacement and- unmount.+- **PR1 — Search lifetime.** Stale responses and partial lists, including those+ from a source that has since been replaced or that arrive after unmount, are+ rejected; the debounce timer and optional+ source cancellation are cleared on replacement and unmount.## Accessibility contract@@ -152,22 +166,23 @@ Draft requirements identify their observational or current-authority basis.`aria-labelledby` relationship; composed owners supply their visible label ID.- **AR3 — State.** Expanded, busy, disabled, active-descendant, and selectedstates are exposed programmatically.-- **AR4 — Result feedback.** Active queries announce the localized result count- or empty-result message through the shared announcer.+- **AR4 — Result feedback.** Each query announces the localized result count+ or empty-result message once, when it settles, through the shared announcer+ (`spec:AST-092` FR8).- **AR5 — Input method.** IME composition commands remain with the candidatewindow; ordinary keyboard and pointer selection remain equivalent.## Design relationships-| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |-| -------------------- | ----------------------------------------------- | -------------------------------- | ----------------- | ------------------ |-| Input | caller-owned visible chrome and focus treatment | unsettled ownership for bare use | prominent | AR2 |-| Loading status | shared Spinner | `component:Spinner` | supporting | FR6 |-| Dropdown | Popover surface with bounded listbox | current source and layer runtime | prominent | FR4, FR8 |-| Highlighted result | overlay plus forced-color outline | objective accessibility standard | prominent | FR5 |-| Empty state | disabled option message | APG/axe | supporting | FR4 |-| Default item content | TypeaheadItem | `component:Typeahead` | prominent | ORD1 |-| Caller item content | caller-owned | caller | context-dependent | ORD1 |+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| -------------------- | ------------------------------------------------------- | -------------------------------- | ----------------- | ------------------ |+| Input | caller-owned visible chrome and focus treatment | Caller; OQ3 | prominent | AR2 |+| Loading status | shared Spinner | `component:Spinner` | supporting | FR6 |+| Dropdown | Popover surface with bounded listbox | current source and layer runtime | prominent | FR4, FR8 |+| Highlighted result | overlay plus forced-color outline | Current source | prominent | FR5 |+| Empty state | empty-search message; today a disabled option (FR4 gap) | Current source | supporting | FR4 |+| Default item content | TypeaheadItem | `component:Typeahead` | prominent | ORD1 |+| Caller item content | caller-owned | caller | context-dependent | ORD1 |### Theming anatomy@@ -230,6 +245,8 @@ Draft requirements identify their observational or current-authority basis.popup is present.- `architecture:layer-runtime` owns top-layer hosting, anchoring, viewportpositioning, and native light dismissal.+- `spec:AST-092` owns incremental search results (FR10).+- `spec:AST-058` owns the empty-search message and option actions (FR4, FR11).- `architecture:public-component-api` owns reachable exports and BasePropspassthrough semantics.- `architecture:component-theming-surface` owns anatomy qualification and target@@ -237,22 +254,40 @@ Draft requirements identify their observational or current-authority basis.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| --------------- | ------------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |-| FR1–FR2 | BaseTypeahead and Typeahead tests | query, overlap, select, clear | current work replaces newer results or selection does not close | `audit:BaseTypeahead/behavior` |-| FR3 | shared stale-response tests plus retained-red probe | newer query, clear, unmount, Escape while pending | late work replaces current results or reopens after explicit dismissal | `audit:BaseTypeahead/a11y` |-| FR4, AR1–AR4 | focused tests, component-scoped axe, live-region tests | results, empty, busy, selected | invalid listbox ownership or state/announcement disappears | `audit:BaseTypeahead/a11y` |-| FR5, AR5 | keyboard, focus-out, IME, and retained-red tests | arrows, Home/End, Enter, Escape, Tab, composition | command selects or dismisses at the wrong time | `audit:BaseTypeahead/a11y` |-| FR6 | busy-lane tests | direct and composed pending source | duplicate/missing Spinner or stale busy state | `audit:BaseTypeahead/a11y` |-| FR7 | focused passthrough tests and strict lint | native-only, alias collisions, DOM/style/events | supported consumer input is dropped or owned semantics are replaced | `audit:BaseTypeahead/api` |-| FR8 | real-Chromium 320px sensor receipt | long result, wide request, LTR/RTL | popup or its content crosses either viewport gutter | `audit:BaseTypeahead/responsive` |-| FR9 | shared disabled tests | native disabled; focusable-disabled before and after open | disabled mode mutates query, opens the list, or accepts a selection | `audit:BaseTypeahead/a11y` |-| Theming anatomy | knowledge and theming-target checks | all mapped parts | target inventory or disposition drifts | `audit:BaseTypeahead/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |+| FR1 | `Typeahead.test.tsx` "shows results on input change", "does not select every result when items lack ids", popover-after-selection and hasSearched-reset cases | Search, select, re-enter | A selection that keeps the query or results open, or selects several rows, fails. Evidence gap: no test asserts focus returning to the input after a selection. | `audit:BaseTypeahead/behavior` |+| FR2 | `BaseTypeahead.test.tsx` "counts grapheme clusters when enforcing minQueryLength"; `Typeahead.test.tsx` minQueryLength and paste cases | Threshold, fallback below it, paste | A search below the threshold or an empty result for an unsearched query fails. Evidence gap: no test asserts the debounce delay. | `audit:BaseTypeahead/behavior` |+| FR3, PR1 | `Typeahead.test.tsx` out-of-order async results cases ("discards a stale response that resolves after a newer query", "discards a response from a source that was replaced while it was in flight"); `BaseTypeahead.test.tsx` source-replacement cases; `BaseTypeahead.test.tsx` "loads the replacement source when ArrowDown opens the closed field", "searches the replacement source for the typed query when ArrowDown opens the closed field"; `BaseTypeahead.incremental.test.tsx` "drops lists for a query that is no longer current (FR4)", "drops lists and rejections that arrive after unmount (FR4)" | Newer query; replaced source | A stale response or partial list that replaces newer results, a list after unmount, or an old list on ArrowDown after a source replacement fails. Evidence gap: no test asserts timer cleanup or the Escape reopen. | `audit:BaseTypeahead/behavior` |+| FR4, AR1, AR3 | `BaseTypeahead.test.tsx` "exposes a completed empty search as a disabled listbox option"; `Typeahead.test.tsx` "renders input with combobox role", "sets aria-expanded=false initially", "does not set aria-activedescendant when search has 0 results"; `BaseTypeahead.emptyState.a11y.chromium.spec.ts` | Results; completed empty | An invalid listbox, an empty search with no message, or an active descendant on the message fails. Evidence gap: no test asserts `aria-selected` on the selected option. The disabled-option cases assert the current FR4 gap pending conformance. | `audit:BaseTypeahead/accessibility` |+| FR5, AR5 | `Typeahead.test.tsx` IME, focus-out, and arrow-scroll cases ("does not select the highlighted result on a composing Enter", "closes the list on the Tab keydown, before the blur it produces", "Tab from the input with the list open moves focus to the next control", "scrolls the highlighted option into view during arrow navigation", "reopens on click when the input was already focused and the dropdown closed without a blur", "picks nothing from a list opened before the field became disabled, and lets it close") | Arrows, Enter, Tab, IME | A composing Enter that selects, a Tab that keeps the list open or traps focus, or an Escape that leaves the list open or moves focus fails. Evidence gap: no test asserts the wrap, or Home and End. | `audit:BaseTypeahead/accessibility` |+| FR6 | `Typeahead.test.tsx` busy-indicator-ownership and hasEntriesOnFocus loading cases | Direct and composed busy; bootstrap | A duplicate or missing Spinner, a stale busy state, or a repeated transition report fails. | `audit:BaseTypeahead/behavior` |+| FR7, ORD2 | `BaseTypeahead.test.tsx` "forwards supported DOM, styling, and event props to the combobox input", "preserves native input attributes when legacy aliases are undefined", "lets defined legacy aliases override their native equivalents" | DOM, style, events; legacy aliases | A dropped prop, a replaced owned semantic, or a wrong alias precedence fails. Evidence gap: no test asserts that a direct caller's `onKeyDown` runs first and that `preventDefault()` in it skips the built-in handling. | `audit:BaseTypeahead/api` |+| FR8 | Evidence gap: no test asserts the popup inside the viewport at 320 CSS px | — | — | `audit:BaseTypeahead/layout` |+| FR9 | `Typeahead.test.tsx` "disables input when isDisabled" (a bare BaseTypeahead, asserting the current native-disabled gap pending conformance), "blocks typing and selection while focusable-disabled", "opens no list and picks nothing while focusable-disabled (spec:AST-085 FR2)", "does not reopen on a click into the still-focused input once disabled", "picks nothing from a list opened before the field became disabled, and lets it close", "does not open a list for a search that settles after the field became disabled", "drops a search answer that arrives after the field became disabled" | Native disabled; focusable-disabled before and after open | Typing, opening, or selecting while focusable-disabled, a list that cannot close, or a search answer that lands after disabling fails. Evidence gap: no test asserts that caller handlers are skipped while disabled. | `audit:BaseTypeahead/accessibility` |+| FR10 | `BaseTypeahead.incremental.test.tsx` cases | Partial, appended, failed, and replaced lists; groups; popup above and below; StrictMode | A partial list not shown at once, a moved row or highlight, a changed option id, a second announcement, a lost list on failure, or a missing development warning fails. | `audit:BaseTypeahead/behavior` |+| FR11 | Evidence gap: no test, matching the source's development warning | Result with `action` | A rendered action or a missing warning fails. | `audit:BaseTypeahead/behavior` |+| AR2, AR4 | `Typeahead.test.tsx` result-announcement cases ("announces the result count to a live region (comboboxes-6)", "announces the plural result count", "speaks the result count from a provider catalog", "announces \"no results found\" when the search is empty (comboboxes-6)"); `BaseTypeahead.incremental.test.tsx` "announces the result count once per query, when it settles (FR8)" | Counts, empty, provider catalog | A missing or wrong announcement fails. Evidence gap: no test asserts a direct caller's accessible name. | `audit:BaseTypeahead/accessibility` |+| ORD1 | `TypeaheadItem.test.tsx` "renders item.element raw in place of the label layout" | `item.element` | `item.element` that does not replace the default content fails. Evidence gap: no test asserts `renderItem` precedence below `item.element`. | `audit:BaseTypeahead/behavior` |+| Theming anatomy | `themingTargets.test.ts`; `scripts/check-knowledge.mjs` | Mapped parts | A rendered class absent from the documented targets, or a stale disposition, fails. | `audit:BaseTypeahead/theming` |++## Current-state impact++- **Empty-search message (FR4).** A completed empty search renders its message+ as a disabled option instead of presentational text, against `spec:AST-058`+ FR7.+- **Result content order (ORD1).** A caller `renderItem` replaces+ `item.element`, which only the default TypeaheadItem renders, although the+ `SearchableItem.element` docs give `item.element` priority.+- **Escape reopen (FR3).** A list a person dismissed with Escape reopens when a+ pending response lands.+- **Disabled input (FR9).** The default disabled mode is native `disabled`,+ which removes the Tab stop, and a focusable-disabled input still runs caller+ click, pointer, and key handlers, against `spec:AST-085` FR1 and FR2.## Decision log-None. This draft records current or objectively remediated behavior and makes no-component-local API, design, compatibility, or ownership decision.+No component-local decision.## Open questions@@ -267,4 +302,5 @@ component-local API, design, compatibility, or ownership decision.## Content boundaryThis file does not duplicate the prop reference, examples, current audit score,-shared layer mechanics, or shared accessibility and theming rules.+shared layer mechanics, or shared accessibility and theming rules. It links to+their owners.diff --git a/docs/specs/components/Typeahead/Typeahead.spec.md b/docs/specs/components/Typeahead/Typeahead.spec.mdindex 50ae4ee242..a9dde61009 100644--- a/docs/specs/components/Typeahead/Typeahead.spec.md+++ b/docs/specs/components/Typeahead/Typeahead.spec.md@@ -1,49 +1,63 @@---schema_version: 3-template_version: 3+template_version: 7kind: componentid: component:Typeahead-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-11-01owners: [cixzhang]-review_triggers: [theming]+review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by:[packages/core/src/Typeahead/Typeahead.test.tsx,+ packages/core/src/Typeahead/Typeahead.fr10.test.tsx,packages/core/src/Typeahead/TypeaheadItem.test.tsx,- packages/core/src/Field/Field.test.tsx,- packages/core/src/Token/Token.test.tsx,- packages/core/src/Icon/Icon.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]modules: []families: [family:input-fields, family:overlay-dismissal]design_specs: []architecture:- [architecture:component-theming-surface, architecture:layer-runtime]+ [+ architecture:component-theming-surface,+ architecture:layer-runtime,+ architecture:public-component-api,+ ]contributing: []-system_specs: []+system_specs: [spec:AST-085]---# Typeahead component contract+## Contract at a glance++| Area | Contract |+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | None changes. Typeahead takes BaseTypeahead's search props plus field props (`label`, `description`, `status`, `isRequired`, `size`), `hasClear`, `isDisabled` and `disabledMessage`, start content, and `container*` and `control*` styling. |+| Behavior | A Field-wrapped BaseTypeahead whose selected value shows as a Token; clicking the Token edits it; clear sets `null`; a disabled field stays focusable, with or without a reason. |+| End-user impact | People search and pick one value, see it as a token, and edit or clear it. |+| Builder impact | Builders style the field through `container*` and `control*` and theme four Typeahead targets. |+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Caller handlers while disabled are listed under Current-state impact. |+| Review checks | Reject a lost target, a Token beside the input instead of over it, an input left in the Tab order behind a Token, a caller key handler that cancels navigation, or a reason not linked from the input. |+| Governing rules | `family:input-fields`; `spec:AST-085` FR1, FR2; `component:BaseTypeahead`; `architecture:component-theming-surface`. |++This table is a review projection; the body below is authoritative.+## IntentTypeahead renders a single-selection search control with an optional standalone-Field shell and delegates its combobox engine and popup results to BaseTypeahead. This draft records current-consumer anatomy, target reachability, and the shipped difference between the-stable result row and its default TypeaheadItem content without changing runtime-behavior, styling, targets, or public API.+Field shell and delegates its combobox engine and popup results to BaseTypeahead.## Compatibility and migration- Released default preserved: `yes`-- Compatibility class: additive documentation only; runtime, DOM, styling,- targets, and public API remain unchanged-- Controlled/uncontrolled behavior: unchanged+- Compatibility class: records shipped behavior; no public prop, default,+ export, or DOM change+- Controlled/uncontrolled behavior: `value` is controlled- Migration decision: noneConsumer migration instructions belong in consumer docs and release notes.@@ -52,10 +66,10 @@ Consumer migration instructions belong in consumer docs and release notes.**Owns**-- The painted Input surface and its current `typeahead` target.-- The Dropdown and Empty state rendered by BaseTypeahead and their current+- The painted Input surface and its `typeahead` target.+- The Dropdown and Empty state rendered by BaseTypeahead and their`typeahead-dropdown` and `typeahead-empty-state` targets.-- Default item content rendered by TypeaheadItem and its current+- Default item content rendered by TypeaheadItem and its`typeahead-item` target.- The stable outer Result row, Result group heading, and Selected result state,which currently have no Typeahead target.@@ -73,25 +87,27 @@ Consumer migration instructions belong in consumer docs and release notes.- General Icon presentation for an Icon-rendered start icon.- Arbitrary ReactNode start or item content supplied by the caller.- A target/state for the outer Result row, Result group heading, or selected-row- concept; none exists on current `main`.+ concept; none exists (OQ1).- Shared layer lifecycle, positioning, and dismissal behavior.## Public concepts-No new public concept is introduced. Consumer props and usage remain documented-in `Typeahead.doc.mjs`; BaseTypeahead and TypeaheadItem retain their existing-public component documentation.+No component-local concept beyond the props documented in `Typeahead.doc.mjs`;+BaseTypeahead and TypeaheadItem keep their own records.## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |-| FR1 | The current standalone presentation contains a Field and painted Input surface; the supported InputGroup path renders the same Input surface without a Field. The surface contains an editable input when unselected or editing, and a Selected token plus collapsed input when selected and not editing. | Current source, docs, and tests | Verified current behavior; no normalization |-| FR2 | Input surface, Dropdown, Empty state, and Default item content carry the four current Typeahead targets documented in `Typeahead.doc.mjs`. | Current source, docs, and tests | Verified current behavior; no target change |-| FR3 | Every result, whether default or caller-rendered, sits inside the same stable outer Result row that owns option semantics, highlight, selected styling, pointer interaction, and keyboard indexing. | Current source and tests | Verified current behavior; no new behavior decided |-| FR4 | `typeahead-item` reaches only the standard TypeaheadItem label/supporting-content branch inside a Result row. A custom `renderItem` branch or caller-provided `item.element` does not receive that target, and no branch gives the outer Result row a Typeahead target. | Current source and owner tests | Verified current asymmetry; no normalization |-| FR5 | Result group heading and Selected result state are stable visible concepts but no current Typeahead target reaches them. The selected check uses a generic Icon, which does not expose a Typeahead-specific selected-row selector. | Current source | Verified factual reachability gaps |-| FR6 | When present, Field, Selected token, Clear button, Spinner, and Icon-rendered start icon retain their Field, Token, Spinner, and Icon theming owners; arbitrary ReactNode start and item content stays caller-owned. | Current composition and owners | Verified current behavior; no target change |+| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |+| FR1 | The current standalone presentation contains a Field and painted Input surface; the supported InputGroup path renders the same Input surface without a Field. The surface contains an editable input when unselected or editing, and a Selected token plus collapsed input when selected and not editing. | Current source, docs, and tests |+| FR2 | Input surface, Dropdown, Empty state, and Default item content carry the four Typeahead targets documented in `Typeahead.doc.mjs`. | Current source, docs, and tests |+| FR3 | Every result, whether default or caller-rendered, sits inside the same stable outer Result row that owns option semantics, highlight, selected styling, pointer interaction, and keyboard indexing. | Current source and tests |+| FR4 | `typeahead-item` reaches only the standard TypeaheadItem label/supporting-content branch inside a Result row. A custom `renderItem` branch or caller-provided `item.element` does not receive that target, and no branch gives the outer Result row a Typeahead target. | Current source and owner tests |+| FR5 | Result group heading and Selected result state are stable visible concepts but no Typeahead target reaches them (OQ1). The selected check uses a generic Icon, which exposes no Typeahead-specific selected-row selector. | Current source |+| FR6 | When present, Field, Selected token, Clear button, Spinner, and Icon-rendered start icon retain their Field, Token, Spinner, and Icon theming owners; arbitrary ReactNode start and item content stays caller-owned. | Current composition and owners |+| FR7 | A disabled Typeahead keeps the input's Tab stop with `aria-disabled` and `readOnly` (`spec:AST-085` FR1), opens and picks nothing, and drops search work in flight when it becomes disabled; with a `disabledMessage` it links the reason Tooltip through `aria-describedby`. Caller handlers other than focus and blur MUST NOT run while disabled (FR2). Implementation gap: a disabled input still runs caller click, pointer, and key handlers (`component:BaseTypeahead` FR9). | `spec:AST-085` FR1, FR2; current tests |+| FR8 | With a selected value and not editing, the Token paints over the collapsed input, which leaves the Tab order, and the Token's button, named by the field label and the value, is the Tab stop; clicking the Token enters edit mode, which searches the value's label and restores the input to the Tab order; blur without an action restores the Token; a composing Escape does not leave edit mode. With `hasClear`, the clear button calls `onChange(null)`, and clearing while editing empties the input. | Current tests |+| FR9 | The field has no root styling props: `control*` reaches the input surface and `container*` the Field box (`family:input-fields` FR10); DOM props and the ref reach the combobox input in both paths; a caller `onKeyDown` runs after built-in key handling, once per key, and also for keys on the clear button; a caller `aria-labelledby` follows the field's own name. The surface keeps one row with the end controls in flow at the inline end, and its height is the shared element size as a minimum. | `family:input-fields` FR10; current tests |### Allowed variation@@ -121,17 +137,31 @@ public component documentation.### Transformation and precedence order-- No new query, search-result, selection, edit-mode, or styling precedence rule is- introduced.+- **ORD1 — Display.** Editing or no value → the editable input; a value not+ being edited → the Token over the collapsed input.### Performance and resources-- No new performance or resource rule is introduced.+- **PR1 — Delegated resources.** Search timers and stale-response rejection are+ BaseTypeahead's (`component:BaseTypeahead` PR1); Typeahead adds no listener of+ its own.## Accessibility contract-This draft does not change or extend Typeahead's existing field, combobox,-listbox, option, live-region, focus, or dismissal behavior.+Combobox, listbox, option, live-region, and dismissal semantics are+`component:BaseTypeahead`'s.++- **AR1 — One field.** The input is named by the Field label (and a caller+ `aria-labelledby` after it) and described by the description and status; the+ combobox exposes the resolved required state as `aria-required` and an error+ status as `aria-invalid`, keeping a caller's own values when the field's state+ is off.+- **AR3 — Token button name.** While a value shows, the Token's button, the Tab+ stop, is named by the field label (or a caller `aria-labelledby`) and the+ value.+- **AR2 — Hidden input behind a Token.** While a Token shows, the collapsed+ input is out of the Tab order, so Tab reaches the Token's controls and moves+ on (FR8).## Design relationships@@ -214,6 +244,8 @@ normalize targets.## Family and system relationships+- `spec:AST-092` incremental search results reach Typeahead through+ BaseTypeahead; Typeahead adds no props for them.- `architecture:component-theming-surface` owns anatomy qualification, localtarget mapping, delegation, and factual `none` dispositions.- `architecture:layer-runtime` owns the current Popover host, positioning, native@@ -225,31 +257,32 @@ normalize targets.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | ------------------------- |-| FR1, FR6 | `Typeahead.test.tsx`, owner tests, and Typeahead composition source | Standalone/InputGroup, empty, editing, selected, clear, start icon | A documented composed part disappears, gains the wrong owner, or misreports Field presence. | `audit:Typeahead/anatomy` |-| FR2 | Source inspection, target inventories, empty-state test, and `TypeaheadItem.test.tsx` | Input, open Dropdown, empty search, default item | A current target is missed, invented, or documented on an element that does not carry it. | `audit:Typeahead/theming` |-| FR3, FR4, FR5 | BaseTypeahead source and result/group/selection tests | Default/custom result, grouped result, selected row | The record hides the outer/inner asymmetry or claims reachability that current code lacks. | `audit:Typeahead/theming` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:Typeahead/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1, FR6 | `Typeahead.test.tsx` Typeahead rendering cases ("renders with label", "renders description text", "shows required indicator", "renders error status message", "shows selected value as a token", "shows clear button when hasClear and value is selected") and value-lane cases | Standalone; selected; clear; status | A missing Field part, Token, or clear button fails. Evidence gap: no test asserts that the InputGroup path omits the Field, or the Spinner and Icon delegation. | `audit:Typeahead/anatomy` |+| FR2 | `Typeahead.test.tsx` "exposes the empty state as a themeable target"; `TypeaheadItem.test.tsx`; `themingTargets.test.ts` | Empty search; default item | A missing empty-state target fails; a rendered class absent from the documented targets fails. Evidence gap: no test asserts the `typeahead`, `typeahead-dropdown`, or `typeahead-item` placement. | `audit:Typeahead/theming` |+| FR3, FR4, FR5 | `TypeaheadItem.test.tsx` "renders item.element raw in place of the label layout" | Default and caller content | `item.element` that keeps the default layout fails. Evidence gap: no test asserts the untargeted outer row, group heading, or selected state. | `audit:Typeahead/theming` |+| FR7 | `Typeahead.test.tsx` disabledMessage cases, including "keeps its tab stop when disabled without a reason" and "drops a search answer that arrives after the field became disabled"; `Typeahead.disabled.a11y.chromium.spec.ts` "Tab reaches the disabled field, which rings and stays read-only" | Disabled with and without a reason | A reason not linked from the input, a disabled input without a Tab stop, typing or selecting while disabled, or a search answer that lands after disabling fails. Evidence gap: no test asserts that caller handlers are skipped while disabled. | `audit:Typeahead/accessibility` |+| FR8, ORD1, AR2, AR3 | `Typeahead.test.tsx` edit-mode and collapsed-input tab-order cases; "calls onChange with null when clear button is clicked"; "does not show clear button when hasClear is false"; "names the token button, the Tab stop while a value shows, by the field label and the value", "names the token button with a caller aria-labelledby as the input is named" | Token, edit, blur, clear; Tab order | A Token that does not enter edit mode, an input left in the Tab order behind a Token, a composing Escape that leaves edit mode, a clear that does not send `null`, or a token button not named by the label and value fails. | `audit:Typeahead/behavior` |+| FR9, AR1 | `Typeahead.fr10.test.tsx` props-type case; `Typeahead.test.tsx` "forwards DOM props and ref to the combobox input while preserving edit and blur behavior", "forwards DOM props and ref to the input inside InputGroup, with control* on the surface", consumer key-handler cases, caller aria-labelledby cases, and end-controls cases; "exposes the resolved required state on the combobox (FormLayout FR5, AR2)", "marks the combobox invalid for an error status only (WCAG 4.1.2)", "keeps a caller's own aria-invalid and aria-required when the field's own state is off" | Standalone and grouped; key handlers; caller name | A root styling prop, a dropped DOM prop or ref, a caller key handler that runs first or twice, a lost caller name, a missing `aria-required` or error `aria-invalid`, or end controls out of flow fails. Evidence gap: no test asserts the minimum height. | `audit:Typeahead/layout` |+| PR1 | Covered by `component:BaseTypeahead`'s rows; no test asserts the absence of Typeahead listeners (evidence gap) | — | — | `audit:Typeahead/behavior` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and targets | Missing, extra, prefixed, stale, or unclassified mappings fail repository validation. | `audit:Typeahead/theming` |++## Current-state impact-Existing tests directly assert Empty state and TypeaheadItem target presence,-selected-value Token behavior, result semantics, selection state, and standalone-Field content. Source inspection confirms InputGroup's Field omission and, with-public target inventories, provides the current Input surface and Dropdown target-evidence. No test is represented here as proof of a target it does not directly-assert.+- **Caller handlers while disabled (FR7).** A disabled Typeahead still runs+ caller click, pointer, and key handlers, against `spec:AST-085` FR2.## Decision log-None. This draft records current facts and introduces no component-local design,-API, theming, or layer-system decision.+No component-local decision.## Open questions- **OQ1 — Should the stable Result row, Result group heading, or Selected resultstate gain a public Typeahead target?** (`human-api`) Their current lack of- reachability is an audit gap, not settled intent. This draft does not normalize- the existing outer-row/default-content asymmetry.+ reachability is not settled intent, and the outer-row/default-content+ asymmetry is recorded, not normalized.## Content boundarydiff --git a/docs/specs/components/Typeahead/TypeaheadItem.spec.md b/docs/specs/components/Typeahead/TypeaheadItem.spec.mdnew file mode 100644index 0000000000..ce6593dc6d--- /dev/null+++ b/docs/specs/components/Typeahead/TypeaheadItem.spec.md@@ -0,0 +1,159 @@+---+schema_version: 3+template_version: 7+kind: component+id: component:TypeaheadItem+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-11-01+owners: [cixzhang]+review_triggers: [public-api, theming]+verified_by: [packages/core/src/Typeahead/TypeaheadItem.test.tsx]+modules: []+families: []+design_specs: []+architecture:+ [architecture:public-component-api, architecture:component-theming-surface]+contributing: []+system_specs: []+---++# TypeaheadItem component contract++## Contract at a glance++| Area | Contract |+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | The default Typeahead result content: `item` (required), `icon`, `description`, `isDisabled`, `group`, root inputs, and a ref. |+| Behavior | Renders an optional icon, the item's label, and an optional description under the `typeahead-item` target; dims when disabled; renders `item.element` raw instead when the item carries one. |+| End-user impact | People see each result's label, icon, and supporting text in one consistent row layout. |+| Builder impact | Builders reuse it inside a custom `renderItem` to keep the default layout and target. |+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Root inputs dropped on the `item.element` path are listed under Current-state impact. |+| Review checks | Reject a lost `typeahead-item` target, a description element when none is given, or option semantics added to this content. |+| Governing rules | `architecture:public-component-api` INV5, INV6; `architecture:component-theming-surface`; `component:BaseTypeahead` for the option row around it. |++This table is a review projection; the body below is authoritative.++## Intent++Give Typeahead results, and custom renderers that want the same look, one+label-and-supporting-content layout.++## Compatibility and migration++- Released default preserved: yes.+- Compatibility class: records shipped behavior; no public prop, default,+ export, or DOM change.+- Controlled/uncontrolled behavior: not applicable.+- Migration decision: none.++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The result content layout: icon, label, and description.+- The `typeahead-item` target and the disabled dimming.++**Does not own / non-goals**++- Option role, highlight, selection, and keyboard behavior — owned by+ `component:BaseTypeahead`'s result row.+- Caller-provided `item.element` content.+- Grouping. The `group` prop has no effect: TypeaheadItem ignores it, and+ BaseTypeahead groups results by `item.auxiliaryData.group`.++## Public concepts++| Concept | Closed values or states | Meaning | Availability | Default | Owner | Stability | Invalid-value behavior |+| -------------- | ------------------------------ | --------------------------------------------------- | -------------- | -------------- | --------- | --------- | ---------------------- |+| Content source | default layout; `item.element` | Whether the item's own element replaces the layout. | Every result | default layout | component | stable | `item.element` wins. |+| Availability | enabled; disabled | Whether the content is dimmed. | Default layout | enabled | component | stable | Not applicable. |++## Behavioral and layout contract++| ID | Invariant | Basis |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |+| FR1 | Without `item.element`, the content renders `icon` before a column of the item's `label` and, when given, `description`; no description element renders without one. | Current source and tests |+| FR2 | The root carries the `typeahead-item` target; `isDisabled` dims it to half opacity. | `architecture:component-theming-surface`; current source and tests |+| FR3 | Root inputs reach the root: `className` merges with the component's classes, `style` and `xstyle` compose, other props pass through, and the ref reaches the root element. | `architecture:public-component-api`; current tests |+| FR4 | With `item.element`, that element renders raw in place of the layout. Caller root inputs MUST still reach the rendered root (`architecture:public-component-api` INV5, INV6). Implementation gap: on this path the ref, `className`, `style`, `xstyle`, and other props are dropped. | `architecture:public-component-api` INV5, INV6; current source and tests |++### Allowed variation++- **AV1 — Content.** Icon, label, and description are caller data.+- **AV2 — Theme paint.** Themes may restyle the `typeahead-item` target.++### Representative states++| State | Required invariant | Allowed variation |+| ------------------------- | ----------------------------------- | ----------------- |+| Label only | Label, no description element. | Label text. |+| With icon and description | Icon, then label above description. | Content. |+| Disabled | Dimmed to half opacity. | — |+| `item.element` | The element renders raw. | Caller content. |++### Transformation and precedence order++- **ORD1 — Content.** `item.element` → default layout.++### Performance and resources++- **PR1 — Render only.** The content owns no state, effect, listener, or+ observer.++## Accessibility contract++- **AR1 — Content only.** TypeaheadItem adds no role or state; the option row+ around it owns them.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ---------------- | ---------------------------------- | ------------------------ | -------------- | ------------------ |+| Icon | Identifies the result at a glance. | Caller content | Supporting | FR1 |+| Label | Names the result. | Current source | Prominent | FR1 |+| Description | Adds secondary detail. | Current source | Supporting | FR1 |++`component:Typeahead` and `component:BaseTypeahead` map the `typeahead-item`+target as "Default item content" in their theming anatomy, so this record+carries no anatomy-theming map.++## Family and system relationships++- `component:BaseTypeahead` owns the option row and chooses this content by+ default.+- `architecture:public-component-api` owns root-input composition.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |+| FR1 | `TypeaheadItem.test.tsx` "renders the item label", "renders the description below the label when provided", "renders no description element when none is provided", "renders the icon before the label content" | Label, description, icon | A missing label, description, or icon, an extra description element, or the icon after the label fails. | `audit:TypeaheadItem/anatomy` |+| FR2 | `TypeaheadItem.test.tsx` "dims the row when isDisabled is set" and "does not dim the row by default" | Enabled and disabled | Missing or default dimming fails. Evidence gap: no test asserts the `typeahead-item` class. | `audit:TypeaheadItem/theming` |+| FR3 | `TypeaheadItem.test.tsx` "forwards pass-through props to the item element", "merges a caller className with its own classes", "forwards ref to the row element" | Pass-through, className, ref | A dropped prop, class, or ref fails. Evidence gap: no test asserts `style` or `xstyle`. | `audit:TypeaheadItem/api` |+| FR4, ORD1 | `TypeaheadItem.test.tsx` "renders item.element raw in place of the label layout" | `item.element` | An element that keeps the default layout fails. Evidence gap: no test asserts the root inputs on this path (the FR4 gap). | `audit:TypeaheadItem/api` |+| PR1, AR1 | Evidence gap: no test asserts the absence of lifecycle resources or roles | — | — | `audit:TypeaheadItem/behavior` |++## Current-state impact++- **Root inputs on `item.element` (FR4).** When an item carries its own element,+ the ref, `className`, `style`, `xstyle`, and other props passed to+ TypeaheadItem are dropped, against `architecture:public-component-api` INV5+ and INV6.++## Decision log++No component-local decision.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables/examples or the option-row+contract. It links to their owners.