Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/packages/core/src/BottomSheet/BottomSheet.tsx b/packages/core/src/BottomSheet/BottomSheet.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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);
};