YPE-2195 - add onVersionPickerPress escape hatch + controlled BibleCard versionId

[cameronapak]

CleanShot.2026-05-15.at.15.45.36.mp4

Summary

Two changes for React Native consumers:

1. onVersionPickerPress escape hatch — Pass this callback to BibleReader.Root or BibleCard to intercept version picker taps and show your own native sheet instead of the built-in popover.

2. Controlled BibleCard.versionId — versionId is now optional. Pass defaultVersionId + onVersionChange for controlled behavior, or just versionId for uncontrolled (backwards compatible).

Closes YPE-2195

Greptile Summary

This PR adds an onVersionPickerPress escape-hatch prop to BibleReader.Root and BibleCard, allowing React Native consumers to intercept version-picker presses and render native sheets instead of the web popover. It also makes BibleCard.versionId properly controllable via useControllableState, with a carefully guarded isControlled check that preserves uncontrolled backwards-compat when only versionId (no onVersionChange) is supplied.

• Escape hatch (version + chapter picker): Root skips the <Popover> wrapper, Trigger becomes a plain <button> that calls onVersionPickerPress, and Content returns null early — cleanly suppressing the popover on all three sides.
• filteredRecentVersions refactor: computation moved from Content and BibleVersionPickerLanguageTrigger into the Root context, eliminating duplication.
• BibleCard controllable state: isControlled gate (versionId !== undefined && onVersionChange !== undefined) ensures existing consumers who pass only versionId keep their current uncontrolled behaviour.

Confidence Score: 5/5

Safe to merge — the escape-hatch and controlled-state logic is correctly guarded on all three sides (Root wrapper, Trigger rendering, Content early-return), and the isControlled gate preserves existing consumer behaviour.

All three surfaces of the escape hatch (Root skips Popover, Trigger renders plain button, Content returns null) are consistent and mutually reinforcing. The BibleCard controllable-state gate correctly distinguishes fully-controlled from uncontrolled-seeded-by-prop scenarios. The filteredRecentVersions move to Root context is a clean dedup with no functional change. No regressions were found in the changed paths.

No files require special attention.

Important Files Changed

Filename	Overview
packages/ui/src/components/bible-version-picker.tsx	Adds onVersionPickerPress escape-hatch: guards isPopoverOpen via renamed raw state + derived value, skips Popover wrapper in Root, returns null in Content when active, and moves filteredRecentVersions computation to Root context to eliminate duplication.
packages/ui/src/components/bible-card.tsx	Makes versionId controllable via useControllableState with an isControlled guard that preserves uncontrolled backwards-compat when only versionId (no onVersionChange) is supplied; threads onVersionPickerPress to BibleCardVersionPicker.
packages/ui/src/components/bible-chapter-picker.tsx	Mirrors the version-picker escape-hatch pattern: renames isPopoverOpen to isPopoverOpenRaw, derives isPopoverOpen as always-false when onChapterPickerPress is active, and guards the setter.
packages/ui/src/components/bible-reader.tsx	Adds onVersionPickerPress to BibleReaderContext, RootProps, and Root; threads it through to Toolbar then BibleVersionPicker.Root. Minimal, straightforward plumbing.
.changeset/version-picker-escape-hatch-and-bible-card-controlled.md	Minor changeset correctly notes the new props, escape-hatch behavior, filteredRecentVersions move, and that BibleWidgetView is kept as a deprecated alias rather than removed.

Sequence Diagram

sequenceDiagram
    participant Consumer as Native Consumer
    participant Root as BibleVersionPicker.Root
    participant Trigger as BibleVersionPicker.Trigger
    participant Content as BibleVersionPicker.Content

    note over Root: onVersionPickerPress provided

    Root->>Root: Renders Context.Provider only (no Popover wrapper)
    Consumer->>Trigger: user taps version button
    Trigger->>Trigger: renders plain button (not PopoverTrigger)
    Trigger->>Consumer: calls onVersionPickerPress with versionId and languageId
    Content->>Content: returns null (escape hatch guard fires)

    note over Root: onVersionPickerPress NOT provided

    Root->>Root: Renders Context.Provider + Popover wrapper
    Consumer->>Trigger: user taps version button
    Trigger->>Root: PopoverTrigger toggles isPopoverOpen
    Root->>Content: isPopoverOpen true, renders PopoverContent

Loading

Comments Outside Diff (1)

1. packages/ui/src/components/bible-version-picker.tsx, line 546-598 (link)

   Content div always renders when escape hatch is active

   When onVersionPickerPress is set, the Content component falls through the !onVersionPickerPress guard and renders a plain, always-visible <div> containing the full version picker UI. Both BibleReader's Toolbar and BibleCard's BibleCardVersionPicker unconditionally include <BibleVersionPicker.Content /> as a child, so enabling the escape hatch immediately injects a permanently-expanded version list inline into the toolbar / card — the opposite of the "suppress popover" intent.

   The simplest fix is to return null early when the escape hatch is active and the caller hasn't supplied explicit open/onRequestClose props (i.e., the default usage inside Toolbar and BibleCardVersionPicker).

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: packages/ui/src/components/bible-version-picker.tsx
   Line: 546-598
   
   Comment:
   **Content div always renders when escape hatch is active**
   
   When `onVersionPickerPress` is set, the `Content` component falls through the `!onVersionPickerPress` guard and renders a plain, always-visible `<div>` containing the full version picker UI. Both `BibleReader`'s Toolbar and `BibleCard`'s `BibleCardVersionPicker` unconditionally include `<BibleVersionPicker.Content />` as a child, so enabling the escape hatch immediately injects a permanently-expanded version list inline into the toolbar / card — the opposite of the "suppress popover" intent.
   
   The simplest fix is to return `null` early when the escape hatch is active and the caller hasn't supplied explicit `open`/`onRequestClose` props (i.e., the default usage inside Toolbar and `BibleCardVersionPicker`).
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

_{Reviews (4): Last reviewed commit: "refactor(ui): use shared DEFAULT_LICENSE..." | Re-trigger Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: f6e7294

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-ui	Minor
vite-react	Patch
@youversion/platform-core	Minor
@youversion/platform-react-hooks	Minor

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