@alaarab/ogrid-core 2.3.0 → 2.4.0

package/dist/types/constants/formulaBar.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Formula bar and formula reference highlighting constants.
+ * Shared across React, Angular, Vue, and JS packages.
+ */
+/** Color palette for formula reference highlights (cycles 0–5). Uses CSS vars with fallbacks. */
+export declare const FORMULA_REF_COLORS: readonly ["var(--ogrid-formula-ref-0, #4285f4)", "var(--ogrid-formula-ref-1, #ea4335)", "var(--ogrid-formula-ref-2, #34a853)", "var(--ogrid-formula-ref-3, #9334e6)", "var(--ogrid-formula-ref-4, #ff6d01)", "var(--ogrid-formula-ref-5, #46bdc6)"];
+/** CSS text for the formula bar container (used by JS and Angular inline styles). */
+export declare const FORMULA_BAR_CSS: {
+    readonly bar: "display:flex;align-items:center;border-bottom:1px solid var(--ogrid-border, #e0e0e0);background:var(--ogrid-bg, #fff);min-height:28px;font-size:13px;";
+    readonly nameBox: "font-family:monospace;font-size:12px;font-weight:500;padding:2px 8px;border-right:1px solid var(--ogrid-border, #e0e0e0);background:var(--ogrid-bg, #fff);color:var(--ogrid-fg, #242424);min-width:52px;text-align:center;line-height:24px;user-select:none;white-space:nowrap;";
+    readonly fxLabel: "padding:2px 8px;font-style:italic;font-weight:600;color:var(--ogrid-muted-fg, #888);user-select:none;border-right:1px solid var(--ogrid-border, #e0e0e0);line-height:24px;font-size:12px;";
+    readonly input: "flex:1;border:none;outline:none;padding:2px 8px;font-family:monospace;font-size:12px;line-height:24px;background:transparent;color:var(--ogrid-fg, #242424);min-width:0;";
+};
+/** Style objects for the formula bar — used by React and Vue (CSSProperties-compatible). */
+export declare const FORMULA_BAR_STYLES: {
+    readonly bar: {
+        readonly display: "flex";
+        readonly alignItems: "center";
+        readonly borderBottom: "1px solid var(--ogrid-border, #e0e0e0)";
+        readonly background: "var(--ogrid-bg, #fff)";
+        readonly minHeight: "28px";
+        readonly fontSize: "13px";
+    };
+    readonly nameBox: {
+        readonly fontFamily: "monospace";
+        readonly fontSize: "12px";
+        readonly fontWeight: 500;
+        readonly padding: "2px 8px";
+        readonly borderRight: "1px solid var(--ogrid-border, #e0e0e0)";
+        readonly background: "var(--ogrid-bg, #fff)";
+        readonly color: "var(--ogrid-fg, #242424)";
+        readonly minWidth: "52px";
+        readonly textAlign: "center";
+        readonly lineHeight: "24px";
+        readonly userSelect: "none";
+        readonly whiteSpace: "nowrap";
+    };
+    readonly fxLabel: {
+        readonly padding: "2px 8px";
+        readonly fontStyle: "italic";
+        readonly fontWeight: 600;
+        readonly color: "var(--ogrid-muted-fg, #888)";
+        readonly userSelect: "none";
+        readonly borderRight: "1px solid var(--ogrid-border, #e0e0e0)";
+        readonly lineHeight: "24px";
+        readonly fontSize: "12px";
+    };
+    readonly input: {
+        readonly flex: 1;
+        readonly border: "none";
+        readonly outline: "none";
+        readonly padding: "2px 8px";
+        readonly fontFamily: "monospace";
+        readonly fontSize: "12px";
+        readonly lineHeight: "24px";
+        readonly background: "transparent";
+        readonly color: "var(--ogrid-fg, #242424)";
+        readonly minWidth: 0;
+    };
+};

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

@@ -2,3 +2,4 @@ export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDT
 export { DEFAULT_DEBOUNCE_MS, PEOPLE_SEARCH_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './timing';
 export { Z_INDEX } from './zIndex';
 export type { ZIndexKey } from './zIndex';
+export { FORMULA_REF_COLORS, FORMULA_BAR_CSS, FORMULA_BAR_STYLES } from './formulaBar';

package/dist/types/formula/functions/financial.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerFinancialFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/reference.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerReferenceFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/functions/statistical-extended.d.ts

@@ -0,0 +1,2 @@
+import type { IFormulaFunction } from '../types';
+export declare function registerStatisticalExtendedFunctions(registry: Map<string, IFormulaFunction>): void;

package/dist/types/formula/types.d.ts

@@ -80,6 +80,8 @@ export interface IFormulaContext {
     getCellValue(address: ICellAddress): unknown;
     getRangeValues(range: ICellRange): unknown[][];
     now(): Date;
+    /** Optional: return the formula string for a cell, or undefined if not a formula cell. */
+    getCellFormula?(address: ICellAddress): string | undefined;
 }
 /** A registered formula function. */
 export interface IFormulaFunction {

package/dist/types/index.d.ts

@@ -1,9 +1,9 @@
 export type { ColumnFilterType, IDateFilterValue, IColumnFilterDef, IColumnMeta, IValueParserParams, IColumnDef, ICellValueChangedEvent, ICellEditorProps, CellEditorParams, IColumnGroupDef, HeaderCell, HeaderRow, IColumnDefinition, } from './types';
-export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './types';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, ISheetDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './types';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange, } from './types';
 export { escapeCsvValue, buildCsvHeader, buildCsvRows, exportToCsv, triggerCsvDownload, } from './utils';
 export type { CsvColumn, FormulaExportOptions } from './utils';
-export { getCellValue, isColumnEditable } from './utils';
+export { getCellValue, isColumnEditable, createGridDataAccessor } from './utils';
 export { flattenColumns, buildHeaderRows } from './utils';
 export { isFilterConfig, getFilterField, mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, } from './utils';
 export { getStatusBarParts } from './utils';
@@ -43,9 +43,12 @@ export type { IFillFormulaOptions } from './utils';
 export { UndoRedoStack } from './utils';
 export { validateColumns, validateRowIds, validateVirtualScrollConfig } from './utils';
 export { indexToColumnLetter, formatCellReference } from './utils';
+export { extractFormulaReferences, processFormulaBarCommit, deriveFormulaBarText, handleFormulaBarKeyDown } from './utils';
+export type { FormulaReference } from './utils';
 export { CHECKBOX_COLUMN_WIDTH, ROW_NUMBER_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, GRID_BORDER_RADIUS, } from './constants';
 export { DEFAULT_DEBOUNCE_MS, PEOPLE_SEARCH_DEBOUNCE_MS, SIDEBAR_TRANSITION_MS, } from './constants';
 export { Z_INDEX } from './constants';
 export type { ZIndexKey } from './constants';
+export { FORMULA_REF_COLORS, FORMULA_BAR_CSS, FORMULA_BAR_STYLES } from './constants';
 export { FormulaError, FormulaEngine, FormulaEvaluator, DependencyGraph, tokenize, parse, createBuiltInFunctions, columnLetterToIndex, parseCellRef, parseRange, formatAddress, toCellKey, fromCellKey, adjustFormulaReferences, toNumber, toString as formulaToString, toBoolean, flattenArgs, isFormulaError, REF_ERROR, DIV_ZERO_ERROR, VALUE_ERROR, NAME_ERROR, CIRC_ERROR, GENERAL_ERROR, NA_ERROR, } from './formula';
 export type { ICellAddress, ICellRange, CellKey, FormulaErrorType, TokenType, Token, ASTNode, BinaryOp, IFormulaContext, IFormulaFunction, IEvaluator, IRecalcResult, IFormulaEngineConfig, IGridDataAccessor, INamedRange, IAuditEntry, IAuditTrail, } from './formula';

package/dist/types/types/dataGridTypes.d.ts

@@ -128,6 +128,13 @@ export interface ISideBarDef {
     /** Position of the side bar (default: 'right'). */
     position?: 'left' | 'right';
 }
+/** Definition for a sheet tab. */
+export interface ISheetDef {
+    id: string;
+    name: string;
+    /** Optional tab color (CSS value). */
+    color?: string;
+}
 /** Configuration for virtual scrolling. */
 export interface IVirtualScrollConfig {
     /** Enable virtual scrolling (default: false). */

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

@@ -1,3 +1,3 @@
 export type { ColumnFilterType, IDateFilterValue, IColumnFilterDef, IColumnMeta, IValueParserParams, IColumnDef, ICellValueChangedEvent, ICellEditorProps, CellEditorParams, IColumnGroupDef, HeaderCell, HeaderRow, IColumnDefinition, } from './columnTypes';
-export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './dataGridTypes';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, ISheetDef, IVirtualScrollConfig, IColumnReorderConfig, IOGridApi, } from './dataGridTypes';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange, } from './dataGridTypes';

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

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';
@@ -40,3 +40,5 @@ 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.3.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",