@xcelsior/ui-spreadsheets 1.0.1

package/src/components/Spreadsheet.tsx

@@ -0,0 +1,1005 @@
+import type React from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+    HiAnnotation,
+    HiChatAlt2,
+    HiChevronDown,
+    HiChevronRight,
+    HiColorSwatch,
+    HiDuplicate,
+} from 'react-icons/hi';
+import { cn } from '../utils';
+import { SpreadsheetCell } from './SpreadsheetCell';
+import { SpreadsheetFilterDropdown } from './SpreadsheetFilterDropdown';
+import { SpreadsheetToolbar } from './SpreadsheetToolbar';
+import { SpreadsheetHeader } from './SpreadsheetHeader';
+import { RowIndexColumnHeader } from './RowIndexColumnHeader';
+import { ColorPickerPopover } from './ColorPickerPopover';
+import { type SpreadsheetSettings, SpreadsheetSettingsModal } from './SpreadsheetSettingsModal';
+import { AddCommentModal, ViewCommentsModal } from './CommentModals';
+import { KeyboardShortcutsModal } from './KeyboardShortcutsModal';
+import { Pagination } from '@xcelsior/design-system';
+import { useSpreadsheetFiltering } from '../hooks/useSpreadsheetFiltering';
+import {
+    useSpreadsheetHighlighting,
+    ROW_INDEX_COLUMN_ID,
+} from '../hooks/useSpreadsheetHighlighting';
+import { useSpreadsheetPinning, ROW_INDEX_COLUMN_WIDTH } from '../hooks/useSpreadsheetPinning';
+import { useSpreadsheetComments } from '../hooks/useSpreadsheetComments';
+import { useSpreadsheetUndoRedo } from '../hooks/useSpreadsheetUndoRedo';
+import { useSpreadsheetKeyboardShortcuts } from '../hooks/useSpreadsheetKeyboardShortcuts';
+import type { CellPosition, SpreadsheetProps } from '../types';
+
+type SpreadsheetUndoEntry = {
+    type: 'cell-edit';
+    rowId: string | number;
+    columnId: string;
+    previousValue: any;
+    nextValue: any;
+};
+
+/**
+ * Spreadsheet component - A feature-rich data grid with Excel-like functionality.
+ *
+ * Features:
+ * - Sortable columns
+ * - Filterable columns (text search, multi-select, range)
+ * - Inline cell editing
+ * - Row selection (single, multi, range)
+ * - Column pinning
+ * - Column grouping with collapse
+ * - Pagination
+ * - Zoom controls
+ * - Undo/Redo
+ * - Cell highlighting
+ * - Keyboard navigation
+ *
+ * @example
+ * ```tsx
+ * const columns = [
+ *   { id: 'name', label: 'Name', sortable: true, filterable: true },
+ *   { id: 'email', label: 'Email', editable: true },
+ *   { id: 'status', label: 'Status', type: 'select', options: ['Active', 'Inactive'] },
+ * ];
+ *
+ * <Spreadsheet
+ *   data={users}
+ *   columns={columns}
+ *   getRowId={(row) => row.id}
+ *   onCellEdit={(rowId, columnId, value) => handleEdit(rowId, columnId, value)}
+ *   showToolbar
+ *   showPagination
+ *   enableRowSelection
+ * />
+ * ```
+ */
+export function Spreadsheet<T extends Record<string, any>>({
+    data,
+    columns,
+    columnGroups,
+    getRowId,
+    onCellEdit,
+    onSelectionChange,
+    onSortChange,
+    onFilterChange,
+    onRowClick,
+    onRowDoubleClick,
+    onRowClone,
+    onAddRowComment,
+    onRowHighlight,
+    showToolbar = true,
+    showPagination = true,
+    showRowIndex = true,
+    enableRowSelection = true,
+    enableCellEditing = true,
+    enableComments = true,
+    enableHighlighting = true,
+    enableUndoRedo = true,
+    defaultPageSize = 25,
+    pageSizeOptions = [25, 50, 100, 200],
+    defaultZoom = 100,
+    autoSave = true,
+    compactMode = false,
+    isLoading = false,
+    className,
+    emptyMessage = 'No data available',
+    rowHighlights: externalRowHighlights,
+    rowComments: externalRowComments,
+    rowActions,
+    // Server-side mode props
+    serverSide = false,
+    totalItems,
+    currentPage: controlledCurrentPage,
+    pageSize: controlledPageSize,
+    onPageChange,
+    sortConfig: controlledSortConfig,
+    filters: controlledFilters,
+}: SpreadsheetProps<T>) {
+    // ==================== HOOKS ====================
+
+    // Filtering and sorting hook
+    const {
+        filters,
+        sortConfig,
+        filteredData,
+        activeFilterColumn,
+        setActiveFilterColumn,
+        handleFilterChange,
+        handleSort,
+        clearAllFilters,
+        hasActiveFilters,
+    } = useSpreadsheetFiltering({
+        data,
+        columns,
+        onFilterChange,
+        onSortChange,
+        serverSide,
+        controlledFilters,
+        controlledSortConfig,
+    });
+
+    // Highlighting hook
+    const {
+        getCellHighlight,
+        handleCellHighlightToggle,
+        getRowHighlight,
+        handleRowHighlightToggle,
+        getColumnHighlight,
+        handleColumnHighlightToggle,
+        highlightPickerRow,
+        setHighlightPickerRow,
+        highlightPickerColumn,
+        setHighlightPickerColumn,
+    } = useSpreadsheetHighlighting({
+        externalRowHighlights,
+        onRowHighlight,
+    });
+
+    // Pinning hook
+    const {
+        pinnedColumns,
+        isRowIndexPinned,
+        collapsedGroups,
+        visibleColumns,
+        handleTogglePin,
+        handleToggleRowIndexPin,
+        handleToggleGroupCollapse,
+        getColumnLeftOffset,
+        isColumnPinned,
+        getColumnPinSide,
+    } = useSpreadsheetPinning({
+        columns,
+        columnGroups,
+        showRowIndex,
+    });
+
+    // Comments hook
+    const {
+        getRowComments,
+        getUnresolvedCommentCount,
+        hasComments,
+        commentModalRow,
+        setCommentModalRow,
+        commentText,
+        setCommentText,
+        viewCommentsRow,
+        setViewCommentsRow,
+        handleAddRowComment,
+        handleToggleCommentResolved,
+    } = useSpreadsheetComments({
+        externalRowComments,
+        onAddRowComment,
+    });
+
+    // Undo/Redo hook
+    const {
+        canUndo,
+        canRedo,
+        undoCount,
+        redoCount,
+        hasUnsavedChanges,
+        saveStatus,
+        handleUndo: popUndoEntry,
+        handleRedo: popRedoEntry,
+        handleSave,
+        pushToUndoStack,
+        markAsChanged,
+    } = useSpreadsheetUndoRedo<SpreadsheetUndoEntry>({
+        enabled: enableUndoRedo,
+        autoSave,
+    });
+
+    // ==================== LOCAL STATE ====================
+
+    // Selection state
+    const [selectedRows, setSelectedRows] = useState<Set<string | number>>(new Set());
+    const [lastSelectedRow, setLastSelectedRow] = useState<string | number | null>(null);
+    const [focusedCell, setFocusedCell] = useState<CellPosition | null>(null);
+    const [editingCell, setEditingCell] = useState<CellPosition | null>(null);
+    const [editValue, setEditValue] = useState<any>('');
+    const [hoveredRow, setHoveredRow] = useState<string | number | null>(null);
+
+    // Pagination state (supports both controlled and uncontrolled modes)
+    const [internalCurrentPage, setInternalCurrentPage] = useState(1);
+    const [internalPageSize, setInternalPageSize] = useState(defaultPageSize);
+    const [zoom, setZoom] = useState(defaultZoom);
+
+    // Use controlled state if provided, otherwise use internal state
+    const currentPage = controlledCurrentPage ?? internalCurrentPage;
+    const pageSize = controlledPageSize ?? internalPageSize;
+
+    // Helper to update pagination state
+    const handlePageChange = useCallback(
+        (newPage: number) => {
+            if (controlledCurrentPage === undefined) {
+                setInternalCurrentPage(newPage);
+            }
+            onPageChange?.(newPage, pageSize);
+        },
+        [controlledCurrentPage, onPageChange, pageSize]
+    );
+
+    const handlePageSizeChange = useCallback(
+        (newPageSize: number) => {
+            if (controlledPageSize === undefined) {
+                setInternalPageSize(newPageSize);
+            }
+            if (controlledCurrentPage === undefined) {
+                setInternalCurrentPage(1);
+            }
+            onPageChange?.(1, newPageSize);
+        },
+        [controlledPageSize, controlledCurrentPage, onPageChange]
+    );
+
+    // Modal state
+    const [showSettingsModal, setShowSettingsModal] = useState(false);
+
+    // Settings state
+    const [spreadsheetSettings, setSpreadsheetSettings] = useState<SpreadsheetSettings>({
+        defaultPinnedColumns: [],
+        defaultSort: null,
+        defaultPageSize,
+        defaultZoom,
+        autoSave,
+        compactView: compactMode,
+        showRowIndex: showRowIndex,
+        pinRowIndex: false,
+        rowIndexHighlightColor: undefined,
+    });
+
+    // Keyboard shortcuts hook (needs to be declared before escape handler can reference its modal states)
+    const handleEscapeCallback = useCallback(() => {
+        if (commentModalRow !== null) {
+            setCommentModalRow(null);
+        } else if (viewCommentsRow !== null) {
+            setViewCommentsRow(null);
+        } else if (highlightPickerRow !== null) {
+            setHighlightPickerRow(null);
+        } else if (highlightPickerColumn !== null) {
+            setHighlightPickerColumn(null);
+        } else {
+            setSelectedRows(new Set());
+            setLastSelectedRow(null);
+            setFocusedCell(null);
+            setEditingCell(null);
+        }
+    }, [
+        commentModalRow,
+        setCommentModalRow,
+        viewCommentsRow,
+        setViewCommentsRow,
+        highlightPickerRow,
+        setHighlightPickerRow,
+        highlightPickerColumn,
+        setHighlightPickerColumn,
+    ]);
+
+    const applyUndo = useCallback(() => {
+        const entry = popUndoEntry();
+        if (!entry || !onCellEdit) return;
+
+        if (entry.type === 'cell-edit') {
+            onCellEdit(entry.rowId, entry.columnId, entry.previousValue);
+            markAsChanged();
+        }
+    }, [popUndoEntry, onCellEdit, markAsChanged]);
+
+    const applyRedo = useCallback(() => {
+        const entry = popRedoEntry();
+        if (!entry || !onCellEdit) return;
+
+        if (entry.type === 'cell-edit') {
+            onCellEdit(entry.rowId, entry.columnId, entry.nextValue);
+            markAsChanged();
+        }
+    }, [popRedoEntry, onCellEdit, markAsChanged]);
+
+    const { showKeyboardShortcuts, setShowKeyboardShortcuts, shortcuts } =
+        useSpreadsheetKeyboardShortcuts({
+            onUndo: applyUndo,
+            onRedo: applyRedo,
+            onEscape: handleEscapeCallback,
+            enabled: true,
+        });
+
+    // ==================== COMPUTED VALUES ====================
+
+    const effectiveShowRowIndex = spreadsheetSettings.showRowIndex !== false;
+    const rowIndexHighlightColor = getColumnHighlight(ROW_INDEX_COLUMN_ID);
+
+    // Refs
+    const tableRef = useRef<HTMLDivElement>(null);
+
+    // Calculate total items for pagination
+    // In server-side mode, use totalItems prop; otherwise use filteredData length
+    const effectiveTotalItems = serverSide ? (totalItems ?? data.length) : filteredData.length;
+
+    // Paginate data (skip pagination in server-side mode - data is already paginated)
+    const paginatedData = useMemo(() => {
+        if (serverSide) {
+            // In server-side mode, data is already paginated by the server
+            return filteredData;
+        }
+        const startIndex = (currentPage - 1) * pageSize;
+        return filteredData.slice(startIndex, startIndex + pageSize);
+    }, [filteredData, currentPage, pageSize, serverSide]);
+
+    const totalPages = Math.max(1, Math.ceil(effectiveTotalItems / pageSize));
+
+    // Reset page when filters change (only in client-side mode)
+    useEffect(() => {
+        if (!serverSide && currentPage > totalPages) {
+            setInternalCurrentPage(1);
+        }
+    }, [totalPages, currentPage, serverSide]);
+
+    // ==================== EVENT HANDLERS ====================
+
+    const handleRowSelect = useCallback(
+        (rowId: string | number, event: React.MouseEvent) => {
+            if (!enableRowSelection) return;
+
+            event.stopPropagation();
+
+            if (event.shiftKey && lastSelectedRow !== null) {
+                // Range selection
+                const currentIndex = filteredData.findIndex((r) => getRowId(r) === rowId);
+                const lastIndex = filteredData.findIndex((r) => getRowId(r) === lastSelectedRow);
+                if (currentIndex !== -1 && lastIndex !== -1) {
+                    const start = Math.min(currentIndex, lastIndex);
+                    const end = Math.max(currentIndex, lastIndex);
+                    const newSelection = new Set(selectedRows);
+                    for (let i = start; i <= end; i++) {
+                        newSelection.add(getRowId(filteredData[i]));
+                    }
+                    setSelectedRows(newSelection);
+                    onSelectionChange?.(Array.from(newSelection));
+                }
+            } else if (event.metaKey || event.ctrlKey) {
+                // Toggle individual selection
+                const newSelection = new Set(selectedRows);
+                if (newSelection.has(rowId)) {
+                    newSelection.delete(rowId);
+                } else {
+                    newSelection.add(rowId);
+                }
+                setSelectedRows(newSelection);
+                setLastSelectedRow(rowId);
+                onSelectionChange?.(Array.from(newSelection));
+            } else {
+                // Single selection
+                if (selectedRows.has(rowId) && selectedRows.size === 1) {
+                    setSelectedRows(new Set());
+                    setLastSelectedRow(null);
+                    onSelectionChange?.([]);
+                } else {
+                    setSelectedRows(new Set([rowId]));
+                    setLastSelectedRow(rowId);
+                    onSelectionChange?.([rowId]);
+                }
+            }
+        },
+        [
+            enableRowSelection,
+            lastSelectedRow,
+            filteredData,
+            selectedRows,
+            getRowId,
+            onSelectionChange,
+        ]
+    );
+
+    const handleCellClick = useCallback(
+        (rowId: string | number, columnId: string, event: React.MouseEvent) => {
+            event.stopPropagation();
+            setFocusedCell({ rowId, columnId });
+
+            const column = (columns || []).find((c) => c.id === columnId);
+            if (column?.editable && enableCellEditing) {
+                const row = (data || []).find((r) => getRowId(r) === rowId);
+                if (row) {
+                    const value = column.getValue ? column.getValue(row) : row[columnId];
+                    setEditingCell({ rowId, columnId });
+                    setEditValue(value);
+                }
+            }
+        },
+        [columns, data, getRowId, enableCellEditing]
+    );
+
+    const handleCellChange = useCallback(
+        (rowId: string | number, columnId: string, newValue: any) => {
+            const row = data.find((r) => getRowId(r) === rowId);
+            const previousValue = row ? (row as Record<string, any>)[columnId] : undefined;
+
+            if (row && Object.is(previousValue, newValue)) {
+                return;
+            }
+
+            if (row && enableUndoRedo) {
+                pushToUndoStack({
+                    type: 'cell-edit',
+                    rowId,
+                    columnId,
+                    previousValue,
+                    nextValue: newValue,
+                });
+            }
+
+            onCellEdit?.(rowId, columnId, newValue);
+            markAsChanged();
+        },
+        [data, getRowId, enableUndoRedo, onCellEdit, pushToUndoStack, markAsChanged]
+    );
+
+    const handleConfirmEdit = useCallback(() => {
+        if (editingCell) {
+            handleCellChange(editingCell.rowId, editingCell.columnId, editValue);
+            setEditingCell(null);
+        }
+    }, [editingCell, editValue, handleCellChange]);
+
+    const handleCancelEdit = useCallback(() => {
+        setEditingCell(null);
+        setEditValue('');
+    }, []);
+
+    // Handle row clone/duplicate
+    const handleRowClone = useCallback(
+        (row: T, rowId: string | number) => {
+            onRowClone?.(row, rowId);
+        },
+        [onRowClone]
+    );
+
+    // Handle row index highlight (using unified column highlight with special ID)
+    const handleRowIndexHighlightClick = useCallback(() => {
+        setHighlightPickerColumn(ROW_INDEX_COLUMN_ID);
+    }, [setHighlightPickerColumn]);
+
+    // ==================== RENDER ====================
+
+    return (
+        <div className={cn('flex flex-col h-full bg-white', className)}>
+            {/* Toolbar */}
+            {showToolbar && (
+                <SpreadsheetToolbar
+                    zoom={zoom}
+                    canUndo={canUndo}
+                    canRedo={canRedo}
+                    undoCount={undoCount}
+                    redoCount={redoCount}
+                    selectedRowCount={selectedRows.size}
+                    hasUnsavedChanges={hasUnsavedChanges}
+                    saveStatus={saveStatus}
+                    autoSave={autoSave}
+                    hasActiveFilters={hasActiveFilters}
+                    onClearFilters={clearAllFilters}
+                    onZoomIn={() => setZoom((z) => Math.min(z + 10, 200))}
+                    onZoomOut={() => setZoom((z) => Math.max(z - 10, 50))}
+                    onZoomReset={() => setZoom(100)}
+                    onUndo={applyUndo}
+                    onRedo={applyRedo}
+                    onClearSelection={() => {
+                        setSelectedRows(new Set());
+                        setLastSelectedRow(null);
+                        onSelectionChange?.([]);
+                    }}
+                    onSave={handleSave}
+                    onSettings={() => setShowSettingsModal(true)}
+                    onShowShortcuts={() => setShowKeyboardShortcuts(true)}
+                    onExport={() => console.log('Export clicked')}
+                />
+            )}
+
+            {/* Table Container */}
+            <div ref={tableRef} className="flex-1 overflow-auto border border-gray-200 rounded">
+                <div
+                    style={{
+                        transform: `scale(${zoom / 100})`,
+                        transformOrigin: 'top left',
+                        width: `${100 / (zoom / 100)}%`,
+                    }}
+                >
+                    <table className="w-full border-separate border-spacing-0 text-xs">
+                        <thead>
+                            {/* Column Group Headers */}
+                            {columnGroups && (
+                                <tr>
+                                    {/* Row index column header (rowSpan=2 for groups) */}
+                                    {effectiveShowRowIndex && (
+                                        <RowIndexColumnHeader
+                                            enableHighlighting={enableHighlighting}
+                                            highlightColor={rowIndexHighlightColor}
+                                            isPinned={isRowIndexPinned}
+                                            onHighlightClick={handleRowIndexHighlightClick}
+                                            onPinClick={handleToggleRowIndexPin}
+                                            hasColumnGroups={true}
+                                        />
+                                    )}
+                                    {columnGroups.map((group) => {
+                                        const groupColumns = (columns || []).filter((c) =>
+                                            group.columns.includes(c.id)
+                                        );
+                                        const isCollapsed = collapsedGroups.has(group.id);
+                                        const visibleGroupColumns = isCollapsed
+                                            ? groupColumns.filter((c) => pinnedColumns.has(c.id))
+                                            : groupColumns;
+                                        const colSpan = Math.max(
+                                            1,
+                                            visibleGroupColumns.length + (isCollapsed ? 1 : 0)
+                                        );
+
+                                        return (
+                                            <th
+                                                key={group.id}
+                                                colSpan={colSpan}
+                                                className={cn(
+                                                    'border border-gray-200 px-2 py-1.5 text-center font-bold text-gray-700',
+                                                    group.collapsible &&
+                                                        'cursor-pointer hover:bg-gray-100'
+                                                )}
+                                                style={{
+                                                    backgroundColor:
+                                                        group.headerColor || 'rgb(243 244 246)',
+                                                }}
+                                                onClick={() =>
+                                                    group.collapsible &&
+                                                    handleToggleGroupCollapse(group.id)
+                                                }
+                                            >
+                                                <div className="flex items-center justify-center gap-1">
+                                                    {group.collapsible &&
+                                                        (isCollapsed ? (
+                                                            <HiChevronRight className="h-3 w-3" />
+                                                        ) : (
+                                                            <HiChevronDown className="h-3 w-3" />
+                                                        ))}
+                                                    <span>{group.label}</span>
+                                                </div>
+                                            </th>
+                                        );
+                                    })}
+                                </tr>
+                            )}
+
+                            {/* Column Headers */}
+                            <tr>
+                                {/* Row index column header (when no groups) */}
+                                {effectiveShowRowIndex && !columnGroups && (
+                                    <RowIndexColumnHeader
+                                        enableHighlighting={enableHighlighting}
+                                        highlightColor={rowIndexHighlightColor}
+                                        isPinned={isRowIndexPinned}
+                                        onHighlightClick={handleRowIndexHighlightClick}
+                                        onPinClick={handleToggleRowIndexPin}
+                                        hasColumnGroups={false}
+                                    />
+                                )}
+                                {visibleColumns.map((column) => {
+                                    const isPinnedLeft =
+                                        isColumnPinned(column.id) &&
+                                        getColumnPinSide(column.id) === 'left';
+                                    return (
+                                        <SpreadsheetHeader
+                                            key={column.id}
+                                            column={column}
+                                            sortConfig={sortConfig}
+                                            hasActiveFilter={!!filters[column.id]}
+                                            isPinned={isColumnPinned(column.id)}
+                                            pinSide={getColumnPinSide(column.id)}
+                                            leftOffset={
+                                                isPinnedLeft ? getColumnLeftOffset(column.id) : 0
+                                            }
+                                            highlightColor={getColumnHighlight(column.id)}
+                                            compactMode={compactMode}
+                                            onClick={() => handleSort(column.id)}
+                                            onFilterClick={() =>
+                                                setActiveFilterColumn(
+                                                    activeFilterColumn === column.id
+                                                        ? null
+                                                        : column.id
+                                                )
+                                            }
+                                            onPinClick={() => handleTogglePin(column.id)}
+                                            onHighlightClick={
+                                                enableHighlighting
+                                                    ? () => setHighlightPickerColumn(column.id)
+                                                    : undefined
+                                            }
+                                        >
+                                            {/* Filter dropdown */}
+                                            {activeFilterColumn === column.id && (
+                                                <SpreadsheetFilterDropdown
+                                                    column={column}
+                                                    filter={filters[column.id]}
+                                                    onFilterChange={(filter) =>
+                                                        handleFilterChange(column.id, filter)
+                                                    }
+                                                    onClose={() => setActiveFilterColumn(null)}
+                                                />
+                                            )}
+                                        </SpreadsheetHeader>
+                                    );
+                                })}
+                            </tr>
+                        </thead>
+
+                        <tbody>
+                            {isLoading ? (
+                                <tr>
+                                    <td
+                                        colSpan={
+                                            visibleColumns.length + (effectiveShowRowIndex ? 1 : 0)
+                                        }
+                                        className="text-center py-8 text-gray-500"
+                                    >
+                                        <div className="flex items-center justify-center gap-2">
+                                            <div className="w-4 h-4 border-2 border-blue-600 border-t-transparent rounded-full animate-spin" />
+                                            Loading...
+                                        </div>
+                                    </td>
+                                </tr>
+                            ) : paginatedData.length === 0 ? (
+                                <tr>
+                                    <td
+                                        colSpan={
+                                            visibleColumns.length + (effectiveShowRowIndex ? 1 : 0)
+                                        }
+                                        className="text-center py-8 text-gray-500"
+                                    >
+                                        {emptyMessage}
+                                    </td>
+                                </tr>
+                            ) : (
+                                paginatedData.map((row, rowIndex) => {
+                                    const rowId = getRowId(row);
+                                    const isRowSelected = selectedRows.has(rowId);
+                                    const isRowHovered = hoveredRow === rowId;
+                                    const rowHighlight = getRowHighlight(rowId);
+                                    const rowCommentsList = getRowComments(rowId);
+                                    const hasRowComments = hasComments(rowId);
+                                    const unresolvedCount = getUnresolvedCommentCount(rowId);
+                                    const displayIndex =
+                                        rowIndex + 1 + (currentPage - 1) * pageSize;
+
+                                    return (
+                                        <tr
+                                            key={rowId}
+                                            onMouseEnter={() => setHoveredRow(rowId)}
+                                            onMouseLeave={() => setHoveredRow(null)}
+                                            onClick={() => {
+                                                onRowClick?.(row, rowIndex);
+                                            }}
+                                            onDoubleClick={() => onRowDoubleClick?.(row, rowIndex)}
+                                            className="transition-colors"
+                                        >
+                                            {/* Row Index Column */}
+                                            {effectiveShowRowIndex && (
+                                                <td
+                                                    onClick={(e) => handleRowSelect(rowId, e)}
+                                                    className={cn(
+                                                        'border border-gray-200 text-center font-semibold cursor-pointer group relative',
+                                                        isRowIndexPinned ? 'z-20' : 'z-0',
+                                                        isRowSelected && 'bg-blue-100',
+                                                        !isRowSelected && rowHighlight && '',
+                                                        isRowHovered &&
+                                                            !isRowSelected &&
+                                                            !rowHighlight &&
+                                                            'bg-gray-50'
+                                                    )}
+                                                    style={{
+                                                        backgroundColor:
+                                                            rowHighlight?.color ||
+                                                            (isRowSelected
+                                                                ? '#dbeafe'
+                                                                : isRowHovered
+                                                                  ? '#f9fafb'
+                                                                  : rowIndexHighlightColor ||
+                                                                    'white'),
+                                                        minWidth: `${ROW_INDEX_COLUMN_WIDTH}px`,
+                                                        width: `${ROW_INDEX_COLUMN_WIDTH}px`,
+                                                        ...(isRowIndexPinned && {
+                                                            position: 'sticky' as const,
+                                                            left: 0,
+                                                        }),
+                                                    }}
+                                                >
+                                                    {/* Row number */}
+                                                    <div className="py-1 px-1">{displayIndex}</div>
+
+                                                    {/* Row comments indicator */}
+                                                    {hasRowComments && (
+                                                        <button
+                                                            type="button"
+                                                            onClick={(e) => {
+                                                                e.stopPropagation();
+                                                                setViewCommentsRow(rowId);
+                                                            }}
+                                                            className="absolute top-0 right-0 p-0.5 hover:bg-gray-200/80 rounded-bl"
+                                                            title={`${rowCommentsList.length} row comment(s) - ${unresolvedCount} unresolved`}
+                                                        >
+                                                            <HiChatAlt2
+                                                                className={cn(
+                                                                    'h-2.5 w-2.5',
+                                                                    unresolvedCount > 0
+                                                                        ? 'text-amber-500'
+                                                                        : 'text-gray-400'
+                                                                )}
+                                                            />
+                                                            {unresolvedCount > 0 && (
+                                                                <span className="absolute -top-0.5 -right-0.5 bg-amber-500 text-white text-[6px] rounded-full w-2 h-2 flex items-center justify-center">
+                                                                    {unresolvedCount}
+                                                                </span>
+                                                            )}
+                                                        </button>
+                                                    )}
+
+                                                    {/* Row Actions (visible on hover) */}
+                                                    <div className="absolute inset-x-0 bottom-0 opacity-0 group-hover:opacity-100 flex items-center justify-center gap-0.5 transition-opacity bg-white/90 py-0.5 border-t border-gray-100">
+                                                        {/* Clone/Duplicate Row */}
+                                                        {onRowClone && (
+                                                            <button
+                                                                type="button"
+                                                                onClick={(e) => {
+                                                                    e.stopPropagation();
+                                                                    handleRowClone(row, rowId);
+                                                                }}
+                                                                className="p-0.5 hover:bg-gray-200 rounded"
+                                                                title="Duplicate row"
+                                                            >
+                                                                <HiDuplicate className="h-2.5 w-2.5 text-gray-500" />
+                                                            </button>
+                                                        )}
+
+                                                        {/* Highlight Row */}
+                                                        {enableHighlighting && (
+                                                            <button
+                                                                type="button"
+                                                                onClick={(e) => {
+                                                                    e.stopPropagation();
+                                                                    setHighlightPickerRow(rowId);
+                                                                }}
+                                                                className="p-0.5 hover:bg-gray-200 rounded"
+                                                                title="Highlight row"
+                                                            >
+                                                                <HiColorSwatch
+                                                                    className={cn(
+                                                                        'h-2.5 w-2.5',
+                                                                        rowHighlight
+                                                                            ? 'text-amber-500'
+                                                                            : 'text-gray-500'
+                                                                    )}
+                                                                />
+                                                            </button>
+                                                        )}
+
+                                                        {/* Add Row Comment */}
+                                                        {enableComments && (
+                                                            <button
+                                                                type="button"
+                                                                onClick={(e) => {
+                                                                    e.stopPropagation();
+                                                                    setCommentModalRow(rowId);
+                                                                }}
+                                                                className="p-0.5 hover:bg-gray-200 rounded"
+                                                                title="Add row comment"
+                                                            >
+                                                                <HiAnnotation className="h-2.5 w-2.5 text-gray-500" />
+                                                            </button>
+                                                        )}
+
+                                                        {/* Custom Row Actions */}
+                                                        {rowActions?.map((action) => {
+                                                            if (
+                                                                action.visible &&
+                                                                !action.visible(row)
+                                                            )
+                                                                return null;
+                                                            return (
+                                                                <button
+                                                                    key={action.id}
+                                                                    type="button"
+                                                                    onClick={(e) => {
+                                                                        e.stopPropagation();
+                                                                        action.onClick(row, rowId);
+                                                                    }}
+                                                                    className={cn(
+                                                                        'p-0.5 hover:bg-gray-200 rounded',
+                                                                        action.className
+                                                                    )}
+                                                                    title={action.tooltip}
+                                                                >
+                                                                    {action.icon}
+                                                                </button>
+                                                            );
+                                                        })}
+                                                    </div>
+                                                </td>
+                                            )}
+
+                                            {/* Data Cells */}
+                                            {visibleColumns.map((column) => {
+                                                const value = column.getValue
+                                                    ? column.getValue(row)
+                                                    : row[column.id];
+                                                const isEditing =
+                                                    editingCell?.rowId === rowId &&
+                                                    editingCell?.columnId === column.id;
+                                                const isFocused =
+                                                    focusedCell?.rowId === rowId &&
+                                                    focusedCell?.columnId === column.id;
+                                                // Priority: cell highlight > row highlight > column highlight
+                                                const cellOrRowOrColumnHighlight =
+                                                    getCellHighlight(rowId, column.id) ||
+                                                    rowHighlight?.color ||
+                                                    getColumnHighlight(column.id);
+                                                const isColPinned = isColumnPinned(column.id);
+                                                const colPinSide = getColumnPinSide(column.id);
+
+                                                return (
+                                                    <SpreadsheetCell
+                                                        key={column.id}
+                                                        value={isEditing ? editValue : value}
+                                                        column={column}
+                                                        row={row}
+                                                        rowIndex={rowIndex}
+                                                        rowId={rowId}
+                                                        isEditable={
+                                                            column.editable && enableCellEditing
+                                                        }
+                                                        isEditing={isEditing}
+                                                        isFocused={isFocused}
+                                                        isRowSelected={isRowSelected}
+                                                        isRowHovered={isRowHovered}
+                                                        highlightColor={cellOrRowOrColumnHighlight}
+                                                        compactMode={compactMode}
+                                                        hasSelectedRows={selectedRows.size > 1}
+                                                        isPinned={isColPinned}
+                                                        pinSide={colPinSide}
+                                                        leftOffset={getColumnLeftOffset(column.id)}
+                                                        onClick={(e) =>
+                                                            handleCellClick(rowId, column.id, e)
+                                                        }
+                                                        onChange={(newValue) =>
+                                                            setEditValue(newValue)
+                                                        }
+                                                        onConfirm={handleConfirmEdit}
+                                                        onCancel={handleCancelEdit}
+                                                        onHighlight={
+                                                            enableHighlighting
+                                                                ? () => {
+                                                                      handleCellHighlightToggle(
+                                                                          rowId,
+                                                                          column.id
+                                                                      );
+                                                                  }
+                                                                : undefined
+                                                        }
+                                                    />
+                                                );
+                                            })}
+                                        </tr>
+                                    );
+                                })
+                            )}
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+
+            {/* Pagination */}
+            {showPagination && effectiveTotalItems > 0 && (
+                <Pagination
+                    currentPage={currentPage}
+                    totalPages={totalPages}
+                    pageSize={pageSize}
+                    totalItems={effectiveTotalItems}
+                    startItem={(currentPage - 1) * pageSize + 1}
+                    endItem={Math.min(currentPage * pageSize, effectiveTotalItems)}
+                    pageSizeOptions={pageSizeOptions}
+                    itemLabel="rows"
+                    onPageChange={handlePageChange}
+                    onPageSizeChange={handlePageSizeChange}
+                />
+            )}
+
+            {/* Add Row Comment Modal */}
+            <AddCommentModal
+                isOpen={commentModalRow !== null}
+                commentText={commentText}
+                onCommentTextChange={setCommentText}
+                onAdd={() => commentModalRow !== null && handleAddRowComment(commentModalRow)}
+                onClose={() => {
+                    setCommentText('');
+                    setCommentModalRow(null);
+                }}
+            />
+
+            {/* View Row Comments Modal */}
+            <ViewCommentsModal
+                isOpen={viewCommentsRow !== null}
+                comments={viewCommentsRow !== null ? getRowComments(viewCommentsRow) : []}
+                onToggleResolved={handleToggleCommentResolved}
+                onClose={() => setViewCommentsRow(null)}
+            />
+
+            {/* Row Highlight Color Picker */}
+            {highlightPickerRow !== null && (
+                <ColorPickerPopover
+                    title="Highlight Row"
+                    paletteType="row"
+                    onSelectColor={(color) => handleRowHighlightToggle(highlightPickerRow, color)}
+                    onClose={() => setHighlightPickerRow(null)}
+                />
+            )}
+
+            {/* Column Highlight Color Picker (unified - works for regular columns and row index) */}
+            {highlightPickerColumn !== null && (
+                <ColorPickerPopover
+                    title={
+                        highlightPickerColumn === ROW_INDEX_COLUMN_ID
+                            ? 'Highlight Row Index Column'
+                            : `Highlight Column: ${columns.find((c) => c.id === highlightPickerColumn)?.label || ''}`
+                    }
+                    paletteType="column"
+                    onSelectColor={(color) =>
+                        handleColumnHighlightToggle(highlightPickerColumn, color)
+                    }
+                    onClose={() => setHighlightPickerColumn(null)}
+                />
+            )}
+
+            {/* Keyboard Shortcuts Modal */}
+            <KeyboardShortcutsModal
+                isOpen={showKeyboardShortcuts}
+                onClose={() => setShowKeyboardShortcuts(false)}
+                shortcuts={shortcuts}
+            />
+
+            {/* Settings Modal */}
+            <SpreadsheetSettingsModal
+                isOpen={showSettingsModal}
+                onClose={() => setShowSettingsModal(false)}
+                settings={spreadsheetSettings}
+                onSave={(newSettings) => {
+                    setSpreadsheetSettings(newSettings);
+                    setZoom(newSettings.defaultZoom);
+                    // Update page size through the proper handler
+                    if (newSettings.defaultPageSize !== pageSize) {
+                        handlePageSizeChange(newSettings.defaultPageSize);
+                    }
+                    if (newSettings.defaultSort) {
+                        // Note: sortConfig is managed by the filtering hook
+                    }
+                }}
+                columns={columns || []}
+                title="Spreadsheet Settings"
+                pageSizeOptions={pageSizeOptions}
+            />
+        </div>
+    );
+}
+
+Spreadsheet.displayName = 'Spreadsheet';