@jmruthers/pace-core 0.5.193 → 0.6.2

package/src/hooks/__tests__/useStorage.unit.test.ts

@@ -38,7 +38,7 @@ const mockSupabase = {
 const mockFile = new File(['test content'], 'test.txt', { type: 'text/plain' });
 
 describe('useStorage Hook', () => {
-  const defaultProps = {
+  const baseProps = {
     supabase: mockSupabase,
     appName: 'test-app',
     orgId: 'test-org',
@@ -46,7 +46,7 @@ describe('useStorage Hook', () => {
 
     describe('Initial State', () => {
     it('should initialize with correct default values', () => {
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       expect(result.current.isUploading).toBe(false);
       expect(result.current.uploadError).toBe(null);
@@ -58,7 +58,7 @@ describe('useStorage Hook', () => {
     });
 
     it('should provide all required functions', () => {
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       expect(typeof result.current.uploadFile).toBe('function');
       expect(typeof result.current.getPublicUrl).toBe('function');
@@ -106,7 +106,7 @@ describe('useStorage Hook', () => {
       vi.mocked(uploadFile).mockResolvedValue(mockUploadResult);
       vi.mocked(listFiles).mockResolvedValue(mockListResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let uploadResult: any;
       await act(async () => {
@@ -132,7 +132,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(uploadFile).mockResolvedValue(mockUploadResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let uploadResult: any;
       await act(async () => {
@@ -153,7 +153,7 @@ describe('useStorage Hook', () => {
       vi.mocked(uploadFile).mockResolvedValue(mockUploadResult);
       vi.mocked(listFiles).mockResolvedValue({ files: [], totalCount: 0, hasMore: false });
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       const customOptions = {
         isPublic: true,
@@ -179,7 +179,7 @@ describe('useStorage Hook', () => {
     it('should handle upload exception', async () => {
       vi.mocked(uploadFile).mockRejectedValue(new Error('Network error'));
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let uploadResult: any;
       await act(async () => {
@@ -197,7 +197,7 @@ describe('useStorage Hook', () => {
     it('should handle upload exception with non-Error object', async () => {
       vi.mocked(uploadFile).mockRejectedValue('String error');
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let uploadResult: any;
       await act(async () => {
@@ -217,7 +217,7 @@ describe('useStorage Hook', () => {
       const mockUrl = 'https://example.com/public/test-file.txt';
       vi.mocked(getPublicUrl).mockReturnValue(mockUrl);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       const url = result.current.getPublicUrl('test-org/public/test-file.txt');
 
@@ -229,7 +229,7 @@ describe('useStorage Hook', () => {
       const mockUrl = 'https://example.com/public/test-file.txt';
       vi.mocked(getPublicUrl).mockReturnValue(mockUrl);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       const url = result.current.getFileUrl('test-org/public/test-file.txt');
 
@@ -245,7 +245,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(getSignedUrl).mockResolvedValue(mockSignedUrl);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let signedUrl: string | null = null;
       await act(async () => {
@@ -263,7 +263,7 @@ describe('useStorage Hook', () => {
     it('should handle signed URL failure', async () => {
       vi.mocked(getSignedUrl).mockRejectedValue(new Error('Signing failed'));
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let signedUrl: string | null = null;
       await act(async () => {
@@ -276,7 +276,7 @@ describe('useStorage Hook', () => {
     it('should handle signed URL with null result', async () => {
       vi.mocked(getSignedUrl).mockResolvedValue(null);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let signedUrl: string | null = null;
       await act(async () => {
@@ -295,7 +295,7 @@ describe('useStorage Hook', () => {
       vi.mocked(deleteFile).mockResolvedValue(mockDeleteResult);
       vi.mocked(listFiles).mockResolvedValue(mockListResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let deleteResult: any;
       await act(async () => {
@@ -311,7 +311,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(deleteFile).mockResolvedValue(mockDeleteResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let deleteResult: any;
       await act(async () => {
@@ -324,7 +324,7 @@ describe('useStorage Hook', () => {
     it('should handle delete file exception', async () => {
       vi.mocked(deleteFile).mockRejectedValue(new Error('Network error'));
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let deleteResult: any;
       await act(async () => {
@@ -344,7 +344,7 @@ describe('useStorage Hook', () => {
       vi.mocked(archiveFile).mockResolvedValue(mockArchiveResult);
       vi.mocked(listFiles).mockResolvedValue(mockListResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let archiveResult: any;
       await act(async () => {
@@ -363,7 +363,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(archiveFile).mockResolvedValue(mockArchiveResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let archiveResult: any;
       await act(async () => {
@@ -376,7 +376,7 @@ describe('useStorage Hook', () => {
     it('should handle archive file exception', async () => {
       vi.mocked(archiveFile).mockRejectedValue(new Error('Network error'));
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let archiveResult: any;
       await act(async () => {
@@ -417,7 +417,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(listFiles).mockResolvedValue(mockListResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let listResult: any;
       await act(async () => {
@@ -439,7 +439,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(listFiles).mockResolvedValue(mockListResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       const customOptions = {
         pathPrefix: 'documents',
@@ -465,7 +465,7 @@ describe('useStorage Hook', () => {
     it('should handle list files failure', async () => {
       vi.mocked(listFiles).mockRejectedValue(new Error('List failed'));
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let listResult: any;
       await act(async () => {
@@ -481,7 +481,7 @@ describe('useStorage Hook', () => {
     it('should handle list files exception with non-Error object', async () => {
       vi.mocked(listFiles).mockRejectedValue('String error');
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       let listResult: any;
       await act(async () => {
@@ -497,7 +497,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(listFiles).mockResolvedValue(mockListResult);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       await act(async () => {
         await result.current.refreshFiles();
@@ -519,7 +519,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(uploadFile).mockReturnValue(uploadPromise);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       expect(result.current.isUploading).toBe(false);
 
@@ -545,7 +545,7 @@ describe('useStorage Hook', () => {
 
       vi.mocked(listFiles).mockReturnValue(listPromise);
 
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       expect(result.current.isListing).toBe(false);
 
@@ -566,13 +566,13 @@ describe('useStorage Hook', () => {
 
   describe('Aliases', () => {
     it('should provide isLoading alias for isListing', () => {
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       expect(result.current.isLoading).toBe(result.current.isListing);
     });
 
     it('should provide error alias for listError', () => {
-      const { result } = renderHook(() => useStorage(defaultProps));
+      const { result } = renderHook(() => useStorage(baseProps));
 
       expect(result.current.error).toBe(result.current.listError);
     });
@@ -580,7 +580,7 @@ describe('useStorage Hook', () => {
 });
 
 describe('useFileUpload Hook', () => {
-  const defaultProps = {
+  const baseProps = {
     supabase: mockSupabase,
     appName: 'test-app',
     orgId: 'test-org',
@@ -588,7 +588,7 @@ describe('useFileUpload Hook', () => {
 
     describe('Initial State', () => {
     it('should initialize with correct default values', () => {
-      const { result } = renderHook(() => useFileUpload(defaultProps));
+      const { result } = renderHook(() => useFileUpload(baseProps));
 
       expect(result.current.uploadProgress).toBe(0);
       expect(result.current.isUploading).toBe(false);
@@ -605,7 +605,7 @@ describe('useFileUpload Hook', () => {
 
       vi.mocked(uploadFile).mockResolvedValue(mockUploadResult);
 
-      const { result } = renderHook(() => useFileUpload(defaultProps));
+      const { result } = renderHook(() => useFileUpload(baseProps));
 
       let uploadResult: any;
       await act(async () => {
@@ -628,7 +628,7 @@ describe('useFileUpload Hook', () => {
 
       vi.mocked(uploadFile).mockReturnValue(uploadPromise);
 
-      const { result } = renderHook(() => useFileUpload(defaultProps));
+      const { result } = renderHook(() => useFileUpload(baseProps));
 
       act(() => {
         result.current.uploadWithProgress(mockFile);
@@ -670,7 +670,7 @@ describe('useFileUpload Hook', () => {
 
       vi.mocked(uploadFile).mockResolvedValue(mockUploadResult);
 
-      const { result } = renderHook(() => useFileUpload(defaultProps));
+      const { result } = renderHook(() => useFileUpload(baseProps));
 
       let uploadResult: any;
       await act(async () => {
@@ -686,7 +686,7 @@ describe('useFileUpload Hook', () => {
     it('should handle upload exception', async () => {
       vi.mocked(uploadFile).mockRejectedValue(new Error('Network error'));
 
-      const { result } = renderHook(() => useFileUpload(defaultProps));
+      const { result } = renderHook(() => useFileUpload(baseProps));
 
       let uploadResult: any;
       await act(async () => {
@@ -707,7 +707,7 @@ describe('useFileUpload Hook', () => {
 
       vi.mocked(uploadFile).mockResolvedValue(mockUploadResult);
 
-      const { result } = renderHook(() => useFileUpload(defaultProps));
+      const { result } = renderHook(() => useFileUpload(baseProps));
 
       await act(async () => {
         await result.current.uploadWithProgress(mockFile);
@@ -729,7 +729,7 @@ describe('useFileUpload Hook', () => {
 
       vi.mocked(uploadFile).mockResolvedValue(mockUploadResult);
 
-      const { result } = renderHook(() => useFileUpload(defaultProps));
+      const { result } = renderHook(() => useFileUpload(baseProps));
 
       const customOptions = {
         isPublic: true,

package/src/hooks/index.ts

@@ -33,9 +33,8 @@ export type { UseAddressAutocompleteOptions, UseAddressAutocompleteReturn } from
 
 // === ORGANISATION HOOKS ===
 export { useOrganisationPermissions } from './useOrganisationPermissions';
-export { useSecureDataAccess } from './useSecureDataAccess';
+// useSecureDataAccess has been removed - use useSecureSupabase from @jmruthers/pace-core/rbac instead
 export type { UseOrganisationPermissionsReturn } from './useOrganisationPermissions';
-export type { SecureDataAccessReturn } from './useSecureDataAccess';
 export { useOrganisationSecurity } from './useOrganisationSecurity';
 export type { OrganisationSecurityHook } from './useOrganisationSecurity';
 

package/src/hooks/public/usePublicEvent.ts

@@ -54,7 +54,7 @@
  * - Error boundary integration
  *
  * @dependencies
- * - React 18+ - Hooks and effects
+ * - React 19+ - Hooks and effects
  * - @supabase/supabase-js - Database integration
  * - Event types - Type definitions
  */
@@ -70,6 +70,10 @@ import { logger } from '../../utils/core/logger';
 // Simple in-memory cache for public data
 const publicDataCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
 
+/**
+ * Return value of the usePublicEvent hook.
+ * Provides event data, loading state, error, and refetch function.
+ */
 export interface UsePublicEventReturn {
   /** The event data, null if not loaded or not found */
   event: Event | null;

package/src/hooks/public/usePublicEventLogo.ts

@@ -59,7 +59,7 @@
  * - Lazy loading support
  *
  * @dependencies
- * - React 18+ - Hooks and effects
+ * - React 19+ - Hooks and effects
  * - @supabase/supabase-js - Storage integration
  * - Event types - Type definitions
  */
@@ -74,6 +74,10 @@ const log = createLogger('usePublicEventLogo');
 // Simple in-memory cache for public data
 const publicDataCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
 
+/**
+ * Return value of the usePublicEventLogo hook.
+ * Provides logo URL, fallback text, loading state, error, and refetch function.
+ */
 export interface UsePublicEventLogoReturn {
   /** The logo URL if available, null if not found or error */
   logoUrl: string | null;

package/src/hooks/public/usePublicFileDisplay.ts

@@ -46,6 +46,10 @@ import { logger } from '../../utils/core/logger';
 // Simple in-memory cache for public file data
 const publicFileCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
 
+/**
+ * Return value of the usePublicFileDisplay hook.
+ * Provides file URLs, references, loading state, error, and refetch function.
+ */
 export interface UsePublicFileDisplayReturn {
   /** Single file URL if category is provided and file found, null otherwise */
   fileUrl: string | null;

package/src/hooks/public/usePublicRouteParams.ts

@@ -51,7 +51,7 @@
  * - Caching integration
  *
  * @dependencies
- * - React 18+ - Hooks and effects
+ * - React 19+ - Hooks and effects
  * - React Router - URL parameter extraction
  * - Event types - Type definitions
  */
@@ -61,6 +61,10 @@ import { useParams, useLocation } from 'react-router-dom';
 import type { Event } from '../../types/event';
 import { usePublicEvent } from './usePublicEvent';
 
+/**
+ * Return value of the usePublicRouteParams hook.
+ * Provides event code, event ID, event data, loading state, error, and refetch function.
+ */
 export interface UsePublicRouteParamsReturn {
   /** The event code from the URL */
   eventCode: string | null;

package/src/hooks/services/useAuth.ts

@@ -11,23 +11,55 @@
 import { useAuthService } from './useAuthService';
 import { type User, type Session, type SupabaseClient, AuthError } from '@supabase/supabase-js';
 
+/**
+ * Authentication state and methods returned by the useAuth hook.
+ */
 export interface AuthState {
+  /** Current authenticated user, or null if not authenticated */
   user: User | null;
+  /** Current session, or null if not authenticated */
   session: Session | null;
+  /** Whether the user is currently authenticated */
   isAuthenticated: boolean;
+  /** Whether authentication state is currently loading */
   authLoading: boolean;
+  /** Any authentication error that occurred, or null */
   authError: AuthError | null;
+  /** Supabase client instance, or null if not available */
   supabase: SupabaseClient | null;
   
   // Auth methods
+  /** Sign in with email and optional password */
   signIn: (email: string, password?: string) => Promise<{ error: AuthError | null }>;
+  /** Sign up with email and password */
   signUp: (email: string, password: string) => Promise<{ error: AuthError | null }>;
+  /** Sign out the current user */
   signOut: () => Promise<{ error: AuthError | null }>;
+  /** Request a password reset email */
   resetPassword: (email: string) => Promise<{ error: AuthError | null }>;
+  /** Update the current user's password */
   updatePassword: (password: string) => Promise<{ error: AuthError | null }>;
+  /** Refresh the current session */
   refreshSession: () => Promise<{ error: AuthError | null }>;
 }
 
+/**
+ * Convenience hook for authentication.
+ * Returns the auth state and methods needed by components.
+ * 
+ * @returns Authentication state and methods
+ * 
+ * @example
+ * ```tsx
+ * const { user, isAuthenticated, signIn, signOut } = useAuth();
+ * 
+ * if (!isAuthenticated) {
+ *   return <LoginForm onSignIn={signIn} />;
+ * }
+ * 
+ * return <Dashboard user={user} onSignOut={signOut} />;
+ * ```
+ */
 export function useAuth(): AuthState {
   const authService = useAuthService();
   

package/src/hooks/services/useCurrentEvent.ts

@@ -22,6 +22,12 @@ export interface CurrentEventState {
   refreshEvents: () => Promise<void>;
 }
 
+/**
+ * Convenience hook for accessing current event state.
+ * Returns event state and methods needed by components.
+ * 
+ * @returns Current event state including events, selected event, loading state, and methods
+ */
 export function useCurrentEvent(): CurrentEventState {
   const eventService = useEventService();
   

package/src/hooks/services/useCurrentOrganisation.ts

@@ -30,6 +30,12 @@ export interface CurrentOrganisationState {
   getPrimaryOrganisation: () => Organisation | null;
 }
 
+/**
+ * Convenience hook for accessing current organisation state.
+ * Returns organisation state and methods needed by components.
+ * 
+ * @returns Current organisation state including selected organisation, organisations, memberships, and methods
+ */
 export function useCurrentOrganisation(): CurrentOrganisationState {
   const organisationService = useOrganisationService();
   

package/src/hooks/useDataTableState.ts

@@ -3,7 +3,7 @@
  * @description Hook for managing DataTable state
  */
 
-import { useState, useCallback, useMemo } from 'react';
+import { useState, useCallback } from 'react';
 import type { SortingState, ColumnFiltersState, ExpandedState } from '@tanstack/react-table';
 
 export interface DataTableState {
@@ -63,24 +63,14 @@ export function useDataTableState(options: UseDataTableStateOptions) {
     setSelectedRows([]);
   }, [initialPageSize]);
 
-  // Computed values
-  const paginatedData = useMemo(() => {
-    const start = pageIndex * pageSize;
-    const end = start + pageSize;
-    return data.slice(start, end);
-  }, [data, pageIndex, pageSize]);
+  // Computed values - React Compiler handles memoization automatically
+  const start = pageIndex * pageSize;
+  const end = start + pageSize;
+  const paginatedData = data.slice(start, end);
 
-  const totalPages = useMemo(() => {
-    return Math.ceil(data.length / pageSize);
-  }, [data.length, pageSize]);
-
-  const hasNextPage = useMemo(() => {
-    return pageIndex < totalPages - 1;
-  }, [pageIndex, totalPages]);
-
-  const hasPreviousPage = useMemo(() => {
-    return pageIndex > 0;
-  }, [pageIndex]);
+  const totalPages = Math.ceil(data.length / pageSize);
+  const hasNextPage = pageIndex < totalPages - 1;
+  const hasPreviousPage = pageIndex > 0;
 
   return {
     state: {

package/src/hooks/useDebounce.ts

@@ -1,6 +1,15 @@
 
 import { useState, useEffect } from 'react';
 
+/**
+ * Hook for debouncing a value.
+ * Returns a debounced version of the value that only updates after the specified delay.
+ * 
+ * @template T - The type of the value to debounce
+ * @param value - The value to debounce
+ * @param delay - The delay in milliseconds
+ * @returns The debounced value
+ */
 export function useDebounce<T>(value: T, delay: number): T {
   const [debouncedValue, setDebouncedValue] = useState<T>(value);
 

package/src/hooks/useEventTheme.ts

@@ -92,6 +92,12 @@ const log = createLogger('useEventTheme');
  * }
  * ```
  */
+/**
+ * Hook that automatically applies event-specific theming.
+ * Works in authenticated mode (via EventProvider) or public page mode (via event prop).
+ * 
+ * @param event - Optional event object for public page mode. If not provided, uses EventProvider context.
+ */
 export function useEventTheme(event?: Event | null): void {
   const location = useLocation();
   

package/src/hooks/useFileDisplay.ts

@@ -71,6 +71,10 @@ function cleanupCache() {
   }
 }
 
+/**
+ * Return value of the useFileDisplay hook.
+ * Provides file URLs, references, loading state, error, and refetch function.
+ */
 export interface UseFileDisplayReturn {
   /** Single file URL if category is provided and file found, null otherwise */
   fileUrl: string | null;

package/src/hooks/useFileReference.ts

@@ -59,6 +59,13 @@ const urlRefreshManager = {
   }
 };
 
+/**
+ * Hook for managing file references.
+ * Provides file upload, retrieval, and URL generation functionality.
+ * 
+ * @param supabase - Supabase client instance
+ * @returns File reference service with upload, get, and URL methods
+ */
 export function useFileReference(supabase: SupabaseClient) {
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -385,13 +392,18 @@ export function useFileReferenceById(
     }
 
     const loadUrl = async () => {
-      const service = createFileReferenceService(supabase);
-      const url = await service.getFileUrl(
-        fileReference.table_name,
-        fileReference.record_id,
-        organisationId
-      );
-      setFileUrl(url);
+      try {
+        const service = createFileReferenceService(supabase);
+        const url = await service.getFileUrl(
+          fileReference.table_name,
+          fileReference.record_id,
+          organisationId
+        );
+        setFileUrl(url);
+      } catch (error) {
+        // Silently fail - component will handle missing URL
+        setFileUrl(null);
+      }
     };
 
     loadUrl();
@@ -478,6 +490,9 @@ export type UseFileReferenceOptions = {
   organisation_id: string;
 };
 
+/**
+ * Return value of the useFileReference hook.
+ */
 export type UseFileReferenceReturn = {
   isLoading: boolean;
   error: string | null;
@@ -492,6 +507,9 @@ export type UseFileReferenceReturn = {
   clearError: () => void;
 };
 
+/**
+ * Return value of the useFileReferenceForRecord hook.
+ */
 export type UseFileReferenceForRecordReturn = {
   isLoading: boolean;
   error: string | null;

package/src/hooks/useFileUrl.ts

@@ -15,11 +15,14 @@ import { createLogger } from '../utils/core/logger';
 
 const log = createLogger('useFileUrl');
 
+/**
+ * Options for the useFileUrl hook.
+ */
 export interface UseFileUrlOptions {
   /** Organisation ID for signed URL generation */
   organisation_id: string | undefined;
   /** Supabase client instance */
-  supabase: SupabaseClient;
+  supabase: SupabaseClient | null;
   /** Whether to auto-load URLs on mount */
   autoLoad?: boolean;
 }
@@ -63,6 +66,13 @@ export function useFileUrl(
       return;
     }
 
+    if (!supabase) {
+      setUrl(null);
+      setIsLoading(false);
+      setError(new Error('Supabase client is required for URL generation'));
+      return;
+    }
+
     // Skip if already loading or URL already exists for this file
     if (isLoading || (url && fileReferenceIdRef.current === fileReference.id)) {
       return;