@jmruthers/pace-core 0.5.193 → 0.6.2

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

@@ -22,6 +22,10 @@ import {
 } from '../types';
 import type { Permission } from '../../../rbac/types';
 
+/**
+ * Return value of the useDataTablePermissions hook.
+ * Contains permission checks and secure feature configuration.
+ */
 export interface UseDataTablePermissionsReturn {
   permissions: {
     canRead: ReturnType<typeof useCan>;
@@ -35,6 +39,15 @@ export interface UseDataTablePermissionsReturn {
   effectivePageId: string | undefined;
 }
 
+/**
+ * Hook for managing RBAC permissions in DataTable components.
+ * Handles scope resolution, permission checks, and secure feature configuration.
+ * 
+ * @template TData - The type of data records in the table
+ * @param rbac - RBAC configuration for the DataTable
+ * @param features - Feature configuration to secure
+ * @returns Permission checks and secure feature configuration
+ */
 export function useDataTablePermissions<TData extends DataRecord>(
   rbac: DataTableRBACConfig,
   features: DataTableFeatureConfig = {}
@@ -45,26 +58,69 @@ export function useDataTablePermissions<TData extends DataRecord>(
 
   // Super admin status - check if user has super admin privileges
   // Super admins bypass all permission checks (similar to PaceAppLayout)
-  const [isSuperAdminUser, setIsSuperAdminUser] = useState<boolean>(false);
-  const [isCheckingSuperAdmin, setIsCheckingSuperAdmin] = useState<boolean>(false);
+  // PERFORMANCE OPTIMIZATION: Check super admin once and share with all useCan hooks to avoid duplicate queries
+  // Use null to indicate "not checked yet" vs false which means "checked and not super admin"
+  const [isSuperAdminUser, setIsSuperAdminUser] = useState<boolean | null>(null);
+  const [isCheckingSuperAdmin, setIsCheckingSuperAdmin] = useState<boolean>(() => !!user?.id);
+  const lastCheckedUserIdRef = useRef<string | null>(null);
+  const isCheckingRef = useRef<boolean>(false);
 
   useEffect(() => {
+    // Skip if already checked for this user ID
+    if (lastCheckedUserIdRef.current === user?.id && isSuperAdminUser !== null) {
+      return;
+    }
+
+    // Skip if already checking
+    if (isCheckingRef.current) {
+      return;
+    }
+
     const checkSuperAdminStatus = async () => {
       if (!user?.id) {
-        setIsSuperAdminUser(false);
+        setIsSuperAdminUser(false); // No user = not super admin
         setIsCheckingSuperAdmin(false);
+        lastCheckedUserIdRef.current = null;
         return;
       }
 
+      // Mark as checking and track user ID
+      isCheckingRef.current = true;
+      lastCheckedUserIdRef.current = user.id;
+
+      const startTime = Date.now();
       setIsCheckingSuperAdmin(true);
+      
+      // Add timeout to prevent infinite hanging
+      const timeoutId = setTimeout(() => {
+        logger.warn('useDataTablePermissions', 'Super admin check taking longer than 5 seconds', {
+          userId: user?.id,
+          elapsedMs: Date.now() - startTime,
+        });
+      }, 5000);
+
       try {
+        logger.debug('useDataTablePermissions', 'Starting super admin check', { userId: user?.id });
         const superAdminStatus = await isSuperAdmin(user.id);
+        const elapsed = Date.now() - startTime;
+        logger.debug('useDataTablePermissions', 'Super admin check completed', {
+          userId: user?.id,
+          isSuperAdmin: superAdminStatus,
+          elapsedMs: elapsed,
+        });
         setIsSuperAdminUser(superAdminStatus);
       } catch (error) {
-        logger.error('useDataTablePermissions', 'Error checking super admin status', { userId: user?.id, error });
-        setIsSuperAdminUser(false);
+        const elapsed = Date.now() - startTime;
+        logger.error('useDataTablePermissions', 'Error checking super admin status', {
+          userId: user?.id,
+          error,
+          elapsedMs: elapsed,
+        });
+        setIsSuperAdminUser(false); // Error = assume not super admin for security
       } finally {
+        clearTimeout(timeoutId);
         setIsCheckingSuperAdmin(false);
+        isCheckingRef.current = false;
       }
     };
 
@@ -156,24 +212,36 @@ export function useDataTablePermissions<TData extends DataRecord>(
    * This allows permission checks for users without organisations (e.g., profile pages).
    * The database function rbac_check_permission_simplified can handle NULL organisation_id.
    * 
-   * IMPORTANT: When using pageName (not pageId), we MUST wait for appId to be resolved,
-   * because the RPC function needs appId to resolve the pageName to a pageId UUID.
-   * If we have a pageId (UUID), we can proceed even without appId.
+   * PERFORMANCE OPTIMIZATION: For page-level permissions with pageId (UUID), we don't need to wait
+   * for full scope resolution. The database function can handle page-level permissions without
+   * organisationId or appId. We only need to wait if:
+   * 1. We're using pageName (not UUID) and need appId to resolve it, OR
+   * 2. We need organisationId for resource-level permissions (but we're using page-level here)
    * 
-   * The key issue: When pageName is used without appId, the RPC function cannot resolve
-   * the pageName to a pageId, which causes permission checks to fail initially, showing
-   * "Access Denied" before the scope resolves and permissions are re-checked.
+   * This allows permission checks to proceed in parallel with scope resolution, reducing load time.
    */
   const isPageName = !pageId && !!pageName; // We're using pageName, not a UUID pageId
   const needsAppIdForResolution = isPageName; // Only need appId if we're resolving a pageName
   
-  // Wait for scope resolution if:
-  // 1. Scope is still loading, OR
-  // 2. We're using pageName and don't have appId yet (needed to resolve pageName to pageId)
-  // This prevents premature permission checks that would fail and show "Access Denied"
-  const shouldWaitForScope = scopeLoading || (needsAppIdForResolution && !stableScope.appId);
+  // PERFORMANCE FIX: For page-level permissions with UUID pageId, we can proceed immediately
+  // The database function handles page-level permissions without requiring full scope
+  // Only wait if we're using pageName (which needs appId to resolve) or if scope is critical
+  // For page-level permissions, organisationId and appId are optional
+  const hasPageId = !!pageId && typeof pageId === 'string';
+  const canProceedWithoutFullScope = hasPageId && !isPageName; // UUID pageId doesn't need appId
+  
+  // Wait for scope resolution only if:
+  // 1. We're using pageName and don't have appId yet (needed to resolve pageName to pageId), OR
+  // 2. Scope is loading AND we don't have a UUID pageId (can't proceed without scope)
+  // This allows permission checks to start earlier for UUID pageIds, reducing load time
+  const shouldWaitForScope = (needsAppIdForResolution && !stableScope.appId) || 
+                             (scopeLoading && !canProceedWithoutFullScope);
   
-  const effectiveScope = (!shouldWaitForScope) ? stableScope : null;
+  // Use available scope immediately if we can proceed, otherwise wait
+  // For page-level permissions, empty scope is acceptable (database handles it)
+  const effectiveScope = (!shouldWaitForScope && (stableScope.organisationId || stableScope.appId || stableScope.eventId || canProceedWithoutFullScope)) 
+    ? stableScope 
+    : (canProceedWithoutFullScope ? { organisationId: undefined, eventId: undefined, appId: undefined } : null);
 
   // Always call hooks with consistent parameters to avoid React hooks order violations
   const userId = user?.id || '';
@@ -189,28 +257,39 @@ export function useDataTablePermissions<TData extends DataRecord>(
   const consistentScope = effectiveScope || { organisationId: undefined, eventId: undefined, appId: undefined };
 
   // Check permissions using useCan hooks
+  // PERFORMANCE OPTIMIZATION: Pass precomputed super admin status to avoid duplicate checks
+  // Each useCan hook would normally check super admin separately (6+ queries), but we check once here
+  // and share the result. Pass null if not checked yet (hooks will check), false/true if checked.
   // Note: The database function already handles super admin bypass, but we check here
   // as an additional safety layer to prevent unnecessary permission checks and ensure
   // super admins never see "Access Denied" even if useCan hasn't completed
-  const canReadResult = useCan(userId, consistentScope, readPermission, effectivePageId, true);
-  const canCreateResult = useCan(userId, consistentScope, createPermission, effectivePageId, true);
-  const canUpdateResult = useCan(userId, consistentScope, updatePermission, effectivePageId, true);
-  const canDeleteResult = useCan(userId, consistentScope, deletePermission, effectivePageId, true);
-  const canExportResult = useCan(userId, consistentScope, readPermission, effectivePageId, true); // Use read permission for export
-  const canImportResult = useCan(userId, consistentScope, createPermission, effectivePageId, true); // Use create permission for import
+  // Pass super admin status directly - null means not checked yet, false/true means checked
+  // This eliminates duplicate super admin checks across all 6 permission hooks
+  const canReadResult = useCan(userId, consistentScope, readPermission, effectivePageId, true, isSuperAdminUser);
+  const canCreateResult = useCan(userId, consistentScope, createPermission, effectivePageId, true, isSuperAdminUser);
+  const canUpdateResult = useCan(userId, consistentScope, updatePermission, effectivePageId, true, isSuperAdminUser);
+  const canDeleteResult = useCan(userId, consistentScope, deletePermission, effectivePageId, true, isSuperAdminUser);
+  const canExportResult = useCan(userId, consistentScope, readPermission, effectivePageId, true, isSuperAdminUser); // Use read permission for export
+  const canImportResult = useCan(userId, consistentScope, createPermission, effectivePageId, true, isSuperAdminUser); // Use create permission for import
 
   // Create permission wrappers that bypass checks for super admins
   // Super admins get can: true for all permissions, but we preserve isLoading and error states
   // to maintain consistent API with useCan return type
+  // React 19 fix: Read isLoading directly from result objects to ensure we get the latest state
+  // instead of relying on memoized object references which may not update properly in React 19
   const permissions = useMemo(() => {
     // Helper to create a permission result that bypasses for super admins
     // If super admin check is still loading, we show loading state to prevent premature "Access Denied"
     // Once super admin check completes, if user is super admin, all permissions are true
     // Otherwise, use the normal permission check results
     const createSuperAdminAwarePermission = (result: ReturnType<typeof useCan>) => ({
-      can: isSuperAdminUser ? true : result.can,
-      // Show loading if super admin check is in progress OR if the underlying permission check is loading
-      isLoading: isCheckingSuperAdmin || result.isLoading,
+      // If super admin check completed and user is super admin, grant all permissions
+      // Otherwise use the normal permission check result
+      // Use === true to distinguish between null (not checked) and false (checked, not super admin)
+      can: isSuperAdminUser === true ? true : result.can,
+      // Show loading if super admin check is in progress (null and checking) OR if the underlying permission check is loading
+      // React 19 fix: Read isLoading directly from the result object to ensure we get the latest state
+      isLoading: (isSuperAdminUser === null && isCheckingSuperAdmin) || result.isLoading,
       error: result.error,
       refetch: result.refetch,
     });
@@ -226,12 +305,25 @@ export function useDataTablePermissions<TData extends DataRecord>(
   }, [
     isSuperAdminUser,
     isCheckingSuperAdmin,
-    canReadResult,
-    canCreateResult,
-    canUpdateResult,
-    canDeleteResult,
-    canExportResult,
-    canImportResult,
+    // React 19 fix: Include individual properties instead of entire objects to ensure proper dependency tracking
+    canReadResult.can,
+    canReadResult.isLoading,
+    canReadResult.error,
+    canCreateResult.can,
+    canCreateResult.isLoading,
+    canCreateResult.error,
+    canUpdateResult.can,
+    canUpdateResult.isLoading,
+    canUpdateResult.error,
+    canDeleteResult.can,
+    canDeleteResult.isLoading,
+    canDeleteResult.error,
+    canExportResult.can,
+    canExportResult.isLoading,
+    canExportResult.error,
+    canImportResult.can,
+    canImportResult.isLoading,
+    canImportResult.error,
   ]);
 
   // MANDATORY: Features are automatically filtered by permissions

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

@@ -26,6 +26,12 @@ export type { DataRecord, CellValue, RowId };
 // STATE INTERFACE
 // ============================================================================
 
+/**
+ * DataTable state interface.
+ * Contains all state for table operations including sorting, filtering, pagination, and editing.
+ * 
+ * @template TData - The type of data records in the table
+ */
 export interface DataTableState<TData extends DataRecord> {
   // Table state
   sorting: SortingState;
@@ -53,6 +59,12 @@ export interface DataTableState<TData extends DataRecord> {
   searchQuery: string;
 }
 
+/**
+ * Actions interface for DataTable state management.
+ * Provides functions to update all aspects of table state.
+ * 
+ * @template TData - The type of data records in the table
+ */
 export interface DataTableStateActions<TData extends DataRecord> {
   setSorting: (sorting: SortingState) => void;
   setColumnFilters: (filters: ColumnFiltersState) => void;
@@ -78,6 +90,19 @@ export interface DataTableStateActions<TData extends DataRecord> {
   initializeState: (partialState: Partial<DataTableState<TData>>) => void;
 }
 
+/**
+ * Computed values interface for DataTable.
+ * Provides derived state values that are computed from the table state.
+ */
+export interface DataTableComputed {
+  hasSelection: boolean;
+  selectedRowIds: string[];
+  isEditing: boolean;
+  isCreating: boolean;
+  hasFilters: boolean;
+  canClearFilters: boolean;
+}
+
 // ============================================================================
 // ACTION TYPES
 // ============================================================================
@@ -108,6 +133,15 @@ export type DataTableAction<TData extends DataRecord> =
 // REDUCER
 // ============================================================================
 
+/**
+ * Reducer function for DataTable state management.
+ * Handles all state updates for the DataTable component.
+ * 
+ * @template TData - The type of data records in the table
+ * @param state - Current table state
+ * @param action - Action to perform
+ * @returns New table state
+ */
 export function dataTableReducer<TData extends DataRecord>(
   state: DataTableState<TData>,
   action: DataTableAction<TData>
@@ -330,7 +364,7 @@ export function useDataTableState<TData extends DataRecord>({
   // COMPUTED VALUES
   // ============================================================================
 
-  const computed = useMemo(() => ({
+  const computed = useMemo<DataTableComputed>(() => ({
     hasSelection: Object.values(state.rowSelection).some(Boolean),
     selectedRowIds: Object.entries(state.rowSelection)
       .filter(([_, selected]) => selected)

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

@@ -2,12 +2,24 @@ import { useMemo } from 'react';
 
 import type { DataRecord, DataTableColumn } from '../types';
 
+/**
+ * Options for the useEffectiveColumnOrder hook.
+ * @template TData - The type of data records in the table
+ */
 interface UseEffectiveColumnOrderOptions<TData extends DataRecord> {
   columns: DataTableColumn<TData>[];
   externalColumnOrder?: string[];
   selectionEnabled: boolean;
 }
 
+/**
+ * Hook to compute effective column order.
+ * Handles external column order and ensures selection column is first when enabled.
+ * 
+ * @template TData - The type of data records in the table
+ * @param options - Column order configuration
+ * @returns Effective column order array
+ */
 export function useEffectiveColumnOrder<TData extends DataRecord>({
   columns,
   externalColumnOrder,

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

@@ -23,7 +23,7 @@ export interface KeyboardNavigationOptions {
   /** Callback when focus moves to a new cell */
   onFocusChange?: (rowIndex: number, columnIndex: number) => void;
   /** Table ref for DOM queries */
-  tableRef?: React.RefObject<HTMLTableElement>;
+  tableRef?: React.RefObject<HTMLTableElement | null>;
 }
 
 export interface KeyboardNavigationState {
@@ -105,7 +105,7 @@ export function useKeyboardNavigation(
   const internalTableRef = useRef<HTMLTableElement>(null);
   const tableRef = externalTableRef || internalTableRef;
   const storedFocusRef = useRef<{ rowIndex: number; columnIndex: number } | null>(null);
-  const navigationTimeoutRef = useRef<NodeJS.Timeout>();
+  const navigationTimeoutRef = useRef<NodeJS.Timeout>(undefined);
 
   // Helper to get cell element
   const getCellElement = useCallback((rowIndex: number, columnIndex: number): HTMLElement | null => {

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

@@ -16,6 +16,10 @@ import type {
   PaginationState,
 } from '@tanstack/react-table';
 
+/**
+ * Parameters for the useServerSideDataEffect hook.
+ * @template TData - The type of data records in the table
+ */
 export interface UseServerSideDataEffectParams<TData extends DataRecord> {
   finalPaginationMode: PaginationMode;
   serverSide?: ServerSideConfig<TData>;
@@ -29,6 +33,13 @@ export interface UseServerSideDataEffectParams<TData extends DataRecord> {
   cleanup?: () => void;
 }
 
+/**
+ * Hook for coordinating server-side data fetching.
+ * Triggers data fetches when table state changes in server-side pagination mode.
+ * 
+ * @template TData - The type of data records in the table
+ * @param params - Server-side data effect configuration
+ */
 export function useServerSideDataEffect<TData extends DataRecord>({
   finalPaginationMode,
   serverSide,

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

@@ -21,6 +21,10 @@ import type {
 import type { ColumnDef } from '@tanstack/react-table';
 import type { HeaderContext, CellContext } from '@tanstack/react-table';
 
+/**
+ * Options for the useTableColumns hook.
+ * @template TData - The type of data records in the table
+ */
 export interface UseTableColumnsOptions<TData extends DataRecord> {
   columns: DataTableColumn<TData>[];
   features: NormalizedDataTableFeatureConfig;
@@ -28,6 +32,10 @@ export interface UseTableColumnsOptions<TData extends DataRecord> {
   columnOrder: string[];
 }
 
+/**
+ * Return value of the useTableColumns hook.
+ * @template TData - The type of data records in the table
+ */
 export interface UseTableColumnsReturn<TData extends DataRecord> {
   enhancedColumns: ColumnDef<TData>[];
 }

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

@@ -14,11 +14,21 @@ import type {
   DataTableStateActions,
 } from './useDataTableState';
 
+/**
+ * Table layout change interface.
+ * Represents changes to column order and visibility.
+ */
 export interface TableLayoutChange {
   columnOrder: string[];
   columnVisibility: VisibilityState;
 }
 
+/**
+ * Snapshot of table state at a point in time.
+ * Used for state persistence and restoration.
+ * 
+ * @template TData - The type of data records in the table
+ */
 export interface TableStateSnapshot<TData extends DataRecord> {
   sorting: SortingState;
   columnFilters: ColumnFiltersState;
@@ -31,6 +41,10 @@ export interface TableStateSnapshot<TData extends DataRecord> {
   columnOrder: string[];
 }
 
+/**
+ * Table event handlers interface.
+ * Provides handlers for all table state changes.
+ */
 export interface TableHandlers {
   onSortingChange: (updaterOrValue: unknown) => void;
   onColumnFiltersChange: (updaterOrValue: unknown) => void;

package/src/components/DataTable/styles.ts

@@ -64,7 +64,7 @@ export const getTableCellClasses = (options: {
   isCompact?: boolean;
   isSortable?: boolean;
   className?: string;
-} = {}) => {
+} = {}): string => {
   const { isVirtualized = false, isCompact = false, isSortable = false, className } = options;
   
   if (isVirtualized) {
@@ -88,7 +88,7 @@ export const getTableCellClasses = (options: {
 export const getTableHeadClasses = (options: {
   isSortable?: boolean;
   className?: string;
-} = {}) => {
+} = {}): string => {
   const { isSortable = false, className } = options;
   
   return cn(
@@ -105,7 +105,7 @@ export const getTableRowClasses = (options: {
   isSelected?: boolean;
   isVirtualized?: boolean;
   className?: string;
-} = {}) => {
+} = {}): string => {
   const { isSelected = false, isVirtualized = false, className } = options;
   
   if (isVirtualized) {
@@ -129,7 +129,7 @@ export const getTableRowClasses = (options: {
 export const getTableContainerClasses = (options: {
   isVirtualized?: boolean;
   className?: string;
-} = {}) => {
+} = {}): string => {
   const { isVirtualized = false, className } = options;
   
   return cn(
@@ -145,7 +145,7 @@ export const getTableClasses = (options: {
   isFixed?: boolean;
   variant?: 'default' | 'compact' | 'spacious';
   className?: string;
-} = {}) => {
+} = {}): string => {
   const { isFixed = false, variant = 'default', className } = options;
   
   if (isFixed) {
@@ -182,7 +182,7 @@ export const getTableClasses = (options: {
  */
 export const getMainContainerClasses = (options: {
   className?: string;
-} = {}) => {
+} = {}): string => {
   const { className } = options;
   
   return cn(

package/src/components/DataTable/types.ts

@@ -55,16 +55,6 @@ export type RowId = string;
  */
 export type GetRowId<TData extends DataRecord> = (row: TData, index: number) => RowId;
 
-/**
- * Generic type for partial data updates
- */
-export type PartialDataRecord<TData extends DataRecord> = Partial<TData>;
-
-/**
- * Generic type for complete data records
- */
-export type CompleteDataRecord<TData extends DataRecord> = TData;
-
 // ============================================================================
 // HIERARCHICAL DATA TYPES
 // ============================================================================
@@ -393,6 +383,12 @@ export interface SimpleColumn<TData extends DataRecord = DataRecord> {
  */
 export type ActionCondition<TData extends DataRecord> = boolean | ((row: TData) => boolean);
 
+/**
+ * Action definition for DataTable rows.
+ * Defines custom actions that can be performed on table rows.
+ * 
+ * @template TData - The type of data records in the table
+ */
 export interface DataTableAction<TData extends DataRecord> {
   /** Display label for the action */
   label: string;

package/src/components/DataTable/utils/a11yUtils.ts

@@ -211,6 +211,13 @@ export function announceBulkOperation(operation: string, count: number): void {
  * Get ARIA sort value for column headers
  * @param sortDirection - Current sort direction
  */
+/**
+ * Converts TanStack Table sort direction to ARIA sort value.
+ * Maps table sort states to accessible ARIA attributes.
+ * 
+ * @param sortDirection - Sort direction from TanStack Table
+ * @returns ARIA sort value for accessibility
+ */
 export function getAriaSortValue(sortDirection: 'asc' | 'desc' | false): 'ascending' | 'descending' | 'none' {
   if (sortDirection === 'asc') return 'ascending';
   if (sortDirection === 'desc') return 'descending';