@happyvertical/smrt-ui 0.51.39 → 0.53.0

package/dist/components/forms/form-retry/content-digest.js

@@ -0,0 +1,169 @@
+/**
+ * The `runOnce()` content digest, computed in the browser (#3291).
+ *
+ * `runOnce()` (`@happyvertical/smrt-core`, `src/run-once.ts`) digests the
+ * submitted content itself on the server, so pairing a form with it does NOT
+ * need this function: send the submission key, pass the action's `FormData`
+ * as `content`, and the server derives the claim. This exists for the cases
+ * where the browser needs the SAME digest the server will compute — to tell a
+ * person whether the retry they are about to send is byte-identical to the
+ * submit that may already be recorded, to key a client-side record of an
+ * attempt, or to log a correlatable identity without logging the content.
+ *
+ * It is a byte-for-byte port of core's `digestRunOnceContent()`, using Web
+ * Crypto (`crypto.subtle`) instead of `node:crypto`; shared test vectors in
+ * both packages hold the two together. The algorithm:
+ *
+ * - Content is normalized once, following JSON serialization exactly:
+ *   `toJSON(key)` is called with the property name or array index (a `Date`
+ *   digests as its ISO string), and `undefined`, function and symbol values
+ *   are omitted from objects and written as `null` in arrays.
+ * - A `FormData` digests as its ORDERED entry list — repeated fields and their
+ *   order are significant — because JSON would reduce every form to `{}` and
+ *   collapse distinct submissions (#3136). A `File`/`Blob` entry digests by
+ *   `{ name, size, type }`, never its bytes: re-choosing the same file after a
+ *   reload reproduces the digest, and a different file of the same name, size
+ *   and type does too.
+ * - Content containing a `FormData` is hashed in a separate domain (the input
+ *   is prefixed with a byte sorted-key JSON never starts with, and user keys
+ *   starting with NUL are escaped), so no plain object can forge it.
+ * - `Map`, `Set`, `RegExp`, any other non-plain object without `toJSON()`, and
+ *   `bigint` are rejected with a `TypeError` rather than hashed as `{}`.
+ * - The digest is the lowercase hex sha256 of the sorted-key JSON encoding.
+ *
+ * `crypto.subtle` exists only in secure contexts (HTTPS, `localhost`); the
+ * function rejects with a clear error elsewhere.
+ *
+ * @module
+ */
+const FORM_DATA_TAG = '\u0000FormData';
+const FORM_DATA_DOMAIN = '\u0001run-once-formdata-v1\n';
+class NormalizedFormData {
+    entries;
+    constructor(entries) {
+        this.entries = entries;
+    }
+}
+const OMIT = Symbol('form-retry-digest-omit');
+function normalize(input, state, key) {
+    let value = input;
+    if (value !== null &&
+        (typeof value === 'object' || typeof value === 'bigint') &&
+        typeof value.toJSON === 'function') {
+        value = value.toJSON(key);
+    }
+    if (value === null)
+        return null;
+    switch (typeof value) {
+        case 'undefined':
+        case 'function':
+        case 'symbol':
+            return OMIT;
+        case 'string':
+        case 'boolean':
+            return value;
+        case 'number':
+            return Number.isFinite(value) ? value : null;
+        case 'bigint':
+            throw new TypeError('submission content cannot contain a bigint; pass plain JSON data');
+    }
+    if (typeof FormData !== 'undefined' && value instanceof FormData) {
+        state.sawFormData = true;
+        const entries = [];
+        value.forEach((entry, name) => {
+            entries.push([name, normalize(entry, state, name)]);
+        });
+        return new NormalizedFormData(entries);
+    }
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+        return {
+            name: value.name ?? null,
+            size: value.size,
+            type: value.type,
+        };
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => {
+            const normalized = normalize(item, state, String(index));
+            return normalized === OMIT ? null : normalized;
+        });
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        const name = value.constructor?.name ||
+            'non-plain object';
+        throw new TypeError(`submission content cannot contain a ${name}; convert it to plain JSON data`);
+    }
+    const result = Object.create(null);
+    for (const [member, memberValue] of Object.entries(value)) {
+        const normalized = normalize(memberValue, state, member);
+        if (normalized !== OMIT)
+            result[member] = normalized;
+    }
+    return result;
+}
+function toFormDataDomain(value) {
+    if (value instanceof NormalizedFormData) {
+        return {
+            [FORM_DATA_TAG]: value.entries.map(([key, entry]) => [
+                key,
+                toFormDataDomain(entry),
+            ]),
+        };
+    }
+    if (Array.isArray(value))
+        return value.map(toFormDataDomain);
+    if (value !== null && typeof value === 'object') {
+        const result = Object.create(null);
+        for (const [key, member] of Object.entries(value)) {
+            result[key.startsWith('\u0000') ? `\u0000${key}` : key] =
+                toFormDataDomain(member);
+        }
+        return result;
+    }
+    return value;
+}
+/** Sorted-key JSON, identical to `@happyvertical/smrt-scanner`'s `stableStringify`. */
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (value && typeof value === 'object') {
+        const sorted = Object.create(null);
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortValue(value[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * The exact string `runOnce()` hashes for `content`.
+ * @throws {TypeError} when `content` contains a value with no faithful JSON form.
+ * @internal
+ */
+export function submissionDigestInput(content) {
+    const state = { sawFormData: false };
+    const captured = normalize(content, state, '');
+    const normalized = captured === OMIT ? null : captured;
+    return state.sawFormData
+        ? FORM_DATA_DOMAIN + JSON.stringify(sortValue(toFormDataDomain(normalized)))
+        : JSON.stringify(sortValue(normalized));
+}
+/**
+ * The content digest `runOnce()` will compute on the server for `content`:
+ * lowercase hex sha256. See the module doc for what is and is not digested
+ * (a `File` by name, size and type — never its bytes).
+ *
+ * @throws {TypeError} (as a rejection) when `content` has no faithful JSON
+ *   form, or when Web Crypto is unavailable (not a secure context).
+ */
+export async function digestSubmissionContent(content) {
+    const input = submissionDigestInput(content);
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new TypeError('digestSubmissionContent needs Web Crypto (crypto.subtle), which browsers expose only in secure contexts (HTTPS or localhost)');
+    }
+    const bytes = new TextEncoder().encode(input);
+    const hash = await subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}

package/dist/components/forms/form-retry/controller.d.ts

@@ -0,0 +1,214 @@
+/**
+ * `createFormRetry()`: the browser half of `runOnce()` for a SvelteKit
+ * enhanced form (#3291).
+ *
+ * One controller per form. It owns the submission key (`submission-key.ts`),
+ * the conditional reset (`form-draft.ts`) and, when asked, the
+ * restore-after-reload draft (`submitted-draft.ts`), and exposes them as:
+ *
+ * - `enhance(submit?)` — a submit function in SvelteKit's `SubmitFunction`
+ *   shape, for `<form method="POST" use:enhance={retry.enhance()}>`;
+ * - `attach` / `action` — an attachment (`{@attach retry.attach}`) or action
+ *   (`use:retry.action`) that keeps a hidden key field in the form and puts a
+ *   restored draft back into its controls;
+ * - `subscribe` — the Svelte store contract, so `$retry.status` and
+ *   `$retry.token` are reactive in a component without this module importing
+ *   Svelte.
+ *
+ * It is framework-free TypeScript: no `@sveltejs/kit` and no `svelte` import.
+ *
+ * ## What happens to one submit
+ *
+ * 1. A file the restored draft says was chosen, but is not chosen now, refuses
+ *    the submit (`status: 'files-required'`) — a native file input cannot be
+ *    restored, and sending without it would silently be different content.
+ * 2. A submit while another is unresolved is refused (`status: 'busy'`) and
+ *    nothing is sent; the form keeps what the person typed.
+ * 3. Otherwise the key is written into the outgoing `FormData` (so the body is
+ *    right even if a hidden field is stale or missing) and what the person can
+ *    see is snapshotted — before the page's own submit function runs, because
+ *    kit built the body before calling it. With restore enabled, the submitted
+ *    values are then kept beside the key.
+ * 4. The result settles the slot:
+ *    - `error` (transport failure, lost response, thrown server error): the key,
+ *      the form and the draft are all kept, and `update()` is NOT called —
+ *      `enhance`'s default would apply the error and can unmount the form. The
+ *      unchanged re-submit is the same claim.
+ *    - `failure` (validation): applied without rotating; the draft is dropped
+ *      because nothing was recorded.
+ *    - `success`: the draft is dropped; the form is reset — and the key
+ *      rotated — only if the fields are unchanged since the submit. A person who
+ *      typed the next entry while the first was in flight keeps it, under the
+ *      same key, and sending it is a different claim because its content
+ *      differs. With the page's own result callback, the key rotates only if
+ *      the form is actually reset while that callback runs.
+ *    - `redirect`: a confirmed write only with `redirectConfirmsWrite: true`.
+ *    - A late result for a submit already settled is ignored entirely.
+ *
+ * An aborted request (the page called `controller.abort()`, before or during
+ * the request — including from its own submit function) produces no result
+ * from `enhance`; it settles like a transport error so the form is not stuck
+ * refusing submits.
+ *
+ * @module
+ */
+import { type FormRetryStorage } from './submission-key.js';
+import { type SubmittedDraft } from './submitted-draft.js';
+import type { FormRetrySubmitFunction } from './types.js';
+/** Where the controller is in a submit's life. */
+export type FormRetryStatus = 
+/** Nothing submitted yet, or a submit was cancelled by the page. */
+'idle'
+/** A submit is in flight. */
+ | 'submitting'
+/** A second submit was refused while one is in flight; nothing was sent. */
+ | 'busy'
+/** A restored draft had files that are not chosen again; nothing was sent. */
+ | 'files-required'
+/** The last submit got no result; send it again unchanged. */
+ | 'transport-error'
+/** The last submit failed validation; nothing was written. */
+ | 'failure'
+/** The last submit was confirmed written. */
+ | 'success'
+/** The last submit redirected without `redirectConfirmsWrite`. */
+ | 'redirect';
+/** A snapshot of the controller, as `subscribe` delivers it. */
+export interface FormRetryState {
+    /** The key the next submit carries. */
+    token: string;
+    /** The key of the unresolved submit, or `null` when idle. */
+    inFlight: string | null;
+    /** Where the controller is in a submit's life. */
+    status: FormRetryStatus;
+    /** A submitted draft from before a reload was restored into this form. */
+    restored: boolean;
+    /**
+     * File fields whose file must be chosen again before a submit is allowed:
+     * the restored draft says a file was sent, and a file input cannot be
+     * restored. Empty when nothing is outstanding.
+     */
+    filesToReselect: readonly string[];
+    /**
+     * Whether the key lives in the tab's storage and survives a reload. `false`
+     * in a private window or webview that refuses storage: the key then lives in
+     * memory for the life of the page.
+     */
+    persistent: boolean;
+}
+/** Non-field state to keep beside the submitted values (opt-in restore). */
+export interface FormRetryValuesHook<T = unknown> {
+    /**
+     * What to keep for this submit — values the page holds outside form fields
+     * (an uploaded asset's id, a signature capture key, a selection). Must be
+     * JSON-serializable: a result that is not keeps no draft for that submit
+     * and drops an earlier attempt's. Called after the submit is accepted.
+     */
+    capture: (formData: FormData) => T;
+    /**
+     * Put a kept value back after a reload. `value` came from storage: validate
+     * it before trusting it, and throw to reject it — the whole draft is then
+     * discarded. Called synchronously inside `createFormRetry()`.
+     */
+    restore: (value: unknown) => void;
+}
+/** Opt-in restore-after-reload. */
+export interface FormRetryRestoreOptions {
+    /**
+     * A stable id for whoever is signed in (e.g. `tenantId:userId`). A draft is
+     * restored only for the owner it was saved by, and never for an empty owner,
+     * so one person's draft is never offered to the next on shared hardware.
+     */
+    owner: string;
+    /** Oldest draft that may be restored, in ms. Default one day. */
+    maxAgeMs?: number;
+    /** A stricter freshness rule (e.g. "same business day"); overrides `maxAgeMs`. */
+    fresh?: (savedAt: Date, now: Date) => boolean;
+    /** Non-field state to keep and restore. */
+    values?: FormRetryValuesHook;
+    /** Fields never written to storage (password inputs are always skipped). */
+    exclude?: readonly string[];
+    /**
+     * Exact storage name for the draft, overriding the derived
+     * `smrt:form-retry:<form>[:<scope>]:draft`.
+     */
+    storageKey?: string;
+}
+/** Options for {@link createFormRetry}. */
+export interface FormRetryOptions {
+    /** The form's slot. One slot per FORM: two forms on a page need two names. */
+    form: string;
+    /** One key per record when a form is rendered once per row. */
+    scope?: string;
+    /** Hidden field that carries the key. Default `submissionKey`. */
+    fieldName?: string;
+    /**
+     * Fields whose change after a submit is not an edit, left out of the
+     * "unchanged since submit" check that decides the success reset — e.g. a
+     * hidden nonce the page rewrites. Every other control counts, hidden inputs
+     * included (choice controls post through them); the key field is always
+     * left out. Not a storage rule: use `restore.exclude` for that.
+     */
+    ignoreFields?: readonly string[];
+    /** Backing store. Default `sessionStorage`; `null` keeps everything in memory. */
+    storage?: FormRetryStorage | null;
+    /** Exact storage name for the key (migration from an older name). */
+    storageKey?: string;
+    /** Mints a key. Default: a random UUID v4. */
+    mint?: () => string;
+    /**
+     * Treat a `redirect` result as a confirmed write (rotate the key, drop the
+     * draft). Default `false`: a redirect cannot vouch for a write on its own.
+     */
+    redirectConfirmsWrite?: boolean;
+    /** Opt-in restore-after-reload. */
+    restore?: FormRetryRestoreOptions;
+    /** Clock seam for draft timestamps and freshness. */
+    now?: () => Date;
+}
+/** A form's retry controller. */
+export interface FormRetry {
+    /** The key the next submit carries. */
+    readonly token: string;
+    /** The hidden field name that carries the key. */
+    readonly fieldName: string;
+    /** The current state. */
+    readonly state: FormRetryState;
+    /** The draft restored after a reload, or `null`. */
+    readonly restored: SubmittedDraft | null;
+    /** Svelte store contract: called now and on every change; returns unsubscribe. */
+    subscribe(listener: (state: FormRetryState) => void): () => void;
+    /**
+     * A submit function for `use:enhance`. An optional inner submit function runs
+     * after the retry gate (it sees the key in `formData` and may still
+     * `cancel()`); its returned callback, if any, replaces the default
+     * `update({ reset })` for applied results and receives an `update` whose
+     * default `reset` is the safe one. On a success it also decides whether the
+     * key retires: only a reset of the form while it runs (through `update()` or
+     * `form.reset()`) rotates the key, so values it keeps on screen keep their
+     * key. Transport errors and stale results never reach it — observe `status`
+     * instead.
+     */
+    enhance(submit?: FormRetrySubmitFunction): FormRetrySubmitFunction;
+    /** Attachment: `{@attach retry.attach}`. Returns its cleanup. */
+    attach: (form: HTMLFormElement) => () => void;
+    /** Action: `use:retry.action`. */
+    action: (form: HTMLFormElement) => {
+        destroy(): void;
+    };
+    /**
+     * Abandon this fill: drop the stored draft and rotate the key, so the next
+     * submit is a new submission. For a "start over" control.
+     *
+     * Refused while a submit is in flight: that request may already have
+     * written, and if its response is lost the unchanged resend must still
+     * carry its key (and a reload must still find its draft). Returns `false`
+     * and changes nothing then; disable the control while
+     * `$retry.inFlight` is set, or call it again once the submit settles.
+     * Returns `true` when the fill was discarded.
+     */
+    discard(): boolean;
+}
+/** Create the retry controller for one form. */
+export declare function createFormRetry(options: FormRetryOptions): FormRetry;
+//# sourceMappingURL=controller.d.ts.map

package/dist/components/forms/form-retry/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../../../src/components/forms/form-retry/controller.ts"],"names":[],"mappings":"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"}