bo-grid 0.21.0 → 1.0.0

package/dist/grid/Pager.svelte

@@ -6,12 +6,20 @@
     pageCount,
     total,
     onGoto,
+    pageSize,
+    pageSizeOptions,
+    onPageSize,
   }: {
     page: number;
     pageCount: number;
     total: number;
     onGoto: (page: number) => void;
+    pageSize?: number;
+    pageSizeOptions?: number[];
+    onPageSize?: (size: number) => void;
   } = $props();
+
+  const showSizes = $derived(!!pageSizeOptions && pageSizeOptions.length > 0);
 </script>
 
 <div class="pager" role="navigation" aria-label="Pagination">
@@ -20,6 +28,20 @@
   <span class="pageinfo">Page {page + 1} of {pageCount} · {total.toLocaleString()} rows</span>
   <button type="button" class="pg" disabled={page >= pageCount - 1} onclick={() => onGoto(page + 1)}>Next ›</button>
   <button type="button" class="pg" disabled={page >= pageCount - 1} aria-label="Last page" onclick={() => onGoto(pageCount - 1)}>»</button>
+  {#if showSizes}
+    <label class="pgsize">
+      Rows
+      <select
+        aria-label="Rows per page"
+        value={pageSize}
+        onchange={(e) => onPageSize?.(Number((e.currentTarget as HTMLSelectElement).value))}
+      >
+        {#each pageSizeOptions as opt (opt)}
+          <option value={opt}>{opt}</option>
+        {/each}
+      </select>
+    </label>
+  {/if}
 </div>
 
 <style>
@@ -60,4 +82,27 @@
     color: var(--bo-text-dim);
     font-variant-numeric: tabular-nums;
   }
+  .pgsize {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    margin-left: auto;
+    font-family: var(--bo-mono);
+    font-size: 11px;
+    color: var(--bo-text-dim);
+  }
+  .pgsize select {
+    font: inherit;
+    font-size: 11px;
+    color: var(--bo-text);
+    background: transparent;
+    border: 0.5px solid var(--bo-border);
+    border-radius: 6px;
+    padding: 2px 4px;
+    cursor: pointer;
+  }
+  .pgsize select:focus-visible {
+    outline: 2px solid var(--bo-sel-border);
+    outline-offset: 1px;
+  }
 </style>

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

@@ -3,6 +3,9 @@ type $$ComponentProps = {
     pageCount: number;
     total: number;
     onGoto: (page: number) => void;
+    pageSize?: number;
+    pageSizeOptions?: number[];
+    onPageSize?: (size: number) => void;
 };
 declare const Pager: import("svelte").Component<$$ComponentProps, {}, "">;
 type Pager = ReturnType<typeof Pager>;

package/dist/grid/column.d.ts

@@ -28,6 +28,13 @@ interface ColBase {
     cellClass?: string | ((value: unknown, row: GridRow) => string | undefined);
     /** Extra class(es) for this column's header. Target via `:global`. */
     headerClass?: string;
+    /** Show a styled tooltip on the column header (the same themed bubble as cell
+        `tooltip`) — describe what the column means, units, caveats. Hovering
+        anywhere on the header reveals it. */
+    headerTooltip?: string;
+    /** Render a small ⓘ info icon in the header as a visible cue that a
+        `headerTooltip` is available. Ignored without `headerTooltip`. */
+    headerInfo?: boolean;
     /** Amber flash on value change (drives off the row's flashSeq/flashDir). */
     flash?: boolean;
     /** Set false to disable header-click sorting on this column. */
@@ -48,13 +55,26 @@ interface ColBase {
     /** Editable choices: when set, editing renders a `<select>` of these options
         instead of a text input (enum/status columns). */
     options?: string[];
-    /** Set a native `title` tooltip on each cell (the full formatted value) — handy
-        when content truncates. */
-    tooltip?: boolean;
+    /** Show a styled floating tooltip on each cell (themed, instant — replaces the
+        native `title`). `true` shows the full formatted value (handy when content
+        truncates); a function returns custom text per value/row (any column type,
+        including `custom`). Return '' to suppress for a given cell. */
+    tooltip?: boolean | ((value: unknown, row: GridRow) => string);
+    /** Let long content wrap to multiple lines instead of truncating with an
+        ellipsis. Pair with a taller `rowHeight`. Default false (single-line +
+        ellipsis). */
+    wrap?: boolean;
     /** Custom display formatter, overriding the built-in type formatter. Applies
         to display, tooltip, copy and (formatted) export. `row` is absent for
         aggregate cells. */
     format?: (value: unknown, row?: GridRow) => string;
+    /** JS cell renderer — the framework-agnostic alternative to the `cell`
+        snippet, for React/Vue/vanilla (and the `<bo-grid>` web component). Return
+        an `HTMLElement`/`Node` (safe — appended as-is) or an HTML **string**
+        (inserted as innerHTML — YOU must sanitize any untrusted data; prefer
+        returning a Node for that). Overrides the cell's display only — sort,
+        filter, tooltip, copy and export still use the value/`format`. */
+    render?: (ctx: CellRenderContext) => string | Node | null | undefined;
     /** Set false to disable drag-to-resize on this column (default on). */
     resizable?: boolean;
     /** Parent header label. Consecutive columns sharing a `group` render under a
@@ -117,6 +137,12 @@ export interface DataBarGeom {
     /** The value is negative (use the bar's `negative` colour). */
     negative: boolean;
 }
+/** Context passed to a column's JS `render` hook. */
+export interface CellRenderContext {
+    value: unknown;
+    row: GridRow;
+    column: ColumnDef;
+}
 export interface CellEditEvent {
     row: GridRow;
     column: ColumnDef;
@@ -204,6 +230,13 @@ export interface GridRow {
  */
 export declare function cellValue(col: ColumnDef, row: GridRow): unknown;
 export declare function formatCell(col: ColumnDef, value: unknown, row?: GridRow): string;
+/**
+ * Resolve a cell's tooltip text for the styled floating tooltip. A boolean
+ * `tooltip` shows the formatted value (skipped for sparkline/custom — no text
+ * form); a function returns custom text for any column type. Empty/whitespace →
+ * no tooltip. Pure; unit-tested.
+ */
+export declare function tooltipText(col: ColumnDef, value: unknown, row: GridRow): string | undefined;
 export declare function isSortable(col: ColumnDef): boolean;
 export declare function isEditable(col: ColumnDef): boolean;
 export declare function compareRows(a: GridRow, b: GridRow, sort: SortState, col?: ColumnDef): number;

package/dist/grid/column.js

@@ -39,6 +39,23 @@ export function formatCell(col, value, row) {
             return value == null ? '' : String(value);
     }
 }
+/**
+ * Resolve a cell's tooltip text for the styled floating tooltip. A boolean
+ * `tooltip` shows the formatted value (skipped for sparkline/custom — no text
+ * form); a function returns custom text for any column type. Empty/whitespace →
+ * no tooltip. Pure; unit-tested.
+ */
+export function tooltipText(col, value, row) {
+    const t = col.tooltip;
+    if (!t)
+        return undefined;
+    const text = typeof t === 'function'
+        ? t(value, row)
+        : col.type === 'sparkline' || col.type === 'custom'
+            ? ''
+            : formatCell(col, value, row);
+    return text && text.trim() ? text : undefined;
+}
 export function isSortable(col) {
     return col.type !== 'sparkline' && col.sortable !== false;
 }

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

@@ -1,7 +1,12 @@
+import type { ComponentProps } from 'svelte';
+import type GridComponent from './grid/Grid.svelte';
 export { default as Grid } from './grid/Grid.svelte';
 export { default as Sparkline } from './sparkline/Sparkline.svelte';
+/** Every `<Grid>` prop, as one object type. Use it to type a config object —
+    especially the `<bo-grid>` web component's `config` (see `bo-grid/element`). */
+export type GridProps = ComponentProps<typeof GridComponent>;
 export type { LazyGroup } from './grid/grouping';
-export type { ColumnDef, Align, GridRow, SortDir, SortState, CellEditEvent, BadgeTone, DataBarConfig, IconRule, ColorScaleConfig, } from './grid/column';
+export type { ColumnDef, Align, GridRow, SortDir, SortState, CellEditEvent, CellRenderContext, BadgeTone, DataBarConfig, IconRule, ColorScaleConfig, } from './grid/column';
 export type { AggKind, AggResult } from './grid/aggregate';
 export type { ColumnFilter, FilterKind, TextOp, NumberOp, DateOp } from './grid/filtering';
 export { fmtPrice, fmtPercent, fmtVolume, fmtDate, fmtCurrency, relativeTime } from './format/format';
@@ -13,9 +18,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

@@ -4,7 +4,6 @@
 // This surface is intentionally small — every export is a compatibility promise.
 // Internal helpers (layout, sorting, grouping, selection internals) are NOT
 // exported; they can change freely between versions.
-// Components
 export { default as Grid } from './grid/Grid.svelte';
 export { default as Sparkline } from './sparkline/Sparkline.svelte';
 // Value formatters (handy when building custom cell content)
@@ -17,8 +16,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": "1.0.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.",
@@ -39,6 +39,7 @@
       "default": "./dist/charts/index.js"
     },
     "./element": {
+      "types": "./dist/bo-grid.element.d.ts",
       "default": "./dist/bo-grid.element.js"
     },
     "./package.json": "./package.json"
@@ -61,7 +62,7 @@
     "demo:build": "vite build",
     "pages:build": "vite build --base=/bo-grid/ --outDir demo-dist",
     "preview": "vite preview",
-    "package": "svelte-package -i src/lib -o dist && node scripts/clean-dist.mjs && pnpm run build:wc",
+    "package": "svelte-package -i src/lib -o dist && node scripts/clean-dist.mjs && pnpm run build:wc && node scripts/emit-element-dts.mjs",
     "build:wc": "vite build --config vite.wc.config.ts",
     "prepublishOnly": "pnpm run package",
     "check": "svelte-check --tsconfig ./tsconfig.json",
@@ -69,6 +70,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",