@alaarab/ogrid-vue 2.3.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, 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';
+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({});
@@ -245,17 +450,7 @@ function useFormulaEngine(params) {
   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
-    };
+    return createGridDataAccessor(itemsRef.value, flatColumnsRef.value);
   }
   watch(
     enabled,
@@ -330,6 +525,53 @@ function useFormulaEngine(params) {
     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;
@@ -615,12 +857,17 @@ function useOGrid(props) {
     () => 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: props.value.onFormulaRecalc,
+    onFormulaRecalc: wrappedOnFormulaRecalc,
     formulaFunctions: props.value.formulaFunctions,
     namedRanges: props.value.namedRanges,
     sheets: props.value.sheets
@@ -713,9 +960,36 @@ 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;
@@ -743,10 +1017,11 @@ function useOGrid(props) {
       rowSelection: p.rowSelection ?? "none",
       selectedRows: effectiveSelectedRows.value,
       onSelectionChange: handleSelectionChange,
-      showRowNumbers: p.showRowNumbers || p.cellReferences,
-      showColumnLetters: !!p.cellReferences,
-      showNameBox: !!p.cellReferences,
-      onActiveCellChange: p.cellReferences ? onActiveCellChange : void 0,
+      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,
@@ -773,6 +1048,7 @@ function useOGrid(props) {
         render: p.emptyState?.render
       },
       formulas: p.formulas,
+      formulaVersion: formulaVersionRef.value,
       ...formulaEngine.enabled.value ? {
         getFormulaValue: formulaEngine.getFormulaValue,
         hasFormula: formulaEngine.hasFormula,
@@ -782,7 +1058,8 @@ function useOGrid(props) {
         getPrecedents: formulaEngine.getPrecedents,
         getDependents: formulaEngine.getDependents,
         getAuditTrail: formulaEngine.getAuditTrail
-      } : {}
+      } : {},
+      formulaReferences: formulaBarState.referencedCells.value.length > 0 ? formulaBarState.referencedCells.value : void 0
     };
   });
   const pagination = computed(() => ({
@@ -801,8 +1078,10 @@ function useOGrid(props) {
     placement: columnChooserPlacement.value
   }));
   const layout = computed(() => {
-    const showNameBox = !!props.value.cellReferences;
-    let resolvedToolbar = props.value.toolbar;
+    const p = props.value;
+    const formulas = !!p.formulas;
+    const showNameBox = !!p.cellReferences && !formulas;
+    let resolvedToolbar = p.toolbar;
     if (showNameBox) {
       const nameBoxEl = h("div", {
         style: {
@@ -823,13 +1102,32 @@ function useOGrid(props) {
       }, 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: props.value.toolbarBelow,
-      className: props.value.className,
-      emptyState: props.value.emptyState,
+      toolbarBelow: p.toolbarBelow,
+      className: p.className,
+      emptyState: p.emptyState,
       sideBarProps: sideBarProps.value,
-      fullScreen: props.value.fullScreen
+      fullScreen: p.fullScreen,
+      formulaBar: formulaBarEl,
+      sheetTabs: sheetTabsEl
     };
   });
   const filtersResult = computed(() => ({
@@ -2449,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) => {
@@ -3138,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;
   };
@@ -3569,7 +3875,7 @@ function createDataGridTable(ui) {
           const cb = propsRef.value.onActiveCellChange;
           if (!cb) return;
           if (ac) {
-            cb(formatCellReference(ac.columnIndex, offset + ac.rowIndex + 1));
+            cb(formatCellReference(ac.columnIndex - state.layout.value.colOffset, offset + ac.rowIndex + 1));
           } else {
             cb(null);
           }
@@ -4112,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,
@@ -4713,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: {
@@ -4731,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/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

@@ -32,6 +32,8 @@ 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/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, IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail, } 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, IFormulaFunction, IRecalcResult, IGridDataAccessor, IAuditEntry, IAuditTrail } 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>)[];
@@ -105,6 +105,14 @@ interface IOGridBaseProps<T> {
     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;
 }
@@ -215,4 +223,8 @@ export interface IOGridDataGridProps<T> {
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-vue",
-  "version": "2.3.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.3.0"
+    "@alaarab/ogrid-core": "2.4.0"
   },
   "peerDependencies": {
     "vue": "^3.3.0"