@alaarab/ogrid-vue 2.2.0 → 2.3.0

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-import { injectGlobalStyles, Z_INDEX, getStatusBarParts, measureRange, flattenColumns, getMultiSelectFilterFields, deriveFilterOptionsFromData, processClientSideData, processClientSideDataAsync, validateColumns, validateRowIds, computeRowSelectionState, buildCellIndex, UndoRedoStack, CHECKBOX_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, computeAggregations, getDataGridStatusBarConfig, validateVirtualScrollConfig, computeVisibleRange, computeTotalHeight, computeVisibleColumnRange, partitionColumnsForVirtualization, buildHeaderRows, ROW_NUMBER_COLUMN_WIDTH, getHeaderFilterConfig, getCellRenderDescriptor, buildInlineEditorProps, buildPopoverEditorProps, resolveCellDisplayContent, resolveCellStyle, rangesEqual, normalizeSelectionRange, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, measureColumnContentWidth, getPinStateForColumn, parseValue, applyFillValues, applyCellDeletion, computeTabNavigation, computeArrowNavigation, computeNextSortState, mergeFilter, applyRangeRowSelection, getScrollTopForRow, getCellValue, calculateDropTarget, reorderColumnArray, computeAutoScrollSpeed } from '@alaarab/ogrid-core';
+import { injectGlobalStyles, Z_INDEX, getStatusBarParts, measureRange, flattenColumns, getMultiSelectFilterFields, deriveFilterOptionsFromData, processClientSideData, processClientSideDataAsync, validateColumns, validateRowIds, computeRowSelectionState, buildCellIndex, UndoRedoStack, CHECKBOX_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, computeAggregations, getDataGridStatusBarConfig, validateVirtualScrollConfig, computeVisibleRange, computeTotalHeight, computeVisibleColumnRange, partitionColumnsForVirtualization, formatCellReference, buildHeaderRows, indexToColumnLetter, ROW_NUMBER_COLUMN_WIDTH, getHeaderFilterConfig, getCellRenderDescriptor, buildInlineEditorProps, buildPopoverEditorProps, resolveCellDisplayContent, resolveCellStyle, rangesEqual, normalizeSelectionRange, formatSelectionAsTsv, parseTsvClipboard, applyPastedValues, applyCutClear, measureColumnContentWidth, getPinStateForColumn, parseValue, applyFillValues, applyCellDeletion, computeTabNavigation, computeArrowNavigation, computeNextSortState, mergeFilter, applyRangeRowSelection, getScrollTopForRow, FormulaEngine, getCellValue, calculateDropTarget, reorderColumnArray, computeAutoScrollSpeed } from '@alaarab/ogrid-core';
 export * from '@alaarab/ogrid-core';
 export { buildInlineEditorProps, buildPopoverEditorProps, getCellRenderDescriptor, getHeaderFilterConfig, isInSelectionRange, normalizeSelectionRange, resolveCellDisplayContent, resolveCellStyle, toUserLike } from '@alaarab/ogrid-core';
 import { defineComponent, ref, computed, onMounted, watch, toValue, onUnmounted, h, shallowRef, triggerRef, nextTick, Teleport, isRef, isReadonly, unref, customRef } from 'vue';
@@ -210,6 +210,126 @@ function useFilterOptions(dataSource, fields) {
   }, { immediate: true });
   return { filterOptions, loadingOptions };
 }
+function useLatestRef(source) {
+  let value = unref(source);
+  return customRef((track, trigger) => ({
+    get() {
+      if (isRef(source)) {
+        value = source.value;
+      }
+      return value;
+    },
+    set(newValue) {
+      value = newValue;
+      trigger();
+    }
+  }));
+}
+
+// src/composables/useFormulaEngine.ts
+function useFormulaEngine(params) {
+  const {
+    formulas,
+    items,
+    flatColumns,
+    initialFormulas,
+    onFormulaRecalc,
+    formulaFunctions,
+    namedRanges,
+    sheets
+  } = params;
+  const itemsRef = useLatestRef(items);
+  const flatColumnsRef = useLatestRef(flatColumns);
+  const onFormulaRecalcRef = useLatestRef(onFormulaRecalc);
+  const engineRef = shallowRef(null);
+  let initialLoaded = false;
+  const enabled = computed(() => formulas?.value ?? false);
+  function createAccessor() {
+    const currentItems = itemsRef.value;
+    const currentCols = flatColumnsRef.value;
+    return {
+      getCellValue: (col, row) => {
+        if (row < 0 || row >= currentItems.length) return null;
+        if (col < 0 || col >= currentCols.length) return null;
+        return getCellValue(currentItems[row], currentCols[col]);
+      },
+      getRowCount: () => currentItems.length,
+      getColumnCount: () => currentCols.length
+    };
+  }
+  watch(
+    enabled,
+    (isEnabled) => {
+      if (isEnabled && !engineRef.value) {
+        engineRef.value = new FormulaEngine({
+          customFunctions: formulaFunctions,
+          namedRanges
+        });
+        if (sheets) {
+          for (const [name, accessor] of Object.entries(sheets)) {
+            engineRef.value.registerSheet(name, accessor);
+          }
+        }
+        if (initialFormulas && !initialLoaded) {
+          initialLoaded = true;
+          const accessor = createAccessor();
+          const result = engineRef.value.loadFormulas(initialFormulas, accessor);
+          if (result.updatedCells.length > 0) {
+            onFormulaRecalcRef.value?.(result);
+          }
+        }
+      } else if (!isEnabled && engineRef.value) {
+        engineRef.value = null;
+      }
+    },
+    { immediate: true }
+  );
+  function getFormulaValue(col, row) {
+    return engineRef.value?.getValue(col, row);
+  }
+  function hasFormula(col, row) {
+    return engineRef.value?.hasFormula(col, row) ?? false;
+  }
+  function getFormula(col, row) {
+    return engineRef.value?.getFormula(col, row);
+  }
+  function setFormula(col, row, formula) {
+    if (!engineRef.value) return;
+    const accessor = createAccessor();
+    const result = engineRef.value.setFormula(col, row, formula, accessor);
+    if (result.updatedCells.length > 0) {
+      onFormulaRecalcRef.value?.(result);
+    }
+  }
+  function onCellChanged(col, row) {
+    if (!engineRef.value) return;
+    const accessor = createAccessor();
+    const result = engineRef.value.onCellChanged(col, row, accessor);
+    if (result.updatedCells.length > 0) {
+      onFormulaRecalcRef.value?.(result);
+    }
+  }
+  function getPrecedents(col, row) {
+    return engineRef.value?.getPrecedents(col, row) ?? [];
+  }
+  function getDependents(col, row) {
+    return engineRef.value?.getDependents(col, row) ?? [];
+  }
+  function getAuditTrail(col, row) {
+    return engineRef.value?.getAuditTrail(col, row) ?? null;
+  }
+  return {
+    enabled,
+    getFormulaValue,
+    hasFormula,
+    getFormula,
+    setFormula,
+    onCellChanged,
+    getPrecedents,
+    getDependents,
+    getAuditTrail
+  };
+}
 var DEFAULT_PANELS = ["columns", "filters"];
 function useSideBarState(params) {
   const { config } = params;
@@ -494,6 +614,17 @@ function useOGrid(props) {
   const displayTotalCount = computed(
     () => isClientSide.value && resolvedClientItems.value ? resolvedClientItems.value.totalCount : serverTotalCount.value
   );
+  const formulasRef = computed(() => !!props.value.formulas);
+  const formulaEngine = useFormulaEngine({
+    formulas: formulasRef,
+    items: displayItems,
+    flatColumns: columns,
+    initialFormulas: props.value.initialFormulas,
+    onFormulaRecalc: props.value.onFormulaRecalc,
+    formulaFunctions: props.value.formulaFunctions,
+    namedRanges: props.value.namedRanges,
+    sheets: props.value.sheets
+  });
   let firstDataRendered = false;
   let rowIdsValidated = false;
   watch(displayItems, (items) => {
@@ -581,6 +712,10 @@ function useOGrid(props) {
   });
   const clearAllFilters = () => setFilters({});
   const isLoadingResolved = computed(() => isServerSide.value && loading.value || displayLoading.value);
+  const activeCellRef = ref(null);
+  const onActiveCellChange = (cellRef) => {
+    activeCellRef.value = cellRef;
+  };
   const dataGridProps = computed(() => {
     const p = props.value;
     const ds = dataProps.value.dataSource;
@@ -608,7 +743,10 @@ function useOGrid(props) {
       rowSelection: p.rowSelection ?? "none",
       selectedRows: effectiveSelectedRows.value,
       onSelectionChange: handleSelectionChange,
-      showRowNumbers: p.showRowNumbers,
+      showRowNumbers: p.showRowNumbers || p.cellReferences,
+      showColumnLetters: !!p.cellReferences,
+      showNameBox: !!p.cellReferences,
+      onActiveCellChange: p.cellReferences ? onActiveCellChange : void 0,
       currentPage: page.value,
       pageSize: pageSize.value,
       statusBar: statusBarConfig.value,
@@ -633,7 +771,18 @@ function useOGrid(props) {
         onClearAll: clearAllFilters,
         message: p.emptyState?.message,
         render: p.emptyState?.render
-      }
+      },
+      formulas: p.formulas,
+      ...formulaEngine.enabled.value ? {
+        getFormulaValue: formulaEngine.getFormulaValue,
+        hasFormula: formulaEngine.hasFormula,
+        getFormula: formulaEngine.getFormula,
+        setFormula: formulaEngine.setFormula,
+        onFormulaCellChanged: formulaEngine.onCellChanged,
+        getPrecedents: formulaEngine.getPrecedents,
+        getDependents: formulaEngine.getDependents,
+        getAuditTrail: formulaEngine.getAuditTrail
+      } : {}
     };
   });
   const pagination = computed(() => ({
@@ -651,14 +800,38 @@ function useOGrid(props) {
     onVisibilityChange: handleVisibilityChange,
     placement: columnChooserPlacement.value
   }));
-  const layout = computed(() => ({
-    toolbar: props.value.toolbar,
-    toolbarBelow: props.value.toolbarBelow,
-    className: props.value.className,
-    emptyState: props.value.emptyState,
-    sideBarProps: sideBarProps.value,
-    fullScreen: props.value.fullScreen
-  }));
+  const layout = computed(() => {
+    const showNameBox = !!props.value.cellReferences;
+    let resolvedToolbar = props.value.toolbar;
+    if (showNameBox) {
+      const nameBoxEl = h("div", {
+        style: {
+          display: "inline-flex",
+          alignItems: "center",
+          padding: "0 8px",
+          fontFamily: "'Consolas', 'Courier New', monospace",
+          fontSize: "12px",
+          border: "1px solid rgba(0,0,0,0.12)",
+          borderRadius: "3px",
+          height: "24px",
+          marginRight: "8px",
+          background: "#fff",
+          minWidth: "40px",
+          color: "rgba(0,0,0,0.6)"
+        },
+        "aria-label": "Active cell reference"
+      }, activeCellRef.value ?? "\u2014");
+      resolvedToolbar = [nameBoxEl, resolvedToolbar];
+    }
+    return {
+      toolbar: resolvedToolbar,
+      toolbarBelow: props.value.toolbarBelow,
+      className: props.value.className,
+      emptyState: props.value.emptyState,
+      sideBarProps: sideBarProps.value,
+      fullScreen: props.value.fullScreen
+    };
+  });
   const filtersResult = computed(() => ({
     hasActiveFilters: hasActiveFilters.value,
     setFilters
@@ -880,23 +1053,6 @@ function useActiveCell(wrapperRef, editingCell) {
   });
   return { activeCell, setActiveCell };
 }
-function useLatestRef(source) {
-  let value = unref(source);
-  return customRef((track, trigger) => ({
-    get() {
-      if (isRef(source)) {
-        value = source.value;
-      }
-      return value;
-    },
-    set(newValue) {
-      value = newValue;
-      trigger();
-    }
-  }));
-}
-
-// src/composables/useCellSelection.ts
 var DRAG_ATTR = "data-drag-range";
 var DRAG_ANCHOR_ATTR = "data-drag-anchor";
 var AUTO_SCROLL_EDGE = 40;
@@ -1313,7 +1469,7 @@ function useKeyboardNavigation(params) {
     const maxColIndex = visibleColumnCount - 1 + colOffset;
     if (items.length === 0) return;
     if (activeCell === null) {
-      if (["ArrowDown", "ArrowUp", "ArrowLeft", "ArrowRight", "Tab", "Enter", "Home", "End"].includes(e.key)) {
+      if (["ArrowDown", "ArrowUp", "ArrowLeft", "ArrowRight", "Tab", "Enter", "Home", "End", "PageDown", "PageUp"].includes(e.key)) {
         setActiveCell({ rowIndex: 0, columnIndex: colOffset });
         e.preventDefault();
       }
@@ -1413,6 +1569,36 @@ function useKeyboardNavigation(params) {
         setActiveCell({ rowIndex: newRowEnd, columnIndex: maxColIndex });
         break;
       }
+      case "PageDown":
+      case "PageUp": {
+        e.preventDefault();
+        const wrapperEl = wrapperRef.value;
+        let pageSize = 10;
+        if (wrapperEl) {
+          const row = wrapperEl.querySelector("tbody tr");
+          if (row && row.offsetHeight > 0) pageSize = Math.max(1, Math.floor(wrapperEl.clientHeight / row.offsetHeight));
+        }
+        const pgDirection = e.key === "PageDown" ? 1 : -1;
+        const newRowPage = Math.max(0, Math.min(rowIndex + pgDirection * pageSize, maxRowIndex));
+        if (shift) {
+          setSelectionRange({
+            startRow: selectionRange?.startRow ?? rowIndex,
+            startCol: selectionRange?.startCol ?? dataColIndex,
+            endRow: newRowPage,
+            endCol: selectionRange?.endCol ?? dataColIndex
+          });
+        } else {
+          setSelectionRange({
+            startRow: newRowPage,
+            startCol: dataColIndex,
+            endRow: newRowPage,
+            endCol: dataColIndex
+          });
+        }
+        setActiveCell({ rowIndex: newRowPage, columnIndex });
+        scrollToRow?.(newRowPage, "center");
+        break;
+      }
       case "Enter":
       case "F2": {
         e.preventDefault();
@@ -2970,14 +3156,14 @@ function useInlineCellEditorState(params) {
       e.stopPropagation();
       cancel();
     }
-    if (e.key === "Enter" && editorType === "text") {
+    if (e.key === "Enter" && (editorType === "text" || editorType === "date")) {
       e.preventDefault();
       e.stopPropagation();
       commit(localValue.value);
     }
   };
   const handleBlur = () => {
-    if (editorType === "text") {
+    if (editorType === "text" || editorType === "date") {
       commit(localValue.value);
     }
   };
@@ -3336,6 +3522,7 @@ function getCellInteractionProps(descriptor, columnId, handlers) {
   const base = {
     "data-row-index": descriptor.rowIndex,
     "data-col-index": descriptor.globalColIndex,
+    ...descriptor.isActive ? { "data-active-cell": "true" } : {},
     ...descriptor.isInRange ? { "data-in-range": "true" } : {},
     tabindex: descriptor.isActive ? 0 : -1,
     onMousedown: (e) => handlers.handleCellMouseDown(e, descriptor.rowIndex, descriptor.globalColIndex),
@@ -3371,6 +3558,24 @@ function createDataGridTable(ui) {
         columnPartition,
         globalColIndexMap
       } = useDataGridTableSetup({ props: propsRef });
+      const rowNumberOffset = computed(() => {
+        const p = propsRef.value;
+        const hasRowNumbers = p.showRowNumbers || p.showColumnLetters;
+        return hasRowNumbers ? ((p.currentPage ?? 1) - 1) * (p.pageSize ?? 25) : 0;
+      });
+      watch(
+        [() => state.interaction.value.activeCell, rowNumberOffset],
+        ([ac, offset]) => {
+          const cb = propsRef.value.onActiveCellChange;
+          if (!cb) return;
+          if (ac) {
+            cb(formatCellReference(ac.columnIndex, offset + ac.rowIndex + 1));
+          } else {
+            cb(null);
+          }
+        },
+        { immediate: true }
+      );
       const onWrapperMousedown = (e) => {
         lastMouseShift.value = e.shiftKey;
       };
@@ -3446,7 +3651,7 @@ function createDataGridTable(ui) {
         } = layout;
         const currentPage = p.currentPage ?? 1;
         const pageSize = p.pageSize ?? 25;
-        const rowNumberOffset = hasRowNumbersCol ? (currentPage - 1) * pageSize : 0;
+        const rowNumberOffset2 = hasRowNumbersCol ? (currentPage - 1) * pageSize : 0;
         const { selectedRowIds, handleRowCheckboxChange, handleSelectAll, allSelected, someSelected } = rowSel;
         const { editingCell: _editingCell, setEditingCell, pendingEditorValue, setPendingEditorValue, commitCellEdit, cancelPopoverEdit, popoverAnchorEl, setPopoverAnchorEl } = editing;
         const {
@@ -3536,13 +3741,14 @@ function createDataGridTable(ui) {
             ]);
           }
           const content = resolveCellDisplayContent(col, item, descriptor.displayValue);
-          const cellStyle = resolveCellStyle(col, item);
+          const cellStyle = resolveCellStyle(col, item, descriptor.displayValue);
           const interactionProps2 = getCellInteractionProps(descriptor, col.columnId, interactionHandlers);
           const cellClasses = ["ogrid-cell-content"];
           if (col.type === "numeric") cellClasses.push("ogrid-cell-content--numeric");
           else if (col.type === "boolean") cellClasses.push("ogrid-cell-content--boolean");
           if (descriptor.canEditAny) cellClasses.push("ogrid-cell-content--editable");
           if (descriptor.isActive) cellClasses.push("ogrid-cell-content--active");
+          if (descriptor.isActive && descriptor.isInRange) cellClasses.push("ogrid-cell-content--active-in-range");
           if (descriptor.isInRange && !descriptor.isActive) cellClasses.push("ogrid-cell-in-range");
           if (descriptor.isInCutRange) cellClasses.push("ogrid-cell-cut");
           const styledContent = cellStyle ? h("span", { style: cellStyle }, content) : content;
@@ -3644,10 +3850,23 @@ function createDataGridTable(ui) {
                     ...virtualScrollEnabled.value ? { "data-virtual-scroll": "" } : {}
                   }, [
                     // Header
-                    h(
-                      "thead",
-                      { class: stickyHeader ? "ogrid-thead ogrid-sticky-header" : "ogrid-thead" },
-                      headerRows.map(
+                    h("thead", { class: stickyHeader ? "ogrid-thead ogrid-sticky-header" : "ogrid-thead" }, [
+                      // Column letter row (A, B, C...) for cell references
+                      ...p.showColumnLetters ? [
+                        h("tr", { class: "ogrid-column-letter-row" }, [
+                          ...hasCheckboxCol ? [h("th", { class: "ogrid-column-letter-cell" })] : [],
+                          ...hasRowNumbersCol ? [h("th", { class: "ogrid-column-letter-cell" })] : [],
+                          ...visibleCols.map((col, colIdx) => {
+                            const { classes: hdrCls, style: hdrSty } = getHeaderClassAndStyle(col);
+                            return h("th", {
+                              key: col.columnId,
+                              class: `ogrid-column-letter-cell ${hdrCls}`,
+                              style: hdrSty
+                            }, indexToColumnLetter(colIdx));
+                          })
+                        ])
+                      ] : [],
+                      ...headerRows.map(
                         (row, rowIdx) => h("tr", { key: rowIdx, class: "ogrid-header-row" }, [
                           // Checkbox header cell
                           ...rowIdx === headerRows.length - 1 && hasCheckboxCol ? [
@@ -3757,7 +3976,7 @@ function createDataGridTable(ui) {
                           })
                         ])
                       )
-                    ),
+                    ]),
                     // Body
                     ...!showEmptyInGrid ? [
                       h("tbody", {}, (() => {
@@ -3822,7 +4041,7 @@ function createDataGridTable(ui) {
                                   left: hasCheckboxCol ? `${CHECKBOX_COLUMN_WIDTH}px` : "0",
                                   zIndex: 2
                                 }
-                              }, String(rowNumberOffset + rowIndex + 1))
+                              }, String(rowNumberOffset2 + rowIndex + 1))
                             ] : [],
                             // Left spacer for column virtualization
                             ...leftSpacerWidth > 0 ? [
@@ -3978,6 +4197,7 @@ function createInlineCellEditor(options) {
         dropdown.style.maxHeight = `${maxH}px`;
         dropdown.style.zIndex = "9999";
         dropdown.style.right = "auto";
+        dropdown.style.textAlign = "left";
         if (flipUp) {
           dropdown.style.top = "auto";
           dropdown.style.bottom = `${window.innerHeight - rect.top}px`;
@@ -4083,7 +4303,7 @@ function createInlineCellEditor(options) {
                 selectDropdownRef.value = el;
               },
               role: "listbox",
-              style: { position: "absolute", top: "100%", left: "0", right: "0", maxHeight: "200px", overflowY: "auto", background: "var(--ogrid-bg, #fff)", border: "1px solid var(--ogrid-border, rgba(0,0,0,0.12))", zIndex: "10", boxShadow: "0 4px 16px rgba(0,0,0,0.2)" }
+              style: { position: "absolute", top: "100%", left: "0", right: "0", maxHeight: "200px", overflowY: "auto", background: "var(--ogrid-bg, #fff)", border: "1px solid var(--ogrid-border, rgba(0,0,0,0.12))", zIndex: "10", boxShadow: "0 4px 16px rgba(0,0,0,0.2)", textAlign: "left" }
             }, values.map(
               (v, i) => h("div", {
                 key: String(v),

package/dist/esm/styles/ogrid-layout.css

@@ -140,6 +140,24 @@
   color: var(--ogrid-fg);
 }
 
+/* === Column letter row (cell references) === */
+
+.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;
+}
+
 /* === Checkbox column === */
 
 .ogrid-checkbox-header,
@@ -254,6 +272,14 @@
   overflow: visible;
 }
 
+/* Active cell inside a selection range: suppress outline (Excel behavior).
+   The range overlay border is sufficient; the active cell is distinguished
+   by its white background vs. the dimmed range cells. */
+.ogrid-cell-content--active-in-range {
+  outline: none;
+  background: var(--ogrid-bg, #fff);
+}
+
 /* === Editing cell wrapper === */
 
 .ogrid-editing-cell {

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

@@ -30,6 +30,8 @@ export { useLatestRef } from './useLatestRef';
 export type { MaybeShallowRef } from './useLatestRef';
 export { useTableLayout } from './useTableLayout';
 export type { UseTableLayoutParams, UseTableLayoutResult } from './useTableLayout';
+export { useFormulaEngine } from './useFormulaEngine';
+export type { UseFormulaEngineParams, UseFormulaEngineResult } from './useFormulaEngine';
 export { useColumnHeaderFilterState } from './useColumnHeaderFilterState';
 export type { UseColumnHeaderFilterStateParams, UseColumnHeaderFilterStateResult, } from './useColumnHeaderFilterState';
 export { useTextFilterState } from './useTextFilterState';

package/dist/types/composables/useFormulaEngine.d.ts

@@ -0,0 +1,52 @@
+/**
+ * useFormulaEngine — Vue composable for integrating the formula engine with the grid.
+ *
+ * Lazily creates a FormulaEngine instance when `formulas` ref is true.
+ * Provides accessor bridge between grid data and formula coordinates.
+ * Tree-shakeable: if `formulas` is false, no formula code is loaded.
+ */
+import { type Ref } from 'vue';
+import { type IGridDataAccessor, type IFormulaFunction, type IRecalcResult, type IColumnDef, type IAuditEntry, type IAuditTrail } from '@alaarab/ogrid-core';
+export interface UseFormulaEngineParams<T> {
+    /** Enable formula support. */
+    formulas?: Ref<boolean>;
+    /** Grid data items. */
+    items: Ref<T[]>;
+    /** Flat leaf columns (for mapping column index <-> columnId). */
+    flatColumns: Ref<IColumnDef<T>[]>;
+    /** Initial formulas to load. */
+    initialFormulas?: Array<{
+        col: number;
+        row: number;
+        formula: string;
+    }>;
+    /** Called when recalculation produces cascading updates. */
+    onFormulaRecalc?: (result: IRecalcResult) => void;
+    /** Custom formula functions. */
+    formulaFunctions?: Record<string, IFormulaFunction>;
+    /** Named ranges: name → cell/range reference string. */
+    namedRanges?: Record<string, string>;
+    /** Sheet accessors for cross-sheet references. */
+    sheets?: Record<string, IGridDataAccessor>;
+}
+export interface UseFormulaEngineResult {
+    /** Whether formula support is active. */
+    enabled: Ref<boolean>;
+    /** Get the formula engine's computed value for a cell coordinate. */
+    getFormulaValue: (col: number, row: number) => unknown;
+    /** Check if a cell has a formula. */
+    hasFormula: (col: number, row: number) => boolean;
+    /** Get the formula string for a cell. */
+    getFormula: (col: number, row: number) => string | undefined;
+    /** Set or clear a formula for a cell. Triggers recalculation. */
+    setFormula: (col: number, row: number, formula: string | null) => void;
+    /** Notify the engine that a non-formula cell value changed. Triggers dependent recalc. */
+    onCellChanged: (col: number, row: number) => 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;
+}
+export declare function useFormulaEngine<T>(params: UseFormulaEngineParams<T>): UseFormulaEngineResult;

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

@@ -1,7 +1,7 @@
 import type { IColumnDef, IColumnGroupDef, ICellValueChangedEvent } from './columnTypes';
-export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IOGridApi, IVirtualScrollConfig, } from '@alaarab/ogrid-core';
+export type { RowId, UserLike, UserLikeInput, FilterValue, IFilters, IFetchParams, IPageResult, IDataSource, IGridColumnState, RowSelectionMode, IRowSelectionChangeEvent, StatusBarPanel, IStatusBarProps, IActiveCell, ISelectionRange, SideBarPanelId, ISideBarDef, IOGridApi, IVirtualScrollConfig, IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail, } from '@alaarab/ogrid-core';
 export { toUserLike, isInSelectionRange, normalizeSelectionRange } from '@alaarab/ogrid-core';
-import type { RowId, UserLike, IFilters, FilterValue, RowSelectionMode, IRowSelectionChangeEvent, IStatusBarProps, IDataSource, ISideBarDef, IVirtualScrollConfig } from '@alaarab/ogrid-core';
+import type { RowId, UserLike, IFilters, FilterValue, RowSelectionMode, IRowSelectionChangeEvent, IStatusBarProps, IDataSource, ISideBarDef, IVirtualScrollConfig, IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail } from '@alaarab/ogrid-core';
 /** Base props shared by both client-side and server-side OGrid modes. */
 interface IOGridBaseProps<T> {
     columns: (IColumnDef<T> | IColumnGroupDef<T>)[];
@@ -42,6 +42,8 @@ interface IOGridBaseProps<T> {
     onSelectionChange?: (event: IRowSelectionChangeEvent<T>) => void;
     /** Show Excel-style row numbers column at the start of the grid (1, 2, 3...). Default: false. */
     showRowNumbers?: boolean;
+    /** Enable Excel-style cell references: column letter headers, row numbers, and name box. Implies showRowNumbers. */
+    cellReferences?: boolean;
     statusBar?: boolean | IStatusBarProps;
     defaultPageSize?: number;
     defaultSortBy?: string;
@@ -87,6 +89,22 @@ interface IOGridBaseProps<T> {
     rowHeight?: number;
     /** Cell spacing/density preset. Controls cell padding throughout the grid. Default: 'normal'. */
     density?: 'compact' | 'normal' | 'comfortable';
+    /** 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>;
     'aria-label'?: string;
     'aria-labelledby'?: string;
 }
@@ -144,6 +162,10 @@ export interface IOGridDataGridProps<T> {
     selectedRows?: Set<RowId>;
     onSelectionChange?: (event: IRowSelectionChangeEvent<T>) => void;
     showRowNumbers?: boolean;
+    showColumnLetters?: boolean;
+    showNameBox?: boolean;
+    /** Callback when the active cell changes. Used by the name box to display the current cell reference. */
+    onActiveCellChange?: (ref: string | null) => void;
     currentPage?: number;
     pageSize?: number;
     statusBar?: IStatusBarProps;
@@ -175,4 +197,22 @@ export interface IOGridDataGridProps<T> {
     'aria-labelledby'?: string;
     /** Custom keydown handler. Called before grid's built-in handling. Call event.preventDefault() to suppress grid default. */
     onKeyDown?: (event: KeyboardEvent) => void;
+    /** Enable formula support. When true, cell values starting with '=' are treated as formulas. */
+    formulas?: boolean;
+    /** Get the formula engine's computed value for a cell, or undefined if no formula. */
+    getFormulaValue?: (col: number, row: number) => unknown;
+    /** Check if a cell has a formula. */
+    hasFormula?: (col: number, row: number) => boolean;
+    /** Get the formula string for a cell. */
+    getFormula?: (col: number, row: number) => string | undefined;
+    /** Set a formula for a cell (called from edit commit when value starts with '='). */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
+    /** Notify the formula engine that a non-formula cell changed. */
+    onFormulaCellChanged?: (col: number, row: number) => 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;
 }

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

@@ -26,6 +26,7 @@ export interface CellInteractionHandlers {
 export interface CellInteractionProps {
     'data-row-index': number;
     'data-col-index': number;
+    'data-active-cell'?: 'true';
     'data-in-range'?: 'true';
     tabindex: number;
     role?: 'button';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-vue",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "OGrid Vue – Vue 3 composables, headless components, and utilities for OGrid data grids.",
   "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.3.0"
   },
   "peerDependencies": {
     "vue": "^3.3.0"