@xcelsior/ui-spreadsheets 1.0.14 → 1.0.16

package/src/hooks/useSpreadsheetSelection.ts

@@ -0,0 +1,678 @@
+import { useCallback, useState, useRef, useMemo } from 'react';
+import type { CellPosition, CellRange, CellEdit, SpreadsheetColumn } from '../types';
+
+export interface UseSpreadsheetSelectionOptions<T> {
+    /** Data rows */
+    data: T[];
+    /** Visible columns */
+    columns: SpreadsheetColumn<T>[];
+    /** Function to get row ID */
+    getRowId: (row: T) => string | number;
+    /** Callback when cell range selection changes */
+    onCellRangeSelectionChange?: (range: CellRange | null) => void;
+    /** Whether cell editing is enabled */
+    enableCellEditing?: boolean;
+}
+
+export interface UseSpreadsheetSelectionReturn {
+    /** Currently focused cell */
+    focusedCell: CellPosition | null;
+    /** Set focused cell */
+    setFocusedCell: (cell: CellPosition | null) => void;
+    /** Currently editing cell */
+    editingCell: CellPosition | null;
+    /** Set editing cell */
+    setEditingCell: (cell: CellPosition | null) => void;
+    /** Selected cell range */
+    selectedCellRange: CellRange | null;
+    /** Set selected cell range */
+    setSelectedCellRange: (range: CellRange | null) => void;
+    /** Whether currently dragging to select */
+    isDragging: boolean;
+    /** Handle cell click */
+    handleCellClick: (rowId: string | number, columnId: string, event: React.MouseEvent) => void;
+    /** Handle cell mouse down (start drag selection) */
+    handleCellMouseDown: (
+        rowId: string | number,
+        columnId: string,
+        event: React.MouseEvent
+    ) => void;
+    /** Handle cell mouse enter (during drag) */
+    handleCellMouseEnter: (rowId: string | number, columnId: string) => void;
+    /** Handle mouse up (end drag) */
+    handleMouseUp: () => void;
+    /** Check if cell is in selection range */
+    isCellInSelection: (rowId: string | number, columnId: string) => boolean;
+    /** Get selection edge for a cell */
+    getCellSelectionEdge: (
+        rowId: string | number,
+        columnId: string
+    ) => { top?: boolean; right?: boolean; bottom?: boolean; left?: boolean } | undefined;
+    /** Get all cells in the current selection */
+    getSelectedCells: () => CellPosition[];
+    /** Get cell values from the selection */
+    getSelectedCellValues: () => { position: CellPosition; value: any }[];
+    /** Clear selection */
+    clearSelection: () => void;
+    /** Navigate to adjacent cell */
+    navigateCell: (direction: 'up' | 'down' | 'left' | 'right', extendSelection?: boolean) => void;
+    /** Handle Tab key navigation */
+    handleTabNavigation: (shiftKey: boolean) => void;
+    /** Enter edit mode for focused cell */
+    enterEditMode: () => void;
+    /** Exit edit mode */
+    exitEditMode: () => void;
+    /** Clipboard data from copy operation */
+    clipboardData: { values: any[][]; startCell: CellPosition } | null;
+    /** Copy selected cells to clipboard */
+    copySelectedCells: () => void;
+    /** Paste clipboard data at focused cell */
+    pasteClipboard: () => CellEdit[];
+    /** Paste from system clipboard (async) */
+    pasteFromSystemClipboard: () => Promise<CellEdit[]>;
+}
+
+/**
+ * Hook for managing Excel-like cell selection in spreadsheet
+ * Supports:
+ * - Single cell selection (click)
+ * - Range selection (shift+click)
+ * - Drag selection (mouse drag)
+ * - Keyboard navigation with selection extension (shift+arrow)
+ * - Copy/paste for multiple cells
+ */
+export function useSpreadsheetSelection<T extends Record<string, any>>({
+    data,
+    columns,
+    getRowId,
+    onCellRangeSelectionChange,
+    enableCellEditing = true,
+}: UseSpreadsheetSelectionOptions<T>): UseSpreadsheetSelectionReturn {
+    const [focusedCell, setFocusedCell] = useState<CellPosition | null>(null);
+    const [editingCell, setEditingCell] = useState<CellPosition | null>(null);
+    const [selectedCellRange, setSelectedCellRangeState] = useState<CellRange | null>(null);
+    const [isDragging, setIsDragging] = useState(false);
+    const [clipboardData, setClipboardData] = useState<{
+        values: any[][];
+        startCell: CellPosition;
+    } | null>(null);
+
+    // Track the anchor cell for shift+click and drag selection
+    const anchorCell = useRef<CellPosition | null>(null);
+
+    // Create a map for quick row index lookup
+    const rowIndexMap = useMemo(() => {
+        const map = new Map<string | number, number>();
+        data.forEach((row, index) => {
+            map.set(getRowId(row), index);
+        });
+        return map;
+    }, [data, getRowId]);
+
+    // Create a map for quick column index lookup
+    const columnIndexMap = useMemo(() => {
+        const map = new Map<string, number>();
+        columns.forEach((col, index) => {
+            map.set(col.id, index);
+        });
+        return map;
+    }, [columns]);
+
+    // Wrapper for setSelectedCellRange that also calls the callback
+    const setSelectedCellRange = useCallback(
+        (range: CellRange | null) => {
+            setSelectedCellRangeState(range);
+            onCellRangeSelectionChange?.(range);
+        },
+        [onCellRangeSelectionChange]
+    );
+
+    // Get normalized range (ensure start is top-left, end is bottom-right)
+    const getNormalizedRange = useCallback(
+        (
+            range: CellRange | null
+        ): {
+            startRowIdx: number;
+            endRowIdx: number;
+            startColIdx: number;
+            endColIdx: number;
+        } | null => {
+            if (!range) return null;
+
+            const startRowIdx = rowIndexMap.get(range.start.rowId);
+            const endRowIdx = rowIndexMap.get(range.end.rowId);
+            const startColIdx = columnIndexMap.get(range.start.columnId);
+            const endColIdx = columnIndexMap.get(range.end.columnId);
+
+            if (
+                startRowIdx === undefined ||
+                endRowIdx === undefined ||
+                startColIdx === undefined ||
+                endColIdx === undefined
+            ) {
+                return null;
+            }
+
+            return {
+                startRowIdx: Math.min(startRowIdx, endRowIdx),
+                endRowIdx: Math.max(startRowIdx, endRowIdx),
+                startColIdx: Math.min(startColIdx, endColIdx),
+                endColIdx: Math.max(startColIdx, endColIdx),
+            };
+        },
+        [rowIndexMap, columnIndexMap]
+    );
+
+    // Check if a cell is within the selection range
+    const isCellInSelection = useCallback(
+        (rowId: string | number, columnId: string): boolean => {
+            const normalizedRange = getNormalizedRange(selectedCellRange);
+            if (!normalizedRange) return false;
+
+            const rowIdx = rowIndexMap.get(rowId);
+            const colIdx = columnIndexMap.get(columnId);
+
+            if (rowIdx === undefined || colIdx === undefined) return false;
+
+            return (
+                rowIdx >= normalizedRange.startRowIdx &&
+                rowIdx <= normalizedRange.endRowIdx &&
+                colIdx >= normalizedRange.startColIdx &&
+                colIdx <= normalizedRange.endColIdx
+            );
+        },
+        [selectedCellRange, rowIndexMap, columnIndexMap, getNormalizedRange]
+    );
+
+    // Get selection edge for visual border styling
+    const getCellSelectionEdge = useCallback(
+        (
+            rowId: string | number,
+            columnId: string
+        ): { top?: boolean; right?: boolean; bottom?: boolean; left?: boolean } | undefined => {
+            if (!isCellInSelection(rowId, columnId)) return undefined;
+
+            const normalizedRange = getNormalizedRange(selectedCellRange);
+            if (!normalizedRange) return undefined;
+
+            const rowIdx = rowIndexMap.get(rowId);
+            const colIdx = columnIndexMap.get(columnId);
+
+            if (rowIdx === undefined || colIdx === undefined) return undefined;
+
+            return {
+                top: rowIdx === normalizedRange.startRowIdx,
+                bottom: rowIdx === normalizedRange.endRowIdx,
+                left: colIdx === normalizedRange.startColIdx,
+                right: colIdx === normalizedRange.endColIdx,
+            };
+        },
+        [isCellInSelection, selectedCellRange, rowIndexMap, columnIndexMap, getNormalizedRange]
+    );
+
+    // Get all cells in the current selection
+    const getSelectedCells = useCallback((): CellPosition[] => {
+        const normalizedRange = getNormalizedRange(selectedCellRange);
+        if (!normalizedRange) {
+            return focusedCell ? [focusedCell] : [];
+        }
+
+        const cells: CellPosition[] = [];
+        for (
+            let rowIdx = normalizedRange.startRowIdx;
+            rowIdx <= normalizedRange.endRowIdx;
+            rowIdx++
+        ) {
+            const row = data[rowIdx];
+            if (!row) continue;
+            const rowId = getRowId(row);
+
+            for (
+                let colIdx = normalizedRange.startColIdx;
+                colIdx <= normalizedRange.endColIdx;
+                colIdx++
+            ) {
+                const column = columns[colIdx];
+                if (!column) continue;
+                cells.push({ rowId, columnId: column.id });
+            }
+        }
+        return cells;
+    }, [selectedCellRange, focusedCell, data, columns, getRowId, getNormalizedRange]);
+
+    // Get cell values from selection
+    const getSelectedCellValues = useCallback((): { position: CellPosition; value: any }[] => {
+        const cells = getSelectedCells();
+        return cells.map((cell) => {
+            const row = data.find((r) => getRowId(r) === cell.rowId);
+            const column = columns.find((c) => c.id === cell.columnId);
+            const value =
+                row && column
+                    ? column.getValue
+                        ? column.getValue(row)
+                        : row[cell.columnId]
+                    : undefined;
+            return { position: cell, value };
+        });
+    }, [getSelectedCells, data, columns, getRowId]);
+
+    // Handle cell click
+    const handleCellClick = useCallback(
+        (rowId: string | number, columnId: string, event: React.MouseEvent) => {
+            event.stopPropagation();
+
+            const newCell: CellPosition = { rowId, columnId };
+
+            if (event.shiftKey && anchorCell.current) {
+                // Extend selection from anchor to clicked cell
+                setSelectedCellRange({
+                    start: anchorCell.current,
+                    end: newCell,
+                });
+                setFocusedCell(newCell);
+            } else {
+                // Single cell selection
+                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);
+                }
+            }
+        },
+        [columns, enableCellEditing, setSelectedCellRange]
+    );
+
+    // Handle cell mouse down (for shift+click selection)
+    const handleCellMouseDown = useCallback(
+        (rowId: string | number, columnId: string, event: React.MouseEvent) => {
+            // Only handle left mouse button
+            if (event.button !== 0) return;
+
+            const newCell: CellPosition = { rowId, columnId };
+
+            if (event.shiftKey && anchorCell.current) {
+                // Shift+click: extend selection from anchor to this cell
+                event.preventDefault();
+                setSelectedCellRange({
+                    start: anchorCell.current,
+                    end: newCell,
+                });
+                setFocusedCell(newCell);
+                setEditingCell(null);
+            } else {
+                // Regular click: focus cell, clear any selection, and enter edit mode if editable
+                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);
+                }
+            }
+        },
+        [columns, enableCellEditing, setSelectedCellRange]
+    );
+
+    // Handle cell mouse enter (currently unused - drag selection disabled)
+    const handleCellMouseEnter = useCallback((_rowId: string | number, _columnId: string) => {
+        // Drag selection is disabled - selection only via shift+click or shift+arrow
+    }, []);
+
+    // Handle mouse up (end drag)
+    const handleMouseUp = useCallback(() => {
+        setIsDragging(false);
+    }, []);
+
+    // Clear selection
+    const clearSelection = useCallback(() => {
+        setFocusedCell(null);
+        setEditingCell(null);
+        setSelectedCellRange(null);
+        anchorCell.current = null;
+    }, [setSelectedCellRange]);
+
+    // Navigate to adjacent cell
+    const navigateCell = useCallback(
+        (direction: 'up' | 'down' | 'left' | 'right', extendSelection = false) => {
+            const currentCell = focusedCell;
+            if (!currentCell) return;
+
+            const currentRowIdx = rowIndexMap.get(currentCell.rowId);
+            const currentColIdx = columnIndexMap.get(currentCell.columnId);
+
+            if (currentRowIdx === undefined || currentColIdx === undefined) return;
+
+            let newRowIdx = currentRowIdx;
+            let newColIdx = currentColIdx;
+
+            switch (direction) {
+                case 'up':
+                    newRowIdx = Math.max(0, currentRowIdx - 1);
+                    break;
+                case 'down':
+                    newRowIdx = Math.min(data.length - 1, currentRowIdx + 1);
+                    break;
+                case 'left':
+                    newColIdx = Math.max(0, currentColIdx - 1);
+                    break;
+                case 'right':
+                    newColIdx = Math.min(columns.length - 1, currentColIdx + 1);
+                    break;
+            }
+
+            const newRow = data[newRowIdx];
+            const newColumn = columns[newColIdx];
+
+            if (!newRow || !newColumn) return;
+
+            const newCell: CellPosition = {
+                rowId: getRowId(newRow),
+                columnId: newColumn.id,
+            };
+
+            setFocusedCell(newCell);
+            setEditingCell(null);
+
+            if (extendSelection) {
+                // Extend selection from anchor
+                if (!anchorCell.current) {
+                    anchorCell.current = currentCell;
+                }
+                setSelectedCellRange({
+                    start: anchorCell.current,
+                    end: newCell,
+                });
+            } else {
+                // Clear selection and set new anchor
+                anchorCell.current = newCell;
+                setSelectedCellRange(null);
+            }
+        },
+        [focusedCell, data, columns, getRowId, rowIndexMap, columnIndexMap, setSelectedCellRange]
+    );
+
+    // Handle Tab key navigation
+    const handleTabNavigation = useCallback(
+        (shiftKey: boolean) => {
+            const currentCell = focusedCell;
+            if (!currentCell) return;
+
+            const currentRowIdx = rowIndexMap.get(currentCell.rowId);
+            const currentColIdx = columnIndexMap.get(currentCell.columnId);
+
+            if (currentRowIdx === undefined || currentColIdx === undefined) return;
+
+            let newRowIdx = currentRowIdx;
+            let newColIdx = currentColIdx;
+
+            if (shiftKey) {
+                // Move backwards
+                newColIdx--;
+                if (newColIdx < 0) {
+                    newColIdx = columns.length - 1;
+                    newRowIdx--;
+                }
+            } else {
+                // Move forwards
+                newColIdx++;
+                if (newColIdx >= columns.length) {
+                    newColIdx = 0;
+                    newRowIdx++;
+                }
+            }
+
+            // Wrap around
+            if (newRowIdx < 0) {
+                newRowIdx = data.length - 1;
+            } else if (newRowIdx >= data.length) {
+                newRowIdx = 0;
+            }
+
+            const newRow = data[newRowIdx];
+            const newColumn = columns[newColIdx];
+
+            if (!newRow || !newColumn) return;
+
+            const newCell: CellPosition = {
+                rowId: getRowId(newRow),
+                columnId: newColumn.id,
+            };
+
+            setFocusedCell(newCell);
+            setEditingCell(null);
+            setSelectedCellRange(null);
+            anchorCell.current = newCell;
+        },
+        [focusedCell, data, columns, getRowId, rowIndexMap, columnIndexMap, setSelectedCellRange]
+    );
+
+    // Enter edit mode
+    const enterEditMode = useCallback(() => {
+        if (!focusedCell || !enableCellEditing) return;
+
+        const column = columns.find((c) => c.id === focusedCell.columnId);
+        if (column?.editable) {
+            setEditingCell(focusedCell);
+        }
+    }, [focusedCell, columns, enableCellEditing]);
+
+    // Exit edit mode
+    const exitEditMode = useCallback(() => {
+        setEditingCell(null);
+    }, []);
+
+    // Copy selected cells
+    const copySelectedCells = useCallback(() => {
+        const normalizedRange = getNormalizedRange(selectedCellRange);
+
+        if (!normalizedRange && !focusedCell) return;
+
+        const startRowIdx =
+            normalizedRange?.startRowIdx ?? rowIndexMap.get(focusedCell!.rowId) ?? 0;
+        const endRowIdx = normalizedRange?.endRowIdx ?? startRowIdx;
+        const startColIdx =
+            normalizedRange?.startColIdx ?? columnIndexMap.get(focusedCell!.columnId) ?? 0;
+        const endColIdx = normalizedRange?.endColIdx ?? startColIdx;
+
+        const values: any[][] = [];
+        const textRows: string[] = [];
+
+        for (let rowIdx = startRowIdx; rowIdx <= endRowIdx; rowIdx++) {
+            const row = data[rowIdx];
+            if (!row) continue;
+
+            const rowValues: any[] = [];
+            const textCells: string[] = [];
+
+            for (let colIdx = startColIdx; colIdx <= endColIdx; colIdx++) {
+                const column = columns[colIdx];
+                if (!column) continue;
+
+                const value = column.getValue ? column.getValue(row) : row[column.id];
+                rowValues.push(value);
+                textCells.push(value != null ? String(value) : '');
+            }
+
+            values.push(rowValues);
+            textRows.push(textCells.join('\t'));
+        }
+
+        // Store in internal clipboard
+        const startRow = data[startRowIdx];
+        const startColumn = columns[startColIdx];
+        if (startRow && startColumn) {
+            setClipboardData({
+                values,
+                startCell: {
+                    rowId: getRowId(startRow),
+                    columnId: startColumn.id,
+                },
+            });
+        }
+
+        // Copy to system clipboard
+        const text = textRows.join('\n');
+        navigator.clipboard.writeText(text).catch(() => {
+            // Fallback for browsers without clipboard API
+            console.warn('Could not copy to system clipboard');
+        });
+    }, [
+        selectedCellRange,
+        focusedCell,
+        data,
+        columns,
+        getRowId,
+        getNormalizedRange,
+        rowIndexMap,
+        columnIndexMap,
+    ]);
+
+    // Parse text into 2D array (tab-separated columns, newline-separated rows)
+    const parseClipboardText = useCallback((text: string): any[][] => {
+        const lines = text.split(/\r?\n/);
+        // Remove trailing empty line if present
+        if (lines.length > 0 && lines[lines.length - 1] === '') {
+            lines.pop();
+        }
+        return lines.map((line) => line.split('\t'));
+    }, []);
+
+    // Helper function to create edits from a 2D values array
+    // If there's a selection, fills the selection. Otherwise starts from focused cell.
+    const createEditsFromValues = useCallback(
+        (values: any[][]): CellEdit[] => {
+            if (!focusedCell) return [];
+
+            const edits: CellEdit[] = [];
+            const normalizedRange = getNormalizedRange(selectedCellRange);
+
+            // Determine the target range
+            let startRowIdx: number;
+            let endRowIdx: number;
+            let startColIdx: number;
+            let endColIdx: number;
+
+            if (normalizedRange) {
+                // Use the selection range
+                startRowIdx = normalizedRange.startRowIdx;
+                endRowIdx = normalizedRange.endRowIdx;
+                startColIdx = normalizedRange.startColIdx;
+                endColIdx = normalizedRange.endColIdx;
+            } else {
+                // No selection, start from focused cell and use clipboard dimensions
+                const focusRowIdx = rowIndexMap.get(focusedCell.rowId);
+                const focusColIdx = columnIndexMap.get(focusedCell.columnId);
+                if (focusRowIdx === undefined || focusColIdx === undefined) return [];
+
+                startRowIdx = focusRowIdx;
+                endRowIdx = Math.min(focusRowIdx + values.length - 1, data.length - 1);
+                startColIdx = focusColIdx;
+                endColIdx = Math.min(
+                    focusColIdx + (values[0]?.length || 1) - 1,
+                    columns.length - 1
+                );
+            }
+
+            // Fill the target range with clipboard values (tiling if needed)
+            for (let rowIdx = startRowIdx; rowIdx <= endRowIdx; rowIdx++) {
+                const row = data[rowIdx];
+                if (!row) continue;
+
+                const rowId = getRowId(row);
+                const valueRowIdx = (rowIdx - startRowIdx) % values.length;
+
+                for (let colIdx = startColIdx; colIdx <= endColIdx; colIdx++) {
+                    const column = columns[colIdx];
+                    if (!column || !column.editable) continue;
+
+                    const valueColIdx = (colIdx - startColIdx) % (values[valueRowIdx]?.length || 1);
+                    let cellValue = values[valueRowIdx]?.[valueColIdx];
+
+                    // Convert value based on column type
+                    if (column.type === 'number' && typeof cellValue === 'string') {
+                        const parsed = parseFloat(cellValue);
+                        cellValue = isNaN(parsed) ? cellValue : parsed;
+                    }
+
+                    edits.push({
+                        rowId,
+                        columnId: column.id,
+                        value: cellValue,
+                    });
+                }
+            }
+
+            return edits;
+        },
+        [
+            focusedCell,
+            selectedCellRange,
+            data,
+            columns,
+            getRowId,
+            rowIndexMap,
+            columnIndexMap,
+            getNormalizedRange,
+        ]
+    );
+
+    // Paste from internal clipboard
+    const pasteClipboard = useCallback((): CellEdit[] => {
+        if (!clipboardData?.values) return [];
+        return createEditsFromValues(clipboardData.values);
+    }, [clipboardData, createEditsFromValues]);
+
+    // Paste from system clipboard (async)
+    const pasteFromSystemClipboard = useCallback(async (): Promise<CellEdit[]> => {
+        if (!focusedCell) return [];
+
+        try {
+            const text = await navigator.clipboard.readText();
+            if (!text) {
+                // Fall back to internal clipboard
+                return pasteClipboard();
+            }
+
+            const values = parseClipboardText(text);
+            return createEditsFromValues(values);
+        } catch {
+            // Clipboard API not available or permission denied, fall back to internal clipboard
+            return pasteClipboard();
+        }
+    }, [focusedCell, pasteClipboard, parseClipboardText, createEditsFromValues]);
+
+    return {
+        focusedCell,
+        setFocusedCell,
+        editingCell,
+        setEditingCell,
+        selectedCellRange,
+        setSelectedCellRange,
+        isDragging,
+        handleCellClick,
+        handleCellMouseDown,
+        handleCellMouseEnter,
+        handleMouseUp,
+        isCellInSelection,
+        getCellSelectionEdge,
+        getSelectedCells,
+        getSelectedCellValues,
+        clearSelection,
+        navigateCell,
+        handleTabNavigation,
+        enterEditMode,
+        exitEditMode,
+        clipboardData,
+        copySelectedCells,
+        pasteClipboard,
+        pasteFromSystemClipboard,
+    };
+}

package/src/index.ts

@@ -23,9 +23,12 @@ export type {
     SpreadsheetToolbarProps,
     SpreadsheetColumnGroupHeaderProps,
     CellPosition,
+    CellRange,
+    CellEdit,
     CellHighlight,
     CellComment,
     SelectionState,
+    SelectionEdge,
     PaginationState,
     RowAction,
     ToolbarMenuItem,

package/src/styles/globals.css

@@ -0,0 +1,3 @@
+@import "tailwindcss";
+
+@source "../**/*.{ts,tsx,css}";