@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/standards/03-solid-principles.md

@@ -0,0 +1,39 @@
+# Architecture & SOLID Standard
+
+**🤖 Cursor Rule**: See [03-solid-principles.mdc](../../cursor-rules/03-solid-principles.mdc) for AI-optimized directives that automatically enforce SOLID principles.
+
+## Purpose
+Define the core architectural principles and SOLID expectations for pace-core and consuming apps so components, APIs, and utilities evolve consistently and sustainably.
+
+## Architectural Principles
+- Composition over complexity
+- Separation of concerns
+- Domain-agnostic core
+- Extensible, stable APIs
+- Secure by default
+- Performance-conscious
+
+## SOLID Principles (Cursor enforcement)
+- **Single Responsibility**: Each module has one reason to change; extract complex logic to hooks/services.
+- **Open/Closed**: Extend via composition/configuration, avoid modifying shared primitives.
+- **Liskov Substitution**: Derived types/components must satisfy the base contract.
+- **Interface Segregation**: Prefer focused interfaces/props over catch-all configs.
+- **Dependency Inversion**: Depend on abstractions (types/interfaces); inject implementations.
+
+## Performance & RLS Boundaries
+- **RLS helper use**: Policies must rely on helper functions (no subqueries) to avoid N+1/per-row overhead.
+- **Test migrations**: Verify DB migrations for performance regressions and timeouts.
+- **Monitor queries**: Use EXPLAIN/Advisors to ensure policies don’t introduce InitPlan nodes.
+
+## In/Out of Scope
+**In scope**: UI primitives, generic hooks, shared API patterns, error-handling conventions, RPC shape conventions.  
+**Out of scope**: App/domain-specific logic, app-specific styling, business workflows.
+
+## Precedence
+1) Security 2) API/RPC 3) Components 4) Code Style 5) Testing 6) Documentation.
+
+## Cursor Checklist
+- Changes fit boundaries (no domain logic in core primitives).
+- Follow SOLID guidance above.
+- Prefer additive changes; avoid breaking contracts.
+- Keep helpers small, pure, and typed.

package/docs/standards/04-testing-standards.md

@@ -0,0 +1,36 @@
+# Testing & Documentation Standard
+
+**🤖 Cursor Rule**: See [04-testing-standards.mdc](../../cursor-rules/04-testing-standards.mdc) for AI-optimized directives that automatically enforce testing standards.
+
+## Testing Strategy
+- Unit tests for utils & hooks
+- Integration tests for components
+- Few meaningful E2E tests (in consuming apps)
+- Coverage: ≥90% utils, ≥70% components
+
+## Test Structure
+- Colocated tests (*.test.ts/tsx)
+- Use RTL + userEvent
+- Avoid unnecessary mocks
+
+## Documentation Requirements
+- Component READMEs
+- API docs
+- Standards directory
+
+## Required Sections (for every component/API doc)
+- Overview
+- API/Props
+- Examples
+- A11y notes
+- Edge cases
+
+## When to update docs
+- New component or API surface: add README + API entry with all required sections.
+- Behavior/prop change: update README/API entry and add migration notes if breaking.
+- Bug fix: document the fixed behavior when it changes user-facing expectations.
+
+## Cursor Checklist
+- Update docs after API or behavior changes (follow \"When to update docs\").
+- Ensure tests cover critical paths
+- Use RTL patterns only

package/docs/standards/05-bug-reports-and-features.md

@@ -0,0 +1,27 @@
+# Bug Reports and Feature Requests
+
+**🤖 Cursor Rule**: See [05-bug-reports-and-features.mdc](../../cursor-rules/05-bug-reports-and-features.mdc) for AI-optimized templates and guidance.
+
+## Purpose
+Standardize how issues and feature requests are captured for pace-core and consuming apps.
+
+## Bug Report Template
+- Description of bug and expected vs actual behavior.
+- Steps to reproduce (minimal, ordered).
+- Minimal reproduction (link/snippet).
+- Environment (pace-core version, React, Node, browser, OS).
+- Error messages/logs.
+- Additional context (screenshots/video).
+
+## Feature Request Template
+- Feature description and problem statement.
+- Proposed solution/API.
+- Use case with real scenario.
+- Alternatives considered.
+- Example code snippet.
+- Additional context/mockups.
+
+## Cursor Checklist
+- Confirm issue belongs to pace-core vs consuming app.
+- Include minimal reproduction and environment.
+- Use templates above when drafting issues.

package/docs/standards/{04-code-style-standard.md → 06-code-quality.md}

@@ -1,5 +1,7 @@
 # TypeScript & Code Style Standard
 
+**🤖 Cursor Rule**: See [06-code-quality.mdc](../../cursor-rules/06-code-quality.mdc) for AI-optimized directives that automatically enforce code quality standards.
+
 ## TypeScript Rules
 - No any
 - Prefer discriminated unions

package/docs/standards/07-tech-stack-compliance.md

@@ -0,0 +1,30 @@
+# Tech Stack & API/RPC Standard
+
+**🤖 Cursor Rule**: See [07-tech-stack-compliance.mdc](../../cursor-rules/07-tech-stack-compliance.mdc) for AI-optimized directives that automatically enforce tech stack compliance.
+
+## Required Stack
+- **React 19+**, functional components only.
+- **TypeScript 5+** with `strict` enabled.
+- **Vite** for tooling; use `import.meta.env`.
+- **Tailwind v4** CSS-first with `app.css` scaffold (see 08-markup-quality).
+- **Supabase** via secure clients/hooks (`useSecureSupabase`); never bypass RLS.
+- **TanStack Query** for server state.
+- **React Hook Form + Zod** (prefer `useZodForm` from pace-core) for forms.
+
+## API & RPC Rules
+- Naming: `<family>_<domain>_<verb>` (e.g., `data_cake_dishes_list`, `app_cake_dish_create`, `_bulk` for bulk).
+- Shape: 
+  ```ts
+  type ApiResult<T> =
+    | { ok: true; data: T }
+    | { ok: false; error: ApiError };
+  ```
+- Read RPCs never mutate; writes idempotent when possible.
+- Never accept dynamic SQL; enforce RLS + tenant boundaries; errors must be user-safe.
+- Deprecation: mark with `@deprecated`; retirement window = 2 stable releases.
+
+## Cursor Checklist
+- Use the required stack (React 19+, TS strict, Vite, Tailwind v4 scaffold, Supabase secure client, TanStack Query, RHF + Zod).
+- Enforce ApiResult shape and naming rules.
+- Do not bypass RLS; avoid overlapping/redundant RPCs.
+- Ensure idempotency for writes; avoid dynamic SQL.

package/docs/standards/08-markup-quality.md

@@ -0,0 +1,345 @@
+# Styling Standard for Consuming Apps
+
+**🤖 Cursor Rule**: See [08-markup-quality.mdc](../../cursor-rules/08-markup-quality.mdc) for AI-optimized directives that automatically enforce markup quality (this rule is ALWAYS APPLIED).
+
+## Purpose
+
+This standard defines the **REQUIRED** configuration for consuming apps to properly use pace-core styling. Adhering to this standard ensures:
+
+- ✅ pace-core components render with correct styles
+- ✅ Colors, typography, and spacing work correctly
+- ✅ Tailwind v4 content scanning works properly
+- ✅ Consistent styling across all PACE suite applications
+
+## Component & Markup Guidance (aligns with Cursor rules)
+- Components should be stateless when possible, fully typed, and accessibility-first.
+- Prefer semantic HTML elements; use `<div>` only when no semantic element fits or when required by a library.
+- Use React Fragments for grouping instead of wrapper nodes; keep markup minimal and avoid wrappers solely for styling.
+- No inline styles; rely on pace-core variants and Tailwind utilities (layout/spacing) using theme tokens (`main-*`, `sec-*`, `acc-*`, semantic tokens).
+- No arbitrary Tailwind colors or bracket syntax—use approved theme tokens only.
+- Apply layout utilities to existing semantic parents or pace-core layout components.
+
+### Component Principles
+- Stateless when possible; keep surface area small and composable.
+- Accessible by default with correct roles, keyboard support, and visible focus.
+- UI primitives only; never add domain logic or data fetching inside components.
+- Support controlled + uncontrolled usage where applicable.
+
+### Testing Expectations
+- Use React Testing Library + userEvent.
+- Test key interactions; snapshots only for simple components.
+- Keep components small—move non-UI logic to hooks/services.
+
+## ⚠️ CRITICAL: Required Configuration
+
+**Without proper configuration, pace-core components will appear unstyled or with incorrect styling.**
+
+## Two-File CSS Architecture
+
+pace-core uses a two-file CSS architecture:
+
+1. **`@jmruthers/pace-core/styles/core.css`** - Core foundation (fonts, resets, typography, component styles)
+2. **`src/app.css`** - App-specific configuration (color palettes, source directives)
+
+## Required File: `src/app.css`
+
+**MUST** create `src/app.css` in your consuming app with the following structure:
+
+```css
+@import "tailwindcss";
+
+/* @source directives for Tailwind v4 content scanning */
+/* CRITICAL: Paths are relative to the CSS file location (src/app.css) */
+@source "./**/*.{js,ts,jsx,tsx}";
+@source "../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+
+/* Import pace-core CSS files so Tailwind processes them */
+/* CRITICAL: Must use package path, not /src/styles/ path */
+@import "@jmruthers/pace-core/styles/core.css";
+
+@theme static {
+  /* Your app's color palettes here */
+  /* See Color Palette Requirements below */
+}
+```
+
+## ⚠️ CRITICAL: @source Directive Paths
+
+**The @source directive paths are relative to the CSS file location, not the project root.**
+
+Since `app.css` is in `src/app.css`, the paths MUST be:
+
+### ✅ CORRECT Patterns
+
+```css
+/* For app source files (relative to src/) */
+@source "./**/*.{js,ts,jsx,tsx}";
+
+/* For pace-core (one level up from src/ to project root, then into node_modules) */
+@source "../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+```
+
+### ❌ WRONG Patterns
+
+```css
+/* ❌ WRONG: Two levels up for node_modules (only needed if app.css is nested deeper) */
+@source "../../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+
+/* ❌ WRONG: Using ../src/ when app.css is already in src/ */
+@source "../src/**/*.{js,ts,jsx,tsx}";
+
+/* ❌ WRONG: Using ./src/ when app.css is already in src/ */
+@source "./src/**/*.{js,ts,jsx,tsx}";
+
+/* ❌ WRONG: Using project root paths (paths are relative to CSS file) */
+@source "./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+```
+
+### Path Resolution Logic
+
+```
+Project Structure:
+your-app/
+├── src/
+│   └── app.css          ← CSS file is here
+├── node_modules/
+│   └── @jmruthers/
+│       └── pace-core/
+│           └── src/     ← pace-core source is here
+```
+
+**From `src/app.css`:**
+- To scan app source: `./**/*.{js,ts,jsx,tsx}` (current directory = src/)
+- To scan pace-core: `../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}` (up one level to project root, then into node_modules)
+
+## ⚠️ CRITICAL: CSS Import Path
+
+**MUST** use the package path, not the source path:
+
+### ✅ CORRECT
+
+```css
+@import "@jmruthers/pace-core/styles/core.css";
+```
+
+### ❌ WRONG
+
+```css
+/* ❌ WRONG: Don't use /src/styles/ path */
+@import "@jmruthers/pace-core/src/styles/core.css";
+
+/* ❌ WRONG: Don't import in main.tsx (import in app.css instead) */
+/* In main.tsx: */
+import '@jmruthers/pace-core/styles/core.css';  /* ❌ WRONG */
+```
+
+## Required Color Palettes
+
+**MUST** define three complete color palettes in `@theme static`:
+
+```css
+@theme static {
+  /* Main palette - Primary brand color (all shades 50-950 required) */
+  --color-main-raw: oklch(0.58 0.23 300);
+  --color-main-50: oklch(0.98 0.003 300);
+  --color-main-100: oklch(0.96 0.014 300);
+  --color-main-200: oklch(0.927 0.033 300);
+  --color-main-300: oklch(0.881 0.059 300);
+  --color-main-400: oklch(0.822 0.093 300);
+  --color-main-500: oklch(0.75 0.133 300);
+  --color-main-600: oklch(0.665 0.182 300);
+  --color-main-700: oklch(0.58 0.23 300);
+  --color-main-800: oklch(0.456 0.158 300);
+  --color-main-900: oklch(0.332 0.099 300);
+  --color-main-950: oklch(0.195 0.047 300);
+
+  /* Secondary palette - Supporting color (all shades 50-950 required) */
+  --color-sec-raw: oklch(0.675 0.169 244.75);
+  --color-sec-50: oklch(0.98 0.003 244.75);
+  --color-sec-100: oklch(0.96 0.014 244.75);
+  --color-sec-200: oklch(0.927 0.032 244.75);
+  --color-sec-300: oklch(0.881 0.057 244.75);
+  --color-sec-400: oklch(0.822 0.089 244.75);
+  --color-sec-500: oklch(0.75 0.128 244.75);
+  --color-sec-600: oklch(0.675 0.169 244.75);
+  --color-sec-700: oklch(0.567 0.134 244.75);
+  --color-sec-800: oklch(0.456 0.101 244.75);
+  --color-sec-900: oklch(0.332 0.068 244.75);
+  --color-sec-950: oklch(0.195 0.037 244.75);
+
+  /* Accent palette - Highlight color (all shades 50-950 required) */
+  --color-acc-raw: oklch(0.64 0.23 7.385);
+  --color-acc-50: oklch(0.98 0.003 7.385);
+  --color-acc-100: oklch(0.96 0.017 7.385);
+  --color-acc-200: oklch(0.927 0.039 7.385);
+  --color-acc-300: oklch(0.881 0.069 7.385);
+  --color-acc-400: oklch(0.822 0.109 7.385);
+  --color-acc-500: oklch(0.75 0.157 7.385);
+  --color-acc-600: oklch(0.64 0.23 7.385);
+  --color-acc-700: oklch(0.567 0.193 7.385);
+  --color-acc-800: oklch(0.456 0.142 7.385);
+  --color-acc-900: oklch(0.332 0.092 7.385);
+  --color-acc-950: oklch(0.195 0.047 7.385);
+}
+```
+
+**All shades (50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950) plus `-raw` are REQUIRED.**
+
+## Required Import in Entry Point (and avoiding duplicate imports)
+
+**MUST** import `app.css` in your entry point (e.g., `src/main.tsx`):
+
+```tsx
+// src/main.tsx
+import './app.css';  // ✅ CORRECT - Import app.css which imports core.css once
+```
+
+**DO NOT** import `core.css` directly in `main.tsx`, `App.tsx`, or any other entry surface. Double-importing `core.css` leads to stylesheet duplication and ordering issues.
+
+```tsx
+// ❌ WRONG - Don't import core.css directly (app.css already does it)
+import '@jmruthers/pace-core/styles/core.css';
+import './app.css';
+```
+
+### Multi-entry decision tree
+
+When you have additional entry points (storybook, tests, preview servers):
+- If the entry point renders your React tree, **import only `app.css`** there as well.
+- If you need raw styles for non-React tooling, **import `@jmruthers/pace-core/styles/core.css` once** in that tool-specific stylesheet, never alongside `app.css`.
+- If you are unsure, default to a single `app.css` import and remove any extra `core.css` imports.
+
+## Styling & Markup Rules (aligns with Cursor)
+
+- **No inline styles**: Do not use `style={{ ... }}` except when a third-party library strictly requires it. Prefer pace-core variants + Tailwind utilities.
+- **Use theme tokens only**: Avoid arbitrary Tailwind colors (`text-gray-500`, `bg-red-500`) and bracket syntax (`bg-[oklch(...)]`). Use `main-*`, `sec-*`, `acc-*`, or semantic tokens like `text-foreground`.
+- **Semantic-first markup**: Prefer semantic HTML elements. Use `<div>` only when no semantic element fits or when required by a library; otherwise use semantic tags or React fragments.
+- **Minimal wrappers**: Avoid extra wrapper elements just for styling—apply layout classes to existing semantic parents or use pace-core layout components.
+- **Typography**: Rely on pace-core typography defaults; only add utilities when they reference approved theme tokens (e.g., `text-main-700`).
+
+## Complete Example
+
+### `src/app.css`
+
+```css
+@import "tailwindcss";
+
+/* @source directives for Tailwind v4 content scanning */
+@source "./**/*.{js,ts,jsx,tsx}";
+@source "../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+
+/* Import pace-core CSS files so Tailwind processes them */
+@import "@jmruthers/pace-core/styles/core.css";
+
+@theme static {
+  /* Your app's color palettes */
+  --color-main-raw: oklch(0.58 0.23 300);
+  --color-main-50: oklch(0.98 0.003 300);
+  /* ... continue through 950 for main, sec, and acc */
+}
+```
+
+### `src/main.tsx`
+
+```tsx
+import { createRoot } from 'react-dom/client';
+import App from './App';
+import './app.css';  // ✅ Import app.css (which imports core.css)
+
+createRoot(document.getElementById('root')!).render(<App />);
+```
+
+## Verification Checklist
+
+Before committing, verify:
+
+- [ ] `src/app.css` exists and follows the structure above
+- [ ] `@source` directives use correct paths (relative to `src/app.css`)
+- [ ] `@import "@jmruthers/pace-core/styles/core.css";` is in `app.css` (not in `main.tsx`)
+- [ ] All three color palettes (main, sec, acc) are defined with all shades (50-950)
+- [ ] `app.css` is imported in `main.tsx` (not `core.css`)
+- [ ] No duplicate imports of `core.css`
+
+## Common Mistakes
+
+### ❌ Mistake 1: Wrong @source Paths
+
+```css
+/* ❌ WRONG */
+@source "../../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+```
+
+**Fix:** Use `../node_modules/` (one level up, not two)
+
+### ❌ Mistake 2: Importing core.css in main.tsx
+
+```tsx
+// ❌ WRONG
+import '@jmruthers/pace-core/styles/core.css';
+import './app.css';
+```
+
+**Fix:** Only import `app.css` in `main.tsx`. The `app.css` file imports `core.css`.
+
+### ❌ Mistake 3: Using /src/styles/ Path
+
+```css
+/* ❌ WRONG */
+@import "@jmruthers/pace-core/src/styles/core.css";
+```
+
+**Fix:** Use `@jmruthers/pace-core/styles/core.css` (package path, not source path)
+
+### ❌ Mistake 4: Missing Color Shades
+
+```css
+/* ❌ WRONG - Missing shades */
+@theme static {
+  --color-main-500: oklch(0.75 0.133 300);
+  /* Missing 50, 100, 200, etc. */
+}
+```
+
+**Fix:** Include all shades (50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950) plus `-raw` for each palette
+
+### ❌ Mistake 5: Wrong App Source Path
+
+```css
+/* ❌ WRONG - If app.css is in src/ */
+@source "../src/**/*.{js,ts,jsx,tsx}";
+```
+
+**Fix:** Use `./**/*.{js,ts,jsx,tsx}` when `app.css` is in `src/`
+
+## Troubleshooting
+
+### Components Appear Unstyled
+
+1. **Check @source directives:** Verify paths are correct relative to `src/app.css`
+2. **Check CSS import:** Ensure `@import "@jmruthers/pace-core/styles/core.css";` is in `app.css`
+3. **Check app.css import:** Ensure `import './app.css';` is in `main.tsx`
+4. **Clear build cache:** Delete `dist/`, `.vite/`, and rebuild
+
+### Colors Don't Work
+
+1. **Check color palettes:** Verify all shades (50-950) are defined for main, sec, and acc
+2. **Check @theme static:** Ensure color variables are in `@theme static` block
+3. **Check import order:** Ensure `core.css` is imported before `@theme static` in `app.css`
+
+### Tailwind Classes Missing
+
+1. **Check @source directives:** Verify pace-core source is being scanned
+2. **Check build output:** Look for warnings about missing classes
+3. **Verify package version:** Ensure you're using a recent version of pace-core
+
+## Related Documentation
+
+- [PACE Core Styling Guide](../styles/README.md) - Complete styling documentation
+- [Project Structure Guide](./00-project-structure-guide.md) - File organization standards
+- [Component Standard](./03-component-standard.md) - Component development standards
+
+---
+
+**Last Updated:** 2025-01-28  
+**Version:** 1.0.0  
+**Applies to:** All consuming apps using `@jmruthers/pace-core`