@eightyfourthousand/lib-editing 2026.3.0

package/src/lib/passage.ts

@@ -0,0 +1,182 @@
+import { Editor } from '@tiptap/react';
+import { Node } from '@tiptap/pm/model';
+import { v4 as uuidv4 } from 'uuid';
+import {
+  annotationExportsFromNode,
+  markAnnotationFromNode,
+  parameterAnnotationFromNode,
+} from './exporters';
+import { findNodePosition, nodeNotFound } from './exporters/util';
+import { ExporterContext } from './exporters/export';
+import { Passage } from '@eightyfourthousand/data-access';
+
+/**
+ * Ensures every node in the editor document has a unique, non-null UUID.
+ *
+ * UUID assignment normally happens asynchronously in NodeView lifecycle hooks
+ * (validateAttrs / createNodeViewDom). When save() is called shortly after a
+ * structural edit (e.g. pressing Enter to create a new paragraph, or splitting
+ * a passage), some nodes may still carry uuid: null or a UUID duplicated from
+ * the node they were split from.  passagesFromNodes() then reads those nodes
+ * synchronously, and annotationExportsFromNode silently skips any node whose
+ * uuid is falsy — producing missing paragraph annotations.
+ *
+ * This function walks the document synchronously and dispatches a single
+ * transaction that stamps a fresh UUID onto every node or mark that either:
+ *   1. has uuid: null / undefined / empty, OR
+ *   2. duplicates the UUID of another node/mark already seen in this walk.
+ *
+ * Block nodes are updated via tr.setNodeMarkup. Inline marks (Link,
+ * InternalLink, GlossaryInstance) carry their own uuid attribute and are
+ * updated via tr.removeMark + tr.addMark, since setNodeMarkup does not apply
+ * to marks. This prevents duplicate annotation UUIDs when a passage is split
+ * and the afterContent inherits copies of the original marks.
+ *
+ * It must be called (and awaited via a Promise.resolve()) before
+ * passagesFromNodes() so that the transaction is committed to the editor state.
+ */
+// Parameter annotation UUID attributes that live on block node attrs (not marks)
+// and must be deduplicated alongside the main `uuid` attribute.
+const PARAMETER_UUID_ATTRS = ['leadingSpaceUuid', 'indentUuid'] as const;
+
+export const ensureUuids = (editor: Editor): void => {
+  const { state, view } = editor;
+  const { doc, tr } = state;
+  const seen = new Set<string>();
+  let changed = false;
+
+  doc.descendants((node, pos) => {
+    // text and doc nodes never carry a uuid
+    if (node.type.name === 'text' || node.type.name === 'doc') {
+      return true;
+    }
+
+    let newAttrs: Record<string, unknown> | null = null;
+
+    // Check main uuid
+    const existing: string | null | undefined = node.attrs.uuid;
+    if (!existing || seen.has(existing)) {
+      newAttrs = { ...node.attrs, uuid: uuidv4() };
+      seen.add(newAttrs.uuid as string);
+    } else {
+      seen.add(existing);
+    }
+
+    // Check parameter annotation UUIDs
+    for (const attrKey of PARAMETER_UUID_ATTRS) {
+      const existingParam = node.attrs[attrKey] as string | null | undefined;
+      if (existingParam === undefined) continue; // node type doesn't use this attr
+      if (!existingParam || seen.has(existingParam)) {
+        newAttrs = { ...(newAttrs ?? node.attrs), [attrKey]: uuidv4() };
+        seen.add(newAttrs[attrKey] as string);
+      } else {
+        seen.add(existingParam);
+      }
+    }
+
+    if (newAttrs) {
+      tr.setNodeMarkup(pos, undefined, newAttrs);
+      changed = true;
+    }
+
+    return true;
+  });
+
+  // Second pass: walk text nodes and fix marks that carry a uuid attribute
+  // (Link, InternalLink, GlossaryInstance). doc.descendants does not expose
+  // marks directly, so we must walk text nodes to find them.
+  doc.descendants((node, pos) => {
+    if (node.type.name !== 'text' || node.marks.length === 0) return true;
+
+    for (const mark of node.marks) {
+      const existing: string | null | undefined = mark.attrs.uuid;
+      if (existing === undefined) continue; // mark type has no uuid attribute
+
+      const isDuplicate = existing ? seen.has(existing) : false;
+      if (!existing || isDuplicate) {
+        const newUuid = uuidv4();
+        const newMark = mark.type.create({ ...mark.attrs, uuid: newUuid });
+        // pos is the start of the text node; the mark spans the full text node
+        tr.removeMark(pos, pos + node.nodeSize, mark.type);
+        tr.addMark(pos, pos + node.nodeSize, newMark);
+        seen.add(newUuid);
+        changed = true;
+      } else {
+        seen.add(existing);
+      }
+    }
+
+    return true;
+  });
+
+  if (changed) {
+    view.dispatch(tr);
+  }
+};
+
+export const passageFromNode = (node: Node, workUuid: string): Passage => {
+  const uuid = node.attrs.uuid;
+  const type = node.attrs.type;
+  const toh = node.attrs.toh;
+
+  const ctx: ExporterContext = {
+    passageUuid: uuid,
+    node,
+    parent: node,
+    root: node,
+    start: 0,
+  };
+  const annotations = [
+    ...parameterAnnotationFromNode(ctx),
+    ...markAnnotationFromNode(ctx),
+  ];
+  node.content.forEach((child) => {
+    const start = findNodePosition(node, child.attrs.uuid, child.type.name);
+    if (start === undefined) {
+      return nodeNotFound(child);
+    }
+    annotations.push(
+      ...annotationExportsFromNode({
+        passageUuid: uuid,
+        node: child,
+        parent: node,
+        root: node,
+        start,
+      }),
+    );
+  });
+
+  const passage: Passage = {
+    uuid,
+    type,
+    workUuid,
+    sort: node.attrs.sort,
+    label: node.attrs.label,
+    content: node.textContent,
+    toh,
+    annotations,
+  };
+  return passage;
+};
+
+export const passagesFromNodes = ({
+  uuids,
+  workUuid,
+  editor,
+}: {
+  uuids: string[];
+  workUuid: string;
+  editor: Editor;
+}): Passage[] => {
+  const passages: Passage[] = [];
+  uuids.forEach((uuid) => {
+    const node = editor.$node('passage', { uuid });
+    if (!node) {
+      console.warn(`No passage node found for uuid: ${uuid}`);
+      return;
+    }
+
+    passages.push(passageFromNode(node.node, workUuid));
+  });
+  return passages;
+};

package/src/lib/titles.ts

@@ -0,0 +1,80 @@
+import {
+  type ExtendedTranslationLanguage,
+  TITLE_TYPES,
+  type Titles,
+  type TitleType,
+} from '@eightyfourthousand/data-access';
+import type { BlockEditorContent } from './components';
+
+const TYPE_FOR_LANGUAGE: Record<ExtendedTranslationLanguage | 'toh', string> = {
+  toh: 'tohTitle',
+  bo: 'boTitle',
+  en: 'enTitle',
+  ja: 'jaTitle',
+  zh: 'zhTitle',
+  'Bo-Ltn': 'boLtnTitle',
+  'Mt-Ltn': 'mtLtnTitle',
+  'Pi-Ltn': 'piLtnTitle',
+  'Sa-Ltn': 'saLtnTitle',
+  'Zh-Ltn': 'zhLtnTitle',
+};
+
+const TITLES_TYPE_TO_NODE_TYPE: Record<TitleType, string> = {
+  toh: 'tohs',
+  mainTitle: 'mainTitles',
+  mainTitleOutsideCatalogueSection: 'alternateMainTitles',
+  longTitle: 'longTitles',
+  otherTitle: 'otherTitles',
+  shortcode: 'shortCodes',
+};
+
+export const titlesToDocument = (titles: Titles): BlockEditorContent => {
+  const content: BlockEditorContent = {
+    type: 'titles',
+    content: [],
+  };
+
+  const titlesByType: Partial<Record<TitleType, Titles>> = {};
+  titles.forEach((title) => {
+    if (!titlesByType[title.type]) {
+      titlesByType[title.type] = [];
+    }
+    titlesByType[title.type]?.push(title);
+  });
+
+  // NOTE: the imported list is already in preferred order
+  TITLE_TYPES.forEach((type) => {
+    const titlesOfType = titlesByType[type];
+    if (titlesOfType?.length) {
+      const orderedTitles = [
+        ...titlesOfType.filter((title) => title.language === 'bo'),
+        ...titlesOfType.filter((title) => title.language === 'en'),
+        ...titlesOfType.filter((title) => title.language === 'Bo-Ltn'),
+        ...titlesOfType.filter((title) => title.language === 'Sa-Ltn'),
+        ...titlesOfType.filter((title) => title.language === 'Pi-Ltn'),
+        ...titlesOfType.filter((title) => title.language === 'zh'),
+        ...titlesOfType.filter((title) => title.language === 'ja'),
+      ];
+
+      content.content?.push({
+        type: TITLES_TYPE_TO_NODE_TYPE[type],
+        content: orderedTitles.map((title) => ({
+          type: TYPE_FOR_LANGUAGE[title.language],
+          attrs: {
+            language: title.language,
+            uuid: title.uuid,
+            type: title.type,
+          },
+          content: [
+            {
+              type: 'text',
+              text: title.title,
+            },
+          ],
+        })),
+      });
+    }
+  });
+
+  return content;
+};

package/src/lib/transformers/abbreviation.spec.ts

@@ -0,0 +1,87 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { abbreviation } from './abbreviation';
+import { blockFromPassage } from '../block';
+import { recurseForType } from './recurse';
+
+const dto: PassageDTO = {
+  sort: 13140,
+  type: 'abbreviations',
+  uuid: 'e350ec6c-a40c-46bf-8182-acba5a50e4fe',
+  label: '',
+  xmlId: 'UT22084-001-001-2226',
+  parent: 'UT22084-001-001-notes-1',
+  content: 'C Choné',
+  work_uuid: '092e9a3c-12a6-4e1c-a05b-16835c0e62a8',
+  annotations: [
+    {
+      end: 2,
+      type: 'abbreviation',
+      uuid: '49c41c6d-0e04-412e-81ad-22f3af377470',
+      start: 0,
+      content: [
+        {
+          uuid: 'e350ec6c-a40c-46bf-8182-acba5a50e4fe',
+        },
+      ],
+      passage_uuid: 'e350ec6c-a40c-46bf-8182-acba5a50e4fe',
+    },
+    {
+      end: 7,
+      type: 'has-abbreviation',
+      uuid: '1e5003e8-e015-4b94-b88c-80b39c263098',
+      start: 2,
+      content: [
+        {
+          uuid: 'e350ec6c-a40c-46bf-8182-acba5a50e4fe',
+        },
+      ],
+      passage_uuid: 'e350ec6c-a40c-46bf-8182-acba5a50e4fe',
+    },
+  ],
+};
+
+describe('abbreviation transformer', () => {
+  const passage = passageFromDTO(
+    dto,
+    annotationsFromDTO(dto.annotations || []),
+  );
+  const block = blockFromPassage(passage);
+
+  if (!block?.content) {
+    throw new Error('Block conversion failed');
+  }
+
+  it('should transform abbreviation annotation correctly', () => {
+    const annotation = passage.annotations.find(
+      (a: Annotation) => a.type === 'abbreviation',
+    ) as Annotation;
+    abbreviation({
+      root: block,
+      parent: block,
+      block,
+      annotation,
+    });
+
+    const val = recurseForType({
+      until: 'abbreviation',
+      block,
+    });
+
+    expect(val).toBeDefined();
+    expect(val?.type).toBe('abbreviation');
+    expect(val?.attrs).toBeDefined();
+    expect(val?.attrs?.abbreviation).toBe(
+      'e350ec6c-a40c-46bf-8182-acba5a50e4fe',
+    );
+    expect(val?.attrs?.uuid).toBe('49c41c6d-0e04-412e-81ad-22f3af377470');
+    expect(val?.content).toBeDefined();
+    expect(val?.content?.length).toBe(1);
+    expect(val?.content?.[0].type).toBe('text');
+    expect(val?.content?.[0].text).toBe('C ');
+  });
+});

package/src/lib/transformers/abbreviation.ts

@@ -0,0 +1,30 @@
+import { AbbreviationAnnotation } from '@eightyfourthousand/data-access';
+import { recurse } from './recurse';
+import { Transformer } from './transformer';
+import { splitContent } from './split-content';
+
+export const abbreviation: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const { abbreviation, uuid } = annotation as AbbreviationAnnotation;
+
+  recurse({
+    until: ['text'],
+    ...ctx,
+    transform: (ctx) => {
+      splitContent({
+        ...ctx,
+        transform: ({ block }) => {
+          block.type = 'abbreviation';
+          block.attrs = {
+            ...block.attrs,
+            abbreviation,
+            uuid,
+          };
+          block.content = [
+            { type: 'text', text: block.text, marks: block.marks },
+          ];
+        },
+      });
+    },
+  });
+};

package/src/lib/transformers/annotate.ts

@@ -0,0 +1,146 @@
+import {
+  AnnotationType,
+  Annotations,
+  ExtendedTranslationLanguage,
+} from '@eightyfourthousand/data-access';
+import type { TranslationEditorContentType, Transformer } from './transformer';
+import {
+  audio,
+  abbreviation,
+  blockquote,
+  code,
+  deprecated,
+  endNoteLink,
+  glossaryInstance,
+  hasAbbreviation,
+  heading,
+  image,
+  indent,
+  inlineTitle,
+  internalLink,
+  leadingSpace,
+  lineGroup,
+  line,
+  link,
+  list,
+  listItem,
+  mantra,
+  mention,
+  paragraph,
+  quote,
+  quoted,
+  reference,
+  span,
+  table,
+  tableBodyData,
+  tableBodyHeader,
+  tableBodyRow,
+  trailer,
+  unknown,
+} from '.';
+import type { TranslationEditorContentItem } from '../components/editor';
+
+const TRANSFORMERS: Partial<Record<AnnotationType, Transformer>> = {
+  abbreviation,
+  audio,
+  blockquote,
+  code,
+  deprecated,
+  endNoteLink,
+  glossaryInstance,
+  hasAbbreviation,
+  heading,
+  indent,
+  image,
+  inlineTitle,
+  internalLink,
+  leadingSpace,
+  line,
+  lineGroup,
+  link,
+  list,
+  listItem,
+  mantra,
+  mention,
+  paragraph,
+  quote,
+  quoted,
+  reference,
+  span,
+  table,
+  tableBodyData,
+  tableBodyHeader,
+  tableBodyRow,
+  trailer,
+  unknown,
+} as const;
+
+export const ITALIC_LANGUAGES: ExtendedTranslationLanguage[] = [
+  'en',
+  'Bo-Ltn',
+  'Mt-Ltn',
+  'Pi-Ltn',
+  'Sa-Ltn',
+  'Zh-Ltn',
+] as const;
+
+export const isAttributeAnnotation = (type: TranslationEditorContentType) => {
+  return ['indent', 'leadingSpace'].includes(type);
+};
+
+export const isBlockAnnotation = (type: TranslationEditorContentType) => {
+  return [
+    'blockquote',
+    'endnotes',
+    'heading',
+    'line',
+    'lineGroup',
+    'list',
+    'listItem',
+    'paragraph',
+    'table',
+    'tableBodyData',
+    'tableBodyHeader',
+    'tableBodyRow',
+    'trailer',
+  ].includes(type);
+};
+
+export const isInlineAnnotation = (type: TranslationEditorContentType) => {
+  return [
+    'abbreviation',
+    'audio',
+    'code',
+    'endNoteLink',
+    'glossaryInstance',
+    'hasAbbreviation',
+    'image',
+    'italic',
+    'inlineTitle',
+    'internalLink',
+    'link',
+    'mantra',
+    'mention',
+    'quote',
+    'quoted',
+    'reference',
+    'span',
+    'text',
+  ].includes(type);
+};
+
+export const annotateBlock = (
+  block: TranslationEditorContentItem,
+  annotations: Annotations,
+) => {
+  for (const annotation of annotations) {
+    const transformer = TRANSFORMERS[annotation.type] || TRANSFORMERS.unknown;
+    transformer?.({ root: block, block, annotation });
+    if (!annotation.validated) {
+      if (!block.attrs) {
+        block.attrs = {};
+      }
+      block.attrs.invalid = true;
+    }
+  }
+};

package/src/lib/transformers/audio.spec.ts

@@ -0,0 +1,55 @@
+import { annotationsFromDTO, PassageDTO, passageFromDTO } from '@eightyfourthousand/data-access';
+import { blockFromPassage } from '../block';
+import { recurseForType } from './recurse';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'Listen to the audio recording.',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 9,
+      type: 'audio',
+      uuid: 'audio-uuid-1',
+      start: 9,
+      content: [
+        {
+          src: 'https://example.com/audio.mp3',
+        },
+        {
+          'media-type': 'audio/mpeg',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('audio transformer', () => {
+  const passage = passageFromDTO(
+    dto,
+    annotationsFromDTO(dto.annotations || [], dto.content.length),
+  );
+  const block = blockFromPassage(passage);
+
+  if (!block?.content) {
+    throw new Error('Block conversion failed');
+  }
+
+  it('should transform audio annotation correctly', () => {
+    const audioNode = recurseForType({
+      until: 'audio',
+      block,
+    });
+    expect(audioNode).toBeDefined();
+    expect(audioNode?.type).toBe('audio');
+    expect(audioNode?.attrs?.src).toBe('https://example.com/audio.mp3');
+    expect(audioNode?.attrs?.mediaType).toBe('audio/mpeg');
+    expect(audioNode?.attrs?.uuid).toBe('audio-uuid-1');
+  });
+});

package/src/lib/transformers/audio.ts

@@ -0,0 +1,29 @@
+import { AudioAnnotation } from '@eightyfourthousand/data-access';
+import { Transformer } from './transformer';
+import { recurse } from './recurse';
+import { splitAndInsert } from './split-insert';
+
+export const audio: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const { src, mediaType, uuid, start, end } = annotation as AudioAnnotation;
+  recurse({
+    ...ctx,
+    until: ['paragraph'],
+    transform: (ctx) => {
+      splitAndInsert({
+        ...ctx,
+        transform: ({ block }) => {
+          block.type = 'audio';
+          block.attrs = {
+            ...block.attrs,
+            src,
+            mediaType,
+            uuid,
+            start,
+            end,
+          };
+        },
+      });
+    },
+  });
+};

package/src/lib/transformers/blockquote.spec.ts

@@ -0,0 +1,48 @@
+import { annotationsFromDTO, PassageDTO, passageFromDTO } from '@eightyfourthousand/data-access';
+import { blockFromPassage } from '../block';
+import { recurseForType } from './recurse';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'This is a quoted text from scripture.',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 37,
+      type: 'blockquote',
+      uuid: 'blockquote-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('blockquote transformer', () => {
+  const passage = passageFromDTO(
+    dto,
+    annotationsFromDTO(dto.annotations || [], dto.content.length),
+  );
+  const block = blockFromPassage(passage);
+
+  if (!block?.content) {
+    throw new Error('Block conversion failed');
+  }
+
+  it('should transform blockquote annotation correctly', () => {
+    const blockquoteNode = recurseForType({
+      until: 'blockquote',
+      block,
+    });
+    expect(blockquoteNode).toBeDefined();
+    expect(blockquoteNode?.type).toBe('blockquote');
+    expect(blockquoteNode?.attrs?.uuid).toBe('blockquote-uuid-1');
+    expect(blockquoteNode?.content).toBeDefined();
+    expect(blockquoteNode?.content?.[0]?.type).toBe('paragraph');
+  });
+});

package/src/lib/transformers/blockquote.ts

@@ -0,0 +1,41 @@
+import { recurse } from './recurse';
+import { splitBlock } from './split-block';
+import { Transformer } from './transformer';
+
+export const blockquote: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const { start, end, uuid } = annotation || {};
+
+  recurse({
+    ...ctx,
+    until: ['paragraph', 'lineGroup'],
+    transform: (ctx) => {
+      const origType = ctx.block?.type || 'paragraph';
+      splitBlock({
+        ...ctx,
+        transform: (ctx) => {
+          const { block } = ctx;
+          block.type = 'blockquote';
+          block.attrs = {
+            ...block.attrs,
+            start,
+            end,
+            uuid,
+          };
+          block.content = [
+            {
+              type: origType,
+              attrs: {
+                ...block.attrs,
+                start,
+                end,
+                uuid,
+              },
+              content: block.content || [],
+            },
+          ];
+        },
+      });
+    },
+  });
+};