@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/BottomSheet/BottomSheetPanel.tsx

@@ -6,13 +6,9 @@
  * @file BottomSheetPanel.tsx
  * @input Uses React, StyleX, theme tokens, text/provider boundaries, container padding, sheet gestures, shared scroll behavior, and the host label
  * @output Internal BottomSheetPanel with a keyboard-reachable scrolling body and motion-state types
- * @position Shared presentation layer for standalone and switcher BottomSheets
- *
- * This component owns everything intrinsic to a sheet surface: height budgets,
- * drag and snap gestures, the handle and scrolling body, the content box's
- * container padding, motion styles, and transition completion. It owns the
- * body's keyboard access; dialog focus entry/return, inert state, and switcher
- * registration belong to the host.
+ * @position Shared presentation layer for standalone and switcher
+ *   BottomSheets. It owns the sheet surface and the body's keyboard access.
+ *   The host owns dialog focus, inert state and switcher registration.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
@@ -71,7 +67,11 @@ import {
   type BottomSheetSnapPoint,
 } from './snapOffsets';
 import {useMobileKeyboard} from './useMobileKeyboard';
-import {useSheetGestures} from './useSheetGestures';
+import {
+  scrollPreservationPadding,
+  sheetLayoutHeight,
+  useSheetGestures,
+} from './useSheetGestures';
 
 const HEIGHT_BUDGETS = {
   hug: '92dvh',
@@ -92,12 +92,10 @@ const TRANSITION_BACKSTOP_BUFFER_MS = 50;
 // padding already provides.
 const HANDLE_BAR_HEIGHT = spacingVars['--spacing-6'];
 
-// Measure the same viewport the height budgets are written against. Those are
-// `dvh`, which the virtual keyboard does not shrink, so reading
-// `visualViewport` here would make the two disagree by exactly the keyboard's
-// height: every detent would move while the sheet it measures did not. A
-// keyboard is `useMobileKeyboard`'s business — it holds the sheet still and
-// scrolls the body — and it does not redefine the sheet's detents.
+// Measure the viewport that the height budgets use. They are `dvh`, which
+// the virtual keyboard does not shrink, so `visualViewport` would differ by
+// the keyboard's height. `useMobileKeyboard` handles the keyboard and does
+// not change the detents.
 function layoutViewportHeight(): number {
   return typeof window === 'undefined' ? 0 : window.innerHeight;
 }
@@ -121,9 +119,8 @@ function snapPointsKeyFor(
 }
 
 /**
- * The queries `design:reduced-motion` names: reduced motion with a coarse
- * primary pointer cross-fades (DR2); reduced motion otherwise changes at once
- * (DR3). The cross-fade's ceiling is the record's 200 ms.
+ * The reduced-motion queries. With a coarse primary pointer the sheet
+ * cross-fades, else it changes at once. The cross-fade lasts at most 200 ms.
  */
 const REDUCED_MOTION_COARSE =
   '@media (prefers-reduced-motion: reduce) and (pointer: coarse)';
@@ -144,13 +141,10 @@ const styles = stylex.create({
     width: '100%',
     maxWidth: 640,
     backgroundColor: colorVars['--color-background-surface'],
-    // Hairline on the three edges that face the scrim. The surface fill alone
-    // separates sheet from scrim in light mode, but not in dark: there the two
-    // sit within a few RGB steps of each other and the drop shadow is black on
-    // near-black, so the sheet's left and right edges disappear. Same
-    // treatment MobileNav gives its scrim-facing edge. The block-end edge is
-    // deliberately left bare; it sits below the viewport, under the overscroll
-    // padding.
+    // A hairline on the three edges that face the scrim. In dark mode the
+    // surface and the scrim are only a few RGB steps apart, and the shadow is
+    // black on near-black, so the side edges disappear. The block-end edge
+    // stays bare, below the viewport.
     borderBlockStartWidth: borderVars['--border-width'],
     borderBlockStartStyle: 'solid',
     borderBlockStartColor: colorVars['--color-border'],
@@ -167,10 +161,9 @@ const styles = stylex.create({
     overflow: 'hidden',
     paddingBlockEnd: `calc(env(safe-area-inset-bottom, 0px) + ${OVERSCROLL_PADDING}px)`,
     marginBlockEnd: `${-OVERSCROLL_PADDING}px`,
-    // Under reduced motion no transform runs (design:reduced-motion DR1). On
-    // a coarse primary pointer the entrance is an opacity-only cross-fade of
-    // at most 200 ms (DR2): the sheet appears at its resting place and fades
-    // in; a fine pointer gets the change at once (DR3), the 0.01s collapse.
+    // Under reduced motion no transform runs. On a coarse primary pointer the
+    // entrance is an opacity cross-fade of at most 200 ms. A fine pointer gets
+    // the change at once (the 0.01s collapse).
     transform: {
       default: 'translateY(0)',
       '@starting-style': {
@@ -196,27 +189,23 @@ const styles = stylex.create({
     transitionTimingFunction: easeVars['--ease-standard'],
     willChange: 'transform, opacity',
   },
+  // A sheet present on page load opens where it rests (spec:AST-013 FR13):
+  // the collapse reduced motion uses, so the transition still ends.
+  sheetSettled: {
+    transitionDuration: '0.01s',
+  },
   /**
-   * The exit is its own motion, not the entrance played backwards.
-   *
-   * `--ease-standard` is `cubic-bezier(0.24, 1, 0.4, 1)`, a decelerate curve:
-   * it spends its speed immediately and coasts. That is right for an entrance,
-   * where the sheet arrives fast and settles, and wrong for an exit. Measured
-   * on device, it put the sheet half off-screen in 59ms of a 410ms close and
-   * 90% off in 163ms -- the travel is over before the eye has followed it, and
-   * the rest of the duration moves pixels already below the fold.
-   *
-   * An exit accelerates instead (`--ease-exit`): away from rest, gathering
-   * speed, quickest as it leaves the screen. The curve is deliberately gentle
-   * rather than a hard `ease-in` -- it is moving within ~50ms, so the close
-   * reads as one departure rather than a hesitation and a snap. The duration
-   * is the entrance's own band, so only the curve differs between the two
-   * directions; a shorter band leaves too little visible travel once a theme
-   * scales the motion scale down (neutral's medium is 300ms against 410ms).
+   * The exit is its own motion, not the entrance played backwards. The
+   * decelerate `--ease-standard` put the sheet half off-screen in 59ms of a
+   * 410ms close, so the travel ended before the eye followed it. An exit
+   * accelerates instead (`--ease-exit`). The curve is gentle, so the sheet
+   * moves within ~50ms and the close reads as one departure. The duration is
+   * the entrance's band, because a shorter band leaves too little travel when
+   * a theme scales motion down.
    */
   sheetClosing: {
-    // Under reduced motion the exit does not travel (DR1); on a coarse
-    // pointer it fades out where it is (DR2), at once on a fine one (DR3).
+    // Under reduced motion the exit does not travel. On a coarse pointer it
+    // fades out where it is, and on a fine one it ends at once.
     transform: {
       default: 'translateY(100%)',
       '@media (prefers-reduced-motion: reduce)': 'translateY(0)',
@@ -225,19 +214,17 @@ const styles = stylex.create({
       default: null,
       [REDUCED_MOTION_COARSE]: 0,
     },
-    // A pointer presentation closes on the theme's exit curve (spec:AST-090
-    // FR12). A touch presentation keeps its own curve, which the exit tokens
-    // do not change.
+    // A pointer presentation closes on the theme's exit curve. A touch
+    // presentation keeps its own curve.
     transitionTimingFunction: {
       default: easeVars['--ease-exit'],
       '@media (pointer: coarse)': 'cubic-bezier(0.3, 0, 0.6, 0.6)',
     },
   },
   /**
-   * An exit that cross-fades on a pointer the media query does not cover: a
-   * touch swipe dismissal under reduced motion fades out in place on every
-   * pointer (design:reduced-motion DR2, the touch drag's release). The same
-   * opacity and ceiling the coarse-pointer rule uses.
+   * An exit that cross-fades on a pointer that the media query does not
+   * cover: a touch swipe dismissal under reduced motion fades out in place on
+   * every pointer. It uses the opacity and ceiling of the coarse-pointer rule.
    */
   sheetClosingCrossFade: {
     transform: 'translateY(0)',
@@ -274,8 +261,7 @@ const styles = stylex.create({
       default: 'grab',
       ':is(:disabled,[aria-disabled="true"])': 'default',
     },
-    // The pill, drawn on the grab bar itself: decoration with no role of its
-    // own (architecture:component-style-authoring INV7).
+    // The pill is drawn on the grab bar itself, as decoration with no role.
     '::before': {
       content: '""',
       width: sizeVars['--size-element-lg'],
@@ -354,6 +340,16 @@ interface BottomSheetPanelProps extends BaseProps<HTMLDivElement> {
   /** Ref forwarded to the visual sheet panel. */
   ref?: React.Ref<HTMLDivElement>;
   state: BottomSheetPanelState;
+  /**
+   * Whether the sheet was open on page load: it then opens where it rests,
+   * with no entry motion.
+   */
+  isEntrySettled?: boolean;
+  /**
+   * Called when the settled entry's transition ends, so the host can release
+   * it and later motion in the same open (a drag's settle) animates as usual.
+   */
+  onEntrySettled?: () => void;
   /**
    * The host's controlled open state — false as soon as the host has taken
    * a close, true while it is open or has refused one — distinct from
@@ -382,10 +378,9 @@ interface BottomSheetPanelProps extends BaseProps<HTMLDivElement> {
 }
 
 /**
- * A hidden sheet observes nothing (component:Popover PR1, FR5): the scroll
- * area's measuring ref attaches as the sheet presents and detaches once it is
- * hidden again, so a closed sheet that stays mounted holds no resize,
- * mutation or viewport observers.
+ * A hidden sheet observes nothing. The scroll area's measuring ref attaches
+ * as the sheet presents and detaches when it is hidden, so a closed sheet
+ * that stays mounted holds no resize, mutation or viewport observers.
  */
 function whilePresented<P extends {ref?: unknown}>(
   isPresented: boolean,
@@ -517,6 +512,9 @@ export function BottomSheetPanel({
   style,
   tabIndex,
   xstyle,
+  isEntrySettled = false,
+  onEntrySettled,
+  onTransitionEnd,
   isSwipeDismissAllowed = true,
   isPageScrollLocked = false,
   onDismiss,
@@ -556,8 +554,7 @@ export function BottomSheetPanel({
   const isClosing = state.kind === 'exiting';
   const isFading = isRetained && state.motion === 'fading';
   // Under reduced motion a retained sheet does not align down to a shorter
-  // entering sheet: that is travel (design:reduced-motion DR1). It fades where
-  // it is.
+  // entering sheet, because that is travel. It fades where it is.
   const isReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
   const alignmentOffset =
     isRetained && !isReducedMotion ? state.alignmentOffset : 0;
@@ -592,6 +589,8 @@ export function BottomSheetPanel({
     ignoredSnapPointsMessage !== '',
   );
 
+  // A caller's height owns the element's height: the drag never writes it.
+  const consumerHeight = style?.height;
   const {
     contentProps,
     handleProps,
@@ -616,6 +615,7 @@ export function BottomSheetPanel({
     onDismiss,
     snapHeights,
     onScrimOpacity,
+    hasFixedHeight: consumerHeight != null,
   });
 
   const {getViewportProps, getContentProps} = useScrollableArea({
@@ -665,10 +665,9 @@ export function BottomSheetPanel({
   useImperativeHandle(ref, () => elementRef.current as HTMLDivElement, []);
 
   const motion = motionForState(state);
-  // design:reduced-motion DR2: the cross-fade applies on a coarse pointer, and
-  // to a transition the release of a touch drag started — a finger's swipe
-  // dismissal fades out in place on every pointer. A mouse or pen drag is not
-  // a touch drag; DR3 covers it and the rest.
+  // The cross-fade applies on a coarse pointer, and to a transition that a
+  // touch drag's release started: a finger's swipe dismissal fades in place on
+  // every pointer. A mouse or pen drag is not a touch drag.
   const isCoarseCrossFade = useMediaQuery(REDUCED_MOTION_COARSE_QUERY);
   const isCrossFade =
     isCoarseCrossFade || (isReducedMotion && isDismissedByTouchDrag);
@@ -682,12 +681,11 @@ export function BottomSheetPanel({
       pendingMotionCompleteRef.current = motion;
       return;
     }
-    // What ends a motion: the fade is opacity; the entrance, alignment and
-    // exit are transforms — except that under the reduced-motion cross-fade
-    // (DR2) an exit fades out where it is and its dialog may close only once
-    // the fade has ended, so it waits on opacity. The entrance keeps waiting
-    // on its (instant) transform, so the retained sheet's fade starts at once
-    // and the two fades cross; the alignment is instant.
+    // What ends a motion: the fade is opacity, and the entrance, alignment and
+    // exit are transforms. Under the reduced-motion cross-fade an exit fades
+    // where it is, and its dialog closes only after the fade, so it waits on
+    // opacity. The entrance still waits on its instant transform, so the
+    // retained sheet's fade starts at once and the two fades cross.
     const crossFadeMotion = isCrossFade && motion === 'exiting';
     return waitForTransition(
       elementRef.current,
@@ -758,6 +756,8 @@ export function BottomSheetPanel({
     // transform — the layout height changes at rest, in one reconciling render
     // whose visible geometry is identical (see useSheetGestures).
     //   - dragging above the base restores the full height below the viewport
+    //     (the move that crosses writes that height to the element itself,
+    //     so this render only catches up to it)
     //   - a peek settles with layout 0, so it slides rather than reflowing
     const layoutOffset = isDragging
       ? dragOffset < settledOffset
@@ -774,7 +774,7 @@ export function BottomSheetPanel({
     const isTraveling = isDragging || settlingLayoutOffset != null;
     resizedHeight =
       layoutOffset > 0 || isTraveling
-        ? `${Math.max(0, sheetHeight - Math.max(0, layoutOffset))}px`
+        ? sheetLayoutHeight(sheetHeight, layoutOffset)
         : undefined;
     gestureTransform =
       translation !== 0 ? `translateY(${translation}px)` : undefined;
@@ -791,34 +791,56 @@ export function BottomSheetPanel({
       ? retainedTransform
       : undefined;
   const consumerTransform = style?.transform;
-  // The transform is written to the element here, not rendered through the
-  // style prop. A drag writes it straight to the element once per input
-  // sample (useSheetGestures) and renders nothing in between, so React never
-  // sees those writes; rendered through the prop, the resting value would be
-  // skipped as "unchanged" when the drag ends and the sheet would stay where
-  // the finger left it. Written after every commit instead, outside a drag,
-  // the resting value lands in the same style update as the restored
-  // transition, so a settle or a dismissal animates from the live position.
+  const hostHeight =
+    isInteractive || isRetained || isClosing ? resizedHeight : undefined;
+  const bodyEndPadding = scrollPreservationPadding(scrollPreservationInset);
+  // The transform is written to the element here, not through the style
+  // prop. A drag writes it straight to the element and renders nothing, so
+  // React never sees those writes. Through the prop, React would skip the
+  // resting value as unchanged, and the sheet would stay where the finger
+  // left it. Written after each commit outside a drag, the resting value
+  // lands with the restored transition, so a settle animates from the live
+  // position.
+  //
+  // A drag that crosses its base detent also writes the height and the end
+  // inset. If the release runs before that move's render commits, React sees
+  // no change and writes nothing, so these are written here too. A caller's
+  // height stays in the style prop, because the drag does not write it.
   useLayoutEffect(() => {
-    if (isDragging || consumerTransform != null) {
+    if (isDragging) {
       return;
     }
     const element = elementRef.current;
     if (element != null) {
-      element.style.transform = sheetTransform ?? '';
+      if (consumerTransform == null) {
+        element.style.transform = sheetTransform ?? '';
+      }
+      if (consumerHeight == null) {
+        element.style.height = hostHeight ?? '';
+      }
+    }
+    const body = bodyElementRef.current;
+    if (body != null) {
+      body.style.paddingBlockEnd = bodyEndPadding ?? '';
     }
   });
   const gestureStyle = {
     transition: contentProps.style.transition,
     touchAction: contentProps.style.touchAction,
     overscrollBehavior: contentProps.style.overscrollBehavior,
-    height: resizedHeight,
+    height: hostHeight,
   };
   return (
     <div
       {...props}
       ref={setElement}
       tabIndex={tabIndex ?? -1}
+      onTransitionEnd={event => {
+        onTransitionEnd?.(event);
+        if (isEntrySettled && event.target === event.currentTarget) {
+          onEntrySettled?.();
+        }
+      }}
       {...mergeProps(
         themeProps('bottom-sheet'),
         stylex.props(
@@ -831,6 +853,7 @@ export function BottomSheetPanel({
           isClosing && isCrossFade && styles.sheetClosingCrossFade,
           isFading && styles.sheetFading,
           isInactive && styles.sheetInactive,
+          isEntrySettled && styles.sheetSettled,
           xstyle,
         ),
         className,
@@ -839,7 +862,7 @@ export function BottomSheetPanel({
           ...(isInteractive
             ? gestureStyle
             : isRetained || isClosing
-              ? {height: resizedHeight}
+              ? {height: hostHeight}
               : {}),
           ...style,
         },
@@ -860,8 +883,8 @@ export function BottomSheetPanel({
                 styles.body,
                 height === 'tall' && styles.tallKeyboardBody,
               ),
-              scrollPreservationInset > 0
-                ? {style: {paddingBlockEnd: `${scrollPreservationInset}px`}}
+              bodyEndPadding != null
+                ? {style: {paddingBlockEnd: bodyEndPadding}}
                 : {},
             ),
           }),

package/src/BottomSheet/BottomSheetSwitcher.tsx

@@ -4,61 +4,12 @@
 
 /**
  * @file BottomSheetSwitcher.tsx
- * @input Uses React context, StyleX, shared layer dismissal, the modal outlet registry, the private bottom-sheet stack, BottomSheetSwitcherContext, BottomSheetHostContext
+ * @input React context, StyleX, shared layer dismissal, the modal outlet
+ *   registry, the private bottom-sheet stack, BottomSheetSwitcherContext,
+ *   BottomSheetHostContext
  * @output Exports BottomSheetSwitcher and BottomSheetSwitcherProps
- * @position Core switcher for mutually exclusive BottomSheet flows
- *
- * The switcher turns a set of declaratively nested BottomSheets into a
- * controlled single-selection group: `activeSheet` names the one interactive
- * child, or is null when the flow is closed. During a handoff the new sheet
- * enters above the previous sheet. If it is shorter, the previous sheet moves
- * down at the same time until their top edges align; otherwise it stays
- * stationary. The previous sheet fades only after both motions complete.
- *
- * Every child sheet owns a native `<dialog>`: a scrim flow presents each
- * sheet with showModal(), as a standalone modal sheet does, and a no-scrim
- * flow with show() inside the flow wrapper (a standalone no-scrim sheet is a
- * manual popover in the top layer instead; this deprecated path keeps its
- * released hosting). For a modal flow 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.
- *
- * A scrim flow is one level of the private bottom-sheet stack
- * (bottomSheetStack.ts) while it is visible: it stacks over, or under, other
- * modal sheets in open order, recedes as a whole when covered, and switching
- * its step in place never changes its position. The level is realized by the
- * active step's dialog; on a handoff the registry is told the dialog changed
- * so the sheets above the flow stay above its new dialog. A flow stacked
- * above another sheet keeps every step backdrop clear; a flow beneath owns
- * the stack's one scrim and hands it between its own steps as it always did.
- * A switcher step is never paired in a replace: the flow replaces its own
- * steps. A flow rendered in another sheet's content leaves and returns with
- * that sheet, like a standalone sheet, without its state being written. A
- * modal flow's host dialog is a toast outlet like a standalone scrim sheet's
- * (Layer/modalOutlet.ts), following the handoff. The switcher is deprecated
- * in favour of standalone step sheets.
+ * @position Core switcher for mutually exclusive BottomSheet flows. It is
+ *   deprecated in favor of standalone step sheets.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
@@ -67,13 +18,31 @@
  * - /packages/core/src/BottomSheet/BottomSheetStacking.test.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcherContext.ts
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.doc.mjs
- * - /packages/core/src/BottomSheet/BottomSheetSwitcher.spec.md
+ * - /docs/specs/components/BottomSheet/BottomSheetSwitcher.spec.md
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.test.tsx
  * - /packages/core/src/BottomSheet/index.ts
  * - /apps/storybook/stories/BottomSheetSwitcher.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/BottomSheet/BottomSheetSwitcherShowcase.tsx
  */
 
+// `activeSheet` names the one interactive child, or null when the flow is
+// closed. On a handoff the new sheet enters above the previous one. A taller
+// previous sheet moves down until the top edges align. The previous sheet
+// fades after both motions end.
+//
+// Each child sheet owns a native `<dialog>`. A scrim flow uses showModal(),
+// and a no-scrim flow uses show() inside the flow wrapper. The switcher
+// decides which dialog is presented, retained or hidden. It keeps one scrim
+// across a handoff, holds the flow's one scroll lock and one dismissal
+// registration, and returns focus to the flow's opener when the flow ends.
+//
+// The ref resolves to the host dialog: the active sheet's, the exiting
+// sheet's during its exit, else the last host's. `id` and `data-testid`
+// render on the host dialog only. Other dialog props apply to every sheet
+// dialog. A scrim flow is one level of the sheet stack (bottomSheetStack.ts),
+// and a step switch never changes that level. A modal flow's host dialog is
+// a toast outlet (Layer/modalOutlet.ts).
+
 import {
   use,
   useCallback,
@@ -87,6 +56,8 @@ import {
   type ReactNode,
   type SyntheticEvent,
 } from 'react';
+import {useIsHydrating} from '../hooks/useIsHydrating';
+import {useSettledOpen} from '../hooks/useSettledOpen';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '../BaseProps';
 import type {DialogPurpose} from '../Dialog';
@@ -130,13 +101,11 @@ const styles = stylex.create({
     display: 'contents',
   },
   // 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.
+  // order would decide which dialog paints in front. So the wrapper is the
+  // flow's isolated surface: the dialogs order themselves inside it, and the
+  // wrapper keeps the one overlay value of the old shared shell. It
+  // passes pointer input through, and each panel opts back in. Consumers of
+  // this mode must avoid transformed or clipping ancestors.
   flowNonModal: {
     display: 'block',
     position: 'fixed',
@@ -250,9 +219,11 @@ function takeOverScrim(dialog: HTMLDialogElement, opacity: number): void {
  * by one state value that names the open step; closing the top sheet and
  * opening the next in the same update, from inside the open step, runs the
  * same replace handoff (see BottomSheet, "Replacing a sheet"). Keeps working until a future minor
- * release removes it: on its own as released (plus two fixes: a toast raised
- * from a step now renders above the flow and can be pressed, and reduced motion
- * follows design:reduced-motion), as one stack level when stacked.
+ * release removes it: on its own as released (plus three fixes: a toast raised
+ * from a step now renders above the flow and can be pressed, reduced motion
+ * follows the reduced-motion design rules, and a flow whose active sheet is set on the
+ * server renders closed until hydration, then opens that sheet settled), as
+ * one stack level when stacked.
  */
 export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {
   /**
@@ -309,10 +280,11 @@ export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {
  * `sheetId` and no switcher, for modal and `hasScrim={false}` flows alike; a
  * step changed from outside the flow's sheets closes and opens with the
  * sheets' own motion. The switcher keeps working until a future
- * minor release removes it: on its own as released (plus two fixes: a toast
- * raised from a step now renders above the flow and can be pressed, and reduced
- * motion follows design:reduced-motion), and as one level of the stack when
- * stacked with other sheets.
+ * minor release removes it: on its own as released (plus three fixes: a toast
+ * raised from a step now renders above the flow and can be pressed, reduced
+ * motion follows the reduced-motion design rules, and a flow whose active sheet is set
+ * on the server renders closed until hydration, then opens that sheet
+ * settled), and as one level of the stack when stacked with other sheets.
  */
 export function BottomSheetSwitcher({
   activeSheet: activeSheetProp,
@@ -335,7 +307,20 @@ export function BottomSheetSwitcher({
   // for it; with the host closed the flow simply reads as closed.
   const host = use(BottomSheetHostContext);
   const isHostOpen = host?.isOpen ?? true;
-  const activeSheet = isHostOpen ? activeSheetProp : null;
+  // A flow with an active sheet on the server reads as closed until
+  // hydration. It opens in the next render, the first one that can enter its
+  // native host. A <dialog> painted open with aria-modal before it is modal
+  // claims a state it does not have.
+  const isHydrating = useIsHydrating();
+  const activeSheet = isHostOpen && !isHydrating ? activeSheetProp : null;
+  // The step active on the server opens settled, with no entry motion. The
+  // first change of step animates (AST-013 FR13). It latches on the flow's
+  // own request, because a hydrating host sheet reads as closed.
+  const [settledSheet, releaseSettledSheet] = useSettledOpen(
+    activeSheetProp,
+    activeSheet,
+    null,
+  );
   // Every sheet host applies the switcher's dialog surface to its own dialog.
   const dialogProps = useShallowStable<BottomSheetSwitcherDialogProps>({
     ...restDialogProps,
@@ -549,14 +534,11 @@ export function BottomSheetSwitcher({
     [],
   );
 
-  // The flow's host dialog is an outlet for app-global surfaces (toasts)
-  // while the flow is a modal one, as a standalone scrim sheet's dialog is
-  // (`component:BottomSheet` FR13): every open scrim sheet supplies one, the
-  // latest among sheets follows the stack, and a Dialog supplied later stays
-  // above. The host changes on a handoff, so the supply follows `hostSheet`;
-  // the retained step's dialog, inert and fading, is never the outlet. A
-  // closing flow stops supplying at once, as a closing sheet does. Passive:
-  // it runs after the layout effects that present the step dialogs.
+  // While the flow is modal, its host dialog is an outlet for app-global
+  // surfaces (toasts), as a standalone scrim sheet's is. The supply follows
+  // `hostSheet` across a handoff, and the fading retained dialog is never the
+  // outlet. A closing flow stops supplying at once. Passive: it runs after the
+  // layout effects that present the step dialogs.
   useModalOutlet(
     hostDialogRef,
     isModal && isFlowOpen,
@@ -1033,6 +1015,8 @@ export function BottomSheetSwitcher({
   const contextValue = useMemo<BottomSheetSwitcherContextValue>(
     () => ({
       activeSheet,
+      settledSheet,
+      releaseSettledSheet,
       hasScrim,
       onActiveSheetChange,
       getSheetPhase,
@@ -1075,6 +1059,8 @@ export function BottomSheetSwitcher({
       registerSheetDialog,
       registerSheetElement,
       registerSheetPurpose,
+      releaseSettledSheet,
+      settledSheet,
       stackView,
     ],
   );

package/src/BottomSheet/BottomSheetSwitcherContext.ts

@@ -50,6 +50,14 @@ export type BottomSheetSwitcherDialogProps = Omit<
 
 export interface BottomSheetSwitcherContextValue {
   activeSheet: string | null;
+  /**
+   * The sheet that was active on page load, until the active sheet first
+   * changes: it opens where it rests, with no entry motion
+   * (spec:AST-013 FR13).
+   */
+  settledSheet: string | null;
+  /** Releases `settledSheet` once its settled entry's transition ends. */
+  releaseSettledSheet: () => void;
   hasScrim: boolean;
   onActiveSheetChange: (sheetId: string | null) => void;
   getSheetPhase: (sheetId: string) => BottomSheetSwitcherPhase;

package/src/BottomSheet/bottomSheetEscape.ts

@@ -9,9 +9,9 @@
  *   request) may dismiss the standalone sheet below it
  * @position Internal to Core, not exported from the package: Popover's sheet
  *   presentation passes `hasEscapeDismiss` through it, so its sheet can
- *   light-dismiss (scrim tap, swipe down) while Escape stays off
- *   (component:Popover DEC-8). A standalone BottomSheet reads the default
- *   (true), so its `purpose` rule is unchanged.
+ *   light-dismiss (scrim tap, swipe down) while Escape stays off. A
+ *   standalone BottomSheet reads the default (true), so its `purpose` rule
+ *   is unchanged.
  */
 
 import {createContext} from 'react';