@astryxdesign/core 0.7.7-canary.550ff21 → 0.7.7-canary.58c5b8a

package/src/gestures/GestureHost.ts

@@ -110,8 +110,9 @@
  *   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.
+ * - A `contextmenu` while a recognizer owns a touch, or while a press
+ *   consumer holds the menu closed (`holdsContextMenu`), is cancelled. So a
+ *   long press never also opens the browser's menu.
  * - When the app loses focus (a window blur, a hidden page), every touch in
  *   flight is cancelled, as in UIKit; a finger the browser keeps alive lifts
  *   on nothing: its `touchend` is cancelled (`spec:AST-094` FR28).
@@ -474,6 +475,16 @@ interface WheelFollow {
   /** The fingers' speed at that move, content px per ms. */
   speedX: number;
   speedY: number;
+  /**
+   * The reading behind that speed: the fingers' travel where it began, and
+   * its interval in ms.
+   */
+  readFromX: number;
+  readFromY: number;
+  readSpan: number;
+  /** The fingers' speed before that reading, content px per ms. */
+  priorSpeedX: number;
+  priorSpeedY: number;
 }
 
 /**
@@ -502,6 +513,39 @@ function absorbedDebt(debt: number, moved: number): number {
   return Math.sign(debt) * Math.max(0, Math.abs(debt) - Math.abs(moved) / 2);
 }
 
+/**
+ * A stall held a bunched wheel's frames back, and the move just before it took
+ * their time. So the wheel joins that move's reading. It can restore what the
+ * late move lowered, but never passes the speed before it.
+ */
+function joinReading(f: WheelFollow, trueX: number, trueY: number): void {
+  if (f.readSpan <= 0) {
+    return;
+  }
+  f.speedX = joinedSpeed(
+    f.speedX,
+    (trueX - f.readFromX) / f.readSpan,
+    f.priorSpeedX,
+  );
+  f.speedY = joinedSpeed(
+    f.speedY,
+    (trueY - f.readFromY) / f.readSpan,
+    f.priorSpeedY,
+  );
+}
+
+/**
+ * A joined reading, held to the speed before the late move. It only ever
+ * raises the current speed, in the current direction.
+ */
+function joinedSpeed(current: number, reading: number, prior: number): number {
+  const held =
+    Math.sign(reading) * Math.min(Math.abs(reading), Math.abs(prior));
+  return held * current >= 0 && Math.abs(held) > Math.abs(current)
+    ? held
+    : current;
+}
+
 /**
  * `target` where it is ahead of `shown` in the direction of `speed`, else
  * `shown`: a reconcile that never steps back.
@@ -687,6 +731,12 @@ export class GestureHost {
    * lift click (`spec:AST-094` FR28: nothing acts).
    */
   private readonly cancelledFingers = new Set<number>();
+  /**
+   * The pens and pointer-read fingers that the app's lost focus cancelled,
+   * by pointer id. Each is kept until its lift, which must not click either,
+   * or until a new press.
+   */
+  private readonly cancelledPointers = new Map<number, PointerKind>();
   /** Touch.identifier → the element the finger landed on. */
   private readonly touchTargets = new Map<number, EventTarget>();
   /**
@@ -711,6 +761,8 @@ export class GestureHost {
   private readonly processed = new WeakSet<Event>();
   /** pointerId → arena id, for live mouse and pen contacts. */
   private readonly pointerIds = new Map<number, number>();
+  /** Each contact's kind: a blur refuses a pen's or a pointer-read finger's lift, never a mouse's. */
+  private readonly pointerKinds = new Map<number, PointerKind>();
   /**
    * 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
@@ -1202,12 +1254,17 @@ export class GestureHost {
    * cancels it (or the click guard drops it, a late one included) and this one
    * is the tap's single activation.
    */
-  private clickRetargeted(target: EventTarget, x: number, y: number): void {
+  private clickRetargeted(
+    target: EventTarget,
+    x: number,
+    y: number,
+    pointerType: string,
+  ): void {
     const view = this.doc.defaultView;
     if (!(target instanceof Element) || !target.isConnected || view == null) {
       return;
     }
-    armClickGuard(this.doc);
+    armClickGuard(this.doc, {takesLateMouse: pointerType === 'touch'});
     if (
       target instanceof view.HTMLElement &&
       target.matches('input, textarea, select, [contenteditable]')
@@ -1771,13 +1828,36 @@ export class GestureHost {
     }
   }
 
-  /** After a contact ends: an armed press that is over stops listening. */
+  /**
+   * A new press is a new gesture, as the click guard reads one, so the lifts
+   * the blur cancelled owe nothing after it. A second finger keeps the other
+   * fingers' refusals, since those fingers may still be down.
+   */
+  private dropCancelledLifts(event: PointerEvent): void {
+    const isSecond = event.pointerType === 'touch' && event.isPrimary === false;
+    for (const [pointerId, kind] of [...this.cancelledPointers]) {
+      if (pointerId === event.pointerId || !(isSecond && kind === 'touch')) {
+        this.cancelledPointers.delete(pointerId);
+      }
+    }
+  }
+
+  /**
+   * After a contact ends: an armed press that is over stops listening. A
+   * contact the lost focus cancelled still owes its lift, so the press is
+   * not over until that lift comes. A lift the page never hears ends it at
+   * the next press, or at a cancel.
+   */
   private releaseArmedPress(): void {
     if (!this.isArmedPress) {
       return;
     }
     queueMicrotask(() => {
-      if (this.isArmedPress && this.arena.touches.length === 0) {
+      if (
+        this.isArmedPress &&
+        this.arena.touches.length === 0 &&
+        this.cancelledPointers.size === 0
+      ) {
         this.isArmedPress = false;
         this.syncKeptPresses();
         this.syncListeners();
@@ -1808,6 +1888,7 @@ export class GestureHost {
         return;
       }
       this.cancelledFingers.clear();
+      this.cancelledPointers.clear();
       this.clearClaimedLifts();
       this.cancelCallerRead?.();
       this.cancelCallerRead = null;
@@ -2270,9 +2351,22 @@ export class GestureHost {
       }
       if (this.wheelSegment?.decaying === true) {
         // Undecided: the real deltas wait for the splitter while the
-        // fingers' last speed carries the pan on.
+        // fingers' last speed carries the pan on. A held wheel with its own
+        // frame ends the reading a stall's bunch joins.
         f.heldX += dx;
         f.heldY += dy;
+        if (this.wheelSegment.bunched) {
+          // A raised speed moves on from where the pan is shown, so the
+          // position never jumps inside the bunch.
+          const since = time - f.lastMove;
+          const speedX = f.speedX;
+          const speedY = f.speedY;
+          joinReading(f, f.trueX - f.heldX, f.trueY - f.heldY);
+          f.baseX += (speedX - f.speedX) * since;
+          f.baseY += (speedY - f.speedY) * since;
+        } else {
+          f.readSpan = 0;
+        }
         this.followProvisionally(gesture, f, time);
         return;
       }
@@ -2285,8 +2379,18 @@ export class GestureHost {
       const debtY = absorbedDebt(gesture.y - beforeY, dy);
       const trueX = beforeX - dx;
       const trueY = beforeY - dy;
+      // A wheel the splitter reads as one stall's merge has no speed of its
+      // own. It joins the reading of the move before its bunch, whose
+      // interval holds its time.
       const elapsed = time - f.lastMove;
-      if (elapsed > 0) {
+      if (this.wheelSegment?.bunched === true) {
+        joinReading(f, trueX, trueY);
+      } else if (elapsed > 0) {
+        f.priorSpeedX = f.speedX;
+        f.priorSpeedY = f.speedY;
+        f.readFromX = f.trueX;
+        f.readFromY = f.trueY;
+        f.readSpan = elapsed;
         f.speedX = (trueX - f.trueX) / elapsed;
         f.speedY = (trueY - f.trueY) / elapsed;
       }
@@ -2437,6 +2541,11 @@ export class GestureHost {
         baseY: kept.y,
         speedX: 0,
         speedY: 0,
+        readFromX: kept.x,
+        readFromY: kept.y,
+        readSpan: 0,
+        priorSpeedX: 0,
+        priorSpeedY: 0,
       };
     }
     this.arena.began(
@@ -2857,13 +2966,19 @@ export class GestureHost {
       if (locksSelectionFor('touch')) {
         toLock.push({id, target, consumerElement});
       }
-      // The finger's events keep going to what the engine hit.
+      // The finger's events keep going to what the engine hit. A disabled
+      // participant can never claim, so a scroll never waits on it.
       this.watchTarget(
         touch.identifier,
         native,
-        recognizers.some(claimsWhileMoving) || consumer?.keepsTouch != null,
-        consumer != null ||
-          recognizers.some(recognizer => recognizer.claimsTouches),
+        recognizers.some(
+          recognizer => recognizer.isEnabled && claimsWhileMoving(recognizer),
+        ) ||
+          (consumer?.keepsTouch != null && consumer.isEnabled?.() !== false),
+        (consumer != null && consumer.isEnabled?.() !== false) ||
+          recognizers.some(
+            recognizer => recognizer.isEnabled && recognizer.claimsTouches,
+          ),
       );
       this.lastFed.set(id, {x: touch.clientX, y: touch.clientY, time});
       this.pairTouch(id, {x: touch.clientX, y: touch.clientY, target: native});
@@ -2898,6 +3013,11 @@ export class GestureHost {
     for (const input of untracked) {
       this.arena.untrackedBegan(input);
     }
+    // Again once the new fingers are delivered: a pinch's second finger may
+    // have landed on another one-finger pan, the next row.
+    if (this.fingerTargets.length > 1 && !this.isFingerClaimed()) {
+      this.failUnclaimedLoneFingerPans();
+    }
     // Stamped after the consumers judged the touch: the brake asks whether
     // an EARLIER finger is still driving a scroll.
     const landed = landedOn(event);
@@ -3143,7 +3263,14 @@ export class GestureHost {
     // A tap sent to what is drawn: the engine's click would hit the layout
     // position, so it is cancelled and the tap clicks what it touched.
     for (const end of retargetedEnds) {
-      if (this.clickRetargetedTap(end.landed, end, dispositions.get(end.id))) {
+      if (
+        this.clickRetargetedTap(
+          end.landed,
+          end,
+          dispositions.get(end.id),
+          'touch',
+        )
+      ) {
         cancelsClick = true;
       }
     }
@@ -3151,7 +3278,7 @@ export class GestureHost {
       if (event.cancelable) {
         event.preventDefault();
       }
-      armClickGuard(this.doc);
+      armClickGuard(this.doc, {takesLateMouse: true});
     }
   };
 
@@ -3165,6 +3292,7 @@ export class GestureHost {
     landed: {x: number; y: number; target: EventTarget} | undefined,
     end: {x: number; y: number},
     disposition: ClickDisposition | undefined,
+    pointerType: string,
   ): boolean {
     if (landed == null || disposition !== 'allow') {
       return false;
@@ -3173,7 +3301,7 @@ export class GestureHost {
     if (moved > UIKIT_TAP.allowableMovement.value) {
       return false;
     }
-    this.clickRetargeted(landed.target, end.x, end.y);
+    this.clickRetargeted(landed.target, end.x, end.y, pointerType);
     return true;
   }
 
@@ -3485,6 +3613,7 @@ export class GestureHost {
     if (!isPointerKind(event.pointerType)) {
       return;
     }
+    this.dropCancelledLifts(event);
     if (event.pointerType === 'touch' && this.usesTouchEvents) {
       this.pairPointer(event.pointerId, {
         x: event.clientX,
@@ -3493,6 +3622,13 @@ export class GestureHost {
       });
       return;
     }
+    if (event.pointerType === 'touch' && event.isPrimary === false) {
+      // Fingers from pointer events: a second one, wherever either lands,
+      // leaves the two to the page's pinch, as onTouchStart does. A finger
+      // that is not the primary pointer is a second finger, even where the
+      // host never heard the first.
+      this.failUnclaimedLoneFingerPans();
+    }
     // A right click, a pen's barrel button, or a ctrl-click on macOS (its
     // context click) starts no press (FR43).
     if (event.pointerType !== 'touch' && !isPrimaryClick(event)) {
@@ -3514,6 +3650,7 @@ export class GestureHost {
     }
     const id = this.nextId++;
     this.pointerIds.set(event.pointerId, id);
+    this.pointerKinds.set(event.pointerId, event.pointerType);
     if (target !== landed && target != null) {
       this.retargeted.set(id, {x: event.clientX, y: event.clientY, target});
     }
@@ -3535,6 +3672,15 @@ export class GestureHost {
         consumer,
       },
     ]);
+    if (
+      event.pointerType === 'touch' &&
+      event.isPrimary === false &&
+      !this.isFingerClaimed()
+    ) {
+      // Again once this finger is delivered: it may have landed on another
+      // one-finger pan.
+      this.failUnclaimedLoneFingerPans();
+    }
     if (locksSelectionFor(event.pointerType)) {
       // The presented target: what the pen is on, where the engine's own
       // hit test may still see the motion's start.
@@ -3593,9 +3739,14 @@ export class GestureHost {
     }
     const id = this.pointerIds.get(event.pointerId);
     if (id == null) {
+      // A contact the lost focus cancelled: its lift clicks nothing.
+      if (this.cancelledPointers.delete(event.pointerId)) {
+        this.refuseCancelledLift(event);
+      }
       return;
     }
     this.pointerIds.delete(event.pointerId);
+    this.pointerKinds.delete(event.pointerId);
     this.unlockSelection(id);
     const dispositions = this.arena.ended([
       {id, x: event.clientX, y: event.clientY, time: eventTime(event)},
@@ -3607,9 +3758,10 @@ export class GestureHost {
       landed,
       {x: event.clientX, y: event.clientY},
       dispositions.get(id),
+      event.pointerType,
     );
     if (!clicked && needsSuppression(dispositions)) {
-      armClickGuard(this.doc);
+      armClickGuard(this.doc, {takesLateMouse: event.pointerType === 'touch'});
     }
     // A finger read from its pointer events: the touchend that follows the
     // lift is cancelled when a gesture took it, which the lift itself may
@@ -3698,9 +3850,12 @@ export class GestureHost {
       }
       return;
     }
+    // A contact that ends in a cancel owes no refused lift.
+    this.cancelledPointers.delete(event.pointerId);
     const id = this.pointerIds.get(event.pointerId);
     if (id != null) {
       this.pointerIds.delete(event.pointerId);
+      this.pointerKinds.delete(event.pointerId);
       this.unlockSelection(id, true);
       this.retargeted.delete(id);
       this.arena.cancelled([id], eventTime(event));
@@ -3767,7 +3922,10 @@ export class GestureHost {
 
   private readonly onContextMenu = (event: MouseEvent): void => {
     for (const touch of this.arena.touches) {
-      if (this.arena.isClaimed(touch.id)) {
+      if (
+        this.arena.isClaimed(touch.id) ||
+        this.arena.consumerOf(touch.id)?.holdsContextMenu?.(touch.id) === true
+      ) {
         event.preventDefault();
         return;
       }
@@ -3902,20 +4060,26 @@ export class GestureHost {
       }
     }
   }
+  /** Whether a finger's drag is claimed: then two fingers make no pinch. */
+  private isFingerClaimed(): boolean {
+    return this.arena.touches.some(
+      touch => touch.pointerType === 'touch' && this.arena.isClaimed(touch.id),
+    );
+  }
 
   private readonly onVisibilityChange = (): void => {
     if (this.doc.visibilityState === 'hidden') {
       this.cancelEverything(this.arena.now());
-      // As at a blur: the press sends no further pointer event, so an armed
-      // press's page listeners go now (FR24).
+      // As at a blur: an armed press's page listeners go once nothing is left
+      // to hear.
       this.releaseArmedPress();
     }
   };
 
   private readonly onBlur = (): void => {
     this.cancelEverything(this.arena.now());
-    // The press a blur ends sends no further pointer event: an armed press's
-    // page listeners go now, as at its lift (FR24).
+    // An armed press's page listeners go once nothing is left to hear. A pen
+    // or a pointer-read finger the blur cancelled still owes its lift.
     this.releaseArmedPress();
   };
 
@@ -3938,8 +4102,27 @@ export class GestureHost {
     );
   }
 
+  /**
+   * The lift of a contact the lost focus cancelled: its click is refused,
+   * and a finger's touchend after it is cancelled.
+   */
+  private refuseCancelledLift(event: PointerEvent): void {
+    armClickGuard(this.doc, {takesLateMouse: event.pointerType === 'touch'});
+    if (event.pointerType === 'touch') {
+      // Noted as a claimed lift is: capped, and gone after its time.
+      this.noteClaimedLift(event);
+    }
+  }
+
   /** The app lost focus: UIKit cancels every touch in flight. */
   private cancelEverything(time: number): void {
+    // The browser may keep a pen or a pointer-read finger down: its lift must
+    // not click. A mouse button held through the blur keeps its click.
+    for (const [pointerId, kind] of this.pointerKinds) {
+      if (kind !== 'mouse') {
+        this.cancelledPointers.set(pointerId, kind);
+      }
+    }
     const ids = [...this.pointerIds.values()];
     for (const id of ids) {
       this.unlockSelection(id, true);
@@ -3953,6 +4136,7 @@ export class GestureHost {
       }
     }
     this.pointerIds.clear();
+    this.pointerKinds.clear();
     this.retargeted.clear();
     this.fingerPointers.clear();
     this.pendingPointers.clear();

package/src/gestures/PressTracker.ts

@@ -95,6 +95,12 @@ export interface PressTrackerOptions {
    * does nothing passes none. @default undefined
    */
   selectionLock?: SelectionLock;
+  /**
+   * Whether the press of `touchId` holds the browser's context menu closed
+   * now; the host then cancels it. For a control whose hold acts, such as a
+   * switch. @default undefined
+   */
+  holdsContextMenu?: (touchId: number) => boolean;
   trackingExpansion?: number;
   /**
    * When the highlight waits `contentTouchDelay`: inside a scroller (a
@@ -312,6 +318,10 @@ export function createPressTracker(options: PressTrackerOptions): PressTracker {
       return options.isEnabled?.() !== false;
     },
 
+    holdsContextMenu(id: number): boolean {
+      return options.holdsContextMenu?.(id) === true;
+    },
+
     touchBegan(touch: GestureTouch): void {
       if (
         touchId != null ||

package/src/gestures/types.ts

@@ -202,6 +202,12 @@ export interface TouchConsumer {
    * undefined and keeps the browser's long-press selection.
    */
   readonly selectionLock?: SelectionLock;
+  /**
+   * Whether this touch's press holds the browser's context menu closed now.
+   * A control whose hold acts uses it (a switch's hold toggles it). The host
+   * then cancels the menu, as for a claimed touch.
+   */
+  holdsContextMenu?(touchId: number): boolean;
   /**
    * Whether the consumer takes touches now (a disabled control does not).
    * The host listens only while something enabled is attached

package/src/gestures/usePressTracker.ts

@@ -132,6 +132,8 @@ export function usePressTracker(
           recognizer,
         ),
       isEnabled: () => optionsRef.current.isEnabled?.() ?? true,
+      holdsContextMenu: id =>
+        optionsRef.current.holdsContextMenu?.(id) === true,
       // The caller's brake, or the host's: a touch that stops a flick
       // presses nothing, as a UIKit control in a decelerating scroll view.
       isBraking: touch => {

package/src/gestures/wheelSegmenter.ts

@@ -3,8 +3,9 @@
 /**
  * @file wheelSegmenter.ts
  * @input A wheel stream's deltas along one axis, with their event times
- * @output Exports WheelSegmenter: splits the stream into gestures and reads
- *   a trackpad's lift (the onset of momentum)
+ * @output Exports WheelSegmenter and isBunched. WheelSegmenter splits the
+ *   stream into gestures and reads a trackpad's lift (the onset of momentum).
+ *   isBunched tells one stall's merge from a frame.
  * @position Read by GestureHost.ts's wheel input: the web reports no
  *   trackpad contact or phase, so both are inferred.
  */
@@ -22,15 +23,32 @@ export interface WheelSegment {
   readonly liftNow: boolean;
   /** This event shrank, so it may be momentum: hold it until known. */
   readonly decaying: boolean;
+  /** This event came so soon after the one before that it is a merge. */
+  readonly bunched: boolean;
 }
 
 /** Momentum arrives at frame rate: a pause this long ends it. */
 const MOMENTUM_GAP_MS = 50;
+/**
+ * A wheel this close to the one before, ms, is one stall's merge. Frames come
+ * further apart at every display rate up to 500 Hz, which is 2 ms.
+ */
+const BUNCHED_MS = 1.5;
 /** Shrinking deltas in a row before the lift is read. */
 const LIFT_RUN = 4;
 /** And how much of its size the run has lost by then. */
 const LIFT_DECAY = 0.8;
 
+/**
+ * Whether a wheel `intervalMs` after the one before is one stall's merge, not
+ * a frame. A stalled page receives the wheels it held back together, within
+ * 1.5 ms of each other. The rule reads no history, so slow wheels never make
+ * a real frame look like a merge.
+ */
+export function isBunched(intervalMs: number): boolean {
+  return intervalMs <= BUNCHED_MS;
+}
+
 /**
  * A trackpad gesture has a finger phase and, after a fling, a momentum phase.
  * In the finger phase, deltas come while the fingers move, with pauses when
@@ -38,7 +56,8 @@ const LIFT_DECAY = 0.8;
  * shrink smoothly. The lift is the start of a run of shrinking deltas that
  * has lost a fifth of its size. In the finger phase, a pause of `idleMs`
  * ends the gesture. In the momentum phase, a reversal, a jump up against the
- * decay, or a pause of 50 ms starts a new gesture. Momentum never pauses,
+ * decay, or a pause of 50 ms starts a new gesture. A bunched wheel is never
+ * a jump. The decay reads it by its last step. Momentum never pauses,
  * reverses or grows.
  */
 export class WheelSegmenter {
@@ -55,6 +74,7 @@ export class WheelSegmenter {
     const size = Math.abs(delta);
     const sign = Math.sign(delta);
     const gap = time - this.last;
+    const bunched = this.count > 0 && isBunched(gap);
     let boundary: WheelBoundary | null = null;
     if (this.count === 0) {
       boundary = this.gesture === 0 ? 'first' : 'idle';
@@ -65,10 +85,16 @@ export class WheelSegmenter {
         boundary = 'reversal';
       } else if (gap >= MOMENTUM_GAP_MS) {
         boundary = 'gap';
-      } else if (size >= 2 && size > this.previous * 1.3 + 0.5) {
+      } else if (!bunched && size >= 2 && size > this.previous * 1.3 + 0.5) {
         boundary = 'jump';
       }
     }
+    // A bunched wheel carries the steps of the frames it merged. The decay
+    // goes on from its last step, so the steps after it read as they are.
+    const steps =
+      boundary == null && bunched && this.previous > 0
+        ? Math.max(1, Math.round(size / this.previous))
+        : 1;
     if (boundary != null) {
       this.gesture += 1;
       this.phase = 'finger';
@@ -78,7 +104,9 @@ export class WheelSegmenter {
     let liftNow = false;
     let decaying = false;
     if (this.phase === 'finger' && this.count >= 3 && size > 0) {
-      decaying = size <= this.previous * 0.995 && size >= this.previous * 0.5;
+      // A bunched wheel is read by its last step, as the decay goes on from it.
+      const step = size / steps;
+      decaying = step <= this.previous * 0.995 && step >= this.previous * 0.5;
       if (decaying) {
         if (this.run === 0) {
           this.runStart = this.previous;
@@ -87,13 +115,13 @@ export class WheelSegmenter {
       } else {
         this.run = 0;
       }
-      if (this.run >= LIFT_RUN && size <= this.runStart * LIFT_DECAY) {
+      if (this.run >= LIFT_RUN && step <= this.runStart * LIFT_DECAY) {
         this.phase = 'momentum';
         liftNow = true;
       }
     }
     this.count += 1;
-    this.previous = size;
+    this.previous = size / steps;
     if (sign !== 0) {
       this.sign = sign;
     }
@@ -104,6 +132,7 @@ export class WheelSegmenter {
       gesture: this.gesture,
       liftNow,
       decaying: decaying && !liftNow,
+      bunched: boundary == null && bunched,
     };
   }