@youversion/platform-react-hooks 1.10.0 → 1.12.0

package/src/context/VerseSelectionProvider.test.tsx

@@ -0,0 +1,362 @@
+import { describe, it, expect } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { VerseSelectionProvider } from './VerseSelectionProvider';
+import { useVerseSelection } from '../useVerseSelection';
+
+// Wrapper for renderHook
+const wrapper = ({ children }: { children: ReactNode }) => (
+  <VerseSelectionProvider>{children}</VerseSelectionProvider>
+);
+
+describe('VerseSelectionProvider', () => {
+  describe('initial state', () => {
+    it('should provide an empty Set instance', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      expect(result.current.selectedVerseUsfms).toBeInstanceOf(Set);
+      expect(result.current.selectedVerseUsfms.size).toBe(0);
+    });
+
+    it('should have selectedCount of 0', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      expect(result.current.selectedCount).toBe(0);
+    });
+
+    it('should return false for isSelected on any verse', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      expect(result.current.isSelected('MAT.1.1')).toBe(false);
+      expect(result.current.isSelected('GEN.1.1')).toBe(false);
+    });
+  });
+
+  describe('toggleVerse', () => {
+    it('should add verse to selection when not present', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      expect(result.current.selectedVerseUsfms.has('MAT.1.1')).toBe(true);
+      expect(result.current.selectedCount).toBe(1);
+    });
+
+    it('should remove verse from selection when already present', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      expect(result.current.selectedCount).toBe(1);
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      expect(result.current.selectedVerseUsfms.has('MAT.1.1')).toBe(false);
+      expect(result.current.selectedCount).toBe(0);
+    });
+
+    it('should support multiple verses selected simultaneously', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+        result.current.toggleVerse('GEN.1.1');
+        result.current.toggleVerse('JHN.3.16');
+      });
+
+      expect(result.current.selectedCount).toBe(3);
+      expect(result.current.selectedVerseUsfms.has('MAT.1.1')).toBe(true);
+      expect(result.current.selectedVerseUsfms.has('GEN.1.1')).toBe(true);
+      expect(result.current.selectedVerseUsfms.has('JHN.3.16')).toBe(true);
+    });
+
+    it('should create new Set reference on each update (immutability)', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      const set1 = result.current.selectedVerseUsfms;
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      const set2 = result.current.selectedVerseUsfms;
+
+      expect(set1).not.toBe(set2);
+      expect(set1.size).toBe(0);
+      expect(set2.size).toBe(1);
+    });
+
+    it('should create new Set reference when removing a verse', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      const setWithVerse = result.current.selectedVerseUsfms;
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      const setWithoutVerse = result.current.selectedVerseUsfms;
+
+      expect(setWithVerse).not.toBe(setWithoutVerse);
+      expect(setWithVerse.size).toBe(1);
+      expect(setWithoutVerse.size).toBe(0);
+    });
+
+    it('should not add duplicate verses', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      // Should toggle off, not add twice
+      expect(result.current.selectedCount).toBe(0);
+    });
+  });
+
+  describe('isSelected', () => {
+    it('should return true for selected verses', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      expect(result.current.isSelected('MAT.1.1')).toBe(true);
+    });
+
+    it('should return false for unselected verses', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      expect(result.current.isSelected('GEN.1.1')).toBe(false);
+    });
+
+    it('should work correctly after toggle operations', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      // Initially not selected
+      expect(result.current.isSelected('MAT.1.1')).toBe(false);
+
+      // Add verse - now selected
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+      expect(result.current.isSelected('MAT.1.1')).toBe(true);
+
+      // Remove verse - not selected again
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+      expect(result.current.isSelected('MAT.1.1')).toBe(false);
+    });
+  });
+
+  describe('clearSelection', () => {
+    it('should clear all selected verses', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+        result.current.toggleVerse('GEN.1.1');
+      });
+
+      expect(result.current.selectedCount).toBe(2);
+
+      act(() => {
+        result.current.clearSelection();
+      });
+
+      expect(result.current.selectedCount).toBe(0);
+      expect(result.current.selectedVerseUsfms.size).toBe(0);
+    });
+
+    it('should create new Set reference', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      const setBeforeClear = result.current.selectedVerseUsfms;
+
+      act(() => {
+        result.current.clearSelection();
+      });
+
+      const setAfterClear = result.current.selectedVerseUsfms;
+
+      expect(setBeforeClear).not.toBe(setAfterClear);
+      expect(setBeforeClear.size).toBe(1);
+      expect(setAfterClear.size).toBe(0);
+    });
+
+    it('should work when already empty', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      const setBeforeClear = result.current.selectedVerseUsfms;
+
+      act(() => {
+        result.current.clearSelection();
+      });
+
+      const setAfterClear = result.current.selectedVerseUsfms;
+
+      expect(setBeforeClear).not.toBe(setAfterClear);
+      expect(setAfterClear.size).toBe(0);
+    });
+  });
+
+  describe('selectedCount', () => {
+    it('should start at 0', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      expect(result.current.selectedCount).toBe(0);
+    });
+
+    it('should increment when verse added', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+      expect(result.current.selectedCount).toBe(1);
+
+      act(() => {
+        result.current.toggleVerse('GEN.1.1');
+      });
+      expect(result.current.selectedCount).toBe(2);
+
+      act(() => {
+        result.current.toggleVerse('JHN.3.16');
+      });
+      expect(result.current.selectedCount).toBe(3);
+    });
+
+    it('should decrement when verse removed', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+        result.current.toggleVerse('GEN.1.1');
+      });
+      expect(result.current.selectedCount).toBe(2);
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+      expect(result.current.selectedCount).toBe(1);
+    });
+
+    it('should return to 0 after clear', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+        result.current.toggleVerse('GEN.1.1');
+        result.current.toggleVerse('JHN.3.16');
+      });
+      expect(result.current.selectedCount).toBe(3);
+
+      act(() => {
+        result.current.clearSelection();
+      });
+      expect(result.current.selectedCount).toBe(0);
+    });
+  });
+
+  describe('callback stability', () => {
+    it('should have stable toggleVerse reference across renders', () => {
+      const { result, rerender } = renderHook(() => useVerseSelection(), { wrapper });
+
+      const toggleRef1 = result.current.toggleVerse;
+
+      rerender();
+
+      const toggleRef2 = result.current.toggleVerse;
+
+      expect(toggleRef1).toBe(toggleRef2);
+    });
+
+    it('should have stable clearSelection reference across renders', () => {
+      const { result, rerender } = renderHook(() => useVerseSelection(), { wrapper });
+
+      const clearRef1 = result.current.clearSelection;
+
+      rerender();
+
+      const clearRef2 = result.current.clearSelection;
+
+      expect(clearRef1).toBe(clearRef2);
+    });
+
+    it('should have stable toggleVerse reference after state changes', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      const toggleRef1 = result.current.toggleVerse;
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      const toggleRef2 = result.current.toggleVerse;
+
+      expect(toggleRef1).toBe(toggleRef2);
+    });
+
+    it('should have stable clearSelection reference after state changes', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      const clearRef1 = result.current.clearSelection;
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      const clearRef2 = result.current.clearSelection;
+
+      expect(clearRef1).toBe(clearRef2);
+    });
+
+    it('should update isSelected reference when selectedVerseUsfms changes', () => {
+      const { result } = renderHook(() => useVerseSelection(), { wrapper });
+
+      const isSelectedRef1 = result.current.isSelected;
+
+      act(() => {
+        result.current.toggleVerse('MAT.1.1');
+      });
+
+      const isSelectedRef2 = result.current.isSelected;
+
+      // isSelected has selectedVerseUsfms in its dependency array, so it should change
+      expect(isSelectedRef1).not.toBe(isSelectedRef2);
+    });
+
+    it('should have stable isSelected reference when no state changes', () => {
+      const { result, rerender } = renderHook(() => useVerseSelection(), { wrapper });
+
+      const isSelectedRef1 = result.current.isSelected;
+
+      rerender();
+
+      const isSelectedRef2 = result.current.isSelected;
+
+      expect(isSelectedRef1).toBe(isSelectedRef2);
+    });
+  });
+});

package/src/useLanguages.test.tsx

@@ -1,4 +1,4 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { renderHook, waitFor, act } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { ReactNode } from 'react';
 import { useLanguages } from './useLanguages';
@@ -206,11 +206,61 @@ describe('useLanguages', () => {
 
       expect(mockGetLanguages).toHaveBeenCalledTimes(1);
 
-      result.current.refetch();
+      act(() => {
+        result.current.refetch();
+      });
 
       await waitFor(() => {
         expect(mockGetLanguages).toHaveBeenCalledTimes(2);
       });
     });
+
+    it('should fetch languages with fields filter', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const options: GetLanguagesOptions = {
+        fields: ['id', 'language', 'script'],
+        page_size: '*',
+      };
+
+      const { result } = renderHook(() => useLanguages(options), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).toHaveBeenCalledWith(options);
+      expect(result.current.languages).toEqual(mockLanguages);
+    });
+
+    it('should refetch when fields change', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result, rerender } = renderHook(({ options }) => useLanguages(options), {
+        wrapper,
+        initialProps: { options: { fields: ['id', 'language'] } as GetLanguagesOptions },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).toHaveBeenCalledTimes(1);
+
+      rerender({ options: { fields: ['id', 'language', 'script'] } as GetLanguagesOptions });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetLanguages).toHaveBeenCalledTimes(2);
+      expect(mockGetLanguages).toHaveBeenLastCalledWith({
+        fields: ['id', 'language', 'script'],
+      });
+    });
   });
 });

package/src/useLanguages.ts

@@ -21,7 +21,13 @@ export function useLanguages(
 
   const { data, loading, error, refetch } = useApiData<Collection<Language>>(
     () => languagesClient.getLanguages(options),
-    [languagesClient, options?.country, options?.page_size, options?.page_token],
+    [
+      languagesClient,
+      JSON.stringify(options.fields),
+      options?.country,
+      options?.page_size,
+      options?.page_token,
+    ],
     {
       enabled: apiOptions?.enabled !== false,
     },

package/src/useVersion.test.tsx

@@ -0,0 +1,242 @@
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ReactNode } from 'react';
+import { useVersion } from './useVersion';
+import { YouVersionContext } from './context';
+import { type BibleClient, type BibleVersion } from '@youversion/platform-core';
+import { useBibleClient } from './useBibleClient';
+
+vi.mock('./useBibleClient');
+
+describe('useVersion', () => {
+  const mockAppKey = 'test-app-key';
+  const mockGetVersion = vi.fn();
+
+  const mockVersion: BibleVersion = {
+    id: 111,
+    title: 'New International Version',
+    abbreviation: 'NIV',
+    localized_title: 'New International Version',
+    localized_abbreviation: 'NIV',
+    language_tag: 'en',
+    books: ['GEN', 'EXO', 'LEV'],
+    youversion_deep_link: 'https://bible.com/versions/111',
+  };
+
+  const createWrapper = (contextValue: { appKey: string }) => {
+    return ({ children }: { children: ReactNode }) => (
+      <YouVersionContext.Provider value={contextValue}>{children}</YouVersionContext.Provider>
+    );
+  };
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    mockGetVersion.mockResolvedValue(mockVersion);
+
+    const mockClient: Partial<BibleClient> = { getVersion: mockGetVersion };
+    vi.mocked(useBibleClient).mockReturnValue(mockClient as BibleClient);
+  });
+
+  describe('fetching version', () => {
+    it('should fetch version by ID', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useVersion(111), { wrapper });
+
+      expect(result.current.loading).toBe(true);
+      expect(result.current.version).toBe(null);
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVersion).toHaveBeenCalledWith(111);
+      expect(result.current.version).toEqual(mockVersion);
+    });
+
+    it('should fetch different version by ID', async () => {
+      const mockKJV: BibleVersion = {
+        id: 1,
+        title: 'King James Version',
+        abbreviation: 'KJV',
+        localized_title: 'King James Version',
+        localized_abbreviation: 'KJV',
+        language_tag: 'en',
+        books: ['GEN', 'EXO', 'LEV'],
+        youversion_deep_link: 'https://bible.com/versions/1',
+      };
+      mockGetVersion.mockResolvedValueOnce(mockKJV);
+
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useVersion(1), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVersion).toHaveBeenCalledWith(1);
+      expect(result.current.version).toEqual(mockKJV);
+    });
+  });
+
+  describe('refetch behavior', () => {
+    it('should refetch when versionId changes', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result, rerender } = renderHook(({ versionId }) => useVersion(versionId), {
+        wrapper,
+        initialProps: { versionId: 111 },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetVersion).toHaveBeenNthCalledWith(1, 111);
+
+      rerender({ versionId: 1 });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVersion).toHaveBeenCalledTimes(2);
+      expect(mockGetVersion).toHaveBeenNthCalledWith(2, 1);
+    });
+  });
+
+  describe('enabled option', () => {
+    it('should not fetch when enabled is false', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useVersion(111, { enabled: false }), {
+        wrapper,
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVersion).not.toHaveBeenCalled();
+      expect(result.current.version).toBe(null);
+    });
+
+    it('should fetch when enabled is true', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useVersion(111, { enabled: true }), {
+        wrapper,
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVersion).toHaveBeenCalled();
+      expect(result.current.version).toEqual(mockVersion);
+    });
+
+    it('should fetch when enabled is not specified', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useVersion(111), {
+        wrapper,
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVersion).toHaveBeenCalled();
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle fetch errors', async () => {
+      const error = new Error('Failed to fetch version');
+      mockGetVersion.mockRejectedValueOnce(error);
+
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useVersion(111), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.version).toBe(null);
+    });
+
+    it('should clear error on successful refetch', async () => {
+      const error = new Error('Failed to fetch version');
+      mockGetVersion.mockRejectedValueOnce(error).mockResolvedValueOnce(mockVersion);
+
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useVersion(111), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+
+      act(() => {
+        result.current.refetch();
+      });
+
+      await waitFor(() => {
+        expect(result.current.error).toBe(null);
+      });
+
+      expect(result.current.version).toEqual(mockVersion);
+    });
+  });
+
+  describe('manual refetch', () => {
+    it('should support manual refetch', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useVersion(111), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetVersion).toHaveBeenCalledTimes(1);
+      expect(mockGetVersion).toHaveBeenNthCalledWith(1, 111);
+
+      act(() => {
+        result.current.refetch();
+      });
+
+      await waitFor(() => {
+        expect(mockGetVersion).toHaveBeenCalledTimes(2);
+      });
+
+      expect(mockGetVersion).toHaveBeenNthCalledWith(2, 111);
+    });
+  });
+});