@jmruthers/pace-core 0.2.7 → 0.4.1

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

@@ -1,752 +0,0 @@
-# Public Pages Implementation Guide
-
-> **🌐 Public Pages** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
-
-Complete guide for implementing public pages that work independently of your main application's authentication context.
-
-## 🚨 **CRITICAL: Architecture Requirements**
-
-**Public pages MUST be completely separate from your main app's authentication context.** This is the #1 reason consuming apps struggle with this feature.
-
-### ❌ **WRONG - This Will Break**
-```tsx
-// DON'T DO THIS - Public pages inside auth context
-<UnifiedAuthProvider>
-  <OrganisationProvider>
-    <EventProvider>
-      <Routes>
-        <Route path="/events/:eventCode" element={<PublicPage />} /> {/* ❌ BREAKS */}
-        <Route path="/dashboard" element={<Dashboard />} />
-      </Routes>
-    </EventProvider>
-  </OrganisationProvider>
-</UnifiedAuthProvider>
-```
-
-### ✅ **CORRECT - Separate Applications**
-```tsx
-// DO THIS - Public pages completely separate
-<BrowserRouter>
-  <Routes>
-    {/* Public routes - NO authentication context */}
-    <Route path="/events/*" element={<PublicPageApp />} />
-    <Route path="/public/*" element={<PublicPageApp />} />
-    
-    {/* Authenticated routes - WITH authentication context */}
-    <Route path="/*" element={<AuthenticatedApp />} />
-  </Routes>
-</BrowserRouter>
-```
-
-## 🏗️ **Required Architecture**
-
-### 1. **Two Separate Applications**
-
-You need to create **two completely separate applications**:
-
-1. **`AuthenticatedApp`** - Your main app with authentication
-2. **`PublicPageApp`** - Public pages with no authentication
-
-### 2. **Root Router Decision**
-
-Your root component decides which app to render based on the route:
-
-```tsx
-function RootApp() {
-  return (
-    <BrowserRouter>
-      <Routes>
-        {/* Public routes - completely isolated */}
-        <Route path="/events/*" element={<PublicPageApp />} />
-        <Route path="/public/*" element={<PublicPageApp />} />
-        <Route path="/reports/*" element={<PublicPageApp />} />
-        
-        {/* Authenticated routes - normal app */}
-        <Route path="/*" element={<AuthenticatedApp />} />
-      </Routes>
-    </BrowserRouter>
-  );
-}
-```
-
-## 🚀 **Quick Start Implementation**
-
-### Step 1: Create Public Page App
-
-```tsx
-// PublicPageApp.tsx
-import React from 'react';
-import { Routes, Route } from 'react-router-dom';
-import { 
-  PublicPageProvider,
-  PublicPageLayout, 
-  PublicPageHeader, 
-  PublicPageFooter,
-  usePublicEvent,
-  usePublicRouteParams,
-  PublicLoadingSpinner
-} from '@jmruthers/pace-core';
-
-export function PublicPageApp() {
-  return (
-    <PublicPageProvider>
-      <Routes>
-        <Route path="/events/:eventCode/recipe-grid-report" element={<PublicRecipePage />} />
-        <Route path="/events/:eventCode" element={<PublicEventPage />} />
-        <Route path="/reports/:reportId" element={<PublicReportPage />} />
-      </Routes>
-    </PublicPageProvider>
-  );
-}
-```
-
-### Step 2: Create Individual Public Pages
-
-```tsx
-// PublicRecipePage.tsx
-import React from 'react';
-import { 
-  PublicPageLayout, 
-  PublicPageHeader, 
-  PublicPageFooter,
-  usePublicEvent,
-  usePublicRouteParams,
-  PublicLoadingSpinner
-} from '@jmruthers/pace-core';
-
-export function PublicRecipePage() {
-  // Step 1: Get event code from URL
-  const { eventCode } = usePublicRouteParams({ fetchEventData: false });
-  
-  // Step 2: Fetch event data
-  const { event, isLoading, error } = usePublicEvent(eventCode || '');
-  
-  // Step 3: Handle loading
-  if (isLoading) {
-    return <PublicLoadingSpinner message="Loading recipe grid report..." />;
-  }
-  
-  // Step 4: Handle error
-  if (error || !event) {
-    return (
-      <div className="min-h-screen bg-white flex items-center justify-center">
-        <div className="text-center">
-          <h1 className="text-2xl font-bold text-gray-900 mb-4">
-            Recipe Grid Report Not Found
-          </h1>
-          <p className="text-gray-600">
-            The event code "{eventCode}" is invalid or not available for public viewing.
-          </p>
-        </div>
-      </div>
-    );
-  }
-  
-  // Step 5: Render public page
-  return (
-    <PublicPageLayout eventCode={eventCode || ''} event={event}>
-      <PublicPageHeader 
-        event={event}
-        eventCode={eventCode || ''}
-        title="Recipe Grid Report"
-        description="Public recipe grid report for this event"
-      />
-      
-      <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">
-          <h2 className="text-xl font-semibold mb-4">Recipe Grid Report</h2>
-          <p>Event: {event.event_name}</p>
-          <p>Code: {event.event_code}</p>
-          {/* Add your recipe grid content */}
-        </div>
-      </main>
-      
-      <PublicPageFooter event={event} />
-    </PublicPageLayout>
-  );
-}
-```
-
-### Step 3: Update Your Main App
-
-```tsx
-// App.tsx
-import React from 'react';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-import { UnifiedAuthProvider, OrganisationProvider, EventProvider } from '@jmruthers/pace-core';
-import { PublicPageApp } from './PublicPageApp';
-import { AuthenticatedApp } from './AuthenticatedApp';
-
-function App() {
-  return (
-    <BrowserRouter>
-      <Routes>
-        {/* Public routes - completely separate */}
-        <Route path="/events/*" element={<PublicPageApp />} />
-        <Route path="/public/*" element={<PublicPageApp />} />
-        <Route path="/reports/*" element={<PublicPageApp />} />
-        
-        {/* Authenticated routes */}
-        <Route path="/*" element={
-          <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
-            <OrganisationProvider>
-              <EventProvider>
-                <AuthenticatedApp />
-              </EventProvider>
-            </OrganisationProvider>
-          </UnifiedAuthProvider>
-        } />
-      </Routes>
-    </BrowserRouter>
-  );
-}
-
-export default App;
-```
-
-## 🧩 **Core Components**
-
-### PublicPageProvider
-
-**Required wrapper for all public pages.** Provides environment variables and context without authentication.
-
-```tsx
-import { PublicPageProvider } from '@jmruthers/pace-core';
-
-<PublicPageProvider>
-  {/* All your public pages go here */}
-</PublicPageProvider>
-```
-
-### PublicPageLayout
-
-**Main layout component for public pages.** Handles event data and provides consistent styling.
-
-```tsx
-import { PublicPageLayout } from '@jmruthers/pace-core';
-
-<PublicPageLayout 
-  eventCode="EVENT123" 
-  event={eventData}
-  showFooter={true}
->
-  {/* Your page content */}
-</PublicPageLayout>
-```
-
-**Props:**
-- `eventCode` (required) - The event code from the URL
-- `event` (optional) - Event data object
-- `showFooter` (optional) - Show/hide footer
-- `className` (optional) - Additional CSS classes
-- `errorFallback` (optional) - Custom error component
-- `loadingFallback` (optional) - Custom loading component
-
-### PublicPageHeader
-
-**Header component with event branding and information.**
-
-```tsx
-import { PublicPageHeader } from '@jmruthers/pace-core';
-
-<PublicPageHeader 
-  event={event}
-  eventCode="EVENT123"
-  title="Recipe Grid Report"
-  description="Public recipe grid report for this event"
-  showEventLogo={true}
-  showAppLogo={true}
-/>
-```
-
-**Props:**
-- `event` (required) - Event data object
-- `eventCode` (required) - Event code from URL
-- `title` (optional) - Page title
-- `description` (optional) - Page description
-- `showEventLogo` (optional) - Show event logo
-- `showAppLogo` (optional) - Show app logo
-
-### PublicPageFooter
-
-**Footer component with event and app information.**
-
-```tsx
-import { PublicPageFooter } from '@jmruthers/pace-core';
-
-<PublicPageFooter 
-  event={event}
-  showEventInfo={true}
-  showCopyright={true}
-  showAppBranding={true}
-/>
-```
-
-## 🔗 **Hooks for Public Pages**
-
-### usePublicRouteParams
-
-**Extract parameters from public page URLs.**
-
-```tsx
-import { usePublicRouteParams } from '@jmruthers/pace-core';
-
-function MyPublicPage() {
-  const { eventCode, reportId, pageId } = usePublicRouteParams({ 
-    fetchEventData: false // Don't auto-fetch event data
-  });
-  
-  // Use the parameters
-  console.log('Event Code:', eventCode);
-  console.log('Report ID:', reportId);
-}
-```
-
-### usePublicEvent
-
-**Fetch event data for public pages.**
-
-```tsx
-import { usePublicEvent } from '@jmruthers/pace-core';
-
-function MyPublicPage() {
-  const { event, isLoading, error, refetch } = usePublicEvent('EVENT123');
-  
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!event) return <div>Event not found</div>;
-  
-  return <div>Event: {event.event_name}</div>;
-}
-```
-
-### useIsPublicPage
-
-**Check if current page is a public page.**
-
-```tsx
-import { useIsPublicPage } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const isPublicPage = useIsPublicPage();
-  
-  if (isPublicPage) {
-    return <div>This is a public page</div>;
-  }
-  
-  return <div>This is an authenticated page</div>;
-}
-```
-
-## 📋 **Common Implementation Patterns**
-
-### Pattern 1: Event-Based Public Pages
-
-```tsx
-// /events/:eventCode/recipe-grid-report
-function PublicRecipePage() {
-  const { eventCode } = usePublicRouteParams({ fetchEventData: false });
-  const { event, isLoading, error } = usePublicEvent(eventCode || '');
-  
-  if (isLoading) return <PublicLoadingSpinner message="Loading..." />;
-  if (error || !event) return <PublicErrorPage eventCode={eventCode} />;
-  
-  return (
-    <PublicPageLayout eventCode={eventCode || ''} event={event}>
-      <PublicPageHeader 
-        event={event}
-        eventCode={eventCode || ''}
-        title="Recipe Grid Report"
-      />
-      
-      <main>
-        {/* Your recipe grid content */}
-      </main>
-      
-      <PublicPageFooter event={event} />
-    </PublicPageLayout>
-  );
-}
-```
-
-### Pattern 2: Report-Based Public Pages
-
-```tsx
-// /reports/:reportId
-function PublicReportPage() {
-  const { reportId } = usePublicRouteParams({ fetchEventData: false });
-  const [report, setReport] = useState(null);
-  const [loading, setLoading] = useState(true);
-  
-  useEffect(() => {
-    // Fetch report data
-    fetchReport(reportId).then(setReport).finally(() => setLoading(false));
-  }, [reportId]);
-  
-  if (loading) return <PublicLoadingSpinner message="Loading report..." />;
-  if (!report) return <div>Report not found</div>;
-  
-  return (
-    <PublicPageLayout eventCode={report.eventCode} event={report.event}>
-      <PublicPageHeader 
-        event={report.event}
-        eventCode={report.eventCode}
-        title={report.title}
-        description={report.description}
-      />
-      
-      <main>
-        {/* Your report content */}
-      </main>
-      
-      <PublicPageFooter event={report.event} />
-    </PublicPageLayout>
-  );
-}
-```
-
-### Pattern 3: Simple Public Info Pages
-
-```tsx
-// /public/:pageId
-function PublicInfoPage() {
-  const { pageId } = usePublicRouteParams({ fetchEventData: false });
-  
-  return (
-    <div className="min-h-screen bg-white">
-      <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>
-        {/* Your content */}
-      </div>
-    </div>
-  );
-}
-```
-
-## ⚠️ **Common Mistakes & Solutions**
-
-### Mistake 1: Public Pages Inside Auth Context
-
-**❌ Problem:**
-```tsx
-<UnifiedAuthProvider>
-  <Route path="/events/:eventCode" element={<PublicPage />} />
-</UnifiedAuthProvider>
-```
-
-**✅ Solution:**
-```tsx
-<Routes>
-  <Route path="/events/*" element={<PublicPageApp />} />
-  <Route path="/*" element={
-    <UnifiedAuthProvider>
-      <AuthenticatedApp />
-    </UnifiedAuthProvider>
-  } />
-</Routes>
-```
-
-### Mistake 2: Using Auth Hooks in Public Pages
-
-**❌ Problem:**
-```tsx
-function PublicPage() {
-  const { user } = useUnifiedAuth(); // ❌ This will break
-  // ...
-}
-```
-
-**✅ Solution:**
-```tsx
-function PublicPage() {
-  const { event } = usePublicEvent(eventCode); // ✅ Use public hooks
-  // ...
-}
-```
-
-### Mistake 3: Missing PublicPageProvider
-
-**❌ Problem:**
-```tsx
-<Route path="/events/:eventCode" element={<PublicPage />} />
-```
-
-**✅ Solution:**
-```tsx
-<Route path="/events/*" element={
-  <PublicPageProvider>
-    <Routes>
-      <Route path=":eventCode" element={<PublicPage />} />
-    </Routes>
-  </PublicPageProvider>
-} />
-```
-
-### Mistake 4: Not Handling Loading/Error States
-
-**❌ Problem:**
-```tsx
-function PublicPage() {
-  const { event } = usePublicEvent(eventCode);
-  return <div>{event.event_name}</div>; // ❌ No loading/error handling
-}
-```
-
-**✅ Solution:**
-```tsx
-function PublicPage() {
-  const { event, isLoading, error } = usePublicEvent(eventCode);
-  
-  if (isLoading) return <PublicLoadingSpinner message="Loading..." />;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!event) return <div>Event not found</div>;
-  
-  return <div>{event.event_name}</div>;
-}
-```
-
-## 🔧 **Environment Setup**
-
-### Required Environment Variables
-
-```env
-# .env.local
-VITE_SUPABASE_URL=your_supabase_url
-VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
-VITE_APP_NAME=Your App Name
-```
-
-### Database Setup
-
-Public pages need access to event data. Ensure your database has:
-
-1. **Events table** with public event data
-2. **RLS policies** that allow public access to specific events
-3. **Event codes** that are publicly accessible
-
-```sql
--- Example RLS policy for public events
-CREATE POLICY "Public events are viewable by anyone" ON events
-  FOR SELECT USING (is_public = true);
-```
-
-## 🧪 **Testing Public Pages**
-
-### Unit Testing
-
-```tsx
-import { render, screen } from '@testing-library/react';
-import { PublicPageProvider } from '@jmruthers/pace-core';
-import { PublicRecipePage } from './PublicRecipePage';
-
-test('renders public recipe page', () => {
-  render(
-    <PublicPageProvider>
-      <PublicRecipePage />
-    </PublicPageProvider>
-  );
-  
-  expect(screen.getByText('Recipe Grid Report')).toBeInTheDocument();
-});
-```
-
-### Integration Testing
-
-```tsx
-import { render, screen } from '@testing-library/react';
-import { BrowserRouter } from 'react-router-dom';
-import { PublicPageApp } from './PublicPageApp';
-
-test('public page app routing works', () => {
-  render(
-    <BrowserRouter>
-      <PublicPageApp />
-    </BrowserRouter>
-  );
-  
-  // Test routing to public pages
-  expect(screen.getByText('Recipe Grid Report')).toBeInTheDocument();
-});
-```
-
-## 🚀 **Deployment Considerations**
-
-### Build Configuration
-
-Ensure your build process handles both authenticated and public routes:
-
-```tsx
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  build: {
-    rollupOptions: {
-      output: {
-        manualChunks: {
-          // Separate chunks for public and authenticated apps
-          'public-app': ['./src/PublicPageApp.tsx'],
-          'auth-app': ['./src/AuthenticatedApp.tsx']
-        }
-      }
-    }
-  }
-});
-```
-
-### Server Configuration
-
-Configure your server to handle both route types:
-
-```nginx
-# nginx.conf
-location /events/ {
-  try_files $uri $uri/ /index.html; # SPA routing for public pages
-}
-
-location /public/ {
-  try_files $uri $uri/ /index.html; # SPA routing for public pages
-}
-
-location / {
-  try_files $uri $uri/ /index.html; # SPA routing for authenticated pages
-}
-```
-
-## 📚 **Complete Example**
-
-Here's a complete working example:
-
-```tsx
-// App.tsx - Root application
-import React from 'react';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-import { UnifiedAuthProvider, OrganisationProvider, EventProvider } from '@jmruthers/pace-core';
-import { PublicPageApp } from './PublicPageApp';
-import { AuthenticatedApp } from './AuthenticatedApp';
-
-function App() {
-  return (
-    <BrowserRouter>
-      <Routes>
-        {/* Public routes - completely separate */}
-        <Route path="/events/*" element={<PublicPageApp />} />
-        <Route path="/public/*" element={<PublicPageApp />} />
-        <Route path="/reports/*" element={<PublicPageApp />} />
-        
-        {/* Authenticated routes */}
-        <Route path="/*" element={
-          <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
-            <OrganisationProvider>
-              <EventProvider>
-                <AuthenticatedApp />
-              </EventProvider>
-            </OrganisationProvider>
-          </UnifiedAuthProvider>
-        } />
-      </Routes>
-    </BrowserRouter>
-  );
-}
-
-export default App;
-```
-
-```tsx
-// PublicPageApp.tsx - Public pages application
-import React from 'react';
-import { Routes, Route } from 'react-router-dom';
-import { PublicPageProvider } from '@jmruthers/pace-core';
-import { PublicRecipePage } from './pages/PublicRecipePage';
-import { PublicEventPage } from './pages/PublicEventPage';
-
-export function PublicPageApp() {
-  return (
-    <PublicPageProvider>
-      <Routes>
-        <Route path="/events/:eventCode/recipe-grid-report" element={<PublicRecipePage />} />
-        <Route path="/events/:eventCode" element={<PublicEventPage />} />
-      </Routes>
-    </PublicPageProvider>
-  );
-}
-```
-
-```tsx
-// pages/PublicRecipePage.tsx - Individual public page
-import React from 'react';
-import { 
-  PublicPageLayout, 
-  PublicPageHeader, 
-  PublicPageFooter,
-  usePublicEvent,
-  usePublicRouteParams,
-  PublicLoadingSpinner
-} from '@jmruthers/pace-core';
-
-export function PublicRecipePage() {
-  const { eventCode } = usePublicRouteParams({ fetchEventData: false });
-  const { event, isLoading, error } = usePublicEvent(eventCode || '');
-  
-  if (isLoading) {
-    return <PublicLoadingSpinner message="Loading recipe grid report..." />;
-  }
-  
-  if (error || !event) {
-    return (
-      <div className="min-h-screen bg-white flex items-center justify-center">
-        <div className="text-center">
-          <h1 className="text-2xl font-bold text-gray-900 mb-4">
-            Recipe Grid Report Not Found
-          </h1>
-          <p className="text-gray-600">
-            The event code "{eventCode}" is invalid or not available for public viewing.
-          </p>
-        </div>
-      </div>
-    );
-  }
-  
-  return (
-    <PublicPageLayout eventCode={eventCode || ''} event={event}>
-      <PublicPageHeader 
-        event={event}
-        eventCode={eventCode || ''}
-        title="Recipe Grid Report"
-        description="Public recipe grid report for this event"
-      />
-      
-      <main className="max-w-6xl mx-auto px-4 py-8">
-        <div className="bg-white 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>
-          {/* Add your recipe grid content here */}
-        </div>
-      </main>
-      
-      <PublicPageFooter event={event} />
-    </PublicPageLayout>
-  );
-}
-```
-
-## 🔗 **Related Documentation**
-
-- **[API Reference - Public Components](../api-reference/components.md#public-components)** - Complete component API
-- **[Troubleshooting - Public Pages](../troubleshooting/common-issues.md#public-pages)** - Common issues and solutions
-- **[Examples - Public Page App](../getting-started/examples/)** - Complete working examples
-- **[Migration Guide - Public Pages](../migration/README.md#public-pages)** - Migration from other approaches
-
----
-
-**Remember**: Public pages are completely separate from your main app. Keep them isolated and they'll work perfectly!