@youversion/platform-react-hooks 1.7.0 → 1.8.1

package/.turbo/turbo-build.log

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

package/AGENTS.md

@@ -0,0 +1,183 @@
+# @youversion/platform-react-hooks
+
+## OVERVIEW
+React integration layer providing data fetching hooks with 3 core providers: YouVersionProvider, YouVersionAuthProvider, and ReaderProvider.
+
+**Depends on `@youversion/platform-core` for all API calls.** Hooks delegate to core clients; do not implement raw HTTP here.
+
+**Related packages:**
+- For lower-level API clients → see `packages/core/AGENTS.md`
+- For pre-built UI components → see `packages/ui/AGENTS.md`
+
+## STRUCTURE
+- `use*.ts` - Data fetching hooks (useBook, useChapter, usePassage, useVersion, etc.)
+- `context/` - Providers and contexts (separate files, exported via index.ts)
+- `utility/` - Helper functions (useDebounce, extractTextFromHTML, extractVersesFromHTML)
+
+## PUBLIC API
+- Data fetching hooks: useBook, useChapter, usePassage, useVersion, useVOTD, useVerse, useChapterNavigation, etc.
+- YouVersionProvider - Core SDK configuration
+- YouVersionAuthProvider - Authentication state
+- ReaderProvider - Reading session context
+- Utility functions exported from utility/index
+
+## PROVIDERS
+
+- **YouVersionProvider**
+  - Holds core SDK configuration (API base URL, clients)
+  - Wrap this around your app before using any data hooks
+
+- **YouVersionAuthProvider**
+  - Manages authentication state (userInfo, tokens, isLoading, error)
+  - Auth hooks like `useYVAuth` depend on this provider
+
+- **ReaderProvider**
+  - Manages Bible reading session state (currentVersion, currentChapter, currentBook, currentVerse)
+  - Hooks like `useChapterNavigation` depend on this provider
+
+## DOs / DON'Ts
+
+✅ Do: Use `YouVersionProvider` for configuration and access that config in hooks
+✅ Do: Wrap async data access in hooks rather than calling core clients directly in components
+✅ Do: Keep hooks **UI-agnostic** (no JSX returned, no direct DOM manipulation)
+✅ Do: Use the `useApiData` pattern for new data fetching hooks
+
+❌ Don't: Import components from `@youversion/platform-react-ui`
+❌ Don't: Talk directly to `fetch`/HTTP; always use `@youversion/platform-core`
+❌ Don't: Access `window.localStorage` directly for auth; rely on core's storage abstractions
+
+## DATA FETCHING PATTERN
+
+Hooks use a custom React Query-like pattern via `useApiData`:
+- Returns `{ data, loading, error, refetch }`
+- Provides caching and refetch capability
+- New hooks should follow this same pattern
+
+## CONVENTIONS
+- Context and Provider in separate files
+- All contexts exported via context/index.ts
+- TypeScript declarations generated separately (no bundling)
+- Build: tsc only
+
+## USAGE EXAMPLES
+
+### Provider Setup (Required)
+
+```tsx
+// Wrap your app with YouVersionProvider before using any hooks
+import { YouVersionProvider } from '@youversion/platform-react-hooks';
+
+function App() {
+  return (
+    <YouVersionProvider
+      appKey="your-app-key"
+      theme="light"                      // "light" | "dark"
+    >
+      <MyApp />
+    </YouVersionProvider>
+  );
+}
+
+// With authentication enabled
+function AppWithAuth() {
+  return (
+    <YouVersionProvider
+      appKey="your-app-key"
+      includeAuth={true}
+      authRedirectUrl="https://myapp.com/callback"
+    >
+      <MyApp />
+    </YouVersionProvider>
+  );
+}
+```
+
+### Data Fetching Hooks
+
+All data hooks return `{ data, loading, error, refetch }`:
+
+```tsx
+import { useChapter, useVersion, useVerseOfTheDay } from '@youversion/platform-react-hooks';
+
+// Fetch a Bible chapter
+function ChapterView() {
+  const { chapter, loading, error } = useChapter(
+    111,      // versionId (e.g., 111 = NIV)
+    'JHN',    // book (USFM abbreviation)
+    3         // chapter number
+  );
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  return <div>{chapter?.content}</div>;
+}
+
+// Fetch Bible version metadata
+function VersionInfo() {
+  const { version, loading } = useVersion(111);
+  if (loading) return <div>Loading...</div>;
+  return <div>{version?.name} ({version?.abbreviation})</div>;
+}
+
+// Fetch Verse of the Day
+function DailyVerse() {
+  const dayOfYear = Math.floor((Date.now() - new Date(new Date().getFullYear(), 0, 0).getTime()) / 86400000);
+  const { data: votd, loading, refetch } = useVerseOfTheDay(dayOfYear);
+
+  if (loading) return <div>Loading...</div>;
+  return (
+    <div>
+      <p>{votd?.verse.text}</p>
+      <button onClick={refetch}>Refresh</button>
+    </div>
+  );
+}
+```
+
+### Authentication Hook
+
+```tsx
+import { useYVAuth } from '@youversion/platform-react-hooks';
+
+function AuthExample() {
+  const { auth, userInfo, signIn, signOut } = useYVAuth();
+
+  if (auth.isLoading) return <div>Loading...</div>;
+
+  if (!auth.isAuthenticated) {
+    return (
+      <button onClick={() => signIn({ redirectUrl: window.location.origin + '/callback' })}>
+        Sign In with YouVersion
+      </button>
+    );
+  }
+
+  return (
+    <div>
+      <p>Welcome, {userInfo?.name}!</p>
+      <button onClick={signOut}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+### Conditional Fetching
+
+```tsx
+// Use the `enabled` option to conditionally fetch
+function ConditionalFetch({ versionId }: { versionId: number | null }) {
+  const { version, loading } = useVersion(versionId ?? 0, {
+    enabled: versionId !== null,  // Only fetch when versionId is provided
+  });
+
+  // ...
+}
+```
+
+## TESTING
+
+- Run tests: `pnpm --filter @youversion/platform-react-hooks test`
+- Framework: Vitest with jsdom environment
+- React Testing Library for component/hook tests
+- Mock object factories live in `__tests__/mocks` (not MSW - hooks delegate HTTP to core)
+- Use provider wrappers for tests so hooks see the same context as in the app

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @youversion/platform-react-hooks
 
+## 1.8.1
+
+### Patch Changes
+
+- 607be3c: Refactor verse HTML transformation to support verse-level highlighting. Extract HTML processing logic to `verse-html-utils.ts` with new `wrapVerseContent()` function that wraps verse content in CSS-targetable `<span class="yv-v">` elements. Simplify footnote extraction using wrapped verse structure. Remove CSS rule preventing text wrapping. Add comprehensive test coverage for verse wrapping behavior.
+- Updated dependencies [607be3c]
+  - @youversion/platform-core@1.8.1
+
+## 1.8.0
+
+### Minor Changes
+
+- 45516c2: Add recently used versions to the Bible Version Picker
+  - Display up to 3 recently selected Bible versions at the top of the picker
+  - Persist recent version selections in localStorage
+  - Recent versions are searchable and excluded from the main "All Versions" list
+
+### Patch Changes
+
+- Updated dependencies [45516c2]
+  - @youversion/platform-core@1.8.0
+
 ## 1.7.0
 
 ### Minor Changes

package/dist/useFilteredVersions.d.ts

@@ -2,5 +2,5 @@ import type { BibleVersion } from '@youversion/platform-core';
 /**
  * Custom hook to filter versions based on search term
  */
-export declare function useFilteredVersions(versions: BibleVersion[], searchTerm: string, selectedLanguage: string): BibleVersion[];
+export declare function useFilteredVersions(versions: BibleVersion[], searchTerm: string, selectedLanguage: string, recentVersions?: Pick<BibleVersion, 'id' | 'title' | 'localized_abbreviation'>[]): BibleVersion[];
 //# sourceMappingURL=useFilteredVersions.d.ts.map

package/dist/useFilteredVersions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFilteredVersions.d.ts","sourceRoot":"","sources":["../src/useFilteredVersions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,EAAE,EACxB,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,GACvB,YAAY,EAAE,CAwBhB"}
+{"version":3,"file":"useFilteredVersions.d.ts","sourceRoot":"","sources":["../src/useFilteredVersions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,YAAY,EAAE,EACxB,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EACxB,cAAc,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,OAAO,GAAG,wBAAwB,CAAC,EAAE,GAC/E,YAAY,EAAE,CA8BhB"}

package/dist/useFilteredVersions.js

@@ -4,7 +4,7 @@ import { getISOFromVersion } from './utility/version';
 /**
  * Custom hook to filter versions based on search term
  */
-export function useFilteredVersions(versions, searchTerm, selectedLanguage) {
+export function useFilteredVersions(versions, searchTerm, selectedLanguage, recentVersions) {
     return useMemo(() => {
         let result = [...versions];
         // Language filter
@@ -18,7 +18,12 @@ export function useFilteredVersions(versions, searchTerm, selectedLanguage) {
                 version.abbreviation.toLowerCase().includes(searchLower) ||
                 getISOFromVersion(version).toLowerCase().includes(searchLower));
         }
+        // Recently Used Filter
+        if (recentVersions) {
+            const recentVersionIds = recentVersions.map((version) => version.id);
+            result = result.filter((version) => !recentVersionIds.includes(version.id));
+        }
         return result;
-    }, [versions, searchTerm, selectedLanguage]);
+    }, [versions, recentVersions, searchTerm, selectedLanguage]);
 }
 //# sourceMappingURL=useFilteredVersions.js.map

package/dist/useFilteredVersions.js.map

@@ -1 +1 @@
-{"version":3,"file":"useFilteredVersions.js","sourceRoot":"","sources":["../src/useFilteredVersions.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAGb,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAwB,EACxB,UAAkB,EAClB,gBAAwB;IAExB,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,IAAI,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;QAE3B,kBAAkB;QAClB,IAAI,gBAAgB,IAAI,gBAAgB,KAAK,GAAG,EAAE,CAAC;YACjD,MAAM,GAAG,MAAM,CAAC,MAAM,CACpB,CAAC,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,gBAAgB,CAAC,WAAW,EAAE,CACzF,CAAC;QACJ,CAAC;QAED,gBAAgB;QAChB,IAAI,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC;YACtB,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;YAC7C,MAAM,GAAG,MAAM,CAAC,MAAM,CACpB,CAAC,OAAO,EAAE,EAAE,CACV,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;gBACjD,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;gBACxD,iBAAiB,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,CACjE,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"useFilteredVersions.js","sourceRoot":"","sources":["../src/useFilteredVersions.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAGb,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAwB,EACxB,UAAkB,EAClB,gBAAwB,EACxB,cAAgF;IAEhF,OAAO,OAAO,CAAC,GAAG,EAAE;QAClB,IAAI,MAAM,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;QAE3B,kBAAkB;QAClB,IAAI,gBAAgB,IAAI,gBAAgB,KAAK,GAAG,EAAE,CAAC;YACjD,MAAM,GAAG,MAAM,CAAC,MAAM,CACpB,CAAC,OAAO,EAAE,EAAE,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,gBAAgB,CAAC,WAAW,EAAE,CACzF,CAAC;QACJ,CAAC;QAED,gBAAgB;QAChB,IAAI,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC;YACtB,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;YAC7C,MAAM,GAAG,MAAM,CAAC,MAAM,CACpB,CAAC,OAAO,EAAE,EAAE,CACV,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;gBACjD,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;gBACxD,iBAAiB,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,CACjE,CAAC;QACJ,CAAC;QAED,uBAAuB;QACvB,IAAI,cAAc,EAAE,CAAC;YACnB,MAAM,gBAAgB,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACrE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9E,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/package.json

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

package/src/useFilteredVersions.test.tsx

@@ -198,6 +198,64 @@ describe('useFilteredVersions', () => {
     });
   });
 
+  describe('recent versions exclusion', () => {
+    it('should not exclude any versions when recentVersions is undefined', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '', '*', undefined));
+
+      expect(result.current).toEqual(mockVersions);
+      expect(result.current).toHaveLength(5);
+    });
+
+    it('should exclude recent versions from the results', () => {
+      const recentVersions = [
+        { id: 1, title: 'King James Version', localized_abbreviation: 'KJV' },
+      ];
+
+      const { result } = renderHook(() =>
+        useFilteredVersions(mockVersions, '', '*', recentVersions),
+      );
+
+      expect(result.current).toHaveLength(4);
+      expect(result.current.find((v) => v.id === 1)).toBeUndefined();
+    });
+
+    it('should exclude multiple recent versions from the results', () => {
+      const recentVersions = [
+        { id: 1, title: 'King James Version', localized_abbreviation: 'KJV' },
+        { id: 2, title: 'New International Version', localized_abbreviation: 'NIV' },
+      ];
+
+      const { result } = renderHook(() =>
+        useFilteredVersions(mockVersions, '', '*', recentVersions),
+      );
+
+      expect(result.current).toHaveLength(3);
+      expect(result.current.find((v) => v.id === 1)).toBeUndefined();
+      expect(result.current.find((v) => v.id === 2)).toBeUndefined();
+    });
+
+    it('should not exclude any versions when recentVersions is empty array', () => {
+      const { result } = renderHook(() => useFilteredVersions(mockVersions, '', '*', []));
+
+      expect(result.current).toEqual(mockVersions);
+      expect(result.current).toHaveLength(5);
+    });
+
+    it('should exclude recent versions even when they match search term', () => {
+      const recentVersions = [
+        { id: 2, title: 'New International Version', localized_abbreviation: 'NIV' },
+      ];
+
+      const { result } = renderHook(() =>
+        useFilteredVersions(mockVersions, 'Version', '*', recentVersions),
+      );
+
+      // "Version" matches KJV and NIV, but NIV is excluded as a recent version
+      expect(result.current).toHaveLength(1);
+      expect(result.current[0]?.title).toBe('King James Version');
+    });
+  });
+
   describe('memoization', () => {
     it('should return the same reference when inputs do not change', () => {
       const { result, rerender } = renderHook(

package/src/useFilteredVersions.ts

@@ -11,6 +11,7 @@ export function useFilteredVersions(
   versions: BibleVersion[],
   searchTerm: string,
   selectedLanguage: string,
+  recentVersions?: Pick<BibleVersion, 'id' | 'title' | 'localized_abbreviation'>[],
 ): BibleVersion[] {
   return useMemo(() => {
     let result = [...versions];
@@ -33,6 +34,12 @@ export function useFilteredVersions(
       );
     }
 
+    // Recently Used Filter
+    if (recentVersions) {
+      const recentVersionIds = recentVersions.map((version) => version.id);
+      result = result.filter((version) => !recentVersionIds.includes(version.id));
+    }
+
     return result;
-  }, [versions, searchTerm, selectedLanguage]);
+  }, [versions, recentVersions, searchTerm, selectedLanguage]);
 }