@cosmicdrift/kumiko-headless 0.183.2 → 0.185.0

package/package.json

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

package/src/index.ts

@@ -86,6 +86,9 @@ export type {
   EditSectionSpec,
   EditSectionViewModel,
   EditViewModel,
+  EmbeddedDerivedOp,
+  EmbeddedListCellViewModel,
+  EmbeddedListIssueGroups,
   FieldConditionCtx,
   FieldRenderer,
   ListColumnSpec,
@@ -96,4 +99,13 @@ export type {
   ScreenSlots,
   Translate,
 } from "./view-model";
-export { computeEditViewModel, computeListViewModel, fieldLabelKey } from "./view-model";
+export {
+  computeDerivedCellValue,
+  computeEditViewModel,
+  computeListViewModel,
+  embeddedCellLabelKey,
+  embeddedCellOptionLabelKey,
+  fieldLabelKey,
+  groupEmbeddedListIssues,
+  sumEmbeddedListColumn,
+} from "./view-model";

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

@@ -362,3 +362,191 @@ describe("computeEditViewModel — date/timestamp min/max/locale (#369)", () =>
     expect(field?.dateLocale).toBeUndefined();
   });
 });
+
+describe("computeEditViewModel — embedded-list cells (#1835)", () => {
+  const lineFieldSchema = {
+    description: { type: "text", required: true },
+    quantity: { type: "number", required: true },
+    unit: { type: "select", options: ["hour", "day"] },
+    product: { type: "reference", entity: "product", labelField: "name" },
+  };
+
+  function embeddedListEntity(overrides?: Record<string, unknown>): EntityDefinition {
+    return {
+      fields: {
+        lines: {
+          type: "embedded",
+          multiple: true,
+          schema: lineFieldSchema,
+          ...overrides,
+        },
+      },
+    } as unknown as EntityDefinition;
+  }
+
+  test("multiple: true embedded field → embeddedListCells has one entry per schema key with correct type/required/options/optionLabels/refEntity", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["lines"] }] }),
+      entity: embeddedListEntity(),
+      values: { lines: [] },
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.type).toBe("embedded");
+    const cells = field?.embeddedListCells;
+    expect(cells).toHaveLength(4);
+
+    const byField = Object.fromEntries((cells ?? []).map((cell) => [cell.field, cell]));
+    expect(byField["description"]).toMatchObject({
+      type: "text",
+      required: true,
+      label: "orders:entity:order:field:lines:cell:description",
+    });
+    expect(byField["quantity"]).toMatchObject({ type: "number", required: true });
+    expect(byField["unit"]).toMatchObject({
+      type: "select",
+      required: false,
+      options: ["hour", "day"],
+      optionLabels: { hour: "hour", day: "day" },
+    });
+    expect(byField["product"]).toMatchObject({
+      type: "reference",
+      required: false,
+      refEntity: "product",
+      refFeature: "orders",
+      refLabelField: "name",
+    });
+  });
+
+  test("minItems/maxItems/derived/totals pass through onto the field view-model when set", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["lines"] }] }),
+      entity: embeddedListEntity({
+        minItems: 1,
+        maxItems: 20,
+        derived: { total: { op: "multiply", from: ["quantity", "unitPrice"] } },
+        totals: ["quantity", "total"],
+      }),
+      values: { lines: [] },
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.embeddedListMinItems).toBe(1);
+    expect(field?.embeddedListMaxItems).toBe(20);
+    expect(field?.embeddedListDerived).toEqual({
+      total: { op: "multiply", from: ["quantity", "unitPrice"] },
+    });
+    expect(field?.embeddedListTotals).toEqual(["quantity", "total"]);
+  });
+
+  test("minItems/maxItems/derived/totals stay undefined when not declared", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["lines"] }] }),
+      entity: embeddedListEntity(),
+      values: { lines: [] },
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.embeddedListMinItems).toBeUndefined();
+    expect(field?.embeddedListMaxItems).toBeUndefined();
+    expect(field?.embeddedListDerived).toBeUndefined();
+    expect(field?.embeddedListTotals).toBeUndefined();
+  });
+
+  test("a plain (non-list) embedded field never gets embeddedListCells — that's how the renderer tells it apart from an embedded list", () => {
+    const entity = {
+      fields: {
+        meta: { type: "embedded", schema: { note: { type: "text" } } },
+      },
+    } as unknown as EntityDefinition;
+
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["meta"] }] }),
+      entity,
+      values: { meta: {} },
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.type).toBe("embedded");
+    expect(field?.embeddedListCells).toBeUndefined();
+    expect(field?.embeddedListMinItems).toBeUndefined();
+  });
+
+  test("select-cell options are translated when registered, fall back to the raw value otherwise", () => {
+    const translateUnit = (key: string) =>
+      key === "orders:entity:order:field:lines:cell:unit:option:hour" ? "Stunde" : key;
+
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["lines"] }] }),
+      entity: embeddedListEntity(),
+      values: { lines: [] },
+      translate: translateUnit,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    const unitCell = field?.embeddedListCells?.find((cell) => cell.field === "unit");
+    expect(unitCell?.optionLabels).toEqual({ hour: "Stunde", day: "day" });
+  });
+
+  test("embeddedListCurrency mirrors entity.defaultCurrency (#1839)", () => {
+    const entity = {
+      defaultCurrency: "USD",
+      fields: {
+        lines: { type: "embedded", multiple: true, schema: lineFieldSchema },
+      },
+    } as unknown as EntityDefinition;
+
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["lines"] }] }),
+      entity,
+      values: { lines: [] },
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.embeddedListCurrency).toBe("USD");
+  });
+
+  test("embeddedListCurrency falls back to EUR when the entity has no defaultCurrency (#1839)", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["lines"] }] }),
+      entity: embeddedListEntity(),
+      values: { lines: [] },
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.embeddedListCurrency).toBe("EUR");
+  });
+
+  test("embeddedListCurrency is undefined for a plain (non-list) embedded field", () => {
+    const entity = {
+      defaultCurrency: "USD",
+      fields: {
+        meta: { type: "embedded", schema: { note: { type: "text" } } },
+      },
+    } as unknown as EntityDefinition;
+
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ title: "x", fields: ["meta"] }] }),
+      entity,
+      values: { meta: {} },
+      translate,
+      featureName: "orders",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.embeddedListCurrency).toBeUndefined();
+  });
+});

package/src/view-model/__tests__/embedded-list.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "bun:test";
+import type { FieldIssue } from "../../dispatcher";
+import {
+  computeDerivedCellValue,
+  groupEmbeddedListIssues,
+  sumEmbeddedListColumn,
+} from "../embedded-list";
+
+function issue(path: string): FieldIssue {
+  return { path, code: "custom", i18nKey: "errors.validation.custom" };
+}
+
+describe("computeDerivedCellValue", () => {
+  test("multiply with two values", () => {
+    expect(computeDerivedCellValue("multiply", [3, 4])).toBe(12);
+  });
+
+  test("multiply with three values", () => {
+    expect(computeDerivedCellValue("multiply", [2, 3, 5])).toBe(30);
+  });
+
+  test("sum adds all values", () => {
+    expect(computeDerivedCellValue("sum", [1, 2, 3])).toBe(6);
+  });
+
+  test("subtract subtracts every value after the first", () => {
+    expect(computeDerivedCellValue("subtract", [10, 3, 2])).toBe(5);
+  });
+
+  test("multiply returns undefined when a source is missing", () => {
+    expect(computeDerivedCellValue("multiply", [3, undefined])).toBeUndefined();
+  });
+
+  test("sum treats a missing source as 0", () => {
+    expect(computeDerivedCellValue("sum", [1, undefined, 2])).toBe(3);
+  });
+
+  test("subtract treats a missing source as 0", () => {
+    expect(computeDerivedCellValue("subtract", [10, undefined])).toBe(10);
+  });
+});
+
+describe("sumEmbeddedListColumn", () => {
+  test("sums a numeric column across rows", () => {
+    const rows = [{ amount: 100 }, { amount: 250 }, { amount: 50 }];
+    expect(sumEmbeddedListColumn(rows, "amount")).toBe(400);
+  });
+
+  test("treats a row missing the field as 0", () => {
+    const rows = [{ amount: 100 }, { other: 1 }, { amount: 50 }];
+    expect(sumEmbeddedListColumn(rows, "amount")).toBe(150);
+  });
+
+  test("returns 0 for an empty rows array", () => {
+    expect(sumEmbeddedListColumn([], "amount")).toBe(0);
+  });
+});
+
+describe("groupEmbeddedListIssues", () => {
+  test("buckets list/row/cell issues, ignoring unrelated and too-deep keys", () => {
+    const allIssues: Record<string, readonly FieldIssue[]> = {
+      lines: [issue("lines")],
+      "lines.0": [issue("lines.0")],
+      "lines.0.amount": [issue("lines.0.amount")],
+      "lines.1.qty": [issue("lines.1.qty")],
+      title: [issue("title")],
+      "lines.0.amount.nested": [issue("lines.0.amount.nested")],
+    };
+
+    const result = groupEmbeddedListIssues(allIssues, "lines");
+
+    expect(result.listIssues).toEqual([issue("lines")]);
+    expect(result.rowIssues).toEqual({ 0: [issue("lines.0")] });
+    expect(result.cellIssues).toEqual({
+      "0.amount": [issue("lines.0.amount")],
+      "1.qty": [issue("lines.1.qty")],
+    });
+    // Unrelated top-level key and the too-deep key must not leak anywhere.
+    expect(Object.values(result.cellIssues).flat()).not.toContainEqual(issue("title"));
+    expect(Object.values(result.cellIssues).flat()).not.toContainEqual(
+      issue("lines.0.amount.nested"),
+    );
+  });
+});

package/src/view-model/__tests__/field-labels.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, test } from "bun:test";
-import { buildOptionLabels, fieldLabelKey, fieldOptionLabelKey } from "../list";
+import {
+  buildOptionLabels,
+  embeddedCellLabelKey,
+  embeddedCellOptionLabelKey,
+  fieldLabelKey,
+  fieldOptionLabelKey,
+} from "../list";
 
 describe("fieldLabelKey", () => {
   test("follows feature:entity:field convention", () => {
@@ -17,16 +23,40 @@ describe("fieldOptionLabelKey", () => {
   });
 });
 
+describe("embeddedCellLabelKey", () => {
+  test("adds a cell segment for the sub-field name", () => {
+    expect(embeddedCellLabelKey("billing", "invoice", "lines", "quantity")).toBe(
+      "billing:entity:invoice:field:lines:cell:quantity",
+    );
+  });
+});
+
+describe("embeddedCellOptionLabelKey", () => {
+  test("appends option value segment after the cell segment", () => {
+    expect(embeddedCellOptionLabelKey("billing", "invoice", "lines", "unit", "hour")).toBe(
+      "billing:entity:invoice:field:lines:cell:unit:option:hour",
+    );
+  });
+});
+
 describe("buildOptionLabels", () => {
   test("maps option values to translated labels with fallback to raw value", () => {
     const labels = buildOptionLabels(
       (key) => (key.endsWith(":option:draft") ? "Draft" : key),
-      "tasks",
-      "task",
-      "status",
+      (value) => fieldOptionLabelKey("tasks", "task", "status", value),
       ["draft", "done"],
     );
     expect(labels["draft"]).toBe("Draft");
     expect(labels["done"]).toBe("done");
   });
+
+  test("keyFor lets the caller supply any key convention (e.g. embedded cell)", () => {
+    const labels = buildOptionLabels(
+      (key) => (key.endsWith(":option:hour") ? "Hour" : key),
+      (value) => embeddedCellOptionLabelKey("billing", "invoice", "lines", "unit", value),
+      ["hour", "day"],
+    );
+    expect(labels["hour"]).toBe("Hour");
+    expect(labels["day"]).toBe("day");
+  });
 });

package/src/view-model/edit.ts

@@ -9,8 +9,42 @@ import {
   normalizeEditField,
   parseRefTarget,
 } from "@cosmicdrift/kumiko-framework/ui-types";
-import { buildOptionLabels, fieldLabelKey } from "./list";
-import type { EditFieldViewModel, EditSectionViewModel, EditViewModel, Translate } from "./types";
+import {
+  buildOptionLabels,
+  embeddedCellLabelKey,
+  embeddedCellOptionLabelKey,
+  fieldLabelKey,
+  fieldOptionLabelKey,
+} from "./list";
+import type {
+  EditFieldViewModel,
+  EditSectionViewModel,
+  EditViewModel,
+  EmbeddedListCellViewModel,
+  Translate,
+} from "./types";
+
+// Sub-field shape read off an EmbeddedFieldDef.schema entry. Mirrors
+// EmbeddedSubFieldDef from packages/types/src/fields.ts — headless only
+// depends on @cosmicdrift/kumiko-framework/ui-types (client-safe subset),
+// which doesn't re-export the embedded types, so this stays a local cast
+// shape like every other field-type narrowing in this file.
+type EmbeddedSubFieldShape = {
+  readonly type:
+    | "text"
+    | "number"
+    | "boolean"
+    | "date"
+    | "money"
+    | "decimal"
+    | "select"
+    | "reference"
+    | "timestamp";
+  readonly required?: boolean;
+  readonly options?: readonly string[];
+  readonly entity?: string;
+  readonly labelField?: string;
+};
 
 export type ComputeEditViewModelInput<
   TValues extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
@@ -72,7 +106,11 @@ export function computeEditViewModel<
           : undefined;
       const optionLabels =
         options !== undefined
-          ? buildOptionLabels(translate, featureName, screen.entity, normalized.field, options)
+          ? buildOptionLabels(
+              translate,
+              (value) => fieldOptionLabelKey(featureName, screen.entity, normalized.field, value),
+              options,
+            )
           : undefined;
       // Multiline-Hint bei `type: "text"` — der Renderer wechselt
       // dann auf textarea. ViewModel hält die Form-Render-Decision
@@ -127,6 +165,69 @@ export function computeEditViewModel<
       const fileDef = isFileType
         ? (fieldDef as unknown as { accept?: readonly string[]; maxSize?: string })
         : 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
+      // renderer tells the two apart by whether embeddedListCells is set,
+      // not by `type` (which stays "embedded" either way).
+      const isEmbeddedList =
+        fieldDef.type === "embedded" &&
+        (fieldDef as unknown as { multiple?: boolean }).multiple === true;
+      const embeddedListDef = isEmbeddedList
+        ? (fieldDef as unknown as {
+            schema: Readonly<Record<string, EmbeddedSubFieldShape>>;
+            minItems?: number;
+            maxItems?: number;
+            derived?: Readonly<
+              Record<
+                string,
+                { readonly op: "multiply" | "sum" | "subtract"; readonly from: readonly string[] }
+              >
+            >;
+            totals?: readonly string[];
+          })
+        : undefined;
+      const embeddedListCells: readonly EmbeddedListCellViewModel[] | undefined =
+        embeddedListDef !== undefined
+          ? Object.entries(embeddedListDef.schema).map(([subFieldName, subField]) => {
+              const cellLabel = translate(
+                embeddedCellLabelKey(featureName, screen.entity, normalized.field, subFieldName),
+              );
+              const cellOptions = subField.type === "select" ? (subField.options ?? []) : undefined;
+              const cellOptionLabels =
+                cellOptions !== undefined
+                  ? buildOptionLabels(
+                      translate,
+                      (value) =>
+                        embeddedCellOptionLabelKey(
+                          featureName,
+                          screen.entity,
+                          normalized.field,
+                          subFieldName,
+                          value,
+                        ),
+                      cellOptions,
+                    )
+                  : undefined;
+              const cellRefTarget =
+                subField.type === "reference" && subField.entity !== undefined
+                  ? parseRefTarget(subField.entity, featureName)
+                  : undefined;
+              const cell: EmbeddedListCellViewModel = {
+                field: subFieldName,
+                label: cellLabel,
+                type: subField.type,
+                required: subField.required === true,
+                ...(cellOptions !== undefined && { options: cellOptions }),
+                ...(cellOptionLabels !== undefined && { optionLabels: cellOptionLabels }),
+                ...(cellRefTarget !== undefined && { refEntity: cellRefTarget.entityName }),
+                ...(cellRefTarget !== undefined && { refFeature: cellRefTarget.featureName }),
+                ...(subField.type === "reference" &&
+                  subField.labelField !== undefined && { refLabelField: subField.labelField }),
+              };
+              return cell;
+            })
+          : undefined;
       const view: EditFieldViewModel = {
         field: normalized.field,
         label,
@@ -152,6 +253,28 @@ export function computeEditViewModel<
         ...(fileDef?.maxSize !== undefined && { maxSize: fileDef.maxSize }),
         ...(isFileType && { entityType: screen.entity, fieldName: normalized.field }),
         ...(normalized.icon !== undefined && { icon: normalized.icon }),
+        ...(embeddedListCells !== undefined && { embeddedListCells }),
+        ...(embeddedListDef?.minItems !== undefined && {
+          embeddedListMinItems: embeddedListDef.minItems,
+        }),
+        ...(embeddedListDef?.maxItems !== undefined && {
+          embeddedListMaxItems: embeddedListDef.maxItems,
+        }),
+        ...(embeddedListDef?.derived !== undefined && {
+          embeddedListDerived: embeddedListDef.derived,
+        }),
+        ...(embeddedListDef?.totals !== undefined && {
+          embeddedListTotals: embeddedListDef.totals,
+        }),
+        // ponytail: "EUR" mirrors DEFAULT_CURRENCIES[0] from
+        // framework/src/engine/field-helpers.ts — headless has no dependency
+        // on that module, so the literal is duplicated here instead of
+        // importing it just for one fallback string. Currency lives on the
+        // head aggregate (entity.defaultCurrency), not per row — one value
+        // for the whole embedded list.
+        ...(embeddedListDef !== undefined && {
+          embeddedListCurrency: entity.defaultCurrency ?? "EUR",
+        }),
       };
       return view;
     });

package/src/view-model/embedded-list.ts

@@ -0,0 +1,84 @@
+import type { FieldIssue } from "../dispatcher";
+
+export type EmbeddedDerivedOp = "multiply" | "sum" | "subtract";
+
+// Canonical implementation moved to packages/framework/src/engine/embedded-derived.ts
+// (the write-schema preprocess needs it server-side too).
+export { computeDerivedCellValue } from "@cosmicdrift/kumiko-framework/ui-types";
+
+/** Sums a numeric/money/decimal column across all rows. Non-numeric or
+ *  missing values count as 0. Money columns are minor-unit integers —
+ *  the sum stays in minor units, never rounds through a major-unit float. */
+export function sumEmbeddedListColumn(
+  rows: readonly Readonly<Record<string, unknown>>[],
+  field: string,
+): number {
+  let sum = 0;
+  for (const row of rows) {
+    const value = row[field];
+    if (typeof value === "number" && Number.isFinite(value)) sum += value;
+  }
+  return sum;
+}
+
+export type EmbeddedListIssueGroups = {
+  /** Issues at exactly `listField` — e.g. min/max row-count violations. */
+  readonly listIssues: readonly FieldIssue[];
+  /** Issues at exactly `${listField}.${rowIndex}` — a row-level check
+   *  (e.g. "row incomplete") that isn't attributable to one cell. */
+  readonly rowIssues: Readonly<Record<number, readonly FieldIssue[]>>;
+  /** Issues at exactly `${listField}.${rowIndex}.${cellField}`, keyed
+   *  `${rowIndex}.${cellField}` (not the full path — the caller already
+   *  knows listField). */
+  readonly cellIssues: Readonly<Record<string, readonly FieldIssue[]>>;
+};
+
+/** Buckets a flat issues-by-path map (FormSnapshot.errors shape — see
+ *  packages/headless/src/form/zod-bridge.ts groupIssuesByPath) into the
+ *  three levels an embedded-list widget renders. Only keys that are
+ *  exactly `listField`, `listField.N`, or `listField.N.subfield` are
+ *  claimed; unrelated keys (other top-level fields, or deeper nesting
+ *  than this field ever produces) are ignored. */
+export function groupEmbeddedListIssues(
+  allIssues: Readonly<Record<string, readonly FieldIssue[]>>,
+  listField: string,
+): EmbeddedListIssueGroups {
+  const listIssues: FieldIssue[] = [];
+  const rowIssues: Record<number, readonly FieldIssue[]> = {};
+  const cellIssues: Record<string, readonly FieldIssue[]> = {};
+
+  const prefix = `${listField}.`;
+  for (const [path, issues] of Object.entries(allIssues)) {
+    if (path === listField) {
+      listIssues.push(...issues);
+      continue;
+    }
+    if (!path.startsWith(prefix)) continue;
+    const rest = path.slice(prefix.length);
+    const segments = rest.split(".");
+    if (segments.length === 1) {
+      const rowIndex = parsePureRowIndex(segments[0]);
+      if (rowIndex === undefined) continue;
+      rowIssues[rowIndex] = issues;
+      continue;
+    }
+    if (segments.length === 2) {
+      const rowIndex = parsePureRowIndex(segments[0]);
+      if (rowIndex === undefined) continue;
+      const cellField = segments[1];
+      cellIssues[`${rowIndex}.${cellField}`] = issues;
+    }
+    // Deeper than `listField.N.subfield` — not a shape this field ever
+    // produces; ignore rather than misattribute to a cell.
+  }
+
+  return { listIssues, rowIssues, cellIssues };
+}
+
+function parsePureRowIndex(segment: string | undefined): number | undefined {
+  if (segment === undefined || segment.length === 0) return undefined;
+  for (const char of segment) {
+    if (char < "0" || char > "9") return undefined;
+  }
+  return Number(segment);
+}

package/src/view-model/index.ts

@@ -1,7 +1,18 @@
 export type { ComputeEditViewModelInput } from "./edit";
 export { computeEditViewModel } from "./edit";
+export type { EmbeddedDerivedOp, EmbeddedListIssueGroups } from "./embedded-list";
+export {
+  computeDerivedCellValue,
+  groupEmbeddedListIssues,
+  sumEmbeddedListColumn,
+} from "./embedded-list";
 export type { ComputeListViewModelInput } from "./list";
-export { computeListViewModel, fieldLabelKey } from "./list";
+export {
+  computeListViewModel,
+  embeddedCellLabelKey,
+  embeddedCellOptionLabelKey,
+  fieldLabelKey,
+} from "./list";
 export type {
   EditExtensionSectionViewModel,
   EditFieldSpec,
@@ -10,6 +21,7 @@ export type {
   EditSectionSpec,
   EditSectionViewModel,
   EditViewModel,
+  EmbeddedListCellViewModel,
   FieldConditionCtx,
   FieldRenderer,
   ListColumnSpec,

package/src/view-model/list.ts

@@ -103,9 +103,7 @@ export function computeListViewModel(input: ComputeListViewModelInput): ListView
       fieldDef.type === "select"
         ? buildOptionLabels(
             translate,
-            featureName,
-            screen.entity,
-            normalized.field,
+            (value) => fieldOptionLabelKey(featureName, screen.entity, normalized.field, value),
             (fieldDef as unknown as { options?: readonly string[] }).options ?? [],
           )
         : undefined;
@@ -155,6 +153,28 @@ export function fieldOptionLabelKey(
   return `${featureName}:entity:${entityName}:field:${fieldName}:option:${value}`;
 }
 
+// Embedded-list cell label key — one level deeper than fieldLabelKey,
+// keyed by the sub-field name inside an embedded-LIST field's `schema`
+// (invoice-positions-style tables built via createEmbeddedListField()).
+export function embeddedCellLabelKey(
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+  subFieldName: string,
+): string {
+  return `${featureName}:entity:${entityName}:field:${fieldName}:cell:${subFieldName}`;
+}
+
+export function embeddedCellOptionLabelKey(
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+  subFieldName: string,
+  value: string,
+): string {
+  return `${featureName}:entity:${entityName}:field:${fieldName}:cell:${subFieldName}:option:${value}`;
+}
+
 // Build a value→label map for a select-field's options. Convention:
 // translate() returns the input key when the lookup misses (i18next
 // default + LocaleResolver convention) — we surface the *raw value* in
@@ -162,18 +182,18 @@ export function fieldOptionLabelKey(
 // Without that fallback, an unlabeled option would render as the full
 // `feature:entity:field:option:value`-key.
 //
-// Shared between list-VM and edit-VM so both builders produce
-// identical option-translations.
+// `keyFor` carries whichever key convention the caller needs (top-level
+// field via fieldOptionLabelKey, embedded-list cell via
+// embeddedCellOptionLabelKey) — shared between list-VM, edit-VM, and
+// embedded-list cells so all three produce identical option-translations.
 export function buildOptionLabels(
   translate: (key: string, params?: Readonly<Record<string, unknown>>) => string,
-  featureName: string,
-  entityName: string,
-  fieldName: string,
+  keyFor: (value: string) => string,
   options: readonly string[],
 ): Readonly<Record<string, string>> {
   const out: Record<string, string> = {};
   for (const value of options) {
-    const key = fieldOptionLabelKey(featureName, entityName, fieldName, value);
+    const key = keyFor(value);
     const translated = translate(key);
     out[value] = translated === key ? value : translated;
   }

package/src/view-model/types.ts

@@ -75,6 +75,33 @@ export type ListViewModel = {
 
 // --- edit view model ---
 
+// Per-cell metadata for one sub-field of an embedded-LIST field
+// (`multiple: true`) — the column/cell shape a renderer needs to draw an
+// invoice-positions-style table. One entry per key of the source
+// EmbeddedFieldDef's `schema`.
+export type EmbeddedListCellViewModel = {
+  readonly field: string;
+  readonly label: string;
+  readonly type:
+    | "text"
+    | "number"
+    | "boolean"
+    | "date"
+    | "money"
+    | "decimal"
+    | "select"
+    | "reference"
+    | "timestamp";
+  readonly required: boolean;
+  /** Only for `type: "select"`. */
+  readonly options?: readonly string[];
+  readonly optionLabels?: Readonly<Record<string, string>>;
+  /** Only for `type: "reference"`. */
+  readonly refEntity?: string;
+  readonly refFeature?: string;
+  readonly refLabelField?: string;
+};
+
 // Resolved field — all predicates evaluated, labels translated. The
 // renderer reads `{ visible, readonly, required }` directly without
 // re-running any predicate.
@@ -148,6 +175,28 @@ export type EditFieldViewModel = {
    *  resolves it against the FIELD_ICONS registry; unknown keys silently
    *  fall back to "no icon". */
   readonly icon?: string;
+  /** Only set for an embedded-LIST field (`multiple: true`) — the per-cell
+   *  metadata the renderer needs to draw each column/cell. Absent for a
+   *  plain (non-list) embedded field. */
+  readonly embeddedListCells?: readonly EmbeddedListCellViewModel[];
+  /** Minimum row count for the embedded list. From EmbeddedFieldDef.minItems. */
+  readonly embeddedListMinItems?: number;
+  /** Maximum row count for the embedded list. From EmbeddedFieldDef.maxItems. */
+  readonly embeddedListMaxItems?: number;
+  /** Sub-field name → how to compute its cell from other sub-fields of the
+   *  same row. From EmbeddedFieldDef.derived. */
+  readonly embeddedListDerived?: Readonly<
+    Record<
+      string,
+      { readonly op: "multiply" | "sum" | "subtract"; readonly from: readonly string[] }
+    >
+  >;
+  /** Numeric sub-field names to sum in a totals row. From EmbeddedFieldDef.totals. */
+  readonly embeddedListTotals?: readonly string[];
+  /** Currency for the whole embedded list's money cells and totals row —
+   *  currency lives on the head aggregate (EntityDefinition.defaultCurrency),
+   *  not per row. Falls back to "EUR" when the entity has no defaultCurrency. */
+  readonly embeddedListCurrency?: string;
 };
 
 // Discriminated by `kind` — mirrors EditSectionSpec on the engine side.