@r0hitsharma/dashboard-kit 0.12.0-rohit-fork-ci.1

package/README.md

@@ -0,0 +1,150 @@
+# @r0hitsharma/dashboard-kit
+
+A generic, declarative dashboard engine. You describe a dashboard as data — a
+`DashboardSpec` manifest — and the engine renders it: a recursive layout tree of
+resizable splits and widgets, a flat widget registry, typed data bindings, and
+declared cross-widget interaction. It ships only the ENGINE and a small set of
+GENERIC adapters over `@r0hitsharma/design-system` and
+`@r0hitsharma/charting`; every domain-specific widget, data source, and
+component binding is the consumer's to register.
+
+## Install
+
+```jsonc
+// peerDependencies
+"@r0hitsharma/dashboard-kit": "*",
+"@r0hitsharma/design-system": "*",
+"@r0hitsharma/charting": "*",
+"react": "^19",
+"react-dom": "^19"
+```
+
+## Quick start
+
+```tsx
+import {
+  DashboardRenderer,
+  type DashboardSpec,
+  type DashboardDataSources,
+} from '@r0hitsharma/dashboard-kit';
+
+const spec: DashboardSpec = {
+  version: 1,
+  title: 'Overview',
+  layout: {
+    type: 'split',
+    direction: 'column',
+    children: [
+      { type: 'widget', ref: 'kpis' },
+      {
+        type: 'split',
+        direction: 'row',
+        children: [
+          { type: 'widget', ref: 'trend', size: 2 },
+          { type: 'widget', ref: 'table', size: 1 },
+        ],
+      },
+    ],
+  },
+  widgets: {
+    kpis: {
+      id: 'kpis',
+      component: 'statRow',
+      title: 'Key metrics',
+      dataBinding: { source: 'metrics', fields: { label: 'name', value: 'value' } },
+      interaction: { reads: ['highlightedKey'] },
+    },
+    trend: {
+      id: 'trend',
+      component: 'lineChart',
+      title: 'Trend',
+      dataBinding: { source: 'series', fields: {} },
+      props: { xField: 'x', series: [{ key: 'A', field: 'a' }] },
+    },
+    table: {
+      id: 'table',
+      component: 'table',
+      title: 'Rows',
+      dataBinding: { source: 'metrics', fields: { rowKey: 'name' } },
+      props: {
+        columns: [
+          { accessorKey: 'name', header: 'Name' },
+          { accessorKey: 'value', header: 'Value', render: 'number' },
+        ],
+      },
+      interaction: { writes: ['highlightedKey'] },
+    },
+  },
+};
+
+const dataSources: DashboardDataSources = {
+  metrics: [
+    { name: 'Alpha', value: 42 },
+    { name: 'Beta', value: 17 },
+  ],
+  series: [
+    { x: 'Mon', a: 3 },
+    { x: 'Tue', a: 5 },
+  ],
+};
+
+export function Example() {
+  return <DashboardRenderer spec={spec} dataSources={dataSources} />;
+}
+```
+
+Clicking a `table` row writes `highlightedKey`; the `statRow` reads it and
+emphasizes the matching tile — cross-highlighting driven entirely by the
+manifest's declared `interaction`.
+
+## The manifest
+
+- `layout` — a recursive tree of `split` (row/column, optionally `resizable`)
+  and `widget` (a `ref` into `widgets`) nodes. Positioning only; independent of
+  what each leaf renders.
+- `widgets` — a flat, id-keyed map of widget nodes: `{ component, props,
+  dataBinding, interaction, thresholds }`.
+- `dataBinding` — `{ source, fields }`: a data-source id plus a channel→field
+  mapping (Vega-Lite style, not a query string).
+- `interaction` — `reads` / `writes` shared-selection keys, plus `agentWritable`
+  (default-deny agent exposure; see below).
+
+## Extending the registry
+
+Register your own component keys → adapters and merge them over the defaults:
+
+```tsx
+import { DashboardRenderer, mergeRegistries, type RegistryComponent } from '@r0hitsharma/dashboard-kit';
+
+const Gauge: RegistryComponent = ({ widget, data }) => /* ... */;
+const registry = mergeRegistries({ gauge: Gauge });
+
+<DashboardRenderer spec={spec} dataSources={ds} registry={registry} />;
+```
+
+The default registry provides `note`, `stat`, `statRow`, `table`, `lineChart`,
+and `areaChart`.
+
+## Validation
+
+`validateDashboardSpec(candidate, { knownComponents })` runs a zod structural
+pass plus referential passes (unknown refs, orphaned widgets, a widget `id` that
+disagrees with its registry key, resizable column-split without a height, an
+`agentWritable` key that isn't writable, optional unknown-component check). It
+never throws — an agent-submitted patch is untrusted input, so it returns
+`{ ok, issues }` and the renderer shows an annotated rejection rather than
+blanking. `DashboardRenderer` runs it by default;
+pass `skipValidation` for a spec you author and trust.
+
+`collectAgentWritableKeys(spec)` is the other half of the `agentWritable`
+contract: it returns the set of keys the manifest actually permits an agent to
+write, so a host app's agent-facing tools can refuse anything outside it.
+
+## Interaction
+
+By default the renderer uses a self-contained local interaction store, enough
+for a standalone dashboard. To cross-filter a synced chart group, back
+interaction with charting's real per-key store via `useChartingInteraction`
+(see `DESIGN.md`).
+
+See `DESIGN.md` for the full contract and design rationale.

package/dist/charting-interaction.d.ts

@@ -0,0 +1,47 @@
+import { type InteractionKey } from '@r0hitsharma/charting';
+import { type ReactElement } from 'react';
+import type { InteractionContextValue } from './interaction.js';
+/**
+ * Adapts a manifest's free-form interaction vocabulary onto charting's REAL
+ * per-key store (`DashboardInteractionProvider` / `useDashboardInteraction` /
+ * `useInteractionValue`), so a declarative dashboard cross-filters the same
+ * synced chart group a hand-built one would.
+ *
+ * The reconciliation this file owns: a manifest names keys in an FDC3-shaped
+ * vocabulary (`highlightedAsset`, `selectedTimeRange`) while charting's store
+ * is typed to `highlightedKey` / `timeRange` / `hoveredTimestamp`. The key map
+ * below is the single, declared place that translation happens — not a rename
+ * of either side. Consumers can pass their own map to extend the vocabulary.
+ *
+ * ── Why a bridge rather than calling `useDashboardInteraction` in each widget
+ * Charting's `DashboardInteractionContext` value changes identity on every
+ * pointer move (`hoveredTimestamp` lives in it), so anything that consumes it
+ * re-renders at hover frequency. {@link InteractionSync} is the SOLE consumer:
+ * a null-rendering component that republishes the mapped keys into a tiny
+ * per-key store. A widget that declared `interaction.reads: ['highlightedAsset']`
+ * then re-renders when the highlight changes and at no other time — matching
+ * the discipline of charting's own `useInteractionValue`.
+ */
+export type InteractionKeyMap = Record<string, InteractionKey>;
+/**
+ * Default manifest-key -> charting-key aliases. Native charting keys map to
+ * themselves so a manifest may also name them directly.
+ */
+export declare const DEFAULT_INTERACTION_KEY_MAP: InteractionKeyMap;
+export type ChartingInteraction = {
+    /** The generic surface to hand the renderer's `interaction` prop. */
+    interaction: InteractionContextValue;
+    /**
+     * Render ONCE inside a `SyncedChartGroup` / `DashboardInteractionProvider`.
+     * It renders nothing observable; it is the sole subscriber to the
+     * high-frequency charting context and republishes the mapped keys into the
+     * per-key store that {@link interaction} reads.
+     */
+    InteractionSync: () => ReactElement;
+};
+/**
+ * Builds a charting-backed {@link InteractionContextValue}. Call it above a
+ * `SyncedChartGroup`, hand `interaction` to `DashboardRenderer`, and render
+ * `<InteractionSync />` inside the group.
+ */
+export declare function useChartingInteraction(keyMap?: InteractionKeyMap): ChartingInteraction;

package/dist/charting-interaction.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useDashboardInteraction, } from '@r0hitsharma/charting';
+import { useCallback, useEffect, useMemo, useRef, } from 'react';
+/**
+ * Default manifest-key -> charting-key aliases. Native charting keys map to
+ * themselves so a manifest may also name them directly.
+ */
+export const DEFAULT_INTERACTION_KEY_MAP = {
+    highlightedAsset: 'highlightedKey',
+    highlightedKey: 'highlightedKey',
+    selectedTimeRange: 'timeRange',
+    timeRange: 'timeRange',
+    hoveredTimestamp: 'hoveredTimestamp',
+};
+/**
+ * Module-scope, not a closure created per `useChartingInteraction` call:
+ * hooks nested inside a `useMemo`/`useCallback` are ambiguous to the rules-of
+ * -hooks check (it can't tell they belong to a separate component render, not
+ * the enclosing hook's), so this needs to be a real, statically top-level
+ * component. Everything it needs comes in as props instead of a closure.
+ *
+ * `keyMap` is a plain prop, not a ref synced from a parent effect: React
+ * flushes child effects before parent effects, so a ref updated by
+ * `useChartingInteraction`'s own effect would still hold the PREVIOUS
+ * `keyMap` when this component's effects below run in the commit where it
+ * actually changed. A prop is simply current already.
+ */
+function ChartingInteractionSync({ keyMap, writerRef, publish, }) {
+    const chart = useDashboardInteraction();
+    // Every manifest alias that resolves to `highlightedKey` gets the
+    // charting value republished under it; likewise for the other keys.
+    const aliasesFor = useCallback((chartingKey) => Object.entries(keyMap)
+        .filter(([, target]) => target === chartingKey)
+        .map(([alias]) => alias), [keyMap]);
+    useEffect(() => {
+        for (const alias of aliasesFor('highlightedKey')) {
+            publish(alias, chart.highlightedKey ?? undefined);
+        }
+    }, [chart.highlightedKey, publish, aliasesFor]);
+    useEffect(() => {
+        for (const alias of aliasesFor('timeRange')) {
+            publish(alias, chart.timeRange ?? undefined);
+        }
+    }, [chart.timeRange, publish, aliasesFor]);
+    useEffect(() => {
+        for (const alias of aliasesFor('hoveredTimestamp')) {
+            publish(alias, chart.hoveredTimestamp ?? undefined);
+        }
+    }, [chart.hoveredTimestamp, publish, aliasesFor]);
+    // The write side, held in a ref so `interaction.write` stays
+    // identity-stable for every consumer.
+    useEffect(() => {
+        writerRef.current = (key, value) => {
+            switch (keyMap[key]) {
+                case 'highlightedKey':
+                    chart.setHighlightedKey(value == null ? null : String(value));
+                    return;
+                case 'timeRange':
+                    chart.setTimeRange(value ?? null);
+                    return;
+                case 'hoveredTimestamp':
+                    chart.setHoveredTimestamp(value == null ? null : Number(value));
+                    return;
+                default:
+                    return;
+            }
+        };
+    }, [chart, keyMap, writerRef]);
+    return null;
+}
+/**
+ * Builds a charting-backed {@link InteractionContextValue}. Call it above a
+ * `SyncedChartGroup`, hand `interaction` to `DashboardRenderer`, and render
+ * `<InteractionSync />` inside the group.
+ */
+export function useChartingInteraction(keyMap = DEFAULT_INTERACTION_KEY_MAP) {
+    const valuesRef = useRef(new Map());
+    const listenersRef = useRef(new Map());
+    const writerRef = useRef(() => { });
+    const read = useCallback((key) => valuesRef.current.get(key), []);
+    const write = useCallback((key, value) => {
+        writerRef.current(key, value);
+    }, []);
+    const subscribe = useCallback((key, onChange) => {
+        let listeners = listenersRef.current.get(key);
+        if (!listeners) {
+            listeners = new Set();
+            listenersRef.current.set(key, listeners);
+        }
+        listeners.add(onChange);
+        return () => {
+            listeners.delete(onChange);
+        };
+    }, []);
+    const publish = useCallback((key, value) => {
+        if (Object.is(valuesRef.current.get(key), value))
+            return;
+        valuesRef.current.set(key, value);
+        for (const listener of listenersRef.current.get(key) ?? [])
+            listener();
+    }, []);
+    const interaction = useMemo(() => ({ read, write, subscribe }), [read, write, subscribe]);
+    // A stable function identity, so React doesn't unmount/remount
+    // `ChartingInteractionSync` (and its charting subscription) across the
+    // dashboard's renders — as long as `keyMap` doesn't churn identity either.
+    // Pass a memoized `keyMap` (module-scoped, like the default, or your own
+    // `useMemo`); an inline object here remounts the subscription every render,
+    // the same discipline `usePlayback`'s `source` and `useDataTable`'s
+    // `columns` already require of their callers.
+    const InteractionSync = useCallback(() => (_jsx(ChartingInteractionSync, { keyMap: keyMap, writerRef: writerRef, publish: publish })), [publish, keyMap]);
+    return { interaction, InteractionSync };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { DashboardSpec, DashboardDataSources, DataBinding, LayoutDirection, LayoutNode, SplitLayoutNode, ThresholdRule, ThresholdSeverity, WidgetInteraction, WidgetLayoutNode, WidgetNode, WidgetTableColumn, } from './schema.js';
+export { DashboardRenderer, renderLayoutNode, type DashboardRendererProps, } from './renderer.js';
+export { DEFAULT_REGISTRY, UnknownWidget, mergeRegistries, type ComponentRegistry, type RegistryComponent, type RegistryComponentProps, } from './registry.js';
+export { collectAgentWritableKeys, dashboardSpecSchema, validateDashboardSpec, type ManifestIssue, type ManifestValidation, type ValidateOptions, } from './validate.js';
+export { useInteractionField, useLocalInteraction, type InteractionContextValue, } from './interaction.js';
+export { DEFAULT_INTERACTION_KEY_MAP, useChartingInteraction, type ChartingInteraction, type InteractionKeyMap, } from './charting-interaction.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+// The recursive renderer.
+export { DashboardRenderer, renderLayoutNode, } from './renderer.js';
+// The string -> component registry mechanism + the default generic adapters.
+export { DEFAULT_REGISTRY, UnknownWidget, mergeRegistries, } from './registry.js';
+// Structural + referential manifest validation, and the agent-exposure query.
+export { collectAgentWritableKeys, dashboardSpecSchema, validateDashboardSpec, } from './validate.js';
+// The generic interaction surface: the local store + the per-key read hook.
+export { useInteractionField, useLocalInteraction, } from './interaction.js';
+// The adapter onto charting's real per-key interaction store.
+export { DEFAULT_INTERACTION_KEY_MAP, useChartingInteraction, } from './charting-interaction.js';

package/dist/interaction.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The interaction surface a manifest's widgets read and write, addressed by
+ * the free-form string keys a `WidgetNode.interaction.reads`/`writes` names.
+ *
+ * This is deliberately a small, transport-agnostic `{read, write, subscribe}`
+ * contract rather than charting's concrete `DashboardInteractionApi` (which is
+ * typed to a fixed set of keys: `timeRange`, `hoveredTimestamp`, `filters`,
+ * `highlightedKey`). A manifest names its OWN vocabulary (`highlightedAsset`,
+ * `selectedTimeRange`, ...); {@link module:charting-interaction} is the adapter
+ * that maps that vocabulary onto charting's real per-key store. Keeping the
+ * engine's contract generic is what lets a consumer back interaction with
+ * charting, with their own store, or with the built-in local store below —
+ * without the engine caring which.
+ */
+export type InteractionContextValue = {
+    read: (key: string) => unknown;
+    write: (key: string, value: unknown) => void;
+    /**
+     * Optional per-key change subscription. When present, widgets reach values
+     * through {@link useInteractionField} rather than calling `read` during
+     * render, so only the widgets bound to a changed key re-render — the same
+     * hover-perf discipline charting's own per-key store enforces.
+     */
+    subscribe?: (key: string, onChange: () => void) => () => void;
+};
+/**
+ * A self-contained interaction store backed by React state — the default the
+ * renderer falls back to when no `interaction` prop is supplied. Correct and
+ * cheap for a standalone manifest (a story, a preview) that isn't synced to a
+ * live chart group; for chart-synced interaction, pass the adapter from
+ * {@link module:charting-interaction} instead.
+ */
+export declare function useLocalInteraction(): InteractionContextValue;
+/**
+ * Reads ONE interaction key, subscribing to just that key when the provider
+ * supports it. `key` may be `undefined` (a widget that declares no
+ * `interaction.reads`), in which case this is a no-op returning `undefined`.
+ *
+ * Named `useInteractionField` (not `useInteractionValue`) so a consumer file
+ * can import both this and charting's own `useInteractionValue` without a name
+ * collision.
+ */
+export declare function useInteractionField(interaction: InteractionContextValue, key: string | undefined): unknown;

package/dist/interaction.js

@@ -0,0 +1,41 @@
+import { useCallback, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
+/**
+ * A self-contained interaction store backed by React state — the default the
+ * renderer falls back to when no `interaction` prop is supplied. Correct and
+ * cheap for a standalone manifest (a story, a preview) that isn't synced to a
+ * live chart group; for chart-synced interaction, pass the adapter from
+ * {@link module:charting-interaction} instead.
+ */
+export function useLocalInteraction() {
+    const [, setState] = useState({});
+    // Keep `read`/`write` identity-stable so the context value doesn't change
+    // for reasons other than a real state change.
+    const stateRef = useRef({});
+    const read = useCallback((key) => stateRef.current[key], []);
+    const write = useCallback((key, value) => {
+        if (Object.is(stateRef.current[key], value))
+            return;
+        stateRef.current = { ...stateRef.current, [key]: value };
+        setState(stateRef.current);
+    }, []);
+    return useMemo(() => ({ read, write }), [read, write]);
+}
+/**
+ * Reads ONE interaction key, subscribing to just that key when the provider
+ * supports it. `key` may be `undefined` (a widget that declares no
+ * `interaction.reads`), in which case this is a no-op returning `undefined`.
+ *
+ * Named `useInteractionField` (not `useInteractionValue`) so a consumer file
+ * can import both this and charting's own `useInteractionValue` without a name
+ * collision.
+ */
+export function useInteractionField(interaction, key) {
+    const { read, subscribe } = interaction;
+    const subscribeToKey = useCallback((onChange) => {
+        if (!key || !subscribe)
+            return () => { };
+        return subscribe(key, onChange);
+    }, [key, subscribe]);
+    const getSnapshot = useCallback(() => (key ? read(key) : undefined), [key, read]);
+    return useSyncExternalStore(subscribeToKey, getSnapshot, getSnapshot);
+}

package/dist/registry.d.ts

@@ -0,0 +1,37 @@
+import { type JSX } from 'react';
+import { type InteractionContextValue } from './interaction.js';
+import type { WidgetNode } from './schema.js';
+/**
+ * The string -> component registry. A manifest's `WidgetNode.component` names a
+ * key here; the resolved adapter owns translating that widget's
+ * `dataBinding.fields` mapping + `props` into a real component's prop shape, so
+ * the manifest stays declarative (field names, not JSX).
+ *
+ * The registry is an EXTENSIBLE MECHANISM: {@link DEFAULT_REGISTRY} ships a
+ * small set of generic adapters over public design-system + charting
+ * components, and a consumer merges in their own domain adapters with
+ * {@link mergeRegistries} (or replaces it wholesale). The engine itself knows
+ * nothing about any specific widget.
+ */
+export type RegistryComponentProps = {
+    widget: WidgetNode;
+    data: Record<string, unknown>[];
+    interaction: InteractionContextValue;
+};
+export type RegistryComponent = (props: RegistryComponentProps) => JSX.Element;
+export type ComponentRegistry = Record<string, RegistryComponent>;
+/**
+ * The default registry: a small set of GENERIC adapters over public
+ * design-system + charting components. Nothing domain-specific — a consumer
+ * merges in their own component keys with {@link mergeRegistries}.
+ */
+export declare const DEFAULT_REGISTRY: ComponentRegistry;
+/** Merges consumer adapters over the defaults (consumer keys win on collision). */
+export declare function mergeRegistries(...registries: ComponentRegistry[]): ComponentRegistry;
+/**
+ * Inline marker rendered in place of a widget whose ref or component key does
+ * not resolve — one bad manifest entry never blanks the whole dashboard.
+ */
+export declare function UnknownWidget({ label }: {
+    label: string;
+}): JSX.Element;

package/dist/registry.js

@@ -0,0 +1,220 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Axis, AreaSeries, Grid, LineSeries, Tooltip, XYChart, chartTheme, } from '@r0hitsharma/charting';
+import { Badge, DataTable, Sparkline, StatRow, StatTile, useDataTable, } from '@r0hitsharma/design-system';
+import { useCallback, useRef, useState, } from 'react';
+import { useInteractionField, } from './interaction.js';
+const lastRecord = (data) => (data.length > 0 ? data[data.length - 1] : {});
+const toNumber = (value) => typeof value === 'number' ? value : Number(value ?? Number.NaN);
+function resolveThresholdTone(value, thresholds) {
+    if (value === undefined || !thresholds)
+        return 'default';
+    for (const rule of thresholds) {
+        const hit = (rule.op === 'gte' && value >= rule.value) ||
+            (rule.op === 'lte' && value <= rule.value) ||
+            (rule.op === 'gt' && value > rule.value) ||
+            (rule.op === 'lt' && value < rule.value) ||
+            (rule.op === 'eq' && value === rule.value);
+        if (hit)
+            return rule.severity === 'success' ? 'success' : 'critical';
+    }
+    return 'default';
+}
+/** Fallback width used only before the first ResizeObserver measurement. */
+const FALLBACK_CHART_WIDTH = 560;
+/**
+ * Sizes a chart's SVG `width` (a hard pixel dimension, not CSS) to whatever
+ * width its container is granted, via a `ResizeObserver` on a callback ref. An
+ * explicit `widget.props.width` still wins.
+ */
+function useChartWidth(explicitWidth) {
+    const [measured, setMeasured] = useState(FALLBACK_CHART_WIDTH);
+    const observerRef = useRef(null);
+    const ref = useCallback((el) => {
+        observerRef.current?.disconnect();
+        observerRef.current = null;
+        if (explicitWidth != null || !el)
+            return;
+        const observer = new ResizeObserver((entries) => {
+            const width = entries[0]?.contentRect.width;
+            if (width && width > 0)
+                setMeasured(Math.floor(width));
+        });
+        observer.observe(el);
+        observerRef.current = observer;
+    }, [explicitWidth]);
+    return { ref, width: explicitWidth ?? measured };
+}
+const CHART_MARGIN = { top: 16, right: 24, bottom: 32, left: 48 };
+const noteStyle = {
+    color: 'var(--colors-text-muted)',
+    fontSize: '0.875rem',
+    lineHeight: 1.6,
+    margin: 0,
+};
+/** A free-form note paragraph, text supplied via `props.text`. */
+const NoteWidget = ({ widget }) => (_jsx("p", { style: noteStyle, children: String(widget.props?.text ?? '') }));
+/**
+ * Formats a numeric value per `props.format`. Non-numeric input falls through
+ * to its string form (or an em dash).
+ */
+function formatStatValue(value, format) {
+    const numeric = toNumber(value);
+    if (!Number.isFinite(numeric))
+        return String(value ?? '—');
+    switch (format) {
+        case 'percent':
+            return `${(numeric * 100).toFixed(1)}%`;
+        case 'ratio':
+            return numeric.toFixed(2);
+        case 'currency':
+            return `$${numeric.toLocaleString('en-US', { maximumFractionDigits: 0 })}`;
+        default:
+            return String(numeric);
+    }
+}
+/** A single stat tile; value/tone resolved from the bound source + thresholds. */
+const StatWidget = ({ widget, data }) => {
+    const fields = widget.dataBinding?.fields ?? {};
+    const record = lastRecord(data);
+    const rawValue = fields.value ? record[fields.value] : undefined;
+    const numeric = toNumber(rawValue);
+    const tone = resolveThresholdTone(Number.isFinite(numeric) ? numeric : undefined, widget.thresholds);
+    return (_jsx(StatTile, { label: widget.props?.label ?? widget.title ?? widget.id, value: formatStatValue(rawValue, widget.props?.format), sub: widget.props?.sub, tone: tone }));
+};
+/**
+ * A row of stat tiles, one per bound record. Reads its first declared
+ * interaction key (`interaction.reads[0]`) as a highlighted-row key: the tile
+ * whose label field matches gets a `success` tone, proving `reads` is wired.
+ */
+const StatRowWidget = ({ widget, data, interaction }) => {
+    const fields = widget.dataBinding?.fields ?? {};
+    const highlightKey = widget.interaction?.reads?.[0];
+    const highlighted = useInteractionField(interaction, highlightKey);
+    return (_jsx(StatRow, { children: data.map((record, index) => {
+            const label = fields.label ? String(record[fields.label]) : `#${index}`;
+            const value = fields.value ? record[fields.value] : undefined;
+            const isHighlighted = highlighted != null && String(highlighted) === label;
+            return (_jsx(StatTile, { label: label, value: formatStatValue(value, widget.props?.format), sub: fields.sub ? String(record[fields.sub] ?? '') : undefined, tone: isHighlighted ? 'success' : 'default' }, label));
+        }) }));
+};
+function renderCell(column, value) {
+    switch (column.render) {
+        case 'number':
+            return typeof value === 'number'
+                ? value.toLocaleString('en-US', { maximumFractionDigits: 2 })
+                : String(value ?? '—');
+        case 'currency':
+            return typeof value === 'number'
+                ? `$${value.toLocaleString('en-US', { maximumFractionDigits: 0 })}`
+                : String(value ?? '—');
+        case 'percent':
+            return typeof value === 'number'
+                ? `${value.toFixed(1)}%`
+                : String(value ?? '—');
+        case 'badge': {
+            const palette = value === 'low' || value === 'success'
+                ? 'green'
+                : value === 'high' || value === 'critical'
+                    ? 'red'
+                    : 'amber';
+            return (_jsx(Badge, { colorPalette: palette, variant: "subtle", children: String(value ?? '—') }));
+        }
+        case 'sparkline':
+            return Array.isArray(value) ? (_jsx(Sparkline, { data: value, width: 96, height: 28, area: true })) : ('—');
+        default:
+            return String(value ?? '—');
+    }
+}
+/**
+ * A data table with declarative columns (`props.columns`). Writes its first
+ * declared interaction key (`interaction.writes[0]`) on row click — the
+ * clicked row's key value — proving `writes` is wired; the same key read by a
+ * sibling widget drives cross-highlighting.
+ */
+const TableWidget = ({ widget, data, interaction }) => {
+    const specColumns = widget.props?.columns ?? [];
+    const rowKeyField = widget.dataBinding?.fields?.rowKey ?? specColumns[0]?.accessorKey;
+    const writeKey = widget.interaction?.writes?.[0];
+    const highlightKey = widget.interaction?.reads?.[0] ?? writeKey;
+    const selected = useInteractionField(interaction, highlightKey);
+    const columns = specColumns.map((column) => ({
+        accessorKey: column.accessorKey,
+        header: column.header,
+        cell: (info) => renderCell(column, info.getValue()),
+    }));
+    const table = useDataTable(data, columns);
+    const getRowKey = useCallback((row) => rowKeyField ? String(row[rowKeyField]) : '', [rowKeyField]);
+    return (_jsx(DataTable, { table: table, isLoading: false, getRowKey: getRowKey, selectedRowKey: selected != null ? String(selected) : undefined, onRowClick: writeKey && rowKeyField
+            ? (row) => interaction.write(writeKey, row[rowKeyField])
+            : undefined }));
+};
+const chartWrapStyle = {
+    width: '100%',
+    minWidth: 0,
+    overflowX: 'auto',
+};
+function readSeries(widget) {
+    const raw = widget.props?.series;
+    if (Array.isArray(raw))
+        return raw;
+    // Fall back to a single series bound through `dataBinding.fields.value`.
+    const field = widget.dataBinding?.fields?.value;
+    return field ? [{ key: widget.title ?? widget.id, field }] : [];
+}
+function makeChartWidget(kind) {
+    return function ChartWidget({ widget, data }) {
+        const explicitWidth = widget.props?.width;
+        const height = widget.props?.height ?? 260;
+        const { ref, width } = useChartWidth(explicitWidth);
+        const xField = widget.props?.xField ?? 'x';
+        const series = readSeries(widget);
+        const label = widget.props?.ariaLabel ??
+            widget.title ??
+            `${kind} chart`;
+        if (data.length === 0 || series.length === 0) {
+            return _jsx("div", { ref: ref, style: chartWrapStyle });
+        }
+        const xAccessor = (d) => d[xField];
+        return (_jsx("div", { ref: ref, style: chartWrapStyle, role: "img", "aria-label": label, children: _jsxs(XYChart, { theme: chartTheme, width: width, height: height, margin: CHART_MARGIN, xScale: { type: 'band', paddingInner: 0.3 }, yScale: { type: 'linear', nice: true }, children: [_jsx(Grid, { columns: false, numTicks: 4 }), _jsx(Axis, { orientation: "bottom", numTicks: 4 }), _jsx(Axis, { orientation: "left", numTicks: 4 }), series.map((s) => kind === 'line' ? (_jsx(LineSeries, { dataKey: s.key, data: data, xAccessor: xAccessor, yAccessor: (d) => toNumber(d[s.field]) }, s.key)) : (_jsx(AreaSeries, { dataKey: s.key, data: data, xAccessor: xAccessor, yAccessor: (d) => toNumber(d[s.field]), fillOpacity: 0.3 }, s.key))), _jsx(Tooltip, { snapTooltipToDatumX: true, snapTooltipToDatumY: true, showSeriesGlyphs: true, renderTooltip: ({ tooltipData }) => {
+                            const datum = tooltipData?.nearestDatum?.datum;
+                            return datum ? String(datum[xField]) : null;
+                        } })] }) }));
+    };
+}
+/**
+ * The default registry: a small set of GENERIC adapters over public
+ * design-system + charting components. Nothing domain-specific — a consumer
+ * merges in their own component keys with {@link mergeRegistries}.
+ */
+export const DEFAULT_REGISTRY = {
+    note: NoteWidget,
+    stat: StatWidget,
+    statRow: StatRowWidget,
+    table: TableWidget,
+    lineChart: makeChartWidget('line'),
+    areaChart: makeChartWidget('area'),
+};
+/** Merges consumer adapters over the defaults (consumer keys win on collision). */
+export function mergeRegistries(...registries) {
+    return Object.assign({}, DEFAULT_REGISTRY, ...registries);
+}
+const unknownStyle = {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '0.375rem',
+    padding: '0.25rem 0.5rem',
+    borderRadius: '0.375rem',
+    borderWidth: '1px',
+    borderStyle: 'dashed',
+    borderColor: 'var(--colors-border-critical, currentColor)',
+    color: 'var(--colors-text-critical, currentColor)',
+    fontFamily: 'var(--fonts-mono, monospace)',
+    fontSize: '0.75rem',
+};
+/**
+ * Inline marker rendered in place of a widget whose ref or component key does
+ * not resolve — one bad manifest entry never blanks the whole dashboard.
+ */
+export function UnknownWidget({ label }) {
+    return (_jsxs("span", { style: unknownStyle, role: "status", children: ["unknown widget: ", label] }));
+}