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.mjsindex 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.tsxindex 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.tsxindex 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