@jmruthers/pace-core 0.5.184 → 0.5.185

package/docs/rbac/getting-started.md

@@ -37,37 +37,112 @@ const supabase = createClient(
 setupRBAC(supabase);
 ```
 
-### 3. Wrap Your App with Required Providers
+### 3. Configure Vite (CRITICAL)
+
+**⚠️ CRITICAL**: Without this configuration, you'll get React context and Router context errors.
+
+Add to your `vite.config.ts`:
+
+```typescript
+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({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+    // CRITICAL: Dedupe React and React Router to ensure single instances
+    dedupe: ['react', 'react-dom', 'react-router-dom']
+  },
+  // CRITICAL: Exclude pace-core from pre-bundling to prevent React context mismatches
+  optimizeDeps: {
+    include: [
+      'react',
+      'react-dom',
+      'react/jsx-runtime'
+    ],
+    exclude: ['@jmruthers/pace-core', 'react-router-dom']
+  },
+});
+```
+
+### 4. Wrap Your App with Required Providers
+
+**⚠️ CRITICAL**: Provider nesting order matters! Follow this exact structure.
 
 ```tsx
-// App.tsx - COMPLETE setup (copy this exactly)
+// src/main.tsx - COMPLETE setup (copy this exactly)
 import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { setupRBAC } from '@jmruthers/pace-core/rbac';
 import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
 import { createClient } from '@supabase/supabase-js';
+import App from './App';
+
+// Import CSS
+import '@jmruthers/pace-core/src/styles/core.css';
 
 // Initialize Supabase
 const supabase = createClient(
-  process.env.REACT_APP_SUPABASE_URL!,
-  process.env.REACT_APP_SUPABASE_ANON_KEY!
+  import.meta.env.VITE_SUPABASE_URL!,
+  import.meta.env.VITE_SUPABASE_ANON_KEY!
 );
 
-// ⚠️ REQUIRED: Setup RBAC first
+// ⚠️ REQUIRED: Setup RBAC before rendering
 setupRBAC(supabase);
 
-function App() {
-  return (
-    <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
-      <OrganisationProvider>
-        <YourAppContent />
-      </OrganisationProvider>
-    </UnifiedAuthProvider>
-  );
-}
-
-export default App;
+const queryClient = new QueryClient();
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    {/* CRITICAL: Correct nesting order */}
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <UnifiedAuthProvider 
+          supabaseClient={supabase} 
+          appName="My App"
+          idleTimeoutMs={30 * 60 * 1000}
+          warnBeforeMs={5 * 60 * 1000}
+          onIdleLogout={() => window.location.href = '/login'}
+        >
+          <OrganisationProvider>
+            <App />
+          </OrganisationProvider>
+        </UnifiedAuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  </React.StrictMode>
+);
 ```
 
+**Provider Nesting Order (CRITICAL):**
+1. `React.StrictMode` (outermost)
+2. `QueryClientProvider`
+3. `BrowserRouter`
+4. `UnifiedAuthProvider`
+5. `OrganisationProvider`
+6. `App` (innermost)
+
+**Why this order matters:**
+- `BrowserRouter` must wrap `UnifiedAuthProvider` to provide Router context
+- `UnifiedAuthProvider` must be inside `BrowserRouter` to use Router hooks
+- Wrong nesting causes "useNavigate() may be used only in the context of a <Router>" errors
+- Missing Vite config causes "useUnifiedAuth must be used within a UnifiedAuthProvider" errors
+
 ## 🎯 **When to Use What Pattern**
 
 ### Pattern 1: PagePermissionGuard (REQUIRED for Pages)
@@ -170,33 +245,46 @@ function UserActions() {
 Here's a complete, working example that demonstrates all patterns:
 
 ```tsx
-// App.tsx - COMPLETE setup
+// src/main.tsx - COMPLETE setup
 import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import { setupRBAC } from '@jmruthers/pace-core/rbac';
 import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
 import { createClient } from '@supabase/supabase-js';
-import { Dashboard } from './components/Dashboard';
+import App from './App';
 
 // Initialize Supabase
 const supabase = createClient(
-  process.env.REACT_APP_SUPABASE_URL!,
-  process.env.REACT_APP_SUPABASE_ANON_KEY!
+  import.meta.env.VITE_SUPABASE_URL!,
+  import.meta.env.VITE_SUPABASE_ANON_KEY!
 );
 
-// ⚠️ REQUIRED: Setup RBAC first
+// ⚠️ REQUIRED: Setup RBAC before rendering
 setupRBAC(supabase);
 
-function App() {
-  return (
-    <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
-      <OrganisationProvider>
-        <Dashboard />
-      </OrganisationProvider>
-    </UnifiedAuthProvider>
-  );
-}
-
-export default App;
+const queryClient = new QueryClient();
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <UnifiedAuthProvider 
+          supabaseClient={supabase} 
+          appName="My App"
+          idleTimeoutMs={30 * 60 * 1000}
+          warnBeforeMs={5 * 60 * 1000}
+          onIdleLogout={() => window.location.href = '/login'}
+        >
+          <OrganisationProvider>
+            <App />
+          </OrganisationProvider>
+        </UnifiedAuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  </React.StrictMode>
+);
 ```
 
 ```tsx
@@ -471,10 +559,47 @@ setupRBAC(supabase);
 **Cause**: OrganisationProvider not wrapping your app or user not in any organisation
 
 **Solution**:
-1. Ensure OrganisationProvider wraps your app
+1. Ensure OrganisationProvider wraps your app (inside UnifiedAuthProvider)
 2. Check that user has organisation memberships in the database
 3. Verify user has selected an organisation
 
+### Error: "useUnifiedAuth must be used within a UnifiedAuthProvider"
+
+**Cause**: Vite is pre-bundling `@jmruthers/pace-core`, creating separate React instances
+
+**Solution**:
+1. Add to `vite.config.ts`:
+   ```typescript
+   optimizeDeps: {
+     exclude: ['@jmruthers/pace-core', 'react-router-dom']
+   }
+   ```
+2. Clear Vite cache: `rm -rf node_modules/.vite`
+3. Restart dev server
+
+### Error: "useNavigate() may be used only in the context of a <Router> component"
+
+**Cause**: Incorrect provider nesting - BrowserRouter should wrap UnifiedAuthProvider
+
+**Solution**:
+1. Ensure correct nesting order:
+   ```tsx
+   <BrowserRouter>
+     <UnifiedAuthProvider>
+       <OrganisationProvider>
+         <App />
+       </OrganisationProvider>
+     </UnifiedAuthProvider>
+   </BrowserRouter>
+   ```
+2. Do NOT put BrowserRouter inside UnifiedAuthProvider
+3. Add to `vite.config.ts`:
+   ```typescript
+   resolve: {
+     dedupe: ['react', 'react-dom', 'react-router-dom']
+   }
+   ```
+
 ### Error: Permission checks always return false
 
 **Cause**: User doesn't have proper roles or permissions assigned

package/docs/standards/pace-core-compliance.md

@@ -0,0 +1,432 @@
+# pace-core Compliance Enforcement
+
+This guide explains how to enforce pace-core usage patterns in consuming apps to ensure consistent design, reduce duplication, and maintain high code quality.
+
+## Overview
+
+pace-core provides a comprehensive enforcement system that includes:
+
+1. **ESLint Rules** - Real-time linting during development
+2. **Static Analysis Script** - Comprehensive codebase scanning
+3. **ESLint Config Preset** - Easy setup for consuming apps
+
+## Quick Start
+
+### Option 1: ESLint Config Preset (Recommended)
+
+The easiest way to enable compliance checking is to use the shareable ESLint config. The config is CommonJS but works with both ES module and CommonJS ESLint configs:
+
+**For ES Module ESLint Config (eslint.config.js):**
+```javascript
+// eslint.config.js (ES modules)
+import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
+
+export default [
+  ...paceCoreConfig,
+  // your other config
+];
+```
+
+**For CommonJS ESLint Config (.eslintrc.js or eslint.config.cjs):**
+```javascript
+// eslint.config.cjs (CommonJS)
+const paceCoreConfig = require('@jmruthers/pace-core/eslint-config');
+
+module.exports = [
+  ...paceCoreConfig,
+  // your other config
+];
+```
+
+### Option 2: Manual ESLint Rules Setup
+
+If you prefer more control, you can import the rules directly. Note: The rules are CommonJS, so use `createRequire` in ES modules:
+
+**For ES Module ESLint Config:**
+```javascript
+// eslint.config.js
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const paceCoreRules = require('@jmruthers/pace-core/eslint-rules').rules;
+
+export default [
+  {
+    plugins: {
+      'pace-core-compliance': {
+        rules: paceCoreRules
+      }
+    },
+    rules: {
+      'pace-core-compliance/no-restricted-imports': 'error',
+      'pace-core-compliance/prefer-pace-core-components': 'warn',
+      'pace-core-compliance/prefer-pace-core-hooks': 'warn',
+      'pace-core-compliance/prefer-pace-core-utils': 'warn',
+      'pace-core-compliance/no-local-component-duplication': 'error'
+    }
+  }
+];
+```
+
+**For CommonJS ESLint Config:**
+```javascript
+// eslint.config.cjs
+const paceCoreRules = require('@jmruthers/pace-core/eslint-rules').rules;
+
+module.exports = [
+  {
+    plugins: {
+      'pace-core-compliance': {
+        rules: paceCoreRules
+      }
+    },
+    rules: {
+      'pace-core-compliance/no-restricted-imports': 'error',
+      'pace-core-compliance/prefer-pace-core-components': 'warn',
+      'pace-core-compliance/prefer-pace-core-hooks': 'warn',
+      'pace-core-compliance/prefer-pace-core-utils': 'warn',
+      'pace-core-compliance/no-local-component-duplication': 'error'
+    }
+  }
+];
+```
+
+## ESLint Rules
+
+### no-restricted-imports
+
+**Severity**: Error
+
+Blocks direct imports of libraries that pace-core wraps and standardizes.
+
+**Restricted Libraries**:
+- `@radix-ui/*` - All Radix UI packages (use pace-core components instead)
+- `lucide-react` - Icons (use pace-core components that include icons)
+- `react-day-picker` - Use `Calendar` from pace-core
+- `@tanstack/react-table` - Use `DataTable` from pace-core
+- `react-hook-form` - Use `Form` and `useZodForm` from pace-core
+- `zod` - Use validation utilities from pace-core
+
+**Example Violation**:
+```typescript
+// ❌ Bad
+import { Dialog } from '@radix-ui/react-dialog';
+import { Button } from 'lucide-react';
+
+// ✅ Good
+import { Dialog } from '@jmruthers/pace-core';
+import { Button } from '@jmruthers/pace-core';
+```
+
+### prefer-pace-core-components
+
+**Severity**: Warning
+
+Suggests using pace-core components instead of native HTML elements.
+
+**Detected Patterns**:
+- `<button>` → Use `Button` from pace-core
+- `<input>` → Use `Input` from pace-core
+- `<textarea>` → Use `Textarea` from pace-core
+- `<label>` → Use `Label` from pace-core
+
+**Example**:
+```tsx
+// ⚠️ Warning
+<button onClick={handleClick}>Click me</button>
+
+// ✅ Recommended
+import { Button } from '@jmruthers/pace-core';
+<Button onClick={handleClick}>Click me</Button>
+```
+
+### prefer-pace-core-hooks
+
+**Severity**: Warning
+
+Detects custom hooks that duplicate pace-core functionality.
+
+**Common Patterns Detected**:
+- `useToast`, `useNotification` → Use `useToast` from pace-core
+- `useDebounce`, `useDebounced` → Use `useDebounce` from pace-core
+- `useAuth`, `useAuthentication` → Use `useUnifiedAuth` from pace-core
+- `useForm`, `useZodForm` → Use `useZodForm` from pace-core
+
+**Example**:
+```typescript
+// ⚠️ Warning
+function useToast() {
+  // custom implementation
+}
+
+// ✅ Recommended
+import { useToast } from '@jmruthers/pace-core';
+```
+
+### prefer-pace-core-utils
+
+**Severity**: Warning
+
+Detects utility functions that duplicate pace-core functionality.
+
+**Common Patterns Detected**:
+- `formatDate`, `dateFormat` → Use `formatDate` from pace-core
+- `formatCurrency`, `formatMoney` → Use `formatCurrency` from pace-core
+- `cn`, `classNames`, `clsx` → Use `cn` from pace-core
+- `validate`, `validateInput` → Use `validateUserInput` from pace-core
+
+**Example**:
+```typescript
+// ⚠️ Warning
+function formatDate(date: Date): string {
+  // custom implementation
+}
+
+// ✅ Recommended
+import { formatDate } from '@jmruthers/pace-core';
+```
+
+### no-local-component-duplication
+
+**Severity**: Error
+
+Prevents creating local components with names matching pace-core components.
+
+**Example Violation**:
+```
+// ❌ Error: components/Button.tsx
+export function Button() { ... }
+
+// pace-core already provides Button component
+```
+
+**Fix**: Remove the local component and import from pace-core:
+```typescript
+import { Button } from '@jmruthers/pace-core';
+```
+
+## Static Analysis Script
+
+The static analysis script provides a comprehensive scan of your codebase and generates a detailed compliance report.
+
+### Running the Script
+
+```bash
+# From your consuming app root
+node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+```
+
+Or add it to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "check:pace-core": "node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs"
+  }
+}
+```
+
+### What It Checks
+
+1. **Restricted Imports** - Scans for direct imports of wrapped libraries
+2. **Duplicate Components** - Finds local components matching pace-core names
+3. **Duplicate Hooks** - Finds local hooks matching pace-core hooks
+4. **Duplicate Utils** - Finds local utils matching pace-core utils
+5. **Suggestions** - Recommends pace-core alternatives for native HTML elements
+
+### Report Output
+
+The script generates a color-coded terminal report showing:
+
+- ❌ **Errors** - Critical violations that must be fixed
+- ⚠️ **Warnings** - Issues that should be addressed
+- 💡 **Suggestions** - Recommendations for improvement
+- ✅ **Summary** - Overall compliance status
+
+Example output:
+```
+═══════════════════════════════════════════════════════════
+  pace-core Compliance Report
+═══════════════════════════════════════════════════════════
+
+❌ Restricted Imports Found: 3
+
+  • src/components/CustomDialog.tsx:5
+    Import: @radix-ui/react-dialog
+    Reason: Use Dialog component from pace-core instead
+
+Summary:
+  Total Issues: 3
+  - Restricted Imports: 3
+  - Duplicate Components/Hooks/Utils: 0
+  - Suggestions: 0
+```
+
+## Best Practices
+
+### 1. Always Import from pace-core
+
+```typescript
+// ✅ Good
+import { Button, Card, Dialog } from '@jmruthers/pace-core';
+import { useToast, useDebounce } from '@jmruthers/pace-core';
+import { formatDate, formatCurrency } from '@jmruthers/pace-core';
+```
+
+### 2. Use pace-core Components for UI
+
+Avoid native HTML elements when pace-core provides a component:
+
+```tsx
+// ❌ Avoid
+<button className="btn">Click</button>
+
+// ✅ Use pace-core
+<Button>Click</Button>
+```
+
+### 3. Leverage pace-core Hooks
+
+Don't recreate hooks that pace-core already provides:
+
+```typescript
+// ❌ Avoid
+const [debouncedValue, setDebouncedValue] = useState(value);
+useEffect(() => {
+  const timer = setTimeout(() => setDebouncedValue(value), 500);
+  return () => clearTimeout(timer);
+}, [value]);
+
+// ✅ Use pace-core
+import { useDebounce } from '@jmruthers/pace-core';
+const debouncedValue = useDebounce(value, 500);
+```
+
+### 4. Use pace-core Utilities
+
+Leverage formatting, validation, and other utilities from pace-core:
+
+```typescript
+// ❌ Avoid
+const formatted = new Intl.DateTimeFormat('en-US').format(date);
+
+// ✅ Use pace-core
+import { formatDate } from '@jmruthers/pace-core';
+const formatted = formatDate(date);
+```
+
+### 5. Check Before Creating New Components
+
+Before creating a new component, check if pace-core already provides it:
+
+1. Review the [pace-core documentation](https://github.com/your-org/pace-core)
+2. Check `core-usage-manifest.json` for available components
+3. Search pace-core exports
+
+## Troubleshooting
+
+### ESLint Rules Not Working
+
+1. **Verify plugin is loaded**: Check that the config is imported correctly:
+   ```javascript
+   // In your eslint.config.js, add temporarily:
+   import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
+   console.log('Config:', paceCoreConfig);
+   console.log('Has plugins:', paceCoreConfig[0]?.plugins);
+   ```
+
+2. **Check rule names**: Rules must be prefixed with `pace-core-compliance/`
+
+3. **Verify manifest exists**: Rules load from `core-usage-manifest.json` in the pace-core package
+
+4. **CommonJS/ES Module issues**: If you're using ES modules and rules aren't loading:
+   - Ensure you're using the config preset (Option 1) which handles this automatically
+   - Or use `createRequire` when importing rules directly (Option 2)
+
+5. **Verify rules are available**: Check that the rules file exists:
+   ```bash
+   ls node_modules/@jmruthers/pace-core/dist/eslint-rules/pace-core-compliance.cjs
+   ```
+
+### Static Analysis Script Errors
+
+1. **Manifest not found**: Ensure `core-usage-manifest.json` exists in pace-core package
+2. **No files scanned**: Check that you're running from the project root
+3. **Permission errors**: Ensure script has read access to source files
+
+### False Positives
+
+If you encounter false positives:
+
+1. **Component name conflicts**: If you have a legitimate reason to create a local component with a pace-core name, consider:
+   - Renaming your component
+   - Using a namespace/prefix
+   - Documenting why pace-core doesn't meet your needs
+
+2. **Hook/Util patterns**: The pattern matching may flag similar names. Review the suggestion and decide if migration makes sense.
+
+## Integration with CI/CD
+
+While CI/CD integration is not included in the initial release, you can easily add it:
+
+```yaml
+# .github/workflows/pace-core-compliance.yml
+name: pace-core Compliance
+
+on: [push, pull_request]
+
+jobs:
+  compliance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npm run check:pace-core
+      - run: npm run lint
+```
+
+## Verification
+
+After setting up the ESLint config, verify it's working:
+
+1. **Check ESLint can load the config**:
+   ```bash
+   npx eslint --print-config src/App.tsx
+   ```
+   Look for `pace-core-compliance` in the plugins section.
+
+2. **Test with a violation**: Create a test file that imports a restricted library:
+   ```typescript
+   // test-violation.ts
+   import { Dialog } from '@radix-ui/react-dialog'; // Should trigger error
+   ```
+   Run ESLint and verify it reports the violation.
+
+3. **Run static analysis**: Use the compliance script to get a full report:
+   ```bash
+   npm run check:pace-core
+   ```
+
+## Getting Help
+
+- **Documentation**: See [pace-core docs](../README.md)
+- **Issues**: Report false positives or rule issues
+- **Manifest**: Check `core-usage-manifest.json` for available exports
+- **ESLint Config**: The config file is at `@jmruthers/pace-core/eslint-config` (CommonJS)
+- **ESLint Rules**: The rules are at `@jmruthers/pace-core/eslint-rules` (CommonJS)
+
+## File Locations
+
+When installed in a consuming app, the compliance tools are available at:
+
+- **ESLint Config**: `node_modules/@jmruthers/pace-core/eslint-config-pace-core.cjs`
+- **ESLint Rules**: `node_modules/@jmruthers/pace-core/dist/eslint-rules/pace-core-compliance.cjs`
+- **Static Analysis Script**: `node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs`
+- **Manifest**: `node_modules/@jmruthers/pace-core/core-usage-manifest.json`
+
+## Related Documentation
+
+- [Component Standards](./03-component-standard.md)
+- [API & RPC Standards](./02-api-and-rpc-standard.md)
+- [Getting Started Guide](../getting-started/README.md)
+