@eightyfourthousand/lib-editing 2026.3.0

package/src/lib/components/editor/extensions/EndNoteLink/endnote-utils.ts

@@ -0,0 +1,412 @@
+import { Editor } from '@tiptap/core';
+import { incrementLabel } from '../Passage/label';
+import { findPassageNode } from '../../util';
+
+interface EndNoteLinkNote {
+  uuid: string;
+  endNote: string;
+  label?: string;
+  location?: string;
+  toh?: string;
+}
+
+interface MarkRange {
+  from: number;
+  to: number;
+  mark: ReturnType<Editor['state']['doc']['resolve']> extends never
+  ? never
+  : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  any;
+  note: EndNoteLinkNote;
+}
+
+/**
+ * Scan main editor from start to `cursorPos`, collecting `endNoteLink` marks.
+ * Return the last one's `endNote` UUID and its position info.
+ */
+export function findLastEndNoteLinkBefore(
+  editor: Editor,
+  cursorPos: number,
+): { endNote: string; from: number; to: number } | undefined {
+  const { doc } = editor.state;
+  let last: { endNote: string; from: number; to: number } | undefined;
+
+  doc.descendants((node, pos) => {
+    if (pos >= cursorPos) return false;
+
+    for (const mark of node.marks) {
+      if (mark.type.name === 'endNoteLink') {
+        const notes: EndNoteLinkNote[] = mark.attrs.notes || [];
+        for (const note of notes) {
+          if (note.endNote) {
+            last = { endNote: note.endNote, from: pos, to: pos + node.nodeSize };
+          }
+        }
+      }
+    }
+    return true;
+  });
+
+  return last;
+}
+
+/**
+ * Traverse the editor doc, return all mark ranges where
+ * notes[].endNote === endNotePassageUuid.
+ */
+export function findAllEndnoteLinksForPassage(
+  editor: Editor,
+  endNotePassageUuid: string,
+): MarkRange[] {
+  const { doc } = editor.state;
+  const results: MarkRange[] = [];
+
+  doc.descendants((node, pos) => {
+    for (const mark of node.marks) {
+      if (mark.type.name === 'endNoteLink') {
+        const notes: EndNoteLinkNote[] = mark.attrs.notes || [];
+        for (const note of notes) {
+          if (note.endNote === endNotePassageUuid) {
+            results.push({
+              from: pos,
+              to: pos + node.nodeSize,
+              mark,
+              note,
+            });
+          }
+        }
+      }
+    }
+    return true;
+  });
+
+  return results;
+}
+
+/**
+ * Batch-remove all `endNoteLink` marks pointing to a given passage UUID
+ * using a single transaction.
+ */
+export function removeAllEndnoteLinksForPassage(
+  editor: Editor,
+  endNotePassageUuid: string,
+): void {
+  const ranges = findAllEndnoteLinksForPassage(editor, endNotePassageUuid);
+  if (ranges.length === 0) return;
+
+  const { tr } = editor.state;
+
+  for (const { from, to, mark, note } of ranges) {
+    tr.removeMark(from, to, mark.type);
+    // If the mark has other notes besides the one we're removing, re-add it
+    const remainingNotes = (mark.attrs.notes || []).filter(
+      (n: EndNoteLinkNote) => n.uuid !== note.uuid,
+    );
+    if (remainingNotes.length > 0) {
+      tr.addMark(from, to, mark.type.create({ ...mark.attrs, notes: remainingNotes }));
+    }
+  }
+
+  editor.view.dispatch(tr);
+}
+
+// Re-export for convenience — canonical definition is in ../../util.ts
+export { findPassageNode } from '../../util';
+
+/**
+ * Get the last passage node in the endnotes editor.
+ * Returns { label, sort, uuid } or undefined if no passages exist.
+ */
+export function getLastEndnoteInEditor(
+  editor: Editor,
+): { label: string; sort: number; uuid: string } | undefined {
+  const { doc } = editor.state;
+  let last: { label: string; sort: number; uuid: string; pos: number } | undefined;
+
+  doc.descendants((node, pos) => {
+    if (node.type.name === 'passage') {
+      last = {
+        label: node.attrs.label || '',
+        sort: node.attrs.sort ?? 0,
+        uuid: node.attrs.uuid,
+        pos,
+      };
+    }
+    return true;
+  });
+
+  return last
+    ? { label: last.label, sort: last.sort, uuid: last.uuid }
+    : undefined;
+}
+
+/**
+ * Get the first endnotes-type passage node in the endnotes editor.
+ * Skips endnotesHeader passages.
+ * Returns { label, sort, uuid } or undefined if no passages exist.
+ */
+export function getFirstEndnoteInEditor(
+  editor: Editor,
+): { label: string; sort: number; uuid: string } | undefined {
+  const { doc } = editor.state;
+  let first: { label: string; sort: number; uuid: string } | undefined;
+
+  doc.descendants((node) => {
+    if (!first && node.type.name === 'passage' && node.attrs.type === 'endnotes') {
+      first = {
+        label: node.attrs.label || '',
+        sort: node.attrs.sort ?? 0,
+        uuid: node.attrs.uuid,
+      };
+      return false;
+    }
+    return true;
+  });
+
+  return first;
+}
+
+/**
+ * Insert a new empty endnote passage into the endnotes editor at the correct
+ * position. Use `afterPassageUuid` to insert after a passage, or
+ * `beforePassageUuid` to insert before one. Falls back to end of doc.
+ * Increments labels and sort values of all subsequent passages.
+ */
+export function insertEndnotePassage(
+  editor: Editor,
+  {
+    label,
+    sort,
+    uuid,
+    afterPassageUuid,
+    beforePassageUuid,
+  }: {
+    label: string;
+    sort: number;
+    uuid: string;
+    afterPassageUuid?: string;
+    beforePassageUuid?: string;
+  },
+): void {
+  const { state } = editor;
+  const { tr, schema } = state;
+  const passageType = schema.nodes.passage;
+  const paragraphType = schema.nodes.paragraph;
+
+  if (!passageType || !paragraphType) {
+    console.warn('Required node types not found in schema');
+    return;
+  }
+
+  const newPassage = passageType.create(
+    { label, sort, uuid, type: 'endnotes' },
+    paragraphType.create(),
+  );
+
+  // Find insertion position
+  let insertPos = state.doc.content.size;
+  if (beforePassageUuid) {
+    state.doc.descendants((node, pos) => {
+      if (
+        node.type.name === 'passage' &&
+        node.attrs.uuid === beforePassageUuid
+      ) {
+        insertPos = pos;
+        return false;
+      }
+      return true;
+    });
+  } else if (afterPassageUuid) {
+    state.doc.descendants((node, pos) => {
+      if (
+        node.type.name === 'passage' &&
+        node.attrs.uuid === afterPassageUuid
+      ) {
+        insertPos = pos + node.nodeSize;
+        return false;
+      }
+      return true;
+    });
+  }
+
+  tr.insert(insertPos, newPassage);
+
+  // Increment labels and sorts of passages after the insertion point.
+  // After the insert, the new passage occupies [insertPos, insertPos + newPassage.nodeSize).
+  // Passages that were at insertPos in the original doc are now shifted by newPassage.nodeSize.
+  const afterNewPos = insertPos + newPassage.nodeSize;
+  const parts = label.split('.');
+  const prefix = parts.slice(0, -1).join('.');
+  const prefixWithDot = prefix ? prefix + '.' : '';
+  const depth = parts.length;
+  let expectedNext = incrementLabel(label);
+
+  tr.doc.descendants((child, childPos) => {
+    if (childPos < afterNewPos) return true;
+    if (child.type.name !== 'passage') return true;
+    const childLabel = child.attrs.label as string;
+    if (!childLabel) return true;
+    if (prefixWithDot && !childLabel.startsWith(prefixWithDot)) return true;
+    if (childLabel.split('.').length !== depth) return true;
+
+    if (child.attrs.type === 'endnotesHeader') {
+      // Only update sort, never change header labels
+      tr.setNodeMarkup(childPos, null, {
+        ...child.attrs,
+        sort: (child.attrs.sort ?? 0) + 1,
+      });
+    } else {
+      tr.setNodeMarkup(childPos, null, {
+        ...child.attrs,
+        label: expectedNext,
+        sort: (child.attrs.sort ?? 0) + 1,
+      });
+      expectedNext = incrementLabel(expectedNext);
+    }
+    return true;
+  });
+
+  editor.view.dispatch(tr);
+}
+
+/**
+ * Delete a passage node from the endnotes editor by UUID,
+ * then normalize labels of subsequent passages.
+ */
+export function deleteEndnotePassageNode(
+  editor: Editor,
+  passageUuid: string,
+): void {
+  const found = findPassageNode(editor, passageUuid);
+  if (!found) return;
+
+  const { pos, node } = found;
+  const { tr } = editor.state;
+
+  // Capture the deleted passage's label before removing it — subsequent
+  // passages should be renumbered starting from this label.
+  const deletedLabel = node.attrs.label as string | undefined;
+
+  // Delete the passage node
+  tr.delete(pos, pos + node.nodeSize);
+
+  // Normalize labels after deletion: passages that were after the deleted
+  // node (now starting at `pos` in the updated doc) get renumbered.
+  if (deletedLabel) {
+    let expectedNext = deletedLabel;
+    const parts = deletedLabel.split('.');
+    const prefix = parts.slice(0, -1).join('.');
+    const prefixWithDot = prefix ? prefix + '.' : '';
+    const depth = parts.length;
+
+    tr.doc.descendants((child, childPos) => {
+      // Only process passages at or after the deletion point
+      if (childPos < pos) return true;
+      if (child.type.name !== 'passage') return true;
+      const childLabel = child.attrs.label as string;
+      if (!childLabel) return true;
+
+      // Only normalize passages with same prefix and depth
+      if (prefixWithDot && !childLabel.startsWith(prefixWithDot)) return true;
+      if (childLabel.split('.').length !== depth) return true;
+
+      if (child.attrs.type === 'endnotesHeader') {
+        // Never change header labels
+        return true;
+      }
+      if (childLabel !== expectedNext) {
+        tr.setNodeMarkup(childPos, null, {
+          ...child.attrs,
+          label: expectedNext,
+        });
+      }
+      expectedNext = incrementLabel(expectedNext);
+      return true;
+    });
+  }
+
+  editor.view.dispatch(tr);
+}
+
+/**
+ * Build a map of endnote passage UUID → label from the endnotes editor.
+ */
+export function buildEndnoteLabelMap(
+  endnotesEditor: Editor,
+): Map<string, string> {
+  const map = new Map<string, string>();
+  endnotesEditor.state.doc.descendants((node) => {
+    if (node.type.name === 'passage' && node.attrs.uuid && node.attrs.label) {
+      map.set(node.attrs.uuid, node.attrs.label);
+    }
+    return true;
+  });
+  return map;
+}
+
+/**
+ * Update the `label` field inside `endNoteLink` marks in an editor to match
+ * the current labels in the endnotes editor. Call this after deleting/renumbering
+ * endnote passages so the superscript numbers in the UI stay in sync.
+ */
+export function syncEndnoteLinkLabels(
+  editor: Editor,
+  labelMap: Map<string, string>,
+): void {
+  const { tr } = editor.state;
+  let changed = false;
+
+  editor.state.doc.descendants((node, pos) => {
+    for (const mark of node.marks) {
+      if (mark.type.name !== 'endNoteLink') continue;
+      const notes: EndNoteLinkNote[] = mark.attrs.notes || [];
+      let notesChanged = false;
+
+      const updatedNotes = notes.map((note) => {
+        const newLabel = labelMap.get(note.endNote);
+        if (newLabel !== undefined && newLabel !== note.label) {
+          notesChanged = true;
+          return { ...note, label: newLabel };
+        }
+        return note;
+      });
+
+      if (notesChanged) {
+        const from = pos;
+        const to = pos + node.nodeSize;
+        tr.removeMark(from, to, mark.type);
+        tr.addMark(
+          from,
+          to,
+          mark.type.create({ ...mark.attrs, notes: updatedNotes }),
+        );
+        changed = true;
+      }
+    }
+    return true;
+  });
+
+  if (changed) {
+    editor.view.dispatch(tr);
+  }
+}
+
+/** Editor keys that can contain endNoteLink marks. */
+const ENDNOTE_LINK_EDITOR_KEYS = ['front', 'translation'] as const;
+
+/**
+ * After deleting/renumbering endnote passages, sync the updated labels into
+ * endNoteLink marks across all editors that may contain them (front + translation).
+ */
+export function syncEndnoteLinkLabelsAcrossEditors(
+  endnotesEditor: Editor,
+  getEditor: (key: string) => Editor | undefined,
+): void {
+  const labelMap = buildEndnoteLabelMap(endnotesEditor);
+  for (const key of ENDNOTE_LINK_EDITOR_KEYS) {
+    const ed = getEditor(key);
+    if (ed) {
+      syncEndnoteLinkLabels(ed, labelMap);
+    }
+  }
+}

package/src/lib/components/editor/extensions/GlobalConfig.ts

@@ -0,0 +1,52 @@
+import { Extension } from '@tiptap/core';
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    globalConfig: {
+      /**
+       * Enable or disable debug mode
+       * @example editor.commands.setDebugMode(true)
+       */
+      setDebug: (enabled: boolean) => ReturnType;
+
+      /**
+       * Check if debug mode is enabled
+       * @example editor.isDebug()
+       */
+      isDebug: () => ReturnType;
+    };
+  }
+
+  interface Storage {
+    globalConfig: {
+      debug: boolean;
+    };
+  }
+}
+
+export const GlobalConfig = Extension.create({
+  name: 'globalConfig',
+
+  addStorage() {
+    return {
+      debug: false,
+    };
+  },
+
+  addCommands() {
+    return {
+      setDebug:
+        (enabled) =>
+        ({ editor }) => {
+          this.storage.debug = enabled;
+          // Force re-render if needed
+          editor.view.updateState(editor.state);
+          return true;
+        },
+
+      isDebug: () => () => {
+        return this.storage.debug;
+      },
+    };
+  },
+});

package/src/lib/components/editor/extensions/GlossaryInstance/GlossaryInput.tsx

@@ -0,0 +1,54 @@
+import { Button, Input } from '@eightyfourthousand/design-system';
+import { CheckIcon, Trash2Icon } from 'lucide-react';
+import { useRef } from 'react';
+
+export const GlossaryInput = ({
+  uuid,
+  onSubmit,
+}: {
+  uuid: string;
+  onSubmit: (entity?: string) => void;
+}) => {
+  const uuidRef = useRef<HTMLInputElement>(null);
+
+  const submit = () => {
+    onSubmit(uuidRef.current?.value);
+  };
+
+  return (
+    <div className="flex space-x-1 items-center">
+      <Input
+        ref={uuidRef}
+        placeholder="Glossary uuid..."
+        value={uuid}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') {
+            e.preventDefault();
+            submit();
+          }
+        }}
+      />
+      <Button
+        size="icon"
+        variant="ghost"
+        disabled={!!uuidRef.current}
+        onClick={submit}
+      >
+        <CheckIcon />
+      </Button>
+      <Button
+        variant="ghost"
+        size="icon"
+        type="button"
+        onClick={() => {
+          if (uuidRef.current) {
+            uuidRef.current.value = '';
+          }
+          onSubmit();
+        }}
+      >
+        <Trash2Icon className="text-destructive" />
+      </Button>
+    </div>
+  );
+};

package/src/lib/components/editor/extensions/GlossaryInstance/GlossaryInstance.tsx

@@ -0,0 +1,129 @@
+import { Button } from '@eightyfourthousand/design-system';
+import { Editor } from '@tiptap/core';
+import { BookOpenIcon, PencilIcon, Trash2Icon } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { GlossaryInput } from './GlossaryInput';
+import { findMarkByUuid } from '../../util';
+import { useHoverCard } from '../../../shared/HoverCardProvider';
+
+const EDITOR_UPDATE_DELAY_MS = 100;
+
+export const GlossaryInstance = ({
+  uuid,
+  glossary,
+  editor,
+  anchor,
+}: {
+  uuid: string;
+  glossary: string;
+  editor: Editor;
+  anchor: HTMLElement;
+}) => {
+  const [isEditing, setIsEditingLocal] = useState(false);
+  const { close, setIsEditing: setIsEditingContext } = useHoverCard();
+
+  const setIsEditing = useCallback(
+    (editing: boolean) => {
+      setIsEditingLocal(editing);
+      setIsEditingContext(editing);
+    },
+    [setIsEditingContext],
+  );
+
+  const deleteLink = useCallback(() => {
+    setIsEditing(false);
+    close();
+
+    setTimeout(() => {
+      const range = findMarkByUuid({
+        editor,
+        uuid,
+        markType: 'glossaryInstance',
+      });
+      if (!range) {
+        console.warn('GlossaryInstance mark not found in the document.');
+        return;
+      }
+
+      const { from, to, mark } = range;
+      const { tr } = editor.state;
+      tr.removeMark(from, to, mark.type);
+      editor.view.dispatch(tr);
+    }, EDITOR_UPDATE_DELAY_MS);
+  }, [editor, uuid, close, setIsEditing]);
+
+  const updateGlossary = useCallback(
+    (newGlossary: string) => {
+      setIsEditing(false);
+      close();
+
+      setTimeout(() => {
+        const range = findMarkByUuid({
+          editor,
+          uuid,
+          markType: 'glossaryInstance',
+        });
+        if (!range) {
+          console.warn('GlossaryInstance mark not found in the document.');
+          return;
+        }
+
+        const { from, to, mark } = range;
+        const { tr } = editor.state;
+        tr.removeMark(from, to, mark.type);
+        tr.addMark(
+          from,
+          to,
+          mark.type.create({ ...mark.attrs, glossary: newGlossary }),
+        );
+        editor.view.dispatch(tr);
+
+        // Update the DOM attribute directly for immediate feedback
+        anchor.setAttribute('glossary', newGlossary);
+      }, EDITOR_UPDATE_DELAY_MS);
+    },
+    [editor, uuid, anchor, close, setIsEditing],
+  );
+
+  return (
+    <div className="flex justify-between gap-2 p-2 w-fit max-w-80">
+      {isEditing ? (
+        <GlossaryInput
+          uuid={glossary}
+          onSubmit={(newGlossary) => {
+            if (newGlossary) {
+              updateGlossary(newGlossary);
+            } else {
+              deleteLink();
+            }
+            setIsEditing(false);
+          }}
+        />
+      ) : (
+        <>
+          <BookOpenIcon className="text-primary my-auto size-6 [&_svg]:size-4" />
+          <span className="truncate text-muted-foreground text-sm my-auto">
+            {glossary}
+          </span>
+          <span className="flex-grow" />
+          <Button
+            variant="ghost"
+            size="icon"
+            className="size-6 [&_svg]:size-4"
+            onClick={() => setIsEditing(true)}
+          >
+            <PencilIcon className="text-primary my-auto" />
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon"
+            className="size-6 [&_svg]:size-4"
+            onClick={deleteLink}
+          >
+            <Trash2Icon className="text-destructive my-auto" />
+          </Button>
+        </>
+      )}
+    </div>
+  );
+};