Skip to content

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

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

/**
 * @file snapPagingValue.ts
 * @input A scrolling row of snap items
 * @output The `SnapPaging` value, the calls Carousel makes on it
 *   (`isSnapPaging`, `attachSnapPaging`, `moveSnapPaging`,
 *   `moveHeldSnapPaging`), where a held row is shown, and stops
 * @position Carousel's only link to snap paging. It imports no pager code,
 *   so a Carousel without `hasSnap={useSnapPaging()}` bundles none
 */

import {isRtlElement} from '../hooks/isRtlElement';
import {realmValue, sharedKey} from '../utils/sharedRealm';

/** Options of `useSnapPaging`. */
export interface SnapPagingOptions {
  /**
   * What one flick moves. `'view'`: one view, landing on the item start edge
   * nearest one viewport on. `'item'`: one item.
   * @default 'view'
   */
  readonly pages?: 'view' | 'item';
}

/**
 * Configured snap paging. Make it with `useSnapPaging`, and pass it to
 * Carousel's `hasSnap`.
 */
export interface SnapPaging {
  /**
   * A brand that is never present, so the paging types of the package and a
   * swizzled copy match.
   */
  readonly '@astryxdesign/core/snap-paging/v1'?: never;
}

/** The paging attached to one row. */
export interface SnapPagingAttachment {
  readonly detach: () => void;
  readonly move: (target: (at: number, end: number) => number) => void;
  readonly moveHeld: (target: (at: number, end: number) => number) => boolean;
}

/**
 * Where a row the paging holds is shown: its offset toward the end, and the
 * travel it was taken over with.
 */
export interface HeldRow {
  readonly offset: number;
  readonly travel: number;
}

/** Hears a held row on each frame of the hold, and null at the hand-back. */
export type HeldRowListener = (held: HeldRow | null) => void;

type Attach = (
  element: HTMLElement,
  onHeld?: HeldRowListener,
) => SnapPagingAttachment;

interface SnapPagingValue {
  readonly attach: Attach;
}

// Registered, so a swizzled Carousel accepts the package's paging value.
const values = realmValue(
  sharedKey('snap-paging/values', 1),
  () => new WeakSet<object>(),
);
// Each attached row's paging, for Carousel's own scroll calls.
const attachments = new WeakMap<HTMLElement, SnapPagingAttachment>();

/** A `SnapPaging` value that attaches with `attach`. */
export function makeSnapPaging(attach: Attach): SnapPaging {
  const value: SnapPagingValue = {attach};
  values.add(value);
  return value as unknown as SnapPaging;
}

/** Whether `value` came from `useSnapPaging`. */
export function isSnapPaging(value: unknown): value is SnapPaging {
  return typeof value === 'object' && value !== null && values.has(value);
}

/**
 * Attaches snap paging to `element`; the returned function detaches it.
 * `onHeld` hears where the row is shown while the paging holds it.
 */
export function attachSnapPaging(
  value: SnapPaging,
  element: HTMLElement,
  onHeld?: HeldRowListener,
): () => void {
  const attachment = (value as unknown as SnapPagingValue).attach(
    element,
    onHeld,
  );
  attachments.set(element, attachment);
  return () => {
    attachments.delete(element);
    attachment.detach();
  };
}

/**
 * Moves the row through the paging to `target(shown, end)`, an offset toward
 * the end, and takes the row over first when it is at rest. `end` is its
 * travel. False when no paging is attached.
 */
export function moveSnapPaging(
  element: HTMLElement,
  target: (shown: number, end: number) => number,
): boolean {
  const attachment = attachments.get(element);
  if (attachment == null) {
    return false;
  }
  attachment.move(target);
  return true;
}

/**
 * Moves a row the paging holds to `target(shown, end)`, an offset toward the
 * end. `end` is its travel when taken over. False when it is not held.
 */
export function moveHeldSnapPaging(
  element: HTMLElement,
  target: (shown: number, end: number) => number,
): boolean {
  return attachments.get(element)?.moveHeld(target) ?? false;
}

/** The stop nearest `at`, or `at` itself when the row has no stops. */
export function nearestStop(stops: ReadonlyArray<number>, at: number): number {
  return stops.reduce(
    (best, stop) => (Math.abs(stop - at) < Math.abs(best - at) ? stop : best),
    stops[0] ?? at,
  );
}

/**
 * The scale a scaled ancestor gives the row's rects: the rect's width over the
 * row's layout width. Scroll offsets do not have it.
 */
export function rowScale(element: HTMLElement, box: DOMRect): number {
  return element.offsetWidth > 0 && box.width > 0
    ? box.width / element.offsetWidth
    : 1;
}

/** A row's pages: one stop each, and the items whose stops native snap skips. */
export interface SnapPages {
  readonly stops: number[];
  readonly skipped: Element[];
}

/**
 * The row's stops, one per page (`snapPages`). Read from the items' rects,
 * with the position `shown` added back.
 */
export function snapStops(
  element: HTMLElement,
  shown: number,
  end: number,
): number[] {
  return snapPages(element, shown, end).stops;
}

/**
 * The row's stops, one per page. Stops closer than half a pixel are one stop.
 * The end's page is the page that the end rounds to. So a stop within half
 * its preceding step of the end is that page, which rests where the row
 * ends. Native snap skips the items of that stop (`skipped`).
 */
export function snapPages(
  element: HTMLElement,
  shown: number,
  end: number,
  isHeld = false,
): SnapPages {
  const stops: number[] = [];
  const owners: Element[][] = [];
  for (const {item, stop} of itemStops(element, shown, end, isHeld)) {
    if (stops.length === 0 || stop > stops[stops.length - 1] + 0.5) {
      stops.push(stop);
      owners.push([item]);
    } else {
      owners[owners.length - 1].push(item);
    }
  }
  const n = stops.length;
  if (
    n >= 3 &&
    stops[n - 1] >= end - 0.5 &&
    stops[n - 1] - stops[n - 2] < (stops[n - 2] - stops[n - 3]) / 2
  ) {
    stops.splice(n - 2, 1);
    return {stops, skipped: owners[n - 2]};
  }
  return {stops: n > 0 ? stops : [0], skipped: []};
}

/**
 * How far the row's items reach, start to end. A held row's items carry the
 * paging's translate, so each rect takes its own item's translate off, read
 * right after it. The span is then the layout's, whenever each rect was read.
 */
export function itemsSpan(element: HTMLElement, isHeld = false): number {
  const items = Array.from(element.children).filter(
    (child): child is HTMLElement => child instanceof HTMLElement,
  );
  if (items.length === 0) {
    return 0;
  }
  // A rect is on screen, scaled with the row; a translate is in the row's own
  // pixels. So each rect takes the scale off before its translate.
  const scale = rowScale(element, element.getBoundingClientRect());
  let start = Infinity;
  let end = -Infinity;
  for (const item of items) {
    const rect = item.getBoundingClientRect();
    const held = isHeld
      ? Number.parseFloat(getComputedStyle(item).translate) || 0
      : 0;
    start = Math.min(start, rect.left / scale - held);
    end = Math.max(end, rect.right / scale - held);
  }
  return end - start;
}

function itemStops(
  element: HTMLElement,
  shown: number,
  end: number,
  isHeld: boolean,
): {item: Element; stop: number}[] {
  const rtl = isRtlElement(element);
  const box = element.getBoundingClientRect();
  const scale = rowScale(element, box);
  const border = rtl
    ? element.offsetWidth - element.clientWidth - element.clientLeft
    : element.clientLeft;
  const style = getComputedStyle(element);
  const padding =
    Number.parseFloat(
      rtl ? style.scrollPaddingRight : style.scrollPaddingLeft,
    ) || 0;
  return Array.from(element.children, item => {
    const rect = item.getBoundingClientRect();
    // A held row's children carry the paging's translate. The rect shows the
    // translate at the time of its read, so the next read takes it off.
    const held = isHeld
      ? Number.parseFloat(getComputedStyle(item).translate) || 0
      : 0;
    const fromEdge =
      (rtl ? box.right - rect.right : rect.left - box.left) / scale +
      (rtl ? held : -held);
    return {
      item,
      stop: Math.min(Math.max(fromEdge - border + shown - padding, 0), end),
    };
  });
}