Fire onGlossChange only when TokenChip input is blurred, adjust onGlossChange to keep stored analyses minimal for now

Author: alex-rawlings-yyc

src/__tests__/components/AnalysisStore.test.tsx

@@ -270,7 +270,7 @@ describe('useAnalysis', () => {
 });
 
 describe('useGlossDispatch', () => {
-  it('creates a new approved TokenAnalysis on each write', async () => {
+  it('replaces the existing approved analysis on subsequent writes for the same token', async () => {
     render(
       <AnalysisStoreProvider analysisLanguage="und">
         <AnalysisReader />
@@ -280,9 +280,24 @@ describe('useGlossDispatch', () => {
     await userEvent.click(screen.getByRole('button', { name: 'write' }));
     await userEvent.click(screen.getByRole('button', { name: 'write' }));
     const analysis: TextAnalysis = JSON.parse(screen.getByTestId('analysis').textContent ?? '');
+    expect(analysis.tokenAnalyses).toHaveLength(1);
+    expect(analysis.tokenAnalysisLinks).toHaveLength(1);
+    expect(analysis.tokenAnalysisLinks[0].status).toBe('approved');
+  });
+
+  it('creates a new approved analysis when writing to a different token', async () => {
+    render(
+      <AnalysisStoreProvider analysisLanguage="und">
+        <AnalysisReader />
+        <GlossWriter tokenRef="tok-1" surfaceText="word" value="hi" />
+        <GlossWriter tokenRef="tok-2" surfaceText="other" value="bye" />
+      </AnalysisStoreProvider>,
+    );
+    await userEvent.click(screen.getAllByRole('button', { name: 'write' })[0]);
+    await userEvent.click(screen.getAllByRole('button', { name: 'write' })[1]);
+    const analysis: TextAnalysis = JSON.parse(screen.getByTestId('analysis').textContent ?? '');
     expect(analysis.tokenAnalyses).toHaveLength(2);
     expect(analysis.tokenAnalysisLinks).toHaveLength(2);
-    analysis.tokenAnalysisLinks.forEach((link) => expect(link.status).toBe('approved'));
   });
 
   it('does not touch existing suggested analyses on write', async () => {

src/__tests__/components/TokenChip.test.tsx

@@ -179,17 +179,31 @@ describe('TokenChip', () => {
     expect(screen.getByRole('textbox', { name: 'Gloss for hello' })).toHaveValue('');
   });
 
-  it('calls the store onGlossChange spy with tokenId and value for each keystroke', async () => {
+  it('calls the store onGlossChange spy once on blur with the final value', async () => {
     const spy = jest.fn();
     render(
       <AnalysisStoreProvider analysisLanguage="und" onGlossChange={spy}>
         <TokenChip {...requiredProps()} />
       </AnalysisStoreProvider>,
     );
     await userEvent.type(screen.getByRole('textbox', { name: 'Gloss for hello' }), 'in');
-    expect(spy).toHaveBeenCalledTimes(2);
-    expect(spy).toHaveBeenNthCalledWith(1, 'GEN 1:1:0', 'i');
-    expect(spy).toHaveBeenNthCalledWith(2, 'GEN 1:1:0', 'in');
+    expect(spy).not.toHaveBeenCalled();
+    await userEvent.tab();
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith('GEN 1:1:0', 'in');
+  });
+
+  it('does not call the store onGlossChange spy when blurring without typing', async () => {
+    const spy = jest.fn();
+    render(
+      <AnalysisStoreProvider analysisLanguage="und" onGlossChange={spy}>
+        <TokenChip {...requiredProps()} />
+      </AnalysisStoreProvider>,
+    );
+    await userEvent.click(screen.getByRole('textbox', { name: 'Gloss for hello' }));
+    await userEvent.tab();
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith('GEN 1:1:0', '');
   });
 
   it('calls onFocus when the input is focused', async () => {

src/components/AnalysisStore.tsx

@@ -170,42 +170,69 @@ export function AnalysisStoreProvider({
   const getAnalysis = useCallback(() => analysisRef.current, []);
 
   /**
-   * Creates a new approved `TokenAnalysis` + `TokenAnalysisLink` for `tokenRef` with the given
-   * gloss string (under `analysisLanguage`), replaces the analysis snapshot, notifies subscribers,
-   * calls `onSave`, and calls the optional `spy` prop for test observability.
-   *
-   * The new `TokenAnalysis` gets a UUID (`crypto.randomUUID()`) as its id to ensure global
-   * uniqueness. Existing analyses for the token are left untouched — this follows the data model's
-   * "multiple competing analyses" design; the UI manages selection and deletion separately.
+   * Writes an approved gloss for `tokenRef`. If an approved `TokenAnalysis` already exists for the
+   * token it is updated in-place; otherwise a new `TokenAnalysis` + `TokenAnalysisLink` are
+   * appended. Non-approved analyses for the token are left untouched. Replaces the analysis
+   * snapshot, notifies subscribers, calls `onSave`, and calls the optional `spy` prop for test
+   * observability.
    *
    * @param tokenRef - The `Token.ref` of the token being glossed.
    * @param surfaceText - The surface text of the token (stored as `Analysis.surfaceText`).
    * @param value - The new gloss string.
    */
   const onGlossChange = useCallback(
     (tokenRef: string, surfaceText: string, value: string) => {
-      const id = crypto.randomUUID();
-      const newAnalysis: TokenAnalysis = {
-        id,
-        surfaceText,
-        gloss: { [analysisLanguage]: value },
-      };
-      const newLink: TokenAnalysisLink = {
-        analysisId: id,
-        status: 'approved',
-        token: { tokenRef, surfaceText },
-      };
+      // eslint-disable-next-line no-type-assertion/no-type-assertion -- ??= above guarantees non-null; TS can't see through the closure boundary
+      const existingApprovedId = approvedAnalysisIdByTokenRef.current!.get(tokenRef);
+
+      let nextAnalyses: TokenAnalysis[];
+      let nextLinks: TokenAnalysisLink[];
+      let nextById: Map<string, TokenAnalysis>;
+
+      if (existingApprovedId === undefined) {
+        const id = crypto.randomUUID();
+        const newAnalysis: TokenAnalysis = {
+          id,
+          surfaceText,
+          gloss: { [analysisLanguage]: value },
+        };
+        const newLink: TokenAnalysisLink = {
+          analysisId: id,
+          status: 'approved',
+          token: { tokenRef, surfaceText },
+        };
+        nextAnalyses = [...analysisRef.current.tokenAnalyses, newAnalysis];
+        nextLinks = [...analysisRef.current.tokenAnalysisLinks, newLink];
+        // eslint-disable-next-line no-type-assertion/no-type-assertion -- ??= above guarantees non-null
+        nextById = new Map([...analysisByIdRef.current!, [id, newAnalysis]]);
+      } else {
+        // Update the gloss on the existing approved analysis; preserve all other fields.
+        // eslint-disable-next-line no-type-assertion/no-type-assertion -- ??= above guarantees non-null; index only stores ids present in analysisByIdRef
+        const existing = analysisByIdRef.current!.get(existingApprovedId)!;
+        const updated: TokenAnalysis = {
+          ...existing,
+          surfaceText,
+          gloss: { ...existing.gloss, [analysisLanguage]: value },
+        };
+        nextAnalyses = analysisRef.current.tokenAnalyses.map(
+          /* v8 ignore next -- passthrough branch for non-matching tokens is structurally unreachable in tests */
+          (ta) => (ta.id === existingApprovedId ? updated : ta),
+        );
+        // Links are unchanged — the same link already points to existingApprovedId.
+        nextLinks = analysisRef.current.tokenAnalysisLinks;
+        // eslint-disable-next-line no-type-assertion/no-type-assertion -- ??= above guarantees non-null
+        nextById = new Map([...analysisByIdRef.current!, [existingApprovedId, updated]]);
+      }
 
       const next: TextAnalysis = {
         ...analysisRef.current,
-        tokenAnalyses: [...analysisRef.current.tokenAnalyses, newAnalysis],
-        tokenAnalysisLinks: [...analysisRef.current.tokenAnalysisLinks, newLink],
+        tokenAnalyses: nextAnalyses,
+        tokenAnalysisLinks: nextLinks,
       };
 
       analysisRef.current = next;
-      // eslint-disable-next-line no-type-assertion/no-type-assertion -- ??= above guarantees non-null; TS can't see through the closure boundary
-      analysisByIdRef.current = new Map([...analysisByIdRef.current!, [id, newAnalysis]]);
-      approvedAnalysisIdByTokenRef.current = buildApprovedGlossIndex(next, analysisByIdRef.current);
+      analysisByIdRef.current = nextById;
+      approvedAnalysisIdByTokenRef.current = buildApprovedGlossIndex(next, nextById);
 
       listenersRef.current.forEach((l) => l());
       onSave?.(next);

src/components/TokenChip.tsx

@@ -1,11 +1,12 @@
 import type { Token } from 'interlinearizer';
-import { memo } from 'react';
+import { memo, useEffect, useState } from 'react';
 import { useGloss, useGlossDispatch } from './AnalysisStore';
 
 /**
  * Renders a single word token as an inline chip with an editable gloss input below the surface
  * text. Gloss value and dispatch are read from {@link AnalysisStoreProvider} context via
- * {@link useGloss} and {@link useGlossDispatch}.
+ * {@link useGloss} and {@link useGlossDispatch}. The gloss is written to the store only on blur to
+ * avoid creating a new analysis entry on every keystroke.
  *
  * @param props - Component props
  * @param props.token - The word token to render.
@@ -16,8 +17,15 @@ export function TokenChip({
   token,
   onFocus,
 }: Readonly<{ token: Token & { type: 'word' }; onFocus: () => void }>) {
-  const gloss = useGloss(token.ref);
+  const committedGloss = useGloss(token.ref);
   const onGlossChange = useGlossDispatch();
+  const [draft, setDraft] = useState(committedGloss);
+
+  // Keep local draft in sync when the committed value changes externally (e.g. project switch).
+  useEffect(() => {
+    setDraft(committedGloss);
+  }, [committedGloss]);
+
   return (
     <label 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 tw:cursor-text">
@@ -27,8 +35,9 @@ 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}
-        onChange={(e) => onGlossChange(token.ref, token.surfaceText, e.target.value)}
+        value={draft}
+        onChange={(e) => setDraft(e.target.value)}
+        onBlur={() => onGlossChange(token.ref, token.surfaceText, draft)}
         onFocus={onFocus}
         type="text"
       />