@ricsam/formula-engine 0.0.15 → 0.0.17

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

@@ -14,8 +14,11 @@ import { DependencyManager } from "./managers/dependency-manager";
 import { StyleManager } from "./managers/style-manager";
 /**
  * Main FormulaEngine class
+ * @template TCellMetadata - Consumer-defined type for cell metadata (rich text, links, custom data, etc.)
+ * @template TSheetMetadata - Consumer-defined type for sheet metadata (text boxes, frozen panes, etc.)
+ * @template TWorkbookMetadata - Consumer-defined type for workbook metadata (themes, document properties, etc.)
  */
-export declare class FormulaEngine {
+export declare class FormulaEngine<TCellMetadata = unknown, TSheetMetadata = unknown, TWorkbookMetadata = unknown> {
     private workbookManager;
     private namedExpressionManager;
     private tableManager;
@@ -25,6 +28,7 @@ export declare class FormulaEngine {
     private dependencyManager;
     private styleManager;
     private copyManager;
+    private referenceManager;
     /**
      * Public access to the store manager for testing
      */
@@ -39,10 +43,74 @@ export declare class FormulaEngine {
     constructor();
     /**
      * Static factory method to build an empty engine
+     * @template TC - Consumer-defined cell metadata type
+     * @template TS - Consumer-defined sheet metadata type
+     * @template TW - Consumer-defined workbook metadata type
      */
-    static buildEmpty(): FormulaEngine;
+    static buildEmpty<TC = unknown, TS = unknown, TW = unknown>(): FormulaEngine<TC, TS, TW>;
     getCellEvaluationResult(cellAddress: CellAddress): SingleEvaluationResult | undefined;
     getCellValue(cellAddress: CellAddress, debug?: boolean): SerializedCellValue;
+    /**
+     * Set metadata for a cell
+     * Metadata can contain rich text, links, comments, or any consumer-defined data
+     */
+    setCellMetadata(address: CellAddress, metadata: TCellMetadata | undefined): void;
+    /**
+     * Get metadata for a cell
+     */
+    getCellMetadata(address: CellAddress): TCellMetadata | undefined;
+    /**
+     * Get all cell metadata for a sheet (serialized as Map)
+     */
+    getSheetMetadataSerialized(opts: {
+        sheetName: string;
+        workbookName: string;
+    }): Map<string, TCellMetadata>;
+    /**
+     * Set metadata for a sheet
+     * Sheet metadata can contain text boxes, frozen panes, print settings, or any consumer-defined data
+     */
+    setSheetMetadata(opts: {
+        workbookName: string;
+        sheetName: string;
+    }, metadata: TSheetMetadata): void;
+    /**
+     * Get metadata for a sheet
+     */
+    getSheetMetadata(opts: {
+        workbookName: string;
+        sheetName: string;
+    }): TSheetMetadata | undefined;
+    /**
+     * Set metadata for a workbook
+     * Workbook metadata can contain themes, document properties, settings, or any consumer-defined data
+     */
+    setWorkbookMetadata(workbookName: string, metadata: TWorkbookMetadata): void;
+    /**
+     * Get metadata for a workbook
+     */
+    getWorkbookMetadata(workbookName: string): TWorkbookMetadata | undefined;
+    /**
+     * Create a tracked reference to a range
+     * Returns a stable UUID that can be used to retrieve the address later
+     * The reference automatically updates when sheets/workbooks are renamed
+     */
+    createRef(address: RangeAddress): string;
+    /**
+     * Get the current address for a tracked reference
+     * Returns undefined if reference doesn't exist or has been invalidated
+     */
+    getRefAddress(refId: string): RangeAddress | undefined;
+    /**
+     * Delete a tracked reference
+     * Returns true if the reference was deleted, false if it didn't exist
+     */
+    deleteRef(refId: string): boolean;
+    /**
+     * Get all invalid reference IDs
+     * Useful for cleanup after sheet/workbook deletions
+     */
+    getInvalidRefs(): string[];
     evaluateFormula(
     /**
      * formula without the leading = sign
@@ -128,6 +196,14 @@ export declare class FormulaEngine {
      * Get the computed style for a specific cell
      */
     getCellStyle(cellAddress: CellAddress): CellStyle | undefined;
+    /**
+     * Get all cell styles (for testing and serialization)
+     */
+    getAllCellStyles(): DirectCellStyle[];
+    /**
+     * Get all conditional styles (for testing and serialization)
+     */
+    getAllConditionalStyles(): ConditionalStyle[];
     /**
      * Add a direct cell style rule
      */
@@ -221,24 +297,61 @@ export declare class FormulaEngine {
      * Get bounds (min/max row/col) from an array of cell addresses
      */
     private getBoundsFromCells;
+    /**
+     * Move a single cell to a new location
+     * Updates all formula references that point to the moved cell
+     *
+     * @param source - The cell to move
+     * @param target - The destination cell address
+     *
+     * @example
+     * // Move A1 to D5. If B1 contains =A1, it will be updated to =D5
+     * engine.moveCell(
+     *   { workbookName, sheetName, colIndex: 0, rowIndex: 0 },
+     *   { workbookName, sheetName, colIndex: 3, rowIndex: 4 }
+     * );
+     */
+    moveCell(source: CellAddress, target: CellAddress): void;
+    /**
+     * Move a range of cells to a new location
+     * Updates all formula references that point to the moved cells
+     *
+     * @param sourceRange - The range to move
+     * @param target - The top-left destination cell address
+     *
+     * @example
+     * // Move A1:D5 to F10. If E1 contains =SUM(A1:D5), it will be updated to =SUM(F10:I14)
+     * engine.moveRange(
+     *   {
+     *     workbookName,
+     *     sheetName,
+     *     range: {
+     *       start: { col: 0, row: 0 },
+     *       end: { col: { type: "number", value: 3 }, row: { type: "number", value: 4 } }
+     *     }
+     *   },
+     *   { workbookName, sheetName, colIndex: 5, rowIndex: 9 }
+     * );
+     */
+    moveRange(sourceRange: RangeAddress, target: CellAddress): void;
     addSheet(opts: {
         workbookName: string;
         sheetName: string;
-    }): import("./types").Sheet;
+    }): import("./types").Sheet<unknown, unknown>;
     removeSheet(opts: {
         workbookName: string;
         sheetName: string;
-    }): import("./types").Sheet;
+    }): import("./types").Sheet<unknown, unknown>;
     renameSheet(opts: {
         sheetName: string;
         newSheetName: string;
         workbookName: string;
-    }): import("./types").Sheet;
-    getSheets(workbookName: string): Map<string, import("./types").Sheet>;
+    }): import("./types").Sheet<unknown, unknown>;
+    getSheets(workbookName: string): Map<string, import("./types").Sheet<unknown, unknown>>;
     getSheet({ workbookName, sheetName, }: {
         workbookName: string;
         sheetName: string;
-    }): import("./types").Sheet | undefined;
+    }): import("./types").Sheet<unknown, unknown> | undefined;
     getSheetSerialized(opts: {
         sheetName: string;
         workbookName: string;
@@ -250,7 +363,7 @@ export declare class FormulaEngine {
         workbookName: string;
         newWorkbookName: string;
     }): void;
-    getWorkbooks(): Map<string, import("./types").Workbook>;
+    getWorkbooks(): Map<string, import("./types").Workbook<unknown, unknown, unknown>>;
     /**
      * Overrides the content of a sheet.
      * @param sheetName - The name of the sheet to set the content of
@@ -293,7 +406,7 @@ export declare class FormulaEngine {
      */
     clearSpreadsheetRange(address: RangeAddress): void;
     getState(): {
-        workbooks: Map<string, import("./types").Workbook>;
+        workbooks: Map<string, import("./types").Workbook<unknown, unknown, unknown>>;
         namedExpressions: {
             sheetExpressions: Map<string, Map<string, Map<string, NamedExpression>>>;
             workbookExpressions: Map<string, Map<string, NamedExpression>>;
@@ -302,6 +415,7 @@ export declare class FormulaEngine {
         tables: Map<string, Map<string, TableDefinition>>;
         conditionalStyles: ConditionalStyle[];
         cellStyles: DirectCellStyle[];
+        references: Map<string, import("./types").TrackedReference>;
     };
     onUpdate(listener: () => void): () => void;
     serializeEngine(): string;

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

@@ -10,14 +10,59 @@ export declare class CopyManager {
     private evaluationManager;
     private styleManager;
     constructor(workbookManager: WorkbookManager, evaluationManager: EvaluationManager, styleManager: StyleManager);
+    /**
+     * Normalize the include option to an array of parts to copy
+     */
+    private normalizeInclude;
+    /**
+     * Check if a specific part should be included in the copy operation
+     */
+    private shouldInclude;
     /**
      * Paste cells from source to target
+     * Delegates to cutCells for move operations or copyOnlyCells for copy operations
      */
-    copyCells(source: CellAddress[], target: CellAddress, options: CopyCellsOptions): void;
+    pasteCells(source: CellAddress[], target: CellAddress, options: CopyCellsOptions): void;
+    /**
+     * Cut cells: Proper snapshot flow for move operations
+     * 1. Snapshot source cells (with styles)
+     * 2. Remove source cells and punch holes in style areas
+     * 3. Update references in OTHER cells (not in moved set)
+     * 4. Update formulas in snapshot and apply to target
+     */
+    private cutCells;
+    /**
+     * Copy cells: Standard copy operation (not cut/move)
+     * Snapshot → Copy with adjustment → Copy formatting
+     */
+    private copyOnlyCells;
     /**
      * Find the top-left cell (minimum row/col indices)
      */
     private findTopLeft;
+    /**
+     * Create a snapshot of cells' content and metadata
+     * This prevents issues with overlapping ranges where source and target overlap
+     * Used for copy operations (not cut)
+     */
+    private snapshotCells;
+    /**
+     * Create a snapshot of cells with content, metadata, AND styles
+     * Used for cut operations to preserve all cell information
+     */
+    private snapshotCellsWithStyles;
+    /**
+     * Apply styles from a snapshot to a target cell
+     * Creates new style areas at the target location
+     */
+    private applyStylesFromSnapshot;
+    /**
+     * Copy content from a cell snapshot to a target cell
+     */
+    private copyCellContentFromSnapshot;
+    /**
+     * Update all formula references when cells are cut (moved)
+     */
     /**
      * Copy content from one cell to another
      */
@@ -69,7 +114,7 @@ export declare class CopyManager {
      * Expand a RangeAddress into an array of CellAddress
      * Handles finite ranges, row-bounded, and column-bounded ranges
      */
-    private expandRangeToCells;
+    expandRangeToCells(rangeAddress: RangeAddress): CellAddress[];
     /**
      * Copy cell content with explicit row/column offset for fill operations
      */

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

@@ -0,0 +1,54 @@
+/**
+ * ReferenceManager - Manages tracked references for external elements
+ *
+ * Allows consumers to create stable references to ranges that automatically
+ * update when sheets/workbooks are renamed and become invalid when deleted.
+ */
+import type { RangeAddress, TrackedReference } from "../types";
+export declare class ReferenceManager {
+    private references;
+    constructor();
+    /**
+     * Create a new tracked reference
+     * Returns UUID for the reference
+     */
+    createRef(address: RangeAddress): string;
+    /**
+     * Get the current address for a reference
+     * Returns undefined if reference doesn't exist or is invalid
+     */
+    getRefAddress(refId: string): RangeAddress | undefined;
+    /**
+     * Delete a reference
+     * Returns true if reference was deleted, false if it didn't exist
+     */
+    deleteRef(refId: string): boolean;
+    /**
+     * Get all invalid reference IDs
+     */
+    getInvalidRefs(): string[];
+    /**
+     * Update references when sheet is renamed
+     */
+    updateSheetName(workbookName: string, oldSheetName: string, newSheetName: string): void;
+    /**
+     * Update references when workbook is renamed
+     */
+    updateWorkbookName(oldWorkbookName: string, newWorkbookName: string): void;
+    /**
+     * Mark references as invalid when sheet is removed
+     */
+    invalidateSheet(workbookName: string, sheetName: string): void;
+    /**
+     * Mark references as invalid when workbook is removed
+     */
+    invalidateWorkbook(workbookName: string): void;
+    /**
+     * Get all references for serialization
+     */
+    getAllReferences(): Map<string, TrackedReference>;
+    /**
+     * Restore references from serialization
+     */
+    resetReferences(refs: Map<string, TrackedReference>): void;
+}

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

@@ -34,7 +34,7 @@ export declare class StyleManager {
     getStylesIntersectingWithRange(range: RangeAddress): DirectCellStyle[];
     /**
      * Get the style for a range if all cells in the range have the same style
-     * Returns the DirectCellStyle if the range is completely contained within a single style's area
+     * Returns the DirectCellStyle if the range is completely contained within a single style's areas
      * Returns undefined if multiple styles, partial coverage, or no styles apply
      */
     getStyleForRange(range: RangeAddress): DirectCellStyle | undefined;
@@ -100,12 +100,12 @@ export declare class StyleManager {
     clearCellStyles(range: RangeAddress): void;
     /**
      * Clear cell styles in a range using subtraction
-     * For each intersecting style, subtract the cleared range:
-     * - If style is completely contained: remove entire style
-     * - If style partially overlaps: split into remaining rectangles
-     * - If no intersection: keep unchanged
+     * For each intersecting style, subtract the cleared range from its areas:
+     * - If an area is completely contained: remove that area
+     * - If an area partially overlaps: split into remaining rectangles (hole punching)
+     * - If no intersection: keep area unchanged
      *
-     * This matches Excel's behavior where pasting replaces formatting
+     * This matches Excel's behavior where cutting/pasting creates multi-area styles
      */
     clearCellStylesInRange(range: RangeAddress): void;
 }

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

@@ -72,6 +72,8 @@ export declare class WorkbookManager {
         newSheetName: string;
     }): Sheet;
     updateAllFormulas(updateCallback: (formula: string) => string): void;
+    updateFormulasExcluding(excludeCellsSet: Set<string>, updateCallback: (formula: string) => string): void;
+    updateFormulasForWorkbook(workbookName: string, updateCallback: (formula: string) => string): void;
     getSheetSerialized({ workbookName, sheetName, }: {
         workbookName: string;
         sheetName: string;
@@ -103,6 +105,43 @@ export declare class WorkbookManager {
          */
         buildingFromScratch?: boolean;
     }): void;
+    /**
+     * Set metadata for a cell
+     */
+    setCellMetadata<TMetadata = unknown>(address: CellAddress, metadata: TMetadata | undefined): void;
+    /**
+     * Get metadata for a cell
+     */
+    getCellMetadata<TMetadata = unknown>(address: CellAddress): TMetadata | undefined;
+    /**
+     * Get all metadata for a sheet
+     */
+    getSheetMetadataSerialized<TMetadata = unknown>(opts: {
+        sheetName: string;
+        workbookName: string;
+    }): Map<string, TMetadata>;
+    /**
+     * Set metadata for a sheet
+     */
+    setSheetMetadata<TSheetMetadata = unknown>(opts: {
+        workbookName: string;
+        sheetName: string;
+    }, metadata: TSheetMetadata): void;
+    /**
+     * Get metadata for a sheet
+     */
+    getSheetMetadata<TSheetMetadata = unknown>(opts: {
+        workbookName: string;
+        sheetName: string;
+    }): TSheetMetadata | undefined;
+    /**
+     * Set metadata for a workbook
+     */
+    setWorkbookMetadata<TWorkbookMetadata = unknown>(workbookName: string, metadata: TWorkbookMetadata): void;
+    /**
+     * Get metadata for a workbook
+     */
+    getWorkbookMetadata<TWorkbookMetadata = unknown>(workbookName: string): TWorkbookMetadata | undefined;
     /**
      * Replace all content for a sheet (safely, without breaking references)
      * This method clears the existing Map and repopulates it rather than replacing the Map reference
@@ -123,7 +162,7 @@ export declare class WorkbookManager {
      */
     iterateCellsInRange(address: RangeAddress): Generator<CellAddress>;
     getCellsInRange(address: RangeAddress): CellAddress[];
-    private getCellContent;
+    getCellContent(cellAddress: CellAddress): SerializedCellValue;
     getSerializedCellValue(cellAddress: CellAddress): SerializedCellValue;
     isCellEmpty(cellAddress: CellAddress): boolean;
     isFormulaCell(cellAddress: CellAddress): boolean;

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

@@ -109,14 +109,42 @@ export declare enum FormulaError {
     ERROR = "#ERROR!",
     SPILL = "#SPILL!"
 }
-export interface Sheet {
+export interface Sheet<TCellMetadata = unknown, TSheetMetadata = unknown> {
     name: string;
     index: number;
     content: Map<string, SerializedCellValue>;
+    /**
+     * Cell metadata - arbitrary consumer-defined data per cell
+     * Examples: rich text content, links, comments, custom app data
+     * The engine stores and copies this data but doesn't interpret it
+     * Keyed by cell reference (e.g., "A1")
+     */
+    metadata: Map<string, TCellMetadata>;
+    /**
+     * Sheet-level metadata - arbitrary consumer-defined data for the entire sheet
+     * Examples: text boxes, drawings, frozen panes, print settings
+     * The engine stores and copies this data but doesn't interpret it
+     */
+    sheetMetadata: TSheetMetadata;
 }
-export interface Workbook {
+export interface Workbook<TCellMetadata = unknown, TSheetMetadata = unknown, TWorkbookMetadata = unknown> {
     name: string;
-    sheets: Map<string, Sheet>;
+    sheets: Map<string, Sheet<TCellMetadata, TSheetMetadata>>;
+    /**
+     * Workbook-level metadata - arbitrary consumer-defined data for the entire workbook
+     * Examples: themes, custom ribbons, document properties, workbook settings
+     * The engine stores and copies this data but doesn't interpret it
+     */
+    workbookMetadata: TWorkbookMetadata;
+}
+/**
+ * Tracked reference - a stable reference to a range that updates automatically
+ * when workbooks/sheets are renamed and becomes invalid when they're deleted
+ */
+export interface TrackedReference {
+    id: string;
+    address: RangeAddress;
+    isValid: boolean;
 }
 export type ValueEvaluationResult = {
     type: "value";
@@ -301,11 +329,11 @@ export interface GradientStyleCondition {
 }
 export type StyleCondition = FormulaStyleCondition | GradientStyleCondition;
 export interface ConditionalStyle {
-    area: RangeAddress;
+    areas: RangeAddress[];
     condition: StyleCondition;
 }
 export interface DirectCellStyle {
-    area: RangeAddress;
+    areas: RangeAddress[];
     style: CellStyle;
 }
 export interface CellStyle {
@@ -317,19 +345,32 @@ export interface CellStyle {
     underline?: boolean;
 }
 export interface CopyCellsOptions {
-    cut: boolean;
     /**
-     * all: Copy everything from the source to the target
-     * content: Copy only the content from the source to the target
-     * style: Copy only the style from the source to the target
+     * Whether this is a cut operation (clears source cells after copying)
+     * @default false
+     */
+    cut?: boolean;
+    /**
+     * What to include in the copy operation.
+     * - Use 'all' as shorthand for ['content', 'style', 'metadata']
+     * - Use array for fine-grained control over what to copy:
+     *   - ['content'] - copy only values/formulas
+     *   - ['style'] - copy only formatting
+     *   - ['metadata'] - copy only metadata (rich text, links, etc.)
+     *   - ['content', 'style'] - copy content and formatting
+     *   - ['content', 'metadata'] - copy content and metadata
+     *   - ['style', 'metadata'] - copy formatting and metadata
+     *   - ['content', 'style', 'metadata'] - same as 'all'
+     * @default 'all'
      */
-    target: 'all' | 'content' | 'style';
+    include?: 'all' | ('content' | 'style' | 'metadata')[];
     /**
      * The type of the content to copy
      * value: Copy the value from the source to the target,
      * e.g. if the cell has the formula =123 + 123 then the value is 246
      * formula: Copy the formula from the source to the target,
      * e.g. if the cell has the formula =123 + 123 then the formula is =123 + 123 is copied
+     * @default 'formula'
      */
-    type: "value" | "formula";
+    type?: "value" | "formula";
 }

package/package.json

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