bo-grid 0.21.0 → 1.0.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 ~32 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 — all on one
+page, each grid lazy-mounting as you scroll (jump between them from the side rail).
 
 > **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 | **~32 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
 
@@ -100,21 +100,26 @@ keep frames smooth.
 
 ### React, Vue, Angular & vanilla
 
-bo-grid also ships a framework-agnostic **custom element**. Import it and drive
-the whole API through a `config` property:
+bo-grid also ships a framework-agnostic **custom element**, fully typed. Import it
+and drive the whole API through a `config` property:
 
-```js
-import 'bo-grid/element'; // registers <bo-grid>, injects styles
+```ts
+import { createBoGrid } from 'bo-grid/element'; // registers <bo-grid>, injects styles
+import type { BoGridConfig } from 'bo-grid/element';
 
-const el = document.querySelector('bo-grid');
-el.config = { columns, rows, theme: 'dark', height: 520 };
+const config: BoGridConfig = { columns, rows, theme: 'dark', height: 520 };
+document.body.append(createBoGrid(config)); // or set `el.config` on an existing element
 ```
 
-It works in React, Vue, Angular and plain HTML — see
-**[docs/frameworks.md](./docs/frameworks.md)** for per-framework recipes. (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.)
+`bo-grid/element` exports `BoGridConfig` (every `<Grid>` prop), a typed
+`BoGridElement`, and the `createBoGrid` helper. `config` is safe to set **after**
+the element attaches (the React `ref` + `useEffect` pattern won't crash). It works
+in React, Vue, Angular and plain HTML — see
+**[docs/frameworks.md](./docs/frameworks.md)** for per-framework recipes and
+**[examples/](./examples/)** for runnable, build-free starters. (Svelte `cell`/
+`detail` snippets are Svelte-only; from other frameworks use a column's
+`render(ctx)` hook, built-in types, or `format`. Native Svelte users should import
+`Grid` directly — smaller, and snippets work.)
 
 ## Column types
 
@@ -159,6 +164,52 @@ buttons, links. The snippet receives `{ row, column, value }`:
 <Grid {rows} {columns} {cell} height={640} />
 ```
 
+**From plain JS (React/Vue/vanilla, `<bo-grid>`):** snippets are Svelte-only, so
+give a column a **`render(ctx)`** function instead. Return an `HTMLElement`/`Node`
+(appended as-is — safe) or an HTML **string** (inserted as innerHTML — sanitize
+any untrusted data yourself; prefer a Node for that). `ctx` is `{ value, row,
+column }`. Display only — sort, filter, tooltip, copy and export still use the
+value / `format`:
+
+```js
+{ type: 'custom', key: 'trend', header: 'Trend', render: ({ row }) => {
+    const el = document.createElement('span');
+    el.textContent = row.changePct > 0 ? '▲' : '▼';
+    el.style.color = row.changePct > 0 ? 'var(--bo-grid-up)' : 'var(--bo-grid-down)';
+    return el;
+  } }
+```
+
+### Tooltips & truncation
+
+Long cell values truncate with an **ellipsis** by default. Set `tooltip` on a
+column to reveal the full text in a **styled floating tooltip** on hover (themed,
+instant — not the native `title`). `tooltip: true` shows the formatted value;
+pass a function for custom text built from the whole row (works for any type,
+including `custom`):
+
+```ts
+const columns: ColumnDef[] = [
+  { type: 'text', key: 'note', header: 'Notes', width: 220, tooltip: true },
+  { type: 'badge', key: 'status', header: 'Status',
+    tooltip: (value, row) => `${value} · ${row.role}` },     // custom text
+  { type: 'text', key: 'bio', header: 'Bio', flex: 1, wrap: true }, // wrap, no ellipsis
+];
+```
+
+Set `wrap: true` to let a column wrap onto multiple lines instead of truncating
+(pair with a taller `rowHeight`).
+
+**Header tooltips:** `headerTooltip` shows the same styled bubble on the column
+header (describe the metric, units, caveats); add `headerInfo: true` for a small
+ⓘ cue:
+
+```ts
+{ type: 'progress', key: 'workload', header: 'Workload', min: 0, max: 100,
+  headerTooltip: 'Share of capacity allocated this sprint (0–100%).',
+  headerInfo: true }
+```
+
 ## Conditional formatting
 
 Paint analytics cues straight into numeric cells — no custom snippet needed.
@@ -260,13 +311,28 @@ a function for variable per-row heights (in-memory mode):
 Variable heights use a prefix-sum + binary-search virtualizer, so scrolling stays
 O(log n). Source mode is uniform-only (unloaded row heights aren't known).
 
+### Sizing the grid
+
+`height` as a **number** is the scroll viewport's pixel height (the element is
+that plus header/pager/footer chrome). Pass a **CSS string** to size the whole
+element instead and let the viewport auto-fit the space left over — ideal for
+filling a flex/grid cell:
+
+```svelte
+<Grid {rows} {columns} height={640} />        <!-- 640px viewport -->
+<Grid {rows} {columns} height="100%" />        <!-- fill a sized parent -->
+<Grid {rows} {columns} height="80vh" />
+```
+
 ## Pagination
 
 Prefer pages over one long scroll? Set `pageSize` (> 0) for a paged view with a
-first/prev/next/last pager; rows still virtualize within each page. In-memory mode.
+first/prev/next/last pager; rows still virtualize within each page. Add
+`pageSizeOptions` for a **rows-per-page dropdown** in the pager (observe changes
+via `onPageSizeChange`). In-memory mode.
 
 ```svelte
-<Grid {rows} {columns} height={640} pageSize={25} />
+<Grid {rows} {columns} height={640} pageSize={25} pageSizeOptions={[25, 50, 100]} />
 ```
 
 ## Sort & filter
@@ -329,6 +395,22 @@ value(s) across the extended range (editable columns; multi-cell selections tile
 Edits, paste and fill are **undoable** with <kbd>Ctrl/⌘</kbd>+<kbd>Z</kbd> (redo
 with <kbd>Ctrl/⌘</kbd>+<kbd>Y</kbd>). A paste or fill undoes as a single step.
 
+For a read-only / display grid, set `cellSelection={false}` to drop the blue
+range-selection highlight (and fill handle) entirely — clicks pass straight
+through to `onRowClick` / `onCellClick`:
+
+```svelte
+<Grid {rows} {columns} height={640} cellSelection={false} onRowClick={open} />
+```
+
+For a **list-detail / master-detail** layout, drive `selectedRowId` (keyed by
+`getRowId`) to highlight the active row — independent of the checkbox selection:
+
+```svelte
+<Grid {rows} {columns} height={640}
+  selectedRowId={active?.id} onRowClick={(r) => (active = r)} />
+```
+
 When more than one cell is selected, a footer bar shows live **Sum / Avg / Count /
 Min / Max** over the numeric cells in the range — and it keeps updating as a
 realtime feed ticks. Choose which stats to show:
@@ -710,17 +792,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 +837,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/{bo-grid.FilterMenu-BHI6rILc.js → bo-grid.FilterMenu-BBxlxrnZ.js}

@@ -1,4 +1,4 @@
-import { p as ce, a as xe, v as me, w as _e, n as x, x as _, s as p, y as L, t as N, z as he, j as ke, f as C, h as w, i as u, m as ge, c as h, A as D, e as F, g as t, B as U, k as S, d as ye, l as f, C as we, o as k, D as Ae, u as Oe, q as Se, r as d, b as A } from "./bo-grid.element-DPnHUXMa.js";
+import { p as ce, a as xe, v as me, w as _e, n as x, x as _, s as p, y as L, t as N, z as he, j as ke, f as C, h as w, i as u, m as ge, c as h, A as D, e as F, g as t, B as U, k as S, d as ye, l as f, C as we, o as k, D as Ae, u as Oe, q as Se, r as d, b as A } from "./bo-grid.element-BZGnfKB_.js";
 var G = k("<option> </option>"), Ne = k('<input class="bo-fm-in svelte-f7i4av" type="number" placeholder="and" aria-label="Upper value"/>'), Ce = k('<select class="bo-fm-op svelte-f7i4av" aria-label="Operator"></select> <input class="bo-fm-in svelte-f7i4av" type="number" placeholder="value" aria-label="Value"/> <!>', 1), Ee = k('<input class="bo-fm-in svelte-f7i4av" type="date" aria-label="End date"/>'), qe = k('<select class="bo-fm-op svelte-f7i4av" aria-label="Operator"></select> <input class="bo-fm-in svelte-f7i4av" type="date" aria-label="Date"/> <!>', 1), Be = k('<label class="bo-fm-opt svelte-f7i4av"><input type="checkbox"/> <span class="svelte-f7i4av"> </span></label>'), De = k('<input class="bo-fm-in svelte-f7i4av" type="search" placeholder="search…" aria-label="Search values"/> <div class="bo-fm-setbar svelte-f7i4av"><button type="button" class="bo-fm-link svelte-f7i4av">All</button> <button type="button" class="bo-fm-link svelte-f7i4av">None</button></div> <div class="bo-fm-list svelte-f7i4av"></div>', 1), Fe = k('<select class="bo-fm-op svelte-f7i4av" aria-label="Operator"></select> <input class="bo-fm-in svelte-f7i4av" type="text" placeholder="filter…" aria-label="Value"/>', 1), ze = k('<div class="bo-filtermenu svelte-f7i4av" role="dialog" tabindex="-1"><div class="bo-fm-head svelte-f7i4av"> </div> <!> <div class="bo-fm-actions svelte-f7i4av"><button class="bo-fm-btn svelte-f7i4av" type="button">Clear</button> <button class="bo-fm-btn bo-fm-apply svelte-f7i4av" type="button">Apply</button></div></div>');
 const Pe = {
   hash: "svelte-f7i4av",

package/dist/{bo-grid.ToolPanel-C3u-4YKc.js → bo-grid.ToolPanel-CCBi982x.js}

@@ -1,4 +1,4 @@
-import { p as z, a as S, c as d, s as r, r as l, b as f, e as j, t as g, g as s, d as L, f as P, h as i, i as w, j as T, k as q, l as A, m as E, n as B, u as D, o as k, q as F } from "./bo-grid.element-DPnHUXMa.js";
+import { p as z, a as S, c as d, s as r, r as l, b as f, e as j, t as g, g as s, d as L, f as P, h as i, i as w, j as T, k as q, l as A, m as E, n as B, u as D, o as k, q as F } from "./bo-grid.element-BZGnfKB_.js";
 var G = k('<label class="bo-tp-opt svelte-7xdno"><input type="checkbox"/> <span class="svelte-7xdno"> </span></label>'), H = k('<div class="bo-toolpanel svelte-7xdno" role="dialog" tabindex="-1" aria-label="Columns"><div class="bo-tp-head svelte-7xdno"><span>Columns</span> <button type="button" class="bo-tp-link svelte-7xdno">Show all</button></div> <input class="bo-tp-search svelte-7xdno" type="search" placeholder="search…" aria-label="Search columns"/> <div class="bo-tp-list svelte-7xdno"></div></div>');
 const I = {
   hash: "svelte-7xdno",