Typeahead component contract¶
Contract at a glance¶
| Area | Contract |
|---|---|
| Public contract | Adds menu and handleRef, forwarded to BaseTypeahead (FR11). 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 five Typeahead targets. |
| Compatibility/readiness | Additive: without menu and handleRef, no 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.
Intent¶
Typeahead renders a single-selection search control with an optional standalone Field shell and delegates its combobox engine and popup results to BaseTypeahead.
Compatibility and migration¶
- Released default preserved:
yes - Compatibility class: additive. It adds the optional
menuandhandleRefprops (FR11); without them, no default or DOM changes - Controlled/uncontrolled behavior:
valueis controlled - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary¶
Owns
- The painted Input surface and its
typeaheadtarget. - The Dropdown and Empty state rendered by BaseTypeahead and their
typeahead-dropdownandtypeahead-empty-statetargets. - Default item content rendered by TypeaheadItem and its
typeahead-itemtarget. - The stable outer Result row and its
typeahead-optiontarget, which carries the row's size and itshighlightedandselectedstates (FR13). - The Result group heading, which has no Typeahead target.
Does not own / non-goals
- Standalone field-shell presentation — rendered by Field and themed through
Field's current
fieldtarget; omitted when Typeahead is inside InputGroup. - The Selected token — rendered by Token and themed through Token's current
tokentarget. - The Clear button — rendered by Field's InputClearButton and themed through
Field's current
input-clear-buttontarget. - Loading-indicator presentation — owned by
component:Spinner. Typeahead decides only where the indicator sits. - General Icon presentation for an Icon-rendered start icon.
- Arbitrary ReactNode start or item content supplied by the caller.
- A target for the Result group heading; none exists (OQ1).
- Shared layer lifecycle, positioning, and dismissal behavior.
Public concepts¶
No component-local concept beyond the props documented in Typeahead.doc.mjs;
BaseTypeahead and TypeaheadItem keep their own records. menu, handleRef
(open() and close()) and onOpenChange are BaseTypeahead's
(component:BaseTypeahead FR13–FR16), forwarded unchanged.
Behavioral and layout contract¶
| 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, Result row, and Default item content carry the five 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; the outer Result row carries typeahead-option in every branch (FR13). |
Current source and owner tests |
| FR5 | The Result group heading is a stable visible concept but no Typeahead target reaches it (OQ1). The selected row is reached through the typeahead-option target's selected state (FR13); the selected check inside it uses a generic Icon. |
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; a non-composing Escape in edit mode with the list hidden leaves edit mode: it restores the Token and moves focus to the Token's button, so focus never falls to the page body; Escape with the list shown hides the list first (spec:AST-075 FR4). 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 |
| FR10 | The result list follows component:BaseTypeahead FR12: a press on the field's input or its buttons, or in the list, keeps it open, and a press anywhere else closes it. |
component:BaseTypeahead FR12 |
| FR11 | menu and handleRef reach BaseTypeahead unchanged, so the menu's listbox and dialog roles, its open handle and its focus return follow component:BaseTypeahead FR13–FR16, and onOpenChange reports the same opens and closes. |
component:BaseTypeahead FR13–FR16 |
| FR12 | Backspace or Delete on the focused Token's button acts on the selected value. With hasClear, it clears the value as the clear button does: onChange(null), a polite announcement that names the cleared value through the shared live region, and focus on the empty input, as a Tokenizer token's removal does. Without hasClear, it enters edit mode, as a click on the Token does. A disabled field ignores both keys. |
Current tests |
| FR13 | Each result option row carries the typeahead-option target with size, highlighted and selected reflections. highlighted marks the active option, the one aria-activedescendant names, so a theme can style the option the keyboard or pointer is on, as it can an Item or CommandPaletteItem row; the default content inside the row keeps typeahead-item. |
architecture:public-component-api DEC-2; component:BaseTypeahead FR17 |
Allowed variation¶
- Standalone Typeahead renders Field; the supported InputGroup path omits it.
- The Input surface shows an editable input while empty or editing and a Token while a selected value is not being edited. This shipped asymmetry is recorded, not normalized into a new shared part or target.
- A Result row may contain standard TypeaheadItem content, custom
renderItemcontent, or a caller-provideditem.element. Only the standard TypeaheadItem label/supporting-content branch carriestypeahead-item. - Results may be ungrouped or grouped. Group wrappers and headings do not gain a target from that variation.
- Semantic names and icon component types render through Icon. Arbitrary ReactNode start content renders directly and stays caller-owned.
Representative states¶
| State | Required invariant | Allowed variation |
|---|---|---|
| Standalone or InputGroup | Field is present only standalone; Input surface anatomy and targets remain the same in both paths. | InputGroup owns grouped layout and labeling support. |
| Empty or editing | Editable input remains inside the typeahead Input surface. |
Query, loading state, and popup visibility may vary. |
| Selected and not editing | Token owns the selected-value presentation while the input is collapsed. | Clear button may be present according to hasClear and disabled state. |
| Results with default renderer | Outer Result row carries typeahead-option; inner TypeaheadItem carries typeahead-item. |
Item label, icon/avatar, and description may vary. |
| Results with custom renderer | Outer Result row carries typeahead-option; custom content receives no typeahead-item. |
Caller owns the inner result content. |
| Grouped and selected results | The selected row carries typeahead-option with its selected state; the group heading remains untargeted. |
A generic Icon paints the selected check. |
| Empty completed search | Empty state carries typeahead-empty-state inside the Dropdown. |
Consumer-supplied empty text may vary. |
Transformation and precedence order¶
- ORD1 — Display. Editing or no value → the editable input; a value not being edited → the Token over the collapsed input.
Performance and resources¶
- PR1 — Delegated resources. Search timers and stale-response rejection are
BaseTypeahead's (
component:BaseTypeaheadPR1); Typeahead adds no listener of its own.
Accessibility contract¶
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-labelledbyafter it) and described by the description and status; the combobox exposes the resolved required state asaria-requiredand an error status asaria-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¶
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Field | Provides the label and optional supporting content outside InputGroup; omitted inside InputGroup. | Field component | Supporting | FR1, FR6 |
| Input surface | Paints the control around the editable input or selected token. | Current source and public docs | Prominent | FR1, FR2 |
| Icon-rendered start icon | Presents a semantic or component icon through Icon. | Icon component | Supporting | FR6 |
| Caller-rendered start content | Presents arbitrary caller content directly in the input surface's start slot. | Caller-supplied content | Context-dependent | FR6 |
| Selected token | Presents the selected value outside edit mode through Token. | Token component | Prominent | FR1, FR6 |
| Spinner | Indicates a search in flight, at the end of the input surface. | Spinner component | Supporting | FR6 |
| Clear button | Removes the selected value through the shared field clear action. | Field component | Supporting | FR6 |
| Dropdown | Paints the anchored listbox surface containing results or Empty state. | Current source and public docs | Prominent | FR2 |
| Empty state | Presents the no-results message after a completed empty search. | Current source and public docs | Prominent | FR2 |
| Result row | Owns option semantics, interaction, highlight, selection styling, and keyboard index for every result. | Current source and tests | Prominent | FR3, FR4, FR13 |
| Default item content | Presents the standard TypeaheadItem label and optional supporting content inside a Result row. | TypeaheadItem component | Prominent | FR2, FR4 |
| Caller-rendered item content | Presents custom renderItem or item.element content inside the stable Result row. |
Caller-supplied content | Context-dependent | FR3, FR4, FR6 |
| Result group heading | Labels a visible group of Result rows. | Current source | Supporting | FR5 |
| Selected result state | Presents selected row weight and a trailing check; reached through the typeahead-option target's selected state. |
Current source | Supporting | FR5, FR13 |
typeahead-option is on the stable outer Result row, which owns interaction and
state for both default and custom content, and reflects its size and its
highlighted and selected states (FR13); typeahead-item is on the default
inner TypeaheadItem content only. Group headings are untargeted (OQ1).
Theming anatomy¶
{
"Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},
"Input surface": {"target": "typeahead"},
"Icon-rendered start icon": {
"delegatesTo": {"owner": "component:Icon", "target": "icon"}
},
"Caller-rendered start content": {
"none": {
"reason": "intentional: Arbitrary ReactNode content is caller-owned and receives no Typeahead target."
}
},
"Selected token": {
"delegatesTo": {"owner": "component:Token", "target": "token"}
},
"Spinner": {
"delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
},
"Clear button": {
"delegatesTo": {
"owner": "component:Field",
"target": "input-clear-button"
}
},
"Dropdown": {"target": "typeahead-dropdown"},
"Empty state": {"target": "typeahead-empty-state"},
"Result row": {"target": "typeahead-option"},
"Default item content": {"target": "typeahead-item"},
"Caller-rendered item content": {
"none": {
"reason": "intentional: Custom renderItem and item.element content is caller-owned and does not receive the standard TypeaheadItem target."
}
},
"Result group heading": {
"none": {
"reason": "reachability-gap: No current public target reaches the visible result-group heading."
}
},
"Selected result state": {"target": "typeahead-option"}
}
Family and system relationships¶
spec:AST-092incremental search results reach Typeahead through BaseTypeahead; Typeahead adds no props for them.architecture:component-theming-surfaceowns anatomy qualification, local target mapping, delegation, and factualnonedispositions.architecture:layer-runtimeowns the current Popover host, positioning, outside-press dismissal, and visibility reconciliation used by the Dropdown.family:overlay-dismissalowns shared Escape and platform-close ordering; Typeahead participates through its composed Popover owner.- Field, Token, and Icon retain ownership of their delegated targets and presentation.
Verification map¶
| 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 group heading. |
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; "hides the list on the first Escape, then restores the Token and focuses its button"; "does not exit edit mode on a composing Escape (IME)"; "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 |
| FR10 | component:BaseTypeahead FR12's verification |
— | — | — |
| FR11 | BaseTypeahead.menu.test.tsx "Typeahead forwards the menu and the handle"; component:BaseTypeahead FR13–FR16's verification |
A dialog-role menu opened from the handle | A menu or handle that does not reach BaseTypeahead fails. | — |
| FR12 | Typeahead.test.tsx "Backspace and Delete on the token" cases |
With and without hasClear; disabled |
A key that does not clear with hasClear, a clear without the announcement or without focus on the empty input, or a clear without hasClear fails. |
audit:Typeahead/behavior |
| FR13 | BaseTypeahead.test.tsx "marks only the active option highlighted on its typeahead-option row" |
Arrow navigation over several results | A row without the target, or a second highlighted row, fails. | audit:Typeahead/theming |
| 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¶
- Caller handlers while disabled (FR7). A disabled Typeahead still runs
caller click, pointer, and key handlers, against
spec:AST-085FR2.
Decision log¶
No component-local decision.
Open questions¶
- OQ1 — Should the Result group heading gain a public Typeahead target?
(
human-api) Its current lack of reachability is not settled intent.
Content boundary¶
This file does not duplicate consumer prop tables, examples, search algorithms, implementation steps, or shared layer and theming rules. It links to their owners.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx