@eightyfourthousand/lib-editing 2026.3.0

package/src/lib/exporters/link.ts

@@ -0,0 +1,67 @@
+import {
+  AnnotationType,
+  InternalLinkAnnotation,
+  LinkAnnotation,
+  ReferenceAnnotation,
+} from '@eightyfourthousand/data-access';
+import { Exporter, ExporterContext } from './export';
+
+export const LINK_TYPES: AnnotationType[] = ['link', 'reference'];
+
+export const link: Exporter<
+  LinkAnnotation | InternalLinkAnnotation | ReferenceAnnotation
+> = ({
+  mark,
+  node,
+  parent,
+  start,
+  passageUuid,
+}: ExporterContext):
+  | InternalLinkAnnotation
+  | LinkAnnotation
+  | ReferenceAnnotation
+  | undefined => {
+  const type = mark?.attrs.type || mark?.type.name;
+  const uuid = mark?.attrs.uuid;
+
+  if (!type || !LINK_TYPES.includes(type)) {
+    console.warn(`Link mark ${uuid} has invalid or missing type: ${type}`);
+    return undefined;
+  }
+
+  const href = mark?.attrs.href;
+  const textContent = node.textContent || parent.textContent || '';
+  if (!href || !textContent) {
+    console.warn(`Link mark ${uuid} is incomplete`);
+    return undefined;
+  }
+
+  const baseAnnotation = {
+    uuid,
+    type,
+    passageUuid,
+    start,
+    end: start + textContent.length,
+    href,
+  };
+
+  switch (type) {
+    case 'reference':
+      // TODO: implement optional fields
+      // const passage = mark?.attrs.passage;
+      // const authority = mark?.attrs.authority;
+      // const work = mark?.attrs.work;
+      return {
+        ...baseAnnotation,
+        type: 'reference',
+      } as ReferenceAnnotation;
+    case 'link': {
+      const text = mark?.attrs.text;
+      return {
+        ...baseAnnotation,
+        type: 'link',
+        text,
+      } as LinkAnnotation;
+    }
+  }
+};

package/src/lib/exporters/list-item.spec.ts

@@ -0,0 +1,48 @@
+import type { Node } from '@tiptap/pm/model';
+import { listItem } from './list-item';
+
+describe('listItem exporter', () => {
+  it('should export listItem annotation correctly', () => {
+    const node = {
+      attrs: {
+        uuid: 'listitem-uuid-1234',
+      },
+      textContent: 'This is a list item',
+    } as unknown as Node;
+
+    const result = listItem({
+      node,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toEqual({
+      uuid: 'listitem-uuid-1234',
+      passageUuid: 'passage-uuid-1234',
+      type: 'listItem',
+      start: 0,
+      end: 19,
+    });
+  });
+
+  it('should return undefined when textContent is empty', () => {
+    const node = {
+      attrs: {
+        uuid: 'listitem-uuid-empty',
+      },
+      textContent: '',
+    } as unknown as Node;
+
+    const result = listItem({
+      node,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/lib/exporters/list-item.ts

@@ -0,0 +1,24 @@
+import { ListItemAnnotation } from '@eightyfourthousand/data-access';
+import { Exporter } from './export';
+
+export const listItem: Exporter<ListItemAnnotation> = ({
+  node,
+  start,
+  passageUuid,
+}): ListItemAnnotation | undefined => {
+  const textContent = node.textContent || '';
+  const uuid = node.attrs.uuid;
+
+  if (!textContent) {
+    console.warn(`List item ${uuid} is empty`);
+    return undefined;
+  }
+
+  return {
+    uuid,
+    type: 'listItem',
+    passageUuid,
+    start,
+    end: start + textContent.length,
+  };
+};

package/src/lib/exporters/list.spec.ts

@@ -0,0 +1,82 @@
+import type { Node } from '@tiptap/pm/model';
+import { list } from './list';
+
+describe('list exporter', () => {
+  it('should export list annotation correctly', () => {
+    const node = {
+      attrs: {
+        uuid: 'list-uuid-1234',
+        spacing: 'compact',
+        nesting: 0,
+        itemStyle: 'bullet',
+      },
+      textContent: 'Item 1\nItem 2\nItem 3',
+    } as unknown as Node;
+
+    const result = list({
+      node,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toEqual({
+      uuid: 'list-uuid-1234',
+      passageUuid: 'passage-uuid-1234',
+      type: 'list',
+      start: 0,
+      end: 20,
+      spacing: 'compact',
+      nesting: 0,
+      itemStyle: 'bullet',
+    });
+  });
+
+  it('should default nesting to 0 when missing', () => {
+    const node = {
+      attrs: {
+        uuid: 'list-uuid-5678',
+      },
+      textContent: 'Item 1',
+    } as unknown as Node;
+
+    const result = list({
+      node,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toEqual({
+      uuid: 'list-uuid-5678',
+      passageUuid: 'passage-uuid-1234',
+      type: 'list',
+      start: 0,
+      end: 6,
+      spacing: undefined,
+      nesting: 0,
+      itemStyle: undefined,
+    });
+  });
+
+  it('should return undefined when textContent is empty', () => {
+    const node = {
+      attrs: {
+        uuid: 'list-uuid-empty',
+      },
+      textContent: '',
+    } as unknown as Node;
+
+    const result = list({
+      node,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/lib/exporters/list.ts

@@ -0,0 +1,31 @@
+import { ListAnnotation } from '@eightyfourthousand/data-access';
+import { Exporter } from './export';
+
+export const list: Exporter<ListAnnotation> = ({
+  node,
+  start,
+  passageUuid,
+}): ListAnnotation | undefined => {
+  const textContent = node.textContent || '';
+  const uuid = node.attrs.uuid;
+
+  if (!textContent) {
+    console.warn(`List ${uuid} is empty`);
+    return undefined;
+  }
+
+  const spacing = node.attrs.spacing;
+  const nesting = (node.attrs.nesting as number) || 0;
+  const itemStyle = node.attrs.itemStyle;
+
+  return {
+    uuid,
+    type: 'list',
+    passageUuid,
+    start,
+    end: start + textContent.length,
+    spacing,
+    nesting,
+    itemStyle,
+  };
+};

package/src/lib/exporters/mantra.spec.ts

@@ -0,0 +1,51 @@
+import type { Node } from '@tiptap/pm/model';
+import { mantra } from './mantra';
+
+describe('mantra exporter', () => {
+  it('should export mantra annotation correctly', () => {
+    const node = {
+      attrs: {
+        uuid: 'mantra-uuid-1234',
+        lang: 'sa-Latn',
+      },
+      textContent: 'oṃ maṇi padme hūṃ',
+    } as unknown as Node;
+
+    const result = mantra({
+      node,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toEqual({
+      uuid: 'mantra-uuid-1234',
+      passageUuid: 'passage-uuid-1234',
+      type: 'mantra',
+      start: 0,
+      end: 17,
+      lang: 'sa-Latn',
+    });
+  });
+
+  it('should return undefined when textContent is empty', () => {
+    const node = {
+      attrs: {
+        uuid: 'mantra-uuid-empty',
+        lang: 'sa-Latn',
+      },
+      textContent: '',
+    } as unknown as Node;
+
+    const result = mantra({
+      node,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/lib/exporters/mantra.ts

@@ -0,0 +1,25 @@
+import { MantraAnnotation } from '@eightyfourthousand/data-access';
+import { Exporter } from './export';
+
+export const mantra: Exporter<MantraAnnotation> = ({
+  node,
+  start,
+  passageUuid,
+}): MantraAnnotation | undefined => {
+  const { uuid, lang } = node.attrs;
+
+  const textContent = node.textContent || '';
+  if (!textContent) {
+    console.warn(`Mantra ${uuid} is empty`);
+    return undefined;
+  }
+
+  return {
+    uuid,
+    type: 'mantra',
+    lang,
+    passageUuid,
+    start,
+    end: start + textContent.length,
+  };
+};

package/src/lib/exporters/mention.ts

@@ -0,0 +1,41 @@
+import { MentionAnnotation } from '@eightyfourthousand/data-access';
+import { Exporter } from './export';
+
+export const mention: Exporter<MentionAnnotation[]> = ({
+  node,
+  start,
+  passageUuid,
+}): MentionAnnotation[] => {
+  const items = node.attrs.items || [];
+
+  if (items.length === 0) {
+    console.warn(`Mention node on passage ${passageUuid} has no items`);
+    return [];
+  }
+
+  return items.map(
+    (item: {
+      uuid: string;
+      entity: string;
+      linkType: string;
+      text?: string;
+      isSameWork?: boolean;
+      subtype?: string;
+      linkToh?: string;
+    }): MentionAnnotation => ({
+      uuid: item.uuid,
+      type: 'mention',
+      passageUuid,
+      entity: item.entity,
+      linkType: item.linkType,
+      // Persist custom override text, but NEVER persist displayText
+      ...(item.text && { text: item.text }),
+      ...(item.isSameWork !== undefined && { isSameWork: item.isSameWork }),
+      ...(item.subtype && { subtype: item.subtype }),
+      ...(item.linkToh && { linkToh: item.linkToh }),
+      // Zero-length annotation: start === end
+      start,
+      end: start,
+    }),
+  );
+};

package/src/lib/exporters/paragraph.spec.ts

@@ -0,0 +1,173 @@
+import type { Node } from '@tiptap/pm/model';
+import { paragraph } from './paragraph';
+import { annotationExportsFromNode } from './annotation';
+
+describe('paragraph exporter', () => {
+  it('should export paragraph annotation correctly', () => {
+    const parent = {
+      attrs: {
+        uuid: 'parent-uuid-5678',
+      },
+    } as unknown as Node;
+
+    const node = {
+      attrs: {
+        uuid: 'paragraph-uuid-1234',
+      },
+      textContent: 'This is a paragraph of text.',
+    } as unknown as Node;
+
+    const result = paragraph({
+      node,
+      parent,
+      root: parent,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toEqual({
+      uuid: 'paragraph-uuid-1234',
+      passageUuid: 'passage-uuid-1234',
+      type: 'paragraph',
+      start: 0,
+      end: 28,
+    });
+  });
+
+  it('should return undefined when paragraph uuid matches parent uuid', () => {
+    const parent = {
+      attrs: {
+        uuid: 'same-uuid-1234',
+      },
+    } as unknown as Node;
+
+    const node = {
+      attrs: {
+        uuid: 'same-uuid-1234',
+      },
+      textContent: 'This is a paragraph.',
+    } as unknown as Node;
+
+    const result = paragraph({
+      node,
+      parent,
+      root: parent,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it('should return undefined when textContent is empty', () => {
+    const parent = {
+      attrs: {
+        uuid: 'parent-uuid-5678',
+      },
+    } as unknown as Node;
+
+    const node = {
+      attrs: {
+        uuid: 'paragraph-uuid-empty',
+      },
+      textContent: '',
+    } as unknown as Node;
+
+    const result = paragraph({
+      node,
+      parent,
+      root: parent,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('annotationExportsFromNode — null UUID guard', () => {
+  it('should produce no annotation and emit a warning when a paragraph node has no uuid', () => {
+    const warnSpy = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const parent = {
+      attrs: { uuid: 'passage-uuid-1234' },
+      marks: [],
+      type: { name: 'passage' },
+      content: { size: 0, childCount: 0, forEach: () => undefined },
+    } as unknown as Node;
+
+    // Simulate a freshly-split paragraph whose UUID has not yet been assigned
+    // by the NodeView mount cycle (uuid: null, as set by TranslationMetadata default).
+    const nullUuidParagraph = {
+      attrs: { uuid: null },
+      marks: [],
+      type: { name: 'paragraph' },
+      textContent: 'Hello world',
+      content: { size: 0, childCount: 0, forEach: () => undefined },
+    } as unknown as Node;
+
+    const annotations = annotationExportsFromNode({
+      passageUuid: 'passage-uuid-1234',
+      node: nullUuidParagraph,
+      parent,
+      root: parent,
+      start: 0,
+    });
+
+    // The paragraph annotation must be absent — no annotation for a uuid-less node.
+    expect(annotations.filter((a) => a.type === 'paragraph')).toHaveLength(0);
+
+    // A warning must be emitted so the issue is visible in development.
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('missing a uuid'),
+    );
+
+    warnSpy.mockRestore();
+  });
+
+  it('should produce a paragraph annotation when the paragraph node has a valid uuid', () => {
+    const warnSpy = jest
+      .spyOn(console, 'warn')
+      .mockImplementation(() => undefined);
+
+    const parent = {
+      attrs: { uuid: 'passage-uuid-1234' },
+      marks: [],
+      type: { name: 'passage' },
+      content: { size: 0, childCount: 0, forEach: () => undefined },
+    } as unknown as Node;
+
+    const paragraphNode = {
+      attrs: { uuid: 'paragraph-uuid-abcd' },
+      marks: [],
+      type: { name: 'paragraph' },
+      textContent: 'Hello world',
+      content: { size: 0, childCount: 0, forEach: () => undefined },
+    } as unknown as Node;
+
+    const annotations = annotationExportsFromNode({
+      passageUuid: 'passage-uuid-1234',
+      node: paragraphNode,
+      parent,
+      root: parent,
+      start: 0,
+    });
+
+    const paragraphAnnotations = annotations.filter(
+      (a) => a.type === 'paragraph',
+    );
+    expect(paragraphAnnotations).toHaveLength(1);
+    expect(paragraphAnnotations[0]).toMatchObject({
+      uuid: 'paragraph-uuid-abcd',
+      type: 'paragraph',
+      passageUuid: 'passage-uuid-1234',
+      start: 0,
+      end: 11,
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+});

package/src/lib/exporters/paragraph.ts

@@ -0,0 +1,32 @@
+import { ParagraphAnnotation } from '@eightyfourthousand/data-access';
+import { Exporter } from './export';
+
+export const paragraph: Exporter<ParagraphAnnotation> = ({
+  node,
+  parent,
+  start,
+  passageUuid,
+}): ParagraphAnnotation | undefined => {
+  const uuid = node.attrs.uuid;
+  const parentUuid = parent?.attrs.uuid;
+
+  // NOTE: paragraph are often inserted as structural elements. When this happens,
+  // they have the same uuid as their parent. We skip these paragraphs.
+  if (uuid === parentUuid) {
+    return;
+  }
+
+  const textContent = node.textContent || '';
+  if (!textContent) {
+    console.warn(`Paragraph ${uuid} is empty`);
+    return undefined;
+  }
+
+  return {
+    uuid,
+    type: 'paragraph',
+    passageUuid,
+    start,
+    end: start + textContent.length,
+  };
+};

package/src/lib/exporters/quote.spec.ts

@@ -0,0 +1,56 @@
+import type { Node, Mark } from '@tiptap/pm/model';
+import { quote } from './quote';
+
+describe('quote exporter', () => {
+  it('should export quote annotation correctly', () => {
+    const node = {
+      textContent: 'quoted text',
+    } as unknown as Node;
+
+    const mark = {
+      attrs: {
+        uuid: 'quote-uuid-1234',
+      },
+    } as unknown as Mark;
+
+    const result = quote({
+      node,
+      mark,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toEqual({
+      uuid: 'quote-uuid-1234',
+      passageUuid: 'passage-uuid-1234',
+      type: 'quote',
+      start: 0,
+      end: 11,
+    });
+  });
+
+  it('should return undefined when textContent is empty', () => {
+    const node = {
+      textContent: '',
+    } as unknown as Node;
+
+    const mark = {
+      attrs: {
+        uuid: 'quote-uuid-empty',
+      },
+    } as unknown as Mark;
+
+    const result = quote({
+      node,
+      mark,
+      parent: node,
+      root: node,
+      start: 0,
+      passageUuid: 'passage-uuid-1234',
+    });
+
+    expect(result).toBeUndefined();
+  });
+});

package/src/lib/exporters/quote.ts

@@ -0,0 +1,25 @@
+import { QuoteAnnotation } from '@eightyfourthousand/data-access';
+import { Exporter } from './export';
+
+export const quote: Exporter<QuoteAnnotation> = ({
+  node,
+  mark,
+  start,
+  passageUuid,
+}): QuoteAnnotation | undefined => {
+  const textContent = node.textContent || '';
+  const uuid = mark?.attrs.uuid;
+
+  if (!textContent) {
+    console.warn(`List item ${uuid} is empty`);
+    return undefined;
+  }
+
+  return {
+    uuid,
+    type: 'quote',
+    passageUuid,
+    start,
+    end: start + textContent.length,
+  };
+};