@jmruthers/pace-core 0.5.185 → 0.5.186

package/docs/api-reference/components.md

@@ -1829,37 +1829,51 @@ 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; // 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;
   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;
 }
 ```
 
+**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
 
 ```tsx
-import { FileUpload, FileCategory, logger } from '@jmruthers/pace-core';
+import { FileUpload, FileCategory } from '@jmruthers/pace-core';
 
 function MyFileUpload() {
-  const handleUpload = (fileRef: FileReference) => {
-    logger.debug('FileUpload', 'File uploaded:', { fileId: fileRef.id, fileName: fileRef.name });
-  };
-
   return (
     <FileUpload
       supabase={supabase}
-      appName="my-app"
-      orgId={organisationId}
-      onUploadComplete={handleUpload}
+      table_name="pace_person"
+      record_id={personId}
+      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);
+        console.log('URL:', result.file_url);
+      }}
     >
       <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>

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);
 

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

@@ -48,6 +48,7 @@ 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
@@ -103,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}
         />
@@ -127,7 +130,8 @@ 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;
@@ -144,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:**
@@ -154,6 +160,7 @@ 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
@@ -171,6 +178,7 @@ interface FileUploadProps {
   record_id="person-123"
   organisation_id={organisationId}
   category={FileCategory.GENERAL_DOCUMENTS}
+  folder="documents"
   pageContext="forms"
   multiple={true}
   accept=".pdf,.doc,.docx"

package/package.json

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