@cosmicdrift/kumiko-headless 0.327.0 → 0.328.1

package/dist/dispatcher/types.js

@@ -0,0 +1,34 @@
+// Dispatcher Contract — the interface every client-side Dispatcher implements.
+// Two implementations ship with Kumiko:
+//
+//   - dispatcher-live: HTTP-only, always online. Writes go straight to
+//     /api/write or /api/batch; a failed network call is a failed write.
+//     Used on the web by default and on mobile when the app is "cockpit"-
+//     style (admin dashboards, back-office UIs).
+//
+//   - dispatcher-savable: Local-first with an outbound queue. Writes land
+//     in a local store, the queue syncs when the network is back. Used on
+//     mobile and for PWA-style web apps.
+//
+// The UI code never reaches for either implementation directly — it takes
+// a `Dispatcher` through a provider/context and calls `write` / `query` /
+// `batch`. A feature-module can therefore be rendered identically on a
+// live-online admin screen and on a mobile app that edits offline; the
+// dispatcher choice is an app-level concern, not a feature-level one.
+//
+// Result shape: `{ isSuccess: true, data } | { isSuccess: false, error }`.
+// Pattern matches the server's WriteResult but does not import it — this
+// package stays free of @cosmicdrift/kumiko-framework so it runs in any JS runtime
+// (browser, Expo/React Native, Web Worker). The HTTP dispatcher adapts
+// the server response to this shape; the savable dispatcher synthesizes
+// it from its own state machine. The shape is the boundary, not the
+// internal detail.
+// SSE frame event names for POST /api/stream — shared across the server route,
+// the live-dispatcher wire parser, and their tests so a typo on one side
+// fails the type-checker instead of the integration test.
+export const StreamFrame = {
+    chunk: "chunk",
+    ping: "ping",
+    done: "done",
+    error: "error",
+};

package/dist/form/form-controller.d.ts

@@ -0,0 +1,2 @@
+import type { FormController, FormControllerOptions, FormValues } from "./types.js";
+export declare function createFormController<TValues extends FormValues, TCtx = unknown>(options: FormControllerOptions<TValues, TCtx>): FormController<TValues>;

package/dist/form/form-controller.js

@@ -0,0 +1,404 @@
+import { createStore } from "../store/index.js";
+import { groupIssuesByPath, zodErrorToFieldIssues } from "./zod-bridge.js";
+// Paths without the prefix (hook-level errors, "(root)") pass through unchanged.
+function stripServerFieldPathPrefix(issues, prefix) {
+    return issues.map((issue) => issue.path.startsWith(prefix) ? { ...issue, path: issue.path.slice(prefix.length) } : issue);
+}
+// Resolve one condition-value (boolean | predicate) against current values + ctx.
+// `undefined` means "condition not declared"; the caller substitutes the
+// field-default (visible:true, readonly:false, required:false).
+function evalCondition(condition, fallback, values, ctx) {
+    if (condition === undefined)
+        return fallback;
+    if (typeof condition === "boolean")
+        return condition;
+    return condition(values, ctx);
+}
+function computeFieldStates(rules, values, ctx) {
+    if (!rules)
+        return {};
+    const out = {};
+    for (const [fieldKey, rule] of Object.entries(rules)) {
+        out[fieldKey] = {
+            visible: evalCondition(rule.visible, true, values, ctx),
+            readonly: evalCondition(rule.readonly, false, values, ctx),
+            required: evalCondition(rule.required, false, values, ctx),
+        };
+    }
+    return out;
+}
+// Reference equality only. For primitive-valued fields this is exact; for
+// object/array fields it treats "same reference" as "unchanged" — callers
+// who mutate in place instead of swapping references (which is bad form
+// anyway, but common in ad-hoc tests) would miss a change. Kumiko's
+// form-controller contract is that mutators build new references.
+// Object.is is chosen over === so NaN !== NaN doesn't mark a field dirty
+// after you re-type the same number back in.
+function valuesDiff(current, initial) {
+    const out = {};
+    // Iterate over BOTH sides — a field that existed on initial but was
+    // deleted from current (via `setValues({ foo: undefined })`) still
+    // counts as a change.
+    // FormValues<T> erlaubt kein keyof-T-Iteration (T ist generic). Cast
+    // zu Record<string, unknown> für dynamic-key-Inspection.
+    const cur = current; // @cast-boundary form-values
+    const ini = initial; // @cast-boundary form-values
+    const o = out; // @cast-boundary form-values
+    const keys = new Set([...Object.keys(cur), ...Object.keys(ini)]);
+    for (const key of keys) {
+        const a = cur[key];
+        const b = ini[key];
+        if (!Object.is(a, b)) {
+            o[key] = a;
+        }
+    }
+    return out;
+}
+// buildInitialValues seeds untouched optional fields with "" for controlled
+// inputs; a `.optional()` server schema accepts undefined but not "".
+// String-only: number/money seed to 0 and boolean seeds to false, and an
+// untouched optional field of those types still submits that seed instead
+// of being omitted — no validation error surfaces it, unlike the "" case.
+// Fixing that needs real per-field seed-tracking (which value was actually
+// user-set vs. defaulted), not just a wider strip predicate here.
+function stripUntouchedEmptyStrings(values, initial, forceIncludeEmpty) {
+    const v = values; // @cast-boundary form-values
+    const ini = initial; // @cast-boundary form-values
+    let out;
+    for (const key of Object.keys(v)) {
+        // Value-based seed strip, except keys previously submitted as "" after a
+        // real clear — those must survive post-rebase submits (#1858).
+        if (!forceIncludeEmpty.has(key) && v[key] === "" && ini[key] === "") {
+            out ??= { ...v };
+            delete out[key];
+        }
+    }
+    return (out ?? v);
+}
+// Shallow-freeze so accidental mutations on the snapshot (e.g. a test
+// writing `snapshot.values.title = "x"`) throw in strict mode instead of
+// silently diverging from the controller's internal state. Deep-freeze
+// would be safer but expensive — keeping it shallow matches React's own
+// immutability expectations and leaves room for sub-controllers to manage
+// their own sub-trees without double-frozen parents blocking them.
+function freezeSnapshot(snapshot) {
+    return Object.freeze(snapshot);
+}
+export function createFormController(options) {
+    // Shallow copy so mutating the input after creation doesn't bleed into
+    // the controller's internal state. `initial` stays fixed across the
+    // controller's lifetime unless rebase() replaces it.
+    let values = { ...options.initial };
+    let initial = { ...options.initial };
+    let errors = Object.freeze({});
+    // Keys last submitted as "" (intentional clear). Survives rebase so a later
+    // submit of other fields does not drop them (#1858).
+    const forceIncludeEmpty = new Set();
+    // ctx is cast-held as TCtx; `undefined` is valid when callers don't
+    // declare conditional predicates that depend on it.
+    let ctx = options.ctx ?? undefined;
+    // Snapshot lives in a Store — same reference across getSnapshot() calls
+    // until a mutator invalidates it via setState. React's useSyncExternalStore
+    // compares snapshot identity to decide on a re-render; the Store holds the
+    // identity stable until invalidate() swaps it for a fresh build.
+    const snapshotStore = createStore(buildSnapshot());
+    // In-flight submit tracker. When a submit() is pending, a second call
+    // awaits the same promise instead of firing a parallel write — avoids
+    // double-submission on double-click and keeps the rebase semantics
+    // coherent (rebasing twice in quick succession would mis-align the
+    // baseline with what the server actually saw).
+    let submitInFlight = null;
+    function buildSnapshot() {
+        const changes = valuesDiff(values, initial);
+        const isDirty = Object.keys(changes).length > 0;
+        const fields = Object.freeze(computeFieldStates(options.fields, values, ctx));
+        return freezeSnapshot({
+            values,
+            initial,
+            changes,
+            isDirty,
+            isUnchanged: !isDirty,
+            errors,
+            fields,
+        });
+    }
+    function invalidate() {
+        snapshotStore.setState(buildSnapshot());
+    }
+    // Local shared implementations so submit() can call validate/rebase
+    // without the this-in-object-literal dance. Both also expose themselves
+    // as methods on the returned controller.
+    // Clears/replaces errors for a scoped run without touching fields outside
+    // the scope — a step-2 validate() that comes back clean must not wipe
+    // step-1's still-unresolved errors from an earlier submit() (or vice
+    // versa when step-2 newly has issues).
+    function replaceScopedErrors(scopeSet, grouped) {
+        if (scopeSet === undefined) {
+            errors = Object.freeze(grouped);
+            // skip: unscoped replace — wholesale overwrite, nothing left to merge
+            return;
+        }
+        const merged = {};
+        for (const [path, issues] of Object.entries(errors)) {
+            if (!scopeSet.has(path))
+                merged[path] = issues;
+        }
+        Object.assign(merged, grouped);
+        errors = Object.freeze(merged);
+    }
+    function runValidate(scope, opts) {
+        // See the validate() doc comment in types.ts for the scope contract.
+        // Normalize nested scope entries (`address.city` → `address`) so wizard
+        // callers that pass dotted paths still match issue root segments (#1898).
+        const scopeSet = scope === undefined ? undefined : new Set(scope.map((s) => s.split(".")[0] ?? s));
+        const includeRoot = opts?.includeRoot === true;
+        if (!options.schema) {
+            if (Object.keys(errors).length > 0) {
+                replaceScopedErrors(scopeSet, {});
+                invalidate();
+            }
+            return true;
+        }
+        const fieldStates = computeFieldStates(options.fields, values, ctx);
+        const parsed = options.schema.safeParse(values);
+        if (parsed.success) {
+            if (Object.keys(errors).length > 0) {
+                replaceScopedErrors(scopeSet, {});
+                invalidate();
+            }
+            return true;
+        }
+        const hiddenFields = new Set();
+        for (const [fieldKey, state] of Object.entries(fieldStates)) {
+            if (!state.visible)
+                hiddenFields.add(fieldKey);
+        }
+        const allIssues = zodErrorToFieldIssues(parsed.error);
+        const relevantIssues = allIssues.filter((issue) => {
+            const rootField = issue.path.split(".")[0] ?? "";
+            if (hiddenFields.has(rootField))
+                return false;
+            // Root-level .refine() issues use path "(root)". Wizard step validate()
+            // still drops them (#1885); submit() passes includeRoot so RenderEdit
+            // fields={…} cannot silently skip cross-field rules (#1907).
+            const isRootIssue = issue.path === "(root)";
+            if (scopeSet && !(includeRoot && isRootIssue) && !scopeSet.has(rootField)) {
+                return false;
+            }
+            return true;
+        });
+        if (relevantIssues.length === 0) {
+            if (Object.keys(errors).length > 0) {
+                replaceScopedErrors(scopeSet, {});
+                invalidate();
+            }
+            return true;
+        }
+        replaceScopedErrors(scopeSet, groupIssuesByPath(relevantIssues));
+        invalidate();
+        return false;
+    }
+    function runRebase() {
+        initial = { ...values };
+        if (Object.keys(errors).length > 0)
+            errors = Object.freeze({});
+        invalidate();
+    }
+    // Stale-submit-safe rebase. Difference to runRebase: the baseline is
+    // taken from the values that were actually SENT to the server, not
+    // from `values` at the moment the server replied. If the user typed
+    // into a field while the submit was in flight, those edits stay as
+    // dirty changes after the call — they never made it to the server, so
+    // pretending they did (via `initial = { ...values }`) would mask unsaved
+    // input. The race shows up as "user edits a field during a 2s save, sees
+    // it as saved, closes the tab — the edit is lost". This path keeps
+    // `values` untouched; only `initial` shifts to the submitted snapshot.
+    function runRebaseToSnapshot(snapped) {
+        initial = { ...snapped };
+        if (Object.keys(errors).length > 0)
+            errors = Object.freeze({});
+        invalidate();
+    }
+    return {
+        getSnapshot: snapshotStore.getSnapshot,
+        subscribe: snapshotStore.subscribe,
+        setField(key, value) {
+            // skip: value unchanged, avoid notify/re-render on identical set
+            // avoids a notify + re-render for "setField with same value" which
+            // happens a lot in controlled inputs on every keystroke of an
+            // untouched field.
+            if (Object.is(values[key], value))
+                return;
+            values = { ...values, [key]: value };
+            invalidate();
+        },
+        setValues(partial) {
+            // skip: partial matches current values, avoid no-op notify
+            // partial that matches current values shouldn't fire listeners.
+            let changed = false;
+            const v = values; // @cast-boundary form-values
+            const p = partial; // @cast-boundary form-values
+            for (const k of Object.keys(p)) {
+                if (!Object.is(v[k], p[k])) {
+                    changed = true;
+                    break;
+                }
+            }
+            // skip: no key in partial actually changed, avoid no-op notify
+            if (!changed)
+                return;
+            values = { ...values, ...partial };
+            invalidate();
+        },
+        clearErrors(path) {
+            if (path === undefined) {
+                // skip: no errors present, avoid no-op notify
+                if (Object.keys(errors).length === 0)
+                    return;
+                errors = Object.freeze({});
+            }
+            else {
+                // skip: path has no error entry, avoid no-op notify
+                if (!(path in errors))
+                    return;
+                const next = { ...errors };
+                delete next[path];
+                errors = Object.freeze(next);
+            }
+            invalidate();
+        },
+        setErrors(nextErrors) {
+            errors = Object.freeze({ ...nextErrors });
+            invalidate();
+        },
+        validate: runValidate,
+        reset() {
+            const alreadyClean = !snapshotStore.getSnapshot().isDirty && Object.keys(errors).length === 0;
+            // skip: already at baseline with no errors, no-op reset
+            if (alreadyClean)
+                return;
+            values = { ...initial };
+            errors = Object.freeze({});
+            forceIncludeEmpty.clear();
+            invalidate();
+        },
+        rebase: runRebase,
+        setCtx(nextCtx) {
+            // Cast back to TCtx: setCtx's public signature takes unknown so
+            // callers don't need to plumb generics. If conditions depend on ctx
+            // and callers pass the wrong shape, the predicate throws at
+            // evaluation time — which is the same fail mode as any other
+            // callback contract violation.
+            ctx = nextCtx;
+            invalidate();
+        },
+        async submit() {
+            const submitCfg = options.submit;
+            if (!submitCfg) {
+                throw new Error("createFormController: submit() called without a `submit` config. Configure `{ dispatcher, type }` on the controller or drive dispatching manually.");
+            }
+            // Concurrent-submit guard: a double-click (two invocations before
+            // the first network call returned) would otherwise fire two writes
+            // AND rebase twice — compounding with the stale-submit race below.
+            // Serialize: subsequent calls await the in-flight promise. Same
+            // pattern the server-side event-dispatcher uses (inFlightTurns).
+            if (submitInFlight)
+                return submitInFlight;
+            if (!runValidate(submitCfg.validateScope, { includeRoot: true })) {
+                return { validationBlocked: true, isSuccess: false };
+            }
+            const payloadMode = submitCfg.payloadMode ?? "values";
+            // Capture the whole snapshot AT submit-time. The user may keep
+            // typing while the network call is in flight; on success we rebase
+            // ONLY to the values that were actually sent, leaving any
+            // subsequent edits as a fresh dirty delta. Without this, an edit
+            // during the await would be swallowed into the new baseline and
+            // the user would see it as "saved" despite the server never seeing
+            // it. Same snapshot is fed to buildPayload — a custom transformer
+            // (nested-write case) sees exactly what submit() sees.
+            const submittedSnapshot = snapshotStore.getSnapshot();
+            const submittedValues = submittedSnapshot.values;
+            // buildPayload wins over payloadMode when both are set.
+            let payload;
+            if (submitCfg.buildPayload) {
+                payload = submitCfg.buildPayload(submittedSnapshot);
+            }
+            else if (payloadMode === "changes") {
+                if (submittedSnapshot.isUnchanged) {
+                    return {
+                        validationBlocked: false,
+                        isSuccess: true,
+                        isNoOp: true,
+                        data: submittedValues,
+                    };
+                }
+                payload = submittedSnapshot.changes;
+            }
+            else if (submitCfg.stripEmptySeeds === false) {
+                payload = submittedValues;
+            }
+            else {
+                payload = stripUntouchedEmptyStrings(submittedValues, submittedSnapshot.initial, forceIncludeEmpty);
+            }
+            // Only enforced here, right before the write actually happens — a
+            // form that never reaches this point (blocked by validation, or a
+            // clean payloadMode "changes" no-op) must not throw just because no
+            // dispatcher was ever wired up.
+            const dispatcher = submitCfg.dispatcher;
+            if (!dispatcher) {
+                // Return SubmitResult (not throw) so RenderEdit's banner path shows
+                // the misconfiguration instead of an unhandled rejection on save.
+                return {
+                    validationBlocked: false,
+                    isSuccess: false,
+                    isNoOp: false,
+                    error: {
+                        code: "misconfigured",
+                        httpStatus: 500,
+                        i18nKey: "errors.internal",
+                        message: "createFormController: submit() called without a dispatcher (dispatcher was absent when the form mounted). Pass `submit.dispatcher` explicitly, or mount a <DispatcherProvider> above this form.",
+                    },
+                };
+            }
+            const runWrite = async () => {
+                const result = await dispatcher.write(submitCfg.type, payload);
+                if (result.isSuccess) {
+                    // Remember intentional empty clears so post-rebase submits keep them (#1858).
+                    if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+                        for (const [k, v] of Object.entries(payload)) {
+                            if (v === "")
+                                forceIncludeEmpty.add(k);
+                            else
+                                forceIncludeEmpty.delete(k);
+                        }
+                    }
+                    // Rebase to the SNAPSHOT, not to the current values — see
+                    // runRebaseToSnapshot comment for why.
+                    runRebaseToSnapshot(submittedValues);
+                    return { validationBlocked: false, isSuccess: true, isNoOp: false, data: result.data };
+                }
+                const serverFields = result.error.details?.fields;
+                if (serverFields && serverFields.length > 0) {
+                    const prefix = submitCfg.serverFieldPathPrefix;
+                    const mappedFields = prefix
+                        ? stripServerFieldPathPrefix(serverFields, prefix)
+                        : serverFields;
+                    errors = Object.freeze(groupIssuesByPath(mappedFields));
+                    invalidate();
+                    const error = prefix
+                        ? { ...result.error, details: { ...result.error.details, fields: mappedFields } }
+                        : result.error;
+                    return { validationBlocked: false, isSuccess: false, isNoOp: false, error };
+                }
+                return { validationBlocked: false, isSuccess: false, isNoOp: false, error: result.error };
+            };
+            submitInFlight = runWrite();
+            try {
+                return await submitInFlight;
+            }
+            finally {
+                submitInFlight = null;
+            }
+        },
+    };
+}

package/dist/form/index.d.ts

@@ -0,0 +1,3 @@
+export { createFormController } from "./form-controller.js";
+export type { FieldConditionPredicate, FieldConditions, FieldConditionValue, FieldState, FormController, FormControllerOptions, FormSnapshot, FormValues, SubmitConfig, SubmitPayloadMode, SubmitResult, } from "./types.js";
+export { groupIssuesByPath, I18N_KEY_PARAM, zodErrorToFieldIssues } from "./zod-bridge.js";

package/dist/form/index.js

@@ -0,0 +1,2 @@
+export { createFormController } from "./form-controller.js";
+export { groupIssuesByPath, I18N_KEY_PARAM, zodErrorToFieldIssues } from "./zod-bridge.js";

package/dist/form/types.d.ts

@@ -0,0 +1,71 @@
+import type { ZodType } from "zod";
+import type { Dispatcher, FieldIssue, WriteResult } from "../dispatcher/index.js";
+export type FormValues = Record<string, unknown>;
+export type FieldConditionPredicate<TValues extends FormValues, TCtx> = (values: TValues, ctx: TCtx) => boolean;
+export type FieldConditionValue<TValues extends FormValues, TCtx> = boolean | FieldConditionPredicate<TValues, TCtx>;
+export type FieldConditions<TValues extends FormValues, TCtx = unknown> = {
+    readonly visible?: FieldConditionValue<TValues, TCtx>;
+    readonly readonly?: FieldConditionValue<TValues, TCtx>;
+    readonly required?: FieldConditionValue<TValues, TCtx>;
+};
+export type FieldState = {
+    readonly visible: boolean;
+    readonly readonly: boolean;
+    readonly required: boolean;
+};
+export type FormSnapshot<TValues extends FormValues> = {
+    readonly values: TValues;
+    readonly initial: TValues;
+    readonly changes: Partial<TValues>;
+    readonly isDirty: boolean;
+    readonly isUnchanged: boolean;
+    readonly errors: Readonly<Record<string, readonly FieldIssue[]>>;
+    readonly fields: Readonly<Record<string, FieldState>>;
+};
+export type FormController<TValues extends FormValues> = {
+    getSnapshot(): FormSnapshot<TValues>;
+    subscribe(listener: () => void): () => void;
+    setField<K extends keyof TValues>(key: K, value: TValues[K]): void;
+    setValues(partial: Partial<TValues>): void;
+    clearErrors(path?: string): void;
+    setErrors(errors: Readonly<Record<string, readonly FieldIssue[]>>): void;
+    validate(scope?: readonly string[]): boolean;
+    reset(): void;
+    rebase(): void;
+    setCtx(ctx: unknown): void;
+    submit<TData = unknown>(): Promise<SubmitResult<TData>>;
+};
+export type FormControllerOptions<TValues extends FormValues, TCtx = unknown> = {
+    readonly initial: TValues;
+    readonly schema?: ZodType;
+    readonly fields?: Readonly<Record<string, FieldConditions<TValues, TCtx>>>;
+    readonly ctx?: TCtx;
+    readonly submit?: SubmitConfig<TValues>;
+};
+export type SubmitPayloadMode = "values" | "changes";
+export type SubmitConfig<TValues extends FormValues = FormValues> = {
+    readonly dispatcher?: Dispatcher;
+    readonly type: string;
+    readonly payloadMode?: SubmitPayloadMode;
+    /** Only applies to payloadMode "values". Controls whether untouched
+     *  empty-string fields (still equal to their initial "" seed) are
+     *  stripped from the payload before dispatch — see SubmitPayloadMode's
+     *  "values" doc for why the stripping exists. Default `true` (current
+     *  behavior). Set `false` to send those fields as `""` unchanged. */
+    readonly stripEmptySeeds?: boolean;
+    readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
+    readonly serverFieldPathPrefix?: string;
+    /** Restricts submit()'s internal validate() call to these field names —
+     *  same contract as validate()'s `scope` param. Set by RenderEdit when the
+     *  caller's `fields` prop narrows which fields are rendered, so an
+     *  unrendered required field can't block a submit the user can't fix.
+     *  Omitted = unscoped (existing behavior, validates everything). */
+    readonly validateScope?: readonly string[];
+};
+export type SubmitResult<TData = unknown> = ({
+    readonly validationBlocked: false;
+    readonly isNoOp?: boolean;
+} & WriteResult<TData>) | {
+    readonly validationBlocked: true;
+    readonly isSuccess: false;
+};

package/dist/form/types.js

@@ -0,0 +1 @@
+export {};

package/dist/form/zod-bridge.d.ts

@@ -0,0 +1,5 @@
+import type { ZodError } from "zod";
+import type { FieldIssue } from "../dispatcher/index.js";
+export declare function zodErrorToFieldIssues(error: ZodError): FieldIssue[];
+export declare const I18N_KEY_PARAM = "i18nKey";
+export declare function groupIssuesByPath(issues: readonly FieldIssue[]): Record<string, readonly FieldIssue[]>;