@astryxdesign/core 0.4.4 → 0.4.5-canary.1fdecb1

package/dist/BottomSheet/snapOffsets.js

@@ -3,9 +3,9 @@
 /**
  * @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.
+ * @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
@@ -14,6 +14,20 @@
  * 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.
+ */
+
 /**
  * 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
@@ -22,9 +36,63 @@
  */
 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);
+/**
+ * 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, viewportPx) {
+  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) {
+  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, viewportPx) {
+  const heights = [];
+  for (const point of points) {
+    const height = parseSnapPoint(point, viewportPx);
+    if (height !== null) {
+      heights.push(height);
+    }
+  }
+  return heights;
 }
 
 /**
@@ -65,38 +133,46 @@ export function nearestOffset(value, offsets) {
 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 detent's offset, or `null` when this sheet has no peek.
  *
- * 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.
+ * 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 isPeekOffset(offset, offsets, tolerancePx = 0.5) {
-  if (offsets.length < 2) {
-    return false;
+export function peekOffsetFor(offsets, visibleSheetHeight) {
+  if (offsets.length < 2 || visibleSheetHeight <= 0) {
+    return null;
   }
-  return Math.abs(offset - offsets[offsets.length - 1]) <= tolerancePx;
+  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 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).
+ *
+ * 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, 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.
+export function scrimOpacityForOffset(offset, offsets, dismissOffset, peekOffset) {
+  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;

package/dist/BottomSheet/useSheetGestures.d.ts

@@ -15,14 +15,16 @@
  * the part the scrolling area gives up as layout height, and the remainder is
  * a transform. Gestures and snaps only ever move the transform, so they stay
  * on the compositor; layout height changes at rest, in one transition-free
- * render whose visible geometry is identical. The peek detent keeps the full
- * height and slides below the viewport instead of reflowing to a sliver.
+ * render whose visible geometry is identical. A peek detent — a stop that is
+ * only a sliver of the sheet — keeps the full height and slides below the
+ * viewport instead of reflowing to that sliver.
  *
- * Those are pixels, and the detents behind them are viewport fractions, so a
- * sheet at rest re-resolves its detent on `resize` / `orientationchange` and
- * re-anchors to the new geometry without animating. The detent it returns to
- * is tracked by index: the pixels stop meaning the same thing when the
- * viewport changes, the stop the user chose does not.
+ * Those are pixels, and the stops behind them are relative to the viewport, so
+ * a sheet at rest re-resolves its detent on `resize` / `orientationchange`,
+ * and whenever the host swaps the snap points, and re-anchors to the new
+ * geometry without animating. The detent it returns to is tracked by index:
+ * the pixels stop meaning the same thing when the viewport changes, the stop
+ * the user chose does not.
  *
  * On touch, the scrolling body hands the gesture to the sheet at a scroll
  * edge. Two shapes, because the browser only offers one of them a choice: a
@@ -70,6 +72,9 @@ export interface UseSheetGesturesOptions {
      * (rotation, a resized desktop window, collapsing browser chrome). The fully
      * open height is always the tallest detent. Omit for a single-height sheet
      * (a drag then only dismisses or springs back).
+     *
+     * Keep the identity stable: a new function is read as new stops, and
+     * re-anchors a resting sheet to them.
      */
     snapHeights?: () => number[];
     /** Notified when the settled visible detent height (px) changes. */
@@ -153,7 +158,7 @@ export interface UseSheetGesturesResult {
     /**
      * How much of `settledOffset` is expressed as layout height rather than as a
      * transform. Equals `settledOffset` at the resizing detents; 0 at fully open
-     * and at the peek, which keep the sheet's full height (see isPeekOffset).
+     * and at the peek, which keep the sheet's full height (see peekOffsetFor).
      */
     settledLayoutOffset: number;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"useSheetGestures.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/useSheetGestures.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useSheetGestures.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/useSheetGestures.ts"],"names":[],"mappings":"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"}

package/dist/BottomSheet/useSheetGestures.js

@@ -19,14 +19,16 @@
  * the part the scrolling area gives up as layout height, and the remainder is
  * a transform. Gestures and snaps only ever move the transform, so they stay
  * on the compositor; layout height changes at rest, in one transition-free
- * render whose visible geometry is identical. The peek detent keeps the full
- * height and slides below the viewport instead of reflowing to a sliver.
+ * render whose visible geometry is identical. A peek detent — a stop that is
+ * only a sliver of the sheet — keeps the full height and slides below the
+ * viewport instead of reflowing to that sliver.
  *
- * Those are pixels, and the detents behind them are viewport fractions, so a
- * sheet at rest re-resolves its detent on `resize` / `orientationchange` and
- * re-anchors to the new geometry without animating. The detent it returns to
- * is tracked by index: the pixels stop meaning the same thing when the
- * viewport changes, the stop the user chose does not.
+ * Those are pixels, and the stops behind them are relative to the viewport, so
+ * a sheet at rest re-resolves its detent on `resize` / `orientationchange`,
+ * and whenever the host swaps the snap points, and re-anchors to the new
+ * geometry without animating. The detent it returns to is tracked by index:
+ * the pixels stop meaning the same thing when the viewport changes, the stop
+ * the user chose does not.
  *
  * On touch, the scrolling body hands the gesture to the sheet at a scroll
  * edge. Two shapes, because the browser only offers one of them a choice: a
@@ -51,7 +53,12 @@
  */
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { useMediaQuery } from "../hooks/index.js";
-import { computeDetentOffsets, isPeekOffset, resolveSettleOffset, scrimOpacityForOffset } from "./snapOffsets.js";
+import { computeDetentOffsets, peekOffsetFor, resolveSettleOffset, scrimOpacityForOffset } from "./snapOffsets.js";
+
+/**
+ * The stops a sheet of a given height rests at: offsets from fully-open in px,
+ * ascending, plus which of them (if any) is the peek.
+ */
 
 // A flick (fast throw) dismisses (down) or expands (up) regardless of where
 // it ends. Requires both a speed and a distance floor so a small nudge
@@ -64,6 +71,18 @@ const DISMISS_OVERSHOOT_RATIO = 0.4;
 // Within this many px of a detent, the live drag is magnetically eased toward
 // it so it "clicks" into place instead of hovering just off the mark.
 const MAGNET_RANGE = 40;
+// The touch path drives the sheet through the same machinery the pointer path
+// uses, by handing it a pointer-shaped object built from a `Touch`. On iOS
+// Safari that object is indistinguishable from the real thing: WebKit raises
+// PointerEvents for a finger under the SAME numeric id it puts in
+// `Touch.identifier`, so such a drag is keyed to a live pointer and the
+// handlers that guard a mouse drag fire against it. Mark the synthetic object
+// so they can tell the two apart.
+
+function isSyntheticTouch(event) {
+  return event.syntheticTouch === true;
+}
+
 // Rubber-band factor for dragging up past fully-open, capped at OVERSCROLL_MAX
 // (the sheet reserves that much bottom padding for the lift to reveal).
 const OVERSCROLL_RESISTANCE = 0.35;
@@ -174,7 +193,7 @@ export function useSheetGestures({
   const [scrollPreservationInset, setScrollPreservationInset] = useState(0);
   // How much of the settled travel is expressed as layout height. Equal to
   // settledOffset for the resizing detents, and 0 at fully open and at the
-  // peek (see isPeekOffset), which keep the full height and use a transform.
+  // peek (see peekOffsetFor), which keep the full height and use a transform.
   const [settledLayoutOffset, setSettledLayoutOffset] = useState(0);
   const settledLayoutOffsetRef = useRef(0);
   // WHICH detent the sheet rests on, as an index into the resolved list. The
@@ -242,17 +261,22 @@ export function useSheetGestures({
   activeOffsetRef.current = isDragging ? dragOffset : settledOffset;
   const isOpenRef = useRef(isOpen);
   isOpenRef.current = isOpen;
+
+  // The resolver is refreshed during render, not with the callbacks below: the
+  // layout effect that re-anchors on a change to it runs BEFORE passive
+  // effects, so a resolver parked in one would still be the previous set of
+  // stops by the time the re-anchor read it.
+  const snapHeightsRef = useRef(snapHeights);
+  snapHeightsRef.current = snapHeights;
   const onDismissRef = useRef(onDismiss);
   const canDismissRef = useRef(canDismiss);
   const onSnapRef = useRef(onSnap);
   const onScrimOpacityRef = useRef(onScrimOpacity);
-  const snapHeightsRef = useRef(snapHeights);
   useEffect(() => {
     onDismissRef.current = onDismiss;
     canDismissRef.current = canDismiss;
     onSnapRef.current = onSnap;
     onScrimOpacityRef.current = onScrimOpacity;
-    snapHeightsRef.current = snapHeights;
   });
 
   // Live drag bookkeeping (refs so pointermove doesn't churn renders).
@@ -349,13 +373,18 @@ export function useSheetGestures({
     return sheetElRef.current?.getBoundingClientRect().height ?? 0;
   }, []);
 
-  // Detent translate offsets (px) from the tallest detent, ascending. Exclude
-  // the border-box portion reserved below the viewport before comparing the
-  // candidate visible heights; otherwise every snap point lands that many px
-  // too low. Snap heights are resolved lazily so they track the viewport.
-  const detentOffsets = useCallback(height => {
+  // Detent translate offsets (px) from the tallest detent, ascending, plus the
+  // peek among them. Exclude the border-box portion reserved below the
+  // viewport before comparing the candidate visible heights; otherwise every
+  // snap point lands that many px too low. Snap heights are resolved lazily so
+  // they track the viewport.
+  const resolveDetents = useCallback(height => {
     const visibleSheetHeight = visibleHeightForOffset(height, 0, offscreenBlockEndInsetRef.current);
-    return computeDetentOffsets(visibleSheetHeight, snapHeightsRef.current?.() ?? []);
+    const offsets = computeDetentOffsets(visibleSheetHeight, snapHeightsRef.current?.() ?? []);
+    return {
+      offsets,
+      peekOffset: peekOffsetFor(offsets, visibleSheetHeight)
+    };
   }, []);
 
   // The height the sheet WOULD have fully open, right now. While it rests at a
@@ -389,48 +418,71 @@ export function useSheetGestures({
   //
   // Re-resolve the SAME detent — by index, the one thing that survives the
   // units changing — against the new geometry, and re-anchor without
-  // animating: the viewport moved, not the user's finger, so there is no
+  // animating: the geometry moved, not the user's finger, so there is no
   // gesture to continue and nothing to ease.
+  const reanchorToSettledDetent = useCallback(() => {
+    // A closed sheet re-anchors on its way back open; a live drag re-measures
+    // on its own, and a settle in flight owns the layout until it lands.
+    if (!isOpenRef.current || dragStateRef.current != null || settlingLayoutOffsetRef.current != null) {
+      return;
+    }
+    const height = measureFullyOpenHeight();
+    if (height <= 0) {
+      return;
+    }
+    const {
+      offsets,
+      peekOffset
+    } = resolveDetents(height);
+    const index = Math.min(settledDetentIndexRef.current, offsets.length - 1);
+    const target = offsets[index];
+    const targetLayoutOffset = target === peekOffset ? 0 : target;
+    const baseLayoutOffset = settledLayoutOffsetRef.current;
+    if (height === sheetHeightRef.current && Math.abs(target - activeOffsetRef.current) <= 0.5 && Math.abs(targetLayoutOffset - baseLayoutOffset) <= 0.5) {
+      return;
+    }
+    sheetHeightRef.current = height;
+    // Re-anchoring is a measurement: the geometry it reads is only knowable
+    // after layout, so the state it corrects can only be set from an effect
+    // (or, on the resize path, from the listener). Both writes below are
+    // guarded by the equality check above, so a re-anchor that finds nothing
+    // to change sets nothing.
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- corrects settled geometry from a measurement
+    setSheetHeight(height);
+    settledDetentIndexRef.current = index;
+    prepareScrollAreaSettle(baseLayoutOffset, target, targetLayoutOffset, target, baseLayoutOffset, naturalEndGapFor(bodyNodeRef.current), false);
+    recordSettledLayoutOffset(targetLayoutOffset);
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- corrects settled geometry from a measurement
+    setSettledOffset(target);
+    onSnapRef.current?.(visibleHeightForOffset(height, target, offscreenBlockEndInsetRef.current));
+    const maxOffset = offsets[offsets.length - 1];
+    const shortestDetentHeight = visibleHeightForOffset(height, maxOffset, offscreenBlockEndInsetRef.current);
+    onScrimOpacityRef.current?.(scrimOpacityForOffset(target, offsets, maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO, peekOffset));
+  }, [measureFullyOpenHeight, prepareScrollAreaSettle, recordSettledLayoutOffset, resolveDetents]);
   useEffect(() => {
     if (!isOpen || typeof window === 'undefined') {
       return;
     }
-    const handleViewportChange = () => {
-      // A live drag re-measures on its own, and a settle in flight owns the
-      // layout until it lands.
-      if (dragStateRef.current != null || settlingLayoutOffsetRef.current != null) {
-        return;
-      }
-      const height = measureFullyOpenHeight();
-      if (height <= 0) {
-        return;
-      }
-      const offsets = detentOffsets(height);
-      const index = Math.min(settledDetentIndexRef.current, offsets.length - 1);
-      const target = offsets[index];
-      const targetLayoutOffset = isPeekOffset(target, offsets) ? 0 : target;
-      const baseLayoutOffset = settledLayoutOffsetRef.current;
-      if (height === sheetHeightRef.current && Math.abs(target - activeOffsetRef.current) <= 0.5 && Math.abs(targetLayoutOffset - baseLayoutOffset) <= 0.5) {
-        return;
-      }
-      sheetHeightRef.current = height;
-      setSheetHeight(height);
-      settledDetentIndexRef.current = index;
-      prepareScrollAreaSettle(baseLayoutOffset, target, targetLayoutOffset, target, baseLayoutOffset, naturalEndGapFor(bodyNodeRef.current), false);
-      recordSettledLayoutOffset(targetLayoutOffset);
-      setSettledOffset(target);
-      onSnapRef.current?.(visibleHeightForOffset(height, target, offscreenBlockEndInsetRef.current));
-      const maxOffset = offsets[offsets.length - 1];
-      const shortestDetentHeight = visibleHeightForOffset(height, maxOffset, offscreenBlockEndInsetRef.current);
-      onScrimOpacityRef.current?.(scrimOpacityForOffset(target, offsets, maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO));
-    };
-    window.addEventListener('resize', handleViewportChange);
-    window.addEventListener('orientationchange', handleViewportChange);
+    window.addEventListener('resize', reanchorToSettledDetent);
+    window.addEventListener('orientationchange', reanchorToSettledDetent);
     return () => {
-      window.removeEventListener('resize', handleViewportChange);
-      window.removeEventListener('orientationchange', handleViewportChange);
+      window.removeEventListener('resize', reanchorToSettledDetent);
+      window.removeEventListener('orientationchange', reanchorToSettledDetent);
     };
-  }, [detentOffsets, isOpen, measureFullyOpenHeight, prepareScrollAreaSettle, recordSettledLayoutOffset]);
+  }, [isOpen, reanchorToSettledDetent]);
+
+  // The other input to the same geometry: the snap points themselves. A host
+  // that swaps them while the sheet rests has moved the stops out from under
+  // it, exactly as a rotation does, so re-anchor the same way. Skipped on the
+  // first run — the sheet is already anchored to the detents it opened with.
+  const hasAnchoredSnapHeightsRef = useRef(false);
+  useLayoutEffect(() => {
+    if (!hasAnchoredSnapHeightsRef.current) {
+      hasAnchoredSnapHeightsRef.current = true;
+      return;
+    }
+    reanchorToSettledDetent();
+  }, [reanchorToSettledDetent, snapHeights]);
   const cancelDrag = useCallback(target => {
     const state = dragStateRef.current;
     if (state == null) {
@@ -450,12 +502,15 @@ export function useSheetGestures({
     // An interrupted drag returns to its previous resting detent. Restore
     // the matching scrim opacity as well so the modal shell cannot remain
     // dimmed with its sheet translated out of view.
-    const offsets = detentOffsets(state.height);
+    const {
+      offsets,
+      peekOffset
+    } = resolveDetents(state.height);
     const maxOffset = offsets[offsets.length - 1];
     const shortestDetentHeight = visibleHeightForOffset(state.height, maxOffset, offscreenBlockEndInsetRef.current);
     const dismissOffset = maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
-    onScrimOpacityRef.current?.(scrimOpacityForOffset(state.baseOffset, offsets, dismissOffset));
-  }, [detentOffsets, prepareScrollAreaSettle]);
+    onScrimOpacityRef.current?.(scrimOpacityForOffset(state.baseOffset, offsets, dismissOffset, peekOffset));
+  }, [prepareScrollAreaSettle, resolveDetents]);
   useEffect(() => {
     const handleWindowBlur = () => cancelDrag();
     const handleVisibilityChange = () => {
@@ -471,7 +526,10 @@ export function useSheetGestures({
     };
   }, [cancelDrag]);
   const settleFromDrag = useCallback((offset, velocity, height, dir, travel, baseOffset, baseLayoutOffset, renderedOffset, layoutOffset, naturalEndGap) => {
-    const offsets = detentOffsets(height);
+    const {
+      offsets,
+      peekOffset
+    } = resolveDetents(height);
     const maxOffset = offsets[offsets.length - 1];
     const shortestDetentHeight = visibleHeightForOffset(height, maxOffset, offscreenBlockEndInsetRef.current);
     const speed = Math.abs(velocity);
@@ -479,14 +537,14 @@ export function useSheetGestures({
     const settleAt = target => {
       // A peek keeps the full layout height and slides below the viewport;
       // every taller detent resizes the scrolling area to what it shows.
-      const targetLayoutOffset = isPeekOffset(target, offsets) ? 0 : target;
+      const targetLayoutOffset = target === peekOffset ? 0 : target;
       prepareScrollAreaSettle(baseLayoutOffset, target, targetLayoutOffset, renderedOffset, layoutOffset, naturalEndGap, true);
       recordSettledLayoutOffset(targetLayoutOffset);
       settledDetentIndexRef.current = Math.max(0, offsets.indexOf(target));
       setSettledOffset(target);
       onSnapRef.current?.(visibleHeightForOffset(height, target, offscreenBlockEndInsetRef.current));
       const dismissOffset = maxOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
-      onScrimOpacityRef.current?.(scrimOpacityForOffset(target, offsets, dismissOffset));
+      onScrimOpacityRef.current?.(scrimOpacityForOffset(target, offsets, dismissOffset, peekOffset));
       if (target !== baseOffset) {
         hapticTick();
       }
@@ -526,10 +584,19 @@ export function useSheetGestures({
     // the starting detent), de-duped and direction-clamped by the util.
     const target = resolveSettleOffset(offset, offsets, dir, baseOffset);
     settleAt(target);
-  }, [detentOffsets, prepareScrollAreaSettle, recordSettledLayoutOffset]);
+  }, [prepareScrollAreaSettle, recordSettledLayoutOffset, resolveDetents]);
   const beginDrag = useCallback((event, sheetHeight, startCoord) => {
     const target = event.currentTarget;
-    target.setPointerCapture?.(event.pointerId);
+    const syntheticTouch = isSyntheticTouch(event);
+    // Never capture for a touch drag. The id came from `Touch.identifier`,
+    // which on iOS names a live pointer: the capture succeeds, WebKit takes
+    // it straight back for its own gesture handling, and the
+    // `lostpointercapture` a millisecond later cancels the drag that just
+    // started. Touch drags need no capture — the listener is on the
+    // scroller itself.
+    if (!syntheticTouch) {
+      target.setPointerCapture?.(event.pointerId);
+    }
     // `startCoord` lets a body-overscroll drag anchor at the original
     // pointer-down position (not the promotion point), so the first frame's
     // delta reflects the full pull distance.
@@ -537,6 +604,7 @@ export function useSheetGestures({
     const naturalEndGap = naturalEndGapFor(bodyNodeRef.current);
     const baseLayoutOffset = settledLayoutOffsetRef.current;
     dragStateRef.current = {
+      syntheticTouch,
       pointerId: event.pointerId,
       startCoord: start,
       lastCoord: event.clientY,
@@ -573,6 +641,12 @@ export function useSheetGestures({
     cancelDrag(event.currentTarget);
   }, [cancelDrag]);
   const handleLostPointerCapture = useCallback(event => {
+    // A touch drag never took capture, so this is WebKit reclaiming its own
+    // pointer for the finger doing the dragging — not the drag losing its
+    // grip.
+    if (dragStateRef.current?.syntheticTouch) {
+      return;
+    }
     if (dragStateRef.current?.pointerId === event.pointerId) {
       cancelDrag();
     }
@@ -582,6 +656,11 @@ export function useSheetGestures({
     if (!state || state.pointerId !== event.pointerId) {
       return;
     }
+    // Same finger, real pointer event: the touch path already drove this
+    // move. Let it own the drag rather than driving it twice.
+    if (state.syntheticTouch && !isSyntheticTouch(event)) {
+      return;
+    }
     const delta = event.clientY - state.startCoord;
     const dt = event.timeStamp - state.lastTime;
     if (dt > 0) {
@@ -589,7 +668,10 @@ export function useSheetGestures({
       state.lastCoord = event.clientY;
       state.lastTime = event.timeStamp;
     }
-    const offsets = detentOffsets(state.height);
+    const {
+      offsets,
+      peekOffset
+    } = resolveDetents(state.height);
     const raw = state.baseOffset + delta;
     const maxDetentOffset = offsets[offsets.length - 1];
     let next;
@@ -618,19 +700,27 @@ export function useSheetGestures({
     const floorOffset = offsets[offsets.length - 1];
     const shortestDetentHeight = visibleHeightForOffset(state.height, floorOffset, offscreenBlockEndInsetRef.current);
     const dismissOffset = floorOffset + shortestDetentHeight * DISMISS_OVERSHOOT_RATIO;
-    onScrimOpacityRef.current?.(scrimOpacityForOffset(next, offsets, dismissOffset));
-  }, [detentOffsets, updateScrollPreservationInset]);
+    onScrimOpacityRef.current?.(scrimOpacityForOffset(next, offsets, dismissOffset, peekOffset));
+  }, [resolveDetents, updateScrollPreservationInset]);
   const endDrag = useCallback(event => {
     const state = dragStateRef.current;
     if (!state || state.pointerId !== event.pointerId) {
       return;
     }
+    // `pointercancel` fires for the finger the moment WebKit claims the
+    // gesture; ending a touch drag on it settles the sheet mid-pull. The
+    // touchend handler is what finishes a touch drag.
+    if (state.syntheticTouch && !isSyntheticTouch(event)) {
+      return;
+    }
     const target = event.currentTarget;
     const delta = event.clientY - state.startCoord;
     const offset = Math.max(0, state.baseOffset + delta);
     const dir = delta === 0 ? 0 : delta > 0 ? 1 : -1;
     dragStateRef.current = null;
-    target.releasePointerCapture?.(event.pointerId);
+    if (!state.syntheticTouch) {
+      target.releasePointerCapture?.(event.pointerId);
+    }
     setIsDragging(false);
     settleFromDrag(offset, state.velocity, state.height || 1, dir, Math.abs(delta), state.baseOffset, state.baseLayoutOffset, state.renderedOffset, state.layoutOffset, state.naturalEndGap);
   }, [settleFromDrag]);
@@ -677,6 +767,11 @@ export function useSheetGestures({
   }, [beginDrag, handlePointerMove, measureHeight]);
   const handleBodyEnd = useCallback(event => {
     armedBodyRef.current = null;
+    // The pointerup/pointercancel for a finger already driving a touch drag
+    // arrives here carrying that drag's own id; touchend ends those.
+    if (dragStateRef.current?.syntheticTouch) {
+      return;
+    }
     if (dragStateRef.current) {
       endDrag(event);
     }
@@ -705,6 +800,7 @@ export function useSheetGestures({
   });
   const bodyRef = useCallback(node => {
     const asPointer = (touch, target) => ({
+      syntheticTouch: true,
       pointerId: touch.identifier,
       clientY: touch.clientY,
       timeStamp: Date.now(),

package/dist/Calendar/Calendar.d.ts

@@ -22,6 +22,23 @@ interface CalendarBaseProps extends Omit<BaseProps<HTMLDivElement>, 'onChange' |
      * Use for complex rules like "weekdays only" or "no holidays".
      */
     dateConstraints?: ReadonlyArray<(date: Date) => boolean>;
+    /**
+     * Range mode only. Maximum number of days a selected range may span,
+     * counting both endpoints — `maxRangeSpan={7}` allows a 7-day window
+     * (start + 6 days). Once a start date is picked, days beyond this distance
+     * from it are disabled in either direction; before a start is picked every
+     * otherwise-valid day stays selectable. Use for rolling windows like "at
+     * most a week from the chosen day". For fixed calendar bounds use min/max.
+     */
+    maxRangeSpan?: number;
+    /**
+     * Range mode only. Minimum number of days a selected range must span,
+     * counting both endpoints — `minRangeSpan={2}` forbids a single-day range.
+     * Once a start date is picked, days closer than this to it are disabled —
+     * except the start itself, which stays selectable as the active anchor.
+     * Defaults to 1 (a same-day start and end is allowed).
+     */
+    minRangeSpan?: number;
     /**
      * Controlled focus date (which month is visible).
      * If not provided, defaults to selected date or today.