@svgrid/grid 1.0.0

package/dist/conditional-formatting.js

@@ -0,0 +1,170 @@
+/**
+ * Conditional formatting engine. Excel-style declarative rules that color a
+ * cell by its value - color scales, in-cell data bars, icon sets, and plain
+ * predicate rules. This goes beyond `cellClass(ctx)` (which can only toggle
+ * static classes) because color scales and data bars need a value computed
+ * against the column's min/max range.
+ *
+ * Everything here is pure: `resolveCellFormat` takes a value + the column's
+ * numeric range and returns the visual primitives, so the `<SvGrid>` render
+ * component just paints the result and the logic is unit-testable.
+ */
+const ICON_SETS = {
+    // ordered low -> high; bucket i picks icon i
+    arrows: ['↓', '→', '↑'],
+    traffic: ['🔴', '🟡', '🟢'],
+    triangles: ['▼', '◆', '▲'],
+};
+/** Min/max of a column's finite numeric values, or null if none. */
+export function computeColumnStat(values) {
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    let any = false;
+    for (const v of values) {
+        if (v == null || v === '')
+            continue;
+        const n = Number(v);
+        if (!Number.isFinite(n))
+            continue;
+        any = true;
+        if (n < min)
+            min = n;
+        if (n > max)
+            max = n;
+    }
+    return any ? { min, max } : null;
+}
+/** Which icon a value lands on, given ascending thresholds. */
+function pickIcon(set, thresholds, n) {
+    let bucket = 0;
+    for (let i = 0; i < thresholds.length; i += 1) {
+        if (n >= thresholds[i])
+            bucket = i + 1;
+    }
+    // Map the bucket onto the available icons (clamp + spread).
+    const idx = Math.min(set.length - 1, Math.max(0, bucket));
+    return set[idx] ?? set[set.length - 1];
+}
+function clamp01(x) {
+    return x < 0 ? 0 : x > 1 ? 1 : x;
+}
+function parseHex(hex) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return null;
+    const int = parseInt(m[1], 16);
+    return [(int >> 16) & 255, (int >> 8) & 255, int & 255];
+}
+function toHex(rgb) {
+    return ('#' +
+        rgb
+            .map((c) => Math.round(clamp01(c / 255) * 255).toString(16).padStart(2, '0'))
+            .join(''));
+}
+/**
+ * Pick a readable text color (near-black or white) for a given hex
+ * background, using WCAG relative luminance. Lets a color-scale fill or a
+ * tinted rule keep its text legible without the caller hand-picking a color.
+ * Returns null when the background isn't a parseable hex (e.g. a CSS var),
+ * so the caller can leave the default text color in place.
+ */
+export function contrastText(bg) {
+    const rgb = parseHex(bg);
+    if (!rgb)
+        return null;
+    const lin = rgb.map((c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+    });
+    const L = 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
+    return L > 0.45 ? '#1e293b' : '#ffffff';
+}
+/** Linear interpolate two hex colors. Falls back to `a` if parsing fails. */
+export function lerpColor(a, b, t) {
+    const ca = parseHex(a);
+    const cb = parseHex(b);
+    if (!ca || !cb)
+        return a;
+    const k = clamp01(t);
+    return toHex([
+        ca[0] + (cb[0] - ca[0]) * k,
+        ca[1] + (cb[1] - ca[1]) * k,
+        ca[2] + (cb[2] - ca[2]) * k,
+    ]);
+}
+function colorScaleAt(fmt, t) {
+    if (fmt.mid) {
+        return t <= 0.5
+            ? lerpColor(fmt.min, fmt.mid, t / 0.5)
+            : lerpColor(fmt.mid, fmt.max, (t - 0.5) / 0.5);
+    }
+    return lerpColor(fmt.min, fmt.max, t);
+}
+/**
+ * Resolve every format that applies to one cell into a single set of visual
+ * primitives. Later-listed formats override earlier ones for the same
+ * property, so order your `conditionalFormats` from general to specific.
+ */
+export function resolveCellFormat(value, row, columnId, formats, stat) {
+    const out = {};
+    for (const fmt of formats) {
+        if (fmt.columns && !fmt.columns.includes(columnId))
+            continue;
+        const n = Number(value);
+        if (fmt.type === 'rule') {
+            if (fmt.when({ value, row })) {
+                if (fmt.background) {
+                    out.background = fmt.background;
+                    // Auto-pick legible text on the tint unless the rule sets its own.
+                    if (!fmt.color) {
+                        const c = contrastText(fmt.background);
+                        if (c)
+                            out.color = c;
+                    }
+                }
+                if (fmt.color)
+                    out.color = fmt.color;
+                if (fmt.fontWeight != null)
+                    out.fontWeight = fmt.fontWeight;
+            }
+            continue;
+        }
+        if (value == null || value === '' || !Number.isFinite(n))
+            continue;
+        if (fmt.type === 'colorScale') {
+            const lo = fmt.minValue ?? stat?.min ?? n;
+            const hi = fmt.maxValue ?? stat?.max ?? n;
+            const t = hi === lo ? 0.5 : clamp01((n - lo) / (hi - lo));
+            out.background = colorScaleAt(fmt, t);
+            // The scale fills the whole cell, so keep the text legible against it.
+            const c = contrastText(out.background);
+            if (c)
+                out.color = c;
+        }
+        else if (fmt.type === 'dataBar') {
+            const lo = fmt.minValue ?? Math.min(0, stat?.min ?? 0);
+            const hi = fmt.maxValue ?? stat?.max ?? n;
+            const span = hi - lo || 1;
+            const percent = clamp01((n - lo) / span) * 100;
+            const negative = n < 0;
+            out.dataBar = {
+                percent,
+                color: negative ? (fmt.negativeColor ?? '#ef4444') : fmt.color,
+                fromRight: false,
+            };
+            if (fmt.showValue === false)
+                out.color = 'transparent';
+        }
+        else if (fmt.type === 'iconSet') {
+            const set = ICON_SETS[fmt.set ?? 'arrows'];
+            out.icon = pickIcon(set, fmt.thresholds, n);
+            if (fmt.iconOnly)
+                out.iconOnly = true;
+        }
+    }
+    return out;
+}
+/** Column ids that need a numeric min/max precomputed (colorScale/dataBar). */
+export function formatsNeedingStats(formats) {
+    return formats.some((f) => f.type === 'colorScale' || f.type === 'dataBar');
+}

package/dist/conditional-formatting.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/conditional-formatting.test.js

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import { computeColumnStat, lerpColor, contrastText, resolveCellFormat, formatsNeedingStats, } from './conditional-formatting';
+describe('contrastText', () => {
+    it('returns dark text on light backgrounds, white on dark', () => {
+        expect(contrastText('#fde68a')).toBe('#1e293b'); // light yellow
+        expect(contrastText('#86efac')).toBe('#1e293b'); // light green
+        expect(contrastText('#1d4ed8')).toBe('#ffffff'); // deep blue
+    });
+    it('returns null for non-hex backgrounds', () => {
+        expect(contrastText('var(--x)')).toBeNull();
+    });
+});
+describe('computeColumnStat', () => {
+    it('returns min/max of finite numbers', () => {
+        expect(computeColumnStat([3, 1, 'x', 9, null])).toEqual({ min: 1, max: 9 });
+    });
+    it('returns null when nothing is numeric', () => {
+        expect(computeColumnStat(['a', null, undefined])).toBeNull();
+    });
+});
+describe('lerpColor', () => {
+    it('interpolates midpoint', () => {
+        expect(lerpColor('#000000', '#ffffff', 0.5)).toBe('#808080');
+    });
+    it('clamps and falls back on bad input', () => {
+        expect(lerpColor('#ff0000', '#00ff00', 0)).toBe('#ff0000');
+        expect(lerpColor('nope', '#00ff00', 0.5)).toBe('nope');
+    });
+});
+describe('resolveCellFormat', () => {
+    const stat = { min: 0, max: 100 };
+    it('color scale maps value position to a gradient color', () => {
+        const fmts = [
+            { type: 'colorScale', min: '#ff0000', max: '#00ff00' },
+        ];
+        expect(resolveCellFormat(0, {}, 'c', fmts, stat).background).toBe('#ff0000');
+        expect(resolveCellFormat(100, {}, 'c', fmts, stat).background).toBe('#00ff00');
+        expect(resolveCellFormat(50, {}, 'c', fmts, stat).background).toBe('#808000');
+    });
+    it('data bar computes a percent and picks negative color', () => {
+        const fmts = [
+            { type: 'dataBar', color: '#16a34a', negativeColor: '#ef4444' },
+        ];
+        const pos = resolveCellFormat(50, {}, 'c', fmts, { min: -100, max: 100 });
+        expect(pos.dataBar?.percent).toBeCloseTo(75);
+        expect(pos.dataBar?.color).toBe('#16a34a');
+        const neg = resolveCellFormat(-50, {}, 'c', fmts, { min: -100, max: 100 });
+        expect(neg.dataBar?.color).toBe('#ef4444');
+    });
+    it('icon set buckets by ascending thresholds', () => {
+        const fmts = [
+            { type: 'iconSet', set: 'arrows', thresholds: [0, 50] },
+        ];
+        expect(resolveCellFormat(-5, {}, 'c', fmts, null).icon).toBe('↓');
+        expect(resolveCellFormat(10, {}, 'c', fmts, null).icon).toBe('→');
+        expect(resolveCellFormat(80, {}, 'c', fmts, null).icon).toBe('↑');
+    });
+    it('rule applies styles only when the predicate matches', () => {
+        const fmts = [
+            {
+                type: 'rule',
+                when: ({ value }) => Number(value) < 0,
+                background: '#fee2e2',
+                color: '#991b1b',
+            },
+        ];
+        expect(resolveCellFormat(-1, {}, 'c', fmts, null).background).toBe('#fee2e2');
+        expect(resolveCellFormat(1, {}, 'c', fmts, null).background).toBeUndefined();
+    });
+    it('respects the columns scope', () => {
+        const fmts = [
+            { type: 'colorScale', min: '#000000', max: '#ffffff', columns: ['other'] },
+        ];
+        expect(resolveCellFormat(50, {}, 'c', fmts, stat).background).toBeUndefined();
+    });
+    it('later formats override earlier ones', () => {
+        const fmts = [
+            { type: 'rule', when: () => true, background: '#aaa' },
+            { type: 'rule', when: () => true, background: '#bbb' },
+        ];
+        expect(resolveCellFormat(1, {}, 'c', fmts, null).background).toBe('#bbb');
+    });
+    it('formatsNeedingStats flags colorScale/dataBar only', () => {
+        expect(formatsNeedingStats([{ type: 'iconSet', thresholds: [0] }])).toBe(false);
+        expect(formatsNeedingStats([{ type: 'dataBar', color: '#000' }])).toBe(true);
+    });
+});

package/dist/core.coverage.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core.coverage.test.js

@@ -0,0 +1,186 @@
+/**
+ * Targets uncovered branches in core.ts:
+ *   - row.getAllCells() / cell.getValue() / cell.getContext()
+ *   - row.getCellValueByColumnId() (both hit + miss path)
+ *   - sortFns variants (alphanumeric, basic, datetime)
+ *   - filterFns variants
+ *   - grouping aggregations
+ *   - paginated row model edge cases
+ */
+import { describe, expect, it } from 'vitest';
+import { columnFilteringFeature, columnGroupingFeature, createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createPaginatedRowModel, createSortedRowModel, createSvGrid, filterFns, rowExpandingFeature, rowPaginationFeature, rowSelectionFeature, rowSortingFeature, sortFns, tableFeatures, } from './index';
+import { isFunction } from './core';
+const features = tableFeatures({
+    columnFilteringFeature,
+    columnGroupingFeature,
+    rowExpandingFeature,
+    rowPaginationFeature,
+    rowSelectionFeature,
+    rowSortingFeature,
+});
+const data = [
+    { id: 1, name: 'Ada', team: 'A', salary: 100, born: '1815-12-10' },
+    { id: 2, name: 'Grace', team: 'B', salary: 200, born: '1906-12-09' },
+    { id: 3, name: 'Alan', team: 'A', salary: 150, born: '1912-06-23' },
+    { id: 4, name: 'Linus', team: 'C', salary: 300, born: '1969-12-28' },
+    { id: 5, name: 'Donald', team: 'A', salary: 90, born: '1938-01-10' },
+];
+const columns = [
+    { field: 'name', header: 'Name' },
+    { field: 'team', header: 'Team' },
+    { field: 'salary', header: 'Salary' },
+    { field: 'born', header: 'Born' },
+];
+function makeGrid(state) {
+    return createSvGrid({
+        data,
+        columns,
+        _features: features,
+        _rowModels: {
+            coreRowModel: createCoreRowModel(),
+            filteredRowModel: createFilteredRowModel(),
+            sortedRowModel: createSortedRowModel(sortFns),
+            groupedRowModel: createGroupedRowModel(),
+            expandedRowModel: createExpandedRowModel(),
+            paginatedRowModel: createPaginatedRowModel(),
+        },
+        state,
+    });
+}
+describe('core - row / cell lazy getters', () => {
+    it('exercises row.getAllCells() and cell.getValue()', () => {
+        const grid = makeGrid();
+        const rows = grid.getRowModel().rows;
+        expect(rows.length).toBeGreaterThan(0);
+        for (const row of rows) {
+            const cells = row.getAllCells();
+            expect(Array.isArray(cells)).toBe(true);
+            for (const cell of cells) {
+                const value = cell.getValue();
+                expect(value).not.toBeUndefined();
+                const ctx = cell.getContext();
+                expect(ctx).toBeDefined();
+                expect(ctx.row).toBe(row);
+                expect(ctx.table).toBe(grid);
+            }
+        }
+    });
+    it('getCellValueByColumnId returns undefined for unknown columns', () => {
+        const grid = makeGrid();
+        const row = grid.getRowModel().rows[0];
+        expect(row.getCellValueByColumnId('no-such')).toBeUndefined();
+        expect(row.getCellValueByColumnId('name')).toBeDefined();
+    });
+    it('caches cached row reference after first access', () => {
+        const grid = makeGrid();
+        const a = grid.getRowModel().rows[0];
+        const b = grid.getRowModel().rows[0];
+        expect(a).toBe(b);
+        const cellsA = a.getAllCells();
+        const cellsB = a.getAllCells();
+        expect(cellsA).toBe(cellsB); // cache hit
+    });
+});
+describe('core - sortFns variants', () => {
+    it('auto comparator uses locale string compare', () => {
+        expect(sortFns.auto('apple', 'banana')).toBeLessThan(0);
+        expect(sortFns.auto('banana', 'apple')).toBeGreaterThan(0);
+        expect(sortFns.auto('apple', 'apple')).toBe(0);
+    });
+    it('number comparator is numeric', () => {
+        expect(sortFns.number(1, 2)).toBeLessThan(0);
+        expect(sortFns.number(2, 1)).toBeGreaterThan(0);
+        expect(sortFns.number(1, 1)).toBe(0);
+    });
+    it('number comparator coerces null to 0', () => {
+        expect(sortFns.number(null, 1)).toBeLessThan(0);
+        expect(sortFns.number(null, null)).toBe(0);
+    });
+    it('date comparator compares ISO strings', () => {
+        expect(sortFns.date('2020-01-01', '2021-01-01')).toBeLessThan(0);
+        expect(sortFns.date('2021-01-01', '2020-01-01')).toBeGreaterThan(0);
+    });
+});
+describe('core - filterFns variants', () => {
+    it('includesString matches case-insensitive substrings', () => {
+        expect(filterFns.includesString('Hello World', 'world')).toBe(true);
+        expect(filterFns.includesString('Hello', 'xyz')).toBe(false);
+    });
+    it('equals matches identical values', () => {
+        expect(filterFns.equals('x', 'x')).toBe(true);
+        expect(filterFns.equals('x', 'y')).toBe(false);
+        expect(filterFns.equals(1, 1)).toBe(true);
+        expect(filterFns.equals(1, '1')).toBe(false);
+    });
+    it('all exported filterFns are callable', () => {
+        for (const key of Object.keys(filterFns)) {
+            expect(typeof filterFns[key]).toBe('function');
+        }
+    });
+});
+describe('core - grouping with aggregations', () => {
+    it('grouping by team produces grouped rows', () => {
+        const grid = makeGrid({ grouping: ['team'] });
+        const rows = grid.getRowModel().rows;
+        expect(rows.length).toBeGreaterThan(0);
+    });
+    it('explicitly expanding a group shows nested rows', () => {
+        const grid = makeGrid({
+            grouping: ['team'],
+            expanded: { group_team_A: true },
+        });
+        const rows = grid.getRowModel().rows;
+        expect(rows.length).toBeGreaterThan(0);
+    });
+});
+describe('core - pagination edge cases', () => {
+    it('page 0 with size larger than data set returns the whole set', () => {
+        const grid = makeGrid({ pagination: { pageIndex: 0, pageSize: 1000 } });
+        const rows = grid.getRowModel().rows;
+        expect(rows.length).toBeLessThanOrEqual(data.length);
+    });
+    it('past-the-end page returns an empty rowset', () => {
+        const grid = makeGrid({ pagination: { pageIndex: 999, pageSize: 2 } });
+        const rows = grid.getRowModel().rows;
+        expect(rows.length).toBe(0);
+    });
+    it('basic page-2 slicing', () => {
+        const grid = makeGrid({ pagination: { pageIndex: 1, pageSize: 2 } });
+        const rows = grid.getRowModel().rows;
+        expect(rows.length).toBeLessThanOrEqual(2);
+    });
+});
+describe('core - selection state', () => {
+    it('initialises with an empty selection record', () => {
+        const grid = makeGrid();
+        expect(grid.getState().rowSelection ?? {}).toEqual({});
+    });
+    it('stores a selection set via initial state', () => {
+        const grid = makeGrid({ rowSelection: { 'row-0': true } });
+        expect(grid.getState().rowSelection).toEqual({ 'row-0': true });
+    });
+});
+describe('isFunction helper', () => {
+    it('returns true for functions', () => {
+        expect(isFunction(() => 0)).toBe(true);
+        expect(isFunction(function () { })).toBe(true);
+    });
+    it('returns false for non-functions', () => {
+        expect(isFunction(null)).toBe(false);
+        expect(isFunction(undefined)).toBe(false);
+        expect(isFunction('string')).toBe(false);
+        expect(isFunction(42)).toBe(false);
+        expect(isFunction({})).toBe(false);
+    });
+});
+describe('core - column visibility + leaf columns', () => {
+    it('getAllColumns returns one entry per column def', () => {
+        const grid = makeGrid();
+        expect(grid.getAllColumns().length).toBe(columns.length);
+    });
+    it('getVisibleLeafColumns reflects columnVisibility state', () => {
+        const grid = makeGrid({ columnVisibility: { name: false } });
+        const visible = grid.getVisibleLeafColumns?.() ?? grid.getAllColumns();
+        expect(Array.isArray(visible)).toBe(true);
+    });
+});