@xcelsior/ui-spreadsheets 1.0.1

package/src/hooks/useSpreadsheetKeyboardShortcuts.ts

@@ -0,0 +1,149 @@
+import { useEffect, useState } from 'react';
+
+export interface KeyboardShortcutHandler {
+    key: string;
+    modifiers?: {
+        meta?: boolean;
+        ctrl?: boolean;
+        shift?: boolean;
+        alt?: boolean;
+    };
+    handler: () => void;
+    description?: string;
+}
+
+export interface UseSpreadsheetKeyboardShortcutsOptions {
+    /** Handlers for undo action */
+    onUndo?: () => void;
+    /** Handler for redo action */
+    onRedo?: () => void;
+    /** Handler for escape key - receives context of what to close */
+    onEscape?: () => void;
+    /** Whether the shortcuts modal is open */
+    isShortcutsModalOpen?: boolean;
+    /** Additional custom shortcuts */
+    customShortcuts?: KeyboardShortcutHandler[];
+    /** Whether shortcuts are enabled */
+    enabled?: boolean;
+}
+
+export interface UseSpreadsheetKeyboardShortcutsReturn {
+    // Shortcuts modal state
+    showKeyboardShortcuts: boolean;
+    setShowKeyboardShortcuts: (show: boolean) => void;
+
+    // OS detection for display
+    isMac: boolean;
+    modifierKey: string;
+
+    // Shortcut definitions for display
+    shortcuts: {
+        general: Array<{ label: string; keys: string[] }>;
+        rowSelection: Array<{ label: string; keys: string[] }>;
+        editing: Array<{ label: string; keys: string[] }>;
+        rowActions: Array<{ label: string; description: string }>;
+    };
+}
+
+export function useSpreadsheetKeyboardShortcuts({
+    onUndo,
+    onRedo,
+    onEscape,
+    customShortcuts = [],
+    enabled = true,
+}: UseSpreadsheetKeyboardShortcutsOptions = {}): UseSpreadsheetKeyboardShortcutsReturn {
+    const [showKeyboardShortcuts, setShowKeyboardShortcuts] = useState(false);
+
+    // Detect OS for keyboard shortcuts display
+    const isMac =
+        typeof navigator !== 'undefined' && /Mac|iPhone|iPod|iPad/.test(navigator.platform);
+    const modifierKey = isMac ? '⌘' : 'Ctrl';
+
+    // Keyboard event handler
+    useEffect(() => {
+        if (!enabled) return;
+
+        const handleKeyDown = (event: KeyboardEvent) => {
+            // Escape key
+            if (event.key === 'Escape') {
+                if (showKeyboardShortcuts) {
+                    setShowKeyboardShortcuts(false);
+                } else {
+                    onEscape?.();
+                }
+                return;
+            }
+
+            // Cmd/Ctrl + / : Toggle keyboard shortcuts modal
+            if ((event.metaKey || event.ctrlKey) && event.key === '/') {
+                event.preventDefault();
+                setShowKeyboardShortcuts((prev) => !prev);
+                return;
+            }
+
+            // Cmd/Ctrl+Z: Undo (without shift)
+            if ((event.metaKey || event.ctrlKey) && event.key === 'z' && !event.shiftKey) {
+                event.preventDefault();
+                onUndo?.();
+                return;
+            }
+
+            // Cmd/Ctrl+Shift+Z: Redo
+            if ((event.metaKey || event.ctrlKey) && event.shiftKey && event.key === 'z') {
+                event.preventDefault();
+                onRedo?.();
+                return;
+            }
+
+            // Custom shortcuts
+            for (const shortcut of customShortcuts) {
+                const modifiersMatch =
+                    (!shortcut.modifiers?.meta || event.metaKey) &&
+                    (!shortcut.modifiers?.ctrl || event.ctrlKey) &&
+                    (!shortcut.modifiers?.shift || event.shiftKey) &&
+                    (!shortcut.modifiers?.alt || event.altKey);
+
+                if (event.key === shortcut.key && modifiersMatch) {
+                    event.preventDefault();
+                    shortcut.handler();
+                    return;
+                }
+            }
+        };
+
+        document.addEventListener('keydown', handleKeyDown);
+        return () => document.removeEventListener('keydown', handleKeyDown);
+    }, [enabled, showKeyboardShortcuts, onUndo, onRedo, onEscape, customShortcuts]);
+
+    // Shortcut definitions for display in modal
+    const shortcuts = {
+        general: [
+            { label: 'Show keyboard shortcuts', keys: [modifierKey, '/'] },
+            { label: 'Close modal / Clear selection', keys: ['Escape'] },
+        ],
+        rowSelection: [
+            { label: 'Select single row', keys: ['Click row number'] },
+            { label: 'Select multiple rows', keys: [modifierKey, 'Click row number'] },
+            { label: 'Select range of rows', keys: ['Shift', 'Click row number'] },
+        ],
+        editing: [
+            { label: 'Undo', keys: [modifierKey, 'Z'] },
+            { label: 'Redo', keys: [modifierKey, 'Shift', 'Z'] },
+            { label: 'Confirm cell edit', keys: ['Enter'] },
+            { label: 'Cancel cell edit', keys: ['Escape'] },
+        ],
+        rowActions: [
+            { label: 'Duplicate row', description: 'Click duplicate icon' },
+            { label: 'Highlight row', description: 'Click highlight icon' },
+            { label: 'Add row comment', description: 'Click comment icon' },
+        ],
+    };
+
+    return {
+        showKeyboardShortcuts,
+        setShowKeyboardShortcuts,
+        isMac,
+        modifierKey,
+        shortcuts,
+    };
+}

package/src/hooks/useSpreadsheetPinning.ts

@@ -0,0 +1,203 @@
+import { useCallback, useMemo, 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 = 56;
+
+export interface UseSpreadsheetPinningOptions<T> {
+    columns: SpreadsheetColumn<T>[];
+    columnGroups?: SpreadsheetColumnGroup[];
+    showRowIndex?: boolean;
+    defaultPinnedColumns?: string[];
+    defaultPinRowIndex?: boolean;
+}
+
+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;
+    handleToggleRowIndexPin: () => void;
+    handleToggleGroupCollapse: (groupId: string) => void;
+
+    // Offset calculations
+    getColumnLeftOffset: (columnId: string) => number;
+    getRowIndexLeftOffset: () => number;
+
+    // Utility
+    isColumnPinned: (columnId: string) => boolean;
+    getColumnPinSide: (columnId: string) => 'left' | 'right' | undefined;
+}
+
+export function useSpreadsheetPinning<T>({
+    columns,
+    columnGroups,
+    showRowIndex = true,
+    defaultPinnedColumns = [],
+    defaultPinRowIndex = false,
+}: UseSpreadsheetPinningOptions<T>): UseSpreadsheetPinningReturn<T> {
+    // Initialize pinned columns from defaults
+    const [pinnedColumns, setPinnedColumns] = useState<Map<string, 'left' | 'right'>>(() => {
+        const map = new Map<string, 'left' | 'right'>();
+        defaultPinnedColumns.forEach((col) => {
+            map.set(col, 'left');
+        });
+        return map;
+    });
+
+    const [isRowIndexPinned, setIsRowIndexPinned] = useState(defaultPinRowIndex);
+    const [collapsedGroups, setCollapsedGroups] = useState<Set<string>>(new Set());
+
+    // Toggle column pin
+    const handleTogglePin = useCallback((columnId: string) => {
+        setPinnedColumns((prev) => {
+            const newMap = new Map(prev);
+            if (newMap.has(columnId)) {
+                newMap.delete(columnId);
+            } else {
+                newMap.set(columnId, 'left');
+            }
+            return newMap;
+        });
+    }, []);
+
+    // Toggle row index pin
+    const handleToggleRowIndexPin = useCallback(() => {
+        setIsRowIndexPinned((prev) => !prev);
+    }, []);
+
+    // Toggle group collapse
+    const handleToggleGroupCollapse = useCallback((groupId: string) => {
+        setCollapsedGroups((prev) => {
+            const newSet = new Set(prev);
+            if (newSet.has(groupId)) {
+                newSet.delete(groupId);
+            } else {
+                newSet.add(groupId);
+            }
+            return newSet;
+        });
+    }, []);
+
+    // Calculate visible columns based on groups, collapse state, and pinning order
+    const visibleColumns = useMemo(() => {
+        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, return result as-is to preserve original order
+        if (pinnedColumns.size === 0) {
+            return result;
+        }
+
+        // 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(([, side]) => side === 'left')
+            .map(([id]) => id);
+        const pinnedRightIds = Array.from(pinnedColumns.entries())
+            .filter(([, side]) => side === 'right')
+            .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);
+            }
+        }
+
+        // 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));
+
+        return [...leftPinned, ...unpinned, ...rightPinned];
+    }, [columns, columnGroups, collapsedGroups, pinnedColumns]);
+
+    // Get left offset for row index column
+    const getRowIndexLeftOffset = useCallback((): number => {
+        return 0;
+    }, []);
+
+    // Calculate column offset for sticky positioning
+    const getColumnLeftOffset = useCallback(
+        (columnId: string): number => {
+            const pinnedLeft = Array.from(pinnedColumns.entries())
+                .filter(([, side]) => side === 'left')
+                .map(([id]) => id);
+            const index = pinnedLeft.indexOf(columnId);
+
+            // Base offset includes the row index column if shown and pinned
+            const baseOffset = showRowIndex && isRowIndexPinned ? 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]);
+                offset += col?.width || col?.minWidth || 100;
+            }
+            return offset;
+        },
+        [pinnedColumns, columns, showRowIndex, isRowIndexPinned]
+    );
+
+    // Check if column is pinned
+    const isColumnPinned = useCallback(
+        (columnId: string): boolean => {
+            return pinnedColumns.has(columnId);
+        },
+        [pinnedColumns]
+    );
+
+    // Get column pin side
+    const getColumnPinSide = useCallback(
+        (columnId: string): 'left' | 'right' | undefined => {
+            return pinnedColumns.get(columnId);
+        },
+        [pinnedColumns]
+    );
+
+    return {
+        pinnedColumns,
+        isRowIndexPinned,
+        collapsedGroups,
+        visibleColumns,
+        handleTogglePin,
+        handleToggleRowIndexPin,
+        handleToggleGroupCollapse,
+        getColumnLeftOffset,
+        getRowIndexLeftOffset,
+        isColumnPinned,
+        getColumnPinSide,
+    };
+}

package/src/hooks/useSpreadsheetUndoRedo.ts

@@ -0,0 +1,167 @@
+import { useCallback, useState } from 'react';
+
+export interface UseSpreadsheetUndoRedoOptions {
+    /** Whether undo/redo is enabled */
+    enabled?: boolean;
+    /** Maximum stack size (default: 50) */
+    maxStackSize?: number;
+    /** Auto-save mode */
+    autoSave?: boolean;
+}
+
+export interface UseSpreadsheetUndoRedoReturn<TSnapshot> {
+    // State
+    undoStack: TSnapshot[];
+    redoStack: TSnapshot[];
+    hasUnsavedChanges: boolean;
+    saveStatus: 'saved' | 'saving' | 'unsaved' | 'error';
+
+    // Computed
+    canUndo: boolean;
+    canRedo: boolean;
+    undoCount: number;
+    redoCount: number;
+
+    // Actions
+    handleUndo: () => TSnapshot | null;
+    handleRedo: () => TSnapshot | null;
+    handleSave: () => void;
+    pushToUndoStack: (snapshot: TSnapshot) => void;
+    clearStacks: () => void;
+
+    // For tracking changes
+    markAsChanged: () => void;
+    markAsSaved: () => void;
+}
+
+export function useSpreadsheetUndoRedo<TSnapshot>({
+    enabled = true,
+    maxStackSize = 50,
+    autoSave = true,
+}: UseSpreadsheetUndoRedoOptions): UseSpreadsheetUndoRedoReturn<TSnapshot> {
+    const [undoStack, setUndoStack] = useState<TSnapshot[]>([]);
+    const [redoStack, setRedoStack] = useState<TSnapshot[]>([]);
+    const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
+    const [saveStatus, setSaveStatus] = useState<'saved' | 'saving' | 'unsaved' | 'error'>('saved');
+
+    // Push current state to undo stack before making changes
+    const pushToUndoStack = useCallback(
+        (snapshot: TSnapshot) => {
+            if (!enabled) return;
+
+            setUndoStack((prev) => {
+                const newStack = [...prev, snapshot];
+                // Limit stack size
+                if (newStack.length > maxStackSize) {
+                    return newStack.slice(-maxStackSize);
+                }
+                return newStack;
+            });
+            // Clear redo stack when new action is performed
+            setRedoStack([]);
+        },
+        [enabled, maxStackSize]
+    );
+
+    // Undo action - returns the state to restore
+    const handleUndo = useCallback((): TSnapshot | null => {
+        if (!enabled || undoStack.length === 0) return null;
+
+        const previousSnapshot = undoStack[undoStack.length - 1];
+
+        // Pop from undo stack
+        setUndoStack((prev) => prev.slice(0, -1));
+
+        // Move snapshot to redo stack
+        setRedoStack((prev) => {
+            const newStack = [...prev, previousSnapshot];
+            if (newStack.length > maxStackSize) {
+                return newStack.slice(-maxStackSize);
+            }
+            return newStack;
+        });
+
+        return previousSnapshot;
+    }, [enabled, undoStack, maxStackSize]);
+
+    // Redo action - returns the state to restore
+    const handleRedo = useCallback((): TSnapshot | null => {
+        if (!enabled || redoStack.length === 0) return null;
+
+        const nextSnapshot = redoStack[redoStack.length - 1];
+
+        // Pop from redo stack
+        setRedoStack((prev) => prev.slice(0, -1));
+
+        // Move snapshot back to undo stack
+        setUndoStack((prev) => {
+            const newStack = [...prev, nextSnapshot];
+            if (newStack.length > maxStackSize) {
+                return newStack.slice(-maxStackSize);
+            }
+            return newStack;
+        });
+
+        return nextSnapshot;
+    }, [enabled, redoStack, maxStackSize]);
+
+    // Save action
+    const handleSave = useCallback(() => {
+        if (!hasUnsavedChanges) return;
+
+        setSaveStatus('saving');
+        // Simulate save delay
+        setTimeout(() => {
+            setSaveStatus('saved');
+            setHasUnsavedChanges(false);
+        }, 500);
+    }, [hasUnsavedChanges]);
+
+    // Mark as changed (call after data modification)
+    const markAsChanged = useCallback(() => {
+        setHasUnsavedChanges(true);
+        if (autoSave) {
+            setSaveStatus('saving');
+            setTimeout(() => setSaveStatus('saved'), 500);
+        } else {
+            setSaveStatus('unsaved');
+        }
+    }, [autoSave]);
+
+    // Mark as saved
+    const markAsSaved = useCallback(() => {
+        setHasUnsavedChanges(false);
+        setSaveStatus('saved');
+    }, []);
+
+    // Clear both stacks
+    const clearStacks = useCallback(() => {
+        setUndoStack([]);
+        setRedoStack([]);
+    }, []);
+
+    return {
+        // State
+        undoStack,
+        redoStack,
+        hasUnsavedChanges,
+        saveStatus,
+
+        // Computed
+        canUndo: enabled && undoStack.length > 0,
+        canRedo: enabled && redoStack.length > 0,
+        undoCount: undoStack.length,
+        redoCount: redoStack.length,
+
+        // Actions
+        handleUndo,
+        handleRedo,
+        handleSave,
+        pushToUndoStack,
+        clearStacks,
+
+        // Change tracking
+        markAsChanged,
+        markAsSaved,
+    };
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// Main Spreadsheet component
+export { Spreadsheet } from './components/Spreadsheet';
+
+// Sub-components
+export { SpreadsheetCell } from './components/SpreadsheetCell';
+export { SpreadsheetHeader } from './components/SpreadsheetHeader';
+export { SpreadsheetFilterDropdown } from './components/SpreadsheetFilterDropdown';
+export { SpreadsheetToolbar } from './components/SpreadsheetToolbar';
+export { SpreadsheetSettingsModal } from './components/SpreadsheetSettingsModal';
+export type { SpreadsheetSettings } from './components/SpreadsheetSettingsModal';
+
+// Types
+export type {
+    SpreadsheetProps,
+    SpreadsheetColumn,
+    SpreadsheetColumnGroup,
+    SpreadsheetSortConfig,
+    SpreadsheetColumnFilter,
+    SpreadsheetState,
+    SpreadsheetCellProps,
+    SpreadsheetHeaderProps,
+    SpreadsheetFilterDropdownProps,
+    SpreadsheetToolbarProps,
+    SpreadsheetColumnGroupHeaderProps,
+    CellPosition,
+    CellHighlight,
+    CellComment,
+    SelectionState,
+    PaginationState,
+    RowAction,
+} from './types';