@astryxdesign/core 0.7.7 → 0.7.8-canary.0d54fd3

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);
+  }
+}

package/src/hooks/scrollLockTouchGuard.ts

@@ -0,0 +1,149 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file scrollLockTouchGuard.ts
+ * @input The node under a finger and the pan's direction, while a scroll lock
+ *   holds the page; the native-scroll probe's edge test (gestures/nativeScroll)
+ * @output isPanAbsorbedBeforePage and isPageZoomedIn, for the page hold
+ * @position Internal hook utility; gestures/pageHold calls it for
+ *   useScrollLock.
+ */
+
+// iOS Safari scrolls an `overflow: hidden` page under a finger.
+// The page hold cancels each pan that would reach the page. This walk decides
+// which pans those are. A scroller that can move in the pan's direction takes
+// the pan. A scroller at its edge that contains its overscroll also takes it.
+// The walk follows flat-tree parents. It ends at a top-layer or fixed-position
+// element, whose containing block is the viewport, so its untaken pans go to
+// the page.
+
+import {canElementScroll} from '../gestures/nativeScroll';
+import {parentAcrossShadow} from '../utils/flatTree';
+
+/**
+ * Whether `element` itself takes a pan. It does when it can still scroll that
+ * way, or when its `overscroll-behavior` contains the overscroll at its edge.
+ */
+function takesPan(
+  element: Element,
+  style: CSSStyleDeclaration,
+  isVertical: boolean,
+  dx: number,
+  dy: number,
+): boolean {
+  const x = isVertical ? 0 : dx;
+  const y = isVertical ? dy : 0;
+  if (canElementScroll(element, x, y)) {
+    return true;
+  }
+  // A scroller at its edge can still move the other way. A box that does not
+  // scroll, or whose content fits, cannot. Its pan goes on along the chain.
+  if (!canElementScroll(element, -x, -y)) {
+    return false;
+  }
+  const behavior = isVertical
+    ? style.overscrollBehaviorY
+    : style.overscrollBehaviorX;
+  return behavior === 'contain' || behavior === 'none';
+}
+
+/**
+ * Whether `element` is in the state that a pseudo-class names (`:modal`,
+ * `:popover-open`). An engine without the pseudo-class has no element in that
+ * state. Its `matches` throws on the selector, so the engine is not asked.
+ * Other errors surface.
+ */
+function isInState(element: Element, pseudoClass: string): boolean {
+  const css = element.ownerDocument.defaultView?.CSS;
+  return (
+    typeof css?.supports === 'function' &&
+    css.supports(`selector(${pseudoClass})`) &&
+    element.matches(pseudoClass)
+  );
+}
+
+/**
+ * Whether a pan that `element` does not take goes to the viewport, not to its
+ * DOM parent. The browser chains scrolling along containing blocks. A
+ * top-layer element (an open modal dialog or popover) or a fixed-position one
+ * has the viewport as its containing block. So a Dialog inside a scrolling
+ * container gives an untaken pan to the page.
+ */
+function chainsToViewport(
+  element: Element,
+  style: CSSStyleDeclaration,
+): boolean {
+  return (
+    style.position === 'fixed' ||
+    isInState(element, ':modal') ||
+    isInState(element, ':popover-open')
+  );
+}
+
+/**
+ * Whether the page is pinch-zoomed in (`visualViewport.scale > 1`). A
+ * one-finger drag then pans the zoomed view, which a zoomed-in reader needs
+ * around an open overlay. The value is read per touch, so a pinch during the
+ * lock counts from the next drag.
+ */
+export function isPageZoomedIn(doc: Document): boolean {
+  return (doc.defaultView?.visualViewport?.scale ?? 1) > 1;
+}
+
+/**
+ * Whether `element` is a native control that takes a finger's drag itself. A
+ * range input moves its thumb, so the drag never reaches the page.
+ */
+function takesDragItself(element: Element): boolean {
+  // `:disabled` also covers a slider inside a disabled fieldset.
+  return element.matches('input[type="range"]:not(:disabled)');
+}
+
+/**
+ * Whether a scroller in the scroll chain of `target` takes a pan of (`dx`,
+ * `dy`) before the page does.
+ */
+export function isPanAbsorbedBeforePage(
+  target: EventTarget | null,
+  dx: number,
+  dy: number,
+): boolean {
+  if (!(target instanceof Node)) {
+    return false;
+  }
+  const doc = target.ownerDocument ?? document;
+  const view = doc.defaultView;
+  if (view == null) {
+    return false;
+  }
+  const isVertical = Math.abs(dy) >= Math.abs(dx);
+  for (
+    let node: Node | null = target;
+    node != null;
+    node = parentAcrossShadow(node)
+  ) {
+    if (!(node instanceof Element)) {
+      continue;
+    }
+    if (takesDragItself(node)) {
+      return true;
+    }
+    if (
+      node === doc.documentElement ||
+      node === doc.body ||
+      node === doc.scrollingElement
+    ) {
+      break;
+    }
+    const style = view.getComputedStyle(node);
+    if (takesPan(node, style, isVertical, dx, dy)) {
+      return true;
+    }
+    if (chainsToViewport(node, style)) {
+      break;
+    }
+  }
+  return false;
+}