Skip to content

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

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

'use client';

/**
 * @file useDrawerDialogPresence.ts
 * @input Controlled open state, modal mode, dialog ref, and rendered-state setter
 * @output Coordinates native top-layer presence, the touch entrance's input hold, exit timing, focus restoration, and unmount cleanup, including focus return after removal while open
 * @position Drawer-internal hook; consumed only by Drawer.tsx
 *
 * The drawer has two independent notions of presence:
 * - React's rendered state keeps the panel visible for its CSS exit.
 * - Native `showModal()` or `showPopover()` state keeps it in the browser top
 *   layer.
 *
 * Their close ordering is a browser-visible invariant: the panel must finish
 * its exit, then leave the active native host and hide in the same task. If the
 * hide lands a frame later, a transformed ancestor becomes the containing block
 * for the now-non-top-layer `position: fixed` panel and it paints back inside
 * the page for one frame.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Drawer/Drawer.test.tsx
 * - /packages/core/src/Drawer/__tests__/DrawerTouchEntrance.interaction.browser.spec.ts
 * - /.github/scripts/modal-close-visibility.js
 */

import {
  useEffect,
  useRef,
  type Dispatch,
  type RefObject,
  type SetStateAction,
} from 'react';
import {flushSync} from 'react-dom';
import {holdEntranceInput} from '../Layer/holdEntranceInput';
import {notifyTopLayerEntry} from '../Layer/modalOutlet';
import {runPopoverOperation} from '../Layer/popoverOperations';
import {prepareFocusReturnOnRemoval} from '../utils/focusReturn';

/** Slack past the computed transition before the backstop gives up waiting. */
const EXIT_BACKSTOP_BUFFER_MS = 50;

/**
 * Hold used when the transition duration cannot be read — an unresolved
 * `var()` outside a real browser. Picking a fixed number would otherwise make
 * an assumption about the consumer's theme.
 */
const EXIT_FALLBACK_MS = 250;

type UseDrawerDialogPresenceOptions = {
  dialogRef: RefObject<HTMLDialogElement | null>;
  isOpen: boolean;
  isModal: boolean;
  setIsRendered: Dispatch<SetStateAction<boolean>>;
};

function isPopoverOpen(dialog: HTMLDialogElement): boolean {
  try {
    return dialog.matches(':popover-open');
  } catch {
    // jsdom and pre-Popover browsers do not recognize :popover-open.
    return false;
  }
}

function isDrawerHostOpen(
  dialog: HTMLDialogElement,
  isModal: boolean,
): boolean {
  return isModal ? dialog.open : isPopoverOpen(dialog) || dialog.open;
}

function showDrawerHost(dialog: HTMLDialogElement, isModal: boolean): void {
  if (isModal) {
    dialog.showModal();
  } else if (typeof dialog.showPopover === 'function') {
    // The dialog's show focuses its first control. A tooltip on that control
    // then asks to show. The browser refuses a show inside another show.
    // Counting this show makes the tooltip wait until it ends.
    runPopoverOperation(dialog.ownerDocument, () => dialog.showPopover());
    // The drawer is now the newest top-layer entry: global hosts shown before
    // it (the toast viewport) re-enter above it, as they do above a modal.
    notifyTopLayerEntry();
  } else {
    // Reduced fallback for browsers below the Popover API support floor.
    dialog.show();
  }
}

function dispatchDialogClose(dialog: HTMLDialogElement): void {
  const EventConstructor = dialog.ownerDocument.defaultView?.Event ?? Event;
  dialog.dispatchEvent(new EventConstructor('close'));
}

/**
 * Leaves the active native host. Returns whether the caller owes a synthetic
 * `close` dispatch: `dialog.close()` used to power the non-modal path, and
 * consumers observe its native `close` event through refs/onClose. Popover
 * dismissal has no equivalent event, so that public DOM contract is preserved
 * explicitly — but by the caller, not here. Native `close` is queued as a
 * task, so a consumer's listener always ran after this hook's own focus
 * restore; the synthetic event must keep that ordering (and fire exactly once
 * per exit, including the unmount path).
 */
function hideDrawerHost(dialog: HTMLDialogElement, isModal: boolean): boolean {
  if (!isModal && typeof dialog.hidePopover === 'function') {
    dialog.hidePopover();
    return true;
  }
  if (dialog.open) {
    dialog.close();
  }
  return false;
}

/**
 * Coordinates the native dialog and React-rendered presence for Drawer.
 *
 * Opening captures the trigger, enters the modal-dialog or manual-popover host,
 * and honours the component's `data-autofocus` contract. Closing waits for the
 * actual transform transition (with a computed-duration backstop), then leaves
 * the native host and synchronously hides the panel before the browser can paint
 * it outside the top layer, restores focus to the captured trigger, and only
 * then dispatches the popover host's synthetic `close`. Unmount cleanup closes
 * a host left open by React Activity or a removed subtree.
 */
export function useDrawerDialogPresence({
  dialogRef,
  isOpen,
  isModal,
  setIsRendered,
}: UseDrawerDialogPresenceOptions): void {
  // Element focused when the drawer opened — restored on close.
  const triggerElementRef = useRef<HTMLElement | null>(null);

  // Syncs the drawer's native host with `isOpen`. It shows or hides the
  // top-layer host, keeps the opener, waits for the exit, and returns focus.
  useEffect(() => {
    const dialog = dialogRef.current;
    if (!dialog) {
      return;
    }

    if (isOpen) {
      if (!isDrawerHostOpen(dialog, isModal)) {
        triggerElementRef.current =
          document.activeElement as HTMLElement | null;
        showDrawerHost(dialog, isModal);
        // React's autoFocus calls .focus() during commit, before the native host
        // is visible, so it silently fails — honour data-autofocus instead (same
        // contract as Dialog).
        dialog.querySelector<HTMLElement>('[data-autofocus]')?.focus();
      }
      // Under a coarse primary pointer, a tap or a drag during the slide-in
      // reaches nothing. A non-modal drawer holds only its panel, so its page
      // stays live. Keys and assistive technology stay live. The hold ends
      // with the slide-in, or with this effect's cleanup on a close or
      // unmount.
      return holdEntranceInput(dialog, {isModal}) ?? undefined;
    }

    if (!isDrawerHostOpen(dialog, isModal)) {
      return;
    }

    return waitForDrawerExit(dialog, () => {
      const owesCloseEvent = hideDrawerHost(dialog, isModal);
      // flushSync, not a plain setState: React's default scheduling can land
      // the commit after the next paint, and that one frame is exactly the
      // bug — the panel paints outside the top layer. Both happen in this
      // task, so the browser never gets to paint between them.
      // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the panel must stop painting in the task the native host closes
      flushSync(() => {
        setIsRendered(false);
      });
      // Return focus after leaving the native host: a modal dialog makes the
      // rest of the document inert, so focusing earlier silently fails.
      triggerElementRef.current?.focus();
      triggerElementRef.current = null;
      // The synthetic popover close fires after the focus restore above,
      // mirroring the task-queued native event: a consumer close listener
      // that retargets focus (master-detail row switching) gets the last word.
      if (owesCloseEvent) {
        dispatchDialogClose(dialog);
      }
    });
  }, [dialogRef, isModal, isOpen, setIsRendered]);

  // Leave the active native host on unmount. When the drawer is mounted inside
  // an <Activity> that flips to mode="hidden", React runs effect cleanups (with
  // stale isOpen) instead of re-running the effect with isOpen=false. Leaving
  // the host active would strand the top-layer surface and skip the next open.
  // This is deliberately separate from the open/close effect: putting it in
  // that cleanup would cut off every delayed slide-out.
  useEffect(() => {
    const dialog = dialogRef.current;
    const returnFocusOnRemoval =
      dialog == null ? null : prepareFocusReturnOnRemoval(dialog);
    return () => {
      if (dialog && isDrawerHostOpen(dialog, isModal)) {
        if (hideDrawerHost(dialog, isModal)) {
          // The drawer is being torn down, so the owed synthetic close fires
          // immediately (still exactly once).
          dispatchDialogClose(dialog);
        }
      }
      // Removal already hid a popover host, so this runs outside the check
      // above. The trigger is null outside an open cycle.
      returnFocusOnRemoval?.(triggerElementRef.current);
    };
  }, [dialogRef, isModal]);
}

/**
 * Wait for the panel's transform transition, with a computed-duration
 * backstop. Mirrors BottomSheetPanel.waitForTransition: the native event is
 * authoritative, and the timeout only prevents a lost event from stranding an
 * open dialog.
 */
function waitForDrawerExit(
  element: HTMLDialogElement,
  complete: () => void,
): () => void {
  let done = false;
  let timer: ReturnType<typeof setTimeout> | null = null;

  const finish = () => {
    if (done) {
      return;
    }
    done = true;
    if (timer != null) {
      clearTimeout(timer);
    }
    element.removeEventListener('transitionend', handleTransitionEnd);
    element.removeEventListener('transitioncancel', handleTransitionEnd);
    complete();
  };

  const handleTransitionEnd = (event: TransitionEvent) => {
    if (event.target === element && event.propertyName === 'transform') {
      finish();
    }
  };

  element.addEventListener('transitionend', handleTransitionEnd);
  element.addEventListener('transitioncancel', handleTransitionEnd);

  const transitionMs = readTransformTransitionMs(element);
  timer = setTimeout(
    finish,
    (transitionMs ?? EXIT_FALLBACK_MS) + EXIT_BACKSTOP_BUFFER_MS,
  );

  return () => {
    done = true;
    if (timer != null) {
      clearTimeout(timer);
    }
    element.removeEventListener('transitionend', handleTransitionEnd);
    element.removeEventListener('transitioncancel', handleTransitionEnd);
  };
}

/** Read the transform transition's duration + delay from computed CSS. */
function readTransformTransitionMs(element: HTMLElement): number | null {
  const computed = window.getComputedStyle(element);
  const properties = computed.transitionProperty
    .split(',')
    .map(value => value.trim());
  const durations = parseTimes(computed.transitionDuration);
  const delays = parseTimes(computed.transitionDelay);

  if (
    properties.length === 0 ||
    durations.length === 0 ||
    delays.length === 0 ||
    durations.includes(null) ||
    delays.includes(null)
  ) {
    return null;
  }

  return properties.reduce((longest, property, index) => {
    if (property !== 'transform' && property !== 'all') {
      return longest;
    }
    const duration = durations[index % durations.length];
    const delay = delays[index % delays.length];
    return Math.max(longest, (duration ?? 0) + (delay ?? 0));
  }, 0);
}

function parseTimes(value: string): (number | null)[] {
  return value.split(',').map(part => {
    const trimmed = part.trim();
    const time = Number.parseFloat(trimmed);
    if (!Number.isFinite(time)) {
      return null;
    }
    if (trimmed.endsWith('ms')) {
      return time;
    }
    return trimmed.endsWith('s') ? time * 1000 : null;
  });
}