@alaarab/ogrid-angular 2.6.0 → 2.6.1

package/dist/esm/services/formula-engine.service.js

@@ -0,0 +1,223 @@
+/**
+ * FormulaEngineService  -  Angular service for integrating the formula engine with the grid.
+ *
+ * Lazily creates a FormulaEngine instance when configured with `formulas: true`.
+ * Provides an accessor bridge between grid data and formula coordinates.
+ * Uses Angular signals for reactive state.
+ *
+ * Port of React's useFormulaEngine hook.
+ */
+import { Injectable, signal, computed, DestroyRef, inject } from '@angular/core';
+import { createGridDataAccessor } from '@alaarab/ogrid-core';
+import { FormulaEngine } from '@alaarab/ogrid-core/formula';
+import * as i0 from "@angular/core";
+/**
+ * Per-component injectable service that wraps FormulaEngine from @alaarab/ogrid-core.
+ *
+ * Not providedIn: 'root'  -  provide it per component so each grid instance
+ * gets its own formula engine.
+ */
+export class FormulaEngineService {
+    constructor() {
+        this.destroyRef = inject(DestroyRef);
+        // --- Internal state ---
+        this.engine = null;
+        this.initialLoaded = false;
+        // --- Data references (updated via configure or setData) ---
+        this.items = [];
+        this.flatColumns = [];
+        // --- Signals ---
+        /** Whether formula support is currently enabled. */
+        this.enabled = signal(false, ...(ngDevMode ? [{ debugName: "enabled" }] : []));
+        /** Last recalculation result, for UI to react to formula changes. */
+        this.lastRecalcResult = signal(null, ...(ngDevMode ? [{ debugName: "lastRecalcResult" }] : []));
+        /** Number of formulas currently registered. */
+        this.formulaCount = computed(() => {
+            // Re-read lastRecalcResult to ensure reactivity when formulas change
+            this.lastRecalcResult();
+            return this.engine?.getAllFormulas().length ?? 0;
+        }, ...(ngDevMode ? [{ debugName: "formulaCount" }] : []));
+        this.destroyRef.onDestroy(() => {
+            this.engine?.clear();
+            this.engine = null;
+        });
+    }
+    /**
+     * Configure the formula engine. Call this when the grid component initializes.
+     *
+     * Lazily creates the FormulaEngine only when `formulas: true`.
+     */
+    configure(options) {
+        const { formulas, initialFormulas, formulaFunctions, onFormulaRecalc, namedRanges, sheets } = options;
+        this.onFormulaRecalcFn = onFormulaRecalc;
+        if (formulas && !this.engine) {
+            // Create engine lazily
+            this.engine = new FormulaEngine({
+                customFunctions: formulaFunctions,
+                namedRanges,
+            });
+            // Register sheet accessors
+            if (sheets) {
+                for (const [name, accessor] of Object.entries(sheets)) {
+                    this.engine.registerSheet(name, accessor);
+                }
+            }
+            this.enabled.set(true);
+        }
+        else if (!formulas && this.engine) {
+            // Tear down engine
+            this.engine.clear();
+            this.engine = null;
+            this.enabled.set(false);
+            this.lastRecalcResult.set(null);
+            this.initialLoaded = false;
+        }
+        // Load initial formulas once
+        if (formulas && this.engine && initialFormulas && !this.initialLoaded) {
+            this.initialLoaded = true;
+            const accessor = this.createAccessor();
+            const result = this.engine.loadFormulas(initialFormulas, accessor);
+            if (result.updatedCells.length > 0) {
+                this.lastRecalcResult.set(result);
+                this.onFormulaRecalcFn?.(result);
+            }
+        }
+    }
+    /**
+     * Update the data references used by the accessor bridge.
+     * Call this whenever the grid's items or columns change.
+     */
+    setData(items, flatColumns) {
+        this.items = items;
+        this.flatColumns = flatColumns;
+    }
+    /**
+     * Set or clear a formula for a cell. Triggers recalculation of dependents.
+     */
+    setFormula(col, row, formula, accessor) {
+        if (!this.engine)
+            return;
+        const acc = accessor ?? this.createAccessor();
+        const result = this.engine.setFormula(col, row, formula, acc);
+        if (result.updatedCells.length > 0) {
+            this.lastRecalcResult.set(result);
+            this.onFormulaRecalcFn?.(result);
+        }
+    }
+    /**
+     * Notify the engine that a non-formula cell's value changed.
+     * Triggers recalculation of any formulas that depend on this cell.
+     */
+    onCellChanged(col, row, accessor) {
+        if (!this.engine)
+            return;
+        const acc = accessor ?? this.createAccessor();
+        const result = this.engine.onCellChanged(col, row, acc);
+        if (result.updatedCells.length > 0) {
+            this.lastRecalcResult.set(result);
+            this.onFormulaRecalcFn?.(result);
+        }
+    }
+    /**
+     * Get the formula engine's computed value for a cell coordinate.
+     */
+    getValue(col, row) {
+        return this.engine?.getValue(col, row);
+    }
+    /**
+     * Check if a cell has a formula.
+     */
+    hasFormula(col, row) {
+        return this.engine?.hasFormula(col, row) ?? false;
+    }
+    /**
+     * Get the formula string for a cell.
+     */
+    getFormula(col, row) {
+        return this.engine?.getFormula(col, row);
+    }
+    /**
+     * Trigger a full recalculation of all formulas.
+     */
+    recalcAll(accessor) {
+        if (!this.engine)
+            return;
+        const acc = accessor ?? this.createAccessor();
+        const result = this.engine.recalcAll(acc);
+        if (result.updatedCells.length > 0) {
+            this.lastRecalcResult.set(result);
+            this.onFormulaRecalcFn?.(result);
+        }
+    }
+    /**
+     * Get all formulas for serialization.
+     */
+    getAllFormulas() {
+        return this.engine?.getAllFormulas() ?? [];
+    }
+    /**
+     * Register a custom function at runtime.
+     */
+    registerFunction(name, fn) {
+        this.engine?.registerFunction(name, fn);
+    }
+    /**
+     * Clear all formulas and cached values.
+     */
+    clear() {
+        this.engine?.clear();
+        this.lastRecalcResult.set(null);
+    }
+    /**
+     * Define a named range.
+     */
+    defineNamedRange(name, ref) {
+        this.engine?.defineNamedRange(name, ref);
+    }
+    /**
+     * Remove a named range.
+     */
+    removeNamedRange(name) {
+        this.engine?.removeNamedRange(name);
+    }
+    /**
+     * Register a sheet accessor for cross-sheet references.
+     */
+    registerSheet(name, accessor) {
+        this.engine?.registerSheet(name, accessor);
+    }
+    /**
+     * Unregister a sheet accessor.
+     */
+    unregisterSheet(name) {
+        this.engine?.unregisterSheet(name);
+    }
+    /**
+     * Get all cells that a cell depends on (deep, transitive).
+     */
+    getPrecedents(col, row) {
+        return this.engine?.getPrecedents(col, row) ?? [];
+    }
+    /**
+     * Get all cells that depend on a cell (deep, transitive).
+     */
+    getDependents(col, row) {
+        return this.engine?.getDependents(col, row) ?? [];
+    }
+    /**
+     * Get full audit trail for a cell.
+     */
+    getAuditTrail(col, row) {
+        return this.engine?.getAuditTrail(col, row) ?? null;
+    }
+    // --- Private helpers ---
+    /** Create a data accessor that bridges grid data to formula coordinates. */
+    createAccessor() {
+        return createGridDataAccessor(this.items, this.flatColumns);
+    }
+    static { this.ɵfac = function FormulaEngineService_Factory(__ngFactoryType__) { return new (__ngFactoryType__ || FormulaEngineService)(); }; }
+    static { this.ɵprov = /*@__PURE__*/ i0.ɵɵdefineInjectable({ token: FormulaEngineService, factory: FormulaEngineService.ɵfac }); }
+}
+(() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassMetadata(FormulaEngineService, [{
+        type: Injectable
+    }], () => [], null); })();