Skip to content

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

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

'use client';

/**
 * @file useZoomCore.ts
 * @input A stage element ref, which clips and centres the photo, and the
 *   element the gestures attach to: the stage, or a gallery's track. Also
 *   whether zoom is on, the current item's key and the zoom and fit callbacks
 * @output Exports `useZoomCore`: Lightbox's zoom stage for every pointer. It
 *   writes the photo's transform through the compositor animator and settles
 *   every zoom, the keyboard's zoom and pan included, on `springs.settle`. Its
 *   API tells an outer pager when the photo is at an edge (`isAtEdge`)
 * @position Lightbox's shared zoom stage, internal. useZoomStage.ts drives
 *   its pointer paths; the geometry is in zoomStage.ts.
 *
 * SYNC: When modified, update useZoomStage.ts, zoomStage.ts, Lightbox.tsx
 * and __tests__/LightboxZoomModes.interaction.browser.spec.ts.
 */

import {useCallback, useMemo, useRef, useState, type RefObject} from 'react';
import type {Point} from '../gestures/types';
import {useAttachment} from '../hooks/useAttachment';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {createMotionEngine, type Animator} from '../motion/animator';
import {resolveMotion} from '../motion/resolveMotion';
import {springs} from '../motion/uikit/springs';
import {registerReducedMotionCrossFade} from '../motion/uikit/timing';
import {observeResize} from '../utils/sharedResizeObserver';
import {
  IDENTITY,
  doubleClickTarget,
  doubleTapScaleFor,
  isZoomed,
  maxScaleFor,
  pannedBy,
  releasedZoomTarget,
  restRange,
  restingTransform,
  transformForResize,
  type StagePoint,
  type ZoomGeometry,
  type ZoomTransform,
} from './zoomStage';

/** Set on the stage while a finger or the mouse drags a zoomed photo. */
export const ZOOM_DRAGGING_ATTRIBUTE = 'data-zoom-dragging';

/** A drag's initial direction on screen. */
export type PanDirection = 'left' | 'right';

export interface UseZoomCoreOptions {
  /** The stage: the box the photo is fitted and centred in, clipping it. */
  stageRef: RefObject<HTMLElement | null>;
  /**
   * Where the gestures attach and what the resize observer watches: the
   * stage by default. In a pager, the track (the pager's own pan sits on
   * the stage, each element has one `touch-action`, and every page shares
   * the track's size).
   */
  surfaceRef?: RefObject<HTMLElement | null>;
  /** Zoom is on (an image item with `hasZoom`). */
  isEnabled: boolean;
  /** Changes when another item shows; the photo returns to the fitted size. */
  itemKey: unknown;
  /** The photo became zoomed or returned to the fitted size. */
  onZoomedChange: (isZoomed: boolean) => void;
  /**
   * The photo left or came back to its fitted size on screen. It reads false
   * from a gesture's first move or a settle's start, and true once a settle
   * back lands.
   */
  onFitChange?: (isAtFit: boolean) => void;
}

/** Whether a shown transform is the fitted size, to within a pixel. */
function isAtFit(transform: ZoomTransform): boolean {
  return (
    Math.abs(transform.scale - 1) < 1e-3 &&
    Math.abs(transform.x) < 0.5 &&
    Math.abs(transform.y) < 0.5
  );
}

/** What Lightbox calls: the photo's ref and the keyboard's zoom and pan. */
export interface ZoomStage {
  /** Callback ref for the photo element the stage moves and scales. */
  readonly contentRef: (element: HTMLElement | null) => void;
  /** Whether the photo is zoomed now. */
  isZoomed(): boolean;
  /** Keyboard: zoom in 2x about the stage's centre, or out when zoomed. */
  toggle(): void;
  zoomIn(): void;
  zoomOut(): void;
  /** Keyboard: move a zoomed photo by (dx, dy) px, kept inside the stage. */
  panBy(dx: number, dy: number): void;
  /**
   * A mouse's or a pen's double-click at a client point: 2× about it, or
   * back when zoomed. Lightbox calls it on the browser's `dblclick`, which
   * keeps the system's double-click speed.
   */
  doubleClickAt(clientX: number, clientY: number): void;
  /**
   * Whether a zoomed photo can no longer move with a drag toward
   * `direction`, since its edge on that side is at the stage's. A pager takes
   * such a drag, as an outer paging scroll view does.
   */
  isAtEdge(direction: PanDirection): boolean;
}

/** The core as the gestures (useZoomStage.ts) drive it. */
export interface ZoomCore {
  /** The API Lightbox calls (one object for the component's lifetime). */
  readonly api: ZoomStage;
  readonly animator: Animator;
  /** The last measured geometry (null until a step measures it). */
  readonly geometryRef: {current: ZoomGeometry | null};
  /** Where the photo is going: the last written value or the settle's end. */
  readonly targetRef: {current: ZoomTransform};
  readonly zoomedRef: {current: boolean};
  readonly optionsRef: {current: UseZoomCoreOptions};
  /** Reads the stage and the photo (layout): when a step begins. */
  measure(): ZoomGeometry | null;
  /** Client px to stage px, from the last measure. */
  toStage(point: Point): StagePoint;
  /** Where the photo shows now (its presentation value). */
  current(): ZoomTransform;
  /** Shows the photo at `transform` at once. */
  write(transform: ZoomTransform): void;
  /** Where the photo is going, when an animation the core did not start ends there. */
  setTarget(transform: ZoomTransform): void;
  setZoomed(next: boolean): void;
  /**
   * Reports that the photo shows at its fitted size again, when an animation
   * the core did not start lands there (`onFitChange`).
   */
  setAtFit(next: boolean): void;
  /** Whether the photo is moving (shown away from where it is going). */
  isMoving(): boolean;
  /** Whether a zoomed photo's edge toward `direction` is at the stage's. */
  isAtEdgeOf(geometry: ZoomGeometry, direction: PanDirection): boolean;
  /**
   * Settles on `springs.settle`: a release past a limit, a double tap, a
   * double-click and the keyboard's zoom and pan. Lightbox's main interaction
   * is a gesture, so every zoom settles on that one spring. A pinch's release
   * starts it at `scaleVelocity`, the photo's scale per second at the lift;
   * anything else starts at rest. Under Reduce Motion the animator's default
   * applies. That is a fade in place on a touch screen or for a finger's
   * release (`touchRelease`), and at once otherwise.
   */
  settleTo(
    geometry: ZoomGeometry,
    target: ZoomTransform,
    options?: {touchRelease?: boolean; scaleVelocity?: number},
  ): void;
}

/**
 * Lightbox's zoom stage. Every zoom step runs on the compositor as baked
 * keyframes, with no React render and no layout read after a step begins. A
 * keyboard step continues from where the photo is going, so presses during a
 * settle add up. React hears only discrete changes (`onZoomedChange`).
 */
export function useZoomCore(options: UseZoomCoreOptions): ZoomCore {
  // One animator for the component's lifetime; the photo's ref attaches it.
  const [animator] = useState(() => createMotionEngine(null));
  const optionsRef = useRef(options);
  useIsomorphicLayoutEffect(() => {
    optionsRef.current = options;
  });
  const contentElementRef = useRef<HTMLElement | null>(null);
  const geometryRef = useRef<ZoomGeometry | null>(null);
  /** Client px of the stage's top-left corner when last measured. */
  const originRef = useRef<Point>({x: 0, y: 0});
  const zoomedRef = useRef(false);
  const targetRef = useRef<ZoomTransform>(IDENTITY);

  const contentRef = useCallback(
    (element: HTMLElement | null) => {
      contentElementRef.current = element;
      animator.attach(element);
    },
    [animator],
  );

  // Layout reads happen here only: when a gesture or a keyboard zoom begins.
  // Sizes are read unrounded (offset sizes round to whole pixels, an error
  // a deep zoom would multiply): the stage's box and the photo's used size.
  // The stage centres the photo, so its fitted box follows from the two.
  const measure = useCallback((): ZoomGeometry | null => {
    const stage = optionsRef.current.stageRef.current;
    const content = contentElementRef.current;
    const view = stage?.ownerDocument.defaultView;
    if (stage == null || content == null || view == null) {
      return null;
    }
    const rect = stage.getBoundingClientRect();
    // The stage has no border or scrollbar: its box is its content box.
    const width = rect.width > 0 ? rect.width : stage.clientWidth;
    const height = rect.height > 0 ? rect.height : stage.clientHeight;
    const used = view.getComputedStyle(content);
    const fitWidth = parseFloat(used.width) || content.offsetWidth;
    const fitHeight = parseFloat(used.height) || content.offsetHeight;
    if (!(width > 0 && height > 0 && fitWidth > 0 && fitHeight > 0)) {
      return null;
    }
    originRef.current = {
      x: rect.left + stage.clientLeft,
      y: rect.top + stage.clientTop,
    };
    // By tag, not `instanceof`: a viewer rendered into another window has
    // that window's element classes.
    const naturalWidth =
      content.tagName === 'IMG'
        ? (content as HTMLImageElement).naturalWidth
        : 0;
    const natural = naturalWidth > 0 ? naturalWidth : fitWidth;
    const doubleTapScale = doubleTapScaleFor(
      width,
      height,
      fitWidth,
      fitHeight,
    );
    const geometry: ZoomGeometry = {
      width,
      height,
      fit: {
        x: (width - fitWidth) / 2,
        y: (height - fitHeight) / 2,
        width: fitWidth,
        height: fitHeight,
      },
      minScale: 1,
      maxScale: maxScaleFor(
        natural,
        fitWidth,
        view.devicePixelRatio || 1,
        doubleTapScale,
      ),
      doubleTapScale,
    };
    geometryRef.current = geometry;
    return geometry;
  }, []);

  const toStage = useCallback(
    (point: Point): StagePoint => ({
      x: point.x - originRef.current.x,
      y: point.y - originRef.current.y,
    }),
    [],
  );

  const current = useCallback(
    (): ZoomTransform => ({
      x: animator.get('x'),
      y: animator.get('y'),
      scale: animator.get('scale'),
    }),
    [animator],
  );

  const atFitRef = useRef(true);
  const setAtFit = useCallback((next: boolean) => {
    if (atFitRef.current !== next) {
      atFitRef.current = next;
      optionsRef.current.onFitChange?.(next);
    }
  }, []);

  const write = useCallback(
    (transform: ZoomTransform) => {
      targetRef.current = transform;
      animator.set({x: transform.x, y: transform.y, scale: transform.scale});
      setAtFit(isAtFit(transform));
    },
    [animator, setAtFit],
  );

  const setTarget = useCallback((transform: ZoomTransform) => {
    targetRef.current = transform;
  }, []);

  const isMoving = useCallback((): boolean => {
    const shown = current();
    const target = targetRef.current;
    return (
      Math.abs(shown.x - target.x) > 0.01 ||
      Math.abs(shown.y - target.y) > 0.01 ||
      Math.abs(shown.scale - target.scale) > 0.0001
    );
  }, [current]);

  const isAtEdgeOf = useCallback(
    (geometry: ZoomGeometry, direction: PanDirection): boolean => {
      const {x, scale} = targetRef.current;
      const range = restRange(geometry, scale);
      return direction === 'left'
        ? x <= range.x.min + 0.5
        : x >= range.x.max - 0.5;
    },
    [],
  );

  const setZoomed = useCallback((next: boolean) => {
    if (zoomedRef.current !== next) {
      zoomedRef.current = next;
      optionsRef.current.onZoomedChange(next);
    }
  }, []);

  const settleTo = useCallback(
    (
      geometry: ZoomGeometry,
      target: ZoomTransform,
      {
        touchRelease = false,
        scaleVelocity = 0,
      }: {touchRelease?: boolean; scaleVelocity?: number} = {},
    ) => {
      const from = current();
      animator.stop();
      // A Reduce Motion cross-fade stopped mid-dip would leave the photo dim,
      // since the next dip returns to the frozen opacity. So every settle
      // starts from full opacity, and ends there.
      if (animator.get('opacity') !== 1) {
        animator.set({opacity: 1});
      }
      targetRef.current = target;
      setZoomed(isZoomed(geometry, target));
      if (
        from.x === target.x &&
        from.y === target.y &&
        from.scale === target.scale
      ) {
        setAtFit(isAtFit(target));
        return;
      }
      // The photo is off its fitted size while it moves, back at it only
      // once a settle there lands.
      setAtFit(false);
      // Registers the reduced-motion cross-fade once; later calls do nothing.
      registerReducedMotionCrossFade();
      // Every zoom settles on `springs.settle`, read where the stage is. A
      // pinch's release starts it at the photo's scale velocity. The offset
      // starts at the matching speed, so the point the fingers held stays
      // put, as it does from rest.
      const stageElement = optionsRef.current.stageRef.current;
      const span = target.scale - from.scale;
      const rate =
        Number.isFinite(scaleVelocity) && span !== 0 ? scaleVelocity / span : 0;
      const handle = animator.animate(
        {x: target.x, y: target.y, scale: target.scale},
        {
          spring: resolveMotion(stageElement, springs.settle),
          velocity: {
            x: (target.x - from.x) * rate,
            y: (target.y - from.y) * rate,
            scale: span * rate,
          },
        },
        {touchRelease},
      );
      if (isAtFit(target)) {
        void handle.finished.then(landed => {
          if (landed && targetRef.current === target) {
            setAtFit(true);
          }
        });
      }
    },
    [animator, current, setAtFit, setZoomed],
  );

  // Another item: back to the fitted size before it paints. Lightbox resets
  // its own zoomed state during that render.
  useIsomorphicLayoutEffect(() => {
    animator.stop();
    animator.set({x: 0, y: 0, scale: 1, opacity: 1});
    targetRef.current = IDENTITY;
    zoomedRef.current = false;
    geometryRef.current = null;
    setAtFit(true);
  }, [animator, options.itemKey, setAtFit]);

  // A rotation or resize keeps the same photo point centred at the same
  // on-screen size (the shared resize observer). It watches the surface: in
  // a gallery the stage moves to each current page, while the track, whose
  // size every page shares, stays.
  const onResize = useCallback(() => {
    const before = geometryRef.current;
    if (before == null || !zoomedRef.current) {
      return;
    }
    const after = measure();
    if (after == null) {
      return;
    }
    animator.stop();
    const next = transformForResize(before, after, targetRef.current);
    write(next);
    setZoomed(isZoomed(after, next));
  }, [animator, measure, setZoomed, write]);
  // The surface mounts with the viewer's first media, which can come after the
  // viewer, as in a gallery mounted closed while its photos load.
  // `useAttachment` follows the element, and zoom turning on or off, after
  // every commit.
  const surfaceRef = options.surfaceRef ?? options.stageRef;
  const isEnabled = options.isEnabled;
  const onResizeRef = useRef(onResize);
  useIsomorphicLayoutEffect(() => {
    onResizeRef.current = onResize;
  });
  useAttachment(
    surfaceRef,
    surface =>
      isEnabled
        ? observeResize(surface, () => onResizeRef.current())
        : () => {},
    isEnabled,
  );

  // The keyboard works on where the photo is going, like UIKit's model
  // values: a press during a settle continues from that settle's end.
  const zoomIn = useCallback(() => {
    const geometry = measure();
    if (geometry == null || zoomedRef.current) {
      return;
    }
    settleTo(geometry, releasedZoomTarget(geometry, targetRef.current));
  }, [measure, settleTo]);

  const zoomOut = useCallback(() => {
    const geometry = measure();
    if (geometry == null || !zoomedRef.current) {
      return;
    }
    settleTo(
      geometry,
      restingTransform(geometry, {...IDENTITY, scale: geometry.minScale}),
    );
  }, [measure, settleTo]);

  const api = useMemo(
    (): ZoomStage => ({
      contentRef,
      isZoomed: () => zoomedRef.current,
      toggle: () => (zoomedRef.current ? zoomOut() : zoomIn()),
      zoomIn,
      zoomOut,
      panBy: (dx: number, dy: number) => {
        const geometry = measure();
        if (geometry == null || !zoomedRef.current) {
          return;
        }
        settleTo(geometry, pannedBy(geometry, targetRef.current, dx, dy));
      },
      doubleClickAt: (clientX: number, clientY: number) => {
        const geometry = measure();
        if (geometry == null) {
          return;
        }
        const point = toStage({x: clientX, y: clientY});
        settleTo(geometry, doubleClickTarget(geometry, current(), point));
      },
      isAtEdge: (direction: PanDirection) => {
        const geometry = geometryRef.current ?? measure();
        if (geometry == null || !zoomedRef.current) {
          return true;
        }
        return isAtEdgeOf(geometry, direction);
      },
    }),
    [
      contentRef,
      current,
      isAtEdgeOf,
      measure,
      settleTo,
      toStage,
      zoomIn,
      zoomOut,
    ],
  );

  // One object for the component's lifetime: every member is stable.
  return useMemo(
    () => ({
      api,
      animator,
      geometryRef,
      targetRef,
      zoomedRef,
      optionsRef,
      measure,
      toStage,
      current,
      write,
      setTarget,
      setZoomed,
      setAtFit,
      isMoving,
      isAtEdgeOf,
      settleTo,
    }),
    [
      api,
      animator,
      measure,
      toStage,
      current,
      write,
      setTarget,
      setZoomed,
      setAtFit,
      isMoving,
      isAtEdgeOf,
      settleTo,
    ],
  );
}