@calliopelabs/ui 0.16.0 → 0.18.0

package/dist/workbench/DataChart.js

@@ -0,0 +1,146 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { ActivityIcon, ChartColumnIcon, ChartPieIcon, CircleIcon, TrendingUpIcon, } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Segmented } from "../primitives/Segmented.js";
+import { Select } from "../primitives/Select.js";
+import { useUI } from "../provider/UIProvider.js";
+import { EmptyState } from "../states/EmptyState.js";
+import { ErrorState } from "../states/ErrorState.js";
+import { LoadingState } from "../states/LoadingState.js";
+import { columnSignature } from "./grid-model.js";
+import { TruncationBanner } from "./TruncationBanner.js";
+/** Recharts puts every point in the DOM, so the chart plots a prefix. */
+const CHART_ROW_CAP = 500;
+/** The five chart series, from the theme: they follow the ground and the accent. */
+const SERIES = [
+    "var(--chart-1)",
+    "var(--chart-2)",
+    "var(--chart-3)",
+    "var(--chart-4)",
+    "var(--chart-5)",
+];
+const KIND_ICON = {
+    bar: ChartColumnIcon,
+    line: TrendingUpIcon,
+    area: ActivityIcon,
+    scatter: CircleIcon,
+    pie: ChartPieIcon,
+};
+function isNumeric(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    return typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value));
+}
+/** Columns mostly numeric in a sample of their first values, and the rest. */
+function classify(names, rows) {
+    const numeric = [];
+    const categorical = [];
+    for (const name of names) {
+        const sample = [];
+        for (const row of rows) {
+            const v = row[name];
+            if (v !== null && v !== undefined)
+                sample.push(v);
+            if (sample.length >= 20)
+                break;
+        }
+        const share = sample.length > 0 ? sample.filter(isNumeric).length / sample.length : 0;
+        (share > 0.7 ? numeric : categorical).push(name);
+    }
+    return { numeric, categorical };
+}
+/**
+ * A quick chart of a result: bar, line, area, scatter or pie, an X column
+ * and one or more Y columns, coloured by the theme's chart series. Recharts
+ * is the host's to supply (`loadCharts`); without it nothing is loaded.
+ */
+export function DataChart(props) {
+    return _jsx(ChartSurface, { ...props }, columnSignature(props.columns));
+}
+function ChartSurface({ columns, rows, loadCharts, truncated, rowCap = CHART_ROW_CAP, className, }) {
+    const { messages } = useUI();
+    const t = messages.workbench;
+    const names = React.useMemo(() => columns.map((c) => (typeof c === "string" ? c : c.name)), [columns]);
+    const { numeric, categorical } = React.useMemo(() => classify(names, rows), [names, rows]);
+    const [kind, setKind] = React.useState("bar");
+    const [x, setX] = React.useState(() => categorical[0] ?? names[0] ?? "");
+    const [ys, setYs] = React.useState(() => {
+        const first = numeric.find((n) => n !== (categorical[0] ?? names[0])) ?? names[1];
+        return first ? [first] : [];
+    });
+    const [lib, setLib] = React.useState(null);
+    const [failed, setFailed] = React.useState(null);
+    const [attempt, setAttempt] = React.useState(0);
+    const loader = React.useRef(loadCharts);
+    React.useEffect(() => {
+        let live = true;
+        loader.current().then((module) => live && setLib(module), (reason) => live && setFailed(reason instanceof Error ? reason.message : String(reason)));
+        return () => {
+            live = false;
+        };
+    }, [attempt]);
+    const data = React.useMemo(() => rows.slice(0, rowCap).map((row) => {
+        const entry = { [x]: row[x] };
+        for (const y of ys) {
+            const v = row[y];
+            entry[y] = typeof v === "number" ? v : Number(v) || 0;
+        }
+        return entry;
+    }), [rows, rowCap, x, ys]);
+    if (rows.length === 0)
+        return _jsx(EmptyState, { title: t.chartNoData, className: className });
+    const notes = [truncated, rows.length > rowCap ? t.chartCap(rowCap, rows.length) : null].filter(Boolean);
+    const tick = { fontSize: 11, fill: "var(--muted-foreground)" };
+    const tooltip = {
+        contentStyle: {
+            backgroundColor: "var(--popover)",
+            border: "1px solid var(--border)",
+            borderRadius: "var(--radius)",
+            color: "var(--popover-foreground)",
+            fontSize: 12,
+        },
+        itemStyle: { color: "var(--popover-foreground)" },
+        labelStyle: { color: "var(--muted-foreground)" },
+        cursor: { fill: "var(--muted)", stroke: "var(--border)" },
+    };
+    const legend = { wrapperStyle: { fontSize: 12, color: "var(--muted-foreground)" } };
+    let chart;
+    if (failed) {
+        chart = (_jsx(ErrorState, { title: t.chartLoadFailed, error: failed, onRetry: () => {
+                setFailed(null);
+                setAttempt((n) => n + 1);
+            }, retryLabel: t.retry }));
+    }
+    else if (!lib) {
+        chart = _jsx(LoadingState, { label: t.chartLoading, variant: "rows", rows: 4 });
+    }
+    else if (ys.length === 0) {
+        chart = _jsx(EmptyState, { title: t.chartPickY });
+    }
+    else {
+        const L = lib;
+        const axes = (_jsxs(_Fragment, { children: [_jsx(L.CartesianGrid, { strokeDasharray: "3 3", stroke: "var(--border)" }), _jsx(L.XAxis, { dataKey: x, tick: tick, tickLine: false, stroke: "var(--border)" }), _jsx(L.YAxis, { tick: tick, tickLine: false, stroke: "var(--border)" }), _jsx(L.Tooltip, { ...tooltip }), ys.length > 1 && _jsx(L.Legend, { ...legend })] }));
+        const series = (i) => SERIES[i % SERIES.length];
+        chart = (_jsx(L.ResponsiveContainer, { width: "100%", height: "100%", children: kind === "bar" ? (_jsxs(L.BarChart, { data: data, children: [axes, ys.map((y, i) => (_jsx(L.Bar, { dataKey: y, fill: series(i), radius: [2, 2, 0, 0], isAnimationActive: false }, y)))] })) : kind === "line" ? (_jsxs(L.LineChart, { data: data, children: [axes, ys.map((y, i) => (_jsx(L.Line, { dataKey: y, stroke: series(i), strokeWidth: 2, dot: { r: 2, fill: series(i) }, isAnimationActive: false }, y)))] })) : kind === "area" ? (_jsxs(L.AreaChart, { data: data, children: [axes, ys.map((y, i) => (_jsx(L.Area, { dataKey: y, stroke: series(i), fill: series(i), fillOpacity: 0.2, strokeWidth: 2, isAnimationActive: false }, y)))] })) : kind === "scatter" ? (_jsxs(L.ScatterChart, { children: [_jsx(L.CartesianGrid, { strokeDasharray: "3 3", stroke: "var(--border)" }), _jsx(L.XAxis, { dataKey: x, name: x, type: "number", tick: tick, tickLine: false, stroke: "var(--border)" }), _jsx(L.YAxis, { dataKey: ys[0], name: ys[0], tick: tick, tickLine: false, stroke: "var(--border)" }), _jsx(L.Tooltip, { ...tooltip }), _jsx(L.Scatter, { data: data, fill: series(0), isAnimationActive: false })] })) : (_jsxs(L.PieChart, { children: [_jsx(L.Tooltip, { ...tooltip }), _jsx(L.Legend, { ...legend }), _jsx(L.Pie, { data: data.map((d) => ({
+                            name: String(d[x] ?? ""),
+                            value: Number(d[ys[0] ?? ""]) || 0,
+                        })), dataKey: "value", nameKey: "name", outerRadius: "80%", stroke: "var(--background)", isAnimationActive: false, children: data.map((_, i) => (_jsx(L.Cell, { fill: series(i) }, i))) })] })) }));
+    }
+    return (_jsxs("section", { "aria-label": t.chartLabel, "data-slot": "data-chart", className: cn("flex min-h-0 flex-col", className), children: [notes.length > 0 && _jsx(TruncationBanner, { children: notes.join(" ") }), _jsxs("div", { className: "flex shrink-0 flex-wrap items-center gap-3 border-b bg-muted/40 px-3 py-1.5 text-xs", children: [_jsx(Segmented, { label: t.chartType, size: "sm", value: kind, onValueChange: setKind, options: ["bar", "line", "area", "scatter", "pie"].map((k) => ({
+                            value: k,
+                            label: t.chartKind(k),
+                            icon: KIND_ICON[k],
+                        })) }), _jsxs("span", { className: "flex items-center gap-1.5", children: [_jsx("span", { className: "text-muted-foreground", "aria-hidden": true, children: t.chartX }), _jsx(Select, { size: "sm", "aria-label": t.chartX, value: x, onValueChange: (next) => {
+                                    setX(next);
+                                    setYs((prev) => prev.filter((y) => y !== next));
+                                }, options: names.map((n) => ({ value: n, label: n })) })] }), _jsxs("fieldset", { className: "flex min-w-0 flex-wrap items-center gap-1", children: [_jsx("legend", { className: "sr-only", children: t.chartY }), _jsx("span", { className: "mr-0.5 text-muted-foreground", "aria-hidden": true, children: t.chartY }), names
+                                .filter((n) => n !== x)
+                                .map((name) => {
+                                const on = ys.includes(name);
+                                return (_jsxs("button", { type: "button", "aria-pressed": on, className: cn("flex items-center gap-1 rounded-full border px-2 py-0.5 outline-none focus-visible:ring-2 focus-visible:ring-ring/50", on
+                                        ? "border-foreground/30 text-foreground"
+                                        : "text-muted-foreground hover:text-foreground"), onClick: () => setYs((prev) => (on ? prev.filter((y) => y !== name) : [...prev, name])), children: [on && (_jsx("span", { "aria-hidden": true, className: "size-2 rounded-full", style: { backgroundColor: SERIES[ys.indexOf(name) % SERIES.length] } })), name] }, name));
+                            })] })] }), _jsx("div", { className: "min-h-64 flex-1 p-4", children: chart })] }));
+}

package/dist/workbench/DataGrid.d.ts

@@ -0,0 +1,89 @@
+import * as React from "react";
+import { type CellMatrix, type CopyFormat, type ExportFile, type ExportFormat } from "./grid-format.js";
+import { type GridColumn, type GridRow } from "./grid-model.js";
+import { type ChangeSet, type PendingChanges } from "./pending.js";
+/** A format the host adds to the export menu (a workbook); the host writes the file. */
+export interface GridExportOption {
+    id: string;
+    label: string;
+}
+/** An export the person asked for. `file` is the library's text for its own formats, null for a host's. */
+export interface GridExportRequest {
+    format: ExportFormat | (string & {});
+    matrix: CellMatrix;
+    file: ExportFile | null;
+}
+/** A copy the grid put on the clipboard. */
+export interface GridCopyEvent {
+    format: CopyFormat;
+    text: string;
+    /** Cells copied: rows times columns. */
+    cells: number;
+}
+/** A commit's failure, as the host rejects `onCommit` with it. `key` is the row key in the change set. */
+export interface GridCommitError {
+    message: string;
+    key?: number;
+}
+export interface DataGridProps {
+    /** Names, or descriptions with a type, keys and nullability. Undeclared types are sniffed from the rows. */
+    columns: readonly (string | GridColumn)[];
+    rows: readonly GridRow[];
+    /** The grid's accessible name. */
+    label?: string;
+    loading?: boolean;
+    error?: string | {
+        message: string;
+    } | null;
+    onRetry?: () => void;
+    /** The server's total when it capped the rows; with `hasMore`, the banner says more exist. */
+    totalRows?: number | null;
+    hasMore?: boolean;
+    /**
+     * Remembers column widths per person (the library's local store). The
+     * grid also starts clean (selection, sort, filter, hidden columns) when it
+     * changes, or when the columns do.
+     */
+    storageKey?: string;
+    /** The table for "Copy as INSERT" and the SQL export. */
+    tableName?: string;
+    /** The exported file's name without extension. */
+    exportName?: string;
+    /** After a copy reached the clipboard: the host may say so. */
+    onCopy?: (event: GridCopyEvent) => void;
+    /**
+     * Takes over export: the grid hands every request here instead of
+     * downloading (`downloadExport(request.file)` downloads one). Required for
+     * `exportFormats`.
+     */
+    onExport?: (request: GridExportRequest) => void;
+    /** Formats the host writes itself (xlsx), after the library's own. */
+    exportFormats?: readonly GridExportOption[];
+    /**
+     * Cells edit in place (Enter, F2, double click or typing), rows add,
+     * duplicate and delete, and the changes wait in a bar to be committed.
+     * Existing rows change only when a column is a `primaryKey`.
+     */
+    editable?: boolean;
+    /**
+     * Writes the changes. Resolve and the grid clears them; reject (with a
+     * `GridCommitError` or an Error) and they stay, with the message shown.
+     */
+    onCommit?: (changes: ChangeSet) => void | Promise<void>;
+    /** Controlled pending changes; leave out to let the grid keep them. */
+    pending?: PendingChanges;
+    onPendingChange?: (pending: PendingChanges) => void;
+    /** Host controls at the end of the toolbar (an edit-mode switch, a refresh). */
+    toolbar?: React.ReactNode;
+    className?: string;
+}
+/**
+ * A data grid for query results and table data: rows and columns both
+ * virtualized (50,000 rows by 30 columns is a few hundred nodes), the
+ * WAI-ARIA grid pattern for the keyboard, cell, row and column selection,
+ * sort (NULLs last), filter, hidden and resizable columns, copy and export
+ * in six text formats, selection statistics, cell and row detail, and
+ * optional editing with pending changes the host commits. Host-driven: the
+ * rows come in, changes go out through callbacks, nothing fetches.
+ */
+export declare function DataGrid(props: DataGridProps): React.JSX.Element;