@jmruthers/pace-core 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Unified Context Selector**: New `ContextSelector` component that intelligently shows all accessible organisations and events in a single dropdown. Replaces the need for separate `OrganisationSelector`, `EventSelector`, and `HybridContextSelector` components.
+  - Automatically determines what to show based on user's roles and permissions
+  - Shows superset of all accessible orgs and events
+  - Works for all app types (org-based, event-based, hybrid)
+  - Used by default in `Header` and `PaceAppLayout` components
+
+### Changed
+- **Header Component**: Now uses unified `ContextSelector` by default instead of separate `OrganisationSelector` and `EventSelector`
+  - New prop: `showContextSelector` (default: `true`) - replaces `showEventSelector` and `showOrgSelector`
+- **PaceAppLayout Component**: Now uses unified `ContextSelector` by default
+  - New prop: `showContextSelector` (default: `true`)
+
+### Removed
+- **OrganisationSelector**: Removed - use `ContextSelector` instead
+- **EventSelector**: Removed - use `ContextSelector` instead
+- **HybridContextSelector**: Removed - use `ContextSelector` instead
+- **Header.showEventSelector**: Removed - use `showContextSelector` instead
+- **Header.showOrgSelector**: Removed - use `showContextSelector` instead
+- **PaceAppLayout.showEventSelector**: Removed - use `showContextSelector` instead
+- **PaceAppLayout.showOrgSelector**: Removed - use `showContextSelector` instead
+
+### Breaking Changes
+- **RBAC Scope Migration**: App-level scope (`rbac_apps.requires_event`) has been removed. All scope is now page-level only (`rbac_app_pages.scope_type`).
+  - **Removed**: `UnifiedAuthProvider.appConfig` prop - scope is now determined per page
+  - **Removed**: `useAppConfig().requiresEvent` and `useAppConfig().supportsDirectAccess` - use `getPageScopeType()` instead
+  - **Removed**: `ContextValidator.validateScope()` - use `ContextValidator.resolveScopeForPage()` instead
+  - **Removed**: `ContextValidator.resolveRequiredContext()` - use `ContextValidator.resolveScopeForPage()` instead
+  - **Removed**: `ContextValidator.isContextReady()` - context readiness is now checked per page
+  - **Removed**: `RBACSecurityValidator.validateContextRequirements()` - no longer needed
+  - **Removed**: `getAppConfigByName()` - use `getPageScopeType()` instead
+  - **Changed**: `useRBAC()` now requires `pageId` parameter for proper scope resolution
+  - **Changed**: `getPermissionMap()`, `getRoleContext()`, and `getAccessLevel()` no longer accept `appConfig` parameter
+
+### Migration Required
+**⚠️ CRITICAL**: All consuming apps must migrate to page-level scope. See [RBAC Scope Migration Guide](./docs/migration/RBAC_SCOPE_MIGRATION.md) for detailed instructions.
+
+**Quick Steps:**
+1. Run database migration: `supabase/migrations/20251231130000_migrate_scope_to_page_level.sql`
+2. Update all pages in `rbac_app_pages` to have explicit `scope_type` set
+3. Remove `appConfig` prop from `UnifiedAuthProvider`
+4. Update `useRBAC(pageId)` calls to pass `pageId` parameter
+5. Replace `useAppConfig().requiresEvent` with `getPageScopeType(pageId)`
+6. Update any code using deprecated `ContextValidator` methods
+
+### 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
@@ -14,25 +87,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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 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 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+
-- Consuming apps should install and configure React Compiler for optimal performance
-- See `docs/migration/REACT_19_MIGRATION.md` for complete migration instructions
+- 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]
 

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

@@ -1,9 +1,9 @@
 ---
 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"
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
 ---
 # pace-core Compliance Guide
 
@@ -31,16 +31,8 @@ This guide ensures consuming apps use pace-core components, hooks, and utilities
 
 **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>;
-}
+// ❌ WRONG: <button className="btn">Click me</button>
+// ✅ CORRECT: import { Button } from '@jmruthers/pace-core'; <Button>Click me</Button>
 ```
 
 ### Hooks
@@ -59,19 +51,8 @@ function MyComponent() {
 
 **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);
+// ❌ WRONG: Custom useDebounce hook implementation
+// ✅ CORRECT: import { useDebounce } from '@jmruthers/pace-core'; const debouncedValue = useDebounce(value, 500);
 ```
 
 ### Utilities
@@ -90,30 +71,49 @@ const debouncedValue = useDebounce(value, 500);
 
 **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);
+// ❌ 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.
 
+**CRITICAL SECURITY REQUIREMENT:** Using `createClient()` from `@supabase/supabase-js` directly bypasses organisation context enforcement and RLS policies, which can lead to:
+- Cross-organisation data access
+- Security vulnerabilities  
+- Data leakage between organisations
+
 ```tsx
-// ❌ WRONG - Direct Supabase client
+// ❌ WRONG: Direct Supabase client creation
 import { createClient } from '@supabase/supabase-js';
-const supabase = createClient(...);
-await supabase.from('users').select('*');
+const supabase = createClient(url, key);
+// This bypasses organisation context and RLS policies!
 
-// ✅ CORRECT - Use secure client
+// ✅ CORRECT: Use secure Supabase client
 import { useSecureSupabase } from '@jmruthers/pace-core/rbac';
 const secureSupabase = useSecureSupabase();
-await secureSupabase.from('users').select('*');
+// Organisation context is automatically enforced
+```
+
+### Detection and Enforcement
+
+pace-core provides multiple layers of protection:
+
+1. **ESLint Rule**: The `no-direct-supabase-client` rule detects `createClient` calls and reports errors
+2. **Runtime Warnings**: Development mode warnings when insecure clients are detected
+3. **Type Safety**: Use `isSecureClient()` to verify clients are secure
+
+```tsx
+// Verify client is secure (optional, but recommended)
+import { isSecureClient, warnIfInsecureClient } from '@jmruthers/pace-core/rbac/utils/clientSecurity';
+
+const supabase = useSecureSupabase();
+warnIfInsecureClient(supabase, 'MyComponent'); // Warns in dev if insecure
+
+if (isSecureClient(supabase)) {
+  // Client is secure, safe to use
+}
 ```
 
 ## MUST: Setup RBAC Before Use
@@ -124,9 +124,7 @@ await secureSupabase.from('users').select('*');
 // 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
@@ -184,27 +182,13 @@ ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
 
 **❌ WRONG - Guessing props:**
 ```tsx
-// Don't guess - this might not work!
-<DataTable
-  data={data}
-  columns={columns}
-  // Missing required rbac prop - will error!
-/>
+<DataTable data={data} columns={columns} /> // Missing required rbac prop
 ```
 
 **✅ 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 }}
-/>
+<DataTable data={data} columns={columns} rbac={{ pageName: 'users' }} features={{ search: true }} />
 ```
 
 ### Documentation Checklist
@@ -249,16 +233,9 @@ Before using any pace-core component:
 
 ```tsx
 import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <UnifiedAuthProvider supabaseClient={supabase} appName="Your App">
-      <OrganisationProvider>
-        {/* Your app */}
-      </OrganisationProvider>
-    </UnifiedAuthProvider>
-  );
-}
+<UnifiedAuthProvider supabaseClient={supabase} appName="Your App">
+  <OrganisationProvider>{/* Your app */}</OrganisationProvider>
+</UnifiedAuthProvider>
 ```
 
 ## MUST: Import Core Styles
@@ -296,26 +273,8 @@ import '@jmruthers/pace-core/styles/core.css';
 
 **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>
+// ❌ 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

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

@@ -1,9 +1,9 @@
 ---
 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"
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
 ---
 # Standards Compliance Guide
 
@@ -26,34 +26,16 @@ This guide ensures consuming apps comply with all pace-core standards. Follow th
 **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;
+-- ❌ 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()));
+CREATE POLICY rbac_select_users ON users FOR SELECT USING (organisation_id = ANY(get_user_organisation_ids()));
 ```
 
 ### MUST: Test Database Migrations
@@ -72,14 +54,8 @@ CREATE POLICY rbac_select_users ON users
 - 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(...)
+-- ✅ 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
@@ -87,15 +63,8 @@ CREATE FUNCTION create_dish(...)
 **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;
-};
+type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError };
+type ApiError = { code: string; message: string; details?: object };
 ```
 
 ### MUST: Enforce RLS in RPCs

package/cursor-rules/02-project-structure.mdc

@@ -1,9 +1,9 @@
 ---
 description: Define standard folder structure and file organization for consuming apps
-globs: ["**/*.{ts,tsx,js,jsx,md}"]
-alwaysApply: true
-paceCoreVersion: "0.5.x"
-rulesVersion: "2025-01-15"
+globs: ["**/*.{ts,tsx,js,jsx,md}", "src/**"]
+alwaysApply: false
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
 ---
 # Project Structure Standard