@ricsam/formula-engine 0.2.11 → 0.2.12

package/dist/mjs/core/managers/range-metadata-manager.mjs

@@ -0,0 +1,95 @@
+// src/core/managers/range-metadata-manager.ts
+import { isCellInRange } from "../utils.mjs";
+import { rangesIntersect, subtractRange } from "../utils/range-utils.mjs";
+var cloneArea = (area) => ({
+  workbookName: area.workbookName,
+  sheetName: area.sheetName,
+  range: {
+    start: { ...area.range.start },
+    end: {
+      col: { ...area.range.end.col },
+      row: { ...area.range.end.row }
+    }
+  }
+});
+var cloneEntry = (entry) => ({
+  id: entry.id,
+  areas: entry.areas.map(cloneArea),
+  metadata: entry.metadata
+});
+
+class RangeMetadataManager {
+  rangeMetadata = [];
+  addRangeMetadata(entry) {
+    const id = entry.id ?? crypto.randomUUID();
+    if (this.rangeMetadata.some((existing) => existing.id === id)) {
+      throw new Error(`Range metadata with id "${id}" already exists`);
+    }
+    this.rangeMetadata.push({
+      id,
+      areas: entry.areas.map(cloneArea),
+      metadata: entry.metadata
+    });
+    return id;
+  }
+  removeRangeMetadata(id) {
+    const beforeLength = this.rangeMetadata.length;
+    this.rangeMetadata = this.rangeMetadata.filter((entry) => entry.id !== id);
+    return this.rangeMetadata.length !== beforeLength;
+  }
+  getAllRangeMetadata() {
+    return this.rangeMetadata.map(cloneEntry);
+  }
+  getRangeMetadataForCell(cellAddress) {
+    return this.rangeMetadata.filter((entry) => entry.areas.some((area) => area.workbookName === cellAddress.workbookName && area.sheetName === cellAddress.sheetName && isCellInRange(cellAddress, area.range))).map(cloneEntry);
+  }
+  getRangeMetadataIntersectingWithRange(range) {
+    return this.rangeMetadata.filter((entry) => entry.areas.some((area) => area.workbookName === range.workbookName && area.sheetName === range.sheetName && rangesIntersect(area.range, range.range))).map(cloneEntry);
+  }
+  clearRangeMetadataInRange(range) {
+    this.rangeMetadata = this.rangeMetadata.map((entry) => ({
+      ...entry,
+      areas: entry.areas.flatMap((area) => {
+        if (area.workbookName !== range.workbookName || area.sheetName !== range.sheetName) {
+          return [area];
+        }
+        return subtractRange(area.range, range.range).map((remainingRange) => ({
+          ...area,
+          range: remainingRange
+        }));
+      })
+    })).filter((entry) => entry.areas.length > 0);
+  }
+  removeWorkbookRangeMetadata(workbookName) {
+    this.rangeMetadata = this.rangeMetadata.filter((entry) => !entry.areas.some((area) => area.workbookName === workbookName));
+  }
+  removeSheetRangeMetadata(workbookName, sheetName) {
+    this.rangeMetadata = this.rangeMetadata.filter((entry) => !entry.areas.some((area) => area.workbookName === workbookName && area.sheetName === sheetName));
+  }
+  updateWorkbookName(oldName, newName) {
+    this.rangeMetadata = this.rangeMetadata.map((entry) => ({
+      ...entry,
+      areas: entry.areas.map((area) => area.workbookName === oldName ? { ...area, workbookName: newName } : area)
+    }));
+  }
+  updateSheetName(workbookName, oldSheetName, newSheetName) {
+    this.rangeMetadata = this.rangeMetadata.map((entry) => ({
+      ...entry,
+      areas: entry.areas.map((area) => area.workbookName === workbookName && area.sheetName === oldSheetName ? { ...area, sheetName: newSheetName } : area)
+    }));
+  }
+  resetRangeMetadata(rangeMetadata) {
+    this.rangeMetadata = rangeMetadata ? rangeMetadata.map(cloneEntry) : [];
+  }
+  toSnapshot() {
+    return this.getAllRangeMetadata();
+  }
+  restoreFromSnapshot(snapshot) {
+    this.resetRangeMetadata(snapshot);
+  }
+}
+export {
+  RangeMetadataManager
+};
+
+//# debugId=7530C074EFE9F64464756E2164756E21

package/dist/mjs/core/managers/range-metadata-manager.mjs.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/core/managers/range-metadata-manager.ts"],
+  "sourcesContent": [
+    "/**\n * RangeMetadataManager - Manages arbitrary consumer-defined metadata attached\n * to ranges rather than individual cells.\n */\n\nimport type {\n  CellAddress,\n  RangeAddress,\n  RangeMetadata,\n  RangeMetadataInput,\n} from \"../types.mjs\";\nimport type { RangeMetadataManagerSnapshot } from \"../engine-snapshot.mjs\";\nimport { isCellInRange } from \"../utils.mjs\";\nimport { rangesIntersect, subtractRange } from \"../utils/range-utils.mjs\";\n\nconst cloneArea = (area: RangeAddress): RangeAddress => ({\n  workbookName: area.workbookName,\n  sheetName: area.sheetName,\n  range: {\n    start: { ...area.range.start },\n    end: {\n      col: { ...area.range.end.col },\n      row: { ...area.range.end.row },\n    },\n  },\n});\n\nconst cloneEntry = <TMetadata>(\n  entry: RangeMetadata<TMetadata>\n): RangeMetadata<TMetadata> => ({\n  id: entry.id,\n  areas: entry.areas.map(cloneArea),\n  metadata: entry.metadata,\n});\n\nexport class RangeMetadataManager<TMetadata = unknown> {\n  private rangeMetadata: RangeMetadata<TMetadata>[] = [];\n\n  addRangeMetadata(entry: RangeMetadataInput<TMetadata>): string {\n    const id = entry.id ?? crypto.randomUUID();\n    if (this.rangeMetadata.some((existing) => existing.id === id)) {\n      throw new Error(`Range metadata with id \"${id}\" already exists`);\n    }\n\n    this.rangeMetadata.push({\n      id,\n      areas: entry.areas.map(cloneArea),\n      metadata: entry.metadata,\n    });\n\n    return id;\n  }\n\n  removeRangeMetadata(id: string): boolean {\n    const beforeLength = this.rangeMetadata.length;\n    this.rangeMetadata = this.rangeMetadata.filter((entry) => entry.id !== id);\n    return this.rangeMetadata.length !== beforeLength;\n  }\n\n  getAllRangeMetadata(): RangeMetadata<TMetadata>[] {\n    return this.rangeMetadata.map(cloneEntry);\n  }\n\n  getRangeMetadataForCell(cellAddress: CellAddress): RangeMetadata<TMetadata>[] {\n    return this.rangeMetadata\n      .filter((entry) =>\n        entry.areas.some(\n          (area) =>\n            area.workbookName === cellAddress.workbookName &&\n            area.sheetName === cellAddress.sheetName &&\n            isCellInRange(cellAddress, area.range)\n        )\n      )\n      .map(cloneEntry);\n  }\n\n  getRangeMetadataIntersectingWithRange(\n    range: RangeAddress\n  ): RangeMetadata<TMetadata>[] {\n    return this.rangeMetadata\n      .filter((entry) =>\n        entry.areas.some(\n          (area) =>\n            area.workbookName === range.workbookName &&\n            area.sheetName === range.sheetName &&\n            rangesIntersect(area.range, range.range)\n        )\n      )\n      .map(cloneEntry);\n  }\n\n  clearRangeMetadataInRange(range: RangeAddress): void {\n    this.rangeMetadata = this.rangeMetadata\n      .map((entry) => ({\n        ...entry,\n        areas: entry.areas.flatMap((area) => {\n          if (\n            area.workbookName !== range.workbookName ||\n            area.sheetName !== range.sheetName\n          ) {\n            return [area];\n          }\n\n          return subtractRange(area.range, range.range).map((remainingRange) => ({\n            ...area,\n            range: remainingRange,\n          }));\n        }),\n      }))\n      .filter((entry) => entry.areas.length > 0);\n  }\n\n  removeWorkbookRangeMetadata(workbookName: string): void {\n    this.rangeMetadata = this.rangeMetadata.filter(\n      (entry) => !entry.areas.some((area) => area.workbookName === workbookName)\n    );\n  }\n\n  removeSheetRangeMetadata(workbookName: string, sheetName: string): void {\n    this.rangeMetadata = this.rangeMetadata.filter(\n      (entry) =>\n        !entry.areas.some(\n          (area) =>\n            area.workbookName === workbookName && area.sheetName === sheetName\n        )\n    );\n  }\n\n  updateWorkbookName(oldName: string, newName: string): void {\n    this.rangeMetadata = this.rangeMetadata.map((entry) => ({\n      ...entry,\n      areas: entry.areas.map((area) =>\n        area.workbookName === oldName ? { ...area, workbookName: newName } : area\n      ),\n    }));\n  }\n\n  updateSheetName(\n    workbookName: string,\n    oldSheetName: string,\n    newSheetName: string\n  ): void {\n    this.rangeMetadata = this.rangeMetadata.map((entry) => ({\n      ...entry,\n      areas: entry.areas.map((area) =>\n        area.workbookName === workbookName && area.sheetName === oldSheetName\n          ? { ...area, sheetName: newSheetName }\n          : area\n      ),\n    }));\n  }\n\n  resetRangeMetadata(rangeMetadata?: RangeMetadata<TMetadata>[]): void {\n    this.rangeMetadata = rangeMetadata ? rangeMetadata.map(cloneEntry) : [];\n  }\n\n  toSnapshot(): RangeMetadataManagerSnapshot {\n    return this.getAllRangeMetadata();\n  }\n\n  restoreFromSnapshot(snapshot: RangeMetadataManagerSnapshot): void {\n    this.resetRangeMetadata(snapshot as RangeMetadata<TMetadata>[]);\n  }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "7530C074EFE9F64464756E2164756E21",
+  "names": []
+}

package/dist/mjs/core/types.mjs.map

@@ -2,7 +2,7 @@
   "version": 3,
   "sources": ["../../../src/core/types.ts"],
   "sourcesContent": [
-    "/**\n * Core type definitions for FormulaEngine\n * This file contains all fundamental types used throughout the engine\n */\n\nimport type { EvaluationContext } from \"../evaluator/evaluation-context.mjs\";\nimport type { FormulaEvaluator } from \"../evaluator/formula-evaluator.mjs\";\nimport type { FunctionNode } from \"../parser/ast.mjs\";\nimport type { DependencyNode } from \"./managers/dependency-node.mjs\";\nimport type { LookupOrder } from \"./managers/range-eval-order-builder.mjs\";\n\n// Cell addressing types\nexport interface CellAddress {\n  sheetName: string;\n  workbookName: string;\n  colIndex: number;\n  rowIndex: number;\n}\n\nexport interface RangeAddress {\n  sheetName: string;\n  workbookName: string;\n  range: SpreadsheetRange;\n}\n\nexport interface LocalCellAddress {\n  colIndex: number;\n  rowIndex: number;\n}\n\nexport type ArethmeticEvaluator = (\n  left: CellValue,\n  right: CellValue,\n  context: EvaluationContext\n) => CellValue | ErrorEvaluationResult;\n\nexport type PositiveInfinity = {\n  type: \"infinity\";\n  sign: \"positive\";\n};\n\nexport type CellInfinity = {\n  type: \"infinity\";\n  sign: \"positive\" | \"negative\";\n};\n\nexport type CellNumber = {\n  type: \"number\";\n  value: number;\n};\n\nexport type SpreadsheetRangeEnd = CellNumber | PositiveInfinity;\n\nexport type SpreadsheetRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  end: {\n    col: SpreadsheetRangeEnd;\n    row: SpreadsheetRangeEnd;\n  };\n};\n\nexport type RelativeRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  width: SpreadsheetRangeEnd;\n  height: SpreadsheetRangeEnd;\n};\n\nexport type FiniteSpreadsheetRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  end: {\n    col: number;\n    row: number;\n  };\n};\n\nexport type CellString = {\n  type: \"string\";\n  value: string;\n};\n\nexport type CellBoolean = {\n  type: \"boolean\";\n  value: boolean;\n};\n\n// Cell value types\nexport type CellValue = CellNumber | CellString | CellBoolean | CellInfinity;\n/**\n * undefined and \"\" are considered empty values\n * undefineds are converted to \"\" in the engine\n *\n * any empty values are deleted from the sheet content\n */\nexport type SerializedCellValue = string | number | boolean | undefined;\n\nexport interface SearchOptions {\n  workbookName?: string;\n  sheetName?: string;\n  caseSensitive?: boolean;\n}\n\nexport interface SearchMatch {\n  workbookName: string;\n  sheetName: string;\n  cellReference: string;\n  cellContent: string;\n  contentKind: \"formula\" | \"text\";\n  occurrenceIndex: number;\n  startIndex: number;\n  endIndexExclusive: number;\n  matchedText: string;\n}\n\nexport interface ReplaceTarget {\n  workbookName: string;\n  sheetName: string;\n  cellReference: string;\n  occurrenceIndex: number;\n}\n\nexport interface ReplaceChange {\n  workbookName: string;\n  sheetName: string;\n  cellReference: string;\n  contentKind: \"formula\" | \"text\";\n  occurrenceIndex: number;\n  startIndex: number;\n  endIndexExclusive: number;\n  matchedText: string;\n  replacementText: string;\n  beforeContent: string;\n  afterContent: string;\n}\n\n// Named expressions\nexport interface NamedExpression {\n  name: string;\n  expression: string;\n}\n\nexport interface TableDefinition {\n  name: string;\n  start: {\n    rowIndex: number;\n    colIndex: number;\n  };\n  headers: Map<string, { name: string; index: number }>;\n  endRow: SpreadsheetRangeEnd;\n  sheetName: string;\n  workbookName: string;\n}\n\n// Formula errors\nexport enum FormulaError {\n  DIV0 = \"#DIV/0!\",\n  NA = \"#N/A\",\n  NAME = \"#NAME?\",\n  NUM = \"#NUM!\",\n  REF = \"#REF!\",\n  VALUE = \"#VALUE!\",\n  CYCLE = \"#CYCLE!\",\n  ERROR = \"#ERROR!\",\n  SPILL = \"#SPILL!\",\n}\n\n// Sheet structure\nexport interface Sheet<TCellMetadata = unknown, TSheetMetadata = unknown> {\n  name: string;\n  index: number; // 0-based index of the sheet\n  content: Map<string, SerializedCellValue>;\n  /**\n   * Cell metadata - arbitrary consumer-defined data per cell\n   * Examples: rich text content, links, comments, custom app data\n   * The engine stores and copies this data but doesn't interpret it\n   * Keyed by cell reference (e.g., \"A1\")\n   */\n  metadata: Map<string, TCellMetadata>;\n  /**\n   * Sheet-level metadata - arbitrary consumer-defined data for the entire sheet\n   * Examples: text boxes, drawings, frozen panes, print settings\n   * The engine stores and copies this data but doesn't interpret it\n   */\n  sheetMetadata: TSheetMetadata;\n}\n\nexport interface Workbook<\n  TCellMetadata = unknown,\n  TSheetMetadata = unknown,\n  TWorkbookMetadata = unknown\n> {\n  name: string;\n  sheets: Map<string, Sheet<TCellMetadata, TSheetMetadata>>;\n  /**\n   * Workbook-level metadata - arbitrary consumer-defined data for the entire workbook\n   * Examples: themes, custom ribbons, document properties, workbook settings\n   * The engine stores and copies this data but doesn't interpret it\n   */\n  workbookMetadata: TWorkbookMetadata;\n}\n\n/**\n * Tracked reference - a stable reference to a range that updates automatically\n * when workbooks/sheets are renamed and becomes invalid when they're deleted\n */\nexport interface TrackedReference {\n  id: string; // UUID\n  address: RangeAddress; // The range being tracked\n  isValid: boolean; // False if sheet/workbook deleted\n}\n\nexport type ValueEvaluationResult = {\n  type: \"value\";\n  result: CellValue;\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   */\n  sourceCell?: CellAddress;\n};\n\nexport type AwaitingEvaluationResult = {\n  type: \"awaiting-evaluation\";\n  waitingFor: DependencyNode;\n  errAddress: DependencyNode;\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   */\n  sourceCell?: CellAddress;\n};\n\nexport type DoesNotSpillResult = {\n  type: \"does-not-spill\";\n};\n\nexport type ErrorEvaluationResult =\n  | {\n      type: \"error\";\n      err: FormulaError;\n      errAddress: DependencyNode;\n      message: string;\n      /**\n       * If the terminating evaluation result is a reference (see evaluateReference)\n       * then we store information about the source cell for context dependent functions like CELL\n       */\n      sourceCell?: CellAddress;\n    }\n  | AwaitingEvaluationResult;\n\nexport type SingleEvaluationResult =\n  | ValueEvaluationResult\n  | ErrorEvaluationResult;\n\nexport type SpilledValuesEvaluator = (\n  spillOffset: { x: number; y: number },\n  context: EvaluationContext\n) => SingleEvaluationResult;\n\nexport type SpilledValuesEvaluationResult = {\n  type: \"spilled-values\";\n\n  /**\n   * When a raw range is evaluated, we will add it to the sourceRange so it can be used e.g. for context dependent functions\n   */\n  sourceRange?: RangeAddress;\n\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   * sourceCell will only be defined on a spilledValue when a single value is looked up,\n   */\n  sourceCell?: CellAddress;\n\n  spillArea: (origin: CellAddress) => SpreadsheetRange;\n  /**\n   * for debugging we add a source string to denote where the spilled values were created\n   */\n  source: string;\n  evaluate: SpilledValuesEvaluator;\n  /**\n   * evaluateAllCells evaluates all non-empty cells in the spilled range.\n   * Because a spilled range can be open-ended, we need to have logic for which cells we should evaluate.\n   * e.g. when evaluating a range such as D:D only the cells in the current sheet residing in\n   * column D should be evaluated and cells producing spilled values that spill onto D:D.\n   *\n   * In order to evaluate spilled cells in D:D the range evaluateAllCells need to get all cells in the\n   * the intersection of the spilled range and D:D, for that reason evaluateAllCells gets an intersection parameter,\n   * where the intersection is relative to the origin.\n   *\n   * #### Producers:\n   * In e.g. SEQUENCE and evaluateRange we have logic for which cells in a spilled range we should evaluate,\n   *\n   * #### Nesting:\n   * e.g. evaluation of scalar operators where we want to nest e.g. `5 * right.evaluate()`\n   * can be implemented by calling\n   * ```ts\n   * const vals = child.evaluateAllCells.call(this, options);\n   * return vals.map(val => ({ ...val, result: 5 * val.result }));\n   * ```\n   *\n   * #### Consumers:\n   * Only functions that need access to all spilled values in a range end up calling evaluateAllCells, e.g.\n   * SUM, MIN, MAX, MATCH. Other types of functions like INDEX doesn't need to evaluate all cells in a range,\n   * but does a lookup into a spilled range using the evaluate method.\n   *\n   */\n  evaluateAllCells: (\n    this: FormulaEvaluator,\n    options: {\n      /**\n       * an intersection relative to the origin\n       */\n      intersection?: SpreadsheetRange;\n      evaluate: SpilledValuesEvaluator;\n      context: EvaluationContext;\n      /**\n       * origin is the cell address that the spilled range is spilled from\n       * e.g. in A3=B2:B4 the origin is A3\n       */\n      origin: CellAddress;\n\n      lookupOrder: LookupOrder;\n    }\n  ) => EvaluateAllCellsResult;\n};\n\nexport type EvaluateAllCellsResult =\n  | ErrorEvaluationResult\n  | {\n      type: \"values\";\n      values: CellInRangeResult[];\n    };\n\nexport type CellInRangeResult = {\n  result: SingleEvaluationResult;\n  relativePos: { x: number; y: number };\n};\n\nexport type FunctionEvaluationResult =\n  | SingleEvaluationResult\n  | SpilledValuesEvaluationResult;\n\nexport type SpilledValue = {\n  /**\n   * spillOnto is the range that the spilled value is spilled onto\n   */\n  spillOnto: SpreadsheetRange;\n  /**\n   * origin is the cell address that the spilled value is spilled from\n   */\n  origin: CellAddress;\n};\n\n/**\n * Function definition\n */\nexport interface FunctionDefinition {\n  name: string;\n  evaluate: (\n    this: FormulaEvaluator,\n    node: FunctionNode,\n    context: EvaluationContext\n  ) => FunctionEvaluationResult;\n  aliases?: string[];\n}\n\n/**\n * Evaluation result\n */\nexport type EvaluationResult = {\n  dependencies: Set<string>;\n} & FunctionEvaluationResult;\n\nexport type SCC = {\n  id: number;\n  nodes: Set<DependencyNode>; // All nodes considering soft + hard edges\n  evaluationOrder: DependencyNode[]; // Flat topologically ordered list\n  resolved: boolean;\n  hardEdgeSCCs: Set<DependencyNode>[]; // SCCs formed by only hard edges (regular dependencies)\n};\n\nexport type SCCDAG = {\n  sccList: SCC[];\n  sccGraph: Map<number, Set<number>>; // Adjacency list of SCC dependencies\n};\n\nexport type EvaluationOrder = {\n  evaluationOrder: Set<DependencyNode>;\n  hasCycle: boolean;\n  cycleNodes?: Set<DependencyNode>;\n  hash: string;\n  sccDAG?: SCCDAG;\n};\n\n// Conditional Styling types\nexport interface LCHColor {\n  l: number; // Lightness: 0-100\n  c: number; // Chroma: 0-150+\n  h: number; // Hue: 0-360\n}\n\nexport interface FormulaStyleCondition {\n  type: \"formula\";\n  formula: string;\n  color: LCHColor;\n}\n\nexport interface GradientStyleCondition {\n  type: \"gradient\";\n  min:\n    | { type: \"lowest_value\"; color: LCHColor }\n    | { type: \"number\"; color: LCHColor; valueFormula: string };\n  max:\n    | { type: \"highest_value\"; color: LCHColor }\n    | { type: \"number\"; color: LCHColor; valueFormula: string };\n}\n\nexport type StyleCondition = FormulaStyleCondition | GradientStyleCondition;\n\nexport interface ConditionalStyle {\n  areas: RangeAddress[];\n  condition: StyleCondition;\n}\n\nexport interface DirectCellStyle {\n  areas: RangeAddress[];\n  style: CellStyle;\n}\n\nexport interface CellStyle {\n  backgroundColor?: string; // Hex color format\n  color?: string; // Text color in hex format\n  fontSize?: number; // Font size in pixels\n  bold?: boolean;\n  italic?: boolean;\n  underline?: boolean;\n}\n\nexport interface CopyCellsOptions {\n  /**\n   * Whether this is a cut operation (clears source cells after copying)\n   * @default false\n   */\n  cut?: boolean;\n  /**\n   * What to include in the copy operation.\n   * - Use 'all' as shorthand for ['content', 'style', 'metadata']\n   * - Use array for fine-grained control over what to copy:\n   *   - ['content'] - copy only values/formulas\n   *   - ['style'] - copy only formatting\n   *   - ['metadata'] - copy only metadata (rich text, links, etc.)\n   *   - ['content', 'style'] - copy content and formatting\n   *   - ['content', 'metadata'] - copy content and metadata\n   *   - ['style', 'metadata'] - copy formatting and metadata\n   *   - ['content', 'style', 'metadata'] - same as 'all'\n   * @default 'all'\n   */\n  include?: \"all\" | (\"content\" | \"style\" | \"metadata\")[];\n  /**\n   * The type of the content to copy\n   * value: Copy the value from the source to the target,\n   * e.g. if the cell has the formula =123 + 123 then the value is 246\n   * formula: Copy the formula from the source to the target,\n   * e.g. if the cell has the formula =123 + 123 then the formula is =123 + 123 is copied\n   * @default 'formula'\n   */\n  type?: \"value\" | \"formula\";\n}\n"
+    "/**\n * Core type definitions for FormulaEngine\n * This file contains all fundamental types used throughout the engine\n */\n\nimport type { EvaluationContext } from \"../evaluator/evaluation-context.mjs\";\nimport type { FormulaEvaluator } from \"../evaluator/formula-evaluator.mjs\";\nimport type { FunctionNode } from \"../parser/ast.mjs\";\nimport type { DependencyNode } from \"./managers/dependency-node.mjs\";\nimport type { LookupOrder } from \"./managers/range-eval-order-builder.mjs\";\n\n// Cell addressing types\nexport interface CellAddress {\n  sheetName: string;\n  workbookName: string;\n  colIndex: number;\n  rowIndex: number;\n}\n\nexport interface RangeAddress {\n  sheetName: string;\n  workbookName: string;\n  range: SpreadsheetRange;\n}\n\nexport interface LocalCellAddress {\n  colIndex: number;\n  rowIndex: number;\n}\n\nexport type ArethmeticEvaluator = (\n  left: CellValue,\n  right: CellValue,\n  context: EvaluationContext\n) => CellValue | ErrorEvaluationResult;\n\nexport type PositiveInfinity = {\n  type: \"infinity\";\n  sign: \"positive\";\n};\n\nexport type CellInfinity = {\n  type: \"infinity\";\n  sign: \"positive\" | \"negative\";\n};\n\nexport type CellNumber = {\n  type: \"number\";\n  value: number;\n};\n\nexport type SpreadsheetRangeEnd = CellNumber | PositiveInfinity;\n\nexport type SpreadsheetRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  end: {\n    col: SpreadsheetRangeEnd;\n    row: SpreadsheetRangeEnd;\n  };\n};\n\nexport type RelativeRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  width: SpreadsheetRangeEnd;\n  height: SpreadsheetRangeEnd;\n};\n\nexport type FiniteSpreadsheetRange = {\n  start: {\n    col: number;\n    row: number;\n  };\n  end: {\n    col: number;\n    row: number;\n  };\n};\n\nexport type CellString = {\n  type: \"string\";\n  value: string;\n};\n\nexport type CellBoolean = {\n  type: \"boolean\";\n  value: boolean;\n};\n\n// Cell value types\nexport type CellValue = CellNumber | CellString | CellBoolean | CellInfinity;\n/**\n * undefined and \"\" are considered empty values\n * undefineds are converted to \"\" in the engine\n *\n * any empty values are deleted from the sheet content\n */\nexport type SerializedCellValue = string | number | boolean | undefined;\n\nexport interface SearchOptions {\n  workbookName?: string;\n  sheetName?: string;\n  caseSensitive?: boolean;\n}\n\nexport interface SearchMatch {\n  workbookName: string;\n  sheetName: string;\n  cellReference: string;\n  cellContent: string;\n  contentKind: \"formula\" | \"text\";\n  occurrenceIndex: number;\n  startIndex: number;\n  endIndexExclusive: number;\n  matchedText: string;\n}\n\nexport interface ReplaceTarget {\n  workbookName: string;\n  sheetName: string;\n  cellReference: string;\n  occurrenceIndex: number;\n}\n\nexport interface ReplaceChange {\n  workbookName: string;\n  sheetName: string;\n  cellReference: string;\n  contentKind: \"formula\" | \"text\";\n  occurrenceIndex: number;\n  startIndex: number;\n  endIndexExclusive: number;\n  matchedText: string;\n  replacementText: string;\n  beforeContent: string;\n  afterContent: string;\n}\n\n// Named expressions\nexport interface NamedExpression {\n  name: string;\n  expression: string;\n}\n\nexport interface TableDefinition {\n  name: string;\n  start: {\n    rowIndex: number;\n    colIndex: number;\n  };\n  headers: Map<string, { name: string; index: number }>;\n  endRow: SpreadsheetRangeEnd;\n  sheetName: string;\n  workbookName: string;\n}\n\n// Formula errors\nexport enum FormulaError {\n  DIV0 = \"#DIV/0!\",\n  NA = \"#N/A\",\n  NAME = \"#NAME?\",\n  NUM = \"#NUM!\",\n  REF = \"#REF!\",\n  VALUE = \"#VALUE!\",\n  CYCLE = \"#CYCLE!\",\n  ERROR = \"#ERROR!\",\n  SPILL = \"#SPILL!\",\n}\n\n// Sheet structure\nexport interface Sheet<TCellMetadata = unknown, TSheetMetadata = unknown> {\n  name: string;\n  index: number; // 0-based index of the sheet\n  content: Map<string, SerializedCellValue>;\n  /**\n   * Cell metadata - arbitrary consumer-defined data per cell\n   * Examples: rich text content, links, comments, custom app data\n   * The engine stores and copies this data but doesn't interpret it\n   * Keyed by cell reference (e.g., \"A1\")\n   */\n  metadata: Map<string, TCellMetadata>;\n  /**\n   * Sheet-level metadata - arbitrary consumer-defined data for the entire sheet\n   * Examples: text boxes, drawings, frozen panes, print settings\n   * The engine stores and copies this data but doesn't interpret it\n   */\n  sheetMetadata: TSheetMetadata;\n}\n\nexport interface Workbook<\n  TCellMetadata = unknown,\n  TSheetMetadata = unknown,\n  TWorkbookMetadata = unknown\n> {\n  name: string;\n  sheets: Map<string, Sheet<TCellMetadata, TSheetMetadata>>;\n  /**\n   * Workbook-level metadata - arbitrary consumer-defined data for the entire workbook\n   * Examples: themes, custom ribbons, document properties, workbook settings\n   * The engine stores and copies this data but doesn't interpret it\n   */\n  workbookMetadata: TWorkbookMetadata;\n}\n\n/**\n * Tracked reference - a stable reference to a range that updates automatically\n * when workbooks/sheets are renamed and becomes invalid when they're deleted\n */\nexport interface TrackedReference {\n  id: string; // UUID\n  address: RangeAddress; // The range being tracked\n  isValid: boolean; // False if sheet/workbook deleted\n}\n\nexport type ValueEvaluationResult = {\n  type: \"value\";\n  result: CellValue;\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   */\n  sourceCell?: CellAddress;\n};\n\nexport type AwaitingEvaluationResult = {\n  type: \"awaiting-evaluation\";\n  waitingFor: DependencyNode;\n  errAddress: DependencyNode;\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   */\n  sourceCell?: CellAddress;\n};\n\nexport type DoesNotSpillResult = {\n  type: \"does-not-spill\";\n};\n\nexport type ErrorEvaluationResult =\n  | {\n      type: \"error\";\n      err: FormulaError;\n      errAddress: DependencyNode;\n      message: string;\n      /**\n       * If the terminating evaluation result is a reference (see evaluateReference)\n       * then we store information about the source cell for context dependent functions like CELL\n       */\n      sourceCell?: CellAddress;\n    }\n  | AwaitingEvaluationResult;\n\nexport type SingleEvaluationResult =\n  | ValueEvaluationResult\n  | ErrorEvaluationResult;\n\nexport type SpilledValuesEvaluator = (\n  spillOffset: { x: number; y: number },\n  context: EvaluationContext\n) => SingleEvaluationResult;\n\nexport type SpilledValuesEvaluationResult = {\n  type: \"spilled-values\";\n\n  /**\n   * When a raw range is evaluated, we will add it to the sourceRange so it can be used e.g. for context dependent functions\n   */\n  sourceRange?: RangeAddress;\n\n  /**\n   * If the terminating evaluation result is a reference (see evaluateReference)\n   * then we store information about the source cell for context dependent functions like CELL\n   * sourceCell will only be defined on a spilledValue when a single value is looked up,\n   */\n  sourceCell?: CellAddress;\n\n  spillArea: (origin: CellAddress) => SpreadsheetRange;\n  /**\n   * for debugging we add a source string to denote where the spilled values were created\n   */\n  source: string;\n  evaluate: SpilledValuesEvaluator;\n  /**\n   * evaluateAllCells evaluates all non-empty cells in the spilled range.\n   * Because a spilled range can be open-ended, we need to have logic for which cells we should evaluate.\n   * e.g. when evaluating a range such as D:D only the cells in the current sheet residing in\n   * column D should be evaluated and cells producing spilled values that spill onto D:D.\n   *\n   * In order to evaluate spilled cells in D:D the range evaluateAllCells need to get all cells in the\n   * the intersection of the spilled range and D:D, for that reason evaluateAllCells gets an intersection parameter,\n   * where the intersection is relative to the origin.\n   *\n   * #### Producers:\n   * In e.g. SEQUENCE and evaluateRange we have logic for which cells in a spilled range we should evaluate,\n   *\n   * #### Nesting:\n   * e.g. evaluation of scalar operators where we want to nest e.g. `5 * right.evaluate()`\n   * can be implemented by calling\n   * ```ts\n   * const vals = child.evaluateAllCells.call(this, options);\n   * return vals.map(val => ({ ...val, result: 5 * val.result }));\n   * ```\n   *\n   * #### Consumers:\n   * Only functions that need access to all spilled values in a range end up calling evaluateAllCells, e.g.\n   * SUM, MIN, MAX, MATCH. Other types of functions like INDEX doesn't need to evaluate all cells in a range,\n   * but does a lookup into a spilled range using the evaluate method.\n   *\n   */\n  evaluateAllCells: (\n    this: FormulaEvaluator,\n    options: {\n      /**\n       * an intersection relative to the origin\n       */\n      intersection?: SpreadsheetRange;\n      evaluate: SpilledValuesEvaluator;\n      context: EvaluationContext;\n      /**\n       * origin is the cell address that the spilled range is spilled from\n       * e.g. in A3=B2:B4 the origin is A3\n       */\n      origin: CellAddress;\n\n      lookupOrder: LookupOrder;\n    }\n  ) => EvaluateAllCellsResult;\n};\n\nexport type EvaluateAllCellsResult =\n  | ErrorEvaluationResult\n  | {\n      type: \"values\";\n      values: CellInRangeResult[];\n    };\n\nexport type CellInRangeResult = {\n  result: SingleEvaluationResult;\n  relativePos: { x: number; y: number };\n};\n\nexport type FunctionEvaluationResult =\n  | SingleEvaluationResult\n  | SpilledValuesEvaluationResult;\n\nexport type SpilledValue = {\n  /**\n   * spillOnto is the range that the spilled value is spilled onto\n   */\n  spillOnto: SpreadsheetRange;\n  /**\n   * origin is the cell address that the spilled value is spilled from\n   */\n  origin: CellAddress;\n};\n\n/**\n * Function definition\n */\nexport interface FunctionDefinition {\n  name: string;\n  evaluate: (\n    this: FormulaEvaluator,\n    node: FunctionNode,\n    context: EvaluationContext\n  ) => FunctionEvaluationResult;\n  aliases?: string[];\n}\n\n/**\n * Evaluation result\n */\nexport type EvaluationResult = {\n  dependencies: Set<string>;\n} & FunctionEvaluationResult;\n\nexport type SCC = {\n  id: number;\n  nodes: Set<DependencyNode>; // All nodes considering soft + hard edges\n  evaluationOrder: DependencyNode[]; // Flat topologically ordered list\n  resolved: boolean;\n  hardEdgeSCCs: Set<DependencyNode>[]; // SCCs formed by only hard edges (regular dependencies)\n};\n\nexport type SCCDAG = {\n  sccList: SCC[];\n  sccGraph: Map<number, Set<number>>; // Adjacency list of SCC dependencies\n};\n\nexport type EvaluationOrder = {\n  evaluationOrder: Set<DependencyNode>;\n  hasCycle: boolean;\n  cycleNodes?: Set<DependencyNode>;\n  hash: string;\n  sccDAG?: SCCDAG;\n};\n\n// Conditional Styling types\nexport interface LCHColor {\n  l: number; // Lightness: 0-100\n  c: number; // Chroma: 0-150+\n  h: number; // Hue: 0-360\n}\n\nexport interface FormulaStyleCondition {\n  type: \"formula\";\n  formula: string;\n  color: LCHColor;\n}\n\nexport interface GradientStyleCondition {\n  type: \"gradient\";\n  min:\n    | { type: \"lowest_value\"; color: LCHColor }\n    | { type: \"number\"; color: LCHColor; valueFormula: string };\n  max:\n    | { type: \"highest_value\"; color: LCHColor }\n    | { type: \"number\"; color: LCHColor; valueFormula: string };\n}\n\nexport type StyleCondition = FormulaStyleCondition | GradientStyleCondition;\n\nexport interface ConditionalStyle {\n  areas: RangeAddress[];\n  condition: StyleCondition;\n}\n\nexport interface DirectCellStyle {\n  areas: RangeAddress[];\n  style: CellStyle;\n}\n\nexport interface RangeMetadata<TMetadata = unknown> {\n  id: string;\n  areas: RangeAddress[];\n  metadata: TMetadata;\n}\n\nexport interface RangeMetadataInput<TMetadata = unknown> {\n  id?: string;\n  areas: RangeAddress[];\n  metadata: TMetadata;\n}\n\nexport interface CellStyle {\n  backgroundColor?: string; // Hex color format\n  color?: string; // Text color in hex format\n  fontSize?: number; // Font size in pixels\n  bold?: boolean;\n  italic?: boolean;\n  underline?: boolean;\n  wrapText?: boolean;\n}\n\nexport type CopyCellsIncludePart =\n  | \"content\"\n  | \"style\"\n  | \"cellMetadata\"\n  | \"rangeMetadata\";\n\nexport interface CopyCellsOptions {\n  /**\n   * Whether this is a cut operation (clears source cells after copying)\n   * @default false\n   */\n  cut?: boolean;\n  /**\n   * What to include in the copy operation.\n   * - Use 'all' as shorthand for ['content', 'style', 'cellMetadata', 'rangeMetadata']\n   * - Use array for fine-grained control over what to copy:\n   *   - ['content'] - copy only values/formulas\n   *   - ['style'] - copy only formatting\n   *   - ['cellMetadata'] - copy only cell metadata (rich text, links, etc.)\n   *   - ['rangeMetadata'] - copy only range metadata\n   *   - ['content', 'style'] - copy content and formatting\n   *   - ['content', 'cellMetadata'] - copy content and cell metadata\n   *   - ['style', 'rangeMetadata'] - copy formatting and range metadata\n   *   - ['content', 'style', 'cellMetadata', 'rangeMetadata'] - same as 'all'\n   * @default 'all'\n   */\n  include?: \"all\" | CopyCellsIncludePart[];\n  /**\n   * The type of the content to copy\n   * value: Copy the value from the source to the target,\n   * e.g. if the cell has the formula =123 + 123 then the value is 246\n   * formula: Copy the formula from the source to the target,\n   * e.g. if the cell has the formula =123 + 123 then the formula is =123 + 123 is copied\n   * @default 'formula'\n   */\n  type?: \"value\" | \"formula\";\n}\n"
   ],
   "mappings": ";AAkKO,IAAK;AAAA,CAAL,CAAK,kBAAL;AAAA,EACL,wBAAO;AAAA,EACP,sBAAK;AAAA,EACL,wBAAO;AAAA,EACP,uBAAM;AAAA,EACN,uBAAM;AAAA,EACN,yBAAQ;AAAA,EACR,yBAAQ;AAAA,EACR,yBAAQ;AAAA,EACR,yBAAQ;AAAA,GATE;",
   "debugId": "0E7C5AF634572D3964756E2164756E21",

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/formula-engine",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "type": "module"
 }

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

@@ -5,10 +5,12 @@ import type { SpreadsheetRange } from "./types";
 import type { FillDirection } from "@ricsam/selection-manager";
 import type { WorkbookManager } from "./managers/workbook-manager";
 import type { StyleManager } from "./managers/style-manager";
+import type { RangeMetadataManager } from "./managers/range-metadata-manager";
 export declare class AutoFill {
     private workbookManager;
     private styleManager;
-    constructor(workbookManager: WorkbookManager, styleManager: StyleManager);
+    private rangeMetadataManager;
+    constructor(workbookManager: WorkbookManager, styleManager: StyleManager, rangeMetadataManager: RangeMetadataManager);
     /**
      * Converts a SpreadsheetRange to FiniteSpreadsheetRange, throwing an error if infinite
      */
@@ -37,4 +39,8 @@ export declare class AutoFill {
      * Copy metadata from seed range to fill range with pattern repetition
      */
     private fillMetadata;
+    /**
+     * Copy range metadata from seed range to fill range with pattern repetition.
+     */
+    private fillRangeMetadata;
 }

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

@@ -1,7 +1,7 @@
 import type { ContextDependency } from "../evaluator/evaluation-context";
 import type { DependencyNode } from "./managers/dependency-node";
-import type { CellAddress, CellInRangeResult, CellValue, ConditionalStyle, DirectCellStyle, FormulaError, NamedExpression, RangeAddress, RelativeRange, SpreadsheetRange, TableDefinition, TrackedReference, Workbook } from "./types";
-export declare const ENGINE_SNAPSHOT_VERSION: 4;
+import type { CellAddress, CellInRangeResult, CellValue, ConditionalStyle, DirectCellStyle, FormulaError, NamedExpression, RangeAddress, RangeMetadata, RelativeRange, SpreadsheetRange, TableDefinition, TrackedReference, Workbook } from "./types";
+export declare const ENGINE_SNAPSHOT_VERSION: 5;
 export type NodeSnapshotId = string;
 export type NamedExpressionManagerSnapshot = {
     sheetExpressions: Map<string, Map<string, Map<string, NamedExpression>>>;
@@ -14,6 +14,7 @@ export type StyleManagerSnapshot = {
     conditionalStyles: ConditionalStyle[];
     cellStyles: DirectCellStyle[];
 };
+export type RangeMetadataManagerSnapshot = RangeMetadata[];
 export type ReferenceManagerSnapshot = Map<string, TrackedReference>;
 export type SerializedValueEvaluationResultSnapshot = {
     type: "value";
@@ -124,6 +125,7 @@ type EngineSnapshotManagers = {
     namedExpression: NamedExpressionManagerSnapshot;
     table: TableManagerSnapshot;
     style: StyleManagerSnapshot;
+    rangeMetadata: RangeMetadataManagerSnapshot;
     reference: ReferenceManagerSnapshot;
     dependency: DependencyManagerSnapshot;
     cache: CacheManagerSnapshot;

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

@@ -2,7 +2,7 @@
  * Main FormulaEngine class
  * Core API implementation for spreadsheet calculations
  */
-import { type CellAddress, type CellStyle, type ConditionalStyle, type CopyCellsOptions, type DirectCellStyle, type NamedExpression, type RangeAddress, type ReplaceChange, type ReplaceTarget, type SearchMatch, type SearchOptions, type SerializedCellValue, type Sheet, type SingleEvaluationResult, type SpreadsheetRange, type SpreadsheetRangeEnd, type TableDefinition } from "./types";
+import { type CellAddress, type CellStyle, type ConditionalStyle, type CopyCellsOptions, type DirectCellStyle, type NamedExpression, type RangeAddress, type RangeMetadata, type RangeMetadataInput, type ReplaceChange, type ReplaceTarget, type SearchMatch, type SearchOptions, type SerializedCellValue, type Sheet, 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";
@@ -12,8 +12,10 @@ 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 { RangeMetadataManager } from "./managers/range-metadata-manager";
 type Metadata = {
     cell?: unknown;
+    range?: unknown;
     sheet?: unknown;
     workbook?: unknown;
 };
@@ -31,6 +33,7 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata> {
     private autoFillManager;
     private dependencyManager;
     private styleManager;
+    private rangeMetadataManager;
     private copyManager;
     private referenceManager;
     /**
@@ -44,6 +47,7 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata> {
     _autoFillManager: AutoFill;
     _dependencyManager: DependencyManager;
     _styleManager: StyleManager;
+    _rangeMetadataManager: RangeMetadataManager<MetadataType<TMetadata, "range">>;
     constructor();
     /**
      * Static factory method to build an empty engine
@@ -98,6 +102,32 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata> {
      * Get metadata for a workbook
      */
     getWorkbookMetadata(workbookName: string): MetadataType<TMetadata, "workbook"> | undefined;
+    /**
+     * Add metadata attached to one or more ranges.
+     * Range metadata is arbitrary consumer-defined data that follows range
+     * copy/paste, autofill, workbook/sheet rename, and serialization flows.
+     */
+    addRangeMetadata(metadata: RangeMetadataInput<MetadataType<TMetadata, "range">>): string;
+    /**
+     * Remove a range metadata entry by id.
+     */
+    removeRangeMetadata(id: string): void;
+    /**
+     * Get all range metadata entries.
+     */
+    getAllRangeMetadata(): RangeMetadata<MetadataType<TMetadata, "range">>[];
+    /**
+     * Get range metadata entries that apply to a specific cell.
+     */
+    getRangeMetadataForCell(address: CellAddress): RangeMetadata<MetadataType<TMetadata, "range">>[];
+    /**
+     * Get range metadata entries intersecting with a range.
+     */
+    getRangeMetadataIntersectingWithRange(range: RangeAddress): RangeMetadata<MetadataType<TMetadata, "range">>[];
+    /**
+     * Clear range metadata from a range, preserving non-overlapping portions.
+     */
+    clearRangeMetadata(range: RangeAddress): void;
     /**
      * Create a tracked reference to a range
      * Returns a stable UUID that can be used to retrieve the address later
@@ -487,6 +517,7 @@ export declare class FormulaEngine<TMetadata extends Metadata = Metadata> {
         tables: Map<string, Map<string, TableDefinition>>;
         conditionalStyles: ConditionalStyle[];
         cellStyles: DirectCellStyle[];
+        rangeMetadata: RangeMetadata<MetadataType<TMetadata, "range">>[];
         references: Map<string, import("./types").TrackedReference>;
     };
     onUpdate(listener: () => void): () => void;

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

@@ -5,11 +5,13 @@ import type { CellAddress, CopyCellsOptions, RangeAddress } from "../types";
 import type { WorkbookManager } from "./workbook-manager";
 import type { EvaluationManager } from "./evaluation-manager";
 import type { StyleManager } from "./style-manager";
+import type { RangeMetadataManager } from "./range-metadata-manager";
 export declare class CopyManager {
     private workbookManager;
     private evaluationManager;
     private styleManager;
-    constructor(workbookManager: WorkbookManager, evaluationManager: EvaluationManager, styleManager: StyleManager);
+    private rangeMetadataManager;
+    constructor(workbookManager: WorkbookManager, evaluationManager: EvaluationManager, styleManager: StyleManager, rangeMetadataManager: RangeMetadataManager);
     /**
      * Normalize the include option to an array of parts to copy
      */
@@ -60,6 +62,7 @@ export declare class CopyManager {
      * Copy content from a cell snapshot to a target cell
      */
     private copyCellContentFromSnapshot;
+    private copyCellMetadataFromSnapshot;
     /**
      * Update all formula references when cells are cut (moved)
      */
@@ -77,6 +80,11 @@ export declare class CopyManager {
      * Clears existing cell styles in target range first (Excel behavior)
      */
     private copyFormatting;
+    private cloneMetadataValue;
+    private getRangeAddressFromBoundingBox;
+    private collectRangeMetadataCopies;
+    private applyRangeMetadataCopies;
+    private copyRangeMetadata;
     /**
      * Get bounding box for a set of cells
      */
@@ -123,6 +131,8 @@ export declare class CopyManager {
      * Adjust formula references by a specific row/column offset
      */
     private adjustFormulaWithOffset;
+    private copyCellMetadata;
+    private copyCellRangeMetadata;
     /**
      * Copy formatting from one cell to another
      * Clears existing cell styles at target (Excel behavior) before copying new ones

package/dist/types/core/managers/range-metadata-manager.d.ts

@@ -0,0 +1,22 @@
+/**
+ * RangeMetadataManager - Manages arbitrary consumer-defined metadata attached
+ * to ranges rather than individual cells.
+ */
+import type { CellAddress, RangeAddress, RangeMetadata, RangeMetadataInput } from "../types";
+import type { RangeMetadataManagerSnapshot } from "../engine-snapshot";
+export declare class RangeMetadataManager<TMetadata = unknown> {
+    private rangeMetadata;
+    addRangeMetadata(entry: RangeMetadataInput<TMetadata>): string;
+    removeRangeMetadata(id: string): boolean;
+    getAllRangeMetadata(): RangeMetadata<TMetadata>[];
+    getRangeMetadataForCell(cellAddress: CellAddress): RangeMetadata<TMetadata>[];
+    getRangeMetadataIntersectingWithRange(range: RangeAddress): RangeMetadata<TMetadata>[];
+    clearRangeMetadataInRange(range: RangeAddress): void;
+    removeWorkbookRangeMetadata(workbookName: string): void;
+    removeSheetRangeMetadata(workbookName: string, sheetName: string): void;
+    updateWorkbookName(oldName: string, newName: string): void;
+    updateSheetName(workbookName: string, oldSheetName: string, newSheetName: string): void;
+    resetRangeMetadata(rangeMetadata?: RangeMetadata<TMetadata>[]): void;
+    toSnapshot(): RangeMetadataManagerSnapshot;
+    restoreFromSnapshot(snapshot: RangeMetadataManagerSnapshot): void;
+}

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

@@ -371,6 +371,16 @@ export interface DirectCellStyle {
     areas: RangeAddress[];
     style: CellStyle;
 }
+export interface RangeMetadata<TMetadata = unknown> {
+    id: string;
+    areas: RangeAddress[];
+    metadata: TMetadata;
+}
+export interface RangeMetadataInput<TMetadata = unknown> {
+    id?: string;
+    areas: RangeAddress[];
+    metadata: TMetadata;
+}
 export interface CellStyle {
     backgroundColor?: string;
     color?: string;
@@ -378,7 +388,9 @@ export interface CellStyle {
     bold?: boolean;
     italic?: boolean;
     underline?: boolean;
+    wrapText?: boolean;
 }
+export type CopyCellsIncludePart = "content" | "style" | "cellMetadata" | "rangeMetadata";
 export interface CopyCellsOptions {
     /**
      * Whether this is a cut operation (clears source cells after copying)
@@ -387,18 +399,19 @@ export interface CopyCellsOptions {
     cut?: boolean;
     /**
      * What to include in the copy operation.
-     * - Use 'all' as shorthand for ['content', 'style', 'metadata']
+     * - Use 'all' as shorthand for ['content', 'style', 'cellMetadata', 'rangeMetadata']
      * - 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.)
+     *   - ['cellMetadata'] - copy only cell metadata (rich text, links, etc.)
+     *   - ['rangeMetadata'] - copy only range metadata
      *   - ['content', 'style'] - copy content and formatting
-     *   - ['content', 'metadata'] - copy content and metadata
-     *   - ['style', 'metadata'] - copy formatting and metadata
-     *   - ['content', 'style', 'metadata'] - same as 'all'
+     *   - ['content', 'cellMetadata'] - copy content and cell metadata
+     *   - ['style', 'rangeMetadata'] - copy formatting and range metadata
+     *   - ['content', 'style', 'cellMetadata', 'rangeMetadata'] - same as 'all'
      * @default 'all'
      */
-    include?: "all" | ("content" | "style" | "metadata")[];
+    include?: "all" | CopyCellsIncludePart[];
     /**
      * The type of the content to copy
      * value: Copy the value from the source to the target,

package/package.json

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