Skip to content

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

TypeScript

feat(lab): add non-modal BottomSheet variant and refine scrim (#4706)

rubyycheung0bca68f8daaa
diff --git a/apps/storybook/stories/BottomSheet.stories.tsx b/apps/storybook/stories/BottomSheet.stories.tsx
index 37c6bc720a..42073f5261 100644
--- a/apps/storybook/stories/BottomSheet.stories.tsx
+++ b/apps/storybook/stories/BottomSheet.stories.tsx
@@ -19,6 +19,15 @@ const meta: Meta<typeof BottomSheet> = {
tags: ['autodocs'],
parameters: {
layout: 'fullscreen',
+ // Render each story in its own iframe in the Docs page. BottomSheet is a
+ // viewport-anchored overlay (position:fixed, dvh heights, detents from
+ // visualViewport); an iframe gives it a real mini-viewport, so both the
+ // modal (top-layer) and non-modal sheets render contained and with correct
+ // physics — instead of a modal escaping to cover the whole Docs page while
+ // a non-modal gets trapped/janky in the preview card.
+ docs: {
+ story: {inline: false, height: '560px'},
+ },
},
decorators: [
Story => (
@@ -91,6 +100,60 @@ export const TallSheet: Story = {
},
};
+export const NonModal: Story = {
+ render: () => {
+ const [isOpen, setIsOpen] = useState(false);
+ const [count, setCount] = useState(0);
+ return (
+ <>
+ {/* With hasScrim={false} the sheet is non-modal: this background stays
+ clickable while the sheet is open (no scrim, no scroll lock). Open
+ the sheet, then tap the counter — it still responds. The story
+ renders in its own iframe in Docs (see meta docs.story), so the
+ sheet gets a real mini-viewport and behaves correctly. */}
+ <VStack gap={3}>
+ <Heading level={3}>Live page (background)</Heading>
+ <Text type="supporting" color="secondary">
+ A non-modal sheet (hasScrim={'{false}'}) leaves this content
+ interactive. Open the sheet, then tap the counter below — it keeps
+ working, and there is no dimming behind the sheet.
+ </Text>
+ <Button label="Open sheet" onClick={() => setIsOpen(true)} />
+ <Button
+ label={`Background clicks: ${count}`}
+ onClick={() => setCount(c => c + 1)}
+ />
+ </VStack>
+ <BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Nearby places"
+ hasScrim={false}
+ height="capped">
+ <Section padding={4}>
+ <VStack gap={3}>
+ <Heading level={3}>Non-modal sheet</Heading>
+ <Text type="supporting" color="secondary">
+ No scrim; the page behind stays live. Drag the handle to resize,
+ flick down to dismiss, or press Escape while focus is here.
+ </Text>
+ <Divider />
+ {Array.from({length: 8}, (_, 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 HugHeight: Story = {
render: () => {
const [isOpen, setIsOpen] = useState(false);
diff --git a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
index 4440d58223..d61ca7e989 100644
--- a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
+++ b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs
@@ -44,13 +44,20 @@ export const docs = {
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 modal scrim 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 uses show(): a non-modal sheet with no scrim, leaving the page behind interactive and scrollable (like Material's standard bottom sheet or an iOS undimmed detent). 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 fades out as the sheet collapses onto its shortest "peek" detent, so a glance-height sheet reveals the content behind it (the sheet stays modal; the background is inert until dismissed). 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. 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).',
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} (non-modal, no scrim) for a peek surface that must coexist with a live page behind it (e.g. a panel over a map); keep the default (hasScrim) 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.' },
],
},
@@ -85,6 +92,17 @@ export const docs = {
label="Share"
height="hug">
<ShareActions />
+</BottomSheet>`,
+ },
+ {
+ label: 'Non-modal sheet (no scrim) — page stays interactive',
+ code: `const [isOpen, setIsOpen] = useState(true);
+<BottomSheet
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ label="Nearby places"
+ hasScrim={false}>
+ <PlaceList />
</BottomSheet>`,
},
],
@@ -92,13 +110,14 @@ export const docs = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsDense = {
- description: 'mobile touch sheet rising from the bottom edge (native modal <dialog>): grab handle, drag-to-resize snap points, swipe-to-dismiss, named height scale',
+ 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.',
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 non-modal peek over a live page; default (hasScrim) 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 ee4e6b6132..ba02360613 100644
--- a/packages/lab/src/BottomSheet/BottomSheet.test.tsx
+++ b/packages/lab/src/BottomSheet/BottomSheet.test.tsx
@@ -147,6 +147,99 @@ describe('BottomSheet', () => {
expect(onOpenChange).not.toHaveBeenCalled();
});
+ describe('hasScrim={false} (non-modal)', () => {
+ it('opens non-modally: show() instead of showModal(), no aria-modal', () => {
+ render(
+ <BottomSheet
+ isOpen
+ onOpenChange={() => {}}
+ label="Filters"
+ hasScrim={false}>
+ Content
+ </BottomSheet>,
+ );
+ expect(HTMLDialogElement.prototype.show).toHaveBeenCalled();
+ expect(HTMLDialogElement.prototype.showModal).not.toHaveBeenCalled();
+ expect(screen.getByRole('dialog')).not.toHaveAttribute('aria-modal');
+ });
+
+ it('does not dismiss when the shell (dialog element itself) is clicked', () => {
+ // No scrim: a tap on the transparent shell must pass through to the page,
+ // not dismiss the sheet.
+ const onOpenChange = vi.fn();
+ render(
+ <BottomSheet
+ isOpen
+ onOpenChange={onOpenChange}
+ label="Filters"
+ hasScrim={false}>
+ Content
+ </BottomSheet>,
+ );
+ fireEvent.click(screen.getByRole('dialog'));
+ expect(onOpenChange).not.toHaveBeenCalled();
+ });
+
+ it('still closes on Escape while focus is inside', () => {
+ const onOpenChange = vi.fn();
+ render(
+ <BottomSheet
+ isOpen
+ onOpenChange={onOpenChange}
+ label="Filters"
+ hasScrim={false}>
+ Content
+ </BottomSheet>,
+ );
+ fireEvent.keyDown(screen.getByRole('dialog'), {key: 'Escape'});
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+
+ it('still dismisses on a downward swipe past the threshold', () => {
+ const onOpenChange = vi.fn();
+ render(
+ <BottomSheet
+ isOpen
+ onOpenChange={onOpenChange}
+ label="Filters"
+ hasScrim={false}>
+ Content
+ </BottomSheet>,
+ );
+ drag(getHandle(), [{y: 0}, {y: 40}, {y: 120}]);
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+
+ it('does not steal focus onto the panel on open', () => {
+ render(
+ <BottomSheet
+ isOpen
+ onOpenChange={() => {}}
+ label="Filters"
+ hasScrim={false}>
+ <button type="button">First action</button>
+ </BottomSheet>,
+ );
+ // The background stays interactive, so the sheet must not grab focus.
+ expect(document.activeElement).not.toBe(getSheet());
+ });
+
+ it('still honors a descendant with data-autofocus', () => {
+ render(
+ <BottomSheet
+ isOpen
+ onOpenChange={() => {}}
+ label="Filters"
+ hasScrim={false}>
+ <input data-autofocus aria-label="Search" />
+ </BottomSheet>,
+ );
+ expect(document.activeElement).toBe(
+ screen.getByRole('textbox', {name: 'Search'}),
+ );
+ });
+ });
+
describe('grab handle', () => {
it('renders a decorative handle hidden from assistive tech', () => {
render(
diff --git a/packages/lab/src/BottomSheet/BottomSheet.tsx b/packages/lab/src/BottomSheet/BottomSheet.tsx
index 6db313aa8d..af50fb77cf 100644
--- a/packages/lab/src/BottomSheet/BottomSheet.tsx
+++ b/packages/lab/src/BottomSheet/BottomSheet.tsx
@@ -9,7 +9,7 @@
* @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: grab handle, snap
- * points, and swipe-to-dismiss. It owns a native modal `<dialog>` directly and
+ * points, and swipe-to-dismiss. It owns a native `<dialog>` directly and
* composes core primitives (`useScrollLock`, `<dialog>.showModal()` for the
* top layer + focus trap, a `::backdrop` scrim) rather than delegating to a
* heavier overlay component — so it controls its own sizing and can render a
@@ -17,6 +17,12 @@
* That shell is what lets the sheet translate freely (including a little past
* fully-open) without clipping against a fixed dialog edge.
*
+ * `hasScrim` picks the presentation: `true` (default) uses `showModal()` (top
+ * 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).
+ *
* The drag/snap/dismiss machinery lives in `useSheetGestures`; the offset
* geometry lives in the pure, tested `snapOffsets` module. Both are internal
* to BottomSheet and not exported from the lab entry point.
@@ -44,6 +50,12 @@ import {useDevWarning, useScrollLock} from '@astryxdesign/core/hooks';
import {mergeProps, mergeRefs, themeProps} from '@astryxdesign/core/utils';
import {useSheetGestures} from './useSheetGestures';
+// A non-modal sheet (hasScrim={false}) uses show() instead of showModal(), so
+// it isn't in the native top layer and needs an explicit z-index to sit above
+// page content. No z-index token exists in the theme; 1000 matches the Drawer
+// / app-level overlay convention.
+const NON_MODAL_Z = 1000;
+
// Detent fractions of the viewport, ascending (peek / mid / full). Detents
// that land within DETENT_DEDUP_PX of each other (e.g. a hug height next to a
// snap) are de-duped in the gesture hook, and any taller than the sheet are
@@ -111,12 +123,36 @@ const styles = stylex.create({
dialogOpen: {
display: 'block',
},
+ // Non-modal (hasScrim={false}) shell: the full-viewport dialog must NOT
+ // intercept taps, or it would swallow every click meant for the interactive
+ // page behind it. Pointer events pass straight through the transparent shell
+ // (and the positioner, which is already none) to the page; the sheet surface
+ // re-enables them (styles.sheet -> pointerEvents:auto). This also inherently
+ // removes tap-outside-to-dismiss, which is correct when there's no scrim.
+ // show() doesn't use the native top layer, so an explicit z-index keeps the
+ // sheet above page content.
+ //
+ // Size to 100% (of the positioning context) rather than the base 100dvw/dvh:
+ // a modal sheet is in the top layer so its `fixed` box is always the viewport,
+ // but a non-modal `show()` dialog is a normal `fixed` element, so if any
+ // ancestor establishes a containing block (transform / filter / contain —
+ // e.g. Storybook's Docs preview wrapper), viewport units measured from that
+ // shifted origin overflow and mis-anchor the sheet. `inset:0 + 100%` fills
+ // whatever the containing block is, so the sheet stays correctly anchored.
+ dialogNonModal: {
+ pointerEvents: 'none',
+ zIndex: NON_MODAL_Z,
+ width: '100%',
+ height: '100%',
+ },
// Opacity is a var the drag handler lowers toward dismissal;
// @starting-style animates the entrance fade-in.
+ // Plain dim, no backdrop blur: bottom sheets on both Material and iOS dim
+ // without blurring, so this intentionally diverges from the other overlays
+ // (Drawer/Dialog/MobileNav/Lightbox, which share a blur(2px) scrim).
scrim: {
'::backdrop': {
backgroundColor: colorVars['--color-overlay'],
- backdropFilter: 'blur(2px)',
opacity: {
default: 'var(--_sheet-scrim-opacity, 1)',
'@starting-style': 0,
@@ -256,17 +292,34 @@ export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
*/
height?: BottomSheetHeight | number | string;
+ /**
+ * Whether to render a modal scrim behind the sheet.
+ * - `true` (default) — `showModal()`: renders in the top layer with a focus
+ * trap, a `::backdrop` scrim, body scroll lock, and tap-scrim-to-dismiss.
+ * The background is inert. Use for focused tasks (filters, forms).
+ * - `false` — `show()`: a non-modal sheet with **no scrim**. The page behind
+ * stays interactive and scrollable (like Material's *standard* bottom
+ * sheet, or an iOS undimmed detent). Escape still closes while focus is
+ * inside the sheet, and drag/flick-to-dismiss still work. Use for a peek
+ * surface that coexists with the page (e.g. a panel over a live map).
+ * @default true
+ */
+ hasScrim?: boolean;
+
/** Test ID for the root element. */
'data-testid'?: string;
}
/**
* A mobile touch sheet that rises from the bottom edge, with a grab handle,
- * drag-to-resize snap points, and swipe-to-dismiss. It owns a native modal
- * `<dialog>` (top layer, focus trap, `::backdrop` scrim) and locks body scroll
- * while open; a slow drag settles to the nearest snap point, a flick down
- * dismisses, and Escape closes — so the swipe always has a keyboard
- * equivalent.
+ * drag-to-resize snap points, and swipe-to-dismiss. It owns a native
+ * `<dialog>` and, by default (`hasScrim`), enters the top layer with a focus
+ * trap + `::backdrop` scrim and locks body scroll; a slow drag settles to the
+ * nearest snap point, a flick down dismisses, and Escape closes — so the swipe
+ * always has a keyboard equivalent.
+ *
+ * With `hasScrim={false}` it opens non-modally (`show()`, no scrim), leaving
+ * the page behind interactive and scrollable.
*
* @example
* ```
@@ -286,6 +339,7 @@ export function BottomSheet({
label,
children,
height = 'capped',
+ hasScrim = true,
xstyle,
...props
}: BottomSheetProps) {
@@ -295,7 +349,7 @@ export function BottomSheet({
const close = useCallback(() => onOpenChange(false), [onOpenChange]);
// Set imperatively (not via state) so a 60fps drag doesn't re-render. The
- // hook reports the scrim opacity for the current detent (hidden at the peek).
+ // hook reports the scrim opacity for the current detent (a faint floor at the peek).
const handleScrimOpacity = useCallback((opacity: number) => {
dialogRef.current?.style.setProperty(
'--_sheet-scrim-opacity',
@@ -310,24 +364,32 @@ export function BottomSheet({
onScrimOpacity: handleScrimOpacity,
});
- // showModal() enters the top layer with a focus trap + ::backdrop; on close
- // we animate out (below) then restore focus to the opener.
+ // Modal: showModal() enters the top layer with a focus trap + ::backdrop and
+ // we restore focus to the opener on close. Standard: show() is non-modal, so
+ // we neither trap nor steal focus (the background stays interactive) — we
+ // only honor an explicit data-autofocus.
useEffect(() => {
const dialog = dialogRef.current;
if (!dialog) {
return;
}
if (isOpen) {
- triggerRef.current = document.activeElement as HTMLElement | null;
dialog.style.setProperty('--_sheet-scrim-opacity', '1');
if (!dialog.open) {
- dialog.showModal();
- // Override showModal()'s default (first tabbable) to land on the panel,
- // so AT reads from the label — unless a descendant sets data-autofocus.
+ // Only remember/restore focus for modal sheets; a non-modal sheet must
+ // not yank focus back from whatever the user does in the live page.
+ if (hasScrim) {
+ triggerRef.current = document.activeElement as HTMLElement | null;
+ dialog.showModal();
+ } else {
+ dialog.show();
+ }
+ // Land on the panel (so AT reads from the label) for modal sheets;
+ // otherwise only honor a descendant data-autofocus.
const autofocus = dialog.querySelector<HTMLElement>('[data-autofocus]');
if (autofocus) {
autofocus.focus();
- } else {
+ } else if (hasScrim) {
sheetNodeRef.current?.focus();
}
}
@@ -364,9 +426,11 @@ export function BottomSheet({
sheet?.removeEventListener('transitionend', onEnd);
};
}
- }, [isOpen]);
+ }, [isOpen, hasScrim]);
- useScrollLock(isOpen);
+ // Only a modal sheet locks body scroll; a non-modal sheet leaves the page
+ // scrollable behind it.
+ useScrollLock(isOpen && hasScrim);
// Enforce an accessible name: label is required by types, but a JS caller
// can still pass an empty string, leaving the sheet unnamed.
@@ -385,7 +449,8 @@ export function BottomSheet({
[close],
);
// Explicit Escape handler in addition to the native `cancel` event, for
- // environments that don't synthesize `cancel`.
+ // environments that don't synthesize `cancel` (and the show() path, which
+ // never fires `cancel`). Only fires when focus is inside the sheet.
const handleKeyDown = useCallback(
(event: React.KeyboardEvent<HTMLDialogElement>) => {
if (event.key === 'Escape') {
@@ -395,13 +460,16 @@ export function BottomSheet({
},
[close],
);
+ // Tap-outside-to-dismiss only applies to modal sheets (the scrim). A non-modal
+ // sheet has no scrim and its transparent shell is pointer-events:none, so taps
+ // pass through to the page rather than dismissing.
const handleClick = useCallback(
(event: React.MouseEvent<HTMLDialogElement>) => {
- if (event.target === event.currentTarget) {
+ if (hasScrim && event.target === event.currentTarget) {
close();
}
},
- [close],
+ [close, hasScrim],
);
const isNamed = typeof height === 'string' && height in HEIGHT_BUDGETS;
@@ -417,11 +485,14 @@ export function BottomSheet({
{...stylex.props(
styles.dialog,
isOpen && styles.dialogOpen,
- styles.scrim,
+ // 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,
+ !hasScrim && styles.dialogNonModal,
)}
ref={mergeRefs(ref, dialogRef)}
aria-label={label}
- aria-modal="true"
+ aria-modal={hasScrim ? 'true' : undefined}
onCancel={handleCancel}
onClick={handleClick}
onKeyDown={handleKeyDown}
diff --git a/packages/lab/src/BottomSheet/snapOffsets.test.ts b/packages/lab/src/BottomSheet/snapOffsets.test.ts
index 8c72b05ab9..24b672cc26 100644
--- a/packages/lab/src/BottomSheet/snapOffsets.test.ts
+++ b/packages/lab/src/BottomSheet/snapOffsets.test.ts
@@ -110,15 +110,21 @@ describe('scrimOpacityForOffset', () => {
expect(scrimOpacityForOffset(60, offsets, dismissOffset)).toBe(1);
});
- it('fades linearly from the mid detent to the peek', () => {
+ it('fades linearly from the mid detent toward the peek floor', () => {
+ // Halfway from mid (100) to peek (200), opacity is halfway from 1 to the
+ // 0.3 floor => 0.65.
expect(scrimOpacityForOffset(150, offsets, dismissOffset)).toBeCloseTo(
- 0.5,
+ 0.65,
);
});
- it('is hidden at or below the peek detent', () => {
- expect(scrimOpacityForOffset(200, offsets, dismissOffset)).toBe(0);
- expect(scrimOpacityForOffset(240, offsets, dismissOffset)).toBe(0);
+ it('thins to the peek floor at or below the peek detent (still modal)', () => {
+ expect(scrimOpacityForOffset(200, offsets, dismissOffset)).toBeCloseTo(
+ 0.3,
+ );
+ expect(scrimOpacityForOffset(240, offsets, dismissOffset)).toBeCloseTo(
+ 0.3,
+ );
});
});
diff --git a/packages/lab/src/BottomSheet/snapOffsets.ts b/packages/lab/src/BottomSheet/snapOffsets.ts
index ea2e1557ed..0a9156785f 100644
--- a/packages/lab/src/BottomSheet/snapOffsets.ts
+++ b/packages/lab/src/BottomSheet/snapOffsets.ts
@@ -74,12 +74,21 @@ export function nearestOffset(
}
/**
- * Scrim opacity (1 = fully visible, 0 = hidden) for a drag/settle `offset`.
+ * Minimum scrim opacity at the peek detent. The scrim thins to a glance state
+ * but never fully vanishes, because a modal sheet keeps the background inert —
+ * a fully clear backdrop would read as "interactive" when it isn't. (For a
+ * genuinely interactive, undimmed peek, use a non-modal sheet, `hasScrim=false`.)
+ */
+export const MIN_PEEK_SCRIM_OPACITY = 0.3;
+
+/**
+ * Scrim opacity (1 = fully visible) for a drag/settle `offset`.
* The scrim stays full while the sheet is at or above its second-shortest
- * detent, then fades to 0 as it collapses onto the shortest ("peek") detent —
- * a glance state that reveals the content behind — and stays hidden below it.
- * A single-detent sheet has no peek, so it instead fades across the dismiss
- * overshoot toward `dismissOffset`.
+ * detent, then fades as it collapses onto the shortest ("peek") detent — a
+ * glance state that thins the backdrop to `MIN_PEEK_SCRIM_OPACITY` (not fully
+ * gone, since the sheet is still modal) and holds there below it.
+ * A single-detent sheet has no peek, so it instead fades all the way to 0
+ * across the dismiss overshoot toward `dismissOffset` (the sheet is leaving).
*/
export function scrimOpacityForOffset(
offset: number,
@@ -87,15 +96,19 @@ export function scrimOpacityForOffset(
dismissOffset: number,
): number {
const shortest = offsets[offsets.length - 1];
- const fadeStart = offsets.length >= 2 ? offsets[offsets.length - 2] : 0;
- const fadeEnd = offsets.length >= 2 ? shortest : dismissOffset;
+ const hasPeek = offsets.length >= 2;
+ const fadeStart = hasPeek ? offsets[offsets.length - 2] : 0;
+ const fadeEnd = hasPeek ? shortest : dismissOffset;
+ // Peek is a resting state on a still-modal sheet, so keep a floor; the
+ // dismiss overshoot is a sheet on its way out, so let it clear completely.
+ const floor = hasPeek ? MIN_PEEK_SCRIM_OPACITY : 0;
if (offset <= fadeStart) {
return 1;
}
if (offset >= fadeEnd) {
- return 0;
+ return floor;
}
- return 1 - (offset - fadeStart) / (fadeEnd - fadeStart);
+ return 1 - (1 - floor) * ((offset - fadeStart) / (fadeEnd - fadeStart));
}
/**
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs b/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
index 6b8ec3a20f..519676b4c0 100644
--- a/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
+++ b/packages/lab/src/BottomSheet/useSheetGestures.doc.mjs
@@ -9,7 +9,7 @@ export const docs = {
{
name: 'options',
type: 'UseSheetGesturesOptions',
- description: 'isOpen, onDismiss, optional snapHeights (candidate detent heights in px), onSnap, and onScrimOpacity (the scrim opacity to show, 1->0 as the sheet collapses onto its peek detent, for a glance affordance). Internal to BottomSheet, not exported from the lab entry point.',
+ 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,
},
],
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.test.ts b/packages/lab/src/BottomSheet/useSheetGestures.test.ts
index 446fa20707..c25787ddce 100644
--- a/packages/lab/src/BottomSheet/useSheetGestures.test.ts
+++ b/packages/lab/src/BottomSheet/useSheetGestures.test.ts
@@ -188,25 +188,25 @@ describe('useSheetGestures', () => {
expect(onDismiss).toHaveBeenCalledTimes(1);
});
- it('fades the scrim from full to hidden as it collapses onto the peek detent', () => {
+ it('fades the scrim from full toward the peek floor as it collapses onto the peek detent', () => {
const onScrimOpacity = vi.fn();
// Sheet 400, detents at 200 and 300 -> offsets [0, 100, 200]. The fade
// spans the mid detent (offset 100) to the peek detent (offset 200):
- // full at/above 100, hidden at/below 200.
+ // full at/above 100, thinned to the peek floor (0.3) at/below 200.
const {hook} = setup({snapHeights: () => [200, 300], onScrimOpacity});
const t = makeTarget();
down(hook, 0, 0, t);
move(hook, 60, 200, t); // offset 60, above the mid detent -> full
- move(hook, 150, 600, t); // offset 150, halfway through the fade -> ~0.5
- move(hook, 220, 1000, t); // offset 220, past the peek -> hidden
+ 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]);
expect(values[0]).toBe(1);
- expect(values[1]).toBeGreaterThan(0.4);
- expect(values[1]).toBeLessThan(0.6);
- expect(values[values.length - 1]).toBe(0);
+ expect(values[1]).toBeGreaterThan(0.55);
+ expect(values[1]).toBeLessThan(0.75);
+ expect(values[values.length - 1]).toBeCloseTo(0.3);
});
- it('keeps the scrim hidden when settled at the peek detent', () => {
+ it('thins the scrim to the peek floor when settled at the peek detent (still modal)', () => {
const onScrimOpacity = vi.fn();
const {hook} = setup({snapHeights: () => [200, 300], onScrimOpacity});
const t = makeTarget();
@@ -216,9 +216,10 @@ describe('useSheetGestures', () => {
move(hook, 200, 900, t);
up(hook, 200, 1400, t);
expect(hook.result.current.settledOffset).toBe(200);
- // Last reported opacity (on settle) is hidden.
+ // 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]);
- expect(values[values.length - 1]).toBe(0);
+ expect(values[values.length - 1]).toBeCloseTo(0.3);
});
it('magnetically settles the live drag onto a nearby detent', () => {
diff --git a/packages/lab/src/BottomSheet/useSheetGestures.ts b/packages/lab/src/BottomSheet/useSheetGestures.ts
index 56dd2c0fef..365c3c95e4 100644
--- a/packages/lab/src/BottomSheet/useSheetGestures.ts
+++ b/packages/lab/src/BottomSheet/useSheetGestures.ts
@@ -119,7 +119,7 @@ export interface UseSheetGesturesOptions {
* Called with the scrim opacity the sheet should show (1 = fully visible,
* 0 = hidden) as the drag moves and on settle. Full while the sheet is at
* or above its mid detent, fading to 0 as it collapses onto the shortest
- * "peek" detent — so a glance-height sheet reveals the content behind — and
+ * "peek" detent — thinning to a faint glance state without fully clearing — and
* on the dismiss overshoot. Lets the owner mirror it onto the scrim.
*/
onScrimOpacity?: (opacity: number) => void;
@@ -320,7 +320,7 @@ export function useSheetGestures({
const target = resolveSettleOffset(offset, offsets, dir, baseOffset);
setSettledOffset(target);
onSnapRef.current?.(height - target);
- // Keep the scrim in sync with the resting detent (hidden at the peek).
+ // Keep the scrim in sync with the resting detent (faint floor at the peek).
const dismissOffset =
maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
onScrimOpacityRef.current?.(