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

solid-drift 0.31.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 (6) hide show

package/README.md CHANGED Viewed

@@ -1698,6 +1698,34 @@ const draw = createPathDraw(() => mark, { duration: 1600 });
 - `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

@@ -64,3 +64,5 @@ 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

@@ -48,3 +48,4 @@ 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/package.json CHANGED Viewed

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