@quantumwake/terminal-ux-dashboard-components 0.1.18 → 0.1.20

package/dist/index.d.cts

@@ -71,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;
@@ -87,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;
@@ -101,6 +104,12 @@ declare const shapeChartData: (chartType: ChartType, rows: Row[], { yFields }?:
 type LegendAnchor = 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none';
 type LegendPosition = 'start' | 'middle' | 'end';
 type TitleAlign = 'left' | 'center' | 'right';
+interface ChartMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
 interface ChartStyle {
     background: string;
     textColor: string;
@@ -132,8 +141,23 @@ interface ChartStyle {
     titleBold: boolean;
     titleBackground: string;
     titleColor: string;
+    height: number;
+    margin: Partial<ChartMargin> | null;
+    maxXTicks: number;
+    seriesColors: string[];
 }
 declare const DEFAULT_CHART_STYLE: ChartStyle;
+declare const DEFAULT_SERIES_COLORS: string[];
+declare const SERIES_OVERFLOW_COLOR = "#707078";
+declare const seriesColor: (i: number, style?: Partial<ChartStyle> | null) => string;
+declare const chartSizing: (style: Partial<ChartStyle> | null | undefined, defaultMargin: ChartMargin) => {
+    frameClass: string;
+    frameStyle: {
+        height?: number;
+    };
+    margin: ChartMargin;
+};
+declare function thinTicks<T>(values: T[], max: number): T[] | undefined;
 declare const LEGEND_ANCHORS: LegendAnchor[];
 declare const withStyleDefaults: (style?: Partial<ChartStyle> | null) => ChartStyle;
 declare const buildNivoTheme: (style?: Partial<ChartStyle> | null) => {
@@ -215,10 +239,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;
@@ -288,6 +332,16 @@ interface LineViewProps {
 }
 declare function LineView({ records, xColumn, yColumn, data: presetData, style }: LineViewProps): react.JSX.Element;
 
+interface SparklineViewProps {
+    /** The series, oldest first. */
+    data: number[];
+    /** Viewbox height in px (the svg scales to its container's width). */
+    height?: number;
+    /** Line + area hue. */
+    color?: string;
+}
+declare function SparklineView({ data, height, color }: SparklineViewProps): react.JSX.Element;
+
 interface ScatterSerie {
     id: string;
     data: {
@@ -312,7 +366,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;
@@ -320,8 +374,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>;
@@ -333,6 +387,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[];
 }
@@ -383,6 +473,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;
@@ -462,7 +560,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;
@@ -539,4 +637,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, 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, 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 ChartMargin, type ChartPanel, type ChartStyle, ChartStyleControls, type ChartStyleControlsProps, type ChartType, type ColorMethod, type ColorOptions, type ColorScope, DEFAULT_CHART_STYLE, DEFAULT_SERIES_COLORS, 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, SERIES_OVERFLOW_COLOR, type SavedDashboard, type ScatterSerie, ScatterView, type ScatterViewProps, SparklineView, type SparklineViewProps, SqlConsole, type SqlConsoleColumn, type SqlConsoleProps, type TitleAlign, aggExpr, aggregate, axisLegend, buildChartSQL, buildNivoTheme, chartSizing, compileWhere, groupBy, heatColor, heatLabelColor, legendConfig, normalizeCells, qIdent, qLit, seriesColor, shapeChartData, thinTicks, useCapabilities, useDashboard, withStyleDefaults };

package/dist/index.d.ts

@@ -71,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;
@@ -87,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;
@@ -101,6 +104,12 @@ declare const shapeChartData: (chartType: ChartType, rows: Row[], { yFields }?:
 type LegendAnchor = 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none';
 type LegendPosition = 'start' | 'middle' | 'end';
 type TitleAlign = 'left' | 'center' | 'right';
+interface ChartMargin {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
 interface ChartStyle {
     background: string;
     textColor: string;
@@ -132,8 +141,23 @@ interface ChartStyle {
     titleBold: boolean;
     titleBackground: string;
     titleColor: string;
+    height: number;
+    margin: Partial<ChartMargin> | null;
+    maxXTicks: number;
+    seriesColors: string[];
 }
 declare const DEFAULT_CHART_STYLE: ChartStyle;
+declare const DEFAULT_SERIES_COLORS: string[];
+declare const SERIES_OVERFLOW_COLOR = "#707078";
+declare const seriesColor: (i: number, style?: Partial<ChartStyle> | null) => string;
+declare const chartSizing: (style: Partial<ChartStyle> | null | undefined, defaultMargin: ChartMargin) => {
+    frameClass: string;
+    frameStyle: {
+        height?: number;
+    };
+    margin: ChartMargin;
+};
+declare function thinTicks<T>(values: T[], max: number): T[] | undefined;
 declare const LEGEND_ANCHORS: LegendAnchor[];
 declare const withStyleDefaults: (style?: Partial<ChartStyle> | null) => ChartStyle;
 declare const buildNivoTheme: (style?: Partial<ChartStyle> | null) => {
@@ -215,10 +239,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;
@@ -288,6 +332,16 @@ interface LineViewProps {
 }
 declare function LineView({ records, xColumn, yColumn, data: presetData, style }: LineViewProps): react.JSX.Element;
 
+interface SparklineViewProps {
+    /** The series, oldest first. */
+    data: number[];
+    /** Viewbox height in px (the svg scales to its container's width). */
+    height?: number;
+    /** Line + area hue. */
+    color?: string;
+}
+declare function SparklineView({ data, height, color }: SparklineViewProps): react.JSX.Element;
+
 interface ScatterSerie {
     id: string;
     data: {
@@ -312,7 +366,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;
@@ -320,8 +374,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>;
@@ -333,6 +387,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[];
 }
@@ -383,6 +473,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;
@@ -462,7 +560,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;
@@ -539,4 +637,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, 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, 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 ChartMargin, type ChartPanel, type ChartStyle, ChartStyleControls, type ChartStyleControlsProps, type ChartType, type ColorMethod, type ColorOptions, type ColorScope, DEFAULT_CHART_STYLE, DEFAULT_SERIES_COLORS, 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, SERIES_OVERFLOW_COLOR, type SavedDashboard, type ScatterSerie, ScatterView, type ScatterViewProps, SparklineView, type SparklineViewProps, SqlConsole, type SqlConsoleColumn, type SqlConsoleProps, type TitleAlign, aggExpr, aggregate, axisLegend, buildChartSQL, buildNivoTheme, chartSizing, compileWhere, groupBy, heatColor, heatLabelColor, legendConfig, normalizeCells, qIdent, qLit, seriesColor, shapeChartData, thinTicks, useCapabilities, useDashboard, withStyleDefaults };