@tiaforge-ui/sinter 0.0.0-stage → 0.1.0

package/dist/runtime/config.d.ts

@@ -0,0 +1,53 @@
+import { type Env } from './env.js';
+import type { Transport } from './app.js';
+export type Middleware = (request: Request, next: (request: Request) => Promise<Response>) => Promise<Response>;
+export interface Config {
+    request: Middleware[];
+    sessionProbe: string | null;
+    onError: ((error: SinterError, element: Element | null) => void) | null;
+    locale: {
+        get(): string;
+        set(locale: string): void;
+    } | null;
+    urlSchemes: string[];
+    origins: string[];
+    /** the transport for a `<sn-sync>` stream URL; `undefined` (or no function) means EventSource */
+    transport: ((url: string) => Transport | undefined) | null;
+    env: Env;
+}
+export declare const config: Config;
+export declare function configure(options: Partial<Omit<Config, 'env'>> & {
+    env?: Partial<Env>;
+}): void;
+/** `$error`: a non-2xx response, a network error (status 0) or a refused request. */
+export declare class SinterError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message: string);
+}
+/** page-load cache entries (`cache` on `<sn-resource>`), in sessionStorage */
+export declare const CACHE_PREFIX = "sn:c:";
+/** Removes the page-load cache; sinter calls it on every 401. */
+export declare function clearCached(env?: Env): void;
+/** Removes every persisted value (`sn:` keys) and the page-load cache, e.g. on logout. */
+export declare function clearPersisted(): void;
+export declare function credentials(mode: RequestCredentials): Middleware;
+/** Adds a header to same-origin requests, or to requests to `options.origin` only. */
+export declare function header(name: string, value: string, options?: {
+    origin?: string;
+}): Middleware;
+export declare function onUnauthorized(handler: (request: Request, response: Response) => Promise<Response>): Middleware;
+export interface LoginRedirectOptions {
+    to: string;
+    returnUrl?: {
+        allow: string[];
+        param?: string;
+    };
+}
+/**
+ * Stores the return URL (same-origin, allowlisted prefixes only), clears
+ * persisted state, navigates to login and never resolves.
+ */
+export declare function loginRedirect(options: LoginRedirectOptions): () => Promise<Response>;
+/** The return URL stored by loginRedirect, if it is same-origin and allowlisted; removes it. */
+export declare function takeReturnUrl(allow: string[]): string | null;

package/dist/runtime/config.js

@@ -0,0 +1,118 @@
+// App-wide configuration and the request middleware helpers. Configuration
+// comes only from configure() in JavaScript, never from the DOM.
+import { defaultEnv } from './env.js';
+export const config = {
+    request: [], sessionProbe: null, onError: null, locale: null, urlSchemes: [], origins: [], transport: null, env: defaultEnv,
+};
+export function configure(options) {
+    const { env, ...rest } = options;
+    Object.assign(config, rest);
+    if (env)
+        config.env = { ...config.env, ...env };
+}
+/** `$error`: a non-2xx response, a network error (status 0) or a refused request. */
+export class SinterError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'SinterError';
+    }
+}
+const PERSIST_PREFIX = 'sn:';
+const RETURN_KEY = 'sn:return';
+/** page-load cache entries (`cache` on `<sn-resource>`), in sessionStorage */
+export const CACHE_PREFIX = 'sn:c:';
+function removeKeys(s, prefix) {
+    if (!s)
+        return;
+    try {
+        const keys = [];
+        for (let i = 0; i < s.length; i++) {
+            const k = s.key(i);
+            if (k && k.startsWith(prefix))
+                keys.push(k);
+        }
+        for (const k of keys)
+            s.removeItem(k);
+    }
+    catch { /* storage failures are ignored */ }
+}
+/** Removes the page-load cache; sinter calls it on every 401. */
+export function clearCached(env = config.env) {
+    removeKeys(env.session(), CACHE_PREFIX);
+}
+/** Removes every persisted value (`sn:` keys) and the page-load cache, e.g. on logout. */
+export function clearPersisted() {
+    removeKeys(config.env.storage(), PERSIST_PREFIX);
+    clearCached();
+}
+// ---- middleware
+export function credentials(mode) {
+    return (req, next) => next(new Request(req, { credentials: mode }));
+}
+/** Adds a header to same-origin requests, or to requests to `options.origin` only. */
+export function header(name, value, options = {}) {
+    return (req, next) => {
+        const target = new URL(req.url).origin;
+        const allowed = options.origin ? target === new URL(options.origin).origin : target === new URL(config.env.href()).origin;
+        if (!allowed)
+            return next(req);
+        const headers = new Headers(req.headers);
+        headers.set(name, value);
+        return next(new Request(req, { headers }));
+    };
+}
+export function onUnauthorized(handler) {
+    return async (req, next) => {
+        const res = await next(req);
+        return res.status === 401 ? handler(req, res) : res;
+    };
+}
+/**
+ * Stores the return URL (same-origin, allowlisted prefixes only), clears
+ * persisted state, navigates to login and never resolves.
+ */
+export function loginRedirect(options) {
+    return () => {
+        const env = config.env;
+        const here = new URL(env.href());
+        const path = here.pathname + here.search + here.hash;
+        let target = options.to;
+        if (options.returnUrl && options.returnUrl.allow.some((p) => here.pathname.startsWith(p))) {
+            try {
+                env.session()?.setItem(RETURN_KEY, path);
+            }
+            catch { /* ignored */ }
+            if (options.returnUrl.param) {
+                const u = new URL(options.to, here);
+                u.searchParams.set(options.returnUrl.param, path);
+                target = u.origin === here.origin ? u.pathname + u.search + u.hash : options.to;
+            }
+        }
+        clearPersisted();
+        env.navigate(target);
+        return new Promise(() => { });
+    };
+}
+/** The return URL stored by loginRedirect, if it is same-origin and allowlisted; removes it. */
+export function takeReturnUrl(allow) {
+    const env = config.env;
+    let v = null;
+    try {
+        const s = env.session();
+        v = s?.getItem(RETURN_KEY) ?? null;
+        s?.removeItem(RETURN_KEY);
+    }
+    catch {
+        return null;
+    }
+    if (!v || !v.startsWith('/') || v.startsWith('//'))
+        return null;
+    const u = new URL(v, env.href());
+    if (u.origin !== new URL(env.href()).origin)
+        return null;
+    return allow.some((p) => u.pathname.startsWith(p)) ? u.pathname + u.search + u.hash : null;
+}

package/dist/runtime/env.d.ts

@@ -0,0 +1,18 @@
+export interface Env {
+    now(): number;
+    setTimeout(fn: () => void, ms: number, kind?: 'debounce' | 'timeout' | 'backoff' | 'clock'): unknown;
+    clearTimeout(handle: unknown): void;
+    queueMicrotask(fn: () => void): void;
+    /** the only way sinter navigates */
+    navigate(url: string): void;
+    fetch(request: Request): Promise<Response>;
+    storage(): Storage | null;
+    session(): Storage | null;
+    /** current location (href) */
+    href(): string;
+    replaceState(url: string): void;
+    random(): number;
+    /** add a window-level listener (pagehide, pageshow, popstate); returns the remover */
+    listen(type: string, fn: (e: Event) => void): () => void;
+}
+export declare const defaultEnv: Env;

package/dist/runtime/env.js

@@ -0,0 +1,23 @@
+// Everything sinter needs from the outside world, in one injectable object, so
+// the testing module can drive time, scheduling, navigation and fetch exactly.
+const g = globalThis;
+const tryGet = (f) => { try {
+    return f();
+}
+catch {
+    return null;
+} };
+export const defaultEnv = {
+    now: Date.now,
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (h) => clearTimeout(h),
+    queueMicrotask: (fn) => queueMicrotask(fn),
+    navigate: (url) => g.location.assign(url),
+    fetch: (req) => fetch(req),
+    storage: () => tryGet(() => g.localStorage),
+    session: () => tryGet(() => g.sessionStorage),
+    href: () => g.location.href,
+    replaceState: (url) => g.history.replaceState(g.history.state, '', url),
+    random: Math.random,
+    listen: (type, fn) => (g.addEventListener(type, fn), () => g.removeEventListener(type, fn)),
+};

package/dist/runtime/helpers.d.ts

@@ -0,0 +1,9 @@
+type Style = 'full' | 'long' | 'medium' | 'short';
+export declare function date(v: unknown, style?: Style): string;
+export declare function time(v: unknown, style?: Style): string;
+export declare function datetime(v: unknown, style?: Style): string;
+/** "3 days ago", relative to `now` (default: the current time). */
+export declare function relative(v: unknown, now?: unknown): string;
+export declare function number(v: unknown, opts?: Intl.NumberFormatOptions): string;
+export declare function bytes(v: unknown): string;
+export {};

package/dist/runtime/helpers.js

@@ -0,0 +1,55 @@
+// Built-in helpers. Each reads the current locale, so bindings that call them
+// re-run when `$locale` changes.
+import { config } from './config.js';
+const locale = () => config.locale?.get();
+const toDate = (v) => {
+    if (v == null || v === '')
+        return null;
+    const d = v instanceof Date ? v : new Date(v);
+    return Number.isNaN(d.getTime()) ? null : d;
+};
+export function date(v, style = 'medium') {
+    const d = toDate(v);
+    return d ? new Intl.DateTimeFormat(locale(), { dateStyle: style }).format(d) : '';
+}
+export function time(v, style = 'short') {
+    const d = toDate(v);
+    return d ? new Intl.DateTimeFormat(locale(), { timeStyle: style }).format(d) : '';
+}
+export function datetime(v, style = 'medium') {
+    const d = toDate(v);
+    return d ? new Intl.DateTimeFormat(locale(), { dateStyle: style, timeStyle: 'short' }).format(d) : '';
+}
+const UNITS = [
+    ['year', 31536000], ['month', 2592000], ['week', 604800], ['day', 86400], ['hour', 3600], ['minute', 60], ['second', 1],
+];
+/** "3 days ago", relative to `now` (default: the current time). */
+export function relative(v, now = Date.now()) {
+    const d = toDate(v), n = toDate(now);
+    if (!d || !n)
+        return '';
+    const diff = (d.getTime() - n.getTime()) / 1000;
+    const fmt = new Intl.RelativeTimeFormat(locale(), { numeric: 'auto' });
+    for (const [unit, secs] of UNITS) {
+        if (Math.abs(diff) >= secs || unit === 'second')
+            return fmt.format(Math.round(diff / secs), unit);
+    }
+    return '';
+}
+export function number(v, opts) {
+    if (v == null || v === '' || Number.isNaN(Number(v)))
+        return '';
+    return new Intl.NumberFormat(locale(), opts).format(Number(v));
+}
+const BYTE_UNITS = ['byte', 'kilobyte', 'megabyte', 'gigabyte', 'terabyte'];
+export function bytes(v) {
+    let n = Number(v);
+    if (v == null || Number.isNaN(n))
+        return '';
+    let i = 0;
+    while (Math.abs(n) >= 1024 && i < BYTE_UNITS.length - 1) {
+        n /= 1024;
+        i++;
+    }
+    return new Intl.NumberFormat(locale(), { style: 'unit', unit: BYTE_UNITS[i], unitDisplay: 'short', maximumFractionDigits: i ? 1 : 0 }).format(n);
+}

package/dist/runtime/request.d.ts

@@ -0,0 +1,23 @@
+import { SinterError, type Middleware } from './config.js';
+import type { Env } from './env.js';
+export declare const TIMEOUT = 30000;
+export interface SendInit {
+    method?: string;
+    /** JSON-serialized unless FormData */
+    body?: unknown;
+    headers?: Record<string, string>;
+    signal?: AbortSignal | undefined;
+}
+export interface RequestLayer {
+    /** Sends a request and returns the parsed body; rejects with SinterError. */
+    send(url: string, init?: SendInit): Promise<unknown>;
+    /** Sends a request and returns the raw response; network errors reject with SinterError(0). */
+    raw(url: string, init?: SendInit): Promise<Response>;
+    /** Requests in flight. */
+    readonly inflight: number;
+}
+export declare const isAbort: (e: unknown) => boolean;
+export declare const toError: (e: unknown) => SinterError;
+export declare function createRequestLayer(env: Env, chain: Middleware[]): RequestLayer;
+/** 204 or empty → null; JSON content type → parsed; anything else → text. */
+export declare function parseBody(res: Response): Promise<unknown>;

package/dist/runtime/request.js

@@ -0,0 +1,93 @@
+// The request layer: every request (resources, actions, the session probe,
+// islands) goes through one middleware chain, then fetch with a timeout and
+// one retry for idempotent requests on network errors.
+import { clearCached, config, SinterError } from './config.js';
+export const TIMEOUT = 30_000;
+export const isAbort = (e) => e?.name == 'AbortError';
+export const toError = (e) => (e instanceof SinterError ? e : new SinterError(0, null, e?.message || 'network error'));
+export function createRequestLayer(env, chain) {
+    let inflight = 0;
+    const terminal = async (req) => {
+        const signal = req.signal, idempotent = /^(GET|HEAD|OPTIONS|PUT|DELETE)$/.test(req.method);
+        for (let retried = 0;; retried++) {
+            const c = new AbortController(), abort = () => c.abort(signal.reason);
+            signal.aborted ? abort() : signal.addEventListener('abort', abort);
+            const timer = env.setTimeout(() => c.abort(), TIMEOUT, 'timeout');
+            try {
+                const res = await env.fetch(new Request(idempotent ? req.clone() : req, { signal: c.signal }));
+                // the session is gone: cached data must not outlive it, whatever the app does next
+                if (res.status == 401)
+                    clearCached(env);
+                return res;
+            }
+            catch (e) {
+                if (signal.aborted)
+                    throw signal.reason ?? e;
+                if (c.signal.aborted)
+                    throw new SinterError(0, null, 'request timed out');
+                if (!idempotent || retried || isAbort(e))
+                    throw toError(e);
+            }
+            finally {
+                env.clearTimeout(timer);
+                signal.removeEventListener('abort', abort);
+            }
+        }
+    };
+    const run = chain.reduceRight((next, mw) => (r) => mw(r, next), terminal);
+    async function raw(url, init = {}) {
+        const target = new URL(url, env.href());
+        if (target.origin != new URL(env.href()).origin && !config.origins.some((o) => new URL(o).origin == target.origin)) {
+            throw new SinterError(0, null, `request to ${target.origin} refused: origin not allowed`);
+        }
+        const method = (init.method ?? 'GET').toUpperCase(), headers = new Headers(init.headers);
+        let body = init.body;
+        if (body == null || method == 'GET')
+            body = undefined;
+        else if (!(body instanceof FormData)) {
+            body = JSON.stringify(body);
+            headers.set('Content-Type', 'application/json');
+        }
+        headers.has('Accept') || headers.set('Accept', 'application/json');
+        // mutations outlive the page: a navigation right after a click must not cancel the write
+        // (keepalive bodies are limited to 64 KB; larger ones and uploads go without it)
+        const keepalive = method != 'GET' && method != 'HEAD' && (body == null || (typeof body == 'string' && body.length < 60_000));
+        inflight++;
+        try {
+            const res = await run(new Request(target, { method, headers, body: body ?? null, credentials: 'same-origin', signal: init.signal ?? null, keepalive }));
+            // also a 401 that middleware answered itself (fetch above clears before onUnauthorized runs)
+            if (res.status == 401)
+                clearCached(env);
+            return res;
+        }
+        catch (e) {
+            throw isAbort(e) ? e : toError(e);
+        }
+        finally {
+            inflight--;
+        }
+    }
+    async function send(url, init) {
+        const res = await raw(url, init), body = await parseBody(res);
+        if (!res.ok) {
+            const b = body, m = typeof body == 'string' ? body.length < 200 && body.trim() : b?.message ?? b?.error;
+            throw new SinterError(res.status, body, typeof m == 'string' && m ? m : `${res.status} ${res.statusText}`.trim());
+        }
+        return body;
+    }
+    return { send, raw, get inflight() { return inflight; } };
+}
+/** 204 or empty → null; JSON content type → parsed; anything else → text. */
+export async function parseBody(res) {
+    const text = res.status == 204 ? '' : await res.text();
+    if (!text)
+        return null;
+    if (!/[/+]json\b/i.test(res.headers.get('Content-Type') ?? ''))
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new SinterError(res.status, text, 'invalid JSON');
+    }
+}

package/dist/runtime/security.d.ts

@@ -0,0 +1,12 @@
+/** Keys that could reach prototypes; dropped from input and refused in computed access. */
+export declare const BAD_KEY: RegExp;
+/** Guard for computed member access in expressions: `obj[k]` compiles to `obj[$k(k)]`. */
+export declare const $k: <K>(key: K) => K;
+/** Allowed schemes: http(s), mailto, tel and configured extras; javascript:, vbscript: and data: never. */
+export declare const schemesOf: (extra: string[]) => Set<string>;
+/** Whether `value` may be written to attribute `name` of `el`; parsed by the browser's own URL parser. */
+export declare function urlAllowed(el: Element, name: string, value: string, base: string, schemes: Set<string>): boolean;
+/** Style values that could load URLs. */
+export declare const STYLE_BAD: RegExp;
+/** Encodes one interpolated URL value. */
+export declare const encodeSegment: (v: unknown) => string;

package/dist/runtime/security.js

@@ -0,0 +1,34 @@
+// Runtime checks for the DOM sinks that cannot be closed at build time.
+/** Keys that could reach prototypes; dropped from input and refused in computed access. */
+export const BAD_KEY = /^(constructor|__proto__|prototype)$/;
+/** Guard for computed member access in expressions: `obj[k]` compiles to `obj[$k(k)]`. */
+export const $k = (key) => {
+    if (BAD_KEY.test(key))
+        throw TypeError(`sinter: [${String(key)}] is not allowed`);
+    return key;
+};
+const URL_ATTR = /^(href|src|action|formaction|poster|cite|data|ping|xlink:href)$/;
+/** Allowed schemes: http(s), mailto, tel and configured extras; javascript:, vbscript: and data: never. */
+export const schemesOf = (extra) => new Set(['http:', 'https:', 'mailto:', 'tel:', ...extra
+        .map((s) => s.toLowerCase().replace(/:?$/, ':'))
+        .filter((s) => !/^(javascript|vbscript|data):$/.test(s))]);
+/** Whether `value` may be written to attribute `name` of `el`; parsed by the browser's own URL parser. */
+export function urlAllowed(el, name, value, base, schemes) {
+    const ok = (v, attr) => {
+        try {
+            const p = new URL(v, base).protocol;
+            return schemes.has(p) || (/^(data|blob):$/.test(p) && attr == 'src' && /^(img|video|audio|source)$/.test(el.localName));
+        }
+        catch {
+            return false;
+        }
+    };
+    name = name.toLowerCase();
+    if (name.endsWith('srcset'))
+        return value.split(',').every((c) => ok(c.trim().split(/\s+/)[0], 'src'));
+    return !URL_ATTR.test(name) || ok(value, name);
+}
+/** Style values that could load URLs. */
+export const STYLE_BAD = /url\(|image(-set)?\(|\\/i;
+/** Encodes one interpolated URL value. */
+export const encodeSegment = (v) => encodeURIComponent(String(v ?? '')).replace(/^\.\.?$/, (d) => d.replace(/\./g, '%2E'));

package/dist/runtime/store.d.ts

@@ -0,0 +1,95 @@
+export type Change<T = any> = {
+    resource: string;
+    op: 'upsert';
+    item: T;
+} | {
+    resource: string;
+    op: 'patch';
+    key: string;
+    fields: Partial<T>;
+} | {
+    resource: string;
+    op: 'remove';
+    key: string;
+} | {
+    resource: string;
+    op: 'refetch';
+};
+export type Op = {
+    op: 'upsert';
+    item: any;
+} | {
+    op: 'patch';
+    key: string;
+    fields: any;
+} | {
+    op: 'remove';
+    key: string;
+};
+export interface Meta {
+    loading: boolean;
+    error: {
+        status: number;
+        body: unknown;
+        message: string;
+    } | null;
+    loadedAt: number | null;
+    pending: number;
+    total: number | null;
+    page?: number;
+    pages?: number | null;
+    from?: number | null;
+    to?: number | null;
+    hasPrev?: boolean;
+    hasNext?: boolean;
+}
+export interface ResourceOptions {
+    key: string[] | null;
+    order: string | null;
+    locale?: () => string | undefined;
+    warn?: (code: number, ...args: unknown[]) => void;
+    /** applied to every stored item (dev builds freeze them) */
+    prep?: <T>(item: T) => T;
+}
+/** The public store handle (`app.resource(name)`), plus the hooks loaders and features use. */
+export interface Resource<T extends object = any> {
+    readonly name: string;
+    readonly meta: Meta;
+    readonly key: string[] | null;
+    readonly isCollection: boolean;
+    get(key: string | T): T | undefined;
+    has(key: string | T): boolean;
+    all(): readonly T[];
+    /** what expressions see: the ordered array, or the single object (null when absent) */
+    value(): readonly T[] | T | null;
+    replace(items: T[] | T | null): void;
+    upsert(item: T): void;
+    patch(key: string | T, fields: Partial<T>): void;
+    remove(key: string | T): void;
+    refetch(): Promise<void>;
+    subscribe(fn: (change: Change<T>) => void): () => void;
+    keyOf(item: string | T): string;
+    /**
+     * Loads in flight: writes made while a load runs are replayed on top of its response,
+     * so a stale response cannot undo them. `startLoad` returns a mark for `endLoad`.
+     */
+    startLoad(): number;
+    endLoad(mark: number, loaded: boolean): void;
+    addLayer(ops: Op[]): number;
+    dropLayer(id: number): void;
+    setTotal(total: number | null): void;
+    /** what the server last confirmed, without optimistic layers (in arrival order) */
+    base(): {
+        items: T[] | T | null;
+        total: number | null;
+    };
+    /** while set, upsert/patch/remove are recorded instead of applied */
+    recording: Op[] | null;
+    loader: {
+        refetch(): Promise<void>;
+    } | null;
+    onDirty(what: 'data' | 'meta'): void;
+}
+/** Copies own enumerable fields, dropping keys that could pollute prototypes. */
+export declare function clean<T>(obj: T): T;
+export declare function createResource<T extends object = any>(name: string, o: ResourceOptions): Resource<T>;