range-math.js

/**
 * Pure, DOM-free implementations of the CSS scroll-driven animation range
 * calculations. Everything here is a plain function of numbers so it can be
 * unit-tested in Node without a browser.
 *
 * All offsets are expressed in the scroll container's scroll coordinate space
 * along the timeline axis: `scrollPos` is the container's current scroll
 * offset, `subjectOffset` is the distance from the container's scroll origin to
 * the subject's leading edge, `subjectSize` is the subject's extent, and
 * `scrollportSize` is the container's visible extent.
 *
 * @module range-math
 */

/**
 * @typedef {object} ViewGeometry
 * @property {number} subjectOffset Distance from the scroll origin to the subject's leading edge.
 * @property {number} subjectSize Subject extent along the axis.
 * @property {number} scrollportSize Visible extent of the scroll container along the axis.
 * @property {number} [insetStart=0] Start-side `view-timeline-inset`.
 * @property {number} [insetEnd=0] End-side `view-timeline-inset`.
 */

/**
 * @typedef {object} ScrollRange
 * @property {number} start Scroll offset at which progress is 0.
 * @property {number} end Scroll offset at which progress is 1.
 */

/** Named ranges this module can resolve. */
export const NAMED_RANGES = Object.freeze([
  'cover',
  'contain',
  'entry',
  'exit',
  'entry-crossing',
  'exit-crossing'
]);

/**
 * Clamp a number into an inclusive interval.
 *
 * @param {number} value Value to clamp.
 * @param {number} [min=0] Lower bound.
 * @param {number} [max=1] Upper bound.
 * @returns {number} The clamped value.
 */
export function clamp (value, min = 0, max = 1) {
  return value < min ? min : value > max ? max : value;
}

/**
 * Resolve a named view-timeline range into absolute scroll offsets.
 *
 * The definitions follow the spec:
 * - `cover` spans from the subject first touching the scrollport to it fully
 *   leaving: `[o - V, o + S]`.
 * - `contain` spans the period where the smaller of subject/scrollport is fully
 *   inside the larger: `[o - V + min(S, V), o + max(0, S - V)]`.
 * - `entry` is `cover` start to `contain` start, `exit` is `contain` end to
 *   `cover` end.
 * - `entry-crossing` is the subject crossing the end edge: `[o - V, o - V + S]`.
 * - `exit-crossing` is the subject crossing the start edge: `[o, o + S]`.
 *
 * @param {string} name One of {@link NAMED_RANGES}; unknown names fall back to `cover`.
 * @param {ViewGeometry} geometry Subject and scrollport geometry.
 * @returns {ScrollRange} Absolute scroll offsets for the range.
 */
export function resolveNamedRange (name, geometry) {
  const insetStart = geometry.insetStart ?? 0;
  const insetEnd = geometry.insetEnd ?? 0;
  const o = geometry.subjectOffset;
  const s = geometry.subjectSize;
  const v = Math.max(0, geometry.scrollportSize - insetStart - insetEnd);

  const coverStart = o - v - insetStart;
  const coverEnd = o + s - insetStart;
  const containStart = coverStart + Math.min(s, v);
  const containEnd = o + Math.max(0, s - v) - insetStart;

  switch (name) {
    case 'contain':
      return { start: containStart, end: containEnd };
    case 'entry':
      return { start: coverStart, end: containStart };
    case 'exit':
      return { start: containEnd, end: coverEnd };
    case 'entry-crossing':
      return { start: coverStart, end: coverStart + s };
    case 'exit-crossing':
      return { start: o - insetStart, end: o + s - insetStart };
    case 'cover':
    default:
      return { start: coverStart, end: coverEnd };
  }
}

/**
 * Resolve one `animation-range` boundary (a named range plus a percentage
 * offset inside it) into an absolute scroll offset.
 *
 * @param {{ name: string, percent: number }} boundary Parsed boundary.
 * @param {ViewGeometry} geometry Subject and scrollport geometry.
 * @returns {number} Absolute scroll offset of the boundary.
 */
export function resolveBoundary (boundary, geometry) {
  const range = resolveNamedRange(boundary.name, geometry);
  return range.start + ((boundary.percent / 100) * (range.end - range.start));
}

/**
 * Resolve a full range specification into the scroll offsets between which the
 * animation is active.
 *
 * @param {{ start: { name: string, percent: number }, end: { name: string, percent: number } }} spec Parsed range.
 * @param {ViewGeometry} geometry Subject and scrollport geometry.
 * @returns {ScrollRange} Active scroll offsets.
 */
export function resolveRange (spec, geometry) {
  return {
    start: resolveBoundary(spec.start, geometry),
    end: resolveBoundary(spec.end, geometry)
  };
}

/**
 * The scroll offsets a `scroll()` timeline spans: the full scrollable distance.
 *
 * @param {{ scrollSize: number, clientSize: number }} geometry Scroller metrics.
 * @returns {ScrollRange} Active scroll offsets.
 */
export function resolveScrollRange (geometry) {
  return { start: 0, end: Math.max(0, geometry.scrollSize - geometry.clientSize) };
}

/**
 * Convert a scroll offset into clamped 0–1 timeline progress.
 *
 * A zero-length range is degenerate; progress is reported as 1 once the scroll
 * position reaches it and 0 before, which matches how a native timeline with no
 * travel behaves.
 *
 * @param {number} scrollPos Current scroll offset.
 * @param {ScrollRange} range Active scroll offsets.
 * @returns {number} Progress in the 0–1 range.
 */
export function progressAt (scrollPos, range) {
  const span = range.end - range.start;
  if (span === 0) return scrollPos >= range.start ? 1 : 0;
  return clamp((scrollPos - range.start) / span);
}

/**
 * Compute progress for a view timeline directly from geometry.
 *
 * @param {number} scrollPos Current scroll offset.
 * @param {{ start: { name: string, percent: number }, end: { name: string, percent: number } }} spec Parsed range.
 * @param {ViewGeometry} geometry Subject and scrollport geometry.
 * @returns {number} Progress in the 0–1 range.
 */
export function viewProgress (scrollPos, spec, geometry) {
  return progressAt(scrollPos, resolveRange(spec, geometry));
}

/**
 * Whether a subject is inside its active range at a given scroll offset.
 *
 * @param {number} scrollPos Current scroll offset.
 * @param {ScrollRange} range Active scroll offsets.
 * @returns {boolean} True when the scroll position lies within the range.
 */
export function isInRange (scrollPos, range) {
  const lo = Math.min(range.start, range.end);
  const hi = Math.max(range.start, range.end);
  return scrollPos >= lo && scrollPos <= hi;
}