@alaarab/ogrid-core 1.8.2 → 1.9.0

package/README.md

@@ -1,48 +1,59 @@
-# @alaarab/ogrid-core
+<p align="center">
+  <strong>OGrid Core</strong> — Headless types, hooks, and utilities for OGrid data grids.
+</p>
 
-Framework-agnostic types, hooks, and utilities for [OGrid](https://github.com/alaarab/ogrid) data tables.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@alaarab/ogrid-core"><img src="https://img.shields.io/npm/v/@alaarab/ogrid-core?color=%23217346&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/alaarab/ogrid/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License" /></a>
+  <img src="https://img.shields.io/badge/React-17%20%7C%2018%20%7C%2019-blue" alt="React 17, 18, 19" />
+  <img src="https://img.shields.io/badge/TypeScript-strict-blue" alt="TypeScript strict" />
+</p>
 
-This package is the shared foundation used by `@alaarab/ogrid-fluent` and `@alaarab/ogrid-material`. You typically don't need to install it directly -- both framework packages re-export everything from core.
+<p align="center">
+  <a href="https://alaarab.github.io/ogrid/">Documentation</a> · <a href="https://alaarab.github.io/ogrid/docs/getting-started/overview">Getting Started</a> · <a href="https://alaarab.github.io/ogrid/docs/api/ogrid-props">API Reference</a>
+</p>
 
-## Install
+---
 
-```bash
-npm install @alaarab/ogrid-core
-```
+Framework-agnostic foundation for [OGrid](https://github.com/alaarab/ogrid) data grids. You typically don't need to install this directly — the UI packages ([`@alaarab/ogrid`](https://www.npmjs.com/package/@alaarab/ogrid), [`@alaarab/ogrid-fluent`](https://www.npmjs.com/package/@alaarab/ogrid-fluent), [`@alaarab/ogrid-material`](https://www.npmjs.com/package/@alaarab/ogrid-material)) re-export everything from core.
 
-## What's Included
+## What's Inside
+
+### Hooks
+
+- `useOGrid` — Orchestrator: pagination, sorting, filtering, visibility, editing, row selection, status bar, grid API
+- `useDataGridState` — All DataGridTable state: layout, selection, editing, interaction, context menu, view models
+- `useColumnHeaderFilterState` — Filter popover (open, temp values, apply/clear, people search debounce)
+- `useColumnChooserState` — Column visibility dropdown
+- `useInlineCellEditorState` — Inline cell editor
+- `useRichSelectState` — Searchable rich select dropdown
+- `useSideBarState` — Side bar panel management
+- `useActiveCell`, `useCellSelection`, `useCellEditing`, `useRowSelection`, `useKeyboardNavigation`, `useClipboard`, `useFillHandle`, `useUndoRedo`, `useContextMenu`, `useColumnResize`, `useFilterOptions`, `useDebounce`
 
 ### Types
 
-- `IColumnDef<T>` -- Column definition with sorting, filtering, and rendering
-- `IDataSource<T>` -- Server-side data source interface
-- `IFetchParams` -- Parameters for `fetchPage()`
-- `IFilters` -- Unified filter values (text, multi-select, people)
-- `UserLike` -- Minimal user shape for people picker
-- `IColumnFilterDef`, `IColumnMeta`, `IPageResult`, `ColumnFilterType`
+`IColumnDef<T>` · `IColumnGroupDef` · `IDataSource<T>` · `IFilters` · `FilterValue` · `IDateFilterValue` · `UserLike` · `IOGridApi<T>` · `IOGridProps<T>` · `IOGridDataGridProps<T>` · `ICellEditorProps<T>` · `IGridColumnState` · `ISideBarDef` · `ColumnFilterType` · `IColumnMeta`
 
-### Hooks
+### Utilities
 
-- `useOGrid(props, ref)` -- Page/sort/filter/visibleColumns + `dataGridProps` for DataGridTable (used by OGrid wrappers)
-- `useDataGridState({ props, wrapperRef })` -- Orchestrator for grid state, selection, editing, clipboard, keyboard, fill handle, status bar
-- `useFilterOptions(dataSource, fields)` -- Loads filter options for multi-select columns
-- `useColumnHeaderFilterState(params)` -- Headless filter popover state (open, temp values, apply/clear, people search)
-- `useColumnChooserState({ columns, visibleColumns, onVisibilityChange })` -- Column visibility dropdown (open, Escape, select all/clear)
-- `useInlineCellEditorState({ value, editorType, onCommit, onCancel })` -- Inline cell editor (localValue, keydown, blur/commit)
+`processClientSideData` · `exportToCsv` · `getCellValue` · `flattenColumns` · `buildHeaderRows` · `getPaginationViewModel` · `getHeaderFilterConfig` · `getCellRenderDescriptor` · `computeAggregations` · `formatShortcut` · `GRID_CONTEXT_MENU_ITEMS`
 
-### Components
+### Headless Components
 
-- `OGridLayout` -- Unified bordered layout: toolbar strip (custom content + column chooser), optional secondary toolbar row, sidebar, grid area, and footer strip (pagination).
+`OGridLayout` · `StatusBar` · `GridContextMenu` · `SideBar` · `MarchingAntsOverlay`
 
-### Utilities
+## Install
+
+```bash
+npm install @alaarab/ogrid-core
+```
+
+Only peer dep is `react ^17 || ^18 || ^19`.
+
+## Documentation
 
-- `getPaginationViewModel(...)` -- Page numbers, ellipsis, start/end item for PaginationControls
-- `getHeaderFilterConfig(col, input)` -- ColumnHeaderFilter props from column + filter/sort state
-- `getCellRenderDescriptor(item, col, rowIndex, colIdx, input)` -- Cell mode (editing-inline / editing-popover / display) and flags for DataGridTable
-- `toUserLike(user)` -- Converts a user-like object to `UserLike`
-- `exportToCsv(items, columns, getValue, filename)` -- Full CSV export
-- `buildCsvHeader`, `buildCsvRows`, `triggerCsvDownload`, `escapeCsvValue` -- Low-level CSV helpers
+Full docs at **[alaarab.github.io/ogrid](https://alaarab.github.io/ogrid/)**.
 
 ## License
 
-MIT
+MIT — Free forever.

package/dist/esm/components/BaseInlineCellEditor.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from 'react';
+import { useInlineCellEditorState, useRichSelectState } from '../hooks';
+// ── Shared editor style constants (used across all 3 UI packages) ──
+export const editorWrapperStyle = {
+    width: '100%',
+    height: '100%',
+    display: 'flex',
+    alignItems: 'center',
+    padding: '6px 10px',
+    boxSizing: 'border-box',
+    overflow: 'hidden',
+    minWidth: 0,
+};
+export const editorInputStyle = {
+    width: '100%',
+    padding: 0,
+    border: 'none',
+    background: 'transparent',
+    color: 'inherit',
+    font: 'inherit',
+    fontSize: '13px',
+    outline: 'none',
+    minWidth: 0,
+};
+export const richSelectWrapperStyle = {
+    ...editorWrapperStyle,
+    position: 'relative',
+};
+export const richSelectDropdownStyle = {
+    position: 'absolute',
+    top: '100%',
+    left: 0,
+    right: 0,
+    maxHeight: 200,
+    overflowY: 'auto',
+    background: 'var(--ogrid-bg, #fff)',
+    border: '1px solid var(--ogrid-border, #ccc)',
+    zIndex: 10,
+    boxShadow: '0 4px 16px rgba(0,0,0,0.2)',
+};
+export const richSelectOptionStyle = {
+    padding: '6px 8px',
+    cursor: 'pointer',
+    color: 'var(--ogrid-fg, #242424)',
+};
+export const richSelectOptionHighlightedStyle = {
+    ...richSelectOptionStyle,
+    background: 'var(--ogrid-bg-hover, #e8f0fe)',
+};
+export const richSelectNoMatchesStyle = {
+    padding: '6px 8px',
+    color: 'var(--ogrid-muted, #999)',
+};
+export const selectEditorStyle = {
+    width: '100%',
+    padding: 0,
+    border: 'none',
+    background: 'transparent',
+    color: 'inherit',
+    font: 'inherit',
+    fontSize: '13px',
+    cursor: 'pointer',
+    outline: 'none',
+};
+/**
+ * Base inline cell editor with shared logic for all editor types except checkbox and select
+ * (which are framework-specific). Used by all 3 UI packages to avoid duplication.
+ *
+ * Usage:
+ * - Radix: Pass Radix Checkbox/native select via render props
+ * - Fluent: Pass Fluent Checkbox/Select via render props
+ * - Material: Pass MUI Checkbox/Select via render props
+ */
+export function BaseInlineCellEditor(props) {
+    const { value, column, editorType, onCommit, onCancel, renderCheckbox, renderSelect } = props;
+    const wrapperRef = React.useRef(null);
+    const { localValue, setLocalValue, handleKeyDown, handleBlur, commit, cancel } = useInlineCellEditorState({ value, editorType, onCommit, onCancel });
+    const richSelectValues = column.cellEditorParams?.values ?? [];
+    const richSelectFormatValue = column.cellEditorParams?.formatValue;
+    const richSelect = useRichSelectState({
+        values: richSelectValues,
+        formatValue: richSelectFormatValue,
+        initialValue: value,
+        onCommit,
+        onCancel,
+    });
+    React.useEffect(() => {
+        const input = wrapperRef.current?.querySelector('input');
+        input?.focus();
+    }, []);
+    // Rich select (shared across all frameworks)
+    if (editorType === 'richSelect') {
+        return (_jsxs("div", { ref: wrapperRef, style: richSelectWrapperStyle, children: [_jsx("input", { type: "text", value: richSelect.searchText, onChange: (e) => richSelect.setSearchText(e.target.value), onKeyDown: richSelect.handleKeyDown, placeholder: "Search...", autoFocus: true, style: editorInputStyle }), _jsxs("div", { style: richSelectDropdownStyle, role: "listbox", children: [richSelect.filteredValues.map((v, i) => (_jsx("div", { role: "option", "aria-selected": i === richSelect.highlightedIndex, onClick: () => richSelect.selectValue(v), style: i === richSelect.highlightedIndex ? richSelectOptionHighlightedStyle : richSelectOptionStyle, children: richSelect.getDisplayText(v) }, String(v)))), richSelect.filteredValues.length === 0 && (_jsx("div", { style: richSelectNoMatchesStyle, children: "No matches" }))] })] }));
+    }
+    // Checkbox (framework-specific)
+    if (editorType === 'checkbox') {
+        const checked = value === true;
+        return _jsx(_Fragment, { children: renderCheckbox(checked, (val) => commit(val), cancel) });
+    }
+    // Select (framework-specific)
+    if (editorType === 'select') {
+        const values = column.cellEditorParams?.values ?? [];
+        return _jsx(_Fragment, { children: renderSelect(value, values, commit, cancel) });
+    }
+    // Date editor (shared across all frameworks)
+    if (editorType === 'date') {
+        return (_jsx("div", { ref: wrapperRef, style: editorWrapperStyle, children: _jsx("input", { type: "date", value: localValue, onChange: (e) => setLocalValue(e.target.value), onBlur: handleBlur, onKeyDown: handleKeyDown, style: editorInputStyle, autoFocus: true }) }));
+    }
+    // Text editor (default, shared across all frameworks)
+    return (_jsx("div", { ref: wrapperRef, style: editorWrapperStyle, children: _jsx("input", { type: "text", value: localValue, onChange: (e) => setLocalValue(e.target.value), onBlur: handleBlur, onKeyDown: handleKeyDown, style: editorInputStyle, autoFocus: true }) }));
+}

package/dist/esm/components/CellErrorBoundary.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+const DEFAULT_FALLBACK_STYLE = {
+    color: '#d32f2f',
+    fontSize: '0.75rem',
+    padding: '2px 4px',
+};
+/**
+ * Error boundary for cell renderers and custom editors.
+ * Prevents a runtime error in a cell from crashing the entire grid.
+ */
+export class CellErrorBoundary extends React.Component {
+    constructor(props) {
+        super(props);
+        this.state = { hasError: false };
+    }
+    static getDerivedStateFromError() {
+        return { hasError: true };
+    }
+    componentDidCatch(error, errorInfo) {
+        if (this.props.onError) {
+            this.props.onError(error, errorInfo);
+        }
+    }
+    componentDidUpdate(prevProps) {
+        // Reset error state when children change (e.g., navigating to a different cell)
+        if (prevProps.children !== this.props.children && this.state.hasError) {
+            this.setState({ hasError: false });
+        }
+    }
+    resetErrorBoundary() {
+        this.setState({ hasError: false });
+    }
+    render() {
+        if (this.state.hasError) {
+            if (this.props.fallback !== undefined) {
+                return this.props.fallback;
+            }
+            return _jsx("span", { style: DEFAULT_FALLBACK_STYLE, children: "\u26A0 Error" });
+        }
+        return this.props.children;
+    }
+}

package/dist/esm/components/EmptyState.js

@@ -0,0 +1,19 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const clearButtonStyle = { background: 'none', border: 'none', color: 'inherit', textDecoration: 'underline', cursor: 'pointer', padding: 0, font: 'inherit' };
+/**
+ * Headless empty state component with default rendering logic.
+ * Framework-specific wrappers provide styling.
+ *
+ * Default behavior:
+ * - Shows "No results found" title
+ * - If hasActiveFilters=true: shows "clear all filters" link
+ * - If message provided: shows custom message
+ * - If render provided: uses custom renderer
+ */
+export function EmptyState(props) {
+    const { message, hasActiveFilters, onClearAll, render } = props;
+    if (render) {
+        return _jsx(_Fragment, { children: render() });
+    }
+    return (_jsx(_Fragment, { children: message != null ? (message) : hasActiveFilters ? (_jsxs(_Fragment, { children: ["No items match your current filters. Try adjusting your search or", ' ', _jsx("button", { type: "button", onClick: onClearAll, style: clearButtonStyle, children: "clear all filters" }), ' ', "to see all items."] })) : ('There are no items available at this time.') }));
+}

package/dist/esm/components/GridContextMenu.js

@@ -1,10 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import * as React from 'react';
 import { GRID_CONTEXT_MENU_ITEMS, getContextMenuHandlers, formatShortcut } from '../utils/gridContextMenuHelpers';
+const menuPositionStyle = (x, y) => ({ left: x, top: y });
 export function GridContextMenu(props) {
-    const { x, y, hasSelection, canUndo, canRedo, onClose, classNames } = props;
+    const { x, y, hasSelection, canUndo, canRedo, onClose, onCopy, onCut, onPaste, onSelectAll, onUndo, onRedo, classNames } = props;
     const ref = React.useRef(null);
-    const handlers = React.useMemo(() => getContextMenuHandlers(props), [props]);
+    const handlers = React.useMemo(() => getContextMenuHandlers({ onCopy, onCut, onPaste, onSelectAll, onUndo, onRedo, onClose }), [onCopy, onCut, onPaste, onSelectAll, onUndo, onRedo, onClose]);
     const isDisabled = React.useCallback((item) => {
         if (item.disabledWhenNoSelection && !hasSelection)
             return true;
@@ -30,5 +31,5 @@ export function GridContextMenu(props) {
             document.removeEventListener('keydown', handleKeyDown, true);
         };
     }, [onClose]);
-    return (_jsx("div", { ref: ref, className: classNames?.contextMenu, role: "menu", style: { left: x, top: y }, "aria-label": "Grid context menu", children: GRID_CONTEXT_MENU_ITEMS.map((item) => (_jsxs(React.Fragment, { children: [item.dividerBefore && _jsx("div", { className: classNames?.contextMenuDivider }), _jsxs("button", { type: "button", className: classNames?.contextMenuItem, onClick: handlers[item.id], disabled: isDisabled(item), children: [_jsx("span", { className: classNames?.contextMenuItemLabel, children: item.label }), item.shortcut && (_jsx("span", { className: classNames?.contextMenuItemShortcut, children: formatShortcut(item.shortcut) }))] })] }, item.id))) }));
+    return (_jsx("div", { ref: ref, className: classNames?.contextMenu, role: "menu", style: menuPositionStyle(x, y), "aria-label": "Grid context menu", children: GRID_CONTEXT_MENU_ITEMS.map((item) => (_jsxs(React.Fragment, { children: [item.dividerBefore && _jsx("div", { className: classNames?.contextMenuDivider }), _jsxs("button", { type: "button", className: classNames?.contextMenuItem, onClick: handlers[item.id], disabled: isDisabled(item), children: [_jsx("span", { className: classNames?.contextMenuItemLabel, children: item.label }), item.shortcut && (_jsx("span", { className: classNames?.contextMenuItemShortcut, children: formatShortcut(item.shortcut) }))] })] }, item.id))) }));
 }

package/dist/esm/components/MarchingAntsOverlay.js

@@ -8,17 +8,18 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * Uses SVG rects positioned via cell data-attribute measurements.
  */
 import { useEffect, useRef, useState, useCallback } from 'react';
-// Inject the @keyframes rule once into <head>
-let styleInjected = false;
+const MARCHING_ANTS_ANIMATION = { animation: 'ogrid-marching-ants 0.5s linear infinite' };
+// Inject the @keyframes rule once into <head> (deduplicates across multiple OGrid instances / module copies)
 function ensureKeyframes() {
-    if (styleInjected || typeof document === 'undefined')
+    if (typeof document === 'undefined')
+        return;
+    if (document.getElementById('ogrid-marching-ants-keyframes'))
         return;
     const style = document.createElement('style');
     style.id = 'ogrid-marching-ants-keyframes';
     style.textContent =
         '@keyframes ogrid-marching-ants{to{stroke-dashoffset:-8}}';
     document.head.appendChild(style);
-    styleInjected = true;
 }
 /** Measure the bounding rect of a range within a container. */
 function measureRange(container, range, colOffset) {
@@ -105,5 +106,5 @@ export function MarchingAntsOverlay({ containerRef, selectionRange, copyRange, c
                     pointerEvents: 'none',
                     zIndex: 5,
                     overflow: 'visible',
-                }, "aria-hidden": "true", children: _jsx("rect", { x: "1", y: "1", width: Math.max(0, clipRect.width - 2), height: Math.max(0, clipRect.height - 2), fill: "none", stroke: "var(--ogrid-selection, #217346)", strokeWidth: "2", strokeDasharray: "4 4", style: { animation: 'ogrid-marching-ants 0.5s linear infinite' } }) }))] }));
+                }, "aria-hidden": "true", children: _jsx("rect", { x: "1", y: "1", width: Math.max(0, clipRect.width - 2), height: Math.max(0, clipRect.height - 2), fill: "none", stroke: "var(--ogrid-selection, #217346)", strokeWidth: "2", strokeDasharray: "4 4", style: MARCHING_ANTS_ANIMATION }) }))] }));
 }

package/dist/esm/components/OGridLayout.js

@@ -1,9 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { SideBar } from './SideBar';
+import { GRID_BORDER_RADIUS } from '../constants';
 // Stable style objects (avoid re-creating on every render)
 const borderedContainerStyle = {
     border: '1px solid var(--ogrid-border, #e0e0e0)',
-    borderRadius: 6,
+    borderRadius: GRID_BORDER_RADIUS,
     overflow: 'hidden',
     display: 'flex',
     flexDirection: 'column',
@@ -66,6 +67,11 @@ const gridChildStyle = {
     display: 'flex',
     flexDirection: 'column',
 };
+const rootStyle = {
+    display: 'flex',
+    flexDirection: 'column',
+    height: '100%',
+};
 /**
  * Renders OGrid layout as a unified bordered container:
  *   ┌────────────────────────────────────┐
@@ -81,10 +87,5 @@ export function OGridLayout(props) {
     const hasSideBar = sideBar != null;
     const sideBarPosition = sideBar?.position ?? 'right';
     const hasToolbar = toolbar != null || toolbarEnd != null;
-    const rootStyle = {
-        display: 'flex',
-        flexDirection: 'column',
-        height: '100%',
-    };
     return (_jsx(Container, { className: className, style: rootStyle, ...containerProps, children: _jsxs("div", { style: borderedContainerStyle, children: [hasToolbar && (_jsxs("div", { style: toolbarBelow ? toolbarStripNoBorderStyle : toolbarStripStyle, children: [_jsx("div", { style: toolbarSectionStyle, children: toolbar }), _jsx("div", { style: toolbarSectionStyle, children: toolbarEnd })] })), toolbarBelow && (_jsx("div", { style: toolbarBelowStyle, children: toolbarBelow })), hasSideBar ? (_jsxs("div", { style: gridAreaFlexStyle, children: [sideBarPosition === 'left' && _jsx(SideBar, { ...sideBar }), _jsx("div", { style: gridChildStyle, children: children }), sideBarPosition !== 'left' && _jsx(SideBar, { ...sideBar })] })) : (_jsx("div", { style: gridAreaSoloStyle, children: children })), pagination && (_jsx("div", { style: footerStripStyle, children: pagination }))] }) }));
 }

package/dist/esm/components/SideBar.js

@@ -5,50 +5,72 @@ const PANEL_LABELS = {
     columns: 'Columns',
     filters: 'Filters',
 };
+// --- Stable style objects (avoid re-creating on every render) ---
+const tabStripBaseStyle = {
+    display: 'flex',
+    flexDirection: 'column',
+    width: TAB_WIDTH,
+    background: 'var(--ogrid-header-bg, #f5f5f5)',
+};
+const tabStripBorderLeft = { ...tabStripBaseStyle, borderLeft: '1px solid var(--ogrid-border, #e0e0e0)' };
+const tabStripBorderRight = { ...tabStripBaseStyle, borderRight: '1px solid var(--ogrid-border, #e0e0e0)' };
+const tabButtonBase = {
+    width: TAB_WIDTH,
+    height: TAB_WIDTH,
+    border: 'none',
+    cursor: 'pointer',
+    color: 'var(--ogrid-fg, #242424)',
+    fontSize: 14,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+};
+const tabButtonActive = { ...tabButtonBase, background: 'var(--ogrid-bg, #fff)', fontWeight: 'bold' };
+const tabButtonInactive = { ...tabButtonBase, background: 'transparent', fontWeight: 'normal' };
+const panelContainerBase = {
+    width: PANEL_WIDTH,
+    display: 'flex',
+    flexDirection: 'column',
+    overflow: 'hidden',
+    background: 'var(--ogrid-bg, #fff)',
+    color: 'var(--ogrid-fg, #242424)',
+};
+const panelContainerBorderLeft = { ...panelContainerBase, borderLeft: '1px solid var(--ogrid-border, #e0e0e0)' };
+const panelContainerBorderRight = { ...panelContainerBase, borderRight: '1px solid var(--ogrid-border, #e0e0e0)' };
+const panelHeaderStyle = {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    padding: '8px 12px',
+    borderBottom: '1px solid var(--ogrid-border, #e0e0e0)',
+    fontWeight: 600,
+};
+const closeButtonStyle = { border: 'none', background: 'transparent', cursor: 'pointer', fontSize: 16, color: 'var(--ogrid-fg, #242424)' };
+const panelBodyStyle = { flex: 1, overflowY: 'auto', padding: '8px 12px' };
+const sideBarRootStyle = { display: 'flex', flexDirection: 'row', flexShrink: 0 };
+const buttonRowStyle = { display: 'flex', gap: 8, marginBottom: 8 };
+const actionButtonStyle = { flex: 1, cursor: 'pointer', background: 'var(--ogrid-bg-subtle, #f3f2f1)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4, padding: '4px 8px' };
+const checkboxLabelStyle = { display: 'flex', alignItems: 'center', gap: 6, padding: '2px 0', cursor: 'pointer' };
+const noFilterStyle = { color: 'var(--ogrid-muted, #999)', fontStyle: 'italic' };
+const filterGroupStyle = { marginBottom: 12 };
+const filterLabelStyle = { fontWeight: 500, marginBottom: 4, fontSize: 13 };
+const textInputStyle = { width: '100%', boxSizing: 'border-box', padding: '4px 6px', background: 'var(--ogrid-bg, #fff)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4 };
+const dateContainerStyle = { display: 'flex', flexDirection: 'column', gap: 4 };
+const dateLabelStyle = { display: 'flex', alignItems: 'center', gap: 4, fontSize: 12 };
+const dateInputStyle = { flex: 1, padding: '2px 4px', background: 'var(--ogrid-bg, #fff)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4 };
+const multiSelectContainerStyle = { maxHeight: 120, overflowY: 'auto' };
+const multiSelectLabelStyle = { display: 'flex', alignItems: 'center', gap: 4, padding: '1px 0', cursor: 'pointer', fontSize: 13 };
 export function SideBar(props) {
     const { activePanel, onPanelChange, panels, position, columns, visibleColumns, onVisibilityChange, onSetVisibleColumns, filterableColumns, filters, onFilterChange, filterOptions, } = props;
     const isOpen = activePanel !== null;
     const handleTabClick = (panel) => {
         onPanelChange(activePanel === panel ? null : panel);
     };
-    const tabStrip = (_jsx("div", { style: {
-            display: 'flex',
-            flexDirection: 'column',
-            width: TAB_WIDTH,
-            borderLeft: position === 'right' ? '1px solid var(--ogrid-border, #e0e0e0)' : undefined,
-            borderRight: position === 'left' ? '1px solid var(--ogrid-border, #e0e0e0)' : undefined,
-            background: 'var(--ogrid-header-bg, #f5f5f5)',
-        }, role: "tablist", "aria-label": "Side bar tabs", children: panels.map((panel) => (_jsx("button", { role: "tab", "aria-selected": activePanel === panel, "aria-label": PANEL_LABELS[panel], onClick: () => handleTabClick(panel), title: PANEL_LABELS[panel], style: {
-                width: TAB_WIDTH,
-                height: TAB_WIDTH,
-                border: 'none',
-                cursor: 'pointer',
-                background: activePanel === panel ? 'var(--ogrid-bg, #fff)' : 'transparent',
-                color: 'var(--ogrid-fg, #242424)',
-                fontWeight: activePanel === panel ? 'bold' : 'normal',
-                fontSize: 14,
-                display: 'flex',
-                alignItems: 'center',
-                justifyContent: 'center',
-            }, children: panel === 'columns' ? '\u2261' : '\u2A65' }, panel))) }));
-    const panelContent = isOpen ? (_jsxs("div", { role: "tabpanel", "aria-label": PANEL_LABELS[activePanel], style: {
-            width: PANEL_WIDTH,
-            display: 'flex',
-            flexDirection: 'column',
-            borderLeft: position === 'right' ? '1px solid var(--ogrid-border, #e0e0e0)' : undefined,
-            borderRight: position === 'left' ? '1px solid var(--ogrid-border, #e0e0e0)' : undefined,
-            overflow: 'hidden',
-            background: 'var(--ogrid-bg, #fff)',
-            color: 'var(--ogrid-fg, #242424)',
-        }, children: [_jsxs("div", { style: {
-                    display: 'flex',
-                    justifyContent: 'space-between',
-                    alignItems: 'center',
-                    padding: '8px 12px',
-                    borderBottom: '1px solid var(--ogrid-border, #e0e0e0)',
-                    fontWeight: 600,
-                }, children: [_jsx("span", { children: PANEL_LABELS[activePanel] }), _jsx("button", { onClick: () => onPanelChange(null), style: { border: 'none', background: 'transparent', cursor: 'pointer', fontSize: 16, color: 'var(--ogrid-fg, #242424)' }, "aria-label": "Close panel", children: "\u00D7" })] }), _jsxs("div", { style: { flex: 1, overflowY: 'auto', padding: '8px 12px' }, children: [activePanel === 'columns' && (_jsx(ColumnsPanel, { columns: columns, visibleColumns: visibleColumns, onVisibilityChange: onVisibilityChange, onSetVisibleColumns: onSetVisibleColumns })), activePanel === 'filters' && (_jsx(FiltersPanel, { filterableColumns: filterableColumns, filters: filters, onFilterChange: onFilterChange, filterOptions: filterOptions }))] })] })) : null;
-    return (_jsxs("div", { style: { display: 'flex', flexDirection: 'row', flexShrink: 0 }, role: "complementary", "aria-label": "Side bar", children: [position === 'left' && tabStrip, position === 'left' && panelContent, position === 'right' && panelContent, position === 'right' && tabStrip] }));
+    const tabStripStyle = position === 'right' ? tabStripBorderLeft : tabStripBorderRight;
+    const panelContainerStyle = position === 'right' ? panelContainerBorderLeft : panelContainerBorderRight;
+    const tabStrip = (_jsx("div", { style: tabStripStyle, role: "tablist", "aria-label": "Side bar tabs", children: panels.map((panel) => (_jsx("button", { role: "tab", "aria-selected": activePanel === panel, "aria-label": PANEL_LABELS[panel], onClick: () => handleTabClick(panel), title: PANEL_LABELS[panel], style: activePanel === panel ? tabButtonActive : tabButtonInactive, children: panel === 'columns' ? '\u2261' : '\u2A65' }, panel))) }));
+    const panelContent = isOpen ? (_jsxs("div", { role: "tabpanel", "aria-label": PANEL_LABELS[activePanel], style: panelContainerStyle, children: [_jsxs("div", { style: panelHeaderStyle, children: [_jsx("span", { children: PANEL_LABELS[activePanel] }), _jsx("button", { onClick: () => onPanelChange(null), style: closeButtonStyle, "aria-label": "Close panel", children: "\u00D7" })] }), _jsxs("div", { style: panelBodyStyle, children: [activePanel === 'columns' && (_jsx(ColumnsPanel, { columns: columns, visibleColumns: visibleColumns, onVisibilityChange: onVisibilityChange, onSetVisibleColumns: onSetVisibleColumns })), activePanel === 'filters' && (_jsx(FiltersPanel, { filterableColumns: filterableColumns, filters: filters, onFilterChange: onFilterChange, filterOptions: filterOptions }))] })] })) : null;
+    return (_jsxs("div", { style: sideBarRootStyle, role: "complementary", "aria-label": "Side bar", children: [position === 'left' && tabStrip, position === 'left' && panelContent, position === 'right' && panelContent, position === 'right' && tabStrip] }));
 }
 // --- Internal sub-components ---
 function ColumnsPanel(props) {
@@ -67,28 +89,28 @@ function ColumnsPanel(props) {
         });
         onSetVisibleColumns(next);
     };
-    return (_jsxs(_Fragment, { children: [_jsxs("div", { style: { display: 'flex', gap: 8, marginBottom: 8 }, children: [_jsx("button", { onClick: handleSelectAll, disabled: allVisible, style: { flex: 1, cursor: 'pointer', background: 'var(--ogrid-bg-subtle, #f3f2f1)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4, padding: '4px 8px' }, children: "Select All" }), _jsx("button", { onClick: handleClearAll, style: { flex: 1, cursor: 'pointer', background: 'var(--ogrid-bg-subtle, #f3f2f1)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4, padding: '4px 8px' }, children: "Clear All" })] }), columns.map((col) => (_jsxs("label", { style: { display: 'flex', alignItems: 'center', gap: 6, padding: '2px 0', cursor: 'pointer' }, children: [_jsx("input", { type: "checkbox", checked: visibleColumns.has(col.columnId), onChange: (e) => onVisibilityChange(col.columnId, e.target.checked), disabled: col.required }), _jsx("span", { children: col.name })] }, col.columnId)))] }));
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { style: buttonRowStyle, children: [_jsx("button", { onClick: handleSelectAll, disabled: allVisible, style: actionButtonStyle, children: "Select All" }), _jsx("button", { onClick: handleClearAll, style: actionButtonStyle, children: "Clear All" })] }), columns.map((col) => (_jsxs("label", { style: checkboxLabelStyle, children: [_jsx("input", { type: "checkbox", checked: visibleColumns.has(col.columnId), onChange: (e) => onVisibilityChange(col.columnId, e.target.checked), disabled: col.required }), _jsx("span", { children: col.name })] }, col.columnId)))] }));
 }
 function FiltersPanel(props) {
     const { filterableColumns, filters, onFilterChange, filterOptions } = props;
     if (filterableColumns.length === 0) {
-        return _jsx("div", { style: { color: 'var(--ogrid-muted, #999)', fontStyle: 'italic' }, children: "No filterable columns" });
+        return _jsx("div", { style: noFilterStyle, children: "No filterable columns" });
     }
     return (_jsx(_Fragment, { children: filterableColumns.map((col) => {
             const filterKey = col.filterField;
-            return (_jsxs("div", { style: { marginBottom: 12 }, children: [_jsx("div", { style: { fontWeight: 500, marginBottom: 4, fontSize: 13 }, children: col.name }), col.filterType === 'text' && (_jsx("input", { type: "text", value: filters[filterKey]?.type === 'text' ? filters[filterKey].value : '', onChange: (e) => onFilterChange(filterKey, e.target.value ? { type: 'text', value: e.target.value } : undefined), placeholder: `Filter ${col.name}...`, "aria-label": `Filter ${col.name}`, style: { width: '100%', boxSizing: 'border-box', padding: '4px 6px', background: 'var(--ogrid-bg, #fff)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4 } })), col.filterType === 'date' && (_jsxs("div", { style: { display: 'flex', flexDirection: 'column', gap: 4 }, children: [_jsxs("label", { style: { display: 'flex', alignItems: 'center', gap: 4, fontSize: 12 }, children: ["From:", _jsx("input", { type: "date", value: filters[filterKey]?.type === 'date' ? (filters[filterKey].value.from ?? '') : '', onChange: (e) => {
+            return (_jsxs("div", { style: filterGroupStyle, children: [_jsx("div", { style: filterLabelStyle, children: col.name }), col.filterType === 'text' && (_jsx("input", { type: "text", value: filters[filterKey]?.type === 'text' ? filters[filterKey].value : '', onChange: (e) => onFilterChange(filterKey, e.target.value ? { type: 'text', value: e.target.value } : undefined), placeholder: `Filter ${col.name}...`, "aria-label": `Filter ${col.name}`, style: textInputStyle })), col.filterType === 'date' && (_jsxs("div", { style: dateContainerStyle, children: [_jsxs("label", { style: dateLabelStyle, children: ["From:", _jsx("input", { type: "date", value: filters[filterKey]?.type === 'date' ? (filters[filterKey].value.from ?? '') : '', onChange: (e) => {
                                             const from = e.target.value || undefined;
                                             const existingValue = filters[filterKey]?.type === 'date' ? filters[filterKey].value : {};
                                             const to = existingValue.to;
                                             onFilterChange(filterKey, from || to ? { type: 'date', value: { from, to } } : undefined);
-                                        }, "aria-label": `${col.name} from date`, style: { flex: 1, padding: '2px 4px', background: 'var(--ogrid-bg, #fff)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4 } })] }), _jsxs("label", { style: { display: 'flex', alignItems: 'center', gap: 4, fontSize: 12 }, children: ["To:", _jsx("input", { type: "date", value: filters[filterKey]?.type === 'date' ? (filters[filterKey].value.to ?? '') : '', onChange: (e) => {
+                                        }, "aria-label": `${col.name} from date`, style: dateInputStyle })] }), _jsxs("label", { style: dateLabelStyle, children: ["To:", _jsx("input", { type: "date", value: filters[filterKey]?.type === 'date' ? (filters[filterKey].value.to ?? '') : '', onChange: (e) => {
                                             const to = e.target.value || undefined;
                                             const existingValue = filters[filterKey]?.type === 'date' ? filters[filterKey].value : {};
                                             const from = existingValue.from;
                                             onFilterChange(filterKey, from || to ? { type: 'date', value: { from, to } } : undefined);
-                                        }, "aria-label": `${col.name} to date`, style: { flex: 1, padding: '2px 4px', background: 'var(--ogrid-bg, #fff)', color: 'var(--ogrid-fg, #242424)', border: '1px solid var(--ogrid-border, #e0e0e0)', borderRadius: 4 } })] })] })), col.filterType === 'multiSelect' && (_jsx("div", { style: { maxHeight: 120, overflowY: 'auto' }, role: "group", "aria-label": `${col.name} options`, children: (filterOptions[filterKey] ?? []).map((opt) => {
+                                        }, "aria-label": `${col.name} to date`, style: dateInputStyle })] })] })), col.filterType === 'multiSelect' && (_jsx("div", { style: multiSelectContainerStyle, role: "group", "aria-label": `${col.name} options`, children: (filterOptions[filterKey] ?? []).map((opt) => {
                             const selected = filters[filterKey]?.type === 'multiSelect' ? filters[filterKey].value.includes(opt) : false;
-                            return (_jsxs("label", { style: { display: 'flex', alignItems: 'center', gap: 4, padding: '1px 0', cursor: 'pointer', fontSize: 13 }, children: [_jsx("input", { type: "checkbox", checked: selected, onChange: (e) => {
+                            return (_jsxs("label", { style: multiSelectLabelStyle, children: [_jsx("input", { type: "checkbox", checked: selected, onChange: (e) => {
                                             const current = filters[filterKey]?.type === 'multiSelect' ? filters[filterKey].value : [];
                                             const next = e.target.checked
                                                 ? [...current, opt]

package/dist/esm/constants.js

@@ -0,0 +1,11 @@
+/**
+ * Core OGrid constants — magic numbers centralized for consistency and maintainability.
+ */
+/** Width of the row selection checkbox column in pixels. */
+export const CHECKBOX_COLUMN_WIDTH = 48;
+/** Default minimum width for resizable columns in pixels. */
+export const DEFAULT_MIN_COLUMN_WIDTH = 80;
+/** Horizontal padding inside cells, used for width calculations. */
+export const CELL_PADDING = 16;
+/** Border radius for the grid container in pixels. */
+export const GRID_BORDER_RADIUS = 6;

package/dist/esm/hooks/index.js

@@ -12,8 +12,14 @@ export { useDebounce } from './useDebounce';
 export { useFillHandle } from './useFillHandle';
 export { useDataGridState } from './useDataGridState';
 export { useColumnHeaderFilterState } from './useColumnHeaderFilterState';
+export { useTextFilterState } from './useTextFilterState';
+export { useMultiSelectFilterState } from './useMultiSelectFilterState';
+export { usePeopleFilterState } from './usePeopleFilterState';
+export { useDateFilterState } from './useDateFilterState';
 export { useColumnChooserState } from './useColumnChooserState';
 export { useInlineCellEditorState } from './useInlineCellEditorState';
 export { useColumnResize } from './useColumnResize';
 export { useRichSelectState } from './useRichSelectState';
 export { useSideBarState } from './useSideBarState';
+export { useTableLayout } from './useTableLayout';
+export { useLatestRef } from './useLatestRef';

package/dist/esm/hooks/useActiveCell.js

@@ -29,18 +29,34 @@ export function useActiveCell(wrapperRef, editingCell) {
         const selector = `[data-row-index="${rowIndex}"][data-col-index="${columnIndex}"]`;
         const cell = wrapperRef.current.querySelector(selector);
         if (cell) {
-            if (typeof cell.scrollIntoView === 'function') {
-                // Account for sticky <thead> so scrollIntoView doesn't leave
-                // the cell hidden behind the header.
-                const thead = wrapperRef.current.querySelector('thead');
-                const headerHeight = thead ? thead.getBoundingClientRect().height : 0;
-                cell.style.scrollMarginTop = `${headerHeight}px`;
-                cell.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+            // Scroll the cell into view within the table wrapper only — do NOT
+            // use native scrollIntoView() which scrolls all ancestor containers
+            // including the page, causing an unwanted viewport jump.
+            const wrapper = wrapperRef.current;
+            const thead = wrapper.querySelector('thead');
+            const headerHeight = thead ? thead.getBoundingClientRect().height : 0;
+            const wrapperRect = wrapper.getBoundingClientRect();
+            const cellRect = cell.getBoundingClientRect();
+            // Vertical scroll (account for sticky thead)
+            const visibleTop = wrapperRect.top + headerHeight;
+            if (cellRect.top < visibleTop) {
+                wrapper.scrollTop -= visibleTop - cellRect.top;
+            }
+            else if (cellRect.bottom > wrapperRect.bottom) {
+                wrapper.scrollTop += cellRect.bottom - wrapperRect.bottom;
+            }
+            // Horizontal scroll
+            if (cellRect.left < wrapperRect.left) {
+                wrapper.scrollLeft -= wrapperRect.left - cellRect.left;
+            }
+            else if (cellRect.right > wrapperRect.right) {
+                wrapper.scrollLeft += cellRect.right - wrapperRect.right;
             }
             if (document.activeElement !== cell && typeof cell.focus === 'function') {
-                cell.focus();
+                cell.focus({ preventScroll: true });
             }
         }
-    }, [activeCell, editingCell, wrapperRef]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [activeCell, editingCell]); // wrapperRef excluded — refs are stable across renders
     return { activeCell, setActiveCell };
 }

package/dist/esm/hooks/useCellEditing.js

@@ -1,4 +1,8 @@
 import { useState } from 'react';
+/**
+ * Manages cell editing state: which cell is being edited and its pending value.
+ * @returns Current editing cell, setter, pending editor value, and setter.
+ */
 export function useCellEditing() {
     const [editingCell, setEditingCell] = useState(null);
     const [pendingEditorValue, setPendingEditorValue] = useState(undefined);

package/dist/esm/hooks/useCellSelection.js

@@ -21,6 +21,11 @@ function autoScrollSpeed(distance) {
     const t = Math.min(distance / AUTO_SCROLL_EDGE, 1);
     return AUTO_SCROLL_MIN_SPEED + t * (AUTO_SCROLL_MAX_SPEED - AUTO_SCROLL_MIN_SPEED);
 }
+/**
+ * Manages cell selection range with drag-to-select and select-all support.
+ * @param params - Row/col counts, active cell setter, and wrapper ref for auto-scroll.
+ * @returns Selection range, setters, mouse/keyboard handlers, and drag state.
+ */
 export function useCellSelection(params) {
     const { colOffset, rowCount, visibleColCount, setActiveCell, wrapperRef } = params;
     const [selectionRange, _setSelectionRange] = useState(null);
@@ -307,7 +312,8 @@ export function useCellSelection(params) {
                 cancelAnimationFrame(rafRef.current);
             stopAutoScroll();
         };
-    }, [colOffset, setActiveCell, wrapperRef]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [colOffset, setActiveCell]); // wrapperRef excluded — refs are stable across renders
     return {
         selectionRange,
         setSelectionRange,