YPE-1156: Hooks - Deprecate Unused Hooks

[cameronapak]

Deprecates hooks and providers that are not used by the UI package or any known consumers. These were inherited from a hackathon project and never adopted.

Deprecated:

• useInitData — convenience wrapper over useVersion, useBook, useChapter that loses error granularity, drops refetch, and has zero consumers. Use the three hooks directly.
• useChapterNavigation — coupled to ReaderProvider which nobody uses. The UI package calls getAdjacentChapter from core directly.
• ReaderProvider, ReaderContext, useReaderContext — the UI package built its own BibleReaderContext instead. Zero consumers.
• VerseSelectionProvider, VerseSelectionContext, useVerseSelection — the UI package handles verse selection via props/callbacks. Zero consumers. (Highlights work won't need this)

Tests for all deprecated code have been removed. Deprecated files are excluded from coverage.

This focus to deprecate code came from working on https://lifechurch.atlassian.net/browse/YPE-1156, but... it's important to know that I do have a deprecation ticket at https://lifechurch.atlassian.net/browse/YPE-1140

[changeset-bot]

🦋 Changeset detected

Latest commit: e14348d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-react-hooks	Minor
@youversion/platform-core	Minor
@youversion/platform-react-ui	Minor
nextjs	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[greptile-apps]

Greptile Summary

This PR deprecates seven unused hooks and providers (useInitData, useChapterNavigation, ReaderProvider, ReaderContext, useReaderContext, VerseSelectionProvider, VerseSelectionContext, useVerseSelection) that were inherited from a hackathon project and never adopted by any known consumers. The approach is clean: each symbol receives a @deprecated JSDoc tag with a migration note, corresponding tests are deleted, and the deprecated files are excluded from coverage measurement so metrics don't regress. Documentation (AGENTS.md) is updated to reflect the new provider surface, and the unified versioning rule is respected by bumping all three packages together in the changeset.

Key changes:

• @deprecated JSDoc added to all seven deprecated symbols across five source files
• Test files for deprecated code removed (4 files deleted)
• vitest.config.ts updated to exclude deprecated files from coverage
• AGENTS.md updated to remove references to ReaderProvider and useChapterNavigation from the public API
• Changeset bumps all packages as minor for unified versioning — the description should clarify that @youversion/platform-core and @youversion/platform-react-ui carry no code changes and are bumped purely for version alignment, as all deprecated symbols live only in @youversion/platform-react-hooks

Confidence Score: 4/5

• Safe to merge — deprecation-only change with no removed functionality, no breaking API changes, no new logic introduced, and all deprecated symbols remain exported (backward compatible).
• All deprecated symbols are correctly marked with @deprecated JSDoc tags with clear migration guidance, coverage config is updated to prevent regressions, and the changeset satisfies the unified versioning rule. The one finding (changeset description clarity) is a communication/documentation issue that doesn't affect code safety but could improve consumer experience by clarifying that @youversion/platform-core and @youversion/platform-react-ui contain no relevant changes in this bump.
• .changeset/twenty-onions-wish.md — recommend clarifying that @youversion/platform-core and @youversion/platform-react-ui are bumped purely for version alignment with no code changes in those packages

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph DEPRECATED["Deprecated (this PR)"]
        RP["ReaderProvider\n@deprecated"]
        RC["ReaderContext / useReaderContext\n@deprecated"]
        CN["useChapterNavigation\n@deprecated"]
        VSP["VerseSelectionProvider\n@deprecated"]
        VSC["VerseSelectionContext\n@deprecated"]
        UVS["useVerseSelection\n@deprecated"]
        UID["useInitData\n@deprecated"]
    end

    subgraph ACTIVE["Active (no change)"]
        YVP["YouVersionProvider"]
        AUTH["YouVersionAuthProvider"]
        HOOKS["useBook / useChapter / useVersion\nuseVOTD / usePassage / etc."]
    end

    subgraph CONSUMERS["Recommended replacements"]
        BRC["UI package: BibleReaderContext\n(own implementation)"]
        GAC["getAdjacentChapter\n(platform-core)"]
        IH["useVersion + useBook + useChapter\n(individual hooks)"]
        PROPS["UI package: props / callbacks\n(verse selection)"]
    end

    CN --> GAC
    RP --> BRC
    RC --> BRC
    UID --> IH
    UVS --> PROPS
    VSP --> PROPS
    VSC --> PROPS

Loading

_{Last reviewed commit: e14348d}

[greptile-apps]

Additional Comments (2)

packages/hooks/src/useChapterNavigation.ts, line 23
Duplicate JSDoc blocks — original description is lost to tooling

Two consecutive /** ... */ blocks appear immediately before useChapterNavigation. TypeScript (and IDEs / documentation generators like TypeDoc) only associate the last JSDoc block with the declaration. The original description on lines 16-18 is therefore orphaned — it won't appear in hover tooltips, generated docs, or type checking output.

Merge both blocks into a single JSDoc comment so consumers see both the description and the deprecation notice:

/**
 * Provides navigation functionality for chapters across book boundaries,
 * including intro chapter support.
 *
 * @deprecated This hook will be removed in the next major version.
 * Use `getAdjacentChapter` from `@youversion/platform-core` directly instead.
 */

---

packages/hooks/src/context/VerseSelectionContext.tsx, line 9
Exported type VerseSelectionContextData not marked deprecated

VerseSelectionContext, VerseSelectionProvider, and useVerseSelection are all marked @deprecated, but the VerseSelectionContextData type they all depend on is not. It is still re-exported through context/index.ts → src/index.ts, so consumers may hold a reference to it. For consistency, it should also carry a deprecation tag so tooling can surface the warning when the type is used directly.

/**
 * @deprecated VerseSelectionContextData will be removed in the next major version.
 */
export type VerseSelectionContextData = {
  selectedVerseUsfms: Set<string>;
  toggleVerse: (usfm: string) => void;
  isSelected: (usfm: string) => boolean;
  clearSelection: () => void;
  selectedCount: number;
};

[cameronapak]

@greptile, please re-review this based on the newest changes.

[greptile-apps]

Additional Comments (2)

.changeset/twenty-onions-wish.md, line 4
Changeset includes packages with no code changes.

@youversion/platform-core and @youversion/platform-react-ui are listed here, but this PR makes zero modifications to either of those packages — only packages/hooks files are changed. Including them in the changeset will trigger unnecessary minor version bumps for both packages on the next release.

@youversion/platform-core is a dependency of @youversion/platform-react-hooks, not the other way around, so the core package doesn't need a version bump because hooks are deprecated. Similarly, nothing in @youversion/platform-react-ui is being modified.

Only @youversion/platform-react-hooks should be listed in this changeset.

'@youversion/platform-react-hooks': minor

---

packages/hooks/src/useChapterNavigation.ts, line 23
Duplicate JSDoc blocks lose the function description.

Two separate JSDoc blocks are attached to useChapterNavigation. TypeScript (and IDEs) only associate the JSDoc block that immediately precedes the declaration — the second block (lines 20–23). The description from the first block ("Provides navigation functionality…") becomes an orphaned comment and will no longer appear when hovering over this function.

Merge the @deprecated tag into the existing JSDoc block:

/**
 * Provides navigation functionality for chapters across book boundaries,
 * including intro chapter support.
 * @deprecated This hook will be removed in the next major version.
 * Use `getAdjacentChapter` from `@youversion/platform-core` directly instead.
 */

[cameronapak]

@greptile, please re-re-review this pull request

[greptile-apps]

Additional Comments (1)

packages/hooks/src/context/VerseSelectionContext.tsx, line 5
Inconsistent @deprecated message on type

All other deprecated exports in this PR use the phrase "No replacement needed. Remove usage. Will be removed in the next major version." but the VerseSelectionContextData type only says "VerseSelectionContextData will be removed in the next major version." — it's missing the "No replacement needed. Remove usage." guidance that consumers would see in their IDE.

/**
 * @deprecated No replacement needed. Remove usage. Will be removed in the next major version.
 */

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

[cameronapak]

@greptile, I've made the change you've mentioned. Please re-re-re-review

[greptile-apps]

Additional Comments (1)

.changeset/twenty-onions-wish.md, line 14
The changeset bumps @youversion/platform-core and @youversion/platform-react-ui as minor, but every deprecated symbol listed (useInitData, useChapterNavigation, ReaderProvider, ReaderContext, useReaderContext, VerseSelectionProvider, VerseSelectionContext, useVerseSelection) lives exclusively in @youversion/platform-react-hooks. There are no code changes in either packages/core or packages/ui.

Consumers watching the @youversion/platform-core changelog will see a new minor version entry describing deprecated hooks that don't exist in that package, which is confusing.

Since the unified versioning rule requires all packages to move together, the bump itself is correct — but consider adding a brief note clarifying that platform-core and platform-react-ui are version-bumped solely for alignment:

---
'@youversion/platform-react-hooks': minor
'@youversion/platform-core': minor
'@youversion/platform-react-ui': minor
---

Deprecates hooks and providers that are not used by the UI package or any known consumers. These were inherited from a hackathon project and never adopted. These will be fully removed in the next major version bump.

Note: `@youversion/platform-core` and `@youversion/platform-react-ui` are bumped here only to maintain unified versioning; they contain no code changes.

Deprecated (all in `@youversion/platform-react-hooks`):
- `useInitData` — convenience wrapper over `useVersion`, `useBook`, `useChapter` that loses error granularity, drops `refetch`, and has zero consumers. Use the three hooks directly.
- `useChapterNavigation` — coupled to `ReaderProvider` which nobody uses. The UI package calls `getAdjacentChapter` from core directly.
- `ReaderProvider`, `ReaderContext`, `useReaderContext` — the UI package built its own `BibleReaderContext` instead. Zero consumers.
- `VerseSelectionProvider`, `VerseSelectionContext`, `useVerseSelection` — the UI package handles verse selection via props/callbacks. Zero consumers.

Context Used: Rule from dashboard - Unified versioning: All packages must maintain exact same version - never version packages independe... (source)

[cameronapak]

@mic-mart if you do so dare to embark upon this quest, please continue reading...

When writing tests for the hooks package, I stumbled upon code inherited from the hackathon that we hadn't used and have no intention or plans to use. Because of that, instead of writing tests unnecessarily for some hooks (even though I've written lots of tests for the hooks package), I found it better to deprecate those unnecessary hooks.

Michael, I find you to be a good person to review this code just in case there's some high-level thing that I may be overlooking or if there's some decisions or context that I don't have