@xcelsior/ui-spreadsheets 1.2.1 → 1.3.0

package/src/hooks/useSpreadsheetPinning.ts

@@ -1,10 +1,10 @@
-import { useCallback, useMemo, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { SpreadsheetColumn, SpreadsheetColumnGroup } from '../types';
 
 // Special column ID for row index
 export const ROW_INDEX_COLUMN_ID = '__row_index__';
-export const ROW_INDEX_COLUMN_WIDTH = 80;
-// Minimum width for any pinned column to ensure header actions (pin, filter, highlight icons) fit
+export const ROW_INDEX_COLUMN_WIDTH = 90;
+// Kept for backward compatibility but no longer enforced on cells
 export const MIN_PINNED_COLUMN_WIDTH = 150;
 
 export interface UseSpreadsheetPinningOptions<T> {
@@ -13,31 +13,24 @@ export interface UseSpreadsheetPinningOptions<T> {
     showRowIndex?: boolean;
     defaultPinnedColumns?: string[];
     defaultPinnedRightColumns?: string[];
+    /** Function to get the current (possibly resized) width for a column */
+    getColumnWidth?: (columnId: string, defaultWidth?: number) => number | undefined;
 }
 
 export interface UseSpreadsheetPinningReturn<T> {
-    // Pinned state
     pinnedColumns: Map<string, 'left' | 'right'>;
     isRowIndexPinned: boolean;
-
-    // Collapsed groups
     collapsedGroups: Set<string>;
-
-    // Visible columns (filtered by groups and reordered by pinning)
     visibleColumns: SpreadsheetColumn<T>[];
-
-    // Actions
     handleTogglePin: (columnId: string) => void;
     handleToggleGroupCollapse: (groupId: string) => void;
     setPinnedColumnsFromIds: (columnIds: string[]) => void;
-
-    // Offset calculations
     getColumnLeftOffset: (columnId: string) => number;
     getColumnRightOffset: (columnId: string) => number;
-
-    // Utility
     isColumnPinned: (columnId: string) => boolean;
     getColumnPinSide: (columnId: string) => 'left' | 'right' | undefined;
+    getPinnedZIndex: (columnId: string) => number;
+    measureRef: (el: HTMLElement | null) => void;
 }
 
 export function useSpreadsheetPinning<T>({
@@ -46,47 +39,94 @@ export function useSpreadsheetPinning<T>({
     showRowIndex = true,
     defaultPinnedColumns = [],
     defaultPinnedRightColumns = [],
+    getColumnWidth,
 }: UseSpreadsheetPinningOptions<T>): UseSpreadsheetPinningReturn<T> {
-    // Initialize pinned columns from defaults (including row index)
     const [pinnedColumns, setPinnedColumns] = useState<Map<string, 'left' | 'right'>>(() => {
         const map = new Map<string, 'left' | 'right'>();
+        if (showRowIndex) {
+            map.set(ROW_INDEX_COLUMN_ID, 'left');
+        }
+        const midpoint = Math.floor(columns.length / 2);
         defaultPinnedColumns.forEach((col) => {
-            map.set(col, 'left');
-        });
-        defaultPinnedRightColumns.forEach((col) => {
-            map.set(col, 'right');
+            if (col === ROW_INDEX_COLUMN_ID) return;
+            const colIndex = columns.findIndex((c) => c.id === col);
+            map.set(col, colIndex >= 0 && colIndex <= midpoint ? 'left' : 'right');
         });
+        defaultPinnedRightColumns.forEach((col) => map.set(col, 'right'));
         return map;
     });
 
     const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(new Set());
 
-    // Derive isRowIndexPinned from pinnedColumns for convenience
-    const isRowIndexPinned = pinnedColumns.has(ROW_INDEX_COLUMN_ID);
-
-    // Toggle column pin (works for any column including row index)
-    const handleTogglePin = useCallback((columnId: string) => {
-        setPinnedColumns((prev) => {
-            const newMap = new Map(prev);
-            if (newMap.has(columnId)) {
-                newMap.delete(columnId);
-            } else {
-                newMap.set(columnId, 'left');
+    // DOM measurement for accurate widths
+    const measuredWidthsRef = useRef<Map<string, number>>(new Map());
+    const tableElRef = useRef<HTMLElement | null>(null);
+    // Counter to trigger re-computation of offset memos after measurement
+    const [measureVersion, setMeasureVersion] = useState(0);
+
+    const measureColumnWidths = useCallback(() => {
+        const el = tableElRef.current;
+        if (!el) return;
+        const newMap = new Map<string, number>();
+        const headers = el.querySelectorAll('th[data-column-id]');
+        headers.forEach((th) => {
+            const colId = th.getAttribute('data-column-id');
+            if (colId) {
+                newMap.set(colId, (th as HTMLElement).offsetWidth);
             }
-            return newMap;
         });
+        // Measure row index from first data row
+        const rowIndexTd = el.querySelector('td[data-column-id="__row_index__"]');
+        if (rowIndexTd) {
+            newMap.set(ROW_INDEX_COLUMN_ID, (rowIndexTd as HTMLElement).offsetWidth);
+        }
+        measuredWidthsRef.current = newMap;
+        setMeasureVersion((v) => v + 1);
     }, []);
 
-    // Set pinned columns from an array of column IDs
+    const measureRef = useCallback((el: HTMLElement | null) => {
+        tableElRef.current = el;
+    }, []);
+
+    const isRowIndexPinned = pinnedColumns.has(ROW_INDEX_COLUMN_ID);
+
+    // Toggle pin with auto left/right detection
+    const handleTogglePin = useCallback(
+        (columnId: string) => {
+            setPinnedColumns((prev) => {
+                const newMap = new Map(prev);
+                if (newMap.has(columnId)) {
+                    newMap.delete(columnId);
+                } else {
+                    if (columnId === ROW_INDEX_COLUMN_ID) {
+                        newMap.set(columnId, 'left');
+                    } else {
+                        const colIndex = columns.findIndex((c) => c.id === columnId);
+                        const midpoint = Math.floor(columns.length / 2);
+                        newMap.set(columnId, colIndex <= midpoint ? 'left' : 'right');
+                    }
+                }
+                return newMap;
+            });
+        },
+        [columns]
+    );
+
     const setPinnedColumnsFromIds = useCallback((columnIds: string[]) => {
         const map = new Map<string, 'left' | 'right'>();
+        if (showRowIndex) {
+            map.set(ROW_INDEX_COLUMN_ID, 'left');
+        }
+        const midpoint = Math.floor(columns.length / 2);
         columnIds.forEach((col) => {
-            map.set(col, 'left');
+            if (col !== ROW_INDEX_COLUMN_ID) {
+                const colIndex = columns.findIndex((c) => c.id === col);
+                map.set(col, colIndex >= 0 && colIndex <= midpoint ? 'left' : 'right');
+            }
         });
         setPinnedColumns(map);
-    }, []);
+    }, [showRowIndex, columns]);
 
-    // Toggle group collapse
     const handleToggleGroupCollapse = useCallback((groupId: string) => {
         setCollapsedGroups((prev) => {
             const newSet = new Set(prev);
@@ -99,135 +139,107 @@ export function useSpreadsheetPinning<T>({
         });
     }, []);
 
-    // Calculate visible columns based on groups, collapse state, and pinning order
+    // Visible columns — filtered by collapse, natural order preserved
     const visibleColumns = useMemo(() => {
-        if (!columns || !Array.isArray(columns) || columns.length === 0) {
-            return [];
-        }
+        if (!columns || !Array.isArray(columns) || columns.length === 0) return [];
 
         let result: SpreadsheetColumn<T>[] = [...columns];
 
-        // Filter based on column groups and collapse state
         if (columnGroups && Array.isArray(columnGroups)) {
             result = result.filter((column) => {
                 const group = columnGroups.find((g) => g.columns.includes(column.id));
                 if (!group) return true;
                 if (!collapsedGroups.has(group.id)) return true;
-                // When collapsed, only show pinned columns
                 return pinnedColumns.has(column.id);
             });
         }
 
-        // If no columns are pinned (excluding row index), return result as-is to preserve original order
-        const nonRowIndexPinned = Array.from(pinnedColumns.keys()).filter(
-            (id) => id !== ROW_INDEX_COLUMN_ID
-        );
-        if (nonRowIndexPinned.length === 0) {
-            return result;
-        }
+        return result;
+    }, [columns, columnGroups, collapsedGroups, pinnedColumns]);
 
-        // Reorder columns: left-pinned first, unpinned in middle, right-pinned last
-        const leftPinned: SpreadsheetColumn<T>[] = [];
-        const unpinned: SpreadsheetColumn<T>[] = [];
-        const rightPinned: SpreadsheetColumn<T>[] = [];
-
-        // Maintain the order of pinned columns as they were added
-        const pinnedLeftIds = Array.from(pinnedColumns.entries())
-            .filter(([id, side]) => side === 'left' && id !== ROW_INDEX_COLUMN_ID)
-            .map(([id]) => id);
-        const pinnedRightIds = Array.from(pinnedColumns.entries())
-            .filter(([id, side]) => side === 'right' && id !== ROW_INDEX_COLUMN_ID)
-            .map(([id]) => id);
-
-        for (const column of result) {
-            const pinSide = pinnedColumns.get(column.id);
-            if (pinSide === 'left') {
-                leftPinned.push(column);
-            } else if (pinSide === 'right') {
-                rightPinned.push(column);
-            } else {
-                unpinned.push(column);
-            }
+    // Measure after render when layout changes
+    useEffect(() => {
+        requestAnimationFrame(() => measureColumnWidths());
+    }, [measureColumnWidths, visibleColumns, pinnedColumns]);
+
+    // Pre-compute a width lookup map (fast O(1) per column)
+    const widthMap = useMemo(() => {
+        // measureVersion is in deps to recompute when DOM measurements update
+        void measureVersion;
+        const map = new Map<string, number>();
+        for (const col of columns) {
+            const measured = measuredWidthsRef.current.get(col.id);
+            if (measured) { map.set(col.id, measured); continue; }
+            const resized = getColumnWidth?.(col.id);
+            if (resized) { map.set(col.id, resized); continue; }
+            map.set(col.id, col.width || col.minWidth || 100);
+        }
+        // Row index
+        const measuredRI = measuredWidthsRef.current.get(ROW_INDEX_COLUMN_ID);
+        map.set(ROW_INDEX_COLUMN_ID, measuredRI || ROW_INDEX_COLUMN_WIDTH);
+        return map;
+    }, [columns, getColumnWidth, measureVersion]);
+
+    // Pre-compute all offsets and z-indices in a single pass (O(n) total, not O(n²))
+    const { leftOffsets, rightOffsets, zIndices } = useMemo(() => {
+        const leftOffsets = new Map<string, number>();
+        const rightOffsets = new Map<string, number>();
+        const zIndices = new Map<string, number>();
+
+        // Row index
+        leftOffsets.set(ROW_INDEX_COLUMN_ID, 0);
+        zIndices.set(ROW_INDEX_COLUMN_ID, 40);
+
+        // Collect left-pinned and right-pinned in natural order
+        const leftPinned = visibleColumns.filter((c) => pinnedColumns.get(c.id) === 'left');
+        const rightPinned = visibleColumns.filter((c) => pinnedColumns.get(c.id) === 'right');
+
+        // Left offsets: cumulative from left edge
+        const isRowIndexPinnedNow = pinnedColumns.has(ROW_INDEX_COLUMN_ID);
+        let leftOffset = showRowIndex && isRowIndexPinnedNow ? (widthMap.get(ROW_INDEX_COLUMN_ID) || ROW_INDEX_COLUMN_WIDTH) : 0;
+        for (let i = 0; i < leftPinned.length; i++) {
+            leftOffsets.set(leftPinned[i].id, leftOffset);
+            // Earlier left-pinned = higher z-index
+            zIndices.set(leftPinned[i].id, 20 + (leftPinned.length - i));
+            leftOffset += widthMap.get(leftPinned[i].id) || 100;
         }
 
-        // Sort left and right pinned columns based on their order in the pinnedColumns map
-        leftPinned.sort((a, b) => pinnedLeftIds.indexOf(a.id) - pinnedLeftIds.indexOf(b.id));
-        rightPinned.sort((a, b) => pinnedRightIds.indexOf(a.id) - pinnedRightIds.indexOf(b.id));
+        // Right offsets: cumulative from right edge
+        let rightOffset = 0;
+        for (let i = rightPinned.length - 1; i >= 0; i--) {
+            rightOffsets.set(rightPinned[i].id, rightOffset);
+            // Later right-pinned (closer to edge) = higher z-index
+            zIndices.set(rightPinned[i].id, 20 + (rightPinned.length - i));
+            rightOffset += widthMap.get(rightPinned[i].id) || 100;
+        }
 
-        return [...leftPinned, ...unpinned, ...rightPinned];
-    }, [columns, columnGroups, collapsedGroups, pinnedColumns]);
+        return { leftOffsets, rightOffsets, zIndices };
+    }, [pinnedColumns, visibleColumns, showRowIndex, widthMap]);
 
-    // Calculate column offset for sticky positioning
+    // O(1) lookups using pre-computed maps
     const getColumnLeftOffset = useCallback(
-        (columnId: string): number => {
-            // Row index column is always at left: 0 when pinned
-            if (columnId === ROW_INDEX_COLUMN_ID) {
-                return 0;
-            }
+        (columnId: string): number => leftOffsets.get(columnId) ?? 0,
+        [leftOffsets]
+    );
 
-            // Get left-pinned columns (excluding row index)
-            const pinnedLeft = Array.from(pinnedColumns.entries())
-                .filter(([id, side]) => side === 'left' && id !== ROW_INDEX_COLUMN_ID)
-                .map(([id]) => id);
-            const index = pinnedLeft.indexOf(columnId);
-
-            // Base offset includes the row index column if shown and pinned
-            const isRowIndexPinnedNow = pinnedColumns.has(ROW_INDEX_COLUMN_ID);
-            const baseOffset = showRowIndex && isRowIndexPinnedNow ? ROW_INDEX_COLUMN_WIDTH : 0;
-
-            if (index === -1) return baseOffset;
-
-            let offset = baseOffset;
-            for (let i = 0; i < index; i++) {
-                const col = columns.find((c) => c.id === pinnedLeft[i]);
-                // Pinned columns are clamped to at least MIN_PINNED_COLUMN_WIDTH
-                // so that header actions (pin, filter, highlight icons) always fit
-                const configuredWidth = col?.minWidth || col?.width || MIN_PINNED_COLUMN_WIDTH;
-                offset += Math.max(configuredWidth, MIN_PINNED_COLUMN_WIDTH);
-            }
-            return offset;
-        },
-        [pinnedColumns, columns, showRowIndex]
+    const getColumnRightOffset = useCallback(
+        (columnId: string): number => rightOffsets.get(columnId) ?? 0,
+        [rightOffsets]
     );
 
-    // Check if column is pinned
     const isColumnPinned = useCallback(
-        (columnId: string): boolean => {
-            return pinnedColumns.has(columnId);
-        },
+        (columnId: string): boolean => pinnedColumns.has(columnId),
         [pinnedColumns]
     );
 
-    // Get column pin side
     const getColumnPinSide = useCallback(
-        (columnId: string): 'left' | 'right' | undefined => {
-            return pinnedColumns.get(columnId);
-        },
+        (columnId: string): 'left' | 'right' | undefined => pinnedColumns.get(columnId),
         [pinnedColumns]
     );
 
-    // Calculate column offset for right sticky positioning
-    const getColumnRightOffset = useCallback(
-        (columnId: string): number => {
-            // Get right-pinned columns
-            const pinnedRight = Array.from(pinnedColumns.entries())
-                .filter(([, side]) => side === 'right')
-                .map(([id]) => id);
-
-            const index = pinnedRight.indexOf(columnId);
-            if (index === -1) return 0;
-
-            // Calculate offset from the right edge
-            // Start from 0 and add widths of columns to the right of this one
-            let offset = 0;
-            for (let i = pinnedRight.length - 1; i > index; i--) {
-                const col = columns.find((c) => c.id === pinnedRight[i]);
-                const configuredWidth = col?.minWidth || col?.width || MIN_PINNED_COLUMN_WIDTH;
-                offset += Math.max(configuredWidth, MIN_PINNED_COLUMN_WIDTH);
-            }
-            return offset;
-        },
-        [pinnedColumns, columns]
+    const getPinnedZIndex = useCallback(
+        (columnId: string): number => zIndices.get(columnId) ?? 0,
+        [zIndices]
     );
 
     return {
@@ -242,5 +254,7 @@ export function useSpreadsheetPinning<T>({
         getColumnRightOffset,
         isColumnPinned,
         getColumnPinSide,
+        getPinnedZIndex,
+        measureRef,
     };
 }

package/src/hooks/useSpreadsheetSelection.ts

@@ -256,7 +256,7 @@ export function useSpreadsheetSelection<T extends Record<string, any>>({
         });
     }, [getSelectedCells, data, columns, getRowId]);
 
-    // Handle cell click
+    // Handle cell click (focus only — edit mode requires double-click or F2)
     const handleCellClick = useCallback(
         (rowId: string | number, columnId: string, event: React.MouseEvent) => {
             event.stopPropagation();
@@ -271,22 +271,17 @@ export function useSpreadsheetSelection<T extends Record<string, any>>({
                 });
                 setFocusedCell(newCell);
             } else {
-                // Single cell selection
+                // Single cell selection — focus only, no edit
                 anchorCell.current = newCell;
                 setFocusedCell(newCell);
                 setSelectedCellRange(null);
-
-                // Enter edit mode if editable
-                const column = columns.find((c) => c.id === columnId);
-                if (column?.editable && enableCellEditing) {
-                    setEditingCell(newCell);
-                }
+                setEditingCell(null);
             }
         },
-        [columns, enableCellEditing, setSelectedCellRange]
+        [setSelectedCellRange]
     );
 
-    // Handle cell mouse down (for shift+click selection)
+    // Handle cell mouse down (for focus and drag-to-select initiation)
     const handleCellMouseDown = useCallback(
         (rowId: string | number, columnId: string, event: React.MouseEvent) => {
             // Only handle left mouse button
@@ -304,26 +299,19 @@ export function useSpreadsheetSelection<T extends Record<string, any>>({
                 setFocusedCell(newCell);
                 setEditingCell(null);
             } else {
-                // Regular click: focus cell, clear any selection, and enter edit mode if editable
+                // Regular click: focus cell only (edit mode requires double-click or F2)
                 anchorCell.current = newCell;
                 setFocusedCell(newCell);
                 setSelectedCellRange(null);
-
-                // Enter edit mode if editable
-                const column = columns.find((c) => c.id === columnId);
-                if (column?.editable && enableCellEditing) {
-                    setEditingCell(newCell);
-                } else {
-                    setEditingCell(null);
-                }
+                setEditingCell(null);
             }
         },
-        [columns, enableCellEditing, setSelectedCellRange]
+        [setSelectedCellRange]
     );
 
-    // Handle cell mouse enter (currently unused - drag selection disabled)
+    // Handle cell mouse enter (drag selection disabled — use Shift+Click or Shift+Arrow for range selection)
     const handleCellMouseEnter = useCallback((_rowId: string | number, _columnId: string) => {
-        // Drag selection is disabled - selection only via shift+click or shift+arrow
+        // Intentionally empty — drag-to-select disabled for better UX in data table context
     }, []);
 
     // Handle mouse up (end drag)

package/src/hooks/useSpreadsheetSummary.ts

@@ -0,0 +1,68 @@
+import { useMemo } from 'react';
+import type { CellPosition, SpreadsheetColumn } from '../types';
+
+export interface SelectionSummary {
+    sum: number;
+    avg: number;
+    count: number;
+    numericCount: number;
+    min: number;
+    max: number;
+}
+
+export interface UseSpreadsheetSummaryOptions<T> {
+    /** Currently selected cell values */
+    selectedCellValues: { position: CellPosition; value: any }[];
+    /** Column definitions for type checking */
+    columns: SpreadsheetColumn<T>[];
+}
+
+export interface UseSpreadsheetSummaryReturn {
+    /** Computed summary for the current selection */
+    summary: SelectionSummary | null;
+    /** Whether there are numeric values to summarize */
+    hasNumericValues: boolean;
+}
+
+/**
+ * Hook for computing Excel-like summary statistics (Sum, Avg, Count, Min, Max)
+ * for the current cell selection. Only computes for numeric values.
+ */
+export function useSpreadsheetSummary<T>({
+    selectedCellValues,
+    columns,
+}: UseSpreadsheetSummaryOptions<T>): UseSpreadsheetSummaryReturn {
+    const summary = useMemo(() => {
+        if (selectedCellValues.length === 0) return null;
+
+        const numericValues: number[] = [];
+
+        for (const { position, value } of selectedCellValues) {
+            const column = columns.find((c) => c.id === position.columnId);
+            // Include values from numeric columns or any parseable number
+            if (column?.type === 'number' || typeof value === 'number') {
+                const num = typeof value === 'number' ? value : parseFloat(value);
+                if (!isNaN(num)) {
+                    numericValues.push(num);
+                }
+            }
+        }
+
+        if (numericValues.length === 0) return null;
+
+        const sum = numericValues.reduce((a, b) => a + b, 0);
+        return {
+            sum: Math.round(sum * 100) / 100,
+            avg: Math.round((sum / numericValues.length) * 100) / 100,
+            count: selectedCellValues.length,
+            numericCount: numericValues.length,
+            min: Math.round(Math.min(...numericValues) * 100) / 100,
+            max: Math.round(Math.max(...numericValues) * 100) / 100,
+        };
+    }, [selectedCellValues, columns]);
+
+    return {
+        summary,
+        hasNumericValues: summary !== null,
+    };
+}

package/src/index.ts

@@ -1,9 +1,12 @@
 // Main Spreadsheet component
 export { Spreadsheet } from './components/Spreadsheet';
 
+// Hooks
+export { useSpreadsheetDuplicates } from './hooks/useSpreadsheetDuplicates';
+
 // Sub-components
 export { SpreadsheetCell } from './components/SpreadsheetCell';
-export { SpreadsheetHeader } from './components/SpreadsheetHeader';
+export { SpreadsheetHeader, MemoizedSpreadsheetHeader } from './components/SpreadsheetHeader';
 export { SpreadsheetFilterDropdown } from './components/SpreadsheetFilterDropdown';
 export { SpreadsheetToolbar } from './components/SpreadsheetToolbar';
 export { SpreadsheetSettingsModal } from './components/SpreadsheetSettingsModal';

package/src/styles/globals.css

@@ -1,3 +1,54 @@
 @import "tailwindcss";
 
 @source "../**/*.{ts,tsx,css}";
+
+/* Minimal scrollbar styling scoped to the spreadsheet container */
+.spreadsheet-scroll-container {
+    scrollbar-width: thin;
+    scrollbar-color: rgb(156 163 175) transparent;
+}
+
+.spreadsheet-scroll-container::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+}
+
+.spreadsheet-scroll-container::-webkit-scrollbar-track {
+    background: transparent;
+}
+
+.spreadsheet-scroll-container::-webkit-scrollbar-thumb {
+    background-color: rgb(209 213 219);
+    border-radius: 3px;
+}
+
+.spreadsheet-scroll-container::-webkit-scrollbar-thumb:hover {
+    background-color: rgb(156 163 175);
+}
+
+.spreadsheet-scroll-container::-webkit-scrollbar-corner {
+    background: transparent;
+}
+
+/* Row hover via CSS to avoid React re-renders */
+.spreadsheet-scroll-container tbody tr:hover > td {
+    background-color: rgb(249 250 251) !important; /* gray-50 */
+}
+
+/* Don't override selected or highlighted row backgrounds */
+.spreadsheet-scroll-container tbody tr:hover > td[style*="dbeafe"],
+.spreadsheet-scroll-container tbody tr:hover > td[style*="239 246 255"] {
+    background-color: rgb(219 234 254) !important; /* blue-100, keep selected */
+}
+
+/* Processing overlay anchored to the table wrapper */
+.spreadsheet-processing-overlay {
+    position: absolute;
+    inset: 0;
+    background: rgba(255, 255, 255, 0.6);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 60;
+    pointer-events: none;
+}