@quantumwake/terminal-ux-dashboard-components 0.1.17 → 0.1.19

package/dist/index.d.cts

@@ -32,6 +32,12 @@ interface DashboardCapabilities {
     removePanel?: (panelId: string) => void;
     persistPanelData?: (panelId: string, rows: QueryResult['rows'], refreshedAt: string) => void;
     persistLayout?: (items: PanelLayout[]) => void;
+    panelHeaderExtra?: (panel: PanelRef) => ReactNode;
+}
+interface PanelRef {
+    id: string;
+    type: string;
+    title?: string;
 }
 interface PanelLayout {
     id: string;
@@ -65,7 +71,7 @@ declare function useCapabilities(): {
     canEditLayout: boolean;
 };
 
-type ChartType = 'bar' | 'grouped-bar' | 'pie' | 'line' | 'scatter' | 'heatmap';
+type ChartType = 'bar' | 'grouped-bar' | 'pie' | 'line' | 'scatter' | 'heatmap' | 'heatmap-plus';
 interface ChartField {
     name: string;
     agg?: string;
@@ -81,13 +87,16 @@ interface ChartConfig {
     yFields?: ChartField[];
     valueField?: ChartField | null;
     filters?: ChartFilter[];
+    labelStat?: string;
+    colorStat?: string;
+    blockField?: string;
 }
 type Row = Record<string, unknown>;
 declare const qIdent: (name: string) => string;
 declare const qLit: (v: unknown) => string;
 declare const aggExpr: (agg: string | undefined, col?: string) => string;
 declare const compileWhere: (filters?: ChartFilter[]) => string;
-declare const buildChartSQL: ({ chartType, xFields, yFields, valueField, filters, }: ChartConfig) => string | null;
+declare const buildChartSQL: ({ chartType, xFields, yFields, valueField, filters, labelStat, colorStat, blockField, }: ChartConfig) => string | null;
 declare const shapeChartData: (chartType: ChartType, rows: Row[], { yFields }?: {
     yFields?: ChartField[];
 }) => unknown;
@@ -209,10 +218,30 @@ declare const axisLegend: (style: Partial<ChartStyle> | null | undefined, axis:
     numeric?: boolean;
 }) => Record<string, unknown>;
 
-type AggFn = 'count' | 'distinct' | 'sum' | 'avg' | 'min' | 'max';
+type AggFn = 'count' | 'distinct' | 'sum' | 'avg' | 'min' | 'max' | 'median';
 declare const groupBy: (records: Row[], column: string) => Record<string, Row[]>;
 declare const aggregate: (records: Row[], column: string, fn: AggFn | string) => number;
 
+type HeatStat = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'median';
+type ColorScope = 'global' | 'row' | 'column' | 'block';
+type ColorMethod = 'linear' | 'rank';
+declare const HEAT_STATS: HeatStat[];
+interface HeatCell {
+    row: string;
+    col: string;
+    colorValue: number;
+    block?: string;
+}
+interface ColorOptions {
+    scope?: ColorScope;
+    method?: ColorMethod;
+    vmin?: number;
+    vmax?: number;
+}
+declare const normalizeCells: (cells: HeatCell[], { scope, method, vmin, vmax }?: ColorOptions) => Map<string, number>;
+declare const heatColor: (t: number) => string;
+declare const heatLabelColor: (t: number) => string;
+
 interface MetricConfig {
     column: string;
     agg?: string;
@@ -306,7 +335,7 @@ interface HeatmapSerie {
         y: number;
     }[];
 }
-type AxisOrder = 'alpha' | 'total-asc' | 'total-desc';
+type AxisOrder$1 = 'alpha' | 'total-asc' | 'total-desc';
 interface HeatmapViewProps {
     records?: Row[];
     rowColumn: string;
@@ -314,8 +343,8 @@ interface HeatmapViewProps {
     valueColumn?: string;
     aggFn?: string;
     data?: HeatmapSerie[];
-    rowOrder?: AxisOrder;
-    colOrder?: AxisOrder;
+    rowOrder?: AxisOrder$1;
+    colOrder?: AxisOrder$1;
     marginAgg?: string;
     showTotals?: boolean;
     style?: Partial<ChartStyle>;
@@ -327,6 +356,42 @@ interface HeatmapViewProps {
  */
 declare function HeatmapView({ records, rowColumn, colColumn, valueColumn, aggFn, data: presetData, rowOrder, colOrder, marginAgg, showTotals, style, }: HeatmapViewProps): react.JSX.Element;
 
+interface HeatPlusDatum {
+    r: string | null;
+    c: string | null;
+    lv: number;
+    cv: number;
+    gr?: number;
+    gc?: number;
+    block?: string;
+}
+type AxisOrder = 'alpha' | 'margin-asc' | 'margin-desc' | 'total-asc' | 'total-desc';
+interface HeatmapPlusViewProps {
+    records?: Row[];
+    rowColumn: string;
+    colColumn: string;
+    valueColumn?: string;
+    labelStat?: HeatStat;
+    colorStat?: HeatStat;
+    blockField?: string;
+    data?: HeatPlusDatum[];
+    scope?: ColorScope;
+    method?: ColorMethod;
+    vmin?: number;
+    vmax?: number;
+    rowOrder?: AxisOrder;
+    colOrder?: AxisOrder;
+    showMargins?: boolean;
+    style?: Partial<ChartStyle>;
+}
+/**
+ * HeatmapPlusView — a cross-tab heatmap with independent label/color stats,
+ * margins computed over the underlying rows, and a scope/method color engine
+ * (see heatmapColor.ts). nivo's built-in scales normalize globally, so colors
+ * are precomputed per cell here and handed to nivo as a function.
+ */
+declare function HeatmapPlusView({ records, rowColumn, colColumn, valueColumn, labelStat, colorStat, blockField, data: presetData, scope, method, vmin, vmax, rowOrder, colOrder, showMargins, style, }: HeatmapPlusViewProps): react.JSX.Element;
+
 interface PivotViewProps {
     records?: Row[];
 }
@@ -377,6 +442,14 @@ interface PanelConfig {
     colOrder?: string;
     marginAgg?: string;
     showTotals?: boolean;
+    labelStat?: string;
+    colorStat?: string;
+    blockField?: string;
+    scope?: string;
+    method?: string;
+    vmin?: number;
+    vmax?: number;
+    showMargins?: boolean;
     columns?: string[];
     text?: string;
     label?: string;
@@ -408,6 +481,19 @@ interface DashboardRendererProps {
     records?: Row[];
     columns?: ColumnDef[];
 }
+interface PanelContentProps {
+    panel: DashboardPanel$1;
+    records?: Row[];
+    columns?: ColumnDef[];
+}
+/**
+ * Renders a single dashboard panel based on its type and config.
+ * Panels saved with a SQL query render server-side (full dataset); the rest
+ * fall back to client-side aggregation over the loaded records.
+ */
+declare function PanelContent({ panel, records, columns }: PanelContentProps): react.JSX.Element | null;
+declare const PanelChart: typeof PanelContent;
+type PanelChartProps = PanelContentProps;
 /**
  * DashboardRenderer — renders a grid of AI-generated or manually configured
  * panels via react-grid-layout. Editing is capability-gated:
@@ -443,7 +529,7 @@ interface Column {
     name: string;
     type: string;
 }
-/** A selectable state (dataset) in the statefs catalog. */
+/** A selectable state (dataset) in the host's catalog. */
 interface StatefsState {
     state_id: string;
     row_count?: number;
@@ -520,4 +606,4 @@ interface DataExplorerProps {
 }
 declare function DataExplorer({ records, columns, states, activeStateId, profile, dashboard, dashboardId, savedDashboards, loading, analyzing, defaultMode, tabs, onSelectState, onRefreshStates, }: DataExplorerProps): react.JSX.Element;
 
-export { type AggFn, type BarDatum, BarView, type BarViewProps, ChartBuilder, type ChartBuilderColumn, type ChartBuilderProps, type ChartConfig, type ChartField, type ChartFilter, type ChartPanel, type ChartStyle, ChartStyleControls, type ChartStyleControlsProps, type ChartType, DEFAULT_CHART_STYLE, type Dashboard$1 as Dashboard, type DashboardCapabilities, type DashboardContextValue, type DashboardPanel$1 as DashboardPanel, DashboardProvider, type DashboardProviderProps, DashboardRenderer, type DashboardRendererProps, type DashboardTheme, DataExplorer, type DataExplorerProps, type HeatmapSerie, HeatmapView, type HeatmapViewProps, type InsightConfig, InsightView, type InsightViewProps, LEGEND_ANCHORS, type LegendAnchor, type LegendPosition, type LineSerie, LineView, type LineViewProps, type MetricConfig, MetricView, type MetricViewProps, type PanelInput, type PanelLayout, type PieDatum, PieView, type PieViewProps, PivotView, type PivotViewProps, type QueryResult, type Row, type SavedDashboard, type ScatterSerie, ScatterView, type ScatterViewProps, SqlConsole, type SqlConsoleColumn, type SqlConsoleProps, type TitleAlign, aggExpr, aggregate, axisLegend, buildChartSQL, buildNivoTheme, compileWhere, groupBy, legendConfig, qIdent, qLit, shapeChartData, useCapabilities, useDashboard, withStyleDefaults };
+export { type AggFn, type BarDatum, BarView, type BarViewProps, ChartBuilder, type ChartBuilderColumn, type ChartBuilderProps, type ChartConfig, type ChartField, type ChartFilter, type ChartPanel, type ChartStyle, ChartStyleControls, type ChartStyleControlsProps, type ChartType, type ColorMethod, type ColorOptions, type ColorScope, DEFAULT_CHART_STYLE, type Dashboard$1 as Dashboard, type DashboardCapabilities, type DashboardContextValue, type DashboardPanel$1 as DashboardPanel, DashboardProvider, type DashboardProviderProps, DashboardRenderer, type DashboardRendererProps, type DashboardTheme, DataExplorer, type DataExplorerProps, HEAT_STATS, type HeatCell, type HeatPlusDatum, type HeatStat, HeatmapPlusView, type HeatmapPlusViewProps, type HeatmapSerie, HeatmapView, type HeatmapViewProps, type InsightConfig, InsightView, type InsightViewProps, LEGEND_ANCHORS, type LegendAnchor, type LegendPosition, type LineSerie, LineView, type LineViewProps, type MetricConfig, MetricView, type MetricViewProps, PanelChart, type PanelChartProps, type PanelInput, type PanelLayout, type PanelRef, type PieDatum, PieView, type PieViewProps, PivotView, type PivotViewProps, type QueryResult, type Row, type SavedDashboard, type ScatterSerie, ScatterView, type ScatterViewProps, SqlConsole, type SqlConsoleColumn, type SqlConsoleProps, type TitleAlign, aggExpr, aggregate, axisLegend, buildChartSQL, buildNivoTheme, compileWhere, groupBy, heatColor, heatLabelColor, legendConfig, normalizeCells, qIdent, qLit, shapeChartData, useCapabilities, useDashboard, withStyleDefaults };

package/dist/index.d.ts

@@ -32,6 +32,12 @@ interface DashboardCapabilities {
     removePanel?: (panelId: string) => void;
     persistPanelData?: (panelId: string, rows: QueryResult['rows'], refreshedAt: string) => void;
     persistLayout?: (items: PanelLayout[]) => void;
+    panelHeaderExtra?: (panel: PanelRef) => ReactNode;
+}
+interface PanelRef {
+    id: string;
+    type: string;
+    title?: string;
 }
 interface PanelLayout {
     id: string;
@@ -65,7 +71,7 @@ declare function useCapabilities(): {
     canEditLayout: boolean;
 };
 
-type ChartType = 'bar' | 'grouped-bar' | 'pie' | 'line' | 'scatter' | 'heatmap';
+type ChartType = 'bar' | 'grouped-bar' | 'pie' | 'line' | 'scatter' | 'heatmap' | 'heatmap-plus';
 interface ChartField {
     name: string;
     agg?: string;
@@ -81,13 +87,16 @@ interface ChartConfig {
     yFields?: ChartField[];
     valueField?: ChartField | null;
     filters?: ChartFilter[];
+    labelStat?: string;
+    colorStat?: string;
+    blockField?: string;
 }
 type Row = Record<string, unknown>;
 declare const qIdent: (name: string) => string;
 declare const qLit: (v: unknown) => string;
 declare const aggExpr: (agg: string | undefined, col?: string) => string;
 declare const compileWhere: (filters?: ChartFilter[]) => string;
-declare const buildChartSQL: ({ chartType, xFields, yFields, valueField, filters, }: ChartConfig) => string | null;
+declare const buildChartSQL: ({ chartType, xFields, yFields, valueField, filters, labelStat, colorStat, blockField, }: ChartConfig) => string | null;
 declare const shapeChartData: (chartType: ChartType, rows: Row[], { yFields }?: {
     yFields?: ChartField[];
 }) => unknown;
@@ -209,10 +218,30 @@ declare const axisLegend: (style: Partial<ChartStyle> | null | undefined, axis:
     numeric?: boolean;
 }) => Record<string, unknown>;
 
-type AggFn = 'count' | 'distinct' | 'sum' | 'avg' | 'min' | 'max';
+type AggFn = 'count' | 'distinct' | 'sum' | 'avg' | 'min' | 'max' | 'median';
 declare const groupBy: (records: Row[], column: string) => Record<string, Row[]>;
 declare const aggregate: (records: Row[], column: string, fn: AggFn | string) => number;
 
+type HeatStat = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'median';
+type ColorScope = 'global' | 'row' | 'column' | 'block';
+type ColorMethod = 'linear' | 'rank';
+declare const HEAT_STATS: HeatStat[];
+interface HeatCell {
+    row: string;
+    col: string;
+    colorValue: number;
+    block?: string;
+}
+interface ColorOptions {
+    scope?: ColorScope;
+    method?: ColorMethod;
+    vmin?: number;
+    vmax?: number;
+}
+declare const normalizeCells: (cells: HeatCell[], { scope, method, vmin, vmax }?: ColorOptions) => Map<string, number>;
+declare const heatColor: (t: number) => string;
+declare const heatLabelColor: (t: number) => string;
+
 interface MetricConfig {
     column: string;
     agg?: string;
@@ -306,7 +335,7 @@ interface HeatmapSerie {
         y: number;
     }[];
 }
-type AxisOrder = 'alpha' | 'total-asc' | 'total-desc';
+type AxisOrder$1 = 'alpha' | 'total-asc' | 'total-desc';
 interface HeatmapViewProps {
     records?: Row[];
     rowColumn: string;
@@ -314,8 +343,8 @@ interface HeatmapViewProps {
     valueColumn?: string;
     aggFn?: string;
     data?: HeatmapSerie[];
-    rowOrder?: AxisOrder;
-    colOrder?: AxisOrder;
+    rowOrder?: AxisOrder$1;
+    colOrder?: AxisOrder$1;
     marginAgg?: string;
     showTotals?: boolean;
     style?: Partial<ChartStyle>;
@@ -327,6 +356,42 @@ interface HeatmapViewProps {
  */
 declare function HeatmapView({ records, rowColumn, colColumn, valueColumn, aggFn, data: presetData, rowOrder, colOrder, marginAgg, showTotals, style, }: HeatmapViewProps): react.JSX.Element;
 
+interface HeatPlusDatum {
+    r: string | null;
+    c: string | null;
+    lv: number;
+    cv: number;
+    gr?: number;
+    gc?: number;
+    block?: string;
+}
+type AxisOrder = 'alpha' | 'margin-asc' | 'margin-desc' | 'total-asc' | 'total-desc';
+interface HeatmapPlusViewProps {
+    records?: Row[];
+    rowColumn: string;
+    colColumn: string;
+    valueColumn?: string;
+    labelStat?: HeatStat;
+    colorStat?: HeatStat;
+    blockField?: string;
+    data?: HeatPlusDatum[];
+    scope?: ColorScope;
+    method?: ColorMethod;
+    vmin?: number;
+    vmax?: number;
+    rowOrder?: AxisOrder;
+    colOrder?: AxisOrder;
+    showMargins?: boolean;
+    style?: Partial<ChartStyle>;
+}
+/**
+ * HeatmapPlusView — a cross-tab heatmap with independent label/color stats,
+ * margins computed over the underlying rows, and a scope/method color engine
+ * (see heatmapColor.ts). nivo's built-in scales normalize globally, so colors
+ * are precomputed per cell here and handed to nivo as a function.
+ */
+declare function HeatmapPlusView({ records, rowColumn, colColumn, valueColumn, labelStat, colorStat, blockField, data: presetData, scope, method, vmin, vmax, rowOrder, colOrder, showMargins, style, }: HeatmapPlusViewProps): react.JSX.Element;
+
 interface PivotViewProps {
     records?: Row[];
 }
@@ -377,6 +442,14 @@ interface PanelConfig {
     colOrder?: string;
     marginAgg?: string;
     showTotals?: boolean;
+    labelStat?: string;
+    colorStat?: string;
+    blockField?: string;
+    scope?: string;
+    method?: string;
+    vmin?: number;
+    vmax?: number;
+    showMargins?: boolean;
     columns?: string[];
     text?: string;
     label?: string;
@@ -408,6 +481,19 @@ interface DashboardRendererProps {
     records?: Row[];
     columns?: ColumnDef[];
 }
+interface PanelContentProps {
+    panel: DashboardPanel$1;
+    records?: Row[];
+    columns?: ColumnDef[];
+}
+/**
+ * Renders a single dashboard panel based on its type and config.
+ * Panels saved with a SQL query render server-side (full dataset); the rest
+ * fall back to client-side aggregation over the loaded records.
+ */
+declare function PanelContent({ panel, records, columns }: PanelContentProps): react.JSX.Element | null;
+declare const PanelChart: typeof PanelContent;
+type PanelChartProps = PanelContentProps;
 /**
  * DashboardRenderer — renders a grid of AI-generated or manually configured
  * panels via react-grid-layout. Editing is capability-gated:
@@ -443,7 +529,7 @@ interface Column {
     name: string;
     type: string;
 }
-/** A selectable state (dataset) in the statefs catalog. */
+/** A selectable state (dataset) in the host's catalog. */
 interface StatefsState {
     state_id: string;
     row_count?: number;
@@ -520,4 +606,4 @@ interface DataExplorerProps {
 }
 declare function DataExplorer({ records, columns, states, activeStateId, profile, dashboard, dashboardId, savedDashboards, loading, analyzing, defaultMode, tabs, onSelectState, onRefreshStates, }: DataExplorerProps): react.JSX.Element;
 
-export { type AggFn, type BarDatum, BarView, type BarViewProps, ChartBuilder, type ChartBuilderColumn, type ChartBuilderProps, type ChartConfig, type ChartField, type ChartFilter, type ChartPanel, type ChartStyle, ChartStyleControls, type ChartStyleControlsProps, type ChartType, DEFAULT_CHART_STYLE, type Dashboard$1 as Dashboard, type DashboardCapabilities, type DashboardContextValue, type DashboardPanel$1 as DashboardPanel, DashboardProvider, type DashboardProviderProps, DashboardRenderer, type DashboardRendererProps, type DashboardTheme, DataExplorer, type DataExplorerProps, type HeatmapSerie, HeatmapView, type HeatmapViewProps, type InsightConfig, InsightView, type InsightViewProps, LEGEND_ANCHORS, type LegendAnchor, type LegendPosition, type LineSerie, LineView, type LineViewProps, type MetricConfig, MetricView, type MetricViewProps, type PanelInput, type PanelLayout, type PieDatum, PieView, type PieViewProps, PivotView, type PivotViewProps, type QueryResult, type Row, type SavedDashboard, type ScatterSerie, ScatterView, type ScatterViewProps, SqlConsole, type SqlConsoleColumn, type SqlConsoleProps, type TitleAlign, aggExpr, aggregate, axisLegend, buildChartSQL, buildNivoTheme, compileWhere, groupBy, legendConfig, qIdent, qLit, shapeChartData, useCapabilities, useDashboard, withStyleDefaults };
+export { type AggFn, type BarDatum, BarView, type BarViewProps, ChartBuilder, type ChartBuilderColumn, type ChartBuilderProps, type ChartConfig, type ChartField, type ChartFilter, type ChartPanel, type ChartStyle, ChartStyleControls, type ChartStyleControlsProps, type ChartType, type ColorMethod, type ColorOptions, type ColorScope, DEFAULT_CHART_STYLE, type Dashboard$1 as Dashboard, type DashboardCapabilities, type DashboardContextValue, type DashboardPanel$1 as DashboardPanel, DashboardProvider, type DashboardProviderProps, DashboardRenderer, type DashboardRendererProps, type DashboardTheme, DataExplorer, type DataExplorerProps, HEAT_STATS, type HeatCell, type HeatPlusDatum, type HeatStat, HeatmapPlusView, type HeatmapPlusViewProps, type HeatmapSerie, HeatmapView, type HeatmapViewProps, type InsightConfig, InsightView, type InsightViewProps, LEGEND_ANCHORS, type LegendAnchor, type LegendPosition, type LineSerie, LineView, type LineViewProps, type MetricConfig, MetricView, type MetricViewProps, PanelChart, type PanelChartProps, type PanelInput, type PanelLayout, type PanelRef, type PieDatum, PieView, type PieViewProps, PivotView, type PivotViewProps, type QueryResult, type Row, type SavedDashboard, type ScatterSerie, ScatterView, type ScatterViewProps, SqlConsole, type SqlConsoleColumn, type SqlConsoleProps, type TitleAlign, aggExpr, aggregate, axisLegend, buildChartSQL, buildNivoTheme, compileWhere, groupBy, heatColor, heatLabelColor, legendConfig, normalizeCells, qIdent, qLit, shapeChartData, useCapabilities, useDashboard, withStyleDefaults };