@ricsam/formula-engine 0.0.16 → 0.0.18

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

@@ -12,10 +12,21 @@ import { EventManager } from "./managers/event-manager";
 import { EvaluationManager } from "./managers/evaluation-manager";
 import { DependencyManager } from "./managers/dependency-manager";
 import { StyleManager } from "./managers/style-manager";
+import type { Api, CreateApi, Declaration } from "./api/api";
+import { type EngineAction } from "./commands";
+type Metadata = {
+    cell?: unknown;
+    sheet?: unknown;
+    workbook?: unknown;
+};
+type MetadataType<TMetadata extends Metadata, TKey extends keyof Metadata> = TMetadata[TKey];
 /**
  * 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<TMetadata extends Metadata = Metadata, TCreateApi extends CreateApi<MetadataType<TMetadata, "cell">, Api, Declaration> | undefined = undefined> {
     private workbookManager;
     private namedExpressionManager;
     private tableManager;
@@ -25,6 +36,11 @@ export declare class FormulaEngine {
     private dependencyManager;
     private styleManager;
     private copyManager;
+    private referenceManager;
+    private apiSchemaManager;
+    private commandExecutor;
+    api: TCreateApi extends CreateApi<MetadataType<TMetadata, "cell">, Api, Declaration> ? TCreateApi["api"] : undefined;
+    private apiDeclaration;
     /**
      * Public access to the store manager for testing
      */
@@ -36,13 +52,77 @@ export declare class FormulaEngine {
     _autoFillManager: AutoFill;
     _dependencyManager: DependencyManager;
     _styleManager: StyleManager;
-    constructor();
+    constructor(api?: TCreateApi);
     /**
      * 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<TMetadata extends Metadata = Metadata, TApiDeclaration extends CreateApi<MetadataType<TMetadata, "cell">, any, any> | undefined = undefined>(api?: TApiDeclaration): FormulaEngine<TMetadata, TApiDeclaration>;
     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: MetadataType<TMetadata, "cell"> | undefined): void;
+    /**
+     * Get metadata for a cell
+     */
+    getCellMetadata(address: CellAddress): MetadataType<TMetadata, "cell"> | undefined;
+    /**
+     * Get all cell metadata for a sheet (serialized as Map)
+     */
+    getSheetMetadataSerialized(opts: {
+        sheetName: string;
+        workbookName: string;
+    }): Map<string, MetadataType<TMetadata, "sheet">>;
+    /**
+     * 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: MetadataType<TMetadata, "sheet">): void;
+    /**
+     * Get metadata for a sheet
+     */
+    getSheetMetadata(opts: {
+        workbookName: string;
+        sheetName: string;
+    }): MetadataType<TMetadata, "sheet"> | undefined;
+    /**
+     * Set metadata for a workbook
+     * Workbook metadata can contain themes, document properties, settings, or any consumer-defined data
+     */
+    setWorkbookMetadata(workbookName: string, metadata: MetadataType<TMetadata, "workbook">): void;
+    /**
+     * Get metadata for a workbook
+     */
+    getWorkbookMetadata(workbookName: string): MetadataType<TMetadata, "workbook"> | 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
@@ -50,29 +130,37 @@ export declare class FormulaEngine {
     formula: string, cellAddress: CellAddress): SerializedCellValue;
     getCellDependents(address: CellAddress | SpreadsheetRange): (SpreadsheetRange | CellAddress)[];
     getCellPrecedents(address: CellAddress | SpreadsheetRange): (SpreadsheetRange | CellAddress)[];
-    addNamedExpression({ expression, expressionName, sheetName, workbookName, }: {
+    addNamedExpression(opts: {
         expression: string;
         expressionName: string;
         sheetName?: string;
         workbookName?: string;
     }): void;
-    removeNamedExpression({ expressionName, sheetName, workbookName, }: {
+    removeNamedExpression(opts: {
+        expressionName: string;
+        sheetName?: string;
+        workbookName?: string;
+    }): void;
+    /**
+     * Check if a named expression exists
+     */
+    hasNamedExpression(opts: {
         expressionName: string;
         sheetName?: string;
         workbookName?: string;
     }): boolean;
-    updateNamedExpression({ expression, expressionName, sheetName, workbookName, }: {
+    updateNamedExpression(opts: {
         expression: string;
         expressionName: string;
         sheetName?: string;
         workbookName?: string;
     }): void;
-    renameNamedExpression({ expressionName, sheetName, workbookName, newName, }: {
+    renameNamedExpression(opts: {
         expressionName: string;
         sheetName?: string;
         workbookName?: string;
         newName: string;
-    }): boolean;
+    }): void;
     setNamedExpressions(opts: ({
         type: "global";
     } | {
@@ -92,7 +180,7 @@ export declare class FormulaEngine {
         start: string;
         numRows: SpreadsheetRangeEnd;
         numCols: number;
-    }): TableDefinition;
+    }): void;
     renameTable(workbookName: string, names: {
         oldName: string;
         newName: string;
@@ -108,10 +196,29 @@ export declare class FormulaEngine {
     removeTable(opts: {
         tableName: string;
         workbookName: string;
+    }): void;
+    /**
+     * Check if a table exists
+     */
+    hasTable(opts: {
+        tableName: string;
+        workbookName: string;
     }): boolean;
+    /**
+     * Get a table definition by name
+     */
+    getTable(opts: {
+        tableName: string;
+        workbookName: string;
+    }): TableDefinition | undefined;
     resetTables(tables: Map<string, Map<string, TableDefinition>>): void;
     getTables(workbookName: string): Map<string, TableDefinition>;
     isCellInTable(cellAddress: CellAddress): TableDefinition | undefined;
+    /**
+     * Get all data cells in a table (excluding header row).
+     * Uses workbook indexes to efficiently handle infinite tables.
+     */
+    private getTableDataCells;
     /**
      * Add a conditional style rule
      */
@@ -119,7 +226,11 @@ export declare class FormulaEngine {
     /**
      * Remove a conditional style rule by index
      */
-    removeConditionalStyle(workbookName: string, index: number): boolean;
+    removeConditionalStyle(workbookName: string, index: number): void;
+    /**
+     * Get the count of conditional styles for a workbook
+     */
+    getConditionalStyleCount(workbookName: string): number;
     /**
      * Get all conditional styles intersecting with a range
      */
@@ -128,6 +239,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
      */
@@ -135,7 +254,11 @@ export declare class FormulaEngine {
     /**
      * Remove a direct cell style rule by index
      */
-    removeCellStyle(workbookName: string, index: number): boolean;
+    removeCellStyle(workbookName: string, index: number): void;
+    /**
+     * Get the count of direct cell styles for a workbook
+     */
+    getCellStyleCount(workbookName: string): number;
     /**
      * Get all direct cell styles intersecting with a range
      */
@@ -221,53 +344,100 @@ 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;
+    }): void;
     removeSheet(opts: {
         workbookName: string;
         sheetName: string;
-    }): import("./types").Sheet;
+    }): void;
     renameSheet(opts: {
         sheetName: string;
         newSheetName: string;
         workbookName: string;
-    }): import("./types").Sheet;
-    getSheets(workbookName: string): Map<string, import("./types").Sheet>;
+    }): void;
+    /**
+     * Check if a sheet exists
+     */
+    hasSheet(opts: {
+        workbookName: string;
+        sheetName: string;
+    }): boolean;
+    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;
     }): Map<string, SerializedCellValue>;
     addWorkbook(workbookName: string): void;
     removeWorkbook(workbookName: string): void;
+    /**
+     * Check if a workbook exists
+     */
+    hasWorkbook(workbookName: string): boolean;
     cloneWorkbook(fromWorkbookName: string, toWorkbookName: string): void;
     renameWorkbook(opts: {
         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
      * @param content - A map of cell addresses to their serialized values
      * @remarks This method is used to set the content of a sheet. It will re-evaluate all sheets to ensure all dependencies are resolved correctly.
+     * @throws SchemaIntegrityError if any evaluated cell value violates a schema constraint
      */
     setSheetContent(opts: {
         sheetName: string;
         workbookName: string;
     }, content: Map<string, SerializedCellValue>): void;
-    setCellContent(address: CellAddress, content: SerializedCellValue): void;
     /**
-     * Re-evaluates all sheets to ensure all dependencies are resolved correctly
-     *
-     * but just clears the evaluation cache
+     * Set the content of a single cell.
+     * @throws SchemaIntegrityError if the evaluated value violates a schema constraint
      */
-    reevaluate(): void;
+    setCellContent(address: CellAddress, content: SerializedCellValue): void;
     /**
      * Auto-fills one or more ranges based on the seedRange and the direction.
      * Supports pattern detection and style copying.
@@ -293,7 +463,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,8 +472,56 @@ 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;
     resetToSerializedEngine(data: string): void;
+    /**
+     * Undo the last command.
+     * @returns true if undo was performed, false if nothing to undo
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone command.
+     * @returns true if redo was performed, false if nothing to redo
+     */
+    redo(): boolean;
+    /**
+     * Check if undo is available.
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available.
+     */
+    canRedo(): boolean;
+    /**
+     * Get the action log for persistence/collaboration.
+     * Actions can be serialized and replayed to reconstruct state.
+     */
+    getActionLog(): EngineAction[];
+    /**
+     * Clear the action log.
+     */
+    clearActionLog(): void;
+    /**
+     * Clear undo/redo history.
+     */
+    clearHistory(): void;
+    /**
+     * Get dependencies for structure commands.
+     * @internal
+     */
+    private getStructureCommandDeps;
+    /**
+     * Get dependencies for table commands.
+     * @internal
+     */
+    private getTableCommandDeps;
+    /**
+     * Get dependencies for named expression commands.
+     * @internal
+     */
+    private getNamedExpressionCommandDeps;
 }
+export {};

package/dist/types/core/managers/api-schema-manager.d.ts

@@ -0,0 +1,121 @@
+/**
+ * ApiSchemaManager - Manages API schema definitions and validation
+ *
+ * Tracks registered schemas and provides validation for cell writes,
+ * spill operations, and copy/paste operations.
+ */
+import type { CellAddress, SerializedCellValue, SpreadsheetRange, TableDefinition } from "../types";
+import type { TableManager } from "./table-manager";
+export type ParseFunction<TCellMetadata = unknown> = (value: unknown, metadata: TCellMetadata) => unknown;
+export type TableSchemaHeaders<TCellMetadata = unknown> = Record<string, {
+    parse: ParseFunction<TCellMetadata>;
+    index: number;
+}>;
+export interface RegisteredTableSchema {
+    type: "table";
+    namespace: string;
+    workbookName: string;
+    tableName: string;
+    headers: TableSchemaHeaders;
+}
+export interface RegisteredCellSchema {
+    type: "cell";
+    namespace: string;
+    cellAddress: CellAddress;
+    parse: ParseFunction;
+}
+export type RegisteredSchema = RegisteredTableSchema | RegisteredCellSchema;
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    originalError?: Error;
+}
+export declare class SchemaValidationError extends Error {
+    cellAddress?: CellAddress | undefined;
+    originalError?: Error | undefined;
+    constructor(message: string, cellAddress?: CellAddress | undefined, originalError?: Error | undefined);
+}
+export declare class ApiSchemaManager {
+    private tableManager;
+    private schemas;
+    constructor(tableManager: TableManager);
+    /**
+     * Register a table schema
+     */
+    registerTableSchema(namespace: string, workbookName: string, tableName: string, headers: TableSchemaHeaders): void;
+    /**
+     * Register a cell schema
+     */
+    registerCellSchema(namespace: string, cellAddress: CellAddress, parse: ParseFunction): void;
+    /**
+     * Get a schema by namespace
+     */
+    getSchema(namespace: string): RegisteredSchema | undefined;
+    /**
+     * Remove a schema
+     */
+    removeSchema(namespace: string): boolean;
+    /**
+     * Check if a cell is protected by a schema
+     * Returns the schema info if protected, null otherwise
+     */
+    isCellProtected(cell: CellAddress): {
+        schema: RegisteredSchema;
+        columnName?: string;
+    } | null;
+    /**
+     * Check if a cell is within a table's data range (excluding header row)
+     */
+    private isCellInTableDataRange;
+    /**
+     * Get column name by index from headers
+     */
+    private getColumnNameByIndex;
+    /**
+     * Validate a cell write against schemas
+     */
+    validateCellWrite(cell: CellAddress, value: SerializedCellValue, metadata?: unknown): ValidationResult;
+    /**
+     * Validate a spill area against schemas
+     * Returns validation result - if invalid, spill should produce #SPILL! error
+     */
+    validateSpillArea(origin: CellAddress, spillArea: SpreadsheetRange, getSpillValue: (row: number, col: number) => SerializedCellValue, getMetadata?: (cell: CellAddress) => unknown): ValidationResult;
+    /**
+     * Update schemas when a table is renamed
+     */
+    updateForTableRename(workbookName: string, oldTableName: string, newTableName: string): void;
+    /**
+     * Update schemas when a sheet is renamed
+     */
+    updateForSheetRename(workbookName: string, oldSheetName: string, newSheetName: string): void;
+    /**
+     * Update schemas when a workbook is renamed
+     */
+    updateForWorkbookRename(oldWorkbookName: string, newWorkbookName: string): void;
+    /**
+     * Get all schemas (for debugging/testing)
+     */
+    getAllSchemas(): Map<string, RegisteredSchema>;
+    /**
+     * Validate all schema constraints using evaluated cell values.
+     *
+     * This is the key method for schema validation with rollback:
+     * - It validates EVALUATED values, not raw content
+     * - A cell with "=123+123" validates as number (246), not string
+     * - Called after re-evaluation to check all schema-constrained cells
+     *
+     * @param getCellValue - Function to get the evaluated value of a cell
+     * @param getCellMetadata - Optional function to get cell metadata
+     * @returns Validation result with all errors found
+     */
+    validateAllSchemaConstraints(getCellValue: (cell: CellAddress) => SerializedCellValue, getCellMetadata?: (cell: CellAddress) => unknown, getTableDataCells?: (table: TableDefinition) => CellAddress[]): {
+        valid: boolean;
+        errors: Array<{
+            message: string;
+            cellAddress?: CellAddress;
+            schemaNamespace?: string;
+            columnName?: string;
+            originalError?: Error;
+        }>;
+    };
+}

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;
 }