@astryxdesign/core 0.7.8 → 0.7.9-canary.7400c1f

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":"AAiBA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAoC,CAAC;AAEzE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;AAE7D,yFAAyF;AACzF,MAAM,MAAM,cAAc,CAAC,CAAC,IACxB;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;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;CACtC,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,yFAAyF;AACzF,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;IACE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ,GACD;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;IACb;;;OAGG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AACH,+EAA+E;GAC7E;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,CAAC;AAErB,yFAAyF;AACzF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;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,yFAAyF;AACzF,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED,eAAO,MAAM,eAAe,EAAE,cAAc,CAAC,KAAK,CAAmB,CAAC;AAuDtE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GACvB,mBAAmB,CAAC,CAAC,CAAC,CAWxB;AAyKD,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;;;;;GAKG;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;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GACvB,aAAa,CAAC,CAAC,CAAC,CAgBlB"}

package/dist/hooks/menuPressGesture.js

@@ -4,7 +4,7 @@
  * @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
+ *   types, the settle constant, and the finger's handoff distance
  * @position Pure module under `useMenuPress`. It has no DOM and no React, so
  *   a unit test can check each transition without a browser.
  *
@@ -13,8 +13,28 @@
  * - /packages/core/src/hooks/useMenuPress.ts
  */
 
-/** How long the opening press must last before its release may act. */
+import { MENU_PRESS_HANDOFF_PX as UIKIT_MENU_PRESS_HANDOFF_PX } from "./menuPressValues.js";
+
+/**
+ * How long the opening press must last before its release may act, unless a
+ * finger's handoff applies.
+ */
 export 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 const MENU_PRESS_HANDOFF_PX = UIKIT_MENU_PRESS_HANDOFF_PX;
+
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+
+/** @internal The machine's own shape, with the finger's handoff; not public contract. */
+
 export const IDLE_MENU_PRESS = {
   phase: 'idle'
 };
@@ -38,6 +58,23 @@ function highlightEffect(row) {
   };
 }
 
+/** A finger or a pen: UIKit's touch rules apply. */
+function isFinger(pointerType) {
+  return pointerType !== 'mouse';
+}
+function hasPosition(event) {
+  return event.x != null && event.y != null;
+}
+
+/**
+ * Whether a finger has travelled the handoff distance from `from`. The
+ * distance is a straight line, as UIMenu measures it: a diagonal 7 pt each
+ * way does not hand off, 9 pt each way does.
+ */
+function hasPassedHandoff(from, to) {
+  return Math.hypot(to.x - from.x, to.y - from.y) >= MENU_PRESS_HANDOFF_PX;
+}
+
 /**
  * Resolve a release while the highlight is tracking the pointer: over an
  * enabled row it acts, over the menu's chrome it acts on nothing, outside the
@@ -73,10 +110,15 @@ function release(pointerType, event) {
  * - `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.
@@ -84,8 +126,11 @@ function release(pointerType, event) {
  * 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 function menuPressStep(gesture, event) {
+export function menuPressTransition(gesture, event) {
   switch (gesture.phase) {
     case 'idle':
       return stepIdle(gesture, event);
@@ -176,23 +221,67 @@ function stepTriggerPress(gesture, event) {
 function stepOpen(gesture, event) {
   switch (event.type) {
     case 'move':
-      if (!event.isInMenu) {
+      {
+        if (isFinger(gesture.pointerType) && hasPosition(event)) {
+          // UIMenu counts from the first sample after the open, not from the
+          // open point.
+          const from = gesture.handoffFrom;
+          if (from == null) {
+            return {
+              gesture: {
+                ...gesture,
+                handoffFrom: {
+                  x: event.x,
+                  y: event.y
+                }
+              },
+              effect: NONE
+            };
+          }
+          if (!hasPassedHandoff(from, event)) {
+            return {
+              gesture,
+              effect: NONE
+            };
+          }
+          return {
+            gesture: {
+              phase: 'tracking',
+              pointerType: gesture.pointerType,
+              origin: 'trigger',
+              row: event.row
+            },
+            effect: highlightEffect(event.row)
+          };
+        }
+        if (!event.isInMenu) {
+          return {
+            gesture,
+            effect: NONE
+          };
+        }
         return {
-          gesture,
-          effect: NONE
+          gesture: {
+            phase: 'tracking',
+            pointerType: gesture.pointerType,
+            origin: 'trigger',
+            row: event.row
+          },
+          effect: highlightEffect(event.row)
         };
       }
-      return {
-        gesture: {
-          phase: 'tracking',
-          pointerType: gesture.pointerType,
-          origin: 'trigger',
-          row: event.row
-        },
-        effect: highlightEffect(event.row)
-      };
     case 'up':
       {
+        if (isFinger(gesture.pointerType) && hasPosition(event)) {
+          // The finger never travelled the handoff distance, so the row under it
+          // appeared under a press nobody moved. Nothing acts, the menu stays,
+          // and the trigger's click for this press is spent.
+          return idle({
+            type: 'settle',
+            stray: true,
+            dismiss: false
+          });
+        }
         const hasSettled = event.time - gesture.openedAt >= MENU_PRESS_SETTLE_MS;
         if (!hasSettled) {
           // The pointer never entered the menu and the press was short: the
@@ -208,7 +297,7 @@ function stepOpen(gesture, event) {
       }
     case 'cancel':
       // As above: the gesture ends, so its document listeners come off. The
-      // menu stays open — a cancelled pointer did not ask to close it.
+      // menu stays open: a cancelled pointer did not ask to close it.
       return idle({
         type: 'settle',
         stray: false,
@@ -225,21 +314,19 @@ function stepOpen(gesture, event) {
 function stepTracking(gesture, event) {
   switch (event.type) {
     case 'move':
-      {
-        if (event.row === gesture.row) {
-          return {
-            gesture,
-            effect: NONE
-          };
-        }
+      if (event.row === gesture.row) {
         return {
-          gesture: {
-            ...gesture,
-            row: event.row
-          },
-          effect: highlightEffect(event.row)
+          gesture,
+          effect: NONE
         };
       }
+      return {
+        gesture: {
+          ...gesture,
+          row: event.row
+        },
+        effect: highlightEffect(event.row)
+      };
     case 'up':
       return release(gesture.pointerType, event);
     case 'cancel':
@@ -257,4 +344,42 @@ function stepTracking(gesture, event) {
         effect: NONE
       };
   }
+}
+
+// ---------------------------------------------------------------------------
+// The released public shape (`@astryxdesign/core/hooks`). The handoff
+// positions and `handoffFrom` stay internal: a caller of
+// `menuPressStep` keeps the settle rule, as released.
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 function menuPressStep(gesture, event) {
+  // The released machine keeps the settle rule. Positions start the handoff,
+  // so a caller's event reaches the transition without them.
+  const {
+    x: _x,
+    y: _y,
+    ...released
+  } = event;
+  const {
+    gesture: next,
+    effect
+  } = menuPressTransition(gesture, released);
+  return {
+    gesture: publicGesture(next),
+    effect
+  };
+}
+function publicGesture(gesture) {
+  if (gesture.phase !== 'open') {
+    return gesture;
+  }
+  return {
+    phase: 'open',
+    pointerType: gesture.pointerType,
+    openedAt: gesture.openedAt
+  };
 }

package/dist/hooks/menuPressValues.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file menuPressValues.ts
+ * @input None
+ * @output The UIKit value the menu press model reads
+ * @position A copy of one UIKit table entry, motion/uikit gestures.ts
+ *   `UIKIT_MENU_PRESS.handoff`. A menu then bundles this number, not the
+ *   table with its measurement records. The table stays the source and
+ *   documents the measurement. menuPressValues.test.ts fails when the copy
+ *   drifts.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/uikit/gestures.ts
+ */
+/** How far the opening finger travels after the menu opens before it picks. */
+export declare const MENU_PRESS_HANDOFF_PX = 10;
+//# sourceMappingURL=menuPressValues.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"menuPressValues.d.ts","sourceRoot":"","sources":["../../src/hooks/menuPressValues.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,KAAK,CAAC"}

package/dist/hooks/menuPressValues.js

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuPressValues.ts
+ * @input None
+ * @output The UIKit value the menu press model reads
+ * @position A copy of one UIKit table entry, motion/uikit gestures.ts
+ *   `UIKIT_MENU_PRESS.handoff`. A menu then bundles this number, not the
+ *   table with its measurement records. The table stays the source and
+ *   documents the measurement. menuPressValues.test.ts fails when the copy
+ *   drifts.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/uikit/gestures.ts
+ */
+
+/** How far the opening finger travels after the menu opens before it picks. */
+export const MENU_PRESS_HANDOFF_PX = 10;

package/dist/hooks/useClickableContainer.d.ts

@@ -1,16 +1,18 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
+ * @output onClick, onMouseUp and onPointerDown handlers for the container;
+ *   INTERACTIVE_SELECTORS list;
  *   hasInteractiveAncestor and the shared innermostInteractive walk
  * @position Core hook for clickable containers with nested interactive
  *   elements. A click on a nested button or link does not run the card's
- *   action. Each navigation passes the rule in utils/safeUrl.ts first.
+ *   action, and a finger press there shows no press on the card. Each navigation
+ *   passes the rule in utils/safeUrl.ts first.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts (export)
  */
-import { type RefObject, type MouseEvent } from 'react';
+import { type RefObject, type MouseEvent, type PointerEvent } from 'react';
 /**
  * The attribute this hook sets on the container it makes clickable. A click
  * inside a nested marked container belongs to that container (see
@@ -57,6 +59,14 @@ export declare function innermostInteractive(el: Element, rootEl: Element | null
  * belongs to that surface, not the container around its trigger.
  */
 export declare function hasInteractiveAncestor(el: Element, rootEl: Element): boolean;
+/**
+ * The touch half of a container's press rule: a finger press that starts on a nested interactive element
+ * other than the container's own action does not activate the container, so
+ * it ends the press controller's paint on `container`. A mouse or pen press,
+ * and a press on the container's surface or on `ownAction`, are left alone.
+ * Not part of the package's public API.
+ */
+export declare function cancelNestedTouchPress(event: PointerEvent<HTMLElement>, container: HTMLElement | null, ownAction: Element | null): void;
 /**
  * Check if there's a text selection inside the node (don't navigate on text select)
  *
@@ -87,6 +97,14 @@ export interface UseClickableContainerOptions {
 export interface ClickableContainerResult {
     onClick: (event: MouseEvent<HTMLElement>) => void;
     onMouseUp: (event: MouseEvent<HTMLElement>) => void;
+    /**
+     * Spread on the container with `onClick`. A press that starts on a nested
+     * interactive element does not activate the container. On a container that
+     * paints its press with `usePressFeedback`, this drops that touch press.
+     * A mouse `:active` press paint is unchanged. A container without it keeps
+     * its activation rule and shows its pressed state for every press.
+     */
+    onPointerDown: (event: PointerEvent<HTMLElement>) => void;
 }
 /**
  * Hook that makes a container element clickable while preserving
@@ -103,12 +121,16 @@ export interface ClickableContainerResult {
  * @example
  * ```
  * const containerRef = useRef<HTMLDivElement>(null);
- * const { onClick, onMouseUp } = useClickableContainer({
+ * const { onClick, onMouseUp, onPointerDown } = useClickableContainer({
  *   containerRef,
  *   onClick: () => console.log('card clicked'),
  * });
  * return (
- *   <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
+ *   <div
+ *     ref={containerRef}
+ *     onClick={onClick}
+ *     onMouseUp={onMouseUp}
+ *     onPointerDown={onPointerDown}>
  *     <p>Click anywhere on this card</p>
  *     <button onClick={() => alert('button')}>Nested button</button>
  *   </div>

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

@@ -1 +1 @@
-{"version":3,"file":"useClickableContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickableContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAyB,KAAK,SAAS,EAAE,KAAK,UAAU,EAAC,MAAM,OAAO,CAAC;AAI9E;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAmBvB,CAAC;AAIZ;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKrE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,aAAa,GAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAqC,GACzE,OAAO,GAAG,IAAI,CAShB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE5E;AASD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CASvD;AAED,MAAM,WAAW,4BAA4B;IAC3C,yCAAyC;IACzC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,YAAY,EACZ,cAAc,EACd,OAAO,EAAE,WAAW,EACpB,IAAI,EACJ,MAAM,EACN,QAAgB,GACjB,EAAE,4BAA4B,GAAG,wBAAwB,CA+GzD"}
+{"version":3,"file":"useClickableContainer.d.ts","sourceRoot":"","sources":["../../src/hooks/useClickableContainer.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AAKf;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAExE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,QAmBvB,CAAC;AAIZ;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKrE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,aAAa,GAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAqC,GACzE,OAAO,GAAG,IAAI,CAShB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAE5E;AASD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,EAChC,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,SAAS,EAAE,OAAO,GAAG,IAAI,GACxB,IAAI,CAeN;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CASvD;AAED,MAAM,WAAW,4BAA4B;IAC3C,yCAAyC;IACzC,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,mEAAmE;IACnE,cAAc,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC/C,oBAAoB;IACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACnD;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAClD,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IACpD;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,YAAY,EACZ,cAAc,EACd,OAAO,EAAE,WAAW,EACpB,IAAI,EACJ,MAAM,EACN,QAAgB,GACjB,EAAE,4BAA4B,GAAG,wBAAwB,CAgIzD"}