@jmruthers/pace-core 0.6.1 → 0.6.2

package/src/components/NavigationMenu/useNavigationFiltering.ts

@@ -0,0 +1,390 @@
+import * as React from "react";
+import { useUnifiedAuth } from "../../providers/services/UnifiedAuthProvider";
+import { useRBAC } from "../../rbac/hooks/useRBAC";
+import { useResolvedScope } from "../../rbac/hooks";
+import { usePermissions } from "../../rbac/hooks/usePermissions";
+import type {
+  Permission,
+  AccessLevel as RBACAccessLevel,
+  UUID,
+  PermissionMap,
+} from "../../rbac/types";
+import { logger } from "../../utils/core/logger";
+import type { NavigationItem } from "./types";
+
+/**
+ * Options for the useNavigationFiltering hook.
+ */
+interface UseNavigationFilteringOptions {
+  items: NavigationItem[];
+  itemsPreFiltered?: boolean;
+  auditLog?: boolean;
+}
+
+/**
+ * Return value of the useNavigationFiltering hook.
+ */
+interface UseNavigationFilteringResult {
+  authContext: ReturnType<typeof useUnifiedAuth> | null;
+  rbacContext: ReturnType<typeof useRBAC> | null;
+  filteredItems: NavigationItem[];
+  permissionMap: PermissionMap;
+  hasAnyPermission: ((permissions: Permission[]) => boolean) | null;
+}
+
+/**
+ * Hook for filtering navigation items based on RBAC permissions.
+ * Filters navigation items to show only those the user has access to.
+ * 
+ * @param options - Navigation filtering configuration
+ * @returns Filtered navigation items and permission context
+ */
+export function useNavigationFiltering({
+  items,
+  itemsPreFiltered = false,
+  auditLog = true,
+}: UseNavigationFilteringOptions): UseNavigationFilteringResult {
+  const [resolvedAppId, setResolvedAppId] = React.useState<string | undefined>(undefined);
+  const previousFilteredItemsRef = React.useRef<NavigationItem[]>([]);
+
+  let authContext = null;
+  try {
+    authContext = useUnifiedAuth();
+  } catch (error) {
+    logger.warn(
+      "NavigationMenu",
+      "useUnifiedAuth not available, running in unauthenticated mode",
+    );
+  }
+
+  let rbacContext = null;
+  try {
+    rbacContext = useRBAC();
+  } catch (error) {
+    logger.warn(
+      "NavigationMenu",
+      "useRBAC not available, permission filtering disabled",
+    );
+  }
+
+  const eventLoadingRaw = authContext?.eventLoading;
+  const eventLoading = eventLoadingRaw ?? false;
+  const selectedEvent = authContext?.selectedEvent || null;
+  const orgContextReady =
+    authContext?.isContextReady ?? (authContext?.selectedOrganisation?.id ? true : false);
+
+  const { supabase } = authContext || {};
+  const { selectedOrganisation } = authContext || {};
+  const { resolvedScope, isLoading: scopeLoading, error: scopeError } = useResolvedScope({
+    supabase: itemsPreFiltered ? null : supabase || null,
+    selectedOrganisationId: itemsPreFiltered ? null : selectedOrganisation?.id || null,
+    selectedEventId: itemsPreFiltered ? null : selectedEvent?.event_id || null,
+  });
+
+  React.useEffect(() => {
+    if (
+      !scopeLoading &&
+      !resolvedScope?.appId &&
+      selectedOrganisation?.id &&
+      authContext?.appName &&
+      authContext?.user?.id &&
+      !resolvedAppId
+    ) {
+      if (!authContext.user || !authContext.appName) {
+        return;
+      }
+      const userId = authContext.user.id;
+      const appName = authContext.appName;
+      import("../../rbac/api")
+        .then(({ resolveAppContext }) => {
+          resolveAppContext({
+            userId,
+            appName,
+          })
+            .then((result) => {
+              if (result?.appId) {
+                setResolvedAppId(result.appId);
+              }
+            })
+            .catch(() => {});
+        })
+        .catch(() => {});
+    }
+  }, [
+    scopeLoading,
+    resolvedScope?.appId,
+    selectedOrganisation?.id,
+    authContext?.appName,
+    authContext?.user?.id,
+    resolvedAppId,
+  ]);
+
+  const effectiveScope = React.useMemo(() => {
+    if (resolvedScope?.organisationId) {
+      return resolvedScope;
+    }
+
+    if (selectedOrganisation?.id) {
+      const fallbackScope = {
+        organisationId: selectedOrganisation.id,
+        eventId: selectedEvent?.event_id || undefined,
+        appId: resolvedAppId,
+      };
+      return fallbackScope;
+    }
+
+    return null;
+  }, [resolvedScope, selectedOrganisation?.id, selectedEvent?.event_id, resolvedAppId]);
+
+  const scopeKey = effectiveScope
+    ? `${effectiveScope.organisationId || ""}-${effectiveScope.eventId || ""}-${
+        effectiveScope.appId || ""
+      }`
+    : "empty";
+
+  const stableScope = React.useMemo(() => {
+    if (effectiveScope?.organisationId) {
+      return {
+        organisationId: effectiveScope.organisationId,
+        eventId: effectiveScope.eventId,
+        appId: effectiveScope.appId,
+      };
+    }
+    return {
+      organisationId: "",
+      eventId: undefined,
+      appId: undefined,
+    };
+  }, [scopeKey, effectiveScope]);
+
+  const userId = (authContext?.user?.id || "") as UUID;
+  const {
+    permissions: permissionMap,
+    hasAnyPermission,
+    isLoading: permissionsLoading,
+    error: permissionsError,
+  } = usePermissions(
+    itemsPreFiltered ? (null as any) : userId,
+    itemsPreFiltered ? undefined : stableScope.organisationId,
+    itemsPreFiltered ? undefined : stableScope.eventId,
+    itemsPreFiltered ? undefined : stableScope.appId,
+  );
+
+  const filteredItems = React.useMemo(() => {
+    if (itemsPreFiltered && items && items.length > 0) {
+      const visibleItems = (items || []).filter((item) => !item.meta?.hidden);
+      previousFilteredItemsRef.current = visibleItems;
+      return visibleItems;
+    }
+
+    const isOrgContextReady = orgContextReady && selectedOrganisation?.id;
+    const isEventContextReady = eventLoadingRaw === undefined ? true : !eventLoading;
+    const hasValidContext = isOrgContextReady && isEventContextReady;
+    const shouldWaitForScope = scopeLoading || !hasValidContext;
+    const shouldRetryAfterError = scopeError && hasValidContext && !scopeLoading;
+
+    if (items && items.length > 0 && selectedOrganisation?.id) {
+      const visibleItems = (items || []).filter((item) => !item.meta?.hidden);
+      previousFilteredItemsRef.current = visibleItems;
+      return visibleItems;
+    }
+
+    if (!authContext || !rbacContext || (shouldWaitForScope && !shouldRetryAfterError)) {
+      return [];
+    }
+
+    if (permissionsLoading) {
+      if (previousFilteredItemsRef.current.length > 0) {
+        return previousFilteredItemsRef.current;
+      }
+      if (items && items.length > 0 && stableScope.organisationId) {
+        return (items || []).filter((item) => !item.meta?.hidden);
+      }
+      return [];
+    }
+
+    if (permissionsError) {
+      logger.warn(
+        "NavigationMenu",
+        "Permission check error - showing no items for security",
+        {
+          permissionsError: permissionsError?.message,
+        },
+      );
+      return [];
+    }
+
+    if (!permissionMap || Object.keys(permissionMap).length === 0) {
+      if (stableScope.organisationId && items && items.length > 0) {
+        return (items || []).filter((item) => !item.meta?.hidden);
+      }
+
+      if (stableScope.organisationId) {
+        logger.warn("NavigationMenu", "Permission map is empty and no items provided - showing nothing", {
+          permissionMapSize: 0,
+          organisationId: stableScope.organisationId,
+          eventId: stableScope.eventId,
+          appId: stableScope.appId,
+        });
+      }
+      return [];
+    }
+
+    const getPageIdFromHref = (href?: string): string | null => {
+      if (!href) return null;
+      const path = href.split("?")[0].split("#")[0].replace(/^\//, "");
+      return path || "home";
+    };
+
+    const hasItemPermission = (item: NavigationItem): boolean => {
+      if (item.permissions && item.permissions.length > 0 && !item.href) {
+        const permissions = item.permissions
+          .filter((p): p is string => typeof p === "string")
+          .map((p) => p as Permission);
+
+        if (permissions.length > 0) {
+          const hasPermission = hasAnyPermission?.(permissions);
+          if (!hasPermission) {
+            return false;
+          }
+        }
+      }
+
+      if (item.roles && item.roles.length > 0) {
+        const hasRole = item.roles.some((role) => {
+          if (typeof role !== "string") return true;
+
+          switch (role.toLowerCase()) {
+            case "super_admin":
+            case "super admin":
+              return rbacContext.isSuperAdmin;
+            case "org_admin":
+            case "org admin":
+            case "admin":
+              return rbacContext.isOrgAdmin || rbacContext.isSuperAdmin;
+            case "event_admin":
+            case "event admin":
+              return rbacContext.isEventAdmin || rbacContext.isSuperAdmin;
+            default:
+              return (
+                rbacContext.organisationRole === role ||
+                rbacContext.eventAppRole === role ||
+                rbacContext.isSuperAdmin
+              );
+          }
+        });
+        if (!hasRole) {
+          return false;
+        }
+      }
+
+      if (item.accessLevel) {
+        if (typeof item.accessLevel === "string") {
+          const accessLevel = item.accessLevel.toLowerCase() as RBACAccessLevel;
+          const userEventRole = rbacContext.eventAppRole;
+
+          if (!rbacContext.isSuperAdmin) {
+            const roleToAccessLevel: Record<string, RBACAccessLevel> = {
+              viewer: "viewer",
+              participant: "participant",
+              planner: "planner",
+              event_admin: "admin",
+            };
+            const userAccessLevel = userEventRole ? roleToAccessLevel[userEventRole] || "viewer" : null;
+
+            const levelHierarchy: Record<RBACAccessLevel, number> = {
+              viewer: 1,
+              participant: 2,
+              planner: 3,
+              admin: 4,
+              super: 5,
+            };
+            const requiredLevel = levelHierarchy[accessLevel] || 0;
+            const userLevel = userAccessLevel ? levelHierarchy[userAccessLevel] || 0 : 0;
+
+            if (userLevel < requiredLevel) {
+              return false;
+            }
+          }
+        }
+      }
+
+      if (item.href) {
+        const pageId = item.pageId || getPageIdFromHref(item.href);
+        if (pageId) {
+          const pagePermission: Permission = `read:page.${pageId}` as Permission;
+
+          const isSuperAdmin = permissionMap["*"] === true;
+          const hasPagePermission = permissionMap[pagePermission] === true;
+          const finalHasPermission = isSuperAdmin || hasPagePermission;
+
+          if (!finalHasPermission) {
+            return false;
+          }
+        }
+      }
+
+      return true;
+    };
+
+    const filterItem = (item: NavigationItem): NavigationItem | null => {
+      if (item.meta?.hidden) return null;
+
+      if (!hasItemPermission(item)) return null;
+
+      let filteredChildren: NavigationItem[] | undefined;
+      if (item.children && item.children.length > 0) {
+        filteredChildren = item.children
+          .map((child) => filterItem(child))
+          .filter((child): child is NavigationItem => child !== null);
+
+        if (filteredChildren.length === 0 && !item.href) {
+          return null;
+        }
+      }
+
+      return {
+        ...item,
+        children: filteredChildren,
+      };
+    };
+
+    const filtered = (items || [])
+      .map((item) => filterItem(item))
+      .filter((item): item is NavigationItem => item !== null);
+
+    previousFilteredItemsRef.current = filtered;
+
+    return filtered;
+  }, [
+    items,
+    itemsPreFiltered,
+    authContext,
+    rbacContext,
+    permissionMap,
+    hasAnyPermission,
+    scopeLoading,
+    scopeError,
+    permissionsLoading,
+    resolvedScope,
+    effectiveScope,
+    auditLog,
+    eventLoadingRaw,
+    eventLoading,
+    selectedEvent,
+    orgContextReady,
+    selectedOrganisation?.id,
+    permissionsError,
+    stableScope.organisationId,
+    stableScope.eventId,
+    stableScope.appId,
+  ]);
+
+  return {
+    authContext,
+    rbacContext,
+    filteredItems,
+    permissionMap,
+    hasAnyPermission: hasAnyPermission || null,
+  };
+}

package/src/components/OrganisationSelector/OrganisationSelector.tsx

@@ -63,6 +63,9 @@ import { useOrganisations } from '../../hooks/useOrganisations';
 import type { Organisation } from '../../types/organisation';
 import { logger } from '../../utils/core/logger';
 
+/**
+ * Props for the OrganisationSelector component.
+ */
 export interface OrganisationSelectorProps {
   /** Placeholder text for the dropdown */
   placeholder?: string;

package/src/components/PaceAppLayout/PaceAppLayout.test.tsx

@@ -889,7 +889,7 @@ describe('PaceAppLayout Component', () => {
       );
       
       await waitFor(() => {
-        // useCan is called with userId, scope, permission, pageId, useCache, appName
+        // useCan is called with userId, scope, permission, pageId, useCache, precomputedSuperAdmin, appName
         expect(mockUseCan).toHaveBeenCalledWith(
           'user-123',
           expect.objectContaining({
@@ -900,6 +900,7 @@ describe('PaceAppLayout Component', () => {
           'update:page.dashboard-page',
           'dashboard-page',
           true,
+          expect.any(Boolean), // precomputedSuperAdmin - can be false, null, or undefined during checks
           'Test App'
         );
       }, { timeout: 2000 });
@@ -921,7 +922,7 @@ describe('PaceAppLayout Component', () => {
       );
       
       await waitFor(() => {
-        // useCan is called with userId, scope, permission, pageId, useCache, appName
+        // useCan is called with userId, scope, permission, pageId, useCache, precomputedSuperAdmin, appName
         // Uses defaultPermission "create" since /dashboard is not in routePermissions
         expect(mockUseCan).toHaveBeenCalledWith(
           'user-123',
@@ -933,6 +934,7 @@ describe('PaceAppLayout Component', () => {
           'create:page.dashboard',
           'dashboard',
           true,
+          expect.any(Boolean), // precomputedSuperAdmin - can be false, null, or undefined during checks
           'Test App'
         );
       }, { timeout: 2000 });

package/src/components/PaceAppLayout/PaceAppLayout.tsx

@@ -121,6 +121,10 @@ import type { PasswordChangeFormError } from '../PasswordChange/PasswordChangeFo
 // Define Operation type locally since old RBAC types are removed
 type Operation = 'read' | 'create' | 'update' | 'delete' | 'manage';
 
+/**
+ * Props for the PaceAppLayout component.
+ * Configures the application layout including navigation, header, and footer.
+ */
 export interface PaceAppLayoutProps {
   /** The name of the application to be displayed in the header. */
   appName: string;
@@ -524,12 +528,15 @@ export function PaceAppLayout({
   // Pass appName to useCan so it can be passed to isPermitted for PORTAL/ADMIN special case
   // Only check permissions if enforcePermissions is true and we have a valid permission string
   const shouldCheckPermission = enforcePermissions && !!currentPermission && !!currentPageId;
+  // Pass super admin status to avoid duplicate check - use null if still checking, false/true if known
+  const superAdminStatus = isSuperAdminFromRBAC ? true : (isCheckingSuperAdminDirect ? null : isSuperAdminDirect);
   const { can: canFromHook, isLoading: isCheckingPermission, error: permissionError } = useCan(
     user?.id || '',
     scope,
     shouldCheckPermission ? currentPermission : ('' as Permission),
     shouldCheckPermission ? currentPageId : '',
     true, // useCache
+    superAdminStatus, // Pass super admin status to avoid duplicate check
     appName // Pass appName for PORTAL/ADMIN special case
   );
 
@@ -817,25 +824,39 @@ export function PaceAppLayout({
   }, [roleBasedRouting, routeConfig, location.pathname, strictMode, user?.id, fallbackRoute, scope, navigate, auditLog, onRouteAccessDenied, onRouteStrictModeViolation]);
 
   const handleSignOut = async () => {
-    await signOut();
+    try {
+      await signOut();
+    } catch (error) {
+      logger.error('PaceAppLayout', 'Failed to sign out', { error: error instanceof Error ? error.message : String(error) });
+    }
   };
 
   const handleChangePassword = async (newPassword: string, confirmPassword: string) => {
-    // The form component in UserMenu already checks for matching passwords
-    const result = await updatePassword(newPassword);
-    if (result?.error) {
-      // The form will display the error message
-      logger.error('PaceAppLayout', 'Failed to change password', { error: result.error.message });
-      // Convert AuthError to PasswordChangeFormError
+    try {
+      // The form component in UserMenu already checks for matching passwords
+      const result = await updatePassword(newPassword);
+      if (result?.error) {
+        // The form will display the error message
+        logger.error('PaceAppLayout', 'Failed to change password', { error: result.error.message });
+        // Convert AuthError to PasswordChangeFormError
+        return {
+          error: {
+            message: result.error.message,
+            code: result.error.name || 'PASSWORD_UPDATE_ERROR'
+          }
+        };
+      }
+      // The form will handle closing the modal on success
+      return {};
+    } catch (error) {
+      logger.error('PaceAppLayout', 'Failed to change password', { error: error instanceof Error ? error.message : String(error) });
       return {
         error: {
-          message: result.error.message,
-          code: result.error.name || 'PASSWORD_UPDATE_ERROR'
+          message: error instanceof Error ? error.message : 'An unexpected error occurred',
+          code: 'PASSWORD_UPDATE_ERROR'
         }
       };
     }
-    // The form will handle closing the modal on success
-    return {};
   };
 
   // CRITICAL: Wait for organisation context to be ready before proceeding

package/src/components/PaceAppLayout/test-setup.tsx

@@ -1,3 +1,4 @@
+/// <reference types="vitest/globals" />
 /**
  * @file Shared Test Setup for PaceAppLayout Tests
  * @package @jmruthers/pace-core
@@ -10,8 +11,6 @@
  * provides the shared mock data and reset functions that can be imported and used
  * in the vi.mock() factory functions.
  */
-
-import { vi } from 'vitest';
 import React from 'react';
 
 // === MOCK DATA ===

package/src/components/PaceLoginPage/PaceLoginPage.tsx

@@ -131,6 +131,9 @@ import { clearPalette } from '../../theming/runtime';
 import { EventServiceContext } from '../../providers/services/EventServiceProvider';
 import { logger } from '../../utils/core/logger';
 
+/**
+ * Props for the PaceLoginPage component.
+ */
 export interface PaceLoginPageProps {
   /** The name of the application to be displayed on the login form. */
   appName: string;

package/src/components/PasswordChange/PasswordChangeForm.tsx

@@ -103,16 +103,25 @@ import { Input } from '../Input/Input';
 import { Label } from '../Label';
 import { cn } from '../../utils/core/cn';
 
+/**
+ * Form values for password change.
+ */
 export interface PasswordChangeFormValues {
   newPassword: string;
   confirmPassword: string;
 }
 
+/**
+ * Error structure for password change form.
+ */
 export interface PasswordChangeFormError {
   message?: string;
   code?: string;
 }
 
+/**
+ * Props for the PasswordChangeForm component.
+ */
 export interface PasswordChangeFormProps {
   onSubmit: (values: PasswordChangeFormValues) => Promise<{ error?: PasswordChangeFormError }>;
   className?: string;

package/src/components/ProtectedRoute/ProtectedRoute.tsx

@@ -79,6 +79,9 @@ import { Alert, AlertDescription, AlertTitle } from '../Alert/Alert';
 import { logger } from '../../utils/core/logger';
 import { usePreventTabReload } from '../../hooks/usePreventTabReload';
 
+/**
+ * Props for the ProtectedRoute component.
+ */
 export interface ProtectedRouteProps {
   /**
    * Whether an event is required for routes inside this component.
@@ -88,14 +91,6 @@ export interface ProtectedRouteProps {
    */
   requireEvent?: boolean;
 
-  /**
-   * Whether super admins can bypass event requirement.
-   * Note: This feature requires additional RBAC setup. For simple bypass, set requireEvent={false} instead.
-   * @default false
-   * @deprecated Use requireEvent={false} for routes that don't need events
-   */
-  allowSuperAdminBypass?: boolean;
-
   /**
    * Custom component to render when no events are available.
    * If not provided, a default message is shown.
@@ -133,7 +128,6 @@ export interface ProtectedRouteProps {
  */
 export function ProtectedRoute({
   requireEvent = false,
-  allowSuperAdminBypass = false,
   noEventsFallback,
   loadingFallback,
   loginPath = '/login'

package/src/components/PublicLayout/PublicPageLayout.tsx

@@ -35,9 +35,9 @@
  *       refetch={refetch}
  *     >
  *       <h1>Event Details</h1>
- *       <div className="content">
+ *       <main className="content">
  *         Your public page content
- *       </div>
+ *       </main>
  *     </PublicPageLayout>
  *   );
  * }
@@ -90,8 +90,6 @@ export interface PublicPageLayoutProps {
   refetch?: () => Promise<void> | void;
   /** Whether to show the footer (default: true) */
   showFooter?: boolean;
-  /** @deprecated Custom CSS classes for the layout - no longer used as wrapper div was removed */
-  className?: string;
   /** Custom error fallback component */
   errorFallback?: React.ComponentType<{ error: Error; retry: () => void }>;
   /** Custom loading fallback component */
@@ -294,7 +292,6 @@ export function PublicPageLayout({
   error = null,
   refetch,
   showFooter = true,
-  className = '',
   errorFallback: ErrorFallback,
   loadingFallback: LoadingFallback,
   customHeader,

package/src/components/PublicLayout/PublicPageProvider.tsx

@@ -50,6 +50,10 @@ interface PublicPageContextType {
   };
 }
 
+/**
+ * Context for public pages.
+ * Provides isolated context for public pages without authentication requirements.
+ */
 export const PublicPageContext = createContext<PublicPageContextType | undefined>(undefined);
 
 export interface PublicPageProviderProps {