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

package/dist/hooks/usePager.js

@@ -0,0 +1,1169 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @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 { useEffect, useRef, useState } from 'react';
+import { getGestureHost } from "../gestures/GestureHost.js";
+import { LongPressGestureRecognizer } from "../gestures/LongPressGestureRecognizer.js";
+import { useAttachmentPair } from "./useAttachment.js";
+import { lockSelection, locksSelectionFor } from "../gestures/selectionLock.js";
+import { PanGestureRecognizer } from "../gestures/PanGestureRecognizer.js";
+import { animatorFor } from "../motion/animator.js";
+import { pagingSettleVelocity, solveAnimatedPageScroll, solvePaging } from "../motion/paging.js";
+import { resolveMotion } from "../motion/resolveMotion.js";
+import { resolveSnapPoint } from "../motion/resolveSnapPoint.js";
+import { rubberBandClamp, rubberBandUnclamp } from "../motion/rubberBand.js";
+import { paging, registerPagingTable } from "../motion/uikit/paging.js";
+import { observeResize } from "../utils/sharedResizeObserver.js";
+import { isRtlElement } from "./isRtlElement.js";
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
+
+/** A release the pager settles: where the content is, how fast, and the page it left. */
+
+/**
+ * A pan or a screen-edge pan, told apart by its kind, never by its class.
+ */
+function isPanFamily(recognizer) {
+  return recognizer.kind === 'pan' || recognizer.kind === 'screenEdgePan';
+}
+
+/**
+ * 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 function pageForRelease({
+  position,
+  velocity,
+  stride,
+  count,
+  startIndex,
+  loop = false
+}) {
+  if (!(stride > 0) || count < 1) {
+    return 0;
+  }
+  const reach = paging.release.maxPagesFromStart;
+  // A stale start page past either end (the count shrank, an overscrolled
+  // track) counts from the nearest real page.
+  const from = loop ? startIndex : Math.min(Math.max(startIndex, 0), count - 1);
+  const first = loop ? from - reach : Math.max(0, from - reach);
+  const last = loop ? from + reach : Math.min(count - 1, from + reach);
+  const points = Array.from({
+    length: last - first + 1
+  }, (_, i) => (first + i) * stride);
+  const {
+    index
+  } = resolveSnapPoint({
+    points,
+    position,
+    velocity,
+    flickThreshold: paging.release.advanceSpeed,
+    // A hair of tolerance so a release exactly on a page reads as on it.
+    tolerance: 1e-6 * stride,
+    start: from * stride,
+    fromIndex: from - first,
+    maxSteps: reach
+  });
+  return first + index;
+}
+
+/** Why the target page changed. */
+
+/**
+ * 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 function nearestLoopCopy(index, from, count) {
+  if (Math.abs(index - from) * 2 <= count) {
+    return index;
+  }
+  return Math.round(from + ((mod(index, count) - mod(from, count) + count + count / 2) % count - count / 2));
+}
+
+/** Whether two measured page lists are the same to within half a pixel. */
+function sameOffsets(a, b) {
+  return b != null && a.length === b.length && a.every((offset, i) => Math.abs(offset - b[i]) < 0.5);
+}
+function mod(value, count) {
+  return (value % count + count) % count;
+}
+
+/** A position curve seen as the track's x (mirrored for LTR). */
+function toTrackCurve(curve, sign) {
+  // `+ 0` turns a mirrored zero (−0) into 0.
+  return {
+    duration: curve.duration,
+    at: t => sign * curve.at(t) + 0,
+    velocity: t => sign * curve.velocity(t) + 0
+  };
+}
+
+/** What a pager runs on; tests pass their own clocked host and animator. */
+
+/**
+ * The pager's pan. Its release velocity is the pan's `scrollVelocity()`, the
+ * one UIScrollView hands `scrollViewWillEndDragging`. Unlike UIKit's, it reads
+ * 0 after a still hold.
+ *
+ * Inside a scroll view, it takes UIKit's rule: a drag whose dominant axis is
+ * horizontal is the pager's (`paging.nestedPanAxisRatio`, the tie included).
+ * Any other drag is the page's. Like every pan, it cancels the touch's moves
+ * once it begins, at its 10 pt hysteresis. Nothing claims a touch earlier.
+ *
+ * Inside a sheet, it keeps the sheet's rule (`axisRatio`,
+ * `paging.panAxisRatio`). The arena shows the sheet as an enclosing vertical
+ * pan that takes part in the touch. Between atan(1 ÷ that ratio) and 45°,
+ * neither moves.
+ */
+class PagerPanGestureRecognizer extends PanGestureRecognizer {
+  /**
+   * The kind of pointer the pan follows. Under Reduce Motion a touch's
+   * release cross-fades; a mouse's or a pen's lands at once on a fine
+   * pointer.
+   */
+  pointerType = null;
+  touchesBegan(touches, event) {
+    if (this.state === 'possible' && touches.length > 0) {
+      this.pointerType = touches[0].pointerType;
+    }
+    super.touchesBegan(touches, event);
+  }
+  hasEnclosingVerticalPan() {
+    for (const other of this.arena?.involvedRecognizers ?? []) {
+      if (other !== this && isPanFamily(other) && (other.direction === 'vertical' || other.direction === 'up' || other.direction === 'down')) {
+        return true;
+      }
+    }
+    return false;
+  }
+  classify(translation) {
+    const decided = super.classify(translation);
+    if (decided !== 'wait' || this.hasEnclosingVerticalPan()) {
+      return decided;
+    }
+    const along = Math.abs(translation.x);
+    const across = Math.abs(translation.y);
+    if (along === 0 && across === 0) {
+      return 'wait';
+    }
+    return along >= paging.nestedPanAxisRatio * across ? 'begin' : 'fail';
+  }
+}
+
+/**
+ * The settle catcher: a zero-duration long press that only stops the settle.
+ * It never claims the touch. So a vertical swipe or a pinch that starts on a
+ * settling track still reaches the page. UIKit also hands the outer scroll
+ * view a vertical drag after the paging view's content stops.
+ */
+class SettleCatcher extends LongPressGestureRecognizer {
+  /** The kind of pointer that caught the settle (see the pager's pan). */
+  pointerType = null;
+  get claimsTouches() {
+    return false;
+  }
+  touchesBegan(touches, event) {
+    if (this.state === 'possible' && touches.length > 0) {
+      this.pointerType = touches[0].pointerType;
+    }
+    super.touchesBegan(touches, event);
+  }
+}
+
+/**
+ * A trackpad swipe that moved under this fraction of a page (in the pages'
+ * own spacing, children pages included) releases still, whatever its
+ * speed.
+ */
+const STILL_RELEASE_FRACTION = 0.1;
+
+/** Whether a pan's contact is a scroll (a trackpad's), not a pointer. */
+function isScrollContact(recognizer) {
+  return recognizer.trackedTouches[0]?.scrollType != null;
+}
+
+/**
+ * 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 function createPager(initial, environment = {}) {
+  registerPagingTable();
+  // Frames and timers come from the viewport's own window, known from the
+  // attach. In a Picture-in-Picture window, the opener's frames stop while
+  // its tab is hidden.
+  let view = null;
+  const realm = () => view ?? globalThis;
+  const setTimer = environment.setTimeout ?? ((callback, ms) => realm().setTimeout(callback, ms));
+  const clearTimer = environment.clearTimeout ?? (handle => realm().clearTimeout(handle));
+  const requestFrame = environment.requestFrame ?? (callback => {
+    const frames = realm();
+    if (typeof frames.requestAnimationFrame === 'function') {
+      frames.requestAnimationFrame(() => callback());
+    } else {
+      setTimer(callback, 16);
+    }
+  });
+  let options = {
+    ...initial
+  };
+  let viewport = null;
+  let trackElement = null;
+  let animator = null;
+  let pageWidth = 0;
+  let isRtl = false;
+  // With `pages: 'children'`, each page's offset (px, ascending), once
+  // measured.
+  let childOffsets = null;
+  const isChildPages = () => options.pages === 'children';
+  const isLooping = () => options.loop === true && !isChildPages();
+  const count = () => isChildPages() && childOffsets != null ? childOffsets.length : Math.max(1, Math.floor(options.count));
+  const stride = () => pageWidth + (options.gap ?? 0);
+  const sign = () => isRtl ? 1 : -1;
+  const clampIndex = index => isLooping() ? index : Math.max(0, Math.min(count() - 1, index));
+
+  /** Where page `index` rests (px). */
+  function offsetOf(index) {
+    if (isChildPages() && childOffsets != null) {
+      return childOffsets[Math.max(0, Math.min(childOffsets.length - 1, index))];
+    }
+    return index * stride();
+  }
+
+  /**
+   * Where `position` falls, in pages: an index plus the fraction of the way
+   * to the next page (past either end, in the end page's spacing).
+   */
+  function pageAt(position) {
+    if (!(isChildPages() && childOffsets != null)) {
+      return position / stride();
+    }
+    const at = childOffsets;
+    const n = at.length;
+    if (n === 1) {
+      return (position - at[0]) / (pageWidth > 0 ? pageWidth : 1);
+    }
+    if (position < at[0]) {
+      return (position - at[0]) / (at[1] - at[0]);
+    }
+    for (let i = 0; i < n - 1; i++) {
+      if (position < at[i + 1]) {
+        return i + (position - at[i]) / (at[i + 1] - at[i]);
+      }
+    }
+    return n - 1 + (position - at[n - 1]) / (at[n - 1] - at[n - 2]);
+  }
+
+  /** The page nearest `position`, or the target before anything is measured. */
+  function nearestPage(position) {
+    if (!isChildPages() && !(stride() > 0)) {
+      return target;
+    }
+    return Math.round(pageAt(position));
+  }
+
+  /**
+   * The page a release from `position` at `velocity` settles on (UIKit's
+   * rule, pageForRelease), in children pages' own spacing.
+   */
+  function releasePage(position, velocity, startIndex) {
+    const pages = isChildPages() && childOffsets != null;
+    return pageForRelease({
+      position: pages ? pageAt(position) : position,
+      velocity,
+      stride: pages ? 1 : stride(),
+      count: count(),
+      startIndex,
+      loop: isLooping()
+    });
+  }
+
+  /**
+   * Children pages: each child's start edge, from the track's start. The
+   * track's own translate moves both alike, so it cancels out. Each offset is
+   * clamped to the travel that keeps the track's end at or past the end of
+   * the viewport's content box. Children clamped onto one offset share its
+   * page.
+   *
+   * Rects are read in the track's own CSS pixels, which its `translate` moves
+   * in. An ancestor's `zoom` scales the rects, so the pager divides out that
+   * scale: the rect's width over the track's used width.
+   */
+  function measureChildOffsets() {
+    const track = trackElement;
+    if (viewport == null || track == null || track.children.length === 0) {
+      return [0];
+    }
+    const box = track.getBoundingClientRect();
+    const used = Number.parseFloat(getComputedStyle(track).width);
+    const scale = used > 0 && box.width > 0 ? box.width / used : 1;
+    const style = getComputedStyle(viewport);
+    const inner = viewport.clientWidth - (Number.parseFloat(style.paddingLeft) || 0) - (Number.parseFloat(style.paddingRight) || 0);
+    const starts = [];
+    let extent = 0;
+    for (const child of Array.from(track.children)) {
+      const rect = child.getBoundingClientRect();
+      starts.push((isRtl ? box.right - rect.right : rect.left - box.left) / scale);
+      extent = Math.max(extent, (isRtl ? box.right - rect.left : rect.right - box.left) / scale);
+    }
+    const end = Math.max(0, extent - inner);
+    const offsets = [];
+    for (const start of starts) {
+      const offset = Math.min(Math.max(start, 0), end);
+      if (offsets.length === 0 || offset > offsets[offsets.length - 1] + 0.5) {
+        offsets.push(offset);
+      }
+    }
+    return offsets.length > 0 ? offsets : [0];
+  }
+
+  // The page the track rests on or is heading for (unbounded when looping),
+  // and the one it last rested on.
+  let target = clampIndex(Math.round(options.defaultIndex ?? 0));
+  let settled = target;
+  let settleHandle = null;
+  let isSwipeSettle = false;
+  let settleToken = 0;
+  let isDragging = false;
+  let dragStart = 0;
+  let dragStartIndex = 0;
+  let dragPosition = 0;
+  let suppressCancelSettle = false;
+  let catchTimer = null;
+  // Whether the finger now holding the track stopped a settle (not one that
+  // ended on its own inside the catch window).
+  let caughtSettle = false;
+  const pan = new PagerPanGestureRecognizer({
+    ...options.panOptions,
+    // Published, so app code can relate its own recognizers to the paging
+    // pan (gesture delegates). Instances are told apart by their element.
+    name: options.panOptions?.name ?? 'pager',
+    direction: 'horizontal',
+    axisRatio: options.panOptions?.axisRatio ?? paging.panAxisRatio,
+    // On the web the pan follows a trackpad's scroll along its axis and never
+    // a mouse wheel's.
+    allowedScrollTypes: options.panOptions?.allowedScrollTypes ?? ['continuous'],
+    shouldBegin: recognizer => {
+      if (options.panOptions?.shouldBegin?.(recognizer) === false) {
+        return false;
+      }
+      const dx = recognizer.totalTranslation().x;
+      const direction = dx < 0 ? 'left' : 'right';
+      return options.shouldBeginPan?.(direction) ?? true;
+    }
+  });
+
+  // Catches a settling track when a finger lands on it. It begins on the
+  // touch itself, alongside the pan, only while the track moves on its own
+  // and the pan is on.
+  const catcher = new SettleCatcher({
+    minimumPressDuration: 0,
+    allowableMovement: Number.POSITIVE_INFINITY,
+    // Its own hold does nothing, so it brings no selection lock: a finger on
+    // a resting track keeps the browser's native long press. Stopping a
+    // settle does something; `holdSelection` locks then.
+    selectionLock: null,
+    shouldBegin: () => settleHandle != null && !isDragging && pan.isEnabled
+  });
+  catcher.recognizeSimultaneouslyWith(pan);
+  function positionToX(position) {
+    const x = sign() * position;
+    return x === 0 ? 0 : x;
+  }
+  function presentation() {
+    if (animator == null) {
+      return offsetOf(target);
+    }
+    return sign() * animator.get('x');
+  }
+  function clearCatchTimer() {
+    if (catchTimer != null) {
+      clearTimer(catchTimer);
+      catchTimer = null;
+    }
+  }
+  function stopSettle() {
+    clearCatchTimer();
+    flushReport();
+    isSwipeSettle = false;
+    if (settleHandle != null) {
+      settleToken += 1;
+      settleHandle = null;
+      animator?.stop(['x']);
+    }
+  }
+  function wrapped(index) {
+    return isLooping() ? mod(index, count()) : index;
+  }
+
+  // The owner passes its own updates (setOptions, a controlled goTo) from an
+  // Effect. The callbacks they cause run from a frame callback, never inside
+  // that Effect. There, a callback that sets state would update the owner
+  // during its own commit. A detach drops the callbacks still waiting.
+  let deferDepth = 0;
+  let deferred = [];
+  let deferredToken = 0;
+  function deliver(callback) {
+    if (deferDepth > 0) {
+      deferred.push(callback);
+    } else {
+      callback();
+    }
+  }
+  function deferringCallbacks(work) {
+    deferDepth += 1;
+    try {
+      work();
+    } finally {
+      deferDepth -= 1;
+      if (deferDepth === 0 && deferred.length > 0) {
+        const calls = deferred;
+        deferred = [];
+        const token = deferredToken;
+        requestFrame(() => {
+          if (token === deferredToken) {
+            for (const call of calls) {
+              call();
+            }
+          }
+        });
+      }
+    }
+  }
+  function dropDeferred() {
+    deferred = [];
+    deferredToken += 1;
+  }
+
+  // A release's report waits for its settle to reach the compositor.
+  let reported = wrapped(target);
+  let pendingReport = null;
+  let reportToken = 0;
+  function report(reason) {
+    pendingReport = null;
+    reportToken += 1;
+    const index = wrapped(target);
+    if (index !== reported) {
+      reported = index;
+      // A controlled move (the owner's `index`, or a `count` that clamps the
+      // page) is the owner's own change: it is not reported back.
+      if (reason !== 'controlled') {
+        deliver(() => options.onIndexChange?.(index, reason));
+      }
+    }
+  }
+  function flushReport() {
+    if (pendingReport != null) {
+      report(pendingReport);
+    }
+  }
+
+  /**
+   * Forgets a release's report still waiting: the pager is detaching, or the
+   * owner's own (controlled) move replaces the page it chose. The page last
+   * reported stays as it was.
+   */
+  function dropReport() {
+    pendingReport = null;
+    reportToken += 1;
+  }
+
+  /**
+   * A release reports its page once the settle reaches the compositor, two
+   * frames after the frame it started in. In Mobile Safari, a main-thread
+   * block that starts within about two frames of the touch freezes a motion
+   * that the touch's handler started. The owner's render of the new page is
+   * such a block. UIKit tells its delegate at the lift
+   * (`scrollViewWillEndDragging`), and the page is known then too (`index`).
+   */
+  function setTarget(next, reason, whenMoving = false) {
+    target = next;
+    if (whenMoving) {
+      pendingReport = reason;
+    } else {
+      report(reason);
+    }
+  }
+
+  /**
+   * Runs `callback` in the `frames`-th animation frame after the frame that a
+   * motion started in. Call it when the motion's start resolves.
+   *
+   * WebKit resolves an animation's start inside that frame's rendering
+   * update, before the frame's animation-frame callbacks. No task runs inside
+   * a rendering update. So a first frame that runs before a task queued at
+   * the resolution is the start's own frame, and it does not count.
+   * Timestamps cannot tell: WebKit stamps that frame's callbacks 0–4 ms after
+   * the animation's start time, as far apart as two frames at 240 Hz. Where
+   * the start resolves after its frame, as in Chromium, the task runs before
+   * the next frame. The report then comes a frame later, never earlier.
+   */
+  function afterFramesPastStart(frames, callback) {
+    let isPastStartFrame = false;
+    setTimer(() => {
+      isPastStartFrame = true;
+    }, 0);
+    const onFrame = left => {
+      const remaining = isPastStartFrame ? left - 1 : left;
+      isPastStartFrame = true;
+      if (remaining <= 0) {
+        callback();
+        return;
+      }
+      requestFrame(() => onFrame(remaining));
+    };
+    requestFrame(() => onFrame(frames));
+  }
+  function rest() {
+    flushReport();
+    isSwipeSettle = false;
+    const previous = wrapped(settled);
+    settled = target;
+    const index = wrapped(settled);
+    deliver(() => options.onSettle?.(index, previous));
+  }
+
+  /**
+   * Plays `curve` on the track. Under Reduce Motion, the animator replaces the
+   * travel. A settle that a touch's release starts (`touchRelease`)
+   * cross-fades on any pointer. Any other motion, such as `goTo` or a mouse's
+   * or a pen's release, cross-fades on a coarse pointer. It lands at once on
+   * any other pointer.
+   */
+  function play(curve, touchRelease = false) {
+    isSwipeSettle = false;
+    if (animator == null) {
+      return;
+    }
+    follow(animator.play({
+      x: toTrackCurve(curve, sign())
+    }, {
+      touchRelease
+    }));
+  }
+  function follow(handle) {
+    const token = ++settleToken;
+    settleHandle = handle;
+    if (pendingReport != null) {
+      const reportAt = reportToken;
+      void handle.started.then(() => afterFramesPastStart(2, () => {
+        if (reportAt === reportToken) {
+          flushReport();
+        }
+      }));
+    }
+    void handle.finished.then(finished => {
+      if (token !== settleToken) {
+        return;
+      }
+      settleHandle = null;
+      if (finished) {
+        rest();
+      }
+    });
+  }
+
+  /**
+   * The settle after a pointer lifts (a release, or a hold let go);
+   * `touchRelease` when that pointer was a touch.
+   */
+  function settleFrom(position, velocity, touchRelease) {
+    const to = offsetOf(target);
+    // UIKit's integrator, as a playable curve (touch motion stays internal).
+    const curve = solvePaging({
+      from: position,
+      velocity,
+      to
+    });
+    if (curve.steps === 0) {
+      animator?.set({
+        x: positionToX(to)
+      });
+      rest();
+      return;
+    }
+    play(curve, touchRelease);
+  }
+  function measure() {
+    if (viewport == null) {
+      return;
+    }
+    const width = viewport.clientWidth;
+    const rtl = isRtlElement(viewport);
+    // A new writing direction mirrors the track, so it re-places it too.
+    let changed = width !== pageWidth || rtl !== isRtl;
+    isRtl = rtl;
+    pageWidth = width;
+    if (isChildPages()) {
+      const offsets = measureChildOffsets();
+      if (!sameOffsets(offsets, childOffsets)) {
+        childOffsets = offsets;
+        changed = true;
+        const pageCount = offsets.length;
+        deliver(() => options.onPagesChange?.(pageCount));
+      }
+    }
+    if (!changed) {
+      return;
+    }
+    if (!isDragging && !isLooping() && target > count() - 1) {
+      // Fewer pages (children clamped onto one): the last one, as a smaller
+      // count clamps. A loop's target is unbounded, so it keeps it.
+      goTo(count() - 1, {
+        animated: false,
+        reason: 'controlled'
+      });
+      return;
+    }
+    // A resize lands on the target page at its new offset (a settle in
+    // flight ends there), as a paging scroll view does on rotation. A finger
+    // that holds a caught track keeps it; its lift settles on the new offsets.
+    if (!isDragging && !caughtSettle) {
+      stopSettle();
+      animator?.set({
+        x: positionToX(offsetOf(target))
+      });
+      if (settled !== target) {
+        rest();
+      }
+    }
+  }
+  function onPan(recognizer) {
+    const state = recognizer.state;
+    if (state === 'began') {
+      // Read before measure(), which can stop the settle on a resize.
+      const wasSwipeSettle = settleHandle != null && isSwipeSettle;
+      measure();
+      clearCatchTimer();
+      const current = presentation();
+      stopSettle();
+      isDragging = true;
+      // A track caught past an end is shown rubber-banded: the drag starts
+      // from its unbanded position, so the first move keeps it under the
+      // finger.
+      dragStart = isLooping() ? current : rubberBandUnclamp(current, offsetOf(0), offsetOf(count() - 1), pageWidth > 0 ? pageWidth : 1);
+      dragPosition = current;
+      // A trackpad swipe that lands while the last swipe's settle runs
+      // begins from that settle's page, so back-to-back swipes page on. Any
+      // other motion, such as a goTo, hands over the page on screen.
+      dragStartIndex = wasSwipeSettle && isScrollContact(recognizer) ? target : nearestPage(current);
+      return;
+    }
+    if (state === 'changed') {
+      const dx = recognizer.translation().x;
+      // Finger right (dx > 0) moves content toward earlier pages in LTR.
+      let raw = dragStart + sign() * dx;
+      if (isScrollContact(recognizer) && pageWidth > 0) {
+        // A trackpad swipe moves the track at most one page from its start
+        // page, across a loop too. The window also holds where the swipe
+        // began, so a swipe that catches a longer move starts from the
+        // screen. A pager that does not loop keeps the rubber band of its
+        // first and last pages below.
+        const looping = isLooping();
+        const before = looping || dragStartIndex > 0 ? offsetOf(dragStartIndex - 1) : -Infinity;
+        const after = looping || dragStartIndex < count() - 1 ? offsetOf(dragStartIndex + 1) : Infinity;
+        raw = Math.min(Math.max(raw, Math.min(before, after, dragStart)), Math.max(before, after, dragStart));
+      }
+      dragPosition = isLooping() ? raw : rubberBandClamp(raw, offsetOf(0), offsetOf(count() - 1), pageWidth > 0 ? pageWidth : 1);
+      animator?.set({
+        x: positionToX(dragPosition)
+      });
+      return;
+    }
+    if (state === 'ended' || state === 'cancelled') {
+      isDragging = false;
+      if (state === 'cancelled' && suppressCancelSettle) {
+        suppressCancelSettle = false;
+        return;
+      }
+      // A still finger releases at 0, where UIScrollView keeps the speed.
+      let velocity = state === 'ended' ? sign() * recognizer.scrollVelocity().x : 0;
+      // A trackpad swipe that moved under a tenth of a page from where it
+      // began, in the pages' own spacing, releases still at any speed. Such a
+      // speed spike is not a flick. A finger's and a mouse's flick keep their
+      // speed.
+      if (isScrollContact(recognizer) && Math.abs(pageAt(dragPosition) - pageAt(dragStart)) < STILL_RELEASE_FRACTION) {
+        velocity = 0;
+      }
+      const next = releasePage(dragPosition, velocity, dragStartIndex);
+      setTarget(next, 'drag', true);
+      settleFrom(dragPosition, pagingSettleVelocity(velocity), pan.pointerType === 'touch');
+      isSwipeSettle = settleHandle != null && isScrollContact(recognizer);
+    }
+  }
+
+  // While a finger holds a caught track, the browser's long-press text
+  // selection and callout stay off. In UIKit, the touch that stops a scroll
+  // view does not reach its content. The gesture system's shared lock is
+  // counted per element. So this lock and the gesture host's own lock for the
+  // same contact release in either order.
+  let releaseSelection = null;
+  function holdSelection(on) {
+    if (on && releaseSelection == null && trackElement != null) {
+      if (locksSelectionFor(catcher.pointerType ?? 'touch')) {
+        releaseSelection = lockSelection([trackElement], null);
+      }
+    } else if (!on && releaseSelection != null) {
+      releaseSelection();
+      releaseSelection = null;
+    }
+  }
+  function onCatch(recognizer) {
+    if (recognizer.state === 'began') {
+      holdSelection(true);
+      clearCatchTimer();
+      caughtSettle = false;
+      catchTimer = setTimer(() => {
+        catchTimer = null;
+        if (settleHandle != null && !isDragging) {
+          stopSettle();
+          caughtSettle = true;
+        }
+      }, paging.catchStopMs);
+      return;
+    }
+    if (recognizer.state === 'ended' || recognizer.state === 'cancelled') {
+      holdSelection(false);
+      if (catchTimer != null) {
+        // Lifted before the catch took hold: the settle runs on.
+        clearCatchTimer();
+        return;
+      }
+      const wasCaught = caughtSettle;
+      caughtSettle = false;
+      if (wasCaught && !isDragging && settleHandle == null && animator != null) {
+        // Held, then lifted without dragging: settle on the nearest page.
+        const position = presentation();
+        const next = releasePage(position, 0, nearestPage(position));
+        setTarget(next, 'drag', true);
+        settleFrom(position, 0, catcher.pointerType === 'touch');
+      }
+    }
+  }
+  function goTo(index, goToOptions = {}) {
+    if (goToOptions.reason === 'controlled' && deferDepth === 0) {
+      // The owner's own move: what it calls back waits for a frame.
+      deferringCallbacks(() => goTo(index, goToOptions));
+      return;
+    }
+    const {
+      animated = true,
+      reason = 'goTo'
+    } = goToOptions;
+    let next = Math.round(index);
+    if (isLooping()) {
+      next = nearestLoopCopy(next, target, count());
+    } else {
+      next = clampIndex(next);
+    }
+    if (isDragging) {
+      suppressCancelSettle = true;
+      isDragging = false;
+      pan.cancel();
+    }
+    const from = presentation();
+    // A move this one retargets hands on its velocity, from its curve.
+    const velocity = settleHandle != null && animator != null ? sign() * animator.getVelocity('x') : undefined;
+    if (reason === 'controlled') {
+      dropReport();
+    }
+    stopSettle();
+    setTarget(next, reason);
+    const to = offsetOf(next);
+    if (!animated || animator == null || from === to) {
+      animator?.set({
+        x: positionToX(to)
+      });
+      rest();
+      return;
+    }
+    play(solveAnimatedPageScroll({
+      from,
+      to,
+      durationMs: resolveMotion(trackElement, paging.animatedScroll, 'durationMs'),
+      curve: resolveMotion(trackElement, paging.animatedScroll.curve),
+      velocity
+    }));
+  }
+  function setOptions(update) {
+    deferringCallbacks(() => applyOptions(update));
+  }
+  function applyOptions(update) {
+    const wasLooping = isLooping();
+    const wasChildPages = isChildPages();
+    const previousCount = count();
+    const previousOffset = offsetOf(target);
+    // A loop's indexes are unbounded. So the page shown and the page last at
+    // rest are read under the old count, before the options change.
+    const shownBefore = wasLooping ? mod(target, previousCount) : target;
+    const settledBefore = wasLooping ? mod(settled, previousCount) : settled;
+    options = {
+      ...options,
+      ...update
+    };
+    if (isChildPages() !== wasChildPages) {
+      syncTrackObserver();
+    }
+    if (isChildPages() && viewport != null && !isDragging) {
+      // The children may have changed with the options (a count, a gap).
+      const offsets = measureChildOffsets();
+      if (!sameOffsets(offsets, childOffsets)) {
+        childOffsets = offsets;
+        const pageCount = offsets.length;
+        deliver(() => options.onPagesChange?.(pageCount));
+      }
+    }
+    if ((wasLooping || isLooping()) && (wasLooping !== isLooping() || count() !== previousCount)) {
+      if (target < 0 || target > Math.min(previousCount, count()) - 1) {
+        rewrap(shownBefore, settledBefore);
+        return;
+      }
+      // The target's slot shows the same page. Only the page last at rest
+      // can be a virtual index, so it is read under the old count.
+      settled = settledBefore;
+    }
+    if (!isLooping() && (target < 0 || target > count() - 1)) {
+      // A smaller `count` clamps.
+      goTo(clampIndex(target), {
+        animated: false,
+        reason: 'controlled'
+      });
+      return;
+    }
+    if (offsetOf(target) !== previousOffset && !isDragging) {
+      // A new gap (or children): the target page at its new offset (a settle
+      // ends there).
+      const wasSettling = settleHandle != null;
+      stopSettle();
+      animator?.set({
+        x: positionToX(offsetOf(target))
+      });
+      if (wasSettling || settled !== target) {
+        rest();
+      }
+    }
+  }
+
+  /**
+   * Turning `loop` off, or a loop's new count, where the target's slot now
+   * shows another page. The page shown keeps its index, and a smaller count
+   * clamps it. A release's waiting report names its page under the old count.
+   * It reaches the owner only while that page exists.
+   */
+  function rewrap(shownBefore, settledBefore) {
+    const next = Math.min(shownBefore, count() - 1);
+    const waiting = pendingReport;
+    pendingReport = null;
+    if (isDragging) {
+      suppressCancelSettle = true;
+      isDragging = false;
+      pan.cancel();
+    }
+    const wasSettling = settleHandle != null;
+    stopSettle();
+    if (waiting != null && shownBefore === next) {
+      target = next;
+      report(waiting);
+    }
+    setTarget(next, 'controlled');
+    animator?.set({
+      x: positionToX(offsetOf(next))
+    });
+    settled = next;
+    if (wasSettling || settledBefore !== next) {
+      deliver(() => options.onSettle?.(next, settledBefore));
+    }
+  }
+  let detachAll = null;
+  // What a detach carries to the next attach: a release's report that still
+  // waits, and whether the detach stopped a motion before the track rested.
+  let carriedReport = null;
+  let carriedEnd = false;
+
+  // Children pages also move when the track's own size changes, as when a
+  // child is added, removed or resized. So the track is observed while the
+  // pages are its children, from the attach or the options change that makes
+  // them so.
+  let unobserveTrack = () => {};
+  function syncTrackObserver() {
+    unobserveTrack();
+    unobserveTrack = isChildPages() && trackElement != null && detachAll != null ? observeResize(trackElement, measure) : () => {};
+  }
+  function attach(nextViewport, nextTrack) {
+    detachAll?.();
+    view = nextViewport.ownerDocument.defaultView;
+    viewport = nextViewport;
+    trackElement = nextTrack;
+    animator = environment.animator ?? animatorFor(nextTrack);
+    pageWidth = 0;
+    isRtl = isRtlElement(nextViewport);
+    pageWidth = nextViewport.clientWidth;
+    if (isChildPages()) {
+      childOffsets = measureChildOffsets();
+      target = clampIndex(target);
+      settled = target;
+    }
+    animator.set({
+      x: positionToX(offsetOf(target))
+    });
+    // No pointer check: a mouse and a trackpad page it too.
+    const removePanListener = pan.addListener(onPan);
+    const removeCatchListener = catcher.addListener(onCatch);
+    const host = environment.host ?? getGestureHost(nextViewport.ownerDocument);
+    const detachPan = host.attach(nextViewport, pan);
+    // The catcher sits on the track, so its long-press styles (no callout, no
+    // selection) stay off the pages' text. The viewport's touch-action
+    // already covers the touches that land on the track.
+    const detachCatch = host.attach(nextTrack, catcher, {
+      manageStyle: false
+    });
+    const detachGestures = () => {
+      detachCatch();
+      detachPan();
+      removeCatchListener();
+      removePanListener();
+    };
+    const unobserve = observeResize(nextViewport, measure);
+    detachAll = () => {
+      unobserve();
+      unobserveTrack();
+      unobserveTrack = () => {};
+      // A drag that the detach ends stays on its start page. The report and
+      // the end of a motion that the detach stops wait for the next attach,
+      // so an unmount calls nothing.
+      if (isDragging) {
+        suppressCancelSettle = true;
+      }
+      deferringCallbacks(() => detachGestures());
+      suppressCancelSettle = false;
+      carriedReport = pendingReport;
+      carriedEnd = target !== settled;
+      dropReport();
+      stopSettle();
+      dropDeferred();
+      holdSelection(false);
+      isDragging = false;
+      detachAll = null;
+    };
+    syncTrackObserver();
+    // A motion that the last detach stopped ends here: its report, if it
+    // still waited, and its onSettle go out from a frame.
+    if (carriedEnd && target !== settled) {
+      const report = carriedReport;
+      deferringCallbacks(() => {
+        pendingReport = report;
+        rest();
+      });
+    }
+    carriedReport = null;
+    carriedEnd = false;
+    return () => detachAll?.();
+  }
+  return {
+    pan,
+    get index() {
+      return wrapped(target);
+    },
+    get virtualIndex() {
+      return target;
+    },
+    get pageCount() {
+      return count();
+    },
+    get isSettling() {
+      return settleHandle != null;
+    },
+    get isDragging() {
+      return isDragging;
+    },
+    presentation,
+    pageOffset: offsetOf,
+    nearestPage: position => clampIndex(nearestPage(position)),
+    goTo,
+    setOptions,
+    setPanEnabled(enabled) {
+      deferringCallbacks(() => pan.setEnabled(enabled));
+    },
+    attach,
+    dispose() {
+      detachAll?.();
+    }
+  };
+}
+/**
+ * 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 function usePager({
+  viewportRef,
+  trackRef,
+  index,
+  isPanEnabled = true,
+  ...options
+}) {
+  const latestRef = useRef(options);
+  // The controlled `index` of the last commit, read when the pager reports.
+  const indexRef = useRef(index);
+  // Syncs the callback and controlled-index refs with the newest render; the
+  // pager's callbacks read them.
+  useIsomorphicLayoutEffect(() => {
+    latestRef.current = options;
+    indexRef.current = index;
+  });
+  // Bumped when the pager reports a page while `index` is controlled. The
+  // render it causes is batched with the owner's own update. If the owner kept
+  // `index`, that render returns the pager to it (the controlled sync below).
+  const [reported, setReported] = useState(0);
+  const [pager] = useState(() => createPager({
+    ...options,
+    defaultIndex: index ?? options.defaultIndex,
+    onIndexChange: (i, reason) => {
+      latestRef.current.onIndexChange?.(i, reason);
+      if (indexRef.current != null) {
+        setReported(n => n + 1);
+      }
+    },
+    onSettle: (i, previous) => latestRef.current.onSettle?.(i, previous),
+    onPagesChange: pageCount => latestRef.current.onPagesChange?.(pageCount),
+    shouldBeginPan: direction => latestRef.current.shouldBeginPan?.(direction) ?? true
+  }));
+
+  // Synchronizes the pager (the track's animation and the gesture host) with
+  // these props. A clamp it causes is not reported back (reason 'controlled').
+  const {
+    count,
+    gap,
+    loop,
+    pages
+  } = options;
+  useIsomorphicLayoutEffect(() => {
+    pager.setOptions({
+      count,
+      gap,
+      loop,
+      pages
+    });
+  }, [pager, count, gap, loop, pages]);
+
+  // Attaches the pager to the viewport and track nodes, and again whenever
+  // either node is replaced; detaches at unmount.
+  useAttachmentPair(viewportRef, trackRef, (viewport, track) => pager.attach(viewport, track), pager);
+
+  // Synchronizes the pan recognizer (the gesture host) with isPanEnabled; what
+  // a drag it ends calls back waits for the next frame, after this Effect.
+  useEffect(() => {
+    pager.setPanEnabled(isPanEnabled);
+  }, [pager, isPanEnabled]);
+
+  // Synchronizes the pager, an imperative system outside React (the track's
+  // animation and its gesture recognizers), with a controlled `index`. A new
+  // `index` moves the pager there. So does the render after a page that it
+  // reported and the owner did not take, such as a refused swipe. A
+  // controlled input returns to its value the same way. The move is the
+  // owner's own, so it is not reported back. It moves only while the two
+  // differ.
+  useEffect(() => {
+    if (index != null && index !== pager.index) {
+      pager.goTo(index, {
+        reason: 'controlled'
+      });
+    }
+  }, [pager, index, reported]);
+  return pager;
+}