@astryxdesign/core 0.4.3 → 0.4.4-canary.0e8af82

package/src/BottomSheet/snapOffsets.test.ts

@@ -0,0 +1,254 @@
+// 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 {
+  computeDetentOffsets,
+  isValidSnapPoint,
+  nearestOffset,
+  peekOffsetFor,
+  resolveSettleOffset,
+  resolveSnapPoints,
+  scrimOpacityForOffset,
+  DETENT_DEDUP_PX,
+} from './snapOffsets';
+
+describe('resolveSnapPoints', () => {
+  it('reads a bare number as a fraction of the viewport', () => {
+    expect(resolveSnapPoints([0.5, 0.92], 800)).toEqual([400, 736]);
+  });
+
+  it('reads a percentage as the same fraction', () => {
+    expect(resolveSnapPoints(['50%', '92%'], 800)).toEqual([400, 736]);
+  });
+
+  it('reads a px length as an absolute height', () => {
+    expect(resolveSnapPoints(['320px'], 800)).toEqual([320]);
+  });
+
+  it('keeps the caller order, mixing forms', () => {
+    expect(resolveSnapPoints(['120px', 0.5, '90%'], 800)).toEqual([
+      120, 400, 720,
+    ]);
+  });
+
+  it('accepts fractional and unit-cased lengths, and surrounding space', () => {
+    expect(resolveSnapPoints(['12.5%', '0.5PX', ' 80px '], 800)).toEqual([
+      100, 0.5, 80,
+    ]);
+  });
+
+  it('drops numbers outside the (0, 1] fraction range', () => {
+    // 200 is the px mistake — a bare number is never a length.
+    expect(resolveSnapPoints([0, 0.5, 1, 1.2, -0.3, 200], 1000)).toEqual([
+      500, 1000,
+    ]);
+  });
+
+  it('drops lengths it cannot resolve by arithmetic on the viewport', () => {
+    expect(
+      resolveSnapPoints(
+        ['50', '30rem', '50vh', 'calc(50% - 20px)', '-10px', '', '0px'],
+        800,
+      ),
+    ).toEqual([]);
+  });
+});
+
+describe('isValidSnapPoint', () => {
+  it('accepts the three supported forms', () => {
+    expect(isValidSnapPoint(0.5)).toBe(true);
+    expect(isValidSnapPoint(1)).toBe(true);
+    expect(isValidSnapPoint('50%')).toBe(true);
+    expect(isValidSnapPoint('320px')).toBe(true);
+  });
+
+  it('rejects what resolveSnapPoints would silently drop', () => {
+    expect(isValidSnapPoint(200)).toBe(false);
+    expect(isValidSnapPoint(0)).toBe(false);
+    expect(isValidSnapPoint('50')).toBe(false);
+    expect(isValidSnapPoint('50vh')).toBe(false);
+    expect(isValidSnapPoint('calc(50% - 20px)')).toBe(false);
+  });
+});
+
+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('peekOffsetFor', () => {
+  it('is the shortest stop when that stop is a sliver', () => {
+    // sheet 800; stops at 800, 400 and 100 visible px. The 100px stop is an
+    // eighth of the sheet, well inside the quarter that makes a peek.
+    expect(peekOffsetFor([0, 400, 700], 800)).toBe(700);
+  });
+
+  it('has no peek when the shortest stop is a working height', () => {
+    // A half-height stop lays its content out and keeps a full scrim; it is
+    // the sheet the caller asked for, not a glance at one.
+    expect(peekOffsetFor([0, 400], 800)).toBeNull();
+  });
+
+  it('has no peek when the sheet has no collapsed stop', () => {
+    expect(peekOffsetFor([0], 800)).toBeNull();
+  });
+
+  it('takes the quarter mark itself as a peek', () => {
+    expect(peekOffsetFor([0, 600], 800)).toBe(600);
+  });
+
+  it('has no peek without a measured sheet', () => {
+    expect(peekOffsetFor([0, 600], 0)).toBeNull();
+  });
+});
+
+describe('scrimOpacityForOffset', () => {
+  describe('with a peek detent', () => {
+    const offsets = [0, 100, 200]; // full, mid, peek
+    const peekOffset = 200;
+    const dismissOffset = 280;
+
+    it('is full at or above the mid detent', () => {
+      expect(scrimOpacityForOffset(0, offsets, dismissOffset, peekOffset)).toBe(
+        1,
+      );
+      expect(
+        scrimOpacityForOffset(100, offsets, dismissOffset, peekOffset),
+      ).toBe(1);
+      expect(
+        scrimOpacityForOffset(60, offsets, dismissOffset, peekOffset),
+      ).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, peekOffset),
+      ).toBeCloseTo(0.65);
+    });
+
+    it('thins to the peek floor at or below the peek detent (still modal)', () => {
+      expect(
+        scrimOpacityForOffset(200, offsets, dismissOffset, peekOffset),
+      ).toBeCloseTo(0.3);
+      expect(
+        scrimOpacityForOffset(240, offsets, dismissOffset, peekOffset),
+      ).toBeCloseTo(0.3);
+    });
+  });
+
+  describe('with collapsed stops but no peek among them', () => {
+    // The shortest stop is a working height, so the scrim is full there and
+    // only fades once the sheet is being dragged out below it.
+    const offsets = [0, 100];
+    const dismissOffset = 160;
+
+    it('stays full at every stop, including the shortest', () => {
+      expect(scrimOpacityForOffset(0, offsets, dismissOffset, null)).toBe(1);
+      expect(scrimOpacityForOffset(100, offsets, dismissOffset, null)).toBe(1);
+    });
+
+    it('fades only across the dismiss overshoot below the shortest stop', () => {
+      expect(
+        scrimOpacityForOffset(130, offsets, dismissOffset, null),
+      ).toBeCloseTo(0.5);
+      expect(scrimOpacityForOffset(160, offsets, dismissOffset, null)).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, null)).toBe(1);
+    });
+
+    it('fades across the dismiss overshoot toward the threshold', () => {
+      expect(
+        scrimOpacityForOffset(80, offsets, dismissOffset, null),
+      ).toBeCloseTo(0.5);
+      expect(scrimOpacityForOffset(160, offsets, dismissOffset, null)).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,245 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file snapOffsets.ts
+ * @input Pure geometry helpers — no React, no DOM.
+ * @output Resolves snap points and converts them to translateY offsets.
+ * @position Internal to BottomSheet; consumed by useSheetGestures and
+ *   BottomSheetPanel, 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.
+ */
+
+/**
+ * A height the sheet can rest at, expressed as the sheet's VISIBLE height:
+ *
+ * - a number in `(0, 1]` — a fraction of the viewport (`0.5` is half the
+ *   screen), so the stop tracks rotation and window resizes;
+ * - a `'<n>%'` string — the same thing spelled in CSS;
+ * - a `'<n>px'` string — an absolute height that does not scale.
+ *
+ * Anything else — a unitless string, `calc()`, `vh`, `rem`, a number outside
+ * `(0, 1]` — is ignored with a dev warning. Percentages resolve against the
+ * layout viewport (`window.innerHeight`), the same box the height budgets are
+ * written against, so the mobile keyboard never moves a stop.
+ */
+export type BottomSheetSnapPoint = number | string;
+
+/**
+ * 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;
+
+/**
+ * Largest share of the fully open sheet the shortest stop may fill and still
+ * be a peek. Above it the stop is a working surface — it lays its content out
+ * and keeps a full scrim — so a two-stop sheet like `[0.5]` behaves like the
+ * half-height panel it asks for rather than like a glance.
+ */
+export const PEEK_MAX_HEIGHT_RATIO = 0.25;
+
+// A snap point string: a positive number with a `px` or `%` unit. Deliberately
+// narrow — every accepted unit has to be resolvable by arithmetic on the
+// viewport height, because this runs inside the drag loop. Units that need the
+// DOM to resolve (`rem`, `em`, `calc()`) would cost a layout per frame.
+const SNAP_POINT_PATTERN = /^(\d+(?:\.\d+)?|\.\d+)(px|%)$/i;
+
+/**
+ * Resolve one snap point to a visible height in px, or `null` when it is not a
+ * snap point this sheet can honor.
+ */
+function parseSnapPoint(
+  point: BottomSheetSnapPoint,
+  viewportPx: number,
+): number | null {
+  if (typeof point === 'number') {
+    // A bare number is a viewport fraction. Anything above 1 is a px value in
+    // disguise; the caller warns rather than guessing which was meant.
+    return Number.isFinite(point) && point > 0 && point <= 1
+      ? point * viewportPx
+      : null;
+  }
+  const match = SNAP_POINT_PATTERN.exec(point.trim());
+  if (match === null) {
+    return null;
+  }
+  const value = Number.parseFloat(match[1]);
+  if (!(value > 0)) {
+    return null;
+  }
+  return match[2].toLowerCase() === '%' ? (value / 100) * viewportPx : value;
+}
+
+/**
+ * Whether a snap point can be resolved at all. The viewport only scales the
+ * result, so validity is independent of it.
+ */
+export function isValidSnapPoint(point: BottomSheetSnapPoint): boolean {
+  return parseSnapPoint(point, 1) !== null;
+}
+
+/**
+ * Resolve snap points to candidate visible heights in px, dropping the ones
+ * this sheet cannot honor. Callers warn about those separately — this stays
+ * silent because it runs on every drag frame.
+ */
+export function resolveSnapPoints(
+  points: ReadonlyArray<BottomSheetSnapPoint>,
+  viewportPx: number,
+): number[] {
+  const heights: number[] = [];
+  for (const point of points) {
+    const height = parseSnapPoint(point, viewportPx);
+    if (height !== null) {
+      heights.push(height);
+    }
+  }
+  return heights;
+}
+
+/**
+ * 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;
+
+/**
+ * The peek detent's offset, or `null` when this sheet has no peek.
+ *
+ * A peek is the shortest stop AND a sliver — at most `PEEK_MAX_HEIGHT_RATIO`
+ * of the fully open sheet. It is the one detent the sheet does NOT express as
+ * layout height: at a sliver 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, so
+ * it keeps the full layout height and slides below the viewport instead. It is
+ * also the only stop that thins the scrim.
+ *
+ * A sheet whose shortest stop is a working height — `[0.5]`, say — has no
+ * peek: half a screen of content deserves to be laid out at half a screen, and
+ * a scrim that thinned there would read as a dismissed sheet.
+ */
+export function peekOffsetFor(
+  offsets: ReadonlyArray<number>,
+  visibleSheetHeight: number,
+): number | null {
+  if (offsets.length < 2 || visibleSheetHeight <= 0) {
+    return null;
+  }
+  const shortest = offsets[offsets.length - 1];
+  const heightAtShortest = visibleSheetHeight - shortest;
+  return heightAtShortest <= PEEK_MAX_HEIGHT_RATIO * visibleSheetHeight
+    ? shortest
+    : null;
+}
+
+/**
+ * Scrim opacity (1 = fully visible) for a drag/settle `offset`.
+ *
+ * The scrim is full down to the shortest stop that is still a working surface,
+ * and only thins past it — onto a peek, where it holds at
+ * `MIN_PEEK_SCRIM_OPACITY` (a glance state, and the sheet is still modal), or
+ * out through the dismiss overshoot toward `dismissOffset`, where it clears
+ * completely because the sheet is leaving.
+ *
+ * So a sheet whose stops are all working heights keeps a full scrim at every
+ * one of them; only the sliver of a peek, or a sheet on its way out, dims less.
+ */
+export function scrimOpacityForOffset(
+  offset: number,
+  offsets: ReadonlyArray<number>,
+  dismissOffset: number,
+  peekOffset: number | null,
+): number {
+  const hasPeek = peekOffset !== null;
+  // The last stop that is still a working surface — the peek's neighbor when
+  // there is a peek, otherwise the shortest stop itself.
+  const fadeStart = hasPeek
+    ? offsets[offsets.length - 2]
+    : offsets[offsets.length - 1];
+  const fadeEnd = hasPeek ? peekOffset : dismissOffset;
+  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);
+}