@xcelsior/ui-spreadsheets 1.0.1

package/src/types.ts

@@ -0,0 +1,612 @@
+import type React from 'react';
+
+/**
+ * Column definition for the spreadsheet
+ */
+export 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.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
+ */
+export 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
+ */
+export interface SpreadsheetSortConfig {
+    /** Column ID to sort by */
+    columnId: string;
+    /** Sort direction */
+    direction: 'asc' | 'desc';
+}
+
+/**
+ * Text filter operator types for Excel-like filtering
+ */
+export type TextFilterOperator =
+    | 'contains'
+    | 'notContains'
+    | 'equals'
+    | 'notEquals'
+    | 'startsWith'
+    | 'endsWith'
+    | 'isEmpty'
+    | 'isNotEmpty';
+
+/**
+ * Number filter operator types for Excel-like filtering
+ */
+export type NumberFilterOperator =
+    | 'equals'
+    | 'notEquals'
+    | 'greaterThan'
+    | 'greaterThanOrEqual'
+    | 'lessThan'
+    | 'lessThanOrEqual'
+    | 'between'
+    | 'isEmpty'
+    | 'isNotEmpty';
+
+/**
+ * Date filter operator types for Excel-like filtering
+ */
+export type DateFilterOperator =
+    | 'equals'
+    | 'notEquals'
+    | 'before'
+    | 'after'
+    | 'between'
+    | 'today'
+    | 'yesterday'
+    | 'thisWeek'
+    | 'lastWeek'
+    | 'thisMonth'
+    | 'lastMonth'
+    | 'thisYear'
+    | 'isEmpty'
+    | 'isNotEmpty';
+
+/**
+ * Text filter condition
+ */
+export interface TextFilterCondition {
+    operator: TextFilterOperator;
+    value?: string;
+}
+
+/**
+ * Number filter condition
+ */
+export interface NumberFilterCondition {
+    operator: NumberFilterOperator;
+    value?: number;
+    valueTo?: number; // For 'between' operator
+}
+
+/**
+ * Date filter condition
+ */
+export interface DateFilterCondition {
+    operator: DateFilterOperator;
+    value?: string; // ISO date string
+    valueTo?: string; // For 'between' operator
+}
+
+/**
+ * Filter configuration for a single column
+ */
+export 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
+ */
+export interface CellPosition {
+    /** Row ID or index */
+    rowId: string | number;
+    /** Column ID */
+    columnId: string;
+}
+
+/**
+ * Cell highlight configuration
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export interface PaginationState {
+    /** Current page (1-indexed) */
+    currentPage: number;
+    /** Number of rows per page */
+    pageSize: number;
+    /** Total number of rows */
+    totalRows: number;
+}
+
+/**
+ * Spreadsheet state
+ */
+export 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
+ */
+export interface RowAction<T = any> {
+    /** Unique identifier */
+    id: string;
+    /** Icon component */
+    icon: React.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;
+}
+
+/**
+ * Server-side pagination state for controlled pagination
+ */
+export interface ServerSidePaginationState {
+    /** Current page (1-indexed) */
+    currentPage: number;
+    /** Number of rows per page */
+    pageSize: number;
+    /** Total number of items (required for server-side pagination) */
+    totalItems: number;
+}
+
+/**
+ * Props for the main Spreadsheet component
+ */
+export 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>[];
+
+    // ==================== SERVER-SIDE MODE ====================
+    /**
+     * 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
+ */
+export 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.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
+ */
+export 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
+ */
+export 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 SpreadsheetPagination component
+ */
+export interface SpreadsheetPaginationProps {
+    /** Current page (1-indexed) */
+    currentPage: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Number of rows per page */
+    pageSize: number;
+    /** Total number of rows */
+    totalRows: number;
+    /** Start index of current page (1-indexed) */
+    startRow: number;
+    /** End index of current page */
+    endRow: number;
+    /** Available page size options */
+    pageSizeOptions?: number[];
+    /** Callback when page changes */
+    onPageChange: (page: number) => void;
+    /** Callback when page size changes */
+    onPageSizeChange: (pageSize: number) => void;
+    /** Custom className */
+    className?: string;
+}
+
+/**
+ * Props for SpreadsheetToolbar component
+ */
+export 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
+ */
+export 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;
+}

package/src/utils.ts

@@ -0,0 +1,16 @@
+// Helper function to check if value is blank/empty
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export const isBlankValue = (value: any): boolean => {
+    return (
+        value === null ||
+        value === undefined ||
+        value === '' ||
+        (typeof value === 'string' && value.trim() === '')
+    );
+};
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs));
+}

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "lib": ["DOM", "DOM.Iterable", "ESNext"],
+        "allowJs": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "strict": true,
+        "noImplicitAny": false,
+        "forceConsistentCasingInFileNames": true,
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "noEmit": true,
+        "jsx": "react-jsx",
+        "declaration": true,
+        "outDir": "./dist",
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["./src/*"],
+            "@components/*": ["./src/components/*"],
+            "@utils/*": ["./src/utils/*"],
+            "@types/*": ["./src/types/*"]
+        }
+    },
+    "include": ["src"],
+    "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['cjs', 'esm'],
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    clean: true,
+    external: ['react', 'react-dom', '@xcelsior/design-system'],
+    outDir: 'dist',
+});