@cosmicdrift/kumiko-renderer 0.237.2 → 0.239.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.237.2",
+  "version": "0.239.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.237.2",
-    "@cosmicdrift/kumiko-headless": "0.237.2",
+    "@cosmicdrift/kumiko-framework": "0.239.0",
+    "@cosmicdrift/kumiko-headless": "0.239.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -27,7 +27,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.237.2"
+    "@cosmicdrift/kumiko-locale-de": "0.239.0"
   },
   "repository": {
     "type": "git",

package/src/app/__tests__/projection-detail-reference-field.test.tsx

@@ -0,0 +1,147 @@
+// fw#2662: projectionDetail fields have no EntityDefinition to carry a real
+// "reference" field type (the shim hardcodes every field as "text"), so a
+// declared reference field used to render the raw id. This renders the real
+// path (KumikoScreen -> ProjectionDetailScreen -> RenderEdit -> RenderField
+// -> ReadOnlyReferenceValue) under a stub dispatcher.
+
+import { describe, expect, test } from "bun:test";
+import type { ProjectionDetailScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher } 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, PrimitivesProvider, type TextProps } from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import type { NavApi } from "../nav";
+import { NavProvider } from "../nav";
+
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+// passChildren would drop testId — ReadOnlyReferenceValue/readOnlyDisplayText
+// render their resolved text into `<Text testId="field-value-<field>">`, and
+// the assertions below read it back by that testid.
+const TestText: ComponentType<TextProps> = ({ children, testId }) => (
+  <span data-testid={testId}>{children}</span>
+);
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: noop,
+  Form: passChildren,
+  Section: passChildren,
+  Card: passChildren,
+  Grid: passChildren,
+  GridCell: passChildren,
+  Text: TestText,
+  Heading: noop,
+  Dialog: noop,
+  Modal: noop,
+  Lightbox: noop,
+  ConfigSourceBadge: noop,
+  ConfigCascadeView: noop,
+  Link: noop,
+};
+
+function stubDispatcher(): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async (type: string) => {
+      if (type === "sessions:query:session:detail") {
+        return {
+          isSuccess: true,
+          data: { id: "sess-1", userId: "u-1", ip: "10.0.0.1" },
+        };
+      }
+      if (type === "user:query:user:list") {
+        return {
+          isSuccess: true,
+          data: { rows: [{ id: "u-1", displayName: "Jane Doe" }], nextCursor: null },
+        };
+      }
+      return { isSuccess: true, data: { rows: [], nextCursor: null } };
+    }) 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: () => [],
+  };
+}
+
+const detailScreen: ProjectionDetailScreenDefinition = {
+  id: "session-detail",
+  type: "projectionDetail",
+  query: "sessions:query:session:detail",
+  layout: {
+    sections: [
+      {
+        fields: [{ field: "userId", refEntity: "user:user", refLabelField: "displayName" }, "ip"],
+      },
+    ],
+  },
+};
+
+function buildSchema(): FeatureSchema {
+  return {
+    featureName: "sessions",
+    entities: {},
+    screens: [detailScreen],
+  } as FeatureSchema;
+}
+
+const staticNav: NavApi = {
+  route: { screenId: "sessions:screen:session-detail" },
+  navigate: () => {},
+  replace: () => {},
+  hrefFor: () => "",
+  searchParams: {},
+  setSearchParams: () => {},
+};
+
+function renderDetailScreen(): ReturnType<typeof render> {
+  return render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <NavProvider value={staticNav}>
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen
+              schema={buildSchema()}
+              qn="sessions:screen:session-detail"
+              entityId="sess-1"
+            />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("projectionDetail reference field resolves labels (fw#2662)", () => {
+  test("a field with refEntity metadata shows the resolved display name instead of the raw id", async () => {
+    const { getByTestId } = renderDetailScreen();
+
+    await waitFor(() => {
+      expect(getByTestId("field-value-userId").textContent).toBe("Jane Doe");
+    });
+  });
+
+  test("non-regression: a field without refEntity metadata renders its raw value unchanged", async () => {
+    const { getByTestId } = renderDetailScreen();
+
+    await waitFor(() => {
+      expect(getByTestId("field-value-ip").textContent).toBe("10.0.0.1");
+    });
+  });
+});

package/src/app/__tests__/projection-list-reference-column.test.tsx

@@ -0,0 +1,161 @@
+// fw#2662: projectionList columns have no EntityDefinition to carry a real
+// "reference" field type (the shim hardcodes every field as "text"), so a
+// declared reference column used to render the raw GUID. This renders the
+// real path (KumikoScreen -> ProjectionListScreen -> RenderList ->
+// useReferenceLookup) under a stub dispatcher, and reads the resolved cell
+// text back off the reference column's injected runtime renderer.
+
+import { describe, expect, test } from "bun:test";
+import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatcher, RuntimeRenderer } 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 DataTableProps, PrimitivesProvider } from "../../primitives";
+import type { FeatureSchema } from "../feature-schema";
+import { KumikoScreen } from "../kumiko-screen";
+import type { NavApi } from "../nav";
+import { NavProvider } from "../nav";
+
+const SYSTEM_TENANT_ID = "00000000-0000-4000-8000-000000000000";
+const REAL_TENANT_ID = "11111111-1111-4111-8111-111111111111";
+
+let capturedProps: DataTableProps | undefined;
+const captureDataTable: ComponentType<DataTableProps> = (props) => {
+  capturedProps = props;
+  return null;
+};
+const getCapturedProps = (): DataTableProps | undefined => capturedProps;
+const noop = (): ReactNode => null;
+const passChildren = ({ children }: { readonly children?: ReactNode }): ReactNode => children;
+
+const testPrimitives: CorePrimitives = {
+  Button: noop,
+  Banner: passChildren,
+  Field: passChildren,
+  Input: noop,
+  DataTable: captureDataTable,
+  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,
+};
+
+function stubDispatcher(): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async (type: string) => {
+      if (type === "delivery:query:log:list") {
+        return {
+          isSuccess: true,
+          data: {
+            rows: [
+              { id: "row-1", tenantId: REAL_TENANT_ID },
+              { id: "row-2", tenantId: SYSTEM_TENANT_ID },
+            ],
+            nextCursor: null,
+          },
+        };
+      }
+      if (type === "tenant:query:tenant:list") {
+        return {
+          isSuccess: true,
+          data: { rows: [{ id: REAL_TENANT_ID, name: "Acme Inc" }], nextCursor: null },
+        };
+      }
+      return { isSuccess: true, data: { rows: [], nextCursor: null } };
+    }) 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 buildSchema(screen: ProjectionListScreenDefinition): FeatureSchema {
+  return {
+    featureName: "delivery",
+    entities: {},
+    screens: [screen],
+  } as FeatureSchema;
+}
+
+const staticNav: NavApi = {
+  route: { screenId: "delivery:screen:log" },
+  navigate: () => {},
+  replace: () => {},
+  hrefFor: () => "",
+  searchParams: {},
+  setSearchParams: () => {},
+};
+
+function renderLogScreen(): void {
+  const screen: ProjectionListScreenDefinition = {
+    id: "log",
+    type: "projectionList",
+    query: "delivery:query:log:list",
+    columns: [
+      {
+        field: "tenantId",
+        label: "delivery.log.col.tenantId",
+        refEntity: "tenant:tenant",
+        refLabelField: "name",
+      },
+    ],
+  };
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <NavProvider value={staticNav}>
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen schema={buildSchema(screen)} qn="delivery:screen:log" />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+function referenceRenderer(): RuntimeRenderer {
+  const col = getCapturedProps()?.columns.find((c) => c.field === "tenantId");
+  if (typeof col?.renderer !== "function") throw new Error("reference column has no renderer yet");
+  return col.renderer as RuntimeRenderer;
+}
+
+describe("projectionList reference column resolves labels (fw#2662)", () => {
+  test("a real tenant id resolves to its name instead of the raw GUID", async () => {
+    capturedProps = undefined;
+    renderLogScreen();
+
+    await waitFor(() => {
+      expect(referenceRenderer()(REAL_TENANT_ID, { tenantId: REAL_TENANT_ID })).toBe("Acme Inc");
+    });
+  });
+
+  test("SYSTEM_TENANT_ID resolves to the system label instead of the raw GUID", async () => {
+    capturedProps = undefined;
+    renderLogScreen();
+
+    await waitFor(() => {
+      expect(referenceRenderer()(SYSTEM_TENANT_ID, { tenantId: SYSTEM_TENANT_ID })).toBe("System");
+    });
+  });
+});

package/src/components/render-field.tsx

@@ -3,6 +3,7 @@ import {
   type FieldIconKey,
   type FieldRenderer,
   isFormatSpec,
+  SYSTEM_REFERENCE_LABELS,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import {
   applyFormatSpec,
@@ -403,6 +404,7 @@ function ReadOnlyReferenceValue({
   readonly featureName: string;
 }): ReactNode {
   const { Text } = usePrimitives();
+  const t = useTranslation();
   const refEntity = field.refEntity ?? "";
   const refFeature = field.refFeature ?? featureName;
   const labelField = field.refLabelField ?? "id";
@@ -420,7 +422,13 @@ function ReadOnlyReferenceValue({
       : [];
   if (ids.length === 0) return <Text testId={`field-value-${field.field}`}>—</Text>;
   const rows = queryResult.data?.rows ?? [];
+  // System-scope ids (e.g. SYSTEM_TENANT_ID) never have a backing row —
+  // same central fallback as useReferenceLookup (render-list.tsx), so a
+  // reference field showing one on the detail path also gets a label
+  // instead of the raw id.
+  const systemLabel = SYSTEM_REFERENCE_LABELS[`${refFeature}:${refEntity}`];
   const labels = ids.map((id) => {
+    if (systemLabel !== undefined && id === systemLabel.id) return t(systemLabel.labelKey);
     const row = rows.find((r) => String(r["id"] ?? "") === id);
     return row !== undefined ? String(row[labelField] ?? id) : id;
   });

package/src/hooks/use-reference-lookup.ts

@@ -17,8 +17,10 @@
 // internen Cache shared zwischen List + Edit-Form für die gleiche
 // Entity, Live-Updates kommen via SSE (use-query-live).
 
+import { SYSTEM_REFERENCE_LABELS } from "@cosmicdrift/kumiko-framework/ui-types";
 import { useMemo } from "react";
 import { toKebab } from "../app/qn";
+import { useTranslation } from "../i18n";
 import { REFERENCE_LIST_LOOKUP_LIMIT } from "./reference-limits";
 import { useQuery } from "./use-query";
 
@@ -40,6 +42,8 @@ export function useReferenceLookup(
   const result = useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(queryQn, {
     limit: REFERENCE_LIST_LOOKUP_LIMIT,
   });
+  const translate = useTranslation();
+  const systemLabel = SYSTEM_REFERENCE_LABELS[`${featureName}:${refEntity}`];
   const map = useMemo(() => {
     const out = new Map<string, string>();
     for (const row of result.data?.rows ?? []) {
@@ -49,7 +53,10 @@ export function useReferenceLookup(
       const label = row[labelField] ?? id;
       out.set(idStr, String(label));
     }
+    // System-scope ids (e.g. SYSTEM_TENANT_ID) never have a backing row, so
+    // the bulk lookup above never covers them — inject the label directly.
+    if (systemLabel !== undefined) out.set(systemLabel.id, translate(systemLabel.labelKey));
     return out;
-  }, [result.data, labelField]);
+  }, [result.data, labelField, systemLabel, translate]);
   return { map, loading: result.loading };
 }

package/src/i18n-defaults.ts

@@ -64,6 +64,7 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.list.end-of-list": "— End of list —",
     "kumiko.list.sort.label": "Sort",
     "kumiko.list.sort.unsorted": "Unsorted",
+    "kumiko.reference.system-tenant": "System",
 
     "kumiko.pager.status": "{from}–{to} of {total}",
     "kumiko.pager.previousPage": "Previous page",