@astryxdesign/core 0.7.3 → 0.7.4-canary.3f6ea7d

package/dist/i18n/generated-locales/pseudo.generated.js

@@ -315,6 +315,7 @@ const runtimeCatalog = {
   '@astryx.chatToolCalls.status.complete': '⟦Çóɱþłéţé⟧',
   '@astryx.chatToolCalls.status.error': '⟦Ƒàíłéð⟧',
   '@astryx.chatToolCalls.groupLabel': '⟦{count} ţóół çàłłš⟧',
+  '@astryx.chatTriggerMenu.searching': '⟦Šéàřçĥíñĝ…⟧',
   '@astryx.chatTriggerMenu.suggestions': '⟦Šúĝĝéšţíóñš⟧',
   '@astryx.citation.label': '⟦Çíţàţíóñ {number}: {title}⟧',
   '@astryx.codeBlock.copied': '⟦Çóþíéð⟧',

package/locales/en.json

@@ -901,7 +901,7 @@
   },
   "@astryx.typeahead.loading": {
     "defaultMessage": "Loading",
-    "description": "Screen-reader-only name for a spinner shown inside a Typeahead dropdown while suggestions are being fetched. Present-progressive form."
+    "description": "Screen-reader-only name for the spinner a Typeahead, Tokenizer or directly used BaseTypeahead shows while suggestions are being fetched; also announced once through the shared announcement channel when each search starts. Present-progressive form."
   },
   "@astryx.typeahead.searchResults": {
     "defaultMessage": "Search results",
@@ -1169,7 +1169,7 @@
   },
   "@astryx.spinner.loading": {
     "defaultMessage": "Loading",
-    "description": "Screen-reader-only default name for a standalone Spinner's role=\"status\" element, used when the consumer supplies neither `aria-label` nor a visible string label. Present-progressive form. Kept separate from `button.loading` and `typeahead.loading` — translations may diverge."
+    "description": "Screen-reader-only default name for a standalone Spinner's role=\"status\" element, used when the consumer supplies neither `aria-label` nor a visible string label; also announced once when a busy input or selector starts loading, in place of its decorative Spinner. Present-progressive form. Kept separate from `button.loading` and `typeahead.loading` — translations may diverge."
   },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "Expand {label}",
@@ -1231,6 +1231,10 @@
     "defaultMessage": "{count} tool calls",
     "description": "Summary label shown in the group header when multiple tool calls are expanded. {count} is the number of calls."
   },
+  "@astryx.chatTriggerMenu.searching": {
+    "defaultMessage": "Searching…",
+    "description": "Shown, and announced politely to screen readers, while a chat composer's @-mention or slash-command menu waits for async search results. Present participle; trailing `…` is one character."
+  },
   "@astryx.chatTriggerMenu.suggestions": {
     "defaultMessage": "Suggestions",
     "description": "Screen-reader-only fallback label for the popover listbox opened by a trigger character (`@`, `/`) in the chat composer when the trigger provides no specific label."

package/locales/pseudo.json

@@ -923,6 +923,9 @@
   "@astryx.chatToolCalls.groupLabel": {
     "defaultMessage": "⟦{count} ţóół çàłłš⟧"
   },
+  "@astryx.chatTriggerMenu.searching": {
+    "defaultMessage": "⟦Šéàřçĥíñĝ…⟧"
+  },
   "@astryx.chatTriggerMenu.suggestions": {
     "defaultMessage": "⟦Šúĝĝéšţíóñš⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.3",
+  "version": "0.7.4-canary.3f6ea7d",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,6 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.4-canary.3f6ea7d",
+    "@astryxdesign/cli": "0.7.4-canary.3f6ea7d",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -802,9 +804,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/cli": "0.7.3"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/BottomSheet/BottomSheet.doc.mjs

@@ -95,7 +95,7 @@ export const docs = {
     derived: [{property: 'padding', expand: 'container'}],
   },
   description:
-    "A mobile touch sheet that rises from the bottom edge, with animated entrance and exit, a grab handle, optional drag-to-resize snap points, and purpose-controlled dismissal. Like Dialog, it is a padded container: content starts at the theme's bottom-sheet padding (--spacing-4 by default), and a lone Section child or bleed children such as Table and Divider align against it. A standalone sheet owns a native <dialog>; inside BottomSheetSwitcher it renders a panel in the switcher's shared dialog. In both modes, ref and shared DOM props target the visual panel <div>.",
+    "A mobile touch sheet that rises from the bottom edge, with animated entrance and exit, a grab handle, optional drag-to-resize snap points, and purpose-controlled dismissal. Like Dialog, it is a padded container: content starts at the theme's bottom-sheet padding (--spacing-4 by default), and a lone Section child or bleed children such as Table and Divider align against it. A sheet always owns a native <dialog>; inside BottomSheetSwitcher the switcher presents and closes that dialog as the flow moves between steps. In both modes, ref and shared DOM props target the visual panel <div>.",
   props: [
     {
       name: 'isOpen',
@@ -165,7 +165,7 @@ export const docs = {
       name: 'hasScrim',
       type: 'boolean',
       description:
-        "For a standalone BottomSheet, whether to render a scrim, the semi-transparent overlay that covers and blocks the background. true (default) uses showModal(): top layer, focus trap, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss when purpose='info', with the background inert. false uses show() with no scrim, leaving the page behind interactive and scrollable. For a multi-step flow, configure hasScrim on BottomSheetSwitcher instead; it owns one shared dialog across every child.",
+        "For a standalone BottomSheet, whether to render a scrim, the semi-transparent overlay that covers and blocks the background. true (default) uses showModal(): top layer, native focus containment, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss when purpose='info', with the background inert. false uses show() with no scrim, leaving the page behind interactive and scrollable. For a multi-step flow, configure hasScrim on BottomSheetSwitcher instead; it applies to every child's dialog.",
       default: 'true',
     },
   ],

package/src/BottomSheet/BottomSheet.spec.md

@@ -66,9 +66,7 @@ Consumer migration instructions belong in consumer docs and release notes.
   `architecture:container-padding`.
 - Standalone sheet presentation, including its optional native-dialog Scrim.
 - The native dialog every sheet renders, standalone or switcher-managed
-  (`component:BottomSheetSwitcher` DEC-1). Implementation gap: a
-  switcher-managed sheet renders a panel inside the switcher's one shared
-  dialog and owns no dialog of its own.
+  (`component:BottomSheetSwitcher` DEC-1).
 
 **Does not own / non-goals**
 
@@ -107,8 +105,7 @@ in `BottomSheet.doc.mjs`.
   without a Scrim.
 - A switcher-managed sheet renders the same panel anatomy in its own dialog while
   BottomSheetSwitcher coordinates that dialog's lifecycle and the flow's one Scrim
-  (`component:BottomSheetSwitcher` DEC-1). Implementation gap: the panel
-  renders inside the switcher's one shared dialog.
+  (`component:BottomSheetSwitcher` DEC-1).
 
 ### Transformation and precedence order
 

package/src/BottomSheet/BottomSheet.tsx

@@ -10,10 +10,22 @@
  *
  * 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 participates in the parent's shared dialog, transition state
- * machine, and dismissal registration. Both render the same BottomSheetPanel,
- * which owns sheet presentation, content padding, gestures, mobile-keyboard
- * accommodation, and motion completion.
+ * 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, and,
+ * in a switcher, handing one scrim between two dialogs and keeping focus in
+ * the active sheet when a retained dialog closes.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/BottomSheet/BottomSheetPanel.tsx
@@ -44,6 +56,7 @@ import type {DialogPurpose} from '../Dialog';
 import type {SpacingStep} from '../utils/types';
 import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {useDevWarning, useScrollLock} from '../hooks';
+import {mergeProps} from '../utils';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 import {focusForLastInput} from '../utils/focusReturn';
@@ -97,14 +110,31 @@ const styles = stylex.create({
         '@starting-style': 0,
       },
       transitionProperty: 'opacity, display',
-      transitionDuration: durationVars['--duration-medium'],
+      // A switcher hands its one scrim from a fading dialog to the next by
+      // pinning this duration for the swap; a standalone sheet never sets it.
+      transitionDuration: `var(--_sheet-scrim-duration, ${durationVars['--duration-medium']})`,
       transitionTimingFunction: easeVars['--ease-standard'],
       transitionBehavior: 'allow-discrete',
       '@media (prefers-reduced-motion: reduce)': {
-        transitionDuration: '0.01s',
+        // The switcher's scrim takeover pins the duration to 0s for one style
+        // flush; a literal here would override that pin and paint a frame
+        // with no scrim under reduced motion.
+        transitionDuration: 'var(--_sheet-scrim-duration, 0.01s)',
       },
     },
   },
+  // A non-modal switcher dialog does not enter the top layer, so DOM order
+  // would decide which sheet paints in front during a handoff. The switcher's
+  // flow wrapper is the isolated surface for that relationship; inside it the
+  // sheet dialogs use local values only, the interactive sheet's on top.
+  dialogNonModalItem: {
+    pointerEvents: 'none',
+    width: '100%',
+    height: '100%',
+  },
+  dialogNonModalItemTop: {
+    zIndex: 1,
+  },
   /**
    * The dim leaves with the sheet, on a curve that matches.
    *
@@ -235,6 +265,43 @@ function focusPanel(panel: HTMLElement | null, isModal: boolean): void {
   }
 }
 
+/**
+ * Present a switcher step's dialog modally with no focus to return to.
+ * showModal() records the element focused at that moment and close() moves
+ * focus back to it, in Chromium and WebKit even when focus is in another
+ * dialog by then. For a step that element is the control that advanced the
+ * flow (Continue, Back) or the flow's opener, and the dialog closes a fade
+ * later, while the user is in the next step: the return would pull focus
+ * off the active panel with no user action. Blurring first leaves nothing
+ * recorded, so the close moves nothing; the entering step then focuses its
+ * own panel, and the switcher returns focus to the opener itself when the
+ * flow ends. The blur happens in the same task as the present, so no frame
+ * paints without focus.
+ */
+function presentStepModally(dialog: HTMLDialogElement): void {
+  const focused = dialog.ownerDocument.activeElement;
+  if (focused instanceof HTMLElement && focused !== dialog.ownerDocument.body) {
+    focused.blur();
+  }
+  dialog.showModal();
+}
+
+/**
+ * Present a switcher dialog whose backdrop must start, and stay, clear: the
+ * opacity is set with the scrim transition pinned to 0s, the dialog is
+ * presented, and the pin is lifted only after a style flush has applied the
+ * clear backdrop, so no frame eases from a previous backdrop value.
+ */
+function presentWithClearScrim(dialog: HTMLDialogElement): void {
+  dialog.style.setProperty('--_sheet-scrim-duration', '0s');
+  dialog.style.setProperty('--_sheet-scrim-opacity', '0');
+  presentStepModally(dialog);
+  if (typeof getComputedStyle === 'function') {
+    void getComputedStyle(dialog, '::backdrop').opacity;
+  }
+  dialog.style.removeProperty('--_sheet-scrim-duration');
+}
+
 function StandaloneBottomSheet({
   ref,
   isOpen,
@@ -449,12 +516,21 @@ function SwitcherBottomSheetItem({
     onActiveSheetChange,
     getSheetPhase,
     getSheetAlignmentOffset,
+    hostSheet,
+    isScrimOwner,
+    isFlowClosing,
     registerSheetElement,
-    registerSheetLabel,
+    registerSheetDialog,
     registerSheetPurpose,
+    onBeforeSheetPresent,
+    isCoveredInTopLayer,
     onSheetEnterStart,
     onSheetTransitionComplete,
     onSheetScrimOpacityChange,
+    dialogProps,
+    onDialogCancel,
+    onDialogClick,
+    onDialogKeyDown,
   } = switcher;
   const hasValidSheetId = typeof sheetId === 'string' && sheetId.length > 0;
   const phase = hasValidSheetId ? getSheetPhase(sheetId) : 'hidden';
@@ -470,6 +546,10 @@ function SwitcherBottomSheetItem({
     phase === 'exiting';
   const isPresented = phase !== 'hidden';
   const isTopSheet = phase === 'active' || phase === 'entering';
+  const ownsScrim = hasValidSheetId && isScrimOwner(sheetId);
+  const isHostSheet = hasValidSheetId && hostSheet === sheetId;
+  const dialogRef = useRef<HTMLDialogElement | null>(null);
+  const dialogModeRef = useRef<'modal' | 'non-modal' | null>(null);
   const panelRef = useRef<HTMLDivElement | null>(null);
   const previousPhaseRef = useRef(phase);
   const previousPhase = previousPhaseRef.current;
@@ -493,6 +573,15 @@ function SwitcherBottomSheetItem({
     },
     [hasValidSheetId, registerSheetElement, sheetId],
   );
+  const handleDialogElementChange = useCallback(
+    (element: HTMLDialogElement | null) => {
+      dialogRef.current = element;
+      if (hasValidSheetId) {
+        registerSheetDialog(sheetId, element);
+      }
+    },
+    [hasValidSheetId, registerSheetDialog, sheetId],
+  );
   const handleMotionStart = useCallback(
     (motion: BottomSheetPanelMotion) => {
       if (motion === 'entering' && hasValidSheetId) {
@@ -522,17 +611,90 @@ function SwitcherBottomSheetItem({
     if (!hasValidSheetId) {
       return;
     }
-    registerSheetLabel(sheetId, label);
-    return () => registerSheetLabel(sheetId, null);
-  }, [hasValidSheetId, label, registerSheetLabel, sheetId]);
+    registerSheetPurpose(sheetId, purpose);
+    return () => registerSheetPurpose(sheetId, null);
+  }, [hasValidSheetId, purpose, registerSheetPurpose, sheetId]);
 
+  // Present this sheet's own dialog while the switcher keeps the sheet on
+  // screen, and close it once the sheet is hidden. A scrim flow presents
+  // modally: an entering dialog is shown above the retained one in the top
+  // layer, and the retained dialog closes only after its panel has faded. A
+  // modal dialog that is still open beneath a newer one -- the user went back
+  // to a sheet that was still fading -- re-presents to become topmost again:
+  // the document is blocked by the topmost modal dialog, so a lower one is
+  // inert whatever the switcher calls it.
+  //
+  // Every present blurs first, so no step dialog records an element to
+  // return focus to: a close while another sheet is active moves nothing,
+  // and when the flow ends the switcher focuses the flow's opener itself.
   useLayoutEffect(() => {
-    if (!hasValidSheetId) {
+    const dialog = dialogRef.current;
+    if (dialog == null || !hasValidSheetId) {
       return;
     }
-    registerSheetPurpose(sheetId, purpose);
-    return () => registerSheetPurpose(sheetId, null);
-  }, [hasValidSheetId, purpose, registerSheetPurpose, sheetId]);
+    if (!isPresented) {
+      if (dialog.open) {
+        dialog.close();
+      }
+      dialogModeRef.current = null;
+      return;
+    }
+    const nextMode = hasScrim ? 'modal' : 'non-modal';
+    if (dialog.open && dialogModeRef.current !== nextMode) {
+      dialog.close();
+    }
+    if (
+      dialog.open &&
+      hasScrim &&
+      isInteractive &&
+      isCoveredInTopLayer(sheetId)
+    ) {
+      dialog.close();
+    }
+    if (!dialog.open) {
+      if (hasScrim) {
+        onBeforeSheetPresent(sheetId);
+        if (ownsScrim) {
+          presentStepModally(dialog);
+        } else {
+          // Entering above a retained dialog whose backdrop already dims the
+          // page: present with a clear backdrop so the page is not dimmed
+          // twice and the previous panel stays undimmed beneath this one.
+          // Pinned to 0s across the present: a dialog re-presented from the
+          // retained position (the user went back while it was fading)
+          // closed with its backdrop at 1, and would otherwise ease it down
+          // over the scrim duration on top of the new owner's backdrop.
+          presentWithClearScrim(dialog);
+        }
+      } else {
+        dialog.show();
+      }
+    }
+    dialogModeRef.current = nextMode;
+  }, [
+    hasScrim,
+    hasValidSheetId,
+    isCoveredInTopLayer,
+    isInteractive,
+    isPresented,
+    onBeforeSheetPresent,
+    ownsScrim,
+    sheetId,
+  ]);
+
+  // A sheet removed while presented -- a consumer unmounts the closing sheet
+  // in the same update that closes the flow -- takes its dialog out of the
+  // top layer with it, but the element would keep its `open` state. Close it
+  // while it is still attached so the native lifecycle ends cleanly.
+  useLayoutEffect(
+    () => () => {
+      const dialog = dialogRef.current;
+      if (dialog?.open) {
+        dialog.close();
+      }
+    },
+    [],
+  );
 
   useEffect(() => {
     if (isInteractive) {
@@ -554,45 +716,96 @@ function SwitcherBottomSheetItem({
     isInteractive && !label,
   );
 
+  // The switcher's dialog surface applies to every sheet dialog, except the
+  // attributes that identify one element: those render on the host dialog
+  // only, the one the switcher's ref resolves to. Of the attributes set
+  // explicitly below, only `role` has a consumer value to keep: a required
+  // step forces `alertdialog`, otherwise the switcher's `role` stands, as on
+  // a shared dialog. `aria-label`/`aria-labelledby` keep consumer precedence
+  // above; `aria-modal`, `aria-hidden`, and `inert` are the host's own state.
+  const {
+    className: switcherClassName,
+    style: switcherStyle,
+    xstyle: switcherXstyle,
+    'aria-label': switcherAriaLabel,
+    'aria-labelledby': switcherAriaLabelledBy,
+    id: switcherId,
+    '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,
+  );
+
   return (
-    <div
-      {...stylex.props(
-        styles.positioner,
-        !isPresented && styles.positionerHidden,
-        isTopSheet && styles.positionerTop,
-      )}
-      hidden={!isPresented}
+    <dialog
+      {...switcherDialogProps}
+      {...dialogPresentationProps}
+      id={isHostSheet ? switcherId : undefined}
+      data-testid={isHostSheet ? switcherTestId : undefined}
+      ref={handleDialogElementChange}
+      aria-label={
+        switcherAriaLabel ??
+        (switcherAriaLabelledBy == null ? label : undefined)
+      }
+      aria-labelledby={switcherAriaLabelledBy}
+      aria-modal={hasScrim && isInteractive ? 'true' : undefined}
       aria-hidden={isInactive ? 'true' : undefined}
-      inert={isInactive ? true : undefined}>
-      <BottomSheetPanel
-        {...props}
-        ref={ref}
-        state={panelState}
-        height={height}
-        label={label}
-        snapPoints={snapPoints}
-        isSwipeDismissAllowed={purpose === 'info'}
-        isPageScrollLocked={hasScrim}
-        xstyle={xstyle}
-        onDismiss={dismissOnSwipe}
-        onScrimOpacity={handleScrimOpacity}
-        onElementChange={handlePanelElementChange}
-        onMotionStart={handleMotionStart}
-        onMotionComplete={handleMotionComplete}>
-        {/* A switcher item consumes its parent controller. Its content starts a
-            fresh ownership scope so a nested BottomSheet is standalone unless
-            it establishes a nested BottomSheetSwitcher of its own. */}
-        <BottomSheetSwitcherContext value={null}>
-          {children}
-        </BottomSheetSwitcherContext>
-      </BottomSheetPanel>
-    </div>
+      inert={isInactive ? true : undefined}
+      role={purpose === 'required' ? 'alertdialog' : switcherDialogProps.role}
+      onCancel={onDialogCancel}
+      onClick={onDialogClick}
+      onKeyDown={onDialogKeyDown}>
+      <div
+        {...stylex.props(
+          styles.positioner,
+          !isPresented && styles.positionerHidden,
+          isTopSheet && styles.positionerTop,
+        )}
+        hidden={!isPresented}
+        aria-hidden={isInactive ? 'true' : undefined}
+        inert={isInactive ? true : undefined}>
+        <BottomSheetPanel
+          {...props}
+          ref={ref}
+          state={panelState}
+          height={height}
+          label={label}
+          snapPoints={snapPoints}
+          isSwipeDismissAllowed={purpose === 'info'}
+          isPageScrollLocked={hasScrim}
+          xstyle={xstyle}
+          onDismiss={dismissOnSwipe}
+          onScrimOpacity={handleScrimOpacity}
+          onElementChange={handlePanelElementChange}
+          onMotionStart={handleMotionStart}
+          onMotionComplete={handleMotionComplete}>
+          {/* A switcher item consumes its parent controller. Its content starts a
+              fresh ownership scope so a nested BottomSheet is standalone unless
+              it establishes a nested BottomSheetSwitcher of its own. */}
+          <BottomSheetSwitcherContext value={null}>
+            <LayerDepthProvider>{children}</LayerDepthProvider>
+          </BottomSheetSwitcherContext>
+        </BottomSheetPanel>
+      </div>
+      {isPresented && <BottomSheetEdgeTint />}
+    </dialog>
   );
 }
 
 /**
- * A mobile touch sheet that either owns a native dialog or participates in a
- * BottomSheetSwitcher shared dialog when given a sheetId inside that context.
+ * A mobile touch sheet that owns a native dialog. Given a sheetId inside a
+ * BottomSheetSwitcher, that switcher coordinates the dialog's lifecycle.
  */
 export function BottomSheet(props: BottomSheetProps) {
   const switcher = use(BottomSheetSwitcherContext);

package/src/BottomSheet/BottomSheetEdgeTint.test.tsx

@@ -127,8 +127,10 @@ describe('BottomSheetEdgeTint', () => {
     expect(tints()).toHaveLength(0);
   });
 
-  // The switcher owns one shared dialog for the whole flow, so the tint
-  // belongs to that dialog and must not be minted per child sheet.
+  // Each switcher step owns a dialog and tints it while presented: one tint
+  // at rest, one per open dialog through a handoff (the retained dialog's
+  // sits beneath the entering dialog), none for a sheet that is not
+  // presented.
   it('gives a non-modal switcher flow exactly one tint', () => {
     render(
       <BottomSheetSwitcher

package/src/BottomSheet/BottomSheetSwitcher.doc.mjs

@@ -3,10 +3,10 @@
 
 const anatomy = [
   {
-    name: 'Shared dialog',
+    name: 'Sheet dialogs',
     required: true,
     description:
-      'One native dialog that owns modality, focus, dismissal, and lifecycle for the complete flow.',
+      "One native dialog per child sheet, presented and closed by the switcher; the dialog hosting the active sheet carries the flow's ref, id, modality, and dismissal.",
   },
   {
     name: 'Sheet panels',
@@ -18,7 +18,7 @@ const anatomy = [
     name: 'Scrim',
     required: false,
     description:
-      'Native dialog backdrop shown by the default scrim-backed modal presentation.',
+      'Native dialog backdrop shown by the default scrim-backed modal presentation; one sheet dialog paints it at a time, so a handoff never dims the page twice.',
   },
 ];
 
@@ -142,18 +142,19 @@ export const docs = {
     },
   },
   description:
-    'Coordinates multiple BottomSheets as a mutually exclusive flow. One activeSheet ID selects the only interactive sheet; during a handoff, the new sheet enters above the inert previous sheet. If the new sheet is shorter, the previous sheet simultaneously moves down until their top edges align, then fades after both transforms complete. The switcher owns one shared native <dialog>: modal flows call showModal() once for one top-layer boundary and one ::backdrop across the whole flow, while no-scrim flows use a non-modal show() shell. Its ref and shared DOM props target that dialog.',
+    'Coordinates multiple BottomSheets as a mutually exclusive flow. One activeSheet ID selects the only interactive sheet; during a handoff, the new sheet enters above the inert previous sheet. If the new sheet is shorter, the previous sheet simultaneously moves down until their top edges align, then fades after both transforms complete. Each child sheet renders its own native <dialog>, exactly like a standalone sheet: modal flows present each sheet with showModal(), no-scrim flows with show(). The browser supplies modality: the page is inert and focus stays in the top-layer dialog, so both hold across a handoff; the switcher holds the shared body scroll lock once for the whole modal flow. The switcher coordinates the rest: one scrim paints at a time, focus returns to the element that opened the flow, its ref, id, and data-testid resolve to the dialog hosting the active sheet, and its other dialog props and handlers apply to every sheet dialog.',
   props: [
     {
       name: 'ref',
       type: 'Ref<HTMLDialogElement>',
-      description: 'Ref forwarded to the one shared native dialog.',
+      description:
+        "Ref resolved to the native dialog hosting the flow: the active sheet's dialog, which changes to the next sheet's on a handoff; the exiting sheet's through its exit; and, while the flow is closed, the dialog that hosted it last (or the first mounted sheet's). It is never null while a sheet is mounted, from the first commit on. id and data-testid render on this 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. Other dialog props apply to every sheet dialog.",
     },
     {
       name: 'onCancel',
       type: '(event: SyntheticEvent<HTMLDialogElement>) => void',
       description:
-        'Called before the switcher handles a native dialog cancel request. Calling preventDefault() keeps the controlled flow open.',
+        "Called before the switcher handles a native cancel request (Escape or the platform close). Attached to every sheet dialog; the browser raises cancel on the dialog it is presenting, the active sheet's. Calling preventDefault() keeps the controlled flow open.",
     },
     {
       name: 'activeSheet',
@@ -173,7 +174,7 @@ export const docs = {
       name: 'hasScrim',
       type: 'boolean',
       description:
-        "Whether the shared dialog is modal. true uses showModal() once for one native ::backdrop, focus trap, scroll lock, and click-to-dismiss when the active BottomSheet has purpose='info'. false uses show() with no backdrop and leaves the page interactive; avoid transformed, contained, or clipping ancestors because the non-modal dialog remains in its containing context.",
+        "Whether the sheet dialogs are modal. true presents each sheet with showModal() for a native ::backdrop, native focus containment, one body scroll lock held for the whole flow, and click-to-dismiss when the active BottomSheet has purpose='info'; only one backdrop paints at a time. false uses show() with no backdrop and leaves the page interactive; avoid transformed, contained, or clipping ancestors because a non-modal dialog remains in its containing context.",
       default: 'true',
     },
     {
@@ -186,7 +187,7 @@ export const docs = {
   usage: {
     anatomy,
     description:
-      "Coordinates a multi-step bottom-sheet flow in one shared dialog; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
+      "Coordinates a multi-step bottom-sheet flow, one native dialog per sheet; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
     bestPractices: [
       {
         guidance: true,
@@ -243,11 +244,11 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
-    'controller with one shared native dialog for mutually exclusive multi-step BottomSheets',
+    'controller for mutually exclusive multi-step BottomSheets, one native dialog per sheet',
   usage: {
     anatomy,
     description:
-      "Coordinates a multi-step bottom-sheet flow in one shared dialog; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
+      "Coordinates a multi-step bottom-sheet flow, one native dialog per sheet; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
     bestPractices: [
       {
         guidance: true,