@quantumwake/terminal-ux-dashboard-components 0.1.8 → 0.1.12

package/dist/index.d.cts

@@ -30,6 +30,7 @@ interface DashboardCapabilities {
     newDashboard?: () => void;
     addPanel?: (panel: PanelInput) => void;
     removePanel?: (panelId: string) => void;
+    persistPanelData?: (panelId: string, rows: QueryResult['rows'], refreshedAt: string) => void;
 }
 interface DashboardContextValue extends DashboardCapabilities {
     theme: DashboardTheme;
@@ -52,6 +53,7 @@ declare function useCapabilities(): {
     canNew: boolean;
     canAddPanel: boolean;
     canEditPanels: boolean;
+    canRefresh: boolean;
 };
 
 type ChartType = 'bar' | 'grouped-bar' | 'pie' | 'line' | 'scatter' | 'heatmap';
@@ -358,6 +360,8 @@ interface PanelConfig {
     text?: string;
     label?: string;
     column?: string;
+    data?: Row[];
+    refreshedAt?: string;
     [key: string]: unknown;
 }
 interface DashboardPanel$1 {
@@ -404,13 +408,6 @@ interface ChartBuilderProps {
     stateId?: string;
     onSave?: (panel: ChartPanel) => void;
 }
-/**
- * ChartBuilder — visual chart authoring over a state's dataset. Generates DuckDB
- * SQL from the visual config (SQL engine mode, exact over the full dataset) or
- * aggregates the loaded sample client-side (Direct mode). The host injects
- * runQuery + theme via <DashboardProvider>; an optional onSave persists the
- * assembled panel (absent ⇒ the save affordance is hidden / read-only).
- */
 declare function ChartBuilder({ records, columns, stateId, onSave }: ChartBuilderProps): react.JSX.Element;
 
 /** A dataset column descriptor: name + DuckDB-ish type tag. */

package/dist/index.d.ts

@@ -30,6 +30,7 @@ interface DashboardCapabilities {
     newDashboard?: () => void;
     addPanel?: (panel: PanelInput) => void;
     removePanel?: (panelId: string) => void;
+    persistPanelData?: (panelId: string, rows: QueryResult['rows'], refreshedAt: string) => void;
 }
 interface DashboardContextValue extends DashboardCapabilities {
     theme: DashboardTheme;
@@ -52,6 +53,7 @@ declare function useCapabilities(): {
     canNew: boolean;
     canAddPanel: boolean;
     canEditPanels: boolean;
+    canRefresh: boolean;
 };
 
 type ChartType = 'bar' | 'grouped-bar' | 'pie' | 'line' | 'scatter' | 'heatmap';
@@ -358,6 +360,8 @@ interface PanelConfig {
     text?: string;
     label?: string;
     column?: string;
+    data?: Row[];
+    refreshedAt?: string;
     [key: string]: unknown;
 }
 interface DashboardPanel$1 {
@@ -404,13 +408,6 @@ interface ChartBuilderProps {
     stateId?: string;
     onSave?: (panel: ChartPanel) => void;
 }
-/**
- * ChartBuilder — visual chart authoring over a state's dataset. Generates DuckDB
- * SQL from the visual config (SQL engine mode, exact over the full dataset) or
- * aggregates the loaded sample client-side (Direct mode). The host injects
- * runQuery + theme via <DashboardProvider>; an optional onSave persists the
- * assembled panel (absent ⇒ the save affordance is hidden / read-only).
- */
 declare function ChartBuilder({ records, columns, stateId, onSave }: ChartBuilderProps): react.JSX.Element;
 
 /** A dataset column descriptor: name + DuckDB-ish type tag. */

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createContext, useContext, useMemo, useState, useEffect, useRef, Suspense } from 'react';
+import { createContext, useContext, useMemo, useState, useEffect, useRef, Suspense, useCallback } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { ResponsiveBar } from '@nivo/bar';
 import { ResponsivePie } from '@nivo/pie';
@@ -37,7 +37,9 @@ function useCapabilities() {
     canRefine: !!c.refineDashboard,
     canNew: !!c.newDashboard,
     canAddPanel: !!c.addPanel,
-    canEditPanels: !!c.removePanel
+    canEditPanels: !!c.removePanel,
+    // Studio can recompute + persist a panel's precomputed result.
+    canRefresh: !!c.persistPanelData
   };
 }
 
@@ -1339,6 +1341,7 @@ var ChartPreview = ({
       return /* @__PURE__ */ jsx("div", { className: "flex items-center justify-center h-full text-sm text-midnight-text-muted", children: "Select a chart type" });
   }
 };
+var MAX_PRECOMPUTE_ROWS = 5e3;
 function ChartBuilder({ records, columns, stateId, onSave }) {
   const { theme, runQuery } = useDashboard();
   const runQueryRef = useRef(runQuery);
@@ -1467,6 +1470,10 @@ function ChartBuilder({ records, columns, stateId, onSave }) {
       config.chartType = chartType;
       if (filters.length) config.filters = filters;
       if (yFields.length) config.yFields = yFields.map((f) => ({ name: f.name, agg: f.agg }));
+      if (sqlRows && sqlRows.length <= MAX_PRECOMPUTE_ROWS) {
+        config.data = sqlRows;
+        config.refreshedAt = (/* @__PURE__ */ new Date()).toISOString();
+      }
     }
     config.style = style;
     onSave({
@@ -1670,76 +1677,167 @@ function ChartBuilder({ records, columns, stateId, onSave }) {
 function ViewLoading() {
   return /* @__PURE__ */ jsx("div", { className: "flex items-center justify-center h-full text-xs text-midnight-text-muted", children: "Loading..." });
 }
+var SQL_CHART_TYPES = /* @__PURE__ */ new Set(["bar", "grouped-bar", "pie", "line", "scatter", "heatmap"]);
+function panelToChartConfig(chartType, config) {
+  const cfg = { chartType, xFields: [], yFields: [], filters: config.filters || [] };
+  switch (chartType) {
+    case "bar":
+    case "grouped-bar":
+      if (config.group) cfg.xFields = [{ name: config.group }];
+      cfg.yFields = config.yFields?.length ? config.yFields : config.value ? [{ name: config.value, agg: config.agg }] : [];
+      break;
+    case "pie":
+      if (config.group) cfg.xFields = [{ name: config.group }];
+      break;
+    case "line":
+    case "scatter":
+      if (config.x) cfg.xFields = [{ name: config.x }];
+      if (config.y) cfg.yFields = [{ name: config.y }];
+      break;
+    case "heatmap":
+      if (config.row) cfg.xFields = [{ name: config.row }];
+      if (config.col) cfg.yFields = [{ name: config.col }];
+      if (config.value) cfg.valueField = { name: config.value, agg: config.agg };
+      break;
+  }
+  return cfg;
+}
+function panelSql(chartType, config) {
+  if (config.sql) return config.sql;
+  if (SQL_CHART_TYPES.has(chartType)) return buildChartSQL(panelToChartConfig(chartType, config)) || "";
+  return "";
+}
 function SqlPanel({ panel }) {
-  const { runQuery } = useDashboard();
+  const { runQuery, persistPanelData } = useDashboard();
+  const { canRefresh } = useCapabilities();
   const runQueryRef = useRef(runQuery);
   runQueryRef.current = runQuery;
   const config = panel.config || {};
   const chartType = config.chartType || panel.type;
-  const [rows, setRows] = useState(null);
+  const sql = panelSql(chartType, config);
+  const precomputed = config.data;
+  const [rows, setRows] = useState(precomputed ?? null);
   const [error, setError] = useState(null);
-  const [loading, setLoading] = useState(true);
+  const [loading, setLoading] = useState(!precomputed && canRefresh);
+  const [refreshing, setRefreshing] = useState(false);
   useEffect(() => {
+    if (precomputed) {
+      setRows(precomputed);
+      setLoading(false);
+      return;
+    }
+    if (!canRefresh) {
+      setLoading(false);
+      return;
+    }
     let cancelled = false;
     setLoading(true);
     setError(null);
-    const sql = config.sql || "";
     runQueryRef.current(sql).then(
       (res) => {
-        if (cancelled) return;
-        setLoading(false);
-        setRows(res?.rows || []);
+        if (!cancelled) {
+          setLoading(false);
+          setRows(res?.rows || []);
+        }
       },
       (err) => {
-        if (cancelled) return;
-        setLoading(false);
-        setRows(null);
-        setError(err instanceof Error ? err.message : String(err) || "Query failed");
+        if (!cancelled) {
+          setLoading(false);
+          setRows(null);
+          setError(err instanceof Error ? err.message : String(err) || "Query failed");
+        }
       }
     );
     return () => {
       cancelled = true;
     };
-  }, [config.sql]);
+  }, [sql, canRefresh]);
+  const refresh = useCallback(async () => {
+    setRefreshing(true);
+    setError(null);
+    try {
+      const res = await runQueryRef.current(sql);
+      const r = res?.rows || [];
+      setRows(r);
+      persistPanelData?.(panel.id, r, (/* @__PURE__ */ new Date()).toISOString());
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err) || "Query failed");
+    } finally {
+      setRefreshing(false);
+    }
+  }, [sql, panel.id, persistPanelData]);
+  const refreshBtn = canRefresh ? /* @__PURE__ */ jsx(
+    "button",
+    {
+      onClick: refresh,
+      disabled: refreshing,
+      title: config.refreshedAt ? `Last computed ${new Date(config.refreshedAt).toLocaleString()} \u2014 click to refresh` : "Compute & save this chart\u2019s data",
+      className: "absolute top-1 right-1 z-10 p-1 bg-midnight-elevated/80 border border-midnight-border text-midnight-text-muted hover:text-midnight-accent transition-colors",
+      children: /* @__PURE__ */ jsx(RefreshCw, { className: `w-3 h-3 ${refreshing ? "animate-spin" : ""}` })
+    }
+  ) : null;
   if (loading && !rows) {
     return /* @__PURE__ */ jsx("div", { className: "flex items-center justify-center h-full text-xs text-midnight-text-muted", children: "Running\u2026" });
   }
+  if (!rows && !error && !canRefresh) {
+    return /* @__PURE__ */ jsxs("div", { className: "flex flex-col items-center justify-center h-full gap-1 px-2 text-center text-xs text-midnight-text-muted", children: [
+      /* @__PURE__ */ jsx(AlertCircle, { className: "w-4 h-4" }),
+      /* @__PURE__ */ jsx("span", { children: "Chart data not available" }),
+      /* @__PURE__ */ jsx("span", { className: "text-[10px] text-midnight-text-subdued", children: "Download the dataset to view this chart." })
+    ] });
+  }
   if (error) {
-    return /* @__PURE__ */ jsx("div", { className: "flex items-center justify-center h-full text-xs text-red-400 px-2 text-center", children: error });
+    return /* @__PURE__ */ jsxs("div", { className: "relative flex items-center justify-center h-full px-2 text-center text-xs text-red-400", children: [
+      refreshBtn,
+      error
+    ] });
   }
   if (!rows) return null;
+  let chart;
   if (chartType === "metric") {
     const first = rows[0];
     const v = first ? Object.values(first)[0] : 0;
-    return /* @__PURE__ */ jsx(MetricView, { value: Number(v) || 0, config: { column: config.column || "", agg: config.agg, label: config.label } });
-  }
-  const shaped = shapeChartData(chartType, rows, { yFields: config.yFields || [] });
-  switch (chartType) {
-    case "bar":
-      return /* @__PURE__ */ jsx(BarView, { data: shaped, groupColumn: config.group || "", valueColumn: config.value || "", style: config.style });
-    case "grouped-bar": {
-      const gb = shaped;
-      return /* @__PURE__ */ jsx(GroupedBarChart, { data: gb.data, keys: gb.keys, yFields: config.yFields || [], style: config.style });
+    chart = /* @__PURE__ */ jsx(MetricView, { value: Number(v) || 0, config: { column: config.column || "", agg: config.agg, label: config.label } });
+  } else {
+    const shaped = shapeChartData(chartType, rows, { yFields: config.yFields || [] });
+    switch (chartType) {
+      case "bar":
+        chart = /* @__PURE__ */ jsx(BarView, { data: shaped, groupColumn: config.group || "", valueColumn: config.value || "", style: config.style });
+        break;
+      case "grouped-bar": {
+        const gb = shaped;
+        chart = /* @__PURE__ */ jsx(GroupedBarChart, { data: gb.data, keys: gb.keys, yFields: config.yFields || [], style: config.style });
+        break;
+      }
+      case "pie":
+        chart = /* @__PURE__ */ jsx(PieView, { data: shaped, groupColumn: config.group || "", style: config.style });
+        break;
+      case "line":
+        chart = /* @__PURE__ */ jsx(LineView, { data: shaped, xColumn: config.x || "", yColumn: config.y || "", style: config.style });
+        break;
+      case "scatter":
+        chart = /* @__PURE__ */ jsx(ScatterView, { data: shaped, xColumn: config.x || "", yColumn: config.y || "", style: config.style });
+        break;
+      case "heatmap":
+        chart = shaped.length ? /* @__PURE__ */ jsx(HeatmapView, { data: shaped, rowColumn: config.row || "", colColumn: config.col || "", rowOrder: config.rowOrder, colOrder: config.colOrder, marginAgg: config.marginAgg, showTotals: config.showTotals, style: config.style }) : /* @__PURE__ */ jsx("div", { className: "flex items-center justify-center h-full text-xs text-midnight-text-muted", children: "No data" });
+        break;
+      default:
+        chart = /* @__PURE__ */ jsxs("div", { className: "p-4 text-xs text-midnight-text-muted", children: [
+          "Unsupported SQL chart: ",
+          chartType
+        ] });
     }
-    case "pie":
-      return /* @__PURE__ */ jsx(PieView, { data: shaped, groupColumn: config.group || "", style: config.style });
-    case "line":
-      return /* @__PURE__ */ jsx(LineView, { data: shaped, xColumn: config.x || "", yColumn: config.y || "", style: config.style });
-    case "scatter":
-      return /* @__PURE__ */ jsx(ScatterView, { data: shaped, xColumn: config.x || "", yColumn: config.y || "", style: config.style });
-    case "heatmap":
-      return shaped.length ? /* @__PURE__ */ jsx(HeatmapView, { data: shaped, rowColumn: config.row || "", colColumn: config.col || "", rowOrder: config.rowOrder, colOrder: config.colOrder, marginAgg: config.marginAgg, showTotals: config.showTotals, style: config.style }) : /* @__PURE__ */ jsx("div", { className: "flex items-center justify-center h-full text-xs text-midnight-text-muted", children: "No data" });
-    default:
-      return /* @__PURE__ */ jsxs("div", { className: "p-4 text-xs text-midnight-text-muted", children: [
-        "Unsupported SQL chart: ",
-        chartType
-      ] });
   }
+  return /* @__PURE__ */ jsxs("div", { className: "relative h-full w-full", children: [
+    refreshBtn,
+    chart
+  ] });
 }
 function PanelContent({ panel, records, columns }) {
   const { type } = panel;
   const config = panel.config || {};
-  if (config.sql) {
+  const effType = config.chartType || type;
+  if (config.sql || SQL_CHART_TYPES.has(effType)) {
     return /* @__PURE__ */ jsx(SqlPanel, { panel });
   }
   if (!records?.length && type !== "insight") {