Memoize Modal handler callbacks, add targetProjectId to modals where relevant to prevent silent deletion, docstring audit

Author: alex-rawlings-yyc

src/__tests__/components/ProjectMetadataModal.test.tsx

@@ -40,6 +40,11 @@ const testProps = {
   onProjectDeleted: jest.fn(),
 };
 
+const testPropsWithTarget = {
+  ...testProps,
+  targetProjectId: 'target-project-id',
+};
+
 describe('ProjectMetadataModal', () => {
   beforeEach(() => {
     jest.mocked(useLocalizedStrings).mockReturnValue([LOCALIZED, false]);
@@ -97,6 +102,24 @@ describe('ProjectMetadataModal', () => {
         'New Name',
         undefined,
         ['en'],
+        undefined,
+      ),
+    );
+  });
+
+  it('passes targetProjectId to sendCommand when the project has a target project', async () => {
+    render(<ProjectMetadataModal {...testPropsWithTarget} />);
+
+    await userEvent.click(screen.getByRole('button', { name: /^save$/i }));
+
+    await waitFor(() =>
+      expect(mockSendCommand).toHaveBeenCalledWith(
+        'interlinearizer.updateProjectMetadata',
+        'il-project-uuid',
+        undefined,
+        undefined,
+        ['en'],
+        'target-project-id',
       ),
     );
   });
@@ -152,6 +175,7 @@ describe('ProjectMetadataModal', () => {
         undefined,
         'New Desc',
         ['en'],
+        undefined,
       ),
     );
   });
@@ -171,6 +195,7 @@ describe('ProjectMetadataModal', () => {
         undefined,
         'Replaced',
         ['en'],
+        undefined,
       ),
     );
   });
@@ -189,6 +214,7 @@ describe('ProjectMetadataModal', () => {
         undefined,
         undefined,
         ['en'],
+        undefined,
       ),
     );
   });
@@ -257,6 +283,7 @@ describe('ProjectMetadataModal', () => {
         undefined,
         undefined,
         ['fr'],
+        undefined,
       ),
     );
   });

src/__tests__/components/SelectInterlinearProjectModal.test.tsx

@@ -167,6 +167,14 @@ describe('SelectInterlinearProjectModal', () => {
     expect(screen.getAllByRole('listitem')).toHaveLength(1);
   });
 
+  it('silently drops entries with a non-string targetProjectId field', async () => {
+    const badTarget = { ...STUB_PROJECT, targetProjectId: 99 };
+    mockSendCommand.mockResolvedValue(JSON.stringify([badTarget, STUB_PROJECT_2]));
+    render(<SelectInterlinearProjectModal {...defaultProps} />);
+    await waitFor(() => expect(screen.getByText('French glosses')).toBeInTheDocument());
+    expect(screen.getAllByRole('listitem')).toHaveLength(1);
+  });
+
   it('shows the empty-state message when getProjectsForSource returns a non-array', async () => {
     mockSendCommand.mockResolvedValue(JSON.stringify({ not: 'an array' }));
     render(<SelectInterlinearProjectModal {...defaultProps} />);

src/components/Interlinearizer.tsx

@@ -5,16 +5,17 @@ import ContinuousView from './ContinuousView';
 import MemoizedSegmentView from './SegmentView';
 
 /**
- * Main component for the Interlinearizer. Renders a sticky toolbar and continuous view at the top,
- * followed by segmented views.
+ * Main content area for the Interlinearizer. Renders an optional {@link ContinuousView} strip at the
+ * top followed by a scrollable list of {@link MemoizedSegmentView}s for the current chapter.
  *
  * @param props - Component props
  * @param props.book - Book data used by the continuous view
  * @param props.bookSegments - Segments to render as individual verse views
  * @param props.continuousScroll - Whether the continuous scroll view is shown
  * @param props.scrRef - Current scripture reference
  * @param props.setScrRef - Callback to update the scripture reference
- * @returns The continuous-view header (when enabled) above the segment list for the active chapter.
+ * @returns The continuous-view strip (when enabled) above the scrollable segment list for the
+ *   active chapter.
  */
 export default function Interlinearizer({
   book,

src/components/InterlinearizerLoader.tsx

@@ -16,7 +16,7 @@ import type { ActiveProjectState } from './SelectInterlinearProjectModal';
 const STRING_KEYS: `%${string}%`[] = ['%interlinearizer_continuousScrollToggle%'];
 
 /**
- * Root component for loading the Interlinearizer. Loads book data and settings, manages modal state
+ * Root component for the Interlinearizer WebView. Loads book data and settings, manages modal state
  * for project creation/selection/metadata, then renders error and loading states or delegates to
  * {@link Interlinearizer} when data is ready.
  *
@@ -61,8 +61,8 @@ export default function InterlinearizerLoader({
 
   /**
    * Persisted snapshot of the active interlinear project — kept in WebView state so it survives tab
-   * restores. Updated after creation and when the user selects an existing project from the
-   * picker.
+   * restores. The setter lives in {@link ProjectModals}, which writes to the same `'activeProject'`
+   * key; this component reads the value to decide which menu items to show.
    */
   const [activeProject] = useWebViewState<ActiveProjectState | undefined>(
     'activeProject',
@@ -100,6 +100,12 @@ export default function InterlinearizerLoader({
     { topMenu: undefined, includeDefaults: true, contextMenu: undefined },
   );
 
+  /**
+   * Top-menu descriptor passed to {@link TabToolbar}. Identical to
+   * `webViewMenuPossiblyError.topMenu` except that the `interlinearizer.openProjectInfoModal` item
+   * is filtered out when no project is active, since that command requires an active project to act
+   * on.
+   */
   const projectMenuData = useMemo(() => {
     const menu =
       webViewMenuPossiblyError && !isPlatformError(webViewMenuPossiblyError)

src/components/ProjectMetadataModal.tsx

@@ -35,6 +35,8 @@ export type ProjectMetadataModalProps = Readonly<{
   description?: string;
   /** Platform.Bible project ID of the source text. */
   sourceProjectId: string;
+  /** Optional Platform.Bible project ID of the target text for bilateral alignment projects. */
+  targetProjectId?: string;
   /** BCP 47 tags for the analysis languages. */
   analysisLanguages: string[];
   /** ISO 8601 creation timestamp. */
@@ -64,6 +66,7 @@ export function ProjectMetadataModal({
   name,
   description,
   sourceProjectId,
+  targetProjectId,
   analysisLanguages,
   createdAt,
   onClose,
@@ -112,6 +115,7 @@ export function ProjectMetadataModal({
         newName,
         newDescription,
         newLanguages,
+        targetProjectId,
       );
       if (!updatedProjectJson) return;
       onProjectSaved?.({
@@ -126,7 +130,15 @@ export function ProjectMetadataModal({
       isSubmittingRef.current = false;
       setIsSubmitting(false);
     }
-  }, [editName, editDescription, editLanguages, interlinearProjectId, onProjectSaved, onClose]);
+  }, [
+    editName,
+    editDescription,
+    editLanguages,
+    interlinearProjectId,
+    targetProjectId,
+    onProjectSaved,
+    onClose,
+  ]);
 
   /**
    * Sends the delete command to the backend, then notifies the caller and closes the modal. Logs on

src/components/ProjectModals.tsx

@@ -12,8 +12,9 @@ import {
 export type ModalState = 'none' | 'select' | 'create' | 'metadata';
 
 /**
- * Component for managing project modals in the Interlinearizer. Handles state for project creation,
- * selection, and metadata modals.
+ * Single mount point for all project-related dialogs. Renders at most one of
+ * {@link SelectInterlinearProjectModal}, {@link CreateProjectModal}, or {@link ProjectMetadataModal}
+ * based on the `modal` prop, and manages the shared WebView state for the active project.
  *
  * @param props - Component props
  * @param props.activeProject - The currently active interlinear project, read from WebView state by
@@ -52,9 +53,10 @@ export default function ProjectModals({
   );
 
   /**
-   * Tracks where the metadata modal was opened from so the correct modal is restored on close.
-   * `'select'` means it was opened via the info icon in the select modal; `'menu'` means it was
-   * opened via the "View Project Info" menu item.
+   * Tracks whether the metadata modal was opened from the select modal (info icon) or from the
+   * top-menu "View Project Info" item. `true` means opened via the select modal, so closing the
+   * metadata modal restores the select modal; `false` means opened from the menu, so closing
+   * dismisses to `'none'`.
    */
   const [metadataSourceIsSelect, setMetadataSourceIsSelect] = useState(false);
 
@@ -102,29 +104,51 @@ export default function ProjectModals({
     [activeProject, resetActiveProject],
   );
 
+  const handleSelectProject = useCallback(
+    (project: InterlinearProjectSummary) => {
+      setActiveProject(project);
+      setModal('none');
+    },
+    [setActiveProject, setModal],
+  );
+
+  const handleSelectCreateNew = useCallback(() => setModal('create'), [setModal]);
+
+  const handleSelectClose = useCallback(() => setModal('none'), [setModal]);
+
+  const handleCreateClose = useCallback(() => setModal('none'), [setModal]);
+
+  const handleProjectCreated = useCallback(
+    (project: InterlinearProjectSummary) => {
+      setActiveProject(project);
+      setModal('none');
+    },
+    [setActiveProject, setModal],
+  );
+
+  const handleMetadataClose = useCallback(() => {
+    setModal(metadataSourceIsSelect ? 'select' : 'none');
+    setMetadataSourceIsSelect(false);
+    setMetadataProject(undefined);
+  }, [metadataSourceIsSelect, setModal]);
+
   return (
     <div>
       {modal === 'select' && (
         <SelectInterlinearProjectModal
           sourceProjectId={projectId}
-          onSelect={(project) => {
-            setActiveProject(project);
-            setModal('none');
-          }}
-          onCreateNew={() => setModal('create')}
-          onClose={() => setModal('none')}
+          onSelect={handleSelectProject}
+          onCreateNew={handleSelectCreateNew}
+          onClose={handleSelectClose}
           onViewInfo={handleViewInfo}
         />
       )}
 
       {modal === 'create' && (
         <CreateProjectModal
           projectId={projectId}
-          onClose={() => setModal('none')}
-          onProjectCreated={(project) => {
-            setActiveProject(project);
-            setModal('none');
-          }}
+          onClose={handleCreateClose}
+          onProjectCreated={handleProjectCreated}
         />
       )}
 
@@ -134,13 +158,10 @@ export default function ProjectModals({
           name={resolvedMetadataProject.name}
           description={resolvedMetadataProject.description}
           sourceProjectId={resolvedMetadataProject.sourceProjectId}
+          targetProjectId={resolvedMetadataProject.targetProjectId}
           analysisLanguages={resolvedMetadataProject.analysisLanguages}
           createdAt={resolvedMetadataProject.createdAt}
-          onClose={() => {
-            setModal(metadataSourceIsSelect ? 'select' : 'none');
-            setMetadataSourceIsSelect(false);
-            setMetadataProject(undefined);
-          }}
+          onClose={handleMetadataClose}
           onProjectSaved={handleMetadataProjectSaved}
           onProjectDeleted={handleMetadataProjectDeleted}
         />

src/components/SelectInterlinearProjectModal.tsx

@@ -18,13 +18,25 @@ const SELECT_INTERLINEAR_PROJECT_STRING_KEYS: `%${string}%`[] = [
 /** The subset of InterlinearProject fields this modal displays and returns. */
 export type InterlinearProjectSummary = Pick<
   InterlinearProject,
-  'id' | 'createdAt' | 'sourceProjectId' | 'analysisLanguages' | 'name' | 'description'
+  | 'id'
+  | 'createdAt'
+  | 'sourceProjectId'
+  | 'targetProjectId'
+  | 'analysisLanguages'
+  | 'name'
+  | 'description'
 >;
 
 /** Fields of the active interlinear project persisted in WebView state. */
 export type ActiveProjectState = Pick<
   InterlinearProjectSummary,
-  'id' | 'createdAt' | 'name' | 'description' | 'sourceProjectId' | 'analysisLanguages'
+  | 'id'
+  | 'createdAt'
+  | 'name'
+  | 'description'
+  | 'sourceProjectId'
+  | 'targetProjectId'
+  | 'analysisLanguages'
 >;
 
 /**
@@ -48,7 +60,8 @@ export function isInterlinearProjectSummary(p: unknown): p is InterlinearProject
     Array.isArray(p.analysisLanguages) &&
     p.analysisLanguages.every((l) => typeof l === 'string') &&
     (!('name' in p) || typeof p.name === 'string') &&
-    (!('description' in p) || typeof p.description === 'string')
+    (!('description' in p) || typeof p.description === 'string') &&
+    (!('targetProjectId' in p) || typeof p.targetProjectId === 'string')
   );
 }
 

src/hooks/useOptimisticBooleanSetting.ts

@@ -7,9 +7,11 @@ const TIMEOUT_MS = 15_000;
 /**
  * Manages a boolean project setting with optimistic UI updates.
  *
- * The local value is updated immediately on change and stays locked until timeout elapses, to allow
- * the stored setting to finish updating. If the setting fails to save, the local value will persist
- * rather than reverting.
+ * The local value is updated immediately on change and stays locked for {@link TIMEOUT_MS} to allow
+ * the stored setting to finish updating without causing a visible bounce. If the platform confirms
+ * the new value before the timeout, the lock is released; if the platform never responds (or
+ * responds after the timeout), the lock clears and subsequent platform updates flow through
+ * normally.
  *
  * @param projectId - PAPI project ID
  * @param settingKey - A valid key for a boolean setting

src/main.ts

@@ -100,7 +100,7 @@ async function openInterlinearizer(projectId?: string): Promise<string | undefin
  * @param webViewId - ID of an open WebView whose project to use; if omitted falls back to a picker.
  * @returns The WebView ID of the opened (or focused) tab, or `undefined` if the user cancels.
  * @throws If `papi.webViews.getOpenWebViewDefinition` rejects.
- * @throws Any error thrown by {@link openInterlinearizer} (dialog or WebView platform errors).
+ * @throws Any error thrown by {@link openInterlinearizer} (dialog or WebView errors).
  */
 async function openInterlinearizerForWebView(webViewId?: string): Promise<string | undefined> {
   if (!webViewId) return openInterlinearizer();
@@ -161,7 +161,7 @@ async function createInterlinearProject(
  * @param interlinearProjectId - UUID of the interlinearizer project to delete.
  * @returns A promise that resolves when the deletion (or no-op) is complete.
  * @throws {SyntaxError} If the project-IDs index contains invalid JSON (propagated from
- *   {@link projectStorage.deleteProject} via {@link readIds}).
+ *   `projectStorage.deleteProject`).
  * @throws If `papi.storage.deleteUserData` rejects for a non-ENOENT reason, or if
  *   `papi.storage.writeUserData` rejects when updating the index. All storage errors are logged and
  *   shown as a notification before being re-thrown so the caller can handle failure UX.
@@ -234,8 +234,8 @@ async function updateProjectMetadata(
  * @returns A JSON string of `InterlinearProject[]`, or `"[]"` if none exist.
  * @throws {SyntaxError} If the project-IDs index or any project record contains invalid JSON.
  * @throws If `papi.storage.readUserData` rejects for a non-ENOENT reason (propagated from
- *   {@link projectStorage.getProjectsForSource}). Callers can use this to distinguish a storage
- *   outage from a legitimately empty list.
+ *   `projectStorage.getProjectsForSource`). Callers can use this to distinguish a storage outage
+ *   from a legitimately empty list.
  */
 async function getProjectsForSource(sourceProjectId: string): Promise<string> {
   try {

src/services/projectStorage.ts

@@ -285,10 +285,10 @@ export async function updateProjectMetadata(
  * @param id - The project UUID to delete.
  * @throws {SyntaxError} If the `projectIds` storage value contains invalid JSON (from
  *   {@link readIds}).
- * @throws If `papi.storage.deleteUserData` throws for a reason other than ENOENT (non-ENOENT errors
- *   are rethrown).
+ * @throws If `papi.storage.deleteUserData` throws for a reason other than ENOENT.
  * @throws If `papi.storage.writeUserData` rejects when updating `PROJECT_IDS_KEY`.
- * @throws Any error propagated from {@link readIds}, `enqueueProjectOp`, or `enqueueIndexOp`.
+ * @throws Any error propagated from {@link readIds}, {@link enqueueProjectOp}, or
+ *   {@link enqueueIndexOp}.
  */
 export async function deleteProject(token: ExecutionToken, id: string): Promise<void> {
   await enqueueProjectOp(id, async () => {