@ricsam/formula-engine 0.0.16 → 0.0.18

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

@@ -72,6 +72,7 @@ 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;
@@ -104,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
@@ -124,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/dist/types/lib.d.ts

@@ -2,3 +2,11 @@ export { FormulaEngine } from "./core/engine";
 export * from "./core/types";
 export * from "./core/utils";
 export * from "./core/utils/color-utils";
+export { defineApi, createApi } from "./core/api/api";
+export type { CreateApi, Declaration, Api, TableApi, CellApi } from "./core/api/api";
+export { TableOrm } from "./core/api/table-orm";
+export { CellOrm } from "./core/api/cell-orm";
+export { SchemaValidationError } from "./core/managers/api-schema-manager";
+export type { ValidationResult } from "./core/managers/api-schema-manager";
+export { SchemaIntegrityError } from "./core/commands";
+export type { EngineAction, EngineCommand } from "./core/commands";

package/package.json

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