@jmruthers/pace-core 0.5.193 → 0.6.2

package/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Removed
+- **DataTable Debug Tools Exports**: Removed all public exports from `packages/core/src/components/DataTable/utils/debugTools.ts` as they were unused. The debug tools functionality remains available internally for development but is no longer exported. Removed exports include:
+  - `DebugLevel` enum
+  - `DebugConfig` interface
+  - `DEFAULT_DEBUG_CONFIG` constant
+  - `DebugLogEntry` interface
+  - `PerformanceTimelineEntry` interface
+  - `MemorySnapshot` interface
+  - `RenderPerformanceData` interface
+  - `DataTableDebugger` class
+  - `dataTableDebugger` instance
+  - `profile` decorator function
+  - `MemoryMonitor` class
+  - `usePerformanceDebugger` hook
+  - `setupDevTools` function
+- **DataTable Type Exports**: Removed duplicative type exports from `packages/core/src/components/DataTable/types.ts`:
+  - `PartialDataRecord<TData>` - Use `Partial<TData>` instead
+  - `CompleteDataRecord<TData>` - Use `TData` directly instead
+- **Flexible Import Helper Functions**: Removed unused helper functions from `packages/core/src/components/DataTable/utils/flexibleImport.ts`:
+  - `createImportOptions()` - Not used anywhere in the codebase
+  - `createRegionalImportOptions()` - Not used anywhere in the codebase
+  - `testDateParsing()` - Not used anywhere in the codebase
+
+### Migration Notes
+- If you were using `PartialDataRecord` or `CompleteDataRecord`, replace them with `Partial<TData>` and `TData` respectively
+- If you were using any of the debug tools exports, they are no longer available. The debug tools remain functional internally but are not exposed as public APIs
+- If you were using `createImportOptions()`, `createRegionalImportOptions()`, or `testDateParsing()`, you'll need to implement similar functionality yourself or use the `flexibleImport()` function directly with manual options
+
+## [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
+- **BREAKING**: Database schema changes (table naming standardization, person-scoped profiles)
+- 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 Guides**: Added comprehensive migration documentation
+
+### Migration Notes
+
+**⚠️ CRITICAL**: This version includes major breaking changes. See migration guides for detailed instructions:
+
+- **React 19 Upgrade**: See [React 19 Migration Guide](./docs/migration/V0.6.0_REACT_19_MIGRATION.md)
+- **Complete Migration Guide**: See [v0.5.190 → v0.6.1 Migration Guide](./docs/migration/V0.5.190_TO_V0.6.1_MIGRATION.md)
+- **Database Changes**: See [Database Changes December 2025](./docs/migration/database-changes-december-2025.md)
+- **Table Naming**: See [Database Changes December 2025](./docs/migration/database-changes-december-2025.md#change-1-table-naming-standardization)
+- **Person-Scoped Profiles**: See [Person-Scoped Profiles Migration Guide](./docs/migration/V0.5.190_person-scoped-profiles-migration-guide.md)
+
+**Quick Summary:**
+- Consuming apps must upgrade to React 19.2.3+
+- Database migrations required for table naming and person-scoped profiles
+- All table names updated to follow `app_entity` naming convention
+- Profiles are now person-scoped instead of organisation-scoped
+
+## [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,299 @@
+---
+description: Enforce pace-core usage patterns and prevent custom solutions when pace-core provides functionality
+globs: ["src/**/*.{ts,tsx,js,jsx}"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# 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: <button className="btn">Click me</button>
+// ✅ CORRECT: import { Button } from '@jmruthers/pace-core'; <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 useDebounce hook implementation
+// ✅ CORRECT: 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 formatDate implementation
+// ✅ CORRECT: 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: import { createClient } from '@supabase/supabase-js'; const supabase = createClient(...);
+// ✅ CORRECT: import { useSecureSupabase } from '@jmruthers/pace-core/rbac'; const secureSupabase = useSecureSupabase();
+```
+
+## 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
+```
+
+## 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
+<DataTable data={data} columns={columns} /> // Missing required rbac prop
+```
+
+**✅ CORRECT - Read documentation first:**
+```tsx
+import { DataTable } from '@jmruthers/pace-core';
+<DataTable data={data} columns={columns} rbac={{ pageName: 'users' }} features={{ search: 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';
+<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: <div style={{ backgroundColor: 'blue' }}> or <Button style={{...}}>
+// ✅ CORRECT: <Card className="bg-main-500 p-4"> or <Button variant="default"> or <div className="flex gap-4">
+```
+
+### 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,244 @@
+---
+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: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# 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 with STABLE SECURITY DEFINER
+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: data_cake_dishes_list, app_cake_dish_create, app_cake_dish_create_bulk
+-- ❌ WRONG: getDishes, create_dish (wrong naming pattern)
+```
+
+### 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