fix(ui): collapse the BibleCard error state into one alert region

[cameronapak]

YPE-2360 | Artifacts | Task

What problems was I solving

The BibleCard component shows an error state when a Bible passage does not load. This error state had two faults.

Fault 1. A screen reader announced two alerts for one failure.

The card showed two separate regions with role="alert". The first region was the word "ERROR" in the header slot. The second region was an icon plus a sentence that explains the error. Both regions were live regions. A screen reader therefore announced the word "Error" first, and then announced the sentence as a second alert.

Fault 2. An error was a dead end.

The card hid the version picker when passageError was set. A 404 error means the passage is not in the selected Bible version. The fix is to select a different version. The card removed that control at the moment the reader needed it.

After this change, a failed request announces one alert. That alert carries the sentence that explains the error. The reader can also select a different version without leaving the card.

What user-facing changes did I ship

• packages/ui/src/components/bible-card.tsx - The word "ERROR" keeps its position and its style. It loses role="alert" and aria-live, so a screen reader no longer announces it as a second alert. The version picker now shows during an error.
• packages/ui/src/components/verse.tsx - The message block loses a duplicate aria-live, because role="alert" already makes the block a live region. The icon now has aria-hidden, so a screen reader skips it.

VerseOfTheDay and standalone BibleTextView show the same message block. Both components get the same two accessibility fixes. The text that they show does not change. Neither component gets an "ERROR" label, because that label belongs to the BibleCard header slot.

This change adds no new i18n keys. The eight status-aware messages, their six locales, and the code that derives errors are all unchanged.

How I implemented it

One alert region

In bible-card.tsx, BibleCardHeaderError was a div with role="alert" and aria-live="polite" around one <h2>. It is now the <h2> alone. The div held no classes that changed the layout, so the card looks the same.

The <h2> uses the same classes as BibleCardHeaderReference. This reuse is deliberate. The card already puts an <h2> in that slot for the passage reference. The error label therefore adds no new heading level to the outline of the host page.

In verse.tsx, VerseUnavailableMessage keeps role="alert" and becomes the only alert region. It loses aria-live and marks its icon aria-hidden.

The header ternary keeps three branches instead of two. Two branches would fall through to the loading spinner during an error. The spinner would then turn forever.

The version picker during an error

In bible-card.tsx, the condition changed from showVersionPicker && !passageError to showVersionPicker. This is the whole source change. The picker reads versionNum and not the passage, so it works while passageError is set.

The header row needs no layout change. The word "ERROR" still sits on the left and the picker on the right. The class yv:justify-between is still correct.

Tests and the Storybook story

bible-card.test.tsx gets a new BibleCard - Error state block with five tests:

• Exactly one role="alert" region shows.
• That region carries the 503 sentence.
• The header shows an <h2> that reads "Error".
• No role="status" spinner shows during an error.
• The version picker shows and is enabled during an error.

The picker test needed five more hook mocks: useLanguages, useLanguage, useVersions, useFilteredVersions, and useOrganizations. The file mocks the hooks package with a bare vi.mock call. Every export therefore returns undefined, and BibleVersionPicker.Root reads these five.

verse.test.tsx gets one test. The alert has no aria-live. The icon has aria-hidden. The alert holds no "Error" text, because a standalone BibleTextView has no header slot.

bible-card.stories.tsx gets showVersionPicker: true on the Error story. Its play function now tests for one alert region and an enabled picker.

.changeset/biblecard-single-error-alert.md is a patch that names @youversion/platform-react-ui.

Deviations from the plan

The plan artifact is a structure outline, not a plan file. It changed twice during the work, so it already describes the final direction. The code and the outline now agree on every phase.

Implemented as planned

• VerseUnavailableMessage keeps role="alert", loses aria-live, and marks its icon aria-hidden.
• BibleCardHeaderError is now a bare <h2> with the classes of BibleCardHeaderReference.
• The header ternary keeps three branches.
• The version picker condition loses && !passageError.
• The tests and the story cover every case that the outline listed.
• No new i18n keys. The errorHeading key comes from the existing locale files.

Deviations and surprises

1. The outline said that the story must test that the picker shows and is enabled. The story also tests that the button text matches /NIV/i. This test is stricter than the outline, and it does not conflict with it.
2. The changeset names one package. The outline asked for three. .changeset/config.json already puts the three packages in a fixed group, so a changeset that names platform-react-ui alone still bumps all three. pnpm changeset status shows this result. A changeset that names all three would also copy this UI-only text into packages/core/CHANGELOG.md and packages/hooks/CHANGELOG.md. The three most recent UI fixes on main (b592e72, 9c2e8e4, 9a2b3e9) each name only the package that changed. The outline records this deviation in its Phase 3 section.

Additions that are not in the plan

Doc comments above BibleCardHeaderError, the header ternary, the version picker condition, and VerseUnavailableMessage. They put the reasoning of the outline into the source. They change no behavior.

Items that were planned but not implemented

None.

How the outline changed during the work

The outline changed shape twice. This history matters only if you read the artifacts next to the diff.

1. The design discussion decided to remove the header label completely.
2. A later outline revision put the word "Error" back, but inside the message block, above the sentence.
3. On 2026-08-07, Cam reviewed the result in Storybook and reversed that decision. The label stays in the header slot. Only its alert semantics change. The code does this.

That reversal made two planned Phase 2 changes unnecessary. Both changes assumed an empty header slot. The header slot always has a child during an error. The justify-end change and the empty-row check therefore left the outline before Phase 2 started.

How to verify it

Run these commands first:

git fetch origin ype-2360-react-biblecard-error-state-needs-better-text
git checkout ype-2360-react-biblecard-error-state-needs-better-text
pnpm install
pnpm --filter @youversion/platform-core --filter @youversion/platform-react-hooks build
pnpm --filter @youversion/platform-react-ui storybook

Manual tests

• Open Components/BibleCard → Error. Make sure that "ERROR" is in the header slot, above one block with the icon and the sentence.
• Set the Storybook theme global to dark. Make sure that the story still reads correctly.
• Start VoiceOver. Make sure that it announces one alert, and that this alert is the sentence.
• In the Error story, open the version picker and select a different version.
• Make sure that the card recovers when the new version returns the passage.
• Open Components/VerseOfTheDay and Components/BibleTextView. Both show the icon and the sentence, with no label.

Automated tests

pnpm typecheck
pnpm lint
pnpm test
pnpm --filter @youversion/platform-react-ui test:integration

If you use a fresh worktree, do these two steps before you run the commands above:

1. Copy packages/core/.env.example to packages/core/.env.local. Without this file, YVP_API_HOST is empty and all 16 core suites fail to collect. The core tests use MSW mocks, so placeholder values are enough. CI supplies both values as secrets.
2. Run pnpm --filter @youversion/platform-react-ui build:css. Without dist/tailwind.css, two WideContainer stories fail on the missing yv:card-content cap. This failure is not related to this branch.

Results on this branch: pnpm test passes 1065 tests (core 369, hooks 289, ui 407). test:integration passes 452 tests. pnpm build --force passes, including verify:styles.

Description for the changelog

Fix the BibleCard error state that announced two alerts instead of one, and keep the version picker usable during an error.

Greptile Summary

The PR consolidates BibleCard errors into one alert region while preserving an error heading and allowing users to switch Bible versions during passage failures.

• Removes duplicate live-region semantics from the card header and shared unavailable-message component.
• Keeps the version picker mounted as an in-card recovery path.
• Hides the decorative error icon from assistive technology.
• Adds unit and Storybook coverage for alert count, heading semantics, and picker availability.
• Adds the required patch changeset.

Confidence Score: 5/5

The PR appears safe to merge, with the accessibility and error-recovery behavior consistently implemented and covered.

The card retains one reachable error alert, preserves a semantic error heading, and exposes the existing version picker during passage failures without a supported path to a render, state, or accessibility regression.

Important Files Changed

Filename	Overview
packages/ui/src/components/bible-card.tsx	Separates the visual error heading from the sole body alert and keeps the version picker available during passage errors without introducing a conflicting loading state.
packages/ui/src/components/verse.tsx	Removes redundant live-region configuration and marks the error icon decorative while retaining the shared status-aware alert message.
packages/ui/src/components/bible-card.test.tsx	Adds focused coverage for one alert, the error heading, absence of a loading status, and picker usability during errors.
packages/ui/src/components/verse.test.tsx	Verifies the shared error alert has no redundant aria-live attribute, hides its icon, and does not add an Error label to standalone usage.
packages/ui/src/components/bible-card.stories.tsx	Updates the integration error story to exercise the single-alert contract and available version-picker recovery path.
.changeset/biblecard-single-error-alert.md	Records the user-visible accessibility and recovery behavior as a patch release.

_{Reviews (1): Last reviewed commit: "chore: add changeset for the BibleCard e..." | Re-trigger Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: f7fcc99

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