@svgrid/grid 1.0.0

package/src/collaboration.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  createCollaboration,
+  type CollabMessage,
+  type CollabTransport,
+} from './collaboration'
+
+/** An in-memory bus so two controllers can talk in a test. */
+function makeBus() {
+  const handlers = new Set<(m: CollabMessage) => void>()
+  const transportFor = (): CollabTransport => ({
+    post: (msg) => {
+      // deliver async-ish to every subscriber except none (real channels echo
+      // to other tabs, not self; our controllers ignore their own id anyway).
+      for (const h of [...handlers]) h(msg)
+    },
+    subscribe: (h) => {
+      handlers.add(h)
+      return () => handlers.delete(h)
+    },
+  })
+  return { transportFor }
+}
+
+const userA = { id: 'a', name: 'Ada', color: '#f00' }
+const userB = { id: 'b', name: 'Bob', color: '#00f' }
+
+describe('createCollaboration', () => {
+  it('peers see each other after hello', () => {
+    const bus = makeBus()
+    const a = createCollaboration({ user: userA, transport: bus.transportFor() })
+    const b = createCollaboration({ user: userB, transport: bus.transportFor() })
+    // A is announced; B's hello reaches A; A replies presence.
+    expect(a.peers().map((p) => p.id)).toEqual(['b'])
+    expect(b.peers().map((p) => p.id)).toEqual(['a'])
+    a.dispose()
+    b.dispose()
+  })
+
+  it('setCell propagates a remote cursor', () => {
+    const bus = makeBus()
+    const onPeers = vi.fn()
+    const a = createCollaboration({ user: userA, transport: bus.transportFor(), onPeersChange: onPeers })
+    const b = createCollaboration({ user: userB, transport: bus.transportFor() })
+    b.setCell({ rowId: 'r1', columnId: 'salary' })
+    const peerB = a.peers().find((p) => p.id === 'b')
+    expect(peerB?.cell).toEqual({ rowId: 'r1', columnId: 'salary' })
+    a.dispose()
+    b.dispose()
+  })
+
+  it('sendEdit fires onRemoteEdit on the other peer only', () => {
+    const bus = makeBus()
+    const aEdits = vi.fn()
+    const bEdits = vi.fn()
+    const a = createCollaboration({ user: userA, transport: bus.transportFor(), onRemoteEdit: aEdits })
+    const b = createCollaboration({ user: userB, transport: bus.transportFor(), onRemoteEdit: bEdits })
+    a.sendEdit('r2', 'name', 'Grace')
+    expect(bEdits).toHaveBeenCalledWith(expect.objectContaining({ rowId: 'r2', columnId: 'name', value: 'Grace' }))
+    expect(aEdits).not.toHaveBeenCalled() // not echoed to self
+    a.dispose()
+    b.dispose()
+  })
+
+  it('bye removes a peer', () => {
+    const bus = makeBus()
+    const a = createCollaboration({ user: userA, transport: bus.transportFor() })
+    const b = createCollaboration({ user: userB, transport: bus.transportFor() })
+    expect(a.peers()).toHaveLength(1)
+    b.dispose()
+    expect(a.peers()).toHaveLength(0)
+    a.dispose()
+  })
+})

package/src/collaboration.ts

@@ -0,0 +1,161 @@
+/**
+ * Real-time collaboration. Presence (who else is here + where their cursor
+ * is) and live edits (a change in one client lands in every other), over a
+ * pluggable transport. The transport is the only thing tied to infrastructure
+ * - swap `broadcastChannelTransport` (same-browser tabs, zero backend) for a
+ * WebSocket / WebRTC / CRDT adapter and the controller is unchanged.
+ *
+ * This is also the natural "multiple agents on one grid" substrate: an AI
+ * agent is just another peer posting `edit` messages.
+ */
+export type CollabUser = {
+  id: string
+  name: string
+  /** A CSS color for this user's cursor / avatar. */
+  color: string
+}
+
+export type CollabCell = { rowId: string; columnId: string }
+
+export type CollabPresence = CollabUser & {
+  cell: CollabCell | null
+  /** Last time we heard from this peer (ms). Used to prune the gone. */
+  ts: number
+}
+
+export type CollabMessage =
+  | { kind: 'hello'; user: CollabUser }
+  | { kind: 'presence'; user: CollabUser; cell: CollabCell | null }
+  | { kind: 'edit'; user: CollabUser; rowId: string; columnId: string; value: unknown }
+  | { kind: 'bye'; userId: string }
+
+export type CollabTransport = {
+  post(msg: CollabMessage): void
+  subscribe(handler: (msg: CollabMessage) => void): () => void
+}
+
+export type Collaboration = {
+  /** Broadcast where this user's cursor is (or null when it leaves). */
+  setCell(cell: CollabCell | null): void
+  /** Broadcast a cell edit to every peer. */
+  sendEdit(rowId: string, columnId: string, value: unknown): void
+  /** The peers currently present (excludes self). */
+  peers(): CollabPresence[]
+  dispose(): void
+}
+
+export type CollaborationOptions = {
+  user: CollabUser
+  transport: CollabTransport
+  /** Fired (with self excluded) whenever the peer set or a cursor changes. */
+  onPeersChange?: (peers: CollabPresence[]) => void
+  /** Fired when another user edits a cell - apply it to your data. */
+  onRemoteEdit?: (edit: {
+    rowId: string
+    columnId: string
+    value: unknown
+    user: CollabUser
+  }) => void
+  /** Drop peers we haven't heard from in this many ms. Default 15000. */
+  peerTimeoutMs?: number
+}
+
+/** BroadcastChannel transport - live across tabs of the same browser, no
+ *  backend. No-ops where BroadcastChannel is unavailable (SSR / old env). */
+export function broadcastChannelTransport(name: string): CollabTransport {
+  const available = typeof BroadcastChannel !== 'undefined'
+  const channel = available ? new BroadcastChannel(name) : null
+  return {
+    post(msg) {
+      channel?.postMessage(msg)
+    },
+    subscribe(handler) {
+      if (!channel) return () => {}
+      const listener = (e: MessageEvent) => handler(e.data as CollabMessage)
+      channel.addEventListener('message', listener)
+      return () => channel.removeEventListener('message', listener)
+    },
+  }
+}
+
+export function createCollaboration(options: CollaborationOptions): Collaboration {
+  const { user, transport } = options
+  const timeout = options.peerTimeoutMs ?? 15_000
+  const peers = new Map<string, CollabPresence>()
+  let ownCell: CollabCell | null = null
+  let disposed = false
+
+  const list = () => [...peers.values()].sort((a, b) => a.name.localeCompare(b.name))
+  const notify = () => options.onPeersChange?.(list())
+
+  function upsert(u: CollabUser, cell: CollabCell | null) {
+    if (u.id === user.id) return
+    peers.set(u.id, { ...u, cell, ts: Date.now() })
+    notify()
+  }
+
+  const unsubscribe = transport.subscribe((msg) => {
+    if (disposed) return
+    switch (msg.kind) {
+      case 'hello':
+        upsert(msg.user, null)
+        // Let the newcomer know we're here (and where our cursor is).
+        transport.post({ kind: 'presence', user, cell: ownCell })
+        break
+      case 'presence':
+        upsert(msg.user, msg.cell)
+        break
+      case 'edit':
+        upsert(msg.user, { rowId: msg.rowId, columnId: msg.columnId })
+        if (msg.user.id !== user.id) {
+          options.onRemoteEdit?.({
+            rowId: msg.rowId,
+            columnId: msg.columnId,
+            value: msg.value,
+            user: msg.user,
+          })
+        }
+        break
+      case 'bye':
+        if (peers.delete(msg.userId)) notify()
+        break
+    }
+  })
+
+  // Prune peers that went silent (closed tab without a `bye`).
+  const pruneTimer =
+    typeof setInterval !== 'undefined'
+      ? setInterval(() => {
+          const now = Date.now()
+          let changed = false
+          for (const [id, p] of peers) {
+            if (now - p.ts > timeout) {
+              peers.delete(id)
+              changed = true
+            }
+          }
+          if (changed) notify()
+        }, Math.max(1000, timeout / 3))
+      : null
+
+  // Announce ourselves.
+  transport.post({ kind: 'hello', user })
+
+  return {
+    setCell(cell) {
+      ownCell = cell
+      transport.post({ kind: 'presence', user, cell })
+    },
+    sendEdit(rowId, columnId, value) {
+      transport.post({ kind: 'edit', user, rowId, columnId, value })
+    },
+    peers: list,
+    dispose() {
+      if (disposed) return
+      disposed = true
+      transport.post({ kind: 'bye', userId: user.id })
+      unsubscribe()
+      if (pruneTimer) clearInterval(pruneTimer)
+    },
+  }
+}

package/src/conditional-formatting.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+import {
+  computeColumnStat,
+  lerpColor,
+  contrastText,
+  resolveCellFormat,
+  formatsNeedingStats,
+  type ConditionalFormat,
+} 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: ConditionalFormat[] = [
+      { 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: ConditionalFormat[] = [
+      { 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: ConditionalFormat[] = [
+      { 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: ConditionalFormat[] = [
+      {
+        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: ConditionalFormat[] = [
+      { type: 'colorScale', min: '#000000', max: '#ffffff', columns: ['other'] },
+    ]
+    expect(resolveCellFormat(50, {}, 'c', fmts, stat).background).toBeUndefined()
+  })
+
+  it('later formats override earlier ones', () => {
+    const fmts: ConditionalFormat[] = [
+      { 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/src/conditional-formatting.ts

@@ -0,0 +1,239 @@
+/**
+ * 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.
+ */
+
+export type ColorScaleFormat = {
+  type: 'colorScale'
+  /** 2-stop (min/max) or 3-stop (min/mid/max) gradient. Hex colors. */
+  min: string
+  mid?: string
+  max: string
+  /** Fix the scale; otherwise derived from the column's data. */
+  minValue?: number
+  maxValue?: number
+}
+
+export type DataBarFormat = {
+  type: 'dataBar'
+  color: string
+  negativeColor?: string
+  minValue?: number
+  maxValue?: number
+  /** Show the cell's text on top of the bar. Default true. */
+  showValue?: boolean
+}
+
+export type IconSetName = 'arrows' | 'traffic' | 'triangles'
+
+export type IconSetFormat = {
+  type: 'iconSet'
+  set?: IconSetName
+  /** Ascending breakpoints. n thresholds => n+1 buckets/icons. */
+  thresholds: number[]
+  /** Hide the numeric text, show only the icon. Default false. */
+  iconOnly?: boolean
+}
+
+export type RuleFormat<TData = unknown> = {
+  type: 'rule'
+  /** Apply the styles below when this returns true. */
+  when: (ctx: { value: unknown; row: TData }) => boolean
+  background?: string
+  color?: string
+  fontWeight?: string | number
+}
+
+export type ConditionalFormatSpec<TData = unknown> =
+  | ColorScaleFormat
+  | DataBarFormat
+  | IconSetFormat
+  | RuleFormat<TData>
+
+/** A format scoped to specific columns (omit `columns` to apply to all). */
+export type ConditionalFormat<TData = unknown> = ConditionalFormatSpec<TData> & {
+  columns?: ReadonlyArray<string>
+}
+
+export type ResolvedCellFormat = {
+  background?: string
+  color?: string
+  fontWeight?: string | number
+  dataBar?: { percent: number; color: string; fromRight: boolean }
+  icon?: string
+  iconOnly?: boolean
+}
+
+export type ColumnStat = { min: number; max: number }
+
+const ICON_SETS: Record<IconSetName, string[]> = {
+  // 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: Iterable<unknown>): ColumnStat | null {
+  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: string[], thresholds: number[], n: number): string {
+  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: number): number {
+  return x < 0 ? 0 : x > 1 ? 1 : x
+}
+
+function parseHex(hex: string): [number, number, number] | null {
+  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: [number, number, number]): string {
+  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: string): string | null {
+  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: string, b: string, t: number): string {
+  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: ColorScaleFormat, t: number): string {
+  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<TData = unknown>(
+  value: unknown,
+  row: TData,
+  columnId: string,
+  formats: ReadonlyArray<ConditionalFormat<TData>>,
+  stat: ColumnStat | null,
+): ResolvedCellFormat {
+  const out: ResolvedCellFormat = {}
+  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: ReadonlyArray<ConditionalFormat<any>>,
+): boolean {
+  return formats.some((f) => f.type === 'colorScale' || f.type === 'dataBar')
+}