npm - solid-drift - Versions diffs - 0.30.0 → 0.32.0 - Mend

solid-drift 0.30.0 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md CHANGED Viewed

@@ -1662,6 +1662,70 @@ const sale = createCountdown(new Date("2026-12-01T00:00:00"), {
 - `createCopy(options?)` copies text to the clipboard: `{ copied, error, copy, reset }`. Uses the async Clipboard API with an `execCommand` fallback (`noFallback: true` disables it). `copied()` flips true for `resetDelay` ms (default 2000) for transient "Copied!" feedback. SSR-safe.
 - `createCountdown(target, options?)` counts down to a date, timestamp, or accessor: `{ remaining, days, hours, minutes, seconds, done, running, start, stop, reset }`. Wall-clock based (the moment is fixed even if the tab hides); recomputes on the shared clock throttled to `interval` ms (default 1000); stops itself at zero and fires `onDone` once. SSR-safe.
+### Marquee, variants, path drawing, press and hover
+```tsx
+import {
+  createMarquee,
+  createVariants,
+  createPathDraw,
+  createPress,
+  createHover,
+} from "solid-drift";
+const marquee = createMarquee({ speed: 80 });
+const card = createVariants(
+  {
+    idle: { scale: 1 },
+    hover: { scale: 1.04 },
+    press: { scale: 0.96 },
+  },
+  { initial: "idle", duration: 180 },
+);
+let strip!: HTMLDivElement;
+let btn!: HTMLButtonElement;
+let mark!: SVGPathElement;
+createEffect(() => marquee.setContentSize(strip.scrollWidth / 2));
+createHover(() => btn, { onChange: (h) => card.go(h ? "hover" : "idle") });
+createPress(() => btn, { onChange: (p) => card.go(p ? "press" : "idle") });
+const draw = createPathDraw(() => mark, { duration: 1600 });
+```
+- `createMarquee(options?)` infinite scroller: `{ offset, running, setContentSize, start, stop }`. The offset advances at `speed` px/s (`direction` left/right/up/down) on the shared clock and wraps at the content size; render the content twice and translate by `-offset()`. Measure one loop unit and pass it to `setContentSize`. Static under reduced motion; SSR-safe.
+- `createVariants(defs, options?)` named animation states: `{ current, values, go }`. `go(name)` tweens numeric props from the current values to the target variant (`duration` ms, easing) and snaps non-numeric props at the end; unknown names are ignored. Snaps instantly under reduced motion; SSR-safe.
+- `createPathDraw(ref, options?)` SVG stroke draw-on: `{ progress, running, start, stop, reset }`. Reads the length with `getTotalLength()` and drives `stroke-dashoffset` to 0, eased; `onDone` fires once; resume keeps a constant speed. Renders fully drawn under reduced motion; SSR-safe.
+- `createPress(ref, options?)` press gesture state: `{ pressed }`. Pointer down/up/cancel/leave plus Enter/Space keys for keyboard parity; `onChange` fires on change only. State only, no animation; pair with `createVariants`. SSR-safe.
+- `createHover(ref, options?)` hover gesture state: `{ hovering }`. Pointer enter/leave plus focus/blur for keyboard parity; `onChange` fires on change only. SSR-safe.
+### App utilities
+```tsx
+import {
+  createColorScheme,
+  createIdle,
+  createOnline,
+  createInstallPrompt,
+  createUndo,
+  createFullscreen,
+} from "solid-drift";
+const theme = createColorScheme(); // follows the OS, persists, writes html[data-theme]
+const { idle } = createIdle({ timeout: 30_000 }); // auto-hide chrome when idle
+const { online } = createOnline(); // offline banner
+const install = createInstallPrompt(); // PWA install button
+const doc = createUndo({ title: "" }); // undoable form state
+let stage!: HTMLDivElement;
+const fs = createFullscreen(() => stage); // fullscreen toggle
+```
+- `createColorScheme(options?)`: `{ scheme, preference, setPreference, toggle }`. Resolves `"system"` through the `(prefers-color-scheme: dark)` media query (reactive to OS changes), persists the preference to localStorage (`storageKey`, null disables), and writes the resolved scheme to `<html data-theme="light|dark">` (configurable `attribute`) plus `color-scheme`. SSR-safe (resolves to light on the server).
+- `createIdle(options?)`: `{ idle, lastActive, reset }`. `idle()` flips true after `timeout` ms (default 60000) without any of the `events` (default mousemove, mousedown, keydown, touchstart, wheel); activity restarts the timer. SSR-safe.
+- `createOnline()`: `{ online }`. Seeds from `navigator.onLine`, follows window `online`/`offline` events. SSR-safe (assumes online).
+- `createInstallPrompt()`: `{ canInstall, prompt }`. Captures `beforeinstallprompt` (preventing the browser mini-bar); `prompt()` shows it from a click handler and resolves to the user's choice, or null when unavailable; each captured event is single-use. SSR-safe.
+- `createUndo(initial, options?)`: undoable state: `{ value, set, undo, redo, clear, reset, canUndo, canRedo, past, future }`. `set()` (value or updater) records history trimmed to `capacity` (default 50); a new `set()` discards the redo stack. Pure logic, SSR-safe.
+- `createFullscreen(ref, options?)`: `{ fullscreen, enter, exit, toggle }`. Tracks `document.fullscreenElement` so Escape and external changes stay in sync; failures go to `onError` instead of throwing. 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/apputils.d.ts ADDED Viewed

@@ -0,0 +1,205 @@
+import { type Accessor } from "solid-js";
+type MaybeElement = () => Element | null | undefined;
+/** Resolved color scheme. */
+export type ColorScheme = "light" | "dark";
+/** Stored preference: an explicit scheme or following the OS. */
+export type ColorSchemePreference = ColorScheme | "system";
+export interface ColorSchemeOptions {
+    /** Preference used when nothing is stored. Default "system". */
+    default?: ColorSchemePreference;
+    /**
+     * localStorage key for the preference. Set to null to disable
+     * persistence. Default "solid-drift:color-scheme".
+     */
+    storageKey?: string | null;
+    /**
+     * Attribute written on `<html>` with the resolved scheme, so CSS can
+     * hook onto it (`html[data-theme="dark"] { ... }`). Default "data-theme".
+     */
+    attribute?: string;
+}
+export interface ColorSchemeControls {
+    /** Resolved scheme: the preference, or the OS scheme when "system". */
+    scheme: Accessor<ColorScheme>;
+    /** The stored preference, "system" included. */
+    preference: Accessor<ColorSchemePreference>;
+    setPreference: (preference: ColorSchemePreference) => void;
+    /** Flips between light and dark, leaving "system" behind. */
+    toggle: () => void;
+}
+/**
+ * Color scheme manager. Resolves "system" through the
+ * `(prefers-color-scheme: dark)` media query (reactive to OS changes),
+ * persists the preference to localStorage, and writes the resolved
+ * scheme to `<html data-theme="light|dark">` plus `color-scheme` so
+ * form controls and scrollbars follow.
+ *
+ * SSR-safe: resolves "system" to "light" on the server.
+ *
+ * ```tsx
+ * const theme = createColorScheme();
+ * <button onClick={theme.toggle}>
+ *   {theme.scheme() === "dark" ? "Light mode" : "Dark mode"}
+ * </button>
+ * ```
+ */
+export declare function createColorScheme(options?: ColorSchemeOptions): ColorSchemeControls;
+export interface IdleOptions {
+    /** Ms of inactivity before `idle()` flips true. Default 60000. */
+    timeout?: number;
+    /**
+     * Activity events that reset the timer. Default mousemove, mousedown,
+     * keydown, touchstart and wheel.
+     */
+    events?: string[];
+    /** Start in the idle state. Default false. */
+    initialIdle?: boolean;
+}
+export interface IdleControls {
+    /** True once `timeout` ms passed without activity. */
+    idle: Accessor<boolean>;
+    /** Timestamp of the last activity. */
+    lastActive: Accessor<number>;
+    /** Mark the user active now and restart the timer. */
+    reset: () => void;
+}
+/**
+ * Idle detection. `idle()` becomes true after `timeout` ms without any
+ * of the activity events; any activity flips it back and restarts the
+ * timer. Useful for auto-hiding chrome, pausing ambient animation, or
+ * "are you still there" prompts.
+ *
+ * SSR-safe: never idle on the server.
+ *
+ * ```tsx
+ * const { idle } = createIdle({ timeout: 30_000 });
+ * <div classList={{ "controls-hidden": idle() }}>…</div>
+ * ```
+ */
+export declare function createIdle(options?: IdleOptions): IdleControls;
+export interface OnlineControls {
+    /** Mirrors `navigator.onLine`, updated on online/offline events. */
+    online: Accessor<boolean>;
+}
+/**
+ * Network connectivity state. Seeds from `navigator.onLine` and follows
+ * the window `online` / `offline` events. SSR-safe: assumes online on
+ * the server.
+ *
+ * ```tsx
+ * const { online } = createOnline();
+ * <Show when={!online()}>
+ *   <p>You are offline. Changes will sync when you reconnect.</p>
+ * </Show>
+ * ```
+ */
+export declare function createOnline(): OnlineControls;
+/** Minimal shape of the PWA `beforeinstallprompt` event. */
+export interface BeforeInstallPromptEvent extends Event {
+    prompt: () => Promise<void>;
+    userChoice: Promise<{
+        outcome: "accepted" | "dismissed";
+    }>;
+}
+export interface InstallPromptControls {
+    /** True once the browser fired `beforeinstallprompt`. */
+    canInstall: Accessor<boolean>;
+    /**
+     * Shows the install prompt. Returns the user's choice, or null when
+     * the browser never offered installation. Each captured event can be
+     * used once.
+     */
+    prompt: () => Promise<{
+        outcome: "accepted" | "dismissed";
+    } | null>;
+}
+/**
+ * PWA install prompt. Captures the `beforeinstallprompt` event (calling
+ * `preventDefault()` so the browser does not show its own mini-bar) and
+ * exposes it through `prompt()`, which is safe to call from a click
+ * handler. SSR-safe: never installable on the server.
+ *
+ * ```tsx
+ * const install = createInstallPrompt();
+ * <Show when={install.canInstall()}>
+ *   <button
+ *     onClick={async () => {
+ *       const choice = await install.prompt();
+ *       if (choice?.outcome === "accepted") toast("Installed!");
+ *     }}
+ *   >
+ *     Install app
+ *   </button>
+ * </Show>
+ * ```
+ */
+export declare function createInstallPrompt(): InstallPromptControls;
+export interface UndoOptions {
+    /** Maximum snapshots kept. Older ones are dropped. Default 50. */
+    capacity?: number;
+}
+export interface UndoControls<T> {
+    /** Current value. */
+    value: Accessor<T>;
+    /** Set a new value, recording the previous one for undo. */
+    set: (value: T | ((prev: T) => T)) => void;
+    /** Step back; no-op when there is nothing to undo. */
+    undo: () => void;
+    /** Step forward; no-op when there is nothing to redo. */
+    redo: () => void;
+    /** Drop all history without touching the value. */
+    clear: () => void;
+    /** Restore the initial value and drop all history. */
+    reset: () => void;
+    canUndo: Accessor<boolean>;
+    canRedo: Accessor<boolean>;
+    /** Undo stack, oldest first. */
+    past: Accessor<readonly T[]>;
+    /** Redo stack, next redo first. */
+    future: Accessor<readonly T[]>;
+}
+/**
+ * Undoable state. `set()` records the previous value, `undo()` steps
+ * back through history, `redo()` steps forward, and any new `set()`
+ * discards the redo stack. Pure logic: no DOM, SSR-safe.
+ *
+ * ```tsx
+ * const doc = createUndo({ title: "", body: "" }, { capacity: 100 });
+ * <input
+ *   value={doc.value().title}
+ *   onInput={(e) => doc.set((d) => ({ ...d, title: e.target.value }))}
+ * />
+ * <button disabled={!doc.canUndo()} onClick={doc.undo}>Undo</button>
+ * <button disabled={!doc.canRedo()} onClick={doc.redo}>Redo</button>
+ * ```
+ */
+export declare function createUndo<T>(initial: T, options?: UndoOptions): UndoControls<T>;
+export interface FullscreenOptions {
+    /** Called when entering/exiting fails or is unsupported. */
+    onError?: (error: unknown) => void;
+}
+export interface FullscreenControls {
+    /** True while the referenced element is the fullscreen element. */
+    fullscreen: Accessor<boolean>;
+    enter: () => Promise<void>;
+    exit: () => Promise<void>;
+    toggle: () => Promise<void>;
+}
+/**
+ * Fullscreen for an element. Tracks `document.fullscreenElement` so the
+ * state stays correct when the user presses Escape or another element
+ * takes over. Failures (unsupported browser, denied request) go to
+ * `onError` instead of throwing. SSR-safe: never fullscreen on the
+ * server.
+ *
+ * ```tsx
+ * let stage!: HTMLDivElement;
+ * const fs = createFullscreen(() => stage);
+ * <button onClick={fs.toggle}>
+ *   {fs.fullscreen() ? "Exit fullscreen" : "Go fullscreen"}
+ * </button>
+ * <div ref={stage}>…</div>
+ * ```
+ */
+export declare function createFullscreen(ref: MaybeElement, options?: FullscreenOptions): FullscreenControls;
+export {};

package/dist/apputils.js ADDED Viewed

@@ -0,0 +1,326 @@
+import { createEffect, createSignal, onCleanup, untrack, } from "solid-js";
+const isSchemePreference = (value) => value === "light" || value === "dark" || value === "system";
+/**
+ * Color scheme manager. Resolves "system" through the
+ * `(prefers-color-scheme: dark)` media query (reactive to OS changes),
+ * persists the preference to localStorage, and writes the resolved
+ * scheme to `<html data-theme="light|dark">` plus `color-scheme` so
+ * form controls and scrollbars follow.
+ *
+ * SSR-safe: resolves "system" to "light" on the server.
+ *
+ * ```tsx
+ * const theme = createColorScheme();
+ * <button onClick={theme.toggle}>
+ *   {theme.scheme() === "dark" ? "Light mode" : "Dark mode"}
+ * </button>
+ * ```
+ */
+export function createColorScheme(options = {}) {
+    const { default: defaultPreference = "system", storageKey = "solid-drift:color-scheme", attribute = "data-theme", } = options;
+    const readStored = () => {
+        if (!storageKey || typeof window === "undefined")
+            return null;
+        try {
+            const raw = window.localStorage.getItem(storageKey);
+            return isSchemePreference(raw) ? raw : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const [preference, setPreference] = createSignal(readStored() ?? defaultPreference);
+    const [systemDark, setSystemDark] = createSignal(false);
+    if (typeof window !== "undefined") {
+        createEffect(() => {
+            const mq = window.matchMedia("(prefers-color-scheme: dark)");
+            setSystemDark(mq.matches);
+            const onChange = (event) => {
+                setSystemDark(event.matches);
+            };
+            mq.addEventListener("change", onChange);
+            onCleanup(() => mq.removeEventListener("change", onChange));
+        });
+        createEffect(() => {
+            const stored = preference();
+            const resolved = stored === "system" ? (systemDark() ? "dark" : "light") : stored;
+            const root = document.documentElement;
+            root.setAttribute(attribute, resolved);
+            root.style.colorScheme = resolved;
+            if (storageKey) {
+                try {
+                    window.localStorage.setItem(storageKey, preference());
+                }
+                catch {
+                    // Storage can be unavailable (private mode); the in-memory
+                    // preference still works for the session.
+                }
+            }
+        });
+    }
+    const scheme = () => {
+        const p = preference();
+        if (p !== "system")
+            return p;
+        if (typeof window === "undefined")
+            return "light";
+        return systemDark() ? "dark" : "light";
+    };
+    return {
+        scheme,
+        preference,
+        setPreference,
+        toggle: () => setPreference(scheme() === "dark" ? "light" : "dark"),
+    };
+}
+/**
+ * Idle detection. `idle()` becomes true after `timeout` ms without any
+ * of the activity events; any activity flips it back and restarts the
+ * timer. Useful for auto-hiding chrome, pausing ambient animation, or
+ * "are you still there" prompts.
+ *
+ * SSR-safe: never idle on the server.
+ *
+ * ```tsx
+ * const { idle } = createIdle({ timeout: 30_000 });
+ * <div classList={{ "controls-hidden": idle() }}>…</div>
+ * ```
+ */
+export function createIdle(options = {}) {
+    const { timeout = 60000, events = ["mousemove", "mousedown", "keydown", "touchstart", "wheel"], initialIdle = false, } = options;
+    if (typeof window === "undefined") {
+        const falsy = () => false;
+        return { idle: falsy, lastActive: () => 0, reset: () => { } };
+    }
+    const [idle, setIdle] = createSignal(initialIdle);
+    const [lastActive, setLastActive] = createSignal(Date.now());
+    let timer;
+    const arm = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => setIdle(true), Math.max(timeout, 0));
+    };
+    const onActivity = () => {
+        setLastActive(Date.now());
+        setIdle(false);
+        arm();
+    };
+    createEffect(() => {
+        for (const name of events) {
+            window.addEventListener(name, onActivity, { passive: true });
+        }
+        arm();
+        onCleanup(() => {
+            for (const name of events) {
+                window.removeEventListener(name, onActivity);
+            }
+            clearTimeout(timer);
+        });
+    });
+    return { idle, lastActive, reset: onActivity };
+}
+/**
+ * Network connectivity state. Seeds from `navigator.onLine` and follows
+ * the window `online` / `offline` events. SSR-safe: assumes online on
+ * the server.
+ *
+ * ```tsx
+ * const { online } = createOnline();
+ * <Show when={!online()}>
+ *   <p>You are offline. Changes will sync when you reconnect.</p>
+ * </Show>
+ * ```
+ */
+export function createOnline() {
+    if (typeof window === "undefined")
+        return { online: () => true };
+    const [online, setOnline] = createSignal(typeof navigator !== "undefined" ? navigator.onLine : true);
+    createEffect(() => {
+        const goOnline = () => {
+            setOnline(true);
+        };
+        const goOffline = () => {
+            setOnline(false);
+        };
+        window.addEventListener("online", goOnline);
+        window.addEventListener("offline", goOffline);
+        onCleanup(() => {
+            window.removeEventListener("online", goOnline);
+            window.removeEventListener("offline", goOffline);
+        });
+    });
+    return { online };
+}
+/**
+ * PWA install prompt. Captures the `beforeinstallprompt` event (calling
+ * `preventDefault()` so the browser does not show its own mini-bar) and
+ * exposes it through `prompt()`, which is safe to call from a click
+ * handler. SSR-safe: never installable on the server.
+ *
+ * ```tsx
+ * const install = createInstallPrompt();
+ * <Show when={install.canInstall()}>
+ *   <button
+ *     onClick={async () => {
+ *       const choice = await install.prompt();
+ *       if (choice?.outcome === "accepted") toast("Installed!");
+ *     }}
+ *   >
+ *     Install app
+ *   </button>
+ * </Show>
+ * ```
+ */
+export function createInstallPrompt() {
+    if (typeof window === "undefined") {
+        return { canInstall: () => false, prompt: async () => null };
+    }
+    const [deferred, setDeferred] = createSignal(null);
+    createEffect(() => {
+        const onBeforeInstall = (event) => {
+            event.preventDefault();
+            setDeferred(event);
+        };
+        window.addEventListener("beforeinstallprompt", onBeforeInstall);
+        onCleanup(() => window.removeEventListener("beforeinstallprompt", onBeforeInstall));
+    });
+    const prompt = async () => {
+        const event = deferred();
+        if (!event)
+            return null;
+        setDeferred(null);
+        await event.prompt();
+        return event.userChoice;
+    };
+    return { canInstall: () => deferred() !== null, prompt };
+}
+/**
+ * Undoable state. `set()` records the previous value, `undo()` steps
+ * back through history, `redo()` steps forward, and any new `set()`
+ * discards the redo stack. Pure logic: no DOM, SSR-safe.
+ *
+ * ```tsx
+ * const doc = createUndo({ title: "", body: "" }, { capacity: 100 });
+ * <input
+ *   value={doc.value().title}
+ *   onInput={(e) => doc.set((d) => ({ ...d, title: e.target.value }))}
+ * />
+ * <button disabled={!doc.canUndo()} onClick={doc.undo}>Undo</button>
+ * <button disabled={!doc.canRedo()} onClick={doc.redo}>Redo</button>
+ * ```
+ */
+export function createUndo(initial, options = {}) {
+    const { capacity = 50 } = options;
+    const limit = Math.max(Math.floor(capacity), 1);
+    const [value, setValue] = createSignal(initial);
+    const [past, setPast] = createSignal([]);
+    const [future, setFuture] = createSignal([]);
+    const set = (next) => {
+        const current = untrack(value);
+        const resolved = typeof next === "function" ? next(current) : next;
+        setPast((stack) => [...stack.slice(-(limit - 1)), current]);
+        setFuture([]);
+        setValue(resolved);
+    };
+    const undo = () => {
+        const stack = untrack(past);
+        if (stack.length === 0)
+            return;
+        const previous = stack[stack.length - 1];
+        setFuture((redo) => [untrack(value), ...redo]);
+        setPast(stack.slice(0, -1));
+        setValue(previous);
+    };
+    const redo = () => {
+        const stack = untrack(future);
+        if (stack.length === 0)
+            return;
+        const [next, ...rest] = stack;
+        setPast((done) => [...done.slice(-(limit - 1)), untrack(value)]);
+        setFuture(rest);
+        setValue(next);
+    };
+    const clear = () => {
+        setPast([]);
+        setFuture([]);
+    };
+    const reset = () => {
+        clear();
+        setValue(initial);
+    };
+    return {
+        value,
+        set,
+        undo,
+        redo,
+        clear,
+        reset,
+        canUndo: () => past().length > 0,
+        canRedo: () => future().length > 0,
+        past: past,
+        future: future,
+    };
+}
+/**
+ * Fullscreen for an element. Tracks `document.fullscreenElement` so the
+ * state stays correct when the user presses Escape or another element
+ * takes over. Failures (unsupported browser, denied request) go to
+ * `onError` instead of throwing. SSR-safe: never fullscreen on the
+ * server.
+ *
+ * ```tsx
+ * let stage!: HTMLDivElement;
+ * const fs = createFullscreen(() => stage);
+ * <button onClick={fs.toggle}>
+ *   {fs.fullscreen() ? "Exit fullscreen" : "Go fullscreen"}
+ * </button>
+ * <div ref={stage}>…</div>
+ * ```
+ */
+export function createFullscreen(ref, options = {}) {
+    const { onError } = options;
+    if (typeof window === "undefined") {
+        const falsy = () => false;
+        const noop = async () => { };
+        return { fullscreen: falsy, enter: noop, exit: noop, toggle: noop };
+    }
+    const [fullscreen, setFullscreen] = createSignal(false);
+    const sync = () => {
+        const el = ref();
+        setFullscreen(el != null && document.fullscreenElement === el);
+    };
+    createEffect(() => {
+        sync();
+        document.addEventListener("fullscreenchange", sync);
+        onCleanup(() => document.removeEventListener("fullscreenchange", sync));
+    });
+    const enter = async () => {
+        const el = ref();
+        if (!el || typeof el.requestFullscreen !== "function") {
+            onError?.(new Error("Fullscreen is not supported"));
+            return;
+        }
+        try {
+            await el.requestFullscreen();
+        }
+        catch (error) {
+            onError?.(error);
+        }
+    };
+    const exit = async () => {
+        if (!document.fullscreenElement)
+            return;
+        try {
+            await document.exitFullscreen();
+        }
+        catch (error) {
+            onError?.(error);
+        }
+    };
+    const toggle = async () => {
+        if (fullscreen())
+            await exit();
+        else
+            await enter();
+    };
+    return { fullscreen, enter, exit, toggle };
+}

package/dist/index.d.ts CHANGED Viewed

@@ -56,3 +56,13 @@ export { createCopy } from "./copy.js";
 export type { CopyOptions, CopyControls } from "./copy.js";
 export { createCountdown } from "./countdown.js";
 export type { CountdownOptions, CountdownControls } from "./countdown.js";
+export { createMarquee } from "./marquee.js";
+export type { MarqueeDirection, MarqueeOptions, MarqueeControls, } from "./marquee.js";
+export { createVariants } from "./variants.js";
+export type { VariantDef, VariantsOptions, VariantsControls, } from "./variants.js";
+export { createPathDraw } from "./pathdraw.js";
+export type { PathDrawOptions, PathDrawControls } from "./pathdraw.js";
+export { createPress, createHover } from "./press.js";
+export type { PressOptions, PressControls, HoverOptions, HoverControls, } from "./press.js";
+export { createColorScheme, createIdle, createOnline, createInstallPrompt, createUndo, createFullscreen, } from "./apputils.js";
+export type { ColorScheme, ColorSchemePreference, ColorSchemeOptions, ColorSchemeControls, IdleOptions, IdleControls, OnlineControls, BeforeInstallPromptEvent, InstallPromptControls, UndoOptions, UndoControls, FullscreenOptions, FullscreenControls, } from "./apputils.js";

package/dist/index.js CHANGED Viewed

@@ -44,3 +44,8 @@ export { createSkeleton } from "./skeleton.js";
 export { createScrollSpy } from "./scrollspy.js";
 export { createCopy } from "./copy.js";
 export { createCountdown } from "./countdown.js";
+export { createMarquee } from "./marquee.js";
+export { createVariants } from "./variants.js";
+export { createPathDraw } from "./pathdraw.js";
+export { createPress, createHover } from "./press.js";
+export { createColorScheme, createIdle, createOnline, createInstallPrompt, createUndo, createFullscreen, } from "./apputils.js";

package/dist/marquee.d.ts ADDED Viewed

@@ -0,0 +1,57 @@
+import { type Accessor } from "solid-js";
+/** Marquee scroll direction. Default "left". */
+export type MarqueeDirection = "left" | "right" | "up" | "down";
+export interface MarqueeOptions {
+    /** Pixels per second. Default 60. */
+    speed?: number;
+    /** Scroll direction. Default "left". */
+    direction?: MarqueeDirection;
+    /** Start scrolling immediately. Default true. */
+    autoStart?: boolean;
+}
+export interface MarqueeControls {
+    /**
+     * Current offset in px. Wraps at the content size, so rendering two
+     * copies of the content side by side and translating by `-offset()`
+     * (or `-offset()` on Y for vertical) loops seamlessly.
+     */
+    offset: Accessor<number>;
+    /** Whether the marquee clock task is running. */
+    running: Accessor<boolean>;
+    /**
+     * Width (horizontal directions) or height (vertical directions) of one
+     * loop unit in px. Measure the content and call this once it is known.
+     */
+    setContentSize: (px: number) => void;
+    start: () => void;
+    stop: () => void;
+}
+/**
+ * Infinite marquee scroller. The offset advances at `speed` px/s on the
+ * shared clock and wraps at the content size, so a doubled content strip
+ * loops seamlessly.
+ *
+ * Reduced-motion aware: marquees are pure motion, so under reduced motion
+ * the marquee stays static (offset 0, never runs). SSR-safe.
+ *
+ * ```tsx
+ * const marquee = createMarquee({ speed: 80 });
+ * let strip!: HTMLDivElement;
+ * createEffect(() => {
+ *   marquee.setContentSize(strip.scrollWidth / 2);
+ * });
+ * <div style={{ overflow: "hidden" }}>
+ *   <div
+ *     ref={strip}
+ *     style={{
+ *       display: "flex",
+ *       transform: `translateX(${-marquee.offset()}px)`,
+ *       "will-change": "transform",
+ *     }}
+ *   >
+ *     {items}{items}
+ *   </div>
+ * </div>
+ * ```
+ */
+export declare function createMarquee(options?: MarqueeOptions): MarqueeControls;

package/dist/marquee.js ADDED Viewed

@@ -0,0 +1,88 @@
+import { createSignal, onCleanup, untrack } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * Infinite marquee scroller. The offset advances at `speed` px/s on the
+ * shared clock and wraps at the content size, so a doubled content strip
+ * loops seamlessly.
+ *
+ * Reduced-motion aware: marquees are pure motion, so under reduced motion
+ * the marquee stays static (offset 0, never runs). SSR-safe.
+ *
+ * ```tsx
+ * const marquee = createMarquee({ speed: 80 });
+ * let strip!: HTMLDivElement;
+ * createEffect(() => {
+ *   marquee.setContentSize(strip.scrollWidth / 2);
+ * });
+ * <div style={{ overflow: "hidden" }}>
+ *   <div
+ *     ref={strip}
+ *     style={{
+ *       display: "flex",
+ *       transform: `translateX(${-marquee.offset()}px)`,
+ *       "will-change": "transform",
+ *     }}
+ *   >
+ *     {items}{items}
+ *   </div>
+ * </div>
+ * ```
+ */
+export function createMarquee(options = {}) {
+    const { speed = 60, direction = "left", autoStart = true } = options;
+    if (typeof window === "undefined") {
+        const zero = () => 0;
+        const falsy = () => false;
+        const noop = () => { };
+        return {
+            offset: zero,
+            running: falsy,
+            setContentSize: noop,
+            start: noop,
+            stop: noop,
+        };
+    }
+    const sign = direction === "left" || direction === "up" ? 1 : -1;
+    const [offset, setOffset] = createSignal(0);
+    const [running, setRunning] = createSignal(false);
+    let size = 0;
+    let phase = 0;
+    let last = 0;
+    let stopClock = null;
+    const task = (t) => {
+        const dt = Math.min(Math.max((t - last) / 1000, 0), 0.25);
+        last = t;
+        phase += speed * dt;
+        if (size > 0) {
+            setOffset((((phase * sign) % size) + size) % size);
+        }
+        return true;
+    };
+    const start = () => {
+        if (untrack(running) || prefersReducedMotion())
+            return;
+        setRunning(true);
+        last = now();
+        stopClock = schedule(task);
+    };
+    const stop = () => {
+        stopClock?.();
+        stopClock = null;
+        setRunning(false);
+    };
+    onCleanup(stop);
+    if (autoStart)
+        start();
+    return {
+        offset,
+        running,
+        setContentSize: (px) => {
+            size = Math.max(px, 0);
+            phase = 0;
+            setOffset(0);
+        },
+        start,
+        stop,
+    };
+}

package/dist/pathdraw.d.ts ADDED Viewed

@@ -0,0 +1,49 @@
+import { type Accessor } from "solid-js";
+import { type Easing } from "./easing.js";
+export interface PathDrawOptions {
+    /** Draw duration in ms. Default 1200. */
+    duration?: number;
+    /** Easing for the draw progress. Default easeInOutCubic. */
+    easing?: Easing;
+    /** Start drawing immediately. Default true. */
+    autoStart?: boolean;
+    /** Fires once when the draw completes. */
+    onDone?: () => void;
+}
+export interface PathDrawControls {
+    /** Eased draw progress, 0 to 1. */
+    progress: Accessor<number>;
+    /** Whether the draw clock task is running. */
+    running: Accessor<boolean>;
+    start: () => void;
+    stop: () => void;
+    /** Back to undrawn (progress 0). */
+    reset: () => void;
+}
+/**
+ * SVG path drawing animation. Drives `stroke-dashoffset` from the full
+ * path length to 0 so the stroke draws itself on, eased on the shared
+ * clock. The length is read with `getTotalLength()`, so any path shape
+ * works with no manual measuring.
+ *
+ * Under reduced motion (and on the server) the path renders fully drawn.
+ * SSR-safe.
+ *
+ * ```tsx
+ * let path!: SVGPathElement;
+ * const draw = createPathDraw(() => path, {
+ *   duration: 1600,
+ *   onDone: () => console.log("drawn"),
+ * });
+ * <svg viewBox="0 0 100 100">
+ *   <path
+ *     ref={path}
+ *     d="M10 80 C 40 10, 60 10, 90 80"
+ *     fill="none"
+ *     stroke="currentColor"
+ *     stroke-width="3"
+ *   />
+ * </svg>
+ * ```
+ */
+export declare function createPathDraw(ref: () => SVGPathElement | null | undefined, options?: PathDrawOptions): PathDrawControls;

package/dist/pathdraw.js ADDED Viewed

@@ -0,0 +1,106 @@
+import { createSignal, onCleanup } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { easeInOutCubic } from "./easing.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * SVG path drawing animation. Drives `stroke-dashoffset` from the full
+ * path length to 0 so the stroke draws itself on, eased on the shared
+ * clock. The length is read with `getTotalLength()`, so any path shape
+ * works with no manual measuring.
+ *
+ * Under reduced motion (and on the server) the path renders fully drawn.
+ * SSR-safe.
+ *
+ * ```tsx
+ * let path!: SVGPathElement;
+ * const draw = createPathDraw(() => path, {
+ *   duration: 1600,
+ *   onDone: () => console.log("drawn"),
+ * });
+ * <svg viewBox="0 0 100 100">
+ *   <path
+ *     ref={path}
+ *     d="M10 80 C 40 10, 60 10, 90 80"
+ *     fill="none"
+ *     stroke="currentColor"
+ *     stroke-width="3"
+ *   />
+ * </svg>
+ * ```
+ */
+export function createPathDraw(ref, options = {}) {
+    const { duration = 1200, easing = easeInOutCubic, autoStart = true, onDone, } = options;
+    const [progress, setProgress] = createSignal(0);
+    const [running, setRunning] = createSignal(false);
+    if (typeof window === "undefined") {
+        const noop = () => { };
+        return { progress, running, start: noop, stop: noop, reset: noop };
+    }
+    let stopClock = null;
+    let doneFired = false;
+    const paint = (p) => {
+        const el = ref();
+        if (!el || typeof el.getTotalLength !== "function")
+            return;
+        const len = el.getTotalLength();
+        el.style.strokeDasharray = `${len}`;
+        el.style.strokeDashoffset = `${len * (1 - p)}`;
+    };
+    const finish = () => {
+        setProgress(1);
+        paint(1);
+        setRunning(false);
+        stopClock = null;
+        if (!doneFired) {
+            doneFired = true;
+            onDone?.();
+        }
+    };
+    const start = () => {
+        if (running())
+            return;
+        if (duration <= 0 || prefersReducedMotion()) {
+            setProgress(1);
+            finish();
+            return;
+        }
+        doneFired = false;
+        setRunning(true);
+        const from = progress();
+        if (from >= 1) {
+            finish();
+            return;
+        }
+        // Remaining time is proportional, so resume keeps a constant speed.
+        const span = Math.max(duration * (1 - from), 1);
+        const t0 = now();
+        paint(from);
+        stopClock?.();
+        stopClock = schedule((t) => {
+            const p = Math.min(Math.max((t - t0) / span, 0), 1);
+            const eased = from + (1 - from) * easing(p);
+            setProgress(eased);
+            paint(eased);
+            if (p >= 1) {
+                finish();
+                return false;
+            }
+            return true;
+        });
+    };
+    const stop = () => {
+        stopClock?.();
+        stopClock = null;
+        setRunning(false);
+    };
+    const reset = () => {
+        stop();
+        doneFired = false;
+        setProgress(0);
+        paint(0);
+    };
+    onCleanup(stop);
+    if (autoStart)
+        start();
+    return { progress, running, start, stop, reset };
+}

package/dist/press.d.ts ADDED Viewed

@@ -0,0 +1,57 @@
+import { type Accessor } from "solid-js";
+type MaybeElement = () => Element | null | undefined;
+export interface PressOptions {
+    /** Fires whenever the pressed state changes. */
+    onChange?: (pressed: boolean) => void;
+}
+export interface PressControls {
+    /** True while the pointer (or keyboard) is pressing the element. */
+    pressed: Accessor<boolean>;
+}
+export interface HoverOptions {
+    /** Fires whenever the hovering state changes. */
+    onChange?: (hovering: boolean) => void;
+}
+export interface HoverControls {
+    /** True while the pointer is over the element (or it has focus). */
+    hovering: Accessor<boolean>;
+}
+/**
+ * Press gesture state. Tracks pointer down/up on the element (mouse,
+ * touch, and pen via pointer events) plus Enter/Space key presses for
+ * keyboard parity. There is no animation here: the host decides how to
+ * respond, typically by driving `createVariants`.
+ *
+ * SSR-safe: always unpressed on the server.
+ *
+ * ```tsx
+ * let btn!: HTMLButtonElement;
+ * const press = createPress(() => btn);
+ * <button
+ *   ref={btn}
+ *   style={{
+ *     transform: press.pressed() ? "scale(0.96)" : "scale(1)",
+ *     transition: "transform 120ms",
+ *   }}
+ * >
+ *   Hold me
+ * </button>
+ * ```
+ */
+export declare function createPress(ref: MaybeElement, options?: PressOptions): PressControls;
+/**
+ * Hover gesture state. Tracks pointer enter/leave plus focus/blur so
+ * keyboard users get the same state. Like `createPress` this is state
+ * only: pair it with `createVariants` (or plain styles) to animate.
+ *
+ * SSR-safe: never hovering on the server.
+ *
+ * ```tsx
+ * let card!: HTMLDivElement;
+ * const hover = createHover(() => card, {
+ *   onChange: (h) => variants.go(h ? "hover" : "idle"),
+ * });
+ * ```
+ */
+export declare function createHover(ref: MaybeElement, options?: HoverOptions): HoverControls;
+export {};

package/dist/press.js ADDED Viewed

@@ -0,0 +1,116 @@
+import { createEffect, createSignal, onCleanup } from "solid-js";
+const falsy = () => false;
+/**
+ * Press gesture state. Tracks pointer down/up on the element (mouse,
+ * touch, and pen via pointer events) plus Enter/Space key presses for
+ * keyboard parity. There is no animation here: the host decides how to
+ * respond, typically by driving `createVariants`.
+ *
+ * SSR-safe: always unpressed on the server.
+ *
+ * ```tsx
+ * let btn!: HTMLButtonElement;
+ * const press = createPress(() => btn);
+ * <button
+ *   ref={btn}
+ *   style={{
+ *     transform: press.pressed() ? "scale(0.96)" : "scale(1)",
+ *     transition: "transform 120ms",
+ *   }}
+ * >
+ *   Hold me
+ * </button>
+ * ```
+ */
+export function createPress(ref, options = {}) {
+    const { onChange } = options;
+    if (typeof window === "undefined")
+        return { pressed: falsy };
+    const [pressed, setPressed] = createSignal(false);
+    const set = (value) => {
+        setPressed((prev) => {
+            if (prev !== value)
+                onChange?.(value);
+            return value;
+        });
+    };
+    createEffect(() => {
+        const el = ref();
+        if (!el)
+            return;
+        const down = () => set(true);
+        const up = () => set(false);
+        const onKeyDown = (event) => {
+            if (event.key === "Enter" || event.key === " ") {
+                if (!event.repeat)
+                    set(true);
+                if (event.key === " ")
+                    event.preventDefault?.();
+            }
+        };
+        const onKeyUp = (event) => {
+            if (event.key === "Enter" || event.key === " ")
+                set(false);
+        };
+        el.addEventListener("pointerdown", down);
+        el.addEventListener("pointerup", up);
+        el.addEventListener("pointercancel", up);
+        el.addEventListener("pointerleave", up);
+        el.addEventListener("keydown", onKeyDown);
+        el.addEventListener("keyup", onKeyUp);
+        onCleanup(() => {
+            el.removeEventListener("pointerdown", down);
+            el.removeEventListener("pointerup", up);
+            el.removeEventListener("pointercancel", up);
+            el.removeEventListener("pointerleave", up);
+            el.removeEventListener("keydown", onKeyDown);
+            el.removeEventListener("keyup", onKeyUp);
+        });
+    });
+    return { pressed };
+}
+/**
+ * Hover gesture state. Tracks pointer enter/leave plus focus/blur so
+ * keyboard users get the same state. Like `createPress` this is state
+ * only: pair it with `createVariants` (or plain styles) to animate.
+ *
+ * SSR-safe: never hovering on the server.
+ *
+ * ```tsx
+ * let card!: HTMLDivElement;
+ * const hover = createHover(() => card, {
+ *   onChange: (h) => variants.go(h ? "hover" : "idle"),
+ * });
+ * ```
+ */
+export function createHover(ref, options = {}) {
+    const { onChange } = options;
+    if (typeof window === "undefined")
+        return { hovering: falsy };
+    const [hovering, setHovering] = createSignal(false);
+    const set = (value) => {
+        setHovering((prev) => {
+            if (prev !== value)
+                onChange?.(value);
+            return value;
+        });
+    };
+    createEffect(() => {
+        const el = ref();
+        if (!el)
+            return;
+        const enter = () => set(true);
+        const leave = () => set(false);
+        el.addEventListener("pointerenter", enter);
+        el.addEventListener("pointerleave", leave);
+        el.addEventListener("focus", enter);
+        el.addEventListener("blur", leave);
+        onCleanup(() => {
+            el.removeEventListener("pointerenter", enter);
+            el.removeEventListener("pointerleave", leave);
+            el.removeEventListener("focus", enter);
+            el.removeEventListener("blur", leave);
+        });
+    });
+    return { hovering };
+}

package/dist/variants.d.ts ADDED Viewed

@@ -0,0 +1,63 @@
+import { type Accessor } from "solid-js";
+import { type Easing } from "./easing.js";
+/**
+ * One named animation state: CSS-ish property values. Numeric values
+ * interpolate; anything else snaps to the target when the transition
+ * finishes.
+ */
+export interface VariantDef {
+    [prop: string]: number | string;
+}
+export interface VariantsOptions {
+    /** Variant applied immediately on creation. */
+    initial?: string;
+    /** Transition length in ms. Default 250. */
+    duration?: number;
+    /** Easing for numeric interpolation. Default easeOutCubic. */
+    easing?: Easing;
+}
+export interface VariantsControls {
+    /** Name of the last variant passed to `go`. */
+    current: Accessor<string | undefined>;
+    /**
+     * Current interpolated values. Bind these straight into styles:
+     * `style={{ transform: `scale(${v.values().scale})` }}`.
+     */
+    values: Accessor<Record<string, number | string>>;
+    /** Transition to the named variant. Unknown names are ignored. */
+    go: (name: string) => void;
+}
+/**
+ * Named animation states with tweened transitions, in the vocabulary of
+ * "variants". `go(name)` interpolates every numeric property from the
+ * current values to the target variant on the shared clock; non-numeric
+ * properties (colors, keywords) snap at the end of the transition.
+ *
+ * Pairs with `createHover` / `createPress`: map gesture states to variant
+ * names and the element animates between them.
+ *
+ * Under reduced motion (and on the server) transitions snap instantly.
+ * SSR-safe.
+ *
+ * ```tsx
+ * const card = createVariants(
+ *   {
+ *     idle: { scale: 1, shadow: 0 },
+ *     hover: { scale: 1.04, shadow: 12 },
+ *     press: { scale: 0.96, shadow: 4 },
+ *   },
+ *   { initial: "idle", duration: 180 },
+ * );
+ * createHover(() => el, {
+ *   onChange: (h) => card.go(h ? "hover" : "idle"),
+ * });
+ * <div
+ *   ref={el}
+ *   style={{
+ *     transform: `scale(${card.values().scale})`,
+ *     "box-shadow": `0 ${card.values().shadow}px 24px rgb(0 0 0 / 0.12)`,
+ *   }}
+ * />
+ * ```
+ */
+export declare function createVariants(variants: Record<string, VariantDef>, options?: VariantsOptions): VariantsControls;

package/dist/variants.js ADDED Viewed

@@ -0,0 +1,86 @@
+import { createSignal, onCleanup, untrack } from "solid-js";
+import { now, schedule } from "./engine.js";
+import { easeOutCubic } from "./easing.js";
+import { prefersReducedMotion } from "./reduced-motion.js";
+/**
+ * Named animation states with tweened transitions, in the vocabulary of
+ * "variants". `go(name)` interpolates every numeric property from the
+ * current values to the target variant on the shared clock; non-numeric
+ * properties (colors, keywords) snap at the end of the transition.
+ *
+ * Pairs with `createHover` / `createPress`: map gesture states to variant
+ * names and the element animates between them.
+ *
+ * Under reduced motion (and on the server) transitions snap instantly.
+ * SSR-safe.
+ *
+ * ```tsx
+ * const card = createVariants(
+ *   {
+ *     idle: { scale: 1, shadow: 0 },
+ *     hover: { scale: 1.04, shadow: 12 },
+ *     press: { scale: 0.96, shadow: 4 },
+ *   },
+ *   { initial: "idle", duration: 180 },
+ * );
+ * createHover(() => el, {
+ *   onChange: (h) => card.go(h ? "hover" : "idle"),
+ * });
+ * <div
+ *   ref={el}
+ *   style={{
+ *     transform: `scale(${card.values().scale})`,
+ *     "box-shadow": `0 ${card.values().shadow}px 24px rgb(0 0 0 / 0.12)`,
+ *   }}
+ * />
+ * ```
+ */
+export function createVariants(variants, options = {}) {
+    const { initial, duration = 250, easing = easeOutCubic } = options;
+    const first = initial ?? Object.keys(variants)[0];
+    const [current, setCurrent] = createSignal(first);
+    const [values, setValues] = createSignal({
+        ...(first ? variants[first] : {}),
+    });
+    if (typeof window === "undefined") {
+        return { current, values, go: () => { } };
+    }
+    let stopClock = null;
+    const go = (name) => {
+        const target = variants[name];
+        if (!target)
+            return;
+        setCurrent(name);
+        stopClock?.();
+        stopClock = null;
+        const from = untrack(values);
+        if (duration <= 0 || prefersReducedMotion()) {
+            setValues({ ...target });
+            return;
+        }
+        const start = now();
+        const numeric = Object.keys(target).filter((k) => typeof target[k] === "number" && typeof from[k] === "number");
+        stopClock = schedule((t) => {
+            const p = Math.min(Math.max((t - start) / duration, 0), 1);
+            const e = easing(p);
+            const next = { ...untrack(values) };
+            for (const k of numeric) {
+                const a = from[k];
+                const b = target[k];
+                next[k] = a + (b - a) * e;
+            }
+            if (p >= 1) {
+                // Snap non-numeric props (and exact numeric targets) at the end.
+                for (const k of Object.keys(target))
+                    next[k] = target[k];
+                setValues(next);
+                stopClock = null;
+                return false;
+            }
+            setValues(next);
+            return true;
+        });
+    };
+    onCleanup(() => stopClock?.());
+    return { current, values, go };
+}

package/package.json CHANGED Viewed

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