Clamp activePhraseIndex, memoize allTokens words as tokenArrays, add coalescing nullish fallback for token chip gloss, extract names prop types for components

Author: alex-rawlings-yyc

src/components/ContinuousView.tsx

@@ -1,5 +1,6 @@
 import type { Book, ScriptureRef, Token } from 'interlinearizer';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { GlossHandlers } from './component-types';
 import MemoizedPhraseBox from './PhraseBox';
 import MemoizedTokenChip from './TokenChip';
 
@@ -13,6 +14,18 @@ function isWordToken(token: Token): token is Token & { type: 'word' } {
   return token.type === 'word';
 }
 
+/**
+ * Clamps `index` to `[0, len - 1]`, returning `0` when `len` is zero or `index` is `undefined`.
+ *
+ * @param index - The raw index to clamp; `undefined` is treated as `0`.
+ * @param len - Length of the target array.
+ * @returns A safe index guaranteed to be within bounds.
+ */
+function clampIndex(index: number | undefined, len: number): number {
+  if (len === 0) return 0;
+  return Math.max(0, Math.min(index ?? 0, len - 1));
+}
+
 /**
  * CSS easing for the strip opacity fade-in/out animation. Uses a sine-like curve for a natural feel
  * at both ends of the transition.
@@ -31,6 +44,17 @@ const STRIP_FADE_MS = 500;
  */
 const PHRASE_WINDOW_HALF = 100;
 
+/** Props for {@link ContinuousView}. */
+type ContinuousViewProps = Readonly<
+  GlossHandlers & {
+    activePhraseIndex: number | undefined;
+    activeVerse: ScriptureRef;
+    book: Book;
+    onFocusPhraseIndexChange: (index: number) => void;
+    onVerseChange: (verse: ScriptureRef) => void;
+  }
+>;
+
 /**
  * Renders all tokens from every segment in the given book as a single flat, horizontally scrollable
  * strip. Arrow buttons advance or retreat the view by one token at a time with smooth scrolling
@@ -66,15 +90,7 @@ export default function ContinuousView({
   onFocusPhraseIndexChange,
   onGlossChange,
   onVerseChange,
-}: Readonly<{
-  activePhraseIndex: number | undefined;
-  activeVerse: ScriptureRef;
-  book: Book;
-  glosses: Record<string, string>;
-  onFocusPhraseIndexChange: (index: number) => void;
-  onGlossChange: (tokenId: string, value: string) => void;
-  onVerseChange: (verse: ScriptureRef) => void;
-}>) {
+}: ContinuousViewProps) {
   const isRtl = document.documentElement.dir === 'rtl';
 
   const allTokens: Token[] = useMemo(
@@ -104,6 +120,15 @@ export default function ContinuousView({
     [allTokens],
   );
 
+  /**
+   * Stable single-token arrays indexed by position in `allTokens`, so `MemoizedPhraseBox` receives
+   * the same array reference across renders and shallow memo comparison holds.
+   */
+  const tokenArrays = useMemo(
+    () => allTokens.map((token) => (isWordToken(token) ? [token] : [])),
+    [allTokens],
+  );
+
   /**
    * Ref mirror of `phraseEntries`. Read inside effects and callbacks that need the latest list
    * without declaring it as a dependency (which would cause spurious re-runs).
@@ -166,7 +191,7 @@ export default function ContinuousView({
   // correctly before the initial-load fade-in fires. Prefer activePhraseIndex (e.g. a focused token
   // carried over from segment view) so there is no flash to the verse-start position on mount.
   const [focusPhraseIndex, setFocusPhraseIndex] = useState<number>(() => {
-    if (activePhraseIndex !== undefined) return activePhraseIndex;
+    if (activePhraseIndex !== undefined) return clampIndex(activePhraseIndex, phraseEntries.length);
 
     const seg = book.segments.find(
       (s) =>
@@ -226,10 +251,11 @@ export default function ContinuousView({
       return;
     }
 
-    jumpTargetRef.current = activePhraseIndex;
+    const clamped = clampIndex(activePhraseIndex, phraseEntriesRef.current.length);
+    jumpTargetRef.current = clamped;
     isExternalJumpInProgressRef.current = true;
     setIsVisible(false);
-    setPendingExternalJumpPhraseIndex(activePhraseIndex);
+    setPendingExternalJumpPhraseIndex(clamped);
   }, [activePhraseIndex]);
 
   // Jump to the first token of the matching segment when the active verse changes.
@@ -466,7 +492,7 @@ export default function ContinuousView({
                   isFocused={isFocusedPhrase}
                   onClick={handlePhraseSelect}
                   onGlossChange={onGlossChange}
-                  tokens={[token]}
+                  tokens={tokenArrays[tokenIndex]}
                 />
               </span>
             );

src/components/Interlinearizer.tsx

@@ -4,6 +4,15 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import ContinuousView from './ContinuousView';
 import MemoizedSegmentView from './SegmentView';
 
+/** Props for {@link Interlinearizer}. */
+type InterlinearizerProps = Readonly<{
+  book: Book;
+  bookSegments: Segment[];
+  continuousScroll: boolean;
+  scrRef: SerializedVerseRef;
+  setScrRef: (newScrRef: SerializedVerseRef) => void;
+}>;
+
 /**
  * Main component for the Interlinearizer. Renders a sticky toolbar and continuous view at the top,
  * followed by segmented views.
@@ -22,13 +31,7 @@ export default function Interlinearizer({
   continuousScroll,
   scrRef,
   setScrRef,
-}: Readonly<{
-  book: Book;
-  bookSegments: Segment[];
-  continuousScroll: boolean;
-  scrRef: SerializedVerseRef;
-  setScrRef: (newScrRef: SerializedVerseRef) => void;
-}>) {
+}: InterlinearizerProps) {
   const [glosses, setGlosses] = useState<Record<string, string>>({});
   const [focusedTokenId, setFocusedTokenId] = useState<string | undefined>(undefined);
 

src/components/PhraseBox.tsx

@@ -1,8 +1,19 @@
 /** @file Shared phrase-box wrapper used around word tokens. */
 import type { Token } from 'interlinearizer';
 import { memo } from 'react';
+import type { GlossHandlers } from './component-types';
 import MemoizedTokenChip from './TokenChip';
 
+/** Props for {@link PhraseBox}. */
+type PhraseBoxProps = Readonly<
+  GlossHandlers & {
+    index?: number;
+    isFocused: boolean;
+    onClick?: (index?: number) => void;
+    tokens: (Token & { type: 'word' })[];
+  }
+>;
+
 /**
  * Wraps one or more tokens in a phrase-level visual container.
  *
@@ -17,21 +28,15 @@ import MemoizedTokenChip from './TokenChip';
  * @param props.tokens - Tokens belonging to this phrase
  * @returns A bordered inline container
  */
+
 export function PhraseBox({
   glosses,
   index,
   isFocused = false,
   onClick,
   onGlossChange,
   tokens,
-}: Readonly<{
-  glosses: Record<string, string>;
-  index?: number;
-  isFocused: boolean;
-  onClick?: (index?: number) => void;
-  onGlossChange: (tokenId: string, value: string) => void;
-  tokens: (Token & { type: 'word' })[];
-}>) {
+}: PhraseBoxProps) {
   const baseClass = isFocused
     ? 'tw:inline-flex tw:items-center tw:rounded tw:border-2 tw:border-white tw:bg-muted/30 tw:px-1 tw:py-0.5'
     : 'tw:inline-flex tw:items-center tw:rounded tw:border tw:border-border/40 tw:bg-muted/20 tw:px-1 tw:py-0.5';
@@ -40,7 +45,7 @@ export function PhraseBox({
       {tokens.map((token) => (
         <MemoizedTokenChip
           key={token.id}
-          gloss={glosses[token.id]}
+          gloss={glosses[token.id] ?? ''}
           onFocus={() => onClick?.(index)}
           onGlossChange={(value) => onGlossChange(token.id, value)}
           token={token}

src/components/SegmentView.tsx

@@ -1,5 +1,6 @@
 import type { ScriptureRef, Segment, Token } from 'interlinearizer';
 import { memo, useCallback, useMemo } from 'react';
+import type { GlossHandlers } from './component-types';
 import MemoizedPhraseBox from './PhraseBox';
 import MemoizedTokenChip from './TokenChip';
 
@@ -23,6 +24,17 @@ function isWordToken(token: Token): token is Token & { type: 'word' } {
  */
 export type SegmentDisplayMode = 'token-chip' | 'baseline-text';
 
+/** Props for {@link SegmentView}. */
+type SegmentViewProps = Readonly<
+  GlossHandlers & {
+    displayMode?: SegmentDisplayMode;
+    focusedTokenId?: string;
+    isActive?: boolean;
+    onSelect: (ref: ScriptureRef, tokenId?: string) => void;
+    segment: Segment;
+  }
+>;
+
 /**
  * Renders a single segment as either inline token chips or plain baseline text.
  *
@@ -50,15 +62,7 @@ export function SegmentView({
   onGlossChange,
   onSelect,
   segment,
-}: Readonly<{
-  displayMode?: SegmentDisplayMode;
-  focusedTokenId?: string;
-  glosses: Record<string, string>;
-  isActive?: boolean;
-  onGlossChange: (tokenId: string, value: string) => void;
-  onSelect: (ref: ScriptureRef, tokenId?: string) => void;
-  segment: Segment;
-}>) {
+}: SegmentViewProps) {
   const { book, chapter, verse } = segment.startRef;
   const ref: ScriptureRef = useMemo(() => ({ book, chapter, verse }), [book, chapter, verse]);
 

src/components/component-types.ts

@@ -0,0 +1,10 @@
+/**
+ * Props shared by components that display and edit token glosses.
+ *
+ * @field glosses - Map from `Token.id` to current gloss text.
+ * @field onGlossChange - Called with the token id and new value when a gloss is edited.
+ */
+export type GlossHandlers = {
+  glosses: Record<string, string>;
+  onGlossChange: (tokenId: string, value: string) => void;
+};