@jmruthers/pace-core 0.5.193 → 0.6.1

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

@@ -0,0 +1,392 @@
+---
+description: Enforce code quality standards including TypeScript, ESLint, formatting, performance, and accessibility
+globs: ["src/**/*.{ts,tsx,js,jsx}"]
+alwaysApply: true
+paceCoreVersion: "0.5.x"
+rulesVersion: "2025-01-15"
+---
+# 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
+function processData(data: unknown) {
+  if (typeof data === 'object' && data !== null && 'value' in data) {
+    return (data as { value: string }).value;
+  }
+  throw new Error('Invalid data');
+}
+
+// ✅ CORRECT - Using proper types
+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
+interface User {
+  isAdmin: boolean;
+  isGuest: boolean;
+  // Confusing: what if both are true?
+}
+
+// ✅ 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
+const expensiveValue = useMemo(() => {
+  return computeExpensiveValue(data);
+}, [data]);
+
+// ✅ CORRECT - Memoize callbacks
+const handleClick = useCallback(() => {
+  doSomething(id);
+}, [id]);
+
+// ✅ CORRECT - Memoize components
+const ExpensiveComponent = React.memo(({ data }) => {
+  return <div>{/* ... */}</div>;
+});
+```
+
+### SHOULD: Avoid Unnecessary Re-renders
+
+**SHOULD avoid causing unnecessary re-renders:**
+
+```tsx
+// ❌ WRONG - New object on every render
+function Component({ items }) {
+  const config = { items, enabled: true }; // New object each render
+  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 loading
+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={handleClick}>Click me</div>
+
+// ✅ CORRECT - Semantic
+<button onClick={handleClick}>Click me</button>
+```
+
+### MUST: Provide ARIA Labels
+
+**MUST provide ARIA labels for interactive elements:**
+
+```tsx
+// ✅ CORRECT - ARIA labels
+<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 - Keyboard accessible
+<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 - Focus styles
+<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
+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
+function processData(data) {
+  if (condition1) {
+    if (condition2) {
+      if (condition3) {
+        // ... many nested conditions
+      }
+    }
+  }
+}
+
+// ✅ CORRECT - Lower complexity
+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 - Error handling
+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 errors
+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/

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

@@ -0,0 +1,309 @@
+---
+description: Enforce tech stack compliance including Tailwind v4, React 19+, Supabase, and other required technologies
+globs: ["src/**/*.{ts,tsx,js,jsx,css}", "*.config.{ts,js}"]
+alwaysApply: true
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Tech Stack Compliance Guide
+
+This guide ensures consuming apps use the correct versions and patterns for all technologies in the PACE stack.
+
+## Tailwind CSS v4
+
+### MUST: Use Tailwind v4 CSS-First Approach
+
+**MUST use Tailwind v4 CSS-first syntax, NOT v3 patterns:**
+
+```css
+/* ✅ CORRECT - Tailwind v4 */
+@import 'tailwindcss';
+
+@theme {
+  --color-main-*: oklch(...);
+  --color-sec-*: oklch(...);
+  --color-acc-*: oklch(...);
+}
+
+/* ❌ WRONG - Tailwind v3 */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+### MUST NOT: Use Bracket Syntax
+
+**MUST NOT use bracket syntax like `bg-[oklch(...)]`. Map everything through theme variables:**
+
+```tsx
+// ❌ WRONG - Bracket syntax
+<div className="bg-[oklch(0.5 0.2 200)]">
+
+// ✅ CORRECT - Theme variable
+<div className="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
+<div className="bg-main-500 text-sec-800 border-acc-300">
+
+// ❌ WRONG - Standard Tailwind colors
+<div className="bg-blue-500 text-gray-800 border-red-300">
+```
+
+### 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
+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 component
+function MyComponent() {
+  const [state, setState] = useState();
+  return <div>...</div>;
+}
+
+// ❌ WRONG - Class component
+class MyComponent extends React.Component {
+  // ...
+}
+```
+
+## Supabase
+
+### MUST: Use Secure Supabase Client
+
+**MUST use `useSecureSupabase()` for all database operations:**
+
+```tsx
+// ✅ CORRECT - Secure client
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+
+function Component() {
+  const secureSupabase = useSecureSupabase();
+  const { data } = await secureSupabase.from('table').select('*');
+}
+
+// ❌ WRONG - Base client
+import { createClient } from '@supabase/supabase-js';
+const supabase = createClient(...);
+```
+
+### 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 function
+const { data } = await secureSupabase.rpc('data_events_list', {
+  organisation_id: orgId
+});
+
+// ❌ AVOID - Complex client-side queries
+const { data } = await secureSupabase
+  .from('events')
+  .select('*, organisations(*), users(*)')
+  .eq('organisation_id', orgId)
+  // ... many joins
+```
+
+## TanStack Query
+
+### MUST: Use TanStack Query for Server State
+
+**MUST use TanStack Query for all server state management:**
+
+```tsx
+// ✅ CORRECT - TanStack Query
+import { useQuery, useMutation } from '@tanstack/react-query';
+
+function Component() {
+  const { data, isLoading } = useQuery({
+    queryKey: ['events', orgId],
+    queryFn: () => fetchEvents(orgId)
+  });
+  
+  const mutation = useMutation({
+    mutationFn: createEvent,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['events'] });
+    }
+  });
+}
+
+// ❌ WRONG - useState for server state
+const [data, setData] = useState();
+useEffect(() => {
+  fetchEvents().then(setData);
+}, []);
+```
+
+### SHOULD: Configure Query Client
+
+**SHOULD configure QueryClient with appropriate defaults:**
+
+```tsx
+// ✅ CORRECT - Configured QueryClient
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 5 * 60 * 1000, // 5 minutes
+      cacheTime: 10 * 60 * 1000, // 10 minutes
+      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
+import { useZodForm } from '@jmruthers/pace-core';
+import { z } from 'zod';
+
+const schema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+});
+
+function Form() {
+  const form = useZodForm(schema);
+  return <Form {...form}>...</Form>;
+}
+
+// ❌ WRONG - Manual form handling
+const [email, setEmail] = useState('');
+const [errors, setErrors] = useState({});
+```
+
+## Vite
+
+### MUST: Use Vite for Build Tooling
+
+**MUST use Vite for all build tooling:**
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  // ...
+});
+```
+
+### MUST: Use Environment Variables Correctly
+
+**MUST use `import.meta.env` for environment variables:**
+
+```tsx
+// ✅ CORRECT - Vite env vars
+const apiUrl = import.meta.env.VITE_API_URL;
+
+// ❌ WRONG - Node.js env vars
+const apiUrl = process.env.VITE_API_URL;
+```
+
+## TypeScript
+
+### MUST: Use TypeScript 5+
+
+**MUST use TypeScript 5+ with strict mode:**
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "strict": true,
+    // ...
+  }
+}
+```
+
+## 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.**
+
+## 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 for build tooling
+- [ ] TypeScript 5+ with strict mode
+- [ ] All versions compatible with pace-core
+
+## 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