@jmruthers/pace-core 0.5.193 → 0.6.2

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.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]

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

@@ -0,0 +1,309 @@
+---
+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
+
+This guide enforces code quality standards to ensure maintainable, performant, and accessible code.
+
+## 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
+
+### MUST: Use pace-core ESLint Config
+
+**MUST extend pace-core ESLint configuration:**
+
+```javascript
+// eslint.config.js
+import paceCoreConfig from '@jmruthers/pace-core/eslint-config';
+
+export default [
+  ...paceCoreConfig,
+  // Your additional config
+];
+```
+
+### MUST: Fix ESLint Errors
+
+**MUST fix all ESLint errors before committing:**
+
+```bash
+npm run lint
+npm run lint:fix  # Auto-fix where possible
+```
+
+## 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: Use Semantic HTML
+
+**MUST use semantic HTML elements:**
+
+```tsx
+// ❌ WRONG: Non-semantic (<div onClick={...}>)
+// ✅ CORRECT: Semantic HTML (<button onClick={...}>)
+```
+
+### MUST: Provide ARIA Labels
+
+**MUST provide ARIA labels for interactive elements:**
+
+```tsx
+// ✅ CORRECT: Provide ARIA labels for interactive elements
+<button aria-label="Close dialog">×</button>
+<input aria-label="Search" type="search" />
+```
+
+### MUST: Ensure Keyboard Navigation
+
+**MUST ensure all interactive elements are keyboard accessible:**
+
+```tsx
+// ✅ 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
+
+**MUST provide visible focus indicators:**
+
+```tsx
+// ✅ CORRECT: Provide visible focus indicators
+<button className="focus:outline-none focus:ring-2 focus:ring-main-500">Click me</button>
+```
+
+## 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);
+}
+```
+
+## Code Quality Checklist
+
+Before committing, verify:
+- [ ] TypeScript strict mode enabled
+- [ ] No `any` types
+- [ ] ESLint passes
+- [ ] Code formatted
+- [ ] Performance optimized
+- [ ] Accessible (semantic HTML, ARIA, keyboard)
+- [ ] Functions are small and focused
+- [ ] Error handling in place
+- [ ] Code is readable
+- [ ] Comments explain "why"
+
+## Reference
+
+- TypeScript Handbook: https://www.typescriptlang.org/docs/
+- ESLint Rules: pace-core eslint-config
+- React Performance: https://react.dev/learn/render-and-commit
+- Web Accessibility: https://www.w3.org/WAI/