@jmruthers/pace-core 0.6.1 → 0.6.3

package/src/components/DataTable/components/VirtualizedDataTable.tsx

@@ -11,6 +11,10 @@ import { flexRender, type Table as TanStackTable, type Cell, type Row } from '@t
 import { cn } from '../../../utils/core/cn';
 import type { DataRecord } from '../types';
 
+/**
+ * Props for the VirtualizedDataTable component.
+ * @template TData - The type of data records in the table
+ */
 export interface VirtualizedDataTableProps<TData extends DataRecord> {
   table: TanStackTable<TData>;
   height?: number;
@@ -42,8 +46,8 @@ MemoizedCell.displayName = 'MemoizedCell';
 /**
  * Memoized row component for performance
  */
-const MemoizedRow = memo(<TData extends DataRecord>({ row, style }: { 
-  row: Row<TData>; 
+const MemoizedRow = memo(({ row, style }: { 
+  row: Row<DataRecord>; 
   style: React.CSSProperties;
 }) => {
   return (
@@ -228,7 +232,7 @@ export function VirtualizedDataTable<TData extends DataRecord>({
                 return (
                   <MemoizedRow
                     key={row.id}
-                    row={row}
+                    row={row as unknown as Row<DataRecord>}
                     style={{
                       position: 'absolute',
                       top: 0,
@@ -284,6 +288,14 @@ export interface EnhancedVirtualizedDataTableProps<TData extends DataRecord>
   getRowId?: (row: TData) => string;
 }
 
+/**
+ * Enhanced virtualized DataTable component.
+ * Provides virtual scrolling for large datasets with performance optimizations.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - Virtualized table configuration
+ * @returns The rendered virtualized table
+ */
 export function EnhancedVirtualizedDataTable<TData extends DataRecord>({
   table,
   height = 400,
@@ -472,7 +484,7 @@ export function EnhancedVirtualizedDataTable<TData extends DataRecord>({
                 return (
                   <MemoizedRow
                     key={row.id}
-                    row={row}
+                    row={row as unknown as Row<DataRecord>}
                     style={{
                       position: 'absolute',
                       top: 0,

package/src/components/DataTable/components/__tests__/AccessDeniedPage.test.tsx

@@ -407,7 +407,7 @@ describe('[component] AccessDeniedPage', () => {
     it('has proper semantic structure', () => {
       render(<AccessDeniedPage resource="users" />);
 
-      const heading = screen.getByRole('heading', { level: 2 });
+      const heading = screen.getByRole('heading', { level: 3 });
       expect(heading).toHaveTextContent('Access Denied');
     });
 
@@ -471,7 +471,9 @@ describe('[component] AccessDeniedPage', () => {
       const { container } = render(<AccessDeniedPage resource="users" />);
 
       const mainContainer = container.firstChild;
-      expect(mainContainer).toHaveClass('flex', 'items-center', 'justify-center');
+      // AccessDeniedPage uses Card component, which has its own layout classes
+      expect(mainContainer).toBeInTheDocument();
+      expect(mainContainer).toHaveClass('max-w-md', 'w-full', 'text-center');
     });
 
     it('renders Card component', async () => {

package/src/components/DataTable/components/cellValueUtils.ts

@@ -0,0 +1,40 @@
+import type { CellValue, DataRecord } from '../types';
+
+const isCellValue = (value: unknown): value is CellValue => {
+  if (value === null || value === undefined) {
+    return true;
+  }
+
+  if (value instanceof Date) {
+    return true;
+  }
+
+  const valueType = typeof value;
+  return valueType === 'string' || valueType === 'number' || valueType === 'boolean';
+};
+
+/**
+ * Converts a data record to a cell value record.
+ * Filters and converts values to valid cell values (string, number, boolean, Date, null, undefined).
+ * 
+ * @template TData - The type of data records
+ * @param row - The data record to convert
+ * @returns A record with cell-compatible values
+ */
+export const toCellValueRecord = <TData extends DataRecord>(row: TData): Record<string, CellValue> => {
+  if (typeof row !== 'object' || row === null) {
+    return {};
+  }
+
+  return Object.entries(row).reduce<Record<string, CellValue>>((accumulator, [key, entryValue]) => {
+    if (isCellValue(entryValue)) {
+      accumulator[key] = entryValue;
+    } else if (entryValue && typeof entryValue === 'object' && 'toString' in entryValue) {
+      accumulator[key] = String(entryValue) as CellValue;
+    } else {
+      accumulator[key] = entryValue as CellValue;
+    }
+
+    return accumulator;
+  }, {});
+};

package/src/components/DataTable/components/hooks/useImportModalFocus.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef } from 'react';
+import type { UseKeyboardNavigationReturn } from '../../hooks/useKeyboardNavigation';
+
+/**
+ * Hook for managing focus when the import modal opens/closes.
+ * Stores and restores focus to maintain keyboard navigation flow.
+ * 
+ * @param isImportOpen - Whether the import modal is currently open
+ * @param keyboardNavigation - Keyboard navigation utilities
+ * @returns Object with last focused element reference
+ */
+export function useImportModalFocus(isImportOpen: boolean, keyboardNavigation: UseKeyboardNavigationReturn) {
+  const lastFocusedElementRef = useRef<HTMLElement | null>(null);
+  const wasImportModalOpenRef = useRef(false);
+
+  useEffect(() => {
+    if (isImportOpen) {
+      wasImportModalOpenRef.current = true;
+      keyboardNavigation.storeFocus();
+      if (document.activeElement instanceof HTMLElement) {
+        lastFocusedElementRef.current = document.activeElement;
+      }
+    }
+  }, [isImportOpen, keyboardNavigation]);
+
+  useEffect(() => {
+    if (isImportOpen) {
+      return;
+    }
+
+    if (!wasImportModalOpenRef.current) {
+      return;
+    }
+
+    wasImportModalOpenRef.current = false;
+    setTimeout(() => {
+      const storedElement = lastFocusedElementRef.current;
+      lastFocusedElementRef.current = null;
+
+      const elementToRestore = storedElement?.isConnected
+        ? storedElement
+        : document.querySelector<HTMLElement>('[data-restore-target="datatable-import-button"]');
+
+      if (elementToRestore && typeof elementToRestore.focus === 'function') {
+        elementToRestore.focus();
+      } else {
+        keyboardNavigation.restoreFocus();
+      }
+    }, 100);
+  }, [isImportOpen, keyboardNavigation]);
+
+  return { lastFocusedElementRef };
+}

package/src/components/DataTable/components/hooks/usePermissionTracking.ts

@@ -0,0 +1,126 @@
+import React from 'react';
+import type { UseDataTablePermissionsReturn } from '../../hooks/useDataTablePermissions';
+import type { createLogger } from '../../../../utils/core/logger';
+
+interface PermissionTrackingParams {
+  permissions: UseDataTablePermissionsReturn['permissions'];
+  effectivePageId?: string;
+  logger: ReturnType<typeof createLogger>;
+}
+
+/**
+ * Result of permission tracking hook.
+ * Provides timing information and loading state for permission checks.
+ */
+export interface PermissionTrackingResult {
+  permissionElapsed: number;
+  shouldAllowRenderAfterTimeout: boolean;
+  isPermissionLoading: boolean;
+}
+
+/**
+ * Hook for tracking permission check performance.
+ * Monitors permission loading times and provides warnings for slow checks.
+ * 
+ * @param params - Permission tracking configuration
+ * @returns Permission tracking results including elapsed time and loading state
+ */
+export function usePermissionTracking({
+  permissions,
+  effectivePageId,
+  logger,
+}: PermissionTrackingParams): PermissionTrackingResult {
+  const permissionCheckStartTime = React.useRef<number | null>(null);
+  const permissionTimeoutId = React.useRef<NodeJS.Timeout | null>(null);
+  const permissionWarningTimeoutId = React.useRef<NodeJS.Timeout | null>(null);
+  const hasStartedTracking = React.useRef<boolean>(false);
+  const [permissionSlowWarning, setPermissionSlowWarning] = React.useState(false);
+
+  React.useEffect(() => {
+    if (permissions.canRead.isLoading && !hasStartedTracking.current) {
+      hasStartedTracking.current = true;
+      permissionCheckStartTime.current = Date.now();
+      logger.debug('DataTable: Permission check started', {
+        pageId: effectivePageId,
+        timestamp: permissionCheckStartTime.current,
+      });
+
+      if (permissionWarningTimeoutId.current) {
+        clearTimeout(permissionWarningTimeoutId.current);
+      }
+      if (permissionTimeoutId.current) {
+        clearTimeout(permissionTimeoutId.current);
+      }
+
+      permissionWarningTimeoutId.current = setTimeout(() => {
+        const elapsed = permissionCheckStartTime.current ? Date.now() - permissionCheckStartTime.current : 0;
+        logger.warn('DataTable: Permission check taking longer than expected (>2s)', {
+          pageId: effectivePageId,
+          elapsedMs: elapsed,
+          diagnostic: 'Permission checks should complete in <1s. This may indicate slow database queries or network issues.',
+        });
+        setPermissionSlowWarning(true);
+      }, 2000);
+
+      permissionTimeoutId.current = setTimeout(() => {
+        const elapsed = permissionCheckStartTime.current ? Date.now() - permissionCheckStartTime.current : 0;
+        logger.warn('DataTable: Permission check taking longer than expected (>5s)', {
+          pageId: effectivePageId,
+          elapsedMs: elapsed,
+          permissionState: {
+            isLoading: permissions.canRead.isLoading,
+            can: permissions.canRead.can,
+            error: permissions.canRead.error?.message,
+          },
+          diagnostic: 'This may indicate slow database queries or network issues. Check scope resolution and permission check performance.',
+        });
+      }, 5000);
+    } else if (!permissions.canRead.isLoading && hasStartedTracking.current) {
+      if (permissionCheckStartTime.current) {
+        const elapsed = Date.now() - permissionCheckStartTime.current;
+        if (elapsed > 1000) {
+          logger.warn('DataTable: Permission check took longer than expected', {
+            pageId: effectivePageId,
+            elapsedMs: elapsed,
+            can: permissions.canRead.can,
+          });
+        }
+        permissionCheckStartTime.current = null;
+      }
+
+      hasStartedTracking.current = false;
+
+      if (permissionWarningTimeoutId.current) {
+        clearTimeout(permissionWarningTimeoutId.current);
+        permissionWarningTimeoutId.current = null;
+      }
+      if (permissionTimeoutId.current) {
+        clearTimeout(permissionTimeoutId.current);
+        permissionTimeoutId.current = null;
+      }
+      setPermissionSlowWarning(false);
+    }
+
+    return () => {
+      if (permissionWarningTimeoutId.current) {
+        clearTimeout(permissionWarningTimeoutId.current);
+      }
+      if (permissionTimeoutId.current) {
+        clearTimeout(permissionTimeoutId.current);
+      }
+    };
+  }, [permissions.canRead.isLoading, effectivePageId, logger, permissions.canRead.can, permissions.canRead.error]);
+
+  const permissionElapsed = permissionCheckStartTime.current ? Date.now() - permissionCheckStartTime.current : 0;
+  const shouldAllowRenderAfterTimeout = permissionElapsed > 3000;
+
+  if (permissionSlowWarning) {
+    // state is only used for logging; keep hook returning derived values
+  }
+
+  return {
+    permissionElapsed,
+    shouldAllowRenderAfterTimeout,
+    isPermissionLoading: permissions.canRead.isLoading && !shouldAllowRenderAfterTimeout,
+  };
+}

package/src/components/DataTable/context/DataTableContext.tsx

@@ -20,6 +20,12 @@ import type {
 // CONTEXT INTERFACE
 // ============================================================================
 
+/**
+ * Context value interface for DataTable.
+ * Provides state, actions, computed values, and utility functions.
+ * 
+ * @template TData - The type of data records in the table
+ */
 export interface DataTableContextValue<TData extends DataRecord> {
   state: DataTableState<TData>;
   actions: ReturnType<typeof useDataTableStateHook<TData>>['actions'];
@@ -37,11 +43,23 @@ const DataTableContext = createContext<DataTableContextValue<DataRecord> | null>
 // PROVIDER COMPONENT
 // ============================================================================
 
+/**
+ * Props for the DataTableProvider component.
+ * @template TData - The type of data records in the table
+ */
 export interface DataTableProviderProps<TData extends DataRecord> {
   children: React.ReactNode;
   options?: UseDataTableStateOptions<TData>;
 }
 
+/**
+ * Context provider component for DataTable.
+ * Provides state management and actions to child components.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - Provider configuration
+ * @returns The context provider
+ */
 export function DataTableProvider<TData extends DataRecord>({
   children,
   options = {}
@@ -66,6 +84,14 @@ export function DataTableProvider<TData extends DataRecord>({
 // HOOKS
 // ============================================================================
 
+/**
+ * Hook to access DataTable context.
+ * Must be used within a DataTableProvider.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns DataTable context value
+ * @throws Error if used outside DataTableProvider
+ */
 export function useDataTableContext<TData extends DataRecord>(): DataTableContextValue<TData> {
   const context = useContext(DataTableContext);
   
@@ -76,21 +102,45 @@ export function useDataTableContext<TData extends DataRecord>(): DataTableContex
   return context as DataTableContextValue<TData>;
 }
 
+/**
+ * Hook to access DataTable state from context.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns Current table state
+ */
 export function useDataTableState<TData extends DataRecord>() {
   const { state } = useDataTableContext<TData>();
   return state;
 }
 
+/**
+ * Hook to access DataTable actions from context.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns Table state actions
+ */
 export function useDataTableActions<TData extends DataRecord>() {
   const { actions } = useDataTableContext<TData>();
   return actions;
 }
 
+/**
+ * Hook to access DataTable computed values from context.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns Computed table values
+ */
 export function useDataTableComputed<TData extends DataRecord>() {
   const { computed } = useDataTableContext<TData>();
   return computed;
 }
 
+/**
+ * Hook to access the clear filters function from context.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns Function to clear all table filters
+ */
 export function useDataTableClearFilters<TData extends DataRecord>() {
   const { clearFilters } = useDataTableContext<TData>();
   return clearFilters;

package/src/components/DataTable/core/ColumnFactory.ts

@@ -12,6 +12,9 @@ import type { DataRecord, DataTableAction } from '../types';
 // COLUMN OPTIONS INTERFACES
 // ============================================================================
 
+/**
+ * Options for text column configuration.
+ */
 export interface TextColumnOptions {
   label?: string;
   sortable?: boolean;
@@ -25,20 +28,36 @@ export interface TextColumnOptions {
   maxSize?: number;
 }
 
+/**
+ * Options for number column configuration.
+ * Extends TextColumnOptions with number-specific formatting.
+ */
 export interface NumberColumnOptions extends TextColumnOptions {
   format?: (value: number) => string;
 }
 
+/**
+ * Options for date column configuration.
+ * Extends TextColumnOptions with date-specific formatting and locale options.
+ */
 export interface DateColumnOptions extends TextColumnOptions {
   format?: (date: Date) => string;
   locale?: string;
   dateOptions?: Intl.DateTimeFormatOptions;
 }
 
+/**
+ * Options for boolean column configuration.
+ * Extends TextColumnOptions with boolean-specific rendering.
+ */
 export interface BooleanColumnOptions extends Omit<TextColumnOptions, 'render'> {
   render?: (value: boolean) => React.ReactNode;
 }
 
+/**
+ * Options for action column configuration.
+ * Defines how action buttons are rendered in table rows.
+ */
 export interface ActionColumnOptions {
   header?: string;
   render?: (row: DataRecord, actions: DataTableAction<DataRecord>[]) => React.ReactNode;
@@ -51,6 +70,12 @@ export interface ActionColumnOptions {
   };
 }
 
+/**
+ * Options for custom column configuration.
+ * Allows full control over column rendering and behavior.
+ * 
+ * @template TData - The type of data records in the table
+ */
 export interface CustomColumnOptions<TData extends DataRecord> {
   header?: string;
   cell?: (info: unknown) => React.ReactNode;
@@ -64,6 +89,12 @@ export interface CustomColumnOptions<TData extends DataRecord> {
   maxSize?: number;
 }
 
+/**
+ * Column configuration interface.
+ * Defines the structure for creating columns programmatically.
+ * 
+ * @template TData - The type of data records in the table
+ */
 export interface ColumnConfig<TData extends DataRecord> {
   key: keyof TData | string;
   type: 'text' | 'number' | 'date' | 'boolean' | 'custom';

package/src/components/DataTable/core/DataTableContext.tsx

@@ -27,7 +27,8 @@ import { LocalDataAdapter } from './LocalDataAdapter';
 const DataTableContext = createContext<IDataTableContext<DataRecord> | null>(null);
 
 /**
- * DataTable provider component
+ * Props for the DataTableProvider component.
+ * @template TData - The type of data records in the table
  */
 export interface DataTableProviderProps<TData extends DataRecord> {
   children: React.ReactNode;
@@ -159,26 +160,56 @@ export function useDataTableContext<TData extends DataRecord = DataRecord>(): ID
 /**
  * Hook to use specific managers
  */
+/**
+ * Hook to access DataTable data manager.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns Data manager instance
+ */
 export function useDataManager<TData extends DataRecord = DataRecord>() {
   const context = useDataTableContext<TData>();
   return context.dataManager;
 }
 
+/**
+ * Hook to access DataTable column manager.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns Column manager instance
+ */
 export function useColumnManager<TData extends DataRecord = DataRecord>() {
   const context = useDataTableContext<TData>();
   return context.columnManager;
 }
 
+/**
+ * Hook to access DataTable action manager.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns Action manager instance
+ */
 export function useActionManager<TData extends DataRecord = DataRecord>() {
   const context = useDataTableContext<TData>();
   return context.actionManager;
 }
 
+/**
+ * Hook to access DataTable state manager.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns State manager instance
+ */
 export function useStateManager<TData extends DataRecord = DataRecord>() {
   const context = useDataTableContext<TData>();
   return context.stateManager;
 }
 
+/**
+ * Hook to access DataTable plugin registry.
+ * 
+ * @template TData - The type of data records in the table
+ * @returns Plugin registry instance
+ */
 export function usePluginRegistry<TData extends DataRecord = DataRecord>() {
   const context = useDataTableContext<TData>();
   return context.pluginRegistry;

package/src/components/DataTable/hooks/useColumnOrderPersistence.ts

@@ -1,6 +1,9 @@
 import { useState, useEffect, useCallback } from 'react';
 import { createLogger } from '../../../utils/core/logger';
 
+/**
+ * Props for the useColumnOrderPersistence hook.
+ */
 interface UseColumnOrderPersistenceProps {
   tableId?: string;
   defaultOrder?: string[];
@@ -8,6 +11,13 @@ interface UseColumnOrderPersistenceProps {
   storageKey?: string;
 }
 
+/**
+ * Hook for persisting column order in localStorage.
+ * Saves and restores column order across page reloads.
+ * 
+ * @param props - Column order persistence configuration
+ * @returns Column order state and update function
+ */
 export function useColumnOrderPersistence({
   tableId,
   defaultOrder = [],

package/src/components/DataTable/hooks/useColumnReordering.ts

@@ -1,6 +1,10 @@
 import { useState, useCallback, useMemo, useEffect } from 'react';
 import type { Column } from '@tanstack/react-table';
 
+/**
+ * Props for the useColumnReordering hook.
+ * @template TData - The type of data records in the table
+ */
 interface UseColumnReorderingProps<TData> {
   columns: Column<TData, unknown>[];
   onColumnOrderChange?: (columnOrder: string[]) => void;
@@ -11,6 +15,14 @@ interface UseColumnReorderingProps<TData> {
   onColumnOrderUpdate?: (columnOrder: string[]) => void;
 }
 
+/**
+ * Hook for managing column reordering in DataTable.
+ * Provides functions to move columns and persist order changes.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - Column reordering configuration
+ * @returns Column order state and reordering functions
+ */
 export function useColumnReordering<TData>({
   columns,
   onColumnOrderChange,

package/src/components/DataTable/hooks/useColumnVisibilityPersistence.ts

@@ -1,6 +1,9 @@
 import { useState, useEffect, useCallback } from 'react';
 import { createLogger } from '../../../utils/core/logger';
 
+/**
+ * Props for the useColumnVisibilityPersistence hook.
+ */
 interface UseColumnVisibilityPersistenceProps {
   tableId?: string;
   defaultVisibility?: Record<string, boolean>;
@@ -8,6 +11,13 @@ interface UseColumnVisibilityPersistenceProps {
   storageKey?: string;
 }
 
+/**
+ * Hook for persisting column visibility in localStorage.
+ * Saves and restores column visibility state across page reloads.
+ * 
+ * @param props - Column visibility persistence configuration
+ * @returns Column visibility state and update function
+ */
 export function useColumnVisibilityPersistence({
   tableId,
   defaultVisibility = {},

package/src/components/DataTable/hooks/useDataTableDataPipeline.ts

@@ -21,6 +21,10 @@ import type {
 } from '../types';
 import type { SortingState } from '@tanstack/react-table';
 
+/**
+ * Parameters for the useDataTableDataPipeline hook.
+ * @template TData - The type of data records in the table
+ */
 export interface UseDataTableDataPipelineParams<TData extends DataRecord> {
   data: TData[];
   features: NormalizedDataTableFeatureConfig;
@@ -30,6 +34,10 @@ export interface UseDataTableDataPipelineParams<TData extends DataRecord> {
   serverData: ServerSideResponse<TData> | null;
 }
 
+/**
+ * Return value of the useDataTableDataPipeline hook.
+ * @template TData - The type of data records in the table
+ */
 export interface UseDataTableDataPipelineResult<TData extends DataRecord> {
   finalTableData: TData[];
   dataCount: number;
@@ -37,6 +45,14 @@ export interface UseDataTableDataPipelineResult<TData extends DataRecord> {
   hierarchicalValidation: { isValid: boolean; errors: string[] };
 }
 
+/**
+ * Hook that encapsulates hierarchical validation, sorting, and data source resolution.
+ * Processes table data through the data pipeline before rendering.
+ * 
+ * @template TData - The type of data records in the table
+ * @param params - Data pipeline configuration
+ * @returns Processed table data and pipeline state
+ */
 export function useDataTableDataPipeline<TData extends DataRecord>({
   data,
   features,