@astryxdesign/core 0.7.3 → 0.7.4-canary.3f6ea7d

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file BottomSheetSwitcher.tsx
- * @input Uses React context, StyleX, theme tokens, shared layer dismissal, focus/scroll-lock hooks, BottomSheetSwitcherContext
+ * @input Uses React context, StyleX, shared layer dismissal, BottomSheetSwitcherContext
  * @output Exports BottomSheetSwitcher and BottomSheetSwitcherProps
  * @position Core switcher for mutually exclusive BottomSheet flows
  *
@@ -15,14 +15,37 @@
  * down at the same time until their top edges align; otherwise it stays
  * stationary. The previous sheet fades only after both motions complete.
  *
- * All child sheets render as panels inside one switcher-owned `<dialog>`. A
- * scrim flow calls showModal() once and keeps that native top-layer dialog open
- * across every handoff. A no-scrim flow calls show() on the same non-modal shell.
- * This keeps one modal boundary and one native ::backdrop without a portal.
+ * Every child sheet owns a native `<dialog>`, exactly like a standalone
+ * sheet: a scrim flow presents each sheet with showModal(), a no-scrim flow
+ * with show(). The browser then does what a modal dialog does -- the page is
+ * inert, focus stays in the top-layer dialog, Escape and the platform close
+ * arrive as `cancel`. The switcher is the coordinator: it decides which
+ * sheet dialog is presented, retained, or hidden, keeps one scrim painted
+ * across a handoff (the retained sheet's backdrop until it fades, then the
+ * new sheet's, swapped without a fade), holds the flow's one page scroll
+ * lock (the shared useScrollLock, as Dialog uses, acquired once while the
+ * flow is presented and released after its exit, never per step) and the
+ * one layer-dismissal registration, and returns focus to the flow's opener
+ * when the flow ends, which no single dialog can know.
+ *
+ * The switcher's one element is a flow wrapper. In a scrim flow it has no box
+ * (`display: contents`): the dialogs sit in the top layer. In a no-scrim flow
+ * it is the isolated surface that orders the sheet dialogs locally, the way
+ * the shared shell once did, so no sheet needs a page-level value of its own.
+ *
+ * Its `ref` resolves to the host dialog: the one presenting the active sheet,
+ * the exiting sheet's through its exit, and the last host's (or the first
+ * mounted sheet's) while the flow is closed, so the ref is never null while a
+ * sheet is mounted. `id` and `data-testid` render on the host dialog only:
+ * a flow that mounts open carries them on the active sheet's dialog in server
+ * markup too; a flow that mounts closed carries them from the first commit's
+ * synchronous re-render on, and its server markup carries them on no element.
+ * Every other dialog prop and handler, `onCancel` included, applies to every
+ * sheet dialog; the browser raises `cancel` on the dialog it presents.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
- * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetSwitcherContext.ts
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
@@ -45,78 +68,42 @@ import {
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import type {DialogPurpose} from '../Dialog';
-import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {useScrollLock} from '../hooks';
-import {
-  useFocusTrap,
-  useFocusTrapEscapeCompatibilitySignal,
-} from '../hooks/useFocusTrap';
-import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {useFocusTrapEscapeCompatibilitySignal} from '../hooks/useFocusTrap';
 import {dispatchLayerEscapeKeyDown} from '../Layer/layerStack';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
-import {composeEventHandlers, mergeProps} from '../utils';
-import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
+import {composeEventHandlers} from '../utils';
+import {mergeRefs} from '../utils/mergeRefs';
 import {
   BottomSheetSwitcherContext,
   type BottomSheetSwitcherContextValue,
+  type BottomSheetSwitcherDialogProps,
   type BottomSheetSwitcherPhase,
   type BottomSheetSwitcherTransitionEvent,
 } from './BottomSheetSwitcherContext';
 
-import {useMergedRefs} from '../hooks/useMergedRefs';
 const styles = stylex.create({
-  dialog: {
-    position: 'fixed',
-    inset: 0,
-    width: '100dvw',
-    height: '100dvh',
-    maxWidth: 'none',
-    maxHeight: 'none',
-    margin: 0,
-    padding: 0,
-    borderWidth: 0,
-    borderStyle: 'none',
-    backgroundColor: 'transparent',
-    overflow: 'visible',
-    display: 'none',
-    outline: 'none',
+  // A scrim flow's dialogs live in the top layer; the wrapper has no box.
+  flow: {
+    display: 'contents',
   },
-  dialogOpen: {
+  // show() leaves a no-scrim flow in the normal rendering tree, where DOM
+  // order would decide which sheet dialog paints in front during a handoff.
+  // The wrapper is then the flow's isolated surface: the sheet dialogs order
+  // themselves locally inside it (`spec:AST-027` FR2), and the wrapper itself
+  // keeps the one overlay value the shared shell carried before, which
+  // `spec:AST-027` records as the non-modal migration gap. It passes pointer
+  // input through to the live page; each sheet panel opts back in. Consumers
+  // of this non-modal mode must still avoid transformed or clipping ancestors.
+  flowNonModal: {
     display: 'block',
-  },
-  // show() leaves a no-scrim flow in the normal rendering tree. The shell must
-  // pass pointer input through to the live page; each sheet panel opts back in.
-  // width/height 100% avoids overflowing a transformed containing block, but
-  // consumers of this non-modal mode must still avoid clipping ancestors.
-  dialogNonModal: {
-    pointerEvents: 'none',
-    zIndex: 1000,
+    position: 'fixed',
+    inset: 0,
     width: '100%',
     height: '100%',
-  },
-  scrim: {
-    '::backdrop': {
-      backgroundColor: colorVars['--color-overlay'],
-      opacity: {
-        default: 'var(--_sheet-scrim-opacity, 1)',
-        '@starting-style': 0,
-      },
-      transitionProperty: 'opacity, display',
-      transitionDuration: durationVars['--duration-medium'],
-      transitionTimingFunction: easeVars['--ease-standard'],
-      transitionBehavior: 'allow-discrete',
-      '@media (prefers-reduced-motion: reduce)': {
-        transitionDuration: '0.01s',
-      },
-    },
-  },
-  // The flow's dim leaves with its last panel. Same rule, same reasoning, as
-  // a standalone sheet's -- see `scrimClosing` in BottomSheet.tsx. A handoff
-  // between two sheets is not a close, and keeps the entrance curve.
-  scrimClosing: {
-    '::backdrop': {
-      transitionTimingFunction: 'linear',
-    },
+    pointerEvents: 'none',
+    isolation: 'isolate',
+    zIndex: 1000,
   },
 });
 
@@ -179,11 +166,54 @@ function alignmentOffsetForElements(
   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');
+}
+
 export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {
-  /** Ref forwarded to the shared native dialog. */
+  /**
+   * 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 shared native dialog receives a cancel event. */
+  /** Called when the active sheet's native dialog receives a cancel event. */
   onCancel?: (event: SyntheticEvent<HTMLDialogElement>) => void;
 
   /**
@@ -198,7 +228,7 @@ export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {
   onActiveSheetChange: (sheetId: string | null) => void;
 
   /**
-   * Whether to open the shared dialog modally with its native ::backdrop.
+   * Whether each sheet dialog opens modally with a native ::backdrop.
    * Disable for a viewport-anchored, non-modal flow over an interactive page.
    * @default true
    */
@@ -209,8 +239,8 @@ export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {
 }
 
 /**
- * Coordinates a set of BottomSheets so zero or one is active at a time inside
- * one shared native dialog. During a handoff the previous panel stays visible
+ * 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.
  *
  * @example
@@ -229,22 +259,40 @@ export function BottomSheetSwitcher({
   hasScrim = true,
   children,
   ref,
-  xstyle,
-  className,
-  style,
   onCancel,
   onClick,
   onKeyDown,
-  ...props
+  className,
+  style,
+  xstyle,
+  ...restDialogProps
 }: BottomSheetSwitcherProps) {
-  const dialogRef = useRef<HTMLDialogElement | null>(null);
-  const dialogModeRef = useRef<'modal' | 'non-modal' | null>(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 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 [sheetLabels, setSheetLabels] = useState<ReadonlyMap<string, string>>(
-    () => new Map(),
-  );
+  const scrimOpacityRef = useRef(1);
+  const scrimOwnerRef = useRef<string | null>(null);
   const [sheetPurposes, setSheetPurposes] = useState<
     ReadonlyMap<string, DialogPurpose>
   >(() => new Map());
@@ -261,11 +309,42 @@ export function BottomSheetSwitcher({
         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 =
-    (activeSheet != null && !unmountedSheetIds.has(activeSheet)) ||
-    (visibleTransition.retainedSheet != null &&
-      !unmountedSheetIds.has(visibleTransition.retainedSheet));
+    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;
+  const isFlowClosing = isFlowVisible && activeSheet == null;
   const activeSheetPurpose =
     (activeSheet == null ? null : sheetPurposes.get(activeSheet)) ?? 'info';
   const allowsEscapeDismiss = activeSheetPurpose !== 'required';
@@ -299,59 +378,102 @@ export function BottomSheetSwitcher({
       onActiveSheetChange(null);
     }
   }, [allowsLightDismiss, onActiveSheetChange]);
-  const {containerRef} = useFocusTrap<HTMLDialogElement>({
-    isActive: isModal,
-  });
-  // Before the shared dismissal stack, this modal trap supplied `onEscape`, so
-  // the released compatibility shim reported it as active. Keep that signal
-  // without registering the switcher twice in the one shared stack.
+  // 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: () => dialogRef.current,
-    isPresent: () => dialogRef.current?.open ?? false,
+    getContainer: () => hostDialogRef.current,
+    isPresent: () => hostDialogRef.current?.open ?? false,
   });
-  useScrollLock(isModal);
 
-  // Open one shared shell for the complete flow. Modal flows enter the native
-  // top layer once; handoffs only swap panels inside it. The final panel owns
-  // the exit timing, so isFlowVisible becomes false only when it is safe to
-  // close the dialog and restore focus.
+  // 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 dialog = dialogRef.current;
-    if (dialog == null) {
+    const host =
+      hostSheet == null
+        ? (sheetDialogsRef.current.values().next().value ?? null)
+        : (sheetDialogsRef.current.get(hostSheet) ?? null);
+    hostDialogRef.current = host;
+    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;
+    },
+    [],
+  );
 
+  // 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);
+  }, []);
+  useLayoutEffect(() => {
     if (isFlowVisible) {
-      const nextMode = hasScrim ? 'modal' : 'non-modal';
-      if (dialog.open && dialogModeRef.current !== nextMode) {
-        dialog.close();
+      if (!hasScrim) {
+        modalFlowRef.current = false;
       }
-      if (!dialog.open) {
-        if (hasScrim && triggerRef.current == null) {
-          triggerRef.current = document.activeElement as HTMLElement | null;
-        }
-        if (hasScrim) {
-          dialog.showModal();
-        } else {
-          dialog.show();
-        }
-      }
-      dialogModeRef.current = nextMode;
       return;
     }
-
-    if (dialog.open) {
-      dialog.close();
-    }
-    if (dialogModeRef.current === 'modal') {
-      triggerRef.current?.focus();
+    if (modalFlowRef.current) {
+      // 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.
+      triggerRef.current?.focus({preventScroll: true});
     }
     triggerRef.current = null;
-    dialogModeRef.current = null;
+    modalFlowRef.current = false;
+    presentationOrderRef.current.clear();
   }, [hasScrim, isFlowVisible]);
 
   const getSheetPhase = useCallback(
@@ -377,6 +499,11 @@ export function BottomSheetSwitcher({
     [visibleTransition],
   );
 
+  const isScrimOwner = useCallback(
+    (sheetId: string) => sheetId === scrimOwnerSheet,
+    [scrimOwnerSheet],
+  );
+
   const registerSheetElement = useCallback(
     (sheetId: string, element: HTMLElement | null) => {
       if (element == null) {
@@ -407,28 +534,44 @@ export function BottomSheetSwitcher({
     [],
   );
 
-  const registerSheetLabel = useCallback(
-    (sheetId: string, label: string | null) => {
-      setSheetLabels(current => {
-        if (label == null) {
-          if (!current.has(sheetId)) {
-            return current;
-          }
-          const next = new Map(current);
-          next.delete(sheetId);
-          return next;
-        }
-        if (current.get(sheetId) === label) {
-          return current;
-        }
-        const next = new Map(current);
-        next.set(sheetId, label);
-        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 => {
@@ -533,67 +676,64 @@ export function BottomSheetSwitcher({
     [],
   );
 
-  const setScrimOpacity = useCallback((opacity: number) => {
-    dialogRef.current?.style.setProperty(
-      '--_sheet-scrim-opacity',
-      String(opacity),
-    );
-  }, []);
+  // 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.
+  const applyScrimOpacity = useCallback(() => {
+    const owner =
+      scrimOwnerSheet == null
+        ? null
+        : (sheetDialogsRef.current.get(scrimOwnerSheet) ?? null);
+    // 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, scrimOpacityRef.current);
+        } else {
+          dialog.style.setProperty(
+            '--_sheet-scrim-opacity',
+            String(scrimOpacityRef.current),
+          );
+        }
+      } else if (sheetId !== scrimOwnerSheet) {
+        dialog.style.setProperty('--_sheet-scrim-opacity', '0');
+      }
+    }
+  }, [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
-      // shared backdrop, so stale gesture updates must not reach the dialog.
+      // flow's scrim value, so stale gesture updates must not reach it.
       if (sheetId !== committedActiveSheetRef.current) {
         return;
       }
-      setScrimOpacity(opacity);
+      scrimOpacityRef.current = opacity;
+      applyScrimOpacity();
     },
-    [setScrimOpacity],
+    [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(() => {
-    setScrimOpacity(activeSheet == null ? 0 : 1);
-  }, [activeSheet, setScrimOpacity]);
-
-  const contextValue = useMemo<BottomSheetSwitcherContextValue>(
-    () => ({
-      activeSheet,
-      hasScrim,
-      onActiveSheetChange,
-      getSheetPhase,
-      getSheetAlignmentOffset,
-      registerSheetElement,
-      registerSheetLabel,
-      registerSheetPurpose,
-      onSheetEnterStart,
-      onSheetTransitionComplete,
-      onSheetScrimOpacityChange,
-    }),
-    [
-      activeSheet,
-      getSheetAlignmentOffset,
-      getSheetPhase,
-      hasScrim,
-      onActiveSheetChange,
-      onSheetEnterStart,
-      onSheetScrimOpacityChange,
-      onSheetTransitionComplete,
-      registerSheetElement,
-      registerSheetLabel,
-      registerSheetPurpose,
-    ],
-  );
-
-  const activeLabel =
-    (activeSheet == null ? null : sheetLabels.get(activeSheet)) ??
-    (visibleTransition.retainedSheet == null
-      ? undefined
-      : sheetLabels.get(visibleTransition.retainedSheet));
-
-  // A `cancel` that bubbles up from a step is not a close request for the
-  // flow: a file input fires one when its picker is dismissed, and a step
-  // renders no dialog of its own, so it lands here. It is left alone.
+    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) {
@@ -618,47 +758,88 @@ export function BottomSheetSwitcher({
   );
   const handleClick = useCallback(
     (event: ReactMouseEvent<HTMLDialogElement>) => {
-      if (hasScrim && event.target === event.currentTarget) {
+      // 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 dialogStyleProps = stylex.props(
-    styles.dialog,
-    isFlowVisible && styles.dialogOpen,
-    hasScrim && styles.scrim,
-    hasScrim && isFlowVisible && activeSheet == null && styles.scrimClosing,
-    !hasScrim && styles.dialogNonModal,
-    xstyle,
+  const onDialogCancel = useMemo(
+    () => composeEventHandlers(onCancel, handleCancel),
+    [handleCancel, onCancel],
   );
-  const dialogPresentationProps = mergeProps(
-    dialogStyleProps,
-    className,
-    style,
+  const onDialogClick = useMemo(
+    () => composeEventHandlers(onClick, handleClick),
+    [handleClick, onClick],
+  );
+  const onDialogKeyDown = useMemo(
+    () => composeEventHandlers(onKeyDown, handleKeyDown),
+    [handleKeyDown, onKeyDown],
+  );
+
+  const contextValue = useMemo<BottomSheetSwitcherContextValue>(
+    () => ({
+      activeSheet,
+      hasScrim,
+      onActiveSheetChange,
+      getSheetPhase,
+      getSheetAlignmentOffset,
+      hostSheet,
+      isScrimOwner,
+      isFlowClosing,
+      registerSheetElement,
+      registerSheetDialog,
+      registerSheetPurpose,
+      onBeforeSheetPresent,
+      isCoveredInTopLayer,
+      onSheetEnterStart,
+      onSheetTransitionComplete,
+      onSheetScrimOpacityChange,
+      dialogProps,
+      onDialogCancel,
+      onDialogClick,
+      onDialogKeyDown,
+    }),
+    [
+      activeSheet,
+      dialogProps,
+      getSheetAlignmentOffset,
+      getSheetPhase,
+      hasScrim,
+      hostSheet,
+      isCoveredInTopLayer,
+      isFlowClosing,
+      isScrimOwner,
+      onActiveSheetChange,
+      onBeforeSheetPresent,
+      onDialogCancel,
+      onDialogClick,
+      onDialogKeyDown,
+      onSheetEnterStart,
+      onSheetScrimOpacityChange,
+      onSheetTransitionComplete,
+      registerSheetDialog,
+      registerSheetElement,
+      registerSheetPurpose,
+    ],
   );
-  const ariaLabel =
-    props['aria-label'] ??
-    (props['aria-labelledby'] == null ? activeLabel : undefined);
 
   return (
     <BottomSheetSwitcherContext value={contextValue}>
-      <dialog
-        {...props}
-        {...dialogPresentationProps}
-        ref={useMergedRefs(ref, dialogRef, containerRef)}
-        aria-label={ariaLabel}
-        aria-modal={isModal ? 'true' : undefined}
-        onCancel={composeEventHandlers(onCancel, handleCancel)}
-        onClick={composeEventHandlers(onClick, handleClick)}
-        onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
-        {...(activeSheetPurpose === 'required'
-          ? {role: 'alertdialog'}
-          : undefined)}>
-        <LayerDepthProvider>{children}</LayerDepthProvider>
-        <BottomSheetEdgeTint />
-      </dialog>
+      <div
+        {...stylex.props(
+          styles.flow,
+          !hasScrim && isFlowVisible && styles.flowNonModal,
+        )}>
+        {children}
+      </div>
     </BottomSheetSwitcherContext>
   );
 }