@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/troubleshooting/common-issues.md

@@ -2,125 +2,6 @@
 
 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
@@ -363,148 +244,7 @@ function OrganisationContextGuard({ children }: { children: React.ReactNode }) {
 
 ## Styling Issues
 
-### 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)
+### 1. App Looks Different from Demo (v0.3.47+ Fixed)
 
 **Problem**: Your consuming app looks different from the PACE Core demo app
 
@@ -539,13 +279,13 @@ npm install @jmruthers/pace-core@latest
 
 **Root Cause**: Missing CSS variables that the header component depends on:
 - `--app-width` (for container width)
-- `--color-main-*` (for header background colors)
-- `--color-sec-*` and `--color-acc-*` (for other header elements)
+- `--color-app-main-*` (for header background colors)
+- `--color-app-sec-*` and `--color-app-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-main-*`, `--color-sec-*`, `--color-acc-*`
+- **App Color Variables**: `--color-app-main-*`, `--color-app-sec-*`, `--color-app-acc-*`
 - **Complete Color Palette**: All color variants (50, 100, 200, etc.) plus `-raw` variants
 
 **Quick Fix**:
@@ -582,92 +322,9 @@ npm install @jmruthers/pace-core@latest
 npm install @jmruthers/pace-core@latest
 ```
 
-### 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)
+### 4. Tailwind v4 Theme File Issues (v0.3.45+ Fixed)
 
-**Problem**: Build failures when using `@import '@jmruthers/pace-core/styles/core.css'`
+**Problem**: Build failures when using `@import '@jmruthers/pace-core/styles/tailwind-v4-theme'`
 
 **Root Cause**: The theme file was missing semantic colors and had circular references in component classes.
 
@@ -685,7 +342,7 @@ npm install @jmruthers/pace-core@latest
 **Usage**:
 ```css
 /* index.css */
-@import '@jmruthers/pace-core/styles/core.css';
+@import '@jmruthers/pace-core/styles/tailwind-v4-theme';
 ```
 
 **Vite Configuration**:
@@ -727,7 +384,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-main-50 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-white hover:bg-primary-700 active:bg-primary-800;
 }
 ```
 
@@ -936,16 +593,16 @@ function App() {
 
 ```typescript
 // Ensure Tailwind CSS is imported
-// Import the core CSS file
-import './app.css'; // Your app's color palette (must come first)
-import '@jmruthers/pace-core/styles/core.css';
+import '@jmruthers/pace-core/styles.css';
+
+// Check if theme provider is set up
+import { ThemeProvider } from '@jmruthers/pace-core';
 
-// Check if your app is properly set up
 function App() {
   return (
-    <div>
+    <ThemeProvider>
       <YourApp />
-    </div>
+    </ThemeProvider>
   );
 }
 ```
@@ -1293,253 +950,6 @@ 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: