@jmruthers/pace-core 0.5.1 → 0.5.4

package/src/components/RBAC/RoleBasedContent.tsx

@@ -1,129 +0,0 @@
-/**
- * @file Role-Based Content Component
- * @package @jmruthers/pace-core
- * @module Components/RBAC
- * @since 0.3.0
- *
- * A component that conditionally renders children based on user roles.
- * This component integrates with the new RBAC system to provide role-based
- * UI rendering with support for multiple role types.
- *
- * Features:
- * - Role-based conditional rendering
- * - Support for global, organisation, and event-app roles
- * - Multiple role checking
- * - Fallback content support
- * - Type-safe role checking
- * - Automatic context detection
- *
- * @example
- * ```tsx
- * import { RoleBasedContent } from '@jmruthers/pace-core';
- * 
- * function MyComponent() {
- *   return (
- *     <div>
- *       <h1>Admin Panel</h1>
- *       
- *       <RoleBasedContent globalRoles={['super_admin']}>
- *         <SuperAdminPanel />
- *       </RoleBasedContent>
- *       
- *       <RoleBasedContent organisationRoles={['org_admin', 'leader']}>
- *         <OrganisationManagementPanel />
- *       </RoleBasedContent>
- *       
- *       <RoleBasedContent eventAppRoles={['event_admin', 'planner']}>
- *         <EventManagementPanel />
- *       </RoleBasedContent>
- *       
- *       <RoleBasedContent 
- *         globalRoles={['super_admin']}
- *         organisationRoles={['org_admin']}
- *         fallback={<p>You need admin privileges to access this content.</p>}
- *       >
- *         <AdminOnlyContent />
- *       </RoleBasedContent>
- *     </div>
- *   );
- * }
- * ```
- *
- * @accessibility
- * - Supports screen reader friendly conditional content
- * - Maintains focus management in conditional renders
- * - Provides accessible fallback content
- *
- * @security
- * - Role-based access control
- * - Secure role checking
- * - Organisation context enforcement
- *
- * @performance
- * - Optimized with React.memo
- * - Minimal re-renders
- * - Efficient role checking
- *
- * @dependencies
- * - React 18+ - Components and hooks
- * - useRBAC hook - Role checking
- * - RBAC types - Type definitions
- */
-
-import React from 'react';
-import { useRBAC } from '../../hooks/useRBAC';
-import type { 
-  RoleBasedContentProps, 
-  GlobalRole, 
-  OrganisationRole, 
-  EventAppRole 
-} from '../../rbac/types';
-
-export function RoleBasedContent({ 
-  children, 
-  globalRoles = [], 
-  organisationRoles = [], 
-  eventAppRoles = [], 
-  fallback = null 
-}: RoleBasedContentProps) {
-  const { 
-    globalRole, 
-    organisationRole, 
-    eventAppRole, 
-    isLoading, 
-    error 
-  } = useRBAC();
-
-  // Show loading state while checking roles
-  if (isLoading) {
-    return (
-      <div className="rbac-loading" role="status" aria-live="polite">
-        <span className="sr-only">Checking roles...</span>
-      </div>
-    );
-  }
-
-  // Show error state - render fallback if provided, otherwise null
-  if (error) {
-    if (fallback) {
-      return (
-        <div className="rbac-error" role="alert">
-          <span className="sr-only">Role check error</span>
-          {fallback}
-        </div>
-      );
-    }
-    return null;
-  }
-
-  // Check if user has any of the required roles
-  const hasGlobalRole = globalRoles.length > 0 && globalRole && globalRoles.includes(globalRole as GlobalRole);
-  const hasOrgRole = organisationRoles.length > 0 && organisationRole && organisationRoles.includes(organisationRole as OrganisationRole);
-  const hasEventRole = eventAppRoles.length > 0 && eventAppRole && eventAppRoles.includes(eventAppRole as EventAppRole);
-
-  // User has access if they have any of the required roles
-  const hasAccess = hasGlobalRole || hasOrgRole || hasEventRole;
-
-  // Render children if user has required role, otherwise show fallback
-  return hasAccess ? <>{children}</> : <>{fallback}</>;
-} 

package/src/components/RBAC/index.ts

@@ -1,23 +0,0 @@
-/**
- * RBAC Components Index
- * @package @jmruthers/pace-core
- * @module Components/RBAC
- * @since 0.3.0
- */
-
-// Export RBAC components
-export { RBACGuard } from './RBACGuard';
-export { RoleBasedContent } from './RoleBasedContent';
-export { RBACProvider } from './RBACProvider';
-export { 
-  PagePermissionGuard,
-  ReadPermissionGuard,
-  CreatePermissionGuard,
-  UpdatePermissionGuard,
-  DeletePermissionGuard,
-  PAGE_IDS
-} from './PagePermissionGuard';
-
-// Export types
-export type { RBACGuardProps } from '../../rbac/types';
-export type { RoleBasedContentProps } from '../../rbac/types'; 

package/src/rbac/hooks.ts

@@ -1,570 +0,0 @@
-/**
- * RBAC React Hooks
- * @package @jmruthers/pace-core
- * @module RBAC/Hooks
- * @since 1.0.0
- * 
- * This module provides React hooks for RBAC functionality.
- */
-
-import { useState, useEffect, useCallback, useMemo } from 'react';
-import { 
-  UUID, 
-  Scope, 
-  Permission, 
-  AccessLevel, 
-  PermissionMap,
-  UsePermissionsReturn,
-  UseCanReturn
-} from './types';
-import { 
-  getAccessLevel, 
-  getPermissionMap, 
-  isPermitted,
-  isPermittedCached 
-} from './api';
-
-/**
- * Hook to get user's permissions in a scope
- * 
- * @param userId - User ID
- * @param scope - Permission scope
- * @returns Permission data and loading state
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { permissions, isLoading, error } = usePermissions(
- *     'user-123',
- *     { organisationId: 'org-456' }
- *   );
- *   
- *   if (isLoading) return <div>Loading...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return (
- *     <div>
- *       {permissions['page-1']?.includes('read') && <ReadButton />}
- *       {permissions['page-1']?.includes('manage') && <ManageButton />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function usePermissions(userId: UUID, scope: Scope): UsePermissionsReturn {
-  const [permissions, setPermissions] = useState<PermissionMap>({});
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const fetchPermissions = useCallback(async () => {
-    if (!userId) {
-      setPermissions({});
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      const result = await getPermissionMap({ userId, scope });
-      setPermissions(result);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to fetch permissions'));
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId]);
-
-  useEffect(() => {
-    fetchPermissions();
-  }, [fetchPermissions]);
-
-  return {
-    permissions,
-    isLoading,
-    error,
-    refetch: fetchPermissions,
-  };
-}
-
-/**
- * Hook to check if user has a specific permission
- * 
- * @param userId - User ID
- * @param scope - Permission scope
- * @param permission - Permission to check
- * @param pageId - Optional page ID
- * @param useCache - Whether to use cached results (default: true)
- * @returns Permission check result and loading state
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { can, isLoading } = useCan(
- *     'user-123',
- *     { organisationId: 'org-456' },
- *     'manage:events',
- *     'page-789'
- *   );
- *   
- *   if (isLoading) return <div>Checking permission...</div>;
- *   
- *   return (
- *     <div>
- *       {can ? <AdminPanel /> : <AccessDenied />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useCan(
-  userId: UUID,
-  scope: Scope,
-  permission: Permission,
-  pageId?: UUID,
-  useCache: boolean = true
-): UseCanReturn {
-  const [can, setCan] = useState(false);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const check = useCallback(async () => {
-    console.log('[useCan] check() called with:', { userId, scope, permission, pageId });
-    console.log('[useCan] Hook parameters:', { userId, scope, permission, pageId, useCache });
-    
-    if (!userId) {
-      console.log('[useCan] No userId, denying access');
-      setCan(false);
-      setIsLoading(false);
-      return;
-    }
-
-    // Check for super admin status first - super admins bypass all scope requirements
-    try {
-      const { isSuperAdmin } = await import('./api');
-      const isSuper = await isSuperAdmin(userId);
-      if (isSuper) {
-        console.log('[useCan] User is super admin, granting access');
-        setCan(true);
-        setIsLoading(false);
-        return;
-      }
-    } catch (error) {
-      console.error('[useCan] Error checking super admin status:', error);
-      // Continue with normal permission check if super admin check fails
-    }
-
-    // Check if scope is incomplete (missing required fields)
-    if (!scope || !scope.organisationId || !scope.appId) {
-      console.log('[useCan] Incomplete scope, waiting for resolution:', scope);
-      setCan(false);
-      setIsLoading(true); // Keep loading until scope is complete
-      return;
-    }
-
-    console.log('[useCan] Scope is complete, checking permission...');
-    console.log('[useCan] Detailed scope info:', {
-      organisationId: scope.organisationId,
-      eventId: scope.eventId,
-      appId: scope.appId,
-      permission,
-      pageId
-    });
-    
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      console.log('[useCan] About to call isPermitted/isPermittedCached...');
-      const result = useCache 
-        ? await isPermittedCached({ userId, scope, permission, pageId })
-        : await isPermitted({ userId, scope, permission, pageId });
-      
-      console.log('[useCan] Permission check result:', result);
-      console.log('[useCan] Permission check details:', {
-        userId,
-        scope,
-        permission,
-        pageId,
-        result,
-        timestamp: new Date().toISOString()
-      });
-      setCan(result);
-    } catch (err) {
-      console.error('[useCan] Permission check error:', err);
-      console.error('[useCan] Error details:', {
-        userId,
-        scope,
-        permission,
-        pageId,
-        error: err instanceof Error ? err.message : 'Unknown error',
-        timestamp: new Date().toISOString()
-      });
-      setError(err instanceof Error ? err : new Error('Failed to check permission'));
-      setCan(false);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId, permission, pageId, useCache]);
-
-  useEffect(() => {
-    check();
-  }, [check]);
-
-  return {
-    can,
-    isLoading,
-    error,
-    check,
-  };
-}
-
-/**
- * Hook to get user's access level in a scope
- * 
- * @param userId - User ID
- * @param scope - Permission scope
- * @returns Access level and loading state
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { accessLevel, isLoading } = useAccessLevel(
- *     'user-123',
- *     { organisationId: 'org-456' }
- *   );
- *   
- *   if (isLoading) return <div>Loading...</div>;
- *   
- *   return (
- *     <div>
- *       {accessLevel === 'super' && <SuperAdminPanel />}
- *       {accessLevel === 'admin' && <AdminPanel />}
- *       {accessLevel === 'planner' && <PlannerPanel />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useAccessLevel(userId: UUID, scope: Scope): {
-  accessLevel: AccessLevel | null;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const [accessLevel, setAccessLevel] = useState<AccessLevel | null>(null);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const fetchAccessLevel = useCallback(async () => {
-    if (!userId) {
-      setAccessLevel(null);
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      const result = await getAccessLevel({ userId, scope });
-      setAccessLevel(result);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to fetch access level'));
-      setAccessLevel(null);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId]);
-
-  useEffect(() => {
-    fetchAccessLevel();
-  }, [fetchAccessLevel]);
-
-  return {
-    accessLevel,
-    isLoading,
-    error,
-    refetch: fetchAccessLevel,
-  };
-}
-
-/**
- * Hook to check multiple permissions at once
- * 
- * @param userId - User ID
- * @param scope - Permission scope
- * @param permissions - Array of permissions to check
- * @param pageId - Optional page ID
- * @param useCache - Whether to use cached results (default: true)
- * @returns Object with permission results and loading state
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { permissions, isLoading } = useMultiplePermissions(
- *     'user-123',
- *     { organisationId: 'org-456' },
- *     ['read:events', 'manage:events', 'delete:events']
- *   );
- *   
- *   return (
- *     <div>
- *       {permissions['read:events'] && <ReadButton />}
- *       {permissions['manage:events'] && <ManageButton />}
- *       {permissions['delete:events'] && <DeleteButton />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useMultiplePermissions(
-  userId: UUID,
-  scope: Scope,
-  permissions: Permission[],
-  pageId?: UUID,
-  useCache: boolean = true
-): {
-  permissions: Record<Permission, boolean>;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const [permissionResults, setPermissionResults] = useState<Record<Permission, boolean>>({} as Record<Permission, boolean>);
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const fetchPermissions = useCallback(async () => {
-    if (!userId || permissions.length === 0) {
-      setPermissionResults({} as Record<Permission, boolean>);
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      const results: Record<Permission, boolean> = {} as Record<Permission, boolean>;
-      
-      // Check all permissions in parallel
-      const promises = permissions.map(async (permission) => {
-        const result = useCache 
-          ? await isPermittedCached({ userId, scope, permission, pageId })
-          : await isPermitted({ userId, scope, permission, pageId });
-        
-        return { permission, result };
-      });
-      
-      const resolved = await Promise.all(promises);
-      
-      resolved.forEach(({ permission, result }) => {
-        results[permission] = result;
-      });
-      
-      setPermissionResults(results);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to check permissions'));
-      setPermissionResults({} as Record<Permission, boolean>);
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId, permissions, pageId, useCache]);
-
-  useEffect(() => {
-    fetchPermissions();
-  }, [fetchPermissions]);
-
-  return {
-    permissions: permissionResults,
-    isLoading,
-    error,
-    refetch: fetchPermissions,
-  };
-}
-
-/**
- * Hook to check if user has any of the specified permissions
- * 
- * @param userId - User ID
- * @param scope - Permission scope
- * @param permissions - Array of permissions to check
- * @param pageId - Optional page ID
- * @returns True if user has any permission and loading state
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { hasAny, isLoading } = useHasAnyPermission(
- *     'user-123',
- *     { organisationId: 'org-456' },
- *     ['read:events', 'manage:events']
- *   );
- *   
- *   return (
- *     <div>
- *       {hasAny ? <EventContent /> : <AccessDenied />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useHasAnyPermission(
-  userId: UUID,
-  scope: Scope,
-  permissions: Permission[],
-  pageId?: UUID
-): {
-  hasAny: boolean;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const { permissions: permissionResults, isLoading, error, refetch } = useMultiplePermissions(
-    userId,
-    scope,
-    permissions,
-    pageId
-  );
-
-  const hasAny = useMemo(() => {
-    return Object.values(permissionResults).some(Boolean);
-  }, [permissionResults]);
-
-  return {
-    hasAny,
-    isLoading,
-    error,
-    refetch,
-  };
-}
-
-/**
- * Hook to check if user has all of the specified permissions
- * 
- * @param userId - User ID
- * @param scope - Permission scope
- * @param permissions - Array of permissions to check
- * @param pageId - Optional page ID
- * @returns True if user has all permissions and loading state
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { hasAll, isLoading } = useHasAllPermissions(
- *     'user-123',
- *     { organisationId: 'org-456' },
- *     ['read:events', 'manage:events']
- *   );
- *   
- *   return (
- *     <div>
- *       {hasAll ? <FullAccessPanel /> : <LimitedAccessPanel />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useHasAllPermissions(
-  userId: UUID,
-  scope: Scope,
-  permissions: Permission[],
-  pageId?: UUID
-): {
-  hasAll: boolean;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const { permissions: permissionResults, isLoading, error, refetch } = useMultiplePermissions(
-    userId,
-    scope,
-    permissions,
-    pageId
-  );
-
-  const hasAll = useMemo(() => {
-    return Object.values(permissionResults).every(Boolean);
-  }, [permissionResults]);
-
-  return {
-    hasAll,
-    isLoading,
-    error,
-    refetch,
-  };
-}
-
-/**
- * Hook to read cached permissions (contract requirement)
- * 
- * This hook only reads from the core cache and does not perform
- * any bespoke caching as per the contract requirements.
- * 
- * @param userId - User ID
- * @param scope - Permission scope
- * @returns Cached permission data and loading state
- * 
- * @example
- * ```tsx
- * function MyComponent() {
- *   const { permissions, isLoading, error } = useCachedPermissions(
- *     'user-123',
- *     { organisationId: 'org-456' }
- *   );
- *   
- *   if (isLoading) return <div>Loading cached permissions...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
- *   
- *   return (
- *     <div>
- *       {permissions['page-1']?.includes('read') && <ReadButton />}
- *       {permissions['page-1']?.includes('manage') && <ManageButton />}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useCachedPermissions(userId: UUID, scope: Scope): {
-  permissions: PermissionMap;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-} {
-  const [permissions, setPermissions] = useState<PermissionMap>({});
-  const [isLoading, setIsLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-
-  const fetchCachedPermissions = useCallback(async () => {
-    if (!userId) {
-      setPermissions({});
-      setIsLoading(false);
-      return;
-    }
-
-    try {
-      setIsLoading(true);
-      setError(null);
-      
-      // Use cached version of getPermissionMap
-      const result = await getPermissionMap({ userId, scope });
-      setPermissions(result);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to fetch cached permissions'));
-    } finally {
-      setIsLoading(false);
-    }
-  }, [userId, scope.organisationId, scope.eventId, scope.appId]);
-
-  useEffect(() => {
-    fetchCachedPermissions();
-  }, [fetchCachedPermissions]);
-
-  return {
-    permissions,
-    isLoading,
-    error,
-    refetch: fetchCachedPermissions,
-  };
-}