@jmruthers/pace-core 0.5.193 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2025-01-28
+
+### Changed
+- **BREAKING**: Upgraded from React 18.3.1 to React 19.2.3
+- **BREAKING**: Updated peer dependencies to require React ^19.0.0
+- **BREAKING**: Updated @types/react to ^19.2.7 and @types/react-dom to ^19.2.3
+- **BREAKING**: Updated @vitejs/plugin-react to ^5.1.2
+- Fixed TypeScript errors related to React 19's stricter type system in Button and Select components
+- Updated vitest.config.ts to remove duplicate configuration keys
+
+### Added
+- **React Compiler**: Added `babel-plugin-react-compiler` for automatic component optimizations
+- **React Compiler Configuration**: Configured React Compiler in vite.config.ts and vitest.config.ts
+- **Migration Guide**: Added React 19 migration guide at `docs/migration/REACT_19_MIGRATION.md`
+- Updated documentation to reflect React 19 requirements
+
+### Technical Details
+- React Compiler automatically optimizes components during development and in consuming apps
+- TypeScript types updated to handle React 19's stricter `child.props` typing
+- All error boundaries verified compatible with React 19 error handling changes
+- All tests pass with React 19 and React Compiler enabled
+
+### Migration Notes
+- Consuming apps must upgrade to React 19.2.3+
+- Consuming apps should install and configure React Compiler for optimal performance
+- See `docs/migration/REACT_19_MIGRATION.md` for complete migration instructions
+
+## [Unreleased]
+
 ### Added
 - **useFormDialog Hook**: Generic React hook for managing form dialog state (open/close, form data, reset behavior). Supports both controlled and uncontrolled usage patterns with type-safe form data management.
 - **DateTimeField Component**: Form input component for datetime values with automatic UTC ↔ timezone conversion

package/README.md

@@ -80,6 +80,7 @@ import React from 'react';
 import ReactDOM from 'react-dom/client';
 import App from './App';
 
+// React 19+ with createRoot
 const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
 root.render(
   <React.StrictMode>
@@ -104,7 +105,12 @@ import path from 'path'
 
 export default defineConfig({
   plugins: [
-    react(),
+    react({
+      // React Compiler for automatic optimizations (React 19+)
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
     tailwindcss({
       // Only need to scan your app's source files
       // pace-core source files are automatically scanned via @source directives

package/cursor-rules/00-pace-core-compliance.mdc

@@ -0,0 +1,372 @@
+---
+description: Enforce pace-core usage patterns and prevent custom solutions when pace-core provides functionality
+globs: ["src/**/*.{ts,tsx,js,jsx}"]
+alwaysApply: true
+paceCoreVersion: "0.5.x"
+rulesVersion: "2025-01-15"
+---
+# pace-core Compliance Guide
+
+This guide ensures consuming apps use pace-core components, hooks, and utilities correctly, preventing duplication and maintaining consistency across the PACE suite.
+
+## MUST: Use pace-core Instead of Custom Solutions
+
+**You MUST use pace-core components, hooks, and utilities when they exist.** Creating custom solutions duplicates functionality and breaks consistency.
+
+### Components
+
+**MUST use pace-core components:**
+- `Button`, `Card`, `Input`, `Label`, `Textarea` - Basic UI components
+- `Dialog`, `Select`, `Tabs`, `Calendar`, `Toast`, `Tooltip` - Advanced UI components
+- `DataTable` - Complex data tables with RBAC integration
+- `Form`, `FormField`, `LoginForm` - Form components
+- `Header`, `Footer`, `PaceAppLayout` - Layout components
+- `FileUpload`, `FileDisplay` - Storage components
+
+**MUST NOT:**
+- Create custom button components when `Button` from pace-core exists
+- Use native HTML elements (`<button>`, `<input>`) when pace-core provides components
+- Import directly from `@radix-ui/*` - Use pace-core wrappers instead
+- Import directly from `lucide-react` - Use pace-core components that include icons
+
+**Example:**
+```tsx
+// ❌ WRONG - Custom button
+function CustomButton() {
+  return <button className="btn">Click me</button>;
+}
+
+// ✅ CORRECT - Use pace-core
+import { Button } from '@jmruthers/pace-core';
+function MyComponent() {
+  return <Button>Click me</Button>;
+}
+```
+
+### Hooks
+
+**MUST use pace-core hooks:**
+- `useUnifiedAuth`, `useEvents`, `useOrganisations` - Authentication and data
+- `usePermissions`, `useCan`, `useSecureSupabase` - RBAC hooks
+- `useToast`, `useDebounce`, `useZodForm` - Utility hooks
+- `useFileReference`, `useFileUpload` - File management hooks
+
+**MUST NOT:**
+- Create custom `useAuth` when `useUnifiedAuth` exists
+- Create custom `useToast` when pace-core provides it
+- Create custom `useDebounce` when pace-core provides it
+- Create custom form hooks when `useZodForm` exists
+
+**Example:**
+```tsx
+// ❌ WRONG - Custom debounce hook
+function useCustomDebounce(value: string, delay: number) {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debounced;
+}
+
+// ✅ CORRECT - Use pace-core
+import { useDebounce } from '@jmruthers/pace-core';
+const debouncedValue = useDebounce(value, 500);
+```
+
+### Utilities
+
+**MUST use pace-core utilities:**
+- `cn` - Class name utility (replaces clsx/tailwind-merge)
+- `formatDate`, `formatTime`, `formatDateTime` - Date formatting
+- `formatCurrency`, `formatNumber`, `formatPercent` - Number formatting
+- `emailSchema`, `nameSchema`, `passwordSchema` - Validation schemas
+- `validateUserInput`, `sanitizeUserInput` - Input validation
+
+**MUST NOT:**
+- Create custom `formatDate` when pace-core provides it
+- Use `clsx` directly - Use `cn` from pace-core
+- Create custom validation when pace-core schemas exist
+
+**Example:**
+```tsx
+// ❌ WRONG - Custom date formatting
+function formatDateCustom(date: Date): string {
+  return new Intl.DateTimeFormat('en-US').format(date);
+}
+
+// ✅ CORRECT - Use pace-core
+import { formatDate } from '@jmruthers/pace-core';
+const formatted = formatDate(date);
+```
+
+## MUST: Use Secure Supabase Client
+
+**You MUST use `useSecureSupabase()` for all database operations.** Never use the base Supabase client directly.
+
+```tsx
+// ❌ WRONG - Direct Supabase client
+import { createClient } from '@supabase/supabase-js';
+const supabase = createClient(...);
+await supabase.from('users').select('*');
+
+// ✅ CORRECT - Use secure client
+import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
+const secureSupabase = useSecureSupabase();
+await secureSupabase.from('users').select('*');
+```
+
+## MUST: Setup RBAC Before Use
+
+**You MUST call `setupRBAC()` before any RBAC usage.** This is non-negotiable.
+
+```tsx
+// main.tsx - MUST be first
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+setupRBAC(supabase);
+
+// Then render app
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```
+
+## MUST: Read Documentation Before Using Components
+
+**You MUST read pace-core component documentation before using any component.** Never guess about props, usage patterns, or behavior.
+
+### Where to Find Documentation
+
+**Component API Reference:**
+- Location: `node_modules/@jmruthers/pace-core/docs/api-reference/components.md`
+- Or: Check pace-core repository `packages/core/docs/api-reference/components.md`
+- Contains: Complete prop definitions, type information, usage examples
+
+**Implementation Guides:**
+- Location: `node_modules/@jmruthers/pace-core/docs/implementation-guides/`
+- Contains: Detailed guides for complex components like DataTable, Forms, etc.
+- Examples:
+  - `data-tables.md` - DataTable component guide
+  - `forms.md` - Form components guide
+  - `file-upload-storage.md` - FileUpload/FileDisplay guide
+
+**Detailed API Documentation:**
+- Location: `node_modules/@jmruthers/pace-core/docs/api/`
+- Contains: In-depth API documentation for all exports
+
+**Quick Reference:**
+- Location: `node_modules/@jmruthers/pace-core/docs/getting-started/quick-reference.md`
+- Contains: Quick lookup for common patterns
+
+### How to Find Component-Specific Docs
+
+1. **Check API Reference First:**
+   ```bash
+   # In your consuming app
+   cat node_modules/@jmruthers/pace-core/docs/api-reference/components.md
+   ```
+
+2. **Search Implementation Guides:**
+   - Look for component name in `implementation-guides/` directory
+   - Complex components have dedicated guides
+
+3. **Check Type Definitions:**
+   ```tsx
+   // Import and check TypeScript types
+   import type { DataTableProps } from '@jmruthers/pace-core';
+   // Hover over type to see prop definitions
+   ```
+
+4. **Use IDE IntelliSense:**
+   - TypeScript types provide inline documentation
+   - Hover over component name to see prop types
+   - Use autocomplete to discover available props
+
+### MUST NOT: Guess About Props or Usage
+
+**❌ WRONG - Guessing props:**
+```tsx
+// Don't guess - this might not work!
+<DataTable
+  data={data}
+  columns={columns}
+  // Missing required rbac prop - will error!
+/>
+```
+
+**✅ CORRECT - Read documentation first:**
+```tsx
+// 1. Read DataTable docs in implementation-guides/data-tables.md
+// 2. Understand required props (rbac is mandatory)
+// 3. Use correct props
+import { DataTable } from '@jmruthers/pace-core';
+
+<DataTable
+  data={data}
+  columns={columns}
+  rbac={{ pageName: 'users' }} // Required - found in docs
+  features={{ search: true, pagination: true }}
+/>
+```
+
+### Documentation Checklist
+
+Before using any pace-core component:
+- [ ] Read component API reference
+- [ ] Check for implementation guide if component is complex
+- [ ] Review TypeScript types for prop definitions
+- [ ] Check examples in documentation
+- [ ] Verify required vs optional props
+- [ ] Understand component behavior and limitations
+
+### Common Documentation Locations
+
+| Component Type | Documentation Location |
+|----------------|----------------------|
+| Basic UI (Button, Card, etc.) | `api-reference/components.md` |
+| DataTable | `implementation-guides/data-tables.md` |
+| Forms | `implementation-guides/forms.md` |
+| RBAC Components | `rbac/getting-started.md` |
+| File Upload/Display | `implementation-guides/file-upload-storage.md` |
+| Hooks | `api-reference/hooks.md` |
+| Utilities | `api-reference/utilities.md` |
+
+## SHOULD: Check pace-core Before Creating New Components
+
+**Before creating a new component, hook, or utility:**
+
+1. Check pace-core exports: `@jmruthers/pace-core`
+2. Review pace-core documentation
+3. Check `core-usage-manifest.json` for available exports
+4. Search pace-core source if needed
+
+**If pace-core doesn't provide what you need:**
+- Consider if it should be added to pace-core (for shared use)
+- Document why custom solution is needed
+- Follow pace-core patterns for consistency
+
+## MUST: Use pace-core Providers
+
+**You MUST wrap your app with required providers:**
+
+```tsx
+import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider supabaseClient={supabase} appName="Your App">
+      <OrganisationProvider>
+        {/* Your app */}
+      </OrganisationProvider>
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+## MUST: Import Core Styles
+
+**You MUST import pace-core styles:**
+
+```tsx
+// main.tsx or App.tsx
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+## MUST NOT: Use Inline Styles
+
+**You MUST NOT use inline styles (`style={{...}}`).** All styling MUST come from pace-core components and Tailwind classes.
+
+### Why No Inline Styles
+
+- Inline styles override pace-core component styles
+- Inline styles break consistency across the PACE suite
+- Inline styles are harder to maintain and update
+- Inline styles don't benefit from theme variables and design system
+
+### Use pace-core Components for Styling
+
+**All styling MUST come from:**
+1. **pace-core components** - Components already have correct styling
+2. **Tailwind utility classes** - Use Tailwind classes for layout and spacing
+3. **Semantic classes** - Use semantic classes from pace-core (e.g., `bg-background`, `text-foreground`)
+
+**MUST NOT:**
+- Use `style={{...}}` prop
+- Use inline CSS strings
+- Override component styles with inline styles
+- Create custom CSS for styling that pace-core provides
+
+**Example:**
+```tsx
+// ❌ WRONG - Inline styles
+<div style={{ backgroundColor: 'blue', padding: '10px', color: 'white' }}>
+  Content
+</div>
+
+// ❌ WRONG - Inline styles on pace-core component
+<Button style={{ backgroundColor: 'red' }}>Click me</Button>
+
+// ✅ CORRECT - Use pace-core component with Tailwind classes
+<Card className="bg-main-500 p-4 text-white">
+  <CardContent>Content</CardContent>
+</Card>
+
+// ✅ CORRECT - Use pace-core component as-is (already styled)
+<Button variant="default">Click me</Button>
+
+// ✅ CORRECT - Use Tailwind for layout/spacing only
+<div className="flex items-center gap-4 p-4">
+  <Button>Action</Button>
+</div>
+```
+
+### When Tailwind Classes Are Acceptable
+
+**Tailwind classes are acceptable for:**
+- Layout (flex, grid, positioning)
+- Spacing (margin, padding, gap)
+- Responsive design (breakpoints)
+- Layout-specific styling not provided by pace-core components
+
+**Tailwind classes MUST NOT:**
+- Override pace-core component internal styles
+- Duplicate styling that pace-core components already provide
+- Use standard Tailwind colors (use `main-*`, `sec-*`, `acc-*` namespaces)
+
+### Styling Checklist
+
+Before adding any styling:
+- [ ] Check if pace-core component provides the styling you need
+- [ ] Use pace-core component variants/props for styling
+- [ ] Use Tailwind classes only for layout/spacing
+- [ ] Never use inline `style={{...}}` prop
+- [ ] Never override component styles with inline styles
+- [ ] Use semantic classes (`bg-background`, `text-foreground`) when available
+
+## SHOULD: Use pace-core Patterns
+
+**Follow pace-core patterns for consistency:**
+- Component structure and composition
+- Error handling patterns
+- Loading state patterns
+- Form validation patterns
+- RBAC permission checking patterns
+
+## Common Mistakes to Avoid
+
+1. **Using inline styles** - Never use `style={{...}}`, use pace-core components and Tailwind classes
+2. **Guessing component props** - Always read documentation first
+3. **Creating duplicate components** - Always check pace-core first
+4. **Using base Supabase client** - Always use `useSecureSupabase()`
+5. **Missing RBAC setup** - Always call `setupRBAC()` first
+6. **Missing providers** - Always wrap with required providers
+7. **Missing styles** - Always import core.css
+8. **Direct library imports** - Use pace-core wrappers instead
+
+## Reference
+
+- **pace-core Exports**: See `pace-core-exports.mdc` for complete export reference
+- **RBAC Implementation**: See `rbac-implementation.mdc` for RBAC patterns
+- **Component Documentation**: 
+  - API Reference: `node_modules/@jmruthers/pace-core/docs/api-reference/components.md`
+  - Implementation Guides: `node_modules/@jmruthers/pace-core/docs/implementation-guides/`
+  - Detailed API: `node_modules/@jmruthers/pace-core/docs/api/`
+- **Always read documentation before using components** - Never guess about props or usage

package/cursor-rules/01-standards-compliance.mdc

@@ -0,0 +1,275 @@
+---
+description: Enforce compliance with all pace-core standards across architecture, API, components, code style, security, testing, and RBAC/RLS
+globs: ["src/**/*.{ts,tsx,js,jsx}", "supabase/migrations/**/*.sql"]
+alwaysApply: true
+paceCoreVersion: "0.5.x"
+rulesVersion: "2025-01-15"
+---
+# Standards Compliance Guide
+
+This guide ensures consuming apps comply with all pace-core standards. Follow these standards to maintain quality, security, and consistency.
+
+## Architecture Standard
+
+### MUST: Follow Architecture Principles
+
+**MUST adhere to:**
+- Composition over complexity
+- Separation of concerns
+- Domain-agnostic design
+- Extensible, stable APIs
+- Secure by default
+- Performance-conscious
+
+### MUST: Use Helper Functions in RLS Policies
+
+**RLS policies MUST use helper functions, NEVER subqueries.**
+
+```sql
+-- ❌ WRONG - Subquery in RLS policy (causes N+1 queries)
+CREATE POLICY rbac_select_users ON users
+  FOR SELECT USING (
+    organisation_id IN (
+      SELECT organisation_id FROM organisation_memberships 
+      WHERE user_id = auth.uid()
+    )
+  );
+
+-- ✅ CORRECT - Helper function
+CREATE OR REPLACE FUNCTION get_user_organisation_ids()
+RETURNS uuid[]
+LANGUAGE plpgsql
+STABLE
+SECURITY DEFINER
+SET search_path TO public
+AS $$
+BEGIN
+  RETURN ARRAY(
+    SELECT organisation_id 
+    FROM organisation_memberships 
+    WHERE user_id = get_effective_user_id()
+  );
+END;
+$$;
+
+CREATE POLICY rbac_select_users ON users
+  FOR SELECT USING (organisation_id = ANY(get_user_organisation_ids()));
+```
+
+### MUST: Test Database Migrations
+
+**MUST verify migrations don't cause query timeouts or performance degradation.**
+
+## API & RPC Standard
+
+### MUST: Follow RPC Naming Convention
+
+**RPCs MUST follow pattern: `<family>_<domain>_<verb>`**
+
+- `data_*` prefix for read operations: `data_cake_dishes_list`, `data_file_reference_list`
+- `app_*` prefix for write operations: `app_cake_dish_create`, `app_cake_dish_update`
+- CRUD verbs only: `create`, `read`, `update`, `delete`, `list`, `get`
+- Bulk operations: `_bulk` suffix (e.g., `app_cake_dish_create_bulk`)
+
+```sql
+-- ✅ CORRECT
+CREATE FUNCTION data_cake_dishes_list(...)
+CREATE FUNCTION app_cake_dish_create(...)
+CREATE FUNCTION app_cake_dish_create_bulk(...)
+
+-- ❌ WRONG
+CREATE FUNCTION getDishes(...)
+CREATE FUNCTION create_dish(...)
+```
+
+### MUST: Use ApiResult Shape
+
+**All RPCs MUST return ApiResult shape:**
+
+```typescript
+type ApiResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; error: ApiError };
+
+type ApiError = {
+  code: string;
+  message: string;
+  details?: object;
+};
+```
+
+### MUST: Enforce RLS in RPCs
+
+**RPCs MUST enforce RLS and tenant boundaries.** Never bypass RLS.
+
+### SHOULD: Make Write RPCs Idempotent
+
+**Write RPCs SHOULD be idempotent when possible.**
+
+## Component Standard
+
+### MUST: Follow Component Principles
+
+**Components MUST:**
+- Be stateless when possible
+- Use composable structure
+- Be accessible by default
+- Be fully typed
+- Have small surface area
+
+### MUST NOT: Add Domain Logic to Components
+
+**Components MUST NOT:**
+- Include domain-specific logic
+- Fetch data directly (use hooks/services)
+- Include business workflows
+
+### MUST: Ensure Accessibility
+
+**Components MUST:**
+- Be keyboard operable
+- Have correct ARIA roles
+- Have visible focus states
+- Avoid inaccessible interactions
+
+## Code Style Standard
+
+### MUST: Follow TypeScript Rules
+
+**MUST:**
+- Use strict mode (`strict: true` in tsconfig)
+- Prefer discriminated unions
+- Use ReadonlyArray where possible
+- Avoid boolean mode flags (use unions instead)
+
+**MUST NOT:**
+- Use `any` (use `unknown` if type is truly unknown)
+- Use implicit any
+- Use unnecessary type assertions
+
+### MUST: Follow Naming Conventions
+
+- Hooks: `useSomething`
+- Providers: `SomethingProvider`
+- Utilities: `camelCase`
+- Components: `PascalCase`
+
+### SHOULD: Use Preferred Patterns
+
+**SHOULD:**
+- Use pure functions
+- Prefer composition over inheritance
+- Use early returns
+- Extract large functions into small helpers
+
+## Security Standard
+
+### MUST: Never Bypass RLS
+
+**MUST enforce RLS on all tables.** Never bypass RLS policies.
+
+### MUST: Validate All Inputs
+
+**MUST validate all inputs using Zod schemas or similar.**
+
+### MUST: Sanitize Logs
+
+**MUST NOT log:**
+- Passwords
+- Tokens
+- Sensitive data (PII)
+
+**MAY log:**
+- IDs
+- Non-PII metadata
+
+### MUST: Use Safe Error Messaging
+
+**MUST NOT expose internal details in error messages.**
+
+### MUST: Use Helper Functions in RLS
+
+**RLS policies MUST use STABLE SECURITY DEFINER helper functions:**
+- `STABLE` - Results consistent within transaction
+- `SECURITY DEFINER` - Bypass RLS to avoid recursion
+- `SET search_path TO 'public'` - Prevent search path injection
+
+## Testing Standard
+
+### MUST: Meet Coverage Requirements
+
+**MUST achieve:**
+- ≥90% coverage for utils & hooks
+- ≥70% coverage for components
+
+### MUST: Use React Testing Library
+
+**MUST use React Testing Library + userEvent for component tests.**
+
+### SHOULD: Colocate Tests
+
+**Tests SHOULD be colocated: `*.test.ts` or `*.test.tsx`**
+
+### SHOULD: Test Critical Paths
+
+**SHOULD test:**
+- Key user interactions
+- Error handling
+- Edge cases
+- Critical business logic
+
+## RBAC & RLS Standard
+
+### MUST: Use Helper Functions
+
+**All RLS policies MUST use helper functions with:**
+- `STABLE` attribute
+- `SECURITY DEFINER` attribute
+- `SET search_path TO 'public'`
+
+### MUST: Follow Policy Naming
+
+**RLS policies MUST follow pattern: `rbac_{operation}_{table_name}_{scope}`**
+
+Example: `rbac_select_users_organisation`
+
+### MUST: Include Organisation Context
+
+**RLS policies MUST include `organisation_id` for multi-tenant isolation.**
+
+### MUST: Include Super Admin Checks
+
+**RLS policies SHOULD include super admin checks where appropriate.**
+
+## Standards Precedence
+
+When standards conflict, follow this order:
+1. Security Standard (highest priority)
+2. API & RPC Standard
+3. Component Standard
+4. Code Style Standard
+5. Testing Standard
+6. Documentation Standard
+
+## Compliance Checklist
+
+Before committing code, verify:
+- [ ] RLS policies use helper functions (no subqueries)
+- [ ] RPCs follow naming convention
+- [ ] Components are accessible and typed
+- [ ] No `any` types used
+- [ ] Inputs are validated
+- [ ] Tests meet coverage requirements
+- [ ] No sensitive data in logs
+- [ ] Error messages are safe
+
+## Reference
+
+See `packages/core/docs/standards/` for complete standards documentation:
+- 01-architecture-standard.md
+- 02-api-and-rpc-standard.md
+- 03-component-standard.md
+- 04-code-style-standard.md
+- 05-security-standard.md
+- 06-testing-and-docs-standard.md
+- 07-rbac-and-rls-standard.md