@pagamio/frontend-commons-lib 0.8.212 → 0.8.214

package/lib/data-table-v2/types/index.d.ts

@@ -0,0 +1,296 @@
+/**
+ * @fileoverview DataTable V2 Types - TanStack Table based
+ */
+import type { ColumnFiltersState, PaginationState, Row, SortingState, VisibilityState } from '@tanstack/react-table';
+import type { ReactNode } from 'react';
+/**
+ * Base column definition extending TanStack's ColumnDef
+ */
+export interface DataTableColumn<TData> {
+    /** Unique column identifier */
+    id: string;
+    /** Column header text or component */
+    header?: string | ReactNode | ((props: {
+        column: unknown;
+    }) => ReactNode);
+    /** Data accessor key */
+    accessorKey?: keyof TData;
+    /** Custom accessor function */
+    accessorFn?: (row: TData) => unknown;
+    /** Custom cell renderer */
+    cell?: (props: {
+        row: Row<TData>;
+        getValue: () => unknown;
+    }) => ReactNode;
+    /** Enable sorting for this column */
+    enableSorting?: boolean;
+    /** Enable filtering for this column */
+    enableFiltering?: boolean;
+    /** Enable column hiding */
+    enableHiding?: boolean;
+    /** Column width (CSS value) */
+    size?: number;
+    /** Minimum column width */
+    minSize?: number;
+    /** Maximum column width */
+    maxSize?: number;
+    /** Column alignment */
+    align?: 'left' | 'center' | 'right';
+    /** Whether column is pinned */
+    pinned?: 'left' | 'right' | false;
+    /** Custom filter function */
+    filterFn?: 'includesString' | 'equalsString' | 'arrIncludes' | 'arrIncludesAll' | 'arrIncludesSome' | 'equals' | 'weakEquals' | 'inNumberRange' | ((row: Row<TData>, columnId: string, filterValue: unknown) => boolean);
+    /** Aggregation function for grouped data */
+    aggregationFn?: 'sum' | 'min' | 'max' | 'extent' | 'mean' | 'median' | 'unique' | 'uniqueCount' | 'count';
+    /** Footer content */
+    footer?: string | ReactNode | ((props: {
+        column: unknown;
+    }) => ReactNode);
+}
+/**
+ * Row selection options
+ */
+export interface RowSelectionOptions<TData> {
+    /** Enable row selection */
+    enabled?: boolean;
+    /** Selection mode */
+    mode?: 'single' | 'multiple';
+    /** Enable select all */
+    enableSelectAll?: boolean;
+    /** Callback when selection changes */
+    onSelectionChange?: (selectedRows: TData[]) => void;
+    /** Get row ID for selection tracking */
+    getRowId?: (row: TData, index: number) => string;
+    /** Pre-selected row IDs */
+    selectedRowIds?: Record<string, boolean>;
+}
+/**
+ * Pagination options
+ */
+export interface PaginationOptions {
+    /** Enable pagination */
+    enabled?: boolean;
+    /** Items per page */
+    pageSize?: number;
+    /** Page size options */
+    pageSizeOptions?: number[];
+    /** Current page index (0-based) */
+    pageIndex?: number;
+    /** Total row count (for server-side pagination) */
+    totalRows?: number;
+    /** Show page size selector */
+    showPageSizeSelector?: boolean;
+    /** Show page info (e.g., "1-10 of 100") */
+    showPageInfo?: boolean;
+    /** Callback when pagination changes */
+    onPaginationChange?: (pagination: PaginationState) => void;
+    /** Server-side pagination */
+    serverSide?: boolean;
+}
+/**
+ * Sorting options
+ */
+export interface SortingOptions {
+    /** Enable sorting */
+    enabled?: boolean;
+    /** Initial sorting state */
+    initialSorting?: SortingState;
+    /** Allow multi-column sorting */
+    enableMultiSort?: boolean;
+    /** Callback when sorting changes */
+    onSortingChange?: (sorting: SortingState) => void;
+    /** Server-side sorting */
+    serverSide?: boolean;
+}
+/**
+ * Filtering options
+ */
+export interface FilteringOptions {
+    /** Enable filtering */
+    enabled?: boolean;
+    /** Enable global filter/search */
+    enableGlobalFilter?: boolean;
+    /** Enable column filters */
+    enableColumnFilters?: boolean;
+    /** Initial filter state */
+    initialFilters?: ColumnFiltersState;
+    /** Global filter placeholder */
+    globalFilterPlaceholder?: string;
+    /** Callback when filters change */
+    onFiltersChange?: (filters: ColumnFiltersState) => void;
+    /** Debounce time for filter input (ms) */
+    filterDebounceMs?: number;
+    /** Server-side filtering */
+    serverSide?: boolean;
+}
+/**
+ * Column visibility options
+ */
+export interface ColumnVisibilityOptions {
+    /** Enable column visibility toggle */
+    enabled?: boolean;
+    /** Initial visibility state */
+    initialVisibility?: VisibilityState;
+    /** Columns that cannot be hidden */
+    alwaysVisible?: string[];
+    /** Callback when visibility changes */
+    onVisibilityChange?: (visibility: VisibilityState) => void;
+}
+/**
+ * Export options
+ */
+export interface ExportOptions {
+    /** Enable export functionality */
+    enabled?: boolean;
+    /** Export formats to enable */
+    formats?: ('csv' | 'excel' | 'json' | 'pdf')[];
+    /** Export filename (without extension) */
+    filename?: string;
+    /** Columns to include in export (by ID) */
+    includeColumns?: string[];
+    /** Columns to exclude from export (by ID) */
+    excludeColumns?: string[];
+    /** Custom export handler */
+    onExport?: (format: string, data: unknown[]) => void;
+}
+/**
+ * Row actions configuration
+ */
+export interface RowAction<TData> {
+    /** Action identifier */
+    id: string;
+    /** Action label */
+    label: string;
+    /** Action icon */
+    icon?: ReactNode;
+    /** Action handler */
+    onClick: (row: TData) => void;
+    /** Whether action is disabled */
+    disabled?: boolean | ((row: TData) => boolean);
+    /** Whether action is hidden */
+    hidden?: boolean | ((row: TData) => boolean);
+    /** Action variant for styling */
+    variant?: 'default' | 'primary' | 'danger';
+}
+/**
+ * Bulk actions configuration
+ */
+export interface BulkAction<TData> {
+    /** Action identifier */
+    id: string;
+    /** Action label */
+    label: string;
+    /** Action icon */
+    icon?: ReactNode;
+    /** Action handler with selected rows */
+    onClick: (selectedRows: TData[]) => void;
+    /** Whether action is disabled */
+    disabled?: boolean;
+    /** Action variant */
+    variant?: 'default' | 'primary' | 'danger';
+}
+/**
+ * Main DataTable props
+ */
+export interface DataTableProps<TData> {
+    /** Table data */
+    data: TData[];
+    /** Column definitions */
+    columns: DataTableColumn<TData>[];
+    /** Row selection options */
+    rowSelection?: RowSelectionOptions<TData>;
+    /** Pagination options */
+    pagination?: PaginationOptions;
+    /** Sorting options */
+    sorting?: SortingOptions;
+    /** Filtering options */
+    filtering?: FilteringOptions;
+    /** Column visibility options */
+    columnVisibility?: ColumnVisibilityOptions;
+    /** Export options */
+    export?: ExportOptions;
+    /** Row actions */
+    rowActions?: RowAction<TData>[];
+    /** Bulk actions */
+    bulkActions?: BulkAction<TData>[];
+    /** Loading state */
+    loading?: boolean;
+    /** Error state */
+    error?: Error | string | null;
+    /** Empty state message */
+    emptyMessage?: string | ReactNode;
+    /** Table title */
+    title?: string;
+    /** Table description */
+    description?: string;
+    /** Enable striped rows */
+    striped?: boolean;
+    /** Enable hover highlight */
+    hoverable?: boolean;
+    /** Enable bordered cells */
+    bordered?: boolean;
+    /** Compact mode (smaller padding) */
+    compact?: boolean;
+    /** Sticky header */
+    stickyHeader?: boolean;
+    /** Maximum height (enables vertical scroll) */
+    maxHeight?: string | number;
+    /** Row click handler */
+    onRowClick?: (row: TData) => void;
+    /** Row double-click handler */
+    onRowDoubleClick?: (row: TData) => void;
+    /** Get row ID */
+    getRowId?: (row: TData, index: number) => string;
+    /** Custom row className */
+    rowClassName?: string | ((row: TData, index: number) => string);
+    /** Wrapper className */
+    className?: string;
+    /** Sub-component classNames */
+    classNames?: DataTableClassNames;
+    /** Custom header content */
+    headerContent?: ReactNode;
+    /** Custom footer content */
+    footerContent?: ReactNode;
+    /** Data fetching/refresh handler */
+    onRefresh?: () => void;
+}
+/**
+ * Custom classNames for DataTable sub-components
+ */
+export interface DataTableClassNames {
+    wrapper?: string;
+    header?: string;
+    toolbar?: string;
+    table?: string;
+    thead?: string;
+    tbody?: string;
+    tfoot?: string;
+    tr?: string;
+    th?: string;
+    td?: string;
+    pagination?: string;
+    search?: string;
+    filters?: string;
+    empty?: string;
+    loading?: string;
+    error?: string;
+}
+/**
+ * Server-side data response format
+ */
+export interface DataTableServerResponse<TData> {
+    data: TData[];
+    total: number;
+    page?: number;
+    pageSize?: number;
+}
+/**
+ * Server-side request parameters
+ */
+export interface DataTableServerRequest {
+    page: number;
+    pageSize: number;
+    sorting?: SortingState;
+    filters?: ColumnFiltersState;
+    globalFilter?: string;
+}

package/lib/data-table-v2/types/index.js

@@ -0,0 +1 @@
+export {};

package/lib/data-table-v2/utils/export.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview DataTable V2 Export Utilities
+ */
+import type { Row } from '@tanstack/react-table';
+export interface ExportConfig {
+    filename?: string;
+    includeColumns?: string[];
+    excludeColumns?: string[];
+    dateFormat?: string;
+}
+/**
+ * Export data to CSV format
+ */
+export declare function exportToCSV<TData>(rows: Row<TData>[], columns: string[], config?: ExportConfig): string;
+/**
+ * Export data to JSON format
+ */
+export declare function exportToJSON<TData>(rows: Row<TData>[], columns: string[]): string;
+/**
+ * Download file to user's device
+ */
+export declare function downloadFile(content: string, filename: string, mimeType: string): void;
+/**
+ * Export handler factory
+ */
+export declare function createExportHandler<TData>(getRows: () => Row<TData>[], getColumns: () => string[], config?: ExportConfig): (format: "csv" | "json" | "excel" | "pdf") => void;

package/lib/data-table-v2/utils/export.js

@@ -0,0 +1,92 @@
+/**
+ * Export data to CSV format
+ */
+export function exportToCSV(rows, columns, config = {}) {
+    const { dateFormat = 'YYYY-MM-DD' } = config;
+    const headers = columns.join(',');
+    const csvRows = rows.map((row) => columns
+        .map((col) => {
+        const value = row.getValue(col);
+        return formatCSVValue(value, dateFormat);
+    })
+        .join(','));
+    return [headers, ...csvRows].join('\n');
+}
+/**
+ * Export data to JSON format
+ */
+export function exportToJSON(rows, columns) {
+    const data = rows.map((row) => {
+        const rowData = {};
+        columns.forEach((col) => {
+            rowData[col] = row.getValue(col);
+        });
+        return rowData;
+    });
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * Format value for CSV export
+ */
+function formatCSVValue(value, dateFormat) {
+    void dateFormat;
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (value instanceof Date) {
+        return value.toISOString().split('T')[0];
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    const stringValue = String(value);
+    // Escape quotes and wrap in quotes if contains special characters
+    if (stringValue.includes(',') || stringValue.includes('"') || stringValue.includes('\n')) {
+        return `"${stringValue.replace(/"/g, '""')}"`;
+    }
+    return stringValue;
+}
+/**
+ * Download file to user's device
+ */
+export function downloadFile(content, filename, mimeType) {
+    const blob = new Blob([content], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = filename;
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+}
+/**
+ * Export handler factory
+ */
+export function createExportHandler(getRows, getColumns, config = {}) {
+    return (format) => {
+        const rows = getRows();
+        const columns = getColumns();
+        const filename = config.filename ?? `export-${Date.now()}`;
+        switch (format) {
+            case 'csv': {
+                const csv = exportToCSV(rows, columns, config);
+                downloadFile(csv, `${filename}.csv`, 'text/csv;charset=utf-8;');
+                break;
+            }
+            case 'json': {
+                const json = exportToJSON(rows, columns);
+                downloadFile(json, `${filename}.json`, 'application/json');
+                break;
+            }
+            case 'excel':
+                console.warn('Excel export requires additional library (xlsx). Using CSV fallback.');
+                const csv = exportToCSV(rows, columns, config);
+                downloadFile(csv, `${filename}.csv`, 'text/csv;charset=utf-8;');
+                break;
+            case 'pdf':
+                console.warn('PDF export requires additional library (jspdf). Not implemented.');
+                break;
+        }
+    };
+}

package/lib/data-table-v2/utils/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @fileoverview DataTable V2 Utilities
+ */
+export { exportToCSV, exportToJSON, downloadFile, createExportHandler, type ExportConfig } from './export';

package/lib/data-table-v2/utils/index.js

@@ -0,0 +1,4 @@
+/**
+ * @fileoverview DataTable V2 Utilities
+ */
+export { exportToCSV, exportToJSON, downloadFile, createExportHandler } from './export';

package/lib/index.d.ts

@@ -20,3 +20,7 @@ export * from './rbac';
 export { useImageUpload } from './shared/hooks/useImageUpload';
 export type { UseImageUploadProps, UploadResponse } from './shared/hooks/useImageUpload';
 export * from './feedback';
+export { BaseChart, BarChart, LineChart, AreaChart, DonutChart, PieChart, HeatmapChart, RadialChart, MixedChart, StatCard, MetricCard, InfoCard, CardGrid, StatCardGrid, MetricCardGrid, TransactionListCard, TopItemsCard, visualRegistryV2, VisualType, getVisualComponent, isRegisteredVisual, getRegisteredVisualTypes, registerVisual, DashboardWrapperV2, useChartData, useChartQueryData, } from './dashboard-visuals-v2';
+export type { BaseChartProps, BarChartProps, LineChartProps, AreaChartProps, DonutChartProps, PieChartProps, HeatmapChartProps, RadialChartProps, MixedChartProps, ChartQueryProps, ChartDataPoint, ChartSeries, StatCardProps, MetricCardProps, InfoCardProps, CardGridProps, TransactionListCardProps, TopItemsCardProps, DashboardWrapperV2Props, } from './dashboard-visuals-v2';
+export { DataTable, DataTableHeader, DataTableBody, DataTablePagination, DataTableSearch, DataTableToolbar, DataTableEmpty, DataTableLoading, DataTableError, DataTableRowActions, useTableData, usePaginatedTableData, exportToCSV, exportToJSON, downloadFile, createExportHandler, } from './data-table-v2';
+export type { DataTableProps, DataTableColumn, DataTableClassNames, RowSelectionOptions, PaginationOptions, SortingOptions, FilteringOptions, ColumnVisibilityOptions, ExportOptions, RowAction, BulkAction, DataTableServerResponse, DataTableServerRequest, UseTableDataOptions, UsePaginatedTableDataOptions, UseTableDataResult, UsePaginatedTableDataResult, } from './data-table-v2';

package/lib/index.js

@@ -30,3 +30,26 @@ export * from './rbac';
 export { useImageUpload } from './shared/hooks/useImageUpload';
 // Feedback System
 export * from './feedback';
+// ============================================
+// V2 Components (ApexCharts + TanStack Table)
+// ============================================
+// Dashboard Visuals V2 - ApexCharts based
+export { 
+// Charts
+BaseChart, BarChart, LineChart, AreaChart, DonutChart, PieChart, HeatmapChart, RadialChart, MixedChart, 
+// Cards
+StatCard, MetricCard, InfoCard, CardGrid, StatCardGrid, MetricCardGrid, TransactionListCard, TopItemsCard, 
+// Registry
+visualRegistryV2, VisualType, getVisualComponent, isRegisteredVisual, getRegisteredVisualTypes, registerVisual, 
+// Wrapper
+DashboardWrapperV2, 
+// Hooks
+useChartData, useChartQueryData, } from './dashboard-visuals-v2';
+// DataTable V2 - TanStack Table based
+export { DataTable, 
+// Sub-components
+DataTableHeader, DataTableBody, DataTablePagination, DataTableSearch, DataTableToolbar, DataTableEmpty, DataTableLoading, DataTableError, DataTableRowActions, 
+// Hooks (TanStack Query)
+useTableData, usePaginatedTableData, 
+// Utils
+exportToCSV, exportToJSON, downloadFile, createExportHandler, } from './data-table-v2';