@jmruthers/pace-core 0.6.1 → 0.6.3

package/cursor-rules/03-solid-principles.mdc

@@ -1,9 +1,9 @@
 ---
 description: Enforce SOLID architecture principles in consuming apps
 globs: ["src/**/*.{ts,tsx}"]
-alwaysApply: true
-paceCoreVersion: "0.5.x"
-rulesVersion: "2025-01-15"
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
 ---
 # SOLID Principles Guide
 
@@ -18,36 +18,19 @@ This guide enforces SOLID architecture principles to ensure maintainable, extens
 **Each function/component SHOULD do one thing:**
 
 ```tsx
-// ❌ WRONG - Multiple responsibilities
-function UserProfile({ userId }: { userId: string }) {
+// ❌ WRONG: Multiple responsibilities (fetching, formatting, rendering in one component)
+function UserProfile({ userId }) {
   const [user, setUser] = useState(null);
   const [events, setEvents] = useState([]);
-  
-  useEffect(() => {
-    // Fetching user
-    fetchUser(userId).then(setUser);
-    // Fetching events
-    fetchEvents(userId).then(setEvents);
-    // Formatting data
-    const formatted = formatUserData(user);
-    // Rendering UI
-    return <div>...</div>;
-  }, [userId]);
-  
+  useEffect(() => { fetchUser(userId).then(setUser); fetchEvents(userId).then(setEvents); }, [userId]);
   return <div>...</div>;
 }
 
-// ✅ CORRECT - Separated responsibilities
-function UserProfile({ userId }: { userId: string }) {
+// ✅ CORRECT: Separated responsibilities (hooks for data, components for UI)
+function UserProfile({ userId }) {
   const user = useUser(userId);
   const events = useUserEvents(userId);
-  
-  return (
-    <div>
-      <UserInfo user={user} />
-      <UserEvents events={events} />
-    </div>
-  );
+  return <div><UserInfo user={user} /><UserEvents events={events} /></div>;
 }
 ```
 
@@ -56,37 +39,19 @@ function UserProfile({ userId }: { userId: string }) {
 **Complex logic SHOULD be extracted into hooks, services, or utilities:**
 
 ```tsx
-// ❌ WRONG - Business logic in component
+// ❌ WRONG: Business logic in component (filtering, sorting, formatting)
 function EventList() {
   const [events, setEvents] = useState([]);
   const [filtered, setFiltered] = useState([]);
-  
-  useEffect(() => {
-    fetchEvents().then(setEvents);
-  }, []);
-  
-  useEffect(() => {
-    const filtered = events
-      .filter(e => e.status === 'active')
-      .sort((a, b) => a.date - b.date)
-      .map(e => ({ ...e, formattedDate: formatDate(e.date) }));
-    setFiltered(filtered);
-  }, [events]);
-  
+  useEffect(() => { /* complex filtering/sorting logic */ }, [events]);
   return <div>{filtered.map(...)}</div>;
 }
 
-// ✅ CORRECT - Logic in hook
+// ✅ CORRECT: Logic extracted to hook
 function useFilteredEvents() {
   const events = useEvents();
-  return useMemo(() => {
-    return events
-      .filter(e => e.status === 'active')
-      .sort((a, b) => a.date - b.date)
-      .map(e => ({ ...e, formattedDate: formatDate(e.date) }));
-  }, [events]);
+  return useMemo(() => events.filter(...).sort(...).map(...), [events]);
 }
-
 function EventList() {
   const filteredEvents = useFilteredEvents();
   return <div>{filteredEvents.map(...)}</div>;
@@ -102,28 +67,16 @@ function EventList() {
 **Extend functionality through composition, not modification:**
 
 ```tsx
-// ❌ WRONG - Modifying base component
-function BaseButton({ onClick, ...props }) {
-  return <button onClick={onClick} {...props} />;
-}
-
+// ❌ WRONG: Modifying base component behavior
 function SpecialButton({ onClick, ...props }) {
-  // Modifying base behavior
-  const handleClick = (e) => {
-    trackEvent('button-click');
-    onClick?.(e);
-  };
-  return <BaseButton onClick={handleClick} {...props} />;
+  const handleClick = (e) => { trackEvent('button-click'); onClick?.(e); };
+  return <BaseButton onClick={handleClick} {...props} />; // Modifies base
 }
 
-// ✅ CORRECT - Composition with pace-core
+// ✅ CORRECT: Composition with pace-core (extend, don't modify)
 import { Button } from '@jmruthers/pace-core';
-
 function SpecialButton({ onClick, ...props }) {
-  const handleClick = (e) => {
-    trackEvent('button-click');
-    onClick?.(e);
-  };
+  const handleClick = (e) => { trackEvent('button-click'); onClick?.(e); };
   return <Button onClick={handleClick} {...props} />;
 }
 ```
@@ -133,13 +86,8 @@ function SpecialButton({ onClick, ...props }) {
 **Extend behavior through configuration:**
 
 ```tsx
-// ✅ CORRECT - Configurable behavior
-interface DataTableConfig {
-  columns: Column[];
-  features: FeatureConfig;
-  rbac: RBACConfig;
-}
-
+// ✅ CORRECT: Extend through configuration, not code changes
+interface DataTableConfig { columns: Column[]; features: FeatureConfig; rbac: RBACConfig; }
 function MyDataTable({ config }: { config: DataTableConfig }) {
   return <DataTable {...config} />;
 }
@@ -154,22 +102,12 @@ function MyDataTable({ config }: { config: DataTableConfig }) {
 **Derived components/hooks MUST maintain the same interface:**
 
 ```tsx
-// ✅ CORRECT - Maintains interface
-interface BaseHook {
-  data: Data | null;
-  isLoading: boolean;
-  error: Error | null;
-}
-
+// ✅ CORRECT: Derived hooks maintain same interface (substitutable)
+interface BaseHook { data: Data | null; isLoading: boolean; error: Error | null; }
 function useBaseData(): BaseHook { ... }
-
 function useExtendedData(): BaseHook {
   const base = useBaseData();
-  // Extends but maintains same interface
-  return {
-    ...base,
-    // Additional properties are optional
-  };
+  return { ...base }; // Maintains interface, extends behavior
 }
 ```
 
@@ -182,7 +120,7 @@ function useExtendedData(): BaseHook {
 **Interfaces SHOULD be small and focused:**
 
 ```tsx
-// ❌ WRONG - Large interface
+// ❌ WRONG: Large interface with many responsibilities
 interface UserService {
   getUser(id: string): Promise<User>;
   createUser(data: UserData): Promise<User>;
@@ -190,24 +128,12 @@ interface UserService {
   deleteUser(id: string): Promise<void>;
   getUserEvents(id: string): Promise<Event[]>;
   getUserOrganisations(id: string): Promise<Organisation[]>;
-  // ... many more methods
-}
-
-// ✅ CORRECT - Segregated interfaces
-interface UserReader {
-  getUser(id: string): Promise<User>;
-  getUserEvents(id: string): Promise<Event[]>;
 }
 
-interface UserWriter {
-  createUser(data: UserData): Promise<User>;
-  updateUser(id: string, data: Partial<User>): Promise<User>;
-  deleteUser(id: string): Promise<void>;
-}
-
-interface UserOrganisationService {
-  getUserOrganisations(id: string): Promise<Organisation[]>;
-}
+// ✅ CORRECT: Segregated interfaces (focused, specific)
+interface UserReader { getUser(id: string): Promise<User>; getUserEvents(id: string): Promise<Event[]>; }
+interface UserWriter { createUser(data: UserData): Promise<User>; updateUser(id: string, data: Partial<User>): Promise<User>; deleteUser(id: string): Promise<void>; }
+interface UserOrganisationService { getUserOrganisations(id: string): Promise<Organisation[]>; }
 ```
 
 ### SHOULD: Use Specific Props
@@ -215,22 +141,12 @@ interface UserOrganisationService {
 **Component props SHOULD be specific, not generic:**
 
 ```tsx
-// ❌ WRONG - Generic props object
-function UserCard({ user, config }: { user: User; config: any }) {
-  // ...
-}
-
-// ✅ CORRECT - Specific props
-interface UserCardProps {
-  user: User;
-  showEmail?: boolean;
-  showAvatar?: boolean;
-  onEdit?: (user: User) => void;
-}
+// ❌ WRONG: Generic props object (config: any)
+function UserCard({ user, config }: { user: User; config: any }) { ... }
 
-function UserCard({ user, showEmail, showAvatar, onEdit }: UserCardProps) {
-  // ...
-}
+// ✅ CORRECT: Specific, focused props interface
+interface UserCardProps { user: User; showEmail?: boolean; showAvatar?: boolean; onEdit?: (user: User) => void; }
+function UserCard({ user, showEmail, showAvatar, onEdit }: UserCardProps) { ... }
 ```
 
 ## Dependency Inversion Principle (DIP)
@@ -242,50 +158,25 @@ function UserCard({ user, showEmail, showAvatar, onEdit }: UserCardProps) {
 **Depend on interfaces/types, not concrete implementations:**
 
 ```tsx
-// ❌ WRONG - Direct dependency on implementation
+// ❌ WRONG: Direct dependency on implementation (tight coupling)
 function UserService() {
   const supabase = useSecureSupabase();
-  
   async function getUser(id: string) {
-    const { data } = await supabase
-      .from('users')
-      .select('*')
-      .eq('id', id)
-      .single();
+    const { data } = await supabase.from('users').select('*').eq('id', id).single();
     return data;
   }
-  
   return { getUser };
 }
 
-// ✅ CORRECT - Abstracted interface
-interface UserRepository {
-  getUser(id: string): Promise<User | null>;
-}
-
+// ✅ CORRECT: Abstracted interface (depend on abstraction)
+interface UserRepository { getUser(id: string): Promise<User | null>; }
 function createUserRepository(supabase: SupabaseClient): UserRepository {
-  return {
-    async getUser(id: string) {
-      const { data } = await supabase
-        .from('users')
-        .select('*')
-        .eq('id', id)
-        .single();
-      return data;
-    }
-  };
+  return { async getUser(id: string) { /* implementation */ } };
 }
-
 function useUserService() {
   const supabase = useSecureSupabase();
-  const repository = useMemo(
-    () => createUserRepository(supabase),
-    [supabase]
-  );
-  
-  return {
-    getUser: repository.getUser,
-  };
+  const repository = useMemo(() => createUserRepository(supabase), [supabase]);
+  return { getUser: repository.getUser };
 }
 ```
 
@@ -294,22 +185,12 @@ function useUserService() {
 **Inject dependencies rather than creating them:**
 
 ```tsx
-// ❌ WRONG - Hard-coded dependency
-function EventService() {
-  const api = new ApiClient('https://api.example.com');
-  // ...
-}
+// ❌ WRONG: Hard-coded dependency
+function EventService() { const api = new ApiClient('https://api.example.com'); }
 
-// ✅ CORRECT - Injected dependency
-function EventService(api: ApiClient) {
-  // ...
-}
-
-// Or with React context
-function useEventService() {
-  const api = useApiClient(); // From context
-  return useMemo(() => new EventService(api), [api]);
-}
+// ✅ CORRECT: Injected dependency (dependency injection)
+function EventService(api: ApiClient) { ... }
+// Or with React context: const api = useApiClient(); useMemo(() => new EventService(api), [api]);
 ```
 
 ## SOLID Checklist

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