@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/migration/rbac-migration.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T21:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC Migration Guide
@@ -684,3 +684,59 @@ const hasPermissionSecure = await isPermitted({
 - **Automatic input sanitization** prevents injection attacks
 
 The new RBAC system provides a more robust, performant, and secure foundation for your application's permission management.
+
+## ♿ Accessibility
+
+RBAC migration should maintain accessibility:
+
+- **Accessibility testing after migration** - Verify all permission-guarded components remain accessible after migration
+- **Screen reader compatibility** - Test with assistive technologies after migration
+- **Keyboard navigation** - Ensure keyboard navigation still works after migration
+- **Focus management** - Verify focus management is correct after migration
+- **Permission announcements** - Ensure permission changes are properly announced
+
+### Accessibility Best Practices
+
+1. **Test accessibility after migration** - Run accessibility tests after each migration step
+2. **Verify keyboard navigation** - Ensure all permission-guarded elements remain keyboard accessible
+3. **Test with screen readers** - Verify permission checks work with assistive technologies
+4. **Check focus indicators** - Ensure focus indicators are visible and correct
+5. **Announce permission changes** - Use ARIA live regions for permission state changes
+
+## ⚠️ Edge Cases
+
+### Permission Check Failures
+
+When permission checks fail after migration:
+- Verify RLS policies are correctly configured
+- Check organisation context is properly set
+- Ensure user has required roles assigned
+- Review permission string format
+- Test with different user roles
+
+### Migration Incomplete
+
+When migration is only partially complete:
+- Document what was migrated and what wasn't
+- Create remediation plan for remaining items
+- Test partially migrated code thoroughly
+- Set timeline for completing migration
+- Monitor for issues in partially migrated code
+
+### Performance Issues After Migration
+
+When performance degrades after migration:
+- Check for unnecessary permission checks
+- Review caching configuration
+- Verify batch operations are used where appropriate
+- Test with performance profiling tools
+- Consider using permission memoization
+
+### Role Assignment Issues
+
+When role assignments don't work correctly:
+- Verify database roles are correctly assigned
+- Check organisation context is properly set
+- Review role assignment process
+- Test with different role combinations
+- Verify super admin permissions work correctly

package/docs/migration/service-architecture.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T21:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Provider Architecture: Service-Based Design
@@ -58,11 +58,26 @@ function MyComponent() {
 
 ## Service Architecture Overview
 
-### How It Works
+### Three-Layer Architecture
 
-1. **Services** (`src/services/`) - Pure TypeScript classes containing business logic
-2. **Service Providers** (`src/providers/services/`) - React context providers that create service instances
-3. **Hooks** - Convenience hooks that access services from context
+The service architecture follows a clear three-layer pattern:
+
+1. **Service Layer** (`src/services/`) - Pure TypeScript classes containing business logic
+   - No React dependencies
+   - Observable pattern for state changes
+   - Easy to unit test
+
+2. **Provider Layer** (`src/providers/services/`) - React context providers that create service instances
+   - Creates and manages service instances (singleton pattern)
+   - Provides services via React context
+   - Handles service lifecycle
+   - **Note**: Providers do NOT export hooks
+
+3. **Hook Layer** (`src/hooks/services/`) - React hooks for reactive component integration
+   - Access services from context
+   - Subscribe to service state changes
+   - Trigger React re-renders when state changes
+   - **⚠️ Always import hooks from here, not from providers**
 
 ### Service Layer
 
@@ -123,28 +138,31 @@ function MyComponent() {
 }
 ```
 
-### Individual Hooks (For Performance)
+### Individual Service Hooks (For Performance)
 
-For better performance, use individual hooks:
+For better performance, use individual service hooks:
 
 ```tsx
 import { 
   useEvents, 
   useOrganisations, 
   useAuthService,
-  useRBACService 
+  useEventService,
+  useOrganisationService
 } from '@jmruthers/pace-core';
 
 function MyComponent() {
-  const events = useEvents();
-  const orgs = useOrganisations();
-  const auth = useAuthService();
-  const rbac = useRBACService();
+  const events = useEvents();              // Convenience hook
+  const orgs = useOrganisations();         // Convenience hook
+  const authService = useAuthService();    // Direct service hook
+  const eventService = useEventService();   // Direct service hook
   
   // Only re-renders when relevant service state changes
 }
 ```
 
+**Important**: Service hooks (like `useAuthService`, `useEventService`) are exported from `hooks/services/` and include state subscription logic. Always import them from the main package or `hooks/services/`, never from `providers/services/`.
+
 ## Testing
 
 ### Testing Services
@@ -216,3 +234,48 @@ Add the required inactivity management props:
 - [API Reference](../../api-reference/providers.md)
 - [Architecture Documentation](../../architecture/services.md)
 - [Example Apps](../../getting-started/examples/)
+
+## ♿ Accessibility
+
+Service architecture migration should maintain accessibility:
+
+- **Accessibility testing after migration** - Verify all components remain accessible after migration
+- **Screen reader compatibility** - Test with assistive technologies after migration
+- **Keyboard navigation** - Ensure keyboard navigation still works after migration
+- **Focus management** - Verify focus management is correct after migration
+
+### Accessibility Best Practices
+
+1. **Test accessibility after migration** - Run accessibility tests after each migration step
+2. **Verify keyboard navigation** - Ensure all interactive elements remain keyboard accessible
+3. **Test with screen readers** - Verify components work with assistive technologies
+4. **Check focus indicators** - Ensure focus indicators are visible and correct
+
+## ⚠️ Edge Cases
+
+### Service Initialization Failures
+
+When services fail to initialize:
+- Verify all required props are provided
+- Check Supabase client is properly configured
+- Review service dependencies
+- Test with minimal configuration
+- Verify environment variables are set correctly
+
+### Service Context Not Available
+
+When service context is not available:
+- Verify service provider is properly mounted
+- Check provider order and hierarchy
+- Review service provider composition
+- Test with service provider examples
+- Verify hooks are called within provider context
+
+### Performance Issues After Migration
+
+When performance degrades after migration:
+- Check for unnecessary re-renders
+- Review service instance creation
+- Verify memoization is working correctly
+- Test with performance profiling tools
+- Consider using individual hooks instead of unified hook

package/docs/rbac/README.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC System
@@ -339,6 +339,82 @@ This allows users with `org_admin` role to access `<PagePermissionGuard pageName
 - **Cache Security** - Secure cache key generation
 - **Type Safety** - Compile-time permission validation
 
+## ♿ Accessibility
+
+The RBAC system is designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All RBAC components meet accessibility standards
+- **Screen Reader Support** - Permission states and errors are properly announced
+- **Keyboard Navigation** - All permission-protected content is keyboard accessible
+- **Focus Management** - Proper focus handling during permission checks and loading states
+- **Error Announcements** - Permission errors are clearly communicated to assistive technologies
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer semantic elements for permission-protected content
+2. **Provide clear fallbacks** - Use descriptive fallback messages for access denied states
+3. **Announce permission changes** - Use ARIA live regions for dynamic permission updates
+4. **Test with screen readers** - Verify permission operations work with assistive technologies
+5. **Ensure keyboard access** - All permission-protected content should be keyboard accessible
+
+## ⚠️ Edge Cases
+
+### Permission Changes During Session
+
+When user permissions change during active session:
+- Permission checks update automatically via cache invalidation
+- Protected content appears/disappears dynamically
+- No page refresh required
+- Clear feedback explains permission changes
+
+### Missing Permission Data
+
+When permission data is missing or unavailable:
+- System fails securely (denies access by default)
+- Clear error messages explain the issue
+- Fallback UI is shown when appropriate
+- User-friendly error messages guide recovery
+
+### Network Failures During Permission Checks
+
+When network fails during permission validation:
+- Operations fail securely (deny by default)
+- Cached permissions may be used when available
+- Error messages clearly explain the issue
+- Retry mechanisms are available
+
+### Concurrent Permission Operations
+
+When multiple permission operations occur simultaneously:
+- Operations are queued and processed in order
+- Permission checks prevent conflicts
+- Audit logging tracks all operations
+- Data consistency is maintained
+
+### Invalid Permission Scopes
+
+When invalid permission scopes are provided:
+- Validation errors are clearly displayed
+- Operations fail gracefully
+- No unauthorized data access
+- User-friendly error messages guide correction
+
+### Super Admin Bypass
+
+When super admin bypasses permission checks:
+- Bypass is clearly logged in audit trail
+- UI indicates elevated privileges
+- Security is maintained through audit logging
+- Clear warnings indicate privilege status
+
+### Database Connection Loss
+
+When database connection is lost:
+- Permission checks fail securely (deny by default)
+- Cached permissions may be used when available
+- Clear error messages explain the issue
+- System recovers automatically when connection is restored
+
 ## 📚 Next Steps
 
 - **[Quick Start Guide](./quick-start.md)** - Build your first RBAC-enabled app

package/docs/rbac/advanced-patterns.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Advanced RBAC Patterns
@@ -773,3 +773,47 @@ function PerformanceTrackedComponent({ userId, scope }) {
 ```
 
 These advanced patterns provide powerful tools for building sophisticated permission systems while maintaining performance and security. Choose the patterns that best fit your application's needs and complexity.
+
+## ♿ Accessibility
+
+Advanced RBAC patterns maintain accessibility standards:
+
+- **WCAG 2.1 AA compliant** - All advanced pattern implementations meet accessibility standards
+- **Screen Reader Support** - Permission states and errors are properly announced
+- **Keyboard Navigation** - All permission-protected content is keyboard accessible
+- **Focus Management** - Proper focus handling during complex permission checks
+- **Error Announcements** - Permission errors are clearly communicated
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer semantic elements in advanced pattern implementations
+2. **Provide clear fallbacks** - Use descriptive fallback messages for access denied
+3. **Test with screen readers** - Verify advanced patterns work with assistive technologies
+4. **Ensure keyboard access** - All interactive elements should be keyboard accessible
+5. **Announce permission changes** - Use ARIA live regions for dynamic updates
+
+## ⚠️ Edge Cases
+
+### Performance Optimization Failures
+
+When performance optimizations don't work:
+- Check that caching is properly configured
+- Verify batch operations are correctly implemented
+- Ensure permission checks are not blocking
+- Review performance metrics for bottlenecks
+
+### Complex Permission Scenario Failures
+
+When complex permission scenarios fail:
+- Verify all permission dependencies are correctly set up
+- Check that permission hierarchies are properly configured
+- Ensure conditional logic handles all edge cases
+- Review error messages for specific issues
+
+### Custom Permission Logic Issues
+
+When custom permission logic doesn't work:
+- Verify custom logic is correctly implemented
+- Check that custom logic integrates with RBAC system
+- Ensure custom logic respects security boundaries
+- Review error messages for specific issues

package/docs/rbac/api-reference.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC API Reference
@@ -612,24 +612,41 @@ import { createClient } from '@supabase/supabase-js';
 const supabase = createClient(url, key);
 
 // Grant organisation role
-const { data: roleId } = await supabase.rpc('grant_organisation_role', {
+const { data: roleId, error: grantError } = await supabase.rpc('rbac_role_grant', {
   p_user_id: 'user-123',
   p_organisation_id: 'org-456',
-  p_role: 'org_admin',
+  p_role_name: 'org_admin',
   p_notes: 'Promoted to administrator'
 });
 
+if (grantError) {
+  console.error('Failed to grant role:', grantError);
+  return;
+}
+
 // Get user roles
-const { data: roles } = await supabase.rpc('get_user_roles', {
-  p_user_id: 'user-123'
+const { data: roles, error: rolesError } = await supabase.rpc('rbac_roles_list', {
+  p_user_id: 'user-123',
+  p_organisation_id: 'org-456'
 });
 
+if (rolesError) {
+  console.error('Failed to get roles:', rolesError);
+  return;
+}
+
 // Revoke role
-const { data: success } = await supabase.rpc('revoke_organisation_role', {
+const { data: success, error: revokeError } = await supabase.rpc('rbac_role_revoke', {
   p_user_id: 'user-123',
   p_organisation_id: 'org-456',
+  p_role_name: 'org_admin',
   p_notes: 'Role revoked'
 });
+
+if (revokeError) {
+  console.error('Failed to revoke role:', revokeError);
+  return;
+}
 ```
 
 ## Core Functions
@@ -1084,3 +1101,55 @@ export async function POST(request: Request) {
 ```
 
 For more examples and advanced usage patterns, see the [Examples Guide](./examples.md) and [Advanced Patterns](./advanced-patterns.md).
+
+## ♿ Accessibility
+
+All RBAC hooks and components are designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All components meet accessibility standards
+- **Screen Reader Support** - Permission states and errors are properly announced
+- **Keyboard Navigation** - All permission-protected content is keyboard accessible
+- **Focus Management** - Proper focus handling during permission checks and loading states
+- **Error Announcements** - Permission errors are clearly communicated to assistive technologies
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer semantic elements for permission-protected content
+2. **Provide clear fallbacks** - Use descriptive fallback messages for access denied states
+3. **Announce permission changes** - Use ARIA live regions for dynamic permission updates
+4. **Test with screen readers** - Verify permission operations work with assistive technologies
+5. **Ensure keyboard access** - All permission-protected content should be keyboard accessible
+
+## ⚠️ Edge Cases
+
+### Permission Check Failures
+
+When permission checks fail:
+- System fails securely (denies access by default)
+- Clear error messages explain the issue
+- Cached permissions may be used when available
+- Retry mechanisms are available
+
+### Invalid Hook Parameters
+
+When invalid parameters are provided to hooks:
+- Validation errors are clearly displayed
+- Operations fail gracefully
+- No unauthorized data access
+- User-friendly error messages guide correction
+
+### Concurrent Permission Operations
+
+When multiple permission operations occur simultaneously:
+- Operations are queued and processed in order
+- Permission checks prevent conflicts
+- Audit logging tracks all operations
+- Data consistency is maintained
+
+### Cache Invalidation Issues
+
+When cache invalidation doesn't work:
+- Manual cache refresh may be required
+- Check that cache keys are correct
+- Verify cache TTL settings
+- Review cache invalidation triggers

package/docs/rbac/event-based-apps.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-01-27T00:00:00+00:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Event-Based Apps with RBAC
@@ -456,7 +456,7 @@ export function Dashboard() {
 
   return (
     <div className="min-h-screen bg-sec-50">
-      <nav className="bg-white shadow">
+      <nav className="bg-background shadow">
         <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
           <div className="flex justify-between h-16">
             <div className="flex items-center">
@@ -545,7 +545,7 @@ export function Participants() {
 
   return (
     <div className="min-h-screen bg-sec-50">
-      <nav className="bg-white shadow">
+      <nav className="bg-background shadow">
         <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
           <div className="flex justify-between h-16">
             <div className="flex items-center">
@@ -870,3 +870,48 @@ If you're still having problems after following this guide exactly:
 
 This guide is designed to be foolproof - if you follow it exactly, your event-based RBAC system will work correctly.
 
+## ♿ Accessibility
+
+The event-based RBAC system includes accessibility features:
+
+- **WCAG 2.1 AA compliant** - All RBAC components meet accessibility standards
+- **Screen Reader Support** - Permission states and errors are properly announced
+- **Keyboard Navigation** - All permission-protected content is keyboard accessible
+- **Focus Management** - Proper focus handling during permission checks
+- **Error Announcements** - Permission errors are clearly communicated
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer semantic elements in your components
+2. **Provide clear fallbacks** - Use descriptive fallback messages for access denied
+3. **Test with screen readers** - Verify your app works with assistive technologies
+4. **Ensure keyboard access** - All interactive elements should be keyboard accessible
+5. **Announce permission changes** - Use ARIA live regions for dynamic updates
+
+## ⚠️ Edge Cases
+
+### Event Selection Failures
+
+When event selection fails:
+- Verify event exists and belongs to organisation
+- Check that user has access to the event
+- Ensure event context is properly set
+- Review error messages for specific issues
+
+### Organisation Resolution Issues
+
+When organisation can't be resolved from event:
+- Verify event has correct organisation_id
+- Check that organisation exists and is active
+- Ensure user has access to the organisation
+- Review event-organisation relationship
+
+### Permission Check Failures
+
+When permission checks fail:
+- Verify `setupRBAC()` was called before using RBAC
+- Check that app name matches exactly (case-sensitive)
+- Ensure user has organisation role assigned
+- Verify page permissions exist in database
+- Confirm event is selected in context
+

package/docs/rbac/examples/rbac-rls-integration-example.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC-RLS Integration Example

package/docs/rbac/examples.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # RBAC Examples
@@ -891,3 +891,39 @@ function ContextAwareComponent({ appId }) {
 ```
 
 These examples demonstrate the flexibility and power of the PACE Core RBAC system. For more advanced patterns and optimization techniques, see the [Advanced Patterns Guide](./advanced-patterns.md).
+
+## ♿ Accessibility
+
+All RBAC examples are designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All example components meet accessibility standards
+- **Screen Reader Support** - Permission states and errors are properly announced
+- **Keyboard Navigation** - All permission-protected content is keyboard accessible
+- **Focus Management** - Proper focus handling during permission checks
+- **Error Announcements** - Permission errors are clearly communicated
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer semantic elements in your components
+2. **Provide clear fallbacks** - Use descriptive fallback messages for access denied
+3. **Test with screen readers** - Verify your app works with assistive technologies
+4. **Ensure keyboard access** - All interactive elements should be keyboard accessible
+5. **Announce permission changes** - Use ARIA live regions for dynamic updates
+
+## ⚠️ Edge Cases
+
+### Permission Check Failures in Examples
+
+When permission checks fail in examples:
+- Verify `setupRBAC()` was called before using RBAC
+- Check that app name matches exactly (case-sensitive)
+- Ensure user has organisation role assigned
+- Verify page permissions exist in database
+
+### Example Code Not Working
+
+When example code doesn't work:
+- Check that all required dependencies are installed
+- Verify provider setup matches examples exactly
+- Ensure database setup is complete
+- Review error messages for specific issues