@eightyfourthousand/lib-editing 2026.3.0

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

@@ -0,0 +1,52 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { code } from './code';
+import { blockFromPassage } from '../block';
+import { findTextNodeWithMarks } from './recurse';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'Some code text here',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 14,
+      type: 'code',
+      uuid: 'code-uuid-1',
+      start: 5,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('code 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 code annotation correctly', () => {
+    const textNode = findTextNodeWithMarks(block);
+    expect(textNode).toBeDefined();
+    expect(textNode?.type).toBe('text');
+    expect(textNode?.marks).toBeDefined();
+    const codeMark = textNode?.marks?.find((m: any) => m.type === 'code');
+    expect(codeMark).toBeDefined();
+    expect(textNode?.text).toBe('code text');
+  });
+});

package/src/lib/transformers/code.ts

@@ -0,0 +1,22 @@
+import type { Transformer } from './transformer';
+import { splitContent } from './split-content';
+import { recurse } from './recurse';
+
+export const code: Transformer = (ctx) => {
+  recurse({
+    ...ctx,
+    until: ['text'],
+    transform: (ctx) =>
+      splitContent({
+        ...ctx,
+        transform: ({ block }) => {
+          block.marks = [
+            ...(block.marks || []),
+            {
+              type: 'code',
+            },
+          ];
+        },
+      }),
+  });
+};

package/src/lib/transformers/deprecated.ts

@@ -0,0 +1,7 @@
+import { Transformer } from './transformer';
+
+export const deprecated: Transformer = ({ block, annotation }) => {
+  console.warn(
+    `Deprecated annotation type ${annotation.type} in block ${block.uuid}`,
+  );
+};

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

@@ -0,0 +1,56 @@
+import { annotationsFromDTO, PassageDTO, passageFromDTO } from '@eightyfourthousand/data-access';
+import { blockFromPassage } from '../block';
+import { findTextNodeWithMarks } from './recurse';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'Some text',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 9,
+      type: 'end-note-link',
+      uuid: 'endnote-link-uuid-1',
+      start: 9,
+      content: [
+        {
+          uuid: 'endnote-uuid-1',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('endNoteLink 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 endNoteLink annotation correctly', () => {
+    // Transformers are applied automatically in blockFromPassage
+    const textNode = findTextNodeWithMarks(block);
+    expect(textNode).toBeDefined();
+    expect(textNode?.type).toBe('text');
+    expect(textNode?.marks).toBeDefined();
+    const endnoteMark = textNode?.marks?.find(
+      (m: any) => m.type === 'endNoteLink',
+    );
+    expect(endnoteMark).toBeDefined();
+    expect(endnoteMark?.attrs?.notes).toBeDefined();
+    expect(endnoteMark?.attrs?.notes?.length).toBe(1);
+    expect(endnoteMark?.attrs?.notes?.[0].endNote).toBe('endnote-uuid-1');
+    expect(endnoteMark?.attrs?.notes?.[0].uuid).toBe('endnote-link-uuid-1');
+  });
+});

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

@@ -0,0 +1,76 @@
+import { EndNoteLinkAnnotation } from '@eightyfourthousand/data-access';
+import { Transformer } from './transformer';
+import { recurse } from './recurse';
+import { splitContentAt } from './split-at';
+import { splitContent } from './split-content';
+
+const innerTransform: Transformer = ({ block, annotation }) => {
+  const { endNote, label, uuid, start, end, toh } =
+    annotation as EndNoteLinkAnnotation;
+  let endnoteMark = block.marks?.find((m) => m.type === 'endNoteLink');
+  const marks = block.marks || [];
+  const notes = endnoteMark?.attrs?.notes || [];
+  notes.push({
+    endNote,
+    label,
+    uuid,
+    start,
+    end,
+    location: end === 0 ? 'start' : 'end',
+    toh,
+  });
+
+  if (endnoteMark) {
+    endnoteMark.attrs = endnoteMark.attrs || {};
+    endnoteMark.attrs.notes = notes;
+  } else {
+    endnoteMark = {
+      type: 'endNoteLink',
+      attrs: {
+        notes,
+      },
+    };
+    marks.push(endnoteMark);
+  }
+
+  block.marks = [...marks];
+};
+
+export const endNoteLink: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const { endNote, uuid, end } = annotation as EndNoteLinkAnnotation;
+
+  if (!endNote) {
+    console.warn(`End note link ${uuid} is missing end note reference`);
+    return;
+  }
+
+  const isStart = end === 0;
+
+  recurse({
+    ...ctx,
+    until: ['text'],
+    transform: (ctx) => {
+      if (isStart) {
+        splitContent({
+          ...ctx,
+          annotation: {
+            ...annotation,
+            end: 1,
+          },
+          transform: ({ block }) => {
+            innerTransform({ ...ctx, block });
+          },
+        });
+        return;
+      }
+
+      splitContentAt({
+        ...ctx,
+        transform: ({ block }) => {
+          innerTransform({ ...ctx, block });
+        },
+      });
+    },
+  });
+};

package/src/lib/transformers/glossary-instance.spec.ts

@@ -0,0 +1,55 @@
+import { annotationsFromDTO, PassageDTO, passageFromDTO } from '@eightyfourthousand/data-access';
+import { blockFromPassage } from '../block';
+import { findTextNodeWithMarks } from './recurse';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'The Buddha taught the Dharma.',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 10,
+      type: 'glossary-instance',
+      uuid: 'glossary-instance-uuid-1',
+      start: 4,
+      content: [
+        {
+          uuid: 'glossary-entry-uuid-1',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('glossaryInstance 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 glossaryInstance annotation correctly', () => {
+    // Transformers are applied automatically in blockFromPassage
+    const textNode = findTextNodeWithMarks(block);
+    expect(textNode).toBeDefined();
+    expect(textNode?.type).toBe('text');
+    expect(textNode?.marks).toBeDefined();
+    const glossaryMark = textNode?.marks?.find(
+      (m: any) => m.type === 'glossaryInstance',
+    );
+    expect(glossaryMark).toBeDefined();
+    expect(glossaryMark?.attrs?.glossary).toBe('glossary-entry-uuid-1');
+    expect(glossaryMark?.attrs?.uuid).toBe('glossary-instance-uuid-1');
+    expect(textNode?.text).toBe('Buddha');
+  });
+});

package/src/lib/transformers/glossary-instance.ts

@@ -0,0 +1,40 @@
+import { GlossaryInstanceAnnotation } from '@eightyfourthousand/data-access';
+import { Transformer } from './transformer';
+import { recurse } from './recurse';
+import { splitContent } from './split-content';
+
+export const glossaryInstance: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const { uuid, glossary, authority, toh } = annotation as GlossaryInstanceAnnotation;
+
+  if (!glossary) {
+    console.warn(`Glossary instance ${uuid} is missing glossary UUID`);
+
+    return;
+  }
+
+  recurse({
+    ...ctx,
+    until: ['text'],
+    transform: (ctx) => {
+      splitContent({
+        ...ctx,
+        transform: (ctx) => {
+          const { block } = ctx;
+          block.marks = [
+            ...(block.marks || []),
+            {
+              type: 'glossaryInstance',
+              attrs: {
+                authority,
+                glossary,
+                uuid,
+                toh,
+              },
+            },
+          ];
+        },
+      });
+    },
+  });
+};

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

@@ -0,0 +1,50 @@
+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: 'The 84000 project translates Tibetan texts.',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 10,
+      type: 'has-abbreviation',
+      uuid: 'has-abbr-uuid-1',
+      start: 4,
+      content: [
+        {
+          uuid: 'abbr-uuid-1',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('hasAbbreviation 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 hasAbbreviation annotation correctly', () => {
+    const hasAbbrNode = recurseForType({ block, until: 'hasAbbreviation' });
+    expect(hasAbbrNode).toBeDefined();
+    expect(hasAbbrNode?.type).toBe('hasAbbreviation');
+    expect(hasAbbrNode?.attrs?.abbreviation).toBe('abbr-uuid-1');
+    expect(hasAbbrNode?.attrs?.uuid).toBe('has-abbr-uuid-1');
+    expect(hasAbbrNode?.content?.[0]?.type).toBe('text');
+    expect(hasAbbrNode?.content?.[0]?.text).toBe('84000 ');
+  });
+});

package/src/lib/transformers/has-abbreviation.ts

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

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

@@ -0,0 +1,62 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { heading } from './heading';
+import { blockFromPassage } from '../block';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'Chapter Title',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 13,
+      type: 'heading',
+      uuid: 'heading-uuid-1',
+      start: 0,
+      content: [
+        {
+          'heading-level': 'h2',
+        },
+        {
+          'heading-type': 'chapter-title',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('heading 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 heading annotation correctly', () => {
+    // The heading transformer should have already been applied during blockFromPassage
+    // The annotation is applied to the paragraph block inside the passage block
+    expect(block.content).toBeDefined();
+    expect(block.content?.length).toBeGreaterThan(0);
+
+    const paragraphBlock = block.content?.[0];
+    expect(paragraphBlock).toBeDefined();
+    expect(paragraphBlock?.type).toBe('heading');
+    expect(paragraphBlock?.attrs).toBeDefined();
+    expect(paragraphBlock?.attrs?.level).toBe(2);
+    expect(paragraphBlock?.attrs?.class).toBe('chapter-title');
+  });
+});

package/src/lib/transformers/heading.ts

@@ -0,0 +1,30 @@
+import { HeadingAnnotation } from '@eightyfourthousand/data-access';
+import { splitBlock } from './split-block';
+import { Transformer } from './transformer';
+import { recurse } from './recurse';
+
+export const heading: Transformer = ({ root, parent, block, annotation }) => {
+  const heading = annotation as HeadingAnnotation;
+  const level = heading.level || 3;
+  const cls = heading.class;
+
+  recurse({
+    until: ['heading', 'paragraph'],
+    root,
+    parent,
+    block,
+    annotation,
+    transform: (ctx) =>
+      splitBlock({
+        ...ctx,
+        transform: ({ block: item }) => {
+          item.type = 'heading';
+          item.attrs = {
+            ...item.attrs,
+            level,
+            class: cls,
+          };
+        },
+      }),
+  });
+};

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

@@ -0,0 +1,51 @@
+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: 'See the diagram below.',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 3,
+      type: 'image',
+      uuid: 'image-uuid-1',
+      start: 3,
+      content: [
+        {
+          src: 'https://example.com/image.jpg',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('image 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 image annotation correctly', () => {
+    const imageNode = recurseForType({
+      until: 'image',
+      block,
+    });
+    expect(imageNode).toBeDefined();
+    expect(imageNode?.type).toBe('image');
+    expect(imageNode?.attrs?.src).toBe('https://example.com/image.jpg');
+    expect(imageNode?.attrs?.uuid).toBe('image-uuid-1');
+  });
+});

package/src/lib/transformers/image.ts

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

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

@@ -0,0 +1,53 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { indent } from './indent';
+import { blockFromPassage } from '../block';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'Indented paragraph text',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 23,
+      type: 'indent',
+      uuid: 'indent-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('indent 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 indent annotation correctly', () => {
+    // The indent annotation is applied to the paragraph block inside the passage block
+    expect(block.content).toBeDefined();
+    expect(block.content?.length).toBeGreaterThan(0);
+
+    const paragraphBlock = block.content?.[0];
+    expect(paragraphBlock).toBeDefined();
+    expect(paragraphBlock?.attrs).toBeDefined();
+    expect(paragraphBlock?.attrs?.hasIndent).toBe(true);
+    expect(paragraphBlock?.attrs?.indentUuid).toBe('indent-uuid-1');
+  });
+});

package/src/lib/transformers/indent.ts

@@ -0,0 +1,17 @@
+import { recurse } from './recurse';
+import { Transformer } from './transformer';
+
+export const indent: Transformer = (ctx) => {
+  const indentUuid = ctx.annotation.uuid;
+  recurse({
+    ...ctx,
+    until: ['paragraph', 'lineGroup', 'list', 'blockquote'],
+    transform: ({ block }) => {
+      block.attrs = {
+        ...block.attrs,
+        hasIndent: true,
+        indentUuid,
+      };
+    },
+  });
+};

package/src/lib/transformers/index.ts

@@ -0,0 +1,33 @@
+export * from './abbreviation';
+export * from './audio';
+export * from './blockquote';
+export * from './code';
+export * from './deprecated';
+export * from './end-note-link';
+export * from './glossary-instance';
+export * from './has-abbreviation';
+export * from './heading';
+export * from './image';
+export * from './indent';
+export * from './inline-title';
+export * from './internal-link';
+export * from './leading-space';
+export * from './line-group';
+export * from './line';
+export * from './link';
+export * from './list-item';
+export * from './list';
+export * from './mantra';
+export * from './mention';
+export * from './paragraph';
+export * from './quote';
+export * from './quoted';
+export * from './reference';
+export * from './span';
+export * from './table';
+export * from './table-body-data';
+export * from './table-body-header';
+export * from './table-body-row';
+export * from './trailer';
+export * from './unknown';
+export * from './transformer';