@xcelsior/ui-spreadsheets 1.0.1

package/dist/index.d.mts

@@ -0,0 +1,687 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+/**
+ * Column definition for the spreadsheet
+ */
+interface SpreadsheetColumn<T = any> {
+    /** Unique identifier for the column */
+    id: string;
+    /** Display label for the column header */
+    label: string;
+    /** Width of the column in pixels */
+    width?: number;
+    /** Minimum width of the column in pixels */
+    minWidth?: number;
+    /** Text alignment */
+    align?: 'left' | 'center' | 'right';
+    /** Whether the column is sortable */
+    sortable?: boolean;
+    /** Whether the column is filterable */
+    filterable?: boolean;
+    /** Whether the column is editable */
+    editable?: boolean;
+    /** Whether the column can be pinned */
+    pinnable?: boolean;
+    /** Type of data in the column (for filtering/formatting) */
+    type?: 'text' | 'number' | 'date' | 'select' | 'boolean';
+    /** Options for select type columns */
+    options?: string[];
+    /** Custom render function for cell content */
+    render?: (value: any, row: T, rowIndex: number) => React$1.ReactNode;
+    /** Custom cell value getter */
+    getValue?: (row: T) => any;
+    /** Group this column belongs to */
+    group?: string;
+    /** Whether this column is frozen/sticky */
+    frozen?: boolean;
+}
+/**
+ * Column group definition
+ */
+interface SpreadsheetColumnGroup {
+    /** Unique identifier for the group */
+    id: string;
+    /** Display label for the group header */
+    label: string;
+    /** Column IDs in this group */
+    columns: string[];
+    /** Whether the group is collapsible */
+    collapsible?: boolean;
+    /** Background color for the group header */
+    headerColor?: string;
+}
+/**
+ * Sort configuration
+ */
+interface SpreadsheetSortConfig {
+    /** Column ID to sort by */
+    columnId: string;
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+/**
+ * Text filter operator types for Excel-like filtering
+ */
+type TextFilterOperator = 'contains' | 'notContains' | 'equals' | 'notEquals' | 'startsWith' | 'endsWith' | 'isEmpty' | 'isNotEmpty';
+/**
+ * Number filter operator types for Excel-like filtering
+ */
+type NumberFilterOperator = 'equals' | 'notEquals' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'between' | 'isEmpty' | 'isNotEmpty';
+/**
+ * Date filter operator types for Excel-like filtering
+ */
+type DateFilterOperator = 'equals' | 'notEquals' | 'before' | 'after' | 'between' | 'today' | 'yesterday' | 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth' | 'thisYear' | 'isEmpty' | 'isNotEmpty';
+/**
+ * Text filter condition
+ */
+interface TextFilterCondition {
+    operator: TextFilterOperator;
+    value?: string;
+}
+/**
+ * Number filter condition
+ */
+interface NumberFilterCondition {
+    operator: NumberFilterOperator;
+    value?: number;
+    valueTo?: number;
+}
+/**
+ * Date filter condition
+ */
+interface DateFilterCondition {
+    operator: DateFilterOperator;
+    value?: string;
+    valueTo?: string;
+}
+/**
+ * Filter configuration for a single column
+ */
+interface SpreadsheetColumnFilter {
+    /** Text search filter (legacy, still supported) */
+    text?: string;
+    /** Minimum value for range filtering (legacy, still supported) */
+    min?: string | number;
+    /** Maximum value for range filtering (legacy, still supported) */
+    max?: string | number;
+    /** Selected values for multi-select filtering */
+    selectedValues?: string[];
+    /** Text filter condition for advanced filtering */
+    textCondition?: TextFilterCondition;
+    /** Number filter condition for advanced filtering */
+    numberCondition?: NumberFilterCondition;
+    /** Date filter condition for advanced filtering */
+    dateCondition?: DateFilterCondition;
+    /** Include blank/empty values */
+    includeBlanks?: boolean;
+    /** Exclude blank/empty values */
+    excludeBlanks?: boolean;
+}
+/**
+ * Cell position identifier
+ */
+interface CellPosition {
+    /** Row ID or index */
+    rowId: string | number;
+    /** Column ID */
+    columnId: string;
+}
+/**
+ * Cell highlight configuration
+ */
+interface CellHighlight {
+    /** Row ID (optional for column highlights) */
+    rowId?: string | number;
+    /** Column ID (optional for row highlights) */
+    columnId?: string;
+    /** Highlight color */
+    color: string;
+}
+/**
+ * Cell comment
+ */
+interface CellComment {
+    /** Unique ID */
+    id: string;
+    /** Row ID */
+    rowId: string | number;
+    /** Column ID (optional for row comments) */
+    columnId?: string;
+    /** Comment text */
+    text: string;
+    /** Author name */
+    author?: string;
+    /** Timestamp */
+    timestamp: Date;
+    /** Whether the comment is resolved */
+    resolved?: boolean;
+}
+/**
+ * Selection state
+ */
+interface SelectionState {
+    /** Selected row IDs */
+    selectedRows: Set<string | number>;
+    /** Focused cell position */
+    focusedCell: CellPosition | null;
+    /** Last selected row (for shift-click range selection) */
+    lastSelectedRow: string | number | null;
+}
+/**
+ * Pagination state
+ */
+interface PaginationState {
+    /** Current page (1-indexed) */
+    currentPage: number;
+    /** Number of rows per page */
+    pageSize: number;
+    /** Total number of rows */
+    totalRows: number;
+}
+/**
+ * Spreadsheet state
+ */
+interface SpreadsheetState<T = any> {
+    /** All data rows */
+    data: T[];
+    /** Column definitions */
+    columns: SpreadsheetColumn<T>[];
+    /** Column groups */
+    columnGroups?: SpreadsheetColumnGroup[];
+    /** Current sort configuration */
+    sortConfig: SpreadsheetSortConfig | null;
+    /** Column filters */
+    filters: Record<string, SpreadsheetColumnFilter>;
+    /** Selection state */
+    selection: SelectionState;
+    /** Pagination state */
+    pagination: PaginationState;
+    /** Collapsed column groups */
+    collapsedGroups: Set<string>;
+    /** Pinned columns */
+    pinnedColumns: Map<string, 'left' | 'right'>;
+    /** Cell highlights */
+    highlights: CellHighlight[];
+    /** Cell comments */
+    comments: CellComment[];
+    /** Zoom level (percentage) */
+    zoom: number;
+    /** Whether there are unsaved changes */
+    hasUnsavedChanges: boolean;
+}
+/**
+ * Row action configuration
+ */
+interface RowAction<T = any> {
+    /** Unique identifier */
+    id: string;
+    /** Icon component */
+    icon: React$1.ReactNode;
+    /** Tooltip text */
+    tooltip: string;
+    /** Callback when action is clicked */
+    onClick: (row: T, rowId: string | number) => void;
+    /** Whether the action is visible */
+    visible?: (row: T) => boolean;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Props for the main Spreadsheet component
+ */
+interface SpreadsheetProps<T = any> {
+    /** Data rows */
+    data: T[];
+    /** Column definitions */
+    columns: SpreadsheetColumn<T>[];
+    /** Column groups */
+    columnGroups?: SpreadsheetColumnGroup[];
+    /** Unique key accessor for each row */
+    getRowId: (row: T) => string | number;
+    /** Callback when a cell value is edited */
+    onCellEdit?: (rowId: string | number, columnId: string, newValue: any) => void;
+    /** Callback when selection changes */
+    onSelectionChange?: (selectedRows: (string | number)[]) => void;
+    /** Callback when sort changes */
+    onSortChange?: (sortConfig: SpreadsheetSortConfig | null) => void;
+    /** Callback when filters change */
+    onFilterChange?: (filters: Record<string, SpreadsheetColumnFilter>) => void;
+    /** Callback for row click */
+    onRowClick?: (row: T, rowIndex: number) => void;
+    /** Callback for row double click */
+    onRowDoubleClick?: (row: T, rowIndex: number) => void;
+    /** Callback when a row is cloned/duplicated */
+    onRowClone?: (row: T, rowId: string | number) => void;
+    /** Callback when a row comment is added */
+    onAddRowComment?: (rowId: string | number, comment: string) => void;
+    /** Callback when row highlight is toggled */
+    onRowHighlight?: (rowId: string | number, color: string | null) => void;
+    /** Whether to show the toolbar */
+    showToolbar?: boolean;
+    /** Whether to show pagination */
+    showPagination?: boolean;
+    /** Whether to show row index column (#) */
+    showRowIndex?: boolean;
+    /** Whether to enable row selection */
+    enableRowSelection?: boolean;
+    /** Whether to enable cell editing */
+    enableCellEditing?: boolean;
+    /** Whether to enable cell comments */
+    enableComments?: boolean;
+    /** Whether to enable cell highlighting */
+    enableHighlighting?: boolean;
+    /** Whether to enable undo/redo */
+    enableUndoRedo?: boolean;
+    /** Initial page size */
+    defaultPageSize?: number;
+    /** Available page size options */
+    pageSizeOptions?: number[];
+    /** Initial zoom level */
+    defaultZoom?: number;
+    /** Whether to auto-save changes */
+    autoSave?: boolean;
+    /** Whether to use compact mode (smaller cells) */
+    compactMode?: boolean;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Custom className */
+    className?: string;
+    /** Empty state message */
+    emptyMessage?: string;
+    /** Row highlights (externally controlled) */
+    rowHighlights?: CellHighlight[];
+    /** Row comments (externally controlled) */
+    rowComments?: CellComment[];
+    /** Custom row actions to display in the index column */
+    rowActions?: RowAction<T>[];
+    /**
+     * Enable server-side mode for filtering, sorting, and pagination.
+     * When enabled, the component will NOT perform client-side filtering, sorting, or pagination.
+     * Instead, it expects the `data` prop to already be filtered, sorted, and paginated by the server.
+     * @default false
+     */
+    serverSide?: boolean;
+    /**
+     * Total number of items (required when serverSide is true).
+     * Used to calculate pagination correctly when data is paginated server-side.
+     */
+    totalItems?: number;
+    /**
+     * Controlled current page (1-indexed). Use with serverSide mode for controlled pagination.
+     * When provided, the component becomes controlled for pagination.
+     */
+    currentPage?: number;
+    /**
+     * Controlled page size. Use with serverSide mode for controlled pagination.
+     * When provided along with currentPage, pagination becomes fully controlled.
+     */
+    pageSize?: number;
+    /**
+     * Callback when page changes. Required for serverSide pagination to work.
+     * Called with (page: number, pageSize: number) when the user changes pages or page size.
+     */
+    onPageChange?: (page: number, pageSize: number) => void;
+    /**
+     * Controlled sort configuration. Use with serverSide mode for controlled sorting.
+     * When provided, sorting becomes controlled by the parent component.
+     */
+    sortConfig?: SpreadsheetSortConfig | null;
+    /**
+     * Controlled filters. Use with serverSide mode for controlled filtering.
+     * When provided, filtering becomes controlled by the parent component.
+     */
+    filters?: Record<string, SpreadsheetColumnFilter>;
+}
+/**
+ * Props for SpreadsheetCell component
+ */
+interface SpreadsheetCellProps {
+    /** Cell value */
+    value: any;
+    /** Column definition */
+    column: SpreadsheetColumn;
+    /** Row data */
+    row: any;
+    /** Row index */
+    rowIndex: number;
+    /** Row ID */
+    rowId: string | number;
+    /** Whether the cell is editable */
+    isEditable?: boolean;
+    /** Whether the cell is currently being edited */
+    isEditing?: boolean;
+    /** Whether the cell is focused */
+    isFocused?: boolean;
+    /** Whether the row is selected */
+    isRowSelected?: boolean;
+    /** Whether the row is hovered */
+    isRowHovered?: boolean;
+    /** Highlight color */
+    highlightColor?: string;
+    /** Whether the cell has comments */
+    hasComments?: boolean;
+    /** Number of unresolved comments */
+    unresolvedCommentCount?: number;
+    /** Whether the cell was recently copied */
+    isCopied?: boolean;
+    /** Compact mode */
+    compactMode?: boolean;
+    /** Whether the column is pinned */
+    isPinned?: boolean;
+    /** Pin side */
+    pinSide?: 'left' | 'right';
+    /** Left offset for sticky positioning */
+    leftOffset?: number;
+    /** Right offset for sticky positioning */
+    rightOffset?: number;
+    /** Callback when cell is clicked */
+    onClick?: (event: React$1.MouseEvent) => void;
+    /** Callback when cell value changes */
+    onChange?: (newValue: any) => void;
+    /** Callback when editing is confirmed */
+    onConfirm?: () => void;
+    /** Callback when editing is cancelled */
+    onCancel?: () => void;
+    /** Callback to copy value down */
+    onCopyDown?: () => void;
+    /** Callback to copy to selected rows */
+    onCopyToSelected?: () => void;
+    /** Callback to add highlight */
+    onHighlight?: () => void;
+    /** Callback to add comment */
+    onAddComment?: () => void;
+    /** Callback to view comments */
+    onViewComments?: () => void;
+    /** Whether there are selected rows (for showing copy to selected button) */
+    hasSelectedRows?: boolean;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Props for SpreadsheetHeader component
+ */
+interface SpreadsheetHeaderProps {
+    /** Column definition */
+    column: SpreadsheetColumn;
+    /** Current sort configuration */
+    sortConfig: SpreadsheetSortConfig | null;
+    /** Whether the column has active filters */
+    hasActiveFilter?: boolean;
+    /** Whether the column is pinned */
+    isPinned?: boolean;
+    /** Pin side */
+    pinSide?: 'left' | 'right';
+    /** Left offset for sticky positioning */
+    leftOffset?: number;
+    /** Right offset for sticky positioning */
+    rightOffset?: number;
+    /** Highlight color */
+    highlightColor?: string;
+    /** Compact mode */
+    compactMode?: boolean;
+    /** Callback when column header is clicked (sorting) */
+    onClick?: () => void;
+    /** Callback to toggle filter dropdown */
+    onFilterClick?: () => void;
+    /** Callback to toggle pin */
+    onPinClick?: () => void;
+    /** Callback to highlight column */
+    onHighlightClick?: () => void;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Props for SpreadsheetFilterDropdown component
+ */
+interface SpreadsheetFilterDropdownProps {
+    /** Column definition */
+    column: SpreadsheetColumn;
+    /** Current filter value */
+    filter?: SpreadsheetColumnFilter;
+    /** All unique values in the column (for select filter) - optional, not currently used */
+    uniqueValues?: string[];
+    /** Callback when filter changes */
+    onFilterChange: (filter: SpreadsheetColumnFilter | undefined) => void;
+    /** Callback to close dropdown */
+    onClose: () => void;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Props for SpreadsheetToolbar component
+ */
+interface SpreadsheetToolbarProps {
+    /** Current zoom level */
+    zoom: number;
+    /** Whether undo is available */
+    canUndo: boolean;
+    /** Whether redo is available */
+    canRedo: boolean;
+    /** Number of undo actions available */
+    undoCount?: number;
+    /** Number of redo actions available */
+    redoCount?: number;
+    /** Number of selected rows */
+    selectedRowCount: number;
+    /** Whether there are unsaved changes */
+    hasUnsavedChanges: boolean;
+    /** Save status */
+    saveStatus: 'saved' | 'saving' | 'unsaved' | 'error';
+    /** Whether auto-save is enabled */
+    autoSave: boolean;
+    /** Summary data to display */
+    summary?: {
+        label: string;
+        value: string | number;
+        variant?: 'success' | 'danger' | 'warning' | 'info';
+    };
+    /** Callback for zoom in */
+    onZoomIn: () => void;
+    /** Callback for zoom out */
+    onZoomOut: () => void;
+    /** Callback for zoom reset */
+    onZoomReset: () => void;
+    /** Callback for undo */
+    onUndo: () => void;
+    /** Callback for redo */
+    onRedo: () => void;
+    /** Callback for clear selection */
+    onClearSelection: () => void;
+    /** Callback for manual save */
+    onSave?: () => void;
+    /** Callback for export */
+    onExport?: () => void;
+    /** Callback for settings */
+    onSettings?: () => void;
+    /** Callback for keyboard shortcuts */
+    onShowShortcuts?: () => void;
+    /** Whether there are active filters */
+    hasActiveFilters?: boolean;
+    /** Callback to clear all filters */
+    onClearFilters?: () => void;
+    /** Custom className */
+    className?: string;
+}
+/**
+ * Props for SpreadsheetColumnGroupHeader component
+ */
+interface SpreadsheetColumnGroupHeaderProps {
+    /** Group definition */
+    group: SpreadsheetColumnGroup;
+    /** Number of visible columns in the group */
+    colSpan: number;
+    /** Whether the group is collapsed */
+    isCollapsed: boolean;
+    /** Callback to toggle collapse */
+    onToggleCollapse: () => void;
+    /** Custom className */
+    className?: string;
+}
+
+/**
+ * Spreadsheet component - A feature-rich data grid with Excel-like functionality.
+ *
+ * Features:
+ * - Sortable columns
+ * - Filterable columns (text search, multi-select, range)
+ * - Inline cell editing
+ * - Row selection (single, multi, range)
+ * - Column pinning
+ * - Column grouping with collapse
+ * - Pagination
+ * - Zoom controls
+ * - Undo/Redo
+ * - Cell highlighting
+ * - Keyboard navigation
+ *
+ * @example
+ * ```tsx
+ * const columns = [
+ *   { id: 'name', label: 'Name', sortable: true, filterable: true },
+ *   { id: 'email', label: 'Email', editable: true },
+ *   { id: 'status', label: 'Status', type: 'select', options: ['Active', 'Inactive'] },
+ * ];
+ *
+ * <Spreadsheet
+ *   data={users}
+ *   columns={columns}
+ *   getRowId={(row) => row.id}
+ *   onCellEdit={(rowId, columnId, value) => handleEdit(rowId, columnId, value)}
+ *   showToolbar
+ *   showPagination
+ *   enableRowSelection
+ * />
+ * ```
+ */
+declare function Spreadsheet<T extends Record<string, any>>({ data, columns, columnGroups, getRowId, onCellEdit, onSelectionChange, onSortChange, onFilterChange, onRowClick, onRowDoubleClick, onRowClone, onAddRowComment, onRowHighlight, showToolbar, showPagination, showRowIndex, enableRowSelection, enableCellEditing, enableComments, enableHighlighting, enableUndoRedo, defaultPageSize, pageSizeOptions, defaultZoom, autoSave, compactMode, isLoading, className, emptyMessage, rowHighlights: externalRowHighlights, rowComments: externalRowComments, rowActions, serverSide, totalItems, currentPage: controlledCurrentPage, pageSize: controlledPageSize, onPageChange, sortConfig: controlledSortConfig, filters: controlledFilters, }: SpreadsheetProps<T>): react_jsx_runtime.JSX.Element;
+declare namespace Spreadsheet {
+    var displayName: string;
+}
+
+/**
+ * SpreadsheetCell component - A single cell in the spreadsheet table.
+ * Supports static display, inline editing, and various cell interactions.
+ *
+ * @example
+ * ```tsx
+ * <SpreadsheetCell
+ *   value="John Doe"
+ *   column={{ id: 'name', label: 'Name', editable: true }}
+ *   row={rowData}
+ *   rowIndex={0}
+ *   rowId="1"
+ *   isEditable={true}
+ *   onClick={handleClick}
+ *   onChange={handleChange}
+ * />
+ * ```
+ */
+declare const SpreadsheetCell: React$1.FC<SpreadsheetCellProps>;
+
+/**
+ * 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')}
+ * />
+ * ```
+ */
+declare const SpreadsheetHeader: React$1.FC<SpreadsheetHeaderProps & {
+    children?: React$1.ReactNode;
+}>;
+
+/**
+ * SpreadsheetFilterDropdown component - Condition-based filter dropdown for columns.
+ * Supports text conditions, number conditions, and date conditions.
+ */
+declare const SpreadsheetFilterDropdown: React$1.FC<SpreadsheetFilterDropdownProps>;
+
+/**
+ * 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())}
+ * />
+ * ```
+ */
+declare const SpreadsheetToolbar: React$1.FC<SpreadsheetToolbarProps>;
+
+/**
+ * Settings configuration for the Spreadsheet
+ */
+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;
+}
+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[];
+}
+/**
+ * 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"
+ * />
+ * ```
+ */
+declare const SpreadsheetSettingsModal: React.FC<SpreadsheetSettingsModalProps>;
+
+export { type CellComment, type CellHighlight, type CellPosition, type PaginationState, type RowAction, type SelectionState, Spreadsheet, SpreadsheetCell, type SpreadsheetCellProps, type SpreadsheetColumn, type SpreadsheetColumnFilter, type SpreadsheetColumnGroup, type SpreadsheetColumnGroupHeaderProps, SpreadsheetFilterDropdown, type SpreadsheetFilterDropdownProps, SpreadsheetHeader, type SpreadsheetHeaderProps, type SpreadsheetProps, type SpreadsheetSettings, SpreadsheetSettingsModal, type SpreadsheetSortConfig, type SpreadsheetState, SpreadsheetToolbar, type SpreadsheetToolbarProps };