@cosmicdrift/kumiko-renderer 0.400.0 → 0.401.0

package/dist/components/use-reference-column-lookups.d.ts

@@ -0,0 +1,6 @@
+import { type PublishedReferenceChunk, type PublishedReferenceLookup, type ReferenceColumnSpec, type ReferenceLookupRequest } from "./render-list-reference-columns.ts";
+export declare function useReferenceColumnLookups(rows: readonly Readonly<Record<string, unknown>>[], referenceColumns: readonly ReferenceColumnSpec[]): {
+    referenceRequests: readonly ReferenceLookupRequest[];
+    handleLookupMap: (field: string, chunkIndex: number, lookup: PublishedReferenceChunk) => void;
+    referenceLookups: Record<string, PublishedReferenceLookup>;
+};

package/dist/components/use-reference-column-lookups.js

@@ -0,0 +1,36 @@
+import { useCallback, useMemo, useState } from "react";
+import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
+import { mergeChunkLookups, referenceIdChunks, } from "./render-list-reference-columns.js";
+// Bridge components (renderReferenceLookupBridges) publish each id chunk's
+// lookup through handleLookupMap; the merged result feeds enrichReferenceColumns.
+export function useReferenceColumnLookups(rows, referenceColumns) {
+    const referenceRequests = useMemo(() => referenceColumns.map((column) => ({
+        ...column,
+        idChunks: referenceIdChunks(rows, column.field, REFERENCE_LIST_LOOKUP_LIMIT),
+    })), [referenceColumns, rows]);
+    const [chunkLookups, setChunkLookups] = useState({});
+    const handleLookupMap = useCallback((field, chunkIndex, lookup) => {
+        setChunkLookups((prev) => {
+            // Skip the update when the lookup is identical. Otherwise the bridge
+            // would re-render and send the same map back until React entered
+            // an infinite loop.
+            const current = prev[field]?.[chunkIndex];
+            const unchanged = current?.map === lookup.map &&
+                current.complete === lookup.complete &&
+                current.idsKey === lookup.idsKey;
+            if (unchanged)
+                return prev;
+            return { ...prev, [field]: { ...prev[field], [chunkIndex]: lookup } };
+        });
+    }, []);
+    const referenceLookups = useMemo(() => {
+        const merged = {};
+        for (const request of referenceRequests) {
+            const lookup = mergeChunkLookups(request.idChunks, chunkLookups[request.field]);
+            if (lookup !== undefined)
+                merged[request.field] = lookup;
+        }
+        return merged;
+    }, [referenceRequests, chunkLookups]);
+    return { referenceRequests, handleLookupMap, referenceLookups };
+}

package/dist/components/use-render-list-columns.d.ts

@@ -1,7 +1,6 @@
 import type { EntityDefinition, EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import { type ScreenLinkResolver } from "../app/reference-link.ts";
 import type { ListColumnViewModel, ListViewModel, Translate } from "../headless/index.ts";
-import { type PublishedReferenceChunk, type ReferenceLookupRequest } from "./render-list-reference-columns.ts";
 export declare function withScreenLinks(columns: readonly ListColumnViewModel[], screen: EntityListScreenDefinition, resolveScreenLink: ScreenLinkResolver): readonly ListColumnViewModel[];
 type RenderListColumnsInput = {
     readonly screen: EntityListScreenDefinition;
@@ -11,8 +10,8 @@ type RenderListColumnsInput = {
     readonly translate: Translate;
 };
 export declare function useRenderListColumns(input: RenderListColumnsInput): {
-    referenceRequests: readonly ReferenceLookupRequest[];
-    handleLookupMap: (field: string, chunkIndex: number, lookup: PublishedReferenceChunk) => void;
+    referenceRequests: readonly import("./render-list-reference-columns.ts").ReferenceLookupRequest[];
+    handleLookupMap: (field: string, chunkIndex: number, lookup: import("./render-list-reference-columns.ts").PublishedReferenceChunk) => void;
     enrichedVm: Omit<ListViewModel, "columns"> & {
         columns: readonly ListColumnViewModel[];
     };

package/dist/components/use-render-list-columns.js

@@ -1,9 +1,9 @@
 import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
-import { useCallback, useMemo, useState } from "react";
+import { useMemo } from "react";
 import { useReferenceLinkResolver, useScreenLinkResolver, } from "../app/reference-link.js";
 import { computeListViewModel } from "../headless/index.js";
-import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
-import { enrichReferenceColumns, mergeChunkLookups, referenceIdChunks, selectReferenceColumns, } from "./render-list-reference-columns.js";
+import { enrichReferenceColumns, selectReferenceColumns } from "./render-list-reference-columns.js";
+import { useReferenceColumnLookups } from "./use-reference-column-lookups.js";
 // A column whose rows name their own target screen links each cell there.
 export function withScreenLinks(columns, screen, resolveScreenLink) {
     const linkFields = new Map();
@@ -38,34 +38,7 @@ export function useRenderListColumns(input) {
     // through onMap. Each bridge makes a constant number of hook calls (one),
     // and React manages its lifecycle when the schema changes via key.
     const referenceColumns = useMemo(() => selectReferenceColumns(vm.columns, featureName), [vm.columns, featureName]);
-    const referenceRequests = useMemo(() => referenceColumns.map((column) => ({
-        ...column,
-        idChunks: referenceIdChunks(rows, column.field, REFERENCE_LIST_LOOKUP_LIMIT),
-    })), [referenceColumns, rows]);
-    const [chunkLookups, setChunkLookups] = useState({});
-    const handleLookupMap = useCallback((field, chunkIndex, lookup) => {
-        setChunkLookups((prev) => {
-            // Skip the update when the lookup is identical. Otherwise the bridge
-            // would re-render and send the same map back until React entered
-            // an infinite loop.
-            const current = prev[field]?.[chunkIndex];
-            const unchanged = current?.map === lookup.map &&
-                current.complete === lookup.complete &&
-                current.idsKey === lookup.idsKey;
-            if (unchanged)
-                return prev;
-            return { ...prev, [field]: { ...prev[field], [chunkIndex]: lookup } };
-        });
-    }, []);
-    const referenceLookups = useMemo(() => {
-        const merged = {};
-        for (const request of referenceRequests) {
-            const lookup = mergeChunkLookups(request.idChunks, chunkLookups[request.field]);
-            if (lookup !== undefined)
-                merged[request.field] = lookup;
-        }
-        return merged;
-    }, [referenceRequests, chunkLookups]);
+    const { referenceRequests, handleLookupMap, referenceLookups } = useReferenceColumnLookups(rows, referenceColumns);
     const resolveReferenceLink = useReferenceLinkResolver();
     const resolveScreenLink = useScreenLinkResolver();
     const enrichedColumns = useMemo(() => withScreenLinks(enrichReferenceColumns({

package/dist/web/app/dashboard-body.js

@@ -16,7 +16,7 @@ function panelSpanClassName(panel) {
         return HALF_PANEL;
     return WIDE_PANEL;
 }
-function PanelBody({ panel, label, screenId, screenParams, translate, }) {
+function PanelBody({ panel, label, featureName, screenId, screenParams, translate, }) {
     if (panel.kind === "stat-group") {
         return (_jsx(StatGroupPanelBody, { panel: panel, label: label, screenId: screenId, screenParams: screenParams, translate: translate }));
     }
@@ -36,7 +36,7 @@ function PanelBody({ panel, label, screenId, screenParams, translate, }) {
         return (_jsx(ChartPanelBody, { panel: panel, label: text, screenParams: screenParams, translate: translate }));
     }
     if (panel.kind === "list") {
-        return (_jsx(ListPanelBody, { panel: panel, label: text, screenParams: screenParams, translate: translate }));
+        return (_jsx(ListPanelBody, { panel: panel, label: text, featureName: featureName, screenParams: screenParams, translate: translate }));
     }
     if (panel.kind === "feed") {
         return (_jsx(FeedPanelBody, { panel: panel, label: text, screenParams: screenParams, translate: translate }));
@@ -51,7 +51,7 @@ function renderDashboardPanel(panel, featureName, screenId, screenParams, transl
         return (_jsx(ScreenPanelTile, { panel: panel, featureName: featureName, recordId: screenParams.recordId, translate: translate }, panel.id));
     }
     const label = panel.kind === "custom" || panel.label === undefined ? undefined : translate(panel.label);
-    return (_jsx(GatedGridCell, { panel: panel, screenParams: screenParams, label: label ?? panel.id, className: panelSpanClassName(panel), children: _jsx(PanelBody, { panel: panel, label: label, screenId: screenId, screenParams: screenParams, translate: translate }) }, panel.id));
+    return (_jsx(GatedGridCell, { panel: panel, screenParams: screenParams, label: label ?? panel.id, className: panelSpanClassName(panel), children: _jsx(PanelBody, { panel: panel, label: label, featureName: featureName, screenId: screenId, screenParams: screenParams, translate: translate }) }, panel.id));
 }
 export function WebDashboardBody({ featureName, screen, translate, }) {
     const t = useTranslation();

package/dist/web/app/dashboard-panels.d.ts

@@ -23,9 +23,10 @@ export declare function ChartPanelBody({ panel, label, screenParams, translate,
     readonly screenParams: ScreenParams;
     readonly translate: Translate;
 }): ReactNode;
-export declare function ListPanelBody({ panel, label, screenParams, translate, }: {
+export declare function ListPanelBody({ panel, label, featureName, screenParams, translate, }: {
     readonly panel: DashboardListPanel;
     readonly label: string;
+    readonly featureName: string;
     readonly screenParams: ScreenParams;
     readonly translate: Translate;
 }): ReactNode;

package/dist/web/app/dashboard-panels.js

@@ -8,13 +8,13 @@ import { EMPTY_VALUE_PLACEHOLDER } from "../../headless/index.js";
 import { extensionSectionName, lastSegment, useExtensionSectionComponent, useNav, usePrimitives, useTranslation, useUserRoles, } from "../../index.js";
 import { initialWindowSelection, } from "../widgets/chart-window.js";
 import { chartToneColor, SegmentBarChart, StackedAreaChart, StackedBarChart, TimeseriesChart, } from "../widgets/charts.js";
-import { DashboardListTable } from "../widgets/dashboard-list.js";
 import { FeedList } from "../widgets/feed-list.js";
 import { ModeSwitch } from "../widgets/mode-switch.js";
 import { ProgressList } from "../widgets/progress-list.js";
 import { SectionCard } from "../widgets/section-card.js";
 import { STAT_CARD_GRID_CLASSES, StatCard, StatStripCell, } from "../widgets/stat.js";
 import { EmptyState, LoadingState } from "../widgets/states.js";
+import { DashboardReferenceListTable } from "./dashboard-reference-list-table.js";
 import { DAY_MS, HOUR_MS, PanelError, PanelShell, panelPayload, QueryPanel, useDashboardFormats, useDashboardQuery, useReportPanelLoaded, } from "./dashboard-shared.js";
 import { isRecord, resolveDashboardText } from "./dashboard-text.js";
 function isSparkPoint(value) {
@@ -222,7 +222,7 @@ export function ChartPanelBody({ panel, label, screenParams, translate, }) {
                 }), ariaLabel: label, testId: testId }));
         } }));
 }
-export function ListPanelBody({ panel, label, screenParams, translate, }) {
+export function ListPanelBody({ panel, label, featureName, screenParams, translate, }) {
     const { formatPercent, formatNumber, formatDateTime } = useDashboardFormats();
     const columns = panel.columns.map((c) => {
         const normalized = normalizeListColumn(c);
@@ -233,9 +233,17 @@ export function ListPanelBody({ panel, label, screenParams, translate, }) {
             ...(normalized.badgeToneField !== undefined && {
                 badgeToneField: normalized.badgeToneField,
             }),
+            ...(normalized.refEntity !== undefined && {
+                reference: {
+                    refEntity: normalized.refEntity,
+                    ...(normalized.refLabelField !== undefined && {
+                        refLabelField: normalized.refLabelField,
+                    }),
+                },
+            }),
         };
     });
-    return (_jsx(QueryPanel, { panel: panel, label: label, screenParams: screenParams, translate: translate, skeleton: "rows", isEmpty: (data) => (data.rows ?? []).length === 0, children: (data) => (_jsx(DashboardListTable, { columns: columns, rows: data.rows ?? [], formatPercent: formatPercent, formatNumber: formatNumber, formatDateTime: formatDateTime, translate: translate })) }));
+    return (_jsx(QueryPanel, { panel: panel, label: label, screenParams: screenParams, translate: translate, skeleton: "rows", isEmpty: (data) => (data.rows ?? []).length === 0, children: (data) => (_jsx(DashboardReferenceListTable, { columns: columns, rows: data.rows ?? [], featureName: featureName, formatPercent: formatPercent, formatNumber: formatNumber, formatDateTime: formatDateTime, translate: translate })) }));
 }
 export function FeedPanelBody({ panel, label, screenParams, translate, }) {
     return (_jsx(QueryPanel, { panel: panel, label: label, screenParams: screenParams, translate: translate, skeleton: "rows", isEmpty: (data) => (data.rows ?? []).length === 0, children: (data, formats) => {

package/dist/web/app/dashboard-reference-list-table.d.ts

@@ -0,0 +1,17 @@
+import { type ComponentProps, type ReactNode } from "react";
+import type { Translate } from "../../headless/index.ts";
+import { type DashboardListColumn, DashboardListTable } from "../widgets/dashboard-list.tsx";
+export type DashboardReferenceTarget = {
+    readonly refEntity: string;
+    readonly refLabelField?: string;
+};
+export type DashboardListTableColumn = DashboardListColumn & {
+    readonly reference?: DashboardReferenceTarget;
+};
+type Props = Omit<ComponentProps<typeof DashboardListTable>, "columns"> & {
+    readonly columns: readonly DashboardListTableColumn[];
+    readonly featureName: string;
+    readonly translate: Translate;
+};
+export declare function DashboardReferenceListTable({ columns, rows, featureName, translate, ...tableProps }: Props): ReactNode;
+export {};

package/dist/web/app/dashboard-reference-list-table.js

@@ -0,0 +1,47 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
+import { useMemo } from "react";
+import { useReferenceLinkResolver } from "../../app/reference-link.js";
+import { renderReferenceLookupBridges } from "../../components/render-list-reference-bridge.js";
+import { enrichReferenceColumns, selectReferenceColumns, } from "../../components/render-list-reference-columns.js";
+import { useReferenceColumnLookups } from "../../components/use-reference-column-lookups.js";
+import { DashboardListTable } from "../widgets/dashboard-list.js";
+function toReferenceViewColumn(column, featureName) {
+    if (column.reference === undefined)
+        return undefined;
+    const target = parseRefTarget(column.reference.refEntity, featureName);
+    return {
+        field: column.field,
+        label: column.label,
+        type: "reference",
+        sortable: false,
+        refEntity: target.entityName,
+        refFeature: target.featureName,
+        refLabelField: column.reference.refLabelField ?? "id",
+    };
+}
+// Dashboard list rows carry raw ids; reference columns resolve them to the target's label
+// the way entity lists do.
+export function DashboardReferenceListTable({ columns, rows, featureName, translate, ...tableProps }) {
+    const viewColumns = useMemo(() => columns.flatMap((column) => {
+        const viewColumn = toReferenceViewColumn(column, featureName);
+        return viewColumn === undefined ? [] : [viewColumn];
+    }), [columns, featureName]);
+    const referenceColumns = useMemo(() => selectReferenceColumns(viewColumns, featureName), [viewColumns, featureName]);
+    const { referenceRequests, handleLookupMap, referenceLookups } = useReferenceColumnLookups(rows, referenceColumns);
+    const resolveReferenceLink = useReferenceLinkResolver();
+    const enriched = useMemo(() => enrichReferenceColumns({
+        columns: viewColumns,
+        referenceColumns,
+        referenceLookups,
+        resolveReferenceLink,
+        featureName,
+        translate,
+    }), [viewColumns, referenceColumns, referenceLookups, resolveReferenceLink, featureName, translate]);
+    const tableColumns = columns.map((column) => {
+        const renderer = enriched.find((c) => c.field === column.field)?.renderer;
+        const { reference: _reference, ...base } = column;
+        return typeof renderer === "function" ? { ...base, renderValue: renderer } : base;
+    });
+    return (_jsxs(_Fragment, { children: [renderReferenceLookupBridges(referenceRequests, handleLookupMap), _jsx(DashboardListTable, { columns: tableColumns, rows: rows, translate: translate, ...tableProps })] }));
+}

package/dist/web/widgets/dashboard-list.d.ts

@@ -5,6 +5,8 @@ export type DashboardListColumn = {
     readonly label: string;
     readonly display?: "bar" | "badge" | "datetime";
     readonly badgeToneField?: string;
+    /** Resolves the raw cell value to display text, e.g. a reference id to its label. */
+    readonly renderValue?: (value: unknown, row: Readonly<Record<string, unknown>>) => string;
 };
 type Row = Readonly<Record<string, unknown>>;
 /** Compact 40px-row table for dashboard lists with optional bar/badge

package/dist/web/widgets/dashboard-list.js

@@ -31,6 +31,8 @@ function Cell({ column, row, formatPercent, formatNumber, formatDateTime, transl
             return EMPTY_VALUE_PLACEHOLDER;
         return _jsx("span", { className: "tabular-nums", children: formatDateTime(atMs) });
     }
+    if (column.renderValue !== undefined)
+        return column.renderValue(raw, row);
     if (typeof raw === "number")
         return _jsx("span", { className: "tabular-nums", children: formatNumber(raw) });
     if (raw === undefined || raw === null || raw === "")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.400.0",
+  "version": "0.401.0",
   "description": "React renderer for Kumiko screens. The root export holds the platform-agnostic logic (primitives contract, hooks, KumikoScreen, navigation and SSE abstractions); ./headless the DOM-free UI logic, ./live the HTTP dispatcher, ./web the browser bindings (HTML primitives, history navigation, EventSource live events, createKumikoApp).",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -48,8 +48,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.400.0",
-    "@cosmicdrift/kumiko-types": "0.400.0",
+    "@cosmicdrift/kumiko-framework": "0.401.0",
+    "@cosmicdrift/kumiko-types": "0.401.0",
     "@types/qrcode": "^1.5.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -79,8 +79,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-locale-de": "0.400.0",
-    "@cosmicdrift/kumiko-testing": "0.400.0",
+    "@cosmicdrift/kumiko-locale-de": "0.401.0",
+    "@cosmicdrift/kumiko-testing": "0.401.0",
     "@tailwindcss/cli": "^4.3.3",
     "@testing-library/react": "^16.3.3",
     "@testing-library/user-event": "^14.6.8",

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.401.0",
+    "type": "fix",
+    "title": "Dashboard list panels show the target's label for reference columns",
+    "detail": "A reference column in a dashboard list panel showed the stored id. It now resolves the target record's label and links to it, using the same lookup as entity lists."
+  },
   {
     "version": "0.399.0",
     "type": "improvement",