@astryxdesign/core 0.7.8 → 0.7.9-canary.07992bb

package/src/Tooltip/useTooltip.tsx

@@ -21,7 +21,7 @@ import {
   type ReactNode,
   type RefCallback,
 } from 'react';
-import {createTriggerFocusGate} from '../utils/triggerFocus';
+import {createTriggerFocusGate, isFocusOnTrigger} from '../utils/triggerFocus';
 import * as stylex from '@stylexjs/stylex';
 import {
   useLayerInternal,
@@ -185,7 +185,8 @@ export interface TooltipReturn {
 
   /**
    * Ref for the positioning anchor element.
-   * Injects anchorName style for CSS anchor positioning.
+   * While the layer is shown, and until its exit animation ends, the trigger
+   * carries the layer's CSS anchor name.
    */
   positionRef: RefCallback<HTMLElement>;
 
@@ -199,6 +200,7 @@ export interface TooltipReturn {
   /**
    * The CSS anchor name to use for positioning.
    * Use this when you need to set anchorName manually (e.g., display:contents wrapper).
+   * Set it only while the layer is shown or its exit animation runs.
    */
   anchorId: string;
 
@@ -308,6 +310,17 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const triggerRef = useRef<HTMLElement | null>(null);
+  // Whether the tooltip is enabled now, for a show that runs after a render
+  // (a pending hover show) and for the trigger ref callback.
+  const isEnabledRef = useRef(isEnabled);
+  isEnabledRef.current = isEnabled;
+  // Counts the renders in which the tooltip is disabled. A pending show
+  // records it, so a show scheduled before a disable is dropped even when
+  // the tooltip is enabled again before the timer fires.
+  const disabledRendersRef = useRef(0);
+  if (!isEnabled) {
+    disabledRendersRef.current += 1;
+  }
 
   // Clear all timeouts
   const clearTimeouts = useCallback(() => {
@@ -460,22 +473,16 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       return;
     }
     clearTimeouts();
+    const disabledRenders = disabledRendersRef.current;
     showTimeoutRef.current = setTimeout(() => {
-      showLayer();
+      // A show runs only if the tooltip stayed enabled since it was
+      // scheduled: nothing would close a tooltip that opens after a disable.
+      if (disabledRendersRef.current === disabledRenders) {
+        showLayer();
+      }
     }, delay);
   }, [isEnabled, isOpen, clearTimeouts, showLayer, delay]);
 
-  // A show scheduled while the triggers were enabled must not outlive them:
-  // disabling also detaches the leave listener that would have cancelled it,
-  // so the timer would open a tooltip that nothing ever closes. Only the
-  // pending show is dropped; a pending hide still runs.
-  useEffect(() => {
-    if (!isEnabled && showTimeoutRef.current) {
-      clearTimeout(showTimeoutRef.current);
-      showTimeoutRef.current = null;
-    }
-  }, [isEnabled]);
-
   // Schedule hide with delay (suppressed when isOpen is true).
   // A small hover bridge (when hideDelay is 0) lets the pointer travel from the
   // trigger onto the tooltip surface without the tooltip vanishing — required
@@ -537,23 +544,25 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
   // focus that counted still hides on blur (utils/triggerFocus.ts).
   const [focusGate] = useState(createTriggerFocusGate);
 
+  // Whether focus on `target` opens the tooltip. With a `trigger`, its
+  // `focusTrigger` rule applies too. Only `:focus-visible` focus opens it, and
+  // a tap never does: a tapped `<input>` also matches `:focus-visible`.
+  const opensOnFocus = useCallback(
+    (target: HTMLElement, trigger: HTMLElement | null): boolean => {
+      if (trigger != null && !isFocusOnTrigger(target, trigger, focusTrigger)) {
+        return false;
+      }
+      return !isTouchInteraction() && target.matches(':focus-visible');
+    },
+    [focusTrigger, isTouchInteraction],
+  );
+
   const handleFocusIn = useCallback(
     (e: Event) => {
       if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
         return;
       }
-      // A tap focuses the trigger it activates, and `:focus-visible` does not
-      // filter that out on every element: a tapped `<input>` or contenteditable
-      // matches it. Those are exactly the action triggers `auto` just decided
-      // to keep shut, so without this the focus reopens what the tap
-      // suppressed, over the field the user is trying to type into.
-      if (isTouchInteraction()) {
-        return;
-      }
-      // Only show tooltip for keyboard focus (:focus-visible),
-      // not programmatic focus (e.g. dialog auto-focus, touch tap)
-      const target = e.target as HTMLElement;
-      if (!target.matches(':focus-visible')) {
+      if (!opensOnFocus(e.target as HTMLElement, null)) {
         return;
       }
       clearTimeouts();
@@ -563,7 +572,7 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
       focusGate,
       focusTrigger,
       isEnabled,
-      isTouchInteraction,
+      opensOnFocus,
       clearTimeouts,
       showLayer,
     ],
@@ -656,66 +665,155 @@ export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
     ],
   );
 
-  // Interaction ref that handles event listeners only
-  const interactionRef: RefCallback<HTMLElement> = useCallback(
-    (el: HTMLElement | null) => {
-      // Cleanup previous element
-      if (triggerRef.current) {
-        triggerRef.current.removeEventListener('mouseenter', handleMouseEnter);
-        triggerRef.current.removeEventListener('mouseleave', handleMouseLeave);
-        triggerRef.current.removeEventListener('focusin', handleFocusIn);
-        triggerRef.current.removeEventListener('focusout', handleFocusOut);
-        triggerRef.current.removeEventListener('focusout', handleHeldFocusOut);
-        stopPressTrackingRef.current?.();
-        triggerRef.current.removeEventListener(
-          'pointerenter',
-          handlePointerEnter,
-        );
-        triggerRef.current.removeEventListener(
-          'pointerdown',
-          handlePointerDown,
-        );
-      }
+  // The trigger's listeners call the latest handlers through this ref, so the
+  // trigger ref callback keeps one identity.
+  const handlersRef = useRef({
+    handleMouseEnter,
+    handleMouseLeave,
+    handleFocusIn,
+    handleFocusOut,
+    handleHeldFocusOut,
+    handlePointerEnter,
+    handlePointerDown,
+    focusTrigger,
+    isOpen,
+    dropHold,
+    hideNow,
+    showNow,
+    opensOnFocus,
+  });
+  handlersRef.current = {
+    handleMouseEnter,
+    handleMouseLeave,
+    handleFocusIn,
+    handleFocusOut,
+    handleHeldFocusOut,
+    handlePointerEnter,
+    handlePointerDown,
+    focusTrigger,
+    isOpen,
+    dropHold,
+    hideNow,
+    showNow,
+    opensOnFocus,
+  };
 
-      if (el) {
-        // Attach hover listeners. `pointerenter` runs before the synthesized
-        // `mouseenter` a tap produces, which is what lets the hover path know
-        // it is looking at a finger.
-        el.addEventListener('pointerenter', handlePointerEnter);
-        el.addEventListener('mouseenter', handleMouseEnter);
-        el.addEventListener('mouseleave', handleMouseLeave);
-        // Press-to-dismiss on a mouse; tap-to-open on a touch pointer.
-        el.addEventListener('pointerdown', handlePointerDown);
-
-        // Focus listeners unless focus never opens the tooltip; `auto` decides
-        // per event (utils/triggerFocus.ts).
-        if (focusTrigger !== 'never') {
-          el.addEventListener('focusin', handleFocusIn);
-          el.addEventListener('focusout', handleFocusOut);
-        }
+  // Removes the attached trigger's listeners (the trigger ref callback's
+  // cleanup).
+  const detachTriggerRef = useRef<(() => void) | null>(null);
+  // Set when the trigger detached while the tooltip was disabled: the
+  // caller removed the wiring (DropdownMenu's Button while its menu is
+  // open), so the next enabled attach reads the focus that arrived meanwhile.
+  const wasSuppressedRef = useRef(false);
+
+  // The trigger's ref callback owns every trigger listener, and reads the
+  // trigger's state when it attaches and detaches.
+  const interactionRef = useCallback((el: HTMLElement | null) => {
+    // A caller that reports `null` by hand detaches the trigger, as the
+    // returned cleanup does.
+    if (el == null) {
+      detachTriggerRef.current?.();
+      return;
+    }
+    if (el === triggerRef.current) {
+      return;
+    }
+    detachTriggerRef.current?.();
+    const latest = () => handlersRef.current;
+    // `pointerenter` runs before the synthesized `mouseenter` a tap produces,
+    // which is what lets the hover path know it is looking at a finger.
+    const onPointerEnter = (e: PointerEvent) => latest().handlePointerEnter(e);
+    const onMouseEnter = () => latest().handleMouseEnter();
+    const onMouseLeave = (e: Event) => latest().handleMouseLeave(e);
+    // Press-to-dismiss on a mouse; tap-to-open on a touch pointer.
+    const onPointerDown = (e: PointerEvent) => latest().handlePointerDown(e);
+    // Focus counts unless focus never opens the tooltip; `auto` decides per
+    // event (isFocusForTrigger).
+    const onFocusIn = (e: Event) => {
+      if (latest().focusTrigger !== 'never') {
+        latest().handleFocusIn(e);
+      }
+    };
+    const onFocusOut = (e: Event) => {
+      if (latest().focusTrigger !== 'never') {
+        latest().handleFocusOut(e);
       }
+    };
+    // A held tooltip's own focus-leave close, whatever `focusTrigger` is.
+    const onHeldFocusOut = (e: FocusEvent) => latest().handleHeldFocusOut(e);
+    el.addEventListener('pointerenter', onPointerEnter);
+    el.addEventListener('mouseenter', onMouseEnter);
+    el.addEventListener('mouseleave', onMouseLeave);
+    el.addEventListener('pointerdown', onPointerDown);
+    el.addEventListener('focusin', onFocusIn);
+    el.addEventListener('focusout', onFocusOut);
+    el.addEventListener('focusout', onHeldFocusOut);
+    triggerRef.current = el;
+
+    // A trigger that attaches again after its wiring was removed
+    // (DropdownMenu's Button as its menu closes) missed the focus that
+    // arrived meanwhile. Show for it only if it would open the tooltip:
+    // returned keyboard focus does, focus returned after a pointer pick does
+    // not. Any other attach leaves the tooltip as it is, so a tooltip
+    // dismissed with Escape stays closed.
+    const focused = el.ownerDocument.activeElement;
+    const wasSuppressed = wasSuppressedRef.current;
+    if (isEnabledRef.current) {
+      wasSuppressedRef.current = false;
+    }
+    if (
+      wasSuppressed &&
+      isEnabledRef.current &&
+      latest().isOpen === undefined &&
+      latest().focusTrigger !== 'never' &&
+      focused instanceof HTMLElement &&
+      el.contains(focused) &&
+      latest().opensOnFocus(focused, el)
+    ) {
+      latest().showNow();
+    }
 
-      // Its own focus-leave listener: `focusTrigger="never"` attaches none.
-      el?.addEventListener('focusout', handleHeldFocusOut);
-      triggerRef.current = el;
-    },
-    [
-      handleHeldFocusOut,
-      focusTrigger,
-      handleMouseEnter,
-      handleMouseLeave,
-      handleFocusIn,
-      handleFocusOut,
-      handlePointerEnter,
-      handlePointerDown,
-    ],
-  );
+    const detach = () => {
+      if (detachTriggerRef.current === detach) {
+        detachTriggerRef.current = null;
+      }
+      el.removeEventListener('pointerenter', onPointerEnter);
+      el.removeEventListener('mouseenter', onMouseEnter);
+      el.removeEventListener('mouseleave', onMouseLeave);
+      el.removeEventListener('pointerdown', onPointerDown);
+      el.removeEventListener('focusin', onFocusIn);
+      el.removeEventListener('focusout', onFocusOut);
+      el.removeEventListener('focusout', onHeldFocusOut);
+      stopPressTrackingRef.current?.();
+      if (triggerRef.current === el) {
+        triggerRef.current = null;
+      }
+      // A caller removes the wiring as it disables the tooltip. Close an
+      // uncontrolled tooltip then, or the next attach shows a stale tooltip.
+      // A detach while enabled, such as a merged ref that changes identity
+      // on a re-render, keeps a hovered or held tooltip open.
+      if (!isEnabledRef.current && latest().isOpen === undefined) {
+        wasSuppressedRef.current = true;
+        latest().dropHold();
+        latest().hideNow();
+      }
+    };
+    detachTriggerRef.current = detach;
+    return detach;
+  }, []);
 
   // Combined ref - shorthand for calling both positionRef and interactionRef
-  const ref: RefCallback<HTMLElement> = useCallback(
+  const ref = useCallback(
     (el: HTMLElement | null) => {
       layerRef(el);
-      interactionRef(el);
+      const detachInteraction = interactionRef(el);
+      if (el == null) {
+        return;
+      }
+      return () => {
+        detachInteraction?.();
+        layerRef(null);
+      };
     },
     [layerRef, interactionRef],
   );

package/src/TreeList/TreeListItem.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file TreeListItem.tsx
- * @input Uses React, StyleX, theme tokens, TreeListBranches
+ * @input Uses React, StyleX, theme tokens, TreeListBranches, the shared press
+ *   overlays and the compositor press layer
  * @output Exports TreeListItem component (internal, not publicly exported)
  * @position Internal implementation; consumed by TreeList.tsx
  *
@@ -27,8 +28,10 @@ import {
 } from '../theme/tokens.stylex';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
+import {rowPressLayerStyles} from '../privateAttributes/press.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import {
+  cancelNestedTouchPress,
   hasInteractiveAncestor,
   useClickableContainer,
 } from '../hooks/useClickableContainer';
@@ -485,6 +488,28 @@ export function TreeListItem({
     interactiveRef: linkRef,
     disabled: isDisabled || !forwardsToLink,
   });
+
+  // A finger press that starts on a control inside the row does not activate
+  // the row, so the row shows no press for it. The row's own action, its link
+  // or invisible button, activates it. The Chevron does too when the row's
+  // surface toggles, since it runs that same toggle.
+  const actionButtonRef = useRef<HTMLButtonElement>(null);
+  const chevronRef = useRef<HTMLButtonElement>(null);
+  const surfaceToggles = onClick == null && handleClick != null;
+  const pressOnRow = (event: React.PointerEvent<HTMLDivElement>) => {
+    if (isDisabled) {
+      return;
+    }
+    const chevron = chevronRef.current;
+    const ownAction =
+      surfaceToggles &&
+      chevron != null &&
+      event.target instanceof Node &&
+      chevron.contains(event.target)
+        ? chevron
+        : (linkRef.current ?? actionButtonRef.current);
+    cancelNestedTouchPress(event, event.currentTarget, ownAction);
+  };
   const {onMouseUp: openLinkOnMiddleClick} = useClickableContainer({
     containerRef: linkRowRef,
     href,
@@ -566,6 +591,7 @@ export function TreeListItem({
       // focusable element to receive Enter/Space). The row's handleClick ignores
       // clicks originating inside a <button>, so this never double-toggles.
       <button
+        ref={chevronRef}
         type="button"
         aria-expanded={isExpanded}
         aria-label={t('@astryx.treeList.toggleChildren')}
@@ -642,6 +668,7 @@ export function TreeListItem({
         </LinkComponent>
       ) : onClick != null ? (
         <button
+          ref={actionButtonRef}
           type="button"
           onClick={onClick}
           aria-disabled={isDisabled || undefined}
@@ -712,6 +739,10 @@ export function TreeListItem({
                   densityStyles[density],
                   styles.interactive,
                   interactionOverlayStyles.backgroundImage,
+                  // The touch press on a compositor layer (after the
+                  // overlay, whose own touch paint it turns off).
+                  rowPressLayerStyles.cell,
+                  rowPressLayerStyles.cellOnImage,
                   isDisabled && styles.disabled,
                   isSelected && styles.selected,
                   xstyle,
@@ -732,7 +763,10 @@ export function TreeListItem({
           )}
           ref={forwardsToLink ? linkRowRef : undefined}
           onClick={forwardsToLink ? delegateToLink : handleClick}
-          onMouseUp={forwardsToLink ? openLinkOnMiddleClick : undefined}>
+          onMouseUp={forwardsToLink ? openLinkOnMiddleClick : undefined}
+          onPointerDown={
+            forwardsToLink || handleClick != null ? pressOnRow : undefined
+          }>
           <div {...stylex.props(styles.indentedContent)}>{innerContent}</div>
         </div>
       </div>

package/src/gestures/GestureHost.ts

@@ -3,7 +3,8 @@
 /**
  * @file GestureHost.ts
  * @input DOM touch, pointer, click, contextmenu, scroll and focus events of
- *   one document; elements with recognizers and consumers attached
+ *   one document; elements with recognizers and consumers attached; the
+ *   input hold's held layers (Layer/inputHold `holdsTouch`)
  * @output Exports GestureHost (the DOM side of the gesture system) and
  *   getGestureHost (one host per document)
  * @position Browser adapter of packages/core/src/gestures: turns real events
@@ -149,6 +150,7 @@ import {
 import {containsAlongFlatTree} from '../utils/flatTree';
 import {isIosWebKit} from '../utils/touchQueries';
 import {type WheelSegment, WheelSegmenter} from './wheelSegmenter';
+import {holdsTouch} from '../Layer/inputHold';
 import {
   gestureHostStyle,
   type GestureHostStyle,
@@ -2126,9 +2128,12 @@ export class GestureHost {
     const recognizers: GestureRecognizer[] = [];
     let consumer: TouchConsumer | null = null;
     let consumerElement: Element | null = null;
+    // A layer that the input hold holds takes no touch while it presents.
+    // The host asks the hold, so the hold needs nothing from gestures/. A
+    // root-entry component can then use the hold with no gesture code.
     if (
       target instanceof Node &&
-      [...this.touchGates].some(gate => gate(target))
+      (holdsTouch(target) || [...this.touchGates].some(gate => gate(target)))
     ) {
       return {recognizers, consumer, consumerElement};
     }
@@ -2287,17 +2292,20 @@ export class GestureHost {
       };
       this.wheel = gesture;
     }
-    const {dx, dy} = wheelPixels(wheel, this.doc.defaultView);
+    let {dx, dy} = wheelPixels(wheel, this.doc.defaultView);
     const horizontal = Math.abs(dx) > Math.abs(dy);
     // The splitter reads a pan's stream only. A ctrl-wheel pinch has no
     // fingers' phase or momentum to tell apart, and ends 100 ms after its
     // last wheel.
     let seg: WheelSegment | null = null;
     if (kind === 'pan') {
+      // Only a trackpad's wheel can join its glide late; a mouse wheel's
+      // notches keep the splitter's other rules.
       seg = this.segmenter.push(
         time,
         horizontal ? dx : dy,
         horizontal ? WHEEL_FOLLOW_END_MS : WHEEL_FOLLOW_END_V_MS,
+        scrollTypeOf(wheel) === 'continuous',
       );
     } else {
       this.segmenter.end();
@@ -2309,6 +2317,14 @@ export class GestureHost {
         gesture = null;
       }
     }
+    // A late wheel the glide took was the fingers' first when this one grows.
+    if (seg != null && seg.carried !== 0) {
+      if (horizontal) {
+        dx += seg.carried;
+      } else {
+        dy += seg.carried;
+      }
+    }
     if (gesture == null) {
       gesture = this.beginWheel(wheel, kind, dx, dy, time);
       this.wheel = gesture;
@@ -2868,8 +2884,8 @@ export class GestureHost {
 
   /**
    * Hold touches away from every participant while `gate(target)` answers
-   * true (a presentation running in a layer: its content takes no touch
-   * until it settles). Returns the release.
+   * true. Returns the release. The input hold's held layers need no gate,
+   * because the host asks `holdsTouch` for every touch.
    */
   addTouchGate(gate: (target: Node) => boolean): () => void {
     this.touchGates.add(gate);

package/src/gestures/PanGestureRecognizer.ts

@@ -55,7 +55,12 @@ export interface PanGestureRecognizerOptions extends GestureRecognizerOptions<Pa
   minimumNumberOfTouches?: number;
   /** @default Infinity */
   maximumNumberOfTouches?: number;
-  hysteresis?: number;
+  /**
+   * The travel that begins the pan, px. A function gives each press its own
+   * threshold: it reads the press's first touch when that touch lands.
+   * @default UIKit's 10
+   */
+  hysteresis?: number | ((touch: GestureTouch) => number);
   /** Movement that may begin the pan; anything else fails it. @default 'any' */
   direction?: PanDirection;
   /**
@@ -117,6 +122,11 @@ export class PanGestureRecognizer extends GestureRecognizer {
   travelAtBegan: Point = ZERO;
 
   private readonly tracker: VelocityTracker;
+  /**
+   * Read once per press. A finger that lands later keeps the press's
+   * threshold.
+   */
+  private readonly hysteresisFor: ((touch: GestureTouch) => number) | null;
   /** The lift's event time once the pan ended: its release (AST-100 FR2). */
   private releaseTime: number | undefined = undefined;
   /** The centroid where the gesture started, in client px. */
@@ -132,7 +142,10 @@ export class PanGestureRecognizer extends GestureRecognizer {
     this.minimumNumberOfTouches = options.minimumNumberOfTouches ?? 1;
     this.maximumNumberOfTouches =
       options.maximumNumberOfTouches ?? Number.POSITIVE_INFINITY;
-    this.hysteresis = options.hysteresis ?? UIKIT_PAN.hysteresis.value;
+    const {hysteresis} = options;
+    this.hysteresisFor = typeof hysteresis === 'function' ? hysteresis : null;
+    this.hysteresis =
+      typeof hysteresis === 'number' ? hysteresis : UIKIT_PAN.hysteresis.value;
     this.direction = options.direction ?? 'any';
     this.axisRatio = options.axisRatio ?? 1;
     this.lockAxis = options.lockAxis ?? false;
@@ -237,6 +250,10 @@ export class PanGestureRecognizer extends GestureRecognizer {
     event: GestureEventContext,
   ): void {
     if (this.numberOfTouches === touches.length) {
+      const first = touches[0];
+      if (this.hysteresisFor != null && first != null) {
+        this.hysteresis = this.hysteresisFor(first);
+      }
       this.origin = centroid(this.touches.values());
       this.adjust = ZERO;
       this.raw = ZERO;

package/src/gestures/README.md

@@ -118,7 +118,8 @@ The pan reads its numbers the way `UIPanGestureRecognizer` does, as measured
 in the UIKit lab:
 
 - It begins once the centroid has moved `hysteresis` (10 px) along either
-  axis, not as a distance.
+  axis, not as a distance. A function gives each press its own threshold,
+  read from the press's first touch when it lands.
 - `translation()` leaves out the travel the threshold took: a slow drag reads
   zero when the pan begins, and a step that overshoots keeps only the
   overshoot. A dragged surface does not jump. `totalTranslation()` is the
@@ -434,11 +435,15 @@ subscriber cancels it: the host cancels `touchend` and `contextmenu` there
 while a claiming participant is attached, never a `touchstart` or a
 `touchmove`, and the click guard (`../utils/clickGuard.ts`) keeps a
 cancelling `click` while it is armed, and from the menu press model's first
-arm on. A blocking `touchmove` sits on a claiming
+arm on. A layer's input hold (`../Layer/inputHold.ts`) cancels pointer and
+mouse events, clicks, `touchmove` and `touchend` there while a layer is held,
+never a `touchstart`. A blocking `touchmove` sits on a claiming
 element and on a claimed touch's target, on the document while an element a
 claiming recognizer lives in is moving (Touches on moving elements), or on
-the window only while a page hold is held, so a page of pressables blocks
-no scroll.
+the window only while a page hold or a layer's input hold is held, so a page
+of pressables blocks no scroll. The stream records the type of the latest
+pointer event it delivers (`getLastPointerType`); the input hold reads it as
+a layer opens.
 
 ### Holding the page still
 
@@ -525,7 +530,11 @@ it never moves it; when the fingers carry on instead, their moves absorb
 what the pan showed past their travel, or short of it, so it never steps
 back and ends on their travel. Fingers that stop release still, once the end
 time passes. In momentum, a reversal, a delta that grows
-against the decay, or a 50 ms pause starts a new gesture. A finger, mouse or
+against the decay, or a 50 ms pause starts a new gesture; a late, coalesced
+trackpad wheel that continues the glide's deceleration (at or below the next
+step, or near the sum of the next steps its stall spans) belongs to the same
+flick. When the next wheel grows instead, it starts a new gesture with the late
+wheel's travel. A finger, mouse or
 pen that comes down ends it, and a wheel claim keeps the page's text
 selection. A gesture a
 recognizer took is latched to it, as a browser latches a scroller: while it

package/src/gestures/ScreenEdgePanGestureRecognizer.ts

@@ -76,12 +76,17 @@ interface EdgeLayout {
  */
 export interface ScreenEdgePanGestureRecognizerOptions extends Omit<
   PanGestureRecognizerOptions,
-  'direction' | 'allowedPointerTypes' | 'allowedScrollTypes'
+  'direction' | 'allowedPointerTypes' | 'allowedScrollTypes' | 'hysteresis'
 > {
   /** The edges a touch may start from. @default ['leading'] */
   edges?: ReadonlyArray<ScreenEdge>;
   /** Width of the band at each edge, px. */
   edgeRegion?: number;
+  /**
+   * The travel that begins the pan in its edge zone, px. It is one number for
+   * every press, since the zone sets the threshold itself. @default UIKit's 15
+   */
+  hysteresis?: number;
 }
 
 export class ScreenEdgePanGestureRecognizer extends PanGestureRecognizer {