An open source design system that's fully customizable and agent ready
Gestures
A gesture recognizer system with UIKit's semantics, for the touch
presentations of Astryx core components. Components import it from
../gestures. The package exports only createPanGesture and its types from
here.
UIKit is the reference throughout: the same recognizer states, the same
conflict rules, the same thresholds (from ../motion/uikit/gestures.ts, each
one sourced or marked as a guess awaiting measurement), and touch handling
that behaves like UIControl and UIScrollView. The rest of this page says
where the web forces a difference.
Using it from a component
import {useRef} from 'react';
import {PanGestureRecognizer, useGestureRecognizer} from '../gestures';
function Sheet() {
const ref = useRef<HTMLDivElement>(null);
useGestureRecognizer(
ref,
() => new PanGestureRecognizer({direction: 'down'}),
pan => {
// Runs inside the input event: write the transform, render nothing.
const element = ref.current;
if (element == null) return;
if (pan.state === 'ended') {
settle(element, pan.translation().y, pan.velocity().y);
} else {
element.style.transform = `translateY(${pan.translation().y}px)`;
}
},
);
return <div ref={ref}>…</div>;
}
- The recognizer is created once per component and keeps its identity, so
relationships set up when it is created (
requireToFail,recognizeSimultaneouslyWith) keep working. - The listener is read through a ref. Passing a new function on each render attaches nothing new, and a gesture never causes a React render.
- The recognizer attaches in a layout effect, so the element's
touch-actionis set before the browser can see a finger. It follows the element behind the ref: a node rendered after mount, or swapped behind the same ref (a trigger renderedasanother element), is attached at that commit. isEnabled: falsemid-gesture ends the gesture without calling the listener, since the handler that turned it off owns that end (no consumer callback from an Effect). A handler that wants UIKit's.cancelledcallsrecognizer.setEnabled(false)itself, which reports it at once. A recognizer that required it to fail (a single tap waiting on a double tap) resolves just after that render, and its listener reports as usual; so does one waiting on a recognizer whose node a render replaced. After unmount the listener hears nothing, not even the cancellation of a gesture the unmount ended.actionGroup: trueattaches the element as an action group, sibling actions a held pointer slides across (family:action-groupsFR5), served like every attachment, for every pointer. Changing it attaches the element again.usePressTracker(ref, options)gives an elementUIControltouch tracking (see below). It follows its element the same way, takesisBraking(by default the host's: a touch that stops a flick presses nothing), and keeps one tracker for the component's life: it readstrackingExpansion,highlightDelay,cancelTravelandquickTapFlash(and the ref itself) as they are now, so a change, even mid-press, never drops the press in progress. Unmounting or losing its element calls neitheronHighlightChangenoronControlEvent, and neither does disabling the control under a finger: the press ends, so the handler that disables it clears its own highlight.useFingerScroll(scroller), an internal piece of the touch module with no public API (not in the gestures barrel; a scroll-driven component imports its module, so it ships only where used), returns a reader,truewhile the scroller's scroll is a finger's: from a scroll while a finger that landed inside it is down, until itsscrollend(the momentum is still the finger's), or, where the browser fires none (mobile Safari before 26), until its scroll events go quiet. Pass a ref, or the document for the page.options.onEndruns each time such a scroll ends, once the reader saysfalse; unmounting does not call it. It is re-exported from@astryxdesign/core/internal/touchfor Lab components that watch a finger's scroll. Outside React,watchFingerScrolls(host, scroller)andisFingerScroll(host, scroller)fromfingerScroll.tsdo the same; that module adds passive scroll listeners only while something is watched.
Outside React, getGestureHost(document).attach(element, recognizer) does
the same and returns a detach function. getGestureHost(document).fingersDown()
is how many fingers are on the screen (the last touch event's touches,
wherever they landed): a recognizer that must not begin under a second
finger checks it in shouldBegin, so two fingers stay the browser's pinch.
Once a drag has claimed its finger, a second finger never breaks it.
Recognizers
| Recognizer | UIKit | Kind | Notes |
|---|---|---|---|
TapGestureRecognizer |
UITapGestureRecognizer |
discrete | numberOfTapsRequired, numberOfTouchesRequired; fails past 45 px of travel, on extra fingers, a hold over 1.5 s, a late or far next tap |
LongPressGestureRecognizer |
UILongPressGestureRecognizer |
continuous | minimumPressDuration 500 ms, allowableMovement 10 px (a distance, not per axis), numberOfTapsRequired; a zero duration begins on the touch itself (a selection tracker over a group of actions) |
PanGestureRecognizer |
UIPanGestureRecognizer |
continuous | min/max touches, direction (axis or one-way) with axisRatio, lockAxis, scrollEdge, firstMoveDecides; translation(), totalTranslation(), velocity(), scrollVelocity() |
SwipeGestureRecognizer |
UISwipeGestureRecognizer |
discrete | recognized during the motion; one or more directions, numberOfTouchesRequired; 50 px along, at most 50 px across, 500 ms |
PinchGestureRecognizer |
UIPinchGestureRecognizer |
continuous | scale (settable, to re-base it), velocity in scale per second, focalPoint() |
ScreenEdgePanGestureRecognizer |
UIScreenEdgePanGestureRecognizer |
continuous | edges: leading / trailing, resolved against the view's writing direction; attached to an edge zone the view lies within; fails as soon as the touch lands outside every requested edge band; a finger's only |
Each recognizer reports what it is in kind ('tap', 'longPress',
'pan', 'screenEdgePan', 'swipe', 'pinch'): code tells the family apart by it, never by instanceof
(architecture:react-component-runtime INV13).
A recognizer created with claimsTouches: false is a watcher (a tab bar
that minimizes while the page scrolls): it never claims, so its element gets
only passive listeners and a scroll never waits for it; it prevents no other
recognizer and none prevents it; and it follows a touch the browser takes
for a scroll to the lift. It adds nothing to the element's derived
touch-action.
Every recognizer also has UIKit's switches: isEnabled (use setEnabled;
turning it off mid-gesture cancels), cancelsTouchesInView (default true),
delaysTouchesBegan (default false), delaysTouchesEnded (default true),
allowedPointerTypes, and requiresExclusiveTouchType.
What the pan reports
The pan reads its numbers the way UIPanGestureRecognizer does, as measured
in the UIKit lab:
- It begins once the centroid has moved
hysteresis(10 px) along either axis, not as a distance. A function gives each press its own threshold, read from the press's first touch when it lands. translation()leaves out the travel the threshold took: a slow drag reads zero when the pan begins, and a step that overshoots keeps only the overshoot. A dragged surface does not jump.totalTranslation()is the movement since the fingers landed, for a surface that wants it.axisRatio(for a pan limited to an axis): the movement along the axis must exceedaxisRatiotimes the movement across it to begin; movement across that exceeds the movement along it fails the pan; in between it waits.velocity()is UIKit's own filter (see Velocity). The lift updates neither number; a finger that rested past the stillness interval releases at 0.
States
possible ─► began ─► changed* ─► ended | cancelled continuous
possible ─► ended discrete ("recognized")
possible ─► failed
Listeners (UIKit's target-action) run for began, changed, ended and
cancelled. addTransitionListener also reports failed and the return to
possible. A recognizer in a terminal state ignores the touches it still
holds and returns to possible when all of them have ended.
Conflicts: the arena
A new touch goes to every recognizer on its hit path, innermost first, and each one that accepts it tracks it until it ends. Then:
- Exclusivity. Two recognizers that share a touch are never active
together unless one allows it (
recognizeSimultaneouslyWith, or theshouldRecognizeSimultaneouslydelegate). The first to recognize fails the other possible ones. A recognizer that tries to begin while a conflicting one is active fails instead. When two qualify on the same input, the innermost one wins. - Failure requirements.
a.requireToFail(b)keepsainpossibleuntilbfails, then letsarecognize. Ifbrecognizes,afails. A recognizer that is not involved in the current touches holds nothing up. The delegatesshouldRequireFailureOfandshouldBeRequiredToFailByexpress the same thing dynamically. - Delegates.
shouldBegin,shouldReceiveTouch, andcanPrevent/canBePreventedon subclasses. The arena's plumbing (touch delivery, approved transitions, a pending recognition) isprotected: a subclass overrides thetouches*handlers and setsstate, and only the gesture system drives the rest.
// Single tap waits for the double tap to fail, as in UIKit.
single.requireToFail(double);
// Inner horizontal scroller yields to the back-swipe in the edge band only:
// the edge pan fails at touch-down anywhere else, so nothing waits.
innerPan.requireToFail(edgePan);
Touches in the view: createPressTracker
A pressable control's view-level touch handling, with UIControl
semantics, built by createPressTracker(options): a factory, as
architecture:react-component-runtime INV13 asks of the touch modules outside
the recognizer family (VelocityTracker is still a class, its one listed gap):
touchDown,touchDragInside/touchDragOutside,touchDragEnter/touchDragExit,touchUpInside/touchUpOutside,touchCancel.- "Inside" is the control's bounds expanded by
trackingExpansion, so a fingertip that slides a little off a button is still on it. - The highlight comes on in the same frame. Inside a scroller it waits
contentTouchDelay(UIScrollView.delaysContentTouches), so a flick paints nothing. A tap quicker than that delay shows the highlight at the lift forquickTapFlash. - A recognizer that takes the touch (
cancelsTouchesInView), or the browser taking it to scroll, cancels the press with no release. UIControl's iOS 6 rule applies: an ancestor's single-finger single tap does not beat the control's own action for a touch on it.vetoesAncestorRecognizerreplaces that rule (a slider vetoes a pan along its track).
The browser's click stays the control's activation, so keyboard and assistive-technology activation keep working.
Press profiles
PRESS_PROFILES holds the two ways UIKit tracks a press:
control(a button, a switch): the highlight comes on in the same frame outside a scroller, the finger is tracked 70 pt beyond the bounds, and the release takes the list's deselect clock, as every surface's does until a control runs its own (UIButton's 0.25 s);cell(a table or collection row): the highlight waits the content-touch delay inside a scroll view and comes on at once outside one (spec:AST-094FR11), travel past the pan hysteresis cancels the press for good, a quicker tap highlights at the lift straight into the release, and the release takes the list's deselect clock.
The document press controller (utils/pressFeedback.ts) writes
data-astryx-press for the presses it tracks, and the action-group tracker
(hooks/actionGroupTracker.ts) writes its groups' presses itself.
Rows and cards
A list of a thousand rows cannot pay for a hook and four listeners per row.
The document press controller (utils/pressFeedback.ts) presses the
innermost enabled [data-astryx-pressable] under each touch and paints it,
with no listener per row; a touch that brakes a scroll the finger set moving
presses nothing.
What the browser is told
Pens. A pen drives every recognizer and press tracker as a finger does: it pans, taps and long-presses; its hold, where the hold does something, keeps text unselected as a finger's does (FR41); its barrel button is a context click and starts no press; a pinch never mixes a pen with a finger; and the screen-edge pan, a finger's only, ignores it (FR43).
For every pointer. Recognizers and press trackers attach for a mouse, a pen and a finger alike (
spec:AST-094FR43, FR19). Where the primary pointer is coarse (TOUCH_QUERY,../utils/coarsePointer.ts), the host listens while something enabled could take a touch. Where it is fine, each element that uses a gesture keeps one passivepointerdownlistener (and a recognizer that claims a moving finger its blockingtouchmove, which FR24 counts outside that budget, FR19) and the page has none: a press on the element (a mouse's primary button, a pen, or a finger, whosepointerdowncomes before itstouchstart) adds the host's document and window listeners, and they go once that press's contacts end and the arena has decided them (a tap that waits on a double tap goes when that wait ends), or when the window blurs during it (FR24). After the last detach the host holds nothing: no listener, note, frame or timer. A press tracker created withkeepsTouchgets its blockingtouchmoveonly during such a press; where the pointer is coarse it keeps it, since Safari honours a blocking listener only when it was registered before the touch. A component that uses no gesture, and a disabled recognizer or consumer, registers nothing; after a consumer'sisEnabled()changes,host.update(element)re-syncs. The screen-edge pan stays off under a mouse, a trackpad and a pen (its recognizer allows touches only; it takes noallowedPointerTypes), and a pinch never mixes a pen with a finger (a recognizer takes one kind of pointer at a time) (FR43). A press tracker takes a mouse press as a press, with the fine-pointer profile: it paints at once, inside a scroller too, and the scroll brake is a finger's only (FR11, DEC-21). A right click, a pen's barrel button and a ctrl-click on macOS (its context click) start no press (isPrimaryClick,../utils/primaryClick.ts). The host follows the query (a tablet docking or undocking a mouse): turning fine cancels every touch in flight.perEventPointer, an option ofattach,attachConsumer,useGestureRecognizerandusePressTrackerfrom before FR43, is accepted and does nothing.touch-action. Each element gets the intersection of what its recognizers leave the browser, never wider than the element's owntouch-action(spec:AST-094FR18). Over an inline value the host writes what both allow, inline. Otherwise it marks the element (data-astryx-touch-action) under a rule in the first cascade layer, which any author rule outranks, and in the next frame writes inline what both allow where that is narrower than the author's rule. Detaching gives the element its own value back (opt out withmanageStyle: false):Recognizers on the element touch-actiontap, long press manipulationhorizontal pan or swipe pan-y pinch-zoomhorizontal edge pan on a strip within its band pan-y pinch-zoomvertical pan or swipe pan-x pinch-zoomone-way pan, pan with scrollEdgeleft as is ( auto)edge pan on a view wider than its band left as is ( auto)free pan pinch-zoompinch pan-x pan-ypinch together with a free pan nonea watcher ( claimsTouches: false), any directionleft as is ( auto)A one-way pan leaves the browser its own axis too: a toast dragged away from its edge scrolls the page. It claims its direction by cancelling
touchmovewhen it begins.pinch-zoomstays in the value unless a pinch recognizer is attached, so the page stays zoomable (WCAG 1.4.4). A long press with a hold also turns off the iOS callout and text selection on its element for its press; one at 0 ms (a touch-down detector) or givenselectionLock: nullleaves them to the browser.While a finger or a pen is down, the host turns them off too only where the hold does something (
spec:AST-094FR41): on the element of a recognizer created with aselectionLock(passlockSelection; a slider's thumb, a segmented control's or a switch's drag) that would take the touch (enabled, and accepting its pointer), restored when the contact ends. The host calls the recognizer's lock and never imports one, so a component with no such hold does not bundle it. A press tracker created with aselectionLock(a control whose own record defines a hold action, such as a stepper's hold-repeat) gets the same for each press. A press-tracked control or row whose hold does nothing, and the document press controller's surfaces (usePressFeedbackrows), keep the browser's long-press selection; a tap never selects. A non-text input under the finger inside such an element (a checkbox, a radio, a switch's input) is locked too: WebKit's own stylesheet makes every input selectable, which no ancestor's lock reaches. A text field keeps its selection, since a held finger places its caret. A finger or a pen takes the lock under any primary pointer, a touchscreen laptop and a desktop pen tablet included; a mouse never does (spec:AST-017FR59).A mouse or pen drag that a recognizer claims takes no new text selection and never clears the page's (
spec:AST-094FR41): from the claim until a task after the lift (the press's ownmouseupandclickcome in its task), the claiming elements and the document refuse a selection, and the selection the page had when the press began is put back over whatever the press or the drag made of it. The hold starts at the claim of whichever recognizer makes it, whatever its state: a swipe recognizes asendedwhile the button is still down, and a recognizer that waits on another's failure claims while stillpossible. A claim given back to the browser (that waiting recognizer failing or cancelled, with no other owner) lets the hold go, and the drag selects again. A drag that starts on selectable text (a character of text that allows a selection, or a text field) is not claimed: no recognizer recognizes with it while it is down, so it selects text, and content under a sheet's or a pager's pan stays selectable. A press a recognizer claims at its own pointerdown, before it moves, is no drag, and a tap claims only at its lift.Claiming. When a recognizer recognizes, it owns its touches. Each element with a recognizer that can claim a moving touch (a pan, a swipe, a long press that then drags, a pinch) has a non-passive
touchmovelistener that cancels the event only while one of its touches is owned. A touch nobody owns scrolls exactly as it would without the system. Taps claim only at the lift, and a recognizer that never claims (claimsTouchesfalse, such as a pull that only watches the scroll) never owns a touch, so an element with only those, or only a press consumer, gets no such listener (see the known limit below). A press tracker created withkeepsTouch: true(opt-in, for a continuous-tracking control such as a held stepper; never plain buttons, links, cards or list cells) gets one: once its press is delivered its finger's moves are cancelled, so the browser's pan never takes the held control (UIKit'stouchesShouldCancel(in:)is false for a tracking control). Its element also getstouch-action: manipulation, for every pointer, as a tap recognizer's does (spec:AST-094FR18), so taps in quick succession never zoom. Where the primary pointer is fine the blocking listener comes only with a press: the element keeps its onepointerdownlistener (FR24), the press adds thetouchmovebefore itstouchstart, and the kept finger's moves are cancelled from then on, as on a phone (FR11, DEC-21). A scroll that starts on such a control waits on the main thread; a move before the press is delivered still scrolls. The listener the host adds to a finger's target at touch-down, for a target that leaves the document mid-gesture, is passive too unless a recognizer on that touch can claim while it moves.Claim at the begin. A pan claims its touch only as it begins, at UIKit's 10 pt (
spec:AST-094FR19), before WebKit commits a slow drag to a scroll at 10–11 px; a drag the browser took first stays the browser's (FR14). Two exceptions: ascrollEdgepan cancels its finger's moves from the first one while every scroller under the finger is at its edge and the finger pulls away from it, the pan's own way (the browser could only rubber-band there); it still begins at 10 pt. AfirstMoveDecidespan, a toast's swipe (component:ToastFR4), holds its finger from a first move its own way and fails on any other first move. Each holds only while that is the one finger on the screen: with a second down anywhere, the moves stay the browser's, for its pinch (FR10). Measured in Mobile Safari (iOS 26.2):touchmovearrives from the first pixel; on a scrollable element WebKit commits to scrolling at 10 to 11 px (the last cancelabletouchmoveat 10 px), and cancelling everytouchmovefrom 8 px keeps the page still for the whole gesture. Underpan-yit scrolls only drags steeper than about 2:1 to 3:1, once the vertical travel reaches about 10 px. A pan that competes with native scrolling therefore decides at 10 px or less.The browser's claim.
pointercancelon a finger, or a scroll above the touch once the finger has travelled the slop (the browser starts a pan no earlier), means the browser took the finger; a scroll under a finger that has not moved (scrollIntoView, a transcript pinned to its end, scroll anchoring) is the page's own and leaves the press and its click alone. So does its firsttouchmovethat can no longer be cancelled, when the browser could pan along the finger's main axis. (Chromium also stops asking after one unconsumedtouchmovewhentouch-actionkeeps it from panning that way, as for a horizontal drag underpan-y; that is not a claim.) Possible recognizers that share it fail, active ones are cancelled, and the view's press is cancelled.Clicks. When a touch's gesture cancelled the view's touches, its
touchendis cancelled (no click and no compatibility mouse events) and the shared click guard (utils/clickGuard.ts, the menu press model's too) swallows the browser's next click, until the nextpointerdownor 400 ms. A click held back for a recognizer that may still recognize (a double tap between taps) is swallowed at once and replayed on the original target if the recognizer fails. Clicks withdetail === 0(keyboard, assistive technology, code) always pass.Context menus. A
contextmenuwhile a recognizer owns a touch is cancelled, so a long press never also opens the browser's menu.Focus. Losing window focus or hiding the page cancels every touch in flight, as UIKit does when the app resigns active.
Native scrolling
scrollEdge makes a pan share its axis with the native scrollers under the
finger. This is the sheet over its own list: the pan begins only if nothing
under the touch could scroll for that movement, the finger landed at the
edge and pulls away from it. The browser has not committed yet, so beginning
claims the touch and the content never moves. From the first move that
pulls away from such an edge the pan already holds the finger, so its moves
are cancelled before it begins and the page does not rubber-band either.
Who gets a drag is decided once, when it begins, as in UIKit: a drag that
began as a scroll stays the scroll view's for its whole length (it scrolls
to the top, then rubber-bands), and never changes hands midway
(spec:AST-094 FR14).
"Could scroll" follows the browser's own rules: touch-action between the
touch and each scroller, scroll chaining stopped by overscroll-behavior,
and RTL scrollLeft ranges, along the flat tree (content slotted into a
shadow-tree scroller scrolls with it, as the hit path does).
The input stream
The host listens through utils/inputStream.ts, which it shares with the
press feedback controller: one native listener per event type, on the
window's capture phase, fanned out to every subscriber in order. It runs
ahead of any document listener, so an app's window-capture
stopPropagation, or a document-capture stopImmediatePropagation
registered before core, no longer hides a touch from either, as UIKit's
recognizers see touches before views do. A recognizer that must claim
mid-gesture still needs the touch to reach its element, where its blocking
touchmove sits, below such a stop. The stream stays ahead of an app's own
window-capture listener only until a type's listener is re-added (a
passivity switch, or a subscription after its last subscriber left), which
appends it after the app's. A type's listener is passive unless a
subscriber cancels it: the host cancels touchend and contextmenu there
while a claiming participant is attached, never a touchstart or a
touchmove, and the click guard (../utils/clickGuard.ts) keeps a
cancelling click while it is armed, and from the menu press model's first
arm on. A layer's input hold (../Layer/inputHold.ts) cancels pointer and
mouse events, clicks, touchmove and touchend there while a layer is held,
never a touchstart. A blocking touchmove sits on a claiming
element and on a claimed touch's target, on the document while an element a
claiming recognizer lives in is moving (Touches on moving elements), or on
the window only while a page hold or a layer's input hold is held, so a page
of pressables blocks no scroll. The stream records the type of the latest
pointer event it delivers (getLastPointerType); the input hold reads it as
a layer opens.
Holding the page still
A scroll lock (useScrollLock) holds the page with
holdPageScroll(document, decide) from pageHold.ts, which returns the
release. It lives in its own module, so a page without a scroll
lock never ships it, and it imports nothing of the gesture host: it asks the
document's host whether a recognizer owns a touch only if a host exists, and
a document without one has no recognizer to own it. A hold reads the
primary pointer as it starts. Where it is coarse it listens at once, since
Safari honours a blocking listener only when it was registered before the
touch, and the first drag after an overlay opens is the one a hold is for;
where it is fine it registers no touch listener until the input stream's
pointerdown sees a touch or pen contact. Either way the hold follows the
pointer from then on. While any hold is active, and only
where the primary pointer is coarse, the input stream listens with a
non-passive touchmove; where the contact's touchstart came before its
pointerdown, the finger is named at its first move. Once per one-finger touch that no
recognizer owns, after the
finger clears a 5 px slop (under WebKit's 10–11 px scroll claim), it asks
decide(origin, dx, dy) whether that pan would scroll the page, origin
being the innermost node under the finger (the composed path's first node),
and cancels the touch's moves for its whole length if so. A second finger is
never cancelled, so pinch-zoom keeps working. With no hold, the listener is
gone and every touch scrolls as without the system.
Multiple fingers
A drag a recognizer has claimed keeps its finger: a second finger never
cancels or redirects it (spec:AST-094 FR10), as in UIKit, where a pan
ignores touches beyond its maximum. Before any claim, a second finger landing
anywhere (often on a plain row no recognizer is on) fails a pan limited to
one finger, so the two fingers zoom the page (WCAG 1.4.4) instead of the pan
claiming them midway.
Wheel and trackpad
A recognizer takes scroll input only where it allows that scroll type
(allowedScrollTypes, UIKit's allowedScrollTypesMask): continuous
for a trackpad's two-finger scroll or pinch, discrete for a mouse wheel's
notches. A pan follows a trackpad, never a mouse wheel (spec:AST-094 FR43,
DEC-24): it allows only continuous, and none by default, so it takes a
trackpad's scroll only where its owner allows it, its element then getting
the one wheel listener, and a mouse wheel's notches always scroll what is
under the pointer. A pinch allows both, for a ctrl-wheel from a trackpad or
a mouse. The screen-edge pan takes none, as it takes no mouse, trackpad or
pen (FR43). A control's thumb, a slider's or a switch's, tracks as a control,
not a pan, and takes no wheel, so a page scroll over it never changes its
value (DEC-23). The web reports no wheel phases or device, so the deltas
tell, and what they cannot tell apart reads as a mouse wheel: a line- or
page-mode delta; a scroll with Shift held (Shift+wheel); a pixel delta a hair
off a whole pixel (a mouse wheel on Windows); a scroll with no legacy wheelDelta (an engine that
sends none); a delta that is not a third of its legacy wheelDelta; or a 120
tick over a 40 px delta. A trackpad's precise deltas, a third of their legacy
wheelDelta (Chromium and WebKit), read as a trackpad.
A wheel gesture drives a pan as a contact moving with the content, along the
pan's own axis, and only once every scroller between the pointer and the
pan's element is at its edge that way, decided at the gesture's first wheel:
a wheel the pan does not take is never prevented. The pan's own element is
the exception on the axis that its derived touch-action keeps from the
browser: a pan on its own scroller takes that scroller's trackpad scroll, as
it takes a finger's pan there, and a scroller inside it still goes first. A watcher
(claimsTouches: false) never takes one, and a gesture whose first wheel
another handler already prevented, or that cannot be cancelled, stays the
page's. A scroll-edge pan (a pull to
refresh) takes one only if no scroller under the pointer could scroll for it,
its own scroll owner and the page included, as its finger's rule reads them
(spec:AST-094 FR19); touch-action narrows only a finger's pan, so a wheel
reads every scroller past it. A ctrl-wheel (a trackpad
pinch, or Control and a mouse wheel) drives a pinch, whose scale follows
exp(-deltaY / 100); a pinch takes it by default and ends 100 ms after its
last wheel. While the fingers move, a trackpad scroll ends 180 ms after its
last wheel vertically and 220 ms horizontally, whoever keeps it (a pan, a
scroller under the pointer, or the page), as a slow drag pauses between
wheels (DEC-24). A gesture's release is never stamped
later than an input that ends it sooner (FR16).
The web reports no trackpad contact or phase either, so one splitter reads
every trackpad stream (wheelSegmenter.ts, DEC-24): at the fourth or later
delta of a shrinking run, once the run has lost a fifth of its size, the
fingers lifted and momentum began. Until it decides,
the shrinking deltas wait, and a pan it follows moves on at the fingers' last
speed, never past what that speed projects. At the lift the pan keeps that
travel and lets go there, still moving at that speed, and the momentum after
it never moves it; when the fingers carry on instead, their moves absorb
what the pan showed past their travel, or short of it, so it never steps
back and ends on their travel. Fingers that stop release still, once the end
time passes. In momentum, a reversal, a delta that grows
against the decay, or a 50 ms pause starts a new gesture; a late, coalesced
trackpad wheel that continues the glide's deceleration (at or below the next
step, or near the sum of the next steps its stall spans) belongs to the same
flick. When the next wheel grows instead, it starts a new gesture with the late
wheel's travel. A finger, mouse or
pen that comes down ends it, and a wheel claim keeps the page's text
selection. A gesture a
recognizer took is latched to it, as a browser latches a scroller: while it
lasts, the host hears every step first, through the shared input stream's
window-capture listener, wherever it lands, so a pan whose element moves from
under a still pointer keeps the gesture. A page that loses focus or hides
cancels a trackpad pan a recognizer still drives, as it cancels every touch;
the rest of that stream is the page's. A ctrl-wheel pinch keeps its stream,
so the page never zooms for it, and a pan its lift released keeps its
momentum latched until the stream ends.
Time
Every input carries its own timestamp (event.timeStamp), and timers are
deadlines on that same clock. Before an input is processed, every timer due
by its timestamp runs first, at its own deadline. A long press therefore
begins at exactly touch-down + 500 ms even when the main thread was blocked
and the timer callback ran late. Tests drive the whole system with explicit
timestamps and no real time.
Velocity
VelocityTracker reports px per second, UIKit's unit, and is the one
velocity tracker every continuous recognizer uses
(architecture:interaction-modality INV10, spec:AST-100 FR1, FR2; no
alternative estimators). One filter, iOS's measured blend, updated on each
moved sample (a sample at the newest position is not motion):
- A pan's velocity is 0.2 times the newest interval's velocity plus 0.8 times the previous interval's (an interval runs from one moved sample to the next; the touch-down counts as the first). With one interval so far it is that interval, as UIKit reports it. It reproduces every value UIKit reported on six recorded touch streams, and like UIKit's it reacts a frame late to an acceleration.
- A scrolling surface's release (paging, a wheel) is 0.25 times the newest
pan value plus 0.75 times the previous one: a pan's
scrollVelocity(). Everything else readsvelocity().
A release reads 0 when the finger stayed still for longer than the stillness
interval (UIKIT_GESTURES.velocity.stillness) before lifting, the one
difference from iOS, whose filter never decays and so flings after a rest;
and 0 with fewer than two moved samples. The pan passes its lift's event time
to the tracker.
Times are the events' own. A finger the browser reports on both pointer and touch events is sampled from its pointer events alone (from its touch events once the browser cancels its pointer), so the two copies of one move never both count.
Haptics
playHaptic(kind) vibrates where navigator.vibrate exists, with one
pattern per UIKit feedback kind. iOS Safari has no vibration API. It plays a
light impact only when a real tap toggles an <input type="checkbox" switch>, and WebKit requires a trusted event for it. attachTapHaptic(label)
puts a hidden switch inside a label the control renders as its tap target,
so every real tap on it plays that impact; focus the activation gives the
switch goes straight back. A label tied to its control by for, or whose
control is itself a switch, gets no switch; a label wrapping its own control
gets one, which hands each tap on to that control. Nothing can play a haptic later
from script, so mid-drag haptics (detent snaps, picker ticks) are not
possible in iOS Safari.
Thresholds
All numbers live in ../motion/uikit/gestures.ts. Each one carries either
its source (Apple documentation, or a measurement: the recognizers' own
values read in a UIKit app on the iOS 26.2 simulator and confirmed with
touches, or Mobile Safari measured on the same simulator) or a guess
together with the measurement that will replace it. A unit test fails if an
entry has neither.
Touch presentation
Whether a component presents itself the touch (UIKit) way is answered once,
in ../utils/touchPresentation.ts:
- touch behaviours (UIKit springs and timings, the press model's touch
profiles) key on a coarse PRIMARY pointer (
TOUCH_QUERY); gestures themselves attach for every pointer (What the browser is told); - layout behaviours key on a compact viewport, below the theme's
mdwidth point (spec:AST-012FR9):COMPACT_QUERYspells the default points for a style, and behaviour reads the active theme's definition, so a theme that movesmdmoves compact with it; - a presentation that needs both, a sheet in place of a popover, asks for
both (
COMPACT_TOUCH_QUERY).
Styles switch on the same conditions by writing the same query as a StyleX
media key ('@media (pointer: coarse)', and the compact-touch query spelled
exactly as COMPACT_TOUCH_QUERY, which a test enforces), so the first paint
is right. Behaviour reads
useTouchPresentation() (SSR-safe), a component with no interaction to
infer from included (UIKit timings under a finger, its own motion under a
mouse), and a decision taken once reads readTouchPresentation().
Migrating a raw-touch drag
A component that listens to touches itself moves onto the recognizers this way:
- No window or document touch listeners: attach a recognizer with
useGestureRecognizerand readtranslation()andvelocity()per state. The host owns the page-wide listeners. - Pick the reading: a drag that coasts like a scroll view (a wheel, a
picker, a pager, a carousel) releases with the pan's
scrollVelocity(); anything else withvelocity(). A one-way drag setsdirection. The host derivestouch-action, so delete a hand-written one. - Native scrolling: a sheet over its own list uses
scrollEdge, notscrollTopchecks; who gets a drag is decided once, when it begins (spec:AST-094FR14). - A behavior that only watches the person's scrolling uses a watcher
(
claimsTouches: false) anduseFingerScroll. - A scroll lock holds the page with
holdPageScroll; nopreventDefaultof its own. - A drag limited to one finger sets
maximumNumberOfTouches: 1. Before it claims, a second finger fails it; once claimed, it keeps its finger (spec:AST-094FR10). Delete a local pinch yield. - The release hands
velocity()(px/s, event time) to the animator. Delete local estimators, sample buffers and time windows; a flick, fling or commit threshold stays in the component, compared against it. - A control whose hold acts (a slider's thumb, a stepper's hold-repeat)
passes
selectionLock: lockSelectionto its recognizer or press tracker (spec:AST-094FR41); content drags keep selection. - Presses use
usePressTracker;keepsTouch: trueonly for a control that tracks a held finger across its own area. - Unit tests drive the gesture harness (
__tests__/harness.ts) with timestamped touches; interaction specs use real touch input, never synthetic DOM events.
Known limits
- A scroll that begins on a recognizer waits for a busy main thread. In
Mobile Safari (iOS 26.2, measured), a vertical scroll that starts on an
element with a non-passive
touchmovelistener waits until the current JavaScript task ends; on a plain row, a pressable row or a tap-only element it starts at once (within 50 ms) even during a 500 ms task. Chromium documents the same rule for non-passive listeners. The listener stays because nothing else keeps UIKit's arbitration: with a passive listener, or one added duringtouchstart(which Safari ignores for that touch), Safari hands every diagonal drag on a swipe row to the list's scroll, 3:1 included. It is never worse than UIKit, where a busy main thread stalls every scroll. - Lists where every row has a horizontal recognizer (swipe actions on
every row of a mail list): every scroll start waits on the current task in
Safari. Keep list screens' tasks short. A native horizontal
scroll-snapreveal inside the row would never wait, but it tracks with scroll physics rather than UIKit's measured tracking spring; it is a possible opt-in, not the default. - Follow-up: Chromium keeps 3:1 to 1.5:1 drags as swipes even with a
passive listener (its
touch-actionfilter drops apan-yscroll that starts sideways), so a passive listener there would cost no parity. It waits on a measured run on Android before any engine-specific choice.
Touches on moving elements
iOS WebKit hit-tests an element that a compositor animation moves where
the animation started: it keeps the transform it resolved when the
animation went to the compositor, so event targets, elementFromPoint and
getBoundingClientRect stay there for the whole curve, though the inline
style holds the value the curve starts from and the computed style is live
(iOS 26.2, measured; Chromium and Linux WebKit hit what is drawn). A finger on a settling sheet
lands on whatever sat under the sheet's start (an upward release can hit
the scrim and close the sheet). UIKit keeps an interruptible animation
hit-testable where it is drawn (UIViewPropertyAnimator).
A style write on the element makes WebKit resolve the transform again, to
the value drawn at that moment, where it stays. So on iOS WebKit, at
touch-down, the host has every element the animator reports as moving
(motion/presentation.ts) resolved with one custom-property write, then
asks the engine what is under the finger: the touch goes to what is drawn
there, with z-order and pointer-events as the engine sees them. A touch
that a busy main thread hands the host late goes to what was drawn under the
finger when it landed (its timestamp): the host asks at the point that
content has moved to since. Press
trackers take their bounds from presentedRect, the reported box moved by
the motion since. A retargeted tap cancels the engine's click,
which would hit the start position, and clicks what it touched; the
click guard drops a late engine click, so the tap acts once. Safari honours a
blocking touchmove only where it was registered before the touch began,
on the engine's own target, which for a moving element is whatever sits
under its start: so while an element a claiming recognizer lives in is
moving, the document carries the blocking listener, and a scroll starting
anywhere waits on the main thread only for that long. Not covered:
scale and rotate (a zoom transition, a lifted preview is hit at its
unscaled box) and CSS transitions or animations the animator did not start.
This is an engine workaround (spec:AST-013 FR6). Its review condition:
re-measure on each iOS release, and remove the correction once iOS WebKit
hit-tests a compositor-moved element where it is drawn. Its regression
fixture is __tests__/presentedHitTesting.test.ts.
Where the web differs from UIKit
- Once a recognizer owns a touch, the browser cannot take the scroll back later in the same gesture. UIKit does not either: it decides between a sheet and its list when the drag begins.
- In Chromium a finger's first
touchmovearrives only after about 16 px. Movement below that comes from the finger's pointer events, but the browser's own decision to scroll happens at that firsttouchmove. Mobile Safari deliverstouchmovefrom the first pixel. - A tap that holds a plain
<button>for a second or more gets no click in Mobile Safari, while UIKit's tap allows 1.5 s. A tap recognizer on the element follows UIKit. - iOS Safari's own back swipe from the screen edge cannot be cancelled by the page. A leading-edge pan works where that swipe has no history to go back to.
translation()is in client CSS px. It is not converted into a rotated or scaled ancestor's coordinate space.- A replayed click is untrusted. Anything that needs real user activation inside the replay window (opening a file picker, for example) should not sit under a multi-tap recognizer.
Tests
__tests__/<Recognizer>.test.ts: each recognizer's state machine on synthetic touches with explicit timestamps.__tests__/arena*.test.ts: the conflict matrix, delivery to the view, click dispositions, cancellation, and multiple fingers.__tests__/GestureHost.test.ts: the DOM integration through real listeners in jsdom.__tests__/VelocityTracker.test.ts: the filter against the velocities UIKit reported on recorded touch streams, a steady speed and a hard acceleration.__tests__/haptics.test.ts: vibration patterns and the hidden switch.__tests__/importGraph.test.ts: a gesture-only component's static imports (useGestureRecognizer, the pan recognizers, the host) reach neither the press tracker nor haptics, which live behindusePressTrackerandattachTapHaptic/playHaptic.__tests__/useFingerScroll.test.tsx: a finger's scroll until itsscrollend, the page through the document, and the ref's node followed.__tests__/browser/: the browser proof on a phone-sized touch screen, in Chromium (CDP touches with timestamps) and WebKit (its own touch input), with mouse and pen input in a fine-pointer context, run bypnpm test:interaction gestures.interaction.browser.spec.tsand in CI's interaction proofs; where WebKit cannot launch on the host,internal/interaction-harness/scripts/webkit-container.mjsruns its project in the official Playwright image. The same fixture passed in Mobile Safari on the iOS 26.2 simulator: claims, click suppression, the scroll edge, pinch, and a long press at exactly 500 ms.