@jmruthers/pace-core 0.5.193 → 0.6.1

package/docs/getting-started/cursor-rules.md

@@ -0,0 +1,262 @@
+# Cursor Rules Quick Start Guide
+
+This guide helps you get started with pace-core cursor rules in your consuming app.
+
+## What are Cursor Rules?
+
+Cursor rules are `.mdc` (Markdown Cursor) files that guide AI assistants (like Cursor) to follow specific patterns and standards when writing code. pace-core provides a comprehensive set of rules that ensure your app maintains quality, consistency, and compliance with pace-core standards.
+
+## Installation
+
+### Step 1: Install pace-core
+
+Make sure pace-core is installed in your project:
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+### Step 2: Install Cursor Rules
+
+Run the installation script from your app root:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "setup:cursor-rules": "node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run setup:cursor-rules
+```
+
+The script will:
+- Create `.cursor/rules/` directory if it doesn't exist
+- Copy all pace-core rules (00-07) to your project
+- **Automatically update** pace-core rules (00-09) if they've changed
+- Preserve any existing custom rules (50+)
+- Skip files that are already up to date
+
+## Quick Start Snippet
+
+When working with Cursor, you can explicitly reference rules:
+
+> "Use pace-core components and follow rules 00–04."
+
+This helps Cursor focus on specific rule sets and ensures consistency.
+
+## Rule Files Overview
+
+The installed rules are numbered for ordering:
+
+- **00-pace-core-compliance.mdc** - Enforce pace-core usage patterns
+- **01-standards-compliance.mdc** - Enforce all pace-core standards
+- **02-project-structure.mdc** - Define standard folder structure
+- **03-solid-principles.mdc** - Enforce SOLID architecture principles
+- **04-testing-standards.mdc** - Enforce testing framework consistency
+- **05-bug-reports-and-features.mdc** - Templates for bug reports (guidance-only)
+- **06-code-quality.mdc** - Enforce code quality standards
+- **07-tech-stack-compliance.mdc** - Enforce tech stack versions and patterns
+
+## Using Rules with Cursor
+
+### Automatic Loading
+
+Cursor automatically loads all `.mdc` files from `.cursor/rules/` when:
+- You open a file that matches the rule's `globs` pattern
+- You ask Cursor to write or modify code
+- Cursor needs context for code generation
+
+### Explicit References
+
+You can explicitly reference rules in your prompts:
+
+```
+"Create a new component following rules 00, 01, and 03"
+"Refactor this code to follow SOLID principles (rule 03)"
+"Write tests following rule 04"
+```
+
+### Rule Semantics
+
+Rules use clear semantics:
+- **MUST** - Hard requirement, non-negotiable
+- **SHOULD** - Strong recommendation, best practice
+- **MAY** - Optional, acceptable alternative
+
+## Custom Rules
+
+### Creating Your Own Rules
+
+Create your own rules in `.cursor/rules/` with numbers starting at `50`:
+
+```
+.cursor/rules/
+├── 00-pace-core-compliance.mdc      # pace-core rule
+├── 01-standards-compliance.mdc     # pace-core rule
+├── ...
+├── 50-my-custom-rule.mdc           # Your custom rule
+└── 51-another-custom-rule.mdc      # Your custom rule
+```
+
+### Rule Format
+
+Your custom rules should follow the same format:
+
+```markdown
+---
+description: Brief description of your rule
+globs: ["targeted/path/**/*.{ts,tsx}"]
+alwaysApply: true
+---
+
+# Your Rule Title
+
+Content with examples and guidelines.
+```
+
+## Running Audits
+
+### Comprehensive Audit
+
+Run the comprehensive audit tool to check compliance:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/audit-consuming-app.cjs
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "audit:pace-core": "node node_modules/@jmruthers/pace-core/scripts/audit-consuming-app.cjs"
+  }
+}
+```
+
+This generates a timestamped markdown report in `audit/` directory.
+
+### Compliance Check
+
+For a quick compliance check:
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/check-pace-core-compliance.cjs
+```
+
+## Updating Rules
+
+When pace-core is updated, run the installation script again:
+
+```bash
+npm run setup:cursor-rules
+```
+
+The script will:
+- **Automatically update** pace-core rules (00-09) if they've changed (version or content differs)
+- Preserve your custom rules (50+)
+- Skip files that are already up to date
+
+### Force Update
+
+To force update all rules (even when versions match):
+
+```bash
+node node_modules/@jmruthers/pace-core/scripts/install-cursor-rules.cjs --force
+```
+
+**Note**: Normally, pace-core rules are automatically updated when they change. The `--force` flag forces an update even when versions match (useful if content changed but version metadata wasn't updated).
+
+## Monorepo Setup
+
+For monorepos, run the installation script from each app's root directory:
+
+```
+monorepo/
+├── apps/
+│   ├── app1/
+│   │   └── .cursor/rules/  # Run script here
+│   └── app2/
+│       └── .cursor/rules/  # Run script here
+```
+
+Each app maintains its own `.cursor/rules/` directory.
+
+## Troubleshooting
+
+### Rules Not Loading
+
+1. Verify rules are in `.cursor/rules/` directory
+2. Check file extensions are `.mdc`
+3. Restart Cursor if rules were just installed
+4. Check rule frontmatter is valid YAML
+
+### Rules Conflicting
+
+1. Check rule numbering (pace-core: 00-09, yours: 50+)
+2. Verify `globs` patterns don't overlap unnecessarily
+3. Review rule priorities in frontmatter
+
+### Installation Fails
+
+1. Check you're in the app root directory
+2. Verify `node_modules/@jmruthers/pace-core/` exists
+3. Check file permissions
+4. Try with `--force` flag if needed
+
+## Best Practices
+
+1. **Run audits regularly** - Check compliance before major commits
+2. **Update rules** - Keep pace-core rules up to date
+3. **Reference rules explicitly** - Tell Cursor which rules to follow
+4. **Create custom rules** - Add app-specific rules starting at 50
+5. **Review audit reports** - Address issues systematically
+
+## Example Workflow
+
+1. **Initial Setup:**
+   ```bash
+   npm install @jmruthers/pace-core
+   npm run setup:cursor-rules
+   ```
+
+2. **Daily Development:**
+   - Cursor automatically uses rules when writing code
+   - Explicitly reference rules when needed: "Follow rules 00-04"
+
+3. **Before Committing:**
+   ```bash
+   npm run audit:pace-core
+   ```
+   Review the generated report in `audit/` directory
+
+4. **After pace-core Updates:**
+   ```bash
+   npm update @jmruthers/pace-core
+   npm run setup:cursor-rules
+   ```
+
+## Related Documentation
+
+- [Cursor Rules README](../../cursor-rules/README.md)
+- [pace-core Standards](../standards/README.md)
+- [pace-core Exports](../api-reference/README.md)
+
+## Support
+
+For issues with cursor rules:
+1. Check this guide
+2. Review rule files for guidance
+3. File an issue in pace-core repository
+4. Check pace-core documentation

package/docs/getting-started/installation-guide.md

@@ -71,7 +71,12 @@ import path from 'path'
 
 export default defineConfig({
   plugins: [
-    react(),
+    react({
+      // React Compiler for automatic optimizations (React 19+)
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
     tailwindcss({
       // CRITICAL: Include pace-core source files for Tailwind scanning
       content: [

package/docs/getting-started/quick-start.md

@@ -57,7 +57,12 @@ import path from 'path';
 
 export default defineConfig({
   plugins: [
-    react(),
+    react({
+      // React Compiler for automatic optimizations (React 19+)
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
     tailwindcss({
       content: [
         './src/**/*.{js,ts,jsx,tsx}',

package/docs/migration/MIGRATION_GUIDE.md

@@ -933,8 +933,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"
   },
@@ -944,8 +944,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/docs/migration/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/standards/README.md

@@ -33,3 +33,42 @@ 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
+
+### 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.1",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {
@@ -71,6 +71,9 @@
     "./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-consuming-app": "./scripts/audit-consuming-app.cjs",
     "./source": {
       "import": "./src/index.ts",
       "default": "./src/index.ts"
@@ -138,7 +141,8 @@
     "docs",
     "core-usage-manifest.json",
     "eslint-config-pace-core.cjs",
-    "scripts"
+    "scripts",
+    "cursor-rules"
   ],
   "scripts": {
     "_comment_build": "Build package and documentation",
@@ -207,9 +211,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 +226,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 +240,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"