Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(lab): animate standalone BottomSheet exit (#5020)

Xinzi Zhoufaedff77d24d
diff --git a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
index 6be4ce716d..e4c96fcb1e 100644
--- a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
+++ b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
@@ -6,59 +6,97 @@ export const docs = {
displayName: 'BottomSheet',
group: 'BottomSheet',
category: 'Overlay',
- keywords: ["bottom sheet","sheet","mobile","touch","drag","swipe","dismiss","grab handle","dialog","overlay","modal"],
+ keywords: [
+ 'bottom sheet',
+ 'sheet',
+ 'mobile',
+ 'touch',
+ 'drag',
+ 'swipe',
+ 'dismiss',
+ 'grab handle',
+ 'dialog',
+ 'overlay',
+ 'modal',
+ ],
theming: {
- targets: [
- {className: 'astryx-bottom-sheet', visualProps: []},
- ],
+ targets: [{className: 'astryx-bottom-sheet', visualProps: []}],
},
- description: 'A mobile touch sheet that rises from the bottom edge, with a grab handle, drag-to-resize snap points, and swipe-to-dismiss. Built on a native modal <dialog>.',
+ description:
+ 'A mobile touch sheet that rises from the bottom edge, with animated entrance and exit, a grab handle, drag-to-resize snap points, and swipe-to-dismiss. Built on a native modal <dialog>.',
props: [
{
name: 'isOpen',
type: 'boolean',
- description: 'Whether the sheet is open. Fully controlled; pair with onOpenChange.',
+ description:
+ 'Whether the sheet is open. Fully controlled; pair with onOpenChange.',
required: true,
},
{
name: 'onOpenChange',
type: '(isOpen: boolean) => void',
- description: 'Called when the sheet opens or closes. The boolean is the requested next state (false on Escape, scrim click, or a swipe past the dismiss threshold). The caller owns the open state.',
+ description:
+ 'Called when the sheet opens or closes. The boolean is the requested next state (false on Escape, scrim click, or a swipe past the dismiss threshold). The caller owns the open state.',
required: true,
},
{
name: 'label',
type: 'string',
- description: 'Accessible label for the sheet. Required; the sheet has no built-in heading to derive a name from.',
+ description:
+ 'Accessible label for the sheet. Required; the sheet has no built-in heading to derive a name from.',
required: true,
},
{
name: 'children',
type: 'ReactNode',
- description: 'Sheet content, rendered below the grab handle in a scrollable area.',
+ description:
+ 'Sheet content, rendered below the grab handle in a scrollable area.',
required: true,
},
{
name: 'height',
type: "'hug' | 'capped' | 'tall' | number | string",
- description: "How tall the sheet is. Named budgets: 'hug' fits its content up to 92% of the viewport, 'capped' is a scrolling mid-height panel (~62%), and 'tall' is a pinned near-full panel (~92%) for content that streams in. Or pass a number (px) / CSS length for a custom budget. The user can drag between snap points regardless. On shorter viewports the sheet fills the available height.",
+ description:
+ "How tall the sheet is. Named budgets: 'hug' fits its content up to 92% of the viewport, 'capped' is a scrolling mid-height panel (~62%), and 'tall' is a pinned near-full panel (~92%) for content that streams in. Or pass a number (px) / CSS length for a custom budget. The user can drag between snap points regardless. On shorter viewports the sheet fills the available height.",
default: "'capped'",
},
{
name: 'hasScrim',
type: 'boolean',
- description: "Whether to render a scrim, the semi-transparent overlay that covers and blocks the background, behind the sheet. true (default) uses showModal(): top layer, focus trap, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss, with the background inert. false still renders a viewport-anchored overlay above the page, not inline content, but uses show() with no scrim, leaving the page behind interactive and scrollable. Escape still closes while focus is inside, and drag/flick-to-dismiss still work.",
+ description:
+ 'Whether to render a scrim, the semi-transparent overlay that covers and blocks the background, behind the sheet. true (default) uses showModal(): top layer, focus trap, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss, with the background inert. false still renders a viewport-anchored overlay above the page, not inline content, but uses show() with no scrim, leaving the page behind interactive and scrollable. Escape still closes while focus is inside, and drag/flick-to-dismiss still work.',
default: 'true',
},
],
usage: {
- description: 'A mobile touch surface for filters, actions, and detail views that should rise from the bottom of the screen. Drag the grab handle to resize: a slow drag settles to the nearest snap point (a short peek, ~half, and ~full detent, filtered to those shorter than the sheet), a fast flick down dismisses, a fast flick up expands. Pulling down on the content when it is scrolled to the top also drags the sheet, giving a larger, more forgiving target. The scrim thins to a faint glance state (but never fully clears) as the sheet collapses onto its shortest "peek" detent; the sheet stays modal, so the background remains inert until dismissed; a residual dim keeps that legible. The sheet is modal: focus is trapped while open and restored to the opener on close, and Escape dismisses, so the swipe gesture always has a keyboard equivalent. Content padding clears the home indicator via env(safe-area-inset-bottom).',
+ description:
+ 'A mobile touch surface for filters, actions, and detail views that should rise from the bottom of the screen. Opening slides the sheet in; closing keeps its native dialog presented but inert until the slide-out and scrim fade complete. Drag the grab handle to resize: a slow drag settles to the nearest snap point (a short peek, ~half, and ~full detent, filtered to those shorter than the sheet), a fast flick down dismisses, a fast flick up expands. Pulling down on the content when it is scrolled to the top also drags the sheet, giving a larger, more forgiving target. The scrim thins to a faint glance state (but never fully clears) as the sheet collapses onto its shortest "peek" detent; the sheet stays modal, so the background remains inert until dismissed; a residual dim keeps that legible. The sheet is modal: focus is trapped while open and restored to the opener after its exit, and Escape dismisses, so the swipe gesture always has a keyboard equivalent. Content padding clears the home indicator via env(safe-area-inset-bottom).',
bestPractices: [
- { guidance: true, description: 'Use for mobile-first surfaces (filters, share sheets, quick actions) where the content should rise from the bottom edge.' },
- { guidance: true, description: 'Keep the caller as the source of truth: derive isOpen from state and clear it in onOpenChange.' },
- { guidance: true, description: "Pick the starting height that fits the content: 'hug' for short bounded content, 'capped' for lists, 'tall' for streaming/resizing content; the user can then drag between snap points." },
- { guidance: true, description: "Use hasScrim={false} for a floating, no-scrim overlay that must coexist with a live page behind it (e.g. a panel over a map). It remains viewport-anchored rather than rendering inline. Keep the default for focused tasks where the background should be inert." },
- { guidance: false, description: 'Use a BottomSheet for desktop inspectors or master-detail; use Drawer (side="end", hasScrim={false}) instead.' },
+ {
+ guidance: true,
+ description:
+ 'Use for mobile-first surfaces (filters, share sheets, quick actions) where the content should rise from the bottom edge.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Keep the caller as the source of truth: derive isOpen from state and clear it in onOpenChange.',
+ },
+ {
+ guidance: true,
+ description:
+ "Pick the starting height that fits the content: 'hug' for short bounded content, 'capped' for lists, 'tall' for streaming/resizing content; the user can then drag between snap points.",
+ },
+ {
+ guidance: true,
+ description:
+ 'Use hasScrim={false} for a floating, no-scrim overlay that must coexist with a live page behind it (e.g. a panel over a map). It remains viewport-anchored rather than rendering inline. Keep the default for focused tasks where the background should be inert.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use a BottomSheet for desktop inspectors or master-detail; use Drawer (side="end", hasScrim={false}) instead.',
+ },
],
},
examples: [
@@ -110,15 +148,36 @@ export const docs = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
- description: 'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, drag-to-resize snap points, swipe-to-dismiss, named height scale, modal (default) or non-modal (hasScrim={false}) presentation',
+ description:
+ 'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, drag-to-resize snap points, swipe-to-dismiss, named height scale, modal (default) or non-modal (hasScrim={false}) presentation',
usage: {
- description: 'Mobile surface for filters, actions, and detail views. Drag the handle to resize between snap points; flick down to dismiss, up to expand. Modal: focus trap + restore, and Escape dismisses so swipe has a keyboard equivalent. Content clears the home indicator via safe-area inset.',
+ description:
+ 'Mobile surface for filters, actions, and detail views. Drag the handle to resize between snap points; flick down to dismiss, up to expand. Modal: focus trap + restore, and Escape dismisses so swipe has a keyboard equivalent. Content clears the home indicator via safe-area inset.',
bestPractices: [
- { guidance: true, description: 'Use for mobile-first bottom surfaces (filters, share sheets, quick actions).' },
- { guidance: true, description: 'Derive isOpen from state; clear it in onOpenChange.' },
- { guidance: true, description: "Pick a height that fits: 'hug' for short content, 'capped' for lists, 'tall' for streaming content." },
- { guidance: true, description: "hasScrim={false} for a floating no-scrim overlay over a live page; it is not inline. Keep the default for focused tasks (inert background)." },
- { guidance: false, description: 'Use for desktop inspectors or master-detail; use Drawer instead.' },
+ {
+ guidance: true,
+ description:
+ 'Use for mobile-first bottom surfaces (filters, share sheets, quick actions).',
+ },
+ {
+ guidance: true,
+ description: 'Derive isOpen from state; clear it in onOpenChange.',
+ },
+ {
+ guidance: true,
+ description:
+ "Pick a height that fits: 'hug' for short content, 'capped' for lists, 'tall' for streaming content.",
+ },
+ {
+ guidance: true,
+ description:
+ 'hasScrim={false} for a floating no-scrim overlay over a live page; it is not inline. Keep the default for focused tasks (inert background).',
+ },
+ {
+ guidance: false,
+ description:
+ 'Use for desktop inspectors or master-detail; use Drawer instead.',
+ },
],
},
};
diff --git a/packages/lab/src/BottomSheet/BottomSheet.test.tsx b/packages/lab/src/BottomSheet/BottomSheet.test.tsx
index ba02360613..5f808107d4 100644
--- a/packages/lab/src/BottomSheet/BottomSheet.test.tsx
+++ b/packages/lab/src/BottomSheet/BottomSheet.test.tsx
@@ -59,6 +59,25 @@ function getSheet(): HTMLElement {
return sheet;
}
+function finishSheetExit() {
+ fireEvent.transitionEnd(getSheet(), {propertyName: 'transform'});
+}
+
+function ExitHarness({hasScrim}: {hasScrim?: boolean}) {
+ const [isOpen, setIsOpen] = useState(true);
+ return (
+ <BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Filters"
+ hasScrim={hasScrim}>
+ <button type="button" onClick={() => setIsOpen(false)}>
+ Close sheet
+ </button>
+ </BottomSheet>
+ );
+}
+
// The grab handle is the panel's first child (decorative, aria-hidden).
function getHandle(): HTMLElement {
const handle = getSheet().querySelector<HTMLElement>('[aria-hidden="true"]');
@@ -134,6 +153,25 @@ describe('BottomSheet', () => {
expect(onOpenChange).toHaveBeenCalledWith(false);
});
+ it('keeps a standalone modal sheet presented through its exit animation', () => {
+ render(<ExitHarness />);
+ const dialog = screen.getByRole('dialog', {name: 'Filters'});
+
+ fireEvent.click(screen.getByRole('button', {name: 'Close sheet'}));
+
+ expect(dialog).toHaveAttribute('open');
+ expect(dialog).toHaveAttribute('inert');
+ expect(dialog).toHaveAttribute('aria-hidden', 'true');
+ expect(dialog).not.toHaveAttribute('aria-modal');
+ expect(dialog).toHaveStyle({'--_sheet-scrim-opacity': '0'});
+ expect(document.body.style.position).toBe('fixed');
+
+ finishSheetExit();
+
+ expect(dialog).not.toHaveAttribute('open');
+ expect(document.body.style.position).not.toBe('fixed');
+ });
+
it('does not dismiss when the sheet surface itself is clicked', () => {
const onOpenChange = vi.fn();
render(
@@ -238,6 +276,21 @@ describe('BottomSheet', () => {
screen.getByRole('textbox', {name: 'Search'}),
);
});
+
+ it('keeps a standalone non-modal sheet visible until its exit ends', () => {
+ render(<ExitHarness hasScrim={false} />);
+ const dialog = screen.getByRole('dialog', {name: 'Filters'});
+
+ fireEvent.click(screen.getByRole('button', {name: 'Close sheet'}));
+
+ expect(dialog).toHaveAttribute('open');
+ expect(dialog).toHaveAttribute('inert');
+ expect(document.body.style.position).not.toBe('fixed');
+
+ finishSheetExit();
+
+ expect(dialog).not.toHaveAttribute('open');
+ });
});
describe('grab handle', () => {
diff --git a/packages/lab/src/BottomSheet/BottomSheet.tsx b/packages/lab/src/BottomSheet/BottomSheet.tsx
index b711b74194..0c99f1ab28 100644
--- a/packages/lab/src/BottomSheet/BottomSheet.tsx
+++ b/packages/lab/src/BottomSheet/BottomSheet.tsx
@@ -21,7 +21,8 @@
* layer, focus trap, scrim, scroll lock, background inert); `false` uses
* `show()` for a non-modal sheet with no scrim, leaving the page behind
* interactive and scrollable (the transparent shell is pointer-events:none so
- * taps pass through).
+ * taps pass through). Both modes keep the native dialog presented but inert
+ * until the slide-out transition ends.
*
* The drag/snap/dismiss machinery lives in `useSheetGestures`; the offset
* geometry lives in the pure, tested `snapOffsets` module. Both are internal
@@ -34,7 +35,7 @@
* - /apps/storybook/stories/BottomSheet.stories.tsx (examples and visual coverage)
*/
-import {useCallback, useEffect, useRef, type ReactNode} from 'react';
+import {useCallback, useEffect, useRef, useState, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '@astryxdesign/core';
import {
@@ -212,6 +213,9 @@ const styles = stylex.create({
sheetClosing: {
transform: 'translateY(100%)',
},
+ sheetExiting: {
+ pointerEvents: 'none',
+ },
handleBar: {
flexShrink: 0,
display: 'flex',
@@ -344,6 +348,8 @@ export function BottomSheet({
xstyle,
...props
}: BottomSheetProps) {
+ const [isPresented, setIsPresented] = useState(isOpen);
+ const isExiting = !isOpen && isPresented;
const dialogRef = useRef<HTMLDialogElement | null>(null);
const triggerRef = useRef<HTMLElement | null>(null);
const sheetNodeRef = useRef<HTMLDivElement | null>(null);
@@ -375,6 +381,7 @@ export function BottomSheet({
return;
}
if (isOpen) {
+ setIsPresented(true);
dialog.style.setProperty('--_sheet-scrim-opacity', '1');
if (!dialog.open) {
// Only remember/restore focus for modal sheets; a non-modal sheet must
@@ -395,6 +402,9 @@ export function BottomSheet({
}
}
} else if (dialog.open) {
+ if (hasScrim) {
+ dialog.style.setProperty('--_sheet-scrim-opacity', '0');
+ }
// Wait for the slide-out (sheetClosing, applied this render) before
// close() releases the top layer. Timeout backstops a missing
// transitionend (reduced motion, hidden tab).
@@ -410,6 +420,7 @@ export function BottomSheet({
if (dialog.open) {
dialog.close();
}
+ setIsPresented(false);
triggerRef.current?.focus();
triggerRef.current = null;
};
@@ -419,8 +430,8 @@ export function BottomSheet({
}
};
sheet?.addEventListener('transitionend', onEnd);
- // Backstop above --duration-medium (410ms) so transitionend normally
- // fires first; this only covers environments that don't emit it.
+ // Backstop above --duration-medium so transitionend normally fires
+ // first; this only covers environments that don't emit it.
const timer = setTimeout(finish, 450);
return () => {
clearTimeout(timer);
@@ -431,7 +442,7 @@ export function BottomSheet({
// Only a modal sheet locks body scroll; a non-modal sheet leaves the page
// scrollable behind it.
- useScrollLock(isOpen && hasScrim);
+ useScrollLock(isPresented && hasScrim);
// Enforce an accessible name: label is required by types, but a JS caller
// can still pass an empty string, leaving the sheet unnamed.
@@ -485,7 +496,7 @@ export function BottomSheet({
<dialog
{...stylex.props(
styles.dialog,
- isOpen && styles.dialogOpen,
+ (isOpen || isPresented) && styles.dialogOpen,
// Modal: paint the ::backdrop scrim (top layer). Non-modal: no scrim,
// pass taps through to the page, and sit above content via z-index.
hasScrim && styles.scrim,
@@ -493,7 +504,9 @@ export function BottomSheet({
)}
ref={mergeRefs(ref, dialogRef)}
aria-label={label}
- aria-modal={hasScrim ? 'true' : undefined}
+ aria-hidden={isExiting ? 'true' : undefined}
+ aria-modal={hasScrim && isOpen ? 'true' : undefined}
+ inert={isExiting ? true : undefined}
onCancel={handleCancel}
onClick={handleClick}
onKeyDown={handleKeyDown}
@@ -508,12 +521,13 @@ export function BottomSheet({
styles.sheet,
isHug ? styles.hugHeight : styles.budget,
!isOpen && styles.sheetClosing,
+ isExiting && styles.sheetExiting,
xstyle,
),
undefined,
{
['--_sheet-budget' as string]: budget,
- ...contentProps.style,
+ ...(isOpen ? contentProps.style : {}),
},
)}>
<div