@cosmicdrift/kumiko-renderer 0.388.0 → 0.390.0

package/dist/primitives.d.ts

@@ -1,6 +1,9 @@
 import type { ConfigCascade, ConfigScope, ConfigValueSource } from "@cosmicdrift/kumiko-framework/engine";
 import type { FieldIconKey, FormWidth, IconKey, NavIconKey, RowActionDisplay, SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
 import { type ComponentType, type FormEvent, type KeyboardEvent, type ReactNode, type Ref } from "react";
+import type { DataTableBulk } from "./data-table-bulk-types.ts";
+import type { DataTableDateRangeFacet, DataTableFacet } from "./data-table-facet-types.ts";
+import type { DataTableTableBlock } from "./data-table-view-types.ts";
 import type { FieldIssue, ListColumnViewModel, ListRowViewModel, RuntimeRenderer } from "./headless/index.ts";
 export type { RuntimeRenderer };
 /** Escape hatch for `data-*` test hooks (e.g. an E2E selector) that don't
@@ -647,55 +650,11 @@ export type DataTableRowAction = {
 export declare function shouldRenderActionsIconOnly(actions: readonly {
     readonly icon?: IconKey;
 }[]): boolean;
-export type DataTableFacet = {
-    /** Entity-Feldname (= URL-State-Key + payload.filters[].field). */
-    readonly field: string;
-    /** Translated Button-Label ("Status", "Active"). */
-    readonly label: string;
-    /** Selectable values with display labels. `value` is the raw filter value
-     *  (a select option or `"true"`/`"false"`), transported as a string. */
-    readonly options: readonly {
-        readonly value: string;
-        readonly label: string;
-    }[];
-    /** Present: render the facet as a row of single-choice toggle chips instead
-     *  of a dropdown. A chip is pressed while the selection equals its values. */
-    readonly chips?: readonly DataTableFacetChip[];
-    /** Chips only: show each chip's `count` next to its label. */
-    readonly showCounts?: boolean;
-    /** Chips only: hide chips whose `count` is 0 (unless pressed). */
-    readonly hideEmpty?: boolean;
-};
-export type DataTableFacetChip = {
-    readonly id: string;
-    /** Translated chip label. */
-    readonly label: string;
-    /** Selection a click sets; `[]` clears the facet. */
-    readonly values: readonly string[];
-    /** Matching row count, undefined while unknown. */
-    readonly count?: number;
-};
-export type DataTableDateRangeFacet = {
-    /** The facet's namespace (its date field) — a key, not a filter value. */
-    readonly field: string;
-    /** Translated label ("When"). */
-    readonly label: string;
-    readonly from: string;
-    readonly to: string;
-};
-/** Splits rows into collapsible groups (order of first appearance). A
- *  renderer without grouping support shows the flat list. A group whose
- *  `headerLabel` is undefined shows its rows without a header and never
- *  collapses. */
-export type DataTableRowGrouping = {
-    readonly keyOf: (row: ListRowViewModel) => string;
-    readonly headerLabel: (groupKey: string, rows: readonly ListRowViewModel[]) => string | undefined;
-    readonly startsCollapsed: (groupKey: string) => boolean;
-};
+export type { BulkRowOutcome, DataTableBulk, DataTableBulkAction, } from "./data-table-bulk-types.ts";
+export type { DataTableDateRangeFacet, DataTableFacet, DataTableFacetChip, } from "./data-table-facet-types.ts";
 export type DataTableProps = {
     readonly columns: readonly ListColumnViewModel[];
     readonly rows: readonly ListRowViewModel[];
-    readonly rowGrouping?: DataTableRowGrouping;
     /** Tints a row. Renderers without row tinting ignore it. */
     readonly rowTone?: (row: ListRowViewModel) => SelectOptionTone | undefined;
     readonly onRowClick?: (row: ListRowViewModel) => void;
@@ -723,6 +682,8 @@ export type DataTableProps = {
      *    kebab). Actions then sit at the same x-position across all rows
      *    (no drifting with label width) and all lists in an app look alike. */
     readonly rowActionMode?: DataTableRowActionMode;
+    /** Present: row checkboxes plus a selection bar that runs these actions once per selected row. */
+    readonly bulk?: DataTableBulk;
     /** Custom empty-state content (e.g. Icon + Heading + CTA-Button).
      *  The default renderer wraps it in a dashed-border box. */
     readonly emptyState?: ReactNode;
@@ -832,7 +793,8 @@ export type DataTableProps = {
     /** Content of the area under an expanded row. Native renderers implement
      *  the same three props. */
     readonly renderExpandedRow?: (row: ListRowViewModel) => ReactNode;
-};
+} & DataTableTableBlock;
+export type DataTableTableBlockProps = Pick<DataTableProps, keyof DataTableTableBlock>;
 /** Cell type for one column of an embedded-list field. Mirrors
  *  EmbeddedListCellViewModel["type"] from `@cosmicdrift/kumiko-renderer/headless`. */
 export type EmbeddedListCellType = "text" | "number" | "boolean" | "date" | "money" | "decimal" | "select" | "reference" | "timestamp";
@@ -1403,6 +1365,8 @@ 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 newest file open; uploads append, so that is the last id. */
+    readonly previewOpenByDefault?: boolean;
     readonly testId?: string;
 };
 /** Band above the tabs of a record detail: optional subtitle line plus the

package/dist/web/app/create-app.d.ts

@@ -92,6 +92,11 @@ export type CreateKumikoAppOptions = {
         readonly hasWorkspaces?: boolean;
         readonly features?: readonly FeatureSchema[];
     }) => NavApi;
+    /** URL prefix the app is mounted under (for example "/admin"). The default nav adapter reads
+     *  and writes URLs relative to it, and the auth gates and pages, which sit outside the
+     *  NavProvider, use it to match and build their paths. A custom `navAdapter` handles its own
+     *  prefix. */
+    readonly basePath?: string;
     /** App-wide default width for form/detail screens that don't set their
      *  own `layout.width`. Default "4xl" (unchanged behavior) — a
      *  consumer app that wants e.g. bundled-feature screens to match its own

package/dist/web/app/create-app.js

@@ -3,7 +3,7 @@ import { isOpenToAllGranted } from "@cosmicdrift/kumiko-framework/ui-types";
 import { createContext, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { createRoot } from "react-dom/client";
 import { rendererError, rendererWarn } from "../../dev-console.js";
-import { AppFeaturesProvider, ClientActionsProvider, ColumnRenderersProvider, ContentEditorsProvider, CustomScreensProvider, createSessionEndedSignal, DashboardBodyProvider, DispatcherProvider, DraftStorageProvider, ErrorBoundary, ExtensionSectionsProvider, hasDetailScreen, KumikoScreen, kumikoDefaultTranslations, LeaveGuardDialog, LiveEventsProvider, LocaleProvider, mergeTranslations, NavProvider, navigateWithReturnTo, PrimitivesProvider, qualifyScreenId, ScreenMissingState, SessionEndedSignalProvider, TokensProvider, toAppSchema, translationsByLocaleFromKeys, useNav, usePrimitives, useTranslation, withSessionEndedDetection, } from "../../index.js";
+import { AppFeaturesProvider, BasePathProvider, ClientActionsProvider, ColumnRenderersProvider, ContentEditorsProvider, CustomScreensProvider, createSessionEndedSignal, DashboardBodyProvider, DispatcherProvider, DraftStorageProvider, ErrorBoundary, ExtensionSectionsProvider, hasDetailScreen, KumikoScreen, kumikoDefaultTranslations, LeaveGuardDialog, LiveEventsProvider, LocaleProvider, mergeTranslations, NavProvider, navigateWithReturnTo, PrimitivesProvider, qualifyScreenId, ScreenMissingState, SessionEndedSignalProvider, TokensProvider, toAppSchema, translationsByLocaleFromKeys, useNav, usePrimitives, useTranslation, withSessionEndedDetection, } from "../../index.js";
 import { createLiveDispatcher } from "../../live/index.js";
 import { lastSegment } from "../layout/nav-tree.js";
 import { clearFileMetaCache } from "../primitives/file-thumbnail.js";
@@ -19,6 +19,7 @@ import { stackWrappers } from "./client-plugin.js";
 import { WebDashboardBody } from "./dashboard-body.js";
 import { DocumentLangSync } from "./document-lang-sync.js";
 import { createBrowserDraftStorage } from "./draft-storage.js";
+import { ListStateStoreBoot } from "./list-state-store-boot.js";
 import { useBrowserNavApi } from "./nav.js";
 import { NavProvidersProvider } from "./nav-providers-context.js";
 import { ResolversProvider } from "./resolvers-context.js";
@@ -237,7 +238,7 @@ function KumikoAppRoot(props) {
             warnMissingCustomScreens(loaded, props.customScreens);
             setApp(loaded);
         }, schemaIsRoleProjected: isFetchMode, ...(isFetchMode && { onUnmountResetSchema: () => setApp(undefined) }), ...(props.translate !== undefined && { translate: props.translate }), ...(props.onRowClick !== undefined && { onRowClick: props.onRowClick }), ...(props.shell !== undefined && { shell: props.shell }) }));
-    return (_jsx(TokensBoot, { children: _jsxs(LocaleProvider, { resolver: props.localeResolver, fallbackBundles: fallbackBundles, children: [_jsx(DocumentLangSync, { resolver: props.localeResolver }), _jsx(PrimitivesProvider, { value: props.primitives, children: _jsx(ScreenWidthProvider, { width: props.screenWidth, children: _jsx(AppFeaturesProvider, { features: app?.features ?? EMPTY_FEATURES, children: _jsx(DispatcherProvider, { dispatcher: props.dispatcher, children: _jsx(DraftStorageProvider, { value: props.draftStorage, children: _jsx(LiveEventsProvider, { value: props.liveEvents, children: _jsx(DashboardBodyProvider, { value: WebDashboardBody, children: _jsx(CustomScreensProvider, { value: props.customScreens, children: _jsx(ColumnRenderersProvider, { value: props.columnRenderers, children: _jsx(ContentEditorsProvider, { value: props.contentEditors, children: _jsx(ExtensionSectionsProvider, { value: props.extensionSectionComponents, children: _jsx(ClientActionsProvider, { value: props.clientActions, children: _jsx(NavProvidersProvider, { value: navProviders, entities: navEntities, children: _jsx(ResolversProvider, { resolvers: props.resolvers, children: _jsx(ToastProvider, { children: _jsxs(ToastActionNotifier, { children: [_jsx(UpdateChecker, {}), _jsx(LeaveGuardDialog, {}), _jsx(SessionEndedSignalProvider, { signal: props.sessionEndedSignal, children: stackWrappers(props.providers, stackWrappers(props.gates, screenNode)) })] }) }) }) }) }) }) }) }) }) }) }) }) }) }) }) })] }) }));
+    return (_jsx(TokensBoot, { children: _jsxs(LocaleProvider, { resolver: props.localeResolver, fallbackBundles: fallbackBundles, children: [_jsx(DocumentLangSync, { resolver: props.localeResolver }), _jsx(PrimitivesProvider, { value: props.primitives, children: _jsx(ScreenWidthProvider, { width: props.screenWidth, children: _jsx(AppFeaturesProvider, { features: app?.features ?? EMPTY_FEATURES, children: _jsx(DispatcherProvider, { dispatcher: props.dispatcher, children: _jsx(DraftStorageProvider, { value: props.draftStorage, children: _jsx(LiveEventsProvider, { value: props.liveEvents, children: _jsx(DashboardBodyProvider, { value: WebDashboardBody, children: _jsx(CustomScreensProvider, { value: props.customScreens, children: _jsx(ColumnRenderersProvider, { value: props.columnRenderers, children: _jsx(ContentEditorsProvider, { value: props.contentEditors, children: _jsx(ExtensionSectionsProvider, { value: props.extensionSectionComponents, children: _jsx(ClientActionsProvider, { value: props.clientActions, children: _jsx(NavProvidersProvider, { value: navProviders, entities: navEntities, children: _jsx(ResolversProvider, { resolvers: props.resolvers, children: _jsx(ToastProvider, { children: _jsxs(ToastActionNotifier, { children: [_jsx(UpdateChecker, {}), _jsx(LeaveGuardDialog, {}), _jsx(SessionEndedSignalProvider, { signal: props.sessionEndedSignal, children: stackWrappers(props.providers, stackWrappers(props.gates, _jsx(ListStateStoreBoot, { children: screenNode }))) })] }) }) }) }) }) }) }) }) }) }) }) }) }) }) }) })] }) }));
 }
 // Sits INSIDE the clientFeature gates (e.g. an auth gate) — a gate that
 // renders a login placeholder instead of children keeps this component
@@ -340,7 +341,9 @@ export function createKumikoApp(options = {}) {
         }
     }
     const localeResolver = options.locale ?? createBrowserLocaleResolver();
-    const navAdapter = options.navAdapter ?? useBrowserNavApi;
+    const { basePath } = options;
+    const useBrowserNavApiWithBasePath = (navOptions) => useBrowserNavApi({ ...navOptions, ...(basePath !== undefined && { basePath }) });
+    const navAdapter = options.navAdapter ?? useBrowserNavApiWithBasePath;
     const reporter = options.reportClientErrors === false ? undefined : createClientErrorReporter();
     reporter?.installGlobalHandlers();
     const handleBoundaryError = (error, info, context) => {
@@ -353,7 +356,7 @@ export function createKumikoApp(options = {}) {
         options.onError?.(error, info, context);
     };
     const root = createRoot(container);
-    root.render(_jsx(ErrorBoundary, { scope: "root", onError: handleBoundaryError, fallback: ({ errorId }) => _jsx(RootErrorFallback, { errorId: errorId }), children: _jsx(BoundaryErrorHandlerContext.Provider, { value: handleBoundaryError, children: _jsx(KumikoAppRoot, { initialApp: initialApp, screenQn: options.screenQn, ...(options.schemaUrl !== undefined && { schemaUrl: options.schemaUrl }), clientFeatures: clientFeatures, providers: providers, gates: gates, customScreens: customScreens, columnRenderers: columnRenderers, extensionSectionComponents: extensionSectionComponents, clientActions: clientActions, contentEditors: contentEditors, resolvers: resolvers, dispatcher: dispatcher, sessionEndedSignal: sessionEndedSignal, draftStorage: draftStorage, primitives: primitives, liveEvents: liveEvents, localeResolver: localeResolver, navAdapter: navAdapter, screenWidth: options.screenWidth, ...(options.translate !== undefined && { translate: options.translate }), ...(options.onRowClick !== undefined && { onRowClick: options.onRowClick }), ...(options.shell !== undefined && { shell: options.shell }) }) }) }));
+    root.render(_jsx(ErrorBoundary, { scope: "root", onError: handleBoundaryError, fallback: ({ errorId }) => _jsx(RootErrorFallback, { errorId: errorId }), children: _jsx(BoundaryErrorHandlerContext.Provider, { value: handleBoundaryError, children: _jsx(BasePathProvider, { basePath: basePath, children: _jsx(KumikoAppRoot, { initialApp: initialApp, screenQn: options.screenQn, ...(options.schemaUrl !== undefined && { schemaUrl: options.schemaUrl }), clientFeatures: clientFeatures, providers: providers, gates: gates, customScreens: customScreens, columnRenderers: columnRenderers, extensionSectionComponents: extensionSectionComponents, clientActions: clientActions, contentEditors: contentEditors, resolvers: resolvers, dispatcher: dispatcher, sessionEndedSignal: sessionEndedSignal, draftStorage: draftStorage, primitives: primitives, liveEvents: liveEvents, localeResolver: localeResolver, navAdapter: navAdapter, screenWidth: options.screenWidth, ...(options.translate !== undefined && { translate: options.translate }), ...(options.onRowClick !== undefined && { onRowClick: options.onRowClick }), ...(options.shell !== undefined && { shell: options.shell }) }) }) }) }));
     return { root };
 }
 // TokensBoot uses the browser-backed TokensApi hook (class-based

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;
+};