@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/implementation-guides/public-pages.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Public Pages Implementation Guide
@@ -135,7 +135,7 @@ export function PublicRecipePage() {
   // Step 4: Handle error
   if (error || !event) {
     return (
-      <div className="min-h-screen bg-white flex items-center justify-center">
+      <div className="min-h-screen bg-background flex items-center justify-center">
         <div className="text-center">
           <h1 className="text-2xl font-bold text-sec-900 mb-4">
             Recipe Grid Report Not Found
@@ -160,7 +160,7 @@ export function PublicRecipePage() {
       
       <main className="max-w-6xl mx-auto px-4 py-8">
         {/* Your public page content here */}
-        <div className="bg-white rounded-lg shadow p-6">
+        <div className="bg-background rounded-lg shadow p-6">
           <h2 className="text-xl font-semibold mb-4">Recipe Grid Report</h2>
           <p>Event: {event.event_name}</p>
           <p>Code: {event.event_code}</p>
@@ -243,11 +243,19 @@ import { PublicPageLayout } from '@jmruthers/pace-core';
 
 **Props:**
 - `eventCode` (required) - The event code from the URL
-- `event` (optional) - Event data object
-- `showFooter` (optional) - Show/hide footer
-- `className` (optional) - Additional CSS classes
+- `children` (required) - Child components to render
+- `event` (optional) - Event data object (if not provided, will be fetched by parent component)
+- `isLoading` (optional) - Loading state (if true, shows loading spinner)
+- `error` (optional) - Error state (if provided, shows error message)
+- `refetch` (optional) - Function to retry loading event data
+- `showFooter` (optional) - Show/hide footer (default: true)
+- `className` (optional, deprecated) - Custom CSS classes (deprecated, no longer used as wrapper div was removed)
 - `errorFallback` (optional) - Custom error component
 - `loadingFallback` (optional) - Custom loading component
+- `customHeader` (optional) - Custom header component
+- `customFooter` (optional) - Custom footer component
+- `showValidationErrors` (optional) - Whether to show event validation errors (default: true)
+- `loadingMessage` (optional) - Custom loading message
 
 ### PublicPageHeader
 
@@ -267,12 +275,15 @@ import { PublicPageHeader } from '@jmruthers/pace-core';
 ```
 
 **Props:**
-- `event` (required) - Event data object
 - `eventCode` (required) - Event code from URL
+- `event` (optional) - Event data object
 - `title` (optional) - Page title
 - `description` (optional) - Page description
-- `showEventLogo` (optional) - Show event logo
-- `showAppLogo` (optional) - Show app logo
+- `showEventLogo` (optional) - Show event logo (default: true)
+- `showAppLogo` (optional) - Show app logo (default: true)
+- `className` (optional) - Custom CSS classes for the header
+- `children` (optional) - Custom content to display in the header
+- `customEventLogo` (optional) - Custom event logo component
 
 ### PublicPageFooter
 
@@ -420,7 +431,7 @@ function PublicInfoPage() {
   const { pageId } = usePublicRouteParams({ fetchEventData: false });
   
   return (
-    <div className="min-h-screen bg-white">
+    <div className="min-h-screen bg-background">
       <div className="max-w-4xl mx-auto px-4 py-8">
         <h1 className="text-3xl font-bold mb-6">Public Information</h1>
         <p>Page ID: {pageId}</p>
@@ -709,7 +720,7 @@ export function PublicRecipePage() {
   
   if (error || !event) {
     return (
-      <div className="min-h-screen bg-white flex items-center justify-center">
+      <div className="min-h-screen bg-background flex items-center justify-center">
         <div className="text-center">
           <h1 className="text-2xl font-bold text-sec-900 mb-4">
             Recipe Grid Report Not Found
@@ -732,7 +743,7 @@ export function PublicRecipePage() {
       />
       
       <main className="max-w-6xl mx-auto px-4 py-8">
-        <div className="bg-white rounded-lg shadow p-6">
+        <div className="bg-background rounded-lg shadow p-6">
           <h2 className="text-xl font-semibold mb-4">Recipe Grid Report</h2>
           <p>Event: {event.event_name}</p>
           <p>Code: {event.event_code}</p>
@@ -755,4 +766,539 @@ export function PublicRecipePage() {
 
 ---
 
+## 🚀 **Advanced Topics**
+
+This section covers advanced topics for public pages, including event logos, caching strategies, SEO optimization, and performance tuning.
+
+### EventLogo Component
+
+A component for displaying event logos with automatic loading and caching.
+
+#### Props
+
+```typescript
+interface EventLogoProps {
+  eventId: string;
+  size?: 'small' | 'medium' | 'large' | 'xlarge';
+  variant?: 'default' | 'square' | 'wide';
+  className?: string;
+  fallback?: React.ReactNode;
+  showLoading?: boolean;
+}
+```
+
+#### Usage Examples
+
+**Basic Logo:**
+```tsx
+<EventLogo eventId={eventId} size="medium" />
+```
+
+**Custom Styling:**
+```tsx
+<EventLogo 
+  eventId={eventId} 
+  size="large"
+  variant="square"
+  className="rounded-lg shadow-lg"
+/>
+```
+
+**With Fallback:**
+```tsx
+<EventLogo 
+  eventId={eventId} 
+  size="medium"
+  fallback={
+    <div className="bg-sec-200 text-sec-500 p-4 rounded">
+      No Logo Available
+    </div>
+  }
+/>
+```
+
+### usePublicEventLogo Hook
+
+Hook for loading and caching event logos.
+
+#### Interface
+
+```typescript
+interface UsePublicEventLogoReturn {
+  logoUrl: string | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+  clearCache: () => void;
+}
+```
+
+#### Usage Examples
+
+> **Storage path formats**
+>
+> When configuring `event_logo` for an event, Pace supports multiple formats:
+>
+> - A fully qualified `https://` URL will be used directly.
+> - A storage path like `public-files/org-123/logo.png` automatically resolves against the standard buckets configured via `pace-core`.
+> - If your deployment stores logos in a different bucket, prefix the path with the bucket name using `custombucket/org-123/logo.png` (alphanumeric names) or `custom-bucket::org-123/logo.png` (bucket names containing hyphens).
+>
+> The double colon form helps when your folders start with numbers (for example `2024/`), ensuring they are not mistaken for bucket names.
+
+**Basic Logo Loading:**
+```tsx
+import { usePublicEventLogo } from '@jmruthers/pace-core';
+
+function EventLogoDisplay({ eventId }: { eventId: string }) {
+  const { logoUrl, loading, error } = usePublicEventLogo(eventId, 'large');
+
+  if (loading) {
+    return <div className="animate-pulse bg-sec-200 w-32 h-32 rounded"></div>;
+  }
+
+  if (error) {
+    return <div className="text-sec-500">Logo unavailable</div>;
+  }
+
+  if (!logoUrl) {
+    return <div className="bg-sec-200 text-sec-500 p-4 rounded">No logo</div>;
+  }
+
+  return (
+    <img 
+      src={logoUrl} 
+      alt="Event logo" 
+      className="w-32 h-32 object-contain"
+    />
+  );
+}
+```
+
+**With Caching Control:**
+```tsx
+import { usePublicEventLogo } from '@jmruthers/pace-core';
+
+function LogoWithCacheControl({ eventId }: { eventId: string }) {
+  const { 
+    logoUrl, 
+    loading, 
+    error, 
+    refetch, 
+    clearCache 
+  } = usePublicEventLogo(eventId, 'medium');
+
+  const handleRefresh = async () => {
+    await refetch();
+  };
+
+  const handleClearCache = () => {
+    clearCache();
+  };
+
+  return (
+    <div className="space-y-4">
+      {loading && <div>Loading logo...</div>}
+      {error && <div>Error: {error.message}</div>}
+      {logoUrl && (
+        <img 
+          src={logoUrl} 
+          alt="Event logo" 
+          className="w-16 h-16 object-contain"
+        />
+      )}
+      
+      <div className="space-x-2">
+        <Button onClick={handleRefresh} size="sm">
+          Refresh Logo
+        </Button>
+        <Button onClick={handleClearCache} size="sm" variant="outline">
+          Clear Cache
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Caching Strategies
+
+#### Client-Side Caching
+
+```tsx
+import { usePublicEvent, clearPublicEventCache } from '@jmruthers/pace-core';
+
+function CachedEventPage({ eventId }: { eventId: string }) {
+  const { event, loading } = usePublicEvent(eventId);
+
+  // Cache management
+  const handleClearCache = () => {
+    clearPublicEventCache();
+    console.log('Event cache cleared');
+  };
+
+  return (
+    <div>
+      <h1>{event?.name}</h1>
+      
+      <div className="space-x-2">
+        <Button onClick={handleClearCache}>
+          Clear Cache
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+#### Cache Statistics
+
+```tsx
+import { getPublicEventCacheStats, getPublicLogoCacheStats } from '@jmruthers/pace-core';
+
+function CacheStats() {
+  const eventStats = getPublicEventCacheStats();
+  const logoStats = getPublicLogoCacheStats();
+
+  return (
+    <div className="bg-sec-50 p-4 rounded">
+      <h3>Cache Statistics</h3>
+      <div className="grid grid-cols-2 gap-4">
+        <div>
+          <h4>Event Cache</h4>
+          <p>Entries: {eventStats.entryCount}</p>
+          <p>Hit Rate: {eventStats.hitRate}%</p>
+          <p>Memory Usage: {eventStats.memoryUsage} bytes</p>
+        </div>
+        <div>
+          <h4>Logo Cache</h4>
+          <p>Entries: {logoStats.entryCount}</p>
+          <p>Hit Rate: {logoStats.hitRate}%</p>
+          <p>Memory Usage: {logoStats.memoryUsage} bytes</p>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### SEO Optimization
+
+#### Meta Tags and Structured Data
+
+```tsx
+import { usePublicEvent } from '@jmruthers/pace-core';
+
+function SEOEventPage({ eventId }: { eventId: string }) {
+  const { event } = usePublicEvent(eventId);
+
+  // Generate structured data for search engines
+  const structuredData = event ? {
+    "@context": "https://schema.org",
+    "@type": "Event",
+    "name": event.name,
+    "description": event.description,
+    "startDate": event.start_date,
+    "endDate": event.end_date,
+    "location": {
+      "@type": "Place",
+      "name": event.location
+    },
+    "url": event.public_url,
+    "image": event.logo_url
+  } : null;
+
+  return (
+    <>
+      {/* Meta tags */}
+      <head>
+        <title>{event?.name || 'Event'}</title>
+        <meta name="description" content={event?.description} />
+        <meta property="og:title" content={event?.name} />
+        <meta property="og:description" content={event?.description} />
+        <meta property="og:image" content={event?.logo_url} />
+        <meta property="og:type" content="event" />
+        <meta name="twitter:card" content="summary_large_image" />
+        
+        {/* Structured data */}
+        {structuredData && (
+          <script
+            type="application/ld+json"
+            dangerouslySetInnerHTML={{
+              __html: JSON.stringify(structuredData)
+            }}
+          />
+        )}
+      </head>
+
+      <main>
+        <h1>{event?.name}</h1>
+        <p>{event?.description}</p>
+        {/* Event content */}
+      </main>
+    </>
+  );
+}
+```
+
+### Performance Optimization
+
+#### Lazy Loading
+
+```tsx
+import { lazy, Suspense } from 'react';
+import { usePublicEvent } from '@jmruthers/pace-core';
+
+// Lazy load heavy components
+const EventSchedule = lazy(() => import('./EventSchedule'));
+const EventSpeakers = lazy(() => import('./EventSpeakers'));
+
+function OptimizedEventPage({ eventId }: { eventId: string }) {
+  const { event, loading } = usePublicEvent(eventId);
+
+  if (loading) return <div>Loading...</div>;
+  if (!event) return <div>Event not found</div>;
+
+  return (
+    <PublicPageLayout>
+      <header>
+        <h1>{event.name}</h1>
+        <p>{event.description}</p>
+      </header>
+      
+      <main>
+        {/* Critical content loads immediately */}
+        <section>
+          <h2>Event Details</h2>
+          <p>Date: {new Date(event.start_date).toLocaleDateString()}</p>
+          <p>Location: {event.location}</p>
+        </section>
+        
+        {/* Non-critical content loads lazily */}
+        <Suspense fallback={<div>Loading schedule...</div>}>
+          <EventSchedule eventId={eventId} />
+        </Suspense>
+        
+        <Suspense fallback={<div>Loading speakers...</div>}>
+          <EventSpeakers eventId={eventId} />
+        </Suspense>
+      </main>
+    </PublicPageLayout>
+  );
+}
+```
+
+#### Image Optimization
+
+```tsx
+import { EventLogo } from '@jmruthers/pace-core';
+
+function OptimizedEventLogo({ eventId }: { eventId: string }) {
+  return (
+    <EventLogo 
+      eventId={eventId}
+      size="large"
+      className="w-full h-auto max-w-md mx-auto"
+      // The component handles:
+      // - WebP format when supported
+      // - Responsive sizing
+      // - Lazy loading
+      // - Error fallbacks
+    />
+  );
+}
+```
+
+### Advanced Error Handling
+
+#### Graceful Degradation
+
+```tsx
+import { usePublicEvent, usePublicEventLogo } from '@jmruthers/pace-core';
+
+function RobustEventPage({ eventId }: { eventId: string }) {
+  const { 
+    event, 
+    loading: eventLoading, 
+    error: eventError 
+  } = usePublicEvent(eventId);
+  
+  const { 
+    logoUrl, 
+    loading: logoLoading, 
+    error: logoError 
+  } = usePublicEventLogo(eventId, 'large');
+
+  // Graceful degradation for missing data
+  const displayName = event?.name || 'Event';
+  const displayDescription = event?.description || 'Event details coming soon';
+  const displayLogo = logoUrl || '/default-event-logo.png';
+
+  if (eventLoading) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <div className="text-center">
+          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-main-600 mx-auto"></div>
+          <p className="mt-4 text-sec-600">Loading event...</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (eventError) {
+    return (
+      <div className="min-h-screen flex items-center justify-center">
+        <div className="text-center">
+          <h1 className="text-2xl font-bold text-sec-800 mb-2">
+            Unable to load event
+          </h1>
+          <p className="text-sec-600 mb-4">
+            {eventError.message}
+          </p>
+          <Button onClick={() => window.location.reload()}>
+            Try Again
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <PublicPageLayout>
+      <header className="bg-main-50 py-8">
+        <div className="container mx-auto px-4 text-center">
+          {logoLoading ? (
+            <div className="animate-pulse bg-sec-200 h-32 w-32 mx-auto rounded"></div>
+          ) : logoError ? (
+            <div className="bg-sec-200 text-sec-500 h-32 w-32 mx-auto rounded flex items-center justify-center">
+              No Logo
+            </div>
+          ) : (
+            <img 
+              src={displayLogo} 
+              alt={`${displayName} logo`}
+              className="h-32 w-32 mx-auto object-contain"
+            />
+          )}
+          
+          <h1 className="text-3xl font-bold text-main-900 mt-4">
+            {displayName}
+          </h1>
+          <p className="text-main-700 mt-2">
+            {displayDescription}
+          </p>
+        </div>
+      </header>
+      
+      <main className="container mx-auto px-4 py-8">
+        {/* Event content */}
+      </main>
+    </PublicPageLayout>
+  );
+}
+```
+
+### Advanced Troubleshooting
+
+#### Common Issues
+
+**Issue: Event not loading**
+- Check that event exists and is published
+- Verify `is_public` flag is set to true
+- Check RLS policies allow public access
+
+**Issue: Logo not displaying**
+- Verify logo file exists in storage bucket
+- Check storage bucket policies
+- Ensure logo URL is correct
+
+**Issue: Cache not working**
+- Check browser storage permissions
+- Verify cache configuration
+- Clear browser cache and test
+
+#### Debug Mode
+
+```tsx
+import { usePublicEvent, usePublicEventLogo } from '@jmruthers/pace-core';
+
+function DebugPublicPage({ eventId }: { eventId: string }) {
+  const { event, loading, error } = usePublicEvent(eventId);
+  const { logoUrl, loading: logoLoading, error: logoError } = usePublicEventLogo(eventId, 'large');
+
+  console.log('Event data:', { event, loading, error });
+  console.log('Logo data:', { logoUrl, logoLoading, logoError });
+
+  return (
+    <div>
+      <h1>Debug Information</h1>
+      <pre>{JSON.stringify({ event, loading, error }, null, 2)}</pre>
+      <pre>{JSON.stringify({ logoUrl, logoLoading, logoError }, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+## ♿ Accessibility
+
+Public pages components are designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All components meet accessibility standards
+- **Semantic HTML** - Proper use of `<header>`, `<main>`, `<footer>` elements
+- **Screen reader friendly** - All interactive elements have proper ARIA labels
+- **Keyboard navigation** - Full keyboard support for all interactive elements
+- **High contrast support** - Colors meet WCAG contrast requirements
+- **Clear content hierarchy** - Proper heading structure and content organization
+
+### Accessibility Best Practices
+
+1. **Always provide alt text** for event logos and images
+2. **Use semantic HTML** - Prefer `<h1>`, `<h2>`, `<nav>`, etc. over generic `<div>` elements
+3. **Ensure keyboard navigation** - All interactive elements should be keyboard accessible
+4. **Test with screen readers** - Verify content is properly announced
+5. **Maintain focus management** - Ensure focus is properly managed during loading states
+
+## ⚠️ Edge Cases
+
+### Missing Event Data
+
+When event data is not available:
+- `PublicPageLayout` automatically shows an error message
+- Error message includes the event code for debugging
+- Provides a "Try Again" button to retry loading
+- Can be customized with `errorFallback` prop
+
+### Invalid Event Codes
+
+When an invalid event code is provided:
+- `usePublicRouteParams` validates event code format
+- Invalid codes trigger error states
+- Error messages are user-friendly
+- Validation errors can be hidden with `showValidationErrors={false}`
+
+### Network Failures
+
+When network requests fail:
+- All hooks provide error states
+- Error objects include descriptive messages
+- Retry mechanisms are available via `refetch` functions
+- Graceful degradation with fallback UI
+
+### Missing Logos
+
+When event logos are not available:
+- Components show fallback UI with event initials
+- No broken image icons
+- Consistent styling regardless of logo availability
+- Custom fallback can be provided via `customEventLogo` prop
+
+### Loading States
+
+During data loading:
+- Loading spinners are shown automatically
+- Custom loading messages can be provided
+- Loading fallback components can be customized
+- Prevents layout shifts during loading
+
+---
+
 **Remember**: Public pages are completely separate from your main app. Keep them isolated and they'll work perfectly!