@jmruthers/pace-core 0.6.5 → 0.6.7

package/CHANGELOG.md

@@ -7,7 +7,111 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Breaking Changes
+- **@supabase/supabase-js is now an included dependency (security enforcement)**: Moved from peer dependency to included dependency to enforce security rules. Consuming apps can no longer import `createClient` directly.
+  - **Action Required**: 
+    - Remove `@supabase/supabase-js` from your `package.json` if installed
+    - Replace `createClient` imports with `createBaseClient()` from `@jmruthers/pace-core`
+  - **Migration**: 
+    ```tsx
+    // ❌ OLD: Direct import
+    import { createClient } from '@supabase/supabase-js';
+    const supabase = createClient(url, key);
+    
+    // ✅ NEW: Use pace-core wrapper
+    import { createBaseClient } from '@jmruthers/pace-core';
+    const supabase = createBaseClient(url, key);
+    ```
+  - **Why**: Enforces security rules - prevents insecure client usage
+  - See [Dependencies Guide](./docs/getting-started/dependencies.md) for details
+
+- **@radix-ui/* packages are now included dependencies (consistency enforcement)**: Moved from peer dependencies to included dependencies to enforce consistency. Consuming apps can no longer import Radix UI primitives directly.
+  - **Action Required**: 
+    - Remove all `@radix-ui/*` packages from your `package.json` if installed
+    - Replace Radix UI imports with pace-core components
+  - **Migration**: 
+    ```tsx
+    // ❌ OLD: Direct Radix UI import
+    import { Checkbox } from '@radix-ui/react-checkbox';
+    
+    // ✅ NEW: Use pace-core component
+    import { Checkbox } from '@jmruthers/pace-core';
+    ```
+  - **Why**: Enforces consistency - prevents bypassing pace-core components
+  - See [Dependencies Guide](./docs/getting-started/dependencies.md) for details
+
+- **lucide-react is now an included dependency (consistency enforcement)**: Moved from peer dependency to included dependency to enforce consistency. Consuming apps can no longer import icons directly from `lucide-react`.
+  - **Action Required**: 
+    - Remove `lucide-react` from your `package.json` if installed
+    - Replace `lucide-react` imports with `@jmruthers/pace-core/icons`
+  - **Migration**: 
+    ```tsx
+    // ❌ OLD: Direct lucide-react import
+    import { ChevronDown, Edit } from 'lucide-react';
+    
+    // ✅ NEW: Use pace-core icon exports
+    import { ChevronDown, Edit } from '@jmruthers/pace-core/icons';
+    ```
+  - **Why**: Enforces consistency - all icons available through pace-core
+  - **Note**: All lucide-react icons are now exported from `@jmruthers/pace-core/icons`
+  - See [Dependencies Guide](./docs/getting-started/dependencies.md) for details
+
+- **@tanstack/react-query is a peer dependency**: Consuming apps need direct access to `QueryClient`, `QueryClientProvider`, and React Query hooks for configuration.
+  - **Action Required**: Install `@tanstack/react-query@^5.90.0` in your consuming app
+  - See [Dependencies Guide](./docs/getting-started/dependencies.md) for details
+
+- **date-fns and date-fns-tz are peer dependencies**: Consuming apps may need direct access to date-fns functions that pace-core doesn't export.
+  - **Action Required**: Install `date-fns@^3.0.0` and `date-fns-tz@^3.0.0` in your consuming app
+  - See [Dependencies Guide](./docs/getting-started/dependencies.md) for details
+
+### Breaking Changes
+- **RBAC Package Surface Area Reduction**: Removed redundant and overlapping RBAC exports to enforce a single correct pattern
+  - **Components Removed**:
+    - `PermissionEnforcer` → Use `PagePermissionGuard` instead
+    - `PermissionGuard` (from adapters) → Use `PagePermissionGuard` instead
+    - `AccessLevelGuard` → Use `useAccessLevel` hook + conditional rendering instead
+    - `RoleBasedRouter` → Use `PagePermissionGuard` + React Router instead
+    - `EnhancedNavigationMenu` → Use `NavigationMenu` + `NavigationGuard` instead
+    - `PagePermissionProvider` → Use `PagePermissionGuard` directly instead
+    - `SecureDataProvider` → Use `useSecureSupabase` hook directly instead
+    - `NavigationProvider` → Use `NavigationGuard` directly instead
+  - **Hooks Removed**:
+    - `useHasAnyPermission` → Use `useMultiplePermissions` with appropriate logic instead
+    - `useHasAllPermissions` → Use `useMultiplePermissions` with appropriate logic instead
+    - `useCachedPermissions` → Caching is automatic in all hooks
+  - **API Functions Removed**:
+    - `hasPermission` → Use `isPermitted` instead
+    - `hasPermissionCached` (from adapters) → Use `isPermittedCached` or hooks (automatic caching) instead
+    - `hasAnyPermissionCached` (from adapters) → Use `hasAnyPermission` or hooks (automatic caching) instead
+  - **Internal Exports Marked**: The following exports are now marked as `@internal` and should not be used by consuming apps:
+    - `RBACEngine`, `createRBACEngine` → Use `isPermitted` API instead
+    - `RBACCache`, `rbacCache`, `CACHE_PATTERNS` → Caching is automatic
+    - `SecureSupabaseClient`, `createSecureClient`, `fromSupabaseClient` → Use `useSecureSupabase` hook instead
+  - **Server Adapters**: Server-side adapters (`withPermissionGuard`, `withAccessLevelGuard`, `withRoleGuard`, `createRBACMiddleware`, `createRBACExpressMiddleware`) remain available for server-side route protection but are optional utilities.
+  
+  **Migration Required**: See [RBAC Migration Guide](./docs/rbac/MIGRATION_GUIDE.md) for detailed migration instructions.
+
+- **RBAC Contract v2.0.0**: Enforced RBAC contract with strict compliance rules
+  - **ESLint Rules**: All RBAC compliance rules are now **ERROR** severity (not warnings)
+  - **EventPageGuard Removed**: Wrapper components around `PagePermissionGuard` are forbidden. Use `PagePermissionGuard` directly and handle event context validation in page components.
+  - **Custom AccessDenied Forbidden**: Custom access denied components are forbidden. Use `AccessDenied` from `@jmruthers/pace-core/rbac` instead.
+  - **Direct RBAC Queries Forbidden**: Direct queries to RBAC tables are forbidden. Use `useSecureSupabase` hook instead.
+  - **Direct RPC Calls Forbidden**: Direct calls to `rbac_check_permission_simplified` are forbidden. Use `isPermitted` from pace-core instead.
+  - **enforcePermissions Clarified**: For event-based apps, `enforcePermissions` must be `false`. For organisation-based apps, it must be `true`.
+  
+  **Migration Required**: See [RBAC Migration Guide](./docs/rbac/MIGRATION_GUIDE.md) for detailed migration instructions.
+
 ### Added
+- **Standard AccessDenied Component**: New `AccessDenied` component exported from `@jmruthers/pace-core/rbac` for consistent access denied UX across all apps
+- **RBAC Contract Documentation**: New `RBAC_CONTRACT.md` defining the mandatory contract between pace-core and consuming apps
+- **RBAC Migration Guide**: New `MIGRATION_GUIDE.md` with step-by-step migration instructions
+- **Enhanced ESLint Rules**: New rules for RBAC compliance:
+  - `no-direct-rbac-rpc`: Detects direct RPC calls to `rbac_check_permission_simplified`
+  - `no-direct-rbac-tables`: Detects direct queries to RBAC tables
+  - `no-bypass-page-guard`: Detects routes without `PagePermissionGuard`
+  - `no-custom-access-denied`: Detects custom access denied components
+- **Pattern Detection**: New `pattern-detector.ts` for static and runtime RBAC violation detection
+- **Enhanced Compliance Tools**: Updated `runtime-compliance.ts` with pattern detection capabilities
 - **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

package/README.md

@@ -1,415 +1,17 @@
 # @jmruthers/pace-core
 
-Clean, modern React component library with Tailwind v4 styling and native utilities.
+React component library with Tailwind v4.
 
-## ⚠️ Breaking Changes
-
-### Version 0.5.65+ - Mandatory Inactivity Timeouts
-
-The `UnifiedAuthProvider` now requires mandatory inactivity timeout configuration for security:
-
-```tsx
-// ❌ Before (will cause TypeScript errors)
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <AppContent />
-</UnifiedAuthProvider>
-
-// ✅ After (required configuration)
-<UnifiedAuthProvider 
-  supabaseClient={supabase} 
-  appName="my-app"
-  idleTimeoutMs={30 * 60 * 1000}  // Required
-  warnBeforeMs={5 * 60 * 1000}    // Required
-  onIdleLogout={() => navigate('/login')}  // Required
->
-  <AppContent />
-</UnifiedAuthProvider>
-```
-
-[📖 Migration Guide](./docs/migration-guides/unified-auth-provider-mandatory-timeouts.md)
-
-## 🚀 PaceAppLayout Usage
-
-**PaceAppLayout uses React Router's nested routing pattern for optimal performance and scalability.**
-
-```tsx
-// ✅ Correct usage with React Router
-<Router>
-  <Routes>
-    <Route path="/" element={<PaceAppLayout appName="My App" />}>
-      <Route path="dashboard" element={<Dashboard />} />
-      <Route path="settings" element={<Settings />} />
-    </Route>
-  </Routes>
-</Router>
-```
-
-## 📦 Type System
-
-PACE Core uses a domain-driven type organization for better maintainability and discoverability:
-
-```typescript
-// Import from domain-specific modules
-import type { Event } from '@jmruthers/pace-core/types/event';
-import type { Organisation } from '@jmruthers/pace-core/types/organisation';
-import type { User, Session } from '@jmruthers/pace-core/types/auth';
-import type { UserId, AppId, PageId } from '@jmruthers/pace-core/types/core';
-import type { RBACPermissionCheckParams } from '@jmruthers/pace-core/rbac/types/functions';
-```
-
-See the [Types API Reference](./docs/api-reference/types.md) for complete type documentation.
-
-## 🚀 Complete Installation Guide
-
-### 1. Install Dependencies
+## Installation
 
 ```bash
-# Install pace-core and required peer dependencies
-npm install @jmruthers/pace-core @tanstack/react-table @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-slot lucide-react class-variance-authority clsx tailwind-merge
-
-# Install Tailwind CSS v4 and Vite plugin
-npm install -D @tailwindcss/vite tailwindcss@^4.0.0
-```
-
-### 2. Import Core Styles
-
-```tsx
-// src/main.tsx (or your app's entry point)
-import '@jmruthers/pace-core/src/styles/core.css';
-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>
-    <App />
-  </React.StrictMode>
-);
-```
-
-### 3. Configure Vite with Tailwind v4
-
-**⚠️ CRITICAL**: This configuration is required for:
-1. **Tailwind CSS scanning** - Ensures components are styled
-2. **React context consistency** - Prevents "useUnifiedAuth must be used within a UnifiedAuthProvider" errors
-3. **Router context availability** - Prevents "useNavigate() may be used only in the context of a <Router>" errors
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-import path from 'path'
-
-export default defineConfig({
-  plugins: [
-    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
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./src"),
-    },
-    // CRITICAL: Dedupe React and React Router to ensure single instances
-    // This prevents Router context issues when pace-core uses react-router-dom
-    dedupe: ['react', 'react-dom', 'react-router-dom']
-  },
-  // CRITICAL: Exclude pace-core from pre-bundling to prevent React context mismatches
-  // Pre-bundling creates separate React instances, causing context errors
-  optimizeDeps: {
-    include: [
-      'react',
-      'react-dom',
-      'react/jsx-runtime',
-      '@radix-ui/react-slot'
-    ],
-    // CRITICAL: Exclude pace-core from pre-bundling
-    // This ensures pace-core uses the same React instance as your app
-    // NOTE: react-router-dom should be INCLUDED, not excluded (excluding causes "module is not defined" errors)
-    exclude: ['@jmruthers/pace-core']
-  },
-  server: {
-    port: 3000,
-    open: true,
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
-  },
-})
-```
-
-**Fallback Configuration:** If the CSS-first approach doesn't work, you can explicitly include pace-core source files:
-
-```typescript
-// vite.config.ts - Fallback configuration
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  // ... rest of config
-})
-```
-
-### 4. Verify Installation
-
-Create a test component to ensure everything works:
-
-```tsx
-// src/App.tsx
-import { Button, Card, Input } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <div className="p-8 space-y-4">
-      <h1 className="text-2xl font-bold text-main-900">PACE Core Test</h1>
-      
-      <Card className="p-4">
-        <h2 className="text-lg font-semibold text-sec-800 mb-2">Components Test</h2>
-        <div className="space-y-2">
-          <Button variant="primary" className="bg-main-600 text-main-50">
-            Primary Button
-          </Button>
-          <Button variant="secondary" className="bg-sec-500 text-main-50">
-            Secondary Button
-          </Button>
-          <Input placeholder="Test input field" className="border-main-300" />
-        </div>
-      </Card>
-    </div>
-  );
-}
-
-export default App;
-```
-
-**Expected Result:** You should see properly styled components with PACE Core's design system colors and typography.
-
-## ⚠️ Critical Configuration Notes
-
-### Why Source File Scanning is Required
-
-Pace-core v0.4.15+ includes source files in the published package because:
-
-- Tailwind v4 needs to scan original TypeScript/JSX files to detect utility classes
-- Compiled JavaScript files don't contain the class names Tailwind needs
-- Without proper scanning, only ~292 CSS rules are generated instead of 800+ needed
-
-### Alternative Configuration (if source files don't work)
-
-If you're still having issues with component scanning:
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        // Try source files first
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}',
-        // Fallback: also scan dist files
-        './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-### Legacy Configuration (v0.4.14 and below)
-
-For older versions, use this configuration:
-
-```typescript
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-## 🔍 Troubleshooting
-
-### Issue: "useUnifiedAuth must be used within a UnifiedAuthProvider"
-
-**Cause**: Vite is pre-bundling `@jmruthers/pace-core`, creating separate React instances
-
-**Solution**:
-1. Add to `vite.config.ts`:
-   ```typescript
-   optimizeDeps: {
-     exclude: ['@jmruthers/pace-core', 'react-router-dom']
-   }
-   ```
-2. Clear Vite cache: `rm -rf node_modules/.vite`
-3. Restart dev server
-
-### Issue: "useNavigate() may be used only in the context of a <Router> component"
-
-**Cause**: Incorrect provider nesting - BrowserRouter should wrap UnifiedAuthProvider
-
-**Solution**:
-1. Ensure correct nesting order in `main.tsx`:
-   ```tsx
-   <QueryClientProvider>
-     <BrowserRouter>
-       <UnifiedAuthProvider>
-         <OrganisationProvider>
-           <App />
-         </OrganisationProvider>
-       </UnifiedAuthProvider>
-     </BrowserRouter>
-   </QueryClientProvider>
-   ```
-2. Do NOT put BrowserRouter inside UnifiedAuthProvider
-3. Add to `vite.config.ts`:
-   ```typescript
-   resolve: {
-     dedupe: ['react', 'react-dom', 'react-router-dom']
-   }
-   ```
-
-### Issue: Only 292 CSS rules instead of 800+
-
-**Solution**: 
-1. Update to pace-core v0.4.15+
-2. Use source file paths: `./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}`
-3. Clear build cache: `rm -rf dist .vite node_modules && npm install`
-
-### Issue: Components appear unstyled
-
-**Solution**: 
-1. Check your Vite configuration includes pace-core source files
-2. Ensure CSS file is imported: `import '@jmruthers/pace-core/src/styles/core.css'`
-3. Restart dev server after configuration changes
-
-### Issue: Build errors with source files
-
-**Solution**: Add TypeScript configuration for node_modules:
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "skipLibCheck": true
-  }
-}
+npm install @jmruthers/pace-core
 ```
 
-### Issue: "Access Denied" errors with valid permissions
-
-**Problem**: Users with valid permissions see "Access Denied" when loading pages with DataTable components.
-
-**Root Cause**: Race condition in permission checking - `useCan` hook was being called with invalid scopes before scope resolution completed.
-
-**Solution**: Fixed in v0.5.7+ - the `useCan` hook now properly handles invalid scopes and shows loading state until valid scope is available.
-
-**What was fixed**:
-- `useCan` hook skips API calls when `organisationId` is empty
-- `PagePermissionGuard` shows loading state during scope resolution
-- Eliminates race condition between scope resolution and permission checking
-
-**No action needed** - this is automatically fixed in v0.5.7+
-
-## Features
-
-- 🎨 **Complete Design System** - Colors, typography, spacing, shadows
-- 🧩 **React Components** - Buttons, inputs, cards, data tables, and more
-- 🔐 **RBAC System** - Role-based access control with Supabase
-- 🎨 **Tailwind v4** - CSS-first approach with design tokens
-- 📱 **Responsive** - Mobile-first design patterns
-- ♿ **Accessible** - WCAG compliant components
-- 🚀 **Performance** - Tree-shakeable, optimized bundle
-
 ## Documentation
 
-- [Quick Start Guide](./docs/getting-started/quick-start.md) - Complete step-by-step tutorial
-- [Installation Guide](./docs/getting-started/installation.md) - Detailed setup instructions
-- [Vite Configuration](./docs/consuming-app-vite-config.md) - **CRITICAL** Tailwind scanning setup
-- [Component API](./docs/api/README.md) - All available components and hooks
-- [Styling Guide](./docs/styles/README.md) - Understanding the design system
-- [Troubleshooting](./docs/troubleshooting/styling-issues.md) - Fix common styling problems
-- [Tailwind Content Scanning](./docs/troubleshooting/tailwind-content-scanning.md) - **NEW** Comprehensive scanning solutions
-
-## Import Strategy
-
-PACE Core provides two import paths to optimize for different use cases:
-
-### Main Export (Recommended for Common Components)
-
-Use the main export for frequently used components and utilities:
-
-```typescript
-import { 
-  Button, 
-  Card, 
-  Input, 
-  DropdownMenu, 
-  Select, 
-  Dialog,
-  useUnifiedAuth 
-} from '@jmruthers/pace-core';
-```
-
-**Available from main export:**
-- **Basic UI**: Button, Card, Input, Textarea, Label, Alert, Avatar, Checkbox, Progress
-- **Advanced UI**: Dialog (with HTML content), DropdownMenu, Select, Toast, Tooltip, Tabs, Calendar
-- **Data Display**: DataTable (with hierarchical actions & expand/collapse all), Table
-- **Forms**: Form, LoginForm
-- **Layout**: PaceAppLayout, Header, Footer, NavigationMenu
-- **Providers**: UnifiedAuthProvider, OrganisationProvider, EventProvider
-- **Hooks**: useUnifiedAuth, useOrganisations, useEvents
-
-### Component Documentation
-
-- **[DataTable Component](docs/implementation-guides/data-tables.md)** - Enterprise-grade data table with hierarchical rows, expand/collapse all, actions, sorting, filtering, and performance optimization
-  - **[Hierarchical DataTable Guide](docs/implementation-guides/hierarchical-datatable.md)** - Complete guide for implementing parent/child rows with expand/collapse all and smart sorting
-- **[Dialog Component](src/components/Dialog/README.md)** - Comprehensive dialog system with smart height management, scrolling, HTML content rendering, and accessibility features
-- **[Storage System](src/utils/storage/README.md)** - File storage utilities with organization-scoped access control
-
-### Complete Components Export (For Specialized Components)
-
-Use the complete export for specialized or advanced components:
-
-```typescript
-import { 
-  DataTable, 
-  NavigationMenu,
-  FormField
-} from '@jmruthers/pace-core/components';
-```
+See [Documentation](./docs/README.md) for complete setup and usage guides.
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details.
+MIT License - see [LICENSE](./LICENSE) for details.