@jmruthers/pace-core 0.5.87 → 0.5.88

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

@@ -38,31 +38,27 @@ graph TD
 
 ```tsx
 import { FileUpload, FileCategory } from '@jmruthers/pace-core';
-import { useFileReference } from '@jmruthers/pace-core';
 
 function MyFileUpload() {
-  const { uploadFile, getFileUrl, deleteFile, isLoading, error } = useFileReference(supabase);
-
-  const handleUpload = async (file: File) => {
-    try {
-      const fileRef = await uploadFile({
-        file,
-        category: FileCategory.DOCUMENT,
-        description: 'User uploaded document'
-      });
-      console.log('File uploaded:', fileRef);
-    } catch (err) {
-      console.error('Upload failed:', err);
-    }
-  };
-
   return (
     <FileUpload
       supabase={supabase}
-      orgId="org-123"
-      onUploadComplete={handleUpload}
+      table_name="person"
+      record_id="person-123"
+      organisation_id="org-123"
+      // app_id auto-resolved from app name
+      category={FileCategory.GENERAL_DOCUMENTS}
       accept=".pdf,.doc,.docx"
       maxSize={5 * 1024 * 1024} // 5MB
+      showProgress={true}
+      showPreview={false}
+      onUploadSuccess={(result) => {
+        console.log('File uploaded:', result.file_reference);
+        console.log('Available at:', result.file_url);
+      }}
+      onUploadError={(error, file) => {
+        console.error(`Upload failed for ${file?.name}:`, error);
+      }}
     >
       <div className="border-2 border-dashed border-main-300 rounded-lg p-8 text-center">
         <p>Drag and drop files here or click to browse</p>
@@ -79,7 +75,7 @@ import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
 import { useFileReferenceForRecord } from '@jmruthers/pace-core';
 
 function UserProfile({ userId }: { userId: string }) {
-  const { fileUrl, uploadFile, deleteFile, isLoading } = useFileReferenceForRecord(
+  const { fileUrl, fileReference, isLoading, error } = useFileReferenceForRecord(
     supabase,
     'pace_person',
     userId,
@@ -91,15 +87,25 @@ function UserProfile({ userId }: { userId: string }) {
       <h2>Profile Documents</h2>
       <FileDisplay
         supabase={supabase}
-        orgId="org-123"
-        recordType="pace_person"
-        recordId={userId}
-        category={FileCategory.DOCUMENT}
-        onUpload={uploadFile}
-        onDelete={deleteFile}
+        table_name="pace_person"
+        record_id={userId}
+        organisation_id="org-123"
+        category={FileCategory.GENERAL_DOCUMENTS}
         showUpload={true}
         showDelete={true}
-      />
+        className="space-y-4"
+      >
+        {/* Optional: Add custom upload component */}
+        <FileUpload
+          supabase={supabase}
+          table_name="pace_person"
+          record_id={userId}
+          organisation_id="org-123"
+          category={FileCategory.GENERAL_DOCUMENTS}
+          accept=".pdf,.doc,.docx"
+          maxSize={10 * 1024 * 1024}
+        />
+      </FileDisplay>
     </div>
   );
 }
@@ -116,15 +122,22 @@ A comprehensive file upload component with drag-and-drop support, validation, an
 ```typescript
 interface FileUploadProps {
   supabase: SupabaseClient;
-  appName: string;
-  orgId: string;
-  onUploadComplete?: (fileRef: FileReference) => void;
-  onUploadStart?: (file: File) => void;
+  table_name: string;
+  record_id: string;
+  organisation_id: string;
+  app_id?: string; // Optional - will be resolved from app name if not provided
+  category: FileCategory;
   accept?: string;
   maxSize?: number;
   multiple?: boolean;
   disabled?: boolean;
+  isPublic?: boolean; // Whether files should be uploaded to public-files bucket
   className?: string;
+  showPreview?: boolean; // Show image preview for accepted files
+  showProgress?: boolean; // Show upload progress bar
+  onUploadSuccess?: (result: FileUploadResult) => void;
+  onUploadError?: (error: string, file?: File) => void;
+  onProgress?: (progress: UploadProgress) => void;
   children?: React.ReactNode;
 }
 ```
@@ -135,11 +148,13 @@ interface FileUploadProps {
 ```tsx
 <FileUpload
   supabase={supabase}
-  appName="my-app"
-  orgId={organisationId}
-  onUploadComplete={(fileRef) => console.log('Uploaded:', fileRef)}
+  table_name="person"
+  record_id="person-123"
+  organisation_id={organisationId}
+  category={FileCategory.PROFILE_PHOTOS}
   accept="image/*"
   maxSize={2 * 1024 * 1024} // 2MB
+  onUploadSuccess={(result) => console.log('Uploaded:', result.file_reference)}
 >
   <Button>Upload Image</Button>
 </FileUpload>
@@ -149,11 +164,14 @@ interface FileUploadProps {
 ```tsx
 <FileUpload
   supabase={supabase}
-  appName="my-app"
-  orgId={organisationId}
+  table_name="person"
+  record_id="person-123"
+  organisation_id={organisationId}
+  category={FileCategory.GENERAL_DOCUMENTS}
   multiple={true}
   accept=".pdf,.doc,.docx"
-  onUploadComplete={(fileRef) => addToFileList(fileRef)}
+  showProgress={true}
+  onUploadSuccess={(result) => addToFileList(result.file_reference)}
 >
   <div className="upload-area">
     <UploadIcon className="w-8 h-8" />
@@ -188,17 +206,14 @@ A component for displaying and managing files associated with database records.
 ```typescript
 interface FileDisplayProps {
   supabase: SupabaseClient;
-  appName: string;
-  orgId: string;
-  recordType: string;
-  recordId: string;
+  table_name: string;
+  record_id: string;
+  organisation_id: string;
   category?: FileCategory;
-  onUpload?: (file: File) => Promise<FileReference>;
-  onDelete?: (fileRef: FileReference) => Promise<void>;
   showUpload?: boolean;
   showDelete?: boolean;
-  showPreview?: boolean;
   className?: string;
+  children?: React.ReactNode;
 }
 ```
 
@@ -208,11 +223,10 @@ interface FileDisplayProps {
 ```tsx
 <FileDisplay
   supabase={supabase}
-  appName="my-app"
-  orgId={organisationId}
-  recordType="pace_person"
-  recordId={personId}
-  category={FileCategory.DOCUMENT}
+  table_name="pace_person"
+  record_id={personId}
+  organisation_id={organisationId}
+  category={FileCategory.GENERAL_DOCUMENTS}
   showUpload={false}
   showDelete={false}
 />
@@ -222,17 +236,25 @@ interface FileDisplayProps {
 ```tsx
 <FileDisplay
   supabase={supabase}
-  appName="my-app"
-  orgId={organisationId}
-  recordType="pace_person"
-  recordId={personId}
-  category={FileCategory.IMAGE}
-  onUpload={handleUpload}
-  onDelete={handleDelete}
+  table_name="pace_person"
+  record_id={personId}
+  organisation_id={organisationId}
+  category={FileCategory.IMAGES}
   showUpload={true}
   showDelete={true}
-  showPreview={true}
-/>
+  className="space-y-4"
+>
+  {/* Optional: Custom upload component */}
+  <FileUpload
+    supabase={supabase}
+    table_name="pace_person"
+    record_id={personId}
+    organisation_id={organisationId}
+    category={FileCategory.IMAGES}
+    accept="image/*"
+    showPreview={true}
+  />
+</FileDisplay>
 ```
 
 ## Hooks
@@ -359,14 +381,24 @@ PACE Core supports predefined file categories for better organization:
 
 ```typescript
 enum FileCategory {
-  DOCUMENT = 'document',
-  IMAGE = 'image',
+  PROFILE_PHOTOS = 'profile_photos',
+  ID_DOCUMENTS = 'id_documents',
+  QUALIFICATIONS = 'qualifications',
+  MEDICAL_DOCUMENTS = 'medical_documents',
+  DISH_IMAGES = 'dish_images',
+  EVENT_LOGOS = 'event_logos',
+  GENERAL_DOCUMENTS = 'general_documents',
+  IMAGES = 'images',
   AUDIO = 'audio',
   VIDEO = 'video',
-  ARCHIVE = 'archive',
-  SPREADSHEET = 'spreadsheet',
-  PRESENTATION = 'presentation',
-  OTHER = 'other'
+  ARCHIVES = 'archives',
+  // CAKE-specific categories
+  CAKE_DISH = 'cake_dish',
+  // TRAC-specific categories
+  TRAC_ACCOMMODATION = 'trac_accommodation',
+  TRAC_ACTIVITY = 'trac_activity',
+  TRAC_JOURNAL = 'trac_journal',
+  TRAC_TRANSPORT = 'trac_transport'
 }
 ```
 
@@ -377,17 +409,23 @@ import { FileCategory } from '@jmruthers/pace-core';
 
 // Upload a document
 await uploadFile({
-  file: pdfFile,
-  category: FileCategory.DOCUMENT,
-  description: 'Contract document'
-});
-
-// Upload an image
+  table_name: 'person',
+  record_id: 'person-123',
+  organisation_id: 'org-123',
+  app_id: 'app-123',
+  category: FileCategory.GENERAL_DOCUMENTS,
+  is_public: false
+}, pdfFile);
+
+// Upload a profile photo
 await uploadFile({
-  file: imageFile,
-  category: FileCategory.IMAGE,
-  description: 'Profile photo'
-});
+  table_name: 'person',
+  record_id: 'person-123',
+  organisation_id: 'org-123',
+  app_id: 'app-123',
+  category: FileCategory.PROFILE_PHOTOS,
+  is_public: false
+}, imageFile);
 ```
 
 ## Database Schema
@@ -536,6 +574,32 @@ function FileUpload() {
 }
 ```
 
+## Recent Improvements
+
+### Performance & Memory Management
+- **Fixed infinite logging loops**: Removed debug logging that was causing performance issues in event services
+- **Memory leak prevention**: Added automatic cleanup in hooks and components to prevent memory accumulation
+- **Cache management**: Implemented cache size limits and TTL for event logos with automatic cleanup
+- **Optimized re-renders**: Fixed infinite re-render loops in FileDisplay component using refs for state tracking
+
+### Enhanced User Experience  
+- **App ID auto-resolution**: FileUpload component now automatically resolves app_id from app name configuration
+- **Better error handling**: More descriptive error messages and graceful failure handling with user-friendly toasts
+- **Progress tracking**: Enhanced upload progress with visual feedback and file previews
+- **Event context integration**: Event logos now automatically sync with selected events from the event selector
+
+### Security & Reliability
+- **RLS policy fixes**: Resolved permission issues for file uploads with proper organisation context setting
+- **Organisation context**: Proper database session context setting via `app.current_organisation_id`
+- **Super admin support**: Enhanced permissions for administrative users with dedicated RLS policies
+- **Bucket validation**: Improved bucket selection and validation logic for public vs private files
+
+### Developer Experience
+- **Comprehensive documentation**: Updated all documentation to reflect current API and best practices
+- **Better TypeScript support**: Improved type definitions and interfaces
+- **Enhanced debugging**: Better error messages and debugging tools for troubleshooting
+- **Legacy system removal**: Completely removed legacy file upload system to eliminate tech debt
+
 ## Migration from Old File Columns
 
 If you're migrating from direct file columns to the file reference system:

package/docs/rbac/super-admin-guide.md

@@ -396,33 +396,9 @@ function MyComponent() {
 }
 ```
 
-### Using SuperAdminGuard Component
+### Super Admin UI Considerations
 
-```tsx
-import { SuperAdminGuard, SuperAdminBadge } from '@jmruthers/pace-core/components';
-
-function AdminDashboard() {
-  return (
-    <div>
-      <header>
-        <h1>Admin Dashboard</h1>
-        <SuperAdminBadge />
-      </header>
-      
-      <SuperAdminGuard
-        fallback={<div>You need super admin access to view this content</div>}
-      >
-        <div className="super-admin-content">
-          <h2>Super Admin Tools</h2>
-          <button>Manage All Organisations</button>
-          <button>View System Logs</button>
-          <button>Access All User Data</button>
-        </div>
-      </SuperAdminGuard>
-    </div>
-  );
-}
-```
+Prefer enforcing super-admin-only behavior using RBAC hooks (e.g., `useRBAC`) and server-side policies. Avoid bespoke guard components.
 
 ### Data Table with Super Admin Access
 
@@ -493,11 +469,7 @@ import {
   PermissionEnforcer, 
   PagePermissionGuard 
 } from '@jmruthers/pace-core/rbac';
-import { 
-  SuperAdminGuard, 
-  SuperAdminBadge, 
-  SuperAdminDebugPanel 
-} from '@jmruthers/pace-core/components';
+// (Super admin UI helpers previously documented have been removed.)
 
 function AdminLayout({ children }) {
   const { isSuperAdmin } = useRBAC();
@@ -515,11 +487,14 @@ function AdminLayout({ children }) {
           <li><Link to="/admin/users">Users</Link></li>
           <li><Link to="/admin/events">Events</Link></li>
           
-          <SuperAdminGuard>
-            <li><Link to="/admin/super-admin">Super Admin</Link></li>
-            <li><Link to="/admin/system-logs">System Logs</Link></li>
-            <li><Link to="/admin/all-organisations">All Organisations</Link></li>
-          </SuperAdminGuard>
+          {/* Gate links using app logic based on isSuperAdmin instead of a guard component */}
+          {isSuperAdmin && (
+            <>
+              <li><Link to="/admin/super-admin">Super Admin</Link></li>
+              <li><Link to="/admin/system-logs">System Logs</Link></li>
+              <li><Link to="/admin/all-organisations">All Organisations</Link></li>
+            </>
+          )}
         </ul>
       </nav>
       
@@ -528,8 +503,9 @@ function AdminLayout({ children }) {
       </main>
       
       <footer className="admin-footer">
+        {/* Optional: inline debug in development */}
         {process.env.NODE_ENV === 'development' && (
-          <SuperAdminDebugPanel />
+          <div>Debug: {String(isSuperAdmin)}</div>
         )}
       </footer>
     </div>
@@ -542,46 +518,18 @@ function AdminLayout({ children }) {
 ```tsx
 import { render, screen } from '@testing-library/react';
 import { useRBAC } from '@jmruthers/pace-core';
-import { SuperAdminGuard } from '@jmruthers/pace-core/components';
+// SuperAdminGuard removed; use conditional rendering in tests
 
 // Mock the hook
 jest.mock('@jmruthers/pace-core/rbac', () => ({
   useRBAC: jest.fn()
 }));
 
-describe('SuperAdminGuard', () => {
-  test('renders children for super admin users', () => {
-    (useRBAC as jest.Mock).mockReturnValue({
-      isSuperAdmin: true,
-      hasGlobalPermission: jest.fn().mockReturnValue(true),
-      isLoading: false
-    });
-
-    render(
-      <SuperAdminGuard fallback={<div>Access Denied</div>}>
-        <div>Super Admin Content</div>
-      </SuperAdminGuard>
-    );
-    
+describe('Super Admin conditional rendering', () => {
+  test('renders content for super admin users', () => {
+    (useRBAC as jest.Mock).mockReturnValue({ isSuperAdmin: true });
+    render(<div>{true && <div>Super Admin Content</div>}</div>);
     expect(screen.getByText('Super Admin Content')).toBeInTheDocument();
-    expect(screen.queryByText('Access Denied')).not.toBeInTheDocument();
-  });
-
-  test('renders fallback for non-super admin users', () => {
-    (useRBAC as jest.Mock).mockReturnValue({
-      isSuperAdmin: false,
-      hasGlobalPermission: jest.fn().mockReturnValue(false),
-      isLoading: false
-    });
-
-    render(
-      <SuperAdminGuard fallback={<div>Access Denied</div>}>
-        <div>Super Admin Content</div>
-      </SuperAdminGuard>
-    );
-    
-    expect(screen.getByText('Access Denied')).toBeInTheDocument();
-    expect(screen.queryByText('Super Admin Content')).not.toBeInTheDocument();
   });
 });
 ```

package/docs/testing/README.md

@@ -8,6 +8,8 @@ reviewedBy: content-audit
 
 This guide covers testing strategies, patterns, and best practices for applications built with PACE Core.
 
+> 📖 **For comprehensive testing standards and patterns**, see the [Testing Standard](../../src/__tests__/TEST_STANDARD.md) - the authoritative guide for writing world-class tests in pace-core.
+
 ## Overview
 
 PACE Core provides comprehensive testing support with:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.87",
+  "version": "0.5.88",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {