@jmruthers/pace-core 0.4.1 → 0.5.1

package/docs/consuming-app-vite-config.md

@@ -0,0 +1,233 @@
+# Consuming App Vite Configuration
+
+This document shows the **CRITICAL** Vite configuration for consuming apps using pace-core with Tailwind v4. Proper configuration is essential to ensure pace-core components are styled correctly.
+
+## ⚠️ Critical: Why This Configuration Matters
+
+Pace-core components contain Tailwind classes that **MUST** be scanned during the build process. Without proper configuration:
+
+- ❌ Component styles will be missing or broken
+- ❌ Colors, spacing, and typography won't work  
+- ❌ The UI will be severely compromised
+- ❌ The entire point of using this UI library is undermined
+
+## ✅ Solution: CSS-First Approach (v0.4.16+)
+
+**NEW**: Pace-core v0.4.16+ uses Tailwind v4's CSS-first approach with `@source` directives in `core.css`. This automatically scans the published source files without requiring complex Vite configuration.
+
+### Method 1: CSS-First Configuration (Recommended)
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      // Only need to scan your app's source files
+      // pace-core source files are automatically scanned via @source directives
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  server: {
+    port: 3000,
+    open: true,
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: true,
+  },
+})
+```
+
+### Method 2: Explicit Source File Scanning (Fallback)
+
+If the CSS-first approach doesn't work, you can explicitly include pace-core source files:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      // Explicitly include pace-core source files for scanning
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  server: {
+    port: 3000,
+    open: true,
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: true,
+  },
+})
+```
+
+### Alternative: PostCSS Configuration
+
+If you prefer PostCSS over Vite plugin:
+
+```javascript
+// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+## 🔄 Fallback: Hybrid Approach
+
+If source file scanning doesn't work, try this hybrid approach:
+
+```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({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        // Try source files first
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}',
+        // Fallback: also scan dist files
+        './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+## 🚨 Legacy Configuration (v0.4.14 and below)
+
+If you're using an older version, use this configuration:
+
+```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({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+## What This Configuration Does
+
+1. **Scans Your Source Files**: Detects Tailwind classes in your app's source code
+2. **Scans Pace-Core Source Files**: Ensures all Tailwind classes used in pace-core components are included
+3. **Generates Complete CSS**: Creates a CSS file with all necessary utility classes
+4. **Enables Proper Styling**: Allows pace-core components to render with correct styles
+
+## Verification Steps
+
+After configuration, verify everything works:
+
+1. **Import the CSS file** in your main entry point:
+   ```tsx
+   import '@jmruthers/pace-core/styles/core.css';
+   ```
+
+2. **Create a test component**:
+   ```tsx
+   import { Button, Card } from '@jmruthers/pace-core';
+   
+   function TestComponent() {
+     return (
+       <Card className="p-4">
+         <Button variant="primary" className="bg-main-600 text-main-50">
+           Test Button
+         </Button>
+       </Card>
+     );
+   }
+   ```
+
+3. **Check the result**: The component should render with proper PACE Core styling
+
+4. **Verify CSS size**: Your CSS file should be 50-100+ kB (not 20-30 kB)
+
+## Common Issues and Solutions
+
+### Issue: Components appear unstyled
+**Solution**: Ensure pace-core source files are included in content scanning
+
+### Issue: Colors don't work (text-main-900, bg-sec-500, etc.)
+**Solution**: Verify the CSS file is imported and content scanning includes pace-core source files
+
+### Issue: Build errors about missing classes
+**Solution**: Check that your content paths are correct and include both source files and pace-core source files
+
+### Issue: Still only 292 CSS rules instead of 800+
+**Solution**: 
+1. Update to pace-core v0.4.15+
+2. Use source file paths: `./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}`
+3. Clear build cache and rebuild
+
+### Issue: Source files not found
+**Solution**: Ensure you're using pace-core v0.4.15+ which includes source files in the published package
+
+## Key Points
+
+- ✅ **Required**: Must include pace-core source files in content scanning
+- ✅ **Critical**: Without this, components won't be styled
+- ✅ **Simple**: Just add the source file paths to your content array
+- ✅ **Reliable**: Works with any project structure when configured correctly
+
+## What NOT to Do
+
+- ❌ **Don't skip content configuration** - pace-core won't be scanned
+- ❌ **Don't rely on automatic scanning only** - it may not catch node_modules
+- ❌ **Don't forget to import the CSS file** - styles won't be available
+- ❌ **Don't assume it works without testing** - always verify with a test component
+
+## Next Steps
+
+- [Installation Guide](./getting-started/installation.md) - Complete setup instructions
+- [Tailwind Content Scanning Guide](./troubleshooting/tailwind-content-scanning.md) - Detailed troubleshooting
+- [Troubleshooting Guide](./troubleshooting/styling-issues.md) - Fix common problems

package/docs/core-concepts/events.md

@@ -492,15 +492,15 @@ function EventStatusIndicator() {
   const status = getEventStatus(selectedEvent.event_date);
   const statusConfig = {
     past: { label: 'Past Event', color: 'text-muted-foreground' },
-    today: { label: 'Today', color: 'text-green-600' },
-    upcoming: { label: 'Upcoming', color: 'text-blue-600' },
+    today: { label: 'Today', color: 'text-main-600' },
+    upcoming: { label: 'Upcoming', color: 'text-main-600' },
   };
 
   return (
     <div className={`flex items-center space-x-2 ${statusConfig[status].color}`}>
       <div className={`w-2 h-2 rounded-full ${
         status === 'past' ? 'bg-muted' :
-        status === 'today' ? 'bg-green-500' : 'bg-blue-500'
+        status === 'today' ? 'bg-main-500' : 'bg-main-500'
       }`} />
       <span className="text-sm font-medium">
         {statusConfig[status].label}

package/docs/core-concepts/organisations.md

@@ -38,7 +38,6 @@ interface Organisation {
 
 ```typescript
 interface OrganisationSettings {
-  theme: 'light' | 'dark' | 'auto';
   timezone: string;
   date_format: string;
   time_format: '12h' | '24h';

package/docs/core-concepts/rbac-system.md

@@ -62,12 +62,12 @@ Permissions define specific actions users can perform on resources.
 - **settings** - Configuration management
 
 #### Permission Examples
-- `view_basic` - View basic organisation information
-- `view_details` - View detailed organisation information
-- `moderate_content` - Moderate content within organisation
-- `manage_events` - Create and manage events
-- `manage_members` - Manage organisation members
-- `manage_settings` - Manage organisation settings
+- `read:page.dashboard` - View dashboard page
+- `create:page.users` - Create users on users page
+- `update:page.settings` - Modify settings page
+- `delete:page.admin` - Remove content from admin page
+- `manage:page.system` - Full system page management
+- `read:events` - View event information (event-app permission)
 
 ### Permission Hierarchy
 
@@ -75,16 +75,20 @@ Permissions follow a hierarchical structure based on organisation roles:
 
 ```
 Organisation Admin
-├── All permissions (view_basic, view_details, moderate_content, manage_events, manage_members, manage_settings)
+├── All page permissions (read:page.*, create:page.*, update:page.*, delete:page.*, manage:page.*)
+├── All event-app permissions (read:events, create:events, update:events, delete:events)
 
 Leader
-├── view_basic, view_details, moderate_content, manage_events
+├── Most page permissions (read:page.*, create:page.*, update:page.*)
+├── Event management (read:events, create:events, update:events)
 
 Member
-├── view_basic, view_details
+├── Basic page permissions (read:page.dashboard, read:page.users)
+├── Basic event access (read:events)
 
 Supporter
-├── view_basic
+├── Limited page permissions (read:page.dashboard)
+├── No event access
 ```
 
 ### Role-Based Permission Mapping
@@ -150,6 +154,15 @@ Permissions can be scoped to specific resources:
 
 ## Security Features
 
+### Database-First Architecture
+
+The RBAC system uses a **database-first architecture** where all permission logic resides in PostgreSQL functions:
+
+- **RPC Functions** - All permission checks use `get_rbac_permissions()` RPC function
+- **RLS Protection** - Direct table access is blocked by Row Level Security policies
+- **Elevated Privileges** - RPC functions run with elevated privileges to bypass RLS
+- **Single Source of Truth** - All permission logic centralized in database functions
+
 ### Permission Validation
 
 - **Runtime Checking** - Permissions are validated on every request

package/docs/documentation-style-checklist.md

@@ -20,7 +20,10 @@ Comprehensive checklist for maintaining consistent, high-quality documentation a
 // ✅ Good - Complete, runnable example
 import React, { useState } from 'react';
 import { DataTable, Button } from '@jmruthers/pace-core';
-import '@jmruthers/pace-core/styles/tokens';
+
+// Import the core CSS file (in your app's entry point)
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
 
 interface User {
   id: string;
@@ -119,7 +122,10 @@ function MyComponent() {
 // ✅ Good - Complete imports
 import React, { useState, useEffect } from 'react';
 import { DataTable, Button, useUnifiedAuth } from '@jmruthers/pace-core';
-import '@jmruthers/pace-core/styles/tokens';
+
+// Import the core CSS file (in your app's entry point)
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
 
 // ❌ Bad - Incomplete imports
 import { DataTable } from '@jmruthers/pace-core';

package/docs/examples/navigation-menu-auth-fix.md

@@ -0,0 +1,344 @@
+# NavigationMenu Authentication Fix Example
+
+This example shows how to fix the NavigationMenu authentication context issue reported in the bug report.
+
+## Problem
+
+The consuming app was getting `permissions: undefined`, `roles: undefined`, `accessLevel: undefined` in console logs from the NavigationMenu component.
+
+## Root Cause
+
+The NavigationMenu component was not properly connected to the authentication context from `useUnifiedAuth`.
+
+## Solution
+
+### 1. Updated NavigationMenu Component
+
+The NavigationMenu component now properly uses the authentication context:
+
+```tsx
+// packages/core/src/components/NavigationMenu/NavigationMenu.tsx
+import { useUnifiedAuth } from "../../providers/UnifiedAuthProvider";
+
+export const NavigationMenu = React.forwardRef<HTMLDivElement, NavigationMenuProps>(({ 
+  items, 
+  filterByPermissions = true,
+  auditLog = true,
+  ...props 
+}, ref) => {
+  // Get authentication context
+  const authContext = React.useMemo(() => {
+    try {
+      return useUnifiedAuth();
+    } catch (error) {
+      console.warn('[NavigationMenu] useUnifiedAuth not available, running in unauthenticated mode');
+      return null;
+    }
+  }, []);
+
+  // Filter navigation items based on permissions
+  const filteredItems = React.useMemo(() => {
+    if (!filterByPermissions || !authContext) return items;
+    
+    return items.filter(item => {
+      // Check permissions if available
+      if (item.permissions && item.permissions.length > 0) {
+        const hasPermission = item.permissions.some(permission => 
+          authContext.hasPermission(permission)
+        );
+        if (!hasPermission) return false;
+      }
+      
+      // Check roles if available
+      if (item.roles && item.roles.length > 0) {
+        const hasRole = item.roles.some(role => 
+          authContext.hasRole(role)
+        );
+        if (!hasRole) return false;
+      }
+      
+      return true;
+    });
+  }, [items, filterByPermissions, authContext]);
+
+  // Log navigation access attempts for debugging
+  React.useEffect(() => {
+    if (auditLog && authContext) {
+      console.log('[NavigationMenu] Navigation access attempt:', {
+        itemId: 'navigation-menu',
+        label: 'Navigation Menu',
+        href: currentPath,
+        permissions: authContext.permissions,
+        roles: authContext.roles,
+        accessLevel: authContext.accessLevel,
+        timestamp: new Date().toISOString()
+      });
+    }
+  }, [auditLog, authContext, currentPath]);
+
+  // ... rest of component
+});
+```
+
+### 2. Updated NavigationItem Type
+
+Navigation items now support permission requirements:
+
+```typescript
+interface NavigationItem {
+  id: string;
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavigationItem[];
+  isActive?: boolean;
+  permissions?: string[];
+  roles?: string[];
+  accessLevel?: string;
+  pageId?: string;
+  strictMode?: boolean;
+  meta?: {
+    title?: string;
+    description?: string;
+    hidden?: boolean;
+    order?: number;
+  };
+}
+```
+
+### 3. Correct App Structure
+
+The consuming app should use this structure:
+
+```tsx
+// App.tsx
+import React from 'react';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { 
+  UnifiedAuthProvider, 
+  OrganisationProvider, 
+  EventProvider,
+  PaceAppLayout 
+} from '@jmruthers/pace-core';
+import { supabase } from './integrations/supabase/client';
+import { AuthenticatedApp } from './AuthenticatedApp';
+
+function App() {
+  return (
+    <BrowserRouter>
+      <Routes>
+        <Route path="/*" element={
+          <UnifiedAuthProvider supabaseClient={supabase} appName="CAKE">
+            <OrganisationProvider>
+              <EventProvider>
+                <AuthenticatedApp />
+              </EventProvider>
+            </OrganisationProvider>
+          </UnifiedAuthProvider>
+        } />
+      </Routes>
+    </BrowserRouter>
+  );
+}
+
+export default App;
+```
+
+### 4. Updated AuthenticatedApp
+
+```tsx
+// AuthenticatedApp.tsx
+import React from 'react';
+import { Routes, Route } from 'react-router-dom';
+import { 
+  useUnifiedAuth, 
+  PaceAppLayout, 
+  NavigationItem, 
+  PaceLoginPage 
+} from "@jmruthers/pace-core";
+
+export function AuthenticatedApp() {
+  const { isAuthenticated, user, isLoading, accessLevel, roles } = useUnifiedAuth();
+
+  if (!isAuthenticated) {
+    return <PaceLoginPage appName="CAKE" />;
+  }
+
+  // Define navigation items with permission requirements
+  const navItems: NavigationItem[] = [
+    { 
+      id: 'meals', 
+      label: 'Meals', 
+      href: '/meals',
+      permissions: ['meals:read']
+    },
+    { 
+      id: 'dishes', 
+      label: 'Dishes', 
+      href: '/dishes',
+      permissions: ['dishes:read']
+    },
+    { 
+      id: 'items', 
+      label: 'Items', 
+      href: '/items',
+      permissions: ['items:read']
+    },
+    { 
+      id: 'diners', 
+      label: 'Diners', 
+      href: '/diners',
+      permissions: ['diners:read']
+    },
+    { 
+      id: 'menus', 
+      label: 'Menus', 
+      href: '/menus',
+      permissions: ['menus:read']
+    },
+    { 
+      id: 'distribution', 
+      label: 'Distribution', 
+      href: '/distribution',
+      permissions: ['distribution:read']
+    },
+    { 
+      id: 'suppliers', 
+      label: 'Suppliers', 
+      href: '/suppliers',
+      permissions: ['suppliers:read']
+    },
+  ];
+
+  return (
+    <PaceAppLayout 
+      key="main-layout"
+      appName="CAKE" 
+      navItems={navItems}
+      showEventSelector={true}
+    >
+      <Routes>
+        <Route index element={<div>Meals Page</div>} />
+        <Route path="meals" element={<div>Meals Page</div>} />
+        <Route path="dishes" element={<div>Dishes Page</div>} />
+        <Route path="items" element={<div>Items Page</div>} />
+        <Route path="diners" element={<div>Diners Page</div>} />
+        <Route path="menus" element={<div>Menus Page</div>} />
+        <Route path="distribution" element={<div>Distribution Page</div>} />
+        <Route path="suppliers" element={<div>Suppliers Page</div>} />
+        <Route path="*" element={<div>Not Found</div>} />
+      </Routes>
+    </PaceAppLayout>
+  );
+}
+```
+
+### 5. Alternative: Direct NavigationMenu Usage
+
+If you want to use NavigationMenu directly without PaceAppLayout:
+
+```tsx
+import { NavigationMenu } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function CustomNavigation() {
+  const { hasPermission, hasRole } = useUnifiedAuth();
+
+  const navItems: NavigationItem[] = [
+    { 
+      id: 'meals', 
+      label: 'Meals', 
+      href: '/meals',
+      permissions: ['meals:read']
+    },
+    { 
+      id: 'admin', 
+      label: 'Admin Panel', 
+      href: '/admin',
+      roles: ['admin', 'super_admin']
+    }
+  ];
+
+  return (
+    <NavigationMenu 
+      items={navItems}
+      currentPath={location.pathname}
+      onNavigate={(item) => navigate(item.href)}
+      buttonText="Menu"
+      filterByPermissions={true}
+      auditLog={true}
+    />
+  );
+}
+```
+
+## Expected Results
+
+After implementing this fix:
+
+1. **Console logs will show proper authentication context**:
+   ```javascript
+   [NavigationMenu] Navigation access attempt: {
+     itemId: "navigation-menu",
+     label: "Navigation Menu",
+     href: "/meals",
+     permissions: { "meals:read": true, "dishes:read": true },
+     roles: ["user", "admin"],
+     accessLevel: "super",
+     timestamp: "2025-10-06T04:38:15.2012"
+   }
+   ```
+
+2. **Navigation items will be filtered based on permissions**:
+   - Items with `permissions: ['meals:read']` will only show if user has that permission
+   - Items with `roles: ['admin']` will only show if user has that role
+
+3. **No more "useUnifiedAuth not available" warnings**
+
+## Testing
+
+To test the fix:
+
+1. **Check console logs**: Should show proper authentication context
+2. **Test permission filtering**: Remove permissions from user and verify items are hidden
+3. **Test role filtering**: Change user roles and verify admin items show/hide
+4. **Test audit logging**: Enable `auditLog={true}` and verify logs are generated
+
+## Migration Guide
+
+If you're updating from the old NavigationMenu:
+
+1. **Add permission requirements to navigation items**:
+   ```tsx
+   // Old way
+   const navItems = [
+     { id: 'meals', label: 'Meals', href: '/meals' }
+   ];
+
+   // New way
+   const navItems = [
+     { id: 'meals', label: 'Meals', href: '/meals', permissions: ['meals:read'] }
+   ];
+   ```
+
+2. **Enable permission filtering**:
+   ```tsx
+   <NavigationMenu 
+     items={navItems}
+     filterByPermissions={true}
+     auditLog={true}
+   />
+   ```
+
+3. **Ensure proper provider hierarchy**:
+   ```tsx
+   <UnifiedAuthProvider>
+     <OrganisationProvider>
+       <EventProvider>
+         <NavigationMenu items={navItems} />
+       </EventProvider>
+     </OrganisationProvider>
+   </UnifiedAuthProvider>
+   ```
+
+This fix resolves the authentication context issue and provides proper permission-based navigation filtering.