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

package/src/lib/types/slots.types.ts

@@ -0,0 +1,332 @@
+/**
+ * Enhanced Slots and SlotProps Type System for DataTable
+ *
+ * This file defines all available slots and their corresponding prop types,
+ * following the MUI DataGrid pattern for maximum flexibility and extensibility.
+ * 
+ * Key improvements:
+ * - Full component props inheritance without limitations
+ * - Better type safety with generic support
+ * - Flexible prop merging and overriding
+ * - Support for custom styling and behavior
+ */
+import { TableProps, TableContainerProps, BoxProps, ToolbarProps, TableRowProps, TableCellProps, TableHeadProps, TableBodyProps } from '@mui/material';
+import { Table, Row, Column } from '@tanstack/react-table';
+import { ComponentType, ReactNode, HTMLAttributes, ComponentProps } from 'react';
+
+import { DataTableColumn, TableFilters, ExportProgress, ExportResult, ExportError, ServerExportColumn } from './index';
+import { DataTableSize } from '../utils/table-helpers';
+import { DataTablePaginationProps } from "../components/pagination";
+import { DataTableToolbarProps } from '../components/toolbar/data-table-toolbar';
+
+/**
+ * Enhanced slot component type that supports full component customization
+ */
+export type SlotComponent<TProps = any> = ComponentType<TProps>;
+
+/**
+ * Base slot props interface that includes common props for all slots
+ */
+export interface BaseSlotProps<T = any> {
+    table: Table<T>;
+}
+
+/**
+ * Enhanced slot props that merge base props with component-specific props
+ */
+export type EnhancedSlotProps<TBase, TComponent> = TBase & TComponent & {
+    // Allow any additional props for maximum flexibility
+    [key: string]: any;
+};
+
+/**
+ * Available slots for customization with enhanced typing
+ */
+export interface DataTableSlots<T = any> {
+    // Container and wrapper slots
+    root?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, BoxProps & { children: ReactNode }>>;
+    tableContainer?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableContainerProps & { 
+        children: ReactNode;
+        enableStickyHeader?: boolean;
+        maxHeight?: string | number;
+        enableVirtualization?: boolean;
+    }>>;
+    table?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableProps & { 
+        children: ReactNode;
+        tableSize?: DataTableSize;
+        enableStickyHeader?: boolean;
+        fitToScreen?: boolean;
+        tableStyle?: React.CSSProperties;
+    }>>;
+
+    // Header slots
+    toolbar?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, ToolbarProps & DataTableToolbarProps & {
+        title?: string;
+        subtitle?: string;
+        enableGlobalFilter?: boolean;
+        enableColumnVisibility?: boolean;
+        enableColumnFilter?: boolean;
+        enableExport?: boolean;
+        enableReset?: boolean;
+        enableTableSizeControl?: boolean;
+        enableColumnPinning?: boolean;
+        extraFilter?: ReactNode;
+        serverExport?: {
+            fetchData: (page: number, pageSize: number, filters: TableFilters) => Promise<{ data: T[]; total: number }>;
+            columns: ServerExportColumn<T>[];
+            pageSize?: number;
+        };
+        currentFilters?: TableFilters;
+        onExportStart?: (format: 'csv' | 'excel', summary: { mode: 'client' | 'server'; totalRows: number; estimatedMemoryMB?: number }) => void;
+        onExportProgress?: (progress: ExportProgress) => void;
+        onExportComplete?: (result: ExportResult) => void;
+        onExportError?: (error: ExportError) => void;
+        onExportCancel?: () => void;
+    }>>;
+
+    header?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableHeadProps & {
+        enableSorting?: boolean;
+        draggable?: boolean;
+        enableColumnResizing?: boolean;
+        enableStickyHeader?: boolean;
+        fitToScreen?: boolean;
+        onColumnReorder?: (draggedColumnId: string, targetColumnId: string) => void;
+    }>>;
+
+    headerRow?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableRowProps & {
+        headerGroups: any[];
+    }>>;
+
+    headerCell?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableCellProps & {
+        header: any;
+        column: Column<T>;
+        enableSorting?: boolean;
+        draggable?: boolean;
+        enableColumnResizing?: boolean;
+        onColumnReorder?: (draggedColumnId: string, targetColumnId: string) => void;
+        isPinned?: boolean | 'left' | 'right';
+        pinnedPosition?: number;
+        pinnedRightPosition?: number;
+    }>>;
+
+    // Icon slots with full component props
+    sortIconAsc?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    sortIconDesc?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+
+    // Body slots
+    body?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableBodyProps & {
+        children: ReactNode;
+        rows: Row<T>[];
+        loading?: boolean;
+        emptyMessage?: string;
+        enableVirtualization?: boolean;
+        enablePagination?: boolean;
+    }>>;
+
+    row?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableRowProps & {
+        row: Row<T>;
+        index: number;
+        enableHover?: boolean;
+        enableStripes?: boolean;
+        isOdd?: boolean;
+        renderSubComponent?: (row: Row<T>) => ReactNode;
+        disableStickyHeader?: boolean;
+    }>>;
+
+    cell?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableCellProps & {
+        row: Row<T>;
+        cell: any;
+        column: Column<T>;
+        value: any;
+        isPinned?: boolean | 'left' | 'right';
+        pinnedPosition?: number;
+        pinnedRightPosition?: number;
+        alignment?: 'left' | 'center' | 'right';
+    }>>;
+
+    // Special row slots
+    loadingRow?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableRowProps & {
+        rowCount: number;
+        colSpan: number;
+    }>>;
+
+    emptyRow?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableRowProps & {
+        colSpan: number;
+        message: string;
+    }>>;
+
+    expandedRow?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, TableRowProps & {
+        row: Row<T>;
+        colSpan: number;
+        children: ReactNode;
+    }>>;
+
+    // Footer slots
+    footer?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, BoxProps & {
+        children: ReactNode;
+        enableStickyFooter?: boolean;
+    }>>;
+
+    pagination?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, DataTablePaginationProps>>;
+
+    // Toolbar component slots with full component inheritance
+    searchInput?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, ComponentProps<'input'> & {
+        value: string;
+        onChange: (value: string) => void;
+        placeholder?: string;
+        autoFocus?: boolean;
+    }>>;
+
+    columnVisibilityControl?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, HTMLAttributes<HTMLDivElement>>>;
+    columnCustomFilterControl?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, HTMLAttributes<HTMLDivElement>>>;
+    columnPinningControl?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, HTMLAttributes<HTMLDivElement>>>;
+    resetButton?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, ComponentProps<'button'>>>;
+    tableSizeControl?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, HTMLAttributes<HTMLDivElement>>>;
+
+    // Bulk action slots
+    bulkActionsToolbar?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, ToolbarProps & {
+        selectionState: any;
+        selectedRowCount: number;
+        bulkActions?: (selectionState: any) => ReactNode;
+        onBulkAction?: (action: string, selectionState: T[]) => void;
+        enableSelectAll?: boolean;
+        onSelectAll?: () => void;
+        onDeselectAll?: () => void;
+    }>>;
+
+    exportButton?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, ComponentProps<'button'> & {
+        filename?: string;
+        dataMode?: 'client' | 'server';
+        serverExport?: {
+            fetchData: (page: number, pageSize: number, filters: TableFilters) => Promise<{ data: T[]; total: number }>;
+            columns: ServerExportColumn<T>[];
+            pageSize?: number;
+        };
+        currentFilters?: TableFilters;
+        onExportStart?: (format: 'csv' | 'excel', summary: { mode: 'client' | 'server'; totalRows: number; estimatedMemoryMB?: number }) => void;
+        onExportProgress?: (progress: ExportProgress) => void;
+        onExportComplete?: (result: ExportResult) => void;
+        onExportError?: (error: ExportError) => void;
+        onExportCancel?: () => void;
+    }>>;
+
+    // Icon slots with full SVG component props
+    searchIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    clearIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    exportIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    columnIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    resetIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    moreIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    filterIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    pinIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    unpinIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    leftIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    rightIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    csvIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    excelIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    selectAllIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    deselectIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    tableSizeIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    tableSizeSmallIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    tableSizeMediumIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+
+    // Selection slots
+    checkboxSelection?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, ComponentProps<'input'> & {
+        row?: Row<T>;
+        checked: boolean;
+        indeterminate?: boolean;
+        onChange: (checked: boolean) => void;
+        disabled?: boolean;
+    }>>;
+
+    // Expansion slots
+    expandIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+    collapseIcon?: SlotComponent<ComponentProps<'svg'> & { [key: string]: any }>;
+
+    // Loading and empty state slots
+    loadingSkeleton?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, HTMLAttributes<HTMLDivElement> & {
+        rows: number;
+        columns: number;
+    }>>;
+
+    noDataOverlay?: SlotComponent<EnhancedSlotProps<BaseSlotProps<T>, HTMLAttributes<HTMLDivElement> & {
+        message: string;
+    }>>;
+
+
+
+    // Special column slots
+    selectionColumn?: DataTableColumn<T>;
+    expandColumn?: DataTableColumn<T>;
+}
+
+/**
+ * Enhanced slot props type that allows full customization
+ */
+export type DataTableSlotProps<T = any> = {
+    [K in keyof DataTableSlots<T>]?: Record<string, any>;
+};
+
+/**
+ * Columns panel props for slot customization
+ */
+export interface ColumnsPanelSlotProps<T = any> {
+    getTogglableColumns?: (columns: DataTableColumn<T>[]) => DataTableColumn<T>[];
+    getPinnableColumns?: (columns: DataTableColumn<T>[]) => DataTableColumn<T>[];
+}
+
+/**
+ * Utility type to make all slot props optional for easier usage
+ */
+export type PartialSlotProps<T = any> = {
+    [K in keyof DataTableSlotProps<T>]?: Partial<DataTableSlotProps<T>[K]>;
+} & {
+    // Special props for columns panel
+    columnsPanel?: ColumnsPanelSlotProps<T>;
+};
+
+/**
+ * Utility type for slot component props with proper generic support
+ */
+export type SlotComponentProps<
+    TSlot extends keyof DataTableSlots<T>,
+    T = any
+> = DataTableSlots<T>[TSlot] extends SlotComponent<infer TProps> ? TProps : never;
+
+/**
+ * Helper type to extract component props from a slot
+ */
+export type ExtractSlotProps<TSlot> = TSlot extends SlotComponent<infer TProps> ? TProps : never;
+
+/**
+ * Default slot components - can be overridden by users
+ */
+// export interface DefaultSlots<T = any> extends DataTableSlots<T> {
+//     // All slots should have default implementations
+// }
+
+/**
+ * Enhanced slot configuration with better prop merging
+ */
+export interface SlotConfiguration<T = any> {
+    slots?: Partial<DataTableSlots<T>>;
+    slotProps?: PartialSlotProps<T>;
+}
+
+/**
+ * Slot override configuration for advanced customization
+ */
+export interface SlotOverrideConfig<T = any> {
+    // Override specific slot behavior
+    overrideSlot?: <K extends keyof DataTableSlots<T>>(
+        slotName: K,
+        component: DataTableSlots<T>[K],
+        props?: Partial<SlotComponentProps<K, T>>
+    ) => void;
+    
+    // Merge props with existing slot props
+    mergeSlotProps?: <K extends keyof DataTableSlots<T>>(
+        slotName: K,
+        props: Partial<SlotComponentProps<K, T>>
+    ) => Partial<SlotComponentProps<K, T>>;
+}

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

@@ -0,0 +1,90 @@
+import { SortingState } from '@tanstack/react-table';
+
+import { ColumnFilterRule, SelectionState } from '../features';
+
+
+/**
+ * Table State and Configuration Types
+ * Consolidated table-related interfaces from data-table.types.ts
+ */
+
+/**
+ * Table filters configuration
+ */
+
+export type TableSize = 'small' | 'medium';
+
+// Extended table state interface with custom column filter support
+
+export interface TableState {
+    columnFilter: ColumnFilterState;
+    selectionState?: SelectionState; // Selection state for CustomSelectionFeature
+    globalFilter?: string;
+    sorting?: SortingState;
+    pagination?: {
+        pageIndex: number;
+        pageSize: number;
+    };
+    columnOrder?: string[];
+    columnPinning?: {
+        left?: string[];
+        right?: string[];
+    };
+    columnVisibility?: Record<string, boolean>;
+    columnSizing?: Record<string, number>;
+}
+
+export interface TableFilters {
+    globalFilter: string;
+    columnFilter: ColumnFilterState;
+    sorting: SortingState;
+    pagination: {
+        pageIndex: number;
+        pageSize: number;
+    };
+    columnOrder: string[];
+    columnPinning: {
+        left?: string[];
+        right?: string[];
+    };
+}
+
+export interface TableFiltersForFetch {
+    search?: string;
+    page?: number;
+    pageSize?: number;
+    sorting?: SortingState;
+    columnFilter?: ColumnFilterState;
+}
+
+export interface ColumnFilterState {
+    filters: ColumnFilterRule[];
+    logic: 'AND' | 'OR';
+    // Add pending state for draft filters before applying
+    pendingFilters: ColumnFilterRule[];
+    pendingLogic: 'AND' | 'OR';
+}
+
+/**
+ * Table performance metrics
+ */
+export interface TablePerformanceMetrics {
+    renderTime: number;
+    dataProcessingTime: number;
+    totalRows: number;
+    visibleRows: number;
+    memoryUsage?: number;
+}
+
+/**
+ * Table metrics for debugging and optimization
+ */
+export interface TableMetrics {
+    totalRows: number;
+    visibleRows: number;
+    totalColumns?: number;
+    visibleColumns?: number;
+    pinnedColumns?: number;
+    renderTime: number;
+    lastUpdated?: Date;
+}

package/src/lib/utils/column-helpers.ts

@@ -0,0 +1,72 @@
+/**
+ * Column utilities for DataTable components
+ */
+import { Column, ColumnDef } from "@tanstack/react-table";
+
+
+export type ColumnType = 'text' | 'number' | 'date' | 'boolean' | 'select' | 'actions';
+
+/**
+ * Get the type of a column from its metadata
+ */
+export function getColumnType(column: Column<any, unknown>): ColumnType {
+    // Check if column has explicit type in columnDef
+    if (column?.columnDef?.type) {
+        return column.columnDef.type;
+    }
+    return 'text'; // Default to text
+}
+
+export function getCustomFilterComponent(column: Column<any, unknown>): any {
+    // Check if column has custom filter component in meta
+    return column?.columnDef?.filterComponent || column?.columnDef?.editComponent;
+}
+
+
+export function getColumnOptions(column: Column<any, unknown>): any[] {
+    // Check if column has explicit options in meta
+    if (column?.columnDef?.options) {
+        return column?.columnDef.options || [];
+    }
+
+    // Default options for boolean type
+    const columnType = getColumnType(column);
+    if (columnType === 'boolean') {
+        return [
+            {
+                value: true,
+                label: 'Yes',
+            },
+            {
+                value: false,
+                label: 'No',
+            },
+        ];
+    }
+
+    return [];
+}
+
+export function withIdsDeep<T>(cols: ColumnDef<T, any>[]): ColumnDef<T, any>[] {
+    return cols.map((c, i) => ({
+        ...c,
+        id: c.id ?? (c as any).accessorKey ?? `col_${i}`,
+        ...(Array.isArray((c as any).columns) && {
+            columns: withIdsDeep((c as any).columns)
+        }),
+    }));
+}
+
+
+/**
+ * Determine if a column should be filterable
+ */
+export function isColumnFilterable(column: Column<any, unknown>): boolean {
+    // Check if column is explicitly marked as filterable
+    if (column?.columnDef?.filterable !== undefined) {
+        return column?.columnDef?.filterable;
+    }
+
+    // Default to filterable for data columns
+    return true;
+}

package/src/lib/utils/debounced-fetch.utils.ts

@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { TableFiltersForFetch } from '../types';
+
+
+export function useDebouncedFetch<T extends Record<string, any>>(
+    onFetchData: ((filters: TableFiltersForFetch) => Promise<{ data: T[]; total: number }>) | undefined,
+    delay = 300,
+) {
+    const [isLoading, setIsLoading] = useState(false);
+    const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    const debouncedFetch = useCallback(async (filters: TableFiltersForFetch) => {
+        if (!onFetchData) return null;
+
+        // Create a unique key for the current fetch parameters
+        // const currentParams = JSON.stringify(filters);
+        // Clear existing timer
+        if (debounceTimer.current) {
+            clearTimeout(debounceTimer.current);
+        }
+
+        return new Promise<{ data: T[]; total: number } | null>((resolve) => {
+            debounceTimer.current = setTimeout(async () => {
+                setIsLoading(true);
+                try {
+                    const result = await onFetchData(filters);
+                    resolve(result);
+                } catch (error) {
+                    // Handle fetch error silently or could be passed to onError callback
+                    console.error('Error fetching data:', error);
+                    resolve(null);
+                } finally {
+                    setIsLoading(false);
+                }
+            }, delay);
+        });
+    }, [onFetchData, delay]);
+
+    // Cleanup timer on unmount
+    useEffect(() => {
+        // Fetch data when dependencies change
+        return () => {
+            if (debounceTimer.current) {
+                clearTimeout(debounceTimer.current);
+            }
+        };
+    }, []);
+
+    return {
+        debouncedFetch,
+        isLoading,
+    };
+}