@astryxdesign/core 0.7.8-canary.fbb81c6 → 0.7.8

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, the settle constant, and the finger's handoff distance
+ *   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.
  *
@@ -13,24 +13,12 @@
  * - /packages/core/src/hooks/useMenuPress.ts
  */
 
-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.
- */
+/** How long the opening press must last before its release may act. */
 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';
 
-/** @internal The machine's own shape, with the finger's handoff; not public contract. */
-export type MenuPressState<T> =
+export type MenuPressGesture<T> =
   | {phase: 'idle'}
   | {
       phase: 'triggerPress';
@@ -41,12 +29,6 @@ export type MenuPressState<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';
@@ -57,8 +39,7 @@ export type MenuPressState<T> =
       row: T | null;
     };
 
-/** @internal The machine's own shape, with the finger's handoff; not public contract. */
-export type MenuPressInput<T> =
+export type MenuPressEvent<T> =
   | {
       type: 'down';
       target: 'trigger' | 'menu';
@@ -69,38 +50,18 @@ export type MenuPressInput<T> =
     }
   /** The menu opened while the trigger press is still held. */
   | {type: 'opened'; 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: 'move'; row: T | null; isInMenu: boolean; time: 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'};
 
-/** @internal The machine's own shape, with the finger's handoff; not public contract. */
-export type MenuPressOutcome<T> =
+export type MenuPressEffect<T> =
   | {type: 'none'}
   /** A mouse pressed the trigger: open the menu now, under the held pointer. */
   | {type: 'open'}
@@ -110,52 +71,27 @@ export type MenuPressOutcome<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};
 
-/** @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 interface MenuPressStep<T> {
+  gesture: MenuPressGesture<T>;
+  effect: MenuPressEffect<T>;
 }
 
-export const IDLE_MENU_PRESS: MenuPressState<never> = {phase: 'idle'};
+export const IDLE_MENU_PRESS: MenuPressGesture<never> = {phase: 'idle'};
 
-const NONE: MenuPressOutcome<never> = {type: 'none'};
+const NONE: MenuPressEffect<never> = {type: 'none'};
 
-function idle<T>(effect: MenuPressOutcome<T>): MenuPressTransition<T> {
+function idle<T>(effect: MenuPressEffect<T>): MenuPressStep<T> {
   return {gesture: {phase: 'idle'}, effect};
 }
 
-function highlightEffect<T>(row: T | null): MenuPressOutcome<T> {
+function highlightEffect<T>(row: T | null): MenuPressEffect<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
@@ -164,8 +100,8 @@ function hasPassedHandoff(
  */
 function release<T>(
   pointerType: MenuPressPointerType,
-  event: Extract<MenuPressInput<T>, {type: 'up'}>,
-): MenuPressTransition<T> {
+  event: Extract<MenuPressEvent<T>, {type: 'up'}>,
+): MenuPressStep<T> {
   if (event.row != null) {
     return idle({type: 'act', row: event.row});
   }
@@ -183,15 +119,10 @@ 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 does not
- *   pick yet.
+ * - `open`: the menu opened under a held pointer, and the pointer has not
+ *   entered it 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.
@@ -199,14 +130,11 @@ 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 menuPressTransition<T>(
-  gesture: MenuPressState<T>,
-  event: MenuPressInput<T>,
-): MenuPressTransition<T> {
+export function menuPressStep<T>(
+  gesture: MenuPressGesture<T>,
+  event: MenuPressEvent<T>,
+): MenuPressStep<T> {
   switch (gesture.phase) {
     case 'idle':
       return stepIdle(gesture, event);
@@ -220,9 +148,9 @@ export function menuPressTransition<T>(
 }
 
 function stepIdle<T>(
-  gesture: Extract<MenuPressState<T>, {phase: 'idle'}>,
-  event: MenuPressInput<T>,
-): MenuPressTransition<T> {
+  gesture: Extract<MenuPressGesture<T>, {phase: 'idle'}>,
+  event: MenuPressEvent<T>,
+): MenuPressStep<T> {
   if (event.type !== 'down') {
     return {gesture, effect: NONE};
   }
@@ -258,9 +186,9 @@ function stepIdle<T>(
 }
 
 function stepTriggerPress<T>(
-  gesture: Extract<MenuPressState<T>, {phase: 'triggerPress'}>,
-  event: MenuPressInput<T>,
-): MenuPressTransition<T> {
+  gesture: Extract<MenuPressGesture<T>, {phase: 'triggerPress'}>,
+  event: MenuPressEvent<T>,
+): MenuPressStep<T> {
   switch (event.type) {
     case 'opened':
       return {
@@ -288,34 +216,11 @@ function stepTriggerPress<T>(
 }
 
 function stepOpen<T>(
-  gesture: Extract<MenuPressState<T>, {phase: 'open'}>,
-  event: MenuPressInput<T>,
-): MenuPressTransition<T> {
+  gesture: Extract<MenuPressGesture<T>, {phase: 'open'}>,
+  event: MenuPressEvent<T>,
+): MenuPressStep<T> {
   switch (event.type) {
-    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),
-        };
-      }
+    case 'move':
       if (!event.isInMenu) {
         return {gesture, effect: NONE};
       }
@@ -328,14 +233,7 @@ 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
@@ -347,7 +245,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':
@@ -356,11 +254,11 @@ function stepOpen<T>(
 }
 
 function stepTracking<T>(
-  gesture: Extract<MenuPressState<T>, {phase: 'tracking'}>,
-  event: MenuPressInput<T>,
-): MenuPressTransition<T> {
+  gesture: Extract<MenuPressGesture<T>, {phase: 'tracking'}>,
+  event: MenuPressEvent<T>,
+): MenuPressStep<T> {
   switch (event.type) {
-    case 'move':
+    case 'move': {
       if (event.row === gesture.row) {
         return {gesture, effect: NONE};
       }
@@ -368,6 +266,7 @@ function stepTracking<T>(
         gesture: {...gesture, row: event.row},
         effect: highlightEffect(event.row),
       };
+    }
     case 'up':
       return release(gesture.pointerType, event);
     case 'cancel':
@@ -379,107 +278,3 @@ 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 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).
-   */
-  | {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/useClickableContainer.doc.mjs

@@ -61,17 +61,12 @@ 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 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: 'Attach both onClick and onMouseUp to the container element for full click handling including middle-click.' },
       { 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.' },
     ],
@@ -98,13 +93,12 @@ 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 onClick + onMouseUp + onPointerDown to container element: full click handling incl. middle-click, no touch pressed state for press on nested control.' },
+      { guidance: true, description: 'Attach both onClick + onMouseUp to container element for full click handling incl. middle-click.' },
       { 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,28 +5,19 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick, onMouseUp and onPointerDown handlers for the container;
- *   INTERACTIVE_SELECTORS list;
+ * @output onClick and onMouseUp 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, and a finger press there shows no press on the card. Each navigation
- *   passes the rule in utils/safeUrl.ts first.
+ *   action. 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,
-  type PointerEvent,
-} from 'react';
+import {useCallback, useEffect, type RefObject, type MouseEvent} 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
@@ -168,14 +159,6 @@ 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;
 }
 
 /**
@@ -193,16 +176,12 @@ export interface ClickableContainerResult {
  * @example
  * ```
  * const containerRef = useRef<HTMLDivElement>(null);
- * const { onClick, onMouseUp, onPointerDown } = useClickableContainer({
+ * const { onClick, onMouseUp } = useClickableContainer({
  *   containerRef,
  *   onClick: () => console.log('card clicked'),
  * });
  * return (
- *   <div
- *     ref={containerRef}
- *     onClick={onClick}
- *     onMouseUp={onMouseUp}
- *     onPointerDown={onPointerDown}>
+ *   <div ref={containerRef} onClick={onClick} onMouseUp={onMouseUp}>
  *     <p>Click anywhere on this card</p>
  *     <button onClick={() => alert('button')}>Nested button</button>
  *   </div>
@@ -326,30 +305,5 @@ export function useClickableContainer({
     [containerRef, href, disabled],
   );
 
-  // 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>) => {
-      const containerEl = containerRef.current;
-      const eventTarget = event.target;
-      if (
-        event.pointerType !== 'touch' ||
-        disabled ||
-        containerEl == null ||
-        !(eventTarget instanceof Element) ||
-        eventTarget === event.currentTarget ||
-        !hasInteractiveAncestor(eventTarget, containerEl) ||
-        // The control the container delegates to is the container's own
-        // action: a press on it activates the container.
-        interactiveRef?.current?.contains(eventTarget) === true
-      ) {
-        return;
-      }
-      cancelPress(containerEl);
-    },
-    [containerRef, interactiveRef, disabled],
-  );
-
-  return {onClick, onMouseUp, onPointerDown};
+  return {onClick, onMouseUp};
 }