@eightyfourthousand/lib-editing 2026.4.0 → 2026.4.2

package/src/lib/exporters/annotation.ts

@@ -1,193 +0,0 @@
-import { Annotation, AnnotationType } from '@eightyfourthousand/data-access';
-import { Exporter, ExporterContext } from './export';
-import { abbreviation } from './abbreviation';
-import { audio } from './audio';
-import { blockquote } from './blockquote';
-import { code } from './code';
-import { endNoteLink } from './end-note-link';
-import { glossaryInstance } from './glossary-instance';
-import { hasAbbreviation } from './has-abbreviation';
-import { heading } from './heading';
-import { image } from './image';
-import { indent } from './indent';
-import { internalLink } from './internal-link';
-import { italic } from './italic';
-import { leadingSpace } from './leading-space';
-import { line } from './line';
-import { lineGroup } from './line-group';
-import { link } from './link';
-import { listItem } from './list-item';
-import { list } from './list';
-import { mantra } from './mantra';
-import { mention } from './mention';
-import { paragraph } from './paragraph';
-import { quote } from './quote';
-import { span } from './span';
-import { trailer } from './trailer';
-import { table } from './table';
-import { tableBodyData } from './table-body-data';
-import { tableBodyHeader } from './table-body-header';
-import { tableBodyRow } from './table-body-row';
-import { SpanMarkType } from '../types';
-import { findNodePosition, nodeNotFound } from './util';
-
-const EXPORTERS: Partial<
-  Record<
-    | AnnotationType
-    | SpanMarkType
-    | 'text'
-    | 'bulletList'
-    | 'tableCell'
-    | 'tableHeader'
-    | 'tableRow',
-    Exporter<Annotation | Annotation[]>
-  >
-> = {
-  abbreviation,
-  audio,
-  bold: span,
-  blockquote,
-  bulletList: list,
-  code,
-  endNoteLink,
-  glossaryInstance,
-  hasAbbreviation,
-  heading,
-  image,
-  indent,
-  inlineTitle: italic,
-  internalLink,
-  italic,
-  leadingSpace,
-  line,
-  lineGroup,
-  link,
-  listItem,
-  mantra,
-  mention,
-  paragraph,
-  quote,
-  reference: link,
-  smallCaps: span,
-  subscript: span,
-  superscript: span,
-  table,
-  tableCell: tableBodyData,
-  tableHeader: tableBodyHeader,
-  tableRow: tableBodyRow,
-  trailer,
-  underline: span,
-
-  // ignored types
-  deprecated: undefined,
-  quoted: undefined,
-  unknown: undefined,
-  text: undefined,
-};
-
-const PARAMETER_ANNOTATION_MAP: { [key: string]: AnnotationType } = {
-  hasIndent: 'indent',
-  hasLeadingSpace: 'leadingSpace',
-};
-
-export const parameterAnnotationFromNode = (
-  ctx: ExporterContext,
-): Annotation[] => {
-  const annotations: Annotation[] = [];
-  const { node, start } = ctx;
-
-  const keys = Object.keys(PARAMETER_ANNOTATION_MAP);
-  keys.forEach((key) => {
-    const annotType = PARAMETER_ANNOTATION_MAP[key];
-    const exporter = EXPORTERS[annotType];
-    const hasAttr = !!node.attrs[key];
-    if (!hasAttr) {
-      return;
-    }
-
-    if (!exporter) {
-      console.warn(`No exporter for parameter annotation: ${key}`);
-    }
-
-    const annotation = exporter?.({ ...ctx, start });
-    if (!annotation) {
-      return;
-    }
-
-    if (Array.isArray(annotation)) {
-      annotations.push(...annotation);
-    } else {
-      annotations.push(annotation);
-    }
-  });
-
-  return annotations;
-};
-
-export const markAnnotationFromNode = (ctx: ExporterContext): Annotation[] => {
-  const { node } = ctx;
-  const annotations: Annotation[] = [];
-  node.marks.forEach((mark) => {
-    const start = findNodePosition(ctx.root, mark.attrs.uuid, mark.type.name);
-    if (start === undefined) {
-      return nodeNotFound(mark);
-    }
-    const type = mark.type.name as AnnotationType;
-    const annotation = EXPORTERS[type]?.({ ...ctx, mark, start });
-    if (!annotation) {
-      return;
-    }
-
-    if (Array.isArray(annotation)) {
-      annotations.push(...annotation);
-    } else {
-      annotations.push(annotation);
-    }
-  });
-  return annotations;
-};
-
-export const annotationExportsFromNode = (
-  ctx: ExporterContext,
-): Annotation[] => {
-  const { node, root } = ctx;
-  const annotations = [
-    ...parameterAnnotationFromNode(ctx),
-    ...markAnnotationFromNode(ctx),
-  ];
-
-  const blockAnnotation = EXPORTERS[node.type.name as AnnotationType]?.(ctx);
-
-  // NOTE: passages often have a root paragraph node that does not map to an
-  // annotation. Ignore nodes without a uuid.
-  if (!node.attrs.uuid) {
-    if (blockAnnotation) {
-      console.warn(
-        `Node "${node.type.name}" is missing a uuid — its annotation was skipped. ` +
-          'This is likely a timing issue where ensureUuids() was not called before export.',
-      );
-    }
-  } else if (blockAnnotation) {
-    if (Array.isArray(blockAnnotation)) {
-      annotations.push(...blockAnnotation);
-    } else {
-      annotations.push(blockAnnotation);
-    }
-  }
-
-  node.content.forEach((child) => {
-    const start = findNodePosition(root, child.attrs.uuid, child.type.name);
-    if (start === undefined) {
-      return nodeNotFound(child);
-    }
-    annotations.push(
-      ...annotationExportsFromNode({
-        ...ctx,
-        node: child,
-        parent: node,
-        start,
-      }),
-    );
-  });
-  return annotations;
-};

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

@@ -1,77 +0,0 @@
-import type { Node } from '@tiptap/pm/model';
-import { audio } from './audio';
-
-describe('audio exporter', () => {
-  it('should export audio annotation correctly', () => {
-    const node = {
-      attrs: {
-        uuid: 'audio-uuid-1234',
-        src: '/audio/recitation.mp3',
-        mediaType: 'audio/mpeg',
-      },
-    } as unknown as Node;
-
-    const result = audio({
-      node,
-      parent: node,
-      root: node,
-      start: 50,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toEqual({
-      uuid: 'audio-uuid-1234',
-      passageUuid: 'passage-uuid-1234',
-      type: 'audio',
-      start: 50,
-      end: 50,
-      src: '/audio/recitation.mp3',
-      mediaType: 'audio/mpeg',
-    });
-  });
-
-  it('should default to audio/mpeg when mediaType is missing', () => {
-    const node = {
-      attrs: {
-        uuid: 'audio-uuid-5678',
-        src: '/audio/recitation.mp3',
-      },
-    } as unknown as Node;
-
-    const result = audio({
-      node,
-      parent: node,
-      root: node,
-      start: 0,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toEqual({
-      uuid: 'audio-uuid-5678',
-      passageUuid: 'passage-uuid-1234',
-      type: 'audio',
-      start: 0,
-      end: 0,
-      src: '/audio/recitation.mp3',
-      mediaType: 'audio/mpeg',
-    });
-  });
-
-  it('should return undefined when src is missing', () => {
-    const node = {
-      attrs: {
-        uuid: 'audio-uuid-nosrc',
-      },
-    } as unknown as Node;
-
-    const result = audio({
-      node,
-      parent: node,
-      root: node,
-      start: 0,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toBeUndefined();
-  });
-});

package/src/lib/exporters/audio.ts

@@ -1,27 +0,0 @@
-import { AudioAnnotation } from '@eightyfourthousand/data-access';
-import { Exporter } from './export';
-
-export const audio: Exporter<AudioAnnotation> = ({
-  node,
-  start,
-  passageUuid,
-}): AudioAnnotation | undefined => {
-  const uuid = node.attrs.uuid;
-  const src = node.attrs.src;
-  const mediaType = node.attrs.mediaType || 'audio/mpeg';
-
-  if (!src) {
-    console.warn(`Audio node ${uuid} is missing src attribute`);
-    return undefined;
-  }
-
-  return {
-    uuid,
-    passageUuid,
-    type: 'audio',
-    start,
-    end: start,
-    src,
-    mediaType,
-  };
-};

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

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

package/src/lib/exporters/blockquote.ts

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

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

@@ -1,93 +0,0 @@
-import type { Node, Mark } from '@tiptap/pm/model';
-import { code } from './code';
-
-describe('code exporter', () => {
-  it('should export code annotation correctly', () => {
-    const node = {
-      textContent: 'const x = 1;',
-    } as unknown as Node;
-
-    const mark = {
-      attrs: {
-        uuid: 'code-uuid-1234',
-      },
-    } as unknown as Mark;
-
-    const result = code({
-      node,
-      mark,
-      parent: node,
-      root: node,
-      start: 0,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toEqual({
-      uuid: 'code-uuid-1234',
-      passageUuid: 'passage-uuid-1234',
-      type: 'code',
-      start: 0,
-      end: 12,
-    });
-  });
-
-  it('should use parent textContent when node textContent is missing', () => {
-    const parent = {
-      textContent: 'function test()',
-    } as unknown as Node;
-
-    const node = {
-      textContent: '',
-    } as unknown as Node;
-
-    const mark = {
-      attrs: {
-        uuid: 'code-uuid-5678',
-      },
-    } as unknown as Mark;
-
-    const result = code({
-      node,
-      mark,
-      parent,
-      root: parent,
-      start: 0,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toEqual({
-      uuid: 'code-uuid-5678',
-      passageUuid: 'passage-uuid-1234',
-      type: 'code',
-      start: 0,
-      end: 15,
-    });
-  });
-
-  it('should return undefined when textContent is missing', () => {
-    const node = {
-      textContent: '',
-    } as unknown as Node;
-
-    const parent = {
-      textContent: '',
-    } as unknown as Node;
-
-    const mark = {
-      attrs: {
-        uuid: 'code-uuid-empty',
-      },
-    } as unknown as Mark;
-
-    const result = code({
-      node,
-      mark,
-      parent,
-      root: parent,
-      start: 0,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toBeUndefined();
-  });
-});

package/src/lib/exporters/code.ts

@@ -1,26 +0,0 @@
-import { CodeAnnotation } from '@eightyfourthousand/data-access';
-import { Exporter } from './export';
-
-export const code: Exporter<CodeAnnotation> = ({
-  node,
-  mark,
-  parent,
-  start,
-  passageUuid,
-}): CodeAnnotation | undefined => {
-  const textContent = node.textContent || parent.textContent || '';
-  const uuid = mark?.attrs.uuid;
-
-  if (!textContent || !uuid) {
-    console.warn(`Code node ${uuid} is missing body text or uuid`);
-    return undefined;
-  }
-
-  return {
-    uuid,
-    type: 'code',
-    passageUuid,
-    start,
-    end: start + textContent.length,
-  };
-};

package/src/lib/exporters/end-note-link.spec.ts

@@ -1,104 +0,0 @@
-import type { Node, Mark } from '@tiptap/pm/model';
-import { endNoteLink } from './end-note-link';
-
-describe('endNoteLink exporter', () => {
-  it('should export endNoteLink annotations correctly', () => {
-    const node = {
-      textContent: 'text',
-    } as unknown as Node;
-
-    const mark = {
-      attrs: {
-        notes: [
-          {
-            uuid: 'note-uuid-1',
-            endNote: 'endnote-uuid-1',
-          },
-          {
-            uuid: 'note-uuid-2',
-            endNote: 'endnote-uuid-2',
-          },
-        ],
-      },
-    } as unknown as Mark;
-
-    const result = endNoteLink({
-      node,
-      mark,
-      parent: node,
-      root: node,
-      start: 10,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toEqual([
-      {
-        uuid: 'note-uuid-1',
-        passageUuid: 'passage-uuid-1234',
-        type: 'endNoteLink',
-        start: 14,
-        end: 14,
-        endNote: 'endnote-uuid-1',
-      },
-      {
-        uuid: 'note-uuid-2',
-        passageUuid: 'passage-uuid-1234',
-        type: 'endNoteLink',
-        start: 14,
-        end: 14,
-        endNote: 'endnote-uuid-2',
-      },
-    ]);
-  });
-
-  it('should return empty array when textContent is missing', () => {
-    const node = {
-      textContent: '',
-    } as unknown as Node;
-
-    const mark = {
-      attrs: {
-        notes: [
-          {
-            uuid: 'note-uuid-1',
-            endNote: 'endnote-uuid-1',
-          },
-        ],
-      },
-    } as unknown as Mark;
-
-    const result = endNoteLink({
-      node,
-      mark,
-      parent: node,
-      root: node,
-      start: 0,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toEqual([]);
-  });
-
-  it('should return empty array when notes are missing', () => {
-    const node = {
-      textContent: 'text',
-    } as unknown as Node;
-
-    const mark = {
-      attrs: {
-        notes: [],
-      },
-    } as unknown as Mark;
-
-    const result = endNoteLink({
-      node,
-      mark,
-      parent: node,
-      root: node,
-      start: 0,
-      passageUuid: 'passage-uuid-1234',
-    });
-
-    expect(result).toEqual([]);
-  });
-});

package/src/lib/exporters/end-note-link.ts

@@ -1,35 +0,0 @@
-import { EndNoteLinkAnnotation } from '@eightyfourthousand/data-access';
-import { Exporter } from './export';
-
-export const endNoteLink: Exporter<EndNoteLinkAnnotation[]> = ({
-  mark,
-  node,
-  start,
-  passageUuid,
-}): EndNoteLinkAnnotation[] => {
-  const textContent = node.textContent;
-  const notes = mark?.attrs.notes || [];
-
-  if (!textContent || notes.length === 0) {
-    console.warn(`Endnote link instance on passage ${passageUuid} incomplete`);
-    return [];
-  }
-
-  const end = start + textContent.length;
-  const annotations: EndNoteLinkAnnotation[] = notes.map(
-    (note: { uuid: string; endNote: string }) => {
-      const { uuid, endNote } = note;
-      return {
-        uuid,
-        type: 'endNoteLink',
-        passageUuid,
-        // end note links are 0-length annotations
-        start: end,
-        end,
-        endNote,
-      };
-    },
-  );
-
-  return annotations;
-};

package/src/lib/exporters/export.ts

@@ -1,12 +0,0 @@
-import type { Node, Mark } from '@tiptap/pm/model';
-
-export type ExporterContext = {
-  passageUuid: string;
-  node: Node;
-  parent: Node;
-  root: Node;
-  start: number;
-  mark?: Mark;
-};
-
-export type Exporter<T> = (ctx: ExporterContext) => T | undefined;