@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/SvPivotDesigner.svelte.d.ts

@@ -0,0 +1,176 @@
+type PivotInputRow = Record<string, unknown>;
+/**
+   * SvPivotDesigner - Excel-style pivot table designer.
+   *
+   * Self-contained, controlled component. The consumer holds the data
+   * + the field list + the layout state; everything else (drag-and-drop,
+   * chip menus, search, presets, the inline pivot grid) is built in.
+   *
+   * Minimal wire-up (in a .svelte file):
+   *   const fields = [
+   *     { field: 'region',   label: 'Region',   kind: 'dimension' },
+   *     { field: 'quarter',  label: 'Quarter',  kind: 'dimension' },
+   *     { field: 'amount',   label: 'Revenue',  kind: 'measure', defaultAgg: 'sum' },
+   *   ]
+   *   let layout = $state(defaultLayoutFor(fields))
+   *
+   *   SvPivotDesigner {data} {fields} bind:layout
+   */
+import { type ColumnDef } from '@svgrid/grid';
+import { type PivotRow, type PivotAggregatorId } from './pivot';
+import { type PivotField, type PivotLayout, type PivotPreset } from './pivot-designer';
+declare function $$render<T extends PivotInputRow>(): {
+    props: {
+        /** Flat input rows. */
+        data: T[];
+        /** All fields the user can pick from the rail. */
+        fields: PivotField<T>[];
+        /** The current pivot layout. Bindable so the consumer can persist it. */
+        layout?: PivotLayout;
+        /** Fired when the user changes the layout (drag, drop, chip menu, …). */
+        onLayoutChange?: (layout: PivotLayout) => void;
+        /** Saved layouts surfaced in the toolbar's Presets menu. */
+        presets?: PivotPreset[];
+        /** Aggregators offered in the Values chip menu. Default: all. */
+        aggregators?: PivotAggregatorId[];
+        /** Show the toolbar above the wells. Default true. */
+        showToolbar?: boolean;
+        /** Show the left-rail field picker. Default true. */
+        showFieldList?: boolean;
+        /** Show the Filters well. Default true. */
+        showFiltersWell?: boolean;
+        /** Custom Export handler. When set, an Export button appears. */
+        onExport?: (layout: PivotLayout, rows: PivotRow[]) => void;
+        /** Height of the inner pivot grid. Default '100%'. */
+        gridHeight?: string | number;
+        /** Render the embedded grid? Set false to host it separately and
+         *  read `pivot` from the on:pivot event. Default true. */
+        embedGrid?: boolean;
+        /** Fires whenever the underlying pivot model rebuilds. */
+        onPivot?: (rows: PivotRow[], columns: ColumnDef<{
+            rowSortingFeature: {
+                key: string;
+            };
+            columnFilteringFeature: {
+                key: string;
+            };
+        }, PivotRow>[]) => void;
+        /** Allow row-level expand / collapse. When true, an expand chevron
+         *  appears in the label cell on every `group` row and clicking it
+         *  toggles which descendant rows are visible. The designer manages
+         *  the collapsed set internally. Default false. */
+        expandable?: boolean;
+        /** Transform the generated column tree right before the grid renders.
+         *  The consumer can attach custom `cell:` / `header:` / `cellClass:`
+         *  properties, change widths, etc. Receives the full tree + the
+         *  current layout (so it can branch on which measures are present). */
+        decorateColumns?: (cols: ColumnDef<{
+            rowSortingFeature: {
+                key: string;
+            };
+            columnFilteringFeature: {
+                key: string;
+            };
+        }, PivotRow>[], layout: PivotLayout) => ColumnDef<{
+            rowSortingFeature: {
+                key: string;
+            };
+            columnFilteringFeature: {
+                key: string;
+            };
+        }, PivotRow>[];
+        /** Click handler forwarded to the embedded SvGrid - typically used
+         *  to drive a drill-through side panel. */
+        onCellClick?: (ctx: {
+            columnId: string;
+            row: PivotRow;
+            value: unknown;
+        }) => void;
+        /** Offer a Table <-> Chart view toggle (same layout as a live chart). Default true. */
+        chartable?: boolean;
+        /** Which view to show first when `chartable`. Default 'table'. */
+        defaultView?: "table" | "chart";
+        /**
+         * Where the authoring UI (field picker + wells) lives relative to the
+         * grid. `'top'` (default) keeps the classic Excel layout: left rail +
+         * a horizontal row of wells above the grid. `'right'` docks everything
+         * as a single vertical tool panel on the right of the grid - the
+         * "enterprise data grid" / AG-Grid pivot-panel arrangement.
+         */
+        panelPosition?: "top" | "right";
+        /** Width of the docked panel when `panelPosition='right'`. Default 280. */
+        panelWidth?: number | string;
+        /**
+         * Enables a "Pivot Mode" toggle. When OFF the embedded grid renders the
+         * flat source rows with `flatColumns`; when ON it renders the pivot.
+         * Requires `flatColumns` to be provided. Bindable.
+         */
+        pivotMode?: boolean;
+        /** Columns for the flat (pivot-off) grid. Enables the Pivot Mode toggle. */
+        flatColumns?: ColumnDef<{
+            rowSortingFeature: {
+                key: string;
+            };
+            columnFilteringFeature: {
+                key: string;
+            };
+        }, T>[];
+        /** Fired when the Pivot Mode toggle changes. */
+        onPivotModeChange?: (on: boolean) => void;
+        /** Fit the embedded grid's columns to width. Default true. Set false to
+         *  let a wide pivot scroll horizontally (recommended with many columns). */
+        gridFitColumns?: boolean;
+        /** Enable the right-click context menu on field-list rows, well chips, and
+         *  the pivot grid (add/move/remove fields, change aggregator, expand /
+         *  collapse). Default true. */
+        contextMenu?: boolean;
+        /**
+         * Column virtualization on the embedded grid. Default true. Set FALSE for
+         * wide pivots with grouped column headers: the grouped header band isn't
+         * virtualized, so a virtualized body leaves off-window group columns
+         * looking empty until scrolled. Disabling it renders every column, so
+         * header and body always stay in sync (fine up to a few hundred columns).
+         */
+        columnVirtualization?: boolean;
+        /**
+         * Render the field picker as an AG-Grid-style **Columns** tool panel: a
+         * collapsible column-group TREE whose checkboxes toggle column VISIBILITY
+         * (with a select-all), instead of the flat "tick to add to a well" list.
+         * Fields still drag into the Rows / Columns / Values wells. The embedded
+         * flat grid (pivot off) hides deselected columns. Default false.
+         */
+        columnTree?: boolean;
+        /** Hidden column ids (field names) when `columnTree` is on. Bindable. */
+        hiddenFields?: string[];
+        /** Fired when column visibility changes (columnTree mode). */
+        onHiddenFieldsChange?: (hidden: string[]) => void;
+        /**
+         * Show a vertical Columns / Filters tab rail on the docked panel
+         * (`panelPosition='right'`). The Filters tab is an AG-Grid-style set-filter
+         * builder: "Add Filter" -> pick a column -> tick which values pass. Filters
+         * narrow the source rows (they drive `layout.filters`). Default false.
+         */
+        toolTabs?: boolean;
+    };
+    exports: {};
+    bindings: "pivotMode" | "layout" | "hiddenFields";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends PivotInputRow> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "pivotMode" | "layout" | "hiddenFields";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends PivotInputRow>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends PivotInputRow>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const SvPivotDesigner: $$IsomorphicComponent;
+type SvPivotDesigner<T extends PivotInputRow> = InstanceType<typeof SvPivotDesigner<T>>;
+export default SvPivotDesigner;

package/dist/SvRecordDetail.svelte.d.ts

@@ -0,0 +1,58 @@
+/**
+   * SvRecordDetail - a full record "detail page" over an entity's rows: a header
+   * (title + subtitle + colored status pill + a few metric tiles + a record
+   * switcher), then tabbed sections - an Overview of grouped label/value pairs plus
+   * one tab per related child collection (Activity / Related), each a timeline of
+   * the child rows that point back at this record. The universal signature view for
+   * relation-heavy entities (a customer / deal / patient / trip page), where a board
+   * or calendar does not fit.
+   *
+   * Pure presentation over plain rows + an EntitySchema (same inputs as SvBoard /
+   * SvSchemaChart), so the generated app and the designer preview render it
+   * identically. When `row` is omitted it self-drives off `rows` (defaults to the
+   * first, switchable via the header dropdown).
+   */
+import type { EntitySchema } from './schema';
+type Row = Record<string, unknown>;
+type Section = {
+    label: string;
+    fields: string[];
+};
+type Related = {
+    label: string;
+    schema: EntitySchema<any>;
+    rows?: ReadonlyArray<Row>;
+    /** The child field pointing back at this record. */
+    foreignKey: string;
+    /** The parent field the child's `foreignKey` matches (default: the id) - lets a
+     *  denormalized view relate by name / company when it has no FK ids. */
+    parentField?: string;
+    titleField: string;
+    subtitleField?: string;
+    dateField?: string;
+    statusField?: string;
+};
+type $$ComponentProps = {
+    schema: EntitySchema<any>;
+    rows?: ReadonlyArray<Row>;
+    /** The specific record to show. Omit to self-drive off `rows`. */
+    row?: Row;
+    /** Initial record to open, by id (e.g. from a URL `?id=` param). Switchable. */
+    selectedId?: string;
+    /** Show a skeleton during first load. */
+    loading?: boolean;
+    titleField: string;
+    subtitleField?: string;
+    /** Enum field rendered as a colored status pill in the header. */
+    statusField?: string;
+    /** A few (numeric) fields shown as header stat tiles. */
+    metricFields?: string[];
+    /** Overview field groups. Empty -> one auto "Details" group. */
+    sections?: Section[];
+    /** Related child collections, one tab each. */
+    related?: Related[];
+    height?: number;
+};
+declare const SvRecordDetail: import("svelte").Component<$$ComponentProps, {}, "">;
+type SvRecordDetail = ReturnType<typeof SvRecordDetail>;
+export default SvRecordDetail;

package/dist/SvSchedule.svelte.d.ts

@@ -0,0 +1,29 @@
+/**
+   * SvSchedule - a month event-calendar over an entity's rows. Each row with a
+   * `dateField` value is placed as an event chip on its day; `titleField` is the
+   * chip label and an optional enum `colorField` tints it. A real scheduling view
+   * (appointments / events / bookings / shifts) - the signature calendar that makes
+   * a Studio app read like a product, not a report.
+   *
+   * Pure presentation over plain rows + an EntitySchema (same inputs as SvBoard /
+   * SvSchemaChart), so the generated app and the designer preview match.
+   */
+import type { EntitySchema } from './schema';
+type Row = Record<string, unknown>;
+type $$ComponentProps = {
+    schema: EntitySchema<any>;
+    rows?: ReadonlyArray<Row>;
+    /** The date / datetime field that places a row on the calendar. */
+    dateField: string;
+    /** Field shown as the event chip label. */
+    titleField: string;
+    /** Optional enum field whose option color tints the chip. */
+    colorField?: string;
+    onSelect?: (id: string) => void;
+    /** Dim the grid + show a loading note during first load. */
+    loading?: boolean;
+    height?: number;
+};
+declare const SvSchedule: import("svelte").Component<$$ComponentProps, {}, "">;
+type SvSchedule = ReturnType<typeof SvSchedule>;
+export default SvSchedule;

package/dist/SvSchemaChart.svelte.d.ts

@@ -0,0 +1,61 @@
+type ChartRow = Record<string, unknown>;
+/**
+   * SvSchemaChart - a reusable chart bound to an `EntitySchema`. It picks
+   * chart-able fields from the schema (dimensions to group by, measures to
+   * reduce), renders built-in controls, and draws with `SvGridChart`.
+   *
+   * Aggregation is either client-side (pass `rows`) or server-side (pass
+   * `getAggregate`, e.g. a SQL / Supabase source's `GROUP BY`), so it scales
+   * past what a page holds. Click a category to drill (`onDrill`).
+   */
+import { type ChartType } from '@svgrid/grid';
+import { type EntitySchema } from './schema';
+import { type AggregateBucket, type AggregateReduce, type AggregateRequest } from './sources/aggregate';
+declare function $$render<TData extends ChartRow>(): {
+    props: {
+        schema: EntitySchema<TData>;
+        /** Client-side data to aggregate. Ignored when `getAggregate` is set. */
+        rows?: ReadonlyArray<TData>;
+        /** Server-side aggregation (a data source's `getAggregate`). Takes precedence. */
+        getAggregate?: (request: AggregateRequest) => Promise<AggregateBucket[]>;
+        /** Filter passed to `getAggregate`. */
+        filterModel?: import("@svgrid/grid").ServerFilterModel | undefined;
+        dimension?: string;
+        measure?: string;
+        reduce?: AggregateReduce;
+        type?: ChartType;
+        /** Show the built-in dimension / measure / type controls. Default true. */
+        controls?: boolean;
+        height?: number;
+        width?: number;
+        dataLabels?: boolean;
+        formatValue?: (v: number) => string;
+        onDrill?: (category: string, dimension: string) => void;
+        /** Bump to re-fetch server aggregates (e.g. after a mutation). */
+        refreshKey?: unknown;
+        /** Brand color. Bars / lines use it; pie slices grouped by an enum use the
+         *  enum's own option colors (matching status badges). */
+        accent?: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TData extends ChartRow> {
+    props(): ReturnType<typeof $$render<TData>>['props'];
+    events(): ReturnType<typeof $$render<TData>>['events'];
+    slots(): ReturnType<typeof $$render<TData>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData extends ChartRow>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <TData extends ChartRow>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const SvSchemaChart: $$IsomorphicComponent;
+type SvSchemaChart<TData extends ChartRow> = InstanceType<typeof SvSchemaChart<TData>>;
+export default SvSchemaChart;

package/dist/SvSchemaDashboard.svelte.d.ts

@@ -0,0 +1,46 @@
+type DashRow = Record<string, unknown>;
+import type { EntitySchema } from './schema';
+import { type DashboardSpec } from './sources/dashboard';
+import type { AggregateBucket, AggregateRequest } from './sources/aggregate';
+declare function $$render<TData extends DashRow>(): {
+    props: {
+        schema: EntitySchema<TData>;
+        /** Rows for KPI tiles (and charts when there's no `getAggregate`). */
+        rows?: ReadonlyArray<TData>;
+        /**
+         * Server-side aggregation (a data source's `getAggregate`). When set, KPI
+         * tiles AND charts are computed server-side (KPIs via a dimension-less
+         * request), so they're correct over the whole table, not just a page.
+         */
+        getAggregate?: (request: AggregateRequest) => Promise<AggregateBucket[]>;
+        /** Filter applied to every widget (KPIs + charts), same shape the grid emits. */
+        filterModel?: AggregateRequest["filterModel"];
+        /** Widget layout. Defaults to a sensible set from the schema. */
+        spec?: DashboardSpec;
+        /** Bump to re-fetch server aggregates after a mutation. */
+        refreshKey?: unknown;
+        onDrill?: (category: string, dimension: string) => void;
+        title?: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<TData extends DashRow> {
+    props(): ReturnType<typeof $$render<TData>>['props'];
+    events(): ReturnType<typeof $$render<TData>>['events'];
+    slots(): ReturnType<typeof $$render<TData>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <TData extends DashRow>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<TData>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<TData>['props']>, ReturnType<__sveltets_Render<TData>['events']>, ReturnType<__sveltets_Render<TData>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<TData>['bindings']>;
+    } & ReturnType<__sveltets_Render<TData>['exports']>;
+    <TData extends DashRow>(internal: unknown, props: ReturnType<__sveltets_Render<TData>['props']> & {}): ReturnType<__sveltets_Render<TData>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const SvSchemaDashboard: $$IsomorphicComponent;
+type SvSchemaDashboard<TData extends DashRow> = InstanceType<typeof SvSchemaDashboard<TData>>;
+export default SvSchemaDashboard;

package/dist/alerts/alert-engine-attach.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Headless glue between the pure engine and the running grid.
+ *
+ * The grid's `onCellValueChange` fires only for edits made through the grid, not
+ * for streaming feeds / server pushes / a programmatic `data = ...`. Alerts must
+ * react to all of those, so we observe changes by diffing snapshots (the same
+ * approach the grid's `attachAutoSavedView` uses for state). `applyAlertEvents`
+ * routes fired events
+ * to their side effects (toast, log) and returns the visual bits (conditional
+ * formats + cells to flash) for the caller to paint. The `<SvGridAlerts>`
+ * overlay drives this reactively via `$effect`; `attachAlertEngine` offers the
+ * same as a plain-JS interval poll for non-Svelte hosts.
+ */
+import type { ConditionalFormat } from '@svgrid/grid/format';
+import { type AlertEngine } from './alert-engine';
+import type { AlertEvent, AlertRule } from './alert-types';
+export type FlashTarget = {
+    rowId: string;
+    columnId?: string;
+};
+export type ApplyAlertOptions = {
+    /**
+     * Gate which fired events actually raise a toast. Every event is still logged
+     * (the badge/panel stay accurate) - this only suppresses the visible toast, so
+     * a busy live feed does not become a toast storm. Return `false` to skip the
+     * toast. Defaults to always-toast.
+     */
+    shouldToast?: (event: AlertEvent) => boolean;
+};
+/**
+ * Perform the side effects of a batch of fired events and return the visual
+ * output: every event is recorded in the log (so the badge/panel stay accurate),
+ * `toast` actions raise a toast (subject to `shouldToast`), and
+ * `badge`/`highlight`/`cellFlash` actions yield formats + flash targets for the
+ * caller to apply to the grid.
+ *
+ * The whole batch lands in the log in ONE reactive write (`pushMany`) so a burst
+ * of firings from a single evaluation does not thrash the store.
+ */
+export declare function applyAlertEvents<TData = Record<string, unknown>>(events: ReadonlyArray<AlertEvent>, getRowId: (row: TData) => string, options?: ApplyAlertOptions): {
+    formats: ConditionalFormat<TData>[];
+    flashes: FlashTarget[];
+};
+export type AttachAlertOptions<TData> = {
+    rules: AlertRule[];
+    getRowId: (row: TData) => string;
+    /** Read the grid's current rows. */
+    getData: () => ReadonlyArray<TData>;
+    getValue?: (row: TData, columnId: string) => unknown;
+    locale?: string | ReadonlyArray<string>;
+    /** Merge alert-driven conditional formats into the grid. */
+    applyFormats?: (formats: ConditionalFormat<TData>[]) => void;
+    /** Flash a cell (e.g. call `api.flashCells`). */
+    flashCell?: (target: FlashTarget) => void;
+    /** Poll interval in ms (`0` disables polling - drive `tick()` yourself). */
+    intervalMs?: number;
+};
+export type AlertAttachment<TData> = {
+    engine: AlertEngine<TData>;
+    /** Run one evaluation pass against the latest data. */
+    tick(): void;
+    /** Push new rules into the engine (e.g. after the user edits a rule). */
+    setRules(rules: AlertRule[]): void;
+    detach(): void;
+};
+/**
+ * Wire the engine to a data source. On the first pass it seeds edges silently
+ * from the current snapshot (so pre-existing matches do not fire); thereafter
+ * each pass fires newly-matching rows.
+ *
+ * Perf: cloning a previous snapshot is gated on `engine.needsPrev()`. For a rule
+ * set that is purely `dataChange`/aggregate (the common case) NO clone is taken -
+ * `engine.evaluate` re-checks the current rows and its edge memory (the `active`
+ * set) fires each row exactly once when it starts matching. Only `relativeChange`
+ * rules, which compare prev -> next, pay for a snapshot. This is the non-Svelte
+ * poll host; for the reactive overlay, `createAlertObserver` adds a scheduler and
+ * an O(changed) push path. Returns `detach()` to stop.
+ */
+export declare function attachAlertEngine<TData = Record<string, unknown>>(opts: AttachAlertOptions<TData>): AlertAttachment<TData>;

package/dist/alerts/alert-engine-attach.js

@@ -0,0 +1,106 @@
+import { toast } from '@svgrid/grid';
+import { alertStore } from './alert-store.svelte';
+import { toConditionalFormats } from './alert-formats';
+import { createAlertEngine } from './alert-engine';
+/**
+ * Perform the side effects of a batch of fired events and return the visual
+ * output: every event is recorded in the log (so the badge/panel stay accurate),
+ * `toast` actions raise a toast (subject to `shouldToast`), and
+ * `badge`/`highlight`/`cellFlash` actions yield formats + flash targets for the
+ * caller to apply to the grid.
+ *
+ * The whole batch lands in the log in ONE reactive write (`pushMany`) so a burst
+ * of firings from a single evaluation does not thrash the store.
+ */
+export function applyAlertEvents(events, getRowId, options = {}) {
+    if (events.length === 0)
+        return { formats: [], flashes: [] };
+    alertStore.pushMany(events);
+    const allow = options.shouldToast;
+    for (const event of events) {
+        if (event.actions.some((a) => a.kind === 'toast') && (!allow || allow(event))) {
+            toast[event.severity](event.message);
+        }
+    }
+    const flashes = [];
+    for (const event of events) {
+        if (event.rowId && event.actions.some((a) => a.kind === 'cellFlash')) {
+            flashes.push({ rowId: event.rowId, columnId: event.columnId });
+        }
+    }
+    return { formats: toConditionalFormats(events, getRowId), flashes };
+}
+/**
+ * Wire the engine to a data source. On the first pass it seeds edges silently
+ * from the current snapshot (so pre-existing matches do not fire); thereafter
+ * each pass fires newly-matching rows.
+ *
+ * Perf: cloning a previous snapshot is gated on `engine.needsPrev()`. For a rule
+ * set that is purely `dataChange`/aggregate (the common case) NO clone is taken -
+ * `engine.evaluate` re-checks the current rows and its edge memory (the `active`
+ * set) fires each row exactly once when it starts matching. Only `relativeChange`
+ * rules, which compare prev -> next, pay for a snapshot. This is the non-Svelte
+ * poll host; for the reactive overlay, `createAlertObserver` adds a scheduler and
+ * an O(changed) push path. Returns `detach()` to stop.
+ */
+export function attachAlertEngine(opts) {
+    const engine = createAlertEngine({
+        rules: opts.rules,
+        getRowId: opts.getRowId,
+        getValue: opts.getValue,
+        locale: opts.locale,
+    });
+    let prev = null;
+    let seeded = false;
+    const snapshot = (rows) => rows.map((r) => (r && typeof r === 'object' ? { ...r } : r));
+    const flush = (events) => {
+        if (events.length === 0)
+            return;
+        const { formats, flashes } = applyAlertEvents(events, opts.getRowId);
+        if (formats.length && opts.applyFormats)
+            opts.applyFormats(formats);
+        if (opts.flashCell)
+            flashes.forEach((f) => opts.flashCell?.(f));
+    };
+    const tick = () => {
+        const rows = opts.getData();
+        const needsPrev = engine.needsPrev();
+        let events;
+        if (!seeded) {
+            // Silent seed: arm edges from the current set, fire nothing.
+            engine.evaluate(rows);
+            events = [];
+            seeded = true;
+        }
+        else if (needsPrev) {
+            events = engine.evaluateTransition(prev ?? [], rows);
+        }
+        else {
+            // No rule reads prev - the edge set dedups, so no clone/diff is needed.
+            events = engine.evaluate(rows);
+        }
+        prev = needsPrev ? snapshot(rows) : null;
+        flush(events);
+    };
+    const interval = opts.intervalMs ?? 400;
+    let timer = null;
+    if (interval > 0) {
+        tick();
+        timer = setInterval(tick, interval);
+    }
+    return {
+        engine,
+        tick,
+        setRules(rules) {
+            engine.setRules(rules);
+            engine.reset();
+            prev = null;
+            seeded = false;
+        },
+        detach() {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+        },
+    };
+}

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

@@ -0,0 +1,42 @@
+import type { AlertEvent, AlertRule } from './alert-types';
+export type AlertEngineOptions<TData> = {
+    rules: AlertRule[];
+    getRowId: (row: TData) => string;
+    /** Resolve a column id to a value (defaults to `row[id]`). */
+    getValue?: (row: TData, columnId: string) => unknown;
+    locale?: string | ReadonlyArray<string>;
+    /** Clock for `firedAt` (injectable for deterministic tests). */
+    now?: () => number;
+};
+export type ValidateEditResult = {
+    vetoed: boolean;
+    events: AlertEvent[];
+};
+export type AlertEngine<TData> = {
+    setRules(rules: AlertRule[]): void;
+    getRules(): AlertRule[];
+    /** Full-snapshot pass: fires `dataChange`/`scheduled`/aggregate edges. */
+    evaluate(rows: ReadonlyArray<TData>): AlertEvent[];
+    /** Prev -> next pass: fires `relativeChange` plus `dataChange` edges. */
+    evaluateTransition(prev: ReadonlyArray<TData>, next: ReadonlyArray<TData>): AlertEvent[];
+    /** Would editing `(row, columnId) -> nextValue` trip a validation rule? */
+    validateEdit(row: TData, columnId: string, nextValue: unknown): ValidateEditResult;
+    /**
+     * True iff some enabled rule reads a row's PREVIOUS value (a `relativeChange`
+     * trigger). When false, the observer can skip cloning prev-snapshots entirely
+     * - the hot-path saver for `dataChange`/aggregate-only rule sets over big feeds.
+     */
+    needsPrev(): boolean;
+    /** True iff some enabled rule is aggregate-scope (needs the full row set). */
+    needsFullSet(): boolean;
+    /** Forget edge memory so matching rows can fire again. */
+    reset(): void;
+};
+/** Fill message-template tokens from the firing context. */
+export declare function renderTemplate(template: string, ctx: {
+    rule: AlertRule;
+    row?: Record<string, unknown>;
+    columnId?: string;
+    value?: unknown;
+}): string;
+export declare function createAlertEngine<TData = Record<string, unknown>>(options: AlertEngineOptions<TData>): AlertEngine<TData>;