@jmruthers/pace-core 0.5.101 → 0.5.103

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

@@ -1,6 +1,6 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
+lastUpdated: 2025-11-01T14:58:00+11:00
+version: 0.5.102
 reviewedBy: content-audit
 ---
 
@@ -30,7 +30,7 @@ CREATE TABLE file_references (
   table_name TEXT NOT NULL,           -- Source table (e.g., 'pace_person')
   record_id TEXT NOT NULL,            -- Source record ID
   file_path TEXT NOT NULL,            -- Storage path
-  file_metadata JSONB DEFAULT '{}',   -- File metadata
+  file_metadata JSONB DEFAULT '{}',   -- File metadata (includes category, fileName, fileType, etc.)
   organisation_id UUID NOT NULL,      -- For RLS
   app_id UUID NOT NULL,               -- Application context
   is_public BOOLEAN DEFAULT false,    -- Public vs private
@@ -39,6 +39,8 @@ CREATE TABLE file_references (
 );
 ```
 
+**Important:** The `category` is stored within the `file_metadata` JSONB field as `file_metadata->>'category'`, **not** as a direct column. Category filtering is performed via RPC functions (`data_file_reference_by_category_list`) that properly query the JSONB field. Direct queries filtering on a non-existent `category` column will fail.
+
 ### Storage Structure
 
 **Organisation-First Structure:**
@@ -222,7 +224,6 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
 import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
 
 <FileDisplay
-  supabase={supabase}
   table_name="pace_person"
   record_id={personId}
   organisation_id={orgId}
@@ -244,7 +245,6 @@ import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
 ```tsx
 // Display just the first image without category filtering or metadata
 <FileDisplay
-  supabase={supabase}
   table_name="event"
   record_id={eventId}
   organisation_id={orgId}
@@ -252,6 +252,59 @@ import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
 />
 // When displayOnly is true, shows first file (prefers images) in simplified format
 // without wrappers, borders, or metadata. Perfect for clean logo/image displays.
+// FileDisplay automatically detects context (public or authenticated) and uses the appropriate Supabase client.
+```
+
+**With Fallback Display:**
+```tsx
+// Show fallback UI when no file is available or image fails to load
+<FileDisplay
+  table_name="pace_person"
+  record_id={personId}
+  organisation_id={orgId}
+  category={FileCategory.PROFILE_PHOTOS}
+  displayOnly={true}
+  showFallback={true}
+  fallbackSize="lg"
+  generateFallbackText={(fileName) => {
+    // Custom fallback text generator - extracts initials from file name
+    if (!fileName) return 'FL';
+    return fileName.split(/[\s\-_]+/)
+      .map(word => word.charAt(0).toUpperCase())
+      .join('')
+      .substring(0, 3);
+  }}
+/>
+// When showFallback is true, displays a styled fallback box with initials or custom text
+// when no file is found, an error occurs, or an image fails to load.
+// FileDisplay automatically detects context (public or authenticated) and uses the appropriate Supabase client.
+```
+
+**Event Logo Example:**
+
+For displaying event logos, use `FileDisplay` directly with appropriate props:
+
+```tsx
+import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
+
+<FileDisplay
+  table_name="event"
+  record_id={event.id}
+  organisation_id={event.organisation_id}
+  category={FileCategory.EVENT_LOGOS}
+  displayOnly={true}
+  showFallback={true}
+  fallbackSize="lg"
+  generateFallbackText={(fileName) => {
+    // Custom fallback generator from event name
+    if (!event.event_name) return 'EV';
+    return event.event_name
+      .split(/[\s\-_]+/)
+      .map(word => word.charAt(0).toUpperCase())
+      .join('')
+      .substring(0, 3);
+  }}
+/>
 ```
 
 ### React Hooks
@@ -346,25 +399,33 @@ fileReferences.forEach(fileRef => {
 });
 ```
 
-#### useEventLogo Hook
+**Note:** Category filtering uses the RPC function `data_file_reference_by_category_list`, which filters on `file_metadata->>'category'` (the JSONB field), not a direct column. This hook automatically handles the filtering correctly.
 
-```tsx
-import { useEventLogo } from '@jmruthers/pace-core';
+#### Event Logo Display
 
-const { logoUrl, fallbackText, isLoading, error, refetch } = useEventLogo(
-  supabase,
-  eventId,
-  eventName,
-  organisationId,
-  {
-    validateImage: true,
-    enableCache: true,
-    cacheTtl: 30 * 60 * 1000 // 30 minutes
-  }
-);
+Event logos can be displayed using `FileDisplay` with category filtering:
 
-// Automatically handles both public and private event logos
-// Falls back to event initials if no logo is found
+```tsx
+import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
+
+// Display event logo with fallback
+<FileDisplay
+  table_name="event"
+  record_id={eventId}
+  organisation_id={organisationId}
+  category={FileCategory.EVENT_LOGOS}
+  displayOnly={true}
+  showFallback={true}
+  fallbackSize="lg"
+  generateFallbackText={(fileName) => {
+    if (!eventName) return 'EV';
+    return eventName
+      .split(/[\s\-_]+/)
+      .map(word => word.charAt(0).toUpperCase())
+      .join('')
+      .substring(0, 3);
+  }}
+/>
 ```
 
 #### useFileReferenceForRecord Hook
@@ -449,6 +510,8 @@ SELECT data_file_reference_get(
 );
 
 -- Get files by category
+-- NOTE: Category filtering uses the file_metadata JSONB field (file_metadata->>'category'),
+-- not a direct column. This RPC function properly filters on the JSONB field.
 SELECT data_file_reference_by_category_list(
   p_table_name := 'event',
   p_record_id := 'event-uuid',

package/package.json

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

package/src/components/DataTable/components/DataTableCore.tsx

@@ -1147,15 +1147,19 @@ function DataTableInternal<TData extends DataRecord>({
 
         {/* Table header */}
         <thead>
-          {table?.getHeaderGroups().map((headerGroup) => (
-            <tr key={headerGroup.id}>
-              {headerGroup.headers
-                .filter(header => {
-                  return typeof header.column.getIsVisible === 'function' 
-                    ? header.column.getIsVisible() 
-                    : true;
-                })
-                .map((header) => {
+          {table?.getHeaderGroups().map((headerGroup) => {
+            // Filter visible headers once to determine first and last
+            const visibleHeaders = headerGroup.headers.filter(header => {
+              return typeof header.column.getIsVisible === 'function' 
+                ? header.column.getIsVisible() 
+                : true;
+            });
+            
+            return (
+              <tr key={headerGroup.id}>
+                {visibleHeaders.map((header, index) => {
+                  const isFirst = index === 0;
+                  const isLast = index === visibleHeaders.length - 1;
                   const isSortable = header.column.getCanSort();
                   const ariaSort = isSortable
                     ? (header.column.getIsSorted() === 'asc'
@@ -1205,7 +1209,12 @@ function DataTableInternal<TData extends DataRecord>({
                   return (
                     <th
                       key={header.id}
-                      className={`px-3 py-2 ${isRightAligned ? 'text-right' : 'text-left'}`}
+                      className={cn(
+                        'px-3 py-2 bg-main-200',
+                        isRightAligned ? 'text-right' : 'text-left',
+                        isFirst && 'rounded-l-md',
+                        isLast && 'rounded-r-md'
+                      )}  
                       scope="col"
                       role="columnheader"
                       {...(isSortable ? { 'aria-sort': ariaSort } : {})}
@@ -1215,7 +1224,7 @@ function DataTableInternal<TData extends DataRecord>({
                         isSortable ? (
                           <Button
                             variant="ghost"
-                            className={`h-auto p-0 font-medium hover:bg-transparent ${isRightAligned ? 'justify-end' : 'justify-start'}`}
+                            className={`h-auto p-0 font-bold hover:bg-transparent ${isRightAligned ? 'justify-end' : 'justify-start'}`}
                             onClick={handleSortClick}
                             {...headerKeyboardHandlers}
                             aria-label={`Sort by ${typeof header.column.columnDef.header === 'string' ? header.column.columnDef.header : 'column'}`}
@@ -1241,8 +1250,9 @@ function DataTableInternal<TData extends DataRecord>({
                     </th>
                   );
                 })}
-            </tr>
-          ))}
+              </tr>
+            );
+          })}
         </thead>
 
         {/* Table body */}

package/src/components/DataTable/hooks/useTableColumns.ts

@@ -50,12 +50,42 @@ export function useTableColumns<TData extends DataRecord>({
 
   const enhancedColumns = useMemo(() => {
     // Create enhanced base columns
-    const baseColumns: ColumnDef<TData>[] = [...columns].map(column => ({
-      ...column,
-      enableSorting: features.sorting && (column.enableSorting !== false),
-      enableColumnFilter: features.filtering && (column.enableColumnFilter !== false),
-      enableGrouping: features.grouping && (column.enableGrouping !== false),
-    }));
+    const baseColumns: ColumnDef<TData>[] = [...columns].map(column => {
+      const baseColumn = {
+        ...column,
+        enableSorting: features.sorting && (column.enableSorting !== false),
+        enableColumnFilter: features.filtering && (column.enableColumnFilter !== false),
+        enableGrouping: features.grouping && (column.enableGrouping !== false),
+      };
+
+      // Automatically set right alignment for numeric columns
+      // Check if column is numeric by:
+      // 1. meta.type === 'number'
+      // 2. fieldType === 'number'
+      // 3. filterType === 'number'
+      // Exclude dates (fieldType === 'date' or meta.type === 'date')
+      const dataTableColumn = column as DataTableColumn<TData>;
+      const isNumericColumn = 
+        column.meta?.type === 'number' ||
+        dataTableColumn.fieldType === 'number' ||
+        dataTableColumn.filterType === 'number';
+      
+      const isDateColumn = 
+        column.meta?.type === 'date' ||
+        dataTableColumn.fieldType === 'date' ||
+        dataTableColumn.filterType === 'date';
+
+      // Set right alignment if numeric and not a date
+      if (isNumericColumn && !isDateColumn) {
+        baseColumn.meta = {
+          ...baseColumn.meta,
+          align: 'right',
+          type: 'number',
+        };
+      }
+
+      return baseColumn;
+    });
 
     // Create selection column if enabled
     const selectionColumn: ColumnDef<TData> | null = features.selection ? {

package/src/components/FileDisplay/FileDisplay.test.tsx

@@ -398,7 +398,7 @@ describe('[component] FileDisplay', () => {
       clearError: vi.fn(),
     });
 
-    // This test verifies that displayOnly logic in FileDisplayBackwardsCompat prefers images
+    // This test verifies that displayOnly logic prefers images
     // The component should select the image file over the PDF
     renderWithProviders(<FileDisplay {...baseProps} displayOnly />);