@jmruthers/pace-core 0.6.1 → 0.6.3

package/docs/architecture/database-schema-requirements.md

@@ -123,6 +123,167 @@ The RBAC system uses a **single source of truth** approach:
 - All functions use `rbac_organisation_roles` table for role management
 - Views inherit RLS policies from the underlying `rbac_organisation_roles` table
 
+## App Access Tables Architecture
+
+The system uses three complementary tables to manage app availability and user permissions:
+
+### Table Relationship Overview
+
+| Table | Purpose | Question It Answers |
+|-------|---------|-------------------|
+| `core_organisation_app_access` | Organisation-level app configuration | "Is this app available for this organisation?" |
+| `core_event_app_access` | Event-level app availability | "Is this app available for this event?" |
+| `rbac_event_app_roles` | User-specific role grants | "Who can do what for this event-app?" |
+
+### 1. `core_organisation_app_access`
+
+**Purpose:** Organisation-level app configuration and feature flags.
+
+**Schema:**
+```sql
+CREATE TABLE core_organisation_app_access (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id) ON DELETE CASCADE,
+    app_id UUID NOT NULL REFERENCES rbac_apps(id),
+    is_enabled BOOLEAN DEFAULT true,
+    settings JSONB DEFAULT '{}',
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW(),
+    created_by UUID REFERENCES auth.users(id),
+    updated_by UUID REFERENCES auth.users(id)
+);
+```
+
+**Use Cases:**
+- Enable/disable apps at the organisation level
+- Store organisation-specific app settings (e.g., feature flags, configuration)
+- Control which apps are available to an organisation
+
+**Key Characteristics:**
+- Organisation-scoped (one record per organisation-app combination)
+- Contains `is_enabled` flag for feature toggling
+- Contains `settings` JSONB field for app-specific configuration
+
+### 2. `core_event_app_access`
+
+**Purpose:** Event-level app availability flag.
+
+**Schema:**
+```sql
+CREATE TABLE core_event_app_access (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    event_id VARCHAR NOT NULL REFERENCES core_events(event_id),
+    app_id UUID NOT NULL REFERENCES rbac_apps(id) ON DELETE CASCADE,
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id),
+    created_at TIMESTAMPTZ DEFAULT NOW() NOT NULL,
+    updated_at TIMESTAMPTZ DEFAULT NOW() NOT NULL,
+    created_by UUID REFERENCES auth.users(id),
+    updated_by UUID REFERENCES auth.users(id),
+    CONSTRAINT core_event_app_access_unique UNIQUE (event_id, app_id, organisation_id)
+);
+```
+
+**Use Cases:**
+- Enable an app for a specific event
+- Track which apps are available for each event
+- Quick check: "Is this app enabled for this event?"
+
+**Key Characteristics:**
+- Event-scoped (one record per event-app-organisation combination)
+- Unique constraint prevents duplicate entries
+- Simple boolean flag (existence = enabled)
+
+### 3. `rbac_event_app_roles`
+
+**Purpose:** User-specific role grants for event-app combinations.
+
+**Schema:**
+```sql
+CREATE TABLE rbac_event_app_roles (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+    event_id VARCHAR NOT NULL REFERENCES core_events(event_id) ON DELETE CASCADE,
+    app_id UUID NOT NULL REFERENCES rbac_apps(id),
+    organisation_id UUID NOT NULL REFERENCES core_organisations(id),
+    role rbac_event_app_role NOT NULL, -- ENUM: 'viewer', 'participant', 'planner', 'event_admin'
+    status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'inactive', 'suspended')),
+    granted_at TIMESTAMPTZ DEFAULT NOW(),
+    granted_by UUID REFERENCES auth.users(id),
+    valid_from TIMESTAMPTZ DEFAULT NOW(),
+    valid_to TIMESTAMPTZ,
+    CONSTRAINT rbac_event_app_roles_unique UNIQUE (user_id, event_id, app_id, role)
+);
+```
+
+**Use Cases:**
+- Grant specific roles to users for event-app combinations
+- Control what users can do (viewer, participant, planner, event_admin)
+- Time-based role validity (valid_from, valid_to)
+- Role status management (active, inactive, suspended)
+
+**Key Characteristics:**
+- User-scoped (one record per user-event-app-role combination)
+- Includes role hierarchy and permissions
+- Time-based validity support
+- Status tracking for role lifecycle
+
+### Relationship Summary
+
+**Access Tables = "Is this app available?"**
+- `core_organisation_app_access`: Organisation-level availability and settings
+- `core_event_app_access`: Event-level availability flag
+
+**Roles Table = "Who can do what?"**
+- `rbac_event_app_roles`: User-specific role grants with permissions
+
+### Important Notes
+
+1. **Separation of Concerns:**
+   - Access tables handle **configuration** (feature flags, availability)
+   - Roles table handles **authorization** (user permissions)
+
+2. **Independence:**
+   - Access records can exist without roles (app enabled, no users yet)
+   - Roles can exist without access records (legacy data or data inconsistency)
+   - These are intentionally independent to allow flexible configuration
+
+3. **Performance:**
+   - Access tables provide fast feature flag checks without querying user roles
+   - Roles table provides detailed permission information when needed
+
+4. **Data Integrity:**
+   - `core_event_app_access` has unique constraint on `(event_id, app_id, organisation_id)`
+   - `rbac_event_app_roles` has unique constraint on `(user_id, event_id, app_id, role)`
+
+### Example Usage Patterns
+
+```sql
+-- Check if app is available for an event (configuration check)
+SELECT EXISTS (
+    SELECT 1 FROM core_event_app_access
+    WHERE event_id = 'event-123'
+    AND app_id = 'app-456'
+    AND organisation_id = 'org-789'
+);
+
+-- Check if user has access to an event-app (authorization check)
+SELECT EXISTS (
+    SELECT 1 FROM rbac_event_app_roles
+    WHERE user_id = 'user-abc'
+    AND event_id = 'event-123'
+    AND app_id = 'app-456'
+    AND status = 'active'
+    AND valid_from <= NOW()
+    AND (valid_to IS NULL OR valid_to > NOW())
+);
+
+-- Get organisation-level app settings
+SELECT settings FROM core_organisation_app_access
+WHERE organisation_id = 'org-789'
+AND app_id = 'app-456'
+AND is_enabled = true;
+```
+
 ## Required RPC Functions
 
 The following RPC functions are required and should be updated to use the correct tables/views:

package/docs/components/context-selector.md

@@ -0,0 +1,126 @@
+# Context Selector - Unified Intelligent Selector
+
+## Overview
+
+The `ContextSelector` (formerly `HybridContextSelector`) is the **single unified selector** for all pace-core applications. It intelligently shows all organisations and events a user can access based on their roles and permissions.
+
+## Why Unified Selector?
+
+Previously, apps had to choose between:
+- `OrganisationSelector` - for org-based apps
+- `EventSelector` - for event-based apps  
+- `HybridContextSelector` - for hybrid apps
+
+This created complexity and required apps to know their scope type upfront. With page-level scope, we can now intelligently show **everything** the user can access in one place.
+
+## How It Works
+
+The `ContextSelector` automatically:
+
+1. **Shows all accessible organisations** - Based on user's organisation roles
+2. **Shows all accessible events** - Based on user's event-app roles and organisation membership
+3. **Groups items intelligently** - Organisations and Events in separate sections
+4. **Handles super admins** - Shows all orgs and events
+5. **Respects permissions** - Only shows what user can actually access
+
+## Usage
+
+### Basic Usage
+
+```tsx
+import { ContextSelector } from '@jmruthers/pace-core';
+
+function MyHeader() {
+  const { switchOrganisation } = useOrganisations();
+  const { events, setSelectedEvent } = useEvents();
+
+  return (
+    <ContextSelector
+      onOrganisationSelect={(org) => switchOrganisation(org.id)}
+      onEventSelect={(event) => {
+        const fullEvent = events.find(e => e.event_id === event.event_id);
+        setSelectedEvent(fullEvent || event);
+      }}
+    />
+  );
+}
+```
+
+### In Header Component
+
+The `Header` component now uses `ContextSelector` by default:
+
+```tsx
+<Header
+  logoUrl="/logo.svg"
+  showContextSelector={true} // Default: shows unified selector
+  user={user}
+  onSignOut={handleSignOut}
+/>
+```
+
+### In PaceAppLayout
+
+```tsx
+<PaceAppLayout
+  appName="MINT"
+  showContextSelector={true} // Default: shows unified selector
+  navItems={navItems}
+>
+  {children}
+</PaceAppLayout>
+```
+
+## Migration from Separate Selectors
+
+### Before (Separate Selectors)
+
+```tsx
+<Header
+  showOrgSelector={true}
+  showEventSelector={true}
+  // ...
+/>
+```
+
+### After (Unified Selector)
+
+```tsx
+<Header
+  showContextSelector={true} // Single prop replaces both
+  // ...
+/>
+```
+
+## Benefits
+
+1. **Simpler API** - One selector instead of three
+2. **Better UX** - Users see everything they can access in one place
+3. **Intelligent** - Automatically determines what to show based on permissions
+4. **Future-proof** - Works with any app configuration (org-based, event-based, hybrid)
+5. **No configuration needed** - Just use it, it figures out what to show
+
+## Migration from Separate Selectors
+
+**⚠️ BREAKING CHANGE**: The separate selectors have been removed. You must migrate to `ContextSelector`.
+
+### Removed Components
+- `OrganisationSelector` - Use `ContextSelector` instead
+- `EventSelector` - Use `ContextSelector` instead
+- `HybridContextSelector` - Use `ContextSelector` instead
+
+### Removed Props
+- `Header.showEventSelector` - Use `showContextSelector` instead
+- `Header.showOrgSelector` - Use `showContextSelector` instead
+- `PaceAppLayout.showEventSelector` - Use `showContextSelector` instead
+- `PaceAppLayout.showOrgSelector` - Use `showContextSelector` instead
+
+## Implementation Details
+
+The selector uses:
+- `useOrganisations()` - Gets accessible organisations
+- `useEvents()` - Gets accessible events (already filtered by permissions)
+- `useRBAC()` - Checks super admin status
+
+Both hooks already filter based on user permissions, so the selector automatically shows the correct items.
+

package/docs/core-concepts/rbac-system.md

@@ -10,7 +10,7 @@ reviewedBy: documentation-standards-audit
 
 PACE Core provides a comprehensive Role-Based Access Control (RBAC) system that manages user permissions through roles, ensuring secure and scalable access control across your application.
 
-> **🔄 Migrating?** If you're upgrading from the legacy RBAC system, see the [Migration Guide](../migration/rbac-migration.md) for step-by-step instructions.
+> **🔄 Migrating?** If you're upgrading from the legacy RBAC system, see the [Migration Guide](../migration/V0.4.0_rbac-migration.md) for step-by-step instructions.
 
 > **⚠️ IMPORTANT**: You **must** call `setupRBAC()` before using any RBAC features. See the [Quick Start Guide](../rbac/quick-start.md) for setup instructions.
 
@@ -278,7 +278,7 @@ If you're upgrading from a system with hardcoded permissions:
 3. **Replace 'manage' Operations** - Use specific CRUD operations instead
 4. **Enable Cache Invalidation** - Ensure realtime subscriptions are active
 
-For detailed migration instructions, see the **[RBAC Migration Guide](../migration/rbac-migration.md)**.
+For detailed migration instructions, see the **[RBAC Migration Guide](../migration/V0.4.0_rbac-migration.md)**.
 
 ## What's Next?
 
@@ -286,7 +286,7 @@ For detailed migration instructions, see the **[RBAC Migration Guide](../migrati
 - **[RBAC Quick Start](../rbac/quick-start.md)** - Build your first RBAC-enabled app
 - **[RBAC API Reference](../rbac/api-reference.md)** - Complete API documentation
 - **[RBAC Examples](../rbac/examples.md)** - Practical usage examples
-- **[Migration Guide](../migration/rbac-migration.md)** - Migrate from legacy RBAC
+- **[Migration Guide](../migration/V0.4.0_rbac-migration.md)** - Migrate from legacy RBAC
 - **[Installation](../getting-started/installation-guide.md)** - Get PACE Core set up
 - **[Authentication](./authentication.md)** - Understand authentication system
 - **[Organisations](./organisations.md)** - Learn about multi-tenancy

package/docs/documentation-index.md

@@ -96,10 +96,8 @@ This index mirrors the folder layout in `packages/core/docs/` so teams can quick
 
 - [Migration overview](./migration/README.md)
 - [Unified migration guide](./migration/MIGRATION_GUIDE.md)
-- [Quick migration guide](./migration/quick-migration-guide.md)
-- [Organisation context timing fix](./migration/organisation-context-timing-fix.md)
-- [Service architecture changes](./migration/service-architecture.md)
-- [RBAC migration](./migration/rbac-migration.md)
+- [Organisation context timing fix](./migration/V0.3.44_organisation-context-timing-fix.md)
+- [RBAC migration](./migration/V0.4.0_rbac-migration.md)
 - [Tailwind scanning updates](./migration/v0.4.15-tailwind-scanning.md)
 - [CSS-first migration (v0.4.16)](./migration/v0.4.16-css-first-approach.md)
 - [Source path fix (v0.4.17)](./migration/v0.4.17-source-path-fix.md)

package/docs/getting-started/cursor-rules.md

@@ -42,7 +42,7 @@ npm run setup:cursor-rules
 
 The script will:
 - Create `.cursor/rules/` directory if it doesn't exist
-- Copy all pace-core rules (00-07) to your project
+- Copy all pace-core rules (00-08) to your project
 - **Automatically update** pace-core rules (00-09) if they've changed
 - Preserve any existing custom rules (50+)
 - Skip files that are already up to date
@@ -67,6 +67,7 @@ The installed rules are numbered for ordering:
 - **05-bug-reports-and-features.mdc** - Templates for bug reports (guidance-only)
 - **06-code-quality.mdc** - Enforce code quality standards
 - **07-tech-stack-compliance.mdc** - Enforce tech stack versions and patterns
+- **08-markup-quality.mdc** - Enforce clean markup standards, semantic HTML usage, and pace-core component patterns
 
 ## Using Rules with Cursor