@jmruthers/pace-core 0.5.184 → 0.5.186

package/docs/implementation-guides/authentication.md

@@ -69,17 +69,64 @@ if (!supabaseUrl || !supabaseAnonKey) {
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
 
-### 4. App Setup with Authentication
+### 4. Configure Vite (CRITICAL)
 
-**CRITICAL**: UnifiedAuthProvider now requires inactivity timeout configuration:
+**⚠️ CRITICAL**: This configuration prevents React context and Router context errors.
+
+Add to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+    // CRITICAL: Dedupe React and React Router to ensure single instances
+    dedupe: ['react', 'react-dom', 'react-router-dom']
+  },
+  // CRITICAL: Exclude pace-core from pre-bundling to prevent React context mismatches
+  optimizeDeps: {
+    include: [
+      'react',
+      'react-dom',
+      'react/jsx-runtime'
+    ],
+    exclude: ['@jmruthers/pace-core', 'react-router-dom']
+  },
+});
+```
+
+### 5. App Setup with Authentication
+
+**⚠️ CRITICAL**: 
+1. Provider nesting order matters - follow the exact structure below
+2. UnifiedAuthProvider requires inactivity timeout configuration
+3. setupRBAC() must be called before rendering
 
 ```tsx
 // src/main.tsx
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 import { BrowserRouter } from 'react-router-dom'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { 
-  UnifiedAuthProvider
+  UnifiedAuthProvider,
+  OrganisationProvider,
+  setupRBAC
 } from '@jmruthers/pace-core'
 import { supabase } from './lib/supabase'
 import App from './App.tsx'
@@ -87,17 +134,46 @@ import App from './App.tsx'
 // CRITICAL: Import the CSS system - includes everything you need
 import '@jmruthers/pace-core/src/styles/core.css'
 
+// ⚠️ REQUIRED: Setup RBAC before rendering
+setupRBAC(supabase);
+
+const queryClient = new QueryClient();
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
-    <BrowserRouter>
-      <UnifiedAuthProvider 
-        supabaseClient={supabase} 
-        appName="my-app"
-        requireOrganisationContext={true}
-        idleTimeoutMs={30 * 60 * 1000}  // 30 minutes - REQUIRED
-        warnBeforeMs={60 * 1000}        // 60 seconds - REQUIRED
-        onIdleLogout={() => window.location.href = '/login'}  // REQUIRED
-      >
+    {/* CRITICAL: Correct nesting order */}
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <UnifiedAuthProvider 
+          supabaseClient={supabase} 
+          appName="my-app"
+          requireOrganisationContext={true}
+          idleTimeoutMs={30 * 60 * 1000}  // 30 minutes - REQUIRED
+          warnBeforeMs={60 * 1000}        // 60 seconds - REQUIRED
+          onIdleLogout={() => window.location.href = '/login'}  // REQUIRED
+        >
+          <OrganisationProvider>
+            <App />
+          </OrganisationProvider>
+        </UnifiedAuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  </React.StrictMode>
+)
+```
+
+**Provider Nesting Order (CRITICAL):**
+1. `React.StrictMode` (outermost)
+2. `QueryClientProvider`
+3. `BrowserRouter`
+4. `UnifiedAuthProvider`
+5. `OrganisationProvider`
+6. `App` (innermost)
+
+**Why this order matters:**
+- `BrowserRouter` must wrap `UnifiedAuthProvider` to provide Router context
+- `UnifiedAuthProvider` must be inside `BrowserRouter` to use Router hooks
+- Wrong nesting causes "useNavigate() may be used only in the context of a <Router>" errors
         <App />
       </UnifiedAuthProvider>
     </BrowserRouter>

package/docs/implementation-guides/file-reference-system.md

@@ -45,14 +45,16 @@ CREATE TABLE file_references (
 
 **Organisation-First Structure:**
 ```
-{bucket}/{orgId}/{category}/{filename}
+{bucket}/{orgId}/{folder}/{timestamp-uuid-filename}
 
 Examples:
 - files/org-123/profile_photos/timestamp-uuid-photo.jpg (private)
-- files/org-123/id_documents/timestamp-uuid-passport.pdf (private)
+- files/org-123/documents/timestamp-uuid-passport.pdf (private)
 - public-files/org-123/event_logos/timestamp-uuid-logo.png (public)
 ```
 
+**Note:** The `folder` prop determines the storage path, while `category` is stored in the `file_metadata` JSONB field for filtering and metadata purposes. You can use the same value for both (e.g., `category={FileCategory.PROFILE_PHOTOS}` and `folder="profile_photos"`), or use different values if needed.
+
 ### Bucket Selection
 
 The system uses two Supabase storage buckets:
@@ -77,7 +79,10 @@ await service.createFileReference({
   table_name: 'pace_person',
   record_id: personId,
   organisation_id: orgId,
+  app_id: 'your-app-id',
   category: FileCategory.PROFILE_PHOTOS,
+  folder: 'profile_photos',
+  pageContext: 'configuration',
   is_public: false // Uses 'files' bucket
 }, file);
 
@@ -86,7 +91,10 @@ await service.createFileReference({
   table_name: 'event',
   record_id: eventId,
   organisation_id: orgId,
+  app_id: 'your-app-id',
   category: FileCategory.EVENT_LOGOS,
+  folder: 'event_logos',
+  pageContext: 'configuration',
   is_public: true // Uses 'public-files' bucket
 }, file);
 ```
@@ -136,6 +144,8 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   organisation_id={orgId}
   app_id="your-app-id" // Optional - auto-resolved from app name if not provided
   category={FileCategory.PROFILE_PHOTOS}
+  folder="profile_photos"
+  pageContext="configuration"
   accept="image/*"
   maxSize={5 * 1024 * 1024}
   onUploadSuccess={(result) => {
@@ -157,6 +167,8 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   organisation_id={orgId}
   // app_id omitted - will be auto-resolved from app name
   category={FileCategory.PROFILE_PHOTOS}
+  folder="profile_photos"
+  pageContext="configuration"
   accept="image/*"
   maxSize={5 * 1024 * 1024}
   showProgress={true}
@@ -191,6 +203,8 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   organisation_id={orgId}
   app_id="your-app-id"
   category={FileCategory.EVENT_LOGOS}
+  folder="event_logos"
+  pageContext="configuration"
   accept="image/*"
   isPublic={true} // Uploads to public-files bucket
   showPreview={true}
@@ -210,6 +224,8 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   organisation_id={orgId}
   app_id="your-app-id"
   category={FileCategory.PROFILE_PHOTOS}
+  folder="profile_photos"
+  pageContext="configuration"
 >
   <div className="custom-upload-ui">
     <p>Click to upload profile photo</p>
@@ -237,6 +253,8 @@ import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
     organisation_id={orgId}
     app_id="your-app-id"
     category={FileCategory.PROFILE_PHOTOS}
+    folder="profile_photos"
+    pageContext="configuration"
   />
 </FileDisplay>
 ```
@@ -331,6 +349,8 @@ const result = await uploadFile({
   organisation_id: orgId,
   app_id: 'your-app-id',
   category: FileCategory.PROFILE_PHOTOS,
+  folder: 'profile_photos',
+  pageContext: 'configuration',
   is_public: false // Uses 'files' bucket
 }, file);
 
@@ -341,6 +361,8 @@ const publicResult = await uploadFile({
   organisation_id: orgId,
   app_id: 'your-app-id',
   category: FileCategory.EVENT_LOGOS,
+  folder: 'event_logos',
+  pageContext: 'configuration',
   is_public: true // Uses 'public-files' bucket
 }, logoFile);
 
@@ -475,14 +497,15 @@ const files = await service.listFileReferences('pace_person', personId, orgId);
 
 ```sql
 -- Create file reference (replaces insert_file_reference)
+-- Requires page context for context-aware permission checks
 SELECT data_file_reference_create(
   p_table_name := 'pace_person',
   p_record_id := 'person-uuid',
   p_file_path := 'org-123/profile_photos/file.jpg',
   p_organisation_id := 'org-uuid',
   p_app_id := 'app-uuid',
+  p_page_context := 'configuration',
   p_file_metadata := '{"fileName": "photo.jpg"}'::jsonb,
-  p_category := 'profile_photos',
   p_is_public := false
 );
 

package/docs/implementation-guides/file-upload-storage.md

@@ -48,6 +48,8 @@ function MyFileUpload() {
       organisation_id="org-123"
       // app_id auto-resolved from app name
       category={FileCategory.GENERAL_DOCUMENTS}
+      folder="documents"
+      pageContext="configuration"
       accept=".pdf,.doc,.docx"
       maxSize={5 * 1024 * 1024} // 5MB
       showProgress={true}
@@ -102,6 +104,8 @@ function UserProfile({ userId }: { userId: string }) {
           record_id={userId}
           organisation_id="org-123"
           category={FileCategory.GENERAL_DOCUMENTS}
+          folder="documents"
+          pageContext="configuration"
           accept=".pdf,.doc,.docx"
           maxSize={10 * 1024 * 1024}
         />
@@ -126,7 +130,9 @@ interface FileUploadProps {
   record_id: string;
   organisation_id: string;
   app_id?: string; // Optional - will be resolved from app name if not provided
-  category: FileCategory;
+  category: FileCategory; // File category for metadata (stored in file_metadata JSONB field)
+  folder: string; // Folder name in storage bucket (e.g., 'profile_photos', 'documents')
+  pageContext: string; // The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
   accept?: string;
   maxSize?: number;
   multiple?: boolean;
@@ -142,6 +148,8 @@ interface FileUploadProps {
 }
 ```
 
+**Note:** The `category` prop is used for metadata purposes (stored in the `file_metadata` JSONB field), while the `folder` prop determines the actual storage path: `{orgId}/{folder}/{timestamp-uuid-filename}`. You can use the same value for both (e.g., `category={FileCategory.PROFILE_PHOTOS}` and `folder="profile_photos"`), or use different values if needed.
+
 #### Usage Examples
 
 **Basic Upload:**
@@ -152,6 +160,8 @@ interface FileUploadProps {
   record_id="person-123"
   organisation_id={organisationId}
   category={FileCategory.PROFILE_PHOTOS}
+  folder="profile_photos"
+  pageContext="configuration"
   accept="image/*"
   maxSize={2 * 1024 * 1024} // 2MB
   onUploadSuccess={(result) => console.log('Uploaded:', result.file_reference)}
@@ -168,6 +178,8 @@ interface FileUploadProps {
   record_id="person-123"
   organisation_id={organisationId}
   category={FileCategory.GENERAL_DOCUMENTS}
+  folder="documents"
+  pageContext="forms"
   multiple={true}
   accept=".pdf,.doc,.docx"
   showProgress={true}
@@ -197,6 +209,23 @@ interface FileUploadProps {
 </FileUpload>
 ```
 
+#### Page Context and Permissions
+
+The `pageContext` parameter enables context-aware permission checks for file uploads. Instead of requiring a generic `'create:files'` permission on a `'files'` page, the system checks permissions based on the actual page where the upload occurs.
+
+**Permission Check Behavior:**
+- The system checks for `'create:page.{pageContext}'` permission first
+- If that permission doesn't exist, it checks for `'update:page.{pageContext}'` permission
+- The user needs at least one of these permissions to upload files
+- This ensures file uploads are controlled by the same permissions as the page where they occur
+
+**Example Use Cases:**
+- Event logo uploads on the `'configuration'` page require `'create:page.configuration'` or `'update:page.configuration'` permission
+- Form document uploads on the `'forms'` page require `'create:page.forms'` or `'update:page.forms'` permission
+- Application file uploads on the `'applications'` page require `'create:page.applications'` or `'update:page.applications'` permission
+
+**Important:** The `pageContext` must match a page defined in your RBAC system (`rbac_app_pages` table) for the permission checks to work correctly.
+
 ### FileDisplay
 
 A component for displaying and managing files associated with database records.

package/docs/rbac/README.md

@@ -66,6 +66,7 @@ function MyComponent() {
 - **[Event-Based Apps](./event-based-apps.md)** - Get up and running in 10 minutes (foolproof guide for event-based apps)
 - **[API Reference](./api-reference.md)** - Complete API documentation
 - **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
+- **[Compliance Guide](./compliance/compliance-guide.md)** - Ensuring proper RBAC/auth setup and usage
 - **[Examples](./examples.md)** - Practical usage examples
 - **[Advanced Patterns](./advanced-patterns.md)** - Complex scenarios and optimizations