Cleanup

Author: alex-rawlings-yyc

src/components/ContinuousView.tsx

@@ -14,7 +14,7 @@ import { buildRenderUnits, groupTokens, resolveFocusContext } from '../utils/tok
 import { useArcPaths } from '../hooks/useArcPaths';
 import { usePhraseHoverState } from '../hooks/usePhraseHoverState';
 import MemoizedArcOverlay from './ArcOverlay';
-import { RECENTER_FADE_EASING, RECENTER_FADE_MS } from './recenter-fade';
+import { RECENTER_FADE_MS, RECENTER_FADE_TRANSITION_STYLE } from './recenter-fade';
 
 /**
  * Clamps `index` to `[0, len - 1]`, returning `0` when `len` is zero.
@@ -29,19 +29,6 @@ function clampIndex(index: number, len: number): number {
   return Math.max(0, Math.min(index, len - 1));
 }
 
-/**
- * CSS easing for the strip opacity fade-in/out animation. Aliased to the shared
- * {@link RECENTER_FADE_EASING} so the strip and the segment list fade on the same curve.
- */
-const STRIP_FADE_EASING = RECENTER_FADE_EASING;
-
-/**
- * Duration of the strip fade animation in milliseconds. Aliased to the shared
- * {@link RECENTER_FADE_MS} so the strip and the segment list fade as one; must match the
- * `setTimeout` in the pending-jump effect.
- */
-const STRIP_FADE_MS = RECENTER_FADE_MS;
-
 /**
  * Backstop, in milliseconds, for committing the deferred inactive-link relayout after an
  * internal-nav smooth scroll. The relayout normally fires on the scroll container's `scrollend`
@@ -292,6 +279,24 @@ export default function ContinuousView({
   /** DOM ref array indexed by group index; used to scroll the focused phrase box into view. */
   const phraseRefs = useRef<(HTMLSpanElement | null)[]>([]);
 
+  /**
+   * Scrolls the phrase group at `groupIndex` to horizontal center of the strip. Every centering
+   * call site shares the `block: 'nearest', inline: 'center'` options and differs only in
+   * `behavior`, so they route through here. Stable identity (reads `phraseRefs` and takes the index
+   * explicitly) so the effects that center a snapshot index keep their intentionally-narrow dep
+   * arrays.
+   *
+   * @param groupIndex - Index into `phraseRefs` of the group to center.
+   * @param behavior - `'auto'` for an instant jump, `'smooth'` for an animated glide.
+   */
+  const centerGroup = useCallback((groupIndex: number, behavior: ScrollBehavior) => {
+    phraseRefs.current[groupIndex]?.scrollIntoView({
+      behavior,
+      block: 'nearest',
+      inline: 'center',
+    });
+  }, []);
+
   /** Ref to the token-strip row; the content row and mouse-leave target. */
   // eslint-disable-next-line no-null/no-null
   const stripRowRef = useRef<HTMLDivElement | null>(null);
@@ -483,7 +488,7 @@ export default function ContinuousView({
     setIsVisible(false);
     const timeout = setTimeout(() => {
       setDisplayFocusedTokenRef(focusedTokenRef);
-    }, STRIP_FADE_MS);
+    }, RECENTER_FADE_MS);
     return () => clearTimeout(timeout);
   }, [focusedTokenRef, displayFocusedTokenRef]);
 
@@ -501,11 +506,7 @@ export default function ContinuousView({
       // to disturb — commit the active segment now alongside the instant scroll.
       setSkipSlotTransitionForJump(true);
       commitPendingActiveSegment();
-      phraseRefs.current[focusPhraseIndex]?.scrollIntoView({
-        behavior: 'auto',
-        block: 'nearest',
-        inline: 'center',
-      });
+      centerGroup(focusPhraseIndex, 'auto');
     }
 
     if (isInternal && !isInitialLoad) {
@@ -514,11 +515,7 @@ export default function ContinuousView({
       // Scrolling synchronously here animates toward a position that then shifts, producing a visible
       // overshoot-and-return ("yank") when crossing a verse boundary.
       const navRafId = requestAnimationFrame(() => {
-        phraseRefs.current[focusPhraseIndex]?.scrollIntoView({
-          behavior: 'smooth',
-          block: 'nearest',
-          inline: 'center',
-        });
+        centerGroup(focusPhraseIndex, 'smooth');
       });
       // Commit the active-segment change (which toggles inactive link-icon visibility, re-laying out
       // the strip) only once the smooth scroll has actually settled. Updating it mid-scroll would
@@ -562,7 +559,7 @@ export default function ContinuousView({
       cancelAnimationFrame(rafId);
       setIsVisible(true);
     };
-  }, [focusPhraseIndex, commitPendingActiveSegment]);
+  }, [focusPhraseIndex, commitPendingActiveSegment, centerGroup]);
 
   // Keep the focused group pinned dead-center after the deferred active-segment flip. When
   // `committedActiveSegmentId` flips (after an internal-nav scroll settles), inactive link icons
@@ -580,13 +577,7 @@ export default function ContinuousView({
       return undefined;
     }
     /** Re-centers the focused group; called synchronously now and each `rAF` until the deadline. */
-    const recenter = () => {
-      phraseRefs.current[focusPhraseIndex]?.scrollIntoView({
-        behavior: 'auto',
-        block: 'nearest',
-        inline: 'center',
-      });
-    };
+    const recenter = () => centerGroup(focusPhraseIndex, 'auto');
     recenter();
     const deadline = performance.now() + LINK_SLOT_TRANSITION_MS;
     let rafId = requestAnimationFrame(function recenterFrame() {
@@ -605,13 +596,9 @@ export default function ContinuousView({
   // when hidden (`opacity: 0`; clickability is guarded at the button level), so toggling it does
   // not shift the layout.
   useEffect(() => {
-    phraseRefs.current[focusPhraseIndex]?.scrollIntoView({
-      behavior: 'auto',
-      block: 'nearest',
-      inline: 'center',
-    });
+    centerGroup(focusPhraseIndex, 'auto');
     // focusPhraseIndex is intentionally excluded: it has its own scroll effect above. This effect
-    // only re-centers in response to layout-affecting option toggles.
+    // only re-centers in response to layout-affecting option toggles. centerGroup is stable.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [simplifyPhrases]);
 
@@ -909,10 +896,7 @@ export default function ContinuousView({
           data-testid="strip-fade-wrapper"
           ref={arcContainerRef}
           className={`tw:arc-container tw:transition-opacity ${stripOpacityClass}`}
-          style={{
-            transitionDuration: `${STRIP_FADE_MS}ms`,
-            transitionTimingFunction: STRIP_FADE_EASING,
-          }}
+          style={RECENTER_FADE_TRANSITION_STYLE}
         >
           <MemoizedArcOverlay
             arcPaths={arcPaths}

src/components/Interlinearizer.tsx

@@ -10,7 +10,19 @@ import { isWordToken } from '../types/type-guards';
 import SegmentListView from './SegmentListView';
 import UnlinkPhraseConfirm from './modals/UnlinkPhraseConfirm';
 import { useInterlinearNav } from './InterlinearNavContext';
-import { RECENTER_FADE_EASING, RECENTER_FADE_MS } from './recenter-fade';
+import { RECENTER_FADE_TRANSITION_STYLE } from './recenter-fade';
+
+/**
+ * Returns the ref of the first word token in `segment`, or `undefined` when the segment has none.
+ * The seed value for `focusedTokenRef` whenever focus must fall back to the active verse's leading
+ * word (initial mount, book change, and external verse reseed).
+ *
+ * @param segment - The segment to read, or `undefined` when no active segment is resolved.
+ * @returns The first word token's ref, or `undefined`.
+ */
+function firstWordTokenRefOf(segment: Segment | undefined): string | undefined {
+  return segment?.tokens.find(isWordToken)?.ref;
+}
 
 /** Props for {@link Interlinearizer}. */
 type InterlinearizerProps = Readonly<{
@@ -105,14 +117,14 @@ function InterlinearizerInner({
   // Seed focusedTokenRef from the active verse on first render so the views always see a defined
   // value. An undefined focusedTokenRef would disable all link buttons (isSameSegmentAsFocus checks
   // focus.focusedSegmentId), so we never want it unset while there's a valid seed available.
-  const [focusedTokenRef, setFocusedTokenRef] = useState<string | undefined>(
-    () => findActiveSegment()?.tokens.find((t) => t.type === 'word')?.ref,
+  const [focusedTokenRef, setFocusedTokenRef] = useState<string | undefined>(() =>
+    firstWordTokenRefOf(findActiveSegment()),
   );
 
   // Reseed when the book changes — the previous focusedTokenRef refers to a token from another
   // book and would never resolve in the new book's maps.
   useEffect(() => {
-    setFocusedTokenRef(findActiveSegment()?.tokens.find((t) => t.type === 'word')?.ref);
+    setFocusedTokenRef(firstWordTokenRefOf(findActiveSegment()));
     // findActiveSegment changes with scrRef too; only re-seed on book change.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [book]);
@@ -213,7 +225,7 @@ function InterlinearizerInner({
     const activeSeg = findActiveSegment();
     if (focusedTokenRef && tokenSegmentMap.get(focusedTokenRef) === activeSeg?.id) return;
     /* v8 ignore next -- activeSeg is always defined when the book includes the active verse */
-    setFocusedTokenRef(activeSeg?.tokens.find((t) => t.type === 'word')?.ref);
+    setFocusedTokenRef(firstWordTokenRefOf(activeSeg));
     // findActiveSegment is intentionally excluded: the verse-coordinate deps already capture the
     // change we care about, and it changes identity on every scrRef update.
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -292,11 +304,7 @@ function InterlinearizerInner({
       )}
       <div
         className="tw:flex tw:flex-col tw:flex-1 tw:min-h-0 tw:transition-opacity"
-        style={{
-          opacity: isModeToggleFading ? 0 : 1,
-          transitionDuration: `${RECENTER_FADE_MS}ms`,
-          transitionTimingFunction: RECENTER_FADE_EASING,
-        }}
+        style={{ opacity: isModeToggleFading ? 0 : 1, ...RECENTER_FADE_TRANSITION_STYLE }}
       >
         {displayContinuousScroll && (
           <div className="tw:shrink-0 tw:border-b tw:border-border tw:bg-background tw:py-2">

src/components/InterlinearizerLoader.tsx

@@ -15,7 +15,7 @@ import type { PhraseMode } from '../types/phrase-mode';
 import ProjectModals, { type ModalState } from './modals/ProjectModals';
 import ScriptureNavControls from './controls/ScriptureNavControls';
 import { InterlinearNavProvider, useInterlinearNav } from './InterlinearNavContext';
-import { RECENTER_FADE_EASING, RECENTER_FADE_MS } from './recenter-fade';
+import { RECENTER_FADE_TRANSITION_STYLE } from './recenter-fade';
 
 /**
  * Root component for the Interlinearizer WebView. Mounts the {@link InterlinearNavProvider} so the
@@ -349,11 +349,7 @@ function InterlinearizerLoaderInner({
       <div
         data-testid="book-fade-wrapper"
         className="tw:flex tw:flex-col tw:flex-1 tw:min-h-0 tw:transition-opacity"
-        style={{
-          opacity: fadePhase === 'out' ? 0 : 1,
-          transitionDuration: `${RECENTER_FADE_MS}ms`,
-          transitionTimingFunction: RECENTER_FADE_EASING,
-        }}
+        style={{ opacity: fadePhase === 'out' ? 0 : 1, ...RECENTER_FADE_TRANSITION_STYLE }}
       >
         {hasError || showLoading || !book ? (
           <div className="tw:flex tw:flex-col tw:gap-4 tw:p-4">

src/components/SegmentListView.tsx

@@ -6,7 +6,7 @@ import type { Dispatch, SetStateAction } from 'react';
 import type { PhraseMode } from '../types/phrase-mode';
 import MemoizedSegmentView from './SegmentView';
 import useSegmentWindow from '../hooks/useSegmentWindow';
-import { RECENTER_FADE_EASING, RECENTER_FADE_MS } from './recenter-fade';
+import { RECENTER_FADE_TRANSITION_STYLE } from './recenter-fade';
 
 /** Props for {@link SegmentListView}. */
 type SegmentListViewProps = Readonly<{
@@ -168,33 +168,18 @@ export default function SegmentListView({
     onSettled: reportSettled,
   });
 
-  /**
-   * Recenters the segment list on the active verse with the same fade-and-rebuild used for external
-   * navigation. Used by the LocateFixed button and the continuous-scroll mode switch. Always fades
-   * (even when the verse is already on screen) so the active verse is guaranteed to land in view —
-   * a plain `scrollIntoView` of an `aria-current` element silently no-ops when the verse is outside
-   * the render window, leaving the list parked wherever it was.
-   *
-   * `recenterOnActive` is captured via ref so this callback's identity stays stable.
-   */
-  const recenterOnActiveRef = useRef<() => void>(() => undefined);
-  recenterOnActiveRef.current = recenterOnActive;
-  const snapToActive = useCallback(() => {
-    recenterOnActiveRef.current();
-  }, []);
-
   // Recenter the segment list on the active verse when switching between continuous and segment
   // modes. Skips the initial mount: the window is already built centered on the anchor there, so a
   // recenter would needlessly fade. Only an actual mode toggle should fade-and-recenter.
+  // `recenterOnActive` has a stable identity, so listing it as a dep doesn't re-fire this.
   const didMountModeSwitchRef = useRef(false);
   useEffect(() => {
     if (!didMountModeSwitchRef.current) {
       didMountModeSwitchRef.current = true;
       return;
     }
-    snapToActive();
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [continuousScroll]);
+    recenterOnActive();
+  }, [continuousScroll, recenterOnActive]);
 
   return (
     <div
@@ -214,7 +199,7 @@ export default function SegmentListView({
               aria-label="Scroll to active verse"
               className="tw:rounded tw:p-1 tw:text-foreground tw:bg-background tw:hover:bg-muted/50 tw:pointer-events-auto"
               tabIndex={-1}
-              onClick={snapToActive}
+              onClick={recenterOnActive}
               type="button"
             >
               <LocateFixed className="tw:h-4 tw:w-4" />
@@ -223,11 +208,7 @@ export default function SegmentListView({
 
           <div
             className="tw:flex tw:flex-col tw:gap-2 tw:transition-opacity"
-            style={{
-              opacity: isFaded ? 0 : 1,
-              transitionDuration: `${RECENTER_FADE_MS}ms`,
-              transitionTimingFunction: RECENTER_FADE_EASING,
-            }}
+            style={{ opacity: isFaded ? 0 : 1, ...RECENTER_FADE_TRANSITION_STYLE }}
           >
             <div ref={topSentinelRef} aria-hidden="true" className="tw:h-px tw:w-full" />
             {windowSegments.map((seg) => (

src/components/SegmentView.tsx

@@ -204,10 +204,6 @@ export function SegmentView({
     </span>
   );
 
-  /** Ref to the flex token row; used by mouse-leave handling. */
-  // eslint-disable-next-line no-null/no-null
-  const tokenRowRef = useRef<HTMLSpanElement | null>(null);
-
   /**
    * `false` until just after the first paint, then `true`. Gates the link-slot fade transition: the
    * initial visibility state must snap into place before paint (fading in on mount would flash),
@@ -483,7 +479,6 @@ export function SegmentView({
         <PhraseStripProvider value={stripContext}>
           <span
             className="tw:token-row tw:pointer-events-none"
-            ref={tokenRowRef}
             style={{
               paddingTop: `${tokenRowTopPadding}px`,
               paddingLeft: `${stripLeftPadding}px`,

src/components/recenter-fade.ts

@@ -16,3 +16,15 @@ export const RECENTER_FADE_EASING = 'cubic-bezier(0.65, 0, 0.35, 1)';
  * transition and for the `setTimeout` that swaps content at the midpoint, so they fade as one.
  */
 export const RECENTER_FADE_MS = 500;
+
+/**
+ * Inline `style` for any element whose opacity fades on the shared recenter clock. Pairs the
+ * duration and easing so the four fade wrappers (loader curtain, mode-toggle wrapper, segment list,
+ * continuous strip) can't drift onto different timings — set `opacity` alongside this and add the
+ * `tw:transition-opacity` class. Frozen so the shared reference is safe to spread into any style
+ * object.
+ */
+export const RECENTER_FADE_TRANSITION_STYLE = Object.freeze({
+  transitionDuration: `${RECENTER_FADE_MS}ms`,
+  transitionTimingFunction: RECENTER_FADE_EASING,
+});

src/hooks/useSegmentWindow.ts

@@ -153,8 +153,9 @@ export interface UseSegmentWindowResult {
   bottomSentinelRef: (el: HTMLElement | null) => void;
   /**
    * Imperatively recenters the window on the active verse with a fade. Intended for the LocateFixed
-   * button: when the active verse is outside the render window `snapToActive` finds no
-   * `aria-current` element, so the button calls this instead.
+   * button and the continuous-scroll mode switch: always fades and rebuilds, so the active verse is
+   * brought into view even when it sits outside the render window (where a plain `scrollIntoView`
+   * of the `aria-current` element would find nothing and silently no-op). Stable identity.
    */
   recenterOnActive: () => void;
 }
@@ -487,8 +488,8 @@ export default function useSegmentWindow({
   }, [recenterEpoch, snapActiveToTop, scrollContainerRef]);
 
   /**
-   * Rebuilds the window centered on the active verse and fades it into view. Shared by both the
-   * external-navigation effect and the imperative `recenterOnActive` callback.
+   * Rebuilds the window centered on the active verse and fades it into view. Used by the
+   * external-navigation effect and returned directly as the imperative `recenterOnActive`.
    *
    * Reads `anchorIndex` / `total` / `scrRef` from refs so its identity is stable across renders,
    * and owns its timer through `recenterTimeoutRef`: a fresh call supersedes any in-flight fade
@@ -688,16 +689,6 @@ export default function useSegmentWindow({
     [segments, range.start, range.end],
   );
 
-  /**
-   * Imperative recenter for the LocateFixed button (and the continuous-scroll mode switch).
-   * Rebuilds the window centered on the active verse and fades it in, so the verse is brought into
-   * view even when it sits outside the current render window. Always fades — see the parent's
-   * `snapToActive`.
-   */
-  const recenterOnActive = useCallback(() => {
-    triggerRecenter();
-  }, [triggerRecenter]);
-
   // Clear any in-flight recenter fade on unmount so the deferred range/snap/state updates don't run
   // against a torn-down tree.
   useEffect(
@@ -715,6 +706,6 @@ export default function useSegmentWindow({
     displayContinuousScroll,
     topSentinelRef,
     bottomSentinelRef,
-    recenterOnActive,
+    recenterOnActive: triggerRecenter,
   };
 }