@jmruthers/pace-core 0.6.1 → 0.6.3

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

@@ -1,9 +1,9 @@
 ---
 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"
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
 ---
 # Code Quality Guide
 
@@ -36,27 +36,17 @@ This guide enforces code quality standards to ensure maintainable, performant, a
 **MUST NOT use `any` type. Use `unknown` if type is truly unknown:**
 
 ```tsx
-// ❌ WRONG - Using any
-function processData(data: any) {
-  return data.value;
-}
+// ❌ WRONG: Using any
+function processData(data: any) { return data.value; }
 
-// ✅ CORRECT - Using unknown with type guard
+// ✅ 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');
 }
-
-// ✅ CORRECT - Using proper types
-interface Data {
-  value: string;
-}
-
-function processData(data: Data) {
-  return data.value;
-}
+// Or: interface Data { value: string; } function processData(data: Data) { return data.value; }
 ```
 
 ### MUST: Use Discriminated Unions
@@ -64,18 +54,11 @@ function processData(data: Data) {
 **MUST use discriminated unions instead of boolean flags:**
 
 ```tsx
-// ❌ WRONG - Boolean flags
-interface User {
-  isAdmin: boolean;
-  isGuest: boolean;
-  // Confusing: what if both are true?
-}
+// ❌ 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 };
+// ✅ CORRECT: Discriminated union
+type User = { type: 'admin'; permissions: Permission[] } | { type: 'guest'; limitedAccess: boolean } | { type: 'user'; role: UserRole };
 ```
 
 ### SHOULD: Use ReadonlyArray
@@ -148,20 +131,10 @@ npm run format
 **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>;
-});
+// ✅ 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
@@ -169,18 +142,12 @@ const ExpensiveComponent = React.memo(({ data }) => {
 **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} />;
-}
+// ❌ 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
+// ✅ CORRECT: Memoize object
 function Component({ items }) {
-  const config = useMemo(
-    () => ({ items, enabled: true }),
-    [items]
-  );
+  const config = useMemo(() => ({ items, enabled: true }), [items]);
   return <Child config={config} />;
 }
 ```
@@ -190,17 +157,11 @@ function Component({ items }) {
 **SHOULD lazy load heavy components:**
 
 ```tsx
-// ✅ CORRECT - Lazy loading
+// ✅ CORRECT: Lazy load heavy components
 import { lazy, Suspense } from 'react';
-
 const HeavyComponent = lazy(() => import('./HeavyComponent'));
-
 function App() {
-  return (
-    <Suspense fallback={<Loading />}>
-      <HeavyComponent />
-    </Suspense>
-  );
+  return <Suspense fallback={<Loading />}><HeavyComponent /></Suspense>;
 }
 ```
 
@@ -211,11 +172,8 @@ function App() {
 **MUST use semantic HTML elements:**
 
 ```tsx
-// ❌ WRONG - Non-semantic
-<div onClick={handleClick}>Click me</div>
-
-// ✅ CORRECT - Semantic
-<button onClick={handleClick}>Click me</button>
+// ❌ WRONG: Non-semantic (<div onClick={...}>)
+// ✅ CORRECT: Semantic HTML (<button onClick={...}>)
 ```
 
 ### MUST: Provide ARIA Labels
@@ -223,7 +181,7 @@ function App() {
 **MUST provide ARIA labels for interactive elements:**
 
 ```tsx
-// ✅ CORRECT - ARIA labels
+// ✅ CORRECT: Provide ARIA labels for interactive elements
 <button aria-label="Close dialog">×</button>
 <input aria-label="Search" type="search" />
 ```
@@ -233,17 +191,8 @@ function App() {
 **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>
+// ✅ 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
@@ -251,10 +200,8 @@ function App() {
 **MUST provide visible focus indicators:**
 
 ```tsx
-// ✅ CORRECT - Focus styles
-<button className="focus:outline-none focus:ring-2 focus:ring-main-500">
-  Click me
-</button>
+// ✅ CORRECT: Provide visible focus indicators
+<button className="focus:outline-none focus:ring-2 focus:ring-main-500">Click me</button>
 ```
 
 ## Code Review Checklist
@@ -281,20 +228,12 @@ function App() {
 **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
-}
+// ❌ 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;
@@ -307,24 +246,11 @@ function processUserData(user: User) {
 **Functions SHOULD have low cyclomatic complexity (< 10):**
 
 ```tsx
-// ❌ WRONG - High complexity
-function processData(data) {
-  if (condition1) {
-    if (condition2) {
-      if (condition3) {
-        // ... many nested conditions
-      }
-    }
-  }
-}
+// ❌ WRONG: High complexity (many nested conditions)
+function processData(data) { if (condition1) { if (condition2) { if (condition3) { /* ... */ } } } }
 
-// ✅ CORRECT - Lower complexity
-function processData(data) {
-  if (!condition1) return;
-  if (!condition2) return;
-  if (!condition3) return;
-  // Process
-}
+// ✅ CORRECT: Lower complexity (early returns)
+function processData(data) { if (!condition1) return; if (!condition2) return; if (!condition3) return; /* Process */ }
 ```
 
 ## Error Handling
@@ -334,7 +260,7 @@ function processData(data) {
 **MUST handle errors and provide user feedback:**
 
 ```tsx
-// ✅ CORRECT - Error handling
+// ✅ CORRECT: Handle errors gracefully with user feedback
 try {
   const data = await fetchData();
   setData(data);
@@ -349,24 +275,15 @@ try {
 **MUST use type-safe error handling:**
 
 ```tsx
-// ✅ CORRECT - Type-safe errors
+// ✅ CORRECT: Type-safe error handling
 function isApiError(error: unknown): error is ApiError {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    'code' in error &&
-    'message' in error
-  );
+  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);
-  }
+  if (isApiError(error)) handleApiError(error);
+  else handleUnknownError(error);
 }
 ```
 

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

@@ -1,7 +1,7 @@
 ---
 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
+alwaysApply: false
 paceCoreVersion: "0.6.x"
 rulesVersion: "2025-01-28"
 ---
@@ -16,19 +16,8 @@ This guide ensures consuming apps use the correct versions and patterns for all
 **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;
+/* ✅ CORRECT: Tailwind v4 CSS-first (@import 'tailwindcss'; @theme { ... }) */
+/* ❌ WRONG: Tailwind v3 (@tailwind base/components/utilities directives) */
 ```
 
 ### MUST NOT: Use Bracket Syntax
@@ -36,11 +25,8 @@ This guide ensures consuming apps use the correct versions and patterns for all
 **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">
+// ❌ WRONG: Bracket syntax (bg-[oklch(...)])
+// ✅ CORRECT: Theme variable (bg-main-500)
 ```
 
 ### MUST: Use Custom Color Namespaces
@@ -51,11 +37,8 @@ This guide ensures consuming apps use the correct versions and patterns for all
 - `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">
+// ✅ CORRECT: Custom namespaces (main-*, sec-*, acc-*)
+// ❌ WRONG: Standard Tailwind colors (blue-*, gray-*, red-*)
 ```
 
 ### MUST: Use Semantic Classes
@@ -77,17 +60,11 @@ This guide ensures consuming apps use the correct versions and patterns for all
 **MUST use React 19+ patterns:**
 
 ```tsx
-// ✅ CORRECT - React 19 features
+// ✅ CORRECT: React 19+ features (Suspense, useTransition, etc.)
 import { Suspense, useTransition } from 'react';
-
 function App() {
   const [isPending, startTransition] = useTransition();
-  
-  return (
-    <Suspense fallback={<Loading />}>
-      <Component />
-    </Suspense>
-  );
+  return <Suspense fallback={<Loading />}><Component /></Suspense>;
 }
 ```
 
@@ -96,16 +73,10 @@ function App() {
 **MUST use functional components with hooks exclusively:**
 
 ```tsx
-// ✅ CORRECT - Functional component
-function MyComponent() {
-  const [state, setState] = useState();
-  return <div>...</div>;
-}
+// ✅ CORRECT: Functional components with hooks
+function MyComponent() { const [state, setState] = useState(); return <div>...</div>; }
 
-// ❌ WRONG - Class component
-class MyComponent extends React.Component {
-  // ...
-}
+// ❌ WRONG: Class components
 ```
 
 ## Supabase
@@ -115,17 +86,8 @@ class MyComponent extends React.Component {
 **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(...);
+// ✅ CORRECT: useSecureSupabase() from '@jmruthers/pace-core/rbac'
+// ❌ WRONG: createClient() from '@supabase/supabase-js' (base client)
 ```
 
 ### MUST: Enforce RLS
@@ -137,17 +99,10 @@ const supabase = createClient(...);
 **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
+// ✅ 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
@@ -157,28 +112,11 @@ const { data } = await secureSupabase
 **MUST use TanStack Query for all server state management:**
 
 ```tsx
-// ✅ CORRECT - TanStack Query
+// ✅ CORRECT: TanStack Query for server state
 import { useQuery, useMutation } from '@tanstack/react-query';
+const { data, isLoading } = useQuery({ queryKey: ['events', orgId], queryFn: () => fetchEvents(orgId) });
 
-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);
-}, []);
+// ❌ WRONG: useState + useEffect for server state
 ```
 
 ### SHOULD: Configure Query Client
@@ -186,16 +124,8 @@ useEffect(() => {
 **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,
-    },
-  },
-});
+// ✅ 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
@@ -205,23 +135,12 @@ const queryClient = new QueryClient({
 **MUST use React Hook Form with Zod for all forms:**
 
 ```tsx
-// ✅ CORRECT - React Hook Form + Zod
+// ✅ CORRECT: React Hook Form + Zod (useZodForm from pace-core)
 import { useZodForm } from '@jmruthers/pace-core';
-import { z } from 'zod';
-
-const schema = z.object({
-  email: z.string().email(),
-  name: z.string().min(1),
-});
+const schema = z.object({ email: z.string().email(), name: z.string().min(1) });
+const form = useZodForm(schema);
 
-function Form() {
-  const form = useZodForm(schema);
-  return <Form {...form}>...</Form>;
-}
-
-// ❌ WRONG - Manual form handling
-const [email, setEmail] = useState('');
-const [errors, setErrors] = useState({});
+// ❌ WRONG: Manual form handling (useState for form state)
 ```
 
 ## Vite
@@ -231,14 +150,10 @@ const [errors, setErrors] = useState({});
 **MUST use Vite for all build tooling:**
 
 ```typescript
-// vite.config.ts
+// ✅ CORRECT: Vite for build tooling
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
-
-export default defineConfig({
-  plugins: [react()],
-  // ...
-});
+export default defineConfig({ plugins: [react()] });
 ```
 
 ### MUST: Use Environment Variables Correctly
@@ -246,11 +161,8 @@ export default defineConfig({
 **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;
+// ✅ CORRECT: import.meta.env.VITE_API_URL (Vite env vars)
+// ❌ WRONG: process.env.VITE_API_URL (Node.js env vars)
 ```
 
 ## TypeScript
@@ -260,15 +172,8 @@ const apiUrl = process.env.VITE_API_URL;
 **MUST use TypeScript 5+ with strict mode:**
 
 ```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "strict": true,
-    // ...
-  }
-}
+// ✅ CORRECT: TypeScript 5+ with strict mode
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "strict": true } }
 ```
 
 ## Version Requirements