@jmruthers/pace-core 0.2.4

package/docs/app.css.example

@@ -0,0 +1,53 @@
+/**
+ * Example app.css file for consuming applications
+ * 
+ * This file demonstrates how to define your app's specific color palette
+ * using the new pace-core styling system.
+ * 
+ * Copy this file to your app as app.css and update the color values
+ * to match your brand.
+ */
+
+@theme static {
+  /* MAIN palette - your primary brand color */
+  --color-main-raw: oklch(0.7 0.057 252.02);
+  --color-main-50:  oklch(0.98 0.001 252.02);
+  --color-main-100: oklch(0.96 0.005 252.02);
+  --color-main-200: oklch(0.927 0.012 252.02);
+  --color-main-300: oklch(0.881 0.021 252.02);
+  --color-main-400: oklch(0.822 0.032 252.02);
+  --color-main-500: oklch(0.75 0.047 252.02);
+  --color-main-600: oklch(0.7 0.057 252.02);
+  --color-main-700: oklch(0.567 0.044 252.02);
+  --color-main-800: oklch(0.456 0.034 252.02);
+  --color-main-900: oklch(0.332 0.024 252.02);
+  --color-main-950: oklch(0.195 0.014 252.02);
+
+  /* SEC palette - your secondary brand color */
+  --color-sec-raw:  oklch(0.58 0.23 280.75);
+  --color-sec-50:   oklch(0.98 0.003 280.75);
+  --color-sec-100:  oklch(0.96 0.014 280.75);
+  --color-sec-200:  oklch(0.927 0.033 280.75);
+  --color-sec-300:  oklch(0.881 0.059 280.75);
+  --color-sec-400:  oklch(0.822 0.093 280.75);
+  --color-sec-500:  oklch(0.75 0.133 280.75);
+  --color-sec-600:  oklch(0.665 0.182 280.75);
+  --color-sec-700:  oklch(0.58 0.23 280.75);
+  --color-sec-800:  oklch(0.456 0.158 280.75);
+  --color-sec-900:  oklch(0.332 0.099 280.75);
+  --color-sec-950:  oklch(0.195 0.047 280.75);
+
+  /* ACC palette - your accent brand color */
+  --color-acc-raw:  oklch(0.64 0.21 37.76);
+  --color-acc-50:   oklch(0.98 0.003 37.76);
+  --color-acc-100:  oklch(0.96 0.015 37.76);
+  --color-acc-200:  oklch(0.927 0.035 37.76);
+  --color-acc-300:  oklch(0.881 0.063 37.76);
+  --color-acc-400:  oklch(0.822 0.099 37.76);
+  --color-acc-500:  oklch(0.75 0.143 37.76);
+  --color-acc-600:  oklch(0.64 0.21 37.76);
+  --color-acc-700:  oklch(0.567 0.177 37.76);
+  --color-acc-800:  oklch(0.456 0.13 37.76);
+  --color-acc-900:  oklch(0.332 0.085 37.76);
+  --color-acc-950:  oklch(0.195 0.044 37.76);
+}

package/docs/architecture/README.md

@@ -0,0 +1,577 @@
+# PACE Core Architecture
+
+This document provides a comprehensive overview of the PACE Core architecture, including system design, component relationships, and architectural decisions. This is the single source of truth for PACE Core's architectural documentation.
+
+## Overview
+
+PACE Core is a comprehensive React component library and utilities package designed for PACE applications. It provides a complete solution for building modern, accessible, and secure applications with built-in authentication, RBAC, and event management.
+
+## Core Principles
+
+### 1. **Consistency First**
+- All components follow the same design patterns
+- Consistent API design across all components
+- Unified styling system using design tokens
+
+### 2. **Type Safety**
+- Full TypeScript support with strict typing
+- Comprehensive type definitions for all APIs
+- IntelliSense support for better developer experience
+
+### 3. **Accessibility**
+- WCAG 2.1 AA compliance where possible
+- Keyboard navigation support
+- Screen reader compatibility
+- Focus management
+
+### 4. **Performance**
+- Optimized bundle sizes
+- Tree-shaking support
+- Lazy loading where appropriate
+- Memoization for expensive operations
+
+### 5. **Flexibility**
+- Customizable styling through design tokens
+- Extensible component APIs
+- Multiple import strategies
+- Configurable behavior
+
+## System Architecture
+
+### High-Level Architecture
+
+```mermaid
+graph TB
+    A[Your Application] --> B[PACE Core]
+    B --> C[Authentication Layer]
+    B --> D[RBAC System]
+    B --> E[UI Components]
+    B --> F[Utilities]
+    
+    C --> G[Supabase Auth]
+    C --> H[UnifiedAuthProvider]
+    
+    D --> I[Permission Engine]
+    D --> J[Role Management]
+    D --> K[Audit System]
+    
+    E --> L[Form Components]
+    E --> M[Data Components]
+    E --> N[Layout Components]
+    E --> O[Navigation Components]
+    
+    F --> P[Theme System]
+    F --> Q[Validation]
+    F --> R[API Helpers]
+```
+
+### Component Architecture
+
+```mermaid
+graph TD
+    A[PACE Core] --> B[Providers]
+    A --> C[Components]
+    A --> D[Hooks]
+    A --> E[Utilities]
+    A --> F[Types]
+    
+    B --> B1[UnifiedAuthProvider]
+    B --> B2[EventProvider]
+    B --> B3[OrganisationProvider]
+    
+    C --> C1[UI Components]
+    C --> C2[Form Components]
+    C --> C3[Data Components]
+    C --> C4[Layout Components]
+    C --> C5[RBAC Components]
+    
+    D --> D1[useUnifiedAuth]
+    D --> D2[useEvents]
+    D --> D3[useOrganisations]
+    D --> D4[useRBAC]
+    D --> D5[useCan]
+    
+    E --> E1[Validation]
+    E --> E2[API Helpers]
+    E --> E3[Theme Utilities]
+    E --> E4[RBAC Utilities]
+    
+    F --> F1[Auth Types]
+    F --> F2[RBAC Types]
+    F --> F3[Component Types]
+    F --> F4[API Types]
+```
+
+### Component Structure
+
+Each component follows a consistent structure:
+
+```
+ComponentName/
+├── ComponentName.tsx       # Main component
+├── ComponentName.test.tsx  # Unit tests
+├── ComponentName.stories.tsx # Storybook stories
+├── components/             # Sub-components
+├── hooks/                  # Component-specific hooks
+├── types.ts               # Component types
+└── index.ts               # Exports
+```
+
+### Component Design Patterns
+
+1. **Compound Components**: Components that work together (e.g., DataTable + DataTableHeader + DataTableBody)
+2. **Render Props**: Flexible rendering patterns for complex components
+3. **Controlled/Uncontrolled**: Support for both controlled and uncontrolled usage
+4. **Composition**: Components that can be composed together
+
+## Core Modules
+
+### 1. Authentication Module
+
+The authentication module provides a unified interface for user authentication across different providers.
+
+**Key Components:**
+- `UnifiedAuthProvider` - Context provider for authentication state
+- `useUnifiedAuth` - Hook for accessing authentication state
+- `PaceLoginPage` - Pre-built login page component
+- `LoginForm` - Login form component
+
+**Architecture:**
+```mermaid
+graph TD
+    A[UnifiedAuthProvider] --> B[Supabase Client]
+    A --> C[Auth State Management]
+    A --> D[Session Management]
+    
+    C --> E[User State]
+    C --> F[Loading State]
+    C --> G[Error State]
+    
+    D --> H[Login/Logout]
+    D --> I[Session Refresh]
+    D --> J[Token Management]
+```
+
+### 2. RBAC System
+
+The Role-Based Access Control system provides comprehensive permission management and enforcement.
+
+**Key Components:**
+- `RBACEngine` - Core permission checking logic
+- `useCan` - Hook for permission checking
+- `PermissionEnforcer` - Component for permission-based rendering
+- `PagePermissionGuard` - Component for page-level protection
+
+**Architecture:**
+```mermaid
+graph TD
+    A[RBAC System] --> B[Permission Engine]
+    A --> C[Role Management]
+    A --> D[Audit System]
+    A --> E[Cache System]
+    
+    B --> F[Permission Checking]
+    B --> G[Access Level Calculation]
+    B --> H[Scope Resolution]
+    
+    C --> I[Global Roles]
+    C --> J[Organisation Roles]
+    C --> K[Event App Roles]
+    
+    D --> L[Audit Logging]
+    D --> M[Event Tracking]
+    D --> N[Compliance Reporting]
+    
+    E --> O[Permission Cache]
+    E --> P[Role Cache]
+    E --> Q[Session Cache]
+```
+
+### 3. UI Components
+
+The UI component system provides a comprehensive set of accessible, customizable components.
+
+**Key Components:**
+- `Button` - Button component with variants
+- `DataTable` - Advanced data table with features
+- `Form` - Form components with validation
+- `Dialog` - Dialog components (replaces Modal)
+- `Select` - Dropdown select components
+
+**Architecture:**
+```mermaid
+graph TD
+    A[UI Components] --> B[Base Components]
+    A --> C[Composite Components]
+    A --> D[Layout Components]
+    A --> E[Form Components]
+    
+    B --> F[Button]
+    B --> G[Input]
+    B --> H[Card]
+    B --> I[Alert]
+    
+    C --> J[DataTable]
+    C --> K[Dialog]
+    C --> L[Select]
+    C --> M[Toast]
+    
+    D --> N[PaceAppLayout]
+    D --> O[Header]
+    D --> P[Footer]
+    D --> Q[NavigationMenu]
+    
+    E --> R[Form]
+    E --> S[FormField]
+    E --> T[FormErrorSummary]
+    E --> U[FormLiveRegion]
+```
+
+### Styling Architecture
+
+PACE Core uses a **design token system** for consistent styling across all consuming applications. The styling system is designed to avoid conflicts with existing applications while providing a unified design language.
+
+For detailed styling information, see [PACE Core Styling Guide](../styles/README.md).
+
+### 4. Event Management
+
+The event management system provides context-aware functionality for event-based applications.
+
+**Key Components:**
+- `EventProvider` - Context provider for event state
+- `useEvents` - Hook for accessing event data
+- `EventSelector` - Component for event selection
+- `EventPermissionEnforcer` - Event-specific permission enforcement
+
+**Architecture:**
+```mermaid
+graph TD
+    A[Event Management] --> B[Event Provider]
+    A --> C[Event Selection]
+    A --> D[Event Permissions]
+    A --> E[Event Context]
+    
+    B --> F[Event State]
+    B --> G[Event Loading]
+    B --> H[Event Error Handling]
+    
+    C --> I[Event List]
+    C --> J[Event Filtering]
+    C --> K[Event Search]
+    
+    D --> L[Event Access Control]
+    D --> M[Event Role Management]
+    D --> N[Event Permission Checking]
+    
+    E --> O[Current Event]
+    E --> P[Event Metadata]
+    E --> Q[Event Configuration]
+```
+
+### 5. Organisation Management
+
+The organisation management system provides multi-tenant support for organisation-based applications.
+
+**Key Components:**
+- `OrganisationProvider` - Context provider for organisation state
+- `useOrganisations` - Hook for accessing organisation data
+- `OrganisationSelector` - Component for organisation selection
+- `OrganisationPermissionEnforcer` - Organisation-specific permission enforcement
+
+**Architecture:**
+```mermaid
+graph TD
+    A[Organisation Management] --> B[Organisation Provider]
+    A --> C[Organisation Selection]
+    A --> D[Organisation Permissions]
+    A --> E[Organisation Context]
+    
+    B --> F[Organisation State]
+    B --> G[Organisation Loading]
+    B --> H[Organisation Error Handling]
+    
+    C --> I[Organisation List]
+    C --> J[Organisation Filtering]
+    C --> K[Organisation Search]
+    
+    D --> L[Organisation Access Control]
+    D --> M[Organisation Role Management]
+    D --> N[Organisation Permission Checking]
+    
+    E --> O[Current Organisation]
+    E --> P[Organisation Metadata]
+    E --> Q[Organisation Configuration]
+```
+
+## Data Flow
+
+### 1. Authentication Flow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant A as App
+    participant P as PACE Core
+    participant S as Supabase
+    
+    U->>A: Login Request
+    A->>P: useUnifiedAuth.login()
+    P->>S: signInWithPassword()
+    S-->>P: Auth Response
+    P-->>A: User State
+    A-->>U: Login Success
+```
+
+### 2. Permission Check Flow
+
+```mermaid
+sequenceDiagram
+    participant C as Component
+    participant H as useCan Hook
+    participant E as RBAC Engine
+    participant D as Database
+    participant A as Audit System
+    
+    C->>H: hasPermission(operation, resource)
+    H->>E: Check Permission
+    E->>D: Query User Roles
+    D-->>E: Role Data
+    E->>E: Calculate Permission
+    E->>A: Log Permission Check
+    E-->>H: Permission Result
+    H-->>C: Boolean Result
+```
+
+### 3. Event Selection Flow
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Component
+    participant E as EventProvider
+    participant D as Database
+    participant R as RBAC
+    
+    U->>C: Select Event
+    C->>E: setSelectedEvent()
+    E->>R: Check Event Access
+    R-->>E: Access Granted
+    E->>D: Load Event Data
+    D-->>E: Event Data
+    E-->>C: Event State Updated
+    C-->>U: UI Updated
+```
+
+## Security Architecture
+
+### 1. Authentication Security
+
+- **JWT Token Management**: Secure token storage and refresh
+- **Session Management**: Automatic session validation and renewal
+- **Password Security**: Integration with Supabase's secure password handling
+- **Multi-Factor Authentication**: Support for MFA through Supabase
+
+### 2. RBAC Security
+
+- **Permission Granularity**: Fine-grained permission system
+- **Role Hierarchy**: Hierarchical role structure
+- **Context Isolation**: Organisation and event context isolation
+- **Audit Logging**: Comprehensive audit trail for all permission checks
+
+### 3. Data Security
+
+- **Row Level Security**: Database-level security policies
+- **API Security**: Secure API endpoints with proper authentication
+- **Input Validation**: Comprehensive input validation and sanitization
+- **XSS Protection**: Built-in XSS protection in components
+
+## Performance Architecture
+
+### 1. Caching Strategy
+
+- **Permission Cache**: In-memory cache for permission checks
+- **Role Cache**: Cached role information for performance
+- **Session Cache**: Cached session data to reduce API calls
+- **Component Cache**: Memoized components for better performance
+
+### 2. Lazy Loading
+
+- **Component Lazy Loading**: Lazy load components when needed
+- **Route Lazy Loading**: Lazy load routes for better initial load time
+- **Data Lazy Loading**: Lazy load data based on user interaction
+
+### 3. Optimization
+
+- **Bundle Splitting**: Optimized bundle splitting for better loading
+- **Tree Shaking**: Dead code elimination for smaller bundles
+- **Code Splitting**: Dynamic imports for better performance
+
+## Scalability Architecture
+
+### 1. Horizontal Scaling
+
+- **Stateless Components**: Components designed for horizontal scaling
+- **Database Scaling**: Support for database read replicas
+- **CDN Integration**: Static asset delivery through CDN
+
+### 2. Vertical Scaling
+
+- **Memory Optimization**: Efficient memory usage patterns
+- **CPU Optimization**: Optimized algorithms and data structures
+- **I/O Optimization**: Efficient database queries and API calls
+
+### 3. Multi-Tenancy
+
+- **Organisation Isolation**: Complete data isolation between organisations
+- **Event Isolation**: Event-specific data isolation
+- **Resource Sharing**: Efficient resource sharing across tenants
+
+## Monitoring and Observability
+
+### 1. Logging
+
+- **Structured Logging**: JSON-structured logs for better parsing
+- **Log Levels**: Configurable log levels for different environments
+- **Log Aggregation**: Centralized log collection and analysis
+
+### 2. Metrics
+
+- **Performance Metrics**: Component render times and performance
+- **Business Metrics**: User actions and business logic metrics
+- **System Metrics**: System health and resource usage
+
+### 3. Tracing
+
+- **Request Tracing**: End-to-end request tracing
+- **Component Tracing**: Component lifecycle tracing
+- **Permission Tracing**: RBAC permission check tracing
+
+## Build System
+
+### Package Structure
+
+PACE Core is built as a single package with multiple entry points:
+
+```json
+{
+  "exports": {
+    ".": "./dist/index.js",
+    "./components": "./dist/components.js",
+    "./rbac": "./dist/rbac/index.js",
+    "./validation": "./dist/validation.js",
+    "./hooks": "./dist/hooks.js",
+    "./styles": "./dist/styles/@jmruthers/pace-core.css",
+    "./styles/tokens": "./dist/styles/design-tokens.css",
+    "./styles/components": "./dist/styles/components.css"
+  }
+}
+```
+
+### Build Process
+
+1. **TypeScript Compilation**: Compile TypeScript to JavaScript
+2. **CSS Processing**: Process CSS files with PostCSS and Tailwind
+3. **Bundle Optimization**: Optimize bundles for production
+4. **Type Generation**: Generate TypeScript declaration files
+
+### Tools Used
+
+- **tsup**: TypeScript bundler for fast builds
+- **PostCSS**: CSS processing and optimization
+- **Tailwind CSS**: Utility-first CSS framework
+- **TypeScript**: Type safety and compilation
+
+### Import Strategies
+
+PACE Core supports tree shaking for optimal bundle sizes and provides multiple import strategies for different use cases. For detailed information about importing components, styles, and utilities, see the [PACE Core Styling Guide](../styles/README.md).
+
+## Development Architecture
+
+### 1. Build System
+
+- **TypeScript**: Full TypeScript support with strict typing
+- **ESBuild**: Fast build system for development and production
+- **Tree Shaking**: Automatic dead code elimination
+- **Source Maps**: Full source map support for debugging
+
+### 2. Testing
+
+- **Unit Testing**: Comprehensive unit test coverage
+- **Integration Testing**: Component integration testing
+- **E2E Testing**: End-to-end testing support
+- **Visual Testing**: Visual regression testing
+
+### Development Workflow
+
+#### Local Development
+
+1. **Install Dependencies**: `npm install`
+2. **Start Development Server**: `npm run dev`
+3. **Run Tests**: `npm run test`
+4. **Build Package**: `npm run build`
+
+#### Testing Strategy
+
+- **Unit Tests**: Jest for component testing
+- **Integration Tests**: Testing component interactions
+- **Visual Tests**: Storybook for visual regression testing
+- **E2E Tests**: Playwright for end-to-end testing
+
+#### Code Quality
+
+- **ESLint**: Code linting and style enforcement
+- **Prettier**: Code formatting
+- **TypeScript**: Type checking
+- **Husky**: Git hooks for quality checks
+
+### 3. Documentation
+
+- **API Documentation**: Comprehensive API documentation
+- **Component Documentation**: Detailed component usage guides
+- **Architecture Documentation**: System architecture documentation
+- **Examples**: Practical usage examples and patterns
+
+## Deployment Architecture
+
+### 1. Build Process
+
+- **Multi-Environment**: Support for multiple deployment environments
+- **Environment Variables**: Secure environment variable management
+- **Build Optimization**: Optimized builds for production
+
+### 2. Package Distribution
+
+- **NPM Package**: Published as NPM package for easy installation
+- **Version Management**: Semantic versioning for package updates
+- **Dependency Management**: Careful dependency management for stability
+
+### 3. Integration
+
+- **Framework Agnostic**: Works with any React-based framework
+- **SSR Support**: Server-side rendering support
+- **Static Generation**: Static site generation support
+
+## Future Architecture
+
+### 1. Planned Features
+
+- **Micro-Frontend Support**: Support for micro-frontend architecture
+- **Plugin System**: Extensible plugin system for custom functionality
+- **Advanced Caching**: More sophisticated caching strategies
+- **Real-time Updates**: WebSocket support for real-time updates
+
+### 2. Scalability Improvements
+
+- **Edge Computing**: Edge computing support for better performance
+- **Progressive Web App**: PWA support for better mobile experience
+- **Offline Support**: Offline functionality for better user experience
+- **Advanced Analytics**: More detailed analytics and monitoring
+
+### 3. Developer Experience
+
+- **CLI Tools**: Command-line tools for better developer experience
+- **Code Generation**: Code generation tools for common patterns
+- **Advanced Debugging**: Better debugging tools and utilities
+- **Performance Profiling**: Built-in performance profiling tools
+
+This architecture provides a solid foundation for building scalable, secure, and maintainable applications with PACE Core. The modular design allows for easy extension and customization while maintaining consistency and reliability.