Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
21.1 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file SnapPaging.ts
 * @input The shared pager, each child's own animator and the
 *   writing-direction read
 * @output `useSnapPaging`: UIKit paging on Carousel's row of snap items, under
 *   a finger and on a trackpad swipe, for every pointer
 * @position Public, from `@astryxdesign/core/SnapPaging` and the root. The
 *   only module that brings the pager to Carousel
 */

import {useRef, useState} from 'react';
import {createPager, type PagerAnimator} from '../hooks/usePager';
import {isRtlElement} from '../hooks/isRtlElement';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {
  animatorFor,
  type MotionCurve,
  type MotionHandle,
} from '../motion/animator';
import {observeMutations} from '../utils/sharedMutationObserver';
import {observeResize} from '../utils/sharedResizeObserver';
import {
  type HeldRowListener,
  itemsSpan,
  makeSnapPaging,
  rowScale,
  type SnapPages,
  type SnapPaging,
  type SnapPagingAttachment,
  type SnapPagingOptions,
  snapPages,
} from './snapPagingValue';

export type {SnapPaging, SnapPagingOptions} from './snapPagingValue';

/**
 * Snap paging for Carousel: `<Carousel hasSnap={useSnapPaging()}>`. Carousel
 * attaches the value to its scroll area. A flick moves one view by default, or
 * one item with `{pages: 'item'}`. The same value lasts for the component's
 * life, so a render attaches nothing again; a new `pages` applies from the
 * next flick.
 *
 * @example
 * ```
 * <Carousel hasSnap={useSnapPaging({pages: 'item'})}>{cards}</Carousel>
 * ```
 */
export function useSnapPaging(options: SnapPagingOptions = {}): SnapPaging {
  const optionsRef = useRef(options);
  // Syncs optionsRef with the committed render, so a new `pages` applies from
  // the next flick. It is written at commit: a render that React discards
  // must not leave its options behind.
  useIsomorphicLayoutEffect(() => {
    optionsRef.current = options;
  });
  const [value] = useState(() => {
    const live: SnapPagingOptions = {
      get pages() {
        return optionsRef.current.pages;
      },
    };
    return makeSnapPaging((element, onHeld) =>
      attachPaging(element, live, onHeld),
    );
  });
  return value;
}

/**
 * The view pages from stop `anchor`. Each lies on the stop nearest one view
 * on from the last, and at least one stop on.
 */
function viewPages(
  stops: ReadonlyArray<number>,
  anchor: number,
  width: number,
): number[] {
  const nearest = (to: number) => {
    let best = 0;
    for (let i = 1; i < stops.length; i++) {
      if (Math.abs(stops[i] - to) < Math.abs(stops[best] - to)) {
        best = i;
      }
    }
    return best;
  };
  const pages = [stops[anchor]];
  for (let i = anchor; i < stops.length - 1;) {
    i = Math.max(nearest(stops[i] + width), i + 1);
    pages.push(stops[i]);
  }
  for (let i = anchor; i > 0;) {
    i = Math.min(nearest(stops[i] - width), i - 1);
    pages.unshift(stops[i]);
  }
  return pages;
}

/**
 * How often a settle's curve is read to find how far it moves the row. Its
 * extremes lie at its ends, which are read exactly, or where it turns and
 * moves slowly.
 */
const SHOWS_SAMPLES_PER_S = 120;

/** One handle for the same motion on every child. */
function combined(handles: ReadonlyArray<MotionHandle>): MotionHandle {
  const [lead] = handles;
  return {
    properties: lead.properties,
    finished: Promise.all(handles.map(async handle => handle.finished)).then(
      results => results.every(Boolean),
    ),
    started: lead.started,
    value: (property, time) => lead.value(property, time),
    velocity: (property, time) => lead.velocity(property, time),
    curve: property => lead.curve(property),
    retarget: (to, transition, options) =>
      combined(handles.map(handle => handle.retarget(to, transition, options))),
    stop: () => {
      for (const handle of handles) {
        handle.stop();
      }
    },
  };
}

/**
 * The track the pager moves. At rest the row scrolls natively, and the
 * position is its scroll offset. A gesture takes the row over: its scroll
 * offset holds, and every child moves by the same translate from there. The
 * settle hands the position back to native scrolling.
 */
function childTrack(element: HTMLElement, onHeld?: HeldRowListener) {
  let isMoving = false;
  let heldOffset = 0;
  let heldTravel = 0;
  // The direction and the lead child, read at the takeover, so a frame of the
  // hold reads no style or layout.
  let heldSign = 1;
  let lead: HTMLElement | null = null;
  let followFrame = 0;
  // The row's travel, the children's span and the row's width at the
  // takeover. A resize while the row is held moves the travel by the change in
  // span and width.
  let takeoverTravel = 0;
  let heldSpan = 0;
  let heldWidth = 0;
  // The row's own inline snap type, back at the hand-back.
  let ownSnapType = '';
  // Each child's start and end along the row, in the position's terms, and
  // the row's outer width, read at the takeover.
  let spans: {start: number; end: number}[] = [];
  let heldOuterWidth = 0;
  // The children the running settle leaves out. Each keeps the translate it
  // had when the settle began.
  let leftOut: HTMLElement[] = [];
  const children = () =>
    Array.from(element.children).filter(
      (child): child is HTMLElement => child instanceof HTMLElement,
    );
  const isRtl = () => isRtlElement(element);
  // The pager's x for a position, and what a child's translate adds to it. A
  // held row keeps the direction it was taken over with.
  const sign = () => (isMoving ? heldSign : isRtl() ? -1 : 1);
  const xOf = (position: number) => -sign() * position;
  const nativePosition = () => Math.abs(element.scrollLeft);
  const padding = () => {
    const style = getComputedStyle(element);
    const left = Number.parseFloat(style.scrollPaddingLeft) || 0;
    const right = Number.parseFloat(style.scrollPaddingRight) || 0;
    return isRtl() ? {start: right, end: left} : {start: left, end: right};
  };
  const toChild = (x: number) => x + sign() * heldOffset;

  function position(): number {
    const first = children()[0];
    if (!isMoving || first == null) {
      return nativePosition();
    }
    return -sign() * (animatorFor(first).get('x') - sign() * heldOffset);
  }

  // Reports where the held row is shown, once a frame, from the lead child's
  // own animator.
  function follow(): void {
    if (onHeld == null || !isMoving) {
      return;
    }
    const offset =
      lead == null
        ? heldOffset
        : -heldSign * (animatorFor(lead).get('x') - heldSign * heldOffset);
    onHeld({offset, travel: heldTravel});
    followFrame = requestAnimationFrame(follow);
  }

  function span(): number {
    return itemsSpan(element, isMoving);
  }

  // Each child's start and end along the row, in the position's terms, with
  // the row shown at `at`. Every child carries the same translate.
  function spansOf(
    items: ReadonlyArray<HTMLElement>,
    at: number,
  ): {start: number; end: number}[] {
    const box = element.getBoundingClientRect();
    const scale = rowScale(element, box);
    const rtl = isRtl();
    return items.map(child => {
      const rect = child.getBoundingClientRect();
      const start =
        (rtl ? box.right - rect.right : rect.left - box.left) / scale + at;
      return {start, end: start + rect.width / scale};
    });
  }

  // A child the settle left out takes the lead's translate before a
  // measure. Its box then reads as the other children's do.
  function alignLeftOut(): void {
    const first = children()[0];
    if (leftOut.length === 0 || first == null) {
      return;
    }
    const x = animatorFor(first).get('x');
    for (const child of leftOut) {
      const animator = animatorFor(child);
      if (animator.get('x') !== x) {
        animator.set({x});
      }
    }
    leftOut = [];
  }

  // A resize while the row is held moves its travel with the row's width and
  // the children's span. A frame of the hold reads the result, not the row.
  function remeasure(): void {
    if (!isMoving) {
      return;
    }
    alignLeftOut();
    const nextSpan = span();
    const nextWidth = element.clientWidth;
    const native = nativePosition();
    spans = spansOf(children(), position());
    heldOuterWidth = element.offsetWidth;
    // WebKit truncates a fractional scroll offset, so the travel stays a whole
    // number of pixels, as the scroll width is. It rounds once, from the
    // takeover, so a resize over many frames adds up no rounding.
    heldTravel = Math.max(
      0,
      Math.round(
        takeoverTravel + (nextSpan - heldSpan) - (nextWidth - heldWidth),
      ),
    );
    // A shorter travel clamps the row's own scroll offset. The children take
    // up the clamp, so the row still shows where the pager holds it.
    if (native !== heldOffset) {
      const at = position();
      heldOffset = native;
      place(at);
    }
  }

  // A held row's translate widens its overflow, so its travel is the one it
  // was taken over with, moved by any resize since.
  function travel(): number {
    return isMoving
      ? heldTravel
      : Math.max(0, element.scrollWidth - element.clientWidth);
  }

  function pages(): SnapPages {
    return snapPages(element, nativePosition(), travel(), isMoving);
  }

  function stops(): number[] {
    alignLeftOut();
    return pages().stops;
  }

  function viewWidth(): number {
    const {start, end} = padding();
    return Math.max(1, element.clientWidth - start - end);
  }

  function place(at: number): void {
    const x = toChild(xOf(at));
    for (const child of children()) {
      const animator = animatorFor(child);
      // A set reads the element's style back, so a child already there
      // gets none.
      if (animator.get('x') !== x) {
        animator.set({x});
      }
    }
  }

  function takeOver(): void {
    if (isMoving) {
      return;
    }
    // Every read comes before the first write, so the takeover forces no
    // layout of its own.
    const offset = nativePosition();
    const rowTravel = Math.max(0, element.scrollWidth - element.clientWidth);
    const rowSign = isRtl() ? -1 : 1;
    const items = children();
    const rowSpan = span();
    const rowWidth = element.clientWidth;
    const itemSpans = spansOf(items, offset);
    heldOffset = offset;
    heldTravel = rowTravel;
    takeoverTravel = rowTravel;
    heldSpan = rowSpan;
    heldWidth = rowWidth;
    heldSign = rowSign;
    heldOuterWidth = element.offsetWidth;
    spans = itemSpans;
    lead = items[0] ?? null;
    isMoving = true;
    // A snap type would snap the row again as its children move.
    ownSnapType = element.style.getPropertyValue('scroll-snap-type');
    element.style.setProperty('scroll-snap-type', 'none');
    // Each child's animator gives it a layer while it moves and takes the layer
    // away after the motion. So the takeover writes no will-change itself.
    place(heldOffset);
    follow();
  }

  // `beforeSnap` runs once the children are back in place and before the
  // row's snap type returns, so the hand-back's scroll snaps on what it
  // writes.
  function handBack(beforeSnap?: () => void): void {
    if (!isMoving) {
      return;
    }
    const at = position();
    for (const child of children()) {
      const animator = animatorFor(child);
      animator.stop(['x']);
      animator.set({x: 0});
      child.style.removeProperty('translate');
    }
    leftOut = [];
    isMoving = false;
    beforeSnap?.();
    if (ownSnapType === '') {
      element.style.removeProperty('scroll-snap-type');
    } else {
      element.style.setProperty('scroll-snap-type', ownSnapType);
    }
    element.scrollTo({left: isRtl() ? -at : at, behavior: 'instant'});
    if (onHeld != null) {
      cancelAnimationFrame(followFrame);
      onHeld({offset: at, travel: heldTravel});
      onHeld(null);
    }
  }

  // Whether the child at `index` can show in the row's view at any point of
  // the track curve `curve`, read from the curve's own values. A child that
  // cannot keeps its place, and the hand-back places every child.
  function showsDuring(curve: MotionCurve): (index: number) => boolean {
    let from = Infinity;
    let to = -Infinity;
    const steps = Math.max(1, Math.ceil(curve.duration * SHOWS_SAMPLES_PER_S));
    for (let i = 0; i <= steps; i++) {
      const at = -heldSign * curve.at((curve.duration * i) / steps);
      from = Math.min(from, at);
      to = Math.max(to, at);
    }
    return index => {
      const span = spans[index];
      return (
        span == null || (span.end > from && span.start < to + heldOuterWidth)
      );
    };
  }

  const animator: PagerAnimator = {
    get(property, time) {
      const first = children()[0];
      if (!isMoving || first == null) {
        return property === 'x' ? xOf(nativePosition()) : 0;
      }
      const value = animatorFor(first).get(property, time);
      return property === 'x' ? value - sign() * heldOffset : value;
    },
    getVelocity(property, time) {
      const first = children()[0];
      return isMoving && first != null
        ? animatorFor(first).getVelocity(property, time)
        : 0;
    },
    set(values, options) {
      if (!isMoving) {
        return;
      }
      const shifted =
        values.x == null ? values : {...values, x: toChild(values.x)};
      for (const child of children()) {
        animatorFor(child).set(shifted, options);
      }
      if (values.x != null) {
        leftOut = [];
      }
    },
    stop(properties) {
      if (!isMoving) {
        return;
      }
      for (const child of children()) {
        animatorFor(child).stop(properties);
      }
      // Each child's animation stops on its own clock, and a child the
      // settle left out kept its place. Every child of a held row moves to
      // where the lead stopped.
      if (isMoving && (properties == null || properties.includes('x'))) {
        place(position());
        leftOut = [];
      }
    },
    play(curves, options) {
      takeOver();
      const offset = sign() * heldOffset;
      const x = curves.x;
      const shifted =
        x == null
          ? curves
          : {
              ...curves,
              x: {...x, at: (t: number) => x.at(t) + offset},
            };
      const [first, ...rest] = children();
      if (first == null) {
        return animatorFor(element).play(shifted, options);
      }
      // The first child always plays: the row's position is read from it.
      const shows = x == null ? () => true : showsDuring(x);
      const players = [first];
      leftOut = [];
      for (const [index, child] of rest.entries()) {
        (shows(index + 1) ? players : leftOut).push(child);
      }
      return combined(
        players.map(child => animatorFor(child).play(shifted, options)),
      );
    },
  };

  return {
    animator,
    get isMoving() {
      return isMoving;
    },
    position,
    travel,
    remeasure,
    pages,
    stops,
    viewWidth,
    place,
    takeOver,
    handBack,
  };
}

/**
 * The pager on the row's children. A finger, a pen or a trackpad swipe takes
 * the row over, and the settle gives it back. A mouse drag and a mouse wheel
 * leave the row to native scrolling.
 */
function attachPaging(
  element: HTMLElement,
  options: SnapPagingOptions,
  onHeld?: HeldRowListener,
): SnapPagingAttachment {
  const track = childTrack(element, onHeld);
  // A child's animator reads its stylesheet's will-change in a later task. So
  // a press that moves the row reads no style in its own task.
  for (const child of Array.from(element.children)) {
    if (child instanceof HTMLElement) {
      animatorFor(child);
    }
  }
  // The stop that view pages count from, set when a gesture takes over.
  let anchor = 0;
  // The row's stops and view width, read before a takeover's first write.
  let measured: {stops: number[]; viewWidth: number} | null = null;
  // Native snap skips each item whose stop the end's page takes. So a wheel,
  // a key or a scroll rests on the same pages as a flick. Each skipped item
  // gets its own inline value and priority back when its stop leaves the
  // end's page or the paging detaches.
  const skipped = new Map<HTMLElement, {value: string; priority: string}>();
  const skip = (items: ReadonlyArray<Element>) => {
    for (const [item, own] of skipped) {
      if (!items.includes(item)) {
        skipped.delete(item);
        if (own.value === '') {
          item.style.removeProperty('scroll-snap-align');
        } else {
          item.style.setProperty('scroll-snap-align', own.value, own.priority);
        }
      }
    }
    for (const item of items) {
      if (item instanceof HTMLElement && !skipped.has(item)) {
        skipped.set(item, {
          value: item.style.getPropertyValue('scroll-snap-align'),
          priority: item.style.getPropertyPriority('scroll-snap-align'),
        });
        item.style.setProperty('scroll-snap-align', 'none');
      }
    }
  };
  // The skip follows the stops at rest, at most once a frame. A change while
  // the paging holds the row waits for the hand-back, which writes it before
  // the row snaps again.
  let resnapFrame: number | null = null;
  let isResnapDue = false;
  const resnap = () => {
    if (track.isMoving) {
      isResnapDue = true;
      return;
    }
    resnapFrame ??= requestAnimationFrame(() => {
      resnapFrame = null;
      if (track.isMoving) {
        isResnapDue = true;
        return;
      }
      isResnapDue = false;
      skip(track.pages().skipped);
    });
  };
  const takeOverShown = (at: number) => {
    // Every read comes before the takeover's first write.
    const stops = track.stops();
    const viewWidth = track.viewWidth();
    anchor = stops.reduce(
      (best, stop, i) =>
        Math.abs(stop - at) < Math.abs(stops[best] - at) ? i : best,
      0,
    );
    measured = {stops, viewWidth};
    pager.setOptions({});
    measured = null;
    // The pager learns its page while the row is at rest, which moves
    // nothing. The takeover then holds the row where it is shown.
    pager.goTo(pager.nearestPage(at), {
      animated: false,
      reason: 'controlled',
    });
    track.takeOver();
  };
  const pager = createPager(
    {
      count: 1,
      pages: 'children',
      // A trackpad swipe is a scroll, not a pointer, so it pages whatever
      // the pointer kinds.
      panOptions: {allowedPointerTypes: ['touch', 'pen']},
      measurePages: () => {
        // A resize while the row is held moves its travel first.
        track.remeasure();
        const stops = measured?.stops ?? track.stops();
        // Native snap follows the new stops. The skip writes in a later
        // frame, so this read stays ahead of any write.
        resnap();
        return (options.pages ?? 'view') === 'item'
          ? stops
          : viewPages(
              stops,
              Math.min(anchor, stops.length - 1),
              measured?.viewWidth ?? track.viewWidth(),
            );
      },
      shouldBeginPan: () => {
        // The finger catches the row where it is shown.
        if (!track.isMoving) {
          takeOverShown(track.position());
        }
        return true;
      },
      onSettle: () => {
        if (!pager.isDragging && !pager.isSettling) {
          track.handBack(
            isResnapDue
              ? () => {
                  isResnapDue = false;
                  skip(track.pages().skipped);
                }
              : undefined,
          );
        }
      },
    },
    {animator: track.animator},
  );
  const detach = pager.attach(element, element);
  // Items that change while the row keeps its size move the stops too.
  let unobserveItems: (() => void)[] = [];
  const observeItems = () => {
    for (const unobserve of unobserveItems) {
      unobserve();
    }
    unobserveItems = Array.from(element.children, item =>
      observeResize(item, resnap),
    );
  };
  const unobserveList = observeMutations(element, {childList: true}, () => {
    observeItems();
    resnap();
  });
  observeItems();
  return {
    detach: () => {
      detach();
      pager.dispose();
      unobserveList();
      for (const unobserve of unobserveItems) {
        unobserve();
      }
      if (resnapFrame != null) {
        cancelAnimationFrame(resnapFrame);
        resnapFrame = null;
      }
      track.handBack();
      skip([]);
    },
    move: target => {
      // A finger on the row keeps it.
      if (pager.isDragging) {
        return;
      }
      // The target reads the row too, so every read comes before the
      // takeover's first write.
      const at = track.position();
      const end = track.travel();
      const to = Math.min(Math.max(target(at, end), 0), end);
      // A move from rest is the pager's own too. So a touch catches it as it
      // catches a settle, and the release rests on a page.
      if (!track.isMoving) {
        takeOverShown(at);
      }
      pager.goTo(pager.nearestPage(to), {offset: to});
    },
    moveHeld: target => {
      if (!track.isMoving) {
        return false;
      }
      // A finger on the row keeps it.
      if (!pager.isDragging) {
        const end = track.travel();
        const to = Math.min(Math.max(target(track.position(), end), 0), end);
        // The pager's own move: a finger on the row stops it at the touch.
        pager.goTo(pager.nearestPage(to), {offset: to});
      }
      return true;
    },
  };
}