@cosmicdrift/kumiko-headless 0.92.0 → 0.94.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.92.0",
+  "version": "0.94.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>",
@@ -32,7 +32,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.92.0",
+    "@cosmicdrift/kumiko-framework": "0.94.0",
     "zod": "^4.4.3"
   },
   "publishConfig": {

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

@@ -15,6 +15,13 @@ const taskEntity = {
     done: { type: "boolean" },
     priority: { type: "number", sortable: true },
   },
+  derivedFields: {
+    // Read-time computed (value appended by the list-query handler). The
+    // view-model only reads valueType; the derive body never runs here, so a
+    // no-op stand-in is enough.
+    statusLabel: { valueType: "text", derive: () => "" },
+    ageDays: { valueType: "number", derive: () => 0 },
+  },
 } as unknown as EntityDefinition;
 
 function listScreen(columns: EntityListScreenDefinition["columns"]): EntityListScreenDefinition {
@@ -125,6 +132,56 @@ describe("computeListViewModel", () => {
     expect(spy).toHaveBeenCalledWith("tasks:entity:task:field:priority");
   });
 
+  test("derived-field column carries its valueType, is display-only (never sortable), no stored-field metadata", () => {
+    const vm = computeListViewModel({
+      screen: listScreen(["statusLabel", "ageDays"]),
+      entity: taskEntity,
+      rows: [],
+      translate,
+      featureName: "tasks",
+    });
+
+    expect(vm.columns).toEqual([
+      {
+        field: "statusLabel",
+        label: "tasks:entity:task:field:statusLabel",
+        type: "text",
+        sortable: false,
+      },
+      {
+        field: "ageDays",
+        label: "tasks:entity:task:field:ageDays",
+        type: "number",
+        sortable: false,
+      },
+    ]);
+  });
+
+  test("derived column value passes through from the row (handler already appended it)", () => {
+    const vm = computeListViewModel({
+      screen: listScreen(["title", "statusLabel"]),
+      entity: taskEntity,
+      rows: [{ id: "t-1", title: "first", statusLabel: "overdue" }],
+      translate,
+      featureName: "tasks",
+    });
+
+    expect(vm.rows[0]?.values).toEqual({ id: "t-1", title: "first", statusLabel: "overdue" });
+  });
+
+  test("derived columns accept an object-form renderer like stored columns", () => {
+    const fmt = { format: "currency" as const, symbol: "€" };
+    const vm = computeListViewModel({
+      screen: listScreen([{ field: "ageDays", renderer: fmt }]),
+      entity: taskEntity,
+      rows: [],
+      translate,
+      featureName: "tasks",
+    });
+
+    expect(vm.columns[0]?.renderer).toEqual(fmt);
+  });
+
   test("slots pass through unchanged for the renderer to mount", () => {
     const slots = { header: { react: { component: "HeaderRef" } } };
     const vm = computeListViewModel({

package/src/view-model/list.ts

@@ -37,14 +37,30 @@ export function computeListViewModel(input: ComputeListViewModelInput): ListView
     const normalized = normalizeListColumn(spec);
     const fieldDef = entity.fields[normalized.field];
     if (!fieldDef) {
-      // Screen references a field that's not on the entity. Fail loud —
-      // the boot-validator (r.screen) should catch this, but a stale
-      // field-rename would leave the screen referring to a ghost column
-      // until ops re-runs boot. We throw so the renderer sees the error
-      // instead of drawing an empty column.
-      throw new Error(
-        `computeListViewModel: screen "${screen.id}" references unknown field "${normalized.field}" on entity "${screen.entity}"`,
-      );
+      // Not a stored field — may be a read-time derived field (value appended
+      // by the list-query handler). Render it as its display valueType; derived
+      // columns carry no reference/select metadata and never server-sort.
+      const derivedDef = entity.derivedFields?.[normalized.field];
+      if (!derivedDef) {
+        // Screen references a field that's neither stored nor derived. Fail
+        // loud — the boot-validator (r.screen) should catch this, but a stale
+        // field-rename would leave the screen referring to a ghost column
+        // until ops re-runs boot. We throw so the renderer sees the error
+        // instead of drawing an empty column.
+        throw new Error(
+          `computeListViewModel: screen "${screen.id}" references unknown field "${normalized.field}" on entity "${screen.entity}"`,
+        );
+      }
+      columns.push({
+        field: normalized.field,
+        label: translate(fieldLabelKey(featureName, screen.entity, normalized.field)),
+        type: derivedDef.valueType,
+        // Display-only: a header sort would round-trip to the server, which has
+        // no column to sort by (see DerivedFieldDef). Never offer the affordance.
+        sortable: false,
+        ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+      });
+      continue;
     }
     const label = translate(fieldLabelKey(featureName, screen.entity, normalized.field));
     // Tier 2.7e-3 + Cross-Feature: Reference-Field — entity-String