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

package/src/hooks/menuPressGesture.ts

@@ -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,12 +13,24 @@
  * - /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';
+
+/**
+ * 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: number = UIKIT_MENU_PRESS_HANDOFF_PX;
+
 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';
@@ -29,6 +41,12 @@ 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';
@@ -39,7 +57,8 @@ export type MenuPressGesture<T> =
       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';
@@ -50,18 +69,38 @@ export type MenuPressEvent<T> =
     }
   /** The menu opened while the trigger press is still held. */
   | {type: 'opened'; time: number}
-  | {type: 'move'; row: T | null; isInMenu: boolean; time: number}
+  | {
+      type: 'move';
+      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. */
   | {type: 'open'}
@@ -71,27 +110,52 @@ 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 const IDLE_MENU_PRESS: MenuPressGesture<never> = {phase: 'idle'};
+export const IDLE_MENU_PRESS: MenuPressState<never> = {phase: 'idle'};
 
-const NONE: MenuPressEffect<never> = {type: 'none'};
+const NONE: MenuPressOutcome<never> = {type: 'none'};
 
-function idle<T>(effect: MenuPressEffect<T>): MenuPressStep<T> {
+function idle<T>(effect: MenuPressOutcome<T>): MenuPressTransition<T> {
   return {gesture: {phase: 'idle'}, effect};
 }
 
-function highlightEffect<T>(row: T | null): MenuPressEffect<T> {
+function highlightEffect<T>(row: T | null): MenuPressOutcome<T> {
   return row == null ? {type: 'clear'} : {type: 'highlight', row};
 }
 
+/** A finger or a pen: UIKit's touch rules apply. */
+function isFinger(pointerType: MenuPressPointerType): boolean {
+  return pointerType !== 'mouse';
+}
+
+function hasPosition(event: {
+  x?: number;
+  y?: number;
+}): event is {x: number; y: number} {
+  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: {x: number; y: number},
+  to: {x: number; y: number},
+): boolean {
+  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
@@ -100,8 +164,8 @@ function highlightEffect<T>(row: T | null): MenuPressEffect<T> {
  */
 function release<T>(
   pointerType: MenuPressPointerType,
-  event: Extract<MenuPressEvent<T>, {type: 'up'}>,
-): MenuPressStep<T> {
+  event: Extract<MenuPressInput<T>, {type: 'up'}>,
+): MenuPressTransition<T> {
   if (event.row != null) {
     return idle({type: 'act', row: event.row});
   }
@@ -119,10 +183,15 @@ function release<T>(
  * - `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.
@@ -130,11 +199,14 @@ function release<T>(
  * 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<T>(
-  gesture: MenuPressGesture<T>,
-  event: MenuPressEvent<T>,
-): MenuPressStep<T> {
+export function menuPressTransition<T>(
+  gesture: MenuPressState<T>,
+  event: MenuPressInput<T>,
+): MenuPressTransition<T> {
   switch (gesture.phase) {
     case 'idle':
       return stepIdle(gesture, event);
@@ -148,9 +220,9 @@ export function menuPressStep<T>(
 }
 
 function stepIdle<T>(
-  gesture: Extract<MenuPressGesture<T>, {phase: 'idle'}>,
-  event: MenuPressEvent<T>,
-): MenuPressStep<T> {
+  gesture: Extract<MenuPressState<T>, {phase: 'idle'}>,
+  event: MenuPressInput<T>,
+): MenuPressTransition<T> {
   if (event.type !== 'down') {
     return {gesture, effect: NONE};
   }
@@ -186,9 +258,9 @@ function stepIdle<T>(
 }
 
 function stepTriggerPress<T>(
-  gesture: Extract<MenuPressGesture<T>, {phase: 'triggerPress'}>,
-  event: MenuPressEvent<T>,
-): MenuPressStep<T> {
+  gesture: Extract<MenuPressState<T>, {phase: 'triggerPress'}>,
+  event: MenuPressInput<T>,
+): MenuPressTransition<T> {
   switch (event.type) {
     case 'opened':
       return {
@@ -216,11 +288,34 @@ function stepTriggerPress<T>(
 }
 
 function stepOpen<T>(
-  gesture: Extract<MenuPressGesture<T>, {phase: 'open'}>,
-  event: MenuPressEvent<T>,
-): MenuPressStep<T> {
+  gesture: Extract<MenuPressState<T>, {phase: 'open'}>,
+  event: MenuPressInput<T>,
+): MenuPressTransition<T> {
   switch (event.type) {
-    case 'move':
+    case 'move': {
+      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};
       }
@@ -233,7 +328,14 @@ function stepOpen<T>(
         },
         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
@@ -245,7 +347,7 @@ function stepOpen<T>(
     }
     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, dismiss: false});
     case 'down':
     case 'opened':
@@ -254,11 +356,11 @@ function stepOpen<T>(
 }
 
 function stepTracking<T>(
-  gesture: Extract<MenuPressGesture<T>, {phase: 'tracking'}>,
-  event: MenuPressEvent<T>,
-): MenuPressStep<T> {
+  gesture: Extract<MenuPressState<T>, {phase: 'tracking'}>,
+  event: MenuPressInput<T>,
+): MenuPressTransition<T> {
   switch (event.type) {
-    case 'move': {
+    case 'move':
       if (event.row === gesture.row) {
         return {gesture, effect: NONE};
       }
@@ -266,7 +368,6 @@ function stepTracking<T>(
         gesture: {...gesture, row: event.row},
         effect: highlightEffect(event.row),
       };
-    }
     case 'up':
       return release(gesture.pointerType, event);
     case 'cancel':
@@ -278,3 +379,108 @@ function stepTracking<T>(
       return {gesture, 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.
+// ---------------------------------------------------------------------------
+
+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 function menuPressStep<T>(
+  gesture: MenuPressGesture<T>,
+  event: MenuPressEvent<T>,
+): MenuPressStep<T> {
+  // 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 as MenuPressEvent<T> & {x?: number; y?: number};
+  const {gesture: next, effect} = menuPressTransition(
+    gesture,
+    released as MenuPressEvent<T>,
+  );
+  return {
+    gesture: publicGesture(next),
+    effect,
+  };
+}
+
+function publicGesture<T>(gesture: MenuPressState<T>): MenuPressGesture<T> {
+  if (gesture.phase !== 'open') {
+    return gesture;
+  }
+  return {
+    phase: 'open',
+    pointerType: gesture.pointerType,
+    openedAt: gesture.openedAt,
+  };
+}

package/src/hooks/menuPressValues.ts

@@ -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/src/hooks/useClickableContainer.doc.mjs

@@ -61,12 +61,17 @@ export const docs = {
       type: '(event: MouseEvent<HTMLElement>) => void',
       description: 'Mouse up handler to attach to the container (handles middle-click navigation for href).',
     },
+    {
+      name: 'onPointerDown',
+      type: '(event: PointerEvent<HTMLElement>) => void',
+      description: 'Pointer down handler to attach to the container. On a container that paints its press with usePressFeedback, it drops a touch press that starts on a nested interactive element, which does not activate the container. A mouse :active press paint is unchanged. Without it, the container keeps its click rules and its pressed state for every press.',
+    },
   ],
   usage: {
     description:
       'Makes a container element clickable while preserving nested interactive element behavior. Solves the "nested interactive elements" problem: when a card is clickable but contains buttons/links, clicking those should NOT trigger the card\'s action. Detects interactive ancestors between the click target and the container, and ignores text selections. Supports href navigation (including middle-click and Ctrl/Cmd+click for new tabs).',
     bestPractices: [
-      { guidance: true, description: 'Attach both onClick and onMouseUp to the container element for full click handling including middle-click.' },
+      { guidance: true, description: 'Attach onClick, onMouseUp and onPointerDown to the container element: full click handling including middle-click, and no touch pressed state for a press on a nested control.' },
       { guidance: true, description: 'Use inside ClickableCard or SelectableCard for the standard card interaction pattern.' },
       { guidance: false, description: 'Use when the entire container is a single interactive element; just use a <button> or <a> directly.' },
     ],
@@ -93,12 +98,13 @@ export const docsDense = {
   returnDescriptions: {
     onClick: 'click handler for container element.',
     onMouseUp: 'mouse up handler for container (handles middle-click navigation for href).',
+    onPointerDown: 'pointer down handler for container: drops usePressFeedback touch press starting on nested interactive element; mouse :active paint unchanged.',
   },
   usage: {
     description:
       'Makes container element clickable while preserving nested interactive element behavior. Solves "nested interactive elements" problem: when card is clickable but contains buttons/links, clicking those must NOT trigger card\'s action. Detects interactive ancestors between click target + container, ignores text selections. Supports href navigation (incl. middle-click + Ctrl/Cmd+click for new tabs).',
     bestPractices: [
-      { guidance: true, description: 'Attach both onClick + onMouseUp to container element for full click handling incl. middle-click.' },
+      { guidance: true, description: 'Attach onClick + onMouseUp + onPointerDown to container element: full click handling incl. middle-click, no touch pressed state for press on nested control.' },
       { guidance: true, description: 'Use inside ClickableCard / SelectableCard for standard card interaction pattern.' },
       { guidance: false, description: 'Use when entire container is single interactive element; just use <button> / <a> directly.' },
     ],

package/src/hooks/useClickableContainer.ts

@@ -5,19 +5,28 @@
 /**
  * @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 {useCallback, useEffect, type RefObject, type MouseEvent} from 'react';
+import {
+  useCallback,
+  useEffect,
+  type RefObject,
+  type MouseEvent,
+  type PointerEvent,
+} from 'react';
 import {isLayerSurface} from '../Layer/layerSurfacePress';
 import {isSafeUrl} from '../utils/safeUrl';
+import {cancelPress} from '../utils/pressFeedback';
 
 /**
  * The attribute this hook sets on the container it makes clickable. A click
@@ -118,6 +127,34 @@ function belongsToSomethingElse(element: Element): boolean {
   return matchesInteractiveSelectors(element) || isLayerSurface(element);
 }
 
+/**
+ * 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 function cancelNestedTouchPress(
+  event: PointerEvent<HTMLElement>,
+  container: HTMLElement | null,
+  ownAction: Element | null,
+): void {
+  const target = event.target;
+  if (
+    event.pointerType !== 'touch' ||
+    container == null ||
+    !(target instanceof Element) ||
+    target === event.currentTarget ||
+    !hasInteractiveAncestor(target, container) ||
+    // The container's own action, such as the control it delegates to: a
+    // press on it activates the container.
+    ownAction?.contains(target) === true
+  ) {
+    return;
+  }
+  cancelPress(container);
+}
+
 /**
  * Check if there's a text selection inside the node (don't navigate on text select)
  *
@@ -159,6 +196,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;
 }
 
 /**
@@ -176,12 +221,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>
@@ -305,5 +354,22 @@ export function useClickableContainer({
     [containerRef, href, disabled],
   );
 
-  return {onClick, onMouseUp};
+  // The press-state counterpart of onClick's rule, for touch: a finger press
+  // that would not activate the container shows no press on it. A mouse or
+  // pen press keeps its `:active` paint.
+  const onPointerDown = useCallback(
+    (event: PointerEvent<HTMLElement>) => {
+      if (disabled) {
+        return;
+      }
+      cancelNestedTouchPress(
+        event,
+        containerRef.current,
+        interactiveRef?.current ?? null,
+      );
+    },
+    [containerRef, interactiveRef, disabled],
+  );
+
+  return {onClick, onMouseUp, onPointerDown};
 }