An open source design system that's fully customizable and agent ready
TypeScript
chore(BottomSheet): source comments explain only non-obvious reasons (1 of 2) (#9523)
Cindy Zhang3684425d7191
diff --git a/.changeset/bottomsheet-comment-cleanup.md b/.changeset/bottomsheet-comment-cleanup.mdnew file mode 100644index 0000000000..6cea1a82a2--- /dev/null+++ b/.changeset/bottomsheet-comment-cleanup.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[docs] Source comments in BottomSheet and BottomSheetSwitcher are shorter and explain only non-obvious reasons. Nothing a consumer imports or renders changes.++@cixzhangdiff --git a/packages/core/src/BottomSheet/BottomSheet.tsx b/packages/core/src/BottomSheet/BottomSheet.tsxindex ee2de4b787..ef271dc140 100644--- a/packages/core/src/BottomSheet/BottomSheet.tsx+++ b/packages/core/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,@@ -172,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%',@@ -219,21 +189,18 @@ const styles = stylex.create({},},},- // A sheet present on page load dims at once (spec:AST-013 FR13): the- // collapse reduced motion uses, so the transition still ends.+ // 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': {@@ -433,18 +400,16 @@ function StandaloneBottomSheet({// state stays the consumer's; nothing here writes it.const host = use(BottomSheetHostContext);const isHostOpen = host?.isOpen ?? true;- // A sheet open on the server renders closed until hydration, and opens in- // the render after it, 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 (FR17).+ // 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 was present on page load, so it opens settled,- // with no rise or fade-in; its later opens and closes animate as usual- // (spec:AST-013 FR13). It latches on its own request, not its host's state:- // a host sheet hydrating reads as closed to the sheets inside it.- // The latch is released when the settled entry's transition ends, so a- // drag's settle later in the same open glides as usual.+ // 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,@@ -473,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) {@@ -631,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,@@ -707,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;@@ -945,7 +899,7 @@ function SwitcherBottomSheetItem({phase === 'fading' ||phase === 'exiting';const isPresented = phase !== 'hidden';- // The step open on the server opens settled (spec:AST-013 FR13).+ // The step open on the server opens settled.const isEntrySettled =hasValidSheetId && isPresented && settledSheet === sheetId;const isTopSheet = phase === 'active' || phase === 'entering';diff --git a/packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx b/packages/core/src/BottomSheet/BottomSheetEdgeTint.tsxindex 1dfa5015d6..c6a1536706 100644--- a/packages/core/src/BottomSheet/BottomSheetEdgeTint.tsx+++ b/packages/core/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';diff --git a/packages/core/src/BottomSheet/BottomSheetHostContext.ts b/packages/core/src/BottomSheet/BottomSheetHostContext.tsindex 150ce043ec..2140407a58 100644--- a/packages/core/src/BottomSheet/BottomSheetHostContext.ts+++ b/packages/core/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 {diff --git a/packages/core/src/BottomSheet/BottomSheetPanel.tsx b/packages/core/src/BottomSheet/BottomSheetPanel.tsxindex 1a3113917b..1c58747324 100644--- a/packages/core/src/BottomSheet/BottomSheetPanel.tsx+++ b/packages/core/src/BottomSheet/BottomSheetPanel.tsx@@ -6,13 +6,9 @@* @file BottomSheetPanel.tsx* @input Uses React, StyleX, theme tokens, text/provider boundaries, container padding, sheet gestures, shared scroll behavior, and the host label* @output Internal BottomSheetPanel with a keyboard-reachable scrolling body and motion-state types- * @position Shared presentation layer for standalone and switcher BottomSheets- *- * This component owns everything intrinsic to a sheet surface: height budgets,- * drag and snap gestures, the handle and scrolling body, the content box's- * container padding, motion styles, and transition completion. It owns the- * body's keyboard access; dialog focus entry/return, inert state, and switcher- * registration belong to the host.+ * @position Shared presentation layer for standalone and switcher+ * BottomSheets. It owns the sheet surface and the body's keyboard access.+ * The host owns dialog focus, inert state and switcher registration.** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/BottomSheet/BottomSheet.tsx@@ -96,12 +92,10 @@ const TRANSITION_BACKSTOP_BUFFER_MS = 50;// padding already provides.const HANDLE_BAR_HEIGHT = spacingVars['--spacing-6'];-// Measure the same viewport the height budgets are written against. Those are-// `dvh`, which the virtual keyboard does not shrink, so reading-// `visualViewport` here would make the two disagree by exactly the keyboard's-// height: every detent would move while the sheet it measures did not. A-// keyboard is `useMobileKeyboard`'s business — it holds the sheet still and-// scrolls the body — and it does not redefine the sheet's detents.+// Measure the viewport that the height budgets use. They are `dvh`, which+// the virtual keyboard does not shrink, so `visualViewport` would differ by+// the keyboard's height. `useMobileKeyboard` handles the keyboard and does+// not change the detents.function layoutViewportHeight(): number {return typeof window === 'undefined' ? 0 : window.innerHeight;}@@ -125,9 +119,8 @@ function snapPointsKeyFor(}/**- * The queries `design:reduced-motion` names: reduced motion with a coarse- * primary pointer cross-fades (DR2); reduced motion otherwise changes at once- * (DR3). The cross-fade's ceiling is the record's 200 ms.+ * The reduced-motion queries. With a coarse primary pointer the sheet+ * cross-fades, else it changes at once. The cross-fade lasts at most 200 ms.*/const REDUCED_MOTION_COARSE ='@media (prefers-reduced-motion: reduce) and (pointer: coarse)';@@ -148,13 +141,10 @@ const styles = stylex.create({width: '100%',maxWidth: 640,backgroundColor: colorVars['--color-background-surface'],- // Hairline on the three edges that face the scrim. The surface fill alone- // separates sheet from scrim in light mode, but not in dark: there the two- // sit within a few RGB steps of each other and the drop shadow is black on- // near-black, so the sheet's left and right edges disappear. Same- // treatment MobileNav gives its scrim-facing edge. The block-end edge is- // deliberately left bare; it sits below the viewport, under the overscroll- // padding.+ // A hairline on the three edges that face the scrim. In dark mode the+ // surface and the scrim are only a few RGB steps apart, and the shadow is+ // black on near-black, so the side edges disappear. The block-end edge+ // stays bare, below the viewport.borderBlockStartWidth: borderVars['--border-width'],borderBlockStartStyle: 'solid',borderBlockStartColor: colorVars['--color-border'],@@ -171,10 +161,9 @@ const styles = stylex.create({overflow: 'hidden',paddingBlockEnd: `calc(env(safe-area-inset-bottom, 0px) + ${OVERSCROLL_PADDING}px)`,marginBlockEnd: `${-OVERSCROLL_PADDING}px`,- // Under reduced motion no transform runs (design:reduced-motion DR1). On- // a coarse primary pointer the entrance is an opacity-only cross-fade of- // at most 200 ms (DR2): the sheet appears at its resting place and fades- // in; a fine pointer gets the change at once (DR3), the 0.01s collapse.+ // Under reduced motion no transform runs. On a coarse primary pointer the+ // entrance is an opacity cross-fade of at most 200 ms. A fine pointer gets+ // the change at once (the 0.01s collapse).transform: {default: 'translateY(0)','@starting-style': {@@ -206,26 +195,17 @@ const styles = stylex.create({transitionDuration: '0.01s',},/**- * The exit is its own motion, not the entrance played backwards.- *- * `--ease-standard` is `cubic-bezier(0.24, 1, 0.4, 1)`, a decelerate curve:- * it spends its speed immediately and coasts. That is right for an entrance,- * where the sheet arrives fast and settles, and wrong for an exit. Measured- * on device, it put the sheet half off-screen in 59ms of a 410ms close and- * 90% off in 163ms -- the travel is over before the eye has followed it, and- * the rest of the duration moves pixels already below the fold.- *- * An exit accelerates instead (`--ease-exit`): away from rest, gathering- * speed, quickest as it leaves the screen. The curve is deliberately gentle- * rather than a hard `ease-in` -- it is moving within ~50ms, so the close- * reads as one departure rather than a hesitation and a snap. The duration- * is the entrance's own band, so only the curve differs between the two- * directions; a shorter band leaves too little visible travel once a theme- * scales the motion scale down (neutral's medium is 300ms against 410ms).+ * The exit is its own motion, not the entrance played backwards. The+ * decelerate `--ease-standard` put the sheet half off-screen in 59ms of a+ * 410ms close, so the travel ended before the eye followed it. An exit+ * accelerates instead (`--ease-exit`). The curve is gentle, so the sheet+ * moves within ~50ms and the close reads as one departure. The duration is+ * the entrance's band, because a shorter band leaves too little travel when+ * a theme scales motion down.*/sheetClosing: {- // Under reduced motion the exit does not travel (DR1); on a coarse- // pointer it fades out where it is (DR2), at once on a fine one (DR3).+ // Under reduced motion the exit does not travel. On a coarse pointer it+ // fades out where it is, and on a fine one it ends at once.transform: {default: 'translateY(100%)','@media (prefers-reduced-motion: reduce)': 'translateY(0)',@@ -234,19 +214,17 @@ const styles = stylex.create({default: null,[REDUCED_MOTION_COARSE]: 0,},- // A pointer presentation closes on the theme's exit curve (spec:AST-090- // FR12). A touch presentation keeps its own curve, which the exit tokens- // do not change.+ // A pointer presentation closes on the theme's exit curve. A touch+ // presentation keeps its own curve.transitionTimingFunction: {default: easeVars['--ease-exit'],'@media (pointer: coarse)': 'cubic-bezier(0.3, 0, 0.6, 0.6)',},},/**- * An exit that cross-fades on a pointer the media query does not cover: a- * touch swipe dismissal under reduced motion fades out in place on every- * pointer (design:reduced-motion DR2, the touch drag's release). The same- * opacity and ceiling the coarse-pointer rule uses.+ * An exit that cross-fades on a pointer that the media query does not+ * cover: a touch swipe dismissal under reduced motion fades out in place on+ * every pointer. It uses the opacity and ceiling of the coarse-pointer rule.*/sheetClosingCrossFade: {transform: 'translateY(0)',@@ -283,8 +261,7 @@ const styles = stylex.create({default: 'grab',':is(:disabled,[aria-disabled="true"])': 'default',},- // The pill, drawn on the grab bar itself: decoration with no role of its- // own (architecture:component-style-authoring INV7).+ // The pill is drawn on the grab bar itself, as decoration with no role.'::before': {content: '""',width: sizeVars['--size-element-lg'],@@ -365,7 +342,7 @@ interface BottomSheetPanelProps extends BaseProps<HTMLDivElement> {state: BottomSheetPanelState;/*** Whether the sheet was open on page load: it then opens where it rests,- * with no entry motion (spec:AST-013 FR13).+ * with no entry motion.*/isEntrySettled?: boolean;/**@@ -401,10 +378,9 @@ interface BottomSheetPanelProps extends BaseProps<HTMLDivElement> {}/**- * A hidden sheet observes nothing (component:Popover PR1, FR5): the scroll- * area's measuring ref attaches as the sheet presents and detaches once it is- * hidden again, so a closed sheet that stays mounted holds no resize,- * mutation or viewport observers.+ * A hidden sheet observes nothing. The scroll area's measuring ref attaches+ * as the sheet presents and detaches when it is hidden, so a closed sheet+ * that stays mounted holds no resize, mutation or viewport observers.*/function whilePresented<P extends {ref?: unknown}>(isPresented: boolean,@@ -578,8 +554,7 @@ export function BottomSheetPanel({const isClosing = state.kind === 'exiting';const isFading = isRetained && state.motion === 'fading';// Under reduced motion a retained sheet does not align down to a shorter- // entering sheet: that is travel (design:reduced-motion DR1). It fades where- // it is.+ // entering sheet, because that is travel. It fades where it is.const isReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');const alignmentOffset =isRetained && !isReducedMotion ? state.alignmentOffset : 0;@@ -690,10 +665,9 @@ export function BottomSheetPanel({useImperativeHandle(ref, () => elementRef.current as HTMLDivElement, []);const motion = motionForState(state);- // design:reduced-motion DR2: the cross-fade applies on a coarse pointer, and- // to a transition the release of a touch drag started — a finger's swipe- // dismissal fades out in place on every pointer. A mouse or pen drag is not- // a touch drag; DR3 covers it and the rest.+ // The cross-fade applies on a coarse pointer, and to a transition that a+ // touch drag's release started: a finger's swipe dismissal fades in place on+ // every pointer. A mouse or pen drag is not a touch drag.const isCoarseCrossFade = useMediaQuery(REDUCED_MOTION_COARSE_QUERY);const isCrossFade =isCoarseCrossFade || (isReducedMotion && isDismissedByTouchDrag);@@ -707,12 +681,11 @@ export function BottomSheetPanel({pendingMotionCompleteRef.current = motion;return;}- // What ends a motion: the fade is opacity; the entrance, alignment and- // exit are transforms — except that under the reduced-motion cross-fade- // (DR2) an exit fades out where it is and its dialog may close only once- // the fade has ended, so it waits on opacity. The entrance keeps waiting- // on its (instant) transform, so the retained sheet's fade starts at once- // and the two fades cross; the alignment is instant.+ // What ends a motion: the fade is opacity, and the entrance, alignment and+ // exit are transforms. Under the reduced-motion cross-fade an exit fades+ // where it is, and its dialog closes only after the fade, so it waits on+ // opacity. The entrance still waits on its instant transform, so the+ // retained sheet's fade starts at once and the two fades cross.const crossFadeMotion = isCrossFade && motion === 'exiting';return waitForTransition(elementRef.current,@@ -821,24 +794,18 @@ export function BottomSheetPanel({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;diff --git a/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx b/packages/core/src/BottomSheet/BottomSheetSwitcher.tsxindex 12f76cbc71..778894e61a 100644--- a/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx+++ b/packages/core/src/BottomSheet/BottomSheetSwitcher.tsx@@ -4,61 +4,12 @@/*** @file BottomSheetSwitcher.tsx- * @input Uses React context, StyleX, shared layer dismissal, the modal outlet registry, the private bottom-sheet stack, BottomSheetSwitcherContext, BottomSheetHostContext+ * @input React context, StyleX, shared layer dismissal, the modal outlet+ * registry, the private bottom-sheet stack, BottomSheetSwitcherContext,+ * BottomSheetHostContext* @output Exports BottomSheetSwitcher and BottomSheetSwitcherProps- * @position Core switcher for mutually exclusive BottomSheet flows- *- * The switcher turns a set of declaratively nested BottomSheets into a- * controlled single-selection group: `activeSheet` names the one interactive- * child, or is null when the flow is closed. During a handoff the new sheet- * enters above the previous sheet. If it is shorter, the previous sheet moves- * down at the same time until their top edges align; otherwise it stays- * stationary. The previous sheet fades only after both motions complete.- *- * Every child sheet owns a native `<dialog>`: a scrim flow presents each- * sheet with showModal(), as a standalone modal sheet does, and a no-scrim- * flow with show() inside the flow wrapper (a standalone no-scrim sheet is a- * manual popover in the top layer instead; this deprecated path keeps its- * released hosting). For a modal flow the browser then does what a modal- * dialog does -- the page is inert, focus stays in the top-layer dialog,- * Escape and the platform close arrive as `cancel`. The switcher is the coordinator: it decides which- * sheet dialog is presented, retained, or hidden, keeps one scrim painted- * across a handoff (the retained sheet's backdrop until it fades, then the- * new sheet's, swapped without a fade), holds the flow's one page scroll- * lock (the shared useScrollLock, as Dialog uses, acquired once while the- * flow is presented and released after its exit, never per step) and the- * one layer-dismissal registration, and returns focus to the flow's opener- * when the flow ends, which no single dialog can know.- *- * The switcher's one element is a flow wrapper. In a scrim flow it has no box- * (`display: contents`): the dialogs sit in the top layer. In a no-scrim flow- * it is the isolated surface that orders the sheet dialogs locally, the way- * the shared shell once did, so no sheet needs a page-level value of its own.- *- * Its `ref` resolves to the host dialog: the one presenting the active sheet,- * the exiting sheet's through its exit, and the last host's (or the first- * mounted sheet's) while the flow is closed, so the ref is never null while a- * sheet is mounted. `id` and `data-testid` render on the host dialog only:- * a flow that mounts open carries them on the active sheet's dialog in server- * markup too; a flow that mounts closed carries them from the first commit's- * synchronous re-render on, and its server markup carries them on no element.- * Every other dialog prop and handler, `onCancel` included, applies to every- * sheet dialog; the browser raises `cancel` on the dialog it presents.- *- * A scrim flow is one level of the private bottom-sheet stack- * (bottomSheetStack.ts) while it is visible: it stacks over, or under, other- * modal sheets in open order, recedes as a whole when covered, and switching- * its step in place never changes its position. The level is realized by the- * active step's dialog; on a handoff the registry is told the dialog changed- * so the sheets above the flow stay above its new dialog. A flow stacked- * above another sheet keeps every step backdrop clear; a flow beneath owns- * the stack's one scrim and hands it between its own steps as it always did.- * A switcher step is never paired in a replace: the flow replaces its own- * steps. A flow rendered in another sheet's content leaves and returns with- * that sheet, like a standalone sheet, without its state being written. A- * modal flow's host dialog is a toast outlet like a standalone scrim sheet's- * (Layer/modalOutlet.ts), following the handoff. The switcher is deprecated- * in favour of standalone step sheets.+ * @position Core switcher for mutually exclusive BottomSheet flows. It is+ * deprecated in favor of standalone step sheets.** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/BottomSheet/BottomSheet.tsx@@ -74,6 +25,24 @@* - /packages/cli/assets/templates/blocks/components/BottomSheet/BottomSheetSwitcherShowcase.tsx*/+// `activeSheet` names the one interactive child, or null when the flow is+// closed. On a handoff the new sheet enters above the previous one. A taller+// previous sheet moves down until the top edges align. The previous sheet+// fades after both motions end.+//+// Each child sheet owns a native `<dialog>`. A scrim flow uses showModal(),+// and a no-scrim flow uses show() inside the flow wrapper. The switcher+// decides which dialog is presented, retained or hidden. It keeps one scrim+// across a handoff, holds the flow's one scroll lock and one dismissal+// registration, and returns focus to the flow's opener when the flow ends.+//+// The ref resolves to the host dialog: the active sheet's, the exiting+// sheet's during its exit, else the last host's. `id` and `data-testid`+// render on the host dialog only. Other dialog props apply to every sheet+// dialog. A scrim flow is one level of the sheet stack (bottomSheetStack.ts),+// and a step switch never changes that level. A modal flow's host dialog is+// a toast outlet (Layer/modalOutlet.ts).+import {use,useCallback,@@ -132,13 +101,11 @@ const styles = stylex.create({display: 'contents',},// show() leaves a no-scrim flow in the normal rendering tree, where DOM- // order would decide which sheet dialog paints in front during a handoff.- // The wrapper is then the flow's isolated surface: the sheet dialogs order- // themselves locally inside it (`spec:AST-027` FR2), and the wrapper itself- // keeps the one overlay value the shared shell carried before, which- // `spec:AST-027` records as the non-modal migration gap. It passes pointer- // input through to the live page; each sheet panel opts back in. Consumers- // of this non-modal mode must still avoid transformed or clipping ancestors.+ // order would decide which dialog paints in front. So the wrapper is the+ // flow's isolated surface: the dialogs order themselves inside it, and the+ // wrapper keeps the one overlay value of the old shared shell. It+ // passes pointer input through, and each panel opts back in. Consumers of+ // this mode must avoid transformed or clipping ancestors.flowNonModal: {display: 'block',position: 'fixed',@@ -254,7 +221,7 @@ function takeOverScrim(dialog: HTMLDialogElement, opacity: number): void {* same replace handoff (see BottomSheet, "Replacing a sheet"). Keeps working until a future minor* release removes it: on its own as released (plus three fixes: a toast raised* from a step now renders above the flow and can be pressed, reduced motion- * follows design:reduced-motion, and a flow whose active sheet is set on the+ * follows the reduced-motion design rules, and a flow whose active sheet is set on the* server renders closed until hydration, then opens that sheet settled), as* one stack level when stacked.*/@@ -315,7 +282,7 @@ export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {* sheets' own motion. The switcher keeps working until a future* minor release removes it: on its own as released (plus three fixes: a toast* raised from a step now renders above the flow and can be pressed, reduced- * motion follows design:reduced-motion, and a flow whose active sheet is set+ * motion follows the reduced-motion design rules, and a flow whose active sheet is set* on the server renders closed until hydration, then opens that sheet* settled), and as one level of the stack when stacked with other sheets.*/@@ -341,15 +308,14 @@ export function BottomSheetSwitcher({const host = use(BottomSheetHostContext);const isHostOpen = host?.isOpen ?? true;// A flow with an active sheet on the server reads as closed until- // hydration, and opens in the render after it, 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 (`component:BottomSheet` FR17).+ // hydration. It opens in the next render, the first one that can enter its+ // native host. A <dialog> painted open with aria-modal before it is modal+ // claims a state it does not have.const isHydrating = useIsHydrating();const activeSheet = isHostOpen && !isHydrating ? activeSheetProp : null;- // The step active on the server was present on page load, so it opens- // settled, with no entry motion; the first change of step animates as- // usual (spec:AST-013 FR13). It latches on the flow's own request: a host- // sheet hydrating reads as closed to a flow inside it.+ // The step active on the server opens settled, with no entry motion. The+ // first change of step animates (AST-013 FR13). It latches on the flow's+ // own request, because a hydrating host sheet reads as closed.const [settledSheet, releaseSettledSheet] = useSettledOpen(activeSheetProp,activeSheet,@@ -568,14 +534,11 @@ export function BottomSheetSwitcher({[],);- // The flow's host dialog is an outlet for app-global surfaces (toasts)- // while the flow is a modal one, as a standalone scrim sheet's dialog is- // (`component:BottomSheet` FR13): every open scrim sheet supplies one, the- // latest among sheets follows the stack, and a Dialog supplied later stays- // above. The host changes on a handoff, so the supply follows `hostSheet`;- // the retained step's dialog, inert and fading, is never the outlet. A- // closing flow stops supplying at once, as a closing sheet does. Passive:- // it runs after the layout effects that present the step dialogs.+ // While the flow is modal, its host dialog is an outlet for app-global+ // surfaces (toasts), as a standalone scrim sheet's is. The supply follows+ // `hostSheet` across a handoff, and the fading retained dialog is never the+ // outlet. A closing flow stops supplying at once. Passive: it runs after the+ // layout effects that present the step dialogs.useModalOutlet(hostDialogRef,isModal && isFlowOpen,diff --git a/packages/core/src/BottomSheet/bottomSheetEscape.ts b/packages/core/src/BottomSheet/bottomSheetEscape.tsindex 61edf358f5..1b0f1f0728 100644--- a/packages/core/src/BottomSheet/bottomSheetEscape.ts+++ b/packages/core/src/BottomSheet/bottomSheetEscape.ts@@ -9,9 +9,9 @@* request) may dismiss the standalone sheet below it* @position Internal to Core, not exported from the package: Popover's sheet* presentation passes `hasEscapeDismiss` through it, so its sheet can- * light-dismiss (scrim tap, swipe down) while Escape stays off- * (component:Popover DEC-8). A standalone BottomSheet reads the default- * (true), so its `purpose` rule is unchanged.+ * light-dismiss (scrim tap, swipe down) while Escape stays off. A+ * standalone BottomSheet reads the default (true), so its `purpose` rule+ * is unchanged.*/import {createContext} from 'react';diff --git a/packages/core/src/BottomSheet/bottomSheetStack.ts b/packages/core/src/BottomSheet/bottomSheetStack.tsindex ca4b06f177..486716d073 100644--- a/packages/core/src/BottomSheet/bottomSheetStack.ts+++ b/packages/core/src/BottomSheet/bottomSheetStack.ts@@ -4,17 +4,12 @@/*** @file bottomSheetStack.ts- * @input Uses the DOM (dialog elements, document order) and focusForLastInput- * @output Exports the private bottom-sheet stack registry: registration of- * sheet hosts (modal sheets stack; non-modal sheets are a group of their- * own, hosted as manual popovers), open-order ranking with tree-order- * ties, native top-layer reconciliation, one view per host (top, covered,- * recede depth, scrim ownership, blocking), the replace handoff between a- * sheet closing and a sheet opening in the same update, and the native- * show/hide and focus helpers the hosts share- * @position Internal to BottomSheet; consumed by the standalone host in- * BottomSheet.tsx and by BottomSheetSwitcher. Not exported from the package- * root, and no public API reaches it.+ * @input The DOM (dialog elements, document order) and focusForLastInput+ * @output The private bottom-sheet stack registry: host registration,+ * open-order ranking, top-layer reconciliation, one view per host, the+ * replace handoff, and the shared native show/hide and focus helpers+ * @position Internal to BottomSheet, used by the standalone host in+ * BottomSheet.tsx and by BottomSheetSwitcher. No public API reaches it.** SYNC: When modified, update:* - /packages/core/src/BottomSheet/BottomSheet.tsx@@ -23,83 +18,37 @@* - /packages/core/src/BottomSheet/BottomSheetReplace.test.tsx* - /packages/core/src/BottomSheet/BottomSheet.doc.mjs* - /apps/storybook/stories/BottomSheetReplace.stories.tsx- *- * ## Why a registry and not a component- *- * Every modal sheet keeps its own native `<dialog>` and its own open state. A- * sheet opened while another sheet is open is a stacked sheet: the browser's- * top layer already paints the later `showModal()` above the earlier one, and- * the later modal dialog already blocks the earlier one. What the browser does- * NOT know is that the two dialogs are sheets of one stack, so this registry- * supplies the rest: which sheet is on top, how far back each covered sheet- * recedes, whose `::backdrop` is the one visible scrim, and when the native- * order would come out wrong (several sheets opening in one commit) it puts- * the top layer right before the frame paints. Nothing here is a public- * surface; the hosts call it from their commit-phase effects only.- *- * ## Order is open order, ties are tree order- *- * Each open cycle of a sheet gets a rank: the batch it opened in, then a- * running sequence. A batch is one React commit: registrations that arrive- * between two seals belong to the same commit, because the hosts seal in- * passive effects and React runs every pending passive effect before the next- * commit's layout effects (and flushes them synchronously after a sync- * commit). Later batch is higher. Within one batch there is no open order, so- * document order of the dialog elements decides: a sheet before the sheets- * rendered in its content, siblings in the order they are written. That is the- * order the first painted frame of a deep link must show, and effect order- * (child first) gets it backwards; the rank is read at compare time, after- * every registration of the commit has arrived, so it does not.- *- * ## The top layer is reconciled, not trusted- *- * The registry remembers the order it called `showModal()` in. After every- * change it computes the order the ranks want; where the two diverge it closes- * the dialogs from the first divergence up and shows them again in rank order.- * That happens inside the commit, before paint, so a deep link whose inner- * sheet registered first is repaired without a frame in between. A sheet that- * closes and reopens gets a new rank and is re-shown on top the same way;- * only the dialogs that have to move up are re-shown, the rest keep their- * place, their backdrop and any motion in flight.- *- * ## A replace is a move the person makes from one sheet to the next- *- * One sheet closing and another opening in the same commit, where the closing- * sheet was the top open sheet of its stack (no other open sheet above it,- * the opening sheet aside) and the interaction came from inside it (the- * control last pressed — or, with no fresh press, the focused element — was- * in its dialog), is a replace: the person is moving from one step to the- * next, not stacking one on the other. The registry then runs the handoff a BottomSheetSwitcher runs- * between its steps, on the two standalone dialogs: the entering sheet rises- * above the retained one; a taller retained sheet moves down to meet it; the- * retained sheet fades only after both motions complete, then its dialog- * closes and the entering sheet takes over the scrim in the same frame. The- * retained sheet is inert at once, keeps no place in the dismissal order, and- * lends its opener to the sheet replacing it, so closing the flow later- * returns focus to where the flow began. A covered sheet closing (not the- * top), a sheet closing in a different update from the open, or a close and- * an open driven from a control outside the closing sheet (two owners acting- * in one update) is never a replace, so a push over a stack and a pop out of- * one keep their motion and their own openers. Non-modal sheets- * (`hasScrim={false}`) replace each other too: they are hosted as manual- * popovers, so the top layer orders them, but they are a group of their own- * that never stacks, recedes, or owns a scrim.- *- * ## One state per page, per document- *- * The state lives on `globalThis` so that two copies of this module on one- * page that speak the same stack protocol version share one stack (see- * StackState); everything the stack reads and writes across commits — the- * entries, each document's shown order, which documents have the press- * listeners, the deferred non-modal sheets and their watchers, the element to- * keep focused across a re-show — is in that shared state and none of it is- * per copy. The one module-level value is the engine probe's answer, a fact- * about the browser that every copy measures alike. A copy on another- * protocol version keeps a stack of its own. Within a state, each document is- * its own stack: a sheet portaled into another document has that document's- * top layer, focus and order.*/+// Each modal sheet keeps its own native `<dialog>` and open state. The top+// layer already paints a later showModal() above an earlier one, and the+// later dialog blocks the earlier one. The browser does not know that the+// dialogs are sheets of one stack. So this registry decides which sheet is on+// top, how far each covered sheet recedes, and whose `::backdrop` is the one+// scrim. The hosts call it only from commit-phase effects.+//+// Order is open order. Each open cycle gets a rank: its batch (one React+// commit), then a sequence. Within one batch, document order decides, so a+// sheet comes before the sheets in its content. Effect order is child first,+// so the rank is read at compare time, after the whole commit registered.+//+// The top layer is reconciled, not trusted. Where the shown order differs+// from the rank order, the registry closes the dialogs from the first+// difference up and shows them again in rank order, inside the commit and+// before paint. Only the dialogs that must move up are shown again.+//+// A replace is one sheet closing and another opening in the same commit,+// where the closing sheet was the top open sheet and the last press or focus+// was inside it. The registry then runs the switcher's handoff on the two+// dialogs. The retained sheet is inert at once and lends its opener to the+// entering sheet. A covered sheet closing, a close in another update, or a+// change driven from outside the closing sheet is never a replace. Non-modal+// sheets replace each other too, but they never stack.+//+// The state lives on `globalThis`, under a key with the protocol version, so+// two copies of this module on one page share one stack. A copy on another+// version keeps its own stack. Each document is its own stack.+import {notifyTopLayerEntry} from '../Layer/modalOutlet';import {focusForLastInput} from '../utils/focusReturn';@@ -356,10 +305,8 @@ interface DeferredTopLayer {* The stack protocol version: the shape and meaning of Entry, the* registration, the batch/seal protocol and the shared listeners. Copies of* the package on one page share one stack per document when they speak the- * same protocol (`component:BottomSheet` PR1); the version is part of the- * document-global key, so a copy on another protocol finds no state of its- * own version and keeps a stack of its own — two independent stacks, each- * ordering only the sheets its copy renders, never a shared state read with+ * same protocol. The version is part of the document-global key, so a copy+ * on another protocol keeps its own stack and never reads a shared state of* the wrong shape. Bump it whenever any of those change.*/const STACK_PROTOCOL_VERSION = 8;@@ -566,10 +513,9 @@ function listenForPresses(doc: Document): void {}/**- * The document's last registered sheet left: nothing feeds the press record- * any more, so the listeners go (`architecture:react-component-runtime`- * INV5: a subscription lives as long as what reads it). The next sheet to- * register in the document installs them again.+ * The document's last registered sheet left. Nothing reads the press record+ * now, so the listeners go. The next sheet to register in the document+ * installs them again.*/function stopListeningForPresses(doc: Document): void {if (state.entries.some(entry => entry.doc === doc)) {@@ -968,8 +914,8 @@ function deferTopLayerEntry(state.deferredTopLayer.set(doc, entry);}if (entry.stopListeningForClose == null) {- // Installed with the first deferral and removed with the last promotion- // (`architecture:react-component-runtime` INV5), like the observer below.+ // Installed with the first deferral and removed with the last promotion,+ // like the observer below.const onClose = () => {promoteDeferredNonModal(doc);};