Skip to content

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

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

'use client';

/**
 * @file usePopoverSurfaceMotion.ts
 * @input React, the shared touch resolver, the layer runtime's presentation
 *   hold and popoverSurfaceMotion
 * @output Exports `usePopoverSurfaceMotion`, the calls Popover makes as it
 *   opens and as it starts to close. Under a finger they present and dismiss
 *   the popover the UIKit way; a mouse keeps the layer's own entrance.
 * @position Internal to Popover; glue between the component and
 *   popoverSurfaceMotion.ts
 *
 * The shared touch resolver decides as the popover opens. Under a finger (a
 * coarse primary pointer, on any touch device) the popover grows out of its
 * source. When the layer runtime reports that it starts to close, it shrinks
 * back into it. A fine primary pointer keeps the layer's own entrance. The
 * growth plays on the surface, the box that paints the popover, and not on
 * the layer. The layer is anchored, and Chromium lays an anchored element out
 * again each time it restyles it, as when an animation on it starts. The
 * motion is created for the surface the first time the popover opens and
 * follows it if the surface is replaced.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Popover/Popover.tsx
 * - /packages/core/src/Popover/usePopoverSurfaceMotion.test.tsx
 */

import {useCallback, useEffect, useMemo, useRef, useState} from 'react';
import {createPresentationHold} from '../Layer/presentationHold';
import {isCoarsePointer} from '../utils/coarsePointer';
import {
  createPopoverSurfaceMotion,
  type PopoverSurfaceMotion,
  type PopoverSurfaceRect,
} from './popoverSurfaceMotion';

// The growth needs where the surface ends and where its source is. Both
// boxes are read once, in the frame that starts it, before that frame writes.
function boxOf(element: Element): PopoverSurfaceRect {
  const rect = element.getBoundingClientRect();
  return {
    left: rect.left,
    top: rect.top,
    width: rect.width,
    height: rect.height,
  };
}

export interface PopoverSurfaceMotionCalls {
  /**
   * Call as the popover opens, right after the browser shows it and before
   * it paints. `entrance` is the surface that carries the pointer
   * presentation's CSS entrance; the touch presentation turns it off there
   * and plays its growth on it.
   */
  present: (
    layer: HTMLElement | null,
    source: HTMLElement | null,
    entrance?: HTMLElement | null,
  ) => void;
  /** Call as the popover starts to close, while the browser still shows it. */
  closeStart: () => void;
}

export function usePopoverSurfaceMotion(): PopoverSurfaceMotionCalls {
  const motionRef = useRef<{
    element: HTMLElement;
    entrance: HTMLElement | null;
    motion: PopoverSurfaceMotion;
  } | null>(null);
  // Whether the presentation in progress is the touch one, held from the
  // open until its close begins (Layer/presentationHold).
  const [touchHold] = useState(() => createPresentationHold<boolean>());

  const release = useCallback(() => {
    motionRef.current?.motion.dispose();
    motionRef.current = null;
  }, []);

  const motionFor = useCallback(
    (element: HTMLElement, entrance: HTMLElement | null) => {
      const current = motionRef.current;
      if (current?.element === element && current.entrance === entrance) {
        return current.motion;
      }
      current?.motion.dispose();
      const motion = createPopoverSurfaceMotion(element, {entrance});
      motionRef.current = {element, entrance, motion};
      return motion;
    },
    [],
  );

  // Releases the motion's compositor animations, and any exit copy still on
  // screen, at unmount.
  useEffect(() => release, [release]);

  const present = useCallback(
    (
      layer: HTMLElement | null,
      source: HTMLElement | null,
      entrance: HTMLElement | null = null,
    ) => {
      if (layer == null) {
        return;
      }
      const isTouch =
        source != null && isCoarsePointer(layer.ownerDocument.defaultView);
      touchHold.take(isTouch);
      if (!isTouch || source == null) {
        // A fine pointer animates nothing here, so nothing is created for
        // it, and nothing is promoted to the compositor. A motion this layer
        // already has (the pointer changed, or a touch presentation is on
        // screen) is released.
        release();
        return;
      }
      const surface = entrance ?? layer;
      motionFor(surface, entrance).enter(() => ({
        surface: boxOf(surface),
        source: boxOf(source),
      }));
    },
    [motionFor, release, touchHold],
  );

  const closeStart = useCallback(() => {
    if (touchHold.current() === true) {
      motionRef.current?.motion.exit();
    }
    touchHold.release();
  }, [touchHold]);

  return useMemo(() => ({present, closeStart}), [present, closeStart]);
}