@cosmicdrift/kumiko-renderer 0.384.0 → 0.385.0

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

@@ -0,0 +1,53 @@
+import type { DashboardChartPanel, DashboardCustomPanel, DashboardFeedPanel, DashboardListPanel, DashboardProgressListPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardTextPanel } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+import { type Translate } from "../../headless/index.ts";
+import { type ScreenParams } from "./dashboard-shared.tsx";
+export declare function StatPanelBody({ panel, label, screenId, screenParams, translate, variant, }: {
+    readonly panel: DashboardStatPanel;
+    readonly label: string;
+    readonly screenId: string;
+    readonly screenParams: ScreenParams;
+    readonly translate: Translate;
+    readonly variant: "card" | "strip";
+}): ReactNode;
+export declare function StatGroupPanelBody({ panel, label, screenId, screenParams, translate, }: {
+    readonly panel: DashboardStatGroupPanel;
+    readonly label: string | undefined;
+    readonly screenId: string;
+    readonly screenParams: ScreenParams;
+    readonly translate: Translate;
+}): ReactNode;
+export declare function ChartPanelBody({ panel, label, screenParams, translate, }: {
+    readonly panel: DashboardChartPanel;
+    readonly label: string;
+    readonly screenParams: ScreenParams;
+    readonly translate: Translate;
+}): ReactNode;
+export declare function ListPanelBody({ panel, label, screenParams, translate, }: {
+    readonly panel: DashboardListPanel;
+    readonly label: string;
+    readonly screenParams: ScreenParams;
+    readonly translate: Translate;
+}): ReactNode;
+export declare function FeedPanelBody({ panel, label, screenParams, translate, }: {
+    readonly panel: DashboardFeedPanel;
+    readonly label: string;
+    readonly screenParams: ScreenParams;
+    readonly translate: Translate;
+}): ReactNode;
+export declare function ProgressListPanelBody({ panel, label, screenParams, translate, }: {
+    readonly panel: DashboardProgressListPanel;
+    readonly label: string;
+    readonly screenParams: ScreenParams;
+    readonly translate: Translate;
+}): ReactNode;
+export declare function TextPanelBody({ panel, label, translate, }: {
+    readonly panel: DashboardTextPanel;
+    readonly label: string | undefined;
+    readonly translate: Translate;
+}): ReactNode;
+export declare function CustomPanelBody({ panel, screenId, filterParams, }: {
+    readonly panel: DashboardCustomPanel;
+    readonly screenId: string;
+    readonly filterParams: Readonly<Record<string, unknown>>;
+}): ReactNode;

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

@@ -0,0 +1,373 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
+import { DASHBOARD_STAT_TONES } from "@cosmicdrift/kumiko-types/screen";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { useEffect, useState } from "react";
+import { rendererWarn } from "../../dev-console.js";
+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 { StatCard, StatStripCell } from "../widgets/stat.js";
+import { EmptyState, LoadingState } from "../widgets/states.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) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "value" in value &&
+        (typeof value.value === "number" || value.value === null));
+}
+function readSparkline(panel, record) {
+    if (panel.sparklineField === undefined)
+        return undefined;
+    const raw = record[panel.sparklineField];
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.filter(isSparkPoint).flatMap((p) => (p.value === null ? [] : [p.value]));
+}
+function readTone(raw) {
+    return isOneOf(DASHBOARD_STAT_TONES, raw) ? raw : undefined;
+}
+function fallbackText(raw, placeholder) {
+    if (raw === undefined || raw === null || isRecord(raw))
+        return placeholder;
+    return String(raw);
+}
+export function StatPanelBody({ panel, label, screenId, screenParams, translate, variant, }) {
+    const formats = useDashboardFormats();
+    // Resolved HERE (not in a separate always-rendered child) so `icon` on
+    // <StatCard> is `undefined` — not a React element that renders empty —
+    // when the icon name isn't registered. StatCard gates its accent chip on
+    // `icon !== undefined`, so a resolved-but-hidden element used to leave a
+    // stray accent-colored chip next to the label.
+    const iconName = panel.icon !== undefined ? extensionSectionName(panel.icon) : undefined;
+    const Icon = useExtensionSectionComponent(iconName);
+    useEffect(() => {
+        if (panel.icon !== undefined && iconName !== undefined && Icon === undefined) {
+            rendererWarn(`[kumiko] Dashboard stat-panel "${panel.id}" on screen "${screenId}" references icon ` +
+                `"${iconName}", which is not registered in clientFeatures.extensionSectionComponents.`);
+        }
+    }, [panel.icon, panel.id, iconName, Icon, screenId]);
+    const { data, error, loading, refetch } = useDashboardQuery(panel.query, panelPayload(panel, screenParams));
+    useReportPanelLoaded(data);
+    if (loading && data === null)
+        return _jsx(LoadingState, { rows: 2 });
+    if (error !== null) {
+        return _jsx(PanelError, { label: label, error: error, onRetry: () => void refetch() });
+    }
+    const record = data ?? {};
+    const rawValue = record[panel.valueField];
+    const tone = readTone(panel.toneField !== undefined ? record[panel.toneField] : undefined) ??
+        // A fixed tone must not paint an all-clear "0" as an alarm.
+        (rawValue === 0 ? undefined : panel.tone);
+    const sub = panel.subField !== undefined ? record[panel.subField] : undefined;
+    const delta = readDelta(panel, record);
+    const valueFormat = panel.valueFormat;
+    let value;
+    if (typeof rawValue !== "number") {
+        value =
+            resolveDashboardText(rawValue, translate, formats) ??
+                fallbackText(rawValue, EMPTY_VALUE_PLACEHOLDER);
+    }
+    else if (valueFormat?.kind === "relativeTime") {
+        value = formats.formatRelative(rawValue);
+    }
+    else {
+        value = formats.formatPanelValue(valueFormat)(rawValue);
+    }
+    const spark = readSparkline(panel, record);
+    const testId = `dashboard-panel-${panel.id}`;
+    const subText = resolveDashboardText(sub, translate, formats) ?? fallbackText(sub, undefined);
+    const icon = Icon !== undefined ? (_jsx(Icon, { entityName: screenId, entityId: null, screenId: screenId, filterParams: screenParams.filterParams })) : undefined;
+    if (variant === "strip") {
+        return (_jsx(StatStripCell, { icon: icon, label: label, value: value, tone: tone ?? "default", ...(Icon !== undefined && { accentColor: panel.accentColor }), ...(subText !== undefined && { sub: subText }), ...(delta !== undefined && { delta }), ...(spark !== undefined && { spark }), testId: testId }));
+    }
+    return (_jsx(StatCard, { icon: icon, label: label, value: value, tone: tone ?? "default", ...(Icon !== undefined && { accentColor: panel.accentColor }), ...(subText !== undefined && { sub: subText }), ...(delta !== undefined && { delta }), ...(spark !== undefined && { spark }), testId: testId }));
+}
+function readDelta(panel, record) {
+    if (panel.deltaField === undefined || panel.deltaDirectionField === undefined)
+        return undefined;
+    const value = record[panel.deltaField];
+    const direction = record[panel.deltaDirectionField];
+    if (value === undefined || value === null)
+        return undefined;
+    if (direction !== "up" && direction !== "down")
+        return undefined;
+    const tone = readTone(panel.deltaToneField !== undefined ? record[panel.deltaToneField] : undefined);
+    return { value: String(value), direction, ...(tone !== undefined && { tone }) };
+}
+export function StatGroupPanelBody({ panel, label, screenId, screenParams, translate, }) {
+    const testId = `dashboard-panel-${panel.id}`;
+    if (label === undefined) {
+        return (_jsx("div", { "data-testid": testId, className: "grid grid-cols-2 gap-y-2 rounded-lg border border-border bg-card py-1 lg:auto-cols-fr lg:grid-flow-col lg:divide-x lg:divide-border-row", children: panel.stats.map((stat) => (_jsx(StatPanelBody, { panel: stat, label: translate(stat.label), screenId: screenId, screenParams: screenParams, translate: translate, variant: "strip" }, stat.id))) }));
+    }
+    return (_jsx(SectionCard, { title: label, ...(panel.subtitle !== undefined && { subtitle: translate(panel.subtitle) }), testId: testId, children: _jsx("section", { className: "grid grid-cols-[repeat(auto-fit,minmax(min(12rem,100%),1fr))] gap-3", children: panel.stats.map((stat) => (_jsx(StatPanelBody, { panel: stat, label: translate(stat.label), screenId: screenId, screenParams: screenParams, translate: translate, variant: "card" }, stat.id))) }) }));
+}
+function markerKindColor(kind) {
+    if (kind === undefined)
+        return undefined;
+    if (kind.color !== undefined)
+        return kind.color;
+    return kind.tone !== undefined ? chartToneColor(kind.tone) : undefined;
+}
+function resolveMarkers(markers, translate, formats, markerKinds) {
+    return markers?.map((marker) => {
+        const color = typeof marker.kind === "string" ? markerKindColor(markerKinds?.[marker.kind]) : undefined;
+        const legendKey = typeof marker.kind === "string" ? markerKinds?.[marker.kind]?.label : undefined;
+        const legendLabel = legendKey !== undefined ? translate(legendKey) : undefined;
+        return {
+            atMs: marker.atMs,
+            label: resolveDashboardText(marker.label, translate, formats) ?? "",
+            ...(color !== undefined && { color }),
+            ...(legendLabel !== undefined && { legendLabel }),
+        };
+    });
+}
+// A plain bar chart ("changes per day") ships `points` without `series`.
+const SINGLE_SERIES_KEY = "value";
+function chartSeries(data, panelLabel, translate) {
+    if (data.series !== undefined && data.series.length > 0) {
+        return data.series.map((s) => ({ ...s, label: translate(s.label) }));
+    }
+    if (data.points !== undefined && data.points.length > 0) {
+        return [{ key: SINGLE_SERIES_KEY, label: panelLabel, points: data.points }];
+    }
+    return [];
+}
+function distinctBucketCount(series) {
+    return new Set(series.flatMap((s) => s.points.map((p) => p.atMs))).size;
+}
+function isChartEmpty(chart, data, series) {
+    if (chart === "segment-bars")
+        return (data.rows ?? []).length === 0;
+    if (chart === "stacked-bars")
+        return distinctBucketCount(series) === 0;
+    if (chart === "stacked-area")
+        return distinctBucketCount(series) < 2;
+    const measured = (data.points ?? []).filter((p) => p.value !== null);
+    return measured.length < 2;
+}
+function windowOf(data, series) {
+    const times = series.flatMap((s) => s.points.map((p) => p.atMs));
+    const startMs = data.windowStartMs ?? (times.length > 0 ? Math.min(...times) : 0);
+    const endMs = data.windowEndMs ?? (times.length > 0 ? Math.max(...times) : 1);
+    return { startMs, endMs };
+}
+export function ChartPanelBody({ panel, label, screenParams, translate, }) {
+    const t = useTranslation();
+    const todayLabel = t("kumiko.dashboard.today");
+    const tones = panel.seriesTones;
+    const colors = panel.seriesColors;
+    const testId = `dashboard-chart-${panel.id}`;
+    const ranges = panel.chart === "stacked-area" && panel.ranges !== undefined
+        ? {
+            default: panel.ranges.default,
+            options: panel.ranges.options.map((option) => ({
+                ...option,
+                label: translate(option.label),
+            })),
+        }
+        : undefined;
+    const [windowSelection, setWindowSelection] = useState(() => initialWindowSelection(ranges, panel.chart === "stacked-area" ? panel.initialWindow : undefined));
+    const rangeSwitch = ranges !== undefined ? (_jsx(ModeSwitch, { value: windowSelection?.kind === "range" ? windowSelection.value : null, options: ranges.options.map((option) => ({
+            value: option.value,
+            label: option.label,
+        })), onChange: (value) => setWindowSelection({ kind: "range", value }), ariaLabel: label, variant: "pill", testId: `dashboard-chart-range-${panel.id}` })) : undefined;
+    return (_jsx(QueryPanel, { panel: panel, label: label, subtitle: panel.subtitle !== undefined ? translate(panel.subtitle) : undefined, action: rangeSwitch, screenParams: screenParams, translate: translate, skeleton: panel.chart === "segment-bars" ? "segments" : "bars", isEmpty: (data) => isChartEmpty(panel.chart, data, chartSeries(data, label, translate)), children: (data, formats) => {
+            const series = chartSeries(data, label, translate);
+            const { startMs, endMs } = windowOf(data, series);
+            const markers = resolveMarkers(data.markers, translate, formats, panel.markerKinds);
+            const formatValue = formats.formatPanelValue(panel.valueFormat);
+            if (panel.chart === "segment-bars") {
+                return (_jsx(SegmentBarChart, { rows: (data.rows ?? []).map((row) => ({
+                        ...row,
+                        label: translate(row.label),
+                        segments: row.segments.map((seg) => ({ ...seg, label: translate(seg.label) })),
+                    })), tones: tones, colors: colors, ariaLabel: label, formatValue: formatValue, testId: testId }));
+            }
+            if (panel.chart === "stacked-bars") {
+                const times = series.flatMap((s) => s.points.map((p) => p.atMs));
+                const spacing = Math.min(...[...new Set(times)]
+                    .sort((a, b) => a - b)
+                    .flatMap((atMs, i, all) => {
+                    const prev = all[i - 1];
+                    return prev === undefined ? [] : [atMs - prev];
+                }), DAY_MS);
+                return (_jsx(StackedBarChart, { series: series, windowEndMs: endMs, tones: tones, colors: colors, ariaLabel: label, todayLabel: todayLabel, formatBucketLabel: spacing < DAY_MS - HOUR_MS ? formats.formatHour : formats.formatDay, formatValue: formatValue, formatAxisValue: formats.formatPanelAxisValue(panel.valueFormat), testId: testId }));
+            }
+            if (panel.chart === "stacked-area") {
+                const lines = (data.lines ?? []).map((line) => ({
+                    ...line,
+                    label: translate(line.label),
+                }));
+                const todayMs = data.todayMs ?? undefined;
+                const formatDateByFormat = (atMs, format) => format === "month" ? formats.formatMonth(atMs) : formats.formatDay(atMs);
+                return (_jsx(StackedAreaChart, { series: series, lines: lines, windowStartMs: startMs, windowEndMs: endMs, ...(todayMs !== undefined && { todayMs }), tones: tones, colors: colors, markers: markers, ...(ranges !== undefined && { ranges }), brush: panel.brush === true, windowSelection: windowSelection, onWindowSelectionChange: setWindowSelection, brushLabels: {
+                        start: t("kumiko.dashboard.brush-start"),
+                        end: t("kumiko.dashboard.brush-end"),
+                    }, ariaLabel: label, todayLabel: todayLabel, formatBucketLabel: formatDateByFormat, formatValue: formatValue, formatAxisValue: formats.formatPanelAxisValue(panel.valueFormat), markerLabels: panel.markerLabels === true, formatMarkerTime: formatDateByFormat, timeZone: formats.timeZone, ...(panel.dateFormat !== undefined && { dateFormat: panel.dateFormat }), ...(panel.markerLegend !== undefined && { markerLegend: panel.markerLegend }), scrollable: panel.scrollable === true, showLegendTotals: panel.legendTotals !== false, emptyContent: _jsx(EmptyState, { title: translate(panel.emptyLabel ?? "kumiko.list.no-entries") }), testId: testId }));
+            }
+            return (_jsx(TimeseriesChart, { points: data.points ?? [], windowStartMs: startMs, windowEndMs: endMs, markers: markers, formatMarkerTime: formats.formatDay, ...((panel.valueFormat !== undefined || panel.unit !== undefined) && {
+                    yAxis: {
+                        ticks: 3,
+                        format: formats.formatPanelAxisValue(panel.valueFormat),
+                        ...(panel.unit !== undefined && { unit: translate(panel.unit) }),
+                    },
+                }), ariaLabel: label, testId: testId }));
+        } }));
+}
+export function ListPanelBody({ panel, label, screenParams, translate, }) {
+    const { formatPercent, formatNumber, formatDateTime } = useDashboardFormats();
+    const columns = panel.columns.map((c) => {
+        const normalized = normalizeListColumn(c);
+        return {
+            field: normalized.field,
+            label: translate(normalized.label ?? normalized.field),
+            ...(normalized.display !== undefined && { display: normalized.display }),
+            ...(normalized.badgeToneField !== undefined && {
+                badgeToneField: normalized.badgeToneField,
+            }),
+        };
+    });
+    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 })) }));
+}
+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) => {
+            const rows = (data.rows ?? []).map((row, i) => {
+                const trailing = resolveDashboardText(row.trailing, translate, formats);
+                return {
+                    id: String(i),
+                    primary: resolveDashboardText(row.primary, translate, formats) ?? EMPTY_VALUE_PLACEHOLDER,
+                    ...(trailing !== undefined && { trailing }),
+                };
+            });
+            return _jsx(FeedList, { rows: rows });
+        } }));
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isProgressTone(value) {
+    return value === "default" || value === "danger";
+}
+function progressUsageOf(row) {
+    const { used, limit } = row;
+    if (!isFiniteNumber(used))
+        return undefined;
+    if (limit === null)
+        return { used, limit: null };
+    return isFiniteNumber(limit) ? { used, limit } : undefined;
+}
+function toProgressListRow(row, index, translate, formats) {
+    const sub = resolveDashboardText(row["sub"], translate, formats);
+    const usage = progressUsageOf(row);
+    const explicitTone = isProgressTone(row["tone"]) ? row["tone"] : undefined;
+    const common = {
+        id: String(index),
+        label: resolveDashboardText(row["label"], translate, formats) ?? EMPTY_VALUE_PLACEHOLDER,
+        ...(sub !== undefined && { sub }),
+    };
+    if (usage === undefined) {
+        return {
+            ...common,
+            value: resolveDashboardText(row["value"], translate, formats) ?? EMPTY_VALUE_PLACEHOLDER,
+            fraction: isFiniteNumber(row["fraction"]) ? row["fraction"] : 0,
+            ...(explicitTone !== undefined && { tone: explicitTone }),
+        };
+    }
+    const { used, limit } = usage;
+    const usedText = formats.formatNumber(used);
+    const limitText = limit === null ? translate("kumiko.dashboard.progress.unlimited") : formats.formatNumber(limit);
+    const exhausted = limit !== null && used >= limit;
+    const tone = explicitTone ?? (exhausted ? "danger" : undefined);
+    let fraction = null;
+    if (limit !== null)
+        fraction = limit === 0 ? 1 : used / limit;
+    return {
+        ...common,
+        value: `${usedText} / ${limitText}`,
+        fraction,
+        ...(tone !== undefined && { tone }),
+    };
+}
+export function ProgressListPanelBody({ 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) => {
+            const rows = (data.rows ?? []).map((row, i) => toProgressListRow(row, i, translate, formats));
+            return _jsx(ProgressList, { rows: rows });
+        } }));
+}
+function TextBlockView({ block, translate, }) {
+    switch (block.kind) {
+        case "heading":
+            return (_jsx("h3", { "data-block": "heading", className: "text-sm font-semibold text-foreground", children: translate(block.text) }));
+        case "paragraph":
+            return (_jsx("p", { "data-block": "paragraph", className: block.emphasis === "strong"
+                    ? "text-sm font-medium text-foreground"
+                    : "text-sm text-muted-foreground", children: translate(block.text) }));
+        case "list":
+            return (_jsx("ul", { "data-block": "list", className: "list-disc space-y-1 pl-5 text-sm text-muted-foreground", children: block.items.map((item) => (_jsx("li", { children: translate(item) }, item))) }));
+        case "code":
+            return (_jsx("pre", { "data-block": "code", className: "overflow-x-auto rounded-md bg-muted p-3 text-xs", children: _jsx("code", { children: block.code }) }));
+        case "hint":
+            return (_jsx("p", { "data-block": "hint", className: "text-xs text-muted-foreground", children: translate(block.text) }));
+        case "link":
+            return _jsx(TextBlockLink, { block: block, translate: translate });
+    }
+}
+function TextBlockLink({ block, translate, }) {
+    const { Link } = usePrimitives();
+    const nav = useNav();
+    const userRoles = useUserRoles();
+    if (block.roles !== undefined && !block.roles.some((role) => userRoles?.includes(role))) {
+        return null;
+    }
+    const target = { screenId: lastSegment(block.screen) };
+    return (_jsx(Link, { href: nav.hrefFor(target), onPress: () => nav.navigate(target), testId: `dashboard-text-link-${target.screenId}`, children: translate(block.text) }));
+}
+function textBlockKey(block) {
+    switch (block.kind) {
+        case "list":
+            return `list:${block.items.join("|")}`;
+        case "code":
+            return `code:${block.code}`;
+        default:
+            return `${block.kind}:${block.text}`;
+    }
+}
+export function TextPanelBody({ panel, label, translate, }) {
+    const blocks = (_jsx("div", { className: "flex flex-col gap-3", children: panel.blocks.map((block) => (_jsx(TextBlockView, { block: block, translate: translate }, textBlockKey(block)))) }));
+    const testId = `dashboard-panel-${panel.id}`;
+    if (label !== undefined) {
+        return (_jsx(PanelShell, { testId: testId, title: label, children: blocks }));
+    }
+    return (_jsx("section", { "data-testid": testId, className: "h-full rounded-lg border border-border bg-card p-4 text-card-foreground", children: blocks }));
+}
+// Resolves panel.component through the same extensionSectionComponents
+// registry as entityEdit extension sections and list header slots; it
+// stays at its array position instead of moving into a separate slot (see
+// the file header comment on the registry). Renders nothing + a dev warning
+// for an unregistered name, analogous to ListHeaderSlotMount in
+// render-list.tsx.
+export function CustomPanelBody({ panel, screenId, filterParams, }) {
+    const name = extensionSectionName(panel.component);
+    const Component = useExtensionSectionComponent(name);
+    useEffect(() => {
+        if (name !== undefined && Component === undefined) {
+            rendererWarn(`[kumiko] Dashboard custom-panel "${panel.id}" on screen "${screenId}" references component ` +
+                `"${name}", which is not registered in clientFeatures.extensionSectionComponents — the panel renders nothing.`);
+        }
+    }, [name, Component, panel.id, screenId]);
+    if (Component === undefined)
+        return null;
+    // Dashboard panels have no entity; entityName carries the screen.id so
+    // ExtensionSectionProps need not be loosened for this one mount site (that
+    // would break every existing registered section that expects entityName to
+    // be a guaranteed string).
+    return (_jsx(Component, { entityName: screenId, entityId: null, screenId: screenId, filterParams: filterParams }));
+}

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

@@ -0,0 +1,90 @@
+import type { DashboardCurrencyFormat, DashboardPanelEmptyState, DashboardPanelQueryOptions } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+import { type Translate } from "../../headless/index.ts";
+import { dispatcherErrorText, type UseQueryResult } from "../../index.ts";
+export declare const WIDE_PANEL = "sm:col-span-2 lg:col-span-4";
+export declare const HALF_PANEL = "sm:col-span-2 lg:col-span-2";
+export declare const HOUR_MS = 3600000;
+export declare const DAY_MS: number;
+export type ScreenParams = {
+    readonly filterParams: Readonly<Record<string, unknown>>;
+    readonly rangeParams: Readonly<Record<string, unknown>>;
+    /** `{ [payloadKey]: recordId }` of a record-bound dashboard, else empty. */
+    readonly recordParams: Readonly<Record<string, unknown>>;
+};
+export declare function panelPayload(panel: DashboardPanelQueryOptions, screenParams: ScreenParams): Readonly<Record<string, unknown>>;
+type RefetchQuery = () => Promise<void>;
+type DashboardQueryRuntime = {
+    /** Polling interval for every panel and gate query; undefined = off. */
+    readonly refreshIntervalMs: number | undefined;
+    /** Adds a query's refetch to the set `refetchAll` walks; returns its removal. */
+    readonly register: (refetch: RefetchQuery) => () => void;
+};
+export declare const DashboardQueryContext: import("react").Context<DashboardQueryRuntime>;
+export declare function useRefetchRegistry(): {
+    readonly register: DashboardQueryRuntime["register"];
+    readonly refetchRegistered: () => Promise<void>;
+};
+/** Live query of a panel or gate that takes part in the dashboard's refresh:
+ *  polls at the screen's interval and is refetched by `refetchAll` after an
+ *  action. A disabled query registers nothing. */
+export declare function useDashboardQuery<TData>(type: string, payload: Readonly<Record<string, unknown>>, options?: {
+    readonly enabled?: boolean;
+}): UseQueryResult<TData>;
+export type DashboardFormats = {
+    readonly timeZone: string;
+    readonly formatNumber: (value: number) => string;
+    readonly formatPercent: (fraction: number) => string;
+    readonly formatDay: (atMs: number) => string;
+    readonly formatMonth: (atMs: number) => string;
+    readonly formatHour: (atMs: number) => string;
+    readonly formatDateTime: (atMs: number) => string;
+    readonly formatMedium: (atMs: number) => string;
+    readonly formatMinor: (amountMinor: number, currency: string, fractionDigits?: number) => string;
+    /** "5 minutes ago"; the component that called `useDashboardFormats` redraws on a
+     *  timer while at least one of its renders used this. */
+    readonly formatRelative: (atMs: number) => string;
+    /** Number formatter for a panel; currency when `valueFormat` is set. */
+    readonly formatPanelValue: (valueFormat: DashboardCurrencyFormat | undefined) => (value: number) => string;
+    /** Compact variant of `formatPanelValue` for chart axes ("1,5 Mio. €"). */
+    readonly formatPanelAxisValue: (valueFormat: DashboardCurrencyFormat | undefined) => (value: number) => string;
+};
+export declare function useDashboardFormats(): DashboardFormats;
+export declare function PanelShell({ testId, title, subtitle, action, children, }: {
+    readonly testId: string;
+    readonly title: string;
+    readonly subtitle?: string;
+    readonly action?: ReactNode;
+    readonly children: ReactNode;
+}): ReactNode;
+export declare function PanelError({ label, error, onRetry, testId, }: {
+    readonly label: string;
+    readonly error: Parameters<typeof dispatcherErrorText>[0];
+    readonly onRetry: () => void;
+    readonly testId?: string;
+}): ReactNode;
+type SkeletonShape = "bars" | "segments" | "rows";
+type QueryPanelProps<TData> = {
+    readonly panel: DashboardPanelQueryOptions & DashboardPanelEmptyState & {
+        readonly id: string;
+        readonly query: string;
+    };
+    readonly label: string;
+    readonly subtitle?: string;
+    readonly action?: ReactNode;
+    readonly screenParams: ScreenParams;
+    readonly translate: Translate;
+    readonly skeleton: SkeletonShape;
+    readonly isEmpty: (data: TData) => boolean;
+    /** Receives the formats of the panel itself, so a relative time inside the body
+     *  redraws this panel and nothing else. */
+    readonly children: (data: TData, formats: DashboardFormats) => ReactNode;
+};
+export declare function QueryPanel<TData>({ panel, label, subtitle, action, screenParams, translate, skeleton, isEmpty, children, }: QueryPanelProps<TData>): ReactNode;
+export declare function useLoadedAt(screenParams: ScreenParams): {
+    readonly loadedAtMs: number;
+    readonly reportLoaded: (atMs: number) => void;
+};
+export declare const PanelLoadedContext: import("react").Context<(atMs: number) => void>;
+export declare function useReportPanelLoaded(data: unknown): void;
+export {};