@astryxdesign/core 0.7.6-canary.eae71cb → 0.7.6-canary.eb282ba

package/dist/BottomSheet/BottomSheet.js

@@ -4,60 +4,12 @@
 
 /**
  * @file BottomSheet.tsx
- * @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
+ * @input React, StyleX, core hooks, shared layer dismissal, the modal outlet
+ *   registry, interaction modality, BottomSheetPanel, the switcher and host
+ *   contexts, and the private bottom-sheet stack registry
  * @output Exports BottomSheet component and BottomSheetProps
  * @position Public BottomSheet router plus private standalone/switcher hosts
  *
- * BottomSheet selects one of two focused hosts. A standalone host owns its
- * native dialog lifecycle and joins the shared layer dismissal stack; a
- * switcher item owns a native dialog of its own too, but hands its lifecycle
- * to the parent's transition state machine, scrim ownership, and dismissal
- * registration. Both render the same BottomSheetPanel, which owns sheet
- * presentation, content padding, gestures, mobile-keyboard accommodation,
- * and motion completion.
- *
- * Every sheet dialog is native first. A scrim-backed sheet is presented with
- * showModal(): the browser makes the page inert and keeps focus inside the
- * dialog, delivers Escape and the platform close as `cancel`, paints the
- * scrim as `::backdrop`, and returns focus to the opener on close(). Page
- * 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, 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
@@ -76,7 +28,30 @@
  * - /apps/storybook/stories/BottomSheetReplace.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/BottomSheet/BottomSheetShowcase.tsx
  */
+
+// BottomSheet picks one of two hosts. A standalone host owns its native
+// dialog and joins the shared layer dismissal stack. A switcher item also
+// owns a native dialog, but its parent switcher owns the lifecycle, the scrim
+// and dismissal. Both render BottomSheetPanel, which owns presentation,
+// padding, gestures, the mobile keyboard and motion.
+//
+// A scrim sheet uses showModal(), so the browser makes the page inert, keeps
+// focus in the dialog, sends Escape as `cancel`, paints `::backdrop`, and
+// returns focus on close(). Script does only what one dialog cannot: it gates
+// `cancel` by `purpose`, orders the stack of sheets, and hands one scrim
+// between dialogs.
+//
+// A standalone sheet joins the private sheet stack (bottomSheetStack.ts)
+// while it is presented. A modal sheet opened over another stacks on top, and
+// the covered sheet recedes. The stack keeps the top layer in open order,
+// also when several sheets open in one commit. A sheet that closes as another
+// opens, from a control inside it, is replaced with the switcher's handoff.
+// Non-modal sheets (`hasScrim={false}`) are manual popovers. They never
+// stack, but they replace each other. Each open modal sheet is an outlet for
+// toasts (Layer/modalOutlet.ts), in stack order.
 import { use, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useIsHydrating } from "../hooks/useIsHydrating.js";
+import { useSettledOpen } from "../hooks/useSettledOpen.js";
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, durationVars, easeVars, spacingVars } from "../theme/tokens.stylex.js";
@@ -96,6 +71,7 @@ import { BottomSheetHostContext, CLOSED_BOTTOM_SHEET_HOST, OPEN_BOTTOM_SHEET_HOS
 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 { layerClickBoundary } from "../Layer/layerClickBoundary.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const styles = {
   dialog: {
@@ -151,6 +127,10 @@ const styles = {
     k4oj2o: "x15l12jy",
     $$css: true
   },
+  scrimSettled: {
+    k9an0g: "x108qnu8",
+    $$css: true
+  },
   scrimClosing: {
     kb4ib: "x1cz9k3x",
     $$css: true
@@ -272,7 +252,18 @@ function StandaloneBottomSheet({
   // state stays the consumer's; nothing here writes it.
   const host = use(BottomSheetHostContext);
   const isHostOpen = host?.isOpen ?? true;
-  const isOpen = isOpenProp && isHostOpen;
+  // A sheet open on the server renders 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 isOpen = isOpenProp && isHostOpen && !isHydrating;
+  // A sheet open on the server opens settled, with no rise or fade-in. Later
+  // opens and closes animate. It latches on its own request, not its host's
+  // state, because a hydrating host reads as closed. The latch ends when the
+  // settled entry's transition ends, so a later drag settle glides.
+  const [settledOpen, releaseSettledOpen] = useSettledOpen(isOpenProp, isOpen, false);
+  const isEntrySettled = settledOpen && isOpen;
   // 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
@@ -293,14 +284,12 @@ function StandaloneBottomSheet({
   // 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.
+  // Only the layout phase knows if a replace pairs this close. Until the
+  // registry answers (a synchronous re-render before paint), the panel holds
+  // its open pose. An exit pose rendered first would start the exit
+  // transition, and the reversal would snap the panel to rest. Each change of
+  // `isOpen` restarts the flag during render, and the layout effect below
+  // settles a close.
   const [isCloseSettled, setIsCloseSettled] = useState(false);
   const [settledIsOpen, setSettledIsOpen] = useState(isOpen);
   if (settledIsOpen !== isOpen) {
@@ -436,17 +425,12 @@ function StandaloneBottomSheet({
     }
   }, [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.
+  // An open modal sheet hosts app-global surfaces (toasts), so they stay
+  // visible above it. The latest outlet follows the sheet stack's order, so a
+  // toast lands in the top sheet and goes back to the revealed sheet when the
+  // top one closes. A Dialog opened from a sheet stays above every sheet. A
+  // closing sheet stops supplying when it starts to close. 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(() => {
@@ -502,19 +486,15 @@ function StandaloneBottomSheet({
       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.
+    // The native close can show a focus ring on the target. Clear it. The
+    // ring shows only after keyboard input.
     //
-    // 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.
+    // If a sheet is open below, focus goes to this sheet's opener when it is
+    // in that sheet, else to that 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).
+    // A non-modal sheet returns focus to its opener only if focus was still
+    // in the sheet. The page behind it stays live, so the person can move
+    // focus away first.
     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))) {
@@ -589,7 +569,7 @@ function StandaloneBottomSheet({
     // 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),
+    ...stackPositionerStyles(stackView), hasScrim && styles.scrim, hasScrim && isEntrySettled && styles.scrimSettled, hasScrim && isExiting && styles.scrimClosing, !hasScrim && styles.dialogNonModal),
     ref: dialogComposedRef
     // A non-modal sheet is hosted in the top layer as a manual popover
     // (no light dismiss, no backdrop), so sheets order by presentation
@@ -605,12 +585,19 @@ function StandaloneBottomSheet({
     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,
+    onCancel: handleCancel
+    // Presses inside the sheet do not reach handlers around where it is
+    // written. The dialog, not the panel, is the root, as in a switcher.
+    ,
+    ...layerClickBoundary({
+      onClick: handleClick
+    }),
     children: [/*#__PURE__*/_jsx(BottomSheetPanel, {
       ...props,
       ref: ref,
       state: panelState,
+      isEntrySettled: isEntrySettled,
+      onEntrySettled: releaseSettledOpen,
       isOpenRequested: isOpen,
       height: height,
       label: label,
@@ -672,7 +659,9 @@ function SwitcherBottomSheetItem({
     dialogProps,
     onDialogCancel,
     onDialogClick,
-    onDialogKeyDown
+    onDialogKeyDown,
+    settledSheet,
+    releaseSettledSheet
   } = switcher;
   const hasValidSheetId = typeof sheetId === 'string' && sheetId.length > 0;
   const phase = hasValidSheetId ? getSheetPhase(sheetId) : 'hidden';
@@ -681,6 +670,8 @@ function SwitcherBottomSheetItem({
   const isInteractive = phase === 'active' || phase === 'entering';
   const isInactive = phase === 'covered' || phase === 'aligning' || phase === 'fading' || phase === 'exiting';
   const isPresented = phase !== 'hidden';
+  // The step open on the server opens settled.
+  const isEntrySettled = hasValidSheetId && isPresented && settledSheet === sheetId;
   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
@@ -833,7 +824,7 @@ function SwitcherBottomSheetItem({
     'data-testid': switcherTestId,
     ...switcherDialogProps
   } = dialogProps;
-  const dialogPresentationProps = mergeProps(stylex.props(styles.dialog, isPresented && styles.dialogOpen, hasScrim && styles.scrim, hasScrim && ownsScrim && isFlowClosing && styles.scrimClosing, !hasScrim && styles.dialogNonModalItem, !hasScrim && isTopSheet && styles.dialogNonModalItemTop, switcherXstyle), switcherClassName, switcherStyle);
+  const dialogPresentationProps = mergeProps(stylex.props(styles.dialog, isPresented && styles.dialogOpen, hasScrim && styles.scrim, hasScrim && isEntrySettled && styles.scrimSettled, hasScrim && ownsScrim && isFlowClosing && styles.scrimClosing, !hasScrim && styles.dialogNonModalItem, !hasScrim && isTopSheet && styles.dialogNonModalItemTop, switcherXstyle), switcherClassName, switcherStyle);
   return /*#__PURE__*/_jsxs("dialog", {
     ...switcherDialogProps,
     ...dialogPresentationProps,
@@ -849,8 +840,15 @@ function SwitcherBottomSheetItem({
     "data-sheet-stack-depth": hasScrim && isPresented && stackView.depth > 0 ? stackView.depth : undefined,
     role: purpose === 'required' ? 'alertdialog' : switcherDialogProps.role,
     onCancel: onDialogCancel,
-    onClick: onDialogClick,
-    onKeyDown: onDialogKeyDown,
+    onKeyDown: onDialogKeyDown
+    // Presses inside the sheet do not reach handlers around where it is
+    // written. The step's dialog, not the panel, is the root, because the
+    // switcher's handlers sit here and must still run.
+    ,
+    ...layerClickBoundary({
+      ...switcherDialogProps,
+      onClick: onDialogClick
+    }),
     children: [/*#__PURE__*/_jsx("div", {
       ...stylex.props(styles.positioner, !isPresented && styles.positionerHidden, isTopSheet && styles.positionerTop, ...(hasScrim ? stackPositionerStyles(stackView) : [])),
       hidden: !isPresented,
@@ -860,6 +858,8 @@ function SwitcherBottomSheetItem({
         ...props,
         ref: ref,
         state: panelState,
+        isEntrySettled: isEntrySettled,
+        onEntrySettled: releaseSettledSheet,
         isOpenRequested: hasValidSheetId && activeSheet === sheetId,
         height: height,
         label: label,

package/dist/BottomSheet/BottomSheetEdgeTint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BottomSheetEdgeTint.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetEdgeTint.tsx"],"names":[],"mappings":"AAkEA;;;GAGG;AACH,wBAAgB,mBAAmB,gCAQlC"}
+{"version":3,"file":"BottomSheetEdgeTint.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetEdgeTint.tsx"],"names":[],"mappings":"AAuDA;;;GAGG;AACH,wBAAgB,mBAAmB,gCAQlC"}

package/dist/BottomSheet/BottomSheetEdgeTint.js

@@ -4,34 +4,23 @@
 
 /**
  * @file BottomSheetEdgeTint.tsx
- * @input Uses StyleX and core color tokens
- * @output Exports BottomSheetEdgeTint, an internal decorative element
+ * @input StyleX and core color tokens
+ * @output BottomSheetEdgeTint, an internal decorative element
  * @position Private helper rendered inside every BottomSheet dialog
  *
- * iOS 26 Safari dropped `<meta name="theme-color">` and instead derives the
- * colour it paints behind its translucent toolbars by sampling the page: it
- * hit tests a point just inside each viewport edge, walks up to the nearest
- * `fixed`/`sticky` ancestor, and extends that element's declared
- * `background-color` into the browser chrome.
- *
- * WebKit may otherwise extend either the dialog backdrop or the host page into
- * the browser chrome. Which one wins varies with dialog mode and the page's
- * own fixed or sticky edge content, so relying on the backdrop makes otherwise
- * identical BottomSheets produce different toolbar colours.
- *
- * This element gives the heuristic something unambiguous to sample: fixed,
- * full width, flush with the bottom edge, taller than WebKit's 10px minimum
- * for reading a declared colour, and painted in the sheet's own surface
- * colour. It is masked out so it never renders for the user; Safari reads the
- * computed style, not the painted pixels.
- *
- * Everywhere else it is inert decoration.
- *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
  * - /packages/core/src/BottomSheet/BottomSheetEdgeTint.test.tsx
  */
+
+// iOS Safari colors its translucent toolbars by sampling the page. It hit
+// tests a point inside each viewport edge, finds the nearest fixed or sticky
+// ancestor, and extends its `background-color`. Without this element, WebKit
+// can pick the dialog backdrop or the page, so equal sheets get different
+// toolbar colors. This element is fixed, full width, at the bottom edge,
+// taller than WebKit's 10px minimum, and in the sheet's surface color. It is
+// masked out: Safari reads the computed style, not the pixels.
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars } from "../theme/tokens.stylex.js";

package/dist/BottomSheet/BottomSheetHostContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BottomSheetHostContext.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetHostContext.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,2BAA2B;IAC1C,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,sBAAsB,6DACsB,CAAC;AAG1D,eAAO,MAAM,sBAAsB,EAAE,2BAEpC,CAAC;AACF,eAAO,MAAM,wBAAwB,EAAE,2BAEtC,CAAC"}
+{"version":3,"file":"BottomSheetHostContext.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetHostContext.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,2BAA2B;IAC1C,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,eAAO,MAAM,sBAAsB,6DACsB,CAAC;AAG1D,eAAO,MAAM,sBAAsB,EAAE,2BAEpC,CAAC;AACF,eAAO,MAAM,wBAAwB,EAAE,2BAEtC,CAAC"}

package/dist/BottomSheet/BottomSheetHostContext.js

@@ -13,17 +13,13 @@
  * - /packages/core/src/BottomSheet/BottomSheet.tsx
  * - /packages/core/src/BottomSheet/BottomSheetSwitcher.tsx
  * - /packages/core/src/BottomSheet/BottomSheetStacking.test.tsx
- *
- * A sheet rendered in another sheet's content is part of that sheet: it is
- * presented only while its host is open, leaves with it, and comes back with
- * it if its own `isOpen` is still true. Without this a host closing from code
- * would leave the inner dialog open in the top layer with no box to paint —
- * an invisible modal blocking the page. The inner sheet's state is never
- * written by the host: it stays the consumer's, as with a Dialog rendered in
- * a closed Dialog. The context is provided by every host (standalone, modal
- * or not, and each switcher step) and read by every standalone sheet and
- * every switcher flow; at the root it is null, which reads as "open".
  */
+
+// A sheet rendered in another sheet's content is presented only while its
+// host is open. Without this, a host that closes from code would leave the
+// inner dialog open in the top layer with no box: an invisible modal that
+// blocks the page. The host never writes the inner sheet's state. At the
+// root the context is null, which reads as open.
 import { createContext } from 'react';
 export const BottomSheetHostContext = /*#__PURE__*/createContext(null);
 BottomSheetHostContext.displayName = 'BottomSheetHostContext';

package/dist/BottomSheet/BottomSheetPanel.d.ts

@@ -2,13 +2,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
@@ -47,6 +43,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
@@ -74,7 +80,7 @@ interface BottomSheetPanelProps extends BaseProps<HTMLDivElement> {
     onMotionComplete?: (motion: BottomSheetPanelMotion) => void;
 }
 /** Internal visual and gesture surface shared by every BottomSheet host. */
-export declare function BottomSheetPanel({ ref, state, isOpenRequested, height, label, children, padding, snapPoints, className, style, tabIndex, xstyle, isSwipeDismissAllowed, isPageScrollLocked, onDismiss, onScrimOpacity, onElementChange, onMotionStart, onMotionComplete, ...props }: BottomSheetPanelProps): import("react").JSX.Element;
+export declare function BottomSheetPanel({ ref, state, isOpenRequested, height, label, children, padding, snapPoints, className, style, tabIndex, xstyle, isEntrySettled, onEntrySettled, onTransitionEnd, isSwipeDismissAllowed, isPageScrollLocked, onDismiss, onScrimOpacity, onElementChange, onMotionStart, onMotionComplete, ...props }: BottomSheetPanelProps): import("react").JSX.Element;
 export declare namespace BottomSheetPanel {
     var displayName: string;
 }

package/dist/BottomSheet/BottomSheetPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BottomSheetPanel.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetPanel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA+B5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AAQvB,QAAA,MAAM,cAAc;;;;CAIV,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,cAAc,CAAC;AAC5D,YAAY,EAAC,oBAAoB,EAAC,CAAC;AA+CnC,eAAO,MAAM,2BAA2B,2DACkB,CAAC;AAiN3D,MAAM,MAAM,sBAAsB,GAChC,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD,MAAM,MAAM,qBAAqB,GAC7B;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,GAChB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAC,GACjC;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC1C,eAAe,EAAE,MAAM,CAAC;CACzB,GACD;IAAC,IAAI,EAAE,SAAS,CAAA;CAAC,CAAC;AAEtB,UAAU,qBAAsB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC/D,+CAA+C;IAC/C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,KAAK,EAAE,qBAAqB,CAAC;IAC7B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,UAAU,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IACjD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3D,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACzD,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;CAC7D;AA4HD,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,EAC/B,GAAG,EACH,KAAK,EACL,eAAe,EACf,MAAM,EACN,KAAK,EACL,QAAQ,EACR,OAAO,EACP,UAAU,EACV,SAAS,EACT,KAAK,EACL,QAAQ,EACR,MAAM,EACN,qBAA4B,EAC5B,kBAA0B,EAC1B,SAAS,EACT,cAAc,EACd,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,GAAG,KAAK,EACT,EAAE,qBAAqB,+BAoZvB;yBAzae,gBAAgB"}
+{"version":3,"file":"BottomSheetPanel.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheetPanel.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA+B5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AAQvB,QAAA,MAAM,cAAc;;;;CAIV,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,cAAc,CAAC;AAC5D,YAAY,EAAC,oBAAoB,EAAC,CAAC;AA4CnC,eAAO,MAAM,2BAA2B,2DACkB,CAAC;AAsM3D,MAAM,MAAM,sBAAsB,GAChC,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD,MAAM,MAAM,qBAAqB,GAC7B;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,GAChB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAC,GACjC;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IAC1C,eAAe,EAAE,MAAM,CAAC;CACzB,GACD;IAAC,IAAI,EAAE,SAAS,CAAA;CAAC,CAAC;AAEtB,UAAU,qBAAsB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC/D,+CAA+C;IAC/C,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,KAAK,EAAE,qBAAqB,CAAC;IAC7B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,UAAU,CAAC,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IACjD,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,KAAK,IAAI,CAAC;IAC3D,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACzD,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;CAC7D;AA2HD,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,EAC/B,GAAG,EACH,KAAK,EACL,eAAe,EACf,MAAM,EACN,KAAK,EACL,QAAQ,EACR,OAAO,EACP,UAAU,EACV,SAAS,EACT,KAAK,EACL,QAAQ,EACR,MAAM,EACN,cAAsB,EACtB,cAAc,EACd,eAAe,EACf,qBAA4B,EAC5B,kBAA0B,EAC1B,SAAS,EACT,cAAc,EACd,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,GAAG,KAAK,EACT,EAAE,qBAAqB,+BAkZvB;yBA1ae,gBAAgB"}

package/dist/BottomSheet/BottomSheetPanel.js

@@ -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
@@ -56,12 +52,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() {
   return typeof window === 'undefined' ? 0 : window.innerHeight;
 }
@@ -83,9 +77,8 @@ function snapPointsKeyFor(points) {
 }
 
 /**
- * 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)';
 export const REDUCED_MOTION_COARSE_QUERY = '(prefers-reduced-motion: reduce) and (pointer: coarse)';
@@ -125,6 +118,10 @@ const styles = {
     k6sLGO: "x1q1rmc8",
     $$css: true
   },
+  sheetSettled: {
+    kIyJzY: "xpvlhck",
+    $$css: true
+  },
   sheetClosing: {
     k3aq6I: "x1weeur4 x1oe9tb1",
     kSiTet: "x1m67veq",
@@ -181,10 +178,9 @@ const styles = {
   }
 };
 /**
- * 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(isPresented, props) {
   return isPresented ? props : {
@@ -293,6 +289,9 @@ export function BottomSheetPanel({
   style,
   tabIndex,
   xstyle,
+  isEntrySettled = false,
+  onEntrySettled,
+  onTransitionEnd,
   isSwipeDismissAllowed = true,
   isPageScrollLocked = false,
   onDismiss,
@@ -329,8 +328,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;
 
@@ -437,10 +435,9 @@ export function BottomSheetPanel({
   // could be mistaken for the panel unmounting and cancel a sheet handoff.
   useImperativeHandle(ref, () => elementRef.current, []);
   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;
   useLayoutEffect(() => {
@@ -453,12 +450,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, motion === 'fading' || crossFadeMotion ? 'opacity' : 'transform', () => {
       if (startedMotionRef.current === motion) {
@@ -536,24 +532,18 @@ export function BottomSheetPanel({
   const consumerTransform = style?.transform;
   const hostHeight = isInteractive || isRetained || isClosing ? resizedHeight : undefined;
   const bodyEndPadding = scrollPreservationPadding(scrollPreservationInset);
-  // 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.
+  // 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.
   //
-  // The height and the scrolling area's end inset are rendered through props,
-  // but a drag that crosses its base detent writes them to the elements too.
-  // When the release is processed before that move's render commits, React
-  // compares the resting values with the ones it committed before the drag,
-  // finds them unchanged and writes nothing, so the sheet would stay drawn at
-  // the drag's height. They are written here after every commit, outside a
-  // drag, for the same reason as the transform. A caller's height is left to
-  // the style prop: the drag does not write over it, so there is nothing to
-  // restore.
+  // 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) {
       return;
@@ -582,7 +572,13 @@ export function BottomSheetPanel({
     ...props,
     ref: setElement,
     tabIndex: tabIndex ?? -1,
-    ...mergeProps(themeProps('bottom-sheet'), stylex.props(layerTextReset.reset, layerStructureReset.reset, styles.sheet, overlayPaddingReset.reset, height === 'hug' ? styles.hugHeight : styles.budget, isClosing && styles.sheetClosing, isClosing && isCrossFade && styles.sheetClosingCrossFade, isFading && styles.sheetFading, isInactive && styles.sheetInactive, xstyle), className, {
+    onTransitionEnd: event => {
+      onTransitionEnd?.(event);
+      if (isEntrySettled && event.target === event.currentTarget) {
+        onEntrySettled?.();
+      }
+    },
+    ...mergeProps(themeProps('bottom-sheet'), stylex.props(layerTextReset.reset, layerStructureReset.reset, styles.sheet, overlayPaddingReset.reset, height === 'hug' ? styles.hugHeight : styles.budget, isClosing && styles.sheetClosing, isClosing && isCrossFade && styles.sheetClosingCrossFade, isFading && styles.sheetFading, isInactive && styles.sheetInactive, isEntrySettled && styles.sheetSettled, xstyle), className, {
       ['--_sheet-budget']: budget,
       ...(isInteractive ? gestureStyle : isRetained || isClosing ? {
         height: hostHeight