Skip to content

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

TypeScript

spec(Slider): onChangeEnd reports the value the owner renders (#7639)

Cindy Zhangfbc03f7b71eb
diff --git a/packages/core/src/Slider/Slider.spec.md b/packages/core/src/Slider/Slider.spec.md
index 44b417df93..acc3f617ab 100644
--- a/packages/core/src/Slider/Slider.spec.md
+++ b/packages/core/src/Slider/Slider.spec.md
@@ -34,13 +34,20 @@ an additive target for the interactive control surface.
## Compatibility and migration
-- Released default preserved: `yes`
+- Released default preserved: `no` — FR5 changes the released `onChangeEnd`
+ payload; every other released default is unchanged
- Compatibility class: additive target and state reflection; default styling,
DOM semantics, and public props remain unchanged, and the one keyboard change
AR1 names — the horizontal arrows follow the track's direction under RTL —
ships as a behavior fix
+- `onChangeEnd` payload (FR5): a new contract decision (`spec:AST-017/FR33`),
+ not a correction. Released victim: an owner that moves `value` only from
+ `onChangeEnd`, with no `onChange`, moves by keyboard today and does not under
+ FR5, so the change is breaking (`spec:AST-017/FR1`) and ships as
+ `[breaking]` in a declared minor (`spec:AST-017/FR31`).
- Controlled/uncontrolled behavior: unchanged; Slider remains controlled
-- Migration decision: none
+- Migration decision: an owner that moves `value` only from `onChangeEnd`
+ moves it from `onChange` instead (FR5)
Consumer migration instructions belong in consumer docs and release notes.
@@ -64,18 +71,20 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-The record adds one public theming target and names the keyboard model (AR1)
-without adding or changing a component prop or value domain. Consumer props,
+The record adds one public theming target, names the keyboard model (AR1), and
+states which value `onChangeEnd` carries (FR5) without adding or changing a
+component prop or value domain. Consumer props,
modes, states, and usage remain documented in `Slider.doc.mjs`.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Review state |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
-| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
-| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively. | Current source, public docs, and #6224 | Approved additive target contract |
-| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target. | Current source and public docs | Verified current asymmetry; not ratified as policy |
-| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip. | Current source and focused tests | Verified composition boundary |
+| ID | Candidate invariant | Basis | Review state |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | The current render places a filled range, one or two thumbs, and optional tick marks over the background track. | Current source, docs, and focused tests | Verified current behavior; no new behavior decided |
+| FR2 | `Slider`, `Interactive control`, `Track`, and `Thumb` carry the `slider`, `slider-control`, `slider-track`, and `slider-thumb` targets respectively. | Current source, public docs, and DEC-1 | Approved additive target contract |
+| FR3 | Filled range, tick marks, mark labels, and adjacent text value display are stable rendered parts without their own current Slider target. | Current source and public docs | Verified current asymmetry; not ratified as policy |
+| FR4 | Label and status presentation continue to use Field and FieldStatus; value tooltips continue to use Tooltip. | Current source and focused tests | Verified composition boundary |
+| FR5 | `onChangeEnd` fires once when an interaction ends — a pointer drag or track press is released or cancelled, or a keyboard step (arrow, Page, Home, End) completes — and carries the value the owner renders after its synchronous response to that interaction's `onChange` calls, including any clamp, snap, or rejection; it never carries a value Slider emitted that the owner did not render. A range reports both values the same way. | Maintainer decision (DEC-3) | Approved |
### Observed current target asymmetry
@@ -106,6 +115,8 @@ either component's remaining target shape.
- ORD1: an arrow or Page key result snaps to the nearest step, then clamps to
the bounds; Home and End go to `min` and `max` (AR1).
+- ORD2: within one interaction, Slider calls `onChange`, the owner responds and
+ renders, then `onChangeEnd` reports the rendered value (FR5).
- The anatomy decision (DEC-1) introduces no value, snapping, geometry,
interaction, or styling precedence rule of its own.
@@ -214,14 +225,15 @@ separately listed value tooltip retains Tooltip's target.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1 | `Slider.test.tsx` structure, range, and marks suites | Single, range, horizontal, vertical, marks | Removing or misaligning stable parts breaks existing role, position, or mark assertions. | `audit:Slider/anatomy` |
-| AR1 | Slider accessibility contract (`internal/a11y-spec`, pending) bound to Slider, in jsdom and Chromium; `Slider.test.tsx` keyboard suites, including "follows the mirrored track under RTL: ArrowLeft increases, ArrowRight decreases, Up/Down unchanged" and "keeps ArrowLeft decreasing on a vertical track under RTL"; the Page, Home/End and Up/Down cases under the contract | Single and range; horizontal LTR and RTL; vertical; disabled; formatted value | A thumb loses its role, name or value properties; an arrow, Page, Home or End key stops stepping or steps against the mirrored track; a range thumb crosses the other | `audit:Slider/accessibility` |
-| FR2 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium | Root, horizontal/vertical control, disabled control, track, and thumb | A target class/state is missing, undocumented, or placed outside its owning anatomy. | `audit:Slider/theming` |
-| FR3 | Source and consumer-doc review | Filled range, marks, labels, adjacent text value | A missing target is inaccurately documented as present or intentionally permanent. | `audit:Slider/theming` |
-| FR4 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only | Label, status, value tooltip, disabled reason | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage. | `audit:Slider/anatomy` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and four current local targets | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation. | `audit:Slider/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1 | `Slider.test.tsx` structure, range, and marks suites | Single, range, horizontal, vertical, marks | Removing or misaligning stable parts breaks existing role, position, or mark assertions. | `audit:Slider/anatomy` |
+| AR1 | Slider accessibility contract (`internal/a11y-spec`, pending) bound to Slider, in jsdom and Chromium; `Slider.test.tsx` keyboard suites, including "follows the mirrored track under RTL: ArrowLeft increases, ArrowRight decreases, Up/Down unchanged" and "keeps ArrowLeft decreasing on a vertical track under RTL"; the Page, Home/End and Up/Down cases under the contract | Single and range; horizontal LTR and RTL; vertical; disabled; formatted value | A thumb loses its role, name or value properties; an arrow, Page, Home or End key stops stepping or steps against the mirrored track; a range thumb crosses the other | `audit:Slider/accessibility` |
+| FR2 | `Slider.test.tsx`, `themingTargets.test.ts`, generated probe theme, and Chromium | Root, horizontal/vertical control, disabled control, track, and thumb | A target class/state is missing, undocumented, or placed outside its owning anatomy. | `audit:Slider/theming` |
+| FR3 | Source and consumer-doc review | Filled range, marks, labels, adjacent text value | A missing target is inaccurately documented as present or intentionally permanent. | `audit:Slider/theming` |
+| FR4 | Source inspection; focused tests cover label, status, and disabled-reason Tooltip only | Label, status, value tooltip, disabled reason | Shared composition or its accessible association disappears; value-tooltip composition still lacks focused coverage. | `audit:Slider/anatomy` |
+| FR5 | Pending: `Slider.test.tsx` change-end cases driven by an owner that renders, clamps, or rejects the emitted value (not yet in the suite) | Single and range; pointer release before and after the owner re-renders; each keyboard step | `onChangeEnd` reports a value the owner did not render, fires more than once per interaction, or skips a completed keyboard step | `audit:Slider/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and four current local targets | Missing, extra, prefixed, stale, or unclaimed mappings fail repository validation. | `audit:Slider/theming` |
The focused Slider suite asserts the `slider-control` target's orientation and
disabled state. Source/metadata guards cover all four target declarations. The
@@ -250,6 +262,15 @@ A thumb already plays the slider role as one composite control, so it carries th
Rejected: keeping ArrowRight as "increase" under RTL; a Tab stop or arrow model per range thumb that differs from the single thumb.
+### DEC-3 — `onChangeEnd` reports the value the owner renders
+
+**Reference:** `component:Slider/DEC-3`
+**Decider:** `cixzhang`, `2026-10-16`
+
+`onChangeEnd` marks the end of an interaction, so it reports what the slider shows when the interaction ends: the controlled value after the owner has answered `onChange`. An owner that clamps, snaps, or rejects a value therefore receives the value it kept, and the commit agrees with the thumb (FR5).
+
+Rejected: reporting the last value Slider emitted through `onChange`.
+
## Open questions
- **OQ1 — After a joint ProgressBar and Slider family audit, should any shared