@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/{hooks/__tests__ → components/FileDisplay}/useFileDisplay.unit.test.ts

@@ -1,7 +1,7 @@
 /**
  * @file useFileDisplay Hook Unit Tests
  * @package @jmruthers/pace-core
- * @module Hooks/__tests__
+ * @module Hooks
  * @since 0.1.0
  *
  * Comprehensive tests for the useFileDisplay hook following TEST_STANDARD.md.
@@ -15,16 +15,16 @@ import {
   clearFileDisplayCache,
   getFileDisplayCacheStats,
   invalidateFileDisplayCache
-} from '../useFileDisplay';
+} from './useFileDisplay';
 import { createMockSupabaseClient } from '../../__tests__/helpers/supabaseMock';
 import type { SupabaseClient } from '@supabase/supabase-js';
 import type { Database } from '../../types/database';
 import { FileCategory as FileCategoryEnum } from '../../types/file-reference';
 
-// Mock storage helpers
+// Mock storage helpers - paths relative to src/hooks/
 vi.mock('../../utils/storage/helpers', () => ({
   getPublicUrl: vi.fn((supabase: any, path: string) => `https://example.com/${path}`),
-  getSignedUrl: vi.fn().mockResolvedValue({ url: 'https://example.com/signed-file.jpg', expiresAt: new Date().toISOString() }),
+  getSignedUrl: vi.fn().mockResolvedValue({ ok: true, data: { url: 'https://example.com/signed-file.jpg', expiresAt: new Date().toISOString() } }),
   generateFileUrlsBatch: vi.fn().mockImplementation(async (supabase, files) => {
     const urlMap = new Map<string, string>();
     for (const file of files) {
@@ -34,11 +34,11 @@ vi.mock('../../utils/storage/helpers', () => ({
         urlMap.set(file.id, `https://example.com/signed/${file.file_path}`);
       }
     }
-    return urlMap;
+    return { ok: true as const, data: urlMap };
   })
 }));
 
-// Mock file reference service
+// Mock file reference service (kept for any legacy references)
 const mockService = {
   getFilesByCategory: vi.fn(),
   listFileReferences: vi.fn()
@@ -48,8 +48,12 @@ vi.mock('../../utils/file-reference', () => ({
   createFileReferenceService: vi.fn(() => mockService)
 }));
 
+const mockFetchFileDisplayData = vi.fn();
+vi.mock('./fetchFileDisplayData', () => ({
+  fetchFileDisplayData: (params: unknown) => mockFetchFileDisplayData(params),
+}));
+
 import { getSignedUrl, generateFileUrlsBatch } from '../../utils/storage/helpers';
-import { createFileReferenceService } from '../../utils/file-reference';
 
 describe('useFileDisplay Hook', () => {
   let mockSupabase: SupabaseClient<Database>;
@@ -95,8 +99,7 @@ describe('useFileDisplay Hook', () => {
     vi.clearAllMocks();
     clearFileDisplayCache();
     mockSupabase = createMockSupabaseClient() as any;
-    mockService.getFilesByCategory.mockResolvedValue([]);
-    mockService.listFileReferences.mockResolvedValue([]);
+    mockFetchFileDisplayData.mockResolvedValue([]);
     
     // Reset generateFileUrlsBatch mock to ensure it returns a Map
     vi.mocked(generateFileUrlsBatch).mockImplementation(async (supabase, files) => {
@@ -108,7 +111,7 @@ describe('useFileDisplay Hook', () => {
           urlMap.set(file.id, `https://example.com/signed/${file.file_path}`);
         }
       }
-      return urlMap;
+      return { ok: true, data: urlMap };
     });
   });
 
@@ -122,8 +125,8 @@ describe('useFileDisplay Hook', () => {
     // Reset getSignedUrl mock to prevent interference with other test files
     vi.mocked(getSignedUrl).mockReset();
     vi.mocked(getSignedUrl).mockResolvedValue({ 
-      url: 'https://example.com/signed-file.jpg', 
-      expiresAt: new Date().toISOString() 
+      ok: true,
+      data: { url: 'https://example.com/signed-file.jpg', expiresAt: new Date().toISOString() }
     });
   });
 
@@ -145,7 +148,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('initializes with loading state when parameters are provided', () => {
-      mockService.getFilesByCategory.mockImplementation(() => new Promise(() => {})); // Never resolves
+      mockFetchFileDisplayData.mockImplementation(() => new Promise(() => {})); // Never resolves
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -173,7 +176,7 @@ describe('useFileDisplay Hook', () => {
 
   describe('Single File Mode (with category)', () => {
     it('fetches single file by category successfully with public file', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -193,16 +196,19 @@ describe('useFileDisplay Hook', () => {
       expect(result.current.fileUrl).toBe('https://example.com/org-123/logos/logo.png');
       expect(result.current.fileCount).toBe(1);
       expect(result.current.error).toBe(null);
-      expect(mockService.getFilesByCategory).toHaveBeenCalledWith(
-        'event',
-        'event-123',
-        FileCategoryEnum.EVENT_LOGOS,
-        'org-123'
+      expect(mockFetchFileDisplayData).toHaveBeenCalledWith(
+        expect.objectContaining({
+          table_name: 'event',
+          record_id: 'event-123',
+          organisation_id: 'org-123',
+          category: FileCategoryEnum.EVENT_LOGOS,
+        })
       );
     });
 
     it('fetches single file by category successfully with private file and signed URL', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockPrivateFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockPrivateFileReference]);
+      vi.mocked(getSignedUrl).mockResolvedValue({ ok: true, data: { url: 'https://example.com/signed-file.jpg', expiresAt: new Date().toISOString() } });
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -224,7 +230,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('handles no files found for category', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -247,7 +253,7 @@ describe('useFileDisplay Hook', () => {
 
     it('handles errors in single file mode', async () => {
       const error = new Error('Database error');
-      mockService.getFilesByCategory.mockRejectedValue(error);
+      mockFetchFileDisplayData.mockRejectedValue(error);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -270,7 +276,8 @@ describe('useFileDisplay Hook', () => {
 
     it('regenerates signed URL from cache for private files', async () => {
       // First, fetch and cache a private file
-      mockService.getFilesByCategory.mockResolvedValue([mockPrivateFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockPrivateFileReference]);
+      vi.mocked(getSignedUrl).mockResolvedValue({ ok: true, data: { url: 'https://example.com/signed-file.jpg', expiresAt: new Date().toISOString() } });
       
       const { result: firstResult } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -287,7 +294,7 @@ describe('useFileDisplay Hook', () => {
       );
 
       // Clear the mock to simulate cache hit
-      mockService.getFilesByCategory.mockClear();
+      mockFetchFileDisplayData.mockClear();
       (getSignedUrl as any).mockClear();
 
       // Second render with same parameters - should use cache
@@ -307,7 +314,7 @@ describe('useFileDisplay Hook', () => {
 
       // Should regenerate signed URL from cache
       expect(getSignedUrl).toHaveBeenCalled();
-      expect(mockService.getFilesByCategory).not.toHaveBeenCalled();
+      expect(mockFetchFileDisplayData).not.toHaveBeenCalled();
     });
   });
 
@@ -317,7 +324,7 @@ describe('useFileDisplay Hook', () => {
         mockFileReference,
         { ...mockFileReference, id: 'file-789', file_path: 'org-123/logos/logo2.png' }
       ];
-      mockService.listFileReferences.mockResolvedValue(files);
+      mockFetchFileDisplayData.mockResolvedValue(files);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', undefined, {
@@ -341,7 +348,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('handles no files found in multiple file mode', async () => {
-      mockService.listFileReferences.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', undefined, {
@@ -364,7 +371,7 @@ describe('useFileDisplay Hook', () => {
 
     it('handles errors in multiple file mode', async () => {
       const error = new Error('Failed to fetch file references');
-      mockService.listFileReferences.mockRejectedValue(error);
+      mockFetchFileDisplayData.mockRejectedValue(error);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', undefined, {
@@ -387,7 +394,7 @@ describe('useFileDisplay Hook', () => {
 
   describe('Caching', () => {
     it('caches file data and returns from cache on subsequent calls', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result, rerender } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -404,7 +411,7 @@ describe('useFileDisplay Hook', () => {
         { timeout: 2000 }
       );
 
-      const firstCallCount = mockService.getFilesByCategory.mock.calls.length;
+      const firstCallCount = mockFetchFileDisplayData.mock.calls.length;
 
       // Rerender with same parameters - should use cache
       rerender();
@@ -417,11 +424,11 @@ describe('useFileDisplay Hook', () => {
       );
 
       // Should not make another service call
-      expect(mockService.getFilesByCategory.mock.calls.length).toBe(firstCallCount);
+      expect(mockFetchFileDisplayData.mock.calls.length).toBe(firstCallCount);
     });
 
     it('respects cache TTL option', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -442,7 +449,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('disables caching when enableCache is false', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result, rerender } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -476,7 +483,7 @@ describe('useFileDisplay Hook', () => {
     it('performs cache cleanup on size limit exceeded', async () => {
       // Fill cache beyond MAX_CACHE_SIZE (100)
       for (let i = 0; i < 101; i++) {
-        mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+        mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
         
         renderHook(() =>
           useFileDisplay('event', `event-${i}`, 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -498,7 +505,7 @@ describe('useFileDisplay Hook', () => {
 
   describe('Cache Management Utilities', () => {
     it('clearFileDisplayCache clears all cached data', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -523,7 +530,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('getFileDisplayCacheStats returns correct statistics', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -547,7 +554,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('invalidateFileDisplayCache invalidates specific entries', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -574,8 +581,8 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('invalidateFileDisplayCache also invalidates all category when specific category invalidated', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
-      mockService.listFileReferences.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       // Create cache entries for both category and all
       renderHook(() =>
@@ -614,7 +621,7 @@ describe('useFileDisplay Hook', () => {
 
   describe('Refetch Functionality', () => {
     it('refetches data when refetch is called', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -630,11 +637,11 @@ describe('useFileDisplay Hook', () => {
         { timeout: 2000 }
       );
 
-      const firstCallCount = mockService.getFilesByCategory.mock.calls.length;
+      const firstCallCount = mockFetchFileDisplayData.mock.calls.length;
 
       // Update mock to return different data
       const newFile = { ...mockFileReference, id: 'file-999', file_path: 'org-123/logos/new-logo.png' };
-      mockService.getFilesByCategory.mockResolvedValue([newFile]);
+      mockFetchFileDisplayData.mockResolvedValue([newFile]);
 
       await result.current.refetch();
 
@@ -646,11 +653,11 @@ describe('useFileDisplay Hook', () => {
       );
 
       // Should have made another call
-      expect(mockService.getFilesByCategory.mock.calls.length).toBeGreaterThan(firstCallCount);
+      expect(mockFetchFileDisplayData.mock.calls.length).toBeGreaterThan(firstCallCount);
     });
 
     it('clears cache before refetching', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -682,7 +689,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('handles refetch errors gracefully', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -698,7 +705,7 @@ describe('useFileDisplay Hook', () => {
       );
 
       const error = new Error('Refetch failed');
-      mockService.getFilesByCategory.mockRejectedValue(error);
+      mockFetchFileDisplayData.mockRejectedValue(error);
 
       await result.current.refetch();
 
@@ -716,7 +723,7 @@ describe('useFileDisplay Hook', () => {
   describe('Error Handling', () => {
     it('handles exceptions during file fetch', async () => {
       const error = new Error('Network timeout');
-      mockService.getFilesByCategory.mockRejectedValue(error);
+      mockFetchFileDisplayData.mockRejectedValue(error);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -738,7 +745,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('handles non-Error exceptions', async () => {
-      mockService.getFilesByCategory.mockRejectedValue('String error');
+      mockFetchFileDisplayData.mockRejectedValue('String error');
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -760,7 +767,7 @@ describe('useFileDisplay Hook', () => {
     it('validates UUID format for organisation_id', async () => {
       const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
-      mockService.getFilesByCategory.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       renderHook(() =>
         useFileDisplay('event', 'event-123', 'invalid-uuid', FileCategoryEnum.EVENT_LOGOS, {
@@ -782,7 +789,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('handles signed URL generation failures', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockPrivateFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockPrivateFileReference]);
       (getSignedUrl as any).mockRejectedValue(new Error('Signed URL generation failed'));
 
       const { result } = renderHook(() =>
@@ -805,7 +812,7 @@ describe('useFileDisplay Hook', () => {
 
   describe('Parameter Changes', () => {
     it('refetches when table_name changes', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       const { result, rerender } = renderHook(
         ({ tableName }) =>
@@ -824,7 +831,7 @@ describe('useFileDisplay Hook', () => {
         { timeout: 2000 }
       );
 
-      const firstCallCount = mockService.getFilesByCategory.mock.calls.length;
+      const firstCallCount = mockFetchFileDisplayData.mock.calls.length;
 
       rerender({ tableName: 'organisation' });
 
@@ -836,17 +843,19 @@ describe('useFileDisplay Hook', () => {
       );
 
       // Should make another call with new table name
-      expect(mockService.getFilesByCategory.mock.calls.length).toBeGreaterThan(firstCallCount);
-      expect(mockService.getFilesByCategory).toHaveBeenCalledWith(
-        'organisation',
-        'event-123',
-        FileCategoryEnum.EVENT_LOGOS,
-        'org-123'
+      expect(mockFetchFileDisplayData.mock.calls.length).toBeGreaterThan(firstCallCount);
+      expect(mockFetchFileDisplayData).toHaveBeenCalledWith(
+        expect.objectContaining({
+          table_name: 'organisation',
+          record_id: 'event-123',
+          organisation_id: 'org-123',
+          category: FileCategoryEnum.EVENT_LOGOS,
+        })
       );
     });
 
     it('refetches when record_id changes', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       const { result, rerender } = renderHook(
         ({ recordId }) =>
@@ -875,11 +884,11 @@ describe('useFileDisplay Hook', () => {
       );
 
       // Should have refetched with new record ID
-      expect(mockService.getFilesByCategory.mock.calls.length).toBeGreaterThan(1);
+      expect(mockFetchFileDisplayData.mock.calls.length).toBeGreaterThan(1);
     });
 
     it('refetches when category changes', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       const { result, rerender } = renderHook(
         ({ category }) =>
@@ -899,7 +908,7 @@ describe('useFileDisplay Hook', () => {
         { timeout: 2000 }
       );
 
-      const firstCallCount = mockService.getFilesByCategory.mock.calls.length;
+      const firstCallCount = mockFetchFileDisplayData.mock.calls.length;
       expect(firstCallCount).toBeGreaterThan(0); // Ensure initial call happened
 
       // Change category - this should trigger a refetch
@@ -914,11 +923,11 @@ describe('useFileDisplay Hook', () => {
 
       // Should have refetched with new category
       // The hook may batch calls or React may optimize, so we check it was called at least once more
-      expect(mockService.getFilesByCategory.mock.calls.length).toBeGreaterThanOrEqual(firstCallCount);
+      expect(mockFetchFileDisplayData.mock.calls.length).toBeGreaterThanOrEqual(firstCallCount);
     });
 
     it('refetches when organisation_id changes', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       const { result, rerender } = renderHook(
         ({ orgId }) =>
@@ -947,11 +956,11 @@ describe('useFileDisplay Hook', () => {
       );
 
       // Should have refetched with new organisation ID
-      expect(mockService.getFilesByCategory.mock.calls.length).toBeGreaterThan(1);
+      expect(mockFetchFileDisplayData.mock.calls.length).toBeGreaterThan(1);
     });
 
     it('handles supabase client changes', async () => {
-      mockService.getFilesByCategory.mockResolvedValue([mockFileReference]);
+      mockFetchFileDisplayData.mockResolvedValue([mockFileReference]);
 
       const { result, rerender } = renderHook(
         ({ supabase }) =>
@@ -980,9 +989,10 @@ describe('useFileDisplay Hook', () => {
         { timeout: 2000 }
       );
 
-      // Should have refetched with new client
-      // The service is created when the hook initializes, so it should be called
-      expect(createFileReferenceService).toHaveBeenCalled();
+      // Hook uses fetchFileDisplayData; when supabase prop changes, effect may re-run depending on ref identity.
+      // At minimum, fetch was called on initial mount.
+      expect(mockFetchFileDisplayData).toHaveBeenCalled();
+      expect(result.current.fileReference).not.toBeNull();
     });
   });
 
@@ -992,7 +1002,7 @@ describe('useFileDisplay Hook', () => {
         ...mockFileReference,
         file_metadata: null
       };
-      mockService.getFilesByCategory.mockResolvedValue([fileWithoutMetadata]);
+      mockFetchFileDisplayData.mockResolvedValue([fileWithoutMetadata]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -1016,7 +1026,7 @@ describe('useFileDisplay Hook', () => {
         ...mockFileReference,
         file_path: null
       };
-      mockService.getFilesByCategory.mockResolvedValue([fileWithoutPath]);
+      mockFetchFileDisplayData.mockResolvedValue([fileWithoutPath]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
@@ -1049,7 +1059,7 @@ describe('useFileDisplay Hook', () => {
     });
 
     it('handles null category parameter for multiple file mode', async () => {
-      mockService.listFileReferences.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'org-123', null, {
@@ -1065,17 +1075,19 @@ describe('useFileDisplay Hook', () => {
       );
 
       // Should use multiple file mode
-      expect(mockService.listFileReferences).toHaveBeenCalledWith(
-        'event',
-        'event-123',
-        'org-123'
+      expect(mockFetchFileDisplayData).toHaveBeenCalledWith(
+        expect.objectContaining({
+          table_name: 'event',
+          record_id: 'event-123',
+          organisation_id: 'org-123',
+        })
       );
     });
 
     it('handles invalid organisation ID format gracefully', async () => {
       const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
-      mockService.getFilesByCategory.mockResolvedValue([]);
+      mockFetchFileDisplayData.mockResolvedValue([]);
 
       const { result } = renderHook(() =>
         useFileDisplay('event', 'event-123', 'not-a-uuid', FileCategoryEnum.EVENT_LOGOS, {
@@ -1105,5 +1117,322 @@ describe('useFileDisplay Hook', () => {
       consoleWarnSpy.mockRestore();
     });
   });
+
+  describe('Dual-Scope Search (organisation_id undefined)', () => {
+    it('searches both user-scoped and organisation-scoped files when organisation_id is undefined', async () => {
+      const userScopedFile = {
+        ...mockFileReference,
+        id: 'user-file-1',
+        organisation_id: null,
+      };
+
+      // Mock user-scoped query
+      mockFetchFileDisplayData.mockResolvedValueOnce([userScopedFile]);
+      
+      // Mock getUser to return a user
+      (mockSupabase.auth.getUser as any).mockResolvedValue({
+        data: { user: { id: 'user-123' } },
+        error: null,
+      });
+
+      // Mock organisation memberships query
+      const mockMembershipsQuery = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockResolvedValue({
+          data: [{ organisation_id: 'org-123' }],
+          error: null,
+        }),
+      };
+
+      // Mock organisation-scoped query
+      mockFetchFileDisplayData.mockResolvedValueOnce([mockFileReference]);
+
+      const mockFrom = vi.fn((table: string) => {
+        if (table === 'core_organisation_memberships') {
+          return mockMembershipsQuery;
+        }
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          order: vi.fn().mockReturnThis(),
+        };
+      });
+      (mockSupabase.from as any) = mockFrom;
+
+      const { result } = renderHook(() =>
+        useFileDisplay('event', 'event-123', undefined, FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Should have queried both scopes
+      expect(mockFetchFileDisplayData).toHaveBeenCalled();
+    });
+
+    it('handles user with no organisation memberships', async () => {
+      mockFetchFileDisplayData.mockResolvedValueOnce([mockFileReference]);
+
+      (mockSupabase.auth.getUser as any).mockResolvedValue({
+        data: { user: { id: 'user-123' } },
+        error: null,
+      });
+
+      // Mock memberships query to return empty
+      const mockMembershipsQuery = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockResolvedValue({
+          data: [],
+          error: null,
+        }),
+      };
+
+      // Mock the fallback query
+      const mockFallbackQuery = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        order: vi.fn().mockResolvedValue({
+          data: [],
+          error: null,
+        }),
+      };
+
+      const mockFrom = vi.fn((table: string) => {
+        if (table === 'core_organisation_memberships') {
+          return mockMembershipsQuery;
+        }
+        if (table === 'core_file_references') {
+          return mockFallbackQuery;
+        }
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+        };
+      });
+      (mockSupabase.from as any) = mockFrom;
+
+      const { result } = renderHook(() =>
+        useFileDisplay('event', 'event-123', undefined, FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.error).toBe(null);
+    });
+
+    it('handles errors when querying user-scoped files', async () => {
+      mockFetchFileDisplayData.mockRejectedValueOnce(new Error('User scope error'));
+
+      (mockSupabase.auth.getUser as any).mockResolvedValue({
+        data: { user: { id: 'user-123' } },
+        error: null,
+      });
+
+      const mockFrom = vi.fn().mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+      });
+      (mockSupabase.from as any) = mockFrom;
+
+      const { result } = renderHook(() =>
+        useFileDisplay('event', 'event-123', undefined, FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Hook sets error when fetchFileDisplayData rejects
+      expect(result.current.error).not.toBe(null);
+      expect(result.current.error?.message).toContain('User scope error');
+    });
+
+    it('handles errors when getting user', async () => {
+      mockFetchFileDisplayData.mockResolvedValueOnce([]);
+
+      (mockSupabase.auth.getUser as any).mockResolvedValue({
+        data: { user: null },
+        error: { message: 'User error' },
+      });
+
+      const mockFrom = vi.fn().mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+      });
+      (mockSupabase.from as any) = mockFrom;
+
+      const { result } = renderHook(() =>
+        useFileDisplay('event', 'event-123', undefined, FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Hook only calls fetchFileDisplayData; empty result yields no error
+      expect(result.current.error).toBe(null);
+      expect(result.current.fileReferences).toEqual([]);
+    });
+
+    it('handles fallback query when no files found through RPC', async () => {
+      mockFetchFileDisplayData.mockResolvedValueOnce([]);
+
+      (mockSupabase.auth.getUser as any).mockResolvedValue({
+        data: { user: { id: 'user-123' } },
+        error: null,
+      });
+
+      const mockMembershipsQuery = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockResolvedValue({
+          data: [],
+          error: null,
+        }),
+      };
+
+      // Mock fallback query to return files - need to chain properly
+      const _mockFallbackQuery = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        order: vi.fn().mockResolvedValue({
+          data: [{
+            id: 'fallback-file-1',
+            table_name: 'event',
+            record_id: 'event-123',
+            file_path: 'path/to/file.jpg',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            organisation_id: 'org-123',
+            app_id: 'app-123',
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z',
+            updated_at: '2024-01-01T00:00:00Z',
+          }],
+          error: null,
+        }),
+      };
+
+      // Create a proper chain for the fallback query
+      const createFallbackChain = () => {
+        const chain = {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+          order: vi.fn().mockResolvedValue({
+            data: [{
+              id: 'fallback-file-1',
+              table_name: 'event',
+              record_id: 'event-123',
+              file_path: 'path/to/file.jpg',
+              file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+              organisation_id: 'org-123',
+              app_id: 'app-123',
+              is_public: true,
+              created_at: '2024-01-01T00:00:00Z',
+              updated_at: '2024-01-01T00:00:00Z',
+            }],
+            error: null,
+          }),
+        };
+        return chain;
+      };
+
+      const mockFrom = vi.fn((table: string) => {
+        if (table === 'core_organisation_memberships') {
+          return mockMembershipsQuery;
+        }
+        if (table === 'core_file_references') {
+          return createFallbackChain();
+        }
+        return {
+          select: vi.fn().mockReturnThis(),
+          eq: vi.fn().mockReturnThis(),
+        };
+      });
+      (mockSupabase.from as any) = mockFrom;
+
+      const { result } = renderHook(() =>
+        useFileDisplay('event', 'event-123', undefined, FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // The fallback query may or may not find files depending on RLS
+      // This test verifies the hook handles the fallback path without errors
+      expect(result.current.error).toBe(null);
+      expect(Array.isArray(result.current.fileReferences)).toBe(true);
+    });
+
+    it('handles empty string organisation_id as explicit null', async () => {
+      mockFetchFileDisplayData.mockResolvedValueOnce([]);
+
+      // When organisation_id is empty string, should treat as null (not undefined)
+      const { result } = renderHook(() =>
+        useFileDisplay('event', 'event-123', '', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.error).toBe(null);
+    });
+  });
+
+  describe('Component Unmount Handling', () => {
+    it('does not update state after component unmounts', async () => {
+      mockFetchFileDisplayData.mockImplementation(() => 
+        new Promise((resolve) => setTimeout(() => resolve([mockFileReference]), 100))
+      );
+
+      const { result, unmount } = renderHook(() =>
+        useFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      // Unmount before promise resolves
+      unmount();
+
+      // Wait for promise to resolve
+      await new Promise(resolve => setTimeout(resolve, 150));
+
+      // State should not have been updated (no errors thrown)
+      expect(result.current.isLoading).toBeDefined();
+    });
+  });
 });