@jmruthers/pace-core 0.5.91 → 0.5.93

package/docs/api-reference/components.md

@@ -1212,7 +1212,152 @@ import { Label } from '@jmruthers/pace-core';
 
 ## Security Components
 
-Currently, security-sensitive UI should be enforced via RBAC hooks and server-side policies. No dedicated Super Admin UI guard is exported.
+### ProtectedRoute
+
+A route protection component that handles authentication and optional event selection without creating blocking issues. This component solves the common chicken-and-egg problem where apps check for `selectedEvent` before rendering, which blocks the event selector from being visible.
+
+#### Props
+
+```typescript
+interface ProtectedRouteProps {
+  /**
+   * Whether an event is required for routes inside this component.
+   * When true, routes will only render if an event is selected or can be selected.
+   * When false, routes render regardless of event state.
+   * @default true
+   */
+  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.
+   */
+  noEventsFallback?: React.ReactNode;
+
+  /**
+   * Custom component to render while events are loading.
+   * If not provided, a default loading spinner is shown.
+   */
+  loadingFallback?: React.ReactNode;
+
+  /**
+   * Login redirect path when user is not authenticated.
+   * @default '/login'
+   */
+  loginPath?: string;
+}
+```
+
+#### Usage
+
+**Basic Usage (with event requirement):**
+```tsx
+import { ProtectedRoute } from '@jmruthers/pace-core';
+import { Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      <Route element={<ProtectedRoute />}>
+        <Route path="/dashboard" element={<DashboardPage />} />
+        <Route path="/events" element={<EventsPage />} />
+      </Route>
+    </Routes>
+  );
+}
+```
+
+**Without Event Requirement:**
+```tsx
+<Route element={<ProtectedRoute requireEvent={false} />}>
+  <Route path="/settings" element={<SettingsPage />} />
+</Route>
+```
+
+**Custom Fallbacks:**
+```tsx
+<Route element={
+  <ProtectedRoute
+    requireEvent={true}
+    loginPath="/login"
+    loadingFallback={<CustomLoader />}
+    noEventsFallback={
+      <div>
+        <h2>No Events Available</h2>
+        <p>Contact your administrator for access.</p>
+      </div>
+    }
+  />
+}>
+  <Route path="/dashboard" element={<DashboardPage />} />
+</Route>
+```
+
+#### Features
+
+- ✅ **Authentication checking** - Redirects to login if not authenticated
+- ✅ **Session restoration** - Handles session restoration states automatically
+- ✅ **Event loading management** - Allows rendering during event loading (prevents UI blocking)
+- ✅ **Event selector visibility** - Allows rendering when events exist but none selected (so event selector in header is visible)
+- ✅ **Clear error states** - Shows helpful messages when no events are available
+- ✅ **Flexible configuration** - Optional event requirement, customizable fallbacks
+
+#### Important Notes
+
+The `ProtectedRoute` component solves a critical UX issue: **When apps check for `selectedEvent` before rendering, the event selector dropdown (typically in `PaceAppLayout` header) is never visible, creating a deadlock where users cannot select an event.**
+
+This component allows rendering when:
+- Events are loading (prevents blocking UI)
+- Events exist but none selected (allows event selector to be visible)
+- Individual pages should handle "no selected event" state gracefully
+
+#### Example: Complete App Setup
+
+```tsx
+import { 
+  UnifiedAuthProvider, 
+  ProtectedRoute, 
+  PaceAppLayout 
+} from '@jmruthers/pace-core';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <UnifiedAuthProvider
+      supabaseClient={supabase}
+      appName="my-app"
+      idleTimeoutMs={30 * 60 * 1000}
+      warnBeforeMs={60 * 1000}
+      onIdleLogout={() => window.location.href = '/login'}
+    >
+      <BrowserRouter>
+        <Routes>
+          <Route path="/login" element={<PaceLoginPage appName="My App" />} />
+          <Route element={<ProtectedRoute />}>
+            <Route element={<PaceAppLayout appName="My App" />}>
+              <Route path="/" element={<DashboardPage />} />
+              <Route path="/events" element={<EventsPage />} />
+            </Route>
+          </Route>
+        </Routes>
+      </BrowserRouter>
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+For more details, see the [Authentication Implementation Guide](../implementation-guides/authentication.md#protected-routes).
+
+---
 
 ### PasswordChangeForm
 

package/docs/best-practices/common-patterns.md

@@ -44,19 +44,37 @@ function App() {
 
 ### Protected Routes
 
-```tsx
-import { useUnifiedAuth, Navigate } from '@jmruthers/pace-core';
-
-function ProtectedRoute({ children }: { children: React.ReactNode }) {
-  const { user, loading } = useUnifiedAuth();
+**✅ Use the standard ProtectedRoute component from pace-core:**
 
-  if (loading) return <div>Loading...</div>;
-  if (!user) return <Navigate to="/login" />;
+```tsx
+import { ProtectedRoute } from '@jmruthers/pace-core';
+import { Routes, Route } from 'react-router-dom';
 
-  return <>{children}</>;
+function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      {/* Routes requiring authentication and event selection */}
+      <Route element={<ProtectedRoute />}>
+        <Route path="/dashboard" element={<DashboardPage />} />
+      </Route>
+      {/* Routes requiring authentication only (no event needed) */}
+      <Route element={<ProtectedRoute requireEvent={false} />}>
+        <Route path="/settings" element={<SettingsPage />} />
+      </Route>
+    </Routes>
+  );
 }
 ```
 
+**Why use the standard component?**
+- Prevents the chicken-and-egg problem where checking `selectedEvent` blocks the event selector from being visible
+- Handles session restoration automatically
+- Manages loading states properly
+- Provides consistent behavior across all pace apps
+
+**❌ Avoid custom ProtectedRoute implementations that block rendering when no event is selected**, as this prevents users from seeing the event selector dropdown in the header.
+
 ### Session Management
 
 ```tsx

package/docs/getting-started/examples/README.md

@@ -516,7 +516,7 @@ src/
 ├── components/
 │   ├── auth/
 │   │   ├── LoginPage.tsx     # Login form
-│   │   └── ProtectedRoute.tsx # Route protection
+│   │   └── (ProtectedRoute now provided by @jmruthers/pace-core)
 │   ├── layout/
 │   │   ├── AppLayout.tsx     # Main layout
 │   │   └── Navigation.tsx    # Navigation menu
@@ -587,9 +587,7 @@ export default App;
 
 ```tsx
 import { Routes, Route } from 'react-router-dom';
-import { LoginPage } from './components/auth/LoginPage';
-import { ProtectedRoute } from './components/auth/ProtectedRoute';
-import { AppLayout } from './components/layout/AppLayout';
+import { ProtectedRoute, PaceLoginPage, PaceAppLayout } from '@jmruthers/pace-core';
 import { DashboardPage } from './components/dashboard/DashboardPage';
 import { MealsPage } from './components/meals/MealsPage';
 import { UsersPage } from './components/users/UsersPage';
@@ -597,28 +595,14 @@ import { UsersPage } from './components/users/UsersPage';
 export function AppRoutes() {
   return (
     <Routes>
-      <Route path="/login" element={<LoginPage />} />
-      <Route path="/" element={
-        <ProtectedRoute>
-          <AppLayout>
-            <DashboardPage />
-          </AppLayout>
-        </ProtectedRoute>
-      } />
-      <Route path="/meals" element={
-        <ProtectedRoute>
-          <AppLayout>
-            <MealsPage />
-          </AppLayout>
-        </ProtectedRoute>
-      } />
-      <Route path="/users" element={
-        <ProtectedRoute>
-          <AppLayout>
-            <UsersPage />
-          </AppLayout>
-        </ProtectedRoute>
-      } />
+      <Route path="/login" element={<PaceLoginPage appName="Meal Manager" />} />
+      <Route element={<ProtectedRoute />}>
+        <Route element={<PaceAppLayout appName="Meal Manager" />}>
+          <Route path="/" element={<DashboardPage />} />
+          <Route path="/meals" element={<MealsPage />} />
+          <Route path="/users" element={<UsersPage />} />
+        </Route>
+      </Route>
     </Routes>
   );
 }

package/docs/getting-started/quick-reference.md

@@ -140,6 +140,29 @@ function MyComponent() {
 ```
 
 ### Protected Routes
+
+**✅ Use the standard ProtectedRoute component for authentication and event selection:**
+```tsx
+import { ProtectedRoute } from '@jmruthers/pace-core';
+import { Routes, Route } from 'react-router-dom';
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      <Route element={<ProtectedRoute />}>
+        <Route path="/dashboard" element={<DashboardPage />} />
+      </Route>
+      {/* Routes without event requirement */}
+      <Route element={<ProtectedRoute requireEvent={false} />}>
+        <Route path="/settings" element={<SettingsPage />} />
+      </Route>
+    </Routes>
+  );
+}
+```
+
+**For permission-based protection, use PermissionGuard:**
 ```tsx
 import { PermissionGuard } from '@jmruthers/pace-core';
 

package/docs/implementation-guides/authentication.md

@@ -134,34 +134,57 @@ export function LoginPage() {
 
 ### 6. Protected Routes
 
-```tsx
-// src/components/ProtectedRoute.tsx
-import { useUnifiedAuth, Navigate } from '@jmruthers/pace-core';
-
-function ProtectedRoute({ children }: { children: React.ReactNode }) {
-  const { user, loading } = useUnifiedAuth();
+PACE Core provides a standard `ProtectedRoute` component that handles authentication, session restoration, and event selection without creating blocking issues.
 
-  if (loading) return <div>Loading...</div>;
-  if (!user) return <Navigate to="/login" />;
+**Key Features:**
+- ✅ Handles authentication checks and redirects
+- ✅ Manages session restoration states
+- ✅ Allows rendering during event loading (prevents UI blocking)
+- ✅ Allows rendering when events exist but none selected (so event selector is visible)
+- ✅ Shows clear error states when no events are available
+- ✅ Optional event requirement
 
-  return <>{children}</>;
-}
+```tsx
+// ✅ Recommended: Use the standard ProtectedRoute from pace-core
+import { ProtectedRoute } from '@jmruthers/pace-core';
+import { Routes, Route } from 'react-router-dom';
 
-// Usage in App.tsx
 function App() {
   return (
     <Routes>
       <Route path="/login" element={<LoginPage />} />
-      <Route path="/" element={
-        <ProtectedRoute>
-          <DashboardPage />
-        </ProtectedRoute>
-      } />
+      {/* Protected routes with event requirement (default) */}
+      <Route element={<ProtectedRoute />}>
+        <Route path="/" element={<DashboardPage />} />
+        <Route path="/events" element={<EventsPage />} />
+      </Route>
+      {/* Protected routes without event requirement */}
+      <Route element={<ProtectedRoute requireEvent={false} />}>
+        <Route path="/settings" element={<SettingsPage />} />
+      </Route>
     </Routes>
   );
 }
 ```
 
+**Advanced Usage:**
+
+```tsx
+// Custom fallbacks for loading and error states
+<Route element={
+  <ProtectedRoute
+    requireEvent={true}
+    loginPath="/login"
+    loadingFallback={<CustomLoader />}
+    noEventsFallback={<CustomNoEventsMessage />}
+  />
+}>
+  <Route path="/dashboard" element={<DashboardPage />} />
+</Route>
+```
+
+**Important:** The `ProtectedRoute` component solves the common chicken-and-egg problem where apps check for `selectedEvent` before rendering, which blocks the event selector (typically in the `PaceAppLayout` header) from being visible. The component allows rendering when events exist but none is selected, enabling users to see and use the event selector dropdown.
+
 ## Configuration Options
 
 ### UnifiedAuthProvider Props

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.91",
+  "version": "0.5.93",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {

package/src/components/EventSelector/EventSelector.tsx

@@ -214,17 +214,35 @@ export function EventSelector({
     return [...events].sort((a, b) => getTime(b) - getTime(a));
   }, [events]);
 
-  // Default to the next upcoming event if none selected
+  // Default to the next upcoming event if none selected, fallback to most recent past event
   useEffect(() => {
     if (!selectedEvent && events.length > 0) {
       const today = new Date();
       const startOfToday = new Date(today.getFullYear(), today.getMonth(), today.getDate()).getTime();
+      
+      // Try to find next future event
       const next = [...events]
         .filter(e => e.event_date && new Date(e.event_date).getTime() >= startOfToday)
         .sort((a, b) => new Date(a.event_date as string).getTime() - new Date(b.event_date as string).getTime())[0];
+      
       if (next) {
         setSelectedEvent(next);
         if (onEventChange) onEventChange(next);
+      } else {
+        // Fallback to most recent past event if no future events found
+        const mostRecentPast = [...events]
+          .filter(e => {
+            if (!e.event_date) return false;
+            const eventDate = new Date(e.event_date);
+            const startOfEventDate = new Date(eventDate.getFullYear(), eventDate.getMonth(), eventDate.getDate()).getTime();
+            return startOfEventDate < startOfToday;
+          })
+          .sort((a, b) => new Date(b.event_date as string).getTime() - new Date(a.event_date as string).getTime())[0];
+        
+        if (mostRecentPast) {
+          setSelectedEvent(mostRecentPast);
+          if (onEventChange) onEventChange(mostRecentPast);
+        }
       }
     }
   }, [events, selectedEvent, setSelectedEvent, onEventChange]);

package/src/components/ProtectedRoute/ProtectedRoute.tsx

@@ -0,0 +1,224 @@
+/**
+ * @file Protected Route Component
+ * @package @jmruthers/pace-core
+ * @module Components/ProtectedRoute
+ * @since 0.6.0
+ *
+ * A route protection component that handles authentication and optional event selection
+ * without creating a chicken-and-egg problem where users cannot see the event selector.
+ *
+ * Features:
+ * - Authentication checking with redirect to login
+ * - Session restoration handling
+ * - Event loading state management
+ * - Smart event selection logic (allows rendering when events exist but none selected)
+ * - Optional event requirement (can be disabled for apps that don't need events)
+ * - Super admin bypass support
+ * - Clear error states for no events available
+ *
+ * @example
+ * Basic protected route:
+ * ```tsx
+ * import { ProtectedRoute } from '@jmruthers/pace-core';
+ * import { Routes, Route } from 'react-router-dom';
+ *
+ * function App() {
+ *   return (
+ *     <Routes>
+ *       <Route path="/login" element={<LoginPage />} />
+ *       <Route element={<ProtectedRoute />}>
+ *         <Route path="/dashboard" element={<DashboardPage />} />
+ *       </Route>
+ *     </Routes>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Protected route without event requirement:
+ * ```tsx
+ * <Route element={<ProtectedRoute requireEvent={false} />}>
+ *   <Route path="/settings" element={<SettingsPage />} />
+ * </Route>
+ * ```
+ *
+ * @example
+ * Protected route with custom no events message:
+ * ```tsx
+ * <Route element={
+ *   <ProtectedRoute
+ *     requireEvent={true}
+ *     noEventsFallback={<CustomNoEventsMessage />}
+ *   />
+ * }>
+ *   <Route path="/dashboard" element={<DashboardPage />} />
+ * </Route>
+ * ```
+ *
+ * @accessibility
+ * - Proper loading states with screen reader support
+ * - Clear error messages
+ * - Keyboard navigation support
+ *
+ * @dependencies
+ * - React Router v6 - Routing functionality
+ * - useUnifiedAuth - Authentication context
+ * - useEvents - Event context
+ * - SessionRestorationLoader - Session restoration UI
+ * - LoadingSpinner - Loading state UI
+ */
+
+import React, { useMemo } from 'react';
+import { Navigate, Outlet } from 'react-router-dom';
+import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
+import { useSessionRestoration } from '../../hooks/useSessionRestoration';
+import { useEvents } from '../../hooks/useEvents';
+import { LoadingSpinner } from '../LoadingSpinner/LoadingSpinner';
+import { SessionRestorationLoader } from '../SessionRestorationLoader';
+import { Alert, AlertDescription, AlertTitle } from '../Alert/Alert';
+
+export interface ProtectedRouteProps {
+  /**
+   * Whether an event is required for routes inside this component.
+   * When true, routes will only render if an event is selected or can be selected.
+   * When false, routes render regardless of event state.
+   * @default true
+   */
+  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.
+   */
+  noEventsFallback?: React.ReactNode;
+
+  /**
+   * Custom component to render while events are loading.
+   * If not provided, a default loading spinner is shown.
+   */
+  loadingFallback?: React.ReactNode;
+
+  /**
+   * Login redirect path when user is not authenticated.
+   * @default '/login'
+   */
+  loginPath?: string;
+}
+
+/**
+ * ProtectedRoute component that handles authentication and optional event selection.
+ *
+ * This component solves the chicken-and-egg problem where apps check for `selectedEvent`
+ * before rendering, which blocks the event selector (typically in the header) from being visible.
+ *
+ * Strategy:
+ * 1. Check authentication first - redirect to login if not authenticated
+ * 2. Allow rendering during event loading - prevents blocking UI
+ * 3. If events exist but none selected - allow rendering so selector is visible
+ * 4. If no events available - show error message
+ * 5. Individual pages should handle "no selected event" state gracefully
+ *
+ * @param props - Configuration for route protection
+ * @returns React element with route protection logic
+ */
+export function ProtectedRoute({
+  requireEvent = true,
+  allowSuperAdminBypass = false,
+  noEventsFallback,
+  loadingFallback,
+  loginPath = '/login'
+}: ProtectedRouteProps) {
+  const { isAuthenticated, isLoading } = useUnifiedAuth();
+  const { selectedEvent, events, isLoading: eventLoading } = useEvents();
+  const sessionRestoration = useSessionRestoration();
+
+  const isRestoringSession = useMemo(() => {
+    return sessionRestoration.isRestoring &&
+      !sessionRestoration.restorationComplete &&
+      !sessionRestoration.restorationError &&
+      !sessionRestoration.hasTimedOut;
+  }, [
+    sessionRestoration.isRestoring,
+    sessionRestoration.restorationComplete,
+    sessionRestoration.restorationError,
+    sessionRestoration.hasTimedOut
+  ]);
+
+  // Show session restoration loader during restoration
+  if (isRestoringSession) {
+    return <SessionRestorationLoader />;
+  }
+
+  // Show loading state while auth is being determined
+  if (isLoading && !sessionRestoration.hasTimedOut) {
+    return loadingFallback || (
+      <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', height: '100vh' }}>
+        <LoadingSpinner />
+      </div>
+    );
+  }
+
+  // Redirect to login if not authenticated
+  if (!isAuthenticated) {
+    if (sessionRestoration.hasTimedOut || sessionRestoration.restorationError) {
+      console.warn('[ProtectedRoute] Session restoration failed, redirecting to login', {
+        timedOut: sessionRestoration.hasTimedOut,
+        error: sessionRestoration.restorationError?.message
+      });
+    }
+    return <Navigate to={loginPath} replace />;
+  }
+
+  // If event is not required, allow rendering
+  if (!requireEvent) {
+    return <Outlet />;
+  }
+
+  // Note: Super admin bypass would require useRBAC hook which adds complexity
+  // Apps that need super admin access without events should set requireEvent={false}
+  // For now, we keep it simple and always require events when requireEvent=true
+
+  // Allow rendering during event loading - prevents blocking UI while events load
+  if (eventLoading) {
+    return <Outlet />;
+  }
+
+  // If no events are available, show error message
+  if (!events || events.length === 0) {
+    return noEventsFallback || (
+      <div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center', minHeight: '100vh', padding: '2rem' }}>
+        <Alert variant="destructive" className="max-w-md">
+          <AlertTitle>No Events Available</AlertTitle>
+          <AlertDescription>
+            You don't have access to any events. Please contact your administrator if you believe this is an error.
+          </AlertDescription>
+        </Alert>
+      </div>
+    );
+  }
+
+  // KEY FIX: Allow rendering when events exist but none selected
+  // This allows the event selector (typically in PaceAppLayout header) to be visible
+  // Individual pages should handle "no selected event" state gracefully
+  // Auto-selection will handle selecting the next event, or user can manually select
+  
+  // If no event selected but events exist, allow rendering
+  // The event selector will be visible and user can select, or auto-selection will kick in
+  if (!selectedEvent) {
+    // Log for debugging - this is expected behavior, not an error
+    console.debug('[ProtectedRoute] Events available but none selected - allowing render so selector is visible');
+    return <Outlet />;
+  }
+
+  // Event is selected - allow rendering
+  return <Outlet />;
+}
+