y11n-spreadsheet 1.0.1 → 1.1.0

package/README.md

@@ -4,10 +4,13 @@ An accessible spreadsheet web component built with [Lit 3.0](https://lit.dev). I
 
 ## Features
 
-- Full keyboard navigation (arrows, Tab, Enter, Escape, Ctrl+A)
+- Full keyboard navigation (arrows, Ctrl+Arrow data-edge jumps, Tab, Enter, Escape, Ctrl+A)
+- Row/column selection via headers (click, Shift+click, drag) or Ctrl+Space / Shift+Space
+- Fill down/right (Ctrl+D / Ctrl+R) and multi-cell entry (Ctrl+Enter)
+- CSV/TSV import and export
 - Copy/cut/paste with TSV clipboard format
-- Undo/redo with Ctrl+Z / Ctrl+Shift+Z
-- Formula engine with 20+ built-in functions and custom function support
+- Undo/redo with Ctrl+Z / Ctrl+Shift+Z (or Ctrl+Y)
+- Formula engine with 50+ built-in functions and custom function support
 - Arrow key cell reference insertion during formula editing
 - Virtual rendering for large datasets (1000+ rows)
 - Dual-mode formula bar (raw / formatted)
@@ -74,8 +77,36 @@ sheet.setData(data);
 sheet.getData()          // Returns a copy of the grid data
 sheet.setData(data)      // Replaces grid data (clears undo/redo)
 sheet.registerFunction('DOUBLE', (ctx, val) => Number(val) * 2)
+
+// Formatting
+sheet.setCellFormat('0:0', { bold: true, verticalAlign: 'top', wrap: true })
+sheet.setRangeFormat({ start: { row: 1, col: 1 }, end: { row: 9, col: 1 } },
+  { numberFormat: { type: 'date', datePattern: 'DD/MM/YYYY' } })
+
+// CSV / TSV
+sheet.toCSV()                                   // display values, A1 → last used cell
+sheet.toCSV({ values: 'raw', delimiter: '\t' }) // formulas, as TSV
+sheet.toCSV({ range: { start: { row: 0, col: 0 }, end: { row: 9, col: 3 } } })
+sheet.fromCSV(text)                             // write at A1 (undoable)
+sheet.fromCSV(text, { start: { row: 5, col: 0 }, delimiter: ';' })
 ```
 
+`fromCSV` drops values outside `rows` × `cols` (and throws a `RangeError` for a negative or non-integer `start`); use the exported `parseDelimited(text)` to size the grid first if needed.
+
+### Cell formats
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `bold`, `italic`, `underline`, `strikethrough` | `boolean` | Text styling |
+| `textColor`, `backgroundColor` | `string` | CSS colors |
+| `textAlign` | `'left' \| 'center' \| 'right'` | Horizontal alignment |
+| `verticalAlign` | `'top' \| 'middle' \| 'bottom'` | Vertical alignment (default middle) |
+| `wrap` | `boolean` | Wrap text instead of truncating. Rows keep their fixed height, so only the lines that fit are shown |
+| `fontSize` | `number` | Font size in px |
+| `numberFormat` | `NumberFormatOptions` | `{ type: 'number' \| 'currency' \| 'percent' \| 'scientific' \| 'date', decimals?, currencySymbol?, thousandsSep?, datePattern? }` |
+
+The `date` type renders date serial numbers (as returned by `DATE`, `TODAY`, `NOW`) using `datePattern` (default `YYYY-MM-DD`; tokens `YYYY YY MM M DD D HH H mm ss`).
+
 ### Events
 
 ```js
@@ -89,7 +120,7 @@ sheet.addEventListener('selection-change', (e) => {
   console.log(e.detail.range); // { start: { row, col }, end: { row, col } }
 });
 
-// Bulk operation (paste, cut, clear, undo, redo)
+// Bulk operation (paste, cut, clear, fill, import, undo, redo)
 sheet.addEventListener('data-change', (e) => {
   console.log(e.detail.updates, e.detail.source, e.detail.operation);
 });
@@ -107,10 +138,15 @@ Formulas start with `=`. Supported syntax:
 
 | Category | Functions |
 |----------|-----------|
-| Aggregates | `SUM`, `AVERAGE`, `MIN`, `MAX`, `COUNT`, `COUNTA` |
-| Conditional | `IF(condition, trueVal, falseVal)` |
-| Math | `ABS`, `ROUND` |
-| String | `CONCAT`, `UPPER`, `LOWER`, `LEN`, `TRIM` |
+| Aggregates | `SUM`, `AVERAGE`, `MIN`, `MAX`, `COUNT`, `COUNTA`, `PRODUCT`, `MEDIAN` |
+| Conditional aggregates | `SUMIF`, `COUNTIF`, `AVERAGEIF`, `SUMIFS`, `COUNTIFS`, `AVERAGEIFS` |
+| Logic | `IF`, `IFS`, `IFERROR`, `AND`, `OR`, `NOT` |
+| Lookup | `VLOOKUP`, `HLOOKUP`, `XLOOKUP`, `INDEX`, `MATCH` |
+| Math | `ABS`, `ROUND`, `ROUNDUP`, `ROUNDDOWN`, `INT`, `MOD`, `POWER`, `SQRT`, `CEILING`, `FLOOR` |
+| Text | `CONCAT`, `TEXTJOIN`, `UPPER`, `LOWER`, `LEN`, `TRIM`, `LEFT`, `RIGHT`, `MID`, `SUBSTITUTE`, `FIND`, `TEXT`, `VALUE` |
+| Date | `DATE`, `TODAY`, `NOW`, `YEAR`, `MONTH`, `DAY`, `WEEKDAY` |
+
+Omitted arguments use their defaults, e.g. `=XLOOKUP(75, A1:A9, B1:B9, , -1)`. Criteria in `SUMIF`/`COUNTIF`/`AVERAGEIF` and the `*IFS` functions accept operators (`">5"`, `"<>x"`) and wildcards (`*`, `?`, `~` to escape). `XLOOKUP` supports match modes `0`, `-1`, `1` (not wildcard mode `2`) and search modes `1`/`-1`; it returns a single value (no spilling).
 
 **Custom functions**:
 
@@ -163,6 +199,7 @@ y11n-spreadsheet {
 | `--ls-formula-mode-active-bg` | `#dbeafe` | Active mode toggle background |
 | `--ls-ref-highlight-border` | `#1a73e8` | Reference highlight border |
 | `--ls-ref-highlight-bg` | `rgba(26, 115, 232, 0.15)` | Reference highlight fill |
+| `--ls-header-selected-bg` | `#dbe7fb` | Row/column header background for selected rows/columns |
 
 </details>
 
@@ -180,14 +217,22 @@ y11n-spreadsheet::part(editor) {
 |-----|--------|
 | Arrow keys | Move active cell |
 | Shift + Arrow | Extend selection |
+| Ctrl/Cmd + Arrow | Jump to the edge of the data region |
+| Ctrl/Cmd + Shift + Arrow | Extend selection to the edge of the data region |
+| Ctrl + Space | Select entire column(s) |
+| Shift + Space | Select entire row(s) |
+| Ctrl + Shift + Space, Ctrl+A | Select all |
 | Tab / Shift+Tab | Move right / left |
-| Enter | Start editing / commit edit |
+| Enter / Shift+Enter (editing) | Commit edit and move down / up |
+| Ctrl/Cmd + Enter (editing) | Commit the value into every selected cell |
+| Enter, F2 | Start editing |
 | Escape | Cancel edit / clear selection |
 | Delete, Backspace | Clear selected cells |
-| Ctrl+A | Select all |
+| Ctrl/Cmd + D | Fill down (copy the top row of the selection into the rest) |
+| Ctrl/Cmd + R | Fill right (copy the left column of the selection into the rest) |
 | Ctrl+C / X / V | Copy / Cut / Paste |
 | Ctrl+Z | Undo |
-| Ctrl+Shift+Z | Redo |
+| Ctrl+Shift+Z / Ctrl+Y | Redo |
 | Any printable character | Start editing with that character |
 
 During formula editing, arrow keys insert cell references instead of navigating.
@@ -210,7 +255,7 @@ import type {
 } from 'y11n-spreadsheet';
 ```
 
-Utility functions for coordinate conversion:
+Utility functions for coordinate conversion, dates, and delimited text:
 
 ```ts
 import { cellKey, parseKey, colToLetter, letterToCol, refToCoord, coordToRef } from 'y11n-spreadsheet';
@@ -221,6 +266,12 @@ colToLetter(0)        // "A"
 letterToCol("AA")     // 26
 refToCoord("B3")      // { row: 2, col: 1 }
 coordToRef({row:0, col:0}) // "A1"
+
+import { dateToSerial, dateSerialToDate, parseDelimited, serializeDelimited } from 'y11n-spreadsheet';
+
+dateToSerial(2024, 0, 1)          // 45292 (month is 0-indexed)
+parseDelimited('a,"b,c"\n1,2')    // [['a', 'b,c'], ['1', '2']]
+serializeDelimited([['a', 'b,c']]) // 'a,"b,c"'
 ```
 
 ## Exports
@@ -282,9 +333,11 @@ src/
   components/y11n-formula-bar.ts    # Formula bar sub-component
   controllers/
     selection-manager.ts            # Selection state (Lit ReactiveController)
-    clipboard-manager.ts            # Clipboard operations (TSV format)
+    clipboard-manager.ts            # Clipboard operations (TSV + HTML formats)
   engine/
     formula-engine.ts               # Recursive descent formula parser
+  utils/
+    delimited.ts                    # CSV/TSV parsing and serialization
   __tests__/                        # Unit tests colocated with source
 e2e/                                # Playwright E2E tests
 stories/                            # Storybook stories

package/dist/components/y11n-format-toolbar.d.ts

@@ -1,13 +1,17 @@
 import { LitElement } from 'lit';
+/** Detail for the `format-action` custom event dispatched by the format toolbar. */
 export interface FormatActionDetail {
+    /** The formatting action to perform */
     action: 'bold' | 'italic' | 'underline' | 'strikethrough' | 'textColor' | 'backgroundColor' | 'textAlign' | 'fontSize' | 'clearFormat';
+    /** The new value for the action (e.g. true/false for toggles, color string, font size number) */
     value?: string | number | boolean;
 }
 /**
- * <y11n-format-toolbar> - A companion toolbar for cell formatting.
+ * `<y11n-format-toolbar>` -- A companion toolbar for cell formatting.
  *
- * Connected to <y11n-spreadsheet> via properties and events.
- * Consumer wires them together:
+ * This component does not manage state internally. The consumer wires it
+ * to `<y11n-spreadsheet>` by binding selection-derived properties and
+ * handling the `format-action` event:
  *
  * ```html
  * <y11n-format-toolbar
@@ -15,6 +19,8 @@ export interface FormatActionDetail {
  *   @format-action=${handle}
  * ></y11n-format-toolbar>
  * ```
+ *
+ * @fires format-action - Dispatched when the user clicks a formatting button or changes a value
  */
 export declare class Y11nFormatToolbar extends LitElement {
     bold: boolean;
@@ -31,7 +37,14 @@ export declare class Y11nFormatToolbar extends LitElement {
     private _handleToolbarKeydown;
     render(): import("lit-html").TemplateResult<1>;
 }
-/** Compute consensus format from a selection range */
+/**
+ * Compute the consensus format from all cells in a selection range.
+ * For each property, returns the common value if all cells agree, or undefined if mixed.
+ *
+ * @param getData - Callback to retrieve cell data by key
+ * @param range - The selection range to inspect
+ * @returns A CellFormat with only the unanimously shared properties set
+ */
 export declare function computeSelectionFormat(getData: (cellId: string) => {
     format?: import('../types.js').CellFormat;
 } | undefined, range: import('../types.js').SelectionRange): import('../types.js').CellFormat;

package/dist/components/y11n-format-toolbar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"y11n-format-toolbar.d.ts","sourceRoot":"","sources":["../../src/components/y11n-format-toolbar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,KAAK,CAAC;AAG5C,MAAM,WAAW,kBAAkB;IACjC,MAAM,EACF,MAAM,GACN,QAAQ,GACR,WAAW,GACX,eAAe,GACf,WAAW,GACX,iBAAiB,GACjB,WAAW,GACX,UAAU,GACV,aAAa,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,qBACa,iBAAkB,SAAQ,UAAU;IAGlB,IAAI,UAAS;IACb,MAAM,UAAS;IACf,SAAS,UAAS;IAClB,aAAa,UAAS;IACvB,SAAS,SAAa;IACtB,eAAe,SAAa;IAC5B,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAU;IAChD,QAAQ,SAAM;IAC0B,QAAQ,UAAS;IAIrF,MAAM,CAAC,MAAM,0BAiKX;IAIF,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,qBAAqB;IAgC7B,MAAM;CAuJP;AAED,sDAAsD;AACtD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK;IAAE,MAAM,CAAC,EAAE,OAAO,aAAa,EAAE,UAAU,CAAA;CAAE,GAAG,SAAS,EACtF,KAAK,EAAE,OAAO,aAAa,EAAE,cAAc,GAC1C,OAAO,aAAa,EAAE,UAAU,CAkDlC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,qBAAqB,EAAE,iBAAiB,CAAC;KAC1C;CACF"}
+{"version":3,"file":"y11n-format-toolbar.d.ts","sourceRoot":"","sources":["../../src/components/y11n-format-toolbar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,KAAK,CAAC;AAG5C,oFAAoF;AACpF,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,MAAM,EACF,MAAM,GACN,QAAQ,GACR,WAAW,GACX,eAAe,GACf,WAAW,GACX,iBAAiB,GACjB,WAAW,GACX,UAAU,GACV,aAAa,CAAC;IAClB,iGAAiG;IACjG,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBACa,iBAAkB,SAAQ,UAAU;IAGlB,IAAI,UAAS;IACb,MAAM,UAAS;IACf,SAAS,UAAS;IAClB,aAAa,UAAS;IACvB,SAAS,SAAa;IACtB,eAAe,SAAa;IAC5B,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAU;IAChD,QAAQ,SAAM;IAC0B,QAAQ,UAAS;IAIrF,MAAM,CAAC,MAAM,0BAiKX;IAIF,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,qBAAqB;IAgC7B,MAAM,yCAsJL;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK;IAAE,MAAM,CAAC,EAAE,OAAO,aAAa,EAAE,UAAU,CAAA;CAAE,GAAG,SAAS,EACtF,KAAK,EAAE,OAAO,aAAa,EAAE,cAAc,GAC1C,OAAO,aAAa,EAAE,UAAU,CAkDlC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,qBAAqB,EAAE,iBAAiB,CAAC;KAC1C;CACF"}

package/dist/components/y11n-formula-bar.d.ts

@@ -1,8 +1,16 @@
 import { LitElement } from 'lit';
+/** Display mode for the formula bar input. */
 export type FormulaBarMode = 'raw' | 'formatted';
 /**
- * Reusable formula bar that supports raw/formatted value display.
- * Emits commit + mode-change events and leaves data persistence to parent components.
+ * `<y11n-formula-bar>` -- Reusable formula bar sub-component.
+ *
+ * Displays the active cell reference and an input for editing cell values.
+ * Supports toggling between raw (formula) and formatted (display) modes.
+ * All data persistence is handled by the parent component; this component
+ * communicates via two custom events:
+ *
+ * @fires formula-bar-commit - Fired on Enter or blur when the draft differs from the source value
+ * @fires formula-bar-mode-change - Fired when the user toggles between raw and formatted mode
  */
 export declare class Y11nFormulaBar extends LitElement {
     cellRef: string;
@@ -11,7 +19,6 @@ export declare class Y11nFormulaBar extends LitElement {
     mode: FormulaBarMode;
     readOnly: boolean;
     private _draft;
-    private _suppressNextBlur;
     static styles: import("lit").CSSResult;
     willUpdate(changedProps: Map<string, unknown>): void;
     private _sourceValue;

package/dist/components/y11n-formula-bar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"y11n-formula-bar.d.ts","sourceRoot":"","sources":["../../src/components/y11n-formula-bar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,KAAK,CAAC;AAG5C,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,WAAW,CAAC;AAUjD;;;GAGG;AACH,qBACa,cAAe,SAAQ,UAAU;IACO,OAAO,SAAQ;IACd,QAAQ,SAAM;IACV,YAAY,SAAM;IAC9C,IAAI,EAAE,cAAc,CAAS;IACW,QAAQ,UAAS;IAE5E,OAAO,CAAC,MAAM,CAAM;IAC7B,OAAO,CAAC,iBAAiB,CAAS;IAElC,MAAM,CAAC,MAAM,0BAuEX;IAEF,UAAU,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAUpD,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,OAAO;IAQf,MAAM;CA8BP;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,kBAAkB,EAAE,cAAc,CAAC;KACpC;CACF"}
+{"version":3,"file":"y11n-formula-bar.d.ts","sourceRoot":"","sources":["../../src/components/y11n-formula-bar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,KAAK,CAAC;AAG5C,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,WAAW,CAAC;AAgBjD;;;;;;;;;;GAUG;AACH,qBACa,cAAe,SAAQ,UAAU;IACO,OAAO,SAAQ;IACd,QAAQ,SAAM;IACV,YAAY,SAAM;IAC9C,IAAI,EAAE,cAAc,CAAS;IACW,QAAQ,UAAS;IAE5E,OAAO,CAAC,MAAM,CAAM;IAE7B,MAAM,CAAC,MAAM,0BAuEX;IAEF,UAAU,CAAC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAQnD;IAED,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ;IAWhB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,OAAO;IAMf,MAAM,yCA6BL;CACF;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,kBAAkB,EAAE,cAAc,CAAC;KACpC;CACF"}

package/dist/controllers/clipboard-manager.d.ts

@@ -1,7 +1,11 @@
 import { type CellFormat, type GridData, type SelectionRange } from '../types.js';
+/** A single cell update produced by a paste operation. */
 export interface PasteUpdate {
+    /** Cell key in `"row:col"` format */
     id: string;
+    /** Raw value to write to the cell */
     value: string;
+    /** Optional format to apply (from HTML or internal paste) */
     format?: CellFormat;
 }
 /**
@@ -12,20 +16,35 @@ export declare class ClipboardManager {
     /** Source range and data from the last internal copy/cut, used for reference adjustment on paste */
     private _copySourceRange;
     private _copySourceData;
+    /** The TSV text we last wrote to the clipboard, used to detect external overwrites */
+    private _lastWrittenText;
     /**
-     * Copy the selected range to the clipboard as both HTML table and TSV.
-     * Falls back to text-only if ClipboardItem API is unavailable.
+     * Copy the selected range to the system clipboard.
+     * Writes two formats: `text/html` (table with inline styles and data-format attributes)
+     * and `text/plain` (TSV). Falls back to text-only if ClipboardItem API is unavailable.
+     *
+     * @param data - The grid data to read cell values from
+     * @param range - The rectangular range to copy
      */
     copy(data: GridData, range: SelectionRange): Promise<void>;
     /**
-     * Cut: copy to clipboard and return the keys that should be cleared.
+     * Cut: copy to clipboard and return the cell keys that should be cleared by the caller.
+     *
+     * @param data - The grid data to read cell values from
+     * @param range - The rectangular range to cut
+     * @returns Array of cell keys (in `"row:col"` format) that were included in the cut
      */
     cut(data: GridData, range: SelectionRange): Promise<string[]>;
     /**
-     * Parse clipboard content and return the updates to apply.
-     * If data was copied internally, uses raw values with reference adjustment.
-     * Otherwise tries HTML table format first, then falls back to TSV text.
-     * The target is the top-left cell where paste begins.
+     * Read from the system clipboard and return cell updates for pasting.
+     * Priority chain: internal copy data (with formula reference adjustment)
+     * -> HTML table -> plain text TSV.
+     *
+     * @param targetRow - 0-indexed row of the top-left paste destination
+     * @param targetCol - 0-indexed column of the top-left paste destination
+     * @param maxRows - Grid row count (for bounds clamping)
+     * @param maxCols - Grid column count (for bounds clamping)
+     * @returns Array of cell updates to apply, or null if clipboard is empty/inaccessible
      */
     paste(targetRow: number, targetCol: number, maxRows: number, maxCols: number): Promise<PasteUpdate[] | null>;
     /**
@@ -49,28 +68,32 @@ export declare class ClipboardManager {
      * Parse a TSV string and generate cell updates.
      * Handles RFC 4180-style quoting: fields containing tabs, newlines, or
      * double-quotes are wrapped in double-quotes, with internal quotes escaped
-     * as "". This is the format Excel and Google Sheets use on the clipboard.
+     * as `""`. This is the format Excel and Google Sheets use on the clipboard.
      *
-     * Exported for testability with paste events where text is already available.
+     * @param text - The TSV text to parse
+     * @param targetRow - 0-indexed row of the top-left paste destination
+     * @param targetCol - 0-indexed column of the top-left paste destination
+     * @param maxRows - Grid row count (for bounds clamping)
+     * @param maxCols - Grid column count (for bounds clamping)
+     * @returns Array of cell updates with keys and values
      */
     parseTSV(text: string, targetRow: number, targetCol: number, maxRows: number, maxCols: number): Array<{
         id: string;
         value: string;
     }>;
-    /**
-     * Parse TSV text into a 2D array of strings, respecting quoted fields.
-     * Quoted fields may contain tabs, newlines, and escaped quotes ("").
-     */
-    private _parseTSVRows;
     /**
      * Adjust cell references in a formula by the given row/col offset.
-     * Absolute references ($A$1) are not adjusted.
-     * Mixed references ($A1, A$1) only adjust the non-absolute part.
+     * Absolute references (`$A$1`) are not adjusted.
+     * Mixed references (`$A1`, `A$1`) only adjust the non-absolute component.
+     * References inside string literals are left untouched.
+     *
+     * @param formula - The formula string (must start with "=")
+     * @param rowOffset - Number of rows to shift relative references
+     * @param colOffset - Number of columns to shift relative references
+     * @returns The adjusted formula string, with `#REF!` for out-of-bounds refs
      */
     adjustFormulaReferences(formula: string, rowOffset: number, colOffset: number): string;
     private serializeRange;
-    /** Quote a TSV field if it contains tabs, newlines, or double-quotes */
-    private _quoteTSVField;
     /**
      * Convert a selection range to an HTML table string.
      * Includes inline styles for visual formatting and data-format for lossless round-trip.
@@ -82,6 +105,7 @@ export declare class ClipboardManager {
     private _parseStyleToFormat;
     /** Validate and sanitize a parsed CellFormat from an external source */
     private _sanitizeFormat;
+    private _sanitizeNumberFormat;
     private _extractStyleProp;
     /** Escape special HTML characters */
     private _escapeHTML;

package/dist/controllers/clipboard-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clipboard-manager.d.ts","sourceRoot":"","sources":["../../src/controllers/clipboard-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,cAAc,EAIpB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,oGAAoG;IACpG,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,eAAe,CAAyB;IAEhD;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBhE;;OAEG;IACG,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAWnE;;;;;OAKG;IACG,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC;IAmChC;;;OAGG;IACH,OAAO,CAAC,cAAc;IAuCtB;;;OAGG;IACH,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC,GAAG,IAAI;IA4CnG;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAuBlC;;;;;;;OAOG;IACH,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBvC;;;OAGG;IACH,OAAO,CAAC,aAAa;IAqErB;;;;OAIG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IA4BtF,OAAO,CAAC,cAAc;IAgBtB,wEAAwE;IACxE,OAAO,CAAC,cAAc;IAOtB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAgC7B,sDAAsD;IACtD,OAAO,CAAC,oBAAoB;IAe5B,2FAA2F;IAC3F,OAAO,CAAC,mBAAmB;IAsC3B,wEAAwE;IACxE,OAAO,CAAC,eAAe;IA6BvB,OAAO,CAAC,iBAAiB;IAQzB,qCAAqC;IACrC,OAAO,CAAC,WAAW;IAUnB,wIAAwI;IACxI,OAAO,CAAC,YAAY;CAerB"}
+{"version":3,"file":"clipboard-manager.d.ts","sourceRoot":"","sources":["../../src/controllers/clipboard-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,QAAQ,EAEb,KAAK,cAAc,EAIpB,MAAM,aAAa,CAAC;AAGrB,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B,oGAAoG;IACpG,OAAO,CAAC,gBAAgB,CAA+B;IACvD,OAAO,CAAC,eAAe,CAAyB;IAChD,sFAAsF;IACtF,OAAO,CAAC,gBAAgB,CAAuB;IAE/C;;;;;;;OAOG;IACG,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAmC/D;IAED;;;;;;OAMG;IACG,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASlE;IAED;;;;;;;;;;OAUG;IACG,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,CA+C/B;IAED;;;OAGG;IACH,OAAO,CAAC,cAAc;IAuCtB;;;OAGG;IACH,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC,GAAG,IAAI,CA0ClG;IAED;;OAEG;IACH,OAAO,CAAC,0BAA0B;IAuBlC;;;;;;;;;;;;OAYG;IACH,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAgBtC;IAID;;;;;;;;;;OAUG;IACH,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA+DrF;IAID,OAAO,CAAC,cAAc;IAgBtB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAgC7B,sDAAsD;IACtD,OAAO,CAAC,oBAAoB;IAiB5B,2FAA2F;IAC3F,OAAO,CAAC,mBAAmB;IA0C3B,wEAAwE;IACxE,OAAO,CAAC,eAAe;IAoCvB,OAAO,CAAC,qBAAqB;IAqB7B,OAAO,CAAC,iBAAiB;IAQzB,qCAAqC;IACrC,OAAO,CAAC,WAAW;IAUnB,wIAAwI;IACxI,OAAO,CAAC,YAAY;CAerB"}

package/dist/controllers/selection-manager.d.ts

@@ -14,6 +14,12 @@ export declare class SelectionManager implements ReactiveController {
     anchor: CellCoord;
     /** The current end of the selection */
     head: CellCoord;
+    /**
+     * Active cell when it differs from `head` (e.g. after selecting whole
+     * rows/columns, where the active cell stays put while the range spans the
+     * full grid). `null` means the active cell is `head`.
+     */
+    private _active;
     /** Whether a drag selection is in progress */
     private _isDragging;
     /** Grid bounds */
@@ -26,27 +32,106 @@ export declare class SelectionManager implements ReactiveController {
     setBounds(maxRows: number, maxCols: number): void;
     /** Get the normalized selection range (top-left to bottom-right) */
     get range(): SelectionRange;
-    /** Get the currently active cell (head of selection) */
+    /** The active-cell override, or `null` when the active cell follows the head. */
+    get activeOverride(): CellCoord | null;
+    /** Get the currently active cell (the head, unless rows/columns were selected) */
     get activeCell(): CellCoord;
     /** Check if a cell is within the current selection */
     isCellSelected(row: number, col: number): boolean;
     /** Check if a cell is the active cell (head) */
     isCellActive(row: number, col: number): boolean;
-    /** Called on mousedown/pointerdown on a cell */
+    /**
+     * Begin a new selection (mousedown/pointerdown on a cell).
+     *
+     * @param row - Row index of the clicked cell
+     * @param col - Column index of the clicked cell
+     * @param extend - If true (Shift+click), keeps the anchor and moves the head
+     */
     startSelection(row: number, col: number, extend?: boolean): void;
-    /** Called on mousemove during drag */
+    /**
+     * Extend the selection during a drag (mousemove while dragging).
+     *
+     * @param row - Row index the mouse is over
+     * @param col - Column index the mouse is over
+     */
     extendSelection(row: number, col: number): void;
-    /** Called on mouseup */
+    /** Finalize the drag selection (mouseup). Clears the dragging flag. */
     endSelection(): void;
     get isDragging(): boolean;
-    /** Move the active cell by delta. If extend=true, extends selection. */
+    /**
+     * Move the active cell by a delta offset.
+     *
+     * @param dRow - Row delta (-1 = up, +1 = down)
+     * @param dCol - Column delta (-1 = left, +1 = right)
+     * @param extend - If true, keeps the anchor and extends the selection (Shift+arrow)
+     */
     move(dRow: number, dCol: number, extend?: boolean): void;
-    /** Move to a specific cell */
+    /**
+     * Move to a specific cell by absolute position.
+     *
+     * @param row - Target row index
+     * @param col - Target column index
+     * @param extend - If true, keeps the anchor and extends the selection
+     */
     moveTo(row: number, col: number, extend?: boolean): void;
+    /**
+     * Restore a full selection state (e.g. from an undo snapshot).
+     *
+     * @param anchor - Selection anchor
+     * @param head - Selection head
+     * @param active - Active-cell override; omit or pass `null` for the head
+     */
+    setSelection(anchor: CellCoord, head: CellCoord, active?: CellCoord | null): void;
     /** Select all cells */
     selectAll(): void;
+    /**
+     * Select every row of the columns between `fromCol` and `toCol` (inclusive).
+     * The head sits on `toCol`, so Shift+Left/Right keeps growing whole columns.
+     *
+     * @param fromCol - Column the selection is anchored at
+     * @param toCol - Column the selection extends to
+     * @param active - Cell to keep active; defaults to the current active row in `toCol`
+     */
+    selectColumns(fromCol: number, toCol: number, active?: CellCoord): void;
+    /**
+     * Select every column of the rows between `fromRow` and `toRow` (inclusive).
+     * The head sits on `toRow`, so Shift+Up/Down keeps growing whole rows.
+     *
+     * @param fromRow - Row the selection is anchored at
+     * @param toRow - Row the selection extends to
+     * @param active - Cell to keep active; defaults to the current active column in `toRow`
+     */
+    selectRows(fromRow: number, toRow: number, active?: CellCoord): void;
     /** Clear selection (collapse to active cell) */
     clearSelection(): void;
-    private clamp;
+    /**
+     * Keep the active-cell override only while extending and only while it is
+     * still inside the range; otherwise the head is the active cell again.
+     */
+    private _syncActive;
+    /**
+     * Clamp a coordinate to the valid grid bounds.
+     *
+     * @param coord - The coordinate to clamp
+     * @returns A new coordinate within `[0, maxRows-1]` x `[0, maxCols-1]`
+     */
+    clamp(coord: CellCoord): CellCoord;
 }
+/**
+ * Find the target of a Ctrl/Cmd+Arrow jump, following spreadsheet semantics:
+ *
+ * - From a filled cell whose neighbour is also filled: move to the last
+ *   filled cell of that contiguous run.
+ * - Otherwise: move to the next filled cell in that direction, or to the
+ *   grid edge if there is none.
+ *
+ * @param from - Starting cell
+ * @param dRow - Row direction (-1, 0, or 1)
+ * @param dCol - Column direction (-1, 0, or 1)
+ * @param rows - Grid row count
+ * @param cols - Grid column count
+ * @param isFilled - Whether the cell at (row, col) has content
+ * @returns The cell to jump to (equal to `from` when already at the edge)
+ */
+export declare function findDataEdge(from: CellCoord, dRow: number, dCol: number, rows: number, cols: number, isFilled: (row: number, col: number) => boolean): CellCoord;
 //# sourceMappingURL=selection-manager.d.ts.map

package/dist/controllers/selection-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selection-manager.d.ts","sourceRoot":"","sources":["../../src/controllers/selection-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,KAAK,CAAC;AAC3E,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAElE;;;;;;;GAOG;AACH,qBAAa,gBAAiB,YAAW,kBAAkB;IACzD,IAAI,EAAE,sBAAsB,CAAC;IAE7B,iDAAiD;IACjD,MAAM,EAAE,SAAS,CAAsB;IAEvC,uCAAuC;IACvC,IAAI,EAAE,SAAS,CAAsB;IAErC,8CAA8C;IAC9C,OAAO,CAAC,WAAW,CAAS;IAE5B,kBAAkB;IAClB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAO1E,aAAa,IAAI,IAAI;IAIrB,gBAAgB,IAAI,IAAI;IAIxB,kEAAkE;IAClE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAKjD,oEAAoE;IACpE,IAAI,KAAK,IAAI,cAAc,CAW1B;IAED,wDAAwD;IACxD,IAAI,UAAU,IAAI,SAAS,CAE1B;IAED,sDAAsD;IACtD,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAKjD,gDAAgD;IAChD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAM/C,gDAAgD;IAChD,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,IAAI;IAa9D,sCAAsC;IACtC,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAM/C,wBAAwB;IACxB,YAAY,IAAI,IAAI;IAIpB,IAAI,UAAU,IAAI,OAAO,CAExB;IAID,wEAAwE;IACxE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,IAAI;IAatD,8BAA8B;IAC9B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,IAAI;IAStD,uBAAuB;IACvB,SAAS,IAAI,IAAI;IAMjB,gDAAgD;IAChD,cAAc,IAAI,IAAI;IAOtB,OAAO,CAAC,KAAK;CAMd"}
+{"version":3,"file":"selection-manager.d.ts","sourceRoot":"","sources":["../../src/controllers/selection-manager.ts"],"names":[],"mappings":"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"}

package/dist/engine/formula-engine.d.ts

@@ -1,4 +1,8 @@
 import { type GridData, type FormulaFunction } from '../types.js';
+type EvalResult = {
+    displayValue: string;
+    type: 'text' | 'number' | 'boolean' | 'error';
+};
 /**
  * Represents a 2D range of values with shape information.
  * Used by lookup functions (VLOOKUP, INDEX, etc.) that need row/col structure.
@@ -14,6 +18,7 @@ export declare class RangeValue {
 }
 export declare class FormulaEngine {
     private _functions;
+    private _builtinFunctionNames;
     private _data;
     private _evaluating;
     private _evalDepth;
@@ -21,9 +26,29 @@ export declare class FormulaEngine {
     private _reverseDeps;
     private _trackingCellKey;
     private _cache;
+    /**
+     * Values of referenced formula cells computed during the current
+     * evaluation pass (one top-level `evaluate()`, or a whole `recalculate()` /
+     * `recalculateAffected()`). Avoids re-evaluating shared precedents, which is
+     * otherwise exponential, and lets deep chains be resolved incrementally.
+     * Null outside a pass, so standalone `evaluate()` calls always see fresh data.
+     */
+    private _memo;
     constructor();
-    /** Register a user-defined function */
+    /**
+     * Register a user-defined formula function.
+     * The name is normalized to uppercase for case-insensitive lookup.
+     *
+     * @param name - Function name (e.g. "MYFUNC"); stored as uppercase
+     * @param fn - The function implementation
+     */
     registerFunction(name: string, fn: FormulaFunction): void;
+    /**
+     * Replace the entire set of user-defined functions while keeping built-ins.
+     *
+     * @param functions - New custom functions keyed by name
+     */
+    setFunctions(functions: Record<string, FormulaFunction>): void;
     /** Update the data reference for evaluation (full reset of dep graph and cache) */
     setData(data: GridData): void;
     /**
@@ -33,23 +58,42 @@ export declare class FormulaEngine {
      */
     updateData(data: GridData, changedKeys: string[]): void;
     /**
-     * Evaluate a raw value. If it starts with '=', parse and execute the formula.
-     * Otherwise, return the value as-is (possibly coerced).
+     * Evaluate a raw value. If it starts with `=`, parse and execute the formula.
+     * Otherwise, return the value as-is (possibly coerced to number/boolean).
      *
-     * @param forCellKey - If provided, tracks formula dependencies for this cell key.
+     * @param rawValue - The raw cell value (formula or literal)
+     * @param forCellKey - If provided, registers dependencies for this cell key
+     *   (side-effect: updates the forward/reverse dep graph and result cache)
+     * @returns The display value and resolved type
+     */
+    evaluate(rawValue: string, forCellKey?: string): EvalResult;
+    private _evaluateDeferred;
+    /** Run `fn` inside an evaluation pass, creating the pass memo if needed. */
+    private _withMemo;
+    /**
+     * Evaluate a raw value as the top-level formula of `forCellKey`.
+     * Throws only EvalDepthError; every other failure becomes an error result.
+     */
+    private _evaluateTopLevel;
+    /**
+     * Convert a formula result to its display string and type based on the
+     * JS type of the result, so text results like "007" or TEXT() output stay text.
      */
-    evaluate(rawValue: string, forCellKey?: string): {
-        displayValue: string;
-        type: 'text' | 'number' | 'boolean' | 'error';
-    };
+    private _resultToDisplay;
     /**
      * Re-evaluate all formula cells in the grid.
-     * Rebuilds the dependency graph. Returns a set of cell keys that changed.
+     * Clears and rebuilds the entire dependency graph and result cache.
+     *
+     * @returns Set of cell keys whose display value or type changed
      */
     recalculate(): Set<string>;
     /**
      * Recalculate only formulas affected by the given changed cell keys.
-     * Uses the dependency graph for targeted recalculation (BFS order).
+     * Uses BFS traversal of the reverse dependency graph for targeted recalculation.
+     * Falls back to full `recalculate()` if the dep graph is empty.
+     *
+     * @param changedKeys - Cell keys whose raw values changed
+     * @returns Set of cell keys whose display value or type changed
      */
     recalculateAffected(changedKeys: string[]): Set<string>;
     private _clearDepsFor;
@@ -66,10 +110,35 @@ export declare class FormulaEngine {
     private _parseUnary;
     private _parsePrimary;
     private _parseFunction;
+    /**
+     * Parse IFERROR(value, fallback) with error trapping on the first argument.
+     * Called after LPAREN has already been consumed.
+     */
+    private _parseIFERROR;
+    /**
+     * Parse IF(condition, then, else), evaluating only the selected branch.
+     * Called after LPAREN has already been consumed.
+     */
+    private _parseIF;
+    /**
+     * Parse IFS(cond1, value1, cond2, value2, ...). Conditions are evaluated in
+     * order until one is true; only that condition's value is evaluated.
+     * No true condition → #N/A. Called after LPAREN has already been consumed.
+     */
+    private _parseIFS;
+    /** Advance past one function argument without evaluating it. */
+    private _skipArgument;
     private _compareValues;
     private _resolveRef;
+    /**
+     * Evaluate a referenced formula cell, reusing its value if it was already
+     * computed in this evaluation pass. Keeps `_trackingCellKey` so transitive
+     * dependencies are recorded (e.g. C1→B1→A1 means C1 depends on A1 too).
+     */
+    private _evaluateFormulaCell;
     private _resolveRange;
     private _createContext;
     private registerBuiltins;
 }
+export {};
 //# sourceMappingURL=formula-engine.d.ts.map

package/dist/engine/formula-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formula-engine.d.ts","sourceRoot":"","sources":["../../src/engine/formula-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EAEb,KAAK,eAAe,EAGrB,MAAM,aAAa,CAAC;AAoDrB;;;GAGG;AACH,qBAAa,UAAU;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAMzD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;IAItC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE;IAK9B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,EAAE;CAO/B;AA4DD,qBAAa,aAAa;IACxB,OAAO,CAAC,UAAU,CAA2C;IAC7D,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,WAAW,CAA0B;IAC7C,OAAO,CAAC,UAAU,CAAK;IAGvB,OAAO,CAAC,KAAK,CAAuC;IACpD,OAAO,CAAC,YAAY,CAAuC;IAC3D,OAAO,CAAC,gBAAgB,CAAuB;IAG/C,OAAO,CAAC,MAAM,CAAmG;;IAMjH,uCAAuC;IACvC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,eAAe,GAAG,IAAI;IAIzD,mFAAmF;IACnF,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAO7B;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI;IAOvD;;;;;OAKG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,GAClB;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAA;KAAE;IA6D1E;;;OAGG;IACH,WAAW,IAAI,GAAG,CAAC,MAAM,CAAC;IAqB1B;;;OAGG;IACH,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC;IAuEvD,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,SAAS;IAoBjB,OAAO,CAAC,WAAW;IAqBnB,OAAO,CAAC,QAAQ;IA+JhB,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,WAAW;IAYnB,OAAO,CAAC,aAAa;IAsCrB,OAAO,CAAC,cAAc;IA4CtB,OAAO,CAAC,cAAc;IA8CtB,OAAO,CAAC,WAAW;IAoCnB,OAAO,CAAC,aAAa;IA4DrB,OAAO,CAAC,cAAc;IAuCtB,OAAO,CAAC,gBAAgB;CA+azB"}
+{"version":3,"file":"formula-engine.d.ts","sourceRoot":"","sources":["../../src/engine/formula-engine.ts"],"names":[],"mappings":"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"}