@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/hooks/actionGroupTracker.ts

@@ -3,7 +3,7 @@
 /**
  * @file actionGroupTracker.ts
  * @input The tracked elements, the action selector and hit expansion, and the
- *   press paint and fade clocks
+ *   press paint and the press controller's fade clock
  * @output createActionGroupTracker, ActionGroupTracker,
  *   ActionGroupTrackerOptions, ActionGroupTarget
  * @position Internal core tracker for a held finger that slides across a
@@ -14,8 +14,7 @@
 
 import {clickAndReport, clickForLift} from '../utils/browserClickWait';
 import {armClickGuard} from '../utils/clickGuard';
-import {PRESSED_ATTRIBUTE} from '../utils/pressFeedback';
-import {PRESS_FADE_MS} from '../utils/pressGesture';
+import {PRESSED_ATTRIBUTE, pressFadeMs} from '../utils/pressFeedback';
 
 /** An action that is not enabled takes no highlight and does not run. */
 const DISABLED = ':disabled, [aria-disabled="true"]';
@@ -57,7 +56,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,
@@ -83,8 +83,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;
   /**
@@ -150,6 +155,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.
@@ -186,6 +192,8 @@ export function createActionGroupTracker(
     }
     clearFade(element);
     element.setAttribute(PRESSED_ATTRIBUTE, 'fading');
+    // The stylesheet's release follows the theme's tempo, so the fade ends on
+    // the press controller's clock.
     fades.set(
       element,
       setTimeout(() => {
@@ -193,7 +201,7 @@ export function createActionGroupTracker(
         if (element.getAttribute(PRESSED_ATTRIBUTE) === 'fading') {
           element.removeAttribute(PRESSED_ATTRIBUTE);
         }
-      }, PRESS_FADE_MS),
+      }, pressFadeMs(element)),
     );
   };
 
@@ -241,6 +249,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 &&
@@ -248,22 +259,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.
@@ -276,6 +291,7 @@ export function createActionGroupTracker(
       highlighted = null;
       isTracking = true;
       isInert = inert;
+      landedOn = landed;
       lastX = x;
       lastY = y;
       getOptions().onMove?.(x, y);

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/longPressDetector.ts

@@ -0,0 +1,273 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file longPressDetector.ts
+ * @input The long-press numbers (motion/uikit/longPress.ts) and touch events
+ * @output createLongPressDetector(): one long press at a time, timed on the
+ *   touch events' clock, with no React
+ * @position Internal; the core of useLongPress and useLongPressDetector
+ *   (useLongPress.ts). Not in the hooks entry.
+ *
+ * SYNC: When modified, update /packages/core/src/hooks/useLongPress.ts
+ */
+
+import {
+  LONG_PRESS_ALLOWABLE_MOVEMENT_PX,
+  LONG_PRESS_DURATION_MS,
+} from '../motion/uikit/longPress';
+
+// The hold is a deadline on the touch events' timestamps, on the clock of the
+// touch's own window. A busy main thread can delay the timer past the
+// deadline. A touch stamped after the deadline then reports the press before
+// it acts. A press started by hand from a point has no stamp, so its page
+// timer waits the full delay.
+
+// The long-press numbers have one source, shared with the gesture
+// recognizers (motion/uikit/longPress.ts).
+const DEFAULT_DELAY_MS = LONG_PRESS_DURATION_MS;
+const DEFAULT_MOVE_CANCEL_PX = LONG_PRESS_ALLOWABLE_MOVEMENT_PX;
+
+/** @internal What a detector reads at each start, move and fire. */
+export interface LongPressDetectorOptions {
+  /** Fired with the start point once the press is held for `delayMs`. */
+  onLongPress: (point: {x: number; y: number}) => void;
+  /** When true, a start does nothing. */
+  disabled?: boolean;
+  /** Hold duration before the press fires, in ms. Defaults to 500. */
+  delayMs?: number;
+  /** Movement past this distance (px, either axis) cancels the press. Defaults to 10. */
+  moveCancelPx?: number;
+}
+
+/**
+ * @internal A press's own movement tolerance, for a core caller that decides
+ * it as the press starts (useMenuPress's trigger).
+ */
+export interface LongPressTolerance {
+  moveCancelPx?: number;
+}
+
+/**
+ * @internal The part of a touch event a detector reads, React's or the DOM's.
+ */
+export interface LongPressTouchEvent {
+  readonly touches: {
+    readonly length: number;
+    readonly [index: number]: {
+      readonly clientX: number;
+      readonly clientY: number;
+    };
+  };
+  readonly timeStamp: number;
+  readonly view?: unknown;
+}
+
+/** @internal One detector: start a press, report its touches, or drop it. */
+export interface LongPressDetector {
+  /** Begin detection at a point, dropping any press still pending. */
+  start: (
+    point: {x: number; y: number},
+    tolerance?: LongPressTolerance,
+  ) => void;
+  /** A touch started: one finger begins a press, a second one ends it. */
+  touchStart: (event: LongPressTouchEvent) => void;
+  /** A touch moved: past the tolerance the press is off. */
+  touchMove: (event: LongPressTouchEvent) => void;
+  /** The lift or the cancel. A press it is stamped past reports first. */
+  touchEnd: (event?: LongPressTouchEvent) => void;
+  /**
+   * Report the pointer's new position. Past the tolerance the press is off.
+   * Returns whether a press is still pending.
+   */
+  moveTo: (point: {x: number; y: number}) => boolean;
+  /** Drop any pending press (a lift, a cancel, or the gesture moving on). */
+  cancel: () => void;
+  /** Whether a press is in progress (started and not dropped). */
+  isPending: () => boolean;
+  /** The options the next start, move and fire read. */
+  setOptions: (options: LongPressDetectorOptions) => void;
+}
+
+/** The part of a window's performance timeline a press reads. */
+type EventClock = Pick<Performance, 'now'>;
+
+function clockOf(event: LongPressTouchEvent): EventClock | null {
+  const view = event.view as {performance?: EventClock} | null | undefined;
+  return (
+    view?.performance ??
+    (typeof performance === 'undefined' ? null : performance)
+  );
+}
+
+/**
+ * An event's time on its window's clock. jsdom stamps events with
+ * `Date.now()`. The detector reads the age of such a stamp on that clock, so a
+ * frozen system time keeps the hold's length. A stamp nearer `Date.now()` than
+ * the window's clock is that kind of stamp.
+ */
+function timeOn(
+  clock: EventClock | null,
+  timeStamp: number | undefined,
+): number | undefined {
+  // A stamp of 0 means the event carries no time, so the hold falls back to
+  // the full delay on the page's timer.
+  if (timeStamp == null || !Number.isFinite(timeStamp) || timeStamp <= 0) {
+    return undefined;
+  }
+  if (
+    clock != null &&
+    Math.abs(Date.now() - timeStamp) < Math.abs(clock.now() - timeStamp)
+  ) {
+    return clock.now() - (Date.now() - timeStamp);
+  }
+  return timeStamp;
+}
+
+/** @internal A long-press detector with no React (see LongPressDetector). */
+export function createLongPressDetector(
+  initial: LongPressDetectorOptions,
+): LongPressDetector {
+  let options = initial;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let from: {x: number; y: number} | null = null;
+  // Null for a press started by hand. It has no stamp.
+  let deadline: number | null = null;
+  let clock: EventClock | null = null;
+  let pressTolerance: LongPressTolerance | null = null;
+
+  const cancel = () => {
+    if (timer != null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    from = null;
+    deadline = null;
+    clock = null;
+  };
+
+  const fire = () => {
+    const at = from;
+    if (at == null) {
+      return;
+    }
+    cancel();
+    options.onLongPress({x: at.x, y: at.y});
+  };
+
+  // A touch stamped at or past the deadline: the finger was down for the
+  // whole delay, so the press reports before the touch acts.
+  const fireIfDue = (event: LongPressTouchEvent | undefined) => {
+    const eventTime =
+      event == null ? undefined : timeOn(clock, event.timeStamp);
+    if (deadline != null && eventTime != null && eventTime >= deadline) {
+      fire();
+    }
+  };
+
+  const begin = (
+    point: {x: number; y: number},
+    tolerance: LongPressTolerance | undefined,
+    started: {at: number; clock: EventClock} | undefined,
+  ) => {
+    if (options.disabled === true) {
+      return;
+    }
+    cancel();
+    const delayMs = options.delayMs ?? DEFAULT_DELAY_MS;
+    from = {x: point.x, y: point.y};
+    pressTolerance = tolerance ?? null;
+    const pressClock = started?.clock ?? null;
+    const pressDeadline = started == null ? null : started.at + delayMs;
+    clock = pressClock;
+    deadline = pressDeadline;
+    // Wait only for the rest of the hold. A touch handled late then keeps its
+    // length, and the wait never passes the delay.
+    const remaining =
+      pressClock == null || pressDeadline == null
+        ? delayMs
+        : Math.min(delayMs, Math.max(0, pressDeadline - pressClock.now()));
+    // A late timer yields to queued input once, so a lift stamped before the
+    // deadline still cancels the press. The gesture arena does the same.
+    const run = (mayYield: boolean) => {
+      timer = null;
+      if (
+        mayYield &&
+        pressClock != null &&
+        pressDeadline != null &&
+        pressClock.now() > pressDeadline
+      ) {
+        timer = setTimeout(() => run(false), 0);
+        return;
+      }
+      fire();
+    };
+    timer = setTimeout(() => run(true), remaining);
+  };
+
+  const moveTo = (point: {x: number; y: number}): boolean => {
+    const at = from;
+    if (at == null) {
+      return false;
+    }
+    // This press's own tolerance when its caller chose one, on either axis.
+    const limit =
+      pressTolerance?.moveCancelPx ??
+      options.moveCancelPx ??
+      DEFAULT_MOVE_CANCEL_PX;
+    if (Math.abs(point.x - at.x) > limit || Math.abs(point.y - at.y) > limit) {
+      cancel();
+      return false;
+    }
+    return true;
+  };
+
+  return {
+    start(point, tolerance) {
+      begin(point, tolerance, undefined);
+    },
+    touchStart(event) {
+      if (options.disabled === true) {
+        return;
+      }
+      if (event.touches.length !== 1) {
+        // A second finger ends the press, unless the press was already due.
+        fireIfDue(event);
+        cancel();
+        return;
+      }
+      const touch = event.touches[0];
+      const touchClock = clockOf(event);
+      const at = timeOn(touchClock, event.timeStamp);
+      begin(
+        {x: touch.clientX, y: touch.clientY},
+        undefined,
+        touchClock == null || at == null ? undefined : {at, clock: touchClock},
+      );
+    },
+    touchMove(event) {
+      if (from == null) {
+        return;
+      }
+      fireIfDue(event);
+      if (from == null) {
+        return;
+      }
+      if (event.touches.length !== 1) {
+        cancel();
+        return;
+      }
+      const touch = event.touches[0];
+      moveTo({x: touch.clientX, y: touch.clientY});
+    },
+    touchEnd(event) {
+      fireIfDue(event);
+      cancel();
+    },
+    moveTo,
+    cancel,
+    isPending: () => from != null,
+    setOptions(next) {
+      options = next;
+    },
+  };
+}

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/rootScrollStyles.ts

@@ -0,0 +1,247 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file rootScrollStyles.ts
+ * @input The inline styles of the root and `<body>`
+ * @output claimRootScrollStyle, which owns the page's `overflow`,
+ *   `overscroll-behavior-y` and `scrollbar-gutter`; isScrollLockActive and
+ *   subscribeScrollLock, which report whether a scroll lock holds the page
+ * @position Internal hook utility. Each caller that changes how the page
+ *   scrolls claims these styles here, so no caller overwrites a value that
+ *   another caller still needs.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/useScrollLock.ts
+ */
+
+/** The root scroll styles a caller can hold. */
+export interface RootScrollStyle {
+  /** `hidden` or `clip` stops wheel, keyboard and scrollbar scrolling of the page. */
+  overflow?: 'hidden' | 'clip';
+  /** `none` turns the page's own bounce off at both vertical edges. */
+  overscrollBehaviorY?: 'none' | 'contain';
+  /** `stable` keeps a classic scrollbar's space while the page cannot scroll. */
+  scrollbarGutter?: 'stable';
+}
+
+type RootScrollProperty = keyof RootScrollStyle;
+
+const PROPERTIES: ReadonlyArray<RootScrollProperty> = [
+  'overflow',
+  'overscrollBehaviorY',
+  'scrollbarGutter',
+];
+
+interface Claim {
+  readonly id: number;
+  readonly value: string;
+}
+
+const claims: Record<RootScrollProperty, Claim[]> = {
+  overflow: [],
+  overscrollBehaviorY: [],
+  scrollbarGutter: [],
+};
+
+type SavedStyle =
+  | 'overflow'
+  | 'overflowX'
+  | 'overflowY'
+  | 'overscrollBehaviorY'
+  | 'scrollbarGutter';
+
+/**
+ * The inline styles saved for each property, so a page's own value comes back
+ * exactly, including a one-axis `overflow-x` or `overflow-y`.
+ */
+const SAVED: Record<RootScrollProperty, ReadonlyArray<SavedStyle>> = {
+  overflow: ['overflow', 'overflowX', 'overflowY'],
+  overscrollBehaviorY: ['overscrollBehaviorY'],
+  scrollbarGutter: ['scrollbarGutter'],
+};
+
+/**
+ * An element that holds a property's claims. It keeps the page's own inline
+ * values, saved at the first claim, and the value that the claims last wrote.
+ */
+interface HeldTarget {
+  readonly element: HTMLElement;
+  readonly pageValues: Partial<Record<SavedStyle, string>>;
+  written: string;
+}
+
+const held = new Map<RootScrollProperty, HeldTarget[]>();
+
+let nextClaimId = 0;
+
+/**
+ * The element whose `overflow` the viewport uses. That is the root, unless the
+ * root's own is `visible` and `<body>` sets one, which then propagates to the
+ * viewport. A write to the root in that case stops the propagation. Then
+ * `<body>` becomes its own scroller at offset 0, and the page jumps to its top.
+ */
+function overflowTarget(doc: Document): HTMLElement {
+  const root = doc.documentElement;
+  const {body} = doc;
+  const view = doc.defaultView;
+  if (body == null || view == null) {
+    return root;
+  }
+  const isVisible = (element: Element) => {
+    const style = view.getComputedStyle(element);
+    return (
+      (style.overflowX || 'visible') === 'visible' &&
+      (style.overflowY || 'visible') === 'visible'
+    );
+  };
+  return isVisible(root) && !isVisible(body) ? body : root;
+}
+
+/**
+ * Where a property's claims go. `overflow` goes to the element that the
+ * viewport takes it from. `overscroll-behavior-y` goes to the root and to
+ * `<body>`, because Chrome on Android reads `<body>`'s value for its
+ * pull-to-refresh. `scrollbar-gutter` goes to the root.
+ */
+function claimTargets(
+  property: RootScrollProperty,
+  doc: Document,
+): HTMLElement[] {
+  if (property === 'overflow') {
+    return [overflowTarget(doc)];
+  }
+  if (property === 'scrollbarGutter') {
+    return [doc.documentElement];
+  }
+  return doc.body == null
+    ? [doc.documentElement]
+    : [doc.documentElement, doc.body];
+}
+
+function applyTopClaim(property: RootScrollProperty): void {
+  const targets = held.get(property);
+  if (targets == null) {
+    return;
+  }
+  const stack = claims[property];
+  const top = stack[stack.length - 1];
+  for (const target of targets) {
+    const {style} = target.element;
+    if (top != null) {
+      style[property] = top.value;
+      target.written = top.value;
+      continue;
+    }
+    // The last claim is gone, so the page gets its own values back. A value
+    // that an outside writer set meanwhile stays.
+    if (style[property] === target.written) {
+      style[property] = '';
+      for (const name of SAVED[property]) {
+        const value = target.pageValues[name];
+        if (value) {
+          style[name] = value;
+        }
+      }
+    }
+  }
+  if (top == null) {
+    held.delete(property);
+  }
+}
+
+/**
+ * Sets the page's `overflow`, `overscroll-behavior-y` or `scrollbar-gutter`
+ * until the returned release runs. Claims stack per property: the latest claim
+ * wins, and a release in any order restores the claim beneath it. The page's
+ * own inline value comes back after the last release, unless an outside writer
+ * changed that style meanwhile. A second release does nothing.
+ *
+ * @example
+ * ```
+ * const release = claimRootScrollStyle({overflow: 'hidden'});
+ * // later
+ * release();
+ * ```
+ */
+export function claimRootScrollStyle(claim: RootScrollStyle): () => void {
+  if (typeof document === 'undefined') {
+    return () => {};
+  }
+  nextClaimId += 1;
+  const id = nextClaimId;
+  const claimed: RootScrollProperty[] = [];
+  for (const property of PROPERTIES) {
+    const value = claim[property];
+    if (value == null) {
+      continue;
+    }
+    if (claims[property].length === 0) {
+      held.set(
+        property,
+        claimTargets(property, document).map(element => {
+          const pageValues: Partial<Record<SavedStyle, string>> = {};
+          for (const name of SAVED[property]) {
+            pageValues[name] = element.style[name];
+          }
+          return {element, pageValues, written: ''};
+        }),
+      );
+    }
+    claims[property].push({id, value});
+    claimed.push(property);
+    applyTopClaim(property);
+  }
+
+  let released = false;
+  return () => {
+    if (released) {
+      return;
+    }
+    released = true;
+    for (const property of claimed) {
+      const stack = claims[property];
+      const index = stack.findIndex(entry => entry.id === id);
+      if (index !== -1) {
+        stack.splice(index, 1);
+      }
+      applyTopClaim(property);
+    }
+  };
+}
+
+let lockCount = 0;
+const lockListeners = new Set<(isActive: boolean) => void>();
+
+/** Whether a scroll lock (useScrollLock) currently holds the page. */
+export function isScrollLockActive(): boolean {
+  return lockCount > 0;
+}
+
+/**
+ * Calls `listener` with the new state each time the page becomes locked or
+ * free. A second lock while one holds is no change. Returns the unsubscribe
+ * function.
+ */
+export function subscribeScrollLock(
+  listener: (isActive: boolean) => void,
+): () => void {
+  lockListeners.add(listener);
+  return () => {
+    lockListeners.delete(listener);
+  };
+}
+
+/** For scroll locks: one lock taken (`1`) or released (`-1`). */
+export function reportScrollLock(delta: 1 | -1): void {
+  const wasActive = lockCount > 0;
+  lockCount = Math.max(0, lockCount + delta);
+  const isActive = lockCount > 0;
+  if (isActive === wasActive) {
+    return;
+  }
+  for (const listener of [...lockListeners]) {
+    listener(isActive);
+  }
+}