@jmruthers/pace-core 0.6.5 → 0.6.7

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

@@ -1,268 +0,0 @@
----
-description: Enforce testing framework consistency and standards for consuming apps
-globs: ["**/*.{test,spec}.{ts,tsx}"]
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# 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 + userEvent
-import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-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
-```
-
-## 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 (component.state.count)
-test('calls setState', () => { const component = render(<Counter />); expect(component.state.count).toBe(0); });
-
-// ✅ 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();
-});
-```
-
-## MUST: Use Accessible Queries
-
-**MUST prefer accessible queries (byRole, byLabelText, etc.):**
-
-```tsx
-// ✅ CORRECT: Accessible queries (byRole, byLabelText, byText)
-screen.getByRole('button', { name: /submit/i });
-screen.getByLabelText(/email address/i);
-
-// ❌ AVOID: Non-accessible queries (getByTestId, getByClassName - use as last resort)
-```
-
-## 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 (global.fetch = mockFetch)
-// ✅ CORRECT: Use real implementation or MSW
-import { server } from './mocks/server';
-server.use(rest.get('/api/events', (req, res, ctx) => res(ctx.json([{ id: '1', name: 'Event' }]))));
-```
-
-## MUST: Test Async Code Properly
-
-**MUST handle async operations correctly:**
-
-```tsx
-// ✅ 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());
-  expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
-});
-```
-
-## MUST: Clean Up After Tests
-
-**MUST clean up resources:**
-
-```tsx
-// ✅ CORRECT: Cleanup after tests
-afterEach(() => { cleanup(); vi.clearAllMocks(); });
-```
-
-## SHOULD: Use Test Utilities
-
-**SHOULD create reusable test utilities:**
-
-```tsx
-// ✅ CORRECT: Reusable test utilities
-export function renderWithProviders(ui: React.ReactElement) {
-  return render(<UnifiedAuthProvider supabaseClient={mockSupabase} appName="Test App">{ui}</UnifiedAuthProvider>);
-}
-// Usage: renderWithProviders(<MyComponent />);
-```
-
-## MUST: Include Timeout Parameters
-
-**Tests MUST include timeout parameters to prevent hanging:**
-
-```tsx
-// ✅ CORRECT: Include timeout parameters to prevent hanging
-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

@@ -1,246 +0,0 @@
----
-description: Standardized templates for bug reports and feature requests for pace-core
-globs: []
-alwaysApply: false
-paceCoreVersion: "0.6.x"
-rulesVersion: "2025-01-28"
----
-# 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]