@jmruthers/pace-core 0.5.191 → 0.6.1

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

@@ -0,0 +1,315 @@
+---
+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"
+---
+# Testing Standards Guide
+
+This guide ensures consistent, high-quality testing across consuming apps in the PACE suite.
+
+## MUST: Meet Coverage Requirements
+
+**MUST achieve minimum coverage:**
+- ≥90% coverage for utils & hooks
+- ≥70% coverage for components
+
+**Verify coverage:**
+```bash
+npm run test:coverage
+```
+
+## MUST: Use React Testing Library
+
+**MUST use React Testing Library + userEvent for all component tests.**
+
+```tsx
+// ✅ CORRECT - React Testing Library
+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';
+```
+
+## MUST: Colocate Tests
+
+**Tests MUST be colocated with source files:**
+
+```
+src/
+├── components/
+│   └── EventCard/
+│       ├── EventCard.tsx
+│       └── EventCard.test.tsx
+├── hooks/
+│   ├── useEventData.ts
+│   └── useEventData.test.ts
+└── utils/
+    ├── formatEvent.ts
+    └── formatEvent.test.ts
+```
+
+## MUST: Use Vitest
+
+**MUST use Vitest for all testing:**
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./vitest.setup.ts'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      thresholds: {
+        lines: 80,
+        functions: 80,
+        branches: 80,
+        statements: 80,
+      },
+    },
+  },
+});
+```
+
+## MUST: Test User Behavior, Not Implementation
+
+**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);
+});
+
+// ✅ CORRECT - Testing user behavior
+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();
+});
+```
+
+## MUST: Use Accessible Queries
+
+**MUST prefer accessible queries (byRole, byLabelText, etc.):**
+
+```tsx
+// ✅ CORRECT - Accessible queries
+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');
+```
+
+## SHOULD: Test Critical Paths
+
+**SHOULD test:**
+- User workflows and interactions
+- Error handling and edge cases
+- Form validation
+- Permission checks (RBAC)
+- Data loading states
+- Error states
+
+## SHOULD: Use Descriptive Test Names
+
+**Test names SHOULD describe behavior:**
+
+```tsx
+// ❌ WRONG - Vague
+test('button works', () => { ... });
+
+// ✅ CORRECT - Descriptive
+test('increments counter when increment button is clicked', () => { ... });
+test('displays error message when API call fails', () => { ... });
+```
+
+## SHOULD: Group Related Tests
+
+**SHOULD use `describe` blocks to group related tests:**
+
+```tsx
+describe('EventCard', () => {
+  describe('rendering', () => {
+    test('displays event title', () => { ... });
+    test('displays event date', () => { ... });
+  });
+  
+  describe('interactions', () => {
+    test('calls onEdit when edit button clicked', () => { ... });
+    test('calls onDelete when delete button clicked', () => { ... });
+  });
+});
+```
+
+## MUST: Avoid Unnecessary Mocks
+
+**MUST NOT mock unless necessary:**
+
+```tsx
+// ❌ WRONG - Unnecessary mock
+const mockFetch = vi.fn();
+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' }]));
+  })
+);
+```
+
+## MUST: Test Async Code Properly
+
+**MUST handle async operations correctly:**
+
+```tsx
+// ✅ CORRECT - Async testing
+test('loads and displays events', async () => {
+  render(<EventList />);
+  
+  expect(screen.getByText(/loading/i)).toBeInTheDocument();
+  
+  await waitFor(() => {
+    expect(screen.getByText('Event 1')).toBeInTheDocument();
+  });
+  
+  expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
+});
+```
+
+## MUST: Clean Up After Tests
+
+**MUST clean up resources:**
+
+```tsx
+// ✅ CORRECT - Cleanup
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+```
+
+## SHOULD: Use Test Utilities
+
+**SHOULD create reusable test utilities:**
+
+```tsx
+// test-utils.tsx
+import { render } from '@testing-library/react';
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+export function renderWithProviders(ui: React.ReactElement) {
+  return render(
+    <UnifiedAuthProvider supabaseClient={mockSupabase} appName="Test App">
+      {ui}
+    </UnifiedAuthProvider>
+  );
+}
+
+// Usage
+test('component works with providers', () => {
+  renderWithProviders(<MyComponent />);
+  // ...
+});
+```
+
+## MUST: Include Timeout Parameters
+
+**Tests MUST include timeout parameters to prevent hanging:**
+
+```tsx
+// ✅ CORRECT - With timeout
+test('async operation completes', async () => {
+  await waitFor(
+    () => expect(screen.getByText('Loaded')).toBeInTheDocument(),
+    { timeout: 5000 }
+  );
+}, { timeout: 10000 });
+```
+
+## Testing Checklist
+
+Before committing tests, verify:
+- [ ] Coverage meets requirements (≥90% utils, ≥70% components)
+- [ ] Using React Testing Library + userEvent
+- [ ] Tests are colocated with source files
+- [ ] Testing user behavior, not implementation
+- [ ] Using accessible queries (byRole, byLabelText)
+- [ ] Test names are descriptive
+- [ ] Related tests grouped with describe
+- [ ] No unnecessary mocks
+- [ ] Async code tested properly
+- [ ] Cleanup after tests
+- [ ] Timeout parameters included
+
+## Test Structure Template
+
+```tsx
+import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ComponentName } from './ComponentName';
+
+describe('ComponentName', () => {
+  beforeEach(() => {
+    // Setup
+  });
+  
+  afterEach(() => {
+    // Cleanup
+    vi.clearAllMocks();
+  });
+  
+  describe('rendering', () => {
+    test('renders correctly', () => {
+      render(<ComponentName />);
+      // Assertions
+    });
+  });
+  
+  describe('interactions', () => {
+    test('handles user interaction', async () => {
+      const user = userEvent.setup();
+      render(<ComponentName />);
+      // Test interaction
+    });
+  });
+});
+```
+
+## Reference
+
+- React Testing Library: https://testing-library.com/react
+- Vitest: https://vitest.dev
+- Testing Standards: See `06-testing-and-docs-standard.md` in pace-core docs

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

@@ -0,0 +1,246 @@
+---
+description: Standardized templates for bug reports and feature requests for pace-core
+globs: []
+alwaysApply: false
+paceCoreVersion: "0.5.x"
+rulesVersion: "2025-01-15"
+---
+# Bug Reports and Feature Requests Guide
+
+This guide provides standardized templates for reporting bugs and requesting features in pace-core. This is a reference guide - Cursor will use this for context when helping with issue reporting.
+
+## Identifying Issues
+
+### Is This a pace-core Issue?
+
+**Before reporting, determine if the issue is in pace-core or your consuming app:**
+
+1. **Check pace-core documentation** - Is the behavior documented?
+2. **Check pace-core source** - Can you find the relevant code?
+3. **Test in isolation** - Can you reproduce with minimal pace-core usage?
+4. **Check similar issues** - Has this been reported before?
+
+**If the issue is in your consuming app:**
+- Fix it locally
+- Don't file a pace-core issue
+
+**If the issue is in pace-core:**
+- Use the templates below to file an issue
+
+## Bug Report Template
+
+### Required Information
+
+```markdown
+## Bug Description
+[Clear, concise description of the bug]
+
+## Expected Behavior
+[What should happen]
+
+## Actual Behavior
+[What actually happens]
+
+## Steps to Reproduce
+1. [First step]
+2. [Second step]
+3. [Third step]
+...
+
+## Minimal Reproduction
+[Link to minimal reproduction or code snippet]
+
+## Environment
+- pace-core version: [e.g., 0.5.193]
+- React version: [e.g., 19.2.3]
+- Node version: [e.g., 20.10.0]
+- Browser: [e.g., Chrome 120]
+- OS: [e.g., macOS 14.2]
+
+## Code Example
+\`\`\`tsx
+// Minimal code that reproduces the issue
+import { Component } from '@jmruthers/pace-core';
+
+function App() {
+  return <Component />;
+}
+\`\`\`
+
+## Error Messages
+[Any error messages or console output]
+
+## Additional Context
+[Screenshots, videos, or other relevant information]
+```
+
+### Example Bug Report
+
+```markdown
+## Bug Description
+DataTable component throws error when `rbac` prop is missing, but error message is unclear.
+
+## Expected Behavior
+DataTable should either:
+1. Work without rbac prop (if not required), OR
+2. Show clear error message explaining rbac is required
+
+## Actual Behavior
+DataTable throws: "Cannot read property 'pageId' of undefined" with no context about missing rbac prop.
+
+## Steps to Reproduce
+1. Import DataTable from pace-core
+2. Use DataTable without rbac prop
+3. See error in console
+
+## Minimal Reproduction
+\`\`\`tsx
+import { DataTable } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <DataTable
+      data={[]}
+      columns={[]}
+      // Missing rbac prop
+    />
+  );
+}
+\`\`\`
+
+## Environment
+- pace-core version: 0.5.193
+- React version: 19.2.3
+- Node version: 20.10.0
+- Browser: Chrome 120
+- OS: macOS 14.2
+
+## Error Messages
+```
+Uncaught TypeError: Cannot read property 'pageId' of undefined
+    at DataTable (DataTable.tsx:123)
+```
+
+## Additional Context
+The error occurs immediately on render. The documentation mentions rbac is required, but the error doesn't reference this.
+```
+
+## Feature Request Template
+
+### Required Information
+
+```markdown
+## Feature Description
+[Clear, concise description of the feature]
+
+## Problem Statement
+[What problem does this solve? Why is it needed?]
+
+## Proposed Solution
+[How should this work? What would the API look like?]
+
+## Use Case
+[Real-world scenario where this would be useful]
+
+## Alternatives Considered
+[Other approaches you've considered]
+
+## Code Example
+\`\`\`tsx
+// How you would use this feature
+import { NewFeature } from '@jmruthers/pace-core';
+
+function App() {
+  return <NewFeature prop="value" />;
+}
+\`\`\`
+
+## Additional Context
+[Screenshots, mockups, or other relevant information]
+```
+
+### Example Feature Request
+
+```markdown
+## Feature Description
+Add `onRowDoubleClick` prop to DataTable component for double-click row interactions.
+
+## Problem Statement
+Currently, DataTable only supports single-click row selection. Many users expect double-click to open/edit a row, which is a common pattern in data tables.
+
+## Proposed Solution
+Add optional `onRowDoubleClick` callback prop:
+- Fires when user double-clicks a row
+- Receives row data and event
+- Works alongside existing selection behavior
+
+## Use Case
+In an event management app, users want to double-click an event row to open the event details modal, while single-click selects the row for bulk operations.
+
+## Alternatives Considered
+1. Using `onRowClick` and detecting double-clicks - but this conflicts with selection
+2. Custom row component - but this loses DataTable features
+3. External double-click handler - but this is less integrated
+
+## Code Example
+\`\`\`tsx
+import { DataTable } from '@jmruthers/pace-core';
+
+function EventList() {
+  const handleRowDoubleClick = (row: Event) => {
+    openEventDetails(row.id);
+  };
+  
+  return (
+    <DataTable
+      data={events}
+      columns={columns}
+      rbac={{ pageName: 'events' }}
+      onRowDoubleClick={handleRowDoubleClick}
+    />
+  );
+}
+\`\`\`
+
+## Additional Context
+This is a common pattern in enterprise data tables. Many similar libraries support this.
+```
+
+## Where to File Issues
+
+**File issues in the pace-core repository:**
+- GitHub Issues: [Repository URL]
+- Include all required information from templates
+- Use appropriate labels if available
+
+## Before Filing
+
+**Check:**
+- [ ] Issue hasn't been reported already
+- [ ] You're using the latest pace-core version
+- [ ] Issue is actually in pace-core (not your app)
+- [ ] You've checked documentation
+- [ ] You have a minimal reproduction
+- [ ] You've included all required information
+
+## After Filing
+
+**Be prepared to:**
+- Provide additional information if requested
+- Test fixes in development versions
+- Verify the fix works in your app
+- Close the issue if resolved
+
+## Tips for Effective Reports
+
+1. **Be specific** - Vague descriptions waste time
+2. **Include reproduction** - Minimal code that shows the issue
+3. **Check existing issues** - Don't duplicate reports
+4. **Be patient** - Maintainers are volunteers
+5. **Be respectful** - Constructive feedback helps
+
+## Reference
+
+- pace-core Documentation: `packages/core/docs/`
+- pace-core Source: `packages/core/src/`
+- GitHub Issues: [Repository URL]