YPE-1204: Fix verse error states + display reference

[jaredhightower-youversion]

Summary

Problem

When using passage?.reference directly in BibleCard, the reference header showed nothing while the API was loading or if the request failed. Users saw a blank space where the reference (e.g. "JOHN 3:16 NIV") should be.

The error state in BibleTextView also displayed a generic "We have run into an error..." message styled as Bible text, which was confusing and didn't match design specs.

Solution

Core (@youversion/platform-core)

• Added formatUsfmForDisplay utility that converts raw USFM strings (e.g. "JHN.3.16") into human-readable references (e.g. "JOHN 3:16")
• Supports book+chapter+verse, chapter-only, and book-only formats
• Exported UsfmBookCode and UsfmReference types for type-safe USFM handling with IDE autocomplete
• Added unit tests covering all format variations

UI (@youversion/platform-react-ui)

• BibleCard: Uses displayReference fallback pattern — shows server reference when available, falls back to client-formatted USFM during loading/error so the header is always visible
• BibleTextView: Replaced generic error string with a dedicated VerseUnavailableMessage component featuring an ExclamationCircle icon matching the Figma design
• Added ExclamationCircle icon component

How it works

// Before: nothing shown during loading or error
{passage?.reference ? <h2>{passage.reference}</h2> : null}

// After: always shows a reference
const displayReference =
  passage?.reference ?? (reference ? formatUsfmForDisplay(reference) : null);
{displayReference ? <h2>{displayReference}</h2> : null}

[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.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 980d393

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[greptile-apps]

Greptile Summary

Improved user experience by ensuring Bible references are always visible and error states are clear and accessible.

Core changes:

• Added formatUsfmForDisplay utility in @youversion/platform-core to convert USFM codes (e.g., "JHN.3.16") to human-readable format ("JOHN 3:16")
• Includes comprehensive book name mappings for the Protestant canon with proper TypeScript types
• Unit tests cover all format variations (book+chapter+verse, chapter-only, book-only, verse ranges)

UI improvements:

• BibleCard now shows a formatted reference during loading/error states instead of blank space
• BibleTextView displays a properly styled error component with icon instead of confusing fake Bible text
• New VerseUnavailableMessage component with accessibility attributes (role="alert", aria-live="polite")
• Added ExclamationCircle icon following established component patterns

Confidence Score: 5/5

• This PR is safe to merge with no issues found
• Clean implementation with comprehensive test coverage, proper TypeScript types, follows project conventions, maintains package boundaries (core → ui), includes accessibility improvements, and solves the stated UX problems without introducing risks
• No files require special attention

Important Files Changed

Filename	Overview
packages/core/src/utils/reference.ts	Added formatUsfmForDisplay utility with comprehensive USFM book mapping and proper type safety
packages/core/src/tests/reference.test.ts	Comprehensive test coverage for all USFM format variations including edge cases
packages/ui/src/components/bible-card.tsx	Implemented fallback pattern using formatUsfmForDisplay to ensure reference is always visible during loading/error states
packages/ui/src/components/verse.tsx	Replaced generic error HTML with dedicated VerseUnavailableMessage component with proper accessibility attributes

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[BibleCard Component] --> B{passage?.reference available?}
    B -->|Yes| C[Display server reference]
    B -->|No| D{reference prop exists?}
    D -->|Yes| E[formatUsfmForDisplay reference]
    D -->|No| F[Display nothing]
    E --> G[Show formatted USFM]
    C --> H[Render header with reference]
    G --> H
    
    I[BibleTextView Component] --> J{API State?}
    J -->|Loading| K[Show Loading...]
    J -->|Error| L[VerseUnavailableMessage]
    J -->|Success| M[Render Bible HTML]
    L --> N[ExclamationCircle Icon + Error Text]
    
    O[formatUsfmForDisplay] --> P[Split USFM by dots]
    P --> Q{Has chapter & verse?}
    Q -->|Yes| R[Format: BOOK C:V]
    Q -->|No| S{Has chapter only?}
    S -->|Yes| T[Format: BOOK C]
    S -->|No| U[Format: BOOK]

Loading

_{Last reviewed commit: 980d393}

[greptile-apps]

_{6 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}