@jmruthers/pace-core 0.5.193 → 0.6.2

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

@@ -0,0 +1,214 @@
+---
+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: false
+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 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
+
+### 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: 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)
+```
+
+## TypeScript
+
+### MUST: Use TypeScript 5+
+
+**MUST use TypeScript 5+ with strict mode:**
+
+```json
+// ✅ CORRECT: TypeScript 5+ with strict mode
+{ "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

package/cursor-rules/08-markup-quality.mdc

@@ -0,0 +1,452 @@
+---
+description: Enforce clean markup standards, semantic HTML usage, and pace-core component patterns
+globs: ["src/**/*.{ts,tsx,js,jsx}"]
+alwaysApply: true
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Markup Quality Guide
+
+This guide enforces clean markup standards, semantic HTML usage, and proper pace-core component patterns to ensure maintainable, accessible, and consistent code.
+
+## pace-core First
+
+### MUST: Use pace-core Components
+
+**MUST use pace-core components wherever possible:**
+
+```tsx
+// ❌ WRONG: Custom button or native HTML element
+<button className="btn-primary">Click me</button>
+<input type="text" className="form-input" />
+
+// ✅ CORRECT: Use pace-core components
+import { Button, Input } from '@jmruthers/pace-core';
+<Button>Click me</Button>
+<Input type="text" />
+```
+
+### MUST NOT: Add Custom Styles to pace-core Components
+
+**MUST NOT add custom styles when pace-core components already provide styling:**
+
+```tsx
+// ❌ WRONG: Overriding pace-core component styles
+<Button className="custom-button-style">Click me</Button>
+<Card className="custom-card-layout">Content</Card>
+
+// ✅ CORRECT: Use pace-core component variants/props
+<Button variant="default">Click me</Button>
+<Card>Content</Card>
+```
+
+### MUST: Rely on pace-core core.css
+
+**MUST rely on pace-core `core.css` for typography, spacing, and visual presentation:**
+
+```tsx
+// ❌ WRONG: Custom typography classes
+<h1 className="text-2xl font-bold">Title</h1>
+<p className="text-gray-500 mb-4">Description</p>
+
+// ✅ CORRECT: Typography defined in pace-core core.css
+<h1>Title</h1>
+<p>Description</p>
+```
+
+### SHOULD: Fall Back to Semantic HTML
+
+**SHOULD only use plain semantic HTML when no suitable pace-core component exists:**
+
+```tsx
+// ✅ CORRECT: Use semantic HTML when pace-core doesn't provide component
+<main>
+  <section>
+    <article>
+      <h2>Article Title</h2>
+      <p>Article content</p>
+    </article>
+  </section>
+</main>
+```
+
+## Semantic HTML Only
+
+### MUST: Use Semantic HTML Elements
+
+**MUST use semantic HTML elements for their intended purpose:**
+
+```tsx
+// ❌ WRONG: Non-semantic elements
+<div onClick={handleClick}>Click me</div>
+<div className="header">Header</div>
+<div className="footer">Footer</div>
+
+// ✅ CORRECT: Semantic HTML elements
+<button onClick={handleClick}>Click me</button>
+<header>Header</header>
+<footer>Footer</footer>
+```
+
+### MUST NOT: Use `<div>` Elements
+
+**MUST NOT use `<div>` elements (except for the first child of `<body>` in `index.html`, React portals, or when required by third-party libraries that mandate specific DOM structure):**
+
+```tsx
+// ❌ WRONG: Using div elements
+<div className="container">
+  <div className="content">Content</div>
+</div>
+
+// ✅ CORRECT: Use semantic elements or React Fragments
+<main>
+  <section>Content</section>
+</main>
+// Or for grouping without semantic meaning:
+<>
+  <Component1 />
+  <Component2 />
+</>
+```
+
+### MUST: Choose Most Semantic Element
+
+**MUST choose the most semantically accurate element for the content:**
+
+```tsx
+// ✅ CORRECT: Choose appropriate semantic elements
+<main>Main content</main>
+<section>Section of content</section>
+<article>Article content</article>
+<header>Header content</header>
+<footer>Footer content</footer>
+<nav>Navigation</nav>
+<ul><li>List items</li></ul>
+<p>Paragraph text</p>
+```
+
+## Typography & Styling
+
+### MUST NOT: Apply Typography Styles Directly
+
+**MUST NOT apply typography styles directly to elements:**
+
+```tsx
+// ❌ WRONG: Direct typography styling
+<h1 className="text-2xl font-bold">Title</h1>
+<p className="text-gray-500 leading-relaxed">Description</p>
+<label className="text-sm uppercase">Label</label>
+
+// ✅ CORRECT: Typography defined in pace-core core.css
+<h1>Title</h1>
+<p>Description</p>
+<label>Label</label>
+```
+
+### MUST: Use pace-core Typography
+
+**MUST rely on typography defined exclusively in `pace-core core.css`:**
+
+```tsx
+// ✅ CORRECT: Typography comes from pace-core core.css
+<h1>Heading 1</h1>
+<h2>Heading 2</h2>
+<h3>Heading 3</h3>
+<p>Paragraph text</p>
+<label>Form label</label>
+```
+
+### MUST NOT: Add Typography Utilities
+
+**MUST NOT add utility classes, inline styles, or custom CSS for typography:**
+
+```tsx
+// ❌ WRONG: Typography utilities or inline styles
+<h1 className="text-3xl font-bold mb-4">Title</h1>
+<p style={{ fontSize: '14px', color: 'gray' }}>Text</p>
+<label className="uppercase tracking-wide">Label</label>
+
+// ✅ CORRECT: No typography styling - pace-core handles it
+<h1>Title</h1>
+<p>Text</p>
+<label>Label</label>
+```
+
+## React Structure Rules
+
+### MUST NOT: Add Wrapper Elements for Single Root
+
+**MUST NOT add wrapper elements solely to satisfy React's single-root requirement:**
+
+```tsx
+// ❌ WRONG: Unnecessary wrapper for single root
+function Component() {
+  return (
+    <div>
+      <Header />
+      <Main />
+      <Footer />
+    </div>
+  );
+}
+
+// ✅ CORRECT: Use React Fragment
+function Component() {
+  return (
+    <>
+      <Header />
+      <Main />
+      <Footer />
+    </>
+  );
+}
+```
+
+### MUST: Use React Fragments
+
+**MUST use React Fragments for grouping without adding DOM elements:**
+
+```tsx
+// ✅ CORRECT: Use React Fragments
+function Component() {
+  return (
+    <>
+      <Component1 />
+      <Component2 />
+      <Component3 />
+    </>
+  );
+}
+```
+
+### MUST NOT: Add Extra Elements
+
+**MUST NOT introduce extra elements that provide no semantic or functional value:**
+
+```tsx
+// ❌ WRONG: Extra wrapper with no purpose
+<article>
+  <div>
+    <h2>Title</h2>
+    <p>Content</p>
+  </div>
+</article>
+
+// ✅ CORRECT: Direct semantic structure
+<article>
+  <h2>Title</h2>
+  <p>Content</p>
+</article>
+```
+
+## Styling & Layout Discipline
+
+### MUST NOT: Add Wrappers for Styling
+
+**MUST NOT add wrapper elements just to apply styles:**
+
+```tsx
+// ❌ WRONG: Wrapper element for styling only
+<div className="flex gap-4">
+  <Button>Button 1</Button>
+  <Button>Button 2</Button>
+</div>
+
+// ✅ CORRECT: Apply styles to existing parent or use pace-core components
+<section className="flex gap-4">
+  <Button>Button 1</Button>
+  <Button>Button 2</Button>
+</section>
+// Or if no semantic parent exists, leave unstyled or use pace-core layout components
+```
+
+### SHOULD: Apply Styles to Existing Elements
+
+**SHOULD apply styles to existing parent components:**
+
+```tsx
+// ✅ CORRECT: Apply styles to semantic parent
+<main className="flex flex-col gap-4">
+  <section>Content 1</section>
+  <section>Content 2</section>
+</main>
+```
+
+### SHOULD: Leave Unstyled When Appropriate
+
+**SHOULD leave elements unstyled if styles aren't necessary:**
+
+```tsx
+// ✅ CORRECT: Unstyled semantic structure
+<article>
+  <h2>Title</h2>
+  <p>Content</p>
+</article>
+```
+
+### MUST: Use pace-core for Layout
+
+**MUST assume most layout and styling will be handled by pace-core, not ad-hoc wrappers:**
+
+```tsx
+// ❌ WRONG: Custom layout wrapper
+<div className="grid grid-cols-2 gap-4">
+  <Card>Card 1</Card>
+  <Card>Card 2</Card>
+</div>
+
+// ✅ CORRECT: Use pace-core layout components or apply to semantic parent
+<section className="grid grid-cols-2 gap-4">
+  <Card>Card 1</Card>
+  <Card>Card 2</Card>
+</section>
+```
+
+## Element Minimisation
+
+### MUST: Use Fewest Elements Possible
+
+**MUST use the fewest elements possible to achieve the desired structure:**
+
+```tsx
+// ❌ WRONG: Unnecessary nesting
+<main>
+  <div>
+    <section>
+      <div>
+        <article>Content</article>
+      </div>
+    </section>
+  </div>
+</main>
+
+// ✅ CORRECT: Minimal structure
+<main>
+  <section>
+    <article>Content</article>
+  </section>
+</main>
+```
+
+### MUST NOT: Create Redundant Nesting
+
+**MUST NOT create redundant nesting:**
+
+```tsx
+// ❌ WRONG: Redundant wrapper
+<article>
+  <div>
+    <h2>Title</h2>
+  </div>
+  <div>
+    <p>Content</p>
+  </div>
+</article>
+
+// ✅ CORRECT: Direct structure
+<article>
+  <h2>Title</h2>
+  <p>Content</p>
+</article>
+```
+
+### MUST: Clear Semantic Purpose
+
+**MUST ensure every element has a clear semantic purpose:**
+
+```tsx
+// ❌ WRONG: Element without semantic purpose
+<div>
+  <Component1 />
+  <Component2 />
+</div>
+
+// ✅ CORRECT: Semantic purpose or Fragment
+<section>
+  <Component1 />
+  <Component2 />
+</section>
+// Or if no semantic grouping needed:
+<>
+  <Component1 />
+  <Component2 />
+</>
+```
+
+## Prohibited Patterns
+
+### MUST NOT: Use These Patterns
+
+**MUST NOT use the following patterns:**
+
+1. **`<div>` elements** - Use semantic HTML or React Fragments instead
+2. **Wrapper elements for styling only** - Apply styles to existing elements or use pace-core components
+3. **Wrapper elements as sole child** - Use React Fragments instead
+4. **Custom typography classes** - Typography is defined in pace-core core.css
+5. **Inline styles for typography** - Use pace-core typography
+6. **Duplicating pace-core layout/visuals** - Use pace-core components instead
+
+```tsx
+// ❌ WRONG: All prohibited patterns
+<div className="wrapper">
+  <div className="content">
+    <h1 className="text-2xl font-bold">Title</h1>
+    <p style={{ color: 'gray' }}>Text</p>
+  </div>
+</div>
+
+// ✅ CORRECT: Clean, semantic markup
+<main>
+  <section>
+    <h1>Title</h1>
+    <p>Text</p>
+  </section>
+</main>
+```
+
+## Expected Outcome
+
+### Code Quality Goals
+
+Code produced under these rules SHOULD:
+
+- **Be semantically correct** - Use appropriate HTML elements for their purpose
+- **Be visually consistent** - Rely on pace-core for styling and typography
+- **Contain minimal markup** - Use fewest elements necessary
+- **Avoid unnecessary abstraction** - No wrappers without purpose
+- **Remain easy to reason about** - Clear structure and purpose
+- **Be easy to refactor** - Minimal coupling and dependencies
+
+### Decision Tree
+
+**When in doubt, follow this decision tree:**
+
+1. **Does pace-core provide a component?** → Use pace-core component
+2. **Is a semantic HTML element appropriate?** → Use semantic element (`<main>`, `<section>`, `<article>`, etc.)
+3. **Do I need to group elements without semantic meaning?** → Use React Fragment (`<>...</>`)
+4. **Do I need styling?** → Apply to existing semantic parent or use pace-core layout components
+5. **Still unsure?** → Remove the element, remove the style, and rely on pace-core or semantic HTML
+
+## Markup Quality Checklist
+
+Before committing code, verify:
+
+- [ ] No `<div>` elements (except first child of `<body>` in `index.html`)
+- [ ] pace-core components used where available
+- [ ] Semantic HTML elements used appropriately
+- [ ] No typography styling applied directly
+- [ ] No wrapper elements for styling only
+- [ ] React Fragments used instead of unnecessary wrappers
+- [ ] Minimal element nesting
+- [ ] Every element has clear semantic purpose
+- [ ] No custom styles overriding pace-core components
+- [ ] Layout handled by pace-core or semantic parents
+- [ ] Code is semantically correct and accessible
+
+## Reference
+
+- **pace-core Components**: See `00-pace-core-compliance.mdc` for component usage
+- **Semantic HTML**: https://developer.mozilla.org/en-US/docs/Glossary/Semantics
+- **React Fragments**: https://react.dev/reference/react/Fragment
+- **Accessibility**: See `06-code-quality.mdc` for accessibility requirements
+- **When in doubt**: Remove the element, remove the style, and rely on pace-core or semantic HTML