bo-grid 0.21.0 → 0.25.0

package/README.md

@@ -1,20 +1,20 @@
 # bo-grid
 
 Tiny, fast **Svelte 5** data grid for fintech UIs — canvas sparklines, batched
-realtime cell updates, and virtual scrolling in a package that gzips to ~20 KB.
-A free alternative to the heavyweight grids that paywall these features.
+realtime cell updates, and virtual scrolling, with a core that gzips to ~31 KB
+(Svelte external; unused exports tree-shake). A free alternative to the heavyweight
+grids that paywall these features.
 
 **[Live demo](https://bonguynvan.github.io/bo-grid/)** ·
 **[API reference](https://bonguynvan.github.io/bo-grid/api.html)** ·
 **[Benchmarks](./BENCHMARKS.md)** ·
 **[Roadmap](./ROADMAP.md)**
 
-The demo is a small gallery of nine grid types — a realtime **Trading desk**, a
-grouped **Portfolio** with subtotals and pivot, a general-purpose editable
-**Spreadsheet**, a live **Order book** depth ladder, a **Correlation** heatmap
-matrix, a **Leaderboard** with rank medals and score bars, a **Tree** file
-explorer, a drag-to-reorder **Tasks** list, and a **1M-row** trade tape windowed
-from a synthetic source — switch between them with the tabs.
+The demo is a gallery of grid types — a realtime **Trading desk**, a grouped
+**Portfolio** with subtotals and pivot, an editable **Spreadsheet**, a live
+**Order book**, a **Correlation** heatmap, a **Dashboard** with in-cell charts, a
+**Wide** 60-column grid, a server-backed **Lazy tree**, and more — switch between
+them with the tabs.
 
 > **Status: actively developed.** Working: config-driven columns, virtual scroll,
 > sort (single / multi / controlled), filtering (global, per-column row, header
@@ -37,13 +37,12 @@ from a synthetic source — switch between them with the tabs.
 | Price | $$$ / dev / year | Free (MIT) |
 | Sparklines | paid tier | built in |
 | Realtime cell updates | DIY / complex | built-in primitive |
-| Bundle | hundreds of KB | **~20 KB gzip** ([benchmarks](./BENCHMARKS.md)) |
+| Bundle | hundreds of KB | **~31 KB gzip core** ([benchmarks](./BENCHMARKS.md)) |
 | Svelte | wrapper | native Svelte 5 |
 
-bo-grid ships most of AG Grid's **paid (Enterprise)** features — grouping, pivot,
-tree data, master-detail, range selection, Excel export, sparklines — for free.
-See the honest **[bo-grid vs AG Grid](./docs/vs-ag-grid.md)** comparison (including
-what it doesn't do) to decide.
+bo-grid ships most of the features other grids put behind a **paid (Enterprise)**
+tier — grouping, pivot, tree data, master-detail, range selection, Excel export,
+sparklines — for free, and runs in any framework via a [custom element](./docs/frameworks.md).
 
 ## Install
 
@@ -56,7 +55,8 @@ Works with **SvelteKit / SSR** out of the box — `<Grid>` server-renders to HTM
 without touching `window`/`document`/`localStorage` (a CI gate, `pnpm ssr`,
 proves it). The package is `sideEffects: false`, so unused exports tree-shake
 away. See the **[SvelteKit guide](./docs/sveltekit.md)** for `load`-function data,
-realtime feeds, and layout persistence.
+server-side / lazy loading, realtime feeds, import helpers, charts, printing, and
+layout persistence.
 
 ## Usage
 
@@ -111,7 +111,8 @@ el.config = { columns, rows, theme: 'dark', height: 520 };
 ```
 
 It works in React, Vue, Angular and plain HTML — see
-**[docs/frameworks.md](./docs/frameworks.md)** for per-framework recipes. (Custom
+**[docs/frameworks.md](./docs/frameworks.md)** for per-framework recipes and
+**[examples/](./examples/)** for runnable, build-free starters. (Custom
 `cell`/`detail` snippets are Svelte-only; use built-in types, `format`, or computed
 `value` from other frameworks. Native Svelte users should import `Grid` directly —
 smaller, and snippets work.)
@@ -710,17 +711,38 @@ const columns = [
 ];
 ```
 
-## Export
+## Export & import
 
-CSV export is dependency-free:
+CSV export — and import — are dependency-free:
 
 ```ts
-import { exportCSV, toCSV } from 'bo-grid';
+import { exportCSV, toCSV, parseCSV } from 'bo-grid';
 
 exportCSV('tickers.csv', rows, columns);          // triggers a download
 const text = toCSV(rows, columns, { formatted: true }); // or get the string
+const rows = parseCSV(text, columns);             // …and back to rows (round-trip)
 ```
 
+`parseCSV` is RFC4180-aware (quoted fields, embedded commas/quotes/newlines), maps
+headers to columns, coerces numeric/`date` columns, and stamps `id` + flash fields
+so the result drops straight into `<Grid rows={…}>`. There's also `parseTSV` (tab-
+separated — what Ctrl/⌘+C copies), and for JSON/API data, `rowsFromObjects(objects)`
+/ `parseJSON(text)`:
+
+```ts
+import { rowsFromObjects } from 'bo-grid';
+const rows = rowsFromObjects(await (await fetch('/api/rows')).json());
+```
+
+Not sure what you'll get? **`parseRows(text, columns?)`** auto-detects JSON / TSV /
+CSV — perfect for a paste handler:
+
+```svelte
+<div onpaste={(e) => (rows = parseRows(e.clipboardData.getData('text'), columns))}>…</div>
+```
+
+See the **CSV import** demo (CSV / TSV / JSON / Auto-detect).
+
 Excel export loads SheetJS via **dynamic import**, so it lands in its own lazy
 chunk and never bloats your core bundle. `xlsx` is an **optional peer dependency**
 — install it only if you use this:
@@ -734,11 +756,23 @@ Sparkline columns are skipped; numeric columns export as raw numbers so
 spreadsheets can compute on them (pass `{ formatted: true }` for display strings).
 Ctrl/⌘+C still copies the current selection as TSV.
 
+**Printing.** The grid virtualizes, so printing it directly drops off-screen rows.
+`printTable(rows, columns, { title })` opens a print window with **all** rows as a
+clean table (Save-as-PDF from the dialog); `toHTMLTable(rows, columns)` returns
+that table as an HTML string to embed. See the **Print** demo.
+
+```ts
+import { printTable } from 'bo-grid';
+printTable(rows, columns, { title: 'Sales report' });
+```
+
 ## Also exported
 
 `Sparkline` component · `drawCandles` / `setupHiDpiCanvas` (draw on your own
 canvas) · `fmtPrice` / `fmtPercent` / `fmtVolume` / `fmtDate` · `heatColor` ·
-`Selection` · `aggregate` · `toCSV` / `exportCSV` / `exportXLSX` / `rowsToMatrix`.
+`Selection` · `aggregate` · `toCSV` / `exportCSV` / `exportXLSX` / `rowsToMatrix` ·
+`parseCSV` / `parseCSVMatrix` / `parseTSV` / `parseJSON` / `parseRows` /
+`rowsFromObjects` · `toHTMLTable` / `printTable`.
 
 ## Pivot tables
 

package/dist/grid/export.d.ts

@@ -16,4 +16,37 @@ export declare function toCSV(rows: readonly GridRow[], columns: readonly Column
 /** Trigger a browser download of text content. No-op outside the browser. */
 export declare function download(filename: string, content: string, mime?: string): void;
 export declare function exportCSV(filename: string, rows: readonly GridRow[], columns: readonly ColumnDef[], opts?: ExportOptions): void;
+/** Parse RFC4180 CSV text into a 2-D string matrix. Pure; inverse of `rowsToMatrix`. */
+export declare function parseCSVMatrix(text: string): string[][];
+/**
+ * Parse CSV text into grid rows. The first line is the header (mapped to columns
+ * by `header` or `key`); numeric columns coerce to numbers, `date` columns to
+ * epoch ms. Rows get `id` + flash fields so they're `GridRow`-ready. Inverse of
+ * `toCSV` — round-trips. Pure; unit-tested.
+ */
+export declare function parseCSV(text: string, columns?: readonly ColumnDef[]): GridRow[];
+/** Parse TAB-separated text into grid rows (same mapping as `parseCSV`). Handy for
+    spreadsheet/clipboard data — `Ctrl/⌘+C` copies the selection as TSV. */
+export declare function parseTSV(text: string, columns?: readonly ColumnDef[]): GridRow[];
+/**
+ * Adapt plain objects (e.g. a JSON API response) to grid rows: stamp `id` (the
+ * object's own `id`, else the index) and `flashSeq`/`flashDir` if absent, keeping
+ * all fields. The cheapest path from `await res.json()` to `<Grid rows>`.
+ */
+export declare function rowsFromObjects(objects: readonly Record<string, unknown>[]): GridRow[];
+/** Parse a JSON array of objects into grid rows (`JSON.parse` + `rowsFromObjects`).
+    Throws on invalid JSON or a non-array top level. */
+export declare function parseJSON(text: string): GridRow[];
+/**
+ * Smart import: detect the format of `text` — a JSON array, TSV, or CSV — and
+ * parse it into grid rows. Ideal for a paste handler where the source is unknown:
+ *
+ *   el.addEventListener('paste', (e) => {
+ *     rows = parseRows(e.clipboardData.getData('text'), columns);
+ *   });
+ *
+ * Leading `[` → JSON (falls through to delimited if it isn't valid JSON); a tab in
+ * the first line → TSV; otherwise CSV. Pure; unit-tested.
+ */
+export declare function parseRows(text: string, columns?: readonly ColumnDef[]): GridRow[];
 export {};

package/dist/grid/export.js

@@ -49,3 +49,156 @@ export function download(filename, content, mime = 'text/csv;charset=utf-8') {
 export function exportCSV(filename, rows, columns, opts = {}) {
     download(filename, toCSV(rows, columns, opts));
 }
+/**
+ * Parse delimited text (CSV/TSV) into a 2-D string matrix — handles quoted fields
+ * with embedded delimiters, doubled quotes and newlines, and CRLF or LF endings.
+ */
+function parseDelimited(text, delim) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let inQuotes = false;
+    let i = 0;
+    const endField = () => {
+        row.push(field);
+        field = '';
+    };
+    const endRow = () => {
+        endField();
+        rows.push(row);
+        row = [];
+    };
+    while (i < text.length) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                }
+                else {
+                    inQuotes = false;
+                    i++;
+                }
+            }
+            else {
+                field += c;
+                i++;
+            }
+            continue;
+        }
+        if (c === '"') {
+            inQuotes = true;
+            i++;
+        }
+        else if (c === delim) {
+            endField();
+            i++;
+        }
+        else if (c === '\n') {
+            endRow();
+            i++;
+        }
+        else if (c === '\r') {
+            i++; // CRLF: the \n ends the row
+        }
+        else {
+            field += c;
+            i++;
+        }
+    }
+    if (field !== '' || row.length > 0)
+        endRow(); // trailing line without a newline
+    return rows;
+}
+/** Parse RFC4180 CSV text into a 2-D string matrix. Pure; inverse of `rowsToMatrix`. */
+export function parseCSVMatrix(text) {
+    return parseDelimited(text, ',');
+}
+// Header-row matrix → grid rows: map each header to a column (by `header` or
+// `key`), coerce numeric columns to numbers and `date` columns to epoch ms, leave
+// blanks/unparseable as-is, and stamp id + flash fields. Drops blank lines.
+function matrixToRows(matrix, columns) {
+    const m = matrix.filter((r) => !(r.length === 1 && r[0] === ''));
+    if (m.length < 1)
+        return [];
+    const headers = m[0];
+    const cols = headers.map((h) => columns.find((c) => c.header === h || c.key === h));
+    return m.slice(1).map((cells, i) => {
+        const row = { id: i, flashSeq: 0, flashDir: 'up' };
+        headers.forEach((h, c) => {
+            const col = cols[c];
+            const raw = cells[c] ?? '';
+            const key = col ? col.key : h;
+            if (raw === '') {
+                row[key] = '';
+            }
+            else if (col?.type === 'date') {
+                const ms = Date.parse(raw);
+                row[key] = Number.isFinite(ms) ? ms : raw;
+            }
+            else if (col && isNumeric(col)) {
+                const n = Number(raw);
+                row[key] = Number.isFinite(n) ? n : raw;
+            }
+            else {
+                row[key] = raw;
+            }
+        });
+        return row;
+    });
+}
+/**
+ * Parse CSV text into grid rows. The first line is the header (mapped to columns
+ * by `header` or `key`); numeric columns coerce to numbers, `date` columns to
+ * epoch ms. Rows get `id` + flash fields so they're `GridRow`-ready. Inverse of
+ * `toCSV` — round-trips. Pure; unit-tested.
+ */
+export function parseCSV(text, columns = []) {
+    return matrixToRows(parseDelimited(text, ','), columns);
+}
+/** Parse TAB-separated text into grid rows (same mapping as `parseCSV`). Handy for
+    spreadsheet/clipboard data — `Ctrl/⌘+C` copies the selection as TSV. */
+export function parseTSV(text, columns = []) {
+    return matrixToRows(parseDelimited(text, '\t'), columns);
+}
+/**
+ * Adapt plain objects (e.g. a JSON API response) to grid rows: stamp `id` (the
+ * object's own `id`, else the index) and `flashSeq`/`flashDir` if absent, keeping
+ * all fields. The cheapest path from `await res.json()` to `<Grid rows>`.
+ */
+export function rowsFromObjects(objects) {
+    return objects.map((o, i) => ({ id: i, flashSeq: 0, flashDir: 'up', ...o }));
+}
+/** Parse a JSON array of objects into grid rows (`JSON.parse` + `rowsFromObjects`).
+    Throws on invalid JSON or a non-array top level. */
+export function parseJSON(text) {
+    const data = JSON.parse(text);
+    if (!Array.isArray(data))
+        throw new Error('parseJSON: expected a JSON array of objects');
+    return rowsFromObjects(data);
+}
+/**
+ * Smart import: detect the format of `text` — a JSON array, TSV, or CSV — and
+ * parse it into grid rows. Ideal for a paste handler where the source is unknown:
+ *
+ *   el.addEventListener('paste', (e) => {
+ *     rows = parseRows(e.clipboardData.getData('text'), columns);
+ *   });
+ *
+ * Leading `[` → JSON (falls through to delimited if it isn't valid JSON); a tab in
+ * the first line → TSV; otherwise CSV. Pure; unit-tested.
+ */
+export function parseRows(text, columns = []) {
+    if (text.trimStart().startsWith('[')) {
+        try {
+            return parseJSON(text);
+        }
+        catch {
+            // Not valid JSON after all — treat it as delimited text below.
+        }
+    }
+    const nl = text.indexOf('\n');
+    const firstLine = nl === -1 ? text : text.slice(0, nl);
+    return firstLine.includes('\t') ? parseTSV(text, columns) : parseCSV(text, columns);
+}

package/dist/grid/print.d.ts

@@ -0,0 +1,17 @@
+import type { ColumnDef, GridRow } from './column';
+/** Escape a string for safe HTML text/attribute interpolation. */
+export declare function escapeHTML(s: string): string;
+/**
+ * Render rows to a semantic `<table>` HTML string (formatted via the column
+ * formatters; numeric columns right-aligned; sparkline/custom columns skipped).
+ * Values are HTML-escaped. Pure; unit-tested. Embed it, or use `printTable`.
+ */
+export declare function toHTMLTable(rows: readonly GridRow[], columns: readonly ColumnDef[]): string;
+/**
+ * Open a print window with all rows as a clean table and trigger the print
+ * dialog. No-op outside the browser (or if a popup is blocked). For PDFs, users
+ * "Save as PDF" from the print dialog.
+ */
+export declare function printTable(rows: readonly GridRow[], columns: readonly ColumnDef[], opts?: {
+    title?: string;
+}): void;

package/dist/grid/print.js

@@ -0,0 +1,55 @@
+import { formatCell, cellValue, isNumeric } from './column';
+const ESC = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+/** Escape a string for safe HTML text/attribute interpolation. */
+export function escapeHTML(s) {
+    return s.replace(/[&<>"']/g, (c) => ESC[c]);
+}
+/**
+ * Render rows to a semantic `<table>` HTML string (formatted via the column
+ * formatters; numeric columns right-aligned; sparkline/custom columns skipped).
+ * Values are HTML-escaped. Pure; unit-tested. Embed it, or use `printTable`.
+ */
+export function toHTMLTable(rows, columns) {
+    const cols = columns.filter((c) => c.type !== 'sparkline' && c.type !== 'custom');
+    const align = (c) => (isNumeric(c) ? ' style="text-align:right"' : '');
+    const head = cols.map((c) => `<th${align(c)}>${escapeHTML(c.header)}</th>`).join('');
+    const body = rows
+        .map((row) => '<tr>' +
+        cols.map((c) => `<td${align(c)}>${escapeHTML(formatCell(c, cellValue(c, row), row))}</td>`).join('') +
+        '</tr>')
+        .join('');
+    return `<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`;
+}
+const PRINT_CSS = `
+*{box-sizing:border-box}
+body{font:12px -apple-system,system-ui,sans-serif;color:#111;margin:24px}
+h1{font-size:16px;margin:0 0 12px}
+table{border-collapse:collapse;width:100%}
+th,td{padding:4px 8px;border:1px solid #ddd;white-space:nowrap;text-align:left}
+thead th{background:#f4f4f4;font-weight:600}
+tbody tr:nth-child(even){background:#fafafa}
+@media print{body{margin:0}}`;
+/**
+ * Open a print window with all rows as a clean table and trigger the print
+ * dialog. No-op outside the browser (or if a popup is blocked). For PDFs, users
+ * "Save as PDF" from the print dialog.
+ */
+export function printTable(rows, columns, opts = {}) {
+    if (typeof window === 'undefined' || typeof window.open !== 'function')
+        return;
+    const win = window.open('', '_blank');
+    if (!win)
+        return; // popup blocked
+    const title = opts.title ?? 'Grid';
+    win.document.write(`<!doctype html><html><head><meta charset="utf-8"><title>${escapeHTML(title)}</title>` +
+        `<style>${PRINT_CSS}</style></head><body><h1>${escapeHTML(title)}</h1>` +
+        `${toHTMLTable(rows, columns)}` +
+        `<script>window.onload=function(){window.print()}<\/script></body></html>`);
+    win.document.close();
+}

package/dist/index.d.ts

@@ -13,9 +13,10 @@ export type { PivotConfig, PivotResult } from './grid/pivot';
 export { themeVars, darkTheme, lightTheme, highContrastDark, highContrastLight, midnightTheme, terminalTheme, themePresets, } from './grid/theme';
 export type { GridTheme, ThemePreset } from './grid/theme';
 export { drawCandles, setupHiDpiCanvas } from './sparkline/sparkline-render';
-export { toCSV, exportCSV } from './grid/export';
+export { toCSV, exportCSV, parseCSV, parseCSVMatrix, parseTSV, parseJSON, parseRows, rowsFromObjects, } from './grid/export';
 export { exportXLSX } from './grid/export-xlsx';
 export type { ExportOptions } from './grid/export';
+export { toHTMLTable, printTable, escapeHTML } from './grid/print';
 export { createArraySource } from './grid/source';
 export type { RowSource, RowRange, RowSourceParams, RowSourceResult, ArraySourceOptions, } from './grid/source';
 export type { Candle } from './types';

package/dist/index.js

@@ -17,8 +17,10 @@ export { pivot } from './grid/pivot';
 export { themeVars, darkTheme, lightTheme, highContrastDark, highContrastLight, midnightTheme, terminalTheme, themePresets, } from './grid/theme';
 // Sparkline canvas primitives (draw candlesticks on your own canvas)
 export { drawCandles, setupHiDpiCanvas } from './sparkline/sparkline-render';
-// Export (CSV is dependency-free; XLSX dynamic-imports the optional `xlsx` peer)
-export { toCSV, exportCSV } from './grid/export';
+// Export + import (CSV is dependency-free; XLSX dynamic-imports the optional `xlsx` peer)
+export { toCSV, exportCSV, parseCSV, parseCSVMatrix, parseTSV, parseJSON, parseRows, rowsFromObjects, } from './grid/export';
 export { exportXLSX } from './grid/export-xlsx';
+// Printable / export HTML (renders ALL rows, unlike the virtualized grid)
+export { toHTMLTable, printTable, escapeHTML } from './grid/print';
 // Server-side / windowed data source
 export { createArraySource } from './grid/source';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bo-grid",
-  "version": "0.21.0",
+  "version": "0.25.0",
   "type": "module",
   "license": "MIT",
   "description": "Tiny, fast Svelte 5 data grid: canvas sparklines, batched realtime cell updates, and virtual scrolling. A free, fintech-focused alternative to heavyweight grids.",
@@ -69,6 +69,7 @@
     "size:lib": "vite build --config vite.lib.config.ts && node scripts/size-lib.mjs",
     "smoke": "vite build --base=./ --outDir demo-dist && node scripts/smoke.mjs",
     "smoke:wc": "node scripts/wc-smoke.mjs",
+    "check:examples": "node scripts/check-examples.mjs",
     "ssr": "node scripts/ssr.mjs",
     "bench": "node scripts/bench.mjs",
     "test": "vitest run",