@svgrid/enterprise 2.2.1 → 2.3.0

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

@@ -0,0 +1,54 @@
+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

@@ -0,0 +1,116 @@
+/**
+ * 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

@@ -0,0 +1,80 @@
+/**
+ * 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

@@ -0,0 +1,94 @@
+/**
+ * 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
+}

package/src/alerts.ts

@@ -0,0 +1,28 @@
+/**
+ * Alerts (Pro) - the public entry for the Alert Rules engine + expression layer.
+ *
+ * Unlike the scheduler/board *views*, alerts are an overlay the consumer mounts
+ * next to the grid (`<SvGridAlerts>`), so there is no renderer to register with
+ * the grid. `enableAlerts()` exists only to keep the Pro soft-gate consistent
+ * with the rest of Enterprise: it works without a license key but nudges once in
+ * the console when unlicensed.
+ *
+ * ```ts
+ * import { setLicenseKey, enableAlerts } from '@svgrid/enterprise'
+ * setLicenseKey('YOUR-KEY')
+ * enableAlerts()
+ * // then mount <SvGridAlerts data={rows} columns={cols} bind:formats /> and
+ * // spread `formats` into <SvGrid conditionalFormats={[...base, ...formats]} />
+ * ```
+ */
+import { isLicenseKeySet } from './license'
+import { emitUnlicensedNudge } from './watermark'
+
+let enabled = false
+
+/** Turn on the alerts feature (soft-gated). Idempotent. */
+export function enableAlerts(): void {
+  if (enabled) return
+  enabled = true
+  if (!isLicenseKeySet()) emitUnlicensedNudge()
+}