@youversion/platform-react-hooks 1.12.2 → 1.14.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @youversion/platform-react-hooks@1.12.2 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/hooks
+> @youversion/platform-react-hooks@1.14.0 build /home/runner/work/platform-sdk-react/platform-sdk-react/packages/hooks
 > tsc -p tsconfig.build.json
 

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @youversion/platform-react-hooks
 
+## 1.14.0
+
+### Minor Changes
+
+- 2d2c597: Added 'system' as an option to YouVersionProvider theme prop that resolves via `prefers-color-scheme` with live OS change listener
+
+### Patch Changes
+
+- Updated dependencies [2d2c597]
+  - @youversion/platform-core@1.14.0
+
+## 1.13.0
+
+### Minor Changes
+
+- d5579d5: Add suggested languages to Bible version picker
+  - Auto-detect user's preferred language from browser settings instead of defaulting to English
+  - Display suggested languages based on available Bible versions and user locale
+  - Fetch complete language data with display names for better internationalization
+  - Add integration tests and Storybook stories for suggested languages functionality
+
+### Patch Changes
+
+- Updated dependencies [d5579d5]
+  - @youversion/platform-core@1.13.0
+
 ## 1.12.2
 
 ### Patch Changes

package/dist/context/YouVersionProvider.d.ts

@@ -3,7 +3,7 @@ interface YouVersionProviderPropsBase {
     children: ReactNode;
     appKey: string;
     apiHost?: string;
-    theme?: 'light' | 'dark';
+    theme?: 'light' | 'dark' | 'system';
 }
 interface YouVersionProviderPropsWithAuth extends YouVersionProviderPropsBase {
     authRedirectUrl: string;

package/dist/context/YouVersionProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"YouVersionProvider.d.ts","sourceRoot":"","sources":["../../src/context/YouVersionProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAK1D,UAAU,2BAA2B;IACnC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B;AAED,UAAU,+BAAgC,SAAQ,2BAA2B;IAC3E,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,UAAU,kCAAmC,SAAQ,2BAA2B;IAC9E,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,eAAe,CAAC,EAAE,KAAK,CAAC;CACzB;AAID,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,iBAAiB,CAAC,+BAA+B,GAAG,kCAAkC,CAAC,GAC7F,KAAK,CAAC,YAAY,CAiDpB"}
+{"version":3,"file":"YouVersionProvider.d.ts","sourceRoot":"","sources":["../../src/context/YouVersionProvider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAK1D,UAAU,2BAA2B;IACnC,QAAQ,EAAE,SAAS,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;CACrC;AAED,UAAU,+BAAgC,SAAQ,2BAA2B;IAC3E,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,UAAU,kCAAmC,SAAQ,2BAA2B;IAC9E,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,eAAe,CAAC,EAAE,KAAK,CAAC;CACzB;AAgCD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,iBAAiB,CAAC,+BAA+B,GAAG,kCAAkC,CAAC,GAC7F,KAAK,CAAC,YAAY,CAkDpB"}

package/dist/context/YouVersionProvider.js

@@ -1,11 +1,37 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { lazy, Suspense, useEffect } from 'react';
+import { lazy, Suspense, useEffect, useState } from 'react';
 import { YouVersionContext } from './YouVersionContext';
 import { YouVersionPlatformConfiguration } from '@youversion/platform-core';
 const AuthProvider = lazy(() => import('./YouVersionAuthProvider'));
+function useResolvedTheme(theme) {
+    const [resolved, setResolved] = useState(() => {
+        if (theme !== 'system')
+            return theme;
+        if (typeof window === 'undefined')
+            return 'light';
+        return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    });
+    useEffect(() => {
+        if (theme !== 'system') {
+            setResolved(theme);
+            return;
+        }
+        if (typeof window === 'undefined')
+            return;
+        const mediaQueryList = window.matchMedia('(prefers-color-scheme: dark)');
+        setResolved(mediaQueryList.matches ? 'dark' : 'light');
+        const handler = (e) => {
+            setResolved(e.matches ? 'dark' : 'light');
+        };
+        mediaQueryList.addEventListener('change', handler);
+        return () => mediaQueryList.removeEventListener('change', handler);
+    }, [theme]);
+    return resolved;
+}
 export function YouVersionProvider(props) {
     const { appKey, apiHost = 'api.youversion.com', includeAuth, theme = 'light', children } = props;
+    const resolvedTheme = useResolvedTheme(theme);
     // Syncing appKey and apiHost to YouVersionPlatformConfiguration
     // so that this can be in sync with any other code that uses
     // the YouVersionPlatformConfiguration, of which a lot of our
@@ -21,7 +47,7 @@ export function YouVersionProvider(props) {
                 appKey,
                 apiHost,
                 installationId: YouVersionPlatformConfiguration.installationId,
-                theme,
+                theme: resolvedTheme,
                 authEnabled: !!includeAuth,
             }, children: _jsx(Suspense, { children: _jsx(AuthProvider, { config: { appKey, apiHost, redirectUri: authRedirectUrl }, children: children }) }) }));
     }
@@ -30,7 +56,7 @@ export function YouVersionProvider(props) {
             appKey,
             apiHost,
             installationId: YouVersionPlatformConfiguration.installationId,
-            theme,
+            theme: resolvedTheme,
             authEnabled: !!includeAuth,
         }, children: children }));
 }

package/dist/context/YouVersionProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"YouVersionProvider.js","sourceRoot":"","sources":["../../src/context/YouVersionProvider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAGb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,+BAA+B,EAAE,MAAM,2BAA2B,CAAC;AAmB5E,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC,CAAC;AAEpE,MAAM,UAAU,kBAAkB,CAChC,KAA8F;IAE9F,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,oBAAoB,EAAE,WAAW,EAAE,KAAK,GAAG,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAEjG,gEAAgE;IAChE,4DAA4D;IAC5D,6DAA6D;IAC7D,wCAAwC;IACxC,SAAS,CAAC,GAAG,EAAE;QACb,+BAA+B,CAAC,MAAM,GAAG,MAAM,CAAC;QAChD,+BAA+B,CAAC,OAAO,GAAG,OAAO,CAAC;IACpD,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEtB,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,EAAE,eAAe,EAAE,GAAG,KAAK,CAAC;QAElC,4EAA4E;QAC5E,OAAO,CACL,KAAC,iBAAiB,CAAC,QAAQ,IACzB,KAAK,EAAE;gBACL,MAAM;gBACN,OAAO;gBACP,cAAc,EAAE,+BAA+B,CAAC,cAAc;gBAC9D,KAAK;gBACL,WAAW,EAAE,CAAC,CAAC,WAAW;aAC3B,YAED,KAAC,QAAQ,cACP,KAAC,YAAY,IAAC,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,YACpE,QAAQ,GACI,GACN,GACgB,CAC9B,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,OAAO,CACL,KAAC,iBAAiB,CAAC,QAAQ,IACzB,KAAK,EAAE;YACL,MAAM;YACN,OAAO;YACP,cAAc,EAAE,+BAA+B,CAAC,cAAc;YAC9D,KAAK;YACL,WAAW,EAAE,CAAC,CAAC,WAAW;SAC3B,YAEA,QAAQ,GACkB,CAC9B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"YouVersionProvider.js","sourceRoot":"","sources":["../../src/context/YouVersionProvider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAGb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,+BAA+B,EAAE,MAAM,2BAA2B,CAAC;AAmB5E,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC,CAAC;AAEpE,SAAS,gBAAgB,CAAC,KAAkC;IAC1D,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAmB,GAAG,EAAE;QAC9D,IAAI,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACrC,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO,OAAO,CAAC;QAClD,OAAO,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACtF,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvB,WAAW,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO;QACT,CAAC;QAED,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,OAAO;QAE1C,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC;QACzE,WAAW,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAEvD,MAAM,OAAO,GAAG,CAAC,CAAsB,EAAE,EAAE;YACzC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC5C,CAAC,CAAC;QACF,cAAc,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACnD,OAAO,GAAG,EAAE,CAAC,cAAc,CAAC,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,KAA8F;IAE9F,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,oBAAoB,EAAE,WAAW,EAAE,KAAK,GAAG,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IACjG,MAAM,aAAa,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAE9C,gEAAgE;IAChE,4DAA4D;IAC5D,6DAA6D;IAC7D,wCAAwC;IACxC,SAAS,CAAC,GAAG,EAAE;QACb,+BAA+B,CAAC,MAAM,GAAG,MAAM,CAAC;QAChD,+BAA+B,CAAC,OAAO,GAAG,OAAO,CAAC;IACpD,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEtB,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,EAAE,eAAe,EAAE,GAAG,KAAK,CAAC;QAElC,4EAA4E;QAC5E,OAAO,CACL,KAAC,iBAAiB,CAAC,QAAQ,IACzB,KAAK,EAAE;gBACL,MAAM;gBACN,OAAO;gBACP,cAAc,EAAE,+BAA+B,CAAC,cAAc;gBAC9D,KAAK,EAAE,aAAa;gBACpB,WAAW,EAAE,CAAC,CAAC,WAAW;aAC3B,YAED,KAAC,QAAQ,cACP,KAAC,YAAY,IAAC,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,YACpE,QAAQ,GACI,GACN,GACgB,CAC9B,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,OAAO,CACL,KAAC,iBAAiB,CAAC,QAAQ,IACzB,KAAK,EAAE;YACL,MAAM;YACN,OAAO;YACP,cAAc,EAAE,+BAA+B,CAAC,cAAc;YAC9D,KAAK,EAAE,aAAa;YACpB,WAAW,EAAE,CAAC,CAAC,WAAW;SAC3B,YAEA,QAAQ,GACkB,CAC9B,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-react-hooks",
-  "version": "1.12.2",
+  "version": "1.14.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@youversion/platform-core": "1.12.2"
+    "@youversion/platform-core": "1.14.0"
   },
   "peerDependencies": {
     "react": ">=19.1.0 <20.0.0"

package/src/context/YouVersionProvider.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import type { PropsWithChildren, ReactNode } from 'react';
-import { lazy, Suspense, useEffect } from 'react';
+import { lazy, Suspense, useEffect, useState } from 'react';
 import { YouVersionContext } from './YouVersionContext';
 import { YouVersionPlatformConfiguration } from '@youversion/platform-core';
 
@@ -9,7 +9,7 @@ interface YouVersionProviderPropsBase {
   children: ReactNode;
   appKey: string;
   apiHost?: string;
-  theme?: 'light' | 'dark';
+  theme?: 'light' | 'dark' | 'system';
 }
 
 interface YouVersionProviderPropsWithAuth extends YouVersionProviderPropsBase {
@@ -24,10 +24,39 @@ interface YouVersionProviderPropsWithoutAuth extends YouVersionProviderPropsBase
 
 const AuthProvider = lazy(() => import('./YouVersionAuthProvider'));
 
+function useResolvedTheme(theme: 'light' | 'dark' | 'system'): 'light' | 'dark' {
+  const [resolved, setResolved] = useState<'light' | 'dark'>(() => {
+    if (theme !== 'system') return theme;
+    if (typeof window === 'undefined') return 'light';
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  });
+
+  useEffect(() => {
+    if (theme !== 'system') {
+      setResolved(theme);
+      return;
+    }
+
+    if (typeof window === 'undefined') return;
+
+    const mediaQueryList = window.matchMedia('(prefers-color-scheme: dark)');
+    setResolved(mediaQueryList.matches ? 'dark' : 'light');
+
+    const handler = (e: MediaQueryListEvent) => {
+      setResolved(e.matches ? 'dark' : 'light');
+    };
+    mediaQueryList.addEventListener('change', handler);
+    return () => mediaQueryList.removeEventListener('change', handler);
+  }, [theme]);
+
+  return resolved;
+}
+
 export function YouVersionProvider(
   props: PropsWithChildren<YouVersionProviderPropsWithAuth | YouVersionProviderPropsWithoutAuth>,
 ): React.ReactElement {
   const { appKey, apiHost = 'api.youversion.com', includeAuth, theme = 'light', children } = props;
+  const resolvedTheme = useResolvedTheme(theme);
 
   // Syncing appKey and apiHost to YouVersionPlatformConfiguration
   // so that this can be in sync with any other code that uses
@@ -48,7 +77,7 @@ export function YouVersionProvider(
           appKey,
           apiHost,
           installationId: YouVersionPlatformConfiguration.installationId,
-          theme,
+          theme: resolvedTheme,
           authEnabled: !!includeAuth,
         }}
       >
@@ -68,7 +97,7 @@ export function YouVersionProvider(
         appKey,
         apiHost,
         installationId: YouVersionPlatformConfiguration.installationId,
-        theme,
+        theme: resolvedTheme,
         authEnabled: !!includeAuth,
       }}
     >

package/src/useChapter.test.tsx

@@ -0,0 +1,228 @@
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ReactNode } from 'react';
+import { useChapter } from './useChapter';
+import { YouVersionContext } from './context';
+import { type BibleClient, type BibleChapter } from '@youversion/platform-core';
+import { useBibleClient } from './useBibleClient';
+
+vi.mock('./useBibleClient');
+
+describe('useChapter', () => {
+  const mockAppKey = 'test-app-key';
+  const mockGetChapter = vi.fn();
+
+  const mockChapter: BibleChapter = {
+    id: '1',
+    passage_id: 'MAT.1',
+    title: 'Matthew 1',
+  };
+
+  const createWrapper = (contextValue: { appKey: string }) => {
+    return ({ children }: { children: ReactNode }) => (
+      <YouVersionContext.Provider value={contextValue}>{children}</YouVersionContext.Provider>
+    );
+  };
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    mockGetChapter.mockResolvedValue(mockChapter);
+
+    const mockClient: Partial<BibleClient> = { getChapter: mockGetChapter };
+    vi.mocked(useBibleClient).mockReturnValue(mockClient as BibleClient);
+  });
+
+  describe('fetching chapter', () => {
+    it('should fetch chapter with versionId, book, chapter params', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapter(111, 'MAT', 1), { wrapper });
+
+      expect(result.current.loading).toBe(true);
+      expect(result.current.chapter).toBe(null);
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).toHaveBeenCalledWith(111, 'MAT', 1);
+      expect(result.current.chapter).toEqual(mockChapter);
+    });
+
+    it('should refetch when versionId changes', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result, rerender } = renderHook(({ versionId }) => useChapter(versionId, 'MAT', 1), {
+        wrapper,
+        initialProps: { versionId: 1 },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).toHaveBeenCalledTimes(1);
+      expect(mockGetChapter).toHaveBeenLastCalledWith(1, 'MAT', 1);
+
+      act(() => {
+        rerender({ versionId: 111 });
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).toHaveBeenCalledTimes(2);
+      expect(mockGetChapter).toHaveBeenLastCalledWith(111, 'MAT', 1);
+    });
+
+    it('should refetch when book changes', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result, rerender } = renderHook(({ book }) => useChapter(1, book, 1), {
+        wrapper,
+        initialProps: { book: 'MAT' },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).toHaveBeenCalledTimes(1);
+      expect(mockGetChapter).toHaveBeenLastCalledWith(1, 'MAT', 1);
+
+      act(() => {
+        rerender({ book: 'GEN' });
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).toHaveBeenCalledTimes(2);
+      expect(mockGetChapter).toHaveBeenLastCalledWith(1, 'GEN', 1);
+    });
+
+    it('should refetch when chapter changes', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result, rerender } = renderHook(({ chapter }) => useChapter(1, 'MAT', chapter), {
+        wrapper,
+        initialProps: { chapter: 1 },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).toHaveBeenCalledTimes(1);
+      expect(mockGetChapter).toHaveBeenLastCalledWith(1, 'MAT', 1);
+
+      act(() => {
+        rerender({ chapter: 5 });
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).toHaveBeenCalledTimes(2);
+      expect(mockGetChapter).toHaveBeenLastCalledWith(1, 'MAT', 5);
+    });
+
+    it('should not fetch when enabled is false', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapter(1, 'MAT', 1, { enabled: false }), {
+        wrapper,
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).not.toHaveBeenCalled();
+      expect(result.current.chapter).toBe(null);
+    });
+
+    it('should handle fetch errors', async () => {
+      const error = new Error('Failed to fetch chapter');
+      mockGetChapter.mockRejectedValueOnce(error);
+
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapter(1, 'MAT', 1), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.chapter).toBe(null);
+    });
+
+    it('should clear error on successful refetch', async () => {
+      const error = new Error('Failed to fetch chapter');
+      mockGetChapter.mockRejectedValueOnce(error).mockResolvedValueOnce(mockChapter);
+
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapter(1, 'MAT', 1), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.chapter).toBe(null);
+
+      act(() => {
+        result.current.refetch();
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toBe(null);
+      expect(result.current.chapter).toEqual(mockChapter);
+    });
+
+    it('should support manual refetch', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapter(1, 'MAT', 1), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapter).toHaveBeenCalledTimes(1);
+
+      act(() => {
+        result.current.refetch();
+      });
+
+      await waitFor(() => {
+        expect(mockGetChapter).toHaveBeenCalledTimes(2);
+      });
+    });
+  });
+});

package/src/useChapters.test.tsx

@@ -0,0 +1,278 @@
+import { renderHook, waitFor, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { ReactNode } from 'react';
+import { useChapters } from './useChapters';
+import { YouVersionContext } from './context';
+import { type BibleClient, type BibleChapter, type Collection } from '@youversion/platform-core';
+import { useBibleClient } from './useBibleClient';
+
+vi.mock('./useBibleClient');
+
+describe('useChapters', () => {
+  const mockAppKey = 'test-app-key';
+  const mockGetChapters = vi.fn();
+
+  const mockChapters: Collection<BibleChapter> = {
+    data: [
+      { id: '1', passage_id: 'MAT.1.1', title: 'Matthew 1' },
+      { id: '2', passage_id: 'MAT.1.2', title: 'Matthew 2' },
+      { id: '3', passage_id: 'MAT.1.3', title: 'Matthew 3' },
+    ],
+    next_page_token: null,
+  };
+
+  const createWrapper = (contextValue: { appKey: string }) => {
+    return ({ children }: { children: ReactNode }) => (
+      <YouVersionContext.Provider value={contextValue}>{children}</YouVersionContext.Provider>
+    );
+  };
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+
+    mockGetChapters.mockResolvedValue(mockChapters);
+
+    const mockClient: Partial<BibleClient> = { getChapters: mockGetChapters };
+    vi.mocked(useBibleClient).mockReturnValue(mockClient as BibleClient);
+  });
+
+  describe('fetching chapters', () => {
+    it('should fetch chapters with versionId, book params', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapters(111, 'MAT'), { wrapper });
+
+      expect(result.current.loading).toBe(true);
+      expect(result.current.chapters).toBe(null);
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).toHaveBeenCalledWith(111, 'MAT');
+      expect(result.current.chapters).toEqual(mockChapters);
+    });
+
+    it('should refetch when versionId changes', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result, rerender } = renderHook(({ versionId }) => useChapters(versionId, 'MAT'), {
+        wrapper,
+        initialProps: { versionId: 1 },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).toHaveBeenCalledTimes(1);
+      expect(mockGetChapters).toHaveBeenLastCalledWith(1, 'MAT');
+
+      act(() => {
+        rerender({ versionId: 111 });
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).toHaveBeenCalledTimes(2);
+      expect(mockGetChapters).toHaveBeenLastCalledWith(111, 'MAT');
+    });
+
+    it('should refetch when book changes', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result, rerender } = renderHook(({ book }) => useChapters(1, book), {
+        wrapper,
+        initialProps: { book: 'MAT' },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).toHaveBeenCalledTimes(1);
+      expect(mockGetChapters).toHaveBeenLastCalledWith(1, 'MAT');
+
+      act(() => {
+        rerender({ book: 'GEN' });
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).toHaveBeenCalledTimes(2);
+      expect(mockGetChapters).toHaveBeenLastCalledWith(1, 'GEN');
+    });
+
+    it('should not fetch when enabled is false', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapters(1, 'MAT', { enabled: false }), {
+        wrapper,
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).not.toHaveBeenCalled();
+      expect(result.current.chapters).toBe(null);
+    });
+
+    it('should handle fetch errors', async () => {
+      const error = new Error('Failed to fetch chapters');
+      mockGetChapters.mockRejectedValueOnce(error);
+
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapters(1, 'MAT'), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.chapters).toBe(null);
+    });
+
+    it('should clear error on successful refetch', async () => {
+      const error = new Error('Failed to fetch chapters');
+      mockGetChapters.mockRejectedValueOnce(error).mockResolvedValueOnce(mockChapters);
+
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapters(1, 'MAT'), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toEqual(error);
+      expect(result.current.chapters).toBe(null);
+
+      act(() => {
+        result.current.refetch();
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(result.current.error).toBe(null);
+      expect(result.current.chapters).toEqual(mockChapters);
+    });
+
+    it('should support manual refetch', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapters(1, 'MAT'), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).toHaveBeenCalledTimes(1);
+
+      act(() => {
+        result.current.refetch();
+      });
+
+      await waitFor(() => {
+        expect(mockGetChapters).toHaveBeenCalledTimes(2);
+      });
+    });
+  });
+
+  describe('book validation', () => {
+    it('should skip fetch when book is "undefined" string', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapters(1, 'undefined'), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).not.toHaveBeenCalled();
+      expect(result.current.chapters).toBe(null);
+    });
+
+    it('should skip fetch when book is "null" string', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapters(1, 'null'), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).not.toHaveBeenCalled();
+      expect(result.current.chapters).toBe(null);
+    });
+
+    it('should skip fetch when book is empty string', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result } = renderHook(() => useChapters(1, ''), { wrapper });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).not.toHaveBeenCalled();
+      expect(result.current.chapters).toBe(null);
+    });
+
+    it('should fetch when book changes from invalid to valid', async () => {
+      const wrapper = createWrapper({
+        appKey: mockAppKey,
+      });
+
+      const { result, rerender } = renderHook(({ book }) => useChapters(1, book), {
+        wrapper,
+        initialProps: { book: 'undefined' },
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).not.toHaveBeenCalled();
+
+      act(() => {
+        rerender({ book: 'MAT' });
+      });
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false);
+      });
+
+      expect(mockGetChapters).toHaveBeenCalledTimes(1);
+      expect(mockGetChapters).toHaveBeenCalledWith(1, 'MAT');
+      expect(result.current.chapters).toEqual(mockChapters);
+    });
+  });
+});

package/src/useVersion.test.tsx

@@ -206,9 +206,11 @@ describe('useVersion', () => {
       });
 
       await waitFor(() => {
+        expect(result.current.loading).toBe(false);
         expect(result.current.error).toBe(null);
       });
 
+      expect(result.current.error).toBe(null);
       expect(result.current.version).toEqual(mockVersion);
     });
   });

package/src/useVersions.test.tsx

@@ -605,9 +605,11 @@ describe('useVersions', () => {
       });
 
       await waitFor(() => {
+        expect(result.current.loading).toBe(false);
         expect(result.current.error).toBe(null);
       });
 
+      expect(result.current.error).toBe(null);
       expect(result.current.versions).toEqual(mockVersions);
     });
   });