@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/gestures/GestureRecognizer.ts

@@ -24,7 +24,8 @@
  * event, so a listener that writes a transform writes it in the same frame
  * as the input, with no React render in between.
  *
- * SYNC: When modified, update GestureArena.ts.
+ * SYNC: When modified, update GestureArena.ts, recognizerInternals.ts and
+ * README.md.
  */
 
 import type {GestureArena} from './GestureArena';
@@ -38,6 +39,16 @@ import type {
 } from './types';
 import {DEFAULT_ENVIRONMENT} from './types';
 
+/**
+ * Turns text selection and the touch callout off on `elements` (and on a
+ * non-text input `target` inside one) for one held press; returns the undo.
+ * utils/selectionLock.ts's `lockSelection` is the one implementation.
+ */
+export type SelectionLock = (
+  elements: Iterable<Element>,
+  target: EventTarget | null,
+) => () => void;
+
 export interface GestureRecognizerOptions<R = GestureRecognizer> {
   /** A name for debugging and test output. */
   name?: string;
@@ -51,6 +62,18 @@ export interface GestureRecognizerOptions<R = GestureRecognizer> {
   cancelsTouchesInView?: boolean;
   /** Hold the view's touch-began until this recognizer fails. @default false */
   delaysTouchesBegan?: boolean;
+  /**
+   * For a hold that does something (a slider's thumb, a switch's or a
+   * segmented control's drag): the lock that turns text selection and the
+   * touch callout off on this recognizer's element for each held press
+   * (`spec:AST-094` FR41). Pass `lockSelection` from utils/selectionLock.ts;
+   * the host calls it and never imports it, so a component without such a
+   * hold does not bundle it. Content under a sheet's or a pager's pan stays
+   * selectable, so there is none by default; a mouse keeps desktop selection
+   * either way. A long press brings its own when it has a hold (a
+   * `minimumPressDuration` above 0); `null` brings none.
+   */
+  selectionLock?: SelectionLock | null;
   /**
    * Hold the view's touch-ended (and the browser's click) while this
    * recognizer may still recognize. @default true
@@ -60,6 +83,17 @@ export interface GestureRecognizerOptions<R = GestureRecognizer> {
   allowedPointerTypes?: ReadonlyArray<PointerKind>;
   /** Ignore a touch of a different kind than the ones already tracked. @default true */
   requiresExclusiveTouchType?: boolean;
+  /**
+   * Whether this recognizer takes its touches from the browser when it
+   * recognizes. `false` makes a watcher (a tab bar that minimizes while the
+   * page scrolls): it never claims, so it gets only passive listeners and
+   * never delays a scroll; it prevents no other recognizer and none prevents
+   * it (`spec:AST-094` FR15); it cancels no press or click under it; and it
+   * keeps tracking a touch the browser takes for a scroll,
+   * reporting through the native scroll and ending at the lift.
+   * @default true
+   */
+  claimsTouches?: boolean;
   /** gestureRecognizerShouldBegin: return false to fail instead of beginning. */
   shouldBegin?: (recognizer: R) => boolean;
   /** gestureRecognizer(_:shouldReceive:): return false to never see this touch. */
@@ -163,6 +197,8 @@ export abstract class GestureRecognizer {
   name: string;
   isEnabled: boolean;
   cancelsTouchesInView: boolean;
+  /** See GestureRecognizerOptions.selectionLock. */
+  readonly selectionLock: SelectionLock | null;
   delaysTouchesBegan: boolean;
   delaysTouchesEnded: boolean;
   allowedPointerTypes: ReadonlySet<PointerKind> | null;
@@ -174,9 +210,9 @@ export abstract class GestureRecognizer {
   view: unknown = null;
 
   /** @internal The arena delivering touches to this recognizer, if any. */
-  arena: GestureArena | null = null;
+  protected arena: GestureArena | null = null;
   /** @internal A recognition waiting for a failure requirement. */
-  pending: 'began' | 'ended' | null = null;
+  protected pending: 'began' | 'ended' | null = null;
 
   /**
    * The delegate functions. Typed against the base so a subclass stays
@@ -195,7 +231,7 @@ export abstract class GestureRecognizer {
   /** Touches currently tracked, by id. */
   protected readonly touches = new Map<number, GestureTouch>();
   /** @internal Every touch id received since the last reset. */
-  readonly seenTouchIds = new Set<number>();
+  protected readonly seenTouchIds = new Set<number>();
   private lastLocation: Point = {x: 0, y: 0};
 
   constructor(options: GestureRecognizerOptions<never> = {}) {
@@ -204,6 +240,7 @@ export abstract class GestureRecognizer {
     this.name = options.name ?? this.constructor.name;
     this.isEnabled = options.isEnabled ?? true;
     this.cancelsTouchesInView = options.cancelsTouchesInView ?? true;
+    this.selectionLock = options.selectionLock ?? null;
     this.delaysTouchesBegan = options.delaysTouchesBegan ?? false;
     this.delaysTouchesEnded = options.delaysTouchesEnded ?? true;
     this.allowedPointerTypes =
@@ -225,7 +262,7 @@ export abstract class GestureRecognizer {
    * it. Every touch recognizer claims; hover has no touches to claim.
    */
   get claimsTouches(): boolean {
-    return true;
+    return this.options.claimsTouches ?? true;
   }
 
   get state(): GestureState {
@@ -242,7 +279,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal Whether this recognizer listens to touch at all. */
-  get acceptsTouchInput(): boolean {
+  protected get acceptsTouchInput(): boolean {
     return (
       this.allowedPointerTypes == null || this.allowedPointerTypes.has('touch')
     );
@@ -299,7 +336,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal Whether this recognizer must wait for `other` to fail. */
-  requiresFailureOf(other: GestureRecognizer): boolean {
+  protected requiresFailureOf(other: GestureRecognizer): boolean {
     return (
       this.failureRequirements.has(other) ||
       this.options.shouldRequireFailureOf?.(this, other) === true ||
@@ -312,7 +349,7 @@ export abstract class GestureRecognizer {
    * (`recognizeSimultaneouslyWith` sets both sides; each delegate answers for
    * its own recognizer), so one delegate alone keeps them exclusive (FR15).
    */
-  allowsSimultaneous(other: GestureRecognizer): boolean {
+  protected allowsSimultaneous(other: GestureRecognizer): boolean {
     return (
       this.simultaneousWith.has(other) ||
       (this.options.shouldRecognizeSimultaneously?.(this, other) === true &&
@@ -321,10 +358,20 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal The delegate's should-begin answer. */
-  shouldBegin(): boolean {
+  protected shouldBegin(): boolean {
     return this.options.shouldBegin?.(this) ?? true;
   }
 
+  /**
+   * @internal Whether this recognizer holds `touchId` before it begins: the
+   * host then cancels that finger's moves as for a touch a recognizer owns.
+   * None does by default (`spec:AST-094` FR19); a scroll-edge pan holds a
+   * finger pulling away from an edge every scroller under it is at.
+   */
+  protected keepsTouch(_touchId: number): boolean {
+    return false;
+  }
+
   /** UIKit's `canPrevent(_:)`: whether recognizing fails `other`. */
   canPrevent(_other: GestureRecognizer): boolean {
     return true;
@@ -409,6 +456,10 @@ export abstract class GestureRecognizer {
     touches: ReadonlyArray<GestureTouch>,
     event: GestureEventContext,
   ): boolean {
+    if (!this.claimsTouches) {
+      // A watcher follows the browser's scroll to the lift.
+      return true;
+    }
     this.touchesCancelled(touches, event);
     return false;
   }
@@ -482,7 +533,7 @@ export abstract class GestureRecognizer {
   // --- Arena hooks (internal) ----------------------------------------------
 
   /** @internal Whether this recognizer takes `touch` right now. */
-  wantsTouch(touch: GestureTouch): boolean {
+  protected wantsTouch(touch: GestureTouch): boolean {
     if (this.state !== 'possible' && !isActive(this.state)) {
       return false;
     }
@@ -493,7 +544,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal */
-  deliverBegan(
+  protected deliverBegan(
     touches: ReadonlyArray<GestureTouch>,
     event: GestureEventContext,
   ): void {
@@ -506,7 +557,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal */
-  deliverBeganElsewhere(
+  protected deliverBeganElsewhere(
     touches: ReadonlyArray<GestureTouch>,
     event: GestureEventContext,
   ): void {
@@ -517,7 +568,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal */
-  deliverMoved(
+  protected deliverMoved(
     touches: ReadonlyArray<GestureTouch>,
     event: GestureEventContext,
   ): void {
@@ -530,7 +581,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal */
-  deliverEnded(
+  protected deliverEnded(
     touches: ReadonlyArray<GestureTouch>,
     event: GestureEventContext,
   ): void {
@@ -548,7 +599,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal */
-  deliverCancelled(
+  protected deliverCancelled(
     touches: ReadonlyArray<GestureTouch>,
     event: GestureEventContext,
   ): void {
@@ -565,7 +616,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal */
-  deliverTakenByBrowser(
+  protected deliverTakenByBrowser(
     touches: ReadonlyArray<GestureTouch>,
     event: GestureEventContext,
   ): void {
@@ -612,7 +663,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal Apply a transition the arena has approved. */
-  applyState(next: GestureState): void {
+  protected applyState(next: GestureState): void {
     const from = this.stateValue;
     if (from === next && next !== 'changed') {
       return;
@@ -635,7 +686,7 @@ export abstract class GestureRecognizer {
   }
 
   /** @internal Return to `possible` for the next attempt. */
-  resetToPossible(): void {
+  protected resetToPossible(): void {
     this.clearTimer();
     this.pending = null;
     this.touches.clear();

package/src/gestures/LongPressGestureRecognizer.ts

@@ -21,6 +21,7 @@
  */
 
 import {UIKIT_LONG_PRESS, UIKIT_TAP} from '../motion/uikit/gestures';
+import {lockSelection} from '../utils/selectionLock';
 import {travel} from './geometry';
 import {
   GestureRecognizer,
@@ -45,6 +46,11 @@ export class LongPressGestureRecognizer extends GestureRecognizer {
     return 'longPress';
   }
 
+  /** @internal The host's brand: a long press keeps the callout and selection off (recognizerInternals). */
+  protected get family(): 'longPress' {
+    return 'longPress';
+  }
+
   minimumPressDuration: number;
   allowableMovement: number;
   numberOfTapsRequired: number;
@@ -59,7 +65,20 @@ export class LongPressGestureRecognizer extends GestureRecognizer {
   beganAt: number | null = null;
 
   constructor(options: LongPressGestureRecognizerOptions = {}) {
-    super(options);
+    // A long press's hold does something (a menu, a hold-repeat): it locks
+    // selection for its press (spec:AST-094 FR41). One at 0 ms recognizes at
+    // touch-down and has no hold, so it brings none, nor does one told null:
+    // there the browser keeps its native long press.
+    super({
+      ...options,
+      selectionLock:
+        options.selectionLock !== undefined
+          ? options.selectionLock
+          : (options.minimumPressDuration ??
+                UIKIT_LONG_PRESS.minimumPressDuration.value) > 0
+            ? lockSelection
+            : null,
+    });
     this.minimumPressDuration =
       options.minimumPressDuration ??
       UIKIT_LONG_PRESS.minimumPressDuration.value;

package/src/gestures/PanGestureRecognizer.ts

@@ -91,6 +91,11 @@ export class PanGestureRecognizer extends GestureRecognizer {
     return 'pan';
   }
 
+  /** @internal The host's brand: a pan follows the one-finger rule (recognizerInternals). */
+  protected get family(): 'pan' {
+    return 'pan';
+  }
+
   minimumNumberOfTouches: number;
   maximumNumberOfTouches: number;
   hysteresis: number;
@@ -368,6 +373,36 @@ export class PanGestureRecognizer extends GestureRecognizer {
     this.offset = {x: -swallowed.x, y: -swallowed.y};
   }
 
+  /**
+   * A scroll-edge pan holds its finger from the first move while every
+   * scroller under it is at its edge and the finger pulls away from that
+   * edge, the pan's own way (`spec:AST-094` FR19, DEC-18):
+   * the browser would only rubber-band there. It still begins at its
+   * hysteresis; a move the content can still scroll stays the browser's,
+   * and so does every move while a second finger is down (a pinch).
+   */
+  protected override keepsTouch(touchId: number): boolean {
+    const touch = this.touches.get(touchId);
+    if (
+      !this.scrollEdge ||
+      this.state !== 'possible' ||
+      // A lone finger only: two fingers before a claim are the page's pinch
+      // (spec:AST-094 FR10).
+      this.touches.size !== 1 ||
+      touch == null ||
+      touch.pointerType !== 'touch' ||
+      touch.takenByBrowser
+    ) {
+      return false;
+    }
+    const moved = this.raw;
+    return (
+      (moved.x !== 0 || moved.y !== 0) &&
+      this.classify(moved) === 'begin' &&
+      !this.nativeCanScroll(moved.x, moved.y)
+    );
+  }
+
   private nativeCanScroll(dx: number, dy: number): boolean {
     for (const touch of this.touches.values()) {
       if (touch.scroll?.canScroll(dx, dy) === true) {

package/src/gestures/PinchGestureRecognizer.ts

@@ -43,7 +43,8 @@ export class PinchGestureRecognizer extends GestureRecognizer {
   private initialSpan = 0;
   private scaleValue = 1;
   private readonly tracker = new VelocityTracker();
-  private lastTime = 0;
+  /** The lift's event time, for the stillness reset. */
+  private liftTime: number | undefined;
 
   constructor(options: PinchGestureRecognizerOptions = {}) {
     super(options);
@@ -59,17 +60,18 @@ export class PinchGestureRecognizer extends GestureRecognizer {
   set scale(value: number) {
     const span = this.span();
     if (span > 0 && value > 0) {
+      const factor = this.scaleValue > 0 ? value / this.scaleValue : 1;
       this.initialSpan = span / value;
       this.scaleValue = value;
-      // The velocity continues from the re-based value, without a jump.
-      this.tracker.reset();
-      this.tracker.add(value, 0, this.lastTime);
+      // The velocity continues from the re-based value, without a jump: the
+      // samples scale with it, keeping the release.
+      this.tracker.scaleBy(factor);
     }
   }
 
   /** Scale per second (UIKit's filter; measured for pans, assumed here). */
   get velocity(): number {
-    return this.tracker.velocity().x;
+    return this.tracker.velocity(this.liftTime).x;
   }
 
   /** The midpoint between the two fingers. */
@@ -90,7 +92,6 @@ export class PinchGestureRecognizer extends GestureRecognizer {
     _touches: ReadonlyArray<GestureTouch>,
     event: GestureEventContext,
   ): void {
-    this.lastTime = event.time;
     if (this.numberOfTouches === 2) {
       this.initialSpan = this.span();
       this.scaleValue = 1;
@@ -106,7 +107,6 @@ export class PinchGestureRecognizer extends GestureRecognizer {
     if (this.numberOfTouches < 2 || this.initialSpan <= 0) {
       return;
     }
-    this.lastTime = event.time;
     const span = this.span();
     // Once recognized, a pinch waiting on a recognizer it requires to fail
     // keeps its re-based start: its moves only follow the fingers.
@@ -131,11 +131,16 @@ export class PinchGestureRecognizer extends GestureRecognizer {
     }
   }
 
-  protected override touchesEnded(): void {
+  protected override touchesEnded(
+    _touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void {
+    this.liftTime = event.time;
     this.setState(isActive(this.state) ? 'ended' : 'failed');
   }
 
   protected override reset(): void {
+    this.liftTime = undefined;
     this.initialSpan = 0;
     this.scaleValue = 1;
     this.tracker.reset();

package/src/gestures/PressTracker.ts

@@ -46,10 +46,10 @@
  * swallows for a touch a recognizer took.
  */
 
-import {UIKIT_GESTURES} from '../motion/uikit/gestures';
+import {UIKIT_CONTROL, UIKIT_PAN, UIKIT_PRESS} from '../motion/uikit/gestures';
 import {timing} from '../motion/uikit/timing';
 import {travel} from './geometry';
-import type {GestureRecognizer} from './GestureRecognizer';
+import type {GestureRecognizer, SelectionLock} from './GestureRecognizer';
 import type {TapGestureRecognizer} from './TapGestureRecognizer';
 import type {GestureTouch, TouchConsumer} from './types';
 
@@ -77,6 +77,24 @@ export interface PressTrackerOptions {
   view?: unknown;
   onControlEvent?: (event: ControlEvent, touch: GestureTouch) => void;
   onHighlightChange?: (isHighlighted: boolean) => void;
+  /**
+   * A continuous-tracking control (a held stepper) keeps its touch once its
+   * press is delivered: the host cancels the browser's pan for that finger,
+   * as UIKit's `touchesShouldCancel(in:)` is false for a tracking control.
+   * Its element then gets a blocking `touchmove` listener, so a scroll that
+   * starts on it waits on the main thread: never set it on plain buttons,
+   * links, cards or list cells.
+   * @default false
+   */
+  keepsTouch?: boolean;
+  /**
+   * For a control whose own record defines a hold action (a stepper's
+   * hold-repeat): pass `lockSelection` (utils/selectionLock.ts) to turn
+   * text selection and the callout off for each press by a finger or a pen,
+   * under any primary pointer (`spec:AST-094` FR41). A control whose hold
+   * does nothing passes none. @default undefined
+   */
+  selectionLock?: SelectionLock;
   trackingExpansion?: number;
   /**
    * When the highlight waits `contentTouchDelay`: inside a scroller (a
@@ -107,7 +125,7 @@ export interface PressTrackerOptions {
   isBraking?: (touch: GestureTouch) => boolean;
 }
 
-const PRESS = UIKIT_GESTURES.press;
+const PRESS = UIKIT_PRESS;
 
 export type PressHighlightDelay = 'inScrollers' | 'always' | 'never';
 
@@ -139,7 +157,7 @@ export const PRESS_PROFILES = {
    */
   cell: {
     highlightDelay: 'inScrollers',
-    cancelTravel: UIKIT_GESTURES.pan.hysteresis.value,
+    cancelTravel: UIKIT_PAN.hysteresis.value,
     quickTapFlash: 0,
     releaseMs: timing.press.highlightOutMs,
   },
@@ -163,8 +181,8 @@ export function vetoesSingleTap(recognizer: GestureRecognizer): boolean {
 /**
  * A control's touch tracking, the gesture host's consumer for one element
  * (UIControl's `beginTracking` / `continueTracking` / `endTracking`): it
- * reports control events and the highlight. Built by
- * {@link createPressTracker}.
+ * reports control events and the highlight, and keeps a continuous-tracking
+ * control's touch. Built by {@link createPressTracker}.
  */
 export interface PressTracker extends TouchConsumer {
   /** Whether the control paints its pressed highlight now. */
@@ -186,10 +204,21 @@ export interface PressTracker extends TouchConsumer {
   allowsAncestorRecognizer(recognizer: unknown): boolean;
   /** Drop any highlight and timers (the control unmounted or was disabled). */
   dispose(): void;
+  /**
+   * Present only for a continuous-tracking control created with
+   * `keepsTouch: true` (a held stepper): once its press is delivered, the
+   * browser's pan must not take the touch. A plain pressable leaves it
+   * undefined and keeps passive listeners, so a scroll starting on it never
+   * waits on the main thread.
+   */
+  readonly keepsTouch?: (touchId: number) => boolean;
+  /** The selection lock of a control whose hold acts (FR41); see the option. */
+  readonly selectionLock: SelectionLock | undefined;
 }
 
 /** Track a control's touches (see {@link PressTracker}). */
 export function createPressTracker(options: PressTrackerOptions): PressTracker {
+  let isKept = false;
   let touchId: number | null = null;
   let bounds: PressBounds | null = null;
   let highlightTimer: ReturnType<typeof setTimeout> | null = null;
@@ -220,6 +249,11 @@ export function createPressTracker(options: PressTrackerOptions): PressTracker {
   };
 
   const setHighlighted = (value: boolean): void => {
+    if (value && touchId != null) {
+      // Delivered: the control keeps this touch until it ends (also when a
+      // quick tap's flash is still showing as the press arrives).
+      isKept = true;
+    }
     if (state.isHighlighted === value) {
       return;
     }
@@ -242,6 +276,8 @@ export function createPressTracker(options: PressTrackerOptions): PressTracker {
   };
 
   const finish = (): void => {
+    // A highlight shown at the lift (a quick tap's flash) keeps nothing.
+    isKept = false;
     touchId = null;
     state.isTracking = false;
     state.isTouchInside = false;
@@ -252,6 +288,7 @@ export function createPressTracker(options: PressTrackerOptions): PressTracker {
     if (touch.id !== touchId) {
       return;
     }
+    isKept = false;
     clearHighlightTimer();
     emit('touchCancel', touch);
     setHighlighted(false);
@@ -269,8 +306,7 @@ export function createPressTracker(options: PressTrackerOptions): PressTracker {
       return state.isTouchInside;
     },
     trackingExpansion:
-      options.trackingExpansion ??
-      UIKIT_GESTURES.control.trackingExpansion.value,
+      options.trackingExpansion ?? UIKIT_CONTROL.trackingExpansion.value,
 
     isEnabled(): boolean {
       return options.isEnabled?.() !== false;
@@ -341,6 +377,7 @@ export function createPressTracker(options: PressTrackerOptions): PressTracker {
       if (touch.id !== touchId) {
         return;
       }
+      isKept = false;
       const inside = contains(touch);
       const wasPending = highlightTimer != null;
       clearHighlightTimer();
@@ -381,6 +418,16 @@ export function createPressTracker(options: PressTrackerOptions): PressTracker {
       setHighlighted(false);
       finish();
     },
+
+    get selectionLock() {
+      return options.selectionLock;
+    },
   };
+  if (options.keepsTouch === true) {
+    // Only the tracked touch whose press was delivered is kept.
+    return Object.assign(tracker, {
+      keepsTouch: (id: number) => isKept && touchId === id,
+    });
+  }
   return tracker;
 }