Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: record Selector contract and accepted indicator change (#5706)

Cindy Zhang1f005bf71a7d
diff --git a/docs/specs/AST-004/spec.md b/docs/specs/AST-004/spec.md
new file mode 100644
index 0000000000..957e27917e
--- /dev/null
+++ b/docs/specs/AST-004/spec.md
@@ -0,0 +1,155 @@
+---
+schema_version: 1
+template_version: 1
+kind: system-spec
+id: spec:AST-004
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+phase: accepted
+owners: [cixzhang, imdreamrunner]
+affects_architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:icon-resolution-and-component-slots,
+ ]
+affects_families: []
+affects_contributing: []
+affects_consumer_docs: []
+---
+
+# Selector empty indicator-space collapse system spec
+
+## Intent
+
+Give unselected options the width currently consumed by an empty selection-mark
+column. A person should not lose label space to an indicator that draws nothing.
+The selected row may therefore shift or truncate earlier when its mark appears;
+that difference is an accepted part of the selection state.
+
+This spec records an approved future change. `component:Selector` remains the
+source of truth for shipped behavior until the implementation and verification
+below land and that current contract is updated in the same pull request.
+
+## Non-goals
+
+- Implementing the runtime change in this specification pull request.
+- Adding a public prop to preserve or select indicator-column reservation.
+- Removing `indicatorPosition` or changing its default logical edge.
+- Hiding an unselected indicator that a theme intentionally renders, such as an
+ unchecked radio replacement.
+- Changing selection, keyboard, loading, adaptive presentation, Popover,
+ BottomSheet, or listbox/dialog semantics.
+- Establishing an input-family or selection-family layout rule.
+
+## Requirements
+
+- **FR1 — Empty indicator space collapses.** An unselected option whose resolved
+ selection indicator draws no content MUST NOT reserve an empty indicator
+ column.
+- **FR2 — Rendered indicators keep their space.** A selected mark and any themed
+ replacement that renders an unselected state MUST remain in row layout at the
+ configured `indicatorPosition`.
+- **FR3 — State-dependent width is intentional.** When only the selected row
+ renders a mark, its label may start at a different inline position or have less
+ available width than an unselected label. The implementation MUST preserve
+ readable row content and existing overflow behavior rather than compensating
+ with blank space.
+- **FR4 — Logical placement still applies.** `indicatorPosition="start"` and
+ `"end"` MUST place each rendered mark at that logical edge in both LTR and RTL.
+- **IR1 — Derive layout from rendered content.** The component MUST determine
+ whether space exists from the resolved indicator output; it MUST NOT add a new
+ public reservation or alignment prop.
+- **IR2 — Preserve theme replacement.** The change MUST continue resolving the
+ indicator through the current theme-owned indicator path, including selected
+ and unselected states.
+- **IR3 — Preserve semantic ownership.** Collapsing visual space MUST NOT change
+ option roles, `aria-selected`, listbox ownership, trigger relationships, or
+ which element carries the stable `selector-check` theme target.
+
+### Platform support
+
+- Supported feature/engine floor: all browsers supported by Astryx Core.
+- Unsupported behavior: none; the layout MUST use the existing cross-browser CSS
+ and React support floor.
+- Browser evidence: real Chromium verifies rendered spacing and truncation. RTL
+ and compact-width cases are required; DOM structure or jsdom alone is not
+ visual evidence.
+
+## Current-state impact
+
+Current `main` intentionally renders an indicator wrapper for every option and
+applies a minimum inline width to that wrapper. The default unchecked check
+indicator draws nothing, so unselected rows still reserve blank space. Existing
+`Selector.test.tsx` coverage explicitly asserts two row children at both
+indicator positions.
+
+Implementation changes `component:Selector/FR3` and its mapped tests. It remains
+bounded by the current systems Selector already uses:
+
+- `architecture:component-theming-surface` continues to own stable theme targets;
+- `architecture:icon-resolution-and-component-slots` continues to own resolved
+ indicator replacement and stateful rendering;
+- `architecture:interaction-modality` and `architecture:layer-runtime` remain
+ unchanged; pointer Popover and touch modal-dialog behavior are not part of this
+ layout change; and
+- `architecture:public-component-api` continues to prohibit exposing a derivable
+ layout difference as a new caller-controlled prop.
+
+### Implementation requirements
+
+1. Collapse the mark wrapper only when the resolved indicator renders no content.
+2. Preserve layout space for the selected default check and for themed indicators
+ that render an unselected state.
+3. Replace the current reserved-column assertion with focused coverage for empty
+ collapse and rendered replacement indicators at both logical positions.
+4. Update `component:Selector` in the implementation pull request so its current
+ requirements and verification map describe the shipped result.
+5. Add stable real-browser visual regression coverage before this spec moves to
+ `shipped`.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| ------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| FR1, FR3 | Focused `Selector.test.tsx` layout assertions | default check; selected and unselected rows; narrow long labels | An empty wrapper keeps width, or selected-state truncation is masked by restored blank spacing |
+| FR2, IR2 | Indicator replacement tests | default check and themed radio; checked and unchecked | Unselected themed output disappears or loses its layout space |
+| FR4 | Logical-order tests and real-browser screenshots | `start`/`end`; LTR/RTL; selected/unselected | A rendered mark appears on the physical rather than logical edge |
+| IR1, IR3 | Public-surface, role, and theme-target tests | default and custom option rendering; search/non-search | A new public prop appears, option/listbox semantics change, or the stable target moves |
+| Visual result | Stable visual regression in real Chromium | pointer Popover and touch modal dialog; narrow/wide; start/end; default/themed indicator | Empty space remains, visible indicators overlap, or selected/unselected content becomes unreadable |
+
+### Completion criteria
+
+This spec moves from `accepted` to `shipped` only when:
+
+- empty default-check wrappers consume no indicator-column width;
+- selected marks and visible unselected theme replacements retain their required
+ space at both logical positions in LTR and RTL;
+- selected-row shift and narrower available width are covered as intentional
+ behavior, including long-label truncation;
+- focused unit and real-browser visual regressions cover pointer Popover and
+ touch modal-dialog presentations without changing their semantics; and
+- `component:Selector` is updated from the reserved-column baseline to the new
+ shipped behavior in the same pull request.
+
+## Decision log
+
+### DEC-1 — Unselected rows collapse empty indicator space
+
+**Reference:** `spec:AST-004/DEC-1`
+**Decider:** `cixzhang`, `2026-08-30`
+
+An unselected Selector option does not reserve blank space when its resolved
+selection indicator draws nothing. This gives unselected labels more usable
+width. A selected label may shift or truncate earlier when its indicator appears;
+that state difference is intentional.
+
+Rejected: reserving an empty column on every row solely to keep selected and
+unselected labels aligned. That alignment spends content width on an absent
+visual and makes the unselected state less useful.
+
+## Open questions
+
+None.
diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.md
new file mode 100644
index 0000000000..2ec55e8503
--- /dev/null
+++ b/packages/core/src/Selector/Selector.spec.md
@@ -0,0 +1,202 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Selector
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+owners: [cixzhang, imdreamrunner]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/Selector/Selector.test.tsx,
+ packages/core/src/Selector/Selector.source-build.test.mjs,
+ ]
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:icon-resolution-and-component-slots,
+ architecture:interaction-modality,
+ architecture:layer-runtime,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: [spec:AST-004/DEC-1]
+---
+
+# Selector component contract
+
+## Intent
+
+Selector lets a person choose one value from a moderate list while keeping the
+trigger usable as a form field or compact toolbar control. It owns single-value
+selection, option navigation, search within the supplied options, and the
+connection between the closed trigger and its selection surface.
+
+## Compatibility and migration
+
+- Released defaults and behavior remain unchanged by this record.
+- `indicatorPosition` defaults to `end`; every option row currently reserves the
+ indicator column at the configured logical edge.
+- `presentation` defaults to `popover`. `bottom-sheet` is an explicit modal
+ presentation, and `adaptive` selects it on compact coarse-pointer screens.
+- `hasClear` changes the value contract to include `null`; that distinction is
+ already part of the public type.
+- `spec:AST-004/DEC-1` accepts a future change that collapses an empty indicator
+ column. It is not shipped behavior and does not replace FR3 until implementation,
+ visual verification, and an update to this current contract land together.
+
+## Ownership boundary
+
+**Owns**
+
+- Choosing one value from supplied options.
+- Trigger, listbox, option, search, empty, loading, and disabled behavior.
+- Keyboard navigation and announcements for that selection flow.
+- Selector-specific composition of shared Field, Layer, adaptive presentation,
+ and indicator behavior.
+
+**Does not own / non-goals**
+
+- Action or navigation menus; DropdownMenu owns those.
+- Multi-value selection; MultiSelector owns it.
+- Product-specific option content or filtering performed outside the supplied
+ option list.
+- Family-wide input sizing, loading, end-lane, or disabled-reason policy. The
+ draft `family:input-fields` record is non-authoritative context only.
+
+## Public concepts
+
+This table names semantic concepts reviewers need. Prop syntax, complete defaults,
+and examples remain in `Selector.doc.mjs`.
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ---------------------- | -------------------------------------- | ------------------------------------------------------- | ----------------------------------------- | --------- | -------- | --------- | ------------------------------- |
+| trigger variant | `input`, `ghost` | Form-field or toolbar presentation | All trigger states | `input` | Selector | released | TypeScript rejects other values |
+| size | `sm`, `md`, `lg` | Trigger and option-row density | All presentations | `md` | Selector | released | TypeScript rejects other values |
+| selected-mark position | `start`, `end` | Logical edge containing the reserved selection column | Every option row | `end` | Selector | released | TypeScript rejects other values |
+| presentation | `popover`, `bottom-sheet`, `adaptive` | Anchored pointer surface or modal compact-touch surface | All trigger variants | `popover` | Selector | released | TypeScript rejects other values |
+| popup semantics | `listbox`; modal dialog containing one | Semantics follow the active presentation | Popover; bottom sheet | `listbox` | Selector | released | No separate role prop is public |
+| option-row state | `selected`, `disabled` | Stable theming state on each option row | Every rendered option | neither | Selector | released | Unknown states are not emitted |
+
+## Behavioral and layout contract
+
+These requirements describe shipped behavior on current `main`.
+
+| ID | Shipped invariant | Evidence |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| FR1 | Selecting an enabled option updates the one selected value, closes the active presentation, and returns the trigger to its stable closed state. | Consumer docs and selection interaction tests |
+| FR2 | Without explicit placement, a non-search popover aligns the selected row over the trigger and clamps it to the viewport. Search popovers and explicit placement use normal Layer positioning. | Consumer docs, implementation, and geometry tests |
+| FR3 | Every option row reserves one selection-mark column at `indicatorPosition`, even when the default unchecked indicator draws nothing. The column has a minimum width and can grow for a larger themed replacement. | `itemMarkColumn`, indicator-position tests, and theme tests |
+| FR4 | `popover` uses an anchored Popover. `bottom-sheet` uses a modal BottomSheet. `adaptive` resolves to the modal bottom sheet on compact coarse-pointer screens and Popover otherwise. | Presentation controller and adaptive-presentation tests |
+| FR5 | While `isLoading` is true, the trigger exposes busy state and the listbox suppresses empty and no-results output. | Loading, empty-state, and announcement tests |
+
+### Allowed variation
+
+- **AV1 — Indicator rendering.** A theme may replace the check indicator. The
+ replacement may draw in both selected and unselected states; the current row
+ still reserves its indicator column.
+- **AV2 — Option content.** `renderOption` may replace visible option content,
+ while Selector keeps row role, selection, disabled state, navigation, and
+ theming state.
+- **AV3 — Selected value content.** `renderValue` may replace the closed value
+ display without changing the placeholder or trigger's selection role.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------ |
+| closed with no value | Label and placeholder identify the field | Consumer placeholder text |
+| closed with a value | Selected option is represented in the trigger | Custom `renderValue` content |
+| pointer / popover | Anchored surface exposes the listbox without modal-dialog semantics | Default or explicit placement |
+| compact coarse pointer | BottomSheet exposes a modal dialog containing the listbox | Explicit `bottom-sheet` or resolved `adaptive` |
+| searching | Visible options, keyboard navigation, and announced result count use one filter | Consumer search and empty text |
+| loading | Trigger is busy; empty and no-results output is suppressed | Consumer loading duration |
+| disabled with reason | Trigger remains focusable enough to expose the reason while activation stays blocked | Consumer reason text |
+| selected/unselected rows | Row semantics and theming state are correct; both reserve the indicator column | Start/end position and themed indicator representation |
+
+### Transformation and precedence order
+
+- **ORD1 — Option normalization precedes filtering and selection.** Strings and
+ option objects become one option shape before search, keyboard matching,
+ rendering, and value comparison.
+- **ORD2 — Caller-selected content wins deliberately.** `startIcon` takes
+ precedence over a selected option's icon; explicit placement takes precedence
+ over selected-item overlay alignment.
+
+### Performance and resources
+
+- **PR1 — Search does not add effect-driven result-count renders.** The next
+ filtered count is derived from the input change and announced once for that
+ query.
+- **PR2 — Geometry work is scoped to the open popover.** Selected-item alignment
+ may read browser layout while opening; it does not impose document-wide or
+ persistent observation while closed.
+
+## Accessibility contract
+
+- **AR1 — Semantics follow presentation.** The anchored presentation exposes a
+ listbox through a Popover and the trigger uses `aria-haspopup="listbox"`. The
+ touch presentation exposes a modal BottomSheet dialog containing the listbox
+ and the trigger uses `aria-haspopup="dialog"`.
+- **AR2 — Focus follows the active interaction model.** The anchored presentation
+ keeps the combobox relationship at the trigger/search control. The modal touch
+ presentation moves focus into its search control or listbox and restores focus
+ to the trigger when it closes.
+- **AR3 — Keyboard selection matches the visible set.** Arrow, Home/End,
+ typeahead, search, Enter, Escape, and Tab behavior operate on the options a
+ person can currently perceive.
+
+## Design relationships
+
+No current design spec is linked.
+
+| Anatomy or state | Current representation requirement | Representation authority | Hierarchy role | Component contract |
+| -------------------------------- | --------------------------------------------------------------------------------------- | -------------------------- | ----------------------- | ------------------ |
+| selected mark and option spacing | Every row reserves the indicator column, preserving label alignment and available width | existing shipped behavior | supporting | FR3 |
+| input versus ghost trigger | none recorded | existing released behavior | form or toolbar control | Public concepts |
+
+The approved but unimplemented replacement for the first row is owned by
+`spec:AST-004/DEC-1`.
+
+## Family and system relationships
+
+- The current architecture links in frontmatter own public API, theming, icon
+ resolution, interaction modality, and Layer behavior used by Selector.
+- `spec:AST-004/DEC-1` owns the accepted future indicator-space change. Its
+ `accepted` phase is direction for implementation, not evidence that the runtime
+ has changed.
+- `family:input-fields` remains a draft. It may inform future reconciliation, but
+ this current component contract neither backlinks to it in frontmatter nor
+ depends on it for present policy.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| --------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1, AR2, AR3 | `Selector.test.tsx` selection, focus, and keyboard suites | closed/open, search/non-search, disabled option | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests | `audit:Selector/behavior` |
+| FR2 | placement and selected-item geometry tests | default, explicit, RTL, transformed entry | Using the wrong positioning model fails the expected position-area or margin | `audit:Selector/behavior` |
+| FR3, AV1 | `itemMarkColumn` source inspection plus indicator-position and replacement-indicator tests | start/end, selected/unselected, check/radio | Removing the wrapper fails row-structure tests; changing its reserved width requires source/layout review | `audit:Selector/design-rendered` |
+| FR4, AR1, AR2 | presentation tests plus `aria-haspopup` source review | pointer, compact coarse pointer, search/non-search | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review | `audit:Selector/accessibility` |
+| FR5 | loading, empty-state, and live-region tests | empty options, unmatched search, loading | Empty/no-results output appears or is announced while loading | `audit:Selector/behavior` |
+| source-build contract | `Selector.source-build.test.mjs` | package source compiled by consumer Babel | Moving evaluated StyleX values outside the supported source form fails compilation | `audit:Selector/code-health` |
+
+## Decision log
+
+No component-local future decision is recorded here. Accepted unimplemented work
+is owned by `spec:AST-004`.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not copy the full prop reference, examples, current audit score,
+family proposals, or future implementation steps. Those remain with their
+existing owners.