fix(ui): show specific Bible passage error messages

[davidfedor]

Map BibleTextView errors to clearer user-facing messages for missing passages, missing or invalid app keys, forbidden access, rate limits, unreachable server/timeouts, and 5xx responses.

Extract the error-message mapping into a dedicated UI helper and extend component tests to cover the new cases.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6fcfbc6

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

[greptile-apps]

Greptile Summary

This PR extracts a new getBibleTextErrorMessage utility that maps HTTP status codes (401, 403, 404, 429, 5xx) and network error patterns to six distinct, user-facing messages, replacing the single hard-coded "unavailable" string previously shown for all errors in BibleTextView. The component and its Storybook story are updated accordingly, and eight new Vitest cases cover every mapped error category.

Key changes:

• New packages/ui/src/lib/bible-text-error.ts helper with status-first guards (5xx checked before the 404/not-found string fallback, closing the shadowing risk) and navigator.onLine awareness for offline detection
• VerseUnavailableMessage now accepts a message prop; BibleTextView supplies it via getBibleTextErrorMessage(currentError)
• Storybook Error story expectation updated to SERVER_ERROR_MESSAGE (the story's MSW stub returns a 500)
• Eight new unit tests; the offline test correctly uses a neutral error string that bypasses isUnreachableServerError, isolating the navigator.onLine branch
• Changeset bumps all three packages at patch level, satisfying unified versioning policy

Minor findings:

• The GENERIC_ERROR_MESSAGE fallback (no status, online, no string match) has no dedicated test
• The JSDoc on VerseUnavailableMessage still describes it as a "verse-unavailable" message rather than the broader error-display role it now serves

Confidence Score: 5/5

Safe to merge — all remaining findings are non-blocking P2 style suggestions with no correctness or runtime impact.

The two previously flagged issues (5xx/not-found ordering and offline test isolation) have been properly addressed in this revision. The error-mapping logic is correct, the new tests are well-targeted, and the changeset follows the unified versioning policy. The only open items are a missing test for the generic fallback path and a stale JSDoc comment, both P2 with no impact on runtime behaviour.

No files require special attention.

Important Files Changed

Filename	Overview
packages/ui/src/lib/bible-text-error.ts	New helper that maps HTTP status codes and error message strings to user-facing strings; logic is correct and the 5xx guard is evaluated before the 404/not-found guard. Generic fallback path (GENERIC_ERROR_MESSAGE) is untested.
packages/ui/src/components/verse.tsx	Removes hard-coded VERSE_UNAVAILABLE_MESSAGE and threads the dynamic message from getBibleTextErrorMessage through the VerseUnavailableMessage prop; JSDoc on VerseUnavailableMessage is now slightly outdated.
packages/ui/src/components/verse.test.tsx	Adds eight new test cases covering 401, 403, 404, 429, 503, offline, timeout, and 5xx-with-not-found scenarios; offline test now uses a message that does not match any string pattern, correctly isolating the navigator.onLine branch.
packages/ui/src/components/bible-card.stories.tsx	Story expectation updated to SERVER_ERROR_MESSAGE to match the 500 MSW stub — correctly reflects the new message mapping.
.changeset/fresh-towns-marry.md	Patch bump for all three packages, satisfying the unified versioning requirement.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[BibleTextView receives error] --> B[getBibleTextErrorMessage]
    B --> C{status === 401?}
    C -- Yes --> D[INVALID_APP_KEY_MESSAGE]
    C -- No --> E{status === 403?}
    E -- Yes --> F[FORBIDDEN_MESSAGE]
    E -- No --> G{status === 429?}
    G -- Yes --> H[RATE_LIMITED_MESSAGE]
    G -- No --> I{status >= 500?}
    I -- Yes --> J[SERVER_ERROR_MESSAGE]
    I -- No --> K{status === 404 OR message includes 'not found'?}
    K -- Yes --> L[PASSAGE_NOT_FOUND_MESSAGE]
    K -- No --> M{navigator.onLine === false?}
    M -- Yes --> N[UNREACHABLE_SERVER_MESSAGE]
    M -- No --> O{isUnreachableServerError message?}
    O -- Yes --> N
    O -- No --> P[GENERIC_ERROR_MESSAGE]
    D & F & H & J & L & N & P --> Q[VerseUnavailableMessage renders message]

Loading

_{Reviews (4): Last reviewed commit: "chore: add changeset" | Re-trigger Greptile}

[davidfedor]

@greptile are all your concerns addressed satisfactorily?

[greptile-apps]

Yes, both concerns are addressed:

P1 (5xx shadowing): Fixed by checking status >= 500 before the message.includes('not found') check. A 503 with "not found" in the message now correctly returns the server error message, as verified by the new test.

P2 (offline test isolation): Fixed by using 'Unexpected connection state' as the error message, which doesn't match any of the string patterns in isUnreachableServerError. The test now properly isolates the navigator.onLine === false code path.

[davidfedor]

@cameronapak I'd love your thoughts on this. Is there a different way you'd suggest that this be structured? Feel free to completely rewrite this if I'm not approaching it the right way.

[cameronapak]

This looks good to me. Thank you for making it where we have better, more specific error copy! Can you run pnpm changeset at the project's root to bump all of the packages, so that the changes propogate into the next version? (we bump them all at once for them to stay on the same version across the board for react sdk packages)

[davidfedor]

@cameronapak changeset added; care to re-review?

[cameronapak]

Approved!