@astryxdesign/core 0.4.2 → 0.4.3-canary.00bed29

package/src/BottomSheet/snapOffsets.test.ts

@@ -0,0 +1,187 @@
+// 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,
+  isPeekOffset,
+  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('isPeekOffset', () => {
+  const offsets = [0, 100, 200]; // full, mid, peek
+
+  it('is true only for the shortest detent', () => {
+    expect(isPeekOffset(200, offsets)).toBe(true);
+    expect(isPeekOffset(100, offsets)).toBe(false);
+    expect(isPeekOffset(0, offsets)).toBe(false);
+  });
+
+  it('tolerates sub-pixel rounding around the peek', () => {
+    expect(isPeekOffset(200.4, offsets)).toBe(true);
+    expect(isPeekOffset(199.6, offsets)).toBe(true);
+    expect(isPeekOffset(196, offsets)).toBe(false);
+  });
+
+  it('has no peek when the sheet has no collapsed stop', () => {
+    expect(isPeekOffset(200, [0])).toBe(false);
+    expect(isPeekOffset(0, [0])).toBe(false);
+  });
+
+  it('treats the only collapsed stop as the peek', () => {
+    expect(isPeekOffset(200, [0, 200])).toBe(true);
+  });
+
+  it('agrees with the detent scrimOpacityForOffset treats as the peek', () => {
+    const dismissOffset = 280;
+    const peek = offsets[offsets.length - 1];
+    expect(isPeekOffset(peek, offsets)).toBe(true);
+    expect(scrimOpacityForOffset(peek, offsets, dismissOffset)).toBeCloseTo(
+      0.3,
+    );
+  });
+});
+
+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 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.65,
+      );
+    });
+
+    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,
+      );
+    });
+  });
+
+  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,159 @@
+// 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.
+ *
+ * A detent is represented as an offset in px from the fully-open position
+ * (0 = fully open, larger = more collapsed). The panel may render that offset
+ * as a translate or as a reduction in layout height. These
+ * helpers turn snap points into the shared 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: ReadonlyArray<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 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 is already covered by the fully-open stop.
+ * - 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: ReadonlyArray<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: ReadonlyArray<number>,
+): number {
+  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;
+
+/**
+ * Whether `offset` is the peek detent: the shortest stop, where the sheet is a
+ * glance rather than a working surface. A sheet with no collapsed stop at all
+ * has no peek — the same rule `scrimOpacityForOffset` thins the scrim by.
+ *
+ * The peek is the one detent the sheet does NOT express as layout height: at a
+ * sliver of viewport there is nothing useful to lay out, and reflowing the
+ * content into it (then back out on the way up) is churn the user sees. It
+ * keeps the full layout height and slides below the viewport instead.
+ */
+export function isPeekOffset(
+  offset: number,
+  offsets: ReadonlyArray<number>,
+  tolerancePx: number = 0.5,
+): boolean {
+  if (offsets.length < 2) {
+    return false;
+  }
+  return Math.abs(offset - offsets[offsets.length - 1]) <= tolerancePx;
+}
+
+/**
+ * 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: number,
+  offsets: ReadonlyArray<number>,
+  dismissOffset: number,
+): number {
+  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: number,
+  offsets: ReadonlyArray<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);
+}