@astryxdesign/core 0.7.7-canary.550ff21 → 0.7.7-canary.58c5b8a

package/src/hooks/actionGroupTracker.ts

@@ -12,6 +12,8 @@
  * SYNC: When modified, update actionGroupTracker.test.ts
  */
 
+import {clickAndReport, clickForLift} from '../utils/browserClickWait';
+import {armClickGuard} from '../utils/clickGuard';
 import {PRESSED_ATTRIBUTE} from '../utils/pressFeedback';
 import {PRESS_FADE_MS} from '../utils/pressGesture';
 
@@ -55,7 +57,8 @@ export interface ActionGroupTrackerOptions {
    * target past the group's ends commits the lift there wherever the finger
    * lifts.
    * @default the target whose rect, grown by `highlightExpansion`, holds the
-   *   point; none between or outside them
+   *   point, the one the press landed on where several do; none between or
+   *   outside them
    */
   resolveTarget?: (
     x: number,
@@ -70,9 +73,9 @@ export interface ActionGroupTrackerOptions {
    */
   onActivated?: (item: HTMLElement, cancelled: boolean) => void;
   /**
-   * After the lift ran an action, take the browser's own click for that
-   * touch (left to it by a recognizer that did not claim the touch), so the
-   * action runs once. @default false
+   * After the lift ran an action, the shared click guard takes the browser's
+   * own click for that touch, so the action runs once. A recognizer that did
+   * not claim the touch leaves that click to the browser. @default false
    */
   swallowsNativeClick?: boolean;
 }
@@ -81,8 +84,13 @@ export interface ActionGroupTracker {
   /**
    * A press began at viewport (x, y): read the actions' rects once and
    * highlight the one under it. An inert press is taken but tracks nothing.
+   * `landed` is the node the press landed on.
    */
-  begin(x: number, y: number, options?: {inert?: boolean}): void;
+  begin(
+    x: number,
+    y: number,
+    options?: {inert?: boolean; landed?: Node | null},
+  ): void;
   /** The finger moved to viewport (x, y). */
   move(x: number, y: number): void;
   /**
@@ -126,54 +134,6 @@ interface TrackedAction {
   bottom: number;
 }
 
-/**
- * Swallow the browser's own click for a touch that the lift already acted
- * on. The listeners exist only from that lift until the click, the next
- * press, or the next key. An activation with `detail === 0` (a key or
- * assistive technology) always passes, and the swallower keeps waiting
- * (`AST-094`).
- */
-function swallowNextClick(view: Window): void {
-  const disarm = () => {
-    view.removeEventListener('click', onClick, true);
-    view.removeEventListener('pointerdown', disarm, true);
-    view.removeEventListener('keydown', disarm, true);
-  };
-  const onClick = (event: MouseEvent) => {
-    if (!event.isTrusted || event.detail === 0) {
-      return;
-    }
-    disarm();
-    event.preventDefault();
-    event.stopImmediatePropagation();
-  };
-  view.addEventListener('click', onClick, true);
-  view.addEventListener('pointerdown', disarm, true);
-  view.addEventListener('keydown', disarm, true);
-}
-
-/**
- * Click `element` (its own `click()`, so its activation behavior and every
- * handler run as for any click) and report whether a handler cancelled it.
- * The event is read from a capture listener that exists only for the call.
- */
-function clickAndReport(element: HTMLElement): boolean {
-  const view = element.ownerDocument.defaultView;
-  let clicked: Event | null = null;
-  const grab = (event: Event) => {
-    if (clicked == null && event.target === element) {
-      clicked = event;
-    }
-  };
-  view?.addEventListener('click', grab, true);
-  try {
-    element.click();
-  } finally {
-    view?.removeEventListener('click', grab, true);
-  }
-  return (clicked as Event | null)?.defaultPrevented === true;
-}
-
 /**
  * Create a tracker. `getOptions` is read on every call, so a hook can pass
  * the latest props without recreating it.
@@ -196,6 +156,7 @@ export function createActionGroupTracker(
   let actions: TrackedAction[] = [];
   let highlighted: HTMLElement | null = null;
   let beganOn: HTMLElement | null = null;
+  let landedOn: Node | null = null;
   let isTracking = false;
   let isInert = false;
   // The finger's last position: `remeasure` resolves it again.
@@ -287,6 +248,9 @@ export function createActionGroupTracker(
     if (resolveTarget != null) {
       return actions.length === 0 ? null : resolveTarget(x, y, actions);
     }
+    // Rects that share an edge, or that have no layout (a test renderer), can
+    // both hold the point: the one the press landed on wins.
+    let first: HTMLElement | null = null;
     for (const action of actions) {
       if (
         x >= action.left - margin &&
@@ -294,22 +258,26 @@ export function createActionGroupTracker(
         y >= action.top - margin &&
         y <= action.bottom + margin
       ) {
-        return action.element;
+        if (landedOn != null && action.element.contains(landedOn)) {
+          return action.element;
+        }
+        first ??= action.element;
       }
     }
-    return null;
+    return first;
   };
 
   const reset = () => {
     actions = [];
     highlighted = null;
     beganOn = null;
+    landedOn = null;
     isTracking = false;
     isInert = false;
   };
 
   return {
-    begin(x, y, {inert = false} = {}) {
+    begin(x, y, {inert = false, landed = null} = {}) {
       // A press can begin while another is tracked, when a second recognizer
       // takes over the finger (a trigger's held press, then the menu's): the
       // action the first one lit loses its paint.
@@ -322,6 +290,7 @@ export function createActionGroupTracker(
       highlighted = null;
       isTracking = true;
       isInert = inert;
+      landedOn = landed;
       lastX = x;
       lastY = y;
       getOptions().onMove?.(x, y);
@@ -358,14 +327,16 @@ export function createActionGroupTracker(
       const {onActivate, onActivated, swallowsNativeClick} = getOptions();
       if (onActivate != null) {
         onActivate(lifted);
+        if (swallowsNativeClick === true) {
+          armClickGuard(lifted.ownerDocument);
+        }
       } else {
-        const cancelled = clickAndReport(lifted);
+        const cancelled =
+          swallowsNativeClick === true
+            ? clickForLift(lifted)
+            : clickAndReport(lifted);
         onActivated?.(lifted, cancelled);
       }
-      const view = lifted.ownerDocument.defaultView;
-      if (swallowsNativeClick === true && view != null) {
-        swallowNextClick(view);
-      }
       return lifted;
     },
     cancel() {

package/src/hooks/index.ts

@@ -133,6 +133,8 @@ export type {
   UseInteractiveRoleOptions,
 } from './useInteractiveRole';
 
+export {useAnimator} from './useAnimator';
+
 export {useLongPress} from './useLongPress';
 export type {UseLongPressOptions, UseLongPressHandlers} from './useLongPress';
 

package/src/hooks/pressGroupContext.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file pressGroupContext.ts
+ * @input Nothing
+ * @output PressGroupContext: true inside a group whose own tracker paints
+ *   its actions' press
+ * @position Internal; not exported from the hooks entry. AlertDialog
+ *   provides it around its tracked actions, and Button reads it.
+ */
+
+import {createContext} from 'react';
+
+/**
+ * True inside a group whose tracker paints a pointer's press on its actions.
+ * Those actions take no `:active` paint, so one press never lights two.
+ */
+export const PressGroupContext = createContext(false);
+PressGroupContext.displayName = 'PressGroupContext';

package/src/hooks/useActionGroupTracking.ts

@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useActionGroupTracking.ts
+ * @input A ref to a group of sibling actions, the actions' selector, and the
+ *   component's tracking constants
+ * @output Exports useActionGroupTracking and ActionGroupTrackingOptions
+ * @position Internal hook, not exported from the hooks entry. A long press
+ *   drives the shared action-group tracker (hooks/actionGroupTracker.ts) for
+ *   a group that a held pointer slides across. AlertDialog consumes it.
+ *
+ * SYNC: When modified, update useActionGroupTracking.test.tsx
+ */
+
+import {useEffect, useRef, useState, type RefObject} from 'react';
+import {isActive} from '../gestures/GestureRecognizer';
+import {LongPressGestureRecognizer} from '../gestures/LongPressGestureRecognizer';
+import {lockSelection} from '../utils/selectionLock';
+import type {GestureTouch, PointerKind} from '../gestures/types';
+import {useGestureRecognizer} from '../gestures/useGestureRecognizer';
+import {UIKIT_PRESS} from '../motion/uikit/gestures';
+import {isIosWebKit} from '../utils/touchQueries';
+import {createActionGroupTracker} from './actionGroupTracker';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+
+export interface ActionGroupTrackingOptions {
+  /** Selects the actions inside the tracked element. */
+  itemSelector: string;
+  /** How long after touch-down the touched action highlights, ms. */
+  highlightOnsetMs: number;
+  /**
+   * How far outside an action a finger keeps it highlighted, px. A mouse or a
+   * pen hit-tests the actions' exact rects.
+   */
+  highlightExpansion: number;
+  /** Pointers that are tracked; others keep the browser's click. @default every pointer */
+  pointerTypes?: ReadonlyArray<PointerKind>;
+  /** A press whose target this rejects is not tracked. */
+  shouldTrack?: (target: unknown) => boolean;
+  /** Off, nothing is attached and nothing is tracked. @default true */
+  isEnabled?: boolean;
+  /**
+   * Let the gesture host write the group's `touch-action` and refuse a text
+   * selection while a finger or a pen holds it.
+   * @default true
+   */
+  manageStyle?: boolean;
+  /** Runs the action under the finger at the lift. @default its own click */
+  onActivate?: (item: HTMLElement) => void;
+}
+
+const PRESS = UIKIT_PRESS;
+
+/** The ref handed to the recognizer while tracking is off: no element. */
+const DETACHED: RefObject<Element | null> = {current: null};
+
+const EVERY_POINTER: ReadonlyArray<PointerKind> = ['touch', 'pen', 'mouse'];
+
+/**
+ * The group's press: a long press that a second finger on the group ends with
+ * nothing acting. A plain long press ignores a second finger.
+ */
+class ActionGroupPress extends LongPressGestureRecognizer {
+  protected override acceptsTouch(touch: GestureTouch): boolean {
+    if (isActive(this.state)) {
+      this.setState('cancelled');
+      return false;
+    }
+    return super.acceptsTouch(touch);
+  }
+}
+
+/**
+ * Track a held pointer on the group behind `ref` across the actions inside
+ * it, through the shared action-group tracker.
+ */
+export function useActionGroupTracking(
+  ref: RefObject<HTMLElement | null>,
+  options: ActionGroupTrackingOptions,
+): ActionGroupPress {
+  const optionsRef = useRef(options);
+  // Keeps the recognizer's delegate and the tracker, which run outside
+  // render, reading the latest options.
+  useIsomorphicLayoutEffect(() => {
+    optionsRef.current = options;
+  });
+  // The pointer that started the current press. Only a finger gets the hit
+  // expansion; a mouse or a pen hit-tests the actions' exact rects.
+  const pointerRef = useRef<PointerKind>('touch');
+  const landedRef = useRef<Node | null>(null);
+  const [tracker] = useState(() =>
+    createActionGroupTracker(() => ({
+      roots: () => [ref.current],
+      itemSelector: optionsRef.current.itemSelector,
+      highlightExpansion:
+        pointerRef.current === 'touch'
+          ? optionsRef.current.highlightExpansion
+          : 0,
+      onActivate: optionsRef.current.onActivate,
+      // The browser's own click for a press the group ran is taken, so the
+      // action runs once. The gesture host swallows it for a press it claims.
+      // This covers one it does not claim, a mouse under a coarse pointer.
+      swallowsNativeClick: true,
+    })),
+  );
+  const isEnabled = options.isEnabled ?? true;
+  // Synchronizes the tracker with tracking on and mounted. Turning tracking
+  // off, or unmounting, drops a tracked press and ends its release fades.
+  // The host reports no cancellation to a disabled recognizer, and the lift
+  // that runs an action often closes the owner before its fade ends.
+  useEffect(
+    () => () => {
+      tracker.cancel();
+      tracker.dispose();
+    },
+    [tracker, isEnabled],
+  );
+
+  return useGestureRecognizer(
+    isEnabled ? ref : DETACHED,
+    () =>
+      new ActionGroupPress({
+        name: 'ActionGroupTracking',
+        minimumPressDuration: options.highlightOnsetMs,
+        allowableMovement: Number.POSITIVE_INFINITY,
+        allowedPointerTypes: options.pointerTypes ?? EVERY_POINTER,
+        delaysTouchesBegan: true,
+        // The hold picks an action, so a held finger or pen starts no text
+        // selection and opens no callout while down. A long press brings this
+        // lock by default; this hold has no minimum duration, so it names it.
+        selectionLock: lockSelection,
+        shouldReceiveTouch: (recognizer, touch) => {
+          if (recognizer.numberOfTouches === 0) {
+            pointerRef.current = touch.pointerType;
+            const target = touch.target as Node | null;
+            landedRef.current =
+              typeof target?.nodeType === 'number' ? target : null;
+          }
+          return receiveTouch(recognizer, touch, optionsRef.current);
+        },
+      }),
+    recognizer => {
+      switch (recognizer.state) {
+        case 'began': {
+          const {x, y} = recognizer.location();
+          tracker.begin(x, y, {landed: landedRef.current});
+          break;
+        }
+        case 'changed': {
+          const {x, y} = recognizer.location();
+          tracker.move(x, y);
+          break;
+        }
+        case 'ended': {
+          const doc = ref.current?.ownerDocument;
+          const focusedBefore = doc?.activeElement ?? null;
+          const beganOn = tracker.beganOn;
+          // Whether a click on the lifted action would focus it. A mouse's or
+          // a pen's pointerdown already gave the engine's answer, on the action
+          // it began on. A tap focuses on a later mousedown, which the claimed
+          // touch cancels, so the platform answers for a finger.
+          // iOS WebKit focuses no tapped button; Chromium and Firefox do.
+          const clickFocuses =
+            pointerRef.current === 'touch'
+              ? !isIosWebKit(doc?.defaultView)
+              : beganOn != null && focusedBefore === beganOn;
+          const lifted = tracker.end();
+          // The lift runs the action's own click(), which moves no focus. So
+          // focus moves to the lifted action, unless its click moved focus.
+          if (
+            clickFocuses &&
+            lifted != null &&
+            lifted.isConnected &&
+            doc?.activeElement === focusedBefore &&
+            focusedBefore !== lifted
+          ) {
+            lifted.focus({preventScroll: true, focusVisible: false});
+          }
+          break;
+        }
+        case 'cancelled':
+          tracker.cancel();
+          break;
+        case 'possible':
+        case 'failed':
+          // Listeners are not called for these.
+          break;
+      }
+    },
+    {
+      isEnabled,
+      manageStyle: options.manageStyle ?? true,
+      actionGroup: true,
+    },
+  );
+}
+
+/**
+ * The recognizer's should-receive delegate. It also picks the press's clock.
+ * Inside a scroller the press waits the content-touch delay and fails past
+ * the slop, so the scroller takes a flick. Elsewhere it begins at once, with
+ * no movement limit.
+ */
+function receiveTouch(
+  recognizer: LongPressGestureRecognizer,
+  touch: GestureTouch,
+  options: ActionGroupTrackingOptions,
+): boolean {
+  if (options.shouldTrack?.(touch.target) === false) {
+    return false;
+  }
+  if (recognizer.numberOfTouches === 0) {
+    const isInsideScroller = touch.scroll?.isInsideScroller === true;
+    recognizer.minimumPressDuration = isInsideScroller
+      ? PRESS.contentTouchDelay.value
+      : options.highlightOnsetMs;
+    recognizer.allowableMovement = isInsideScroller
+      ? PRESS.slop.value
+      : Number.POSITIVE_INFINITY;
+  }
+  return true;
+}

package/src/hooks/useAnimator.doc.mjs

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useAnimator',
+  displayName: 'useAnimator',
+  keywords: [
+    'animate',
+    'animation',
+    'animator',
+    'spring',
+    'decay',
+    'momentum',
+    'fling',
+    'motion',
+    'transform',
+    'opacity',
+    'drag',
+    'card',
+  ],
+  params: [
+    {
+      name: 'ref',
+      type: 'RefObject<HTMLElement | null>',
+      description:
+        'The ref of the one element to animate, the same ref you pass to the element: another hook, such as a gesture hook, can take it too, so a drag and an animation share one element. After every render the animator follows the element behind it. When the element unmounts its motion stops and its values return to rest, so a remount starts at rest, and so does a node that replaces it. Before the element mounts, and while it is unmounted, every call does nothing and `animate` and `decay` resolve at once.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'animator',
+      type: 'AnimatorHandle',
+      description:
+        "The element's animator, the same object on every render: `animate(target, {velocity?})` springs channels to a target on the state-change motion Astryx's components use, `decay(velocity)` coasts them from a release velocity, `set(values)` jumps them, `get()` and `getVelocity()` read them, and `stop()` halts them. The channels are `x` and `y` (px), `scale` (1 at the element's size), `rotate` (degrees) and `opacity` (0 to 1). `animate` and `decay` return a promise that resolves when the motion ends. Calling it never re-renders the component. Calls before the ref attaches do nothing and resolve at once.",
+    },
+  ],
+  usage: {
+    description:
+      "Animates one element with the motion Astryx's own components use. Call `animator.animate` to spring an element to new values on the state-change motion, `animator.decay` to fling it with the momentum of a released scroll view, and `animator.set` to move it directly, so a card can follow a finger, snap back and be thrown away. To animate an area's layout as its items change, use `useAnimatedLayout`; for what a component already animates, such as a sheet's detents or a carousel's snapping, use the component's own props. Outside React, use `createAnimator`.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Call the animator from event handlers and effects: it lives outside render, so animating never re-renders the component.',
+      },
+      {
+        guidance: true,
+        description:
+          'Start every `animate` that follows a drag with the release velocity, so the element carries on as it was thrown.',
+      },
+      {
+        guidance: true,
+        description:
+          'Reach every state an animation shows without the animation too: a key, a button or a menu item that calls the same code.',
+      },
+      {
+        guidance: false,
+        description:
+          'Keep the animated values in React state: read them with `animator.get()` when you need them.',
+      },
+    ],
+    accessibility: [
+      {
+        name: 'Keyboard and assistive technology',
+        category: 'Keyboard',
+        description:
+          'An animator moves an element; it adds no way to act. Give every action an animation stands for a control a keyboard and a screen reader can reach, such as a button that discards a card, and have it call `animate`, which Reduce Motion turns into a fade in place. Keep `decay` for a throw the person made: Reduce Motion keeps the momentum of a coast, as it continues that throw. Keep focus on an element that stays on screen: move it before you fling its element away.',
+      },
+      {
+        name: 'Reduce Motion',
+        category: 'Content',
+        criterion: '2.3.3 Animation from Interactions',
+        description:
+          'When the person asks for reduced motion, every call is planned for them. On a touch screen a move or a scale becomes a short opacity cross-fade: the element fades out where it was and fades back in where it lands. With a mouse it lands at once. A decay of `x` and `y` keeps its momentum, as it continues the throw the person made; a decay of `scale`, `rotate` or `opacity` is planned like a move. No option turns this off.',
+      },
+    ],
+  },
+  relatedHooks: ['useAnimatedLayout'],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    "Animates the element behind ref (x, y, scale, rotate, opacity) with Astryx's motion; returns the animator.",
+  paramDescriptions: {
+    ref: 'The element ref; share it with a gesture hook to drag and animate one element.',
+  },
+  returnDescriptions: {
+    animator:
+      'animate(target, {velocity?}), decay(velocity), set, get, getVelocity, stop; stable, never re-renders.',
+  },
+  usage: {
+    description:
+      'Spring with animate, fling with decay, follow a finger with set. Reduce Motion: a cross-fade on touch, at once with a mouse; decay keeps its momentum.',
+    bestPractices: [
+      {
+        guidance: true,
+        description: 'Pass the release velocity to animate after a drag.',
+      },
+      {
+        guidance: false,
+        description: 'Keep animated values in state; read animator.get().',
+      },
+    ],
+  },
+};

package/src/hooks/useAnimator.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAnimator.ts
+ * @input React (useState), the element ref the caller owns, the public
+ *   animator factory (animator/createAnimator.ts) and useAttachment
+ * @output Exports `useAnimator(ref)`: the public animator for the element
+ *   behind `ref`
+ * @position Public hook, exported from `@astryxdesign/core/hooks`. A thin
+ *   wrapper over `createAnimator` with no behavior of its own.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useAnimator.test.tsx
+ * - /packages/core/src/hooks/useAnimator.doc.mjs
+ */
+
+import {useState, type RefObject} from 'react';
+import {
+  createAttachableAnimator,
+  type AnimatorHandle,
+} from '../animator/createAnimator';
+import {useAttachment} from './useAttachment';
+
+/**
+ * Animates the element behind `ref` with the motion Core uses. Call
+ * `animate`, `decay`, `set`, `get`, `getVelocity` or `stop` on the returned
+ * animator from event handlers and effects. Pass the same `ref` to a gesture
+ * hook to drag and animate one element.
+ *
+ * The hook makes the animator once, and animating never re-renders the
+ * component. After each commit, the animator follows the element behind
+ * `ref`, also a node that replaces it. An unmount stops running motion and
+ * drops the values. A remount, or a node that replaces the element, starts
+ * at rest. While no element is attached, every call does nothing, and
+ * `animate` and `decay` resolve at once.
+ *
+ * @example
+ * ```
+ * const ref = useRef<HTMLDivElement>(null);
+ * const animator = useAnimator(ref);
+ * return (
+ *   <div ref={ref} onClick={() => animator.animate({scale: 1.2})}>
+ *     Card
+ *   </div>
+ * );
+ * ```
+ */
+export function useAnimator(
+  ref: RefObject<HTMLElement | null>,
+): AnimatorHandle {
+  const [{handle, attach}] = useState(() => {
+    const {animator, attach: attachElement} = createAttachableAnimator();
+    // The handle without `destroy`: the hook owns the element's lifetime.
+    const {destroy: _destroy, ...handle} = animator;
+    return {
+      handle,
+      attach: (element: HTMLElement) => {
+        attachElement(element);
+        return () => attachElement(null);
+      },
+    };
+  });
+  useAttachment(ref, attach, null);
+  return handle;
+}