Update package configuration and enhance interlinearizer WebView functionality

- Add Node.js version requirement (>=18) to package.json and package-lock.json.
- Improve interlinearizer WebView by implementing keyboard navigation for JSON view modes, allowing users to switch between modes using arrow keys.
- Refactor related tests to ensure proper functionality of the new keyboard navigation feature.
- Update README to reflect the new Node.js requirement and clarify usage of test data paths.

Author: alex-rawlings-yyc

README.md

@@ -108,7 +108,7 @@ The general file structure for an extension is as follows:
     - `assets/descriptions/description-<locale>.md` contains a brief description of the extension in the language specified by `<locale>`
 - `contributions/` contains JSON files the platform uses to extend data structures for things like menus and settings. The JSON files are referenced from the manifest
 - `public/` contains other static files that are copied into the build folder
-- `test-data/` contains sample interlinear XML (e.g. `Interlinear_en_MAT.xml`) for development and tests
+- `test-data/` contains sample interlinear XML (e.g. `Interlinear_en_MAT.xml`) for development and tests. In tests, resolve paths via `getTestDataPath('Interlinear_en_MAT.xml')` from `src/__tests__/test-helpers` rather than building paths with `..` segments.
 - `.github/` contains files to facilitate integration with GitHub
   - `.github/workflows` contains [GitHub Actions](https://github.com/features/actions) workflows for automating various processes in this repo (e.g. **Test** and **Lint** on push/PR to main, release-prep, hotfix-\*; **Publish** and **Bump Versions** manual dispatch; **CodeQL** for security)
   - `.github/assets/release-body.md` combined with a generated changelog becomes the body of [releases published using GitHub Actions](#publishing)
@@ -119,6 +119,10 @@ The general file structure for an extension is as follows:
 
 ## To install
 
+### Requirements
+
+- **Node.js >= 18** is required. The test suite uses the Web Crypto API (`globalThis.crypto.subtle`) for hashing in `paratext9Converter` tests (e.g. the `sha256HexWebCrypto` path in `src/__tests__/parsers/paratext-9/paratext9Converter.test.ts` when `convertParatext9ToInterlinearization` is called without the `hashSha256Hex` option). Node 18+ provides this API; older versions will cause those tests to fail. The same requirement is enforced in `package.json` via `engines.node` and is used by CI.
+
 ### Install dependencies:
 
 1. Follow the instructions to install [`paranext-core`](https://github.com/paranext/paranext-core#developer-install). We recommend you clone `paranext-core` in the same parent directory in which you cloned this repository so you do not have to [reconfigure paths](#configure-paths-to-paranext-core-repo) to `paranext-core`.

package-lock.json

@@ -6,6 +6,9 @@
   "types": "src/types/interlinearizer.d.ts",
   "author": "SIL Global",
   "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build:web-view": "webpack --config ./webpack/webpack.config.web-view.ts",
     "build:main": "webpack --config ./webpack/webpack.config.main.ts",

package.json

@@ -5,7 +5,8 @@
 import type { WebViewProps } from '@papi/core';
 import type { SerializedVerseRef } from '@sillsdev/scripture';
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
-import type { InterlinearData } from 'paratext-9-types';
+import React from 'react';
+import type { InterlinearData } from 'parsers/paratext-9/paratext-9-types';
 
 /** Stub InterlinearData returned by the mocked parser. Matches shape the WebView displays. */
 const stubInterlinearData: InterlinearData = {
@@ -202,6 +203,21 @@ describe('InterlinearizerWebView', () => {
     expect(screen.getByText(/paratext-9/i)).toBeInTheDocument();
   });
 
+  it('Analyses view shows empty JSON pre when createAnalyses returns undefined', async () => {
+    mockCreateAnalyses.mockReturnValueOnce(undefined);
+
+    const { container } = await renderWebView();
+    fireEvent.click(screen.getByRole('radio', { name: /^analyses$/i }));
+    await waitFor(() => {
+      expect(screen.getByText(/^Analyses \(JSON\):$/)).toBeInTheDocument();
+    });
+
+    const jsonPre = container.querySelector('pre');
+    expect(jsonPre).toBeInTheDocument();
+    expect(jsonPre).toBeEmptyDOMElement();
+    expect(jsonPre).not.toHaveTextContent('undefined');
+  });
+
   it('renders empty JSON pre when jsonToShow is undefined (converter returns undefined)', async () => {
     mockConvert.mockResolvedValueOnce(undefined);
 
@@ -243,4 +259,153 @@ describe('InterlinearizerWebView', () => {
     expect(jsonPre).toBeInTheDocument();
     expect(jsonPre).toBeEmptyDOMElement();
   });
+
+  describe('handleJsonViewModeKeyDown', () => {
+    it('ArrowRight moves to next mode and updates selection', async () => {
+      await renderWebView();
+      const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+      expect(screen.getByText(/^InterlinearData \(JSON\):$/)).toBeInTheDocument();
+
+      await act(async () => {
+        fireEvent.keyDown(radiogroup, { key: 'ArrowRight' });
+      });
+
+      expect(screen.getByText(/^Interlinearization \(JSON\):$/)).toBeInTheDocument();
+      expect(screen.getByRole('radio', { name: /^interlinearization$/i })).toHaveAttribute(
+        'aria-checked',
+        'true',
+      );
+    });
+
+    it('ArrowDown moves to next mode', async () => {
+      await renderWebView();
+      const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+
+      await act(async () => {
+        fireEvent.keyDown(radiogroup, { key: 'ArrowDown' });
+      });
+      expect(screen.getByText(/^Interlinearization \(JSON\):$/)).toBeInTheDocument();
+
+      await act(async () => {
+        fireEvent.keyDown(radiogroup, { key: 'ArrowDown' });
+      });
+      expect(screen.getByText(/^Analyses \(JSON\):$/)).toBeInTheDocument();
+    });
+
+    it('ArrowRight from last mode (Analyses) wraps to first (InterlinearData)', async () => {
+      await renderWebView();
+      const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+      fireEvent.click(screen.getByRole('radio', { name: /^analyses$/i }));
+      expect(screen.getByText(/^Analyses \(JSON\):$/)).toBeInTheDocument();
+
+      await act(async () => {
+        fireEvent.keyDown(radiogroup, { key: 'ArrowRight' });
+      });
+
+      expect(screen.getByText(/^InterlinearData \(JSON\):$/)).toBeInTheDocument();
+      expect(screen.getByRole('radio', { name: /^interlineardata$/i })).toHaveAttribute(
+        'aria-checked',
+        'true',
+      );
+    });
+
+    it('ArrowLeft moves to previous mode', async () => {
+      await renderWebView();
+      const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+      fireEvent.click(screen.getByRole('radio', { name: /^analyses$/i }));
+      expect(screen.getByText(/^Analyses \(JSON\):$/)).toBeInTheDocument();
+
+      await act(async () => {
+        fireEvent.keyDown(radiogroup, { key: 'ArrowLeft' });
+      });
+
+      expect(screen.getByText(/^Interlinearization \(JSON\):$/)).toBeInTheDocument();
+      expect(screen.getByRole('radio', { name: /^interlinearization$/i })).toHaveAttribute(
+        'aria-checked',
+        'true',
+      );
+    });
+
+    it('ArrowUp moves to previous mode', async () => {
+      await renderWebView();
+      const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+      fireEvent.click(screen.getByRole('radio', { name: /^interlinearization$/i }));
+
+      await act(async () => {
+        fireEvent.keyDown(radiogroup, { key: 'ArrowUp' });
+      });
+
+      expect(screen.getByText(/^InterlinearData \(JSON\):$/)).toBeInTheDocument();
+      expect(screen.getByRole('radio', { name: /^interlineardata$/i })).toHaveAttribute(
+        'aria-checked',
+        'true',
+      );
+    });
+
+    it('ArrowLeft from first mode (InterlinearData) wraps to last (Analyses)', async () => {
+      await renderWebView();
+      const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+      expect(screen.getByText(/^InterlinearData \(JSON\):$/)).toBeInTheDocument();
+
+      await act(async () => {
+        fireEvent.keyDown(radiogroup, { key: 'ArrowLeft' });
+      });
+
+      expect(screen.getByText(/^Analyses \(JSON\):$/)).toBeInTheDocument();
+      expect(screen.getByRole('radio', { name: /^analyses$/i })).toHaveAttribute(
+        'aria-checked',
+        'true',
+      );
+    });
+
+    it('non-arrow key does not change mode', async () => {
+      await renderWebView();
+      const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+      expect(screen.getByText(/^InterlinearData \(JSON\):$/)).toBeInTheDocument();
+
+      fireEvent.keyDown(radiogroup, { key: 'a' });
+      fireEvent.keyDown(radiogroup, { key: 'Enter' });
+      expect(screen.getByText(/^InterlinearData \(JSON\):$/)).toBeInTheDocument();
+      expect(screen.getByRole('radio', { name: /^interlineardata$/i })).toHaveAttribute(
+        'aria-checked',
+        'true',
+      );
+    });
+
+    it('moves focus to the newly selected radio on arrow key', async () => {
+      await renderWebView();
+      const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+      const interlinearizationRadio = screen.getByRole('radio', {
+        name: /^interlinearization$/i,
+      });
+
+      await act(async () => {
+        fireEvent.keyDown(radiogroup, { key: 'ArrowRight' });
+      });
+
+      expect(document.activeElement).toBe(interlinearizationRadio);
+    });
+
+    it('does nothing when current view mode is not in JSON_VIEW_MODES (idx === -1)', async () => {
+      const setJsonViewMode = jest.fn();
+      let useStateCallCount = 0;
+      const useStateSpy = jest.spyOn(React, 'useState').mockImplementation(() => {
+        useStateCallCount += 1;
+        return useStateCallCount === 1 ? ['invalid', setJsonViewMode] : [undefined, jest.fn()];
+      });
+
+      try {
+        await renderWebView();
+        const radiogroup = screen.getByRole('radiogroup', { name: /json view mode/i });
+
+        await act(async () => {
+          fireEvent.keyDown(radiogroup, { key: 'ArrowRight' });
+        });
+
+        expect(setJsonViewMode).not.toHaveBeenCalled();
+      } finally {
+        useStateSpy.mockRestore();
+      }
+    });
+  });
 });

src/__tests__/interlinearizer.web-view.test.tsx

@@ -5,11 +5,11 @@
 /// <reference types="jest" />
 
 import { createHash } from 'crypto';
-import type { InterlinearData } from 'paratext-9-types';
 import {
   convertParatext9ToInterlinearization,
   createAnalyses,
 } from 'parsers/paratext-9/paratext9Converter';
+import type { InterlinearData } from 'parsers/paratext-9/paratext-9-types';
 
 /** SHA-256 hex hasher using Node crypto. */
 function nodeSha256Hex(str: string): Promise<string> {

src/__tests__/parsers/paratext-9/paratext9Converter.test.ts

@@ -2,9 +2,9 @@
 /// <reference types="jest" />
 
 import * as fs from 'fs';
-import * as path from 'path';
 
 import { Paratext9Parser } from 'parsers/paratext-9/paratext9Parser';
+import { getTestDataPath } from '../../test-helpers';
 
 describe('Paratext9Parser', () => {
   let parser: Paratext9Parser;
@@ -575,15 +575,7 @@ describe('Paratext9Parser', () => {
     });
 
     it('parses real test-data file without throwing', () => {
-      const xmlPath = path.join(
-        __dirname,
-        '..',
-        '..',
-        '..',
-        '..',
-        'test-data',
-        'Interlinear_en_MAT.xml',
-      );
+      const xmlPath = getTestDataPath('Interlinear_en_MAT.xml');
       const xml = fs.readFileSync(xmlPath, 'utf-8');
       const result = parser.parse(xml);
 

src/__tests__/parsers/paratext-9/paratext9Parser.test.ts

@@ -1,10 +1,23 @@
 /**
  * @file Test helpers used to build type-safe mocks without type assertions. Provides a minimal
- *   ExecutionActivationContext that satisfies @papi/core types.
+ *   ExecutionActivationContext that satisfies @papi/core types, and a stable path resolver for the
+ *   test-data directory.
  */
+import * as path from 'path';
+
 import type { ExecutionActivationContext } from '@papi/core';
 import { UnsubscriberAsyncList } from 'platform-bible-utils';
 
+/**
+ * Resolves a path to a file under the project's test-data directory.
+ *
+ * @param relativePath - Filename or path relative to test-data (e.g. 'Interlinear_en_MAT.xml').
+ * @returns Absolute path to the file under test-data.
+ */
+export function getTestDataPath(relativePath: string): string {
+  return path.resolve(__dirname, '..', '..', 'test-data', relativePath);
+}
+
 /** Minimal execution token-shaped object for tests (structural match for ExecutionToken). */
 const mockExecutionToken: {
   type: 'extension';