@ricsam/formula-engine 0.0.4 → 0.0.6

package/dist/types/core/engine.d.ts

@@ -2,7 +2,7 @@
  * Main FormulaEngine class
  * Core API implementation for spreadsheet calculations
  */
-import { type CellAddress, type NamedExpression, type RangeAddress, type SerializedCellValue, type SingleEvaluationResult, type SpreadsheetRange, type SpreadsheetRangeEnd, type TableDefinition } from "./types";
+import { type CellAddress, type CellStyle, type ConditionalStyle, type DirectCellStyle, type NamedExpression, type RangeAddress, type SerializedCellValue, type SingleEvaluationResult, type SpreadsheetRange, type SpreadsheetRangeEnd, type TableDefinition } from "./types";
 import type { FillDirection } from "@ricsam/selection-manager";
 import { AutoFill } from "./autofill-utils";
 import { WorkbookManager } from "./managers/workbook-manager";
@@ -11,6 +11,7 @@ import { TableManager } from "./managers/table-manager";
 import { EventManager } from "./managers/event-manager";
 import { EvaluationManager } from "./managers/evaluation-manager";
 import { DependencyManager } from "./managers/dependency-manager";
+import { StyleManager } from "./managers/style-manager";
 /**
  * Main FormulaEngine class
  */
@@ -22,6 +23,7 @@ export declare class FormulaEngine {
     private evaluationManager;
     private autoFillManager;
     private dependencyManager;
+    private styleManager;
     /**
      * Public access to the store manager for testing
      */
@@ -32,6 +34,7 @@ export declare class FormulaEngine {
     _evaluationManager: EvaluationManager;
     _autoFillManager: AutoFill;
     _dependencyManager: DependencyManager;
+    _styleManager: StyleManager;
     constructor();
     /**
      * Static factory method to build an empty engine
@@ -39,6 +42,11 @@ export declare class FormulaEngine {
     static buildEmpty(): FormulaEngine;
     getCellEvaluationResult(cellAddress: CellAddress): SingleEvaluationResult | undefined;
     getCellValue(cellAddress: CellAddress, debug?: boolean): SerializedCellValue;
+    evaluateFormula(
+    /**
+     * formula without the leading = sign
+     */
+    formula: string, cellAddress: CellAddress): SerializedCellValue;
     getCellDependents(address: CellAddress | SpreadsheetRange): (SpreadsheetRange | CellAddress)[];
     getCellPrecedents(address: CellAddress | SpreadsheetRange): (SpreadsheetRange | CellAddress)[];
     addNamedExpression({ expression, expressionName, sheetName, workbookName, }: {
@@ -103,6 +111,34 @@ export declare class FormulaEngine {
     resetTables(tables: Map<string, Map<string, TableDefinition>>): void;
     getTables(workbookName: string): Map<string, TableDefinition>;
     isCellInTable(cellAddress: CellAddress): TableDefinition | undefined;
+    /**
+     * Add a conditional style rule
+     */
+    addConditionalStyle(style: ConditionalStyle): void;
+    /**
+     * Remove a conditional style rule by index
+     */
+    removeConditionalStyle(workbookName: string, index: number): boolean;
+    /**
+     * Get all conditional styles for a workbook
+     */
+    getConditionalStyles(workbookName: string): ConditionalStyle[];
+    /**
+     * Get the computed style for a specific cell
+     */
+    getCellStyle(cellAddress: CellAddress): CellStyle | undefined;
+    /**
+     * Add a direct cell style rule
+     */
+    addCellStyle(style: DirectCellStyle): void;
+    /**
+     * Remove a direct cell style rule by index
+     */
+    removeCellStyle(workbookName: string, index: number): boolean;
+    /**
+     * Get all direct cell styles for a workbook
+     */
+    getCellStyles(workbookName: string): DirectCellStyle[];
     addSheet(opts: {
         workbookName: string;
         sheetName: string;
@@ -181,6 +217,8 @@ export declare class FormulaEngine {
             globalExpressions: Map<string, NamedExpression>;
         };
         tables: Map<string, Map<string, TableDefinition>>;
+        conditionalStyles: ConditionalStyle[];
+        cellStyles: DirectCellStyle[];
     };
     onUpdate(listener: () => void): () => void;
     serializeEngine(): string;

package/dist/types/core/managers/dependency-manager.d.ts

@@ -1,5 +1,5 @@
 import { type ContextDependency } from "../../evaluator/evaluation-context";
-import { type CellAddress, type EvaluationOrder, type SpilledValue } from "../types";
+import { type CellAddress, type EvaluationOrder, type SerializedCellValue, type SpilledValue } from "../types";
 import { AstEvaluationNode } from "../../evaluator/dependency-nodes/ast-evaluation-node";
 import { CellValueNode } from "../../evaluator/dependency-nodes/cell-value-node";
 import { EmptyCellEvaluationNode } from "../../evaluator/dependency-nodes/empty-cell-evaluation-node";
@@ -7,8 +7,9 @@ import { SpillMetaNode } from "../../evaluator/dependency-nodes/spill-meta-node"
 import { RangeEvaluationNode } from "../../evaluator/range-evaluation-node";
 import type { ASTNode } from "../../parser/ast";
 import { CacheManager } from "./cache-manager";
-import type { CellNodeKeyDictionary, CellNodeType, DependencyNode } from "./dependency-node";
+import type { DependencyNode } from "./dependency-node";
 import { WorkbookManager } from "./workbook-manager";
+import { VirtualCellValueNode } from "../../evaluator/dependency-nodes/virtual-cell-value-node";
 export interface DependencyTreeNode {
     type: "cell" | "range" | "empty";
     circular?: boolean;
@@ -33,11 +34,12 @@ export declare class DependencyManager {
     private cacheManager;
     private workbookManager;
     /**
-     * The dependency graph
+     * The dependency graph AKA cellNodes
      */
-    private evaluatedNodes;
+    private cellNodes;
     private spillMetaNodes;
     private emptyCells;
+    private virtualCellValueNodes;
     /**
      * registry of spilled values
      */
@@ -69,7 +71,7 @@ export declare class DependencyManager {
     getCellValueNode(nodeKey: string): CellValueNode;
     getCellValueOrEmptyCellNode(nodeKey: string): CellValueNode | EmptyCellEvaluationNode;
     getSpillMetaOrEmptySpillMetaNode(nodeKey: string): SpillMetaNode | EmptyCellEvaluationNode;
-    lookupCellNode<T extends CellNodeType>(nodeKey: string, types: T[]): CellNodeKeyDictionary[T][];
+    getVirtualCellValueNode(cellAddress: CellAddress, cellValue: SerializedCellValue): VirtualCellValueNode;
     getRangeNode(rangeKey: string): RangeEvaluationNode;
     asts: Map<
     /**
@@ -96,7 +98,6 @@ export declare class DependencyManager {
      * only resolved ast nodes can be saved
      */
     private saveAstNode;
-    getEvaluatedNodes(): Map<string, CellValueNode>;
     /**
      * Get transitive dependencies and transitive frontier dependencies
      * This is only used by buildEvaluationOrder, so we'll optimize it there
@@ -113,7 +114,7 @@ export declare class DependencyManager {
      * 5. For each SCC, create internal evaluation order with cycle breaking
      * 6. Join the sorted SCC evaluation orders to create final evaluation order
      */
-    buildEvaluationOrder(node: CellValueNode | EmptyCellEvaluationNode): EvaluationOrder;
+    buildEvaluationOrder(node: CellValueNode | EmptyCellEvaluationNode | VirtualCellValueNode): EvaluationOrder;
     /**
      * Find strongly connected components using Tarjan's algorithm
      * @param nodes - Map of nodes to analyze

package/dist/types/core/managers/evaluation-manager.d.ts

@@ -7,6 +7,8 @@ import type { WorkbookManager } from "./workbook-manager";
 import { SpillMetaNode } from "../../evaluator/dependency-nodes/spill-meta-node";
 import { EmptyCellEvaluationNode } from "../../evaluator/dependency-nodes/empty-cell-evaluation-node";
 import type { TableManager } from "./table-manager";
+import type { DependencyNode } from "./dependency-node";
+import { VirtualCellValueNode } from "../../evaluator/dependency-nodes/virtual-cell-value-node";
 export declare class EvaluationManager {
     private workbookManager;
     private tableManager;
@@ -18,12 +20,20 @@ export declare class EvaluationManager {
     evaluationResultToSerializedValue(evaluation: SingleEvaluationResult, cellAddress: CellAddress, debug?: boolean): SerializedCellValue;
     evaluateEmptyCell(node: EmptyCellEvaluationNode): void;
     evaluateRangeNode(node: RangeEvaluationNode): void;
-    evaluateCellNode(node: CellValueNode | SpillMetaNode): void;
-    evaluateDependencyNode(dependencyKey: string): void;
+    evaluateCellNode(node: CellValueNode | SpillMetaNode | VirtualCellValueNode): void;
+    evaluateDependencyNode(dependency: DependencyNode): void;
+    /**
+     * User exposed method to evaluate a formula
+     */
+    evaluateFormula(
+    /**
+     * formula for example
+     */
+    cellValue: SerializedCellValue, cellAddress: CellAddress): SerializedCellValue;
     /**
      * Evaluates a cell by building the evaluation order and evaluating the dependencies in order
      */
-    evaluateCell(node: CellValueNode | EmptyCellEvaluationNode): void;
+    evaluateCell(node: CellValueNode | EmptyCellEvaluationNode | VirtualCellValueNode): void;
     convertScalarValueToCellValue(val: SerializedCellValue): CellValue;
     canSpill(spillCandidate: CellAddress, spillArea: SpreadsheetRange): boolean;
     getCellEvaluationResult(cellAddress: CellAddress): SingleEvaluationResult | undefined;

package/dist/types/core/managers/style-manager.d.ts

@@ -0,0 +1,92 @@
+/**
+ * StyleManager - Manages conditional styling for cells
+ */
+import type { CellAddress, CellStyle, ConditionalStyle, DirectCellStyle } from "../types";
+import type { WorkbookManager } from "./workbook-manager";
+import type { EvaluationManager } from "./evaluation-manager";
+export declare class StyleManager {
+    private workbookManager;
+    private evaluationManager;
+    private conditionalStyles;
+    private cellStyles;
+    constructor(workbookManager: WorkbookManager, evaluationManager: EvaluationManager);
+    /**
+     * Add a conditional style rule
+     */
+    addConditionalStyle(style: ConditionalStyle): void;
+    /**
+     * Remove a conditional style rule by index for a specific workbook
+     */
+    removeConditionalStyle(workbookName: string, index: number): boolean;
+    /**
+     * Get all conditional styles for a workbook
+     */
+    getConditionalStyles(workbookName: string): ConditionalStyle[];
+    /**
+     * Add a direct cell style rule
+     */
+    addCellStyle(style: DirectCellStyle): void;
+    /**
+     * Remove a direct cell style rule by index for a specific workbook
+     */
+    removeCellStyle(workbookName: string, index: number): boolean;
+    /**
+     * Get all direct cell styles for a workbook
+     */
+    getCellStyles(workbookName: string): DirectCellStyle[];
+    /**
+     * Get all conditional styles across all workbooks (for serialization)
+     */
+    getAllConditionalStyles(): ConditionalStyle[];
+    /**
+     * Get all cell styles (for serialization)
+     */
+    getAllCellStyles(): DirectCellStyle[];
+    /**
+     * Reset all styles (for deserialization)
+     */
+    resetStyles(conditionalStyles?: ConditionalStyle[], cellStyles?: DirectCellStyle[]): void;
+    /**
+     * Remove all styles for a workbook
+     */
+    removeWorkbookStyles(workbookName: string): void;
+    /**
+     * Update workbook name in all style references
+     */
+    updateWorkbookName(oldName: string, newName: string): void;
+    /**
+     * Update sheet name in style references
+     */
+    updateSheetName(workbookName: string, oldSheetName: string, newSheetName: string): void;
+    /**
+     * Remove styles that reference a deleted sheet
+     */
+    removeSheetStyles(workbookName: string, sheetName: string): void;
+    /**
+     * Get the style for a specific cell
+     * Returns the first matching style (first match wins)
+     * Checks cellStyles first, then conditionalStyles
+     */
+    getCellStyle(cellAddress: CellAddress): CellStyle | undefined;
+    /**
+     * Evaluate a formula-based style condition
+     */
+    private evaluateFormulaCondition;
+    /**
+     * Evaluate a gradient-based style condition
+     */
+    private evaluateGradientCondition;
+    /**
+     * Calculate min and max bounds for a gradient
+     */
+    private calculateGradientBounds;
+    /**
+     * Get a range reference string from a RangeAddress
+     * Follows CANONICAL_RANGES.md format:
+     * - Closed: A5:D10
+     * - Row-bounded (col-open): A5:10
+     * - Col-bounded (row-open): A5:D
+     * - Open both: A5:INFINITY
+     */
+    private getRangeReference;
+}

package/dist/types/core/types.d.ts

@@ -270,3 +270,45 @@ export type EvaluationOrder = {
     hash: string;
     sccDAG?: SCCDAG;
 };
+export interface LCHColor {
+    l: number;
+    c: number;
+    h: number;
+}
+export interface FormulaStyleCondition {
+    type: "formula";
+    formula: string;
+    color: LCHColor;
+}
+export interface GradientStyleCondition {
+    type: "gradient";
+    min: {
+        type: "lowest_value";
+        color: LCHColor;
+    } | {
+        type: "number";
+        color: LCHColor;
+        valueFormula: string;
+    };
+    max: {
+        type: "highest_value";
+        color: LCHColor;
+    } | {
+        type: "number";
+        color: LCHColor;
+        valueFormula: string;
+    };
+}
+export type StyleCondition = FormulaStyleCondition | GradientStyleCondition;
+export interface ConditionalStyle {
+    area: RangeAddress;
+    condition: StyleCondition;
+}
+export interface DirectCellStyle {
+    area: RangeAddress;
+    style: CellStyle;
+}
+export interface CellStyle {
+    backgroundColor?: string;
+    color?: string;
+}

package/dist/types/core/utils/color-utils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Color utilities for conditional styling
+ * Handles LCH color space conversions and interpolation
+ */
+import type { LCHColor } from "../types";
+/**
+ * Convert LCH color to hex string
+ * LCH uses the CIELCH color space which provides perceptually uniform colors
+ */
+export declare function lchToHex(color: LCHColor): string;
+/**
+ * Convert hex color string to LCH color
+ * @param hex Hex color string (e.g., "#FF0000" or "FF0000")
+ * @returns LCH color
+ */
+export declare function hexToLch(hex: string): LCHColor;
+/**
+ * Interpolate between two LCH colors
+ * @param color1 Starting color
+ * @param color2 Ending color
+ * @param t Interpolation factor (0-1)
+ * @returns Interpolated LCH color
+ */
+export declare function interpolateLCH(color1: LCHColor, color2: LCHColor, t: number): LCHColor;
+/**
+ * Calculate interpolation factor for a value within a range
+ * @param value Current value
+ * @param min Minimum value
+ * @param max Maximum value
+ * @returns Factor between 0 and 1
+ */
+export declare function calculateGradientFactor(value: number, min: number, max: number): number;

package/dist/types/evaluator/dependency-nodes/virtual-cell-value-node.d.ts

@@ -0,0 +1,11 @@
+import type { CellAddress, SerializedCellValue, SingleEvaluationResult } from "../../core/types";
+import { BaseEvalNode } from "./base-eval-node";
+import type { SpillMetaNode } from "./spill-meta-node";
+export declare class VirtualCellValueNode extends BaseEvalNode<SingleEvaluationResult> {
+    readonly cellAddress: CellAddress;
+    readonly cellValue: SerializedCellValue;
+    constructor(key: string, cellAddress: CellAddress, cellValue: SerializedCellValue);
+    toString(): string;
+    spillMeta: SpillMetaNode | undefined;
+    setSpillMetaNode(node: SpillMetaNode): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/formula-engine",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "module": "./dist/mjs/lib.mjs",
   "scripts": {
     "test": "bun test",