@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Typeahead/BaseTypeahead.spec.md

@@ -1,270 +0,0 @@
----
-schema_version: 3
-template_version: 4
-kind: component
-id: component:BaseTypeahead
-authority: draft
-archive_reason: null
-superseded_by: null
-approved_by: null
-approved_at: null
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/Typeahead/BaseTypeahead.test.tsx,
-    packages/core/src/Typeahead/Typeahead.test.tsx,
-    packages/core/src/Tokenizer/Tokenizer.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:overlay-dismissal]
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:layer-runtime,
-  ]
-contributing: []
-system_specs: []
----
-
-# BaseTypeahead component contract
-
-## 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.
-
-This draft records verified shipped or audit-remediated behavior. It does not
-approve a new prop, default, compatibility promise, visual treatment, or
-ownership boundary.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: patch corrections preserve the existing public surface
-- Controlled/uncontrolled behavior: controlled `value` remains unchanged
-- Migration decision: none; unresolved public-surface cleanup requires a
-  separate compatibility decision
-
-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.
-- 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.
-- Spinner presentation, owned by `component:Spinner`.
-- Shared top-layer hosting, positioning, and dismissal behavior, owned by
-  `architecture:layer-runtime` and `family: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`    | released  | caller retains control                                                          |
-| search source   | `search`, `bootstrap`, optional `cancel` | Supplies query and focus results                             | enabled input              | required                         | `component:BaseTypeahead`    | released  | rejected work clears current results                                            |
-| focus bootstrap | on or off                                | Offers bootstrap results before query input                  | empty focused input        | off                              | `component:BaseTypeahead`    | released  | off keeps the menu closed                                                       |
-| query threshold | non-negative number                      | Minimum visible-character count before search                | non-empty query            | `1`                              | `component:BaseTypeahead`    | released  | below threshold cancels work and closes results                                 |
-| debounce        | milliseconds                             | Delays query search                                          | typed query                | `150`                            | `component:BaseTypeahead`    | released  | non-positive runs immediately                                                   |
-| result cap      | number                                   | Limits fetched results shown                                 | completed search/bootstrap | `10`                             | `component:BaseTypeahead`    | released  | source order is preserved                                                       |
-| result content  | default, `renderItem`, or `item.element` | Chooses content inside the stable option row                 | result present             | default TypeaheadItem            | caller and component         | released  | `item.element` takes precedence                                                 |
-| disabled state  | native or focusable-disabled             | Blocks query mutation; native disabled blocks all activation | disabled                   | native disabled                  | component and caller wrapper | released  | a list open before focusable-disabled applied picks nothing and can still close |
-| popup width     | intrinsic or fixed pixels                | Sets result popup width before viewport clamping             | popup present              | intrinsic, at least anchor width | `component:BaseTypeahead`    | released  | viewport fit wins                                                               |
-| size            | `sm`, `md`, `lg`                         | Selects option-row padding                                   | popup options              | `md`                             | `component:BaseTypeahead`    | released  | TypeScript rejects other values                                                 |
-
-## Behavioral and layout contract
-
-Draft requirements identify their observational or current-authority basis.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                        | Basis                                                 | Draft review state                             |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------- |
-| FR1 | The input is controlled by internal query state while `value` is caller-controlled; selecting a result calls `onChange(item)`, clears query/results, closes the popup, and returns focus to the input.                                                                                                     | Current source and tests                              | verified shipped behavior                      |
-| FR2 | Search starts only at the grapheme-count threshold, uses the configured debounce, and never presents an empty result for a query that was not searched.                                                                                                                                                    | Public API, current i18n character utility, tests     | verified audit remediation                     |
-| FR3 | A newer query, selection, clear, source replacement, or unmount invalidates stale asynchronous work. Escape hides the current popup but does not invalidate pending work, so a late response currently reopens it (retained violation).                                                                    | Current source, focused retained-red probe, and tests | verified shipped behavior                      |
-| FR4 | The popup is a named listbox whose result rows are options. A completed empty search renders one disabled option so the listbox retains a valid owned child.                                                                                                                                               | APG combobox pattern, axe, tests                      | verified audit remediation                     |
-| FR5 | Arrow keys wrap the highlight; Home/End move to the first/last option; Enter selects; Escape and Tab hide the current popup; IME-owned key events do not activate combobox commands. Escape dismissal is not durable while source work remains pending (FR3).                                              | Current source and tests                              | verified shipped behavior; Escape gap retained |
-| FR6 | Pending asynchronous source work sets `aria-busy` and renders one named Spinner unless the composed wrapper owns the busy indicator lane.                                                                                                                                                                  | Current source, input-family FR7, tests               | verified shipped behavior                      |
-| FR7 | Supported BaseProps DOM, ARIA, data, class, style, event, and `xstyle` inputs reach the combobox input while component-owned role, state, value, and behavior remain authoritative.                                                                                                                        | `architecture:public-component-api/INV5–INV7`, tests  | verified audit remediation                     |
-| FR8 | The popup remains within the inline viewport at 320 CSS px, including long default results and a requested width larger than the available viewport.                                                                                                                                                       | WCAG 1.4.10, real Chromium                            | verified audit remediation                     |
-| FR9 | Native disabled removes ordinary focus and activation. Focusable-disabled uses `aria-disabled` plus `readOnly` and blocks text/query mutation, opening the list, and selection by Enter or a press, including from a list that was open before it applied; that list can still close (`spec:AST-085` FR2). | Current source and tests                              | verified shipped behavior                      |
-
-### 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.
-- 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                                                                                  | synchronous or asynchronous source     |
-| query pending     | combobox is busy and duplicate stale work is rejected                                                                            | direct or wrapper-owned Spinner        |
-| results           | one highlighted option and valid active descendant                                                                               | grouped/default/custom content         |
-| completed empty   | one disabled empty option; no active descendant                                                                                  | caller-supplied empty text             |
-| selected result   | matching option exposes `aria-selected=true`                                                                                     | generic check presentation             |
-| disabled          | native disabled blocks activation; focusable-disabled blocks query mutation, opening and picking, also from an already-open list | native or focusable-disabled semantics |
-| dismissed pending | Escape hides the popup; a late pending response currently reopens it                                                             | source completion timing               |
-| narrow viewport   | popup and result content remain inside two viewport gutters                                                                      | intrinsic or requested width           |
-
-### Transformation and precedence order
-
-- **ORD1 — Result content.** `item.element` → caller `renderItem` →
-  TypeaheadItem.
-- **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.
-
-### Performance and resources
-
-- **PR1 — Search lifetime.** One generation counter rejects stale responses,
-  including responses from a source that has since been replaced; debounce
-  timers and optional source cancellation are cleared on replacement and
-  unmount.
-
-## Accessibility contract
-
-- **AR1 — Combobox pattern.** DOM focus stays on the input while
-  `aria-activedescendant` identifies the highlighted option in the named listbox.
-- **AR2 — Accessible name.** A direct caller supplies `aria-label` or a valid
-  `aria-labelledby` relationship; composed owners supply their visible label ID.
-- **AR3 — State.** Expanded, busy, disabled, active-descendant, and selected
-  states are exposed programmatically.
-- **AR4 — Result feedback.** Active queries announce the localized result count
-  or empty-result message through the shared announcer.
-- **AR5 — Input method.** IME composition commands remain with the candidate
-  window; ordinary keyboard and pointer selection remain equivalent.
-
-## Design relationships
-
-| Anatomy or state     | Design requirement                              | Representation authority         | Hierarchy role    | Component contract |
-| -------------------- | ----------------------------------------------- | -------------------------------- | ----------------- | ------------------ |
-| Input                | caller-owned visible chrome and focus treatment | unsettled ownership for bare use | prominent         | AR2                |
-| Loading status       | shared Spinner                                  | `component:Spinner`              | supporting        | FR6                |
-| Dropdown             | Popover surface with bounded listbox            | current source and layer runtime | prominent         | FR4, FR8           |
-| Highlighted result   | overlay plus forced-color outline               | objective accessibility standard | prominent         | FR5                |
-| Empty state          | disabled option message                         | APG/axe                          | supporting        | FR4                |
-| Default item content | TypeaheadItem                                   | `component:Typeahead`            | prominent         | ORD1               |
-| Caller item content  | caller-owned                                    | caller                           | context-dependent | ORD1               |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "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": {
-    "none": {
-      "reason": "reachability-gap: The stable option row owns highlight and selection but has no current target."
-    }
-  },
-  "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": {
-    "none": {
-      "reason": "reachability-gap: No current Typeahead target or state reaches the outer selected option."
-    }
-  }
-}
-```
-
-## Family and system relationships
-
-- `family:overlay-dismissal` owns Escape and platform-close ordering while the
-  popup is present.
-- `architecture:layer-runtime` owns top-layer hosting, anchoring, viewport
-  positioning, and native light dismissal.
-- `architecture:public-component-api` owns reachable exports and BaseProps
-  passthrough semantics.
-- `architecture:component-theming-surface` owns anatomy qualification and target
-  disposition.
-
-## Verification map
-
-| Contract        | Verification                                           | Representative states                                     | Mutation or failure expectation                                        | Audit section                    |
-| --------------- | ------------------------------------------------------ | --------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------- |
-| FR1–FR2         | BaseTypeahead and Typeahead tests                      | query, overlap, select, clear                             | current work replaces newer results or selection does not close        | `audit:BaseTypeahead/behavior`   |
-| FR3             | shared stale-response tests plus retained-red probe    | newer query, clear, unmount, Escape while pending         | late work replaces current results or reopens after explicit dismissal | `audit:BaseTypeahead/a11y`       |
-| FR4, AR1–AR4    | focused tests, component-scoped axe, live-region tests | results, empty, busy, selected                            | invalid listbox ownership or state/announcement disappears             | `audit:BaseTypeahead/a11y`       |
-| FR5, AR5        | keyboard, focus-out, IME, and retained-red tests       | arrows, Home/End, Enter, Escape, Tab, composition         | command selects or dismisses at the wrong time                         | `audit:BaseTypeahead/a11y`       |
-| FR6             | busy-lane tests                                        | direct and composed pending source                        | duplicate/missing Spinner or stale busy state                          | `audit:BaseTypeahead/a11y`       |
-| FR7             | focused passthrough tests and strict lint              | native-only, alias collisions, DOM/style/events           | supported consumer input is dropped or owned semantics are replaced    | `audit:BaseTypeahead/api`        |
-| FR8             | real-Chromium 320px sensor receipt                     | long result, wide request, LTR/RTL                        | popup or its content crosses either viewport gutter                    | `audit:BaseTypeahead/responsive` |
-| FR9             | shared disabled tests                                  | native disabled; focusable-disabled before and after open | disabled mode mutates query, opens the list, or accepts a selection    | `audit:BaseTypeahead/a11y`       |
-| Theming anatomy | knowledge and theming-target checks                    | all mapped parts                                          | target inventory or disposition drifts                                 | `audit:BaseTypeahead/theming`    |
-
-## Decision log
-
-None. This draft records current or objectively remediated behavior and makes no
-component-local API, design, compatibility, or ownership decision.
-
-## Open questions
-
-- **OQ1 — How should the released public props type remove package-internal
-  composition knobs such as `__queryEntries`, `isFocusableDisabled`, and
-  `inputTabIndex`?** (`human-api`)
-- **OQ2 — Should `inputXStyle` be deprecated now that the inherited `xstyle`
-  contract 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.

package/src/Typeahead/Typeahead.spec.md

@@ -1,257 +0,0 @@
----
-schema_version: 3
-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,
-  ]
-modules: []
-families: [family:input-fields, 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.
-- 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/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, Spinner, and Icon-rendered start icon retain their Field, Token, Spinner, and Icon theming owners; arbitrary ReactNode start and item content stays caller-owned.                                                                                      | Current composition and owners  | Verified current behavior; no target change        |
-
-### 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           |
-| 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           |
-| 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"}
-  },
-  "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": {
-    "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.