solid-drift 0.22.0 → 0.24.0

package/README.md

@@ -1445,6 +1445,67 @@ createInfiniteScroll(() => sentinel, {
 - `createScrollLock()` returns `{ locked, lock, unlock }`: sets `document.body.style.overflow = "hidden"`, restores the previous value when the last lock releases, and reference-counts nested locks so stacked modals cannot unlock each other early. Unmounting releases the locks.
 - `createInfiniteScroll(ref, options)` observes a sentinel with IntersectionObserver and calls `onLoadMore` as it approaches the viewport (`threshold` px prefetch via `rootMargin`, default `200`). `disabled` is a reactive kill switch (e.g. `() => !hasMore()`).
 
+### Haptics
+
+Tactile feedback through the Vibration API: `createHaptic` wraps `navigator.vibrate` with an iOS-style vocabulary (light/medium/heavy, success/warning/error), one-shot presets, and morse-code encoding; `createHapticBeat` is a 16-step haptic sequencer (heartbeat pulses, metronome ticks, breathing guides) running on the shared animation clock.
+
+```tsx
+import { createHaptic, createHapticBeat, hapticBeatPresets } from "solid-drift"
+
+const haptic = createHaptic()
+// Buttons get a physical click:
+<button onClick={() => { haptic.light(); confirm() }}>Confirm</button>
+// Morse code: dots, dashes, letter gaps, word gaps.
+<button onClick={() => haptic.morse("... --- ...")}>SOS</button>
+
+// A heartbeat pulse the user can toggle:
+const beat = createHapticBeat(haptic, {
+  bpm: 60,
+  pattern: hapticBeatPresets.heartbeat,
+  onStep: (i) => setFlash(i === 0),
+})
+<button onClick={() => beat.toggle()}>
+  {beat.playing() ? "Stop pulse" : "Start pulse"}
+</button>
+```
+
+- `createHaptic(options?)` returns `{ supported, vibrate, light, medium, heavy, success, warning, error, morse }`. `vibrate(pattern)` fires a raw ms pattern; `morse(code, unit?)` encodes `"."`, `"-"`, `" "` (letter gap), `"/"` (word gap) with a configurable dot length (default 60ms). `hapticPatterns` holds the one-shot presets (`tap`, `doubleTap`, `longPress`, `tick`, `heartbeat`, `success`, `warning`, `error`). `options.enabled` is a boolean or a signal master switch (wire it to `useLowPowerMode()`).
+- `createHapticBeat(haptic, options?)` returns `{ playing, bpm, step, start, stop, toggle, setBpm }`. The 16-step pattern uses `"x"` for a hit, `"X"` for an accent, anything else for a rest; steps run as 16th notes at `bpm` (live-changeable via `setBpm`), the downbeat fires immediately on `start()`, and `onStep(i)` reports each step index. `hapticBeatPresets` ships `heartbeat`, `metronome`, `ticks`, and `pulse`.
+- Haptics are tactile, not visual, so they fire under reduced motion too; the `enabled` switch is the way to offer quiet. Everything is a no-op where vibration is unsupported, and SSR-safe.
+
+### Bottom sheet
+
+A draggable bottom sheet built on `createDrag`: the user pulls it up by a handle (or the sheet itself) and on release it springs to the nearest snap point, projected forward by the release velocity like a native sheet. Dragging below the lowest snap (or a fast downward flick) dismisses it when `dismissible`.
+
+```tsx
+import { createBottomSheet } from "solid-drift"
+
+let sheet!: HTMLDivElement
+let handle!: HTMLDivElement
+const bs = createBottomSheet(() => handle, {
+  snapPoints: [0.4, 1],       // fractions of the sheet's own height
+  measureRef: () => sheet,    // measure the sheet, not the handle
+  onOpenChange: (open) => setScrimVisible(open),
+})
+
+<div
+  ref={sheet}
+  style={{
+    position: "fixed", left: "0", right: "0", bottom: "0",
+    transform: `translateY(${bs.y()}px)`,
+  }}
+>
+  <div ref={handle} style={{ "touch-action": "none" }}>Handle</div>
+  <div>Sheet content</div>
+</div>
+<button onClick={() => bs.openSheet()}>Open</button>
+```
+
+- `createBottomSheet(ref, options?)` returns `{ open, snapIndex, y, status, openSheet, close, snapTo }`. `y()` is the current translateY in pixels; `status()` is `idle`, `dragging`, or `settling`; `snapIndex()` is the snap-point index or -1 when dismissed.
+- `snapPoints` are visible height fractions (`1` fully open); values are clamped to [0, 1] and sorted ascending, an empty array falls back to `[1]`. Default `[0.5, 1]`; `initialSnap` (default the fullest) picks the point `openSheet()` opens at.
+- While the pointer is down the sheet tracks 1:1 with light rubber-banding past the fully-open top and the dismissed bottom. On release, the target is the nearest snap to `y + velocity * 0.18`; dismissal happens past the midpoint between the lowest snap and closed, or on a downward flick over 700 px/s. Snap travel uses a spring (`options.spring`, default stiffness 400 / damping 40).
+- Bind `ref` to the drag handle when the sheet body scrolls (keeps drag and scroll from fighting), to the sheet root otherwise. The moving element gets `translateY(y())`; the drag target needs `touch-action: none`. Starts dismissed on the server (SSR-safe); under reduced motion it jumps straight to snap targets.
+
 ### Easings
 
 Named easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutExpo`, `easeOutBack`, plus the cartoon set: `easeInBack` (anticipation dip before movement), `easeInOutBack` (wind-up, overshoot, settle), `easeOutElastic` (decaying rubber-band oscillation), `easeOutBounce` (shrinking cartoon bounces). Also `cubicBezier(x1, y1, x2, y2)` for CSS-style curves. Pass a name or a custom `(t) => number` function anywhere an easing is accepted.

package/dist/haptic.d.ts

@@ -0,0 +1,115 @@
+import { type Accessor } from "solid-js";
+export type HapticPattern = number | number[];
+export interface HapticOptions {
+    /**
+     * Master switch. Accepts a plain boolean or a signal, so it can be
+     * wired to `useLowPowerMode()`. Default true.
+     */
+    enabled?: Accessor<boolean> | boolean;
+}
+export interface HapticControls {
+    /** True when the device can vibrate and haptics are enabled. */
+    supported: Accessor<boolean>;
+    /** Fire a raw vibration pattern (ms). No-op when unsupported. */
+    vibrate: (pattern: HapticPattern) => void;
+    /** Short tap. */
+    light: () => void;
+    /** Firmer tap. */
+    medium: () => void;
+    /** Strong tap. */
+    heavy: () => void;
+    /** Rising two-tap confirmation. */
+    success: () => void;
+    /** Double low tap. */
+    warning: () => void;
+    /** Triple strong tap. */
+    error: () => void;
+    /**
+     * Vibrate morse code: "." dot, "-" dash, " " letter gap, "/" word
+     * gap. `unit` is the dot length in ms (default 60).
+     */
+    morse: (code: string, unit?: number) => void;
+}
+/**
+ * One-shot vibration presets, in milliseconds. Pass any of these to
+ * `vibrate`, or use the named helpers on the controls.
+ */
+export declare const hapticPatterns: Record<string, HapticPattern>;
+/**
+ * Tactile feedback through the Vibration API (`navigator.vibrate`).
+ * Buttons, toggles, and confirmations get a physical click; the
+ * presets mirror the iOS haptic vocabulary (light/medium/heavy,
+ * success/warning/error) using vibration timing.
+ *
+ * Haptics are tactile, not visual, so they still fire under reduced
+ * motion. Gate them with `enabled` (a boolean or a signal) when the
+ * user asks for quiet, e.g. wired to `useLowPowerMode()`.
+ *
+ * SSR-safe and unsupported-device safe: everything is a no-op and
+ * `supported()` is false.
+ *
+ * ```tsx
+ * const haptic = createHaptic()
+ * <button onClick={() => { haptic.light(); confirm() }}>Confirm</button>
+ * <button onClick={() => haptic.morse("... --- ...")}>SOS</button>
+ * ```
+ */
+export declare function createHaptic(options?: HapticOptions): HapticControls;
+/**
+ * 16-step haptic sequencer presets. "x" is a hit, "X" an accent, and
+ * anything else a rest.
+ */
+export declare const hapticBeatPresets: Record<string, string>;
+export interface HapticBeatOptions {
+    /** Beats per minute (quarter notes). Default 60. */
+    bpm?: number;
+    /**
+     * 16-step pattern string: "x" hit, "X" accent, anything else rest.
+     * Shorter strings are padded with rests, longer ones are cut.
+     * Default is the heartbeat preset.
+     */
+    pattern?: string;
+    /** Vibration ms for a normal step. Default 12. */
+    stepMs?: number;
+    /** Vibration ms for an accent step. Default 30. */
+    accentMs?: number;
+    /** Start immediately. Default false. */
+    autostart?: boolean;
+    /** Called on every step with its index (0-15). */
+    onStep?: (step: number) => void;
+}
+export interface HapticBeatControls {
+    /** Whether the sequencer is running. */
+    playing: Accessor<boolean>;
+    /** Current tempo. Change it live with setBpm. */
+    bpm: Accessor<number>;
+    /** Current step index (0-15), or -1 when stopped. */
+    step: Accessor<number>;
+    start: () => void;
+    stop: () => void;
+    toggle: () => void;
+    setBpm: (bpm: number) => void;
+}
+/**
+ * A 16-step haptic sequencer on the shared animation clock: heartbeat
+ * pulses, metronome ticks, breathing guides, game countdowns. The
+ * steps run as 16th notes at `bpm`, so a 60 BPM heartbeat preset
+ * pulses once per second with the accent on the downbeat.
+ *
+ * Takes the haptic controls from `createHaptic` (so one `enabled`
+ * switch gates everything) and drives `vibrate` per step. Tempo
+ * changes apply live. SSR-safe: `start()` is a no-op on the server.
+ *
+ * ```tsx
+ * const haptic = createHaptic()
+ * const beat = createHapticBeat(haptic, {
+ *   bpm: 60,
+ *   pattern: hapticBeatPresets.heartbeat,
+ *   onStep: (i) => setFlash(i === 0),
+ * })
+ * <button onClick={() => beat.toggle()}>
+ *   {beat.playing() ? "Stop pulse" : "Start pulse"}
+ * </button>
+ * ```
+ */
+export declare function createHapticBeat(haptic: Pick<HapticControls, "vibrate">, options?: HapticBeatOptions): HapticBeatControls;

package/dist/haptic.js

@@ -0,0 +1,200 @@
+import { createSignal, onCleanup } from "solid-js";
+import { now, schedule } from "./engine.js";
+/**
+ * One-shot vibration presets, in milliseconds. Pass any of these to
+ * `vibrate`, or use the named helpers on the controls.
+ */
+export const hapticPatterns = {
+    tap: 10,
+    doubleTap: [15, 50, 15],
+    longPress: 60,
+    tick: 8,
+    heartbeat: [25, 150, 40],
+    success: [10, 40, 25],
+    warning: [30, 50, 30],
+    error: [50, 50, 50, 50, 80],
+};
+/**
+ * Tactile feedback through the Vibration API (`navigator.vibrate`).
+ * Buttons, toggles, and confirmations get a physical click; the
+ * presets mirror the iOS haptic vocabulary (light/medium/heavy,
+ * success/warning/error) using vibration timing.
+ *
+ * Haptics are tactile, not visual, so they still fire under reduced
+ * motion. Gate them with `enabled` (a boolean or a signal) when the
+ * user asks for quiet, e.g. wired to `useLowPowerMode()`.
+ *
+ * SSR-safe and unsupported-device safe: everything is a no-op and
+ * `supported()` is false.
+ *
+ * ```tsx
+ * const haptic = createHaptic()
+ * <button onClick={() => { haptic.light(); confirm() }}>Confirm</button>
+ * <button onClick={() => haptic.morse("... --- ...")}>SOS</button>
+ * ```
+ */
+export function createHaptic(options = {}) {
+    const enabled = typeof options.enabled === "function"
+        ? options.enabled
+        : () => options.enabled !== false;
+    const canVibrate = typeof navigator !== "undefined" &&
+        typeof navigator.vibrate === "function";
+    const supported = () => canVibrate && enabled();
+    const vibrate = (pattern) => {
+        if (!supported())
+            return;
+        try {
+            navigator.vibrate(pattern);
+        }
+        catch {
+            // Haptics are best-effort: never crash the interaction.
+        }
+    };
+    const morse = (code, unit = 60) => {
+        const u = Math.max(1, Math.round(unit));
+        const pattern = [];
+        for (const ch of code) {
+            if (ch === ".") {
+                pattern.push(u, u);
+            }
+            else if (ch === "-") {
+                pattern.push(3 * u, u);
+            }
+            else if (ch === " " || ch === "/") {
+                // Extend the trailing pause: a letter gap is 3 units total, a
+                // word gap 7, and one unit is already there after each element.
+                const last = pattern.length - 1;
+                if (last >= 0)
+                    pattern[last] += ch === " " ? 2 * u : 6 * u;
+            }
+        }
+        // Drop the trailing pause: nothing to separate after the last element.
+        if (pattern.length % 2 === 0)
+            pattern.pop();
+        if (pattern.length > 0)
+            vibrate(pattern);
+    };
+    return {
+        supported,
+        vibrate,
+        light: () => vibrate(hapticPatterns.tap),
+        medium: () => vibrate(20),
+        heavy: () => vibrate(30),
+        success: () => vibrate(hapticPatterns.success),
+        warning: () => vibrate(hapticPatterns.warning),
+        error: () => vibrate(hapticPatterns.error),
+        morse,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* createHapticBeat                                                     */
+/* ------------------------------------------------------------------ */
+/**
+ * 16-step haptic sequencer presets. "x" is a hit, "X" an accent, and
+ * anything else a rest.
+ */
+export const hapticBeatPresets = {
+    /** Lub-dub heartbeat. */
+    heartbeat: "X.......x.......",
+    /** Four-on-the-floor metronome. */
+    metronome: "X...x...x...x...",
+    /** Steady eighth-note ticks. */
+    ticks: "x.x.x.x.x.x.x.x.",
+    /** One pulse per bar. */
+    pulse: "X...............",
+};
+function parseSteps(pattern) {
+    const steps = [];
+    for (let i = 0; i < 16; i++) {
+        const ch = pattern[i];
+        steps.push(ch === "X" ? 2 : ch === "x" ? 1 : 0);
+    }
+    return steps;
+}
+/**
+ * A 16-step haptic sequencer on the shared animation clock: heartbeat
+ * pulses, metronome ticks, breathing guides, game countdowns. The
+ * steps run as 16th notes at `bpm`, so a 60 BPM heartbeat preset
+ * pulses once per second with the accent on the downbeat.
+ *
+ * Takes the haptic controls from `createHaptic` (so one `enabled`
+ * switch gates everything) and drives `vibrate` per step. Tempo
+ * changes apply live. SSR-safe: `start()` is a no-op on the server.
+ *
+ * ```tsx
+ * const haptic = createHaptic()
+ * const beat = createHapticBeat(haptic, {
+ *   bpm: 60,
+ *   pattern: hapticBeatPresets.heartbeat,
+ *   onStep: (i) => setFlash(i === 0),
+ * })
+ * <button onClick={() => beat.toggle()}>
+ *   {beat.playing() ? "Stop pulse" : "Start pulse"}
+ * </button>
+ * ```
+ */
+export function createHapticBeat(haptic, options = {}) {
+    const { bpm: initialBpm = 60, pattern = hapticBeatPresets.heartbeat, stepMs = 12, accentMs = 30, autostart = false, onStep, } = options;
+    const steps = parseSteps(pattern);
+    const [playing, setPlaying] = createSignal(false);
+    const [bpm, setBpm] = createSignal(Math.max(1, initialBpm));
+    const [step, setStep] = createSignal(-1);
+    let cancel = null;
+    const stepDuration = () => 60000 / bpm() / 4;
+    const fire = (index) => {
+        setStep(index);
+        const kind = steps[index];
+        if (kind === 2)
+            haptic.vibrate(accentMs);
+        else if (kind === 1)
+            haptic.vibrate(stepMs);
+        onStep?.(index);
+    };
+    const start = () => {
+        if (typeof window === "undefined")
+            return; // SSR: no-op
+        if (playing())
+            return;
+        setPlaying(true);
+        let index = 0;
+        fire(0); // no latency: the downbeat lands immediately
+        let nextTime = now() + stepDuration();
+        cancel = schedule((t) => {
+            if (!playing())
+                return false;
+            const dur = stepDuration();
+            while (t >= nextTime) {
+                index = (index + 1) % 16;
+                fire(index);
+                nextTime += dur;
+                if (nextTime < t - 250) {
+                    // Long main-thread stall: skip ahead instead of
+                    // machine-gunning the missed steps.
+                    nextTime = t + dur;
+                    break;
+                }
+            }
+            return true;
+        });
+    };
+    const stop = () => {
+        if (!playing())
+            return;
+        setPlaying(false);
+        setStep(-1);
+        cancel?.();
+        cancel = null;
+    };
+    onCleanup(stop);
+    if (autostart)
+        start();
+    return {
+        playing,
+        bpm,
+        step,
+        start,
+        stop,
+        toggle: () => (playing() ? stop() : start()),
+        setBpm: (next) => setBpm(Math.max(1, next)),
+    };
+}

package/dist/index.d.ts

@@ -15,6 +15,8 @@ export { isLowPowerMode, useLowPowerMode, type LowPowerOptions, } from "./power.
 export { createSlotMachine, type SlotMachineControls, type SlotMachineOptions, type SlotMachineStatus, createRedPacket, type RedPacketCoin, type RedPacketControls, type RedPacketOptions, type RedPacketStatus, createConfetti, type ConfettiControls, type ConfettiOptions, createEmojiBurst, type EmojiBurstControls, type EmojiBurstOptions, createScratch, type ScratchControls, type ScratchOptions, } from "./fun.js";
 export { createStagger } from "./stagger.js";
 export { createDebounced, createThrottled, createLocalStorage, type LocalStorageOptions, type LocalStorageControls, createMediaQuery, createClickOutside, type ClickOutsideOptions, createScrollLock, type ScrollLockControls, createInfiniteScroll, type InfiniteScrollOptions, } from "./dom.js";
+export { createHaptic, hapticPatterns, type HapticOptions, type HapticControls, type HapticPattern, createHapticBeat, hapticBeatPresets, type HapticBeatOptions, type HapticBeatControls, } from "./haptic.js";
+export { createBottomSheet, type BottomSheetOptions, type BottomSheetControls, } from "./sheet.js";
 export { createHorizontalScroll, type HorizontalScrollOptions, type HorizontalScrollResult, } from "./horizontal.js";
 export { createScrub, type ScrubKeyframe, type ScrubOptions } from "./scrub.js";
 export { createScrollColor, type ScrollColorStop, type ScrollColorOptions, type ScrollColorFormat, createScrollTracking, type ScrollTrackingOptions, createScrollLine, type ScrollLineOptions, type ScrollLineStyle, type ScrollLineAxis, type ScrollLineOrigin, } from "./scrollfx.js";

package/dist/index.js

@@ -15,6 +15,8 @@ export { isLowPowerMode, useLowPowerMode, } from "./power.js";
 export { createSlotMachine, createRedPacket, createConfetti, createEmojiBurst, createScratch, } from "./fun.js";
 export { createStagger } from "./stagger.js";
 export { createDebounced, createThrottled, createLocalStorage, createMediaQuery, createClickOutside, createScrollLock, createInfiniteScroll, } from "./dom.js";
+export { createHaptic, hapticPatterns, createHapticBeat, hapticBeatPresets, } from "./haptic.js";
+export { createBottomSheet, } from "./sheet.js";
 export { createHorizontalScroll, } from "./horizontal.js";
 export { createScrub } from "./scrub.js";
 export { createScrollColor, createScrollTracking, createScrollLine, } from "./scrollfx.js";

package/dist/sheet.d.ts

@@ -0,0 +1,99 @@
+import { type Accessor } from "solid-js";
+import { type DragStatus } from "./gesture.js";
+import type { SpringOptions } from "./spring.js";
+type MaybeElement = () => Element | null | undefined;
+export interface BottomSheetOptions {
+    /**
+     * Snap points as fractions of the sheet's own height. `1` is fully
+     * open, `0.4` shows 40% of the sheet. Values are clamped to
+     * [0, 1] and sorted ascending; an empty array falls back to [1].
+     * Default `[0.5, 1]`.
+     */
+    snapPoints?: number[];
+    /**
+     * Index into `snapPoints` opened by `openSheet()` with no argument.
+     * Default is the last point (fully open).
+     */
+    initialSnap?: number;
+    /**
+     * Dragging below the lowest snap dismisses the sheet on release.
+     * Default true.
+     */
+    dismissible?: boolean;
+    /** Spring physics for snap animations. Default `{ stiffness: 400, damping: 40 }`. */
+    spring?: SpringOptions;
+    /**
+     * Element used to measure the sheet height. Defaults to the drag
+     * ref. Pass the sheet root here when the drag ref is a handle, so
+     * snap fractions apply to the sheet and not the handle.
+     */
+    measureRef?: MaybeElement;
+    /** Called when the sheet opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+}
+export interface BottomSheetControls {
+    /** Whether the sheet is open (not dismissed). */
+    open: Accessor<boolean>;
+    /** Index into `snapPoints`, or -1 when dismissed. */
+    snapIndex: Accessor<number>;
+    /**
+     * Current translateY in pixels. Drive the sheet's transform with
+     * this: `transform: translateY(${y()}px)`.
+     */
+    y: Accessor<number>;
+    /** `idle`, `dragging` while the pointer is down, `settling` while snapping. */
+    status: Accessor<DragStatus>;
+    /** Open the sheet at a snap point (default the fullest). */
+    openSheet: (index?: number) => void;
+    /** Dismiss the sheet below the screen. */
+    close: () => void;
+    /** Snap to a point by index (opens the sheet if dismissed). */
+    snapTo: (index: number) => void;
+}
+/**
+ * A draggable bottom sheet built on `createDrag`.
+ *
+ * The sheet is a fixed, bottom-anchored panel the user drags by a
+ * handle (or the sheet itself). On release it snaps to the nearest
+ * snap point, projected forward by the release velocity like a
+ * native sheet; a downward drag past the lowest point (or a fast
+ * downward flick) dismisses it when `dismissible`.
+ *
+ * The drag gesture itself, pointer tracking, release velocity, and
+ * reduced-motion behavior come from `createDrag`; this primitive
+ * adds the snap-point semantics on top. While the pointer is down
+ * the sheet tracks 1:1 with light rubber-banding past the top and
+ * bottom edges; on release it springs to the chosen point.
+ *
+ * Bind the `ref` to the drag handle when the sheet body scrolls
+ * (a handle keeps drag and scroll from fighting); bind it to the
+ * sheet root for non-scrolling sheets. Either way the moving
+ * element gets `transform: translateY(${y()}px)` and the drag
+ * target gets `touch-action: none`. When the drag ref is a handle,
+ * pass the sheet root as `options.measureRef` so snap fractions
+ * are measured against the sheet.
+ *
+ * SSR-safe: starts dismissed with `y()` at 0 on the server.
+ *
+ * ```tsx
+ * let sheet!: HTMLDivElement
+ * let handle!: HTMLDivElement
+ * const bs = createBottomSheet(() => handle, {
+ *   snapPoints: [0.4, 1],
+ *   measureRef: () => sheet,
+ * })
+ * <div
+ *   ref={sheet}
+ *   style={{
+ *     position: "fixed", left: "0", right: "0", bottom: "0",
+ *     transform: `translateY(${bs.y()}px)`,
+ *   }}
+ * >
+ *   <div ref={handle} style={{ "touch-action": "none" }}>Handle</div>
+ *   <div>Sheet content</div>
+ * </div>
+ * <button onClick={() => bs.openSheet()}>Open</button>
+ * ```
+ */
+export declare function createBottomSheet(ref: MaybeElement, options?: BottomSheetOptions): BottomSheetControls;
+export {};

package/dist/sheet.js

@@ -0,0 +1,219 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { createDrag, } from "./gesture.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * A draggable bottom sheet built on `createDrag`.
+ *
+ * The sheet is a fixed, bottom-anchored panel the user drags by a
+ * handle (or the sheet itself). On release it snaps to the nearest
+ * snap point, projected forward by the release velocity like a
+ * native sheet; a downward drag past the lowest point (or a fast
+ * downward flick) dismisses it when `dismissible`.
+ *
+ * The drag gesture itself, pointer tracking, release velocity, and
+ * reduced-motion behavior come from `createDrag`; this primitive
+ * adds the snap-point semantics on top. While the pointer is down
+ * the sheet tracks 1:1 with light rubber-banding past the top and
+ * bottom edges; on release it springs to the chosen point.
+ *
+ * Bind the `ref` to the drag handle when the sheet body scrolls
+ * (a handle keeps drag and scroll from fighting); bind it to the
+ * sheet root for non-scrolling sheets. Either way the moving
+ * element gets `transform: translateY(${y()}px)` and the drag
+ * target gets `touch-action: none`. When the drag ref is a handle,
+ * pass the sheet root as `options.measureRef` so snap fractions
+ * are measured against the sheet.
+ *
+ * SSR-safe: starts dismissed with `y()` at 0 on the server.
+ *
+ * ```tsx
+ * let sheet!: HTMLDivElement
+ * let handle!: HTMLDivElement
+ * const bs = createBottomSheet(() => handle, {
+ *   snapPoints: [0.4, 1],
+ *   measureRef: () => sheet,
+ * })
+ * <div
+ *   ref={sheet}
+ *   style={{
+ *     position: "fixed", left: "0", right: "0", bottom: "0",
+ *     transform: `translateY(${bs.y()}px)`,
+ *   }}
+ * >
+ *   <div ref={handle} style={{ "touch-action": "none" }}>Handle</div>
+ *   <div>Sheet content</div>
+ * </div>
+ * <button onClick={() => bs.openSheet()}>Open</button>
+ * ```
+ */
+export function createBottomSheet(ref, options = {}) {
+    const { snapPoints: snapPointsOption, initialSnap: initialSnapOption, dismissible = true, spring = {}, measureRef, onOpenChange, } = options;
+    // Snap points are visible height fractions, ascending. Values are
+    // clamped to [0, 1] and sorted; an empty list falls back to [1]
+    // (a single fully-open snap).
+    const snapPoints = (snapPointsOption?.length ? [...snapPointsOption] : [1])
+        .map((p) => Math.min(1, Math.max(0, p)))
+        .sort((a, b) => a - b);
+    const initialSnap = initialSnapOption ?? snapPoints.length - 1;
+    const [open, setOpen] = createSignal(false);
+    const [snapIndex, setSnapIndex] = createSignal(-1);
+    const [y, setY] = createSignal(0);
+    const [snapping, setSnapping] = createSignal(false);
+    // Sheet height in px, measured lazily from the element.
+    let height = 0;
+    const measure = () => {
+        const el = (measureRef ?? ref)();
+        if (el && typeof el.offsetHeight === "number") {
+            const h = el.offsetHeight;
+            if (h > 0)
+                height = h;
+        }
+        return height;
+    };
+    const snapY = (index) => height * (1 - snapPoints[index]);
+    const closedY = () => height;
+    // Snap animation: the same semi-implicit Euler spring the gesture
+    // primitives use.
+    let cancelSnap = null;
+    const animateTo = (target) => {
+        cancelSnap?.();
+        cancelSnap = null;
+        if (prefersReducedMotion()) {
+            setY(target);
+            setSnapping(false);
+            return;
+        }
+        const { stiffness = 400, damping = 40 } = spring;
+        let current = untrack(y);
+        let v = 0;
+        let last = now();
+        setSnapping(true);
+        const task = (t) => {
+            const dt = Math.min(Math.max((t - last) / 1000, 0), 0.064);
+            last = t;
+            v += (-stiffness * (current - target) - damping * v) * dt;
+            current += v * dt;
+            setY(current);
+            if (Math.abs(current - target) < 0.5 && Math.abs(v) < 20) {
+                setY(target);
+                setSnapping(false);
+                cancelSnap = null;
+                return false;
+            }
+            return true;
+        };
+        cancelSnap = schedule(task);
+    };
+    onCleanup(() => cancelSnap?.());
+    const openAt = (index) => {
+        measure();
+        const i = Math.max(0, Math.min(snapPoints.length - 1, index));
+        if (!untrack(open)) {
+            setOpen(true);
+            onOpenChange?.(true);
+        }
+        setSnapIndex(i);
+        animateTo(snapY(i));
+    };
+    const close = () => {
+        measure();
+        if (untrack(open)) {
+            setOpen(false);
+            onOpenChange?.(false);
+        }
+        setSnapIndex(-1);
+        animateTo(closedY());
+    };
+    // The underlying gesture: pointer tracking and release velocity.
+    // Its own y is only ever used as a per-grab delta source; the
+    // sheet position lives in `y` above.
+    let dragBase = 0;
+    let sheetBase = 0;
+    const settleFromRelease = (info) => {
+        measure();
+        const releaseY = untrack(y);
+        const projected = releaseY + info.velocityY * 0.18;
+        const lowest = snapY(0);
+        const dismissLine = (lowest + height) / 2;
+        if (dismissible &&
+            (projected >= dismissLine ||
+                (info.velocityY > 700 && projected > lowest))) {
+            close();
+            return;
+        }
+        let best = 0;
+        let bestDist = Math.abs(snapY(0) - projected);
+        for (let i = 1; i < snapPoints.length; i++) {
+            const d = Math.abs(snapY(i) - projected);
+            if (d < bestDist) {
+                bestDist = d;
+                best = i;
+            }
+        }
+        openAt(best);
+    };
+    const drag = createDrag(ref, {
+        axis: "y",
+        momentum: false, // the sheet chooses its own snap target
+        onDragStart: () => {
+            cancelSnap?.();
+            cancelSnap = null;
+            setSnapping(false);
+            measure();
+        },
+        onDragEnd: settleFromRelease,
+    });
+    // 1:1 tracking while the pointer is down, with rubber-banding past
+    // the fully-open top and the dismissed bottom. The grab bases are
+    // captured on the transition into "dragging" inside this effect:
+    // writes from event handlers flush effects synchronously, so the
+    // effect runs during setStatus("dragging"), before onDragStart.
+    // Capturing here keeps the bases correct under any scheduling.
+    let prevDragStatus = "idle";
+    createEffect(() => {
+        const s = drag.status();
+        if (s === "dragging" && prevDragStatus !== "dragging") {
+            dragBase = drag.y();
+            sheetBase = untrack(y);
+        }
+        prevDragStatus = s;
+        if (s !== "dragging")
+            return;
+        const raw = sheetBase + (drag.y() - dragBase);
+        const h = height;
+        let next = raw;
+        if (next < 0)
+            next = next * 0.3;
+        else if (next > h)
+            next = h + (next - h) * 0.3;
+        setY(next);
+    });
+    const status = () => {
+        if (drag.status() === "dragging")
+            return "dragging";
+        return snapping() ? "settling" : "idle";
+    };
+    // Client-only: park the dismissed sheet below the screen once the
+    // element (and its height) exists.
+    if (typeof window !== "undefined") {
+        createEffect(() => {
+            const el = ref();
+            const mel = (measureRef ?? ref)();
+            if (!el || !mel)
+                return;
+            const h = measure();
+            if (!untrack(open) && untrack(snapIndex) === -1)
+                setY(h);
+        });
+    }
+    return {
+        open,
+        snapIndex,
+        y,
+        status,
+        openSheet: (index = initialSnap) => openAt(index),
+        close,
+        snapTo: openAt,
+    };
+}

package/package.json

@@ -43,5 +43,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.22.0"
+  "version": "0.24.0"
 }