@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/alerts/alert-engine.js

@@ -0,0 +1,196 @@
+/**
+ * The pure alert engine - no DOM, no timers. It turns rules + data snapshots
+ * into `AlertEvent`s, with true-edge de-duplication so a `dataChange` rule fires
+ * once when a row starts matching (not on every re-evaluation while it keeps
+ * matching). The reactive/observing wrapper lives in `alert-engine-attach.ts`.
+ */
+import { evaluateChange, evaluatePredicate } from '../expressions/evaluate';
+import { collectColumnRefs } from '../expressions/parse';
+const AGG_ROW_KEY = '*';
+/** Fill message-template tokens from the firing context. */
+export function renderTemplate(template, ctx) {
+    const { rule, row, columnId, value } = ctx;
+    return template
+        .replace(/\{rule\}/g, rule.name)
+        .replace(/\{severity\}/g, rule.severity)
+        .replace(/\{column\}/g, columnId ?? '')
+        .replace(/\{value\}/g, value == null ? '' : String(value))
+        .replace(/\{row\.([\w$]+)\}/g, (_m, key) => fmt(row?.[key]))
+        .replace(/\{([\w$]+)\}/g, (m, key) => (row && key in row ? fmt(row[key]) : m));
+}
+function fmt(v) {
+    return v == null ? '' : String(v);
+}
+function defaultMessage(rule) {
+    return rule.name;
+}
+export function createAlertEngine(options) {
+    let rules = options.rules;
+    const getValue = options.getValue;
+    const now = options.now ?? (() => Date.now());
+    // Edge memory: keys currently satisfying a `dataChange`/aggregate predicate.
+    const active = new Set();
+    const ctxFor = (row, rows, prev) => ({
+        row,
+        prev,
+        rows,
+        getValue,
+        locale: options.locale,
+    });
+    const val = (row, columnId) => columnId == null
+        ? undefined
+        : getValue
+            ? getValue(row, columnId)
+            : row?.[columnId];
+    // A representative column for the message `{value}`/`{column}` tokens: the
+    // rule's explicit target, else the first column its predicate references.
+    const primaryColumn = (rule) => rule.columns?.[0] ?? collectColumnRefs(rule.predicate)[0];
+    function buildEvent(rule, opts) {
+        const msgAction = rule.actions.find((a) => a.message);
+        const template = msgAction?.message ?? defaultMessage(rule);
+        const message = renderTemplate(template, {
+            rule,
+            row: opts.row,
+            columnId: opts.columnId,
+            value: opts.value,
+        });
+        return {
+            ruleId: rule.id,
+            ruleName: rule.name,
+            severity: rule.severity,
+            scope: rule.scope,
+            triggerType: rule.trigger.type,
+            rowId: opts.rowId,
+            columnId: opts.columnId,
+            value: opts.value,
+            message,
+            actions: rule.actions,
+            firedAt: now(),
+        };
+    }
+    /** Aggregate-scope: one edge event when the predicate over all rows flips true. */
+    function evaluateAggregate(rule, rows) {
+        const key = `${rule.id}::${AGG_ROW_KEY}`;
+        const first = rows[0];
+        const matches = first != null && evaluatePredicate(rule.predicate, ctxFor(first, rows));
+        if (matches && !active.has(key)) {
+            active.add(key);
+            return [buildEvent(rule, {})];
+        }
+        if (!matches)
+            active.delete(key);
+        return [];
+    }
+    /** Row/cell dataChange: edge event when a row newly satisfies the predicate. */
+    function evaluateDataChangeRow(rule, row, rows) {
+        const id = options.getRowId(row);
+        const key = `${rule.id}::${id}`;
+        const matches = evaluatePredicate(rule.predicate, ctxFor(row, rows));
+        if (matches && !active.has(key)) {
+            active.add(key);
+            const source = primaryColumn(rule);
+            // Expose the column on the event only for cell scope; still surface its
+            // value for the message tokens regardless of scope.
+            const columnId = rule.scope === 'cell' ? source : undefined;
+            return [buildEvent(rule, { row, rowId: id, columnId, value: val(row, source) })];
+        }
+        if (!matches)
+            active.delete(key);
+        return [];
+    }
+    /** relativeChange: fires whenever the change test holds for a prev->next row. */
+    function evaluateRelative(rule, row, prev, rows) {
+        if (rule.trigger.type !== 'relativeChange' || prev == null)
+            return [];
+        const changed = evaluateChange(rule.trigger.expr, ctxFor(row, rows, prev));
+        if (!changed)
+            return [];
+        // Gate on the predicate too, so "price jumped AND price > 100" is expressible.
+        if (!evaluatePredicate(rule.predicate, ctxFor(row, rows, prev)))
+            return [];
+        const columnId = rule.trigger.expr.column;
+        return [
+            buildEvent(rule, {
+                row,
+                rowId: options.getRowId(row),
+                columnId,
+                value: val(row, columnId),
+            }),
+        ];
+    }
+    function activeRules() {
+        return rules.filter((r) => r.enabled);
+    }
+    return {
+        setRules(next) {
+            rules = next;
+        },
+        getRules() {
+            return rules;
+        },
+        needsPrev() {
+            return rules.some((r) => r.enabled && r.trigger.type === 'relativeChange');
+        },
+        needsFullSet() {
+            return rules.some((r) => r.enabled && r.scope === 'aggregate');
+        },
+        reset() {
+            active.clear();
+        },
+        evaluate(rows) {
+            const events = [];
+            for (const rule of activeRules()) {
+                if (rule.scope === 'aggregate') {
+                    events.push(...evaluateAggregate(rule, rows));
+                }
+                else if (rule.trigger.type === 'dataChange' || rule.trigger.type === 'scheduled') {
+                    for (const row of rows)
+                        events.push(...evaluateDataChangeRow(rule, row, rows));
+                }
+            }
+            return events;
+        },
+        evaluateTransition(prev, next) {
+            const prevById = new Map();
+            for (const row of prev)
+                prevById.set(options.getRowId(row), row);
+            const events = [];
+            for (const rule of activeRules()) {
+                if (rule.scope === 'aggregate') {
+                    events.push(...evaluateAggregate(rule, next));
+                    continue;
+                }
+                for (const row of next) {
+                    const before = prevById.get(options.getRowId(row));
+                    if (rule.trigger.type === 'relativeChange') {
+                        events.push(...evaluateRelative(rule, row, before, next));
+                    }
+                    else if (rule.trigger.type === 'dataChange') {
+                        events.push(...evaluateDataChangeRow(rule, row, next));
+                    }
+                }
+            }
+            return events;
+        },
+        validateEdit(row, columnId, nextValue) {
+            const candidate = { ...row, [columnId]: nextValue };
+            const events = [];
+            let vetoed = false;
+            for (const rule of activeRules()) {
+                if (rule.trigger.type !== 'validation')
+                    continue;
+                if (!evaluatePredicate(rule.predicate, ctxFor(candidate)))
+                    continue;
+                events.push(buildEvent(rule, {
+                    row: candidate,
+                    rowId: options.getRowId(candidate),
+                    columnId,
+                    value: nextValue,
+                }));
+                if (rule.actions.some((a) => a.kind === 'preventEdit'))
+                    vetoed = true;
+            }
+            return { vetoed, events };
+        },
+    };
+}

package/dist/alerts/alert-formats.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Bridge fired alert events to the grid's conditional-formatting engine. A
+ * `badge` / `highlight` action becomes a `RuleFormat` whose `when` matches the
+ * row that fired, so `resolveCellFormat` paints it - the same painter the grid
+ * already uses for color scales and data bars. No new rendering path.
+ */
+import type { ConditionalFormat } from '@svgrid/grid/format';
+import type { AlertEvent, AlertRule } from './alert-types';
+export type StylingContext<TData> = {
+    getValue?: (row: TData, columnId: string) => unknown;
+    locale?: string | ReadonlyArray<string>;
+};
+/**
+ * Persistent styling: one self-contained `RuleFormat` per enabled rule that has
+ * a `badge`/`highlight` action. The format's `when` runs the rule predicate
+ * directly, so the styling stays live as data changes (rows light up while they
+ * match and clear when they stop) without any row-id bookkeeping. One format
+ * per rule keeps the array tiny regardless of row count.
+ */
+export declare function rulesToConditionalFormats<TData = Record<string, unknown>>(rules: ReadonlyArray<AlertRule>, ctx?: StylingContext<TData>): ConditionalFormat<TData>[];
+/**
+ * Turn active alert events into conditional formats. Events whose actions only
+ * toast/log/flash contribute nothing here. Matching is by row id, so the format
+ * follows the row through sort/filter rather than a fixed index.
+ */
+export declare function toConditionalFormats<TData = Record<string, unknown>>(events: ReadonlyArray<AlertEvent>, getRowId: (row: TData) => string): ConditionalFormat<TData>[];

package/dist/alerts/alert-formats.js

@@ -0,0 +1,58 @@
+import { evaluatePredicate } from '../expressions/evaluate';
+/** Which action kinds paint onto cells. */
+const STYLING_KINDS = new Set(['badge', 'highlight']);
+/**
+ * Persistent styling: one self-contained `RuleFormat` per enabled rule that has
+ * a `badge`/`highlight` action. The format's `when` runs the rule predicate
+ * directly, so the styling stays live as data changes (rows light up while they
+ * match and clear when they stop) without any row-id bookkeeping. One format
+ * per rule keeps the array tiny regardless of row count.
+ */
+export function rulesToConditionalFormats(rules, ctx = {}) {
+    const formats = [];
+    for (const rule of rules) {
+        if (!rule.enabled)
+            continue;
+        for (const action of rule.actions) {
+            if (!STYLING_KINDS.has(action.kind))
+                continue;
+            const columns = action.columns ?? rule.columns;
+            const style = action.style ?? {};
+            formats.push({
+                type: 'rule',
+                ...(columns ? { columns } : {}),
+                when: ({ row }) => evaluatePredicate(rule.predicate, { row, getValue: ctx.getValue, locale: ctx.locale }),
+                ...(style.background ? { background: style.background } : {}),
+                ...(style.color ? { color: style.color } : {}),
+            });
+        }
+    }
+    return formats;
+}
+/**
+ * Turn active alert events into conditional formats. Events whose actions only
+ * toast/log/flash contribute nothing here. Matching is by row id, so the format
+ * follows the row through sort/filter rather than a fixed index.
+ */
+export function toConditionalFormats(events, getRowId) {
+    const formats = [];
+    for (const event of events) {
+        if (event.rowId == null)
+            continue;
+        const rowId = event.rowId;
+        for (const action of event.actions) {
+            if (!STYLING_KINDS.has(action.kind))
+                continue;
+            const columns = action.columns ?? (event.columnId ? [event.columnId] : undefined);
+            const style = action.style ?? {};
+            formats.push({
+                type: 'rule',
+                ...(columns ? { columns } : {}),
+                when: ({ row }) => getRowId(row) === rowId,
+                ...(style.background ? { background: style.background } : {}),
+                ...(style.color ? { color: style.color } : {}),
+            });
+        }
+    }
+    return formats;
+}

package/dist/alerts/alert-observer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 { 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;
+};
+export declare function createAlertObserver<TData = Record<string, unknown>>(opts: AlertObserverOptions<TData>): AlertObserver<TData>;

package/dist/alerts/alert-observer.js

@@ -0,0 +1,156 @@
+import { createAlertScheduler } from './alert-scheduler';
+const clone = (r) => r && typeof r === 'object' ? { ...r } : r;
+export function createAlertObserver(opts) {
+    const { engine, getRowId, onEvents } = opts;
+    const scheduler = 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 = []; // last array seen by scan (reference diff)
+    let prevSnapById = new Map(); // cloned prev VALUES (only if needsPrev)
+    let fullById = null; // full current set (only if needsFullSet)
+    // Pending work, accumulated between scheduler runs.
+    const pushQueue = new Map();
+    let scanSource = null;
+    function snapshotAll(rows) {
+        prevSnapById = new Map();
+        for (const row of rows)
+            prevSnapById.set(getRowId(row), clone(row));
+    }
+    function rebuildFullIndex(rows) {
+        fullById = new Map();
+        for (const row of rows)
+            fullById.set(getRowId(row), row);
+    }
+    function seedNow(rows) {
+        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) {
+        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) {
+        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 = [];
+        const changedPrev = [];
+        for (let i = 0; i < rows.length; i++) {
+            if (rows[i] !== prevRows[i]) {
+                const row = rows[i];
+                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/dist/alerts/alert-scheduler.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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;
+};
+export declare function createAlertScheduler(mode?: AlertSchedulerMode): AlertScheduler;

package/dist/alerts/alert-scheduler.js

@@ -0,0 +1,54 @@
+const host = typeof globalThis !== 'undefined' ? globalThis : {};
+function raf(cb) {
+    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) {
+    if (typeof host.requestIdleCallback === 'function') {
+        const id = host.requestIdleCallback(cb);
+        return () => host.cancelIdleCallback?.(id);
+    }
+    return raf(cb);
+}
+export function createAlertScheduler(mode = 'raf') {
+    let pendingFn = null;
+    let cancelHandle = 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/dist/alerts/alert-storage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare function memoryAlertRules(initial?: AlertRule[]): AlertRulesStorage;
+/** localStorage-backed storage. Safe to construct under SSR (no-ops there). */
+export declare function localStorageAlertRules(key: string): AlertRulesStorage;
+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 declare function createAlertRules(storage?: AlertRulesStorage): AlertRulesManager;