Add UI for morphosyntactic analysis of tokens

Author: alex-rawlings-yyc

contributions/localizedStrings.json

@@ -24,6 +24,9 @@
       "%interlinearizer_projectSettings_simplifyPhrasesDescription%": "Hide interactive controls (split, unlink, remove-token) on phrases that are not currently focused, leaving only their style change on hover",
       "%interlinearizer_projectSettings_chapterLabelInVerse%": "Show Chapter in Verse Label",
       "%interlinearizer_projectSettings_chapterLabelInVerseDescription%": "Mark chapter boundaries by labeling the first verse of each chapter as chapter:verse instead of showing an inline chapter header above it",
+      "%interlinearizer_viewOption_showMorphology%": "Show morphology",
+      "%interlinearizer_projectSettings_showMorphology%": "Show Morphology",
+      "%interlinearizer_projectSettings_showMorphologyDescription%": "Display morpheme breakdown and per-morpheme glosses beneath each word token",
       "%interlinearizer_linkButton_crossSegmentDisabledTooltip%": "Cross-segment phrases are not supported. This link button is outside the current segment.",
 
       "%interlinearizer_modal_create_title%": "Create Interlinear Project",

contributions/projectSettings.json

@@ -21,6 +21,11 @@
         "label": "%interlinearizer_projectSettings_chapterLabelInVerse%",
         "description": "%interlinearizer_projectSettings_chapterLabelInVerseDescription%",
         "default": false
+      },
+      "interlinearizer.showMorphology": {
+        "label": "%interlinearizer_projectSettings_showMorphology%",
+        "description": "%interlinearizer_projectSettings_showMorphologyDescription%",
+        "default": false
       }
     }
   }

cspell.json

@@ -18,6 +18,7 @@
     "bara",
     "baselining",
     "BBCCCVVV",
+    "believ",
     "clickability",
     "cullable",
     "deconflict",
@@ -63,6 +64,7 @@
     "struc",
     "Stylesheet",
     "typedefs",
+    "unanalyzed",
     "unhover",
     "unobserves",
     "unphrased",

src/__tests__/components/AnalysisStore.test.tsx

@@ -8,8 +8,12 @@ import type { TextAnalysis, TokenAnalysis, TokenAnalysisLink } from 'interlinear
 import {
   AnalysisStoreProvider,
   useAnalysis,
+  useAnalysisLanguage,
   useGloss,
   useGlossDispatch,
+  useMorphemeBreakdownDispatch,
+  useMorphemeGlossDispatch,
+  useMorphemes,
   usePhraseLinkByIdMap,
   usePhraseLinkForToken,
   usePhraseLinkMap,
@@ -812,3 +816,249 @@ describe('usePhraseGlossDispatch', () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// Morpheme hooks
+// ---------------------------------------------------------------------------
+
+/**
+ * Renders the morpheme forms for a token, used to assert on `useMorphemes`.
+ *
+ * @param props.tokenRef - Token ref to subscribe to.
+ * @returns JSX element with joined morpheme forms.
+ */
+function MorphemeReader({ tokenRef }: Readonly<{ tokenRef: string }>) {
+  const morphemes = useMorphemes(tokenRef);
+  return <span data-testid="morphemes">{morphemes.map((m) => m.form).join(',')}</span>;
+}
+
+/**
+ * Renders the analysis language, used to assert on `useAnalysisLanguage`.
+ *
+ * @returns JSX element with the analysis language string.
+ */
+function LanguageReader() {
+  const lang = useAnalysisLanguage();
+  return <span data-testid="lang">{lang}</span>;
+}
+
+/**
+ * Renders a button that dispatches a morpheme breakdown, used to test
+ * `useMorphemeBreakdownDispatch`.
+ *
+ * @param props.tokenRef - Token ref to write.
+ * @param props.surfaceText - Surface text of the token.
+ * @param props.forms - Morpheme forms to write.
+ * @returns JSX element suitable for passing to `render`.
+ */
+function MorphemeWriter({
+  tokenRef,
+  surfaceText,
+  forms,
+}: Readonly<{ tokenRef: string; surfaceText: string; forms: string[] }>) {
+  const dispatch = useMorphemeBreakdownDispatch();
+  return (
+    <button onClick={() => dispatch(tokenRef, surfaceText, forms)} type="button">
+      break
+    </button>
+  );
+}
+
+/**
+ * Renders a button that dispatches a morpheme gloss, used to test `useMorphemeGlossDispatch`.
+ *
+ * @param props.tokenRef - Token ref to write.
+ * @param props.morphemeId - Morpheme id to gloss.
+ * @param props.value - Gloss value.
+ * @returns JSX element suitable for passing to `render`.
+ */
+function MorphemeGlossWriter({
+  tokenRef,
+  morphemeId,
+  value,
+}: Readonly<{ tokenRef: string; morphemeId: string; value: string }>) {
+  const dispatch = useMorphemeGlossDispatch();
+  return (
+    <button onClick={() => dispatch(tokenRef, morphemeId, value)} type="button">
+      gloss
+    </button>
+  );
+}
+
+/**
+ * Renders a component that calls `useMorphemes` without a provider, used to test the error.
+ *
+ * @returns Nothing — only mounted to trigger the throw.
+ */
+function MorphemesUser() {
+  useMorphemes('tok-1');
+  return undefined;
+}
+
+/**
+ * Renders a component that calls `useAnalysisLanguage` without a provider, used to test the error.
+ *
+ * @returns Nothing — only mounted to trigger the throw.
+ */
+function LanguageUser() {
+  useAnalysisLanguage();
+  return undefined;
+}
+
+/**
+ * Renders a component that calls `useMorphemeBreakdownDispatch` without a provider.
+ *
+ * @returns Nothing — only mounted to trigger the throw.
+ */
+function MorphemeBreakdownDispatchUser() {
+  useMorphemeBreakdownDispatch();
+  return undefined;
+}
+
+/**
+ * Renders a component that calls `useMorphemeGlossDispatch` without a provider.
+ *
+ * @returns Nothing — only mounted to trigger the throw.
+ */
+function MorphemeGlossDispatchUser() {
+  useMorphemeGlossDispatch();
+  return undefined;
+}
+
+describe('useMorphemes', () => {
+  it('returns empty array when no morphemes exist', () => {
+    render(
+      <AnalysisStoreProvider analysisLanguage="und">
+        <MorphemeReader tokenRef="tok-1" />
+      </AnalysisStoreProvider>,
+    );
+    expect(screen.getByTestId('morphemes')).toHaveTextContent('');
+  });
+
+  it('returns morphemes from an approved analysis with morphemes', () => {
+    const ta: TokenAnalysis = {
+      id: 'ta-1',
+      surfaceText: 'unbelievable',
+      morphemes: [
+        { id: 'm-1', form: 'un-', writingSystem: 'und' },
+        { id: 'm-2', form: 'believe', writingSystem: 'und' },
+      ],
+    };
+    const link: TokenAnalysisLink = {
+      analysisId: 'ta-1',
+      status: 'approved',
+      token: { tokenRef: 'tok-1', surfaceText: 'unbelievable' },
+    };
+    const analysis: TextAnalysis = {
+      segmentAnalyses: [],
+      segmentAnalysisLinks: [],
+      tokenAnalyses: [ta],
+      tokenAnalysisLinks: [link],
+      phraseAnalyses: [],
+      phraseAnalysisLinks: [],
+    };
+    render(
+      <AnalysisStoreProvider initialAnalysis={analysis} analysisLanguage="und">
+        <MorphemeReader tokenRef="tok-1" />
+      </AnalysisStoreProvider>,
+    );
+    expect(screen.getByTestId('morphemes')).toHaveTextContent('un-,believe');
+  });
+
+  it('throws when called outside an AnalysisStoreProvider', () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => render(<MorphemesUser />)).toThrow(
+      'useMorphemes must be used inside an AnalysisStoreProvider',
+    );
+  });
+});
+
+describe('useAnalysisLanguage', () => {
+  it('returns the analysis language from the provider', () => {
+    render(
+      <AnalysisStoreProvider analysisLanguage="fr">
+        <LanguageReader />
+      </AnalysisStoreProvider>,
+    );
+    expect(screen.getByTestId('lang')).toHaveTextContent('fr');
+  });
+
+  it('throws when called outside an AnalysisStoreProvider', () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => render(<LanguageUser />)).toThrow(
+      'useAnalysisLanguage must be used inside an AnalysisStoreProvider',
+    );
+  });
+});
+
+describe('useMorphemeBreakdownDispatch', () => {
+  it('writes morphemes and calls onSave', async () => {
+    const onSave = jest.fn();
+    render(
+      <AnalysisStoreProvider analysisLanguage="und" onSave={onSave}>
+        <MorphemeWriter tokenRef="tok-1" surfaceText="cat" forms={['ca', '-t']} />
+        <MorphemeReader tokenRef="tok-1" />
+      </AnalysisStoreProvider>,
+    );
+
+    await userEvent.click(screen.getByRole('button', { name: 'break' }));
+
+    expect(screen.getByTestId('morphemes')).toHaveTextContent('ca,-t');
+    expect(onSave).toHaveBeenCalledTimes(1);
+    const saved: TextAnalysis = onSave.mock.calls[0][0];
+    expect(saved.tokenAnalyses).toHaveLength(1);
+    expect(saved.tokenAnalyses[0].morphemes).toHaveLength(2);
+  });
+
+  it('throws when called outside an AnalysisStoreProvider', () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => render(<MorphemeBreakdownDispatchUser />)).toThrow(
+      'useMorphemeBreakdownDispatch must be used inside an AnalysisStoreProvider',
+    );
+  });
+});
+
+describe('useMorphemeGlossDispatch', () => {
+  it('writes a morpheme gloss and calls onSave', async () => {
+    const onSave = jest.fn();
+    const ta: TokenAnalysis = {
+      id: 'ta-1',
+      surfaceText: 'cat',
+      morphemes: [
+        { id: 'm-1', form: 'ca', writingSystem: 'und' },
+        { id: 'm-2', form: '-t', writingSystem: 'und' },
+      ],
+    };
+    const link: TokenAnalysisLink = {
+      analysisId: 'ta-1',
+      status: 'approved',
+      token: { tokenRef: 'tok-1', surfaceText: 'cat' },
+    };
+    const analysis: TextAnalysis = {
+      segmentAnalyses: [],
+      segmentAnalysisLinks: [],
+      tokenAnalyses: [ta],
+      tokenAnalysisLinks: [link],
+      phraseAnalyses: [],
+      phraseAnalysisLinks: [],
+    };
+    render(
+      <AnalysisStoreProvider initialAnalysis={analysis} analysisLanguage="und" onSave={onSave}>
+        <MorphemeGlossWriter tokenRef="tok-1" morphemeId="m-1" value="prefix" />
+      </AnalysisStoreProvider>,
+    );
+
+    await userEvent.click(screen.getByRole('button', { name: 'gloss' }));
+
+    expect(onSave).toHaveBeenCalledTimes(1);
+    const saved: TextAnalysis = onSave.mock.calls[0][0];
+    expect(saved.tokenAnalyses[0].morphemes?.[0].gloss).toStrictEqual({ und: 'prefix' });
+  });
+
+  it('throws when called outside an AnalysisStoreProvider', () => {
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => render(<MorphemeGlossDispatchUser />)).toThrow(
+      'useMorphemeGlossDispatch must be used inside an AnalysisStoreProvider',
+    );
+  });
+});

src/__tests__/components/ContinuousView.test.tsx

@@ -419,6 +419,7 @@ function requiredProps(
   wordTokenByRef: ReadonlyMap<string, Token & { type: 'word' }>;
   hideInactiveLinkButtons: boolean;
   simplifyPhrases: boolean;
+  showMorphology: boolean;
 } {
   const { tokenSegmentMap, tokenDocOrder, wordTokenByRef } = buildLookups(book);
   return {
@@ -433,6 +434,7 @@ function requiredProps(
     wordTokenByRef,
     hideInactiveLinkButtons: false,
     simplifyPhrases: false,
+    showMorphology: false,
   };
 }
 
@@ -899,6 +901,7 @@ describe('ContinuousView scroll behavior', () => {
           wordTokenByRef={wordTokenByRef}
           hideInactiveLinkButtons={false}
           simplifyPhrases={false}
+          showMorphology={false}
         />
       );
     }
@@ -945,6 +948,7 @@ describe('ContinuousView scroll behavior', () => {
           wordTokenByRef={wordTokenByRef}
           hideInactiveLinkButtons
           simplifyPhrases={false}
+          showMorphology={false}
         />
       );
     }