@alaarab/ogrid-js 2.1.10 → 2.1.12

package/dist/esm/index.js

@@ -561,20 +561,31 @@ function processClientSideData(data, columns, filters, sortBy, sortDirection) {
         if (Number.isNaN(bt)) return 1 * dir;
         return at === bt ? 0 : at > bt ? dir : -dir;
       });
-    } else {
+    } else if (!compare) {
+      const keyCache = /* @__PURE__ */ new Map();
+      for (let i = 0; i < sortable.length; i++) {
+        const row = sortable[i];
+        const v = sortCol ? getCellValue(row, sortCol) : row[sortBy];
+        if (v == null) {
+          keyCache.set(row, void 0);
+        } else if (typeof v === "number") {
+          keyCache.set(row, v);
+        } else {
+          keyCache.set(row, String(v).toLowerCase());
+        }
+      }
       sortable.sort((a, b) => {
-        if (compare) return compare(a, b) * dir;
-        const av = sortCol ? getCellValue(a, sortCol) : a[sortBy];
-        const bv = sortCol ? getCellValue(b, sortCol) : b[sortBy];
-        if (av == null && bv == null) return 0;
-        if (av == null) return -1 * dir;
-        if (bv == null) return 1 * dir;
+        const av = keyCache.get(a);
+        const bv = keyCache.get(b);
+        if (av === void 0 && bv === void 0) return 0;
+        if (av === void 0) return -1 * dir;
+        if (bv === void 0) return 1 * dir;
         if (typeof av === "number" && typeof bv === "number")
           return av === bv ? 0 : av > bv ? dir : -dir;
-        const as = String(av).toLowerCase();
-        const bs = String(bv).toLowerCase();
-        return as === bs ? 0 : as > bs ? dir : -dir;
+        return av === bv ? 0 : av > bv ? dir : -dir;
       });
+    } else {
+      sortable.sort((a, b) => compare(a, b) * dir);
     }
     return sortable;
   }
@@ -757,7 +768,77 @@ function getHeaderFilterConfig(col, input) {
   }
   return base;
 }
-function getCellRenderDescriptor(item, col, rowIndex, colIdx, input) {
+var _CellDescriptorCache = class _CellDescriptorCache2 {
+  constructor() {
+    this.cache = /* @__PURE__ */ new Map();
+    this.lastVersion = "";
+  }
+  /**
+   * Compute a version string from the volatile parts of CellRenderDescriptorInput.
+   * This string changes whenever any input that affects per-cell output changes.
+   * Cheap to compute (simple string concat) — O(1) regardless of grid size.
+   */
+  static computeVersion(input) {
+    const ec = input.editingCell;
+    const ac = input.activeCell;
+    const sr = input.selectionRange;
+    const cr = input.cutRange;
+    const cp = input.copyRange;
+    return (ec ? `${String(ec.rowId)}\0${ec.columnId}` : "") + "
" + (ac ? `${ac.rowIndex}\0${ac.columnIndex}` : "") + "
" + (sr ? `${sr.startRow}\0${sr.startCol}\0${sr.endRow}\0${sr.endCol}` : "") + "
" + (cr ? `${cr.startRow}\0${cr.startCol}\0${cr.endRow}\0${cr.endCol}` : "") + "
" + (cp ? `${cp.startRow}\0${cp.startCol}\0${cp.endRow}\0${cp.endCol}` : "") + "
" + (input.isDragging ? "1" : "0") + "
" + (input.editable !== false ? "1" : "0") + "
" + (input.onCellValueChanged ? "1" : "0");
+  }
+  /**
+   * Get a cached descriptor or compute a new one.
+   *
+   * @param rowIndex - Row index in the dataset.
+   * @param colIdx - Column index within the visible columns.
+   * @param version - Volatile version string (from CellDescriptorCache.computeVersion).
+   * @param compute - Factory function called on cache miss.
+   * @returns The descriptor (cached or freshly computed).
+   */
+  get(rowIndex, colIdx, version, compute) {
+    const key = rowIndex * _CellDescriptorCache2.MAX_COL_STRIDE + colIdx;
+    const entry = this.cache.get(key);
+    if (entry !== void 0 && entry.version === version) {
+      return entry.descriptor;
+    }
+    const descriptor = compute();
+    this.cache.set(key, { version, descriptor });
+    return descriptor;
+  }
+  /**
+   * Update the last-seen version and return it.
+   * Call once per render pass to track whether any volatile state changed.
+   * If the version is unchanged from last render, the entire render is a no-op for all cells.
+   */
+  updateVersion(version) {
+    this.lastVersion = version;
+  }
+  /** The last version string set via updateVersion(). */
+  get currentVersion() {
+    return this.lastVersion;
+  }
+  /**
+   * Clear all cached entries. Call when the grid's data changes (new items array,
+   * different column count, etc.) to prevent stale cell values from being served.
+   */
+  clear() {
+    this.cache.clear();
+  }
+};
+_CellDescriptorCache.MAX_COL_STRIDE = 1024;
+var CellDescriptorCache = _CellDescriptorCache;
+function getCellRenderDescriptor(item, col, rowIndex, colIdx, input, cache) {
+  if (cache !== void 0) {
+    return cache.get(
+      rowIndex,
+      colIdx,
+      cache.currentVersion,
+      () => computeCellDescriptor(item, col, rowIndex, colIdx, input)
+    );
+  }
+  return computeCellDescriptor(item, col, rowIndex, colIdx, input);
+}
+function computeCellDescriptor(item, col, rowIndex, colIdx, input) {
   const rowId = input.getRowId(item);
   const globalColIndex = colIdx + input.colOffset;
   const colEditable = isColumnEditable(col, item);
@@ -1332,6 +1413,7 @@ function validateColumns(columns) {
     console.warn("[OGrid] columns prop is empty or not an array");
     return;
   }
+  const isDev = typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
   const ids = /* @__PURE__ */ new Set();
   for (const col of columns) {
     if (!col.columnId) {
@@ -1341,10 +1423,25 @@ function validateColumns(columns) {
       console.warn(`[OGrid] Duplicate columnId: "${col.columnId}"`);
     }
     ids.add(col.columnId);
+    if (isDev && col.editable === true && col.cellEditor == null) {
+      console.warn(
+        `[OGrid] Column "${col.columnId}" has editable=true but no cellEditor defined. Cells will not open an editor on double-click. Set cellEditor to 'text', 'select', 'checkbox', 'date', or a custom component.`
+      );
+    }
+  }
+}
+function validateVirtualScrollConfig(config) {
+  if (typeof process !== "undefined" && process.env?.NODE_ENV === "production") return;
+  if (config.enabled !== true) return;
+  if (!config.rowHeight || config.rowHeight <= 0) {
+    console.warn(
+      "[OGrid] virtualScroll.enabled is true but rowHeight is missing or <= 0. Set a positive rowHeight (e.g. virtualScroll: { enabled: true, rowHeight: 36 }) for correct virtual scrolling behavior."
+    );
   }
 }
 function validateRowIds(items, getRowId) {
   if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+  if (!getRowId) return;
   const ids = /* @__PURE__ */ new Set();
   const limit = Math.min(items.length, 100);
   for (let i = 0; i < limit; i++) {
@@ -1366,16 +1463,44 @@ var DEFAULT_DEBOUNCE_MS = 300;
 var PEOPLE_SEARCH_DEBOUNCE_MS = DEFAULT_DEBOUNCE_MS;
 var SIDEBAR_TRANSITION_MS = 300;
 var Z_INDEX = {
+  /** Column resize drag handle */
+  RESIZE_HANDLE: 1,
+  /** Active/editing cell outline */
+  ACTIVE_CELL: 2,
+  /** Fill handle dot */
+  FILL_HANDLE: 3,
   /** Selection range overlay (marching ants) */
   SELECTION_OVERLAY: 4,
+  /** Row number column */
+  ROW_NUMBER: 5,
   /** Clipboard overlay (copy/cut animation) */
   CLIPBOARD_OVERLAY: 5,
+  /** Sticky pinned body cells */
+  PINNED: 6,
+  /** Selection checkbox column in body */
+  SELECTION_CELL: 7,
+  /** Sticky thead row */
+  THEAD: 8,
+  /** Pinned header cells (sticky both axes) */
+  PINNED_HEADER: 10,
+  /** Focused header cell */
+  HEADER_FOCUS: 11,
+  /** Checkbox column in sticky header (sticky both axes) */
+  SELECTION_HEADER_PINNED: 12,
+  /** Loading overlay within table */
+  LOADING: 2,
+  /** Column reorder drop indicator */
+  DROP_INDICATOR: 100,
   /** Dropdown menus (column chooser, pagination size select) */
   DROPDOWN: 1e3,
+  /** Filter popovers */
+  FILTER_POPOVER: 1e3,
   /** Modal dialogs */
   MODAL: 2e3,
+  /** Fullscreen grid container */
+  FULLSCREEN: 9999,
   /** Context menus (right-click grid menu) */
-  CONTEXT_MENU: 9999
+  CONTEXT_MENU: 1e4
 };
 
 // src/utils/getCellCoordinates.ts
@@ -1908,18 +2033,18 @@ var TableRenderer = class {
     this.container.innerHTML = "";
     const wrapper = document.createElement("div");
     wrapper.className = "ogrid-wrapper";
-    wrapper.setAttribute("role", "grid");
+    wrapper.setAttribute("role", "region");
     wrapper.setAttribute("tabindex", "0");
     wrapper.style.position = "relative";
     if (this.state.rowHeight) {
       wrapper.style.setProperty("--ogrid-row-height", `${this.state.rowHeight}px`);
     }
-    if (this.state.ariaLabel) {
-      wrapper.setAttribute("aria-label", this.state.ariaLabel);
-    }
+    const label = this.state.ariaLabel ?? "Data grid";
+    wrapper.setAttribute("aria-label", label);
     this.wrapperEl = wrapper;
     this.table = document.createElement("table");
     this.table.className = "ogrid-table";
+    this.table.setAttribute("role", "grid");
     this.thead = document.createElement("thead");
     if (this.state.stickyHeader) {
       this.thead.classList.add("ogrid-sticky-header");
@@ -2174,6 +2299,11 @@ var TableRenderer = class {
           }
           if (!cell.isGroup && cell.columnDef) {
             th.setAttribute("data-column-id", cell.columnDef.columnId);
+            th.setAttribute("scope", "col");
+            const groupSort = this.state.sort;
+            if (groupSort?.field === cell.columnDef.columnId) {
+              th.setAttribute("aria-sort", groupSort.direction === "asc" ? "ascending" : "descending");
+            }
             this.applyPinningStyles(th, cell.columnDef.columnId, true);
           }
           tr.appendChild(th);
@@ -2202,6 +2332,11 @@ var TableRenderer = class {
         const th = document.createElement("th");
         th.className = "ogrid-header-cell";
         th.setAttribute("data-column-id", col.columnId);
+        th.setAttribute("scope", "col");
+        const sort = this.state.sort;
+        if (sort?.field === col.columnId) {
+          th.setAttribute("aria-sort", sort.direction === "asc" ? "ascending" : "descending");
+        }
         const textSpan = document.createElement("span");
         textSpan.textContent = col.name;
         th.appendChild(textSpan);
@@ -2232,6 +2367,8 @@ var TableRenderer = class {
           const filterBtn = document.createElement("button");
           filterBtn.className = "ogrid-filter-icon";
           filterBtn.setAttribute("aria-label", `Filter ${col.name}`);
+          filterBtn.setAttribute("aria-expanded", "false");
+          filterBtn.setAttribute("aria-haspopup", "dialog");
           filterBtn.style.border = "none";
           filterBtn.style.background = "transparent";
           filterBtn.style.cursor = "pointer";
@@ -2322,6 +2459,7 @@ var TableRenderer = class {
       const isRowSelected = this.interactionState?.selectedRowIds?.has(rowId) === true;
       if (isRowSelected) {
         tr.setAttribute("data-row-selected", "true");
+        tr.setAttribute("aria-selected", "true");
       }
       if (hasCheckbox) {
         const td = document.createElement("td");
@@ -3755,6 +3893,7 @@ var ColumnPinningState = class {
 // src/state/VirtualScrollState.ts
 var DEFAULT_ROW_HEIGHT = 36;
 var DEFAULT_OVERSCAN = 5;
+var DEFAULT_PASSTHROUGH_THRESHOLD = 100;
 var VirtualScrollState = class {
   constructor(config) {
     this.emitter = new EventEmitter();
@@ -3765,10 +3904,12 @@ var VirtualScrollState = class {
     this._ro = null;
     this._cachedRange = { startIndex: 0, endIndex: -1, offsetTop: 0, offsetBottom: 0 };
     this._config = config ?? { enabled: false };
+    validateVirtualScrollConfig(this._config);
   }
-  /** Whether virtual scrolling is active. */
+  /** Whether virtual scrolling is active (enabled + meets the row threshold). */
   get enabled() {
-    return this._config.enabled === true && this._totalRows > 0;
+    const threshold = this._config.threshold ?? DEFAULT_PASSTHROUGH_THRESHOLD;
+    return this._config.enabled === true && this._totalRows >= threshold;
   }
   get config() {
     return this._config;
@@ -3809,6 +3950,7 @@ var VirtualScrollState = class {
   }
   /** Update the virtual scroll configuration. */
   updateConfig(config) {
+    validateVirtualScrollConfig(config);
     this._config = config;
     this.recompute();
     this.emitter.emit("configChanged", { config });
@@ -3982,7 +4124,11 @@ var KeyboardNavState = class {
   constructor(params, getActiveCell, getSelectionRange, setActiveCell, setSelectionRange) {
     this.wrapperRef = null;
     this.handleKeyDown = (e) => {
-      const { items, visibleCols, colOffset, editable, onCellValueChanged, onCopy, onCut, onPaste, onUndo, onRedo, onContextMenu, onStartEdit, getRowId, clearClipboardRanges } = this.params;
+      const { items, visibleCols, colOffset, editable, onCellValueChanged, onCopy, onCut, onPaste, onUndo, onRedo, onContextMenu, onStartEdit, getRowId, clearClipboardRanges, onKeyDown, onFillDown } = this.params;
+      if (onKeyDown) {
+        onKeyDown(e);
+        if (e.defaultPrevented) return;
+      }
       const activeCell = this.getActiveCell();
       const selectionRange = this.getSelectionRange();
       const maxRowIndex = items.length - 1;
@@ -4022,6 +4168,14 @@ var KeyboardNavState = class {
             void onPaste?.();
           }
           break;
+        case "d":
+          if (e.ctrlKey || e.metaKey) {
+            if (editable !== false && onFillDown) {
+              e.preventDefault();
+              onFillDown();
+            }
+          }
+          break;
         case "ArrowDown":
         case "ArrowUp":
         case "ArrowRight":
@@ -4433,6 +4587,13 @@ var FillHandleState = class {
   updateParams(params) {
     this.params = params;
   }
+  /** Fill the current selection down from the top row (keyboard Ctrl+D). No-op if no selection or editable=false. */
+  fillDown() {
+    const range = this.getSelectionRange();
+    if (!range || this.params.editable === false || !this.params.onCellValueChanged) return;
+    const norm = normalizeSelectionRange(range);
+    this.applyFillValuesFromCore(norm, { startRow: norm.startRow, startCol: norm.startCol });
+  }
   /** Called when the fill handle square is mousedown'd. */
   startFillDrag(e) {
     e.preventDefault();
@@ -5706,7 +5867,9 @@ var OGridRendering = class {
         onRedo: () => undoRedoState?.redo(),
         onContextMenu: (x, y) => this.ctx.showContextMenu(x, y),
         onStartEdit: (rowId, columnId) => this.ctx.startCellEdit(rowId, columnId),
-        clearClipboardRanges: () => clipboardState?.clearClipboardRanges()
+        clearClipboardRanges: () => clipboardState?.clearClipboardRanges(),
+        onKeyDown: options.onKeyDown,
+        onFillDown: fillHandleState ? () => fillHandleState.fillDown() : void 0
       });
       clipboardState.updateParams({
         items,
@@ -5738,6 +5901,11 @@ var OGridRendering = class {
   renderHeaderFilterPopover() {
     const { headerFilterState, headerFilterComponent, filterConfigs } = this.ctx;
     const openId = headerFilterState.openColumnId;
+    const allBtns = this.ctx.tableContainer.querySelectorAll(".ogrid-filter-icon[aria-haspopup]");
+    for (const btn of allBtns) {
+      const colId = btn.closest("th[data-column-id]")?.getAttribute("data-column-id");
+      btn.setAttribute("aria-expanded", colId === openId ? "true" : "false");
+    }
     if (!openId) {
       headerFilterComponent.cleanup();
       return;
@@ -6372,4 +6540,4 @@ var OGrid = class {
   }
 };
 
-export { AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX, CELL_PADDING, CHECKBOX_COLUMN_WIDTH, COLUMN_HEADER_MENU_ITEMS, ClipboardState, ColumnChooser, ColumnPinningState, ColumnReorderState, ColumnResizeState, ContextMenu, DEFAULT_DEBOUNCE_MS, DEFAULT_MIN_COLUMN_WIDTH, EventEmitter, FillHandleState, GRID_BORDER_RADIUS, GRID_CONTEXT_MENU_ITEMS, GridState, HeaderFilter, HeaderFilterState, InlineCellEditor, KeyboardNavState, MAX_PAGE_BUTTONS, MarchingAntsOverlay, OGrid, OGridEventWiring, OGridRendering, PAGE_SIZE_OPTIONS, PEOPLE_SEARCH_DEBOUNCE_MS, PaginationControls, ROW_NUMBER_COLUMN_WIDTH, RowSelectionState, SIDEBAR_TRANSITION_MS, SelectionState, SideBar, SideBarState, StatusBar, TableLayoutState, TableRenderer, UndoRedoStack, UndoRedoState, VirtualScrollState, Z_INDEX, applyCellDeletion, applyCutClear, applyFillValues, applyPastedValues, applyRangeRowSelection, areGridRowPropsEqual, booleanParser, buildCellIndex, buildCsvHeader, buildCsvRows, buildHeaderRows, buildInlineEditorProps, buildPopoverEditorProps, calculateDropTarget, clampSelectionToBounds, computeAggregations, computeArrowNavigation, computeAutoScrollSpeed, computeNextSortState, computeRowSelectionState, computeTabNavigation, computeTotalHeight, computeVisibleRange, currencyParser, dateParser, debounce, deriveFilterOptionsFromData, emailParser, escapeCsvValue, exportToCsv, findCtrlArrowTarget, flattenColumns, formatCellValueForTsv, formatSelectionAsTsv, formatShortcut, getCellRenderDescriptor, getCellValue, getColumnHeaderMenuItems, getContextMenuHandlers, getDataGridStatusBarConfig, getFilterField, getHeaderFilterConfig, getMultiSelectFilterFields, getPaginationViewModel, getPinStateForColumn, getScrollTopForRow, getStatusBarParts, injectGlobalStyles, isColumnEditable, isFilterConfig, isInSelectionRange, isRowInRange, measureColumnContentWidth, measureRange, mergeFilter, normalizeSelectionRange, numberParser, parseTsvClipboard, parseValue, processClientSideData, rangesEqual, reorderColumnArray, resolveCellDisplayContent, resolveCellStyle, toUserLike, triggerCsvDownload, validateColumns, validateRowIds };
+export { AUTOSIZE_EXTRA_PX, AUTOSIZE_MAX_PX, CELL_PADDING, CHECKBOX_COLUMN_WIDTH, COLUMN_HEADER_MENU_ITEMS, CellDescriptorCache, ClipboardState, ColumnChooser, ColumnPinningState, ColumnReorderState, ColumnResizeState, ContextMenu, DEFAULT_DEBOUNCE_MS, DEFAULT_MIN_COLUMN_WIDTH, EventEmitter, FillHandleState, GRID_BORDER_RADIUS, GRID_CONTEXT_MENU_ITEMS, GridState, HeaderFilter, HeaderFilterState, InlineCellEditor, KeyboardNavState, MAX_PAGE_BUTTONS, MarchingAntsOverlay, OGrid, OGridEventWiring, OGridRendering, PAGE_SIZE_OPTIONS, PEOPLE_SEARCH_DEBOUNCE_MS, PaginationControls, ROW_NUMBER_COLUMN_WIDTH, RowSelectionState, SIDEBAR_TRANSITION_MS, SelectionState, SideBar, SideBarState, StatusBar, TableLayoutState, TableRenderer, UndoRedoStack, UndoRedoState, VirtualScrollState, Z_INDEX, applyCellDeletion, applyCutClear, applyFillValues, applyPastedValues, applyRangeRowSelection, areGridRowPropsEqual, booleanParser, buildCellIndex, buildCsvHeader, buildCsvRows, buildHeaderRows, buildInlineEditorProps, buildPopoverEditorProps, calculateDropTarget, clampSelectionToBounds, computeAggregations, computeArrowNavigation, computeAutoScrollSpeed, computeNextSortState, computeRowSelectionState, computeTabNavigation, computeTotalHeight, computeVisibleRange, currencyParser, dateParser, debounce, deriveFilterOptionsFromData, emailParser, escapeCsvValue, exportToCsv, findCtrlArrowTarget, flattenColumns, formatCellValueForTsv, formatSelectionAsTsv, formatShortcut, getCellRenderDescriptor, getCellValue, getColumnHeaderMenuItems, getContextMenuHandlers, getDataGridStatusBarConfig, getFilterField, getHeaderFilterConfig, getMultiSelectFilterFields, getPaginationViewModel, getPinStateForColumn, getScrollTopForRow, getStatusBarParts, injectGlobalStyles, isColumnEditable, isFilterConfig, isInSelectionRange, isRowInRange, measureColumnContentWidth, measureRange, mergeFilter, normalizeSelectionRange, numberParser, parseTsvClipboard, parseValue, processClientSideData, rangesEqual, reorderColumnArray, resolveCellDisplayContent, resolveCellStyle, toUserLike, triggerCsvDownload, validateColumns, validateRowIds, validateVirtualScrollConfig };

package/dist/styles/ogrid.css

@@ -6,6 +6,13 @@
 
 /* ── Light Theme (default) — :where() for zero specificity ── */
 :where(:root) {
+  /* Cell padding — override for row density:
+     --ogrid-cell-padding          : shorthand (default 6px 10px)
+     --ogrid-cell-padding-vertical : vertical only (default 6px)
+     --ogrid-cell-padding-horizontal: horizontal only (default 10px) */
+  --ogrid-cell-padding: 6px 10px;
+  --ogrid-cell-padding-vertical: 6px;
+  --ogrid-cell-padding-horizontal: 10px;
   --ogrid-bg: #ffffff;
   --ogrid-fg: rgba(0, 0, 0, 0.87);
   --ogrid-fg-secondary: rgba(0, 0, 0, 0.6);
@@ -132,7 +139,7 @@
 .ogrid-container.ogrid-fullscreen {
   position: fixed;
   inset: 0;
-  z-index: 9999;
+  z-index: var(--ogrid-z-fullscreen, 9999);
   border-radius: 0;
   border: none;
 }
@@ -224,7 +231,7 @@
 
 .ogrid-table thead {
   background: var(--ogrid-bg-subtle, #f3f2f1);
-  z-index: 8;
+  z-index: var(--ogrid-z-thead, 8);
 }
 
 .ogrid-table thead.ogrid-sticky-header {
@@ -270,7 +277,7 @@
   width: 8px;
   cursor: col-resize;
   user-select: none;
-  z-index: 1;
+  z-index: var(--ogrid-z-resize-handle, 1);
 }
 
 .ogrid-resize-handle::after {
@@ -316,7 +323,7 @@
 /* ── Body Rows ── */
 
 .ogrid-table tbody td {
-  padding: 6px 10px;
+  padding: var(--ogrid-cell-padding, 6px 10px);
   background: var(--ogrid-bg, #ffffff);
   border-bottom: 1px solid var(--ogrid-border, #e8e8e8);
   position: relative;
@@ -345,12 +352,15 @@
   background: var(--ogrid-bg-selected-hover, #dae8f8);
 }
 
-.ogrid-checkbox-header,
-.ogrid-checkbox-cell {
+/* Element-type selector (th.ogrid-checkbox-header, td.ogrid-checkbox-cell) has specificity
+   0,1,1 which beats the generic .ogrid-table tbody td (0,1,2) — wait, 0,1,1 < 0,1,2.
+   Qualify with .ogrid-table to reach 0,2,1, beating the base td padding rule (0,1,2). */
+.ogrid-table th.ogrid-checkbox-header,
+.ogrid-table td.ogrid-checkbox-cell {
   width: 48px;
   min-width: 48px;
   max-width: 48px;
-  padding: 4px !important;
+  padding: 4px;
   text-align: center;
 }
 
@@ -367,20 +377,22 @@
 .ogrid-cell[data-active-cell='true'] {
   outline: 2px solid var(--ogrid-selection, #217346);
   outline-offset: -1px;
-  z-index: 2;
+  z-index: var(--ogrid-z-active-cell, 2);
   position: relative;
 }
 
-.ogrid-cell[data-in-range='true'] {
-  background: var(--ogrid-bg-range, rgba(33, 115, 70, 0.12)) !important;
+/* Cell range/drag highlights: qualify with .ogrid-container to reach specificity 0,3,0,
+   beating row-hover rules (.ogrid-table tbody tr:hover td = 0,2,3). */
+.ogrid-container .ogrid-cell[data-in-range='true'] {
+  background: var(--ogrid-bg-range, rgba(33, 115, 70, 0.12));
 }
 
-[data-drag-range] {
-  background: var(--ogrid-bg-range, rgba(33, 115, 70, 0.12)) !important;
+.ogrid-container [data-drag-range] {
+  background: var(--ogrid-bg-range, rgba(33, 115, 70, 0.12));
 }
 
-[data-drag-anchor] {
-  background: var(--ogrid-bg, #fff) !important;
+.ogrid-container [data-drag-anchor] {
+  background: var(--ogrid-bg, #fff);
 }
 
 /* ── Fill Handle ── */
@@ -396,7 +408,7 @@
   border-radius: 1px;
   cursor: crosshair;
   pointer-events: auto;
-  z-index: 3;
+  z-index: var(--ogrid-z-fill-handle, 3);
 }
 
 /* ── Pinned Columns ── */
@@ -404,7 +416,7 @@
 .ogrid-table th[data-pinned='left'],
 .ogrid-table td[data-pinned='left'] {
   position: sticky;
-  z-index: 6;
+  z-index: var(--ogrid-z-pinned, 6);
   background: var(--ogrid-bg, #fff);
   will-change: transform;
   border-right: 1px solid var(--ogrid-border, rgba(0, 0, 0, 0.12));
@@ -413,13 +425,13 @@
 
 .ogrid-table thead th[data-pinned='left'] {
   background: var(--ogrid-bg-subtle, #f3f2f1);
-  z-index: 9;
+  z-index: var(--ogrid-z-pinned-header, 10);
 }
 
 .ogrid-table th[data-pinned='right'],
 .ogrid-table td[data-pinned='right'] {
   position: sticky;
-  z-index: 6;
+  z-index: var(--ogrid-z-pinned, 6);
   background: var(--ogrid-bg, #fff);
   will-change: transform;
   border-left: 1px solid var(--ogrid-border, rgba(0, 0, 0, 0.12));
@@ -428,7 +440,7 @@
 
 .ogrid-table thead th[data-pinned='right'] {
   background: var(--ogrid-bg-subtle, #f3f2f1);
-  z-index: 9;
+  z-index: var(--ogrid-z-pinned-header, 10);
 }
 
 /* ── Empty State ── */
@@ -445,7 +457,7 @@
 .ogrid-loading-overlay {
   position: absolute;
   inset: 0;
-  z-index: 100;
+  z-index: var(--ogrid-z-drop-indicator, 100);
   display: flex;
   align-items: center;
   justify-content: center;
@@ -589,10 +601,20 @@
   cursor: not-allowed;
 }
 
-.ogrid-pagination-active {
-  background: var(--ogrid-primary, #217346) !important;
-  border-color: var(--ogrid-primary, #217346) !important;
-  color: var(--ogrid-primary-fg, #fff) !important;
+/* Active pagination button: compound selector (0,2,0) beats base (0,1,0).
+   The :hover rule (.ogrid-pagination-btn:hover:not(:disabled), 0,3,0) still wins on hover,
+   but that is the correct UX — hovered active page shows hover style. */
+.ogrid-pagination-btn.ogrid-pagination-active {
+  background: var(--ogrid-primary, #217346);
+  border-color: var(--ogrid-primary, #217346);
+  color: var(--ogrid-primary-fg, #fff);
+}
+
+/* Keep active state even when hovered */
+.ogrid-pagination-btn.ogrid-pagination-active:hover:not(:disabled) {
+  background: var(--ogrid-primary, #217346);
+  border-color: var(--ogrid-primary, #217346);
+  color: var(--ogrid-primary-fg, #fff);
 }
 
 .ogrid-pagination-ellipsis {
@@ -797,7 +819,7 @@
 
 .ogrid-header-filter-popover {
   position: fixed;
-  z-index: 1000;
+  z-index: var(--ogrid-z-filter-popover, 1000);
   min-width: 280px;
   max-width: 320px;
   background: var(--ogrid-bg, #fff);
@@ -909,7 +931,7 @@
 
 .ogrid-context-menu {
   position: fixed;
-  z-index: 10000;
+  z-index: var(--ogrid-z-context-menu, 10000);
   min-width: 160px;
   padding: 4px 0;
   background: var(--ogrid-bg, #fff);
@@ -952,7 +974,7 @@
 
 .ogrid-cell-editor {
   position: absolute;
-  z-index: 10;
+  z-index: var(--ogrid-z-filter-popover, 1000);
   background: var(--ogrid-bg, #fff);
   border: 2px solid var(--ogrid-selection, #217346);
   border-radius: 0;
@@ -982,7 +1004,7 @@
   width: 3px;
   background: var(--ogrid-primary, #217346);
   pointer-events: none;
-  z-index: 100;
+  z-index: var(--ogrid-z-drop-indicator, 100);
   transition: left 0.05s;
 }
 
@@ -996,9 +1018,11 @@
 
 /* ── Virtual Scrolling ── */
 
-.ogrid-virtual-spacer td {
-  padding: 0 !important;
-  border: none !important;
+/* Virtual spacer: element+class selector (0,1,1) beats plain td rules (0,0,1).
+   But .ogrid-table tbody td (0,1,2) has higher specificity so we qualify with the table. */
+.ogrid-table .ogrid-virtual-spacer td {
+  padding: 0;
+  border: none;
   line-height: 0;
 }
 

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

@@ -38,6 +38,8 @@ export declare class FillHandleState<T> {
     get fillRange(): ISelectionRange | null;
     setWrapperRef(ref: HTMLElement | null): void;
     updateParams(params: FillHandleParams<T>): void;
+    /** Fill the current selection down from the top row (keyboard Ctrl+D). No-op if no selection or editable=false. */
+    fillDown(): void;
     /** Called when the fill handle square is mousedown'd. */
     startFillDrag(e: MouseEvent): void;
     private onMouseMove;

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

@@ -14,6 +14,10 @@ export interface KeyboardNavParams<T> {
     onContextMenu?: (x: number, y: number) => void;
     onStartEdit?: (rowId: RowId, columnId: string) => void;
     clearClipboardRanges?: () => void;
+    /** Custom keydown handler. Called before grid default. preventDefault() suppresses grid handling. */
+    onKeyDown?: (event: KeyboardEvent) => void;
+    /** Fill-down callback (Ctrl+D). Provided by FillHandleState. */
+    onFillDown?: () => void;
 }
 export declare class KeyboardNavState<T> {
     private params;

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

@@ -21,7 +21,7 @@ export declare class VirtualScrollState {
     private _ro;
     private _cachedRange;
     constructor(config?: IVirtualScrollConfig);
-    /** Whether virtual scrolling is active. */
+    /** Whether virtual scrolling is active (enabled + meets the row threshold). */
     get enabled(): boolean;
     get config(): IVirtualScrollConfig;
     get containerHeight(): number;

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

@@ -122,6 +122,8 @@ export interface OGridOptions<T> {
     columnChooser?: boolean | 'toolbar' | 'sidebar';
     /** Secondary toolbar row rendered below the primary toolbar. */
     toolbarBelow?: HTMLElement | null;
+    /** Custom keydown handler. Called before grid's built-in handling. Call event.preventDefault() to suppress grid default. */
+    onKeyDown?: (event: KeyboardEvent) => void;
 }
 /** Events emitted by the OGrid instance. */
 export interface OGridEvents<T> extends Record<string, unknown> {

package/package.json

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