Memoize ref, handleTokenClick, and tokenArrays; introduce TokenChip type guard to ensure that input always has a handler; update docs

Author: alex-rawlings-yyc

src/__tests__/components/PhraseBox.test.tsx

@@ -33,32 +33,32 @@ jest.mock('../../components/TokenChip', () => ({
 }));
 
 /** Pre-built test token */
-const TEST_TOKEN: Token = {
+const TEST_TOKEN = {
   id: 'token-1',
   surfaceText: 'Hello',
   writingSystem: 'en',
   type: 'word',
   charStart: 0,
   charEnd: 5,
-};
+} satisfies Token;
 
 /** Second test token */
-const TEST_TOKEN_2: Token = {
+const TEST_TOKEN_2 = {
   id: 'token-2',
   surfaceText: 'World',
   writingSystem: 'en',
   type: 'word',
   charStart: 6,
   charEnd: 11,
-};
+} satisfies Token;
 
 /** Shared props shape used by both helper functions. */
 type PhraseBoxTestProps = {
   glosses: Record<string, string>;
   isFocused: boolean;
   onClick?: (index?: number) => void;
   onGlossChange: (tokenId: string, value: string) => void;
-  tokens: Token[];
+  tokens: (Token & { type: 'word' })[];
 };
 
 /**

src/__tests__/components/SegmentView.test.tsx

@@ -11,22 +11,24 @@ jest.mock('../../components/PhraseBox', () => ({
   __esModule: true,
   default: ({
     glosses,
+    index,
     isFocused = false,
     onClick,
     onGlossChange,
     tokens,
   }: {
     glosses: Record<string, string>;
+    index?: number;
     isFocused: boolean;
-    onClick?: () => void;
+    onClick?: (index?: number) => void;
     onGlossChange: (tokenId: string, value: string) => void;
     tokens: Token[];
   }) => (
     <span data-focus-state={isFocused ? 'focused' : 'default'}>
       {tokens.map((t) => (
         <span key={t.id}>
           {onClick ? (
-            <button onClick={onClick} type="button">
+            <button onClick={() => onClick(index)} type="button">
               {t.surfaceText}
             </button>
           ) : (

src/__tests__/components/TokenChip.test.tsx

@@ -7,27 +7,42 @@ import userEvent from '@testing-library/user-event';
 import type { Token } from 'interlinearizer';
 import { TokenChip } from '../../components/TokenChip';
 
-const WORD_TOKEN: Token = {
+const WORD_TOKEN = {
   id: 'GEN 1:1:0',
   surfaceText: 'hello',
   writingSystem: 'en',
   type: 'word',
   charStart: 0,
   charEnd: 5,
-};
+} satisfies Token;
 
-const PUNCT_TOKEN: Token = {
+const PUNCT_TOKEN = {
   id: 'GEN 1:1:5',
   surfaceText: '.',
   writingSystem: 'en',
   type: 'punctuation',
   charStart: 5,
   charEnd: 6,
-};
+} satisfies Token;
+
+/**
+ * Minimal required props for a word-token `TokenChip`. Spread into render calls so tests only need
+ * to override what they actually care about.
+ *
+ * @returns An object with all required word-token props set to no-op stubs.
+ */
+function requiredWordProps() {
+  return {
+    token: WORD_TOKEN,
+    gloss: '',
+    onFocus: jest.fn(),
+    onGlossChange: jest.fn(),
+  } as const;
+}
 
 describe('TokenChip', () => {
   it('renders the surface text for a word token', () => {
-    render(<TokenChip token={WORD_TOKEN} />);
+    render(<TokenChip {...requiredWordProps()} />);
     expect(screen.getByText('hello')).toBeInTheDocument();
   });
 
@@ -37,7 +52,7 @@ describe('TokenChip', () => {
   });
 
   it('applies a border class to word tokens', () => {
-    render(<TokenChip token={WORD_TOKEN} />);
+    render(<TokenChip {...requiredWordProps()} />);
     // The outer container holds the border; the inner span is just the surface text
     const outer = screen.getByText('hello').closest('span')?.parentElement;
     expect(outer?.className).toContain('tw:border');
@@ -50,14 +65,14 @@ describe('TokenChip', () => {
   });
 
   it('renders word and punctuation tokens as inline spans', () => {
-    const { container: wc } = render(<TokenChip token={WORD_TOKEN} />);
+    const { container: wc } = render(<TokenChip {...requiredWordProps()} />);
     const { container: pc } = render(<TokenChip token={PUNCT_TOKEN} />);
     expect(wc.querySelector('span')).toBeInTheDocument();
     expect(pc.querySelector('span')).toBeInTheDocument();
   });
 
   it('renders a gloss input for word tokens', () => {
-    render(<TokenChip token={WORD_TOKEN} />);
+    render(<TokenChip {...requiredWordProps()} />);
     expect(screen.getByRole('textbox', { name: 'Gloss for hello' })).toBeInTheDocument();
   });
 
@@ -67,41 +82,28 @@ describe('TokenChip', () => {
   });
 
   it('shows the current gloss value in the input', () => {
-    render(<TokenChip token={WORD_TOKEN} gloss="in" />);
+    render(<TokenChip {...requiredWordProps()} gloss="in" />);
     expect(screen.getByRole('textbox', { name: 'Gloss for hello' })).toHaveValue('in');
   });
 
-  it('shows an empty input when no gloss is provided', () => {
-    render(<TokenChip token={WORD_TOKEN} />);
+  it('shows an empty string in the input when gloss is empty', () => {
+    render(<TokenChip {...requiredWordProps()} gloss="" />);
     expect(screen.getByRole('textbox', { name: 'Gloss for hello' })).toHaveValue('');
   });
 
   it('calls onGlossChange for each keystroke', async () => {
     const handleChange = jest.fn();
-    render(<TokenChip token={WORD_TOKEN} onGlossChange={handleChange} />);
+    render(<TokenChip {...requiredWordProps()} onGlossChange={handleChange} />);
     await userEvent.type(screen.getByRole('textbox', { name: 'Gloss for hello' }), 'in');
     expect(handleChange).toHaveBeenCalledTimes(2);
     expect(handleChange).toHaveBeenNthCalledWith(1, 'i');
     expect(handleChange).toHaveBeenNthCalledWith(2, 'n');
   });
 
-  it('does not throw when onGlossChange is omitted and the user types', async () => {
-    render(<TokenChip token={WORD_TOKEN} />);
-    await userEvent.type(screen.getByRole('textbox', { name: 'Gloss for hello' }), 'in');
-    // No assertion needed — test passes if no error is thrown
-  });
-
   it('calls onFocus when the input is focused', async () => {
     const handleFocus = jest.fn();
-    render(<TokenChip token={WORD_TOKEN} onFocus={handleFocus} />);
+    render(<TokenChip {...requiredWordProps()} onFocus={handleFocus} />);
     await userEvent.click(screen.getByRole('textbox', { name: 'Gloss for hello' }));
     expect(handleFocus).toHaveBeenCalledTimes(1);
   });
-
-  it('does not throw when onFocus is omitted', async () => {
-    render(<TokenChip token={WORD_TOKEN} />);
-    await userEvent.click(screen.getByRole('textbox', { name: 'Gloss for hello' }));
-    await userEvent.tab();
-    // No assertion needed — test passes if no error is thrown
-  });
 });

src/components/ContinuousView.tsx

@@ -3,8 +3,22 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import MemoizedPhraseBox from './PhraseBox';
 import MemoizedTokenChip from './TokenChip';
 
-/** CSS easing for the strip opacity fade-in/out animation. */
+/**
+ * Narrows a `Token` to a word token.
+ *
+ * @param token - The token to test.
+ * @returns `true` when `token.type === 'word'`.
+ */
+function isWordToken(token: Token): token is Token & { type: 'word' } {
+  return token.type === 'word';
+}
+
+/**
+ * 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.
+ */
 const STRIP_FADE_EASING = 'cubic-bezier(0.65, 0, 0.35, 1)';
+
 /**
  * Duration of the strip fade animation in milliseconds. Must match the `setTimeout` in the
  * pending-jump effect.
@@ -435,7 +449,7 @@ export default function ContinuousView({
         >
           {allTokens.slice(windowStartTokenIndex, windowEndTokenIndex).map((token, i) => {
             const tokenIndex = windowStartTokenIndex + i;
-            if (token.type !== 'word') return <MemoizedTokenChip key={token.id} token={token} />;
+            if (!isWordToken(token)) return <MemoizedTokenChip key={token.id} token={token} />;
 
             const phraseIndex = phraseIndexByTokenIndex.get(tokenIndex);
             const isFocusedPhrase = phraseIndex !== undefined && phraseIndex === focusPhraseIndex;

src/components/InterlinearizerLoader.tsx

@@ -19,6 +19,8 @@ const STRING_KEYS = ['%interlinearizer_continuousScrollToggle%'] as const;
  * @param props.projectId - PAPI project ID passed from the host
  * @param props.useWebViewScrollGroupScrRef - Hook that exposes the shared scroll-group scripture
  *   reference and its setter
+ * @returns The toolbar and either an error/loading state or the fully rendered
+ *   {@link Interlinearizer}
  */
 export default function InterlinearizerLoader({
   projectId,

src/components/PhraseBox.tsx

@@ -30,7 +30,7 @@ export function PhraseBox({
   isFocused: boolean;
   onClick?: (index?: number) => void;
   onGlossChange: (tokenId: string, value: string) => void;
-  tokens: Token[];
+  tokens: (Token & { type: 'word' })[];
 }>) {
   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'
@@ -75,5 +75,6 @@ export function PhraseBox({
   );
 }
 
+/** Memoized version of {@link PhraseBox}; use this for all render-stable phrase lists. */
 const MemoizedPhraseBox = memo(PhraseBox);
 export default MemoizedPhraseBox;

src/components/SegmentView.tsx

@@ -1,8 +1,18 @@
-import type { ScriptureRef, Segment } from 'interlinearizer';
-import { memo } from 'react';
+import type { ScriptureRef, Segment, Token } from 'interlinearizer';
+import { memo, useCallback, useMemo } from 'react';
 import MemoizedPhraseBox from './PhraseBox';
 import MemoizedTokenChip from './TokenChip';
 
+/**
+ * Narrows a `Token` to a word token.
+ *
+ * @param token - The token to test.
+ * @returns `true` when `token.type === 'word'`.
+ */
+function isWordToken(token: Token): token is Token & { type: 'word' } {
+  return token.type === 'word';
+}
+
 /**
  * The two display modes for {@link SegmentView}.
  *
@@ -50,14 +60,29 @@ export function SegmentView({
   segment: Segment;
 }>) {
   const { book, chapter, verse } = segment.startRef;
-  const ref: ScriptureRef = { book, chapter, verse };
+  const ref: ScriptureRef = useMemo(() => ({ book, chapter, verse }), [book, chapter, verse]);
+
   /**
-   * Forwards a token-chip click to the parent as a scripture reference + token id.
+   * Forwards a token-chip click (identified by its index in `segment.tokens`) to the parent as a
+   * scripture reference + token id. Stable across renders so `MemoizedPhraseBox` can memoize.
    *
-   * @param tokenId - The id of the clicked token.
-   * @throws Propagates any error thrown by `onSelect`.
+   * @param index - Index of the clicked token within `segment.tokens`.
    */
-  const handleTokenClick = (tokenId: string) => onSelect(ref, tokenId);
+  const handleTokenClick = useCallback(
+    (index?: number) => {
+      if (index !== undefined) onSelect(ref, segment.tokens[index].id);
+    },
+    [onSelect, ref, segment.tokens],
+  );
+
+  /**
+   * Stable single-token arrays for word tokens keyed by position, so `MemoizedPhraseBox` receives
+   * the same reference across renders.
+   */
+  const tokenArrays = useMemo(
+    () => segment.tokens.map((token) => (isWordToken(token) ? [token] : [])),
+    [segment.tokens],
+  );
 
   const sharedClassName = isActive
     ? 'tw:w-full tw:rounded tw:border tw:border-border tw:bg-muted/50 tw:p-2'
@@ -92,15 +117,16 @@ export function SegmentView({
     >
       {verseLabel}
       <span className="tw:flex tw:flex-wrap tw:gap-1">
-        {segment.tokens.map((token) =>
+        {segment.tokens.map((token, index) =>
           token.type === 'word' ? (
             <MemoizedPhraseBox
               key={token.id}
               glosses={glosses}
+              index={index}
               isFocused={focusedTokenId === token.id}
-              onClick={() => handleTokenClick(token.id)}
+              onClick={handleTokenClick}
               onGlossChange={onGlossChange}
-              tokens={[token]}
+              tokens={tokenArrays[index]}
             />
           ) : (
             <MemoizedTokenChip key={token.id} token={token} />
@@ -111,5 +137,6 @@ export function SegmentView({
   );
 }
 
+/** Memoized version of {@link SegmentView}; use this for all render-stable segment lists. */
 const MemoizedSegmentView = memo(SegmentView);
 export default MemoizedSegmentView;

src/components/TokenChip.tsx

@@ -1,30 +1,38 @@
 import type { Token } from 'interlinearizer';
 import { memo } from 'react';
 
+/** Props for a word token chip; requires gloss editing callbacks. */
+type WordProps = Readonly<{
+  token: Token & { type: 'word' };
+  gloss: string;
+  onFocus: () => void;
+  onGlossChange: (value: string) => void;
+}>;
+
+/** Props for a punctuation token chip; editing props are excluded via `never`. */
+type PunctProps = Readonly<{
+  token: Token;
+  gloss?: never;
+  onFocus?: never;
+  onGlossChange?: never;
+}>;
+
 /**
  * Renders a single token as an inline chip. Word tokens get a bordered box with an editable gloss
- * input below; non-word tokens (e.g. punctuation) are rendered as muted inline text with no gloss.
+ * input below; punctuation tokens are rendered as muted inline text with no gloss.
+ *
+ * Props are a discriminated union on `token.type`: word tokens require `onGlossChange` and accept
+ * `gloss` and `onFocus`; punctuation tokens accept none of these.
  *
  * @param props - Component props
- * @param props.gloss - Current gloss text for this token (English). Absent when no gloss has been
- *   set.
- * @param props.onFocus - Called when the gloss input receives focus; used by the parent to track
- *   which token is active.
- * @param props.onGlossChange - Called with the new gloss value when the user edits the input.
- * @param props.token - The token to render
+ * @param props.token - The token to render; its `type` field discriminates the union.
+ * @param props.gloss - (word only) Current gloss text. Absent when no gloss has been set.
+ * @param props.onFocus - (word only) Called when the gloss input receives focus.
+ * @param props.onGlossChange - (word only) Called with the new gloss value when the user edits the
+ *   input.
  * @returns A styled inline block
  */
-export function TokenChip({
-  gloss,
-  onFocus,
-  onGlossChange,
-  token,
-}: Readonly<{
-  gloss?: string;
-  onFocus?: () => void;
-  onGlossChange?: (value: string) => void;
-  token: Token;
-}>) {
+export function TokenChip({ gloss, onFocus, onGlossChange, token }: WordProps | PunctProps) {
   return token.type === 'word' ? (
     <span className="tw:inline-flex tw:shrink-0 tw:flex-col tw:items-center tw:rounded tw:border tw:border-border tw:bg-muted tw:px-1.5 tw:py-0.5">
       <span className="tw:whitespace-nowrap tw:font-mono tw:text-sm tw:text-foreground">
@@ -34,7 +42,7 @@ export function TokenChip({
         aria-label={`Gloss for ${token.surfaceText}`}
         className="tw:mt-0.5 tw:rounded tw:border tw:border-border tw:bg-background tw:px-1 tw:text-center tw:text-sm tw:text-foreground tw:outline-none tw:focus:border-ring tw:focus:ring-1 tw:focus:ring-ring"
         style={{ fieldSizing: 'content', minWidth: '5ch' }}
-        value={gloss ?? ''}
+        value={gloss}
         onChange={(e) => onGlossChange?.(e.target.value)}
         onFocus={onFocus}
         type="text"
@@ -47,5 +55,6 @@ export function TokenChip({
   );
 }
 
+/** Memoized version of {@link TokenChip}; use this for all render-stable token lists. */
 const MemoizedTokenChip = memo(TokenChip);
 export default MemoizedTokenChip;