@cosmicdrift/kumiko-renderer 0.389.0 → 0.390.1

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

@@ -0,0 +1,18 @@
+import type { EntityDefinition, EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ListColumnViewModel, ListViewModel, Translate } from "../headless/index.ts";
+import { type PublishedReferenceLookup } from "./render-list-reference-columns.ts";
+type RenderListColumnsInput = {
+    readonly screen: EntityListScreenDefinition;
+    readonly entity: Pick<EntityDefinition, "fields" | "derivedFields">;
+    readonly rows: readonly Readonly<Record<string, unknown>>[];
+    readonly featureName: string;
+    readonly translate: Translate;
+};
+export declare function useRenderListColumns(input: RenderListColumnsInput): {
+    referenceColumns: import("./render-list-reference-columns.ts").ReferenceColumnSpec[];
+    handleLookupMap: (field: string, lookup: PublishedReferenceLookup) => void;
+    enrichedVm: Omit<ListViewModel, "columns"> & {
+        columns: readonly ListColumnViewModel[];
+    };
+};
+export {};

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

@@ -0,0 +1,41 @@
+import { useCallback, useMemo, useState } from "react";
+import { useReferenceLinkResolver } from "../app/reference-link.js";
+import { computeListViewModel } from "../headless/index.js";
+import { enrichReferenceColumns, selectReferenceColumns, } from "./render-list-reference-columns.js";
+export function useRenderListColumns(input) {
+    const { screen, entity, rows, featureName, translate } = input;
+    const vm = useMemo(() => computeListViewModel({ screen, entity, rows, translate, featureName }), [screen, entity, rows, translate, featureName]);
+    // Reference-field eager loading through bridge components.
+    // The Hooks rule requires useReferenceLookup for each reference column,
+    // but the number of columns varies with the schema. Each column therefore
+    // mounts a ReferenceLookupBridge that publishes its map to local state
+    // 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 [referenceLookups, setReferenceLookups] = useState({});
+    const handleLookupMap = useCallback((field, lookup) => {
+        setReferenceLookups((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];
+            if (current?.map === lookup.map && current.complete === lookup.complete)
+                return prev;
+            return { ...prev, [field]: lookup };
+        });
+    }, []);
+    const resolveReferenceLink = useReferenceLinkResolver();
+    const enrichedColumns = useMemo(() => enrichReferenceColumns({
+        columns: vm.columns,
+        referenceColumns,
+        referenceLookups,
+        resolveReferenceLink,
+        featureName,
+        translate,
+    }), [vm.columns, referenceColumns, referenceLookups, resolveReferenceLink, featureName, translate]);
+    const enrichedVm = useMemo(() => ({
+        ...vm,
+        columns: enrichedColumns,
+    }), [vm, enrichedColumns]);
+    return { referenceColumns, handleLookupMap, enrichedVm };
+}

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

@@ -0,0 +1,4 @@
+export declare function useRenderListSearch(searchValue: string | undefined, onSearchChange: ((next: string) => void) | undefined): {
+    readonly localQ: string;
+    readonly setLocalQ: (next: string) => void;
+};

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

@@ -0,0 +1,50 @@
+import { useEffect, useRef, useState } from "react";
+const SEARCH_DEBOUNCE_MS = 300;
+// Local search buffer + debounce. External changes (browser back,
+// cross-component reset) are mirrored back; typing only fires
+// onSearchChange after 300ms without further keystrokes.
+export function useRenderListSearch(searchValue, onSearchChange) {
+    const [localQ, setLocalQ] = useState(searchValue ?? "");
+    // Sync during render, not in a useEffect: the passive effect also fires on
+    // mount and can flush after a keystroke landing in the same commit,
+    // resetting localQ and swallowing the input.
+    const [syncedSearchValue, setSyncedSearchValue] = useState(searchValue);
+    // The parent may echo our own debounced emits back late (router/URL round
+    // trip), possibly after a newer emit already went out; adopting such a stale
+    // echo would erase keys typed in between. All unechoed emits are kept, and a
+    // matching echo drops itself and every older one. The render phase only reads
+    // the list (a discarded or repeated render must find the echo again); the
+    // matched entries are dropped in an effect.
+    const pendingEmitsRef = useRef([]);
+    if (searchValue !== syncedSearchValue) {
+        setSyncedSearchValue(searchValue);
+        if (!pendingEmitsRef.current.includes(searchValue ?? "")) {
+            setLocalQ(searchValue ?? "");
+            pendingEmitsRef.current = [];
+        }
+    }
+    useEffect(() => {
+        const echoIndex = pendingEmitsRef.current.indexOf(syncedSearchValue ?? "");
+        if (echoIndex >= 0)
+            pendingEmitsRef.current.splice(0, echoIndex + 1);
+    }, [syncedSearchValue]);
+    useEffect(() => {
+        // skip: no search handler wired, so typing never emits
+        if (onSearchChange === undefined)
+            return;
+        // skip: buffer already matches the parent value
+        if (localQ === (searchValue ?? ""))
+            return;
+        // A late echo of an older emit changes searchValue but must not re-send
+        // the value that is already in flight.
+        // skip: that value is already in flight
+        if (pendingEmitsRef.current.at(-1) === localQ)
+            return;
+        const timer = setTimeout(() => {
+            pendingEmitsRef.current.push(localQ);
+            onSearchChange(localQ);
+        }, SEARCH_DEBOUNCE_MS);
+        return () => clearTimeout(timer);
+    }, [localQ, searchValue, onSearchChange]);
+    return { localQ, setLocalQ };
+}

package/dist/primitives.d.ts

@@ -1365,7 +1365,7 @@ export type JsonViewProps = {
  *  PDFs, an inline preview. Used for `renderer: { format: "file" }` on a detail field. */
 export type FileValueListProps = {
     readonly fileIds: readonly string[];
-    /** Starts the inline PDF preview of the first file open. */
+    /** Starts the inline PDF preview of the newest file open; uploads append, so that is the last id. */
     readonly previewOpenByDefault?: boolean;
     readonly testId?: string;
 };

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

@@ -1,3 +1,3 @@
-import { type ReactNode } from "react";
+import type { ReactNode } from "react";
 import { type DashboardBodyProps } from "../../index.ts";
 export declare function WebDashboardBody({ featureName, screen, translate, }: DashboardBodyProps): ReactNode;

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

@@ -1,55 +1,12 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from "react";
-import { ErrorReference } from "../../app/error-reference.js";
-import { dispatcherErrorText, EmbeddedScreenProvider, evalVisibleWhen, HeaderActionsBar, KumikoScreen, useEmbeddedScreen, useLocale, useNav, usePageHeaderCompact, usePageHeaderSlotAvailable, usePrimitives, useQuery, useRecordActions, useTranslation, } from "../../index.js";
-import { cn } from "../lib/cn.js";
-import { EmbeddedFormProvider } from "../primitives/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useNav, usePageHeaderCompact, usePageHeaderSlotAvailable, usePrimitives, useTranslation, } from "../../index.js";
 import { PageSection } from "../primitives/layout.js";
-import { ModeSwitch } from "../widgets/mode-switch.js";
-import { SectionCard } from "../widgets/section-card.js";
-import { StatusBadge } from "../widgets/status-badge.js";
+import { buildScopeBadge, dashboardDescription, recordTitleText, renderActionErrorBanner, renderDescriptionAndNotice, renderHeaderActionsBar, renderPageHeaderSlot, renderRecordError, renderRecordMissing, renderTitleRow, } from "./dashboard-header.js";
 import { ChartPanelBody, CustomPanelBody, FeedPanelBody, ListPanelBody, ProgressListPanelBody, StatGroupPanelBody, StatPanelBody, TextPanelBody, } from "./dashboard-panels.js";
-import { resolveRefreshIntervalMs } from "./dashboard-refresh.js";
-import { DashboardQueryContext, HALF_PANEL, PanelError, PanelLoadedContext, useDashboardFormats, useDashboardQuery, useLoadedAt, useRefetchRegistry, WIDE_PANEL, } from "./dashboard-shared.js";
-// Value lives in the URL under `filter.id` (like useListUrlState's
-// `<screenId>.page`, same replaceState) so a `navigate` rowAction with
-// `params` can deep-link onto this filter.
-function useFilterParams(screen, enabled) {
-    const { Field, Input } = usePrimitives();
-    const t = useTranslation();
-    const nav = useNav();
-    const filter = screen.filter;
-    const value = filter !== undefined ? (nav.searchParams[filter.id] ?? "") : "";
-    const optionsQueryResult = useQuery(filter?.optionsQuery ?? "", {}, { enabled: enabled && filter?.optionsQuery !== undefined });
-    if (filter === undefined) {
-        return { params: {}, picker: null };
-    }
-    const dynamicOptions = filter.optionsQuery !== undefined
-        ? (optionsQueryResult.data?.rows ?? [])
-        : (filter.options ?? []).map((o) => ({ value: o.value, label: t(o.label) }));
-    const allLabel = t(filter.allLabel ?? "kumiko.dashboard.filter.all");
-    const options = [{ value: "", label: allLabel }, ...dynamicOptions];
-    const picker = (_jsx("div", { className: "max-w-xs", children: _jsx(Field, { id: `dashboard-filter-${filter.id}`, label: t(filter.label), children: _jsx(Input, { kind: "combobox", id: `dashboard-filter-${filter.id}`, name: filter.id, options: options, value: value, onChange: (next) => nav.setSearchParams({ [filter.id]: next === "" ? null : next }), placeholder: filter.placeholder !== undefined ? t(filter.placeholder) : allLabel }) }) }));
-    const params = value === "" ? {} : { [filter.id]: value };
-    return { params, picker };
-}
-// An unknown/stale URL value falls back to the declared default.
-function useTimeRange(screen, translate) {
-    const t = useTranslation();
-    const nav = useNav();
-    const resolver = useLocale();
-    const timeRange = screen.timeRange;
-    if (timeRange === undefined)
-        return { params: {}, control: null };
-    const fromUrl = nav.searchParams[timeRange.id];
-    const value = timeRange.options.find((o) => o.value === fromUrl)?.value ?? timeRange.default;
-    return {
-        // Metric buckets are cut server-side; without the user's zone they default
-        // to UTC while the axis labels are formatted in the user's zone.
-        params: { [timeRange.id]: value, timeZone: resolver.timeZone() },
-        control: (_jsx(ModeSwitch, { value: value, options: timeRange.options.map((o) => ({ value: o.value, label: translate(o.label) })), onChange: (next) => nav.setSearchParams({ [timeRange.id]: next }), ariaLabel: t("kumiko.dashboard.time-range"), testId: `dashboard-time-range-${timeRange.id}` })),
-    };
-}
+import { ScreenPanelTile } from "./dashboard-screen-tiles.js";
+import { DashboardQueryContext, HALF_PANEL, PanelLoadedContext, useDashboardFormats, WIDE_PANEL, } from "./dashboard-shared.js";
+import { GatedGridCell, useDashboardVisibility, VisibilityGateQueries, VisibilityQueryContext, } from "./dashboard-visibility.js";
+import { useDashboardHeaderActions, useDashboardRecord, useDashboardScreenParams, } from "./use-dashboard-screen-state.js";
 function panelSpanClassName(panel) {
     if (panel.kind === "stat")
         return undefined;
@@ -88,212 +45,51 @@ function PanelBody({ panel, label, screenId, screenParams, translate, }) {
     }
     return (_jsx(ProgressListPanelBody, { panel: panel, label: text, screenParams: screenParams, translate: translate }));
 }
-const VisibilityQueryContext = createContext(new Map());
-const NO_GATE_PAYLOAD = {};
-function visibilityGate(query, payload) {
-    return { key: `${query}|${JSON.stringify(payload)}`, query, payload };
-}
-// Embedded screens carry no screen filter; in-grid panels pass the filter
-// (unless ignoreScreenFilter, never for a stat-group) and the time range.
-function panelVisibilityGate(panel, screenParams) {
-    if (panel.kind === "custom" || panel.visibleWhen === undefined)
-        return undefined;
-    if (panel.kind === "screen")
-        return visibilityGate(panel.visibleWhen.query, NO_GATE_PAYLOAD);
-    const dropsFilter = panel.kind !== "stat-group" && panel.kind !== "text" && panel.ignoreScreenFilter === true;
-    return visibilityGate(panel.visibleWhen.query, {
-        ...(dropsFilter ? {} : screenParams.filterParams),
-        ...screenParams.rangeParams,
-        ...screenParams.recordParams,
-    });
-}
-// One live query per distinct gate (query + payload), shared by every panel
-// that gates on it — N panels on the same status query would otherwise each
-// open their own request, SSE subscription and refetch per event. The queries
-// run as keyed siblings of the grid so a changing gate count never changes the
-// grid's position in the tree (which would remount every panel).
-function VisibilityGateQuery({ gate, onResult, onForget, }) {
-    const { data, error, loading, refetch } = useDashboardQuery(gate.query, gate.payload);
-    const { key } = gate;
-    useEffect(() => {
-        onResult(key, { data, error, loading, refetch });
-    }, [key, data, error, loading, refetch, onResult]);
-    useEffect(() => () => onForget(key), [key, onForget]);
-    return null;
-}
-function VisibilityGateQueries({ gates, onResult, onForget, }) {
-    return gates.map((gate) => (_jsx(VisibilityGateQuery, { gate: gate, onResult: onResult, onForget: onForget }, gate.key)));
-}
-function useVisibilityGateResults() {
-    const [results, setResults] = useState(new Map());
-    const report = useCallback((key, result) => {
-        setResults((prev) => new Map(prev).set(key, result));
-    }, []);
-    const forget = useCallback((key) => {
-        setResults((prev) => {
-            if (!prev.has(key))
-                return prev;
-            const next = new Map(prev);
-            next.delete(key);
-            return next;
-        });
-    }, []);
-    return { results, report, forget };
-}
-const NOOP_REFETCH = async () => { };
-// A gate reports through an effect, so for its first commit (and after a payload change) no
-// result exists yet; without a placeholder that reads as "hidden" and flashes the fallback.
-function withPendingGates(results, gateKeys) {
-    if (gateKeys.every((key) => results.has(key)))
-        return results;
-    const merged = new Map(results);
-    for (const key of gateKeys) {
-        if (!merged.has(key)) {
-            merged.set(key, { data: null, error: null, loading: true, refetch: NOOP_REFETCH });
-        }
+function renderDashboardPanel(panel, featureName, screenId, screenParams, translate) {
+    if (panel.kind === "screen") {
+        return (_jsx(ScreenPanelTile, { panel: panel, featureName: featureName, translate: translate }, panel.id));
     }
-    return merged;
-}
-function distinctVisibilityGates(panels, screenParams) {
-    const gates = new Map();
-    for (const panel of panels) {
-        const gate = panelVisibilityGate(panel, screenParams);
-        if (gate !== undefined)
-            gates.set(gate.key, gate);
-    }
-    return [...gates.values()];
-}
-function GatedGridCell({ panel, screenParams, label, className, children, }) {
-    const gate = panelVisibilityGate(panel, screenParams);
-    const visibility = useContext(VisibilityQueryContext).get(gate?.key ?? "");
-    const visibleWhen = panel.kind === "custom" ? undefined : panel.visibleWhen;
-    if (visibleWhen !== undefined) {
-        const verdict = evalVisibleWhen(visibleWhen, visibility);
-        if (verdict === "error" && visibility?.error) {
-            return (_jsx("div", { className: cn("min-w-0", className), "data-testid": `dashboard-panel-${panel.id}`, children: _jsx(PanelError, { label: label, error: visibility.error, onRetry: () => void visibility.refetch() }) }));
-        }
-        // Loading renders nothing too: a skeleton that then vanishes flickers.
-        if (verdict !== "visible")
-            return null;
-    }
-    return _jsx("div", { className: cn("min-w-0", className), children: children });
-}
-function EmbeddedScreenPanelTile({ panel, target, translate, }) {
-    const screenBody = _jsx(KumikoScreen, { schema: target.schema, qn: target.qn, translate: translate });
-    const embedded = panel.chromeless === true ? (_jsx(EmbeddedFormProvider, { children: _jsx(EmbeddedScreenProvider, { children: screenBody }) })) : (screenBody);
-    return (_jsx("div", { className: cn("min-w-0", WIDE_PANEL), "data-testid": `dashboard-panel-${panel.id}`, children: panel.label !== undefined && panel.chromeless !== true ? (_jsx(SectionCard, { title: translate(panel.label), children: embedded })) : (_jsxs(_Fragment, { children: [panel.label !== undefined && (_jsx("h3", { className: "mb-3 text-sm font-semibold text-foreground", children: translate(panel.label) })), embedded] })) }));
-}
-// Own component so the target lookup (a hook) only runs for panels that actually fall back.
-function FallbackScreenPanelTile({ panel, fallback, featureName, translate, }) {
-    const target = useEmbeddedScreen(featureName, fallback);
-    if (target === undefined)
-        return null;
-    return _jsx(EmbeddedScreenPanelTile, { panel: panel, target: target, translate: translate });
-}
-function ScreenPanelTile({ panel, featureName, translate, }) {
-    const visibleWhen = panel.visibleWhen;
-    const visibility = useContext(VisibilityQueryContext).get(visibleWhen !== undefined ? visibilityGate(visibleWhen.query, NO_GATE_PAYLOAD).key : "");
-    const target = useEmbeddedScreen(featureName, panel.screen);
-    const verdict = visibleWhen === undefined ? "visible" : evalVisibleWhen(visibleWhen, visibility);
-    // Nothing while the gate loads: a fallback that flashes before the real panel flickers.
-    if (verdict === "loading")
-        return null;
-    if (verdict !== "visible" && panel.fallback !== undefined) {
-        return (_jsx(FallbackScreenPanelTile, { panel: panel, fallback: panel.fallback, featureName: featureName, translate: translate }));
-    }
-    if (target === undefined)
-        return null;
-    // A failed gate query must not silently drop the panel: on the
-    // account-security page that would hide every MFA enable/disable path.
-    if (verdict === "error" && visibility?.error) {
-        return (_jsx("div", { className: cn("min-w-0", WIDE_PANEL), "data-testid": `dashboard-panel-${panel.id}`, children: _jsx(PanelError, { label: panel.label !== undefined ? translate(panel.label) : panel.id, error: visibility.error, onRetry: () => void visibility.refetch() }) }));
-    }
-    if (verdict !== "visible")
-        return null;
-    return _jsx(EmbeddedScreenPanelTile, { panel: panel, target: target, translate: translate });
-}
-const NO_RECORD_ROW = {};
-function recordTitleText(row, field) {
-    if (row === null || field === undefined)
-        return undefined;
-    const value = row[field];
-    if (typeof value !== "string" && typeof value !== "number")
-        return undefined;
-    return String(value) === "" ? undefined : String(value);
+    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));
 }
 export function WebDashboardBody({ featureName, screen, translate, }) {
     const t = useTranslation();
     const effectiveTranslate = translate ?? t;
-    const { Text, Banner, PageHeader, Heading, Button, Dialog, ActionOverflowMenu, Grid } = usePrimitives();
+    const primitives = usePrimitives();
     const nav = useNav();
     const headerSlotAvailable = usePageHeaderSlotAvailable();
     const headerCompactContext = usePageHeaderCompact();
     const { formatDateTime } = useDashboardFormats();
-    const recordBinding = screen.record;
-    const recordId = recordBinding !== undefined ? (nav.searchParams[recordBinding.param] ?? "") : "";
-    const recordMissing = recordBinding !== undefined && recordId === "";
-    const recordPayloadKey = recordBinding?.payloadKey ?? recordBinding?.param;
-    const recordParams = recordPayloadKey !== undefined && recordId !== "" ? { [recordPayloadKey]: recordId } : {};
-    const recordQueryName = recordBinding?.query;
-    const { params: filterParams, picker } = useFilterParams(screen, !recordMissing);
-    const { params: rangeParams, control: rangeControl } = useTimeRange(screen, effectiveTranslate);
-    const screenParams = { filterParams, rangeParams, recordParams };
-    const { loadedAtMs, reportLoaded } = useLoadedAt(screenParams);
-    const visibilityGates = distinctVisibilityGates(screen.panels, screenParams);
-    const gateResults = useVisibilityGateResults();
-    const gateKeysSignature = visibilityGates.map((gate) => gate.key).join("\n");
-    const gateResultsWithPending = useMemo(() => withPendingGates(gateResults.results, gateKeysSignature === "" ? [] : gateKeysSignature.split("\n")), [gateResults.results, gateKeysSignature]);
-    // The record query is not a panel query: it needs the interval before the
-    // registry context below exists, and `refresh.field` reads from its own row.
-    const [refreshIntervalMs, setRefreshIntervalMs] = useState(() => resolveRefreshIntervalMs(screen.refresh, null));
-    const recordQuery = useQuery(recordQueryName ?? "", recordParams, {
-        enabled: recordQueryName !== undefined && !recordMissing,
-        live: true,
-        ...(refreshIntervalMs !== undefined && { refetchIntervalMs: refreshIntervalMs }),
-    });
-    const { data: recordRow, refetch: refetchRecord } = recordQuery;
-    useEffect(() => {
-        setRefreshIntervalMs(resolveRefreshIntervalMs(screen.refresh, recordRow));
-    }, [screen.refresh, recordRow]);
-    const { register, refetchRegistered } = useRefetchRegistry();
-    const queryRuntime = useMemo(() => ({ refreshIntervalMs, register }), [refreshIntervalMs, register]);
-    const refetchAll = useCallback(async () => {
-        await Promise.all([
-            recordQueryName !== undefined ? refetchRecord() : Promise.resolve(),
-            refetchRegistered(),
-        ]);
-    }, [recordQueryName, refetchRecord, refetchRegistered]);
-    const [actionError, setActionError] = useState(null);
-    const idOnlyRow = useMemo(() => (recordPayloadKey !== undefined ? { id: recordId, [recordPayloadKey]: recordId } : null), [recordId, recordPayloadKey]);
-    const actionRow = recordQueryName !== undefined ? recordRow : idOnlyRow;
-    const headerActions = useRecordActions({
-        actions: actionRow !== null && !recordMissing ? screen.actions : undefined,
-        record: actionRow ?? NO_RECORD_ROW,
-        recordId,
-        translate: effectiveTranslate,
-        onWriteSuccess: refetchAll,
-    });
-    const scope = screen.scope;
-    // A raw description is agent-facing prose; only an i18n key is user-facing copy.
-    const translatedDescription = screen.description !== undefined ? effectiveTranslate(screen.description) : undefined;
-    const description = translatedDescription !== screen.description ? translatedDescription : undefined;
-    const scopeBadge = scope !== undefined ? (_jsx(StatusBadge, { tone: "accent", testId: `dashboard-${screen.id}-scope`, children: effectiveTranslate(scope.badge) })) : null;
-    if (recordMissing) {
-        return (_jsx(PageSection, { className: "flex flex-col gap-4", testId: `dashboard-${screen.id}`, children: _jsx(Banner, { variant: "info", testId: `dashboard-${screen.id}-record-missing`, children: t("kumiko.dashboard.record.missing") }) }));
+    const params = useDashboardScreenParams(screen, effectiveTranslate, nav);
+    const { screenParams } = params;
+    const visibility = useDashboardVisibility(screen.panels, screenParams);
+    const record = useDashboardRecord(screen, params);
+    const { recordQuery, recordRow, refetchRecord } = record;
+    const { actionError, setActionError, headerActions } = useDashboardHeaderActions(screen, params, record, effectiveTranslate);
+    const description = dashboardDescription(screen, effectiveTranslate);
+    const scopeBadge = buildScopeBadge(screen, effectiveTranslate);
+    if (params.recordMissing) {
+        return (_jsx(PageSection, { className: "flex flex-col gap-4", testId: `dashboard-${screen.id}`, children: renderRecordMissing(primitives, t, screen.id) }));
     }
-    const usesPageHeaderSlot = headerSlotAvailable && PageHeader !== undefined;
-    const recordTitle = recordTitleText(recordRow, recordBinding?.titleField);
-    const headerActionsBar = headerActions !== undefined && headerActions.length > 0 ? (_jsx(Grid, { columns: "auto", testId: `dashboard-${screen.id}-actions`, children: _jsx(HeaderActionsBar, { actions: headerActions, Button: Button, Dialog: Dialog, ActionOverflowMenu: ActionOverflowMenu, onError: setActionError, collapseAfterPrimary: usesPageHeaderSlot, compact: headerCompactContext && usesPageHeaderSlot, PageHeader: PageHeader, overflowTestId: `dashboard-${screen.id}-actions-overflow` }) })) : null;
+    const usesPageHeaderSlot = headerSlotAvailable && primitives.PageHeader !== undefined;
+    const model = {
+        screen,
+        t,
+        translate: effectiveTranslate,
+        primitives,
+        headerActions,
+        setActionError,
+        headerCompactContext,
+        usesPageHeaderSlot,
+        recordTitle: recordTitleText(recordRow, params.recordBinding?.titleField),
+        scopeBadge,
+        picker: params.picker,
+        rangeControl: params.rangeControl,
+        loadedAtMs: params.loadedAtMs,
+        formatDateTime,
+    };
+    const headerActionsBar = renderHeaderActionsBar(model);
     // The shell header owns the title; the badge and the actions sit in it there.
     const badgeInHeader = scopeBadge !== null && usesPageHeaderSlot;
-    const showPageHeader = usesPageHeaderSlot && (badgeInHeader || recordTitle !== undefined || headerActionsBar !== null);
-    return (_jsx(PanelLoadedContext.Provider, { value: reportLoaded, children: _jsx(DashboardQueryContext.Provider, { value: queryRuntime, children: _jsxs(PageSection, { className: "flex flex-col gap-4", testId: `dashboard-${screen.id}`, children: [showPageHeader && (_jsx(PageHeader, { ...(recordTitle !== undefined && { title: recordTitle }), ...(badgeInHeader && { status: scopeBadge }), ...(headerActionsBar !== null && { actions: headerActionsBar }) })), _jsxs("div", { className: "flex flex-wrap items-end justify-between gap-3", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-2", children: [!usesPageHeaderSlot && recordTitle !== undefined && (_jsx(Heading, { variant: "page", testId: `dashboard-${screen.id}-record-title`, children: recordTitle })), !badgeInHeader && scopeBadge, picker] }), _jsxs("div", { className: "flex flex-wrap items-center gap-3", children: [!usesPageHeaderSlot && headerActionsBar, screen.showUpdatedAt !== false && (_jsx("span", { "data-testid": `dashboard-${screen.id}-updated-at`, className: "text-xs tabular-nums text-muted-foreground", children: t("kumiko.dashboard.updated-at", { time: formatDateTime(loadedAtMs) }) })), rangeControl] })] }), actionError !== null && (_jsxs(Banner, { variant: "error", testId: "render-edit-action-error", children: [actionError.message, _jsx(ErrorReference, { requestId: actionError.requestId })] })), recordQuery.error !== null && recordRow === null && (_jsxs("div", { role: "alert", "data-testid": `dashboard-${screen.id}-record-error`, className: "flex flex-col items-start gap-2 text-sm", children: [_jsx("span", { className: "text-status-bad", children: dispatcherErrorText(recordQuery.error, t) }), _jsx(Button, { variant: "secondary", onClick: () => void refetchRecord(), children: t("kumiko.dashboard.panel.error.retry") })] })), description !== undefined && (_jsx(Text, { variant: "muted", testId: `dashboard-${screen.id}-description`, children: description })), scope?.notice !== undefined && (_jsx(Banner, { variant: "info", testId: `dashboard-${screen.id}-scope-notice`, children: effectiveTranslate(scope.notice) })), _jsxs(VisibilityQueryContext.Provider, { value: gateResultsWithPending, children: [_jsx(VisibilityGateQueries, { gates: visibilityGates, onResult: gateResults.report, onForget: gateResults.forget }), _jsx("div", { className: "grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4", children: screen.panels.map((panel) => {
-                                    if (panel.kind === "screen") {
-                                        return (_jsx(ScreenPanelTile, { panel: panel, featureName: featureName, translate: effectiveTranslate }, panel.id));
-                                    }
-                                    const label = panel.kind === "custom" || panel.label === undefined
-                                        ? undefined
-                                        : effectiveTranslate(panel.label);
-                                    return (_jsx(GatedGridCell, { panel: panel, screenParams: screenParams, label: label ?? panel.id, className: panelSpanClassName(panel), children: _jsx(PanelBody, { panel: panel, label: label, screenId: screen.id, screenParams: screenParams, translate: effectiveTranslate }) }, panel.id));
-                                }) })] })] }) }) }));
+    return (_jsx(PanelLoadedContext.Provider, { value: params.reportLoaded, children: _jsx(DashboardQueryContext.Provider, { value: record.queryRuntime, children: _jsxs(PageSection, { className: "flex flex-col gap-4", testId: `dashboard-${screen.id}`, children: [renderPageHeaderSlot(model, headerActionsBar, badgeInHeader), renderTitleRow(model, headerActionsBar, badgeInHeader), renderActionErrorBanner(primitives, actionError), renderRecordError(model, recordQuery.error, recordRow, refetchRecord), renderDescriptionAndNotice(model, description), _jsxs(VisibilityQueryContext.Provider, { value: visibility.gateResultsWithPending, children: [_jsx(VisibilityGateQueries, { gates: visibility.visibilityGates, onResult: visibility.gateResults.report, onForget: visibility.gateResults.forget }), _jsx("div", { className: "grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4", children: screen.panels.map((panel) => renderDashboardPanel(panel, featureName, screen.id, screenParams, effectiveTranslate)) })] })] }) }) }));
 }

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

@@ -0,0 +1,34 @@
+import type { DashboardScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { Dispatch, ReactNode, SetStateAction } from "react";
+import { type ErrorNotice } from "../../app/error-reference.tsx";
+import type { DispatcherError, Translate } from "../../headless/index.ts";
+import { type usePrimitives, type useRecordActions } from "../../index.ts";
+import type { useDashboardFormats, useLoadedAt } from "./dashboard-shared.tsx";
+type Primitives = ReturnType<typeof usePrimitives>;
+export type DashboardHeaderModel = {
+    readonly screen: DashboardScreenDefinition;
+    readonly t: Translate;
+    readonly translate: Translate;
+    readonly primitives: Primitives;
+    readonly headerActions: ReturnType<typeof useRecordActions>;
+    readonly setActionError: Dispatch<SetStateAction<ErrorNotice | null>>;
+    readonly headerCompactContext: boolean;
+    readonly usesPageHeaderSlot: boolean;
+    readonly recordTitle: string | undefined;
+    readonly scopeBadge: ReactNode;
+    readonly picker: ReactNode;
+    readonly rangeControl: ReactNode;
+    readonly loadedAtMs: ReturnType<typeof useLoadedAt>["loadedAtMs"];
+    readonly formatDateTime: ReturnType<typeof useDashboardFormats>["formatDateTime"];
+};
+export declare function recordTitleText(row: Readonly<Record<string, unknown>> | null, field: string | undefined): string | undefined;
+export declare function buildScopeBadge(screen: DashboardScreenDefinition, translate: Translate): ReactNode;
+export declare function dashboardDescription(screen: DashboardScreenDefinition, translate: Translate): string | undefined;
+export declare function renderRecordMissing(primitives: Primitives, t: Translate, screenId: string): ReactNode;
+export declare function renderHeaderActionsBar(model: DashboardHeaderModel): ReactNode;
+export declare function renderPageHeaderSlot(model: DashboardHeaderModel, headerActionsBar: ReactNode, badgeInHeader: boolean): ReactNode;
+export declare function renderTitleRow(model: DashboardHeaderModel, headerActionsBar: ReactNode, badgeInHeader: boolean): ReactNode;
+export declare function renderActionErrorBanner(primitives: Primitives, actionError: ErrorNotice | null): ReactNode;
+export declare function renderRecordError(model: DashboardHeaderModel, error: DispatcherError | null, recordRow: Readonly<Record<string, unknown>> | null, refetchRecord: () => Promise<void>): ReactNode;
+export declare function renderDescriptionAndNotice(model: DashboardHeaderModel, description: string | undefined): ReactNode;
+export {};

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

@@ -0,0 +1,58 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ErrorReference } from "../../app/error-reference.js";
+import { dispatcherErrorText, HeaderActionsBar, } from "../../index.js";
+import { StatusBadge } from "../widgets/status-badge.js";
+export function recordTitleText(row, field) {
+    if (row === null || field === undefined)
+        return undefined;
+    const value = row[field];
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    return String(value) === "" ? undefined : String(value);
+}
+export function buildScopeBadge(screen, translate) {
+    const scope = screen.scope;
+    return scope !== undefined ? (_jsx(StatusBadge, { tone: "accent", testId: `dashboard-${screen.id}-scope`, children: translate(scope.badge) })) : null;
+}
+export function dashboardDescription(screen, translate) {
+    // A raw description is agent-facing prose; only an i18n key is user-facing copy.
+    const translatedDescription = screen.description !== undefined ? translate(screen.description) : undefined;
+    return translatedDescription !== screen.description ? translatedDescription : undefined;
+}
+export function renderRecordMissing(primitives, t, screenId) {
+    const { Banner } = primitives;
+    return (_jsx(Banner, { variant: "info", testId: `dashboard-${screenId}-record-missing`, children: t("kumiko.dashboard.record.missing") }));
+}
+export function renderHeaderActionsBar(model) {
+    const { screen, headerActions, headerCompactContext, usesPageHeaderSlot, setActionError } = model;
+    const { Button, Dialog, ActionOverflowMenu, Grid, PageHeader } = model.primitives;
+    return headerActions !== undefined && headerActions.length > 0 ? (_jsx(Grid, { columns: "auto", testId: `dashboard-${screen.id}-actions`, children: _jsx(HeaderActionsBar, { actions: headerActions, Button: Button, Dialog: Dialog, ActionOverflowMenu: ActionOverflowMenu, onError: setActionError, collapseAfterPrimary: usesPageHeaderSlot, compact: headerCompactContext && usesPageHeaderSlot, PageHeader: PageHeader, overflowTestId: `dashboard-${screen.id}-actions-overflow` }) })) : null;
+}
+export function renderPageHeaderSlot(model, headerActionsBar, badgeInHeader) {
+    const { PageHeader } = model.primitives;
+    const { recordTitle, scopeBadge, usesPageHeaderSlot } = model;
+    const showPageHeader = usesPageHeaderSlot && (badgeInHeader || recordTitle !== undefined || headerActionsBar !== null);
+    return (showPageHeader &&
+        PageHeader !== undefined && (_jsx(PageHeader, { ...(recordTitle !== undefined && { title: recordTitle }), ...(badgeInHeader && { status: scopeBadge }), ...(headerActionsBar !== null && { actions: headerActionsBar }) })));
+}
+export function renderTitleRow(model, headerActionsBar, badgeInHeader) {
+    const { Heading } = model.primitives;
+    const { screen, usesPageHeaderSlot, recordTitle, scopeBadge, picker, rangeControl } = model;
+    return (_jsxs("div", { className: "flex flex-wrap items-end justify-between gap-3", children: [_jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-2", children: [!usesPageHeaderSlot && recordTitle !== undefined && (_jsx(Heading, { variant: "page", testId: `dashboard-${screen.id}-record-title`, children: recordTitle })), !badgeInHeader && scopeBadge, picker] }), _jsxs("div", { className: "flex flex-wrap items-center gap-3", children: [!usesPageHeaderSlot && headerActionsBar, screen.showUpdatedAt !== false && (_jsx("span", { "data-testid": `dashboard-${screen.id}-updated-at`, className: "text-xs tabular-nums text-muted-foreground", children: model.t("kumiko.dashboard.updated-at", {
+                            time: model.formatDateTime(model.loadedAtMs),
+                        }) })), rangeControl] })] }));
+}
+export function renderActionErrorBanner(primitives, actionError) {
+    const { Banner } = primitives;
+    return (actionError !== null && (_jsxs(Banner, { variant: "error", testId: "render-edit-action-error", children: [actionError.message, _jsx(ErrorReference, { requestId: actionError.requestId })] })));
+}
+export function renderRecordError(model, error, recordRow, refetchRecord) {
+    const { Button } = model.primitives;
+    return (error !== null &&
+        recordRow === null && (_jsxs("div", { role: "alert", "data-testid": `dashboard-${model.screen.id}-record-error`, className: "flex flex-col items-start gap-2 text-sm", children: [_jsx("span", { className: "text-status-bad", children: dispatcherErrorText(error, model.t) }), _jsx(Button, { variant: "secondary", onClick: () => void refetchRecord(), children: model.t("kumiko.dashboard.panel.error.retry") })] })));
+}
+export function renderDescriptionAndNotice(model, description) {
+    const { Text, Banner } = model.primitives;
+    const { screen } = model;
+    return (_jsxs(_Fragment, { children: [description !== undefined && (_jsx(Text, { variant: "muted", testId: `dashboard-${screen.id}-description`, children: description })), screen.scope?.notice !== undefined && (_jsx(Banner, { variant: "info", testId: `dashboard-${screen.id}-scope-notice`, children: model.translate(screen.scope.notice) }))] }));
+}

package/dist/web/app/dashboard-screen-controls.d.ts

@@ -0,0 +1,11 @@
+import type { DashboardScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ReactNode } from "react";
+import type { Translate } from "../../headless/index.ts";
+export declare function useFilterParams(screen: DashboardScreenDefinition, enabled: boolean): {
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly picker: ReactNode;
+};
+export declare function useTimeRange(screen: DashboardScreenDefinition, translate: Translate): {
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly control: ReactNode;
+};

package/dist/web/app/dashboard-screen-controls.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useLocale, useNav, usePrimitives, useQuery, useTranslation } from "../../index.js";
+import { ModeSwitch } from "../widgets/mode-switch.js";
+// Value lives in the URL under `filter.id` (like useListUrlState's
+// `<screenId>.page`, same replaceState) so a `navigate` rowAction with
+// `params` can deep-link onto this filter.
+export function useFilterParams(screen, enabled) {
+    const { Field, Input } = usePrimitives();
+    const t = useTranslation();
+    const nav = useNav();
+    const filter = screen.filter;
+    const value = filter !== undefined ? (nav.searchParams[filter.id] ?? "") : "";
+    const optionsQueryResult = useQuery(filter?.optionsQuery ?? "", {}, { enabled: enabled && filter?.optionsQuery !== undefined });
+    if (filter === undefined) {
+        return { params: {}, picker: null };
+    }
+    const dynamicOptions = filter.optionsQuery !== undefined
+        ? (optionsQueryResult.data?.rows ?? [])
+        : (filter.options ?? []).map((o) => ({ value: o.value, label: t(o.label) }));
+    const allLabel = t(filter.allLabel ?? "kumiko.dashboard.filter.all");
+    const options = [{ value: "", label: allLabel }, ...dynamicOptions];
+    const picker = (_jsx("div", { className: "max-w-xs", children: _jsx(Field, { id: `dashboard-filter-${filter.id}`, label: t(filter.label), children: _jsx(Input, { kind: "combobox", id: `dashboard-filter-${filter.id}`, name: filter.id, options: options, value: value, onChange: (next) => nav.setSearchParams({ [filter.id]: next === "" ? null : next }), placeholder: filter.placeholder !== undefined ? t(filter.placeholder) : allLabel }) }) }));
+    const params = value === "" ? {} : { [filter.id]: value };
+    return { params, picker };
+}
+// An unknown/stale URL value falls back to the declared default.
+export function useTimeRange(screen, translate) {
+    const t = useTranslation();
+    const nav = useNav();
+    const resolver = useLocale();
+    const timeRange = screen.timeRange;
+    if (timeRange === undefined)
+        return { params: {}, control: null };
+    const fromUrl = nav.searchParams[timeRange.id];
+    const value = timeRange.options.find((o) => o.value === fromUrl)?.value ?? timeRange.default;
+    return {
+        // Metric buckets are cut server-side; without the user's zone they default
+        // to UTC while the axis labels are formatted in the user's zone.
+        params: { [timeRange.id]: value, timeZone: resolver.timeZone() },
+        control: (_jsx(ModeSwitch, { value: value, options: timeRange.options.map((o) => ({ value: o.value, label: translate(o.label) })), onChange: (next) => nav.setSearchParams({ [timeRange.id]: next }), ariaLabel: t("kumiko.dashboard.time-range"), testId: `dashboard-time-range-${timeRange.id}` })),
+    };
+}

package/dist/web/app/dashboard-screen-tiles.d.ts

@@ -0,0 +1,8 @@
+import type { DashboardScreenPanel } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+import type { Translate } from "../../headless/index.ts";
+export declare function ScreenPanelTile({ panel, featureName, translate, }: {
+    readonly panel: DashboardScreenPanel;
+    readonly featureName: string;
+    readonly translate: Translate;
+}): ReactNode;