@astryxdesign/core 0.7.7 → 0.7.8-canary.07ee4b5

package/src/hooks/scrollbarGutter.ts

@@ -2,7 +2,8 @@
 
 /**
  * @file scrollbarGutter.ts
- * @input The element a scroll lock pins, plus live layout measurements
+ * @input The element whose width a scroll lock holds, plus live layout
+ *   measurements
  * @output holdScrollbarGutter and the ScrollbarGutterHold it returns
  * @position Internal hook utility; used by useScrollLock and MobileNav so that
  *   locking background scroll does not resize the layout viewport.
@@ -16,6 +17,8 @@
 // engines without `scrollbar-gutter`, and it applies only when a measurement
 // shows that the element moved.
 
+import {claimRootScrollStyle} from './rootScrollStyles';
+
 const NOOP: ScrollbarGutterHold = {
   settle() {},
   release() {},
@@ -23,14 +26,23 @@ const NOOP: ScrollbarGutterHold = {
 
 export interface ScrollbarGutterHold {
   /**
-   * Call once the lock's own styles are applied: measures whether the element
-   * grew anyway and, only then, pads the difference away.
+   * Call once the lock's own styles apply. It holds the gutter open, or,
+   * without `scrollbar-gutter`, pads away only the width the element gained.
    */
   settle(): void;
   /** Call on unlock: restores everything this hold changed. */
   release(): void;
 }
 
+/** Whether the engine reserves a gutter for `scrollbar-gutter: stable`. */
+function supportsScrollbarGutter(): boolean {
+  return (
+    typeof CSS !== 'undefined' &&
+    typeof CSS.supports === 'function' &&
+    CSS.supports('scrollbar-gutter', 'stable')
+  );
+}
+
 /**
  * Keeps `element`'s content box the width it is right now, across a scroll
  * lock that is about to hide the document's scrollbar.
@@ -40,8 +52,8 @@ export interface ScrollbarGutterHold {
  * ScrollbarGutterHold.release} on unlock:
  *
  * ```
- * const hold = holdScrollbarGutter(document.body);
- * body.style.position = 'fixed';
+ * const hold = holdScrollbarGutter(document.documentElement);
+ * document.documentElement.style.overflow = 'hidden';
  * hold.settle();
  * ```
  *
@@ -56,28 +68,37 @@ export function holdScrollbarGutter(element: HTMLElement): ScrollbarGutterHold {
   const root = document.documentElement;
   const viewportWidth = root.clientWidth;
 
-  // 0 means "no layout to measure" (jsdom, and any non-visual environment),
-  // not "the scrollbar is as wide as the window".
-  if (viewportWidth === 0) {
+  // 0 means that there is no layout to measure, as in jsdom. An overlay
+  // scrollbar takes no space, so there is nothing to hold. A gutter held open
+  // on such a page would add space that was never there.
+  if (viewportWidth === 0 || window.innerWidth <= viewportWidth) {
     return NOOP;
   }
 
-  const previousGutter = root.style.scrollbarGutter;
+  if (supportsScrollbarGutter()) {
+    // The gutter holds the width by construction, so the lock forces no second
+    // layout. Each hold is a stacked claim, so one release keeps the gutter
+    // that another hold still needs.
+    let releaseGutter: (() => void) | null = null;
+    return {
+      settle() {
+        releaseGutter ??= claimRootScrollStyle({scrollbarGutter: 'stable'});
+      },
+      release() {
+        releaseGutter?.();
+        releaseGutter = null;
+      },
+    };
+  }
+
+  // An engine without `scrollbar-gutter`: measure the element now, again
+  // once the lock's styles apply, and pad away what it grew. This is the one
+  // path that reads layout after a write.
   const previousPadding = element.style.paddingRight;
   const widthBefore = element.getBoundingClientRect().width;
-
-  let heldGutter = false;
   let padded = false;
   let settled = false;
 
-  // Only when a space-taking scrollbar is actually there. Holding the gutter
-  // open on a page that never had one would carve out 15px that was never
-  // reserved — the same shift, in the other direction.
-  if (window.innerWidth > viewportWidth) {
-    root.style.scrollbarGutter = 'stable';
-    heldGutter = true;
-  }
-
   return {
     settle() {
       if (settled) {
@@ -86,9 +107,7 @@ export function holdScrollbarGutter(element: HTMLElement): ScrollbarGutterHold {
       settled = true;
 
       // What the lock actually did to this element, rather than what we
-      // assumed it would do. 0 on any engine where the gutter held — and on a
-      // page that already sets `scrollbar-gutter: stable` itself, where the
-      // scrollbar was never taking the space back.
+      // assumed it would do.
       const grew = element.getBoundingClientRect().width - widthBefore;
       if (grew <= 0) {
         return;
@@ -105,10 +124,6 @@ export function holdScrollbarGutter(element: HTMLElement): ScrollbarGutterHold {
         element.style.paddingRight = previousPadding;
         padded = false;
       }
-      if (heldGutter) {
-        root.style.scrollbarGutter = previousGutter;
-        heldGutter = false;
-      }
     },
   };
 }

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

package/src/hooks/useAnnounceRenderedText.ts

@@ -135,6 +135,7 @@ export function useAnnounceRenderedText(
   );
   const isFirstRunRef = useRef(true);
 
+  // Syncs the live region with the rendered text.
   // No dependency array: the text lives in the DOM, and a caller can change it
   // without a prop that this hook sees. One text read per render is cheap, and
   // the dedupe below makes later renders no-ops.

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();