An open source design system that's fully customizable and agent ready
TypeScript
feat(core): touch-action derivation, native scroll probe, haptics and the gesture host (#8071)
Christopher Chedeau5cd7a15d4b4c
diff --git a/.changeset/gesture-browser-negotiation.md b/.changeset/gesture-browser-negotiation.mdnew file mode 100644index 0000000000..1be0500883--- /dev/null+++ b/.changeset/gesture-browser-negotiation.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[chore] Internal: touch-action derivation, the native scroll probe and haptics for the gesture system. Not exported from the package entry point; no component uses them yet.++@vjeuxdiff --git a/.changeset/gesture-host.md b/.changeset/gesture-host.mdnew file mode 100644index 0000000000..5b0b9fd7c2--- /dev/null+++ b/.changeset/gesture-host.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[chore] Internal: the gesture system's DOM host (claims, click suppression, the browser's takeover, the pointer behind a contact), serving a mouse, a pen and a finger alike, with no page listener while idle where the primary pointer is fine. Not exported from the package entry point; no component uses it yet.++@vjeuxdiff --git a/packages/core/src/gestures/GestureArena.ts b/packages/core/src/gestures/GestureArena.tsindex 3acc3edc83..409589f3c5 100644--- a/packages/core/src/gestures/GestureArena.ts+++ b/packages/core/src/gestures/GestureArena.ts@@ -262,6 +262,41 @@ export class GestureArena {});}+ /**+ * A contact began where nothing takes part (plain page content). It is+ * never tracked and stays the browser's; recognizers already tracking a+ * gesture hear of it, as of any touch off their hit path.+ */+ untrackedBegan(input: TouchBeganInput): void {+ if (!this.active.some(recognizer => recognizer.numberOfTouches > 0)) {+ return;+ }+ this.run(input.time, () => {+ const time = this.clampTime(input.time);+ const touch: GestureTouch = {+ id: input.id,+ pointerType: input.pointerType,+ phase: 'began',+ x: input.x,+ y: input.y,+ time,+ startX: input.x,+ startY: input.y,+ startTime: time,+ samples: [{x: input.x, y: input.y, time}],+ target: input.target,+ scroll: input.scroll ?? null,+ takenByBrowser: false,+ };+ const context = this.context();+ for (const recognizer of [...this.active]) {+ if (recognizer.numberOfTouches > 0) {+ recognizer.deliverBeganElsewhere([touch], context);+ }+ }+ });+ }+/** Contacts moved. */moved(inputs: ReadonlyArray<TouchInput>): void {if (inputs.length === 0) {diff --git a/packages/core/src/gestures/GestureHost.ts b/packages/core/src/gestures/GestureHost.tsnew file mode 100644index 0000000000..55e63f4c28--- /dev/null+++ b/packages/core/src/gestures/GestureHost.ts@@ -0,0 +1,2065 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file GestureHost.ts+ * @input DOM touch, pointer, click, contextmenu, scroll and focus events of+ * one document; elements with recognizers and consumers attached, and+ * consumer types found by attribute+ * @output Exports GestureHost (the DOM side of the gesture system),+ * getGestureHost (one host per document) and the delegated consumer type+ * @position Browser adapter of packages/core/src/gestures: turns real events+ * into GestureArena input, and carries out what the arena decides+ *+ * FOR EVERY POINTER+ *+ * - Recognizers and press consumers attach for a mouse, a pen and a finger+ * alike (`spec:AST-094` FR43, FR19). Where the primary pointer is coarse+ * the host listens on the page while something enabled could take a+ * touch. Where it is fine, each element with an enabled recognizer or+ * consumer keeps one passive `pointerdown` listener and the page has none:+ * a press on it (a mouse's primary button, a pen, or a finger, whose+ * `pointerdown` comes before its `touchstart`) installs the host's page+ * listeners, which go once that press's contacts end; the click listener+ * alone stays through the swallower's window, for the click a claimed lift+ * owes (FR21, FR24). An element whose recognizer claims a moving finger+ * keeps its blocking `touchmove` under every pointer, a listener FR24+ * counts apart.+ * - A right click, a pen's barrel button and a ctrl-click on macOS start no+ * press (primaryClick.ts).+ * - The host follows the primary pointer (a tablet docking a mouse): turning+ * fine with no press held removes the page listeners and cancels every+ * touch in flight.+ * - A delegated consumer type has no element to listen on: where the+ * primary pointer is fine, the document keeps one passive `pointerdown`+ * listener for every type, counted once per page (FR24).+ *+ * INPUT CHANNELS+ *+ * - Fingers begin and end with Touch Events: they are the only cancelable+ * channel (a pointer event's preventDefault cannot stop a scroll or a+ * click), they keep arriving after the browser takes a pan (which a scroll+ * handoff needs), and every event lists all the fingers at once. A+ * finger's movement comes from BOTH its `touchmove`s and its+ * `pointermove`s (paired at touchstart by target and position), the echo+ * of one in the other dropped: Chromium sends no `touchmove` until a+ * finger has travelled about 16 px, while a tap fails and a pan begins at+ * 10.+ * - A finger's events go to the element it landed on even after that+ * element leaves the document, and then never reach the document. Each+ * tracked finger's target therefore gets its own listeners, and a finger+ * the events say is no longer down is cancelled, so a re-rendered or+ * removed target never strands a gesture.+ * - Mice and pens come from Pointer Events, with coalesced samples for+ * velocity. A pen on an iPad also produces `stylus` touches; those are left+ * to the pointer path.+ * - `pointercancel` on a finger is the browser saying it took that finger+ * for its own pan or zoom; so is a `touchmove` that can no longer be+ * cancelled where `touch-action` let the browser pan, and a scroll above+ * the touch.+ *+ * WHAT THE BROWSER IS TOLD+ *+ * - Each element gets the `touch-action` its recognizers leave the browser+ * (touchAction.ts), set inline when they attach and restored when they+ * detach.+ * - Each element with a recognizer that can claim a touch while it moves (a+ * pan, a swipe, a long press that then drags, a pinch) gets a+ * NON-passive `touchmove` listener that cancels the event only while a+ * recognizer owns one of its touches (a pan claims when it begins, at+ * UIKit's 10 pt, `spec:AST-094` FR17). Nothing else is ever cancelled, so a+ * touch nobody claims scrolls exactly as it would without the system. The+ * known cost: a scroll that BEGINS on such an element waits for a busy main+ * thread (measured in iOS Safari; a passive listener would hand every+ * diagonal to the scroll instead). Elements whose recognizers only claim+ * at the lift (taps) and press consumers get no blocking listener, so a+ * scroll starting on them never waits.+ * - A lift whose click must not happen cancels its `touchend` (no click, no+ * compatibility mouse events) and arms a one-shot swallower for the next+ * trusted click; a click held for a recognizer that may still recognize is+ * replayed if they all fail. Keyboard and assistive-technology clicks+ * (`detail === 0`) always pass.+ * - A `contextmenu` while a recognizer owns a touch is cancelled, so a long+ * press never also opens the browser's menu.+ *+ * DELEGATED CONSUMERS. A consumer type registered with an attribute (a+ * pressable row) is found at touch-down by walking up from the touch target,+ * and an instance is created for that one touch: a list of a thousand rows+ * costs nothing until a finger lands on one.+ *+ * SSR-safe: nothing touches `window` or `document` until something attaches.+ *+ * SYNC: When modified, update GestureHost.test.ts and README.md.+ */++import {UIKIT_GESTURES} from '../motion/uikit/gestures';+import {+ browserClock,+ GestureArena,+ type ArenaBeganInput,+ type ClickDisposition,+ type GestureArenaOptions,+ type GestureClock,+} from './GestureArena';+import type {GestureRecognizer} from './GestureRecognizer';+import {HAPTIC_SWITCH_ATTRIBUTE} from './haptics';+import {isPrimaryClick} from '../utils/primaryClick';+import {createNativeScrollProbe, parentAcrossShadow} from './nativeScroll';+import {+ gestureHostStyle,+ type GestureHostStyle,+ holdSelectionStyle,+ intersectTouchAction,+} from './touchAction';+import {+ markTouchAction,+ TOUCH_ACTION_ATTRIBUTE,+ unmarkTouchAction,+} from './touchActionRule';+import type {ScreenEdgePanGestureRecognizer} from './ScreenEdgePanGestureRecognizer';+import type {+ GestureEnvironment,+ GestureTouch,+ PointerKind,+ TouchBeganInput,+ TouchConsumer,+ TouchInput,+ TouchSample,+} from './types';++interface Registration {+ readonly recognizers: GestureRecognizer[];+ consumer: TouchConsumer | null;+ touchMoveListener: EventListener | null;+ /**+ * Under `inputMode: 'pointer-events'`, the element's blocking `touchend`+ * listener: it cancels a claimed finger's lift (`spec:AST-094` FR21).+ */+ touchEndListener: EventListener | null;+ /** Inline values the host replaced, to restore on detach. */+ readonly savedStyle: Map<string, string>;+ /**+ * What the element's own stylesheet gives it, read in a frame for the+ * derived value the host marked then: `null` where the host's rule is in+ * force (the author sets nothing else); the host never allows more than+ * the author does. `null` before the read.+ */+ authorTouchAction: {derived: string; author: string | null} | null;+ manageStyle: boolean;+ /** An action group (`family:action-groups` FR5). */+ actionGroup: boolean;+}++export interface GestureHostOptions {+ /** The arena's clock; tests pass a manual one. */+ clock?: GestureClock;+ /**+ * Where fingers come from: Touch Events where the browser has them+ * (`auto`), or Pointer Events only.+ */+ inputMode?: 'auto' | 'pointer-events';+ /** Every recognizer transition, for debugging and tests. */+ onTransition?: GestureArenaOptions['onTransition'];+ /**+ * Whether the primary pointer is coarse (a phone, a tablet). Gestures+ * attach for every pointer (`spec:AST-094` FR43); where it is fine, an+ * element that uses a gesture keeps one passive `pointerdown` listener+ * (beside a claiming recognizer's blocking `touchmove`, FR19) and the+ * page's listeners last only a press (FR24).+ * @default `(pointer: coarse)` on the document's window+ */+ isPrimaryPointerCoarse?: () => boolean;+}++export interface AttachOptions {+ /**+ * Let the host set the element's styles: its `touch-action`, and the+ * selection and callout lock a hold that does something keeps while it is+ * held (`spec:AST-094` FR41). With false the caller keeps both.+ * @default true+ */+ manageStyle?: boolean;+ /**+ * The element is an action group, sibling actions a held pointer slides+ * across (`family:action-groups` FR5). It is served like every+ * attachment, for every pointer (`spec:AST-094` FR43). @default false+ */+ actionGroup?: boolean;+}++/**+ * A kind of view-level consumer found by attribute instead of attached to+ * each element.+ */+export interface DelegatedConsumerType {+ /** Marks an element as this kind of consumer. */+ readonly attribute: string;+ /**+ * The consumer for one contact on `element`, or null for none (a disabled+ * control). The innermost marked element decides, even with null: a press+ * on a disabled button does not light the row around it.+ */+ create(element: Element, pointerType: PointerKind): TouchConsumer | null;+}++const STYLE_PROPERTIES: Record<keyof GestureHostStyle, string> = {+ touchAction: 'touch-action',+ WebkitTouchCallout: '-webkit-touch-callout',+ WebkitUserSelect: '-webkit-user-select',+ userSelect: 'user-select',+};++/**+ * Whether a recognizer can take a touch while it moves, and so needs the+ * blocking `touchmove` listener that stops the browser's pan. A tap claims+ * only at the lift (it fails once the finger travels), so it needs none.+ */+function claimsWhileMoving(recognizer: GestureRecognizer): boolean {+ return recognizer.acceptsTouchInput && recognizer.kind !== 'tap';+}++/**+ * Run `task` in the next frame, before it paints: a read there styles what+ * the frame must style anyway, and its writes are what the frame shows.+ */+/**+ * A CSS-wide keyword, which names no touch-action of its own: the value in+ * force resolves it (`initial` and `unset` to `auto`, `inherit` to the+ * parent's).+ */+function isCssWideKeyword(value: string): boolean {+ return CSS_WIDE_KEYWORDS.has(value.trim().toLowerCase());+}++const CSS_WIDE_KEYWORDS: ReadonlySet<string> = new Set([+ 'initial',+ 'inherit',+ 'unset',+ 'revert',+ 'revert-layer',+]);++function inNextFrame(view: Window | null, task: () => void): void {+ if (view != null && typeof view.requestAnimationFrame === 'function') {+ view.requestAnimationFrame(task);+ } else {+ setTimeout(task, 0);+ }+}++const PASSIVE_CAPTURE = {capture: true, passive: true} as const;++/**+ * A screen-edge pan, told apart by its kind (architecture:react-component-runtime+ * INV13), so the host can report its layout changes without importing it.+ */+function asScreenEdgePan(+ recognizer: GestureRecognizer,+): ScreenEdgePanGestureRecognizer | null {+ return recognizer.kind === 'screenEdgePan'+ ? (recognizer as ScreenEdgePanGestureRecognizer)+ : null;+}++/** The inline properties a held press sets to none (holdSelectionStyle). */+const HOLD_SELECTION_PROPERTIES = [+ '-webkit-touch-callout',+ '-webkit-user-select',+ 'user-select',+] as const;++/** Elements a held press turned selection off on, and what to restore. */+const heldSelection = new WeakMap<+ HTMLElement,+ {+ count: number;+ saved: ReadonlyArray<{name: string; value: string; priority: string}>;+ }+>();+const ACTIVE_CAPTURE = {capture: true, passive: false} as const;++type StylusTouch = Touch & {touchType?: string};++interface PlacedContact {+ readonly x: number;+ readonly y: number;+ readonly target: unknown;+}++/** A touchstart and a pointerdown describe one finger: same target, same spot. */+function isSamePlace(a: PlacedContact, b: PlacedContact): boolean {+ return (+ a.target === b.target &&+ Math.abs(a.x - b.x) <= 1 &&+ Math.abs(a.y - b.y) <= 1+ );+}++function isPointerKind(type: string): type is PointerKind {+ return type === 'touch' || type === 'mouse' || type === 'pen';+}++/**+ * An event's time on the arena's clock (`performance.now()`). Some engines+ * and DOM emulators stamp events in epoch milliseconds instead.+ */+function eventTime(event: Event): number {+ const time = event.timeStamp;+ if (+ time > 1e12 &&+ typeof performance !== 'undefined' &&+ performance.timeOrigin > 0+ ) {+ return time - performance.timeOrigin;+ }+ return time;+}++/** A touch list as an array; a synthetic event may carry none. */+function touchesOf(list: TouchList | null | undefined): Touch[] {+ return list == null ? [] : Array.from(list);+}++export class GestureHost {+ readonly arena: GestureArena;+ private readonly doc: Document;+ private readonly registry = new Map<Element, Registration>();+ private readonly delegated = new Set<DelegatedConsumerType>();+ /** Touch.identifier → arena id, for live fingers. */+ private readonly touchIds = new Map<number, number>();+ /** Touch.identifier → the element the finger landed on. */+ private readonly touchTargets = new Map<number, EventTarget>();+ /** Finger targets with listeners of their own, and how many fingers each. */+ /**+ * Finger targets with listeners of their own: how many fingers each, and+ * how many of those a recognizer could claim while they move (only those+ * need the blocking `touchmove` listener).+ */+ private readonly watched = new Map<+ EventTarget,+ {count: number; blocking: number}+ >();+ /** Fingers whose target listener is the blocking one. */+ private readonly blockingFingers = new Set<number>();+ /** Touch events already handled (the document's and the target's listeners both see one). */+ private readonly processed = new WeakSet<Event>();+ /** pointerId → arena id, for live mouse and pen contacts. */+ private readonly pointerIds = new Map<number, number>();+ /** Elements whose caller touch-action waits for a read after paint. */+ private readonly pendingCallerReads = new Set<HTMLElement>();+ private isCallerReadScheduled = false;+ /**+ * The boxes the host watches for screen-edge pans (syncLayoutWatch): each+ * element with an enabled one, and the root for one whose band moves with+ * the viewport (spec:AST-094 FR18, FR19, DEC-22), and the one observer+ * that watches them.+ */+ private readonly layoutWatched = new Set<Element>();+ private layoutObserver: ResizeObserver | null = null;+ /** Fingers whose first uncancelable `touchmove` was already judged. */+ private readonly judgedUncancelable = new Set<number>();+ /**+ * A finger's pointerId → its arena id, once its pointerdown and its+ * touchstart are paired. Chromium sends no `touchmove` until a finger has+ * travelled its slop (about 16 px), but sends every `pointermove`, so the+ * finger's movement comes from both channels; and its `pointercancel` is+ * the browser's claim of exactly that finger.+ */+ private readonly fingerPointers = new Map<number, number>();+ /** Finger pointerdowns still waiting for their touchstart. */+ private readonly pendingPointers = new Map<number, PlacedContact>();+ /**+ * Under `inputMode: 'pointer-events'`, where claimed fingers lifted: the+ * `touchend` that follows their `pointerup` is cancelled (FR21).+ */+ private readonly claimedLifts: PlacedContact[] = [];+ /** Fingers still waiting for their pointerdown, by arena id. */+ private readonly unpairedTouches = new Map<number, PlacedContact>();+ /** The last position fed per contact, so one channel's echo is dropped. */+ /** The elements each held contact turned selection off on. */+ private readonly heldSelectionBy = new Map<number, HTMLElement[]>();+ private readonly isPrimaryPointerCoarse: () => boolean;+ private readonly coarseQuery: MediaQueryList | null;+ private isWatchingPointer = false;+ private readonly onPointerKindChange = (): void => this.refreshAll();+ private readonly lastFed = new Map<number, TouchSample>();+ /** When a finger was last down or lifted, and where it landed. */+ private lastTouch: {readonly target: Node; readonly time: number} | null =+ null;+ /** The last scroll a finger drove, and when. */+ /** Scrollers a recognizer is scrolling itself this frame (ownScroll). */+ private readonly ownedScrolls = new Set<Node>();+ private lastScroll: {readonly scroller: Node; readonly time: number} | null =+ null;+ private nextId = 1;+ private isInstalled = false;+ private readonly inputMode: 'auto' | 'pointer-events';+ private usesTouchEvents = true;+ private swallowDeadline = Number.NEGATIVE_INFINITY;+ /**+ * Where the primary pointer is fine: what listens for a press itself (the+ * elements that use a gesture, and the document for delegated consumers),+ * with its removal; whether a press one armed is held, the page's+ * listeners lasting that long; and the pending removal of the click+ * listener a released press kept (FR21, FR24).+ */+ private readonly armed = new Map<EventTarget, () => void>();+ private isArmedPress = false;+ private clickRemoval: ReturnType<typeof setTimeout> | null = null;++ constructor(doc: Document, options: GestureHostOptions = {}) {+ this.doc = doc;+ this.inputMode = options.inputMode ?? 'auto';+ const environment: GestureEnvironment = {+ viewportSize: () => ({+ width: doc.defaultView?.innerWidth ?? 0,+ height: doc.defaultView?.innerHeight ?? 0,+ }),+ isRtl: view =>+ view instanceof Element &&+ doc.defaultView?.getComputedStyle(view).direction === 'rtl',+ // A screen-edge pan tells a view within its edge band from any other+ // by its box (spec:AST-094 FR18).+ viewRect: view => {+ if (!(view instanceof Element)) {+ return null;+ }+ const {left, top, width, height} = view.getBoundingClientRect();+ return {left, top, width, height};+ },+ };+ this.arena = new GestureArena({+ clock: options.clock ?? browserClock,+ environment,+ onDeferredClick: (touch, allowed) => this.replayClick(touch, allowed),+ onTransition: options.onTransition,+ });+ const view = doc.defaultView;+ const coarseQuery =+ options.isPrimaryPointerCoarse == null &&+ typeof view?.matchMedia === 'function'+ ? view.matchMedia('(pointer: coarse)')+ : null;+ this.isPrimaryPointerCoarse =+ options.isPrimaryPointerCoarse ?? (() => coarseQuery?.matches ?? false);+ this.coarseQuery = coarseQuery;+ }++ /** Re-derive every element's styles and the host's listeners. */+ private refreshAll(): void {+ for (const [element, registration] of this.registry) {+ this.refresh(element, registration);+ }+ this.syncListeners();+ }++ // --- Attachment ------------------------------------------------------------++ /** Attach a recognizer to an element. Returns the detach function. */+ attach(+ element: Element,+ recognizer: GestureRecognizer,+ options: AttachOptions = {},+ ): () => void {+ const registration = this.registrationFor(element);+ registration.manageStyle = options.manageStyle ?? registration.manageStyle;+ registration.actionGroup = options.actionGroup ?? registration.actionGroup;+ recognizer.view = element;+ registration.recognizers.push(recognizer);+ recognizer.onEnabledChange = () => {+ this.refresh(element, registration);+ this.syncListeners();+ };+ const edgePan = asScreenEdgePan(recognizer);+ if (edgePan != null) {+ // A new answer may also move the band the pan watches onto or off the+ // right side, whose band moves with the viewport (an in-place switch+ // of direction): the layout watch follows (FR18, FR24, DEC-22).+ edgePan.onTouchBehaviorChange = () => {+ this.refresh(element, registration);+ this.syncLayoutWatch();+ };+ }+ this.refresh(element, registration);+ this.syncListeners();+ return () => {+ recognizer.onEnabledChange = null;+ if (edgePan != null) {+ edgePan.onTouchBehaviorChange = null;+ }+ const index = registration.recognizers.indexOf(recognizer);+ if (index >= 0) {+ registration.recognizers.splice(index, 1);+ }+ // A recognizer whose view goes away mid-gesture is cancelled, as in+ // UIKit when a view leaves the window.+ if (recognizer.state !== 'possible' || recognizer.isInvolved()) {+ recognizer.cancel();+ }+ this.refresh(element, registration);+ // Even when the element keeps other attachments: one left disabled+ // keeps no listener or observer (FR24).+ this.syncListeners();+ this.cleanup(element, registration);+ };+ }++ /**+ * Watch the box of each element with an enabled screen-edge pan, and the+ * root's for a pan that watches the right side, whose band moves with the+ * viewport: a resize may move an element into or out of its edge band, and+ * the pan then measures again and re-derives the element's touch-action+ * (FR19). The host sets touch-action for every pointer (FR43), so it+ * watches under any primary pointer. One ResizeObserver serves every+ * element and goes with the last one, and no listener is added (FR24); an+ * engine without ResizeObserver keeps each pan's first measurement.+ */+ private syncLayoutWatch(): void {+ const wanted = new Set<Element>();+ let watchesViewport = false;+ for (const [element, registration] of this.registry) {+ for (const recognizer of registration.recognizers) {+ const edgePan = asScreenEdgePan(recognizer);+ if (edgePan != null && edgePan.isEnabled) {+ wanted.add(element);+ watchesViewport ||= edgePan.watchesViewport;+ }+ }+ }+ if (watchesViewport) {+ wanted.add(this.doc.documentElement);+ }+ for (const element of [...this.layoutWatched]) {+ if (!wanted.has(element)) {+ this.layoutObserver?.unobserve(element);+ this.layoutWatched.delete(element);+ }+ }+ if (wanted.size === 0) {+ this.layoutObserver?.disconnect();+ this.layoutObserver = null;+ return;+ }+ const view = this.doc.defaultView;+ if (+ this.layoutObserver == null &&+ view != null &&+ typeof view.ResizeObserver === 'function'+ ) {+ this.layoutObserver = new view.ResizeObserver(this.onLayoutChange);+ for (const element of this.layoutWatched) {+ this.layoutObserver.observe(element);+ }+ }+ for (const element of wanted) {+ if (!this.layoutWatched.has(element)) {+ this.layoutObserver?.observe(element);+ this.layoutWatched.add(element);+ }+ }+ }++ /** A watched box or the root resized: each enabled edge pan measures again. */+ private readonly onLayoutChange = (): void => {+ for (const registration of this.registry.values()) {+ for (const recognizer of registration.recognizers) {+ const edgePan = asScreenEdgePan(recognizer);+ if (edgePan != null && edgePan.isEnabled) {+ edgePan.layoutChanged();+ }+ }+ }+ };++ /** Attach the view-level touch consumer of an element (a pressable control). */+ attachConsumer(element: Element, consumer: TouchConsumer): () => void {+ const registration = this.registrationFor(element);+ registration.consumer = consumer;+ this.syncListeners();+ return () => {+ if (registration.consumer === consumer) {+ registration.consumer = null;+ }+ // Even when the element keeps a recognizer: one left disabled keeps+ // no listener or observer (FR24).+ this.syncListeners();+ this.cleanup(element, registration);+ };+ }++ /**+ * Find consumers of a kind by attribute, one instance per contact. Returns+ * the function that stops it.+ */+ addDelegatedConsumer(type: DelegatedConsumerType): () => void {+ this.delegated.add(type);+ this.syncListeners();+ return () => {+ this.delegated.delete(type);+ this.syncListeners();+ };+ }++ /**+ * Re-derive an element's styles and the host's listeners after its+ * recognizers' options or its consumer's enabled state changed.+ */+ update(element: Element): void {+ const registration = this.registry.get(element);+ if (registration != null) {+ this.refresh(element, registration);+ }+ this.syncListeners();+ }++ /**+ * The Pointer Events `pointerId` of a contact the arena tracks: a mouse's+ * or a pen's own, and for a finger driven by touch events the pointer its+ * touch was paired with (null before the pairing, or without Pointer+ * Events). It hands a held finger to code that follows pointers, as a+ * menu does when a long press turns into a press-drag selection.+ */+ pointerIdOf(touch: GestureTouch | number): number | null {+ const id = typeof touch === 'number' ? touch : touch.id;+ for (const [pointerId, arenaId] of this.fingerPointers) {+ if (arenaId === id) {+ return pointerId;+ }+ }+ for (const [pointerId, arenaId] of this.pointerIds) {+ if (arenaId === id) {+ return pointerId;+ }+ }+ return null;+ }++ /**+ * Whether a finger set a scroller containing `node` moving within the last+ * `window` ms. A touch there now brakes the scroll rather than pressing+ * whatever is under it: a native list highlights nothing for one.+ */+ isScrollBraking(+ node: Node,+ window: number = UIKIT_GESTURES.press.scrollBrake.value,+ ): boolean {+ const last = this.lastScroll;+ return (+ last != null &&+ this.arena.now() - last.time < window &&+ last.scroller.contains(node)+ );+ }++ private registrationFor(element: Element): Registration {+ let registration = this.registry.get(element);+ if (registration == null) {+ registration = {+ recognizers: [],+ consumer: null,+ touchMoveListener: null,+ touchEndListener: null,+ savedStyle: new Map(),+ authorTouchAction: null,+ manageStyle: true,+ actionGroup: false,+ };+ this.registry.set(element, registration);+ }+ return registration;+ }++ private refresh(element: Element, registration: Registration): void {+ if (registration.manageStyle && element instanceof HTMLElement) {+ this.applyStyle(element, registration);+ }+ // For every pointer (FR43): a finger's claim cancels its moves here+ // (FR19), a listener FR24 counts apart from the one an element keeps for+ // its press.+ const needsListener = registration.recognizers.some(+ r => r.isEnabled && claimsWhileMoving(r),+ );+ if (needsListener && registration.touchMoveListener == null) {+ const listener: EventListener = event =>+ this.cancelIfClaimed(event as TouchEvent);+ registration.touchMoveListener = listener;+ element.addEventListener('touchmove', listener, {passive: false});+ } else if (!needsListener && registration.touchMoveListener != null) {+ element.removeEventListener('touchmove', registration.touchMoveListener);+ registration.touchMoveListener = null;+ }+ // Pointer Events only: a claimed finger's touchend is not the host's+ // own document listener's to cancel, so the element cancels it.+ const needsEndListener =+ this.inputMode === 'pointer-events' &&+ registration.recognizers.some(r => r.isEnabled && r.acceptsTouchInput);+ if (needsEndListener && registration.touchEndListener == null) {+ const listener: EventListener = event =>+ this.cancelClaimedLift(event as TouchEvent);+ registration.touchEndListener = listener;+ element.addEventListener('touchend', listener, {passive: false});+ } else if (!needsEndListener && registration.touchEndListener != null) {+ element.removeEventListener('touchend', registration.touchEndListener);+ registration.touchEndListener = null;+ }+ }++ private applyStyle(element: HTMLElement, registration: Registration): void {+ // Where no attached recognizer is enabled the host manages no style: the+ // element keeps its own touch-action, and any value set before is+ // restored (FR24). Every pointer gets it: a touchscreen laptop's finger+ // as a phone's (spec:AST-094 FR43).+ const enabled = registration.recognizers.filter(r => r.isEnabled);+ const style: GestureHostStyle =+ enabled.length > 0 ? gestureHostStyle(enabled) : {};+ for (const key of Object.keys(+ STYLE_PROPERTIES,+ ) as (keyof GestureHostStyle)[]) {+ const property = STYLE_PROPERTIES[key];+ let value = style[key];+ if (key === 'touchAction') {+ value = this.touchActionToWrite(element, registration, value);+ }+ if (value != null) {+ if (!registration.savedStyle.has(property)) {+ registration.savedStyle.set(+ property,+ element.style.getPropertyValue(property),+ );+ }+ element.style.setProperty(property, value);+ } else if (registration.savedStyle.has(property)) {+ const saved = registration.savedStyle.get(property) ?? '';+ registration.savedStyle.delete(property);+ if (saved === '') {+ element.style.removeProperty(property);+ } else {+ element.style.setProperty(property, saved);+ }+ }+ }+ }++ /**+ * The touch-action to write inline, if any. The author's value (a+ * trigger's own `touch-action: none`) stays in force and the host never+ * allows more (spec:AST-094 FR18, DEC-8):+ * - an inline value is the style's own, read with no recalc, and the host+ * writes what both allow, inline; a CSS-wide keyword (`initial`,+ * `inherit`, `unset`, `revert`, `revert-layer`) names no touch-action of+ * its own, so it is read as an author rule is, as what it resolves to;+ * - otherwise the element is marked with the derived value, under a rule+ * any author rule outranks, as the recognizer attaches: a subtree that+ * mounts with it is styled once, never restyled for it in a later frame.+ * The next frame reads what is in force, styles clean, and the host+ * writes inline only what both allow where that is narrower than an+ * author rule's value.+ */+ private touchActionToWrite(+ element: HTMLElement,+ registration: Registration,+ derived: string | undefined,+ ): string | undefined {+ if (derived == null) {+ unmarkTouchAction(element);+ registration.authorTouchAction = null;+ return undefined;+ }+ const property = STYLE_PROPERTIES.touchAction;+ const inline = registration.savedStyle.has(property)+ ? (registration.savedStyle.get(property) ?? '')+ : element.style.getPropertyValue(property);+ if (inline !== '' && !isCssWideKeyword(inline)) {+ unmarkTouchAction(element);+ return intersectTouchAction(derived, inline);+ }+ if (!markTouchAction(element, derived)) {+ // No document or shadow root to hold the rule (a detached element):+ // nothing is styled there, and the next frame looks again.+ this.readCallerTouchActionInNextFrame(element);+ return undefined;+ }+ const read = registration.authorTouchAction;+ if (read == null || read.derived !== derived) {+ // The rule is in force until the read: the derived value, or the+ // author's where the author sets one.+ this.readCallerTouchActionInNextFrame(element);+ return undefined;+ }+ if (read.author == null) {+ return undefined;+ }+ const both = intersectTouchAction(derived, read.author);+ return both === read.author ? undefined : both;+ }++ /**+ * Read the touch-action in force on each marked element in the next frame,+ * then apply its style again. Batched: one style read serves every pending+ * element, and the writes follow the reads. The host has written no+ * touch-action inline on them, so a value other than the mark is an author+ * rule's.+ */+ private readCallerTouchActionInNextFrame(element: HTMLElement): void {+ this.pendingCallerReads.add(element);+ if (this.isCallerReadScheduled) {+ return;+ }+ this.isCallerReadScheduled = true;+ inNextFrame(this.doc.defaultView, () => {+ this.isCallerReadScheduled = false;+ const pending: [HTMLElement, Registration][] = [];+ for (const candidate of this.pendingCallerReads) {+ const registration = this.registry.get(candidate);+ if (registration != null) {+ pending.push([candidate, registration]);+ }+ }+ this.pendingCallerReads.clear();+ const view = this.doc.defaultView;+ for (const [candidate, registration] of pending) {+ const derived = candidate.getAttribute(TOUCH_ACTION_ATTRIBUTE);+ if (derived == null || view == null) {+ continue;+ }+ const inForce = view.getComputedStyle(candidate).touchAction || 'auto';+ registration.authorTouchAction = {+ derived,+ author: inForce === derived ? null : inForce,+ };+ }+ for (const [candidate, registration] of pending) {+ this.applyStyle(candidate, registration);+ }+ });+ }++ private cleanup(element: Element, registration: Registration): void {+ if (registration.recognizers.length > 0 || registration.consumer != null) {+ return;+ }+ if (registration.touchMoveListener != null) {+ element.removeEventListener('touchmove', registration.touchMoveListener);+ }+ if (registration.touchEndListener != null) {+ element.removeEventListener('touchend', registration.touchEndListener);+ registration.touchEndListener = null;+ }+ this.registry.delete(element);+ this.syncListeners();+ }++ /**+ * Listen only while something could take a touch now (`spec:AST-094`+ * FR24, FR43): where the primary pointer is coarse, while an enabled+ * recognizer or consumer, or a delegated consumer, is attached; where it is+ * fine, only during a press something armed (syncArmed). Otherwise no page+ * listener is registered, so an idle page and a disabled control pay+ * nothing.+ */+ private syncListeners(): void {+ this.syncLayoutWatch();+ // The primary pointer can change (a tablet's keyboard attached or+ // removed): while anything is attached, styles and listeners follow it.+ // Nothing touch-related stays once the last attachment goes (FR24).+ const hasAttachments = this.registry.size > 0 || this.delegated.size > 0;+ if (hasAttachments && !this.isWatchingPointer) {+ this.coarseQuery?.addEventListener?.('change', this.onPointerKindChange);+ this.isWatchingPointer = true;+ } else if (!hasAttachments && this.isWatchingPointer) {+ this.coarseQuery?.removeEventListener?.(+ 'change',+ this.onPointerKindChange,+ );+ this.isWatchingPointer = false;+ }+ this.syncArmed();+ if (this.shouldListen()) {+ this.install();+ } else if (this.isInstalled) {+ this.uninstall();+ }+ }++ private shouldListen(): boolean {+ if (!this.isPrimaryPointerCoarse()) {+ return this.isArmedPress;+ }+ if (this.delegated.size > 0) {+ return true;+ }+ for (const registration of this.registry.values()) {+ if (isServed(registration)) {+ return true;+ }+ }+ return false;+ }++ /**+ * Where the primary pointer is fine, each element with an enabled+ * recognizer or press consumer listens for a press itself: one passive+ * `pointerdown` listener, in the capture phase, so the outermost one hears+ * a press first and serves every recognizer on its path. Delegated+ * consumer types, which have no element, arm the document once. A press+ * installs the host's page listeners for as long as its contacts last+ * (`spec:AST-094` FR24, FR43). Where the primary pointer is coarse the+ * page's listeners serve every press, and nothing is armed.+ */+ private syncArmed(): void {+ const wanted = new Set<EventTarget>();+ if (!this.isPrimaryPointerCoarse()) {+ for (const [element, registration] of this.registry) {+ if (isServed(registration)) {+ wanted.add(element);+ }+ }+ if (this.delegated.size > 0) {+ wanted.add(this.doc);+ }+ }+ for (const [target, disarm] of [...this.armed]) {+ if (!wanted.has(target)) {+ disarm();+ this.armed.delete(target);+ }+ }+ for (const target of wanted) {+ if (this.armed.has(target)) {+ continue;+ }+ target.addEventListener(+ 'pointerdown',+ this.onArmedPress,+ PASSIVE_CAPTURE,+ );+ this.armed.set(target, () => {+ target.removeEventListener(+ 'pointerdown',+ this.onArmedPress,+ PASSIVE_CAPTURE,+ );+ });+ }+ }++ /**+ * A press on something armed, where the primary pointer is fine: a+ * mouse's primary button, a pen, or a finger. The page's listeners come+ * for this press, and the press goes on to them, its capture phase on the+ * page being over.+ */+ private readonly onArmedPress = (event: Event): void => {+ const press = event as PointerEvent;+ if (+ this.isInstalled ||+ !isPointerKind(press.pointerType) ||+ (press.pointerType !== 'touch' && !isPrimaryClick(press))+ ) {+ return;+ }+ this.isArmedPress = true;+ this.install();+ this.onPointerDown(press);+ // A mouse's or a pen's press that nothing took has nothing to wait for;+ // a finger's contact begins at its touchstart, which comes next.+ if (press.pointerType !== 'touch') {+ this.releaseArmedPress();+ }+ };++ /**+ * After a contact ends: once no contact of the press that armed the page's+ * listeners is down, they go (FR24). A recognizer still deciding after the+ * lift needs no input; the click it may owe keeps its listener+ * (releaseClickListener).+ */+ private releaseArmedPress(): void {+ if (+ this.isArmedPress &&+ !this.arena.touches.some(+ touch => touch.phase !== 'ended' && touch.phase !== 'cancelled',+ )+ ) {+ this.isArmedPress = false;+ this.syncListeners();+ }+ }++ /**+ * The click listener outlives the page's others while the swallower is+ * armed: a claimed lift's click comes after its pointerup or touchend+ * (`spec:AST-094` FR21; FR24 counts it as press work). It goes when that+ * window closes, unless the host listens again by then.+ */+ private releaseClickListener(): void {+ const view = this.doc.defaultView;+ if (this.clickRemoval != null) {+ clearTimeout(this.clickRemoval);+ this.clickRemoval = null;+ }+ const remaining = this.swallowDeadline - browserClock.now();+ if (view == null || remaining < 0) {+ view?.removeEventListener('click', this.onClick, ACTIVE_CAPTURE);+ return;+ }+ this.clickRemoval = setTimeout(() => {+ this.clickRemoval = null;+ if (!this.isInstalled) {+ view.removeEventListener('click', this.onClick, ACTIVE_CAPTURE);+ }+ }, remaining + 1);+ }++ // --- Listeners -------------------------------------------------------------++ private install(): void {+ if (this.isInstalled) {+ return;+ }+ if (this.clickRemoval != null) {+ clearTimeout(this.clickRemoval);+ this.clickRemoval = null;+ }+ const view = this.doc.defaultView;+ this.isInstalled = true;+ this.usesTouchEvents =+ this.inputMode === 'auto' && view != null && 'ontouchstart' in view;+ const doc = this.doc;+ // Pointer Events only: a finger comes from its pointer events alone. A+ // browser that has Touch Events still sends them for the same finger, and+ // reading both would track it twice (a long press needs one touch).+ if (this.inputMode === 'auto') {+ doc.addEventListener('touchstart', this.onTouchStart, PASSIVE_CAPTURE);+ doc.addEventListener('touchmove', this.onTouchMove, PASSIVE_CAPTURE);+ doc.addEventListener('touchend', this.onTouchEnd, ACTIVE_CAPTURE);+ doc.addEventListener('touchcancel', this.onTouchCancel, PASSIVE_CAPTURE);+ }+ doc.addEventListener('pointerdown', this.onPointerDown, PASSIVE_CAPTURE);+ doc.addEventListener('pointermove', this.onPointerMove, PASSIVE_CAPTURE);+ doc.addEventListener('pointerup', this.onPointerUp, PASSIVE_CAPTURE);+ doc.addEventListener(+ 'pointercancel',+ this.onPointerCancel,+ PASSIVE_CAPTURE,+ );+ doc.addEventListener('contextmenu', this.onContextMenu, ACTIVE_CAPTURE);+ doc.addEventListener('scroll', this.onScroll, PASSIVE_CAPTURE);+ doc.addEventListener('visibilitychange', this.onVisibilityChange);+ view?.addEventListener('click', this.onClick, ACTIVE_CAPTURE);+ view?.addEventListener('blur', this.onBlur);+ }++ private uninstall(): void {+ if (!this.isInstalled) {+ return;+ }+ this.isInstalled = false;+ const doc = this.doc;+ const view = doc.defaultView;+ doc.removeEventListener('touchstart', this.onTouchStart, PASSIVE_CAPTURE);+ doc.removeEventListener('touchmove', this.onTouchMove, PASSIVE_CAPTURE);+ doc.removeEventListener('touchend', this.onTouchEnd, ACTIVE_CAPTURE);+ doc.removeEventListener('touchcancel', this.onTouchCancel, PASSIVE_CAPTURE);+ doc.removeEventListener('pointerdown', this.onPointerDown, PASSIVE_CAPTURE);+ doc.removeEventListener('pointermove', this.onPointerMove, PASSIVE_CAPTURE);+ doc.removeEventListener('pointerup', this.onPointerUp, PASSIVE_CAPTURE);+ doc.removeEventListener(+ 'pointercancel',+ this.onPointerCancel,+ PASSIVE_CAPTURE,+ );+ doc.removeEventListener('contextmenu', this.onContextMenu, ACTIVE_CAPTURE);+ doc.removeEventListener('scroll', this.onScroll, PASSIVE_CAPTURE);+ doc.removeEventListener('visibilitychange', this.onVisibilityChange);+ this.releaseClickListener();+ view?.removeEventListener('blur', this.onBlur);+ this.cancelEverything(this.arena.now());+ this.lastTouch = null;+ this.lastScroll = null;+ }++ // --- Hit path --------------------------------------------------------------++ /**+ * The recognizers on the path from `target` to the document, innermost+ * first, and (for a contact) its consumer: the innermost element with an+ * attached consumer or a delegated consumer type's attribute.+ */+ private participantsAt(+ target: unknown,+ pointerType: PointerKind | null,+ ): {+ recognizers: GestureRecognizer[];+ consumer: TouchConsumer | null;+ } {+ const recognizers: GestureRecognizer[] = [];+ let consumer: TouchConsumer | null = null;+ let hasConsumerOwner = pointerType == null;+ for (+ let node: Node | null = target instanceof Node ? target : null;+ node != null;+ node = parentAcrossShadow(node)+ ) {+ if (!(node instanceof Element)) {+ continue;+ }+ const registration = this.registry.get(node);+ if (registration != null) {+ recognizers.push(...registration.recognizers);+ }+ if (hasConsumerOwner || pointerType == null) {+ continue;+ }+ if (registration?.consumer != null) {+ consumer = registration.consumer;+ hasConsumerOwner = true;+ continue;+ }+ for (const type of this.delegated) {+ if (node.hasAttribute(type.attribute)) {+ consumer = type.create(node, pointerType);+ hasConsumerOwner = true;+ break;+ }+ }+ }+ return {recognizers, consumer};+ }++ // --- Touch events ----------------------------------------------------------++ /** Whether this event is new to the host (and mark it handled). */+ private takeEvent(event: Event): boolean {+ if (this.processed.has(event)) {+ return false;+ }+ this.processed.add(event);+ return true;+ }++ private readonly onTouchStart = (event: TouchEvent): void => {+ if (!this.takeEvent(event)) {+ return;+ }+ const time = eventTime(event);+ const inputs: ArenaBeganInput[] = [];+ const untracked: TouchBeganInput[] = [];+ const stale: number[] = [];+ for (const touch of touchesOf(event.changedTouches)) {+ if ((touch as StylusTouch).touchType === 'stylus') {+ continue;+ }+ // A finger number still tracked here began again: the touch it named+ // ended where no listener of ours could hear it.+ const previous = this.forgetFinger(touch.identifier);+ if (previous != null) {+ stale.push(previous);+ }+ const target = touch.target instanceof Node ? touch.target : event.target;+ const {recognizers, consumer} = this.participantsAt(target, 'touch');+ if (recognizers.length === 0 && consumer == null) {+ // Nothing here takes part: the touch stays the page's, but a+ // recognizer tracking another finger hears it began (a second+ // finger beside an open menu ends its press, spec:AST-094 FR28).+ untracked.push({+ id: this.nextId++,+ x: touch.clientX,+ y: touch.clientY,+ time,+ pointerType: 'touch',+ target,+ });+ continue;+ }+ const id = this.nextId++;+ this.touchIds.set(touch.identifier, id);+ this.holdSelection(id, recognizers);+ this.watchTarget(+ touch.identifier,+ target,+ recognizers.some(claimsWhileMoving),+ );+ this.lastFed.set(id, {x: touch.clientX, y: touch.clientY, time});+ this.pairTouch(id, {x: touch.clientX, y: touch.clientY, target});+ inputs.push({+ id,+ x: touch.clientX,+ y: touch.clientY,+ time,+ pointerType: 'touch',+ target,+ scroll: createNativeScrollProbe(target),+ recognizers,+ consumer,+ });+ }+ if (stale.length > 0) {+ this.arena.cancelled(stale, time);+ }+ this.arena.began(inputs);+ for (const input of untracked) {+ this.arena.untrackedBegan(input);+ }+ // Stamped after the consumers judged the touch: the brake asks whether+ // an EARLIER finger is still driving a scroll.+ if (event.target instanceof Node) {+ this.lastTouch = {target: event.target, time};+ }+ };++ private readonly onTouchMove = (event: TouchEvent): void => {+ if (!this.takeEvent(event)) {+ return;+ }+ this.dropFingersNotDown(event);+ const time = eventTime(event);+ const ids: number[] = [];+ const inputs: TouchInput[] = [];+ for (const touch of touchesOf(event.changedTouches)) {+ const id = this.touchIds.get(touch.identifier);+ if (id == null) {+ continue;+ }+ ids.push(id);+ inputs.push({id, x: touch.clientX, y: touch.clientY, time});+ }+ if (inputs.length === 0) {+ return;+ }+ if (!event.cancelable) {+ // The browser no longer asks the page about these fingers. WebKit+ // stops asking when it takes the touch to pan (its pointercancel comes+ // with it); Chromium also stops after one unconsumed touchmove, even+ // when `touch-action` keeps it from panning the way the finger went (a+ // horizontal drag under pan-y). So a finger's FIRST uncancelable move+ // counts as the browser's claim only if the browser could pan along+ // the finger's main axis since touch-down; later ones add nothing, and+ // pointercancel or a scroll still report any real pan.+ const placed = new Map(inputs.map(input => [input.id, input]));+ const taken = ids.filter(id => {+ const touch = this.arena.getTouch(id);+ if (+ touch == null ||+ touch.takenByBrowser ||+ this.arena.isClaimed(id) ||+ touch.scroll?.allowsNativePan === false ||+ this.judgedUncancelable.has(id)+ ) {+ return false;+ }+ this.judgedUncancelable.add(id);+ const input = placed.get(id);+ if (input == null || touch.scroll == null) {+ return true;+ }+ const dx = input.x - touch.startX;+ const dy = input.y - touch.startY;+ return Math.abs(dx) >= Math.abs(dy)+ ? touch.scroll.canScroll(dx, 0)+ : touch.scroll.canScroll(0, dy);+ });+ if (taken.length > 0) {+ this.arena.browserTookOver(taken, time);+ }+ }+ this.feedMoves(inputs);+ };++ /**+ * Under `inputMode: 'pointer-events'` a finger comes from its pointer+ * events, so its touches carry no id of ours: the live finger it is, the+ * nearest pointer-fed finger on the same target. Its touchmoves can then+ * be cancelled once a recognizer claims it (`spec:AST-094` FR19, FR21).+ */+ private pointerFingerAt(touch: Touch): number | undefined {+ let best: GestureTouch | null = null;+ let bestDistance = Number.POSITIVE_INFINITY;+ for (const finger of this.arena.touches) {+ if (+ finger.pointerType !== 'touch' ||+ finger.phase === 'ended' ||+ finger.phase === 'cancelled' ||+ !(finger.target instanceof Node) ||+ !(touch.target instanceof Node) ||+ !(+ finger.target === touch.target ||+ finger.target.contains(touch.target) ||+ touch.target.contains(finger.target)+ )+ ) {+ continue;+ }+ const d = Math.hypot(finger.x - touch.clientX, finger.y - touch.clientY);+ if (d < bestDistance) {+ best = finger;+ bestDistance = d;+ }+ }+ return best?.id;+ }++ /**+ * Cancel the `touchend` of a finger a recognizer owned when it lifted+ * (`inputMode: 'pointer-events'`): its `pointerup` came first, at the same+ * place on the same target (`spec:AST-094` FR21).+ */+ private cancelClaimedLift(event: TouchEvent): void {+ if (!event.cancelable || event.defaultPrevented) {+ return;+ }+ for (const touch of touchesOf(event.changedTouches)) {+ const index = this.claimedLifts.findIndex(lift =>+ isSamePlace(lift, {+ x: touch.clientX,+ y: touch.clientY,+ target: touch.target,+ }),+ );+ if (index >= 0) {+ this.claimedLifts.splice(index, 1);+ event.preventDefault();+ return;+ }+ }+ }++ /**+ * Cancel a `touchmove` while a recognizer owns one of its fingers. A touch+ * no recognizer owns keeps its moves (`spec:AST-094` FR19): nothing is+ * cancelled before a recognizer begins, or for a touch it does not track.+ */+ private cancelIfClaimed(event: TouchEvent): void {+ if (!event.cancelable || event.defaultPrevented) {+ return;+ }+ // Only the touches this move reports: another finger a recognizer owns+ // does not make this one its own.+ const moved = touchesOf(event.changedTouches);+ for (const touch of moved) {+ const id =+ this.touchIds.get(touch.identifier) ??+ (this.inputMode === 'pointer-events'+ ? this.pointerFingerAt(touch)+ : undefined);+ if (id != null && this.arena.isClaimed(id)) {+ event.preventDefault();+ return;+ }+ }+ if (moved.some(touch => (touch as StylusTouch).touchType === 'stylus')) {+ for (const id of this.pointerIds.values()) {+ if (this.arena.isClaimed(id)) {+ // A pen whose pointer a recognizer owns: its stylus touches too,+ // never a finger no recognizer owns.+ event.preventDefault();+ return;+ }+ }+ }+ }++ private readonly onTouchEnd = (event: TouchEvent): void => {+ if (!this.takeEvent(event)) {+ return;+ }+ this.dropFingersNotDown(event);+ const time = eventTime(event);+ const inputs: TouchInput[] = [];+ for (const touch of touchesOf(event.changedTouches)) {+ const id = this.forgetFinger(touch.identifier);+ if (id == null) {+ continue;+ }+ inputs.push({id, x: touch.clientX, y: touch.clientY, time});+ }+ // The lift is when momentum starts: the clock the brake wants most.+ if (event.target instanceof Node) {+ this.lastTouch = {target: event.target, time};+ }+ if (inputs.length === 0) {+ this.releaseArmedPress();+ return;+ }+ const dispositions = this.arena.ended(inputs);+ if (needsSuppression(dispositions)) {+ if (event.cancelable) {+ event.preventDefault();+ }+ this.armSwallower();+ }+ this.releaseArmedPress();+ };++ private readonly onTouchCancel = (event: TouchEvent): void => {+ if (!this.takeEvent(event)) {+ return;+ }+ const listed = touchesOf(event.changedTouches);+ // A cancel that names no finger is the system taking them all.+ const identifiers =+ listed.length > 0+ ? listed.map(touch => touch.identifier)+ : [...this.touchIds.keys()];+ const ids: number[] = [];+ for (const identifier of identifiers) {+ const id = this.forgetFinger(identifier);+ if (id != null) {+ ids.push(id);+ }+ }+ if (ids.length > 0) {+ this.arena.cancelled(ids, eventTime(event));+ }+ this.releaseArmedPress();+ };++ /** The target's own listeners, for a target that left the document. */+ private readonly onTargetTouchMove = (event: Event): void => {+ this.onTouchMove(event as TouchEvent);+ this.cancelIfClaimed(event as TouchEvent);+ };++ /** The same for a finger nothing could claim while it moves: never blocks. */+ private readonly onTargetTouchMovePassive = (event: Event): void => {+ this.onTouchMove(event as TouchEvent);+ };++ private readonly onTargetTouchEnd = (event: Event): void => {+ this.onTouchEnd(event as TouchEvent);+ };++ private readonly onTargetTouchCancel = (event: Event): void => {+ this.onTouchCancel(event as TouchEvent);+ };++ /**+ * Cancel tracked fingers the event says are no longer down. `touches`+ * lists every finger on the screen; one missing from it (and not lifting+ * in this very event) ended where we could not see it.+ */+ private dropFingersNotDown(event: TouchEvent): void {+ if (event.touches == null || this.touchIds.size === 0) {+ return;+ }+ const down = new Set<number>();+ for (const touch of touchesOf(event.touches)) {+ down.add(touch.identifier);+ }+ for (const touch of touchesOf(event.changedTouches)) {+ down.add(touch.identifier);+ }+ const gone = [...this.touchIds.keys()].filter(+ identifier => !down.has(identifier),+ );+ const ids: number[] = [];+ for (const identifier of gone) {+ const id = this.forgetFinger(identifier);+ if (id != null) {+ ids.push(id);+ }+ }+ if (ids.length > 0) {+ this.arena.cancelled(ids, eventTime(event));+ }+ }++ private watchTarget(+ identifier: number,+ target: EventTarget | null,+ isBlocking: boolean,+ ): void {+ if (target == null || typeof target.addEventListener !== 'function') {+ return;+ }+ this.touchTargets.set(identifier, target);+ const state = this.watched.get(target);+ if (state == null) {+ this.watched.set(target, {count: 1, blocking: isBlocking ? 1 : 0});+ if (isBlocking) {+ this.blockingFingers.add(identifier);+ }+ target.addEventListener(+ 'touchmove',+ isBlocking ? this.onTargetTouchMove : this.onTargetTouchMovePassive,+ {passive: !isBlocking},+ );+ target.addEventListener('touchend', this.onTargetTouchEnd, {+ passive: false,+ });+ target.addEventListener('touchcancel', this.onTargetTouchCancel, {+ passive: true,+ });+ return;+ }+ const wasBlocking = state.blocking > 0;+ state.count += 1;+ if (isBlocking) {+ state.blocking += 1;+ this.blockingFingers.add(identifier);+ }+ this.swapTargetTouchMove(target, wasBlocking, state.blocking > 0);+ }++ private unwatchTarget(identifier: number): void {+ const target = this.touchTargets.get(identifier);+ if (target == null) {+ return;+ }+ this.touchTargets.delete(identifier);+ const state = this.watched.get(target);+ if (state == null) {+ return;+ }+ const wasBlocking = state.blocking > 0;+ state.count -= 1;+ if (this.blockingFingers.delete(identifier)) {+ state.blocking -= 1;+ }+ if (state.count > 0) {+ this.swapTargetTouchMove(target, wasBlocking, state.blocking > 0);+ return;+ }+ this.watched.delete(target);+ target.removeEventListener(+ 'touchmove',+ wasBlocking ? this.onTargetTouchMove : this.onTargetTouchMovePassive,+ );+ target.removeEventListener('touchend', this.onTargetTouchEnd);+ target.removeEventListener('touchcancel', this.onTargetTouchCancel);+ }++ /**+ * Keeps one `touchmove` listener on a watched target: the blocking one+ * while a finger on it could be claimed as it moves, a passive one+ * otherwise, so a scroll starting there never waits on the main thread+ * (`spec:AST-094` FR19).+ */+ private swapTargetTouchMove(+ target: EventTarget,+ wasBlocking: boolean,+ isBlocking: boolean,+ ): void {+ if (wasBlocking === isBlocking) {+ return;+ }+ target.removeEventListener(+ 'touchmove',+ wasBlocking ? this.onTargetTouchMove : this.onTargetTouchMovePassive,+ );+ target.addEventListener(+ 'touchmove',+ isBlocking ? this.onTargetTouchMove : this.onTargetTouchMovePassive,+ {passive: !isBlocking},+ );+ }++ /** Stop tracking a finger by its Touch.identifier; returns its arena id. */+ private forgetFinger(identifier: number): number | undefined {+ const id = this.touchIds.get(identifier);+ this.touchIds.delete(identifier);+ this.unwatchTarget(identifier);+ if (id != null) {+ this.forgetContact(id);+ }+ return id;+ }++ private pairTouch(id: number, place: PlacedContact): void {+ for (const [pointerId, pending] of this.pendingPointers) {+ if (isSamePlace(pending, place)) {+ this.pendingPointers.delete(pointerId);+ this.fingerPointers.set(pointerId, id);+ return;+ }+ }+ this.unpairedTouches.set(id, place);+ }++ private pairPointer(pointerId: number, place: PlacedContact): void {+ for (const [id, unpaired] of this.unpairedTouches) {+ if (isSamePlace(unpaired, place)) {+ this.unpairedTouches.delete(id);+ this.fingerPointers.set(pointerId, id);+ return;+ }+ }+ this.pendingPointers.set(pointerId, place);+ }++ /** Feed moves, dropping the echo of a move the other channel delivered. */+ private feedMoves(inputs: ReadonlyArray<TouchInput>): void {+ const fresh = inputs.filter(input => {+ const last = this.lastFed.get(input.id);+ if (+ last != null &&+ (input.time < last.time ||+ (input.time === last.time &&+ input.x === last.x &&+ input.y === last.y))+ ) {+ return false;+ }+ this.lastFed.set(input.id, {x: input.x, y: input.y, time: input.time});+ return true;+ });+ if (fresh.length > 0) {+ this.arena.moved(fresh);+ }+ }++ /**+ * For one held press by a finger or a pen: text selection and the touch+ * callout off on the elements whose hold does something (a long press),+ * as `holdSelectionStyle` decides (`spec:AST-094` FR41, DEC-9).+ * Everything else keeps the browser's long-press selection. Restored when+ * the contact ends; refcounted across contacts on one element.+ */+ private holdSelection(+ id: number,+ recognizers: ReadonlyArray<GestureRecognizer>,+ ): void {+ const elements = new Set<HTMLElement>();+ for (const recognizer of recognizers) {+ if (+ recognizer.view instanceof HTMLElement &&+ recognizer.isEnabled &&+ // An element attached with manageStyle: false keeps its own styles.+ this.registry.get(recognizer.view)?.manageStyle !== false &&+ holdSelectionStyle([recognizer]) != null+ ) {+ elements.add(recognizer.view);+ }+ }+ if (elements.size === 0) {+ return;+ }+ const held = [...elements];+ for (const element of held) {+ const entry = heldSelection.get(element);+ if (entry != null) {+ entry.count += 1;+ continue;+ }+ const saved = HOLD_SELECTION_PROPERTIES.map(name => ({+ name,+ value: element.style.getPropertyValue(name),+ priority: element.style.getPropertyPriority(name),+ }));+ for (const name of HOLD_SELECTION_PROPERTIES) {+ element.style.setProperty(name, 'none');+ }+ heldSelection.set(element, {count: 1, saved});+ }+ this.heldSelectionBy.set(id, held);+ }++ /** Undo `holdSelection` for a contact that ended; idempotent. */+ private releaseSelection(id: number): void {+ const held = this.heldSelectionBy.get(id);+ if (held == null) {+ return;+ }+ this.heldSelectionBy.delete(id);+ for (const element of held) {+ const entry = heldSelection.get(element);+ if (entry == null) {+ continue;+ }+ entry.count -= 1;+ if (entry.count > 0) {+ continue;+ }+ heldSelection.delete(element);+ for (const {name, value, priority} of entry.saved) {+ if (value === '') {+ element.style.removeProperty(name);+ } else {+ element.style.setProperty(name, value, priority);+ }+ }+ }+ }++ /** Forget a contact's pairing and echo state. */+ private forgetContact(id: number): void {+ this.releaseSelection(id);+ this.lastFed.delete(id);+ this.judgedUncancelable.delete(id);+ this.unpairedTouches.delete(id);+ for (const [pointerId, paired] of this.fingerPointers) {+ if (paired === id) {+ this.fingerPointers.delete(pointerId);+ }+ }+ }++ // --- Pointer events --------------------------------------------------------++ private readonly onPointerDown = (event: PointerEvent): void => {+ // A new press: whatever click is still owed to the last one is not this.+ this.disarmSwallower();+ if (!isPointerKind(event.pointerType)) {+ return;+ }+ if (event.pointerType === 'touch' && this.usesTouchEvents) {+ this.pairPointer(event.pointerId, {+ x: event.clientX,+ y: event.clientY,+ target: event.target,+ });+ return;+ }+ // A right click, a pen's barrel button and a ctrl-click on macOS start+ // no press (FR43).+ if (event.pointerType !== 'touch' && !isPrimaryClick(event)) {+ return;+ }+ const {recognizers, consumer} = this.participantsAt(+ event.target,+ event.pointerType,+ );+ if (recognizers.length === 0 && consumer == null) {+ return;+ }+ const id = this.nextId++;+ this.pointerIds.set(event.pointerId, id);+ if (event.pointerType !== 'mouse') {+ this.holdSelection(id, recognizers);+ }+ this.arena.began([+ {+ id,+ x: event.clientX,+ y: event.clientY,+ time: eventTime(event),+ pointerType: event.pointerType,+ target: event.target,+ scroll: createNativeScrollProbe(event.target),+ recognizers,+ consumer,+ },+ ]);+ };++ private readonly onPointerMove = (event: PointerEvent): void => {+ if (event.pointerType === 'touch' && this.usesTouchEvents) {+ const id = this.fingerPointers.get(event.pointerId);+ if (id != null) {+ this.feedMoves([+ {+ id,+ x: event.clientX,+ y: event.clientY,+ time: eventTime(event),+ history: coalescedHistory(event),+ },+ ]);+ }+ return;+ }+ const id = this.pointerIds.get(event.pointerId);+ if (id != null) {+ this.arena.moved([+ {+ id,+ x: event.clientX,+ y: event.clientY,+ time: eventTime(event),+ history: coalescedHistory(event),+ },+ ]);+ return;+ }+ };++ private readonly onPointerUp = (event: PointerEvent): void => {+ if (event.pointerType === 'touch' && this.usesTouchEvents) {+ // The lift itself is the touchend's: it alone can cancel the click.+ this.fingerPointers.delete(event.pointerId);+ this.pendingPointers.delete(event.pointerId);+ return;+ }+ const id = this.pointerIds.get(event.pointerId);+ if (id == null) {+ this.releaseArmedPress();+ return;+ }+ this.pointerIds.delete(event.pointerId);+ this.releaseSelection(id);+ if (event.pointerType === 'touch' && this.arena.isClaimed(id)) {+ this.claimedLifts.push({+ x: event.clientX,+ y: event.clientY,+ target: event.target,+ });+ if (this.claimedLifts.length > 8) {+ this.claimedLifts.shift();+ }+ }+ const dispositions = this.arena.ended([+ {id, x: event.clientX, y: event.clientY, time: eventTime(event)},+ ]);+ if (needsSuppression(dispositions)) {+ this.armSwallower();+ }+ this.releaseArmedPress();+ };++ private readonly onPointerCancel = (event: PointerEvent): void => {+ if (event.pointerType === 'touch' && this.usesTouchEvents) {+ const id =+ this.fingerPointers.get(event.pointerId) ??+ this.touchForCancelledPointer(event);+ this.fingerPointers.delete(event.pointerId);+ this.pendingPointers.delete(event.pointerId);+ if (id != null) {+ this.arena.browserTookOver([id], eventTime(event));+ }+ return;+ }+ const id = this.pointerIds.get(event.pointerId);+ if (id != null) {+ this.pointerIds.delete(event.pointerId);+ this.releaseSelection(id);+ this.arena.cancelled([id], eventTime(event));+ }+ this.releaseArmedPress();+ };++ /**+ * Which live finger a touch `pointercancel` is about. The pointer keeps+ * the target the finger landed on (implicit capture), as the Touch does;+ * among fingers on that target, the nearest. WebKit also numbers the+ * pointer like the Touch, which settles what position cannot.+ */+ private touchForCancelledPointer(event: PointerEvent): number | null {+ let best: GestureTouch | null = null;+ let bestDistance = Number.POSITIVE_INFINITY;+ for (const touch of this.arena.touches) {+ if (+ touch.pointerType !== 'touch' ||+ touch.phase === 'ended' ||+ touch.phase === 'cancelled' ||+ touch.target !== event.target+ ) {+ continue;+ }+ const d = Math.hypot(touch.x - event.clientX, touch.y - event.clientY);+ if (d < bestDistance) {+ best = touch;+ bestDistance = d;+ }+ }+ if (best != null) {+ return best.id;+ }+ return this.touchIds.get(event.pointerId) ?? null;+ }++ // --- Clicks, menus, scrolls, focus -----------------------------------------++ private armSwallower(): void {+ this.swallowDeadline =+ browserClock.now() + UIKIT_GESTURES.click.strayClickWindow.value;+ }++ private disarmSwallower(): void {+ this.swallowDeadline = Number.NEGATIVE_INFINITY;+ }++ private readonly onClick = (event: MouseEvent): void => {+ if (browserClock.now() > this.swallowDeadline) {+ return;+ }+ if (!event.isTrusted || event.detail === 0) {+ return;+ }+ if (+ event.target instanceof Element &&+ event.target.hasAttribute(HAPTIC_SWITCH_ATTRIBUTE)+ ) {+ return;+ }+ this.disarmSwallower();+ event.preventDefault();+ event.stopImmediatePropagation();+ };++ private replayClick(touch: GestureTouch, allowed: boolean): void {+ if (!allowed) {+ return;+ }+ // The browser's own click was swallowed while recognizers decided; they+ // all failed, so the click the touch earned is delivered now.+ this.disarmSwallower();+ const target = touch.target;+ const view = this.doc.defaultView;+ if (!(target instanceof Element) || !target.isConnected || view == null) {+ return;+ }+ target.dispatchEvent(+ new view.MouseEvent('click', {+ bubbles: true,+ cancelable: true,+ composed: true,+ detail: 1,+ clientX: touch.x,+ clientY: touch.y,+ }),+ );+ }++ private readonly onContextMenu = (event: MouseEvent): void => {+ for (const touch of this.arena.touches) {+ if (this.arena.isClaimed(touch.id)) {+ event.preventDefault();+ return;+ }+ }+ };++ /**+ * A recognizer is about to scroll `scroller` itself (a menu's edge+ * autoscroll, spec:AST-094 FR30): the scroll that write fires is not a+ * finger's and not the browser taking one. It passes until the end of the+ * next frame, when that event has fired; a real pan in that window still+ * reports itself through pointercancel or touchcancel.+ */+ ownScroll(scroller: Node): void {+ this.ownedScrolls.add(scroller);+ const view = this.doc.defaultView;+ if (view == null) {+ return;+ }+ view.requestAnimationFrame(() => {+ view.requestAnimationFrame(() => {+ this.ownedScrolls.delete(scroller);+ });+ });+ }++ private readonly onScroll = (event: Event): void => {+ const time = eventTime(event);+ const scroller = event.target === this.doc ? this.doc : event.target;+ if (!(scroller instanceof Node) || this.ownedScrolls.has(scroller)) {+ return;+ }+ // A scroll is a finger's only if that finger was inside this scroller,+ // recently; anything else is the program moving something.+ const last = this.lastTouch;+ if (+ last != null &&+ time - last.time < UIKIT_GESTURES.press.momentumMemory.value &&+ scroller.contains(last.target)+ ) {+ this.lastScroll = {scroller, time};+ }+ const taken: number[] = [];+ for (const touch of this.arena.touches) {+ if (+ touch.takenByBrowser ||+ touch.phase === 'ended' ||+ touch.phase === 'cancelled' ||+ touch.pointerType !== 'touch' ||+ this.arena.isClaimed(touch.id)+ ) {+ continue;+ }+ if (+ touch.target instanceof Node &&+ scroller.contains(touch.target) &&+ // Only a pan this finger drove takes the touch: the browser starts+ // one only once the finger has travelled the take distance+ // (spec:AST-094 FR20). A scroll under a finger that has not+ // (scrollIntoView, a transcript pinned to its end, scroll+ // anchoring) is the page's own: the touch, and the click it earns,+ // stay where they are.+ Math.hypot(touch.x - touch.startX, touch.y - touch.startY) >=+ UIKIT_GESTURES.press.slop.value+ ) {+ taken.push(touch.id);+ }+ }+ if (taken.length > 0) {+ this.arena.browserTookOver(taken, time);+ }+ };++ private readonly onVisibilityChange = (): void => {+ if (this.doc.visibilityState === 'hidden') {+ this.cancelEverything(this.arena.now());+ this.releaseArmedPress();+ }+ };++ private readonly onBlur = (): void => {+ this.cancelEverything(this.arena.now());+ this.releaseArmedPress();+ };++ /** The app lost focus: UIKit cancels every touch in flight. */+ private cancelEverything(time: number): void {+ const ids = [...this.pointerIds.values()];+ for (const id of ids) {+ this.releaseSelection(id);+ }+ for (const identifier of [...this.touchIds.keys()]) {+ const id = this.forgetFinger(identifier);+ if (id != null) {+ ids.push(id);+ }+ }+ this.pointerIds.clear();+ this.fingerPointers.clear();+ this.pendingPointers.clear();+ this.unpairedTouches.clear();+ this.lastFed.clear();+ if (ids.length > 0) {+ this.arena.cancelled(ids, time);+ }+ }+}++/** Whether an attachment could take a press now: something on it is enabled. */+function isServed(registration: Registration): boolean {+ return (+ registration.recognizers.some(r => r.isEnabled) ||+ (registration.consumer != null &&+ registration.consumer.isEnabled?.() !== false)+ );+}++function needsSuppression(+ dispositions: Map<number, ClickDisposition>,+): boolean {+ for (const disposition of dispositions.values()) {+ if (disposition !== 'allow') {+ return true;+ }+ }+ return false;+}++function coalescedHistory(event: PointerEvent): TouchSample[] {+ if (typeof event.getCoalescedEvents !== 'function') {+ return [];+ }+ const coalesced = event.getCoalescedEvents();+ return coalesced.slice(0, -1).map(sample => ({+ x: sample.clientX,+ y: sample.clientY,+ time: eventTime(sample),+ }));+}++const hosts = new WeakMap<Document, GestureHost>();++/** The gesture host of a document, created on first use. */+export function getGestureHost(doc: Document): GestureHost {+ let host = hosts.get(doc);+ if (host == null) {+ host = new GestureHost(doc);+ hosts.set(doc, host);+ }+ return host;+}diff --git a/packages/core/src/gestures/GestureRecognizer.ts b/packages/core/src/gestures/GestureRecognizer.tsindex 349ebbbda9..80f8651133 100644--- a/packages/core/src/gestures/GestureRecognizer.ts+++ b/packages/core/src/gestures/GestureRecognizer.ts@@ -142,9 +142,20 @@ export const MANIPULATION: NativeTouchBehavior = {doubleTapZoom: false,};+/**+ * What a recognizer is. The gesture code tells the family apart by it, never+ * by `instanceof` (`architecture:react-component-runtime` INV13); a+ * screen-edge pan is its own kind, though it is built on the pan.+ */+export type RecognizerKind =+ 'tap' | 'longPress' | 'pan' | 'screenEdgePan' | 'swipe' | 'pinch';+let nextRecognizerId = 1;export abstract class GestureRecognizer {+ /** What this recognizer is (see RecognizerKind). */+ abstract get kind(): RecognizerKind;+/** Stable id, for ordering and debugging. */readonly id = nextRecognizerId++;name: string;@@ -568,12 +579,19 @@ export abstract class GestureRecognizer {}}+ /** @internal The host's hook: listeners follow whether anything is enabled. */+ onEnabledChange: (() => void) | null = null;+/*** UIKit's `isEnabled` setter: turning a recognizer off mid-gesture cancels* the gesture (an active one) or fails it (a possible one).*/setEnabled(value: boolean): void {+ const changed = this.isEnabled !== value;this.isEnabled = value;+ if (changed) {+ this.onEnabledChange?.();+ }if (!value && (this.state !== 'possible' || this.isInvolved())) {this.cancel();}diff --git a/packages/core/src/gestures/LongPressGestureRecognizer.ts b/packages/core/src/gestures/LongPressGestureRecognizer.tsindex b552928573..839fede44a 100644--- a/packages/core/src/gestures/LongPressGestureRecognizer.ts+++ b/packages/core/src/gestures/LongPressGestureRecognizer.ts@@ -41,6 +41,10 @@ export interface LongPressGestureRecognizerOptions extends GestureRecognizerOpti}export class LongPressGestureRecognizer extends GestureRecognizer {+ override get kind(): GestureRecognizer['kind'] {+ return 'longPress';+ }+minimumPressDuration: number;allowableMovement: number;numberOfTapsRequired: number;diff --git a/packages/core/src/gestures/PanGestureRecognizer.ts b/packages/core/src/gestures/PanGestureRecognizer.tsindex 136fbcfe09..18ae9bb1ef 100644--- a/packages/core/src/gestures/PanGestureRecognizer.ts+++ b/packages/core/src/gestures/PanGestureRecognizer.ts@@ -87,6 +87,10 @@ const DIRECTION_VECTORS: Partial<Record<PanDirection, Point>> = {};export class PanGestureRecognizer extends GestureRecognizer {+ override get kind(): GestureRecognizer['kind'] {+ return 'pan';+ }+minimumNumberOfTouches: number;maximumNumberOfTouches: number;hysteresis: number;diff --git a/packages/core/src/gestures/PinchGestureRecognizer.ts b/packages/core/src/gestures/PinchGestureRecognizer.tsindex 2835237645..07b3a6c3c1 100644--- a/packages/core/src/gestures/PinchGestureRecognizer.ts+++ b/packages/core/src/gestures/PinchGestureRecognizer.ts@@ -35,6 +35,10 @@ export interface PinchGestureRecognizerOptions extends GestureRecognizerOptions<}export class PinchGestureRecognizer extends GestureRecognizer {+ override get kind(): GestureRecognizer['kind'] {+ return 'pinch';+ }+hysteresis: number;private initialSpan = 0;private scaleValue = 1;diff --git a/packages/core/src/gestures/ScreenEdgePanGestureRecognizer.ts b/packages/core/src/gestures/ScreenEdgePanGestureRecognizer.tsindex 5f6dd1cedc..d9ca6f5c4d 100644--- a/packages/core/src/gestures/ScreenEdgePanGestureRecognizer.ts+++ b/packages/core/src/gestures/ScreenEdgePanGestureRecognizer.ts@@ -85,6 +85,10 @@ export interface ScreenEdgePanGestureRecognizerOptions extends Omit<}export class ScreenEdgePanGestureRecognizer extends PanGestureRecognizer {+ override get kind(): PanGestureRecognizer['kind'] {+ return 'screenEdgePan';+ }+edges: ReadonlyArray<ScreenEdge>;edgeRegion: number;/** The physical edge the current gesture started from. */diff --git a/packages/core/src/gestures/SwipeGestureRecognizer.ts b/packages/core/src/gestures/SwipeGestureRecognizer.tsindex d4b83bc072..51d4f1cbf9 100644--- a/packages/core/src/gestures/SwipeGestureRecognizer.ts+++ b/packages/core/src/gestures/SwipeGestureRecognizer.ts@@ -41,6 +41,10 @@ export interface SwipeGestureRecognizerOptions extends GestureRecognizerOptions<const SWIPE = UIKIT_SWIPE;export class SwipeGestureRecognizer extends GestureRecognizer {+ override get kind(): GestureRecognizer['kind'] {+ return 'swipe';+ }+directions: ReadonlyArray<SwipeDirection>;numberOfTouchesRequired: number;minimumDistance: number;diff --git a/packages/core/src/gestures/TapGestureRecognizer.ts b/packages/core/src/gestures/TapGestureRecognizer.tsindex 1d27e57912..a8acc09ab6 100644--- a/packages/core/src/gestures/TapGestureRecognizer.ts+++ b/packages/core/src/gestures/TapGestureRecognizer.ts@@ -43,6 +43,10 @@ export interface TapGestureRecognizerOptions extends GestureRecognizerOptions<Taconst TAP = UIKIT_TAP;export class TapGestureRecognizer extends GestureRecognizer {+ override get kind(): GestureRecognizer['kind'] {+ return 'tap';+ }+numberOfTapsRequired: number;numberOfTouchesRequired: number;allowableMovement: number;diff --git a/packages/core/src/gestures/__tests__/GestureHost.test.ts b/packages/core/src/gestures/__tests__/GestureHost.test.tsnew file mode 100644index 0000000000..cae31eb550--- /dev/null+++ b/packages/core/src/gestures/__tests__/GestureHost.test.ts@@ -0,0 +1,2087 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file GestureHost.test.ts+ * @input A GestureHost on the jsdom document, real DOM listeners, and+ * dispatched touch, pointer, click, contextmenu and scroll events with+ * explicit timestamps+ * @output The DOM integration: hit-path collection (shadow DOM included),+ * touch-action negotiation, cancelling touchmove only while claimed,+ * click suppression and replay, browser takeover, the mouse path,+ * context menus, focus loss+ * @position jsdom integration tests of packages/core/src/gestures+ */++import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import {UIKIT_GESTURES} from '../../motion/uikit/gestures';+import {GestureHost} from '../GestureHost';+import {LongPressGestureRecognizer} from '../LongPressGestureRecognizer';+import {PanGestureRecognizer} from '../PanGestureRecognizer';+import {ScreenEdgePanGestureRecognizer} from '../ScreenEdgePanGestureRecognizer';+import {TapGestureRecognizer} from '../TapGestureRecognizer';+import {ManualClock, RecordingConsumer} from './harness';+import type {GestureTouch} from '../types';++interface Contact {+ id: number;+ x: number;+ y: number;+ target?: EventTarget;+}++function touch(+ type: 'touchstart' | 'touchmove' | 'touchend' | 'touchcancel',+ target: EventTarget,+ changed: Contact[],+ all: Contact[],+ time: number,+ cancelable = true,+): Event {+ const event = new Event(type, {bubbles: true, cancelable, composed: true});+ const toTouch = (contact: Contact) => ({+ identifier: contact.id,+ clientX: contact.x,+ clientY: contact.y,+ target: contact.target ?? target,+ });+ Object.defineProperty(event, 'changedTouches', {value: changed.map(toTouch)});+ Object.defineProperty(event, 'touches', {value: all.map(toTouch)});+ Object.defineProperty(event, 'timeStamp', {value: time});+ target.dispatchEvent(event);+ return event;+}++function pointer(+ type: string,+ target: EventTarget,+ init: {+ id?: number;+ pointerType: string;+ x: number;+ y: number;+ buttons?: number;+ time: number;+ },+): Event {+ const event = new PointerEvent(type, {+ bubbles: true,+ cancelable: true,+ composed: true,+ pointerId: init.id ?? 1,+ pointerType: init.pointerType,+ clientX: init.x,+ clientY: init.y,+ button: 0,+ buttons: init.buttons ?? 0,+ });+ Object.defineProperty(event, 'timeStamp', {value: init.time});+ target.dispatchEvent(event);+ return event;+}++let host: GestureHost;+let clock: ManualClock;+let detachers: (() => void)[];++/** jsdom computes no layout: give a scroller its metrics. */+function scrollable(+ element: HTMLElement,+ metrics: {scrollTop?: number; scrollHeight?: number; clientHeight?: number},+): void {+ for (const [key, value] of Object.entries(metrics)) {+ Object.defineProperty(element, key, {configurable: true, value});+ }+}++/**+ * jsdom drops `touch-action` from styles: elements under test carry it in+ * `data-touch-action`, and computed style reports it from there.+ */+function touchActionFromData(): () => void {+ const original = window.getComputedStyle.bind(window);+ const spy = vi+ .spyOn(window, 'getComputedStyle')+ .mockImplementation((element: Element, pseudo?: string | null) => {+ const style = original(element, pseudo);+ // The author's rule outranks the host's zero-specificity rule, which+ // applies where the author sets nothing.+ const touchAction =+ element.getAttribute('data-touch-action') ??+ element.getAttribute('data-astryx-touch-action');+ if (touchAction == null) {+ return style;+ }+ return new Proxy(style, {+ get(target, key): string | number | object | null | undefined {+ if (key === 'touchAction') {+ return touchAction;+ }+ if (key === 'getPropertyValue') {+ return (name: string) =>+ name === 'touch-action'+ ? touchAction+ : target.getPropertyValue(name);+ }+ const value = Reflect.get(target, key) as+ string | number | object | null | undefined;+ return typeof value === 'function' ? value.bind(target) : value;+ },+ });+ });+ return () => spy.mockRestore();+}++/** The host's touch-action rules in a document or shadow root. */+function hostRules(root: Document | ShadowRoot): string {+ const adopted = (root.adoptedStyleSheets ?? []).flatMap(sheet =>+ [...sheet.cssRules].map(rule => rule.cssText),+ );+ const styles = [...root.querySelectorAll('style')].map(+ style => style.textContent ?? '',+ );+ return [...adopted, ...styles].join('\n');+}++function mount(html: string): Record<string, HTMLElement> {+ document.body.innerHTML = html;+ const elements: Record<string, HTMLElement> = {};+ for (const element of document.querySelectorAll<HTMLElement>('[id]')) {+ elements[element.id] = element;+ }+ return elements;+}++beforeEach(() => {+ clock = new ManualClock();+ host = new GestureHost(document, {clock, isPrimaryPointerCoarse: () => true});+ detachers = [];+});++afterEach(() => {+ for (const detach of detachers) {+ detach();+ }+ document.body.innerHTML = '';+});++describe('GestureHost', () => {+ it("measures a screen-edge pan's view, so an edge-zone strip takes the axis at UIKit's 15 px, not 10 (spec:AST-094 FR18)", () => {+ const {strip} = mount('<div id="strip"></div>');+ strip.getBoundingClientRect = () =>+ DOMRect.fromRect({x: 0, y: 0, width: 40, height: 800});+ const pan = new ScreenEdgePanGestureRecognizer({+ name: 'edge',+ edges: ['leading'],+ });+ detachers.push(host.attach(strip, pan));+ const down = {id: 1, x: 5, y: 300};+ touch('touchstart', strip, [down], [down], 0);+ const at14 = {...down, x: 19};+ touch('touchmove', strip, [at14], [at14], 16);+ expect(pan.state).toBe('possible');+ const at15 = {...down, x: 20};+ touch('touchmove', strip, [at15], [at15], 32);+ expect(pan.state).toBe('began');+ touch('touchend', strip, [at15], [], 48);+ });++ it("re-derives a screen-edge pan's touch-action when its box or the viewport resizes, with no listener of its own (spec:AST-094 FR19, FR24, DEC-22)", () => {+ // jsdom has no ResizeObserver: a stand-in the test drives.+ const observed = new Set<Element>();+ const callbacks: (() => void)[] = [];+ class StandInResizeObserver {+ constructor(callback: () => void) {+ callbacks.push(callback);+ }+ observe(target: Element): void {+ observed.add(target);+ }+ unobserve(target: Element): void {+ observed.delete(target);+ }+ disconnect(): void {+ observed.clear();+ }+ }+ const original = Object.getOwnPropertyDescriptor(window, 'ResizeObserver');+ const width = Object.getOwnPropertyDescriptor(window, 'innerWidth');+ Object.defineProperty(window, 'ResizeObserver', {+ configurable: true,+ value: StandInResizeObserver,+ });+ const listen = vi.spyOn(window, 'addEventListener');+ try {+ const {strip, trail} = mount(+ '<div id="strip"></div><div id="trail"></div>',+ );+ let stripWidth = 40;+ strip.getBoundingClientRect = () =>+ DOMRect.fromRect({x: 0, y: 0, width: stripWidth, height: 800});+ trail.getBoundingClientRect = () =>+ DOMRect.fromRect({x: 1004, y: 0, width: 20, height: 800});+ Object.defineProperty(window, 'innerWidth', {+ configurable: true,+ value: 1024,+ });+ const leading = new ScreenEdgePanGestureRecognizer({name: 'edge'});+ const detachStrip = host.attach(strip, leading);+ // A leading pan in LTR watches the left side: the viewport cannot move+ // its band, so only its own box is watched.+ expect(observed).toEqual(new Set([strip]));+ const trailing = new ScreenEdgePanGestureRecognizer({+ name: 'back',+ edges: ['trailing'],+ });+ const detachTrail = host.attach(trail, trailing);+ // The trailing pan's band moves with the viewport: the root is watched.+ expect(observed).toEqual(+ new Set([strip, trail, document.documentElement]),+ );+ expect(strip.getAttribute('data-astryx-touch-action')).toBe(+ 'pan-y pinch-zoom',+ );+ expect(trail.getAttribute('data-astryx-touch-action')).toBe(+ 'pan-y pinch-zoom',+ );+ // The strip grows past the band: its claim goes.+ stripWidth = 390;+ callbacks.forEach(callback => callback());+ expect(strip.hasAttribute('data-astryx-touch-action')).toBe(false);+ // The viewport widens, so the root resizes: the trailing strip no+ // longer sits at its edge.+ Object.defineProperty(window, 'innerWidth', {+ configurable: true,+ value: 1280,+ });+ callbacks.forEach(callback => callback());+ expect(trail.hasAttribute('data-astryx-touch-action')).toBe(false);+ // A disabled pan is not watched (FR24).+ trailing.setEnabled(false);+ expect(observed).toEqual(new Set([strip]));+ // Nothing is watched once the last edge pan lets go, and no listener+ // was ever added for a resize.+ detachStrip();+ detachTrail();+ expect(observed.size).toBe(0);+ expect(listen).not.toHaveBeenCalledWith(+ 'resize',+ expect.anything(),+ expect.anything(),+ );+ } finally {+ listen.mockRestore();+ if (original == null) {+ delete (window as {ResizeObserver?: unknown}).ResizeObserver;+ } else {+ Object.defineProperty(window, 'ResizeObserver', original);+ }+ if (width != null) {+ Object.defineProperty(window, 'innerWidth', width);+ }+ }+ });++ it('tells a recognizer tracking a finger about a second finger on plain page content, and leaves that finger to the page (spec:AST-094 FR28)', () => {+ const {box} = mount('<div id="box"></div><p id="page">text</p>');+ const page = document.getElementById('page')!;+ const elsewhere: number[] = [];+ class Recorder extends LongPressGestureRecognizer {+ protected override touchBeganElsewhere(+ touches: ReadonlyArray<GestureTouch>,+ ): void {+ elsewhere.push(...touches.map(t => t.id));+ }+ }+ const recorder = new Recorder({name: 'recorder'});+ detachers.push(host.attach(box, recorder));+ const first = {id: 1, x: 10, y: 10};+ touch('touchstart', box, [first], [first], 0);+ const second = {id: 2, x: 200, y: 300};+ const start = touch('touchstart', page, [second], [first, second], 20);+ expect(elsewhere).toHaveLength(1);+ expect(start.defaultPrevented).toBe(false);+ const moved = {...second, y: 340};+ const move = touch('touchmove', page, [moved], [first, moved], 36);+ expect(move.defaultPrevented).toBe(false);+ const end = touch('touchend', page, [moved], [first], 50);+ expect(end.defaultPrevented).toBe(false);+ touch('touchend', box, [first], [], 60);+ });++ it('leaves a finger on plain page content alone when no finger is being tracked', () => {+ const {box} = mount('<div id="box"></div><p id="page">text</p>');+ const page = document.getElementById('page')!;+ const elsewhere: number[] = [];+ class Recorder extends LongPressGestureRecognizer {+ protected override touchBeganElsewhere(+ touches: ReadonlyArray<GestureTouch>,+ ): void {+ elsewhere.push(...touches.map(t => t.id));+ }+ }+ detachers.push(host.attach(box, new Recorder({name: 'recorder'})));+ const finger = {id: 1, x: 200, y: 300};+ touch('touchstart', page, [finger], [finger], 0);+ touch('touchend', page, [finger], [], 30);+ expect(elsewhere).toEqual([]);+ });++ it("does not read a recognizer's own scroll write as the browser taking the finger (spec:AST-094 FR30)", async () => {+ const {list} = mount('<div id="list"><div id="row"></div></div>');+ scrollable(list, {scrollHeight: 1000, clientHeight: 200});+ const row = document.getElementById('row')!;+ // Tolerant enough to keep tracking a finger that has travelled the+ // press slop: only such a finger's touch can be the browser's pan.+ const press = new LongPressGestureRecognizer({+ name: 'press',+ allowableMovement: 100,+ });+ detachers.push(host.attach(row, press));+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', row, [finger], [finger], 0);+ const moved = {...finger, y: 40};+ touch('touchmove', row, [moved], [moved], 16);+ host.ownScroll(list);+ list.dispatchEvent(new Event('scroll'));+ expect(press.numberOfTouches).toBe(1);+ // After the next frame, a scroll nobody announced is the browser's again.+ await new Promise(resolve =>+ requestAnimationFrame(() => requestAnimationFrame(resolve)),+ );+ await new Promise(resolve => requestAnimationFrame(resolve));+ list.dispatchEvent(new Event('scroll'));+ expect(press.numberOfTouches).toBe(0);+ });++ it('watches the pointer kind only while something is attached (spec:AST-094 FR24)', () => {+ const {box} = mount('<div id="box"></div>');+ const add = vi.fn();+ const remove = vi.fn();+ const matchMedia = window.matchMedia;+ window.matchMedia = ((query: string) => ({+ matches: false,+ media: query,+ addEventListener: add,+ removeEventListener: remove,+ })) as unknown as typeof window.matchMedia;+ try {+ const host2 = new GestureHost(document, {clock});+ expect(add).not.toHaveBeenCalled();+ const detach = host2.attach(box, new PanGestureRecognizer());+ expect(add).toHaveBeenCalledTimes(1);+ detach();+ expect(remove).toHaveBeenCalledWith('change', add.mock.calls[0][1]);+ } finally {+ window.matchMedia = matchMedia;+ }+ });++ it('sets touch-action for every pointer while a recognizer is enabled (spec:AST-094 FR18, FR43)', () => {+ const {box} = mount('<div id="box"></div>');+ const mark = () => box.getAttribute('data-astryx-touch-action');+ let coarse = false;+ const host2 = new GestureHost(document, {+ clock,+ isPrimaryPointerCoarse: () => coarse,+ });+ const pan = new PanGestureRecognizer({direction: 'horizontal'});+ const detach = host2.attach(box, pan);+ // A touchscreen laptop's finger gets it as a phone's does.+ expect(mark()).toBe('pan-y pinch-zoom');+ pan.setEnabled(false);+ expect(mark()).toBeNull();+ pan.setEnabled(true);+ expect(mark()).toBe('pan-y pinch-zoom');+ coarse = true;+ host2.update(box);+ expect(mark()).toBe('pan-y pinch-zoom');+ detach();+ expect(mark()).toBeNull();+ });++ it('registers no document listener for a disabled consumer until it is enabled (spec:AST-094 FR24)', () => {+ const {box} = mount('<div id="box"></div>');+ const added = vi.spyOn(document, 'addEventListener');+ const removed = vi.spyOn(document, 'removeEventListener');+ added.mockClear();+ removed.mockClear();+ const types = (spy: typeof added) =>+ spy.mock.calls+ .map(call => call[0])+ .filter(t => /^(touch|pointer)/.test(t));+ const coarse = new GestureHost(document, {+ clock,+ isPrimaryPointerCoarse: () => true,+ });+ let enabled = false;+ const consumer = new RecordingConsumer();+ Object.assign(consumer, {isEnabled: () => enabled});+ const detach = coarse.attachConsumer(box, consumer);+ expect(types(added)).toEqual([]);+ enabled = true;+ coarse.update(box);+ expect(types(added)).toContain('touchstart');+ enabled = false;+ coarse.update(box);+ expect(types(removed)).toContain('touchstart');+ detach();+ });++ it('registers no page listener while idle where the primary pointer is fine, or while nothing enabled is attached (spec:AST-094 FR24, FR43)', () => {+ const {box} = mount('<div id="box"></div>');+ const added = vi.spyOn(document, 'addEventListener');+ const removed = vi.spyOn(document, 'removeEventListener');+ added.mockClear();+ removed.mockClear();+ const types = (spy: typeof added) =>+ spy.mock.calls+ .map(call => call[0])+ .filter(t => /^(touch|pointer)/.test(t));+ // A fine primary pointer: the page has no listener; the element keeps+ // one passive pointerdown for its press and, as a claimer, its blocking+ // touchmove (FR19, a listener FR24 counts apart).+ const fine = new GestureHost(document, {+ clock,+ isPrimaryPointerCoarse: () => false,+ });+ const boxAdded = vi.spyOn(box, 'addEventListener');+ const detachFine = fine.attach(box, new PanGestureRecognizer());+ expect(types(added)).toEqual([]);+ expect(boxAdded.mock.calls.map(call => [call[0], call[2]])).toEqual([+ ['touchmove', {passive: false}],+ ['pointerdown', {capture: true, passive: true}],+ ]);+ detachFine();+ boxAdded.mockClear();+ // A coarse one, with only a disabled recognizer: nothing at all.+ const coarse = new GestureHost(document, {+ clock,+ isPrimaryPointerCoarse: () => true,+ });+ const pan = new PanGestureRecognizer({isEnabled: false});+ const detach = coarse.attach(box, pan);+ expect(types(added)).toEqual([]);+ expect(boxAdded).not.toHaveBeenCalled();+ // Enabling it registers the listeners; disabling removes them.+ pan.setEnabled(true);+ expect(types(added)).toContain('touchstart');+ expect(boxAdded).toHaveBeenCalledWith('touchmove', expect.any(Function), {+ passive: false,+ });+ pan.setEnabled(false);+ expect(types(removed)).toContain('touchstart');+ detach();+ });++ it('sets touch-action on attach and restores it on detach; the long-press styles wait for a held press', () => {+ // The author's value is read in the next frame (FR18): fake the frame.+ vi.useFakeTimers({toFake: ['setTimeout', 'requestAnimationFrame']});+ detachers.push(() => vi.useRealTimers());+ const {box} = mount('<div id="box" style="color: red"></div>');+ const set = vi.spyOn(box.style, 'setProperty');+ const remove = vi.spyOn(box.style, 'removeProperty');+ const detachPan = host.attach(+ box,+ new PanGestureRecognizer({direction: 'horizontal'}),+ );+ const detachPress = host.attach(box, new LongPressGestureRecognizer());+ vi.advanceTimersByTime(16);+ expect(set).toHaveBeenCalledWith('touch-action', 'pan-y pinch-zoom');+ expect(set).not.toHaveBeenCalledWith('-webkit-touch-callout', 'none');+ detachPress();+ detachPan();+ expect(remove).toHaveBeenCalledWith('touch-action');+ });+ it("writes a touch-action no wider than the caller's own", () => {+ vi.useFakeTimers({toFake: ['setTimeout', 'requestAnimationFrame']});+ const restore = touchActionFromData();+ try {+ const {trigger, strip} = mount(+ '<div id="trigger" data-touch-action="none"></div><div id="strip" data-touch-action="pan-y"></div>',+ );+ const set = vi.spyOn(trigger.style, 'setProperty');+ const setStrip = vi.spyOn(strip.style, 'setProperty');+ detachers.push(+ host.attach(trigger, new LongPressGestureRecognizer({name: 'hold'})),+ host.attach(+ strip,+ new PanGestureRecognizer({name: 'h', direction: 'horizontal'}),+ ),+ );+ vi.advanceTimersByTime(16);+ // manipulation (the hold's) with none, and pan-y pinch-zoom (the+ // pan's) with pan-y, allow the caller's own: its rule stays in force.+ expect(window.getComputedStyle(trigger).touchAction).toBe('none');+ expect(window.getComputedStyle(strip).touchAction).toBe('pan-y');+ expect(set).not.toHaveBeenCalledWith('touch-action', expect.anything());+ expect(setStrip).not.toHaveBeenCalledWith(+ 'touch-action',+ expect.anything(),+ );+ } finally {+ restore();+ vi.useRealTimers();+ }+ });+ it('marks an element with its derived touch-action as it attaches, under a rule any author rule outranks, with no inline write and no style read (spec:AST-094 FR18, DEC-8)', () => {+ const restore = touchActionFromData();+ try {+ const {box} = mount('<div id="box"></div>');+ const set = vi.spyOn(box.style, 'setProperty');+ const read = vi.mocked(window.getComputedStyle);+ read.mockClear();+ detachers.push(+ host.attach(box, new PanGestureRecognizer({direction: 'horizontal'})),+ );+ expect(box.getAttribute('data-astryx-touch-action')).toBe(+ 'pan-y pinch-zoom',+ );+ expect(hostRules(document)).toContain(+ ':where([data-astryx-touch-action="pan-y pinch-zoom"])',+ );+ expect(set).not.toHaveBeenCalledWith('touch-action', expect.anything());+ expect(read).not.toHaveBeenCalled();+ } finally {+ restore();+ }+ });+ it('leaves no touch-action rule in a document or shadow root once its last marked element lets go (spec:AST-094 FR24)', () => {+ const restore = touchActionFromData();+ try {+ const {box, other, outer} = mount(+ '<div id="box"></div><div id="other"></div><div id="outer"></div>',+ );+ const shadow = outer.attachShadow({mode: 'open'});+ shadow.innerHTML = '<div id="inner"></div>';+ const inner = shadow.getElementById('inner') as HTMLElement;+ const releaseBox = host.attach(+ box,+ new PanGestureRecognizer({direction: 'horizontal'}),+ );+ const releaseOther = host.attach(+ other,+ new PanGestureRecognizer({direction: 'vertical'}),+ );+ const releaseInner = host.attach(+ inner,+ new PanGestureRecognizer({direction: 'horizontal'}),+ );+ expect(hostRules(document)).toContain('data-astryx-touch-action');+ expect(hostRules(shadow)).toContain('data-astryx-touch-action');+ // One element still marked keeps its root's rules.+ releaseBox();+ expect(hostRules(document)).toContain('data-astryx-touch-action');+ releaseOther();+ expect(hostRules(document)).not.toContain('data-astryx-touch-action');+ releaseInner();+ expect(hostRules(shadow)).not.toContain('data-astryx-touch-action');+ // A later attach brings its rule back.+ detachers.push(+ host.attach(box, new PanGestureRecognizer({direction: 'horizontal'})),+ );+ expect(hostRules(document)).toContain(+ ':where([data-astryx-touch-action="pan-y pinch-zoom"])',+ );+ } finally {+ restore();+ }+ });+ it("keeps an author rule in force from the first frame, and writes the intersection inline only where it is narrower than the author's (spec:AST-094 FR18)", () => {+ vi.useFakeTimers({toFake: ['setTimeout', 'requestAnimationFrame']});+ const restore = touchActionFromData();+ try {+ const {both, strip} = mount(+ '<div id="both" data-touch-action="pan-x pan-y"></div><div id="strip" data-touch-action="pan-y"></div>',+ );+ const setBoth = vi.spyOn(both.style, 'setProperty');+ const setStrip = vi.spyOn(strip.style, 'setProperty');+ detachers.push(+ host.attach(both, new PanGestureRecognizer({direction: 'horizontal'})),+ host.attach(strip, new PanGestureRecognizer({direction: 'horizontal'})),+ );+ // Before the host reads anything, the author's value stands.+ expect(both.getAttribute('data-astryx-touch-action')).toBe(+ 'pan-y pinch-zoom',+ );+ expect(window.getComputedStyle(both).touchAction).toBe('pan-x pan-y');+ expect(setBoth).not.toHaveBeenCalledWith(+ 'touch-action',+ expect.anything(),+ );+ vi.advanceTimersByTime(16);+ // pan-y pinch-zoom with pan-x pan-y allows pan-y: narrower than the+ // author's, so it is written.+ expect(setBoth).toHaveBeenLastCalledWith('touch-action', 'pan-y');+ // With pan-y it is the author's own value: nothing to write.+ expect(setStrip).not.toHaveBeenCalledWith(+ 'touch-action',+ expect.anything(),+ );+ } finally {+ restore();+ vi.useRealTimers();+ }+ });+ for (const {keyword, resolved, make, written} of [+ {+ keyword: 'initial',+ resolved: 'auto',+ make: () => new TapGestureRecognizer({name: 'tap'}),+ written: 'manipulation',+ },+ {+ keyword: 'inherit',+ resolved: 'pan-y',+ make: () =>+ new PanGestureRecognizer({name: 'h', direction: 'horizontal'}),+ written: null,+ },+ ]) {+ it(`reads a caller's inline \`touch-action: ${keyword}\` as what it resolves to, never intersecting the keyword itself (spec:AST-094 FR18, DEC-8)`, () => {+ vi.useFakeTimers({toFake: ['setTimeout', 'requestAnimationFrame']});+ const restore = touchActionFromData();+ try {+ // jsdom keeps no touch-action: the inline keyword stands in through+ // getPropertyValue, and what it resolves to through computed style.+ const {box} = mount(+ `<div id="box" data-touch-action="${resolved}"></div>`,+ );+ vi.spyOn(box.style, 'getPropertyValue').mockImplementation(name =>+ name === 'touch-action' ? keyword : '',+ );+ const set = vi.spyOn(box.style, 'setProperty');+ detachers.push(host.attach(box, make()));+ // A keyword names no touch-action of its own: nothing is written+ // from it at once, and never none.+ expect(set).not.toHaveBeenCalledWith('touch-action', expect.anything());+ vi.advanceTimersByTime(16);+ expect(set).not.toHaveBeenCalledWith('touch-action', 'none');+ if (written == null) {+ // What the derived value allows of it is its own value: nothing+ // to narrow.+ expect(set).not.toHaveBeenCalledWith(+ 'touch-action',+ expect.anything(),+ );+ } else {+ expect(set).toHaveBeenLastCalledWith('touch-action', written);+ }+ } finally {+ restore();+ vi.useRealTimers();+ }+ });+ }+ it('removes the mark when the last recognizer detaches', () => {+ const {box} = mount('<div id="box"></div>');+ const detach = host.attach(+ box,+ new PanGestureRecognizer({direction: 'horizontal'}),+ );+ expect(box.hasAttribute('data-astryx-touch-action')).toBe(true);+ detach();+ expect(box.hasAttribute('data-astryx-touch-action')).toBe(false);+ });+ it('adds the rule to the shadow root an element is in', () => {+ const {box} = mount('<div id="box"></div>');+ const shadow = box.attachShadow({mode: 'open'});+ const inner = document.createElement('div');+ shadow.append(inner);+ detachers.push(host.attach(inner, new LongPressGestureRecognizer()));+ expect(inner.getAttribute('data-astryx-touch-action')).toBe('manipulation');+ expect(hostRules(shadow)).toContain(+ ':where([data-astryx-touch-action="manipulation"])',+ );+ });+ it("is never wider than the author's touch-action, at any frame (spec:AST-094 FR18, DEC-8)", () => {+ vi.useFakeTimers({toFake: ['setTimeout', 'requestAnimationFrame']});+ const restore = touchActionFromData();+ try {+ const {trigger} = mount(+ '<div id="trigger" data-touch-action="none"></div>',+ );+ const set = vi.spyOn(trigger.style, 'setProperty');+ detachers.push(+ host.attach(trigger, new LongPressGestureRecognizer({name: 'hold'})),+ );+ // The author's none outranks the host's manipulation from the attach+ // on, and the read finds nothing to narrow.+ expect(window.getComputedStyle(trigger).touchAction).toBe('none');+ vi.advanceTimersByTime(16);+ expect(window.getComputedStyle(trigger).touchAction).toBe('none');+ expect(set).not.toHaveBeenCalledWith('touch-action', expect.anything());+ } finally {+ restore();+ vi.useRealTimers();+ }+ });+ it('gives an element attached while on screen its touch-action in the attach itself', () => {+ const restore = touchActionFromData();+ try {+ const {box} = mount('<div id="box"></div>');+ detachers.push(host.attach(box, new TapGestureRecognizer({name: 'tap'})));+ expect(window.getComputedStyle(box).touchAction).toBe('manipulation');+ } finally {+ restore();+ }+ });+ it("reads no computed style while attaching: a caller's inline touch-action applies at once, a stylesheet's is read in the next frame", () => {+ vi.useFakeTimers({toFake: ['setTimeout', 'requestAnimationFrame']});+ const restore = touchActionFromData();+ try {+ const {trigger, strip} = mount(+ '<div id="trigger" data-touch-action="none"></div><div id="strip"></div>',+ );+ // jsdom keeps no touch-action in a style: this stands in for the+ // caller's inline `touch-action: pan-y`.+ vi.spyOn(strip.style, 'getPropertyValue').mockImplementation(name =>+ name === 'touch-action' ? 'pan-y' : '',+ );+ const set = vi.spyOn(trigger.style, 'setProperty');+ const setStrip = vi.spyOn(strip.style, 'setProperty');+ const read = vi.mocked(window.getComputedStyle);+ read.mockClear();+ detachers.push(+ host.attach(trigger, new LongPressGestureRecognizer({name: 'hold'})),+ host.attach(+ strip,+ new PanGestureRecognizer({name: 'h', direction: 'horizontal'}),+ ),+ );+ // Attaching forces no style recalc over whatever just mounted.+ expect(read).not.toHaveBeenCalled();+ // The caller's inline value: pan-y pinch-zoom ∩ pan-y, at once.+ expect(setStrip).toHaveBeenLastCalledWith('touch-action', 'pan-y');+ // A stylesheet's value: read once in the next frame, where none is+ // already no wider than both allow.+ vi.advanceTimersByTime(16);+ expect(read).toHaveBeenCalledTimes(1);+ expect(set).not.toHaveBeenCalledWith('touch-action', expect.anything());+ } finally {+ restore();+ vi.useRealTimers();+ }+ });++ it('turns selection and the callout off for one held press, only where the hold does something (spec:AST-094 FR41)', () => {+ const {hold, plain} = mount(+ '<div><div id="hold"></div><div id="plain"></div></div>',+ );+ detachers.push(host.attach(hold, new LongPressGestureRecognizer()));+ detachers.push(host.attach(plain, new TapGestureRecognizer()));+ // jsdom drops the prefixed properties, so the writes are observed.+ const set = vi.spyOn(hold.style, 'setProperty');+ const remove = vi.spyOn(hold.style, 'removeProperty');+ const plainSet = vi.spyOn(plain.style, 'setProperty');+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', hold, [finger], [finger], 0);+ expect(set).toHaveBeenCalledWith('-webkit-touch-callout', 'none');+ expect(set).toHaveBeenCalledWith('user-select', 'none');+ expect(remove).not.toHaveBeenCalledWith('user-select');+ touch('touchend', hold, [finger], [], 100);+ expect(remove).toHaveBeenCalledWith('-webkit-touch-callout');+ expect(remove).toHaveBeenCalledWith('user-select');+ const other = {id: 2, x: 10, y: 40};+ touch('touchstart', plain, [other], [other], 200);+ expect(plainSet).not.toHaveBeenCalledWith('user-select', 'none');+ touch('touchend', plain, [other], [], 260);+ });++ it('leaves selection and the callout alone on an element attached with manageStyle: false, whose styles the caller keeps', () => {+ const {hold} = mount('<div id="hold"></div>');+ detachers.push(+ host.attach(hold, new LongPressGestureRecognizer(), {manageStyle: false}),+ );+ const set = vi.spyOn(hold.style, 'setProperty');+ const remove = vi.spyOn(hold.style, 'removeProperty');+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', hold, [finger], [finger], 0);+ touch('touchend', hold, [finger], [], 100);+ expect(set).not.toHaveBeenCalled();+ expect(remove).not.toHaveBeenCalled();+ });++ it('cancels touchmove only once a recognizer owns the touch, and swallows the click', () => {+ const {box, child} = mount('<div id="box"><span id="child">x</span></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ const states: string[] = [];+ pan.addListener(r => states.push(r.state));+ detachers.push(host.attach(box, pan));+ const finger = {id: 7, x: 10, y: 10};+ touch('touchstart', child, [finger], [finger], 0);+ const early = touch(+ 'touchmove',+ child,+ [{...finger, x: 15}],+ [{...finger, x: 15}],+ 16,+ );+ expect(early.defaultPrevented).toBe(false);+ expect(pan.state).toBe('possible');+ const claimed = touch(+ 'touchmove',+ child,+ [{...finger, x: 30}],+ [{...finger, x: 30}],+ 32,+ );+ expect(claimed.defaultPrevented).toBe(true);+ expect(states).toEqual(['began']);+ const end = touch('touchend', child, [{...finger, x: 30}], [], 48);+ expect(end.defaultPrevented).toBe(true);+ expect(states).toEqual(['began', 'ended']);+ });++ it('leaves the touchend (and the click) alone when nothing claimed the touch', () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ detachers.push(host.attach(box, pan));+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ touch('touchmove', box, [{...finger, x: 13}], [{...finger, x: 13}], 16);+ const end = touch('touchend', box, [{...finger, x: 13}], [], 40);+ expect(end.defaultPrevented).toBe(false);+ });++ it('leaves a second finger no recognizer owns to the page while the claimed one is held (spec:AST-094 FR19)', () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({maximumNumberOfTouches: 1});+ detachers.push(host.attach(box, pan));+ const first = {id: 1, x: 10, y: 10};+ touch('touchstart', box, [first], [first], 0);+ const moved = {...first, x: 40};+ touch('touchmove', box, [moved], [moved], 16);+ const second = {id: 2, x: 200, y: 200};+ touch('touchstart', box, [second], [moved, second], 20);+ const pinchLike = touch(+ 'touchmove',+ box,+ [{...second, x: 260}],+ [moved, {...second, x: 260}],+ 32,+ );+ expect(pinchLike.defaultPrevented).toBe(false);+ expect(pan.state).toBe('began');+ expect(pan.numberOfTouches).toBe(1);+ // The claimed finger's own moves stay cancelled.+ const own = touch(+ 'touchmove',+ box,+ [{...moved, x: 60}],+ [+ {...moved, x: 60},+ {...second, x: 260},+ ],+ 48,+ );+ expect(own.defaultPrevented).toBe(true);+ });++ it('reads pointercancel on a finger as the browser taking it', () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ const view = new RecordingConsumer();+ const events: string[] = [];+ detachers.push(host.attach(box, pan), host.attachConsumer(box, view));+ pan.addTransitionListener((_r, _from, to) => events.push(to));+ const finger = {id: 3, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ pointer('pointercancel', box, {+ id: 99,+ pointerType: 'touch',+ x: 10,+ y: 14,+ time: 20,+ });+ expect(events).toEqual(['failed', 'possible']);+ // The view's touch is cancelled, with no release.+ expect(view.events.map(event => event.split(':')[0])).toEqual([+ 'began',+ 'cancelled',+ ]);+ });++ it("pairs a finger's pointer with its touch: pointermoves inside the browser's touchmove slop count", () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ const states: string[] = [];+ pan.addListener(r => states.push(`${r.state}:${r.translation().x}`));+ detachers.push(host.attach(box, pan));+ // Chromium's order: pointerdown, then touchstart, at the same spot.+ pointer('pointerdown', box, {+ id: 21,+ pointerType: 'touch',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ const finger = {id: 0, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ // No touchmove yet (inside the slop), but the pointer moved 12 px.+ pointer('pointermove', box, {+ id: 21,+ pointerType: 'touch',+ x: 16,+ y: 10,+ buttons: 1,+ time: 16,+ });+ pointer('pointermove', box, {+ id: 21,+ pointerType: 'touch',+ x: 22,+ y: 10,+ buttons: 1,+ time: 32,+ });+ // Translation 2: the 10 px hysteresis is left out, as in UIKit.+ expect(states).toEqual(['began:2']);+ // The first touchmove (the same input as a pointermove) is cancelled+ // and not read twice.+ pointer('pointermove', box, {+ id: 21,+ pointerType: 'touch',+ x: 26,+ y: 10,+ buttons: 1,+ time: 48,+ });+ const first = touch(+ 'touchmove',+ box,+ [{...finger, x: 26}],+ [{...finger, x: 26}],+ 48,+ );+ expect(first.defaultPrevented).toBe(true);+ expect(states).toEqual(['began:2', 'changed:6']);+ // pointercancel names the finger exactly, whatever its coordinates say.+ pointer('pointercancel', box, {+ id: 21,+ pointerType: 'touch',+ x: 0,+ y: 0,+ time: 60,+ });+ expect(host.arena.getTouch(1)?.takenByBrowser).toBe(true);+ });++ it("gives a finger's target a passive touchmove listener unless a recognizer on that touch can claim while it moves (spec:AST-094 FR19)", () => {+ const {taps, pan} = mount(+ '<div id="taps"><span id="tapChild">t</span></div><div id="pan"><span id="panChild">p</span></div>',+ );+ detachers.push(host.attach(taps, new TapGestureRecognizer({name: 'tap'})));+ detachers.push(host.attach(pan, new PanGestureRecognizer({name: 'pan'})));+ const moveListenerFlags = (element: Element) => {+ const added = vi.spyOn(element, 'addEventListener');+ return () =>+ added.mock.calls+ .filter(([type]) => type === 'touchmove')+ .map(([, , options]) => (options as AddEventListenerOptions).passive);+ };+ const tapChild = taps.querySelector('#tapChild')!;+ const panChild = pan.querySelector('#panChild')!;+ const onTapChild = moveListenerFlags(tapChild);+ const onPanChild = moveListenerFlags(panChild);+ const tapFinger = {id: 1, x: 10, y: 10};+ touch('touchstart', tapChild, [tapFinger], [tapFinger], 0);+ const panFinger = {id: 2, x: 10, y: 10};+ touch('touchstart', panChild, [panFinger], [tapFinger, panFinger], 0);+ expect(onTapChild()).toEqual([true]);+ expect(onPanChild()).toEqual([false]);+ touch('touchend', tapChild, [tapFinger], [panFinger], 20);+ touch('touchend', panChild, [panFinger], [], 20);+ });++ it('gives the blocking touchmove listener only to elements whose recognizers claim while moving', () => {+ const {taps, pan, press, both, row} = mount(+ '<div id="taps"></div><div id="pan"></div><div id="press"></div><div id="both"></div><div id="row"></div>',+ );+ const blocking = (element: HTMLElement) => {+ const added = vi.spyOn(element, 'addEventListener');+ const removed = vi.spyOn(element, 'removeEventListener');+ return {+ added: () =>+ added.mock.calls.filter(([type, , options]) => {+ const flags = options as AddEventListenerOptions | undefined;+ return type === 'touchmove' && flags?.passive === false;+ }).length,+ removed: () =>+ removed.mock.calls.filter(([type]) => type === 'touchmove').length,+ };+ };+ // Taps claim only at the lift: a scroll starting on them never waits.+ const onTaps = blocking(taps);+ detachers.push(host.attach(taps, new TapGestureRecognizer({name: 'tap'})));+ detachers.push(+ host.attach(+ taps,+ new TapGestureRecognizer({name: 'double', numberOfTapsRequired: 2}),+ ),+ );+ expect(onTaps.added()).toBe(0);+ // A press consumer adds none either.+ const onRow = blocking(row);+ detachers.push(host.attachConsumer(row, new RecordingConsumer()));+ expect(onRow.added()).toBe(0);+ // A pan and a long press can take a moving touch: they get one.+ const onPan = blocking(pan);+ detachers.push(host.attach(pan, new PanGestureRecognizer({name: 'pan'})));+ expect(onPan.added()).toBe(1);+ const onPress = blocking(press);+ detachers.push(+ host.attach(press, new LongPressGestureRecognizer({name: 'press'})),+ );+ expect(onPress.added()).toBe(1);+ // A tap beside a pan: the listener comes with the pan and leaves with it.+ const onBoth = blocking(both);+ detachers.push(host.attach(both, new TapGestureRecognizer({name: 'tap2'})));+ expect(onBoth.added()).toBe(0);+ const detachPan = host.attach(+ both,+ new PanGestureRecognizer({name: 'pan2', direction: 'horizontal'}),+ );+ expect(onBoth.added()).toBe(1);+ detachPan();+ expect(onBoth.removed()).toBe(1);+ });++ it("leaves a one-way pan's touch to the page until the pan begins (spec:AST-094 FR19)", () => {+ const {card} = mount('<div id="card"></div>');+ const pan = new PanGestureRecognizer({name: 'pan', direction: 'up'});+ detachers.push(host.attach(card, pan));+ const finger = {id: 1, x: 50, y: 100};+ touch('touchstart', card, [finger], [finger], 0);+ const at = (y: number, time: number) =>+ touch('touchmove', card, [{...finger, y}], [{...finger, y}], time);+ expect(at(97, 16).defaultPrevented).toBe(false);+ expect(at(95, 32).defaultPrevented).toBe(false);+ expect(pan.state).toBe('possible');+ expect(at(88, 48).defaultPrevented).toBe(true);+ expect(pan.state).toBe('began');+ touch('touchend', card, [{...finger, y: 88}], [], 64);+ });++ it('leaves a scroll-edge pan to claim at its begin', () => {+ const {sheet} = mount('<div id="sheet"></div>');+ const pan = new PanGestureRecognizer({+ name: 'sheet',+ direction: 'down',+ scrollEdge: true,+ });+ detachers.push(host.attach(sheet, pan));+ const finger = {id: 1, x: 50, y: 100};+ touch('touchstart', sheet, [finger], [finger], 0);+ const at = (y: number, time: number) =>+ touch('touchmove', sheet, [{...finger, y}], [{...finger, y}], time);+ expect(at(107, 16).defaultPrevented).toBe(false);+ expect(at(112, 32).defaultPrevented).toBe(true);+ expect(pan.state).toBe('began');+ touch('touchend', sheet, [{...finger, y: 112}], [], 48);+ });++ it('names the pointer a finger, a pen or a mouse is driven by', () => {+ const {box} = mount('<div id="box"></div>');+ const press = new LongPressGestureRecognizer({name: 'press'});+ detachers.push(host.attach(box, press));+ // A finger: its pointerdown pairs with its touchstart.+ pointer('pointerdown', box, {+ id: 31,+ pointerType: 'touch',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ const finger = {id: 0, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ const [held] = press.trackedTouches;+ expect(host.pointerIdOf(held)).toBe(31);+ expect(host.pointerIdOf(held.id)).toBe(31);+ touch('touchend', box, [finger], [], 40);+ // A pen is its own pointer.+ pointer('pointerdown', box, {+ id: 7,+ pointerType: 'pen',+ x: 10,+ y: 10,+ buttons: 1,+ time: 100,+ });+ const [pen] = press.trackedTouches;+ expect(host.pointerIdOf(pen)).toBe(7);+ pointer('pointerup', box, {+ id: 7,+ pointerType: 'pen',+ x: 10,+ y: 10,+ time: 140,+ });+ expect(host.pointerIdOf(pen)).toBeNull();+ });++ it('reads a touchmove that can no longer be cancelled as the browser taking it, where it could pan', () => {+ const {list, box} = mount(+ '<div id="list" style="overflow-y: auto"><div id="box"></div></div>',+ );+ scrollable(list, {scrollTop: 0, scrollHeight: 1000, clientHeight: 400});+ const tap = new TapGestureRecognizer({name: 'tap'});+ const events: string[] = [];+ tap.addTransitionListener((_r, _from, to) => events.push(to));+ detachers.push(host.attach(box, tap));+ const finger = {id: 1, x: 10, y: 30};+ touch('touchstart', box, [finger], [finger], 0);+ touch(+ 'touchmove',+ box,+ [{...finger, y: 14}],+ [{...finger, y: 14}],+ 16,+ false,+ );+ expect(events).toEqual(['failed', 'possible']);+ });++ it('keeps a horizontal drag under pan-y when Chromium stops asking after one unconsumed move', () => {+ const restore = touchActionFromData();+ try {+ const {list, row} = mount(+ '<div id="list" style="overflow-y: auto"><div id="row" data-touch-action="pan-y pinch-zoom"></div></div>',+ );+ scrollable(list, {scrollTop: 0, scrollHeight: 1000, clientHeight: 400});+ const consumer = new RecordingConsumer();+ detachers.push(host.attachConsumer(row, consumer));+ const finger = {id: 1, x: 100, y: 30};+ touch('touchstart', row, [finger], [finger], 0);+ // The first move goes unconsumed; Chromium sends the rest uncancelable+ // although pan-y keeps it from panning sideways.+ touch('touchmove', row, [{...finger, x: 120}], [{...finger, x: 120}], 16);+ touch(+ 'touchmove',+ row,+ [{...finger, x: 140, y: 33}],+ [{...finger, x: 140, y: 33}],+ 32,+ false,+ );+ touch(+ 'touchmove',+ row,+ [{...finger, x: 160, y: 35}],+ [{...finger, x: 160, y: 35}],+ 48,+ false,+ );+ expect(consumer.events).toEqual([+ 'began:1',+ 'moved:1',+ 'moved:1',+ 'moved:1',+ ]);+ } finally {+ restore();+ }+ });++ it("judges only the first uncancelable move: a sideways drag that turns vertical stays the page's", () => {+ const restore = touchActionFromData();+ try {+ const {list, row} = mount(+ '<div id="list" style="overflow-y: auto"><div id="row" data-touch-action="pan-y pinch-zoom"></div></div>',+ );+ scrollable(list, {scrollTop: 0, scrollHeight: 1000, clientHeight: 400});+ const consumer = new RecordingConsumer();+ detachers.push(host.attachConsumer(row, consumer));+ const finger = {id: 1, x: 100, y: 100};+ touch('touchstart', row, [finger], [finger], 0);+ touch('touchmove', row, [{...finger, x: 120}], [{...finger, x: 120}], 16);+ touch(+ 'touchmove',+ row,+ [{...finger, x: 130, y: 98}],+ [{...finger, x: 130, y: 98}],+ 32,+ false,+ );+ // Chromium dropped the scroll when it began sideways; the finger+ // turning upward later does not make it a pan.+ touch(+ 'touchmove',+ row,+ [{...finger, x: 132, y: 40}],+ [{...finger, x: 132, y: 40}],+ 48,+ false,+ );+ expect(+ consumer.events.filter(event => event.startsWith('cancelled')),+ ).toEqual([]);+ expect(consumer.events.at(-1)).toBe('moved:1');+ } finally {+ restore();+ }+ });++ it('reads a scroll above an unclaimed touch that has travelled as the browser taking it (spec:AST-094 FR20)', () => {+ const {list, row} = mount('<div id="list"><div id="row"></div></div>');+ const tap = new TapGestureRecognizer({name: 'tap'});+ detachers.push(host.attach(row, tap));+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', row, [finger], [finger], 0);+ const moved = {...finger, y: 20};+ touch('touchmove', row, [moved], [moved], 16);+ list.dispatchEvent(new Event('scroll'));+ expect(tap.state).toBe('possible');+ expect(tap.numberOfTouches).toBe(0);+ });++ it('lets a scroll take an unclaimed touch from 10 px of travel, straight or diagonal, and not before (spec:AST-094 FR20)', () => {+ const takenAfter = (dx: number, dy: number) => {+ const {list, row} = mount('<div id="list"><div id="row"></div></div>');+ const consumer = new RecordingConsumer();+ const detach = host.attachConsumer(row, consumer);+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', row, [finger], [finger], 0);+ const moved = {...finger, x: 10 + dx, y: 10 + dy};+ touch('touchmove', row, [moved], [moved], 16);+ list.dispatchEvent(new Event('scroll'));+ const taken = consumer.events.some(event =>+ event.startsWith('cancelled'),+ );+ touch('touchend', row, [moved], [], 32);+ detach();+ return taken;+ };+ // A still finger: the scroll is the page's own (anchoring, a carousel).+ expect(takenAfter(0, 0)).toBe(false);+ expect(takenAfter(0, 9)).toBe(false);+ expect(takenAfter(0, 10)).toBe(true);+ // 9.9 px and 11.3 px from where it landed.+ expect(takenAfter(7, 7)).toBe(false);+ expect(takenAfter(8, 8)).toBe(true);+ });++ it('drives mouse input through Pointer Events', () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ let released = {x: 0, y: 0};+ pan.addListener(r => {+ if (r.state === 'ended') {+ released = r.velocity();+ }+ });+ detachers.push(host.attach(box, pan));+ pointer('pointerdown', box, {+ pointerType: 'mouse',+ x: 0,+ y: 0,+ buttons: 1,+ time: 0,+ });+ for (let t = 8; t <= 96; t += 8) {+ pointer('pointermove', box, {+ pointerType: 'mouse',+ x: t * 2,+ y: 0,+ buttons: 1,+ time: t,+ });+ }+ pointer('pointerup', box, {pointerType: 'mouse', x: 192, y: 0, time: 104});+ expect(pan.state).toBe('possible');+ expect(released.x).toBeCloseTo(2000, 0);+ });++ it('cancels the context menu while a long press owns the touch', () => {+ const {box} = mount('<div id="box"></div>');+ const press = new LongPressGestureRecognizer({name: 'press'});+ detachers.push(host.attach(box, press));+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ const before = new MouseEvent('contextmenu', {+ bubbles: true,+ cancelable: true,+ });+ box.dispatchEvent(before);+ expect(before.defaultPrevented).toBe(false);+ host.arena.advanceTime(500);+ expect(press.state).toBe('began');+ const during = new MouseEvent('contextmenu', {+ bubbles: true,+ cancelable: true,+ });+ box.dispatchEvent(during);+ expect(during.defaultPrevented).toBe(true);+ });++ it('holds the click of a tap a double tap may claim, and replays it when the double tap fails', () => {+ const {row, button} = mount(+ '<div id="row"><button id="button">Go</button></div>',+ );+ const double = new TapGestureRecognizer({+ name: 'double',+ numberOfTapsRequired: 2,+ });+ detachers.push(host.attach(row, double));+ const clicks: {target: EventTarget | null; detail: number}[] = [];+ button.addEventListener('click', event =>+ clicks.push({target: event.target, detail: event.detail}),+ );+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', button, [finger], [finger], 0);+ const end = touch('touchend', button, [finger], [], 60);+ expect(end.defaultPrevented).toBe(true);+ expect(clicks).toEqual([]);+ const interval = UIKIT_GESTURES.tap.maximumIntervalBetweenTaps.value;+ host.arena.advanceTime(60 + interval);+ expect(clicks).toEqual([{target: button, detail: 1}]);+ });++ it('collects recognizers across shadow roots', () => {+ const {outer} = mount('<div id="outer"></div>');+ const shadow = outer.attachShadow({mode: 'open'});+ shadow.innerHTML = '<span id="inner">x</span>';+ const inner = shadow.getElementById('inner') as HTMLElement;+ const tap = new TapGestureRecognizer({name: 'tap'});+ const actions: string[] = [];+ tap.addListener(r => actions.push(r.state));+ detachers.push(host.attach(outer, tap));+ const finger = {id: 1, x: 5, y: 5, target: inner};+ touch('touchstart', inner, [finger], [finger], 0);+ touch('touchend', inner, [finger], [], 50);+ expect(actions).toEqual(['ended']);+ });++ it('cancels every touch in flight when the window loses focus', () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ const states: string[] = [];+ pan.addListener(r => states.push(r.state));+ detachers.push(host.attach(box, pan));+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ touch('touchmove', box, [{...finger, x: 40}], [{...finger, x: 40}], 16);+ window.dispatchEvent(new Event('blur'));+ expect(states).toEqual(['began', 'cancelled']);+ });++ it('finishes a gesture whose target left the document mid-gesture', () => {+ const {box, child} = mount('<div id="box"><span id="child">x</span></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ const states: string[] = [];+ pan.addListener(r => states.push(r.state));+ detachers.push(host.attach(box, pan));+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', child, [finger], [finger], 0);+ touch('touchmove', child, [{...finger, x: 40}], [{...finger, x: 40}], 16);+ // A re-render replaces the span: its events no longer reach the document.+ child.remove();+ const move = touch(+ 'touchmove',+ child,+ [{...finger, x: 60}],+ [{...finger, x: 60}],+ 32,+ );+ expect(move.defaultPrevented).toBe(true);+ touch('touchend', child, [{...finger, x: 60}], [], 48);+ // The move and the lift after the removal still reached the pan.+ expect(states).toEqual(['began', 'changed', 'ended']);+ expect(host.arena.touches).toEqual([]);+ });++ it('cancels a finger the events say is no longer down', () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ const states: string[] = [];+ pan.addListener(r => states.push(r.state));+ detachers.push(host.attach(box, pan));+ const first = {id: 1, x: 10, y: 10};+ touch('touchstart', box, [first], [first], 0);+ touch('touchmove', box, [{...first, x: 40}], [{...first, x: 40}], 16);+ // Its touchend went to a node outside the document; the next event for+ // another finger no longer lists it.+ const other = {id: 2, x: 300, y: 300};+ touch('touchmove', document.body, [other], [other], 32);+ expect(states).toEqual(['began', 'cancelled']);+ });++ it('treats a reused finger number as a new touch', () => {+ const {box} = mount('<div id="box"></div>');+ const tap = new TapGestureRecognizer({name: 'tap'});+ const states: string[] = [];+ tap.addListener(r => states.push(r.state));+ detachers.push(host.attach(box, tap));+ const finger = {id: 4, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ // No touchend reached us; the same identifier lands again.+ touch('touchstart', box, [finger], [finger], 500);+ touch('touchend', box, [finger], [], 560);+ expect(states).toEqual(['ended']);+ });++ it('cancels every finger on a touchcancel that names none', () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ const states: string[] = [];+ pan.addListener(r => states.push(r.state));+ detachers.push(host.attach(box, pan));+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ touch('touchmove', box, [{...finger, x: 40}], [{...finger, x: 40}], 16);+ box.dispatchEvent(new Event('touchcancel', {bubbles: true}));+ expect(states).toEqual(['began', 'cancelled']);+ });++ it('reads epoch-stamped events on the arena clock', () => {+ const {box} = mount('<div id="box"></div>');+ const pan = new PanGestureRecognizer({name: 'pan'});+ let released = {x: 0, y: 0};+ pan.addListener(r => {+ if (r.state === 'ended') {+ released = r.velocity();+ }+ });+ detachers.push(host.attach(box, pan));+ const epoch = performance.timeOrigin + 5000;+ const finger = {id: 1, x: 0, y: 10};+ touch('touchstart', box, [finger], [finger], epoch);+ for (let t = 8; t <= 96; t += 8) {+ const at = {...finger, x: t};+ touch('touchmove', box, [at], [at], epoch + t);+ }+ touch('touchend', box, [{...finger, x: 96}], [], epoch + 100);+ expect(released.x).toBeCloseTo(1000, 0);+ expect(host.arena.now()).toBeLessThan(1e9);+ });++ it('ignores touches that land outside every attached element', () => {+ const {box, elsewhere} = mount(+ '<div id="box"></div><div id="elsewhere"></div>',+ );+ const pan = new PanGestureRecognizer({name: 'pan'});+ detachers.push(host.attach(box, pan));+ const finger = {id: 1, x: 10, y: 10};+ touch('touchstart', elsewhere, [finger], [finger], 0);+ const move = touch(+ 'touchmove',+ elsewhere,+ [{...finger, x: 60}],+ [{...finger, x: 60}],+ 16,+ );+ expect(move.defaultPrevented).toBe(false);+ expect(host.arena.touches).toEqual([]);+ });+});++describe('every pointer where the primary pointer is fine (spec:AST-094 FR19, FR24, FR43)', () => {+ /** The page listeners live now, by type: what was added and not removed. */+ function pageListeners(): () => string[] {+ const counts = new Map<string, number>();+ for (const target of [document, window] as EventTarget[]) {+ const add = target.addEventListener.bind(target);+ const remove = target.removeEventListener.bind(target);+ vi.spyOn(target, 'addEventListener').mockImplementation(+ (type, listener, options) => {+ counts.set(type, (counts.get(type) ?? 0) + 1);+ add(type, listener, options);+ },+ );+ vi.spyOn(target, 'removeEventListener').mockImplementation(+ (type, listener, options) => {+ counts.set(type, (counts.get(type) ?? 0) - 1);+ remove(type, listener, options);+ },+ );+ }+ return () =>+ [...counts]+ .filter(+ ([type, count]) =>+ count > 0 &&+ /^(touch|pointer|click|blur|scroll|contextmenu|visibilitychange)/.test(+ type,+ ),+ )+ .map(([type]) => type)+ .sort();+ }++ function fineHost(): GestureHost {+ return new GestureHost(document, {+ clock,+ isPrimaryPointerCoarse: () => false,+ });+ }++ /** A button press with the button and modifier given. */+ function press(+ target: EventTarget,+ init: {pointerType: string; button: number; ctrlKey?: boolean},+ ): void {+ const event = new PointerEvent('pointerdown', {+ bubbles: true,+ cancelable: true,+ composed: true,+ pointerId: 9,+ pointerType: init.pointerType,+ clientX: 10,+ clientY: 10,+ button: init.button,+ buttons: init.button === 0 ? 1 : 2,+ ctrlKey: init.ctrlKey ?? false,+ });+ Object.defineProperty(event, 'timeStamp', {value: 0});+ target.dispatchEvent(event);+ }++ afterEach(() => {+ vi.restoreAllMocks();+ vi.useRealTimers();+ });++ it('keeps one passive pointerdown listener on each element that uses a gesture and none on the page while idle; a disabled one keeps none', () => {+ const {box, row, off} = mount(+ '<div id="box"></div><div id="row"></div><div id="off"></div>',+ );+ const live = pageListeners();+ const downs = (element: HTMLElement) => {+ const spy = vi.spyOn(element, 'addEventListener');+ return () => spy.mock.calls.filter(call => call[0] === 'pointerdown');+ };+ const boxDowns = downs(box);+ const rowDowns = downs(row);+ const offAdded = vi.spyOn(off, 'addEventListener');+ const fine = fineHost();+ detachers.push(+ fine.attach(box, new PanGestureRecognizer({direction: 'horizontal'})),+ fine.attach(row, new TapGestureRecognizer()),+ fine.attach(off, new TapGestureRecognizer({isEnabled: false})),+ );+ expect(live()).toEqual([]);+ expect(boxDowns()).toEqual([+ ['pointerdown', expect.any(Function), {capture: true, passive: true}],+ ]);+ expect(rowDowns()).toHaveLength(1);+ expect(offAdded).not.toHaveBeenCalled();+ });++ it("installs the page listeners for a mouse's primary-button press, serves it to every recognizer on its path, and removes them as the press ends", () => {+ vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout', 'performance']});+ const {outer, box} = mount('<div id="outer"><div id="box"></div></div>');+ const live = pageListeners();+ const fine = fineHost();+ const pan = new PanGestureRecognizer({+ name: 'pan',+ direction: 'horizontal',+ });+ const outerTap = new TapGestureRecognizer({name: 'outer'});+ const states: string[] = [];+ const outerTransitions: string[] = [];+ pan.addListener(r => states.push(r.state));+ outerTap.addTransitionListener((_current, _from, to) =>+ outerTransitions.push(to),+ );+ detachers.push(fine.attach(box, pan), fine.attach(outer, outerTap));+ pointer('pointerdown', box, {+ pointerType: 'mouse',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ expect(live()).toEqual(+ expect.arrayContaining(['click', 'pointermove', 'pointerup']),+ );+ pointer('pointermove', box, {+ pointerType: 'mouse',+ x: 40,+ y: 10,+ buttons: 1,+ time: 16,+ });+ pointer('pointerup', box, {pointerType: 'mouse', x: 40, y: 10, time: 32});+ expect(states[0]).toBe('began');+ expect(states[states.length - 1]).toBe('ended');+ expect(outerTransitions).toContain('failed');+ // The click the claimed lift owes is still swallowed (FR21): its+ // listener alone stays, for the swallower's window.+ expect(live()).toEqual(['click']);+ vi.advanceTimersByTime(1001);+ expect(live()).toEqual([]);+ });++ it('removes every page listener at once after a press nothing claimed', () => {+ const {box} = mount('<div id="box"></div>');+ const live = pageListeners();+ const fine = fineHost();+ detachers.push(fine.attach(box, new PanGestureRecognizer()));+ pointer('pointerdown', box, {+ pointerType: 'mouse',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ pointer('pointermove', box, {+ pointerType: 'mouse',+ x: 13,+ y: 10,+ buttons: 1,+ time: 16,+ });+ pointer('pointerup', box, {pointerType: 'mouse', x: 13, y: 10, time: 40});+ expect(live()).toEqual([]);+ });++ it("starts no press for a right click, a pen's barrel button or a ctrl-click on macOS (spec:AST-094 FR43)", () => {+ const {box} = mount('<div id="box"></div>');+ const live = pageListeners();+ const fine = fineHost();+ const tap = new TapGestureRecognizer({name: 'tap'});+ const transitions: string[] = [];+ tap.addTransitionListener((_current, _from, to) => transitions.push(to));+ detachers.push(fine.attach(box, tap));+ press(box, {pointerType: 'mouse', button: 2});+ press(box, {pointerType: 'pen', button: 2});+ vi.spyOn(navigator, 'platform', 'get').mockReturnValue('MacIntel');+ press(box, {pointerType: 'mouse', button: 0, ctrlKey: true});+ expect(live()).toEqual([]);+ expect(transitions).toEqual([]);+ expect(host.arena.touches).toEqual([]);+ });++ it('serves a pen press, and keeps no pointer listener after it', () => {+ const {box} = mount('<div id="box"></div>');+ const live = pageListeners();+ const fine = fineHost();+ const pan = new PanGestureRecognizer({direction: 'horizontal'});+ const states: string[] = [];+ pan.addListener(r => states.push(r.state));+ detachers.push(fine.attach(box, pan));+ pointer('pointerdown', box, {+ id: 3,+ pointerType: 'pen',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ pointer('pointermove', box, {+ id: 3,+ pointerType: 'pen',+ x: 40,+ y: 10,+ buttons: 1,+ time: 16,+ });+ pointer('pointerup', box, {+ id: 3,+ pointerType: 'pen',+ x: 40,+ y: 10,+ time: 32,+ });+ expect(states[0]).toBe('began');+ expect(states[states.length - 1]).toBe('ended');+ expect(live().filter(type => type !== 'click')).toEqual([]);+ });++ it("serves a touchscreen laptop's finger: its pointerdown brings the page listeners, its touches are read, and a claim cancels its touchmove and its lift", () => {+ const {box} = mount('<div id="box"></div>');+ const live = pageListeners();+ const fine = fineHost();+ const pan = new PanGestureRecognizer({direction: 'horizontal'});+ const states: string[] = [];+ pan.addListener(r => states.push(r.state));+ detachers.push(fine.attach(box, pan));+ const finger = {id: 1, x: 10, y: 10};+ const moved = {id: 1, x: 40, y: 10};+ pointer('pointerdown', box, {+ id: 5,+ pointerType: 'touch',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ expect(live()).toEqual(expect.arrayContaining(['touchstart', 'touchend']));+ touch('touchstart', box, [finger], [finger], 0);+ const move = touch('touchmove', box, [moved], [moved], 16);+ expect(states).toContain('began');+ expect(move.defaultPrevented).toBe(true);+ pointer('pointerup', box, {+ id: 5,+ pointerType: 'touch',+ x: 40,+ y: 10,+ time: 32,+ });+ const lift = touch('touchend', box, [moved], [], 32);+ expect(lift.defaultPrevented).toBe(true);+ expect(states[states.length - 1]).toBe('ended');+ expect(live().filter(type => type !== 'click')).toEqual([]);+ });++ it('serves an action group like every attachment: its press reaches every recognizer on its path (family:action-groups FR5)', () => {+ const {outer, group, one} = mount(+ '<div id="outer"><div id="group"><button id="one"></button></div></div>',+ );+ const fine = fineHost();+ const outerPan = new PanGestureRecognizer({direction: 'horizontal'});+ const outerStates: string[] = [];+ outerPan.addListener(r => outerStates.push(r.state));+ detachers.push(+ fine.attach(group, new TapGestureRecognizer(), {actionGroup: true}),+ fine.attach(outer, outerPan),+ );+ pointer('pointerdown', one, {+ pointerType: 'mouse',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ pointer('pointermove', one, {+ pointerType: 'mouse',+ x: 40,+ y: 10,+ buttons: 1,+ time: 16,+ });+ pointer('pointerup', one, {pointerType: 'mouse', x: 40, y: 10, time: 32});+ expect(outerStates).toContain('began');+ });++ it("re-syncs when only some of an element's recognizers detach: one left disabled keeps no pointerdown, page listener or ResizeObserver (spec:AST-094 FR24)", () => {+ const {box} = mount('<div id="box"></div>');+ const live = pageListeners();+ // Where the primary pointer is fine: the element's one pointerdown goes+ // with its last enabled recognizer.+ const boxRemoved = vi.spyOn(box, 'removeEventListener');+ const fine = fineHost();+ const detachPan = fine.attach(box, new PanGestureRecognizer());+ detachers.push(+ fine.attach(box, new TapGestureRecognizer({isEnabled: false})),+ );+ detachPan();+ expect(+ boxRemoved.mock.calls.filter(call => call[0] === 'pointerdown'),+ ).toHaveLength(1);+ // A press consumer's detach re-syncs as a recognizer's does.+ const {pad} = mount('<div id="box"></div><div id="pad"></div>');+ const padRemoved = vi.spyOn(pad, 'removeEventListener');+ const detachConsumer = fine.attachConsumer(pad, new RecordingConsumer());+ detachers.push(+ fine.attach(pad, new TapGestureRecognizer({isEnabled: false})),+ );+ detachConsumer();+ expect(+ padRemoved.mock.calls.filter(call => call[0] === 'pointerdown'),+ ).toHaveLength(1);+ // Where it is coarse: the page's listeners go too.+ const coarse = new GestureHost(document, {+ clock,+ isPrimaryPointerCoarse: () => true,+ });+ const {row} = mount('<div id="row"></div>');+ const detachRowPan = coarse.attach(row, new PanGestureRecognizer());+ detachers.push(+ coarse.attach(row, new TapGestureRecognizer({isEnabled: false})),+ );+ expect(live()).toContain('touchstart');+ detachRowPan();+ expect(live()).toEqual([]);+ });++ it("watches the viewport once a touch-down finds a leading pan's direction switched in place to the right edge, and stops when it switches back (spec:AST-094 FR18, FR24, DEC-22)", () => {+ const observed = new Set<Element>();+ class StandInResizeObserver {+ observe(target: Element): void {+ observed.add(target);+ }+ unobserve(target: Element): void {+ observed.delete(target);+ }+ disconnect(): void {+ observed.clear();+ }+ }+ const original = Object.getOwnPropertyDescriptor(window, 'ResizeObserver');+ Object.defineProperty(window, 'ResizeObserver', {+ configurable: true,+ value: StandInResizeObserver,+ });+ try {+ const {strip} = mount('<div id="strip" style="direction: ltr"></div>');+ detachers.push(+ host.attach(+ strip,+ new ScreenEdgePanGestureRecognizer({+ name: 'edge',+ edges: ['leading'],+ }),+ ),+ );+ // Under LTR the leading edge is the left one: its band stays put.+ expect(observed.has(document.documentElement)).toBe(false);+ // The page turns RTL in place; the next touch-down measures again, and+ // the leading edge is the right one, whose band moves with the viewport.+ strip.style.direction = 'rtl';+ const first = {id: 1, x: 4, y: 300};+ touch('touchstart', strip, [first], [first], 0);+ touch('touchend', strip, [first], [], 40);+ expect(observed.has(document.documentElement)).toBe(true);+ // Back to LTR in place: the root is watched for nothing, and goes.+ strip.style.direction = 'ltr';+ const second = {id: 2, x: 4, y: 300};+ touch('touchstart', strip, [second], [second], 200);+ touch('touchend', strip, [second], [], 240);+ expect(observed.has(document.documentElement)).toBe(false);+ } finally {+ if (original == null) {+ delete (window as {ResizeObserver?: unknown}).ResizeObserver;+ } else {+ Object.defineProperty(window, 'ResizeObserver', original);+ }+ }+ });++ it("stops watching a screen-edge pan's box when it detaches while a disabled recognizer stays on the element (spec:AST-094 FR24)", () => {+ const observed = new Set<Element>();+ class StandInResizeObserver {+ observe(target: Element): void {+ observed.add(target);+ }+ unobserve(target: Element): void {+ observed.delete(target);+ }+ disconnect(): void {+ observed.clear();+ }+ }+ const original = Object.getOwnPropertyDescriptor(window, 'ResizeObserver');+ Object.defineProperty(window, 'ResizeObserver', {+ configurable: true,+ value: StandInResizeObserver,+ });+ try {+ const {strip} = mount('<div id="strip"></div>');+ const fine = fineHost();+ const detachEdge = fine.attach(+ strip,+ new ScreenEdgePanGestureRecognizer({name: 'edge'}),+ );+ detachers.push(+ fine.attach(strip, new TapGestureRecognizer({isEnabled: false})),+ );+ expect(observed).toEqual(new Set([strip]));+ detachEdge();+ expect(observed.size).toBe(0);+ } finally {+ if (original == null) {+ delete (window as {ResizeObserver?: unknown}).ResizeObserver;+ } else {+ Object.defineProperty(window, 'ResizeObserver', original);+ }+ }+ });++ it('removes the element listener on detach and leaves nothing on the page', () => {+ const {box} = mount('<div id="box"></div>');+ const live = pageListeners();+ const boxRemoved = vi.spyOn(box, 'removeEventListener');+ const fine = fineHost();+ const detach = fine.attach(box, new TapGestureRecognizer());+ detach();+ expect(boxRemoved).toHaveBeenCalledWith(+ 'pointerdown',+ expect.any(Function),+ {capture: true, passive: true},+ );+ expect(live()).toEqual([]);+ });++ it('gives a coarse primary pointer its page listeners and no element pointerdown', () => {+ const {box} = mount('<div id="box"></div>');+ const live = pageListeners();+ const boxAdded = vi.spyOn(box, 'addEventListener');+ const coarse = new GestureHost(document, {+ clock,+ isPrimaryPointerCoarse: () => true,+ });+ detachers.push(coarse.attach(box, new TapGestureRecognizer()));+ expect(live()).toEqual(+ expect.arrayContaining(['pointerdown', 'touchstart']),+ );+ expect(+ boxAdded.mock.calls.filter(call => call[0] === 'pointerdown'),+ ).toEqual([]);+ });+});++describe("inputMode 'pointer-events'", () => {+ /** A clock whose timers the test fires. */+ class TimerClock {+ time = 0;+ private readonly timers = new Map<number, () => void>();+ private next = 1;+ now(): number {+ return this.time;+ }+ setTimeout(callback: () => void): number {+ const id = this.next++;+ this.timers.set(id, callback);+ return id;+ }+ clearTimeout(id: number): void {+ this.timers.delete(id);+ }+ /** Runs every timer, and the ones they set, at `time`. */+ fireAll(time: number): void {+ this.time = time;+ while (this.timers.size > 0) {+ const due = [...this.timers.values()];+ this.timers.clear();+ for (const callback of due) {+ callback();+ }+ }+ }+ }++ it("tracks a finger once, from its pointer events, so a still finger's long press begins", () => {+ const {box} = mount('<div id="box"></div>');+ const timers = new TimerClock();+ const pointerHost = new GestureHost(document, {+ clock: timers,+ inputMode: 'pointer-events',+ isPrimaryPointerCoarse: () => true,+ });+ const press = new LongPressGestureRecognizer();+ const states: string[] = [];+ press.addListener(r => states.push(r.state));+ detachers.push(pointerHost.attach(box, press));+ // A browser with Touch Events sends both for one finger.+ pointer('pointerdown', box, {+ pointerType: 'touch',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ const finger = {id: 7, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ expect(press.numberOfTouches).toBe(1);+ timers.fireAll(800);+ expect(states).toContain('began');+ pointer('pointerup', box, {pointerType: 'touch', x: 10, y: 10, time: 820});+ touch('touchend', box, [finger], [], 820);+ expect(states).toContain('ended');+ });++ it("cancels a claimed finger's touchmove, matching its touches to its pointer", () => {+ const {box} = mount('<div id="box"></div>');+ const pointerHost = new GestureHost(document, {+ clock,+ inputMode: 'pointer-events',+ isPrimaryPointerCoarse: () => true,+ });+ const pan = new PanGestureRecognizer({direction: 'horizontal'});+ detachers.push(pointerHost.attach(box, pan));+ pointer('pointerdown', box, {+ pointerType: 'touch',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ const finger = {id: 7, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ // Before the pan claims, the browser keeps the move.+ const early = {...finger, x: 14};+ pointer('pointermove', box, {+ pointerType: 'touch',+ x: 14,+ y: 10,+ buttons: 1,+ time: 8,+ });+ expect(touch('touchmove', box, [early], [early], 8).defaultPrevented).toBe(+ false,+ );+ // Past its hysteresis the pan owns the finger: its touchmoves are cancelled.+ const claimed = {...finger, x: 40};+ pointer('pointermove', box, {+ pointerType: 'touch',+ x: 40,+ y: 10,+ buttons: 1,+ time: 32,+ });+ expect(pan.state).toBe('began');+ expect(+ touch('touchmove', box, [claimed], [claimed], 32).defaultPrevented,+ ).toBe(true);+ });++ it("cancels a claimed finger's touchend, and leaves an unclaimed one's alone", () => {+ const {box, other} = mount('<div id="box"></div><div id="other"></div>');+ const pointerHost = new GestureHost(document, {+ clock,+ inputMode: 'pointer-events',+ isPrimaryPointerCoarse: () => true,+ });+ const pan = new PanGestureRecognizer({direction: 'horizontal'});+ detachers.push(+ pointerHost.attach(box, pan),+ pointerHost.attach(other, new TapGestureRecognizer()),+ );+ // A pan that claims, then lifts: its touchend is cancelled (FR21).+ pointer('pointerdown', box, {+ pointerType: 'touch',+ x: 10,+ y: 10,+ buttons: 1,+ time: 0,+ });+ const finger = {id: 7, x: 10, y: 10};+ touch('touchstart', box, [finger], [finger], 0);+ pointer('pointermove', box, {+ pointerType: 'touch',+ x: 40,+ y: 10,+ buttons: 1,+ time: 32,+ });+ expect(pan.state).toBe('began');+ pointer('pointerup', box, {pointerType: 'touch', x: 40, y: 10, time: 48});+ const lifted = {...finger, x: 40};+ expect(touch('touchend', box, [lifted], [], 48).defaultPrevented).toBe(+ true,+ );+ // A tap nobody claimed before its lift keeps its touchend.+ pointer('pointerdown', other, {+ id: 2,+ pointerType: 'touch',+ x: 10,+ y: 80,+ buttons: 1,+ time: 400,+ });+ const second = {id: 8, x: 10, y: 80};+ touch('touchstart', other, [second], [second], 400);+ pointer('pointerup', other, {+ id: 2,+ pointerType: 'touch',+ x: 10,+ y: 80,+ time: 460,+ });+ expect(touch('touchend', other, [second], [], 460).defaultPrevented).toBe(+ false,+ );+ });+});diff --git a/packages/core/src/gestures/__tests__/arena.test.ts b/packages/core/src/gestures/__tests__/arena.test.tsindex 8cc06fc5fe..741e64e72c 100644--- a/packages/core/src/gestures/__tests__/arena.test.ts+++ b/packages/core/src/gestures/__tests__/arena.test.ts@@ -39,6 +39,11 @@ interface Script {* gesture ends with its last touch and a possible one fails.*/class Scripted extends GestureRecognizer {+ // A discrete one decides at the lift, as a tap does.+ override get kind(): GestureRecognizer['kind'] {+ return this.discrete ? 'tap' : 'pan';+ }+/** Expects more input after its touches lifted (a multi-tap between taps). */isWaiting = false;private readonly discrete: boolean;diff --git a/packages/core/src/gestures/__tests__/arenaPinchSwipeEdge.test.ts b/packages/core/src/gestures/__tests__/arenaPinchSwipeEdge.test.tsindex 54829fb2ae..2e1e0f2871 100644--- a/packages/core/src/gestures/__tests__/arenaPinchSwipeEdge.test.ts+++ b/packages/core/src/gestures/__tests__/arenaPinchSwipeEdge.test.ts@@ -24,6 +24,11 @@ import {createHarness, RecordingConsumer} from './harness';* test fails it: something another recognizer can wait on.*/class Held extends GestureRecognizer {+ // Possible until failed, as a tap waiting for its next tap.+ override get kind(): GestureRecognizer['kind'] {+ return 'tap';+ }+private isWaiting = true;override isInvolved(): boolean {diff --git a/packages/core/src/gestures/__tests__/browser/build-fixture.mjs b/packages/core/src/gestures/__tests__/browser/build-fixture.mjsnew file mode 100644index 0000000000..0d1be1180c--- /dev/null+++ b/packages/core/src/gestures/__tests__/browser/build-fixture.mjs@@ -0,0 +1,46 @@+#!/usr/bin/env node+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file build-fixture.mjs+ * @input fixture.ts beside this file+ * @output A standalone HTML page (the fixture bundled inline) for running the+ * gesture proofs in any browser, including Mobile Safari on the iOS+ * simulator+ * @position Test-only helper of packages/core/src/gestures+ *+ * node packages/core/src/gestures/__tests__/browser/build-fixture.mjs out.html+ *+ * The page records every recognizer transition and every click on+ * `window.__gestures`; read it with the Web Inspector or by evaluating+ * `JSON.stringify(window.__gestures)`.+ */++import fs from 'node:fs';+import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {build} from 'esbuild';++const here = path.dirname(fileURLToPath(import.meta.url));+const out = process.argv[2];+if (out == null) {+ console.error('usage: build-fixture.mjs <out.html>');+ process.exit(1);+}+const result = await build({+ entryPoints: [path.join(here, 'fixture.ts')],+ bundle: true,+ write: false,+ format: 'iife',+ platform: 'browser',+ target: 'es2022',+});+const html = `<!doctype html>+<meta charset="utf-8">+<meta name="viewport" content="width=device-width, initial-scale=1">+<title>Gesture fixture</title>+<body></body>+<script>${result.outputFiles[0].text.replaceAll('</script', '<\\/script')}</script>+`;+fs.writeFileSync(out, html);+console.log(`wrote ${out} (${html.length} bytes)`);diff --git a/packages/core/src/gestures/__tests__/browser/fixture.ts b/packages/core/src/gestures/__tests__/browser/fixture.tsnew file mode 100644index 0000000000..9cd162bc56--- /dev/null+++ b/packages/core/src/gestures/__tests__/browser/fixture.ts@@ -0,0 +1,307 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file fixture.ts+ * @input Nothing: bundled by esbuild and injected into a blank page+ * @output A page of gesture hosts (a horizontal pan inside a scroller, a tap+ * target, a long press, a pinch, a sheet body that hands its scroll to a+ * pan, a passive control: a press consumer under `pan-y` with no+ * recognizer, pans and a long press under narrower author `touch-action`+ * values, and leading screen-edge pans on an edge-zone strip and on a wider+ * element, left to right and right to left) that records every recognizer+ * transition, every consumer event and every click on `window.__gestures`+ * @position Browser fixture of gestures.interaction.browser.spec.ts;+ * test-only+ */++import {getGestureHost} from '../../GestureHost';+import type {GestureRecognizer} from '../../GestureRecognizer';+import {LongPressGestureRecognizer} from '../../LongPressGestureRecognizer';+import {PanGestureRecognizer} from '../../PanGestureRecognizer';+import {PinchGestureRecognizer} from '../../PinchGestureRecognizer';+import {ScreenEdgePanGestureRecognizer} from '../../ScreenEdgePanGestureRecognizer';+import {TapGestureRecognizer} from '../../TapGestureRecognizer';++interface Entry {+ name: string;+ state: string;+ time: number;+ x?: number;+ y?: number;+ scale?: number;+ beganAt?: number | null;+ startedAt?: number;+}++interface ListenerEntry {+ id: string;+ type: string;+ passive: boolean | null;+}++declare global {+ interface Window {+ __gestures: Entry[];+ __listeners: ListenerEntry[];+ /** The page-level (document and window) listeners now added, by type. */+ __pageListeners: Map<string, number>;+ /** The page-level listener types the attachments below added. */+ __attachListeners: string[];+ }+}++window.__gestures = [];++// Every touch listener added to an element with an id, as the engine sees+// it: which elements make a scroll wait for the page.+window.__listeners = [];+// And every listener on the document or the window, added and removed: what+// gesture work costs the page between presses (spec:AST-094 FR24).+window.__pageListeners = new Map();+const isPage = (target: EventTarget) =>+ target === document || target === window;+const addListener = EventTarget.prototype.addEventListener;+EventTarget.prototype.addEventListener = function (+ this: EventTarget,+ type: string,+ listener: EventListenerOrEventListenerObject | null,+ options?: boolean | AddEventListenerOptions,+) {+ if (this instanceof Element && this.id !== '' && type.startsWith('touch')) {+ window.__listeners.push({+ id: this.id,+ type,+ passive: typeof options === 'object' ? (options.passive ?? null) : null,+ });+ }+ if (isPage(this) && listener != null) {+ window.__pageListeners.set(+ type,+ (window.__pageListeners.get(type) ?? 0) + 1,+ );+ }+ addListener.call(this, type, listener, options);+};+const removeListener = EventTarget.prototype.removeEventListener;+EventTarget.prototype.removeEventListener = function (+ this: EventTarget,+ type: string,+ listener: EventListenerOrEventListenerObject | null,+ options?: boolean | EventListenerOptions,+) {+ if (isPage(this) && listener != null) {+ window.__pageListeners.set(+ type,+ (window.__pageListeners.get(type) ?? 0) - 1,+ );+ }+ removeListener.call(this, type, listener, options);+};++document.body.style.margin = '0';+document.body.innerHTML = `+ <div id="page" style="font: 14px sans-serif">+ <div id="scroller" style="height: 240px; overflow-y: auto; overscroll-behavior: contain; background: #eef">+ <div style="height: 40px">scroller</div>+ <div id="hpan" style="height: 140px; background: #ccd">+ <button id="hbutton" style="width: 200px; height: 80px; margin: 30px">button</button>+ </div>+ <div id="scrollRow" style="height: 60px; background: #ece; touch-action: none">row (a press in the scroller)</div>+ <div style="height: 1200px">content</div>+ </div>+ <div id="tapper" style="height: 60px; background: #efe">tap</div>+ <div id="presser" style="height: 60px; background: #fee">press</div>+ <div id="pinchable" style="height: 160px; background: #ffe">pinch</div>+ <div id="sheetBody" style="height: 240px; overflow-y: auto; overscroll-behavior: contain; background: #eee">+ <div style="height: 1200px">sheet content</div>+ </div>+ <div id="passive" style="height: 60px; background: #dfd; touch-action: pan-y pinch-zoom">passive control</div>+ <div id="card" style="height: 80px; background: #def">card (swipe up)</div>+ <style>+ .author-none { touch-action: none; }+ .author-pan-y { touch-action: pan-y; }+ .author-pinch-zoom { touch-action: pinch-zoom; }+ .author-pan-xy { touch-action: pan-x pan-y; }+ </style>+ <div id="authorNone" class="author-none" style="height: 60px; background: #fdd">author none</div>+ <div id="authorPanY" class="author-pan-y" style="height: 60px; background: #dfd">author pan-y</div>+ <div id="authorPinchZoom" class="author-pinch-zoom" style="height: 60px; background: #ffd">author pinch-zoom</div>+ <div id="authorPanXY" class="author-pan-xy" style="height: 60px; background: #ddf">author pan-x pan-y</div>+ <div id="inlinePanXY" style="height: 60px; background: #fdf; touch-action: pan-x pan-y">inline pan-x pan-y</div>+ <div id="edgeZone" style="width: 40px; height: 120px; background: #fcf">edge</div>+ <div id="edgeWide" style="width: 200px; height: 120px; overflow-x: auto; background: #cff">+ <div style="width: 800px; height: 100px">wider than the band</div>+ </div>+ <div dir="rtl">+ <div id="edgeZoneRtl" style="width: 40px; height: 120px; background: #fcf">edge</div>+ <div id="edgeWideRtl" style="width: 200px; height: 120px; overflow-x: auto; background: #cff">+ <div style="width: 800px; height: 100px">wider than the band</div>+ </div>+ </div>+ <div style="height: 1600px">page</div>+ <div id="passiveEnd" style="height: 60px; background: #dfd; touch-action: pan-y pinch-zoom">passive control at the page's end</div>+ </div>`;++function element(id: string): HTMLElement {+ const found = document.getElementById(id);+ if (found == null) {+ throw new Error(`missing #${id}`);+ }+ return found;+}++const beforeAttach = new Map(window.__pageListeners);+const host = getGestureHost(document);++function record(recognizer: GestureRecognizer, extra: () => Partial<Entry>) {+ recognizer.addTransitionListener((current, _from, to) => {+ window.__gestures.push({+ name: current.name,+ state: to,+ time: current.arena?.now() ?? performance.now(),+ ...(to === 'possible' || to === 'failed' ? {} : extra()),+ });+ });+}++const hpan = new PanGestureRecognizer({name: 'hpan', direction: 'horizontal'});+record(hpan, () => ({x: hpan.translation().x, y: hpan.translation().y}));+host.attach(element('hpan'), hpan);++const tap = new TapGestureRecognizer({name: 'tap'});+record(tap, () => ({}));+host.attach(element('tapper'), tap);++const press = new LongPressGestureRecognizer({name: 'press'});+record(press, () => ({+ beganAt: press.beganAt,+ startedAt: press.trackedTouches[0]?.startTime,+}));+host.attach(element('presser'), press);++const pinch = new PinchGestureRecognizer({name: 'pinch'});+const pinchPan = new PanGestureRecognizer({+ name: 'pinchPan',+ maximumNumberOfTouches: 2,+});+pinch.recognizeSimultaneouslyWith(pinchPan);+record(pinch, () => ({scale: pinch.scale}));+record(pinchPan, () => ({x: pinchPan.translation().x}));+host.attach(element('pinchable'), pinch);+host.attach(element('pinchable'), pinchPan);++const sheet = new PanGestureRecognizer({+ name: 'sheet',+ direction: 'down',+ scrollEdge: true,+});+record(sheet, () => ({y: sheet.translation().y}));+host.attach(element('sheetBody'), sheet);++// A one-way pan over the scrollable page, as a toast's upward swipe is: it+// claims its touch as it begins, at UIKit's 10 pt (spec:AST-094 FR19).+const card = new PanGestureRecognizer({name: 'card', direction: 'up'});+record(card, () => ({x: card.translation().x, y: card.translation().y}));+host.attach(element('card'), card);++// Narrower author touch-action (spec:AST-094 FR18, DEC-8): the host's value+// is the derived one intersected with the author's, never wider.+const authorNone = new LongPressGestureRecognizer({name: 'authorNone'});+record(authorNone, () => ({}));+host.attach(element('authorNone'), authorNone);+for (const id of [+ 'authorPanY',+ 'authorPinchZoom',+ 'authorPanXY',+ 'inlinePanXY',+]) {+ const pan = new PanGestureRecognizer({name: id, direction: 'horizontal'});+ record(pan, () => ({x: pan.translation().x}));+ host.attach(element(id), pan);+}++// Leading screen-edge pans (FR18, DEC-13): on an edge-zone strip within the+// 40.2 px band and on an element reaching beyond it, left to right and, with+// the leading edge on the right, right to left.+for (const id of ['edgeZone', 'edgeWide', 'edgeZoneRtl', 'edgeWideRtl']) {+ const edge = new ScreenEdgePanGestureRecognizer({+ name: id,+ edges: ['leading'],+ });+ record(edge, () => ({x: edge.translation().x}));+ host.attach(element(id), edge);+}++// A control with no recognizer of its own (no blocking listener): only a+// press consumer, under pan-y, as a passive switch is.+const passiveEvent = (state: string) =>+ window.__gestures.push({name: 'passive', state, time: performance.now()});+host.attachConsumer(element('passive'), {+ touchBegan: () => passiveEvent('began'),+ touchMoved: () => passiveEvent('moved'),+ touchEnded: () => passiveEvent('ended'),+ touchCancelled: () => passiveEvent('cancelled'),+});++// The same control at the very end of the page, where a page scrolled to its+// end has no room to scroll on: what ends its press is the signal FR20+// counts there.+const passiveEndEvent = (state: string) =>+ window.__gestures.push({name: 'passiveEnd', state, time: performance.now()});+host.attachConsumer(element('passiveEnd'), {+ touchBegan: () => passiveEndEvent('began'),+ touchMoved: () => passiveEndEvent('moved'),+ touchEnded: () => passiveEndEvent('ended'),+ touchCancelled: () => passiveEndEvent('cancelled'),+});+// Which browser signal arrives, in order with the presses it ends: on the+// window, whose capture listeners run before the host's on the document.+addListener.call(+ window,+ 'pointercancel',+ event => {+ if ((event as PointerEvent).pointerType === 'touch') {+ window.__gestures.push({+ name: 'dom:pointercancel',+ state: 'dom',+ time: performance.now(),+ });+ }+ },+ true,+);++// The fixture's own loggers go around the count of page listeners.+// A press consumer inside the scroller, as a list row is: a scroll of the+// scroller takes its press only once the finger has moved the take distance+// (FR20). `touch-action: none` keeps the browser's own pan out of it, so the+// only scroll is the one the test makes.+const rowEvent = (state: string) =>+ window.__gestures.push({name: 'scrollRow', state, time: performance.now()});+host.attachConsumer(element('scrollRow'), {+ touchBegan: () => rowEvent('began'),+ touchMoved: () => rowEvent('moved'),+ touchEnded: () => rowEvent('ended'),+ touchCancelled: () => rowEvent('cancelled'),+});++for (const type of ['click', 'mousedown']) {+ addListener.call(+ document,+ type,+ event => {+ const target = event.target as HTMLElement | null;+ window.__gestures.push({+ name: `${type}:${target?.id ?? ''}`,+ state: 'dom',+ time: event.timeStamp,+ });+ },+ true,+ );+}++window.__attachListeners = [...window.__pageListeners]+ .filter(([type, count]) => count > (beforeAttach.get(type) ?? 0))+ .map(([type]) => type)+ .sort();diff --git a/packages/core/src/gestures/__tests__/browser/gestures.interaction.browser.spec.ts b/packages/core/src/gestures/__tests__/browser/gestures.interaction.browser.spec.tsnew file mode 100644index 0000000000..3828f751f8--- /dev/null+++ b/packages/core/src/gestures/__tests__/browser/gestures.interaction.browser.spec.ts@@ -0,0 +1,1137 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file gestures.interaction.browser.spec.ts+ * @input The gesture fixture bundled with esbuild, a phone-sized touch+ * screen, and real engine touch input: Chromium through CDP with explicit+ * timestamps, WebKit through its own input command (real-time pacing)+ * @output Browser proof of the negotiation the unit tests cannot see:+ * touch-action per element, touchmove cancelled exactly while a recognizer+ * owns the finger, native scrolling untouched otherwise, click suppression+ * with no ghost click, a drag that began as a scroll staying the browser's, pinch-zoom+ * left to the browser, a second finger that never breaks the first, and+ * timing taken from event timestamps under a blocked main thread+ * @position Browser tests of packages/core/src/gestures, run by+ * `pnpm test:interaction` (playwright.interaction.config.ts, a phone in+ * Chromium and WebKit) and in CI's interaction proofs. WebKit's Linux build+ * cannot scroll, fling or pinch-zoom from injected touches, and synthesises+ * a click only from its tap gesture; the checks that need those run in+ * Chromium here and in Mobile Safari on the iOS simulator.+ */++import path from 'node:path';+import {fileURLToPath} from 'node:url';+import {build} from 'esbuild';+import {expect, test, type Page} from '@playwright/test';++interface Entry {+ name: string;+ state: string;+ time: number;+ x?: number;+ y?: number;+ scale?: number;+ beganAt?: number | null;+ startedAt?: number;+}++let bundle = '';++test.beforeAll(async () => {+ const result = await build({+ entryPoints: [+ path.join(path.dirname(fileURLToPath(import.meta.url)), 'fixture.ts'),+ ],+ bundle: true,+ write: false,+ format: 'iife',+ platform: 'browser',+ target: 'es2022',+ });+ bundle = result.outputFiles[0].text;+});++type Point = {x: number; y: number};+type Finger = Point & {id: number};++/** The fingers down after a step, and when (ms after the gesture's start). */+interface Step {+ t: number;+ down: Finger[];+}++interface Driver {+ readonly engine: 'chromium' | 'webkit';+ /** Plays the steps as real touch input; returns the page time of t = 0. */+ play(steps: Step[]): Promise<number>;+ /** A tap through the engine's tap path (WebKit synthesises click only from it). */+ tap(at: Point): Promise<void>;+}++const sleep = async (ms: number) =>+ new Promise(resolve => setTimeout(resolve, ms));++/** Each step's change against the previous one: who landed, lifted, moved. */+function diff(previous: Finger[], next: Finger[]) {+ const before = new Set(previous.map(finger => finger.id));+ const after = new Set(next.map(finger => finger.id));+ return {+ landed: next.filter(finger => !before.has(finger.id)),+ lifted: previous.filter(finger => !after.has(finger.id)),+ };+}++async function chromiumDriver(page: Page): Promise<Driver> {+ const cdp = await page.context().newCDPSession(page);+ const origin = await page.evaluate(() => performance.timeOrigin);+ // The fingers down, across calls: a gesture may span several.+ let down: Finger[] = [];+ const send = async (type: string, points: Finger[], at: number) =>+ cdp.send('Input.dispatchTouchEvent', {+ type: type as 'touchStart',+ touchPoints: points.map(point => ({+ x: point.x,+ y: point.y,+ id: point.id,+ })),+ timestamp: (origin + at) / 1000,+ });+ return {+ engine: 'chromium',+ async play(steps) {+ // CDP stamps every event with the scripted time, so the page sees the+ // script's timing exactly, whatever the dispatch latency.+ const base = Math.ceil(await page.evaluate(() => performance.now())) + 50;+ for (const step of steps) {+ const {landed} = diff(down, step.down);+ // CDP diffs active points against the previous event: a new point+ // is pressed, a missing one released; touchEnd carries none.+ const type =+ landed.length > 0+ ? 'touchStart'+ : step.down.length === 0+ ? 'touchEnd'+ : 'touchMove';+ await send(type, step.down, base + step.t);+ down = step.down;+ }+ return base;+ },+ async tap(at) {+ const base = Math.ceil(await page.evaluate(() => performance.now())) + 50;+ await send('touchStart', [{...at, id: 1}], base);+ await send('touchEnd', [], base + 60);+ },+ };+}++interface WebKitSession {+ send(method: string, params?: Record<string, unknown>): Promise<unknown>;+}++/** Playwright's server-side WebKit page session (a locally launched browser). */+function webkitSession(page: Page): WebKitSession {+ const connection = (+ page as unknown as {_connection?: {toImpl?: (o: unknown) => unknown}}+ )._connection;+ const impl = connection?.toImpl?.(page) as+ {delegate?: {_pageProxySession?: WebKitSession}} | undefined;+ const session = impl?.delegate?._pageProxySession;+ if (session == null) {+ throw new Error('WebKit touch input needs a locally launched browser');+ }+ return session;+}++function webkitDriver(page: Page): Driver {+ const session = webkitSession(page);+ // WebKit's command applies the event's phase to every point it lists: a+ // start lists only the fingers that land, an end only those that lift, a+ // move every finger down. Integer CSS px; the page sees real time.+ const points = (fingers: Finger[]) =>+ fingers.map(f => ({x: Math.round(f.x), y: Math.round(f.y), id: f.id}));+ // The fingers down, across calls: a gesture may span several.+ let down: Finger[] = [];+ return {+ engine: 'webkit',+ async play(steps) {+ const start = Date.now();+ const base = await page.evaluate(() => performance.now());+ for (const step of steps) {+ const wait = start + step.t - Date.now();+ if (wait > 0) {+ await sleep(wait);+ }+ const {landed, lifted} = diff(down, step.down);+ if (landed.length > 0) {+ await session.send('Input.dispatchTouchEvent', {+ type: 'touchStart',+ touchPoints: points(landed),+ });+ } else if (lifted.length > 0) {+ await session.send('Input.dispatchTouchEvent', {+ type: 'touchEnd',+ touchPoints: points(lifted),+ });+ } else {+ await session.send('Input.dispatchTouchEvent', {+ type: 'touchMove',+ touchPoints: points(step.down),+ });+ }+ down = step.down;+ }+ return base;+ },+ async tap(at) {+ await page.touchscreen.tap(Math.round(at.x), Math.round(at.y));+ },+ };+}++/** One finger from `from` to `to` in `count` frames of 16 ms, then a lift. */+function drag(from: Point, to: Point, count = 12, lift = true): Step[] {+ const steps: Step[] = [{t: 0, down: [{...from, id: 1}]}];+ for (let i = 1; i <= count; i++) {+ const k = i / count;+ steps.push({+ t: i * 16,+ down: [+ {+ x: from.x + (to.x - from.x) * k,+ y: from.y + (to.y - from.y) * k,+ id: 1,+ },+ ],+ });+ }+ if (lift) {+ steps.push({t: (count + 1) * 16, down: []});+ }+ return steps;+}++/** Down at `from`, through each offset in turn 16 ms apart, then up. */+function travel(from: Point, offsets: ReadonlyArray<Point>): Step[] {+ const steps: Step[] = [{t: 0, down: [{...from, id: 1}]}];+ offsets.forEach((offset, index) => {+ steps.push({+ t: (index + 1) * 16,+ down: [{x: from.x + offset.x, y: from.y + offset.y, id: 1}],+ });+ });+ steps.push({t: (offsets.length + 2) * 16, down: []});+ return steps;+}++/** Offsets along x, one per step, ending `distance` px from touch-down. */+const alongX = (...xs: number[]): Point[] => xs.map(x => ({x, y: 0}));++async function open(page: Page, engine: string): Promise<Driver> {+ // A real navigation first: touch emulation exposes the Touch Events API+ // to documents it creates.+ await page.goto('about:blank');+ await page.setContent(+ '<!doctype html><meta name="viewport" content="width=device-width, initial-scale=1"><body></body>',+ );+ await page.addScriptTag({content: bundle});+ return engine === 'webkit' ? webkitDriver(page) : chromiumDriver(page);+}++async function center(page: Page, id: string): Promise<Point> {+ const box = await page.locator(`#${id}`).boundingBox();+ if (box == null) {+ throw new Error(`#${id} has no box`);+ }+ return {+ x: Math.round(box.x + box.width / 2),+ y: Math.round(box.y + box.height / 2),+ };+}++async function log(page: Page): Promise<Entry[]> {+ await page.waitForTimeout(50);+ return page.evaluate(() => window.__gestures);+}++async function clearLog(page: Page): Promise<void> {+ await page.evaluate(() => {+ window.__gestures.length = 0;+ });+}++async function scrollTop(page: Page, id: string): Promise<number> {+ return page.evaluate(+ target => document.getElementById(target)?.scrollTop ?? -1,+ id,+ );+}++/** Record whether each touchmove reached the page cancelled. */+async function logTouchMoves(page: Page): Promise<void> {+ await page.evaluate(() => {+ const moves: boolean[] = [];+ (window as unknown as {__moves: boolean[]}).__moves = moves;+ window.addEventListener(+ 'touchmove',+ event => moves.push(event.defaultPrevented),+ {passive: true},+ );+ });+}++async function readTouchMoves(page: Page): Promise<boolean[]> {+ return page.evaluate(+ () => (window as unknown as {__moves: boolean[]}).__moves,+ );+}++const states = (entries: Entry[], name: string) =>+ entries.filter(entry => entry.name === name).map(entry => entry.state);++test('derives touch-action per element from its recognizers', async ({+ page,+ browserName,+}) => {+ await open(page, browserName);+ const actions = await page.evaluate(() =>+ Object.fromEntries(+ ['hpan', 'tapper', 'presser', 'pinchable', 'sheetBody'].map(id => [+ id,+ getComputedStyle(document.getElementById(id) as HTMLElement)+ .touchAction,+ ]),+ ),+ );+ expect(actions).toEqual({+ hpan: 'pan-y pinch-zoom',+ tapper: 'manipulation',+ presser: 'manipulation',+ pinchable: 'none',+ sheetBody: 'auto',+ });+});++test('only elements whose recognizers claim a moving touch carry a blocking touchmove listener', async ({+ page,+ browserName,+}) => {+ await open(page, browserName);+ const blocking = await page.evaluate(() =>+ window.__listeners+ .filter(entry => entry.type === 'touchmove' && entry.passive === false)+ .map(entry => entry.id),+ );+ // Pans (the cards' and the screen-edge pans' too), long presses, a pinch+ // and the sheet's pan can take a moving touch; a tap-only element and a+ // press consumer never wait.+ expect(new Set(blocking)).toEqual(+ new Set([+ 'hpan',+ 'presser',+ 'pinchable',+ 'sheetBody',+ 'card',+ 'authorNone',+ 'authorPanY',+ 'authorPinchZoom',+ 'authorPanXY',+ 'inlinePanXY',+ 'edgeZone',+ 'edgeWide',+ 'edgeZoneRtl',+ 'edgeWideRtl',+ ]),+ );+});++test('a horizontal drag on a pan-y element is the recognizer’s: cancelled moves, no scroll, no click', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await logTouchMoves(page);+ const start = await center(page, 'hbutton');+ // A 4:1 drag, the shape WebKit would otherwise pan natively.+ await driver.play(drag(start, {x: start.x + 120, y: start.y + 30}));+ const entries = await log(page);+ const hpan = states(entries, 'hpan');+ expect(hpan[0]).toBe('began');+ expect(hpan.slice(-2)).toEqual(['ended', 'possible']);+ const last = entries+ .filter(entry => entry.name === 'hpan' && entry.state === 'changed')+ .at(-1);+ // As in UIKit, the 10 px hysteresis is not part of the translation.+ expect(last?.x).toBeCloseTo(120 - 10, 0);+ // Every touchmove after the claim was cancelled.+ const moves = await readTouchMoves(page);+ expect(moves.length).toBeGreaterThan(0);+ expect(moves.slice(-3).every(Boolean)).toBe(true);+ expect(await scrollTop(page, 'scroller')).toBe(0);+ expect(entries.some(entry => entry.name.startsWith('click:'))).toBe(false);+ expect(entries.some(entry => entry.name.startsWith('mousedown:'))).toBe(+ false,+ );+});++test('a vertical drag on the same element fails the pan and is never cancelled', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await logTouchMoves(page);+ const start = await center(page, 'hpan');+ await driver.play(drag(start, {x: start.x + 4, y: start.y - 120}));+ const entries = await log(page);+ expect(states(entries, 'hpan')).toEqual(['failed', 'possible']);+ expect((await readTouchMoves(page)).some(Boolean)).toBe(false);+ if (driver.engine === 'chromium') {+ // The browser scrolled it natively.+ expect(await scrollTop(page, 'scroller')).toBeGreaterThan(60);+ }+ expect(entries.some(entry => entry.name.startsWith('click:'))).toBe(false);+});++test('a horizontal drag on a passive pan-y control keeps its press: uncancelable moves the browser cannot pan are not a claim', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await page.evaluate(() => {+ document.getElementById('passive')?.scrollIntoView({block: 'center'});+ });+ const start = await center(page, 'passive');+ await driver.play(+ drag({x: start.x - 120, y: start.y}, {x: start.x + 120, y: start.y + 6}),+ );+ const consumed = (await log(page))+ .filter(entry => entry.name === 'passive')+ .map(entry => entry.state);+ expect(consumed[0]).toBe('began');+ expect(consumed).not.toContain('cancelled');+ expect(consumed.at(-1)).toBe('ended');+});++test('a vertical drag on a passive pan-y control, over a page with room to scroll, hands the press to the browser (FR20)', async ({+ page,+ browserName,+}) => {+ test.skip(+ browserName === 'webkit',+ 'needs native scrolling from injected touches (Mobile Safari on the simulator)',+ );+ const driver = await open(page, browserName);+ await page.evaluate(() => {+ document.getElementById('passive')?.scrollIntoView({block: 'center'});+ });+ const before = await page.evaluate(() => window.scrollY);+ const start = await center(page, 'passive');+ // Up, along the axis pan-y leaves the browser, which has room that way.+ await driver.play(drag(start, {x: start.x + 4, y: start.y - 120}));+ const consumed = states(await log(page), 'passive');+ expect(consumed[0]).toBe('began');+ expect(consumed.at(-1)).toBe('cancelled');+ expect(consumed).not.toContain('ended');+ expect(await page.evaluate(() => window.scrollY)).toBeGreaterThan(+ before + 20,+ );+});++test('a vertical drag on a passive pan-y control where no scroller has room is not handed over by its moves: the browser\u2019s pointercancel ends the press (FR20)', async ({+ page,+ browserName,+}) => {+ test.skip(+ browserName === 'webkit',+ 'needs native scrolling from injected touches (Mobile Safari on the simulator)',+ );+ const driver = await open(page, browserName);+ // The page at its end: no room to scroll on.+ await page.evaluate(() => {+ window.scrollTo(0, document.documentElement.scrollHeight);+ });+ const atEnd = await page.evaluate(() => window.scrollY);+ const start = await center(page, 'passiveEnd');+ await driver.play(drag(start, {x: start.x + 4, y: start.y - 120}));+ const entries = (await log(page)).filter(+ entry => entry.name === 'passiveEnd' || entry.name === 'dom:pointercancel',+ );+ const order = entries.map(entry =>+ entry.name === 'passiveEnd' ? entry.state : 'pointercancel',+ );+ expect(order[0]).toBe('began');+ // The press ends cancelled, at the browser's pointercancel and not before:+ // an uncancelable move along an axis no scroller can scroll is no claim.+ const cancelledAt = order.indexOf('cancelled');+ expect(cancelledAt).toBeGreaterThan(0);+ expect(order.slice(0, cancelledAt)).toContain('pointercancel');+ expect(order).not.toContain('ended');+ expect(await page.evaluate(() => window.scrollY)).toBe(atEnd);+});++test('a one-way overlay pan keeps its direction from the page, and leaves the other way to it', async ({+ page,+ browserName,+}) => {+ test.skip(+ browserName === 'webkit',+ 'needs native scrolling from injected touches (Mobile Safari on the simulator)',+ );+ const driver = await open(page, browserName);+ await page.evaluate(() => {+ document.getElementById('card')?.scrollIntoView({block: 'center'});+ });+ const before = await page.evaluate(() => window.scrollY);+ const start = await center(page, 'card');+ // Up, slowly: the card's pan begins at 10 px and the page never moves.+ await driver.play(drag(start, {x: start.x, y: start.y - 40}, 40));+ expect(await page.evaluate(() => window.scrollY)).toBe(before);+ const up = (await log(page)).filter(entry => entry.name === 'card');+ expect(up[0]?.state).toBe('began');+ expect(up.filter(entry => entry.state === 'changed').at(-1)?.y).toBe(-30);+ // Down: the page's.+ await clearLog(page);+ await driver.play(drag(start, {x: start.x, y: start.y + 60}, 30));+ expect(await page.evaluate(() => window.scrollY)).toBeLessThan(before - 20);+ expect(states(await log(page), 'card')).toEqual(['failed', 'possible']);+});++test('a tap recognizer replaces the click: no ghost click, no compatibility mouse events', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await driver.tap(await center(page, 'tapper'));+ let entries = await log(page);+ expect(states(entries, 'tap')).toEqual(['ended', 'possible']);+ expect(entries.filter(entry => entry.state === 'dom')).toEqual([]);++ // A tap the pan does not take keeps its click (exactly one).+ await clearLog(page);+ await driver.tap(await center(page, 'hbutton'));+ entries = await log(page);+ expect(entries.filter(entry => entry.name === 'click:hbutton')).toHaveLength(+ 1,+ );+});++test('a keyboard activation inside the click window after a claimed drag still clicks: the swallower passes a click whose detail is 0 (FR21)', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ // A pan claims the drag: its touchend is cancelled, so no click follows it,+ // and the swallower stays armed for the stray one it may still owe.+ const start = await center(page, 'hpan');+ await driver.play(drag(start, {x: start.x + 40, y: start.y}, 8));+ expect(states(await log(page), 'hpan')).toContain('ended');+ await clearLog(page);+ // Enter on a focused button: a click whose detail is 0, which passes.+ await page.focus('#hbutton');+ await page.keyboard.press('Enter');+ const entries = await log(page);+ expect(entries.filter(entry => entry.name === 'click:hbutton')).toHaveLength(+ 1,+ );+});++test('scroll edge: at the top the pull is the sheet’s at once', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ const start = await center(page, 'sheetBody');+ await driver.play(drag(start, {x: start.x, y: start.y + 96}));+ const entries = await log(page);+ const sheet = entries.filter(entry => entry.name === 'sheet');+ expect(sheet[0]?.state).toBe('began');+ expect(+ sheet.filter(entry => entry.state === 'changed').at(-1)?.y,+ ).toBeCloseTo(96 - 10, 0);+ expect(await scrollTop(page, 'sheetBody')).toBe(0);+});++test('a drag that began as a scroll stays the browser’s (AST-094 FR14): the content scrolls to its top and the sheet never begins', async ({+ page,+ browserName,+}) => {+ test.skip(+ browserName === 'webkit',+ 'needs native scrolling from injected touches (Mobile Safari on the simulator)',+ );+ const driver = await open(page, browserName);+ await page.evaluate(() => {+ (document.getElementById('sheetBody') as HTMLElement).scrollTop = 60;+ });+ const start = await center(page, 'sheetBody');+ start.y -= 60;+ await driver.play(drag(start, {x: start.x, y: start.y + 200}, 25));+ const entries = await log(page);+ const sheet = entries.filter(entry => entry.name === 'sheet');+ // The content takes the whole drag: it scrolls to its top, and the travel+ // past that point never becomes the sheet's.+ expect(await scrollTop(page, 'sheetBody')).toBe(0);+ expect(sheet.some(entry => entry.state === 'began')).toBe(false);+});++/** Two fingers that land one after the other and spread apart. */+function spread(at: Point, from: number, by: number, drift = 0): Step[] {+ const steps: Step[] = [+ {t: 0, down: [{x: at.x - from, y: at.y, id: 1}]},+ {+ t: 30,+ down: [+ {x: at.x - from, y: at.y, id: 1},+ {x: at.x + from, y: at.y, id: 2},+ ],+ },+ ];+ for (let i = 1; i <= 12; i++) {+ const half = from + (by * i) / 12;+ steps.push({+ t: 30 + i * 16,+ down: [+ {x: at.x - half + drift * i, y: at.y, id: 1},+ {x: at.x + half + drift * i, y: at.y, id: 2},+ ],+ });+ }+ steps.push({t: 30 + 13 * 16, down: []});+ return steps;+}++test('pinch-zoom stays the browser’s on an element without a pinch recognizer', async ({+ page,+ browserName,+}) => {+ test.skip(+ browserName === 'webkit',+ 'needs native pinch-zoom from injected touches (Mobile Safari on the simulator)',+ );+ const driver = await open(page, browserName);+ await driver.play(spread(await center(page, 'tapper'), 20, 96));+ await page.waitForTimeout(400);+ expect(+ await page.evaluate(() => window.visualViewport?.scale ?? 1),+ ).toBeGreaterThan(1.2);+ expect(states(await log(page), 'tap')).not.toContain('ended');+});++test('a pinch recognizer takes the two-finger gesture on its element only, alongside its pan', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await driver.play(spread(await center(page, 'pinchable'), 20, 40, 1));+ const entries = await log(page);+ expect(states(entries, 'pinch')[0]).toBe('began');+ const scale = entries+ .filter(entry => entry.name === 'pinch' && entry.state === 'changed')+ .at(-1)?.scale;+ // The span grew from 40 to 120; as in UIKit, the scale is measured from+ // the starting span moved by the 8 px hysteresis.+ expect(scale).toBeCloseTo(120 / (40 + 8), 1);+ expect(states(entries, 'pinchPan')).toContain('began');+ expect(await page.evaluate(() => window.visualViewport?.scale ?? 1)).toBe(1);+});++test('a second finger never breaks a claimed one-finger pan', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ const start = await center(page, 'hbutton');+ const other = await center(page, 'tapper');+ const steps: Step[] = [{t: 0, down: [{...start, id: 1}]}];+ for (let i = 1; i <= 4; i++) {+ steps.push({t: i * 16, down: [{x: start.x + i * 10, y: start.y, id: 1}]});+ }+ const first = {x: start.x + 40, y: start.y, id: 1};+ steps.push({t: 80, down: [first, {...other, id: 2}]});+ for (let i = 1; i <= 6; i++) {+ steps.push({+ t: 80 + i * 16,+ down: [+ {x: first.x + i * 5, y: first.y, id: 1},+ {x: other.x + i * 15, y: other.y + i * 15, id: 2},+ ],+ });+ }+ steps.push({+ t: 200,+ down: [{x: other.x + 90, y: other.y + 90, id: 2}],+ });+ steps.push({t: 216, down: []});+ await driver.play(steps);+ const entries = await log(page);+ const hpan = entries.filter(entry => entry.name === 'hpan');+ expect(hpan.map(entry => entry.state)).not.toContain('cancelled');+ expect(hpan.map(entry => entry.state)).toContain('ended');+ expect(hpan.filter(entry => entry.state === 'changed').at(-1)?.x).toBeCloseTo(+ 70 - 10,+ 0,+ );+ expect(await page.evaluate(() => window.visualViewport?.scale ?? 1)).toBe(1);+});++test('a long press begins at touch-down + 500 ms on the event clock, even when the main thread was blocked', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ const at = await center(page, 'presser');+ const base = await driver.play([{t: 0, down: [{...at, id: 1}]}]);+ // Block the main thread well past the press duration.+ await page.evaluate(() => {+ const end = performance.now() + 800;+ while (performance.now() < end) {+ // busy+ }+ });+ await page.waitForTimeout(100);+ await driver.play([{t: 0, down: []}]);+ const entries = await log(page);+ const began = entries.find(+ entry => entry.name === 'press' && entry.state === 'began',+ );+ if (driver.engine === 'chromium') {+ // The touch carries the timestamp CDP gave it (to the browser's 0.1 ms+ // timestamp precision).+ expect(Math.abs((began?.startedAt ?? 0) - base)).toBeLessThan(0.5);+ }+ // The press began exactly 500 ms after the touch, though the timer that+ // noticed it ran 300 ms late.+ expect((began?.beganAt ?? 0) - (began?.startedAt ?? 0)).toBeCloseTo(500, 6);+ expect(states(entries, 'press')).toEqual(['began', 'ended', 'possible']);+ expect(entries.some(entry => entry.name.startsWith('click:'))).toBe(false);+});++async function scrollToCenter(page: Page, id: string): Promise<void> {+ await page.evaluate(target => {+ document.getElementById(target)?.scrollIntoView({block: 'center'});+ }, id);+}++async function resetMoves(page: Page): Promise<void> {+ await page.evaluate(() => {+ (window as unknown as {__moves: boolean[]}).__moves.length = 0;+ });+}++test('takes a pan at 10 px of travel on its axis and not at 9: the move that reaches 10 is the first cancelled (FR19)', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await logTouchMoves(page);+ const start = await center(page, 'hpan');+ await driver.play(travel(start, alongX(3, 6, 9)));+ expect(states(await log(page), 'hpan')).not.toContain('began');+ expect((await readTouchMoves(page)).some(Boolean)).toBe(false);+ await clearLog(page);+ await resetMoves(page);+ await driver.play(travel(start, alongX(3, 6, 10)));+ expect(states(await log(page), 'hpan')[0]).toBe('began');+ if (driver.engine === 'webkit') {+ // WebKit delivers every move. Chromium holds back the moves inside its+ // own touch slop, so the page sees none of them to cancel.+ const moves = await readTouchMoves(page);+ expect(moves.at(-1)).toBe(true);+ expect(moves.filter(Boolean)).toHaveLength(1);+ }+});++test('measures a pan’s travel per axis: a free pan stays possible at (7, 7) and (8, 8) and begins at (10, 10) (FR19)', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ const start = await center(page, 'pinchable');+ for (const d of [7, 8]) {+ await clearLog(page);+ await driver.play(+ travel(start, [+ {x: d - 4, y: d - 4},+ {x: d, y: d},+ ]),+ );+ expect(states(await log(page), 'pinchPan')).not.toContain('began');+ }+ await clearLog(page);+ await driver.play(+ travel(start, [+ {x: 6, y: 6},+ {x: 10, y: 10},+ ]),+ );+ expect(states(await log(page), 'pinchPan')[0]).toBe('began');+});++test('keeps a narrower author touch-action: the derived value intersected with the author’s, never wider (FR18, DEC-8)', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ // A class rule wider than what both allow is narrowed inline after a frame.+ await page.evaluate(+ async () =>+ new Promise(resolve =>+ requestAnimationFrame(() => requestAnimationFrame(resolve)),+ ),+ );+ const values = await page.evaluate(() =>+ Object.fromEntries(+ [+ 'authorNone',+ 'authorPanY',+ 'authorPinchZoom',+ 'authorPanXY',+ 'inlinePanXY',+ ].map(id => {+ const element = document.getElementById(id) as HTMLElement;+ return [+ id,+ [getComputedStyle(element).touchAction, element.style.touchAction],+ ];+ }),+ ),+ );+ expect(values).toEqual({+ // A long press derives `manipulation`; the author's `none` stands.+ authorNone: ['none', ''],+ // Author values the derived `pan-y pinch-zoom` contains: theirs, no write.+ authorPanY: ['pan-y', ''],+ authorPinchZoom: ['pinch-zoom', ''],+ // Wider author values: what both allow, written inline.+ authorPanXY: ['pan-y', 'pan-y'],+ inlinePanXY: ['pan-y', 'pan-y'],+ });+ // Each pan still takes a horizontal drag.+ for (const id of [+ 'authorPanY',+ 'authorPinchZoom',+ 'authorPanXY',+ 'inlinePanXY',+ ]) {+ await scrollToCenter(page, id);+ await clearLog(page);+ const start = await center(page, id);+ await driver.play(drag(start, {x: start.x + 60, y: start.y}, 6));+ expect(states(await log(page), id)[0]).toBe('began');+ }+ if (driver.engine === 'chromium') {+ // The browser keeps the axis the author left it, and only that: none on+ // the author's `none`, the vertical one on the author's `pan-y`.+ await scrollToCenter(page, 'authorNone');+ let before = await page.evaluate(() => window.scrollY);+ let start = await center(page, 'authorNone');+ await driver.play(drag(start, {x: start.x, y: start.y - 80}, 10));+ expect(await page.evaluate(() => window.scrollY)).toBe(before);+ await scrollToCenter(page, 'authorPanY');+ before = await page.evaluate(() => window.scrollY);+ start = await center(page, 'authorPanY');+ await driver.play(drag(start, {x: start.x, y: start.y - 80}, 10));+ expect(await page.evaluate(() => window.scrollY)).toBeGreaterThan(+ before + 20,+ );+ }+});++test('an edge-zone strip claims pan-x for its band, and a touch 1 px inside the edge begins at 15 px of inward travel, not 14 (FR18, DEC-13)', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await scrollToCenter(page, 'edgeZone');+ expect(+ await page.evaluate(() => [+ getComputedStyle(document.getElementById('edgeZone') as HTMLElement)+ .touchAction,+ getComputedStyle(document.getElementById('edgeWide') as HTMLElement)+ .touchAction,+ document+ .getElementById('edgeWide')+ ?.getAttribute('data-astryx-touch-action') ?? null,+ ]),+ ).toEqual(['pan-y pinch-zoom', 'auto', null]);+ const {y} = await center(page, 'edgeZone');+ await driver.play(travel({x: 39, y}, alongX(5, 10, 14)));+ expect(states(await log(page), 'edgeZone')).not.toContain('began');+ await clearLog(page);+ await driver.play(travel({x: 39, y}, alongX(5, 10, 15)));+ expect(states(await log(page), 'edgeZone')[0]).toBe('began');+});++test('on an element reaching beyond the band, a touch at 40 px decides at 10 px and one at 41 px fails at touch-down (FR18, DEC-13)', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await logTouchMoves(page);+ await scrollToCenter(page, 'edgeWide');+ const {y} = await center(page, 'edgeWide');+ await driver.play(travel({x: 40, y}, alongX(3, 6, 9)));+ expect(states(await log(page), 'edgeWide')).not.toContain('began');+ await clearLog(page);+ await resetMoves(page);+ await driver.play(travel({x: 40, y}, alongX(3, 6, 10)));+ expect(states(await log(page), 'edgeWide')[0]).toBe('began');+ if (driver.engine === 'webkit') {+ // From the move it begins on, it claims by cancelling them (Chromium+ // holds back moves inside its touch slop).+ expect((await readTouchMoves(page)).at(-1)).toBe(true);+ }+ await clearLog(page);+ await resetMoves(page);+ await driver.play(travel({x: 41, y}, alongX(10, 20, 30)));+ expect(states(await log(page), 'edgeWide')[0]).toBe('failed');+ expect((await readTouchMoves(page)).some(Boolean)).toBe(false);+ if (driver.engine === 'chromium') {+ // Outside the band the author's horizontal scroll goes ahead.+ await clearLog(page);+ await driver.play(drag({x: 100, y}, {x: 20, y}, 10));+ expect(states(await log(page), 'edgeWide')[0]).toBe('failed');+ expect(+ await page.evaluate(+ () => document.getElementById('edgeWide')?.scrollLeft ?? 0,+ ),+ ).toBeGreaterThan(20);+ }+});++test('under RTL the leading band is the right one: 362 px begins at 15 px leftward on the strip, and a leading pan fails a touch at 361 px (FR18, DEC-13)', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ await scrollToCenter(page, 'edgeZoneRtl');+ const zone = await center(page, 'edgeZoneRtl');+ await driver.play(travel({x: 363, y: zone.y}, alongX(-5, -10, -14)));+ expect(states(await log(page), 'edgeZoneRtl')).not.toContain('began');+ await clearLog(page);+ await driver.play(travel({x: 363, y: zone.y}, alongX(-5, -10, -15)));+ expect(states(await log(page), 'edgeZoneRtl')[0]).toBe('began');+ await scrollToCenter(page, 'edgeWideRtl');+ const wide = await center(page, 'edgeWideRtl');+ await clearLog(page);+ await driver.play(travel({x: 361, y: wide.y}, alongX(-10, -20)));+ expect(states(await log(page), 'edgeWideRtl')[0]).toBe('failed');+ await clearLog(page);+ await driver.play(travel({x: 362, y: wide.y}, alongX(-3, -6, -10)));+ expect(states(await log(page), 'edgeWideRtl')[0]).toBe('began');+});++test('a scroll under a held press takes it only once the finger is 10 px from where it landed: a still finger, 9 px and (7, 7) keep it, 10 px and (8, 8) lose it (FR20)', async ({+ page,+ browserName,+}) => {+ const driver = await open(page, browserName);+ const row = await center(page, 'scrollRow');+ const finger = (offset: Point): Finger => ({+ x: row.x + offset.x,+ y: row.y + offset.y,+ id: 1,+ });+ const cases: ReadonlyArray<{+ name: string;+ path: ReadonlyArray<Point>;+ kept: boolean;+ }> = [+ // Sub-pixel jitter where the engine takes it (WebKit's command rounds to+ // whole pixels, so there the finger is still).+ {+ name: 'still',+ path: [+ {x: 0.3, y: -0.3},+ {x: -0.3, y: 0.3},+ {x: 0.3, y: 0},+ ],+ kept: true,+ },+ {name: '9 px', path: alongX(3, 6, 9), kept: true},+ {+ name: '(7, 7)',+ path: [+ {x: 3, y: 3},+ {x: 7, y: 7},+ ],+ kept: true,+ },+ {name: '10 px', path: alongX(3, 6, 10), kept: false},+ {+ name: '(8, 8)',+ path: [+ {x: 4, y: 4},+ {x: 8, y: 8},+ ],+ kept: false,+ },+ ];+ for (const {name, path: offsets, kept} of cases) {+ await page.evaluate(() => {+ (document.getElementById('scroller') as HTMLElement).scrollTop = 0;+ });+ await clearLog(page);+ // Chromium holds back the moves inside its own touch slop, so a finger+ // held there is still to the page: it first goes past the slop, and the+ // page sees every move after that.+ const excursion: Point[] =+ driver.engine === 'chromium' ? [{x: 20, y: 20}] : [];+ const steps: Step[] = [{t: 0, down: [finger({x: 0, y: 0})]}];+ [...excursion, ...offsets].forEach((offset, index) => {+ steps.push({t: (index + 1) * 16, down: [finger(offset)]});+ });+ await driver.play(steps);+ // The finger rests at its offset while the scroller scrolls under it.+ await page.evaluate(() => {+ (document.getElementById('scroller') as HTMLElement).scrollTop += 40;+ });+ await page.waitForTimeout(100);+ await driver.play([{t: 0, down: []}]);+ const pressed = states(await log(page), 'scrollRow');+ expect(pressed[0], name).toBe('began');+ if (kept) {+ expect(pressed, name).not.toContain('cancelled');+ expect(pressed.at(-1), name).toBe('ended');+ } else {+ expect(pressed.at(-1), name).toBe('cancelled');+ }+ }+});++/** The page-level listener counts now, by type. */+async function pageListenerCounts(page: Page): Promise<Map<string, number>> {+ return new Map(await page.evaluate(() => [...window.__pageListeners]));+}++/**+ * The page-level listener types gesture work uses that are added beyond+ * `baseline`: the engine and the test runner keep listeners of their own.+ */+async function addedPageListeners(+ page: Page,+ baseline: Map<string, number>,+): Promise<string[]> {+ return [...(await pageListenerCounts(page))]+ .filter(+ ([type, count]) =>+ count > (baseline.get(type) ?? 0) &&+ /^(touch|pointer|click$|blur$|scroll$|contextmenu$|visibilitychange$)/.test(+ type,+ ),+ )+ .map(([type]) => type)+ .sort();+}++test.describe('under a fine primary pointer (spec:AST-094 FR43, FR24)', () => {+ test.use({hasTouch: false, isMobile: false});++ test('a mouse drag begins a pan at 10 px on its axis and ends it at the lift; the click after it reaches no page handler', async ({+ page,+ browserName,+ }) => {+ await open(page, browserName);+ expect(+ await page.evaluate(() => matchMedia('(pointer: coarse)').matches),+ ).toBe(false);+ const start = await center(page, 'hpan');+ await page.mouse.move(start.x, start.y);+ await page.mouse.down();+ await page.mouse.move(start.x + 9, start.y);+ expect(states(await log(page), 'hpan')).not.toContain('began');+ await page.mouse.move(start.x + 10, start.y);+ expect(states(await log(page), 'hpan')[0]).toBe('began');+ await page.mouse.up();+ const entries = await log(page);+ expect(states(entries, 'hpan').slice(-2)).toEqual(['ended', 'possible']);+ expect(entries.some(entry => entry.name.startsWith('click:'))).toBe(false);+ });++ test('a mouse tap recognizes a tap, and the right button starts nothing', async ({+ page,+ browserName,+ }) => {+ await open(page, browserName);+ const at = await center(page, 'tapper');+ await page.mouse.click(at.x, at.y, {button: 'right'});+ expect(states(await log(page), 'tap')).toEqual([]);+ await page.mouse.click(at.x, at.y);+ expect(states(await log(page), 'tap')).toContain('ended');+ });++ test('the page carries no gesture listener between presses: a press adds them, and they go after it', async ({+ page,+ browserName,+ }) => {+ await open(page, browserName);+ // Attaching every gesture of the page added no page-level listener.+ expect(await page.evaluate(() => window.__attachListeners)).toEqual([]);+ // A press that nothing claims (a pan pressed and lifted in place).+ const start = await center(page, 'hpan');+ await page.mouse.move(start.x, start.y);+ const idle = await pageListenerCounts(page);+ await page.mouse.down();+ expect(await addedPageListeners(page, idle)).toEqual(+ expect.arrayContaining(['pointercancel', 'pointermove', 'pointerup']),+ );+ await page.mouse.up();+ await page.waitForTimeout(50);+ expect(await addedPageListeners(page, idle)).toEqual([]);+ // A right click adds none.+ await page.mouse.click(start.x, start.y, {button: 'right'});+ expect(await addedPageListeners(page, idle)).toEqual([]);+ // After a claimed drag only the click swallower stays, for 1 s.+ await page.mouse.down();+ await page.mouse.move(start.x + 40, start.y, {steps: 4});+ await page.mouse.up();+ await page.waitForTimeout(50);+ expect(await addedPageListeners(page, idle)).toEqual(['click']);+ await page.waitForTimeout(1100);+ expect(await addedPageListeners(page, idle)).toEqual([]);+ });++ test('a pen drag begins a pan at 10 px like a mouse; the pen’s barrel button starts nothing', async ({+ page,+ browserName,+ }) => {+ test.skip(browserName === 'webkit', 'no pen input in WebKit’s driver');+ await open(page, browserName);+ const cdp = await page.context().newCDPSession(page);+ const pen = async (+ type: 'mousePressed' | 'mouseMoved' | 'mouseReleased',+ x: number,+ y: number,+ button: 'left' | 'right' | 'none',+ ) =>+ cdp.send('Input.dispatchMouseEvent', {+ type,+ x,+ y,+ button,+ buttons:+ type === 'mouseReleased' || button === 'none'+ ? 0+ : button === 'left'+ ? 1+ : 2,+ clickCount: type === 'mouseMoved' ? 0 : 1,+ pointerType: 'pen',+ });+ const start = await center(page, 'hpan');+ await pen('mousePressed', start.x, start.y, 'right');+ await pen('mouseMoved', start.x + 30, start.y, 'right');+ await pen('mouseReleased', start.x + 30, start.y, 'right');+ expect(states(await log(page), 'hpan')).toEqual([]);+ await pen('mousePressed', start.x, start.y, 'left');+ await pen('mouseMoved', start.x + 9, start.y, 'left');+ expect(states(await log(page), 'hpan')).not.toContain('began');+ await pen('mouseMoved', start.x + 10, start.y, 'left');+ expect(states(await log(page), 'hpan')[0]).toBe('began');+ await pen('mouseReleased', start.x + 10, start.y, 'left');+ expect(states(await log(page), 'hpan').slice(-2)).toEqual([+ 'ended',+ 'possible',+ ]);+ });+});diff --git a/packages/core/src/gestures/__tests__/browserNegotiation.test.ts b/packages/core/src/gestures/__tests__/browserNegotiation.test.tsnew file mode 100644index 0000000000..93660caee9--- /dev/null+++ b/packages/core/src/gestures/__tests__/browserNegotiation.test.ts@@ -0,0 +1,293 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file browserNegotiation.test.ts+ * @input Recognizer sets, touch-action strings, and jsdom elements with+ * scripted scroll metrics+ * @output What the browser is told (touch-action and long-press styles) and+ * what the native scroll probe answers (edges, touch-action, chaining,+ * RTL)+ * @position Unit tests of touchAction.ts and nativeScroll.ts+ */++import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import {LongPressGestureRecognizer} from '../LongPressGestureRecognizer';+import {createNativeScrollProbe, parseTouchAction} from '../nativeScroll';+import {PanGestureRecognizer} from '../PanGestureRecognizer';+import {PinchGestureRecognizer} from '../PinchGestureRecognizer';+import {ScreenEdgePanGestureRecognizer} from '../ScreenEdgePanGestureRecognizer';+import {SwipeGestureRecognizer} from '../SwipeGestureRecognizer';+import {TapGestureRecognizer} from '../TapGestureRecognizer';+import {+ deriveTouchAction,+ gestureHostStyle,+ holdSelectionStyle,+} from '../touchAction';++describe('deriveTouchAction', () => {+ it('needs nothing without touch recognizers', () => {+ expect(deriveTouchAction([])).toBeNull();+ expect(+ deriveTouchAction([+ new PanGestureRecognizer({allowedPointerTypes: ['mouse']}),+ ]),+ ).toBeNull();+ });++ it('removes only double-tap zoom for taps and long presses', () => {+ expect(deriveTouchAction([new TapGestureRecognizer()])).toBe(+ 'manipulation',+ );+ expect(deriveTouchAction([new LongPressGestureRecognizer()])).toBe(+ 'manipulation',+ );+ });++ it('gives the browser the other axis of a one-axis pan or swipe, and keeps pinch-zoom', () => {+ expect(+ deriveTouchAction([new PanGestureRecognizer({direction: 'horizontal'})]),+ ).toBe('pan-y pinch-zoom');+ expect(+ deriveTouchAction([new PanGestureRecognizer({direction: 'vertical'})]),+ ).toBe('pan-x pinch-zoom');+ expect(deriveTouchAction([new PanGestureRecognizer()])).toBe('pinch-zoom');+ expect(+ deriveTouchAction([new SwipeGestureRecognizer({direction: 'left'})]),+ ).toBe('pan-y pinch-zoom');+ });++ it('leaves the browser everything for a one-way pan, or one that shares native scrolling', () => {+ // The other direction keeps scrolling natively; the pan claims its own+ // by cancelling touchmove when it begins.+ expect(+ deriveTouchAction([new PanGestureRecognizer({direction: 'down'})]),+ ).toBeNull();+ // A screen-edge pan from one edge goes one way, inward (spec:AST-094 FR18).+ expect(+ deriveTouchAction([+ new ScreenEdgePanGestureRecognizer({edges: ['leading']}),+ ]),+ ).toBeNull();+ expect(+ deriveTouchAction([+ new PanGestureRecognizer({direction: 'down', scrollEdge: true}),+ ]),+ ).toBeNull();+ expect(+ deriveTouchAction([+ new PanGestureRecognizer({direction: 'down', scrollEdge: true}),+ new TapGestureRecognizer(),+ ]),+ ).toBe('manipulation');+ });++ it('takes pinch-zoom only for a pinch recognizer', () => {+ expect(deriveTouchAction([new PinchGestureRecognizer()])).toBe(+ 'pan-x pan-y',+ );+ expect(+ deriveTouchAction([+ new PinchGestureRecognizer(),+ new PanGestureRecognizer(),+ ]),+ ).toBe('none');+ });++ it('intersects every recognizer on the element', () => {+ expect(+ deriveTouchAction([+ new TapGestureRecognizer(),+ new PanGestureRecognizer({direction: 'horizontal'}),+ ]),+ ).toBe('pan-y pinch-zoom');+ });++ it('locks selection only for a held press, never on the element (spec:AST-094 FR41)', () => {+ // The attached style is the touch-action alone: a mouse and a keyboard+ // keep selecting (spec:AST-017 FR59).+ expect(gestureHostStyle([new LongPressGestureRecognizer()])).toEqual({+ touchAction: 'manipulation',+ });+ // The host applies this for one press, from touch-down to the lift.+ expect(holdSelectionStyle([new LongPressGestureRecognizer()])).toEqual({+ WebkitTouchCallout: 'none',+ WebkitUserSelect: 'none',+ userSelect: 'none',+ });+ // A hold that does nothing selects natively.+ expect(holdSelectionStyle([new TapGestureRecognizer()])).toBeNull();+ });+});++describe('parseTouchAction', () => {+ it('reads the pans each value allows', () => {+ expect(parseTouchAction('auto')).toEqual({x: true, y: true});+ expect(parseTouchAction('manipulation')).toEqual({x: true, y: true});+ expect(parseTouchAction('none')).toEqual({x: false, y: false});+ expect(parseTouchAction('pan-y pinch-zoom')).toEqual({x: false, y: true});+ expect(parseTouchAction('pan-left')).toEqual({x: true, y: false});+ expect(parseTouchAction('pinch-zoom')).toEqual({x: false, y: false});+ });+});++/** Give an element the scroll metrics jsdom cannot lay out. */+function scroller(+ element: HTMLElement,+ metrics: {+ scrollTop?: number;+ scrollHeight?: number;+ clientHeight?: number;+ scrollLeft?: number;+ scrollWidth?: number;+ clientWidth?: number;+ },+): void {+ for (const [key, value] of Object.entries(metrics)) {+ Object.defineProperty(element, key, {configurable: true, value});+ }+}++/**+ * jsdom drops `touch-action` from styles, so the elements under test carry+ * it in `data-touch-action` and computed style reports it from there.+ */+function withTouchActionFromData(): () => void {+ const original = window.getComputedStyle.bind(window);+ const spy = vi+ .spyOn(window, 'getComputedStyle')+ .mockImplementation((element: Element, pseudo?: string | null) => {+ const style = original(element, pseudo);+ const touchAction = element.getAttribute('data-touch-action');+ if (touchAction == null) {+ return style;+ }+ return new Proxy(style, {+ get(target, key): string | number | object | null | undefined {+ if (key === 'touchAction') {+ return touchAction;+ }+ const value = Reflect.get(target, key) as+ string | number | object | null | undefined;+ return typeof value === 'function' ? value.bind(target) : value;+ },+ });+ });+ return () => spy.mockRestore();+}++describe('createNativeScrollProbe', () => {+ let restore: () => void = () => {};+ beforeEach(() => {+ restore = withTouchActionFromData();+ });+ afterEach(() => {+ restore();+ document.body.innerHTML = '';+ document.documentElement.style.overflow = '';+ });++ function setup(listStyle: string) {+ // The page itself does not scroll in these cases.+ document.documentElement.style.overflow = 'hidden';+ document.body.innerHTML = `<div id="list" style="${listStyle}"><button id="row">Row</button></div>`;+ const list = document.getElementById('list') as HTMLElement;+ const row = document.getElementById('row') as HTMLElement;+ return {list, row};+ }++ it('answers by edge: at the top a pull down scrolls nothing, a pull up does', () => {+ const {list, row} = setup('overflow-y: auto');+ scroller(list, {scrollTop: 0, scrollHeight: 1000, clientHeight: 400});+ const probe = createNativeScrollProbe(row);+ expect(probe.canScroll(0, 20)).toBe(false);+ expect(probe.canScroll(0, -20)).toBe(true);+ expect(probe.isInsideScroller).toBe(true);+ scroller(list, {scrollTop: 600});+ expect(probe.canScroll(0, -20)).toBe(false);+ expect(probe.canScroll(0, 20)).toBe(true);+ });++ it('finds a scroller in a shadow tree around the slot a light-DOM row is slotted into', () => {+ document.documentElement.style.overflow = 'hidden';+ document.body.innerHTML =+ '<div id="host"><button id="row">Row</button></div>';+ const host = document.getElementById('host') as HTMLElement;+ const row = document.getElementById('row') as HTMLElement;+ const shadow = host.attachShadow({mode: 'open'});+ shadow.innerHTML =+ '<div id="list" style="overflow-y: auto"><slot></slot></div>';+ const list = shadow.getElementById('list') as HTMLElement;+ scroller(list, {scrollTop: 0, scrollHeight: 1000, clientHeight: 400});+ const probe = createNativeScrollProbe(row);+ expect(probe.isInsideScroller).toBe(true);+ expect(probe.canScroll(0, -20)).toBe(true);+ });++ it('puts a control in a fixed bar outside the page it floats over (spec:AST-094 FR11)', () => {+ document.body.innerHTML =+ '<div id="bar" style="position: fixed"><button id="row">Row</button></div>';+ const root = document.scrollingElement ?? document.documentElement;+ scroller(root as HTMLElement, {+ scrollTop: 0,+ scrollHeight: 3000,+ clientHeight: 800,+ });+ const probe = createNativeScrollProbe(document.getElementById('row'));+ // The page still scrolls under a drag that starts on the bar, but the bar+ // is not in a scroll view, so its control gets no content-touch delay.+ expect(probe.isInsideScroller).toBe(false);+ expect(probe.canScroll(0, -20)).toBe(true);+ for (const key of ['scrollTop', 'scrollHeight', 'clientHeight']) {+ Reflect.deleteProperty(root, key);+ }+ });++ it('honors touch-action between the touch and the scroller', () => {+ const {list, row} = setup('overflow-y: auto');+ row.setAttribute('data-touch-action', 'pan-x');+ scroller(list, {scrollTop: 100, scrollHeight: 1000, clientHeight: 400});+ const probe = createNativeScrollProbe(row);+ expect(probe.canScroll(0, 20)).toBe(false);+ expect(probe.allowsNativePan).toBe(true);+ row.setAttribute('data-touch-action', 'none');+ expect(createNativeScrollProbe(row).allowsNativePan).toBe(false);+ });++ it('ignores the wobble of a mostly straight drag', () => {+ const {list, row} = setup('overflow-x: auto; overflow-y: hidden');+ scroller(list, {scrollLeft: 50, scrollWidth: 1000, clientWidth: 300});+ const probe = createNativeScrollProbe(row);+ expect(probe.canScroll(2, 30)).toBe(false);+ expect(probe.canScroll(30, 2)).toBe(true);+ });++ it('follows the RTL scrollLeft range', () => {+ const {list, row} = setup(+ 'overflow-x: auto; overflow-y: hidden; direction: rtl',+ );+ // RTL starts at 0 and runs negative toward the inline end (the left).+ scroller(list, {scrollLeft: 0, scrollWidth: 1000, clientWidth: 300});+ const probe = createNativeScrollProbe(row);+ expect(probe.canScroll(30, 0)).toBe(true); // reveals content on the left+ expect(probe.canScroll(-30, 0)).toBe(false);+ scroller(list, {scrollLeft: -700});+ expect(probe.canScroll(30, 0)).toBe(false);+ });++ it('stops the chain at overscroll-behavior: contain', () => {+ document.documentElement.style.overflow = '';+ document.body.innerHTML = `<div id="outer" style="overflow-y: auto"><div id="inner" style="overflow-y: auto; overscroll-behavior: contain"><span id="t">x</span></div></div>`;+ const outer = document.getElementById('outer') as HTMLElement;+ const inner = document.getElementById('inner') as HTMLElement;+ scroller(outer, {scrollTop: 300, scrollHeight: 2000, clientHeight: 500});+ scroller(inner, {scrollTop: 0, scrollHeight: 800, clientHeight: 400});+ const probe = createNativeScrollProbe(document.getElementById('t'));+ // The inner list is at its top and contains its overscroll: a pull+ // down reaches nothing, though the outer one could scroll.+ expect(probe.canScroll(0, 20)).toBe(false);+ inner.style.overscrollBehavior = 'auto';+ expect(+ createNativeScrollProbe(document.getElementById('t')).canScroll(0, 20),+ ).toBe(true);+ });+});diff --git a/packages/core/src/gestures/__tests__/haptics.test.ts b/packages/core/src/gestures/__tests__/haptics.test.tsnew file mode 100644index 0000000000..c52c387696--- /dev/null+++ b/packages/core/src/gestures/__tests__/haptics.test.ts@@ -0,0 +1,187 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file haptics.test.ts+ * @input playHaptic, attachTapHaptic and the support probes, with+ * navigator.vibrate stubbed or absent, in jsdom+ * @output Vibration patterns per feedback kind where the platform vibrates,+ * nothing where it does not; the hidden switch iOS Safari plays its tap+ * haptic on: hidden from layout, touch and assistive technology, its click+ * and change kept inside, removed on release+ * @position Unit tests of packages/core/src/gestures/haptics.ts+ */++import {afterEach, describe, expect, it, vi} from 'vitest';+import {+ HAPTIC_FEEDBACK_KINDS,+ HAPTIC_VIBRATION_PATTERNS,+} from '../../motion/uikit/gestures';+import {+ attachTapHaptic,+ canVibrate,+ HAPTIC_SWITCH_ATTRIBUTE,+ playHaptic,+ supportsSwitchControl,+} from '../haptics';++const original = Object.getOwnPropertyDescriptor(navigator, 'vibrate');++function stubVibrate(implementation: (pattern: number[]) => boolean) {+ const vibrate = vi.fn(implementation);+ Object.defineProperty(navigator, 'vibrate', {+ configurable: true,+ value: vibrate,+ });+ return vibrate;+}++afterEach(() => {+ if (original == null) {+ delete (navigator as {vibrate?: unknown}).vibrate;+ } else {+ Object.defineProperty(navigator, 'vibrate', original);+ }+ document.body.innerHTML = '';+});++describe('playHaptic', () => {+ it('vibrates each feedback kind with its own pattern', () => {+ const vibrate = stubVibrate(() => true);+ expect(canVibrate()).toBe(true);+ for (const kind of HAPTIC_FEEDBACK_KINDS) {+ expect(playHaptic(kind)).toBe(true);+ expect(vibrate).toHaveBeenLastCalledWith([+ ...HAPTIC_VIBRATION_PATTERNS[kind].value,+ ]);+ }+ });++ it('plays nothing where the platform cannot vibrate, or refuses', () => {+ delete (navigator as {vibrate?: unknown}).vibrate;+ expect(canVibrate()).toBe(false);+ expect(playHaptic('impactLight')).toBe(false);+ stubVibrate(() => false);+ expect(playHaptic('selection')).toBe(false);+ });++ it('lets an error from the platform through: a vibrate that throws is not a refusal', () => {+ stubVibrate(() => {+ throw new Error('blocked');+ });+ expect(() => playHaptic('selection')).toThrow('blocked');+ });+});++describe('attachTapHaptic', () => {+ it('gives the label a hidden switch that keeps its own events inside', () => {+ document.body.innerHTML = '<label id="tap">Tap</label>';+ const label = document.getElementById('tap') as HTMLLabelElement;+ const onClick = vi.fn();+ const onChange = vi.fn();+ label.addEventListener('click', onClick);+ label.addEventListener('change', onChange);++ const release = attachTapHaptic(label);+ const input = label.querySelector(`[${HAPTIC_SWITCH_ATTRIBUTE}]`);+ expect(input).toBeInstanceOf(HTMLInputElement);+ const sw = input as HTMLInputElement;+ expect(sw.type).toBe('checkbox');+ expect(sw.hasAttribute('switch')).toBe(true);+ expect(sw.getAttribute('aria-hidden')).toBe('true');+ expect(sw.tabIndex).toBe(-1);+ // It never takes the touch itself, so a pan starting on it still+ // scrolls, and it takes no room.+ expect(sw.style.pointerEvents).toBe('none');+ expect(sw.style.position).toBe('absolute');++ // The switch toggling (the label's activation) does not reach the+ // control as a second click or a change.+ sw.click();+ expect(onClick).not.toHaveBeenCalled();+ expect(onChange).not.toHaveBeenCalled();++ release();+ expect(label.querySelector(`[${HAPTIC_SWITCH_ATTRIBUTE}]`)).toBeNull();+ });++ it('never leaves the focus on its hidden switch', () => {+ document.body.innerHTML =+ '<button id="before">Before</button><label id="tap">Tap</label>';+ const before = document.getElementById('before') as HTMLButtonElement;+ const label = document.getElementById('tap') as HTMLLabelElement;+ const release = attachTapHaptic(label);+ const sw = label.querySelector<HTMLInputElement>(+ `[${HAPTIC_SWITCH_ATTRIBUTE}]`,+ )!;+ before.focus();+ // Chromium focuses a label's control on its activation.+ sw.focus();+ expect(document.activeElement).not.toBe(sw);+ expect(document.activeElement).toBe(before);+ release();+ });++ it('keeps a label\u2019s own control: the tap plays and the control still toggles', () => {+ document.body.innerHTML =+ '<label id="tap"><input id="own" type="checkbox"> Remember me</label>';+ const label = document.getElementById('tap') as HTMLLabelElement;+ const own = document.getElementById('own') as HTMLInputElement;+ const onOwnClick = vi.fn();+ own.addEventListener('click', onOwnClick);+ const release = attachTapHaptic(label);+ const sw = label.querySelector<HTMLInputElement>(+ `[${HAPTIC_SWITCH_ATTRIBUTE}]`,+ )!;+ // The switch takes the label's activation, so a tap plays.+ expect(label.control).toBe(sw);+ // The checkbox keeps its name: the label's text, through aria-labelledby.+ expect(own).toHaveAccessibleName('Remember me');+ sw.click();+ expect(sw.checked).toBe(true);+ expect(own.checked).toBe(true);+ expect(onOwnClick).toHaveBeenCalledTimes(1);+ release();+ expect(label.control).toBe(own);+ expect(own).not.toHaveAttribute('aria-labelledby');+ });++ it('gives a disabled control no feedback and leaves no focus on the switch (FR23)', () => {+ document.body.innerHTML =+ '<button id="before">Before</button>' ++ '<label id="tap"><input id="own" type="checkbox" disabled> Remember me</label>';+ const before = document.getElementById('before') as HTMLButtonElement;+ const label = document.getElementById('tap') as HTMLLabelElement;+ const own = document.getElementById('own') as HTMLInputElement;+ const release = attachTapHaptic(label);+ const sw = label.querySelector<HTMLInputElement>(+ `[${HAPTIC_SWITCH_ATTRIBUTE}]`,+ )!;+ before.focus();+ sw.focus();+ sw.click();+ // The switch did not toggle (nothing plays), the control did not change,+ // and focus is not stranded on the hidden switch.+ expect(sw.checked).toBe(false);+ expect(own.checked).toBe(false);+ expect(document.activeElement).toBe(before);+ release();+ });++ it('leaves a label whose control is already a switch, or tied by for, as it is', () => {+ document.body.innerHTML =+ '<label id="a"><input type="checkbox" switch> Wi-Fi</label>' ++ '<label id="b" for="c">Bluetooth</label><input id="c" type="checkbox">';+ for (const id of ['a', 'b']) {+ const label = document.getElementById(id) as HTMLLabelElement;+ const release = attachTapHaptic(label);+ expect(label.querySelector(`[${HAPTIC_SWITCH_ATTRIBUTE}]`)).toBeNull();+ release();+ }+ });++ it('reports whether the browser knows the switch control', () => {+ // jsdom has no `switch` property on checkbox inputs, like browsers+ // before Safari 17.4.+ expect(supportsSwitchControl(document)).toBe(false);+ });+});diff --git a/packages/core/src/gestures/__tests__/recognizerKind.test.ts b/packages/core/src/gestures/__tests__/recognizerKind.test.tsnew file mode 100644index 0000000000..520c9c6e70--- /dev/null+++ b/packages/core/src/gestures/__tests__/recognizerKind.test.ts@@ -0,0 +1,78 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file recognizerKind.test.ts+ * @input Each recognizer of the family, and the sources of Core and Lab+ * @output A recognizer is told apart by its `kind`, never by `instanceof`+ * (architecture:react-component-runtime INV13): each one reports its kind,+ * a screen-edge pan its own; and no source checks a recognizer's class+ * @position Unit and source boundary test of packages/core/src/gestures+ */++import fs from 'node:fs';+import path from 'node:path';+import {describe, expect, it} from 'vitest';+import {LongPressGestureRecognizer} from '../LongPressGestureRecognizer';+import {PanGestureRecognizer} from '../PanGestureRecognizer';+import {PinchGestureRecognizer} from '../PinchGestureRecognizer';+import {ScreenEdgePanGestureRecognizer} from '../ScreenEdgePanGestureRecognizer';+import {SwipeGestureRecognizer} from '../SwipeGestureRecognizer';+import {TapGestureRecognizer} from '../TapGestureRecognizer';++const ROOT = path.resolve(__dirname, '../../../../..');++function sourcesUnder(directory: string): string[] {+ const files: string[] = [];+ const visit = (current: string) => {+ for (const entry of fs.readdirSync(current, {withFileTypes: true})) {+ if (entry.name === 'node_modules' || entry.name.startsWith('.')) {+ continue;+ }+ const full = path.join(current, entry.name);+ if (entry.isDirectory()) {+ visit(full);+ } else if (/\.(m?[jt]sx?)$/.test(entry.name)) {+ files.push(full);+ }+ }+ };+ if (fs.existsSync(directory)) {+ visit(directory);+ }+ return files;+}++describe('recognizer kinds', () => {+ it('each recognizer reports its kind, a screen-edge pan its own (architecture:react-component-runtime INV13)', () => {+ const kinds = [+ new TapGestureRecognizer(),+ new LongPressGestureRecognizer(),+ new PanGestureRecognizer(),+ new ScreenEdgePanGestureRecognizer({edges: ['leading']}),+ new SwipeGestureRecognizer(),+ new PinchGestureRecognizer(),+ ].map(recognizer => (recognizer as {kind?: string}).kind);+ expect(kinds).toEqual([+ 'tap',+ 'longPress',+ 'pan',+ 'screenEdgePan',+ 'swipe',+ 'pinch',+ ]);+ });++ it('is never told apart by instanceof in Core or Lab (architecture:react-component-runtime INV13)', () => {+ // Built from parts, so this file does not match itself.+ const check = new RegExp(+ ['\\binstanceof\\s+', '[A-Za-z]*', 'GestureRecognizer\\b'].join(''),+ );+ const offenders = [+ ...sourcesUnder(path.join(ROOT, 'packages/core/src')),+ ...sourcesUnder(path.join(ROOT, 'packages/lab/src')),+ ]+ .filter(file => check.test(fs.readFileSync(file, 'utf8')))+ .map(file => path.relative(ROOT, file));+ expect(offenders).toEqual([]);+ });+});diff --git a/packages/core/src/gestures/__tests__/touchActionRule.test.ts b/packages/core/src/gestures/__tests__/touchActionRule.test.tsnew file mode 100644index 0000000000..eef249c398--- /dev/null+++ b/packages/core/src/gestures/__tests__/touchActionRule.test.ts@@ -0,0 +1,54 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file touchActionRule.test.ts+ * @input markTouchAction and unmarkTouchAction on a document+ * @output Where the rule lives: an adopted constructable sheet where the+ * engine has one, a style element where it has none, and an error from a+ * constructable sheet that exists is not taken for a missing one+ * @position Unit test of packages/core/src/gestures/touchActionRule.ts+ */++import {afterEach, describe, expect, it, vi} from 'vitest';+import {markTouchAction, unmarkTouchAction} from '../touchActionRule';++afterEach(() => {+ vi.unstubAllGlobals();+ document.body.innerHTML = '';+ document.head.innerHTML = '';+});++describe('touchActionRule', () => {+ it('writes the rule into a style element where the engine has no constructable sheets', () => {+ expect('adoptedStyleSheets' in document).toBe(false);+ const element = document.createElement('div');+ document.body.append(element);+ expect(markTouchAction(element, 'pan-y')).toBe(true);+ expect(document.head.querySelector('style')?.textContent).toContain(+ 'pan-y',+ );+ unmarkTouchAction(element);+ });++ it('lets an error from a constructable sheet that exists through, instead of taking it for a missing one', () => {+ class BrokenSheet {+ constructor() {+ throw new Error('broken sheet');+ }+ replaceSync(): void {}+ }+ vi.stubGlobal('CSSStyleSheet', BrokenSheet);+ Object.defineProperty(document, 'adoptedStyleSheets', {+ configurable: true,+ writable: true,+ value: [],+ });+ try {+ const element = document.createElement('div');+ document.body.append(element);+ expect(() => markTouchAction(element, 'pan-x')).toThrow('broken sheet');+ } finally {+ delete (document as {adoptedStyleSheets?: unknown}).adoptedStyleSheets;+ }+ });+});diff --git a/packages/core/src/gestures/haptics.ts b/packages/core/src/gestures/haptics.tsnew file mode 100644index 0000000000..416129dd7d--- /dev/null+++ b/packages/core/src/gestures/haptics.ts@@ -0,0 +1,203 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file haptics.ts+ * @input A feedback kind, or a label element a real finger will tap+ * @output Exports playHaptic (vibration where the platform has it),+ * attachTapHaptic (iOS Safari's tap-moment light impact) and the support+ * probes+ * @position Haptics of packages/core/src/gestures; the kinds and the+ * vibration patterns live in the constants table (motion/uikit/gestures.ts)+ *+ * The web has one haptics API, `navigator.vibrate`, and iOS Safari does not+ * implement it. iOS Safari does play a haptic in exactly one place: when a+ * REAL tap toggles an `<input type="checkbox" switch>`, by landing on the+ * switch or on a `<label>` tied to it (and during a native drag-flip of the+ * switch). That haptic is UIImpactFeedbackGenerator(.light). WebKit requires+ * a user gesture AND a trusted event for it: a `label.click()` from script+ * does not play it (WebKit bug 309082, May 2026), so nothing can fire a+ * haptic later from JavaScript, and mid-drag haptics (detent snaps, picker+ * ticks) cannot exist in iOS Safari.+ *+ * So there are two tools:+ *+ * - `attachTapHaptic(label)` puts a visually hidden switch inside a label the+ * control renders as its tap target: every real tap on the label plays the+ * light impact at the moment of the tap. The switch itself never takes the+ * touch (`pointer-events: none`; WebKit marks a switch's `touchstart`+ * handled, which would stop a pan starting on it from scrolling the page),+ * and its own events never reach the page.+ * - `playHaptic(kind)` vibrates where `navigator.vibrate` exists (Android+ * browsers) with the kind's pattern, and does nothing elsewhere.+ *+ * UIKit's haptics follow the system setting, not Reduce Motion, so neither+ * tool consults `prefers-reduced-motion`.+ */++import {+ HAPTIC_VIBRATION_PATTERNS,+ type HapticFeedbackKind,+} from '../motion/uikit/gestures';++/** Marks the hidden switch, so click handlers can recognize and ignore it. */+export const HAPTIC_SWITCH_ATTRIBUTE = 'data-astryx-haptic-switch';++/** Whether this browser vibrates at all. */+export function canVibrate(): boolean {+ return (+ typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function'+ );+}++/** Whether this browser knows the switch control (Safari 17.4 and later). */+export function supportsSwitchControl(doc?: Document): boolean {+ const target = doc ?? (typeof document === 'undefined' ? null : document);+ if (target == null) {+ return false;+ }+ const input = target.createElement('input');+ input.type = 'checkbox';+ return 'switch' in input;+}++/**+ * Vibrate for a feedback kind where `navigator.vibrate` exists. Returns+ * whether anything was played. Never plays on iOS, which has no vibration+ * API; use `attachTapHaptic` for the tap moment there.+ */+export function playHaptic(kind: HapticFeedbackKind): boolean {+ if (!canVibrate()) {+ return false;+ }+ return navigator.vibrate([...HAPTIC_VIBRATION_PATTERNS[kind].value]);+}++const VISUALLY_HIDDEN =+ 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;' ++ 'overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;' ++ 'opacity:0;pointer-events:none;';++let nextLabelId = 0;++/** A native disabled control, or one marked `aria-disabled`. */+function isDisabledControl(control: HTMLElement): boolean {+ return (+ control.matches(':disabled') ||+ control.getAttribute('aria-disabled') === 'true'+ );+}++/** Whether `input` is a switch checkbox, which plays the tap haptic itself. */+function isSwitch(input: HTMLInputElement): boolean {+ return input.type === 'checkbox' && input.hasAttribute('switch');+}++function swallow(event: Event): void {+ event.stopPropagation();+}++/**+ * Make every real tap on `label` play iOS Safari's light impact, by giving it+ * a hidden switch to toggle. Returns a function that removes the switch.+ * Harmless where switches have no haptics.+ *+ * - The switch never keeps the focus: where a label's activation focuses+ * its control (Chromium), the focus goes on to the label's own control,+ * or back where it was, so it never lands on an `aria-hidden` element.+ * - A label that already has a control keeps it: the switch takes the+ * label's activation (it goes first) and hands the click on to that+ * control, so the tap plays and the control still toggles. The control+ * keeps its name too: while the switch is attached it is labelled by the+ * label through `aria-labelledby`, unless it already names itself. A control+ * that is itself a switch plays on its own, and a label tied to its+ * control by `for` cannot be given a second one: both are left as they+ * are.+ */+export function attachTapHaptic(label: HTMLLabelElement): () => void {+ const existing = label.control;+ if (+ (existing instanceof HTMLInputElement && isSwitch(existing)) ||+ (existing != null && label.htmlFor !== '')+ ) {+ return () => {};+ }+ const doc = label.ownerDocument;+ const input = doc.createElement('input');+ input.type = 'checkbox';+ input.setAttribute('switch', '');+ input.setAttribute(HAPTIC_SWITCH_ATTRIBUTE, '');+ input.setAttribute('aria-hidden', 'true');+ input.tabIndex = -1;+ input.style.cssText = VISUALLY_HIDDEN;+ // The label's activation clicks the switch, and that click would bubble+ // through the control as a second click: keep it, and the switch's+ // change events, inside. A label with a control of its own gets that+ // click handed on, so the control still toggles.+ // A disabled control gives no feedback (spec:AST-094 FR23): its label's+ // activation neither toggles the switch, so nothing plays, nor reaches+ // the control.+ const onClick = (event: Event) => {+ event.stopPropagation();+ if (existing != null && isDisabledControl(existing)) {+ event.preventDefault();+ return;+ }+ existing?.click();+ };+ const onFocus = (event: FocusEvent) => {+ const previous = event.relatedTarget;+ if (+ existing instanceof HTMLElement &&+ existing.tabIndex >= 0 &&+ !isDisabledControl(existing)+ ) {+ existing.focus({preventScroll: true});+ }+ if (doc.activeElement !== input) {+ return;+ }+ if (previous instanceof HTMLElement && previous.isConnected) {+ previous.focus({preventScroll: true});+ }+ if (doc.activeElement === input) {+ input.blur();+ }+ };+ input.addEventListener('click', onClick);+ input.addEventListener('change', swallow);+ input.addEventListener('input', swallow);+ input.addEventListener('focus', onFocus);+ // The switch becomes the label's control, so the control the label named+ // is named through `aria-labelledby` instead (the switch is aria-hidden,+ // so the label's text is the name).+ let labelledControl: HTMLElement | null = null;+ let addedLabelId = false;+ if (existing != null) {+ label.prepend(input);+ if (+ existing instanceof HTMLElement &&+ !existing.hasAttribute('aria-labelledby') &&+ !existing.hasAttribute('aria-label')+ ) {+ if (label.id === '') {+ label.id = `astryx-haptic-label-${(nextLabelId += 1)}`;+ addedLabelId = true;+ }+ existing.setAttribute('aria-labelledby', label.id);+ labelledControl = existing;+ }+ } else {+ label.appendChild(input);+ }+ return () => {+ labelledControl?.removeAttribute('aria-labelledby');+ if (addedLabelId) {+ label.removeAttribute('id');+ }+ input.removeEventListener('click', onClick);+ input.removeEventListener('change', swallow);+ input.removeEventListener('input', swallow);+ input.removeEventListener('focus', onFocus);+ input.remove();+ };+}diff --git a/packages/core/src/gestures/nativeScroll.ts b/packages/core/src/gestures/nativeScroll.tsnew file mode 100644index 0000000000..1b0de8835d--- /dev/null+++ b/packages/core/src/gestures/nativeScroll.ts@@ -0,0 +1,277 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file nativeScroll.ts+ * @input An element a touch landed on+ * @output Exports createNativeScrollProbe (the NativeScrollProbe a host gives+ * each touch) and parseTouchAction+ * @position DOM half of the scroll coordination in packages/core/src/gestures+ *+ * Answers one question for a recognizer without letting it touch the DOM:+ * would the browser scroll something if this finger moved that way?+ *+ * The browser scrolls the innermost scroller that has room, then chains+ * outward, so the answer is "yes" while ANY scroller under the touch can+ * still move in that direction, with three narrowings that match the+ * browser's own:+ *+ * - `touch-action` between the touch target and a scroller must allow the+ * axis, or the browser will not pan that scroller with a finger;+ * - an `overscroll-behavior` other than `auto` on the axis stops the chain at+ * that scroller (a sheet body with `contain` never scrolls the page);+ * - a finger moving down scrolls content toward its START (scrollTop+ * decreasing), and horizontally the range follows the writing direction+ * (RTL `scrollLeft` runs from minus the overflow to zero).+ *+ * Styles are read once per touch, on the first question; scroll offsets are+ * read fresh on every question, since a native scroll moves them.+ */++import type {NativeScrollProbe} from './types';++export interface AllowedPans {+ readonly x: boolean;+ readonly y: boolean;+}++/** Which pans a `touch-action` value lets the browser perform. */+export function parseTouchAction(value: string): AllowedPans {+ const tokens = value.trim().split(/\s+/);+ if (tokens.includes('auto') || tokens.includes('manipulation')) {+ return {x: true, y: true};+ }+ if (tokens.includes('none')) {+ return {x: false, y: false};+ }+ return {+ x: tokens.some(+ token =>+ token === 'pan-x' || token === 'pan-left' || token === 'pan-right',+ ),+ y: tokens.some(+ token => token === 'pan-y' || token === 'pan-up' || token === 'pan-down',+ ),+ };+}++interface ChainEntry {+ readonly element: Element;+ readonly x: boolean;+ readonly y: boolean;+ readonly isRtl: boolean;+ readonly stopsX: boolean;+ readonly stopsY: boolean;+ /**+ * The scroller sits beyond a `position: fixed` ancestor of the touch: it+ * still scrolls under the finger, but it does not carry the touched+ * element, so the element is not inside a scroll view (spec:AST-094 FR11).+ */+ readonly isBeyondFixed: boolean;+}++const SCROLLABLE = new Set(['auto', 'scroll', 'overlay']);+const EDGE_TOLERANCE = 1;++/**+ * The node's parent in the flat tree: a slotted node's slot, then out of+ * shadow roots to their hosts, so a scroller inside a shadow tree around the+ * slot is found.+ */+export function parentAcrossShadow(node: Node): Node | null {+ const slot =+ node instanceof Element || node instanceof Text ? node.assignedSlot : null;+ if (slot != null) {+ return slot;+ }+ if (node.parentNode != null) {+ return node.parentNode instanceof ShadowRoot+ ? node.parentNode.host+ : node.parentNode;+ }+ return null;+}++interface Chain {+ readonly entries: ChainEntry[];+ /** touch-action allows some pan all the way up. */+ readonly allowsPan: boolean;+}++function buildChain(target: Element): Chain {+ const doc = target.ownerDocument;+ const view = doc.defaultView;+ if (view == null) {+ return {entries: [], allowsPan: false};+ }+ const root = doc.scrollingElement ?? doc.documentElement;+ const chain: ChainEntry[] = [];+ let allowX = true;+ let allowY = true;+ let reachedRoot = false;+ let isBeyondFixed = false;+ for (+ let node: Node | null = target;+ node != null;+ node = parentAcrossShadow(node)+ ) {+ if (!(node instanceof Element)) {+ continue;+ }+ const style = view.getComputedStyle(node);+ const pans = parseTouchAction(style.touchAction || 'auto');+ allowX &&= pans.x;+ allowY &&= pans.y;+ const isRoot = node === root || node === doc.documentElement;+ if (isRoot) {+ reachedRoot = true;+ }+ const overflowX = isRoot ? rootOverflow(doc, 'x') : style.overflowX;+ const overflowY = isRoot ? rootOverflow(doc, 'y') : style.overflowY;+ const scrollsX = SCROLLABLE.has(overflowX);+ const scrollsY = SCROLLABLE.has(overflowY);+ if (scrollsX || scrollsY) {+ const element = isRoot ? root : node;+ const [behaviorX, behaviorY] = overscrollBehavior(style);+ chain.push({+ element,+ x: scrollsX && allowX,+ y: scrollsY && allowY,+ isRtl: style.direction === 'rtl',+ stopsX: behaviorX !== 'auto',+ stopsY: behaviorY !== 'auto',+ isBeyondFixed,+ });+ }+ if (isRoot) {+ break;+ }+ if (style.position === 'fixed') {+ isBeyondFixed = true;+ }+ }+ if (!reachedRoot && root instanceof Element) {+ chain.push({+ element: root,+ x: allowX && SCROLLABLE.has(rootOverflow(doc, 'x')),+ y: allowY && SCROLLABLE.has(rootOverflow(doc, 'y')),+ isRtl: false,+ stopsX: false,+ stopsY: false,+ isBeyondFixed,+ });+ }+ return {entries: chain, allowsPan: allowX || allowY};+}++/** `overscroll-behavior` per axis, from the longhands or the shorthand. */+function overscrollBehavior(style: CSSStyleDeclaration): [string, string] {+ const x = style.overscrollBehaviorX;+ const y = style.overscrollBehaviorY;+ if (x !== '' && y !== '' && x != null && y != null) {+ return [x, y];+ }+ const [first = 'auto', second = first] = (+ style.getPropertyValue('overscroll-behavior') || 'auto'+ )+ .trim()+ .split(/\s+/);+ return [x || first, y || second];+}++/**+ * The viewport scrolls unless the root or the body clips it (a scroll lock+ * sets `overflow: hidden` on one of them).+ */+function rootOverflow(doc: Document, axis: 'x' | 'y'): string {+ const view = doc.defaultView;+ if (view == null) {+ return 'hidden';+ }+ for (const element of [doc.documentElement, doc.body]) {+ if (element == null) {+ continue;+ }+ const style = view.getComputedStyle(element);+ const value = axis === 'x' ? style.overflowX : style.overflowY;+ if (value === 'hidden' || value === 'clip') {+ return 'hidden';+ }+ }+ return 'auto';+}++function canMoveY(element: Element, dy: number): boolean {+ if (element.scrollHeight - element.clientHeight <= EDGE_TOLERANCE) {+ return false;+ }+ return dy > 0+ ? element.scrollTop > EDGE_TOLERANCE - 0.5+ : element.scrollTop <+ element.scrollHeight - element.clientHeight - EDGE_TOLERANCE + 0.5;+}++function canMoveX(entry: ChainEntry, dx: number): boolean {+ const {element} = entry;+ const overflow = element.scrollWidth - element.clientWidth;+ if (overflow <= EDGE_TOLERANCE) {+ return false;+ }+ const min = entry.isRtl ? -overflow : 0;+ const max = entry.isRtl ? 0 : overflow;+ // A finger moving right drags the content right: scrollLeft decreases.+ return dx > 0+ ? element.scrollLeft > min + EDGE_TOLERANCE - 0.5+ : element.scrollLeft < max - EDGE_TOLERANCE + 0.5;+}++/** A probe of the native scrollers under `target`. */+export function createNativeScrollProbe(target: unknown): NativeScrollProbe {+ let chain: Chain | null = null;+ const getChain = (): ChainEntry[] => {+ chain ??=+ target instanceof Element+ ? buildChain(target)+ : {entries: [], allowsPan: false};+ return chain.entries;+ };+ return {+ canScroll(dx: number, dy: number): boolean {+ const ax = Math.abs(dx);+ const ay = Math.abs(dy);+ // The minor axis of a mostly-straight drag is the hand's wobble, not+ // a direction: the browser locks to the major one.+ const considerX = ax > 0 && ax >= ay / 2;+ const considerY = ay > 0 && ay >= ax / 2;+ for (const entry of getChain()) {+ if (considerY && entry.y && canMoveY(entry.element, dy)) {+ return true;+ }+ if (considerX && entry.x && canMoveX(entry, dx)) {+ return true;+ }+ const stops =+ (!considerX || entry.stopsX) && (!considerY || entry.stopsY);+ if (stops && (entry.stopsX || entry.stopsY)) {+ return false;+ }+ }+ return false;+ },+ get allowsNativePan(): boolean {+ getChain();+ return chain?.allowsPan === true;+ },+ get isInsideScroller(): boolean {+ return getChain().some(+ entry =>+ !entry.isBeyondFixed &&+ ((entry.y &&+ entry.element.scrollHeight - entry.element.clientHeight >+ EDGE_TOLERANCE) ||+ (entry.x &&+ entry.element.scrollWidth - entry.element.clientWidth >+ EDGE_TOLERANCE)),+ );+ },+ };+}diff --git a/packages/core/src/gestures/touchAction.ts b/packages/core/src/gestures/touchAction.tsnew file mode 100644index 0000000000..5400b97c90--- /dev/null+++ b/packages/core/src/gestures/touchAction.ts@@ -0,0 +1,191 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file touchAction.ts+ * @input The recognizers attached to one element+ * @output Exports deriveTouchAction (the element's `touch-action`),+ * gestureHostStyle (the inline style a host sets for its recognizers),+ * intersectTouchAction (what both a derived and a caller's value allow) and+ * holdSelectionStyle (the selection and callout lock for one held press)+ * @position Browser negotiation of packages/core/src/gestures, pure so a+ * server render can emit the same style the client would set+ *+ * `touch-action` is decided when the finger lands and cannot change during+ * the gesture, so it must say up front what the browser may still do: the+ * intersection of what every recognizer on the element leaves it.+ *+ * - A tap or long press only removes double-tap zoom (`manipulation`): no+ * 300 ms click delay, scrolling and pinch-zoom untouched.+ * - A one-axis pan or swipe gives the browser the other axis.+ * - A pan that coordinates with native scrolling (`scrollEdge`) keeps both+ * axes: who gets the drag is decided once, when it begins, and a drag the+ * browser began scrolling stays the browser's to the lift (`spec:AST-094`+ * FR14).+ * - `pinch-zoom` stays in every value unless a pinch recognizer is attached,+ * so the page stays zoomable (WCAG 1.4.4).+ *+ * WebKit pans a drag with any vertical component even under `pan-y`, so the+ * value alone does not protect a horizontal pan there: the host also cancels+ * `touchmove` while a recognizer owns the touch (see GestureHost.ts).+ */++import type {GestureRecognizer, NativeTouchBehavior} from './GestureRecognizer';++/** The intersection of what each touch recognizer leaves the browser. */+export function combinedNativeBehavior(+ recognizers: ReadonlyArray<GestureRecognizer>,+): NativeTouchBehavior {+ let panX = true;+ let panY = true;+ let pinchZoom = true;+ let doubleTapZoom = true;+ for (const recognizer of recognizers) {+ if (!recognizer.acceptsTouchInput) {+ continue;+ }+ const behavior = recognizer.nativeTouchBehavior;+ panX &&= behavior.panX;+ panY &&= behavior.panY;+ pinchZoom &&= behavior.pinchZoom;+ doubleTapZoom &&= behavior.doubleTapZoom;+ }+ return {panX, panY, pinchZoom, doubleTapZoom};+}++/** The `touch-action` value for a set of recognizers, or null for none needed. */+export function deriveTouchAction(+ recognizers: ReadonlyArray<GestureRecognizer>,+): string | null {+ const behavior = combinedNativeBehavior(recognizers);+ if (+ behavior.panX &&+ behavior.panY &&+ behavior.pinchZoom &&+ behavior.doubleTapZoom+ ) {+ return null;+ }+ if (behavior.panX && behavior.panY && behavior.pinchZoom) {+ return 'manipulation';+ }+ const tokens: string[] = [];+ if (behavior.panX) {+ tokens.push('pan-x');+ }+ if (behavior.panY) {+ tokens.push('pan-y');+ }+ if (behavior.pinchZoom) {+ tokens.push('pinch-zoom');+ }+ return tokens.length === 0 ? 'none' : tokens.join(' ');+}++export interface GestureHostStyle {+ touchAction?: string;+ WebkitTouchCallout?: string;+ WebkitUserSelect?: string;+ userSelect?: string;+}++/**+ * The style a host sets for these recognizers while they are attached: the+ * `touch-action`. Text selection is not locked here: a mouse, a keyboard and+ * assistive technology keep selecting as they do today (spec:AST-017 FR59,+ * spec:AST-094 FR41).+ */+export function gestureHostStyle(+ recognizers: ReadonlyArray<GestureRecognizer>,+): GestureHostStyle {+ const style: GestureHostStyle = {};+ const touchAction = deriveTouchAction(recognizers);+ if (touchAction != null) {+ style.touchAction = touchAction;+ }+ return style;+}++/** What a `touch-action` value lets the browser do, as tokens. */+const ALL_PANS = [+ 'pan-left',+ 'pan-right',+ 'pan-up',+ 'pan-down',+ 'pinch-zoom',+] as const;++function touchActionTokens(value: string): Set<string> {+ const parts = value+ .trim()+ .split(/\s+/)+ .filter(part => part !== '');+ const tokens = new Set<string>();+ if (parts.length === 0) {+ parts.push('auto');+ }+ for (const part of parts) {+ if (part === 'auto') {+ ALL_PANS.forEach(token => tokens.add(token));+ tokens.add('double-tap-zoom');+ } else if (part === 'manipulation') {+ ALL_PANS.forEach(token => tokens.add(token));+ } else if (part === 'pan-x') {+ tokens.add('pan-left').add('pan-right');+ } else if (part === 'pan-y') {+ tokens.add('pan-up').add('pan-down');+ } else if ((ALL_PANS as ReadonlyArray<string>).includes(part)) {+ tokens.add(part);+ }+ }+ return tokens;+}++/**+ * The `touch-action` that allows only what both values allow: the host's+ * derived value never overrides a caller's narrower one.+ */+export function intersectTouchAction(derived: string, caller: string): string {+ const own = touchActionTokens(caller);+ const both = new Set(+ [...touchActionTokens(derived)].filter(token => own.has(token)),+ );+ if (ALL_PANS.every(token => both.has(token))) {+ return both.has('double-tap-zoom') ? 'auto' : 'manipulation';+ }+ const parts: string[] = [];+ for (const [axis, start, end] of [+ ['pan-x', 'pan-left', 'pan-right'],+ ['pan-y', 'pan-up', 'pan-down'],+ ] as const) {+ if (both.has(start) && both.has(end)) {+ parts.push(axis);+ } else if (both.has(start)) {+ parts.push(start);+ } else if (both.has(end)) {+ parts.push(end);+ }+ }+ if (both.has('pinch-zoom')) {+ parts.push('pinch-zoom');+ }+ return parts.length === 0 ? 'none' : parts.join(' ');+}++/**+ * The lock a host applies for one press only, from touch-down to the lift or+ * a cancel, on an element whose hold does something (a long press): no iOS+ * callout and no text-selection start under the held finger, as a+ * long-pressed row in UIKit selects no text (spec:AST-094 FR41). Null where+ * the hold does nothing, so a long press there selects natively.+ */+export function holdSelectionStyle(+ recognizers: ReadonlyArray<GestureRecognizer>,+): GestureHostStyle | null {+ const holds = recognizers.some(+ recognizer =>+ recognizer.kind === 'longPress' && recognizer.acceptsTouchInput,+ );+ return holds+ ? {WebkitTouchCallout: 'none', WebkitUserSelect: 'none', userSelect: 'none'}+ : null;+}diff --git a/packages/core/src/gestures/touchActionRule.ts b/packages/core/src/gestures/touchActionRule.tsnew file mode 100644index 0000000000..76559b41f8--- /dev/null+++ b/packages/core/src/gestures/touchActionRule.ts@@ -0,0 +1,157 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file touchActionRule.ts+ * @input An element and the touch-action its recognizers derive+ * @output Exports markTouchAction and unmarkTouchAction: the element carries+ * the derived value in TOUCH_ACTION_ATTRIBUTE, and its document or shadow+ * root holds one zero-specificity rule per value in the first cascade+ * layer (`reset`), so any author rule, in any layer or none, or inline+ * value outranks the host's (`spec:AST-094` FR18, DEC-8); a root's rules+ * go with its last marked element (FR24)+ * @position The gesture host's touch-action writer (GestureHost.ts)+ *+ * The mark is set as a recognizer attaches, so a subtree that mounts with+ * it is styled once with its touch-action: a value written after that first+ * styling restyles every descendant (each one's effective touch-action+ * changes). Until the host reads the element's own value, the value in+ * force is the author's where the author sets one, and the derived value+ * elsewhere: never wider than the author's.+ *+ * SYNC: When modified, update GestureHost.ts.+ */++/** The attribute that carries the host's derived touch-action. */+export const TOUCH_ACTION_ATTRIBUTE = 'data-astryx-touch-action';++/**+ * The cascade layer the rules sit in: the first in the order every package+ * stylesheet declares (`spec:AST-080` FR3), so an author rule in any later+ * layer, or in none, outranks them. Unlayered, they would outrank every+ * layered author rule.+ */+const RULE_LAYER = 'reset';++type RuleRoot = Document | ShadowRoot;++/**+ * Per document or shadow root: the values it has a rule for, their rules'+ * text, where that text goes (an adopted sheet, or a style element where+ * constructable sheets are missing), and the elements marked there. The+ * rules go with the root's last marked element (`spec:AST-094` FR24).+ */+const sheets = new WeakMap<+ RuleRoot,+ {+ readonly values: Set<string>;+ readonly marked: Set<Element>;+ css: string;+ write(css: string): void;+ remove(): void;+ }+>();++/** Where each marked element's rule lives, for its unmark after it leaves. */+const markedRoots = new WeakMap<Element, RuleRoot>();++function sheetOf(root: RuleRoot) {+ let entry = sheets.get(root);+ if (entry == null) {+ const doc = root.nodeType === 9 ? (root as Document) : root.ownerDocument;+ let write: ((css: string) => void) | undefined;+ let remove: (() => void) | undefined;+ // A constructable sheet where the engine has one; a style element only+ // where it has none, so any other error from a sheet is not hidden.+ const Sheet = doc?.defaultView?.CSSStyleSheet;+ if (+ typeof Sheet === 'function' &&+ 'replaceSync' in Sheet.prototype &&+ 'adoptedStyleSheets' in root+ ) {+ const sheet = new Sheet();+ root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];+ write = css => sheet.replaceSync(css);+ remove = () => {+ root.adoptedStyleSheets = root.adoptedStyleSheets.filter(+ adopted => adopted !== sheet,+ );+ };+ } else {+ const style = doc?.createElement('style');+ const parent =+ root.nodeType === 9 ? (doc?.head ?? doc?.documentElement) : root;+ if (style != null && parent != null) {+ parent.append(style);+ write = css => {+ style.textContent = css;+ };+ remove = () => style.remove();+ }+ }+ if (write == null || remove == null) {+ return null;+ }+ entry = {values: new Set(), marked: new Set(), css: '', write, remove};+ sheets.set(root, entry);+ }+ return entry;+}++/**+ * Give `element` the derived touch-action under a rule any author rule+ * outranks. Returns false where no rule can hold it (a detached element):+ * the caller writes nothing until the element is in a document.+ */+export function markTouchAction(element: Element, value: string): boolean {+ const root = element.getRootNode() as RuleRoot;+ const entry =+ element.isConnected && (root.nodeType === 9 || 'host' in root)+ ? sheetOf(root)+ : null;+ if (entry == null) {+ return false;+ }+ if (!entry.values.has(value)) {+ entry.values.add(value);+ entry.css += `:where([${TOUCH_ACTION_ATTRIBUTE}="${value}"]){touch-action:${value}}`;+ entry.write(`@layer ${RULE_LAYER}{${entry.css}}`);+ }+ if (element.getAttribute(TOUCH_ACTION_ATTRIBUTE) !== value) {+ element.setAttribute(TOUCH_ACTION_ATTRIBUTE, value);+ }+ const previous = markedRoots.get(element);+ if (previous != null && previous !== root) {+ // Moved to another root: the old one lets it go.+ releaseMark(element, previous);+ }+ entry.marked.add(element);+ markedRoots.set(element, root);+ return true;+}++/** `root` no longer holds `element`'s mark; its last mark takes the rules. */+function releaseMark(element: Element, root: RuleRoot): void {+ const entry = sheets.get(root);+ if (entry == null) {+ return;+ }+ entry.marked.delete(element);+ if (entry.marked.size === 0) {+ entry.remove();+ sheets.delete(root);+ }+}++/**+ * Remove the host's mark; the element's own touch-action stands. The last+ * mark in a document or shadow root takes its rules with it.+ */+export function unmarkTouchAction(element: Element): void {+ element.removeAttribute(TOUCH_ACTION_ATTRIBUTE);+ const root = markedRoots.get(element);+ if (root == null) {+ return;+ }+ markedRoots.delete(element);+ releaseMark(element, root);+}diff --git a/packages/core/src/gestures/types.ts b/packages/core/src/gestures/types.tsindex 975989d0a3..064d028f18 100644--- a/packages/core/src/gestures/types.ts+++ b/packages/core/src/gestures/types.ts@@ -172,4 +172,11 @@ export interface TouchConsumer {* (attached above this consumer) from beginning for a touch on it.*/allowsAncestorRecognizer?(recognizer: unknown): boolean;+ /**+ * Whether the consumer takes touches now (a disabled control does not).+ * The host listens only while something enabled is attached+ * (`spec:AST-094` FR24); after this changes, call `host.update(element)`.+ * @default true+ */+ isEnabled?(): boolean;}diff --git a/packages/core/src/utils/primaryClick.test.ts b/packages/core/src/utils/primaryClick.test.tsnew file mode 100644index 0000000000..4bdcb3b094--- /dev/null+++ b/packages/core/src/utils/primaryClick.test.ts@@ -0,0 +1,38 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file primaryClick.test.ts+ * @input isPrimaryClick over button presses on Apple and other platforms+ * @output Tests that only the main button, and not a ctrl-click on macOS,+ * is a primary click (spec:AST-094 FR43)+ * @position Unit tests of packages/core/src/utils/primaryClick.ts+ */++import {afterEach, describe, expect, it, vi} from 'vitest';+import {isPrimaryClick} from './primaryClick';++function onPlatform(platform: string) {+ vi.spyOn(navigator, 'platform', 'get').mockReturnValue(platform);+}++afterEach(() => {+ vi.restoreAllMocks();+});++describe('isPrimaryClick (spec:AST-094 FR43)', () => {+ it('takes the main button, and no right click or pen barrel button', () => {+ onPlatform('Win32');+ expect(isPrimaryClick({button: 0, ctrlKey: false})).toBe(true);+ expect(isPrimaryClick({button: 2, ctrlKey: false})).toBe(false);+ expect(isPrimaryClick({button: 1, ctrlKey: false})).toBe(false);+ });++ it("takes no ctrl-click on macOS, that platform's context click, and a ctrl-click elsewhere", () => {+ onPlatform('MacIntel');+ expect(isPrimaryClick({button: 0, ctrlKey: true})).toBe(false);+ expect(isPrimaryClick({button: 0, ctrlKey: false})).toBe(true);+ vi.restoreAllMocks();+ onPlatform('Win32');+ expect(isPrimaryClick({button: 0, ctrlKey: true})).toBe(true);+ });+});diff --git a/packages/core/src/utils/primaryClick.ts b/packages/core/src/utils/primaryClick.tsnew file mode 100644index 0000000000..fa90fdc588--- /dev/null+++ b/packages/core/src/utils/primaryClick.ts@@ -0,0 +1,28 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file primaryClick.ts+ * @input A mouse or pen button press: its `button` and `ctrlKey`+ * @output Exports isPrimaryClick+ * @position Internal util, the one primary-click rule: the gesture host+ * starts a press only for one, and the press controller paints only one;+ * platform detection is utils/isApplePlatform.ts+ *+ * Deliberately absent from utils/index.ts: packages/core/src/index.ts does+ * `export * from './utils'`, so naming it there would publish it as API.+ */++import {isApplePlatform} from './isApplePlatform';++/**+ * Whether a button press is a primary click: the main button, and not a+ * ctrl-click on macOS or iPadOS, which is that platform's context click+ * (`spec:AST-094` FR43). A right click, a pen's barrel button and a macOS+ * ctrl-click start no press.+ */+export function isPrimaryClick(event: {+ readonly button: number;+ readonly ctrlKey: boolean;+}): boolean {+ return event.button === 0 && !(event.ctrlKey && isApplePlatform());+}