diff --git a/packages/core/src/bible-html-transformer.ts b/packages/core/src/bible-html-transformer.ts
index d8bc50ab..97cb1b78 100644
--- a/packages/core/src/bible-html-transformer.ts
+++ b/packages/core/src/bible-html-transformer.ts
@@ -122,6 +122,8 @@ export type TransformedBibleHtml = {
};
function wrapVerseContent(doc: Document): void {
+ const verseBlockSelector =
+ '.p, p, .d, .q, .q1, .q2, .q3, .q4, .qm, .qm1, .qm2, .qm3, .qm4, .qr, .qc, .m, .mi, .pi, .pi1, .pi2, .pi3, .pi4, .pc, .pr, .pm, .pmo, .pmc, .pmr, .li, .li1, .li2, .li3, .li4';
function wrapParagraphContent(doc: Document, paragraph: Element, verseNum: string): void {
const children = Array.from(paragraph.childNodes);
if (children.length === 0) return;
@@ -162,7 +164,7 @@ function wrapVerseContent(doc: Document): void {
if (currentParagraph.querySelector('.yv-v[v]')) break;
- if (currentParagraph.classList.contains('p') || currentParagraph.tagName === 'P') {
+ if (currentParagraph.matches(verseBlockSelector)) {
wrapParagraphContent(doc, currentParagraph, verseNum);
}
@@ -197,8 +199,8 @@ function wrapVerseContent(doc: Document): void {
const nodesToWrap = collectNodesBetweenMarkers(marker, nextMarker);
if (nodesToWrap.length === 0) return;
- const currentParagraph = marker.closest('.p, p, div.p');
- const nextParagraph = nextMarker?.closest('.p, p, div.p') || null;
+ const currentParagraph = marker.closest(verseBlockSelector);
+ const nextParagraph = nextMarker?.closest(verseBlockSelector) || null;
const doc = marker.ownerDocument;
wrapNodesInVerse(marker, verseNum, nodesToWrap);
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 0d82dbf5..9f1ffa90 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -26,13 +26,16 @@ export { LanguagesClient } from './languages';
export { getLanguage } from './languages-language';
export { getLanguages, type GetLanguagesOptions } from './languages-list';
export { SearchClient, type SearchVersesOptions } from './search';
-export {
- getSuggestedQueries,
- getTrendingQueries,
-} from './search-queries';
+export { getSuggestedQueries, getTrendingQueries } from './search-queries';
export { searchVerses } from './search-verses';
export { searchTopics } from './search-topics';
-export { isValidStructuralUsfmReference } from './schemas/search';
+export {
+ MAX_SEARCH_QUERY_GRAPHEMES,
+ clampSearchText,
+ isValidStructuralUsfmReference,
+ parseSearchLanguageRange,
+} from './schemas/search';
+export { parseUsfmReference, type UsfmReference } from './usfm-reference';
export { OrganizationsClient } from './organizations';
export {
HighlightsClient,
diff --git a/packages/core/src/schemas/search.ts b/packages/core/src/schemas/search.ts
index e8b8b767..8edcca4e 100644
--- a/packages/core/src/schemas/search.ts
+++ b/packages/core/src/schemas/search.ts
@@ -1,16 +1,33 @@
import * as z from 'zod/mini';
+import { parseUsfmReference } from '../usfm-reference';
+
+export const MAX_SEARCH_QUERY_GRAPHEMES = 100;
+
+let searchTextSegmenter: Intl.Segmenter | undefined;
+
+/** Truncates to 100 graphemes, or Unicode code points when Intl.Segmenter is unavailable. */
+export function clampSearchText(raw: string): string {
+ if (Intl.Segmenter === undefined) {
+ return Array.from(raw).slice(0, MAX_SEARCH_QUERY_GRAPHEMES).join('');
+ }
+ searchTextSegmenter ??= new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+ const segments = searchTextSegmenter.segment(raw)[Symbol.iterator]();
+ let end = 0;
+ for (let count = 0; count < MAX_SEARCH_QUERY_GRAPHEMES; count += 1) {
+ const next = segments.next();
+ if (next.done) {
+ return raw;
+ }
+ end = next.value.index + next.value.segment.length;
+ }
+ return raw.slice(0, end);
+}
/** Known Platform Search user-intent values. Unknown wire strings remain valid. */
export const KNOWN_SEARCH_USER_INTENTS = ['unknown', 'topical', 'text', 'reference'] as const;
export type KnownSearchUserIntent = (typeof KNOWN_SEARCH_USER_INTENTS)[number];
-/**
- * Dot-separated USFM passage id for search hits (`BOOK.CHAPTER[.VERSE[-VERSE]]`).
- * Structural only: book codes are not checked against {@link BOOK_IDS}.
- */
-const USFM_REFERENCE_PATTERN = /^([A-Z0-9]{1,3})\.(\d+)(?:\.(\d+)(?:-(\d+))?)?$/;
-
/**
* Structural USFM reference check for search verse hits.
* Rejects malformed references and non-positive chapter/verse numbers.
@@ -22,31 +39,7 @@ const USFM_REFERENCE_PATTERN = /^([A-Z0-9]{1,3})\.(\d+)(?:\.(\d+)(?:-(\d+))?)?$/
* (for example `ZZZ.1.1`) so bad hits drop without throwing while good hits stay.
*/
export function isValidStructuralUsfmReference(usfm: string): boolean {
- const match = USFM_REFERENCE_PATTERN.exec(usfm);
- if (!match) {
- return false;
- }
-
- const chapter = Number(match[2]);
- if (!Number.isInteger(chapter) || chapter <= 0) {
- return false;
- }
-
- if (match[3] !== undefined) {
- const verse = Number(match[3]);
- if (!Number.isInteger(verse) || verse <= 0) {
- return false;
- }
- }
-
- if (match[4] !== undefined) {
- const verseEnd = Number(match[4]);
- if (!Number.isInteger(verseEnd) || verseEnd <= 0) {
- return false;
- }
- }
-
- return true;
+ return parseUsfmReference(usfm) !== null;
}
/** Normalizes caller language ranges for search endpoints (`en_US` → `en-us`). */
@@ -246,14 +239,15 @@ export function toSearchTopicsResponse(wire: SearchTopicsWire): SearchTopicsResp
};
}
-/** Input validation for verse/topic search queries (1–100 characters). */
-export const SearchTextQuerySchema = z
- .string()
- .check(
- z.trim(),
- z.minLength(1, 'Query must be between 1 and 100 characters'),
- z.maxLength(100, 'Query must be between 1 and 100 characters'),
- );
+/** Input validation for verse/topic search queries (1–100 grapheme clusters). */
+export const SearchTextQuerySchema = z.string().check(
+ z.trim(),
+ z.minLength(1, 'Query must be between 1 and 100 characters'),
+ z.refine(
+ (value) => clampSearchText(value) === value,
+ 'Query must be between 1 and 100 characters',
+ ),
+);
/** Input validation for suggested-query partial text (non-empty). */
export const SuggestedSearchQuerySchema = z
diff --git a/packages/core/src/styles/bible-reader.css b/packages/core/src/styles/bible-reader.css
index a2ad5092..549dbad7 100644
--- a/packages/core/src/styles/bible-reader.css
+++ b/packages/core/src/styles/bible-reader.css
@@ -174,6 +174,12 @@
text-underline-offset: 0.33em;
}
+ /* Search-driven transient focus. Dim the rest of the chapter. */
+ &[data-yv-verse-focus] .yv-v:not(.yv-v-focused),
+ &[data-yv-verse-focus] .yv-h {
+ opacity: 0.35;
+ }
+
/* Demo highlighted verse styling 20% opacity of expressive yellow 30 */
& .yv-v.yv-v-highlighted {
background-color: rgba(241, 156, 51, 0.2);
diff --git a/packages/core/src/styles/theme.css b/packages/core/src/styles/theme.css
index 8fd31212..d3a668d3 100644
--- a/packages/core/src/styles/theme.css
+++ b/packages/core/src/styles/theme.css
@@ -3,6 +3,7 @@
@import './preflight.css';
[data-yv-sdk] {
+ color-scheme: light;
/* Brand colors */
--yv-red: oklch(from #ff3d4d l c h);
--yv-red-dark-mode: oklch(from #f04c59 l c h);
@@ -123,6 +124,7 @@
--yv-highlight-mix-p: 1;
&[data-yv-theme='dark'] {
+ color-scheme: dark;
/* Brand colors - Dark theme */
--yv-background: var(--yv-gray-50);
--yv-foreground: var(--yv-white);
diff --git a/packages/core/src/usfm-reference.ts b/packages/core/src/usfm-reference.ts
new file mode 100644
index 00000000..2bab8779
--- /dev/null
+++ b/packages/core/src/usfm-reference.ts
@@ -0,0 +1,72 @@
+export type UsfmReference = Readonly<{
+ book: string;
+ chapter: string;
+ verses: readonly number[];
+}>;
+
+const USFM_REFERENCE_PATTERN = /^([A-Z0-9]{1,3})\.(\d+)(?:\.(\d+)(?:-(\d+))?)?$/;
+
+/**
+ * Longest Bible chapter is Psalm 119 (176 verses). Anything longer is
+ * malformed and is rejected rather than expanded.
+ */
+const MAX_RANGE_LENGTH = 250;
+
+function isPositiveSafeInteger(value: number): boolean {
+ return Number.isSafeInteger(value) && value > 0;
+}
+
+/**
+ * Parses `JHN.6`, `JHN.6.9`, and `JHN.6.9-11`. Returns `null` for anything
+ * malformed, non-positive, not a safe integer, with `verseEnd < verseStart`,
+ * or a verse span longer than 250. Does not check book codes against
+ * `BOOK_IDS`.
+ *
+ * Sole owner of this grammar. `isValidStructuralUsfmReference` is
+ * `parseUsfmReference(usfm) !== null`.
+ */
+export function parseUsfmReference(usfm: string): UsfmReference | null {
+ const match = USFM_REFERENCE_PATTERN.exec(usfm);
+ if (!match) {
+ return null;
+ }
+
+ const book = match[1];
+ const chapter = match[2];
+ if (book === undefined || chapter === undefined) {
+ return null;
+ }
+
+ const chapterNumber = Number(chapter);
+ if (!isPositiveSafeInteger(chapterNumber)) {
+ return null;
+ }
+
+ if (match[3] === undefined) {
+ return { book, chapter, verses: [] };
+ }
+
+ const verseStart = Number(match[3]);
+ if (!isPositiveSafeInteger(verseStart)) {
+ return null;
+ }
+
+ if (match[4] === undefined) {
+ return { book, chapter, verses: [verseStart] };
+ }
+
+ const verseEnd = Number(match[4]);
+ if (!isPositiveSafeInteger(verseEnd) || verseEnd < verseStart) {
+ return null;
+ }
+
+ if (verseEnd - verseStart + 1 > MAX_RANGE_LENGTH) {
+ return null;
+ }
+
+ const verses: number[] = [];
+ for (let verse = verseStart; verse <= verseEnd; verse += 1) {
+ verses.push(verse);
+ }
+ return { book, chapter, verses };
+}
diff --git a/packages/hooks/src/context/YouVersionContext.tsx b/packages/hooks/src/context/YouVersionContext.tsx
index 477543cd..e9e5f667 100644
--- a/packages/hooks/src/context/YouVersionContext.tsx
+++ b/packages/hooks/src/context/YouVersionContext.tsx
@@ -1,7 +1,12 @@
'use client';
import { createContext } from 'react';
-import type { BibleClient, LanguagesClient, OrganizationsClient } from '@youversion/platform-core';
+import type {
+ BibleClient,
+ LanguagesClient,
+ OrganizationsClient,
+ SearchClient,
+} from '@youversion/platform-core';
import type { HookOverrides } from '../hook-overrides';
export type { HookOverrides };
@@ -20,6 +25,8 @@ export type YouVersionContextData = {
languagesClient?: LanguagesClient;
/** Test seam: skip constructing a live OrganizationsClient. */
organizationsClient?: OrganizationsClient;
+ /** Test seam: skip constructing a live SearchClient. */
+ searchClient?: SearchClient;
/** Test seam: return stub hook results without fetching. */
hookOverrides?: HookOverrides;
};
diff --git a/packages/hooks/src/hook-overrides.ts b/packages/hooks/src/hook-overrides.ts
index bbd6faa5..9323bea0 100644
--- a/packages/hooks/src/hook-overrides.ts
+++ b/packages/hooks/src/hook-overrides.ts
@@ -10,6 +10,7 @@ import type { UseLanguageResult } from './useLanguage';
import type { UseLanguagesResult } from './useLanguages';
import type { UseOrganizationsResult } from './useOrganizations';
import type { UsePassageProps, UsePassageResult } from './usePassage';
+import type { UseBibleSearchProps, UseBibleSearchResult } from './useBibleSearch';
import type { UseVersionResult } from './useVersion';
import type { UseVersionsOptions, UseVersionsResult } from './useVersions';
import type { UseVerseOfTheDayResult } from './useVOTD';
@@ -39,6 +40,7 @@ export type HookOverrides = {
) => UseLanguagesResult;
useOrganizations?: (organizationIds: (string | null | undefined)[]) => UseOrganizationsResult;
usePassage?: (props: UsePassageProps) => UsePassageResult;
+ useBibleSearch?: (props: UseBibleSearchProps) => UseBibleSearchResult;
useTheme?: () => 'light' | 'dark';
useVersion?: (versionId: number, options?: UseApiDataOptions) => UseVersionResult;
useVersions?: (
diff --git a/packages/hooks/src/index.ts b/packages/hooks/src/index.ts
index 0d44d571..8e623aad 100644
--- a/packages/hooks/src/index.ts
+++ b/packages/hooks/src/index.ts
@@ -14,6 +14,8 @@ export * from './useOrganizationsClient';
export * from './context';
export * from './utility';
export * from './useBibleClient';
+export * from './useSearchClient';
+export * from './useBibleSearch';
export * from './usePassage';
export * from './useVOTD';
export * from './useHighlights';
diff --git a/packages/hooks/src/internal/bible-search-session.test.ts b/packages/hooks/src/internal/bible-search-session.test.ts
new file mode 100644
index 00000000..46fe4e03
--- /dev/null
+++ b/packages/hooks/src/internal/bible-search-session.test.ts
@@ -0,0 +1,486 @@
+import { describe, expect, it } from 'vitest';
+import type { SearchQuery, SearchVersesResponse } from '@youversion/platform-core';
+import {
+ EMPTY_QUERY,
+ MAX_SEARCH_QUERY_LENGTH,
+ clampSearchInput,
+ createSearchSession,
+ deriveSearchPhase,
+ normalizeQuery,
+ projectVerses,
+ queriesRequest,
+ searchSessionReducer,
+ versesRequest,
+ type NormalizedQuery,
+ type SearchSession,
+ type VersesRequest,
+} from './bible-search-session';
+
+const LOVE = normalizeQuery('love');
+const GRACE = normalizeQuery('grace');
+
+const trendingQueries: readonly SearchQuery[] = [{ text: 'love' }, { text: 'hope' }];
+const suggestQueries: readonly SearchQuery[] = [{ text: 'love of God' }];
+
+function versesResponse(
+ ids: readonly string[],
+ nextPageToken: string | null = null,
+): SearchVersesResponse {
+ return {
+ verses: ids.map((id) => ({ id })),
+ didYouMean: [],
+ searchInsteadFor: null,
+ nextPageToken,
+ };
+}
+
+function firstPageRequest(query: NormalizedQuery, versionId = 111): VersesRequest {
+ return { query, versionId, pageToken: null };
+}
+
+function browsing(raw: string, versionId = 111): SearchSession {
+ return searchSessionReducer(createSearchSession(versionId), { type: 'setQuery', raw });
+}
+
+function submitted(raw: string, versionId = 111): SearchSession {
+ return searchSessionReducer(browsing(raw, versionId), { type: 'submit' });
+}
+
+function withPages(
+ session: SearchSession,
+ ids: readonly string[],
+ nextPageToken: string | null = 'page-2',
+): SearchSession {
+ const request = versesRequest(session);
+ if (request === null) {
+ throw new Error('expected a verses request');
+ }
+ return searchSessionReducer(session, {
+ type: 'commitPage',
+ request,
+ response: versesResponse(ids, nextPageToken),
+ });
+}
+
+describe('clampSearchInput', () => {
+ it('leaves short input unchanged, including trailing spaces', () => {
+ expect(clampSearchInput('love ')).toBe('love ');
+ });
+
+ it('clamps to 100 graphemes without trimming or splitting clusters', () => {
+ const raw = `${'a'.repeat(MAX_SEARCH_QUERY_LENGTH)}bcd`;
+ expect(clampSearchInput(raw)).toBe('a'.repeat(MAX_SEARCH_QUERY_LENGTH));
+
+ const combiningCluster = 'e\u0301';
+ expect(clampSearchInput(`${'a'.repeat(99)}${combiningCluster}z`)).toBe(
+ `${'a'.repeat(99)}${combiningCluster}`,
+ );
+ expect(clampSearchInput(`${'a'.repeat(99)}😀z`)).toBe(`${'a'.repeat(99)}😀`);
+ });
+});
+
+describe('normalizeQuery', () => {
+ it('trims and brands a non-empty query', () => {
+ expect(normalizeQuery(' love ')).toBe('love');
+ });
+
+ it('maps whitespace-only input to the empty query', () => {
+ expect(normalizeQuery(' ')).toBe(EMPTY_QUERY);
+ });
+});
+
+describe('searchSessionReducer', () => {
+ it('starts browsing with an empty query', () => {
+ expect(createSearchSession(111)).toEqual({
+ versionId: 111,
+ raw: '',
+ normalized: EMPTY_QUERY,
+ lane: { kind: 'browsing' },
+ });
+ });
+
+ it('setQuery keeps the submitted lane when only trailing space changes', () => {
+ const withResults = withPages(submitted('love'), ['JHN.3.16']);
+ const next = searchSessionReducer(withResults, { type: 'setQuery', raw: 'love ' });
+ expect(next.raw).toBe('love ');
+ expect(next.normalized).toBe(LOVE);
+ expect(next.lane).toEqual(withResults.lane);
+ });
+
+ it('setQuery drops to browsing when the normalized query changes', () => {
+ const withResults = withPages(submitted('love'), ['JHN.3.16']);
+ expect(searchSessionReducer(withResults, { type: 'setQuery', raw: 'grace' })).toEqual({
+ versionId: 111,
+ raw: 'grace',
+ normalized: GRACE,
+ lane: { kind: 'browsing' },
+ });
+ });
+
+ it('setQuery returns the same object when raw is unchanged', () => {
+ const state = browsing('love');
+ expect(searchSessionReducer(state, { type: 'setQuery', raw: 'love' })).toBe(state);
+ });
+
+ it('submit on empty input lands in browsing with a cleared raw field', () => {
+ const spaces = browsing(' ');
+ expect(searchSessionReducer(spaces, { type: 'submit' })).toEqual({
+ versionId: 111,
+ raw: '',
+ normalized: EMPTY_QUERY,
+ lane: { kind: 'browsing' },
+ });
+ });
+
+ it('submit starts a submitted lane with no pages', () => {
+ expect(submitted('love')).toEqual({
+ versionId: 111,
+ raw: 'love',
+ normalized: LOVE,
+ lane: { kind: 'submitted', query: LOVE, pages: [], wantsMore: false },
+ });
+ });
+
+ it('resubmission clears pages and refreshes whitespace-only suggestion text', () => {
+ const state = withPages(submitted('love'), ['JHN.3.16']);
+ expect(searchSessionReducer(state, { type: 'submit' })).toEqual({
+ versionId: 111,
+ raw: 'love',
+ normalized: 'love',
+ lane: { kind: 'submitted', query: 'love', pages: [], wantsMore: false },
+ });
+ expect(searchSessionReducer(state, { type: 'selectSuggestion', text: ' love ' })).toMatchObject(
+ { raw: ' love ', normalized: 'love', lane: { pages: [] } },
+ );
+ });
+
+ it('selectSuggestion fills the input and submits in one transition', () => {
+ const state = browsing('lo');
+ expect(searchSessionReducer(state, { type: 'selectSuggestion', text: 'love of God' })).toEqual({
+ versionId: 111,
+ raw: 'love of God',
+ normalized: 'love of God',
+ lane: {
+ kind: 'submitted',
+ query: 'love of God',
+ pages: [],
+ wantsMore: false,
+ },
+ });
+ });
+
+ it('loadMore is a no-op until a page with a next token exists', () => {
+ const empty = submitted('love');
+ expect(searchSessionReducer(empty, { type: 'loadMore' })).toBe(empty);
+ const lastPage = withPages(submitted('love'), ['JHN.3.16'], null);
+ expect(searchSessionReducer(lastPage, { type: 'loadMore' })).toBe(lastPage);
+ });
+
+ it('loadMore sets wantsMore when the last page has a next token', () => {
+ const paged = withPages(submitted('love'), ['JHN.3.16'], 'page-2');
+ const next = searchSessionReducer(paged, { type: 'loadMore' });
+ expect(next.lane).toEqual({
+ kind: 'submitted',
+ query: LOVE,
+ pages: [
+ {
+ token: null,
+ hits: [{ id: 'JHN.3.16' }],
+ nextToken: 'page-2',
+ },
+ ],
+ wantsMore: true,
+ });
+ expect(searchSessionReducer(next, { type: 'loadMore' })).toBe(next);
+ });
+
+ it('setVersion returns identity for the same id', () => {
+ const state = submitted('love');
+ expect(searchSessionReducer(state, { type: 'setVersion', versionId: 111 })).toBe(state);
+ });
+
+ it('setVersion re-runs a submitted search under the new version', () => {
+ const withResults = withPages(submitted('love'), ['JHN.3.16']);
+ expect(searchSessionReducer(withResults, { type: 'setVersion', versionId: 222 })).toEqual({
+ versionId: 222,
+ raw: 'love',
+ normalized: LOVE,
+ lane: { kind: 'submitted', query: LOVE, pages: [], wantsMore: false },
+ });
+ });
+
+ it('commitPage ignores a stale query, version, or duplicate token', () => {
+ const state = submitted('love');
+ const request = firstPageRequest(LOVE);
+ const response = versesResponse(['JHN.3.16'], 'page-2');
+ const committed = searchSessionReducer(state, { type: 'commitPage', request, response });
+
+ expect(
+ searchSessionReducer(state, {
+ type: 'commitPage',
+ request: { ...request, query: GRACE },
+ response,
+ }),
+ ).toBe(state);
+ expect(
+ searchSessionReducer(state, {
+ type: 'commitPage',
+ request: { ...request, versionId: 222 },
+ response,
+ }),
+ ).toBe(state);
+ expect(
+ searchSessionReducer(committed, {
+ type: 'commitPage',
+ request,
+ response: versesResponse(['ROM.8.28'], 'page-3'),
+ }),
+ ).toBe(committed);
+ expect(
+ searchSessionReducer(browsing('love'), { type: 'commitPage', request, response }),
+ ).toEqual(browsing('love'));
+ });
+
+ it('commitPage appends the matching page and clears wantsMore', () => {
+ const first = withPages(submitted('love'), ['JHN.3.16'], 'page-2');
+ const loadingMore = searchSessionReducer(first, { type: 'loadMore' });
+ const second = searchSessionReducer(loadingMore, {
+ type: 'commitPage',
+ request: { query: LOVE, versionId: 111, pageToken: 'page-2' },
+ response: versesResponse(['ROM.8.28'], null),
+ });
+ expect(second.lane).toEqual({
+ kind: 'submitted',
+ query: LOVE,
+ pages: [
+ { token: null, hits: [{ id: 'JHN.3.16' }], nextToken: 'page-2' },
+ { token: 'page-2', hits: [{ id: 'ROM.8.28' }], nextToken: null },
+ ],
+ wantsMore: false,
+ });
+ });
+});
+
+describe('queriesRequest and versesRequest', () => {
+ it('returns trending for an empty settled query and suggest otherwise', () => {
+ expect(queriesRequest(createSearchSession(111), EMPTY_QUERY)).toEqual({ kind: 'trending' });
+ expect(queriesRequest(browsing('love'), LOVE)).toEqual({ kind: 'suggest', query: LOVE });
+ expect(queriesRequest(submitted('love'), LOVE)).toBeNull();
+ expect(queriesRequest(browsing('loved'), null)).toBeNull();
+ expect(queriesRequest(browsing('loved'), LOVE)).toBeNull();
+ });
+
+ it('requests the first verse page, then the next token only while wantsMore', () => {
+ const first = submitted('love');
+ expect(versesRequest(first)).toEqual(firstPageRequest(LOVE));
+ expect(versesRequest(browsing('love'))).toBeNull();
+
+ const paged = withPages(first, ['JHN.3.16'], 'page-2');
+ expect(versesRequest(paged)).toBeNull();
+ expect(versesRequest(searchSessionReducer(paged, { type: 'loadMore' }))).toEqual({
+ query: LOVE,
+ versionId: 111,
+ pageToken: 'page-2',
+ });
+ });
+});
+
+describe('projectVerses', () => {
+ it('parses verse hits, drops malformed and chapter-only ids, and keeps only the first duplicate', () => {
+ expect(
+ projectVerses([{ id: 'JHN.3.16-18' }, { id: 'BAD' }, { id: 'JHN.3.16-18' }, { id: 'JHN.3' }]),
+ ).toEqual([{ id: 'JHN.3.16-18', book: 'JHN', chapter: '3', verses: [16, 17, 18] }]);
+ });
+});
+
+describe('deriveSearchPhase', () => {
+ const idle = {
+ queries: null,
+ queriesLoading: false,
+ versesLoading: false,
+ versesError: null,
+ } satisfies {
+ queries: readonly SearchQuery[] | null;
+ queriesLoading: boolean;
+ versesLoading: boolean;
+ versesError: Error | null;
+ };
+
+ it('maps empty browsing to trending, including a loading list', () => {
+ expect(
+ deriveSearchPhase({
+ session: createSearchSession(111),
+ settled: EMPTY_QUERY,
+ ...idle,
+ queries: trendingQueries,
+ }),
+ ).toEqual({ kind: 'trending', queries: trendingQueries, loading: false });
+ expect(
+ deriveSearchPhase({
+ session: createSearchSession(111),
+ settled: EMPTY_QUERY,
+ ...idle,
+ queriesLoading: true,
+ }),
+ ).toEqual({ kind: 'trending', queries: [], loading: true });
+ });
+
+ it('maps typing to suggesting, with debounce distinct from loading', () => {
+ const typing = browsing('love');
+ expect(
+ deriveSearchPhase({
+ session: typing,
+ settled: EMPTY_QUERY,
+ ...idle,
+ queries: trendingQueries,
+ }),
+ ).toEqual({
+ kind: 'suggesting',
+ queries: trendingQueries,
+ loading: false,
+ debouncing: true,
+ });
+ expect(
+ deriveSearchPhase({
+ session: typing,
+ settled: LOVE,
+ ...idle,
+ queries: suggestQueries,
+ queriesLoading: true,
+ }),
+ ).toEqual({
+ kind: 'suggesting',
+ queries: suggestQueries,
+ loading: true,
+ debouncing: false,
+ });
+ });
+
+ it('treats a suggestion failure as an empty list, never failed', () => {
+ expect(
+ deriveSearchPhase({
+ session: browsing('love'),
+ settled: LOVE,
+ ...idle,
+ queries: null,
+ }),
+ ).toEqual({
+ kind: 'suggesting',
+ queries: [],
+ loading: false,
+ debouncing: false,
+ });
+ });
+
+ it('maps a submitted first page in flight to searching', () => {
+ expect(
+ deriveSearchPhase({
+ session: submitted('love'),
+ settled: LOVE,
+ ...idle,
+ versesLoading: true,
+ }),
+ ).toEqual({ kind: 'searching' });
+ });
+
+ it('keeps searching in the landed-before-commit frame', () => {
+ expect(
+ deriveSearchPhase({
+ session: submitted('love'),
+ settled: LOVE,
+ ...idle,
+ }),
+ ).toEqual({ kind: 'searching' });
+ });
+
+ it('maps a first-page error to failed, then searching while retrying', () => {
+ const error = new Error('search failed');
+ expect(
+ deriveSearchPhase({
+ session: submitted('love'),
+ settled: LOVE,
+ ...idle,
+ versesError: error,
+ }),
+ ).toEqual({ kind: 'failed', error });
+ expect(
+ deriveSearchPhase({
+ session: submitted('love'),
+ settled: LOVE,
+ ...idle,
+ versesLoading: true,
+ versesError: error,
+ }),
+ ).toEqual({ kind: 'searching' });
+ });
+
+ it('maps zero projected hits to empty only when pagination is exhausted', () => {
+ expect(
+ deriveSearchPhase({
+ session: withPages(submitted('love'), ['BAD', 'JHN.3']),
+ settled: LOVE,
+ ...idle,
+ }),
+ ).toEqual({ kind: 'searching' });
+ expect(
+ deriveSearchPhase({
+ session: withPages(submitted('love'), ['BAD', 'JHN.3'], null),
+ settled: LOVE,
+ ...idle,
+ }),
+ ).toEqual({ kind: 'empty' });
+ });
+
+ it('maps non-empty hits to results and encodes nextPage as one enum', () => {
+ const john = {
+ id: 'JHN.3.16',
+ book: 'JHN',
+ chapter: '3',
+ verses: [16],
+ };
+ const available = withPages(submitted('love'), ['JHN.3.16'], 'page-2');
+ expect(deriveSearchPhase({ session: available, settled: LOVE, ...idle })).toEqual({
+ kind: 'results',
+ verses: [john],
+ nextPage: 'available',
+ });
+
+ const loadingMore = searchSessionReducer(available, { type: 'loadMore' });
+ expect(
+ deriveSearchPhase({
+ session: loadingMore,
+ settled: LOVE,
+ ...idle,
+ versesLoading: true,
+ }),
+ ).toEqual({ kind: 'results', verses: [john], nextPage: 'loading' });
+ expect(
+ deriveSearchPhase({
+ session: loadingMore,
+ settled: LOVE,
+ ...idle,
+ versesError: new Error('page 2 failed'),
+ }),
+ ).toEqual({ kind: 'results', verses: [john], nextPage: 'failed' });
+
+ const last = withPages(submitted('love'), ['JHN.3.16'], null);
+ expect(deriveSearchPhase({ session: last, settled: LOVE, ...idle })).toEqual({
+ kind: 'results',
+ verses: [john],
+ nextPage: 'none',
+ });
+
+ const first = withPages(submitted('love'), ['JHN.3.16', 'JHN.3.16'], 'page-2');
+ const loadingSecond = searchSessionReducer(first, { type: 'loadMore' });
+ const duplicateAcrossPages = searchSessionReducer(loadingSecond, {
+ type: 'commitPage',
+ request: { query: LOVE, versionId: 111, pageToken: 'page-2' },
+ response: versesResponse(['JHN.3.16', 'ROM.8.28']),
+ });
+ expect(
+ deriveSearchPhase({ session: duplicateAcrossPages, settled: LOVE, ...idle }),
+ ).toMatchObject({
+ verses: [john, { id: 'ROM.8.28', book: 'ROM', chapter: '8', verses: [28] }],
+ });
+ });
+});
diff --git a/packages/hooks/src/internal/bible-search-session.ts b/packages/hooks/src/internal/bible-search-session.ts
new file mode 100644
index 00000000..10a8746c
--- /dev/null
+++ b/packages/hooks/src/internal/bible-search-session.ts
@@ -0,0 +1,390 @@
+import {
+ MAX_SEARCH_QUERY_GRAPHEMES,
+ clampSearchText,
+ parseUsfmReference,
+} from '@youversion/platform-core';
+import type { SearchQuery, SearchVerseHit, SearchVersesResponse } from '@youversion/platform-core';
+
+export type NormalizedQuery = string & { readonly __normalizedQuery: unique symbol };
+
+export type VersePage = Readonly<{
+ /** Continuation token this page answered. `null` for the first page. */
+ token: string | null;
+ hits: readonly SearchVerseHit[];
+ nextToken: string | null;
+}>;
+
+/**
+ * Which lane is live. The PRD forbids suggesting for a query that is already
+ * submitted, so the lanes are one union rather than two slices that can both
+ * be on at once.
+ */
+export type SearchLane =
+ | { readonly kind: 'browsing' }
+ | {
+ readonly kind: 'submitted';
+ readonly query: NormalizedQuery;
+ /** Ascending. No two pages share a `token`. Empty while the first page is wanted. */
+ readonly pages: readonly VersePage[];
+ /** The user asked for the page after `pages.at(-1)` and it has not landed. */
+ readonly wantsMore: boolean;
+ };
+
+export type SearchSession = Readonly<{
+ versionId: number;
+ /** Raw controlled input. Clamped to 100 characters. Not trimmed while typing. */
+ raw: string;
+ /** Always `normalizeQuery(raw)`. Never set on its own. */
+ normalized: NormalizedQuery;
+ lane: SearchLane;
+}>;
+
+export type QueriesRequest =
+ | { readonly kind: 'trending' }
+ | { readonly kind: 'suggest'; readonly query: NormalizedQuery };
+
+export type VersesRequest = Readonly<{
+ query: NormalizedQuery;
+ versionId: number;
+ pageToken: string | null;
+}>;
+
+export type BibleSearchResult = Readonly<{
+ /** USFM id. Same semantics as `BiblePassage.id` (D1). */
+ id: string;
+ book: string;
+ /** Chapter id as a string, matching `BibleReaderContext.setChapter`. */
+ chapter: string;
+ /** Expanded, ascending. `JHN.3.16-18` becomes `[16, 17, 18]`. Chapter-only hits are omitted. */
+ verses: readonly number[];
+}>;
+
+export type BibleSearchPhase =
+ | {
+ readonly kind: 'trending';
+ readonly queries: readonly SearchQuery[];
+ readonly loading: boolean;
+ readonly error?: Error;
+ }
+ | {
+ readonly kind: 'suggesting';
+ readonly queries: readonly SearchQuery[];
+ readonly loading: boolean;
+ readonly error?: Error;
+ /** A keystroke is still settling. Never drive a spinner from this. */
+ readonly debouncing: boolean;
+ }
+ | { readonly kind: 'searching' }
+ | {
+ readonly kind: 'results';
+ readonly verses: readonly [BibleSearchResult, ...BibleSearchResult[]];
+ readonly nextPage: 'none' | 'available' | 'loading' | 'failed';
+ }
+ | { readonly kind: 'empty' }
+ | { readonly kind: 'failed'; readonly error: Error };
+
+export const MAX_SEARCH_QUERY_LENGTH = MAX_SEARCH_QUERY_GRAPHEMES;
+export const SEARCH_SUGGESTION_DEBOUNCE_MS = 300;
+export const SEARCH_VERSES_PAGE_SIZE = 20;
+export const EMPTY_QUERY =
+ // SAFETY: the empty string is the branded empty query. normalizeQuery is the
+ // only other mint, and it returns this constant after trim.
+ '' as NormalizedQuery;
+
+export function clampSearchInput(raw: string): string {
+ return clampSearchText(raw);
+}
+
+export function normalizeQuery(raw: string): NormalizedQuery {
+ const trimmed = raw.trim();
+ if (trimmed === '') {
+ return EMPTY_QUERY;
+ }
+ // SAFETY: branding after trim. Empty input already returned EMPTY_QUERY.
+ return trimmed as NormalizedQuery;
+}
+
+export type SearchSessionAction =
+ | { readonly type: 'setQuery'; readonly raw: string }
+ | { readonly type: 'submit' }
+ | { readonly type: 'selectSuggestion'; readonly text: string }
+ | { readonly type: 'loadMore' }
+ | { readonly type: 'setVersion'; readonly versionId: number }
+ | {
+ readonly type: 'commitPage';
+ readonly request: VersesRequest;
+ readonly response: SearchVersesResponse;
+ };
+
+export function createSearchSession(versionId: number): SearchSession {
+ return {
+ versionId,
+ raw: '',
+ normalized: EMPTY_QUERY,
+ lane: { kind: 'browsing' },
+ };
+}
+
+function submitNormalized(
+ state: SearchSession,
+ raw: string,
+ normalized: NormalizedQuery,
+): SearchSession {
+ if (normalized === EMPTY_QUERY) {
+ if (state.raw === '' && state.normalized === EMPTY_QUERY && state.lane.kind === 'browsing') {
+ return state;
+ }
+ return { ...state, raw: '', normalized: EMPTY_QUERY, lane: { kind: 'browsing' } };
+ }
+ return {
+ ...state,
+ raw,
+ normalized,
+ lane: { kind: 'submitted', query: normalized, pages: [], wantsMore: false },
+ };
+}
+
+/**
+ * Pure. Returns the same object for a no-op so React bails out.
+ *
+ * Invariants:
+ * - `normalized` is always `normalizeQuery(raw)`.
+ * - A submitted lane never contains two pages with the same token.
+ * - `wantsMore` is true only when the last page has a `nextToken`.
+ */
+export function searchSessionReducer(
+ state: SearchSession,
+ action: SearchSessionAction,
+): SearchSession {
+ switch (action.type) {
+ case 'setQuery': {
+ const raw = clampSearchInput(action.raw);
+ const normalized = normalizeQuery(raw);
+ if (normalized === state.normalized) {
+ if (raw === state.raw) {
+ return state;
+ }
+ return { ...state, raw };
+ }
+ return { ...state, raw, normalized, lane: { kind: 'browsing' } };
+ }
+ case 'submit': {
+ return submitNormalized(state, state.raw, state.normalized);
+ }
+ case 'selectSuggestion': {
+ const raw = clampSearchInput(action.text);
+ const normalized = normalizeQuery(raw);
+ return submitNormalized(state, raw, normalized);
+ }
+ case 'loadMore': {
+ if (state.lane.kind !== 'submitted' || state.lane.wantsMore) {
+ return state;
+ }
+ const last = state.lane.pages.at(-1);
+ if (last?.nextToken == null) {
+ return state;
+ }
+ return { ...state, lane: { ...state.lane, wantsMore: true } };
+ }
+ case 'setVersion': {
+ if (action.versionId === state.versionId) {
+ return state;
+ }
+ if (state.lane.kind === 'submitted') {
+ return {
+ ...state,
+ versionId: action.versionId,
+ lane: {
+ kind: 'submitted',
+ query: state.lane.query,
+ pages: [],
+ wantsMore: false,
+ },
+ };
+ }
+ return { ...state, versionId: action.versionId };
+ }
+ case 'commitPage': {
+ if (state.lane.kind !== 'submitted') {
+ return state;
+ }
+ if (
+ action.request.query !== state.lane.query ||
+ action.request.versionId !== state.versionId
+ ) {
+ return state;
+ }
+ if (state.lane.pages.some((page) => page.token === action.request.pageToken)) {
+ return state;
+ }
+ return {
+ ...state,
+ lane: {
+ ...state.lane,
+ pages: [
+ ...state.lane.pages,
+ {
+ token: action.request.pageToken,
+ hits: action.response.verses,
+ nextToken: action.response.nextPageToken ?? null,
+ },
+ ],
+ wantsMore: false,
+ },
+ };
+ }
+ default: {
+ const _exhaustive: never = action;
+ return _exhaustive;
+ }
+ }
+}
+
+export function queriesRequest(
+ session: SearchSession,
+ settled: NormalizedQuery | null,
+): QueriesRequest | null {
+ if (session.lane.kind === 'submitted' || settled === null) {
+ return null;
+ }
+ if (settled !== session.normalized) {
+ return null;
+ }
+ if (settled === EMPTY_QUERY) {
+ return { kind: 'trending' };
+ }
+ return { kind: 'suggest', query: settled };
+}
+
+export function versesRequest(session: SearchSession): VersesRequest | null {
+ if (session.lane.kind !== 'submitted') {
+ return null;
+ }
+ if (session.lane.pages.length === 0) {
+ return {
+ query: session.lane.query,
+ versionId: session.versionId,
+ pageToken: null,
+ };
+ }
+ if (!session.lane.wantsMore) {
+ return null;
+ }
+ const last = session.lane.pages.at(-1);
+ if (last?.nextToken == null) {
+ return null;
+ }
+ return {
+ query: session.lane.query,
+ versionId: session.versionId,
+ pageToken: last.nextToken,
+ };
+}
+
+export function projectVerses(hits: readonly SearchVerseHit[]): readonly BibleSearchResult[] {
+ const verses: BibleSearchResult[] = [];
+ const seen = new Set
();
+ for (const hit of hits) {
+ if (seen.has(hit.id)) {
+ continue;
+ }
+ seen.add(hit.id);
+ const parsed = parseUsfmReference(hit.id);
+ if (parsed === null || parsed.verses.length === 0) {
+ continue;
+ }
+ verses.push({
+ id: hit.id,
+ book: parsed.book,
+ chapter: parsed.chapter,
+ verses: parsed.verses,
+ });
+ }
+ return verses;
+}
+
+function flattenHits(pages: readonly VersePage[]): readonly SearchVerseHit[] {
+ const hits: SearchVerseHit[] = [];
+ for (const page of pages) {
+ hits.push(...page.hits);
+ }
+ return hits;
+}
+
+function nextPageStatus(input: {
+ readonly session: SearchSession;
+ readonly failed: boolean;
+ readonly inFlight: boolean;
+}): 'none' | 'available' | 'loading' | 'failed' {
+ if (input.failed) {
+ return 'failed';
+ }
+ if (input.inFlight) {
+ return 'loading';
+ }
+ if (input.session.lane.kind !== 'submitted') {
+ return 'none';
+ }
+ const last = input.session.lane.pages.at(-1);
+ return last?.nextToken ? 'available' : 'none';
+}
+
+export function deriveSearchPhase(input: {
+ readonly session: SearchSession;
+ readonly bookIds?: readonly string[];
+ readonly settled: NormalizedQuery | null;
+ readonly queries: readonly SearchQuery[] | null;
+ readonly queriesLoading: boolean;
+ readonly queriesError?: Error | null;
+ readonly versesLoading: boolean;
+ readonly versesError: Error | null;
+}): BibleSearchPhase {
+ const queries = input.queries ?? [];
+ if (input.session.lane.kind === 'browsing') {
+ const error = input.queriesError && !input.queriesLoading ? { error: input.queriesError } : {};
+ if (input.session.normalized === EMPTY_QUERY) {
+ return { kind: 'trending', queries, loading: input.queriesLoading, ...error };
+ }
+ return {
+ kind: 'suggesting',
+ queries,
+ loading: input.queriesLoading,
+ debouncing: input.settled !== input.session.normalized,
+ ...error,
+ };
+ }
+
+ const wanted = versesRequest(input.session);
+ const failed = wanted !== null && input.versesError !== null && !input.versesLoading;
+ const inFlight = wanted !== null && !failed;
+ const verses = projectVerses(flattenHits(input.session.lane.pages)).filter(
+ (verse) => input.bookIds === undefined || input.bookIds.includes(verse.book),
+ );
+
+ if (input.session.lane.pages.length === 0) {
+ if (failed && input.versesError !== null) {
+ return { kind: 'failed', error: input.versesError };
+ }
+ if (inFlight) {
+ return { kind: 'searching' };
+ }
+ }
+
+ const first = verses[0];
+ if (first === undefined) {
+ if (failed && input.versesError !== null) return { kind: 'failed', error: input.versesError };
+ if (
+ input.bookIds?.length !== 0 &&
+ nextPageStatus({ session: input.session, failed, inFlight }) !== 'none'
+ ) {
+ return { kind: 'searching' };
+ }
+ return { kind: 'empty' };
+ }
+
+ return {
+ kind: 'results',
+ verses: [first, ...verses.slice(1)],
+ nextPage: nextPageStatus({ session: input.session, failed, inFlight }),
+ };
+}
diff --git a/packages/hooks/src/test/utils.tsx b/packages/hooks/src/test/utils.tsx
index dcb6e177..54cc80ff 100644
--- a/packages/hooks/src/test/utils.tsx
+++ b/packages/hooks/src/test/utils.tsx
@@ -1,6 +1,12 @@
import { type ReactNode, type ComponentType } from 'react';
-import type { BibleClient, LanguagesClient, OrganizationsClient } from '@youversion/platform-core';
+import type {
+ BibleClient,
+ LanguagesClient,
+ OrganizationsClient,
+ SearchClient,
+} from '@youversion/platform-core';
import { YouVersionContext } from '../context';
+import type { HookOverrides } from '../hook-overrides';
import { TestQueryClientProvider } from '../test-utils';
export { TestQueryClientProvider };
@@ -10,6 +16,8 @@ export type YVWrapperOptions = {
bibleClient?: BibleClient;
languagesClient?: LanguagesClient;
organizationsClient?: OrganizationsClient;
+ searchClient?: SearchClient;
+ hookOverrides?: HookOverrides;
};
/** Builds a `BibleClient`-typed stub with only the methods the test calls. */
@@ -32,14 +40,29 @@ export function createOrganizationsClientStub(
return methods as OrganizationsClient;
}
+/** Builds a `SearchClient`-typed stub with only the methods the test calls. */
+export function createSearchClientStub(methods: Partial): SearchClient {
+ // SAFETY: stub implements the methods under test
+ return methods as SearchClient;
+}
+
export const createYVWrapper = (
appKey = 'test-app-key',
options: YVWrapperOptions = {},
): ComponentType<{ children: ReactNode }> => {
- const { theme, bibleClient, languagesClient, organizationsClient } = options;
+ const { theme, bibleClient, languagesClient, organizationsClient, searchClient, hookOverrides } =
+ options;
const Wrapper = ({ children }: { children: ReactNode }) => (
{children}
diff --git a/packages/hooks/src/useBibleSearch.test.tsx b/packages/hooks/src/useBibleSearch.test.tsx
new file mode 100644
index 00000000..96a9841c
--- /dev/null
+++ b/packages/hooks/src/useBibleSearch.test.tsx
@@ -0,0 +1,564 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { BibleVersion, SearchQueries, SearchVersesResponse } from '@youversion/platform-core';
+import { useBibleSearch, type UseBibleSearchResult } from './useBibleSearch';
+import {
+ SEARCH_SUGGESTION_DEBOUNCE_MS,
+ SEARCH_VERSES_PAGE_SIZE,
+} from './internal/bible-search-session';
+import { createBibleClientStub, createSearchClientStub, createYVWrapper } from './test/utils';
+
+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 trending: SearchQueries = { queries: [{ text: 'love' }, { text: 'hope' }] };
+const suggestions: SearchQueries = { queries: [{ text: 'love of God' }] };
+
+function versesPage(ids: readonly string[], nextPageToken: string | null): SearchVersesResponse {
+ return {
+ verses: ids.map((id) => ({ id })),
+ didYouMean: [],
+ searchInsteadFor: null,
+ nextPageToken,
+ };
+}
+
+async function settleDebounce(): Promise {
+ await act(async () => {
+ await new Promise((resolve) => {
+ setTimeout(resolve, SEARCH_SUGGESTION_DEBOUNCE_MS + 20);
+ });
+ });
+}
+
+function createSearchFixture() {
+ const mockGetVersion = vi.fn().mockResolvedValue(mockVersion);
+ const mockGetTrendingQueries = vi.fn().mockResolvedValue(trending);
+ const mockGetSuggestedQueries = vi.fn().mockResolvedValue(suggestions);
+ const mockSearchVerses = vi.fn().mockResolvedValue(versesPage(['JHN.3.16'], 'page-2'));
+
+ const bibleClient = createBibleClientStub({ getVersion: mockGetVersion });
+ const searchClient = createSearchClientStub({
+ getTrendingQueries: mockGetTrendingQueries,
+ getSuggestedQueries: mockGetSuggestedQueries,
+ searchVerses: mockSearchVerses,
+ });
+ const wrapper = createYVWrapper('test-app-key', { bibleClient, searchClient });
+
+ return {
+ wrapper,
+ bibleClient,
+ searchClient,
+ mockGetVersion,
+ mockGetTrendingQueries,
+ mockGetSuggestedQueries,
+ mockSearchVerses,
+ };
+}
+
+describe('useBibleSearch', () => {
+ it('resubmits failed and empty searches without replaying cached pages or duplicating an in-flight request', async () => {
+ const fixture = createSearchFixture();
+ let finishRetry!: (page: SearchVersesResponse) => void;
+ fixture.mockSearchVerses
+ .mockRejectedValueOnce(new Error('unavailable'))
+ .mockResolvedValueOnce(versesPage([], null))
+ .mockImplementationOnce(
+ () =>
+ new Promise((resolve) => {
+ finishRetry = resolve;
+ }),
+ );
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), {
+ wrapper: fixture.wrapper,
+ });
+ act(() => result.current.selectSuggestion('love'));
+ await waitFor(() => expect(result.current.phase.kind).toBe('failed'));
+ act(() => result.current.submit());
+ await waitFor(() => expect(result.current.phase.kind).toBe('empty'));
+ expect(fixture.mockSearchVerses).toHaveBeenCalledTimes(2);
+ act(() => result.current.submit());
+ expect(result.current.phase.kind).toBe('searching');
+ await waitFor(() => expect(fixture.mockSearchVerses).toHaveBeenCalledTimes(3));
+ act(() => result.current.submit());
+ act(() => result.current.selectSuggestion(' love '));
+ expect(result.current.query).toBe(' love ');
+ expect(result.current.phase.kind).toBe('searching');
+ expect(fixture.mockSearchVerses).toHaveBeenCalledTimes(3);
+ await act(async () => finishRetry(versesPage(['JHN.3.16'], null)));
+ await waitFor(() =>
+ expect(result.current.phase).toMatchObject({
+ kind: 'results',
+ verses: [{ id: 'JHN.3.16' }],
+ nextPage: 'none',
+ }),
+ );
+ expect(fixture.mockGetSuggestedQueries).not.toHaveBeenCalled();
+ });
+
+ it('replaces a failed continuation with loading immediately when the book filter changes', async () => {
+ const fixture = createSearchFixture();
+ let finishPage!: (page: SearchVersesResponse) => void;
+ fixture.mockSearchVerses
+ .mockResolvedValueOnce(versesPage(['PSA.91.1'], 'second'))
+ .mockRejectedValueOnce(new Error('page unavailable'))
+ .mockImplementationOnce(
+ () =>
+ new Promise((resolve) => {
+ finishPage = resolve;
+ }),
+ );
+ const { result, rerender } = renderHook(
+ ({ bookIds }) => useBibleSearch({ versionId: 111, bookIds }),
+ { wrapper: fixture.wrapper, initialProps: { bookIds: ['JHN'] } },
+ );
+ act(() => result.current.selectSuggestion('Psalm 91'));
+ await waitFor(() => expect(result.current.phase.kind).toBe('failed'));
+ rerender({ bookIds: ['PSA'] });
+ expect(result.current.phase).toMatchObject({ kind: 'results', nextPage: 'loading' });
+ await waitFor(() => expect(fixture.mockSearchVerses).toHaveBeenCalledTimes(3));
+ await act(async () => finishPage(versesPage([], null)));
+ await waitFor(() =>
+ expect(result.current.phase).toMatchObject({ kind: 'results', nextPage: 'none' }),
+ );
+ rerender({ bookIds: ['JHN'] });
+ expect(result.current.phase).toEqual({ kind: 'empty' });
+ });
+
+ it('skips nonmatching pages, retries failures, and reuses loaded results when the book filter changes', async () => {
+ const fixture = createSearchFixture();
+ const unavailable = new Error('page unavailable');
+ fixture.mockSearchVerses
+ .mockResolvedValueOnce(versesPage(['GEN.1.1'], 'second'))
+ .mockRejectedValueOnce(unavailable)
+ .mockResolvedValueOnce(versesPage(['PSA.23.1'], 'third'))
+ .mockResolvedValueOnce(versesPage(['JHN.3.16', 'GEN.1.2'], null));
+ const phases: string[] = [];
+ const { result, rerender } = renderHook<
+ UseBibleSearchResult,
+ { bookIds: readonly string[] | undefined }
+ >(
+ ({ bookIds }) => {
+ const search = useBibleSearch({ versionId: 111, bookIds });
+ phases.push(search.phase.kind);
+ return search;
+ },
+ { wrapper: fixture.wrapper, initialProps: { bookIds: ['JHN'] } },
+ );
+ act(() => result.current.selectSuggestion('love'));
+ await waitFor(() =>
+ expect(result.current.phase).toEqual({ kind: 'failed', error: unavailable }),
+ );
+ expect(phases).not.toContain('empty');
+ act(() => result.current.retry());
+ await waitFor(() =>
+ expect(result.current.phase).toMatchObject({
+ kind: 'results',
+ verses: [{ id: 'JHN.3.16' }],
+ nextPage: 'none',
+ }),
+ );
+ expect(fixture.mockSearchVerses.mock.calls.map((call) => call[2].pageToken)).toEqual([
+ undefined,
+ 'second',
+ 'second',
+ 'third',
+ ]);
+ rerender({ bookIds: undefined });
+ expect(result.current.phase).toMatchObject({
+ kind: 'results',
+ verses: [{ id: 'GEN.1.1' }, { id: 'PSA.23.1' }, { id: 'JHN.3.16' }, { id: 'GEN.1.2' }],
+ });
+ rerender({ bookIds: ['EXO'] });
+ expect(result.current.phase).toEqual({ kind: 'empty' });
+ expect(fixture.mockSearchVerses).toHaveBeenCalledTimes(4);
+ });
+
+ it('abandons filtered pagination when the query is cleared, ignoring its late response', async () => {
+ const fixture = createSearchFixture();
+ let finishPage!: (page: SearchVersesResponse) => void;
+ fixture.mockSearchVerses
+ .mockResolvedValueOnce(versesPage(['GEN.1.1'], 'second'))
+ .mockImplementationOnce(
+ () =>
+ new Promise((resolve) => {
+ finishPage = resolve;
+ }),
+ );
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111, bookIds: ['JHN'] }), {
+ wrapper: fixture.wrapper,
+ });
+ act(() => result.current.selectSuggestion('love'));
+ await waitFor(() => expect(fixture.mockSearchVerses).toHaveBeenCalledTimes(2));
+ expect(result.current.phase.kind).toBe('searching');
+ act(() => result.current.setQuery(''));
+ await act(async () => finishPage(versesPage(['JHN.3.16'], 'third')));
+ expect(result.current.phase.kind).toBe('trending');
+ expect(fixture.mockSearchVerses).toHaveBeenCalledTimes(2);
+ });
+
+ it('surfaces discovery failures, retries trending, and still submits after suggestions fail', async () => {
+ const { wrapper, mockGetTrendingQueries, mockGetSuggestedQueries, mockSearchVerses } =
+ createSearchFixture();
+ const unavailable = new Error('discovery unavailable');
+ mockGetTrendingQueries.mockRejectedValueOnce(unavailable);
+ mockGetSuggestedQueries.mockRejectedValueOnce(unavailable);
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+ await waitFor(() =>
+ expect(result.current.phase).toMatchObject({
+ kind: 'trending',
+ loading: false,
+ error: unavailable,
+ }),
+ );
+ act(() => result.current.retry());
+ await waitFor(() =>
+ expect(result.current.phase).toEqual({
+ kind: 'trending',
+ queries: trending.queries,
+ loading: false,
+ }),
+ );
+ act(() => result.current.setQuery('mercy'));
+ await settleDebounce();
+ await waitFor(() =>
+ expect(result.current.phase).toMatchObject({
+ kind: 'suggesting',
+ loading: false,
+ error: unavailable,
+ }),
+ );
+ act(() => result.current.submit());
+ await waitFor(() => expect(result.current.phase.kind).toBe('results'));
+ expect(result.current.query).toBe('mercy');
+ expect(mockSearchVerses).toHaveBeenCalledWith('mercy', 111, {
+ pageSize: SEARCH_VERSES_PAGE_SIZE,
+ });
+ });
+
+ it('waits for version.language_tag before requesting trending', async () => {
+ const { wrapper, mockGetVersion, mockGetTrendingQueries } = createSearchFixture();
+ let resolveVersion: (version: BibleVersion) => void = () => {};
+ mockGetVersion.mockReturnValue(
+ new Promise((resolve) => {
+ resolveVersion = resolve;
+ }),
+ );
+
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+
+ await act(async () => {
+ await Promise.resolve();
+ });
+
+ expect(mockGetTrendingQueries).not.toHaveBeenCalled();
+ expect(result.current.phase).toEqual({ kind: 'trending', queries: [], loading: false });
+
+ await act(async () => {
+ resolveVersion(mockVersion);
+ });
+
+ await waitFor(() => {
+ expect(mockGetTrendingQueries).toHaveBeenCalledWith('en');
+ });
+ await waitFor(() => {
+ expect(result.current.phase).toEqual({
+ kind: 'trending',
+ queries: trending.queries,
+ loading: false,
+ });
+ });
+ });
+
+ it('falls back to wildcard discovery when version metadata fails', async () => {
+ const { wrapper, mockGetVersion, mockGetTrendingQueries } = createSearchFixture();
+ mockGetVersion.mockRejectedValueOnce(new Error('metadata unavailable'));
+
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+
+ await waitFor(() => {
+ expect(mockGetTrendingQueries).toHaveBeenCalledWith('*');
+ });
+ await waitFor(() => {
+ expect(result.current.phase).toEqual({
+ kind: 'trending',
+ queries: trending.queries,
+ loading: false,
+ });
+ });
+ });
+
+ it.each(['', 'not a language tag'])(
+ 'falls back to wildcard discovery for unusable language tag %j',
+ async (languageTag) => {
+ const { wrapper, mockGetVersion, mockGetTrendingQueries } = createSearchFixture();
+ mockGetVersion.mockResolvedValueOnce({ ...mockVersion, language_tag: languageTag });
+
+ renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+
+ await waitFor(() => {
+ expect(mockGetTrendingQueries).toHaveBeenCalledWith('*');
+ });
+ },
+ );
+
+ it('debounces suggestions without requesting or displaying a stale query', async () => {
+ const { wrapper, mockGetSuggestedQueries } = createSearchFixture();
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+
+ await waitFor(() => {
+ expect(result.current.phase).toEqual({
+ kind: 'trending',
+ queries: trending.queries,
+ loading: false,
+ });
+ });
+
+ act(() => {
+ result.current.setQuery('love');
+ });
+
+ expect(result.current.query).toBe('love');
+ expect(result.current.phase).toEqual({
+ kind: 'suggesting',
+ queries: [],
+ loading: false,
+ debouncing: true,
+ });
+ expect(mockGetSuggestedQueries).not.toHaveBeenCalled();
+
+ await settleDebounce();
+
+ await waitFor(() => {
+ expect(mockGetSuggestedQueries).toHaveBeenCalledWith('love', 'en');
+ });
+ await waitFor(() => {
+ expect(result.current.phase).toEqual({
+ kind: 'suggesting',
+ queries: suggestions.queries,
+ loading: false,
+ debouncing: false,
+ });
+ });
+ });
+
+ it('supersedes an earlier suggestion response as soon as normalized input changes', async () => {
+ const { wrapper, mockGetSuggestedQueries } = createSearchFixture();
+ let resolveEarlier: (value: SearchQueries) => void = () => {};
+ mockGetSuggestedQueries.mockReturnValueOnce(
+ new Promise((resolve) => {
+ resolveEarlier = resolve;
+ }),
+ );
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+
+ await waitFor(() => {
+ expect(result.current.phase.kind).toBe('trending');
+ });
+ act(() => {
+ result.current.setQuery('love');
+ });
+ await settleDebounce();
+ await waitFor(() => {
+ expect(mockGetSuggestedQueries).toHaveBeenCalledWith('love', 'en');
+ });
+
+ act(() => {
+ result.current.setQuery('loved');
+ });
+ expect(result.current.phase).toEqual({
+ kind: 'suggesting',
+ queries: [],
+ loading: false,
+ debouncing: true,
+ });
+
+ await act(async () => {
+ resolveEarlier({ queries: [{ text: 'stale love' }] });
+ });
+ expect(result.current.phase).toEqual({
+ kind: 'suggesting',
+ queries: [],
+ loading: false,
+ debouncing: true,
+ });
+ });
+
+ it('submits verses, suppresses suggestions, paginates, and retries a failed next page', async () => {
+ const { wrapper, mockGetSuggestedQueries, mockSearchVerses } = createSearchFixture();
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+
+ await waitFor(() => {
+ expect(result.current.phase.kind).toBe('trending');
+ });
+
+ act(() => {
+ result.current.setQuery('love');
+ });
+ await settleDebounce();
+ await waitFor(() => {
+ expect(mockGetSuggestedQueries).toHaveBeenCalledTimes(1);
+ });
+
+ mockGetSuggestedQueries.mockClear();
+ act(() => {
+ result.current.submit();
+ });
+
+ expect(mockGetSuggestedQueries).not.toHaveBeenCalled();
+ await waitFor(() => {
+ expect(mockSearchVerses).toHaveBeenCalledWith('love', 111, {
+ pageSize: SEARCH_VERSES_PAGE_SIZE,
+ });
+ });
+ await waitFor(() => {
+ expect(result.current.phase).toEqual({
+ kind: 'results',
+ verses: [{ id: 'JHN.3.16', book: 'JHN', chapter: '3', verses: [16] }],
+ nextPage: 'available',
+ });
+ });
+
+ mockSearchVerses.mockRejectedValueOnce(new Error('page 2 failed'));
+ act(() => {
+ result.current.loadMore();
+ });
+
+ await waitFor(() => {
+ expect(mockSearchVerses).toHaveBeenCalledWith('love', 111, {
+ pageSize: SEARCH_VERSES_PAGE_SIZE,
+ pageToken: 'page-2',
+ });
+ });
+ await waitFor(() => {
+ expect(result.current.phase).toEqual({
+ kind: 'results',
+ verses: [{ id: 'JHN.3.16', book: 'JHN', chapter: '3', verses: [16] }],
+ nextPage: 'failed',
+ });
+ });
+
+ mockSearchVerses.mockResolvedValueOnce(versesPage(['JHN.3.16', 'ROM.8.28'], null));
+ act(() => {
+ result.current.retry();
+ });
+
+ await waitFor(() => {
+ expect(result.current.phase).toEqual({
+ kind: 'results',
+ verses: [
+ { id: 'JHN.3.16', book: 'JHN', chapter: '3', verses: [16] },
+ { id: 'ROM.8.28', book: 'ROM', chapter: '8', verses: [28] },
+ ],
+ nextPage: 'none',
+ });
+ });
+ });
+
+ it('does not re-request the submitted query as suggestions during the first edit debounce', async () => {
+ const { wrapper, mockGetSuggestedQueries } = createSearchFixture();
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+
+ await waitFor(() => {
+ expect(result.current.phase.kind).toBe('trending');
+ });
+
+ act(() => {
+ result.current.setQuery('love');
+ });
+ await settleDebounce();
+ await waitFor(() => {
+ expect(mockGetSuggestedQueries).toHaveBeenCalledTimes(1);
+ });
+
+ act(() => {
+ result.current.submit();
+ });
+ await waitFor(() => {
+ expect(result.current.phase.kind).toBe('results');
+ });
+
+ mockGetSuggestedQueries.mockClear();
+ act(() => {
+ result.current.setQuery('loved');
+ });
+
+ expect(mockGetSuggestedQueries).not.toHaveBeenCalled();
+ expect(result.current.phase).toEqual({
+ kind: 'suggesting',
+ queries: [],
+ loading: false,
+ debouncing: true,
+ });
+
+ await settleDebounce();
+
+ await waitFor(() => {
+ expect(mockGetSuggestedQueries).toHaveBeenCalledTimes(1);
+ });
+ expect(mockGetSuggestedQueries).toHaveBeenCalledWith('loved', 'en');
+ expect(mockGetSuggestedQueries).not.toHaveBeenCalledWith('love', 'en');
+ });
+
+ it('selectSuggestion submits immediately without a filled-but-idle frame', async () => {
+ const { wrapper, mockSearchVerses } = createSearchFixture();
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), { wrapper });
+
+ await waitFor(() => {
+ expect(result.current.phase.kind).toBe('trending');
+ });
+
+ act(() => {
+ result.current.selectSuggestion('love of God');
+ });
+
+ expect(result.current.query).toBe('love of God');
+ expect(result.current.phase.kind).toBe('searching');
+ await waitFor(() => {
+ expect(mockSearchVerses).toHaveBeenCalledWith('love of God', 111, {
+ pageSize: SEARCH_VERSES_PAGE_SIZE,
+ });
+ });
+ });
+
+ it('returns the hook override without fetching search', async () => {
+ const { bibleClient, searchClient, mockGetTrendingQueries, mockSearchVerses } =
+ createSearchFixture();
+ const stub: UseBibleSearchResult = {
+ query: 'love',
+ phase: { kind: 'empty' },
+ setQuery: () => {},
+ submit: () => {},
+ selectSuggestion: () => {},
+ loadMore: () => {},
+ retry: () => {},
+ };
+ const overrideWrapper = createYVWrapper('test-app-key', {
+ bibleClient,
+ searchClient,
+ hookOverrides: { useBibleSearch: () => stub },
+ });
+
+ const { result } = renderHook(() => useBibleSearch({ versionId: 111 }), {
+ wrapper: overrideWrapper,
+ });
+
+ expect(result.current).toBe(stub);
+ await act(async () => {
+ await Promise.resolve();
+ });
+ expect(mockGetTrendingQueries).not.toHaveBeenCalled();
+ expect(mockSearchVerses).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/hooks/src/useBibleSearch.ts b/packages/hooks/src/useBibleSearch.ts
new file mode 100644
index 00000000..a56020e2
--- /dev/null
+++ b/packages/hooks/src/useBibleSearch.ts
@@ -0,0 +1,182 @@
+'use client';
+
+import { useCallback, useEffect, useReducer, useState } from 'react';
+import { parseSearchLanguageRange, type SearchVersesOptions } from '@youversion/platform-core';
+import { useApiData } from './useApiData';
+import { useHookOverride } from './useHookOverride';
+import { useQueryKeyBase } from './internal/useQueryKeyBase';
+import { useSearchClient } from './useSearchClient';
+import { useVersion } from './useVersion';
+import { useDebounce } from './utility/useDebounce';
+import {
+ EMPTY_QUERY,
+ SEARCH_SUGGESTION_DEBOUNCE_MS,
+ SEARCH_VERSES_PAGE_SIZE,
+ clampSearchInput,
+ createSearchSession,
+ deriveSearchPhase,
+ normalizeQuery,
+ queriesRequest,
+ searchSessionReducer,
+ versesRequest,
+ type BibleSearchPhase,
+ type BibleSearchResult,
+} from './internal/bible-search-session';
+
+export type { BibleSearchPhase, BibleSearchResult };
+
+export type UseBibleSearchProps = Readonly<{
+ versionId: number;
+ /** Client-side result filter. Unset includes all books; empty includes none.
+ * Pages without matches are skipped until a match or the end is reached. */
+ bookIds?: readonly string[];
+}>;
+
+export type UseBibleSearchResult = Readonly<{
+ query: string;
+ phase: BibleSearchPhase;
+ setQuery: (raw: string) => void;
+ submit: () => void;
+ selectSuggestion: (text: string) => void;
+ loadMore: () => void;
+ /** Re-requests failed suggestions, the initial search, or a failed results page. */
+ retry: () => void;
+}>;
+
+export function useBibleSearch(props: UseBibleSearchProps): UseBibleSearchResult {
+ const { versionId } = props;
+ const override = useHookOverride('useBibleSearch');
+ const client = useSearchClient();
+ const keyBase = useQueryKeyBase();
+ const [session, dispatch] = useReducer(searchSessionReducer, versionId, createSearchSession);
+ const [submission, setSubmission] = useState(0);
+
+ useEffect(() => {
+ dispatch({ type: 'setVersion', versionId });
+ }, [versionId]);
+
+ const { version, loading: versionLoading } = useVersion(versionId);
+ let languageRanges: string | null = null;
+ if (!versionLoading) {
+ try {
+ languageRanges = parseSearchLanguageRange(version?.language_tag ?? '*');
+ } catch {
+ languageRanges = '*';
+ }
+ }
+ const debounced = useDebounce(session.normalized, SEARCH_SUGGESTION_DEBOUNCE_MS);
+ const settled = session.normalized === EMPTY_QUERY ? EMPTY_QUERY : debounced;
+ const qReq = queriesRequest(session, settled);
+ const suggestQuery = qReq?.kind === 'suggest' ? qReq.query : '';
+ const queries = useApiData(
+ [...keyBase, 'searchQueries', languageRanges, qReq?.kind ?? 'off', suggestQuery],
+ () => {
+ if (qReq === null || languageRanges === null) {
+ return Promise.reject(new Error('search queries requested while disabled'));
+ }
+ return qReq.kind === 'trending'
+ ? client.getTrendingQueries(languageRanges)
+ : client.getSuggestedQueries(qReq.query, languageRanges);
+ },
+ {
+ enabled: !override && qReq !== null && languageRanges !== null,
+ keepPreviousData: false,
+ },
+ );
+
+ const vReq = versesRequest(session);
+ const verses = useApiData(
+ [
+ ...keyBase,
+ 'searchVerses',
+ vReq?.versionId,
+ vReq?.query ?? '',
+ vReq?.pageToken ?? '',
+ props.bookIds,
+ submission,
+ ],
+ () => {
+ if (vReq === null) {
+ return Promise.reject(new Error('search verses requested while disabled'));
+ }
+ const options: SearchVersesOptions = { pageSize: SEARCH_VERSES_PAGE_SIZE };
+ if (vReq.pageToken !== null) {
+ options.pageToken = vReq.pageToken;
+ }
+ return client.searchVerses(vReq.query, vReq.versionId, options);
+ },
+ {
+ enabled: !override && vReq !== null,
+ keepPreviousData: false,
+ },
+ );
+
+ useEffect(() => {
+ const request = versesRequest(session);
+ if (request !== null && verses.data !== null) {
+ dispatch({ type: 'commitPage', request, response: verses.data });
+ }
+ }, [session, verses.data]);
+
+ const setQuery = useCallback((raw: string) => {
+ dispatch({ type: 'setQuery', raw });
+ }, []);
+ const selectSuggestion = useCallback(
+ (text: string) => {
+ const normalized = normalizeQuery(clampSearchInput(text));
+ if (session.lane.kind === 'submitted' && session.lane.query === normalized) {
+ if (verses.loading) {
+ dispatch({ type: 'setQuery', raw: text });
+ return;
+ }
+ // A deliberate resubmission must not recommit a cached empty or failed search.
+ setSubmission((previous) => previous + 1);
+ }
+ dispatch({ type: 'selectSuggestion', text });
+ },
+ [session.lane, verses.loading],
+ );
+ const submit = useCallback(() => {
+ selectSuggestion(session.raw);
+ }, [selectSuggestion, session.raw]);
+ const loadMore = useCallback(() => {
+ dispatch({ type: 'loadMore' });
+ }, []);
+ const retry = useCallback(() => {
+ if (vReq !== null && verses.error !== null) {
+ verses.refetch();
+ } else if (qReq !== null && queries.error !== null) {
+ queries.refetch();
+ }
+ }, [vReq, verses, qReq, queries]);
+
+ const phase = deriveSearchPhase({
+ session,
+ bookIds: props.bookIds,
+ settled,
+ queries: queries.data?.queries ?? null,
+ queriesLoading: queries.loading,
+ queriesError: queries.error,
+ versesLoading: verses.loading,
+ versesError: verses.error,
+ });
+ useEffect(() => {
+ if (!override && phase.kind === 'searching' && vReq === null) {
+ dispatch({ type: 'loadMore' });
+ }
+ }, [override, phase.kind, vReq]);
+
+ if (override) {
+ return override(props);
+ }
+
+ return {
+ query: session.raw,
+ phase,
+ setQuery,
+ submit,
+ selectSuggestion,
+ loadMore,
+ retry,
+ };
+}
diff --git a/packages/hooks/src/useSearchClient.test.tsx b/packages/hooks/src/useSearchClient.test.tsx
new file mode 100644
index 00000000..25351677
--- /dev/null
+++ b/packages/hooks/src/useSearchClient.test.tsx
@@ -0,0 +1,50 @@
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import type { ReactNode } from 'react';
+import { SearchClient } from '@youversion/platform-core';
+import { useSearchClient } from './useSearchClient';
+import { YouVersionContext } from './context';
+import { createSearchClientStub, createYVWrapper } from './test/utils';
+
+describe('useSearchClient', () => {
+ it('creates a SearchClient when context is valid', () => {
+ const wrapper = createYVWrapper();
+ const { result } = renderHook(() => useSearchClient(), { wrapper });
+
+ expect(result.current).toBeInstanceOf(SearchClient);
+ });
+
+ it('returns the injected SearchClient when present', () => {
+ const searchClient = createSearchClientStub({});
+ const wrapper = createYVWrapper('test-app-key', { searchClient });
+ const { result } = renderHook(() => useSearchClient(), { wrapper });
+
+ expect(result.current).toBe(searchClient);
+ });
+
+ it('throws when context is not provided', () => {
+ expect(() => renderHook(() => useSearchClient())).toThrow(
+ 'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
+ );
+ });
+
+ it('throws when appKey is missing', () => {
+ const wrapper = ({ children }: { children: ReactNode }) => (
+ {children}
+ );
+
+ expect(() => renderHook(() => useSearchClient(), { wrapper })).toThrow(
+ 'YouVersion context not found. Make sure your component is wrapped with YouVersionProvider and an API key is provided.',
+ );
+ });
+
+ it('memoizes the SearchClient instance', () => {
+ const wrapper = createYVWrapper();
+ const { result, rerender } = renderHook(() => useSearchClient(), { wrapper });
+ const firstClient = result.current;
+
+ rerender();
+
+ expect(result.current).toBe(firstClient);
+ });
+});
diff --git a/packages/hooks/src/useSearchClient.ts b/packages/hooks/src/useSearchClient.ts
new file mode 100644
index 00000000..faa5f933
--- /dev/null
+++ b/packages/hooks/src/useSearchClient.ts
@@ -0,0 +1,14 @@
+'use client';
+
+import { useContext, useMemo } from 'react';
+import { SearchClient } from '@youversion/platform-core';
+import { YouVersionContext } from './context';
+import { useApiClient } from './internal/useApiClient';
+
+/** Mirrors `useBibleClient`. `YouVersionContext.searchClient` wins in tests. */
+export function useSearchClient(): SearchClient {
+ const override = useContext(YouVersionContext)?.searchClient;
+ const apiClient = useApiClient();
+ const constructed = useMemo(() => new SearchClient(apiClient), [apiClient]);
+ return override ?? constructed;
+}
diff --git a/packages/hooks/src/utility/useDebounce.test.tsx b/packages/hooks/src/utility/useDebounce.test.tsx
index 01dcd30e..2d74cad3 100644
--- a/packages/hooks/src/utility/useDebounce.test.tsx
+++ b/packages/hooks/src/utility/useDebounce.test.tsx
@@ -92,4 +92,45 @@ describe('useDebounce', () => {
expect(result.current).toBe('updated');
});
+
+ it('debounces null like any other value and cancels it when superseded', () => {
+ type NullableProps = { value: string | null };
+ const { result, rerender } = renderHook(
+ ({ value }) => useDebounce(value, 500),
+ { initialProps: { value: 'love' } },
+ );
+
+ rerender({ value: null });
+ expect(result.current).toBe('love');
+ act(() => {
+ vi.advanceTimersByTime(499);
+ });
+ expect(result.current).toBe('love');
+ act(() => {
+ vi.advanceTimersByTime(1);
+ });
+ expect(result.current).toBeNull();
+
+ rerender({ value: 'loved' });
+ expect(result.current).toBeNull();
+
+ act(() => {
+ vi.advanceTimersByTime(500);
+ });
+
+ expect(result.current).toBe('loved');
+ rerender({ value: null });
+ act(() => {
+ vi.advanceTimersByTime(300);
+ });
+ rerender({ value: 'hope' });
+ act(() => {
+ vi.advanceTimersByTime(200);
+ });
+ expect(result.current).toBe('loved');
+ act(() => {
+ vi.advanceTimersByTime(300);
+ });
+ expect(result.current).toBe('hope');
+ });
});
diff --git a/packages/ui/package.json b/packages/ui/package.json
index f0646cd4..f9d88380 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -69,7 +69,8 @@
"react-i18next": "^17.0.0",
"tailwind-merge": "3.3.1",
"tw-animate-css": "1.4.0",
- "xstate": "5.32.4"
+ "xstate": "5.32.4",
+ "zod": "4.1.12"
},
"peerDependencies": {
"react": ">=19.1.0 <20.0.0",
diff --git a/packages/ui/src/components/bible-reader-controlled.test.tsx b/packages/ui/src/components/bible-reader-controlled.test.tsx
index 50809895..8111d4e4 100644
--- a/packages/ui/src/components/bible-reader-controlled.test.tsx
+++ b/packages/ui/src/components/bible-reader-controlled.test.tsx
@@ -118,6 +118,15 @@ function defaultOverrides(): HookOverrides {
}),
useFilteredVersions: () => [],
useOrganizations: () => ({ organizations: new Map() }),
+ useBibleSearch: () => ({
+ query: '',
+ phase: { kind: 'trending', queries: [], loading: false },
+ setQuery: () => undefined,
+ submit: () => undefined,
+ selectSuggestion: () => undefined,
+ loadMore: () => undefined,
+ retry: () => undefined,
+ }),
};
}
diff --git a/packages/ui/src/components/bible-reader-navigation.test.tsx b/packages/ui/src/components/bible-reader-navigation.test.tsx
new file mode 100644
index 00000000..e6a90711
--- /dev/null
+++ b/packages/ui/src/components/bible-reader-navigation.test.tsx
@@ -0,0 +1,188 @@
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { expect, it, vi } from 'vitest';
+import { StrictMode } from 'react';
+import { BibleReader, useBibleReaderContext } from './bible-reader';
+import { BibleReaderNavigation } from './bible-reader-navigation';
+import { HookOverrideProvider } from '@/test/hook-overrides';
+import type { HookOverrides } from '@youversion/platform-react-hooks';
+
+function CurrentDestination() {
+ const { book, chapter, versionId, verseFocus } = useBibleReaderContext();
+ return (
+
+ );
+}
+
+it('consumes the newest pre-mount request once and supports mounted cross-version, range and in-place focus requests', () => {
+ const navigation = new BibleReaderNavigation();
+ const changed = vi.fn();
+ navigation.request({ versionId: 111, passageId: 'ROM.8.28' });
+ navigation.request({ versionId: 3034, passageId: 'JHN.3.16-18' });
+ const overrides: HookOverrides = {
+ useBooks: () => ({ books: null, loading: false, error: null, refetch: () => {} }),
+ };
+ const jsx = (
+
+
+
+
+
+
+
+ );
+ const view = render(jsx);
+ const destination = () =>
+ JSON.parse(screen.getByRole('status', { name: 'destination' }).textContent ?? '{}');
+ expect(destination()).toMatchObject({
+ versionId: 3034,
+ book: 'JHN',
+ chapter: '3',
+ verseFocus: {
+ verses: [16, 17, 18],
+ showsFullChapter: false,
+ shouldFocus: false,
+ },
+ });
+ expect(changed).toHaveBeenCalledTimes(1);
+ act(() => navigation.focusReference({ versionId: 3034, passageId: 'JHN.3.17' }, false));
+ expect(destination().verseFocus).toMatchObject({
+ verses: [17],
+ scrollsToVerse: false,
+ shouldFocus: true,
+ });
+ act(() => navigation.focusReference({ versionId: 111, passageId: 'ROM.8.28' }, false));
+ expect(destination()).toMatchObject({ versionId: 3034, book: 'JHN', chapter: '3' });
+ act(() => navigation.focusReference({ versionId: 111, passageId: 'ROM.8.28' }));
+ expect(destination()).toMatchObject({
+ versionId: 111,
+ book: 'ROM',
+ chapter: '8',
+ verseFocus: {
+ verses: [28],
+ showsFullChapter: true,
+ scrollsToVerse: true,
+ shouldFocus: true,
+ },
+ });
+ view.unmount();
+ render(jsx);
+ expect(destination()).toMatchObject({
+ versionId: 111,
+ book: 'JHN',
+ chapter: '1',
+ verseFocus: null,
+ });
+});
+
+it('renders passage-only and full-chapter destinations through the reader fetch', async ({
+ onTestFinished,
+}) => {
+ const scrollTo = Object.getOwnPropertyDescriptor(Element.prototype, 'scrollTo');
+ Element.prototype.scrollTo = vi.fn();
+ onTestFinished(() => {
+ Object.defineProperty(
+ Element.prototype,
+ 'scrollTo',
+ scrollTo ?? { value: undefined, configurable: true, writable: true },
+ );
+ });
+ const navigation = new BibleReaderNavigation();
+ const requested = vi.fn();
+ const overrides: HookOverrides = {
+ useBooks: () => ({ books: null, loading: false, error: null, refetch: () => {} }),
+ useVersion: () => ({ version: null, loading: false, error: null, refetch: () => {} }),
+ usePassage: (props) => {
+ requested(props.versionId, props.usfm);
+ return { passage: null, loading: true, error: null, refetch: () => {} };
+ },
+ };
+ navigation.request({ versionId: 3034, passageId: 'JHN.3.16-18' });
+ render(
+
+
+
+
+
+
+ ,
+ );
+ await waitFor(() => expect(requested).toHaveBeenLastCalledWith(3034, 'JHN.3.16-18'));
+ expect(
+ requested.mock.calls.every(
+ ([version, passage]) => version === 3034 && passage === 'JHN.3.16-18',
+ ),
+ ).toBe(true);
+ act(() => navigation.request({ versionId: 111, passageId: 'ROM.8.28' }, true));
+ await waitFor(() => expect(requested).toHaveBeenLastCalledWith(111, 'ROM.8'));
+});
+
+it('waits for controlled destinations and never revives an activated passage or focus after leaving it', ({
+ onTestFinished,
+}) => {
+ const scrollTo = Object.getOwnPropertyDescriptor(Element.prototype, 'scrollTo');
+ Element.prototype.scrollTo = vi.fn();
+ onTestFinished(() => {
+ Object.defineProperty(
+ Element.prototype,
+ 'scrollTo',
+ scrollTo ?? { value: undefined, configurable: true, writable: true },
+ );
+ });
+ const navigation = new BibleReaderNavigation();
+ navigation.request({ versionId: 3034, passageId: 'JHN.3.16' });
+ const requested = vi.fn();
+ const changed = vi.fn();
+ const overrides: HookOverrides = {
+ useBooks: () => ({ books: null, loading: false, error: null, refetch: () => {} }),
+ useVersion: () => ({ version: null, loading: false, error: null, refetch: () => {} }),
+ usePassage: (props) => {
+ if (props.options?.enabled) requested(props.versionId, props.usfm);
+ return { passage: null, loading: true, error: null, refetch: () => {} };
+ },
+ };
+ const reader = (versionId: number, book: string, chapter: string) => (
+
+
+
+
+
+
+
+
+ );
+ const view = render(reader(111, 'ROM', '8'));
+ const destination = () =>
+ JSON.parse(screen.getByRole('status', { name: 'destination' }).textContent ?? '{}');
+ expect(requested).not.toHaveBeenCalled();
+ expect(changed.mock.calls).toEqual([[3034], ['JHN'], ['3']]);
+ // A host can round-trip the controlled fields separately.
+ view.rerender(reader(3034, 'ROM', '8'));
+ expect(requested).not.toHaveBeenCalled();
+ view.rerender(reader(3034, 'JHN', '3'));
+ expect(requested).toHaveBeenLastCalledWith(3034, 'JHN.3.16');
+ view.rerender(reader(3034, 'JHN', '4'));
+ expect(destination().verseFocus).toBeNull();
+ view.rerender(reader(3034, 'JHN', '3'));
+ expect(requested).toHaveBeenLastCalledWith(3034, 'JHN.3');
+ act(() => navigation.focusReference({ versionId: 111, passageId: 'ROM.8.28' }));
+ expect(destination().verseFocus).toMatchObject({ passageId: 'ROM.8.28', shouldFocus: true });
+ view.rerender(reader(111, 'JHN', '3'));
+ expect(destination().verseFocus).not.toBeNull();
+ view.rerender(reader(111, 'ROM', '8'));
+ expect(requested).toHaveBeenLastCalledWith(111, 'ROM.8');
+ view.rerender(reader(3034, 'ROM', '8'));
+ expect(destination().verseFocus).toBeNull();
+ view.rerender(reader(111, 'ROM', '8'));
+ expect(destination().verseFocus).toBeNull();
+});
diff --git a/packages/ui/src/components/bible-reader-navigation.ts b/packages/ui/src/components/bible-reader-navigation.ts
new file mode 100644
index 00000000..b94b257e
--- /dev/null
+++ b/packages/ui/src/components/bible-reader-navigation.ts
@@ -0,0 +1,75 @@
+import { parseUsfmReference } from '@youversion/platform-core';
+
+export type BibleReaderReference = Readonly<{
+ versionId: number;
+ passageId: string;
+}>;
+
+/** @internal */
+export type BibleReaderNavigationRequest = BibleReaderReference &
+ Readonly<{
+ book: string;
+ chapter: string;
+ verses: readonly number[];
+ showsFullChapter: boolean;
+ scrollsToVerse: boolean;
+ shouldFocus: boolean;
+ }>;
+
+/**
+ * A host-owned connection to `BibleReader.Root` via its `navigation` prop.
+ * Create once and retain it outside the reader. Before mount, the newest request
+ * replaces any pending request. Mounting consumes that request once.
+ */
+export class BibleReaderNavigation {
+ private pending: BibleReaderNavigationRequest | null = null;
+ private listeners = new Set<() => void>();
+
+ /** Show a passage, or its full chapter. Ordinary navigation does not focus. */
+ request(reference: BibleReaderReference, showsFullChapter = false): void {
+ this.enqueue(reference, showsFullChapter, true, false);
+ }
+
+ /**
+ * Show the full chapter, scroll to the passage, then focus its verses.
+ * With `scrollsToVerse: false`, focus only if that chapter/version is already
+ * displayed, without navigating or changing the scroll position.
+ */
+ focusReference(reference: BibleReaderReference, scrollsToVerse = true): void {
+ this.enqueue(reference, true, scrollsToVerse, true);
+ }
+
+ private enqueue(
+ reference: BibleReaderReference,
+ showsFullChapter: boolean,
+ scrollsToVerse: boolean,
+ shouldFocus: boolean,
+ ): void {
+ const parsed = parseUsfmReference(reference.passageId);
+ if (parsed === null || !Number.isSafeInteger(reference.versionId) || reference.versionId <= 0) {
+ throw new Error('Reader navigation requires a valid passage ID and Bible version ID');
+ }
+ this.pending = { ...reference, ...parsed, showsFullChapter, scrollsToVerse, shouldFocus };
+ for (const listener of this.listeners) listener();
+ }
+
+ /** @internal Read without consuming during render; consume only after commit. */
+ peek(): BibleReaderNavigationRequest | null {
+ return this.pending;
+ }
+
+ /** @internal */
+ consume(): BibleReaderNavigationRequest | null {
+ const request = this.pending;
+ this.pending = null;
+ return request;
+ }
+
+ /** @internal */
+ subscribe(listener: () => void): () => void {
+ this.listeners.add(listener);
+ return () => {
+ this.listeners.delete(listener);
+ };
+ }
+}
diff --git a/packages/ui/src/components/bible-reader-search.stories.tsx b/packages/ui/src/components/bible-reader-search.stories.tsx
new file mode 100644
index 00000000..c775d63d
--- /dev/null
+++ b/packages/ui/src/components/bible-reader-search.stories.tsx
@@ -0,0 +1,331 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, screen, userEvent, waitFor, within } from 'storybook/test';
+import { BibleReader } from './bible-reader';
+import { useState } from 'react';
+import { BibleReaderNavigation } from './bible-reader-navigation';
+import { Button } from './ui/button';
+import { delay, http, HttpResponse } from 'msw';
+import { globalHandlers } from '@/test/mocks/handlers';
+
+const meta = {
+ title: 'Components/BibleReaderSearch',
+ component: BibleReader.Root,
+ parameters: {
+ layout: 'fullscreen',
+ },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+export const OpenTrending: Story = {
+ tags: ['integration'],
+ args: {
+ defaultVersionId: 111,
+ defaultBook: 'JHN',
+ defaultChapter: '1',
+ },
+ render: (args) => (
+
+
+
+
+
+
+ ),
+ play: async ({ canvasElement }) => {
+ await waitFor(
+ async () => {
+ const verseContainer = canvasElement.querySelector('[data-slot="yv-bible-renderer"]');
+ await expect(verseContainer).toBeInTheDocument();
+ },
+ { timeout: 5000 },
+ );
+
+ const searchButton = await waitFor(
+ () => screen.getByRole('button', { name: 'Search the Bible' }),
+ { timeout: 5000 },
+ );
+ await userEvent.click(searchButton);
+
+ await waitFor(async () => {
+ await expect(
+ within(screen.getByRole('region', { name: 'Trending Searches' })).getByRole('button', {
+ name: 'love',
+ }),
+ ).toBeInTheDocument();
+ });
+ },
+};
+
+/** Host-owned navigation created before the reader mounts. */
+function NavigationExample() {
+ const [navigation] = useState(() => {
+ const connection = new BibleReaderNavigation();
+ connection.focusReference({ versionId: 111, passageId: 'JHN.1.51' });
+ return connection;
+ });
+ return (
+
+
+
+
+
+
+
+
+
{`${book}.${chapter}`}
+
+
+ );
+ }
+
+ const user = userEvent.setup();
+ render();
+
+ expect(screen.getByTestId('location')).toHaveTextContent('JHN.1');
+ await user.click(screen.getByRole('button', { name: /john 3:16/i }));
+ expect(screen.getByTestId('location')).toHaveTextContent('JHN.3');
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ });
+});
+
+describe('BibleReader.Toolbar search control', () => {
+ it('passes serializable reader context to an async override without opening built-in search', async () => {
+ const onSearchPress = vi.fn(async () => undefined);
+ const user = userEvent.setup();
+ render(
+
+
+
+
+ ,
+ );
+ await user.click(screen.getByRole('button', { name: 'Search the Bible' }));
+ expect(onSearchPress).toHaveBeenCalledExactlyOnceWith({
+ versionId: 111,
+ book: 'JHN',
+ chapter: '3',
+ });
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ });
+
+ it('omits the search trigger when search is none', () => {
+ render(
+
+
+
+
+ ,
+ );
+
+ expect(screen.queryByRole('button', { name: 'Search the Bible' })).not.toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Settings' })).toBeInTheDocument();
+ });
+});
diff --git a/packages/ui/src/components/bible-reader-search.tsx b/packages/ui/src/components/bible-reader-search.tsx
new file mode 100644
index 00000000..28543877
--- /dev/null
+++ b/packages/ui/src/components/bible-reader-search.tsx
@@ -0,0 +1,689 @@
+'use client';
+
+import i18n from '@/i18n';
+import { buildVerseReference } from '@/lib/verse-share';
+import { useRecentSearches } from '@/lib/use-recent-searches';
+import { cn } from '@/lib/utils';
+import { useControllableState } from '@radix-ui/react-use-controllable-state';
+import type { BibleBook } from '@youversion/platform-core';
+import {
+ useBibleSearch,
+ usePassage,
+ type BibleSearchResult,
+ type UseBibleSearchResult,
+} from '@youversion/platform-react-hooks';
+import {
+ useCallback,
+ useEffect,
+ useId,
+ useRef,
+ useState,
+ type ReactElement,
+ type RefCallback,
+} from 'react';
+import { useTranslation } from 'react-i18next';
+import { useBibleReaderContext } from './bible-reader';
+import { SearchIcon } from './icons/search';
+import { XIcon } from './icons/x';
+import { LoaderIcon } from './icons/loader';
+import { FlameIcon } from './icons/flame';
+import { ClockBackIcon } from './icons/clock-back';
+import { ChevronBackwardIcon } from './icons/chevron-backward';
+import { Button } from './ui/button';
+import { Popover, PopoverContent, PopoverTrigger } from './ui/popover';
+import { InputGroup, InputGroupAddon, InputGroupInput } from './ui/input-group';
+
+export type BibleReaderSearchProps = {
+ open?: boolean;
+ defaultOpen?: boolean;
+ onOpenChange?: (open: boolean) => void;
+};
+
+/** Serializable snapshot for host-owned search, including Expo DOM callbacks. */
+export type BibleReaderSearchPressData = {
+ versionId: number;
+ book: string;
+ chapter: string;
+};
+
+type SearchQueryItem = Readonly<{ text: string }>;
+
+type PassageText =
+ | { readonly status: 'loading' }
+ | { readonly status: 'ready'; readonly value: string }
+ | { readonly status: 'unavailable' };
+
+/**
+ * Trigger, popover, suggestion list, result list, and navigation on select.
+ * Must render inside `BibleReader.Root`.
+ *
+ * Zero required props. Optional open control is for a host-owned trigger.
+ * Fresh session on open comes from unmounting popover content on close.
+ */
+export function BibleReaderSearch({
+ open: openProp,
+ defaultOpen,
+ onOpenChange,
+}: BibleReaderSearchProps): ReactElement {
+ const { t } = useTranslation(undefined, { i18n });
+ const { background, onSearchPress, versionId, book, chapter } = useBibleReaderContext();
+ const history = useRecentSearches();
+ const navigating = useRef(false);
+ const [open, setOpen] = useControllableState({
+ prop: openProp,
+ defaultProp: defaultOpen ?? false,
+ onChange: onOpenChange,
+ });
+
+ if (onSearchPress) {
+ return (
+
+ );
+ }
+
+ return (
+
+
+
+
+ {
+ if (navigating.current) event.preventDefault();
+ navigating.current = false;
+ }}
+ >
+ setOpen(false)}
+ onNavigate={() => {
+ navigating.current = true;
+ setOpen(false);
+ }}
+ />
+
+
+ );
+}
+
+function SearchPanel({
+ onClose,
+ onNavigate,
+ recentSearches,
+ rememberSearch,
+}: {
+ onClose: () => void;
+ onNavigate: () => void;
+ recentSearches: readonly string[];
+ rememberSearch: (query: string) => void;
+}): ReactElement {
+ const { t } = useTranslation(undefined, { i18n });
+ const { versionId, navigation, booksData, booksLoading } = useBibleReaderContext();
+ const [testament, setTestament] = useState<'both' | 'old_testament' | 'new_testament'>('both');
+ const [filtersOpen, setFiltersOpen] = useState(false);
+ const [animateFilters, setAnimateFilters] = useState(false);
+ const filtersId = useId();
+ const testamentOptions = [
+ ['old_testament', t('oldTestamentHeading', 'Old Testament')],
+ ['new_testament', t('newTestamentHeading', 'New Testament')],
+ ['both', t('bibleSearchBothTestaments', 'Both')],
+ ] as const;
+ const search = useBibleSearch({
+ versionId,
+ bookIds:
+ testament === 'both'
+ ? undefined
+ : booksData.filter((book) => book.canon === testament).map((book) => book.id),
+ });
+ const inputRef = useRef(null);
+ const scrollRef = useRef(null);
+ const hasQuery = search.query !== '';
+ const showingResults = !['trending', 'suggesting'].includes(search.phase.kind);
+ const resetSearch = (): void => {
+ search.setQuery('');
+ setTestament('both');
+ setFiltersOpen(false);
+ inputRef.current?.focus();
+ if (scrollRef.current) scrollRef.current.scrollTop = 0;
+ };
+
+ const onPick = (text: string): void => {
+ rememberSearch(text);
+ search.selectSuggestion(text);
+ inputRef.current?.focus();
+ if (scrollRef.current) scrollRef.current.scrollTop = 0;
+ };
+
+ const onSelectVerse = (verse: BibleSearchResult): void => {
+ onNavigate();
+ navigation.focusReference({ versionId, passageId: verse.id });
+ };
+
+ return (
+
+
+ {showingResults ? (
+
+ ) : null}
+
+
+
+
+ search.setQuery(event.target.value)}
+ onKeyDown={(event) => {
+ if (event.key === 'Enter' && !event.nativeEvent.isComposing) {
+ event.preventDefault();
+ rememberSearch(search.query);
+ search.submit();
+ if (scrollRef.current) scrollRef.current.scrollTop = 0;
+ }
+ }}
+ />
+ {search.query !== '' ? (
+
+
+
+ ) : null}
+
+ {!hasQuery ? (
+
+ ) : null}
+
+ {showingResults ? (
+
+
+
{t('bibleSearchBibleHeading', 'Bible')}
+
+
+
+
+
+ {testamentOptions.map(([value, label]) => (
+
+ ))}
+
+
+
+
+ ) : null}
+
+
+
+
+
+ {recentSearches.length > 0 ? (
+ ({ text }))}
+ busy={false}
+ onPick={onPick}
+ />
+ ) : null}
+
+ );
+ case 'suggesting':
+ return (
+
+ );
+ case 'searching':
+ return (
+
+
+
+ );
+ case 'results':
+ return (
+
+ );
+ case 'empty':
+ return (
+
+ {t('noBibleSearchResults')}
+
+ );
+ case 'failed':
+ return (
+
+
+ {t('bibleSearchFailure', "We couldn't complete this search. Try again.")}
+
+
+
+ {heading}
+
+ {busy ? (
+
+
+
+ ) : error ? (
+
+
+ {t(
+ 'bibleSearchQueriesFailure',
+ "We couldn't load search suggestions. You can still search by typing a query.",
+ )}
+
+
+
+ {items.map((item) => (
+ -
+
+
+ ))}
+
+ )}
+
+ );
+}
+
+function VerseResults({
+ verses,
+ nextPage,
+ versionId,
+ booksData,
+ onLoadMore,
+ onRetry,
+ onSelect,
+}: {
+ verses: readonly [BibleSearchResult, ...BibleSearchResult[]];
+ nextPage: 'none' | 'available' | 'loading' | 'failed';
+ versionId: number;
+ booksData: readonly BibleBook[];
+ onLoadMore: () => void;
+ onRetry: () => void;
+ onSelect: (verse: BibleSearchResult) => void;
+}): ReactElement {
+ const { t } = useTranslation(undefined, { i18n });
+ const requested = useRef(false);
+ const [settled, setSettled] = useState>(() => new Set());
+ const [revealed, setRevealed] = useState>(() => new Set());
+ const onSettled = useCallback((id: string) => {
+ setSettled((previous) => (previous.has(id) ? previous : new Set([...previous, id])));
+ }, []);
+ const previewsLoading = verses.some((verse) => !settled.has(verse.id));
+ const hasVisibleResults = verses.some((verse) => revealed.has(verse.id));
+ useEffect(() => {
+ if (!previewsLoading) setRevealed(new Set(verses.map((verse) => verse.id)));
+ }, [previewsLoading, verses]);
+ useEffect(() => {
+ if (nextPage !== 'available') requested.current = false;
+ }, [nextPage]);
+ const loadMoreWhenNearEnd = useCallback(() => {
+ if (nextPage !== 'available' || requested.current) return;
+ requested.current = true;
+ onLoadMore();
+ }, [nextPage, onLoadMore]);
+ const paginationTriggerRef = useIntersectionCallback(loadMoreWhenNearEnd);
+ const paginationTriggerIndex = Math.max(0, verses.length - 5);
+
+ return (
+
+
+ {verses.map((verse, index) => (
+ - = paginationTriggerIndex ? paginationTriggerRef : undefined
+ }
+ >
+ book.id === verse.book)?.title}
+ onSettled={onSettled}
+ onSelect={() => onSelect(verse)}
+ />
+
+ ))}
+
+ {nextPage === 'available' && !previewsLoading ? (
+
+ ) : null}
+ {nextPage === 'loading' || previewsLoading ? (
+
+
+
+ ) : null}
+ {nextPage === 'failed' ? (
+
+
+ {t('bibleSearchFailure', "We couldn't complete this search. Try again.")}
+
+
+
+ ) : null}
+