solid-drift 0.28.0 → 0.29.0

package/README.md

@@ -1617,6 +1617,32 @@ await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
 
 `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

@@ -48,3 +48,7 @@ export { createBattery, createNetwork, createWakeLock, createContactPick, create
 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

@@ -40,3 +40,5 @@ 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/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.28.0"
+  "version": "0.29.0"
 }