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

package/src/BottomSheet/snapOffsets.test.ts

@@ -0,0 +1,146 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file snapOffsets.test.ts
+ * @input Uses vitest, snapOffsets pure helpers
+ * @output Unit tests for the snap-point -> translateY offset geometry
+ * @position Testing; validates snapOffsets.ts (no DOM needed)
+ *
+ * SYNC: When snapOffsets.ts changes, update these tests to match.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {
+  snapFractionsToHeights,
+  computeDetentOffsets,
+  nearestOffset,
+  resolveSettleOffset,
+  scrimOpacityForOffset,
+  DETENT_DEDUP_PX,
+} from './snapOffsets';
+
+describe('snapFractionsToHeights', () => {
+  it('scales in-range fractions to px', () => {
+    expect(snapFractionsToHeights([0.5, 0.92], 800)).toEqual([400, 736]);
+  });
+  it('drops out-of-range fractions', () => {
+    expect(snapFractionsToHeights([0, 0.5, 1, 1.2, -0.3], 1000)).toEqual([
+      500, 1000,
+    ]);
+  });
+});
+
+describe('computeDetentOffsets', () => {
+  it('always includes fully-open (0) first, ascending', () => {
+    // sheet 800; detent visible heights 400, 640 -> offsets 400, 160 -> sorted
+    expect(computeDetentOffsets(800, [400, 640])).toEqual([0, 160, 400]);
+  });
+
+  it('drops detents at or taller than the sheet (cannot translate up)', () => {
+    // 800 and 900 are >= sheet 800 -> dropped; only 500 (offset 300) remains
+    expect(computeDetentOffsets(800, [500, 800, 900])).toEqual([0, 300]);
+  });
+
+  it('de-dupes near-equal detents, keeping the taller (smaller offset)', () => {
+    // sheet 800; heights 760 (offset 40) and 400 (offset 400). 40 is within
+    // DETENT_DEDUP_PX of the fully-open 0 -> collapses to just [0, 400].
+    expect(computeDetentOffsets(800, [760, 400])).toEqual([0, 400]);
+  });
+
+  it('keeps detents that are farther apart than the dedup threshold', () => {
+    // offsets 0, 100, 400 with default 48px dedup -> all kept
+    expect(computeDetentOffsets(800, [700, 400])).toEqual([0, 100, 400]);
+  });
+
+  it('respects a custom dedup threshold', () => {
+    // offsets 0, 100, 400; dedup 150 -> 100 collapses into 0
+    expect(computeDetentOffsets(800, [700, 400], 150)).toEqual([0, 400]);
+  });
+
+  it('a single-height sheet has just the fully-open detent', () => {
+    expect(computeDetentOffsets(600, [])).toEqual([0]);
+  });
+});
+
+describe('nearestOffset', () => {
+  it('picks the closest offset', () => {
+    expect(nearestOffset(180, [0, 200, 400])).toBe(200);
+    expect(nearestOffset(90, [0, 200, 400])).toBe(0);
+  });
+});
+
+describe('resolveSettleOffset', () => {
+  const offsets = [0, 200, 400]; // full, mid, short
+
+  it('a down-drag never settles above the starting detent', () => {
+    // start at mid (200), drag down to ~240 -> nearest at/below is 200 (mid),
+    // never back up to 0.
+    expect(resolveSettleOffset(240, offsets, 1, 200)).toBe(200);
+  });
+
+  it('a down-drag past the midpoint moves to the next lower detent', () => {
+    // start mid (200), drag to 320 -> nearest at/below is 400 (short)
+    expect(resolveSettleOffset(320, offsets, 1, 200)).toBe(400);
+  });
+
+  it('an up-drag never settles below the starting detent', () => {
+    // start mid (200), drag up to ~160 -> nearest at/above is 0 or 200; 160 is
+    // closer to 200, so it holds mid rather than dropping to short.
+    expect(resolveSettleOffset(160, offsets, -1, 200)).toBe(200);
+  });
+
+  it('an up-drag past the midpoint expands to the next higher detent', () => {
+    // start mid (200), drag up to 80 -> nearest at/above is 0 (full)
+    expect(resolveSettleOffset(80, offsets, -1, 200)).toBe(0);
+  });
+
+  it('with no direction, picks the plain nearest', () => {
+    expect(resolveSettleOffset(180, offsets, 0, 200)).toBe(200);
+  });
+});
+
+describe('scrimOpacityForOffset', () => {
+  describe('with a peek detent (>= 2 detents)', () => {
+    const offsets = [0, 100, 200]; // full, mid, peek
+    const dismissOffset = 280;
+
+    it('is full at or above the mid detent', () => {
+      expect(scrimOpacityForOffset(0, offsets, dismissOffset)).toBe(1);
+      expect(scrimOpacityForOffset(100, offsets, dismissOffset)).toBe(1);
+      expect(scrimOpacityForOffset(60, offsets, dismissOffset)).toBe(1);
+    });
+
+    it('fades linearly from the mid detent to the peek', () => {
+      expect(scrimOpacityForOffset(150, offsets, dismissOffset)).toBeCloseTo(
+        0.5,
+      );
+    });
+
+    it('is hidden at or below the peek detent', () => {
+      expect(scrimOpacityForOffset(200, offsets, dismissOffset)).toBe(0);
+      expect(scrimOpacityForOffset(240, offsets, dismissOffset)).toBe(0);
+    });
+  });
+
+  describe('with a single detent (no peek)', () => {
+    const offsets = [0];
+    const dismissOffset = 160;
+
+    it('stays full until the drag begins collapsing', () => {
+      expect(scrimOpacityForOffset(0, offsets, dismissOffset)).toBe(1);
+    });
+
+    it('fades across the dismiss overshoot toward the threshold', () => {
+      expect(scrimOpacityForOffset(80, offsets, dismissOffset)).toBeCloseTo(
+        0.5,
+      );
+      expect(scrimOpacityForOffset(160, offsets, dismissOffset)).toBe(0);
+    });
+  });
+});
+
+describe('DETENT_DEDUP_PX', () => {
+  it('is a sane positive threshold', () => {
+    expect(DETENT_DEDUP_PX).toBeGreaterThan(0);
+  });
+});

package/src/BottomSheet/snapOffsets.ts

@@ -0,0 +1,126 @@
+// 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: readonly number[],
+  viewportPx: number,
+): number[] {
+  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: number,
+  detentHeights: readonly number[],
+  dedupPx: number = DETENT_DEDUP_PX,
+): number[] {
+  const collapsed = detentHeights
+    .filter(h => h > 0 && h < sheetHeight)
+    .map(h => sheetHeight - h);
+  const ascending = [0, ...collapsed].sort((a, b) => a - b);
+
+  const deduped: number[] = [];
+  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: number,
+  offsets: readonly number[],
+): number {
+  return offsets.reduce(
+    (best, o) => (Math.abs(o - value) < Math.abs(best - value) ? o : best),
+    offsets[0],
+  );
+}
+
+/**
+ * Scrim opacity (1 = fully visible, 0 = hidden) 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`.
+ */
+export function scrimOpacityForOffset(
+  offset: number,
+  offsets: readonly number[],
+  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;
+  if (offset <= fadeStart) {
+    return 1;
+  }
+  if (offset >= fadeEnd) {
+    return 0;
+  }
+  return 1 - (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: number,
+  offsets: readonly number[],
+  dir: number,
+  baseOffset: number,
+): number {
+  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/src/BottomSheet/useSheetGestures.doc.mjs

@@ -1,15 +1,15 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../../../core/src/docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'useSheetGestures',
   displayName: 'useSheetGestures',
-  keywords: ['sheet', 'drag', 'swipe', 'dismiss', 'gesture', 'pointer', 'touch', 'bottom sheet'],
+  keywords: ['sheet', 'drag', 'swipe', 'snap', 'detent', 'dismiss', 'gesture', 'pointer', 'touch', 'bottom sheet'],
   params: [
     {
       name: 'options',
       type: 'UseSheetGesturesOptions',
-      description: 'isOpen and onDismiss. 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, 1->0 as the sheet collapses onto its peek detent, for a glance affordance). Internal to BottomSheet, not exported from the lab entry point.',
       required: true,
     },
   ],
@@ -17,15 +17,16 @@ export const docs = {
     {
       name: 'result',
       type: 'UseSheetGesturesResult',
-      description: 'contentProps (spread on the sliding surface for the live translate + touch-action guard), handleProps (spread on the grab handle for the pointer drag), plus dragOffset and isDragging for callers that want to drive their own animation.',
+      description: 'contentProps (spread on the sliding surface for the live translate + touch-action guard), handleProps (spread on the grab handle for the pointer drag), plus dragOffset, settledOffset, and isDragging for callers that want to drive their own animation.',
     },
   ],
   usage: {
     description:
-      'Drag-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 (one path for mouse + touch), SSR-safe, and respects prefers-reduced-motion. Escape (routed by the owning dialog) provides the keyboard equivalent of the swipe.',
+      'Drag + snap machinery for the bottom sheet. A slow drag on the handle resizes the sheet live and, on release, settles to the nearest snap detent; a fast downward flick dismisses (swipe-to-close); a fast upward flick expands to the tallest detent. The measured sheet height is always the tallest detent, and snapHeights add shorter rest points beneath it. Pointer-events based (one path for mouse + touch), SSR-safe, and respects prefers-reduced-motion. Escape (routed by the owning dialog) provides the keyboard equivalent of the dismiss swipe.',
     bestPractices: [
       { guidance: true, description: 'Spread handleProps on the grab-handle element and contentProps on the sliding surface (the panel that carries the translate).' },
-      { guidance: false, description: 'Wire onDismiss to anything other than the owning sheet close; it fires when a swipe crosses the dismiss threshold.' },
+      { guidance: true, description: 'Pass snapHeights in px relative to the viewport; the hook filters out any that are >= the measured sheet height.' },
+      { guidance: false, description: 'Wire onDismiss to anything other than the owning sheet close; it fires on a swipe-to-close or a drag past the shortest detent.' },
     ],
   },
 };