@youversion/platform-react-hooks 1.16.0 → 1.18.0

package/.turbo/turbo-build.log

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

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @youversion/platform-react-hooks
 
+## 1.18.0
+
+### Minor Changes
+
+- b8c6e1b: In our BibleCard component, we've added an error UI to make it more clear when an error has occurred fetching the Bible verse.
+
+### Patch Changes
+
+- Updated dependencies [b8c6e1b]
+  - @youversion/platform-core@1.18.0
+
+## 1.17.1
+
+### Patch Changes
+
+- a7100fd: We've added support for footnotes in Bible book introduction chapters. This is a rare occurance, but an example can be found in Joshua's introduction chapter when using the TPT Bible Version
+- Updated dependencies [a7100fd]
+  - @youversion/platform-core@1.17.1
+
+## 1.17.0
+
+### Minor Changes
+
+- c3d673e: added error ui for faild verses
+
+### Patch Changes
+
+- a5f91bf: Add cross-book chapter navigation to Bible Reader toolbar with prev/next buttons, intro chapter support, and accessible aria-labels
+- Updated dependencies [a5f91bf]
+- Updated dependencies [c3d673e]
+  - @youversion/platform-core@1.17.0
+
 ## 1.16.0
 
 ### Minor Changes

package/dist/useChapterNavigation.d.ts

@@ -7,16 +7,8 @@ interface UseChapterNavigationResult {
     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.
+ * Provides navigation functionality for chapters across book boundaries,
+ * including intro chapter support.
  */
 export declare function useChapterNavigation(): UseChapterNavigationResult;
 export {};

package/dist/useChapterNavigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useChapterNavigation.d.ts","sourceRoot":"","sources":["../src/useChapterNavigation.ts"],"names":[],"mappings":"AAGA,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,IAAI,0BAA0B,CAoDjE"}
+{"version":3,"file":"useChapterNavigation.d.ts","sourceRoot":"","sources":["../src/useChapterNavigation.ts"],"names":[],"mappings":"AAMA,UAAU,0BAA0B;IAClC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,0BAA0B,CAsDjE"}

package/dist/useChapterNavigation.js

@@ -1,52 +1,54 @@
+'use client';
+import { getAdjacentChapter } from '@youversion/platform-core';
 import { useReaderContext } from './context/ReaderContext';
-import { useChapters } from './useChapters';
+import { useBooks } from './useBooks';
 /**
- * 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.
+ * Provides navigation functionality for chapters across book boundaries,
+ * including intro chapter support.
  */
 export function useChapterNavigation() {
-    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);
-            }
+    const { currentChapter, currentVersion, currentBook, setChapter, setBook } = useReaderContext();
+    const { books, loading: booksLoading } = useBooks(currentVersion?.id ?? 0, {
+        enabled: Boolean(currentVersion?.id),
+    });
+    const booksData = books?.data ?? [];
+    const bookId = currentBook?.id ?? '';
+    const chapterId = currentChapter?.id ?? '';
+    const nextResult = getAdjacentChapter(booksData, bookId, chapterId, 'next');
+    const prevResult = getAdjacentChapter(booksData, bookId, chapterId, 'previous');
+    const canNavigateNext = !booksLoading && nextResult !== null;
+    const canNavigatePrevious = !booksLoading && prevResult !== null;
+    const currentChapterIndex = currentBook?.chapters?.findIndex((c) => c.id === currentChapter?.id) ?? -1;
+    const navigate = (result) => {
+        if (!result || !booksData.length)
+            return;
+        const targetBook = booksData.find((b) => b.id === result.bookId);
+        if (!targetBook)
+            return;
+        const targetChapter = targetBook.chapters?.find((c) => c.id === result.chapterId) ??
+            (targetBook.intro?.id === result.chapterId
+                ? {
+                    id: targetBook.intro.id,
+                    passage_id: targetBook.intro.passage_id,
+                    title: targetBook.intro.title,
+                }
+                : undefined);
+        if (!targetChapter)
+            return;
+        if (targetBook.id !== currentBook?.id) {
+            setBook(targetBook);
         }
+        setChapter(targetChapter);
     };
+    const navigateToNext = () => navigate(nextResult);
+    const navigateToPrevious = () => navigate(prevResult);
     return {
         canNavigatePrevious,
         canNavigateNext,
         navigateToPrevious,
         navigateToNext,
         currentChapterIndex,
-        isLoading: chaptersLoading,
+        isLoading: booksLoading,
     };
 }
 //# sourceMappingURL=useChapterNavigation.js.map

package/dist/useChapterNavigation.js.map

@@ -1 +1 @@
-{"version":3,"file":"useChapterNavigation.js","sourceRoot":"","sources":["../src/useChapterNavigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAW5C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,gBAAgB,EAAE,CAAC;IAEvF,MAAM,cAAc,GAAG,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC;IAE7C,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,WAAW,CACxD,cAAc,EAAE,EAAE,IAAI,CAAC,EACvB,cAAc,EACd,EAAE,OAAO,EAAE,OAAO,CAAC,cAAc,IAAI,cAAc,EAAE,EAAE,CAAC,EAAE,CAC3D,CAAC;IAEF,MAAM,mBAAmB,GAAG,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,cAAc,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAE9F,MAAM,mBAAmB,GAAG,OAAO,CACjC,CAAC,eAAe,IAAI,QAAQ,EAAE,IAAI,IAAI,mBAAmB,KAAK,CAAC,CAAC,IAAI,mBAAmB,GAAG,CAAC,CAC5F,CAAC;IAEF,MAAM,eAAe,GAAG,OAAO,CAC7B,CAAC,eAAe;QACd,QAAQ,EAAE,IAAI;QACd,mBAAmB,KAAK,CAAC,CAAC;QAC1B,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CACjD,CAAC;IAEF,MAAM,kBAAkB,GAAG,GAAG,EAAE;QAC9B,IAAI,mBAAmB,IAAI,QAAQ,EAAE,IAAI,EAAE,CAAC;YAC1C,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC,CAAC;YAC/D,IAAI,eAAe,EAAE,CAAC;gBACpB,iEAAiE;gBACjE,UAAU,CAAC,eAAe,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,GAAG,EAAE;QAC1B,IAAI,eAAe,IAAI,QAAQ,EAAE,IAAI,EAAE,CAAC;YACtC,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,mBAAmB,GAAG,CAAC,CAAC,CAAC;YAC3D,IAAI,WAAW,EAAE,CAAC;gBAChB,iEAAiE;gBACjE,UAAU,CAAC,WAAW,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,mBAAmB;QACnB,eAAe;QACf,kBAAkB;QAClB,cAAc;QACd,mBAAmB;QACnB,SAAS,EAAE,eAAe;KAC3B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"useChapterNavigation.js","sourceRoot":"","sources":["../src/useChapterNavigation.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAWtC;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,gBAAgB,EAAE,CAAC;IAEhG,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,QAAQ,CAAC,cAAc,EAAE,EAAE,IAAI,CAAC,EAAE;QACzE,OAAO,EAAE,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;KACrC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,KAAK,EAAE,IAAI,IAAI,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC;IACrC,MAAM,SAAS,GAAG,cAAc,EAAE,EAAE,IAAI,EAAE,CAAC;IAE3C,MAAM,UAAU,GAAG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAC5E,MAAM,UAAU,GAAG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAEhF,MAAM,eAAe,GAAG,CAAC,YAAY,IAAI,UAAU,KAAK,IAAI,CAAC;IAC7D,MAAM,mBAAmB,GAAG,CAAC,YAAY,IAAI,UAAU,KAAK,IAAI,CAAC;IAEjE,MAAM,mBAAmB,GACvB,WAAW,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,cAAc,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAE7E,MAAM,QAAQ,GAAG,CAAC,MAAoD,EAAE,EAAE;QACxE,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM;YAAE,OAAO;QAEzC,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC;QACjE,IAAI,CAAC,UAAU;YAAE,OAAO;QAExB,MAAM,aAAa,GACjB,UAAU,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,SAAS,CAAC;YAC3D,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,KAAK,MAAM,CAAC,SAAS;gBACxC,CAAC,CAAC;oBACE,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,EAAE;oBACvB,UAAU,EAAE,UAAU,CAAC,KAAK,CAAC,UAAU;oBACvC,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK;iBAC9B;gBACH,CAAC,CAAC,SAAS,CAAC,CAAC;QACjB,IAAI,CAAC,aAAa;YAAE,OAAO;QAE3B,IAAI,UAAU,CAAC,EAAE,KAAK,WAAW,EAAE,EAAE,EAAE,CAAC;YACtC,OAAO,CAAC,UAAU,CAAC,CAAC;QACtB,CAAC;QACD,UAAU,CAAC,aAAa,CAAC,CAAC;IAC5B,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAClD,MAAM,kBAAkB,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IAEtD,OAAO;QACL,mBAAmB;QACnB,eAAe;QACf,kBAAkB;QAClB,cAAc;QACd,mBAAmB;QACnB,SAAS,EAAE,YAAY;KACxB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youversion/platform-react-hooks",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -22,7 +22,7 @@
     }
   },
   "dependencies": {
-    "@youversion/platform-core": "1.16.0"
+    "@youversion/platform-core": "1.18.0"
   },
   "peerDependencies": {
     "react": ">=19.1.0 <20.0.0"
@@ -37,8 +37,8 @@
     "jsdom": "27.0.1",
     "typescript": "5.9.3",
     "vitest": "4.0.4",
-    "@internal/eslint-config": "0.0.0",
-    "@internal/tsconfig": "0.0.0"
+    "@internal/tsconfig": "0.0.0",
+    "@internal/eslint-config": "0.0.0"
   },
   "scripts": {
     "dev": "tsc --watch",

package/src/useChapterNavigation.test.tsx

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import React from 'react';
+import { useChapterNavigation } from './useChapterNavigation';
+import { useReaderContext } from './context/ReaderContext';
+import { ReaderProvider } from './context/ReaderProvider';
+import { createMockBook, createMockVersion } from './__tests__/mocks/bibles';
+import type { BibleBook, BibleChapter } from '@youversion/platform-core';
+
+function makeChapters(bookId: string, count: number): BibleChapter[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: (i + 1).toString(),
+    passage_id: `${bookId}.${i + 1}`,
+    title: (i + 1).toString(),
+  }));
+}
+
+const genChapters = makeChapters('GEN', 50);
+const exoChapters = makeChapters('EXO', 40);
+const revChapters = makeChapters('REV', 22);
+
+const mockBooks: BibleBook[] = [
+  createMockBook({
+    id: 'GEN',
+    title: 'Genesis',
+    chapters: genChapters,
+    intro: { id: 'INTRO', passage_id: 'GEN.INTRO', title: 'Intro' },
+  }),
+  createMockBook({
+    id: 'EXO',
+    title: 'Exodus',
+    canon: 'old_testament',
+    chapters: exoChapters,
+  }),
+  createMockBook({
+    id: 'REV',
+    title: 'Revelation',
+    canon: 'new_testament',
+    chapters: revChapters,
+  }),
+];
+
+const mockUseBooks = vi.fn();
+vi.mock('./useBooks', () => ({
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+  useBooks: (...args: unknown[]) => mockUseBooks(...args),
+}));
+
+function useNavWithContext() {
+  const nav = useChapterNavigation();
+  const ctx = useReaderContext();
+  return { nav, ctx };
+}
+
+function wrapper(book: BibleBook, chapter: BibleChapter) {
+  return ({ children }: { children: React.ReactNode }) => (
+    <ReaderProvider
+      currentVersion={createMockVersion()}
+      currentBook={book}
+      currentChapter={chapter}
+      currentVerse={null}
+    >
+      {children}
+    </ReaderProvider>
+  );
+}
+
+const genBook = mockBooks[0]!;
+const exoBook = mockBooks[1]!;
+const revBook = mockBooks[2]!;
+
+describe('useChapterNavigation', () => {
+  beforeEach(() => {
+    mockUseBooks.mockReturnValue({
+      books: { data: mockBooks },
+      loading: false,
+      error: null,
+      refetch: vi.fn(),
+    });
+  });
+
+  it('navigateToNext within same book updates chapter, keeps book', () => {
+    const { result } = renderHook(useNavWithContext, {
+      wrapper: wrapper(genBook, genChapters[0]!),
+    });
+
+    act(() => result.current.nav.navigateToNext());
+
+    expect(result.current.ctx.currentChapter.id).toBe('2');
+    expect(result.current.ctx.currentBook.id).toBe('GEN');
+  });
+
+  it('navigateToNext cross-book updates both book and chapter', () => {
+    const { result } = renderHook(useNavWithContext, {
+      wrapper: wrapper(genBook, genChapters.at(-1)!),
+    });
+
+    act(() => result.current.nav.navigateToNext());
+
+    expect(result.current.ctx.currentBook.id).toBe('EXO');
+    expect(result.current.ctx.currentChapter.id).toBe('1');
+  });
+
+  it('navigateToPrevious to intro sets chapter to INTRO, keeps book', () => {
+    const { result } = renderHook(useNavWithContext, {
+      wrapper: wrapper(genBook, genChapters[0]!),
+    });
+
+    act(() => result.current.nav.navigateToPrevious());
+
+    expect(result.current.ctx.currentChapter.id).toBe('INTRO');
+    expect(result.current.ctx.currentBook.id).toBe('GEN');
+  });
+
+  it('navigateToPrevious cross-book updates both book and chapter', () => {
+    const { result } = renderHook(useNavWithContext, {
+      wrapper: wrapper(exoBook, exoChapters[0]!),
+    });
+
+    act(() => result.current.nav.navigateToPrevious());
+
+    expect(result.current.ctx.currentBook.id).toBe('GEN');
+    expect(result.current.ctx.currentChapter.id).toBe('50');
+  });
+
+  it('canNavigatePrevious is false at Bible start', () => {
+    const introChapter: BibleChapter = { id: 'INTRO', passage_id: 'GEN.INTRO', title: 'Intro' };
+
+    const { result } = renderHook(useNavWithContext, {
+      wrapper: wrapper(genBook, introChapter),
+    });
+
+    expect(result.current.nav.canNavigatePrevious).toBe(false);
+  });
+
+  it('canNavigateNext is false at Bible end', () => {
+    const { result } = renderHook(useNavWithContext, {
+      wrapper: wrapper(revBook, revChapters[21]!),
+    });
+
+    expect(result.current.nav.canNavigateNext).toBe(false);
+  });
+
+  it('both disabled while loading', () => {
+    mockUseBooks.mockReturnValue({
+      books: null,
+      loading: true,
+      error: null,
+      refetch: vi.fn(),
+    });
+
+    const { result } = renderHook(useNavWithContext, {
+      wrapper: wrapper(genBook, genChapters[0]!),
+    });
+
+    expect(result.current.nav.canNavigateNext).toBe(false);
+    expect(result.current.nav.canNavigatePrevious).toBe(false);
+    expect(result.current.nav.isLoading).toBe(true);
+  });
+});

package/src/useChapterNavigation.ts

@@ -1,5 +1,8 @@
+'use client';
+
+import { getAdjacentChapter } from '@youversion/platform-core';
 import { useReaderContext } from './context/ReaderContext';
-import { useChapters } from './useChapters';
+import { useBooks } from './useBooks';
 
 interface UseChapterNavigationResult {
   canNavigatePrevious: boolean;
@@ -11,67 +14,61 @@ interface UseChapterNavigationResult {
 }
 
 /**
- * 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.
+ * Provides navigation functionality for chapters across book boundaries,
+ * including intro chapter support.
  */
 export function useChapterNavigation(): UseChapterNavigationResult {
-  const { currentChapter, currentVersion, currentBook, setChapter } = useReaderContext();
+  const { currentChapter, currentVersion, currentBook, setChapter, setBook } = useReaderContext();
 
-  const bookIdentifier = currentBook?.id ?? '';
+  const { books, loading: booksLoading } = useBooks(currentVersion?.id ?? 0, {
+    enabled: Boolean(currentVersion?.id),
+  });
 
-  const { chapters, loading: chaptersLoading } = useChapters(
-    currentVersion?.id ?? 0,
-    bookIdentifier,
-    { enabled: Boolean(bookIdentifier && currentVersion?.id) },
-  );
+  const booksData = books?.data ?? [];
+  const bookId = currentBook?.id ?? '';
+  const chapterId = currentChapter?.id ?? '';
 
-  const currentChapterIndex = chapters?.data.findIndex((c) => c.id === currentChapter.id) ?? -1;
+  const nextResult = getAdjacentChapter(booksData, bookId, chapterId, 'next');
+  const prevResult = getAdjacentChapter(booksData, bookId, chapterId, 'previous');
 
-  const canNavigatePrevious = Boolean(
-    !chaptersLoading && chapters?.data && currentChapterIndex !== -1 && currentChapterIndex > 0,
-  );
+  const canNavigateNext = !booksLoading && nextResult !== null;
+  const canNavigatePrevious = !booksLoading && prevResult !== null;
 
-  const canNavigateNext = Boolean(
-    !chaptersLoading &&
-      chapters?.data &&
-      currentChapterIndex !== -1 &&
-      currentChapterIndex < chapters.data.length - 1,
-  );
+  const currentChapterIndex =
+    currentBook?.chapters?.findIndex((c) => c.id === currentChapter?.id) ?? -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 navigate = (result: { bookId: string; chapterId: string } | null) => {
+    if (!result || !booksData.length) return;
 
-  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);
-      }
+    const targetBook = booksData.find((b) => b.id === result.bookId);
+    if (!targetBook) return;
+
+    const targetChapter =
+      targetBook.chapters?.find((c) => c.id === result.chapterId) ??
+      (targetBook.intro?.id === result.chapterId
+        ? {
+            id: targetBook.intro.id,
+            passage_id: targetBook.intro.passage_id,
+            title: targetBook.intro.title,
+          }
+        : undefined);
+    if (!targetChapter) return;
+
+    if (targetBook.id !== currentBook?.id) {
+      setBook(targetBook);
     }
+    setChapter(targetChapter);
   };
 
+  const navigateToNext = () => navigate(nextResult);
+  const navigateToPrevious = () => navigate(prevResult);
+
   return {
     canNavigatePrevious,
     canNavigateNext,
     navigateToPrevious,
     navigateToNext,
     currentChapterIndex,
-    isLoading: chaptersLoading,
+    isLoading: booksLoading,
   };
 }