@jmruthers/pace-core 0.5.185 → 0.5.187

package/src/hooks/useAddressAutocomplete.test.ts

@@ -0,0 +1,318 @@
+/**
+ * @file Address Autocomplete Hook Tests
+ * @package @jmruthers/pace-core
+ * @module Hooks/__tests__
+ * @since 0.1.0
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { useAddressAutocomplete } from './useAddressAutocomplete';
+import * as googlePlacesUtils from '../utils/google-places';
+
+// Mock the Google Places utilities
+vi.mock('../utils/google-places', () => ({
+  fetchPlaceAutocomplete: vi.fn(),
+  fetchPlaceDetails: vi.fn(),
+  createAddressFromPlaceResult: vi.fn(),
+  getAddressByPlaceId: vi.fn(),
+}));
+
+// Mock useQueryCache
+vi.mock('./useQueryCache', () => ({
+  useQueryCache: () => ({
+    getCachedQuery: async <T,>(_table: string, _filterKey: string, _filterValue: string, fetchFn: () => Promise<T>) => {
+      return fetchFn();
+    },
+  }),
+}));
+
+// Mock useDebounce to return value immediately for tests
+vi.mock('./useDebounce', () => ({
+  useDebounce: (value: any, _delay: number) => value,
+}));
+
+describe('useAddressAutocomplete', () => {
+  const mockApiKey = 'test-api-key';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+    vi.useRealTimers();
+  });
+
+  describe('Initial state', () => {
+    it('returns initial state with empty suggestions', () => {
+      const { result } = renderHook(() => useAddressAutocomplete(mockApiKey, ''));
+
+      expect(result.current.suggestions).toEqual([]);
+      expect(result.current.isLoading).toBe(false);
+      expect(result.current.error).toBeNull();
+    }, { timeout: 5000 });
+  });
+
+  describe('Autocomplete suggestions', () => {
+    it('fetches suggestions when input value changes', async () => {
+      const mockPredictions = [
+        {
+          description: '123 Main St, Melbourne VIC, Australia',
+          place_id: 'ChIJ123',
+          structured_formatting: {
+            main_text: '123 Main St',
+            secondary_text: 'Melbourne VIC, Australia',
+          },
+        },
+      ];
+
+      vi.mocked(googlePlacesUtils.fetchPlaceAutocomplete).mockResolvedValueOnce(mockPredictions);
+
+      const { result } = renderHook(() =>
+        useAddressAutocomplete(mockApiKey, '123 Main', { debounceDelay: 0 })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.suggestions).toHaveLength(1);
+        },
+        { timeout: 1000 }
+      );
+
+      expect(result.current.suggestions[0].place_id).toBe('ChIJ123');
+    }, { timeout: 5000 });
+
+    it('debounces input value', async () => {
+      vi.mocked(googlePlacesUtils.fetchPlaceAutocomplete).mockResolvedValue([]);
+
+      // Since we're mocking useDebounce to return immediately, this test verifies
+      // that the hook still works correctly with rapid input changes
+      const { result, rerender } = renderHook(
+        ({ inputValue }) => useAddressAutocomplete(mockApiKey, inputValue, { debounceDelay: 0 }),
+        { initialProps: { inputValue: '123' } }
+      );
+
+      // Change input quickly - with mocked debounce, each change triggers immediately
+      rerender({ inputValue: '123 M' });
+      rerender({ inputValue: '123 Ma' });
+      rerender({ inputValue: '123 Main' });
+
+      // Wait for the last call
+      await waitFor(
+        () => {
+          expect(googlePlacesUtils.fetchPlaceAutocomplete).toHaveBeenCalled();
+        },
+        { timeout: 1000 }
+      );
+
+      // With mocked debounce, it will be called for each change
+      expect(googlePlacesUtils.fetchPlaceAutocomplete).toHaveBeenCalled();
+    }, { timeout: 5000 });
+
+    it('clears suggestions when input is empty', async () => {
+      vi.mocked(googlePlacesUtils.fetchPlaceAutocomplete).mockResolvedValueOnce([
+        { description: '123 Main St', place_id: 'ChIJ123' },
+      ]);
+
+      const { result, rerender } = renderHook(
+        ({ inputValue }) => useAddressAutocomplete(mockApiKey, inputValue, { debounceDelay: 0 }),
+        { initialProps: { inputValue: '123 Main' } }
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.suggestions).toBeDefined();
+          expect(result.current.suggestions.length).toBeGreaterThan(0);
+        },
+        { timeout: 1000 }
+      );
+
+      rerender({ inputValue: '' });
+
+      await waitFor(
+        () => {
+          expect(result.current.suggestions).toBeDefined();
+          expect(result.current.suggestions).toEqual([]);
+        },
+        { timeout: 1000 }
+      );
+    }, { timeout: 5000 });
+
+    it('handles API errors', async () => {
+      const error = new Error('API request denied');
+      vi.mocked(googlePlacesUtils.fetchPlaceAutocomplete).mockRejectedValueOnce(error);
+
+      const { result } = renderHook(() =>
+        useAddressAutocomplete(mockApiKey, '123 Main', { debounceDelay: 0 })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.error).not.toBeNull();
+        },
+        { timeout: 1000 }
+      );
+
+      expect(result.current.error?.message).toBe('API request denied');
+      expect(result.current.suggestions).toEqual([]);
+    }, { timeout: 5000 });
+  });
+
+  describe('Address selection', () => {
+    it('selects address by place_id', async () => {
+      const mockPlaceDetails = {
+        place_id: 'ChIJ123',
+        formatted_address: '123 Main St, Melbourne VIC 3000, Australia',
+        address_components: [],
+        geometry: { location: { lat: -37.8136, lng: 144.9631 } },
+      };
+
+      const mockParsedAddress = {
+        place_id: 'ChIJ123',
+        full_address: '123 Main St, Melbourne VIC 3000, Australia',
+        street_number: null,
+        route: null,
+        suburb: null,
+        state: null,
+        postcode: null,
+        country: null,
+        lat: -37.8136,
+        lng: 144.9631,
+      };
+
+      vi.mocked(googlePlacesUtils.fetchPlaceDetails).mockResolvedValueOnce(mockPlaceDetails);
+      vi.mocked(googlePlacesUtils.createAddressFromPlaceResult).mockReturnValueOnce(mockParsedAddress);
+
+      const { result } = renderHook(() => useAddressAutocomplete(mockApiKey, ''));
+
+      const address = await result.current.selectAddress('ChIJ123');
+
+      expect(address).not.toBeNull();
+      expect(address?.place_id).toBe('ChIJ123');
+      expect(googlePlacesUtils.fetchPlaceDetails).toHaveBeenCalledWith('ChIJ123', mockApiKey);
+    }, { timeout: 5000 });
+
+    it('returns null when place_id is invalid', async () => {
+      vi.mocked(googlePlacesUtils.fetchPlaceDetails).mockRejectedValueOnce(new Error('Place not found'));
+
+      const { result } = renderHook(() => useAddressAutocomplete(mockApiKey, ''));
+
+      const address = await result.current.selectAddress('invalid');
+
+      expect(address).toBeNull();
+    });
+  });
+
+  describe('getAddressByPlaceId', () => {
+    it('retrieves address by place_id', async () => {
+      const mockAddress = {
+        place_id: 'ChIJ123',
+        full_address: '123 Main St',
+        street_number: null,
+        route: null,
+        suburb: null,
+        state: null,
+        postcode: null,
+        country: null,
+        lat: null,
+        lng: null,
+      };
+
+      vi.mocked(googlePlacesUtils.getAddressByPlaceId).mockResolvedValueOnce(mockAddress);
+
+      const { result } = renderHook(() => useAddressAutocomplete(mockApiKey, ''));
+
+      const address = await result.current.getAddressByPlaceId('ChIJ123');
+
+      expect(address).not.toBeNull();
+      expect(address?.place_id).toBe('ChIJ123');
+    }, { timeout: 5000 });
+
+    it('returns null on error', async () => {
+      vi.mocked(googlePlacesUtils.getAddressByPlaceId).mockResolvedValueOnce(null);
+
+      const { result } = renderHook(() => useAddressAutocomplete(mockApiKey, ''));
+
+      const address = await result.current.getAddressByPlaceId('invalid');
+
+      expect(address).toBeNull();
+    }, { timeout: 5000 });
+  });
+
+  describe('clearSuggestions', () => {
+    it('clears suggestions', async () => {
+      vi.mocked(googlePlacesUtils.fetchPlaceAutocomplete).mockResolvedValueOnce([
+        { description: '123 Main St', place_id: 'ChIJ123' },
+      ]);
+
+      const { result } = renderHook(() =>
+        useAddressAutocomplete(mockApiKey, '123 Main', { debounceDelay: 0 })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.suggestions).toBeDefined();
+          expect(result.current.suggestions.length).toBeGreaterThan(0);
+        },
+        { timeout: 1000 }
+      );
+
+      result.current.clearSuggestions();
+
+      // Wait for state update
+      await waitFor(
+        () => {
+          expect(result.current.suggestions).toEqual([]);
+          expect(result.current.error).toBeNull();
+        },
+        { timeout: 1000 }
+      );
+    }, { timeout: 5000 });
+  });
+
+  describe('Caching', () => {
+    it('uses cache when enabled', async () => {
+      const mockPredictions = [{ description: '123 Main St', place_id: 'ChIJ123' }];
+      vi.mocked(googlePlacesUtils.fetchPlaceAutocomplete).mockResolvedValueOnce(mockPredictions);
+
+      const { result } = renderHook(() =>
+        useAddressAutocomplete(mockApiKey, '123 Main', {
+          debounceDelay: 0,
+          cacheEnabled: true,
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.suggestions.length).toBeGreaterThan(0);
+        },
+        { timeout: 1000 }
+      );
+
+      expect(googlePlacesUtils.fetchPlaceAutocomplete).toHaveBeenCalled();
+    });
+
+    it('skips cache when disabled', async () => {
+      const mockPredictions = [{ description: '123 Main St', place_id: 'ChIJ123' }];
+      vi.mocked(googlePlacesUtils.fetchPlaceAutocomplete).mockResolvedValueOnce(mockPredictions);
+
+      const { result } = renderHook(() =>
+        useAddressAutocomplete(mockApiKey, '123 Main', {
+          debounceDelay: 0,
+          cacheEnabled: false,
+        })
+      );
+
+      await waitFor(
+        () => {
+          expect(result.current.suggestions.length).toBeGreaterThan(0);
+        },
+        { timeout: 1000 }
+      );
+
+      expect(googlePlacesUtils.fetchPlaceAutocomplete).toHaveBeenCalled();
+    }, { timeout: 5000 });
+  });
+});
+

package/src/hooks/useAddressAutocomplete.ts

@@ -0,0 +1,268 @@
+/**
+ * @file Address Autocomplete Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/AddressAutocomplete
+ * @since 0.1.0
+ *
+ * Hook for managing Google Places API autocomplete functionality.
+ * Provides debounced input, caching, and address selection.
+ */
+
+import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { useDebounce } from './useDebounce';
+import { useQueryCache } from './useQueryCache';
+import {
+  fetchPlaceAutocomplete,
+  fetchPlaceDetails,
+  createAddressFromPlaceResult,
+  getAddressByPlaceId,
+} from '../utils/google-places';
+import type {
+  GooglePlaceAutocompletePrediction,
+  ParsedAddress,
+  AutocompleteOptions,
+} from '../utils/google-places';
+
+export interface UseAddressAutocompleteOptions {
+  /** Google Places API options */
+  autocompleteOptions?: AutocompleteOptions;
+  /** Debounce delay in milliseconds (default: 300) */
+  debounceDelay?: number;
+  /** Enable caching (default: true) */
+  cacheEnabled?: boolean;
+  /** Cache TTL configuration */
+  cacheTTL?: {
+    /** Autocomplete cache TTL in seconds (default: 3600 = 1 hour) */
+    autocomplete?: number;
+    /** Place details cache TTL in seconds (default: 86400 = 24 hours) */
+    placeDetails?: number;
+  };
+}
+
+export interface UseAddressAutocompleteReturn {
+  /** Array of autocomplete suggestions */
+  suggestions: GooglePlaceAutocompletePrediction[];
+  /** Loading state */
+  isLoading: boolean;
+  /** Error state */
+  error: Error | null;
+  /** Select an address by place_id */
+  selectAddress: (placeId: string) => Promise<ParsedAddress | null>;
+  /** Get address by place_id (uses cache) */
+  getAddressByPlaceId: (placeId: string) => Promise<ParsedAddress | null>;
+  /** Clear suggestions */
+  clearSuggestions: () => void;
+}
+
+/**
+ * Hook for Google Places API autocomplete with caching
+ *
+ * @param apiKey - Google Places API key
+ * @param inputValue - Current input value
+ * @param options - Hook configuration options
+ * @returns Autocomplete state and functions
+ *
+ * @example
+ * ```tsx
+ * const { suggestions, isLoading, selectAddress } = useAddressAutocomplete(
+ *   apiKey,
+ *   inputValue,
+ *   { debounceDelay: 300, cacheEnabled: true }
+ * );
+ * ```
+ */
+export function useAddressAutocomplete(
+  apiKey: string,
+  inputValue: string,
+  options: UseAddressAutocompleteOptions = {}
+): UseAddressAutocompleteReturn {
+  const {
+    debounceDelay = 300,
+    cacheEnabled = true,
+    cacheTTL = {
+      autocomplete: 3600, // 1 hour
+      placeDetails: 86400, // 24 hours
+    },
+    autocompleteOptions,
+  } = options;
+
+  const [suggestions, setSuggestions] = useState<GooglePlaceAutocompletePrediction[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const debouncedInput = useDebounce(inputValue, debounceDelay);
+  const { getCachedQuery } = useQueryCache();
+  const abortControllerRef = useRef<AbortController | null>(null);
+
+  // Memoize autocompleteOptions to prevent unnecessary re-renders
+  const memoizedAutocompleteOptions = useMemo(
+    () => autocompleteOptions,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(autocompleteOptions)]
+  );
+
+  // Fetch autocomplete suggestions
+  useEffect(() => {
+    // Cancel previous request if still in flight
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort();
+    }
+
+    // Reset state if input is empty
+    if (!debouncedInput.trim()) {
+      setSuggestions([]);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Don't fetch if no API key
+    if (!apiKey) {
+      setError(new Error('Google Places API key is required'));
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+
+    const fetchSuggestions = async () => {
+      try {
+        let predictions: GooglePlaceAutocompletePrediction[];
+
+        if (cacheEnabled) {
+          // Use cached query with TTL
+          predictions = await getCachedQuery(
+            'google-places-autocomplete',
+            'query',
+            debouncedInput,
+            async () => {
+              return fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
+            },
+            { ttl: cacheTTL.autocomplete, enabled: true }
+          );
+        } else {
+          // Direct fetch without cache
+          predictions = await fetchPlaceAutocomplete(debouncedInput, apiKey, memoizedAutocompleteOptions);
+        }
+
+        setSuggestions(predictions);
+        setIsLoading(false);
+      } catch (err) {
+        // Ignore aborted requests
+        if (err instanceof Error && err.name === 'AbortError') {
+          return;
+        }
+
+        const error = err instanceof Error ? err : new Error('Failed to fetch autocomplete suggestions');
+        setError(error);
+        setSuggestions([]);
+        setIsLoading(false);
+      }
+    };
+
+    fetchSuggestions();
+
+    // Cleanup function to cancel in-flight requests
+    return () => {
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort();
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [debouncedInput, apiKey, cacheEnabled, cacheTTL.autocomplete]);
+
+  // Select address by place_id
+  const selectAddress = useCallback(
+    async (placeId: string): Promise<ParsedAddress | null> => {
+      if (!placeId || !apiKey) {
+        return null;
+      }
+
+      setIsLoading(true);
+      setError(null);
+
+      try {
+        let placeDetails;
+
+        if (cacheEnabled) {
+          // Use cached query with TTL
+          placeDetails = await getCachedQuery(
+            'google-places-details',
+            'place_id',
+            placeId,
+            async () => {
+              return fetchPlaceDetails(placeId, apiKey);
+            },
+            { ttl: cacheTTL.placeDetails, enabled: true }
+          );
+        } else {
+          // Direct fetch without cache
+          placeDetails = await fetchPlaceDetails(placeId, apiKey);
+        }
+
+        const parsedAddress = createAddressFromPlaceResult(placeDetails);
+        setIsLoading(false);
+        return parsedAddress;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Failed to fetch place details');
+        setError(error);
+        setIsLoading(false);
+        return null;
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [apiKey, cacheEnabled, cacheTTL.placeDetails]
+  );
+
+  // Get address by place_id (utility function)
+  const getAddressByPlaceIdFn = useCallback(
+    async (placeId: string): Promise<ParsedAddress | null> => {
+      if (!placeId || !apiKey) {
+        return null;
+      }
+
+      try {
+        if (cacheEnabled) {
+          // Use cached query with TTL
+          return await getCachedQuery(
+            'google-places-details',
+            'place_id',
+            placeId,
+            async () => {
+              const result = await getAddressByPlaceId(placeId, apiKey);
+              if (!result) {
+                throw new Error('Failed to fetch address');
+              }
+              return result;
+            },
+            { ttl: cacheTTL.placeDetails, enabled: true }
+          );
+        } else {
+          return await getAddressByPlaceId(placeId, apiKey);
+        }
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Failed to get address by place_id');
+        setError(error);
+        return null;
+      }
+    },
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [apiKey, cacheEnabled, cacheTTL.placeDetails]
+  );
+
+  // Clear suggestions
+  const clearSuggestions = useCallback(() => {
+    setSuggestions([]);
+    setError(null);
+  }, []);
+
+  return {
+    suggestions,
+    isLoading,
+    error,
+    selectAddress,
+    getAddressByPlaceId: getAddressByPlaceIdFn,
+    clearSuggestions,
+  };
+}
+

package/src/hooks/useFileDisplay.ts

@@ -37,7 +37,7 @@
 import { useState, useEffect, useCallback } from 'react';
 import type { SupabaseClient } from '@supabase/supabase-js';
 import { FileReference, FileCategory } from '../types/file-reference';
-import { getPublicUrl, getSignedUrl } from '../utils/storage/helpers';
+import { getPublicUrl, getSignedUrl, generateFileUrlsBatch } from '../utils/storage/helpers';
 import { createFileReferenceService } from '../utils/file-reference';
 import { logger } from '../utils/core/logger';
 
@@ -279,24 +279,12 @@ export function useFileDisplay(
         logger.debug('useFileDisplay', 'Setting file URL:', url ? 'URL set' : 'URL is null');
         setFileUrl(url);
       } else {
-        // Multiple files mode - generate URLs for all files
-        const urlMap = new Map<string, string>();
-        for (const fileRef of files) {
-          let url: string | null = null;
-          if (fileRef.is_public) {
-            url = getPublicUrl(supabase, fileRef.file_path, true);
-          } else {
-            const signedUrlResult = await getSignedUrl(supabase, fileRef.file_path, {
+        // Multiple files mode - generate URLs for all files in batch
+        const urlMap = await generateFileUrlsBatch(supabase, files, {
               appName: 'pace-core',
               orgId: organisation_id,
               expiresIn: 3600
             });
-            url = signedUrlResult?.url || null;
-          }
-          if (url) {
-            urlMap.set(fileRef.id, url);
-          }
-        }
         setFileUrls(urlMap);
         setFileReference(null);
         setFileUrl(null);

package/src/hooks/useFileReference.test.ts

@@ -18,6 +18,7 @@ let serviceMock: any;
 const mockUploadFileWithReference = vi.fn();
 const mockGetPublicUrl = vi.fn();
 const mockGetSignedUrl = vi.fn();
+const mockGenerateFileUrlsBatch = vi.fn();
 
 // Setup mocks
 beforeEach(() => {
@@ -47,12 +48,25 @@ beforeEach(() => {
     url: 'https://example.com/signed-file.jpg', 
     expiresAt: new Date(Date.now() + 3600 * 1000).toISOString() 
   });
+  // Mock batch URL generation to return URLs for all files
+  mockGenerateFileUrlsBatch.mockImplementation(async (supabase, files) => {
+    const urlMap = new Map<string, string>();
+    for (const file of files) {
+      if (file.is_public) {
+        urlMap.set(file.id, `https://example.com/${file.file_path}`);
+      } else {
+        urlMap.set(file.id, `https://example.com/signed/${file.file_path}`);
+      }
+    }
+    return urlMap;
+  });
   
   // Apply mocks
   vi.spyOn(fileReferenceUtils, 'createFileReferenceService').mockImplementation(mockCreateFileReferenceService as any);
   vi.spyOn(fileReferenceUtils, 'uploadFileWithReference').mockImplementation(mockUploadFileWithReference as any);
   vi.spyOn(storageHelpers, 'getPublicUrl').mockImplementation(mockGetPublicUrl as any);
   vi.spyOn(storageHelpers, 'getSignedUrl').mockImplementation(mockGetSignedUrl as any);
+  vi.spyOn(storageHelpers, 'generateFileUrlsBatch').mockImplementation(mockGenerateFileUrlsBatch as any);
 });
 
 afterEach(() => {
@@ -67,6 +81,7 @@ const mockFileUploadOptions = {
   organisation_id: 'test-org-123',
   app_id: 'test-app-123',
   category: FileCategory.GENERAL_DOCUMENTS,
+  folder: 'documents',
   pageContext: 'configuration',
   is_public: false
 };
@@ -504,16 +519,19 @@ describe('[hook] useFilesByCategory', () => {
     );
     
     await waitFor(() => {
-      expect(mockGetPublicUrl).toHaveBeenCalledWith(mockSupabase, publicFile.file_path, true);
-      expect(mockGetSignedUrl).toHaveBeenCalledWith(
+      // Verify batch URL generation was called with both files
+      expect(mockGenerateFileUrlsBatch).toHaveBeenCalledWith(
         mockSupabase,
-        privateFile.file_path,
+        [publicFile, privateFile],
         expect.objectContaining({
           appName: 'file-reference',
           orgId: 'test-org-123',
           expiresIn: 3600
         })
       );
+      // Verify URLs were generated
+      expect(result.current.fileUrls.get(publicFile.id)).toBeDefined();
+      expect(result.current.fileUrls.get(privateFile.id)).toBeDefined();
     });
   });
 });