@alaarab/ogrid-react 2.0.0-beta

package/README.md

@@ -0,0 +1,55 @@
+<p align="center">
+  <strong>OGrid React</strong> — React hooks, headless components, and utilities for OGrid data grids.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@alaarab/ogrid-react"><img src="https://img.shields.io/npm/v/@alaarab/ogrid-react?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>
+
+<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>
+
+---
+
+React hooks and headless components for [OGrid](https://github.com/alaarab/ogrid) data grids. You typically don't need to install this directly — the UI packages ([`@alaarab/ogrid-react-radix`](https://www.npmjs.com/package/@alaarab/ogrid-react-radix), [`@alaarab/ogrid-react-fluent`](https://www.npmjs.com/package/@alaarab/ogrid-react-fluent), [`@alaarab/ogrid-react-material`](https://www.npmjs.com/package/@alaarab/ogrid-react-material)) re-export everything from this package.
+
+## 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`
+
+### Headless Components
+
+`OGridLayout` · `StatusBar` · `GridContextMenu` · `SideBar` · `MarchingAntsOverlay`
+
+### Utilities
+
+`processClientSideData` · `exportToCsv` · `getCellValue` · `flattenColumns` · `buildHeaderRows` · `getPaginationViewModel` · `getHeaderFilterConfig` · `getCellRenderDescriptor` · `computeAggregations` · `formatShortcut` · `GRID_CONTEXT_MENU_ITEMS`
+
+## Install
+
+```bash
+npm install @alaarab/ogrid-react
+```
+
+Peer dep: `react ^17 || ^18 || ^19`.
+
+## Documentation
+
+Full docs at **[alaarab.github.io/ogrid](https://alaarab.github.io/ogrid/)**.
+
+## License
+
+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

@@ -0,0 +1,35 @@
+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';
+const menuPositionStyle = (x, y) => ({ left: x, top: y });
+export function GridContextMenu(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({ 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;
+        if (item.id === 'undo' && !canUndo)
+            return true;
+        if (item.id === 'redo' && !canRedo)
+            return true;
+        return false;
+    }, [hasSelection, canUndo, canRedo]);
+    React.useEffect(() => {
+        const handleClickOutside = (e) => {
+            if (ref.current && !ref.current.contains(e.target))
+                onClose();
+        };
+        const handleKeyDown = (e) => {
+            if (e.key === 'Escape')
+                onClose();
+        };
+        document.addEventListener('mousedown', handleClickOutside, true);
+        document.addEventListener('keydown', handleKeyDown, true);
+        return () => {
+            document.removeEventListener('mousedown', handleClickOutside, true);
+            document.removeEventListener('keydown', handleKeyDown, true);
+        };
+    }, [onClose]);
+    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

@@ -0,0 +1,110 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * MarchingAntsOverlay — Renders range overlays on top of the grid:
+ *
+ * 1. **Selection range**: solid green border around the current selection
+ * 2. **Copy/Cut range**: animated dashed border (marching ants) like Excel
+ *
+ * Uses SVG rects positioned via cell data-attribute measurements.
+ */
+import { useEffect, useRef, useState, useCallback } from 'react';
+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 (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);
+}
+/** Measure the bounding rect of a range within a container. */
+function measureRange(container, range, colOffset) {
+    const startGlobalCol = range.startCol + colOffset;
+    const endGlobalCol = range.endCol + colOffset;
+    const topLeft = container.querySelector(`[data-row-index="${range.startRow}"][data-col-index="${startGlobalCol}"]`);
+    const bottomRight = container.querySelector(`[data-row-index="${range.endRow}"][data-col-index="${endGlobalCol}"]`);
+    if (!topLeft || !bottomRight)
+        return null;
+    const cRect = container.getBoundingClientRect();
+    const tlRect = topLeft.getBoundingClientRect();
+    const brRect = bottomRight.getBoundingClientRect();
+    return {
+        top: tlRect.top - cRect.top,
+        left: tlRect.left - cRect.left,
+        width: brRect.right - tlRect.left,
+        height: brRect.bottom - tlRect.top,
+    };
+}
+export function MarchingAntsOverlay({ containerRef, selectionRange, copyRange, cutRange, colOffset, }) {
+    const [selRect, setSelRect] = useState(null);
+    const [clipRect, setClipRect] = useState(null);
+    const rafRef = useRef(0);
+    const clipRange = copyRange ?? cutRange;
+    const measureAll = useCallback(() => {
+        const container = containerRef.current;
+        if (!container) {
+            setSelRect(null);
+            setClipRect(null);
+            return;
+        }
+        setSelRect(selectionRange ? measureRange(container, selectionRange, colOffset) : null);
+        setClipRect(clipRange ? measureRange(container, clipRange, colOffset) : null);
+    }, [selectionRange, clipRange, containerRef, colOffset]);
+    // Inject keyframes on mount
+    useEffect(() => {
+        ensureKeyframes();
+    }, []);
+    // Measure when any range changes; re-measure on resize
+    useEffect(() => {
+        if (!selectionRange && !clipRange) {
+            setSelRect(null);
+            setClipRect(null);
+            return;
+        }
+        // Delay one frame so cells are rendered
+        rafRef.current = requestAnimationFrame(measureAll);
+        const container = containerRef.current;
+        let ro;
+        if (container) {
+            ro = new ResizeObserver(measureAll);
+            ro.observe(container);
+        }
+        return () => {
+            cancelAnimationFrame(rafRef.current);
+            ro?.disconnect();
+        };
+    }, [selectionRange, clipRange, measureAll, containerRef]);
+    if (!selRect && !clipRect)
+        return null;
+    // When clipboard range matches the selection range, hide the solid selection border
+    // so the marching ants animation is clearly visible (not obscured by solid stroke underneath).
+    const clipRangeMatchesSel = selectionRange != null &&
+        clipRange != null &&
+        selectionRange.startRow === clipRange.startRow &&
+        selectionRange.startCol === clipRange.startCol &&
+        selectionRange.endRow === clipRange.endRow &&
+        selectionRange.endCol === clipRange.endCol;
+    return (_jsxs(_Fragment, { children: [selRect && !clipRangeMatchesSel && (_jsx("svg", { style: {
+                    position: 'absolute',
+                    top: selRect.top,
+                    left: selRect.left,
+                    width: selRect.width,
+                    height: selRect.height,
+                    pointerEvents: 'none',
+                    zIndex: 4,
+                    overflow: 'visible',
+                }, "aria-hidden": "true", children: _jsx("rect", { x: "1", y: "1", width: Math.max(0, selRect.width - 2), height: Math.max(0, selRect.height - 2), fill: "none", stroke: "var(--ogrid-selection, #217346)", strokeWidth: "2" }) })), clipRect && (_jsx("svg", { style: {
+                    position: 'absolute',
+                    top: clipRect.top,
+                    left: clipRect.left,
+                    width: clipRect.width,
+                    height: clipRect.height,
+                    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: MARCHING_ANTS_ANIMATION }) }))] }));
+}

package/dist/esm/components/OGridLayout.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { SideBar } from './SideBar';
+import { GRID_BORDER_RADIUS } from '@alaarab/ogrid-core';
+// Stable style objects (avoid re-creating on every render)
+const borderedContainerStyle = {
+    border: '1px solid var(--ogrid-border, #e0e0e0)',
+    borderRadius: GRID_BORDER_RADIUS,
+    overflow: 'hidden',
+    display: 'flex',
+    flexDirection: 'column',
+    flex: 1,
+    minHeight: 0,
+    background: 'var(--ogrid-bg, #fff)',
+};
+const toolbarStripBase = {
+    display: 'flex',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    padding: '6px 12px',
+    background: 'var(--ogrid-header-bg, #f5f5f5)',
+    gap: 8,
+    flexWrap: 'wrap',
+    minHeight: 0,
+};
+/** Toolbar strip with border-bottom (when it's the only toolbar row). */
+const toolbarStripStyle = {
+    ...toolbarStripBase,
+    borderBottom: '1px solid var(--ogrid-border, #e0e0e0)',
+};
+/** Toolbar strip without border-bottom (when toolbarBelow follows — it owns the border). */
+const toolbarStripNoBorderStyle = toolbarStripBase;
+const toolbarSectionStyle = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 8,
+};
+/** Secondary toolbar row (e.g. active filter chips). Matches toolbar strip styling. */
+const toolbarBelowStyle = {
+    borderBottom: '1px solid var(--ogrid-border, #e0e0e0)',
+    padding: '6px 12px',
+    background: 'var(--ogrid-header-bg, #f5f5f5)',
+};
+const footerStripStyle = {
+    borderTop: '1px solid var(--ogrid-border, #e0e0e0)',
+    background: 'var(--ogrid-header-bg, #f5f5f5)',
+    padding: '6px 12px',
+};
+const gridAreaFlexStyle = {
+    width: '100%',
+    minWidth: 0,
+    minHeight: 0,
+    flex: 1,
+    display: 'flex',
+};
+const gridAreaSoloStyle = {
+    width: '100%',
+    minWidth: 0,
+    minHeight: 0,
+    flex: 1,
+    display: 'flex',
+    flexDirection: 'column',
+};
+const gridChildStyle = {
+    flex: 1,
+    minWidth: 0,
+    minHeight: 0,
+    display: 'flex',
+    flexDirection: 'column',
+};
+const rootStyle = {
+    display: 'flex',
+    flexDirection: 'column',
+    height: '100%',
+};
+/**
+ * Renders OGrid layout as a unified bordered container:
+ *   ┌────────────────────────────────────┐
+ *   │ [toolbar strip]                    │
+ *   ├────────────────────────────────────┤
+ *   │ [sidebar]? [grid]                  │
+ *   ├────────────────────────────────────┤
+ *   │ [footer strip / pagination]        │
+ *   └────────────────────────────────────┘
+ */
+export function OGridLayout(props) {
+    const { containerComponent: Container = 'div', containerProps = {}, className, toolbar, toolbarEnd, toolbarBelow, children, pagination, sideBar, } = props;
+    const hasSideBar = sideBar != null;
+    const sideBarPosition = sideBar?.position ?? 'right';
+    const hasToolbar = toolbar != null || toolbarEnd != null;
+    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

@@ -0,0 +1,122 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const PANEL_WIDTH = 240;
+const TAB_WIDTH = 36;
+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 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) {
+    const { columns, visibleColumns, onVisibilityChange, onSetVisibleColumns } = props;
+    const allVisible = columns.every((c) => visibleColumns.has(c.columnId));
+    const handleSelectAll = () => {
+        const next = new Set(visibleColumns);
+        columns.forEach((c) => next.add(c.columnId));
+        onSetVisibleColumns(next);
+    };
+    const handleClearAll = () => {
+        const next = new Set();
+        columns.forEach((c) => {
+            if (c.required && visibleColumns.has(c.columnId))
+                next.add(c.columnId);
+        });
+        onSetVisibleColumns(next);
+    };
+    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: noFilterStyle, children: "No filterable columns" });
+    }
+    return (_jsx(_Fragment, { children: filterableColumns.map((col) => {
+            const filterKey = col.filterField;
+            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: 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: 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: 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]
+                                                : current.filter((v) => v !== opt);
+                                            onFilterChange(filterKey, next.length > 0 ? { type: 'multiSelect', value: next } : undefined);
+                                        } }), _jsx("span", { children: opt })] }, opt));
+                        }) }))] }, col.columnId));
+        }) }));
+}

package/dist/esm/components/StatusBar.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { getStatusBarParts } from '../utils';
+export function StatusBar({ classNames, ...rest }) {
+    const parts = getStatusBarParts(rest);
+    return (_jsx("div", { className: classNames?.statusBar, role: "status", "aria-live": "polite", children: parts.map((p) => (_jsxs("span", { className: classNames?.statusBarItem, children: [_jsx("span", { className: classNames?.statusBarLabel, children: p.label }), _jsx("span", { className: classNames?.statusBarValue, children: p.value.toLocaleString() })] }, p.key))) }));
+}

package/dist/esm/hooks/index.js

@@ -0,0 +1,25 @@
+export { useFilterOptions } from './useFilterOptions';
+export { useOGrid } from './useOGrid';
+export { useActiveCell } from './useActiveCell';
+export { useCellEditing } from './useCellEditing';
+export { useContextMenu } from './useContextMenu';
+export { useCellSelection } from './useCellSelection';
+export { useClipboard } from './useClipboard';
+export { useRowSelection } from './useRowSelection';
+export { useKeyboardNavigation } from './useKeyboardNavigation';
+export { useUndoRedo } from './useUndoRedo';
+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';