Release velocity system spec¶
{
"paths": [
"packages/core/src/BottomSheet/**",
"packages/core/src/Item/**",
"packages/core/src/Toast/**",
"packages/core/src/Swipe/**",
"packages/core/src/motion/uikit/swipeActions.ts"
]
}
Intent¶
When a person flicks a sheet, a toast, a row, a page, or a wheel and lifts their finger, every Core and Lab component of that kind reads the same speed from that motion, as iOS does, and a finger that stopped before lifting never counts as a flick. Components share the reading of a flick; each decides, by its own threshold, what that speed does. One release filter defines the speed every component reads; components decide only what a given velocity means for them.
Non-goals¶
- What a component does with the velocity: its flick threshold, its commit point, its projection, and its settle curve stay with the component and its record.
- Pinch scale velocity and scroll physics the browser owns.
- Public API: the velocity source, its filter values, and every threshold stay
internal (
spec:AST-002FR3), except the publicflickThresholdofspec:AST-107's snap-point drag (FR3). - Equivalent internal implementations remain valid when they satisfy this contract.
Requirements¶
- FR1 — One velocity per kind of surface. Every Core and Lab component that
reads the velocity of a pointer gesture reports it in CSS pixels per second
on each physical axis, and components of the same kind report the same
velocity for the same contact motion. Dragged surfaces are a sheet's drag, a
toast's swipe, a row swipe, a navigation pop, and interactive dismiss;
scrolling surfaces are paging and a wheel picker.
architecture:interaction-modalityINV10 owns the source in Core and how a Lab component matches it. - FR2 — A moving finger reads as on iOS; a still finger never flicks. The
velocity a component reads when the contact lifts is the velocity iOS
reports for the same motion: a pan's velocity for a dragged surface, and a
scroll view's release velocity for a scrolling surface. It is 0 when the
contact stayed still for longer than a fixed stillness interval before
lifting, the one case where it differs from iOS. Every component of a kind
reads the same release velocity and none reads another estimate. The stillness
interval is an internal tuning value; how the velocity is computed is
architecture:interaction-modalityINV10. - FR3 — Thresholds sit on top of the one velocity. A component's flick,
fling, or commit threshold compares the FR2 velocity, possibly with travel
or projection the component owns. Thresholds are per-component tuning that
stays internal (
spec:AST-002FR3), except the publicflickThresholda product passes tospec:AST-107's snap-point drag; a component never derives a second velocity to compare against. - FR4 — Event time for every pointer. The velocity follows the input events' own timestamps, so a handler that runs late does not change it, and the same motion gives the same velocity for touch, pen, and mouse pointers.
- FR5 — Direction follows the rendered direction. A flick toward the
logical end moves toward the logical end in both directions
(
design:bidirectionalityDR13); a component maps the physical velocity onto its logical axis from the rendered direction (architecture:internationalizationINV11).
Platform support¶
- Supported feature/engine floor: the package's supported browsers
(
spec:AST-013FR1, FR3); pointer events with event timestamps. - Unsupported behavior: a gesture with fewer than two moved samples has a release velocity of 0.
- Browser evidence: FR4 depends on the timestamps browsers put on pointer
events, so it needs real-browser evidence in Safari on iOS and Chrome on
Android (
spec:AST-013FR10); unit and component tests in Verification prove FR1–FR3 and FR5, and real-device feel for each component remains that component's evidence.
Current-state impact¶
- No velocity source exists in Core on
main. Its first landing meets FR1–FR5 andarchitecture:interaction-modalityINV10: iOS's blend with the FR2 stillness reset, and no selectable alternative filters. A Lab gesture matches it as INV10 describes. - BottomSheet's drag estimates velocity from a two-point window over its recent samples with event timestamps. Under FR1 and FR2 it reads the tracker.
- Item's row swipe compares a speed in pixels per millisecond timed with the handler's clock. Under FR1, FR2, and FR4 it reads the tracker in pixels per second with event timestamps, and keeps its own threshold (FR3).
- Toast's swipe averages travel over the whole drag timed with the wall clock. Under FR1, FR2, and FR4 it reads the tracker, and keeps its own threshold (FR3).
- A component that later reads gesture velocity, such as paging, a wheel picker, a navigation pop, or interactive dismiss, reads it from the tracker.
- Sparse move streams. The filter weighs the interval from touch-down to the first move like any other, as UIKit does. For a touch-down and three moves, that interval carries 0.6 of a scrolling surface's release. A stream whose first move comes late, with later moves on cadence, reads lower. Engines that stamp that move differently can read one flick on either side of a component's threshold.
Verification¶
| Contract | Verification | Representative states | Mutation or failure expectation |
|---|---|---|---|
| FR1 | One recorded sample stream read through two different components, plus a unit check | a sheet drag and a row swipe fed the same stream; a Lab gesture and a Core gesture fed the same stream; steady motion in x and y | Two components of the same kind reporting different velocities for the same stream, or a unit other than pixels per second |
| FR2 | Release velocity tests through a component over recorded iOS streams | recorded pan and scroll-view releases; acceleration before lift; a pause longer than the stillness interval before lift; one sample | A release that differs from the velocity iOS recorded for the same stream, or a non-zero release after a still pause |
| FR3 | Component tests at each threshold | a flick just under and just over a component's threshold; the same velocity across two components | Two components of the same kind reading different velocities for the same flick, or a threshold other than spec:AST-107's flickThreshold reachable from public API |
| FR4 | Unit tests with handler delay and per-pointer streams, plus real-browser pointer-event streams in Safari on iOS and Chrome on Android | delayed handlers with fixed event timestamps; touch, pen, and mouse streams | Velocity that changes with handler delay or pointer type |
| FR5 | Component tests in both directions | a flick toward the inline end in left-to-right and right-to-left | A flick toward the inline end treated as the opposite action in right-to-left |
A three-move flick whose first move comes late is informational in WebKit, not a required row. WebKit's injected touches carry their arrival time, so its release can fall on either side of a component's threshold.
Decision log¶
DEC-1 — One release filter that reads as iOS does, with a stillness reset; thresholds stay per component¶
Reference: spec:AST-100/DEC-1
Decider: cixzhang, 2026-10-24
Each component estimating velocity its own way reads the same flick at different speeds in components of the same kind, and counts a finger that paused before lifting as a flick in one place and not another. One release filter, with one source in Core and no copy in Lab, gives every component of a kind the same speed for the same motion. Reading a moving finger the way iOS does keeps flicks, paging, and dismissal near their thresholds where an iPhone puts them, and the stillness reset stops a resting finger from flinging, which is the one place the filter departs from iOS. What a speed means stays with each component as internal tuning, so components keep their feel without a second estimator.
Rejected: a fixed time window, which reads quick flicks much faster than iOS; iOS's blend with no stillness reset, which flings after a rest; and several selectable estimators or per-component filters, which reintroduce the disagreement this record removes.
DEC-2 — Release velocity stays cadence-dependent¶
Reference: spec:AST-100/DEC-2
Decider: Specs consistency ruling, 2026-11-08, applying DEC-1
Coalesced samples and time-weighted intervals would make release speed independent of how many moves an engine delivers, but they read quick flicks faster than iOS, which DEC-1's reason rejects; the filter stays as DEC-1 records it, and the engine split is the Sparse move streams gap.
Open questions¶
None.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx