@cosmicdrift/kumiko-headless 0.168.0 → 0.171.0

package/package.json

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

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

@@ -19,6 +19,7 @@ const orderEntity = {
     notes: { type: "text" },
     vatExempt: { type: "boolean" },
     vatReason: { type: "text" },
+    kind: { type: "text" },
   },
 } as unknown as EntityDefinition;
 
@@ -152,6 +153,34 @@ describe("computeEditViewModel", () => {
     expect(reasonShown?.required).toBe(true);
   });
 
+  test("section with all fields hidden by visible condition → section.visible is false but section stays in the array (key stability)", () => {
+    const screen = editScreen({
+      sections: [
+        {
+          title: "Person",
+          fields: [{ field: "customerName", visible: { field: "kind", eq: "person" } }],
+        },
+        {
+          title: "Firma",
+          fields: [{ field: "notes", visible: { field: "kind", eq: "company" } }],
+        },
+      ],
+    });
+
+    const vm = computeEditViewModel({
+      screen,
+      entity: orderEntity,
+      values: { kind: "person", customerName: "Acme" },
+      translate,
+      featureName: "orders",
+    });
+
+    expect(vm.sections).toHaveLength(2);
+    expect(asFields(vm.sections[0]).visible).toBe(true);
+    expect(asFields(vm.sections[1]).visible).toBe(false);
+    expect(vm.sections[1]?.title).toBe("Firma");
+  });
+
   test("readonly condition { field, ne } evaluates against form values", () => {
     const screen = editScreen({
       sections: [
@@ -258,6 +287,42 @@ describe("computeEditViewModel", () => {
     });
     expect(asFields(vm.sections[0]).fields[0]?.span).toBe(2);
   });
+
+  test("section.description is translated and passed through; absent stays undefined", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({
+        sections: [
+          {
+            title: "Basics",
+            description: "orders:screen:order-edit.basics.help",
+            fields: ["notes"],
+          },
+          { title: "Extra", fields: ["kind"] },
+        ],
+      }),
+      entity: orderEntity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+    expect(asFields(vm.sections[0]).description).toBe("orders:screen:order-edit.basics.help");
+    expect(asFields(vm.sections[1]).description).toBeUndefined();
+  });
+
+  test("field.icon propagates to the view model; absent stays undefined", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({
+        sections: [{ title: "x", fields: [{ field: "customerName", icon: "user" }, "notes"] }],
+      }),
+      entity: orderEntity,
+      values: {},
+      translate,
+      featureName: "orders",
+    });
+    const fields = asFields(vm.sections[0]).fields;
+    expect(fields[0]?.icon).toBe("user");
+    expect(fields[1]?.icon).toBeUndefined();
+  });
 });
 
 describe("computeEditViewModel — date/timestamp min/max/locale (#369)", () => {

package/src/view-model/edit.ts

@@ -151,13 +151,21 @@ export function computeEditViewModel<
         ...(fileDef?.accept !== undefined && { accept: fileDef.accept }),
         ...(fileDef?.maxSize !== undefined && { maxSize: fileDef.maxSize }),
         ...(isFileType && { entityType: screen.entity, fieldName: normalized.field }),
+        ...(normalized.icon !== undefined && { icon: normalized.icon }),
       };
       return view;
     });
+    // Boot-validator rejects fields.length === 0 (screens.ts), so an empty
+    // section never reaches this code.
+    const visible = fields.some((field) => field.visible);
     return {
       kind: "fields" as const,
+      visible,
       // Titellose Section (flache Form) → kein h3; nur übersetzen wenn gesetzt.
       ...(sectionSpec.title !== undefined && { title: translate(sectionSpec.title) }),
+      ...(sectionSpec.description !== undefined && {
+        description: translate(sectionSpec.description),
+      }),
       columns: sectionSpec.columns ?? 1,
       fields,
     };

package/src/view-model/types.ts

@@ -143,6 +143,11 @@ export type EditFieldViewModel = {
    *  die richtige Field-Def prüfen kann. */
   readonly entityType?: string;
   readonly fieldName?: 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
+   *  fall back to "no icon". */
+  readonly icon?: string;
 };
 
 // Discriminated by `kind` — mirrors EditSectionSpec on the engine side.
@@ -152,8 +157,15 @@ export type EditSectionViewModel = EditFieldsSectionViewModel | EditExtensionSec
 
 export type EditFieldsSectionViewModel = {
   readonly kind: "fields";
+  /** False when the section has fields but none of them is visible.
+   *  The renderer then draws nothing, but the section stays in the array
+   *  (key stability). */
+  readonly visible: boolean;
   /** Optional — eine titellose Section rendert nur ihre Felder (flache Form). */
   readonly title?: string;
+  /** Translated help text under the block heading, from
+   *  `EditFieldsSection.description`. Renders even without `title`. */
+  readonly description?: string;
   readonly columns: number;
   readonly fields: readonly EditFieldViewModel[];
 };