@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/migration/v0.4.17-source-path-fix.md

@@ -1,235 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# Migration Guide: v0.4.17 Source Path Fix
-
-This guide explains the critical fix in pace-core v0.4.17 that resolves the @source directive path issue.
-
-## 🎯 What's Fixed in v0.4.17
-
-**Issue**: The @source directives in `core.css` were using incorrect relative paths, preventing Tailwind v4 from scanning the pace-core source files.
-
-**Root Cause**: Since `core.css` is located in `src/styles/core.css`, the relative paths `./src/**/*.{js,ts,jsx,tsx}` were looking for `dist/src/` which doesn't exist.
-
-## ✅ The Fix
-
-### Before (v0.4.16 - Incorrect)
-```css
-/* @source directives for Tailwind v4 content scanning */
-@source "./src/**/*.{js,ts,jsx,tsx}";
-@source "./src/components/**/*.{js,ts,jsx,tsx}";
-@source "./src/providers/**/*.{js,ts,jsx,tsx}";
-@source "./src/hooks/**/*.{js,ts,jsx,tsx}";
-@source "./src/utils/**/*.{js,ts,jsx,tsx}";
-@source "./src/types/**/*.{js,ts,jsx,tsx}";
-@source "./src/validation/**/*.{js,ts,jsx,tsx}";
-@source "./src/rbac/**/*.{js,ts,jsx,tsx}";
-```
-
-### After (v0.4.17 - Correct)
-```css
-/* @source directives for Tailwind v4 content scanning */
-@source "../src/**/*.{js,ts,jsx,tsx}";
-@source "../src/components/**/*.{js,ts,jsx,tsx}";
-@source "../src/providers/**/*.{js,ts,jsx,tsx}";
-@source "../src/hooks/**/*.{js,ts,jsx,tsx}";
-@source "../src/utils/**/*.{js,ts,jsx,tsx}";
-@source "../src/types/**/*.{js,ts,jsx,tsx}";
-@source "../src/validation/**/*.{js,ts,jsx,tsx}";
-@source "../src/rbac/**/*.{js,ts,jsx,tsx}";
-```
-
-## 📁 File Structure Explanation
-
-```
-node_modules/@jmruthers/pace-core/
-├── dist/
-│   └── styles/
-│       └── core.css          ← @source directives are here
-├── src/                      ← Source files are here
-│   ├── components/
-│   ├── providers/
-│   ├── hooks/
-│   └── ...
-└── package.json
-```
-
-**Path Resolution**:
-- From `src/styles/core.css` to `src/` requires `../src/`
-- The `../` goes up one directory from `src/styles/` to `src/`
-- Then `src/` goes into the source directory
-
-## 🚀 Migration Steps
-
-### 1. Update pace-core
-
-```bash
-npm install @jmruthers/pace-core@latest
-```
-
-### 2. Verify the Fix
-
-Check that your CSS file size increases significantly:
-
-```bash
-# Before (v0.4.16) - ~21KB
-# After (v0.4.17) - 50-100+ KB
-ls -la dist/assets/*.css
-```
-
-### 3. Test Component Styling
-
-Create a test component to verify styling:
-
-```tsx
-// src/TestComponent.tsx
-import { Button, Card } from '@jmruthers/pace-core';
-
-export function TestComponent() {
-  return (
-    <div className="p-8 space-y-4">
-      <h1 className="text-2xl font-bold text-main-900">Path Fix Test</h1>
-      
-      <Card className="p-4 border border-main-300">
-        <h2 className="text-lg font-semibold text-sec-800 mb-2">
-          Component Styling Test
-        </h2>
-        <div className="space-y-2">
-          <Button 
-            variant="primary" 
-            className="bg-main-600 text-main-50 hover:bg-main-700"
-          >
-            Primary Button
-          </Button>
-          <Button 
-            variant="secondary" 
-            className="bg-sec-500 text-main-50 hover:bg-sec-600"
-          >
-            Secondary Button
-          </Button>
-          <div className="p-2 bg-acc-100 text-acc-800 rounded">
-            Accent colored div
-          </div>
-        </div>
-      </Card>
-    </div>
-  );
-}
-```
-
-**Expected Result**:
-- ✅ Proper PACE Core colors (main, sec, acc palettes)
-- ✅ Correct spacing and typography
-- ✅ Hover effects working
-- ✅ Component styling complete
-
-## 🔍 Verification Steps
-
-### 1. Check CSS Output Size
-
-```bash
-# Check CSS file size
-ls -la dist/assets/*.css
-```
-
-**Expected Results**:
-- ✅ **50-100+ kB** (with all utility classes)
-- ❌ **20-30 kB** (missing classes - indicates scanning issue)
-
-### 2. Count CSS Rules
-
-```bash
-# Count CSS rules (approximate)
-grep -c "\.bg-\|\.text-\|\.p-\|\.m-\|\.w-\|\.h-\|\.flex\|\.grid" dist/assets/*.css
-```
-
-**Expected Results**:
-- ✅ **800+ rules** (complete utility set)
-- ❌ **<300 rules** (incomplete - scanning issue)
-
-### 3. Check Browser Dev Tools
-
-Inspect elements to verify:
-1. **Open browser dev tools**
-2. **Inspect the test component**
-3. **Check computed styles** for:
-   - `background-color` values (should show PACE Core colors)
-   - `color` values (should show proper text colors)
-   - `padding`, `margin` values (should show proper spacing)
-
-## 📊 Before vs After
-
-| Aspect | v0.4.16 (Broken) | v0.4.17 (Fixed) |
-|--------|------------------|-----------------|
-| **@source paths** | `./src/**/*.{js,ts,jsx,tsx}` | `../src/**/*.{js,ts,jsx,tsx}` |
-| **Path resolution** | Looks for `dist/src/` (doesn't exist) | Looks for `src/` (correct) |
-| **CSS Rules** | ~292 rules | 800+ rules |
-| **File Size** | 20-30 kB | 50-100+ kB |
-| **Component Styling** | Incomplete | Complete |
-| **Colors** | Missing | Full palette |
-| **Spacing** | Limited | Complete |
-
-## 🎉 Success Indicators
-
-You'll know the fix was successful when:
-
-- ✅ **CSS file is 50-100+ kB**
-- ✅ **Components render with proper styling**
-- ✅ **PACE Core colors work** (`bg-main-600`, `text-sec-700`, etc.)
-- ✅ **Spacing and typography are correct**
-- ✅ **Hover effects and transitions work**
-- ✅ **No console errors about missing classes**
-
-## 🛠️ Troubleshooting
-
-### Issue: Still only 292 CSS rules
-
-**Possible Causes**:
-1. Using old package version
-2. Cached build files
-3. @source directives still not working
-
-**Solutions**:
-1. **Verify package version**:
-   ```bash
-   npm list @jmruthers/pace-core
-   # Should show v0.4.17+
-   ```
-
-2. **Clear all caches**:
-   ```bash
-   rm -rf dist .vite node_modules package-lock.json
-   npm install
-   npm run build
-   ```
-
-3. **Check @source directives**:
-   ```bash
-   # Verify correct paths in core.css
-   grep -n "@source" node_modules/@jmruthers/pace-core/src/styles/core.css
-   ```
-
-### Issue: Components still unstyled
-
-**Solution**:
-1. Verify CSS import: `import '@jmruthers/pace-core/src/styles/core.css'`
-2. Restart dev server after changes
-3. Check browser dev tools for missing classes
-
-## 📚 Additional Resources
-
-- [CSS-First Migration Guide](./v0.4.16-css-first-approach.md)
-- [Troubleshooting Guide](../troubleshooting/tailwind-content-scanning.md)
-- [Vite Configuration Guide](../consuming-app-vite-config.md)
-
-## 🆘 Need Help?
-
-If you're still experiencing issues after following this guide:
-
-1. **Check the troubleshooting guides** above
-2. **Verify your configuration** matches the examples
-3. **Test with a minimal example** to isolate the issue
-4. **Contact support** with specific error messages and configuration details

package/docs/rbac/RBAC_EVENT_CONTEXT_LOADING.md

@@ -1,222 +0,0 @@
-# RBAC Event Context Loading - How It Works
-
-## Overview
-
-For event-based apps (`requires_event: true`), RBAC waits for event context to be ready before loading permissions. This document explains how this works and answers common questions.
-
-## How RBAC Detects Event Context Availability
-
-### Automatic Detection via React Hooks
-
-RBAC uses React's dependency system to automatically detect when event context becomes available:
-
-1. **`useRBAC` hook watches event state**:
-   - `eventLoading` - boolean indicating if events are loading
-   - `selectedEvent` - the currently selected event object (or null)
-
-2. **`loadRBACContext` callback depends on event state**:
-   ```typescript
-   const loadRBACContext = useCallback(async () => {
-     // ... loading logic
-   }, [selectedEvent, eventLoading, ...other dependencies]);
-   ```
-
-3. **`useEffect` automatically re-runs when callback changes**:
-   ```typescript
-   useEffect(() => {
-     loadRBACContext();
-   }, [loadRBACContext]);
-   ```
-
-### Flow Diagram
-
-```
-1. Component mounts → useRBAC called
-2. loadRBACContext created (depends on eventLoading, selectedEvent)
-3. useEffect runs → calls loadRBACContext()
-4. If eventLoading=true OR selectedEvent=null:
-   → Log: "Waiting for event context"
-   → Set isLoading=true
-   → Return early (don't load RBAC)
-5. When eventLoading changes to false AND selectedEvent becomes available:
-   → loadRBACContext callback is recreated (dependency changed)
-   → useEffect detects callback changed → re-runs
-   → loadRBACContext() called again
-   → This time: eventLoading=false AND selectedEvent exists
-   → Proceeds to load RBAC context
-   → Log: "Loading RBAC context"
-   → Log: "RBAC context loaded successfully"
-```
-
-## Should You See the "Waiting for Event Context" Log?
-
-**Yes, you should see this log** when:
-- App has `requires_event: true`
-- Event context is loading (`eventLoading: true`) OR no event selected (`selectedEvent: null`)
-
-**Log level**: `INFO` (should be visible in console)
-
-**Log message**:
-```
-[useRBAC] Waiting for event context before loading RBAC context
-```
-
-**If you don't see this log**, it might mean:
-1. App doesn't have `requires_event: true` configured
-2. Event context loads too quickly (race condition)
-3. Log level is set too high (unlikely, as it's INFO level)
-
-## Is RBAC Loading Automatic?
-
-**Yes, RBAC loading is completely automatic**. You don't need to call anything explicitly.
-
-### How It Works Automatically
-
-1. **`useRBAC` hook is called automatically** when:
-   - Component using RBAC mounts (e.g., `NavigationMenu`, `PagePermissionGuard`)
-   - Or when you explicitly call `useRBAC()` in a component
-
-2. **React's dependency system triggers re-runs**:
-   - When `eventLoading` changes from `true` → `false`
-   - When `selectedEvent` changes from `null` → object
-   - The `loadRBACContext` callback is recreated
-   - The `useEffect` detects the change and re-runs
-   - RBAC context loads automatically
-
-### What You Need to Do
-
-**Nothing!** Just ensure:
-- ✅ `setupRBAC(supabase)` is called in your app initialization
-- ✅ `UnifiedAuthProvider` has `appConfig={{ requires_event: true }}` for event-based apps
-- ✅ `EventProvider` is wrapping your app (for event-based apps)
-- ✅ Event context is loading correctly
-
-## How to Manually Trigger RBAC Loading (For Testing)
-
-### Option 1: Force Re-render
-
-If you need to manually trigger RBAC loading for testing:
-
-```typescript
-import { useRBAC } from '@jmruthers/pace-core/rbac';
-
-function TestComponent() {
-  const { isLoading, error, permissionMap } = useRBAC();
-  const [forceReload, setForceReload] = useState(0);
-  
-  const manualReload = () => {
-    setForceReload(prev => prev + 1);
-    // This will cause useRBAC to re-run
-  };
-  
-  return (
-    <div>
-      <button onClick={manualReload}>Reload RBAC</button>
-      <div>Loading: {isLoading ? 'Yes' : 'No'}</div>
-      <div>Permissions: {Object.keys(permissionMap).length}</div>
-    </div>
-  );
-}
-```
-
-### Option 2: Call RPC Directly (Advanced)
-
-For debugging, you can call the RPC function directly:
-
-```typescript
-import { getEngine } from '@jmruthers/pace-core/rbac';
-
-async function testRBAC() {
-  const engine = getEngine();
-  
-  // Test app resolution
-  const appContext = await engine.resolveAppContext({
-    userId: 'your-user-id',
-    appName: 'TRAC'
-  });
-  console.log('App context:', appContext);
-  
-  // Test permission map
-  const permissionMap = await engine.getPermissionMap({
-    userId: 'your-user-id',
-    scope: {
-      organisationId: 'your-org-id',
-      eventId: 'your-event-id',
-      appId: appContext?.appId
-    }
-  });
-  console.log('Permission map:', permissionMap);
-}
-```
-
-### Option 3: Check Console Logs
-
-The fix includes detailed logging:
-
-1. **When waiting**: `[useRBAC] Waiting for event context before loading RBAC context`
-2. **When loading**: `[useRBAC] Loading RBAC context`
-3. **When successful**: `[useRBAC] RBAC context loaded successfully` (with permission count)
-
-## Troubleshooting
-
-### RBAC Not Loading After Event Context Ready
-
-**Symptoms**:
-- Event context loads (`eventLoading: false`, `selectedEvent` set)
-- No RBAC loading logs appear
-- Permission map remains empty
-
-**Check**:
-1. ✅ Verify `appConfig={{ requires_event: true }}` in `UnifiedAuthProvider`
-2. ✅ Verify database has `requires_event: true` for your app
-3. ✅ Check console for "Waiting for event context" log (should appear first)
-4. ✅ Check console for "Loading RBAC context" log (should appear after event ready)
-5. ✅ Verify `selectedEvent` is actually set (not null)
-6. ✅ Verify `eventLoading` is actually `false` (not `true`)
-
-**If still not working**:
-- Check browser console for any errors
-- Verify `setupRBAC(supabase)` was called
-- Check that `useRBAC` hook is being called somewhere (NavigationMenu calls it automatically)
-
-### Logs Not Appearing
-
-**If you don't see any logs**:
-1. Check log level - logs are `INFO` level, should be visible
-2. Check browser console filter settings
-3. Verify RBAC logger is configured correctly
-
-### Permission Map Still Empty
-
-**If permission map is empty after RBAC loads**:
-1. Check "RBAC context loaded successfully" log - what's the `permissionCount`?
-2. If `permissionCount: 0`, check:
-   - User has event-app role assigned
-   - Permissions exist for that role in database
-   - Event ID matches the selected event
-   - Organisation ID matches user's organisation
-
-## Expected Console Log Sequence
-
-For event-based apps, you should see this sequence:
-
-```
-1. [RBAC INFO] RBAC system initialized successfully
-2. [useRBAC] Waiting for event context before loading RBAC context
-   { eventLoading: true, hasSelectedEvent: false, appName: "TRAC" }
-3. [useRBAC] Loading RBAC context
-   { appName: "TRAC", requiresEvent: true, hasSelectedEvent: true, ... }
-4. [useRBAC] RBAC context loaded successfully
-   { appName: "TRAC", permissionCount: 32, ... }
-```
-
-## Summary
-
-- ✅ **RBAC detection is automatic** - React hooks handle it
-- ✅ **You should see "Waiting" log** - when event is loading
-- ✅ **RBAC loads automatically** - when event context becomes ready
-- ✅ **No manual triggering needed** - but you can force re-render for testing
-- ✅ **Detailed logs included** - to help debug issues
-
-The fix ensures RBAC waits for event context before loading, preventing NetworkError and ensuring permissions load correctly for event-based apps.
-

package/docs/rbac/RBAC_LOGIN_SAFETY_FIX.md

@@ -1,95 +0,0 @@
-# RBAC Login Safety Fix - v0.5.148
-
-## Problem
-
-After RBAC changes, users reported login failures. Investigation revealed:
-1. **CORS error** - Network/infrastructure issue (separate from RBAC)
-2. **Potential hook errors** - `useOrganisations()` might throw when called before authentication
-
-## Root Cause
-
-`useRBAC` hook calls `useOrganisations()` unconditionally (required by React hooks rules). If `useOrganisations()` throws an error when there's no authenticated user, it could break the login flow.
-
-## Fix Applied
-
-Wrapped `useOrganisations()` call in try-catch, similar to how `useEvents()` is handled:
-
-```typescript
-// Safely get organisation context - may not be available during login
-let selectedOrganisation: { id: string } | null = null;
-let orgContextReady = false;
-let orgLoading = false;
-try {
-  const orgContext = useOrganisations();
-  selectedOrganisation = orgContext.selectedOrganisation;
-  orgContextReady = orgContext.isContextReady;
-  orgLoading = orgContext.isLoading;
-} catch (error) {
-  // Organisation provider not available or user not authenticated - this is OK
-  logger.debug('[useRBAC] Organisation provider not available, continuing without organisation context', error);
-}
-```
-
-## Safety Guarantees
-
-1. ✅ **`useRBAC` never throws** - All hook calls are wrapped in try-catch
-2. ✅ **Safe during login** - Returns empty state when unauthenticated
-3. ✅ **Early returns** - Exits immediately if no user/session
-4. ✅ **No logging noise** - Only logs when authenticated
-5. ✅ **No network calls** - Doesn't make RPC calls when unauthenticated
-
-## Verification
-
-### When Unauthenticated:
-- `useRBAC` returns safely with empty state
-- No errors thrown
-- No network calls made
-- Login flow proceeds normally
-
-### When Authenticated:
-- `useRBAC` loads organisation context
-- Waits for organisation context before loading RBAC
-- Loads permissions correctly
-
-## CORS Error (Separate Issue)
-
-The CORS error is **NOT caused by RBAC**. It's a network/infrastructure issue:
-
-```
-Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource 
-at https://srqhjwivpohjcjqikjry.supabase.co/auth/v1/token?grant_type=password
-```
-
-### To Fix CORS:
-1. Check Supabase Dashboard → Settings → API → CORS
-2. Add `localhost:8087` to allowed origins
-3. Or use wildcard `*` for development
-4. Check network/proxy settings
-5. Verify browser isn't blocking requests
-
-## Testing
-
-1. **Before login**:
-   - Open browser console
-   - Navigate to login page
-   - Verify no RBAC errors
-   - Verify login form displays
-
-2. **During login**:
-   - Enter credentials
-   - Click login
-   - Verify no RBAC errors in console
-   - If CORS error appears, it's a Supabase config issue (not RBAC)
-
-3. **After login**:
-   - Verify RBAC loads correctly
-   - Check console for RBAC loading logs
-   - Verify permissions load
-
-## Summary
-
-- ✅ **RBAC is now safe** - Wrapped in try-catch, won't break login
-- ✅ **No interference** - Early returns prevent any action when unauthenticated
-- ⚠️ **CORS is separate** - Infrastructure issue, needs Supabase config fix
-- ✅ **Ready for testing** - Should work correctly now
-

package/docs/rbac/RBAC_V0.5.147_FIX.md

@@ -1,117 +0,0 @@
-# RBAC v0.5.147 Fix - Event Context Loading
-
-## Problem
-
-RBAC wasn't loading for event-based apps because:
-1. **Logger filtering**: Critical logs were using `logger.info()` but RBAC logger defaults to `logLevel: 'warn'`, so logs were filtered out
-2. **Missing dependencies**: `appConfig` wasn't in `loadRBACContext` dependencies, so callback wasn't recreated when appConfig changed
-3. **No visibility**: No way to verify if `useRBAC` hook was being called
-
-## Fixes Applied
-
-### 1. Changed Log Levels to `warn`
-
-All critical logs now use `logger.warn()` instead of `logger.info()` so they're always visible:
-
-- `[useRBAC] Hook initialized` - Shows when hook is called
-- `[useRBAC] Waiting for event context before loading RBAC context` - Shows when waiting
-- `[useRBAC] Loading RBAC context` - Shows when loading starts
-- `[useRBAC] RBAC context loaded successfully` - Shows when loading completes
-
-### 2. Added Direct Console Logging
-
-Added direct `console.warn()` at hook initialization as a fallback to ensure visibility:
-
-```typescript
-console.warn('[useRBAC] Hook initialized (direct log)', hookInitLog);
-```
-
-This ensures logs are visible even if logger configuration is incorrect.
-
-### 3. Added `appConfig` to Dependencies
-
-Added `appConfig` to `loadRBACContext` callback dependencies so it recreates when appConfig changes:
-
-```typescript
-}, [appName, logger, resetState, selectedEvent, selectedEvent?.event_id, selectedOrganisation?.id, session, user, requiresEvent, eventLoading, appConfig]);
-```
-
-### 4. Improved `requiresEvent` Logic
-
-Changed default behavior when `appConfig` is `null`:
-
-```typescript
-// If appConfig is null initially, default to true (safer for event-based apps)
-const requiresEvent = appConfig?.requires_event ?? (appConfig === null ? true : false);
-```
-
-This prevents premature loading when appConfig hasn't loaded yet.
-
-### 5. Added useEffect Logging
-
-Added logging in `useEffect` to track when it runs:
-
-```typescript
-useEffect(() => {
-  logger.warn('[useRBAC] useEffect triggered - calling loadRBACContext', { ... });
-  loadRBACContext();
-}, [loadRBACContext, appName, requiresEvent, eventLoading, selectedEvent, user, session]);
-```
-
-### 6. Added Explicit useEffect Dependencies
-
-Added explicit dependencies to `useEffect` so it re-runs when event context changes:
-
-```typescript
-}, [loadRBACContext, appName, requiresEvent, eventLoading, selectedEvent, user, session]);
-```
-
-## Expected Console Logs
-
-After this fix, you should see this sequence:
-
-```
-1. [useRBAC] Hook initialized (direct log)
-   { appName: "TRAC", requiresEvent: true, ... }
-
-2. [useRBAC] useEffect triggered - calling loadRBACContext
-   { appName: "TRAC", requiresEvent: true, eventLoading: true, ... }
-
-3. [useRBAC] Waiting for event context before loading RBAC context
-   { eventLoading: true, hasSelectedEvent: false, appName: "TRAC" }
-
-4. [useRBAC] useEffect triggered - calling loadRBACContext
-   { appName: "TRAC", requiresEvent: true, eventLoading: false, hasSelectedEvent: true, ... }
-
-5. [useRBAC] Loading RBAC context
-   { appName: "TRAC", requiresEvent: true, hasSelectedEvent: true, ... }
-
-6. [useRBAC] RBAC context loaded successfully
-   { appName: "TRAC", permissionCount: 32, ... }
-```
-
-## Debugging Steps
-
-If you still don't see logs:
-
-1. **Check if hook is called**: Look for `[useRBAC] Hook initialized (direct log)` - this uses direct `console.warn()` so it should always appear
-2. **Check if effect runs**: Look for `[useRBAC] useEffect triggered` - this shows when the effect runs
-3. **Check event context**: Verify `eventLoading: false` and `hasSelectedEvent: true` in logs
-4. **Check appConfig**: Verify `appConfig` is not `null` and `requiresEvent: true` in logs
-
-## Testing
-
-To test the fix:
-
-1. Clear browser cache
-2. Restart dev server
-3. Open browser console
-4. Navigate to app
-5. Look for the log sequence above
-
-## Related Issues
-
-- Fixes: RBAC not loading for event-based apps
-- Related: NavigationMenu empty when `filterNavigationByPermissions={true}`
-- Related: RBAC logs not appearing
-