@astryxdesign/core 0.7.7-canary.550ff21 → 0.7.7-canary.58c5b8a

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":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA8B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAClE,OAAO,EAAiB,KAAK,WAAW,EAAC,MAAM,yBAAyB,CAAC;AAKzE,OAAO,EACL,oBAAoB,EACpB,KAAK,2BAA2B,EACjC,MAAM,kCAAkC,CAAC;AAO1C,OAAO,EAEL,KAAK,QAAQ,EAGd,MAAM,oBAAoB,CAAC;AAc5B,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAWD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wBAAgB,cAAc,CAAC,EAC7B,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,KAAK,EACL,UAAU,EACV,IAAY,GACb,EAAE,WAAW,GAAG,MAAM,CA0BtB;AAED,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,YAAY,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IAChC,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnE;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,KAAK,OAAO,CAAC;IAC1D,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sBAAsB;IACtB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,KAAK;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,oBAAoB,CAAC;IACnC,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,mEAAmE;IACnE,YAAY,IAAI,MAAM,CAAC;IACvB,qCAAqC;IACrC,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,qEAAqE;IACrE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IACtC,iEAAiE;IACjE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD,8DAA8D;IAC9D,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;IACjD;;;;;OAKG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,yDAAyD;IACzD,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,GAAG,MAAM,IAAI,CAAC;IAC9D,gEAAgE;IAChE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,MAAM,CASR;AA4BD,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3D,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,oEAAoE;IACpE,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CAC/C;AAqGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,YAAY,EACrB,WAAW,GAAE,gBAAqB,GACjC,KAAK,CAm3BP;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,mEAAmE;IACnE,WAAW,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC3C,6CAA6C;IAC7C,QAAQ,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACxC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,EACvB,WAAW,EACX,QAAQ,EACR,KAAK,EACL,YAAmB,EACnB,GAAG,OAAO,EACX,EAAE,eAAe,GAAG,KAAK,CAmEzB"}