@alaarab/ogrid-vue 2.1.15 → 2.3.0

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-import { injectGlobalStyles, Z_INDEX, getStatusBarParts, measureRange, flattenColumns, getMultiSelectFilterFields, deriveFilterOptionsFromData, processClientSideData, validateColumns, validateRowIds, computeRowSelectionState, buildCellIndex, UndoRedoStack, CHECKBOX_COLUMN_WIDTH, DEFAULT_MIN_COLUMN_WIDTH, CELL_PADDING, computeAggregations, getDataGridStatusBarConfig, validateVirtualScrollConfig, computeVisibleRange, computeTotalHeight, 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;
@@ -331,7 +451,11 @@ function useOGrid(props) {
     return new Set(visible.length > 0 ? visible : columns.value.map((c) => c.columnId));
   })());
   const columnWidthOverrides = ref({});
-  const pinnedOverrides = ref({});
+  const initialPinned = {};
+  for (const col of flattenColumns(props.value.columns)) {
+    if (col.pinned) initialPinned[col.columnId] = col.pinned;
+  }
+  const pinnedOverrides = ref(initialPinned);
   const page = computed(() => controlledState.value.page ?? internalPage.value);
   const pageSize = computed(() => controlledState.value.pageSize ?? internalPageSize.value);
   const sort = computed(() => controlledState.value.sort ?? internalSort.value);
@@ -389,8 +513,9 @@ function useOGrid(props) {
     if (hasServerFilterOptions.value) return serverFilterOptions.value;
     return deriveFilterOptionsFromData(displayData.value, columns.value);
   });
+  const workerSortEnabled = computed(() => !!props.value.workerSort);
   const clientItemsAndTotal = computed(() => {
-    if (!isClientSide.value) return null;
+    if (!isClientSide.value || workerSortEnabled.value) return null;
     const rows = processClientSideData(
       displayData.value,
       columns.value,
@@ -403,6 +528,42 @@ function useOGrid(props) {
     const paged = rows.slice(start, start + pageSize.value);
     return { items: paged, totalCount: total };
   });
+  const asyncClientItems = ref(null);
+  let workerSortAbortId = 0;
+  watch(
+    [isClientSide, workerSortEnabled, displayData, columns, filters, () => sort.value.field, () => sort.value.direction, page, pageSize],
+    () => {
+      if (!isClientSide.value || !workerSortEnabled.value) return;
+      const data = displayData.value;
+      const cols = columns.value;
+      const f = filters.value;
+      const sf = sort.value.field;
+      const sd = sort.value.direction;
+      const p = page.value;
+      const ps = pageSize.value;
+      const abortId = ++workerSortAbortId;
+      processClientSideDataAsync(data, cols, f, sf, sd).then((rows) => {
+        if (abortId !== workerSortAbortId || isDestroyed) return;
+        const total = rows.length;
+        const start = (p - 1) * ps;
+        const paged = rows.slice(start, start + ps);
+        asyncClientItems.value = { items: paged, totalCount: total };
+      }).catch(() => {
+        if (abortId !== workerSortAbortId || isDestroyed) return;
+        const rows = processClientSideData(data, cols, f, sf, sd);
+        const total = rows.length;
+        const start = (p - 1) * ps;
+        const paged = rows.slice(start, start + ps);
+        asyncClientItems.value = { items: paged, totalCount: total };
+      });
+    },
+    { immediate: true }
+  );
+  const resolvedClientItems = computed(() => {
+    const syncResult = clientItemsAndTotal.value;
+    if (syncResult) return syncResult;
+    return asyncClientItems.value;
+  });
   const serverItems = ref([]);
   const serverTotalCount = ref(0);
   const loading = ref(false);
@@ -448,11 +609,22 @@ function useOGrid(props) {
     isDestroyed = true;
   });
   const displayItems = computed(
-    () => isClientSide.value && clientItemsAndTotal.value ? clientItemsAndTotal.value.items : serverItems.value
+    () => isClientSide.value && resolvedClientItems.value ? resolvedClientItems.value.items : serverItems.value
   );
   const displayTotalCount = computed(
-    () => isClientSide.value && clientItemsAndTotal.value ? clientItemsAndTotal.value.totalCount : serverTotalCount.value
+    () => 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) => {
@@ -540,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;
@@ -567,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,
@@ -592,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(() => ({
@@ -610,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
@@ -839,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;
@@ -1272,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();
       }
@@ -1372,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();
@@ -2929,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);
     }
   };
@@ -3104,13 +3331,24 @@ function useColumnReorder(params) {
 }
 var DEFAULT_PASSTHROUGH_THRESHOLD = 100;
 function useVirtualScroll(params) {
-  const { totalRows, rowHeight, enabled, overscan = 5, threshold = DEFAULT_PASSTHROUGH_THRESHOLD } = params;
+  const {
+    totalRows,
+    rowHeight,
+    enabled,
+    overscan = 5,
+    threshold = DEFAULT_PASSTHROUGH_THRESHOLD,
+    columnsEnabled,
+    columnWidths,
+    columnOverscan = 2
+  } = params;
   onMounted(() => {
     validateVirtualScrollConfig({ enabled: enabled.value, rowHeight });
   });
   const containerRef = ref(null);
   const scrollTop = ref(0);
+  const scrollLeft = ref(0);
   const containerHeight = ref(0);
+  const containerWidth = ref(0);
   let rafId = 0;
   let resizeObserver;
   let prevObservedEl = null;
@@ -3131,6 +3369,17 @@ function useVirtualScroll(params) {
     if (!enabled.value) return 0;
     return computeTotalHeight(totalRows.value, rowHeight);
   });
+  const columnRange = computed(() => {
+    if (!columnsEnabled?.value) return null;
+    const widths = columnWidths?.value;
+    if (!widths || widths.length === 0) return null;
+    return computeVisibleColumnRange(
+      scrollLeft.value,
+      widths,
+      containerWidth.value,
+      columnOverscan
+    );
+  });
   const onScroll = () => {
     if (!rafId) {
       rafId = requestAnimationFrame(() => {
@@ -3138,6 +3387,7 @@ function useVirtualScroll(params) {
         const el = containerRef.value;
         if (el) {
           scrollTop.value = el.scrollTop;
+          scrollLeft.value = el.scrollLeft;
         }
       });
     }
@@ -3146,6 +3396,7 @@ function useVirtualScroll(params) {
     const el = containerRef.value;
     if (!el) return;
     containerHeight.value = el.clientHeight;
+    containerWidth.value = el.clientWidth;
   };
   watch(containerRef, (el) => {
     if (el === prevObservedEl) return;
@@ -3165,6 +3416,7 @@ function useVirtualScroll(params) {
       }
       measure();
       scrollTop.value = el.scrollTop;
+      scrollLeft.value = el.scrollLeft;
     }
   });
   onUnmounted(() => {
@@ -3183,7 +3435,7 @@ function useVirtualScroll(params) {
     if (!el) return;
     el.scrollTop = getScrollTopForRow(index, rowHeight, containerHeight.value, align);
   };
-  return { containerRef, visibleRange, totalHeight, scrollToRow };
+  return { containerRef, visibleRange, totalHeight, scrollToRow, columnRange, scrollLeft };
 }
 function useDataGridTableSetup(params) {
   const { props: propsRef } = params;
@@ -3207,11 +3459,45 @@ function useDataGridTableSetup(params) {
   const totalRowsRef = computed(() => propsRef.value.items.length);
   const rowHeight = propsRef.value.virtualScroll?.rowHeight ?? 36;
   const overscan = propsRef.value.virtualScroll?.overscan ?? 5;
+  const columnsVirtEnabled = computed(() => propsRef.value.virtualScroll?.columns === true);
+  const columnOverscan = propsRef.value.virtualScroll?.columnOverscan ?? 2;
+  const unpinnedColumnWidths = computed(() => {
+    const layout = state.layout.value;
+    const { visibleCols, columnSizingOverrides } = layout;
+    const pinnedCols = propsRef.value.pinnedColumns ?? {};
+    const widths = [];
+    for (const col of visibleCols) {
+      if (pinnedCols[col.columnId] || col.pinned) continue;
+      const override = columnSizingOverrides[col.columnId];
+      widths.push(override ? override.widthPx : col.defaultWidth ?? col.minWidth ?? DEFAULT_MIN_COLUMN_WIDTH);
+    }
+    return widths;
+  });
   const virtualScroll = useVirtualScroll({
     totalRows: totalRowsRef,
     rowHeight,
     enabled: virtualScrollEnabled,
-    overscan
+    overscan,
+    columnsEnabled: columnsVirtEnabled,
+    columnWidths: unpinnedColumnWidths,
+    columnOverscan
+  });
+  const columnPartition = computed(() => {
+    if (!columnsVirtEnabled.value) return null;
+    const layout = state.layout.value;
+    const cols = layout.visibleCols;
+    const range = virtualScroll.columnRange.value;
+    const pinnedCols = propsRef.value.pinnedColumns;
+    return partitionColumnsForVirtualization(cols, range, pinnedCols);
+  });
+  const globalColIndexMap = computed(() => {
+    const layout = state.layout.value;
+    const cols = layout.visibleCols;
+    const map = /* @__PURE__ */ new Map();
+    for (let i = 0; i < cols.length; i++) {
+      map.set(cols[i].columnId, i);
+    }
+    return map;
   });
   const columnSizingOverridesRef = computed(() => state.layout.value.columnSizingOverrides);
   const columnResize = useColumnResize({
@@ -3227,13 +3513,16 @@ function useDataGridTableSetup(params) {
     columnReorder,
     virtualScroll,
     virtualScrollEnabled,
-    columnResize
+    columnResize,
+    columnPartition,
+    globalColIndexMap
   };
 }
 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),
@@ -3265,8 +3554,28 @@ function createDataGridTable(ui) {
         columnReorder: { isDragging: isReorderDragging, dropIndicatorX, handleHeaderMouseDown: handleReorderMouseDown },
         virtualScroll: { containerRef: vsContainerRef, visibleRange, totalHeight: _totalHeight, scrollToRow: _scrollToRow },
         virtualScrollEnabled,
-        columnResize: { handleResizeStart, handleResizeDoubleClick, getColumnWidth }
+        columnResize: { handleResizeStart, handleResizeDoubleClick, getColumnWidth },
+        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;
       };
@@ -3342,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 {
@@ -3432,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;
@@ -3457,11 +3767,25 @@ function createDataGridTable(ui) {
           ]);
         };
         const { cellStyles: colCellStyles, cellClasses: colCellClasses, hdrStyles: colHdrStyles, hdrClasses: colHdrClasses } = columnMetaCache.value;
-        const columnLayouts = visibleCols.map((col) => ({
+        const allColumnLayouts = visibleCols.map((col) => ({
           col,
           tdClasses: colCellClasses[col.columnId] || "ogrid-data-cell",
           tdDynamicStyle: colCellStyles[col.columnId] || {}
         }));
+        const partition = columnPartition.value;
+        let columnLayouts = allColumnLayouts;
+        let leftSpacerWidth = 0;
+        let rightSpacerWidth = 0;
+        if (partition) {
+          const visibleIds = /* @__PURE__ */ new Set();
+          for (const col of partition.pinnedLeft) visibleIds.add(col.columnId);
+          for (const col of partition.virtualizedUnpinned) visibleIds.add(col.columnId);
+          for (const col of partition.pinnedRight) visibleIds.add(col.columnId);
+          columnLayouts = allColumnLayouts.filter((cl) => visibleIds.has(cl.col.columnId));
+          leftSpacerWidth = partition.leftSpacerWidth;
+          rightSpacerWidth = partition.rightSpacerWidth;
+        }
+        const colIndexMap = globalColIndexMap.value;
         const getHeaderClassAndStyle = (col) => {
           const base = colHdrStyles[col.columnId] || {};
           return {
@@ -3522,13 +3846,27 @@ function createDataGridTable(ui) {
                     },
                     class: "ogrid-table",
                     role: "grid",
-                    style: { minWidth: `${minTableWidth}px` }
+                    style: { minWidth: `${minTableWidth}px` },
+                    ...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 ? [
@@ -3638,7 +3976,7 @@ function createDataGridTable(ui) {
                           })
                         ])
                       )
-                    ),
+                    ]),
                     // Body
                     ...!showEmptyInGrid ? [
                       h("tbody", {}, (() => {
@@ -3703,17 +4041,25 @@ 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 ? [
+                              h("td", { key: "__col-spacer-left", style: { width: `${leftSpacerWidth}px`, minWidth: `${leftSpacerWidth}px`, maxWidth: `${leftSpacerWidth}px`, padding: "0" } })
                             ] : [],
                             // Data cells
                             ...columnLayouts.map(
-                              (cl, colIdx) => h("td", {
+                              (cl) => h("td", {
                                 key: cl.col.columnId,
                                 "data-column-id": cl.col.columnId,
                                 class: cl.tdClasses,
                                 style: cl.tdDynamicStyle
-                              }, [renderCellContent(item, cl.col, rowIndex, colIdx)])
-                            )
+                              }, [renderCellContent(item, cl.col, rowIndex, colIndexMap.get(cl.col.columnId) ?? 0)])
+                            ),
+                            // Right spacer for column virtualization
+                            ...rightSpacerWidth > 0 ? [
+                              h("td", { key: "__col-spacer-right", style: { width: `${rightSpacerWidth}px`, minWidth: `${rightSpacerWidth}px`, maxWidth: `${rightSpacerWidth}px`, padding: "0" } })
+                            ] : []
                           ]));
                         }
                         if (vsEnabled && vr.offsetBottom > 0) {
@@ -3851,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`;
@@ -3956,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,
@@ -189,8 +207,16 @@
   position: relative;
   padding: 0;
   height: 1px;
+  contain: content;
 }
 
+/* Pinned columns need contain: none because contain breaks position: sticky */
+.ogrid-data-cell--pinned-left,
+.ogrid-data-cell--pinned-right { contain: none; }
+
+/* content-visibility: auto on rows for non-virtualized grids */
+.ogrid-table:not([data-virtual-scroll]) tbody tr { content-visibility: auto; }
+
 .ogrid-data-cell--pinned-left {
   position: sticky;
   z-index: var(--ogrid-z-pinned, 6);
@@ -246,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/useDataGridTableSetup.d.ts

@@ -1,5 +1,5 @@
 import { type Ref } from 'vue';
-import type { IOGridDataGridProps } from '../types';
+import type { IOGridDataGridProps, IColumnDef } from '../types';
 import { type UseDataGridStateResult } from './useDataGridState';
 import { type UseColumnResizeResult } from './useColumnResize';
 import { type UseColumnReorderResult } from './useColumnReorder';
@@ -27,6 +27,16 @@ export interface UseDataGridTableSetupResult<T> {
     virtualScrollEnabled: Ref<boolean>;
     /** Column resize handlers (handleResizeStart, getColumnWidth). */
     columnResize: UseColumnResizeResult<T>;
+    /** Column virtualization partition (or null when column virtualization is off). */
+    columnPartition: Ref<{
+        pinnedLeft: IColumnDef<T>[];
+        virtualizedUnpinned: IColumnDef<T>[];
+        pinnedRight: IColumnDef<T>[];
+        leftSpacerWidth: number;
+        rightSpacerWidth: number;
+    } | null>;
+    /** Map from columnId to its global index in visibleCols. */
+    globalColIndexMap: Ref<Map<string, number>>;
 }
 /**
  * Shared setup composable for Vue DataGridTable components.

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

@@ -1,5 +1,5 @@
 import { type Ref } from 'vue';
-import type { IVisibleRange } from '@alaarab/ogrid-core';
+import type { IVisibleRange, IVisibleColumnRange } from '@alaarab/ogrid-core';
 export interface UseVirtualScrollParams {
     totalRows: Ref<number>;
     rowHeight: number;
@@ -10,12 +10,22 @@ export interface UseVirtualScrollParams {
      * When totalRows < threshold, all rows render without virtualization.
      */
     threshold?: number;
+    /** Enable column virtualization. */
+    columnsEnabled?: Ref<boolean>;
+    /** Column widths array for unpinned columns. */
+    columnWidths?: Ref<number[]>;
+    /** Number of extra columns to render outside the visible area. Default: 2. */
+    columnOverscan?: number;
 }
 export interface UseVirtualScrollResult {
     containerRef: Ref<HTMLElement | null>;
     visibleRange: Ref<IVisibleRange>;
     totalHeight: Ref<number>;
     scrollToRow: (index: number, align?: 'start' | 'center' | 'end') => void;
+    /** Visible column range for horizontal virtualization, or null when column virtualization is off. */
+    columnRange: Ref<IVisibleColumnRange | null>;
+    /** Reactive scrollLeft value. */
+    scrollLeft: Ref<number>;
 }
 /**
  * Manages virtual scrolling with RAF-throttled scroll handling and ResizeObserver

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;
@@ -81,10 +83,28 @@ interface IOGridBaseProps<T> {
     columnReorder?: boolean;
     /** Virtual scrolling configuration. Set `enabled: true` with a fixed `rowHeight` to virtualize large datasets. */
     virtualScroll?: IVirtualScrollConfig;
+    /** Offload sort/filter to a Web Worker for large datasets. Falls back to sync when sort column has a custom compare. */
+    workerSort?: boolean;
     /** Fixed row height in pixels. Overrides default row height (36px). */
     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;
 }
@@ -142,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;
@@ -173,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.1.15",
+  "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.1.15"
+    "@alaarab/ogrid-core": "2.3.0"
   },
   "peerDependencies": {
     "vue": "^3.3.0"