@eightyfourthousand/lib-editing 2026.4.0 → 2026.4.1

package/src/lib/components/editor/PaginationProvider.tsx

@@ -1,457 +0,0 @@
-'use client';
-
-import {
-  createContext,
-  useContext,
-  ReactNode,
-  useRef,
-  useState,
-  useEffect,
-  useMemo,
-} from 'react';
-import { Editor } from '@tiptap/react';
-import { TranslationEditorContent } from './TranslationEditor';
-import { useBlockEditor, useTranslationExtensions } from './hooks';
-import type { XmlFragment } from 'yjs';
-import {
-  createGraphQLClient,
-  getTranslationBlocks,
-  getTranslationBlocksAround,
-} from '@eightyfourthousand/client-graphql';
-import type { PanelFilter } from '@eightyfourthousand/data-access';
-import { PassageSkeleton } from '../shared/PassageSkeleton';
-import { isUuid, scrollToElement, useIsMobile } from '@eightyfourthousand/lib-utils';
-import { PanelName, TabName, useNavigation } from '../shared';
-import { LotusPond, SHEET_ANIMATION_DURATION } from '@eightyfourthousand/design-system';
-import { useEditorState } from './EditorProvider';
-import { usePaginationLoadTriggers } from '../shared/hooks/usePaginationLoadTriggers';
-
-const LOADING_SKELETONS_COUNT = 3;
-const CHUNK_SIZE = 25;
-
-/**
- * Insert content in chunks with yielding to browser to prevent long frame blocking
- */
-const insertContentChunked = async (
-  editor: Editor,
-  pos: number,
-  content: TranslationEditorContent,
-) => {
-  if (!Array.isArray(content) || content.length <= CHUNK_SIZE) {
-    // Small content - insert all at once
-    editor.commands.insertContentAt(pos, content);
-    return;
-  }
-
-  // Insert in chunks to avoid blocking the main thread
-  for (let i = 0; i < content.length; i += CHUNK_SIZE) {
-    const chunk = content.slice(i, i + CHUNK_SIZE);
-    const insertPos = i === 0 ? pos : editor.state.doc.content.size;
-    editor.commands.insertContentAt(insertPos, chunk);
-
-    // Yield to browser between chunks (except after last chunk)
-    if (i + CHUNK_SIZE < content.length) {
-      await new Promise((resolve) => requestAnimationFrame(resolve));
-    }
-  }
-};
-
-interface PaginationContextState {
-  endCursor?: string;
-  startCursor?: string;
-  editor?: Editor;
-}
-
-export const PaginationContext = createContext<PaginationContextState>({});
-
-export const PaginationProvider = ({
-  uuid,
-  filter,
-  panel,
-  tab,
-  content,
-  fragment,
-  isEditable = true,
-  onCreate,
-  children,
-}: {
-  uuid: string;
-  filter?: PanelFilter;
-  panel: PanelName;
-  tab?: TabName;
-  content: TranslationEditorContent;
-  fragment?: XmlFragment;
-  isEditable?: boolean;
-  onCreate?: (params: { editor: Editor }) => void;
-  children: ReactNode;
-}) => {
-  const initialEndCursor = Array.isArray(content)
-    ? content.at(-1)?.attrs?.uuid
-    : content?.attrs?.uuid;
-
-  const { setNavigating } = useEditorState();
-
-  const [startCursor, setStartCursor] = useState<string | undefined>();
-  const [endCursor, setEndCursor] = useState<string | undefined>(
-    initialEndCursor || undefined,
-  );
-  const [navCursor, setNavCursor] = useState<string | undefined>();
-  const processedNavCursorRef = useRef<string | undefined>(undefined);
-  const isNavigatingRef = useRef(false);
-
-  const [startIsLoading, setStartIsLoading] = useState(false);
-  const [endIsLoading, setEndIsLoading] = useState(true);
-  const [isEditorReady, setIsEditorReady] = useState(false);
-  const childrenDivRef = useRef<HTMLDivElement>(null);
-  const handledStartLoadRequestRef = useRef(0);
-  const handledEndLoadRequestRef = useRef(0);
-  const dataClient = useMemo(() => createGraphQLClient(), []);
-
-  const { panels, updatePanel, setShowOuterContent } = useNavigation();
-  const isMobile = useIsMobile();
-
-  // Extract hash as a primitive value so we only react to actual hash changes,
-  // not to every panels object reference change.
-  // When a `tab` is specified, only accept the hash when the panel's active tab
-  // matches — this prevents a PaginationProvider for one tab (e.g. endnotes)
-  // from reacting to hashes set by a different tab (e.g. glossary).
-  const panelHash =
-    !tab || panels[panel]?.tab === tab || (tab === 'translation' && panels[panel]?.tab === 'compare')
-      ? panels[panel]?.hash
-      : undefined;
-
-  const { extensions } = useTranslationExtensions({
-    fragment,
-  });
-
-  const { editor } = useBlockEditor({
-    extensions,
-    content,
-    isEditable,
-    onCreate: ({ editor }) => {
-      setEndIsLoading(false);
-      setIsEditorReady(true);
-      onCreate?.({ editor });
-    },
-  });
-  const {
-    loadMoreAtStartRef,
-    loadMoreAtEndRef,
-    startLoadRequest,
-    endLoadRequest,
-  } = usePaginationLoadTriggers({
-    enabled: isEditorReady,
-    startCursor,
-    endCursor,
-    startIsLoading,
-    endIsLoading,
-  });
-
-  useEffect(() => {
-    setShowOuterContent(!startCursor);
-  }, [startCursor, setShowOuterContent]);
-
-  useEffect(() => {
-    const div = childrenDivRef.current;
-    if (!div) {
-      return;
-    }
-
-    setNavCursor(panelHash);
-  }, [panelHash]);
-
-  useEffect(() => {
-    const div = childrenDivRef.current;
-    if (!div || !navCursor || startIsLoading || endIsLoading) {
-      return;
-    }
-
-    // Guard: Don't re-process the same hash
-    if (processedNavCursorRef.current === navCursor) {
-      return;
-    }
-
-    // Mark as processing IMMEDIATELY (synchronously) to prevent re-entry
-    // from effect re-runs while async work is in progress
-    processedNavCursorRef.current = navCursor;
-
-    (async () => {
-      isNavigatingRef.current = true;
-      setNavigating(true, true, fragment);
-      try {
-        // On mobile, add a delay to allow panel Sheet animation to complete
-        // before attempting to scroll to the element
-        if (isMobile) {
-          await new Promise((resolve) =>
-            setTimeout(resolve, SHEET_ANIMATION_DURATION),
-          );
-        }
-
-        let element = div.querySelector<HTMLElement>(
-          `#${CSS.escape(navCursor)}`,
-        );
-
-        if (!element && isUuid(navCursor)) {
-          const {
-            blocks,
-            hasMoreBefore,
-            hasMoreAfter,
-            prevCursor,
-            nextCursor,
-          } = await getTranslationBlocksAround({
-            client: dataClient,
-            uuid,
-            type: filter,
-            passageUuid: navCursor,
-          });
-
-          // Guard: if the UUID doesn't correspond to any passages for this
-          // filter (e.g. a cross-tab UUID leaked through), bail out rather
-          // than wiping the editor with an empty setContent([]) call.
-          if (!blocks || blocks.length === 0) {
-            return;
-          }
-
-          // Wait for editor to finish updating
-          await new Promise<void>((resolve) => {
-            const handleUpdate = () => {
-              editor?.off('update', handleUpdate);
-              requestAnimationFrame(() => resolve());
-            };
-
-            editor?.on('update', handleUpdate);
-            editor?.chain().clearContent().setContent(blocks).run();
-          });
-          setStartCursor(hasMoreBefore && prevCursor ? prevCursor : undefined);
-          setEndCursor(hasMoreAfter && nextCursor ? nextCursor : undefined);
-
-          // Wait for React to re-render and update the DOM (remove/add skeletons)
-          // by waiting until the element's position stabilizes
-          await new Promise<void>((resolve) => {
-            let stabilityCount = 0;
-            let lastTop = -1;
-
-            const checkStability = () => {
-              const el = div.querySelector<HTMLElement>(
-                `#${CSS.escape(navCursor)}`,
-              );
-              if (!el) {
-                requestAnimationFrame(checkStability);
-                return;
-              }
-
-              const currentTop = el.getBoundingClientRect().top;
-
-              // Check if position has stabilized (same for 2 consecutive frames)
-              if (currentTop === lastTop) {
-                stabilityCount++;
-                if (stabilityCount >= 2) {
-                  resolve();
-                  return;
-                }
-              } else {
-                stabilityCount = 0;
-              }
-
-              lastTop = currentTop;
-              requestAnimationFrame(checkStability);
-            };
-
-            requestAnimationFrame(checkStability);
-          });
-
-          element = div.querySelector<HTMLElement>(`#${CSS.escape(navCursor)}`);
-        }
-
-        if (!element) {
-          return;
-        }
-
-        await scrollToElement({ element });
-
-        updatePanel({
-          name: panel,
-          state: { ...panels[panel], hash: undefined },
-        });
-      } catch (error) {
-        console.error('Navigation failed:', error);
-      } finally {
-        isNavigatingRef.current = false;
-        setNavigating(false);
-      }
-    })();
-  }, [
-    panel,
-    uuid,
-    filter,
-    navCursor,
-    startIsLoading,
-    endIsLoading,
-    // Intentionally excluding `panels` - we only read its current value when clearing hash.
-    // Including it causes infinite loops since updatePanel() creates a new panels object.
-    editor,
-    dataClient,
-    updatePanel,
-    isMobile,
-  ]);
-
-  useEffect(() => {
-    return () => {
-      editor?.destroy();
-    };
-  }, [editor]);
-
-  useEffect(() => {
-    if (
-      endLoadRequest === 0 ||
-      handledEndLoadRequestRef.current === endLoadRequest ||
-      endIsLoading ||
-      !endCursor ||
-      isNavigatingRef.current
-    ) {
-      return;
-    }
-
-    handledEndLoadRequestRef.current = endLoadRequest;
-    setEndIsLoading(true);
-
-    (async () => {
-      const {
-        blocks,
-        hasMoreAfter: hasMore,
-        nextCursor,
-      } = await getTranslationBlocks({
-        client: dataClient,
-        uuid,
-        type: filter,
-        cursor: endCursor,
-      });
-
-      const pos = editor?.state.doc?.content.size;
-
-      if (pos >= 0 && blocks.length && editor) {
-        setNavigating(true);
-        await insertContentChunked(editor, pos, blocks);
-        setNavigating(false);
-      }
-
-      setEndCursor(hasMore && nextCursor ? nextCursor : undefined);
-      setEndIsLoading(false);
-    })();
-  }, [
-    uuid,
-    filter,
-    endIsLoading,
-    editor,
-    endCursor,
-    dataClient,
-    endLoadRequest,
-  ]);
-
-  useEffect(() => {
-    if (
-      startLoadRequest === 0 ||
-      handledStartLoadRequestRef.current === startLoadRequest ||
-      startIsLoading ||
-      !startCursor ||
-      isNavigatingRef.current
-    ) {
-      return;
-    }
-
-    handledStartLoadRequestRef.current = startLoadRequest;
-    setStartIsLoading(true);
-
-    (async () => {
-      const { blocks, hasMoreBefore, prevCursor } = await getTranslationBlocks({
-        client: dataClient,
-        uuid,
-        type: filter,
-        cursor: startCursor,
-        direction: 'backward',
-      });
-
-      const pos = 0;
-
-      if (blocks.length && editor?.view?.dom) {
-        const editorEl = editor.view.dom;
-        const scrollContainer =
-          editorEl.closest('[data-panel]') || editorEl.parentElement;
-        const previousScrollHeight = scrollContainer?.scrollHeight || 0;
-        const previousScrollTop = scrollContainer?.scrollTop || 0;
-
-        // For start insertion, insert all at once to maintain scroll position accuracy.
-        // Chunking here would cause scroll jank since we adjust scroll after insertion.
-        setNavigating(true);
-        editor.commands.insertContentAt(pos, blocks);
-        setNavigating(false);
-
-        requestAnimationFrame(() => {
-          const newScrollHeight = scrollContainer?.scrollHeight || 0;
-          const deltaHeight = newScrollHeight - previousScrollHeight;
-          if (scrollContainer) {
-            scrollContainer.scrollTop = previousScrollTop + deltaHeight;
-          }
-        });
-      } else if (blocks.length && editor) {
-        // Fallback: insert without scroll preservation when view not ready
-        setNavigating(true);
-        editor.commands.insertContentAt(pos, blocks);
-        setNavigating(false);
-      }
-
-      setStartCursor(hasMoreBefore && prevCursor ? prevCursor : undefined);
-      setStartIsLoading(false);
-    })();
-  }, [
-    uuid,
-    filter,
-    startIsLoading,
-    editor,
-    startCursor,
-    dataClient,
-    startLoadRequest,
-  ]);
-
-  return (
-    <PaginationContext.Provider
-      value={{
-        startCursor,
-        endCursor,
-        editor,
-      }}
-    >
-      {startCursor && (
-        <div className="flex flex-col gap-4 pt-6">
-          {Array.from({ length: LOADING_SKELETONS_COUNT }).map((_, i) => (
-            <PassageSkeleton key={i} />
-          ))}
-        </div>
-      )}
-      <div ref={loadMoreAtStartRef} className="h-0" />
-      <div ref={childrenDivRef}>{children}</div>
-      <div ref={loadMoreAtEndRef} className="h-0" />
-      {endCursor ? (
-        <div className="flex flex-col gap-4 pb-8 pt-6">
-          {Array.from({ length: LOADING_SKELETONS_COUNT }).map((_, i) => (
-            <PassageSkeleton key={i} />
-          ))}
-        </div>
-      ) : (
-        <div className="w-full pt-16 pb-6 @c/sidebar:pt-8">
-          <LotusPond className="@c/sidebar:hidden mx-auto w-96" />
-        </div>
-      )}
-    </PaginationContext.Provider>
-  );
-};
-
-export const usePagination = () => {
-  const context = useContext(PaginationContext);
-
-  if (!context) {
-    throw new Error('usePagination must be used within a PaginationProvider');
-  }
-
-  return context;
-};

package/src/lib/components/editor/TitlesBuilder.tsx

@@ -1,40 +0,0 @@
-'use client';
-
-import { Imprint, Titles as TitlesData } from '@eightyfourthousand/data-access';
-import { useEffect, useState } from 'react';
-import { useEditorState } from './EditorProvider';
-import { Titles } from '../shared/titles';
-import { TranslationSkeleton } from '../shared/TranslationSkeleton';
-
-export const TitlesBuilder = ({
-  titles,
-  imprint,
-}: {
-  titles: TitlesData;
-  imprint?: Imprint;
-}) => {
-  const [isEditable, setIsEditable] = useState(false);
-  const [loading, setLoading] = useState(true);
-
-  const { canEdit } = useEditorState();
-
-  useEffect(() => {
-    const checkEditable = async () => {
-      if (!loading) {
-        return;
-      }
-
-      const editable = await canEdit();
-
-      setIsEditable(editable);
-      setLoading(false);
-    };
-    checkEditable();
-  }, [loading, canEdit]);
-
-  return !loading ? (
-    <Titles titles={titles} imprint={imprint} canEdit={isEditable} />
-  ) : (
-    <TranslationSkeleton />
-  );
-};

package/src/lib/components/editor/TranslationBuilder.tsx

@@ -1,171 +0,0 @@
-'use client';
-
-import type { TranslationRenderer } from '../shared/types';
-import { useEffect, useRef, useState } from 'react';
-import type { XmlFragment } from 'yjs';
-import { useEditorState } from './EditorProvider';
-import { TranslationEditor } from './TranslationEditor';
-import { TranslationSkeleton, useNavigation } from '../shared';
-import { PaginationProvider } from './PaginationProvider';
-import {
-  removeAllEndnoteLinksForPassage,
-  syncEndnoteLinkLabelsAcrossEditors,
-} from './extensions/EndNoteLink/endnote-utils';
-
-export const TranslationBuilder = ({
-  content,
-  name,
-  className,
-  filter,
-  panel,
-}: TranslationRenderer) => {
-  const [fragment, setFragment] = useState<XmlFragment>();
-  const [isObserving, setIsObserving] = useState(false);
-  const [isEditable, setIsEditable] = useState(false);
-
-  const {
-    canEdit,
-    setEditor,
-    getEditor,
-    startObserving,
-    getFragment,
-    isNavigating,
-  } = useEditorState();
-
-  const { uuid } = useNavigation();
-
-  // Track known passage UUIDs by passage type so we can detect deletions
-  // (backspace, merge, etc.) and clean up related marks in other editors.
-  // This ref is independent of the Y.js observer's knownUuidsRef, which
-  // can be cleared during navigation.
-  const passageUuidsByTypeRef = useRef<Record<string, Set<string>>>({});
-  const debouncedSyncRef = useRef<ReturnType<typeof setTimeout>>(undefined);
-  const pendingDeletedByTypeRef = useRef<Record<string, Set<string>>>({});
-
-  useEffect(() => {
-    (async () => {
-      const isEditable = await canEdit();
-
-      setIsEditable(isEditable);
-      if (isEditable) {
-        setFragment(getFragment(name));
-      }
-    })();
-  }, [name, canEdit, getFragment]);
-
-  return content && fragment ? (
-    <PaginationProvider
-      uuid={uuid}
-      panel={panel}
-      tab={name}
-      filter={filter}
-      content={content}
-      fragment={fragment}
-      isEditable={isEditable}
-      onCreate={({ editor }) => {
-        editor.commands.setDebug(true);
-        setEditor(name, editor);
-        if (!isObserving) {
-          setIsObserving(true);
-          startObserving(name);
-        }
-
-        if (name === 'endnotes') {
-          // Initialize known passage UUIDs grouped by type
-          const byType: Record<string, Set<string>> = {};
-          const doc = editor.state.doc;
-          for (let i = 0; i < doc.childCount; i++) {
-            const child = doc.child(i);
-            if (child.type.name === 'passage' && child.attrs.uuid) {
-              const pType = (child.attrs.type as string) || 'unknown';
-              (byType[pType] ??= new Set()).add(child.attrs.uuid);
-            }
-          }
-          passageUuidsByTypeRef.current = byType;
-
-          editor.on('update', () => {
-            // Collect current passage UUIDs grouped by type (cheap)
-            const currentByType: Record<string, Set<string>> = {};
-            const doc = editor.state.doc;
-            for (let i = 0; i < doc.childCount; i++) {
-              const child = doc.child(i);
-              if (child.type.name === 'passage' && child.attrs.uuid) {
-                const pType = (child.attrs.type as string) || 'unknown';
-                (currentByType[pType] ??= new Set()).add(child.attrs.uuid);
-              }
-            }
-
-            // Detect deleted and added passages per type (skip during
-            // navigation to avoid false positives from content replacement)
-            const deletedByType: Record<string, string[]> = {};
-            let hasAdded = false;
-            if (!isNavigating()) {
-              const prevByType = passageUuidsByTypeRef.current;
-              for (const pType of Object.keys(prevByType)) {
-                const prev = prevByType[pType];
-                const curr = currentByType[pType];
-                prev.forEach((uuid) => {
-                  if (!curr?.has(uuid)) {
-                    (deletedByType[pType] ??= []).push(uuid);
-                  }
-                });
-              }
-              if (!hasAdded) {
-                outer: for (const pType of Object.keys(currentByType)) {
-                  const prev = prevByType[pType];
-                  for (const uuid of currentByType[pType]) {
-                    if (!prev?.has(uuid)) {
-                      hasAdded = true;
-                      break outer;
-                    }
-                  }
-                }
-              }
-            }
-
-            // Always update the baseline so the next diff is accurate
-            passageUuidsByTypeRef.current = currentByType;
-
-            const hasDeleted = Object.keys(deletedByType).length > 0;
-
-            // Accumulate deletions and debounce the expensive sync work
-            // so rapid keystrokes don't trigger multiple full traversals
-            for (const [pType, uuids] of Object.entries(deletedByType)) {
-              const pending = (pendingDeletedByTypeRef.current[pType] ??=
-                new Set());
-              for (const uuid of uuids) {
-                pending.add(uuid);
-              }
-            }
-
-            if (hasDeleted || hasAdded) {
-              if (debouncedSyncRef.current) {
-                clearTimeout(debouncedSyncRef.current);
-              }
-              debouncedSyncRef.current = setTimeout(() => {
-                const pendingEndnotes =
-                  pendingDeletedByTypeRef.current['endnotes'];
-                if (pendingEndnotes?.size) {
-                  const frontEditor = getEditor('front');
-                  const translationEditor = getEditor('translation');
-                  for (const uuid of pendingEndnotes) {
-                    if (frontEditor)
-                      removeAllEndnoteLinksForPassage(frontEditor, uuid);
-                    if (translationEditor)
-                      removeAllEndnoteLinksForPassage(translationEditor, uuid);
-                  }
-                }
-                pendingDeletedByTypeRef.current = {};
-                syncEndnoteLinkLabelsAcrossEditors(editor, getEditor);
-              }, 150);
-            }
-          });
-        }
-      }}
-    >
-      <TranslationEditor className={className} />
-    </PaginationProvider>
-  ) : (
-    <TranslationSkeleton />
-  );
-};

package/src/lib/components/editor/TranslationEditor.tsx

@@ -1,32 +0,0 @@
-'use client';
-
-import { EditorContent } from '@tiptap/react';
-import { TranslationBubbleMenu } from './menus';
-import { cn } from '@eightyfourthousand/lib-utils';
-import { usePagination } from './PaginationProvider';
-import type {
-  TranslationEditorContentItem,
-  TranslationEditorContent,
-} from '@eightyfourthousand/data-access';
-
-// Re-export for backwards compatibility
-export type { TranslationEditorContentItem, TranslationEditorContent };
-
-export const TranslationEditor = ({ className }: { className?: string }) => {
-  const { editor } = usePagination();
-
-  if (!editor) {
-    return null;
-  }
-
-  return (
-    <div className={cn('flex h-full', className)}>
-      <div className="relative flex flex-col flex-1 h-full">
-        <EditorContent className="flex-1" editor={editor} />
-        {editor.isEditable && <TranslationBubbleMenu editor={editor} />}
-      </div>
-    </div>
-  );
-};
-
-export default TranslationEditor;