BaseTypeahead component contract¶
Contract at a glance¶
| Area | Contract |
|---|---|
| Public contract | Adds the optional menu (listbox or dialog role) and handleRef (open(), close()) of DEC-1. 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). The menu may instead put information around the list, or show a named dialog that takes focus and returns it on close (FR13–FR16). |
| End-user impact | People find and pick a result by typing; screen-reader users hear result counts. 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 | Additive: without menu and handleRef, no default or DOM change. The empty-search option, 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.
Intent¶
BaseTypeahead is the exported combobox engine beneath Typeahead and Tokenizer. It renders a bare input, search and bootstrap behavior, keyboard navigation, a styled result listbox, loading feedback, and selection callbacks. A direct caller supplies the visible input wrapper, accessible name, and selected-value presentation.
Compatibility and migration¶
- Released default preserved:
yes - Compatibility class: additive. It adds the optional
menuandhandleRefprops and their exported types (DEC-1); without them, no default or DOM changes - Controlled/uncontrolled behavior:
valueis controlled; query text is internal - Migration decision: none; public-surface cleanup is OQ1 and OQ2
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary¶
Owns
- Query text, search/bootstrap scheduling, stale-response rejection, result ordering, highlight, and selection callbacks.
- Combobox, listbox, option, busy, selected, and empty-result semantics.
- The anchored result popup and current dropdown/empty-state visual treatment.
- The menu's layer in both roles: position, top layer, outside press, Escape, focus return, and the ARIA that ties it to the input (FR13–FR16).
- Direct-caller loading feedback when a composed wrapper does not take over the busy indicator lane.
Does not own / non-goals
- The visible input wrapper, label presentation, field border, or focus ring.
- Selected-value or token presentation in Typeahead and Tokenizer.
- Caller-rendered result content, and the caller's menu content around the list or inside the dialog.
- Spinner presentation, owned by
component:Spinner. - Shared top-layer hosting, positioning, and dismissal behavior, owned by
architecture:layer-runtimeandfamily:overlay-dismissal.
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 |
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 |
| menu | listbox (optional render) or dialog (label, render) |
What the anchored menu shows: the result list, the list with information around it, or content that takes focus | popup present | listbox, list only |
caller and component | stable | TypeScript refuses a dialog without label or render |
| open handle | open(), close(); onOpenChange reports |
Opens and closes the menu imperatively; there is no controlled open state | enabled input | closed | component:BaseTypeahead |
stable | open() on a disabled field does nothing |
| size | sm, md, lg |
Selects option-row padding | popup options | md |
component:BaseTypeahead |
stable | TypeScript rejects other values |
Behavioral and layout contract¶
| 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; a pick whose onChange calls the handle's open() keeps the popup open instead (FR16). |
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. A focus bootstrap or reload that yields no eligible choice, or fails, closes the list; a completed empty search for a typed query still shows FR4's message. | Current source and tests |
| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Work still pending when the popup is dismissed settles without reopening it or leaving the field busy; a search answer for the unchanged query is kept for the next open, and an open while that search still runs waits for 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. A query's answer that arrives after the popup was dismissed, while it stays closed, is kept, not shown. The next open by ArrowDown, by focus returning to the field, by a pointer press, or by the handle's open() shows the kept list, announces its count once (spec:AST-092 FR8), and is busy only while that query's work is still pending. An empty answer reopens the popup this way only when it was kept through a dismissal. An open by any of these paths after a dismissal left the field's text unsearched (a cleared debounce or an aborted request) starts that search (FR12). |
Current source and tests; spec:AST-092 FR4 |
| FR4 | In the listbox role (FR13), 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, and the dismissal holds while source work is pending (FR3); IME-owned key events do not activate combobox commands. | 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. After the popup is dismissed while source work is pending, the control is not busy; the next open shows that work's latest list (FR3). |
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 or, if the popup was dismissed while it was pending, at the next open (FR3), keeps the last non-empty list when the answer fails, and warns in development when a later list moves shown rows. After the popup is dismissed while the query is pending, a partial list leaves the popup closed and the control not busy; the next open shows the query's latest list (FR3). |
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 |
| FR12 | While the list is open, a press that starts and ends on the field's input or its buttons, or in the list, keeps the list open; a press that starts and ends anywhere else closes it, and a scroll or pinch that starts outside does not. A press on the field's label or a Tokenizer token moves focus out of the input and back, so the list closes and reopens on that press and ends open. A field inside an open shadow root counts the same. The list is a manual popover, because the browser's light dismiss counts a press in a text input as outside (architecture:layer-runtime). |
architecture:layer-runtime; current source and tests |
| FR13 | menu chooses what the anchored popup shows, and BaseTypeahead owns its layer: position, top layer, outside press (FR12), Escape, focus return, and the ARIA that ties it to the input (DEC-1). {role: 'listbox'}, the default, shows the result list; its optional render receives the list, the query, the busy state, whether the search found nothing, and close, and places information such as a header, a footer, or a hint around the list. The list stays the only listbox and keeps FR1–FR12. Content outside the list is information only: anything a person acts on is a result in the list, so the arrow keys reach it, and a control rendered outside the list draws one development warning. |
DEC-1 |
| FR14 | {role: 'dialog', label, render} shows the caller's content in a dialog named by label (AR6); render receives the query and close. Focus moves to its first control, or to the dialog, when it shows. The input moves no highlight and picks nothing while it shows; Escape closes it. Only the handle opens it: a search, a focus load, a focus or ArrowDown on the input does not. It does not close when the query empties, a load finds nothing, or the input loses focus; a press outside the field and the dialog closes it (FR12). |
DEC-1 |
| FR15 | When a dialog-role menu closes (Escape, an outside press, close), focus returns to the element that had focus when the menu was asked to open (open() called, or the menu shown), or to the input when that element is gone. A press outside that moves focus to another control leaves it there. A focus return to the input does not open the list. |
DEC-1 |
| FR16 | handleRef exposes open() and close(), and onOpenChange reports each open and close; there is no controlled open state (DEC-1). open() runs after the commit it is called in, so it uses the menu the caller rendered in the same event: a dialog opens at once, and a listbox shows its results, loading them first if needed. A pick whose onChange calls open() keeps the menu open, so switching from the list to a dialog keeps the same layer on the same anchor without closing it. When the menu stays a listbox after such a pick, focus returns to the input and the list loads its focus entries, or closes when there are none. |
DEC-1 |
| FR17 | 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; result content inside the row keeps its own target (typeahead-item). |
architecture:public-component-api DEC-2; architecture:component-theming-surface; current tests |
Allowed variation¶
- Search and bootstrap may complete synchronously or asynchronously.
- Results may be grouped or ungrouped and may use default or caller-rendered content.
- A direct caller may anchor the popup to the input or to its own wrapper.
- The menu may be the result list alone, the list with information around it, or a dialog that takes focus (FR13–FR16).
- Typeahead and Tokenizer may own the visible wrapper and busy-indicator lane.
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, and closes when a bootstrap or reload yields none or fails | 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 | the popup stays closed and not busy; a late answer for the same query opens only on the next open | 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→ callerrenderItem→ TypeaheadItem. Implementation gap: a callerrenderItemreplacesitem.element, which only the default TypeaheadItem renders. - ORD2 — Input props. Consumer rest props → defined legacy aliases (
inputId,ariaDescribedBy,ariaLabelledBy,inputTabIndex) → component-owned semantics and handlers → component styles → consumer class/style escape hatches. An omitted legacy alias preserves its equivalent native BaseProp. - ORD3 — Menu content. A listbox-role
renderwraps the result list, whose rows still follow ORD1; withoutrenderthe menu is the list alone. A dialog-rolerenderreplaces the list while it shows.
Performance and resources¶
- 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¶
- AR1 — Combobox pattern. In the listbox role, DOM focus stays on the
input while
aria-activedescendantidentifies the highlighted option in the named listbox. A dialog-role menu takes focus instead (AR6). - AR2 — Accessible name. A direct caller supplies
aria-labelor a validaria-labelledbyrelationship; composed owners supply their visible label ID. - AR3 — State. Expanded, busy, disabled, active-descendant, and selected states are exposed programmatically.
- AR4 — Result feedback. Each query announces the localized result count
or empty-result message once, when it settles or, if the popup was dismissed
while it was pending, at the next open (FR3), through the shared announcer
(
spec:AST-092FR8). - AR5 — Input method. IME composition commands remain with the candidate window; ordinary keyboard and pointer selection remain equivalent.
- AR6 — Dialog menu. A dialog-role menu is a
dialognamed by itslabel; the input carriesaria-haspopup="dialog",aria-expanded, andaria-controlsnaming the layer that holds the dialog, and no active descendant. Focus moves into the dialog when it shows and returns as FR15 says.
Design relationships¶
| 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¶
{
"Input": {
"none": {
"reason": "intentional: The direct caller owns the bare input chrome and styles it through supported input styling props."
}
},
"Loading status": {
"delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
},
"Dropdown": {
"delegatesTo": {
"owner": "component:Typeahead",
"target": "typeahead-dropdown"
}
},
"Empty state": {
"delegatesTo": {
"owner": "component:Typeahead",
"target": "typeahead-empty-state"
}
},
"Result group heading": {
"none": {
"reason": "reachability-gap: No current public target reaches the visible group heading."
}
},
"Result row": {
"delegatesTo": {
"owner": "component:Typeahead",
"target": "typeahead-option"
}
},
"Menu content": {
"none": {
"reason": "intentional: The caller renders it around the list or inside the dialog and styles it; menu styling overrides are not decided (DEC-1)."
}
},
"Menu dialog": {
"none": {
"reason": "intentional: The dialog role's surface is the popover's own; menu styling overrides are not decided (DEC-1)."
}
},
"Default item content": {
"delegatesTo": {
"owner": "component:Typeahead",
"target": "typeahead-item"
}
},
"Caller-rendered item content": {
"none": {
"reason": "intentional: Caller-rendered result content remains caller-owned."
}
},
"Selected result state": {
"delegatesTo": {
"owner": "component:Typeahead",
"target": "typeahead-option"
}
}
}
Family and system relationships¶
family:overlay-dismissalowns Escape and platform-close ordering while the popup is present.architecture:layer-runtimeowns top-layer hosting, anchoring, viewport positioning, and outside-press dismissal for a text field's layer (FR12).spec:AST-092owns incremental search results (FR10).spec:AST-058owns the empty-search message and option actions (FR4, FR11).architecture:public-component-apiowns reachable exports and BaseProps passthrough semantics.architecture:component-theming-surfaceowns anatomy qualification and target disposition.
Verification map¶
| 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; BaseTypeahead.test.tsx "focus list with no choices" cases and "closes an open focus list when the reload fails" |
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)"; BaseTypeahead.test.tsx "BaseTypeahead pending work after a dismissal" cases; Tokenizer.test.tsx "keeps a dismissed menu closed when its search answers late, and shows that answer on reopen" |
Newer query; replaced source; dismissal while pending | A stale response or partial list that replaces newer results, a list after unmount, an old list on ArrowDown after a source replacement, or a popup that reopens or stays busy after a dismissal fails. Evidence gap: no test asserts timer cleanup. | audit:BaseTypeahead/behavior |
| FR3 | BaseTypeahead.test.tsx "every open path after a dismissal shows the kept list at once" cases; BaseTypeahead.test.tsx "searches the typed text when a press on the field's label dismissed it inside the debounce"; Tokenizer.test.tsx "searches the typed text when a press on a token dismissed it inside the debounce" |
ArrowDown, focus return, pointer press, and open() after a dismissal, with the search pending or settled; an empty settled answer not kept through a dismissal |
An open path that waits for the answer, searches again, stays busy after the query settled, announces the kept count twice or not at all, or reopens an empty answer that was not kept fails. | 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 |
| FR12 | Typeahead.test.tsx press inside and outside suite; Tokenizer.test.tsx press-inside case; TypeaheadInputPress.a11y.chromium.spec.ts |
Press in the input, in the list, elsewhere; a scroll that starts elsewhere; a field in a shadow root | A press on the field or in the list that closes the list, a press elsewhere that leaves it open, or a scroll that closes it fails. | — |
| FR13, FR16, ORD3 | BaseTypeahead.menu.test.tsx "shows information around the result list, and the list stays the only listbox", "warns in development when a control sits outside the result list", "keeps the menu open when a pick switches it to a dialog", "reloads the focus entries, with focus back in the input", "closes with focus in the input when there are no focus entries"; BaseTypeaheadMenu.a11y.chromium.spec.ts keyboard and role-switch cases in Chromium |
Header and footer around the list; a control outside it; a pick that switches to a dialog | A second listbox, information inside the list, an unreached result, a missing warning, or a layer that hides between the list and the dialog fails. | audit:BaseTypeahead/behavior |
| FR14, FR15, AR6 | BaseTypeahead.menu.test.tsx dialog-role cases, including "closes on a press outside the field and the dialog, and keeps a press inside" and "opens only from the handle: typing, focus and ArrowDown leave it closed"; BaseTypeaheadMenu.a11y.chromium.spec.ts focus-return and outside-press cases in Chromium |
Open from a button; Escape; close with the opener gone; an emptied query; a blur of the input | An unnamed dialog, a missing aria-haspopup, an active descendant, focus that stays outside, focus that lands on the page, a dialog that closes on an empty query or a blur, stays open after a press outside, or opens from typing or focus fails. |
audit:BaseTypeahead/accessibility |
| FR17 | BaseTypeahead.test.tsx "marks only the active option highlighted on its typeahead-option row" |
Arrow navigation over several results; a selected result | A row without the target, a second highlighted row, or a highlight on a row the active descendant does not name fails. | audit:BaseTypeahead/theming |
| 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¶
- Active option perception. The active option shows only the
--color-overlay-hoverfill, under 3:1 against the listbox in light and dark, againstspec:AST-020FR1 (WCAG 2.2 1.4.11). Selector draws the shared focus ring after keyboard input (component:SelectorAR5). - Empty-search message (FR4). A completed empty search renders its message
as a disabled option instead of presentational text, against
spec:AST-058FR7. - Result content order (ORD1). A caller
renderItemreplacesitem.element, which only the default TypeaheadItem renders, although theSearchableItem.elementdocs giveitem.elementpriority. - 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, againstspec:AST-085FR1 and FR2.
Decision log¶
DEC-1 — Astryx owns the typeahead menu's layer, and callers fill it¶
Decider: cixzhang, 2026-11-07 (row 49: "49 A")
The layer holds what screen-reader and keyboard users rely on: the menu's
role and name, where focus goes back to, what a press outside does, the order
in which Escape closes layers, and whether the menu stays above a Dialog. So
BaseTypeahead owns the layer, and a caller fills it through one menu config
that carries the role, the name and the content together (FR13–FR16). The
name matches the public menuWidth ("Okay menu"); the shape is one config
with the label inside ("I like the config idea"); focus return is one generic
rule ("Generic rule sounds good"); and the open state is reported, not
controlled, as in ComplexSelector ("Okay for open").
Rejected: callers composing the layer from spread props (Downshift style),
because one missed spread removes the role, the name or the focus return with
no visible sign. Rejected for now: typed layer options (width, placement,
maximum height) in the config, which no caller needs today and can be added
later without a break. Not included: a controlled isOpen, and an
onTokenActivate callback.
Note (not decided). Menu styling overrides may be added later (for example part styling or theme targets); they are out of scope now (Cindy: "49A we may add menu styling overrides").
DEC-2 — No controlRef on TextInput¶
Decider: cixzhang, 2026-11-06
TextInput does not expose a ref to its bordered control box for anchoring a
Popover: that route handles none of the necessary accessibility for that
experience (combobox role, active option, keyboard model, result
announcements). A custom typeahead uses BaseTypeahead with anchorRef and
the menu config.
Rejected: a controlRef on TextInput.
Open questions¶
- OQ1 — How should the released public props type remove package-internal
composition knobs such as
__queryEntries,isFocusableDisabled, andinputTabIndex? (human-api) - OQ2 — Should
inputXStylebe deprecated now that the inheritedxstylecontract correctly reaches the same input? (human-api) - OQ3 — Does bare BaseTypeahead own a default focus-visible ring, or must every
direct caller provide the ring on its wrapper? (
human-design)
Content boundary¶
This file does not duplicate the prop reference, examples, current audit score, shared layer mechanics, or shared accessibility and theming rules. It links to their owners.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx