From e0881e5ae33e222b12bd4cb2cbe8310fefd51b3e Mon Sep 17 00:00:00 2001
From: Cameron Pak <cameronandrewpak@gmail.com>
Date: Thu, 4 Jun 2026 12:50:23 -0500
Subject: [PATCH] YPE-2776 - feat(ui): clarify BibleReader loading on chapter
 change

Fade the outgoing chapter text in place behind a sticky, viewport-centered
spinner while the next chapter loads, instead of pulsing the stale text.
Avoids the layout flash a bare spinner would cause and the confusing
stale-but-active text. The opacity transition doubles as a fade-in for the
incoming chapter.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../bible-reader-chapter-loading-overlay.md   |  5 ++
 packages/ui/src/components/verse.test.tsx     |  2 +-
 packages/ui/src/components/verse.tsx          | 62 ++++++++++++-------
 3 files changed, 46 insertions(+), 23 deletions(-)
 create mode 100644 .changeset/bible-reader-chapter-loading-overlay.md

diff --git a/.changeset/bible-reader-chapter-loading-overlay.md b/.changeset/bible-reader-chapter-loading-overlay.md
new file mode 100644
index 00000000..3199d783
--- /dev/null
+++ b/.changeset/bible-reader-chapter-loading-overlay.md
@@ -0,0 +1,5 @@
+---
+'@youversion/platform-react-ui': patch
+---
+
+Improve the chapter-change loading experience in `BibleReader`/`BibleTextView`. Instead of pulsing the previous chapter's text while the next chapter loads, the outgoing text now fades to a low opacity in place (no layout shift) with a spinner overlaid and centered in the visible reading area. This avoids both the confusing stale-but-active text and the flash-of-empty-content a bare spinner would cause, and the opacity transition doubles as a smooth fade-in for the incoming chapter.
diff --git a/packages/ui/src/components/verse.test.tsx b/packages/ui/src/components/verse.test.tsx
index 8db161ae..2a8e0104 100644
--- a/packages/ui/src/components/verse.test.tsx
+++ b/packages/ui/src/components/verse.test.tsx
@@ -668,7 +668,7 @@ describe('BibleTextView - Refetch loading behavior', () => {
     );
 
     await waitFor(() => {
-      const wrapper = container.querySelector('[data-yv-sdk]');
+      const wrapper = container.querySelector('[aria-busy="true"]');
       expect(wrapper).not.toBeNull();
       expect((wrapper as HTMLElement).style.pointerEvents).toBe('none');
     });
diff --git a/packages/ui/src/components/verse.tsx b/packages/ui/src/components/verse.tsx
index 3946e955..59938030 100644
--- a/packages/ui/src/components/verse.tsx
+++ b/packages/ui/src/components/verse.tsx
@@ -544,29 +544,47 @@ export const BibleTextView = forwardRef<HTMLDivElement, BibleTextViewProps>(
       );
     }
 
+    // While the next chapter loads, usePassage keeps returning the previous
+    // passage. Fade it in place behind a spinner rather than clearing it (which
+    // would flash the layout). The spinner is sticky so it stays centered in view
+    // on long chapters.
     return (
-      <div
-        data-yv-sdk
-        data-yv-theme={currentTheme}
-        className={cn(fetchedLoading || currentLoading ? 'yv:animate-pulse' : '')}
-        aria-busy={currentLoading || undefined}
-        style={currentLoading ? { pointerEvents: 'none' } : undefined}
-      >
-        <Verse.Html
-          ref={ref}
-          html={currentPassage?.content || ''}
-          fontFamily={fontFamily}
-          fontSize={fontSize}
-          lineHeight={lineHeight}
-          showVerseNumbers={showVerseNumbers}
-          renderNotes={renderNotes}
-          reference={currentPassage?.reference}
-          theme={currentTheme}
-          selectedVerses={selectedVerses}
-          onVerseSelect={onVerseSelect}
-          highlightedVerses={highlightedVerses}
-          onFootnotePress={onFootnotePress}
-        />
+      <div data-yv-sdk data-yv-theme={currentTheme} className="yv:relative">
+        <div
+          className={cn('yv:transition-opacity yv:duration-300', currentLoading && 'yv:opacity-40')}
+          aria-busy={currentLoading || undefined}
+          style={currentLoading ? { pointerEvents: 'none' } : undefined}
+        >
+          <Verse.Html
+            ref={ref}
+            html={currentPassage?.content || ''}
+            fontFamily={fontFamily}
+            fontSize={fontSize}
+            lineHeight={lineHeight}
+            showVerseNumbers={showVerseNumbers}
+            renderNotes={renderNotes}
+            reference={currentPassage?.reference}
+            theme={currentTheme}
+            selectedVerses={selectedVerses}
+            onVerseSelect={onVerseSelect}
+            highlightedVerses={highlightedVerses}
+            onFootnotePress={onFootnotePress}
+          />
+        </div>
+        {currentLoading && (
+          <div
+            role="status"
+            aria-label={t('loadingPassageAriaLabel')}
+            className="yv:pointer-events-none yv:absolute yv:inset-0"
+          >
+            <div className="yv:sticky yv:top-1/2 yv:flex yv:-translate-y-1/2 yv:justify-center">
+              <LoaderIcon
+                className="yv:size-8 yv:animate-spin yv:text-muted-foreground"
+                aria-hidden="true"
+              />
+            </div>
+          </div>
+        )}
       </div>
     );
   },