Skip to content

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

TypeScript

spec(Selectors): define shared trigger hierarchy (#7386)

Ernest0eaae388d0b2
diff --git a/docs/specs/AST-079-selector-trigger-hierarchy/spec.md b/docs/specs/AST-079-selector-trigger-hierarchy/spec.md
new file mode 100644
index 0000000000..f875a8332a
--- /dev/null
+++ b/docs/specs/AST-079-selector-trigger-hierarchy/spec.md
@@ -0,0 +1,180 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-079
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+phase: proposed
+owners: [cixzhang]
+affects_architecture:
+ [architecture:public-component-api, architecture:component-theming-surface]
+affects_families: [family:input-fields]
+affects_contributing: []
+affects_consumer_docs: [Selector, MultiSelector, ComplexSelector]
+---
+
+# Shared selector trigger hierarchy system spec
+
+## Intent
+
+A builder can place `Selector`, `MultiSelector`, or `ComplexSelector` beside
+controls in a toolbar or navigation area without making one selector look like a
+form field while another uses a different hierarchy. `Selector` defines the
+`input`, `secondary`, and `ghost` trigger vocabulary in its current component
+contract. `MultiSelector` and `ComplexSelector` adopt the same values and roles,
+so all three built-in selector triggers communicate one caller choice while
+keeping their own value and popup behavior.
+
+## Ownership boundary
+
+`component:Selector` owns Selector's closed trigger values and DD1's durable
+relationship between its `secondary` trigger and adjacent secondary Buttons.
+This record owns adoption of that vocabulary by `MultiSelector` and
+`ComplexSelector`, plus the cross-component requirement that all three expose the
+same value names, defaults, and resting roles. Their component records keep each
+selector's selection, popup, and anatomy contracts.
+
+The released `Button` component owns its own variant map and secondary treatment;
+this record does not define Button behavior. `family:input-fields` owns the layout,
+status, and InputGroup rules projected by FR5 and FR6, but it does not add this
+visual axis to every input-family member. General control hierarchy, exact token
+selection, and component geometry remain outside this record.
+
+## Non-goals
+
+- Adding the trigger variants to another input-family member.
+- Replacing or weakening `component:Selector/DD1`.
+- Changing selection, search, popup, focus, keyboard, form, or accessibility
+ behavior.
+- Requiring identical geometry or state-by-state pixels across the three selector
+ components or between a selector and Button.
+- Prescribing exact theme tokens beyond the default resting roles in FR2.
+- Styling a caller-rendered trigger. A control supplied through `renderTrigger`
+ remains caller-owned under `spec:AST-055`.
+- Equivalent internal implementations remain valid when they satisfy this
+ contract.
+
+## Public concepts
+
+| Concept | Closed values | Meaning | Default | Owner | Stability |
+| ------------------------ | --------------------------------- | --------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------- | --------------------------------- |
+| built-in trigger variant | `input`, `secondary`, and `ghost` | Selects form-field, neutral medium-emphasis, or transparent low-emphasis trigger chrome | `input` | Selector meaning: `component:Selector`; adoption: AST-079 | `secondary` additive; others kept |
+
+## Requirements
+
+- **FR1 — Every selector trigger exposes the same closed vocabulary.** `Selector`
+ keeps the current `input`, `secondary`, and `ghost` values owned by its
+ component contract. `MultiSelector` and `ComplexSelector` MUST accept the same
+ three values for the built-in trigger's `variant`. Every public type, rendered
+ `data-variant` reflection, consumer theming declaration of the `variant`
+ visual-prop axis, and consumer document that exposes this axis MUST use those
+ same names. Other values are rejected by the public type.
+- **FR2 — The resting roles are shared.** At rest, `input` presents an opaque,
+ bordered form-field surface; `secondary` presents a borderless trigger with a
+ neutral fill and medium emphasis; and `ghost` presents a transparent,
+ lower-emphasis trigger. The three treatments MUST remain distinguishable at
+ rest. `component:Selector/DD1` additionally owns Selector's parity with an
+ adjacent secondary Button through its states. MultiSelector and ComplexSelector
+ MAY reuse their existing shared non-input hover, active, focus-visible,
+ disabled, and read-only treatments; this record does not require their state
+ pixels to be identical to Selector or Button. A theme MAY choose exact tokens
+ while preserving the resting roles. The Button component retains ownership of
+ its own secondary treatment.
+- **FR3 — Trigger paint does not change selector behavior.** Changing `variant`
+ MUST NOT change the selected value, option or child vocabulary, popup
+ presentation mode (`popover`, `bottom-sheet`, or `adaptive`) or overlay
+ semantics, keyboard model, focus ownership, form participation, accessible
+ name, role, or value semantics. Visual alignment MAY follow the chosen trigger
+ surface.
+- **FR4 — Adoption is compatible.** `input` remains the default for all three
+ components. Existing `input` and `ghost` callers keep their released behavior.
+ A MultiSelector or ComplexSelector caller opts into `secondary` explicitly; no
+ migration is required for an existing callsite. Selector compatibility remains
+ owned by its current component contract.
+- **FR5 — Family width and status rules still govern.** Under
+ `family:input-fields` FR1, standalone `Selector` MAY follow its displayed
+ content while `MultiSelector` and `ComplexSelector` MUST keep their available
+ inline size across value changes. Under family FR8, a requested `attached`
+ status on the borderless `secondary` or translucent `ghost` trigger resolves
+ to `detached`; status border and shadow remain limited to an eligible `input`
+ trigger.
+- **FR6 — InputGroup keeps the connected surface.** `Selector` and
+ `MultiSelector` MAY use `secondary` inside InputGroup. The trigger MAY keep its
+ neutral local fill, but it MUST adopt the group's resolved height, connected
+ edge radii, and focus stacking and MUST NOT paint a standalone outer border,
+ shadow, or status treatment. InputGroup remains the owner of the connected
+ outer geometry under `family:input-fields` FR3. `ComplexSelector` has no
+ InputGroup support.
+
+### Platform support
+
+- Supported feature/engine floor: every browser and renderer already supported
+ by the three components; the vocabulary adds no platform feature.
+- Unsupported behavior: none. A theme that changes exact paint still preserves
+ FR2's resting hierarchy and FR3's behavior.
+- Browser evidence: real-browser resting pixels beside secondary Buttons and
+ before/after inline-size measurements for value changes in MultiSelector and
+ ComplexSelector. Source inspection covers shared non-input state branches.
+ Conformance to FR6 requires focused DOM/style tests and rendered group geometry
+ for secondary Selector and MultiSelector before their implementation is
+ accepted.
+
+## Current-state impact
+
+- The current Selector contract and DD1 remain the authority for Selector's
+ values and local parity decision.
+- The draft MultiSelector and ComplexSelector component records cite
+ `spec:AST-079/DEC-1` for sibling adoption without making their unrelated claims
+ current.
+- MultiSelector and ComplexSelector consumer docs expose the shared three-value
+ vocabulary and explain when to choose each value; Selector keeps its current
+ documentation.
+- `family:input-fields` continues to own inline size, status placement, and
+ InputGroup surface rules; this record projects those rules onto the adopted
+ trigger value without changing them.
+- The Button component retains its released variant map and rendering. This
+ record defines secondary independently as a borderless, neutral-filled,
+ medium-emphasis selector trigger at rest.
+- Grouped secondary Selector and MultiSelector paths require the FR6 adaptation
+ and evidence before they conform; AST-079 does not treat current standalone
+ implementation evidence as proof of grouped geometry.
+- `architecture:public-component-api` continues to own additive API admission,
+ defaults, and compatibility. `architecture:component-theming-surface`
+ continues to own target and visual-prop propagation.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| FR1, FR4 | Public type, default-prop, `data-variant`, theme-metadata, and docs checks | all three components; omitted value; each explicit value | A component omits a value, changes its default, publishes a different value, or accepts an untyped value |
+| FR2 | Resting browser pixels and focused DOM/style tests | each variant at rest; default and themed paint | Secondary reads as a field or ghost trigger, ghost gains an opaque resting fill, or the three resting roles collapse |
+| FR3 | Source review of variant-specific branches plus existing interaction, form, popup, keyboard, focus, and accessibility suites | popover, bottom sheet, adaptive; editable, disabled, and read-only where supported | A visual variant changes selection or overlay semantics, form output, focus, naming, role, or value |
+| FR5 | Focused status tests and browser width measurements | attached request on each variant; short/long MultiSelector and ComplexSelector values | Non-input status attaches, input-only status paint leaks, or a multi-value/rich selector changes available inline size |
+| FR6 | Focused InputGroup DOM/style tests plus rendered group geometry | secondary Selector and MultiSelector as first, middle, and last group children | A trigger keeps standalone edges/status paint, loses group height/focus stacking, or the connected surface splits |
+
+## Decision log
+
+### DEC-1 — MultiSelector and ComplexSelector adopt Selector's trigger hierarchy
+
+**Reference:** `spec:AST-079/DEC-1`
+**Decider:** pending owner review
+
+Selector's current component contract already gives a caller three trigger roles.
+A caller choosing the same role on a multi-value or rich-content selector should
+not learn different names or receive a different default. MultiSelector and
+ComplexSelector therefore adopt Selector's `input`, `secondary`, and `ghost`
+vocabulary while keeping their separate interaction models and component-owned
+geometry.
+
+Rejected: sibling-specific value names or partial vocabularies, which make the
+same caller intent depend on selection model; a theme-only override, which cannot
+express caller intent through the public API; or promoting the draft sibling
+component records wholesale, which would approve unrelated claims.
+
+## Open questions
+
+None.
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.spec.md b/packages/core/src/ComplexSelector/ComplexSelector.spec.md
index 607833213c..547adc643d 100644
--- a/packages/core/src/ComplexSelector/ComplexSelector.spec.md
+++ b/packages/core/src/ComplexSelector/ComplexSelector.spec.md
@@ -23,7 +23,7 @@ design_specs: []
architecture:
[architecture:component-theming-surface, architecture:layer-runtime]
contributing: []
-system_specs: []
+system_specs: [spec:AST-079/DEC-1]
---
# ComplexSelector component contract
@@ -98,7 +98,8 @@ remain documented in `ComplexSelector.doc.mjs`.
### Representative states
-- Input and ghost variants use the same six-part anatomy and current targets.
+- Input, secondary, and ghost variants use the same six-part anatomy and current
+ targets.
- The start slot is absent when `startIcon` is omitted. When present, exactly
one of Icon-rendered start icon or Caller-rendered start content applies.
- The Popup remains mounted in both states: it is hidden while closed and shown
@@ -188,13 +189,17 @@ caller-owned ReactNode content.
## Decision log
-- **DEC-1 — Anchored mode through `renderTrigger`.** A picker anchored in a row the
- caller owns cannot host the Field shell or a nested button. The caller
- renders the control and spreads the given props; the component keeps owning
- open state through the existing `handleRef`/`onOpenChange`. Rejected: an
- `anchorRef` plus a controlled `isOpen`, per the rule already written on
- `ComplexSelectorHandle`. Proposed in a pull request; FR5 becomes policy only
- when an owner approves this record.
+- **DEC-1 — Anchored mode through `renderTrigger`.**
+
+ **Decider:** pending owner review
+
+ A picker anchored in a row the caller owns cannot host the Field shell or a
+ nested button. The caller renders the control and spreads the given props; the
+ component keeps owning open state through the existing
+ `handleRef`/`onOpenChange`.
+
+ Rejected: an `anchorRef` plus a controlled `isOpen`, per the rule already
+ written on `ComplexSelectorHandle`.
## Open questions
diff --git a/packages/core/src/MultiSelector/MultiSelector.spec.md b/packages/core/src/MultiSelector/MultiSelector.spec.md
index e134a36ee5..d7090ce694 100644
--- a/packages/core/src/MultiSelector/MultiSelector.spec.md
+++ b/packages/core/src/MultiSelector/MultiSelector.spec.md
@@ -31,7 +31,7 @@ architecture:
architecture:public-component-api,
]
contributing: []
-system_specs: [spec:AST-011/DEC-1]
+system_specs: [spec:AST-011/DEC-1, spec:AST-079/DEC-1]
---
# MultiSelector component contract