Skip to content

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

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

'use client';

/**
 * @file BottomSheetSwitcher.tsx
 * @input React context, StyleX, shared layer dismissal, the modal outlet
 *   registry, the private bottom-sheet stack, BottomSheetSwitcherContext,
 *   BottomSheetHostContext
 * @output Exports BottomSheetSwitcher and BottomSheetSwitcherProps
 * @position Core switcher for mutually exclusive BottomSheet flows. It is
 *   deprecated in favor of standalone step sheets.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/BottomSheet/BottomSheet.tsx
 * - /packages/core/src/BottomSheet/bottomSheetStack.ts
 * - /packages/core/src/BottomSheet/BottomSheetHostContext.ts
 * - /packages/core/src/BottomSheet/BottomSheetStacking.test.tsx
 * - /packages/core/src/BottomSheet/BottomSheetSwitcherContext.ts
 * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
 * - /docs/specs/components/BottomSheet/BottomSheetSwitcher.spec.md
 * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
 * - /packages/core/src/BottomSheet/index.ts
 * - /apps/storybook/stories/BottomSheetSwitcher.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/BottomSheet/BottomSheetSwitcherShowcase.tsx
 */

// `activeSheet` names the one interactive child, or null when the flow is
// closed. On a handoff the new sheet enters above the previous one. A taller
// previous sheet moves down until the top edges align. The previous sheet
// fades after both motions end.
//
// Each child sheet owns a native `<dialog>`. A scrim flow uses showModal(),
// and a no-scrim flow uses show() inside the flow wrapper. The switcher
// decides which dialog is presented, retained or hidden. It keeps one scrim
// across a handoff, holds the flow's one scroll lock and one dismissal
// registration, and returns focus to the flow's opener when the flow ends.
//
// The ref resolves to the host dialog: the active sheet's, the exiting
// sheet's during its exit, else the last host's. `id` and `data-testid`
// render on the host dialog only. Other dialog props apply to every sheet
// dialog. A scrim flow is one level of the sheet stack (bottomSheetStack.ts),
// and a step switch never changes that level. A modal flow's host dialog is
// a toast outlet (Layer/modalOutlet.ts).

import {
  use,
  useCallback,
  useEffect,
  useLayoutEffect,
  useMemo,
  useRef,
  useState,
  type KeyboardEvent as ReactKeyboardEvent,
  type MouseEvent as ReactMouseEvent,
  type ReactNode,
  type SyntheticEvent,
} from 'react';
import {useIsHydrating} from '../hooks/useIsHydrating';
import {useSettledOpen} from '../hooks/useSettledOpen';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import type {DialogPurpose} from '../Dialog';
import {useScrollLock} from '../hooks/useScrollLock';
import {useFocusTrapEscapeCompatibilitySignal} from '../hooks/useFocusTrap';
import {dispatchLayerEscapeKeyDown} from '../Layer/layerStack';
import {useLayerDismissal} from '../Layer/useLayerDismissal';
import {composeEventHandlers} from '../utils';
import {mergeRefs} from '../utils/mergeRefs';
import {useModalOutletWithoutRef} from '../Layer/modalOutlet';
import {BottomSheetHostContext} from './BottomSheetHostContext';
import {
  BOTTOM_SHEET_STACK_DEFAULT_VIEW,
  cancelScrimWrite,
  closeDialogKeepingFocus,
  focusSheetPanel,
  getBottomSheetBeneath,
  isClosingTogether,
  notifyBottomSheetHostChanged,
  presentStepModally,
  presentWithClearScrim,
  registerBottomSheet,
  reportClosedTogether,
  sealBottomSheetBatch,
  setBottomSheetOpen,
  writeScrimOpacity,
  type BottomSheetScrimWrite,
  type BottomSheetStackView,
} from './bottomSheetStack';
import {
  BottomSheetSwitcherContext,
  type BottomSheetSwitcherContextValue,
  type BottomSheetSwitcherDialogProps,
  type BottomSheetSwitcherPhase,
  type BottomSheetSwitcherTransitionEvent,
} from './BottomSheetSwitcherContext';

const styles = stylex.create({
  // A scrim flow's dialogs live in the top layer; the wrapper has no box.
  flow: {
    display: 'contents',
  },
  // show() leaves a no-scrim flow in the normal rendering tree, where DOM
  // order would decide which dialog paints in front. So the wrapper is the
  // flow's isolated surface: the dialogs order themselves inside it, and the
  // wrapper keeps the one overlay value of the old shared shell. It
  // passes pointer input through, and each panel opts back in. Consumers of
  // this mode must avoid transformed or clipping ancestors.
  flowNonModal: {
    display: 'block',
    position: 'fixed',
    inset: 0,
    width: '100%',
    height: '100%',
    pointerEvents: 'none',
    isolation: 'isolate',
    zIndex: 1000,
  },
});

type RetainedSheetPhase = 'covered' | 'aligning' | 'fading' | 'exiting';

interface SheetTransitionState {
  enteringSheet: string | null;
  retainedSheet: string | null;
  retainedPhase: RetainedSheetPhase | null;
  alignmentOffset: number;
  isAlignmentComplete: boolean;
}

const IDLE_TRANSITION: SheetTransitionState = {
  enteringSheet: null,
  retainedSheet: null,
  retainedPhase: null,
  alignmentOffset: 0,
  isAlignmentComplete: false,
};

const ALIGNMENT_THRESHOLD_PX = 1;

function transitionForActiveSheetChange(
  previousSheet: string | null,
  nextSheet: string | null,
): SheetTransitionState {
  if (previousSheet == null) {
    return IDLE_TRANSITION;
  }
  if (nextSheet == null) {
    return {
      enteringSheet: null,
      retainedSheet: previousSheet,
      retainedPhase: 'exiting',
      alignmentOffset: 0,
      isAlignmentComplete: false,
    };
  }
  return {
    enteringSheet: nextSheet,
    retainedSheet: previousSheet,
    retainedPhase: 'covered',
    alignmentOffset: 0,
    isAlignmentComplete: false,
  };
}

function alignmentOffsetForElements(
  enteringElement: HTMLElement | undefined,
  retainedElement: HTMLElement | undefined,
): number {
  if (enteringElement == null || retainedElement == null) {
    return 0;
  }
  const enteringPositioner = enteringElement.parentElement;
  const enteringTop =
    enteringPositioner?.getBoundingClientRect().top ??
    enteringElement.getBoundingClientRect().top;
  return Math.max(0, enteringTop - retainedElement.getBoundingClientRect().top);
}

/**
 * Keeps one object identity while its own enumerable entries are unchanged, so
 * the consumer's rest props can sit in a memoized context value without
 * refreshing every sheet host on each switcher render.
 */
function useShallowStable<T extends object>(value: T): T {
  const stableRef = useRef(value);
  const previous = stableRef.current;
  const previousKeys = Object.keys(previous) as (keyof T)[];
  const nextKeys = Object.keys(value) as (keyof T)[];
  const isSame =
    previousKeys.length === nextKeys.length &&
    nextKeys.every(key => Object.is(previous[key], value[key]));
  if (!isSame) {
    stableRef.current = value;
  }
  return stableRef.current;
}

/**
 * Hands the flow's scrim to `dialog` without a fade. The backdrop's opacity
 * transition would otherwise ease from the transparent value the entering
 * dialog was presented with, dipping the page's dim for one motion token
 * exactly when the previous dialog's backdrop disappears. Even a near-zero
 * duration paints its first frame at the start value, so the swap disables
 * the transition outright, flushes style so the new value is committed under
 * that rule, then restores the token for later gesture and exit fades.
 */
function takeOverScrim(dialog: HTMLDialogElement, opacity: number): void {
  dialog.style.setProperty('--_sheet-scrim-duration', '0s');
  dialog.style.setProperty('--_sheet-scrim-opacity', String(opacity));
  if (typeof getComputedStyle === 'function') {
    void getComputedStyle(dialog, '::backdrop').opacity;
  }
  dialog.style.removeProperty('--_sheet-scrim-duration');
}

/**
 * @deprecated Write each step as its own `BottomSheet` with `isOpen`, driven
 * by one state value that names the open step; closing the top sheet and
 * opening the next in the same update, from inside the open step, runs the
 * same replace handoff (see BottomSheet, "Replacing a sheet"). Keeps working until a future minor
 * release removes it: on its own as released (plus three fixes: a toast raised
 * from a step now renders above the flow and can be pressed, reduced motion
 * follows the reduced-motion design rules, and a flow whose active sheet is set on the
 * server renders closed until hydration, then opens that sheet settled), as
 * one stack level when stacked.
 */
export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {
  /**
   * Ref resolved to the native dialog hosting the flow: the active sheet's
   * dialog, which changes on a handoff; the exiting sheet's through its exit;
   * and, while the flow is closed, the dialog that hosted it last (or the
   * first mounted sheet's), so it is never null while a sheet is mounted,
   * from the first commit on.
   */
  ref?: React.Ref<HTMLDialogElement>;

  /** Called when the active sheet's native dialog receives a cancel event. */
  onCancel?: (event: SyntheticEvent<HTMLDialogElement>) => void;

  /**
   * ID of the interactive BottomSheet, or null when the flow should close.
   * Must match a nested BottomSheet's `sheetId`. The previous sheet may remain
   * visually present and inert while the new sheet enters, moving downward at
   * the same time if the new sheet is shorter, then fade away.
   */
  activeSheet: string | null;

  /** Called with null when the active sheet requests dismissal. */
  onActiveSheetChange: (sheetId: string | null) => void;

  /**
   * Whether each sheet dialog opens modally with a native ::backdrop.
   * Disable for a viewport-anchored, non-modal flow over an interactive page.
   * @default true
   */
  hasScrim?: boolean;

  /** BottomSheets identified by unique `sheetId` values. */
  children: ReactNode;
}

/**
 * Coordinates a set of BottomSheets so zero or one is active at a time, each
 * in its own native dialog. During a handoff the previous panel stays visible
 * and inert beneath the entering panel, then fades after motion completes.
 *
 * @deprecated Write each step as its own `BottomSheet` with `isOpen`, driven
 * by one state value that names the open step:
 *
 * ```
 * const [step, setStep] = useState(null);
 * const close = own => isOpen => !isOpen && setStep(c => (c === own ? null : c));
 * <BottomSheet isOpen={step === 'details'} onOpenChange={close('details')} label="Details">…</BottomSheet>
 * <BottomSheet isOpen={step === 'confirm'} onOpenChange={close('confirm')} label="Confirm">…</BottomSheet>
 * ```
 *
 * Closing the top sheet and opening the next in the same update, from a
 * control inside the open step, runs the same replace handoff, with no
 * `sheetId` and no switcher, for modal and `hasScrim={false}` flows alike; a
 * step changed from outside the flow's sheets closes and opens with the
 * sheets' own motion. The switcher keeps working until a future
 * minor release removes it: on its own as released (plus three fixes: a toast
 * raised from a step now renders above the flow and can be pressed, reduced
 * motion follows the reduced-motion design rules, and a flow whose active sheet is set
 * on the server renders closed until hydration, then opens that sheet
 * settled), and as one level of the stack when stacked with other sheets.
 */
export function BottomSheetSwitcher({
  activeSheet: activeSheetProp,
  onActiveSheetChange,
  hasScrim = true,
  children,
  ref,
  onCancel,
  onClick,
  onKeyDown,
  className,
  style,
  xstyle,
  ...restDialogProps
}: BottomSheetSwitcherProps) {
  // A flow rendered in another sheet's content is part of that sheet, as a
  // standalone sheet is: it is presented only while its host is open, leaves
  // with it, and comes back with it if its own `activeSheet` still names a
  // step (see BottomSheetHostContext). The consumer's state is never written
  // for it; with the host closed the flow simply reads as closed.
  const host = use(BottomSheetHostContext);
  const isHostOpen = host?.isOpen ?? true;
  // A flow with an active sheet on the server reads as closed until
  // hydration. It opens in the next render, the first one that can enter its
  // native host. A <dialog> painted open with aria-modal before it is modal
  // claims a state it does not have.
  const isHydrating = useIsHydrating();
  const activeSheet = isHostOpen && !isHydrating ? activeSheetProp : null;
  // The step active on the server opens settled, with no entry motion. The
  // first change of step animates (AST-013 FR13). It latches on the flow's
  // own request, because a hydrating host sheet reads as closed.
  const [settledSheet, releaseSettledSheet] = useSettledOpen(
    activeSheetProp,
    activeSheet,
    null,
  );
  // Every sheet host applies the switcher's dialog surface to its own dialog.
  const dialogProps = useShallowStable<BottomSheetSwitcherDialogProps>({
    ...restDialogProps,
    className,
    style,
    xstyle,
  });
  const hostDialogRef = useRef<HTMLDialogElement | null>(null);
  const flowRef = useRef<HTMLDivElement | null>(null);
  const sheetDialogsRef = useRef(new Map<string, HTMLDialogElement>());
  // Sheet ids in the order their dialogs mounted (tree order on first mount).
  // State, not a ref: the resting host below is rendered -- it carries the
  // consumer's `id` -- so a sheet mounting or leaving must re-render.
  const [sheetOrder, setSheetOrder] = useState<ReadonlyArray<string>>([]);
  // The sheet that hosted the flow last, kept while the flow is closed so the
  // ref and `id` stay on the dialog the person last used. State adjusted
  // during render (not a ref read during render): it changes exactly when
  // the presented host does, and the next render reads it.
  const [lastHostSheet, setLastHostSheet] = useState<string | null>(null);
  const presentationOrderRef = useRef(new Map<string, number>());
  const presentationCounterRef = useRef(0);
  const modalFlowRef = useRef(false);
  const triggerRef = useRef<HTMLElement | null>(null);
  const sheetElementsRef = useRef(new Map<string, HTMLElement>());
  const committedActiveSheetRef = useRef(activeSheet);
  const scrimOpacityRef = useRef(1);
  const scrimOwnerRef = useRef<string | null>(null);
  // The flow's place in the stack of presented modal sheets; default until
  // the stack reports, in the commit that presents the flow. The whole flow
  // is one level, keyed once for its lifetime, so a handoff keeps its rank.
  const stackKeyRef = useRef<object>({});
  const [stackView, setStackView] = useState<BottomSheetStackView>(
    BOTTOM_SHEET_STACK_DEFAULT_VIEW,
  );
  const stackViewRef = useRef(stackView);
  stackViewRef.current = stackView;
  const scrimWriteRef = useRef<BottomSheetScrimWrite>({frame: null});
  // Releases the pending scrim write frame on unmount.
  useEffect(() => () => cancelScrimWrite(scrimWriteRef.current), []);
  // What the flow's place in the stack was when it left the registry: its
  // depth and the open sheet beneath it. React runs the registration
  // effect's cleanup before the focus-return effect below in the same
  // commit, so by then the registry no longer knows the flow; the cleanup
  // records what the return needs.
  const leftStackRef = useRef<{
    depth: number;
    revealed: {element: HTMLDialogElement; focus: () => void} | null;
    closingTogether: boolean;
  } | null>(null);
  const [sheetPurposes, setSheetPurposes] = useState<
    ReadonlyMap<string, DialogPurpose>
  >(() => new Map());
  const [unmountedSheetIds, setUnmountedSheetIds] = useState<
    ReadonlySet<string>
  >(() => new Set());
  const [transition, setTransition] =
    useState<SheetTransitionState>(IDLE_TRANSITION);

  const activeSheetChanged = committedActiveSheetRef.current !== activeSheet;
  const visibleTransition = activeSheetChanged
    ? transitionForActiveSheetChange(
        committedActiveSheetRef.current,
        activeSheet,
      )
    : transition;
  const presentedActiveSheet =
    activeSheet != null && !unmountedSheetIds.has(activeSheet)
      ? activeSheet
      : null;
  const presentedRetainedSheet =
    visibleTransition.retainedSheet != null &&
    !unmountedSheetIds.has(visibleTransition.retainedSheet)
      ? visibleTransition.retainedSheet
      : null;
  const isFlowVisible =
    presentedActiveSheet != null || presentedRetainedSheet != null;
  const isModal = hasScrim && isFlowVisible;
  // The dialog that hosts the flow for its ref, its single-instance
  // attributes, and its dismissal registration: the active sheet's, the
  // retained sheet's while the flow closes through its exit, and while the
  // flow is closed the dialog that hosted it last (or the first mounted
  // sheet's before any open), so the ref resolves to a closed dialog element
  // rather than to null, as the shared dialog did. Which sheet mounts first
  // is known only once its dialog registers during the first commit: the
  // ref is attached to it in that same commit (below), and the rendered
  // `id` follows in the synchronous re-render that commit schedules, before
  // the first paint. Server markup therefore carries the `id` on no element.
  const presentedHostSheet = presentedActiveSheet ?? presentedRetainedSheet;
  if (presentedHostSheet != null && presentedHostSheet !== lastHostSheet) {
    setLastHostSheet(presentedHostSheet);
  }
  const restingHostSheet =
    lastHostSheet != null && sheetOrder.includes(lastHostSheet)
      ? lastHostSheet
      : (sheetOrder[0] ?? null);
  const hostSheet = presentedHostSheet ?? restingHostSheet;
  // The dialog whose backdrop paints the flow's one scrim. A retained sheet
  // keeps it through a handoff so the entering dialog, presented above it in
  // the top layer, does not dim the previous panel beneath its own backdrop.
  const scrimOwnerSheet = presentedRetainedSheet ?? presentedActiveSheet;
  // Whether the flow's one scrim is the stack's visible scrim. A flow stacked
  // above another sheet keeps every step backdrop clear: the sheet beneath
  // dims the page, and a second dim would double it.
  const flowOwnsStackScrim = !stackView.isStacked || stackView.ownsScrim;
  const isFlowOpen = activeSheet != null;
  const isFlowOpenRef = useRef(isFlowOpen);
  isFlowOpenRef.current = isFlowOpen;
  const isFlowClosing = isFlowVisible && activeSheet == null;
  const activeSheetPurpose =
    (activeSheet == null ? null : sheetPurposes.get(activeSheet)) ?? 'info';
  const allowsEscapeDismiss = activeSheetPurpose !== 'required';
  const allowsLightDismiss = activeSheetPurpose === 'info';

  useLayoutEffect(() => {
    const previousActiveSheet = committedActiveSheetRef.current;
    if (previousActiveSheet === activeSheet) {
      return;
    }
    committedActiveSheetRef.current = activeSheet;
    const nextTransition = transitionForActiveSheetChange(
      previousActiveSheet,
      activeSheet,
    );
    setTransition(
      nextTransition.retainedSheet != null &&
        !sheetElementsRef.current.has(nextTransition.retainedSheet)
        ? IDLE_TRANSITION
        : nextTransition,
    );
  }, [activeSheet]);

  const dismissOnEscape = useCallback(() => {
    if (allowsEscapeDismiss) {
      onActiveSheetChange(null);
    }
  }, [allowsEscapeDismiss, onActiveSheetChange]);
  const dismissOnLightInteraction = useCallback(() => {
    if (allowsLightDismiss) {
      onActiveSheetChange(null);
    }
  }, [allowsLightDismiss, onActiveSheetChange]);
  // Focus containment is the native modal dialog's: showModal() makes the
  // page inert, so Tab cannot leave the active sheet. The released read-only
  // `hasActiveFocusTrapEscape()` signal still reports a modal flow as a trap,
  // as it did when a JavaScript trap backed it.
  useFocusTrapEscapeCompatibilitySignal(isModal);
  // One lock for the whole modal flow, as on a shared dialog: `isModal` stays
  // true through a handoff (two dialogs open) and through the exit motion, so
  // the shared counter is taken once and given back once.
  useScrollLock(isModal);
  const {shouldDismissOnCloseRequest} = useLayerDismissal({
    isActive: isFlowVisible,
    escapeBehavior: allowsEscapeDismiss ? 'close' : 'block',
    onDismiss: dismissOnEscape,
    getContainer: () => hostDialogRef.current,
    // A covered flow stands down from dismissal while a sheet covers it, so
    // Escape and the platform close request reach the top sheet; see the
    // standalone host.
    isPresent: () =>
      (hostDialogRef.current?.open ?? false) && !stackViewRef.current.isCovered,
  });

  // Point the consumer ref and the dismissal registration at the host dialog.
  // Sheet hosts register their dialogs during commit, so by the time this
  // layout effect runs the map already names the dialog for `hostSheet` --
  // and, in the first commit of a flow that mounts closed, the first
  // registered dialog before `sheetOrder` has caught up, so a parent's own
  // mount effects already find the ref resolved. The ref is attached the way
  // React attaches one: a callback ref's returned cleanup runs on detach, and
  // only a ref without one receives null. Attachment follows the resolved
  // element, not the render that resolved it: the re-render that catches
  // `sheetOrder` up resolves the same dialog and leaves the ref alone.
  const attachedRef = useRef<{
    ref: React.Ref<HTMLDialogElement> | undefined;
    host: HTMLDialogElement;
    detach: (() => void) | undefined;
  } | null>(null);
  useLayoutEffect(() => {
    const host =
      hostSheet == null
        ? (sheetDialogsRef.current.values().next().value ?? null)
        : (sheetDialogsRef.current.get(hostSheet) ?? null);
    const previousHost = hostDialogRef.current;
    hostDialogRef.current = host;
    if (host != null && host !== previousHost) {
      // The level's dialog changed on a handoff; the registry puts the
      // sheets above the flow back above its new dialog.
      notifyBottomSheetHostChanged(stackKeyRef.current);
    }
    const attached = attachedRef.current;
    if (attached?.host === host && attached.ref === ref) {
      return;
    }
    attached?.detach?.();
    if (host == null) {
      attachedRef.current = null;
      return;
    }
    const detach = mergeRefs(ref)(host);
    attachedRef.current = {
      ref,
      host,
      detach: typeof detach === 'function' ? detach : undefined,
    };
  }, [hostSheet, ref, sheetOrder]);
  useLayoutEffect(
    () => () => {
      hostDialogRef.current = null;
      attachedRef.current?.detach?.();
      attachedRef.current = null;
    },
    [],
  );

  // While the flow is modal, its host dialog is an outlet for app-global
  // surfaces (toasts), as a standalone scrim sheet's is. The supply follows
  // `hostSheet` across a handoff, and the fading retained dialog is never the
  // outlet. A closing flow stops supplying at once. Passive: it runs after the
  // layout effects that present the step dialogs.
  // The flow has no element for the outlet's ref. Its wrapper's ref is the
  // sheet stack's tree-order anchor, which the stack reads in the closing
  // commit, and the element of its host step changes on a handoff.
  useModalOutletWithoutRef(
    hostDialogRef,
    isModal && isFlowOpen,
    stackView.isTop || !stackView.isStacked,
    'bottom-sheet',
    hostSheet,
  );

  // Focus return is native per dialog: each showModal() records the focused
  // element and close() focuses it again. That serves a one-sheet flow, but
  // the second sheet of a flow records a control inside the first, which is
  // hidden by the time the flow ends, so the browser's return lands nowhere.
  // The flow therefore remembers its own opener -- the page element focused
  // before the first modal present -- and focuses it after the last dialog
  // closes. Sheet hosts ask before presenting modally, so the capture sees
  // the page element; hosts present in their own layout effects, which run
  // before the one below, so the restore follows the last dialog's close.
  const onBeforeSheetPresent = useCallback((sheetId: string) => {
    if (triggerRef.current == null) {
      triggerRef.current = document.activeElement as HTMLElement | null;
    }
    modalFlowRef.current = true;
    presentationCounterRef.current += 1;
    presentationOrderRef.current.set(sheetId, presentationCounterRef.current);
  }, []);
  // Syncs document focus with the flow's visibility. When the flow hides, focus
  // goes to the opener, to the sheet now on top, or to the target of the
  // registry.
  useLayoutEffect(() => {
    if (isFlowVisible) {
      if (!hasScrim) {
        modalFlowRef.current = false;
      }
      return;
    }
    const left = leftStackRef.current;
    leftStackRef.current = null;
    if (modalFlowRef.current) {
      const depth = left?.depth ?? stackViewRef.current.depth;
      if (depth > 0) {
        // Closed from code beneath open sheets: focus stays in the sheet on
        // top; the flow's own close must not pull it back to the opener.
      } else if (left?.closingTogether) {
        // Closing together with the other sheets of its stack ("Close all"):
        // the registry returns focus once, after the last dialog has left.
        reportClosedTogether(stackKeyRef.current);
      } else {
        // With a sheet still open beneath the flow, focus returns into that
        // sheet: to the opener when it is there, else to the sheet's panel.
        // Otherwise, like the browser's own return on close(), without
        // scrolling: the page kept its scroll offset under the lock, and an
        // opener scrolled out of view must not drag the page back to itself.
        const revealed =
          left?.revealed ?? getBottomSheetBeneath(stackKeyRef.current);
        const trigger = triggerRef.current;
        if (
          revealed != null &&
          (trigger == null || !revealed.element.contains(trigger))
        ) {
          revealed.focus();
        } else {
          trigger?.focus({preventScroll: true});
        }
      }
    }
    triggerRef.current = null;
    modalFlowRef.current = false;
    presentationOrderRef.current.clear();
  }, [hasScrim, isFlowVisible]);

  // A scrim flow is one level of the bottom-sheet stack while it is visible.
  // The step hosts present their own dialogs; the registry re-presents the
  // level's dialog only to restore open order, moves focus into the active
  // panel when the flow lands on top, and reports the flow's view (top,
  // covered, depth, scrim ownership). Switching the step never
  // re-registers, so a switch in place keeps the flow's position.
  useLayoutEffect(() => {
    if (!isFlowVisible || !hasScrim) {
      return;
    }
    const key = stackKeyRef.current;
    const unregister = registerBottomSheet(
      {
        key,
        getElement: () => hostDialogRef.current,
        // The flow wrapper contains every step dialog, so it orders the flow
        // against sheets opened in the same commit whichever step is active.
        getTreeAnchor: () => flowRef.current,
        show: () => {
          const dialog = hostDialogRef.current;
          if (dialog == null || dialog.open) {
            return;
          }
          const hostId = [...sheetDialogsRef.current].find(
            ([, candidate]) => candidate === dialog,
          )?.[0];
          if (hostId != null) {
            onBeforeSheetPresent(hostId);
          }
          const ownsFlowScrim =
            hostId != null && hostId === scrimOwnerRef.current;
          const view = stackViewRef.current;
          if (ownsFlowScrim && (!view.isStacked || view.ownsScrim)) {
            dialog.style.setProperty(
              '--_sheet-scrim-opacity',
              String(scrimOpacityRef.current),
            );
            presentStepModally(dialog);
          } else {
            presentWithClearScrim(dialog);
          }
        },
        hide: () => closeDialogKeepingFocus(hostDialogRef.current),
        getReturnTarget: () => triggerRef.current,
        focus: reason => {
          const active = committedActiveSheetRef.current;
          const panel =
            active == null ? undefined : sheetElementsRef.current.get(active);
          focusSheetPanel(panel ?? null, reason, true);
        },
        onView: view => {
          const previous = stackViewRef.current;
          stackViewRef.current = view;
          setStackView(view);
          // A change of the stack's scrim owner lands with no fade on the
          // flow's own owner dialog; see writeScrimOpacity.
          const owner =
            scrimOwnerRef.current == null
              ? null
              : (sheetDialogsRef.current.get(scrimOwnerRef.current) ?? null);
          if (owner == null) {
            return;
          }
          const ownsNow = !view.isStacked || view.ownsScrim;
          const ownedBefore = !previous.isStacked || previous.ownsScrim;
          if (isFlowOpenRef.current && ownsNow !== ownedBefore) {
            writeScrimOpacity(
              owner,
              ownsNow && scrimOpacityRef.current > 0 ? '1' : '0',
              scrimWriteRef.current,
            );
          } else if (!isFlowOpenRef.current && view.isScrimTakenOver) {
            writeScrimOpacity(owner, '0', scrimWriteRef.current);
          }
        },
      },
      isFlowOpenRef.current,
    );
    return () => {
      // Read before the entry leaves: the focus-return effect runs after.
      leftStackRef.current = {
        depth: stackViewRef.current.depth,
        revealed: getBottomSheetBeneath(key),
        closingTogether: isClosingTogether(key),
      };
      unregister();
    };
  }, [hasScrim, isFlowVisible, onBeforeSheetPresent]);
  // Syncs the open state of this flow in the sheet stack registry.
  useLayoutEffect(() => {
    if (isFlowVisible && hasScrim) {
      setBottomSheetOpen(stackKeyRef.current, isFlowOpen);
    }
  }, [hasScrim, isFlowOpen, isFlowVisible]);
  // Closes a batch of same-commit opens; see sealBottomSheetBatch.
  useEffect(() => {
    sealBottomSheetBatch();
  });

  const getSheetPhase = useCallback(
    (sheetId: string): BottomSheetSwitcherPhase => {
      if (sheetId === activeSheet) {
        return sheetId === visibleTransition.enteringSheet
          ? 'entering'
          : 'active';
      }
      if (sheetId === visibleTransition.retainedSheet) {
        return visibleTransition.retainedPhase ?? 'hidden';
      }
      return 'hidden';
    },
    [activeSheet, visibleTransition],
  );

  const getSheetAlignmentOffset = useCallback(
    (sheetId: string) =>
      visibleTransition.retainedSheet === sheetId
        ? visibleTransition.alignmentOffset
        : 0,
    [visibleTransition],
  );

  const isScrimOwner = useCallback(
    (sheetId: string) => sheetId === scrimOwnerSheet,
    [scrimOwnerSheet],
  );

  const registerSheetElement = useCallback(
    (sheetId: string, element: HTMLElement | null) => {
      if (element == null) {
        sheetElementsRef.current.delete(sheetId);
        setUnmountedSheetIds(current => {
          if (current.has(sheetId)) {
            return current;
          }
          const next = new Set(current);
          next.add(sheetId);
          return next;
        });
        setTransition(current =>
          current.retainedSheet === sheetId ? IDLE_TRANSITION : current,
        );
      } else {
        sheetElementsRef.current.set(sheetId, element);
        setUnmountedSheetIds(current => {
          if (!current.has(sheetId)) {
            return current;
          }
          const next = new Set(current);
          next.delete(sheetId);
          return next;
        });
      }
    },
    [],
  );

  const registerSheetDialog = useCallback(
    (sheetId: string, dialog: HTMLDialogElement | null) => {
      if (dialog == null) {
        sheetDialogsRef.current.delete(sheetId);
        presentationOrderRef.current.delete(sheetId);
        setSheetOrder(current =>
          current.includes(sheetId)
            ? current.filter(id => id !== sheetId)
            : current,
        );
      } else {
        sheetDialogsRef.current.set(sheetId, dialog);
        setSheetOrder(current =>
          current.includes(sheetId) ? current : [...current, sheetId],
        );
      }
    },
    [],
  );

  const isCoveredInTopLayer = useCallback((sheetId: string) => {
    const order = presentationOrderRef.current;
    const own = order.get(sheetId);
    if (own == null) {
      return false;
    }
    for (const [otherId, stamp] of order) {
      if (
        otherId !== sheetId &&
        stamp > own &&
        sheetDialogsRef.current.get(otherId)?.open
      ) {
        return true;
      }
    }
    return false;
  }, []);

  const registerSheetPurpose = useCallback(
    (sheetId: string, purpose: DialogPurpose | null) => {
      setSheetPurposes(current => {
        if (purpose == null) {
          if (!current.has(sheetId)) {
            return current;
          }
          const next = new Map(current);
          next.delete(sheetId);
          return next;
        }
        if (current.get(sheetId) === purpose) {
          return current;
        }
        const next = new Map(current);
        next.set(sheetId, purpose);
        return next;
      });
    },
    [],
  );

  useLayoutEffect(() => {
    // eslint-disable-next-line @eslint-react/set-state-in-effect -- clear a retained sheet after its panel unmounts
    setTransition(current =>
      current.retainedSheet != null &&
      unmountedSheetIds.has(current.retainedSheet)
        ? IDLE_TRANSITION
        : current,
    );
  }, [unmountedSheetIds]);

  const onSheetEnterStart = useCallback((sheetId: string) => {
    setTransition(current => {
      if (
        current.enteringSheet !== sheetId ||
        current.retainedSheet == null ||
        current.retainedPhase !== 'covered'
      ) {
        return current;
      }
      const alignmentOffset = alignmentOffsetForElements(
        sheetElementsRef.current.get(sheetId),
        sheetElementsRef.current.get(current.retainedSheet),
      );
      if (alignmentOffset <= ALIGNMENT_THRESHOLD_PX) {
        return current;
      }
      return {
        ...current,
        retainedPhase: 'aligning',
        alignmentOffset,
        isAlignmentComplete: false,
      };
    });
  }, []);

  const onSheetTransitionComplete = useCallback(
    ({sheetId, phase}: BottomSheetSwitcherTransitionEvent) => {
      setTransition(current => {
        if (phase === 'entering') {
          if (current.enteringSheet !== sheetId) {
            return current;
          }
          if (current.retainedSheet == null) {
            return IDLE_TRANSITION;
          }
          if (
            current.retainedPhase === 'aligning' &&
            !current.isAlignmentComplete
          ) {
            return {...current, enteringSheet: null};
          }
          return {
            ...current,
            enteringSheet: null,
            retainedPhase: 'fading',
          };
        }

        if (
          phase === 'aligning' &&
          current.retainedSheet === sheetId &&
          current.retainedPhase === 'aligning'
        ) {
          return current.enteringSheet == null
            ? {...current, retainedPhase: 'fading'}
            : {...current, isAlignmentComplete: true};
        }

        if (
          (phase === 'fading' || phase === 'exiting') &&
          current.retainedSheet === sheetId &&
          current.retainedPhase === phase
        ) {
          return IDLE_TRANSITION;
        }

        return current;
      });
    },
    [],
  );

  // One scrim for the flow. Only the owning dialog's backdrop carries the
  // current opacity; every other presented dialog keeps its backdrop clear.
  // When ownership moves — the retained dialog has faded and closes, or a
  // rapid replacement hides it — the new owner takes the value without a
  // fade, in the same layout pass that closes the old one.
  // A flow stacked above another sheet keeps every backdrop clear: the
  // stack's owner beneath dims the page (`flowOwnsStackScrim`).
  const applyScrimOpacity = useCallback(() => {
    const owner =
      scrimOwnerSheet == null
        ? null
        : (sheetDialogsRef.current.get(scrimOwnerSheet) ?? null);
    const value = flowOwnsStackScrim ? scrimOpacityRef.current : 0;
    // A fresh open keeps the backdrop's @starting-style fade; only a hand
    // from one presented dialog to another swaps without one.
    const ownerChanged =
      scrimOwnerRef.current != null &&
      scrimOwnerRef.current !== scrimOwnerSheet;
    scrimOwnerRef.current = scrimOwnerSheet;
    for (const [sheetId, dialog] of sheetDialogsRef.current) {
      if (dialog === owner) {
        if (ownerChanged && dialog.open) {
          takeOverScrim(dialog, value);
        } else {
          dialog.style.setProperty('--_sheet-scrim-opacity', String(value));
        }
      } else if (sheetId !== scrimOwnerSheet) {
        dialog.style.setProperty('--_sheet-scrim-opacity', '0');
      }
    }
  }, [flowOwnsStackScrim, scrimOwnerSheet]);
  const onSheetScrimOpacityChange = useCallback(
    (sheetId: string, opacity: number) => {
      // A pointer captured by the outgoing sheet can keep delivering gesture
      // events after a handoff. Only the currently committed sheet owns the
      // flow's scrim value, so stale gesture updates must not reach it.
      if (sheetId !== committedActiveSheetRef.current) {
        return;
      }
      scrimOpacityRef.current = opacity;
      applyScrimOpacity();
    },
    [applyScrimOpacity],
  );

  // A committed selection resets the flow's scrim value -- 1 while a sheet
  // is active, 0 for the exit fade -- and writes it to the owning backdrop in
  // the same effect; a gesture then adjusts the value through
  // `onSheetScrimOpacityChange` until the next selection.
  useLayoutEffect(() => {
    scrimOpacityRef.current = activeSheet == null ? 0 : 1;
    applyScrimOpacity();
  }, [applyScrimOpacity, activeSheet, hasScrim, isFlowVisible]);

  // A `cancel` that bubbles up from inside a step is not a close request for
  // the flow: a file input fires one when its picker is dismissed, and it
  // reaches the step's dialog. Only a `cancel` fired at a sheet dialog itself
  // dismisses; the bubbled one is left alone.
  const handleCancel = useCallback(
    (event: SyntheticEvent<HTMLDialogElement>) => {
      if (event.target !== event.currentTarget) {
        return;
      }
      event.preventDefault();
      if (shouldDismissOnCloseRequest()) {
        dismissOnEscape();
      }
    },
    [dismissOnEscape, shouldDismissOnCloseRequest],
  );
  const handleKeyDown = useCallback(
    (event: ReactKeyboardEvent<HTMLDialogElement>) => {
      // A consumer may stop propagation without claiming Escape. Route that
      // unprevented press now so the shared stack still chooses the top layer;
      // its preventDefault marker makes the document listener a no-op if the
      // event does continue bubbling.
      dispatchLayerEscapeKeyDown(event.nativeEvent);
    },
    [],
  );
  const handleClick = useCallback(
    (event: ReactMouseEvent<HTMLDialogElement>) => {
      // A `::backdrop` click targets its dialog element. Only the active
      // sheet's backdrop is the flow's scrim; a retained dialog is inert and
      // a hidden one closed, so neither can be clicked, but be explicit.
      if (
        hasScrim &&
        event.target === event.currentTarget &&
        event.currentTarget === hostDialogRef.current
      ) {
        dismissOnLightInteraction();
      }
    },
    [dismissOnLightInteraction, hasScrim],
  );
  const onDialogCancel = useMemo(
    () => composeEventHandlers(onCancel, handleCancel),
    [handleCancel, onCancel],
  );
  const onDialogClick = useMemo(
    () => composeEventHandlers(onClick, handleClick),
    [handleClick, onClick],
  );
  const onDialogKeyDown = useMemo(
    () => composeEventHandlers(onKeyDown, handleKeyDown),
    [handleKeyDown, onKeyDown],
  );

  const contextValue = useMemo<BottomSheetSwitcherContextValue>(
    () => ({
      activeSheet,
      settledSheet,
      releaseSettledSheet,
      hasScrim,
      onActiveSheetChange,
      getSheetPhase,
      getSheetAlignmentOffset,
      hostSheet,
      isScrimOwner,
      isFlowClosing,
      registerSheetElement,
      registerSheetDialog,
      registerSheetPurpose,
      onBeforeSheetPresent,
      isCoveredInTopLayer,
      onSheetEnterStart,
      onSheetTransitionComplete,
      onSheetScrimOpacityChange,
      stackView,
      dialogProps,
      onDialogCancel,
      onDialogClick,
      onDialogKeyDown,
    }),
    [
      activeSheet,
      dialogProps,
      getSheetAlignmentOffset,
      getSheetPhase,
      hasScrim,
      hostSheet,
      isCoveredInTopLayer,
      isFlowClosing,
      isScrimOwner,
      onActiveSheetChange,
      onBeforeSheetPresent,
      onDialogCancel,
      onDialogClick,
      onDialogKeyDown,
      onSheetEnterStart,
      onSheetScrimOpacityChange,
      onSheetTransitionComplete,
      registerSheetDialog,
      registerSheetElement,
      registerSheetPurpose,
      releaseSettledSheet,
      settledSheet,
      stackView,
    ],
  );

  return (
    <BottomSheetSwitcherContext value={contextValue}>
      <div
        ref={flowRef}
        {...stylex.props(
          styles.flow,
          !hasScrim && isFlowVisible && styles.flowNonModal,
        )}>
        {children}
      </div>
    </BottomSheetSwitcherContext>
  );
}

BottomSheetSwitcher.displayName = 'BottomSheetSwitcher';