@eightyfourthousand/lib-editing 2026.3.0

package/src/lib/transformers/inline-title.spec.ts

@@ -0,0 +1,59 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { inlineTitle } from './inline-title';
+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 Dhammapada is a collection of sayings',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 14,
+      type: 'inline-title',
+      uuid: 'inline-title-uuid-1',
+      start: 4,
+      content: [
+        {
+          lang: 'Sa-Ltn',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('inlineTitle 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 inlineTitle annotation correctly', () => {
+    const textNode = findTextNodeWithMarks(block);
+    expect(textNode).toBeDefined();
+    expect(textNode?.type).toBe('text');
+    expect(textNode?.marks).toBeDefined();
+    const italicMark = textNode?.marks?.find((m: any) => m.type === 'italic');
+    expect(italicMark).toBeDefined();
+    expect(italicMark?.attrs?.uuid).toBe('inline-title-uuid-1');
+    expect(italicMark?.attrs?.lang).toBe('Sa-Ltn');
+    expect(italicMark?.attrs?.type).toBe('inlineTitle');
+    expect(textNode?.text).toBe('Dhammapada');
+  });
+});

package/src/lib/transformers/inline-title.ts

@@ -0,0 +1,34 @@
+import { InlineTitleAnnotation } from '@eightyfourthousand/data-access';
+import { Transformer } from './transformer';
+import { splitContent } from './split-content';
+import { ITALIC_LANGUAGES } from './annotate';
+import { recurse } from './recurse';
+
+export const inlineTitle: Transformer = (ctx) => {
+  const { annotation } = ctx;
+
+  const { lang, uuid } = annotation as InlineTitleAnnotation;
+  if (!lang) {
+    return;
+  }
+
+  const markType = ITALIC_LANGUAGES.includes(lang) ? 'italic' : undefined;
+  if (!markType) {
+    return;
+  }
+
+  recurse({
+    ...ctx,
+    until: ['text'],
+    transform: (ctx) =>
+      splitContent({
+        ...ctx,
+        transform: ({ block }) => {
+          block.marks = [
+            ...(block.marks || []),
+            { type: markType, attrs: { uuid, lang, type: 'inlineTitle' } },
+          ];
+        },
+      }),
+  });
+};

package/src/lib/transformers/internal-link.spec.ts

@@ -0,0 +1,67 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { internalLink } from './internal-link';
+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: 'See the glossary entry',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 22,
+      type: 'internal-link',
+      uuid: 'internal-link-uuid-1',
+      start: 8,
+      content: [
+        {
+          type: 'glossary',
+        },
+        {
+          uuid: 'glossary-entity-uuid',
+        },
+        {
+          href: '#glossary-entry',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('internalLink 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 internalLink annotation correctly', () => {
+    const textNode = findTextNodeWithMarks(block);
+    expect(textNode).toBeDefined();
+    expect(textNode?.type).toBe('text');
+    expect(textNode?.marks).toBeDefined();
+    const internalLinkMark = textNode?.marks?.find(
+      (m: any) => m.type === 'internalLink',
+    );
+    expect(internalLinkMark).toBeDefined();
+    expect(internalLinkMark?.attrs?.uuid).toBe('internal-link-uuid-1');
+    expect(internalLinkMark?.attrs?.type).toBe('glossary');
+    expect(internalLinkMark?.attrs?.entity).toBe('glossary-entity-uuid');
+    expect(textNode?.text).toBe('glossary entry');
+  });
+});

package/src/lib/transformers/internal-link.ts

@@ -0,0 +1,65 @@
+import { InternalLinkAnnotation } from '@eightyfourthousand/data-access';
+import { Transformer } from './transformer';
+import { splitContent } from './split-content';
+import { recurse } from './recurse';
+
+// NOTE: over time, internal links become just regular links.
+export const internalLink: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const {
+    uuid,
+    entity,
+    href = '#',
+    start,
+    end,
+    linkType: type,
+    toh,
+    isSameWork,
+    subtype,
+    linkToh,
+  } = annotation as InternalLinkAnnotation;
+
+  if (!(end - start)) {
+    // If the annotation has no length, we don't need to do anything.
+    console.warn(
+      `Skipping internal link transformation for annotation with no length`,
+      annotation,
+    );
+    return;
+  }
+
+  // NOTE: we use redirects to forward older urls. Hashes aren't passed to the
+  // api, so make an effort to convert them to query params.
+  let path = href.replace('#', '?xmlId=');
+
+  if (type && entity) {
+    path = `/entity/${type}/${entity}`;
+  }
+
+  recurse({
+    ...ctx,
+    until: ['text'],
+    transform: (ctx) =>
+      splitContent({
+        ...ctx,
+        transform: ({ block }) => {
+          block.marks = [
+            ...(block.marks || []),
+            {
+              type: 'internalLink',
+              attrs: {
+                uuid,
+                href: path,
+                entity,
+                type,
+                toh,
+                isSameWork,
+                subtype,
+                linkToh,
+              },
+            },
+          ];
+        },
+      }),
+  });
+};

package/src/lib/transformers/italic.ts

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

package/src/lib/transformers/leading-space.spec.ts

@@ -0,0 +1,55 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { leadingSpace } from './leading-space';
+import { blockFromPassage } from '../block';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'Paragraph text',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 0,
+      type: 'leading-space',
+      uuid: 'leading-space-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('leadingSpace 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 leadingSpace annotation correctly', () => {
+    // The leadingSpace 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?.hasLeadingSpace).toBe(true);
+    expect(paragraphBlock?.attrs?.leadingSpaceUuid).toBe(
+      'leading-space-uuid-1',
+    );
+  });
+});

package/src/lib/transformers/leading-space.ts

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

package/src/lib/transformers/line-group.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: 'A group of verse lines',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 22,
+      type: 'line-group',
+      uuid: 'linegroup-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('lineGroup 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 lineGroup annotation correctly', () => {
+    const lineGroupNode = recurseForType({
+      until: 'lineGroup',
+      block,
+    });
+    expect(lineGroupNode).toBeDefined();
+    expect(lineGroupNode?.type).toBe('lineGroup');
+    expect(lineGroupNode?.attrs?.uuid).toBe('linegroup-uuid-1');
+    expect(lineGroupNode?.content).toBeDefined();
+    expect(lineGroupNode?.content?.[0]?.type).toBe('line');
+  });
+});

package/src/lib/transformers/line-group.ts

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

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

@@ -0,0 +1,54 @@
+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: 'First line of verse.',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 20,
+      start: 0,
+      type: 'line-group',
+      uuid: 'line-group-uuid-1',
+      passage_uuid: 'passage-uuid-1234',
+      content: [],
+    },
+    {
+      end: 20,
+      type: 'line',
+      uuid: 'line-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('line 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 line annotation correctly', () => {
+    const lineNode = recurseForType({
+      until: 'line',
+      block,
+    });
+    expect(lineNode).toBeDefined();
+    expect(lineNode?.type).toBe('line');
+    expect(lineNode?.attrs?.uuid).toBe('line-uuid-1');
+  });
+});

package/src/lib/transformers/line.ts

@@ -0,0 +1,27 @@
+import { recurse } from './recurse';
+import { splitBlock } from './split-block';
+import { Transformer } from './transformer';
+
+export const line: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const { start, end, uuid } = annotation || {};
+
+  return recurse({
+    ...ctx,
+    until: ['line'],
+    transform: (ctx) => {
+      splitBlock({
+        ...ctx,
+        transform: ({ block }) => {
+          block.type = 'line';
+          block.attrs = {
+            ...block.attrs,
+            start,
+            end,
+            uuid,
+          };
+        },
+      });
+    },
+  });
+};

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

@@ -0,0 +1,61 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { link } from './link';
+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: 'Click here to learn more',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 10,
+      type: 'link',
+      uuid: 'link-uuid-1',
+      start: 6,
+      content: [
+        {
+          href: 'https://example.com',
+        },
+        {
+          'link-text': 'here',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('link 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 link annotation correctly', () => {
+    const textNode = findTextNodeWithMarks(block);
+    expect(textNode).toBeDefined();
+    expect(textNode?.type).toBe('text');
+    expect(textNode?.marks).toBeDefined();
+    const linkMark = textNode?.marks?.find((m: any) => m.type === 'link');
+    expect(linkMark).toBeDefined();
+    expect(linkMark?.attrs?.uuid).toBe('link-uuid-1');
+    expect(linkMark?.attrs?.href).toBe('https://example.com');
+    expect(textNode?.text).toBe('here');
+  });
+});

package/src/lib/transformers/link.ts

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

package/src/lib/transformers/list-item.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: 'Item in the list',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 16,
+      type: 'list-item',
+      uuid: 'listitem-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('listItem 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 listItem annotation correctly', () => {
+    const listItemNode = recurseForType({
+      until: 'listItem',
+      block,
+    });
+    expect(listItemNode).toBeDefined();
+    expect(listItemNode?.type).toBe('listItem');
+    expect(listItemNode?.attrs?.uuid).toBe('listitem-uuid-1');
+    expect(listItemNode?.content).toBeDefined();
+    expect(listItemNode?.content?.[0]?.type).toBe('paragraph');
+  });
+});

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

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