@alaarab/ogrid-vue 2.2.0 → 2.4.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, FORMULA_BAR_STYLES, handleFormulaBarKeyDown, measureRange, FORMULA_REF_COLORS, deriveFormulaBarText, extractFormulaReferences, 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, processFormulaBarCommit, applyCellDeletion, computeTabNavigation, computeArrowNavigation, computeNextSortState, mergeFilter, columnLetterToIndex, getCellValue, applyRangeRowSelection, getScrollTopForRow, FormulaEngine, calculateDropTarget, reorderColumnArray, createGridDataAccessor, 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';
@@ -173,6 +173,211 @@ var StatusBar = defineComponent({
     };
   }
 });
+var FormulaBar = defineComponent({
+  name: "FormulaBar",
+  props: {
+    cellRef: { type: [String, null], default: null },
+    formulaText: { type: String, required: true },
+    isEditing: { type: Boolean, required: true }
+  },
+  emits: ["inputChange", "commit", "cancel", "startEditing"],
+  setup(props, { emit }) {
+    const inputRef = ref(null);
+    watch(() => props.isEditing, (editing) => {
+      if (editing && inputRef.value) {
+        inputRef.value.focus();
+      }
+    });
+    return () => h("div", { style: FORMULA_BAR_STYLES.bar, role: "toolbar", "aria-label": "Formula bar" }, [
+      h(
+        "div",
+        { style: FORMULA_BAR_STYLES.nameBox, "aria-label": "Active cell reference" },
+        props.cellRef ?? "\u2014"
+      ),
+      h("div", { style: FORMULA_BAR_STYLES.fxLabel, "aria-hidden": "true" }, "fx"),
+      h("input", {
+        ref: inputRef,
+        type: "text",
+        style: FORMULA_BAR_STYLES.input,
+        value: props.formulaText,
+        readonly: !props.isEditing,
+        onInput: (e) => emit("inputChange", e.target.value),
+        onKeydown: (e) => handleFormulaBarKeyDown(e.key, () => e.preventDefault(), () => emit("commit"), () => emit("cancel")),
+        onClick: () => {
+          if (!props.isEditing) emit("startEditing");
+        },
+        onDblclick: () => {
+          if (!props.isEditing) emit("startEditing");
+        },
+        "aria-label": "Formula input",
+        spellcheck: false,
+        autocomplete: "off"
+      })
+    ]);
+  }
+});
+var barStyle = {
+  display: "flex",
+  alignItems: "center",
+  borderTop: "1px solid var(--ogrid-border, #e0e0e0)",
+  background: "var(--ogrid-header-bg, #f5f5f5)",
+  minHeight: "30px",
+  overflowX: "auto",
+  overflowY: "hidden",
+  gap: "0",
+  fontSize: "12px"
+};
+var addBtnStyle = {
+  background: "none",
+  border: "none",
+  cursor: "pointer",
+  padding: "4px 10px",
+  fontSize: "16px",
+  lineHeight: "22px",
+  color: "var(--ogrid-fg-secondary, #666)",
+  flexShrink: 0
+};
+var tabBaseStyle = {
+  background: "none",
+  border: "none",
+  borderBottom: "2px solid transparent",
+  cursor: "pointer",
+  padding: "4px 16px",
+  fontSize: "12px",
+  lineHeight: "22px",
+  color: "var(--ogrid-fg, #242424)",
+  whiteSpace: "nowrap",
+  position: "relative"
+};
+var activeTabStyle = {
+  ...tabBaseStyle,
+  fontWeight: 600,
+  borderBottomColor: "var(--ogrid-primary, #217346)",
+  background: "var(--ogrid-bg, #fff)"
+};
+var SheetTabs = defineComponent({
+  name: "SheetTabs",
+  props: {
+    sheets: { type: Array, required: true },
+    activeSheet: { type: String, required: true },
+    showAddButton: { type: Boolean, default: false }
+  },
+  emits: ["sheetChange", "sheetAdd"],
+  setup(props, { emit }) {
+    return () => h("div", { style: barStyle, role: "tablist", "aria-label": "Sheet tabs" }, [
+      props.showAddButton ? h("button", {
+        type: "button",
+        style: addBtnStyle,
+        onClick: () => emit("sheetAdd"),
+        title: "Add sheet",
+        "aria-label": "Add sheet"
+      }, "+") : null,
+      ...props.sheets.map((sheet) => {
+        const isActive = sheet.id === props.activeSheet;
+        const base = isActive ? activeTabStyle : tabBaseStyle;
+        const style = isActive && sheet.color ? { ...base, borderBottomColor: sheet.color } : base;
+        return h("button", {
+          key: sheet.id,
+          type: "button",
+          role: "tab",
+          "aria-selected": isActive,
+          style,
+          onClick: () => emit("sheetChange", sheet.id)
+        }, sheet.name);
+      })
+    ]);
+  }
+});
+function measureRef(container, r, colOffset) {
+  const startCol = r.col + colOffset;
+  const endCol = (r.endCol ?? r.col) + colOffset;
+  const endRow = r.endRow ?? r.row;
+  const tl = container.querySelector(
+    `[data-row-index="${r.row}"][data-col-index="${startCol}"]`
+  );
+  const br = container.querySelector(
+    `[data-row-index="${endRow}"][data-col-index="${endCol}"]`
+  );
+  if (!tl || !br) return null;
+  const cRect = container.getBoundingClientRect();
+  const tlRect = tl.getBoundingClientRect();
+  const brRect = br.getBoundingClientRect();
+  return {
+    top: Math.round(tlRect.top - cRect.top),
+    left: Math.round(tlRect.left - cRect.left),
+    width: Math.round(brRect.right - tlRect.left),
+    height: Math.round(brRect.bottom - tlRect.top),
+    color: FORMULA_REF_COLORS[r.colorIndex % FORMULA_REF_COLORS.length]
+  };
+}
+var FormulaRefOverlay = defineComponent({
+  name: "FormulaRefOverlay",
+  props: {
+    containerEl: { type: Object, default: null },
+    references: { type: Array, required: true },
+    colOffset: { type: Number, required: true }
+  },
+  setup(props) {
+    const rects = ref([]);
+    let rafId = 0;
+    function measureAll() {
+      const container = props.containerEl;
+      const refs = props.references;
+      if (!container || refs.length === 0) {
+        rects.value = [];
+        return;
+      }
+      const measured = [];
+      for (const r of refs) {
+        const rect = measureRef(container, r, props.colOffset);
+        if (rect) measured.push(rect);
+      }
+      rects.value = measured;
+    }
+    watch(
+      () => [props.references, props.containerEl, props.colOffset],
+      () => {
+        cancelAnimationFrame(rafId);
+        if (!props.containerEl || props.references.length === 0) {
+          rects.value = [];
+          return;
+        }
+        rafId = requestAnimationFrame(measureAll);
+      },
+      { immediate: true }
+    );
+    return () => {
+      if (rects.value.length === 0) return null;
+      return rects.value.map(
+        (r, i) => h("svg", {
+          key: i,
+          style: {
+            position: "absolute",
+            top: `${r.top}px`,
+            left: `${r.left}px`,
+            width: `${r.width}px`,
+            height: `${r.height}px`,
+            pointerEvents: "none",
+            zIndex: 3,
+            overflow: "visible"
+          },
+          "aria-hidden": "true"
+        }, [
+          h("rect", {
+            x: "1",
+            y: "1",
+            width: Math.max(0, r.width - 2),
+            height: Math.max(0, r.height - 2),
+            fill: "none",
+            stroke: r.color,
+            "stroke-width": "2",
+            style: "shape-rendering: crispEdges"
+          })
+        ])
+      );
+    };
+  }
+});
 function useFilterOptions(dataSource, fields) {
   const filterOptions = ref({});
   const loadingOptions = ref({});
@@ -210,6 +415,163 @@ 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() {
+    return createGridDataAccessor(itemsRef.value, flatColumnsRef.value);
+  }
+  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
+  };
+}
+function useFormulaBar(params) {
+  const { activeCol, activeRow, activeCellRef, getFormula, getRawValue, setFormula, onCellValueChanged } = params;
+  const isEditing = ref(false);
+  const editText = ref("");
+  const isFormulaBarEditing = ref(false);
+  const displayText = computed(
+    () => deriveFormulaBarText(activeCol.value, activeRow.value, getFormula, getRawValue)
+  );
+  watch([activeCol, activeRow], () => {
+    isEditing.value = false;
+    isFormulaBarEditing.value = false;
+  });
+  const startEditing = () => {
+    editText.value = displayText.value;
+    isEditing.value = true;
+    isFormulaBarEditing.value = true;
+  };
+  const onInputChange = (text) => {
+    editText.value = text;
+  };
+  const onCommit = () => {
+    const col = activeCol.value;
+    const row = activeRow.value;
+    if (col == null || row == null || !setFormula) return;
+    processFormulaBarCommit(editText.value, col, row, setFormula, onCellValueChanged);
+    isEditing.value = false;
+    isFormulaBarEditing.value = false;
+  };
+  const onCancel = () => {
+    isEditing.value = false;
+    isFormulaBarEditing.value = false;
+    editText.value = "";
+  };
+  const formulaText = computed(() => isEditing.value ? editText.value : displayText.value);
+  const referencedCells = computed(() => extractFormulaReferences(formulaText.value));
+  return {
+    cellRef: activeCellRef,
+    formulaText,
+    isEditing,
+    onInputChange,
+    onCommit,
+    onCancel,
+    startEditing,
+    referencedCells,
+    isFormulaBarEditing
+  };
+}
 var DEFAULT_PANELS = ["columns", "filters"];
 function useSideBarState(params) {
   const { config } = params;
@@ -494,6 +856,22 @@ function useOGrid(props) {
   const displayTotalCount = computed(
     () => isClientSide.value && resolvedClientItems.value ? resolvedClientItems.value.totalCount : serverTotalCount.value
   );
+  const formulasRef = computed(() => !!props.value.formulas);
+  const formulaVersionRef = ref(0);
+  const wrappedOnFormulaRecalc = (result) => {
+    formulaVersionRef.value += 1;
+    props.value.onFormulaRecalc?.(result);
+  };
+  const formulaEngine = useFormulaEngine({
+    formulas: formulasRef,
+    items: displayItems,
+    flatColumns: columns,
+    initialFormulas: props.value.initialFormulas,
+    onFormulaRecalc: wrappedOnFormulaRecalc,
+    formulaFunctions: props.value.formulaFunctions,
+    namedRanges: props.value.namedRanges,
+    sheets: props.value.sheets
+  });
   let firstDataRendered = false;
   let rowIdsValidated = false;
   watch(displayItems, (items) => {
@@ -581,6 +959,37 @@ function useOGrid(props) {
   });
   const clearAllFilters = () => setFilters({});
   const isLoadingResolved = computed(() => isServerSide.value && loading.value || displayLoading.value);
+  const activeCellRef = ref(null);
+  const activeCellCoords = ref(null);
+  const onActiveCellChange = (cellRef) => {
+    activeCellRef.value = cellRef;
+    if (cellRef) {
+      const m = cellRef.match(/^([A-Z]+)(\d+)$/);
+      if (m) {
+        activeCellCoords.value = { col: columnLetterToIndex(m[1]), row: parseInt(m[2], 10) - 1 };
+      } else {
+        activeCellCoords.value = null;
+      }
+    } else {
+      activeCellCoords.value = null;
+    }
+  };
+  const formulaBarActiveCol = computed(() => activeCellCoords.value?.col ?? null);
+  const formulaBarActiveRow = computed(() => activeCellCoords.value?.row ?? null);
+  const getRawValue = (col, row) => {
+    const items = displayItems.value;
+    const cols = columns.value;
+    if (row < 0 || row >= items.length || col < 0 || col >= cols.length) return void 0;
+    return getCellValue(items[row], cols[col]);
+  };
+  const formulaBarState = useFormulaBar({
+    activeCol: formulaBarActiveCol,
+    activeRow: formulaBarActiveRow,
+    activeCellRef,
+    getFormula: formulaEngine.enabled.value ? formulaEngine.getFormula : void 0,
+    getRawValue,
+    setFormula: formulaEngine.enabled.value ? formulaEngine.setFormula : void 0
+  });
   const dataGridProps = computed(() => {
     const p = props.value;
     const ds = dataProps.value.dataSource;
@@ -608,7 +1017,11 @@ function useOGrid(props) {
       rowSelection: p.rowSelection ?? "none",
       selectedRows: effectiveSelectedRows.value,
       onSelectionChange: handleSelectionChange,
-      showRowNumbers: p.showRowNumbers,
+      showRowNumbers: p.showRowNumbers || p.cellReferences || p.formulas,
+      showColumnLetters: !!(p.cellReferences || p.formulas),
+      showNameBox: !!(p.cellReferences && !p.formulas),
+      // formula bar includes name box
+      onActiveCellChange: p.cellReferences || p.formulas ? onActiveCellChange : void 0,
       currentPage: page.value,
       pageSize: pageSize.value,
       statusBar: statusBarConfig.value,
@@ -633,7 +1046,20 @@ function useOGrid(props) {
         onClearAll: clearAllFilters,
         message: p.emptyState?.message,
         render: p.emptyState?.render
-      }
+      },
+      formulas: p.formulas,
+      formulaVersion: formulaVersionRef.value,
+      ...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
+      } : {},
+      formulaReferences: formulaBarState.referencedCells.value.length > 0 ? formulaBarState.referencedCells.value : void 0
     };
   });
   const pagination = computed(() => ({
@@ -651,14 +1077,59 @@ 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 p = props.value;
+    const formulas = !!p.formulas;
+    const showNameBox = !!p.cellReferences && !formulas;
+    let resolvedToolbar = p.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];
+    }
+    const formulaBarEl = formulas ? h(FormulaBar, {
+      cellRef: formulaBarState.cellRef.value,
+      formulaText: formulaBarState.formulaText.value,
+      isEditing: formulaBarState.isEditing.value,
+      onInputChange: formulaBarState.onInputChange,
+      onCommit: formulaBarState.onCommit,
+      onCancel: formulaBarState.onCancel,
+      onStartEditing: formulaBarState.startEditing
+    }) : void 0;
+    const sheetTabsEl = p.sheetDefs && p.sheetDefs.length > 0 && p.activeSheet && p.onSheetChange ? h(SheetTabs, {
+      sheets: p.sheetDefs,
+      activeSheet: p.activeSheet,
+      showAddButton: !!p.onSheetAdd,
+      onSheetChange: p.onSheetChange,
+      onSheetAdd: p.onSheetAdd ?? (() => {
+      })
+    }) : void 0;
+    return {
+      toolbar: resolvedToolbar,
+      toolbarBelow: p.toolbarBelow,
+      className: p.className,
+      emptyState: p.emptyState,
+      sideBarProps: sideBarProps.value,
+      fullScreen: p.fullScreen,
+      formulaBar: formulaBarEl,
+      sheetTabs: sheetTabsEl
+    };
+  });
   const filtersResult = computed(() => ({
     hasActiveFilters: hasActiveFilters.value,
     setFilters
@@ -880,23 +1351,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 +1767,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 +1867,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();
@@ -2263,7 +2747,10 @@ function useDataGridState(params) {
     getRowId,
     editable: editableProp.value,
     onCellValueChanged: onCellValueChanged.value,
-    isDragging: cellSelection.value ? isDragging.value : false
+    isDragging: cellSelection.value ? isDragging.value : false,
+    getFormulaValue: props.value.getFormulaValue,
+    hasFormula: props.value.hasFormula,
+    formulaVersion: props.value.formulaVersion
   }));
   const popoverAnchorEl = ref(null);
   const setPopoverAnchorEl = (el) => {
@@ -2952,9 +3439,14 @@ function useColumnChooserState(params) {
 }
 function useInlineCellEditorState(params) {
   const { value, editorType, onCommit, onCancel } = params;
-  const localValue = ref(
-    value !== null && value !== void 0 ? String(value) : ""
-  );
+  const localValue = ref((() => {
+    if (value === null || value === void 0) return "";
+    if (editorType === "date") {
+      const str = String(value);
+      return str.match(/^\d{4}-\d{2}-\d{2}/) ? str.substring(0, 10) : str;
+    }
+    return String(value);
+  })());
   const setLocalValue = (v) => {
     localValue.value = v;
   };
@@ -2970,14 +3462,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 +3828,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 +3864,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 - state.layout.value.colOffset, offset + ac.rowIndex + 1));
+          } else {
+            cb(null);
+          }
+        },
+        { immediate: true }
+      );
       const onWrapperMousedown = (e) => {
         lastMouseShift.value = e.shiftKey;
       };
@@ -3446,7 +3957,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 +4047,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 +4156,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 +4282,7 @@ function createDataGridTable(ui) {
                           })
                         ])
                       )
-                    ),
+                    ]),
                     // Body
                     ...!showEmptyInGrid ? [
                       h("tbody", {}, (() => {
@@ -3822,7 +4347,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 ? [
@@ -3893,6 +4418,14 @@ function createDataGridTable(ui) {
             columnSizingOverrides: layout.columnSizingOverrides,
             columnOrder: p.columnOrder
           }),
+          // Formula reference overlay
+          ...p.formulaReferences && p.formulaReferences.length > 0 ? [
+            h(FormulaRefOverlay, {
+              containerEl: tableContainerRef.value,
+              references: p.formulaReferences,
+              colOffset: _colOffset
+            })
+          ] : [],
           // Column header menu
           h(ui.ColumnHeaderMenu, {
             isOpen: headerMenu.isOpen,
@@ -3978,6 +4511,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 +4617,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),
@@ -4493,8 +5027,12 @@ function createOGrid(ui) {
                 style: { padding: "8px 12px", borderBottom: "1px solid var(--ogrid-border, rgba(0,0,0,0.12))" }
               }, [layout.value.toolbarBelow])
             ] : [],
+            // Formula bar (between toolbar and grid)
+            ...layout.value.formulaBar ? [layout.value.formulaBar] : [],
             // Main content area (sidebar + grid)
             h("div", { style: { display: "flex", flex: "1", minHeight: "0" } }, mainAreaChildren),
+            // Sheet tabs (between grid and footer)
+            ...layout.value.sheetTabs ? [layout.value.sheetTabs] : [],
             // Footer strip (pagination)
             h("div", {
               style: {
@@ -4511,4 +5049,4 @@ function createOGrid(ui) {
   });
 }
 
-export { MarchingAntsOverlay, StatusBar, createDataGridTable, createInlineCellEditor, createOGrid, getCellInteractionProps, useActiveCell, useCellEditing, useCellSelection, useClipboard, useColumnChooserState, useColumnHeaderFilterState, useColumnHeaderMenuState, useColumnPinning, useColumnReorder, useColumnResize, useContextMenu, useDataGridState, useDataGridTableSetup, useDateFilterState, useDebounce, useDebouncedCallback, useFillHandle, useFilterOptions, useInlineCellEditorState, useKeyboardNavigation, useMultiSelectFilterState, useOGrid, usePeopleFilterState, useRichSelectState, useRowSelection, useSideBarState, useTableLayout, useTextFilterState, useUndoRedo, useVirtualScroll };
+export { FormulaBar, FormulaRefOverlay, MarchingAntsOverlay, SheetTabs, StatusBar, createDataGridTable, createInlineCellEditor, createOGrid, getCellInteractionProps, useActiveCell, useCellEditing, useCellSelection, useClipboard, useColumnChooserState, useColumnHeaderFilterState, useColumnHeaderMenuState, useColumnPinning, useColumnReorder, useColumnResize, useContextMenu, useDataGridState, useDataGridTableSetup, useDateFilterState, useDebounce, useDebouncedCallback, useFillHandle, useFilterOptions, useFormulaBar, useInlineCellEditorState, useKeyboardNavigation, useMultiSelectFilterState, useOGrid, usePeopleFilterState, useRichSelectState, useRowSelection, useSideBarState, useTableLayout, useTextFilterState, useUndoRedo, useVirtualScroll };

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/components/FormulaBar.d.ts

@@ -0,0 +1,52 @@
+/**
+ * FormulaBar — Headless Excel-style formula bar component.
+ *
+ * Layout: [Name Box] [fx] [Formula Input]
+ *
+ * Uses --ogrid-* CSS variables for theming.
+ */
+import { type PropType } from 'vue';
+export interface FormulaBarProps {
+    /** Active cell reference (e.g. "A1"). */
+    cellRef: string | null;
+    /** Text displayed/edited in the formula input. */
+    formulaText: string;
+    /** Whether the input is in editing mode. */
+    isEditing: boolean;
+}
+export declare const FormulaBar: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    cellRef: {
+        type: PropType<string | null>;
+        default: null;
+    };
+    formulaText: {
+        type: StringConstructor;
+        required: true;
+    };
+    isEditing: {
+        type: BooleanConstructor;
+        required: true;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("cancel" | "inputChange" | "commit" | "startEditing")[], "cancel" | "inputChange" | "commit" | "startEditing", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    cellRef: {
+        type: PropType<string | null>;
+        default: null;
+    };
+    formulaText: {
+        type: StringConstructor;
+        required: true;
+    };
+    isEditing: {
+        type: BooleanConstructor;
+        required: true;
+    };
+}>> & Readonly<{
+    onCancel?: ((...args: any[]) => any) | undefined;
+    onInputChange?: ((...args: any[]) => any) | undefined;
+    onCommit?: ((...args: any[]) => any) | undefined;
+    onStartEditing?: ((...args: any[]) => any) | undefined;
+}>, {
+    cellRef: string | null;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

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

@@ -0,0 +1,39 @@
+/**
+ * FormulaRefOverlay — Renders colored border overlays on cells referenced by
+ * the active formula, like Excel's reference highlighting.
+ *
+ * Port of React's FormulaRefOverlay component.
+ */
+import { type PropType } from 'vue';
+import { type FormulaReference } from '@alaarab/ogrid-core';
+export declare const FormulaRefOverlay: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    containerEl: {
+        type: PropType<HTMLElement | null>;
+        default: null;
+    };
+    references: {
+        type: PropType<FormulaReference[]>;
+        required: true;
+    };
+    colOffset: {
+        type: NumberConstructor;
+        required: true;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>[] | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    containerEl: {
+        type: PropType<HTMLElement | null>;
+        default: null;
+    };
+    references: {
+        type: PropType<FormulaReference[]>;
+        required: true;
+    };
+    colOffset: {
+        type: NumberConstructor;
+        required: true;
+    };
+}>> & Readonly<{}>, {
+    containerEl: HTMLElement | null;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

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

@@ -0,0 +1,45 @@
+/**
+ * SheetTabs — Excel-style sheet tab bar at the bottom of the grid.
+ *
+ * Layout: [+] [Sheet1] [Sheet2] [Sheet3]
+ */
+import { type PropType } from 'vue';
+import type { ISheetDef } from '@alaarab/ogrid-core';
+export interface SheetTabsProps {
+    sheets: ISheetDef[];
+    activeSheet: string;
+}
+export declare const SheetTabs: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    sheets: {
+        type: PropType<ISheetDef[]>;
+        required: true;
+    };
+    activeSheet: {
+        type: StringConstructor;
+        required: true;
+    };
+    showAddButton: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, ("sheetChange" | "sheetAdd")[], "sheetChange" | "sheetAdd", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    sheets: {
+        type: PropType<ISheetDef[]>;
+        required: true;
+    };
+    activeSheet: {
+        type: StringConstructor;
+        required: true;
+    };
+    showAddButton: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onSheetChange?: ((...args: any[]) => any) | undefined;
+    onSheetAdd?: ((...args: any[]) => any) | undefined;
+}>, {
+    showAddButton: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

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

@@ -30,6 +30,10 @@ 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 { useFormulaBar } from './useFormulaBar';
+export type { UseFormulaBarParams, UseFormulaBarResult } from './useFormulaBar';
 export { useColumnHeaderFilterState } from './useColumnHeaderFilterState';
 export type { UseColumnHeaderFilterStateParams, UseColumnHeaderFilterStateResult, } from './useColumnHeaderFilterState';
 export { useTextFilterState } from './useTextFilterState';

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

@@ -0,0 +1,44 @@
+/**
+ * useFormulaBar — Vue composable for formula bar state.
+ *
+ * Manages the formula bar text, editing mode, and reference extraction.
+ */
+import { type Ref } from 'vue';
+import { type FormulaReference } from '@alaarab/ogrid-core';
+export interface UseFormulaBarParams {
+    /** Active cell column index (0-based). */
+    activeCol: Ref<number | null>;
+    /** Active cell row index (0-based). */
+    activeRow: Ref<number | null>;
+    /** Active cell reference string (e.g. "A1"). */
+    activeCellRef: Ref<string | null>;
+    /** Get formula string for a cell. */
+    getFormula?: (col: number, row: number) => string | undefined;
+    /** Get raw display value for a cell. */
+    getRawValue?: (col: number, row: number) => unknown;
+    /** Set formula for a cell. */
+    setFormula?: (col: number, row: number, formula: string | null) => void;
+    /** Commit a non-formula value change. */
+    onCellValueChanged?: (col: number, row: number, value: unknown) => void;
+}
+export interface UseFormulaBarResult {
+    /** Cell reference string (e.g. "A1"). */
+    cellRef: Ref<string | null>;
+    /** Text shown in the formula bar input. */
+    formulaText: Ref<string>;
+    /** Whether the formula bar input is being edited. */
+    isEditing: Ref<boolean>;
+    /** Update the formula bar input text. */
+    onInputChange: (text: string) => void;
+    /** Commit the current edit. */
+    onCommit: () => void;
+    /** Cancel the current edit. */
+    onCancel: () => void;
+    /** Start editing the formula bar. */
+    startEditing: () => void;
+    /** References extracted from the current formula text (for highlighting). */
+    referencedCells: Ref<FormulaReference[]>;
+    /** Whether the formula bar is actively being edited (for click-to-insert-ref guards). */
+    isFormulaBarEditing: Ref<boolean>;
+}
+export declare function useFormulaBar(params: UseFormulaBarParams): UseFormulaBarResult;

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/composables/useOGrid.d.ts

@@ -31,6 +31,10 @@ export interface UseOGridLayout {
     };
     sideBarProps: SideBarProps | null;
     fullScreen?: boolean;
+    /** Formula bar element (rendered between toolbar and grid). */
+    formulaBar?: unknown;
+    /** Sheet tabs element (rendered between grid and footer). */
+    sheetTabs?: unknown;
 }
 /** Filter state. */
 export interface UseOGridFilters {

package/dist/types/index.d.ts

@@ -4,8 +4,11 @@ export type { ColumnFilterType, IColumnFilterDef, IColumnMeta, IColumnGroupDef,
 export { toUserLike, isInSelectionRange, normalizeSelectionRange } from './types';
 export { MarchingAntsOverlay } from './components/MarchingAntsOverlay';
 export { StatusBar, type StatusBarProps } from './components/StatusBar';
-export { useOGrid, useDataGridState, useActiveCell, useCellEditing, useCellSelection, useClipboard, useRowSelection, useKeyboardNavigation, useFillHandle, useUndoRedo, useContextMenu, useColumnResize, useColumnReorder, useVirtualScroll, useFilterOptions, useDebounce, useDebouncedCallback, useTableLayout, useColumnHeaderFilterState, useTextFilterState, useMultiSelectFilterState, usePeopleFilterState, useDateFilterState, useColumnChooserState, useInlineCellEditorState, useRichSelectState, useSideBarState, useColumnPinning, useColumnHeaderMenuState, useDataGridTableSetup, } from './composables';
-export type { UseOGridResult, UseOGridPagination, UseOGridColumnChooser, UseOGridLayout, UseOGridFilters, ColumnChooserPlacement, UseDataGridStateParams, UseDataGridStateResult, DataGridLayoutState, DataGridRowSelectionState, DataGridEditingState, DataGridCellInteractionState, DataGridContextMenuState, DataGridViewModelState, DataGridPinningState, UseActiveCellResult, EditingCell, UseCellEditingParams, UseCellEditingResult, UseCellSelectionParams, UseCellSelectionResult, UseClipboardParams, UseClipboardResult, UseRowSelectionParams, UseRowSelectionResult, UseKeyboardNavigationParams, UseKeyboardNavigationResult, UseFillHandleParams, UseFillHandleResult, UseUndoRedoParams, UseUndoRedoResult, ContextMenuPosition, UseContextMenuResult, UseColumnResizeParams, UseColumnResizeResult, UseColumnReorderParams, UseColumnReorderResult, UseVirtualScrollParams, UseVirtualScrollResult, UseFilterOptionsResult, UseTableLayoutParams, UseTableLayoutResult, UseColumnHeaderFilterStateParams, UseColumnHeaderFilterStateResult, UseTextFilterStateParams, UseTextFilterStateResult, UseMultiSelectFilterStateParams, UseMultiSelectFilterStateResult, UsePeopleFilterStateParams, UsePeopleFilterStateResult, UseDateFilterStateParams, UseDateFilterStateResult, UseColumnChooserStateParams, UseColumnChooserStateResult, InlineCellEditorType, UseInlineCellEditorStateParams, UseInlineCellEditorStateResult, UseRichSelectStateParams, UseRichSelectStateResult, UseSideBarStateParams, UseSideBarStateResult, DebouncedFn, UseColumnPinningParams, UseColumnPinningResult, UseColumnHeaderMenuStateParams, UseColumnHeaderMenuStateResult, UseDataGridTableSetupParams, UseDataGridTableSetupResult, MaybeShallowRef, } from './composables';
+export { FormulaBar, type FormulaBarProps } from './components/FormulaBar';
+export { SheetTabs, type SheetTabsProps } from './components/SheetTabs';
+export { FormulaRefOverlay } from './components/FormulaRefOverlay';
+export { useOGrid, useDataGridState, useActiveCell, useCellEditing, useCellSelection, useClipboard, useRowSelection, useKeyboardNavigation, useFillHandle, useUndoRedo, useContextMenu, useColumnResize, useColumnReorder, useVirtualScroll, useFilterOptions, useDebounce, useDebouncedCallback, useTableLayout, useColumnHeaderFilterState, useTextFilterState, useMultiSelectFilterState, usePeopleFilterState, useDateFilterState, useColumnChooserState, useInlineCellEditorState, useRichSelectState, useSideBarState, useColumnPinning, useColumnHeaderMenuState, useDataGridTableSetup, useFormulaBar, } from './composables';
+export type { UseOGridResult, UseOGridPagination, UseOGridColumnChooser, UseOGridLayout, UseOGridFilters, ColumnChooserPlacement, UseDataGridStateParams, UseDataGridStateResult, DataGridLayoutState, DataGridRowSelectionState, DataGridEditingState, DataGridCellInteractionState, DataGridContextMenuState, DataGridViewModelState, DataGridPinningState, UseActiveCellResult, EditingCell, UseCellEditingParams, UseCellEditingResult, UseCellSelectionParams, UseCellSelectionResult, UseClipboardParams, UseClipboardResult, UseRowSelectionParams, UseRowSelectionResult, UseKeyboardNavigationParams, UseKeyboardNavigationResult, UseFillHandleParams, UseFillHandleResult, UseUndoRedoParams, UseUndoRedoResult, ContextMenuPosition, UseContextMenuResult, UseColumnResizeParams, UseColumnResizeResult, UseColumnReorderParams, UseColumnReorderResult, UseVirtualScrollParams, UseVirtualScrollResult, UseFilterOptionsResult, UseTableLayoutParams, UseTableLayoutResult, UseColumnHeaderFilterStateParams, UseColumnHeaderFilterStateResult, UseTextFilterStateParams, UseTextFilterStateResult, UseMultiSelectFilterStateParams, UseMultiSelectFilterStateResult, UsePeopleFilterStateParams, UsePeopleFilterStateResult, UseDateFilterStateParams, UseDateFilterStateResult, UseColumnChooserStateParams, UseColumnChooserStateResult, InlineCellEditorType, UseInlineCellEditorStateParams, UseInlineCellEditorStateResult, UseRichSelectStateParams, UseRichSelectStateResult, UseSideBarStateParams, UseSideBarStateResult, DebouncedFn, UseColumnPinningParams, UseColumnPinningResult, UseColumnHeaderMenuStateParams, UseColumnHeaderMenuStateResult, UseDataGridTableSetupParams, UseDataGridTableSetupResult, MaybeShallowRef, UseFormulaBarParams, UseFormulaBarResult, } from './composables';
 export { getHeaderFilterConfig, getCellRenderDescriptor, resolveCellDisplayContent, resolveCellStyle, buildInlineEditorProps, buildPopoverEditorProps, getCellInteractionProps, } from './utils';
 export type { HeaderFilterConfigInput, HeaderFilterConfig, CellRenderDescriptorInput, CellRenderDescriptor, CellRenderMode, CellInteractionHandlers, CellInteractionProps, } from './utils';
 export { createDataGridTable, type IDataGridTableUIBindings } from './components/createDataGridTable';

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, ISheetDef, FormulaReference, } 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, ISheetDef, FormulaReference } 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,30 @@ 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>;
+    /** Sheet definitions for the tab bar at grid bottom. */
+    sheetDefs?: ISheetDef[];
+    /** Active sheet ID (controlled). */
+    activeSheet?: string;
+    /** Called when user clicks a sheet tab. */
+    onSheetChange?: (sheetId: string) => void;
+    /** Called when user clicks the "+" add sheet button. */
+    onSheetAdd?: () => void;
     'aria-label'?: string;
     'aria-labelledby'?: string;
 }
@@ -144,6 +170,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 +205,26 @@ 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;
+    /** Monotonic counter incremented on each formula recalculation — used for cache invalidation. */
+    formulaVersion?: number;
+    /** Cell references to highlight (from active formula in formula bar). */
+    formulaReferences?: FormulaReference[];
 }

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

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

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.4.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.4.0"
   },
   "peerDependencies": {
     "vue": "^3.3.0"