@jmruthers/pace-core 0.6.5 → 0.6.7

package/cursor-rules/07-api-tech-stack.mdc

@@ -0,0 +1,377 @@
+---
+description: Enforce tech stack compliance, API/RPC naming conventions, and Vite configuration patterns
+globs: ["src/**/*.{ts,tsx,js,jsx,css}", "*.config.{ts,js}", "supabase/migrations/**/*.sql"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# API & Tech Stack Standards Guide
+
+**📚 Human-Readable Standard**: See [7-api-tech-stack-standards.md](../../packages/core/docs/standards/7-api-tech-stack-standards.md) for complete documentation.
+
+This guide ensures consuming apps use the correct versions and patterns for all technologies in the PACE stack, and follow API/RPC naming conventions.
+
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Use Tailwind v4 CSS-first** - Use `@import 'tailwindcss'` and `@theme`, never `@tailwind` directives
+2. **Use theme variables** - Never use bracket syntax like `bg-[oklch(...)]`, always use theme variables (`bg-main-500`)
+3. **Use custom color namespaces** - Always use `main-*`, `sec-*`, `acc-*`, never standard Tailwind colors
+4. **Follow RPC naming** - Read operations: `data_*`, write operations: `app_*`, verbs: `create`, `read`, `update`, `delete`, `list`, `get`
+5. **Return ApiResult** - All RPCs must return ApiResult shape with proper error handling
+6. **Use TanStack Query** - Always use TanStack Query for server state, never `useState + useEffect`
+7. **Use React Hook Form + Zod** - Always use `useZodForm` from pace-core for forms
+
+**Decision Tree: RPC Naming**
+```
+1. What operation is this?
+   ├─ Read (SELECT) → data_<domain>_<verb>
+   ├─ Write (INSERT/UPDATE/DELETE) → app_<domain>_<verb>
+   └─ Bulk operation → app_<domain>_<verb>_bulk
+
+2. What verb should I use?
+   ├─ Get single item → get
+   ├─ Get multiple items → list
+   ├─ Create → create
+   ├─ Update → update
+   ├─ Delete → delete
+   └─ Read (generic) → read
+```
+
+**Decision Tree: Styling**
+```
+1. What am I styling?
+   ├─ Component → Use pace-core component (already styled)
+   ├─ Layout → Use Tailwind utilities (grid, flex, gap)
+   └─ Custom → Use theme variables (main-*, sec-*, acc-*)
+
+2. Do I need a color?
+   ├─ YES → Use theme variable (bg-main-500, text-sec-700)
+   └─ NO → Use semantic class (bg-background, text-foreground)
+
+3. Am I using bracket syntax?
+   ├─ YES → WRONG - Use theme variable instead
+   └─ NO → Continue
+```
+
+## Tailwind CSS v4
+
+### MUST: Use Tailwind v4 CSS-First Approach
+
+**MUST use Tailwind v4 CSS-first syntax, NOT v3 patterns:**
+
+```css
+/* ✅ CORRECT: Tailwind v4 CSS-first (@import 'tailwindcss'; @theme { ... }) */
+/* ❌ WRONG: Tailwind v3 (@tailwind base/components/utilities directives) */
+```
+
+### MUST NOT: Use Bracket Syntax
+
+**MUST NOT use bracket syntax like `bg-[oklch(...)]`. Map everything through theme variables:**
+
+```tsx
+// ❌ WRONG: Bracket syntax (bg-[oklch(...)])
+// ✅ CORRECT: Theme variable (bg-main-500)
+```
+
+### MUST: Use Custom Color Namespaces
+
+**MUST use custom color namespaces:**
+- `main-*` for primary colors (green, emerald, teal, cyan, sky, blue)
+- `sec-*` for secondary colors (indigo, violet, purple, fuchsia, slate, gray, zinc, neutral, stone)
+- `acc-*` for accent colors (red, orange, amber, yellow, lime, pink, rose)
+
+```tsx
+// ✅ CORRECT: Custom namespaces (main-*, sec-*, acc-*)
+// ❌ WRONG: Standard Tailwind colors (blue-*, gray-*, red-*)
+```
+
+### MUST: Use Semantic Classes
+
+**MUST use semantic classes mapped in index.css:**
+
+```tsx
+// ✅ CORRECT - Semantic classes
+<div className="bg-background text-foreground">
+
+// ❌ WRONG - Direct color classes (unless necessary)
+<div className="bg-main-50 text-main-950">
+```
+
+## React 19+
+
+### MUST: Use React 19+ Features
+
+**MUST use React 19+ patterns:**
+
+```tsx
+// ✅ CORRECT: React 19+ features (Suspense, useTransition, etc.)
+import { Suspense, useTransition } from 'react';
+function App() {
+  const [isPending, startTransition] = useTransition();
+  return <Suspense fallback={<Loading />}><Component /></Suspense>;
+}
+```
+
+### MUST: Use Functional Components
+
+**MUST use functional components with hooks exclusively:**
+
+```tsx
+// ✅ CORRECT: Functional components with hooks
+function MyComponent() { const [state, setState] = useState(); return <div>...</div>; }
+
+// ❌ WRONG: Class components
+```
+
+## Supabase
+
+### MUST: Use Secure Supabase Client
+
+**MUST use `useSecureSupabase()` for all database operations:**
+
+```tsx
+// ✅ CORRECT: useSecureSupabase() from '@jmruthers/pace-core/rbac'
+// ❌ WRONG: createClient() from '@supabase/supabase-js' (base client)
+```
+
+### MUST: Enforce RLS
+
+**MUST ensure RLS is enabled on all tables. Never bypass RLS.**
+
+### SHOULD: Use RPC Functions
+
+**SHOULD use RPC functions for complex queries:**
+
+```tsx
+// ✅ CORRECT: RPC functions for complex queries
+const { data } = await secureSupabase.rpc('data_events_list', { organisation_id: orgId });
+
+// ❌ AVOID: Complex client-side queries with many joins
+```
+
+## TanStack Query
+
+### MUST: Use TanStack Query for Server State
+
+**MUST use TanStack Query for all server state management:**
+
+```tsx
+// ✅ CORRECT: TanStack Query for server state
+import { useQuery, useMutation } from '@tanstack/react-query';
+const { data, isLoading } = useQuery({ queryKey: ['events', orgId], queryFn: () => fetchEvents(orgId) });
+
+// ❌ WRONG: useState + useEffect for server state
+```
+
+### SHOULD: Configure Query Client
+
+**SHOULD configure QueryClient with appropriate defaults:**
+
+```tsx
+// ✅ CORRECT: Configure QueryClient with appropriate defaults (staleTime, cacheTime, retry)
+const queryClient = new QueryClient({ defaultOptions: { queries: { staleTime: 5 * 60 * 1000, cacheTime: 10 * 60 * 1000, retry: 1 } } });
+```
+
+## React Hook Form + Zod
+
+### MUST: Use React Hook Form with Zod
+
+**MUST use React Hook Form with Zod for all forms:**
+
+```tsx
+// ✅ CORRECT: React Hook Form + Zod (useZodForm from pace-core)
+import { useZodForm } from '@jmruthers/pace-core';
+const schema = z.object({ email: z.string().email(), name: z.string().min(1) });
+const form = useZodForm(schema);
+
+// ❌ WRONG: Manual form handling (useState for form state)
+```
+
+## Vite Configuration
+
+### MUST: Use Vite for Build Tooling
+
+**MUST use Vite for all build tooling:**
+
+```typescript
+// ✅ CORRECT: Vite for build tooling
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+export default defineConfig({ plugins: [react()] });
+```
+
+### MUST: Configure Vite for pace-core
+
+**⚠️ CRITICAL: Vite configuration prevents React context mismatches!**
+
+**MUST** configure Vite to exclude `@jmruthers/pace-core` and `react-router-dom` from pre-bundling:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+    // CRITICAL: Dedupe React dependencies
+    dedupe: ['react', 'react-dom', 'react-router-dom'],
+  },
+  optimizeDeps: {
+    include: [
+      'react',
+      'react-dom',
+      'react/jsx-runtime',
+    ],
+    // CRITICAL: Exclude pace-core to prevent React context mismatches
+    exclude: ['@jmruthers/pace-core', 'react-router-dom'],
+  },
+});
+```
+
+**Why this matters:**
+- Pre-bundling `@jmruthers/pace-core` creates separate React instances
+- This causes "useUnifiedAuth must be used within a UnifiedAuthProvider" errors
+- Excluding it ensures pace-core uses the same React instance as your app
+- `react-router-dom` must also be excluded and deduped to prevent Router context errors
+
+### MUST: Use Environment Variables Correctly
+
+**MUST use `import.meta.env` for environment variables:**
+
+```tsx
+// ✅ CORRECT: import.meta.env.VITE_API_URL (Vite env vars)
+// ❌ WRONG: process.env.VITE_API_URL (Node.js env vars)
+```
+
+## API & RPC Patterns
+
+### MUST: Follow RPC Naming Convention
+
+**RPCs MUST follow pattern: `<family>_<domain>_<verb>`**
+
+- `data_*` prefix for read operations: `data_events_list`, `data_file_reference_list`
+- `app_*` prefix for write operations: `app_event_create`, `app_event_update`
+- CRUD verbs only: `create`, `read`, `update`, `delete`, `list`, `get`
+- Bulk operations: `_bulk` suffix (e.g., `app_event_create_bulk`)
+
+```sql
+-- ✅ CORRECT: data_events_list, app_event_create, app_event_create_bulk
+-- ❌ WRONG: getEvents, create_event (wrong naming pattern)
+```
+
+### MUST: Use ApiResult Shape
+
+**All RPCs MUST return ApiResult shape:**
+
+```typescript
+type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError };
+type ApiError = { code: string; message: string; details?: object };
+```
+
+```tsx
+// ✅ CORRECT: Handle ApiResult
+const result = await supabase.rpc('app_events_create', { name, date });
+if (!result.ok) {
+  // Handle error
+  return { ok: false, error: result.error };
+}
+return { ok: true, data: result.data };
+```
+
+### MUST: Enforce RLS in RPCs
+
+**RPCs MUST enforce RLS and tenant boundaries.** Never bypass RLS.
+
+### SHOULD: Make Write RPCs Idempotent
+
+**Write RPCs SHOULD be idempotent when possible:**
+
+```sql
+-- ✅ CORRECT: Idempotent create (ON CONFLICT DO NOTHING)
+INSERT INTO events (id, name, date)
+VALUES (p_event_id, p_name, p_date)
+ON CONFLICT (id) DO NOTHING;
+```
+
+## TypeScript
+
+**Note**: TypeScript configuration details are handled by ESLint and the standards. See [7-api-tech-stack-standards.md](../../packages/core/docs/standards/7-api-tech-stack-standards.md) for complete TypeScript setup.
+
+**MUST:**
+- Use TypeScript 5+ with strict mode
+- Follow TypeScript patterns from [4-code-quality-standards.md](../../packages/core/docs/standards/4-code-quality-standards.md)
+
+## Version Requirements
+
+### MUST: Use Required Versions
+
+**MUST use compatible versions:**
+
+- React: `^19.0.0`
+- TypeScript: `^5.0.0`
+- Tailwind CSS: `^4.0.0`
+- Vite: `^6.0.0`
+- Supabase: `^2.49.0+`
+
+**Check `package.json` for exact versions required by pace-core.**
+
+## Common Mistakes to Avoid
+
+**When writing code, NEVER:**
+1. **Use Tailwind v3 patterns** - Always use v4 CSS-first syntax
+   ```css
+   /* ❌ WRONG */
+   @tailwind base;
+   @tailwind components;
+   @tailwind utilities;
+   
+   /* ✅ CORRECT */
+   @import "tailwindcss";
+   @theme { /* ... */ }
+   ```
+
+2. **Use bracket syntax for colors** - Always use theme variables
+   ```tsx
+   // ❌ WRONG
+   <div className="bg-[oklch(0.5 0.2 250)]">
+   
+   // ✅ CORRECT
+   <div className="bg-main-500">
+   ```
+
+3. **Use standard Tailwind colors** - Always use custom namespaces (main-*, sec-*, acc-*)
+4. **Use useState + useEffect for server state** - Always use TanStack Query
+5. **Create RPCs without ApiResult** - Always return ApiResult shape
+6. **Use wrong RPC naming** - Always follow `data_*` or `app_*` pattern
+
+## Tech Stack Checklist
+
+Before committing, verify:
+- [ ] Tailwind v4 CSS-first syntax (no @tailwind directives)
+- [ ] No bracket syntax for colors (use theme variables)
+- [ ] Custom color namespaces (main-*, sec-*, acc-*)
+- [ ] React 19+ functional components
+- [ ] Secure Supabase client (useSecureSupabase)
+- [ ] TanStack Query for server state
+- [ ] React Hook Form + Zod for forms
+- [ ] Vite configured correctly (optimizeDeps.exclude, resolve.dedupe)
+- [ ] TypeScript 5+ with strict mode
+- [ ] All versions compatible with pace-core
+- [ ] RPCs follow naming convention (data_* or app_*)
+- [ ] RPCs return ApiResult shape
+- [ ] RPCs enforce RLS
+
+## Reference
+
+- Tailwind v4: https://tailwindcss.com/blog/tailwindcss-v4
+- React 19: https://react.dev/blog/2024/04/25/react-19-upgrade-guide
+- Supabase: https://supabase.com/docs
+- TanStack Query: https://tanstack.com/query
+- React Hook Form: https://react-hook-form.com
+- Vite: https://vitejs.dev

package/cursor-rules/08-testing-documentation.mdc

@@ -0,0 +1,324 @@
+---
+description: Enforce testing standards, documentation requirements, and issue reporting templates
+globs: ["**/*.{test,spec}.{ts,tsx}", "**/*.md", "**/*.mdx"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Testing & Documentation Standards Guide
+
+**📚 Human-Readable Standard**: See [8-testing-documentation-standards.md](../../packages/core/docs/standards/8-testing-documentation-standards.md) for complete documentation including coverage requirements, test timeouts, and documentation templates.
+
+This guide ensures consistent, high-quality testing and documentation across consuming apps in the PACE suite.
+
+## AI Agent Instructions
+
+**When writing or modifying tests, ALWAYS:**
+1. **Use React Testing Library** - Always use `@testing-library/react` and `userEvent`, never Enzyme or other libraries
+2. **Test user behavior** - Test what users see and do, not implementation details
+3. **Use accessible queries** - Prefer `getByRole`, `getByLabelText` over `getByTestId`
+4. **Include timeouts** - Always include timeout parameters to prevent tests from hanging
+5. **Colocate tests** - Place test files next to source files (`Component.test.tsx` next to `Component.tsx`)
+6. **Use descriptive names** - Test names should clearly describe the behavior being tested
+7. **Group related tests** - Use `describe` blocks to organize related tests
+
+**Decision Tree: Writing Tests**
+```
+1. What am I testing?
+   ├─ Component → Use React Testing Library + userEvent
+   ├─ Hook → Test hook in isolation with renderHook
+   ├─ Utility → Test pure function directly
+   └─ Integration → Test user workflows end-to-end
+
+2. How do I query elements?
+   ├─ Interactive element → getByRole (preferred)
+   ├─ Form field → getByLabelText (preferred)
+   ├─ Text content → getByText
+   └─ Last resort → getByTestId (avoid if possible)
+
+3. Is this async?
+   ├─ YES → Use waitFor with timeout
+   └─ NO → Direct assertions
+```
+
+## Testing Patterns
+
+### 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);
+});
+```
+
+### 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: 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);
+
+// ❌ AVOID: Non-accessible queries (use as last resort)
+screen.getByTestId('submit-button');
+```
+
+### MUST: Include Timeout Parameters
+
+**Tests MUST include timeout parameters to prevent hanging:**
+
+```tsx
+// ✅ CORRECT: Include timeout parameters
+test('async operation completes', async () => {
+  await waitFor(
+    () => expect(screen.getByText('Loaded')).toBeInTheDocument(),
+    { timeout: 5000 }
+  );
+}, { timeout: 10000 });
+```
+
+**Configure timeouts in `vitest.config.ts`:**
+
+```typescript
+export default defineConfig({
+  test: {
+    testTimeout: 10000, // Default 10 seconds for all tests
+    hookTimeout: 10000,
+  },
+});
+```
+
+### 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', () => { ... });
+  });
+});
+```
+
+## Coverage Requirements
+
+**Note**: Coverage threshold enforcement is handled by CI/ESLint. See [8-testing-documentation-standards.md](../../packages/core/docs/standards/8-testing-documentation-standards.md) for complete coverage requirements.
+
+**MUST achieve:**
+- ≥90% coverage for utils & hooks
+- ≥70% coverage for components
+
+**MUST configure test runner to enforce thresholds:**
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    coverage: {
+      thresholds: {
+        lines: 80,
+        functions: 80,
+        branches: 80,
+        statements: 80,
+      },
+    },
+  },
+});
+```
+
+## Documentation Requirements
+
+### MUST: Document Public APIs
+
+**MUST document all public functions, components, and hooks:**
+
+```tsx
+/**
+ * Fetches event data for a given event ID.
+ * 
+ * @param eventId - The unique identifier for the event
+ * @returns Event data or null if not found
+ * @throws {Error} If eventId is invalid
+ */
+export async function fetchEvent(eventId: string): Promise<Event | null> {
+  // Implementation
+}
+```
+
+### MUST: Include Usage Examples
+
+**MUST include usage examples in documentation:**
+
+```tsx
+/**
+ * Example usage:
+ * ```tsx
+ * const { event, isLoading } = useEventData('event-123');
+ * if (isLoading) return <Loading />;
+ * return <EventCard event={event} />;
+ * ```
+ */
+```
+
+### SHOULD: Document Complex Logic
+
+**SHOULD document complex logic and business rules:**
+
+```tsx
+// Calculate event duration, accounting for timezone differences
+// Events can span multiple days, so we need to handle day boundaries
+function calculateDuration(start: Date, end: Date): number {
+  // Implementation
+}
+```
+
+## Bug Reports & Feature Requests
+
+**Note**: Complete templates are in [8-testing-documentation-standards.md](../../packages/core/docs/standards/8-testing-documentation-standards.md). Use these patterns when creating issues.
+
+### Bug Report Checklist
+
+Before filing a bug report:
+- [ ] Issue hasn't been reported already
+- [ ] Using latest pace-core version
+- [ ] Issue is in pace-core (not your app)
+- [ ] Checked documentation
+- [ ] Have minimal reproduction
+- [ ] Included all required information
+
+### Feature Request Checklist
+
+Before filing a feature request:
+- [ ] Feature doesn't already exist
+- [ ] Checked if workaround exists
+- [ ] Clear problem statement
+- [ ] Proposed solution described
+- [ ] Real-world use case provided
+- [ ] Alternatives considered
+
+## Common Mistakes to Avoid
+
+**When writing tests, NEVER:**
+1. **Test implementation details** - Always test user behavior
+   ```tsx
+   // ❌ WRONG
+   test('calls setState', () => {
+     const component = render(<Counter />);
+     expect(component.state.count).toBe(0);
+   });
+   
+   // ✅ CORRECT
+   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();
+   });
+   ```
+
+2. **Use getByTestId as first choice** - Always prefer accessible queries (getByRole, getByLabelText)
+3. **Skip timeouts** - Always include timeout parameters to prevent hanging
+4. **Place tests in separate directory** - Always colocate tests with source files
+5. **Use vague test names** - Always use descriptive names that explain behavior
+
+## 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
+
+## Reference
+
+**Note**: Coverage threshold enforcement and detailed test configuration are handled by CI/ESLint. See [8-testing-documentation-standards.md](../../packages/core/docs/standards/8-testing-documentation-standards.md) for complete enforcement details.
+
+- React Testing Library: https://testing-library.com/react
+- Vitest: https://vitest.dev
+- Complete templates: [8-testing-documentation-standards.md](../../packages/core/docs/standards/8-testing-documentation-standards.md)