@astryxdesign/lab 0.2.0-canary.fc53ff7 → 0.3.0-canary.2d2dba1

package/dist/BottomSheet/snapOffsets.js

@@ -0,0 +1,114 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 const DETENT_DEDUP_PX = 48;
+
+/** Resolve snap points given as viewport fractions (0, 1] to px heights. */
+export function snapFractionsToHeights(fractions, viewportPx) {
+  return fractions.filter(f => f > 0 && f <= 1).map(f => f * viewportPx);
+}
+
+/**
+ * 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 function computeDetentOffsets(sheetHeight, detentHeights, dedupPx = DETENT_DEDUP_PX) {
+  const collapsed = detentHeights.filter(h => h > 0 && h < sheetHeight).map(h => sheetHeight - h);
+  const ascending = [0, ...collapsed].sort((a, b) => a - b);
+  const deduped = [];
+  for (const offset of ascending) {
+    const last = deduped[deduped.length - 1];
+    if (last === undefined || offset - last >= dedupPx) {
+      deduped.push(offset);
+    }
+  }
+  return deduped;
+}
+
+/** Nearest value in `offsets` to `value` (offsets must be non-empty). */
+export function nearestOffset(value, offsets) {
+  return offsets.reduce((best, o) => Math.abs(o - value) < Math.abs(best - value) ? o : best, offsets[0]);
+}
+
+/**
+ * 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 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, offsets, dismissOffset) {
+  const shortest = offsets[offsets.length - 1];
+  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 floor;
+  }
+  return 1 - (1 - floor) * ((offset - fadeStart) / (fadeEnd - fadeStart));
+}
+
+/**
+ * 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 function resolveSettleOffset(value, offsets, dir, baseOffset) {
+  let candidates = offsets;
+  if (dir > 0) {
+    const downward = offsets.filter(o => o >= baseOffset);
+    if (downward.length > 0) {
+      candidates = downward;
+    }
+  } else if (dir < 0) {
+    const upward = offsets.filter(o => o <= baseOffset);
+    if (upward.length > 0) {
+      candidates = upward;
+    }
+  }
+  return nearestOffset(value, candidates);
+}

package/dist/BottomSheet/useSheetGestures.d.ts

@@ -4,13 +4,14 @@
  * @output Exports useSheetGestures hook and its option/result types
  * @position Internal to BottomSheet; not exported from the lab entry point
  *
- * Drag-to-dismiss machinery for the bottom sheet. Tracks a pointer drag
- * down the block axis, translates the sliding surface live, and on release
- * either dismisses (past a distance or velocity threshold) or springs back
- * to fully open. Pointer-events based so one code path covers mouse + touch.
+ * Drag + snap machinery for the bottom sheet. Tracks a pointer drag down the
+ * block axis, translates the sliding surface live, and on release either
+ * settles to the nearest snap detent (a slow drag) or dismisses (a fast flick
+ * down). A fast flick up expands to the tallest detent. This is the core
+ * behavior split the sheet needs: DRAG places, SWIPE closes.
  *
- * Kept private to BottomSheet: the behavior is sheet-specific (a dismiss
- * edge on a bottom-anchored surface). It is not a general primitive and is
+ * Kept private to BottomSheet: a dismiss edge + detents on a bottom-anchored
+ * surface are inherently sheet concepts. It is not a general primitive and is
  * intentionally not exported.
  *
  * SSR-safe: no window/document access at module scope; all measurement
@@ -25,8 +26,27 @@ import { type CSSProperties, type PointerEvent as ReactPointerEvent } from 'reac
 export interface UseSheetGesturesOptions {
     /** Whether the owning sheet is open. Drag state resets when it closes. */
     isOpen: boolean;
-    /** Called when a drag crosses the dismiss threshold (distance or flick). */
+    /** Called on a swipe-to-close (fast downward flick, or drag past the floor). */
     onDismiss: () => void;
+    /**
+     * Resolver for candidate detent heights in px BELOW the full sheet height.
+     * Called lazily at the start of each drag so the values stay current (e.g.
+     * after a rotation or the virtual keyboard opening) without a persistent
+     * resize listener. The measured full height is always the tallest detent,
+     * so the effective detent set is `[...snapHeights(), fullHeight]`. Omit for
+     * a single-height sheet (a drag then only dismisses or springs back).
+     */
+    snapHeights?: () => number[];
+    /** Notified when the settled detent height (px) changes. */
+    onSnap?: (heightPx: number) => void;
+    /**
+     * 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 — 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;
 }
 export interface SheetContentProps {
     style: CSSProperties;
@@ -38,26 +58,49 @@ export interface SheetHandleProps {
     onPointerUp: (event: ReactPointerEvent) => void;
     onPointerCancel: (event: ReactPointerEvent) => void;
 }
+export interface SheetBodyProps {
+    ref: (node: HTMLElement | null) => void;
+    onPointerDown: (event: ReactPointerEvent) => void;
+    onPointerMove: (event: ReactPointerEvent) => void;
+    onPointerUp: (event: ReactPointerEvent) => void;
+    onPointerCancel: (event: ReactPointerEvent) => void;
+}
 export interface UseSheetGesturesResult {
+    /**
+     * Callback ref for the sheet surface. The hook observes it (ResizeObserver)
+     * to keep the fully-open height current, so detents stay correct across
+     * rotation / viewport changes without re-measuring mid-drag.
+     */
+    sheetRef: (node: HTMLElement | null) => void;
     /** Spread on the sliding surface: live translate + touch-action guard. */
     contentProps: SheetContentProps;
     /** Spread on the grab-handle element: pointer drag handlers. */
     handleProps: SheetHandleProps;
-    /** Current live drag offset in px (positive = dragged toward the edge). */
+    /**
+     * Spread on the scrollable body. An overscroll-at-top pull-down starts a
+     * sheet drag (a larger, more forgiving target when the content isn't itself
+     * scrolling); normal scrolling passes through untouched.
+     */
+    bodyProps: SheetBodyProps;
+    /** Current live drag translate in px (0 = fully expanded, larger = collapsed). */
     dragOffset: number;
+    /** Translate of the resting detent in px (0 = tallest detent). */
+    settledOffset: number;
     /** Whether a drag is currently in progress. */
     isDragging: boolean;
 }
 /**
- * Drag-to-dismiss machinery for the bottom sheet. Returns props to spread on
- * the grab handle and the sliding surface, plus live drag state for callers
- * that want to drive their own animation.
+ * Drag + snap machinery for the bottom sheet. Returns props to spread on the
+ * grab handle and the sliding surface, plus live drag state. A slow drag
+ * settles to the nearest detent; a fast downward flick dismisses; a fast
+ * upward flick expands to the tallest detent.
  *
  * @example
  * ```
  * const {contentProps, handleProps} = useSheetGestures({
  *   isOpen,
  *   onDismiss: () => onOpenChange(false),
+ *   snapHeights: () => [240, 0.5 * (window.visualViewport?.height ?? 0)],
  * });
  * <div {...contentProps}>
  *   <div {...handleProps} />
@@ -65,5 +108,5 @@ export interface UseSheetGesturesResult {
  * </div>
  * ```
  */
-export declare function useSheetGestures({ isOpen, onDismiss, }: UseSheetGesturesOptions): UseSheetGesturesResult;
+export declare function useSheetGestures({ isOpen, onDismiss, snapHeights, onSnap, onScrimOpacity, }: UseSheetGesturesOptions): UseSheetGesturesResult;
 //# sourceMappingURL=useSheetGestures.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useSheetGestures.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/useSheetGestures.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,YAAY,IAAI,iBAAiB,EACvC,MAAM,OAAO,CAAC;AAQf,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,WAAW,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAChD,eAAe,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,YAAY,EAAE,iBAAiB,CAAC;IAChC,gEAAgE;IAChE,WAAW,EAAE,gBAAgB,CAAC;IAC9B,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,EAAE,OAAO,CAAC;CACrB;AASD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,SAAS,GACV,EAAE,uBAAuB,GAAG,sBAAsB,CA4HlD"}
+{"version":3,"file":"useSheetGestures.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/useSheetGestures.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,YAAY,IAAI,iBAAiB,EACvC,MAAM,OAAO,CAAC;AAgEf,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;IAC7B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,aAAa,CAAC;IACrB,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,WAAW,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAChD,eAAe,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACxC,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,aAAa,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAClD,WAAW,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAChD,eAAe,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IAC7C,0EAA0E;IAC1E,YAAY,EAAE,iBAAiB,CAAC;IAChC,gEAAgE;IAChE,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,SAAS,EAAE,cAAc,CAAC;IAC1B,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,UAAU,EAAE,OAAO,CAAC;CACrB;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,SAAS,EACT,WAAW,EACX,MAAM,EACN,cAAc,GACf,EAAE,uBAAuB,GAAG,sBAAsB,CAielD"}