@xcelsior/ui-spreadsheets 1.0.1

package/src/components/Spreadsheet.stories.tsx

@@ -0,0 +1,1146 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useCallback, useEffect, useState } from 'react';
+import { Spreadsheet } from './Spreadsheet';
+import type {
+    SpreadsheetColumn,
+    SpreadsheetColumnGroup,
+    SpreadsheetSortConfig,
+    SpreadsheetColumnFilter,
+} from '../types';
+import { HiEye, HiPencil, HiTrash } from 'react-icons/hi';
+
+// Sample data types
+interface User {
+    id: number;
+    name: string;
+    email: string;
+    department: string;
+    role: string;
+    status: string;
+    salary: number;
+    startDate: string;
+    isActive: boolean;
+}
+
+interface Product {
+    id: number;
+    name: string;
+    category: string;
+    price: number;
+    stock: number;
+    sku: string;
+    supplier: string;
+    lastUpdated: string;
+}
+
+// Sample user data
+const sampleUsers: User[] = Array.from({ length: 100 }, (_, i) => ({
+    id: i + 1,
+    name: `User ${i + 1}`,
+    email: `user${i + 1}@example.com`,
+    department: ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'][i % 5],
+    role: ['Admin', 'Manager', 'Developer', 'Designer', 'Analyst'][i % 5],
+    status: ['Active', 'Inactive', 'Pending'][i % 3],
+    salary: 50000 + Math.floor(Math.random() * 100000),
+    startDate: new Date(2020 + (i % 5), i % 12, (i % 28) + 1).toISOString().split('T')[0],
+    isActive: i % 3 !== 1,
+}));
+
+// Sample product data
+const sampleProducts: Product[] = Array.from({ length: 50 }, (_, i) => ({
+    id: i + 1,
+    name: `Product ${i + 1}`,
+    category: ['Electronics', 'Clothing', 'Food', 'Books', 'Home'][i % 5],
+    price: Math.round((10 + Math.random() * 990) * 100) / 100,
+    stock: Math.floor(Math.random() * 1000),
+    sku: `SKU-${String(i + 1).padStart(5, '0')}`,
+    supplier: ['Supplier A', 'Supplier B', 'Supplier C'][i % 3],
+    lastUpdated: new Date(2024, i % 12, (i % 28) + 1).toISOString().split('T')[0],
+}));
+
+// User columns
+const userColumns: SpreadsheetColumn<User>[] = [
+    { id: 'id', label: 'ID', width: 60, sortable: true, align: 'center' },
+    { id: 'name', label: 'Name', width: 150, sortable: true, filterable: true, editable: true },
+    { id: 'email', label: 'Email', width: 220, sortable: true, filterable: true, editable: true },
+    {
+        id: 'department',
+        label: 'Department',
+        width: 120,
+        sortable: true,
+        filterable: true,
+        type: 'select',
+        options: ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'],
+    },
+    {
+        id: 'role',
+        label: 'Role',
+        width: 120,
+        sortable: true,
+        filterable: true,
+        type: 'select',
+        options: ['Admin', 'Manager', 'Developer', 'Designer', 'Analyst'],
+    },
+    {
+        id: 'status',
+        label: 'Status',
+        width: 100,
+        sortable: true,
+        filterable: true,
+        type: 'select',
+        options: ['Active', 'Inactive', 'Pending'],
+    },
+    {
+        id: 'salary',
+        label: 'Salary',
+        width: 120,
+        sortable: true,
+        type: 'number',
+        align: 'right',
+        render: (value) => `$${value.toLocaleString()}`,
+    },
+    { id: 'startDate', label: 'Start Date', width: 120, sortable: true, type: 'date' },
+    { id: 'isActive', label: 'Active', width: 80, type: 'boolean', align: 'center' },
+];
+
+// Product columns
+const productColumns: SpreadsheetColumn<Product>[] = [
+    { id: 'id', label: 'ID', width: 60, sortable: true, align: 'center' },
+    { id: 'sku', label: 'SKU', width: 120, sortable: true, filterable: true },
+    {
+        id: 'name',
+        label: 'Product Name',
+        width: 180,
+        sortable: true,
+        filterable: true,
+        editable: true,
+    },
+    {
+        id: 'category',
+        label: 'Category',
+        width: 120,
+        sortable: true,
+        filterable: true,
+        type: 'select',
+        options: ['Electronics', 'Clothing', 'Food', 'Books', 'Home'],
+    },
+    {
+        id: 'price',
+        label: 'Price',
+        width: 100,
+        sortable: true,
+        type: 'number',
+        align: 'right',
+        render: (value) => `$${value.toFixed(2)}`,
+    },
+    { id: 'stock', label: 'Stock', width: 80, sortable: true, type: 'number', align: 'right' },
+    { id: 'supplier', label: 'Supplier', width: 120, sortable: true, filterable: true },
+    { id: 'lastUpdated', label: 'Last Updated', width: 120, sortable: true, type: 'date' },
+];
+
+// Column groups example
+const columnGroups: SpreadsheetColumnGroup[] = [
+    {
+        id: 'personal',
+        label: 'Personal Info',
+        columns: ['name', 'email'],
+        collapsible: true,
+        headerColor: '#e0f2fe',
+    },
+    {
+        id: 'work',
+        label: 'Work Info',
+        columns: ['department', 'role', 'status'],
+        collapsible: true,
+        headerColor: '#fef3c7',
+    },
+    {
+        id: 'compensation',
+        label: 'Compensation',
+        columns: ['salary', 'startDate'],
+        collapsible: true,
+        headerColor: '#d1fae5',
+    },
+];
+
+const meta: Meta<typeof Spreadsheet> = {
+    title: 'Components/Spreadsheet',
+    component: Spreadsheet,
+    parameters: {
+        layout: 'fullscreen',
+        docs: {
+            description: {
+                component: `
+A feature-rich spreadsheet component with Excel-like functionality.
+
+## Features
+- **Sorting**: Click column headers to sort data
+- **Filtering**: Filter by text, multi-select, or range
+- **Cell Editing**: Double-click cells to edit (when enabled)
+- **Row Selection**: Single, multi (Ctrl/Cmd+click), and range (Shift+click) selection
+- **Column Pinning**: Pin columns to left or right
+- **Column Grouping**: Group columns with collapsible headers
+- **Pagination**: Navigate through large datasets
+- **Zoom Controls**: Adjust the view zoom level
+- **Undo/Redo**: Revert or replay changes
+- **Cell Highlighting**: Highlight rows/columns with colors
+- **Comments**: Add comments to rows
+- **Keyboard Navigation**: Arrow keys, Tab, Enter, Escape
+- **Row Actions**: Custom action buttons per row
+
+## Keyboard Shortcuts
+- **Arrow Keys**: Navigate cells
+- **Tab/Shift+Tab**: Move horizontally
+- **Enter**: Start editing / Confirm edit
+- **Escape**: Cancel editing
+- **Ctrl/Cmd+Z**: Undo
+- **Ctrl/Cmd+Shift+Z**: Redo
+- **Ctrl/Cmd+C**: Copy cell value
+- **Space**: Toggle row selection
+- **Ctrl/Cmd+A**: Select all rows
+                `,
+            },
+        },
+    },
+    tags: ['autodocs'],
+    argTypes: {
+        data: { control: false },
+        columns: { control: false },
+        columnGroups: { control: false },
+        getRowId: { control: false },
+        onCellEdit: { action: 'onCellEdit' },
+        onSelectionChange: { action: 'onSelectionChange' },
+        onSortChange: { action: 'onSortChange' },
+        onFilterChange: { action: 'onFilterChange' },
+        onRowClick: { action: 'onRowClick' },
+        onRowDoubleClick: { action: 'onRowDoubleClick' },
+        onRowClone: { action: 'onRowClone' },
+        onAddRowComment: { action: 'onAddRowComment' },
+        onRowHighlight: { action: 'onRowHighlight' },
+        showToolbar: {
+            control: 'boolean',
+            description: 'Show/hide the toolbar with search, zoom, and settings',
+        },
+        showPagination: {
+            control: 'boolean',
+            description: 'Show/hide pagination controls',
+        },
+        showRowIndex: {
+            control: 'boolean',
+            description: 'Show/hide row index column (#)',
+        },
+        enableRowSelection: {
+            control: 'boolean',
+            description: 'Enable/disable row selection',
+        },
+        enableCellEditing: {
+            control: 'boolean',
+            description: 'Enable/disable inline cell editing',
+        },
+        enableComments: {
+            control: 'boolean',
+            description: 'Enable/disable row comments',
+        },
+        enableHighlighting: {
+            control: 'boolean',
+            description: 'Enable/disable row/column highlighting',
+        },
+        enableUndoRedo: {
+            control: 'boolean',
+            description: 'Enable/disable undo/redo functionality',
+        },
+        defaultPageSize: {
+            control: 'select',
+            options: [10, 25, 50, 100],
+            description: 'Default number of rows per page',
+        },
+        defaultZoom: {
+            control: { type: 'range', min: 50, max: 150, step: 10 },
+            description: 'Default zoom level (percentage)',
+        },
+        compactMode: {
+            control: 'boolean',
+            description: 'Use compact cell styling',
+        },
+        isLoading: {
+            control: 'boolean',
+            description: 'Show loading state',
+        },
+        emptyMessage: {
+            control: 'text',
+            description: 'Message to display when data is empty',
+        },
+    },
+    args: {
+        showToolbar: true,
+        showPagination: true,
+        showRowIndex: true,
+        enableRowSelection: true,
+        enableCellEditing: true,
+        enableComments: true,
+        enableHighlighting: true,
+        enableUndoRedo: true,
+        defaultPageSize: 25,
+        defaultZoom: 100,
+        compactMode: false,
+        isLoading: false,
+        emptyMessage: 'No data available',
+    },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Default story with users (interactive with state management)
+export const Default: Story = {
+    render: (args) => {
+        const [data, setData] = useState(sampleUsers);
+        const [, setSelectedRows] = useState<(string | number)[]>([]);
+
+        const handleCellEdit = (rowId: string | number, columnId: string, newValue: any) => {
+            console.log('Cell Edit:', { rowId, columnId, newValue });
+            setData((prev) =>
+                prev.map((row) => (row.id === rowId ? { ...row, [columnId]: newValue } : row))
+            );
+        };
+
+        const handleRowClone = (row: User, rowId: string | number) => {
+            const newId = Math.max(...data.map((r) => r.id)) + 1;
+            const clonedRow = { ...row, id: newId, name: `${row.name} (Copy)` };
+            const rowIndex = data.findIndex((r) => r.id === rowId);
+            const newData = [...data];
+            newData.splice(rowIndex + 1, 0, clonedRow);
+            setData(newData);
+        };
+
+        return (
+            <Spreadsheet
+                {...args}
+                data={data}
+                columns={userColumns}
+                getRowId={(row) => row.id}
+                onCellEdit={handleCellEdit}
+                onRowClone={handleRowClone}
+                onSelectionChange={setSelectedRows}
+            />
+        );
+    },
+};
+
+// Interactive example with state management
+export const Interactive: Story = {
+    render: () => {
+        const [data, setData] = useState(sampleUsers);
+        const [selectedRows, setSelectedRows] = useState<(string | number)[]>([]);
+
+        const handleCellEdit = (rowId: string | number, columnId: string, newValue: any) => {
+            setData((prev) =>
+                prev.map((row) => (row.id === rowId ? { ...row, [columnId]: newValue } : row))
+            );
+        };
+
+        const handleRowClone = (row: User, rowId: string | number) => {
+            const newId = Math.max(...data.map((r) => r.id)) + 1;
+            const clonedRow = { ...row, id: newId, name: `${row.name} (Copy)` };
+            const rowIndex = data.findIndex((r) => r.id === rowId);
+            const newData = [...data];
+            newData.splice(rowIndex + 1, 0, clonedRow);
+            setData(newData);
+        };
+
+        return (
+            <div className="p-4">
+                <div className="mb-4 text-sm text-gray-600">
+                    Selected rows: {selectedRows.length > 0 ? selectedRows.join(', ') : 'None'}
+                </div>
+                <Spreadsheet
+                    data={data}
+                    columns={userColumns}
+                    getRowId={(row) => row.id}
+                    onCellEdit={handleCellEdit}
+                    onRowClone={handleRowClone}
+                    onSelectionChange={setSelectedRows}
+                    showToolbar
+                    showPagination
+                    enableRowSelection
+                    enableCellEditing
+                />
+            </div>
+        );
+    },
+};
+
+// With column groups
+export const WithColumnGroups: Story = {
+    args: {
+        data: sampleUsers,
+        columns: userColumns,
+        columnGroups: columnGroups,
+        getRowId: (row: User) => row.id,
+    },
+};
+
+// Products spreadsheet
+export const ProductsSpreadsheet: Story = {
+    args: {
+        data: sampleProducts,
+        columns: productColumns,
+        getRowId: (row: Product) => row.id,
+    },
+};
+
+// Compact mode
+export const CompactMode: Story = {
+    args: {
+        data: sampleUsers,
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        compactMode: true,
+        defaultPageSize: 50,
+    },
+};
+
+// Read-only mode (no editing, no row actions)
+export const ReadOnly: Story = {
+    args: {
+        data: sampleUsers,
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        enableCellEditing: false,
+        enableComments: false,
+        enableHighlighting: false,
+    },
+};
+
+// Loading state
+export const Loading: Story = {
+    args: {
+        data: [],
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        isLoading: true,
+    },
+};
+
+// Empty state
+export const Empty: Story = {
+    args: {
+        data: [],
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        emptyMessage: 'No users found. Try adjusting your filters.',
+    },
+};
+
+// Minimal (no toolbar, no pagination)
+export const Minimal: Story = {
+    args: {
+        data: sampleUsers.slice(0, 10),
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        showToolbar: false,
+        showPagination: false,
+        showRowIndex: false,
+    },
+};
+
+// With row actions
+export const WithRowActions: Story = {
+    render: () => {
+        const handleView = (row: User) => {
+            alert(`Viewing user: ${row.name}`);
+        };
+
+        const handleEdit = (row: User) => {
+            alert(`Editing user: ${row.name}`);
+        };
+
+        const handleDelete = (row: User) => {
+            if (confirm(`Delete user ${row.name}?`)) {
+                alert(`Deleted: ${row.name}`);
+            }
+        };
+
+        return (
+            <Spreadsheet
+                data={sampleUsers}
+                columns={userColumns}
+                getRowId={(row) => row.id}
+                rowActions={[
+                    {
+                        id: 'view',
+                        icon: <HiEye className="w-4 h-4" />,
+                        tooltip: 'View details',
+                        onClick: handleView,
+                    },
+                    {
+                        id: 'edit',
+                        icon: <HiPencil className="w-4 h-4" />,
+                        tooltip: 'Edit user',
+                        onClick: handleEdit,
+                    },
+                    {
+                        id: 'delete',
+                        icon: <HiTrash className="w-4 h-4 text-red-500" />,
+                        tooltip: 'Delete user',
+                        onClick: handleDelete,
+                        visible: (row) => row.status !== 'Active',
+                    },
+                ]}
+            />
+        );
+    },
+};
+
+// With pre-existing highlights and comments
+export const WithHighlightsAndComments: Story = {
+    args: {
+        data: sampleUsers,
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        rowHighlights: [
+            { rowId: 1, color: '#fef3c7' },
+            { rowId: 3, color: '#d1fae5' },
+            { rowId: 5, color: '#fee2e2' },
+        ],
+        rowComments: [
+            {
+                id: '1',
+                rowId: 1,
+                text: 'VIP customer - handle with care',
+                author: 'Admin',
+                timestamp: new Date('2024-01-15'),
+            },
+            {
+                id: '2',
+                rowId: 3,
+                text: 'Needs follow-up next week',
+                author: 'Sales Team',
+                timestamp: new Date('2024-01-14'),
+            },
+        ],
+    },
+};
+
+// Large dataset (performance test)
+export const LargeDataset: Story = {
+    args: {
+        data: Array.from({ length: 1000 }, (_, i) => ({
+            id: i + 1,
+            name: `User ${i + 1}`,
+            email: `user${i + 1}@example.com`,
+            department: ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'][i % 5],
+            role: ['Admin', 'Manager', 'Developer', 'Designer', 'Analyst'][i % 5],
+            status: ['Active', 'Inactive', 'Pending'][i % 3],
+            salary: 50000 + Math.floor(Math.random() * 100000),
+            startDate: new Date(2020 + (i % 5), i % 12, (i % 28) + 1).toISOString().split('T')[0],
+            isActive: i % 3 !== 1,
+        })),
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        defaultPageSize: 100,
+    },
+};
+
+// Custom zoom level
+export const ZoomedOut: Story = {
+    args: {
+        data: sampleUsers,
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        defaultZoom: 75,
+    },
+};
+
+// Custom zoom level (zoomed in)
+export const ZoomedIn: Story = {
+    args: {
+        data: sampleUsers,
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        defaultZoom: 125,
+    },
+};
+
+// Selection only mode (no editing)
+export const SelectionOnly: Story = {
+    args: {
+        data: sampleUsers,
+        columns: userColumns,
+        getRowId: (row: User) => row.id,
+        enableRowSelection: true,
+        enableCellEditing: false,
+    },
+    render: (args) => {
+        const [selected, setSelected] = useState<(string | number)[]>([]);
+
+        return (
+            <div className="p-4">
+                <div className="mb-4 p-3 bg-blue-50 rounded-lg">
+                    <strong>Selected Users:</strong>{' '}
+                    {selected.length > 0
+                        ? selected.map((id) => `User ${id}`).join(', ')
+                        : 'None - Click rows to select'}
+                </div>
+                <Spreadsheet {...(args as any)} onSelectionChange={setSelected} />
+            </div>
+        );
+    },
+};
+
+// With custom cell rendering
+export const CustomCellRendering: Story = {
+    args: {
+        data: sampleUsers,
+        columns: [
+            { id: 'id', label: 'ID', width: 60 },
+            { id: 'name', label: 'Name', width: 150, editable: true },
+            { id: 'email', label: 'Email', width: 220, editable: true },
+            {
+                id: 'status',
+                label: 'Status',
+                width: 120,
+                render: (value: string) => (
+                    <span
+                        className={`px-2 py-1 rounded-full text-xs font-medium ${
+                            value === 'Active'
+                                ? 'bg-green-100 text-green-800'
+                                : value === 'Inactive'
+                                  ? 'bg-red-100 text-red-800'
+                                  : 'bg-yellow-100 text-yellow-800'
+                        }`}
+                    >
+                        {value}
+                    </span>
+                ),
+            },
+            {
+                id: 'salary',
+                label: 'Salary',
+                width: 150,
+                align: 'right' as const,
+                render: (value: number) => (
+                    <div className="flex items-center justify-end gap-2">
+                        <div
+                            className="h-2 bg-blue-500 rounded"
+                            style={{
+                                width: `${Math.min((value / 150000) * 100, 100)}%`,
+                                maxWidth: '80px',
+                            }}
+                        />
+                        <span>${value.toLocaleString()}</span>
+                    </div>
+                ),
+            },
+            {
+                id: 'isActive',
+                label: 'Active',
+                width: 80,
+                align: 'center' as const,
+                render: (value: boolean) => (value ? '✅' : '❌'),
+            },
+        ],
+        getRowId: (row: User) => row.id,
+    },
+};
+
+// Column Filtering Demo - showcasing all filter types
+export const ColumnFiltering: Story = {
+    render: () => {
+        const [data] = useState(sampleUsers);
+        const [activeFilters, setActiveFilters] = useState<Record<string, any>>({});
+
+        // Columns with all filter types enabled
+        const filterableColumns: SpreadsheetColumn<User>[] = [
+            { id: 'id', label: 'ID', width: 60, sortable: true, align: 'center' },
+            {
+                id: 'name',
+                label: 'Name',
+                width: 150,
+                sortable: true,
+                filterable: true,
+                type: 'text',
+            },
+            {
+                id: 'email',
+                label: 'Email',
+                width: 220,
+                sortable: true,
+                filterable: true,
+                type: 'text',
+            },
+            {
+                id: 'department',
+                label: 'Department',
+                width: 130,
+                sortable: true,
+                filterable: true,
+                type: 'text',
+            },
+            {
+                id: 'salary',
+                label: 'Salary',
+                width: 120,
+                sortable: true,
+                filterable: true,
+                type: 'number',
+                align: 'right',
+                render: (value) => `$${value.toLocaleString()}`,
+            },
+            {
+                id: 'startDate',
+                label: 'Start Date',
+                width: 130,
+                sortable: true,
+                filterable: true,
+                type: 'date',
+            },
+            {
+                id: 'status',
+                label: 'Status',
+                width: 100,
+                sortable: true,
+                filterable: true,
+                type: 'text',
+            },
+        ];
+
+        const activeFilterCount = Object.keys(activeFilters).length;
+
+        return (
+            <div className="p-4">
+                <div className="mb-4 p-4 bg-blue-50 rounded-lg border border-blue-200">
+                    <h3 className="font-semibold text-blue-900 mb-2">Column Filtering Demo</h3>
+                    <p className="text-sm text-blue-700 mb-3">
+                        Click the filter icon (funnel) in any column header to open the filter
+                        dropdown. Different column types show different filter options:
+                    </p>
+                    <ul className="text-sm text-blue-700 space-y-1 ml-4 list-disc">
+                        <li>
+                            <strong>Text columns</strong> (Name, Email, Department, Status):
+                            Contains, Starts with, Equals, etc.
+                        </li>
+                        <li>
+                            <strong>Number columns</strong> (Salary): Greater than, Less than,
+                            Between, Equals, etc.
+                        </li>
+                        <li>
+                            <strong>Date columns</strong> (Start Date): Before, After, Between,
+                            Today, This week, etc.
+                        </li>
+                    </ul>
+                    {activeFilterCount > 0 && (
+                        <div className="mt-3 pt-3 border-t border-blue-200">
+                            <span className="text-sm font-medium text-blue-800">
+                                Active filters: {activeFilterCount}
+                            </span>
+                            <pre className="mt-2 text-xs bg-white p-2 rounded border overflow-auto max-h-24">
+                                {JSON.stringify(activeFilters, null, 2)}
+                            </pre>
+                        </div>
+                    )}
+                </div>
+                <Spreadsheet
+                    data={data}
+                    columns={filterableColumns}
+                    getRowId={(row) => row.id}
+                    onFilterChange={setActiveFilters}
+                    showToolbar
+                    showPagination
+                    enableRowSelection={false}
+                    enableCellEditing={false}
+                    defaultPageSize={25}
+                />
+            </div>
+        );
+    },
+};
+
+// ==================== SERVER-SIDE MODE STORIES ====================
+
+// Large dataset for server-side simulation (1000 records)
+const allServerData: User[] = Array.from({ length: 1000 }, (_, i) => ({
+    id: i + 1,
+    name: `User ${i + 1}`,
+    email: `user${i + 1}@example.com`,
+    department: ['Engineering', 'Marketing', 'Sales', 'HR', 'Finance'][i % 5],
+    role: ['Admin', 'Manager', 'Developer', 'Designer', 'Analyst'][i % 5],
+    status: ['Active', 'Inactive', 'Pending'][i % 3],
+    salary: 50000 + Math.floor(Math.random() * 100000),
+    startDate: new Date(2020 + (i % 5), i % 12, (i % 28) + 1).toISOString().split('T')[0],
+    isActive: i % 3 !== 1,
+}));
+
+/**
+ * Simulates a server-side API call with filtering, sorting, and pagination.
+ * In a real application, this would be an API call to your backend.
+ */
+function simulateServerFetch(params: {
+    page: number;
+    pageSize: number;
+    sortConfig: SpreadsheetSortConfig | null;
+    filters: Record<string, SpreadsheetColumnFilter>;
+}): Promise<{ data: User[]; totalItems: number }> {
+    return new Promise((resolve) => {
+        // Simulate network delay
+        setTimeout(() => {
+            let result = [...allServerData];
+
+            // Apply filters (simulating server-side filtering)
+            for (const [columnId, filter] of Object.entries(params.filters)) {
+                if (!filter) continue;
+
+                if (filter.textCondition) {
+                    const { operator, value } = filter.textCondition;
+                    result = result.filter((row) => {
+                        const cellValue = String((row as any)[columnId] ?? '').toLowerCase();
+                        const filterValue = (value ?? '').toLowerCase();
+
+                        switch (operator) {
+                            case 'contains':
+                                return cellValue.includes(filterValue);
+                            case 'notContains':
+                                return !cellValue.includes(filterValue);
+                            case 'equals':
+                                return cellValue === filterValue;
+                            case 'notEquals':
+                                return cellValue !== filterValue;
+                            case 'startsWith':
+                                return cellValue.startsWith(filterValue);
+                            case 'endsWith':
+                                return cellValue.endsWith(filterValue);
+                            case 'isEmpty':
+                                return !cellValue;
+                            case 'isNotEmpty':
+                                return !!cellValue;
+                            default:
+                                return true;
+                        }
+                    });
+                }
+
+                if (filter.numberCondition) {
+                    const { operator, value, valueTo } = filter.numberCondition;
+                    result = result.filter((row) => {
+                        const cellValue = (row as any)[columnId];
+                        if (operator === 'isEmpty') return cellValue == null;
+                        if (operator === 'isNotEmpty') return cellValue != null;
+
+                        const numValue = Number(cellValue);
+                        if (Number.isNaN(numValue)) return false;
+
+                        switch (operator) {
+                            case 'equals':
+                                return value !== undefined && numValue === value;
+                            case 'notEquals':
+                                return value !== undefined && numValue !== value;
+                            case 'greaterThan':
+                                return value !== undefined && numValue > value;
+                            case 'greaterThanOrEqual':
+                                return value !== undefined && numValue >= value;
+                            case 'lessThan':
+                                return value !== undefined && numValue < value;
+                            case 'lessThanOrEqual':
+                                return value !== undefined && numValue <= value;
+                            case 'between':
+                                return (
+                                    value !== undefined &&
+                                    valueTo !== undefined &&
+                                    numValue >= value &&
+                                    numValue <= valueTo
+                                );
+                            default:
+                                return true;
+                        }
+                    });
+                }
+            }
+
+            // Apply sorting (simulating server-side sorting)
+            if (params.sortConfig) {
+                const { columnId, direction } = params.sortConfig;
+                result.sort((a, b) => {
+                    const aValue = (a as any)[columnId];
+                    const bValue = (b as any)[columnId];
+
+                    if (aValue === null || aValue === undefined) return 1;
+                    if (bValue === null || bValue === undefined) return -1;
+
+                    if (typeof aValue === 'string' && typeof bValue === 'string') {
+                        return direction === 'asc'
+                            ? aValue.localeCompare(bValue)
+                            : bValue.localeCompare(aValue);
+                    }
+
+                    return direction === 'asc'
+                        ? aValue < bValue
+                            ? -1
+                            : aValue > bValue
+                              ? 1
+                              : 0
+                        : aValue > bValue
+                          ? -1
+                          : aValue < bValue
+                            ? 1
+                            : 0;
+                });
+            }
+
+            const totalItems = result.length;
+
+            // Apply pagination (simulating server-side pagination)
+            const startIndex = (params.page - 1) * params.pageSize;
+            const paginatedData = result.slice(startIndex, startIndex + params.pageSize);
+
+            resolve({ data: paginatedData, totalItems });
+        }, 300); // 300ms simulated delay
+    });
+}
+
+// Server-side mode with full control
+export const ServerSideMode: Story = {
+    render: () => {
+        // Server-side state
+        const [data, setData] = useState<User[]>([]);
+        const [totalItems, setTotalItems] = useState(0);
+        const [isLoading, setIsLoading] = useState(true);
+
+        // Controlled state for pagination, sorting, and filtering
+        const [currentPage, setCurrentPage] = useState(1);
+        const [pageSize, setPageSize] = useState(25);
+        const [sortConfig, setSortConfig] = useState<SpreadsheetSortConfig | null>(null);
+        const [filters, setFilters] = useState<Record<string, SpreadsheetColumnFilter>>({});
+
+        // Fetch data from "server"
+        const fetchData = useCallback(async () => {
+            setIsLoading(true);
+            const result = await simulateServerFetch({
+                page: currentPage,
+                pageSize,
+                sortConfig,
+                filters,
+            });
+            setData(result.data);
+            setTotalItems(result.totalItems);
+            setIsLoading(false);
+        }, [currentPage, pageSize, sortConfig, filters]);
+
+        // Fetch data whenever params change
+        useEffect(() => {
+            fetchData();
+        }, [fetchData]);
+
+        // Handle page change
+        const handlePageChange = (page: number, size: number) => {
+            if (size !== pageSize) {
+                setPageSize(size);
+                setCurrentPage(1); // Reset to page 1 when page size changes
+            } else {
+                setCurrentPage(page);
+            }
+        };
+
+        // Handle sort change
+        const handleSortChange = (newSortConfig: SpreadsheetSortConfig | null) => {
+            setSortConfig(newSortConfig);
+            setCurrentPage(1); // Reset to page 1 when sorting changes
+        };
+
+        // Handle filter change
+        const handleFilterChange = (newFilters: Record<string, SpreadsheetColumnFilter>) => {
+            setFilters(newFilters);
+            setCurrentPage(1); // Reset to page 1 when filters change
+        };
+
+        const filterableColumns: SpreadsheetColumn<User>[] = [
+            { id: 'id', label: 'ID', width: 60, sortable: true, align: 'center' },
+            {
+                id: 'name',
+                label: 'Name',
+                width: 150,
+                sortable: true,
+                filterable: true,
+                type: 'text',
+            },
+            {
+                id: 'email',
+                label: 'Email',
+                width: 220,
+                sortable: true,
+                filterable: true,
+                type: 'text',
+            },
+            {
+                id: 'department',
+                label: 'Department',
+                width: 130,
+                sortable: true,
+                filterable: true,
+                type: 'text',
+            },
+            {
+                id: 'salary',
+                label: 'Salary',
+                width: 120,
+                sortable: true,
+                filterable: true,
+                type: 'number',
+                align: 'right',
+                render: (value) => `$${value.toLocaleString()}`,
+            },
+            {
+                id: 'startDate',
+                label: 'Start Date',
+                width: 130,
+                sortable: true,
+                filterable: true,
+                type: 'date',
+            },
+            {
+                id: 'status',
+                label: 'Status',
+                width: 100,
+                sortable: true,
+                filterable: true,
+                type: 'text',
+            },
+        ];
+
+        return (
+            <div className="p-4">
+                <div className="mb-4 p-4 bg-purple-50 rounded-lg border border-purple-200">
+                    <h3 className="font-semibold text-purple-900 mb-2">Server-Side Mode Demo</h3>
+                    <p className="text-sm text-purple-700 mb-3">
+                        This example demonstrates server-side filtering, sorting, and pagination.
+                        The spreadsheet does NOT process data client-side - instead, it sends
+                        requests to the "server" (simulated) whenever you:
+                    </p>
+                    <ul className="text-sm text-purple-700 space-y-1 ml-4 list-disc">
+                        <li>Change pages or page size</li>
+                        <li>Sort by clicking column headers</li>
+                        <li>Apply filters using the filter dropdowns</li>
+                    </ul>
+                    <div className="mt-3 pt-3 border-t border-purple-200 grid grid-cols-2 gap-4 text-xs">
+                        <div>
+                            <span className="font-medium text-purple-800">Current State:</span>
+                            <pre className="mt-1 bg-white p-2 rounded border overflow-auto max-h-32">
+                                {JSON.stringify(
+                                    {
+                                        currentPage,
+                                        pageSize,
+                                        sortConfig,
+                                        filterCount: Object.keys(filters).length,
+                                    },
+                                    null,
+                                    2
+                                )}
+                            </pre>
+                        </div>
+                        <div>
+                            <span className="font-medium text-purple-800">Server Response:</span>
+                            <pre className="mt-1 bg-white p-2 rounded border overflow-auto max-h-32">
+                                {JSON.stringify(
+                                    { totalItems, loadedRows: data.length, isLoading },
+                                    null,
+                                    2
+                                )}
+                            </pre>
+                        </div>
+                    </div>
+                </div>
+                <Spreadsheet
+                    data={data}
+                    columns={filterableColumns}
+                    getRowId={(row) => row.id}
+                    // Enable server-side mode
+                    serverSide
+                    totalItems={totalItems}
+                    // Controlled pagination
+                    currentPage={currentPage}
+                    pageSize={pageSize}
+                    onPageChange={handlePageChange}
+                    // Controlled sorting
+                    sortConfig={sortConfig}
+                    onSortChange={handleSortChange}
+                    // Controlled filtering
+                    filters={filters}
+                    onFilterChange={handleFilterChange}
+                    // Other props
+                    isLoading={isLoading}
+                    showToolbar
+                    showPagination
+                    enableRowSelection={false}
+                    enableCellEditing={false}
+                    pageSizeOptions={[10, 25, 50, 100]}
+                />
+            </div>
+        );
+    },
+};
+
+// Server-side pagination only (sorting and filtering still client-side)
+export const ServerSidePaginationOnly: Story = {
+    render: () => {
+        const [data, setData] = useState<User[]>([]);
+        const [totalItems] = useState(allServerData.length);
+        const [isLoading, setIsLoading] = useState(true);
+        const [currentPage, setCurrentPage] = useState(1);
+        const [pageSize, setPageSize] = useState(25);
+
+        // Simulate fetching just the current page
+        useEffect(() => {
+            setIsLoading(true);
+            const timer = setTimeout(() => {
+                const startIndex = (currentPage - 1) * pageSize;
+                setData(allServerData.slice(startIndex, startIndex + pageSize));
+                setIsLoading(false);
+            }, 200);
+            return () => clearTimeout(timer);
+        }, [currentPage, pageSize]);
+
+        const handlePageChange = (page: number, size: number) => {
+            if (size !== pageSize) {
+                setPageSize(size);
+                setCurrentPage(1);
+            } else {
+                setCurrentPage(page);
+            }
+        };
+
+        return (
+            <div className="p-4">
+                <div className="mb-4 p-4 bg-green-50 rounded-lg border border-green-200">
+                    <h3 className="font-semibold text-green-900 mb-2">
+                        Server-Side Pagination Only
+                    </h3>
+                    <p className="text-sm text-green-700">
+                        This example shows server-side pagination while keeping client-side sorting
+                        and filtering. Useful when you have a large dataset but want quick local
+                        filtering on the current page.
+                    </p>
+                    <div className="mt-2 text-xs text-green-600">
+                        Page {currentPage} of {Math.ceil(totalItems / pageSize)} | Showing{' '}
+                        {data.length} of {totalItems} total items
+                    </div>
+                </div>
+                <Spreadsheet
+                    data={data}
+                    columns={userColumns}
+                    getRowId={(row) => row.id}
+                    // Server-side pagination
+                    serverSide
+                    totalItems={totalItems}
+                    currentPage={currentPage}
+                    pageSize={pageSize}
+                    onPageChange={handlePageChange}
+                    // Client-side sorting and filtering (no controlled state)
+                    isLoading={isLoading}
+                    showToolbar
+                    showPagination
+                    enableRowSelection
+                    enableCellEditing={false}
+                />
+            </div>
+        );
+    },
+};