An open source design system that's fully customizable and agent ready
TypeScript
docs(core): record MultiSelector and Typeahead anatomy (#5756)
Cindy Zhang00477a533bf5
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjsindex 7717523467..5673b91a92 100644--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs@@ -1,5 +1,116 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Field',+ required: false,+ description:+ 'Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.',+ },+ {+ name: 'Trigger',+ required: true,+ description:+ 'Painted control that displays the current selection or placeholder and opens the selection surface.',+ },+ {+ name: 'Icon-rendered start icon',+ required: false,+ description:+ 'Optional leading semantic icon or icon component rendered through Icon.',+ },+ {+ name: 'Caller-rendered start content',+ required: false,+ description:+ 'Optional arbitrary React content rendered directly at the start of the trigger.',+ },+ {+ name: 'Trigger clear button',+ required: false,+ description:+ 'Shared clear action that removes every selected value when hasClear is enabled.',+ },+ {+ name: 'Status icon',+ required: false,+ description:+ 'Status glyph shown in place of the disclosure indicator for attached or tooltip status.',+ },+ {+ name: 'Indicator icon',+ required: false,+ description:+ 'Trailing chevron shown when status presentation does not replace it; reflects collapsed or expanded state.',+ },+ {+ name: 'Search row',+ required: false,+ description:+ 'Panel header with a borderless search input and optional clear action.',+ },+ {+ name: 'Search icon',+ required: false,+ description:+ 'Leading magnifier rendered through Icon inside the search row.',+ },+ {+ name: 'Search clear button',+ required: false,+ description:+ 'Shared clear action shown in the search row while a query is present.',+ },+ {+ name: 'Option row',+ required: false,+ description:+ 'Selectable row for an option or the optional select-all choice.',+ },+ {+ name: 'Option checkbox indicator',+ required: false,+ description:+ 'CheckboxInput indicator that presents each row’s selected, unselected, or indeterminate state.',+ },+ {+ name: 'Option divider',+ required: false,+ description:+ 'Divider supplied in the public options data to separate adjacent option groups.',+ },+ {+ name: 'Section heading',+ required: false,+ description: 'Visible heading for a labeled group of option rows.',+ },+ {+ name: 'Empty state',+ required: false,+ description:+ 'Message shown when the shared panel content has no options or no search matches.',+ },+ {+ name: 'Pointer popup',+ required: false,+ description:+ 'Anchored painted surface that hosts the shared panel content for popover presentation.',+ },+ {+ name: 'Touch sheet heading',+ required: false,+ description:+ 'Heading above the shared panel content in bottom-sheet presentation.',+ },+ {+ name: 'Touch sheet',+ required: false,+ description:+ 'BottomSheet surface that hosts the same panel content for bottom-sheet presentation.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {@@ -264,6 +375,7 @@ export const docs = {},],usage: {+ anatomy,description:'A checkbox dropdown for selecting multiple values from a list. Selected items can display as a count, labels, or badges. Use it for filtering or when presenting a finite set of options where multiple choices are needed.',bestPractices: [diff --git a/packages/core/src/MultiSelector/MultiSelector.spec.md b/packages/core/src/MultiSelector/MultiSelector.spec.mdnew file mode 100644index 0000000000..f754c05533--- /dev/null+++ b/packages/core/src/MultiSelector/MultiSelector.spec.md@@ -0,0 +1,266 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:MultiSelector+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [theming]+verified_by:+ [+ packages/core/src/MultiSelector/MultiSelector.test.tsx,+ packages/core/src/BottomSheet/BottomSheet.test.tsx,+ packages/core/src/CheckboxInput/CheckboxInput.test.tsx,+ packages/core/src/Divider/Divider.test.tsx,+ packages/core/src/Field/Field.test.tsx,+ packages/core/src/Icon/Icon.test.tsx,+ packages/core/src/Text/Text.test.tsx,+ scripts/check-knowledge.mjs,+ ]+families: [family:overlay-dismissal]+design_specs: []+architecture:+ [architecture:component-theming-surface, architecture:layer-runtime]+contributing: []+system_specs: []+---++# MultiSelector component contract++## Intent++MultiSelector renders a multi-selection control with an optional standalone Field+shell and one shared panel content tree in either an anchored pointer popup or a+touch-oriented BottomSheet.+This draft records current consumer anatomy and theming ownership without changing+runtime behavior, styling, targets, or public API.++## 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+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The painted Trigger and its current `multi-selector` target.+- Indicator icon, Search row, Option row, Section heading, Empty state, and+ Pointer popup presentation through the other six current MultiSelector targets.+- One shared panel-content tree containing optional search, option, divider,+ section, and empty-state content regardless of which presentation hosts it.++**Does not own / non-goals**++- Standalone field-shell presentation — rendered by Field and themed through+ Field's current `field` target; omitted when MultiSelector is inside InputGroup.+- Shared clear actions — rendered by Field's InputClearButton and themed through+ Field's current `input-clear-button` target.+- Option checkbox presentation — rendered by CheckboxInput and themed through+ CheckboxInput's current `checkbox-indicator` target.+- Public option dividers — rendered by Divider and themed through Divider's+ current `divider` target.+- General Icon presentation for start, search, and status icons — rendered by+ Icon and themed through Icon's current `icon` target.+- The Touch sheet heading — rendered by Heading and themed through Text's current+ `heading` target.+- The Touch sheet panel — rendered by BottomSheet and themed through+ BottomSheet's current `bottom-sheet` target.+- Arbitrary ReactNode start content supplied by the caller.+- Shared layer lifecycle, positioning, and dismissal behavior.++## Public concepts++No new public concept is introduced. Consumer props and usage remain documented+in `MultiSelector.doc.mjs`.++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |+| FR1 | The current standalone presentation contains a Field and painted Trigger; the supported InputGroup path renders the same Trigger without a Field. Optional start content, clear action, status icon, or Indicator icon follows supplied props and state. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR2 | The shared panel content contains the optional Search row, zero or more Option rows, optional public Option dividers and Section headings, and an Empty state when the applicable result set is empty and the value is not loading. | Current source, docs, and tests | Verified current behavior; no new behavior decided |+| FR3 | Trigger, Indicator icon, Search row, Option row, Section heading, Empty state, and Pointer popup carry the seven current non-deprecated MultiSelector targets documented in `MultiSelector.doc.mjs`. | Current source, docs, and tests | Verified current behavior; no target change |+| FR4 | When present, Field, shared clear actions, option checkbox indicators, public Option dividers, general icons, Touch sheet heading, and Touch sheet retain their Field, CheckboxInput, Divider, Icon, Text, and BottomSheet theming owners. | Current composition and owners | Verified current behavior; no target change |+| FR5 | Pointer popup and Touch sheet are separate surface anatomy rows, but both host the same `panelContent` tree; the Touch sheet additionally renders its Heading. Changing presentation does not create a second search, option, divider, section, or empty-state content model. | Current source and tests | Verified current behavior; no normalization |+| FR6 | `multi-selector-clear-icon` remains a deprecated compatibility alias for `input-clear-icon`; it is not a current target and does not claim a separate anatomy part. | Current public target metadata | Verified current compatibility state |++### Allowed variation++- Standalone MultiSelector renders Field; the supported InputGroup path omits it.+- `presentation="popover"` uses the Pointer popup; `presentation="bottom-sheet"`+ uses the Touch sheet and its Heading; `presentation="adaptive"` selects between+ those existing branches from current modality and viewport behavior.+- Search row, Option divider, Section heading, Empty state, select-all Option row,+ and both clear actions are optional under their documented prop and data conditions.+- Semantic names and icon component types render through Icon. Arbitrary ReactNode+ start content renders directly and stays caller-owned.+- Trigger text, labels, badges, and custom option content may vary inside the+ Trigger or Option row without creating another MultiSelector target.++### Representative states++| State | Required invariant | Allowed variation |+| -------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |+| Standalone or InputGroup | Field is present only standalone; Trigger anatomy and targets remain the same in both paths. | InputGroup owns grouped layout and labeling support. |+| Pointer presentation | Pointer popup carries `multi-selector-popup` and hosts the shared panel content. | Search, groups, options, and empty content follow their ordinary states. |+| Touch presentation | BottomSheet owns the Sheet panel, Text owns its Heading, and the sheet hosts the same shared panel content. | Adaptive or explicit selection may choose this branch. |+| Search enabled with a query | Search row owns `multi-selector-search`; its icons/actions keep their shared owners. | Results may be flat, grouped, or empty. |+| Option, select all, selected, disabled | Option row owns `multi-selector-option` and reflects its current size/state metadata. | Checkbox state and custom row content vary independently. |+| Attached or tooltip status | Status icon replaces the Indicator icon. | Tooltip status wraps the icon in a button without changing Icon owner. |++### Transformation and precedence order++- No new search, selection, presentation, or styling precedence rule is introduced.++### Performance and resources++- No new performance or resource rule is introduced.++## Accessibility contract++This draft does not change or extend MultiSelector's existing field, combobox,+listbox, checkbox, live-region, focus, or dismissal behavior.++## 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, FR4 |+| Trigger | Presents the current selection or placeholder and opens the active presentation. | Current source and public docs | Prominent | FR1, FR3 |+| Icon-rendered start icon | Presents a semantic or component icon through Icon. | Icon component | Supporting | FR1, FR4 |+| Caller-rendered start content | Presents arbitrary caller content directly in the trigger's start slot. | Caller-supplied content | Context-dependent | FR1 |+| Trigger clear button | Removes every selected value through the shared field clear action. | Field component | Supporting | FR1, FR4 |+| Status icon | Presents attached or tooltip validation state through Icon. | Icon component | Supporting | FR1, FR4 |+| Indicator icon | Presents disclosure state when status presentation does not replace it. | Current source and public docs | Supporting | FR1, FR3 |+| Search row | Provides query entry at the top of the shared panel content. | Current source and public docs | Supporting | FR2, FR3, FR5 |+| Search icon | Presents the search affordance through Icon. | Icon component | Supporting | FR2, FR4 |+| Search clear button | Clears a present query through the shared field clear action. | Field component | Supporting | FR2, FR4 |+| Option row | Presents one option or the select-all choice and owns row interaction/state. | Current source and public docs | Prominent | FR2, FR3 |+| Option checkbox indicator | Presents the option's selected, unselected, or indeterminate state through CheckboxInput. | CheckboxInput component | Supporting | FR2, FR4 |+| Option divider | Separates adjacent groups when a public divider entry is present in the options data. | Divider component | Supporting | FR2, FR4 |+| Section heading | Labels a visible group of option rows. | Current source and public docs | Supporting | FR2, FR3 |+| Empty state | Presents no-options or no-results content when the panel has no selectable rows to show. | Current source and public docs | Prominent | FR2, FR3 |+| Pointer popup | Paints the anchored pointer surface around the shared panel content. | Current source and public docs | Prominent | FR3, FR5 |+| Touch sheet heading | Names the bottom-sheet presentation above the shared panel content. | Text component | Prominent | FR4, FR5 |+| Touch sheet | Paints the BottomSheet surface around the same shared panel content. | BottomSheet component | Prominent | FR4, FR5 |++The seven current MultiSelector targets remain on their shipped visible elements.+Nested shared primitives keep their own owners. The Pointer popup and Touch sheet+are intentionally separate rows because they use different surface owners; the+Touch sheet adds a Heading owned by Text. Search, option, divider, section, and+empty-state content remains one shared tree.++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "Field": {"delegatesTo": {"owner": "component:Field", "target": "field"}},+ "Trigger": {"target": "multi-selector"},+ "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 MultiSelector target."+ }+ },+ "Trigger clear button": {+ "delegatesTo": {+ "owner": "component:Field",+ "target": "input-clear-button"+ }+ },+ "Status icon": {+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}+ },+ "Indicator icon": {"target": "multi-selector-indicator-icon"},+ "Search row": {"target": "multi-selector-search"},+ "Search icon": {+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}+ },+ "Search clear button": {+ "delegatesTo": {+ "owner": "component:Field",+ "target": "input-clear-button"+ }+ },+ "Option row": {"target": "multi-selector-option"},+ "Option checkbox indicator": {+ "delegatesTo": {+ "owner": "component:CheckboxInput",+ "target": "checkbox-indicator"+ }+ },+ "Option divider": {+ "delegatesTo": {"owner": "component:Divider", "target": "divider"}+ },+ "Section heading": {"target": "multi-selector-section-heading"},+ "Empty state": {"target": "multi-selector-empty-state"},+ "Pointer popup": {"target": "multi-selector-popup"},+ "Touch sheet heading": {+ "delegatesTo": {"owner": "component:Text", "target": "heading"}+ },+ "Touch sheet": {+ "delegatesTo": {+ "owner": "component:BottomSheet",+ "target": "bottom-sheet"+ }+ }+}+```++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, local+ target mapping, delegation, and exclusion of deprecated aliases.+- `architecture:layer-runtime` owns the current Popover host and the distinction+ between browser popover and native-dialog sheet presentation.+- `family:overlay-dismissal` owns shared Escape and platform-close ordering. The+ Pointer popup participates through its composed Popover owner; the Touch sheet+ inherits BottomSheet's current local-only adoption gap.+- Field, CheckboxInput, Divider, Icon, Text, and BottomSheet retain ownership of+ their delegated targets and presentation.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |+| FR1, FR2 | `MultiSelector.test.tsx` render, search, divider, grouping, status, select-all, and empty-state suites plus InputGroup source inspection | Standalone/InputGroup, search, divided, selected, empty, status | Removing a documented part or misreporting Field presence conflicts with existing structure, content assertions, or source. | `audit:MultiSelector/anatomy` |+| FR3, FR6 | Component target suites, source inspection, and public target inventory | All seven current targets and deprecated alias | A current target is missed, invented, moved, or confused with the deprecated clear-icon alias. | `audit:MultiSelector/theming` |+| FR4 | Composed owner source/tests for Field, CheckboxInput, Divider, Icon, Text, and BottomSheet | Field omission/presence, clear actions, checkbox, divider, icons, heading, sheet | A shared part gains the wrong local owner or its documented owner no longer renders it. | `audit:MultiSelector/theming` |+| FR5 | `MultiSelector.test.tsx` presentation suites and `panelContent` source inspection | Explicit popover, explicit sheet, adaptive touch | A presentation stops using its owner or receives a divergent panel-content implementation. | `audit:MultiSelector/overlay` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local targets | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | `audit:MultiSelector/theming` |++Existing component tests directly assert the Trigger, Indicator icon, Search row,+Option row, Section heading, Empty state, and Pointer popup targets. Presentation+tests directly distinguish the Popover and BottomSheet branches. Source inspection+distinguishes standalone Field presence from InputGroup omission and confirms that both surface branches receive the same `panelContent`, while the touch branch+adds Heading; Divider, Text, BottomSheet, and other shared primitive tests provide+owner evidence rather than new MultiSelector targets.++## Decision log++None. This draft records current facts and introduces no component-local design,+API, theming, or layer-system decision.++## Open questions++None.++## Content boundary++This file does not duplicate consumer prop tables, examples, search or selection+algorithms, implementation steps, or shared layer and theming rules. It links to+their owners.diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjsindex e09cd31ae5..100a40ba94 100644--- a/packages/core/src/Typeahead/Typeahead.doc.mjs+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs@@ -1,5 +1,85 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */+const anatomy = [+ {+ name: 'Field',+ required: false,+ description:+ 'Standalone Field shell that provides the label and optional supporting content; omitted inside InputGroup.',+ },+ {+ name: 'Input surface',+ required: true,+ description:+ 'Painted control surface containing the editable input or the selected token.',+ },+ {+ name: 'Icon-rendered start icon',+ required: false,+ description:+ 'Optional leading semantic icon or icon component rendered through Icon.',+ },+ {+ name: 'Caller-rendered start content',+ required: false,+ description:+ 'Optional arbitrary React content rendered directly at the start of the input surface.',+ },+ {+ name: 'Selected token',+ required: false,+ description:+ 'Token that presents the selected item while the control is not in edit mode.',+ },+ {+ name: 'Clear button',+ required: false,+ description:+ 'Shared clear action that removes the selected item when hasClear is enabled.',+ },+ {+ name: 'Dropdown',+ required: false,+ description:+ 'Anchored listbox surface containing the current search results.',+ },+ {+ name: 'Empty state',+ required: false,+ description: 'Message shown after a completed search returns no results.',+ },+ {+ name: 'Result row',+ required: false,+ description:+ 'Stable option wrapper that owns highlight, selection, pointer, and keyboard behavior.',+ },+ {+ name: 'Default item content',+ required: false,+ description:+ 'Standard TypeaheadItem label and supporting content rendered inside a result row when renderItem and item.element are absent.',+ },+ {+ name: 'Caller-rendered item content',+ required: false,+ description:+ 'Caller-owned result content supplied through renderItem or item.element inside the stable result row.',+ },+ {+ name: 'Result group heading',+ required: false,+ description: 'Visible heading for a labeled group of result rows.',+ },+ {+ name: 'Selected result state',+ required: false,+ description:+ 'Selected styling and trailing check presented on the current result row.',+ },+];+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */export const docs = {@@ -86,7 +166,8 @@ export const docs = {{name: 'minQueryLength',type: 'number',- description: 'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',+ description:+ 'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',default: '1',},{@@ -199,6 +280,7 @@ export const docs = {],},usage: {+ anatomy,description:'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',bestPractices: [diff --git a/packages/core/src/Typeahead/Typeahead.spec.md b/packages/core/src/Typeahead/Typeahead.spec.mdnew file mode 100644index 0000000000..4bd39e4444--- /dev/null+++ b/packages/core/src/Typeahead/Typeahead.spec.md@@ -0,0 +1,250 @@+---+schema_version: 1+template_version: 3+kind: component+id: component:Typeahead+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [theming]+verified_by:+ [+ packages/core/src/Typeahead/Typeahead.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,+ scripts/check-knowledge.mjs,+ ]+families: [family:overlay-dismissal]+design_specs: []+architecture:+ [architecture:component-theming-surface, architecture:layer-runtime]+contributing: []+system_specs: []+---++# Typeahead component contract++## Intent++Typeahead 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.++## 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+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- The painted Input surface and its current `typeahead` target.+- The Dropdown and Empty state rendered by BaseTypeahead and their current+ `typeahead-dropdown` and `typeahead-empty-state` targets.+- Default item content rendered by TypeaheadItem and its current+ `typeahead-item` target.+- The stable outer Result row, Result group heading, and Selected result state,+ which currently have no Typeahead target.++**Does not own / non-goals**++- Standalone field-shell presentation — rendered by Field and themed through+ Field's current `field` target; omitted when Typeahead is inside InputGroup.+- The Selected token — rendered by Token and themed through Token's current+ `token` target.+- The Clear button — rendered by Field's InputClearButton and themed through+ Field's current `input-clear-button` target.+- 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`.+- 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.++## 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, and Icon-rendered start icon retain their Field, Token, and Icon theming owners; arbitrary ReactNode start and item content stays caller-owned. | Current composition and owners | Verified current behavior; no target change |++### 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 `renderItem`+ content, or a caller-provided `item.element`. Only the standard TypeaheadItem+ label/supporting-content branch carries `typeahead-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 remains untargeted; inner TypeaheadItem carries `typeahead-item`. | Item label, icon/avatar, and description may vary. |+| Results with custom renderer | Outer Result row remains untargeted; custom content receives no `typeahead-item`. | Caller owns the inner result content. |+| Grouped and selected results | Group heading and selected-row concept remain untargeted by Typeahead. | 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++- No new query, search-result, selection, edit-mode, or styling precedence rule is+ introduced.++### Performance and resources++- No new performance or resource rule is introduced.++## Accessibility contract++This draft does not change or extend Typeahead's existing field, combobox,+listbox, option, live-region, focus, or dismissal behavior.++## 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 |+| 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 |+| 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 without a Typeahead-specific target or target state. | Current source | Supporting | FR5 |++The current target placement is asymmetric: `typeahead-item` is on default inner+TypeaheadItem content, while the stable outer Result row owns interaction and state+for both default and custom content. Group headings and the selected-result concept+are also untargeted. This record preserves those facts and does not move, add, or+normalize targets.++### Theming anatomy++<!-- anatomy-theming:v1 -->++```json+{+ "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"}+ },+ "Clear button": {+ "delegatesTo": {+ "owner": "component:Field",+ "target": "input-clear-button"+ }+ },+ "Dropdown": {"target": "typeahead-dropdown"},+ "Empty state": {"target": "typeahead-empty-state"},+ "Result row": {+ "none": {+ "reason": "reachability-gap: The stable outer option row owns interaction and state but has no current Typeahead target."+ }+ },+ "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": {+ "none": {+ "reason": "reachability-gap: No current Typeahead target or target state reaches the outer selected row and its selection concept."+ }+ }+}+```++## Family and system relationships++- `architecture:component-theming-surface` owns anatomy qualification, local+ target mapping, delegation, and factual `none` dispositions.+- `architecture:layer-runtime` owns the current Popover host, positioning, native+ light-dismiss, and visibility reconciliation used by the Dropdown.+- `family:overlay-dismissal` owns 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`, 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` |++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.++## Decision log++None. This draft records current facts and introduces no component-local design,+API, theming, or layer-system decision.++## Open questions++- **OQ1 — Should the stable Result row, Result group heading, or Selected result+ state 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.++## 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.