@jmruthers/pace-core 0.5.180 → 0.5.182

package/docs/troubleshooting/react-hooks-issue-analysis.md

@@ -1,172 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# React Hooks Issue Analysis - pace-cake Team
-
-## 🐛 Issue Summary
-**Error**: "Rendered more hooks than during the previous render" in MenuModal component when using DataTable from pace-core.
-
-## 🔍 Root Cause Analysis
-
-### ✅ **pace-core DataTable is Clean**
-After thorough analysis of the pace-core DataTable component and related hooks, I can confirm that **this is NOT a bug in pace-core**. The DataTable component follows proper React hooks rules:
-
-- **No early returns** before hooks
-- **No conditional hooks** - all hooks are called unconditionally  
-- **Consistent hook order** - hooks are always called in the same sequence
-- **Proper hook dependencies** - all hooks have stable dependencies
-
-### ❌ **The Problem is in pace-cake's Pattern**
-
-The consuming app is using this **problematic pattern**:
-
-```typescript
-// ❌ WRONG - Early return before hooks
-export const MenuModal = ({ isOpen, onClose, unit, eventId }: MenuModalProps) => {
-  // This early return causes the hooks error
-  if (!isOpen || !unit?.unit_id || !eventId) {
-    return null;
-  }
-
-  const { selectedOrganisation } = useOrganisations(); // Hook called after early return
-  const { mealplans, isLoading, ... } = useMealplanData(unit.unit_id, eventId);
-  
-  return <DataTable ... />;
-};
-```
-
-## 🚨 **Why This Causes the Error**
-
-1. **First render**: `isOpen = false` → early return → **0 hooks called**
-2. **Second render**: `isOpen = true` → no early return → **2+ hooks called**  
-3. **React detects**: "Rendered more hooks than during the previous render" ❌
-
-This violates the fundamental React hooks rule: **hooks must always be called in the same order on every render**.
-
-## ✅ **The Correct Pattern**
-
-```typescript
-// ✅ CORRECT - Hooks before any conditional logic
-export const MenuModal = ({ isOpen, onClose, unit, eventId }: MenuModalProps) => {
-  // Always call hooks first, regardless of conditions
-  const { selectedOrganisation } = useOrganisations();
-  const { mealplans, isLoading, ... } = useMealplanData(unit?.unit_id, eventId);
-  
-  // Then do conditional rendering
-  if (!isOpen || !unit?.unit_id || !eventId) {
-    return null;
-  }
-  
-  return (
-    <Dialog open={isOpen} onOpenChange={onClose}>
-      <DialogContent>
-        <DataTable
-          data={mealplans}
-          columns={columns}
-          // ... other props
-        />
-      </DialogContent>
-    </Dialog>
-  );
-};
-```
-
-## 🛠️ **Alternative Solutions**
-
-### **Option 1: Conditional Hook Parameters**
-```typescript
-// Pass safe defaults to hooks
-const { mealplans, isLoading } = useMealplanData(
-  unit?.unit_id || '', 
-  eventId || ''
-);
-
-// Handle empty data in the hook or component
-if (!unit?.unit_id || !eventId) {
-  return null;
-}
-```
-
-### **Option 2: Wrapper Component Pattern**
-```typescript
-const MenuModalContent = ({ unit, eventId, onClose }) => {
-  // All hooks here - no early returns
-  const { selectedOrganisation } = useOrganisations();
-  const { mealplans, isLoading } = useMealplanData(unit.unit_id, eventId);
-  
-  return (
-    <DialogContent>
-      <DataTable data={mealplans} columns={columns} />
-    </DialogContent>
-  );
-};
-
-export const MenuModal = ({ isOpen, onClose, unit, eventId }) => {
-  if (!isOpen || !unit?.unit_id || !eventId) {
-    return null;
-  }
-  
-  return (
-    <Dialog open={isOpen} onOpenChange={onClose}>
-      <MenuModalContent unit={unit} eventId={eventId} onClose={onClose} />
-    </Dialog>
-  );
-};
-```
-
-## 📋 **Recommended Fix for pace-cake**
-
-**Update the MenuModal component by moving all hooks before any conditional logic:**
-
-```typescript
-export const MenuModal = ({ isOpen, onClose, unit, eventId }: MenuModalProps) => {
-  // ✅ Move hooks to the top - before any early returns
-  const { selectedOrganisation } = useOrganisations();
-  const { mealplans, isLoading, ... } = useMealplanData(unit?.unit_id, eventId);
-  
-  // ✅ Then do conditional rendering
-  if (!isOpen || !unit?.unit_id || !eventId) {
-    return null;
-  }
-
-  return (
-    <Dialog open={isOpen} onOpenChange={onClose}>
-      <DialogContent>
-        <DataTable
-          data={mealplans}
-          columns={columns}
-          // ... other props
-        />
-      </DialogContent>
-    </Dialog>
-  );
-};
-```
-
-## 🎯 **Key Points**
-
-- **Not a pace-core bug** - DataTable follows proper React hooks rules
-- **Consuming app issue** - early return before hooks violates React rules  
-- **Simple fix** - move hooks before conditional logic
-- **This is a common React pattern mistake** - not specific to DataTable
-
-## 📚 **React Hooks Rules Reference**
-
-1. **Only call hooks at the top level** - Don't call hooks inside loops, conditions, or nested functions
-2. **Only call hooks from React functions** - Don't call hooks from regular JavaScript functions
-3. **Call hooks in the same order every time** - This is what's being violated in the current code
-
-## 🔗 **Additional Resources**
-
-- [React Hooks Rules](https://reactjs.org/docs/hooks-rules.html)
-- [React Hooks FAQ](https://reactjs.org/docs/hooks-faq.html)
-- [Common Hooks Mistakes](https://reactjs.org/docs/hooks-faq.html#what-can-i-do-if-my-effect-dependencies-change-too-often)
-
----
-
-**Status**: ✅ **Resolved** - This is a consuming app pattern issue, not a pace-core bug.  
-**Action Required**: Update MenuModal component to call hooks before conditional logic.  
-**Priority**: High - This is blocking feature implementation.

package/docs/troubleshooting/tailwind-content-scanning.md

@@ -1,219 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# Tailwind v4 Content Scanning Solutions
-
-This guide provides comprehensive solutions for Tailwind v4 content scanning issues with pace-core components.
-
-## 🚨 The Core Problem
-
-Tailwind v4 needs to scan source files to detect utility classes, but published packages only contain compiled JavaScript. This results in:
-
-- ❌ Only ~292 CSS rules instead of 987+ needed
-- ❌ Missing component styles
-- ❌ Severely compromised UI
-
-## ✅ Solution 1: Use Source Files (Recommended)
-
-Pace-core v0.4.15+ includes source files in the published package for Tailwind scanning.
-
-### Updated Vite Configuration
-
-```typescript
-// 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: [
-        // Your app's source files
-        './src/**/*.{js,ts,jsx,tsx}',
-        // Pace-core source files (NEW)
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-### Alternative: PostCSS Configuration
-
-```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: [],
-}
-```
-
-## ✅ Solution 2: Pre-built CSS (Fallback)
-
-If source file scanning doesn't work, use the pre-built CSS approach:
-
-### 1. Import Pre-built CSS
-
-```tsx
-// src/main.tsx
-import '@jmruthers/pace-core/src/styles/core.css';
-// Don't import your own Tailwind CSS
-```
-
-### 2. Disable Tailwind in Your App
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-// Don't include tailwindcss plugin
-
-export default defineConfig({
-  plugins: [react()],
-})
-```
-
-## ✅ Solution 3: Hybrid Approach
-
-Use both approaches for maximum compatibility:
-
-### 1. Vite Configuration
-
-```typescript
-// 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/src/**/*.{js,ts,jsx,tsx}',
-        // Fallback: also scan dist files
-        './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-### 2. CSS Import
-
-```tsx
-// src/main.tsx
-import '@jmruthers/pace-core/src/styles/core.css';
-```
-
-## 🔍 Verification Steps
-
-### 1. Check CSS Output Size
-
-After building, your CSS should be:
-- **Expected**: 50-100+ kB (with all utility classes)
-- **Problem**: 20-30 kB (missing classes)
-
-### 2. Verify Component Styling
-
-Test with a simple 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>
-  );
-}
-```
-
-**Expected Result**: Properly styled components with PACE Core colors and spacing.
-
-### 3. Check Browser Dev Tools
-
-Inspect elements to verify:
-- ✅ `bg-main-600` class is applied
-- ✅ `text-main-50` class is applied
-- ✅ Component has proper padding and styling
-
-## 🛠️ Troubleshooting
-
-### Issue: Source files not found
-
-**Error**: `Cannot resolve './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'`
-
-**Solution**: Ensure you're using pace-core v0.4.15+ which includes source files.
-
-### Issue: Still only 292 rules
-
-**Possible Causes**:
-1. Using old package version
-2. Incorrect content paths
-3. Cached build files
-
-**Solutions**:
-1. Update to latest pace-core: `npm install @jmruthers/pace-core@latest`
-2. Clear node_modules and reinstall: `rm -rf node_modules package-lock.json && npm install`
-3. Clear build cache: `rm -rf dist .vite`
-
-### Issue: Build errors with source files
-
-**Error**: TypeScript errors when scanning source files
-
-**Solution**: Add TypeScript configuration for node_modules:
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "skipLibCheck": true
-  },
-  "include": [
-    "src/**/*",
-    "node_modules/@jmruthers/pace-core/src/**/*"
-  ]
-}
-```
-
-## 📊 Expected Results
-
-With proper configuration, you should see:
-
-- **CSS file size**: 50-100+ kB
-- **Utility classes**: 800+ rules
-- **Component styling**: Full PACE Core design system
-- **Colors working**: `bg-main-600`, `text-sec-700`, etc.
-- **Spacing working**: `p-4`, `m-2`, `space-y-4`, etc.
-
-## 🆘 Still Having Issues?
-
-If none of these solutions work:
-
-1. **Check package version**: `npm list @jmruthers/pace-core`
-2. **Verify source files**: Check if `node_modules/@jmruthers/pace-core/src/` exists
-3. **Try pre-built CSS**: Use Solution 2 as a fallback
-4. **Contact support**: This may be a deeper compatibility issue
-
-## 📚 Related Documentation
-
-- [Installation Guide](../getting-started/installation.md)
-- [Vite Configuration](../consuming-app-vite-config.md)
-- [Troubleshooting Guide](./styling-issues.md)

package/examples/RBAC/EventBasedApp.tsx

@@ -1,239 +0,0 @@
-/**
- * Event-Based App Example
- * @package @jmruthers/pace-core
- * @module Examples/RBAC/EventBasedApp
- * @since 1.0.0
- * 
- * This example demonstrates how to build an event-based app using the RBAC system.
- */
-
-import React from 'react';
-import { 
-  PermissionEnforcer, 
-  PagePermissionGuard, 
-  NavigationGuard,
-  useCan 
-} from '../../src/rbac';
-import { useUnifiedAuth } from '../../src/providers';
-import type { Permission } from '../../src/rbac/types';
-
-// Example navigation items for an event-based app
-const navigationItems = [
-  {
-    id: 'dashboard',
-    name: 'Dashboard',
-    label: 'Dashboard',
-    path: '/event/dashboard',
-    permissions: ['read:events'] as Permission[],
-  },
-  {
-    id: 'participants',
-    name: 'Participants',
-    label: 'Participants',
-    path: '/event/participants',
-    permissions: ['read:participants'] as Permission[],
-  },
-  {
-    id: 'settings',
-    name: 'Settings',
-    label: 'Settings',
-    path: '/event/settings',
-    permissions: ['read:events', 'create:events', 'update:events', 'delete:events'] as Permission[],
-  },
-];
-
-// Example event dashboard component
-function EventDashboard() {
-  const { user, selectedEventId } = useUnifiedAuth();
-  
-  return (
-    <div className="event-dashboard">
-      <h1>Event Dashboard</h1>
-      <p>Event ID: {selectedEventId}</p>
-      
-      {/* Example of using useCan hook with event context */}
-      <PermissionEnforcer
-        permissions={['read:events']}
-        operation="dashboard"
-      >
-        <div className="dashboard-content">
-          <h2>Event Overview</h2>
-          <p>Welcome to the event dashboard!</p>
-        </div>
-      </PermissionEnforcer>
-      
-      {/* Example of conditional rendering based on permissions */}
-      <PermissionEnforcer
-        permissions={['read:events', 'create:events', 'update:events', 'delete:events']}
-        operation="event-management"
-      >
-        <div className="admin-controls">
-          <h3>Admin Controls</h3>
-          <button>Edit Event</button>
-          <button>Delete Event</button>
-        </div>
-      </PermissionEnforcer>
-    </div>
-  );
-}
-
-// Example participants page component
-function ParticipantsPage() {
-  return (
-    <PagePermissionGuard
-      pageName="participants"
-      operation="read"
-    >
-      <div className="participants-page">
-        <h1>Participants</h1>
-        <p>Manage event participants here.</p>
-        
-        <PermissionEnforcer
-          permissions={['create:participants']}
-          operation="add-participant"
-        >
-          <button>Add Participant</button>
-        </PermissionEnforcer>
-        
-        <PermissionEnforcer
-          permissions={['delete:participants']}
-          operation="remove-participant"
-        >
-          <button>Remove Participant</button>
-        </PermissionEnforcer>
-      </div>
-    </PagePermissionGuard>
-  );
-}
-
-// Example settings page component
-function SettingsPage() {
-  return (
-    <PagePermissionGuard
-      pageName="settings"
-      operation="read"
-    >
-      <div className="settings-page">
-        <h1>Event Settings</h1>
-        <p>Configure event settings here.</p>
-        
-        <PermissionEnforcer
-          permissions={['update:events']}
-          operation="update-settings"
-        >
-          <form>
-            <label>
-              Event Name:
-              <input type="text" />
-            </label>
-            <button type="submit">Save Changes</button>
-          </form>
-        </PermissionEnforcer>
-      </div>
-    </PagePermissionGuard>
-  );
-}
-
-// Example navigation component
-function EventNavigation() {
-  return (
-    <nav className="event-navigation">
-      <ul>
-        {navigationItems.map(item => (
-          <li key={item.id}>
-            <NavigationGuard
-              navigationItem={item}
-              fallback={<span className="disabled">{item.name}</span>}
-            >
-              <a href={item.path}>{item.name}</a>
-            </NavigationGuard>
-          </li>
-        ))}
-      </ul>
-    </nav>
-  );
-}
-
-// Example main app component
-export function EventBasedApp() {
-  const { selectedEventId, user } = useUnifiedAuth();
-  
-  // Show loading state if no event is selected
-  if (!selectedEventId) {
-    return (
-      <div className="event-app">
-        <h1>Event-Based App</h1>
-        <p>Please select an event to continue.</p>
-      </div>
-    );
-  }
-  
-  // Show loading state if no user is authenticated
-  if (!user) {
-    return (
-      <div className="event-app">
-        <h1>Event-Based App</h1>
-        <p>Please log in to continue.</p>
-      </div>
-    );
-  }
-  
-  return (
-    <div className="event-app">
-      <header>
-        <h1>Event-Based App</h1>
-        <p>User: {user.email}</p>
-        <p>Event: {selectedEventId}</p>
-      </header>
-      
-      <EventNavigation />
-      
-      <main>
-        <EventDashboard />
-        <ParticipantsPage />
-        <SettingsPage />
-      </main>
-    </div>
-  );
-}
-
-// Example of using the app with different permission scenarios
-export function EventBasedAppWithCustomScope() {
-  const { user } = useUnifiedAuth();
-  
-  // Example of providing explicit scope
-  const customScope = {
-    eventId: 'event-123',
-    appId: 'app-456'
-  };
-  
-  return (
-    <div className="event-app">
-      <h1>Event-Based App with Custom Scope</h1>
-      
-      <PermissionEnforcer
-        scope={customScope}
-        permissions={['read:events']}
-        operation="custom-scope-example"
-      >
-        <div>
-          <p>This content is shown when the user has read:events permission</p>
-          <p>for event-123 in app-456.</p>
-        </div>
-      </PermissionEnforcer>
-      
-      <PermissionEnforcer
-        scope={customScope}
-        permissions={['read:events', 'create:events', 'update:events', 'delete:events']}
-        operation="admin-example"
-        fallback={<p>You don't have admin permissions for this event.</p>}
-      >
-        <div>
-          <p>This content is shown when the user has events permissions</p>
-          <p>for event-123 in app-456.</p>
-        </div>
-      </PermissionEnforcer>
-    </div>
-  );
-}
-