@jmruthers/pace-core 0.5.193 → 0.6.2

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,
@@ -29,8 +41,8 @@ export function useColumnReordering<TData>({
   });
 
   // Update column order when columns change
-  // Using useMemo to prevent infinite loops
-  useMemo(() => {
+  // Using useEffect for side effects (state updates)
+  useEffect(() => {
     if (enableReordering) {
       const newOrder = columns.map(col => col.id);
       setColumnOrder(prevOrder => {

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,