@cosmicdrift/kumiko-headless 0.324.0 → 0.325.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.324.0",
+  "version": "0.325.1",
   "description": "Headless UI logic for Kumiko — Dispatcher contract, Form-Controller, View-Model, Nav-Resolver. Plattform- und React-frei; jeder Renderer (renderer, renderer-web, renderer-native, …) komponiert darauf.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.324.0",
+    "@cosmicdrift/kumiko-framework": "0.325.1",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

package/src/form/__tests__/submit.test.ts

@@ -172,6 +172,67 @@ describe("createFormController — submit()", () => {
     expect(form.getSnapshot().errors["title"]?.[0]?.code).toBe("too_small");
   });
 
+  test("server validation failure with serverFieldPathPrefix: paths are stripped before mapping to form fields", async () => {
+    const disp = makeDispatcher({
+      isSuccess: false,
+      error: {
+        code: "validation_error",
+        httpStatus: 400,
+        i18nKey: "errors.validation",
+        message: "Validation failed",
+        details: {
+          fields: [
+            { path: "changes.count", code: "too_small", i18nKey: "errors.validation.too_small" },
+            { path: "title", code: "too_small", i18nKey: "errors.validation.too_small" },
+          ],
+        },
+      },
+    });
+    const form = createFormController({
+      initial: { title: "hello", count: 1 },
+      submit: {
+        dispatcher: disp,
+        type: "app:write:task:update",
+        serverFieldPathPrefix: "changes.",
+      },
+    });
+
+    const result = await form.submit();
+
+    expect(result.isSuccess).toBe(false);
+    expect(form.getSnapshot().errors["count"]).toBeDefined();
+    expect(form.getSnapshot().errors["title"]).toBeDefined();
+    expect(form.getSnapshot().errors["changes.count"]).toBeUndefined();
+    if (result.validationBlocked || result.isSuccess) throw new Error("expected a server failure");
+    expect(result.error.details?.fields?.map((f) => f.path)).toEqual(["count", "title"]);
+  });
+
+  test("server validation failure without serverFieldPathPrefix: prefixed paths pass through unchanged", async () => {
+    const disp = makeDispatcher({
+      isSuccess: false,
+      error: {
+        code: "validation_error",
+        httpStatus: 400,
+        i18nKey: "errors.validation",
+        message: "Validation failed",
+        details: {
+          fields: [
+            { path: "changes.count", code: "too_small", i18nKey: "errors.validation.too_small" },
+          ],
+        },
+      },
+    });
+    const form = createFormController({
+      initial: { title: "hello", count: 1 },
+      submit: { dispatcher: disp, type: "app:write:task:update" },
+    });
+
+    const result = await form.submit();
+
+    expect(result.isSuccess).toBe(false);
+    expect(form.getSnapshot().errors["changes.count"]).toBeDefined();
+  });
+
   test("non-validation server error: form state is left alone, error passes through", async () => {
     const disp = makeDispatcher({
       isSuccess: false,

package/src/form/form-controller.ts

@@ -12,6 +12,16 @@ import type {
 } 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).
@@ -423,8 +433,16 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
 
         const serverFields = result.error.details?.fields;
         if (serverFields && serverFields.length > 0) {
-          errors = Object.freeze(groupIssuesByPath(serverFields));
+          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 };
       };

package/src/form/types.ts

@@ -272,6 +272,9 @@ export type SubmitConfig<TValues extends FormValues = FormValues> = {
   // That's intentional: a caller choosing to write a transformer is
   // making an explicit statement about payload shape.
   readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
+  // When buildPayload nests values under a key, server issue paths carry it
+  // ("changes.vin"); submit() strips this prefix so errors map onto form fields.
+  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