An open source design system that's fully customizable and agent ready
TypeScript
docs: define async option-source states (#5707)
Cindy Zhange03511bb7c1d
diff --git a/docs/specs/AST-001/spec.md b/docs/specs/AST-001/spec.mdnew file mode 100644index 0000000000..01c0273854--- /dev/null+++ b/docs/specs/AST-001/spec.md@@ -0,0 +1,147 @@+---+schema_version: 1+template_version: 1+kind: system-spec+id: spec:AST-001+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-08-31+phase: accepted+owners: [cixzhang, imdreamrunner]+affects_architecture: [architecture:public-component-api]+affects_families: [family:input-fields]+affects_contributing: []+affects_consumer_docs: [Selector, MultiSelector]+---++# Async option-source states++## Intent++People using Selector or MultiSelector should be able to use every option the+caller has provided, including while the field value is resolving or being+saved. When no option is available, the control should communicate whether the+source is still pending or has completed empty instead of presenting a silent,+actionable-looking selector.++## Non-goals++- Redefining input-family `isLoading`; it remains a value-resolution or saving+ state.+- Choosing the public API name or shape for initial option-source pending state.+- Defining failure, retry, pagination, caching, or stale-response ordering.+- Changing Typeahead's component-owned async search lifecycle.+- Implementing Selector or MultiSelector behavior in this specification pull+ request.++## Requirements++- **FR1 — Provided options determine availability.** The normalized options+ supplied to Selector or MultiSelector are the source of which options can be+ rendered and selected.+- **FR2 — Input loading does not suppress options.** Input `isLoading` MUST NOT+ hide, disable, or otherwise make a provided option unavailable. Search and+ keyboard navigation MUST operate on the same provided option set while the+ field value is busy.+- **FR3 — Zero provided options means no selectable option state.** When the+ normalized provided set contains no selectable option, the selector MUST NOT+ offer activation or navigation that implies a choice is available.+- **FR4 — Initial pending is explicit.** Initial option-source pending state MUST+ be supplied independently. It MUST NOT be inferred from zero options or input+ `isLoading`.+- **FR5 — Pending does not create false empty or read-only claims.** With zero+ provided options, explicit initial pending still has no selectable option, but+ it MUST be presented and announced as loading rather than as completed empty+ or read-only. With provided options, a pending source signal MUST NOT override+ FR1 or FR2.+- **FR6 — Completed empty is read-only and explicit.** With zero provided options+ and no explicit initial pending state, the selector is read-only with no+ selectable option. Its visible and programmatic state MUST communicate that+ completion without requiring a person to activate an unavailable popup.+- **FR7 — Loading, read-only, and empty stay distinguishable.** Visual output,+ accessibility semantics, focus behavior, and announcements MUST agree for:+ initial pending, completed empty, and provided options while input `isLoading`+ is true. A transition from initial pending to completed empty MUST announce the+ new outcome once without losing the control's accessible name or current+ value.++### Platform support++- Supported feature/engine floor: the same browser and assistive-technology+ support as Selector and MultiSelector.+- Unsupported behavior: input `isLoading` MUST NOT be used as a fallback+ option-source signal.+- Browser evidence: the loading, read-only, and completed-empty states require+ real-browser keyboard, accessibility-tree, and screen-reader verification;+ DOM assertions alone are not sufficient.++## Current-state impact++- Selector and MultiSelector already keep non-empty provided options rendered,+ keyboard-reachable, and selectable while input `isLoading` is true. That+ satisfies FR1 and FR2; implementation MUST preserve it.+- Input `isLoading` currently suppresses empty and no-results presentation and+ search result-count announcements. Source comments and consumer API text+ describe that suppression as meaning options have not arrived, although the+ flag owns value resolution or saving.+- Neither component exposes explicit initial option-source pending state. With+ zero options and no input loading, each still offers an actionable trigger that+ opens completed-empty content rather than a read-only no-choice state.+- `family:input-fields/FR5` and `family:input-fields/DEC-2` already record the+ approved meaning of input `isLoading`. This spec narrows the resulting+ zero-option, pending, and accessibility requirements for selectors.+- `architecture:public-component-api` and `spec:AST-002` govern the unresolved+ public API needed to represent explicit initial pending state.+- Implementation targets the pending API, zero-option read-only behavior, and+ accessible state transitions. It also removes incorrect option-nonarrival+ claims while preserving populated-option availability. The owning component+ contracts and consumer docs must then link the applicable AST-001 decisions;+ until that lands, `component:Selector` remains the source of truth for shipped+ Selector behavior.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |+| FR1, FR2 | Selector and MultiSelector interaction tests | populated options with input `isLoading`; searched and unsearched; pointer and keyboard | A provided option disappears, becomes unreachable, or cannot be selected because the field value is busy |+| FR3, FR5, FR6 | State-transition and activation tests | zero options while initial pending; pending to completed empty; zero options without pending | The control offers a nonexistent choice, claims completed empty while pending, or keeps presenting loading after completion |+| FR7 | Real-browser keyboard, accessibility-tree, and screen-reader matrix | initial pending, completed empty/read-only, populated while input `isLoading`, existing selected value | Visible and announced states disagree, focus is lost, name/value disappears, or a transition is silent or announced repeatedly |+| Public API | Type-level and consumer-example tests after OQ1 is resolved | omitted/default state, explicit initial pending, dynamic completion | Zero options or input `isLoading` silently substitutes for the explicit source state |++## Decision log++### DEC-1 — Provided options stay available while the input value is loading++**Reference:** `spec:AST-001/DEC-1`+**Decider:** `cixzhang`, `2026-08-31`++Selector and MultiSelector derive option availability from the options the caller+provides. Input `isLoading` describes value resolution or saving and does not+suppress those options.++Rejected: treating input `isLoading` as evidence that independently supplied+options have not arrived, because it makes valid choices unavailable and combines+two unrelated states.++### DEC-2 — Zero options is a no-choice state, not evidence of pending work++**Reference:** `spec:AST-001/DEC-2`+**Decider:** `cixzhang`, `2026-08-31`++Zero provided options means there is no selectable option and, once the source is+not explicitly pending, the selector is read-only and communicates completed+empty. Initial pending is a separate explicit state: it has no selectable option+but communicates loading and MUST NOT be inferred from the empty array.++Rejected: using one zero-option observation to mean both “still loading” and+“completed with no choices,” because people and assistive technology could not+distinguish waiting from a finished read-only control.++## Open questions++- **OQ1 — What public API represents explicit initial option-source pending for+ Selector and MultiSelector?** (`human-api`) The API must distinguish pending+ from completed empty without changing input `isLoading` or overriding provided+ option availability.