@jmruthers/pace-core 0.5.121 → 0.5.123

package/src/hooks/public/usePublicEventLogo.ts

@@ -0,0 +1,285 @@
+/**
+ * @file Public Event Logo Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * A React hook for accessing public event logo URLs without authentication.
+ * Provides logo URLs with fallback handling for public pages.
+ *
+ * Features:
+ * - No authentication required
+ * - Automatic fallback to event initials
+ * - Caching for performance
+ * - Error handling and loading states
+ * - TypeScript support
+ * - Image validation
+ *
+ * @example
+ * ```tsx
+ * import { usePublicEventLogo } from '@jmruthers/pace-core';
+ *
+ * function EventHeader() {
+ *   const { logoUrl, fallbackText, isLoading, error } = usePublicEventLogo(
+ *     eventId, 
+ *     eventName, 
+ *     organisationId
+ *   );
+ *
+ *   if (isLoading) return <div>Loading logo...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       {logoUrl ? (
+ *         <img src={logoUrl} alt={`${eventName} logo`} />
+ *       ) : (
+ *         <div className="logo-fallback">{fallbackText}</div>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - No direct accessibility concerns (hook)
+ * - Enables accessible logo display with proper alt text
+ * - Supports screen reader friendly fallbacks
+ *
+ * @security
+ * - Only returns public-safe logo URLs
+ * - Validates image existence before returning URL
+ * - No sensitive information exposed
+ * - Rate limiting applied at storage level
+ *
+ * @performance
+ * - Built-in caching with TTL
+ * - Image validation and optimization
+ * - Minimal re-renders with stable references
+ * - Lazy loading support
+ *
+ * @dependencies
+ * - React 18+ - Hooks and effects
+ * - @supabase/supabase-js - Storage integration
+ * - Event types - Type definitions
+ */
+
+import { useState, useEffect, useCallback, useMemo } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
+
+// Simple in-memory cache for public data
+const publicDataCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
+
+export interface UsePublicEventLogoReturn {
+  /** The logo URL if available, null if not found or error */
+  logoUrl: string | null;
+  /** Fallback text (event initials) if no logo is available */
+  fallbackText: string;
+  /** Whether the logo is currently loading */
+  isLoading: boolean;
+  /** Any error that occurred during loading */
+  error: Error | null;
+  /** Function to manually refetch the logo */
+  refetch: () => Promise<void>;
+}
+
+export interface UsePublicEventLogoOptions {
+  /** Cache TTL in milliseconds (default: 30 minutes) */
+  cacheTtl?: number;
+  /** Whether to enable caching (default: true) */
+  enableCache?: boolean;
+  /** Whether to validate image existence (default: true) */
+  validateImage?: boolean;
+  /** Custom fallback text generator */
+  generateFallbackText?: (eventName: string) => string;
+  /** Supabase client instance (required) */
+  supabase: SupabaseClient<Database>;
+}
+
+/**
+ * Generate fallback text from event name (first letter of each word)
+ */
+function defaultGenerateFallbackText(eventName: string): string {
+  if (!eventName) return 'EV';
+  
+  return eventName
+    .split(' ')
+    .map(word => word.charAt(0).toUpperCase())
+    .join('')
+    .substring(0, 3); // Max 3 characters
+}
+
+/**
+ * Hook for accessing public event logo URLs
+ * 
+ * This hook provides access to event logo URLs without requiring
+ * authentication. It includes fallback handling and image validation.
+ * 
+ * @param eventId - The event ID to fetch logo for
+ * @param eventName - The event name for fallback text generation
+ * @param organisationId - The organisation ID for storage path
+ * @param options - Configuration options for caching and behavior
+ * @returns Object containing logo URL, fallback text, loading state, error, and refetch function
+ */
+export function usePublicEventLogo(
+  eventId: string | undefined,
+  eventName: string | undefined,
+  organisationId: string | undefined,
+  options: UsePublicEventLogoOptions
+): UsePublicEventLogoReturn {
+  const {
+    cacheTtl = 30 * 60 * 1000, // 30 minutes
+    enableCache = true,
+    validateImage = true,
+    generateFallbackText = defaultGenerateFallbackText,
+    supabase
+  } = options;
+
+  const [logoUrl, setLogoUrl] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Generate fallback text
+  const fallbackText = useMemo(() => {
+    return eventName ? generateFallbackText(eventName) : 'EV';
+  }, [eventName, generateFallbackText]);
+
+  const fetchLogo = useCallback(async (): Promise<void> => {
+    if (!eventId || !organisationId || !supabase) {
+      setLogoUrl(null);
+      setIsLoading(false);
+      return;
+    }
+
+    // Validate UUID format for organisationId to prevent database errors
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (!uuidRegex.test(organisationId)) {
+      console.warn('[usePublicEventLogo] Invalid organisationId format (not a valid UUID):', organisationId);
+      // Don't return early - let the database handle the validation
+      // This allows for more graceful error handling
+    }
+
+    // Check cache first
+    const cacheKey = `public_logo_${eventId}_${organisationId}`;
+    if (enableCache) {
+      const cached = publicDataCache.get(cacheKey);
+      if (cached && Date.now() - cached.timestamp < cached.ttl) {
+        setLogoUrl(cached.data);
+        setIsLoading(false);
+        setError(null);
+        return;
+      }
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      // Call the public logo RPC function
+      const { data, error: rpcError } = await (supabase as any).rpc('get_public_event_logo', {
+        event_id_param: eventId,
+        organisation_id_param: organisationId
+      });
+
+      if (rpcError) {
+        throw new Error(rpcError.message || 'Failed to fetch logo');
+      }
+
+      if (!data || data.length === 0 || !data[0] || !data[0].logo_url) {
+        setLogoUrl(null);
+        return;
+      }
+
+      const logoUrl = data[0].logo_url;
+
+      // Validate image existence if requested
+      if (validateImage) {
+        try {
+          const response = await fetch(logoUrl, { method: 'HEAD' });
+          if (!response.ok) {
+            console.warn('[usePublicEventLogo] Logo URL not accessible:', logoUrl);
+            setLogoUrl(null);
+            return;
+          }
+        } catch (fetchError) {
+          console.warn('[usePublicEventLogo] Error validating logo URL:', fetchError);
+          setLogoUrl(null);
+          return;
+        }
+      }
+
+      setLogoUrl(logoUrl);
+
+      // Cache the result
+      if (enableCache) {
+        publicDataCache.set(cacheKey, {
+          data: logoUrl,
+          timestamp: Date.now(),
+          ttl: cacheTtl
+        });
+      }
+
+    } catch (err) {
+      console.error('[usePublicEventLogo] Error fetching logo:', err);
+      const error = err instanceof Error ? err : new Error('Unknown error occurred');
+      setError(error);
+      setLogoUrl(null);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [eventId, organisationId, supabase, cacheTtl, enableCache, validateImage]);
+
+  // Fetch logo when parameters change
+  useEffect(() => {
+    if (eventId && organisationId) {
+      fetchLogo();
+    } else {
+      setLogoUrl(null);
+      setIsLoading(false);
+      setError(null);
+    }
+  }, [fetchLogo, eventId, organisationId]);
+
+  const refetch = useCallback(async (): Promise<void> => {
+    if (!eventId || !organisationId) return;
+    
+    // Clear cache for this logo
+    if (enableCache) {
+      const cacheKey = `public_logo_${eventId}_${organisationId}`;
+      publicDataCache.delete(cacheKey);
+    }
+    await fetchLogo();
+  }, [fetchLogo, eventId, organisationId, enableCache]);
+
+  return {
+    logoUrl,
+    fallbackText,
+    isLoading,
+    error,
+    refetch
+  };
+}
+
+/**
+ * Clear all cached public logo data
+ * Useful for testing or when you need to force refresh all data
+ */
+export function clearPublicLogoCache(): void {
+  for (const [key] of publicDataCache) {
+    if (key.startsWith('public_logo_')) {
+      publicDataCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getPublicLogoCacheStats(): { size: number; keys: string[] } {
+  const keys = Array.from(publicDataCache.keys()).filter(key => key.startsWith('public_logo_'));
+  return {
+    size: keys.length,
+    keys
+  };
+}

package/src/hooks/public/usePublicRouteParams.ts

@@ -88,12 +88,20 @@ interface UsePublicRouteParamsOptions {
 /**
  * Validate event code format
  * Event codes should be alphanumeric with optional hyphens/underscores in the middle
+ * Supports 2-50 characters
  */
 function validateEventCodeFormat(eventCode: string): boolean {
   if (!eventCode || typeof eventCode !== 'string') return false;
   
-  // Allow alphanumeric characters, hyphens, and underscores
-  // Length between 3 and 50 characters
+  // Length check: 2-50 characters
+  if (eventCode.length < 2 || eventCode.length > 50) return false;
+  
+  // For 2-character codes: both must be alphanumeric
+  if (eventCode.length === 2) {
+    return /^[a-zA-Z0-9]{2}$/.test(eventCode);
+  }
+  
+  // For 3+ character codes: alphanumeric at start and end, hyphens/underscores allowed in middle
   // Must not start or end with hyphen/underscore
   const eventCodeRegex = /^[a-zA-Z0-9][a-zA-Z0-9_-]{1,48}[a-zA-Z0-9]$/;
   const matchesFormat = eventCodeRegex.test(eventCode);
@@ -262,8 +270,17 @@ export function generatePublicRoutePath(
 
 /**
  * Utility function to extract event code from a public route path
+ * Supports 2-50 character event codes
  */
 export function extractEventCodeFromPath(path: string): string | null {
-  const match = path.match(/^\/public\/event\/([a-zA-Z0-9_-]{3,50})(?:\/.*)?$/);
-  return match ? match[1] : null;
+  const match = path.match(/^\/public\/event\/([a-zA-Z0-9_-]{2,50})(?:\/.*)?$/);
+  if (!match) return null;
+  
+  const eventCode = match[1];
+  // Validate the extracted code using the same validation function
+  if (!validateEventCodeFormat(eventCode)) {
+    return null;
+  }
+  
+  return eventCode;
 }

package/src/hooks/useEventTheme.test.ts

@@ -139,15 +139,15 @@ describe('useEventTheme', () => {
 
       renderHook(() => useEventTheme());
 
+      // parseAndNormalizeEventColours fills all shades, so empty objects become objects with all shades
       expect(mockClearPalette).not.toHaveBeenCalled();
-      expect(mockApplyPalette).toHaveBeenCalledWith({
-        main: {
-          '50': '#f0f9ff',
-          '100': '#e0f2fe'
-        },
-        sec: {},
-        acc: {}
-      });
+      expect(mockApplyPalette).toHaveBeenCalled();
+      const callArgs = mockApplyPalette.mock.calls[0][0];
+      expect(callArgs.main['50']).toBe('#f0f9ff');
+      expect(callArgs.main['100']).toBe('#e0f2fe');
+      // sec and acc will have all shades filled (possibly undefined)
+      expect(callArgs.sec).toBeDefined();
+      expect(callArgs.acc).toBeDefined();
     });
 
     it('applies the palette with secondary colours', () => {
@@ -170,14 +170,14 @@ describe('useEventTheme', () => {
 
       renderHook(() => useEventTheme());
 
-      expect(mockApplyPalette).toHaveBeenCalledWith({
-        main: {},
-        sec: {
-          '500': '#3b82f6',
-          '600': '#2563eb'
-        },
-        acc: {}
-      });
+      // parseAndNormalizeEventColours fills all shades, so empty objects become objects with all shades
+      expect(mockApplyPalette).toHaveBeenCalled();
+      const callArgs = mockApplyPalette.mock.calls[0][0];
+      expect(callArgs.sec['500']).toBe('#3b82f6');
+      expect(callArgs.sec['600']).toBe('#2563eb');
+      // main and acc will have all shades filled (possibly undefined)
+      expect(callArgs.main).toBeDefined();
+      expect(callArgs.acc).toBeDefined();
     });
 
     it('applies the palette with accent colours', () => {
@@ -200,14 +200,14 @@ describe('useEventTheme', () => {
 
       renderHook(() => useEventTheme());
 
-      expect(mockApplyPalette).toHaveBeenCalledWith({
-        main: {},
-        sec: {},
-        acc: {
-          '500': '#ef4444',
-          '600': '#dc2626'
-        }
-      });
+      // parseAndNormalizeEventColours fills all shades, so empty objects become objects with all shades
+      expect(mockApplyPalette).toHaveBeenCalled();
+      const callArgs = mockApplyPalette.mock.calls[0][0];
+      expect(callArgs.acc['500']).toBe('#ef4444');
+      expect(callArgs.acc['600']).toBe('#dc2626');
+      // main and sec will have all shades filled (possibly undefined)
+      expect(callArgs.main).toBeDefined();
+      expect(callArgs.sec).toBeDefined();
     });
 
     it('applies the full palette with all colors', () => {
@@ -236,20 +236,19 @@ describe('useEventTheme', () => {
 
       renderHook(() => useEventTheme());
 
-      expect(mockApplyPalette).toHaveBeenCalledWith({
-        main: {
-          '500': '#0ea5e9',
-          '600': '#0284c7'
-        },
-        sec: {
-          '500': '#8b5cf6',
-          '600': '#7c3aed'
-        },
-        acc: {
-          '500': '#f59e0b',
-          '600': '#d97706'
-        }
-      });
+      // parseAndNormalizeEventColours fills all shades, so the palette will have all shades filled
+      expect(mockApplyPalette).toHaveBeenCalled();
+      const callArgs = mockApplyPalette.mock.calls[0][0];
+      expect(callArgs.main['500']).toBe('#0ea5e9');
+      expect(callArgs.main['600']).toBe('#0284c7');
+      expect(callArgs.sec['500']).toBe('#8b5cf6');
+      expect(callArgs.sec['600']).toBe('#7c3aed');
+      expect(callArgs.acc['500']).toBe('#f59e0b');
+      expect(callArgs.acc['600']).toBe('#d97706');
+      // All palettes will have all shades (50-950) filled
+      expect(callArgs.main).toBeDefined();
+      expect(callArgs.sec).toBeDefined();
+      expect(callArgs.acc).toBeDefined();
     });
   });
 
@@ -304,11 +303,12 @@ describe('useEventTheme', () => {
 
       const { rerender } = renderHook(() => useEventTheme());
 
-      expect(mockApplyPalette).toHaveBeenCalledWith({
-        main: { '500': '#0ea5e9' },
-        sec: {},
-        acc: {}
-      });
+      // parseAndNormalizeEventColours fills all shades, so empty objects become objects with all shades
+      expect(mockApplyPalette).toHaveBeenCalled();
+      const firstCallArgs = mockApplyPalette.mock.calls[0][0];
+      expect(firstCallArgs.main['500']).toBe('#0ea5e9');
+      expect(firstCallArgs.sec).toBeDefined();
+      expect(firstCallArgs.acc).toBeDefined();
 
       mockUseEvents.mockReturnValue({
         selectedEvent: {
@@ -357,5 +357,81 @@ describe('useEventTheme', () => {
       expect(mockClearPalette).toHaveBeenCalled();
     });
   });
+
+  describe('Public page mode (with event prop)', () => {
+    it('uses event prop directly when provided', () => {
+      const event = {
+        id: 'event-1',
+        event_id: 'event-1',
+        event_name: 'Public Event',
+        event_colours: {
+          main: { '500': { L: 0.5, C: 0.2, H: 0 } },
+          sec: {},
+          acc: {}
+        },
+        organisation_id: 'org1',
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString()
+      };
+
+      renderHook(() => useEventTheme(event));
+
+      // Should not call useEvents when event prop is provided
+      expect(mockUseEvents).not.toHaveBeenCalled();
+      expect(mockApplyPalette).toHaveBeenCalled();
+    });
+
+    it('clears palette when event prop is null', () => {
+      renderHook(() => useEventTheme(null));
+
+      expect(mockClearPalette).toHaveBeenCalled();
+    });
+
+    it('handles EventProvider not available gracefully when event prop provided', () => {
+      // Mock useEvents to throw (simulating no EventProvider)
+      mockUseEvents.mockImplementation(() => {
+        throw new Error('useEvents must be used within EventServiceProvider');
+      });
+
+      const event = {
+        id: 'event-1',
+        event_id: 'event-1',
+        event_name: 'Public Event',
+        event_colours: {
+          main: { '500': { L: 0.5, C: 0.2, H: 0 } },
+          sec: {},
+          acc: {}
+        },
+        organisation_id: 'org1',
+        created_at: new Date().toISOString(),
+        updated_at: new Date().toISOString()
+      };
+
+      // Should not throw and should use event prop
+      expect(() => renderHook(() => useEventTheme(event))).not.toThrow();
+      expect(mockApplyPalette).toHaveBeenCalled();
+    });
+
+    it('falls back to EventProvider when event prop is undefined', () => {
+      mockUseEvents.mockReturnValue({
+        selectedEvent: {
+          id: 'event-1',
+          event_name: 'Provider Event',
+          event_colours: {
+            main: { '500': '#0ea5e9' },
+            sec: {},
+            acc: {}
+          }
+        },
+        events: [],
+        isLoading: false,
+      } as any);
+
+      renderHook(() => useEventTheme(undefined));
+
+      expect(mockUseEvents).toHaveBeenCalled();
+      expect(mockApplyPalette).toHaveBeenCalled();
+    });
+  });
 });