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

package/src/lib/utils/export-utils.ts

@@ -0,0 +1,285 @@
+import { Table } from '@tanstack/react-table';
+import * as XLSX from 'xlsx';
+import { SelectionState } from '../features';
+
+// Local types for the utility functions (keep simpler for actual implementation)
+export interface ExportOptions {
+    format: 'csv' | 'excel';
+    filename: string;
+    onProgress?: (progress: { processedRows?: number; totalRows?: number; percentage?: number }) => void;
+    onComplete?: (result: { success: boolean; filename: string; totalRows: number }) => void;
+    onError?: (error: { message: string; code: string }) => void;
+}
+
+
+export interface ServerExportOptions extends ExportOptions {
+    fetchData: (filters?: any, selection?: SelectionState) => Promise<{ data: any[]; total: number }>;
+    currentFilters?: any;
+    selection?: SelectionState;
+}
+
+/**
+ * Export data for client-side tables
+ * - If rows are selected, export only selected rows
+ * - Otherwise export all filtered/visible rows
+ * - Only export visible columns
+ */
+export async function exportClientData<TData>(
+    table: Table<TData>,
+    options: ExportOptions,
+): Promise<void> {
+    const { format, filename, onProgress, onComplete, onError } = options;
+
+    try {
+        // Get selected rows if any are selected
+        // const selectedRowIds = Object.keys(table.getState().rowSelection).filter(
+        //     key => table.getState().rowSelection[key]
+        // );
+
+        // const hasSelectedRows = selectedRowIds.length > 0;
+
+        // // Get the rows to export
+        // const rowsToExport = hasSelectedRows ? table.getSelectedRowModel().rows : table.getFilteredRowModel().rows;
+
+        const selectedRows = table.getSelectedRows ? table.getSelectedRows() : [];
+        const hasSelectedRows = selectedRows.length > 0;
+        const rowsToExport = hasSelectedRows ? selectedRows : table.getFilteredRowModel().rows;
+        // Prepare data for export - get all visible columns and their values, excluding hideInExport columns
+        const exportData = rowsToExport.map((row, index) => {
+            onProgress?.({
+                processedRows: index + 1,
+                totalRows: rowsToExport.length,
+                percentage: Math.round(((index + 1) / rowsToExport.length) * 100),
+            });
+
+            const rowData: Record<string, any> = {};
+
+            // Get all visible cells for this row, excluding columns marked as hideInExport
+            row.getVisibleCells().forEach(cell => {
+                const columnDef = cell.column.columnDef
+
+                // Skip columns marked as hideInExport
+                if (columnDef.hideInExport === true) {
+                    return;
+                }
+
+                const header = typeof columnDef.header === 'string' ? columnDef.header : cell.column.id;
+
+                // Use getValue() - it already handles all formatting
+                rowData[header] = cell.getValue() || '';
+            });
+
+            return rowData;
+        });
+
+        // Export the data
+        await exportToFile(exportData, format, filename);
+
+        onComplete?.({
+            success: true,
+            filename: `${filename}.${format === 'excel' ? 'xlsx' : 'csv'}`,
+            totalRows: exportData.length,
+        });
+
+    } catch (error) {
+        console.error('Client export failed:', error);
+        onError?.({
+            message: error instanceof Error ? error.message : 'Export failed',
+            code: 'CLIENT_EXPORT_ERROR',
+        });
+    }
+}
+
+/**
+ * Export data for server-side tables
+ * - Fetch data using provided fetchData function
+ * - Pass selection information to server for filtering
+ * - Export all returned data (server handles selection/filtering)
+ */
+export async function exportServerData<TData>(
+    table: Table<TData>,
+    options: ServerExportOptions,
+): Promise<void> {
+    const { format, filename, fetchData, currentFilters, selection, onProgress, onComplete, onError } = options;
+
+    try {
+        // Initial progress
+        onProgress?.({ });
+
+        // First, get total count to determine if we need chunking
+        const initialResponse = await fetchData({
+            ...currentFilters,
+            pagination: { pageIndex: 0, pageSize: 1 }
+        }, selection);
+
+        if (!initialResponse || !initialResponse.data || !Array.isArray(initialResponse.data)) {
+            throw new Error('Invalid data received from server');
+        }
+
+        const totalRows = initialResponse.total || initialResponse.data.length;
+        const CHUNK_SIZE = 1000; // Fetch 1000 rows per request
+        const needsChunking = totalRows > CHUNK_SIZE;
+
+        let allData: TData[] = [];
+
+        if (needsChunking) {
+            // Fetch data in chunks (no progress events during fetching)
+            const totalPages = Math.ceil(totalRows / CHUNK_SIZE);
+
+            for (let page = 1; page <= totalPages; page++) {
+                // Fetch current chunk
+                const chunkFilters = {
+                    ...currentFilters,
+                    pagination: {
+                        pageIndex: page - 1,
+                        pageSize: CHUNK_SIZE,
+                    },
+                };
+
+                const chunkResponse = await fetchData(chunkFilters, selection);
+
+                if (!chunkResponse || !chunkResponse.data || !Array.isArray(chunkResponse.data)) {
+                    throw new Error(`Failed to fetch chunk ${page}`);
+                }
+
+                allData = [...allData, ...chunkResponse.data];
+
+                // Small delay to prevent overwhelming the server
+                if (page < totalPages) {
+                    await new Promise(resolve => setTimeout(resolve, 100));
+                }
+            }
+        } else {
+            // Small dataset, use single request
+            allData = initialResponse.data;
+        }
+
+        // Get visible columns for proper headers and data processing, excluding hideInExport columns
+        const visibleColumns = table.getVisibleLeafColumns().filter(col => {
+            const columnDef = col.columnDef;
+            return col.getIsVisible() && columnDef.hideInExport !== true;
+        });
+
+        // Prepare data for export with proper column processing
+        const exportData: Record<string, any>[] = [];
+
+        for (let index = 0; index < allData.length; index++) {
+            const rowData = allData[index];
+
+            const exportRow: Record<string, any> = {};
+
+            visibleColumns.forEach(column => {
+                const columnId = column.id;
+                const columnDef = column.columnDef;
+                const header = typeof columnDef.header === 'string'
+                    ? columnDef.header
+                    : columnId;
+
+                // Get value from raw data
+                let value = rowData[columnId];
+
+                // Apply accessorFn if defined
+                if (column.accessorFn && typeof column.accessorFn === 'function') {
+                    value = (column.accessorFn(rowData, index) || '')?.toString() || '';
+                }
+
+                // Convert to string for export
+                if (value === null || value === undefined) {
+                    value = '';
+                } else if (typeof value === 'object') {
+                    value = JSON.stringify(value);
+                } else {
+                    value = String(value);
+                }
+
+                exportRow[header] = value;
+            });
+
+            exportData.push(exportRow);
+        }
+
+        await exportToFile(exportData, format, filename);
+
+        onComplete?.({
+            success: true,
+            filename: `${filename}.${format === 'excel' ? 'xlsx' : 'csv'}`,
+            totalRows: exportData.length,
+        });
+
+    } catch (error) {
+        console.error('Server export failed:', error);
+        onError?.({
+            message: error instanceof Error ? error.message : 'Export failed',
+            code: 'SERVER_EXPORT_ERROR',
+        });
+    }
+}
+
+/**
+ * Export data to file (CSV or Excel)
+ */
+async function exportToFile(
+    data: Record<string, any>[],
+    format: 'csv' | 'excel',
+    filename: string,
+): Promise<void> {
+    if (data.length === 0) {
+        throw new Error('No data to export');
+    }
+
+    if (format === 'csv') {
+        const csv = convertToCSV(data);
+        downloadFile(csv, `${filename}.csv`, 'text/csv');
+    } else {
+        const workbook = XLSX.utils.book_new();
+        const worksheet = XLSX.utils.json_to_sheet(data);
+        XLSX.utils.book_append_sheet(workbook, worksheet, 'Data');
+
+        const excelBuffer = XLSX.write(workbook, { bookType: 'xlsx', type: 'array' });
+        const blob = new Blob([excelBuffer], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' });
+        downloadFile(blob, `${filename}.xlsx`, 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
+    }
+}
+
+/**
+ * Convert data to CSV format
+ */
+function convertToCSV(data: Record<string, any>[]): string {
+    if (data.length === 0) return '';
+
+    const headers = Object.keys(data[0]);
+    const csvRows = [headers.join(',')];
+
+    for (const row of data) {
+        const values = headers.map(header => {
+            const value = row[header] || '';
+            // Escape quotes and wrap in quotes if contains comma or quote
+            if (typeof value === 'string' && (value.includes(',') || value.includes('"') || value.includes('\n'))) {
+                return `"${value.replace(/"/g, '""')}"`;
+            }
+            return value;
+        });
+        csvRows.push(values.join(','));
+    }
+
+    return csvRows.join('\n');
+}
+
+/**
+ * Download file to user's device
+ */
+function downloadFile(content: string | Blob, filename: string, mimeType: string): void {
+    const blob = content instanceof Blob ? content : new Blob([content], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = filename;
+    link.style.display = 'none';
+
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+
+    URL.revokeObjectURL(url);
+}

package/src/lib/utils/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Utility functions for DataTable components
+ */
+
+// Styling utilities
+export * from './styling-helpers';
+
+// Table utilities
+export * from './table-helpers';
+
+// Column utilities
+export * from './column-helpers';
+
+// Export utilities
+export * from './export-utils';
+
+// Special columns utilities
+export * from './special-columns.utils';
+
+// Debounced fetch utilities
+export * from './debounced-fetch.utils';
+
+// Slot helper utilities
+export * from './slot-helpers';
+
+// Logging utilities
+export * from './logger';

package/src/lib/utils/logger.ts

@@ -0,0 +1,203 @@
+/**
+ * Logging utilities for the DataTable package.
+ *
+ * Provides a lightweight wrapper around `console` that can be configured globally
+ * or per-instance to help troubleshoot behaviour in consuming applications.
+ */
+
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+
+interface ConsoleLike {
+    debug?: (...args: unknown[]) => void;
+    info?: (...args: unknown[]) => void;
+    warn?: (...args: unknown[]) => void;
+    error?: (...args: unknown[]) => void;
+    log?: (...args: unknown[]) => void;
+}
+
+export interface DataTableLoggingOptions {
+    /**
+     * Whether logging should be enabled.
+     */
+    enabled?: boolean;
+    /**
+     * Minimum level that will be emitted. Defaults to `warn`.
+     */
+    level?: LogLevel;
+    /**
+     * Prefix prepended to every log message. Defaults to `DataTable`.
+     */
+    prefix?: string;
+    /**
+     * Optional scope that will be appended after the prefix when present.
+     */
+    scope?: string;
+    /**
+     * Include an ISO timestamp ahead of each log line.
+     */
+    includeTimestamp?: boolean;
+    /**
+     * A custom logger implementation. Defaults to `console`.
+     */
+    logger?: ConsoleLike;
+}
+
+type LoggerInput = boolean | DataTableLoggingOptions;
+
+type ResolvedLoggerConfig = Required<Omit<DataTableLoggingOptions, 'logger'>> & {
+    logger: ConsoleLike;
+};
+
+type LogMethodLevel = Exclude<LogLevel, 'silent'>;
+
+const LOG_LEVEL_ORDER: Record<LogLevel, number> = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+};
+
+const defaultConsole: ConsoleLike = typeof console !== 'undefined'
+    ? console
+    : {
+        log: () => undefined,
+        debug: () => undefined,
+        info: () => undefined,
+        warn: () => undefined,
+        error: () => undefined,
+    };
+
+let globalConfig: ResolvedLoggerConfig = {
+    enabled: false,
+    level: 'warn',
+    prefix: 'DataTable',
+    scope: '',
+    includeTimestamp: false,
+    logger: defaultConsole,
+};
+
+const isLevelEnabled = (level: LogMethodLevel, config: ResolvedLoggerConfig) => {
+    if (!config.enabled) {
+        return false;
+    }
+    return LOG_LEVEL_ORDER[level] <= LOG_LEVEL_ORDER[config.level];
+};
+
+const formatPrefix = (level: LogMethodLevel, config: ResolvedLoggerConfig) => {
+    const segments: string[] = [];
+    if (config.prefix) {
+        segments.push(config.prefix);
+    }
+    if (config.scope) {
+        segments.push(config.scope);
+    }
+    const prefix = segments.length > 0 ? `[${segments.join(':')}]` : '';
+    return config.includeTimestamp
+        ? `[${new Date().toISOString()}]${prefix ? ` ${prefix}` : ''} [${level.toUpperCase()}]`
+        : `${prefix ? `${prefix} ` : ''}[${level.toUpperCase()}]`;
+};
+
+const getConsoleMethod = (level: LogMethodLevel, logger: ConsoleLike) => {
+    const methodName = level === 'debug' ? 'debug' : level;
+    return logger[methodName] ?? logger.log ?? defaultConsole.log ?? (() => undefined);
+};
+
+const normaliseInput = (input?: LoggerInput): DataTableLoggingOptions => {
+    if (typeof input === 'boolean') {
+        return { enabled: input };
+    }
+    return input ?? {};
+};
+
+const resolveConfig = (
+    scope: string | undefined,
+    input?: LoggerInput,
+    parent?: ResolvedLoggerConfig,
+): ResolvedLoggerConfig => {
+    const overrides = normaliseInput(input);
+    const base = parent ?? globalConfig;
+
+    return {
+        enabled: overrides.enabled ?? base.enabled,
+        level: overrides.level ?? base.level,
+        prefix: overrides.prefix ?? base.prefix,
+        scope: overrides.scope ?? scope ?? base.scope ?? '',
+        includeTimestamp: overrides.includeTimestamp ?? base.includeTimestamp,
+        logger: overrides.logger ?? base.logger ?? defaultConsole,
+    };
+};
+
+export interface LoggerInstance {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    /**
+     * Create a new logger that inherits configuration and extends the scope.
+     */
+    child: (scope: string, overrides?: LoggerInput) => LoggerInstance;
+    /**
+     * Check whether a level would emit given current configuration.
+     */
+    isLevelEnabled: (level: LogMethodLevel) => boolean;
+    /**
+     * Access the resolved configuration for inspection.
+     */
+    config: ResolvedLoggerConfig;
+}
+
+const createLoggerMethods = (config: ResolvedLoggerConfig): Omit<LoggerInstance, 'child' | 'isLevelEnabled' | 'config'> => {
+    const logWithLevel = (level: LogMethodLevel) => {
+        const consoleMethod = getConsoleMethod(level, config.logger);
+        return (...args: unknown[]) => {
+            if (!isLevelEnabled(level, config)) {
+                return;
+            }
+            const prefix = formatPrefix(level, config);
+            consoleMethod(prefix, ...args);
+        };
+    };
+
+    return {
+        debug: logWithLevel('debug'),
+        info: logWithLevel('info'),
+        warn: logWithLevel('warn'),
+        error: logWithLevel('error'),
+    };
+};
+
+/**
+ * Create a new logger instance. Configuration cascades from the global config unless overridden.
+ */
+export const createLogger = (scope?: string, input?: LoggerInput, parentConfig?: ResolvedLoggerConfig): LoggerInstance => {
+    const resolvedConfig = resolveConfig(scope, input, parentConfig);
+    const methods = createLoggerMethods(resolvedConfig);
+
+    const child = (childScope: string, overrides?: LoggerInput) => {
+        const combinedScope = childScope
+            ? (resolvedConfig.scope ? `${resolvedConfig.scope}.${childScope}` : childScope)
+            : resolvedConfig.scope;
+        return createLogger(combinedScope, overrides, resolvedConfig);
+    };
+
+    return {
+        ...methods,
+        child,
+        isLevelEnabled: (level: LogMethodLevel) => isLevelEnabled(level, resolvedConfig),
+        config: resolvedConfig,
+    };
+};
+
+/**
+ * Configure the global logger defaults for every DataTable instance.
+ */
+export const configureDataTableLogging = (options: DataTableLoggingOptions) => {
+    globalConfig = resolveConfig(options.scope, options, globalConfig);
+};
+
+/**
+ * Read the current global logging configuration.
+ */
+export const getDataTableLoggingConfig = (): ResolvedLoggerConfig => ({ ...globalConfig });
+