solid-drift 0.21.0 → 0.23.0

package/README.md

@@ -1390,6 +1390,89 @@ const scratch = createScratch(() => foil, {
 
 Options: `threshold` (fraction cleared to complete, default `0.45`), `brush` (eraser radius in px, default `26`), `paint(ctx, w, h)` (custom cover art), `onComplete`. Returns `{ cleared, done, reset }`: `cleared()` is the 0..1 fraction erased, `reset()` repaints the cover. Scratching is direct manipulation, so it works identically under reduced motion. SSR-safe: `cleared()` stays 0.
 
+### DOM utilities
+
+Everyday DOM glue, signal-native: debounced and throttled signal transforms, a persisted signal, a live media query, outside-press dismissal, body scroll locking, and infinite scroll. All SSR-safe.
+
+```tsx
+import {
+  createDebounced,
+  createThrottled,
+  createLocalStorage,
+  createMediaQuery,
+  createClickOutside,
+  createScrollLock,
+  createInfiniteScroll,
+} from "solid-drift"
+
+// Debounced search: the query waits for a 300ms pause before firing.
+const [query, setQuery] = createSignal("")
+const debounced = createDebounced(query, 300)
+createEffect(() => { if (debounced()) search(debounced()) })
+
+// Throttled scroll position: at most one update per 100ms.
+const throttledY = createThrottled(scrollY, 100)
+
+// Persisted theme, synced across tabs.
+const theme = createLocalStorage<"light" | "dark">("theme", "light")
+theme.set("dark")
+
+// Live media query.
+const wide = createMediaQuery("(min-width: 1024px)")
+
+// Dismiss a menu on outside press.
+let menu!: HTMLDivElement
+createClickOutside(() => menu, () => setOpen(false))
+
+// Lock body scroll while a modal is open (nested locks stack).
+const scroll = createScrollLock()
+createEffect(() => { modalOpen() ? scroll.lock() : scroll.unlock() })
+
+// Infinite scroll: prefetch as the sentinel approaches.
+let sentinel!: HTMLDivElement
+createInfiniteScroll(() => sentinel, {
+  onLoadMore: () => loadPage(),
+  disabled: () => !hasMore(),
+})
+<div ref={sentinel} />
+```
+
+- `createDebounced(source, delay)` returns an `Accessor<T>` that follows the source after it stops changing for `delay` ms (trailing edge).
+- `createThrottled(source, interval)` returns an `Accessor<T>` that updates at most once per `interval` ms: leading change applies immediately, the rest collapse into one trailing update.
+- `createLocalStorage<T>(key, initialValue, options?)` returns `{ value, set, remove }`: reads the stored value on creation (falling back on missing or corrupt JSON), writes through on every set, and stays in sync across tabs via the `storage` event (`sync: true` default). Custom `serialize`/`deserialize` supported. Behaves like a plain signal where storage is unavailable.
+- `createMediaQuery(query)` returns an `Accessor<boolean>` that tracks the query live (`false` on the server).
+- `createClickOutside(ref, handler, options?)` calls `handler` on `pointerdown` (default, configurable via `events`) outside the element. Shadow-DOM aware via `composedPath`. No-op on the server.
+- `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.
+
 ### 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/dom.d.ts

@@ -0,0 +1,163 @@
+import { type Accessor, type Setter } from "solid-js";
+type MaybeElement = () => Element | null | undefined;
+/**
+ * A signal that follows the source after it stops changing for `delay`
+ * ms. The classic search-input pattern: the UI stays live while the
+ * query signal waits for a pause before firing network requests.
+ *
+ * Trailing edge only. The pending update is cancelled on cleanup.
+ * SSR-safe: holds the source's initial value on the server.
+ *
+ * ```tsx
+ * const [query, setQuery] = createSignal("")
+ * const debounced = createDebounced(query, 300)
+ * createEffect(() => {
+ *   const q = debounced()
+ *   if (q) search(q) // fires only after a 300ms pause
+ * })
+ * ```
+ */
+export declare function createDebounced<T>(source: Accessor<T>, delay: number): Accessor<T>;
+/**
+ * A signal that follows the source at most once per `interval` ms.
+ * The first change applies immediately (leading edge); changes inside
+ * the window collapse into one trailing update. For scroll or resize
+ * handlers that feed expensive work.
+ *
+ * SSR-safe: holds the source's initial value on the server.
+ *
+ * ```tsx
+ * const throttledY = createThrottled(scrollY, 100)
+ * ```
+ */
+export declare function createThrottled<T>(source: Accessor<T>, interval: number): Accessor<T>;
+export interface LocalStorageOptions<T> {
+    /** Serialize a value. Default JSON.stringify. */
+    serialize?: (value: T) => string;
+    /** Deserialize a stored string. Default JSON.parse. */
+    deserialize?: (raw: string) => T;
+    /**
+     * React to `storage` events from other tabs. Default true: the
+     * signal stays in sync across tabs.
+     */
+    sync?: boolean;
+}
+export interface LocalStorageControls<T> {
+    value: Accessor<T>;
+    set: Setter<T>;
+    /** Remove the key from storage and reset to the initial value. */
+    remove: () => void;
+}
+/**
+ * A signal persisted to `localStorage`. Reads the stored value on
+ * creation (falling back to `initialValue` when missing or corrupt),
+ * writes through on every set, and stays in sync across tabs via the
+ * `storage` event.
+ *
+ * SSR-safe and storage-less-safe: without `window.localStorage` it
+ * behaves like a plain signal.
+ *
+ * ```tsx
+ * const theme = createLocalStorage<"light" | "dark">("theme", "light")
+ * theme.set("dark") // localStorage.theme = '"dark"'
+ * ```
+ */
+export declare function createLocalStorage<T>(key: string, initialValue: T, options?: LocalStorageOptions<T>): LocalStorageControls<T>;
+/**
+ * A boolean signal tracking a CSS media query, updating live when the
+ * query starts or stops matching. The primitive behind
+ * `usePrefersReducedMotion`, generalized.
+ *
+ * SSR-safe (and safe where `matchMedia` is missing): constant `false`.
+ *
+ * ```tsx
+ * const wide = createMediaQuery("(min-width: 1024px)")
+ * const columns = () => (wide() ? 4 : 2)
+ * ```
+ */
+export declare function createMediaQuery(query: string): Accessor<boolean>;
+export interface ClickOutsideOptions {
+    /**
+     * Events that count as "outside". Default `["pointerdown"]`: fires
+     * before `click`, so menus dismiss without a visible flash, and
+     * covers touch via Pointer Events.
+     */
+    events?: string[];
+}
+/**
+ * Call `handler` when the user interacts outside the element:
+ * dropdowns, popovers, and menus that dismiss on outside press.
+ *
+ * Listens on `window` (so it works even when the press lands on an
+ * overlaying element), ignores presses inside the ref, and cleans up
+ * on unmount. SSR-safe: no-op on the server.
+ *
+ * ```tsx
+ * let menu!: HTMLDivElement
+ * const [open, setOpen] = createSignal(false)
+ * createClickOutside(() => menu, () => setOpen(false))
+ * ```
+ */
+export declare function createClickOutside(ref: MaybeElement, handler: (event: Event) => void, options?: ClickOutsideOptions): void;
+export interface ScrollLockControls {
+    /** Whether the body scroll is currently locked. */
+    locked: Accessor<boolean>;
+    /** Lock body scroll. Nested locks stack; all must unlock. */
+    lock: () => void;
+    /** Release one lock. Restores the original overflow when empty. */
+    unlock: () => void;
+}
+/**
+ * Lock body scroll while overlays are open: modals, drawers, the
+ * bottom sheet. `overflow: hidden` goes on `document.body`, the
+ * previous value is restored when the last lock releases, and nested
+ * locks are reference-counted so two stacked modals cannot unlock
+ * each other early. Unmounting while locked releases the lock.
+ *
+ * SSR-safe: no-op on the server.
+ *
+ * ```tsx
+ * const scroll = createScrollLock()
+ * createEffect(() => {
+ *   if (modalOpen()) scroll.lock()
+ *   else scroll.unlock()
+ * })
+ * ```
+ */
+export declare function createScrollLock(): ScrollLockControls;
+export interface InfiniteScrollOptions {
+    /** Called when the sentinel approaches the viewport. */
+    onLoadMore: () => void;
+    /**
+     * Trigger distance in px before the sentinel enters: the observer's
+     * rootMargin. Default 200.
+     */
+    threshold?: number;
+    /**
+     * Reactive kill switch, e.g. `() => !hasMore()`. While true the
+     * sentinel is unobserved.
+     */
+    disabled?: Accessor<boolean>;
+}
+/**
+ * Infinite scroll: observe a sentinel element at the end of a list
+ * and call `onLoadMore` as it approaches the viewport, prefetching
+ * before the user hits the bottom.
+ *
+ * Built on IntersectionObserver with a `rootMargin` prefetch zone.
+ * SSR-safe (and safe without IntersectionObserver): never fires.
+ *
+ * ```tsx
+ * let sentinel!: HTMLDivElement
+ * const [items, setItems] = createSignal<string[]>([])
+ * const [hasMore, setHasMore] = createSignal(true)
+ * createInfiniteScroll(() => sentinel, {
+ *   onLoadMore: () => loadPage(),
+ *   disabled: () => !hasMore(),
+ * })
+ * <For each={items()}>{(item) => <Row item={item} />}</For>
+ * <div ref={sentinel} />
+ * ```
+ */
+export declare function createInfiniteScroll(ref: MaybeElement, options: InfiniteScrollOptions): void;
+export {};

package/dist/dom.js

@@ -0,0 +1,316 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+/* ------------------------------------------------------------------ */
+/* createDebounced                                                     */
+/* ------------------------------------------------------------------ */
+/**
+ * A signal that follows the source after it stops changing for `delay`
+ * ms. The classic search-input pattern: the UI stays live while the
+ * query signal waits for a pause before firing network requests.
+ *
+ * Trailing edge only. The pending update is cancelled on cleanup.
+ * SSR-safe: holds the source's initial value on the server.
+ *
+ * ```tsx
+ * const [query, setQuery] = createSignal("")
+ * const debounced = createDebounced(query, 300)
+ * createEffect(() => {
+ *   const q = debounced()
+ *   if (q) search(q) // fires only after a 300ms pause
+ * })
+ * ```
+ */
+export function createDebounced(source, delay) {
+    const [value, setValue] = createSignal(untrack(source));
+    if (typeof window === "undefined")
+        return value;
+    let timer;
+    createEffect(() => {
+        const next = source();
+        clearTimeout(timer);
+        timer = setTimeout(() => setValue(() => next), Math.max(0, delay));
+    });
+    onCleanup(() => clearTimeout(timer));
+    return value;
+}
+/* ------------------------------------------------------------------ */
+/* createThrottled                                                     */
+/* ------------------------------------------------------------------ */
+/**
+ * A signal that follows the source at most once per `interval` ms.
+ * The first change applies immediately (leading edge); changes inside
+ * the window collapse into one trailing update. For scroll or resize
+ * handlers that feed expensive work.
+ *
+ * SSR-safe: holds the source's initial value on the server.
+ *
+ * ```tsx
+ * const throttledY = createThrottled(scrollY, 100)
+ * ```
+ */
+export function createThrottled(source, interval) {
+    const [value, setValue] = createSignal(untrack(source));
+    if (typeof window === "undefined")
+        return value;
+    const wait = Math.max(0, interval);
+    let last = 0;
+    let timer;
+    createEffect(() => {
+        const next = source();
+        const t = Date.now();
+        clearTimeout(timer);
+        timer = undefined;
+        if (t - last >= wait) {
+            last = t;
+            setValue(() => next);
+        }
+        else {
+            timer = setTimeout(() => {
+                last = Date.now();
+                timer = undefined;
+                setValue(() => next);
+            }, wait - (t - last));
+        }
+    });
+    onCleanup(() => clearTimeout(timer));
+    return value;
+}
+/**
+ * A signal persisted to `localStorage`. Reads the stored value on
+ * creation (falling back to `initialValue` when missing or corrupt),
+ * writes through on every set, and stays in sync across tabs via the
+ * `storage` event.
+ *
+ * SSR-safe and storage-less-safe: without `window.localStorage` it
+ * behaves like a plain signal.
+ *
+ * ```tsx
+ * const theme = createLocalStorage<"light" | "dark">("theme", "light")
+ * theme.set("dark") // localStorage.theme = '"dark"'
+ * ```
+ */
+export function createLocalStorage(key, initialValue, options = {}) {
+    const { serialize = JSON.stringify, deserialize = JSON.parse, sync = true, } = options;
+    const storage = () => {
+        if (typeof window === "undefined")
+            return null;
+        try {
+            return window.localStorage;
+        }
+        catch {
+            return null; // private mode / blocked storage
+        }
+    };
+    const read = () => {
+        const store = storage();
+        if (!store)
+            return initialValue;
+        try {
+            const raw = store.getItem(key);
+            return raw === null ? initialValue : deserialize(raw);
+        }
+        catch {
+            return initialValue; // corrupt JSON: fall back, don't crash
+        }
+    };
+    const [value, setValue] = createSignal(read());
+    const set = ((next) => {
+        const resolved = typeof next === "function"
+            ? next(untrack(value))
+            : next;
+        setValue(() => resolved);
+        try {
+            storage()?.setItem(key, serialize(resolved));
+        }
+        catch {
+            // Quota exceeded or blocked: the signal still updates.
+        }
+        return resolved;
+    });
+    const remove = () => {
+        try {
+            storage()?.removeItem(key);
+        }
+        catch {
+            // ignore
+        }
+        setValue(() => initialValue);
+    };
+    if (typeof window !== "undefined" && sync) {
+        const onStorage = (event) => {
+            if (event.key !== key)
+                return;
+            try {
+                setValue(() => event.newValue === null ? initialValue : deserialize(event.newValue));
+            }
+            catch {
+                // ignore corrupt cross-tab writes
+            }
+        };
+        window.addEventListener("storage", onStorage);
+        onCleanup(() => window.removeEventListener("storage", onStorage));
+    }
+    return { value, set, remove };
+}
+/* ------------------------------------------------------------------ */
+/* createMediaQuery                                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * A boolean signal tracking a CSS media query, updating live when the
+ * query starts or stops matching. The primitive behind
+ * `usePrefersReducedMotion`, generalized.
+ *
+ * SSR-safe (and safe where `matchMedia` is missing): constant `false`.
+ *
+ * ```tsx
+ * const wide = createMediaQuery("(min-width: 1024px)")
+ * const columns = () => (wide() ? 4 : 2)
+ * ```
+ */
+export function createMediaQuery(query) {
+    const no = () => false;
+    if (typeof window === "undefined" ||
+        typeof window.matchMedia !== "function") {
+        return no;
+    }
+    const mql = window.matchMedia(query);
+    const [matches, setMatches] = createSignal(mql.matches);
+    const onChange = (event) => {
+        setMatches(event.matches);
+    };
+    mql.addEventListener("change", onChange);
+    onCleanup(() => mql.removeEventListener("change", onChange));
+    return matches;
+}
+/**
+ * Call `handler` when the user interacts outside the element:
+ * dropdowns, popovers, and menus that dismiss on outside press.
+ *
+ * Listens on `window` (so it works even when the press lands on an
+ * overlaying element), ignores presses inside the ref, and cleans up
+ * on unmount. SSR-safe: no-op on the server.
+ *
+ * ```tsx
+ * let menu!: HTMLDivElement
+ * const [open, setOpen] = createSignal(false)
+ * createClickOutside(() => menu, () => setOpen(false))
+ * ```
+ */
+export function createClickOutside(ref, handler, options = {}) {
+    if (typeof window === "undefined")
+        return;
+    const { events = ["pointerdown"] } = options;
+    const onEvent = (event) => {
+        const el = ref();
+        if (!el)
+            return;
+        const target = event.target;
+        // Shadow-DOM aware: composedPath pierces shadow roots.
+        const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+        const inside = (target !== null && el.contains(target)) || path.includes(el);
+        if (!inside)
+            handler(event);
+    };
+    for (const name of events) {
+        window.addEventListener(name, onEvent);
+    }
+    onCleanup(() => {
+        for (const name of events) {
+            window.removeEventListener(name, onEvent);
+        }
+    });
+}
+let lockCount = 0;
+let savedOverflow = "";
+/**
+ * Lock body scroll while overlays are open: modals, drawers, the
+ * bottom sheet. `overflow: hidden` goes on `document.body`, the
+ * previous value is restored when the last lock releases, and nested
+ * locks are reference-counted so two stacked modals cannot unlock
+ * each other early. Unmounting while locked releases the lock.
+ *
+ * SSR-safe: no-op on the server.
+ *
+ * ```tsx
+ * const scroll = createScrollLock()
+ * createEffect(() => {
+ *   if (modalOpen()) scroll.lock()
+ *   else scroll.unlock()
+ * })
+ * ```
+ */
+export function createScrollLock() {
+    const [locked, setLocked] = createSignal(false);
+    if (typeof window === "undefined" || typeof document === "undefined") {
+        return { locked, lock: () => { }, unlock: () => { } };
+    }
+    let held = 0;
+    const lock = () => {
+        if (lockCount === 0) {
+            savedOverflow = document.body.style.overflow;
+            document.body.style.overflow = "hidden";
+        }
+        lockCount++;
+        held++;
+        setLocked(true);
+    };
+    const unlock = () => {
+        if (held === 0)
+            return;
+        held--;
+        lockCount--;
+        if (lockCount === 0) {
+            document.body.style.overflow = savedOverflow;
+            setLocked(false);
+        }
+        else if (held === 0) {
+            setLocked(false);
+        }
+    };
+    onCleanup(() => {
+        while (held > 0)
+            unlock();
+    });
+    return { locked, lock, unlock };
+}
+/**
+ * Infinite scroll: observe a sentinel element at the end of a list
+ * and call `onLoadMore` as it approaches the viewport, prefetching
+ * before the user hits the bottom.
+ *
+ * Built on IntersectionObserver with a `rootMargin` prefetch zone.
+ * SSR-safe (and safe without IntersectionObserver): never fires.
+ *
+ * ```tsx
+ * let sentinel!: HTMLDivElement
+ * const [items, setItems] = createSignal<string[]>([])
+ * const [hasMore, setHasMore] = createSignal(true)
+ * createInfiniteScroll(() => sentinel, {
+ *   onLoadMore: () => loadPage(),
+ *   disabled: () => !hasMore(),
+ * })
+ * <For each={items()}>{(item) => <Row item={item} />}</For>
+ * <div ref={sentinel} />
+ * ```
+ */
+export function createInfiniteScroll(ref, options) {
+    const { onLoadMore, threshold = 200, disabled } = options;
+    if (typeof window === "undefined" ||
+        typeof IntersectionObserver === "undefined") {
+        return;
+    }
+    createEffect(() => {
+        const el = ref();
+        if (!el)
+            return;
+        if (disabled?.() === true)
+            return;
+        const observer = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.isIntersecting)
+                    onLoadMore();
+            }
+        }, { rootMargin: `${threshold}px` });
+        observer.observe(el);
+        onCleanup(() => observer.disconnect());
+    });
+}

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

@@ -14,6 +14,8 @@ export { usePrefersReducedMotion, prefersReducedMotion, } from "./reduced-motion
 export { isLowPowerMode, useLowPowerMode, type LowPowerOptions, } from "./power.js";
 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 { 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

@@ -14,6 +14,8 @@ export { usePrefersReducedMotion, prefersReducedMotion, } from "./reduced-motion
 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 { createHorizontalScroll, } from "./horizontal.js";
 export { createScrub } from "./scrub.js";
 export { createScrollColor, createScrollTracking, createScrollLine, } from "./scrollfx.js";

package/package.json

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