@xcelsior/ui-spreadsheets 1.0.1

package/src/components/SpreadsheetToolbar.tsx

@@ -0,0 +1,346 @@
+import React from 'react';
+import {
+    HiCheck,
+    HiCog,
+    HiDotsVertical,
+    HiDownload,
+    HiFilter,
+    HiOutlineQuestionMarkCircle,
+    HiReply,
+    HiX,
+    HiZoomIn,
+    HiZoomOut,
+} from 'react-icons/hi';
+import { cn } from '../utils';
+import type { SpreadsheetToolbarProps } from '../types';
+
+/**
+ * SpreadsheetToolbar component - Top toolbar with zoom controls, undo/redo, filters, and actions.
+ *
+ * @example
+ * ```tsx
+ * <SpreadsheetToolbar
+ *   zoom={100}
+ *   canUndo={true}
+ *   canRedo={false}
+ *   selectedRowCount={3}
+ *   showFilters={false}
+ *   hasUnsavedChanges={false}
+ *   saveStatus="saved"
+ *   autoSave={true}
+ *   onZoomIn={() => setZoom(zoom + 10)}
+ *   onZoomOut={() => setZoom(zoom - 10)}
+ *   onZoomReset={() => setZoom(100)}
+ *   onUndo={handleUndo}
+ *   onRedo={handleRedo}
+ *   onToggleFilters={() => setShowFilters(!showFilters)}
+ *   onClearSelection={() => setSelectedRows(new Set())}
+ * />
+ * ```
+ */
+export const SpreadsheetToolbar: React.FC<SpreadsheetToolbarProps> = ({
+    zoom,
+    canUndo,
+    canRedo,
+    undoCount = 0,
+    redoCount = 0,
+    selectedRowCount,
+    hasUnsavedChanges,
+    saveStatus,
+    autoSave,
+    summary,
+    onZoomIn,
+    onZoomOut,
+    onZoomReset,
+    onUndo,
+    onRedo,
+    onClearSelection,
+    onSave,
+    onExport,
+    onSettings,
+    onShowShortcuts,
+    hasActiveFilters,
+    onClearFilters,
+    className,
+}) => {
+    const [showMoreMenu, setShowMoreMenu] = React.useState(false);
+    const menuRef = React.useRef<HTMLDivElement>(null);
+
+    // Close menu on outside click
+    React.useEffect(() => {
+        const handleClickOutside = (event: MouseEvent) => {
+            if (menuRef.current && !menuRef.current.contains(event.target as Node)) {
+                setShowMoreMenu(false);
+            }
+        };
+
+        document.addEventListener('mousedown', handleClickOutside);
+        return () => document.removeEventListener('mousedown', handleClickOutside);
+    }, []);
+
+    const buttonBaseClasses =
+        'p-1.5 rounded transition-colors disabled:opacity-50 disabled:cursor-not-allowed';
+
+    const getSaveStatusDisplay = () => {
+        switch (saveStatus) {
+            case 'saved':
+                return {
+                    text: '✓ All changes saved',
+                    className: 'text-gray-500',
+                };
+            case 'saving':
+                return {
+                    text: '⟳ Saving...',
+                    className: 'text-amber-500',
+                };
+            case 'unsaved':
+                return {
+                    text: '● Unsaved changes',
+                    className: 'text-amber-500',
+                };
+            case 'error':
+                return {
+                    text: '⚠ Error saving',
+                    className: 'text-red-500',
+                };
+            default:
+                return null;
+        }
+    };
+
+    const saveStatusDisplay = getSaveStatusDisplay();
+
+    const getSummaryVariantClasses = (variant?: string) => {
+        switch (variant) {
+            case 'success':
+                return 'bg-green-50 border-green-200 text-green-700';
+            case 'danger':
+                return 'bg-red-50 border-red-200 text-red-700';
+            case 'warning':
+                return 'bg-amber-50 border-amber-200 text-amber-700';
+            default:
+                return 'bg-blue-50 border-blue-200 text-blue-700';
+        }
+    };
+
+    return (
+        <div
+            className={cn(
+                'flex flex-wrap items-center justify-between gap-2 px-4 py-2 border-b border-gray-200 bg-white',
+                className
+            )}
+        >
+            {/* Left section: Primary actions */}
+            <div className="flex items-center gap-2">
+                {/* Undo/Redo buttons */}
+                <div className="flex items-center gap-1">
+                    <button
+                        type={'button'}
+                        onClick={onUndo}
+                        disabled={!canUndo}
+                        className={cn(
+                            buttonBaseClasses,
+                            canUndo
+                                ? 'bg-gray-100 text-gray-700 hover:bg-gray-200'
+                                : 'bg-gray-50 text-gray-400'
+                        )}
+                        title={`Undo (${undoCount} changes)`}
+                    >
+                        <HiReply className="h-4 w-4" />
+                    </button>
+                    <button
+                        type={'button'}
+                        onClick={onRedo}
+                        disabled={!canRedo}
+                        className={cn(
+                            buttonBaseClasses,
+                            canRedo
+                                ? 'bg-gray-100 text-gray-700 hover:bg-gray-200'
+                                : 'bg-gray-50 text-gray-400'
+                        )}
+                        title={`Redo (${redoCount} changes)`}
+                        style={{ transform: 'scaleX(-1)' }}
+                    >
+                        <HiReply className="h-4 w-4" />
+                    </button>
+                </div>
+
+                {/* Zoom controls */}
+                <div className="flex items-center gap-1 px-1.5 py-1 bg-gray-100 rounded">
+                    <button
+                        type={'button'}
+                        onClick={onZoomOut}
+                        className="p-1 hover:bg-white rounded"
+                        title="Zoom out"
+                    >
+                        <HiZoomOut className="h-4 w-4 text-gray-600" />
+                    </button>
+                    <button
+                        type={'button'}
+                        onClick={onZoomReset}
+                        className="px-2 py-0.5 hover:bg-white rounded text-xs min-w-[45px] text-center text-gray-600"
+                        title="Reset zoom"
+                    >
+                        {zoom}%
+                    </button>
+                    <button
+                        type={'button'}
+                        onClick={onZoomIn}
+                        className="p-1 hover:bg-white rounded"
+                        title="Zoom in"
+                    >
+                        <HiZoomIn className="h-4 w-4 text-gray-600" />
+                    </button>
+                </div>
+            </div>
+
+            {/* Center section: Status indicators */}
+            <div className="flex items-center gap-2 flex-1 min-w-0">
+                {/* Selected rows indicator */}
+                {selectedRowCount > 0 && (
+                    <div className="flex items-center gap-2 px-2.5 py-1.5 bg-blue-600 text-white rounded">
+                        <span className="text-xs font-medium whitespace-nowrap">
+                            {selectedRowCount} row{selectedRowCount !== 1 ? 's' : ''} selected
+                        </span>
+                        <button
+                            type={'button'}
+                            onClick={onClearSelection}
+                            className="p-0.5 hover:bg-blue-700 rounded"
+                            title="Clear selection"
+                        >
+                            <HiX className="h-3 w-3" />
+                        </button>
+                    </div>
+                )}
+
+                {/* Clear filters button */}
+                {hasActiveFilters && onClearFilters && (
+                    <div className="flex items-center gap-2 px-2.5 py-1.5 bg-amber-500 text-white rounded">
+                        <HiFilter className="h-3.5 w-3.5" />
+                        <span className="text-xs font-medium whitespace-nowrap">
+                            Filters active
+                        </span>
+                        <button
+                            type={'button'}
+                            onClick={onClearFilters}
+                            className="p-0.5 hover:bg-amber-600 rounded"
+                            title="Clear all filters"
+                        >
+                            <HiX className="h-3 w-3" />
+                        </button>
+                    </div>
+                )}
+
+                {/* Summary badge */}
+                {summary && (
+                    <div
+                        className={cn(
+                            'flex items-center gap-2 px-2.5 py-1.5 rounded border text-xs',
+                            getSummaryVariantClasses(summary.variant)
+                        )}
+                    >
+                        <span className="font-semibold whitespace-nowrap">{summary.label}:</span>
+                        <span className="font-bold whitespace-nowrap">{summary.value}</span>
+                    </div>
+                )}
+            </div>
+
+            {/* Right section: Action buttons */}
+            <div className="flex items-center gap-2">
+                {/* Save status */}
+                {saveStatusDisplay && (
+                    <span
+                        className={cn(
+                            'text-xs flex items-center gap-1',
+                            saveStatusDisplay.className
+                        )}
+                    >
+                        {saveStatusDisplay.text}
+                    </span>
+                )}
+
+                {/* Manual save button (when auto-save is off) */}
+                {!autoSave && onSave && (
+                    <button
+                        type={'button'}
+                        onClick={onSave}
+                        disabled={!hasUnsavedChanges}
+                        className={cn(
+                            'px-3 py-1.5 text-xs bg-blue-600 text-white rounded hover:bg-blue-700 transition-colors flex items-center gap-1.5',
+                            'disabled:opacity-50 disabled:cursor-not-allowed disabled:hover:bg-blue-600'
+                        )}
+                    >
+                        <HiCheck className="h-3.5 w-3.5" />
+                        Save
+                    </button>
+                )}
+
+                {/* More menu dropdown */}
+                <div className="relative" ref={menuRef}>
+                    <button
+                        type={'button'}
+                        onClick={() => setShowMoreMenu(!showMoreMenu)}
+                        className="px-2.5 py-1.5 bg-gray-100 text-gray-700 rounded hover:bg-gray-200 transition-colors flex items-center gap-1.5 text-xs"
+                        title="More actions"
+                    >
+                        <HiDotsVertical className="h-3.5 w-3.5" />
+                        <span className="hidden lg:inline">More</span>
+                    </button>
+
+                    {/* Dropdown Menu */}
+                    {showMoreMenu && (
+                        <div className="absolute right-0 top-full mt-1 bg-white border border-gray-200 shadow-lg rounded py-1 min-w-[180px] z-20">
+                            {onSettings && (
+                                <button
+                                    type={'button'}
+                                    onClick={() => {
+                                        onSettings();
+                                        setShowMoreMenu(false);
+                                    }}
+                                    className="w-full px-3 py-2 text-left hover:bg-gray-50 flex items-center gap-2 text-xs transition-colors"
+                                >
+                                    <HiCog className="h-3.5 w-3.5 text-gray-500" />
+                                    <span className="text-gray-700">Settings</span>
+                                </button>
+                            )}
+
+                            {onShowShortcuts && (
+                                <button
+                                    type={'button'}
+                                    onClick={() => {
+                                        onShowShortcuts();
+                                        setShowMoreMenu(false);
+                                    }}
+                                    className="w-full px-3 py-2 text-left hover:bg-gray-50 flex items-center gap-2 text-xs transition-colors"
+                                >
+                                    <HiOutlineQuestionMarkCircle className="h-3.5 w-3.5 text-gray-500" />
+                                    <span className="text-gray-700">Keyboard Shortcuts</span>
+                                </button>
+                            )}
+
+                            {(onSettings || onShowShortcuts) && onExport && (
+                                <div className="border-t border-gray-100 my-1" />
+                            )}
+
+                            {onExport && (
+                                <button
+                                    type={'button'}
+                                    onClick={() => {
+                                        onExport();
+                                        setShowMoreMenu(false);
+                                    }}
+                                    className="w-full px-3 py-2 text-left hover:bg-gray-50 flex items-center gap-2 text-xs transition-colors"
+                                >
+                                    <HiDownload className="h-3.5 w-3.5 text-gray-500" />
+                                    <span className="text-gray-700">Export</span>
+                                </button>
+                            )}
+                        </div>
+                    )}
+                </div>
+            </div>
+        </div>
+    );
+};
+
+SpreadsheetToolbar.displayName = 'SpreadsheetToolbar';

package/src/hooks/index.ts

@@ -0,0 +1,40 @@
+export {
+    useSpreadsheetFiltering,
+    type UseSpreadsheetFilteringOptions,
+    type UseSpreadsheetFilteringReturn,
+} from './useSpreadsheetFiltering';
+
+export {
+    useSpreadsheetHighlighting,
+    HIGHLIGHT_COLORS,
+    ROW_INDEX_COLUMN_ID,
+    type UseSpreadsheetHighlightingOptions,
+    type UseSpreadsheetHighlightingReturn,
+} from './useSpreadsheetHighlighting';
+
+export {
+    useSpreadsheetPinning,
+    ROW_INDEX_COLUMN_WIDTH,
+    ROW_INDEX_COLUMN_ID as PINNING_ROW_INDEX_COLUMN_ID,
+    type UseSpreadsheetPinningOptions,
+    type UseSpreadsheetPinningReturn,
+} from './useSpreadsheetPinning';
+
+export {
+    useSpreadsheetComments,
+    type UseSpreadsheetCommentsOptions,
+    type UseSpreadsheetCommentsReturn,
+} from './useSpreadsheetComments';
+
+export {
+    useSpreadsheetUndoRedo,
+    type UseSpreadsheetUndoRedoOptions,
+    type UseSpreadsheetUndoRedoReturn,
+} from './useSpreadsheetUndoRedo';
+
+export {
+    useSpreadsheetKeyboardShortcuts,
+    type UseSpreadsheetKeyboardShortcutsOptions,
+    type UseSpreadsheetKeyboardShortcutsReturn,
+    type KeyboardShortcutHandler,
+} from './useSpreadsheetKeyboardShortcuts';

package/src/hooks/useSpreadsheetComments.ts

@@ -0,0 +1,132 @@
+import { useCallback, useState } from 'react';
+import type { CellComment } from '../types';
+
+export interface UseSpreadsheetCommentsOptions {
+    /** External row comments (controlled mode) */
+    externalRowComments?: CellComment[];
+    /** Callback when a row comment is added (controlled mode) */
+    onAddRowComment?: (rowId: string | number, comment: string) => void;
+}
+
+export interface UseSpreadsheetCommentsReturn {
+    // Comments data
+    rowComments: CellComment[];
+    getRowComments: (rowId: string | number) => CellComment[];
+    getUnresolvedCommentCount: (rowId: string | number) => number;
+
+    // Add comment modal state
+    commentModalRow: string | number | null;
+    setCommentModalRow: (rowId: string | number | null) => void;
+    commentText: string;
+    setCommentText: (text: string) => void;
+
+    // View comments modal state
+    viewCommentsRow: string | number | null;
+    setViewCommentsRow: (rowId: string | number | null) => void;
+
+    // Actions
+    handleAddRowComment: (rowId: string | number) => void;
+    handleToggleCommentResolved: (commentId: string) => void;
+
+    // Utility
+    hasComments: (rowId: string | number) => boolean;
+}
+
+export function useSpreadsheetComments({
+    externalRowComments,
+    onAddRowComment,
+}: UseSpreadsheetCommentsOptions = {}): UseSpreadsheetCommentsReturn {
+    // Internal comments state
+    const [rowCommentsInternal, setRowCommentsInternal] = useState<CellComment[]>([]);
+
+    // Modal states
+    const [commentModalRow, setCommentModalRow] = useState<string | number | null>(null);
+    const [commentText, setCommentText] = useState('');
+    const [viewCommentsRow, setViewCommentsRow] = useState<string | number | null>(null);
+
+    // Use external comments if provided, otherwise use internal
+    const rowComments = externalRowComments || rowCommentsInternal;
+
+    // Get comments for a specific row
+    const getRowComments = useCallback(
+        (rowId: string | number): CellComment[] => {
+            return rowComments.filter((c) => c.rowId === rowId && !c.columnId);
+        },
+        [rowComments]
+    );
+
+    // Get unresolved comment count for a row
+    const getUnresolvedCommentCount = useCallback(
+        (rowId: string | number): number => {
+            return rowComments.filter((c) => c.rowId === rowId && !c.columnId && !c.resolved)
+                .length;
+        },
+        [rowComments]
+    );
+
+    // Check if row has comments
+    const hasComments = useCallback(
+        (rowId: string | number): boolean => {
+            return rowComments.some((c) => c.rowId === rowId && !c.columnId);
+        },
+        [rowComments]
+    );
+
+    // Add a row comment
+    const handleAddRowComment = useCallback(
+        (rowId: string | number) => {
+            if (!commentText.trim()) return;
+
+            if (onAddRowComment) {
+                // Controlled mode
+                onAddRowComment(rowId, commentText);
+            } else {
+                // Uncontrolled mode
+                setRowCommentsInternal((prev) => [
+                    ...prev,
+                    {
+                        id: `comment-${Date.now()}`,
+                        rowId,
+                        text: commentText,
+                        timestamp: new Date(),
+                        resolved: false,
+                    },
+                ]);
+            }
+            setCommentText('');
+            setCommentModalRow(null);
+        },
+        [commentText, onAddRowComment]
+    );
+
+    // Toggle comment resolved status
+    const handleToggleCommentResolved = useCallback((commentId: string) => {
+        setRowCommentsInternal((prev) =>
+            prev.map((c) => (c.id === commentId ? { ...c, resolved: !c.resolved } : c))
+        );
+    }, []);
+
+    return {
+        // Comments data
+        rowComments,
+        getRowComments,
+        getUnresolvedCommentCount,
+
+        // Add comment modal state
+        commentModalRow,
+        setCommentModalRow,
+        commentText,
+        setCommentText,
+
+        // View comments modal state
+        viewCommentsRow,
+        setViewCommentsRow,
+
+        // Actions
+        handleAddRowComment,
+        handleToggleCommentResolved,
+
+        // Utility
+        hasComments,
+    };
+}