@c9up/aurora 0.1.6 → 0.1.7

package/README.md

@@ -24,7 +24,7 @@ providers: [
 
 ## Entry points
 
-- `@c9up/aurora` — main API
+- `@c9up/aurora` — main API: reactive primitives (`signal`/`effect`/`html`/`component`/`hydrate`) plus the client toolkit — `WebStorage`/`persistedSignal`, reactive browser signals (`prefersDark`/`online`/`windowSize`/…), SPA navigation (`navigate`/`queryParam`), `cookie`/`clipboard`/`share`, and the `HttpClient` fetch wrapper
 - `@c9up/aurora/provider` — Ream IoC provider
 - `@c9up/aurora/services/main` — container service accessor
 - `@c9up/aurora/relay` — realtime adapter

package/dist/browser.d.ts

@@ -6,6 +6,7 @@
  * without `typeof window` guards at every call site. Node-free — part of the
  * client barrel.
  */
+import { type Signal } from "./reactive.js";
 /** Navigate to `url` with a full page load. No-op during SSR. */
 export declare function redirect(url: string): void;
 /**
@@ -15,14 +16,145 @@ export declare function redirect(url: string): void;
 export declare function replace(url: string): void;
 /** Reload the current page. No-op during SSR. */
 export declare function reload(): void;
+/** Which Web Storage area backs a {@link WebStorage}. */
+export type StorageArea = "local" | "session";
+export interface WebStorageOptions {
+    /**
+     * Key namespace, e.g. `"myapp:"`. Keys are written and read prefixed so
+     * independent stores never collide. Default `""` (no namespace).
+     */
+    prefix?: string;
+    /**
+     * Backing area — `"local"` (`localStorage`, persists across sessions, the
+     * default) or `"session"` (`sessionStorage`, cleared when the tab closes).
+     */
+    area?: StorageArea;
+}
 /**
- * Typed, SSR-safe `localStorage` wrapper. Values are JSON-serialised; reads
- * return `null` on the server, on a missing key, or on malformed JSON. Writes
- * swallow quota / private-mode errors so a full storage never crashes the app.
+ * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ *
+ * - Values are JSON-serialised; reads return `null` on the server, on a missing
+ *   key, or on malformed JSON.
+ * - Writes swallow quota / private-mode errors so a full store never crashes
+ *   the app (best-effort).
+ * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
+ *   so two prefixed stores over the same area never touch each other's data.
  */
-export declare const storage: {
+export declare class WebStorage {
+    #private;
+    constructor(options?: WebStorageOptions);
+    /** The on-disk key for `key`, namespaced by the configured prefix. */
+    fullKey(key: string): string;
     get<T>(key: string): T | null;
     set(key: string, value: unknown): void;
+    /** Whether `key` is present (and not the server). */
+    has(key: string): boolean;
     remove(key: string): void;
+    /** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
+    getOrSet<T>(key: string, factory: () => T): T;
+    /** Keys in this store, prefix stripped. Empty array during SSR. */
+    keys(): string[];
+    /** Remove this store's keys. With no prefix this clears the whole area. */
     clear(): void;
+}
+/**
+ * Default `localStorage` store (no namespace). Backward-compatible with the
+ * previous `storage.get/set/remove/clear` helper, plus `has`/`keys`/`getOrSet`.
+ */
+export declare const storage: WebStorage;
+/** Default `sessionStorage` store (no namespace) — cleared when the tab closes. */
+export declare const session: WebStorage;
+export interface PersistedSignalOptions extends WebStorageOptions {
+    /**
+     * Update the signal when ANOTHER tab writes the same key (the browser
+     * `storage` event). Default `true`. Only effective for `area: "local"` —
+     * the browser never emits storage events for `sessionStorage` across tabs.
+     */
+    crossTab?: boolean;
+}
+/**
+ * A {@link Signal} whose value is mirrored to web storage.
+ *
+ * The initial value is read from storage (falling back to `initial` on a miss)
+ * and every write is persisted via a reactive `effect`. With `crossTab`
+ * (default `true`, local area only) the signal also updates live when another
+ * tab writes the same key. SSR-safe: with no `window` it is a plain in-memory
+ * signal seeded with `initial`. Because the mirror runs inside `effect`, a
+ * `persistedSignal` created in a component's setup is disposed with it.
+ */
+export declare function persistedSignal<T>(key: string, initial: T, options?: PersistedSignalOptions): Signal<T>;
+/** Reactive `window.matchMedia(query).matches`. `false` during SSR. */
+export declare function mediaQuery(query: string): Signal<boolean>;
+/** Reactive `prefers-color-scheme: dark`. Shortcut over {@link mediaQuery}. */
+export declare function prefersDark(): Signal<boolean>;
+/** Reactive online/offline status (`navigator.onLine`). `true` during SSR. */
+export declare function online(): Signal<boolean>;
+export interface WindowSize {
+    width: number;
+    height: number;
+}
+/** Reactive `{ width, height }` of the viewport. `{0,0}` during SSR. */
+export declare function windowSize(): Signal<WindowSize>;
+/** Reactive tab visibility (`!document.hidden`). `true` during SSR. */
+export declare function visibility(): Signal<boolean>;
+/** Reactive `window.location.hash`. `""` during SSR. */
+export declare function hash(): Signal<string>;
+/** Go back one history entry. No-op during SSR. */
+export declare function back(): void;
+/** Go forward one history entry. No-op during SSR. */
+export declare function forward(): void;
+/**
+ * SPA navigation: push `url` onto history WITHOUT a full page reload (contrast
+ * {@link redirect}, which reloads). Emits a `popstate` event so reactive URL
+ * consumers — e.g. {@link queryParam} or a router — pick up the change. No-op
+ * during SSR.
+ */
+export declare function navigate(url: string): void;
+/**
+ * A {@link Signal} bound to a single URL query parameter. Reading reflects the
+ * current value (`null` when absent); writing updates the URL via `pushState`
+ * (no reload). Stays in sync with back/forward and {@link navigate} through the
+ * `popstate` event. SSR-safe: a plain `null` signal with no listeners.
+ */
+export declare function queryParam(key: string): Signal<string | null>;
+export interface CookieOptions {
+    /** Path scope. Default `"/"`. */
+    path?: string;
+    /** Lifetime in seconds. */
+    maxAge?: number;
+    /** Absolute expiry. */
+    expires?: Date;
+    /** Domain scope. */
+    domain?: string;
+    /** SameSite policy. */
+    sameSite?: "strict" | "lax" | "none";
+    /** Restrict to HTTPS. */
+    secure?: boolean;
+}
+/**
+ * SSR-safe cookie accessor — the one store {@link WebStorage} can't cover, for
+ * values the server also reads. Reads return `null` during SSR; writes are a
+ * no-op. Names and values are URL-encoded.
+ */
+export declare const cookie: {
+    get(name: string): string | null;
+    set(name: string, value: string, options?: CookieOptions): void;
+    remove(name: string, options?: Pick<CookieOptions, "path" | "domain">): void;
 };
+/** Async clipboard access. Methods return `false`/`null` when unavailable. */
+export declare const clipboard: {
+    /** Copy `text`. Returns whether it succeeded. */
+    copy(text: string): Promise<boolean>;
+    /** Read clipboard text, or `null` if unavailable / denied. */
+    read(): Promise<string | null>;
+};
+export interface ShareData {
+    title?: string;
+    text?: string;
+    url?: string;
+}
+/**
+ * Invoke the native Web Share sheet. Returns `false` when unsupported or the
+ * user cancels — never throws.
+ */
+export declare function share(data: ShareData): Promise<boolean>;

package/dist/browser.js

@@ -6,6 +6,7 @@
  * without `typeof window` guards at every call site. Node-free — part of the
  * client barrel.
  */
+import { effect, signal } from "./reactive.js";
 /** Navigate to `url` with a full page load. No-op during SSR. */
 export function redirect(url) {
     if (typeof window !== "undefined") {
@@ -28,15 +29,38 @@ export function reload() {
     }
 }
 /**
- * Typed, SSR-safe `localStorage` wrapper. Values are JSON-serialised; reads
- * return `null` on the server, on a missing key, or on malformed JSON. Writes
- * swallow quota / private-mode errors so a full storage never crashes the app.
+ * Typed, SSR-safe key/value store over `localStorage` / `sessionStorage`.
+ *
+ * - Values are JSON-serialised; reads return `null` on the server, on a missing
+ *   key, or on malformed JSON.
+ * - Writes swallow quota / private-mode errors so a full store never crashes
+ *   the app (best-effort).
+ * - `prefix` namespaces keys; {@link keys} and {@link clear} stay scoped to it,
+ *   so two prefixed stores over the same area never touch each other's data.
  */
-export const storage = {
+export class WebStorage {
+    #prefix;
+    #area;
+    constructor(options = {}) {
+        this.#prefix = options.prefix ?? "";
+        this.#area = options.area ?? "local";
+    }
+    #backend() {
+        if (typeof window === "undefined")
+            return undefined;
+        return this.#area === "session"
+            ? window.sessionStorage
+            : window.localStorage;
+    }
+    /** The on-disk key for `key`, namespaced by the configured prefix. */
+    fullKey(key) {
+        return this.#prefix + key;
+    }
     get(key) {
-        if (typeof localStorage === "undefined")
+        const backend = this.#backend();
+        if (!backend)
             return null;
-        const raw = localStorage.getItem(key);
+        const raw = backend.getItem(this.fullKey(key));
         if (raw === null)
             return null;
         try {
@@ -45,25 +69,310 @@ export const storage = {
         catch {
             return null;
         }
-    },
+    }
     set(key, value) {
-        if (typeof localStorage === "undefined")
+        const backend = this.#backend();
+        if (!backend)
             return;
         try {
-            localStorage.setItem(key, JSON.stringify(value));
+            backend.setItem(this.fullKey(key), JSON.stringify(value));
         }
         catch {
             // QuotaExceededError / Safari private mode — best-effort write.
         }
-    },
+    }
+    /** Whether `key` is present (and not the server). */
+    has(key) {
+        const backend = this.#backend();
+        if (!backend)
+            return false;
+        return backend.getItem(this.fullKey(key)) !== null;
+    }
     remove(key) {
-        if (typeof localStorage !== "undefined") {
-            localStorage.removeItem(key);
+        this.#backend()?.removeItem(this.fullKey(key));
+    }
+    /** Read `key`, or compute + persist `factory()` on a miss, returning the value. */
+    getOrSet(key, factory) {
+        const existing = this.get(key);
+        if (existing !== null)
+            return existing;
+        const value = factory();
+        this.set(key, value);
+        return value;
+    }
+    /** Keys in this store, prefix stripped. Empty array during SSR. */
+    keys() {
+        const backend = this.#backend();
+        if (!backend)
+            return [];
+        const out = [];
+        for (let i = 0; i < backend.length; i++) {
+            const k = backend.key(i);
+            if (k === null)
+                continue;
+            if (this.#prefix === "" || k.startsWith(this.#prefix)) {
+                out.push(k.slice(this.#prefix.length));
+            }
         }
-    },
+        return out;
+    }
+    /** Remove this store's keys. With no prefix this clears the whole area. */
     clear() {
-        if (typeof localStorage !== "undefined") {
-            localStorage.clear();
+        const backend = this.#backend();
+        if (!backend)
+            return;
+        if (this.#prefix === "") {
+            backend.clear();
+            return;
+        }
+        for (const key of this.keys())
+            backend.removeItem(this.fullKey(key));
+    }
+}
+/**
+ * Default `localStorage` store (no namespace). Backward-compatible with the
+ * previous `storage.get/set/remove/clear` helper, plus `has`/`keys`/`getOrSet`.
+ */
+export const storage = new WebStorage();
+/** Default `sessionStorage` store (no namespace) — cleared when the tab closes. */
+export const session = new WebStorage({ area: "session" });
+/**
+ * A {@link Signal} whose value is mirrored to web storage.
+ *
+ * The initial value is read from storage (falling back to `initial` on a miss)
+ * and every write is persisted via a reactive `effect`. With `crossTab`
+ * (default `true`, local area only) the signal also updates live when another
+ * tab writes the same key. SSR-safe: with no `window` it is a plain in-memory
+ * signal seeded with `initial`. Because the mirror runs inside `effect`, a
+ * `persistedSignal` created in a component's setup is disposed with it.
+ */
+export function persistedSignal(key, initial, options = {}) {
+    const store = new WebStorage(options);
+    const stored = store.get(key);
+    const sig = signal(stored !== null ? stored : initial);
+    // Mirror every change back to storage; runs once immediately, then on change.
+    effect(() => {
+        store.set(key, sig());
+    });
+    if ((options.crossTab ?? true) &&
+        (options.area ?? "local") === "local" &&
+        typeof window !== "undefined") {
+        const fullKey = store.fullKey(key);
+        window.addEventListener("storage", (event) => {
+            if (event.key !== fullKey || event.newValue === null)
+                return;
+            try {
+                sig(JSON.parse(event.newValue));
+            }
+            catch {
+                // Ignore a malformed cross-tab write.
+            }
+        });
+    }
+    return sig;
+}
+// ─── Reactive browser-state signals ──────────────────────────────────
+//
+// Each returns a Signal seeded from the current browser state and refreshed
+// when the relevant event fires. The listener lives for the page lifetime, so
+// create these ONCE at module scope and share the signal rather than calling
+// them per component render. SSR-safe: with no `window`/`document`/`navigator`
+// they return a plain signal seeded with a sensible default and never listen.
+/**
+ * Internal: a signal seeded by `read()` and refreshed when any of `events`
+ * fire on `target`. `target` is `undefined` during SSR — then it's a static
+ * signal of the default `read()`.
+ */
+function eventSignal(target, events, read) {
+    const sig = signal(read());
+    if (target) {
+        const update = () => {
+            sig(read());
+        };
+        for (const ev of events)
+            target.addEventListener(ev, update);
+    }
+    return sig;
+}
+/** Reactive `window.matchMedia(query).matches`. `false` during SSR. */
+export function mediaQuery(query) {
+    if (typeof window === "undefined" ||
+        typeof window.matchMedia !== "function") {
+        return signal(false);
+    }
+    const mql = window.matchMedia(query);
+    const sig = signal(mql.matches);
+    mql.addEventListener("change", (event) => {
+        sig(event.matches);
+    });
+    return sig;
+}
+/** Reactive `prefers-color-scheme: dark`. Shortcut over {@link mediaQuery}. */
+export function prefersDark() {
+    return mediaQuery("(prefers-color-scheme: dark)");
+}
+/** Reactive online/offline status (`navigator.onLine`). `true` during SSR. */
+export function online() {
+    const read = () => typeof navigator === "undefined" ? true : navigator.onLine;
+    return eventSignal(typeof window === "undefined" ? undefined : window, ["online", "offline"], read);
+}
+/** Reactive `{ width, height }` of the viewport. `{0,0}` during SSR. */
+export function windowSize() {
+    const read = () => typeof window === "undefined"
+        ? { width: 0, height: 0 }
+        : { width: window.innerWidth, height: window.innerHeight };
+    return eventSignal(typeof window === "undefined" ? undefined : window, ["resize"], read);
+}
+/** Reactive tab visibility (`!document.hidden`). `true` during SSR. */
+export function visibility() {
+    const read = () => typeof document === "undefined" ? true : !document.hidden;
+    return eventSignal(typeof document === "undefined" ? undefined : document, ["visibilitychange"], read);
+}
+/** Reactive `window.location.hash`. `""` during SSR. */
+export function hash() {
+    const read = () => typeof window === "undefined" ? "" : window.location.hash;
+    return eventSignal(typeof window === "undefined" ? undefined : window, ["hashchange"], read);
+}
+// ─── URL / history (SPA navigation) ──────────────────────────────────
+/** Go back one history entry. No-op during SSR. */
+export function back() {
+    if (typeof window !== "undefined")
+        window.history.back();
+}
+/** Go forward one history entry. No-op during SSR. */
+export function forward() {
+    if (typeof window !== "undefined")
+        window.history.forward();
+}
+/**
+ * SPA navigation: push `url` onto history WITHOUT a full page reload (contrast
+ * {@link redirect}, which reloads). Emits a `popstate` event so reactive URL
+ * consumers — e.g. {@link queryParam} or a router — pick up the change. No-op
+ * during SSR.
+ */
+export function navigate(url) {
+    if (typeof window === "undefined")
+        return;
+    window.history.pushState({}, "", url);
+    window.dispatchEvent(new Event("popstate"));
+}
+/**
+ * A {@link Signal} bound to a single URL query parameter. Reading reflects the
+ * current value (`null` when absent); writing updates the URL via `pushState`
+ * (no reload). Stays in sync with back/forward and {@link navigate} through the
+ * `popstate` event. SSR-safe: a plain `null` signal with no listeners.
+ */
+export function queryParam(key) {
+    const read = () => typeof window === "undefined"
+        ? null
+        : new URLSearchParams(window.location.search).get(key);
+    const sig = signal(read());
+    if (typeof window !== "undefined") {
+        window.addEventListener("popstate", () => {
+            sig(read());
+        });
+        // Mirror writes back to the URL (skips the no-op initial run).
+        effect(() => {
+            const value = sig();
+            const url = new URL(window.location.href);
+            if (value === null)
+                url.searchParams.delete(key);
+            else
+                url.searchParams.set(key, value);
+            const next = url.pathname + url.search + url.hash;
+            const current = window.location.pathname +
+                window.location.search +
+                window.location.hash;
+            if (next !== current)
+                window.history.pushState({}, "", next);
+        });
+    }
+    return sig;
+}
+/**
+ * SSR-safe cookie accessor — the one store {@link WebStorage} can't cover, for
+ * values the server also reads. Reads return `null` during SSR; writes are a
+ * no-op. Names and values are URL-encoded.
+ */
+export const cookie = {
+    get(name) {
+        if (typeof document === "undefined")
+            return null;
+        const prefix = `${encodeURIComponent(name)}=`;
+        for (const part of document.cookie.split("; ")) {
+            if (part.startsWith(prefix)) {
+                return decodeURIComponent(part.slice(prefix.length));
+            }
+        }
+        return null;
+    },
+    set(name, value, options = {}) {
+        if (typeof document === "undefined")
+            return;
+        const parts = [
+            `${encodeURIComponent(name)}=${encodeURIComponent(value)}`,
+            `path=${options.path ?? "/"}`,
+        ];
+        if (options.maxAge !== undefined)
+            parts.push(`max-age=${options.maxAge}`);
+        if (options.expires)
+            parts.push(`expires=${options.expires.toUTCString()}`);
+        if (options.domain)
+            parts.push(`domain=${options.domain}`);
+        if (options.sameSite)
+            parts.push(`samesite=${options.sameSite}`);
+        if (options.secure)
+            parts.push("secure");
+        // biome-ignore lint/suspicious/noDocumentCookie: the Cookie Store API is async-only and unsupported in Safari/Firefox; `document.cookie` is the sole sync, broadly-supported write path for an SSR-safe helper.
+        document.cookie = parts.join("; ");
+    },
+    remove(name, options = {}) {
+        this.set(name, "", { ...options, maxAge: 0, expires: new Date(0) });
+    },
+};
+// ─── Clipboard & Web Share ───────────────────────────────────────────
+/** Async clipboard access. Methods return `false`/`null` when unavailable. */
+export const clipboard = {
+    /** Copy `text`. Returns whether it succeeded. */
+    async copy(text) {
+        if (typeof navigator === "undefined" || !navigator.clipboard?.writeText) {
+            return false;
+        }
+        try {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    /** Read clipboard text, or `null` if unavailable / denied. */
+    async read() {
+        if (typeof navigator === "undefined" || !navigator.clipboard?.readText) {
+            return null;
+        }
+        try {
+            return await navigator.clipboard.readText();
+        }
+        catch {
+            return null;
         }
     },
 };
+/**
+ * Invoke the native Web Share sheet. Returns `false` when unsupported or the
+ * user cancels — never throws.
+ */
+export async function share(data) {
+    if (typeof navigator === "undefined" ||
+        typeof navigator.share !== "function") {
+        return false;
+    }
+    try {
+        await navigator.share(data);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `HttpClient` — a small typed wrapper over `fetch` so call sites read
+ * `await http.get<User>("/auth/me")` instead of hand-rolling headers,
+ * `res.json()`, and status checks.
+ *
+ * - Auto JSON: a plain-object/array body is `JSON.stringify`-d with a
+ *   `Content-Type: application/json` header; a JSON response is parsed.
+ *   `FormData`/`Blob`/`URLSearchParams`/`string`/binary bodies pass through
+ *   untouched.
+ * - Bearer auth: a `token` (string or getter, read fresh per request) is sent
+ *   as `Authorization: Bearer …` unless the caller set the header themselves.
+ * - Errors: a non-2xx response rejects with an {@link HttpError} carrying the
+ *   status, the `Response`, and the parsed body.
+ *
+ * Node-free and isomorphic — uses the global `fetch` (browsers, Node 18+,
+ * Workers, Bun, Deno). Part of the client barrel.
+ */
+export interface HttpClientOptions {
+    /** Prepended to every request URL, unless the URL is already absolute. */
+    baseURL?: string;
+    /** Headers merged into every request. */
+    headers?: Record<string, string>;
+    /**
+     * Bearer token sent as `Authorization: Bearer <token>`. A getter is read
+     * fresh on each request (so a rotated/late-set token is always current);
+     * a `null`/`undefined` result omits the header.
+     */
+    token?: string | null | (() => string | null | undefined);
+    /** Default `credentials` mode (e.g. `"include"` to send cookies). */
+    credentials?: RequestCredentials;
+}
+export interface HttpRequestOptions<T = unknown> {
+    /** Query params appended to the URL. `null`/`undefined` values are skipped. */
+    query?: Record<string, string | number | boolean | null | undefined>;
+    /** Extra headers for this request (override the client defaults). */
+    headers?: Record<string, string>;
+    /** Per-request bearer token override (`null` to force-omit). */
+    token?: string | null;
+    /** Abort signal. */
+    signal?: AbortSignal;
+    /** `credentials` mode for this request. */
+    credentials?: RequestCredentials;
+    /**
+     * Runtime validator/mapper for the parsed body. When provided, the return
+     * type is whatever it returns — no unchecked cast. When omitted, the parsed
+     * body is returned as `T` (an UNCHECKED assertion of the response shape).
+     */
+    parse?: (raw: unknown) => T;
+}
+/** Thrown on a non-2xx response. Carries the status, the `Response`, and the parsed body. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly response: Response;
+    readonly data: unknown;
+    constructor(response: Response, data: unknown);
+}
+export declare class HttpClient {
+    #private;
+    constructor(options?: HttpClientOptions);
+    /** Set a default header for every subsequent request (case-insensitive replace). Chainable. */
+    setHeader(name: string, value: string): this;
+    /** Merge several default headers at once. Chainable. */
+    setHeaders(headers: Record<string, string>): this;
+    /** Remove a default header (case-insensitive). Chainable. */
+    removeHeader(name: string): this;
+    /** A copy of the current default headers. */
+    getHeaders(): Record<string, string>;
+    get<T>(url: string, options?: HttpRequestOptions<T>): Promise<T>;
+    delete<T>(url: string, options?: HttpRequestOptions<T>): Promise<T>;
+    post<T>(url: string, body?: unknown, options?: HttpRequestOptions<T>): Promise<T>;
+    put<T>(url: string, body?: unknown, options?: HttpRequestOptions<T>): Promise<T>;
+    patch<T>(url: string, body?: unknown, options?: HttpRequestOptions<T>): Promise<T>;
+    /** Send a request and return the raw `Response` (no parsing, no throw on non-2xx). */
+    raw(method: string, url: string, body?: unknown, options?: HttpRequestOptions): Promise<Response>;
+    /** Derive a new client with merged defaults (e.g. a scope that adds a token). */
+    extend(options: HttpClientOptions): HttpClient;
+}
+/** Default same-origin client. Configure your own via `new HttpClient({ … })`. */
+export declare const http: HttpClient;