@youversion/platform-react-hooks 0.4.1

package/src/useVerse.ts

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

package/src/useVerseSelection.ts

@@ -0,0 +1,13 @@
+import { useContext } from 'react';
+import {
+  VerseSelectionContext,
+  type VerseSelectionContextData,
+} from './context/VerseSelectionContext';
+
+export function useVerseSelection(): VerseSelectionContextData {
+  const context = useContext(VerseSelectionContext);
+  if (!context) {
+    throw new Error('useVerseSelection must be used within a VerseSelectionProvider');
+  }
+  return context;
+}

package/src/useVerses.ts

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

package/src/useVersion.ts

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

package/src/useVersions.ts

@@ -0,0 +1,33 @@
+'use client';
+
+import { useBibleClient } from './useBibleClient';
+import { useApiData, type UseApiDataOptions } from './useApiData';
+import type { Collection, BibleVersion } from '@youversion/platform-core';
+
+export function useVersions(
+  languageRanges: string = 'en',
+  licenseId?: string | number,
+  options?: UseApiDataOptions,
+): {
+  versions: Collection<BibleVersion> | null;
+  loading: boolean;
+  error: Error | null;
+  refetch: () => void;
+} {
+  const bibleClient = useBibleClient();
+
+  const {
+    data: versions,
+    loading,
+    error,
+    refetch,
+  } = useApiData<Collection<BibleVersion>>(
+    () => bibleClient.getVersions(languageRanges, licenseId),
+    [bibleClient, languageRanges, licenseId],
+    {
+      enabled: options?.enabled !== false,
+    },
+  );
+
+  return { versions, loading, error, refetch };
+}

package/src/utility/extractTextFromHTML.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest';
+import { extractTextFromHtml } from './extractTextFromHTML';
+
+describe('extractTextFromHtml', () => {
+  it('should return empty string for empty input', () => {
+    expect(extractTextFromHtml('')).toBe('');
+  });
+
+  it('should return empty string for falsy input', () => {
+    expect(extractTextFromHtml(null as unknown as string)).toBe('');
+    expect(extractTextFromHtml(undefined as unknown as string)).toBe('');
+  });
+
+  it('should extract text from single content span', () => {
+    const html = '<span class="content">Hello World</span>';
+    expect(extractTextFromHtml(html)).toBe('Hello World');
+  });
+
+  it('should extract text from multiple content spans', () => {
+    const html = `
+      <span class="content">In the</span>
+      <span class="content">beginning</span>
+      <span class="content">God</span>
+    `;
+    expect(extractTextFromHtml(html)).toBe('In the beginning God');
+  });
+
+  it('should ignore non-content spans', () => {
+    const html = `
+      <span class="label">1</span>
+      <span class="content">In the beginning</span>
+      <span class="footnote">*</span>
+      <span class="content">God created</span>
+    `;
+    expect(extractTextFromHtml(html)).toBe('In the beginning God created');
+  });
+
+  it('should normalize whitespace', () => {
+    const html = `
+      <span class="content">  In   the  </span>
+      <span class="content">   beginning   </span>
+    `;
+    expect(extractTextFromHtml(html)).toBe('In the beginning');
+  });
+
+  it('should handle nested elements within content spans', () => {
+    const html = `
+      <span class="content">The <em>word</em> of God</span>
+      <span class="content">is <strong>powerful</strong></span>
+    `;
+    expect(extractTextFromHtml(html)).toBe('The word of God is powerful');
+  });
+
+  it('should filter out empty content spans', () => {
+    const html = `
+      <span class="content">Hello</span>
+      <span class="content">   </span>
+      <span class="content"></span>
+      <span class="content">World</span>
+    `;
+    expect(extractTextFromHtml(html)).toBe('Hello World');
+  });
+
+  it('should handle complex verse markup', () => {
+    const html = `
+      <span class="label">1</span>
+      <span class="content">In the beginning</span>
+      <span class="content">God created the heavens and the earth.</span>
+      <span class="footnote">a</span>
+      <span class="label">2</span>
+      <span class="content">Now the earth was formless and empty,</span>
+    `;
+    expect(extractTextFromHtml(html)).toBe(
+      'In the beginning God created the heavens and the earth. Now the earth was formless and empty,',
+    );
+  });
+
+  it('should handle HTML with no content spans', () => {
+    const html = `
+      <div>Some text</div>
+      <span class="label">1</span>
+      <span class="footnote">*</span>
+    `;
+    expect(extractTextFromHtml(html)).toBe('');
+  });
+
+  it('should preserve order of content spans', () => {
+    const html = `
+      <span class="content">First</span>
+      <span class="other">ignored</span>
+      <span class="content">Second</span>
+      <span class="content">Third</span>
+    `;
+    expect(extractTextFromHtml(html)).toBe('First Second Third');
+  });
+
+  it('should handle special characters and entities', () => {
+    const html = `
+      <span class="content">God's love</span>
+      <span class="content">&amp; mercy</span>
+    `;
+    expect(extractTextFromHtml(html)).toBe("God's love & mercy");
+  });
+
+  it('should handle line breaks and tabs in content', () => {
+    const html = `
+      <span class="content">Line one\nLine two</span>
+      <span class="content">Tab\there</span>
+    `;
+    expect(extractTextFromHtml(html)).toBe('Line one Line two Tab here');
+  });
+});

package/src/utility/extractTextFromHTML.ts

@@ -0,0 +1,22 @@
+/**
+ * Extracts readable text from an HTML string, focusing on content spans.
+ * This is needed because verses include markup for labels, footnotes, etc.
+ *
+ * @param html - The HTML content to extract text from
+ * @returns Plain text with normalized whitespace
+ */
+export function extractTextFromHtml(html: string): string {
+  if (!html) return '';
+
+  const container = document.createElement('div');
+  container.innerHTML = html;
+
+  // Extract text from content spans and join with spaces
+  const contentText = Array.from(container.querySelectorAll<HTMLElement>('span.content'))
+    .map((el) => (el.textContent || '').trim())
+    .filter(Boolean)
+    .join(' ');
+
+  // Normalize whitespace
+  return contentText.replace(/\s+/g, ' ').trim();
+}

package/src/utility/extractVersesFromHTML.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect } from 'vitest';
+import { extractVersesFromHTML } from './extractVersesFromHTML';
+
+describe('extractVersesFromHTML', () => {
+  it('should return empty array for null input', () => {
+    expect(extractVersesFromHTML(null)).toEqual([]);
+  });
+
+  it('should return empty array for undefined input', () => {
+    expect(extractVersesFromHTML(undefined)).toEqual([]);
+  });
+
+  it('should return empty array for empty string', () => {
+    expect(extractVersesFromHTML('')).toEqual([]);
+  });
+
+  it('should extract single verse from HTML', () => {
+    const html = `
+      <span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>
+      <span class="content">In the beginning God created the heavens and the earth.</span>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toEqual({
+      verse: 1,
+      html: expect.stringContaining('<span class="yv-v" v="1">') as string,
+    });
+    expect(result[0]?.html).toContain('In the beginning God created');
+  });
+
+  it('should extract multiple verses from HTML', () => {
+    const html = `
+      <span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>
+      <span class="content">In the beginning God created the heavens and the earth.</span>
+      <span class="yv-v" v="2"></span><span class="yv-vlbl">2</span>
+      <span class="content">Now the earth was formless and empty.</span>
+      <span class="yv-v" v="3"></span><span class="yv-vlbl">3</span>
+      <span class="content">And God said, "Let there be light," and there was light.</span>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toHaveLength(3);
+    expect(result[0]).toEqual({
+      verse: 1,
+      html: expect.stringContaining('In the beginning') as string,
+    });
+    expect(result[1]).toEqual({
+      verse: 2,
+      html: expect.stringContaining('formless and empty') as string,
+    });
+    expect(result[2]).toEqual({
+      verse: 3,
+      html: expect.stringContaining('Let there be light') as string,
+    });
+  });
+
+  it('should handle verses with double-digit numbers', () => {
+    const html = `
+      <span class="yv-v" v="10"></span><span class="yv-vlbl">10</span>
+      <span class="content">Verse ten content.</span>
+      <span class="yv-v" v="25"></span><span class="yv-vlbl">25</span>
+      <span class="content">Verse twenty-five content.</span>
+      <span class="yv-v" v="100"></span><span class="yv-vlbl">100</span>
+      <span class="content">Verse one hundred content.</span>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toHaveLength(3);
+    expect(result[0]?.verse).toBe(10);
+    expect(result[1]?.verse).toBe(25);
+    expect(result[2]?.verse).toBe(100);
+  });
+
+  it('should preserve HTML formatting within verses', () => {
+    const html = `
+      <span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>
+      <span class="content">This has <strong>bold</strong> and <em>italic</em> text.</span>
+      <sup class="footnote">a</sup>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.html).toContain('<strong>bold</strong>');
+    expect(result[0]?.html).toContain('<em>italic</em>');
+    expect(result[0]?.html).toContain('<sup class="footnote">a</sup>');
+  });
+
+  it('should handle verses with footnotes and cross-references', () => {
+    const html = `
+      <span class="yv-v" v="5"></span><span class="yv-vlbl">5</span>
+      <span class="content">God called the light "day,"</span>
+      <sup class="footnote">a</sup>
+      <span class="content">and the darkness he called "night."</span>
+      <sup class="crossref">b</sup>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.verse).toBe(5);
+    expect(result[0]?.html).toContain('God called the light');
+    expect(result[0]?.html).toContain('footnote');
+    expect(result[0]?.html).toContain('crossref');
+  });
+
+  it('should handle HTML with no verse markers', () => {
+    const html = `
+      <div>Some content without verse markers</div>
+      <span class="content">Just regular text</span>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toEqual([]);
+  });
+
+  it('should handle malformed verse markers', () => {
+    const html = `
+      <span class="yv-v" v="1"></span>
+      <span class="content">Missing verse label span</span>
+      <span class="yv-vlbl">2</span>
+      <span class="content">Missing verse marker span</span>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toEqual([]);
+  });
+
+  it('should trim whitespace from extracted HTML', () => {
+    const html = `
+      <span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>
+
+
+      <span class="content">Content with surrounding whitespace</span>
+
+
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.html).not.toMatch(/^\s+/);
+    expect(result[0]?.html).not.toMatch(/\s+$/);
+  });
+
+  it('should handle consecutive verses without content between them', () => {
+    const html = `
+      <span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>
+      <span class="yv-v" v="2"></span><span class="yv-vlbl">2</span>
+      <span class="content">Verse 2 content</span>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toHaveLength(2);
+    expect(result[0]).toEqual({
+      verse: 1,
+      html: '<span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>',
+    });
+    expect(result[1]?.html).toContain('Verse 2 content');
+  });
+
+  it('should extract verses in correct order', () => {
+    const html = `
+      <span class="yv-v" v="3"></span><span class="yv-vlbl">3</span>
+      <span class="content">Third verse</span>
+      <span class="yv-v" v="1"></span><span class="yv-vlbl">1</span>
+      <span class="content">First verse</span>
+      <span class="yv-v" v="2"></span><span class="yv-vlbl">2</span>
+      <span class="content">Second verse</span>
+    `;
+
+    const result = extractVersesFromHTML(html);
+
+    expect(result).toHaveLength(3);
+    expect(result[0]?.verse).toBe(3);
+    expect(result[1]?.verse).toBe(1);
+    expect(result[2]?.verse).toBe(2);
+  });
+});

package/src/utility/extractVersesFromHTML.ts

@@ -0,0 +1,31 @@
+/**
+ * Splits a passage HTML into an array of verse HTML strings.
+ * Expects markers like: <span class="yv-v" v="N"></span><span class="yv-vlbl">N</span>
+ */
+export function extractVersesFromHTML(
+  html: string | null | undefined,
+): { verse: number; html: string }[] {
+  if (!html) return [];
+
+  const results: { verse: number; html: string }[] = [];
+  const pattern = /<span class="yv-v" v="(\d+)"><\/span><span class="yv-vlbl">\d+<\/span>/g;
+
+  let execResult: RegExpExecArray | null;
+  const indices: { verse: number; index: number }[] = [];
+
+  while ((execResult = pattern.exec(html)) !== null) {
+    const verseNumString = execResult[1]!;
+    indices.push({ verse: parseInt(verseNumString, 10), index: execResult.index });
+  }
+
+  for (let i = 0; i < indices.length; i++) {
+    const current = indices[i]!;
+    const next = indices[i + 1];
+    const start = current.index;
+    const end = next ? next.index : html.length;
+    const slice = html.slice(start, end).trim();
+    results.push({ verse: current.verse, html: slice });
+  }
+
+  return results;
+}

package/src/utility/getDayOfYear.ts

@@ -0,0 +1,6 @@
+export function getDayOfYear(date: Date): number {
+  const dayOfYear = Math.floor(
+    (date.getTime() - new Date(date.getFullYear(), 0, 0).getTime()) / 86400000,
+  );
+  return dayOfYear;
+}

package/src/utility/index.ts

@@ -0,0 +1,5 @@
+export * from './extractTextFromHTML';
+export * from './useDebounce';
+export * from './version';
+export * from './extractVersesFromHTML';
+export * from './getDayOfYear';

package/src/utility/useDebounce.test.tsx

@@ -0,0 +1,95 @@
+import { renderHook, act } from '@testing-library/react';
+import { describe, beforeEach, afterEach, it, expect, vi } from 'vitest';
+import { useDebounce } from './useDebounce';
+
+describe('useDebounce', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+  });
+
+  it('should return initial value immediately', () => {
+    const { result } = renderHook(() => useDebounce('initial', 500));
+
+    expect(result.current).toBe('initial');
+  });
+
+  it('should debounce value changes', () => {
+    const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), {
+      initialProps: { value: 'initial', delay: 500 },
+    });
+
+    expect(result.current).toBe('initial');
+
+    rerender({ value: 'updated', delay: 500 });
+
+    expect(result.current).toBe('initial');
+
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+
+    expect(result.current).toBe('updated');
+  });
+
+  it('should cancel previous timeout on rapid changes', () => {
+    const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), {
+      initialProps: { value: 'first', delay: 500 },
+    });
+
+    expect(result.current).toBe('first');
+
+    rerender({ value: 'second', delay: 500 });
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(result.current).toBe('first');
+
+    rerender({ value: 'third', delay: 500 });
+
+    act(() => {
+      vi.advanceTimersByTime(300);
+    });
+
+    expect(result.current).toBe('first');
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+
+    expect(result.current).toBe('third');
+  });
+
+  it('should handle different data types', () => {
+    const { result: numberResult } = renderHook(() => useDebounce(42, 100));
+    expect(numberResult.current).toBe(42);
+
+    const { result: objectResult } = renderHook(() => useDebounce({ key: 'value' }, 100));
+    expect(objectResult.current).toEqual({ key: 'value' });
+
+    const { result: arrayResult } = renderHook(() => useDebounce([1, 2, 3], 100));
+    expect(arrayResult.current).toEqual([1, 2, 3]);
+  });
+
+  it('should update immediately when delay is 0', () => {
+    const { result, rerender } = renderHook(({ value, delay }) => useDebounce(value, delay), {
+      initialProps: { value: 'initial', delay: 0 },
+    });
+
+    expect(result.current).toBe('initial');
+
+    rerender({ value: 'updated', delay: 0 });
+
+    act(() => {
+      vi.runAllTimers();
+    });
+
+    expect(result.current).toBe('updated');
+  });
+});

package/src/utility/useDebounce.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Custom hook for debouncing a value.
+ *
+ * The hook delays the update of the given value until a specified delay has passed
+ * after the last change. It is commonly used to optimize the performance of
+ * functions that depend on user input or rapidly updating values.
+ *
+ * @param value - The input value to be debounced.
+ * @param delay - The duration in milliseconds to delay the update of the value.
+ *
+ * @returns The debounced value, updated after the specified delay.
+ */
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => clearTimeout(handler);
+  }, [value, delay]);
+
+  return debouncedValue;
+}

package/src/utility/version.ts

@@ -0,0 +1,5 @@
+import type { BibleVersion } from '@youversion/platform-core';
+
+export function getISOFromVersion(version: BibleVersion): string {
+  return version?.language_tag || 'unknown';
+}

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx"]
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "@internal/tsconfig/react.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": ".",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*", "vitest.setup.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    globals: true,
+  },
+});