bo-grid 0.2.0 → 0.8.0

package/README.md

@@ -6,7 +6,8 @@ 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)**
+**[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
@@ -15,14 +16,16 @@ 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 (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.**
+> **Status: actively developed.** Working: config-driven columns, virtual scroll,
+> sort (single / multi / controlled), filtering (global, per-column row, header
+> filter menus with set / number / date filters, quick search, controlled +
+> server-side), multi-cell selection + live aggregation, grouping (nested, sticky,
+> subtotals), pivot, tree data, master-detail, a server-side `RowSource` for huge
+> datasets, CSV/Excel export, column management (reorder, resize, pin L/R, hide,
+> autosize, tool panel, column menu), spreadsheet editing (inline + typed editors,
+> validation, copy/paste, fill handle, undo/redo), row selection, pagination,
+> 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.
@@ -145,9 +148,27 @@ to opt out. Sorting is a snapshot — rows hold position while their values upda
 in place (trading-grid behaviour), so a realtime feed never reshuffles the view.
 
 Pass a `filter` string to quick-filter rows (matches across column values). Drive
-it from your own search input — the grid stays presentation-only. Set `filterRow`
-to add a row of **per-column filter inputs** under the header (rows must match
-every non-empty column filter; in-memory mode).
+it from your own search input — or set `quickFilter` for a **built-in search box**
+above the grid. Set `filterRow` to add a row of **per-column filter inputs** under
+the header (rows must match every non-empty column filter; in-memory mode).
+
+For richer filtering, set `filterMenu` to add a **funnel to each column header**.
+Clicking it opens a menu whose control matches the column type — text
+(contains / equals / starts / ends), number (`=, ≠, <, ≤, >, ≥, between`), or date
+(before / after / on / between). Set `col.filter: 'set'` for a **set filter** — a
+searchable checkbox list of the column's distinct values (All / None). The menu
+is lazy-loaded on first open, so it costs nothing until used; disable it per
+column with `col.filter: false`:
+
+```svelte
+<Grid {rows} {columns} height={640} filterMenu />
+```
+
+Filtering is uncontrolled by default. To **own the filter state** (persist it, set
+initial filters, sync to the URL), pass a controlled `columnFilters` map and
+handle `onFilterChange` — mirrors controlled `sort`. In **server (`source`) mode**
+the filter menu still works: text/number/date filters are delegated to your
+`RowSource` via `params.columnFilters` (set filters need in-memory data).
 
 Sorting is uncontrolled by default. To own it (persist it, set an initial sort,
 or sync to the URL), pass a controlled `sort` array and handle `onSortChange`:
@@ -171,6 +192,13 @@ values flow through the same validation as inline editing — non-editable colum
 and invalid numbers are skipped — and each accepted cell emits `onCellEdit`, so
 paste only does anything when you've wired that callback.
 
+Set `fillHandle` for an **Excel-style fill handle**: the selection grows a small
+square at its bottom-right corner; drag it down or right to copy the selected
+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.
+
 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:
@@ -264,6 +292,30 @@ these:
 }
 ```
 
+Native form controls (checkboxes, date pickers, number spinners, search inputs,
+scrollbars) follow the theme automatically via `color-scheme` + `accent-color`.
+A custom theme defaults to dark; set `scheme: 'light'` (or `--bo-grid-scheme:
+light`) for a light one.
+
+**Tokens** cover colour, typography (`mono`/`sans`/`fontSize`), shape (`radius`),
+and density (`cellPad`, plus the `rowHeight` prop) — so the whole look is yours.
+Numeric columns use tabular figures so digits line up. A few looks:
+
+```svelte
+<!-- Compact / dense -->
+<Grid {rows} {columns} rowHeight={28}
+  theme={{ fontSize: '12px', cellPad: '6px' }} height={640} />
+
+<!-- Roomy & rounded -->
+<Grid {rows} {columns} rowHeight={44}
+  theme={{ radius: '16px', cellPad: '16px', fontSize: '14px' }} height={640} />
+
+<!-- Branded -->
+<Grid {rows} {columns}
+  theme={{ bg: '#0b1020', headerBg: '#0d1226', up: '#22d3ee', down: '#fb7185',
+           selBorder: '#22d3ee', radius: '12px' }} height={640} />
+```
+
 ## Server-side / large datasets
 
 Instead of an in-memory `rows` array, back the grid with a **`RowSource`** — the
@@ -327,6 +379,19 @@ your own column-picker UI and drive the prop; the grid stays presentation-only:
 <Grid {rows} {columns} hiddenColumns={['bonus', 'rating']} height={640} />
 ```
 
+Or set `columnMenu` for a **per-column header menu** (a ⋮ trigger, or
+<kbd>Alt</kbd>+<kbd>↓</kbd> on the focused column) with **sort**, **pin**
+(left/right/unpin), **Autosize** (fit to content), and **Hide column** actions,
+and `columnsPanel` for a **"Columns" button** that opens a checklist to toggle
+visibility (and restore hidden columns). Runtime hide/pin compose with
+`hiddenColumns` / `col.pinned`, persist via `persistKey`, and hide reports through
+`onColumnVisibilityChange`:
+
+```svelte
+<Grid {rows} {columns} columnMenu height={640}
+  onColumnVisibilityChange={(hidden) => (myHidden = hidden)} />
+```
+
 ## Header groups
 
 Give columns a `group` label to render a spanning parent header over consecutive
@@ -407,7 +472,9 @@ is keyboard-accessible: the <kbd>ContextMenu</kbd> key (or
 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.
 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
+editor seeded with that character (Excel-style type-to-edit). The editor matches
+the column type: numeric columns get a number input, `date` columns a native date
+picker, `options` columns a `<select>`, everything else a text input. The grid is
 controlled, so it reports the change via `onCellEdit` — update your own row data
 there:
 

package/dist/grid/Cell.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
   import type { ColumnDef, GridRow } from './column';
-  import { formatCell, colStyle, candlesOf } from './column';
+  import { formatCell, colStyle, candlesOf, isNumeric } from './column';
   import { heatColor } from './heatmap';
   import Sparkline from '../sparkline/Sparkline.svelte';
 
@@ -19,6 +19,8 @@
     alt = false,
     editing = false,
     seed = null,
+    fillCorner = false,
+    fillpreview = false,
     colIndex,
     cellId,
     cellSnippet,
@@ -30,6 +32,7 @@
     onCellDblClick,
     onEditCommit,
     onEditCancel,
+    onFillStart,
   }: {
     col: ColumnDef;
     row: GridRow;
@@ -47,6 +50,10 @@
     /** 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;
+    /** Show the fill handle (this cell is the selection's bottom-right corner). */
+    fillCorner?: boolean;
+    /** This cell is inside the in-progress fill drag's preview range. */
+    fillpreview?: boolean;
     colIndex?: number;
     cellId?: string;
     cellSnippet?: Snippet<[{ row: GridRow; column: ColumnDef; value: unknown }]>;
@@ -60,11 +67,14 @@
     onCellDblClick?: (r: number, c: number) => void;
     onEditCommit?: (raw: string) => void;
     onEditCancel?: () => void;
+    onFillStart?: () => void;
   } = $props();
 
   let cancelled = false;
   function focusSelect(node: HTMLInputElement) {
     node.focus();
+    // Only text/search inputs support text selection; number/date inputs throw.
+    if (node.type !== 'text' && node.type !== 'search') return;
     // 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);
@@ -95,6 +105,14 @@
   // goes through the $state getter — fine-grained reactivity is preserved even
   // though the key is only known at runtime.
   const value = $derived(row[col.key]);
+  // Typed inline editor: date columns edit with a date picker, numeric columns
+  // with a numeric input; everything else stays a text input.
+  const editorType = $derived(col.type === 'date' ? 'date' : isNumeric(col) ? 'number' : 'text');
+  const editorValue = $derived(
+    col.type === 'date' && Number.isFinite(Number(value))
+      ? new Date(Number(value)).toISOString().slice(0, 10)
+      : String(value ?? ''),
+  );
   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(
@@ -129,6 +147,7 @@
   class:neg={col.type === 'percent' && Number(value) < 0}
   class:sel={selected}
   class:focus={focused}
+  class:fillpreview={fillpreview}
   style={cellStyle()}
   role="gridcell"
   tabindex="-1"
@@ -191,7 +210,8 @@
   {:else if editing}
     <input
       class="bo-edit"
-      value={seed ?? String(value ?? '')}
+      type={editorType}
+      value={seed ?? editorValue}
       use:focusSelect
       onkeydown={onEditKey}
       onblur={onEditBlur}
@@ -212,6 +232,18 @@
   {:else}
     {formatCell(col, value, row)}
   {/if}
+  {#if fillCorner}
+    <span
+      class="fill-handle"
+      role="button"
+      tabindex="-1"
+      aria-label="Fill"
+      onpointerdown={(e) => {
+        e.stopPropagation();
+        onFillStart?.();
+      }}
+    ></span>
+  {/if}
 </span>
 
 <style>
@@ -219,9 +251,9 @@
     position: relative;
     display: flex;
     align-items: center;
-    padding: 0 8px;
+    padding: 0 var(--bo-cell-pad, 8px);
     height: 100%;
-    font-size: 13px;
+    font-size: var(--bo-font-size, 13px);
     line-height: 1.4;
     overflow: hidden;
     white-space: nowrap;
@@ -318,6 +350,22 @@
       inset 0 0 0 1000px var(--bo-sel-fill),
       inset 0 0 0 1px var(--bo-sel-border);
   }
+  /* Fill: a draggable square at the selection's corner + the drag preview. */
+  .fill-handle {
+    position: absolute;
+    right: -3px;
+    bottom: -3px;
+    width: 7px;
+    height: 7px;
+    background: var(--bo-sel-border);
+    border: 1px solid var(--bo-bg);
+    cursor: crosshair;
+    z-index: 4;
+    touch-action: none;
+  }
+  .c.fillpreview {
+    box-shadow: inset 0 0 0 1px var(--bo-sel-border);
+  }
 
   .flash {
     animation: flash 0.3s linear;

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

@@ -17,6 +17,10 @@ type $$ComponentProps = {
     /** 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;
+    /** Show the fill handle (this cell is the selection's bottom-right corner). */
+    fillCorner?: boolean;
+    /** This cell is inside the in-progress fill drag's preview range. */
+    fillpreview?: boolean;
     colIndex?: number;
     cellId?: string;
     cellSnippet?: Snippet<[{
@@ -42,6 +46,7 @@ type $$ComponentProps = {
     onCellDblClick?: (r: number, c: number) => void;
     onEditCommit?: (raw: string) => void;
     onEditCancel?: () => void;
+    onFillStart?: () => void;
 };
 declare const Cell: import("svelte").Component<$$ComponentProps, {}, "">;
 type Cell = ReturnType<typeof Cell>;

package/dist/grid/FilterMenu.svelte

@@ -0,0 +1,263 @@
+<script lang="ts">
+  // Floating header filter menu. Lazy-loaded by Grid (dynamic import) so it
+  // stays out of the core bundle until a filter is opened. Presentation-only:
+  // the parent owns open/close + position and applies the resulting filter.
+  import { untrack } from 'svelte';
+  import {
+    isFilterActive,
+    type ColumnFilter,
+    type FilterKind,
+    type TextOp,
+    type NumberOp,
+    type DateOp,
+  } from './filtering';
+
+  let {
+    kind,
+    header,
+    filter,
+    values = [],
+    x,
+    y,
+    onApply,
+    onClose,
+  }: {
+    kind: FilterKind;
+    header: string;
+    filter: ColumnFilter | null;
+    /** Distinct column values for a set filter's checklist. */
+    values?: string[];
+    x: number;
+    y: number;
+    onApply: (f: ColumnFilter | null) => void;
+    onClose: () => void;
+  } = $props();
+
+  const TEXT_OPS: Array<{ op: TextOp; label: string }> = [
+    { op: 'contains', label: 'Contains' },
+    { op: 'notContains', label: 'Not contains' },
+    { op: 'equals', label: 'Equals' },
+    { op: 'starts', label: 'Starts with' },
+    { op: 'ends', label: 'Ends with' },
+  ];
+  const NUMBER_OPS: Array<{ op: NumberOp; label: string }> = [
+    { op: 'eq', label: '=' },
+    { op: 'ne', label: '≠' },
+    { op: 'lt', label: '<' },
+    { op: 'le', label: '≤' },
+    { op: 'gt', label: '>' },
+    { op: 'ge', label: '≥' },
+    { op: 'between', label: 'Between' },
+  ];
+  const DATE_OPS: Array<{ op: DateOp; label: string }> = [
+    { op: 'on', label: 'On' },
+    { op: 'before', label: 'Before' },
+    { op: 'after', label: 'After' },
+    { op: 'between', label: 'Between' },
+  ];
+
+  const toMs = (s: string): number => (s ? Date.parse(`${s}T00:00:00Z`) : NaN);
+  const toDateInput = (ms: number): string =>
+    Number.isFinite(ms) ? new Date(ms).toISOString().slice(0, 10) : '';
+
+  // Local draft, seeded once from the active filter. The menu is recreated each
+  // time it opens, so capturing the initial prop value (not tracking it) is what
+  // we want.
+  const init = untrack(() => filter);
+  let textOp = $state<TextOp>(init?.kind === 'text' ? init.op : 'contains');
+  let textQ = $state(init?.kind === 'text' ? init.q : '');
+  let numOp = $state<NumberOp>(init?.kind === 'number' ? init.op : 'eq');
+  let numA = $state<number | null>(init?.kind === 'number' && Number.isFinite(init.a) ? init.a : null);
+  let numB = $state<number | null>(
+    init?.kind === 'number' && init.b != null && Number.isFinite(init.b) ? init.b : null,
+  );
+  let dateOp = $state<DateOp>(init?.kind === 'date' ? init.op : 'on');
+  let dateA = $state(init?.kind === 'date' ? toDateInput(init.a) : '');
+  let dateB = $state(init?.kind === 'date' && init.b != null ? toDateInput(init.b) : '');
+  // Set filter: track the *excluded* values (unchecked boxes).
+  let excluded = $state(new Set<string>(init?.kind === 'set' ? init.excluded : []));
+  let search = $state('');
+  const shown = $derived(values.filter((v) => v.toLowerCase().includes(search.trim().toLowerCase())));
+  function toggleVal(v: string) {
+    const n = new Set(excluded);
+    if (n.has(v)) n.delete(v);
+    else n.add(v);
+    excluded = n;
+  }
+
+  function build(): ColumnFilter | null {
+    let f: ColumnFilter;
+    if (kind === 'number') {
+      f = { kind: 'number', op: numOp, a: numA ?? NaN, b: numB ?? undefined };
+    } else if (kind === 'date') {
+      f = { kind: 'date', op: dateOp, a: toMs(dateA), b: dateB ? toMs(dateB) : undefined };
+    } else if (kind === 'set') {
+      f = { kind: 'set', excluded: [...excluded] };
+    } else {
+      f = { kind: 'text', op: textOp, q: textQ };
+    }
+    return isFilterActive(f) ? f : null;
+  }
+
+  function apply() {
+    onApply(build());
+  }
+  function clear() {
+    onApply(null);
+  }
+  function onKey(e: KeyboardEvent) {
+    if (e.key === 'Enter') apply();
+    else if (e.key === 'Escape') onClose();
+  }
+</script>
+
+<div
+  class="bo-filtermenu"
+  role="dialog"
+  tabindex="-1"
+  aria-label="Filter {header}"
+  style="left:{x}px;top:{y}px;"
+  onpointerdown={(e) => e.stopPropagation()}
+  onkeydown={onKey}
+>
+  <div class="bo-fm-head">{header}</div>
+
+  {#if kind === 'number'}
+    <select class="bo-fm-op" bind:value={numOp} aria-label="Operator">
+      {#each NUMBER_OPS as o (o.op)}<option value={o.op}>{o.label}</option>{/each}
+    </select>
+    <input class="bo-fm-in" type="number" bind:value={numA} placeholder="value" aria-label="Value" />
+    {#if numOp === 'between'}
+      <input class="bo-fm-in" type="number" bind:value={numB} placeholder="and" aria-label="Upper value" />
+    {/if}
+  {:else if kind === 'date'}
+    <select class="bo-fm-op" bind:value={dateOp} aria-label="Operator">
+      {#each DATE_OPS as o (o.op)}<option value={o.op}>{o.label}</option>{/each}
+    </select>
+    <input class="bo-fm-in" type="date" bind:value={dateA} aria-label="Date" />
+    {#if dateOp === 'between'}
+      <input class="bo-fm-in" type="date" bind:value={dateB} aria-label="End date" />
+    {/if}
+  {:else if kind === 'set'}
+    <input class="bo-fm-in" type="search" bind:value={search} placeholder="search…" aria-label="Search values" />
+    <div class="bo-fm-setbar">
+      <button type="button" class="bo-fm-link" onclick={() => (excluded = new Set())}>All</button>
+      <button type="button" class="bo-fm-link" onclick={() => (excluded = new Set(values))}>None</button>
+    </div>
+    <div class="bo-fm-list">
+      {#each shown as v (v)}
+        <label class="bo-fm-opt">
+          <input type="checkbox" checked={!excluded.has(v)} onchange={() => toggleVal(v)} />
+          <span>{v === '' ? '(blank)' : v}</span>
+        </label>
+      {/each}
+    </div>
+  {:else}
+    <select class="bo-fm-op" bind:value={textOp} aria-label="Operator">
+      {#each TEXT_OPS as o (o.op)}<option value={o.op}>{o.label}</option>{/each}
+    </select>
+    <!-- svelte-ignore a11y_autofocus -->
+    <input class="bo-fm-in" type="text" bind:value={textQ} placeholder="filter…" aria-label="Value" autofocus />
+  {/if}
+
+  <div class="bo-fm-actions">
+    <button class="bo-fm-btn" type="button" onclick={clear}>Clear</button>
+    <button class="bo-fm-btn bo-fm-apply" type="button" onclick={apply}>Apply</button>
+  </div>
+</div>
+
+<style>
+  .bo-filtermenu {
+    position: fixed;
+    z-index: 30;
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    width: 200px;
+    padding: 10px;
+    background: var(--bo-header-bg);
+    border: 0.5px solid var(--bo-border);
+    border-radius: 8px;
+    box-shadow: 0 10px 30px rgba(0, 0, 0, 0.35);
+    font-size: 12px;
+    color: var(--bo-text);
+  }
+  .bo-fm-head {
+    font-weight: 600;
+    color: var(--bo-text-dim);
+    padding-bottom: 2px;
+  }
+  .bo-fm-op,
+  .bo-fm-in {
+    width: 100%;
+    padding: 5px 7px;
+    font: inherit;
+    color: var(--bo-text);
+    background: var(--bo-bg);
+    border: 0.5px solid var(--bo-border);
+    border-radius: 5px;
+  }
+  .bo-fm-setbar {
+    display: flex;
+    gap: 12px;
+  }
+  .bo-fm-link {
+    padding: 0;
+    font: inherit;
+    font-size: 11px;
+    color: var(--bo-up);
+    background: none;
+    border: 0;
+    cursor: pointer;
+  }
+  .bo-fm-link:hover {
+    text-decoration: underline;
+  }
+  .bo-fm-list {
+    display: flex;
+    flex-direction: column;
+    max-height: 180px;
+    overflow-y: auto;
+    border: 0.5px solid var(--bo-border);
+    border-radius: 5px;
+  }
+  .bo-fm-opt {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+    padding: 4px 7px;
+    cursor: pointer;
+    white-space: nowrap;
+  }
+  .bo-fm-opt:hover {
+    background: var(--bo-row-hover);
+  }
+  .bo-fm-opt span {
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  .bo-fm-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 6px;
+    margin-top: 2px;
+  }
+  .bo-fm-btn {
+    padding: 5px 12px;
+    font: inherit;
+    font-size: 11px;
+    color: var(--bo-text-dim);
+    background: transparent;
+    border: 0.5px solid var(--bo-border);
+    border-radius: 5px;
+    cursor: pointer;
+  }
+  .bo-fm-btn:hover {
+    color: var(--bo-text);
+  }
+  .bo-fm-apply {
+    color: #0a0a0a;
+    background: var(--bo-up);
+    border-color: var(--bo-up);
+  }
+</style>

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

@@ -0,0 +1,15 @@
+import { type ColumnFilter, type FilterKind } from './filtering';
+type $$ComponentProps = {
+    kind: FilterKind;
+    header: string;
+    filter: ColumnFilter | null;
+    /** Distinct column values for a set filter's checklist. */
+    values?: string[];
+    x: number;
+    y: number;
+    onApply: (f: ColumnFilter | null) => void;
+    onClose: () => void;
+};
+declare const FilterMenu: import("svelte").Component<$$ComponentProps, {}, "">;
+type FilterMenu = ReturnType<typeof FilterMenu>;
+export default FilterMenu;