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

package/src/hooks/useAttachment.ts

@@ -9,7 +9,7 @@
  * @output Exports useAttachment and useAttachmentPair (two elements): they keep
  *   the attach function bound to the nodes the refs hold across commits
  * @position Internal React helper, not in hooks/index.ts: the one attach and
- *   release lifecycle of the gesture hooks and the pager
+ *   release lifecycle of the gesture hooks, the pager and useAnimator
  *
  * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
  * gestures/__tests__/useFingerScroll.test.tsx and

package/src/hooks/useAutoMediaMode.ts

@@ -160,6 +160,7 @@ export function useAutoMediaMode(
   const {tokens} = useTheme();
   const lastRef = useRef<{background: string; tokens: unknown} | null>(null);
 
+  // Syncs the media mode with the painted color behind the element.
   // No dependency array. A surface color is a painted value, and it changes
   // when a prop on some ancestor changes. No dependency that this hook can
   // name catches that. So the measurement runs on each render, and it skips

package/src/hooks/useBusyAnnouncement.ts

@@ -45,6 +45,8 @@ export function useBusyAnnouncement(
   // Or how to take back its write inside a modal, wherever the modal moves
   // it, until it settles.
   const modalMessageRef = useRef<WithdrawAnnouncement | null>(null);
+  // Syncs the live region with `isBusy`. When it becomes true, the busy message
+  // is announced one frame later.
   useEffect(() => {
     if (!isBusy) {
       hasAnnouncedRef.current = false;

package/src/hooks/useDevWarning.ts

@@ -40,6 +40,8 @@ export function useDevWarning(
   condition: boolean = true,
 ): void {
   const hasWarnedRef = useRef(false);
+  // The console is outside React. The ref prints the warning one time, also
+  // when StrictMode runs the Effect again.
   useEffect(() => {
     if (condition && !hasWarnedRef.current) {
       hasWarnedRef.current = true;

package/src/hooks/useFocusTrap.ts

@@ -50,6 +50,8 @@ export function hasActiveFocusTrapEscape(): boolean {
  * second dismissal owner.
  */
 export function useFocusTrapEscapeCompatibilitySignal(isActive: boolean): void {
+  // Syncs the module count of active Escape traps with `isActive`. The
+  // compatibility signal reads this count.
   useEffect(() => {
     if (!isActive) {
       return;

package/src/hooks/useGridFocus.doc.mjs

@@ -67,16 +67,16 @@ export const docs = {
     },
     {
       name: 'options.onPageUp',
-      type: '() => void',
+      type: '(event: React.KeyboardEvent) => void',
       description:
-        'Callback for Page Up key (e.g., navigate to previous month in calendars).',
+        'Callback for Page Up key (e.g., navigate to previous month in calendars). Receives the key event, so `event.shiftKey` can select a larger step, such as a year.',
       required: false,
     },
     {
       name: 'options.onPageDown',
-      type: '() => void',
+      type: '(event: React.KeyboardEvent) => void',
       description:
-        'Callback for Page Down key (e.g., navigate to next month in calendars).',
+        'Callback for Page Down key (e.g., navigate to next month in calendars). Receives the key event, so `event.shiftKey` can select a larger step, such as a year.',
       required: false,
     },
     {
@@ -172,9 +172,9 @@ export const docsDense = {
     'options.onNavigateAfter':
       'callback when navigation would go after last cell. Receives column index + offset.',
     'options.onPageUp':
-      'callback for Page Up key (e.g. navigate to previous month in calendars).',
+      'callback for Page Up key (e.g. previous month in calendars); receives the key event (shiftKey → e.g. a year).',
     'options.onPageDown':
-      'callback for Page Down key (e.g. navigate to next month in calendars).',
+      'callback for Page Down key (e.g. next month in calendars); receives the key event (shiftKey → e.g. a year).',
     'options.hasRovingTabIndex':
       'own a single roving tab stop across the grid (one focus target tabindex=0, rest -1); repaired on render + moved with arrows. Attach handleFocus to onFocus. default false.',
   },

package/src/hooks/useGridFocus.ts

@@ -80,14 +80,16 @@ export interface UseGridFocusOptions {
   onNavigateAfter?: (column: number, offset: number) => void;
 
   /**
-   * Callback for Page Up key (e.g., previous month).
+   * Callback for Page Up key (e.g., previous month). It receives the key
+   * event, so `event.shiftKey` can select a larger step, such as a year.
    */
-  onPageUp?: () => void;
+  onPageUp?: (event: React.KeyboardEvent) => void;
 
   /**
-   * Callback for Page Down key (e.g., next month).
+   * Callback for Page Down key (e.g., next month). It receives the key
+   * event, so `event.shiftKey` can select a larger step, such as a year.
    */
-  onPageDown?: () => void;
+  onPageDown?: (event: React.KeyboardEvent) => void;
 
   /**
    * Roving-tabindex ownership. When true, the hook manages a single tab stop
@@ -157,7 +159,8 @@ export interface UseGridFocusReturn<T extends HTMLElement = HTMLElement> {
  * - End: Move to last cell in row
  * - Ctrl+Home: Move to first cell in grid
  * - Ctrl+End: Move to last cell in grid
- * - Page Up/Down: Custom callbacks (e.g., month navigation)
+ * - Page Up/Down: Custom callbacks that receive the key event (e.g., month
+ *   navigation, or a year with Shift)
  *
  * The hook enumerates ALL cells matched by `cellSelector` in DOM order and
  * computes row/column over that full set, preserving the true grid geometry
@@ -571,11 +574,11 @@ export function useGridFocus<T extends HTMLElement = HTMLElement>(
           break;
 
         case 'PageUp':
-          onPageUp?.();
+          onPageUp?.(e);
           break;
 
         case 'PageDown':
-          onPageDown?.();
+          onPageDown?.(e);
           break;
 
         default:

package/src/hooks/useHotkeys.ts

@@ -157,6 +157,8 @@ export function useHotkeys(hotkeys: Hotkey[]): void {
     hotkeysRef.current = hotkeys;
   });
 
+  // Syncs a window keydown listener with this mount. The listener runs the
+  // first hotkey that matches.
   useEffect(() => {
     const isApple = isApplePlatform();
 

package/src/hooks/useImageMode.ts

@@ -73,6 +73,8 @@ export function useImageMode(
     mode: 'dark' | 'light' | null;
   } | null>(null);
 
+  // Syncs the mode with the image at `src`. It fetches and decodes the image,
+  // then samples its pixels.
   useEffect(() => {
     if (!src) {
       return;

package/src/hooks/useInputStatusIcon.tsx

@@ -15,9 +15,10 @@
 import {useCallback, useEffect, useState} from 'react';
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Icon, type IconName, type IconSize} from '../Icon';
+import {Icon, type IconSize} from '../Icon/Icon';
+import type {IconName} from '../Icon/globalIconRegistry';
 import type {InputStatus, InputStatusType} from '../Field/types';
-import {useTooltip} from '../Tooltip';
+import {useTooltip} from '../Tooltip/useTooltip';
 import {radiusVars} from '../theme/tokens.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';

package/src/hooks/useKeyboardHint.tsx

@@ -244,7 +244,7 @@ export function useKeyboardHint(
     [clearDismissTimeout, dismiss, dismissAfterMs, isEnabled, layer],
   );
 
-  // Cleanup on unmount
+  // Releases the dismiss timer and the layer anchor on unmount.
   useEffect(
     () => () => {
       clearDismissTimeout();

package/src/hooks/useLongPress.doc.mjs

@@ -59,7 +59,7 @@ export const docs = {
   ],
   usage: {
     description:
-      'Detects a single-finger press-and-hold and reports where it happened, so touch users can reach affordances that a pointer gets from right-click. iOS Safari never synthesizes a contextmenu event on long-press, which makes this the only touch route into a cursor-positioned surface such as ContextMenu. The press cancels on movement, lift, multi-touch or unmount.',
+      'Detects a single-finger press-and-hold and reports where it happened, so touch users can reach affordances that a pointer gets from right-click. iOS Safari never synthesizes a contextmenu event on long-press, which makes this the only touch route into a cursor-positioned surface such as ContextMenu. The press cancels on movement, lift, multi-touch or unmount. The hold is timed on the touch events\u2019 own timestamps: when a busy page handles the lift late, a finger held for the full delay still reports its long press, before the lift acts.',
     bestPractices: [
       {
         guidance: true,
@@ -102,7 +102,7 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Touch press-and-hold for affordances a pointer reaches by right-click (e.g. ContextMenu). Reports the point so the surface opens under the finger.',
+      "Touch press-and-hold for affordances a pointer reaches by right-click (e.g. ContextMenu). Reports the point so the surface opens under the finger. Timed on the touch events' timestamps: a busy page delays the report, never drops it.",
     bestPractices: [
       {
         guidance: true,

package/src/hooks/useLongPress.ts

@@ -11,6 +11,7 @@
  *   `useMenuPress` for the held-finger menu open
  *
  * SYNC: When modified, update the hooks barrel /packages/core/src/hooks/index.ts
+ * and the detector it wraps, /packages/core/src/hooks/longPressDetector.ts
  */
 
 // iOS Safari sends no `contextmenu` event on a long press. So a long press is
@@ -18,24 +19,24 @@
 //
 // A caller can spread the touch handlers, or call `start`, `moveTo` and
 // `cancel` from its own pointer events, as `useMenuPress` does. Both ways use
-// this hook's hold time, movement tolerance and timer, so a long press means
-// the same thing on a context menu and on a menu trigger.
+// the hold time, movement tolerance and timer of createLongPressDetector. So a
+// long press means the same thing on a context menu and on a menu trigger.
 //
 // The defaults come from the long-press recognizer. The recognizer measures
 // its tolerance as a distance, as UIKit does. This hook measures it on each
 // axis. The context menu's own movement allowance is a guess and is not
 // measured yet (AST-094).
+//
+// The hold is a deadline on the touch events' own clock (longPressDetector.ts).
 
-import {useCallback, useEffect, useRef} from 'react';
+import {useCallback, useEffect, useState} from 'react';
 import {
-  LONG_PRESS_ALLOWABLE_MOVEMENT_PX,
-  LONG_PRESS_DURATION_MS,
-} from '../motion/uikit/longPress';
+  createLongPressDetector,
+  type LongPressTolerance,
+} from './longPressDetector';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 
-// 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;
+export type {LongPressTolerance};
 
 export interface UseLongPressOptions {
   /** Fired with the touch start point once the press is held for `delayMs`. */
@@ -48,19 +49,15 @@ export interface UseLongPressOptions {
   moveCancelPx?: number;
 }
 
-/**
- * @internal A press's own movement tolerance, for a core caller that decides
- * it as the press starts (useMenuPress's trigger). Not in the hooks entry.
- */
-export interface LongPressTolerance {
-  moveCancelPx?: number;
-}
-
 export interface UseLongPressHandlers {
   onTouchStart: (e: React.TouchEvent) => void;
   onTouchMove: (e: React.TouchEvent) => void;
-  onTouchEnd: () => void;
-  onTouchCancel: () => void;
+  /**
+   * The lift. Pass the event, so a press it is stamped past (its timer held
+   * back by a busy page) still reports first. Spreading the handlers does.
+   */
+  onTouchEnd: (e?: React.TouchEvent) => void;
+  onTouchCancel: (e?: React.TouchEvent) => void;
   /**
    * Begin detection at a point, for a caller driving this from its own
    * pointer events rather than the touch handlers above.
@@ -109,109 +106,22 @@ export function useLongPress(
 export function useLongPressDetector(
   options: UseLongPressOptions,
 ): LongPressDetectorHandlers {
-  const {
-    onLongPress,
-    disabled = false,
-    delayMs = DEFAULT_DELAY_MS,
-    moveCancelPx = DEFAULT_MOVE_CANCEL_PX,
-  } = options;
-
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const startRef = useRef<{x: number; y: number} | null>(null);
-  // The press in progress's tolerance, when its caller chose one at start.
-  const pressToleranceRef = useRef<LongPressTolerance | null>(null);
-  // Keep the latest callback without re-creating handlers on every render.
-  const onLongPressRef = useRef(onLongPress);
-  onLongPressRef.current = onLongPress;
-
-  const clear = useCallback(() => {
-    if (timerRef.current != null) {
-      clearTimeout(timerRef.current);
-      timerRef.current = null;
-    }
-    startRef.current = null;
-  }, []);
-
-  const start = useCallback(
-    (point: {x: number; y: number}, tolerance?: LongPressTolerance) => {
-      if (disabled) {
-        return;
-      }
-      // Clear a stale timer first, then record the start point. The clear
-      // also sets startRef to null.
-      clear();
-      startRef.current = {x: point.x, y: point.y};
-      pressToleranceRef.current = tolerance ?? null;
-      timerRef.current = setTimeout(() => {
-        const from = startRef.current;
-        if (from == null) {
-          return;
-        }
-        onLongPressRef.current({x: from.x, y: from.y});
-      }, delayMs);
-    },
-    [disabled, delayMs, clear],
-  );
-
-  const moveTo = useCallback(
-    (point: {x: number; y: number}): boolean => {
-      const from = startRef.current;
-      if (from == null) {
-        return false;
-      }
-      // This press's own tolerance when its caller chose one, on either axis.
-      const limit = pressToleranceRef.current?.moveCancelPx ?? moveCancelPx;
-      if (
-        Math.abs(point.x - from.x) > limit ||
-        Math.abs(point.y - from.y) > limit
-      ) {
-        clear();
-        return false;
-      }
-      return true;
-    },
-    [moveCancelPx, clear],
-  );
-
-  const onTouchStart = useCallback(
-    (e: React.TouchEvent) => {
-      if (disabled) {
-        return;
-      }
-      if (e.touches.length !== 1) {
-        clear();
-        return;
-      }
-      const touch = e.touches[0];
-      start({x: touch.clientX, y: touch.clientY});
-    },
-    [disabled, clear, start],
-  );
-
-  const onTouchMove = useCallback(
-    (e: React.TouchEvent) => {
-      if (startRef.current == null) {
-        return;
-      }
-      if (e.touches.length !== 1) {
-        clear();
-        return;
-      }
-      const touch = e.touches[0];
-      moveTo({x: touch.clientX, y: touch.clientY});
-    },
-    [clear, moveTo],
-  );
-
-  useEffect(() => clear, [clear]);
+  const [detector] = useState(() => createLongPressDetector(options));
+  // The detector reads only committed options. A render that React discards
+  // never reaches it.
+  useIsomorphicLayoutEffect(() => {
+    detector.setOptions(options);
+  });
+  // The detector's pending timer ends with the component.
+  useEffect(() => detector.cancel, [detector]);
 
   return {
-    onTouchStart,
-    onTouchMove,
-    onTouchEnd: clear,
-    onTouchCancel: clear,
-    start,
-    moveTo,
-    cancel: clear,
+    onTouchStart: detector.touchStart,
+    onTouchMove: detector.touchMove,
+    onTouchEnd: detector.touchEnd,
+    onTouchCancel: detector.touchEnd,
+    start: detector.start,
+    moveTo: detector.moveTo,
+    cancel: detector.cancel,
   };
 }

package/src/hooks/useMenuHover.ts

@@ -297,6 +297,7 @@ export function useMenuHover<T extends HTMLElement = HTMLElement>(
     };
   }, [clearTimeouts, hideAndRestoreFocus]);
 
+  // Releases the hover timers on unmount.
   useEffect(() => {
     return () => clearTimeouts();
   }, [clearTimeouts]);

package/src/hooks/useMenuPress.ts

@@ -831,6 +831,8 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
     endGesture();
   }, [endGesture, step]);
 
+  // Syncs the document listeners of the menu gesture counter with this mount.
+  // Unmount ends the gesture.
   useEffect(() => {
     // Install the gesture counter's listeners before the first press.
     currentGesture();

package/src/hooks/useOverflow.ts

@@ -251,7 +251,8 @@ export function useOverflow(
     [calculate],
   );
 
-  // Recalculate when itemCount changes
+  // Syncs the visible count with the rendered layout. It measures again after
+  // the items change.
   useIsomorphicLayoutEffect(() => {
     calculate();
   }, [calculate]);

package/src/hooks/usePressFeedback.ts

@@ -50,6 +50,7 @@ import {installPressFeedback, pressableProps} from '../utils/pressFeedback';
  * ```
  */
 export function usePressFeedback(): typeof pressableProps {
+  // Syncs the shared document listener for press feedback with this mount.
   useEffect(() => installPressFeedback(), []);
   return pressableProps;
 }

package/src/hooks/useResolvedRequired.ts

@@ -29,6 +29,9 @@ import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
  * Semantics only: this drives `aria-required`, never the native `required`
  * attribute, so a layout-level default can't silently switch on browser
  * validation bubbles. `isOptional` takes precedence, matching `FieldLabel`.
+ *
+ * CheckboxInput and Switch do not use this hook: an unchecked box or an off
+ * switch is an answer, so a form default gives them no required state.
  */
 export function useResolvedRequired({
   isRequired = false,

package/src/hooks/useScrollLock.doc.mjs

@@ -4,23 +4,50 @@
 export const docs = {
   name: 'useScrollLock',
   displayName: 'useScrollLock',
-  keywords: ['scroll', 'lock', 'modal', 'dialog', 'body', 'prevent', 'background', 'ios', 'safari', 'fixed', 'scrollbar', 'gutter', 'layout shift', 'reflow'],
+  keywords: [
+    'scroll',
+    'lock',
+    'modal',
+    'dialog',
+    'page',
+    'prevent',
+    'background',
+    'ios',
+    'safari',
+    'touch',
+    'scrollbar',
+    'gutter',
+    'layout shift',
+    'reflow',
+  ],
   params: [
     {
       name: 'isLocked',
       type: 'boolean',
-      description: 'whether body scroll should be locked.',
+      description: 'whether page scroll should be locked.',
       required: true,
     },
   ],
   returns: [],
   usage: {
     description:
-      'Locks body scroll when active by pinning the body with position: fixed. This prevents background scrolling behind modals and dialogs, which is necessary for iOS Safari where overscroll-behavior: contain does not work. Restores the original scroll position when unlocked. Pinning hides the document scrollbar, so where that scrollbar takes layout space (desktop) the hook holds its gutter open with scrollbar-gutter: stable for the duration of the lock. The page, including any position: fixed chrome, does not shift sideways.',
+      'Locks page scroll while active and keeps the page where it is. The page gets overflow: hidden (on the root, or on body when its own overflow is the one the viewport uses), which stops wheel, keyboard and scrollbar scrolling, and overscroll-behavior-y: none on the root and body, which stops the overscroll bounce while the lock holds. Where the primary pointer is coarse (phones and tablets), a one-finger pan that would scroll the page is cancelled, because iOS Safari scrolls an overflow: hidden page under a finger; pans that a scroller inside the overlay can take, drags on a native range input, pinch-zoom, and one-finger drags on a pinch-zoomed page (which pan the zoomed view) still work. The scroll offset never changes, so nothing jumps when the lock starts or ends, and iOS Safari keeps its toolbar as it was. Where the hidden scrollbar takes layout space (desktop), the hook holds its gutter open with scrollbar-gutter: stable, so the page, including any position: fixed chrome, does not shift sideways.',
     bestPractices: [
-      { guidance: true, description: 'Use when opening full-screen modals or dialogs to prevent background content from scrolling.' },
-      { guidance: true, description: 'Pass the same boolean that controls dialog visibility (e.g., isOpen) as the isLocked parameter.' },
-      { guidance: false, description: 'Use for non-modal overlays like popovers or tooltips; users should be able to scroll away from those.' },
+      {
+        guidance: true,
+        description:
+          'Use when opening full-screen modals or dialogs to prevent background content from scrolling.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass the same boolean that controls dialog visibility (e.g., isOpen) as the isLocked parameter.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for non-modal overlays like popovers or tooltips; users should be able to scroll away from those.',
+      },
     ],
   },
   relatedComponents: ['Dialog'],
@@ -32,17 +59,29 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked. Holds the hidden scrollbar\'s gutter open (scrollbar-gutter: stable) so the page (incl. position: fixed chrome) does not shift sideways.',
+    "Locks page scroll while active, page stays where it is: overflow: hidden on the root, or on body when its own overflow propagates (wheel, keyboard, scrollbar) + overscroll-behavior-y: none on root and body (no overscroll bounce while locked) + cancels 1-finger pans that would scroll the page (iOS Safari scrolls overflow: hidden pages under a finger); overlay scrollers, range inputs, pinch-zoom + drags on a zoomed page still work. Offset never changes: no jump, iOS toolbar unchanged. Holds the hidden scrollbar's gutter open (scrollbar-gutter: stable) so the page (incl. position: fixed chrome) does not shift sideways.",
   paramDescriptions: {
-    isLocked: 'whether body scroll should be locked.',
+    isLocked: 'whether page scroll should be locked.',
   },
   usage: {
     description:
-      'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked. Holds the hidden scrollbar\'s gutter open (scrollbar-gutter: stable) so the page (incl. position: fixed chrome) does not shift sideways.',
+      "Locks page scroll while active, page stays where it is: overflow: hidden on the root, or on body when its own overflow propagates (wheel, keyboard, scrollbar) + overscroll-behavior-y: none on root and body (no overscroll bounce while locked) + cancels 1-finger pans that would scroll the page (iOS Safari scrolls overflow: hidden pages under a finger); overlay scrollers, range inputs, pinch-zoom + drags on a zoomed page still work. Offset never changes: no jump, iOS toolbar unchanged. Holds the hidden scrollbar's gutter open (scrollbar-gutter: stable) so the page (incl. position: fixed chrome) does not shift sideways.",
     bestPractices: [
-      { guidance: true, description: 'Use when opening full-screen modals / dialogs to prevent background content from scrolling.' },
-      { guidance: true, description: 'Pass same boolean that controls dialog visibility (e.g. isOpen) as isLocked parameter.' },
-      { guidance: false, description: 'Use for non-modal overlays like popovers / tooltips; users should be able to scroll away from those.' },
+      {
+        guidance: true,
+        description:
+          'Use when opening full-screen modals / dialogs to prevent background content from scrolling.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass same boolean that controls dialog visibility (e.g. isOpen) as isLocked parameter.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for non-modal overlays like popovers / tooltips; users should be able to scroll away from those.',
+      },
     ],
   },
 };