@astryxdesign/lab 0.2.0-canary.8d64648 → 0.2.0-canary.8dfd7cf

package/src/BottomSheet/BottomSheet.tsx

@@ -4,21 +4,22 @@
 
 /**
  * @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 modal `<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.
+ * 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)
@@ -27,81 +28,168 @@
  * - /apps/storybook/stories/BottomSheet.stories.tsx (examples and visual coverage)
  */
 
-import {type ReactNode} from 'react';
+import {useCallback, useEffect, useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {BaseProps} from '@astryxdesign/core';
 import {
   colorVars,
+  durationVars,
+  easeVars,
   radiusVars,
+  shadowVars,
+  sizeVars,
   spacingVars,
 } from '@astryxdesign/core/theme/tokens.stylex';
-import {mergeProps, themeProps} from '@astryxdesign/core/utils';
-import {Drawer} from '../Drawer';
+import {useDevWarning, useScrollLock} from '@astryxdesign/core/hooks';
+import {mergeProps, mergeRefs, themeProps} from '@astryxdesign/core/utils';
 import {useSheetGestures} from './useSheetGestures';
 
+// 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.
  */
 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',
 } 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;
+// 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(): number[] {
+  if (typeof window === 'undefined') {
+    return [];
+  }
+  const vh = window.visualViewport?.height ?? window.innerHeight;
+  return SNAP_FRACTIONS.map(f => f * vh);
+}
 
 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.
+  // A full-viewport transparent shell: it supplies the top layer, focus trap,
+  // and ::backdrop scrim but paints nothing and doesn't clip, so the sheet can
+  // translate past fully-open without hitting a fixed dialog edge. It stays
+  // hit-testable (no pointer-events:none) so taps on the transparent area
+  // reach onClick and dismiss the sheet — the positioner below passes those
+  // taps through to here, while the sheet itself re-enables pointer events.
+  dialog: {
+    position: 'fixed',
+    inset: 0,
+    width: '100dvw',
+    height: '100dvh',
+    maxWidth: 'none',
+    maxHeight: 'none',
+    margin: 0,
+    padding: 0,
+    border: 'none',
+    backgroundColor: 'transparent',
+    overflow: 'visible',
+    display: 'none',
+    outline: 'none',
+  },
+  dialogOpen: {
+    display: 'block',
+  },
+  // Opacity is a var the drag handler lowers toward dismissal;
+  // @starting-style animates the entrance fade-in.
+  scrim: {
+    '::backdrop': {
+      backgroundColor: colorVars['--color-overlay'],
+      backdropFilter: 'blur(2px)',
+      opacity: {
+        default: 'var(--_sheet-scrim-opacity, 1)',
+        '@starting-style': 0,
+      },
+      transitionProperty: 'opacity, display',
+      transitionDuration: durationVars['--duration-medium'],
+      transitionTimingFunction: easeVars['--ease-standard'],
+      transitionBehavior: 'allow-discrete',
+      '@media (prefers-reduced-motion: reduce)': {
+        transitionDuration: '0.01s',
+      },
+    },
+  },
+  positioner: {
+    position: 'absolute',
+    insetInline: 0,
+    insetBlockEnd: 0,
+    display: 'flex',
+    justifyContent: 'center',
+    pointerEvents: 'none',
+  },
   sheet: {
+    pointerEvents: 'auto',
+    boxSizing: 'border-box',
     display: 'flex',
     flexDirection: 'column',
     minHeight: 0,
-    height: '100%',
     width: '100%',
-    maxWidth: MAX_SHEET_WIDTH,
-    marginInline: 'auto',
+    maxWidth: 640,
     backgroundColor: colorVars['--color-background-surface'],
-    borderStartStartRadius: radiusVars['--radius-page'],
-    borderStartEndRadius: radiusVars['--radius-page'],
+    borderStartStartRadius: radiusVars['--radius-container'],
+    borderStartEndRadius: radiusVars['--radius-container'],
+    boxShadow: shadowVars['--shadow-high'],
+    // tabIndex=-1 makes this the initial focus target; it's a programmatic
+    // landing spot, not an interactive control, so suppress the focus ring.
+    outline: 'none',
     overflow: 'hidden',
-    paddingBlockEnd: `env(safe-area-inset-bottom, 0px)`,
+    // Reserved overdrag zone: extra bottom padding (surface bg + home-indicator
+    // clearance) that a small upward drag reveals, negated by an equal negative
+    // margin so at rest it sits BELOW the fold — the true sheet stays pinned to
+    // the bottom edge. Budget heights add the same amount back (see `budget` /
+    // `hugHeight`) so the visible height is unchanged.
+    paddingBlockEnd: `calc(env(safe-area-inset-bottom, 0px) + ${OVERSCROLL_PADDING}px)`,
+    marginBlockEnd: `${-OVERSCROLL_PADDING}px`,
+    transform: {
+      default: 'translateY(0)',
+      '@starting-style': 'translateY(100%)',
+    },
+    transitionProperty: 'transform',
+    transitionDuration: durationVars['--duration-medium'],
+    transitionTimingFunction: easeVars['--ease-standard'],
     willChange: 'transform',
+    '@media (prefers-reduced-motion: reduce)': {
+      transitionDuration: '0.01s',
+    },
   },
-  // 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,
+  sheetClosing: {
+    transform: 'translateY(100%)',
   },
   handleBar: {
     flexShrink: 0,
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
-    paddingBlock: spacingVars['--spacing-2'],
+    // The whole strip is the drag target: 48px (top of the spacing scale,
+    // above Apple's 44px / WCAG 2.5.8's 24px), no overlap tricks.
+    height: spacingVars['--spacing-12'],
     touchAction: 'none',
     cursor: 'grab',
   },
   handlePill: {
-    width: 36,
-    height: 4,
+    width: sizeVars['--size-element-lg'],
+    height: spacingVars['--spacing-1'],
     borderRadius: radiusVars['--radius-full'],
     backgroundColor: colorVars['--color-border'],
   },
@@ -109,16 +197,26 @@ const styles = stylex.create({
     flexGrow: 1,
     minHeight: 0,
     overflowY: 'auto',
-    overscrollBehavior: 'contain',
+    // No overscroll bounce inside the sheet — a pull-down at the top edge is
+    // handed off to the sheet drag (see useSheetGestures' touch handling)
+    // rather than rubber-banding the content.
+    overscrollBehavior: 'none',
+    // Allow native vertical scrolling of the content; the at-top pull-down is
+    // intercepted via a non-passive touchmove listener, not by blocking
+    // touch-action (which would suppress scrolling entirely).
+    touchAction: 'pan-y',
   },
-  // `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: {
+  // Both budgets add the overdrag padding back to the height so the visible
+  // height (minus the off-screen padding) matches the intended budget.
+  budget: {
+    height: `calc(var(--_sheet-budget) + ${OVERSCROLL_PADDING}px)`,
+  },
+  hugHeight: {
     height: 'fit-content',
-    maxHeight: HEIGHT_BUDGETS.auto,
+    maxHeight: `calc(${HEIGHT_BUDGETS.hug} + ${OVERSCROLL_PADDING}px)`,
   },
 });
+
 export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
   /** Ref forwarded to the underlying <dialog> element. */
   ref?: React.Ref<HTMLDialogElement>;
@@ -127,8 +225,8 @@ export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
   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;
@@ -143,28 +241,32 @@ export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
   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;
+  height?: BottomSheetHeight | number | string;
 
   /** 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 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.
  *
  * @example
  * ```
@@ -178,48 +280,182 @@ export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {
  * ```
  */
 export function BottomSheet({
+  ref,
   isOpen,
   onOpenChange,
   label,
   children,
-  height = 'medium',
+  height = 'capped',
   xstyle,
   ...props
 }: BottomSheetProps) {
-  const close = () => onOpenChange(false);
-  const {contentProps, handleProps} = useSheetGestures({
+  const dialogRef = useRef<HTMLDialogElement | null>(null);
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const sheetNodeRef = useRef<HTMLDivElement | null>(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 (hidden at the peek).
+  const handleScrimOpacity = useCallback((opacity: number) => {
+    dialogRef.current?.style.setProperty(
+      '--_sheet-scrim-opacity',
+      String(opacity),
+    );
+  }, []);
+
+  const {contentProps, handleProps, bodyProps, sheetRef} = useSheetGestures({
     isOpen,
     onDismiss: close,
+    snapHeights: defaultSnapHeights,
+    onScrimOpacity: handleScrimOpacity,
   });
 
+  // showModal() enters the top layer with a focus trap + ::backdrop; on close
+  // we animate out (below) then restore focus to the opener.
+  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.
+        const autofocus = dialog.querySelector<HTMLElement>('[data-autofocus]');
+        if (autofocus) {
+          autofocus.focus();
+        } else {
+          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: TransitionEvent) => {
+        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]);
+
+  useScrollLock(isOpen);
+
+  // 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: React.SyntheticEvent<HTMLDialogElement>) => {
+      event.preventDefault();
+      close();
+    },
+    [close],
+  );
+  // Explicit Escape handler in addition to the native `cancel` event, for
+  // environments that don't synthesize `cancel`.
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLDialogElement>) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        close();
+      }
+    },
+    [close],
+  );
+  const handleClick = useCallback(
+    (event: React.MouseEvent<HTMLDialogElement>) => {
+      if (event.target === event.currentTarget) {
+        close();
+      }
+    },
+    [close],
+  );
+
+  const isNamed = typeof height === 'string' && height in HEIGHT_BUDGETS;
+  const budget = isNamed
+    ? HEIGHT_BUDGETS[height as BottomSheetHeight]
+    : typeof height === 'number'
+      ? `${height}px`
+      : height;
+  const isHug = height === 'hug';
+
   return (
-    <Drawer
-      isOpen={isOpen}
-      onClose={close}
-      side="bottom"
-      size={HEIGHT_BUDGETS[height]}
-      label={label}
-      hasScrim
-      hasCloseButton={false}
-      xstyle={[styles.dialogSurface, height === 'auto' && styles.autoHeight]}
+    <dialog
+      {...stylex.props(
+        styles.dialog,
+        isOpen && styles.dialogOpen,
+        styles.scrim,
+      )}
+      ref={mergeRefs(ref, dialogRef)}
+      aria-label={label}
+      aria-modal="true"
+      onCancel={handleCancel}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
       {...props}>
-      <div
-        data-astryx-sheet=""
-        {...mergeProps(
-          themeProps('bottom-sheet'),
-          stylex.props(styles.sheet, xstyle),
-          contentProps.style,
-        )}>
+      <div {...stylex.props(styles.positioner)}>
         <div
-          data-astryx-sheet-handle=""
-          {...stylex.props(styles.handleBar)}
-          {...handleProps}
-          aria-hidden="true">
-          <div {...stylex.props(styles.handlePill)} />
+          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' as string]: budget,
+              ...contentProps.style,
+            },
+          )}>
+          <div
+            {...stylex.props(styles.handleBar)}
+            {...handleProps}
+            aria-hidden="true">
+            <div {...stylex.props(styles.handlePill)} />
+          </div>
+          <div {...stylex.props(styles.body)} {...bodyProps}>
+            {children}
+          </div>
         </div>
-        <div {...stylex.props(styles.body)}>{children}</div>
       </div>
-    </Drawer>
+    </dialog>
   );
 }