@cosmicdrift/kumiko-headless 0.328.0 → 0.329.0

package/src/form/form-controller.ts

@@ -1,458 +0,0 @@
-import type { FieldIssue } from "../dispatcher";
-import { createStore } from "../store";
-import type {
-  FieldConditions,
-  FieldConditionValue,
-  FieldState,
-  FormController,
-  FormControllerOptions,
-  FormSnapshot,
-  FormValues,
-  SubmitResult,
-} from "./types";
-import { groupIssuesByPath, zodErrorToFieldIssues } from "./zod-bridge";
-
-// Paths without the prefix (hook-level errors, "(root)") pass through unchanged.
-function stripServerFieldPathPrefix(
-  issues: readonly FieldIssue[],
-  prefix: string,
-): readonly FieldIssue[] {
-  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<TValues extends FormValues, TCtx>(
-  condition: FieldConditionValue<TValues, TCtx> | undefined,
-  fallback: boolean,
-  values: TValues,
-  ctx: TCtx,
-): boolean {
-  if (condition === undefined) return fallback;
-  if (typeof condition === "boolean") return condition;
-  return condition(values, ctx);
-}
-
-function computeFieldStates<TValues extends FormValues, TCtx>(
-  rules: Readonly<Record<string, FieldConditions<TValues, TCtx>>> | undefined,
-  values: TValues,
-  ctx: TCtx,
-): Record<string, FieldState> {
-  if (!rules) return {};
-  const out: Record<string, FieldState> = {};
-  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<TValues extends FormValues>(
-  current: TValues,
-  initial: TValues,
-): Partial<TValues> {
-  const out: Partial<TValues> = {};
-  // 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 as Record<string, unknown>; // @cast-boundary form-values
-  const ini = initial as Record<string, unknown>; // @cast-boundary form-values
-  const o = out as Record<string, unknown>; // @cast-boundary form-values
-  const keys = new Set<string>([...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<TValues extends FormValues>(
-  values: TValues,
-  initial: TValues,
-  forceIncludeEmpty: ReadonlySet<string>,
-): TValues {
-  const v = values as Record<string, unknown>; // @cast-boundary form-values
-  const ini = initial as Record<string, unknown>; // @cast-boundary form-values
-  let out: Record<string, unknown> | undefined;
-  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) as TValues;
-}
-
-// 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<TValues extends FormValues>(
-  snapshot: FormSnapshot<TValues>,
-): FormSnapshot<TValues> {
-  return Object.freeze(snapshot);
-}
-
-export function createFormController<TValues extends FormValues, TCtx = unknown>(
-  options: FormControllerOptions<TValues, TCtx>,
-): FormController<TValues> {
-  // 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: TValues = { ...options.initial };
-  let initial: TValues = { ...options.initial };
-  let errors: Readonly<Record<string, readonly FieldIssue[]>> = 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<string>();
-  // ctx is cast-held as TCtx; `undefined` is valid when callers don't
-  // declare conditional predicates that depend on it.
-  let ctx: TCtx = (options.ctx as TCtx) ?? (undefined as TCtx);
-
-  // 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<FormSnapshot<TValues>>(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: Promise<unknown> | null = null;
-
-  function buildSnapshot(): FormSnapshot<TValues> {
-    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: Set<string> | undefined,
-    grouped: Readonly<Record<string, readonly FieldIssue[]>>,
-  ): void {
-    if (scopeSet === undefined) {
-      errors = Object.freeze(grouped);
-      // skip: unscoped replace — wholesale overwrite, nothing left to merge
-      return;
-    }
-    const merged: Record<string, readonly FieldIssue[]> = {};
-    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?: readonly string[],
-    opts?: { readonly includeRoot?: boolean },
-  ): boolean {
-    // 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<string>();
-    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(): void {
-    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: TValues): void {
-    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 as Record<string, unknown>; // @cast-boundary form-values
-      const p = partial as Record<string, unknown>; // @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: Record<string, readonly FieldIssue[]> = { ...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 as TCtx;
-      invalidate();
-    },
-    async submit<TData = unknown>(): Promise<SubmitResult<TData>> {
-      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 as Promise<SubmitResult<TData>>;
-
-      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: unknown;
-      if (submitCfg.buildPayload) {
-        payload = submitCfg.buildPayload(submittedSnapshot);
-      } else if (payloadMode === "changes") {
-        if (submittedSnapshot.isUnchanged) {
-          return {
-            validationBlocked: false,
-            isSuccess: true,
-            isNoOp: true,
-            data: submittedValues as unknown as TData,
-          };
-        }
-        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 (): Promise<SubmitResult<TData>> => {
-        const result = await dispatcher.write<TData>(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 as Record<string, unknown>)) {
-              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 as Promise<SubmitResult<TData>>);
-      } finally {
-        submitInFlight = null;
-      }
-    },
-  };
-}

package/src/form/index.ts

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