@alaarab/ogrid-js 2.2.0 → 2.4.0

package/dist/styles/ogrid.css

@@ -268,6 +268,24 @@
   background: var(--ogrid-header-bg, #f5f5f5);
 }
 
+/* ── Column Letter Row (A, B, C...) ── */
+
+.ogrid-column-letter-row {
+  background: var(--ogrid-column-letter-bg, var(--ogrid-header-bg));
+}
+
+.ogrid-column-letter-cell {
+  text-align: center;
+  font-size: 11px;
+  font-weight: 500;
+  color: var(--ogrid-fg-muted, rgba(0, 0, 0, 0.5));
+  padding: 2px 4px;
+  background: var(--ogrid-column-letter-bg, var(--ogrid-header-bg));
+  border-bottom: 1px solid var(--ogrid-border, rgba(0, 0, 0, 0.12));
+  user-select: none;
+  font-variant-numeric: tabular-nums;
+}
+
 /* ── Resize Handle ── */
 
 .ogrid-resize-handle {
@@ -392,6 +410,12 @@
 
 /* Cell range/drag highlights: qualify with .ogrid-container to reach specificity 0,3,0,
    beating row-hover rules (.ogrid-table tbody tr:hover td = 0,2,3). */
+/* Active cell inside a selection range: suppress outline (Excel behavior) */
+.ogrid-cell[data-active-cell='true'][data-in-range='true'] {
+  outline: none;
+  background: var(--ogrid-bg, #fff);
+}
+
 .ogrid-container .ogrid-cell[data-in-range='true'] {
   background: var(--ogrid-bg-range, rgba(33, 115, 70, 0.12));
 }
@@ -404,6 +428,12 @@
   background: var(--ogrid-bg, #fff);
 }
 
+/* Hide active cell outline during drag */
+.ogrid-cell[data-active-cell='true'][data-drag-range],
+.ogrid-cell[data-active-cell='true'][data-drag-anchor] {
+  outline: none;
+}
+
 /* ── Fill Handle ── */
 
 .ogrid-fill-handle {

package/dist/types/OGrid.d.ts

@@ -120,6 +120,13 @@ export declare class OGrid<T> {
     private cellEditor;
     private contextMenu;
     private layoutState;
+    private formulaEngine;
+    private formulaBar;
+    private formulaBarContainer;
+    /** Tracks the text currently displayed/edited in the formula bar. */
+    private formulaBarText;
+    /** Whether the formula bar input is currently in editing mode. */
+    private formulaBarEditing;
     private events;
     private unsubscribes;
     private containerEl;
@@ -130,6 +137,7 @@ export declare class OGrid<T> {
     private options;
     private isFullScreen;
     private fullscreenBtn;
+    private nameBoxEl;
     private renderingHelper;
     private eventWiringHelper;
     /** The imperative grid API (extends React's IOGridApi with JS-specific methods). */
@@ -144,6 +152,11 @@ export declare class OGrid<T> {
     private startCellEdit;
     private buildFilterConfigs;
     private handleFilterIconClick;
+    /** Build a grid data accessor for the formula engine from current state. */
+    private buildFormulaAccessor;
+    private handleFormulaBarCommit;
+    private handleFormulaBarCancel;
+    private handleFormulaBarStartEditing;
     /** Subscribe to grid events. */
     on<K extends keyof OGridEvents<T>>(event: K, handler: (data: OGridEvents<T>[K]) => void): void;
     /** Unsubscribe from grid events. */

package/dist/types/components/FormulaBar.d.ts

@@ -0,0 +1,37 @@
+/**
+ * FormulaBar — DOM-based Excel-style formula bar for the vanilla JS grid.
+ *
+ * Layout: [Name Box] [fx] [Formula Input]
+ *
+ * Uses --ogrid-* CSS variables for theming. Matches the React FormulaBar
+ * component behavior exactly.
+ */
+export interface FormulaBarCallbacks {
+    /** Called when the user presses Enter to commit the formula/value. */
+    onCommit: () => void;
+    /** Called when the user presses Escape to cancel editing. */
+    onCancel: () => void;
+    /** Called when the input text changes. */
+    onInputChange: (text: string) => void;
+    /** Called when the user clicks the input to start editing. */
+    onStartEditing: () => void;
+}
+export declare class FormulaBar {
+    private el;
+    private nameBoxEl;
+    private inputEl;
+    private isEditing;
+    private callbacks;
+    constructor(callbacks: FormulaBarCallbacks);
+    /** Create the formula bar DOM and append it to the given container. */
+    mount(container: HTMLElement): void;
+    /** Update the formula bar display with the current active cell ref and formula text. */
+    update(cellRef: string | null, formulaText: string): void;
+    /** Set editing state. When true, the input becomes editable and receives focus. */
+    setEditing(editing: boolean): void;
+    /** Remove the formula bar from the DOM and clean up event listeners. */
+    destroy(): void;
+    private handleKeyDown;
+    private handleInput;
+    private handleClick;
+}

package/dist/types/index.d.ts

@@ -30,5 +30,9 @@ export { VirtualScrollState } from './state/VirtualScrollState';
 export { MarchingAntsOverlay } from './components/MarchingAntsOverlay';
 export { SideBarState } from './state/SideBarState';
 export { HeaderFilterState } from './state/HeaderFilterState';
+export { FormulaEngineState } from './state/FormulaEngineState';
+export type { FormulaEngineStateOptions } from './state/FormulaEngineState';
 export { SideBar } from './components/SideBar';
 export { HeaderFilter } from './components/HeaderFilter';
+export { FormulaBar } from './components/FormulaBar';
+export type { FormulaBarCallbacks } from './components/FormulaBar';

package/dist/types/renderer/TableRenderer.d.ts

@@ -3,6 +3,7 @@ import type { IActiveCell, ISelectionRange } from '@alaarab/ogrid-core';
 import type { GridState } from '../state/GridState';
 import type { HeaderFilterState, HeaderFilterConfig } from '../state/HeaderFilterState';
 import type { VirtualScrollState } from '../state/VirtualScrollState';
+import type { FormulaEngineState } from '../state/FormulaEngineState';
 export interface TableRendererInteractionState {
     activeCell: IActiveCell | null;
     selectionRange: ISelectionRange | null;
@@ -27,6 +28,8 @@ export interface TableRendererInteractionState {
     allSelected?: boolean;
     someSelected?: boolean;
     showRowNumbers?: boolean;
+    showColumnLetters?: boolean;
+    showNameBox?: boolean;
     pinnedColumns?: Record<string, 'left' | 'right'>;
     leftOffsets?: Record<string, number>;
     rightOffsets?: Record<string, number>;
@@ -66,7 +69,9 @@ export declare class TableRenderer<T> {
     private lastPinnedColumns;
     private lastAllSelected;
     private lastSomeSelected;
+    private formulaEngine;
     constructor(container: HTMLElement, state: GridState<T>);
+    setFormulaEngine(engine: FormulaEngineState): void;
     setVirtualScrollState(vs: VirtualScrollState): void;
     setHeaderFilterState(state: HeaderFilterState, configs: Map<string, HeaderFilterConfig>): void;
     setOnFilterIconClick(handler: (columnId: string, headerEl: HTMLElement) => void): void;

package/dist/types/state/ClipboardState.d.ts

@@ -11,6 +11,16 @@ export interface ClipboardParams<T> {
     colOffset: number;
     editable?: boolean;
     onCellValueChanged?: (event: ICellValueChangedEvent<T>) => void;
+    /** When true, enables formula-aware copy/paste. */
+    formulas?: boolean;
+    /** Flat (unfiltered) column list used to map visible col to flat col index. */
+    flatColumns?: IColumnDef<T>[];
+    /** Returns the formula string for a flat column + row, or undefined if none. */
+    getFormula?: (col: number, row: number) => string | undefined;
+    /** Returns true if a flat column + row has a formula. */
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Sets or clears a formula for a flat column + row. */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
 }
 export declare class ClipboardState<T> {
     private emitter;

package/dist/types/state/FillHandleState.d.ts

@@ -1,4 +1,4 @@
-import type { IActiveCell, ISelectionRange, IColumnDef, ICellValueChangedEvent } from '@alaarab/ogrid-core';
+import type { IActiveCell, ISelectionRange, IColumnDef, ICellValueChangedEvent, IFillFormulaOptions } from '@alaarab/ogrid-core';
 interface FillHandleEvents extends Record<string, unknown> {
     fillRangeChange: {
         fillRange: ISelectionRange | null;
@@ -12,6 +12,8 @@ export interface FillHandleParams<T> {
     colOffset: number;
     beginBatch?: () => void;
     endBatch?: () => void;
+    /** Optional formula-aware fill options. When provided, cells with formulas adjust references during fill. */
+    formulaOptions?: IFillFormulaOptions<T>;
 }
 /**
  * Manages Excel-style fill handle drag-to-fill for cell ranges (vanilla JS).

package/dist/types/state/FormulaEngineState.d.ts

@@ -0,0 +1,78 @@
+import type { IGridDataAccessor, IFormulaFunction, IRecalcResult, IAuditEntry, IAuditTrail } from '@alaarab/ogrid-core';
+/** Options for FormulaEngineState. */
+export interface FormulaEngineStateOptions {
+    /** Enable formula support. Engine is only created when true. */
+    formulas?: boolean;
+    /** Formulas to load on initialization (requires an accessor via `initialize()`). */
+    initialFormulas?: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /** Custom formula functions to register with the engine. */
+    formulaFunctions?: Record<string, IFormulaFunction>;
+    /** Callback invoked after every recalculation. */
+    onFormulaRecalc?: (result: IRecalcResult) => void;
+    /** Named ranges: name → cell/range reference string. */
+    namedRanges?: Record<string, string>;
+    /** Sheet accessors for cross-sheet references. */
+    sheets?: Record<string, IGridDataAccessor>;
+}
+/**
+ * FormulaEngineState — wraps the core `FormulaEngine` for the vanilla JS grid.
+ *
+ * Follows the same EventEmitter pattern as other JS state classes. The engine
+ * is lazily created only when `formulas` is true in the options, keeping the
+ * cost at zero for grids that don't use formulas.
+ *
+ * ## Events
+ * - `formulaRecalc` — emitted after every recalculation with `IRecalcResult`.
+ */
+export declare class FormulaEngineState {
+    private emitter;
+    private engine;
+    private readonly options;
+    constructor(options: FormulaEngineStateOptions);
+    /**
+     * Initialize with an accessor — loads `initialFormulas` if provided.
+     * Must be called after the grid data is available so the accessor is valid.
+     */
+    initialize(accessor: IGridDataAccessor): void;
+    /**
+     * Set or clear a formula for a cell. Triggers recalculation of dependents
+     * and emits `formulaRecalc`.
+     */
+    setFormula(col: number, row: number, formula: string | null, accessor: IGridDataAccessor): IRecalcResult | undefined;
+    /**
+     * Notify the engine that a non-formula cell's value changed.
+     * Triggers recalculation of any formulas that depend on the changed cell.
+     */
+    onCellChanged(col: number, row: number, accessor: IGridDataAccessor): IRecalcResult | undefined;
+    /** Get the computed value for a formula cell (or undefined if no formula). */
+    getValue(col: number, row: number): unknown | undefined;
+    /** Check if a cell has a formula. */
+    hasFormula(col: number, row: number): boolean;
+    /** Get the formula string for a cell (or undefined if no formula). */
+    getFormula(col: number, row: number): string | undefined;
+    /** Whether the formula engine is active. */
+    isEnabled(): boolean;
+    /** Define a named range. */
+    defineNamedRange(name: string, ref: string): void;
+    /** Remove a named range. */
+    removeNamedRange(name: string): void;
+    /** Register a sheet accessor for cross-sheet references. */
+    registerSheet(name: string, accessor: IGridDataAccessor): void;
+    /** Unregister a sheet accessor. */
+    unregisterSheet(name: string): void;
+    /** Get all cells that a cell depends on (deep, transitive). */
+    getPrecedents(col: number, row: number): IAuditEntry[];
+    /** Get all cells that depend on a cell (deep, transitive). */
+    getDependents(col: number, row: number): IAuditEntry[];
+    /** Get full audit trail for a cell. */
+    getAuditTrail(col: number, row: number): IAuditTrail | null;
+    /** Subscribe to the `formulaRecalc` event. Returns an unsubscribe function. */
+    onFormulaRecalc(handler: (result: IRecalcResult) => void): () => void;
+    /** Clean up all listeners. */
+    destroy(): void;
+    private emitRecalc;
+}

package/dist/types/state/GridState.d.ts

@@ -1,6 +1,7 @@
 import type { IColumnDef, IColumnGroupDef } from '../types/columnTypes';
 import type { RowId, IFilters, OGridOptions, IJsOGridApi } from '../types/gridTypes';
 import type { FilterValue } from '@alaarab/ogrid-core';
+import type { FormulaEngineState } from './FormulaEngineState';
 interface StateChangeEvent {
     type: 'data' | 'sort' | 'filter' | 'page' | 'columns' | 'loading';
 }
@@ -29,6 +30,7 @@ export declare class GridState<T> {
     private _stickyHeader;
     private _fullScreen;
     private _workerSort;
+    private _formulaEngine;
     private _filterOptions;
     private _columnOrder;
     private _visibleColsCache;
@@ -88,6 +90,8 @@ export declare class GridState<T> {
     refreshData(): void;
     onStateChange(handler: (event: StateChangeEvent) => void): () => void;
     getApi(): IJsOGridApi<T>;
+    /** Wire in the formula engine so exportToCsv can use it. */
+    setFormulaEngine(engine: FormulaEngineState): void;
     destroy(): void;
 }
 export {};

package/dist/types/types/gridTypes.d.ts

@@ -1,6 +1,6 @@
 import type { IColumnDef, IColumnGroupDef, ICellValueChangedEvent } from './columnTypes';
-import type { RowId, IFilters, IDataSource, RowSelectionMode, IRowSelectionChangeEvent, IOGridApi, ISideBarDef, IStatusBarProps, IVirtualScrollConfig } from '@alaarab/ogrid-core';
-export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IOGridApi, } from '@alaarab/ogrid-core';
+import type { RowId, IFilters, IDataSource, RowSelectionMode, IRowSelectionChangeEvent, IOGridApi, ISideBarDef, IStatusBarProps, IVirtualScrollConfig, IFormulaFunction, IRecalcResult, IGridDataAccessor } from '@alaarab/ogrid-core';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IVirtualScrollConfig, IOGridApi, IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail, } from '@alaarab/ogrid-core';
 /** Standardized cell event parameter for cell interaction callbacks. */
 export interface CellEvent {
     /** Zero-based row index within the current page. */
@@ -17,7 +17,9 @@ export interface CellEvent {
 /** Extended API for the vanilla JS package (adds methods not in the core IOGridApi). */
 export interface IJsOGridApi<T> extends IOGridApi<T> {
     /** Export displayed rows to CSV and trigger a download. */
-    exportToCsv: (filename?: string) => void;
+    exportToCsv: (filename?: string, options?: {
+        exportMode?: 'values' | 'formulas';
+    }) => void;
     /** Scroll to a specific row by index (virtual scrolling). */
     scrollToRow: (index: number, options?: {
         align?: 'start' | 'center' | 'end';
@@ -54,6 +56,8 @@ export interface OGridOptions<T> {
     onCellValueChanged?: (event: ICellValueChangedEvent<T>) => void;
     /** Show row numbers column. Default: false. */
     showRowNumbers?: boolean;
+    /** Enable Excel-style cell references: column letter headers, row numbers, and name box. Implies showRowNumbers. */
+    cellReferences?: boolean;
     /** Status bar configuration or boolean to enable/disable with defaults. */
     statusBar?: boolean | IStatusBarProps;
     /** Plural label for the entity type (e.g. 'items'). Used in status bar and empty state. */
@@ -131,6 +135,22 @@ export interface OGridOptions<T> {
     toolbarBelow?: HTMLElement | null;
     /** Custom keydown handler. Called before grid's built-in handling. Call event.preventDefault() to suppress grid default. */
     onKeyDown?: (event: KeyboardEvent) => void;
+    /** Enable Excel-like formula support. When true, cells starting with '=' are treated as formulas. Default: false. */
+    formulas?: boolean;
+    /** Initial formulas to load when the formula engine initializes. */
+    initialFormulas?: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /** Called when formula recalculation produces updated cell values (e.g. cascade from an edited cell). */
+    onFormulaRecalc?: (result: IRecalcResult) => void;
+    /** Custom formula functions to register with the formula engine (e.g. { MYFUNC: { minArgs: 1, maxArgs: 1, evaluate: ... } }). */
+    formulaFunctions?: Record<string, IFormulaFunction>;
+    /** Named ranges for the formula engine: name → cell/range ref string (e.g. { Revenue: 'A1:A10' }). */
+    namedRanges?: Record<string, string>;
+    /** Sheet accessors for cross-sheet formula references (e.g. { Sheet2: accessor }). */
+    sheets?: Record<string, IGridDataAccessor>;
 }
 /** Events emitted by the OGrid instance. */
 export interface OGridEvents<T> extends Record<string, unknown> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-js",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "OGrid vanilla JS – framework-free data grid with sorting, filtering, pagination, and spreadsheet-style editing.",
   "main": "dist/esm/index.js",
   "module": "dist/esm/index.js",
@@ -36,7 +36,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@alaarab/ogrid-core": "2.2.0"
+    "@alaarab/ogrid-core": "2.4.0"
   },
   "sideEffects": [
     "**/*.css"