bo-grid 0.1.0 → 0.2.0

package/README.md

@@ -1,26 +1,30 @@
 # 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 a few KB.
+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.
 
 **[Live demo](https://bonguynvan.github.io/bo-grid/)** ·
-**[API reference](https://bonguynvan.github.io/bo-grid/api.html)**
+**[API reference](https://bonguynvan.github.io/bo-grid/api.html)** ·
+**[Benchmarks](./BENCHMARKS.md)**
 
-The demo is a small gallery of seven grid types — a realtime **Trading desk**, a
+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, and a **1M-row** trade
-tape windowed from a synthetic source — switch between them with the tabs.
-
-> **Status: v0.1 (early).** Working: config-driven columns, virtual scroll,
-> client sort + filter, multi-cell selection + live range aggregation, row
-> grouping (nested, collapsible, sticky headers, live subtotals), a server-side
+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.
+
+> **Status: v0.2.** Working: config-driven columns, virtual scroll, client
+> single/multi/controlled sort + global & per-column filters, multi-cell selection
+> + live range aggregation, row grouping (nested, collapsible, sticky headers,
+> live subtotals), pivot tables, tree data, master-detail, a server-side
 > `RowSource` for huge datasets, CSV/Excel export, drag-to-reorder and
-> drag-to-resize columns, pinned columns, inline cell editing with clipboard
-> copy/paste, sparklines, realtime flash, heatmaps. Unit
-> tests (Vitest), type-check, a headless mount smoke-test, and library + demo
-> bundle-size budgets all run in CI. Feature-complete for v0; a formal WCAG audit
+> drag-to-resize columns, pinned columns (left/right), row selection, pagination,
+> inline editing with validation, type-to-edit, clipboard copy/paste, sparklines,
+> realtime flash, heatmaps, theming, and full keyboard a11y. **SSR/SvelteKit-safe.**
+> Unit tests (Vitest), type-check, a headless mount smoke-test, an SSR render
+> check, and library + demo bundle-size budgets all run in CI. A formal WCAG audit
 > is the main thing left — see the roadmap.
 
 ## Why
@@ -30,9 +34,14 @@ tape windowed 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 | ~500 KB | a few KB gzip |
+| Bundle | hundreds of KB | **~20 KB gzip** ([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.
+
 ## Install
 
 ```sh
@@ -40,6 +49,12 @@ npm i bo-grid
 # peer dependency: svelte@^5
 ```
 
+Works with **SvelteKit / SSR** out of the box — `<Grid>` server-renders to HTML
+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.
+
 ## Usage
 
 ```svelte
@@ -112,6 +127,15 @@ 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).
 
+## 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.
+
+```svelte
+<Grid {rows} {columns} height={640} pageSize={25} />
+```
+
 ## Sort & filter
 
 Click a column header to sort (asc → desc → off). **Shift-click** additional
@@ -175,7 +199,8 @@ columns (and `rowClass`) but are display-only:
 
 Set `rowSelection` for a leading checkbox column — whole-row selection keyed by
 `row.id`, so it survives sorting and filtering (unlike the positional cell
-selection above). The header checkbox selects/clears all matching rows.
+selection above). The header checkbox selects/clears all matching rows, and
+<kbd>Space</kbd> toggles the focused row from the keyboard.
 `onRowSelectionChange` reports the selected ids:
 
 ```svelte
@@ -269,8 +294,10 @@ client-only, so it's not applied in source mode.
 
 ## Column reorder
 
-Drag any column header to reorder columns. Pass `persistKey` to remember the
-user's order across reloads (saved to `localStorage`):
+Pass `onRowReorder(from, to)` to enable **drag-to-reorder rows** via a handle in
+the first column — reorder your own `rows` array in the callback (flat, unsorted,
+in-memory lists). Drag any column header to reorder columns; pass `persistKey` to
+remember the user's order across reloads (saved to `localStorage`):
 
 ```svelte
 <Grid {rows} {columns} persistKey="watchlist" height={640} />
@@ -283,8 +310,9 @@ grip to reset it to its default width. Resizing a fit-to-width (`flex`) column
 pins it to the dragged width and lets its neighbours absorb the difference. The
 same `persistKey` remembers widths across reloads.
 
-Resizing is on by default. Turn it off for the whole grid with `resizable={false}`,
-or per column with `resizable: false` (handy for a fixed action column):
+Bound a column's draggable range with `minWidth` / `maxWidth`. Resizing is on by
+default. Turn it off for the whole grid with `resizable={false}`, or per column
+with `resizable: false` (handy for a fixed action column):
 
 ```svelte
 <Grid {rows} {columns} resizable={false} height={640} />
@@ -312,6 +340,33 @@ const columns = [
 ];
 ```
 
+## Tree data
+
+Pass `getChildren` to render hierarchical rows — `rows` become the roots, and each
+node gets an indented first column with an expand chevron when it has children:
+
+```svelte
+<Grid {rows} {columns} height={520} getChildren={(r) => r.children} />
+```
+
+In tree mode the grid renders the tree directly (filter/sort/group/paginate are
+not applied to it). Nodes are keyboard-accessible: **→** expands a collapsed node,
+**←** collapses an expanded one, and rows expose `aria-level` / `aria-expanded`.
+
+## Master-detail
+
+Pass a `detail` snippet to render an expandable panel under each row — the grid
+adds a leading expand toggle and virtualizes the expanded heights (`detailHeight`,
+default 160). In-memory mode:
+
+```svelte
+<Grid {rows} {columns} height={640} detailHeight={120} detail={rowDetail} />
+
+{#snippet rowDetail({ row })}
+  <div class="detail">…anything about {row.name}…</div>
+{/snippet}
+```
+
 ## Per-row styling
 
 Return a class from `rowClass` to style rows by their data (e.g. red/green book
@@ -326,15 +381,35 @@ levels). Rows live inside the grid, so target the class with `:global(...)`:
 </style>
 ```
 
+For per-column styling, a column's `cellClass` (static or `(value, row)`
+conditional) and `headerClass` add classes to that column's cells/header:
+
+```ts
+{ type: 'number', key: 'pnl', header: 'P&L',
+  cellClass: (v) => (Number(v) < 0 ? 'loss' : 'gain'), headerClass: 'num-head' }
+```
+
 `onRowClick(row, event)` fires when a row is activated by click or <kbd>Enter</kbd>
 on the focused cell — wire it to open a detail view or navigate.
 
+Pass `rowMenu(row)` to add a **right-click menu** of row actions; each item runs
+its `onSelect` and the menu closes (also on outside-click or <kbd>Esc</kbd>). It
+is keyboard-accessible: the <kbd>ContextMenu</kbd> key (or
+<kbd>Shift</kbd>+<kbd>F10</kbd>) opens it at the focused cell.
+
+```svelte
+<Grid {rows} {columns} height={640}
+  rowMenu={(r) => [{ label: 'Delete', onSelect: () => remove(r.id) }]} />
+```
+
 ## Inline editing
 
 Mark a column `editable: true`. Double-click a cell (or press <kbd>Enter</kbd> on
 the focused cell) to edit; <kbd>Enter</kbd>/blur commits, <kbd>Esc</kbd> cancels.
-The grid is controlled, so it reports the change via `onCellEdit` — update your
-own row data there:
+Or just start typing — a printable key on a focused editable cell opens the
+editor seeded with that character (Excel-style type-to-edit). The grid is
+controlled, so it reports the change via `onCellEdit` — update your own row data
+there:
 
 ```svelte
 <Grid
@@ -354,17 +429,27 @@ applies to paste too):
 { type: 'number', key: 'qty', header: 'Qty', editable: true, validate: (v) => v >= 0 }
 ```
 
+Give an editable column `options` to edit it via a dropdown instead of a text
+input (enum/status columns):
+
+```ts
+{ type: 'text', key: 'status', header: 'Status', editable: true,
+  options: ['New', 'Active', 'Closed'] }
+```
+
 ## Pinned columns
 
-Set `pinned: true` on a column to keep it visible while the rest scroll
-horizontally. This is opt-in: with no pinned columns the grid stays fit-to-width
-(no horizontal scroll). Pinned columns move to the left edge and stick there.
+Set `pinned: true` (or `'left'`) on a column to keep it visible while the rest
+scroll horizontally; `pinned: 'right'` sticks it to the right edge (e.g. an
+actions or total column). Opt-in: with no pinned columns the grid stays
+fit-to-width (no horizontal scroll).
 
 ```ts
 const columns = [
   { type: 'text',  key: 'symbol', header: 'Symbol', width: 132, pinned: true },
   { type: 'price', key: 'price',  header: 'Price',  width: 88,  pinned: true },
-  // …wider columns scroll under the pinned ones
+  // …wider columns scroll under the pinned ones…
+  { type: 'number', key: 'pnl',   header: 'P&L',    width: 96,  pinned: 'right' },
 ];
 ```
 

package/dist/grid/Cell.svelte

@@ -13,13 +13,17 @@
     selected = false,
     focused = false,
     pinned = false,
-    pinLeft = 0,
+    pinSide = 'left',
+    pinOffset = 0,
     width,
     alt = false,
     editing = false,
+    seed = null,
     colIndex,
     cellId,
     cellSnippet,
+    tree,
+    dragHandle,
     onCellDown,
     onCellEnter,
     onCellClick,
@@ -34,14 +38,22 @@
     selected?: boolean;
     focused?: boolean;
     pinned?: boolean;
-    pinLeft?: number;
+    pinSide?: 'left' | 'right';
+    pinOffset?: number;
     /** Fixed pixel width (pinned/horizontal-scroll mode). */
     width?: number;
     alt?: boolean;
     editing?: boolean;
+    /** Type-to-edit seed: when set, the editor opens pre-filled with this string
+        (the character that triggered the edit) instead of the current value. */
+    seed?: string | null;
     colIndex?: number;
     cellId?: string;
     cellSnippet?: Snippet<[{ row: GridRow; column: ColumnDef; value: unknown }]>;
+    /** Tree-data gutter for the first column: indent + expand chevron. */
+    tree?: { depth: number; hasChildren: boolean; expanded: boolean; onToggle: () => void };
+    /** Drag-to-reorder handle for the first column (HTML5 draggable grip). */
+    dragHandle?: { onStart: () => void; onEnd: () => void };
     onCellDown?: (r: number, c: number, e: PointerEvent) => void;
     onCellEnter?: (r: number, c: number, e: PointerEvent) => void;
     onCellClick?: (r: number, c: number, e: MouseEvent) => void;
@@ -53,7 +65,13 @@
   let cancelled = false;
   function focusSelect(node: HTMLInputElement) {
     node.focus();
-    node.select();
+    // Type-to-edit: keep the seeded character and put the caret after it;
+    // otherwise select the whole value so the next keystroke replaces it.
+    if (seed != null) node.setSelectionRange(node.value.length, node.value.length);
+    else node.select();
+  }
+  function focusEl(node: HTMLElement) {
+    node.focus();
   }
   function onEditKey(e: KeyboardEvent) {
     e.stopPropagation(); // keep arrows/Enter in the input, not the grid
@@ -78,12 +96,22 @@
   // though the key is only known at runtime.
   const value = $derived(row[col.key]);
   const kind = $derived(col.type === 'text' ? 'text' : col.type === 'sparkline' ? 'spark' : 'num');
+  // Optional per-column cell class (static string or value/row function).
+  const extraClass = $derived(
+    typeof col.cellClass === 'function' ? (col.cellClass(value, row) ?? '') : (col.cellClass ?? ''),
+  );
+  // Native tooltip of the full value (opt-in via column `tooltip`).
+  const tip = $derived(
+    col.tooltip && col.type !== 'sparkline' && col.type !== 'custom'
+      ? formatCell(col, value, row)
+      : undefined,
+  );
 
   function cellStyle(): string {
     let s = width != null ? `flex:0 0 ${width}px;width:${width}px;` : colStyle(col);
     if (col.type === 'heatmap') s += `background:${heatColor(Number(value), col.min, col.max)};`;
     if (pinned) {
-      s += `position:sticky;left:${pinLeft}px;z-index:1;`;
+      s += `position:sticky;${pinSide}:${pinOffset}px;z-index:1;`;
       // Pinned cells must be opaque to cover scrolled content. Heatmap already
       // set a background; otherwise match the (alternating) row colour.
       if (col.type !== 'heatmap') s += `background:var(${alt ? '--bo-row-a' : '--bo-row-b'});`;
@@ -95,7 +123,7 @@
 <!-- Keyboard interaction is handled at the grid level (arrow nav via aria-activedescendant + Enter); this cell click is a pointer affordance. -->
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <span
-  class="c {kind}"
+  class="c {kind} {extraClass}"
   class:dim={col.type === 'volume'}
   class:pos={col.type === 'percent' && Number(value) >= 0}
   class:neg={col.type === 'percent' && Number(value) < 0}
@@ -105,6 +133,7 @@
   role="gridcell"
   tabindex="-1"
   id={cellId}
+  title={tip}
   aria-colindex={colIndex}
   aria-selected={selected}
   onpointerdown={(e) => onCellDown?.(r, c, e)}
@@ -112,10 +141,57 @@
   onclick={(e) => onCellClick?.(r, c, e)}
   ondblclick={() => onCellDblClick?.(r, c)}
 >
-  {#if editing}
-    <input
+  {#if dragHandle}
+    <span
+      class="drag-handle"
+      role="button"
+      tabindex="-1"
+      aria-label="Drag to reorder row"
+      draggable="true"
+      onpointerdown={(e) => e.stopPropagation()}
+      ondragstart={() => dragHandle.onStart()}
+      ondragend={() => dragHandle.onEnd()}
+    >⠿</span>
+  {/if}
+  {#if tree}
+    <span class="tree-gutter" style="padding-left:{tree.depth * 16}px">
+      {#if tree.hasChildren}
+        <button
+          class="tree-toggle"
+          type="button"
+          aria-expanded={tree.expanded}
+          aria-label="Toggle children"
+          onpointerdown={(e) => e.stopPropagation()}
+          onclick={(e) => {
+            e.stopPropagation();
+            tree.onToggle();
+          }}
+        >
+          {tree.expanded ? '▾' : '▸'}
+        </button>
+      {:else}
+        <span class="tree-leaf"></span>
+      {/if}
+    </span>
+  {/if}
+  {#if editing && col.options && col.options.length > 0}
+    <select
       class="bo-edit"
       value={String(value ?? '')}
+      use:focusEl
+      onkeydown={onEditKey}
+      onblur={onEditBlur}
+      onpointerdown={(e) => e.stopPropagation()}
+      onclick={(e) => e.stopPropagation()}
+    >
+      {#each col.options as opt (opt)}
+        <option value={opt}>{opt}</option>
+      {/each}
+    </select>
+  {:else if editing}
+    <input
+      class="bo-edit"
+      value={seed ?? String(value ?? '')}
       use:focusSelect
       onkeydown={onEditKey}
       onblur={onEditBlur}
@@ -128,13 +204,13 @@
   {:else if col.type === 'sparkline'}
     <Sparkline candles={candlesOf(row, col.sparkKey)} />
   {:else if col.type === 'text'}
-    <strong>{formatCell(col, value)}</strong>{#if col.sub}<em>{row[col.sub]}</em>{/if}
+    <strong>{formatCell(col, value, row)}</strong>{#if col.sub}<em>{row[col.sub]}</em>{/if}
   {:else if col.flash}
     {#key row.flashSeq}
-      <span class="flash {row.flashDir}">{formatCell(col, value)}</span>
+      <span class="flash {row.flashDir}">{formatCell(col, value, row)}</span>
     {/key}
   {:else}
-    {formatCell(col, value)}
+    {formatCell(col, value, row)}
   {/if}
 </span>
 
@@ -171,6 +247,44 @@
   .spark {
     overflow: visible;
   }
+  /* Tree-data gutter: indent + expand chevron, before the cell content. */
+  .tree-gutter {
+    display: inline-flex;
+    align-items: center;
+    flex: none;
+  }
+  .tree-toggle {
+    width: 18px;
+    height: 18px;
+    padding: 0;
+    font-size: 10px;
+    line-height: 1;
+    color: var(--bo-text-dim);
+    background: transparent;
+    border: 0;
+    border-radius: 4px;
+    cursor: pointer;
+  }
+  .tree-toggle:hover {
+    color: var(--bo-text);
+    background: var(--bo-row-hover);
+  }
+  .tree-leaf {
+    display: inline-block;
+    width: 18px;
+  }
+  .drag-handle {
+    flex: none;
+    margin-right: 4px;
+    font-size: 12px;
+    line-height: 1;
+    color: var(--bo-text-dim);
+    cursor: grab;
+    user-select: none;
+  }
+  .drag-handle:active {
+    cursor: grabbing;
+  }
   .bo-edit {
     width: 100%;
     height: 100%;

package/dist/grid/Cell.svelte.d.ts

@@ -8,11 +8,15 @@ type $$ComponentProps = {
     selected?: boolean;
     focused?: boolean;
     pinned?: boolean;
-    pinLeft?: number;
+    pinSide?: 'left' | 'right';
+    pinOffset?: number;
     /** Fixed pixel width (pinned/horizontal-scroll mode). */
     width?: number;
     alt?: boolean;
     editing?: boolean;
+    /** Type-to-edit seed: when set, the editor opens pre-filled with this string
+        (the character that triggered the edit) instead of the current value. */
+    seed?: string | null;
     colIndex?: number;
     cellId?: string;
     cellSnippet?: Snippet<[{
@@ -20,6 +24,18 @@ type $$ComponentProps = {
         column: ColumnDef;
         value: unknown;
     }]>;
+    /** Tree-data gutter for the first column: indent + expand chevron. */
+    tree?: {
+        depth: number;
+        hasChildren: boolean;
+        expanded: boolean;
+        onToggle: () => void;
+    };
+    /** Drag-to-reorder handle for the first column (HTML5 draggable grip). */
+    dragHandle?: {
+        onStart: () => void;
+        onEnd: () => void;
+    };
     onCellDown?: (r: number, c: number, e: PointerEvent) => void;
     onCellEnter?: (r: number, c: number, e: PointerEvent) => void;
     onCellClick?: (r: number, c: number, e: MouseEvent) => void;