@alaarab/ogrid-core 2.2.0 → 2.4.0

package/dist/types/utils/cellReference.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Excel-style cell reference utilities.
+ *
+ * Column letters use base-26 encoding: A–Z, AA–AZ, BA–BZ, …
+ * Row numbers are 1-based.
+ */
+/**
+ * Convert a 0-based column index to an Excel-style column letter.
+ * @example indexToColumnLetter(0)   // 'A'
+ * @example indexToColumnLetter(25)  // 'Z'
+ * @example indexToColumnLetter(26)  // 'AA'
+ * @example indexToColumnLetter(702) // 'AAA'
+ */
+export declare function indexToColumnLetter(index: number): string;
+/**
+ * Format a cell reference string from a 0-based column index and a 1-based row number.
+ * @example formatCellReference(0, 1)    // 'A1'
+ * @example formatCellReference(2, 15)   // 'C15'
+ * @example formatCellReference(26, 100) // 'AA100'
+ */
+export declare function formatCellReference(colIndex: number, rowNumber: number): string;

package/dist/types/utils/cellValue.d.ts

@@ -1,4 +1,5 @@
 import type { IColumnDef } from '../types/columnTypes';
+import type { IGridDataAccessor } from '../formula/types';
 /**
  * Get the cell value for a row/column, using valueGetter when defined otherwise item[columnId].
  *
@@ -14,3 +15,8 @@ export declare function getCellValue<T>(item: T, col: IColumnDef<T>): unknown;
  * Handles both boolean and function-based `editable` definitions.
  */
 export declare function isColumnEditable<T>(col: IColumnDef<T>, item: T): boolean;
+/**
+ * Create an IGridDataAccessor from items and flat columns.
+ * Shared factory used by React, Angular, Vue, and JS formula engine integrations.
+ */
+export declare function createGridDataAccessor<T>(items: T[], flatColumns: IColumnDef<T>[]): IGridDataAccessor;

package/dist/types/utils/clipboardHelpers.d.ts

@@ -20,9 +20,17 @@ export declare function formatCellValueForTsv(raw: unknown, formatted: unknown):
  * @param items       Flat array of all row data objects.
  * @param visibleCols Visible column definitions.
  * @param range       The selection range to serialize (will be normalized).
+ * @param formulaOptions  Optional formula-aware options. When provided, cells with
+ *                        formulas will have their formula string copied instead of
+ *                        the computed value.
  * @returns TSV string with rows separated by \\r\\n and columns by \\t.
  */
-export declare function formatSelectionAsTsv<T>(items: T[], visibleCols: IColumnDef<T>[], range: ISelectionRange): string;
+export declare function formatSelectionAsTsv<T>(items: T[], visibleCols: IColumnDef<T>[], range: ISelectionRange, formulaOptions?: {
+    colOffset: number;
+    flatColumns: IColumnDef<T>[];
+    getFormula?: (col: number, row: number) => string | undefined;
+    hasFormula?: (col: number, row: number) => boolean;
+}): string;
 /**
  * Parse a TSV clipboard string into a 2D array of cell strings.
  * Handles both \\r\\n and \\n line endings. Ignores trailing empty lines.
@@ -36,14 +44,22 @@ export declare function parseTsvClipboard(text: string): string[][];
  * For each cell in the parsed rows, validates editability, parses the value,
  * and produces a cell value changed event.
  *
+ * When `formulaOptions` is provided, cells whose pasted text starts with "="
+ * are routed through `setFormula` instead of the normal value parse path.
+ *
  * @param parsedRows   2D array of string values (from parseTsvClipboard).
  * @param anchorRow    Target starting row index.
  * @param anchorCol    Target starting column index (data column, not absolute).
  * @param items        Array of all row data objects.
  * @param visibleCols  Visible column definitions.
+ * @param formulaOptions  Optional formula-aware options.
  * @returns Array of cell value changed events to apply.
  */
-export declare function applyPastedValues<T>(parsedRows: string[][], anchorRow: number, anchorCol: number, items: T[], visibleCols: IColumnDef<T>[]): ICellValueChangedEvent<T>[];
+export declare function applyPastedValues<T>(parsedRows: string[][], anchorRow: number, anchorCol: number, items: T[], visibleCols: IColumnDef<T>[], formulaOptions?: {
+    colOffset: number;
+    flatColumns: IColumnDef<T>[];
+    setFormula?: (col: number, row: number, formula: string | null) => void;
+}): ICellValueChangedEvent<T>[];
 /**
  * Clear cells in a cut range by setting each editable cell to an empty-string-parsed value.
  * Used after pasting cut content to clear the original cells.

package/dist/types/utils/dataGridViewModel.d.ts

@@ -75,6 +75,12 @@ export interface CellRenderDescriptorInput<T> {
     onCellValueChanged?: unknown;
     /** True while user is drag-selecting cells — hides fill handle during drag. */
     isDragging?: boolean;
+    /** Get the formula engine's computed value for a cell (colIdx, rowIndex). */
+    getFormulaValue?: (col: number, row: number) => unknown;
+    /** Check if a cell has a formula at the given coordinate. */
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Monotonic counter incremented on each formula recalculation — used for cache invalidation. */
+    formulaVersion?: number;
 }
 export interface CellRenderDescriptor {
     mode: CellRenderMode;
@@ -181,8 +187,9 @@ export declare function getCellRenderDescriptor<T>(item: T, col: IColumnDef<T>,
 export declare function resolveCellDisplayContent<T>(col: IColumnDef<T>, item: T, displayValue: unknown): unknown;
 /**
  * Resolves the cellStyle from a column def, handling both function and static values.
+ * When displayValue is a FormulaError, merges red error color styling.
  */
-export declare function resolveCellStyle<T>(col: IColumnDef<T>, item: T): Record<string, string> | undefined;
+export declare function resolveCellStyle<T>(col: IColumnDef<T>, item: T, displayValue?: unknown): Record<string, string> | undefined;
 /**
  * Builds props for InlineCellEditor. Shared across all UI packages.
  */

package/dist/types/utils/exportToCsv.d.ts

@@ -4,8 +4,16 @@ export interface CsvColumn {
 }
 export declare function escapeCsvValue(value: unknown): string;
 export declare function buildCsvHeader(columns: CsvColumn[]): string;
-export declare function buildCsvRows<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => string): string[];
-export declare function exportToCsv<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => string, filename?: string): void;
+export interface FormulaExportOptions {
+    getFormula?: (col: number, row: number) => string | undefined;
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Map from columnId to flat column index */
+    columnIdToIndex?: Map<string, number>;
+    /** Export mode: 'values' (default) exports computed results, 'formulas' exports formula strings */
+    exportMode?: 'values' | 'formulas';
+}
+export declare function buildCsvRows<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => unknown, formulaOptions?: FormulaExportOptions): string[];
+export declare function exportToCsv<T>(items: T[], columns: CsvColumn[], getValue: (item: T, columnId: string) => unknown, filename?: string, formulaOptions?: FormulaExportOptions): void;
 /**
  * Triggers a browser CSV file download.
  *

package/dist/types/utils/fillHelpers.d.ts

@@ -4,15 +4,32 @@
  */
 import type { IColumnDef, ICellValueChangedEvent } from '../types/columnTypes';
 import type { ISelectionRange } from '../types/dataGridTypes';
+/**
+ * Options for formula-aware fill. When provided, source cells with formulas will
+ * have their relative references adjusted instead of copying raw values.
+ */
+export interface IFillFormulaOptions<T> {
+    /** Flat (unfiltered) column list used to map visible col indices to formula storage indices. */
+    flatColumns: IColumnDef<T>[];
+    /** Returns the formula string for a given (flatColIndex, rowIndex), or undefined if none. */
+    getFormula?: (col: number, row: number) => string | undefined;
+    /** Returns true if the cell at (flatColIndex, rowIndex) has a formula. */
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Sets or clears the formula at (flatColIndex, rowIndex). Pass null to clear. */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
+}
 /**
  * Apply fill values from a source cell across a normalized selection range.
  * Copies the value from the start cell of the range to every other editable cell.
+ * If formulaOptions is provided and the source cell has a formula, relative references
+ * in the formula are adjusted for each target cell instead of copying the raw value.
  *
  * @param range           The normalized fill range (startRow/startCol is the source).
  * @param sourceRow       The original source row index (skipped during fill).
  * @param sourceCol       The original source col index (skipped during fill).
  * @param items           Array of all row data objects.
  * @param visibleCols     Visible column definitions.
+ * @param formulaOptions  Optional formula-aware fill configuration.
  * @returns Array of cell value changed events to apply. Empty if source cell is out of bounds.
  */
-export declare function applyFillValues<T>(range: ISelectionRange, sourceRow: number, sourceCol: number, items: T[], visibleCols: IColumnDef<T>[]): ICellValueChangedEvent<T>[];
+export declare function applyFillValues<T>(range: ISelectionRange, sourceRow: number, sourceCol: number, items: T[], visibleCols: IColumnDef<T>[], formulaOptions?: IFillFormulaOptions<T>): ICellValueChangedEvent<T>[];

package/dist/types/utils/formulaBarHelpers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Formula bar helper utilities.
+ *
+ * Extracts cell/range references from a formula string for highlighting.
+ * Uses the formula tokenizer to parse CELL_REF and range tokens.
+ */
+/** A parsed reference from a formula — either a single cell or a range. */
+export interface FormulaReference {
+    type: 'cell' | 'range';
+    col: number;
+    row: number;
+    endCol?: number;
+    endRow?: number;
+    /** Color palette index (cycles through 0-5). */
+    colorIndex: number;
+}
+/**
+ * Extract all cell and range references from a formula string.
+ * Each reference gets a cycling colorIndex for UI highlighting.
+ *
+ * @param formula - The formula string including the leading '='.
+ * @returns Array of references found in the formula.
+ */
+/**
+ * Handle Enter/Escape key events in the formula bar input.
+ * Shared across React, Angular, Vue, and JS.
+ */
+export declare function handleFormulaBarKeyDown(key: string, preventDefault: () => void, onCommit: () => void, onCancel: () => void): void;
+/**
+ * Process a formula bar commit: if the text starts with '=', set as formula;
+ * otherwise clear any existing formula and commit as a plain value.
+ */
+export declare function processFormulaBarCommit(text: string, col: number, row: number, setFormula: (col: number, row: number, formula: string | null) => void, onCellValueChanged?: (col: number, row: number, value: unknown) => void): void;
+/**
+ * Derive the display text for a formula bar from the active cell.
+ * Returns the formula string (with '=' prefix) if the cell has a formula,
+ * otherwise the stringified raw value.
+ */
+export declare function deriveFormulaBarText(col: number | null, row: number | null, getFormula?: (col: number, row: number) => string | undefined, getRawValue?: (col: number, row: number) => unknown): string;
+export declare function extractFormulaReferences(formula: string): FormulaReference[];

package/dist/types/utils/index.d.ts

@@ -1,5 +1,5 @@
 export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './exportToCsv';
-export { getCellValue, isColumnEditable } from './cellValue';
+export { getCellValue, isColumnEditable, createGridDataAccessor } from './cellValue';
 export { flattenColumns, buildHeaderRows } from './columnUtils';
 export { isFilterConfig, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, } from './ogridHelpers';
 export { getStatusBarParts } from './statusBarHelpers';
@@ -7,7 +7,7 @@ export { getDataGridStatusBarConfig } from './dataGridStatusBar';
 export { getPaginationViewModel, PAGE_SIZE_OPTIONS, MAX_PAGE_BUTTONS, } from './paginationHelpers';
 export type { PaginationViewModel } from './paginationHelpers';
 export { GRID_CONTEXT_MENU_ITEMS, COLUMN_HEADER_MENU_ITEMS, getContextMenuHandlers, getColumnHeaderMenuItems, formatShortcut } from './gridContextMenuHelpers';
-export type { CsvColumn } from './exportToCsv';
+export type { CsvColumn, FormulaExportOptions } from './exportToCsv';
 export type { StatusBarPart, StatusBarPartsInput } from './statusBarHelpers';
 export type { GridContextMenuItem, IColumnHeaderMenuItem, GridContextMenuHandlerProps, ColumnHeaderMenuInput, ColumnHeaderMenuHandlers } from './gridContextMenuHelpers';
 export { parseValue, numberParser, currencyParser, dateParser, emailParser, booleanParser, } from './valueParsers';
@@ -36,5 +36,9 @@ export type { ArrowNavigationContext, ArrowNavigationResult } from './keyboardNa
 export { rangesEqual, clampSelectionToBounds, computeAutoScrollSpeed, applyRangeRowSelection, computeRowSelectionState } from './selectionHelpers';
 export { formatCellValueForTsv, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, } from './clipboardHelpers';
 export { applyFillValues } from './fillHelpers';
+export type { IFillFormulaOptions } from './fillHelpers';
 export { UndoRedoStack } from './undoRedoStack';
 export { validateColumns, validateRowIds, validateVirtualScrollConfig } from './validation';
+export { indexToColumnLetter, formatCellReference } from './cellReference';
+export { extractFormulaReferences, processFormulaBarCommit, deriveFormulaBarText, handleFormulaBarKeyDown } from './formulaBarHelpers';
+export type { FormulaReference } from './formulaBarHelpers';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-core",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "OGrid core – framework-agnostic types, algorithms, and utilities for OGrid data grids.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",