@svgrid/grid 1.0.0

package/dist/server-data-source.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Server-Side Row Model (SSRM) controller. A single, documented datasource
+ * contract for grids whose data lives on the server - the "I have a million
+ * rows in a database" case. The consumer implements ONE async `getRows`
+ * function; this controller owns the request lifecycle (sort, filter, page),
+ * de-dupes/races, and pushes results back through `onChange`.
+ *
+ * It's headless and framework-agnostic on purpose: wire `setSort` /
+ * `setFilter` / `setPage` to the grid's controlled callbacks, and render the
+ * grid from the `{ rows, total, loading }` it hands you. See the demo.
+ */
+export type ServerSortModel = Array<{
+    id: string;
+    desc: boolean;
+}>;
+export type ServerFilterModel = {
+    /** Free-text global search. */
+    global?: string;
+    /**
+     * Per-column filters, keyed by column id. `value` (+ `valueTo`) carry the
+     * operator-style filter; `selectedValues` carries a facet/checklist
+     * selection (set-filter). Either or both may be present.
+     */
+    columns?: Record<string, {
+        operator: string;
+        value: string;
+        valueTo?: string;
+        selectedValues?: string[];
+    }>;
+};
+export type ServerRequest = {
+    /** Zero-based index of the first row wanted (inclusive). */
+    startRow: number;
+    /** Index just past the last row wanted (exclusive). */
+    endRow: number;
+    pageIndex: number;
+    pageSize: number;
+    sortModel: ServerSortModel;
+    filterModel: ServerFilterModel;
+};
+export type ServerResult<TData> = {
+    rows: ReadonlyArray<TData>;
+    /** Total row count after filtering (for the pager). */
+    rowCount: number;
+};
+export type ServerDataSource<TData> = {
+    getRows(request: ServerRequest): Promise<ServerResult<TData>>;
+};
+export type ServerState<TData> = {
+    rows: ReadonlyArray<TData>;
+    total: number;
+    loading: boolean;
+    error: unknown;
+    pageIndex: number;
+    pageSize: number;
+    pageCount: number;
+    sortModel: ServerSortModel;
+    filterModel: ServerFilterModel;
+};
+export type ServerController<TData> = {
+    /** Re-fetch the current page (e.g. after a mutation). */
+    refresh(): void;
+    setSort(sortModel: ServerSortModel): void;
+    setFilter(filterModel: ServerFilterModel): void;
+    setPage(pageIndex: number): void;
+    setPageSize(pageSize: number): void;
+    getState(): ServerState<TData>;
+    /** Stop accepting in-flight responses (call on unmount). */
+    dispose(): void;
+};
+export type ServerControllerOptions<TData> = {
+    pageSize?: number;
+    /** Called whenever any of `rows` / `total` / `loading` / page changes. */
+    onChange: (state: ServerState<TData>) => void;
+};
+export declare function createServerDataSource<TData>(source: ServerDataSource<TData>, options: ServerControllerOptions<TData>): ServerController<TData>;

package/dist/server-data-source.js

@@ -0,0 +1,83 @@
+export function createServerDataSource(source, options) {
+    const state = {
+        rows: [],
+        total: 0,
+        loading: false,
+        error: null,
+        pageIndex: 0,
+        pageSize: options.pageSize ?? 50,
+        pageCount: 1,
+        sortModel: [],
+        filterModel: {},
+    };
+    // Monotonic request id: only the latest fetch is allowed to land, so a slow
+    // response for an old sort/filter can't clobber a newer one.
+    let requestSeq = 0;
+    let disposed = false;
+    const emit = () => {
+        state.pageCount = Math.max(1, Math.ceil(state.total / state.pageSize));
+        options.onChange({ ...state });
+    };
+    async function fetchPage() {
+        if (disposed)
+            return;
+        const id = ++requestSeq;
+        state.loading = true;
+        state.error = null;
+        emit();
+        const startRow = state.pageIndex * state.pageSize;
+        try {
+            const result = await source.getRows({
+                startRow,
+                endRow: startRow + state.pageSize,
+                pageIndex: state.pageIndex,
+                pageSize: state.pageSize,
+                sortModel: state.sortModel,
+                filterModel: state.filterModel,
+            });
+            if (disposed || id !== requestSeq)
+                return; // stale
+            state.rows = result.rows;
+            state.total = result.rowCount;
+            state.loading = false;
+            emit();
+        }
+        catch (err) {
+            if (disposed || id !== requestSeq)
+                return;
+            state.rows = [];
+            state.error = err;
+            state.loading = false;
+            emit();
+        }
+    }
+    return {
+        refresh: fetchPage,
+        setSort(sortModel) {
+            state.sortModel = sortModel;
+            state.pageIndex = 0;
+            void fetchPage();
+        },
+        setFilter(filterModel) {
+            state.filterModel = filterModel;
+            state.pageIndex = 0;
+            void fetchPage();
+        },
+        setPage(pageIndex) {
+            const clamped = Math.max(0, pageIndex);
+            if (clamped === state.pageIndex)
+                return;
+            state.pageIndex = clamped;
+            void fetchPage();
+        },
+        setPageSize(pageSize) {
+            state.pageSize = Math.max(1, pageSize);
+            state.pageIndex = 0;
+            void fetchPage();
+        },
+        getState: () => ({ ...state }),
+        dispose() {
+            disposed = true;
+        },
+    };
+}

package/dist/server-data-source.test.d.ts

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

package/dist/server-data-source.test.js

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createServerDataSource } from './server-data-source';
+function makeSource(total = 250, delay = 0) {
+    const all = Array.from({ length: total }, (_, i) => ({ id: i }));
+    return {
+        calls: 0,
+        async getRows(req) {
+            this.calls += 1;
+            if (delay)
+                await new Promise((r) => setTimeout(r, delay));
+            // server applies sort: reverse when desc on 'id'
+            let rows = all;
+            if (req.sortModel[0]?.id === 'id' && req.sortModel[0]?.desc)
+                rows = [...all].reverse();
+            return { rows: rows.slice(req.startRow, req.endRow), rowCount: total };
+        },
+    };
+}
+const flush = () => new Promise((r) => setTimeout(r, 0));
+describe('createServerDataSource', () => {
+    it('fetches a page and reports total + pageCount', async () => {
+        const src = makeSource(250);
+        const states = [];
+        const ctl = createServerDataSource(src, { pageSize: 50, onChange: (s) => states.push(s) });
+        ctl.refresh();
+        await flush();
+        const last = ctl.getState();
+        expect(last.rows).toHaveLength(50);
+        expect(last.total).toBe(250);
+        expect(last.pageCount).toBe(5);
+        expect(last.loading).toBe(false);
+        // emitted a loading=true then loading=false
+        expect(states.some((s) => s.loading)).toBe(true);
+    });
+    it('setPage fetches the right slice', async () => {
+        const src = makeSource(250);
+        const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => { } });
+        ctl.setPage(2);
+        await flush();
+        expect(ctl.getState().rows[0]).toEqual({ id: 100 });
+    });
+    it('setSort resets to page 0 and re-fetches', async () => {
+        const src = makeSource(250);
+        const ctl = createServerDataSource(src, { pageSize: 50, onChange: () => { } });
+        ctl.setPage(2);
+        await flush();
+        ctl.setSort([{ id: 'id', desc: true }]);
+        await flush();
+        const s = ctl.getState();
+        expect(s.pageIndex).toBe(0);
+        expect(s.rows[0]).toEqual({ id: 249 }); // reversed
+    });
+    it('ignores a stale response when a newer request supersedes it', async () => {
+        // slow source: first call (page 0) resolves AFTER the second (page 1)
+        const all = Array.from({ length: 100 }, (_, i) => ({ id: i }));
+        let call = 0;
+        const src = {
+            getRows: vi.fn(async (req) => {
+                call += 1;
+                const delay = call === 1 ? 40 : 5; // first call is slow
+                await new Promise((r) => setTimeout(r, delay));
+                return { rows: all.slice(req.startRow, req.endRow), rowCount: 100 };
+            }),
+        };
+        const ctl = createServerDataSource(src, { pageSize: 10, onChange: () => { } });
+        ctl.refresh(); // page 0 (slow)
+        ctl.setPage(3); // page 30 (fast) - should win
+        await new Promise((r) => setTimeout(r, 80));
+        expect(ctl.getState().rows[0]).toEqual({ id: 30 });
+    });
+    it('dispose stops further updates', async () => {
+        const src = makeSource(50, 20);
+        const onChange = vi.fn();
+        const ctl = createServerDataSource(src, { pageSize: 10, onChange });
+        ctl.refresh();
+        ctl.dispose();
+        await new Promise((r) => setTimeout(r, 40));
+        // only the synchronous loading=true emit happened before dispose
+        expect(ctl.getState().rows).toHaveLength(0);
+    });
+});

package/dist/sparkline.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Sparkline geometry. Pure functions that turn an array of numbers into the
+ * SVG primitives a tiny in-cell chart needs - no DOM, so it is trivially
+ * unit-testable and the `<SvGrid>` render component just paints the result.
+ *
+ * Four chart types, mirroring the de-facto enterprise-grid set:
+ *   - `line`     a single polyline
+ *   - `area`     a polyline plus a filled area down to the baseline
+ *   - `bar`      one column per value, scaled from the dataset min..max
+ *   - `winloss`  fixed-height up/down bars (sign only), e.g. W/L streaks
+ */
+export type SparklineType = 'line' | 'area' | 'bar' | 'winloss';
+export type SparklineConfig = {
+    type?: SparklineType;
+    /** Stroke (line/area) or positive fill (bar/winloss). */
+    color?: string;
+    /** Fill for negative bars / losses. Defaults to a red. */
+    negativeColor?: string;
+    width?: number;
+    height?: number;
+    /** Fix the value scale instead of deriving it from the row's own data. */
+    min?: number;
+    max?: number;
+    lineWidth?: number;
+    /** Draw a dot on the last point (line/area). Default true. */
+    lastPoint?: boolean;
+};
+export type SparklineBar = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    negative: boolean;
+};
+export type SparklineGeometry = {
+    width: number;
+    height: number;
+    type: SparklineType;
+    color: string;
+    negativeColor: string;
+    lineWidth: number;
+    /** `line` / `area`: the polyline through every point. */
+    linePath: string;
+    /** `area`: closed path filled down to the baseline. */
+    areaPath: string;
+    /** `bar` / `winloss`: one rect per value. */
+    bars: SparklineBar[];
+    /** `line` / `area`: the final point, for the end-cap dot. */
+    lastPoint: {
+        x: number;
+        y: number;
+    } | null;
+};
+/** Coerce loose cell values (arrays, comma strings) into a number array. */
+export declare function toSparklineValues(value: unknown): number[];
+export declare function buildSparkline(values: number[], cfg?: SparklineConfig): SparklineGeometry | null;

package/dist/sparkline.js

@@ -0,0 +1,97 @@
+const DEFAULTS = {
+    width: 88,
+    height: 22,
+    color: 'var(--sg-accent, #2563eb)',
+    negativeColor: '#ef4444',
+    lineWidth: 1.5,
+};
+/** Coerce loose cell values (arrays, comma strings) into a number array. */
+export function toSparklineValues(value) {
+    if (Array.isArray(value)) {
+        return value.map((v) => Number(v)).filter((n) => Number.isFinite(n));
+    }
+    if (typeof value === 'string' && value.trim()) {
+        return value
+            .split(/[,\s]+/)
+            .map((v) => Number(v))
+            .filter((n) => Number.isFinite(n));
+    }
+    return [];
+}
+export function buildSparkline(values, cfg = {}) {
+    if (!values.length)
+        return null;
+    const width = cfg.width ?? DEFAULTS.width;
+    const height = cfg.height ?? DEFAULTS.height;
+    const type = cfg.type ?? 'line';
+    const color = cfg.color ?? DEFAULTS.color;
+    const negativeColor = cfg.negativeColor ?? DEFAULTS.negativeColor;
+    const lineWidth = cfg.lineWidth ?? DEFAULTS.lineWidth;
+    const pad = Math.ceil(lineWidth) + 1;
+    const innerW = Math.max(1, width - pad * 2);
+    const innerH = Math.max(1, height - pad * 2);
+    const base = { width, height, type, color, negativeColor, lineWidth };
+    if (type === 'winloss') {
+        const n = values.length;
+        const gap = n > 1 ? Math.min(2, innerW / n / 3) : 0;
+        const slot = innerW / n;
+        const barW = Math.max(1, slot - gap);
+        const mid = height / 2;
+        const h = innerH / 2;
+        const bars = values.map((v, i) => {
+            const x = pad + i * slot + (slot - barW) / 2;
+            if (v > 0)
+                return { x, y: mid - h, w: barW, h, negative: false };
+            if (v < 0)
+                return { x, y: mid, w: barW, h, negative: true };
+            return { x, y: mid - 1, w: barW, h: 2, negative: false };
+        });
+        return { ...base, linePath: '', areaPath: '', bars, lastPoint: null };
+    }
+    const min = cfg.min ?? Math.min(...values);
+    const max = cfg.max ?? Math.max(...values);
+    const span = max - min || 1;
+    if (type === 'bar') {
+        const n = values.length;
+        const gap = n > 1 ? Math.min(2, innerW / n / 3) : 0;
+        const slot = innerW / n;
+        const barW = Math.max(1, slot - gap);
+        // Bars grow from a zero baseline when the data spans zero, else from min.
+        const baseVal = min < 0 && max > 0 ? 0 : min;
+        const baseY = pad + innerH - ((baseVal - min) / span) * innerH;
+        const bars = values.map((v, i) => {
+            const x = pad + i * slot + (slot - barW) / 2;
+            const vy = pad + innerH - ((v - min) / span) * innerH;
+            const top = Math.min(vy, baseY);
+            const h = Math.max(1, Math.abs(vy - baseY));
+            return { x, y: top, w: barW, h, negative: v < baseVal };
+        });
+        return { ...base, linePath: '', areaPath: '', bars, lastPoint: null };
+    }
+    // line / area
+    const n = values.length;
+    const stepX = n > 1 ? innerW / (n - 1) : 0;
+    const pts = values.map((v, i) => ({
+        x: pad + i * stepX,
+        y: pad + innerH - ((v - min) / span) * innerH,
+    }));
+    const linePath = pts
+        .map((p, i) => `${i === 0 ? 'M' : 'L'}${round(p.x)},${round(p.y)}`)
+        .join(' ');
+    const first = pts[0];
+    const last = pts[pts.length - 1];
+    const baseY = pad + innerH;
+    const areaPath = type === 'area'
+        ? `${linePath} L${round(last.x)},${round(baseY)} L${round(first.x)},${round(baseY)} Z`
+        : '';
+    return {
+        ...base,
+        linePath,
+        areaPath,
+        bars: [],
+        lastPoint: cfg.lastPoint === false ? null : { x: last.x, y: last.y },
+    };
+}
+function round(n) {
+    return Math.round(n * 100) / 100;
+}

package/dist/sparkline.test.d.ts

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

package/dist/sparkline.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { buildSparkline, toSparklineValues } from './sparkline';
+describe('toSparklineValues', () => {
+    it('passes through number arrays and drops non-finite', () => {
+        expect(toSparklineValues([1, 2, NaN, 3])).toEqual([1, 2, 3]);
+    });
+    it('parses comma / space separated strings', () => {
+        expect(toSparklineValues('1, 2 3,4')).toEqual([1, 2, 3, 4]);
+    });
+    it('returns [] for empty / unusable input', () => {
+        expect(toSparklineValues(null)).toEqual([]);
+        expect(toSparklineValues('')).toEqual([]);
+        expect(toSparklineValues({})).toEqual([]);
+    });
+});
+describe('buildSparkline', () => {
+    it('returns null for empty data', () => {
+        expect(buildSparkline([])).toBeNull();
+    });
+    it('builds a line path through every point', () => {
+        const g = buildSparkline([0, 5, 10], { type: 'line', width: 100, height: 20 });
+        expect(g.type).toBe('line');
+        expect(g.linePath.startsWith('M')).toBe(true);
+        // three points => one M + two L commands
+        expect((g.linePath.match(/[ML]/g) ?? []).length).toBe(3);
+        expect(g.lastPoint).not.toBeNull();
+    });
+    it('closes the area path back to the baseline', () => {
+        const g = buildSparkline([1, 2, 3], { type: 'area' });
+        expect(g.areaPath.endsWith('Z')).toBe(true);
+    });
+    it('emits one bar per value and flags negatives', () => {
+        const g = buildSparkline([-2, 4, -1], { type: 'bar' });
+        expect(g.bars).toHaveLength(3);
+        expect(g.bars[0].negative).toBe(true);
+        expect(g.bars[1].negative).toBe(false);
+    });
+    it('winloss uses sign only, equal-height up/down bars', () => {
+        const g = buildSparkline([1, -1, 1], { type: 'winloss', height: 20 });
+        expect(g.bars).toHaveLength(3);
+        expect(g.bars[0].negative).toBe(false);
+        expect(g.bars[1].negative).toBe(true);
+        // up and down bars are the same height (sign-only chart)
+        expect(g.bars[0].h).toBeCloseTo(g.bars[1].h);
+    });
+    it('honors a fixed min/max scale', () => {
+        const a = buildSparkline([5, 5, 5], { type: 'line', min: 0, max: 10 });
+        // flat series on a 0..10 scale sits at the vertical middle, not the top
+        const ys = a.linePath.match(/,(-?\d+(\.\d+)?)/g).map((s) => Number(s.slice(1)));
+        expect(new Set(ys).size).toBe(1);
+    });
+});

package/dist/static-functions.d.ts

@@ -0,0 +1 @@
+export { createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createPaginatedRowModel, createSortedRowModel, filterFns, sortFns, tableFeatures, } from './core';

package/dist/static-functions.js

@@ -0,0 +1 @@
+export { createCoreRowModel, createExpandedRowModel, createFilteredRowModel, createGroupedRowModel, createPaginatedRowModel, createSortedRowModel, filterFns, sortFns, tableFeatures, } from './core';

package/dist/subscribe.d.ts

@@ -0,0 +1,9 @@
+import type { RowData, SvGrid, TableFeatures } from './core';
+/**
+ * Fine-grained subscription to `table.store` using `useSelector` with shallow
+ * comparison. Call from `<script>` so the selector is contextually typed.
+ */
+export declare function subscribeGrid<TFeatures extends TableFeatures, TData extends RowData, TSelected>(grid: SvGrid<TData>, selector: (state: Record<string, any>) => TSelected): {
+    readonly current: TSelected;
+};
+export declare const subscribeSvGrid: typeof subscribeGrid;

package/dist/subscribe.js

@@ -0,0 +1,31 @@
+const shallowCompare = (a, b) => {
+    if (Object.is(a, b))
+        return true;
+    if (!a || !b || typeof a !== 'object' || typeof b !== 'object')
+        return false;
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((key) => Object.is(aObj[key], bObj[key]));
+};
+/**
+ * Fine-grained subscription to `table.store` using `useSelector` with shallow
+ * comparison. Call from `<script>` so the selector is contextually typed.
+ */
+export function subscribeGrid(grid, selector) {
+    let current = selector(grid.store.state);
+    grid.store.subscribe(() => {
+        const next = selector(grid.store.state);
+        if (!shallowCompare(current, next))
+            current = next;
+    });
+    return {
+        get current() {
+            return current;
+        },
+    };
+}
+export const subscribeSvGrid = subscribeGrid;

package/dist/subscribe.test.d.ts

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

package/dist/subscribe.test.js

@@ -0,0 +1,93 @@
+/**
+ * Unit tests for the grid-store subscribe helper.
+ *
+ * The function attaches a selector to grid.store and shallow-compares each
+ * emitted state, updating the returned `current` getter only when the
+ * selection actually changed.
+ */
+import { describe, expect, it } from 'vitest';
+import { subscribeGrid, subscribeSvGrid } from './subscribe';
+/**
+ * Minimal hand-rolled stand-in for `grid.store` that mimics the TanStack
+ * Store shape `subscribeGrid` reads: `state` getter + `subscribe(listener)`
+ * + `setState(updater)` that fires the listeners.
+ */
+function makeFakeStore(initial) {
+    let state = initial;
+    const listeners = new Set();
+    const store = {
+        get state() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        setState(updater) {
+            state = updater(state);
+            for (const l of listeners)
+                l();
+        },
+    };
+    return store;
+}
+describe('subscribeGrid', () => {
+    it('starts with the current selected value', () => {
+        const store = makeFakeStore({ sorting: ['name'], rowSelection: { '0': true } });
+        const grid = { store };
+        const sub = subscribeGrid(grid, (s) => s.sorting);
+        expect(sub.current).toEqual(['name']);
+    });
+    it('updates the selected value when the store fires a change', () => {
+        const store = makeFakeStore({ sorting: ['name'] });
+        const grid = { store };
+        const sub = subscribeGrid(grid, (s) => s.sorting);
+        store.setState((prev) => ({ ...prev, sorting: ['age'] }));
+        expect(sub.current).toEqual(['age']);
+    });
+    it('keeps the previous reference when shallow-compare reports equal', () => {
+        const store = makeFakeStore({ sel: { a: true } });
+        const grid = { store };
+        const sub = subscribeGrid(grid, (s) => s.sel);
+        const initial = sub.current;
+        // A new object with the same key/value content - shallow-equal to the prev.
+        store.setState(() => ({ sel: { a: true } }));
+        expect(sub.current).toBe(initial);
+    });
+    it('replaces the reference when a key value changes', () => {
+        const store = makeFakeStore({ sel: { a: true } });
+        const grid = { store };
+        const sub = subscribeGrid(grid, (s) => s.sel);
+        const initial = sub.current;
+        store.setState(() => ({ sel: { a: false } }));
+        expect(sub.current).not.toBe(initial);
+        expect(sub.current).toEqual({ a: false });
+    });
+    it('treats a different key set as a change', () => {
+        const store = makeFakeStore({ sel: { a: true } });
+        const grid = { store };
+        const sub = subscribeGrid(grid, (s) => s.sel);
+        store.setState(() => ({ sel: { a: true, b: true } }));
+        expect(sub.current).toEqual({ a: true, b: true });
+    });
+    it('treats primitive selections (numbers, strings) correctly', () => {
+        const store = makeFakeStore({ count: 1 });
+        const grid = { store };
+        const sub = subscribeGrid(grid, (s) => s.count);
+        expect(sub.current).toBe(1);
+        store.setState(() => ({ count: 1 }));
+        expect(sub.current).toBe(1);
+        store.setState(() => ({ count: 2 }));
+        expect(sub.current).toBe(2);
+    });
+    it('treats null and undefined as inequal to objects (early-return shallowCompare branch)', () => {
+        const store = makeFakeStore({ sel: { a: true } });
+        const grid = { store };
+        const sub = subscribeGrid(grid, (s) => s.sel);
+        store.setState(() => ({ sel: null }));
+        expect(sub.current).toBeNull();
+    });
+    it('exports the subscribeSvGrid alias as the same function', () => {
+        expect(subscribeSvGrid).toBe(subscribeGrid);
+    });
+});

package/dist/sv-grid-scrollbar.d.ts

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