YPE-2776 - feat(ui): show loading overlay when changing chapters in BibleReader (#259)

* YPE-2776 - feat(ui): show loading overlay when changing chapters in BibleReader

When changing chapters, BibleReader now keeps the previous chapter's text
mounted, dims it to 40% opacity, and floats a spinner over it after a short
delay — instead of pulsing stale text (confusingly reads as real content) or
flashing a blank spinner. Fast/cached switches stay instant since the dim and
spinner are gated behind a ~250ms delay.

- Lift usePassage into BibleReader.Content and pass passageState down so the
  reader owns the loading treatment without touching BibleTextView. On refetch
  it passes loading:false to suppress BibleTextView's pulse; first load keeps
  BibleTextView's own centered spinner.
- Reset scroll to top on book/chapter change (instant); version-only swaps keep
  scroll position.
- Single role=status live region for the overlay; LoaderIcon is decorative.
- Hoist useDelayedLoading out of bible-card.tsx into a shared lib util.
- Add deterministic unit test for the delay gate + an integration story
  asserting stale text persistence, delayed dim+spinner, recovery, and scroll
  reset.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(ui): address Greptile review on chapter-change loading overlay

- Center the loading spinner with sticky top-[50vh] (viewport-relative)
  instead of top-1/2, which resolved to 50% of the tall passage container
  and could strand the spinner off-screen when scrolled (e.g. on version
  changes where scroll position is preserved).
- Drop redundant aria-live="polite"; role="status" already implies it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore(ui): remove AI-generated comment slop from chapter loading overlay

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: cameronapak

.changeset/bible-reader-chapter-loading-overlay.md

@@ -0,0 +1,5 @@
+---
+'@youversion/platform-react-ui': patch
+---
+
+BibleReader now keeps the previous chapter's text on screen while the next chapter loads, dimming it and floating a spinner over it (after a short delay) instead of pulsing stale text or flashing a blank spinner. Fast/cached chapter switches stay instant, the scroll position resets to the top on chapter change, and the `useDelayedLoading` helper is shared with BibleCard. No changes to BibleTextView.

packages/ui/src/components/bible-card.tsx

@@ -6,28 +6,12 @@ import { BibleTextView, type FootnoteData } from './verse';
 import { BibleAppLogoLockup } from './bible-app-logo-lockup';
 import { BibleVersionPicker, type BibleVersionPickerPressData } from './bible-version-picker';
 import { Button } from './ui/button';
-import { useEffect, useState } from 'react';
 import { useControllableState } from '@radix-ui/react-use-controllable-state';
 import { SOURCE_SERIF_FONT } from '@/lib/verse-html-utils';
+import { useDelayedLoading } from '@/lib/use-delayed-loading';
 import { LoaderIcon } from './icons/loader';
 import { AnimatedHeight } from './animated-height';
 
-function useDelayedLoading(loading: boolean, delay = 250): boolean {
-  const [showSpinner, setShowSpinner] = useState(false);
-
-  useEffect(() => {
-    if (!loading) {
-      setShowSpinner(false);
-      return;
-    }
-
-    const timer = setTimeout(() => setShowSpinner(true), delay);
-    return () => clearTimeout(timer);
-  }, [loading, delay]);
-
-  return showSpinner;
-}
-
 type PassageResult = ReturnType<typeof usePassage>;
 type VersionResult = ReturnType<typeof useVersion>;
 

packages/ui/src/components/bible-reader.stories.tsx

@@ -5,6 +5,7 @@ import { BibleReader } from './bible-reader';
 import { setupAuthenticatedUser } from '../test/utils';
 import { INTER_FONT, SOURCE_SERIF_FONT } from '@/lib/verse-html-utils';
 import mockBibles from '../test/mock-data/bibles.json';
+import { globalHandlers } from '../test/mocks/handlers';
 
 let signInMock: ReturnType<typeof fn>;
 
@@ -794,3 +795,78 @@ export const JoshuaIntroChapter: Story = {
     });
   },
 };
+
+export const ChapterChangeLoadingOverlay: Story = {
+  tags: ['integration'],
+  args: {
+    defaultVersionId: 111,
+    defaultBook: 'JHN',
+    defaultChapter: '1',
+  },
+  parameters: {
+    msw: {
+      handlers: [
+        http.get('*/v1/bibles/111/passages/:usfm', async ({ params }) => {
+          await delay(800);
+          const usfm = params.usfm as string;
+          return HttpResponse.json({
+            id: usfm,
+            content: `<div class="p"><span class="verse">Passage text for ${usfm}.</span></div>`,
+            reference: usfm,
+          });
+        }),
+        ...globalHandlers,
+      ],
+    },
+  },
+  render: (args) => (
+    <div className="yv:h-screen yv:bg-background">
+      <BibleReader.Root {...args}>
+        <BibleReader.Content />
+        <BibleReader.Toolbar />
+      </BibleReader.Root>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    await waitFor(
+      async () => {
+        const renderer = canvasElement.querySelector('[data-slot="yv-bible-renderer"]');
+        await expect(renderer?.textContent).toContain('JHN.1');
+      },
+      { timeout: 5000 },
+    );
+
+    const nextButton = screen.getByRole('button', { name: /next chapter/i });
+    await userEvent.click(nextButton);
+
+    const rendererAfterClick = canvasElement.querySelector('[data-slot="yv-bible-renderer"]');
+    await expect(rendererAfterClick?.textContent).toContain('JHN.1');
+
+    await waitFor(
+      async () => {
+        const overlay = canvasElement.querySelector('[aria-label="Loading passage"]');
+        await expect(overlay).toBeInTheDocument();
+        await expect(overlay).toHaveAttribute('role', 'status');
+        await expect(canvasElement.querySelector('[class*="opacity-40"]')).toBeInTheDocument();
+        const renderer = canvasElement.querySelector('[data-slot="yv-bible-renderer"]');
+        await expect(renderer?.textContent).toContain('JHN.1');
+      },
+      { timeout: 2000 },
+    );
+
+    await waitFor(
+      async () => {
+        const renderer = canvasElement.querySelector('[data-slot="yv-bible-renderer"]');
+        await expect(renderer?.textContent).toContain('JHN.2');
+        await expect(
+          canvasElement.querySelector('[aria-label="Loading passage"]'),
+        ).not.toBeInTheDocument();
+        await expect(canvasElement.querySelector('[class*="opacity-40"]')).not.toBeInTheDocument();
+      },
+      { timeout: 5000 },
+    );
+
+    const scroller = canvasElement.querySelector('main');
+    await expect(scroller?.scrollTop).toBe(0);
+  },
+};

packages/ui/src/components/bible-reader.tsx

@@ -5,6 +5,7 @@ import i18n from '@/i18n';
 import { useControllableState } from '@radix-ui/react-use-controllable-state';
 import {
   useBooks,
+  usePassage,
   useTheme,
   useVersion,
   useYVAuth,
@@ -22,6 +23,7 @@ import {
   type ReactElement,
 } from 'react';
 import { cn } from '@/lib/utils';
+import { useDelayedLoading } from '@/lib/use-delayed-loading';
 import { DEFAULT_LICENSE_FREE_BIBLE_VERSION, getAdjacentChapter } from '@youversion/platform-core';
 import { BibleChapterPicker, type BibleChapterPickerPressData } from './bible-chapter-picker';
 import { BibleVersionPicker, type BibleVersionPickerPressData } from './bible-version-picker';
@@ -349,13 +351,39 @@ function Content() {
     return !inChapters && !isIntro;
   }, [bookData, chapter]);
 
+  // Own the passage fetch here (instead of BibleTextView) to control the loading
+  // treatment. Args mirror BibleTextView's internal fetch so the cache key matches.
+  const {
+    passage,
+    loading: passageLoading,
+    error: passageError,
+  } = usePassage({
+    versionId,
+    usfm: usfmReference,
+    include_headings: true,
+    include_notes: true,
+    options: { enabled: !chapterUnavailable },
+  });
+
+  const isRefetching = !chapterUnavailable && passageLoading && passage !== null;
+  const showLoadingOverlay = useDelayedLoading(isRefetching);
+
+  // Version-only changes intentionally preserve scroll position.
+  const scrollContainerRef = useRef<HTMLElement>(null);
+  useEffect(() => {
+    scrollContainerRef.current?.scrollTo({ top: 0 });
+  }, [book, chapter]);
+
   let chapterLabel: string = bookData?.chapters?.find((ch) => ch.id === chapter)?.title || chapter;
   if (bookData?.intro && chapter === bookData?.intro.id) {
     chapterLabel = bookData.intro.title;
   }
 
   return (
-    <main className="yv:*:max-w-lg yv:flex yv:flex-col yv:items-center yv:gap-6 yv:overflow-y-auto yv:px-6 yv:max-sm:px-4 yv:py-12 yv:h-full">
+    <main
+      ref={scrollContainerRef}
+      className="yv:*:max-w-lg yv:flex yv:flex-col yv:items-center yv:gap-6 yv:overflow-y-auto yv:px-6 yv:max-sm:px-4 yv:py-12 yv:h-full"
+    >
       <h1 className="yv:flex yv:gap-2 yv:flex-col yv:justify-center yv:items-center yv:text-muted-foreground yv:font-medium">
         <span
           className={cn(
@@ -376,16 +404,46 @@ function Content() {
           {t('chapterUnavailable')}
         </p>
       ) : (
-        <BibleTextView
-          reference={usfmReference}
-          versionId={versionId}
-          fontFamily={currentFontFamily}
-          fontSize={currentFontSize}
-          lineHeight={lineHeight}
-          showVerseNumbers={showVerseNumbers}
-          theme={background}
-          onFootnotePress={onFootnotePress}
-        />
+        <div className="yv:relative yv:w-full">
+          <div
+            className={cn(
+              'yv:transition-opacity yv:duration-150 yv:motion-reduce:transition-none',
+              showLoadingOverlay ? 'yv:opacity-40' : 'yv:opacity-100',
+            )}
+          >
+            <BibleTextView
+              reference={usfmReference}
+              versionId={versionId}
+              fontFamily={currentFontFamily}
+              fontSize={currentFontSize}
+              lineHeight={lineHeight}
+              showVerseNumbers={showVerseNumbers}
+              theme={background}
+              onFootnotePress={onFootnotePress}
+              passageState={{
+                passage,
+                loading: isRefetching ? false : passageLoading,
+                error: passageError,
+              }}
+            />
+          </div>
+
+          {showLoadingOverlay ? (
+            <div
+              role="status"
+              aria-label={t('loadingPassageAriaLabel')}
+              className="yv:pointer-events-none yv:absolute yv:inset-0"
+            >
+              {/* top-[50vh] (viewport-relative) keeps the spinner centered in the scrollport.
+                  top-1/2 would resolve to 50% of the tall passage container and strand the
+                  spinner off-screen when scrolled (e.g. on version changes). */}
+              <LoaderIcon
+                className="yv:sticky yv:top-[50vh] yv:mx-auto yv:block yv:size-6 yv:-translate-y-1/2 yv:animate-spin yv:text-muted-foreground"
+                aria-hidden="true"
+              />
+            </div>
+          ) : null}
+        </div>
       )}
 
       {version?.copyright && (

packages/ui/src/lib/use-delayed-loading.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useDelayedLoading } from './use-delayed-loading';
+
+describe('useDelayedLoading', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('stays false while not loading', () => {
+    const { result } = renderHook(() => useDelayedLoading(false));
+    expect(result.current).toBe(false);
+  });
+
+  it('does not surface a fast load that resolves before the delay', () => {
+    const { result, rerender } = renderHook(({ loading }) => useDelayedLoading(loading, 250), {
+      initialProps: { loading: true },
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(200);
+    });
+    expect(result.current).toBe(false);
+
+    rerender({ loading: false });
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current).toBe(false);
+  });
+
+  it('surfaces a slow load once the delay elapses', () => {
+    const { result } = renderHook(() => useDelayedLoading(true, 250));
+
+    expect(result.current).toBe(false);
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(result.current).toBe(true);
+  });
+
+  it('resets to false as soon as loading clears', () => {
+    const { result, rerender } = renderHook(({ loading }) => useDelayedLoading(loading, 250), {
+      initialProps: { loading: true },
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(250);
+    });
+    expect(result.current).toBe(true);
+
+    rerender({ loading: false });
+    expect(result.current).toBe(false);
+  });
+});

packages/ui/src/lib/use-delayed-loading.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+
+export function useDelayedLoading(loading: boolean, delay = 250): boolean {
+  const [showSpinner, setShowSpinner] = useState(false);
+
+  useEffect(() => {
+    if (!loading) {
+      setShowSpinner(false);
+      return;
+    }
+
+    const timer = setTimeout(() => setShowSpinner(true), delay);
+    return () => clearTimeout(timer);
+  }, [loading, delay]);
+
+  return showSpinner;
+}