@jmruthers/pace-core 0.5.193 → 0.6.2

package/docs/migration/V0.6.0_REACT_19_MIGRATION.md

@@ -0,0 +1,227 @@
+---
+lastUpdated: 2025-01-28T00:00:00+11:00
+version: 0.5.193
+reviewedBy: react-19-upgrade
+---
+
+# React 19 Migration Guide
+
+This guide documents the React 19 upgrade for `@jmruthers/pace-core` and provides migration instructions for consuming apps.
+
+## Overview
+
+PACE Core has been upgraded from React 18.3.1 to React 19.2.3, including the React Compiler for automatic optimizations. This upgrade provides improved performance, better type safety, and new features.
+
+## What Changed
+
+### Core Upgrades
+
+- **React**: `^18.3.1` → `^19.2.3`
+- **React DOM**: `^18.3.1` → `^19.2.3`
+- **@types/react**: `^18.3.17` → `^19.2.7`
+- **@types/react-dom**: `^18.3.5` → `^19.2.3`
+- **@vitejs/plugin-react**: `^4.5.1` → `^5.1.2`
+- **React Compiler**: Added `babel-plugin-react-compiler@^1.0.0`
+
+### React Compiler
+
+The React Compiler is now configured in pace-core's build setup. It automatically optimizes React components by:
+- Automatically memoizing components and values
+- Reducing the need for manual `useMemo` and `useCallback`
+- Optimizing re-renders based on actual dependencies
+
+## Breaking Changes
+
+### TypeScript Type Stricter
+
+React 19 has stricter TypeScript types. The main change affects accessing `child.props` in React elements:
+
+**Before (React 18)**:
+```tsx
+React.Children.map(children, (child) => {
+  if (React.isValidElement(child)) {
+    const variant = child.props.variant; // Works
+  }
+});
+```
+
+**After (React 19)**:
+```tsx
+React.Children.map(children, (child) => {
+  if (React.isValidElement(child)) {
+    const props = child.props as { variant?: string; [key: string]: unknown };
+    const variant = props.variant; // Type-safe
+  }
+});
+```
+
+### Error Handling
+
+React 19 changes how errors are handled:
+- Errors during render are no longer re-thrown
+- Uncaught errors are reported to `window.reportError`
+- Error boundaries continue to work as before
+
+### StrictMode Behavior
+
+React 19 StrictMode changes:
+- `useMemo` and `useCallback` reuse results from first render during second render
+- Ref callbacks are double-invoked on initial mount
+
+## Migration Steps for Consuming Apps
+
+### Step 1: Update React Dependencies
+
+```bash
+npm install react@^19.2.3 react-dom@^19.2.3
+npm install -D @types/react@^19.2.7 @types/react-dom@^19.2.3
+```
+
+### Step 2: Update Vite Plugin
+
+```bash
+npm install -D @vitejs/plugin-react@^5.1.2
+```
+
+### Step 3: Install React Compiler (Recommended)
+
+```bash
+npm install -D babel-plugin-react-compiler@latest
+```
+
+### Step 4: Configure React Compiler in Vite
+
+Update your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+    tailwindcss()
+  ],
+  // ... rest of config
+})
+```
+
+### Step 5: Update TypeScript Types
+
+If you have custom components that access `child.props`, update them:
+
+```tsx
+// Before
+const props = child.props;
+
+// After
+const props = child.props as { [key: string]: unknown };
+// Or with specific types
+const props = child.props as { variant?: string; size?: string; [key: string]: unknown };
+```
+
+### Step 6: Test Your Application
+
+1. Run your test suite
+2. Check for TypeScript errors
+3. Verify components render correctly
+4. Test error boundaries
+5. Use React DevTools to verify React Compiler is working (look for "Memo ✨" badge)
+
+## React Compiler Benefits
+
+The React Compiler automatically:
+- Memoizes components that don't need to re-render
+- Optimizes `useMemo` and `useCallback` usage
+- Reduces unnecessary re-renders
+- Improves performance without manual optimization
+
+### When to Keep Manual Optimizations
+
+You can still use manual `useMemo`/`useCallback` for:
+- Complex dependencies that the compiler can't analyze
+- Performance-critical code where you want explicit control
+- Cases where the compiler optimization doesn't match your needs
+
+The compiler will work alongside your manual optimizations.
+
+## Verification
+
+### Check React Compiler is Working
+
+1. Install React DevTools browser extension
+2. Open your app in development mode
+3. Open React DevTools
+4. Look for components with "Memo ✨" badge - these are optimized by the compiler
+
+### Build Verification
+
+```bash
+# Type checking
+npm run type-check
+
+# Build
+npm run build
+
+# Tests
+npm run test
+```
+
+## Troubleshooting
+
+### TypeScript Errors with child.props
+
+If you see errors like `'child.props' is of type 'unknown'`, add type assertions:
+
+```tsx
+const props = child.props as { [key: string]: unknown };
+```
+
+### React Compiler Not Working
+
+1. Verify `babel-plugin-react-compiler` is installed
+2. Check `vite.config.ts` has the compiler configured
+3. Restart your dev server
+4. Check React DevTools for "Memo ✨" badges
+
+### Test Failures
+
+If tests fail after upgrading:
+1. Update `@testing-library/react` to latest version
+2. Check for StrictMode-related test issues
+3. Verify error boundaries still work correctly
+
+## Rollback Plan
+
+If you encounter issues:
+
+1. **Disable React Compiler**: Remove from `vite.config.ts`:
+   ```typescript
+   react() // Remove babel config
+   ```
+
+2. **Downgrade React**: Temporarily downgrade to React 18.3.1 if needed
+3. **Report Issues**: Open an issue with details about the problem
+
+## Additional Resources
+
+- [React 19 Upgrade Guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide)
+- [React Compiler Documentation](https://react.dev/learn/react-compiler)
+- [PACE Core Installation Guide](../getting-started/installation-guide.md)
+
+## Support
+
+If you encounter issues migrating to React 19:
+1. Check this guide first
+2. Review [Troubleshooting](../troubleshooting/README.md)
+3. Open an issue on GitHub with:
+   - Package version
+   - React version
+   - Error messages
+   - Migration attempt details
+

package/docs/migration/database-changes-december-2025.md

@@ -427,7 +427,7 @@ const { data: files } = await supabase
 
 **Migration:** `20251205211120_migrate_profiles_to_person_scoped.sql` + related migrations  
 **Date:** 2025-12-05  
-**Documentation:** See [Person-Scoped Profiles Migration Guide](./person-scoped-profiles-migration-guide.md)
+**Documentation:** See [Person-Scoped Profiles Migration Guide](./V0.5.190_person-scoped-profiles-migration-guide.md)
 
 ### Quick Summary
 
@@ -501,7 +501,7 @@ const { data } = await supabase
 - [ ] Update `pace_contact` queries to use `person_id` instead of `member_id`
 - [ ] Update profile creation logic (no `organisation_id` needed)
 - [ ] Review profile access patterns (person-scoped, not org-scoped)
-- [ ] See [Person-Scoped Profiles Migration Guide](./person-scoped-profiles-migration-guide.md) for detailed checklist
+- [ ] See [Person-Scoped Profiles Migration Guide](./V0.5.190_person-scoped-profiles-migration-guide.md) for detailed checklist
 
 ### Phase 3: Testing
 
@@ -708,7 +708,7 @@ All migration files are located in:
 
 ### Documentation
 
-- [Person-Scoped Profiles Migration Guide](./person-scoped-profiles-migration-guide.md)
+- [Person-Scoped Profiles Migration Guide](./V0.5.190_person-scoped-profiles-migration-guide.md)
 - [API & RPC Standard](../standards/02-api-and-rpc-standard.md)
 - [Database Schema Requirements](../architecture/database-schema-requirements.md)
 

package/docs/rbac/event-based-apps.md

@@ -973,7 +973,7 @@ VALUES (
 - **[API Reference](./api-reference.md)** - Complete API documentation
 - **[Examples](./examples.md)** - More complex usage patterns
 - **[Troubleshooting](./troubleshooting.md)** - Advanced troubleshooting
-- **[Migration Guide](../migration/rbac-migration.md)** - If migrating from legacy RBAC
+- **[Migration Guide](../migration/V0.4.0_rbac-migration.md)** - If migrating from legacy RBAC
 
 ## 🆘 Still Having Issues?
 

package/docs/rbac/getting-started.md

@@ -843,7 +843,7 @@ function AdaptiveComponent({ appId }) {
 - [Examples](./examples.md) - More complex examples
 - [Event-Based Apps](./event-based-apps.md) - Guide for event-based applications
 - [Troubleshooting](./troubleshooting.md) - Common issues and solutions
-- [Migration Guide](../migration/rbac-migration.md) - Migrating from legacy RBAC
+- [Migration Guide](../migration/V0.4.0_rbac-migration.md) - Migrating from legacy RBAC
 
 ## ♿ Accessibility
 

package/docs/rbac/quick-start.md

@@ -740,7 +740,7 @@ The system will automatically resolve the organisation ID from the event context
 - **[API Reference](./api-reference.md)** - Complete API documentation
 - **[Examples](./examples.md)** - More complex usage patterns
 - **[Troubleshooting](./troubleshooting.md)** - Advanced troubleshooting
-- **[Migration Guide](../migration/rbac-migration.md)** - If migrating from legacy RBAC
+- **[Migration Guide](../migration/V0.4.0_rbac-migration.md)** - If migrating from legacy RBAC
 
 ## 🆘 Still Having Issues?
 

package/docs/standards/README.md

@@ -33,3 +33,43 @@ This document is the single source of truth for all engineering standards for pa
 - Apply Cursor Checklists
 - Prefer pace-core for reusable logic
 - Update docs on API changes
+
+## Cursor Rules
+
+pace-core provides comprehensive Cursor rules that automatically enforce these standards in consuming apps.
+
+### Installation
+
+Install cursor rules in your consuming app:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+```
+
+### Rule Files
+
+The cursor rules cover:
+- **00-pace-core-compliance** - Enforce pace-core usage patterns
+- **01-standards-compliance** - Enforce all standards (this document)
+- **02-project-structure** - Define standard folder structure
+- **03-solid-principles** - Enforce SOLID architecture
+- **04-testing-standards** - Enforce testing consistency
+- **05-bug-reports-and-features** - Templates for issue reporting
+- **06-code-quality** - Enforce code quality standards
+- **07-tech-stack-compliance** - Enforce tech stack versions
+- **08-markup-quality** - Enforce clean markup standards, semantic HTML usage, and pace-core component patterns
+
+### Audit Tool
+
+Run comprehensive audits to check compliance:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/audit-consuming-app.cjs
+```
+
+This generates timestamped markdown reports in `audit/` directory.
+
+### Documentation
+
+- [Cursor Rules Quick Start](../getting-started/cursor-rules.md)
+- [Cursor Rules README](../../cursor-rules/README.md)

package/docs/troubleshooting/migration.md

@@ -506,8 +506,8 @@ export default defineConfig({
     
     // New dependencies
     "@jmruthers/pace-core": "^2.0.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "@supabase/supabase-js": "^2.38.0",
     "zod": "^3.22.0"
   },
@@ -517,8 +517,8 @@ export default defineConfig({
     "@types/react-dom": "^17.0.0",
     
     // New dev dependencies
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^4.0.0",
     "vite": "^4.4.0",
     "typescript": "^5.0.0"

package/examples/PublicPages/PublicEventPage.tsx

@@ -23,7 +23,7 @@
  * ```
  *
  * @dependencies
- * - React 18+ - Component framework
+ * - React 19+ - Component framework
  * - React Router - Routing
  * - Public pages components - Layout and data access
  * - Tailwind CSS - Styling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.193",
+  "version": "0.6.2",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {
@@ -71,6 +71,10 @@
     "./docs": "./docs/README.md",
     "./package.json": "./package.json",
     "./core-usage-manifest.json": "./core-usage-manifest.json",
+    "./cursor-rules": "./cursor-rules",
+    "./scripts/install-cursor-rules": "./scripts/install-cursor-rules.cjs",
+    "./scripts/audit": "./scripts/audit/index.cjs",
+    "./scripts/audit-consuming-app": "./scripts/audit-consuming-app.cjs",
     "./source": {
       "import": "./src/index.ts",
       "default": "./src/index.ts"
@@ -138,7 +142,8 @@
     "docs",
     "core-usage-manifest.json",
     "eslint-config-pace-core.cjs",
-    "scripts"
+    "scripts",
+    "cursor-rules"
   ],
   "scripts": {
     "_comment_build": "Build package and documentation",
@@ -207,9 +212,9 @@
     "@tanstack/react-table": "^8.0.0",
     "clsx": "^2.0.0",
     "lucide-react": "^0.400.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0",
+    "react": "^19.0.0",
     "react-day-picker": "^9.0.0",
+    "react-dom": "^19.0.0",
     "react-hook-form": "^7.0.0",
     "react-router-dom": "^6.0.0",
     "tailwind-merge": "^2.0.0",
@@ -222,8 +227,8 @@
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",
     "@types/papaparse": "^5.3.16",
-    "@types/react": "^18.3.17",
-    "@types/react-dom": "^18.3.5",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "@types/react-window": "^1.8.8",
     "@vitejs/plugin-react": "^4.5.1",
     "@vitest/coverage-v8": "^3.2.3",
@@ -236,6 +241,7 @@
     "typedoc": "^0.25.13",
     "typedoc-plugin-markdown": "^3.17.1",
     "typedoc-plugin-merge-modules": "^5.1.0",
+    "tsup": "^8.5.0",
     "typescript": "^5.4.0",
     "typescript-eslint": "^8.39.0",
     "vite": "^6.0.3"

package/scripts/audit/core/checks/accessibility.cjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+/**
+ * Accessibility Check Module
+ * @package @jmruthers/pace-core
+ * @module Audit/Checks/Accessibility
+ * 
+ * Checks for:
+ * - Missing aria-* attributes
+ * - Missing keyboard navigation
+ * - Missing focus management
+ * - Missing alt text on images
+ */
+
+const fs = require('fs');
+const { getRelativePath, getLineNumber } = require('../utils.cjs');
+
+const accessibilityCheck = {
+  name: 'accessibility',
+  description: 'Accessibility checks (aria attributes, keyboard navigation, alt text)',
+  severity: 'warning',
+  
+  async run(context) {
+    const { projectRoot, files } = context;
+    const issues = [];
+    const warnings = [];
+    const suggestions = [];
+    
+    if (!files || files.length === 0) {
+      return { issues, warnings, suggestions };
+    }
+    
+    for (const filePath of files) {
+      try {
+        // Only check React component files
+        if (!filePath.match(/\.(tsx|jsx)$/)) {
+          continue;
+        }
+        
+        const content = fs.readFileSync(filePath, 'utf8');
+        const relativePath = getRelativePath(filePath, projectRoot);
+        const normalizedPath = relativePath.replace(/\\/g, '/');
+        
+        // Skip root-level src directory - in pace-core repository, this is a demo/showcase app
+        // Note: We DO check packages/core/ files because accessibility issues (missing alt attributes, missing form labels) are real issues that should be fixed
+        const isRootSrc = normalizedPath.startsWith('src/') && !normalizedPath.includes('packages/');
+        if (isRootSrc) {
+          continue; // Skip demo app files
+        }
+        
+        // Skip scripts directory - utility scripts don't need accessibility validation
+        const isScript = normalizedPath.startsWith('scripts/') || normalizedPath.includes('/scripts/');
+        if (isScript) {
+          continue; // Skip script files
+        }
+        
+        // Skip pace-core library components and examples - these are designed to accept accessibility props
+        // Library components accept id, aria-label, etc. via props spread
+        // Examples are demonstration code, not production code
+        const isPaceCorePackage = normalizedPath.includes('packages/core/') || normalizedPath.startsWith('packages/core/');
+        const isExample = normalizedPath.includes('/examples/');
+        const isLibraryComponent = isPaceCorePackage && !isExample;
+        
+        // Check for images without alt text
+        // Skip library components - they accept alt as a prop
+        if (!isLibraryComponent) {
+          const imgPattern = /<img[^>]*>/g;
+          let imgMatch;
+          while ((imgMatch = imgPattern.exec(content)) !== null) {
+            const imgTag = imgMatch[0];
+            // Check for alt attribute, including React props (alt=, alt =, alt={)
+            const hasAlt = imgTag.includes('alt=') || imgTag.includes('alt =') || imgTag.includes('alt={');
+            if (!hasAlt) {
+              warnings.push({
+                type: 'missing-alt-text',
+                file: relativePath,
+                line: getLineNumber(content, imgMatch.index),
+                message: 'Image element missing alt attribute',
+                recommendation: 'Add alt text to all images for accessibility: <img alt="description" ... />'
+              });
+            }
+          }
+        }
+        
+        // Check for buttons/clickable elements without aria-label or accessible text
+        const buttonPattern = /<(button|a|div)\s+[^>]*(onClick|role=["']button["'])[^>]*>/g;
+        let buttonMatch;
+        while ((buttonMatch = buttonPattern.exec(content)) !== null) {
+          const buttonTag = buttonMatch[0];
+          const hasAriaLabel = buttonTag.includes('aria-label=') || buttonTag.includes('ariaLabel=');
+          const hasAccessibleText = buttonTag.includes('>') && content.substring(buttonMatch.index).match(/<[^>]*>([^<]+)</);
+          
+          if (!hasAriaLabel && !hasAccessibleText) {
+            warnings.push({
+              type: 'missing-aria-label',
+              file: relativePath,
+              line: getLineNumber(content, buttonMatch.index),
+              message: 'Interactive element missing accessible label',
+              recommendation: 'Add aria-label or ensure element contains accessible text content'
+            });
+          }
+        }
+        
+        // Check for form inputs without labels
+        // Skip library components - they accept id, aria-label, etc. via props spread
+        // Skip examples - they're demonstration code
+        if (!isLibraryComponent && !isExample) {
+          const inputPattern = /<input[^>]*>/g;
+          let inputMatch;
+          while ((inputMatch = inputPattern.exec(content)) !== null) {
+            // Get the full input tag including multi-line attributes
+            const inputStart = inputMatch.index;
+            const afterInput = content.substring(inputStart, Math.min(content.length, inputStart + 500));
+            const inputTagEnd = afterInput.indexOf('>');
+            const fullInputTag = inputTagEnd !== -1 ? afterInput.substring(0, inputTagEnd + 1) : inputMatch[0];
+            
+            // Check for id (including React props)
+            const hasId = /id=["']([^"']+)["']|id=\{/.test(fullInputTag);
+            // Check for aria-label (including React props)
+            const hasAriaLabel = /aria-label=["']|ariaLabel=|aria-label=\{/.test(fullInputTag);
+            
+            if (hasId) {
+              const idMatch = fullInputTag.match(/id=["']([^"']+)["']/);
+              if (idMatch) {
+                const id = idMatch[1];
+                // Check if there's a corresponding label
+                const beforeInput = content.substring(Math.max(0, inputMatch.index - 200), inputMatch.index);
+                const hasLabel = new RegExp(`<label[^>]*for=["']${id}["']`, 'i').test(beforeInput);
+                
+                if (!hasLabel && !hasAriaLabel) {
+                  warnings.push({
+                    type: 'missing-input-label',
+                    file: relativePath,
+                    line: getLineNumber(content, inputMatch.index),
+                    message: 'Form input missing associated label',
+                    recommendation: 'Add a <label> element with for attribute matching input id, or use aria-label'
+                  });
+                }
+              }
+            } else if (!hasAriaLabel) {
+              warnings.push({
+                type: 'missing-input-label',
+                file: relativePath,
+                line: getLineNumber(content, inputMatch.index),
+                message: 'Form input missing id and label',
+                recommendation: 'Add id to input and corresponding label, or use aria-label'
+              });
+            }
+          }
+        }
+        
+        // Check for missing focus management in modals/dialogs
+        const dialogPattern = /<Dialog|<dialog/gi;
+        if (dialogPattern.test(content)) {
+          // Skip Dialog.tsx itself - it IS the Dialog component
+          if (normalizedPath.includes('/Dialog/Dialog.tsx') || normalizedPath.includes('/Dialog/Dialog.jsx')) {
+            continue; // Skip the Dialog component file itself
+          }
+          
+          // Check if Dialog from pace-core is used (which handles focus automatically)
+          // Check for both published package import and relative imports (within pace-core repo)
+          const usesPaceCoreDialog = content.includes('from \'@jmruthers/pace-core\'') ||
+                                    content.includes('from "@jmruthers/pace-core"') ||
+                                    content.includes('from \'../Dialog') ||
+                                    content.includes('from "../Dialog') ||
+                                    content.includes('from \'../../Dialog') ||
+                                    content.includes('from "../../Dialog') ||
+                                    content.includes('from \'../../../Dialog') ||
+                                    content.includes('from "../../../Dialog') ||
+                                    content.includes('from \'./Dialog') ||
+                                    content.includes('from "./Dialog');
+          
+          if (!usesPaceCoreDialog) {
+            suggestions.push({
+              type: 'dialog-focus-management',
+              file: relativePath,
+              message: 'Custom dialog implementation detected',
+              recommendation: 'Use Dialog component from @jmruthers/pace-core which handles focus management automatically'
+            });
+          }
+        }
+        
+        // Check for color contrast issues (heuristic - check for color props without sufficient contrast)
+        const colorPattern = /(?:color|bg-|text-)=["']([^"']+)["']/g;
+        // This is a simplified check - full implementation would need color contrast calculation
+        // For now, just suggest using pace-core components which handle contrast
+        
+      } catch (error) {
+        // Skip files with errors
+      }
+    }
+    
+    return { issues, warnings, suggestions };
+  }
+};
+
+module.exports = accessibilityCheck;