@cosmicdrift/kumiko-renderer 0.183.2 → 0.185.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.183.2",
+  "version": "0.185.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.183.2",
-    "@cosmicdrift/kumiko-headless": "0.183.2",
+    "@cosmicdrift/kumiko-framework": "0.185.0",
+    "@cosmicdrift/kumiko-headless": "0.185.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2"
   },

package/src/components/__tests__/embedded-list-field.test.tsx

@@ -0,0 +1,319 @@
+// EmbeddedListField Tests — RTL + happy-dom, style follows
+// render-field-app-locale.test.tsx: mount under real Locale/Dispatcher/
+// Primitives providers, capture the props the (mocked) EmbeddedListInput
+// primitive receives, then invoke its callbacks the way the real
+// primitive would (a user clicking/typing) and assert the resulting
+// onChange call.
+
+import { describe, expect, test } from "bun:test";
+import type { Dispatcher, EditFieldViewModel, FieldIssue } from "@cosmicdrift/kumiko-headless";
+import { render, waitFor } from "@testing-library/react";
+import type { ComponentType, ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
+import { kumikoDefaultTranslations } from "../../i18n-defaults";
+import {
+  type CorePrimitives,
+  type EmbeddedListInputProps,
+  PrimitivesProvider,
+} from "../../primitives";
+import { EmbeddedListField } from "../embedded-list-field";
+import { RenderField, type RenderFieldProps } from "../render-field";
+
+let captured: EmbeddedListInputProps | undefined;
+const captureEmbeddedListInput: ComponentType<EmbeddedListInputProps> = (props) => {
+  captured = props;
+  return null;
+};
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+function testPrimitives(): CorePrimitives {
+  return {
+    Button: noop,
+    Banner: noop,
+    Field: passChildren,
+    Input: noop,
+    EmbeddedListInput: captureEmbeddedListInput,
+    DataTable: noop,
+    Form: passChildren,
+    Section: passChildren,
+    Card: passChildren,
+    Grid: passChildren,
+    GridCell: passChildren,
+    Text: passChildren,
+    Heading: noop,
+    Dialog: noop,
+    Modal: noop,
+    Lightbox: noop,
+    ConfigSourceBadge: noop,
+    ConfigCascadeView: noop,
+    Link: noop,
+  };
+}
+
+type ProductRow = { readonly id: string; readonly name: string };
+
+function stubDispatcher(productRows: readonly ProductRow[] = []): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async (type: string) => {
+      if (type === "invoices:query:product:list") {
+        return { isSuccess: true, data: { rows: productRows } };
+      }
+      return { isSuccess: true, data: { rows: [] } };
+    }) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function invoiceLinesField(overrides: Partial<EditFieldViewModel> = {}): EditFieldViewModel {
+  return {
+    field: "lines",
+    label: "Lines",
+    type: "embedded",
+    value: [],
+    visible: true,
+    readOnly: false,
+    required: true,
+    embeddedListCells: [
+      {
+        field: "product",
+        label: "Product",
+        type: "reference",
+        required: true,
+        refEntity: "product",
+        refFeature: "invoices",
+        refLabelField: "name",
+      },
+      {
+        field: "unit",
+        label: "Unit",
+        type: "select",
+        required: true,
+        options: ["pcs", "hours", "kg"],
+      },
+      { field: "quantity", label: "Qty", type: "number", required: true },
+      { field: "unitPrice", label: "Unit Price", type: "money", required: true },
+      { field: "amount", label: "Amount", type: "money", required: false },
+    ],
+    embeddedListDerived: { amount: { op: "multiply", from: ["quantity", "unitPrice"] } },
+    embeddedListTotals: ["amount"],
+    embeddedListMinItems: 1,
+    embeddedListMaxItems: 5,
+    ...overrides,
+  };
+}
+
+function renderEmbeddedListField(
+  field: EditFieldViewModel,
+  onChange: (v: unknown) => void,
+  allIssues: Readonly<Record<string, readonly FieldIssue[]>> = {},
+  productRows: readonly ProductRow[] = [],
+): void {
+  captured = undefined;
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver()}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher(productRows)}>
+        <PrimitivesProvider value={testPrimitives()}>
+          <EmbeddedListField
+            field={field}
+            id="kumiko-edit-lines"
+            onChange={onChange}
+            allIssues={allIssues}
+            featureName="invoices"
+          />
+        </PrimitivesProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("EmbeddedListField — cell change recomputes derived", () => {
+  test("changing quantity updates the cell and recomputes amount in the same row", () => {
+    const rows = [{ product: "p1", unit: "pcs", quantity: 2, unitPrice: 500, amount: 1000 }];
+    let lastValue: unknown;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), (v) => {
+      lastValue = v;
+    });
+    captured?.onCellChange(0, "quantity", 4);
+    expect(lastValue).toEqual([
+      { product: "p1", unit: "pcs", quantity: 4, unitPrice: 500, amount: 2000 },
+    ]);
+  });
+});
+
+describe("EmbeddedListField — row operations", () => {
+  const rows = [
+    { product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 },
+    { product: "p2", unit: "hours", quantity: 2, unitPrice: 200, amount: 400 },
+  ];
+
+  test("onAddRow appends an empty row with derived recomputed", () => {
+    let lastValue: unknown;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), (v) => {
+      lastValue = v;
+    });
+    captured?.onAddRow();
+    expect(lastValue).toEqual([...rows, { amount: undefined }]);
+  });
+
+  test("onRemoveRow removes exactly the targeted row", () => {
+    let lastValue: unknown;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), (v) => {
+      lastValue = v;
+    });
+    captured?.onRemoveRow(0);
+    expect(lastValue).toEqual([rows[1]]);
+  });
+
+  test("onDuplicateRow inserts a copy right after the source row", () => {
+    let lastValue: unknown;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), (v) => {
+      lastValue = v;
+    });
+    captured?.onDuplicateRow(0);
+    expect(lastValue).toEqual([rows[0], rows[0], rows[1]]);
+  });
+
+  test("onDuplicateRow is a no-op for an out-of-range index", () => {
+    let called = false;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), () => {
+      called = true;
+    });
+    captured?.onDuplicateRow(99);
+    expect(called).toBe(false);
+  });
+
+  test("onMoveRow moves an element from one index to another, immutably", () => {
+    let lastValue: unknown;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), (v) => {
+      lastValue = v;
+    });
+    captured?.onMoveRow(1, 0);
+    expect(lastValue).toEqual([rows[1], rows[0]]);
+    // original array must stay untouched
+    expect(rows).toEqual([
+      { product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 },
+      { product: "p2", unit: "hours", quantity: 2, unitPrice: 200, amount: 400 },
+    ]);
+  });
+
+  test("onMoveRow is a no-op for an out-of-range target index", () => {
+    let called = false;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), () => {
+      called = true;
+    });
+    captured?.onMoveRow(0, 5);
+    expect(called).toBe(false);
+  });
+});
+
+describe("EmbeddedListField — paste coercion", () => {
+  test("pastes number/money/select cells with correct coercion per column type", () => {
+    const rows = [{ product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 }];
+    let lastValue: unknown;
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), (v) => {
+      lastValue = v;
+    });
+    // Columns in order: product, unit, quantity, unitPrice, amount.
+    // Paste starting at column index 1 ("unit") for row 0: unit, quantity, unitPrice.
+    captured?.onPasteCells?.(0, 1, [["hours", "3", "12,50"]]);
+    expect(lastValue).toEqual([
+      { product: "p1", unit: "hours", quantity: 3, unitPrice: 1250, amount: 3750 },
+    ]);
+  });
+
+  test("paste beyond the current rows appends new rows but never past maxItems", () => {
+    const rows = [{ product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 }];
+    let lastValue: unknown;
+    renderEmbeddedListField(invoiceLinesField({ value: rows, embeddedListMaxItems: 2 }), (v) => {
+      lastValue = v;
+    });
+    captured?.onPasteCells?.(0, 2, [
+      ["1", "100"],
+      ["2", "200"],
+      ["3", "300"],
+    ]);
+    const result = lastValue as readonly Record<string, unknown>[];
+    expect(result.length).toBe(2);
+  });
+});
+
+describe("EmbeddedListField — reference column populated via useQuery", () => {
+  test("referenceOptions come from the product list query", async () => {
+    renderEmbeddedListField(invoiceLinesField({ value: [] }), () => {}, {}, [
+      { id: "p1", name: "Widget A" },
+    ]);
+    await waitFor(() => {
+      const productColumn = captured?.columns.find((c) => c.field === "product");
+      expect(productColumn?.referenceOptions).toEqual([{ value: "p1", label: "Widget A" }]);
+    });
+  });
+});
+
+describe("EmbeddedListField — issue grouping wiring", () => {
+  test("a lines.0.amount issue is routed as a cellIssue at 0.amount", () => {
+    const rows = [{ product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 }];
+    const issue: FieldIssue = { path: "lines.0.amount", code: "custom", i18nKey: "Bad amount" };
+    renderEmbeddedListField(invoiceLinesField({ value: rows }), () => {}, {
+      "lines.0.amount": [issue],
+    });
+    expect(captured?.cellIssues?.["0.amount"]).toEqual([issue]);
+    expect(captured?.rowIssues ?? {}).toEqual({});
+    expect(captured?.listIssues ?? []).toEqual([]);
+  });
+
+  test("a lines-level issue is routed as a listIssue", () => {
+    const issue: FieldIssue = { path: "lines", code: "custom", i18nKey: "Too few lines" };
+    renderEmbeddedListField(invoiceLinesField({ value: [] }), () => {}, {
+      lines: [issue],
+    });
+    expect(captured?.listIssues).toEqual([issue]);
+  });
+});
+
+function renderFieldWithEmbeddedList(
+  field: EditFieldViewModel,
+  allIssues: RenderFieldProps["allIssues"],
+): void {
+  captured = undefined;
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver()}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <PrimitivesProvider value={testPrimitives()}>
+          <RenderField
+            field={field}
+            onChange={() => {}}
+            allIssues={allIssues}
+            featureName="invoices"
+          />
+        </PrimitivesProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("RenderField — routes embedded-list fields to EmbeddedListField (plumbing)", () => {
+  test("field.embeddedListCells set → RenderField mounts EmbeddedListField, allIssues propagate", () => {
+    const rows = [{ product: "p1", unit: "pcs", quantity: 1, unitPrice: 100, amount: 100 }];
+    const issue: FieldIssue = { path: "lines.0.amount", code: "custom", i18nKey: "Bad amount" };
+    renderFieldWithEmbeddedList(invoiceLinesField({ value: rows }), {
+      "lines.0.amount": [issue],
+    });
+    expect(captured?.cellIssues?.["0.amount"]).toEqual([issue]);
+  });
+});

package/src/components/embedded-list-field.tsx

@@ -0,0 +1,247 @@
+import type { EditFieldViewModel, FieldIssue } from "@cosmicdrift/kumiko-headless";
+import {
+  computeDerivedCellValue,
+  groupEmbeddedListIssues,
+  sumEmbeddedListColumn,
+} from "@cosmicdrift/kumiko-headless";
+import type { ReactNode } from "react";
+import { toKebab } from "../app/qn";
+import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits";
+import { useQuery } from "../hooks/use-query";
+import { useTranslation } from "../i18n";
+import type { EmbeddedListColumn, EmbeddedListTotal } from "../primitives";
+import { usePrimitives } from "../primitives";
+
+export type EmbeddedListFieldProps = {
+  readonly field: EditFieldViewModel;
+  readonly id: string;
+  readonly onChange: (value: unknown) => void;
+  readonly allIssues: Readonly<Record<string, readonly FieldIssue[]>>;
+  readonly featureName: string;
+};
+
+type EmbeddedRow = Readonly<Record<string, unknown>>;
+
+function withRecomputedDerived(
+  row: EmbeddedRow,
+  derived: EditFieldViewModel["embeddedListDerived"],
+): EmbeddedRow {
+  if (derived === undefined) return row;
+  const result: Record<string, unknown> = { ...row };
+  for (const [derivedField, def] of Object.entries(derived)) {
+    const values = def.from.map((src) => {
+      const v = result[src];
+      return typeof v === "number" ? v : undefined;
+    });
+    result[derivedField] = computeDerivedCellValue(def.op, values);
+  }
+  return result;
+}
+
+function coerceCellValue(column: EmbeddedListColumn, text: string): unknown {
+  switch (column.type) {
+    case "text":
+      return text;
+    case "number":
+    case "decimal": {
+      if (text.trim() === "") return undefined;
+      const n = Number(text);
+      return Number.isFinite(n) ? n : undefined;
+    }
+    case "money": {
+      // Money cells are minor-unit integers (cents) in storage — paste
+      // arrives as a major-unit decimal string ("12,99"/"12.99"), so ×100.
+      if (text.trim() === "") return undefined;
+      const n = Number(text.replace(",", "."));
+      return Number.isFinite(n) ? Math.round(n * 100) : undefined;
+    }
+    case "boolean":
+      return ["true", "1", "yes", "y", "ja"].includes(text.trim().toLowerCase());
+    case "date":
+    case "timestamp":
+      return text.trim();
+    case "select": {
+      const match = (column.options ?? []).find(
+        (opt) => opt === text || column.optionLabels?.[opt] === text,
+      );
+      return match;
+    }
+    case "reference": {
+      const match = (column.referenceOptions ?? []).find(
+        (o) => o.label === text || o.value === text,
+      );
+      return match?.value;
+    }
+    default: {
+      const exhaustiveCheck: never = column.type;
+      return exhaustiveCheck;
+    }
+  }
+}
+
+export function EmbeddedListField({
+  field,
+  id,
+  onChange,
+  allIssues,
+  featureName,
+}: EmbeddedListFieldProps): ReactNode {
+  const { EmbeddedListInput } = usePrimitives();
+  const t = useTranslation();
+
+  const cells = field.embeddedListCells ?? [];
+  const rows = Array.isArray(field.value) ? (field.value as readonly EmbeddedRow[]) : [];
+  const derived = field.embeddedListDerived;
+
+  const referenceCells = cells.filter((c) => c.type === "reference");
+  const referenceQueries = referenceCells.map((cell) => {
+    const refFeature = cell.refFeature ?? featureName;
+    const refEntity = cell.refEntity ?? "";
+    const qn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+    // biome-ignore lint/correctness/useHookAtTopLevel: referenceCells comes from the entity-schema definition — fixed for the screen's lifetime, not a real conditional-hook risk.
+    return useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(qn, {
+      limit: REFERENCE_COMBOBOX_LIMIT,
+    });
+  });
+
+  if (EmbeddedListInput === undefined) return null;
+
+  const columns: EmbeddedListColumn[] = cells.map((cell) => {
+    const isDerived = derived?.[cell.field] !== undefined;
+    if (cell.type === "reference") {
+      const idx = referenceCells.indexOf(cell);
+      const query = referenceQueries[idx];
+      const labelField = cell.refLabelField ?? "id";
+      const referenceOptions = (query?.data?.rows ?? []).map((row) => ({
+        value: String(row["id"] ?? ""),
+        label: String(row[labelField] ?? row["id"] ?? ""),
+      }));
+      return {
+        field: cell.field,
+        label: cell.label,
+        type: cell.type,
+        required: cell.required,
+        derived: isDerived,
+        referenceOptions,
+        referenceLoading: query?.loading ?? false,
+      };
+    }
+    return {
+      field: cell.field,
+      label: cell.label,
+      type: cell.type,
+      required: cell.required,
+      derived: isDerived,
+      ...(cell.options !== undefined && { options: cell.options }),
+      ...(cell.optionLabels !== undefined && { optionLabels: cell.optionLabels }),
+    };
+  });
+
+  const totals: EmbeddedListTotal[] = (field.embeddedListTotals ?? []).map((subFieldName) => {
+    const cell = cells.find((c) => c.field === subFieldName);
+    return {
+      field: subFieldName,
+      label: cell?.label ?? subFieldName,
+      value: sumEmbeddedListColumn(rows, subFieldName),
+    };
+  });
+
+  const { listIssues, rowIssues, cellIssues } = groupEmbeddedListIssues(allIssues, field.field);
+
+  function replaceRow(rowIndex: number, updater: (row: EmbeddedRow) => EmbeddedRow): void {
+    const nextRows = rows.map((row, i) => (i === rowIndex ? updater(row) : row));
+    onChange(nextRows);
+  }
+
+  function handleCellChange(rowIndex: number, cellField: string, value: unknown): void {
+    replaceRow(rowIndex, (row) => withRecomputedDerived({ ...row, [cellField]: value }, derived));
+  }
+
+  function handleAddRow(): void {
+    onChange([...rows, withRecomputedDerived({}, derived)]);
+  }
+
+  function handleRemoveRow(rowIndex: number): void {
+    onChange(rows.filter((_, i) => i !== rowIndex));
+  }
+
+  function handleDuplicateRow(rowIndex: number): void {
+    const source = rows[rowIndex];
+    if (source === undefined) return;
+    const next = [...rows];
+    next.splice(rowIndex + 1, 0, { ...source });
+    onChange(next);
+  }
+
+  function handleMoveRow(fromIndex: number, toIndex: number): void {
+    if (toIndex < 0 || toIndex >= rows.length) return;
+    const next = [...rows];
+    const [moved] = next.splice(fromIndex, 1);
+    if (moved === undefined) return;
+    next.splice(toIndex, 0, moved);
+    onChange(next);
+  }
+
+  function handlePasteCells(
+    rowIndex: number,
+    columnIndex: number,
+    grid: readonly (readonly string[])[],
+  ): void {
+    const maxItems = field.embeddedListMaxItems;
+    const nextRows = [...rows];
+    const touchedIndices = new Set<number>();
+
+    grid.forEach((gridRow, gridRowOffset) => {
+      const targetRowIndex = rowIndex + gridRowOffset;
+      if (targetRowIndex >= nextRows.length) {
+        if (maxItems !== undefined && nextRows.length >= maxItems) return;
+        nextRows.push({});
+      }
+      const targetRow = nextRows[targetRowIndex];
+      if (targetRow === undefined) return;
+      let updatedRow: Record<string, unknown> = { ...targetRow };
+      gridRow.forEach((text, gridColOffset) => {
+        const column = columns[columnIndex + gridColOffset];
+        if (column === undefined) return;
+        updatedRow = { ...updatedRow, [column.field]: coerceCellValue(column, text) };
+      });
+      nextRows[targetRowIndex] = updatedRow;
+      touchedIndices.add(targetRowIndex);
+    });
+
+    const recomputed = nextRows.map((row, i) =>
+      touchedIndices.has(i) ? withRecomputedDerived(row, derived) : row,
+    );
+    onChange(recomputed);
+  }
+
+  return (
+    <EmbeddedListInput
+      id={id}
+      columns={columns}
+      rows={rows}
+      totals={totals}
+      currency={field.embeddedListCurrency}
+      disabled={field.readOnly}
+      minItems={field.embeddedListMinItems}
+      maxItems={field.embeddedListMaxItems}
+      listIssues={listIssues}
+      rowIssues={rowIssues}
+      cellIssues={cellIssues}
+      onCellChange={handleCellChange}
+      onAddRow={handleAddRow}
+      onRemoveRow={handleRemoveRow}
+      onDuplicateRow={handleDuplicateRow}
+      onMoveRow={handleMoveRow}
+      onPasteCells={handlePasteCells}
+      addLabel={t("kumiko.field.embedded-list.add-row")}
+      removeLabel={t("kumiko.field.embedded-list.remove-row")}
+      duplicateLabel={t("kumiko.field.embedded-list.duplicate-row")}
+      moveUpLabel={t("kumiko.field.embedded-list.move-up")}
+      moveDownLabel={t("kumiko.field.embedded-list.move-down")}
+      emptyLabel={t("kumiko.field.embedded-list.empty")}
+      emptyCtaLabel={t("kumiko.field.embedded-list.empty-cta")}
+      testId={id}
+    />
+  );
+}

package/src/components/render-edit.tsx

@@ -468,6 +468,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
                     {...(fieldAppendix !== undefined && {
                       fieldAppendix: fieldAppendix(field.field),
                     })}
+                    allIssues={snapshot.errors}
                   />
                 ))}
               </Grid>
@@ -533,6 +534,9 @@ type GridCellForFieldProps = {
   readonly featureName: string;
   readonly labelAppendix?: ReactNode;
   readonly fieldAppendix?: ReactNode;
+  /** Full issues-by-path map (FormSnapshot.errors) — passed through for
+   *  embedded-list fields, which bucket row-/cell-level issues themselves. */
+  readonly allIssues: Readonly<Record<string, readonly FieldIssue[]>>;
 };
 
 function GridCellForField({
@@ -544,6 +548,7 @@ function GridCellForField({
   featureName,
   labelAppendix,
   fieldAppendix,
+  allIssues,
 }: GridCellForFieldProps): ReactNode {
   const effectiveSpan = field.span !== undefined ? Math.min(field.span, columns) : 1;
   return (
@@ -555,6 +560,7 @@ function GridCellForField({
         featureName={featureName}
         {...(labelAppendix !== undefined && { labelAppendix })}
         {...(fieldAppendix !== undefined && { fieldAppendix })}
+        allIssues={allIssues}
       />
     </GridCell>
   );

package/src/components/render-field.tsx

@@ -9,6 +9,7 @@ import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits";
 import { useQuery } from "../hooks/use-query";
 import { useLocale, useTranslation } from "../i18n";
 import { usePrimitives } from "../primitives";
+import { EmbeddedListField } from "./embedded-list-field";
 import { ReferenceCreateDialog } from "./reference-create-dialog";
 
 // RenderField übersetzt ein EditFieldViewModel → Primitives-Baum.
@@ -32,6 +33,11 @@ export type RenderFieldProps = {
   /** Optionaler Zusatz-Inhalt der nach dem Input gerendert wird (z.B.
    *  ConfigCascade). */
   readonly fieldAppendix?: ReactNode;
+  /** Flat issues-by-path map (FormSnapshot.errors) — only relevant for
+   *  type:"embedded" with embeddedListCells, to bucket row-/cell-issues
+   *  (`${field}.${rowIndex}` / `${field}.${rowIndex}.${cellField}`).
+   *  Other field types ignore this prop. */
+  readonly allIssues?: Readonly<Record<string, readonly FieldIssue[]>>;
 };
 
 export function RenderField({
@@ -41,6 +47,7 @@ export function RenderField({
   featureName,
   labelAppendix,
   fieldAppendix,
+  allIssues,
 }: RenderFieldProps): ReactNode {
   const { Field, Input } = usePrimitives();
   // App-Locale (i18n) für money/date-Inputs — sonst fielen sie auf
@@ -58,7 +65,15 @@ export function RenderField({
   // useQuery() für den Live-Lookup, also muss sie als React-
   // Komponente gemountet werden (nicht als pure render-Call).
   const control =
-    field.type === "reference" ? (
+    field.type === "embedded" && field.embeddedListCells !== undefined ? (
+      <EmbeddedListField
+        field={field}
+        id={id}
+        onChange={onChange}
+        allIssues={allIssues ?? {}}
+        featureName={featureName ?? ""}
+      />
+    ) : field.type === "reference" ? (
       <ReferenceInput
         field={field}
         id={id}

package/src/hooks/use-query.ts

@@ -43,7 +43,7 @@ export type UseQueryOptions = {
 // Extract the entity-name from a standard Kumiko query type. Returns
 // undefined for non-conforming types so the live-mode silently skips
 // them instead of subscribing to a channel no event will ever match.
-function entityFromQueryType(type: string): string | undefined {
+export function entityFromQueryType(type: string): string | undefined {
   // Expected shape: "<feature>:query:<entity>:<verb>"
   const parts = type.split(":");
   if (parts.length !== 4) return undefined;

package/src/i18n-defaults.ts

@@ -36,6 +36,13 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.field.locatedTzHint": "Zeit lokal am angegebenen Ort",
     "kumiko.field.reference-created-no-id":
       "Datensatz wurde angelegt, konnte aber nicht automatisch ausgewählt werden. Bitte manuell auswählen.",
+    "kumiko.field.embedded-list.add-row": "Zeile hinzufügen",
+    "kumiko.field.embedded-list.remove-row": "Zeile entfernen",
+    "kumiko.field.embedded-list.duplicate-row": "Zeile duplizieren",
+    "kumiko.field.embedded-list.move-up": "Nach oben verschieben",
+    "kumiko.field.embedded-list.move-down": "Nach unten verschieben",
+    "kumiko.field.embedded-list.empty": "Noch keine Zeilen.",
+    "kumiko.field.embedded-list.empty-cta": "Erste Zeile hinzufügen",
 
     // List — DataTable Toolbar, Empty-State, Search.
     "kumiko.list.search-placeholder": "Suchen…",
@@ -58,6 +65,11 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.widget.loading": "Lade…",
     "kumiko.widget.error.title": "Konnte nicht geladen werden.",
 
+    // Widgets — UploadZone Status-Zeile pro Datei.
+    "kumiko.widget.upload.uploading": "Wird hochgeladen…",
+    "kumiko.widget.upload.done": "Hochgeladen",
+    "kumiko.widget.upload.error": "Fehlgeschlagen",
+
     // Nav — Sidebar Tree (Toggle-aria-Labels).
     "kumiko.nav.expand": "Aufklappen",
     "kumiko.nav.collapse": "Zuklappen",
@@ -187,6 +199,13 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.field.locatedTzHint": "Time local to the given location",
     "kumiko.field.reference-created-no-id":
       "Record was created but could not be selected automatically. Please select it manually.",
+    "kumiko.field.embedded-list.add-row": "Add row",
+    "kumiko.field.embedded-list.remove-row": "Remove row",
+    "kumiko.field.embedded-list.duplicate-row": "Duplicate row",
+    "kumiko.field.embedded-list.move-up": "Move up",
+    "kumiko.field.embedded-list.move-down": "Move down",
+    "kumiko.field.embedded-list.empty": "No rows yet.",
+    "kumiko.field.embedded-list.empty-cta": "Add first row",
 
     "kumiko.list.search-placeholder": "Search…",
     "kumiko.list.empty.title": "No entries yet.",
@@ -204,6 +223,10 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.widget.loading": "Loading…",
     "kumiko.widget.error.title": "Couldn't load.",
 
+    "kumiko.widget.upload.uploading": "Uploading…",
+    "kumiko.widget.upload.done": "Uploaded",
+    "kumiko.widget.upload.error": "Failed",
+
     "kumiko.nav.expand": "Expand",
     "kumiko.nav.collapse": "Collapse",
     "kumiko.nav.search": "Search navigation…",

package/src/index.ts

@@ -115,7 +115,7 @@ export { useListUrlState } from "./hooks/use-list-url-state";
 export type { UseMutationResult } from "./hooks/use-mutation";
 export { useMutation } from "./hooks/use-mutation";
 export type { UseQueryOptions, UseQueryResult } from "./hooks/use-query";
-export { useQuery } from "./hooks/use-query";
+export { entityFromQueryType, useQuery } from "./hooks/use-query";
 export { useStore, useStoreSelector } from "./hooks/use-store";
 export type {
   StreamStatus,
@@ -153,6 +153,10 @@ export type {
   DataTableSort,
   DataTableSortDir,
   DialogProps,
+  EmbeddedListCellType,
+  EmbeddedListColumn,
+  EmbeddedListInputProps,
+  EmbeddedListTotal,
   FieldProps,
   FormProps,
   FormWidth,

package/src/primitives.tsx

@@ -15,6 +15,7 @@
 //   Field     — label + issues um ein Input-Control
 //   Input     — discriminated union über text/number/boolean/date
 //   DataTable — Spalten + Zeilen + onRowClick, Empty-State intern
+//   EmbeddedListInput — row array + totals table for createEmbeddedListField
 //   Form      — submit-Wrapper (Web: <form>, Native: View + onSubmit)
 //   Section   — titled Gruppe von Feldern (Web: <fieldset>+<legend>)
 //   Grid      — columns-basiertes Layout innerhalb einer Section
@@ -46,6 +47,7 @@ import {
   createContext,
   type FormEvent,
   type ReactNode,
+  type Ref,
   useContext,
 } from "react";
 
@@ -82,6 +84,13 @@ export type ButtonProps = {
   readonly width?: "full" | "auto";
   readonly children: ReactNode;
   readonly testId?: string;
+  /** Layout extras — Web merges via cn(), native impls ignore it
+   *  (precedent: LinkProps.className). */
+  readonly className?: string;
+  /** DOM ref on the button — escape hatch for cases that need more than
+   *  a click (e.g. binding a drop-target handler). Web forwards it, native
+   *  impls ignore it (no native equivalent). */
+  readonly ref?: Ref<HTMLButtonElement>;
 };
 
 /** Navigations-Link. `variant="button"` rendert die Button-Optik auf einem
@@ -533,6 +542,98 @@ export type DataTableProps = {
   readonly testId?: string;
 };
 
+// ---- EmbeddedListInput (createEmbeddedListField widget) ----
+
+/** Cell type for one column of an embedded-list field. Mirrors
+ *  EmbeddedListCellViewModel["type"] from `@cosmicdrift/kumiko-headless`. */
+export type EmbeddedListCellType =
+  | "text"
+  | "number"
+  | "boolean"
+  | "date"
+  | "money"
+  | "decimal"
+  | "select"
+  | "reference"
+  | "timestamp";
+
+/** One column of an embedded-list table (one entry per key of the source
+ *  EmbeddedFieldDef's `schema`). */
+export type EmbeddedListColumn = {
+  readonly field: string;
+  readonly label: string;
+  readonly type: EmbeddedListCellType;
+  readonly required: boolean;
+  /** Read-only, value supplied by the caller (already computed from
+   *  sibling cells) — not directly user-editable. */
+  readonly derived: boolean;
+  /** Only for `type: "select"`. */
+  readonly options?: readonly string[];
+  readonly optionLabels?: Readonly<Record<string, string>>;
+  /** Only for `type: "reference"` — pre-fetched by the caller, ONE query
+   *  per column shared across every row (not one query per cell). */
+  readonly referenceOptions?: readonly { readonly value: string; readonly label: string }[];
+  readonly referenceLoading?: boolean;
+};
+
+/** One entry of an embedded-list totals row (e.g. an invoice's total
+ *  amount, summed across all rows by the caller). */
+export type EmbeddedListTotal = {
+  readonly field: string;
+  readonly label: string;
+  readonly value: number;
+};
+
+/** Row-array + totals table for a `createEmbeddedListField` (invoice-
+ *  positions-style) field — structurally too different from `Input`'s
+ *  value/onChange union to fit there, so it's its own primitive, same as
+ *  `DataTable`. Controlled: the caller (the eventual form-field wrapper)
+ *  computes rows/derived values/issue groups and wires every callback;
+ *  this primitive only renders and reports interaction. */
+export type EmbeddedListInputProps = {
+  readonly id: string;
+  readonly columns: readonly EmbeddedListColumn[];
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly totals?: readonly EmbeddedListTotal[];
+  /** Currency for money cells and the totals row — one value for the whole
+   *  list (currency lives on the head aggregate, not the row). Web impl
+   *  falls back to "EUR" when absent. */
+  readonly currency?: string;
+  /** Whole-list read-only (e.g. a released invoice) — hides row-mutation
+   *  affordances and disables every cell. */
+  readonly disabled?: boolean;
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  /** Shown under the whole list (e.g. under the totals row). */
+  readonly listIssues?: readonly FieldIssue[];
+  /** Keyed by row index. */
+  readonly rowIssues?: Readonly<Record<number, readonly FieldIssue[]>>;
+  /** Keyed `${rowIndex}.${field}`. */
+  readonly cellIssues?: Readonly<Record<string, readonly FieldIssue[]>>;
+  readonly onCellChange: (rowIndex: number, field: string, value: unknown) => void;
+  readonly onAddRow: () => void;
+  readonly onRemoveRow: (rowIndex: number) => void;
+  readonly onDuplicateRow: (rowIndex: number) => void;
+  readonly onMoveRow: (fromIndex: number, toIndex: number) => void;
+  /** Tab/newline-delimited clipboard paste starting at (rowIndex,
+   *  columnIndex) — parsed to a 2D string grid by the Web impl (paste
+   *  events are a browser-only concept); undefined caller = no paste
+   *  handling wired up. */
+  readonly onPasteCells?: (
+    rowIndex: number,
+    columnIndex: number,
+    grid: readonly (readonly string[])[],
+  ) => void;
+  readonly addLabel: string;
+  readonly removeLabel: string;
+  readonly duplicateLabel: string;
+  readonly moveUpLabel: string;
+  readonly moveDownLabel: string;
+  readonly emptyLabel: string;
+  readonly emptyCtaLabel: string;
+  readonly testId?: string;
+};
+
 export type { FormWidth };
 
 /** Submit-Wrapper. Web: `<form onSubmit>`, Native: View das einen
@@ -750,6 +851,10 @@ export type CorePrimitives = {
   readonly Field: ComponentType<FieldProps>;
   readonly Input: ComponentType<InputProps>;
   readonly DataTable: ComponentType<DataTableProps>;
+  /** Optional (unlike the other Core-Primitives) so existing partial
+   *  CorePrimitives mocks in tests keep compiling — additive rollout of
+   *  a new primitive shouldn't force every test double to grow a stub. */
+  readonly EmbeddedListInput?: ComponentType<EmbeddedListInputProps>;
   readonly Form: ComponentType<FormProps>;
   readonly Section: ComponentType<SectionProps>;
   readonly Card: ComponentType<CardProps>;