Skip to content

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

TypeScript

docs(lab): prepare Bottom Sheet for promotion (#5078)

Xinzi Zhouaeb66f5a3219
diff --git a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
index 60309412f2..49af24da83 100644
--- a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
+++ b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
@@ -3,7 +3,7 @@
export const docs = {
name: 'BottomSheet',
- displayName: 'BottomSheet',
+ displayName: 'Bottom Sheet',
group: 'BottomSheet',
category: 'Overlay',
keywords: [
@@ -22,6 +22,34 @@ export const docs = {
'mobile keyboard',
'visual viewport',
],
+ playground: {
+ overlay: true,
+ defaults: {
+ isOpen: false,
+ label: 'Filters',
+ height: 'hug',
+ children: {
+ __element: 'Section',
+ props: {padding: 4},
+ children: {
+ __element: 'VStack',
+ props: {gap: 2},
+ children: [
+ {
+ __element: 'Heading',
+ props: {level: 3},
+ children: 'Filters',
+ },
+ {
+ __element: 'Text',
+ props: {type: 'body'},
+ children: 'Adjust the properties below, then open the preview.',
+ },
+ ],
+ },
+ },
+ },
+ },
theming: {
targets: [{className: 'astryx-bottom-sheet', visualProps: []}],
},
@@ -77,7 +105,7 @@ export const docs = {
],
usage: {
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. Mobile-keyboard accommodation is supported only while Tall is fully expanded: the outer sheet remains stationary while visual-viewport overlap extends its internal scroll range and the body scrolls focused controls above the keyboard. Shorter Tall detents, Hug, Capped, numeric, and CSS-length heights do not automatically move or add keyboard scroll space. Actual Tall-sheet travel or closing dismisses the keyboard. Content padding clears the home indicator via env(safe-area-inset-bottom).',
+ 'A mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',
bestPractices: [
{
guidance: true,
@@ -87,32 +115,12 @@ export const docs = {
{
guidance: true,
description:
- 'Keep the caller as the source of truth: derive isOpen from state and clear it in onOpenChange.',
- },
- {
- guidance: true,
- description:
- 'Use BottomSheetSwitcher with a unique sheetId per sheet for multi-step flows; it owns one shared dialog while the new top sheet enters and a taller previous sheet simultaneously aligns downward behind a shorter step, then fades it afterward.',
- },
- {
- 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:
- "If a sheet contains a text-entry control that can bring up the mobile keyboard, use 'tall' and keep it fully expanded while editing. Its outer sheet stays stationary while the built-in body scrolls. Shorter Tall detents, Hug, Capped, numeric, and CSS-length heights do not provide keyboard-aware positioning or scroll space.",
- },
- {
- 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.',
+ "Pick the starting height that fits the content: 'hug' for short bounded content, 'capped' for lists, and 'tall' for forms or streaming/resizing content.",
},
{
guidance: false,
description:
- 'Use a BottomSheet for desktop inspectors or master-detail; use Drawer (side="end", hasScrim={false}) instead.',
+ "Don't make the sheet content overly long. Consider breaking it into steps and using Bottom Sheet Switcher.",
},
],
},
@@ -197,41 +205,22 @@ export const docsDense = {
'mobile touch sheet rising from the bottom edge (native <dialog>): grab handle, drag-to-resize snap points, swipe-to-dismiss, fully-expanded Tall visual-viewport mobile-keyboard handling, named height scale, modal (default) or non-modal (hasScrim={false}) presentation',
usage: {
description:
- 'Mobile surface for filters, actions, forms, 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. Only fully expanded Tall accommodates the mobile keyboard: its outer sheet stays stationary while its body gains scroll space and reveals focused controls. Shorter Tall detents, Hug, Capped, and custom heights do not move or add keyboard scroll space. Tall-sheet travel or closing dismisses the keyboard. Content clears the home indicator via safe-area inset.',
+ 'Mobile touch surface for filters, actions, forms, and detail views that should rise from the bottom of the viewport; use BottomSheetSwitcher for multi-step flows.',
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:
- 'Use BottomSheetSwitcher + sheetId for mutually exclusive multi-step flows in one shared dialog.',
- },
- {
- guidance: true,
- description:
- "Pick a height that fits: 'hug' for short content, 'capped' for lists, 'tall' for streaming content.",
- },
- {
- guidance: true,
- description:
- "If a sheet contains a text-entry control that can bring up the mobile keyboard, use 'tall' and keep it fully expanded while editing. Shorter Tall detents, Hug, Capped, numeric, and CSS-length heights are not keyboard-aware.",
+ 'Use for mobile-first surfaces (filters, share sheets, quick actions) where the content should rise from the bottom edge.',
},
{
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).',
+ "Pick the starting height that fits the content: 'hug' for short bounded content, 'capped' for lists, and 'tall' for forms or streaming/resizing content.",
},
{
guidance: false,
description:
- 'Use for desktop inspectors or master-detail; use Drawer instead.',
+ "Don't make the sheet content overly long. Consider breaking it into steps and using Bottom Sheet Switcher.",
},
],
},
diff --git a/packages/lab/src/BottomSheet/BottomSheet.test.tsx b/packages/lab/src/BottomSheet/BottomSheet.test.tsx
index 577d8e6523..00129b350c 100644
--- a/packages/lab/src/BottomSheet/BottomSheet.test.tsx
+++ b/packages/lab/src/BottomSheet/BottomSheet.test.tsx
@@ -183,7 +183,7 @@ function getHandle(): HTMLElement {
// 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}>) {
+function drag(handle: HTMLElement, points: {y: number}[]) {
const [down, ...rest] = points;
fireEvent.pointerDown(handle, {pointerId: 1, clientY: down.y});
for (const p of rest) {
@@ -764,7 +764,7 @@ describe('BottomSheet', () => {
expect(body.scrollTop).toBe(248);
viewport.height = 800;
- act(() => viewport.dispatchEvent(new Event('resize')));
+ void act(() => viewport.dispatchEvent(new Event('resize')));
expect(body.style.getPropertyValue('--_sheet-keyboard-inset')).toBe(
'0px',
);
@@ -881,7 +881,7 @@ describe('BottomSheet', () => {
focus.mockRestore();
input.focus();
- act(() => viewport.dispatchEvent(new Event('resize')));
+ void act(() => viewport.dispatchEvent(new Event('resize')));
expect(body.style.getPropertyValue('--_sheet-keyboard-inset')).toBe(
'0px',
@@ -929,7 +929,7 @@ describe('BottomSheet', () => {
fireEvent.pointerDown(input, {pointerId: 1, clientY: 200});
body.scrollTop = 120;
fireEvent.focus(input, {relatedTarget: null});
- act(() => viewport.dispatchEvent(new Event('resize')));
+ void act(() => viewport.dispatchEvent(new Event('resize')));
expect(body.scrollTop).toBe(120);
expect(focus).not.toHaveBeenCalled();
@@ -1089,7 +1089,7 @@ describe('BottomSheet', () => {
expect(body.scrollTop).toBe(248);
viewport.height = 800;
- act(() => viewport.dispatchEvent(new Event('resize')));
+ void act(() => viewport.dispatchEvent(new Event('resize')));
expect(body.style.getPropertyValue('--_sheet-keyboard-inset')).toBe(
'0px',
);
@@ -1129,7 +1129,7 @@ describe('BottomSheet', () => {
);
viewport.height = 800;
- act(() => viewport.dispatchEvent(new Event('resize')));
+ void act(() => viewport.dispatchEvent(new Event('resize')));
expect(body.style.getPropertyValue('--_sheet-keyboard-inset')).toBe(
'0px',
);
@@ -1172,7 +1172,7 @@ describe('BottomSheet', () => {
);
viewport.height = 800;
- act(() => viewport.dispatchEvent(new Event('resize')));
+ void act(() => viewport.dispatchEvent(new Event('resize')));
expect(body.style.getPropertyValue('--_sheet-keyboard-inset')).toBe(
'0px',
);
@@ -1217,7 +1217,7 @@ describe('BottomSheet', () => {
);
viewport.height = 800;
- act(() => viewport.dispatchEvent(new Event('resize')));
+ void act(() => viewport.dispatchEvent(new Event('resize')));
expect(body.style.getPropertyValue('--_sheet-keyboard-inset')).toBe(
'0px',
);
diff --git a/packages/lab/src/BottomSheet/BottomSheetPanel.test.tsx b/packages/lab/src/BottomSheet/BottomSheetPanel.test.tsx
index 8888400d67..6b4a800301 100644
--- a/packages/lab/src/BottomSheet/BottomSheetPanel.test.tsx
+++ b/packages/lab/src/BottomSheet/BottomSheetPanel.test.tsx
@@ -198,9 +198,9 @@ describe('BottomSheetPanel', () => {
</BottomSheetPanel>,
);
- act(() => vi.advanceTimersByTime(649));
+ void act(() => vi.advanceTimersByTime(649));
expect(onMotionComplete).not.toHaveBeenCalled();
- act(() => vi.advanceTimersByTime(1));
+ void act(() => vi.advanceTimersByTime(1));
expect(onMotionComplete).toHaveBeenCalledWith('entering');
} finally {
vi.useRealTimers();
diff --git a/packages/lab/src/BottomSheet/BottomSheetSwitcher.doc.mjs b/packages/lab/src/BottomSheet/BottomSheetSwitcher.doc.mjs
index bc133d4c68..20ad2768d5 100644
--- a/packages/lab/src/BottomSheet/BottomSheetSwitcher.doc.mjs
+++ b/packages/lab/src/BottomSheet/BottomSheetSwitcher.doc.mjs
@@ -3,7 +3,7 @@
export const docs = {
name: 'BottomSheetSwitcher',
- displayName: 'BottomSheetSwitcher',
+ displayName: 'Bottom Sheet Switcher',
group: 'BottomSheet',
category: 'Overlay',
keywords: ['bottom sheet', 'switcher', 'multi-step', 'flow', 'wizard'],
@@ -16,7 +16,7 @@ export const docs = {
],
},
description:
- 'Coordinates multiple BottomSheets as a mutually exclusive flow. One activeSheet ID selects the only interactive sheet; during a handoff, the new sheet enters above the inert previous sheet. If the new sheet is shorter, the previous sheet simultaneously moves down until their top edges align, then fades after both transforms complete. The switcher owns one shared native <dialog>: modal flows call showModal() once for one top-layer boundary and one ::backdrop across the whole flow, while no-scrim flows use a non-modal show() shell.',
+ 'Coordinates multiple BottomSheets as a mutually exclusive flow. One activeSheet ID selects the only interactive sheet; during a handoff, the new sheet enters above the inert previous sheet. If the new sheet is shorter, the previous sheet simultaneously moves down until their top edges align, then fades after both transforms complete. The switcher owns one shared native <dialog>: modal flows call showModal() once for one top-layer boundary and one ::backdrop across the whole flow, while no-scrim flows use a non-modal show() shell. Its ref and shared DOM props target that dialog.',
props: [
{
name: 'activeSheet',
@@ -27,7 +27,7 @@ export const docs = {
},
{
name: 'onActiveSheetChange',
- type: '(sheetId: string | null) => void',
+ type: '(activeSheet: string | null) => void',
description:
'Called with null when the active sheet dismisses. The same state setter can be used by flow controls to switch to another sheet ID.',
required: true,
@@ -48,48 +48,23 @@ export const docs = {
],
usage: {
description:
- 'Use one activeSheet value as the source of truth for a multi-step bottom-sheet flow. Set it to a child sheetId to open or switch steps, and set it to null to close. On a handoff, the previous sheet becomes inert immediately while the new active sheet enters above it. A taller previous sheet simultaneously moves down until its top edge aligns with the shorter new sheet; it fades only after both transforms complete. Equal-height or shorter previous sheets stay stationary and fade after the entrance. The switcher keeps one shared dialog open across the transition, with one modal boundary, native backdrop, focus trap, and body scroll lock when hasScrim is true, and restores focus to the trigger that started the flow after the final exit finishes.',
+ "Coordinates a multi-step bottom-sheet flow in one shared dialog; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
bestPractices: [
{
guidance: true,
description:
- 'Give every nested BottomSheet a stable, unique sheetId and model the flow as one activeSheet value.',
- },
- {
- guidance: true,
- description:
- 'Keep state local to the sheet that owns it; lift only data that another sheet needs.',
- },
- {
- guidance: true,
- description:
- "Treat each switcher sheet's content as a new ownership scope. A BottomSheet opened from that content is standalone; wrap it in a nested BottomSheetSwitcher when it starts another multi-step flow.",
- },
- {
- guidance: true,
- description:
- 'Configure hasScrim on BottomSheetSwitcher, not its individual BottomSheet children, so the modal layer remains stable across handoffs.',
- },
- {
- guidance: true,
- description:
- 'When hasScrim is false, keep the switcher outside transformed, contained, and overflow-clipping ancestors so its non-modal dialog can remain viewport-aligned.',
- },
- {
- guidance: true,
- description:
- 'Treat activeSheet as the interaction state: a previous sheet can remain visually present and move beneath the entering sheet, but it is inert and hidden from assistive technology.',
+ 'Use when each step depends on the previous one and only one step needs attention at a time.',
},
{
guidance: false,
description:
- 'Use separate isOpen booleans for sheets in the same flow; they can drift and request overlapping dialogs.',
+ "Don't split information across sheets when people need to compare it; use a full-page layout that keeps the relevant content visible together instead.",
},
],
},
examples: [
{
- label: 'Two-step flow',
+ label: 'Three-step flow',
code: `const [activeSheet, setActiveSheet] = useState(null);
<>
@@ -97,11 +72,18 @@ export const docs = {
<BottomSheetSwitcher
activeSheet={activeSheet}
onActiveSheetChange={setActiveSheet}>
- <BottomSheet sheetId="details" label="Details">
- <Button label="Continue" onClick={() => setActiveSheet('confirm')} />
+ <BottomSheet sheetId="details" label="Details" height="hug">
+ <SetupDetails />
+ <Button label="Continue" onClick={() => setActiveSheet('preferences')} />
</BottomSheet>
- <BottomSheet sheetId="confirm" label="Confirm">
+ <BottomSheet sheetId="preferences" label="Preferences" height="hug">
+ <Preferences />
<Button label="Back" onClick={() => setActiveSheet('details')} />
+ <Button label="Continue" onClick={() => setActiveSheet('confirm')} />
+ </BottomSheet>
+ <BottomSheet sheetId="confirm" label="Confirm" height="hug">
+ <Confirmation />
+ <Button label="Back" onClick={() => setActiveSheet('preferences')} />
<Button label="Done" onClick={() => setActiveSheet(null)} />
</BottomSheet>
</BottomSheetSwitcher>
@@ -116,24 +98,17 @@ export const docsDense = {
'controller with one shared native dialog for mutually exclusive multi-step BottomSheets',
usage: {
description:
- 'One activeSheet ID makes one nested sheet interactive in one shared dialog. Change IDs to enter a new top sheet while simultaneously aligning a taller previous sheet behind a shorter one, then fade it; null closes the flow.',
+ "Coordinates a multi-step bottom-sheet flow in one shared dialog; set activeSheet to a nested BottomSheet's sheetId to open or switch steps, and to null to close.",
bestPractices: [
- {
- guidance: true,
- description: 'Use stable, unique sheetId values for every child.',
- },
- {
- guidance: true,
- description: "Let the switcher own the flow's one shared scrim.",
- },
{
guidance: true,
description:
- 'Nested sheets start a new standalone or nested-switcher scope.',
+ 'Use when each step depends on the previous one and only one step needs attention at a time.',
},
{
guidance: false,
- description: 'Coordinate a single flow with separate open booleans.',
+ description:
+ "Don't split information across sheets when people need to compare it; use a full-page layout that keeps the relevant content visible together instead.",
},
],
},
diff --git a/packages/lab/src/BottomSheet/BottomSheetSwitcher.tsx b/packages/lab/src/BottomSheet/BottomSheetSwitcher.tsx
index 386442e46e..8ebfbfede0 100644
--- a/packages/lab/src/BottomSheet/BottomSheetSwitcher.tsx
+++ b/packages/lab/src/BottomSheet/BottomSheetSwitcher.tsx
@@ -17,7 +17,7 @@
*
* All child sheets render as panels inside one switcher-owned `<dialog>`. A
* scrim flow calls showModal() once and keeps that native top-layer dialog open
- * across every handoff. A no-scrim flow calls show() on the same inline shell.
+ * across every handoff. A no-scrim flow calls show() on the same non-modal shell.
* This keeps one modal boundary and one native ::backdrop without a portal.
*
* SYNC: When modified, update these files to stay in sync:
@@ -191,7 +191,7 @@ export interface BottomSheetSwitcherProps extends BaseProps<HTMLDialogElement> {
/**
* Whether to open the shared dialog modally with its native ::backdrop.
- * Disable for an inline, non-modal flow over an interactive page.
+ * Disable for a viewport-anchored, non-modal flow over an interactive page.
* @default true
*/
hasScrim?: boolean;
diff --git a/packages/lab/src/BottomSheet/index.ts b/packages/lab/src/BottomSheet/index.ts
index 87d0c132a7..f464c5eff2 100644
--- a/packages/lab/src/BottomSheet/index.ts
+++ b/packages/lab/src/BottomSheet/index.ts
@@ -1,5 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+'use client';
+
/**
* @file index.ts
* @input BottomSheet.tsx, BottomSheetSwitcher.tsx
@@ -8,6 +10,6 @@
*/
export {BottomSheet} from './BottomSheet';
-export type {BottomSheetProps} from './BottomSheet';
+export type {BottomSheetHeight, BottomSheetProps} from './BottomSheet';
export {BottomSheetSwitcher} from './BottomSheetSwitcher';
export type {BottomSheetSwitcherProps} from './BottomSheetSwitcher';
diff --git a/packages/lab/src/BottomSheet/snapOffsets.ts b/packages/lab/src/BottomSheet/snapOffsets.ts
index 0a9156785f..f39b024df3 100644
--- a/packages/lab/src/BottomSheet/snapOffsets.ts
+++ b/packages/lab/src/BottomSheet/snapOffsets.ts
@@ -25,7 +25,7 @@ export const DETENT_DEDUP_PX = 48;
/** Resolve snap points given as viewport fractions (0, 1] to px heights. */
export function snapFractionsToHeights(
- fractions: readonly number[],
+ fractions: ReadonlyArray<number>,
viewportPx: number,
): number[] {
return fractions.filter(f => f > 0 && f <= 1).map(f => f * viewportPx);
@@ -44,7 +44,7 @@ export function snapFractionsToHeights(
*/
export function computeDetentOffsets(
sheetHeight: number,
- detentHeights: readonly number[],
+ detentHeights: ReadonlyArray<number>,
dedupPx: number = DETENT_DEDUP_PX,
): number[] {
const collapsed = detentHeights
@@ -65,7 +65,7 @@ export function computeDetentOffsets(
/** Nearest value in `offsets` to `value` (offsets must be non-empty). */
export function nearestOffset(
value: number,
- offsets: readonly number[],
+ offsets: ReadonlyArray<number>,
): number {
return offsets.reduce(
(best, o) => (Math.abs(o - value) < Math.abs(best - value) ? o : best),
@@ -92,7 +92,7 @@ export const MIN_PEEK_SCRIM_OPACITY = 0.3;
*/
export function scrimOpacityForOffset(
offset: number,
- offsets: readonly number[],
+ offsets: ReadonlyArray<number>,
dismissOffset: number,
): number {
const shortest = offsets[offsets.length - 1];
@@ -119,7 +119,7 @@ export function scrimOpacityForOffset(
*/
export function resolveSettleOffset(
value: number,
- offsets: readonly number[],
+ offsets: ReadonlyArray<number>,
dir: number,
baseOffset: number,
): number {
diff --git a/packages/lab/src/BottomSheet/useMobileKeyboard.ts b/packages/lab/src/BottomSheet/useMobileKeyboard.ts
index 4cdec8557f..c93fc872b6 100644
--- a/packages/lab/src/BottomSheet/useMobileKeyboard.ts
+++ b/packages/lab/src/BottomSheet/useMobileKeyboard.ts
@@ -48,11 +48,11 @@ interface KeyboardGeometry {
interface FocusScrollSnapshot {
target: HTMLElement;
- elements: Array<{
+ elements: {
element: HTMLElement;
scrollLeft: number;
scrollTop: number;
- }>;
+ }[];
windowX: number;
windowY: number;
}
@@ -99,7 +99,7 @@ function isIOSWebKit(): boolean {
const userAgent = window.navigator.userAgent;
return (
/iPad|iPhone|iPod/.test(userAgent) ||
- (/Macintosh/.test(userAgent) && window.navigator.maxTouchPoints > 1)
+ (userAgent.includes('Macintosh') && window.navigator.maxTouchPoints > 1)
);
}
@@ -111,7 +111,9 @@ function isTextEntryControl(element: Element | null): element is HTMLElement {
return (
!element.disabled &&
!element.readOnly &&
- !NON_TEXT_INPUT_TYPES.has(element.type)
+ !NON_TEXT_INPUT_TYPES.has(
+ (element.getAttribute('type') ?? 'text').toLowerCase(),
+ )
);
}
return (
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs b/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
deleted file mode 100644
index 519676b4c0..0000000000
--- a/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
+++ /dev/null
@@ -1,32 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
-export const docs = {
- name: 'useSheetGestures',
- displayName: 'useSheetGestures',
- keywords: ['sheet', 'drag', 'swipe', 'snap', 'detent', 'dismiss', 'gesture', 'pointer', 'touch', 'bottom sheet'],
- params: [
- {
- name: 'options',
- type: 'UseSheetGesturesOptions',
- description: 'isOpen, onDismiss, optional snapHeights (candidate detent heights in px), onSnap, and onScrimOpacity (the scrim opacity to show, fading from 1 toward a faint floor as the sheet collapses onto its peek detent, for a glance affordance). 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, settledOffset, and isDragging for callers that want to drive their own animation.',
- },
- ],
- usage: {
- description:
- 'Drag + snap machinery for the bottom sheet. A slow drag on the handle resizes the sheet live and, on release, settles to the nearest snap detent; a fast downward flick dismisses (swipe-to-close); a fast upward flick expands to the tallest detent. The measured sheet height is always the tallest detent, and snapHeights add shorter rest points beneath it. 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 dismiss 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: true, description: 'Pass snapHeights in px relative to the viewport; the hook filters out any that are >= the measured sheet height.' },
- { guidance: false, description: 'Wire onDismiss to anything other than the owning sheet close; it fires on a swipe-to-close or a drag past the shortest detent.' },
- ],
- },
-};
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.test.ts b/packages/lab/src/BottomSheet/useSheetGestures.test.ts
index e77ab6e950..24765b7754 100644
--- a/packages/lab/src/BottomSheet/useSheetGestures.test.ts
+++ b/packages/lab/src/BottomSheet/useSheetGestures.test.ts
@@ -68,7 +68,7 @@ function setup(options: Partial<UseSheetGesturesOptions> = {}) {
isOpen: true,
onDismiss,
...options,
- } as UseSheetGesturesOptions,
+ },
},
);
return {hook, onDismiss};
@@ -201,7 +201,7 @@ describe('useSheetGestures', () => {
move(hook, 60, 200, t); // offset 60, above the mid detent -> full
move(hook, 150, 600, t); // offset 150, halfway -> between 1 and 0.3 (~0.65)
move(hook, 220, 1000, t); // offset 220, past the peek -> peek floor
- const values = onScrimOpacity.mock.calls.map(c => c[0]);
+ const values = onScrimOpacity.mock.calls.map(c => Number(c[0]));
expect(values[0]).toBe(1);
expect(values[1]).toBeGreaterThan(0.55);
expect(values[1]).toBeLessThan(0.75);
@@ -220,7 +220,7 @@ describe('useSheetGestures', () => {
expect(hook.result.current.settledOffset).toBe(200);
// Last reported opacity (on settle) is the peek floor, not fully hidden —
// the sheet is still modal, so the backdrop keeps a minimum dim.
- const values = onScrimOpacity.mock.calls.map(c => c[0]);
+ const values = onScrimOpacity.mock.calls.map(c => Number(c[0]));
expect(values[values.length - 1]).toBeCloseTo(0.3);
});
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.ts b/packages/lab/src/BottomSheet/useSheetGestures.ts
index 67c1cfc9c8..a84bea9e1f 100644
--- a/packages/lab/src/BottomSheet/useSheetGestures.ts
+++ b/packages/lab/src/BottomSheet/useSheetGestures.ts
@@ -506,7 +506,7 @@ export function useSheetGestures({
top: boolean;
bottom: boolean;
} | null>(null);
- const prevTouchHandlers = useRef<{
+ const previousTouchHandlersRef = useRef<{
start: (e: TouchEvent) => void;
move: (e: TouchEvent) => void;
end: (e: TouchEvent) => void;
@@ -615,8 +615,8 @@ export function useSheetGestures({
};
const prev = bodyNodeRef.current;
- if (prev && prevTouchHandlers.current) {
- const h = prevTouchHandlers.current;
+ if (prev && previousTouchHandlersRef.current) {
+ const h = previousTouchHandlersRef.current;
prev.removeEventListener('touchstart', h.start);
prev.removeEventListener('touchmove', h.move);
prev.removeEventListener('touchend', h.end);
@@ -628,17 +628,17 @@ export function useSheetGestures({
node.addEventListener('touchmove', onTouchMove, {passive: false});
node.addEventListener('touchend', onTouchEnd, {passive: true});
node.addEventListener('touchcancel', onTouchEnd, {passive: true});
- prevTouchHandlers.current = {
+ previousTouchHandlersRef.current = {
start: onTouchStart,
move: onTouchMove,
end: onTouchEnd,
};
} else {
- prevTouchHandlers.current = null;
+ previousTouchHandlersRef.current = null;
}
}, []);
- const reducedMotion = useMemo(prefersReducedMotion, [isOpen]);
+ const reducedMotion = useMemo(() => prefersReducedMotion(), [isOpen]);
// While dragging, follow the finger; otherwise rest at the settled detent.
const activeOffset = isDragging ? dragOffset : settledOffset;
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
index f4f019d42b..ef7c62cc41 100644
--- a/packages/lab/src/index.ts
+++ b/packages/lab/src/index.ts
@@ -48,6 +48,7 @@ export {Drawer, type DrawerProps} from './Drawer';
// BottomSheet — mobile touch sheet on a native modal <dialog>
export {
BottomSheet,
+ type BottomSheetHeight,
type BottomSheetProps,
BottomSheetSwitcher,
type BottomSheetSwitcherProps,