@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/troubleshooting/common-issues.md

@@ -2,6 +2,125 @@
 
 This guide provides solutions to the most common issues you may encounter when using `@jmruthers/pace-core`.
 
+## Navigation Issues
+
+### NavigationMenu Not Receiving Authentication Context
+
+**Problem**: `NavigationMenu` shows `permissions: undefined`, `roles: undefined`, `accessLevel: undefined` in console logs.
+
+**Root Cause**: The `NavigationMenu` component is not properly connected to the authentication context.
+
+**Solution**: Ensure `NavigationMenu` is used within the proper provider hierarchy and enable permission filtering:
+
+```tsx
+// ❌ WRONG - NavigationMenu without proper context
+<NavigationMenu 
+  items={navItems}
+  currentPath={location.pathname}
+  onNavigate={handleNavigate}
+/>
+
+// ✅ CORRECT - NavigationMenu with authentication context
+<UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+  <OrganisationProvider>
+    <EventProvider>
+      <PaceAppLayout 
+        appName="My App" 
+        navItems={navItems}
+        showEventSelector={true}
+      >
+        <Routes>
+          {/* Your routes */}
+        </Routes>
+      </PaceAppLayout>
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+**Alternative Solution**: Use `NavigationMenu` directly with permission filtering:
+
+```tsx
+import { NavigationMenu } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function AuthenticatedNavigation() {
+  const { hasPermission, hasRole } = useUnifiedAuth();
+
+  const navItems = [
+    { 
+      id: 'dashboard', 
+      label: 'Dashboard', 
+      href: '/dashboard',
+      permissions: ['dashboard:read']
+    },
+    { 
+      id: 'admin', 
+      label: 'Admin Panel', 
+      href: '/admin',
+      roles: ['admin']
+    }
+  ];
+
+  return (
+    <NavigationMenu 
+      items={navItems}
+      currentPath={location.pathname}
+      onNavigate={handleNavigate}
+      filterByPermissions={true}
+      auditLog={true}
+    />
+  );
+}
+```
+
+### NavigationMenu Items Not Filtering by Permissions
+
+**Problem**: All navigation items are shown regardless of user permissions.
+
+**Solution**: Enable permission filtering and add permission requirements to navigation items:
+
+```tsx
+// Add permissions to navigation items
+const navItems = [
+  { 
+    id: 'dashboard', 
+    label: 'Dashboard', 
+    href: '/dashboard',
+    permissions: ['dashboard:read'] // Required permission
+  },
+  { 
+    id: 'admin', 
+    label: 'Admin Panel', 
+    href: '/admin',
+    roles: ['admin', 'super_admin'] // Required roles
+  }
+];
+
+// Enable filtering
+<NavigationMenu 
+  items={navItems}
+  filterByPermissions={true}
+  auditLog={true}
+/>
+```
+
+### NavigationMenu Console Errors
+
+**Problem**: Console shows "useUnifiedAuth not available" warnings.
+
+**Solution**: Ensure `NavigationMenu` is used within `UnifiedAuthProvider`:
+
+```tsx
+// ❌ WRONG - Outside of auth provider
+<NavigationMenu items={navItems} />
+
+// ✅ CORRECT - Inside auth provider
+<UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+  <NavigationMenu items={navItems} />
+</UnifiedAuthProvider>
+```
+
 ## Authentication Issues
 
 ### 1. "User not authenticated" Error
@@ -244,7 +363,148 @@ function OrganisationContextGuard({ children }: { children: React.ReactNode }) {
 
 ## Styling Issues
 
-### 1. App Looks Different from Demo (v0.3.47+ Fixed)
+### 1. App Looks Unstyled (Raw HTML)
+
+**Problem**: App appears with default browser styling only - no colors, fonts, or proper layout.
+
+**Symptoms**:
+- Default browser styling only
+- No colors, fonts, or layout
+- Components look like plain HTML
+- Header is squashed or too wide
+- Main container stretches full width
+- Missing colored background
+
+**Solution**:
+
+**CRITICAL**: Use the `PaceAppLayout` component - don't just import CSS files:
+
+```tsx
+// ❌ Wrong - just CSS imports
+import '@jmruthers/pace-core/styles/core.css';
+
+function App() {
+  return (
+    <div>
+      <h1>My App</h1>
+      {/* This won't be styled properly */}
+    </div>
+  );
+}
+
+// ✅ Correct - use PaceAppLayout
+import { PaceAppLayout } from '@jmruthers/pace-core';
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
+
+function App() {
+  return (
+    <PaceAppLayout appName="My Application">
+      <div className="container mx-auto px-4 py-6">
+        <h1 className="text-3xl font-bold text-main-900">My App</h1>
+        <p className="text-main-700">This will be properly styled</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+**Common Causes**:
+- Missing CSS imports
+- Wrong build tool configuration (using Tailwind v3 instead of v4)
+- Not using PaceAppLayout component
+- Missing app.css with color palette
+- CSS files not being processed
+
+**Build Tool Configuration**:
+
+**For Vite (Recommended):**
+```js
+// vite.config.js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss() // Tailwind v4 - no config file needed!
+  ],
+})
+```
+
+**Dependencies:**
+```bash
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+# Remove old Tailwind v3 if installed
+npm uninstall tailwindcss@^3.0.0
+```
+
+**Create app.css with Color Palette:**
+```css
+/* app.css - Your app's color palette */
+@theme static {
+  /* MAIN palette - your primary brand color */
+  --color-main-raw: oklch(0.7 0.057 252.02);
+  --color-main-50: oklch(0.98 0.001 252.02);
+  --color-main-100: oklch(0.96 0.005 252.02);
+  --color-main-200: oklch(0.927 0.012 252.02);
+  --color-main-300: oklch(0.881 0.021 252.02);
+  --color-main-400: oklch(0.822 0.032 252.02);
+  --color-main-500: oklch(0.75 0.047 252.02);
+  --color-main-600: oklch(0.7 0.057 252.02);
+  --color-main-700: oklch(0.567 0.044 252.02);
+  --color-main-800: oklch(0.456 0.034 252.02);
+  --color-main-900: oklch(0.332 0.024 252.02);
+  --color-main-950: oklch(0.195 0.014 252.02);
+
+  /* SEC palette - your secondary brand color */
+  --color-sec-raw: oklch(0.58 0.23 280.75);
+  --color-sec-50: oklch(0.98 0.003 280.75);
+  --color-sec-100: oklch(0.96 0.014 280.75);
+  --color-sec-200: oklch(0.927 0.033 280.75);
+  --color-sec-300: oklch(0.881 0.059 280.75);
+  --color-sec-400: oklch(0.822 0.093 280.75);
+  --color-sec-500: oklch(0.75 0.133 280.75);
+  --color-sec-600: oklch(0.665 0.182 280.75);
+  --color-sec-700: oklch(0.58 0.23 280.75);
+  --color-sec-800: oklch(0.456 0.158 280.75);
+  --color-sec-900: oklch(0.332 0.099 280.75);
+  --color-sec-950: oklch(0.195 0.047 280.75);
+
+  /* ACC palette - your accent brand color */
+  --color-acc-raw: oklch(0.64 0.21 37.76);
+  --color-acc-50: oklch(0.98 0.003 37.76);
+  --color-acc-100: oklch(0.96 0.015 37.76);
+  --color-acc-200: oklch(0.927 0.035 37.76);
+  --color-acc-300: oklch(0.881 0.063 37.76);
+  --color-acc-400: oklch(0.822 0.099 37.76);
+  --color-acc-500: oklch(0.75 0.143 37.76);
+  --color-acc-600: oklch(0.64 0.21 37.76);
+  --color-acc-700: oklch(0.567 0.177 37.76);
+  --color-acc-800: oklch(0.456 0.13 37.76);
+  --color-acc-900: oklch(0.332 0.085 37.76);
+  --color-acc-950: oklch(0.195 0.044 37.76);
+}
+```
+
+**Debugging Steps**:
+1. Check Browser DevTools for CSS import errors
+2. Verify pace-core CSS files are loading in Network tab
+3. Inspect elements to see if Tailwind classes are applied
+4. Ensure Tailwind v4 is installed and configured
+5. Test CSS imports with temporary rule: `body { background-color: red !important; }`
+
+**Quick Checklist**:
+- [ ] CSS files imported in main.tsx/App.tsx
+- [ ] app.css created with color palette
+- [ ] Using PaceAppLayout component
+- [ ] Tailwind v4 configured in build tool
+- [ ] No custom CSS overriding pace-core styles
+- [ ] All required dependencies installed
+- [ ] No build errors in console
+
+### 2. App Looks Different from Demo (v0.3.47+ Fixed)
 
 **Problem**: Your consuming app looks different from the PACE Core demo app
 
@@ -279,13 +539,13 @@ npm install @jmruthers/pace-core@latest
 
 **Root Cause**: Missing CSS variables that the header component depends on:
 - `--app-width` (for container width)
-- `--color-app-main-*` (for header background colors)
-- `--color-app-sec-*` and `--color-app-acc-*` (for other header elements)
+- `--color-main-*` (for header background colors)
+- `--color-sec-*` and `--color-acc-*` (for other header elements)
 
 **Solution**: This issue was fixed in v0.3.48+. The theme file now includes all required CSS variables:
 
 - **Layout Variables**: `--app-width: 90rem`
-- **App Color Variables**: `--color-app-main-*`, `--color-app-sec-*`, `--color-app-acc-*`
+- **App Color Variables**: `--color-main-*`, `--color-sec-*`, `--color-acc-*`
 - **Complete Color Palette**: All color variants (50, 100, 200, etc.) plus `-raw` variants
 
 **Quick Fix**:
@@ -322,9 +582,92 @@ npm install @jmruthers/pace-core@latest
 npm install @jmruthers/pace-core@latest
 ```
 
-### 4. Tailwind v4 Theme File Issues (v0.3.45+ Fixed)
+### 4. Login Page Styling Issues (v0.4.4+ Fixed)
+
+**Problem**: Login page looks different from the pace-core demo - unstyled button, wrong background, missing shadows.
+
+**Symptoms**:
+- Button appears as plain text instead of styled button
+- Background is white instead of gradient
+- Card has no shadow or wrong styling
+- Input fields are dark instead of white
+- Overall appearance doesn't match the demo
+
+**Root Cause**: Missing theme mappings in `styles/core.css` prevented CSS variables from being processed correctly by Tailwind v4.
+
+**Solution**: This issue was fixed in v0.4.4+. The theme file now includes complete mappings for all color palettes.
+
+**Quick Fix**:
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+**Required Setup** (must be exactly like this):
+
+1. **CSS Imports** (in your main.tsx):
+```tsx
+import './app.css'; // Your app's palette definitions (must come first)
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+2. **App.css** (complete palette required):
+```css
+@theme static {
+  /* MAIN palette - your primary brand color */
+  --color-main-50: oklch(0.98 0.001 252.02);
+  --color-main-100: oklch(0.96 0.005 252.02);
+  /* ... all shades 50-950 + raw */
+  
+  /* SEC palette - your secondary brand color */
+  --color-sec-50: oklch(0.98 0.003 280.75);
+  /* ... all shades 50-950 + raw */
+  
+  /* ACC palette - your accent brand color */
+  --color-acc-50: oklch(0.98 0.003 37.76);
+  /* ... all shades 50-950 + raw */
+}
+
+@layer base {
+  .appGradient {
+    background: radial-gradient(var(--color-main-200), oklch(from var(--color-main-200) l c h / 0%) 30%), 
+                conic-gradient(var(--color-main-200), var(--color-sec-200), var(--color-acc-200), var(--color-main-200));
+    background-attachment: fixed;
+  }
+}
+```
+
+3. **HTML Structure** (in your index.html):
+```html
+<body class="appGradient">
+  <div id="root" class="grid grid-rows-[auto_1fr_auto] min-h-screen"></div>
+</body>
+```
+
+4. **Vite Configuration** (Tailwind v4 required):
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss() // Tailwind v4 - no config file needed!
+  ],
+});
+```
+
+**Debugging Steps**:
+1. Check browser dev tools for CSS import errors
+2. Verify `bg-main-600` class resolves to actual color value
+3. Ensure all CSS files are imported in correct order
+4. Confirm Tailwind v4 is installed (not v3)
+5. Test with minimal setup to isolate the issue
+
+### 5. Tailwind v4 Theme File Issues (v0.3.45+ Fixed)
 
-**Problem**: Build failures when using `@import '@jmruthers/pace-core/styles/tailwind-v4-theme'`
+**Problem**: Build failures when using `@import '@jmruthers/pace-core/styles/core.css'`
 
 **Root Cause**: The theme file was missing semantic colors and had circular references in component classes.
 
@@ -342,7 +685,7 @@ npm install @jmruthers/pace-core@latest
 **Usage**:
 ```css
 /* index.css */
-@import '@jmruthers/pace-core/styles/tailwind-v4-theme';
+@import '@jmruthers/pace-core/styles/core.css';
 ```
 
 **Vite Configuration**:
@@ -384,7 +727,7 @@ export default defineConfig({
 ```css
 /* ✅ Fixed - no circular references */
 .pace-button-primary {
-  @apply inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none ring-offset-background bg-primary-600 text-white hover:bg-primary-700 active:bg-primary-800;
+  @apply inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none ring-offset-background bg-primary-600 text-main-50 hover:bg-primary-700 active:bg-primary-800;
 }
 ```
 
@@ -593,16 +936,16 @@ function App() {
 
 ```typescript
 // Ensure Tailwind CSS is imported
-import '@jmruthers/pace-core/styles.css';
-
-// Check if theme provider is set up
-import { ThemeProvider } from '@jmruthers/pace-core';
+// Import the core CSS file
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
 
+// Check if your app is properly set up
 function App() {
   return (
-    <ThemeProvider>
+    <div>
       <YourApp />
-    </ThemeProvider>
+    </div>
   );
 }
 ```
@@ -950,6 +1293,253 @@ function LoggingErrorBoundary({ children }) {
 }
 ```
 
+## 🌐 Public Pages Issues
+
+### Public Pages Not Working
+
+**Problem**: Public pages show authentication errors or don't load properly
+
+**Root Cause**: Public pages are being rendered inside the authentication context
+
+**Solution**: Public pages MUST be completely separate from your main app
+
+```tsx
+// ❌ WRONG - This will break
+<UnifiedAuthProvider>
+  <Routes>
+    <Route path="/events/:eventCode" element={<PublicPage />} />
+  </Routes>
+</UnifiedAuthProvider>
+
+// ✅ CORRECT - Separate applications
+<BrowserRouter>
+  <Routes>
+    <Route path="/events/*" element={<PublicPageApp />} />
+    <Route path="/*" element={
+      <UnifiedAuthProvider>
+        <AuthenticatedApp />
+      </UnifiedAuthProvider>
+    } />
+  </Routes>
+</BrowserRouter>
+```
+
+**Complete Setup:**
+```tsx
+// PublicPageApp.tsx
+import { PublicPageProvider } from '@jmruthers/pace-core';
+
+export function PublicPageApp() {
+  return (
+    <PublicPageProvider>
+      <Routes>
+        <Route path="/events/:eventCode" element={<PublicEventPage />} />
+      </Routes>
+    </PublicPageProvider>
+  );
+}
+```
+
+### Public Page Hooks Not Working
+
+**Problem**: `usePublicEvent` or `usePublicRouteParams` return null/undefined
+
+**Root Cause**: Not using the hooks inside `PublicPageProvider`
+
+**Solution**: Ensure all public page components are wrapped in `PublicPageProvider`
+
+```tsx
+// ❌ WRONG - Hooks won't work
+function PublicPage() {
+  const { eventCode } = usePublicRouteParams(); // Returns null
+  // ...
+}
+
+// ✅ CORRECT - Hooks work properly
+<PublicPageProvider>
+  <PublicPage /> {/* Hooks work here */}
+</PublicPageProvider>
+```
+
+### Public Page Loading Forever
+
+**Problem**: Public pages show loading spinner indefinitely
+
+**Root Cause**: Event data not found or API errors
+
+**Solution**: Add proper error handling and fallbacks
+
+```tsx
+function PublicEventPage() {
+  const { eventCode } = usePublicRouteParams({ fetchEventData: false });
+  const { event, isLoading, error, refetch } = usePublicEvent(eventCode || '');
+  
+  // Handle loading
+  if (isLoading) {
+    return <PublicLoadingSpinner message="Loading event..." />;
+  }
+  
+  // Handle error
+  if (error) {
+    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">
+            Event Not Found
+          </h1>
+          <p className="text-gray-600 mb-6">
+            The event code "{eventCode}" is invalid or not available for public viewing.
+          </p>
+          <button
+            onClick={refetch}
+            className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
+          >
+            Try Again
+          </button>
+        </div>
+      </div>
+    );
+  }
+  
+  // Handle missing event
+  if (!event) {
+    return <div>Event not found</div>;
+  }
+  
+  // Render the page
+  return (
+    <PublicPageLayout eventCode={eventCode || ''} event={event}>
+      {/* Your content */}
+    </PublicPageLayout>
+  );
+}
+```
+
+### Public Page Styling Issues
+
+**Problem**: Public pages appear unstyled or broken
+
+**Root Cause**: Missing CSS import or Tailwind configuration
+
+**Solution**: Ensure CSS is imported and Tailwind is configured
+
+```tsx
+// Make sure to import CSS
+import '@jmruthers/pace-core/styles/core.css';
+
+// And configure Tailwind properly
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+### Public Page Environment Variables
+
+**Problem**: Public pages can't access Supabase or environment variables
+
+**Root Cause**: Missing environment variables or incorrect configuration
+
+**Solution**: Set up environment variables and pass them to `PublicPageProvider`
+
+```tsx
+// .env.local
+VITE_SUPABASE_URL=your_supabase_url
+VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+VITE_APP_NAME=Your App Name
+
+// PublicPageApp.tsx
+import { PublicPageProvider } from '@jmruthers/pace-core';
+
+export function PublicPageApp() {
+  return (
+    <PublicPageProvider
+      environment={{
+        supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
+        supabaseKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
+      }}
+    >
+      <Routes>
+        <Route path="/events/:eventCode" element={<PublicEventPage />} />
+      </Routes>
+    </PublicPageProvider>
+  );
+}
+```
+
+### Public Page "process is not defined" Error
+
+**Problem**: `ReferenceError: process is not defined` when using `PublicPageProvider` in Vite-based applications
+
+**Root Cause**: The component is trying to access Node.js globals (`process`) that aren't available in browser environments
+
+**Solution**: This has been fixed in pace-core v0.4.61+. The `PublicPageProvider` now safely handles both browser and Node.js environments.
+
+**If you're still seeing this error:**
+
+1. **Update pace-core** to the latest version:
+   ```bash
+   npm update @jmruthers/pace-core
+   ```
+
+2. **Verify your Vite configuration** includes environment variable support:
+   ```ts
+   // vite.config.ts
+   export default defineConfig({
+     plugins: [react(), tailwindcss()],
+     envDir: '.', // Look for .env files in root
+     envPrefix: 'VITE_', // Only load VITE_ prefixed variables
+   })
+   ```
+
+3. **Set up environment variables** in your `.env` file:
+   ```bash
+   # .env.local
+   VITE_SUPABASE_URL=your_supabase_url
+   VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+   ```
+
+4. **Use the correct environment variable names**:
+   - ✅ `VITE_SUPABASE_URL` (Vite)
+   - ✅ `NEXT_PUBLIC_SUPABASE_URL` (Next.js)
+   - ❌ `SUPABASE_URL` (not prefixed for Vite)
+
+**The fix ensures:**
+- ✅ Safe access to `import.meta.env` (Vite/browser)
+- ✅ Safe access to `process.env` (Node.js/server)
+- ✅ Proper fallback handling
+- ✅ No "process is not defined" errors
+
+### Public Page Database Access
+
+**Problem**: Public pages can't access event data from database
+
+**Root Cause**: Missing RLS policies or incorrect database setup
+
+**Solution**: Set up proper RLS policies for public access
+
+```sql
+-- Enable RLS on events table
+ALTER TABLE events ENABLE ROW LEVEL SECURITY;
+
+-- Create policy for public events
+CREATE POLICY "Public events are viewable by anyone" ON events
+  FOR SELECT USING (is_public = true);
+
+-- Or allow specific event codes
+CREATE POLICY "Specific event codes are public" ON events
+  FOR SELECT USING (event_code IN ('EVENT123', 'EVENT456'));
+```
+
 ## Getting Help
 
 If you're still experiencing issues: