@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/BottomSheet/BottomSheet.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file BottomSheet.tsx
- * @input Uses React, StyleX, core hooks, shared layer dismissal, the shared interaction modality, named BottomSheetPanel, BottomSheetSwitcherContext
+ * @input Uses React, StyleX, core hooks, shared layer dismissal, the modal outlet registry, the shared interaction modality, named BottomSheetPanel, BottomSheetSwitcherContext, BottomSheetHostContext, the private bottom-sheet stack registry
  * @output Exports BottomSheet component and BottomSheetProps
  * @position Public BottomSheet router plus private standalone/switcher hosts
  *
@@ -23,20 +23,57 @@
  * scroll is locked by the shared useScrollLock hook, as for Dialog: a
  * standalone sheet holds it while presented, a switcher holds one for the
  * whole modal flow. The remaining script is what no single dialog can
- * decide: gating `cancel` by `purpose` and the shared dismissal stack, and,
- * in a switcher, handing one scrim between two dialogs and keeping focus in
- * the active sheet when a retained dialog closes.
+ * decide: gating `cancel` by `purpose` and the shared dismissal stack, the
+ * stack of sheets below, and, in a switcher, handing one scrim between two
+ * dialogs and keeping focus in the active sheet when a retained dialog
+ * closes.
+ *
+ * A standalone sheet also joins the private bottom-sheet stack
+ * (bottomSheetStack.ts) while it is presented. The stack is behaviour, not
+ * API: a modal sheet opened while another modal sheet is open stacks on top
+ * of it, the covered sheet recedes and is blocked, one scrim stays visible,
+ * and the native top layer is kept in open order even when several sheets
+ * open in one commit. A sheet rendered in another sheet's content leaves
+ * with its host and returns with it while its own `isOpen` is still true;
+ * its state is never written for it. A modal sheet on its own never
+ * notices the stack; when every sheet of a stack closes in one update, the
+ * registry returns focus once, to the bottom sheet's target, after the last
+ * dialog has closed.
+ *
+ * A standalone sheet closing in the same update as another standalone sheet
+ * opens, at the same level and from a control inside the closing sheet, is
+ * replaced by it: the two run the handoff a BottomSheetSwitcher runs between
+ * its steps (entering sheet above, retained sheet aligning down then fading,
+ * one steady scrim, focus into the new sheet and back to the flow's opener
+ * on close). The registry pairs them and drives the handoff; this host
+ * renders the retained panel state it reports, and reports its panel's
+ * motions back. Non-modal sheets (`hasScrim={false}`) are hosted as manual
+ * popovers so the top layer orders them, with `show()` below the Popover API
+ * floor; they never stack, but they replace each other the same way, and
+ * return focus to their opener on close only while the person is still in
+ * them.
+ *
+ * Every open standalone modal sheet supplies its dialog as an outlet for
+ * app-global surfaces (toasts) (Layer/modalOutlet.ts); the latest outlet,
+ * the one they render into, follows the sheet stack's order, so toasts land
+ * in the top sheet and return to the sheet beneath when it closes.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheetPanel.tsx
  * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetHostContext.ts
+ * - /packages/core/src/BottomSheet/bottomSheetStack.ts
  * - /packages/core/src/BottomSheet/BottomSheet.doc.mjs
  * - /packages/core/src/BottomSheet/BottomSheet.test.tsx
+ * - /packages/core/src/BottomSheet/BottomSheetStacking.test.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/Layer/layerDismissalFamilies.test.tsx
  * - /packages/core/src/Layer/layerDismissalInvariants.test.tsx
+ * - /packages/core/src/Toast/ToastViewport.modalHost.test.tsx
  * - /apps/storybook/stories/BottomSheet.stories.tsx
+ * - /apps/storybook/stories/BottomSheetStacking.stories.tsx
+ * - /apps/storybook/stories/BottomSheetReplace.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/BottomSheet/BottomSheetShowcase.tsx
  */
 
@@ -54,10 +91,18 @@ import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import type {DialogPurpose} from '../Dialog';
 import type {SpacingStep} from '../utils/types';
-import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
-import {useDevWarning, useScrollLock} from '../hooks';
+import {
+  colorVars,
+  durationVars,
+  easeVars,
+  spacingVars,
+} from '../theme/tokens.stylex';
+import {useDevWarning} from '../hooks/useDevWarning';
+import {useScrollLock} from '../hooks/useScrollLock';
 import {mergeProps} from '../utils';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
+import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
+import {useModalOutlet} from '../Layer/modalOutlet';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {focusForLastInput} from '../utils/focusReturn';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
@@ -67,6 +112,32 @@ import {
   type BottomSheetPanelState,
 } from './BottomSheetPanel';
 import {BottomSheetEdgeTint} from './BottomSheetEdgeTint';
+import {
+  BottomSheetHostContext,
+  CLOSED_BOTTOM_SHEET_HOST,
+  OPEN_BOTTOM_SHEET_HOST,
+} from './BottomSheetHostContext';
+import {
+  BOTTOM_SHEET_STACK_DEFAULT_VIEW,
+  cancelScrimWrite,
+  closeDialogKeepingFocus,
+  focusSheetPanel,
+  getBottomSheetBeneath,
+  hideSheetHost,
+  isClosingTogether,
+  isSheetHostPresented,
+  presentStepModally,
+  presentWithClearScrim,
+  registerBottomSheet,
+  reportBottomSheetMotion,
+  reportClosedTogether,
+  sealBottomSheetBatch,
+  setBottomSheetOpen,
+  showSheetHostNonModal,
+  writeScrimOpacity,
+  type BottomSheetScrimWrite,
+  type BottomSheetStackView,
+} from './bottomSheetStack';
 import {
   BottomSheetSwitcherContext,
   type BottomSheetSwitcherContextValue,
@@ -75,6 +146,7 @@ import {
 
 export type {BottomSheetHeight, BottomSheetSnapPoint} from './BottomSheetPanel';
 import type {BottomSheetHeight, BottomSheetSnapPoint} from './BottomSheetPanel';
+import {BottomSheetEscapeContext} from './bottomSheetEscape';
 
 const styles = stylex.create({
   dialog: {
@@ -96,12 +168,34 @@ const styles = stylex.create({
   dialogOpen: {
     display: 'block',
   },
+  // An open standalone dialog is its panel's positioner: the panel sits at its
+  // block end, centred, with no wrapper between them
+  // (architecture:component-style-authoring INV7). A tap beside a narrower
+  // panel lands on the dialog itself, which light dismiss reads. The stack's
+  // recede (stackPositionerStyles) is applied to this dialog too, so a
+  // covered standalone sheet shrinks and lifts as one, panel and all.
+  dialogPanelHost: {
+    display: 'grid',
+    alignContent: 'end',
+    justifyItems: 'center',
+  },
+  // A non-modal sheet is hosted in the top layer (manual popover), so it
+  // carries no page-level z-index (spec:AST-027). Below the Popover API
+  // floor `show()` leaves it in page stacking order as a reduced fallback:
+  // usable, but with no promise over later page content.
   dialogNonModal: {
     pointerEvents: 'none',
-    zIndex: 1000,
     width: '100%',
     height: '100%',
   },
+  dialogNonModalItem: {
+    pointerEvents: 'none',
+    width: '100%',
+    height: '100%',
+  },
+  dialogNonModalItemTop: {
+    zIndex: 1,
+  },
   scrim: {
     '::backdrop': {
       backgroundColor: colorVars['--color-overlay'],
@@ -110,31 +204,17 @@ const styles = stylex.create({
         '@starting-style': 0,
       },
       transitionProperty: 'opacity, display',
-      // A switcher hands its one scrim from a fading dialog to the next by
-      // pinning this duration for the swap; a standalone sheet never sets it.
+      // The scrim changes hands between stacked sheets with no fade at all:
+      // the host pins this to 0s inline for the frame the change lands in
+      // (see `writeScrimOpacity`). Reduced motion keeps the pin too.
       transitionDuration: `var(--_sheet-scrim-duration, ${durationVars['--duration-medium']})`,
       transitionTimingFunction: easeVars['--ease-standard'],
       transitionBehavior: 'allow-discrete',
       '@media (prefers-reduced-motion: reduce)': {
-        // The switcher's scrim takeover pins the duration to 0s for one style
-        // flush; a literal here would override that pin and paint a frame
-        // with no scrim under reduced motion.
         transitionDuration: 'var(--_sheet-scrim-duration, 0.01s)',
       },
     },
   },
-  // A non-modal switcher dialog does not enter the top layer, so DOM order
-  // would decide which sheet paints in front during a handoff. The switcher's
-  // flow wrapper is the isolated surface for that relationship; inside it the
-  // sheet dialogs use local values only, the interactive sheet's on top.
-  dialogNonModalItem: {
-    pointerEvents: 'none',
-    width: '100%',
-    height: '100%',
-  },
-  dialogNonModalItemTop: {
-    zIndex: 1,
-  },
   /**
    * The dim leaves with the sheet, on a curve that matches.
    *
@@ -163,8 +243,58 @@ const styles = stylex.create({
   positionerTop: {
     zIndex: 1,
   },
+  // A sheet in a stack recedes and returns with CSS motion only; the style
+  // stays on while another sheet is presented so the return animates too.
+  // On a standalone sheet these apply to the dialog itself (its panel's
+  // positioner); on a switcher step, to the step's positioner.
+  positionerStackMotion: {
+    transformOrigin: '50% 0',
+    transitionProperty: 'transform',
+    transitionDuration: durationVars['--duration-medium'],
+    transitionTimingFunction: easeVars['--ease-standard'],
+    '@media (prefers-reduced-motion: reduce)': {
+      transitionDuration: '0.01s',
+    },
+  },
+  // Covered sheets recede behind the top sheet: the nearest shrinks a step
+  // about its top edge and lifts, the next shrinks a second step; deeper
+  // sheets share that second step. Only sheets count toward the depth.
+  positionerReceded1: {
+    transform: `translateY(calc(-1 * ${spacingVars['--spacing-2']})) scale(0.96)`,
+  },
+  positionerReceded2: {
+    transform: `translateY(calc(-2 * ${spacingVars['--spacing-2']})) scale(0.92)`,
+  },
 });
 
+/** Positioner styles for a sheet's place in the stack; the switcher items share them. */
+function stackPositionerStyles(view: BottomSheetStackView) {
+  return [
+    view.isStacked && styles.positionerStackMotion,
+    view.depth === 1 && styles.positionerReceded1,
+    view.depth >= 2 && styles.positionerReceded2,
+  ] as const;
+}
+
+/** The `data-sheet-stack` value for a host: only set while sheets stack. */
+function stackStateAttribute(
+  view: BottomSheetStackView,
+  isOpen: boolean,
+): 'top' | 'covered' | 'exiting' | 'replaced' | undefined {
+  if (!view.isStacked) {
+    return undefined;
+  }
+  if (!isOpen) {
+    return view.replacedMotion != null ? 'replaced' : 'exiting';
+  }
+  return view.isTop ? 'top' : 'covered';
+}
+
+/** Scrim opacity for an open modal sheet: one visible backdrop per stack. */
+function scrimOpacityForView(view: BottomSheetStackView): '0' | '1' {
+  return view.isStacked && !view.ownsScrim ? '0' : '1';
+}
+
 interface BottomSheetSharedProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the visual sheet panel <div>. */
   ref?: React.Ref<HTMLDivElement>;
@@ -213,12 +343,23 @@ interface StandaloneBottomSheetProps extends BottomSheetSharedProps {
   isOpen: boolean;
   onOpenChange: (isOpen: boolean) => void;
   hasScrim?: boolean;
-  /** Element that receives focus after the sheet closes. */
+  /**
+   * Element that receives focus after the sheet closes. For a sheet on its
+   * own, or the last sheet of a stack, it is always focused, wherever focus
+   * was. When the sheet closes with a modal sheet still open beneath it,
+   * focus returns into that sheet instead (to this element if it is inside
+   * it, else the revealed sheet's panel), because the page is still inert.
+   */
   finalFocusRef?: RefObject<HTMLElement | null>;
   sheetId?: never;
 }
 
 interface SwitcherBottomSheetProps extends BottomSheetSharedProps {
+  /**
+   * @deprecated `BottomSheetSwitcher` is deprecated; give each step its own
+   * standalone sheet with `isOpen` instead. Keeps working until a future
+   * minor release removes the switcher.
+   */
   sheetId: string;
   isOpen?: never;
   onOpenChange?: never;
@@ -248,63 +389,13 @@ function panelStateForSwitcherPhase(
   }
 }
 
-// preventScroll on both: presenting a sheet must not scroll the page to reveal
-// what it just focused. For an autofocused field that reveal is the mobile
-// keyboard's, and it moves the document under a fixed sheet; useMobileKeyboard
-// brings the field into view within the sheet instead.
 function focusPanel(panel: HTMLElement | null, isModal: boolean): void {
-  const activeElement = document.activeElement;
-  if (activeElement != null && panel?.contains(activeElement)) {
-    return;
-  }
-  const autofocus = panel?.querySelector<HTMLElement>('[data-autofocus]');
-  if (autofocus != null) {
-    autofocus.focus({preventScroll: true});
-  } else if (isModal) {
-    panel?.focus({preventScroll: true});
-  }
-}
-
-/**
- * Present a switcher step's dialog modally with no focus to return to.
- * showModal() records the element focused at that moment and close() moves
- * focus back to it, in Chromium and WebKit even when focus is in another
- * dialog by then. For a step that element is the control that advanced the
- * flow (Continue, Back) or the flow's opener, and the dialog closes a fade
- * later, while the user is in the next step: the return would pull focus
- * off the active panel with no user action. Blurring first leaves nothing
- * recorded, so the close moves nothing; the entering step then focuses its
- * own panel, and the switcher returns focus to the opener itself when the
- * flow ends. The blur happens in the same task as the present, so no frame
- * paints without focus.
- */
-function presentStepModally(dialog: HTMLDialogElement): void {
-  const focused = dialog.ownerDocument.activeElement;
-  if (focused instanceof HTMLElement && focused !== dialog.ownerDocument.body) {
-    focused.blur();
-  }
-  dialog.showModal();
-}
-
-/**
- * Present a switcher dialog whose backdrop must start, and stay, clear: the
- * opacity is set with the scrim transition pinned to 0s, the dialog is
- * presented, and the pin is lifted only after a style flush has applied the
- * clear backdrop, so no frame eases from a previous backdrop value.
- */
-function presentWithClearScrim(dialog: HTMLDialogElement): void {
-  dialog.style.setProperty('--_sheet-scrim-duration', '0s');
-  dialog.style.setProperty('--_sheet-scrim-opacity', '0');
-  presentStepModally(dialog);
-  if (typeof getComputedStyle === 'function') {
-    void getComputedStyle(dialog, '::backdrop').opacity;
-  }
-  dialog.style.removeProperty('--_sheet-scrim-duration');
+  focusSheetPanel(panel, 'open', isModal);
 }
 
 function StandaloneBottomSheet({
   ref,
-  isOpen,
+  isOpen: isOpenProp,
   onOpenChange,
   label,
   children,
@@ -319,19 +410,76 @@ function StandaloneBottomSheet({
   const dialogRef = useRef<HTMLDialogElement | null>(null);
   const panelRef = useRef<HTMLDivElement | null>(null);
   const triggerRef = useRef<HTMLElement | null>(null);
+  // Whether focus was inside this sheet when its close began. A non-modal
+  // sheet leaves the page interactive, so it returns focus to its opener
+  // only if the person was still in the sheet; a modal sheet always does.
+  const hadFocusAtCloseRef = useRef(false);
+  const finalFocusRefRef = useRef(finalFocusRef);
+  finalFocusRefRef.current = finalFocusRef;
+  // A sheet rendered in another sheet's content is presented only while that
+  // sheet is open: it leaves with its host and, if its own state is still
+  // open, comes back when the host does (see BottomSheetHostContext). Its
+  // state stays the consumer's; nothing here writes it.
+  const host = use(BottomSheetHostContext);
+  const isHostOpen = host?.isOpen ?? true;
+  const isOpen = isOpenProp && isHostOpen;
+  // Presentation outlives the controlled prop: a closing sheet stays mounted
+  // and in its native host through its exit, and only its motion completion
+  // (or a replace finishing) clears it. The open flip is derived during
+  // render; the close flip is the host's own event.
   const [isPresented, setIsPresented] = useState(isOpen);
+  if (isOpen && !isPresented) {
+    setIsPresented(true);
+  }
   const shouldPresent = isOpen || isPresented;
+
+  // The sheet's place in the stack of presented modal sheets. Default until
+  // the stack reports otherwise, which it does in the commit that presents
+  // the sheet, so the first painted frame already shows it.
+  const stackKeyRef = useRef<object>({});
+  const [stackView, setStackView] = useState<BottomSheetStackView>(
+    BOTTOM_SHEET_STACK_DEFAULT_VIEW,
+  );
+  const isOpenRef = useRef(isOpen);
+  isOpenRef.current = isOpen;
+  // Closed and being replaced by the sheet that opened in the same update:
+  // the panel is retained (stays, aligns, fades) instead of sliding out.
+  const isReplaced = !isOpen && isPresented && stackView.replacedMotion != null;
+  // Whether a replace pairs this close is known only once every sheet of the
+  // commit has reported to the registry, in the layout phase. Until the
+  // registry has answered (a synchronous re-render later, before paint) the
+  // panel holds its open pose: an exit pose rendered first and read back by
+  // the panel's own style query would start the exit transition, and the
+  // reversal into the retained pose would then snap the panel to rest. The
+  // flag is keyed to the close it settles: every change of `isOpen` starts
+  // it over, during render, and the layout effect below settles a close.
+  const [isCloseSettled, setIsCloseSettled] = useState(false);
+  const [settledIsOpen, setSettledIsOpen] = useState(isOpen);
+  if (settledIsOpen !== isOpen) {
+    setSettledIsOpen(isOpen);
+    setIsCloseSettled(false);
+  }
   const panelState: BottomSheetPanelState = isOpen
-    ? {kind: 'open', entering: false}
-    : isPresented
-      ? {kind: 'exiting'}
-      : {kind: 'hidden'};
+    ? {kind: 'open', entering: stackView.isReplacing}
+    : isReplaced
+      ? {
+          kind: 'retained',
+          motion: stackView.replacedMotion ?? 'covered',
+          alignmentOffset: stackView.alignmentOffset,
+        }
+      : isPresented
+        ? isCloseSettled
+          ? {kind: 'exiting'}
+          : {kind: 'open', entering: false}
+        : {kind: 'hidden'};
 
+  // Popover's sheet may turn Escape off on its own (bottomSheetEscape.ts).
+  const isEscapeAllowed = use(BottomSheetEscapeContext);
   const dismissOnEscape = useCallback(() => {
-    if (isOpen && purpose !== 'required') {
+    if (isOpen && purpose !== 'required' && isEscapeAllowed) {
       onOpenChange(false);
     }
-  }, [isOpen, onOpenChange, purpose]);
+  }, [isEscapeAllowed, isOpen, onOpenChange, purpose]);
   const dismissOnLightInteraction = useCallback(() => {
     if (purpose === 'info') {
       onOpenChange(false);
@@ -343,63 +491,224 @@ function StandaloneBottomSheet({
     },
     [],
   );
+  const stackViewRef = useRef(stackView);
+  stackViewRef.current = stackView;
+  const scrimWriteRef = useRef<BottomSheetScrimWrite>({frame: null});
+  useEffect(() => () => cancelScrimWrite(scrimWriteRef.current), []);
+  const writeScrim = useCallback(
+    (opacity: '0' | '1') =>
+      writeScrimOpacity(dialogRef.current, opacity, scrimWriteRef.current),
+    [],
+  );
   const handleScrimOpacity = useCallback((opacity: number) => {
+    // Only the sheet whose backdrop is the visible scrim thins it; a sheet
+    // stacked above it has a transparent backdrop that a drag must not reveal.
+    const view = stackViewRef.current;
+    if (view.isStacked && !view.ownsScrim) {
+      return;
+    }
     dialogRef.current?.style.setProperty(
       '--_sheet-scrim-opacity',
       String(opacity),
     );
   }, []);
 
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (dialog == null || !isOpen) {
+  // A sheet joins the registry for as long as it is presented. For a modal
+  // sheet the registry shows the dialog (in open order, repairing same-commit
+  // ties before paint), moves focus into it when it lands on top, and reports
+  // the sheet's view. A non-modal sheet is a group of its own: it is shown as
+  // a manual popover (or by `show()` below the Popover API floor), never
+  // stacks or recedes, and only replaces other non-modal sheets.
+  useLayoutEffect(() => {
+    if (!shouldPresent) {
       return;
     }
-
-    // The controlled prop opens an already-mounted dialog; presentation state
-    // must latch here so a later close can keep it mounted through its exit.
-    // eslint-disable-next-line @eslint-react/set-state-in-effect -- latches controlled open state for exit animation
-    setIsPresented(true);
-    dialog.style.setProperty('--_sheet-scrim-opacity', '1');
-    const wasOpen = dialog.open;
-    if (!wasOpen) {
-      if (hasScrim) {
-        triggerRef.current = document.activeElement as HTMLElement | null;
-        dialog.showModal();
-      } else {
-        dialog.show();
-      }
-      focusPanel(panelRef.current, hasScrim);
+    const key = stackKeyRef.current;
+    return registerBottomSheet(
+      {
+        key,
+        getElement: () => dialogRef.current,
+        show: () => {
+          const dialog = dialogRef.current;
+          if (dialog == null || isSheetHostPresented(dialog)) {
+            return;
+          }
+          if (triggerRef.current == null) {
+            triggerRef.current = document.activeElement as HTMLElement | null;
+          }
+          if (!hasScrim) {
+            showSheetHostNonModal(dialog, panelRef.current);
+            return;
+          }
+          dialog.style.setProperty(
+            '--_sheet-scrim-opacity',
+            scrimOpacityForView(stackViewRef.current),
+          );
+          dialog.showModal();
+        },
+        hide: () => closeDialogKeepingFocus(dialogRef.current),
+        focus: reason => focusSheetPanel(panelRef.current, reason, hasScrim),
+        getReturnTarget: () =>
+          finalFocusRefRef.current?.current ?? triggerRef.current,
+        onView: view => {
+          stackViewRef.current = view;
+          setStackView(view);
+          // Who owns the scrim is the stack's decision; a change of owner
+          // lands with no fade (see writeScrimOpacity). A replaced sheet
+          // keeps the scrim it owns until the sheet replacing it takes it
+          // over; a closing sheet whose scrim an open sheet took over drops
+          // its backdrop the same way; a closing sheet that owned the scrim
+          // alone fades it out.
+          if (isOpenRef.current || view.replacedMotion != null) {
+            writeScrim(scrimOpacityForView(view));
+          } else if (view.isScrimTakenOver) {
+            writeScrim('0');
+          }
+        },
+        replaceable: {
+          getPanel: () => panelRef.current,
+          getOpener: () => triggerRef.current,
+          setOpener: opener => {
+            triggerRef.current = opener;
+          },
+          finish: () => {
+            // The registry has closed the dialog; focus stayed in the sheet
+            // that replaced this one, and so did the flow's opener.
+            triggerRef.current = null;
+            setIsPresented(false);
+          },
+        },
+      },
+      isOpenRef.current,
+      hasScrim,
+    );
+  }, [hasScrim, shouldPresent, writeScrim]);
+  useLayoutEffect(() => {
+    if (!isOpen) {
+      // Read before the browser's focus fixup for the exiting sheet's
+      // `inert` runs (at the next rendering opportunity), so this is where
+      // focus was when the person closed the sheet.
+      const dialog = dialogRef.current;
+      hadFocusAtCloseRef.current =
+        dialog != null && dialog.contains(dialog.ownerDocument.activeElement);
+    }
+    if (shouldPresent) {
+      setBottomSheetOpen(stackKeyRef.current, isOpen);
+    }
+    if (!isOpen) {
+      // The registry has had every sheet's report for this commit; a close
+      // that was not paired as a replace is an exit from here on.
+      // eslint-disable-next-line @eslint-react/set-state-in-effect -- settles the close once the registry has answered
+      setIsCloseSettled(true);
     }
-  }, [hasScrim, isOpen]);
+  }, [hasScrim, isOpen, shouldPresent]);
 
+  // Host app-global surfaces (toasts) inside this sheet while it is an open
+  // modal, so they stay visible and operable above it. Every open scrim sheet
+  // supplies an outlet (each is an active native modal); the latest outlet —
+  // the one global hosts render into — follows the sheet stack's order among
+  // sheets rather than the order the sheets were supplied in, so a toast lands
+  // in the top sheet, and when that sheet closes the sheet it reveals becomes
+  // the latest sheet again and takes the toasts back; a Dialog opened from a
+  // sheet is supplied later and stays above every sheet. A closing sheet stays modal through its
+  // exit animation, but inert and hidden, so it stops supplying as soon as it
+  // starts closing. The registry reports a lone open sheet as the top one.
+  // Passive: it runs after the layout effects that present.
+  useModalOutlet(
+    dialogRef,
+    isOpen && hasScrim,
+    stackView.isTop,
+    'bottom-sheet',
+  );
+  // Closes a batch of same-commit opens; see sealBottomSheetBatch.
   useEffect(() => {
-    if (!isOpen && isPresented && hasScrim) {
-      handleScrimOpacity(0);
+    sealBottomSheetBatch();
+  });
+
+  // The scrim at rest: one visible backdrop per stack while open (a sheet
+  // stacked above the owner keeps its own backdrop transparent, and a reopen
+  // during the exit brings the owner's back), fading out through the exit.
+  useLayoutEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog == null || !hasScrim) {
+      return;
     }
-  }, [handleScrimOpacity, hasScrim, isOpen, isPresented]);
+    // A replaced sheet keeps the scrim it owns until the sheet replacing it
+    // takes it over; see bottomSheetStack.
+    if (isOpen || isReplaced) {
+      dialog.style.setProperty(
+        '--_sheet-scrim-opacity',
+        scrimOpacityForView(stackViewRef.current),
+      );
+    } else if (isPresented) {
+      dialog.style.setProperty('--_sheet-scrim-opacity', '0');
+    }
+  }, [hasScrim, isOpen, isPresented, isReplaced]);
 
+  const handleMotionStart = useCallback((motion: BottomSheetPanelMotion) => {
+    reportBottomSheetMotion(stackKeyRef.current, 'start', motion);
+  }, []);
   const handleMotionComplete = useCallback(
     (motion: BottomSheetPanelMotion) => {
+      // The replace handoff's motions (entering as a replacer, aligning and
+      // fading as the replaced sheet) are the registry's to sequence.
+      reportBottomSheetMotion(stackKeyRef.current, 'complete', motion);
       if (motion !== 'exiting' || isOpen) {
         return;
       }
+      // A sheet closing from code beneath open sheets leaves focus where it
+      // is: in the sheet on top. Its own close must not pull focus back to
+      // the element its dialog recorded, nor does it move it anywhere else.
+      if (hasScrim && stackViewRef.current.depth > 0) {
+        closeDialogKeepingFocus(dialogRef.current);
+        setIsPresented(false);
+        triggerRef.current = null;
+        return;
+      }
+      // Closing together with the other sheets of its stack ("Close all"):
+      // the registry returns focus once, after the last dialog has left.
+      if (hasScrim && isClosingTogether(stackKeyRef.current)) {
+        closeDialogKeepingFocus(dialogRef.current);
+        setIsPresented(false);
+        triggerRef.current = null;
+        reportClosedTogether(stackKeyRef.current);
+        return;
+      }
       const dialog = dialogRef.current;
-      if (dialog?.open) {
-        dialog.close();
+      if (dialog != null) {
+        hideSheetHost(dialog);
       }
       setIsPresented(false);
       // The returned focus shows the focus-visible ring only after keyboard
       // input (`architecture:interaction-modality` INV1). The native close
       // may already have restored focus to the target with a ring; the helper
       // clears it first.
-      const returnTarget = finalFocusRef?.current ?? triggerRef.current;
-      if (returnTarget != null) {
+      //
+      // With a sheet still open beneath this one, focus returns into that
+      // sheet: to the opener when it is there, else to the sheet's panel.
+      //
+      // An explicit `finalFocusRef` always receives focus, as released. The
+      // recorded opener of a non-modal sheet does so only if the person was
+      // still in the sheet when it closed (`hidePopover()` never moves
+      // focus, and the page behind it was live, so focus the person took
+      // elsewhere stays there).
+      const revealed = hasScrim
+        ? getBottomSheetBeneath(stackKeyRef.current)
+        : null;
+      const returnTarget =
+        finalFocusRef?.current ??
+        (hasScrim || hadFocusAtCloseRef.current ? triggerRef.current : null);
+      if (
+        revealed != null &&
+        (returnTarget == null || !revealed.element.contains(returnTarget))
+      ) {
+        revealed.focus();
+      } else if (returnTarget != null) {
         focusForLastInput(returnTarget);
       }
       triggerRef.current = null;
     },
-    [finalFocusRef, isOpen],
+    [finalFocusRef, hasScrim, isOpen],
   );
 
   useInteractionModalityTracking();
@@ -421,20 +730,32 @@ function StandaloneBottomSheet({
   // rather than letting it close a layer behind it. `required` blocks too.
   const {shouldDismissOnCloseRequest} = useLayerDismissal({
     isActive: shouldPresent,
-    escapeBehavior: isOpen && purpose !== 'required' ? 'close' : 'block',
+    escapeBehavior:
+      isOpen && purpose !== 'required' && isEscapeAllowed ? 'close' : 'block',
     onDismiss: dismissOnEscape,
     getContainer: () => dialogRef.current,
-    isPresent: () => dialogRef.current?.open ?? false,
+    // A covered sheet is on screen but never the one a press is for: the
+    // dismissal stack ranks by tree nesting first, which would hand Escape to
+    // a covered sheet nested in another sheet's content ahead of a top sheet
+    // written outside it. Standing down while covered keeps Escape and the
+    // platform close request with the top sheet, as the sheet stack orders.
+    // A replaced sheet stands down the same way: the sheet that replaced it,
+    // registered before or after it, takes the press.
+    isPresent: () =>
+      isSheetHostPresented(dialogRef.current) &&
+      !stackViewRef.current.isCovered &&
+      stackViewRef.current.replacedMotion == null,
   });
 
   // The native `cancel` event is a close request the stack never saw a press
-  // for (Android back, the platform close watcher). One that bubbles up from
-  // inside is not: a file input fires it when its picker is dismissed, so it is
-  // left alone. Otherwise always preventDefault so the browser cannot close the
-  // controlled <dialog>, then answer with the stack's rules: only the top-most
-  // layer dismisses, and nothing dismisses during an IME composition.
+  // for (Android back, the platform close watcher). Always preventDefault so
+  // the browser cannot close the controlled <dialog>, then answer with the
+  // stack's rules: only the top-most layer dismisses, and nothing dismisses
+  // during an IME composition.
   const handleCancel = useCallback(
     (event: React.SyntheticEvent<HTMLDialogElement>) => {
+      // A `cancel` that bubbles up from inside is not a close request: a
+      // file input fires it when its picker is dismissed, so it is left alone.
       if (event.target !== event.currentTarget) {
         return;
       }
@@ -454,42 +775,84 @@ function StandaloneBottomSheet({
     [dismissOnLightInteraction, hasScrim],
   );
 
+  const isExiting = !isOpen && isPresented;
+  // A covered sheet is blocked by the browser: the top sheet's modal dialog
+  // makes everything outside it inert, this dialog included. A covered sheet
+  // that contains no presented sheet is marked inert and hidden as well, so
+  // the state is explicit; one that does contain the top sheet is left alone,
+  // because inert on it would reach the top sheet too.
+  const isInert = isExiting || stackView.isBlocked;
+
   return (
     <dialog
       {...stylex.props(
         styles.dialog,
         shouldPresent && styles.dialogOpen,
+        shouldPresent && styles.dialogPanelHost,
+        // The dialog is the panel's positioner, so the stack's recede
+        // transforms the dialog: panel, grabber and all shrink and lift as
+        // one. The backdrop is not a descendant and stays put.
+        ...stackPositionerStyles(stackView),
         hasScrim && styles.scrim,
-        hasScrim && !isOpen && isPresented && styles.scrimClosing,
+        hasScrim && isExiting && styles.scrimClosing,
         !hasScrim && styles.dialogNonModal,
       )}
       ref={dialogRef}
+      // A non-modal sheet is hosted in the top layer as a manual popover
+      // (no light dismiss, no backdrop), so sheets order by presentation
+      // without a page-level z-index. Below the Popover API floor the
+      // attribute is inert and the sheet falls back to show(), in page
+      // stacking order (the documented reduced fallback).
+      popover={hasScrim ? undefined : 'manual'}
       aria-label={label}
-      aria-hidden={!isOpen && isPresented ? 'true' : undefined}
+      aria-hidden={isInert ? 'true' : undefined}
       aria-modal={hasScrim && isOpen ? 'true' : undefined}
       role={purpose === 'required' ? 'alertdialog' : undefined}
-      inert={!isOpen && isPresented ? true : undefined}
+      inert={isInert ? true : undefined}
+      data-sheet-stack={
+        hasScrim ? stackStateAttribute(stackView, isOpen) : undefined
+      }
+      data-sheet-stack-depth={
+        hasScrim && stackView.depth > 0 ? stackView.depth : undefined
+      }
       onCancel={handleCancel}
       onClick={handleClick}>
-      <div {...stylex.props(styles.positioner)}>
-        <BottomSheetPanel
-          {...props}
-          ref={ref}
-          state={panelState}
-          height={height}
-          label={label}
-          snapPoints={snapPoints}
-          isSwipeDismissAllowed={purpose === 'info'}
-          isPageScrollLocked={shouldPresent && hasScrim}
-          xstyle={xstyle}
-          onDismiss={dismissOnLightInteraction}
-          onScrimOpacity={handleScrimOpacity}
-          onElementChange={handlePanelElementChange}
-          onMotionComplete={handleMotionComplete}>
-          <LayerDepthProvider>{children}</LayerDepthProvider>
-        </BottomSheetPanel>
-      </div>
-      <BottomSheetEdgeTint />
+      <BottomSheetPanel
+        {...props}
+        ref={ref}
+        state={panelState}
+        isOpenRequested={isOpen}
+        height={height}
+        label={label}
+        snapPoints={snapPoints}
+        isSwipeDismissAllowed={purpose === 'info'}
+        isPageScrollLocked={shouldPresent && hasScrim}
+        xstyle={xstyle}
+        onDismiss={dismissOnLightInteraction}
+        onScrimOpacity={handleScrimOpacity}
+        onElementChange={handlePanelElementChange}
+        onMotionStart={handleMotionStart}
+        onMotionComplete={handleMotionComplete}>
+        <ModalAnnounceProvider
+          dialogRef={dialogRef}
+          isOpen={isOpen && hasScrim}>
+          <LayerDepthProvider>
+            {/* A sheet opened inside this one starts from Escape on. */}
+            <BottomSheetEscapeContext value>
+              <BottomSheetHostContext
+                value={
+                  isOpen ? OPEN_BOTTOM_SHEET_HOST : CLOSED_BOTTOM_SHEET_HOST
+                }>
+                {children}
+              </BottomSheetHostContext>
+            </BottomSheetEscapeContext>
+          </LayerDepthProvider>
+        </ModalAnnounceProvider>
+      </BottomSheetPanel>
+      {/* Its own element, outside the panel's transform, so it stays flush
+          with the viewport's bottom edge at every detent; only while the
+          sheet is presented, so a closed sheet renders no extra element. */}
+      {shouldPresent && <BottomSheetEdgeTint />}
     </dialog>
   );
 }
@@ -527,6 +890,7 @@ function SwitcherBottomSheetItem({
     onSheetEnterStart,
     onSheetTransitionComplete,
     onSheetScrimOpacityChange,
+    stackView,
     dialogProps,
     onDialogCancel,
     onDialogClick,
@@ -547,6 +911,10 @@ function SwitcherBottomSheetItem({
   const isPresented = phase !== 'hidden';
   const isTopSheet = phase === 'active' || phase === 'entering';
   const ownsScrim = hasValidSheetId && isScrimOwner(sheetId);
+  // The flow is one level of the bottom-sheet stack; a sheet outside the flow
+  // covering it blocks every step dialog, the way a covered standalone sheet
+  // is blocked. A step is also inactive on its own terms during a handoff.
+  const isBlocked = isInactive || (hasScrim && stackView.isBlocked);
   const isHostSheet = hasValidSheetId && hostSheet === sheetId;
   const dialogRef = useRef<HTMLDialogElement | null>(null);
   const dialogModeRef = useRef<'modal' | 'non-modal' | null>(null);
@@ -760,8 +1128,18 @@ function SwitcherBottomSheetItem({
       }
       aria-labelledby={switcherAriaLabelledBy}
       aria-modal={hasScrim && isInteractive ? 'true' : undefined}
-      aria-hidden={isInactive ? 'true' : undefined}
-      inert={isInactive ? true : undefined}
+      aria-hidden={isBlocked ? 'true' : undefined}
+      inert={isBlocked ? true : undefined}
+      data-sheet-stack={
+        hasScrim && isPresented
+          ? stackStateAttribute(stackView, activeSheet != null)
+          : undefined
+      }
+      data-sheet-stack-depth={
+        hasScrim && isPresented && stackView.depth > 0
+          ? stackView.depth
+          : undefined
+      }
       role={purpose === 'required' ? 'alertdialog' : switcherDialogProps.role}
       onCancel={onDialogCancel}
       onClick={onDialogClick}
@@ -771,14 +1149,16 @@ function SwitcherBottomSheetItem({
           styles.positioner,
           !isPresented && styles.positionerHidden,
           isTopSheet && styles.positionerTop,
+          ...(hasScrim ? stackPositionerStyles(stackView) : []),
         )}
         hidden={!isPresented}
-        aria-hidden={isInactive ? 'true' : undefined}
-        inert={isInactive ? true : undefined}>
+        aria-hidden={isBlocked ? 'true' : undefined}
+        inert={isBlocked ? true : undefined}>
         <BottomSheetPanel
           {...props}
           ref={ref}
           state={panelState}
+          isOpenRequested={hasValidSheetId && activeSheet === sheetId}
           height={height}
           label={label}
           snapPoints={snapPoints}
@@ -792,9 +1172,28 @@ function SwitcherBottomSheetItem({
           onMotionComplete={handleMotionComplete}>
           {/* A switcher item consumes its parent controller. Its content starts a
               fresh ownership scope so a nested BottomSheet is standalone unless
-              it establishes a nested BottomSheetSwitcher of its own. */}
+              it establishes a nested BottomSheetSwitcher of its own. A
+              standalone sheet in this step's content is presented only while
+              the step is the interactive one: it leaves when the step is left,
+              keeps its own isOpen, and returns with the step while still open. */}
           <BottomSheetSwitcherContext value={null}>
-            <LayerDepthProvider>{children}</LayerDepthProvider>
+            <ModalAnnounceProvider
+              dialogRef={dialogRef}
+              isOpen={isPresented && hasScrim}>
+              <LayerDepthProvider>
+                {/* A sheet opened inside this one starts from Escape on. */}
+                <BottomSheetEscapeContext value>
+                  <BottomSheetHostContext
+                    value={
+                      isInteractive
+                        ? OPEN_BOTTOM_SHEET_HOST
+                        : CLOSED_BOTTOM_SHEET_HOST
+                    }>
+                    {children}
+                  </BottomSheetHostContext>
+                </BottomSheetEscapeContext>
+              </LayerDepthProvider>
+            </ModalAnnounceProvider>
           </BottomSheetSwitcherContext>
         </BottomSheetPanel>
       </div>