@jmruthers/pace-core 0.6.1 → 0.6.2

package/cursor-rules/04-testing-standards.mdc

@@ -1,9 +1,9 @@
 ---
 description: Enforce testing framework consistency and standards for consuming apps
 globs: ["**/*.{test,spec}.{ts,tsx}"]
-alwaysApply: true
-paceCoreVersion: "0.5.x"
-rulesVersion: "2025-01-15"
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
 ---
 # Testing Standards Guide
 
@@ -25,24 +25,18 @@ npm run test:coverage
 **MUST use React Testing Library + userEvent for all component tests.**
 
 ```tsx
-// ✅ CORRECT - React Testing Library
+// ✅ CORRECT: React Testing Library + userEvent
 import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { Button } from '@jmruthers/pace-core';
-
 test('button clicks work', async () => {
   const user = userEvent.setup();
   const handleClick = vi.fn();
-  
   render(<Button onClick={handleClick}>Click me</Button>);
-  
   await user.click(screen.getByRole('button', { name: /click me/i }));
-  
   expect(handleClick).toHaveBeenCalledTimes(1);
 });
 
-// ❌ WRONG - Enzyme or other testing libraries
-import { shallow } from 'enzyme';
+// ❌ WRONG: Enzyme or other testing libraries
 ```
 
 ## MUST: Colocate Tests
@@ -94,21 +88,15 @@ export default defineConfig({
 **Tests MUST focus on what users see and do:**
 
 ```tsx
-// ❌ WRONG - Testing implementation
-test('calls setState', () => {
-  const component = render(<Counter />);
-  expect(component.state.count).toBe(0);
-});
+// ❌ WRONG: Testing implementation (component.state.count)
+test('calls setState', () => { const component = render(<Counter />); expect(component.state.count).toBe(0); });
 
-// ✅ CORRECT - Testing user behavior
+// ✅ CORRECT: Testing user behavior (what user sees and does)
 test('displays count and increments on button click', async () => {
   const user = userEvent.setup();
   render(<Counter />);
-  
   expect(screen.getByText('Count: 0')).toBeInTheDocument();
-  
   await user.click(screen.getByRole('button', { name: /increment/i }));
-  
   expect(screen.getByText('Count: 1')).toBeInTheDocument();
 });
 ```
@@ -118,14 +106,11 @@ test('displays count and increments on button click', async () => {
 **MUST prefer accessible queries (byRole, byLabelText, etc.):**
 
 ```tsx
-// ✅ CORRECT - Accessible queries
+// ✅ CORRECT: Accessible queries (byRole, byLabelText, byText)
 screen.getByRole('button', { name: /submit/i });
 screen.getByLabelText(/email address/i);
-screen.getByText(/welcome/i);
 
-// ❌ AVOID - Non-accessible queries (use as last resort)
-screen.getByTestId('submit-button');
-screen.getByClassName('btn-primary');
+// ❌ AVOID: Non-accessible queries (getByTestId, getByClassName - use as last resort)
 ```
 
 ## SHOULD: Test Critical Paths
@@ -174,19 +159,10 @@ describe('EventCard', () => {
 **MUST NOT mock unless necessary:**
 
 ```tsx
-// ❌ WRONG - Unnecessary mock
-const mockFetch = vi.fn();
-global.fetch = mockFetch;
-
-// ✅ CORRECT - Use real implementation or MSW
+// ❌ WRONG: Unnecessary mock (global.fetch = mockFetch)
+// ✅ CORRECT: Use real implementation or MSW
 import { server } from './mocks/server';
-import { rest } from 'msw';
-
-server.use(
-  rest.get('/api/events', (req, res, ctx) => {
-    return res(ctx.json([{ id: '1', name: 'Event' }]));
-  })
-);
+server.use(rest.get('/api/events', (req, res, ctx) => res(ctx.json([{ id: '1', name: 'Event' }]))));
 ```
 
 ## MUST: Test Async Code Properly
@@ -194,16 +170,11 @@ server.use(
 **MUST handle async operations correctly:**
 
 ```tsx
-// ✅ CORRECT - Async testing
+// ✅ CORRECT: Async testing with waitFor
 test('loads and displays events', async () => {
   render(<EventList />);
-  
   expect(screen.getByText(/loading/i)).toBeInTheDocument();
-  
-  await waitFor(() => {
-    expect(screen.getByText('Event 1')).toBeInTheDocument();
-  });
-  
+  await waitFor(() => expect(screen.getByText('Event 1')).toBeInTheDocument());
   expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
 });
 ```
@@ -213,11 +184,8 @@ test('loads and displays events', async () => {
 **MUST clean up resources:**
 
 ```tsx
-// ✅ CORRECT - Cleanup
-afterEach(() => {
-  cleanup();
-  vi.clearAllMocks();
-});
+// ✅ CORRECT: Cleanup after tests
+afterEach(() => { cleanup(); vi.clearAllMocks(); });
 ```
 
 ## SHOULD: Use Test Utilities
@@ -225,23 +193,11 @@ afterEach(() => {
 **SHOULD create reusable test utilities:**
 
 ```tsx
-// test-utils.tsx
-import { render } from '@testing-library/react';
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-
+// ✅ CORRECT: Reusable test utilities
 export function renderWithProviders(ui: React.ReactElement) {
-  return render(
-    <UnifiedAuthProvider supabaseClient={mockSupabase} appName="Test App">
-      {ui}
-    </UnifiedAuthProvider>
-  );
+  return render(<UnifiedAuthProvider supabaseClient={mockSupabase} appName="Test App">{ui}</UnifiedAuthProvider>);
 }
-
-// Usage
-test('component works with providers', () => {
-  renderWithProviders(<MyComponent />);
-  // ...
-});
+// Usage: renderWithProviders(<MyComponent />);
 ```
 
 ## MUST: Include Timeout Parameters
@@ -249,12 +205,9 @@ test('component works with providers', () => {
 **Tests MUST include timeout parameters to prevent hanging:**
 
 ```tsx
-// ✅ CORRECT - With timeout
+// ✅ CORRECT: Include timeout parameters to prevent hanging
 test('async operation completes', async () => {
-  await waitFor(
-    () => expect(screen.getByText('Loaded')).toBeInTheDocument(),
-    { timeout: 5000 }
-  );
+  await waitFor(() => expect(screen.getByText('Loaded')).toBeInTheDocument(), { timeout: 5000 });
 }, { timeout: 10000 });
 ```
 

package/cursor-rules/05-bug-reports-and-features.mdc

@@ -2,8 +2,8 @@
 description: Standardized templates for bug reports and feature requests for pace-core
 globs: []
 alwaysApply: false
-paceCoreVersion: "0.5.x"
-rulesVersion: "2025-01-15"
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
 ---
 # Bug Reports and Feature Requests Guide
 

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

@@ -1,9 +1,9 @@
 ---
 description: Enforce code quality standards including TypeScript, ESLint, formatting, performance, and accessibility
 globs: ["src/**/*.{ts,tsx,js,jsx}"]
-alwaysApply: true
-paceCoreVersion: "0.5.x"
-rulesVersion: "2025-01-15"
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
 ---
 # Code Quality Guide
 
@@ -36,27 +36,17 @@ This guide enforces code quality standards to ensure maintainable, performant, a
 **MUST NOT use `any` type. Use `unknown` if type is truly unknown:**
 
 ```tsx
-// ❌ WRONG - Using any
-function processData(data: any) {
-  return data.value;
-}
+// ❌ WRONG: Using any
+function processData(data: any) { return data.value; }
 
-// ✅ CORRECT - Using unknown with type guard
+// ✅ 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');
 }
-
-// ✅ CORRECT - Using proper types
-interface Data {
-  value: string;
-}
-
-function processData(data: Data) {
-  return data.value;
-}
+// Or: interface Data { value: string; } function processData(data: Data) { return data.value; }
 ```
 
 ### MUST: Use Discriminated Unions
@@ -64,18 +54,11 @@ function processData(data: Data) {
 **MUST use discriminated unions instead of boolean flags:**
 
 ```tsx
-// ❌ WRONG - Boolean flags
-interface User {
-  isAdmin: boolean;
-  isGuest: boolean;
-  // Confusing: what if both are true?
-}
+// ❌ 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 };
+// ✅ CORRECT: Discriminated union
+type User = { type: 'admin'; permissions: Permission[] } | { type: 'guest'; limitedAccess: boolean } | { type: 'user'; role: UserRole };
 ```
 
 ### SHOULD: Use ReadonlyArray
@@ -148,20 +131,10 @@ npm run format
 **SHOULD use React.memo, useMemo, useCallback appropriately:**
 
 ```tsx
-// ✅ CORRECT - Memoize expensive computations
-const expensiveValue = useMemo(() => {
-  return computeExpensiveValue(data);
-}, [data]);
-
-// ✅ CORRECT - Memoize callbacks
-const handleClick = useCallback(() => {
-  doSomething(id);
-}, [id]);
-
-// ✅ CORRECT - Memoize components
-const ExpensiveComponent = React.memo(({ data }) => {
-  return <div>{/* ... */}</div>;
-});
+// ✅ 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
@@ -169,18 +142,12 @@ const ExpensiveComponent = React.memo(({ data }) => {
 **SHOULD avoid causing unnecessary re-renders:**
 
 ```tsx
-// ❌ WRONG - New object on every render
-function Component({ items }) {
-  const config = { items, enabled: true }; // New object each render
-  return <Child config={config} />;
-}
+// ❌ 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
+// ✅ CORRECT: Memoize object
 function Component({ items }) {
-  const config = useMemo(
-    () => ({ items, enabled: true }),
-    [items]
-  );
+  const config = useMemo(() => ({ items, enabled: true }), [items]);
   return <Child config={config} />;
 }
 ```
@@ -190,17 +157,11 @@ function Component({ items }) {
 **SHOULD lazy load heavy components:**
 
 ```tsx
-// ✅ CORRECT - Lazy loading
+// ✅ CORRECT: Lazy load heavy components
 import { lazy, Suspense } from 'react';
-
 const HeavyComponent = lazy(() => import('./HeavyComponent'));
-
 function App() {
-  return (
-    <Suspense fallback={<Loading />}>
-      <HeavyComponent />
-    </Suspense>
-  );
+  return <Suspense fallback={<Loading />}><HeavyComponent /></Suspense>;
 }
 ```
 
@@ -211,11 +172,8 @@ function App() {
 **MUST use semantic HTML elements:**
 
 ```tsx
-// ❌ WRONG - Non-semantic
-<div onClick={handleClick}>Click me</div>
-
-// ✅ CORRECT - Semantic
-<button onClick={handleClick}>Click me</button>
+// ❌ WRONG: Non-semantic (<div onClick={...}>)
+// ✅ CORRECT: Semantic HTML (<button onClick={...}>)
 ```
 
 ### MUST: Provide ARIA Labels
@@ -223,7 +181,7 @@ function App() {
 **MUST provide ARIA labels for interactive elements:**
 
 ```tsx
-// ✅ CORRECT - ARIA labels
+// ✅ CORRECT: Provide ARIA labels for interactive elements
 <button aria-label="Close dialog">×</button>
 <input aria-label="Search" type="search" />
 ```
@@ -233,17 +191,8 @@ function App() {
 **MUST ensure all interactive elements are keyboard accessible:**
 
 ```tsx
-// ✅ CORRECT - Keyboard accessible
-<button
-  onClick={handleClick}
-  onKeyDown={(e) => {
-    if (e.key === 'Enter' || e.key === ' ') {
-      handleClick();
-    }
-  }}
->
-  Click me
-</button>
+// ✅ CORRECT: Ensure keyboard navigation (Enter or Space key)
+<button onClick={handleClick} onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') handleClick(); }}>Click me</button>
 ```
 
 ### MUST: Provide Focus Indicators
@@ -251,10 +200,8 @@ function App() {
 **MUST provide visible focus indicators:**
 
 ```tsx
-// ✅ CORRECT - Focus styles
-<button className="focus:outline-none focus:ring-2 focus:ring-main-500">
-  Click me
-</button>
+// ✅ CORRECT: Provide visible focus indicators
+<button className="focus:outline-none focus:ring-2 focus:ring-main-500">Click me</button>
 ```
 
 ## Code Review Checklist
@@ -281,20 +228,12 @@ function App() {
 **Functions SHOULD be small and focused:**
 
 ```tsx
-// ❌ WRONG - Large function
-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
-}
+// ❌ 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;
@@ -307,24 +246,11 @@ function processUserData(user: User) {
 **Functions SHOULD have low cyclomatic complexity (< 10):**
 
 ```tsx
-// ❌ WRONG - High complexity
-function processData(data) {
-  if (condition1) {
-    if (condition2) {
-      if (condition3) {
-        // ... many nested conditions
-      }
-    }
-  }
-}
+// ❌ WRONG: High complexity (many nested conditions)
+function processData(data) { if (condition1) { if (condition2) { if (condition3) { /* ... */ } } } }
 
-// ✅ CORRECT - Lower complexity
-function processData(data) {
-  if (!condition1) return;
-  if (!condition2) return;
-  if (!condition3) return;
-  // Process
-}
+// ✅ CORRECT: Lower complexity (early returns)
+function processData(data) { if (!condition1) return; if (!condition2) return; if (!condition3) return; /* Process */ }
 ```
 
 ## Error Handling
@@ -334,7 +260,7 @@ function processData(data) {
 **MUST handle errors and provide user feedback:**
 
 ```tsx
-// ✅ CORRECT - Error handling
+// ✅ CORRECT: Handle errors gracefully with user feedback
 try {
   const data = await fetchData();
   setData(data);
@@ -349,24 +275,15 @@ try {
 **MUST use type-safe error handling:**
 
 ```tsx
-// ✅ CORRECT - Type-safe errors
+// ✅ CORRECT: Type-safe error handling
 function isApiError(error: unknown): error is ApiError {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'code' in error &&
-    'message' in error
-  );
+  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);
-  }
+  if (isApiError(error)) handleApiError(error);
+  else handleUnknownError(error);
 }
 ```