bo-grid 0.1.0

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

@@ -0,0 +1,76 @@
+import type { Snippet } from 'svelte';
+import type { ColumnDef, GridRow, SortState, CellEditEvent } from './column';
+import { type GridTheme } from './theme';
+import { type AggKind } from './aggregate';
+import type { RowSource } from './source';
+type $$ComponentProps = {
+    rows: GridRow[];
+    columns: ColumnDef[];
+    height: number;
+    /** Row height in px (uniform), or a function for variable heights
+        (in-memory mode only). Default 36. */
+    rowHeight?: number | ((row: GridRow, index: number) => number);
+    /** Built-in theme name or a custom token map. Default 'dark'. */
+    theme?: 'dark' | 'light' | GridTheme;
+    /** Allow drag-to-resize column widths. Default true; opt out per column
+        with `resizable: false`. */
+    resizable?: boolean;
+    /** Show a leading checkbox column for whole-row selection (keyed by row id,
+        stable across sort/filter). Default false. */
+    rowSelection?: boolean;
+    /** Called with the selected row ids whenever the row-selection set changes. */
+    onRowSelectionChange?: (selectedIds: Array<string | number>) => void;
+    /** Column keys to hide (controlled). Build your own column-picker UI and
+        drive this prop — the grid stays presentation-only. */
+    hiddenColumns?: string[];
+    /** Return extra CSS class(es) for a data row (e.g. to colour by value).
+        Style them via `:global(.your-class)` since rows live inside the grid. */
+    rowClass?: (row: GridRow) => string | undefined;
+    /** Identity key for row selection. Defaults to `row.id`; override for
+        string/UUID/composite keys. */
+    getRowId?: (row: GridRow) => string | number;
+    /** Called when a data row is activated by click or Enter (open a detail
+        view, navigate, …). Edit-input and checkbox clicks are excluded. */
+    onRowClick?: (row: GridRow, event: MouseEvent | KeyboardEvent) => void;
+    /** Controlled sort order (multi-key, primary first). When set, the grid
+        reflects this and reports changes via `onSortChange` instead of holding
+        its own state. Omit for uncontrolled sorting. */
+    sort?: SortState[];
+    /** Called with the new sort order whenever a header is clicked. */
+    onSortChange?: (sort: SortState[]) => void;
+    /** Show a pinned totals row: each column with a `groupAgg` shows that
+        aggregate over all (filtered) rows. In-memory mode only. Default false. */
+    footer?: boolean;
+    /** Called when a cell is clicked, with its row, column and value. Fires in
+        addition to `onRowClick`; excluded for the edit input. */
+    onCellClick?: (info: {
+        row: GridRow;
+        column: ColumnDef;
+        value: unknown;
+    }, event: MouseEvent) => void;
+    /** Rows pinned to the top, always visible above the scroll (a benchmark, a
+        summary, "your position"). Display-only — not virtualized or selectable. */
+    pinnedRows?: GridRow[];
+    /** Show a per-column filter input row under the header. Rows must match every
+        non-empty column filter (AND). In-memory mode only. Default false. */
+    filterRow?: boolean;
+    filter?: string;
+    groupBy?: string[];
+    aggregations?: AggKind[];
+    persistKey?: string;
+    /** Back the grid with a windowed/server data source instead of `rows`.
+        In source mode, sort + filter are delegated to the source; grouping is
+        not applied. */
+    source?: RowSource;
+    /** Called when an editable cell is committed. Update your row data in here. */
+    onCellEdit?: (e: CellEditEvent) => void;
+    /** Render content for `type: 'custom'` columns. */
+    cell?: Snippet<[{
+        row: GridRow;
+        column: ColumnDef;
+        value: unknown;
+    }]>;
+};
+declare const Grid: import("svelte").Component<$$ComponentProps, {}, "">;
+type Grid = ReturnType<typeof Grid>;
+export default Grid;

package/dist/grid/GroupRow.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+  import type { ColumnDef, GridRow } from './column';
+  import { colStyle, formatCell } from './column';
+  import { aggregate } from './aggregate';
+  import type { GroupNode } from './grouping';
+
+  let {
+    group,
+    columns,
+    onToggle,
+    rowIndex,
+  }: {
+    group: GroupNode;
+    columns: ColumnDef[];
+    onToggle: (path: string) => void;
+    rowIndex?: number;
+  } = $props();
+
+  // Aggregate over the group's leaf rows. Reads row $state values, so group
+  // subtotals stay live as the feed ticks (only on-screen groups are rendered).
+  function aggText(col: ColumnDef): string {
+    if (col.type === 'sparkline' || col.type === 'text' || !col.groupAgg) return '';
+    const vals: number[] = [];
+    for (const row of group.rows) {
+      const v = Number((row as GridRow)[col.key]);
+      if (Number.isFinite(v)) vals.push(v);
+    }
+    const a = aggregate(vals);
+    if (!a) return '';
+    if (col.groupAgg === 'count') return String(a.count);
+    return formatCell(col, a[col.groupAgg]);
+  }
+</script>
+
+<div class="group" role="row" aria-rowindex={rowIndex}>
+  <button
+    class="toggle"
+    type="button"
+    style={colStyle(columns[0])}
+    aria-expanded={!group.collapsed}
+    onclick={() => onToggle(group.path)}
+  >
+    <span class="chev" style="margin-left:{group.depth * 12}px">{group.collapsed ? '▸' : '▾'}</span>
+    <span class="val">{group.value}</span>
+    <span class="count">{group.count}</span>
+  </button>
+
+  {#each columns as col, ci (ci)}
+    {#if ci > 0}
+      <span class="agg" style={colStyle(col)}>{aggText(col)}</span>
+    {/if}
+  {/each}
+</div>
+
+<style>
+  .group {
+    display: flex;
+    align-items: stretch;
+    width: 100%;
+    height: 100%;
+    background: color-mix(in srgb, var(--bo-header-bg) 85%, var(--bo-text) 4%);
+    border-bottom: 0.5px solid var(--bo-border);
+  }
+  .toggle {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-width: 0;
+    padding: 0 8px;
+    font: inherit;
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--bo-text);
+    background: transparent;
+    border: 0;
+    cursor: pointer;
+    text-align: left;
+  }
+  .chev {
+    font-size: 10px;
+    color: var(--bo-text-dim);
+  }
+  .val {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+  .count {
+    flex: none;
+    padding: 0 5px;
+    font-family: var(--bo-mono);
+    font-size: 10px;
+    font-weight: 500;
+    color: var(--bo-text-dim);
+    background: var(--bo-row-hover);
+    border-radius: 999px;
+  }
+  .agg {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    padding: 0 8px;
+    font-family: var(--bo-mono);
+    font-size: 11px;
+    font-variant-numeric: tabular-nums;
+    color: var(--bo-text-dim);
+    overflow: hidden;
+    white-space: nowrap;
+  }
+</style>

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

@@ -0,0 +1,11 @@
+import type { ColumnDef } from './column';
+import type { GroupNode } from './grouping';
+type $$ComponentProps = {
+    group: GroupNode;
+    columns: ColumnDef[];
+    onToggle: (path: string) => void;
+    rowIndex?: number;
+};
+declare const GroupRow: import("svelte").Component<$$ComponentProps, {}, "">;
+type GroupRow = ReturnType<typeof GroupRow>;
+export default GroupRow;

package/dist/grid/aggregate.d.ts

@@ -0,0 +1,11 @@
+export type AggKind = 'sum' | 'avg' | 'count' | 'min' | 'max';
+export interface AggResult {
+    sum: number;
+    avg: number;
+    count: number;
+    min: number;
+    max: number;
+}
+/** Aggregate a list of numbers. Returns null for an empty list. */
+export declare function aggregate(values: number[]): AggResult | null;
+export declare const AGG_LABELS: Record<AggKind, string>;

package/dist/grid/aggregate.js

@@ -0,0 +1,23 @@
+/** Aggregate a list of numbers. Returns null for an empty list. */
+export function aggregate(values) {
+    if (values.length === 0)
+        return null;
+    let sum = 0;
+    let min = Infinity;
+    let max = -Infinity;
+    for (const v of values) {
+        sum += v;
+        if (v < min)
+            min = v;
+        if (v > max)
+            max = v;
+    }
+    return { sum, avg: sum / values.length, count: values.length, min, max };
+}
+export const AGG_LABELS = {
+    sum: 'Sum',
+    avg: 'Avg',
+    count: 'Count',
+    min: 'Min',
+    max: 'Max',
+};

package/dist/grid/clipboard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse clipboard text into a rectangular grid of cell strings.
+ *
+ * Tolerates CRLF / lone CR line endings and a single trailing newline
+ * (spreadsheets append one when copying a range). Empty input yields `[]`.
+ */
+export declare function parseClipboard(text: string): string[][];
+/** True when the parsed clipboard holds exactly one cell. */
+export declare function isSingleCell(grid: string[][]): boolean;

package/dist/grid/clipboard.js

@@ -0,0 +1,24 @@
+// Clipboard TSV (tab-separated values) parsing for paste support.
+//
+// Spreadsheets (Excel, Google Sheets) and the grid's own copy use a simple
+// TSV shape: rows joined by "\n", cells within a row joined by "\t". This is
+// deliberately not full CSV — no quoting/escaping — to match what copy emits
+// and what spreadsheets put on the clipboard for a plain rectangular range.
+/**
+ * Parse clipboard text into a rectangular grid of cell strings.
+ *
+ * Tolerates CRLF / lone CR line endings and a single trailing newline
+ * (spreadsheets append one when copying a range). Empty input yields `[]`.
+ */
+export function parseClipboard(text) {
+    let t = text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    if (t.endsWith('\n'))
+        t = t.slice(0, -1);
+    if (t === '')
+        return [];
+    return t.split('\n').map((line) => line.split('\t'));
+}
+/** True when the parsed clipboard holds exactly one cell. */
+export function isSingleCell(grid) {
+    return grid.length === 1 && grid[0].length === 1;
+}

package/dist/grid/column.d.ts

@@ -0,0 +1,95 @@
+import type { Candle } from '../types';
+import { type DateStyle } from '../format/format';
+import type { AggKind } from './aggregate';
+export type Align = 'left' | 'right';
+interface ColBase {
+    /** Field on the row to read for this column's value. */
+    key: string;
+    header: string;
+    /** Fixed width in px. Ignored when `flex` is set. */
+    width?: number;
+    /** flex-grow weight; column stretches to fill remaining space. */
+    flex?: number;
+    align?: Align;
+    /** Amber flash on value change (drives off the row's flashSeq/flashDir). */
+    flash?: boolean;
+    /** Set false to disable header-click sorting on this column. */
+    sortable?: boolean;
+    /** When grouping is active, show this aggregate of the column on group headers. */
+    groupAgg?: AggKind;
+    /** Pin this column to the left; it stays visible during horizontal scroll. */
+    pinned?: boolean;
+    /** Allow inline editing (double-click or Enter on the focused cell). */
+    editable?: boolean;
+    /** Validate an edited value before it commits (inline edit or paste). Return
+        false to reject and keep the old value. Receives the coerced value. */
+    validate?: (value: string | number, row: GridRow) => boolean;
+    /** 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
+        spanning header. Best with fixed-width columns. */
+    group?: string;
+}
+export interface CellEditEvent {
+    row: GridRow;
+    column: ColumnDef;
+    /** Parsed value: a number for numeric columns, otherwise the raw string. */
+    value: string | number;
+}
+/**
+ * Discriminated column config — the public Phase 0 "columns + rows" surface,
+ * extended with the Phase 1 sparkline + heatmap cell types.
+ */
+export type ColumnDef = (ColBase & {
+    type: 'text';
+    sub?: string;
+}) | (ColBase & {
+    type: 'price';
+}) | (ColBase & {
+    type: 'percent';
+}) | (ColBase & {
+    type: 'volume';
+}) | (ColBase & {
+    type: 'number';
+    decimals?: number;
+}) | (ColBase & {
+    type: 'date';
+    dateStyle?: DateStyle;
+}) | (ColBase & {
+    type: 'heatmap';
+    min: number;
+    max: number;
+    decimals?: number;
+}) | (ColBase & {
+    type: 'sparkline';
+    sparkKey: string;
+}) | (ColBase & {
+    type: 'custom';
+});
+export type SortDir = 'asc' | 'desc';
+export interface SortState {
+    key: string;
+    dir: SortDir;
+}
+/** Minimal row contract the grid relies on. Concrete rows add their own fields. */
+export interface GridRow {
+    id: number;
+    flashSeq: number;
+    flashDir: 'up' | 'down';
+    [field: string]: unknown;
+}
+export declare function formatCell(col: ColumnDef, value: unknown): string;
+export declare function isSortable(col: ColumnDef): boolean;
+export declare function isEditable(col: ColumnDef): boolean;
+export declare function compareRows(a: GridRow, b: GridRow, sort: SortState): number;
+/**
+ * Multi-key comparison: apply each sort in order, returning the first that
+ * separates the rows. An empty list leaves rows in their original order.
+ */
+export declare function compareBySorts(a: GridRow, b: GridRow, sorts: readonly SortState[]): number;
+export declare function colStyle(col: ColumnDef): string;
+/** Concrete pixel width for a column (flex columns get a sensible default). */
+export declare function colWidth(col: ColumnDef): number;
+export declare function isNumeric(col: ColumnDef): boolean;
+export declare function candlesOf(row: GridRow, key: string): Candle[];
+export {};

package/dist/grid/column.js

@@ -0,0 +1,62 @@
+import { fmtPrice, fmtPercent, fmtVolume, fmtDate } from '../format/format';
+export function formatCell(col, value) {
+    const n = typeof value === 'number' ? value : Number(value);
+    switch (col.type) {
+        case 'price':
+            return fmtPrice(n);
+        case 'percent':
+            return fmtPercent(n);
+        case 'volume':
+            return fmtVolume(n);
+        case 'number':
+            return n.toFixed(col.decimals ?? 2);
+        case 'date':
+            return fmtDate(n, col.dateStyle);
+        case 'heatmap':
+            return n.toFixed(col.decimals ?? 2);
+        default:
+            return value == null ? '' : String(value);
+    }
+}
+export function isSortable(col) {
+    return col.type !== 'sparkline' && col.sortable !== false;
+}
+export function isEditable(col) {
+    return !!col.editable && col.type !== 'sparkline' && col.type !== 'date' && col.type !== 'custom';
+}
+function rawCompare(a, b) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a - b;
+    return String(a ?? '').localeCompare(String(b ?? ''));
+}
+export function compareRows(a, b, sort) {
+    const d = rawCompare(a[sort.key], b[sort.key]);
+    return sort.dir === 'asc' ? d : -d;
+}
+/**
+ * Multi-key comparison: apply each sort in order, returning the first that
+ * separates the rows. An empty list leaves rows in their original order.
+ */
+export function compareBySorts(a, b, sorts) {
+    for (const sort of sorts) {
+        const d = compareRows(a, b, sort);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+export function colStyle(col) {
+    if (col.flex)
+        return `flex:${col.flex} 1 0;min-width:0;`;
+    return `flex:0 0 ${col.width ?? 96}px;`;
+}
+/** Concrete pixel width for a column (flex columns get a sensible default). */
+export function colWidth(col) {
+    return col.flex ? (col.width ?? 160) : (col.width ?? 96);
+}
+export function isNumeric(col) {
+    return col.type !== 'text' && col.type !== 'sparkline' && col.type !== 'custom';
+}
+export function candlesOf(row, key) {
+    return row[key] ?? [];
+}

package/dist/grid/export-xlsx.d.ts

@@ -0,0 +1,8 @@
+import type { ColumnDef, GridRow } from './column';
+import { type ExportOptions } from './export';
+/**
+ * Export rows to a .xlsx file. SheetJS is loaded via dynamic import, so it lands
+ * in its own lazy chunk and never bloats the core bundle. `xlsx` is an optional
+ * peer dependency — install it only if you use this function.
+ */
+export declare function exportXLSX(filename: string, rows: readonly GridRow[], columns: readonly ColumnDef[], opts?: ExportOptions): Promise<void>;

package/dist/grid/export-xlsx.js

@@ -0,0 +1,19 @@
+import { rowsToMatrix } from './export';
+/**
+ * Export rows to a .xlsx file. SheetJS is loaded via dynamic import, so it lands
+ * in its own lazy chunk and never bloats the core bundle. `xlsx` is an optional
+ * peer dependency — install it only if you use this function.
+ */
+export async function exportXLSX(filename, rows, columns, opts = {}) {
+    let XLSX;
+    try {
+        XLSX = await import('xlsx');
+    }
+    catch {
+        throw new Error("bo-grid: xlsx export requires the optional peer dependency 'xlsx' (npm i xlsx)");
+    }
+    const ws = XLSX.utils.aoa_to_sheet(rowsToMatrix(rows, columns, opts));
+    const wb = XLSX.utils.book_new();
+    XLSX.utils.book_append_sheet(wb, ws, 'Sheet1');
+    XLSX.writeFile(wb, filename);
+}

package/dist/grid/export.d.ts

@@ -0,0 +1,19 @@
+import type { ColumnDef, GridRow } from './column';
+export interface ExportOptions {
+    /** Use formatted display strings instead of raw values. Default false. */
+    formatted?: boolean;
+    /** Include a header row. Default true. */
+    header?: boolean;
+}
+type Cell = string | number;
+/**
+ * Build a 2-D matrix (rows × columns) for export. Sparkline columns are skipped.
+ * `formatted` produces display strings; otherwise numeric columns stay numbers
+ * so spreadsheets can compute on them.
+ */
+export declare function rowsToMatrix(rows: readonly GridRow[], columns: readonly ColumnDef[], opts?: ExportOptions): Cell[][];
+export declare function toCSV(rows: readonly GridRow[], columns: readonly ColumnDef[], opts?: ExportOptions): string;
+/** 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;
+export {};

package/dist/grid/export.js

@@ -0,0 +1,48 @@
+import { formatCell, isNumeric } from './column';
+function rawValue(col, v) {
+    if (col.type === 'date')
+        return formatCell(col, v); // epoch ms isn't useful raw
+    if (isNumeric(col)) {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : '';
+    }
+    return v == null ? '' : String(v);
+}
+/**
+ * Build a 2-D matrix (rows × columns) for export. Sparkline columns are skipped.
+ * `formatted` produces display strings; otherwise numeric columns stay numbers
+ * so spreadsheets can compute on them.
+ */
+export function rowsToMatrix(rows, columns, opts = {}) {
+    const cols = columns.filter((c) => c.type !== 'sparkline' && c.type !== 'custom');
+    const matrix = [];
+    if (opts.header !== false)
+        matrix.push(cols.map((c) => c.header));
+    for (const row of rows) {
+        matrix.push(cols.map((c) => (opts.formatted ? formatCell(c, row[c.key]) : rawValue(c, row[c.key]))));
+    }
+    return matrix;
+}
+function csvCell(v) {
+    const s = String(v ?? '');
+    return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+export function toCSV(rows, columns, opts = {}) {
+    return rowsToMatrix(rows, columns, opts)
+        .map((r) => r.map(csvCell).join(','))
+        .join('\r\n');
+}
+/** Trigger a browser download of text content. No-op outside the browser. */
+export function download(filename, content, mime = 'text/csv;charset=utf-8') {
+    if (typeof document === 'undefined' || typeof URL.createObjectURL !== 'function')
+        return;
+    const url = URL.createObjectURL(new Blob([content], { type: mime }));
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+}
+export function exportCSV(filename, rows, columns, opts = {}) {
+    download(filename, toCSV(rows, columns, opts));
+}

package/dist/grid/grouping.d.ts

@@ -0,0 +1,36 @@
+import type { GridRow } from './column';
+export interface GroupNode {
+    /** Unique path, e.g. "Tech" or "Tech/NYSE" for nested groups. */
+    path: string;
+    /** Nesting level, 0 = outermost. */
+    depth: number;
+    /** The group key value (stringified). */
+    value: string;
+    /** All leaf data rows under this group (across nested sub-groups). */
+    rows: GridRow[];
+    count: number;
+    collapsed: boolean;
+}
+export type VisualRow = {
+    kind: 'data';
+    row: GridRow;
+} | {
+    kind: 'group';
+    group: GroupNode;
+};
+/**
+ * Flatten data rows into the visual row list the grid renders: a stream of
+ * group-header rows interleaved with their data rows, honoring collapse state.
+ * Collapsed groups omit their children entirely. Reads only the group-key
+ * fields (which are static), so a realtime tick never rebuilds this list.
+ *
+ * Group headers are the same height as data rows, so the uniform-height virtual
+ * scroller works unchanged — it just windows over a longer mixed list.
+ */
+export declare function buildFlatRows(rows: GridRow[], groupBy: string[], collapsed: Set<string>): VisualRow[];
+/**
+ * The chain of group nodes (outermost → innermost) that the row at `idx` belongs
+ * to. Used to render sticky group headers: scan backward from idx, taking the
+ * nearest preceding header at each depth until the depth-0 group is found.
+ */
+export declare function activeGroupsAt(flat: VisualRow[], idx: number): GroupNode[];

package/dist/grid/grouping.js

@@ -0,0 +1,62 @@
+/**
+ * Flatten data rows into the visual row list the grid renders: a stream of
+ * group-header rows interleaved with their data rows, honoring collapse state.
+ * Collapsed groups omit their children entirely. Reads only the group-key
+ * fields (which are static), so a realtime tick never rebuilds this list.
+ *
+ * Group headers are the same height as data rows, so the uniform-height virtual
+ * scroller works unchanged — it just windows over a longer mixed list.
+ */
+export function buildFlatRows(rows, groupBy, collapsed) {
+    if (groupBy.length === 0)
+        return rows.map((row) => ({ kind: 'data', row }));
+    const out = [];
+    const recurse = (subset, depth, parentPath) => {
+        const key = groupBy[depth];
+        const buckets = new Map();
+        for (const row of subset) {
+            const gv = String(row[key] ?? '');
+            const arr = buckets.get(gv);
+            if (arr)
+                arr.push(row);
+            else
+                buckets.set(gv, [row]);
+        }
+        for (const gv of [...buckets.keys()].sort()) {
+            const groupRows = buckets.get(gv);
+            const path = parentPath ? `${parentPath}/${gv}` : gv;
+            const isCollapsed = collapsed.has(path);
+            out.push({
+                kind: 'group',
+                group: { path, depth, value: gv, rows: groupRows, count: groupRows.length, collapsed: isCollapsed },
+            });
+            if (isCollapsed)
+                continue;
+            if (depth + 1 < groupBy.length)
+                recurse(groupRows, depth + 1, path);
+            else
+                for (const row of groupRows)
+                    out.push({ kind: 'data', row });
+        }
+    };
+    recurse(rows, 0, '');
+    return out;
+}
+/**
+ * The chain of group nodes (outermost → innermost) that the row at `idx` belongs
+ * to. Used to render sticky group headers: scan backward from idx, taking the
+ * nearest preceding header at each depth until the depth-0 group is found.
+ */
+export function activeGroupsAt(flat, idx) {
+    const found = new Map();
+    for (let i = Math.min(idx, flat.length - 1); i >= 0; i--) {
+        const item = flat[i];
+        if (item.kind !== 'group')
+            continue;
+        if (!found.has(item.group.depth))
+            found.set(item.group.depth, item.group);
+        if (item.group.depth === 0)
+            break;
+    }
+    return [...found.values()].sort((a, b) => a.depth - b.depth);
+}

package/dist/grid/heatmap.d.ts

@@ -0,0 +1 @@
+export declare function heatColor(value: number, min: number, max: number): string;

package/dist/grid/heatmap.js

@@ -0,0 +1,12 @@
+// Diverging background ramp for the heatmap column type
+// (proposal Phase 1 §Heatmap column): red below mid, green above.
+const MAX_ALPHA = 0.34;
+export function heatColor(value, min, max) {
+    const span = max - min || 1;
+    const t = Math.max(0, Math.min(1, (value - min) / span)); // 0..1
+    const k = (t - 0.5) * 2; // -1 (cold) .. +1 (hot)
+    const alpha = Math.min(MAX_ALPHA, Math.abs(k) * MAX_ALPHA).toFixed(3);
+    return k < 0
+        ? `rgba(248, 113, 113, ${alpha})` // --down
+        : `rgba(52, 211, 153, ${alpha})`; // --up
+}

package/dist/grid/pin.d.ts

@@ -0,0 +1,23 @@
+import type { ColumnDef } from './column';
+export interface PinInfo {
+    pinned: boolean;
+    /** Sticky left offset (px) when pinned. */
+    left: number;
+    /** Concrete width (px). */
+    width: number;
+}
+export interface PinLayout {
+    /** Columns with pinned ones moved to the front. */
+    columns: ColumnDef[];
+    info: PinInfo[];
+    /** Sum of all column widths (the horizontally-scrollable content width). */
+    totalWidth: number;
+    anyPinned: boolean;
+}
+/**
+ * Arrange columns for pinning: pinned-left columns move to the front, and each
+ * gets a sticky `left` offset (cumulative width of the pinned columns before it).
+ * When nothing is pinned, column order is untouched and the grid stays in its
+ * default fit-to-width layout.
+ */
+export declare function arrangePinned(cols: readonly ColumnDef[]): PinLayout;