An open source design system that's fully customizable and agent ready
schema_version: 4 template_version: 2 kind: system-spec id: spec:AST-109 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: [] affects_consumer_docs: [Selector]
Clear value system spec
{
"paths": ["packages/core/src/Selector/**"]
}
Intent
Clearing a Selector returns it to its starting point, and the caller says
what that point is. A filter whose starting point is "Everyone" clears to
"Everyone", not to a blank field. The row that stands for the starting point
stays in the list while a search narrows it, so a person can always get back
from the list itself.
Members
This rule applies to Selector only. Its value type is string, its clear
option (FR4) is the option whose value is clearValue, and equality is
string equality. Every other member of family:input-fields, including
Typeahead, Tokenizer, MultiSelector, and ComplexSelector, keeps a plain
boolean hasClear with no clearValue.
Non-goals
- A reset concept separate from clear. There is one clear job, one prop for
it, and
hasClear'sclearValuenames where it lands. - A default value or uncontrolled mode.
Selectoris controlled and has nodefaultValue. - Search matching and query normalization.
spec:AST-056FR4 owns the matching floor. hasClear's object form on any input other thanSelector:Typeahead,Tokenizer,MultiSelector,ComplexSelector,PowerSearch, and text, number, date, time, and file inputs.- 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. In that case, state who depends on it and why an equivalent implementation would not satisfy the contract.
Public contract
<Selector
label="Owner"
hasClear={{clearValue: 'all'}}
hasSearch
value={owner} // string, never null
onChange={setOwner} // (value: string) => void
options={[
{value: 'all', label: 'Everyone', icon: UsersIcon},
{type: 'divider'},
...owners,
]}
/>
Requirements
- FR1 —
hasClear={{clearValue}}is where clear lands.Selector'shasClearacceptsboolean | {clearValue: string}.truebehaves as it does today: clear reportsnull. The object form turns clear on and makes every clear path reportclearValuethroughonChangeandchangeAction: the trigger's clear button, Delete and Backspace on the trigger, and choosing the clear option (FR4).falseand absent keep their current meaning. - FR2 — Types follow the object form, and existing callers are unchanged.
With
hasClear={{clearValue}},value,onChange, andchangeActiontakestringwithoutnull. Withtrue,false, or nohasClear, the types stay exactly as shipped, includingnullunderhasClear. - FR3 — At the clear value there is nothing to clear. While the value
equals
clearValue, the trigger's clear button is hidden, as it is hidden while the value is empty today. The trigger shows the value as it shows any value: that option's label and icon, andplaceholderis not shown. - FR4 — The clear option stays in the list. The option whose
valueequalsclearValueis the clear option. Search never hides it, including a query that matches nothing, where the empty-search message renders after it. It is not a result: result-count announcements and the empty-search state count matching items only. While a query is active, the default highlight lands on the first matching item, never on the clear option, so Enter never chooses it by accident; arrow keys reach it. It keeps the caller's position among top-level entries. AclearValuethat matches no option pins nothing and warns in development. - FR5 — Choosing the clear option is choosing a value. It uses the option
row's anatomy, size, press model, touch target, theme target, and
presentations, and closed-trigger type-to-find matches its label. Choosing it
closes the surface and returns focus to the trigger (
component:SelectorFR1). The clear button returns focus as it does today. - FR6 — Disabled, read-only, required, and forms keep their meaning. Clear
stays unavailable while
Selectoris disabled or read-only (component:SelectorFR6). An emptyclearValuefailsisRequiredvalidation as an empty value does today; a non-empty one does not. WithhtmlName, the submitted value after clear isclearValue.
Accessibility contract
- AR1 — Name and state. The clear option's accessible name is its label,
and its selected state is exposed while the value equals
clearValue. The clear button's accessible name and tooltip are unchanged (family:input-fieldsFR11). - AR2 — Focus. As FR5: choosing the clear option returns focus to the trigger, and the clear button keeps its existing focus return.
- AR3 — Announcement. Clear announces nothing extra: the trigger reads the new value, as for any choice.
- AR4 — Motion. Nothing here adds motion. Each surface's own motion and reduced-motion behavior apply.
Platform support
- Supported feature/engine floor: every supported browser and renderer. Nothing here is behind a capability check.
- Unsupported behavior: none.
- Browser evidence: type tests for FR2; DOM and accessibility-tree assertions for names, selected state, focus, and announcements; real-Chromium interaction for the press model in the popover and the bottom sheet.
Current-state impact
family:input-fieldsnames the{clearValue}form ofhasClearin its adoption table forSelectoronly, and cites this record. Every other member'shasClearstays a boolean.component:Selectornames the clear option and FR3's clear-button rule.Selector's.doc.mjsdocumentshasClear's object form and its type narrowing.Selectorkeeps one internal clear path; its current internal name does not constrain the public prop.
Verification
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1 | Selector callback and Action suites |
Clear button, Delete/Backspace, clear option; hasClear true and {clearValue} |
Any clear path reports something other than clearValue under the object form, or anything but null under true |
| FR2 | Selector type tests |
No hasClear; true; {clearValue} |
null is accepted with the object form, or any shipped signature changes without it |
| FR3 | Trigger rendering suites | Value equals clearValue; differs; empty |
The clear button shows at clearValue, or the trigger shows placeholder there |
| FR4 | Search suites with live-region assertions | No query; matches; no match; Enter in the search input; a clearValue with no option |
The row is filtered, counted, highlighted by default under a query, or chosen by Enter |
| FR5 | Interaction suites in popover and bottom sheet; real-Chromium | Pointer, touch, keyboard; type-to-find | The row diverges from option-row behavior, or focus lands elsewhere |
| FR6 | Disabled, read-only, required, and form suites | Disabled; read-only; required with empty and non-empty clearValue; htmlName |
Clear is reachable, required validation is wrong, or the submitted value differs |
| AR1–AR4 | Accessibility-tree, focus, and announcement assertions | Selector at and away from clearValue |
The name or state is missing, focus moves elsewhere, or an extra announcement fires |
Known verification gap: none of these suites exist on main.
Decision log
DEC-1 — Going back is clear, to a value the caller names on hasClear
Reference: spec:AST-109/DEC-1
Decider: cixzhang, 2026-10-28
Clear already means "go back to the starting point"; the object form of
hasClear lets the caller say where that is, so one job keeps one prop
(architecture:public-component-api INV21). The object is plain configuration
on the existing switch, not an anatomy setting (INV18), it adds no visual
boolean (INV20), and it costs nothing at runtime (INV19).
Rejected: a separate reset value or row, because it shares clear's job.
Rejected: a separate clearValue prop, because two props would switch one job.
DEC-2 — The clear option is the option that holds the clear value
Reference: spec:AST-109/DEC-2
Decider: pending
The option already carries the clear value's label and icon, so it is the row that stays in the list. No new entry kind or label prop exists.
Rejected: a dedicated clear entry in options, because it names the clear
state a second time beside the option that holds the value.
DEC-3 — Types narrow only with the object form
Reference: spec:AST-109/DEC-3
Decider: cixzhang, 2026-10-28
With hasClear={{clearValue}} Selector never reports null, so its types
say so. With any other hasClear value nothing changes, so the object form is
additive.
DEC-4 — The clear value is Selector's alone
Reference: spec:AST-109/DEC-4
Decider: cixzhang, 2026-10-29
hasClear's object form and the clear option belong to Selector, whose
filters start at a real value such as "Everyone". Typeahead, Tokenizer, and
every other input keep a plain boolean hasClear. PowerSearch is not a
selector.
Rejected: the object form across the selector family, because only Selector
needs clear to land on a real value.
Open questions
- OQ1 — Does
hasClear's object form extend toMultiSelectororComplexSelector? (human-api) Until ruled, both keep a plain booleanhasClear.