@xcelsior/ui-spreadsheets 1.0.1

package/src/components/SpreadsheetHeader.tsx

@@ -0,0 +1,111 @@
+import type React from 'react';
+import { HiChevronDown, HiChevronUp } from 'react-icons/hi';
+import { cn } from '../utils';
+import type { SpreadsheetHeaderProps } from '../types';
+import { ColumnHeaderActions } from './ColumnHeaderActions';
+
+const cellPaddingCompact = 'px-1.5 py-1';
+const cellPaddingNormal = 'px-2 py-1.5';
+
+/**
+ * SpreadsheetHeader component - A column header cell with sorting, filtering, and pinning capabilities.
+ *
+ * @example
+ * ```tsx
+ * <SpreadsheetHeader
+ *   column={{ id: 'name', label: 'Name', sortable: true }}
+ *   sortConfig={{ columnId: 'name', direction: 'asc' }}
+ *   onClick={() => handleSort('name')}
+ *   onFilterClick={() => setActiveFilter('name')}
+ * />
+ * ```
+ */
+export const SpreadsheetHeader: React.FC<
+    SpreadsheetHeaderProps & { children?: React.ReactNode }
+> = ({
+    column,
+    sortConfig,
+    hasActiveFilter = false,
+    isPinned = false,
+    pinSide,
+    leftOffset = 0,
+    rightOffset = 0,
+    highlightColor,
+    compactMode = false,
+    onClick,
+    onFilterClick,
+    onPinClick,
+    onHighlightClick,
+    className,
+    children,
+}) => {
+    const isSorted = sortConfig?.columnId === column.id;
+    const sortDirection = isSorted ? sortConfig.direction : null;
+
+    const cellPadding = compactMode ? cellPaddingCompact : cellPaddingNormal;
+
+    // Build sticky positioning styles for pinned columns
+    const positionStyles: React.CSSProperties = {};
+    if (isPinned) {
+        positionStyles.position = 'sticky';
+        if (pinSide === 'left') {
+            positionStyles.left = `${leftOffset}px`;
+        } else if (pinSide === 'right') {
+            positionStyles.right = `${rightOffset}px`;
+        }
+    }
+
+    return (
+        <th
+            onClick={column.sortable ? onClick : undefined}
+            className={cn(
+                'border border-gray-200 text-xs font-semibold text-gray-700 sticky group',
+                cellPadding,
+                column.align === 'right' && 'text-right',
+                column.align === 'center' && 'text-center',
+                column.sortable && 'cursor-pointer hover:bg-gray-100',
+                isPinned ? 'z-30' : 'z-20',
+                className
+            )}
+            style={{
+                backgroundColor: highlightColor || 'rgb(243 244 246)', // gray-100
+                minWidth: column.minWidth || column.width,
+                top: 0, // For sticky header
+                ...positionStyles,
+            }}
+        >
+            <div className="flex items-center justify-between gap-1">
+                {/* Label and sort indicator */}
+                <span className="flex-1 flex items-center gap-1">
+                    {column.label}
+                    {isSorted && (
+                        <span className="text-blue-600">
+                            {sortDirection === 'asc' ? (
+                                <HiChevronUp className="h-3 w-3" />
+                            ) : (
+                                <HiChevronDown className="h-3 w-3" />
+                            )}
+                        </span>
+                    )}
+                </span>
+
+                {/* Action buttons using unified ColumnHeaderActions */}
+                <ColumnHeaderActions
+                    enableFiltering={column.filterable}
+                    enableHighlighting={!!onHighlightClick}
+                    enablePinning={column.pinnable !== false}
+                    hasActiveFilter={hasActiveFilter}
+                    hasActiveHighlight={!!highlightColor}
+                    isPinned={isPinned}
+                    onFilterClick={onFilterClick}
+                    onHighlightClick={onHighlightClick}
+                    onPinClick={onPinClick}
+                />
+            </div>
+            {/* Filter dropdown rendered inside th for proper positioning */}
+            {children}
+        </th>
+    );
+};
+
+SpreadsheetHeader.displayName = 'SpreadsheetHeader';

package/src/components/SpreadsheetSettingsModal.tsx

@@ -0,0 +1,555 @@
+import { useState, useEffect } from 'react';
+import { HiX, HiCog, HiViewBoards, HiSortAscending, HiEye } from 'react-icons/hi';
+import type { SpreadsheetColumn, SpreadsheetSortConfig } from '../types';
+
+/**
+ * Settings configuration for the Spreadsheet
+ */
+export interface SpreadsheetSettings {
+    /** Default pinned column IDs */
+    defaultPinnedColumns: string[];
+    /** Default sort configuration */
+    defaultSort: SpreadsheetSortConfig | null;
+    /** Default page size */
+    defaultPageSize: number;
+    /** Default zoom level */
+    defaultZoom: number;
+    /** Whether auto-save is enabled */
+    autoSave: boolean;
+    /** Whether compact view is enabled */
+    compactView: boolean;
+    /** Whether to show row index column */
+    showRowIndex?: boolean;
+    /** Whether row index column is pinned */
+    pinRowIndex?: boolean;
+    /** Row index column highlight color */
+    rowIndexHighlightColor?: string;
+}
+
+export interface SpreadsheetSettingsModalProps {
+    /** Whether the modal is open */
+    isOpen: boolean;
+    /** Callback to close the modal */
+    onClose: () => void;
+    /** Current settings */
+    settings: SpreadsheetSettings;
+    /** Callback to save settings */
+    onSave: (settings: SpreadsheetSettings) => void;
+    /** Available columns for pinning/sorting */
+    columns: SpreadsheetColumn[];
+    /** Title for the modal */
+    title?: string;
+    /** Available page size options */
+    pageSizeOptions?: number[];
+}
+
+const DEFAULT_SETTINGS: SpreadsheetSettings = {
+    defaultPinnedColumns: [],
+    defaultSort: null,
+    defaultPageSize: 25,
+    defaultZoom: 100,
+    autoSave: true,
+    compactView: false,
+    showRowIndex: true,
+    pinRowIndex: false,
+    rowIndexHighlightColor: undefined,
+};
+
+/**
+ * SpreadsheetSettingsModal - A generic settings modal for configuring spreadsheet options.
+ *
+ * @example
+ * ```tsx
+ * <SpreadsheetSettingsModal
+ *   isOpen={showSettings}
+ *   onClose={() => setShowSettings(false)}
+ *   settings={currentSettings}
+ *   onSave={(newSettings) => setSettings(newSettings)}
+ *   columns={columns}
+ *   title="Spreadsheet Settings"
+ * />
+ * ```
+ */
+export const SpreadsheetSettingsModal: React.FC<SpreadsheetSettingsModalProps> = ({
+    isOpen,
+    onClose,
+    settings,
+    onSave,
+    columns,
+    title = 'Spreadsheet Settings',
+    pageSizeOptions = [25, 50, 100, 200],
+}) => {
+    const [activeTab, setActiveTab] = useState<'columns' | 'sorting' | 'display'>('columns');
+    const [localSettings, setLocalSettings] = useState<SpreadsheetSettings>(settings);
+
+    // Update local settings when parent settings change
+    useEffect(() => {
+        setLocalSettings(settings);
+    }, [settings]);
+
+    if (!isOpen) return null;
+
+    const handleSave = () => {
+        onSave(localSettings);
+        onClose();
+    };
+
+    const handleReset = () => {
+        setLocalSettings(DEFAULT_SETTINGS);
+    };
+
+    const togglePinnedColumn = (columnId: string) => {
+        const isPinned = localSettings.defaultPinnedColumns.includes(columnId);
+        if (isPinned) {
+            setLocalSettings({
+                ...localSettings,
+                defaultPinnedColumns: localSettings.defaultPinnedColumns.filter(
+                    (col) => col !== columnId
+                ),
+            });
+        } else {
+            setLocalSettings({
+                ...localSettings,
+                defaultPinnedColumns: [...localSettings.defaultPinnedColumns, columnId],
+            });
+        }
+    };
+
+    const handleSortChange = (columnId: string, direction: 'asc' | 'desc') => {
+        if (columnId === '') {
+            setLocalSettings({
+                ...localSettings,
+                defaultSort: null,
+            });
+        } else {
+            setLocalSettings({
+                ...localSettings,
+                defaultSort: { columnId, direction },
+            });
+        }
+    };
+
+    const handleDisplaySettingChange = (key: keyof SpreadsheetSettings, value: any) => {
+        const newSettings = {
+            ...localSettings,
+            [key]: value,
+        };
+        setLocalSettings(newSettings);
+
+        // Apply changes immediately for visual settings
+        if (key === 'compactView' || key === 'autoSave') {
+            onSave(newSettings);
+        }
+    };
+
+    const tabs = [
+        { id: 'columns' as const, label: 'Pinned Columns', Icon: HiViewBoards },
+        { id: 'sorting' as const, label: 'Default Sorting', Icon: HiSortAscending },
+        { id: 'display' as const, label: 'Display Options', Icon: HiEye },
+    ];
+
+    return (
+        <div
+            className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="settings-modal-title"
+        >
+            {/* Backdrop */}
+            <button
+                type="button"
+                className="absolute inset-0 cursor-default"
+                onClick={onClose}
+                onKeyDown={(e) => e.key === 'Escape' && onClose()}
+                aria-label="Close settings"
+            />
+            <div className="bg-white rounded-lg w-[90%] max-w-[700px] max-h-[90vh] flex flex-col shadow-xl relative z-10">
+                {/* Header */}
+                <div className="px-6 py-5 border-b border-gray-200 flex items-center justify-between">
+                    <div className="flex items-center gap-3">
+                        <HiCog className="h-6 w-6 text-blue-600" />
+                        <h2 id="settings-modal-title" className="text-xl font-bold text-gray-900">
+                            {title}
+                        </h2>
+                    </div>
+                    <button
+                        type="button"
+                        onClick={onClose}
+                        className="p-2 hover:bg-gray-100 rounded-lg transition-colors text-gray-500 hover:text-gray-700"
+                    >
+                        <HiX className="h-5 w-5" />
+                    </button>
+                </div>
+
+                {/* Tabs */}
+                <div className="flex border-b border-gray-200 px-6">
+                    {tabs.map((tab) => (
+                        <button
+                            key={tab.id}
+                            type="button"
+                            onClick={() => setActiveTab(tab.id)}
+                            className={`px-4 py-3 flex items-center gap-2 text-sm font-medium transition-colors border-b-2 ${
+                                activeTab === tab.id
+                                    ? 'text-blue-600 border-blue-600'
+                                    : 'text-gray-500 border-transparent hover:text-gray-700'
+                            }`}
+                        >
+                            <tab.Icon className="h-4 w-4" />
+                            {tab.label}
+                        </button>
+                    ))}
+                </div>
+
+                {/* Content */}
+                <div className="flex-1 overflow-auto p-6">
+                    {/* Pinned Columns Tab */}
+                    {activeTab === 'columns' && (
+                        <div>
+                            <div className="p-4 bg-blue-50 border border-blue-200 rounded-lg mb-4 flex gap-3">
+                                <HiViewBoards className="h-4 w-4 text-blue-600 shrink-0 mt-0.5" />
+                                <div>
+                                    <p className="text-sm font-semibold text-gray-900 mb-1">
+                                        About Pinned Columns
+                                    </p>
+                                    <p className="text-sm text-gray-600">
+                                        Pinned columns stay visible while you scroll horizontally
+                                        through the table.
+                                    </p>
+                                </div>
+                            </div>
+                            <p className="text-sm text-gray-600 mb-4">
+                                Select which columns should be pinned to the left by default.
+                            </p>
+                            <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-2">
+                                {/* Row Index Column - Special handling */}
+                                <button
+                                    type="button"
+                                    onClick={() =>
+                                        setLocalSettings({
+                                            ...localSettings,
+                                            pinRowIndex: !localSettings.pinRowIndex,
+                                        })
+                                    }
+                                    className={`flex items-center gap-2 p-3 rounded-lg border transition-colors text-left ${
+                                        localSettings.pinRowIndex !== false
+                                            ? 'bg-blue-50 border-blue-300 text-blue-700'
+                                            : 'bg-gray-50 border-gray-200 text-gray-700 hover:border-blue-300'
+                                    }`}
+                                >
+                                    <HiViewBoards className="h-4 w-4 shrink-0" />
+                                    <span className="text-sm flex-1 truncate"># (Row Index)</span>
+                                </button>
+                                {columns.map((column) => {
+                                    const isPinned = localSettings.defaultPinnedColumns.includes(
+                                        column.id
+                                    );
+
+                                    return (
+                                        <button
+                                            key={column.id}
+                                            type="button"
+                                            onClick={() => togglePinnedColumn(column.id)}
+                                            className={`flex items-center gap-2 p-3 rounded-lg border transition-colors text-left ${
+                                                isPinned
+                                                    ? 'bg-blue-50 border-blue-300 text-blue-700'
+                                                    : 'bg-gray-50 border-gray-200 text-gray-700 hover:border-blue-300'
+                                            }`}
+                                        >
+                                            <HiViewBoards className="h-4 w-4 shrink-0" />
+                                            <span className="text-sm flex-1 truncate">
+                                                {column.label}
+                                            </span>
+                                        </button>
+                                    );
+                                })}
+                            </div>
+
+                            {/* Row Index Highlight */}
+                            <div className="mt-6 p-4 bg-amber-50 border border-amber-200 rounded-lg">
+                                <p className="text-sm font-semibold text-gray-900 mb-3">
+                                    Row Index Column Highlight
+                                </p>
+                                <p className="text-sm text-gray-600 mb-3">
+                                    Apply a highlight color to the # (row index) column to make it
+                                    stand out.
+                                </p>
+                                <div className="flex items-center gap-2 flex-wrap">
+                                    {[
+                                        '#fef3c7',
+                                        '#dbeafe',
+                                        '#dcfce7',
+                                        '#fce7f3',
+                                        '#f3e8ff',
+                                        '#e0e7ff',
+                                        '#fed7d7',
+                                        '#c6f6d5',
+                                    ].map((color) => (
+                                        <button
+                                            key={color}
+                                            type="button"
+                                            onClick={() =>
+                                                setLocalSettings({
+                                                    ...localSettings,
+                                                    rowIndexHighlightColor:
+                                                        localSettings.rowIndexHighlightColor ===
+                                                        color
+                                                            ? undefined
+                                                            : color,
+                                                })
+                                            }
+                                            className={`w-8 h-8 rounded-lg border-2 transition-all ${
+                                                localSettings.rowIndexHighlightColor === color
+                                                    ? 'border-blue-600 scale-110 ring-2 ring-blue-300'
+                                                    : 'border-gray-300 hover:border-gray-400'
+                                            }`}
+                                            style={{ backgroundColor: color }}
+                                            title={
+                                                localSettings.rowIndexHighlightColor === color
+                                                    ? 'Remove highlight'
+                                                    : 'Apply highlight'
+                                            }
+                                        />
+                                    ))}
+                                    {localSettings.rowIndexHighlightColor && (
+                                        <button
+                                            type="button"
+                                            onClick={() =>
+                                                setLocalSettings({
+                                                    ...localSettings,
+                                                    rowIndexHighlightColor: undefined,
+                                                })
+                                            }
+                                            className="text-sm text-red-600 hover:text-red-700 ml-2 px-2 py-1 rounded hover:bg-red-50"
+                                        >
+                                            Clear
+                                        </button>
+                                    )}
+                                </div>
+                            </div>
+                        </div>
+                    )}
+
+                    {/* Default Sorting Tab */}
+                    {activeTab === 'sorting' && (
+                        <div>
+                            <p className="text-sm text-gray-600 mb-4">
+                                Set the default column sorting when opening the spreadsheet.
+                            </p>
+
+                            <div className="space-y-4">
+                                <div>
+                                    <label className="block text-sm font-medium text-gray-900 mb-2">
+                                        Sort Column
+                                    </label>
+                                    <select
+                                        value={localSettings.defaultSort?.columnId || ''}
+                                        onChange={(e) =>
+                                            handleSortChange(
+                                                e.target.value,
+                                                localSettings.defaultSort?.direction || 'asc'
+                                            )
+                                        }
+                                        className="w-full p-3 text-sm bg-white border border-gray-300 rounded-lg text-gray-900 cursor-pointer focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+                                    >
+                                        <option value="">No default sorting</option>
+                                        {columns
+                                            .filter((col) => col.sortable !== false)
+                                            .map((column) => (
+                                                <option key={column.id} value={column.id}>
+                                                    {column.label}
+                                                </option>
+                                            ))}
+                                    </select>
+                                </div>
+
+                                {localSettings.defaultSort && (
+                                    <div>
+                                        <label className="block text-sm font-medium text-gray-900 mb-2">
+                                            Sort Direction
+                                        </label>
+                                        <select
+                                            value={localSettings.defaultSort.direction}
+                                            onChange={(e) =>
+                                                handleSortChange(
+                                                    localSettings.defaultSort!.columnId,
+                                                    e.target.value as 'asc' | 'desc'
+                                                )
+                                            }
+                                            className="w-full p-3 text-sm bg-white border border-gray-300 rounded-lg text-gray-900 cursor-pointer focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+                                        >
+                                            <option value="asc">Ascending (A → Z, 0 → 9)</option>
+                                            <option value="desc">Descending (Z → A, 9 → 0)</option>
+                                        </select>
+                                    </div>
+                                )}
+                            </div>
+                        </div>
+                    )}
+
+                    {/* Display Options Tab */}
+                    {activeTab === 'display' && (
+                        <div className="space-y-5">
+                            <p className="text-sm text-gray-600">
+                                Customize the display and behavior of the spreadsheet.
+                            </p>
+
+                            {/* Row Index Options */}
+                            <div className="p-4 bg-blue-50 border border-blue-200 rounded-lg">
+                                <p className="text-sm font-semibold text-gray-900 mb-3">
+                                    Row Index Column
+                                </p>
+                                <div className="space-y-3">
+                                    {/* Show Row Index */}
+                                    <label className="flex items-center gap-3 cursor-pointer">
+                                        <input
+                                            type="checkbox"
+                                            checked={localSettings.showRowIndex !== false}
+                                            onChange={(e) =>
+                                                setLocalSettings({
+                                                    ...localSettings,
+                                                    showRowIndex: e.target.checked,
+                                                })
+                                            }
+                                            className="w-4 h-4 cursor-pointer rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+                                        />
+                                        <span className="text-sm text-gray-700">
+                                            Show row index (#) column
+                                        </span>
+                                    </label>
+                                    <p className="text-xs text-gray-500 ml-7">
+                                        Tip: Use the "Pinned Columns" tab to pin and highlight the
+                                        row index column.
+                                    </p>
+                                </div>
+                            </div>
+
+                            {/* Page Size */}
+                            <div>
+                                <label className="block text-sm font-medium text-gray-900 mb-2">
+                                    Default Page Size
+                                </label>
+                                <select
+                                    value={localSettings.defaultPageSize}
+                                    onChange={(e) =>
+                                        setLocalSettings({
+                                            ...localSettings,
+                                            defaultPageSize: parseInt(e.target.value, 10),
+                                        })
+                                    }
+                                    className="w-full p-3 text-sm bg-white border border-gray-300 rounded-lg text-gray-900 cursor-pointer focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+                                >
+                                    {pageSizeOptions.map((size) => (
+                                        <option key={size} value={size}>
+                                            {size} rows
+                                        </option>
+                                    ))}
+                                </select>
+                            </div>
+
+                            {/* Default Zoom */}
+                            <div>
+                                <label className="block text-sm font-medium text-gray-900 mb-2">
+                                    Default Zoom Level: {localSettings.defaultZoom}%
+                                </label>
+                                <input
+                                    type="range"
+                                    min="50"
+                                    max="150"
+                                    step="10"
+                                    value={localSettings.defaultZoom}
+                                    onChange={(e) =>
+                                        setLocalSettings({
+                                            ...localSettings,
+                                            defaultZoom: parseInt(e.target.value, 10),
+                                        })
+                                    }
+                                    className="w-full cursor-pointer"
+                                />
+                                <div className="flex justify-between mt-1 text-xs text-gray-500">
+                                    <span>50%</span>
+                                    <span>150%</span>
+                                </div>
+                            </div>
+
+                            {/* Toggle Options */}
+                            <div className="space-y-3">
+                                {/* Auto Save */}
+                                <label className="flex items-center gap-3 p-4 bg-gray-50 border border-gray-200 rounded-lg cursor-pointer hover:bg-gray-100 transition-colors">
+                                    <input
+                                        type="checkbox"
+                                        checked={localSettings.autoSave}
+                                        onChange={(e) =>
+                                            handleDisplaySettingChange('autoSave', e.target.checked)
+                                        }
+                                        className="w-5 h-5 cursor-pointer rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+                                    />
+                                    <div className="flex-1">
+                                        <div className="text-sm font-medium text-gray-900">
+                                            Auto-save changes
+                                        </div>
+                                        <div className="text-sm text-gray-500 mt-0.5">
+                                            Automatically save changes without confirmation
+                                        </div>
+                                    </div>
+                                </label>
+
+                                {/* Compact View */}
+                                <label className="flex items-center gap-3 p-4 bg-gray-50 border border-gray-200 rounded-lg cursor-pointer hover:bg-gray-100 transition-colors">
+                                    <input
+                                        type="checkbox"
+                                        checked={localSettings.compactView}
+                                        onChange={(e) =>
+                                            handleDisplaySettingChange(
+                                                'compactView',
+                                                e.target.checked
+                                            )
+                                        }
+                                        className="w-5 h-5 cursor-pointer rounded border-gray-300 text-blue-600 focus:ring-blue-500"
+                                    />
+                                    <div className="flex-1">
+                                        <div className="text-sm font-medium text-gray-900">
+                                            Compact view
+                                        </div>
+                                        <div className="text-sm text-gray-500 mt-0.5">
+                                            Reduce padding and spacing to show more rows on screen
+                                        </div>
+                                    </div>
+                                </label>
+                            </div>
+                        </div>
+                    )}
+                </div>
+
+                {/* Footer */}
+                <div className="px-6 py-4 border-t border-gray-200 flex justify-between items-center gap-3">
+                    <button
+                        type="button"
+                        onClick={handleReset}
+                        className="px-4 py-2.5 text-sm font-medium text-red-600 bg-red-50 border border-red-200 rounded-lg hover:bg-red-100 transition-colors"
+                    >
+                        Reset to Defaults
+                    </button>
+
+                    <div className="flex gap-2">
+                        <button
+                            type="button"
+                            onClick={onClose}
+                            className="px-4 py-2.5 text-sm font-medium text-gray-700 bg-gray-100 border border-gray-200 rounded-lg hover:bg-gray-200 transition-colors"
+                        >
+                            Cancel
+                        </button>
+                        <button
+                            type="button"
+                            onClick={handleSave}
+                            className="px-4 py-2.5 text-sm font-medium text-white bg-blue-600 rounded-lg hover:bg-blue-700 transition-colors"
+                        >
+                            Save Settings
+                        </button>
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+};
+
+SpreadsheetSettingsModal.displayName = 'SpreadsheetSettingsModal';