@youversion/platform-react-hooks 0.4.1

package/src/useBibleClient.test.tsx

@@ -0,0 +1,151 @@
+import { renderHook } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ReactNode } from 'react';
+import { useBibleClient } from './useBibleClient';
+import { BibleSDKContext } from './context';
+import { BibleClient, ApiClient } from '@youversion/platform-core';
+
+vi.mock('@youversion/platform-core', async () => {
+  const actual = await vi.importActual('@youversion/platform-core');
+  return {
+    ...actual,
+    BibleClient: vi.fn(function () {
+      return {
+        isBibleClient: true,
+      };
+    }),
+    ApiClient: vi.fn(function () {
+      return {
+        isApiClient: true,
+      };
+    }),
+    YouVersionPlatformConfiguration: {
+      get installationId() {
+        return 'auto-generated-uuid';
+      },
+    },
+  };
+});
+
+describe('useBibleClient', () => {
+  const mockAppId = 'test-app-id';
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should create and return a BibleClient instance when context is valid', () => {
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <BibleSDKContext.Provider
+        value={{
+          appId: mockAppId,
+        }}
+      >
+        {children}
+      </BibleSDKContext.Provider>
+    );
+
+    const { result } = renderHook(() => useBibleClient(), { wrapper });
+
+    expect(ApiClient).toHaveBeenCalledWith({
+      appId: mockAppId,
+      installationId: 'auto-generated-uuid',
+    });
+    expect(BibleClient).toHaveBeenCalledWith(expect.objectContaining({ isApiClient: true }));
+    expect(result.current).toEqual(expect.objectContaining({ isBibleClient: true }));
+  });
+
+  it('should throw error when context is not provided', () => {
+    expect(() => renderHook(() => useBibleClient())).toThrow(
+      'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+    );
+  });
+
+  it('should throw error when appId is missing', () => {
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <BibleSDKContext.Provider
+        value={{
+          appId: '',
+        }}
+      >
+        {children}
+      </BibleSDKContext.Provider>
+    );
+
+    expect(() => renderHook(() => useBibleClient(), { wrapper })).toThrow(
+      'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+    );
+  });
+
+  it('should memoize the BibleClient instance', () => {
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <BibleSDKContext.Provider
+        value={{
+          appId: mockAppId,
+        }}
+      >
+        {children}
+      </BibleSDKContext.Provider>
+    );
+
+    const { result, rerender } = renderHook(() => useBibleClient(), { wrapper });
+    const firstClient = result.current;
+
+    rerender();
+    const secondClient = result.current;
+
+    expect(firstClient).toBe(secondClient);
+    expect(BibleClient).toHaveBeenCalledTimes(1);
+  });
+
+  it('should create new BibleClient when appId changes', () => {
+    let currentAppId = mockAppId;
+
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <BibleSDKContext.Provider
+        value={{
+          appId: currentAppId,
+        }}
+      >
+        {children}
+      </BibleSDKContext.Provider>
+    );
+
+    const { result, rerender } = renderHook(() => useBibleClient(), { wrapper });
+
+    const firstClient = result.current;
+    expect(BibleClient).toHaveBeenCalledTimes(1);
+    expect(ApiClient).toHaveBeenCalledWith({
+      appId: mockAppId,
+      installationId: 'auto-generated-uuid',
+    });
+
+    currentAppId = 'new-app-id';
+    rerender();
+
+    const secondClient = result.current;
+    expect(BibleClient).toHaveBeenCalledTimes(2);
+    expect(firstClient).not.toBe(secondClient);
+
+    expect(ApiClient).toHaveBeenLastCalledWith({
+      appId: 'new-app-id',
+      installationId: 'auto-generated-uuid',
+    });
+  });
+
+  it('should throw error when appId is null', () => {
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <BibleSDKContext.Provider
+        value={{
+          appId: null as unknown as string,
+        }}
+      >
+        {children}
+      </BibleSDKContext.Provider>
+    );
+
+    expect(() => renderHook(() => useBibleClient(), { wrapper })).toThrow(
+      'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+    );
+  });
+});

package/src/useBibleClient.ts

@@ -0,0 +1,22 @@
+'use client';
+
+import { useContext, useMemo } from 'react';
+import { BibleSDKContext } from './context';
+import { BibleClient, ApiClient, YouVersionPlatformConfiguration } from '@youversion/platform-core';
+
+export function useBibleClient(): BibleClient {
+  const context = useContext(BibleSDKContext);
+  return useMemo(() => {
+    if (!context?.appId) {
+      throw new Error(
+        'BibleSDK context not found. Make sure your component is wrapped with BibleSDKProvider and an API key is provided.',
+      );
+    }
+    return new BibleClient(
+      new ApiClient({
+        appId: context.appId,
+        installationId: YouVersionPlatformConfiguration.installationId,
+      }),
+    );
+  }, [context?.appId]);
+}

package/src/useBook.ts

@@ -0,0 +1,28 @@
+'use client';
+
+import { useBibleClient } from './useBibleClient';
+import { useApiData, type UseApiDataOptions } from './useApiData';
+import type { BibleBook } from '@youversion/platform-core';
+
+export function useBook(
+  versionId: number,
+  book: string,
+  options?: UseApiDataOptions,
+): {
+  book: BibleBook | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const bibleClient = useBibleClient();
+
+  const { data, loading, error, refetch } = useApiData<BibleBook>(
+    () => bibleClient.getBook(versionId, book),
+    [bibleClient, versionId, book],
+    {
+      enabled: options?.enabled !== false,
+    },
+  );
+
+  return { book: data, loading, error, refetch };
+}

package/src/useBooks.ts

@@ -0,0 +1,31 @@
+'use client';
+import { useBibleClient } from './useBibleClient';
+import { useApiData, type UseApiDataOptions } from './useApiData';
+import type { BibleBook, Collection } from '@youversion/platform-core';
+
+export function useBooks(
+  versionId: number,
+  options?: UseApiDataOptions,
+): {
+  books: Collection<BibleBook> | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const bibleClient = useBibleClient();
+
+  const {
+    data: books,
+    loading,
+    error,
+    refetch,
+  } = useApiData<Collection<BibleBook>>(
+    () => bibleClient.getBooks(versionId),
+    [bibleClient, versionId],
+    {
+      enabled: options?.enabled !== false,
+    },
+  );
+
+  return { books, loading, error, refetch };
+}

package/src/useChapter.ts

@@ -0,0 +1,33 @@
+'use client';
+import { useBibleClient } from './useBibleClient';
+import { useApiData, type UseApiDataOptions } from './useApiData';
+import type { BibleChapter } from '@youversion/platform-core';
+
+export function useChapter(
+  versionId: number,
+  book: string,
+  chapter: number,
+  options?: UseApiDataOptions,
+): {
+  chapter: BibleChapter | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const bibleClient = useBibleClient();
+
+  const {
+    data: chapterData,
+    loading,
+    error,
+    refetch,
+  } = useApiData<BibleChapter>(
+    () => bibleClient.getChapter(versionId, book, chapter),
+    [bibleClient, versionId, book, chapter],
+    {
+      enabled: options?.enabled !== false,
+    },
+  );
+
+  return { chapter: chapterData, loading, error, refetch };
+}

package/src/useChapterNavigation.ts

@@ -0,0 +1,77 @@
+import { useReaderContext } from './context/ReaderContext';
+import { useChapters } from './useChapters';
+
+interface UseChapterNavigationResult {
+  canNavigatePrevious: boolean;
+  canNavigateNext: boolean;
+  navigateToPrevious: () => void;
+  navigateToNext: () => void;
+  currentChapterIndex: number;
+  isLoading: boolean;
+}
+
+/**
+ * Provides navigation functionality for chapters within a book, allowing the user to move
+ * to the previous or next chapter, as well as access additional chapter navigation metadata.
+ *
+ * @return {UseChapterNavigationResult} An object containing properties and methods for chapter navigation:
+ * - `canNavigatePrevious` (boolean): Indicates whether navigating to the previous chapter is possible.
+ * - `canNavigateNext` (boolean): Indicates whether navigating to the next chapter is possible.
+ * - `navigateToPrevious` (function): Moves to the previous chapter if possible.
+ * - `navigateToNext` (function): Moves to the next chapter if possible.
+ * - `currentChapterIndex` (number): The index of the current chapter within the list of chapters.
+ * - `isLoading` (boolean): Whether the chapter data is still loading.
+ */
+export function useChapterNavigation(): UseChapterNavigationResult {
+  const { currentChapter, currentVersion, currentBook, setChapter } = useReaderContext();
+
+  const bookIdentifier = currentBook?.id ?? '';
+
+  const { chapters, loading: chaptersLoading } = useChapters(
+    currentVersion?.id ?? 0,
+    bookIdentifier,
+    { enabled: Boolean(bookIdentifier && currentVersion?.id) },
+  );
+
+  const currentChapterIndex = chapters?.data.findIndex((c) => c.id === currentChapter.id) ?? -1;
+
+  const canNavigatePrevious = Boolean(
+    !chaptersLoading && chapters?.data && currentChapterIndex !== -1 && currentChapterIndex > 0,
+  );
+
+  const canNavigateNext = Boolean(
+    !chaptersLoading &&
+      chapters?.data &&
+      currentChapterIndex !== -1 &&
+      currentChapterIndex < chapters.data.length - 1,
+  );
+
+  const navigateToPrevious = () => {
+    if (canNavigatePrevious && chapters?.data) {
+      const previousChapter = chapters.data[currentChapterIndex - 1];
+      if (previousChapter) {
+        // Use the chapter as-is since it already has all required fields
+        setChapter(previousChapter);
+      }
+    }
+  };
+
+  const navigateToNext = () => {
+    if (canNavigateNext && chapters?.data) {
+      const nextChapter = chapters.data[currentChapterIndex + 1];
+      if (nextChapter) {
+        // Use the chapter as-is since it already has all required fields
+        setChapter(nextChapter);
+      }
+    }
+  };
+
+  return {
+    canNavigatePrevious,
+    canNavigateNext,
+    navigateToPrevious,
+    navigateToNext,
+    currentChapterIndex,
+    isLoading: chaptersLoading,
+  };
+}

package/src/useChapters.ts

@@ -0,0 +1,36 @@
+'use client';
+
+import { useBibleClient } from './useBibleClient';
+import { useApiData, type UseApiDataOptions } from './useApiData';
+import type { BibleChapter, Collection } from '@youversion/platform-core';
+
+export function useChapters(
+  versionId: number,
+  book: string,
+  options?: UseApiDataOptions,
+): {
+  chapters: Collection<BibleChapter> | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const bibleClient = useBibleClient();
+
+  // Don't attempt to fetch if book is invalid
+  const isValidBook = Boolean(book) && book !== 'undefined' && book !== 'null';
+
+  const {
+    data: chapters,
+    loading,
+    error,
+    refetch,
+  } = useApiData<Collection<BibleChapter>>(
+    () => bibleClient.getChapters(versionId, book),
+    [bibleClient, versionId, book],
+    {
+      enabled: options?.enabled !== false && isValidBook,
+    },
+  );
+
+  return { chapters, loading, error, refetch };
+}

package/src/useFilteredVersions.test.tsx

@@ -0,0 +1,248 @@
+import { renderHook } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import type { BibleVersion } from '@youversion/platform-core';
+import { useFilteredVersions } from './useFilteredVersions';
+
+const mockVersions: BibleVersion[] = [
+  {
+    id: 1,
+    title: 'King James Version',
+    abbreviation: 'KJV',
+    copyright_short: '',
+    copyright_long: '',
+    info: null,
+    publisher_url: null,
+    language_tag: 'en',
+    local_abbreviation: 'KJV',
+    local_title: 'King James Version',
+    books: [],
+    youversion_deep_link: 'https://www.bible.com/versions/1',
+  },
+  {
+    id: 2,
+    title: 'New International Version',
+    abbreviation: 'NIV',
+    copyright_short: '',
+    copyright_long: '',
+    info: null,
+    publisher_url: null,
+    language_tag: 'en',
+    local_abbreviation: 'NIV',
+    local_title: 'New International Version',
+    books: [],
+    youversion_deep_link: 'https://www.bible.com/versions/2',
+  },
+  {
+    id: 3,
+    title: 'Reina-Valera 1960',
+    abbreviation: 'RVR1960',
+    copyright_short: '',
+    copyright_long: '',
+    info: null,
+    publisher_url: null,
+    language_tag: 'es',
+    local_abbreviation: 'RVR1960',
+    local_title: 'Reina-Valera 1960',
+    books: [],
+    youversion_deep_link: 'https://www.bible.com/versions/3',
+  },
+  {
+    id: 4,
+    title: 'Nueva Versión Internacional',
+    abbreviation: 'NVI',
+    copyright_short: '',
+    copyright_long: '',
+    info: null,
+    publisher_url: null,
+    language_tag: 'es',
+    local_abbreviation: 'NVI',
+    local_title: 'Nueva Versión Internacional',
+    books: [],
+    youversion_deep_link: 'https://www.bible.com/versions/4',
+  },
+  {
+    id: 5,
+    title: 'La Bible du Semeur',
+    abbreviation: 'BDS',
+    copyright_short: '',
+    copyright_long: '',
+    info: null,
+    publisher_url: null,
+    language_tag: 'fr',
+    local_abbreviation: 'BDS',
+    local_title: 'La Bible du Semeur',
+    books: [],
+    youversion_deep_link: 'https://www.bible.com/versions/5',
+  },
+];
+
+describe('useFilteredVersions', () => {
+  describe('language filtering', () => {
+    it('should return all versions when language is "*"', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '', '*'));
+
+      expect(result.current).toEqual(mockVersions);
+      expect(result.current).toHaveLength(5);
+    });
+
+    it('should filter versions by language_tag', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '', 'en'));
+
+      expect(result.current).toHaveLength(2);
+      expect(result.current.every((v) => v.language_tag === 'en')).toBe(true);
+    });
+
+    it('should filter versions by language_tag (Spanish)', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '', 'es'));
+
+      expect(result.current).toHaveLength(2);
+      expect(result.current.every((v) => v.language_tag === 'es')).toBe(true);
+    });
+
+    it('should handle case-insensitive language matching', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '', 'EN'));
+
+      expect(result.current).toHaveLength(2);
+      expect(result.current.every((v) => v.language_tag === 'en')).toBe(true);
+    });
+
+    it('should return empty array when language matches no versions', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '', 'de'));
+
+      expect(result.current).toEqual([]);
+    });
+  });
+
+  describe('search term filtering', () => {
+    it('should return all versions when search term is empty', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '', '*'));
+
+      expect(result.current).toEqual(mockVersions);
+    });
+
+    it('should return all versions when search term is whitespace only', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '   ', '*'));
+
+      expect(result.current).toEqual(mockVersions);
+    });
+
+    it('should filter by title', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'King', '*'));
+
+      expect(result.current).toHaveLength(1);
+      expect(result.current[0]?.title).toBe('King James Version');
+    });
+
+    it('should filter by abbreviation', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'NIV', '*'));
+
+      expect(result.current).toHaveLength(1);
+      expect(result.current[0]?.abbreviation).toBe('NIV');
+    });
+
+    it('should filter by language_tag', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'fr', '*'));
+
+      expect(result.current).toHaveLength(1);
+      expect(result.current[0]?.language_tag).toBe('fr');
+    });
+
+    it('should be case-insensitive', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'KING', '*'));
+
+      expect(result.current).toHaveLength(1);
+      expect(result.current[0]?.title).toBe('King James Version');
+    });
+
+    it('should find partial matches', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'Version', '*'));
+
+      expect(result.current).toHaveLength(2);
+      expect(result.current[0]?.title).toBe('King James Version');
+      expect(result.current[1]?.title).toBe('New International Version');
+    });
+
+    it('should return empty array when no matches found', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'xyz', '*'));
+
+      expect(result.current).toEqual([]);
+    });
+  });
+
+  describe('combined filtering', () => {
+    it('should filter by both language and search term', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'International', 'en'));
+
+      expect(result.current).toHaveLength(1);
+      expect(result.current[0]?.abbreviation).toBe('NIV');
+      expect(result.current[0]?.language_tag).toBe('en');
+    });
+
+    it('should return empty array when language matches but search term does not', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'Reina', 'en'));
+
+      expect(result.current).toEqual([]);
+    });
+
+    it('should return empty array when search term matches but language does not', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'King', 'es'));
+
+      expect(result.current).toEqual([]);
+    });
+
+    it('should filter Spanish versions by search term', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, 'Reina', 'es'));
+
+      expect(result.current).toHaveLength(1);
+      expect(result.current[0]?.abbreviation).toBe('RVR1960');
+    });
+  });
+
+  describe('memoization', () => {
+    it('should return the same reference when inputs do not change', () => {
+      const { result, rerender } = renderHook(
+        ({ versions, searchTerm, language }) => useFilteredVersions(versions, searchTerm, language),
+        {
+          initialProps: {
+            versions: mockVersions,
+            searchTerm: 'King',
+            language: 'en',
+          },
+        },
+      );
+
+      const firstResult = result.current;
+
+      rerender({
+        versions: mockVersions,
+        searchTerm: 'King',
+        language: 'en',
+      });
+
+      expect(result.current).toBe(firstResult);
+    });
+
+    it('should return a new reference when inputs change', () => {
+      const { result, rerender } = renderHook(
+        ({ versions, searchTerm, language }) => useFilteredVersions(versions, searchTerm, language),
+        {
+          initialProps: {
+            versions: mockVersions,
+            searchTerm: 'King',
+            language: 'en',
+          },
+        },
+      );
+
+      const firstResult = result.current;
+
+      rerender({
+        versions: mockVersions,
+        searchTerm: 'International',
+        language: 'en',
+      });
+
+      expect(result.current).not.toBe(firstResult);
+    });
+  });
+});

package/src/useFilteredVersions.ts

@@ -0,0 +1,38 @@
+'use client';
+
+import type { BibleVersion } from '@youversion/platform-core';
+import { useMemo } from 'react';
+import { getISOFromVersion } from './utility/version';
+
+/**
+ * Custom hook to filter versions based on search term
+ */
+export function useFilteredVersions(
+  versions: BibleVersion[],
+  searchTerm: string,
+  selectedLanguage: string,
+): BibleVersion[] {
+  return useMemo(() => {
+    let result = [...versions];
+
+    // Language filter
+    if (selectedLanguage && selectedLanguage !== '*') {
+      result = result.filter(
+        (version) => getISOFromVersion(version).toLowerCase() === selectedLanguage.toLowerCase(),
+      );
+    }
+
+    // Search filter
+    if (searchTerm.trim()) {
+      const searchLower = searchTerm.toLowerCase();
+      result = result.filter(
+        (version) =>
+          version.title.toLowerCase().includes(searchLower) ||
+          version.abbreviation.toLowerCase().includes(searchLower) ||
+          getISOFromVersion(version).toLowerCase().includes(searchLower),
+      );
+    }
+
+    return result;
+  }, [versions, searchTerm, selectedLanguage]);
+}