@astryxdesign/core 0.7.8 → 0.7.9-canary.0200dfe

package/dist/gestures/wheelSegmenter.js

@@ -5,6 +5,7 @@
  * @input A wheel stream's deltas along one axis, with their event times
  * @output Exports WheelSegmenter and isBunched. WheelSegmenter splits the
  *   stream into gestures and reads a trackpad's lift (the onset of momentum).
+ *   It keeps a trackpad's late or merged glide wheels in their flick.
  *   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.
@@ -21,6 +22,25 @@ const BUNCHED_MS = 1.5;
 const LIFT_RUN = 4;
 /** And how much of its size the run has lost by then. */
 const LIFT_DECAY = 0.8;
+/** How near a wheel must lie to a sum of the glide's next steps, px. */
+const FIT_PX = 1;
+/** Or as a share of that sum, when the share is larger. */
+const FIT_SHARE = 0.25;
+/** The most glide steps one wheel is read as carrying. */
+const MAX_STEPS = 64;
+/** How near a late or rising wheel must lie to the glide's sum, as a share. */
+const LATE_FIT_SHARE = 0.15;
+/**
+ * How far a wheel may grow past the last unbunched one and still be the
+ * glide, px.
+ */
+const RISE_PX = 0.5;
+/** A stream's frame interval until it shows its own, ms. */
+const FRAME_MS = 16;
+/** The longest frame interval a trackpad reports at: 60 Hz, ms. */
+const SLOWEST_FRAME_MS = 1000 / 60;
+/** The intervals that set a gesture's frame before its window applies. */
+const FIRST_PACES = 3;
 
 /**
  * Whether a wheel `intervalMs` after the one before is one stall's merge, not
@@ -42,6 +62,16 @@ export function isBunched(intervalMs) {
  * 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.
+ *
+ * A stalled page receives a trackpad's glide late, and the engine merges the
+ * wheels it held. In momentum, a trackpad wheel that the glide's decay
+ * explains stays in the flick. It may come after a pause, or rise after more
+ * than a frame. It is at or below the next step, or near the sum of the next
+ * steps its stall spans. After such a wheel, a trackpad wheel that grows
+ * starts a new gesture and takes the late wheel's travel. The decay also
+ * reads a trackpad merge in momentum, by its last step. It reads one in a
+ * shrinking run too, where it explains the merge better than steady steps
+ * do. Other wheels keep the rules above.
  */
 export class WheelSegmenter {
   gesture = 0;
@@ -52,40 +82,108 @@ export class WheelSegmenter {
   count = 0;
   run = 0;
   runStart = 0;
-  push(time, delta, idleMs) {
+  /** The decay's step-to-step ratio, from the last two one-step wheels. */
+  ratio = 1;
+  /** The gesture's last on-pace intervals, ms: their median is its frame. */
+  paces = [];
+  /** The intervals in a row that came slower than the frame allows, ms. */
+  slower = [];
+  /** When the gesture's last wheel within two frames of the one before came. */
+  onPace = -Infinity;
+  /** The gesture's last wheel that was not bunched, px. */
+  paced = 0;
+  /** A wheel joined the glide late: a later one that grows is the fingers'. */
+  resumed = false;
+  /**
+   * The signed travel of the last wheel that joined the glide late, with any
+   * wheel merged with it.
+   */
+  joined = 0;
+
+  /**
+   * Reads one wheel. `continuous` is whether it carries a trackpad's
+   * signature (`scrollTypeOf`). Only those wheels can join a glide late.
+   */
+  push(time, delta, idleMs, continuous = false) {
     const size = Math.abs(delta);
     const sign = Math.sign(delta);
     const gap = time - this.last;
     const bunched = this.count > 0 && isBunched(gap);
+    const frame = this.frameMs();
     let boundary = null;
+    let carriedSteps = null;
     if (this.count === 0) {
       boundary = this.gesture === 0 ? 'first' : 'idle';
     } else if (this.phase === 'finger' && gap >= idleMs) {
       boundary = 'idle';
     } else if (this.phase === 'momentum') {
+      // A late wheel carries the steps of its whole stall, which began at the
+      // last wheel that came on pace.
+      const frames = Math.round((time - this.onPace) / frame);
+      const late = gap >= MOMENTUM_GAP_MS;
+      const rises = !bunched && size >= 2 && size > this.previous * 1.3 + 0.5;
       if (sign !== 0 && this.sign !== 0 && sign !== this.sign) {
         boundary = 'reversal';
-      } else if (gap >= MOMENTUM_GAP_MS) {
-        boundary = 'gap';
-      } else if (!bunched && size >= 2 && size > this.previous * 1.3 + 0.5) {
+      } else if (late || rises) {
+        // A wheel that rises on pace is the fingers'. One that rises after a
+        // skipped frame may carry the frames its stall held.
+        if (continuous && sign === this.sign && (late || gap >= 1.5 * frame)) {
+          carriedSteps = this.glideSteps(size, Math.max(1, frames), LATE_FIT_SHARE);
+        }
+        if (carriedSteps == null) {
+          boundary = late ? 'gap' : 'jump';
+        }
+      } else if (continuous && this.resumed && !bunched && size > FIT_PX && size > this.paced + RISE_PX) {
+        // A glide only falls, so after a late wheel one that grows is the
+        // fingers'. A whole-pixel glide repeats a step as it slows.
         boundary = 'jump';
       }
     }
+    if (carriedSteps == null && boundary == null && bunched && continuous) {
+      if (this.phase === 'momentum') {
+        carriedSteps = this.glideSteps(size, MAX_STEPS);
+      } else if (this.run > 0) {
+        // In a shrinking run, the decay reads a merge only where it explains
+        // the merge better than steady steps do.
+        const decay = this.glideSteps(size, MAX_STEPS);
+        if (decay != null && decay > 1 && Math.abs(size - this.glideSum(decay)) < this.steadyOff(size)) {
+          carriedSteps = decay;
+        }
+      }
+    }
     // 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;
+    const steps = carriedSteps ?? (boundary == null && bunched && this.previous > 0 ? Math.max(1, Math.round(size / this.previous)) : 1);
+    // On the decay, a wheel of several steps ends at the decay's own step.
+    const onDecay = carriedSteps != null && carriedSteps > 1;
+    // A bunched wheel is read by its last step, as the decay goes on from it.
+    const step = onDecay ? this.previous * this.ratio ** steps : size / steps;
     if (boundary != null) {
       this.gesture += 1;
       this.phase = 'finger';
       this.count = 0;
       this.run = 0;
+      this.ratio = 1;
+      this.resumed = false;
+      this.paces = [];
+      this.slower = [];
+    }
+    // The late wheel was the fingers' when the next one grows: the new
+    // gesture takes its travel.
+    const carried = boundary === 'jump' ? this.joined : 0;
+    const joinedLate = boundary == null && carriedSteps != null && !bunched;
+    if (joinedLate) {
+      this.resumed = true;
+    }
+    // A wheel merged with the late one is the same dispatch: it adds to it.
+    this.joined = joinedLate ? delta : bunched && boundary == null && this.joined !== 0 ? this.joined + delta : 0;
+    if (!bunched) {
+      this.paced = size;
     }
     let liftNow = false;
     let decaying = false;
     if (this.phase === 'finger' && this.count >= 3 && size > 0) {
-      // 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;
+      decaying = onDecay ? this.ratio <= 0.995 : step <= this.previous * 0.995 && step >= this.previous * 0.5;
       if (decaying) {
         if (this.run === 0) {
           this.runStart = this.previous;
@@ -99,8 +197,17 @@ export class WheelSegmenter {
         liftNow = true;
       }
     }
+    if (steps === 1 && this.count > 0 && this.previous > 0 && step > 0) {
+      this.ratio = Math.min(1, Math.max(0.5, step / this.previous));
+    }
+    if (!bunched && boundary == null && gap < MOMENTUM_GAP_MS) {
+      this.notePace(gap, frame);
+    }
+    if (boundary != null || !bunched && gap < 2 * frame) {
+      this.onPace = time;
+    }
     this.count += 1;
-    this.previous = size / steps;
+    this.previous = step;
     if (sign !== 0) {
       this.sign = sign;
     }
@@ -111,10 +218,92 @@ export class WheelSegmenter {
       gesture: this.gesture,
       liftNow,
       decaying: decaying && !liftNow,
-      bunched: boundary == null && bunched
+      bunched: boundary == null && bunched,
+      carried
     };
   }
 
+  /**
+   * Keep an interval for the frame. The gesture's first FIRST_PACES set it.
+   * After them, only an interval within half a frame and one and a half
+   * frames counts: a stall's squeezed wheels come faster. FIRST_PACES slower
+   * intervals in a row set the frame again, so a squeezed start cannot hold
+   * it down.
+   */
+  notePace(gap, frame) {
+    const inWindow = gap >= 0.5 * frame && gap <= 1.5 * frame;
+    if (this.paces.length < FIRST_PACES || inWindow) {
+      this.paces = [...this.paces.slice(-7), gap];
+      this.slower = [];
+      return;
+    }
+    this.slower = gap > 1.5 * frame ? [...this.slower, gap] : [];
+    if (this.slower.length >= FIRST_PACES) {
+      this.paces = this.slower;
+      this.slower = [];
+    }
+  }
+
+  /**
+   * The gesture's frame interval: the median of its last on-pace intervals,
+   * or FRAME_MS before it shows one. A trackpad reports at 60 Hz or faster,
+   * so a longer median is a stall's.
+   */
+  frameMs() {
+    if (this.paces.length === 0) {
+      return FRAME_MS;
+    }
+    const sorted = [...this.paces].sort((a, b) => a - b);
+    const middle = sorted.length >> 1;
+    const median = sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+    return Math.min(median, SLOWEST_FRAME_MS);
+  }
+
+  /** The sum of the decay's next `count` steps from `previous`. */
+  glideSum(count) {
+    let next = this.previous * this.ratio;
+    let sum = 0;
+    for (let i = 0; i < count; i++) {
+      sum += next;
+      next *= this.ratio;
+    }
+    return sum;
+  }
+
+  /**
+   * How far a merge of `size` lies from whole steps of the run's steady
+   * size, or of its last step, whichever lies nearer.
+   */
+  steadyOff(size) {
+    return Math.min(...[this.runStart, this.previous].filter(step => step > 0).map(step => Math.abs(size - Math.max(1, Math.round(size / step)) * step)));
+  }
+
+  /**
+   * How many of the decay's next steps a trackpad wheel of `size` carries,
+   * at most `most`. A wheel at or below the next step carries one. A larger
+   * one carries the fewest steps whose sum lies within FIT_PX or `share` of
+   * it. The decay goes on from `previous` at `ratio` a step. Null when
+   * no sum lies that near.
+   */
+  glideSteps(size, most, share = FIT_SHARE) {
+    if (this.previous <= 0 || size <= 0) {
+      return null;
+    }
+    let next = this.previous * this.ratio;
+    if (size <= next + FIT_PX) {
+      return 1;
+    }
+    let sum = next;
+    for (let count = 2; count <= Math.min(most, MAX_STEPS); count++) {
+      next *= this.ratio;
+      sum += next;
+      if (Math.abs(size - sum) <= Math.max(FIT_PX, sum * share)) {
+        return count;
+      }
+    }
+    return null;
+  }
+
   /** The gesture ended on its own (its timer): the next event starts one. */
   end() {
     this.count = 0;

package/dist/hooks/StackItemScrollRegion.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file StackItemScrollRegion.tsx
+ * @input A scrollable `div` or `span` StackItem's props, ref and children
+ * @output StackItemScrollRegion (internal; not re-exported from
+ *   hooks/index.ts), which renders that element and names it as a group
+ *   while its content overflows
+ * @position Internal client island for StackItem, which itself stays a
+ *   static render. Only a scrollable `div` or `span` item measures its
+ *   overflow, on the client; another element keeps its own role.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Stack/StackItem.tsx
+ * - /packages/core/src/serverSafeComponents.test.ts
+ */
+import { type AriaRole, type ReactNode, type Ref } from 'react';
+export interface StackItemScrollRegionProps {
+    as: 'div' | 'span';
+    ref?: Ref<HTMLElement>;
+    elementProps: {
+        role?: AriaRole;
+        'aria-label'?: string;
+        [prop: string]: unknown;
+    };
+    children?: ReactNode;
+}
+export declare function StackItemScrollRegion({ as: element, ref, elementProps, children, }: StackItemScrollRegionProps): import("react").DetailedReactHTMLElement<{
+    ref: import("react").RefCallback<HTMLElement>;
+    role: AriaRole | undefined;
+    'aria-label': string | undefined;
+}, HTMLElement>;
+//# sourceMappingURL=StackItemScrollRegion.d.ts.map

package/dist/hooks/StackItemScrollRegion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StackItemScrollRegion.d.ts","sourceRoot":"","sources":["../../src/hooks/StackItemScrollRegion.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAgB,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,KAAK,GAAG,EAAC,MAAM,OAAO,CAAC;AAI7E,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,KAAK,GAAG,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IACvB,YAAY,EAAE;QACZ,IAAI,CAAC,EAAE,QAAQ,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,qBAAqB,CAAC,EACpC,EAAE,EAAE,OAAO,EACX,GAAG,EACH,YAAY,EACZ,QAAQ,GACT,EAAE,0BAA0B;;;;gBAiB5B"}

package/dist/hooks/StackItemScrollRegion.js

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file StackItemScrollRegion.tsx
+ * @input A scrollable `div` or `span` StackItem's props, ref and children
+ * @output StackItemScrollRegion (internal; not re-exported from
+ *   hooks/index.ts), which renders that element and names it as a group
+ *   while its content overflows
+ * @position Internal client island for StackItem, which itself stays a
+ *   static render. Only a scrollable `div` or `span` item measures its
+ *   overflow, on the client; another element keeps its own role.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/Stack/StackItem.tsx
+ * - /packages/core/src/serverSafeComponents.test.ts
+ */
+import { createElement } from 'react';
+import { useMergedRefs } from "./useMergedRefs.js";
+import { useScrollRegionProps } from "./useScrollRegionProps.js";
+export function StackItemScrollRegion({
+  as: element,
+  ref,
+  elementProps,
+  children
+}) {
+  const region = useScrollRegionProps({
+    isScrollable: true,
+    role: elementProps.role,
+    label: elementProps['aria-label']
+  });
+  const mergedRef = useMergedRefs(ref, region.ref);
+  return /*#__PURE__*/createElement(element, {
+    ...elementProps,
+    ref: mergedRef,
+    role: region.role,
+    'aria-label': region['aria-label']
+  }, children);
+}

package/dist/hooks/computeOverflow.d.ts

@@ -38,6 +38,8 @@ export interface ComputeOverflowResult {
     /** Number of rows the visible items occupy (always 1 for the single-line path). */
     rows: number;
 }
+/** Count how many rows a set of items occupies when wrapped at availableWidth. */
+export declare function countRows(orderedWidths: number[], gap: number, availableWidth: number): number;
 /**
  * Pure overflow computation. Given plain measurements and the configured
  * limits, return how many items should be visible and how many rows they

package/dist/hooks/computeOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computeOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/computeOverflow.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,YAAY,EAAE,OAAO,GAAG,KAAK,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;CACd;AA0LD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,oBAAoB,GAC1B,qBAAqB,CAqDvB"}
+{"version":3,"file":"computeOverflow.d.ts","sourceRoot":"","sources":["../../src/hooks/computeOverflow.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,YAAY,EAAE,OAAO,GAAG,KAAK,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;CACd;AAwHD,kFAAkF;AAClF,wBAAgB,SAAS,CACvB,aAAa,EAAE,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,GACrB,MAAM,CAkBR;AA2CD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,oBAAoB,GAC1B,qBAAqB,CAqDvB"}

package/dist/hooks/computeOverflow.js

@@ -107,7 +107,7 @@ function packRows(orderedWidths, gap, availableWidth, indicatorReserve, maxRows)
 }
 
 /** Count how many rows a set of items occupies when wrapped at availableWidth. */
-function countRows(orderedWidths, gap, availableWidth) {
+export function countRows(orderedWidths, gap, availableWidth) {
   if (orderedWidths.length === 0) {
     return 0;
   }

package/dist/hooks/menuPressGesture.d.ts

@@ -1,19 +1,16 @@
 /**
- * @file menuPressGesture.ts
- * @input A menu press gesture and one pointer event, both as plain data
- * @output The pure `menuPressStep` state machine, its state, event and effect
- *   types, and the settle constant
- * @position Pure module under `useMenuPress`. It has no DOM and no React, so
- *   a unit test can check each transition without a browser.
- *
- * SYNC: When modified, update:
- * - /packages/core/src/hooks/menuPressGesture.test.ts
- * - /packages/core/src/hooks/useMenuPress.ts
+ * How long the opening press must last before its release may act, unless a
+ * finger's handoff applies.
  */
-/** How long the opening press must last before its release may act. */
 export declare const MENU_PRESS_SETTLE_MS = 300;
+/**
+ * How far a finger that opened the menu travels, from the first sample the
+ * menu sees, before it starts picking (UIMenu's scrub handoff).
+ */
+export declare const MENU_PRESS_HANDOFF_PX: number;
 export type MenuPressPointerType = 'mouse' | 'touch' | 'pen';
-export type MenuPressGesture<T> = {
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+export type MenuPressState<T> = {
     phase: 'idle';
 } | {
     phase: 'triggerPress';
@@ -23,6 +20,15 @@ export type MenuPressGesture<T> = {
     phase: 'open';
     pointerType: MenuPressPointerType;
     openedAt: number;
+    /**
+     * A finger's handoff: the first position the menu saw after it opened,
+     * which the scrub distance is counted from. Unset until that sample.
+     * @internal Not public contract.
+     */
+    handoffFrom?: {
+        x: number;
+        y: number;
+    };
 } | {
     phase: 'tracking';
     pointerType: MenuPressPointerType;
@@ -31,7 +37,8 @@ export type MenuPressGesture<T> = {
     /** The enabled row currently under the pointer, if any. */
     row: T | null;
 };
-export type MenuPressEvent<T> = {
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+export type MenuPressInput<T> = {
     type: 'down';
     target: 'trigger' | 'menu';
     pointerType: MenuPressPointerType;
@@ -48,18 +55,33 @@ export type MenuPressEvent<T> = {
     row: T | null;
     isInMenu: boolean;
     time: number;
+    /**
+     * Viewport position, for a finger's handoff distance.
+     * @internal Not public contract.
+     */
+    x?: number;
+    /** @internal See `x`. */
+    y?: number;
 } | {
     type: 'up';
     row: T | null;
     isInMenu: boolean;
     isOnTrigger: boolean;
     time: number;
+    /**
+     * Viewport position, for a finger's handoff distance.
+     * @internal Not public contract.
+     */
+    x?: number;
+    /** @internal See `x`. */
+    y?: number;
 }
 /** The browser took the gesture: pointercancel, a second pointer, a scroll. */
  | {
     type: 'cancel';
 };
-export type MenuPressEffect<T> = {
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+export type MenuPressOutcome<T> = {
     type: 'none';
 }
 /** A mouse pressed the trigger: open the menu now, under the held pointer. */
@@ -77,18 +99,19 @@ export type MenuPressEffect<T> = {
 /**
  * The gesture ended without a row acting. `stray` says whether the browser
  * will still report a `click` for this gesture that must not act; `dismiss`
- * says the menu should close (a mouse released outside it).
+ * says the menu should close: a mouse released outside it.
  */
  | {
     type: 'settle';
     stray: boolean;
     dismiss: boolean;
 };
-export interface MenuPressStep<T> {
-    gesture: MenuPressGesture<T>;
-    effect: MenuPressEffect<T>;
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+export interface MenuPressTransition<T> {
+    gesture: MenuPressState<T>;
+    effect: MenuPressOutcome<T>;
 }
-export declare const IDLE_MENU_PRESS: MenuPressGesture<never>;
+export declare const IDLE_MENU_PRESS: MenuPressState<never>;
 /**
  * Advance the gesture by one event. Pure: same inputs, same output.
  *
@@ -97,10 +120,15 @@ export declare const IDLE_MENU_PRESS: MenuPressGesture<never>;
  * - `idle`: no gesture is live.
  * - `triggerPress`: a finger rests on the trigger, and the menu is not open
  *   yet. A mouse press on the trigger skips this state and opens at once.
- * - `open`: the menu opened under a held pointer, and the pointer has not
- *   entered it yet.
+ * - `open`: the menu opened under a held pointer, and the pointer does not
+ *   pick yet.
  * - `tracking`: the pointer is held, and the highlight follows it.
  *
+ * A finger or a pen that opened the menu picks only after it travels
+ * `MENU_PRESS_HANDOFF_PX` from the first position the menu sees. UIMenu
+ * hands off the same way. Until then nothing lights, and its lift acts on
+ * nothing. A host that reports no positions keeps the settle rule.
+ *
  * The settle rule: the release of the opening gesture acts only after the
  * pointer entered the menu or the press lasted `MENU_PRESS_SETTLE_MS`. Else a
  * menu that opens under the pointer would pick a row that nobody chose.
@@ -108,6 +136,90 @@ export declare const IDLE_MENU_PRESS: MenuPressGesture<never>;
  * Rows are opaque (`T`). The hook feeds in the enabled row under the
  * pointer, or `null` over a divider, a heading, a disabled row, or outside
  * the menu.
+ *
+ * @internal The machine's own shape, with the finger's handoff; not public
+ * contract.
+ */
+export declare function menuPressTransition<T>(gesture: MenuPressState<T>, event: MenuPressInput<T>): MenuPressTransition<T>;
+export type MenuPressGesture<T> = {
+    phase: 'idle';
+} | {
+    phase: 'triggerPress';
+    pointerType: MenuPressPointerType;
+    startedAt: number;
+} | {
+    phase: 'open';
+    pointerType: MenuPressPointerType;
+    openedAt: number;
+} | {
+    phase: 'tracking';
+    pointerType: MenuPressPointerType;
+    /** Where the press began. */
+    origin: 'trigger' | 'menu';
+    /** The enabled row currently under the pointer, if any. */
+    row: T | null;
+};
+export type MenuPressEvent<T> = {
+    type: 'down';
+    target: 'trigger' | 'menu';
+    pointerType: MenuPressPointerType;
+    /** The enabled row under the press when it lands inside the menu. */
+    row: T | null;
+    time: number;
+}
+/** The menu opened while the trigger press is still held. */
+ | {
+    type: 'opened';
+    time: number;
+} | {
+    type: 'move';
+    row: T | null;
+    isInMenu: boolean;
+    time: number;
+} | {
+    type: 'up';
+    row: T | null;
+    isInMenu: boolean;
+    isOnTrigger: boolean;
+    time: number;
+}
+/** The browser took the gesture: pointercancel, a second pointer, a scroll. */
+ | {
+    type: 'cancel';
+};
+export type MenuPressEffect<T> = {
+    type: 'none';
+}
+/** A mouse pressed the trigger: open the menu now, under the held pointer. */
+ | {
+    type: 'open';
+} | {
+    type: 'highlight';
+    row: T;
+} | {
+    type: 'clear';
+} | {
+    type: 'act';
+    row: T;
+}
+/**
+ * The gesture ends without a row acting. Its `stray` flag is true when the
+ * browser still sends a `click` for this gesture. That click must not act.
+ * Its `dismiss` flag is true when the menu must close (a mouse released
+ * outside it).
+ */
+ | {
+    type: 'settle';
+    stray: boolean;
+    dismiss: boolean;
+};
+export interface MenuPressStep<T> {
+    gesture: MenuPressGesture<T>;
+    effect: MenuPressEffect<T>;
+}
+/**
+ * The menu press machine, as released: one step from a gesture and an event
+ * to the next gesture and the effect to apply. Pure.
  */
 export declare function menuPressStep<T>(gesture: MenuPressGesture<T>, event: MenuPressEvent<T>): MenuPressStep<T>;
 //# sourceMappingURL=menuPressGesture.d.ts.map

package/dist/hooks/menuPressGesture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menuPressGesture.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressGesture.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAE7D,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GACf;IACE,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,oBAAoB,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IACE,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,oBAAoB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IACE,KAAK,EAAE,UAAU,CAAC;IAClB,WAAW,EAAE,oBAAoB,CAAC;IAClC,6BAA6B;IAC7B,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;CACf,CAAC;AAEN,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;IACE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,MAAM,CAAC;IAC3B,WAAW,EAAE,oBAAoB,CAAC;IAClC,qEAAqE;IACrE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AACH,6DAA6D;GAC3D;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAC9B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAC9D;IACE,IAAI,EAAE,IAAI,CAAC;IACX,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AACH,+EAA+E;GAC7E;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,CAAC;AAErB,MAAM,MAAM,eAAe,CAAC,CAAC,IACzB;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC;AAChB,8EAA8E;GAC5E;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GACd;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,CAAC,CAAA;CAAC,GAC3B;IAAC,IAAI,EAAE,OAAO,CAAA;CAAC,GACf;IAAC,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,CAAC,CAAA;CAAC;AACvB;;;;GAIG;GACD;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAC,CAAC;AAEvD,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;CAC5B;AAED,eAAO,MAAM,eAAe,EAAE,gBAAgB,CAAC,KAAK,CAAmB,CAAC;AA+BxE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GACvB,aAAa,CAAC,CAAC,CAAC,CAWlB"}
+{"version":3,"file":"menuPressGesture.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressGesture.ts"],"names":[],"mappings":"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"}