@jmruthers/pace-core 0.6.1 → 0.6.3

package/src/components/DataTable/components/DataTableErrorBoundary.tsx

@@ -42,6 +42,11 @@ interface DataTableErrorBoundaryProps {
 // ERROR BOUNDARY COMPONENT
 // ============================================================================
 
+/**
+ * Error boundary component for DataTable.
+ * Catches errors in the DataTable component tree and displays a fallback UI.
+ * Provides error recovery with retry functionality.
+ */
 export class DataTableErrorBoundary extends Component<
   DataTableErrorBoundaryProps,
   ErrorBoundaryState
@@ -195,6 +200,12 @@ export class DataTableErrorBoundary extends Component<
 // HOOK FOR ERROR BOUNDARY
 // ============================================================================
 
+/**
+ * Hook for programmatically triggering error boundary reset.
+ * Useful for error recovery in DataTable components.
+ * 
+ * @returns Object with error state and reset function
+ */
 export function useDataTableErrorBoundary() {
   const [error, setError] = React.useState<Error | null>(null);
 

package/src/components/DataTable/components/DataTableLayout.tsx

@@ -0,0 +1,559 @@
+import React from 'react';
+import { Edit, Trash, ChevronUp, ChevronDown, ChevronsUpDown } from 'lucide-react';
+import type { Table } from '@tanstack/react-table';
+import { cn } from '../../../utils/core/cn';
+import { Button } from '../../Button/Button';
+import { DataTableToolbar } from './DataTableToolbar';
+import { UnifiedTableBody } from './UnifiedTableBody';
+import { PaginationControls, EnhancedPaginationControls } from './PaginationControls';
+import { DataTableModals } from './DataTableModals';
+import { announceSortChange } from '../utils/a11yUtils';
+import { exportToCSVWithTableRows } from '../utils/exportUtils';
+import { getTableClasses } from '../styles';
+import { toast } from '../../../hooks/useToast';
+import type {
+  AggregateConfig,
+  DataRecord,
+  DataTableAction,
+  DataTableColumn,
+  DataTableRBACConfig,
+  EmptyStateConfig,
+  ExportOptions,
+  HierarchicalConfig,
+  NormalizedDataTableFeatureConfig,
+  PaginationMode,
+} from '../types';
+import type { DataTableState, DataTableStateActions } from '../hooks/useDataTableState';
+import type { UseDataTablePermissionsReturn } from '../hooks/useDataTablePermissions';
+import type { GetRowId } from '../types';
+import type { ImportModalConfig } from './ImportModal';
+import type { UseDataTableDataPipelineResult } from '../hooks/useDataTableDataPipeline';
+import type { UseKeyboardNavigationReturn } from '../hooks/useKeyboardNavigation';
+import type { Column } from '@tanstack/react-table';
+import type { createLogger } from '../../../utils/core/logger';
+
+interface DataTableLayoutProps<TData extends DataRecord> {
+  table: Table<TData>;
+  title?: string;
+  description?: string;
+  variant: 'default' | 'compact' | 'spacious';
+  className?: string;
+  columns: DataTableColumn<TData>[];
+  secureFeatures: NormalizedDataTableFeatureConfig;
+  enhancedPagination: boolean;
+  searchQuery: string;
+  onSearch: (value: string) => void;
+  state: DataTableState<TData>;
+  stateActions: DataTableStateActions<TData>;
+  rowSelection: Record<string, boolean>;
+  onCreateRow?: (data: Partial<TData>) => void;
+  onEditRow?: (row: TData, data: Partial<TData>) => void;
+  onImport?: (data: TData[]) => void | Promise<void>;
+  onExport?: (options: ExportOptions<TData>) => void | Promise<void>;
+  onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
+  rbac: DataTableRBACConfig;
+  permissions: UseDataTablePermissionsReturn['permissions'];
+  effectiveActions: DataTableAction<TData>[];
+  finalPageSizeOptions: number[];
+  finalPaginationMode: PaginationMode;
+  finalDataCount: number;
+  isLoading: boolean;
+  finalTableData: TData[];
+  aggregates: AggregateConfig[];
+  resolvedGetRowId: GetRowId<TData>;
+  data: TData[];
+  emptyState?: EmptyStateConfig | React.ReactElement<any>;
+  virtualHeight: number;
+  hierarchical?: HierarchicalConfig;
+  hierarchicalState: UseDataTableDataPipelineResult<TData>['hierarchicalState'];
+  logger: ReturnType<typeof createLogger>;
+  secureHandlers: {
+    onEditRow?: ((row: TData, data: Partial<TData>) => void) | undefined;
+    onDeleteRow?: ((row: TData) => void) | undefined;
+    onCreateRow?: ((data: Partial<TData>) => void) | undefined;
+    onImport?: ((data: TData[]) => void | Promise<void>) | undefined;
+    onExport?: ((options: ExportOptions<TData>) => void | Promise<void>) | undefined;
+    onDeleteSelected?: ((selectedRows: Record<string, boolean>) => void) | undefined;
+  };
+  importModalConfig?: ImportModalConfig;
+  keyboardNavigation: UseKeyboardNavigationReturn;
+  lastFocusedElementRef: React.RefObject<HTMLElement | null>;
+}
+
+const SYSTEM_COLUMN_IDS = new Set(['select', 'actions']);
+
+/**
+ * Main layout component for DataTable.
+ * Orchestrates all DataTable UI components including toolbar, body, pagination, and modals.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - DataTable layout configuration
+ * @returns The complete DataTable UI layout
+ */
+export function DataTableLayout<TData extends DataRecord>({
+  table,
+  title,
+  description,
+  variant,
+  className,
+  columns,
+  secureFeatures,
+  enhancedPagination,
+  searchQuery,
+  onSearch,
+  state,
+  stateActions,
+  rowSelection,
+  onCreateRow,
+  onEditRow,
+  onImport,
+  onExport,
+  onDeleteSelected,
+  rbac,
+  permissions,
+  effectiveActions,
+  finalPageSizeOptions,
+  finalPaginationMode,
+  finalDataCount,
+  isLoading,
+  finalTableData,
+  aggregates,
+  resolvedGetRowId,
+  data,
+  emptyState,
+  virtualHeight,
+  hierarchical,
+  hierarchicalState,
+  logger,
+  secureHandlers,
+  importModalConfig,
+  keyboardNavigation,
+  lastFocusedElementRef,
+}: DataTableLayoutProps<TData>) {
+  const handleExport = async () => {
+    try {
+      const tableRows = table.getFilteredRowModel().rows;
+      const tableColumns = table.getAllColumns();
+      const visibleTableColumns = tableColumns.filter((col) => !SYSTEM_COLUMN_IDS.has(col.id) && col.getIsVisible());
+
+      const visibleColumns: DataTableColumn<TData>[] = [];
+      const columnIdToTableColumn = new Map<string, Column<TData>>();
+
+      visibleTableColumns.forEach((tableCol) => {
+        const originalCol = columns.find((col) => {
+          const colId = col.id || col.accessorKey;
+          return colId && String(colId) === tableCol.id;
+        });
+
+        if (!originalCol) return;
+
+        columnIdToTableColumn.set(tableCol.id, tableCol);
+        visibleColumns.push(originalCol);
+      });
+
+      const timestamp = new Date().toISOString().split('T')[0];
+      const filename = title
+        ? `${title.replace(/[^a-z0-9]/gi, '_').toLowerCase()}_${timestamp}.csv`
+        : `data_export_${timestamp}.csv`;
+
+      const exportOptions: ExportOptions<TData> = {
+        tableRows,
+        allColumns: columns,
+        visibleColumns,
+        columnIdToTableColumn,
+        data,
+        filename,
+        table,
+      };
+
+      if (secureHandlers.onExport) {
+        await secureHandlers.onExport(exportOptions);
+        return;
+      }
+
+      const exportColumns: Array<{
+        header?: string;
+        id?: string;
+        accessorKey?: string;
+        accessorFn?: (row: any) => any;
+        editAccessorKey?: string;
+        isIdColumn?: boolean;
+      }> = exportOptions.visibleColumns.map((col) => {
+        const colId = col.id || col.accessorKey;
+        const hasAccessorFn = 'accessorFn' in col && (col as any).accessorFn;
+
+        return {
+          ...col,
+          header: typeof col.header === 'string'
+            ? col.header
+            : col.accessorKey || colId || 'Column',
+          id: colId ? String(colId) : undefined,
+          accessorFn: hasAccessorFn ? (col as any).accessorFn : undefined,
+        };
+      });
+
+      await exportToCSVWithTableRows(
+        exportOptions.tableRows,
+        exportColumns,
+        exportOptions.columnIdToTableColumn,
+        exportOptions.filename
+      );
+
+      toast({
+        title: 'Export Successful',
+        description: `Data exported to ${exportOptions.filename}`,
+        variant: 'default',
+      });
+    } catch (error) {
+      logger.error('Failed to export data:', error);
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
+      toast({
+        title: 'Export Failed',
+        description: `Failed to export data: ${errorMessage}`,
+        variant: 'destructive',
+      });
+    }
+  };
+
+  const PaginationComponent = enhancedPagination || finalPaginationMode !== 'client'
+    ? EnhancedPaginationControls
+    : PaginationControls;
+
+  const visibleColumns = table?.getVisibleFlatColumns() || [];
+  const dataColumns = visibleColumns.filter((col) => !SYSTEM_COLUMN_IDS.has(col.id)).length;
+  const hasSelectColumn = visibleColumns.some((col) => col.id === 'select');
+  const hasActionsColumn = visibleColumns.some((col) => col.id === 'actions');
+
+  return (
+    <>
+      <table
+        className={getTableClasses({
+          isFixed: false,
+          variant,
+          className: cn('border-collapse relative w-full', className),
+        })}
+        aria-label={title}
+        aria-describedby={description ? 'table-description' : undefined}
+        aria-busy={isLoading ? 'true' : 'false'}
+      >
+        <caption className="text-left pb-2">
+          {(title || description) && (
+            <>
+              {title && <h2>{title}</h2>}
+              {description && <p id="table-description">{description}</p>}
+            </>
+          )}
+          <DataTableToolbar
+            features={secureFeatures}
+            globalFilter={searchQuery}
+            onGlobalFilterChange={onSearch}
+            columns={columns}
+            grouping={state.grouping}
+            onGroupByChange={(columnId) => {
+              stateActions.setGrouping(columnId ? [columnId] : []);
+            }}
+            tableColumns={table?.getAllColumns() || []}
+            onColumnVisibilityChange={(columnId: string, visible: boolean) => {
+              stateActions.setColumnVisibility({ ...state.columnVisibility, [columnId]: visible });
+            }}
+            onCreateRow={secureFeatures.creation && secureHandlers.onCreateRow ? () => stateActions.setCreating(true) : undefined}
+            onImportClick={() => {
+              if (document.activeElement instanceof HTMLElement) {
+                lastFocusedElementRef.current = document.activeElement;
+              }
+              stateActions.setImportModal(true);
+            }}
+            onExport={handleExport}
+            rowSelection={rowSelection}
+            onDeleteSelected={
+              secureHandlers.onDeleteSelected
+                ? async (selectedRows: Record<string, boolean>) => {
+                    const selectedCount = Object.values(selectedRows).filter(Boolean).length;
+                    if (selectedCount === 0) {
+                      toast({
+                        title: 'No Selection',
+                        description: 'Please select at least one row to delete',
+                        variant: 'default',
+                      });
+                      return;
+                    }
+                    try {
+                      const result = secureHandlers.onDeleteSelected!(selectedRows) as any;
+                      if (result !== undefined && result !== null && typeof result === 'object' && typeof result.then === 'function') {
+                        await result;
+                      }
+                      toast({
+                        title: 'Delete Successful',
+                        description: `Successfully deleted ${selectedCount} ${selectedCount === 1 ? 'row' : 'rows'}`,
+                        variant: 'default',
+                      });
+                    } catch (error) {
+                      logger.error('Bulk delete error:', error);
+                      toast({
+                        title: 'Delete Failed',
+                        description: error instanceof Error ? error.message : 'Failed to delete selected rows',
+                        variant: 'destructive',
+                      });
+                    }
+                  }
+                : undefined
+            }
+            onToggleFilterRow={() => stateActions.setFilterRow(!state.showFilterRow)}
+            showFilterRow={state.showFilterRow}
+            rbac={rbac}
+            permissions={permissions}
+          />
+        </caption>
+
+        <colgroup>
+          {hasSelectColumn && <col span={1} data-col-type="select" />}
+          <col span={dataColumns} data-col-type="data" />
+          {hasActionsColumn && <col span={1} data-col-type="actions" />}
+        </colgroup>
+
+        <thead>
+          {table?.getHeaderGroups().map((headerGroup) => {
+            const visibleHeaders = headerGroup.headers.filter((header) => {
+              return typeof header.column.getIsVisible === 'function'
+                ? header.column.getIsVisible()
+                : true;
+            });
+
+            return (
+              <tr key={headerGroup.id}>
+                {visibleHeaders.map((header, index) => {
+                  const isFirst = index === 0;
+                  const isLast = index === visibleHeaders.length - 1;
+                  const isSortable = header.column.getCanSort();
+                  const ariaSort = isSortable
+                    ? header.column.getIsSorted() === 'asc'
+                      ? 'ascending'
+                      : header.column.getIsSorted() === 'desc'
+                      ? 'descending'
+                      : 'none'
+                    : undefined;
+                  const isRightAligned = header.column.columnDef.meta?.align === 'right';
+
+                  const handleSortClick = (event: React.MouseEvent) => {
+                    const originalHandler = header.column.getToggleSortingHandler();
+                    if (originalHandler) {
+                      originalHandler(event);
+                    }
+
+                    const columnName =
+                      typeof header.column.columnDef.header === 'string'
+                        ? header.column.columnDef.header
+                        : 'column';
+                    const currentSort = header.column.getIsSorted();
+                    const newSort = currentSort === 'asc' ? 'desc' : currentSort === 'desc' ? null : 'asc';
+                    announceSortChange(columnName, newSort);
+                  };
+
+                  const headerKeyboardHandlers = keyboardNavigation.getHeaderKeyboardHandlers(
+                    header.index,
+                    () => {
+                      const originalHandler = header.column.getToggleSortingHandler();
+                      if (originalHandler) {
+                        originalHandler({} as any);
+                      }
+
+                      const columnName =
+                        typeof header.column.columnDef.header === 'string'
+                          ? header.column.columnDef.header
+                          : 'column';
+                      const currentSort = header.column.getIsSorted();
+                      const newSort = currentSort === 'asc' ? 'desc' : currentSort === 'desc' ? null : 'asc';
+                      announceSortChange(columnName, newSort);
+                    }
+                  );
+
+                  return (
+                    <th
+                      key={header.id}
+                      className={cn(
+                        'px-3 py-2 bg-main-200',
+                        isRightAligned ? 'text-right' : 'text-left',
+                        isFirst && 'rounded-l-md',
+                        isLast && 'rounded-r-md'
+                      )}
+                      scope="col"
+                      role="columnheader"
+                      {...(isSortable ? { 'aria-sort': ariaSort } : {})}
+                      {...(isSortable ? headerKeyboardHandlers : {})}
+                    >
+                      {header.isPlaceholder ? null : isSortable ? (
+                        <Button
+                          variant="ghost"
+                          className={`h-auto p-0 font-bold hover:bg-transparent ${isRightAligned ? 'justify-end' : 'justify-start'}`}
+                          onClick={handleSortClick}
+                          {...headerKeyboardHandlers}
+                          aria-label={`Sort by ${
+                            typeof header.column.columnDef.header === 'string'
+                              ? header.column.columnDef.header
+                              : 'column'
+                          }`}
+                          tabIndex={0}
+                        >
+                          {typeof header.column.columnDef.header === 'function'
+                            ? header.column.columnDef.header(header.getContext())
+                            : header.column.columnDef.header}
+                          {header.column.getIsSorted() === 'asc' ? (
+                            <ChevronUp className="size-4" />
+                          ) : header.column.getIsSorted() === 'desc' ? (
+                            <ChevronDown className="size-4" />
+                          ) : (
+                            <ChevronsUpDown className="size-4" />
+                          )}
+                        </Button>
+                      ) : typeof header.column.columnDef.header === 'function' ? (
+                        header.column.columnDef.header(header.getContext())
+                      ) : (
+                        header.column.columnDef.header
+                      )}
+                    </th>
+                  );
+                })}
+              </tr>
+            );
+          })}
+        </thead>
+
+        <UnifiedTableBody
+          table={table}
+          isCreating={state.isCreating}
+          creationData={state.creationData}
+          onCreationDataChange={stateActions.setCreationData}
+          onSaveCreation={() => {
+            if (onCreateRow) {
+              onCreateRow(state.creationData as Partial<TData>);
+              stateActions.clearCreationData();
+              stateActions.setCreating(false);
+            }
+          }}
+          onCancelCreation={() => {
+            stateActions.clearCreationData();
+            stateActions.setCreating(false);
+          }}
+          editingRowId={state.editingRowId}
+          editingData={state.editingData}
+          onEditingDataChange={(data) => {
+            if (state.editingRowId) {
+              stateActions.setEditingRow(state.editingRowId, data);
+            }
+          }}
+          onSaveEditing={() => {
+            if (onEditRow && state.editingRowId) {
+              const originalRow = data.find((row) => {
+                try {
+                  const rowId = resolvedGetRowId(row, 0);
+                  return rowId === state.editingRowId;
+                } catch {
+                  return false;
+                }
+              });
+              if (originalRow) {
+                onEditRow(originalRow, state.editingData as Partial<TData>);
+              }
+            }
+            stateActions.clearEditing();
+          }}
+          onCancelEditing={() => {
+            stateActions.clearEditing();
+          }}
+          grouping={state.grouping}
+          aggregates={aggregates}
+          getRowId={resolvedGetRowId}
+          emptyState={React.isValidElement(emptyState) ? undefined : (emptyState as any)}
+          isFiltered={searchQuery !== '' || state.columnFilters.length > 0}
+          onClearFilters={() => {
+            onSearch('');
+            stateActions.setColumnFilters([]);
+          }}
+          enableFiltering={secureFeatures.filtering}
+          showFilterRow={state.showFilterRow}
+          dataLength={finalTableData?.length || 0}
+          virtualHeight={virtualHeight}
+          forceVirtualization={false}
+          hierarchical={
+            secureFeatures.hierarchical && hierarchical?.enabled && hierarchicalState
+              ? {
+                  ...hierarchical,
+                  state: hierarchicalState,
+                  expandAll: hierarchicalState.expandAll,
+                  collapseAll: hierarchicalState.collapseAll,
+                  isAllExpanded:
+                    hierarchicalState.getExpandedIds().length > 0 &&
+                    hierarchicalState.getExpandedIds().length === (finalTableData as any[]).filter((row) => (row as any).isParent).length,
+                  hasAnyChildren: (finalTableData as any[]).some((row) => (row as any).isParent),
+                }
+              : undefined
+          }
+          actions={effectiveActions}
+          rbac={rbac}
+          permissions={permissions}
+        />
+
+        {secureFeatures.pagination && (
+          <tfoot>
+            <tr>
+              <td colSpan={visibleColumns.length}>
+                <PaginationComponent
+                  table={table}
+                  pageSizeOptions={finalPageSizeOptions}
+                  paginationMode={finalPaginationMode}
+                  totalCount={finalDataCount}
+                  isLoading={isLoading}
+                />
+              </td>
+            </tr>
+          </tfoot>
+        )}
+      </table>
+
+      <DataTableModals
+        showImportModal={state.showImportModal}
+        onCloseImportModal={() => stateActions.setImportModal(false)}
+        onImport={async (modalData: TData[]) => {
+          if (onImport) {
+            try {
+              const result = onImport(modalData);
+              if (result && typeof result.then === 'function') {
+                await result;
+              }
+
+              toast({
+                title: 'Import Successful',
+                description: `Successfully imported ${modalData.length} ${modalData.length === 1 ? 'row' : 'rows'}`,
+                variant: 'default',
+              });
+            } catch (error) {
+              logger.error('Import error:', error);
+              toast({
+                title: 'Import Failed',
+                description: error instanceof Error ? error.message : 'Failed to import data',
+                variant: 'destructive',
+              });
+              return;
+            }
+          } else {
+            logger.error('onImport handler not provided');
+            toast({
+              title: 'Import Not Configured',
+              description: 'Import functionality requires an onImport handler to be provided.',
+              variant: 'destructive',
+            });
+            return;
+          }
+          stateActions.setImportModal(false);
+        }}
+        importModalConfig={importModalConfig}
+        columns={columns.map((col) => ({
+          id: col.id,
+          accessorKey: col.accessorKey,
+          header: typeof col.header === 'string' ? col.header : undefined,
+          editAccessorKey: col.editAccessorKey,
+        }))}
+      />
+    </>
+  );
+}

package/src/components/DataTable/components/DataTableModals.tsx

@@ -175,6 +175,14 @@ export interface DataTableModalsProps<TData extends Record<string, unknown> = Re
  * />
  * ```
  */
+/**
+ * Container component for all DataTable modal dialogs.
+ * Manages import modals and other data table related dialogs.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - Modal configuration and handlers
+ * @returns The rendered modals
+ */
 export function DataTableModals<TData extends Record<string, unknown> = Record<string, unknown>>({
   showImportModal,
   onCloseImportModal,

package/src/components/DataTable/components/DataTableToolbar.tsx

@@ -141,6 +141,14 @@ interface DataTableToolbarProps<TData extends DataRecord = DataRecord> {
  * />
  * ```
  */
+/**
+ * Toolbar component for DataTable.
+ * Provides search, filters, export/import, and other table actions.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - Toolbar configuration and handlers
+ * @returns The rendered toolbar
+ */
 export function DataTableToolbar<TData extends DataRecord>({
   features,
   rbac,

package/src/components/DataTable/components/DraggableColumnHeader.tsx

@@ -4,6 +4,10 @@ import { ChevronUp, ChevronDown,ChevronsUpDown } from 'lucide-react';
 import { cn } from '../../../utils/core/cn';
 import type { Header } from '@tanstack/react-table';
 
+/**
+ * Props for the DraggableColumnHeader component.
+ * @template TData - The type of data records in the table
+ */
 interface DraggableColumnHeaderProps<TData> {
   header: Header<TData, unknown>;
   onMoveLeft?: () => void;
@@ -14,6 +18,14 @@ interface DraggableColumnHeaderProps<TData> {
   onColumnDrop?: (draggedColumnId: string, targetColumnId: string) => void;
 }
 
+/**
+ * Draggable column header component for DataTable.
+ * Provides drag-and-drop column reordering functionality.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - Draggable column header configuration
+ * @returns The rendered draggable column header
+ */
 export function DraggableColumnHeader<TData>({
   header,
   onMoveLeft,