@cosmicdrift/kumiko-headless 0.192.0 → 0.193.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.192.0",
+  "version": "0.193.0",
   "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.192.0",
+    "@cosmicdrift/kumiko-framework": "0.193.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

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

@@ -214,6 +214,23 @@ describe("createFormController — submit()", () => {
     expect(disp.writeSpy).toHaveBeenCalledWith("app:write:task:create", { note: "" });
   });
 
+  test("payloadMode: 'values' with stripEmptySeeds: false — keeps an untouched empty-string field", async () => {
+    // Same setup as the strip test above, but the caller opts out — the
+    // untouched "" seed must survive unchanged in the payload.
+    const disp = makeDispatcher();
+    const form = createFormController({
+      initial: { title: "hello", dueDate: "" },
+      submit: { dispatcher: disp, type: "app:write:task:create", stripEmptySeeds: false },
+    });
+
+    await form.submit();
+
+    expect(disp.writeSpy).toHaveBeenCalledWith("app:write:task:create", {
+      title: "hello",
+      dueDate: "",
+    });
+  });
+
   test("stale-submit race: edits during the in-flight write stay dirty after success", async () => {
     // User submits "hello", the network takes 50ms. During those 50ms the
     // user types "world" into the same field. The server sees "hello"

package/src/form/form-controller.ts

@@ -325,6 +325,8 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
           };
         }
         payload = submittedSnapshot.changes;
+      } else if (submitCfg.stripEmptySeeds === false) {
+        payload = submittedValues;
       } else {
         payload = stripUntouchedEmptyStrings(submittedValues, submittedSnapshot.initial);
       }

package/src/form/types.ts

@@ -231,8 +231,14 @@ export type FormControllerOptions<TValues extends FormValues, TCtx = unknown> =
 // objects — but that assumes an update flow. For creates, `changes ===
 // values` in practice because initial is empty.
 //
-//   - "values"  — send the full current `values` object. Right for create
+//   - "values"  — send the current `values` object. Right for create
 //                 handlers whose schema expects a full entity payload.
+//                 Untouched fields that are still "" (the seed
+//                 buildInitialValues gives controlled optional inputs)
+//                 are stripped from the payload before it's sent, because
+//                 `.optional()` server schemas accept `undefined` but not
+//                 `""`. Set `stripEmptySeeds: false` on SubmitConfig to
+//                 opt out and send those fields as `""` unchanged.
 //   - "changes" — send only the `changes` delta. Right for update
 //                 handlers; noop when the form is un-dirty (submit
 //                 short-circuits into a no-network success).
@@ -246,6 +252,12 @@ export type SubmitConfig<TValues extends FormValues = FormValues> = {
   // Qualified write-handler name (e.g. "orders:write:order:create").
   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;
   // Optional payload transformer — overrides payloadMode. Used for
   // nested-writes: the submit path calls buildPayload(snapshot) once at
   // submit-time and sends the result. The snapshot is the one captured