@jmruthers/pace-core 0.6.5 → 0.6.7

package/cursor-rules/{03-solid-principles.mdc → 03-architecture.mdc}

@@ -1,13 +1,43 @@
 ---
-description: Enforce SOLID architecture principles in consuming apps
+description: Enforce SOLID architecture principles, component design, and API design patterns
 globs: ["src/**/*.{ts,tsx}"]
 alwaysApply: false
 paceCoreVersion: "0.6.x"
 rulesVersion: "2025-01-28"
 ---
-# SOLID Principles Guide
+# Architecture Standards Guide
 
-This guide enforces SOLID architecture principles to ensure maintainable, extensible, and testable code.
+**📚 Human-Readable Standard**: See [3-architecture-standards.md](../../packages/core/docs/standards/3-architecture-standards.md) for complete documentation.
+
+This guide enforces SOLID architecture principles, component design patterns, and API design patterns to ensure maintainable, extensible, and testable code.
+
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Extract complex logic** - Move business logic out of components into hooks, services, or utilities
+2. **Use composition** - Extend functionality through composition, not modification of pace-core components
+3. **Keep components simple** - Components should only handle UI rendering, not data fetching or business logic
+4. **Use focused interfaces** - Create small, specific interfaces instead of large, generic ones
+5. **Depend on abstractions** - Use interfaces/types, not concrete implementations
+6. **Follow ApiResult pattern** - All RPCs must return ApiResult shape with proper error handling
+
+**Decision Tree: Where should this logic live?**
+```
+1. What type of logic is this?
+   ├─ UI rendering → Component
+   ├─ Data fetching → Hook or service
+   ├─ Business logic → Hook, service, or utility
+   ├─ Formatting/transformation → Utility function
+   └─ Validation → Zod schema or utility
+
+2. Is this logic complex?
+   ├─ YES → Extract to hook/service/utility
+   └─ NO → Can stay in component if simple
+
+3. Does this modify pace-core behavior?
+   ├─ YES → Use composition (wrap pace-core component)
+   └─ NO → Continue
+```
 
 ## Single Responsibility Principle (SRP)
 
@@ -204,17 +234,103 @@ Before committing code, verify:
 - [ ] No god objects or bloated components
 - [ ] Code is testable and maintainable
 
-## Anti-Patterns to Avoid
+## Common Mistakes to Avoid
+
+**When writing code, NEVER:**
+1. **Create god objects** - Components/classes that do too much
+   ```tsx
+   // ❌ WRONG: Component does everything
+   function UserDashboard({ userId }) {
+     const [user, setUser] = useState(null);
+     const [events, setEvents] = useState([]);
+     const [organisations, setOrganisations] = useState([]);
+     // 200+ lines of logic...
+   }
+   
+   // ✅ CORRECT: Separated concerns
+   function UserDashboard({ userId }) {
+     const user = useUser(userId);
+     const events = useUserEvents(userId);
+     const organisations = useUserOrganisations(userId);
+     return <DashboardContent user={user} events={events} organisations={organisations} />;
+   }
+   ```
+
+2. **Put business logic in components** - Extract to hooks/services
+3. **Create large interfaces** - Use focused, specific interfaces
+4. **Depend on concrete implementations** - Use abstractions (interfaces/types)
+5. **Modify pace-core components** - Use composition instead
+6. **Use boolean flags for states** - Use discriminated unions
+
+## API Design Patterns
+
+### MUST: Follow API Design Principles
+
+**APIs MUST be:**
+- Intuitive and consistent
+- Extensible without breaking changes
+- Clear about errors and edge cases
+
+### MUST: Use ApiResult Pattern
+
+**All RPCs MUST return ApiResult shape:**
+
+```typescript
+type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError };
+type ApiError = { code: string; message: string; details?: object };
+```
+
+```tsx
+// ✅ CORRECT: RPC returns ApiResult
+const result = await supabase.rpc('app_events_create', { name, date });
+if (!result.ok) {
+  // Handle error
+  return { ok: false, error: result.error };
+}
+return { ok: true, data: result.data };
+```
+
+### SHOULD: Make Write RPCs Idempotent
+
+**Write RPCs SHOULD be idempotent when possible:**
+
+```sql
+-- ✅ CORRECT: Idempotent create (ON CONFLICT DO NOTHING)
+INSERT INTO events (id, name, date)
+VALUES (p_event_id, p_name, p_date)
+ON CONFLICT (id) DO NOTHING;
+```
+
+## Component Design Patterns
+
+### MUST: Follow Component Principles
 
-1. **God Objects** - Classes/components that do too much
-2. **Feature Envy** - Functions that use more of another object than their own
-3. **Data Clumps** - Groups of data that should be objects
-4. **Long Parameter Lists** - Use objects/interfaces instead
-5. **Divergent Change** - One class changed for multiple reasons
-6. **Shotgun Surgery** - One change requires many class modifications
+**Components MUST:**
+- Be stateless when possible
+- Use composable structure
+- Be accessible by default
+- Be fully typed
+- Have small surface area
+
+### MUST NOT: Add Domain Logic to Components
+
+**Components MUST NOT:**
+- Include domain-specific logic
+- Fetch data directly (use hooks/services)
+- Include business workflows
+
+### MUST: Ensure Accessibility
+
+**Components MUST:**
+- Be keyboard operable
+- Have correct ARIA roles
+- Have visible focus states
+- Avoid inaccessible interactions
 
 ## Reference
 
+**Note**: RLS policy validation is handled by the audit tool. See [3-architecture-standards.md](../../packages/core/docs/standards/3-architecture-standards.md) for complete enforcement details.
+
 - Single Responsibility: Each module has one reason to change
 - Open/Closed: Open for extension, closed for modification
 - Liskov Substitution: Subtypes must be substitutable

package/cursor-rules/04-code-quality.mdc

@@ -0,0 +1,419 @@
+---
+description: Enforce code quality standards including TypeScript, ESLint, formatting, performance, and accessibility
+globs: ["src/**/*.{ts,tsx,js,jsx}"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Code Quality Guide
+
+**📚 Human-Readable Standard**: See [4-code-quality-standards.md](../../packages/core/docs/standards/4-code-quality-standards.md) for complete documentation.
+
+This guide enforces code quality standards to ensure maintainable, performant, and accessible code.
+
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Use strict TypeScript** - Never use `any`, always use proper types or `unknown` with type guards
+2. **Use discriminated unions** - Replace boolean flags with discriminated unions for better type safety
+3. **Use ReadonlyArray** - Use `ReadonlyArray` for immutable arrays
+4. **Ensure accessibility** - All components must be keyboard accessible, have ARIA labels, and visible focus states
+5. **Use semantic HTML** - Use semantic elements (`<main>`, `<section>`, `<article>`, etc.) instead of `<div>` wrappers
+6. **Memoize appropriately** - Use `useMemo` and `useCallback` for expensive computations and stable references
+7. **Early returns** - Use early returns to reduce nesting and improve readability
+
+**Decision Tree: Type Safety**
+```
+1. What type should I use?
+   ├─ Known structure → Interface or type
+   ├─ Truly unknown → unknown (with type guard)
+   └─ Multiple variants → Discriminated union (not boolean flags)
+
+2. Is this an array that shouldn't be mutated?
+   ├─ YES → ReadonlyArray<T>
+   └─ NO → Array<T> or T[]
+
+3. Do I need multiple states?
+   ├─ YES → Discriminated union (type: 'loading' | 'success' | 'error')
+   └─ NO → Single type
+```
+
+## TypeScript Standards
+
+### MUST: Use Strict Mode
+
+**TypeScript MUST use strict mode:**
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true
+  }
+}
+```
+
+### MUST NOT: Use `any`
+
+**MUST NOT use `any` type. Use `unknown` if type is truly unknown:**
+
+```tsx
+// ❌ WRONG: Using any
+function processData(data: any) { return data.value; }
+
+// ✅ CORRECT: Using unknown with type guard or proper types
+function processData(data: unknown) {
+  if (typeof data === 'object' && data !== null && 'value' in data) {
+    return (data as { value: string }).value;
+  }
+  throw new Error('Invalid data');
+}
+// Or: interface Data { value: string; } function processData(data: Data) { return data.value; }
+```
+
+### MUST: Use Discriminated Unions
+
+**MUST use discriminated unions instead of boolean flags:**
+
+```tsx
+// ❌ WRONG: Boolean flags (confusing: what if both are true?)
+interface User { isAdmin: boolean; isGuest: boolean; }
+
+// ✅ CORRECT: Discriminated union
+type User = { type: 'admin'; permissions: Permission[] } | { type: 'guest'; limitedAccess: boolean } | { type: 'user'; role: UserRole };
+```
+
+### SHOULD: Use ReadonlyArray
+
+**SHOULD use ReadonlyArray for immutable arrays:**
+
+```tsx
+// ✅ CORRECT - ReadonlyArray
+function processItems(items: ReadonlyArray<Item>) {
+  // Can't mutate items
+  return items.map(item => transform(item));
+}
+```
+
+## ESLint Configuration
+
+**Note**: ESLint configuration and enforcement is handled by ESLint (Layer 3). See [4-code-quality-standards.md](../../packages/core/docs/standards/4-code-quality-standards.md) for complete ESLint setup instructions.
+
+**MUST:**
+- Use pace-core ESLint config
+- Fix all ESLint errors before committing
+- Run `npm run lint` before committing
+
+## Code Formatting
+
+### MUST: Use Consistent Formatting
+
+**MUST use Prettier or equivalent for consistent formatting:**
+
+```json
+// .prettierrc
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 100
+}
+```
+
+### MUST: Format Before Committing
+
+**MUST format code before committing:**
+
+```bash
+npm run format
+# Or use pre-commit hook
+```
+
+## Performance Considerations
+
+### SHOULD: Optimize Re-renders
+
+**SHOULD use React.memo, useMemo, useCallback appropriately:**
+
+```tsx
+// ✅ CORRECT: Memoize expensive computations, callbacks, and components
+const expensiveValue = useMemo(() => computeExpensiveValue(data), [data]);
+const handleClick = useCallback(() => doSomething(id), [id]);
+const ExpensiveComponent = React.memo(({ data }) => <div>{/* ... */}</div>);
+```
+
+### SHOULD: Avoid Unnecessary Re-renders
+
+**SHOULD avoid causing unnecessary re-renders:**
+
+```tsx
+// ❌ WRONG: New object on every render (causes unnecessary re-renders)
+function Component({ items }) { const config = { items, enabled: true }; return <Child config={config} />; }
+
+// ✅ CORRECT: Memoize object
+function Component({ items }) {
+  const config = useMemo(() => ({ items, enabled: true }), [items]);
+  return <Child config={config} />;
+}
+```
+
+### SHOULD: Lazy Load Heavy Components
+
+**SHOULD lazy load heavy components:**
+
+```tsx
+// ✅ CORRECT: Lazy load heavy components
+import { lazy, Suspense } from 'react';
+const HeavyComponent = lazy(() => import('./HeavyComponent'));
+function App() {
+  return <Suspense fallback={<Loading />}><HeavyComponent /></Suspense>;
+}
+```
+
+## Accessibility Requirements
+
+**MUST** ensure all components and pages meet WCAG 2.1 Level AA standards.
+
+### Core Principles
+
+1. **Semantic HTML** - Use semantic elements (`<main>`, `<section>`, `<article>`, `<nav>`, etc.) instead of `<div>` wrappers
+2. **Keyboard Navigation** - All interactive elements must be accessible via keyboard
+3. **ARIA Labels** - Provide clear labels for screen readers when visible text isn't sufficient
+4. **Focus Management** - Visible focus indicators on all interactive elements
+5. **Color Contrast** - Text must meet 4.5:1 contrast ratio (WCAG AA)
+
+### Implementation Requirements
+
+```tsx
+// ✅ CORRECT - Semantic HTML with ARIA
+<main>
+  <h1>Page Title</h1>
+  <section aria-labelledby="section-title">
+    <h2 id="section-title">Section Title</h2>
+    <Button
+      aria-label="Delete user"
+      aria-describedby="delete-help"
+    >
+      Delete
+    </Button>
+    <span id="delete-help" className="sr-only">
+      Permanently removes the user account
+    </span>
+  </section>
+</main>
+
+// ❌ WRONG - Non-semantic structure
+<div>
+  <div className="title">Page Title</div>
+  <div>
+    <button>Delete</button>
+  </div>
+</div>
+```
+
+### Keyboard Navigation
+
+**MUST** ensure all interactive elements are keyboard accessible:
+
+```tsx
+// ✅ CORRECT - pace-core components handle keyboard navigation automatically
+import { Button, DataTable } from '@jmruthers/pace-core';
+
+<Button onClick={handleClick}>Click me</Button>
+<DataTable data={data} columns={columns} />
+```
+
+### Screen Reader Support
+
+**MUST** provide appropriate ARIA attributes:
+
+```tsx
+// ✅ CORRECT - ARIA labels for icons
+<Button aria-label="Close dialog">
+  <Icon name="x" aria-hidden="true" />
+</Button>
+
+// ✅ CORRECT - Error messages with role="alert"
+{error && (
+  <div role="alert" aria-live="polite">
+    {error.message}
+  </div>
+)}
+
+// ✅ CORRECT - Loading states
+<div role="status" aria-live="polite" aria-busy={loading}>
+  {loading && <span className="sr-only">Loading data...</span>}
+  {loading ? <Spinner /> : <Content />}
+</div>
+```
+
+### Testing Accessibility
+
+**MUST** test with:
+- Keyboard navigation (Tab, Enter, Space, Arrow keys)
+- Screen readers (NVDA, JAWS, VoiceOver)
+- Automated tools (axe DevTools, WAVE, Lighthouse)
+
+**Accessibility Checklist:**
+- [ ] All interactive elements keyboard accessible
+- [ ] Visible focus indicators on all interactive elements
+- [ ] ARIA labels provided for icons and images
+- [ ] Semantic HTML used appropriately
+- [ ] Error messages properly associated with form fields
+- [ ] Color contrast meets WCAG AA (4.5:1 for text)
+- [ ] Screen reader announcements work correctly
+- [ ] Focus management in modals and dynamic content
+
+## Code Review Checklist
+
+**Before submitting code for review, verify:**
+
+- [ ] TypeScript strict mode enabled
+- [ ] No `any` types used
+- [ ] ESLint passes with no errors
+- [ ] Code is formatted consistently
+- [ ] Performance optimizations applied where needed
+- [ ] Accessibility requirements met
+- [ ] Semantic HTML used
+- [ ] ARIA labels provided
+- [ ] Keyboard navigation works
+- [ ] Focus indicators visible
+- [ ] Code is readable and maintainable
+- [ ] Comments explain "why", not "what"
+
+## Code Complexity
+
+### SHOULD: Keep Functions Small
+
+**Functions SHOULD be small and focused:**
+
+```tsx
+// ❌ WRONG: Large function (100+ lines, multiple responsibilities)
+function processUserData(user) { /* 100+ lines of logic */ }
+
+// ✅ CORRECT: Small, focused functions
+function validateUser(user: User): ValidationResult { /* Validation logic */ }
+function transformUser(user: User): TransformedUser { /* Transformation logic */ }
+function processUserData(user: User) {
+  const validation = validateUser(user);
+  if (!validation.valid) return validation;
+  return transformUser(user);
+}
+```
+
+### SHOULD: Limit Cyclomatic Complexity
+
+**Functions SHOULD have low cyclomatic complexity (< 10):**
+
+```tsx
+// ❌ WRONG: High complexity (many nested conditions)
+function processData(data) { if (condition1) { if (condition2) { if (condition3) { /* ... */ } } } }
+
+// ✅ CORRECT: Lower complexity (early returns)
+function processData(data) { if (!condition1) return; if (!condition2) return; if (!condition3) return; /* Process */ }
+```
+
+## Error Handling
+
+### MUST: Handle Errors Gracefully
+
+**MUST handle errors and provide user feedback:**
+
+```tsx
+// ✅ CORRECT: Handle errors gracefully with user feedback
+try {
+  const data = await fetchData();
+  setData(data);
+} catch (error) {
+  logger.error('Failed to fetch data', error);
+  toast.error('Failed to load data. Please try again.');
+}
+```
+
+### MUST: Use Type-Safe Error Handling
+
+**MUST use type-safe error handling:**
+
+```tsx
+// ✅ CORRECT: Type-safe error handling
+function isApiError(error: unknown): error is ApiError {
+  return typeof error === 'object' && error !== null && 'code' in error && 'message' in error;
+}
+try {
+  await apiCall();
+} catch (error) {
+  if (isApiError(error)) handleApiError(error);
+  else handleUnknownError(error);
+}
+```
+
+## Common Mistakes to Avoid
+
+**When writing code, NEVER:**
+1. **Use `any` type** - Always use proper types or `unknown` with type guards
+   ```tsx
+   // ❌ WRONG
+   function process(data: any) {
+     return data.value;
+   }
+   
+   // ✅ CORRECT
+   function process(data: unknown) {
+     if (typeof data === 'object' && data !== null && 'value' in data) {
+       return (data as { value: string }).value;
+     }
+     throw new Error('Invalid data');
+   }
+   ```
+
+2. **Use boolean flags for multiple states** - Use discriminated unions
+   ```tsx
+   // ❌ WRONG
+   interface User { isAdmin: boolean; isGuest: boolean; }
+   
+   // ✅ CORRECT
+   type User = 
+     | { type: 'admin'; permissions: Permission[] }
+     | { type: 'guest'; limitedAccess: boolean }
+     | { type: 'user'; role: UserRole };
+   ```
+
+3. **Forget accessibility** - Always ensure keyboard navigation, ARIA labels, and semantic HTML
+4. **Create mutable arrays when they shouldn't change** - Use `ReadonlyArray`
+5. **Skip memoization for expensive operations** - Use `useMemo` and `useCallback` appropriately
+
+## Code Quality Checklist
+
+Before committing, verify:
+- [ ] TypeScript strict mode enabled
+- [ ] No `any` types (use `unknown` with type guards)
+- [ ] Discriminated unions used instead of boolean flags
+- [ ] `ReadonlyArray` used for immutable arrays
+- [ ] Naming conventions followed (hooks: `use*`, providers: `*Provider`, etc.)
+- [ ] Pure functions preferred (no side effects)
+- [ ] Early returns used to reduce nesting
+- [ ] Complex logic extracted to helpers
+- [ ] Components are small and focused
+- [ ] Functional components only (no class components)
+- [ ] Hook dependencies are complete
+- [ ] Memoization used when appropriate
+- [ ] Accessibility requirements met (WCAG 2.1 AA)
+- [ ] Keyboard navigation supported
+- [ ] ARIA labels provided where needed
+- [ ] Semantic HTML used appropriately
+
+## Reference
+
+**Note**: ESLint configuration details and mechanical type checking are handled by ESLint (Layer 3). See [4-code-quality-standards.md](../../packages/core/docs/standards/4-code-quality-standards.md) for complete enforcement details.
+
+- TypeScript Handbook: https://www.typescriptlang.org/docs/
+- React Performance: https://react.dev/learn/render-and-commit
+- Web Accessibility: https://www.w3.org/WAI/