@alaarab/ogrid-react 2.0.0-beta

package/dist/esm/hooks/useOGrid.js

@@ -0,0 +1,465 @@
+import { useMemo, useCallback, useState, useEffect, useRef, useImperativeHandle, } from 'react';
+import { mergeFilter, deriveFilterOptionsFromData, getMultiSelectFilterFields, flattenColumns, processClientSideData, } from '../utils';
+import { useFilterOptions } from './useFilterOptions';
+import { useSideBarState } from './useSideBarState';
+const DEFAULT_PAGE_SIZE = 25;
+const EMPTY_LOADING_OPTIONS = {};
+/**
+ * Top-level orchestration hook for OGrid: manages pagination, sorting, filtering, column visibility, and sidebar.
+ * @param props - All OGrid props (columns, data, callbacks, feature flags).
+ * @param ref - Forwarded ref for imperative API (refresh, export, applyColumnState).
+ * @returns Grouped props for DataGridTable, pagination controls, column chooser, layout, and filters.
+ */
+export function useOGrid(props, ref) {
+    const { columns: columnsProp, getRowId, data, dataSource, page: controlledPage, pageSize: controlledPageSize, sort: controlledSort, filters: controlledFilters, visibleColumns: controlledVisibleColumns, isLoading: controlledLoading, onPageChange, onPageSizeChange, onSortChange, onFiltersChange, onVisibleColumnsChange, columnOrder, onColumnOrderChange, onColumnResized, onColumnPinned, freezeRows, freezeCols, defaultPageSize = DEFAULT_PAGE_SIZE, defaultSortBy, defaultSortDirection = 'asc', toolbar, toolbarBelow, emptyState, entityLabelPlural = 'items', className, layoutMode = 'fill', suppressHorizontalScroll, editable, cellSelection, onCellValueChanged, onUndo, onRedo, canUndo, canRedo, rowSelection = 'none', selectedRows, onSelectionChange, statusBar, pageSizeOptions, sideBar, onFirstDataRendered, onError, columnChooser: columnChooserProp, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, } = props;
+    // Resolve column chooser placement
+    const columnChooserPlacement = columnChooserProp === false ? 'none'
+        : columnChooserProp === 'sidebar' ? 'sidebar'
+            : 'toolbar';
+    const columns = useMemo(() => flattenColumns(columnsProp), [columnsProp]);
+    const isServerSide = dataSource != null;
+    const isClientSide = !isServerSide;
+    const [internalData, setInternalData] = useState([]);
+    const [internalLoading, setInternalLoading] = useState(false);
+    const displayData = data ?? internalData;
+    const displayLoading = controlledLoading ?? internalLoading;
+    const defaultSortField = defaultSortBy ?? columns[0]?.columnId ?? '';
+    const [internalPage, setInternalPage] = useState(1);
+    const [internalPageSize, setInternalPageSize] = useState(defaultPageSize);
+    const [internalSort, setInternalSort] = useState({
+        field: defaultSortField,
+        direction: defaultSortDirection,
+    });
+    const [internalFilters, setInternalFilters] = useState({});
+    const [internalVisibleColumns, setInternalVisibleColumns] = useState(() => {
+        const visible = columns
+            .filter((c) => c.defaultVisible !== false)
+            .map((c) => c.columnId);
+        return new Set(visible.length > 0 ? visible : columns.map((c) => c.columnId));
+    });
+    const [columnWidthOverrides, setColumnWidthOverrides] = useState({});
+    const [pinnedOverrides, setPinnedOverrides] = useState({});
+    const page = controlledPage ?? internalPage;
+    const pageSize = controlledPageSize ?? internalPageSize;
+    const sort = controlledSort ?? internalSort;
+    const filters = controlledFilters ?? internalFilters;
+    const visibleColumns = controlledVisibleColumns ?? internalVisibleColumns;
+    const setPage = useCallback((p) => {
+        if (controlledPage === undefined)
+            setInternalPage(p);
+        onPageChange?.(p);
+    }, [controlledPage, onPageChange]);
+    const setPageSize = useCallback((size) => {
+        if (controlledPageSize === undefined)
+            setInternalPageSize(size);
+        onPageSizeChange?.(size);
+        setPage(1);
+    }, [controlledPageSize, onPageSizeChange, setPage]);
+    const setSort = useCallback((s) => {
+        if (controlledSort === undefined)
+            setInternalSort(s);
+        onSortChange?.(s);
+        setPage(1);
+    }, [controlledSort, onSortChange, setPage]);
+    const setFilters = useCallback((f) => {
+        if (controlledFilters === undefined)
+            setInternalFilters(f);
+        onFiltersChange?.(f);
+        setPage(1);
+    }, [controlledFilters, onFiltersChange, setPage]);
+    const setVisibleColumns = useCallback((cols) => {
+        if (controlledVisibleColumns === undefined)
+            setInternalVisibleColumns(cols);
+        onVisibleColumnsChange?.(cols);
+    }, [controlledVisibleColumns, onVisibleColumnsChange]);
+    const handleSort = useCallback((columnKey) => {
+        setSort({
+            field: columnKey,
+            direction: sort.field === columnKey && sort.direction === 'asc' ? 'desc' : 'asc',
+        });
+    }, [sort, setSort]);
+    /** Single filter change handler — wraps discriminated FilterValue into mergeFilter. */
+    const handleFilterChange = useCallback((key, value) => {
+        setFilters(mergeFilter(filters, key, value));
+    }, [filters, setFilters]);
+    const handleVisibilityChange = useCallback((columnKey, isVisible) => {
+        const next = new Set(visibleColumns);
+        if (isVisible)
+            next.add(columnKey);
+        else
+            next.delete(columnKey);
+        setVisibleColumns(next);
+    }, [visibleColumns, setVisibleColumns]);
+    const [internalSelectedRows, setInternalSelectedRows] = useState(new Set());
+    const effectiveSelectedRows = selectedRows ?? internalSelectedRows;
+    const handleSelectionChange = useCallback((event) => {
+        if (selectedRows === undefined) {
+            setInternalSelectedRows(new Set(event.selectedRowIds));
+        }
+        onSelectionChange?.(event);
+    }, [selectedRows, onSelectionChange]);
+    const multiSelectFilterFields = useMemo(() => getMultiSelectFilterFields(columns), [columns]);
+    const filterOptionsSource = useMemo(() => dataSource ?? { fetchFilterOptions: undefined }, [dataSource]);
+    const { filterOptions: serverFilterOptions, loadingOptions: loadingFilterOptions } = useFilterOptions(filterOptionsSource, multiSelectFilterFields);
+    const hasServerFilterOptions = dataSource?.fetchFilterOptions != null;
+    const clientFilterOptions = useMemo(() => {
+        if (hasServerFilterOptions)
+            return serverFilterOptions;
+        return deriveFilterOptionsFromData(displayData, columns);
+    }, [hasServerFilterOptions, displayData, columns, serverFilterOptions]);
+    // --- Client-side filtering & sorting ---
+    const clientItemsAndTotal = useMemo(() => {
+        if (!isClientSide)
+            return null;
+        const rows = processClientSideData(displayData, columns, filters, sort.field, sort.direction);
+        const total = rows.length;
+        const start = (page - 1) * pageSize;
+        const paged = rows.slice(start, start + pageSize);
+        return { items: paged, totalCount: total };
+    }, [
+        isClientSide,
+        displayData,
+        columns,
+        filters,
+        sort.field,
+        sort.direction,
+        page,
+        pageSize,
+    ]);
+    const [serverItems, setServerItems] = useState([]);
+    const [serverTotalCount, setServerTotalCount] = useState(0);
+    const [loading, setLoading] = useState(true);
+    const fetchIdRef = useRef(0);
+    // Ref counter to trigger server-side re-fetches
+    const refreshCounterRef = useRef(0);
+    const [refreshCounter, setRefreshCounter] = useState(0);
+    useEffect(() => {
+        if (!isServerSide || !dataSource) {
+            if (!isServerSide)
+                setLoading(false);
+            return;
+        }
+        const id = ++fetchIdRef.current;
+        setLoading(true);
+        dataSource
+            .fetchPage({
+            page,
+            pageSize,
+            sort: { field: sort.field, direction: sort.direction },
+            filters,
+        })
+            .then((res) => {
+            if (id !== fetchIdRef.current)
+                return;
+            setServerItems(res.items);
+            setServerTotalCount(res.totalCount);
+        })
+            .catch((err) => {
+            if (id !== fetchIdRef.current)
+                return;
+            onError?.(err);
+            setServerItems([]);
+            setServerTotalCount(0);
+        })
+            .finally(() => {
+            if (id === fetchIdRef.current)
+                setLoading(false);
+        });
+    }, [
+        isServerSide,
+        dataSource,
+        page,
+        pageSize,
+        sort.field,
+        sort.direction,
+        filters,
+        onError,
+        refreshCounter,
+    ]);
+    const displayItems = isClientSide && clientItemsAndTotal
+        ? clientItemsAndTotal.items
+        : serverItems;
+    const displayTotalCount = isClientSide && clientItemsAndTotal
+        ? clientItemsAndTotal.totalCount
+        : serverTotalCount;
+    // Fire onFirstDataRendered once when the grid first has data
+    const firstDataRenderedRef = useRef(false);
+    useEffect(() => {
+        if (!firstDataRenderedRef.current && displayItems.length > 0) {
+            firstDataRenderedRef.current = true;
+            onFirstDataRendered?.();
+        }
+    }, [displayItems.length, onFirstDataRendered]);
+    useImperativeHandle(ref, () => ({
+        setRowData: (d) => {
+            if (!isServerSide)
+                setInternalData(d);
+        },
+        setLoading: setInternalLoading,
+        getColumnState: () => ({
+            visibleColumns: Array.from(visibleColumns),
+            sort,
+            columnOrder: columnOrder ?? undefined,
+            columnWidths: Object.keys(columnWidthOverrides).length > 0 ? columnWidthOverrides : undefined,
+            filters: Object.keys(filters).length > 0 ? filters : undefined,
+            pinnedColumns: Object.keys(pinnedOverrides).length > 0 ? pinnedOverrides : undefined,
+        }),
+        applyColumnState: (state) => {
+            if (state.visibleColumns) {
+                setVisibleColumns(new Set(state.visibleColumns));
+            }
+            if (state.sort) {
+                setSort(state.sort);
+            }
+            if (state.columnOrder && onColumnOrderChange) {
+                onColumnOrderChange(state.columnOrder);
+            }
+            if (state.columnWidths) {
+                setColumnWidthOverrides(state.columnWidths);
+            }
+            if (state.filters) {
+                setFilters(state.filters);
+            }
+            if (state.pinnedColumns) {
+                setPinnedOverrides(state.pinnedColumns);
+            }
+        },
+        setFilterModel: setFilters,
+        getSelectedRows: () => Array.from(effectiveSelectedRows),
+        setSelectedRows: (rowIds) => {
+            if (selectedRows === undefined)
+                setInternalSelectedRows(new Set(rowIds));
+        },
+        selectAll: () => {
+            const allIds = new Set(displayItems.map((item) => getRowId(item)));
+            if (selectedRows === undefined)
+                setInternalSelectedRows(allIds);
+            onSelectionChange?.({
+                selectedRowIds: Array.from(allIds),
+                selectedItems: displayItems,
+            });
+        },
+        deselectAll: () => {
+            if (selectedRows === undefined)
+                setInternalSelectedRows(new Set());
+            onSelectionChange?.({
+                selectedRowIds: [],
+                selectedItems: [],
+            });
+        },
+        clearFilters: () => setFilters({}),
+        clearSort: () => setSort({ field: defaultSortField, direction: defaultSortDirection }),
+        resetGridState: (options) => {
+            setFilters({});
+            setSort({ field: defaultSortField, direction: defaultSortDirection });
+            if (!options?.keepSelection) {
+                if (selectedRows === undefined)
+                    setInternalSelectedRows(new Set());
+                onSelectionChange?.({ selectedRowIds: [], selectedItems: [] });
+            }
+        },
+        getDisplayedRows: () => displayItems,
+        refreshData: () => {
+            if (isServerSide) {
+                refreshCounterRef.current += 1;
+                setRefreshCounter(refreshCounterRef.current);
+            }
+        },
+    }), [
+        visibleColumns,
+        sort,
+        columnOrder,
+        columnWidthOverrides,
+        pinnedOverrides,
+        filters,
+        setFilters,
+        setSort,
+        setVisibleColumns,
+        onColumnOrderChange,
+        isServerSide,
+        effectiveSelectedRows,
+        selectedRows,
+        displayItems,
+        getRowId,
+        onSelectionChange,
+        defaultSortField,
+        defaultSortDirection,
+    ]);
+    // With discriminated union, any defined value is active (mergeFilter already strips empties)
+    const hasActiveFilters = useMemo(() => {
+        return Object.values(filters).some((v) => v !== undefined);
+    }, [filters]);
+    const columnChooserColumns = useMemo(() => columns.map((c) => ({
+        columnId: c.columnId,
+        name: c.name,
+        required: c.required === true,
+    })), [columns]);
+    const statusBarConfig = useMemo(() => {
+        if (!statusBar)
+            return undefined;
+        if (typeof statusBar === 'object')
+            return statusBar;
+        const totalData = isClientSide ? (data?.length ?? 0) : serverTotalCount;
+        const filteredData = displayTotalCount;
+        return {
+            totalCount: totalData,
+            filteredCount: hasActiveFilters ? filteredData : undefined,
+            selectedCount: effectiveSelectedRows.size,
+            suppressRowCount: true, // OGrid always has pagination which shows the total
+        };
+    }, [
+        statusBar,
+        isClientSide,
+        data,
+        serverTotalCount,
+        displayTotalCount,
+        hasActiveFilters,
+        effectiveSelectedRows.size,
+    ]);
+    const handleColumnResized = useCallback((columnId, width) => {
+        setColumnWidthOverrides((prev) => ({ ...prev, [columnId]: width }));
+        onColumnResized?.(columnId, width);
+    }, [onColumnResized]);
+    const handleColumnPinned = useCallback((columnId, pinned) => {
+        setPinnedOverrides((prev) => {
+            if (pinned === null) {
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const { [columnId]: _, ...rest } = prev;
+                return rest;
+            }
+            return { ...prev, [columnId]: pinned };
+        });
+        onColumnPinned?.(columnId, pinned);
+    }, [onColumnPinned]);
+    // --- Side bar ---
+    const sideBarState = useSideBarState({ config: sideBar });
+    const filterableColumns = useMemo(() => columns
+        .filter((c) => c.filterable && c.filterable.type)
+        .map((c) => ({
+        columnId: c.columnId,
+        name: c.name,
+        filterField: c.filterable.filterField ?? c.columnId,
+        filterType: c.filterable.type,
+    })), [columns]);
+    const sideBarProps = useMemo(() => {
+        if (!sideBarState.isEnabled)
+            return null;
+        return {
+            activePanel: sideBarState.activePanel,
+            onPanelChange: sideBarState.setActivePanel,
+            panels: sideBarState.panels,
+            position: sideBarState.position,
+            columns: columnChooserColumns,
+            visibleColumns,
+            onVisibilityChange: handleVisibilityChange,
+            onSetVisibleColumns: setVisibleColumns,
+            filterableColumns,
+            filters,
+            onFilterChange: handleFilterChange,
+            filterOptions: clientFilterOptions,
+        };
+    }, [
+        sideBarState.isEnabled,
+        sideBarState.activePanel,
+        sideBarState.setActivePanel,
+        sideBarState.panels,
+        sideBarState.position,
+        columnChooserColumns,
+        visibleColumns,
+        handleVisibilityChange,
+        setVisibleColumns,
+        filterableColumns,
+        filters,
+        handleFilterChange,
+        clientFilterOptions,
+    ]);
+    const clearAllFilters = useCallback(() => setFilters({}), [setFilters]);
+    const isLoadingResolved = (isServerSide && loading) || displayLoading;
+    const dataGridProps = useMemo(() => ({
+        items: displayItems,
+        columns: columnsProp,
+        getRowId,
+        sortBy: sort.field,
+        sortDirection: sort.direction,
+        onColumnSort: handleSort,
+        visibleColumns,
+        columnOrder,
+        onColumnOrderChange,
+        onColumnResized: handleColumnResized,
+        onColumnPinned: handleColumnPinned,
+        pinnedColumns: pinnedOverrides,
+        initialColumnWidths: columnWidthOverrides,
+        freezeRows,
+        freezeCols,
+        editable,
+        cellSelection,
+        onCellValueChanged,
+        onUndo,
+        onRedo,
+        canUndo,
+        canRedo,
+        rowSelection,
+        selectedRows: effectiveSelectedRows,
+        onSelectionChange: handleSelectionChange,
+        statusBar: statusBarConfig,
+        isLoading: isLoadingResolved,
+        filters,
+        onFilterChange: handleFilterChange,
+        filterOptions: clientFilterOptions,
+        loadingFilterOptions: dataSource?.fetchFilterOptions ? loadingFilterOptions : EMPTY_LOADING_OPTIONS,
+        peopleSearch: dataSource?.searchPeople,
+        getUserByEmail: dataSource?.getUserByEmail,
+        layoutMode,
+        suppressHorizontalScroll,
+        'aria-label': ariaLabel,
+        'aria-labelledby': ariaLabelledBy,
+        emptyState: {
+            hasActiveFilters,
+            onClearAll: clearAllFilters,
+            message: emptyState?.message,
+            render: emptyState?.render,
+        },
+    }), [
+        displayItems, columnsProp, getRowId, sort.field, sort.direction, handleSort,
+        visibleColumns, columnOrder, onColumnOrderChange, handleColumnResized,
+        handleColumnPinned, pinnedOverrides, columnWidthOverrides, freezeRows, freezeCols,
+        editable, cellSelection, onCellValueChanged, onUndo, onRedo, canUndo, canRedo,
+        rowSelection, effectiveSelectedRows, handleSelectionChange, statusBarConfig,
+        isLoadingResolved, filters, handleFilterChange, clientFilterOptions, dataSource,
+        loadingFilterOptions, layoutMode, suppressHorizontalScroll, ariaLabel, ariaLabelledBy,
+        hasActiveFilters, clearAllFilters, emptyState,
+    ]);
+    const pagination = useMemo(() => ({
+        page,
+        pageSize,
+        displayTotalCount,
+        setPage,
+        setPageSize,
+        pageSizeOptions,
+        entityLabelPlural,
+    }), [page, pageSize, displayTotalCount, setPage, setPageSize, pageSizeOptions, entityLabelPlural]);
+    const columnChooser = useMemo(() => ({
+        columns: columnChooserColumns,
+        visibleColumns,
+        onVisibilityChange: handleVisibilityChange,
+        placement: columnChooserPlacement,
+    }), [columnChooserColumns, visibleColumns, handleVisibilityChange, columnChooserPlacement]);
+    const layout = useMemo(() => ({
+        toolbar,
+        toolbarBelow,
+        className,
+        emptyState,
+        sideBarProps,
+    }), [toolbar, toolbarBelow, className, emptyState, sideBarProps]);
+    const filtersResult = useMemo(() => ({
+        hasActiveFilters,
+        setFilters,
+    }), [hasActiveFilters, setFilters]);
+    return {
+        dataGridProps,
+        pagination,
+        columnChooser,
+        layout,
+        filters: filtersResult,
+    };
+}

package/dist/esm/hooks/usePeopleFilterState.js

@@ -0,0 +1,68 @@
+/**
+ * People filter state sub-hook for column header filters.
+ * Manages people search text, suggestions, loading state, input ref, and user select/clear handlers.
+ * Includes debounced people search effect.
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+const PEOPLE_SEARCH_DEBOUNCE_MS = 300;
+export function usePeopleFilterState(params) {
+    const { onUserChange, peopleSearch, isFilterOpen, filterType } = params;
+    const peopleInputRef = useRef(null);
+    const peopleSearchTimeoutRef = useRef(undefined);
+    const [peopleSuggestions, setPeopleSuggestions] = useState([]);
+    const [isPeopleLoading, setIsPeopleLoading] = useState(false);
+    const [peopleSearchText, setPeopleSearchText] = useState('');
+    // Sync temp state when popover opens
+    useEffect(() => {
+        if (isFilterOpen) {
+            setPeopleSearchText('');
+            setPeopleSuggestions([]);
+            if (filterType === 'people') {
+                setTimeout(() => peopleInputRef.current?.focus(), 50);
+            }
+        }
+    }, [isFilterOpen, filterType]);
+    // People search with debounce
+    useEffect(() => {
+        if (!peopleSearch || !isFilterOpen || filterType !== 'people')
+            return;
+        if (peopleSearchTimeoutRef.current)
+            window.clearTimeout(peopleSearchTimeoutRef.current);
+        if (!peopleSearchText.trim()) {
+            setPeopleSuggestions([]);
+            return;
+        }
+        setIsPeopleLoading(true);
+        peopleSearchTimeoutRef.current = window.setTimeout(async () => {
+            try {
+                const results = await peopleSearch(peopleSearchText);
+                setPeopleSuggestions(results.slice(0, 10));
+            }
+            catch {
+                setPeopleSuggestions([]);
+            }
+            finally {
+                setIsPeopleLoading(false);
+            }
+        }, PEOPLE_SEARCH_DEBOUNCE_MS);
+        return () => {
+            if (peopleSearchTimeoutRef.current)
+                window.clearTimeout(peopleSearchTimeoutRef.current);
+        };
+    }, [peopleSearchText, peopleSearch, isFilterOpen, filterType]);
+    const handleUserSelect = useCallback((user) => {
+        onUserChange?.(user);
+    }, [onUserChange]);
+    const handleClearUser = useCallback(() => {
+        onUserChange?.(undefined);
+    }, [onUserChange]);
+    return {
+        peopleSuggestions,
+        isPeopleLoading,
+        peopleSearchText,
+        setPeopleSearchText,
+        peopleInputRef,
+        handleUserSelect,
+        handleClearUser,
+    };
+}

package/dist/esm/hooks/useRichSelectState.js

@@ -0,0 +1,58 @@
+import { useState, useCallback, useMemo } from 'react';
+/**
+ * Manages searchable rich select editor state with keyboard navigation (arrow keys, enter, escape).
+ * @param params - Values, format function, initial value, and commit/cancel callbacks.
+ * @returns Search text, filtered values, highlighted index, keyboard handler, and select function.
+ */
+export function useRichSelectState(params) {
+    const { values, formatValue, onCommit, onCancel } = params;
+    const [searchText, setSearchText] = useState('');
+    const [highlightedIndex, setHighlightedIndex] = useState(0);
+    const getDisplayText = useCallback((value) => {
+        if (formatValue)
+            return formatValue(value);
+        return value != null ? String(value) : '';
+    }, [formatValue]);
+    const filteredValues = useMemo(() => {
+        if (!searchText.trim())
+            return values;
+        const lower = searchText.toLowerCase();
+        return values.filter((v) => getDisplayText(v).toLowerCase().includes(lower));
+    }, [values, searchText, getDisplayText]);
+    const selectValue = useCallback((value) => {
+        onCommit(value);
+    }, [onCommit]);
+    const handleKeyDown = useCallback((e) => {
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                setHighlightedIndex((prev) => Math.min(prev + 1, filteredValues.length - 1));
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                setHighlightedIndex((prev) => Math.max(prev - 1, 0));
+                break;
+            case 'Enter':
+                e.preventDefault();
+                e.stopPropagation();
+                if (filteredValues.length > 0 && highlightedIndex < filteredValues.length) {
+                    selectValue(filteredValues[highlightedIndex]);
+                }
+                break;
+            case 'Escape':
+                e.preventDefault();
+                e.stopPropagation();
+                onCancel();
+                break;
+        }
+    }, [filteredValues, highlightedIndex, selectValue, onCancel]);
+    return {
+        searchText,
+        setSearchText,
+        filteredValues,
+        highlightedIndex,
+        handleKeyDown,
+        selectValue,
+        getDisplayText,
+    };
+}

package/dist/esm/hooks/useRowSelection.js

@@ -0,0 +1,80 @@
+import { useState, useCallback, useRef, useMemo } from 'react';
+import { useLatestRef } from './useLatestRef';
+/**
+ * Manages row selection state for single or multiple selection modes with shift-click range support.
+ * @param params - Items, getRowId, selection mode, controlled state, and selection change callback.
+ * @returns Selected row IDs, update function, checkbox handlers, and selection state booleans.
+ */
+export function useRowSelection(params) {
+    const { items, getRowId, rowSelection, controlledSelectedRows, onSelectionChange, } = params;
+    const [internalSelectedRows, setInternalSelectedRows] = useState(new Set());
+    const lastClickedRowRef = useRef(-1);
+    // Defensive: convert to Set if caller passes an array (e.g. from JSON state)
+    const selectedRowIds = useMemo(() => controlledSelectedRows != null
+        ? controlledSelectedRows instanceof Set
+            ? controlledSelectedRows
+            : new Set(controlledSelectedRows)
+        : internalSelectedRows, [controlledSelectedRows, internalSelectedRows]);
+    const updateSelection = useCallback((newSelectedIds) => {
+        if (controlledSelectedRows === undefined) {
+            setInternalSelectedRows(newSelectedIds);
+        }
+        onSelectionChange?.({
+            selectedRowIds: Array.from(newSelectedIds),
+            selectedItems: items.filter((item) => newSelectedIds.has(getRowId(item))),
+        });
+    }, [controlledSelectedRows, onSelectionChange, items, getRowId]);
+    // Read selectedRowIds via ref to avoid recreating this callback on every selection change
+    const selectedRowIdsRef = useLatestRef(selectedRowIds);
+    const itemsRef = useLatestRef(items);
+    const handleRowCheckboxChange = useCallback((rowId, checked, rowIndex, shiftKey) => {
+        if (rowSelection === 'single') {
+            updateSelection(checked ? new Set([rowId]) : new Set());
+            lastClickedRowRef.current = rowIndex;
+            return;
+        }
+        const next = new Set(selectedRowIdsRef.current);
+        const currentItems = itemsRef.current;
+        if (shiftKey && lastClickedRowRef.current >= 0 && lastClickedRowRef.current !== rowIndex) {
+            const start = Math.min(lastClickedRowRef.current, rowIndex);
+            const end = Math.max(lastClickedRowRef.current, rowIndex);
+            for (let i = start; i <= end; i++) {
+                if (i < currentItems.length) {
+                    const id = getRowId(currentItems[i]);
+                    if (checked)
+                        next.add(id);
+                    else
+                        next.delete(id);
+                }
+            }
+        }
+        else {
+            if (checked)
+                next.add(rowId);
+            else
+                next.delete(rowId);
+        }
+        lastClickedRowRef.current = rowIndex;
+        updateSelection(next);
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- itemsRef, selectedRowIdsRef are stable refs
+    [rowSelection, getRowId, updateSelection]);
+    const handleSelectAll = useCallback((checked) => {
+        if (checked) {
+            updateSelection(new Set(items.map((item) => getRowId(item))));
+        }
+        else {
+            updateSelection(new Set());
+        }
+    }, [items, getRowId, updateSelection]);
+    const allSelected = useMemo(() => items.length > 0 && items.every((item) => selectedRowIds.has(getRowId(item))), [items, selectedRowIds, getRowId]);
+    const someSelected = useMemo(() => !allSelected && items.some((item) => selectedRowIds.has(getRowId(item))), [allSelected, items, selectedRowIds, getRowId]);
+    return {
+        selectedRowIds,
+        updateSelection,
+        handleRowCheckboxChange,
+        handleSelectAll,
+        allSelected,
+        someSelected,
+    };
+}