An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-056): one shape for search props across components (#6903)
Cindy Zhangc7e5277a6795
diff --git a/docs/specs/AST-056-search-prop-shape/spec.md b/docs/specs/AST-056-search-prop-shape/spec.mdnew file mode 100644index 0000000000..3bc977dda9--- /dev/null+++ b/docs/specs/AST-056-search-prop-shape/spec.md@@ -0,0 +1,577 @@+---+schema_version: 4+template_version: 1+kind: system-spec+id: spec:AST-056+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+phase: proposed+owners: [cixzhang]+affects_architecture: [architecture:public-component-api]+affects_families: [family:input-fields]+affects_contributing: [contributing:api-conventions]+affects_consumer_docs:+ [Selector, MultiSelector, Tokenizer, Typeahead, BaseTypeahead, CommandPalette]+review_triggers: [public-api, accessibility, compatibility]+---++# Search state vocabulary system spec++<!-- review-applicability:v1 -->++```json+{+ "scope": "global",+ "triggers": {+ "public-api": [+ "FR1",+ "FR2",+ "FR3",+ "FR4",+ "FR5",+ "FR6",+ "FR7",+ "DEC-1",+ "DEC-2",+ "DEC-3",+ "DEC-4"+ ],+ "accessibility": ["AR1", "AR2"],+ "compatibility": ["FR7"]+ }+}+```++## Contract at a glance++| Area | Contract |+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | One vocabulary, not one structure. "The query matched nothing" is `emptySearchText` taking `ReactNode`, on every component that has the state; "there is nothing here at all" stays `emptyText` and the two never merge (FR1, FR2, DEC-1). A capability that needs a query names that in its own prop name, and its handler is its only switch (FR5, DEC-3). No configuration object (DEC-2). |+| Behavior | Unchanged. Who resolves a query is settled by who owns the choices and is not restated per component: a component holding its own choice set filters them and exposes a boolean to show the input; a component whose presented choices ARE the query's result takes a required `searchSource` (FR4, DEC-2). |+| End-user impact | A person meets the same dead end everywhere, and can be offered the same way out of it: widening `emptySearchResultsText` to `ReactNode` lets a product put a link or a create row in a `Tokenizer`'s empty result as it already can in a `Selector`'s. A half-configured create row stops silently rendering nothing (FR5). Whatever a caller supplies is also what gets announced (FR3, AR1). |+| Builder impact | One rename to learn: `emptySearchResultsText` becomes `emptySearchText`. No prop moves, no object literal, no restructuring. Every shipped prop keeps working through the cycle. |+| Compatibility/readiness | Not additive, but small: one prop renamed on three components, with its type widened from `string` to `ReactNode`. No required prop moves. The replacement-first cycle and its cost are in `Migration and compatibility`; FR7 is the only requirement that constrains it. Authority: `draft`. Three owner questions remain open; none of them changes FR1 or FR2. |+| Review checks | Reject a second name for a state these props already express; a boolean that gates a handler; a capability that renders inert when a sibling prop is missing; an empty-state value that cannot reach assistive technology (AR1); a query input named only by its placeholder (AR2). |+| Governing rules | [`spec:AST-002`](../AST-002/spec.md) FR1, FR4, FR15, FR16 and `spec:AST-002/DEC-1`, `DEC-6` for admission and one responsibility per input; [`architecture:public-component-api`](../../architecture/public-component-api.md) INV1, INV2, INV3, INV9 for the shared naming grammar and released-API lifecycle; [`spec:AST-017`](../AST-017/spec.md) FR28–FR31 for deprecation and cleanup; [`family:input-fields`](../../families/input-fields.md) for the field chrome around the query input, unchanged here. |++This table is a review projection; the body below is authoritative.++## Intent++Typing to narrow a list is one thing a person does, and Astryx spells it seven+ways. A builder who has used `hasSearch` on `Selector` finds no `hasSearch` on+`Tokenizer`; a builder who has set `emptySearchResultsText` on `Typeahead`+finds `emptySearchText` on `CommandPalette`, taking a different type. Nothing+is broken for the person using the product, but every new search-adjacent+capability lands as another flat prop on one component, with its own name, and+the next component copies whichever neighbour it happened to read.++This record owns one answer: **a shared vocabulary for the states a typed+query produces, with no restructuring.** It fixes the name and type of "the+query matched nothing", keeps that state distinct from "there is nothing here+at all", and says how a capability that cannot work without a query declares+that dependency.++An earlier draft proposed collecting these props into one object-valued+`search` prop. That is rejected in DEC-2: it would have cost nine+deprecations across seven components, four of them a required prop, to solve+a tidiness problem rather than one a person using an Astryx product meets.++The trigger is [#6829](https://github.com/facebook/astryx/pull/6829), which+proposes `hasCreate` + `onCreate` on `MultiSelector` — a sixth and seventh+search-adjacent prop on a component that already carries three, under a name+`Tokenizer` already ships with a different contract. That pull request is+blocked on this ruling, and the shape it adopts is the shape every later+component copies.++## Ownership boundary++**Owns**++- The name and type of each observable state a typed query produces, shared+ across every component that has that state.+- That "the query matched nothing" and "there is nothing here at all" are+ distinct states under distinct names, and neither absorbs the other.+- How a capability that cannot function without a query declares that+ dependency, and what gates it.+- Whether a newly proposed search-related prop joins this vocabulary or+ introduces a second name for something it already says.+- The accessibility floor the arrangement must keep for the empty-result+ message and the query input's name.++**Why no existing record can hold it**++- [`spec:AST-002`](../AST-002/spec.md) is `current` and approved, and a record+ carries one `authority` value, so adding unapproved claims to it would+ present them as approved (`architecture:knowledge-contracts` INV1, INV14).+ It also owns a different fact — whether a public API is admitted at all —+ and both its FR17 and its DEC-7 say in their own words that **component prop+ and event naming remains separate**. A rule about the shape and name of a+ component prop is structurally outside what AST-002 claims. This record sits+ downstream of AST-002 FR1 and FR4: admission still decides whether a search+ capability exists, and this record decides only where it is spelled.+- [`architecture:public-component-api`](../../architecture/public-component-api.md)+ is `current` and approved, with the same authority problem. It holds the+ shared naming grammar (INV2) and links its human rulings through+ `deciding_specs` — `spec:AST-002/DEC-1`, `spec:AST-005/DEC-1`,+ `spec:AST-012/DEC-1`. A new cross-component ruling belongs in a spec it+ links, not inside it; its own INV18 boundary keeps observable caller-visible+ behavior in a product contract.+- [`family:input-fields`](../../families/input-fields.md) is `current` and owns+ the field chrome — label, status, size, theming — shared by its members. Two+ of the components this record binds, `BaseTypeahead` and `CommandPalette`,+ are not members and are not input fields; `CommandPalette` is a dialog. They+ are not one sibling family, which is why the vocabulary is owned here rather+ than by that contract.+- `contributing:api-conventions` and the wiki's `Prop Naming` section document+ conventions for booleans, callbacks, enums, direction, and HTML collisions.+ They say nothing about one state keeping one name across components, and+ guidance is not an authority record. Both owe an amendment once this record+ is `current`.+- The six component records would each hold a private copy of the same+ decision, which `architecture:knowledge-contracts` INV2 forbids.+ `component:MultiSelector` is already drafting one as its FR10 / DEC-3.++## Non-goals++- **Matching quality.** Fuzzy matching, ranking, highlighting, tokenization,+ and diacritic folding are not settled here. FR4 fixes only the floor for the+ mode where the component does the filtering.+- **Whether any particular component should gain search, or a create row.**+ That is `spec:AST-002` admission, case by case.+- **`PowerSearch`.** Its query is a structured field/operator/value expression,+ not a typed string narrowing a list. Its `maxSearchResults` and its per-field+ `searchSource` are cited as evidence of spread, not governed (OQ4).+- **`emptyBootstrapText` on `CommandPalette`.** "No query yet, and the default+ set is empty" is a different observable state from "the query matched+ nothing"; it stays a top-level prop.+- **The trigger-menu configuration on `ChatComposerInput`.** Its per-trigger+ objects each carry an `emptySearchResultsText`, so FR1 reaches them, but+ whether that nested rename rides this record's cycle is OQ4.+- **Internal filtering implementation.** Equivalent internal implementations+ remain valid when they satisfy this contract. Internal modules, files,+ function names, algorithms, data structures, storage layouts, manifests,+ journals, locks, transaction protocols, and CI job/workflow topology belong in+ architecture or implementation unless callers or interoperating systems+ intentionally depend on that exact mechanism as a public protocol.++## Evidence: every search-shaped prop in core today++Read from `packages/core/src` at this record's base commit. This table is the+evidence for FR1–FR5; it is not a migration plan.++| Component | Query input exists because | Who resolves the query | Placeholder | "Nothing matched" | Query observable by the caller | Create affordance | Other search-shaped props |+| ------------------- | ------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |+| `Selector` | `hasSearch?: boolean` — default `false` | the component, over its own `options` | `searchPlaceholder?: string` — `'Search…'` | `emptySearchText?: ReactNode` — `'No results found'` | **no** — `searchQuery` is internal `useState` | — | `emptyText?: ReactNode` (`'No options'`, a different state) |+| `MultiSelector` | `hasSearch?: boolean` — default `false` | the component, over its own `options` | `searchPlaceholder?: string` — `'Search…'` | `emptySearchText?: ReactNode` — `'No results found'` | **no** — `searchQuery` is internal `useState` | `hasCreate` + `onCreate` **proposed** in #6829 | `emptyText?: ReactNode` (`'No options'`) |+| `Tokenizer` | `searchSource: SearchSource<T>` — **required** | the caller's source | `placeholder?: string` — the input is the control | `emptySearchResultsText?: string` — `'No results found'` | `onChangeQuery?: (query: string) => void` | `hasCreate?: boolean` — **the component mints the token** | `minQueryLength?: number` (`1`), `debounceMs?: number` (`150`) |+| `Typeahead` | `searchSource: SearchSource<T>` — **required** | the caller's source | `placeholder?: string` | `emptySearchResultsText?: string` | `onChangeQuery?: (query: string) => void` | — | `minQueryLength?: number`, `debounceMs?: number` |+| `BaseTypeahead` | `searchSource: SearchSource<T>` — **required** | the caller's source | `placeholder?: string` | `emptySearchResultsText?: string` | `onChangeQuery?: (query: string) => void` | `__queryEntries` — underscored, `@internal` | `minQueryLength?: number`, `debounceMs?: number` |+| `CommandPalette` | `searchSource: SearchSource<T>` — **required** | the caller's source | `CommandPaletteInput.placeholder` — `'Search…'` | `emptySearchText?: ReactNode` — `'No results'` | through the `input` slot's `value` / `onValueChange` | — | `emptyBootstrapText?: ReactNode` (`'Type to search'`) |+| `ChatComposerInput` | one `searchSource` per entry in `triggers[]` | the caller's source, per trigger | — (the composer's own `placeholder`) | `triggers[].emptySearchResultsText?: string` | — | — | `triggers[].loadingText`, `triggers[].menuLabel`, `debounceMs` |+| `PowerSearch` | a structured filter expression, not a typed query | the caller's per-field `searchSource?` (value pickers) | internal (`@astryx.powersearch.placeholder`) | — | — | — | `maxSearchResults?: number` |++Four drift axes are visible in that table, and each one is a separate decision+somebody made alone:++1. **Two names for "nothing matched":** `emptySearchText` on `Selector`,+ `MultiSelector`, and `CommandPalette`; `emptySearchResultsText` on+ `Typeahead`, `BaseTypeahead`, `Tokenizer`, and each `ChatComposerTrigger`.+2. **Two types for the same message:** `ReactNode` on the first group, `string`+ on the second. A builder who can pass an element to one component cannot to+ its neighbour.+3. **Three defaults for it:** `'No results found'`, `'No results'`, and —+ because `Selector` and `MultiSelector` also carry a top-level `emptyText` —+ `'No options'` for the adjacent state.+4. **The prefix only appears where search is optional.** `Selector` and+ `MultiSelector` write `searchPlaceholder` because they also have a trigger+ placeholder; `Typeahead` and `Tokenizer` write `placeholder` because the+ query input _is_ the control. Both are locally right, which is exactly why+ no component will fix this on its own.++Beyond core, `packages/lab` has already copied the drift and added a fifth+name: `MobileTokenizer` takes `searchSource` + `emptySearchResultsText`,+`TransferList` takes `hasSearch` + `searchPlaceholder` + `searchLabel`, and+`ChatEmojiPicker` takes `searchLabel`. Lab is not a stable public promise, so+this record does not govern it; it is evidence that the pattern spreads by+copying.++### Two prior claims about prior art, corrected++- **`searchConfig` is not a component prop and is not prior art for this+ shape.** It is a parameter and plugin-config field in+ `Table/plugins/filtering/useTableFiltering.tsx`, holding a+ `PowerSearchConfig` — the structured field/operator/value configuration of+ the filter builder. It configures a different concept.+- **The repository's real precedent for this shape is `ChatComposerTrigger`.**+ Each entry in `ChatComposerInput`'s `triggers[]` is an object carrying+ `searchSource`, `renderItem`, `onSelect`, `emptySearchResultsText`,+ `loadingText`, and `menuLabel` — the whole configuration of one trigger's+ query in one value, with keys that mostly drop the prefix the surrounding+ name already supplies. It works, it is shipped, and nobody has asked for it+ to be flattened.++## Public API and concepts++| Concept | Closed values or states | Meaning | Default | Owner | Stability |+| ----------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------- | -------------- | --------- |+| `emptySearchText` | `ReactNode` | What the component shows when the query matched nothing. One name and one type everywhere (FR1) | per component | `spec:AST-056` | proposed |+| showing the input | a boolean, or a required `searchSource` | A component holding its own choices exposes a boolean; one whose choices ARE the result takes a source | per component | the component | shipped |+| a query-only capability | a handler whose name says it needs a query | Presence of the handler is the switch; no boolean beside it (FR5) | absent | `spec:AST-056` | proposed |+| "no choices at all" | the component's own top-level `emptyText` | A different observable state from "the query matched nothing"; unchanged by this record | the component's localized default | the component | stable |+| fetch tuning | `minQueryLength`, `debounceMs`, loading text | Not placed by this record; they belong to whoever fetches, and OQ5 asks whether they move inside | per component | the component | stable |++## Requirements++### Behavioral contract++| ID | Invariant | Basis | Verification state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------- |+| FR1 | One observable state has one prop name and one type across every component with a typed query. "The query matched nothing" is `emptySearchText`, accepting `ReactNode`. `emptySearchResultsText` resolves to it and its `string` typing is widened, so a caller may pass an element. No component may name or type this state differently. | DEC-1; `architecture:public-component-api` INV2 | Proposed; no evidence on `main` |+| FR2 | "The query matched nothing" and "the component was given no choices at all" are different states and MUST stay separately expressible under distinct names: `emptySearchText` and `emptyText`. `Selector` and `MultiSelector` already declare both, so neither name may absorb the other, and a component offering only one MUST still use the name that matches the state it means. | DEC-1; `spec:AST-002` FR16 | Proposed; shipped behavior, unspecified |+| FR3 | Whatever a caller supplies for an empty state MUST reach the person operating the component, visually and non-visually alike. A component that announces this state MUST announce what it rendered. Announcing a built-in default while rendering the caller's element is a defect, not a fallback. | AR1; `architecture:interaction-modality` | Proposed; defect on `main` (see AR1) |+| FR4 | Who resolves the query is settled by who owns the choices, and is not restated per component. A component that holds its own choice set resolves the query itself, matching case-insensitively on each choice's displayed label at minimum, and exposes a boolean to turn the query input on. A component whose presented choices ARE the query's result takes a required `searchSource`. Both kinds reach the same observable states: a narrowed list, an empty result, and `emptyText`. | DEC-2; `spec:AST-002` FR16 | Proposed; shipped behavior, unspecified |+| FR5 | A capability that cannot function without a typed query MUST have exactly one switch, and MUST report through the component's primary change callback with a descriptor naming the kind of change, rather than through a handler prop of its own. A caller MUST NOT be able to express a configuration that renders nothing and reports nothing, which `hasCreate && hasSearch && onCreate != null` permits whenever any one piece is missing. Enabling it on a component with no query input MUST warn in development rather than fail silently. | DEC-3; `spec:AST-002` FR15 (never silently render a broken state) | Proposed; no evidence on `main` |+| FR6 | A new search-related capability is admitted under `spec:AST-002` against this record, or not at all. A new top-level prop whose name carries the word `search` MUST name the state or capability it governs in the vocabulary this record fixes, and MUST NOT introduce a second name for a state one of these props already expresses. | DEC-4; `spec:AST-002` FR1, FR5, DEC-1 | Proposed; no evidence on `main` |+| FR7 | Every prop this record renames is a released public surface with a victim, so it MUST follow `spec:AST-017` FR28–FR31: the replacement ships first, old usage stays equivalent through the overlap, each old prop gets a `DEP-*` id and a distinct `CLN-*` id, and removal happens only in a minor whose frozen manifest carries both. While both exist, a component given both MUST resolve to the new prop and MUST fire a development warning. | `architecture:public-component-api` INV9; `spec:AST-017` FR1, FR3, FR28–FR31 | Proposed; cycle not started |++### Accessibility contract++- **AR1 — The empty-result message reaches assistive technology as written.**+ Whatever `emptySearchText` renders on screen MUST be what a screen reader+ receives when the panel becomes empty. Today it is not: `Selector` and+ `MultiSelector` announce `typeof emptySearchText === 'string' ? emptySearchText+: t('@astryx.selector.emptySearchResults')`, so a caller who passes an element+ — which the `ReactNode` type invites — is silently announced the default+ string instead of their own message. Accepting `ReactNode` (FR1) obliges the+ component to derive an announceable string from it, or to document and+ require a separate announceable form; it may not announce something the+ person on screen is not reading.+- **AR2 — The query input has an accessible name that is not its placeholder.**+ A placeholder is placeholder text and MUST NOT be the input's only+ accessible name. The component supplies the name — `Selector` and+ `MultiSelector` use a localized "Search options" today — and a component+ that falls back to the placeholder, as `CommandPaletteInput` does and its own+ comment flags, MUST gain a real name as part of adopting this record.++### Platform support++- Supported feature/engine floor: every supported renderer and every supported+ browser. Nothing here is behind a capability check.+- Unsupported behavior: none. A component that cannot satisfy FR3's+ required/optional rule does not partially adopt the prop; it keeps its+ current API until the rule is settled for it.+- Browser evidence: this record contracts prop shape and announcement, not+ layout or paint, so every requirement here is provable in jsdom. AR1's+ announcement is a live-region assertion, not a pixel claim. Adopting+ components keep whatever real-browser evidence their own records already+ require.++## Migration and compatibility++This is not additive, and the cost is concentrated in one place.++**What is shipped and has a released victim.** Nine public props across seven+core components: `hasSearch`, `searchPlaceholder`, and `emptySearchText` on+`Selector` and `MultiSelector`; `searchSource` and `emptySearchResultsText` on+`Tokenizer`, `Typeahead`, and `BaseTypeahead`; `searchSource` and+`emptySearchText` on `CommandPalette`; `onChangeQuery` on the three typeaheads;+`hasCreate` on `Tokenizer`; `emptySearchResultsText` on every+`ChatComposerTrigger`. Under `spec:AST-017` FR1 and FR3, and+`architecture:public-component-api` INV9, removing or retyping any of them is a+breaking change.++**The expensive one is `searchSource`.** It is **required** on `Tokenizer`,+`Typeahead`, `BaseTypeahead`, and `CommandPalette`. The cut that removes it does+not degrade a long tail of callsites — it fails every existing callsite of those+four components at type-check. Nothing else here is close to that.++**This record's recommendation: deprecate with a replacement-first cycle.** Not+coexist indefinitely, not replace.++- A patch ships `search` on each adopter while every old prop keeps working,+ carries `@deprecated` naming its replacement, and behaves exactly as before+ (`spec:AST-017` FR28, FR29). During the overlap a component reads both and+ the key wins, with one development warning on conflict (FR9).+- Each old prop gets a `DEP-*` id and a distinct `CLN-*` id. Removal happens in+ a later minor only when both ids are in that minor's frozen manifest+ (`spec:AST-017` FR31). This record sets no clock; FR30 forbids reading+ release cadence as one.+- Until that cleanup minor, FR3's "MUST declare `search` required" cannot be+ true on the four components where `searchSource` is required, because+ `searchSource` still satisfies them. FR3's required clause becomes+ enforceable at cleanup, not at adoption.++**What each option actually costs.**++- **Deprecate with a cycle (recommended).** One prop doubles for the length of+ the overlap, on three components: `emptySearchResultsText` and+ `emptySearchText` both present in the types, both in `.doc.mjs`, both in the+ consumer docs. Three `DEP-*` records and three `CLN-*` ids. The rename is+ mechanically codemoddable, including where a caller spreads props, because+ the value's meaning does not change and the type only widens. Then one minor+ that breaks unmigrated callsites of three components — and a caller who+ passed a `string` needs no edit beyond the name.+- **Coexist indefinitely.** Nothing breaks, ever. The drift survives in the+ type signature: a builder still meets `emptySearchResultsText` on one+ component and `emptySearchText` on another, and the standard governs only+ components built after it. That answers "so when we add it later on other+ components we match the pattern" and leaves today's inconsistency in place.+- **Replace outright.** A major version, or a minor that breaks four+ components' entire callsite base at once with no overlap. Rejected: no user+ problem here justifies it.++**`Tokenizer.hasCreate` is the one genuine collision, and it is not mechanical.**+Tokenizer's shipped `hasCreate` is a boolean with no callback: the component+mints the token from the typed text itself, because a token _is_ a string.+#6829's `onCreate` exists precisely because `MultiSelector` cannot do that — an+option needs a value the caller defines. Under FR7 the boolean cannot survive as+a boolean, but mapping it to `onCreate` moves work onto every existing Tokenizer+caller. OQ5 puts that to the owner; until it is answered, this record does not+require `Tokenizer` to change `hasCreate`.++## Current-state impact++- `architecture:public-component-api` gains `spec:AST-056` in its+ `deciding_specs` and a line in its `Deciding specs` list when this record+ becomes `current`. No invariant of that record changes: FR1–FR10 sit inside+ its INV2, INV3, and INV9 grammar rather than amending it.+- `contributing:api-conventions` and the wiki's `Prop Naming` section gain the+ state-naming rule: one observable state has one prop name and one type+ across every component that has it, and a new prop may not introduce a+ second name for a state an existing one already expresses. Neither surface+ rules on this today.+- `component:Selector`, `component:MultiSelector`, `component:Tokenizer`,+ `component:Typeahead`, `component:BaseTypeahead`, and+ `component:CommandPalette` cite this record instead of each recording a+ private copy. `component:MultiSelector` is `authority: draft` and is drafting+ exactly such a copy as its FR10 / DEC-3; that claim is withdrawn in favour of+ FR6 and FR7 here.+- [#6829](https://github.com/facebook/astryx/pull/6829) is blocked on this+ ruling. Its `hasCreate` + `onCreate` pair is rejected by FR5, which admits+ the same user need as `hasCreate` alone, reported through the component's+ existing `onChange` with a descriptor naming the creation — the shape+ `Tokenizer` already ships — so the capability cannot be half-configured and+ one word does not carry two contracts.+- `family:input-fields`, `spec:AST-002`, and `spec:AST-017` are read, not+ changed: field chrome, admission, and the deprecation lifecycle keep their+ owners.+- No shipped public API changes on this record's own merge. Every component+ keeps every prop and every default until an adoption change lands.+- While this record is `draft` its `review-applicability:v1` block routes+ nothing: global routing loads `current` claims only+ (`architecture:knowledge-contracts` INV20). It becomes live on approval.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR2 | Per-adopter prop-surface suites plus the repository's exported-surface and `.doc.mjs` prop checks | Each adopter's declared props; the exported object type imported from the package entry point | A top-level prop whose name carries `search`, a key repeating the prefix, or an unexported object type fails. |+| FR3 | Per-adopter rendering suites | `search` absent; `search={{}}`; `search` omitted on a component that requires it | A query input rendering with the prop absent, residual query state, or a required/optional declaration that contradicts whether the component holds choices, fails. |+| FR4 | Per-adopter suites in both modes | No `source`, with choices the component holds; a `source` supplied; a query matching nothing in each mode | Divergent observable states between the two modes, or a component re-filtering what a `source` returned, fails. |+| FR5, AR1 | Per-adopter suites plus their live-region assertions | A string `emptyText`; an element `emptyText`; the adjacent "no choices at all" state | A differently named or typed key, or an announcement that does not carry what the element rendered, fails. This is the gap AR1 names on `main` today. |+| FR6, FR7 | Type-level checks plus per-adopter suites | `onCreate` given with `search` present; `onCreate` given with `search` absent | A create affordance reachable without search, a boolean gating a handler, or a silently inert configuration, fails. |+| FR8 | Per-adopter suites | Typing; clearing; programmatic change | A callback that suppresses the component's own resolution, or a component requiring it, fails. |+| FR9 | Overlap suites on each adopter plus the release lifecycle's manifest checks | Old prop alone; key alone; both given; neither | Old usage changing behavior, a silent win for the old prop, a missing `DEP-*`/`CLN-*` pair, or a removal absent from the frozen minor manifest, fails. |+| FR10, AR2 | Public-API review against this record; per-adopter accessible-name assertions | A proposed new search capability; each adopter's query input, named and unnamed | A new top-level `search*` prop admitted, or a query input whose only name is its placeholder, fails. |++Known verification gap: none of the suites above exist on `main`, and no+component implements `search`. This record is `draft`, does not govern review,+and names no implementation. AR1 additionally records a defect in current+shipped behavior rather than a passing contract.++## Decision log++Every decision below is **proposed**. None has been ruled on; `approved_by` is+`null` and the record is `draft`.++### DEC-1 — One name and one type for "the query matched nothing"++**Reference:** `spec:AST-056/DEC-1`+**Decider:** `cixzhang`, `2026-10-02`++`emptySearchText`, accepting `ReactNode`, everywhere.++This is the drift that reached people. A person who searches a `Selector` and+a `Tokenizer` in the same product meets the same dead end, and today the two+components do not even agree what to call it, let alone what a caller may put+there. `Selector`, `MultiSelector` and `CommandPalette` say `emptySearchText`+and accept a `ReactNode`; `Tokenizer`, `Typeahead`, `BaseTypeahead` and+`ChatComposerInput` say `emptySearchResultsText` and accept a `string` — so+the same product cannot offer the same "no results, try X" row in both, and a+builder who learns one component has to discover the other.++The name resolves toward `emptySearchText` rather than a shorter one, and the+reason is load-bearing: `Selector` and `MultiSelector` already declare BOTH+`emptyText` and `emptySearchText`, for two genuinely different sentences —+"there is nothing here at all" and "nothing matched what you typed". Shortening+the search state's name would collide with a shipped prop meaning the other+thing, on the two components with the most search surface. So three components+rename toward the majority spelling instead of seven renaming away from it.++The type resolves toward `ReactNode`, not toward `string`. A dead end is+exactly where a product wants a link, an illustration, or a create+affordance, and narrowing the four components that already allow it would+remove a shipped capability to win consistency. Widening the other three is+what lets a product offer the same dead end everywhere, which is the whole+point of agreeing on the name.++### DEC-2 — No `search` configuration object++**Reference:** `spec:AST-056/DEC-2`+**Decider:** `cixzhang`, `2026-10-02`++An earlier draft of this record proposed collecting every search-related prop+into one object-valued `search` prop, with `placeholder`, `emptyText`,+`onChange` and `onCreate` as keys. Rejected.++The object would have solved tidiness rather than anything a person using an+Astryx product meets. Three flat props are not hard to pass, and the survey+below shows the repository has no settled convention to appeal to: every+`*Config` object in core configures a hook, and the only object-valued+component props are `collapsible` and `button`.++Against that, the cost was concrete. Nine shipped props would have entered a+deprecation cycle, four of them a **required** `searchSource`, breaking every+callsite of four components in the cleanup minor. `ComplexSelector` would+have taken a `search` object with one meaningful key, since it owns its own+content. And autocomplete gets worse, not better: typing inside a component's+tag lists flat props immediately, while `search={{` has to be known about+first.++What the drift actually called for was a shared vocabulary, which DEC-1 and+FR6 give without restructuring anything.++### DEC-3 — A query-only capability is enabled by a boolean and reported through the existing change callback++**Reference:** `spec:AST-056/DEC-3`+**Decider:** `cixzhang`, `2026-10-02`++A capability that only exists while a query does — creating a value from text+that matched nothing — is enabled by one boolean and reported through the+component's primary change callback, carrying a descriptor that says what kind+of change it was.++`Tokenizer` already does this: `hasCreate` turns the row on, and+`onChange(items, change)` reports `{item, type: 'create'}` beside `'add'`,+`'remove'` and `'reorder'`. A caller learns about a creation on the channel it+already listens to for every other change, and nothing can be half-configured,+because there is only one switch.++The shape this rules out is a boolean and a handler gating each other, which+is what `hasCreate && hasSearch && onCreate != null` produces: three ways to+be half-set, every one of them rendering nothing, reporting nothing, and+warning about nothing. A builder sets the boolean, sees no create row, and has+no way to learn why.++A component whose value does not carry the created object — `MultiSelector`+holds `options` separately from `value: string[]` — reports the next value and+the creation together, so the caller adds the option and accepts the value in+one update. That obligation is the caller's and must be stated where the+capability lands; it does not justify a second shape for the same capability.++The one case a boolean cannot prevent is enabling creation on a component+whose query input is switched off. That warns in development (FR5) rather than+rendering nothing in silence.++### DEC-4 — The vocabulary is fixed; new capabilities join it++**Reference:** `spec:AST-056/DEC-4`+**Decider:** `cixzhang`, `2026-10-02`++Every prop in the survey below was a reasonable local decision. The drift came+from each one being made alone: two names for one state, two types for one+name, `searchLabel` in lab, `maxSearchResults` on one component.++So the standard is a vocabulary rather than a structure. A new search-related+prop names its state in the words this record fixes, and does not introduce a+second name for something an existing prop already says. That is checkable in+review without anybody restructuring a component.++## Open questions++- **OQ1 — ANSWERED. Two concepts, split by who owns the choices.** (`human-api`)++ `cixzhang`, 2026-10-02: a component that holds its own choices takes the+ `search` object; a component whose choices arrive from the caller keeps+ `searchSource`. The shared matching rule and `createStaticSource` show the+ two can be unified, but unifying them would make `source` a required member+ of an otherwise-optional object on four components, and would move a shipped+ required prop for no gain to its callers. FR1 and FR4 record the split, and+ DEC-1 carries the reasoning.++- **OQ2 — ANSWERED. Deprecate with a cycle.** (`human-api`)++ `cixzhang`, 2026-10-02: `emptySearchResultsText` is marked `@deprecated`+ pointing at `emptySearchText`, both work through the overlap, and removal+ happens in a later minor under `spec:AST-017` FR28–FR31. The cost is three+ `DEP-*`/`CLN-*` pairs and one doubled prop on three components, which is+ what FR7 already describes — far less than the nine pairs the rejected+ object form would have cost. The rename is codemoddable even where a caller+ spreads props, because the value's meaning does not change and the type only+ widens.++- **OQ3 — ANSWERED. No.** (`human-api`)++ `cixzhang`, 2026-10-02: observing the query does not become public on+ `Selector` or `MultiSelector` as part of this record. `searchQuery` stays+ internal state on both. A caller who needs to act on the query gets a+ capability that names what it is for — creation, below — rather than a raw+ query feed they must then re-implement the component's own behavior around.++- **OQ4 — ANSWERED. Three adopters; the rest are governed by FR1 only.** (`human-api`)++ `cixzhang`, 2026-10-02: `Selector`, `MultiSelector` and `ComplexSelector`+ are where a `search` object would have gone, so they are the components this+ record most directly addresses; with the object rejected (DEC-2) the+ distinction mostly dissolves. `Tokenizer`, `Typeahead`, `BaseTypeahead`,+ `CommandPalette` and `ChatComposerInput` keep `searchSource` and are bound by+ FR1 (one name, one type for "the query matched nothing") and FR6 (no second+ name for a state these props already express). `PowerSearch` stays cited and+ excluded: a structured field/operator/value expression is not a typed query+ over a list.++- **OQ5 — ANSWERED. One capability, a boolean plus a change descriptor.** (`human-api`)++ `cixzhang`, 2026-10-02: a create affordance is enabled by a boolean and+ reported through the component's existing change callback, carrying a+ descriptor that says the change was a creation. No separate handler prop,+ and no `create` configuration object.++ `Tokenizer` already works this way: `onChange(items, change)` where `change`+ is `{item, type: 'create'}`, alongside `'add'`, `'remove'` and `'reorder'`.+ `MultiSelector` can report the same way — the next value together with a+ descriptor naming the created query — so the caller adds the option and+ accepts the value in one update, learning about creation on the channel it+ already listens to for every other selection change.++ This supersedes an earlier answer here that treated the two as different+ capabilities needing different shapes, on the grounds that `MultiSelector`+ splits `options` from `value: string[]` and so cannot mint an option the way+ `Tokenizer` mints a token. That difference is real but does not force a+ separate handler: reporting the value and the creation together is exactly+ what the descriptor is for. `hasCreate` therefore means one thing in both+ components, which is FR1's rule applied to a verb rather than a state.++ Two things the contract owes, to be settled where the capability lands+ rather than here: the descriptor's shape as a public type, and the caller's+ obligation to add the created option — `Tokenizer` has no such obligation+ because its value carries the object itself, while a `MultiSelector` caller+ who accepts the value without adding the option holds an id that matches+ nothing.++ `minQueryLength`, `debounceMs` and the trigger-menu `loadingText` stay where+ they are. They describe fetching, which only exists where the caller owns+ the choices, and this record does not reorganize shipped props.++## Content boundary++This record does not duplicate any component's anatomy, prop table, theming+targets, or consumer examples; the admission argument in `spec:AST-002`; the+deprecation, cleanup, and release-manifest mechanics in `spec:AST-017`; the+shared naming grammar in `architecture:public-component-api`; the field chrome+in `family:input-fields`; or the matching, debouncing, and cancellation+behavior each component's own record owns. It links their canonical owners.