solid-drift 0.27.0 → 0.29.0

package/README.md

@@ -1600,6 +1600,49 @@ scanline.start();
 - `createShake(options?)` detects shake gestures from `devicemotion`: `{ supported, needsPermission, listening, shakes, error, requestPermission, start, stop }`. A shake counts when the acceleration delta exceeds `threshold` (default 15 m/s^2), rate-limited by `cooldown` (default 800ms); `onShake` fires per shake.
 - `createScanline(options?)` is the animated line of a QR/barcode viewfinder: `{ progress, running, start, stop }`. `progress()` sweeps 0..1 on the shared clock (`direction: "down" | "up" | "alternate"`); bind it to the line's position. Under reduced motion it freezes mid-frame. Every primitive is SSR-safe: server renders get `supported: false` and safe no-op actions.
 
+### Optimistic updates
+
+```tsx
+import { createOptimistic } from "solid-drift";
+
+const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+  bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+);
+
+// in an event handler:
+await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+  // already rolled back; read feed.error() for a toast
+});
+```
+
+`createOptimistic(initial, apply)` gives `{ value, setBase, pending, pendingCount, error, commit, reset }`. `commit(update, task)` applies the update instantly, then runs the task; on success the update is promoted into the base truth (no flicker while the server catches up), and on failure it is rolled back, `error()` is set, and the error is rethrown. `setBase()` folds fresh server truth in (after a refetch); write `apply` idempotently, for example upsert by id, so truth that already includes an optimistic update does not duplicate it. `reset()` drops in-flight updates. Pure signals, SSR-safe.
+
+### Skeleton and scroll spy
+
+```tsx
+import { createSkeleton, createScrollSpy } from "solid-drift";
+
+const sk = createSkeleton({ delay: 200, minVisible: 400 });
+createEffect(() => sk.setLoading(query.loading()));
+
+const spy = createScrollSpy({ targets: ["intro", "api", "faq"], offset: 80 });
+
+<Show when={sk.show()} fallback={<ArticleView />}>
+  <div class="skeleton" style={{ "--shine": `${sk.phase() * 100}%` }} />
+</Show>
+<nav>
+  <For each={["intro", "api", "faq"]}>
+    {(id) => (
+      <a classList={{ active: spy.active() === id }}
+         onClick={() => spy.scrollTo(id)}>{id}</a>
+    )}
+  </For>
+</nav>
+```
+
+- `createSkeleton(options?)` is a loading-placeholder controller with flicker protection: `{ loading, show, phase, setLoading }`. `show()` flips true only after `delay` ms (default 200), so fast loads never flash a skeleton, and stays true for at least `minVisible` ms once shown. `phase()` sweeps 0..1 on the shared clock while shown for a JS-driven shimmer (bind it to a gradient stop); it freezes under reduced motion. On the server `show()` never flips.
+- `createScrollSpy(options)` tracks the deepest section at or above the offset line: `{ active, scrollTo, refresh }`. `targets` is an id list or accessor; `container` defaults to the window (pass an element for a scrollable panel); scroll handling is rAF-throttled on the shared clock; `scrollTo(id)` smooth-scrolls (auto under reduced motion); `onChange` fires only when the active id changes. 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/index.d.ts

@@ -46,3 +46,9 @@ export { createVoiceState, createMicLevel, createSpeech, createWaveform, createT
 export type { VoiceStatus, VoiceStateControls, MicLevelOptions, MicLevelControls, SpeechOptions, SpeechControls, WaveformOptions, WaveformControls, TTSProvider, TTSOptions, TTSControls, ThinkingOptions, ThinkingControls, PromptOptions, PromptControls, } from "./voice.js";
 export { createBattery, createNetwork, createWakeLock, createContactPick, createOTP, createShare, createNFC, createTorch, createGyro, createShake, createScanline, } from "./hardware.js";
 export type { BatteryState, NetworkState, WakeLockState, PickedContact, ContactPickState, OTPState, ShareState, NFCRecord, NFCMessage, NFCState, TorchState, GyroState, ShakeOptions, ShakeState, ScanlineOptions, ScanlineState, } from "./hardware.js";
+export { createOptimistic } from "./optimistic.js";
+export type { OptimisticControls } from "./optimistic.js";
+export { createSkeleton } from "./skeleton.js";
+export type { SkeletonOptions, SkeletonControls } from "./skeleton.js";
+export { createScrollSpy } from "./scrollspy.js";
+export type { ScrollSpyOptions, ScrollSpyControls } from "./scrollspy.js";

package/dist/index.js

@@ -39,3 +39,6 @@ export { createPoll, shortenAddress, isAddress, formatUnits, parseUnits, CHAINS,
 export { createSSEParser, createSSE, createChatModel, } from "./stream.js";
 export { createVoiceState, createMicLevel, createSpeech, createWaveform, createTTS, createThinking, createPrompt, } from "./voice.js";
 export { createBattery, createNetwork, createWakeLock, createContactPick, createOTP, createShare, createNFC, createTorch, createGyro, createShake, createScanline, } from "./hardware.js";
+export { createOptimistic } from "./optimistic.js";
+export { createSkeleton } from "./skeleton.js";
+export { createScrollSpy } from "./scrollspy.js";

package/dist/optimistic.d.ts

@@ -0,0 +1,44 @@
+export interface OptimisticControls<T, U> {
+    /** Server truth plus every in-flight optimistic update, in commit order. */
+    value: () => T;
+    /** Replace the server truth (for example after a refetch). */
+    setBase: (next: T | ((prev: T) => T)) => void;
+    /** True while at least one commit is in flight. */
+    pending: () => boolean;
+    /** Number of commits currently in flight. */
+    pendingCount: () => number;
+    /** Last commit failure, cleared when the next commit starts. */
+    error: () => Error | null;
+    /**
+     * Apply `update` immediately, then run `task`. On success the update is
+     * promoted into the base truth (so the value stays stable while the
+     * server catches up); on failure it is rolled back, `error()` is set,
+     * and the error is rethrown so callers can react (toast, retry).
+     */
+    commit: (update: U, task: (update: U) => Promise<unknown>) => Promise<void>;
+    /** Drop every in-flight optimistic update without running their tasks. */
+    reset: () => void;
+}
+/**
+ * createOptimistic
+ *
+ * Optimistic updates with rollback, in the spirit of React's `useOptimistic`.
+ * The UI reflects `update` the moment `commit()` is called; if the backing
+ * task (a transaction, a POST, a stream send) fails, that update is rolled
+ * back and the error surfaces on `error()`.
+ *
+ * Write `apply` idempotently (upsert by id rather than blind append) when
+ * the server truth delivered through `setBase` may already include an
+ * optimistic update.
+ *
+ * ```ts
+ * const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+ *   bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+ * );
+ *
+ * await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+ *   // already rolled back; show a toast from feed.error()
+ * });
+ * ```
+ */
+export declare function createOptimistic<T, U>(initial: T, apply: (state: T, update: U) => T): OptimisticControls<T, U>;

package/dist/optimistic.js

@@ -0,0 +1,76 @@
+import { createSignal } from "solid-js";
+/**
+ * createOptimistic
+ *
+ * Optimistic updates with rollback, in the spirit of React's `useOptimistic`.
+ * The UI reflects `update` the moment `commit()` is called; if the backing
+ * task (a transaction, a POST, a stream send) fails, that update is rolled
+ * back and the error surfaces on `error()`.
+ *
+ * Write `apply` idempotently (upsert by id rather than blind append) when
+ * the server truth delivered through `setBase` may already include an
+ * optimistic update.
+ *
+ * ```ts
+ * const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+ *   bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+ * );
+ *
+ * await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+ *   // already rolled back; show a toast from feed.error()
+ * });
+ * ```
+ */
+export function createOptimistic(initial, apply) {
+    const [base, setBaseSignal] = createSignal(initial);
+    const [queue, setQueue] = createSignal([]);
+    const [error, setError] = createSignal(null);
+    let nextId = 0;
+    const value = () => {
+        const truth = base();
+        const pending = queue();
+        if (pending.length === 0)
+            return truth;
+        return pending.reduce((state, entry) => apply(state, entry.update), truth);
+    };
+    const setBase = (next) => {
+        if (typeof next === "function") {
+            setBaseSignal(next);
+        }
+        else {
+            setBaseSignal(() => next);
+        }
+    };
+    const commit = async (update, task) => {
+        const id = nextId++;
+        setError(null);
+        setQueue((q) => [...q, { id, update }]);
+        try {
+            await task(update);
+            // Promote the confirmed update into the base truth so the value
+            // stays stable while the server truth catches up via setBase.
+            setBaseSignal((prev) => apply(prev, update));
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+        finally {
+            setQueue((q) => q.filter((entry) => entry.id !== id));
+        }
+    };
+    const reset = () => {
+        setQueue([]);
+        setError(null);
+    };
+    return {
+        value,
+        setBase,
+        pending: () => queue().length > 0,
+        pendingCount: () => queue().length,
+        error,
+        commit,
+        reset,
+    };
+}

package/dist/scrollspy.d.ts

@@ -0,0 +1,42 @@
+export interface ScrollSpyOptions {
+    /** Section element ids in document order, or an accessor for them. */
+    targets: string[] | (() => string[]);
+    /**
+     * Scroll container; defaults to the window. Pass an element for a
+     * scrollable panel, or a getter when the ref is not mounted yet.
+     */
+    container?: HTMLElement | Window | (() => HTMLElement | Window | null);
+    /** Pixels below the container top where a section becomes active. Default 0. */
+    offset?: number;
+    /** Smooth-scroll in scrollTo. Default true (auto under reduced motion). */
+    smooth?: boolean;
+    onChange?: (id: string | null) => void;
+}
+export interface ScrollSpyControls {
+    /** Id of the deepest section at or above the offset line, or null. */
+    active: () => string | null;
+    /** Scroll the section into view. No-op on the server or for unknown ids. */
+    scrollTo: (id: string) => void;
+    /** Recompute the active section immediately. */
+    refresh: () => void;
+}
+/**
+ * createScrollSpy
+ *
+ * Navigation scroll spy: `active()` is the id of the deepest target
+ * section whose top sits at or above the `offset` line of the scroll
+ * container. Scroll handling is rAF-throttled on the shared clock.
+ *
+ * ```tsx
+ * const spy = createScrollSpy({ targets: ["intro", "api", "faq"], offset: 80 });
+ * <nav>
+ *   <For each={["intro", "api", "faq"]}>
+ *     {(id) => (
+ *       <a classList={{ active: spy.active() === id }}
+ *          onClick={() => spy.scrollTo(id)}>{id}</a>
+ *     )}
+ *   </For>
+ * </nav>
+ * ```
+ */
+export declare function createScrollSpy(options: ScrollSpyOptions): ScrollSpyControls;

package/dist/scrollspy.js

@@ -0,0 +1,105 @@
+import { createSignal, onCleanup } from "solid-js";
+import { schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+function isClient() {
+    return typeof globalThis.window !== "undefined";
+}
+function getDocument() {
+    return globalThis.document;
+}
+/**
+ * createScrollSpy
+ *
+ * Navigation scroll spy: `active()` is the id of the deepest target
+ * section whose top sits at or above the `offset` line of the scroll
+ * container. Scroll handling is rAF-throttled on the shared clock.
+ *
+ * ```tsx
+ * const spy = createScrollSpy({ targets: ["intro", "api", "faq"], offset: 80 });
+ * <nav>
+ *   <For each={["intro", "api", "faq"]}>
+ *     {(id) => (
+ *       <a classList={{ active: spy.active() === id }}
+ *          onClick={() => spy.scrollTo(id)}>{id}</a>
+ *     )}
+ *   </For>
+ * </nav>
+ * ```
+ */
+export function createScrollSpy(options) {
+    const { offset = 0, smooth = true, onChange } = options;
+    const [active, setActive] = createSignal(null);
+    const resolveTargets = () => typeof options.targets === "function" ? options.targets() : options.targets;
+    const resolveContainer = () => {
+        if (!isClient())
+            return null;
+        const c = options.container;
+        if (typeof c === "function")
+            return c() ?? null;
+        return c ?? globalThis.window;
+    };
+    const sectionTop = (el, container) => {
+        const rect = el.getBoundingClientRect().top;
+        if (container === globalThis.window)
+            return rect;
+        const containerRect = container.getBoundingClientRect();
+        return rect - containerRect.top;
+    };
+    const update = () => {
+        const doc = getDocument();
+        const container = resolveContainer();
+        if (!doc || !container)
+            return;
+        let current = null;
+        for (const id of resolveTargets()) {
+            const el = doc.getElementById(id);
+            if (!el)
+                continue;
+            if (sectionTop(el, container) <= offset)
+                current = id;
+        }
+        if (current !== active()) {
+            setActive(current);
+            onChange?.(current);
+        }
+    };
+    let queued = false;
+    const onScroll = () => {
+        if (queued)
+            return;
+        queued = true;
+        schedule(() => {
+            queued = false;
+            update();
+            return false;
+        });
+    };
+    const container = resolveContainer();
+    const removeListener = (() => {
+        if (container &&
+            typeof container.addEventListener === "function") {
+            const target = container;
+            target.addEventListener("scroll", onScroll, { passive: true });
+            return () => target.removeEventListener("scroll", onScroll);
+        }
+        return null;
+    })();
+    const scrollTo = (id) => {
+        const doc = getDocument();
+        if (!doc)
+            return;
+        const el = doc.getElementById(id);
+        if (!el || typeof el.scrollIntoView !== "function")
+            return;
+        el.scrollIntoView({
+            behavior: smooth && !prefersReducedMotion() ? "smooth" : "auto",
+            block: "start",
+        });
+    };
+    if (isClient())
+        update();
+    onCleanup(() => {
+        removeListener?.();
+    });
+    return { active, scrollTo, refresh: update };
+}

package/dist/skeleton.d.ts

@@ -0,0 +1,37 @@
+export interface SkeletonOptions {
+    /** Milliseconds before the skeleton appears; hides flashes for fast loads. Default 200. */
+    delay?: number;
+    /** Milliseconds the skeleton stays visible once shown. Default 0. */
+    minVisible?: number;
+    /** Drive a shimmer `phase` while shown. Default true. */
+    shimmer?: boolean;
+    /** Milliseconds per shimmer sweep. Default 1400. */
+    shimmerDuration?: number;
+}
+export interface SkeletonControls {
+    /** Raw loading flag, mirrors the last setLoading call. */
+    loading: () => boolean;
+    /** Debounced visibility: bind `{#if}` / `<Show>` to this. */
+    show: () => boolean;
+    /** Shimmer sweep 0..1 while shown (0 otherwise); bind to a gradient position. */
+    phase: () => number;
+    setLoading: (loading: boolean) => void;
+}
+/**
+ * createSkeleton
+ *
+ * Loading-placeholder controller with flicker protection: the skeleton
+ * appears only after `delay` (fast loads never flash it) and, once shown,
+ * stays for at least `minVisible`. While shown, `phase()` sweeps 0..1 on
+ * the shared clock for a JS-driven shimmer; it freezes under reduced
+ * motion. On the server `show()` never flips.
+ *
+ * ```tsx
+ * const sk = createSkeleton({ delay: 200, minVisible: 400 });
+ * createEffect(() => { sk.setLoading(query.loading()); });
+ * <Show when={sk.show()} fallback={<ArticleView/>}>
+ *   <div class="skeleton" style={{ "--shine": `${sk.phase() * 100}%` }} />
+ * </Show>
+ * ```
+ */
+export declare function createSkeleton(options?: SkeletonOptions): SkeletonControls;

package/dist/skeleton.js

@@ -0,0 +1,112 @@
+import { createSignal, onCleanup } from "solid-js";
+import { schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+function isClient() {
+    return typeof globalThis.window !== "undefined";
+}
+/**
+ * createSkeleton
+ *
+ * Loading-placeholder controller with flicker protection: the skeleton
+ * appears only after `delay` (fast loads never flash it) and, once shown,
+ * stays for at least `minVisible`. While shown, `phase()` sweeps 0..1 on
+ * the shared clock for a JS-driven shimmer; it freezes under reduced
+ * motion. On the server `show()` never flips.
+ *
+ * ```tsx
+ * const sk = createSkeleton({ delay: 200, minVisible: 400 });
+ * createEffect(() => { sk.setLoading(query.loading()); });
+ * <Show when={sk.show()} fallback={<ArticleView/>}>
+ *   <div class="skeleton" style={{ "--shine": `${sk.phase() * 100}%` }} />
+ * </Show>
+ * ```
+ */
+export function createSkeleton(options = {}) {
+    const { delay = 200, minVisible = 0, shimmer = true, shimmerDuration = 1400, } = options;
+    const [loading, setLoadingSignal] = createSignal(false);
+    const [show, setShow] = createSignal(false);
+    const [phase, setPhase] = createSignal(0);
+    let showTimer = null;
+    let hideTimer = null;
+    let shownAt = 0;
+    let stopShimmer = null;
+    const clearTimer = (timer) => {
+        if (timer !== null)
+            clearTimeout(timer);
+    };
+    const startShimmer = () => {
+        if (!shimmer || stopShimmer !== null)
+            return;
+        if (prefersReducedMotion() || shimmerDuration <= 0) {
+            setPhase(0);
+            return;
+        }
+        let start = 0;
+        let first = true;
+        stopShimmer = schedule((t) => {
+            if (first) {
+                start = t;
+                first = false;
+            }
+            setPhase(((t - start) % shimmerDuration) / shimmerDuration);
+            return true;
+        });
+    };
+    const stopShimmerNow = () => {
+        stopShimmer?.();
+        stopShimmer = null;
+        setPhase(0);
+    };
+    const reveal = () => {
+        setShow(true);
+        shownAt = Date.now();
+        startShimmer();
+    };
+    const conceal = () => {
+        setShow(false);
+        stopShimmerNow();
+    };
+    const setLoading = (value) => {
+        setLoadingSignal(value);
+        if (!isClient())
+            return;
+        if (value) {
+            clearTimer(hideTimer);
+            hideTimer = null;
+            if (show() || showTimer !== null)
+                return;
+            if (delay <= 0) {
+                reveal();
+                return;
+            }
+            showTimer = setTimeout(() => {
+                showTimer = null;
+                reveal();
+            }, delay);
+        }
+        else {
+            clearTimer(showTimer);
+            showTimer = null;
+            if (!show())
+                return;
+            const remaining = minVisible - (Date.now() - shownAt);
+            if (remaining <= 0) {
+                conceal();
+                return;
+            }
+            clearTimer(hideTimer);
+            hideTimer = setTimeout(() => {
+                hideTimer = null;
+                conceal();
+            }, remaining);
+        }
+    };
+    onCleanup(() => {
+        clearTimer(showTimer);
+        clearTimer(hideTimer);
+        showTimer = null;
+        hideTimer = null;
+        stopShimmerNow();
+    });
+    return { loading, show, phase, setLoading };
+}

package/package.json

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