@ackplus/react-tanstack-data-table 1.0.34 → 1.1.1

package/src/lib/types/data-table-api.ts

@@ -0,0 +1,169 @@
+import { ColumnPinningState, SortingState, ColumnOrderState, TableState, Row, Table } from '@tanstack/react-table';
+
+import { ColumnFilterState } from './table.types';
+import { SelectionState } from '../features';
+
+export interface DataTableApi<T = any> {
+    // Column Management
+    columnVisibility: {
+        showColumn: (columnId: string) => void;
+        hideColumn: (columnId: string) => void;
+        toggleColumn: (columnId: string) => void;
+        showAllColumns: () => void;
+        hideAllColumns: () => void;
+        resetColumnVisibility: () => void;
+    };
+
+    table :{
+        getTable: () => Table<T>;
+    }
+
+    // Column Ordering
+    columnOrdering: {
+        setColumnOrder: (columnOrder: ColumnOrderState) => void;
+        moveColumn: (columnId: string, toIndex: number) => void;
+        resetColumnOrder: () => void;
+    };
+
+    // Column Pinning
+    columnPinning: {
+        pinColumnLeft: (columnId: string) => void;
+        pinColumnRight: (columnId: string) => void;
+        unpinColumn: (columnId: string) => void;
+        setPinning: (pinning: ColumnPinningState) => void;
+        resetColumnPinning: () => void;
+    };
+
+    // Column Resizing
+    columnResizing: {
+        resizeColumn: (columnId: string, width: number) => void;
+        autoSizeColumn: (columnId: string) => void;
+        autoSizeAllColumns: () => void;
+        resetColumnSizing: () => void;
+    };
+
+    // Filtering
+    filtering: {
+        setGlobalFilter: (filter: string) => void;
+        clearGlobalFilter: () => void;
+        setColumnFilters: (filters: ColumnFilterState) => void;
+        addColumnFilter: (columnId: string, operator: string, value: any) => void;
+        removeColumnFilter: (filterId: string) => void;
+        clearAllFilters: () => void;
+        resetFilters: () => void;
+    };
+
+    // Sorting
+    sorting: {
+        setSorting: (sorting: SortingState) => void;
+        sortColumn: (columnId: string, direction: 'asc' | 'desc' | false) => void;
+        clearSorting: () => void;
+        resetSorting: () => void;
+    };
+
+    // Pagination
+    pagination: {
+        goToPage: (pageIndex: number) => void;
+        nextPage: () => void;
+        previousPage: () => void;
+        setPageSize: (pageSize: number) => void;
+        goToFirstPage: () => void;
+        goToLastPage: () => void;
+        resetPagination?: () => void;
+    };
+
+    // Enhanced Row Selection with automatic mode detection
+    selection: {
+        // Basic selection (works with current selectMode)
+        selectRow: (rowId: string) => void;
+        deselectRow: (rowId: string) => void;
+        toggleRowSelection: (rowId: string) => void;
+
+        // Smart selection methods (automatically handle page vs all modes)
+        selectAll: () => void; // Selects all based on current selectMode
+        deselectAll: () => void; // Deselects all
+        toggleSelectAll: () => void; // Toggles select all
+
+        // Selection state getters
+        getSelectionState: () => SelectionState; // Get selection state
+        getSelectedCount: () => number; // Get total selected count
+        getSelectedRows: () => Row<T>[]
+        // Selection state checks
+        isRowSelected: (rowId: string) => boolean;
+    };
+
+    // Data Management
+    data: {
+        refresh: (resetPagination?: boolean) => void;
+        reload: () => void;
+
+        // Data CRUD operations
+        getAllData: () => T[];
+        getRowData: (rowId: string) => T | undefined;
+        getRowByIndex: (index: number) => T | undefined;
+        updateRow: (rowId: string, updates: Partial<T>) => void;
+        updateRowByIndex: (index: number, updates: Partial<T>) => void;
+        insertRow: (newRow: T, index?: number) => void;
+        deleteRow: (rowId: string) => void;
+        deleteRowByIndex: (index: number) => void;
+        deleteSelectedRows: () => void;
+        replaceAllData: (newData: T[]) => void;
+
+        // Bulk operations
+        updateMultipleRows: (updates: Array<{ rowId: string; data: Partial<T> }>) => void;
+        insertMultipleRows: (newRows: T[], startIndex?: number) => void;
+        deleteMultipleRows: (rowIds: string[]) => void;
+
+        // Field-specific updates
+        updateField: (rowId: string, fieldName: keyof T, value: any) => void;
+        updateFieldByIndex: (index: number, fieldName: keyof T, value: any) => void;
+
+        // Data queries
+        findRows: (predicate: (row: T) => boolean) => T[];
+        findRowIndex: (predicate: (row: T) => boolean) => number;
+        getDataCount: () => number;
+        getFilteredDataCount: () => number;
+    };
+
+    // Layout Management
+    layout: {
+        resetLayout: () => void;
+        resetAll: () => void;
+        saveLayout: () => any;
+        restoreLayout: (layout: any) => void;
+    };
+
+    // Table State
+    state: {
+        getTableState: () => any;
+        getCurrentFilters: () => ColumnFilterState;
+        getCurrentSorting: () => SortingState;
+        getCurrentPagination: () => { pageIndex: number; pageSize: number };
+        getCurrentSelection: () => SelectionState;
+    };
+
+    // Simplified Export
+    export: {
+        exportCSV: (options?: {
+            filename?: string;
+            onlyVisibleColumns?: boolean;
+            onlySelectedRows?: boolean;
+            includeHeaders?: boolean;
+        }) => Promise<void>;
+        exportExcel: (options?: {
+            filename?: string;
+            onlyVisibleColumns?: boolean;
+            onlySelectedRows?: boolean;
+            includeHeaders?: boolean;
+        }) => Promise<void>;
+        exportServerData: (options: {
+            format: 'csv' | 'excel';
+            filename?: string;
+            fetchData: (filters?: Partial<TableState>) => Promise<{ data: T[]; total: number }>;
+            pageSize?: number;
+            includeHeaders?: boolean;
+        }) => Promise<void>;
+        isExporting: () => boolean;
+        cancelExport: () => void;
+    };
+}

package/src/lib/types/data-table.types.ts

@@ -0,0 +1,139 @@
+/**
+ * Type definitions for DataTable components
+ */
+import { Row, SortingState, ColumnResizeMode, ColumnPinningState, PaginationState, ColumnDef } from '@tanstack/react-table';
+import { ReactNode } from 'react';
+
+import type { ColumnFilterState, TableFilters, TableState } from './index';
+import { DataTableSlots, PartialSlotProps } from './slots.types';
+import { DataTableSize } from '../utils/table-helpers';
+import { SelectionState } from '../features';
+import { DataTableLoggingOptions } from '../utils/logger';
+
+// Selection mode type
+export type SelectMode = 'page' | 'all';
+
+// Dynamic data management interfaces
+// TableFilters now imported from types folder
+
+export interface DataTableProps<T> {
+    // Core data props
+    // columns: DataTableColumn<T>[] | AccessorKeyColumnDef <T, string>[];
+    columns: ColumnDef<T, any>[];
+    data?: T[];
+    totalRow?: number;
+    idKey?: keyof T;
+    extraFilter?: ReactNode | null;
+    footerFilter?: ReactNode | null;
+
+    // Data management modes (MUI DataGrid style)
+    dataMode?: 'client' | 'server'; // Data management mode (default: 'client')
+    initialState?: Partial<TableState>;
+    initialLoadData?: boolean; // Initial load data (default: true)
+    onDataStateChange?: (filters: Partial<TableState>) => void; // Callback when any filter/state changes
+    onFetchData?: (filters: Partial<TableFilters>) => Promise<{ data: T[]; total: number }>;
+
+    // Simplified Export props
+    exportFilename?: string;
+    onExportProgress?: (progress: { processedRows?: number; totalRows?: number; percentage?: number }) => void;
+    onExportComplete?: (result: { success: boolean; filename: string; totalRows: number }) => void;
+    onExportError?: (error: { message: string; code: string }) => void;
+
+    // Server export callback - receives current table state/filters and selection data
+    onServerExport?: (filters?: Partial<TableState>, selection?: SelectionState) => Promise<{ data: any[]; total: number }>;
+
+    // Export cancellation callback - called when export is cancelled
+    onExportCancel?: () => void;
+
+    // Selection props
+    enableRowSelection?: boolean | ((row: Row<T>) => boolean);
+    enableMultiRowSelection?: boolean;
+    selectMode?: SelectMode; // 'page' | 'all' - defines selection scope
+    
+    // Row selection control (like MUI DataGrid)
+    isRowSelectable?: (params: { row: T; id: string }) => boolean;
+    
+    onSelectionChange?: (selection: SelectionState) => void;
+
+    // Row click props
+    onRowClick?: (event: React.MouseEvent<HTMLTableRowElement>, row: Row<T>) => void;
+    selectOnRowClick?: boolean; // If true, row click will toggle selection (default: false)
+
+    // Bulk action props
+    enableBulkActions?: boolean;
+    bulkActions?: (selectionState: SelectionState) => ReactNode;
+
+    // Column resizing props
+    enableColumnResizing?: boolean;
+    columnResizeMode?: ColumnResizeMode;
+    onColumnSizingChange?: (sizing: Record<string, number>) => void;
+
+    // Column ordering props
+    enableColumnDragging?: boolean;
+    onColumnDragEnd?: (columnOrder: string[]) => void;
+
+    // Column pinning props
+    enableColumnPinning?: boolean;
+    onColumnPinningChange?: (pinning: ColumnPinningState) => void;
+
+    // Column visibility props
+    enableColumnVisibility?: boolean;
+    onColumnVisibilityChange?: (visibility: Record<string, boolean>) => void;
+
+    // Expandable rows props
+    enableExpanding?: boolean;
+    getRowCanExpand?: (row: Row<T>) => boolean;
+    renderSubComponent?: (row: Row<T>) => ReactNode;
+
+    // Pagination props
+    enablePagination?: boolean;
+    paginationMode?: 'client' | 'server'; // Pagination mode (default: 'client')
+
+    // Filtering props
+    enableGlobalFilter?: boolean;
+    enableColumnFilter?: boolean;
+    filterMode?: 'client' | 'server'; // Filtering mode (default: 'client')
+
+    // Sorting props
+    enableSorting?: boolean;
+    sortingMode?: 'client' | 'server'; // Sorting mode (default: 'client')
+    onSortingChange?: (sorting: SortingState) => void;
+
+    // Styling props
+    enableHover?: boolean;
+    enableStripes?: boolean;
+    tableContainerProps?: any;
+    tableProps?: any;
+    fitToScreen?: boolean;
+    tableSize?: DataTableSize;
+
+    // Sticky header/footer props
+    enableStickyHeaderOrFooter?: boolean;
+    maxHeight?: string | number;
+
+    // Virtualization props
+    enableVirtualization?: boolean;
+    estimateRowHeight?: number;
+
+    // Toolbar props
+    enableTableSizeControl?: boolean;
+    enableExport?: boolean;
+    enableReset?: boolean;
+
+    // Loading and empty states
+    loading?: boolean;
+    emptyMessage?: string | ReactNode;
+    skeletonRows?: number;
+
+    // Column filters props
+    onColumnFiltersChange?: (filterState: ColumnFilterState) => void;
+    onPaginationChange?: (pagination: PaginationState) => void;
+    onGlobalFilterChange?: (globalFilter: string) => void;
+    onColumnFilterChange?: (columnFilter: ColumnFilterState) => void;
+    // Slots for component customization (similar to MUI DataGrid)
+    slots?: Partial<DataTableSlots<T>>;
+    slotProps?: PartialSlotProps<T>;
+
+    // Logging configuration
+    logging?: boolean | DataTableLoggingOptions;
+}

package/src/lib/types/export.types.ts

@@ -0,0 +1,154 @@
+/**
+ * Export Configuration Types
+ * Consolidated export-related interfaces from export-utils.ts
+ */
+
+import { TableState } from './table.types';
+
+
+/**
+ * Server export column configuration
+ */
+export interface ServerExportColumn<T = any> {
+    id: string;
+    header: string;
+    accessor: keyof T | string;
+    formatter?: (value: any, row: T) => string;
+}
+
+/**
+ * Export options configuration
+ */
+export interface ExportOptions {
+    filename?: string;
+    format: 'csv' | 'excel';
+    includeHeaders?: boolean;
+    onlyVisibleColumns?: boolean;
+    onlyFilteredData?: boolean;
+    // New options for large datasets
+    chunkSize?: number;
+    onProgress?: (progress: ExportProgress) => void;
+    onComplete?: (result: ExportResult) => void;
+    onError?: (error: ExportError) => void;
+    signal?: AbortSignal; // For cancellation
+}
+
+/**
+ * Export progress information
+ */
+export interface ExportProgress {
+    processedRows: number;
+    totalRows: number;
+    percentage: number;
+    currentChunk: number;
+    totalChunks: number;
+    estimatedTimeRemaining?: number;
+}
+
+/**
+ * Export result information
+ */
+export interface ExportResult {
+    success: boolean;
+    filename: string;
+    totalRows: number;
+    totalColumns: number;
+    processingTime: number;
+    fileSize?: number;
+}
+
+/**
+ * Export error information
+ */
+export interface ExportError {
+    message: string;
+    code: 'CANCELLED' | 'MEMORY_ERROR' | 'PROCESSING_ERROR' | 'UNKNOWN';
+    details?: any;
+}
+
+/**
+ * Export configuration for DataTable
+ */
+export interface ExportConfig {
+    enabled: boolean;
+    formats: ('csv' | 'excel')[];
+    filename?: string;
+    includeHeaders?: boolean;
+    onlyVisibleColumns?: boolean;
+    onlyFilteredData?: boolean;
+    // New configuration for large datasets
+    chunkSize?: number;
+    enableProgressTracking?: boolean;
+    maxMemoryThreshold?: number; // MB
+}
+
+/**
+ * Export state for tracking ongoing exports
+ */
+export interface ExportState {
+    isExporting: boolean;
+    progress?: ExportProgress;
+    controller?: AbortController;
+    startTime?: number;
+}
+
+/**
+ * Chunked data processing configuration
+ */
+export interface ChunkProcessingConfig {
+    chunkSize: number;
+    delayBetweenChunks: number; // ms
+    useWebWorker: boolean;
+}
+
+/**
+ * Styling options for pinned columns (actual implementation)
+ */
+export interface PinnedColumnStyleOptions {
+    width?: number | string;
+    minWidth?: number;
+    maxWidth?: number;
+    isPinned?: 'left' | 'right' | false;
+    pinnedPosition?: number;
+    pinnedRightPosition?: number;
+    zIndex?: number;
+    disableStickyHeader?: boolean;
+    isLastLeftPinnedColumn?: boolean;
+    isFirstRightPinnedColumn?: boolean;
+    wrapText?: boolean; // If true, text will wrap; if false, text will truncate with ellipsis (default: false)
+}
+
+/**
+ * Simplified Export Types for DataTable
+ */
+
+export interface SimpleExportOptions {
+    filename?: string;
+    format: 'csv' | 'excel';
+    includeHeaders?: boolean;
+    onlyVisibleColumns?: boolean;
+    onlySelectedRows?: boolean;
+}
+
+/**
+ * Selection data for server exports
+ */
+export interface SelectionExportData {
+    selectAllMatching?: boolean;
+    excludedIds?: string[];
+    selectedIds?: string[];
+    hasSelection?: boolean;
+}
+
+export interface ServerExportOptions extends SimpleExportOptions {
+    fetchData: (filters?: Partial<TableState>, selection?: SelectionExportData) => Promise<{ data: any[]; total: number }>;
+    currentFilters?: any; // Current table filters/state
+    pageSize?: number;
+    selection?: SelectionExportData;
+}
+
+export interface ExportCallbacks {
+    onProgress?: (progress: ExportProgress) => void;
+    onComplete?: (result: ExportResult) => void;
+    onError?: (error: ExportError) => void;
+}

package/src/lib/types/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Consolidated Types Index
+ * All DataTable types in one organized location
+ */
+
+// Column-related types
+export * from './column.types';
+
+// Table state and configuration types
+export * from './table.types';
+
+// Export functionality types
+export * from './export.types';
+
+// API types (already exists)
+export * from './data-table-api';
+
+// Slots and slotProps types
+export * from './slots.types';
+
+// Re-export commonly used types for convenience
+export type { DataTableApi } from './data-table-api';