@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/BottomSheet/BottomSheet.js

@@ -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,35 +23,78 @@
  * 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
  */
 import { use, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
-import { colorVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
-import { useDevWarning, useScrollLock } from "../hooks/index.js";
+import { colorVars, durationVars, easeVars, spacingVars } from "../theme/tokens.stylex.js";
+import { useDevWarning } from "../hooks/useDevWarning.js";
+import { useScrollLock } from "../hooks/useScrollLock.js";
 import { mergeProps } from "../utils/index.js";
 import { LayerDepthProvider } from "../Layer/LayerDepthContext.js";
+import { ModalAnnounceProvider } from "../hooks/ModalAnnounceProvider.js";
+import { useModalOutlet } from "../Layer/modalOutlet.js";
 import { useLayerDismissal } from "../Layer/useLayerDismissal.js";
 import { focusForLastInput } from "../utils/focusReturn.js";
 import { useInteractionModalityTracking } from "../utils/interactionModality.js";
 import { BottomSheetPanel } from "./BottomSheetPanel.js";
 import { BottomSheetEdgeTint } from "./BottomSheetEdgeTint.js";
+import { BottomSheetHostContext, CLOSED_BOTTOM_SHEET_HOST, OPEN_BOTTOM_SHEET_HOST } from "./BottomSheetHostContext.js";
+import { BOTTOM_SHEET_STACK_DEFAULT_VIEW, cancelScrimWrite, closeDialogKeepingFocus, focusSheetPanel, getBottomSheetBeneath, hideSheetHost, isClosingTogether, isSheetHostPresented, presentStepModally, presentWithClearScrim, registerBottomSheet, reportBottomSheetMotion, reportClosedTogether, sealBottomSheetBatch, setBottomSheetOpen, showSheetHostNonModal, writeScrimOpacity } from "./bottomSheetStack.js";
 import { BottomSheetSwitcherContext } from "./BottomSheetSwitcherContext.js";
+import { BottomSheetEscapeContext } from "./bottomSheetEscape.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const styles = {
   dialog: {
@@ -75,6 +118,28 @@ const styles = {
     k1xSpc: "x1lliihq",
     $$css: true
   },
+  dialogPanelHost: {
+    k1xSpc: "xrvj5dj",
+    kfiyM8: "x4465f1",
+    kAPf3g: "x1o2pa38",
+    $$css: true
+  },
+  dialogNonModal: {
+    kfzvcC: "x47corl",
+    kzqmXN: "xh8yej3",
+    kZKoxP: "x5yr21d",
+    $$css: true
+  },
+  dialogNonModalItem: {
+    kfzvcC: "x47corl",
+    kzqmXN: "xh8yej3",
+    kZKoxP: "x5yr21d",
+    $$css: true
+  },
+  dialogNonModalItemTop: {
+    kY2c9j: "x1vjfegm",
+    $$css: true
+  },
   scrim: {
     kGyWv1: "xnixb3f",
     k5sjJv: "xni466t xxiuuzi",
@@ -85,21 +150,65 @@ const styles = {
     k4oj2o: "x15l12jy",
     $$css: true
   },
-  dialogNonModalItem: {
+  scrimClosing: {
+    kb4ib: "x1cz9k3x",
+    $$css: true
+  },
+  positioner: {
+    kVAEAm: "x10l6tqk",
+    kkqhue: "x17y0mx6",
+    krVfgx: "x1ey2m1c",
+    k1xSpc: "x78zum5",
+    kjj79g: "xl56j7k",
     kfzvcC: "x47corl",
-    kzqmXN: "xh8yej3",
-    kZKoxP: "x5yr21d",
     $$css: true
   },
-  dialogNonModalItemTop: {
+  positionerHidden: {
+    k1xSpc: "x1s85apg",
+    $$css: true
+  },
+  positionerTop: {
     kY2c9j: "x1vjfegm",
     $$css: true
   },
-  scrimClosing: {
-    kb4ib: "x1cz9k3x",
+  positionerStackMotion: {
+    k3nNDw: "x1fpg8nb",
+    k1ekBW: "x11xpdln",
+    kIyJzY: "x80gvsz",
+    kAMwcw: "xlr8y92",
+    k6CgDc: "xzg1mie",
+    $$css: true
+  },
+  positionerReceded1: {
+    k3aq6I: "xfkfg1k",
+    $$css: true
+  },
+  positionerReceded2: {
+    k3aq6I: "xdo3dbm",
     $$css: true
   }
 };
+
+/** Positioner styles for a sheet's place in the stack; the switcher items share them. */
+function stackPositionerStyles(view) {
+  return [view.isStacked && styles.positionerStackMotion, view.depth === 1 && styles.positionerReceded1, view.depth >= 2 && styles.positionerReceded2];
+}
+
+/** The `data-sheet-stack` value for a host: only set while sheets stack. */
+function stackStateAttribute(view, isOpen) {
+  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) {
+  return view.isStacked && !view.ownsScrim ? '0' : '1';
+}
 function panelStateForSwitcherPhase(phase, alignmentOffset) {
   switch (phase) {
     case 'active':
@@ -130,67 +239,12 @@ function panelStateForSwitcherPhase(phase, alignmentOffset) {
       };
   }
 }
-
-// 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, isModal) {
-  const activeElement = document.activeElement;
-  if (activeElement != null && panel?.contains(activeElement)) {
-    return;
-  }
-  const autofocus = panel?.querySelector('[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) {
-  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) {
-  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,
@@ -205,21 +259,76 @@ function StandaloneBottomSheet({
   const dialogRef = useRef(null);
   const panelRef = useRef(null);
   const triggerRef = useRef(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({});
+  const [stackView, setStackView] = useState(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 = isOpen ? {
     kind: 'open',
-    entering: false
-  } : isPresented ? {
+    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);
@@ -228,55 +337,192 @@ function StandaloneBottomSheet({
   const handlePanelElementChange = useCallback(element => {
     panelRef.current = element;
   }, []);
+  const stackViewRef = useRef(stackView);
+  stackViewRef.current = stackView;
+  const scrimWriteRef = useRef({
+    frame: null
+  });
+  useEffect(() => () => cancelScrimWrite(scrimWriteRef.current), []);
+  const writeScrim = useCallback(opacity => writeScrimOpacity(dialogRef.current, opacity, scrimWriteRef.current), []);
   const handleScrimOpacity = useCallback(opacity => {
+    // 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;
+    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;
+        }
+        if (!hasScrim) {
+          showSheetHostNonModal(dialog, panelRef.current);
+          return;
+        }
+        dialog.style.setProperty('--_sheet-scrim-opacity', scrimOpacityForView(stackViewRef.current));
         dialog.showModal();
-      } else {
-        dialog.show();
+      },
+      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);
+        }
       }
-      focusPanel(panelRef.current, hasScrim);
+    }, 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);
     }
-  }, [hasScrim, isOpen]);
+    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, 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;
+    }
+    // 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');
     }
-  }, [handleScrimOpacity, hasScrim, isOpen, isPresented]);
+  }, [hasScrim, isOpen, isPresented, isReplaced]);
+  const handleMotionStart = useCallback(motion => {
+    reportBottomSheetMotion(stackKeyRef.current, 'start', motion);
+  }, []);
   const handleMotionComplete = useCallback(motion => {
+    // 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();
   useScrollLock(shouldPresent && hasScrim);
   useDevWarning('BottomSheet', 'requires a non-empty `label` for an accessible name; the open sheet ' + 'has no built-in heading to derive one from.', isOpen && !label);
@@ -293,19 +539,27 @@ function StandaloneBottomSheet({
     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 => {
+    // 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;
     }
@@ -319,88 +573,66 @@ function StandaloneBottomSheet({
       dismissOnLightInteraction();
     }
   }, [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 /*#__PURE__*/_jsxs("dialog", {
-    ...{
-      0: {
-        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1s85apg x1a2a7pz"
-      },
-      8: {
-        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1a2a7pz x1lliihq"
-      },
-      4: {
-        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1s85apg x1a2a7pz xnixb3f xni466t xxiuuzi xc0dz0a x10buo38 x15h3t91 x142juwg x15l12jy"
-      },
-      12: {
-        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1a2a7pz x1lliihq xnixb3f xni466t xxiuuzi xc0dz0a x10buo38 x15h3t91 x142juwg x15l12jy"
-      },
-      2: {
-        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1s85apg x1a2a7pz x1cz9k3x"
-      },
-      10: {
-        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1a2a7pz x1lliihq x1cz9k3x"
-      },
-      6: {
-        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1s85apg x1a2a7pz xnixb3f xni466t xxiuuzi xc0dz0a x10buo38 x142juwg x15l12jy x1cz9k3x"
-      },
-      14: {
-        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1a2a7pz x1lliihq xnixb3f xni466t xxiuuzi xc0dz0a x10buo38 x142juwg x15l12jy x1cz9k3x"
-      },
-      1: {
-        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1s85apg x1a2a7pz x47corl xfo81ep xh8yej3 x5yr21d"
-      },
-      9: {
-        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1a2a7pz x1lliihq x47corl xfo81ep xh8yej3 x5yr21d"
-      },
-      5: {
-        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1s85apg x1a2a7pz xnixb3f xni466t xxiuuzi xc0dz0a x10buo38 x15h3t91 x142juwg x15l12jy x47corl xfo81ep xh8yej3 x5yr21d"
-      },
-      13: {
-        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1a2a7pz x1lliihq xnixb3f xni466t xxiuuzi xc0dz0a x10buo38 x15h3t91 x142juwg x15l12jy x47corl xfo81ep xh8yej3 x5yr21d"
-      },
-      3: {
-        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1s85apg x1a2a7pz x1cz9k3x x47corl xfo81ep xh8yej3 x5yr21d"
-      },
-      11: {
-        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1a2a7pz x1lliihq x1cz9k3x x47corl xfo81ep xh8yej3 x5yr21d"
-      },
-      7: {
-        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1s85apg x1a2a7pz xnixb3f xni466t xxiuuzi xc0dz0a x10buo38 x142juwg x15l12jy x1cz9k3x x47corl xfo81ep xh8yej3 x5yr21d"
-      },
-      15: {
-        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xc342km xng3xce xjbqb8w x1rea2x4 x1a2a7pz x1lliihq xnixb3f xni466t xxiuuzi xc0dz0a x10buo38 x142juwg x15l12jy x1cz9k3x x47corl xfo81ep xh8yej3 x5yr21d"
-      }
-    }[!!shouldPresent << 3 | !!hasScrim << 2 | !!(hasScrim && !isOpen && isPresented) << 1 | !!!hasScrim << 0],
-    ref: dialogRef,
+    ...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 && 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,
-    children: [/*#__PURE__*/_jsx("div", {
-      ...{
-        className: "x10l6tqk x17y0mx6 x1ey2m1c x78zum5 xl56j7k x47corl"
-      },
-      children: /*#__PURE__*/_jsx(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,
+    children: [/*#__PURE__*/_jsx(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,
+      children: /*#__PURE__*/_jsx(ModalAnnounceProvider, {
+        dialogRef: dialogRef,
+        isOpen: isOpen && hasScrim,
         children: /*#__PURE__*/_jsx(LayerDepthProvider, {
-          children: children
+          children: /*#__PURE__*/_jsx(BottomSheetEscapeContext, {
+            value: true,
+            children: /*#__PURE__*/_jsx(BottomSheetHostContext, {
+              value: isOpen ? OPEN_BOTTOM_SHEET_HOST : CLOSED_BOTTOM_SHEET_HOST,
+              children: children
+            })
+          })
         })
       })
-    }), /*#__PURE__*/_jsx(BottomSheetEdgeTint, {})]
+    }), shouldPresent && /*#__PURE__*/_jsx(BottomSheetEdgeTint, {})]
   });
 }
 function SwitcherBottomSheetItem({
@@ -432,6 +664,7 @@ function SwitcherBottomSheetItem({
     onSheetEnterStart,
     onSheetTransitionComplete,
     onSheetScrimOpacityChange,
+    stackView,
     dialogProps,
     onDialogCancel,
     onDialogClick,
@@ -446,6 +679,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(null);
   const dialogModeRef = useRef(null);
@@ -602,34 +839,24 @@ function SwitcherBottomSheetItem({
     "aria-label": switcherAriaLabel ?? (switcherAriaLabelledBy == null ? label : undefined),
     "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,
     onKeyDown: onDialogKeyDown,
     children: [/*#__PURE__*/_jsx("div", {
-      ...{
-        0: {
-          className: "x10l6tqk x17y0mx6 x1ey2m1c x78zum5 xl56j7k x47corl"
-        },
-        2: {
-          className: "x10l6tqk x17y0mx6 x1ey2m1c xl56j7k x47corl x1s85apg"
-        },
-        1: {
-          className: "x10l6tqk x17y0mx6 x1ey2m1c x78zum5 xl56j7k x47corl x1vjfegm"
-        },
-        3: {
-          className: "x10l6tqk x17y0mx6 x1ey2m1c xl56j7k x47corl x1s85apg x1vjfegm"
-        }
-      }[!!!isPresented << 1 | !!isTopSheet << 0],
+      ...stylex.props(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,
       children: /*#__PURE__*/_jsx(BottomSheetPanel, {
         ...props,
         ref: ref,
         state: panelState,
+        isOpenRequested: hasValidSheetId && activeSheet === sheetId,
         height: height,
         label: label,
         snapPoints: snapPoints,
@@ -643,8 +870,18 @@ function SwitcherBottomSheetItem({
         onMotionComplete: handleMotionComplete,
         children: /*#__PURE__*/_jsx(BottomSheetSwitcherContext, {
           value: null,
-          children: /*#__PURE__*/_jsx(LayerDepthProvider, {
-            children: children
+          children: /*#__PURE__*/_jsx(ModalAnnounceProvider, {
+            dialogRef: dialogRef,
+            isOpen: isPresented && hasScrim,
+            children: /*#__PURE__*/_jsx(LayerDepthProvider, {
+              children: /*#__PURE__*/_jsx(BottomSheetEscapeContext, {
+                value: true,
+                children: /*#__PURE__*/_jsx(BottomSheetHostContext, {
+                  value: isInteractive ? OPEN_BOTTOM_SHEET_HOST : CLOSED_BOTTOM_SHEET_HOST,
+                  children: children
+                })
+              })
+            })
           })
         })
       })