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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.