Skip to content

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

TypeScript

spec(AST-094): a thumb that sets a value takes no wheel or trackpad scroll (FR43) (#8905)

Christopher Chedeaubea4846f05a0
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index 570c14dd17..88767807cd 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -545,8 +545,48 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
row (`spec:AST-057` AR2, DEC-7); a
pinch under a pen; the screen-edge pan under a mouse, a trackpad, or a pen;
and the 44 px coarse-pointer touch target, which stays coarse-only and never overlaps a
- neighbor's target. On the web, a pan also
- takes wheel and trackpad scrolling; a pinch takes a ctrl-wheel; one shared
+ neighbor's target. On the web, a pan takes a trackpad's two-finger scroll
+ where its record allows it, and never a mouse wheel's notches. A scroll is a
+ trackpad's only when it carries Chromium's and WebKit's trackpad signature:
+ pixel deltas whose `wheelDelta` is three times the delta, with no whole tick
+ (a `wheelDelta` that is a multiple of 120 over a delta that is a multiple of
+ 40 px) and no accelerated-mouse remainder (a fractional part under 0.01 px).
+ Any other scroll, Shift+wheel and a tilt wheel included, is a mouse wheel's,
+ and a mouse wheel scrolls what is under it. A thumb that sets a value, a
+ slider's or a switch's where it pans, takes neither, so a scroll over it goes
+ to the scroll under it (DEC-23). The web reports no trackpad contact or
+ phase, so one splitter reads every trackpad stream (DEC-24): while the
+ fingers move, a pause of 180 ms on a vertical pan or 220 ms on a horizontal
+ one ends the gesture; the fingers' lift is read at the fourth or later delta
+ of a shrinking run, once the run has lost a fifth of its size; momentum after
+ the lift never moves a surface or continues a gesture; and during momentum a
+ reversal, a delta that rises against the decay, or a 50 ms gap starts a new
+ gesture without a pointer move. While the splitter has not yet decided
+ between a lift and fingers still moving, the surface keeps moving at the
+ fingers' last speed, never farther than that speed carries it over the held
+ deltas; a lift then continues without a stop, and fingers that keep moving
+ take up the difference. A pan released at the lift is stamped at the
+ fingers' last move, so the release keeps their velocity (FR36); a pan whose
+ stream stops releases still. A pinch takes a ctrl-wheel, and a pinch and a
+ mouse-wheel pan end 100 ms after their last event. A BottomSheet's pull
+ follows a trackpad as it follows a finger: a sheet a swipe cannot close
+ (`purpose` `form` or `required`) stretches past its resting place on FR3's
+ rubber band for a finger and a trackpad alike, the same travel giving the
+ same stretch, a trackpad's pull reaching no farther than the sheet's height,
+ and springs back at the release; an `info` sheet closes on a flick or past
+ its close distance and otherwise springs back (FR36, FR37); a mouse wheel
+ never moves a sheet. A pager follows a trackpad swipe, never more than one
+ page from where the swipe began, rubber-banded at its first and last page; it
+ commits past half a page or on a flick, never on a speed spike that moved it
+ less than a tenth of a page, and a swipe that lands during a settle starts
+ from that settle's page, so back-to-back swipes page on. A swipe row follows
+ a trackpad swipe from its first event past its 8 px start and settles at the
+ release to the nearest detent by position and velocity, and a long fast swipe
+ fires the outermost action where `spec:AST-057` allows a full swipe; within
+ one gesture an open row only closes, never passing rest to its other side.
+ Every followed trackpad pan runs one shared path (the splitter, the pan, the
+ snap-point drag and the animator), and a component declares only its detents
+ and actions, a row's being `spec:AST-057`'s. One shared
context request answers a finger's or a pen's long press, a right click, and
Shift+F10; the
press model has a fine-pointer profile with no delay (FR11); and with a
@@ -562,7 +602,9 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
- Supported engines: Astryx's supported browsers (`spec:AST-013`) with touch
input, on iOS and Android, and, for FR43, desktop browsers with a mouse, a
- trackpad, or a pen. UIKit on the reference release is the parity
+ trackpad, or a pen. A trackpad drives a pan only in a browser that reports
+ `wheelDelta` (Chromium and WebKit); elsewhere every scroll counts as a mouse
+ wheel's (FR43). UIKit on the reference release is the parity
reference, not a support floor; an older iOS Safari gets the same behavior
wherever its engine supports it, and Android Chrome gets the same behavior.
This amends `spec:AST-013` FR3 with an explicit Android Chrome support row
@@ -609,8 +651,15 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
FR7, FR9, FR11) follow FR26–FR30, FR33, and FR11's profiles under every
primary pointer; its mouse rules (the mouse halves of FR1–FR3) and its
non-gesture rules stay in the module.
-- `spec:AST-057`: a trackpad's horizontal scroll swipes a row (DEC-7); a
- mouse drag never does.
+- `spec:AST-057`: a trackpad's horizontal scroll swipes a row (DEC-7),
+ following the fingers and settling to the nearest detent (FR43); a mouse
+ drag and a mouse wheel never do.
+- `component:BottomSheet`: a `form` or `required` sheet rubber-bands past its
+ resting place under a finger as under a trackpad (FR3, FR43), with the same
+ stretch for the same travel; a mouse wheel scrolls its content and never
+ moves it. Implementation gap: a finger drags it one for one below rest.
+- The shared pager (Carousel's paging presentation, Lightbox's viewer): a
+ trackpad swipe follows FR43's pager rule.
- `architecture:react-component-runtime` INV13: gestures attach for every
pointer, within FR24's listener budget.
- `design:user-states` DR1, DR3 and `family:buttons`: press timing follows
@@ -672,7 +721,8 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
| FR36–FR40 | Release tests on synthetic touch streams with explicit timestamps, per use | below and past each commit point; a flick that projects past it; a slow drag past it; a release moving back; Reduce Motion; keyboard and mouse paths | a decision that changes mid-settle, a release moving back that commits, a settle that does not start at the release velocity, or an action with no keyboard or mouse path fails |
| FR41 | Browser tests with real touch input (`spec:AST-013` FR10) | a tap; a long press on a ContextMenu trigger, a DropdownMenu trigger the caller renders, a row with a context menu, and a slider thumb; a long press on a checkbox row's label and on plain text; a cancelled press; mouse and keyboard selection; a pen long press; a mouse long press, which makes no context request | a tap that selects, a hold with an action that starts a selection or callout, a label or plain text whose long press does not select natively, a suppression that outlives the press, or a change to native selection elsewhere or to mouse, keyboard, or assistive-technology selection fails |
| FR42 | Default-theme geometry tests under a coarse and a fine pointer, and hit-testing between adjacent targets | every component at phone width with a finger and with a mouse; a dense toolbar; a chip and its remove button; a Switch beside a label link | a default-theme box that grows under touch or at phone width other than with its text, or, where no component or module record sets the hit area, a touch target under 44 px where neighbors allow it or a hit area that overlaps a neighbor's target, fails |
-| FR43 | Browser tests with a mouse, a trackpad, a pen, a finger, and the keyboard, and resource counts | a pan by drag and by wheel; a ctrl-wheel pinch; a long press, a right click, and Shift+F10; a mouse press; a handle drag; a row swipe with a mouse and a trackpad; a component with no gesture | a gesture missing under a mouse or pen, a mouse-drag swipe action, a pen pinch, an edge pan under a mouse, a trackpad, or a pen, a press delay under a fine pointer, an idle listener in a component with no gesture, or added stylesheet bytes, fails |
+| FR43 | Browser tests with a mouse, a trackpad, a pen, a finger, and the keyboard, and resource counts | a pan by drag and by wheel; a slider's thumb under a wheel and a trackpad scroll; a ctrl-wheel pinch; a long press, a right click, and Shift+F10; a mouse press; a handle drag; a row swipe with a mouse and a trackpad; a component with no gesture | a gesture missing under a mouse or pen, a mouse-drag swipe action, a pen pinch, an edge pan under a mouse, a trackpad, or a pen, a press delay under a fine pointer, a wheel or trackpad scroll that changes a thumb's value or does not reach the scroll under it, an idle listener in a component with no gesture, or added stylesheet bytes, fails |
+| FR43 trackpad | Unit tests on timed wheel streams; WebKit browser tests with trackpad streams (Chromium's driver wheels read as a mouse wheel) | a form and a required sheet pulled 30 to 240 px by a finger and by a trackpad; mouse lines, notches, ticks and accelerated deltas over a sheet, a pager and a row; ten swipes each starting mid-momentum, ten whose momentum ends, and a slow drag with 150 ms pauses; a trackpad flick and a slow stopped drag on an info sheet; a fling, a slow 60 px swipe, a 42 px spike and back-to-back swipes on a pager; a row opened and swiped back within one gesture, and a long fast swipe; a pinch and a mouse-wheel pan ending | a trackpad stretch that differs from a finger's for the same travel (120 px gives 54 px on the reference sheet), a mouse wheel that moves a sheet, a pager or a row, splitter counts other than ten, ten and one, momentum that moves a surface, a flick released with no velocity, a pager that travels past one page or pages on a spike, an info sheet a flick leaves open or a slow stopped drag closes, an open row that reveals its other side within one gesture, or a pinch or mouse-wheel pan that ends after 100 ms fails |
| all | iOS simulator: the UIKit reference capture and the same gesture in Safari; real iOS Safari and Android Chrome devices | per component | an unmatched curve or timing is a parity defect |
## Decision log
@@ -853,6 +903,38 @@ internal" for exactly these three knobs, and DEC-1's and DEC-3's per-role
retuning, which a theme does through the knobs; DEC-11's rejected alternative, public
per-component roles, stays rejected.
+### DEC-24 — A pan follows a trackpad, never a mouse wheel, and reads the trackpad's phases itself
+
+**Reference:** `spec:AST-094/DEC-24`
+**Decider:** `cixzhang`, `2026-10-31`
+
+A trackpad's two-finger scroll is direct manipulation, as a finger is, so a
+pan follows it, and a finger and a trackpad share a surface's rubber band and
+release. A mouse wheel's notches are a scrolling control, and a few quick
+notches never move or close a sheet, so a pan takes none, and a scroll without
+the trackpad signature counts as a wheel's. The web reports no trackpad
+contact, phase or momentum, and a timeout alone releases under resting
+fingers, carries momentum into the surface and merges the next swipe, so one
+splitter infers the lift and the gesture's bounds for every pan. A row follows
+the fingers, as a mail list's row does. This narrows DEC-21's wheel and
+trackpad mapping for a pan.
+
+Rejected: a mouse wheel driving a pan; a discrete step per trackpad swipe for rows and paging; a longer end timeout instead of the splitter.
+
+### DEC-23 — A thumb that sets a value takes no wheel
+
+**Reference:** `spec:AST-094/DEC-23`
+**Decider:** `vjeux`, `2026-10-29`
+
+A consistency decision: a thumb that sets a value, a slider's or a switch's
+where it pans, takes no wheel or trackpad scroll, so a scroll over it goes to
+the scroll under it and never changes the value (FR43). Touch work keeps
+released mouse behavior (`spec:AST-017` FR59, FR41), and a native range input
+ignores the wheel (DEC-1). This narrows DEC-21's wheel and trackpad mapping
+for a pan.
+
+Rejected: the thumb's pan taking wheel and trackpad scrolling, as other pans do.
+
### DEC-21 — Gestures work on the web, not only under a finger
**Reference:** `spec:AST-094/DEC-21`