@jmruthers/pace-core 0.5.114 → 0.5.116

package/src/hooks/__tests__/usePublicFileDisplay.test.ts

@@ -0,0 +1,916 @@
+/**
+ * @file usePublicFileDisplay Hook Tests
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * Comprehensive tests for the usePublicFileDisplay hook following TEST_STANDARD.md.
+ * Tests focus on behavior: file fetching, caching, error handling, and loading states.
+ */
+
+import { renderHook, waitFor } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { 
+  usePublicFileDisplay, 
+  clearPublicFileDisplayCache, 
+  getPublicFileDisplayCacheStats 
+} from '../public/usePublicFileDisplay';
+import { createMockSupabaseClient } from '../../__tests__/helpers/supabaseMock';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
+import type { FileCategory } from '../../types/file-reference';
+import { FileCategory as FileCategoryEnum } from '../../types/file-reference';
+
+// Mock getPublicUrl
+vi.mock('../../utils/storage/helpers', () => ({
+  getPublicUrl: vi.fn((supabase: any, path: string) => `https://example.com/${path}`)
+}));
+
+import { getPublicUrl } from '../../utils/storage/helpers';
+
+describe('usePublicFileDisplay Hook', () => {
+  let mockSupabase: SupabaseClient<Database>;
+
+  const mockFileReference = {
+    id: 'file-123',
+    table_name: 'event',
+    record_id: 'event-123',
+    file_path: 'org-123/logos/logo.png',
+    file_metadata: {
+      category: FileCategoryEnum.EVENT_LOGOS,
+      app_id: 'app-123'
+    },
+    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'
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    clearPublicFileDisplayCache();
+    mockSupabase = createMockSupabaseClient() as any;
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    clearPublicFileDisplayCache();
+  });
+
+  describe('Initialization', () => {
+    it('initializes with correct default state when parameters are missing', () => {
+      const { result } = renderHook(() =>
+        usePublicFileDisplay(undefined, undefined, undefined, undefined, {
+          supabase: mockSupabase
+        })
+      );
+
+      expect(result.current.fileUrl).toBe(null);
+      expect(result.current.fileReference).toBe(null);
+      expect(result.current.fileReferences).toEqual([]);
+      expect(result.current.fileUrls).toEqual(new Map());
+      expect(result.current.fileCount).toBe(0);
+      expect(result.current.isLoading).toBe(false);
+      expect(result.current.error).toBe(null);
+    });
+
+    it('initializes with loading state when parameters are provided', () => {
+      (mockSupabase.rpc as any).mockImplementation(() => new Promise(() => {})); // Never resolves
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      expect(result.current.isLoading).toBe(true);
+      expect(result.current.fileUrl).toBe(null);
+      expect(result.current.error).toBe(null);
+    });
+  });
+
+  describe('Single File Mode (with category)', () => {
+    it('fetches single file by category successfully', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.fileReference).not.toBeNull();
+      expect(result.current.fileReference?.id).toBe('file-123');
+      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(mockSupabase.rpc).toHaveBeenCalledWith('data_file_reference_by_category_list', {
+        p_table_name: 'event',
+        p_record_id: 'event-123',
+        p_category: FileCategoryEnum.EVENT_LOGOS,
+        p_organisation_id: 'org-123'
+      });
+    });
+
+    it('handles no files found for category', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.fileUrl).toBe(null);
+      expect(result.current.fileReference).toBe(null);
+      expect(result.current.fileCount).toBe(0);
+      expect(result.current.error).toBe(null);
+    });
+
+    it('filters out non-public files in single file mode', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: false, // Non-public file
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Should filter out non-public files
+      expect(result.current.fileUrl).toBe(null);
+      expect(result.current.fileReference).toBe(null);
+      expect(result.current.fileCount).toBe(0);
+    });
+
+    it('handles RPC errors in single file mode', async () => {
+      const rpcError = { message: 'Database error', code: 'PGRST116' };
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: null,
+        error: rpcError
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.error).toBeInstanceOf(Error);
+      expect(result.current.error?.message).toBe('Database error');
+      expect(result.current.fileUrl).toBe(null);
+      expect(result.current.fileReference).toBe(null);
+    });
+  });
+
+  describe('Multiple Files Mode (without category)', () => {
+    it('fetches multiple files successfully', async () => {
+      const fileIds = ['file-123', 'file-456'];
+      (mockSupabase.rpc as any)
+        .mockResolvedValueOnce({
+          data: fileIds.map(id => ({ id })),
+          error: null
+        });
+
+      (mockSupabase.from as any).mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        in: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockResolvedValue({
+          data: [
+            { ...mockFileReference, id: 'file-123' },
+            { ...mockFileReference, id: 'file-456', file_path: 'org-123/logos/logo2.png' }
+          ],
+          error: null
+        })
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', undefined, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.fileCount).toBe(2);
+      expect(result.current.fileReferences.length).toBe(2);
+      expect(result.current.fileUrls.size).toBe(2);
+      expect(result.current.fileUrls.get('file-123')).toBe('https://example.com/org-123/logos/logo.png');
+      expect(result.current.fileUrls.get('file-456')).toBe('https://example.com/org-123/logos/logo2.png');
+      expect(result.current.fileUrl).toBe(null); // No single file URL in multiple mode
+      expect(result.current.fileReference).toBe(null); // No single file reference in multiple mode
+    });
+
+    it('handles no files found in multiple file mode', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', undefined, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.fileCount).toBe(0);
+      expect(result.current.fileReferences).toEqual([]);
+      expect(result.current.fileUrls.size).toBe(0);
+      expect(result.current.error).toBe(null);
+    });
+
+    it('filters out non-public files in multiple file mode', async () => {
+      const fileIds = ['file-123', 'file-456'];
+      (mockSupabase.rpc as any)
+        .mockResolvedValueOnce({
+          data: fileIds.map(id => ({ id })),
+          error: null
+        });
+
+      (mockSupabase.from as any).mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        in: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockResolvedValue({
+          data: [
+            { ...mockFileReference, id: 'file-123', is_public: true },
+            { ...mockFileReference, id: 'file-456', is_public: false } // Non-public
+          ],
+          error: null
+        })
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', undefined, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Should only include public files
+      expect(result.current.fileCount).toBe(1);
+      expect(result.current.fileReferences.length).toBe(1);
+      expect(result.current.fileReferences[0].id).toBe('file-123');
+    });
+
+    it('handles RPC errors in multiple file mode', async () => {
+      const rpcError = { message: 'Failed to fetch file references', code: 'PGRST116' };
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: null,
+        error: rpcError
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', undefined, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.error).toBeInstanceOf(Error);
+      expect(result.current.error?.message).toBe('Failed to fetch file references');
+      expect(result.current.fileCount).toBe(0);
+    });
+  });
+
+  describe('Caching', () => {
+    it('caches file data and returns from cache on subsequent calls', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result, rerender } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase,
+          enableCache: true,
+          cacheTtl: 30 * 60 * 1000 // 30 minutes
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      const firstCallCount = (mockSupabase.rpc as any).mock.calls.length;
+
+      // Rerender with same parameters - should use cache
+      rerender();
+
+      await waitFor(
+        () => {
+          expect(result.current.fileUrl).toBe('https://example.com/org-123/logos/logo.png');
+        },
+        { timeout: 1000 }
+      );
+
+      // Should not make another RPC call
+      expect((mockSupabase.rpc as any).mock.calls.length).toBe(firstCallCount);
+    });
+
+    it('respects cache TTL option', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase,
+          enableCache: true,
+          cacheTtl: 1000 // 1 second
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.fileUrl).toBe('https://example.com/org-123/logos/logo.png');
+    });
+
+    it('disables caching when enableCache is false', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result, rerender } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase,
+          enableCache: false
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      const firstCallCount = (mockSupabase.rpc as any).mock.calls.length;
+
+      // Rerender - should make another call since caching is disabled
+      rerender();
+
+      // The hook should refetch when dependencies change, but with caching disabled
+      // it will make a new call on each render
+      await waitFor(
+        () => {
+          expect(result.current.fileUrl).toBe('https://example.com/org-123/logos/logo.png');
+        },
+        { timeout: 2000 }
+      );
+    });
+  });
+
+  describe('Refetch Functionality', () => {
+    it('refetches data when refetch is called', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase,
+          enableCache: true
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      const firstCallCount = (mockSupabase.rpc as any).mock.calls.length;
+
+      // Update mock to return different data
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-456',
+            file_path: 'org-123/logos/new-logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      await result.current.refetch();
+
+      await waitFor(
+        () => {
+          expect(result.current.fileReference?.id).toBe('file-456');
+        },
+        { timeout: 2000 }
+      );
+
+      // Should have made another call
+      expect((mockSupabase.rpc as any).mock.calls.length).toBeGreaterThan(firstCallCount);
+    });
+
+    it('clears cache before refetching', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase,
+          enableCache: true
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Verify cache exists
+      const statsBefore = getPublicFileDisplayCacheStats();
+      expect(statsBefore.size).toBeGreaterThan(0);
+
+      await result.current.refetch();
+
+      // Cache should be cleared and then repopulated
+      await waitFor(
+        () => {
+          expect(result.current.fileUrl).toBeDefined();
+        },
+        { timeout: 2000 }
+      );
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('handles exceptions during file fetch', async () => {
+      const error = new Error('Network timeout');
+      (mockSupabase.rpc as any).mockRejectedValue(error);
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.error).toBeInstanceOf(Error);
+      expect(result.current.error?.message).toBe('Network timeout');
+      expect(result.current.fileUrl).toBe(null);
+      expect(result.current.fileReference).toBe(null);
+    });
+
+    it('handles non-Error exceptions', async () => {
+      (mockSupabase.rpc as any).mockRejectedValue('String error');
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(result.current.error).toBeInstanceOf(Error);
+      expect(result.current.error?.message).toBe('Unknown error occurred');
+    });
+
+    it('validates UUID format for organisation_id', async () => {
+      const consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'invalid-uuid', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        '[usePublicFileDisplay] Invalid organisationId format (not a valid UUID):',
+        'invalid-uuid'
+      );
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe('Parameter Changes', () => {
+    it('refetches when table_name changes', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
+
+      const { result, rerender } = renderHook(
+        ({ tableName }) =>
+          usePublicFileDisplay(tableName, 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+            supabase: mockSupabase
+          }),
+        {
+          initialProps: { tableName: 'event' }
+        }
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      const firstCallCount = (mockSupabase.rpc as any).mock.calls.length;
+
+      rerender({ tableName: 'organisation' });
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Should make another call with new table name
+      expect((mockSupabase.rpc as any).mock.calls.length).toBeGreaterThan(firstCallCount);
+      expect((mockSupabase.rpc as any).mock.calls[firstCallCount][0]).toBe('data_file_reference_by_category_list');
+      expect((mockSupabase.rpc as any).mock.calls[firstCallCount][1].p_table_name).toBe('organisation');
+    });
+
+    it('refetches when record_id changes', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
+
+      const { result, rerender } = renderHook(
+        ({ recordId }) =>
+          usePublicFileDisplay('event', recordId, 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+            supabase: mockSupabase
+          }),
+        {
+          initialProps: { recordId: 'event-123' }
+        }
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      rerender({ recordId: 'event-456' });
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Should have refetched with new record ID
+      expect((mockSupabase.rpc as any).mock.calls.length).toBeGreaterThan(1);
+    });
+
+    it('refetches when category changes', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
+
+      const { result, rerender } = renderHook(
+        ({ category }) =>
+          usePublicFileDisplay('event', 'event-123', 'org-123', category, {
+            supabase: mockSupabase
+          }),
+        {
+          initialProps: { category: FileCategoryEnum.EVENT_LOGOS }
+        }
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      rerender({ category: FileCategoryEnum.EVENT_DOCUMENTS });
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Should have refetched with new category
+      expect((mockSupabase.rpc as any).mock.calls.length).toBeGreaterThan(1);
+    });
+  });
+
+  describe('Cache Management Utilities', () => {
+    it('clears public file display cache', () => {
+      // Add some data to cache (by fetching files)
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase,
+          enableCache: true
+        })
+      );
+
+      // Wait for cache to be populated
+      waitFor(
+        () => {
+          expect(result.current.fileUrl).not.toBeNull();
+        },
+        { timeout: 2000 }
+      );
+
+      // Clear cache
+      clearPublicFileDisplayCache();
+
+      const stats = getPublicFileDisplayCacheStats();
+      expect(stats.size).toBe(0);
+      expect(stats.keys).toEqual([]);
+    });
+
+    it('gets cache statistics', () => {
+      const stats = getPublicFileDisplayCacheStats();
+      expect(stats).toEqual({
+        size: 0,
+        keys: []
+      });
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles missing file metadata gracefully', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: 'org-123/logos/logo.png',
+            file_metadata: null, // Missing metadata
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // The implementation filters out files without file_metadata when category is provided
+      // because it checks for file_metadata in the filter
+      // So we expect no file reference when metadata is missing
+      expect(result.current.fileReference).toBe(null);
+      expect(result.current.fileCount).toBe(0);
+    });
+
+    it('handles files without file_path', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [
+          {
+            id: 'file-123',
+            file_path: null, // Missing file path
+            file_metadata: { category: FileCategoryEnum.EVENT_LOGOS },
+            is_public: true,
+            created_at: '2024-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', FileCategoryEnum.EVENT_LOGOS, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Should filter out files without file_path
+      expect(result.current.fileReference).toBe(null);
+      expect(result.current.fileUrl).toBe(null);
+    });
+
+    it('handles empty string parameters', () => {
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('', '', '', undefined, {
+          supabase: mockSupabase
+        })
+      );
+
+      expect(result.current.isLoading).toBe(false);
+      expect(result.current.fileUrl).toBe(null);
+      expect(result.current.fileReference).toBe(null);
+      expect(result.current.fileCount).toBe(0);
+    });
+
+    it('handles null category parameter for multiple file mode', async () => {
+      (mockSupabase.rpc as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
+
+      const { result } = renderHook(() =>
+        usePublicFileDisplay('event', 'event-123', 'org-123', null, {
+          supabase: mockSupabase
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.isLoading).toBe(false);
+        },
+        { timeout: 2000 }
+      );
+
+      // Should use multiple file mode
+      expect(mockSupabase.rpc).toHaveBeenCalledWith('data_file_reference_list', expect.any(Object));
+    });
+  });
+});
+