@quantumwake/terminal-ux-dashboard-components 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,477 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type DashboardTheme = Record<string, string>;
+interface QueryResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+}
+interface SavedDashboard {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+interface DashboardCapabilities {
+    runQuery: (sql: string, stateId?: string) => Promise<QueryResult>;
+    saveDashboard?: (name?: string) => Promise<void> | void;
+    listDashboards?: () => Promise<SavedDashboard[]> | SavedDashboard[];
+    searchDashboards?: (query: string) => Promise<SavedDashboard[]> | SavedDashboard[];
+    loadDashboard?: (id: string) => Promise<void> | void;
+    deleteDashboard?: (id: string) => Promise<void> | void;
+    analyzeDataset?: () => Promise<void> | void;
+    refineDashboard?: (prompt: string) => Promise<void> | void;
+    removePanel?: (panelId: string) => void;
+}
+interface DashboardContextValue extends DashboardCapabilities {
+    theme: DashboardTheme;
+}
+interface DashboardProviderProps extends DashboardCapabilities {
+    theme: DashboardTheme;
+    children: ReactNode;
+}
+declare function DashboardProvider({ children, ...value }: DashboardProviderProps): react.JSX.Element;
+declare function useDashboard(): DashboardContextValue;
+declare function useCapabilities(): {
+    canRun: boolean;
+    canSave: boolean;
+    canList: boolean;
+    canSearch: boolean;
+    canLoad: boolean;
+    canDelete: boolean;
+    canAnalyze: boolean;
+    canRefine: boolean;
+    canEditPanels: boolean;
+};
+
+type ChartType = 'bar' | 'grouped-bar' | 'pie' | 'line' | 'scatter' | 'heatmap';
+interface ChartField {
+    name: string;
+    agg?: string;
+}
+interface ChartFilter {
+    column: string;
+    op: string;
+    value?: string | null;
+}
+interface ChartConfig {
+    chartType: ChartType;
+    xFields?: ChartField[];
+    yFields?: ChartField[];
+    valueField?: ChartField | null;
+    filters?: ChartFilter[];
+}
+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 shapeChartData: (chartType: ChartType, rows: Row[], { yFields }?: {
+    yFields?: ChartField[];
+}) => unknown;
+
+type LegendAnchor = 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'none';
+type LegendPosition = 'start' | 'middle' | 'end';
+type TitleAlign = 'left' | 'center' | 'right';
+interface ChartStyle {
+    background: string;
+    textColor: string;
+    legendColor: string;
+    fontSize: number;
+    gridColor: string;
+    tooltipBg: string;
+    tooltipColor: string;
+    xLegendPosition: LegendPosition;
+    xLegendOffset: number;
+    yLegendPosition: LegendPosition;
+    yLegendOffset: number;
+    legendAnchor: LegendAnchor;
+    titleAlign: TitleAlign;
+}
+declare const DEFAULT_CHART_STYLE: ChartStyle;
+declare const LEGEND_ANCHORS: LegendAnchor[];
+declare const withStyleDefaults: (style?: Partial<ChartStyle> | null) => ChartStyle;
+declare const buildNivoTheme: (style?: Partial<ChartStyle> | null) => {
+    background: string;
+    text: {
+        fill: string;
+        fontSize: number;
+    };
+    axis: {
+        ticks: {
+            text: {
+                fill: string;
+                fontSize: number;
+            };
+        };
+        legend: {
+            text: {
+                fill: string;
+                fontSize: number;
+            };
+        };
+    };
+    grid: {
+        line: {
+            stroke: string;
+        };
+    };
+    crosshair: {
+        line: {
+            stroke: string;
+            strokeDasharray: string;
+        };
+    };
+    labels: {
+        text: {
+            fontSize: number;
+        };
+    };
+    legends: {
+        text: {
+            fill: string;
+            fontSize: number;
+        };
+    };
+    tooltip: {
+        container: {
+            background: string;
+            color: string;
+            border: string;
+        };
+    };
+};
+declare const legendConfig: (style?: Partial<ChartStyle> | null) => {
+    translateX: number;
+    anchor: "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    direction: "column";
+    itemWidth: number;
+    itemHeight: number;
+    itemsSpacing: number;
+    symbolSize: number;
+    symbolShape: "circle";
+    itemTextColor: string;
+} | {
+    translateX: number;
+    translateY: number;
+    anchor: "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+    direction: "column";
+    itemWidth: number;
+    itemHeight: number;
+    itemsSpacing: number;
+    symbolSize: number;
+    symbolShape: "circle";
+    itemTextColor: string;
+} | null;
+declare const axisLegend: (style: Partial<ChartStyle> | null | undefined, axis: "x" | "y", legendText: string) => {
+    legend: string;
+    legendPosition: LegendPosition;
+    legendOffset: number;
+};
+
+type AggFn = 'count' | 'distinct' | 'sum' | 'avg' | 'min' | 'max';
+declare const groupBy: (records: Row[], column: string) => Record<string, Row[]>;
+declare const aggregate: (records: Row[], column: string, fn: AggFn | string) => number;
+
+interface MetricConfig {
+    column: string;
+    agg?: string;
+    label?: string;
+}
+interface MetricViewProps {
+    records?: Row[];
+    config: MetricConfig;
+    /** Pre-computed value bypasses client-side aggregation. */
+    value?: number | string | null;
+}
+/** Single-number metric card. Shows a big number with a label. */
+declare function MetricView({ records, config, value: presetValue }: MetricViewProps): react.JSX.Element;
+
+interface InsightConfig {
+    text?: string;
+}
+interface InsightViewProps {
+    config: InsightConfig;
+}
+/** Text insight card rendered from AI analysis. */
+declare function InsightView({ config }: InsightViewProps): react.JSX.Element;
+
+interface BarDatum {
+    group: string;
+    value: number;
+}
+interface BarViewProps {
+    records?: Row[];
+    groupColumn: string;
+    valueColumn: string;
+    aggFn?: string;
+    /** Pre-aggregated [{group, value}] bypasses client-side aggregation. */
+    data?: BarDatum[];
+    style?: Partial<ChartStyle>;
+}
+declare function BarView({ records, groupColumn, valueColumn, aggFn, data: presetData, style }: BarViewProps): react.JSX.Element;
+
+interface PieDatum {
+    id: string;
+    label: string;
+    value: number;
+}
+interface PieViewProps {
+    records?: Row[];
+    groupColumn: string;
+    /** Pre-aggregated [{id, label, value}] bypasses client-side aggregation. */
+    data?: PieDatum[];
+    style?: Partial<ChartStyle>;
+}
+declare function PieView({ records, groupColumn, data: presetData, style }: PieViewProps): react.JSX.Element;
+
+interface LineSerie {
+    id: string;
+    data: {
+        x: string;
+        y: number;
+    }[];
+}
+interface LineViewProps {
+    records?: Row[];
+    xColumn: string;
+    yColumn: string;
+    /** Pre-shaped Nivo line series bypasses client-side processing. */
+    data?: LineSerie[];
+    style?: Partial<ChartStyle>;
+}
+declare function LineView({ records, xColumn, yColumn, data: presetData, style }: LineViewProps): react.JSX.Element;
+
+interface ScatterSerie {
+    id: string;
+    data: {
+        x: number;
+        y: number;
+    }[];
+}
+interface ScatterViewProps {
+    records?: Row[];
+    xColumn: string;
+    yColumn: string;
+    /** Pre-shaped Nivo scatter series bypasses client-side processing. */
+    data?: ScatterSerie[];
+    style?: Partial<ChartStyle>;
+}
+declare function ScatterView({ records, xColumn, yColumn, data: presetData, style }: ScatterViewProps): react.JSX.Element;
+
+interface HeatmapSerie {
+    id: string;
+    data: {
+        x: string;
+        y: number;
+    }[];
+}
+type AxisOrder = 'alpha' | 'total-asc' | 'total-desc';
+interface HeatmapViewProps {
+    records?: Row[];
+    rowColumn: string;
+    colColumn: string;
+    valueColumn?: string;
+    aggFn?: string;
+    data?: HeatmapSerie[];
+    rowOrder?: AxisOrder;
+    colOrder?: AxisOrder;
+    marginAgg?: string;
+    showTotals?: boolean;
+    style?: Partial<ChartStyle>;
+}
+/**
+ * HeatmapView builds a cross-tabulation heatmap (confusion / pairwise matrix).
+ * rowColumn values become rows, colColumn values become columns; the cell value
+ * is aggFn over valueColumn (or a record count when no valueColumn).
+ */
+declare function HeatmapView({ records, rowColumn, colColumn, valueColumn, aggFn, data: presetData, rowOrder, colOrder, marginAgg, showTotals, style, }: HeatmapViewProps): react.JSX.Element;
+
+interface PivotViewProps {
+    records?: Row[];
+}
+/**
+ * PivotView wraps react-pivottable — a drag-and-drop pivot table that
+ * introspects columns from the data automatically.
+ */
+declare function PivotView({ records }: PivotViewProps): react.JSX.Element;
+
+interface ChartStyleControlsProps {
+    style?: Partial<ChartStyle> | null;
+    onChange: (next: ChartStyle) => void;
+}
+/**
+ * ChartStyleControls — the standardized appearance editor used across all
+ * charts. Edits a plain style object (see chartStyle.ts); theme-aware via the
+ * host-injected DashboardContext theme. Parent persists the style and passes it
+ * to the views.
+ */
+declare function ChartStyleControls({ style, onChange }: ChartStyleControlsProps): react.JSX.Element;
+
+interface SqlConsoleColumn {
+    name: string;
+    type?: string;
+}
+interface SqlConsoleProps {
+    columns?: SqlConsoleColumn[];
+    stateId?: string;
+}
+/**
+ * SqlConsole — a HuggingFace-style read-only SQL editor over a state's full
+ * dataset. The state's data is exposed (server-side DuckDB in studio, DuckDB-WASM
+ * in the viewer) as a view named `data`; queries run against the entire dataset,
+ * not a client sample.
+ */
+declare function SqlConsole({ columns, stateId }: SqlConsoleProps): react.JSX.Element;
+
+interface PanelConfig {
+    sql?: string;
+    chartType?: ChartType | 'metric';
+    style?: Partial<ChartStyle>;
+    group?: string;
+    value?: string;
+    agg?: string;
+    x?: string;
+    y?: string;
+    row?: string;
+    col?: string;
+    yFields?: ChartField[];
+    rowOrder?: string;
+    colOrder?: string;
+    marginAgg?: string;
+    showTotals?: boolean;
+    columns?: string[];
+    text?: string;
+    label?: string;
+    column?: string;
+    [key: string]: unknown;
+}
+interface DashboardPanel$1 {
+    id: string;
+    type: string;
+    title?: string;
+    width?: number;
+    height?: number;
+    config?: PanelConfig;
+}
+interface Dashboard$1 {
+    insights?: string;
+    panels?: DashboardPanel$1[];
+}
+interface ColumnDef {
+    name: string;
+}
+interface DashboardRendererProps {
+    dashboard?: Dashboard$1 | null;
+    records?: Row[];
+    columns?: ColumnDef[];
+}
+/**
+ * DashboardRenderer — renders a grid of AI-generated or manually configured
+ * panels. The per-panel remove button is gated behind canEditPanels: the
+ * published viewer (no removePanel) renders the dashboard READ-ONLY.
+ */
+declare function DashboardRenderer({ dashboard, records, columns }: DashboardRendererProps): react.JSX.Element | null;
+
+interface ChartBuilderColumn {
+    name: string;
+    type?: string;
+}
+interface ChartPanel {
+    title: string;
+    type: ChartType | 'bar';
+    config: Record<string, unknown>;
+    width: number;
+    height: number;
+}
+interface ChartBuilderProps {
+    records?: Row[];
+    columns: ChartBuilderColumn[];
+    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. */
+interface Column {
+    name: string;
+    type: string;
+}
+/** A selectable state (dataset) in the statefs catalog. */
+interface StatefsState {
+    state_id: string;
+    row_count?: number;
+    [key: string]: unknown;
+}
+/** Per-column profile statistics shown in the ProfileSummary table. */
+interface ProfileColumn {
+    name: string;
+    type: string;
+    distinct_count?: number;
+    null_count?: number;
+    avg_length?: number;
+    min_length?: number;
+    max_length?: number;
+    min?: number | string;
+    max?: number | string;
+    top_values?: string[];
+    [key: string]: unknown;
+}
+/** Dataset profile (row/column counts + per-column stats). */
+interface DatasetProfile {
+    total_rows?: number;
+    columns?: ProfileColumn[];
+    [key: string]: unknown;
+}
+/** A single dashboard panel descriptor. */
+interface DashboardPanel {
+    id: string;
+    type: string;
+    title?: string;
+    width?: number;
+    height?: number;
+    config?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** A dashboard config: AI insights + a grid of panels. */
+interface Dashboard {
+    insights?: string;
+    panels?: DashboardPanel[];
+    [key: string]: unknown;
+}
+interface DataExplorerProps {
+    /** All records for the active state (viz/builder source). Empty when not loaded. */
+    records: Row[];
+    /** Active state's columns ({ name, type }), from schema or profile. */
+    columns: Column[];
+    /** The catalog of selectable states. */
+    states?: StatefsState[];
+    /** Currently-selected state id (null = none selected). */
+    activeStateId?: string | null;
+    /** Profile (stats) of the active state. */
+    profile?: DatasetProfile | null;
+    /** Active dashboard config (null = not yet generated). */
+    dashboard?: Dashboard | null;
+    /** Persisted id of the active dashboard (null = unsaved). Drives Save vs Save-as. */
+    dashboardId?: string | null;
+    /** Saved dashboards listed for the current project (shown in the saved panel). */
+    savedDashboards?: SavedDashboard[];
+    /** True while the catalog/profile/records are loading. */
+    loading?: boolean;
+    /** True while the AI is generating/refining the dashboard. */
+    analyzing?: boolean;
+    /** Select a state (host fetches its profile/records). */
+    onSelectState: (id: string) => void;
+    /** Refresh the states catalog. */
+    onRefreshStates?: () => void;
+}
+declare function DataExplorer({ records, columns, states, activeStateId, profile, dashboard, dashboardId, savedDashboards, loading, analyzing, 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 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 };