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

jest.config.ts

@@ -30,6 +30,7 @@ const config: Config = {
     '!src/**/__tests__/**',
     '!src/**/*.test.{ts,tsx}',
     '!src/**/*.spec.{ts,tsx}',
+    '!src/components/component-types.ts',
   ],
 
   /** Directory for coverage output. */

src/__tests__/components/ContinuousView.test.tsx

@@ -395,6 +395,12 @@ describe('ContinuousView rendering', () => {
     expect(screen.getByText('.')).toBeInTheDocument();
   });
 
+  it('renders without crashing when book has no word tokens and activePhraseIndex is set', () => {
+    render(<ContinuousView book={makeWordFreeBook()} {...requiredProps()} activePhraseIndex={0} />);
+
+    expect(screen.getByText('.')).toBeInTheDocument();
+  });
+
   it('clicking an out-of-focus phrase box brings it into focus', async () => {
     render(<ContinuousView book={makeBook()} {...requiredProps()} />);
 

src/__tests__/components/SegmentView.test.tsx

@@ -95,13 +95,19 @@ const PUNCT_SEGMENT: Segment = {
  * @returns An object containing all required SegmentView props set to no-op stubs.
  */
 function requiredProps(): {
+  displayMode: 'token-chip';
+  focusedTokenId: string | undefined;
   glosses: Record<string, string>;
+  isActive: boolean;
   onGlossChange: (tokenId: string, value: string) => void;
   onSelect: (ref: ScriptureRef, tokenId?: string) => void;
   segment: Segment;
 } {
   return {
+    displayMode: 'token-chip',
+    focusedTokenId: undefined,
     glosses: {},
+    isActive: false,
     onGlossChange: jest.fn(),
     onSelect: jest.fn(),
     segment: WORD_SEGMENT,

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.
+ *
+ * @param index - The raw index to clamp.
+ * @param len - Length of the target array.
+ * @returns A safe index guaranteed to be within bounds.
+ */
+function clampIndex(index: number, len: number): number {
+  if (len === 0) return 0;
+  return Math.max(0, Math.min(index, 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,11 +24,22 @@ 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 | undefined;
+    isActive: boolean;
+    onSelect: (ref: ScriptureRef, tokenId?: string) => void;
+    segment: Segment;
+  }
+>;
+
 /**
  * Renders a single segment as either inline token chips or plain baseline text.
  *
  * @param props - Component props
- * @param props.displayMode - Controls how segment content is rendered; defaults to `'token-chip'`
+ * @param props.displayMode - Controls how segment content is rendered
  * @param props.focusedTokenId - When set, the matching word token's `PhraseBox` is rendered in the
  *   focused state; only meaningful in `token-chip` mode.
  * @param props.glosses - Map from `Token.id` to current English gloss text for tokens in this
@@ -43,22 +55,14 @@ export type SegmentDisplayMode = 'token-chip' | 'baseline-text';
  *   segment content
  */
 export function SegmentView({
-  displayMode = 'token-chip',
+  displayMode,
   focusedTokenId,
   glosses,
   isActive,
   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;
+};