@cosmicdrift/kumiko-headless 0.191.0 → 0.193.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.191.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.191.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

package/src/view-model/__tests__/edit.test.ts

@@ -549,4 +549,48 @@ describe("computeEditViewModel — embedded-list cells (#1835)", () => {
     const field = asFields(vm.sections[0]).fields[0];
     expect(field?.embeddedListCurrency).toBeUndefined();
   });
+
+  test("imageVariant is the FIRST variant declared on the field def", () => {
+    const entity = {
+      fields: {
+        avatar: {
+          type: "image",
+          variants: {
+            profile: { fit: "cover", size: { width: 512, height: 512 }, format: "webp" },
+            big: { fit: "cover", size: { width: 1024, height: 1024 }, format: "webp" },
+          },
+        },
+      },
+    } as unknown as EntityDefinition;
+
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["avatar"] }] }),
+      entity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.imageVariant).toBe("profile");
+  });
+
+  test("imageVariant is undefined for an image field without variants", () => {
+    const entity = {
+      fields: {
+        avatar: { type: "image" },
+      },
+    } as unknown as EntityDefinition;
+
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["avatar"] }] }),
+      entity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.imageVariant).toBeUndefined();
+  });
 });

package/src/view-model/edit.ts

@@ -170,8 +170,14 @@ export function computeEditViewModel<
       // importing it just for one fallback string.
       const resolvedCurrency = entity.defaultCurrency ?? "EUR";
       const fileDef = isFileType
-        ? (fieldDef as unknown as { accept?: readonly string[]; maxSize?: string })
+        ? (fieldDef as unknown as {
+            accept?: readonly string[];
+            maxSize?: string;
+            variants?: Readonly<Record<string, unknown>>;
+          })
         : undefined;
+      const imageVariant =
+        fieldDef.type === "image" ? Object.keys(fileDef?.variants ?? {})[0] : undefined;
       // Embedded-LIST field (`multiple: true`) — per-cell metadata for a
       // renderer to draw one row per array item (invoice-positions-style
       // table). A plain (non-list) embedded field emits none of this; the
@@ -261,6 +267,7 @@ export function computeEditViewModel<
         ...(fileDef?.accept !== undefined && { accept: fileDef.accept }),
         ...(fileDef?.maxSize !== undefined && { maxSize: fileDef.maxSize }),
         ...(isFileType && { entityType: screen.entity, fieldName: normalized.field }),
+        ...(imageVariant !== undefined && { imageVariant }),
         ...(normalized.icon !== undefined && { icon: normalized.icon }),
         ...(embeddedListCells !== undefined && { embeddedListCells }),
         ...(embeddedListDef?.minItems !== undefined && {

package/src/view-model/types.ts

@@ -181,6 +181,13 @@ export type EditFieldViewModel = {
    *  die richtige Field-Def prüfen kann. */
   readonly entityType?: string;
   readonly fieldName?: string;
+  /** Only for `type: "image"` — the variant name the preview requests
+   *  (`/api/files/:id/variant/:name`) instead of the original. The FIRST
+   *  variant declared on the field def wins; a spec may legitimately carry
+   *  neither `size` nor `maxEdge` (format-/blur-only), so "the smallest one"
+   *  is not a rule that always has an answer. Absent when the field declares
+   *  no variants — the preview then loads the original. */
+  readonly imageVariant?: string;
   /** Prefix-icon key from `EditFieldSpec.icon`, passed through unchanged
    *  (no i18n — it's a symbolic key, not a display string). The renderer
    *  resolves it against the FIELD_ICONS registry; unknown keys silently