bo-grid 0.25.0 → 1.0.0

package/README.md

@@ -1,7 +1,7 @@
 # bo-grid
 
 Tiny, fast **Svelte 5** data grid for fintech UIs — canvas sparklines, batched
-realtime cell updates, and virtual scrolling, with a core that gzips to ~31 KB
+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.
 
@@ -13,8 +13,8 @@ grids that paywall these features.
 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.
+**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,7 +37,7 @@ 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 | **~31 KB gzip core** ([benchmarks](./BENCHMARKS.md)) |
+| Bundle | hundreds of KB | **~32 KB gzip core** ([benchmarks](./BENCHMARKS.md)) |
 | Svelte | wrapper | native Svelte 5 |
 
 bo-grid ships most of the features other grids put behind a **paid (Enterprise)**
@@ -100,22 +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
+`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. (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.)
+**[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
 
@@ -160,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.
@@ -261,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
@@ -330,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:

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",