@svgrid/grid 1.0.2 → 1.1.1

package/src/collaboration.coverage.test.ts

@@ -0,0 +1,220 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  broadcastChannelTransport,
+  createCollaboration,
+  type CollabMessage,
+  type CollabTransport,
+} 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<(m: CollabMessage) => void>()
+  const posted: CollabMessage[] = []
+  const transport: CollabTransport = {
+    post: (msg) => {
+      posted.push(msg)
+    },
+    subscribe: (h) => {
+      handlers.add(h)
+      return () => handlers.delete(h)
+    },
+  }
+  const deliver = (msg: CollabMessage) => {
+    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: CollabMessage[] = []
+    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: CollabMessage[] = []
+    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/src/column-groups.test.ts

@@ -0,0 +1,59 @@
+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<string>() // 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/src/column-groups.ts

@@ -0,0 +1,80 @@
+// 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.
+
+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 }>;
+};
+
+// 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: any, parentId: string | undefined, ix: number): string {
+  return def.id ?? def.field ?? `${parentId ?? "col"}_d_${ix}`;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function computeColumnGroupMeta(columns: ReadonlyArray<any>): ColumnGroupMeta {
+  const collapsibleGroupIds = new Set<string>();
+  const defaultOpen = new Map<string, boolean>();
+  const leafControl = new Map<string, { groupId: string; show: ColumnGroupShow }>();
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function walk(defs: ReadonlyArray<any>, parentId: string | undefined, controllingGroup: string | undefined) {
+    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: any) => 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: ColumnGroupMeta,
+  collapsed: ReadonlySet<string>,
+): Record<string, boolean> {
+  const hidden: Record<string, boolean> = {};
+  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/src/column-types.test.ts

@@ -0,0 +1,68 @@
+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/src/column-types.ts

@@ -0,0 +1,82 @@
+// cellDataType resolution. A column's `cellDataType` (or grid-level
+// `inferColumnTypes`) is a high-level shorthand that fills in `editorType`,
+// `format`, and - transitively, via `getColumnAlign` and the filter-operator
+// tables, which both key off `editorType` - alignment and filter operators.
+//
+// Anything set explicitly on the ColumnDef always wins; this only fills gaps.
+// Resolution happens once when columns are ingested, producing plain ColumnDef
+// objects, so every downstream reader (editing, filtering, formatting,
+// alignment) sees a normal column with no new code paths.
+export type CellDataType = "text" | "number" | "boolean" | "date" | "dateString";
+
+type TypeDefaults = {
+  editorType: string;
+  format?: { type: string };
+};
+
+function defaultsFor(dt: CellDataType): TypeDefaults {
+  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: unknown): CellDataType | undefined {
+  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: ReadonlyArray<any>,
+  sampleRow: unknown,
+  infer: boolean,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any[] {
+  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: CellDataType | undefined = col.cellDataType;
+    if (!dt && infer && !hasExplicitEditor && sampleRow != null) {
+      const field = col.field;
+      const raw =
+        col.accessorFn?.(sampleRow) ??
+        (typeof field === "string" ? (sampleRow as Record<string, unknown>)[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,
+    };
+  });
+}