@cosmicdrift/kumiko-headless 0.237.1 → 0.238.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.237.1",
+  "version": "0.238.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.237.1",
+    "@cosmicdrift/kumiko-framework": "0.238.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

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

@@ -676,3 +676,57 @@ describe("computeEditViewModel — multiSelect display/columns/maxRows passthrou
     expect(field?.maxRows).toBeUndefined();
   });
 });
+
+describe("computeEditViewModel — declared reference metadata (fw#2662)", () => {
+  // projectionDetail fields have no real EntityDefinition — the shim that
+  // adapts them synthesizes a pseudo-entity where every field is hardcoded
+  // to "text" (see projection-detail-shim.ts). EditFieldSpec.refEntity must
+  // be evaluated BEFORE the entity.fields lookup, or it never fires against
+  // that shape.
+  const projectionPseudoEntity = {
+    fields: {
+      userId: { type: "text" },
+      ip: { type: "text" },
+    },
+  } as unknown as EntityDefinition;
+
+  test("EditFieldSpec.refEntity marks the field as a reference, even against a pseudo-entity whose fields are all 'text' (fw#2662)", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({
+        sections: [
+          { fields: [{ field: "userId", refEntity: "user:user", refLabelField: "displayName" }] },
+        ],
+      }),
+      entity: projectionPseudoEntity,
+      values: { userId: "u-1" },
+      translate,
+      featureName: "sessions",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field).toMatchObject({
+      field: "userId",
+      type: "reference",
+      refEntity: "user",
+      refFeature: "user",
+      refLabelField: "displayName",
+    });
+    expect(field?.refMultiple).toBeUndefined();
+  });
+
+  test("non-regression: a projectionDetail field without refEntity metadata stays 'text', unchanged (fw#2662)", () => {
+    const vm = computeEditViewModel({
+      screen: editScreen({ sections: [{ fields: ["ip"] }] }),
+      entity: projectionPseudoEntity,
+      values: { ip: "10.0.0.1" },
+      translate,
+      featureName: "sessions",
+    });
+
+    const field = asFields(vm.sections[0]).fields[0];
+    expect(field?.type).toBe("text");
+    expect(field?.refEntity).toBeUndefined();
+    expect(field?.refFeature).toBeUndefined();
+    expect(field?.refLabelField).toBeUndefined();
+  });
+});

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

@@ -339,6 +339,62 @@ describe("computeListViewModel", () => {
     });
   });
 
+  // projectionList/relatedList columns have no real EntityDefinition — the
+  // shim that adapts them synthesizes a pseudo-entity where every field is
+  // hardcoded to "text" (see projection-list-shim.ts /
+  // related-list-section.tsx). ListColumnSpec.refEntity must be evaluated
+  // BEFORE the entity.fields lookup, or it never fires against that shape.
+  const projectionPseudoEntity = {
+    fields: {
+      tenantId: { type: "text" },
+      type: { type: "text" },
+    },
+  } as unknown as EntityDefinition;
+
+  test("ListColumnSpec.refEntity marks the column as a reference, even against a pseudo-entity whose fields are all 'text' (fw#2662)", () => {
+    const vm = computeListViewModel({
+      screen: listScreen([
+        {
+          field: "tenantId",
+          label: "delivery.log.col.tenantId",
+          refEntity: "tenant:tenant",
+          refLabelField: "name",
+        },
+      ]),
+      entity: projectionPseudoEntity,
+      rows: [],
+      translate,
+      featureName: "delivery",
+    });
+
+    expect(vm.columns[0]).toEqual({
+      field: "tenantId",
+      label: "delivery.log.col.tenantId",
+      type: "reference",
+      sortable: false,
+      refFeature: "tenant",
+      refEntity: "tenant",
+      refLabelField: "name",
+    });
+  });
+
+  test("non-regression: a projectionList column without refEntity metadata stays 'text', unchanged (fw#2662)", () => {
+    const vm = computeListViewModel({
+      screen: listScreen([{ field: "type", label: "delivery.log.col.type" }]),
+      entity: projectionPseudoEntity,
+      rows: [],
+      translate,
+      featureName: "delivery",
+    });
+
+    expect(vm.columns[0]).toEqual({
+      field: "type",
+      label: "delivery.log.col.type",
+      type: "text",
+      sortable: false,
+    });
+  });
+
   test("row-meta column: explicit label + renderer are passed through unchanged", () => {
     const fmt = { format: "currency" as const, symbol: "€" };
     const vm = computeListViewModel({

package/src/view-model/edit.ts

@@ -97,6 +97,18 @@ export function computeEditViewModel<
           `computeEditViewModel: screen "${screen.id}" references unknown field "${normalized.field}" on entity "${screen.entity}"`,
         );
       }
+      // Declared reference metadata (EditFieldSpec.refEntity) — for
+      // projectionDetail fields, which have no EntityDefinition field to
+      // carry a real "reference" type. Takes priority over fieldDef.type
+      // below so it also fires against the pseudo-entity that hardcodes
+      // every field as "text" (projection-detail-shim) — real entityEdit
+      // screens never set this, so their fieldDef.type === "reference"
+      // branch is unaffected.
+      const declaredRefTarget =
+        normalized.refEntity !== undefined
+          ? parseRefTarget(normalized.refEntity, featureName)
+          : undefined;
+      const effectiveType = declaredRefTarget !== undefined ? "reference" : fieldDef.type;
       const label = translate(
         screen.fieldLabels?.[normalized.field] ??
           fieldLabelKey(featureName, screen.entity, normalized.field),
@@ -160,26 +172,33 @@ export function computeEditViewModel<
       const min = dateBounds?.min;
       const max = dateBounds?.max;
       const dateLocale = dateBounds?.locale;
-      // Tier 2.7e-3: Reference-Field — refEntity + refLabelField in
-      // das ViewModel reichen damit der Renderer die Lookup-Query
-      // bauen kann ohne noch an EntityDefinition zu greifen.
-      // Tier 2.7e-3: Reference-Field — entity-String kann same-feature
-      // ("user") oder cross-feature ("users:user") sein. parseRefTarget
-      // splittet das, der Renderer baut die Lookup-QN aus
-      // (refFeature, refEntity).
+      // Tier 2.7e-3: Reference-Field — refEntity + refLabelField travel into
+      // the view model so the renderer can build the lookup query without
+      // touching the EntityDefinition again. The entity-string can be
+      // same-feature ("user") or cross-feature ("users:user"); parseRefTarget
+      // splits that, the renderer builds the lookup QN from
+      // (refFeature, refEntity). Declared metadata (declaredRefTarget) takes
+      // priority, same as effectiveType above.
       const refRaw =
-        fieldDef.type === "reference"
+        declaredRefTarget === undefined && fieldDef.type === "reference"
           ? (fieldDef as unknown as { entity?: string }).entity
           : undefined;
-      const refTarget = refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined;
+      const refTarget =
+        declaredRefTarget ??
+        (refRaw !== undefined ? parseRefTarget(refRaw, featureName) : undefined);
       const refEntity = refTarget?.entityName;
       const refFeature = refTarget?.featureName;
       const refLabelField =
-        fieldDef.type === "reference"
-          ? ((fieldDef as unknown as { labelField?: string }).labelField ?? "id")
-          : undefined;
+        declaredRefTarget !== undefined
+          ? (normalized.refLabelField ?? "id")
+          : fieldDef.type === "reference"
+            ? ((fieldDef as unknown as { labelField?: string }).labelField ?? "id")
+            : undefined;
+      // Declared reference metadata has no `multiple` concept (it targets
+      // row-meta/derived fields, always single-valued) — only a real
+      // ReferenceFieldDef carries it.
       const refMultiple =
-        fieldDef.type === "reference"
+        declaredRefTarget === undefined && fieldDef.type === "reference"
           ? ((fieldDef as unknown as { multiple?: boolean }).multiple ?? false)
           : undefined;
       // file/image: accept/maxSize ins ViewModel + entityType/fieldName für
@@ -272,7 +291,7 @@ export function computeEditViewModel<
       const view: EditFieldViewModel = {
         field: normalized.field,
         label,
-        type: fieldDef.type,
+        type: effectiveType,
         value: values[normalized.field],
         visible,
         readOnly,

package/src/view-model/list.ts

@@ -40,6 +40,31 @@ export function computeListViewModel(input: ComputeListViewModelInput): ListView
   const columns: ListColumnViewModel[] = [];
   for (const spec of screen.columns) {
     const normalized = normalizeListColumn(spec);
+    if (normalized.refEntity !== undefined) {
+      // Declared reference metadata (ListColumnSpec.refEntity) — for
+      // projectionList/relatedList columns, which have no EntityDefinition
+      // field to carry a real "reference" type. Checked before the
+      // entity.fields lookup below so it also fires against the pseudo-
+      // entities that hardcode every field as "text" (projection-list-shim,
+      // related-list-section) — those never reach the reference branch
+      // further down since fieldDef.type is always "text" there.
+      const refTarget = parseRefTarget(normalized.refEntity, featureName);
+      columns.push({
+        field: normalized.field,
+        label: translate(
+          normalized.label ?? fieldLabelKey(featureName, screen.entity, normalized.field),
+        ),
+        type: "reference",
+        // The declared value is the referenced id, not the resolved label —
+        // there is no column to server-sort by, same as row-meta references.
+        sortable: false,
+        refEntity: refTarget.entityName,
+        refFeature: refTarget.featureName,
+        refLabelField: normalized.refLabelField ?? "id",
+        ...(normalized.renderer !== undefined && { renderer: normalized.renderer }),
+      });
+      continue;
+    }
     const fieldDef = entity.fields[normalized.field];
     if (!fieldDef) {
       // Not a stored field — may be a read-time derived field (value appended