An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-056): mark approved, and clear text the rewrite left behind (#6907)
Cindy Zhang967a936ee07d
diff --git a/docs/specs/AST-056-search-prop-shape/spec.md b/docs/specs/AST-056-search-prop-shape/spec.mdindex 3bc977dda9..089a830d3a 100644--- a/docs/specs/AST-056-search-prop-shape/spec.md+++ b/docs/specs/AST-056-search-prop-shape/spec.md@@ -3,12 +3,12 @@ schema_version: 4template_version: 1kind: system-specid: spec:AST-056-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null-phase: proposed+approved_by: cixzhang+approved_at: 2026-10-02+phase: acceptedowners: [cixzhang]affects_architecture: [architecture:public-component-api]affects_families: [family:input-fields]@@ -284,60 +284,58 @@ core components: `hasSearch`, `searchPlaceholder`, and `emptySearchText` on`architecture:public-component-api` INV9, removing or retyping any of them is abreaking 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.+**Nothing required moves.** An earlier draft would have folded the **required**+`searchSource` on `Tokenizer`, `Typeahead`, `BaseTypeahead` and+`CommandPalette` into an object, failing every existing callsite of those four+components at type-check. DEC-2 rejected that, so the whole migration is now+one optional prop renamed on four surfaces, with its type widened.**This record's recommendation: deprecate with a replacement-first cycle.** Notcoexist indefinitely, not replace.-- A patch ships `search` on each adopter while every old prop keeps working,+- A patch ships `emptySearchText` on each renaming component while the 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).+ the new prop wins, with one development warning on conflict (FR7).- Each old prop gets a `DEP-*` id and a distinct `CLN-*` id. Removal happens ina later minor only when both ids are in that minor's frozen manifest(`spec:AST-017` FR31). This record sets no clock; FR30 forbids readingrelease 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.+- A caller who passed a `string` needs no edit beyond the name: the type only+ widens, so every existing value stays valid.**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.+ the overlap, on `Tokenizer`, `Typeahead`, `BaseTypeahead` and+ `ChatComposerTrigger`: `emptySearchResultsText` and `emptySearchText` both+ present in the types, both in `.doc.mjs`, both in the consumer docs. Four+ `DEP-*` records and four `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 those four surfaces.- **Coexist indefinitely.** Nothing breaks, ever. The drift survives in thetype signature: a builder still meets `emptySearchResultsText` on onecomponent and `emptySearchText` on another, and the standard governs onlycomponents built after it. That answers "so when we add it later on othercomponents 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`.+- **Replace outright.** A minor that renames with no overlap. Rejected: the+ deprecation costs little here and no user problem justifies breaking+ callsites that a cycle would carry.++**`Tokenizer.hasCreate` needs no migration.** An earlier reading treated it as+a collision, because `Tokenizer`'s `hasCreate` is a boolean with no callback+while #6829 proposed a handler for `MultiSelector`. OQ5 settles it the other+way: `Tokenizer` mints the token itself and reports it through+`onChange(items, {item, type: 'create'})`, which is exactly the shape DEC-3+describes, so `Tokenizer` already conforms and changes nothing.+`MultiSelector` converges on it when #6829 returns.## 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+ becomes `current`. No invariant of that record changes: FR1–FR7 sit insideits INV2, INV3, and INV9 grammar rather than amending it.- `contributing:api-conventions` and the wiki's `Prop Naming` section gain thestate-naming rule: one observable state has one prop name and one type@@ -348,8 +346,7 @@ require `Tokenizer` to change `hasCreate`.`component:Typeahead`, `component:BaseTypeahead`, and`component:CommandPalette` cite this record instead of each recording aprivate 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.+ exactly such a copy; that claim is withdrawn in favour of FR5 and FR6 here.- [#6829](https://github.com/facebook/astryx/pull/6829) is blocked on thisruling. Its `hasCreate` + `onCreate` pair is rejected by FR5, which admitsthe same user need as `hasCreate` alone, reported through the component's@@ -385,8 +382,8 @@ 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`.+Every decision below was ruled by `cixzhang` on 2026-10-02, on this record's+pull request.### DEC-1 — One name and one type for "the query matched nothing"