@svgrid/grid 1.1.0 → 1.1.1

package/dist/collaboration.coverage.test.js

@@ -0,0 +1,200 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { broadcastChannelTransport, createCollaboration, } from './collaboration';
+const userA = { id: 'a', name: 'Ada', color: '#f00' };
+const userB = { id: 'b', name: 'Bob', color: '#00f' };
+/** A controllable transport whose subscriber we can drive by hand. */
+function manualTransport() {
+    const handlers = new Set();
+    const posted = [];
+    const transport = {
+        post: (msg) => {
+            posted.push(msg);
+        },
+        subscribe: (h) => {
+            handlers.add(h);
+            return () => handlers.delete(h);
+        },
+    };
+    const deliver = (msg) => {
+        for (const h of [...handlers])
+            h(msg);
+    };
+    return { transport, posted, deliver, handlers };
+}
+describe('createCollaboration - presence / edit upserts', () => {
+    it('hello reply carries the responder own cell', () => {
+        const t = manualTransport();
+        const a = createCollaboration({ user: userA, transport: t.transport });
+        a.setCell({ rowId: 'r0', columnId: 'c0' });
+        t.posted.length = 0;
+        // a newcomer says hello -> A replies presence with its own cell.
+        t.deliver({ kind: 'hello', user: userB });
+        const reply = t.posted.find((m) => m.kind === 'presence');
+        expect(reply).toEqual({ kind: 'presence', user: userA, cell: { rowId: 'r0', columnId: 'c0' } });
+        expect(a.peers().map((p) => p.id)).toEqual(['b']);
+        a.dispose();
+    });
+    it('presence message records the peer cursor', () => {
+        const t = manualTransport();
+        const onPeersChange = vi.fn();
+        const a = createCollaboration({ user: userA, transport: t.transport, onPeersChange });
+        t.deliver({ kind: 'presence', user: userB, cell: { rowId: 'r9', columnId: 'name' } });
+        expect(a.peers()[0]?.cell).toEqual({ rowId: 'r9', columnId: 'name' });
+        expect(onPeersChange).toHaveBeenCalled();
+        a.dispose();
+    });
+    it('edit from another peer sets a cursor AND fires onRemoteEdit', () => {
+        const t = manualTransport();
+        const onRemoteEdit = vi.fn();
+        const a = createCollaboration({ user: userA, transport: t.transport, onRemoteEdit });
+        t.deliver({ kind: 'edit', user: userB, rowId: 'r1', columnId: 'age', value: 30 });
+        expect(a.peers()[0]?.cell).toEqual({ rowId: 'r1', columnId: 'age' });
+        expect(onRemoteEdit).toHaveBeenCalledWith({
+            rowId: 'r1',
+            columnId: 'age',
+            value: 30,
+            user: userB,
+        });
+        a.dispose();
+    });
+    it('ignores own id on upsert (presence/edit echoed back)', () => {
+        const t = manualTransport();
+        const onRemoteEdit = vi.fn();
+        const a = createCollaboration({ user: userA, transport: t.transport, onRemoteEdit });
+        // self-echo: should not appear as a peer and should not call onRemoteEdit
+        t.deliver({ kind: 'presence', user: userA, cell: { rowId: 'x', columnId: 'y' } });
+        t.deliver({ kind: 'edit', user: userA, rowId: 'x', columnId: 'y', value: 1 });
+        expect(a.peers()).toHaveLength(0);
+        expect(onRemoteEdit).not.toHaveBeenCalled();
+        a.dispose();
+    });
+    it('bye for an unknown peer does not notify', () => {
+        const t = manualTransport();
+        const onPeersChange = vi.fn();
+        const a = createCollaboration({ user: userA, transport: t.transport, onPeersChange });
+        onPeersChange.mockClear();
+        t.deliver({ kind: 'bye', userId: 'ghost' });
+        expect(onPeersChange).not.toHaveBeenCalled();
+        a.dispose();
+    });
+    it('setCell broadcasts a presence with the new cell', () => {
+        const t = manualTransport();
+        const a = createCollaboration({ user: userA, transport: t.transport });
+        t.posted.length = 0;
+        a.setCell(null);
+        expect(t.posted).toContainEqual({ kind: 'presence', user: userA, cell: null });
+        a.dispose();
+    });
+    it('sendEdit broadcasts an edit message', () => {
+        const t = manualTransport();
+        const a = createCollaboration({ user: userA, transport: t.transport });
+        t.posted.length = 0;
+        a.sendEdit('r5', 'col', 'v');
+        expect(t.posted).toContainEqual({
+            kind: 'edit',
+            user: userA,
+            rowId: 'r5',
+            columnId: 'col',
+            value: 'v',
+        });
+        a.dispose();
+    });
+    it('drops messages after dispose and unsubscribes', () => {
+        const t = manualTransport();
+        const onPeersChange = vi.fn();
+        const a = createCollaboration({ user: userA, transport: t.transport, onPeersChange });
+        a.dispose();
+        onPeersChange.mockClear();
+        // After dispose the handler is unsubscribed; even if delivered it no-ops.
+        t.deliver({ kind: 'hello', user: userB });
+        expect(onPeersChange).not.toHaveBeenCalled();
+        expect(a.peers()).toHaveLength(0);
+        // second dispose is a no-op
+        a.dispose();
+    });
+});
+describe('createCollaboration - prune timer', () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => vi.useRealTimers());
+    it('prunes peers gone silent past the timeout', () => {
+        const t = manualTransport();
+        const onPeersChange = vi.fn();
+        const a = createCollaboration({
+            user: userA,
+            transport: t.transport,
+            onPeersChange,
+            peerTimeoutMs: 3000,
+        });
+        t.deliver({ kind: 'presence', user: userB, cell: null });
+        expect(a.peers()).toHaveLength(1);
+        onPeersChange.mockClear();
+        // advance past the timeout; prune interval is max(1000, timeout/3) = 1000
+        vi.advanceTimersByTime(4000);
+        expect(a.peers()).toHaveLength(0);
+        expect(onPeersChange).toHaveBeenCalled();
+        a.dispose();
+    });
+    it('prune tick with no expired peers does not notify', () => {
+        const t = manualTransport();
+        const onPeersChange = vi.fn();
+        const a = createCollaboration({
+            user: userA,
+            transport: t.transport,
+            onPeersChange,
+            peerTimeoutMs: 9000,
+        });
+        t.deliver({ kind: 'presence', user: userB, cell: null });
+        onPeersChange.mockClear();
+        vi.advanceTimersByTime(3000); // one tick, peer still fresh
+        expect(onPeersChange).not.toHaveBeenCalled();
+        expect(a.peers()).toHaveLength(1);
+        a.dispose();
+    });
+    it('dispose clears the prune timer', () => {
+        const clearSpy = vi.spyOn(globalThis, 'clearInterval');
+        const t = manualTransport();
+        const a = createCollaboration({ user: userA, transport: t.transport });
+        a.dispose();
+        expect(clearSpy).toHaveBeenCalled();
+        clearSpy.mockRestore();
+    });
+});
+describe('broadcastChannelTransport', () => {
+    it('round-trips a message across two channels of the same name', async () => {
+        const tx = broadcastChannelTransport('svgrid-test-chan');
+        const rx = broadcastChannelTransport('svgrid-test-chan');
+        const received = [];
+        const off = rx.subscribe((m) => received.push(m));
+        tx.post({ kind: 'hello', user: userA });
+        // BroadcastChannel delivery is async (microtask/macrotask).
+        await new Promise((r) => setTimeout(r, 10));
+        expect(received).toContainEqual({ kind: 'hello', user: userA });
+        off();
+    });
+    it('subscribe returns a working unsubscribe', async () => {
+        const tx = broadcastChannelTransport('svgrid-unsub-chan');
+        const rx = broadcastChannelTransport('svgrid-unsub-chan');
+        const received = [];
+        const off = rx.subscribe((m) => received.push(m));
+        off();
+        tx.post({ kind: 'bye', userId: 'a' });
+        await new Promise((r) => setTimeout(r, 10));
+        expect(received).toHaveLength(0);
+    });
+    it('no-ops gracefully when BroadcastChannel is unavailable', () => {
+        const original = globalThis.BroadcastChannel;
+        // @ts-expect-error - simulate SSR / old environment
+        delete globalThis.BroadcastChannel;
+        try {
+            const tx = broadcastChannelTransport('nope');
+            const handler = vi.fn();
+            const off = tx.subscribe(handler);
+            expect(() => tx.post({ kind: 'bye', userId: 'x' })).not.toThrow();
+            expect(() => off()).not.toThrow();
+            expect(handler).not.toHaveBeenCalled();
+        }
+        finally {
+            globalThis.BroadcastChannel = original;
+        }
+    });
+});

package/dist/column-groups.d.ts

@@ -0,0 +1,19 @@
+export type ColumnGroupShow = "open" | "closed";
+export type ColumnGroupMeta = {
+    /** Group ids that render a collapse toggle. */
+    collapsibleGroupIds: Set<string>;
+    /** Group id -> whether it starts expanded (openByDefault). */
+    defaultOpen: Map<string, boolean>;
+    /** Leaf column id -> the group controlling it + its show mode. */
+    leafControl: Map<string, {
+        groupId: string;
+        show: ColumnGroupShow;
+    }>;
+};
+export declare function computeColumnGroupMeta(columns: ReadonlyArray<any>): ColumnGroupMeta;
+/**
+ * Which leaf ids are hidden right now, given the set of collapsed group ids.
+ * `'open'` leaves hide while their group is collapsed; `'closed'` leaves hide
+ * while it is expanded.
+ */
+export declare function hiddenLeavesForCollapse(meta: ColumnGroupMeta, collapsed: ReadonlySet<string>): Record<string, boolean>;

package/dist/column-groups.js

@@ -0,0 +1,62 @@
+// Collapsible column groups (AG-Grid `columnGroupShow`). A column group can
+// carry a collapse toggle: its child columns tagged `columnGroupShow: 'open'`
+// show only when the group is expanded, `'closed'` show only when collapsed,
+// and untagged children always show.
+//
+// This module derives, from the user's column tree, the pure metadata the
+// controller needs: which groups are collapsible, their default state, and each
+// controlled leaf's group + show-mode. The controller turns that into a hidden
+// map (merged into column visibility) AND feeds the same hidden set into the
+// group-header colspan/width math, so headers stay aligned with the leaves.
+// Mirror the id resolution used by the group-header derivation so group ids and
+// leaf ids line up across both.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function idOf(def, parentId, ix) {
+    return def.id ?? def.field ?? `${parentId ?? "col"}_d_${ix}`;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function computeColumnGroupMeta(columns) {
+    const collapsibleGroupIds = new Set();
+    const defaultOpen = new Map();
+    const leafControl = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    function walk(defs, parentId, controllingGroup) {
+        defs.forEach((def, ix) => {
+            const id = idOf(def, parentId, ix);
+            if (def.columns?.length) {
+                // A group is collapsible when any DIRECT child declares columnGroupShow.
+                const collapsible = def.columns.some(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                (c) => c.columnGroupShow === "open" || c.columnGroupShow === "closed");
+                if (collapsible) {
+                    collapsibleGroupIds.add(id);
+                    defaultOpen.set(id, def.openByDefault === true);
+                }
+                walk(def.columns, id, collapsible ? id : controllingGroup);
+            }
+            else {
+                const show = def.columnGroupShow;
+                if ((show === "open" || show === "closed") && controllingGroup) {
+                    leafControl.set(id, { groupId: controllingGroup, show });
+                }
+            }
+        });
+    }
+    walk(columns, undefined, undefined);
+    return { collapsibleGroupIds, defaultOpen, leafControl };
+}
+/**
+ * Which leaf ids are hidden right now, given the set of collapsed group ids.
+ * `'open'` leaves hide while their group is collapsed; `'closed'` leaves hide
+ * while it is expanded.
+ */
+export function hiddenLeavesForCollapse(meta, collapsed) {
+    const hidden = {};
+    for (const [leafId, ctrl] of meta.leafControl) {
+        const isCollapsed = collapsed.has(ctrl.groupId);
+        const hide = ctrl.show === "open" ? isCollapsed : !isCollapsed;
+        if (hide)
+            hidden[leafId] = true;
+    }
+    return hidden;
+}

package/dist/column-groups.test.d.ts

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

package/dist/column-groups.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { computeColumnGroupMeta, hiddenLeavesForCollapse } from './column-groups';
+// A group "Q1" with an always-on Total plus Jan/Feb that only show when open.
+const columns = [
+    { field: 'name' },
+    {
+        id: 'q1',
+        header: 'Q1',
+        columns: [
+            { field: 'q1Total' },
+            { field: 'jan', columnGroupShow: 'open' },
+            { field: 'feb', columnGroupShow: 'open' },
+        ],
+    },
+    {
+        id: 'q2',
+        header: 'Q2',
+        openByDefault: true,
+        columns: [
+            { field: 'q2Total', columnGroupShow: 'closed' },
+            { field: 'apr', columnGroupShow: 'open' },
+        ],
+    },
+];
+describe('computeColumnGroupMeta', () => {
+    it('marks groups with columnGroupShow children as collapsible', () => {
+        const meta = computeColumnGroupMeta(columns);
+        expect([...meta.collapsibleGroupIds].sort()).toEqual(['q1', 'q2']);
+        expect(meta.defaultOpen.get('q1')).toBe(false);
+        expect(meta.defaultOpen.get('q2')).toBe(true);
+    });
+    it('maps controlled leaves to their group + show mode', () => {
+        const meta = computeColumnGroupMeta(columns);
+        expect(meta.leafControl.get('jan')).toEqual({ groupId: 'q1', show: 'open' });
+        expect(meta.leafControl.get('q2Total')).toEqual({ groupId: 'q2', show: 'closed' });
+        // untagged always-on column is not controlled
+        expect(meta.leafControl.has('q1Total')).toBe(false);
+        expect(meta.leafControl.has('name')).toBe(false);
+    });
+});
+describe('hiddenLeavesForCollapse', () => {
+    const meta = computeColumnGroupMeta(columns);
+    it('hides open-columns while collapsed, shows them while expanded', () => {
+        const collapsed = new Set(['q1']);
+        const hidden = hiddenLeavesForCollapse(meta, collapsed);
+        expect(hidden.jan).toBe(true);
+        expect(hidden.feb).toBe(true);
+        expect(hidden.q1Total).toBeUndefined(); // always on
+    });
+    it('hides closed-columns while expanded', () => {
+        const collapsed = new Set(); // q2 expanded
+        const hidden = hiddenLeavesForCollapse(meta, collapsed);
+        expect(hidden.q2Total).toBe(true); // 'closed' hides when expanded
+        expect(hidden.apr).toBeUndefined(); // 'open' shows when expanded
+    });
+});

package/dist/column-types.d.ts

@@ -0,0 +1,10 @@
+export type CellDataType = "text" | "number" | "boolean" | "date" | "dateString";
+/** Best-effort inference of a column's data type from a sample value. */
+export declare function inferCellDataType(value: unknown): CellDataType | undefined;
+/**
+ * Resolve `cellDataType` (explicit or, when `infer` is on, inferred from
+ * `sampleRow`) into concrete `editorType` / `format` defaults. Explicit fields
+ * on the ColumnDef are preserved. Columns that resolve to no type are returned
+ * untouched. Nested column groups are resolved recursively.
+ */
+export declare function resolveColumnTypes(columns: ReadonlyArray<any>, sampleRow: unknown, infer: boolean): any[];

package/dist/column-types.js

@@ -0,0 +1,63 @@
+function defaultsFor(dt) {
+    switch (dt) {
+        case "number":
+            return { editorType: "number" };
+        case "boolean":
+            return { editorType: "checkbox" };
+        case "date":
+            return { editorType: "date", format: { type: "date" } };
+        case "dateString":
+            // ISO date strings ('2026-06-27') - date editor, but no Date coercion.
+            return { editorType: "date" };
+        case "text":
+        default:
+            return { editorType: "text" };
+    }
+}
+/** Best-effort inference of a column's data type from a sample value. */
+export function inferCellDataType(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "number" && Number.isFinite(value))
+        return "number";
+    if (typeof value === "boolean")
+        return "boolean";
+    if (value instanceof Date)
+        return "date";
+    if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}([T\s]|$)/.test(value)) {
+        return "dateString";
+    }
+    return "text";
+}
+/**
+ * Resolve `cellDataType` (explicit or, when `infer` is on, inferred from
+ * `sampleRow`) into concrete `editorType` / `format` defaults. Explicit fields
+ * on the ColumnDef are preserved. Columns that resolve to no type are returned
+ * untouched. Nested column groups are resolved recursively.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function resolveColumnTypes(columns, sampleRow, infer) {
+    return columns.map((col) => {
+        // Recurse into header groups first.
+        if (col.columns && col.columns.length) {
+            return { ...col, columns: resolveColumnTypes(col.columns, sampleRow, infer) };
+        }
+        // An explicit editorType means the author already chose - don't override.
+        const hasExplicitEditor = col.editorType != null;
+        let dt = col.cellDataType;
+        if (!dt && infer && !hasExplicitEditor && sampleRow != null) {
+            const field = col.field;
+            const raw = col.accessorFn?.(sampleRow) ??
+                (typeof field === "string" ? sampleRow[field] : undefined);
+            dt = inferCellDataType(raw);
+        }
+        if (!dt)
+            return col;
+        const d = defaultsFor(dt);
+        return {
+            ...col,
+            editorType: col.editorType ?? d.editorType,
+            format: col.format ?? d.format,
+        };
+    });
+}

package/dist/column-types.test.d.ts

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

package/dist/column-types.test.js

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import { inferCellDataType, resolveColumnTypes } from './column-types';
+describe('inferCellDataType', () => {
+    it('classifies primitives', () => {
+        expect(inferCellDataType(42)).toBe('number');
+        expect(inferCellDataType(true)).toBe('boolean');
+        expect(inferCellDataType(new Date())).toBe('date');
+        expect(inferCellDataType('2026-06-27')).toBe('dateString');
+        expect(inferCellDataType('2026-06-27T10:00:00Z')).toBe('dateString');
+        expect(inferCellDataType('hello')).toBe('text');
+    });
+    it('returns undefined for null/undefined so nothing is forced', () => {
+        expect(inferCellDataType(null)).toBeUndefined();
+        expect(inferCellDataType(undefined)).toBeUndefined();
+    });
+});
+describe('resolveColumnTypes', () => {
+    it('maps explicit cellDataType to editorType + format', () => {
+        const cols = [
+            { field: 'name', cellDataType: 'text' },
+            { field: 'age', cellDataType: 'number' },
+            { field: 'active', cellDataType: 'boolean' },
+            { field: 'joined', cellDataType: 'date' },
+            { field: 'iso', cellDataType: 'dateString' },
+        ];
+        const out = resolveColumnTypes(cols, undefined, false);
+        expect(out[0].editorType).toBe('text');
+        expect(out[1].editorType).toBe('number');
+        expect(out[2].editorType).toBe('checkbox');
+        expect(out[3].editorType).toBe('date');
+        expect(out[3].format).toEqual({ type: 'date' });
+        expect(out[4].editorType).toBe('date');
+        expect(out[4].format).toBeUndefined();
+    });
+    it('never overrides an explicit editorType or format', () => {
+        const cols = [{ field: 'age', cellDataType: 'number', editorType: 'text', format: { type: 'currency' } }];
+        const out = resolveColumnTypes(cols, undefined, false);
+        expect(out[0].editorType).toBe('text');
+        expect(out[0].format).toEqual({ type: 'currency' });
+    });
+    it('infers from a sample row only when infer=true and nothing is declared', () => {
+        const cols = [
+            { field: 'age' },
+            { field: 'name' },
+            { field: 'when' },
+            { field: 'flag' },
+        ];
+        const sample = { age: 30, name: 'Ada', when: '2026-01-02', flag: false };
+        const off = resolveColumnTypes(cols, sample, false);
+        expect(off[0].editorType).toBeUndefined(); // inference off
+        const on = resolveColumnTypes(cols, sample, true);
+        expect(on[0].editorType).toBe('number');
+        expect(on[1].editorType).toBe('text');
+        expect(on[2].editorType).toBe('date');
+        expect(on[3].editorType).toBe('checkbox');
+    });
+    it('recurses into header groups', () => {
+        const cols = [{ header: 'Group', columns: [{ field: 'age', cellDataType: 'number' }] }];
+        const out = resolveColumnTypes(cols, undefined, false);
+        expect(out[0].columns[0].editorType).toBe('number');
+    });
+});

package/dist/columns.test.d.ts

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