@svgrid/enterprise 2.5.2 → 2.6.0

package/src/alerts/alert-observer.ts

@@ -1,208 +0,0 @@
-/**
- * alert-observer - the observation layer that turns data movement into engine
- * passes WITHOUT ever blocking the grid's render frame, and in O(changed) rather
- * than O(all rows).
- *
- * Two ways to feed it, both funnelling through the same coalescing scheduler so
- * at most one evaluation runs per frame, post-paint:
- *
- *  - PUSH  (`pushChanged`) - the consumer already knows which rows changed (a
- *    streaming feed, a transaction, the flagship demo's own tick loop). We
- *    evaluate ONLY those rows. Cost is O(rows that changed) at any dataset size.
- *
- *  - SCAN  (`scan`) - the zero-effort fallback for a plain `data = ...` where no
- *    change signal exists. We index-diff the new array against the previous one
- *    (Svelte 5 replaces changed rows immutably, so unchanged rows keep their
- *    reference) and evaluate only the mismatches. Still O(all rows) to FIND the
- *    changes, but deferred to after paint so it never lengthens the grid's frame.
- *
- * Cloning of previous row values is gated on `engine.needsPrev()`: for a rule set
- * that is purely `dataChange`/aggregate (the common case), we keep NO prev
- * snapshots at all - the biggest GC saver on large live feeds. Full-set passes
- * (aggregate scope, or a row-count change) run on the same deferred path.
- *
- * Pure TypeScript - no Svelte, no DOM. The `<SvGridAlerts>` overlay wires an
- * instance to a scheduler and an `onEvents` sink; `attachAlertEngine` wraps it
- * for non-Svelte hosts.
- */
-import type { AlertEngine } from './alert-engine'
-import type { AlertEvent, AlertRule } from './alert-types'
-import { createAlertScheduler, type AlertScheduler, type AlertSchedulerMode } from './alert-scheduler'
-
-export type AlertObserverOptions<TData> = {
-  engine: AlertEngine<TData>
-  getRowId: (row: TData) => string
-  /** Fired events to route to side effects (toast/log/formats). Batched per run. */
-  onEvents: (events: AlertEvent[]) => void
-  /** Scheduling strategy (default `raf`), or a custom scheduler for tests. */
-  schedule?: AlertSchedulerMode | AlertScheduler
-}
-
-export type AlertObserver<TData> = {
-  /** Silent full seed - arms edges from the current set so pre-existing matches
-   *  do not fire. Call on mount and after a rule change (in push mode). */
-  seed(rows: ReadonlyArray<TData>): void
-  /** Queue changed rows for a deferred, O(changed) evaluation (push mode). */
-  pushChanged(rows: ReadonlyArray<TData>): void
-  /** Schedule a deferred index-diff scan of the latest full row set (watch mode). */
-  scan(getRows: () => ReadonlyArray<TData>): void
-  /** Swap the rule set; edge memory is reset and a fresh seed is required. */
-  setRules(rules: AlertRule[]): void
-  /** Run any pending evaluation immediately (e.g. before a snapshot/test). */
-  flush(): void
-  /** Stop: cancel pending work and release retained snapshots. */
-  detach(): void
-}
-
-const clone = <TData>(r: TData): TData =>
-  r && typeof r === 'object' ? ({ ...(r as Record<string, unknown>) } as TData) : r
-
-export function createAlertObserver<TData = Record<string, unknown>>(
-  opts: AlertObserverOptions<TData>,
-): AlertObserver<TData> {
-  const { engine, getRowId, onEvents } = opts
-  const scheduler: AlertScheduler =
-    opts.schedule && typeof opts.schedule === 'object'
-      ? opts.schedule
-      : createAlertScheduler(opts.schedule ?? 'raf')
-
-  // Carry-over between runs. Only populated when a rule actually needs it.
-  let seeded = false
-  let prevRows: ReadonlyArray<TData> = [] // last array seen by scan (reference diff)
-  let prevSnapById = new Map<string, TData>() // cloned prev VALUES (only if needsPrev)
-  let fullById: Map<string, TData> | null = null // full current set (only if needsFullSet)
-
-  // Pending work, accumulated between scheduler runs.
-  const pushQueue = new Map<string, TData>()
-  let scanSource: (() => ReadonlyArray<TData>) | null = null
-
-  function snapshotAll(rows: ReadonlyArray<TData>) {
-    prevSnapById = new Map()
-    for (const row of rows) prevSnapById.set(getRowId(row), clone(row))
-  }
-
-  function rebuildFullIndex(rows: ReadonlyArray<TData>) {
-    fullById = new Map()
-    for (const row of rows) fullById.set(getRowId(row), row)
-  }
-
-  function seedNow(rows: ReadonlyArray<TData>) {
-    engine.reset()
-    engine.evaluate(rows) // arm dataChange/aggregate edges; discard the events
-    seeded = true
-    prevRows = rows
-    if (engine.needsPrev()) snapshotAll(rows)
-    else prevSnapById = new Map()
-    if (engine.needsFullSet()) rebuildFullIndex(rows)
-    else fullById = null
-  }
-
-  function emit(events: AlertEvent[]) {
-    if (events.length) onEvents(events)
-  }
-
-  /** PUSH run: evaluate exactly the queued rows (or the full set for aggregates). */
-  function runPush() {
-    const next = [...pushQueue.values()]
-    pushQueue.clear()
-    if (next.length === 0) return
-    const needsPrev = engine.needsPrev()
-
-    if (engine.needsFullSet()) {
-      // Aggregates need every row; evaluate over the maintained full index.
-      const rows = fullById ? [...fullById.values()] : next
-      const prev = needsPrev ? [...prevSnapById.values()] : []
-      const events = engine.evaluateTransition(prev, rows)
-      if (needsPrev) snapshotAll(rows)
-      emit(events)
-      return
-    }
-
-    const prev = needsPrev ? next.map((r) => prevSnapById.get(getRowId(r)) ?? r) : []
-    if (needsPrev) for (const r of next) prevSnapById.set(getRowId(r), clone(r))
-    emit(engine.evaluateTransition(prev, next))
-  }
-
-  /** SCAN run: index-diff the latest full array and evaluate the mismatches. */
-  function runScan(rows: ReadonlyArray<TData>) {
-    if (!seeded) {
-      seedNow(rows)
-      return
-    }
-    const needsPrev = engine.needsPrev()
-    const needsFull = engine.needsFullSet() || rows.length !== prevRows.length
-
-    if (needsFull) {
-      const prev = needsPrev ? [...prevSnapById.values()] : []
-      const events = engine.evaluateTransition(prev, rows)
-      prevRows = rows
-      if (needsPrev) snapshotAll(rows)
-      if (engine.needsFullSet()) rebuildFullIndex(rows)
-      emit(events)
-      return
-    }
-
-    // Fast path: index-aligned reference diff (unchanged rows keep their ref).
-    const changedNext: TData[] = []
-    const changedPrev: TData[] = []
-    for (let i = 0; i < rows.length; i++) {
-      if (rows[i] !== prevRows[i]) {
-        const row = rows[i] as TData
-        changedNext.push(row)
-        if (needsPrev) changedPrev.push(prevSnapById.get(getRowId(row)) ?? row)
-      }
-    }
-    prevRows = rows
-    if (changedNext.length === 0) return
-    if (needsPrev) for (const r of changedNext) prevSnapById.set(getRowId(r), clone(r))
-    emit(engine.evaluateTransition(changedPrev, changedNext))
-  }
-
-  function run() {
-    // A consumer drives one mode at a time; be defensive and honour whichever
-    // has pending work (scan takes precedence as it carries the full set).
-    if (scanSource) {
-      const src = scanSource
-      scanSource = null
-      runScan(src())
-    }
-    if (pushQueue.size) runPush()
-  }
-
-  return {
-    seed(rows) {
-      // Seeding is a one-off; do it synchronously so edges are armed before the
-      // first data event, then let subsequent evaluations defer.
-      seedNow(rows)
-    },
-    pushChanged(rows) {
-      if (fullById) for (const r of rows) fullById.set(getRowId(r), r)
-      for (const r of rows) pushQueue.set(getRowId(r), r)
-      if (!seeded) seeded = true // push implies the consumer is driving; edges arm lazily
-      scheduler.schedule(run)
-    },
-    scan(getRows) {
-      scanSource = getRows
-      scheduler.schedule(run)
-    },
-    setRules(rules) {
-      engine.setRules(rules)
-      engine.reset()
-      // Force a fresh silent seed before anything fires under the new rules.
-      seeded = false
-      prevSnapById = new Map()
-      fullById = null
-      pushQueue.clear()
-    },
-    flush() {
-      scheduler.flush()
-    },
-    detach() {
-      scheduler.cancel()
-      prevSnapById = new Map()
-      fullById = null
-      pushQueue.clear()
-      scanSource = null
-    },
-  }
-}

package/src/alerts/alert-scheduler.ts

@@ -1,96 +0,0 @@
-/**
- * alert-scheduler - decouples WHEN alert evaluation runs from the reactive flush
- * that mutates the grid's data. The whole performance premise of the rewrite is
- * that alert work must never lengthen the frame that paints the grid: on a data
- * change we schedule one evaluation for AFTER paint (`requestAnimationFrame`) and
- * coalesce a burst of updates into a single run.
- *
- * Modes:
- *  - `raf`  (default) - run once on the next animation frame, post-paint.
- *  - `idle` - run when the browser is idle (`requestIdleCallback`), best for
- *             non-urgent watch scans; falls back to `raf` where unavailable.
- *  - `sync` - run immediately (deterministic tests, or hosts with no rAF).
- *
- * The scheduler is intentionally tiny and dependency-free: it holds at most one
- * pending callback (the latest wins), so repeated `schedule()` calls within a
- * frame collapse to a single run. The observer accumulates the changed-row queue
- * itself, so "latest wins" loses no work.
- */
-export type AlertSchedulerMode = 'raf' | 'idle' | 'sync'
-
-export type AlertScheduler = {
-  /** Queue `fn` to run once on the next tick (coalesced). */
-  schedule(fn: () => void): void
-  /** Run any pending callback now, synchronously. No-op if nothing is pending. */
-  flush(): void
-  /** Drop any pending callback without running it. */
-  cancel(): void
-  /** Whether a callback is currently queued. */
-  readonly pending: boolean
-}
-
-type RafHost = {
-  requestAnimationFrame?: (cb: () => void) => number
-  cancelAnimationFrame?: (handle: number) => void
-  requestIdleCallback?: (cb: () => void) => number
-  cancelIdleCallback?: (handle: number) => void
-}
-
-const host: RafHost = typeof globalThis !== 'undefined' ? (globalThis as RafHost) : {}
-
-function raf(cb: () => void): () => void {
-  if (typeof host.requestAnimationFrame === 'function') {
-    const id = host.requestAnimationFrame(cb)
-    return () => host.cancelAnimationFrame?.(id)
-  }
-  const id = setTimeout(cb, 16)
-  return () => clearTimeout(id)
-}
-
-function idle(cb: () => void): () => void {
-  if (typeof host.requestIdleCallback === 'function') {
-    const id = host.requestIdleCallback(cb)
-    return () => host.cancelIdleCallback?.(id)
-  }
-  return raf(cb)
-}
-
-export function createAlertScheduler(mode: AlertSchedulerMode = 'raf'): AlertScheduler {
-  let pendingFn: (() => void) | null = null
-  let cancelHandle: (() => void) | null = null
-
-  const request = mode === 'idle' ? idle : raf
-
-  const run = () => {
-    cancelHandle = null
-    const fn = pendingFn
-    pendingFn = null
-    fn?.()
-  }
-
-  return {
-    schedule(fn) {
-      if (mode === 'sync') {
-        fn()
-        return
-      }
-      // Latest wins - the observer keeps the accumulated queue, so replacing the
-      // callback never drops queued rows; it just avoids double-running a frame.
-      pendingFn = fn
-      if (!cancelHandle) cancelHandle = request(run)
-    },
-    flush() {
-      if (!pendingFn) return
-      cancelHandle?.()
-      run()
-    },
-    cancel() {
-      cancelHandle?.()
-      cancelHandle = null
-      pendingFn = null
-    },
-    get pending() {
-      return pendingFn != null
-    },
-  }
-}

package/src/alerts/alert-storage.test.ts

@@ -1,54 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { createAlertRules, memoryAlertRules } from './alert-storage'
-import type { AlertRule } from './alert-types'
-
-const rule = (id: string, over: Partial<AlertRule> = {}): AlertRule => ({
-  id,
-  name: `Rule ${id}`,
-  enabled: true,
-  severity: 'info',
-  scope: 'row',
-  predicate: { kind: 'const', value: true },
-  trigger: { type: 'dataChange' },
-  actions: [{ kind: 'toast' }],
-  createdAt: 0,
-  ...over,
-})
-
-describe('createAlertRules CRUD', () => {
-  it('saves, replaces, gets, removes and toggles', () => {
-    const mgr = createAlertRules(memoryAlertRules())
-    mgr.save(rule('a'))
-    mgr.save(rule('b'))
-    expect(mgr.list().map((r) => r.id)).toEqual(['a', 'b'])
-
-    // Save with an existing id replaces in place.
-    mgr.save(rule('a', { name: 'Renamed' }))
-    expect(mgr.get('a')?.name).toBe('Renamed')
-    expect(mgr.list()).toHaveLength(2)
-
-    expect(mgr.toggle('a')).toBe(false)
-    expect(mgr.get('a')?.enabled).toBe(false)
-
-    expect(mgr.rename('b', 'Bee')).toBe(true)
-    expect(mgr.get('b')?.name).toBe('Bee')
-
-    expect(mgr.remove('a')).toBe(true)
-    expect(mgr.remove('missing')).toBe(false)
-    expect(mgr.list().map((r) => r.id)).toEqual(['b'])
-  })
-})
-
-describe('export / import share', () => {
-  it('round-trips a rule set through JSON', () => {
-    const src = createAlertRules(memoryAlertRules())
-    src.save(rule('a'))
-    src.save(rule('b', { severity: 'error' }))
-    const json = src.export()
-
-    const dest = createAlertRules(memoryAlertRules())
-    const imported = dest.import(json)
-    expect(imported).toHaveLength(2)
-    expect(dest.get('b')?.severity).toBe('error')
-  })
-})

package/src/alerts/alert-storage.ts

@@ -1,116 +0,0 @@
-/**
- * Alert-rule persistence + sharing. Mirrors the grid's `named-views` storage
- * shape: a pluggable `AlertRulesStorage` (in-memory or localStorage), wrapped by
- * a small CRUD manager. `export()` / `import()` make a rule set shareable as
- * JSON, so a team lead can hand round a set of alerts.
- */
-import type { AlertRule } from './alert-types'
-
-export type AlertRulesStorage = {
-  read(): AlertRule[]
-  write(rules: AlertRule[]): void
-}
-
-/** In-memory storage (default). State lives only as long as the manager. */
-export function memoryAlertRules(initial: AlertRule[] = []): AlertRulesStorage {
-  let rules = [...initial]
-  return {
-    read: () => rules,
-    write: (next) => {
-      rules = next
-    },
-  }
-}
-
-/** localStorage-backed storage. Safe to construct under SSR (no-ops there). */
-export function localStorageAlertRules(key: string): AlertRulesStorage {
-  const available = typeof localStorage !== 'undefined'
-  return {
-    read() {
-      if (!available) return []
-      try {
-        const raw = localStorage.getItem(key)
-        const parsed = raw ? JSON.parse(raw) : []
-        return Array.isArray(parsed) ? (parsed as AlertRule[]) : []
-      } catch {
-        return []
-      }
-    },
-    write(rules) {
-      if (!available) return
-      try {
-        localStorage.setItem(key, JSON.stringify(rules))
-      } catch {
-        // quota / private-mode - persistence is best-effort
-      }
-    },
-  }
-}
-
-export type AlertRulesManager = {
-  list(): AlertRule[]
-  get(id: string): AlertRule | undefined
-  /** Insert or replace a rule (matched by id). Returns the saved rule. */
-  save(rule: AlertRule): AlertRule
-  remove(id: string): boolean
-  rename(id: string, name: string): boolean
-  /** Flip a rule's `enabled` flag. Returns the new value (or undefined). */
-  toggle(id: string): boolean | undefined
-  /** Serialise the whole rule set to shareable JSON. */
-  export(): string
-  /** Replace the rule set from JSON produced by `export()`. */
-  import(json: string): AlertRule[]
-}
-
-/** CRUD manager over a storage adapter (defaults to in-memory). */
-export function createAlertRules(
-  storage: AlertRulesStorage = memoryAlertRules(),
-): AlertRulesManager {
-  const load = () => storage.read()
-  const commit = (rules: AlertRule[]) => storage.write(rules)
-
-  return {
-    list: () => load(),
-    get: (id) => load().find((r) => r.id === id),
-    save(rule) {
-      const rules = load()
-      const i = rules.findIndex((r) => r.id === rule.id)
-      if (i >= 0) rules[i] = rule
-      else rules.push(rule)
-      commit(rules)
-      return rule
-    },
-    remove(id) {
-      const rules = load()
-      const next = rules.filter((r) => r.id !== id)
-      if (next.length === rules.length) return false
-      commit(next)
-      return true
-    },
-    rename(id, name) {
-      const rules = load()
-      const rule = rules.find((r) => r.id === id)
-      if (!rule) return false
-      rule.name = name
-      commit(rules)
-      return true
-    },
-    toggle(id) {
-      const rules = load()
-      const rule = rules.find((r) => r.id === id)
-      if (!rule) return undefined
-      rule.enabled = !rule.enabled
-      commit(rules)
-      return rule.enabled
-    },
-    export() {
-      return JSON.stringify(load(), null, 2)
-    },
-    import(json) {
-      const parsed = JSON.parse(json)
-      const rules = Array.isArray(parsed) ? (parsed as AlertRule[]) : []
-      commit(rules)
-      return rules
-    },
-  }
-}

package/src/alerts/alert-store.svelte.ts

@@ -1,80 +0,0 @@
-/**
- * alert-store - the reactive log behind the alerts badge + panel. A singleton
- * queue of fired `AlertEvent`s (newest first) with an unacknowledged count,
- * mirroring the grid's `toast-store` shape. The observer pushes events here; the
- * badge reads `activeCount`; the panel lists, acknowledges, and clears them.
- *
- * Perf: a burst of events from one evaluation is written in ONE array update via
- * `pushMany` (not one reassignment per event), and `activeCount` is a maintained
- * counter - not an O(n) reduce recomputed on every render.
- */
-import type { AlertEvent } from './alert-types'
-
-const MAX = 500
-
-function createAlertStore() {
-  let events = $state<AlertEvent[]>([])
-  let active = $state(0)
-  let seq = 0
-
-  /** Recompute the unacknowledged counter after a trim/clear/ack. */
-  function recount(list: ReadonlyArray<AlertEvent>): number {
-    let n = 0
-    for (const e of list) if (!e.acknowledged) n++
-    return n
-  }
-
-  return {
-    get events() {
-      return events
-    },
-    /** Number of unacknowledged events (what the badge shows). */
-    get activeCount() {
-      return active
-    },
-    /** Append one event (kept for API compatibility; prefer `pushMany`). */
-    push(event: AlertEvent) {
-      this.pushMany([event])
-    },
-    /** Append a batch of events in a single reactive update (newest first). */
-    pushMany(batch: ReadonlyArray<AlertEvent>) {
-      if (batch.length === 0) return
-      const tagged: AlertEvent[] = []
-      let added = 0
-      // Newest first: reverse so the last event in the batch ends up on top.
-      for (let i = batch.length - 1; i >= 0; i--) {
-        tagged.push({ ...batch[i]!, _id: ++seq } as AlertEvent & { _id: number })
-        if (!batch[i]!.acknowledged) added++
-      }
-      let next = [...tagged, ...events]
-      if (next.length > MAX) {
-        next = next.slice(0, MAX)
-        // A trim can drop unacknowledged events - recount to stay exact.
-        active = recount(next)
-      } else {
-        active += added
-      }
-      events = next
-    },
-    acknowledge(index: number) {
-      const next = events.slice()
-      const cur = next[index]
-      if (cur && !cur.acknowledged) {
-        next[index] = { ...cur, acknowledged: true }
-        active = Math.max(0, active - 1)
-        events = next
-      }
-    },
-    acknowledgeAll() {
-      events = events.map((e) => (e.acknowledged ? e : { ...e, acknowledged: true }))
-      active = 0
-    },
-    clear() {
-      events = []
-      active = 0
-    },
-  }
-}
-
-/** The shared alerts log. Read `.events` / `.activeCount` inside a component. */
-export const alertStore = createAlertStore()

package/src/alerts/alert-types.ts

@@ -1,94 +0,0 @@
-/**
- * Alert Rules engine - the model layer.
- *
- * An alert rule is a declarative "when this predicate holds (or this value
- * moves), do these things": raise a toast, paint a badge/highlight, flash the
- * cell, veto the edit, or log it. Rules are authored by end users at runtime,
- * persisted, and shareable - the AdapTable-style alerting surface, built on the
- * grid's own filter/conditional-format engines.
- *
- * Predicates and change tests come from the expression layer (`../expressions`).
- */
-import type { ChangeExpr, PredicateExpr } from '../expressions/expression-types'
-import type { Schedule } from '../scheduling'
-
-/** Maps onto the toast variants + conditional-format intent. */
-export type AlertSeverity = 'info' | 'success' | 'warning' | 'error'
-
-/** What the rule watches over. */
-export type AlertScope = 'row' | 'cell' | 'aggregate'
-
-/**
- * When a rule fires:
- * - `dataChange`   - a row newly satisfies `predicate` after an edit/update.
- * - `relativeChange` - a value moved (delta / percent / crossed a threshold).
- * - `validation`   - evaluated on edit; may veto the change (`preventEdit`).
- * - `scheduled`    - re-checked on a cron/one-off schedule (reuses the enterprise
- *                    scheduler); surfaces rows currently matching `predicate`.
- */
-export type AlertTrigger =
-  | { type: 'dataChange' }
-  | { type: 'relativeChange'; expr: ChangeExpr }
-  | { type: 'validation' }
-  | { type: 'scheduled'; schedule: Schedule }
-
-/** A thing the rule does when it fires. */
-export type AlertActionKind =
-  | 'toast'
-  | 'badge'
-  | 'cellFlash'
-  | 'highlight'
-  | 'preventEdit'
-  | 'log'
-
-/** Visual styling for `badge` / `highlight` actions. */
-export type AlertActionStyle = {
-  background?: string
-  color?: string
-  /** A short glyph/emoji shown as a badge. */
-  icon?: string
-}
-
-export type AlertAction = {
-  kind: AlertActionKind
-  /**
-   * Message template. Tokens: `{rule}`, `{severity}`, `{column}`, `{value}`,
-   * and `{field}` / `{row.field}` for any row field.
-   */
-  message?: string
-  style?: AlertActionStyle
-  /** Columns the badge/highlight/flash targets (defaults to the rule's). */
-  columns?: string[]
-}
-
-export type AlertRule = {
-  id: string
-  name: string
-  enabled: boolean
-  severity: AlertSeverity
-  scope: AlertScope
-  predicate: PredicateExpr
-  trigger: AlertTrigger
-  actions: AlertAction[]
-  /** Columns in scope for cell-level styling (badge/highlight/flash). */
-  columns?: string[]
-  createdAt: number
-}
-
-/** A single firing of a rule. */
-export type AlertEvent = {
-  ruleId: string
-  ruleName: string
-  severity: AlertSeverity
-  scope: AlertScope
-  triggerType: AlertTrigger['type']
-  /** The row that matched (absent for aggregate-scope events). */
-  rowId?: string
-  /** The column that triggered/targets the event, when applicable. */
-  columnId?: string
-  value?: unknown
-  message: string
-  actions: AlertAction[]
-  firedAt: number
-  acknowledged?: boolean
-}