Skip to content

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

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

'use client';

/**
 * @file outsidePress.ts
 * @input Pointer presses on a document and on the shadow roots around a
 *   given root; with closesOnPan, pan moves from core's input stream
 * @output watchOutsidePress, and useOutsidePress, one watch per component.
 *   noteOutsideDismissal and outsideDismissalCount keep a per-document count
 *   of layers that an outside press or focus move closed. The inside tests
 *   are isPressInsideOwnedLayer and isFocusInsideOwnedLayer
 * @position Internal to Layer: the outside-press dismissal for a manual
 *   popover whose owner decides what counts as inside. Not exported.
 */

import {useCallback, useEffect, useMemo, useRef} from 'react';
import {UIKIT_PAN} from '../motion/uikit/gestures';
import {shadowHostOf, shadowRootsOutward} from '../utils/flatTree';
import {subscribeInput} from '../utils/inputStream';
import {isElement, isNode} from '../utils/nodeType';

export interface OutsidePressOptions {
  /** The pointer types the watch follows; every type when omitted. */
  readonly pointerTypes?: ReadonlyArray<string>;
  /**
   * A press outside also closes the layer as it begins to pan, or when the
   * browser takes it. While one press outside is followed, other pointers are
   * ignored. A new primary pointer starts a new press.
   */
  readonly closesOnPan?: boolean;
  /**
   * The shadow root the layer renders in. The document sees a press inside a
   * closed root as a press on its host. So each root from this one out to the
   * document judges presses too, and an inner root's judgment stands.
   */
  readonly root?: Node | null;
}

// A modal host's backdrop press reads this. A press that closed a layer above
// the host is that layer's, so the host stays open.
const outsideDismissals = new WeakMap<Document, number>();

/** Records that a layer in `doc` is closing because a press or focus went outside it. */
export function noteOutsideDismissal(doc: Document): void {
  outsideDismissals.set(doc, (outsideDismissals.get(doc) ?? 0) + 1);
}

/** How many layers an outside press has closed in `doc` so far. */
export function outsideDismissalCount(doc: Document): number {
  return outsideDismissals.get(doc) ?? 0;
}

/**
 * Watch the owner's document for a press outside, until the returned function
 * is called. The caller stops it when its layer hides and when it unmounts.
 *
 * @param owner - The element that owns the layer (the field); its document is
 *   watched.
 * @param isInside - Whether a press with this composed path is inside.
 * @param onOutside - Called once for each press that starts and ends outside,
 *   as native light dismiss does. With `closesOnPan`, also when that press
 *   pans or is cancelled.
 * @returns Stops watching.
 */
export function watchOutsidePress(
  owner: Element,
  isInside: (path: ReadonlyArray<EventTarget>) => boolean,
  onOutside: () => void,
  {pointerTypes, closesOnPan = false, root = null}: OutsidePressOptions = {},
): () => void {
  const doc = owner.ownerDocument;
  const shadows = root == null ? [] : shadowRootsOutward(root);
  let startedOutside = false;
  let panStart: {id: number; x: number; y: number} | null = null;
  const follows = (event: PointerEvent) =>
    pointerTypes == null || pointerTypes.includes(event.pointerType);
  const close = () => {
    startedOutside = false;
    panStart = null;
    noteOutsideDismissal(doc);
    onOutside();
  };

  // Capture phase, so a press whose target stops propagation is still seen.
  // An inner root's listener runs after the outer ones', so its judgment
  // stands.
  const handleDown = (event: PointerEvent) => {
    if (!follows(event)) {
      return;
    }
    if (
      closesOnPan &&
      panStart != null &&
      panStart.id !== event.pointerId &&
      !event.isPrimary
    ) {
      return;
    }
    startedOutside = !isInside(event.composedPath());
    if (closesOnPan) {
      panStart = startedOutside
        ? {id: event.pointerId, x: event.clientX, y: event.clientY}
        : null;
    }
  };
  const handleMove = (event: PointerEvent) => {
    if (
      panStart?.id === event.pointerId &&
      Math.max(
        Math.abs(event.clientX - panStart.x),
        Math.abs(event.clientY - panStart.y),
      ) >= UIKIT_PAN.hysteresis.value
    ) {
      close();
    }
  };
  const judgeUp = (event: PointerEvent) => {
    if (!follows(event) || (closesOnPan && panStart?.id !== event.pointerId)) {
      return;
    }
    const wasOutside = startedOutside;
    startedOutside = false;
    panStart = null;
    if (wasOutside && !isInside(event.composedPath())) {
      noteOutsideDismissal(doc);
      onOutside();
    }
  };
  // The document and each root see a lift inside a deeper closed root as a
  // lift on that root's host. So each of them judges, in the capture phase,
  // only a lift whose path does not hold the host below it. The innermost root
  // judges every lift it sees. A host judges a lift on itself, which no root
  // sees.
  let judgedLift: Event | null = null;
  const judgeUpUnlessBelow =
    (hostBelow: Element | null) => (event: PointerEvent) => {
      if (
        event === judgedLift ||
        (hostBelow != null && event.composedPath().includes(hostBelow))
      ) {
        return;
      }
      judgedLift = event;
      judgeUp(event);
    };
  const handleUp = judgeUpUnlessBelow(shadows.at(-1)?.host ?? null);
  const liftJudges = shadows.map(({root: shadow, host}, index) => ({
    shadow,
    host,
    handleRootUp: judgeUpUnlessBelow(
      index === 0 ? null : shadows[index - 1].host,
    ) as EventListener,
    handleHostUp: judgeUpUnlessBelow(null) as EventListener,
  }));
  const handleCancel = (event: PointerEvent) => {
    if (!follows(event)) {
      return;
    }
    if (closesOnPan && panStart?.id === event.pointerId) {
      close();
    } else if (!closesOnPan) {
      startedOutside = false;
    }
  };

  const judges: EventTarget[] = [
    doc,
    ...shadows.map(({root: shadow}) => shadow),
  ];
  for (const target of judges) {
    target.addEventListener('pointerdown', handleDown as EventListener, true);
  }
  const view = doc.defaultView;
  const stopMoves =
    closesOnPan && view != null
      ? subscribeInput(view, 'pointermove', handleMove)
      : null;
  doc.addEventListener('pointerup', handleUp, true);
  for (const {shadow, host, handleRootUp, handleHostUp} of liftJudges) {
    shadow.addEventListener('pointerup', handleRootUp, true);
    host.addEventListener('pointerup', handleHostUp);
  }
  doc.addEventListener('pointercancel', handleCancel, true);
  return () => {
    for (const target of judges) {
      target.removeEventListener(
        'pointerdown',
        handleDown as EventListener,
        true,
      );
    }
    stopMoves?.();
    doc.removeEventListener('pointerup', handleUp, true);
    for (const {shadow, host, handleRootUp, handleHostUp} of liftJudges) {
      shadow.removeEventListener('pointerup', handleRootUp, true);
      host.removeEventListener('pointerup', handleHostUp);
    }
    doc.removeEventListener('pointercancel', handleCancel, true);
  };
}

export interface OutsidePressWatch {
  /** Start watching, replacing any watch already running. */
  start: (
    owner: Element,
    isInside: (path: ReadonlyArray<EventTarget>) => boolean,
    onOutside: () => void,
    options?: OutsidePressOptions,
  ) => void;
  /** Stop watching; does nothing when no watch is running. */
  stop: () => void;
}

/**
 * One outside-press watch for a component: it calls `start` when its layer
 * shows and `stop` when it hides, and the watch's document listeners (an
 * external system) are removed when the component unmounts with it running.
 * Both functions are stable.
 */
export function useOutsidePress(): OutsidePressWatch {
  const stopRef = useRef<(() => void) | null>(null);
  const stop = useCallback(() => {
    stopRef.current?.();
    stopRef.current = null;
  }, []);
  const start = useCallback<OutsidePressWatch['start']>(
    (owner, isInside, onOutside, options) => {
      stopRef.current?.();
      stopRef.current = watchOutsidePress(owner, isInside, onOutside, options);
    },
    [],
  );
  // Stops the outside-press listeners on unmount.
  useEffect(() => stop, [stop]);
  return useMemo(() => ({start, stop}), [start, stop]);
}

/** Whether `node` is the layer with this id, or inside it across shadow roots. */
function isWithinLayer(node: Node, layerId: string): boolean {
  for (
    let current: Node | null = node;
    current != null;
    current = current.parentNode ?? shadowHostOf(current)
  ) {
    if (isElement(current) && current.id === layerId) {
      return true;
    }
  }
  return false;
}

/**
 * Whether a press with this composed path is on a text field or in the
 * field's own layer, which may be hosted outside the field.
 *
 * @param path - The press's composed path.
 * @param field - The field that owns the layer.
 * @param layerId - The layer element's id.
 */
export function isPressInsideOwnedLayer(
  path: ReadonlyArray<EventTarget>,
  field: Element,
  layerId: string,
): boolean {
  return path.some(
    target =>
      target === field ||
      (layerId !== '' &&
        isNode(target) &&
        isElement(target) &&
        target.id === layerId),
  );
}

/**
 * Whether focus moving to `next` stays with a text field's own layer: on the
 * field, or in the layer, which may be hosted outside the field or inside a
 * shadow root. Each owner decides what a blur that fails this means,
 * including when `next` is null.
 *
 * @param next - The blur's `relatedTarget`.
 * @param field - The field that owns the layer.
 * @param layerId - The layer element's id.
 */
export function isFocusInsideOwnedLayer(
  next: EventTarget | null,
  field: Element | null | undefined,
  layerId: string,
): boolean {
  return (
    isNode(next) &&
    (field?.contains(next) === true || isWithinLayer(next, layerId))
  );
}