@jmruthers/pace-core 0.6.6 → 0.6.7

package/docs/standards/01-standards-compliance.md

@@ -1,188 +0,0 @@
-# Standards Compliance
-
-**🤖 Cursor Rule**: See [01-standards-compliance.mdc](../../cursor-rules/01-standards-compliance.mdc) for AI-optimized directives that automatically enforce these standards.
-
-## Purpose
-Provide a single reference for precedence and traceability between standards and Cursor rules.
-
-## Precedence
-1. Security
-2. API/RPC
-3. Components & Markup
-4. Code Quality/Style
-5. Testing & Documentation
-6. Consuming App Structure
-
-## File Mapping (Standards ↔ Cursor Rules)
-
-| Standard | Rule | Purpose |
-|----------|------|---------|
-| `00-pace-core-compliance` | `00-pace-core-compliance.mdc` | Enforce pace-core usage patterns |
-| `01-standards-compliance` | `01-standards-compliance.mdc` | This file - meta-standard |
-| `02-project-structure` | `02-project-structure.mdc` | Define standard folder structure |
-| `03-solid-principles` | `03-solid-principles.mdc` | Enforce SOLID architecture |
-| `04-testing-standards` | `04-testing-standards.mdc` | Enforce testing consistency |
-| `05-bug-reports-and-features` | `05-bug-reports-and-features.mdc` | Templates for issue reporting |
-| `06-code-quality` | `06-code-quality.mdc` | Enforce code quality standards |
-| `07-tech-stack-compliance` | `07-tech-stack-compliance.mdc` | Enforce tech stack versions |
-| `08-markup-quality` | `08-markup-quality.mdc` | Enforce clean markup standards |
-| `09-rbac-compliance` | `09-rbac-compliance.mdc` | Enforce RBAC contract |
-| `10-error-handling-patterns` | `10-error-handling-patterns.mdc` | Enforce error handling patterns |
-| `11-performance-optimization` | `11-performance-optimization.mdc` | Enforce performance best practices |
-| `12-ci-cd-integration` | `12-ci-cd-integration.mdc` | Enforce CI/CD best practices |
-
-## Documentation Standards
-
-### Purpose
-
-Documentation ensures code is maintainable, understandable, and usable. All documentation MUST follow these standards.
-
-### When to Document
-
-**MUST document:**
-- New components, hooks, utilities, or APIs
-- Breaking changes to existing APIs
-- Complex business logic or algorithms
-- Non-obvious implementation decisions
-- Configuration requirements
-- Migration paths for breaking changes
-
-**SHOULD document:**
-- Public APIs and their usage
-- Component props and behavior
-- Hook return values and dependencies
-- Utility function parameters and return types
-- Error conditions and handling
-
-**MAY document:**
-- Internal implementation details (if helpful)
-- Performance considerations
-- Future plans or limitations
-
-### Documentation Structure
-
-**Every component/API documentation MUST include:**
-
-1. **Overview** - What it does and when to use it
-2. **API/Props** - Complete prop/parameter definitions with types
-3. **Examples** - Real-world usage examples
-4. **Accessibility (A11y)** - Accessibility considerations and requirements
-5. **Edge Cases** - Known limitations, error conditions, and special cases
-
-**Example Structure:**
-
-```markdown
-# ComponentName
-
-## Overview
-Brief description of what the component does and when to use it.
-
-## API
-
-### Props
-- `propName` (type): Description
-- `optionalProp?` (type): Description (default: value)
-
-## Examples
-
-### Basic Usage
-\`\`\`tsx
-<ComponentName prop="value" />
-\`\`\`
-
-### Advanced Usage
-\`\`\`tsx
-<ComponentName prop="value" optionalProp="optional" />
-\`\`\`
-
-## Accessibility
-- Keyboard navigation: Supported
-- Screen readers: Announced as...
-- Focus management: ...
-
-## Edge Cases
-- Handles null/undefined: Yes/No
-- Error conditions: ...
-- Performance considerations: ...
-```
-
-### Documentation Formats
-
-**Component Documentation:**
-- Location: `packages/core/docs/api-reference/components.md` or component-specific README
-- Format: Markdown with code examples
-- Must include: Overview, Props, Examples, A11y, Edge Cases
-
-**API Documentation:**
-- Location: `packages/core/docs/api-reference/`
-- Format: TypeScript types + Markdown descriptions
-- Must include: Function signatures, Parameters, Return types, Examples
-
-**Implementation Guides:**
-- Location: `packages/core/docs/implementation-guides/`
-- Format: Step-by-step guides with examples
-- Must include: Overview, Step-by-step instructions, Code examples, Troubleshooting
-
-**Standards Documentation:**
-- Location: `packages/core/docs/standards/`
-- Format: Markdown with examples and checklists
-- Must include: Purpose, Requirements, Examples, Checklists
-
-### Documentation Maintenance
-
-**MUST update documentation when:**
-- Adding new props/parameters
-- Changing behavior (breaking or non-breaking)
-- Fixing bugs that change user-facing behavior
-- Deprecating features
-
-**SHOULD update documentation when:**
-- Improving examples
-- Adding new use cases
-- Clarifying edge cases
-
-**Update Process:**
-1. Update code and tests first
-2. Update documentation to match
-3. Verify examples still work
-4. Update related documentation if needed
-
-### Documentation Quality Checklist
-
-Before committing documentation, verify:
-
-- [ ] Overview clearly explains purpose and usage
-- [ ] All props/parameters documented with types
-- [ ] Examples are complete and working
-- [ ] Accessibility considerations documented
-- [ ] Edge cases and limitations documented
-- [ ] Code examples are syntax-highlighted
-- [ ] Links to related documentation included
-- [ ] Breaking changes have migration guides
-- [ ] Documentation matches actual implementation
-
-## Authoring Checklist
-
-- Apply the precedence above when resolving conflicts.
-- Keep rule and standard filenames aligned (00–12).
-- Update relevant standards whenever rules change and vice versa.
-- Document any exceptions in-line within the affected standard.
-- Follow documentation standards when updating docs.
-
-## Reference
-
-**🤖 Cursor Rule**: See [01-standards-compliance.mdc](../../cursor-rules/01-standards-compliance.mdc) for AI-optimized directives.
-
-**Related Standards**:
-- **00-pace-core-compliance.md** - pace-core usage patterns
-- **02-project-structure.md** - Project structure and organization
-- **03-solid-principles.md** - SOLID architecture principles
-- **04-testing-standards.md** - Testing framework standards
-- **05-bug-reports-and-features.md** - Issue reporting templates
-- **06-code-quality.md** - Code quality and TypeScript standards
-- **07-tech-stack-compliance.md** - Tech stack and API/RPC standards
-- **08-markup-quality.md** - Markup and styling standards
-- **09-rbac-compliance.md** - RBAC and RLS standards
-- **10-error-handling-patterns.md** - Error handling patterns
-- **11-performance-optimization.md** - Performance optimization
-- **12-ci-cd-integration.md** - CI/CD integration patterns

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

@@ -1,39 +0,0 @@
-# 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

@@ -1,36 +0,0 @@
-# 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

@@ -1,27 +0,0 @@
-# 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/06-code-quality.md

@@ -1,34 +0,0 @@
-# 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
-- Avoid assertions unless in escape hatches
-- Use ReadonlyArray where possible
-- Avoid boolean mode flags
-
-## Naming Conventions
-- Hooks: useSomething
-- Providers: SomethingProvider
-- Utilities: camelCase
-- Components: PascalCase
-
-## Preferred Patterns
-- Pure functions
-- Composition over inheritance
-- Early returns
-- Small private helpers
-
-## Forbidden
-- Implicit any
-- Bloated components
-- Domain-specific types in pace-core
-
-## Cursor Checklist
-- No any / unknown / unnecessary assertions
-- Convert flags into unions
-- Enforce naming rules
-- Extract large functions into helpers
-- Prevent domain types from leaking in

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

@@ -1,30 +0,0 @@
-# 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.