Skip to content

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

TypeScript

spec(Slider): every pointer tracks from the grab point; a finger's release coasts (#9407)

Cindy Zhang8a552463756e
diff --git a/docs/specs/components/Slider/Slider.spec.md b/docs/specs/components/Slider/Slider.spec.md
index f23b712d76..d574648ea4 100644
--- a/docs/specs/components/Slider/Slider.spec.md
+++ b/docs/specs/components/Slider/Slider.spec.md
@@ -18,10 +18,11 @@ verified_by:
]
modules: []
families: []
-design_specs: []
-architecture: [architecture:component-theming-surface]
+design_specs: [design:reduced-motion, design:user-states]
+architecture:
+ [architecture:component-theming-surface, architecture:public-component-api]
contributing: []
-system_specs: []
+system_specs: [spec:AST-017, spec:AST-020, spec:AST-085, spec:AST-094]
---
# Slider component contract
@@ -35,7 +36,8 @@ an additive target for the interactive control surface.
## Compatibility and migration
- Released default preserved: `no` — FR5 changes the released `onChangeEnd`
- payload; every other released default is unchanged
+ payload and FR7 how every pointer drags a thumb and when `onChangeEnd` fires
+ after a finger's drag; 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 —
@@ -45,9 +47,24 @@ an additive target for the interactive control surface.
`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`).
+- Pointer tracking and the finger's coast (FR7): ships as a patch `[fix]`
+ by the owner's ruling on 2026-11-01 ("touch timing: I don't think these are
+ breaking. Can you name a desirable scenario?"). No desirable use depends on
+ the released drag: a press on a thumb that jumps the value is a defect; a
+ slow drag still ends at the lift, since only a flick coasts; and
+ `onChangeEnd` still carries the value the person sees settle (FR5). What
+ moves is when a touch flick's `onChangeEnd` fires, about 0.6 s after the
+ lift, once the coast settles; an owner that acts at the release keeps doing
+ so through `onChangeEnd` and receives it after the coast.
+- Implementation gap: FR7 is not shipped. Every pointer still moves the
+ thumb's center to the pointer on press, a finger has no 48 px target, lift,
+ or coast, `onChangeEnd` fires at the release, and the `springs.sliderRelease`
+ motion role is not yet in the motion role table.
- Controlled/uncontrolled behavior: unchanged; Slider remains controlled
- Migration decision: an owner that moves `value` only from `onChangeEnd`
- moves it from `onChange` instead (FR5)
+ moves it from `onChange` instead (FR5); an owner that needs the value at a
+ finger's lift reads the last `onChange` instead of waiting for
+ `onChangeEnd` (FR7)
Consumer migration instructions belong in consumer docs and release notes.
@@ -71,21 +88,23 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-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,
+The record adds one public theming target, names the keyboard model (AR1),
+states which value `onChangeEnd` carries and when (FR5), and states how a
+pointer drags a thumb (FR7), 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 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 |
-| FR6 | When both thumbs of a range share a value, a pointer press takes the thumb that can travel toward the pointer: a press on the track beside them takes the thumb on its side, and a press on the thumbs or on their shared value, such as its mark label, moves neither until the pointer moves, when the direction of that first movement picks the thumb, which takes the drag's focus, pressed state and value tooltip. Until then the upper thumb, drawn over the lower one, holds the press, its focus and its pressed state, so a press that never moves changes no value and leaves focus on the upper thumb. A drag that began on the shared thumbs and comes back past their value moves the other thumb: the dragged thumb stops against it and the other follows the pointer, so with both at 80 a drag to 95 and back to 50 ends at [50, 80]. | Current source and focused tests | Accepted 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 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 (after a finger's release, once its coast settles; FR7), 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 |
+| FR6 | When both thumbs of a range share a value, a pointer press takes the thumb that can travel toward the pointer: a press on the track beside them takes the thumb on its side, and a press on the thumbs or on their shared value, such as its mark label, moves neither until the pointer moves, when the direction of that first movement picks the thumb, which takes the drag's focus, pressed state and value tooltip. Until then the upper thumb, drawn over the lower one, holds the press, its focus and its pressed state, so a press that never moves changes no value and leaves focus on the upper thumb. A drag that began on the shared thumbs and comes back past their value moves the other thumb: the dragged thumb stops against it and the other follows the pointer, so with both at 80 a drag to 95 and back to 50 ends at [50, 80]. | Current source and focused tests | Accepted contract |
+| FR7 | Every pointer — a finger, a pen, or a mouse — drags a thumb by its travel. A press on a thumb changes no value. Once the pointer has moved `spec:AST-094/FR19`'s 10 px from where it pressed — a distance the pointer travels, not a zone around the thumb — the value moves by the pointer's further travel along the track over the track's length, from wherever the thumb was grabbed, so the thumb never jumps to the pointer; each move is written to the thumb with no component render (`spec:AST-094/FR9`). Between coincident range thumbs, FR6's first movement is the one that crosses the 10 px. A finger or a pen claims the drag only along the track, so a swipe across it scrolls the page; a mouse claims in any direction. Under a coarse primary pointer, after hydration (`spec:AST-094/FR13`), each thumb takes a finger or a pen through a 48 px touch target that grows toward a range's other thumb only to half the gap (`spec:AST-094/FR42`), and the held thumb lifts. After a finger lifts, the thumb coasts toward 0.4 of the release's momentum projection and settles on the `springs.sliderRelease` motion role, about 0.6 s, with `onChange` firing through the coast; the role is internal, with UISlider's measured value at `tempo` 1 and `'standard'`, and follows the theme's motion knobs (`spec:AST-094/FR4`). A mouse's or a pen's drag ends at its release, with no coast. A tap or a click on the track still sets the value: a finger's tap when it lifts, and a mouse press at once, where a primary click lands; a secondary click and a wheel or trackpad scroll change nothing (`spec:AST-094/FR43`). Under reduced motion the thumb does not lift, a tap's value applies at once, and the coast continues (`design:reduced-motion/DR2`). Implementation gap: not shipped yet (Compatibility and migration). | UIKit measurements and maintainer decision (DEC-4) | Approved |
### Observed current target asymmetry
@@ -116,8 +135,9 @@ 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).
+- ORD2: within one interaction, Slider calls `onChange`, through a finger's
+ coast (FR7), the owner responds and renders, then, once the thumb has
+ stopped, `onChangeEnd` reports the rendered value (FR5).
- The anatomy decision (DEC-1) introduces no value, snapping, geometry,
interaction, or styling precedence rule of its own.
@@ -235,6 +255,7 @@ separately listed value tooltip retains Tooltip's target.
| 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` |
| FR6 | `Slider.test.tsx` coincident range thumbs cases | Both thumbs at the minimum, the maximum and mid-range; a track press on each side; a press on the thumbs moved either way; a press that never moves, on the thumbs and on the mark label of their value; a drag that passes back over the shared value; right to left | A press or drag on coincident thumbs moves neither thumb, moves the thumb that cannot travel toward the pointer, keeps its focus, pressed state or tooltip on a thumb the drag has left, or leaves a press that never moves on the lower thumb | `audit:Slider/anatomy` |
+| FR7 | Pending: touch and fine-pointer browser tests in Chromium and WebKit (not yet in the suite) | Drag, threshold, grab offset, coast, slow release, track tap and swipe, mouse click, secondary click, wheel, close range thumbs, vertical, right to left, reduced motion | The thumb jumps to the pointer, a press moves the value, a swipe across is trapped, a drag waits on the owner's render, a mouse or pen release coasts, or `onChangeEnd` fires before a finger's coast stops | `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` |
The focused Slider suite asserts the `slider-control` target's orientation and
@@ -273,6 +294,15 @@ Rejected: keeping ArrowRight as "increase" under RTL; a Tab stop or arrow model
Rejected: reporting the last value Slider emitted through `onChange`.
+### DEC-4 — Every pointer tracks a thumb like UISlider
+
+**Reference:** `component:Slider/DEC-4`
+**Decider:** `cixzhang`, `2026-11-01`
+
+A thumb that jumps to the pointer changes the value on a press nobody meant as a drag, and one tracking model makes a Slider drag the same on every device, the deliberate consistency `spec:AST-017/DEC-25` allows. A finger adds UISlider's measured target, lift, and coast; the coast is a finger's alone, while a mouse's or a pen's drag ends at its release, and `onChangeEnd` waits for the coast to stop so the reported value is the one on screen (FR5). A tap or a click on the track sets the value, so a drag is not the only pointer path (WCAG 2.2 SC 2.5.7). No prop restores the released drag: the tracking is the same under every pointer, and the touch-only parts are touch-only behavior this record defines (`architecture:public-component-api/INV16`).
+
+Rejected: a mouse keeping the jump to the pointer, which gives one Slider two drags by device.
+
## Open questions
- **OQ1 — After a joint ProgressBar and Slider family audit, should any shared