@jmruthers/pace-core 0.6.6 → 0.6.7

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/

package/cursor-rules/{08-markup-quality.mdc → 05-styling.mdc}

@@ -7,15 +7,49 @@ rulesVersion: "2025-01-28"
 ---
 # Markup Quality Guide
 
-**📚 Human-Readable Standard**: See [08-markup-quality.md](../../packages/core/docs/standards/08-markup-quality.md) for complete documentation including **CRITICAL CSS configuration requirements**.
+**📚 Human-Readable Standard**: See [5-styling-standards.md](../../packages/core/docs/standards/5-styling-standards.md) for complete documentation including **CRITICAL CSS configuration requirements**.
 
 **⚠️ IMPORTANT**: This rule is ALWAYS APPLIED. The standard includes required CSS setup that MUST be followed for pace-core components to render correctly.
 
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Use pace-core components** - Never use native HTML elements when pace-core provides components
+2. **Use semantic HTML** - Always use semantic elements (`<main>`, `<section>`, `<article>`, etc.) instead of `<div>` wrappers
+3. **Never use inline styles** - Never use `style={{...}}`, always use pace-core components or Tailwind classes
+4. **Use Grid for layout** - Prefer CSS Grid over Flexbox for centering, two-dimensional layouts, and full-page layouts
+5. **Minimize elements** - Use the fewest elements possible, prefer React Fragments over wrapper divs
+6. **Check CSS setup** - Before using pace-core components, verify CSS is configured correctly (see checklist below)
+
+**Decision Tree: Markup & Styling**
+```
+1. What element should I use?
+   ├─ Button → <Button> from pace-core (not <button>)
+   ├─ Input → <Input> from pace-core (not <input>)
+   ├─ Page wrapper → <main> (not <div>)
+   ├─ Section → <section> (not <div>)
+   ├─ Article → <article> (not <div>)
+   └─ Navigation → <nav> (not <div>)
+
+2. Do I need a wrapper?
+   ├─ For React single root → Use Fragment (<>...</>)
+   ├─ For styling only → Apply to existing semantic parent
+   └─ For layout → Use Grid (grid place-items-center, grid grid-cols-*)
+
+3. How do I center content?
+   ├─ Both axes → grid place-items-center
+   └─ Single axis → flex (but prefer grid)
+
+4. Am I using inline styles?
+   ├─ YES → WRONG - Use pace-core component or Tailwind class
+   └─ NO → Continue
+```
+
 ## ⚠️ CRITICAL: CSS Configuration Required
 
 **Before using pace-core components, you MUST configure CSS correctly.** Without proper configuration, pace-core components will appear unstyled or with incorrect styling.
 
-**MUST read the standard for complete CSS setup instructions**: [08-markup-quality.md](../../packages/core/docs/standards/08-markup-quality.md)
+**MUST read the standard for complete CSS setup instructions**: [5-styling-standards.md](../../packages/core/docs/standards/5-styling-standards.md)
 
 **Quick checklist:**
 - [ ] `src/app.css` exists with `@import "tailwindcss";`
@@ -38,18 +72,29 @@ This guide enforces clean markup standards, semantic HTML usage, and proper pace
 
 ```tsx
 // ❌ WRONG: Custom button or native HTML element
-<button className="btn-primary">Click me</button>
-<input type="text" className="form-input" />
+<button className="btn-primary" onClick={handleClick}>
+  Click me
+</button>
+<input 
+  type="text" 
+  className="form-input" 
+  value={value}
+  onChange={handleChange}
+/>
 
 // ✅ CORRECT: Use pace-core components
 import { Button, Input } from '@jmruthers/pace-core';
-<Button>Click me</Button>
-<Input type="text" />
+<Button onClick={handleClick}>Click me</Button>
+<Input 
+  type="text" 
+  value={value}
+  onChange={handleChange}
+/>
 ```
 
 ### MUST NOT: Add Custom Styles to pace-core Components
 
-**MUST NOT add custom styles when pace-core components already provide styling:**
+**NEVER add custom styles when pace-core components already provide styling. Use component variants/props instead.**
 
 ```tsx
 // ❌ WRONG: Overriding pace-core component styles
@@ -111,7 +156,7 @@ import { Button, Input } from '@jmruthers/pace-core';
 
 ### MUST: Prefer Semantic HTML (Limit `<div>`)
 
-**You MUST prefer semantic HTML elements** (`<main>`, `<section>`, `<article>`, `<header>`, `<footer>`, `<nav>`, lists, etc.).
+**ALWAYS prefer semantic HTML elements** (`<main>`, `<section>`, `<article>`, `<header>`, `<footer>`, `<nav>`, lists, etc.).
 Using semantic elements improves accessibility, maintainability, and consistency.
 
 #### `<div>` usage policy
@@ -470,8 +515,8 @@ Before committing code, verify:
 
 ## Reference
 
-- **pace-core Components**: See `00-pace-core-compliance.mdc` for component usage
+- **pace-core Components**: See [01-pace-core-compliance.mdc](./01-pace-core-compliance.mdc) for component usage
 - **Semantic HTML**: https://developer.mozilla.org/en-US/docs/Glossary/Semantics
 - **React Fragments**: https://react.dev/reference/react/Fragment
-- **Accessibility**: See `06-code-quality.mdc` for accessibility requirements
+- **Accessibility**: See [04-code-quality.mdc](./04-code-quality.mdc) for accessibility requirements
 - **When in doubt**: Remove the element, remove the style, and rely on pace-core or semantic HTML

package/cursor-rules/{09-rbac-compliance.mdc → 06-security-rbac.mdc}

@@ -1,18 +1,48 @@
 ---
-description: Enforce RBAC contract compliance - strict rules for permission checking, page protection, and RBAC usage patterns
-globs: ["src/**/*.{ts,tsx,js,jsx}"]
+description: Enforce RBAC contract compliance, RLS policy patterns, and security requirements
+globs: ["src/**/*.{ts,tsx,js,jsx}", "supabase/migrations/**/*.sql"]
 alwaysApply: false
 paceCoreVersion: "0.6.x"
 rulesVersion: "2025-01-28"
 ---
-# RBAC Compliance Guide
+# Security & RBAC Standards Guide
 
-**📚 Human-Readable Standard**: See [09-rbac-compliance.md](../../packages/core/docs/standards/09-rbac-compliance.md) for complete documentation including RLS policy patterns, helper functions, and security requirements.
+**📚 Human-Readable Standard**: See [6-security-rbac-standards.md](../../packages/core/docs/standards/6-security-rbac-standards.md) for complete documentation including RLS policy patterns, helper functions, and security requirements.
 
-This guide enforces the **mandatory RBAC contract** between pace-core and consuming apps. These rules are **enforced by ESLint** and violations will result in build errors.
+This guide enforces the **mandatory RBAC contract** and security patterns between pace-core and consuming apps.
 
 **⚠️ CRITICAL**: This contract is **non-negotiable**. See [RBAC Contract](../../packages/core/docs/rbac/RBAC_CONTRACT.md) for complete documentation.
 
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Protect all pages** - Wrap every protected page with `PagePermissionGuard` (no exceptions)
+2. **Use pace-core hooks directly** - Never create wrapper functions around `useCan` or `useResourcePermissions`
+3. **Use RESOURCE_NAMES constants** - Never use string literals in `useResourcePermissions` calls
+4. **Validate all inputs** - Always validate user input with Zod schemas before processing
+5. **Never expose internals** - Never show SQL errors, stack traces, or internal details to users
+6. **Use helper functions in RLS** - Always use STABLE SECURITY DEFINER helper functions, never subqueries
+7. **Sanitize logs** - Never log passwords, tokens, or sensitive data
+
+**Decision Tree: Security & Permissions**
+```
+1. Is this a protected page?
+   ├─ YES → Wrap with PagePermissionGuard (no exceptions)
+   └─ NO → Continue
+
+2. Do I need to check permissions?
+   ├─ YES → Use pace-core hooks directly (useCan, useResourcePermissions)
+   └─ NO → Continue
+
+3. Am I handling user input?
+   ├─ YES → Validate with Zod schema
+   └─ NO → Continue
+
+4. Am I logging or showing errors?
+   ├─ YES → Never expose internals, sanitize sensitive data
+   └─ NO → Continue
+```
+
 ## MUST: Use PagePermissionGuard for All Protected Pages
 
 **MUST wrap all protected pages with `PagePermissionGuard`:**
@@ -358,6 +388,32 @@ These rules are enforced by ESLint rules (all ERROR severity):
 7. **`no-resource-permission-string-literals`** - Detects string literals in `useResourcePermissions` calls
 8. **`no-permission-wrapper-functions`** - Detects wrapper functions around pace-core permission hooks
 
+## Common Mistakes to Avoid
+
+**When writing code, NEVER:**
+1. **Skip PagePermissionGuard** - Every protected page must be wrapped
+   ```tsx
+   // ❌ WRONG
+   function DashboardPage() {
+     return <DashboardContent />;
+   }
+   
+   // ✅ CORRECT
+   function DashboardPage() {
+     return (
+       <PagePermissionGuard pageName="dashboard" operation="read">
+         <DashboardContent />
+       </PagePermissionGuard>
+     );
+   }
+   ```
+
+2. **Create wrapper functions around permission hooks** - Use hooks directly
+3. **Use string literals in useResourcePermissions** - Always use RESOURCE_NAMES constants
+4. **Bypass input validation** - Always validate with Zod schemas
+5. **Expose internal errors** - Never show SQL, stack traces, or file paths to users
+6. **Log sensitive data** - Never log passwords, tokens, or PII
+
 ## Compliance Checklist
 
 Before committing RBAC-related code, verify:
@@ -459,4 +515,4 @@ $$;
 - **Migration Guide**: `packages/core/docs/rbac/MIGRATION_GUIDE.md` - Migrating to RBAC Contract v2.0.0
 - **Quick Start**: `packages/core/docs/rbac/quick-start.md` - Getting started guide
 - **API Reference**: `packages/core/docs/rbac/api-reference.md` - Complete API documentation
-- **RLS Standards**: `packages/core/docs/standards/09-rbac-compliance.md` - RLS policy patterns and super-admin requirements
+- **RLS Standards**: [6-security-rbac-standards.md](../../packages/core/docs/standards/6-security-rbac-standards.md) - RLS policy patterns and super-admin requirements