@astryxdesign/core 0.7.6 → 0.7.7-canary.0eb44a2

package/dist/gestures/wheelSegmenter.js

@@ -0,0 +1,122 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file wheelSegmenter.ts
+ * @input A wheel stream's deltas along one axis, with their event times
+ * @output Exports WheelSegmenter and isBunched. WheelSegmenter splits the
+ *   stream into gestures and reads a trackpad's lift (the onset of momentum).
+ *   isBunched tells one stall's merge from a frame.
+ * @position Read by GestureHost.ts's wheel input: the web reports no
+ *   trackpad contact or phase, so both are inferred.
+ */
+
+/** Momentum arrives at frame rate: a pause this long ends it. */
+const MOMENTUM_GAP_MS = 50;
+/**
+ * A wheel this close to the one before, ms, is one stall's merge. Frames come
+ * further apart at every display rate up to 500 Hz, which is 2 ms.
+ */
+const BUNCHED_MS = 1.5;
+/** Shrinking deltas in a row before the lift is read. */
+const LIFT_RUN = 4;
+/** And how much of its size the run has lost by then. */
+const LIFT_DECAY = 0.8;
+
+/**
+ * Whether a wheel `intervalMs` after the one before is one stall's merge, not
+ * a frame. A stalled page receives the wheels it held back together, within
+ * 1.5 ms of each other. The rule reads no history, so slow wheels never make
+ * a real frame look like a merge.
+ */
+export function isBunched(intervalMs) {
+  return intervalMs <= BUNCHED_MS;
+}
+
+/**
+ * A trackpad gesture has a finger phase and, after a fling, a momentum phase.
+ * In the finger phase, deltas come while the fingers move, with pauses when
+ * they move slowly. In the momentum phase, deltas come at frame rate and
+ * shrink smoothly. The lift is the start of a run of shrinking deltas that
+ * has lost a fifth of its size. In the finger phase, a pause of `idleMs`
+ * ends the gesture. In the momentum phase, a reversal, a jump up against the
+ * decay, or a pause of 50 ms starts a new gesture. A bunched wheel is never
+ * a jump. The decay reads it by its last step. Momentum never pauses,
+ * reverses or grows.
+ */
+export class WheelSegmenter {
+  gesture = 0;
+  phase = 'finger';
+  last = -Infinity;
+  previous = 0;
+  sign = 0;
+  count = 0;
+  run = 0;
+  runStart = 0;
+  push(time, delta, idleMs) {
+    const size = Math.abs(delta);
+    const sign = Math.sign(delta);
+    const gap = time - this.last;
+    const bunched = this.count > 0 && isBunched(gap);
+    let boundary = null;
+    if (this.count === 0) {
+      boundary = this.gesture === 0 ? 'first' : 'idle';
+    } else if (this.phase === 'finger' && gap >= idleMs) {
+      boundary = 'idle';
+    } else if (this.phase === 'momentum') {
+      if (sign !== 0 && this.sign !== 0 && sign !== this.sign) {
+        boundary = 'reversal';
+      } else if (gap >= MOMENTUM_GAP_MS) {
+        boundary = 'gap';
+      } else if (!bunched && size >= 2 && size > this.previous * 1.3 + 0.5) {
+        boundary = 'jump';
+      }
+    }
+    // A bunched wheel carries the steps of the frames it merged. The decay
+    // goes on from its last step, so the steps after it read as they are.
+    const steps = boundary == null && bunched && this.previous > 0 ? Math.max(1, Math.round(size / this.previous)) : 1;
+    if (boundary != null) {
+      this.gesture += 1;
+      this.phase = 'finger';
+      this.count = 0;
+      this.run = 0;
+    }
+    let liftNow = false;
+    let decaying = false;
+    if (this.phase === 'finger' && this.count >= 3 && size > 0) {
+      // A bunched wheel is read by its last step, as the decay goes on from it.
+      const step = size / steps;
+      decaying = step <= this.previous * 0.995 && step >= this.previous * 0.5;
+      if (decaying) {
+        if (this.run === 0) {
+          this.runStart = this.previous;
+        }
+        this.run += 1;
+      } else {
+        this.run = 0;
+      }
+      if (this.run >= LIFT_RUN && step <= this.runStart * LIFT_DECAY) {
+        this.phase = 'momentum';
+        liftNow = true;
+      }
+    }
+    this.count += 1;
+    this.previous = size / steps;
+    if (sign !== 0) {
+      this.sign = sign;
+    }
+    this.last = time;
+    return {
+      boundary,
+      phase: this.phase,
+      gesture: this.gesture,
+      liftNow,
+      decaying: decaying && !liftNow,
+      bunched: boundary == null && bunched
+    };
+  }
+
+  /** The gesture ended on its own (its timer): the next event starts one. */
+  end() {
+    this.count = 0;
+  }
+}

package/dist/hooks/useAttachment.d.ts

@@ -1,15 +1,15 @@
 /**
  * @file useAttachment.ts
- * @input A node ref (an element's, or the document's), an attach function
+ * @input Node refs (an element's, or the document's), an attach function
  *   and a key
- * @output Exports useAttachment: keeps the attach function bound to the node
- *   the ref holds across commits
- * @position Internal React helper, not in hooks/index.ts: the one attach
- *   and release lifecycle of the gesture hooks (useGestureRecognizer,
- *   usePressTracker, useFingerScroll)
+ * @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
  *
- * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx
- * and gestures/__tests__/useFingerScroll.test.tsx.
+ * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
+ * gestures/__tests__/useFingerScroll.test.tsx and
+ * __tests__/useAttachmentPair.test.tsx.
  */
 import { type RefObject } from 'react';
 /**
@@ -19,4 +19,12 @@ import { type RefObject } from 'react';
  * a commit that changes neither does nothing (react-component-runtime INV3).
  */
 export declare function useAttachment<T extends Node = Element>(ref: RefObject<T | null>, attach: (element: T) => () => void, key: unknown): void;
+/**
+ * `useAttachment` for two elements. It keeps `attach` bound to the pair the
+ * refs hold after each commit, once both are there. Replacing either element
+ * releases the attachment and attaches the new pair. A changed `key`
+ * re-attaches, and the last attachment is released on unmount. A commit that
+ * changes neither does nothing.
+ */
+export declare function useAttachmentPair<A extends Element, B extends Element>(firstRef: RefObject<A | null>, secondRef: RefObject<B | null>, attach: (first: A, second: B) => () => void, key: unknown): void;
 //# sourceMappingURL=useAttachment.d.ts.map

package/dist/hooks/useAttachment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAttachment.d.ts","sourceRoot":"","sources":["../../src/hooks/useAttachment.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,IAAI,GAAG,OAAO,EACpD,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EACxB,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,IAAI,EAClC,GAAG,EAAE,OAAO,GACX,IAAI,CA2BN"}
+{"version":3,"file":"useAttachment.d.ts","sourceRoot":"","sources":["../../src/hooks/useAttachment.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAS,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,IAAI,GAAG,OAAO,EACpD,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EACxB,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,IAAI,EAClC,GAAG,EAAE,OAAO,GACX,IAAI,CAEN;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EACpE,QAAQ,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EAC7B,SAAS,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EAC9B,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,MAAM,IAAI,EAC3C,GAAG,EAAE,OAAO,GACX,IAAI,CAMN"}

package/dist/hooks/useAttachment.js

@@ -4,16 +4,16 @@
 
 /**
  * @file useAttachment.ts
- * @input A node ref (an element's, or the document's), an attach function
+ * @input Node refs (an element's, or the document's), an attach function
  *   and a key
- * @output Exports useAttachment: keeps the attach function bound to the node
- *   the ref holds across commits
- * @position Internal React helper, not in hooks/index.ts: the one attach
- *   and release lifecycle of the gesture hooks (useGestureRecognizer,
- *   usePressTracker, useFingerScroll)
+ * @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
  *
- * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx
- * and gestures/__tests__/useFingerScroll.test.tsx.
+ * SYNC: When modified, update gestures/__tests__/useGestureRecognizer.test.tsx,
+ * gestures/__tests__/useFingerScroll.test.tsx and
+ * __tests__/useAttachmentPair.test.tsx.
  */
 import { useRef } from 'react';
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
@@ -25,21 +25,41 @@ import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
  * a commit that changes neither does nothing (react-component-runtime INV3).
  */
 export function useAttachment(ref, attach, key) {
+  useAttachedNodes([ref], ([node]) => attach(node), key);
+}
+
+/**
+ * `useAttachment` for two elements. It keeps `attach` bound to the pair the
+ * refs hold after each commit, once both are there. Replacing either element
+ * releases the attachment and attaches the new pair. A changed `key`
+ * re-attaches, and the last attachment is released on unmount. A commit that
+ * changes neither does nothing.
+ */
+export function useAttachmentPair(firstRef, secondRef, attach, key) {
+  useAttachedNodes([firstRef, secondRef], ([first, second]) => attach(first, second), key);
+}
+
+/**
+ * The lifecycle both share: one attachment of the nodes the refs hold. It is
+ * made once every node is there, and released when a node or `key` changes
+ * and at unmount.
+ */
+function useAttachedNodes(refs, attach, key) {
   const attachmentRef = useRef(null);
 
-  // Syncs the attachment with the DOM node `ref` holds after this commit.
+  // Syncs the attachment with the DOM nodes the refs hold after this commit.
   useIsomorphicLayoutEffect(() => {
-    const element = ref.current;
+    const nodes = refs.map(ref => ref.current);
     const current = attachmentRef.current;
-    if (current?.element === element && current?.key === key) {
+    if (current != null && current.key === key && nodes.every((node, index) => node === current.nodes[index])) {
       return;
     }
     current?.release();
-    attachmentRef.current = element == null ? null : {
-      element,
+    attachmentRef.current = nodes.every(node => node != null) ? {
+      nodes: nodes,
       key,
-      release: attach(element)
-    };
+      release: attach(nodes)
+    } : null;
   });
 
   // Releases the attachment at unmount.

package/dist/hooks/useFocusTrap.d.ts

@@ -83,4 +83,19 @@ export interface UseFocusTrapReturn<T extends HTMLElement = HTMLElement> {
  * ```
  */
 export declare function useFocusTrap<T extends HTMLElement = HTMLElement>(options: UseFocusTrapOptions): UseFocusTrapReturn<T>;
+/**
+ * Package-internal options. Not re-exported from the package entry point.
+ */
+interface InternalFocusTrapOptions extends UseFocusTrapOptions {
+    /**
+     * The element to restore focus to on deactivation, read at activation. For
+     * an overlay that may move focus inside before the trap activates (initial
+     * focus within the opening event), the element focused at activation is
+     * already inside, so the overlay names its opener instead. Returning `null`
+     * falls back to the element focused at activation.
+     */
+    getRestoreTarget?: () => HTMLElement | null;
+}
+export declare function useFocusTrapInternal<T extends HTMLElement = HTMLElement>(options: InternalFocusTrapOptions): UseFocusTrapReturn<T>;
+export {};
 //# sourceMappingURL=useFocusTrap.d.ts.map

package/dist/hooks/useFocusTrap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAU7E;AA+BD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAI1E;AA8DD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAuQvB"}
+{"version":3,"file":"useFocusTrap.d.ts","sourceRoot":"","sources":["../../src/hooks/useFocusTrap.ts"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,qCAAqC,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAU7E;AA+BD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,WAAW,GAAG,WAAW,EAAE,CAI1E;AA8DD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IACrE;;OAEG;IACH,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAC9D,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;GAEG;AACH,UAAU,wBAAyB,SAAQ,mBAAmB;IAC5D;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EACtE,OAAO,EAAE,wBAAwB,GAChC,kBAAkB,CAAC,CAAC,CAAC,CA2QvB"}

package/dist/hooks/useFocusTrap.js

@@ -200,10 +200,21 @@ function focusLastDescendant(container) {
  * ```
  */
 export function useFocusTrap(options) {
+  return useFocusTrapInternal(options);
+}
+
+/**
+ * Package-internal options. Not re-exported from the package entry point.
+ */
+
+export function useFocusTrapInternal(options) {
   const {
     isActive,
-    onEscape
+    onEscape,
+    getRestoreTarget
   } = options;
+  const getRestoreTargetRef = useRef(getRestoreTarget);
+  getRestoreTargetRef.current = getRestoreTarget;
   const containerRef = useRef(null);
   const lastFocusRef = useRef(null);
   // Track if focus change was triggered by keyboard (Tab key)
@@ -274,7 +285,7 @@ export function useFocusTrap(options) {
     // Snapshot the container now; by cleanup it may be detached or unmounted.
     const container = containerRef.current;
     const doc = trapDocument(container);
-    const previouslyFocused = doc.activeElement;
+    const previouslyFocused = getRestoreTargetRef.current?.() ?? doc.activeElement;
 
     // Whether focus ever entered the trap container while it was active.
     // Initialized from the current active element in case focus was already

package/dist/hooks/usePager.d.ts

@@ -0,0 +1,261 @@
+/**
+ * @file usePager.ts
+ * @input A viewport and its track, a page count and gap (or the track's
+ *   children), the gesture system and the animator
+ * @output Exports `createPager` (the framework-free pager), `usePager` (its
+ *   React face) and their types
+ * @position Shared hook for core components that page like a UIKit paging
+ *   scroll view, such as Carousel's paging presentation
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/usePager.test.ts
+ * - /packages/core/src/hooks/__tests__/usePager.interaction.browser.spec.ts
+ */
+import { type RefObject } from 'react';
+import { type GestureHost } from '../gestures/GestureHost.js';
+import { PanGestureRecognizer, type PanGestureRecognizerOptions } from '../gestures/PanGestureRecognizer.js';
+import { type Animator } from '../motion/animator.js';
+/** A release the pager settles: where the content is, how fast, and the page it left. */
+export interface PageRelease {
+    /** Content offset at the lift, px, or pages for children pages (may be past either end). */
+    position: number;
+    /** Content velocity at the release, px/s (the shared release velocity). */
+    velocity: number;
+    /** Distance between consecutive pages: page width plus the gap, px (1 for children pages). */
+    stride: number;
+    /** Number of pages (at least 1). */
+    count: number;
+    /** The page the drag started on (its rest position when the finger landed). */
+    startIndex: number;
+    /** Wraps around: the target may leave [0, count - 1] (the owner wraps it). */
+    loop?: boolean;
+}
+/**
+ * The page a release settles on. It applies UIKit's measured paging rule
+ * (`release` in uikit/paging.ts) through the release policy of
+ * resolveSnapPoint.ts, with the pager's own pages and thresholds.
+ *
+ * - A release at `advanceSpeed` or faster is a flick: it goes to the next page
+ *   in the direction of the velocity, from any content position.
+ * - A slower release goes to the page nearest the content. UIKit's measured
+ *   `commitFraction` is half a page, the policy's nearest snap point.
+ * - A release whose velocity points back toward the start page settles there,
+ *   at any travel, through the policy's `start`.
+ * - The page is never more than `maxPagesFromStart` from the start page
+ *   (`maxSteps`). It is clamped to the pages unless the pager loops.
+ * - The policy sees only the pages within that reach of the start page. So a
+ *   looping target may leave the range, and the owner wraps it.
+ *
+ * With children pages, positions are in pages, but the velocity stays px/s.
+ * The policy reads the velocity only against `advanceSpeed` and for its
+ * direction.
+ *
+ * @example
+ * ```
+ * // Released at rest 60 % of the way from page 1 to page 2: page 2.
+ * pageForRelease({position: 1.6 * 402, velocity: 0, stride: 402, count: 6, startIndex: 1});
+ * // Flicked forward at 600 px/s from 6 % past page 1: page 2.
+ * pageForRelease({position: 1.06 * 402, velocity: 600, stride: 402, count: 6, startIndex: 1});
+ * ```
+ */
+export declare function pageForRelease({ position, velocity, stride, count, startIndex, loop, }: PageRelease): number;
+/** Why the target page changed. */
+export type PagerChangeReason = 'drag' | 'goTo' | 'controlled';
+export interface PagerOptions {
+    /** Number of pages (at least 1). */
+    count: number;
+    /** Space between pages, px; it shows only while a page moves. @default 0 */
+    gap?: number;
+    /** Pages wrap around; indexes become unbounded. @default false */
+    loop?: boolean;
+    /**
+     * What a page is. With `'viewport'`, every page is the viewport's width, at
+     * index × (width + `gap`). With `'children'`, each child of the track is a
+     * page at its own start edge, as `scroll-snap-align: start` places it.
+     *
+     * With children pages, the viewport's padding stays an inset. The travel
+     * ends where the track's end meets the end of the viewport's content box. A
+     * child whose start lies past that point rests there, so the last children
+     * can share one page. The count is then the number of distinct pages
+     * (`pageCount`). `count` and `gap` serve only before the first measure, and
+     * children pages do not loop. The pager measures the children on attach, on
+     * a resize, on an options change and when a drag begins. It never measures
+     * while a finger moves.
+     * @default 'viewport'
+     */
+    pages?: 'viewport' | 'children';
+    /** Starting page. @default 0 */
+    defaultIndex?: number;
+    /**
+     * The target page changed (index wrapped into [0, count)). A release
+     * reports once its settle is moving; `index` has the page from the lift.
+     * A controlled move (the `index` prop, or a `count` that clamps the page)
+     * is the owner's own and is not reported.
+     */
+    onIndexChange?: (index: number, reason: PagerChangeReason) => void;
+    /**
+     * The track came to rest on `index` after moving on its own (a settle, a
+     * `goTo`), having last rested on `previous` (equal when it returned).
+     */
+    onSettle?: (index: number, previous: number) => void;
+    /**
+     * With `pages: 'children'`: a measure found different pages (how many, or
+     * where they rest) after the viewport or the track resized or the options
+     * changed. Not called for the measure an attach makes: read `pageCount`
+     * after attaching.
+     */
+    onPagesChange?: (pageCount: number) => void;
+    /**
+     * Called when the pan would begin, with the drag's first physical direction
+     * on screen, the same in RTL. Return false to leave the touch to someone
+     * else, such as a zoomed photo that can still pan that way.
+     */
+    shouldBeginPan?: (direction: 'left' | 'right') => boolean;
+    /** Constructor options for the pan (e.g. `allowedPointerTypes`). */
+    panOptions?: Partial<PanGestureRecognizerOptions>;
+}
+export interface GoToOptions {
+    /** Animate with `setContentOffset(_:animated:)`'s curve. @default true */
+    animated?: boolean;
+    /** @default 'goTo' */
+    reason?: PagerChangeReason;
+}
+export interface Pager {
+    /** The page pan, for failure requirements and simultaneity. */
+    readonly pan: PanGestureRecognizer;
+    /** The target page, wrapped into [0, count). */
+    readonly index: number;
+    /** The target page, unbounded when looping. */
+    readonly virtualIndex: number;
+    /**
+     * How many pages there are: `count`, or with `pages: 'children'` the
+     * distinct pages last measured.
+     */
+    readonly pageCount: number;
+    /** Whether the track is moving on its own (a settle or a `goTo`). */
+    readonly isSettling: boolean;
+    /** Whether a finger is dragging the track. */
+    readonly isDragging: boolean;
+    /** The content offset on screen right now, from the curve (px). */
+    presentation(): number;
+    /** Where page `index` rests (px). */
+    pageOffset(index: number): number;
+    /** The page whose rest is nearest content offset `position` (px). */
+    nearestPage(position: number): number;
+    /** Move to a page (wrapped to the nearest copy when looping). */
+    goTo(index: number, options?: GoToOptions): void;
+    /** Update options; a smaller count clamps the target page. */
+    setOptions(options: Partial<PagerOptions>): void;
+    /**
+     * Turns the page pan on or off (the hook's `isPanEnabled`). While it is off,
+     * a touch does not stop a settle or a `goTo`. A drag that it ends settles as
+     * a cancelled drag does. The callbacks of that settle wait for the next
+     * frame, so no callback runs inside the caller's update.
+     */
+    setPanEnabled(enabled: boolean): void;
+    /** Attach to the elements; returns a detach function. */
+    attach(viewport: HTMLElement, track: HTMLElement): () => void;
+    /** Detach and stop everything (attaching again restarts it). */
+    dispose(): void;
+}
+/**
+ * The copy of page `index` nearest virtual page `from`, in a loop of `count`
+ * pages. Two copies can be equally near: with two pages, or half an even
+ * count away. Then it is `index` itself when that is one of them, so a step
+ * to `from + 1` always goes forward.
+ */
+export declare function nearestLoopCopy(index: number, from: number, count: number): number;
+/** What a pager runs on; tests pass their own clocked host and animator. */
+export interface PagerEnvironment {
+    /** The gesture host; the document's shared host by default. */
+    host?: GestureHost;
+    /** The track's animator; `animatorFor(track)` by default. */
+    animator?: Animator;
+    /** Timers for the catch delay; the viewport's window's by default. */
+    setTimeout?: (callback: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+    /** The next animation frame; the viewport's window's by default. */
+    requestFrame?: (callback: () => void) => void;
+}
+/**
+ * Creates a pager: UIKit's paging scroll view, driven by the gesture system
+ * and played on the compositor. A native scroll-snap container does not run
+ * UIKit's paging integrator, and it cannot share a gesture with a pinch.
+ * Attach the pager to its viewport and track. It measures the page width on
+ * attach, on a resize and when a drag begins, never while a finger moves.
+ *
+ * - A horizontal pan moves the track 1:1, with one `translate` write per
+ *   move, no layout read and no React render. Past the first or last page,
+ *   the track follows UIKit's rubber band, with d = the page width.
+ * - At the lift, `pageForRelease` picks the page with UIKit's measured rule.
+ *   The track then settles on UIKit's paging integrator (`solvePaging`),
+ *   baked into keyframes.
+ * - A finger that lands on a settling pager catches it `paging.catchStopMs`
+ *   after the touch, as in UIKit. A drag catches it at once, from the value
+ *   on screen. While the pan is off, a touch does not stop the motion.
+ * - `goTo` runs the curve of `setContentOffset(_:animated:)` and cancels a
+ *   drag in progress. It reads that duration and curve through
+ *   `resolveMotion`.
+ * - Under Reduce Motion, the drag still follows the finger, but nothing
+ *   travels after the lift. A touch's release cross-fades in 200 ms on any
+ *   pointer. `goTo` and a mouse's or a pen's release cross-fade on a coarse
+ *   pointer, and land at once on any other.
+ * - `onIndexChange` reports a release's page once its settle runs on the
+ *   compositor, two frames after the frame it started in. It reports a
+ *   `goTo` at once, and never a controlled change. A report still waiting at
+ *   a detach or a controlled move is dropped. `onSettle` runs when the track
+ *   rests.
+ * - A detach ends a drag on its start page, and an unmount calls nothing.
+ *   When a replaced viewport or track attaches, a motion that the detach
+ *   stopped ends on its page. Its report and `onSettle` go out from a frame.
+ * - A controlled `index` wins. A page that the pager reports and the owner
+ *   does not take returns the pager to `index`, without a report.
+ * - The pan and the catch attach for every pointer. A mouse drags the track
+ *   as a finger does. The pan follows a trackpad's scroll along its axis, but
+ *   never a mouse wheel's.
+ * - A trackpad swipe moves the track at most one page from its start page.
+ *   A swipe that moves under a tenth of a page releases still, at any speed.
+ *   A swipe that lands during the last swipe's settle begins from that
+ *   settle's page.
+ *
+ * Positions are content offsets in px, 0 at page 0 and growing toward later
+ * pages. The track is translated by −position, or by +position in a
+ * right-to-left viewport. The owner renders the pages: all of them, a window,
+ * or a wrapped copy for a loop. With `loop`, indexes are unbounded, and
+ * `index` wraps them into [0, count).
+ *
+ * Give the current page and its neighbors their own layers
+ * (`will-change: transform`). Through a busy main thread, Mobile Safari moves
+ * the track but cannot paint new content, so part of a page that slides in
+ * stays blank. A page on its own layer is painted whole before it moves.
+ */
+export declare function createPager(initial: PagerOptions, environment?: PagerEnvironment): Pager;
+export interface UsePagerOptions extends PagerOptions {
+    /** The gesture surface: the clipped box the pages show through. */
+    viewportRef: RefObject<HTMLElement | null>;
+    /** The row of pages the pager translates. */
+    trackRef: RefObject<HTMLElement | null>;
+    /**
+     * Controlled target page; a change animates to it (reason 'controlled'),
+     * and a page the pager reports that the owner does not take returns it
+     * here.
+     */
+    index?: number;
+    /** Live toggle for the pan; turning it off mid-drag cancels the drag. */
+    isPanEnabled?: boolean;
+}
+/**
+ * A pager on two elements. Callbacks are read through a ref, so passing new
+ * functions each render costs nothing; a gesture never renders.
+ *
+ * @example
+ * ```
+ * const pager = usePager({viewportRef, trackRef, count: photos.length, gap: 40,
+ *   onIndexChange: setCounter});
+ * <div ref={viewportRef} style={{overflow: 'hidden'}}>
+ *   <div ref={trackRef} style={{display: 'flex', gap: 40}}>…pages…</div>
+ * </div>
+ * ```
+ */
+export declare function usePager({ viewportRef, trackRef, index, isPanEnabled, ...options }: UsePagerOptions): Pager;
+//# sourceMappingURL=usePager.d.ts.map

package/dist/hooks/usePager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePager.d.ts","sourceRoot":"","sources":["../../src/hooks/usePager.ts"],"names":[],"mappings":"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"}