@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/ProtectedRoute/useProtectedRouteState.ts

@@ -0,0 +1,128 @@
+/**
+ * @file Protected Route State Hook
+ * @package @jmruthers/pace-core
+ * @module Components/ProtectedRoute
+ * @since 0.6.0
+ *
+ * Computes the current "phase" for ProtectedRoute (session-restoring, loading, redirect, etc.)
+ * so the component can render from a single discriminated value.
+ */
+
+import { useMemo } from 'react';
+import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
+import { useSessionRestoration } from '../../hooks/useSessionRestoration';
+import { useEvents } from '../../hooks/useEvents';
+import { usePreventTabReload } from '../../hooks/usePreventTabReload';
+import { logger } from '../../utils/core/logger';
+import { useVisibilityRedirectGrace } from './useVisibilityRedirectGrace';
+
+export type ProtectedRoutePhase =
+  | 'session-restoring'
+  | 'event-loading'
+  | 'auth-loading'
+  | 'redirect'
+  | 'no-events'
+  | 'outlet';
+
+export interface UseProtectedRouteStateProps {
+  requireEvent?: boolean;
+  loginPath?: string;
+}
+
+export interface UseProtectedRouteStateResult {
+  phase: ProtectedRoutePhase;
+  loginPath: string;
+}
+
+/**
+ * Computes the current ProtectedRoute phase from auth, session, event, and visibility state.
+ */
+export function useProtectedRouteState({
+  requireEvent = false,
+  loginPath = '/login',
+}: UseProtectedRouteStateProps): UseProtectedRouteStateResult {
+  const { isAuthenticated, isLoading } = useUnifiedAuth();
+  const eventsContext = useEvents();
+  const sessionRestoration = useSessionRestoration();
+
+  usePreventTabReload({ enabled: true, gracePeriodMs: 2000 });
+
+  const visibility = useVisibilityRedirectGrace(isAuthenticated);
+
+  const eventLoading = requireEvent ? (eventsContext.isLoading ?? false) : false;
+
+  const isRestoringSession = useMemo(
+    () =>
+      sessionRestoration.isRestoring &&
+      !sessionRestoration.restorationComplete &&
+      !sessionRestoration.restorationError &&
+      !sessionRestoration.hasTimedOut,
+    [
+      sessionRestoration.isRestoring,
+      sessionRestoration.restorationComplete,
+      sessionRestoration.restorationError,
+      sessionRestoration.hasTimedOut,
+    ]
+  );
+
+  const phase = useMemo((): ProtectedRoutePhase => {
+    if (isRestoringSession) return 'session-restoring';
+    if (requireEvent && eventLoading) return 'event-loading';
+    if (isLoading && !sessionRestoration.hasTimedOut) return 'auth-loading';
+
+    if (!isAuthenticated) {
+      if (sessionRestoration.hasTimedOut || sessionRestoration.restorationError) {
+        logger.warn('ProtectedRoute', 'Session restoration failed, redirecting to login', {
+          timedOut: sessionRestoration.hasTimedOut,
+          error: sessionRestoration.restorationError?.message,
+        });
+        return 'redirect';
+      }
+
+      const restorationNotComplete =
+        !sessionRestoration.restorationComplete &&
+        !sessionRestoration.hasTimedOut &&
+        !sessionRestoration.restorationError;
+
+      if (
+        restorationNotComplete ||
+        sessionRestoration.isRestoring ||
+        isLoading
+      ) {
+        return 'auth-loading';
+      }
+
+      if (!visibility.wasAuthenticatedBefore) return 'redirect';
+      if (visibility.showLoadingForVisibility) return 'auth-loading';
+      if (
+        (typeof document !== 'undefined' && !document.hidden && visibility.wasAuthenticatedBefore && isLoading)
+      ) {
+        return 'auth-loading';
+      }
+      if (visibility.shouldRedirectToLogin) return 'redirect';
+      if (isLoading) return 'auth-loading';
+      return 'redirect';
+    }
+
+    if (!requireEvent) return 'outlet';
+    const eventsList = requireEvent ? (eventsContext.events || []) : [];
+    if (!eventsList.length) return 'no-events';
+    return 'outlet';
+  }, [
+    isRestoringSession,
+    requireEvent,
+    eventLoading,
+    isLoading,
+    sessionRestoration.hasTimedOut,
+    sessionRestoration.restorationError,
+    sessionRestoration.restorationComplete,
+    sessionRestoration.isRestoring,
+    isAuthenticated,
+    visibility.wasAuthenticatedBefore,
+    visibility.showLoadingForVisibility,
+    visibility.shouldRedirectToLogin,
+    eventsContext.events,
+  ]);
+
+  return { phase, loginPath };
+}

package/src/components/ProtectedRoute/useVisibilityRedirectGrace.ts

@@ -0,0 +1,89 @@
+/**
+ * @file Visibility Redirect Grace Hook
+ * @package @jmruthers/pace-core
+ * @module Components/ProtectedRoute
+ * @since 0.6.0
+ *
+ * Encapsulates tab visibility and redirect grace period logic for ProtectedRoute.
+ * Prevents immediate redirects to login when the tab becomes visible (e.g. after
+ * switching back) so session refresh has time to complete.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+
+const GRACE_PERIOD_MS = 2000;
+
+export interface UseVisibilityRedirectGraceResult {
+  /** True when we are in the "tab just became visible" grace period (show loading, do not redirect). */
+  showLoadingForVisibility: boolean;
+  /** True when we have confirmed the user should redirect to login after the grace period. */
+  shouldRedirectToLogin: boolean;
+  /** True if the user was previously authenticated (used to decide immediate redirect vs grace). */
+  wasAuthenticatedBefore: boolean;
+}
+
+/**
+ * Tracks visibility and auth state to avoid redirecting to login during tab visibility changes.
+ * Returns booleans for the parent to decide "show loading" vs "redirect".
+ */
+export function useVisibilityRedirectGrace(isAuthenticated: boolean): UseVisibilityRedirectGraceResult {
+  const wasAuthenticatedRef = useRef(false);
+  const [shouldRedirect, setShouldRedirect] = useState(false);
+  const [inGracePeriod, setInGracePeriod] = useState(false);
+
+  // Track auth and clear flags when authenticated
+  useEffect(() => {
+    if (isAuthenticated) {
+      wasAuthenticatedRef.current = true;
+      setShouldRedirect(false);
+      setInGracePeriod(false);
+    }
+  }, [isAuthenticated]);
+
+  // Visibility change: grace period when tab becomes visible and user appears logged out
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    let timeoutId: ReturnType<typeof setTimeout> | null = null;
+    let wasHidden = document.hidden;
+
+    const handleVisibilityChange = () => {
+      const isNowVisible = !document.hidden;
+
+      if (isNowVisible && wasHidden) {
+        if (!isAuthenticated && wasAuthenticatedRef.current) {
+          setInGracePeriod(true);
+          setShouldRedirect(false);
+          if (timeoutId) clearTimeout(timeoutId);
+          timeoutId = setTimeout(() => {
+            setInGracePeriod(false);
+            setShouldRedirect((prev) => prev);
+          }, GRACE_PERIOD_MS);
+        }
+      } else if (!isNowVisible) {
+        setInGracePeriod(false);
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+      }
+
+      wasHidden = !isNowVisible;
+    };
+
+    // Only start grace period from visibilitychange (tab became visible), not when effect runs
+    // after isAuthenticated changes (e.g. auth→unauth), so we don't show loading instead of redirect.
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+      if (timeoutId) clearTimeout(timeoutId);
+    };
+  }, [isAuthenticated]);
+
+  return {
+    showLoadingForVisibility: inGracePeriod,
+    shouldRedirectToLogin: shouldRedirect,
+    wasAuthenticatedBefore: wasAuthenticatedRef.current,
+  };
+}

package/src/components/PublicLayout/PublicLayout.test.tsx

@@ -1,7 +1,7 @@
 /**
  * @file Integration Tests for PublicLayout Components
  * @package @jmruthers/pace-core
- * @module Components/PublicLayout/__tests__
+ * @module Components/PublicLayout
  * @since 1.0.0
  * 
  * Integration tests for PublicLayout components focusing on observable behavior,
@@ -12,13 +12,10 @@ import React from 'react';
 import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-
-// Following testing standards: use timeout parameter to prevent hanging
-const TEST_TIMEOUT = 10000; // 10 seconds per test
-import { 
-  PublicPageLayout, 
-  PublicPageHeader, 
-  PublicPageFooter 
+import {
+  PublicPageLayout,
+  PublicPageHeader,
+  PublicPageFooter
 } from './PublicPageLayout';
 import { PublicPageProvider } from './PublicPageProvider';
 import { usePublicPageContext, useIsPublicPage } from './usePublicPageContext';
@@ -26,6 +23,10 @@ import type { PublicPageContextType } from './PublicPageContext';
 import { useEventTheme } from '../../hooks/useEventTheme';
 import type { Event } from '../../types/event';
 import { assertOrganisationId } from '../../types/core';
+import { logger } from '../../utils/core/logger';
+
+// Following testing standards: use timeout parameter to prevent hanging
+const TEST_TIMEOUT = 10000; // 10 seconds per test
 
 // === SHARED MOCKS ===
 
@@ -70,18 +71,22 @@ vi.mock('../../hooks/useAppConfig', () => ({
 }));
 
 vi.mock('../FileDisplay/FileDisplay', () => ({
-  FileDisplay: vi.fn(({ table_name, record_id, organisation_id, category, className, _generateFallbackText }) => (
-    <div 
-      data-testid="event-logo" 
-      data-table-name={table_name}
-      data-record-id={record_id}
-      data-organisation-id={organisation_id}
-      data-category={category}
-      className={className}
-    >
-      Event Logo
-    </div>
-  ))
+  FileDisplay: vi.fn(({ table_name, record_id, organisation_id, category, className, generateFallbackText }) => {
+    const fallbackText = typeof generateFallbackText === 'function' ? generateFallbackText('') : '';
+    return (
+      <div
+        data-testid="event-logo"
+        data-table-name={table_name}
+        data-record-id={record_id}
+        data-organisation-id={organisation_id}
+        data-category={category}
+        data-fallback={fallbackText}
+        className={className}
+      >
+        {fallbackText || 'Event Logo'}
+      </div>
+    );
+  })
 }));
 
 vi.mock('../../utils/core/cn', () => ({
@@ -252,17 +257,13 @@ describe('[component] PublicPageLayout', () => {
         </PublicPageLayout>
       );
 
-      // The loading state renders a container with grid and place-items-center classes
-      // There may be multiple "Loading..." texts (from LoadingSpinner mock and actual text)
-      // So we query by the container element using getAllByText and find the one in the container
-      const loadingTexts = screen.getAllByText('Loading...');
-      // Find the container that has the grid classes (changed from p to div for semantic HTML)
-      const loadingContainer = loadingTexts.find(text => {
-        const container = text.closest('div');
-        return container && container.classList.contains('grid');
-      })?.closest('div');
+      // Loading state uses <main> with role="status" and layout classes
+      const loadingContainer = screen.getByRole('status');
       expect(loadingContainer).toBeInTheDocument();
-      expect(loadingContainer).toHaveClass('grid', 'place-items-center', 'text-center', 'size-full');
+      expect(loadingContainer).toHaveClass('grid', 'place-items-center', 'text-center', 'size-full', 'gap-2');
+      expect(loadingContainer).toHaveAttribute('role', 'status');
+      expect(loadingContainer).toHaveAttribute('aria-busy', 'true');
+      expect(loadingContainer.querySelector('.sr-only')).toHaveTextContent('Loading');
     });
   });
 
@@ -281,6 +282,20 @@ describe('[component] PublicPageLayout', () => {
       expect(screen.getByText('Try Again')).toBeInTheDocument();
     });
 
+    it('error state has one h1 and Try Again is a button (accessibility)', () => {
+      const error = new Error('Event not found');
+      render(
+        <PublicPageLayout eventCode="EVENT123" error={error}>
+          <div>Test Content</div>
+        </PublicPageLayout>
+      );
+
+      const headings = screen.getAllByRole('heading', { level: 1 });
+      expect(headings).toHaveLength(1);
+      expect(headings[0]).toHaveTextContent('Event Not Found');
+      expect(screen.getByRole('button', { name: /try again/i })).toBeInTheDocument();
+    });
+
     it('calls refetch when Try Again button is clicked', async () => {
       const user = userEvent.setup();
       const mockRefetch = vi.fn().mockResolvedValue(undefined);
@@ -370,6 +385,19 @@ describe('[component] PublicPageLayout', () => {
       expect(screen.getByText('Try Again')).toBeInTheDocument();
     });
 
+    it('missing event state has one h1 and Try Again is a button (accessibility)', () => {
+      render(
+        <PublicPageLayout eventCode="EVENT123">
+          <div>Test Content</div>
+        </PublicPageLayout>
+      );
+
+      const headings = screen.getAllByRole('heading', { level: 1 });
+      expect(headings).toHaveLength(1);
+      expect(headings[0]).toHaveTextContent('Event Not Available');
+      expect(screen.getByRole('button', { name: /try again/i })).toBeInTheDocument();
+    });
+
     it('calls refetch when Try Again is clicked in missing event state', async () => {
       const user = userEvent.setup();
       const mockRefetch = vi.fn().mockResolvedValue(undefined);
@@ -485,6 +513,7 @@ describe('[component] PublicPageLayout', () => {
       );
 
       expect(screen.getByTestId('custom-footer')).toBeInTheDocument();
+      expect(screen.queryByRole('contentinfo')).not.toBeInTheDocument();
     });
 
     it('renders main content with correct classes', () => {
@@ -496,7 +525,7 @@ describe('[component] PublicPageLayout', () => {
 
       const main = container.querySelector('main');
       expect(main).toBeInTheDocument();
-      expect(main).toHaveClass('px-4', 'w-[min(var(--app-width),100%)]', 'mx-auto', 'py-8');
+      expect(main).toHaveClass('px-4', 'w-full', 'max-w-app-content-max', 'mx-auto', 'py-8');
     });
 
     it('wraps content in error boundary', () => {
@@ -510,6 +539,82 @@ describe('[component] PublicPageLayout', () => {
     });
   });
 
+  describe('Print orientation', () => {
+    it('applies print-page-landscape class in error state when printPageOrientation is landscape', () => {
+      const error = new Error('Event not found');
+      const { container } = render(
+        <PublicPageLayout eventCode="EVENT123" error={error} printPageOrientation="landscape">
+          <div>Test Content</div>
+        </PublicPageLayout>
+      );
+
+      const main = container.querySelector('main');
+      expect(main).toBeInTheDocument();
+      expect(main).toHaveClass('print-page-landscape');
+    });
+
+    it('applies print-page-portrait class in error state when printPageOrientation is portrait', () => {
+      const error = new Error('Event not found');
+      const { container } = render(
+        <PublicPageLayout eventCode="EVENT123" error={error} printPageOrientation="portrait">
+          <div>Test Content</div>
+        </PublicPageLayout>
+      );
+
+      const main = container.querySelector('main');
+      expect(main).toBeInTheDocument();
+      expect(main).toHaveClass('print-page-portrait');
+    });
+
+    it('applies print-page-landscape class in missing-event state when printPageOrientation is landscape', () => {
+      const { container } = render(
+        <PublicPageLayout eventCode="EVENT123" printPageOrientation="landscape">
+          <div>Test Content</div>
+        </PublicPageLayout>
+      );
+
+      const main = container.querySelector('main');
+      expect(main).toBeInTheDocument();
+      expect(main).toHaveClass('print-page-landscape');
+    });
+
+    it('applies print-page-portrait class in missing-event state when printPageOrientation is portrait', () => {
+      const { container } = render(
+        <PublicPageLayout eventCode="EVENT123" printPageOrientation="portrait">
+          <div>Test Content</div>
+        </PublicPageLayout>
+      );
+
+      const main = container.querySelector('main');
+      expect(main).toBeInTheDocument();
+      expect(main).toHaveClass('print-page-portrait');
+    });
+
+    it('applies print-page-landscape class to main content when printPageOrientation is landscape', () => {
+      const { container } = render(
+        <PublicPageLayout eventCode="EVENT123" event={mockEvent} printPageOrientation="landscape">
+          <div data-testid="content">Test Content</div>
+        </PublicPageLayout>
+      );
+
+      const mains = container.querySelectorAll('main');
+      expect(mains.length).toBe(1);
+      expect(mains[0]).toHaveClass('print-page-landscape');
+    });
+
+    it('applies print-page-portrait class to main content when printPageOrientation is portrait', () => {
+      const { container } = render(
+        <PublicPageLayout eventCode="EVENT123" event={mockEvent} printPageOrientation="portrait">
+          <div data-testid="content">Test Content</div>
+        </PublicPageLayout>
+      );
+
+      const mains = container.querySelectorAll('main');
+      expect(mains.length).toBe(1);
+      expect(mains[0]).toHaveClass('print-page-portrait');
+    });
+  });
+
   describe('Edge Cases', () => {
     it('handles empty eventCode', () => {
       render(
@@ -532,10 +637,10 @@ describe('[component] PublicPageLayout', () => {
       expect(screen.queryByText('Test Venue')).not.toBeInTheDocument();
     });
 
-    it('handles deprecated className prop gracefully', () => {
+    it('handles unknown props gracefully', () => {
       const { container } = render(
-        <PublicPageLayout 
-          eventCode="EVENT123" 
+        <PublicPageLayout
+          eventCode="EVENT123"
           event={mockEvent}
           className="deprecated-class"
         >
@@ -543,7 +648,7 @@ describe('[component] PublicPageLayout', () => {
         </PublicPageLayout>
       );
 
-      // Component should still render even with deprecated prop
+      // Component ignores unknown props and still renders
       expect(container).toBeInTheDocument();
     }, TEST_TIMEOUT);
 
@@ -760,6 +865,27 @@ describe('[component] PublicPageHeader', () => {
       expect(screen.getByTestId('event-logo')).toHaveAttribute('data-record-id', 'event-123');
     });
 
+    it('renders event logo fallback text from event name abbreviation (generateFallbackText)', () => {
+      render(
+        <PublicPageHeader event={mockEvent} eventCode="EVENT123" />
+      );
+
+      const eventLogo = screen.getByTestId('event-logo');
+      expect(eventLogo).toHaveAttribute('data-fallback', 'TE');
+      expect(eventLogo).toHaveTextContent('TE');
+    });
+
+    it('renders event logo fallback EV when event has no event_name', () => {
+      const eventWithNoName = { ...mockEvent, event_name: '' };
+      render(
+        <PublicPageHeader event={eventWithNoName} eventCode="EVENT123" />
+      );
+
+      const eventLogo = screen.getByTestId('event-logo');
+      expect(eventLogo).toHaveAttribute('data-fallback', 'EV');
+      expect(eventLogo).toHaveTextContent('EV');
+    });
+
     it('hides event logo when showEventLogo is false', () => {
       render(
         <PublicPageHeader 
@@ -814,6 +940,20 @@ describe('[component] PublicPageHeader', () => {
       expect(screen.getByText('Test Venue')).toBeInTheDocument();
     });
 
+    it('uses correct heading order (h1 then h4 when venue present) for accessibility', () => {
+      render(
+        <PublicPageHeader event={mockEvent} eventCode="EVENT123" />
+      );
+
+      const header = screen.getByRole('banner');
+      expect(header.tagName).toBe('HEADER');
+      const h1 = header.querySelector('h1');
+      const h4 = header.querySelector('h4');
+      expect(h1).toBeInTheDocument();
+      expect(h4).toBeInTheDocument();
+      expect((h1!.compareDocumentPosition(h4!) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0).toBe(true);
+    });
+
     it('does not display venue when event has no venue', () => {
       render(
         <PublicPageHeader event={mockEventWithoutVenue} eventCode="EVENT123" />
@@ -1167,6 +1307,41 @@ describe('[component] PublicPageProvider', () => {
       expect(screen.getByTestId('url')).toHaveTextContent('https://test.supabase.co');
       expect(screen.getByTestId('key')).toHaveTextContent('test-key');
     });
+
+    it('uses process.env when import.meta.env is undefined (getEnvVar process.env branch)', () => {
+      mockCreateClient.mockClear();
+      Object.defineProperty(import.meta, 'env', {
+        value: undefined,
+        writable: true,
+        configurable: true
+      });
+      const originalProcessEnv = process.env;
+      process.env = {
+        ...originalProcessEnv,
+        VITE_SUPABASE_URL: 'https://process-env.supabase.co',
+        VITE_SUPABASE_PUBLISHABLE_KEY: 'process-env-key'
+      };
+
+      const TestComponent = () => {
+        const context = usePublicPageContext();
+        return (
+          <div>
+            <span data-testid="url">{context.environment.supabaseUrl || 'no-url'}</span>
+            <span data-testid="key">{context.environment.supabaseKey || 'no-key'}</span>
+          </div>
+        );
+      };
+
+      render(
+        <PublicPageProvider>
+          <TestComponent />
+        </PublicPageProvider>
+      );
+
+      expect(screen.getByTestId('url')).toHaveTextContent('https://process-env.supabase.co');
+      expect(screen.getByTestId('key')).toHaveTextContent('process-env-key');
+      expect(mockCreateClient).toHaveBeenCalledWith('https://process-env.supabase.co', 'process-env-key');
+    });
   });
 
   describe('Supabase Client Creation', () => {
@@ -1226,6 +1401,10 @@ describe('[component] PublicPageProvider', () => {
       );
 
       expect(screen.getByText('no-client')).toBeInTheDocument();
+      expect(logger.warn).toHaveBeenCalledWith(
+        'PublicPageProvider',
+        expect.stringContaining('Missing Supabase')
+      );
     });
 
     it('supports NEXT_PUBLIC_ prefixed environment variables', () => {
@@ -1285,7 +1464,9 @@ describe('[component] PublicPageProvider', () => {
 
       render(<TestComponent />);
 
-      expect(screen.getByText('usePublicPageContext must be used within a PublicPageProvider')).toBeInTheDocument();
+      const message = screen.getByText('usePublicPageContext must be used within a PublicPageProvider');
+      expect(message).toBeInTheDocument();
+      expect(message.textContent).toContain('PublicPageProvider');
 
       console.error = consoleError;
     });