@astryxdesign/lab 0.2.0-canary.fc53ff7 → 0.3.0-canary.82d4dab

package/README.md

@@ -20,6 +20,12 @@ See the **[Component Lifecycle](https://github.com/facebook/astryx/wiki/Componen
 
 **Core:** Full keyboard/a11y, hover guards, theming story, status states, spec compliance, vibe tested. Shipped to consumers on `latest`.
 
+## Promotion gate: accessibility
+
+The [Accessibility Checklist](https://github.com/facebook/astryx/wiki/Accessibility-Checklist) is a hard requirement for graduating to core — every item, verified in the promotion PR, alongside the hardening bar linked above.
+
+Lab components get the same scan coverage as core (the `pr-a11y` axe audit and the weekly full scan run against lab too), but a11y findings on a lab component do not block lab merges — they block **promotion**. Iterate freely in lab; clear the checklist to graduate.
+
 ## Usage
 
 Inside the monorepo (storybook/sandbox), imports resolve via pnpm workspaces:

package/dist/BottomSheet/BottomSheet.d.ts

@@ -1,20 +1,27 @@
 /**
  * @file BottomSheet.tsx
- * @input Uses React, StyleX, theme tokens, Drawer, useSheetGestures, themeProps
+ * @input Uses React, StyleX, theme tokens, core hooks (useScrollLock), utils, useSheetGestures
  * @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.
+ * A mobile touch surface that rises from the bottom edge: grab handle, snap
+ * 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
+ * full-height transparent shell with the visible sheet bottom-anchored inside.
+ * That shell is what lets the sheet translate freely (including a little past
+ * fully-open) without clipping against a fixed dialog edge.
  *
- * 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.
+ * `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.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/lab/src/BottomSheet/BottomSheet.doc.mjs (props table, features, usage)
@@ -25,15 +32,16 @@
 import { type ReactNode } from 'react';
 import type { BaseProps } from '@astryxdesign/core';
 /**
- * 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).
+ * Height budget for each named size, as a fraction of the viewport:
+ * - `hug` — fits its content, never taller than 92%.
+ * - `capped` — a scrolling mid-height panel (62%).
+ * - `tall` — a pinned near-full panel (92%); use when content streams in so
+ *   the sheet doesn't resize under the user.
  */
 declare const HEIGHT_BUDGETS: {
-    readonly short: "240px";
-    readonly medium: "50dvh";
-    readonly tall: "90dvh";
-    readonly auto: "90dvh";
+    readonly hug: "92dvh";
+    readonly capped: "62dvh";
+    readonly tall: "92dvh";
 };
 export type BottomSheetHeight = keyof typeof HEIGHT_BUDGETS;
 export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
@@ -42,8 +50,8 @@ export interface BottomSheetProps extends BaseProps<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
+     * 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;
@@ -55,26 +63,46 @@ export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
     /** 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
+     * How tall the sheet is. A named budget, or any explicit height:
+     * - `'hug'` — fits its content, never taller than 92% of the viewport.
+     * - `'capped'` — a scrolling mid-height panel (~62%).
+     * - `'tall'` — a pinned near-full panel (~92%); use when content streams in
+     *   so the sheet doesn't resize under the user.
+     * - a `number` (px) or CSS length string (e.g. `'70dvh'`, `480`) for a
+     *   custom budget.
      *
-     * On viewports shorter than the budget the sheet fills the available
-     * height.
-     * @default 'medium'
+     * The user can still drag between snap points regardless of the starting
+     * height. On viewports shorter than the budget the sheet fills the
+     * available height.
+     * @default 'capped'
+     */
+    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
      */
-    height?: BottomSheetHeight;
+    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
- * 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.
+ * 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
+ * `<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
  * ```
@@ -87,7 +115,7 @@ export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
  * </BottomSheet>
  * ```
  */
-export declare function BottomSheet({ isOpen, onOpenChange, label, children, height, xstyle, ...props }: BottomSheetProps): import("react").JSX.Element;
+export declare function BottomSheet({ ref, isOpen, onOpenChange, label, children, height, hasScrim, xstyle, ...props }: BottomSheetProps): import("react").JSX.Element;
 export declare namespace BottomSheet {
     var displayName: string;
 }

package/dist/BottomSheet/BottomSheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BottomSheet.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheet.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AAUlD;;;;GAIG;AACH,QAAA,MAAM,cAAc;;;;;CAKV,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,cAAc,CAAC;AAoE5D,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IACpE,wDAAwD;IACxD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnC,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,MAAiB,EACjB,MAAM,EACN,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAoClB;yBA5Ce,WAAW"}
+{"version":3,"file":"BottomSheet.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/BottomSheet.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAiC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAErE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,oBAAoB,CAAC;AA2BlD;;;;;;GAMG;AACH,QAAA,MAAM,cAAc;;;;CAIV,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,cAAc,CAAC;AAiL5D,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IACpE,wDAAwD;IACxD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAEnC,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAExC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;IAE7C;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,GAAG,EACH,MAAM,EACN,YAAY,EACZ,KAAK,EACL,QAAQ,EACR,MAAiB,EACjB,QAAe,EACf,MAAM,EACN,GAAG,KAAK,EACT,EAAE,gBAAgB,+BA0LlB;yBApMe,WAAW"}

package/dist/BottomSheet/BottomSheet.js

@@ -4,21 +4,28 @@
 
 /**
  * @file BottomSheet.tsx
- * @input Uses React, StyleX, theme tokens, Drawer, useSheetGestures, themeProps
+ * @input Uses React, StyleX, theme tokens, core hooks (useScrollLock), utils, useSheetGestures
  * @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.
+ * A mobile touch surface that rises from the bottom edge: grab handle, snap
+ * 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
+ * full-height transparent shell with the visible sheet bottom-anchored inside.
+ * That shell is what lets the sheet translate freely (including a little past
+ * fully-open) without clipping against a fixed dialog edge.
  *
- * 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.
+ * `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.
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/lab/src/BottomSheet/BottomSheet.doc.mjs (props table, features, usage)
@@ -26,64 +33,109 @@
  * - /packages/lab/src/BottomSheet/index.ts (exports if types change)
  * - /apps/storybook/stories/BottomSheet.stories.tsx (examples and visual coverage)
  */
+import { useCallback, useEffect, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import '@astryxdesign/core/theme/tokens.stylex';
-import { colorVars, radiusVars, spacingVars } from '@astryxdesign/core/theme/tokens.stylex';
-import { mergeProps, themeProps } from '@astryxdesign/core/utils';
-import { Drawer } from "../Drawer/index.js";
+import { colorVars, durationVars, easeVars, radiusVars, shadowVars, sizeVars, spacingVars } from '@astryxdesign/core/theme/tokens.stylex';
+import { useDevWarning, useScrollLock } from '@astryxdesign/core/hooks';
+import { mergeProps, mergeRefs, themeProps } from '@astryxdesign/core/utils';
 import { useSheetGestures } from "./useSheetGestures.js";
 
+// 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.
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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
+// dropped, so a full set is safe to offer. The shortest is a glance "peek";
+// the scrim hides as the sheet collapses onto it (see onScrimOpacity).
+const SNAP_FRACTIONS = [0.14, 0.5, 0.92];
+
 /**
- * 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).
+ * Height budget for each named size, as a fraction of the viewport:
+ * - `hug` — fits its content, never taller than 92%.
+ * - `capped` — a scrolling mid-height panel (62%).
+ * - `tall` — a pinned near-full panel (92%); use when content streams in so
+ *   the sheet doesn't resize under the user.
  */
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const HEIGHT_BUDGETS = {
-  short: '240px',
-  medium: '50dvh',
-  tall: '90dvh',
-  auto: '90dvh'
+  hug: '92dvh',
+  // upper bound only; the sheet hugs its content beneath it
+  capped: '62dvh',
+  tall: '92dvh'
 };
-// 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;
+// px the sheet extends below its budget as reserved padding, revealed by an
+// upward overdrag rather than showing a gap.
+// SYNC: must match OVERSCROLL_MAX in useSheetGestures.ts (the drag cap).
+const OVERSCROLL_PADDING = 48;
+
+/**
+ * Default snap detents in px, resolved against the *visual* viewport (like iOS
+ * detents), so a mid rest point is ~half the screen regardless of the sheet's
+ * own height budget. Read lazily at drag start (no persistent listener) so it
+ * reflects the live viewport after a rotation or the virtual keyboard opening.
+ * SSR-safe: returns `[]` off the client.
+ */
+function defaultSnapHeights() {
+  if (typeof window === 'undefined') {
+    return [];
+  }
+  const vh = window.visualViewport?.height ?? window.innerHeight;
+  return SNAP_FRACTIONS.map(f => f * vh);
+}
 const styles = {
   sheet: {
+    kfzvcC: "x67bb7w",
+    kB7OPa: "x9f619",
     k1xSpc: "x78zum5",
     kXwgrk: "xdt5ytf",
     kAzted: "x2lwn1j",
-    kZKoxP: "x5yr21d",
     kzqmXN: "xh8yej3",
     ks0D6T: "x11gisft",
-    kUOVxO: "xvueqy4",
     kWkggS: "x10xzikg",
-    krdFHd: "x183tx6i",
-    kfmiAY: "x663v1",
+    krdFHd: "x81l70g",
+    kfmiAY: "x7hs6f1",
+    kGVxlE: "x1kcpxr7",
+    kI3sdo: "x1a2a7pz",
     kVQacm: "xb3r6kr",
-    kGO01o: "x1a148e8",
+    kGO01o: "x1wkw6tp",
+    k1K539: "x1if0o47",
+    k3aq6I: "xnn1q72 xhbqy3z",
+    k1ekBW: "x11xpdln",
+    kIyJzY: "x80gvsz",
+    kAMwcw: "xlr8y92",
     k6sLGO: "x1so62im",
+    k6CgDc: "xzg1mie",
+    $$css: true
+  },
+  sheetClosing: {
+    k3aq6I: "x1weeur4",
     $$css: true
   },
-  dialogSurface: {
-    kWkggS: "xjbqb8w",
-    kGVxlE: "x1gnnqk1",
-    kEafiO: "x972fbf",
+  budget: {
+    kZKoxP: "x1tpcejd",
     $$css: true
   },
-  autoHeight: {
+  hugHeight: {
     kZKoxP: "xg7h5cd",
-    kskxy: "x1ismmbu",
+    kskxy: "x14bu9tk",
     $$css: true
   }
 };
 /**
- * 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.
+ * 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
+ * `<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
  * ```
@@ -97,53 +149,197 @@ const styles = {
  * ```
  */
 export function BottomSheet({
+  ref,
   isOpen,
   onOpenChange,
   label,
   children,
-  height = 'medium',
+  height = 'capped',
+  hasScrim = true,
   xstyle,
   ...props
 }) {
-  const close = () => onOpenChange(false);
+  const dialogRef = useRef(null);
+  const triggerRef = useRef(null);
+  const sheetNodeRef = useRef(null);
+  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 (a faint floor at the peek).
+  const handleScrimOpacity = useCallback(opacity => {
+    dialogRef.current?.style.setProperty('--_sheet-scrim-opacity', String(opacity));
+  }, []);
   const {
     contentProps,
-    handleProps
+    handleProps,
+    bodyProps,
+    sheetRef
   } = useSheetGestures({
     isOpen,
-    onDismiss: close
+    onDismiss: close,
+    snapHeights: defaultSnapHeights,
+    onScrimOpacity: handleScrimOpacity
   });
-  return /*#__PURE__*/_jsx(Drawer, {
-    isOpen: isOpen,
-    onClose: close,
-    side: "bottom",
-    size: HEIGHT_BUDGETS[height],
-    label: label,
-    hasScrim: true,
-    hasCloseButton: false,
-    xstyle: [styles.dialogSurface, height === 'auto' && styles.autoHeight],
+
+  // 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) {
+      dialog.style.setProperty('--_sheet-scrim-opacity', '1');
+      if (!dialog.open) {
+        // 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;
+          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('[data-autofocus]');
+        if (autofocus) {
+          autofocus.focus();
+        } else if (hasScrim) {
+          sheetNodeRef.current?.focus();
+        }
+      }
+    } else if (dialog.open) {
+      // Wait for the slide-out (sheetClosing, applied this render) before
+      // close() releases the top layer. Timeout backstops a missing
+      // transitionend (reduced motion, hidden tab).
+      const sheet = sheetNodeRef.current;
+      let done = false;
+      const finish = () => {
+        if (done) {
+          return;
+        }
+        done = true;
+        clearTimeout(timer);
+        sheet?.removeEventListener('transitionend', onEnd);
+        if (dialog.open) {
+          dialog.close();
+        }
+        triggerRef.current?.focus();
+        triggerRef.current = null;
+      };
+      const onEnd = event => {
+        if (event.target === sheet && event.propertyName === 'transform') {
+          finish();
+        }
+      };
+      sheet?.addEventListener('transitionend', onEnd);
+      // Backstop above --duration-medium (410ms) so transitionend normally
+      // fires first; this only covers environments that don't emit it.
+      const timer = setTimeout(finish, 450);
+      return () => {
+        clearTimeout(timer);
+        sheet?.removeEventListener('transitionend', onEnd);
+      };
+    }
+  }, [isOpen, hasScrim]);
+
+  // 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.
+  useDevWarning('BottomSheet', 'requires a non-empty `label` for an accessible name; the open sheet ' + 'has no built-in heading to derive one from.', isOpen && !label);
+  const handleCancel = useCallback(event => {
+    event.preventDefault();
+    close();
+  }, [close]);
+  // Explicit Escape handler in addition to the native `cancel` event, for
+  // 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 => {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      close();
+    }
+  }, [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 => {
+    if (hasScrim && event.target === event.currentTarget) {
+      close();
+    }
+  }, [close, hasScrim]);
+  const isNamed = typeof height === 'string' && height in HEIGHT_BUDGETS;
+  const budget = isNamed ? HEIGHT_BUDGETS[height] : typeof height === 'number' ? `${height}px` : height;
+  const isHug = height === 'hug';
+  return /*#__PURE__*/_jsx("dialog", {
+    ...{
+      0: {
+        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1s85apg x1a2a7pz"
+      },
+      4: {
+        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1a2a7pz x1lliihq"
+      },
+      2: {
+        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1s85apg x1a2a7pz xnixb3f xni466t xxiuuzi xc0dz0a xft5bk6 x15h3t91 x142juwg x1viac0w"
+      },
+      6: {
+        className: "xixxii4 x10a8y8t x1o6l61p xtdtrs8 x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1a2a7pz x1lliihq xnixb3f xni466t xxiuuzi xc0dz0a xft5bk6 x15h3t91 x142juwg x1viac0w"
+      },
+      1: {
+        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1s85apg x1a2a7pz x47corl xfo81ep xh8yej3 x5yr21d"
+      },
+      5: {
+        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1a2a7pz x1lliihq x47corl xfo81ep xh8yej3 x5yr21d"
+      },
+      3: {
+        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1s85apg x1a2a7pz xnixb3f xni466t xxiuuzi xc0dz0a xft5bk6 x15h3t91 x142juwg x1viac0w x47corl xfo81ep xh8yej3 x5yr21d"
+      },
+      7: {
+        className: "xixxii4 x10a8y8t x1x1rfll x7ab17h x1ghz6dp x1717udv xjbqb8w x1rea2x4 x1a2a7pz x1lliihq xnixb3f xni466t xxiuuzi xc0dz0a xft5bk6 x15h3t91 x142juwg x1viac0w x47corl xfo81ep xh8yej3 x5yr21d"
+      }
+    }[!!isOpen << 2 | !!hasScrim << 1 | !!!hasScrim << 0],
+    ref: mergeRefs(ref, dialogRef),
+    "aria-label": label,
+    "aria-modal": hasScrim ? 'true' : undefined,
+    onCancel: handleCancel,
+    onClick: handleClick,
+    onKeyDown: handleKeyDown,
     ...props,
-    children: /*#__PURE__*/_jsxs("div", {
-      "data-astryx-sheet": "",
-      ...mergeProps(themeProps('bottom-sheet'), stylex.props(styles.sheet, xstyle), contentProps.style),
-      children: [/*#__PURE__*/_jsx("div", {
-        "data-astryx-sheet-handle": "",
-        ...{
-          className: "x2lah0s x78zum5 x6s0dn4 xl56j7k xce4md1 x5ve5x3 x1jm3nie"
-        },
-        ...handleProps,
-        "aria-hidden": "true",
-        children: /*#__PURE__*/_jsx("div", {
+    children: /*#__PURE__*/_jsx("div", {
+      ...{
+        className: "x10l6tqk x17y0mx6 x1ey2m1c x78zum5 xl56j7k x47corl"
+      },
+      children: /*#__PURE__*/_jsxs("div", {
+        ref: mergeRefs(sheetRef, sheetNodeRef),
+        tabIndex: -1,
+        ...mergeProps(themeProps('bottom-sheet'), stylex.props(styles.sheet, isHug ? styles.hugHeight : styles.budget, !isOpen && styles.sheetClosing, xstyle), undefined, {
+          ['--_sheet-budget']: budget,
+          ...contentProps.style
+        }),
+        children: [/*#__PURE__*/_jsx("div", {
+          ...{
+            className: "x2lah0s x78zum5 x6s0dn4 xl56j7k x1k15mir x5ve5x3 x1jm3nie"
+          },
+          ...handleProps,
+          "aria-hidden": "true",
+          children: /*#__PURE__*/_jsx("div", {
+            ...{
+              className: "x1m747yf x11c6zpc xjspbzw x1m4xfpy"
+            }
+          })
+        }), /*#__PURE__*/_jsx("div", {
           ...{
-            className: "x14qfxbe xqu0tyb xjspbzw x1m4xfpy"
-          }
-        })
-      }), /*#__PURE__*/_jsx("div", {
-        ...{
-          className: "x1iyjqo2 x2lwn1j x1odjw0f xish69e"
-        },
-        children: children
-      })]
+            className: "x1iyjqo2 x2lwn1j x1odjw0f x8du1vd xx69xxh"
+          },
+          ...bodyProps,
+          children: children
+        })]
+      })
     })
   });
 }

package/dist/BottomSheet/snapOffsets.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @file snapOffsets.ts
+ * @input Pure geometry helpers — no React, no DOM.
+ * @output Converts snap points to translateY offsets for the sheet surface.
+ * @position Internal to BottomSheet; consumed by useSheetGestures, tested by
+ *   snapOffsets.test.ts.
+ *
+ * The sheet is rendered at its full (fully-open) height and *translated down*
+ * to express shorter detents — translate is GPU-composited, so this is cheaper
+ * than animating layout height. A detent is therefore a translateY offset in
+ * px from the fully-open position (0 = fully open, larger = more collapsed).
+ * These helpers turn snap points into that offset list; they are pure so the
+ * geometry can be unit-tested without a DOM.
+ */
+/**
+ * Detents whose resting offsets land within this many px of each other are
+ * treated as the same stop (the taller one wins). Stops the sheet from having
+ * two near-identical rest positions — e.g. when a content-hugging height sits
+ * a hair away from a fractional snap point.
+ */
+export declare const DETENT_DEDUP_PX = 48;
+/** Resolve snap points given as viewport fractions (0, 1] to px heights. */
+export declare function snapFractionsToHeights(fractions: readonly number[], viewportPx: number): number[];
+/**
+ * Given the sheet's full height (px, as rendered fully open) and a set of
+ * candidate detent *visible heights* (px), return the resting translateY
+ * offsets from fully-open, ascending and de-duplicated.
+ *
+ * - `0` (fully open) is always the first detent.
+ * - Only heights strictly shorter than the sheet become collapsed detents; a
+ *   height >= the sheet can't be shown by translating down, so it's dropped.
+ * - Offsets closer than `dedupPx` collapse to the smaller (taller) offset, so
+ *   near-identical detents — e.g. a hug height ≈ a snap point — become one stop.
+ */
+export declare function computeDetentOffsets(sheetHeight: number, detentHeights: readonly number[], dedupPx?: number): number[];
+/** Nearest value in `offsets` to `value` (offsets must be non-empty). */
+export declare function nearestOffset(value: number, offsets: readonly number[]): number;
+/**
+ * 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 declare 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 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 declare function scrimOpacityForOffset(offset: number, offsets: readonly number[], dismissOffset: number): number;
+/**
+ * Settle target for a released drag. Restricts candidates to the drag
+ * direction so a committed drag never snaps *back past* where it started
+ * (a down-drag settles at/below the start, an up-drag at/above), then picks
+ * the nearest remaining detent. `dir`: 1 = dragged down, -1 = up, 0 = neither.
+ */
+export declare function resolveSettleOffset(value: number, offsets: readonly number[], dir: number, baseOffset: number): number;
+//# sourceMappingURL=snapOffsets.d.ts.map

package/dist/BottomSheet/snapOffsets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapOffsets.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/snapOffsets.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,4EAA4E;AAC5E,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,UAAU,EAAE,MAAM,GACjB,MAAM,EAAE,CAEV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,SAAS,MAAM,EAAE,EAChC,OAAO,GAAE,MAAwB,GAChC,MAAM,EAAE,CAcV;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CAKR;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,aAAa,EAAE,MAAM,GACpB,MAAM,CAeR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,MAAM,CAcR"}