Skip to content

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

TypeScript

feat(lab): add BottomSheet (snap points, swipe-to-dismiss, grab handle) (#4468)

Cindy Zhang56a87ea36534
diff --git a/apps/storybook/stories/BottomSheet.stories.tsx b/apps/storybook/stories/BottomSheet.stories.tsx
new file mode 100644
index 0000000000..7d24e9a53a
--- /dev/null
+++ b/apps/storybook/stories/BottomSheet.stories.tsx
@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {useState} from 'react';
+import {BottomSheet} from '@astryxdesign/lab';
+import {Button} from '@astryxdesign/core/Button';
+import {Divider} from '@astryxdesign/core/Divider';
+import {Heading} from '@astryxdesign/core/Heading';
+import {Section} from '@astryxdesign/core/Section';
+import {VStack} from '@astryxdesign/core/Stack';
+import {Text} from '@astryxdesign/core/Text';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {TextArea} from '@astryxdesign/core/TextArea';
+import {CheckboxInput} from '@astryxdesign/core/CheckboxInput';
+
+const meta: Meta<typeof BottomSheet> = {
+ title: 'Lab/BottomSheet',
+ component: BottomSheet,
+ tags: ['autodocs'],
+ parameters: {
+ layout: 'fullscreen',
+ },
+ decorators: [
+ Story => (
+ <div style={{minHeight: 480, padding: 32}}>
+ <Story />
+ </div>
+ ),
+ ],
+};
+
+export default meta;
+type Story = StoryObj<typeof BottomSheet>;
+
+export const Showcase: Story = {
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <Button label="Open sheet" onClick={() => setIsOpen(true)} />
+ <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen} label="Filters">
+ <Section padding={4}>
+ <VStack gap={4}>
+ <Heading level={3}>Filters</Heading>
+ <Divider />
+ <VStack gap={2}>
+ <CheckboxInput label="In stock" value={false} />
+ <CheckboxInput label="On sale" value={false} />
+ <CheckboxInput label="Free shipping" value={false} />
+ </VStack>
+ <Button label="Apply" onClick={() => setIsOpen(false)} />
+ </VStack>
+ </Section>
+ </BottomSheet>
+ </>
+ );
+ },
+};
+
+export const TallSheet: Story = {
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <Button label="Open nearby places" onClick={() => setIsOpen(true)} />
+ <BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Nearby places"
+ height="tall">
+ <Section padding={4}>
+ <VStack gap={3}>
+ <Text type="supporting" color="secondary">
+ Drag the handle down or press Escape to dismiss.
+ </Text>
+ <Divider />
+ {Array.from({length: 12}, (_, i) => (
+ <VStack key={i} gap={1}>
+ <Text type="label">Place {i + 1}</Text>
+ <Text type="supporting" color="secondary">
+ {(0.2 + i * 0.3).toFixed(1)} mi away
+ </Text>
+ </VStack>
+ ))}
+ </VStack>
+ </Section>
+ </BottomSheet>
+ </>
+ );
+ },
+};
+
+export const AutoHeight: Story = {
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <Button label="Add a comment" onClick={() => setIsOpen(true)} />
+ <BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Add a comment"
+ height="auto">
+ <Section padding={4}>
+ <VStack gap={4}>
+ <Heading level={3}>Add a comment</Heading>
+ <Text type="supporting" color="secondary">
+ The sheet fits its content up to the tall budget.
+ </Text>
+ <Divider />
+ <TextInput label="Title" value="" />
+ <TextArea label="Comment" rows={4} value="" />
+ <Button label="Post" onClick={() => setIsOpen(false)} />
+ </VStack>
+ </Section>
+ </BottomSheet>
+ </>
+ );
+ },
+};
diff --git a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
new file mode 100644
index 0000000000..aaa891c4c5
--- /dev/null
+++ b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
@@ -0,0 +1,105 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('../../../core/src/docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'BottomSheet',
+ displayName: 'BottomSheet',
+ group: 'BottomSheet',
+ category: 'Overlay',
+ keywords: ["bottom sheet","sheet","mobile","touch","drag","swipe","dismiss","grab handle","dialog","overlay","modal"],
+ theming: {
+ targets: [
+ {className: 'astryx-bottom-sheet', visualProps: []},
+ ],
+ },
+ description: 'A mobile touch sheet that rises from the bottom edge, with a grab handle and swipe-to-dismiss. Built on the Drawer <dialog> engine.',
+ props: [
+ {
+ name: 'isOpen',
+ type: 'boolean',
+ 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.',
+ 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.',
+ required: true,
+ },
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Sheet content, rendered below the grab handle in a scrollable area.',
+ required: true,
+ },
+ {
+ name: 'height',
+ type: "'short' | 'medium' | 'tall' | 'auto'",
+ description: "How tall the sheet is: 'short' is a fixed peek height, 'medium' is half the viewport, 'tall' is nearly the full viewport, and 'auto' fits its content up to the 'tall' budget. On shorter viewports the sheet fills the available height.",
+ default: "'medium'",
+ },
+ ],
+ usage: {
+ description: 'A mobile touch surface for filters, actions, and detail views that should rise from the bottom of the screen. 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).',
+ 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 a height that fits the content — 'auto' for short sheets, 'medium'/'tall' for lists and forms." },
+ { guidance: false, description: 'Use a BottomSheet for desktop inspectors or master-detail; use Drawer (side="end", hasScrim={false}) instead.' },
+ ],
+ },
+ examples: [
+ {
+ label: 'Basic',
+ code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Filters">
+ <FilterControls />
+</BottomSheet>`,
+ },
+ {
+ label: 'Tall sheet (a list)',
+ code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Nearby places"
+ height="tall">
+ <PlaceList />
+</BottomSheet>`,
+ },
+ {
+ label: 'Auto height (fits content)',
+ code: `const [isOpen, setIsOpen] = useState(false);
+<BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Share"
+ height="auto">
+ <ShareActions />
+</BottomSheet>`,
+ },
+ ],
+};
+
+/** @type {import('../../../core/src/docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'mobile touch sheet rising from the bottom edge (built on the Drawer <dialog> engine): grab handle, swipe-to-dismiss, named height scale',
+ usage: {
+ description: 'Mobile surface for filters, actions, and detail views. 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: 'auto' for short sheets, 'medium'/'tall' for lists and forms." },
+ { 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
new file mode 100644
index 0000000000..d4f15731aa
--- /dev/null
+++ b/packages/lab/src/BottomSheet/BottomSheet.test.tsx
@@ -0,0 +1,233 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheet.test.tsx
+ * @input Uses vitest, @testing-library/react, BottomSheet component
+ * @output Unit tests for BottomSheet component behavior
+ * @position Lab testing; validates BottomSheet.tsx implementation
+ *
+ * SYNC: When BottomSheet.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render, screen, fireEvent, act} from '@testing-library/react';
+import {useState} from 'react';
+import {BottomSheet} from './BottomSheet';
+
+// jsdom doesn't implement <dialog> open/close or pointer capture; stub them.
+beforeEach(() => {
+ HTMLDialogElement.prototype.showModal = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.setAttribute('open', '');
+ });
+ HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+ this.setAttribute('open', '');
+ });
+ HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+ this.removeAttribute('open');
+ });
+ if (!Element.prototype.setPointerCapture) {
+ Element.prototype.setPointerCapture = vi.fn();
+ Element.prototype.releasePointerCapture = vi.fn();
+ }
+
+ vi.stubGlobal(
+ 'matchMedia',
+ vi.fn().mockReturnValue({
+ matches: false,
+ media: '',
+ onchange: null,
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn(),
+ addListener: vi.fn(),
+ removeListener: vi.fn(),
+ dispatchEvent: vi.fn(),
+ }),
+ );
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+function getHandle(): HTMLElement {
+ const handle = document.querySelector<HTMLElement>(
+ '[data-astryx-sheet-handle]',
+ );
+ if (!handle) {
+ throw new Error('grab handle not found');
+ }
+ return handle;
+}
+
+// Drive a pointer drag on the grab handle. jsdom PointerEvents don't carry
+// clientY, so dispatch plain events with the coords the handlers read.
+function drag(handle: HTMLElement, points: Array<{y: number}>) {
+ const [down, ...rest] = points;
+ fireEvent.pointerDown(handle, {pointerId: 1, clientY: down.y});
+ for (const p of rest) {
+ fireEvent.pointerMove(handle, {pointerId: 1, clientY: p.y});
+ }
+ const last = points[points.length - 1];
+ fireEvent.pointerUp(handle, {pointerId: 1, clientY: last.y});
+}
+
+describe('BottomSheet', () => {
+ it('renders children when open and applies the accessible label', () => {
+ render(
+ <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+ Sheet content
+ </BottomSheet>,
+ );
+ const dialog = screen.getByRole('dialog');
+ expect(dialog).toBeInTheDocument();
+ expect(dialog).toHaveAccessibleName('Filters');
+ expect(screen.getByText('Sheet content')).toBeInTheDocument();
+ });
+
+ it('does not show when isOpen is false', () => {
+ render(
+ <BottomSheet isOpen={false} onOpenChange={() => {}} label="Filters">
+ Hidden
+ </BottomSheet>,
+ );
+ expect(HTMLDialogElement.prototype.showModal).not.toHaveBeenCalled();
+ });
+
+ it('opens modally (showModal + aria-modal)', () => {
+ render(
+ <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+ Content
+ </BottomSheet>,
+ );
+ expect(HTMLDialogElement.prototype.showModal).toHaveBeenCalled();
+ expect(screen.getByRole('dialog')).toHaveAttribute('aria-modal', 'true');
+ });
+
+ it('requests close on Escape', () => {
+ const onOpenChange = vi.fn();
+ render(
+ <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+ Content
+ </BottomSheet>,
+ );
+ fireEvent.keyDown(screen.getByRole('dialog'), {key: 'Escape'});
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+
+ it('requests close when the scrim (dialog element itself) is clicked', () => {
+ const onOpenChange = vi.fn();
+ render(
+ <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+ Content
+ </BottomSheet>,
+ );
+ fireEvent.click(screen.getByRole('dialog'));
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+
+ describe('grab handle', () => {
+ it('renders a decorative handle hidden from assistive tech', () => {
+ render(
+ <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+ Content
+ </BottomSheet>,
+ );
+ const handle = getHandle();
+ expect(handle).toHaveAttribute('aria-hidden', 'true');
+ });
+ });
+
+ describe('swipe to dismiss', () => {
+ it('requests close when dragged past the dismiss threshold', () => {
+ const onOpenChange = vi.fn();
+ render(
+ <BottomSheet isOpen onOpenChange={onOpenChange} label="Filters">
+ Content
+ </BottomSheet>,
+ );
+ // No measured height in jsdom (0) -> any downward drag dismisses via
+ // the distance branch (offset > 0.25) once released downward.
+ drag(getHandle(), [{y: 0}, {y: 40}, {y: 120}]);
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+ });
+
+ describe('height', () => {
+ it('renders for each named height without error', () => {
+ for (const height of ['short', 'medium', 'tall', 'auto'] as const) {
+ const {unmount} = render(
+ <BottomSheet
+ isOpen
+ onOpenChange={() => {}}
+ label="Filters"
+ height={height}>
+ Content
+ </BottomSheet>,
+ );
+ expect(screen.getByRole('dialog')).toBeInTheDocument();
+ unmount();
+ }
+ });
+ });
+
+ describe('focus restore', () => {
+ function Harness() {
+ const [isOpen, setIsOpen] = useState(false);
+ return (
+ <>
+ <button type="button" onClick={() => setIsOpen(true)}>
+ Open sheet
+ </button>
+ <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen} label="Filters">
+ <button type="button" onClick={() => setIsOpen(false)}>
+ Done
+ </button>
+ </BottomSheet>
+ </>
+ );
+ }
+
+ it('restores focus to the opener after close', async () => {
+ vi.useFakeTimers();
+ try {
+ render(<Harness />);
+ const opener = screen.getByRole('button', {name: 'Open sheet'});
+ opener.focus();
+ fireEvent.click(opener);
+ fireEvent.click(screen.getByRole('button', {name: 'Done'}));
+ await act(async () => {
+ vi.runAllTimers();
+ });
+ expect(document.activeElement).toBe(opener);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+ });
+
+ describe('reduced motion', () => {
+ it('opens without throwing when prefers-reduced-motion is set', () => {
+ vi.stubGlobal(
+ 'matchMedia',
+ vi.fn().mockReturnValue({
+ matches: true,
+ media: '(prefers-reduced-motion: reduce)',
+ onchange: null,
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn(),
+ addListener: vi.fn(),
+ removeListener: vi.fn(),
+ dispatchEvent: vi.fn(),
+ }),
+ );
+ render(
+ <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
+ Content
+ </BottomSheet>,
+ );
+ expect(screen.getByRole('dialog')).toBeInTheDocument();
+ });
+ });
+});
diff --git a/packages/lab/src/BottomSheet/BottomSheet.tsx b/packages/lab/src/BottomSheet/BottomSheet.tsx
new file mode 100644
index 0000000000..adc1eb8c98
--- /dev/null
+++ b/packages/lab/src/BottomSheet/BottomSheet.tsx
@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file BottomSheet.tsx
+ * @input Uses React, StyleX, theme tokens, Drawer, useSheetGestures, themeProps
+ * @output Exports BottomSheet component and BottomSheetProps
+ * @position Lab implementation; consumed by index.ts, tested by BottomSheet.test.tsx, demonstrated in Storybook
+ *
+ * A mobile touch surface that rises from the bottom edge with a grab handle
+ * and swipe-to-dismiss. Built ON TOP OF the lab Drawer's native `<dialog>`
+ * engine (`side="bottom"`) rather than forking it — Drawer owns
+ * showModal/show, the open/close slide animation, focus trap + restore,
+ * scroll lock, the Escape/scrim contract, and the LIFO overlay registry.
+ * BottomSheet layers the grab handle and the drag-to-dismiss gesture on top,
+ * inside the dialog.
+ *
+ * The gesture translate is applied to an inner sheet wrapper, not the
+ * `<dialog>` itself, so Drawer owns the open/close slide and the drag
+ * translates within it without the two transforms fighting.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/BottomSheet/BottomSheet.doc.mjs (props table, features, usage)
+ * - /packages/lab/src/BottomSheet/BottomSheet.test.tsx (tests for new/changed behavior)
+ * - /packages/lab/src/BottomSheet/index.ts (exports if types change)
+ * - /apps/storybook/stories/BottomSheet.stories.tsx (examples and visual coverage)
+ */
+
+import {type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '@astryxdesign/core';
+import {
+ colorVars,
+ radiusVars,
+ spacingVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+import {mergeProps, themeProps} from '@astryxdesign/core/utils';
+import {Drawer} from '../Drawer';
+import {useSheetGestures} from './useSheetGestures';
+
+/**
+ * Height budget for each named size. `medium`/`tall` track the viewport so
+ * the sheet scales with the device; `short` is a fixed peek height. `auto`
+ * is handled separately (fits content, capped at the `tall` budget).
+ */
+const HEIGHT_BUDGETS = {
+ short: '240px',
+ medium: '50dvh',
+ tall: '90dvh',
+ auto: '90dvh',
+} as const;
+
+export type BottomSheetHeight = keyof typeof HEIGHT_BUDGETS;
+
+// Sheets on wide touch devices (tablets) shouldn't stretch edge to edge;
+// cap and center them. Matches the `sm` layout breakpoint. On phones the
+// viewport is narrower than this, so the sheet stays full-width.
+const MAX_SHEET_WIDTH = 640;
+
+const styles = stylex.create({
+ // Inner wrapper that carries the live drag translate AND the visible sheet
+ // surface (background, rounded top, width cap). The translate must live on
+ // the painted surface — not the <dialog> — so the whole sheet follows the
+ // swipe instead of the content sliding out of a fixed white panel. Drawer
+ // owns the open/close slide on the <dialog>; this wrapper adds the gesture
+ // offset within it so the two transforms don't fight. Safe-area padding
+ // clears the home indicator on notched devices.
+ sheet: {
+ display: 'flex',
+ flexDirection: 'column',
+ minHeight: 0,
+ height: '100%',
+ width: '100%',
+ maxWidth: MAX_SHEET_WIDTH,
+ marginInline: 'auto',
+ backgroundColor: colorVars['--color-background-surface'],
+ borderStartStartRadius: radiusVars['--radius-page'],
+ borderStartEndRadius: radiusVars['--radius-page'],
+ overflow: 'hidden',
+ paddingBlockEnd: `env(safe-area-inset-bottom, 0px)`,
+ willChange: 'transform',
+ },
+ // Neutralize Drawer's <dialog> surface so only the swipeable wrapper paints.
+ // Without this the dialog's white background + shadow stay fixed while the
+ // wrapper slides, leaving a static panel behind the drag. The scrim behind
+ // the sheet provides the depth separation a shadow would.
+ dialogSurface: {
+ backgroundColor: 'transparent',
+ boxShadow: 'none',
+ borderBlockStartWidth: 0,
+ },
+ handleBar: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ paddingBlock: spacingVars['--spacing-2'],
+ touchAction: 'none',
+ cursor: 'grab',
+ },
+ handlePill: {
+ width: 36,
+ height: 4,
+ borderRadius: radiusVars['--radius-full'],
+ backgroundColor: colorVars['--color-border'],
+ },
+ body: {
+ flexGrow: 1,
+ minHeight: 0,
+ overflowY: 'auto',
+ overscrollBehavior: 'contain',
+ },
+ // `auto` fits content instead of filling the height budget; the budget
+ // becomes an upper bound. Applied to the <dialog> (overrides Drawer's
+ // block-size treatment, which is applied earlier in the props chain).
+ autoHeight: {
+ height: 'fit-content',
+ maxHeight: HEIGHT_BUDGETS.auto,
+ },
+});
+export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
+ /** Ref forwarded to the underlying <dialog> element. */
+ ref?: React.Ref<HTMLDialogElement>;
+
+ /** Whether the sheet is open. Fully controlled — pair with `onOpenChange`. */
+ isOpen: boolean;
+
+ /**
+ * 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.
+ */
+ onOpenChange: (isOpen: boolean) => void;
+
+ /**
+ * Accessible label for the sheet (required — the sheet has no built-in
+ * heading to derive a name from).
+ */
+ label: string;
+
+ /** Sheet content, rendered below the grab handle in a scrollable area. */
+ children: ReactNode;
+
+ /**
+ * How tall the sheet is:
+ * - `'short'` — a fixed peek height
+ * - `'medium'` — half the viewport
+ * - `'tall'` — nearly the full viewport
+ * - `'auto'` — fits its content, capped at the `'tall'` budget
+ *
+ * On viewports shorter than the budget the sheet fills the available
+ * height.
+ * @default 'medium'
+ */
+ height?: BottomSheetHeight;
+
+ /** Test ID for the root element. */
+ 'data-testid'?: string;
+}
+
+/**
+ * A mobile touch sheet that rises from the bottom edge, with a grab handle
+ * and swipe-to-dismiss. Built on the lab Drawer's `<dialog>` engine
+ * (`side="bottom"`): Drawer owns the open/close slide, focus trap + restore,
+ * scroll lock, and the Escape/scrim contract, while BottomSheet layers the
+ * grab handle and drag-to-dismiss on top.
+ *
+ * @example
+ * ```
+ * const [isOpen, setIsOpen] = useState(false);
+ * <BottomSheet
+ * isOpen={isOpen}
+ * onOpenChange={setIsOpen}
+ * label="Filters">
+ * <FilterControls />
+ * </BottomSheet>
+ * ```
+ */
+export function BottomSheet({
+ isOpen,
+ onOpenChange,
+ label,
+ children,
+ height = 'medium',
+ xstyle,
+ ...props
+}: BottomSheetProps) {
+ const close = () => onOpenChange(false);
+ const {contentProps, handleProps} = useSheetGestures({
+ isOpen,
+ onDismiss: close,
+ });
+
+ return (
+ <Drawer
+ isOpen={isOpen}
+ onClose={close}
+ side="bottom"
+ size={HEIGHT_BUDGETS[height]}
+ label={label}
+ hasScrim
+ hasCloseButton={false}
+ xstyle={[styles.dialogSurface, height === 'auto' && styles.autoHeight]}
+ {...props}>
+ <div
+ data-astryx-sheet=""
+ {...mergeProps(
+ themeProps('bottom-sheet'),
+ stylex.props(styles.sheet, xstyle),
+ contentProps.style,
+ )}>
+ <div
+ data-astryx-sheet-handle=""
+ {...stylex.props(styles.handleBar)}
+ {...handleProps}
+ aria-hidden="true">
+ <div {...stylex.props(styles.handlePill)} />
+ </div>
+ <div {...stylex.props(styles.body)}>{children}</div>
+ </div>
+ </Drawer>
+ );
+}
+
+BottomSheet.displayName = 'BottomSheet';
diff --git a/packages/lab/src/BottomSheet/index.ts b/packages/lab/src/BottomSheet/index.ts
new file mode 100644
index 0000000000..661f21083b
--- /dev/null
+++ b/packages/lab/src/BottomSheet/index.ts
@@ -0,0 +1,11 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input BottomSheet.tsx
+ * @output Re-exports BottomSheet component and BottomSheetProps type
+ * @position Lab entry point for the BottomSheet directory
+ */
+
+export {BottomSheet} from './BottomSheet';
+export type {BottomSheetProps} from './BottomSheet';
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs b/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
new file mode 100644
index 0000000000..4d90c024f2
--- /dev/null
+++ b/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../../../core/src/docs-types').HookDoc} */
+export const docs = {
+ name: 'useSheetGestures',
+ displayName: 'useSheetGestures',
+ keywords: ['sheet', 'drag', 'swipe', 'dismiss', 'gesture', 'pointer', 'touch', 'bottom sheet'],
+ params: [
+ {
+ name: 'options',
+ type: 'UseSheetGesturesOptions',
+ description: 'isOpen and onDismiss. Internal to BottomSheet — not exported from the lab entry point.',
+ required: true,
+ },
+ ],
+ returns: [
+ {
+ name: 'result',
+ type: 'UseSheetGesturesResult',
+ description: 'contentProps (spread on the sliding surface for the live translate + touch-action guard), handleProps (spread on the grab handle for the pointer drag), plus dragOffset and isDragging for callers that want to drive their own animation.',
+ },
+ ],
+ usage: {
+ description:
+ 'Drag-to-dismiss machinery for the bottom sheet. Tracks a pointer drag down the block axis, translates the sliding surface live, and on release either dismisses (past a distance or velocity threshold) or springs back to fully open. Pointer-events based (one path for mouse + touch), SSR-safe, and respects prefers-reduced-motion. Escape (routed by the owning dialog) provides the keyboard equivalent of the swipe.',
+ bestPractices: [
+ { guidance: true, description: 'Spread handleProps on the grab-handle element and contentProps on the sliding surface (the panel that carries the translate).' },
+ { guidance: false, description: 'Wire onDismiss to anything other than the owning sheet close — it fires when a swipe crosses the dismiss threshold.' },
+ ],
+ },
+};
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.test.ts b/packages/lab/src/BottomSheet/useSheetGestures.test.ts
new file mode 100644
index 0000000000..85788dcf8e
--- /dev/null
+++ b/packages/lab/src/BottomSheet/useSheetGestures.test.ts
@@ -0,0 +1,160 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useSheetGestures.test.ts
+ * @input Uses vitest, @testing-library/react renderHook, useSheetGestures
+ * @output Unit tests for useSheetGestures behavior
+ * @position Testing; validates useSheetGestures.ts implementation
+ *
+ * SYNC: When useSheetGestures.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {act, renderHook} from '@testing-library/react';
+import {
+ useSheetGestures,
+ type UseSheetGesturesOptions,
+} from './useSheetGestures';
+
+const SHEET_HEIGHT = 400;
+
+// A fake pointer event object good enough for the handlers, which only read
+// pointerId, clientY, timeStamp, and currentTarget's capture + measure APIs.
+function pointerEvent(
+ clientY: number,
+ timeStamp: number,
+ target: HTMLElement,
+ pointerId = 1,
+) {
+ return {
+ pointerId,
+ clientY,
+ timeStamp,
+ currentTarget: target,
+ } as unknown as React.PointerEvent;
+}
+
+function makeTarget(): HTMLElement {
+ const el = document.createElement('div');
+ el.setAttribute('data-astryx-sheet', '');
+ el.setPointerCapture = vi.fn();
+ el.releasePointerCapture = vi.fn();
+ el.getBoundingClientRect = () => ({height: SHEET_HEIGHT}) as DOMRect;
+ return el;
+}
+
+beforeEach(() => {
+ vi.stubGlobal(
+ 'matchMedia',
+ vi.fn().mockReturnValue({
+ matches: false,
+ addEventListener: vi.fn(),
+ removeEventListener: vi.fn(),
+ }),
+ );
+});
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+function setup(options: Partial<UseSheetGesturesOptions> = {}) {
+ const onDismiss = vi.fn();
+ const hook = renderHook(
+ (props: UseSheetGesturesOptions) => useSheetGestures(props),
+ {
+ initialProps: {
+ isOpen: true,
+ onDismiss,
+ ...options,
+ } as UseSheetGesturesOptions,
+ },
+ );
+ return {hook, onDismiss};
+}
+
+describe('useSheetGestures', () => {
+ it('dismisses when dragged past the distance threshold (slow drag)', () => {
+ const {hook, onDismiss} = setup();
+ const target = makeTarget();
+ const {handleProps} = hook.result.current;
+ act(() => {
+ handleProps.onPointerDown(pointerEvent(0, 0, target));
+ });
+ // Drag down slowly, well past 25% of 400px, low velocity.
+ act(() => {
+ handleProps.onPointerMove(pointerEvent(60, 200, target));
+ handleProps.onPointerMove(pointerEvent(140, 600, target));
+ });
+ act(() => {
+ handleProps.onPointerUp(pointerEvent(140, 620, target));
+ });
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ });
+
+ it('dismisses on a fast flick even below the distance threshold', () => {
+ const {hook, onDismiss} = setup();
+ const target = makeTarget();
+ const {handleProps} = hook.result.current;
+ act(() => {
+ handleProps.onPointerDown(pointerEvent(0, 0, target));
+ });
+ // Small distance (30px < 100px) but very fast (30px / 10ms = 3px/ms).
+ act(() => {
+ handleProps.onPointerMove(pointerEvent(30, 10, target));
+ });
+ act(() => {
+ handleProps.onPointerUp(pointerEvent(30, 12, target));
+ });
+ expect(onDismiss).toHaveBeenCalledTimes(1);
+ });
+
+ it('springs back (no dismiss) below the threshold', () => {
+ const {hook, onDismiss} = setup();
+ const target = makeTarget();
+ const {handleProps} = hook.result.current;
+ act(() => {
+ handleProps.onPointerDown(pointerEvent(0, 0, target));
+ });
+ act(() => {
+ handleProps.onPointerMove(pointerEvent(20, 300, target));
+ });
+ act(() => {
+ handleProps.onPointerUp(pointerEvent(20, 620, target));
+ });
+ expect(onDismiss).not.toHaveBeenCalled();
+ expect(hook.result.current.dragOffset).toBe(0);
+ expect(hook.result.current.isDragging).toBe(false);
+ });
+
+ it('translates the surface live during a drag', () => {
+ const {hook} = setup();
+ const target = makeTarget();
+ const {handleProps} = hook.result.current;
+ act(() => {
+ handleProps.onPointerDown(pointerEvent(0, 0, target));
+ });
+ act(() => {
+ handleProps.onPointerMove(pointerEvent(50, 100, target));
+ });
+ expect(hook.result.current.dragOffset).toBe(50);
+ expect(hook.result.current.isDragging).toBe(true);
+ expect(hook.result.current.contentProps.style.transform).toBe(
+ 'translateY(50px)',
+ );
+ });
+
+ it('ignores upward drag past the fully-open position', () => {
+ const {hook} = setup();
+ const target = makeTarget();
+ const {handleProps} = hook.result.current;
+ act(() => {
+ handleProps.onPointerDown(pointerEvent(100, 0, target));
+ });
+ // Drag UP (clientY decreasing) — no rubber-band overscroll.
+ act(() => {
+ handleProps.onPointerMove(pointerEvent(20, 100, target));
+ });
+ expect(hook.result.current.dragOffset).toBe(0);
+ });
+});
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.ts b/packages/lab/src/BottomSheet/useSheetGestures.ts
new file mode 100644
index 0000000000..34c4552c56
--- /dev/null
+++ b/packages/lab/src/BottomSheet/useSheetGestures.ts
@@ -0,0 +1,226 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useSheetGestures.ts
+ * @input Uses React (useCallback, useEffect, useMemo, useRef, useState)
+ * @output Exports useSheetGestures hook and its option/result types
+ * @position Internal to BottomSheet; not exported from the lab entry point
+ *
+ * Drag-to-dismiss machinery for the bottom sheet. Tracks a pointer drag
+ * down the block axis, translates the sliding surface live, and on release
+ * either dismisses (past a distance or velocity threshold) or springs back
+ * to fully open. Pointer-events based so one code path covers mouse + touch.
+ *
+ * Kept private to BottomSheet: the behavior is sheet-specific (a dismiss
+ * edge on a bottom-anchored surface). It is not a general primitive and is
+ * intentionally not exported.
+ *
+ * SSR-safe: no window/document access at module scope; all measurement
+ * happens inside handlers. Respects prefers-reduced-motion by skipping the
+ * settle transition.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
+ * - /packages/lab/src/BottomSheet/useSheetGestures.test.ts
+ */
+
+import {
+ useCallback,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ type CSSProperties,
+ type PointerEvent as ReactPointerEvent,
+} from 'react';
+
+// Fraction of the measured sheet height a drag must cross (with low
+// velocity) before release dismisses instead of springing back.
+const DISMISS_DISTANCE_RATIO = 0.25;
+// A quick flick past this speed (px/ms) dismisses regardless of distance.
+const DISMISS_VELOCITY = 0.5;
+
+export interface UseSheetGesturesOptions {
+ /** Whether the owning sheet is open. Drag state resets when it closes. */
+ isOpen: boolean;
+ /** Called when a drag crosses the dismiss threshold (distance or flick). */
+ onDismiss: () => void;
+}
+
+export interface SheetContentProps {
+ style: CSSProperties;
+}
+
+export interface SheetHandleProps {
+ style: CSSProperties;
+ onPointerDown: (event: ReactPointerEvent) => void;
+ onPointerMove: (event: ReactPointerEvent) => void;
+ onPointerUp: (event: ReactPointerEvent) => void;
+ onPointerCancel: (event: ReactPointerEvent) => void;
+}
+
+export interface UseSheetGesturesResult {
+ /** Spread on the sliding surface: live translate + touch-action guard. */
+ contentProps: SheetContentProps;
+ /** Spread on the grab-handle element: pointer drag handlers. */
+ handleProps: SheetHandleProps;
+ /** Current live drag offset in px (positive = dragged toward the edge). */
+ dragOffset: number;
+ /** Whether a drag is currently in progress. */
+ isDragging: boolean;
+}
+
+function prefersReducedMotion(): boolean {
+ if (typeof window === 'undefined' || !window.matchMedia) {
+ return false;
+ }
+ return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * Drag-to-dismiss machinery for the bottom sheet. Returns props to spread on
+ * the grab handle and the sliding surface, plus live drag state for callers
+ * that want to drive their own animation.
+ *
+ * @example
+ * ```
+ * const {contentProps, handleProps} = useSheetGestures({
+ * isOpen,
+ * onDismiss: () => onOpenChange(false),
+ * });
+ * <div {...contentProps}>
+ * <div {...handleProps} />
+ * {children}
+ * </div>
+ * ```
+ */
+export function useSheetGestures({
+ isOpen,
+ onDismiss,
+}: UseSheetGesturesOptions): UseSheetGesturesResult {
+ const [dragOffset, setDragOffset] = useState(0);
+ const [isDragging, setIsDragging] = useState(false);
+
+ // Latest callback ref so pointer handlers stay stable across renders.
+ const onDismissRef = useRef(onDismiss);
+ useEffect(() => {
+ onDismissRef.current = onDismiss;
+ });
+
+ // Live drag bookkeeping (refs so pointermove doesn't churn renders).
+ const dragStateRef = useRef<{
+ pointerId: number;
+ startCoord: number;
+ lastCoord: number;
+ lastTime: number;
+ velocity: number;
+ height: number;
+ } | null>(null);
+
+ // Reset drag state each time the sheet re-opens.
+ useEffect(() => {
+ if (isOpen) {
+ setDragOffset(0);
+ setIsDragging(false);
+ }
+ }, [isOpen]);
+
+ const measureHeight = useCallback((el: HTMLElement | null): number => {
+ const sheet = el?.closest<HTMLElement>('[data-astryx-sheet]') ?? el;
+ return sheet?.getBoundingClientRect().height ?? 0;
+ }, []);
+
+ const settleFromDrag = useCallback(
+ (offset: number, velocity: number, height: number) => {
+ const dismiss =
+ offset > height * DISMISS_DISTANCE_RATIO || velocity > DISMISS_VELOCITY;
+ if (dismiss) {
+ onDismissRef.current();
+ return;
+ }
+ // Below threshold: spring back to fully open.
+ setDragOffset(0);
+ },
+ [],
+ );
+
+ const handlePointerDown = useCallback(
+ (event: ReactPointerEvent) => {
+ const target = event.currentTarget as HTMLElement;
+ target.setPointerCapture?.(event.pointerId);
+ dragStateRef.current = {
+ pointerId: event.pointerId,
+ startCoord: event.clientY,
+ lastCoord: event.clientY,
+ lastTime: event.timeStamp,
+ velocity: 0,
+ height: measureHeight(target),
+ };
+ setIsDragging(true);
+ },
+ [measureHeight],
+ );
+
+ const handlePointerMove = useCallback((event: ReactPointerEvent) => {
+ const state = dragStateRef.current;
+ if (!state || state.pointerId !== event.pointerId) {
+ return;
+ }
+ // Dragging DOWN (increasing Y) collapses/dismisses. Only allow drag in
+ // the closing direction past the fully-open position (no overscroll).
+ const delta = event.clientY - state.startCoord;
+ const dt = event.timeStamp - state.lastTime;
+ if (dt > 0) {
+ state.velocity = (event.clientY - state.lastCoord) / dt;
+ state.lastCoord = event.clientY;
+ state.lastTime = event.timeStamp;
+ }
+ setDragOffset(Math.max(0, delta));
+ }, []);
+
+ const endDrag = useCallback(
+ (event: ReactPointerEvent) => {
+ const state = dragStateRef.current;
+ if (!state || state.pointerId !== event.pointerId) {
+ return;
+ }
+ const target = event.currentTarget as HTMLElement;
+ target.releasePointerCapture?.(event.pointerId);
+ const offset = Math.max(0, event.clientY - state.startCoord);
+ dragStateRef.current = null;
+ setIsDragging(false);
+ settleFromDrag(offset, state.velocity, state.height || 1);
+ },
+ [settleFromDrag],
+ );
+
+ // Reduced motion skips the settle transition (snaps instantly).
+ const reducedMotion = useMemo(prefersReducedMotion, [isOpen]);
+
+ const contentProps = useMemo<SheetContentProps>(
+ () => ({
+ style: {
+ transform: dragOffset !== 0 ? `translateY(${dragOffset}px)` : undefined,
+ transition: isDragging || reducedMotion ? 'none' : undefined,
+ touchAction: 'none',
+ overscrollBehavior: 'contain',
+ },
+ }),
+ [dragOffset, isDragging, reducedMotion],
+ );
+
+ const handleProps = useMemo<SheetHandleProps>(
+ () => ({
+ style: {touchAction: 'none', cursor: 'grab'},
+ onPointerDown: handlePointerDown,
+ onPointerMove: handlePointerMove,
+ onPointerUp: endDrag,
+ onPointerCancel: endDrag,
+ }),
+ [handlePointerDown, handlePointerMove, endDrag],
+ );
+
+ return {contentProps, handleProps, dragOffset, isDragging};
+}
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
index f358e1a5bf..d13003bc88 100644
--- a/packages/lab/src/index.ts
+++ b/packages/lab/src/index.ts
@@ -35,6 +35,9 @@ export * from './Chat';
// Drawer — experimental overlay panel
export {Drawer, type DrawerProps} from './Drawer';
+// BottomSheet — mobile touch sheet built on the Drawer <dialog> engine
+export {BottomSheet, type BottomSheetProps} from './BottomSheet';
+
// Stat — experimental KPI/metric display
export {
Stat,