From 028ad35533474594abf29f68e8e5bedac5e5160b Mon Sep 17 00:00:00 2001
From: Jack <zhuangjianguo@gmail.com>
Date: Sun, 7 Jun 2026 19:17:27 +0800
Subject: [PATCH] feat(plugin-dashboard): render dataset-bound widgets
 (ADR-0021 B-P1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A dashboard widget that binds a semantic-layer `dataset` (instead of an inline
`object`+`valueField` query) now renders via the governed queryDataset path:
new DatasetWidget fetches `dataSource.queryDataset(dataset, {dimensions,
measures: values, compareTo})` and renders a KPI value (metric) or a bar chart
(dimensioned) — numbers match the dataset everywhere. DashboardRenderer branches
to it when `widget.dataset` is set (early, before the object-aggregate path),
at both render sites. Additive/dual-form: inline widgets unchanged. Errors
surface instead of wrong/empty numbers.

Widget fields read via `(widget as any)` until objectui bumps @objectstack/spec
(the bundled DashboardWidget type gains dataset/dimensions/values then).

Tests: DatasetWidget (6) — KPI value, chart query mapping, compareTo forwarding,
error surfacing, no-dataset-support guard, no-measures prompt.

Pairs with framework dashboard.zod dual-form.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/DashboardRenderer.tsx                 | 15 ++-
 .../plugin-dashboard/src/DatasetWidget.tsx    | 98 +++++++++++++++++++
 .../src/__tests__/DatasetWidget.test.tsx      | 48 +++++++++
 3 files changed, 159 insertions(+), 2 deletions(-)
 create mode 100644 packages/plugin-dashboard/src/DatasetWidget.tsx
 create mode 100644 packages/plugin-dashboard/src/__tests__/DatasetWidget.test.tsx

diff --git a/packages/plugin-dashboard/src/DashboardRenderer.tsx b/packages/plugin-dashboard/src/DashboardRenderer.tsx
index bc6bc277f..0485cb98b 100644
--- a/packages/plugin-dashboard/src/DashboardRenderer.tsx
+++ b/packages/plugin-dashboard/src/DashboardRenderer.tsx
@@ -30,6 +30,7 @@ import {
 } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import { isObjectProvider } from './utils';
+import { DatasetWidget } from './DatasetWidget';
 
 interface SortableWidgetWrapperProps {
   id: string;
@@ -402,6 +403,12 @@ export const DashboardRenderer = forwardRef<HTMLDivElement, DashboardRendererPro
           ? { ...widget.layout, w: Math.min(widget.layout.w, columns) }
           : undefined;
 
+        // ADR-0021 — a widget bound to a semantic-layer dataset renders through
+        // the governed queryDataset path (DatasetWidget) instead of the inline
+        // object-aggregate schema. `as any` because the bundled DashboardWidget
+        // type gains `dataset` only after objectui bumps @objectstack/spec.
+        const datasetBound = !!(widget as any).dataset;
+
         const getComponentSchema = () => {
             if (widget.component) return widget.component;
 
@@ -786,7 +793,9 @@ export const DashboardRenderer = forwardRef<HTMLDivElement, DashboardRendererPro
                 style={innerGridSpanStyle}
                 {...designModeProps}
             >
-                 <SchemaRenderer schema={componentSchema} className={cn("h-full w-full", designMode && "pointer-events-none")} dataSource={dataSource} />
+                 {datasetBound
+                   ? <div className={cn("h-full w-full", designMode && "pointer-events-none")}><DatasetWidget widget={widget} dataSource={dataSource} /></div>
+                   : <SchemaRenderer schema={componentSchema} className={cn("h-full w-full", designMode && "pointer-events-none")} dataSource={dataSource} />}
                  {designMode && <div className="absolute inset-0 z-10" aria-hidden="true" data-testid="widget-click-overlay" />}
             </div>
         ) : (
@@ -813,7 +822,9 @@ export const DashboardRenderer = forwardRef<HTMLDivElement, DashboardRendererPro
                 )}
                 <CardContent className="p-0">
                     <div className={cn("h-full w-full", "p-3 sm:p-4 md:p-6", designMode && "pointer-events-none")}>
-                        <SchemaRenderer schema={componentSchema} dataSource={dataSource} />
+                        {datasetBound
+                          ? <DatasetWidget widget={widget} dataSource={dataSource} />
+                          : <SchemaRenderer schema={componentSchema} dataSource={dataSource} />}
                     </div>
                 </CardContent>
                 {designMode && <div className="absolute inset-0 z-10" aria-hidden="true" data-testid="widget-click-overlay" />}
diff --git a/packages/plugin-dashboard/src/DatasetWidget.tsx b/packages/plugin-dashboard/src/DatasetWidget.tsx
new file mode 100644
index 000000000..074e2efb2
--- /dev/null
+++ b/packages/plugin-dashboard/src/DatasetWidget.tsx
@@ -0,0 +1,98 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * DatasetWidget — renders a dashboard widget that binds to a semantic-layer
+ * `dataset` (ADR-0021) instead of an inline `object` + `valueField` query.
+ *
+ * It selects the dataset's dimensions/measures BY NAME and runs them through
+ * `dataSource.queryDataset` — the same governed path the dataset preview and
+ * dataset-bound reports use — so the numbers match everywhere. A `metric`
+ * widget shows the single measure value; other types render a bar chart via the
+ * shared chart registry (`bar-chart`). Errors surface instead of silently
+ * showing wrong/empty numbers.
+ *
+ * Field access goes through `as any` because the bundled `@object-ui/types`
+ * `DashboardWidgetSchema` only gains `dataset`/`dimensions`/`values` once
+ * objectui bumps its `@objectstack/spec` dependency (cross-repo spec skew).
+ */
+
+import { useEffect, useMemo, useState } from 'react';
+import { SchemaRenderer } from '@object-ui/react';
+import { cn } from '@object-ui/components';
+import { Loader2, BarChart3, AlertTriangle } from 'lucide-react';
+
+type Row = Record<string, unknown>;
+interface DatasetCapableSource {
+  queryDataset?: (dataset: string, selection: unknown) => Promise<{ rows: Row[] }>;
+}
+
+function formatValue(v: unknown): string {
+  if (v == null) return '—';
+  if (typeof v === 'number') return Number.isInteger(v) ? String(v) : v.toLocaleString(undefined, { maximumFractionDigits: 2 });
+  return String(v);
+}
+
+export function DatasetWidget({ widget, dataSource }: { widget: any; dataSource: unknown }) {
+  const datasetName = String(widget?.dataset ?? '');
+  const dimensions: string[] = useMemo(() => (Array.isArray(widget?.dimensions) ? widget.dimensions.filter(Boolean) : []), [widget]);
+  const values: string[] = useMemo(() => (Array.isArray(widget?.values) ? widget.values.filter(Boolean) : []), [widget]);
+  const compareTo = widget?.compareTo;
+  const isMetric = widget?.type === 'metric' || dimensions.length === 0;
+
+  const [state, setState] = useState<{ status: 'idle' | 'loading' | 'ok' | 'error'; rows: Row[]; error?: string }>({ status: 'idle', rows: [] });
+
+  const signature = `${datasetName}|${dimensions.join(',')}|${values.join(',')}`;
+  useEffect(() => {
+    const src = dataSource as DatasetCapableSource | undefined;
+    if (!src || typeof src.queryDataset !== 'function') {
+      setState({ status: 'error', rows: [], error: 'This data source does not support dataset queries.' });
+      return;
+    }
+    if (values.length === 0) { setState({ status: 'idle', rows: [] }); return; }
+    let cancelled = false;
+    setState({ status: 'loading', rows: [] });
+    src.queryDataset(datasetName, { dimensions, measures: values, ...(compareTo ? { compareTo } : {}) })
+      .then((res) => { if (!cancelled) setState({ status: 'ok', rows: Array.isArray(res?.rows) ? res.rows : [] }); })
+      .catch((e) => { if (!cancelled) setState({ status: 'error', rows: [], error: String((e as Error)?.message ?? e) }); });
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [signature]);
+
+  if (values.length === 0) {
+    return <div className="flex h-full w-full items-center justify-center rounded border border-dashed bg-muted/20 p-4 text-xs text-muted-foreground">Pick measures (values) for this dataset widget.</div>;
+  }
+  if (state.status === 'loading' || state.status === 'idle') {
+    return <div className="flex h-full w-full items-center justify-center p-4 text-muted-foreground"><Loader2 className="h-4 w-4 animate-spin" /></div>;
+  }
+  if (state.status === 'error') {
+    return (
+      <div role="alert" className="flex h-full w-full items-start gap-2 rounded border border-destructive/40 bg-destructive/5 p-3 text-xs text-destructive">
+        <AlertTriangle className="h-3.5 w-3.5 mt-0.5 shrink-0" /><span className="break-words">{state.error}</span>
+      </div>
+    );
+  }
+  if (state.rows.length === 0) {
+    return <div className="flex h-full w-full items-center justify-center rounded border border-dashed bg-muted/20 p-4 text-xs text-muted-foreground"><BarChart3 className="mr-2 h-4 w-4" />No rows</div>;
+  }
+
+  // Metric / KPI — show the single measure value of the first row.
+  if (isMetric) {
+    const value = state.rows[0]?.[values[0]];
+    return (
+      <div className="flex h-full w-full flex-col items-start justify-center gap-1 p-2">
+        <span className="text-2xl font-semibold tabular-nums">{formatValue(value)}</span>
+        <span className="text-xs text-muted-foreground">{values[0]}</span>
+      </div>
+    );
+  }
+
+  // Chart — bar chart of the first measure over the first dimension, via the
+  // shared chart registry (`bar-chart`).
+  return (
+    <div className={cn('h-full w-full min-h-[220px]')}>
+      <SchemaRenderer
+        schema={{ type: 'bar-chart', data: state.rows, xAxisKey: dimensions[0], dataKey: values[0] } as any}
+      />
+    </div>
+  );
+}
diff --git a/packages/plugin-dashboard/src/__tests__/DatasetWidget.test.tsx b/packages/plugin-dashboard/src/__tests__/DatasetWidget.test.tsx
new file mode 100644
index 000000000..ba3c46c17
--- /dev/null
+++ b/packages/plugin-dashboard/src/__tests__/DatasetWidget.test.tsx
@@ -0,0 +1,48 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, cleanup, waitFor } from '@testing-library/react';
+import { DatasetWidget } from '../DatasetWidget';
+
+afterEach(cleanup);
+
+const makeSource = (impl: (d: string, s: any) => Promise<{ rows: any[] }>) => ({ queryDataset: vi.fn(impl) });
+
+describe('DatasetWidget', () => {
+  it('renders a KPI value for a metric widget', async () => {
+    const src = makeSource(async () => ({ rows: [{ revenue: 510000 }] }));
+    render(<DatasetWidget widget={{ type: 'metric', dataset: 'sales', values: ['revenue'] }} dataSource={src} />);
+    expect(await screen.findByText('510000')).toBeInTheDocument();
+    expect(src.queryDataset).toHaveBeenCalledWith('sales', { dimensions: [], measures: ['revenue'] });
+  });
+
+  it('runs the dataset query for a dimensioned (chart) widget — rows→dimensions, values→measures', async () => {
+    const src = makeSource(async () => ({ rows: [{ stage: 'won', revenue: 100 }, { stage: 'lost', revenue: 20 }] }));
+    render(<DatasetWidget widget={{ type: 'bar', dataset: 'sales', dimensions: ['stage'], values: ['revenue'] }} dataSource={src} />);
+    await waitFor(() => expect(src.queryDataset).toHaveBeenCalledWith('sales', { dimensions: ['stage'], measures: ['revenue'] }));
+  });
+
+  it('forwards compareTo when set', async () => {
+    const src = makeSource(async () => ({ rows: [{ revenue: 1 }] }));
+    render(<DatasetWidget widget={{ type: 'metric', dataset: 'sales', values: ['revenue'], compareTo: 'previousPeriod' }} dataSource={src} />);
+    await waitFor(() => expect(src.queryDataset).toHaveBeenCalledWith('sales', { dimensions: [], measures: ['revenue'], compareTo: 'previousPeriod' }));
+  });
+
+  it('surfaces a dataset error instead of wrong numbers', async () => {
+    const src = makeSource(async () => { throw new Error('relationship "account" not declared'); });
+    render(<DatasetWidget widget={{ type: 'metric', dataset: 'sales', values: ['revenue'] }} dataSource={src} />);
+    expect(await screen.findByText(/not declared/)).toBeInTheDocument();
+  });
+
+  it('errors when the data source cannot run dataset queries', async () => {
+    render(<DatasetWidget widget={{ type: 'metric', dataset: 'sales', values: ['revenue'] }} dataSource={{}} />);
+    await waitFor(() => expect(screen.getByText(/does not support dataset queries/)).toBeInTheDocument());
+  });
+
+  it('prompts when no measures are selected (no query run)', () => {
+    const src = makeSource(async () => ({ rows: [] }));
+    render(<DatasetWidget widget={{ type: 'bar', dataset: 'sales', dimensions: ['stage'], values: [] }} dataSource={src} />);
+    expect(screen.getByText(/Pick measures/)).toBeInTheDocument();
+    expect(src.queryDataset).not.toHaveBeenCalled();
+  });
+});