@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/BottomSheet/BottomSheet.tsx

@@ -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
@@ -77,6 +29,27 @@
  * - /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,
@@ -87,6 +60,8 @@ import {
   type RefObject,
   type ReactNode,
 } 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';
@@ -99,6 +74,7 @@ import {
 } from '../theme/tokens.stylex';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {useScrollLock} from '../hooks/useScrollLock';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import {mergeProps} from '../utils/mergeProps';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
@@ -147,6 +123,7 @@ import {
 export type {BottomSheetHeight, BottomSheetSnapPoint} from './BottomSheetPanel';
 import type {BottomSheetHeight, BottomSheetSnapPoint} from './BottomSheetPanel';
 import {BottomSheetEscapeContext} from './bottomSheetEscape';
+import {layerClickBoundary} from '../Layer/layerClickBoundary';
 
 const styles = stylex.create({
   dialog: {
@@ -168,21 +145,18 @@ const styles = stylex.create({
   dialogOpen: {
     display: 'block',
   },
-  // An open standalone dialog is its panel's positioner: the panel sits at its
-  // block end, centred, with no wrapper between them
-  // (architecture:component-style-authoring INV7). A tap beside a narrower
-  // panel lands on the dialog itself, which light dismiss reads. The stack's
-  // recede (stackPositionerStyles) is applied to this dialog too, so a
-  // covered standalone sheet shrinks and lifts as one, panel and all.
+  // An open standalone dialog positions its panel: the panel sits at its
+  // block end, centred, with no wrapper. A tap beside a narrower panel lands
+  // on the dialog, which light dismiss reads. The stack's recede applies to
+  // this dialog too, so a covered sheet shrinks and lifts as one.
   dialogPanelHost: {
     display: 'grid',
     alignContent: 'end',
     justifyItems: 'center',
   },
-  // A non-modal sheet is hosted in the top layer (manual popover), so it
-  // carries no page-level z-index (spec:AST-027). Below the Popover API
-  // floor `show()` leaves it in page stacking order as a reduced fallback:
-  // usable, but with no promise over later page content.
+  // A non-modal sheet is in the top layer as a manual popover, so it has no
+  // page z-index (AST-027). Below the Popover API floor, `show()` leaves it
+  // in page stacking order as a reduced fallback.
   dialogNonModal: {
     pointerEvents: 'none',
     width: '100%',
@@ -215,14 +189,18 @@ const styles = stylex.create({
       },
     },
   },
+  // A sheet present on page load dims at once (AST-013 FR13), with the
+  // reduced-motion collapse, so the transition still ends.
+  scrimSettled: {
+    '::backdrop': {
+      transitionDuration: '0.01s',
+    },
+  },
   /**
-   * The dim leaves with the sheet, on a curve that matches.
-   *
-   * A fade covers no distance, so the decelerate token front-loads its
-   * progress and simply ends it early: `--ease-standard` puts the scrim at 90%
-   * faded in 163ms of a 410ms close, leaving an undimmed page under a sheet
-   * that is still sliding across it. `linear` spends the duration it is given.
-   * Same reasoning the touch date picker's surface swap already carries.
+   * The dim leaves with the sheet, on a matching curve. A fade covers no
+   * distance, so `--ease-standard` would end it early: 90% faded after 163ms
+   * of a 410ms close, under a sheet that is still sliding. `linear` uses the
+   * whole duration.
    */
   scrimClosing: {
     '::backdrop': {
@@ -422,7 +400,22 @@ 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
@@ -445,14 +438,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) {
@@ -603,17 +594,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,
@@ -679,19 +665,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;
@@ -711,7 +693,8 @@ function StandaloneBottomSheet({
     [finalFocusRef, hasScrim, isOpen],
   );
 
-  useInteractionModalityTracking();
+  const {ref: modalityRef} = useInteractionModalityTracking();
+  const dialogComposedRef = useMergedRefs(dialogRef, modalityRef);
   useScrollLock(shouldPresent && hasScrim);
   useDevWarning(
     'BottomSheet',
@@ -794,10 +777,11 @@ function StandaloneBottomSheet({
         // one. The backdrop is not a descendant and stays put.
         ...stackPositionerStyles(stackView),
         hasScrim && styles.scrim,
+        hasScrim && isEntrySettled && styles.scrimSettled,
         hasScrim && isExiting && styles.scrimClosing,
         !hasScrim && styles.dialogNonModal,
       )}
-      ref={dialogRef}
+      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
       // without a page-level z-index. Below the Popover API floor the
@@ -816,11 +800,15 @@ function StandaloneBottomSheet({
         hasScrim && stackView.depth > 0 ? stackView.depth : undefined
       }
       onCancel={handleCancel}
-      onClick={handleClick}>
+      // 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})}>
       <BottomSheetPanel
         {...props}
         ref={ref}
         state={panelState}
+        isEntrySettled={isEntrySettled}
+        onEntrySettled={releaseSettledOpen}
         isOpenRequested={isOpen}
         height={height}
         label={label}
@@ -895,6 +883,8 @@ function SwitcherBottomSheetItem({
     onDialogCancel,
     onDialogClick,
     onDialogKeyDown,
+    settledSheet,
+    releaseSettledSheet,
   } = switcher;
   const hasValidSheetId = typeof sheetId === 'string' && sheetId.length > 0;
   const phase = hasValidSheetId ? getSheetPhase(sheetId) : 'hidden';
@@ -909,6 +899,9 @@ function SwitcherBottomSheetItem({
     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
@@ -1106,6 +1099,7 @@ function SwitcherBottomSheetItem({
       styles.dialog,
       isPresented && styles.dialogOpen,
       hasScrim && styles.scrim,
+      hasScrim && isEntrySettled && styles.scrimSettled,
       hasScrim && ownsScrim && isFlowClosing && styles.scrimClosing,
       !hasScrim && styles.dialogNonModalItem,
       !hasScrim && isTopSheet && styles.dialogNonModalItemTop,
@@ -1142,8 +1136,14 @@ function SwitcherBottomSheetItem({
       }
       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,
+      })}>
       <div
         {...stylex.props(
           styles.positioner,
@@ -1158,6 +1158,8 @@ function SwitcherBottomSheetItem({
           {...props}
           ref={ref}
           state={panelState}
+          isEntrySettled={isEntrySettled}
+          onEntrySettled={releaseSettledSheet}
           isOpenRequested={hasValidSheetId && activeSheet === sheetId}
           height={height}
           label={label}

package/src/BottomSheet/BottomSheetEdgeTint.tsx

@@ -4,35 +4,24 @@
 
 /**
  * @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 {colorVars} from '../theme/tokens.stylex';
 

package/src/BottomSheet/BottomSheetHostContext.ts

@@ -13,18 +13,14 @@
  * - /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 interface BottomSheetHostContextValue {