@eightyfourthousand/lib-editing 2026.3.0

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

@@ -0,0 +1,58 @@
+import { annotationsFromDTO, PassageDTO, passageFromDTO } from '@eightyfourthousand/data-access';
+import { blockFromPassage } from '../block';
+
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'First item in list',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 18,
+      type: 'list',
+      uuid: 'list-uuid-1',
+      start: 0,
+      content: [
+        {
+          nesting: '0',
+        },
+        {
+          'list-spacing': 'compact',
+        },
+        {
+          'list-item-style': 'bullet',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('list 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 list annotation correctly', () => {
+    // The list should be in block.content[0] and become a bulletList
+    const listNode = block.content?.[0];
+    expect(listNode).toBeDefined();
+    expect(listNode?.type).toBe('bulletList');
+    expect(listNode?.attrs?.uuid).toBe('list-uuid-1');
+    expect(listNode?.attrs?.nesting).toBe(0);
+    expect(listNode?.attrs?.spacing).toBe('compact');
+    expect(listNode?.attrs?.itemStyle).toBe('bullet');
+    expect(listNode?.content).toBeDefined();
+    expect(listNode?.content?.[0]?.type).toBe('paragraph');
+  });
+});

package/src/lib/transformers/list.ts

@@ -0,0 +1,42 @@
+import { ListAnnotation } from '@eightyfourthousand/data-access';
+import { recurse } from './recurse';
+import { splitBlock } from './split-block';
+import { Transformer } from './transformer';
+
+export const list: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const { start, end, uuid, nesting, spacing, itemStyle } =
+    (annotation as ListAnnotation) || {};
+
+  recurse({
+    ...ctx,
+    until: ['paragraph'],
+    transform: (ctx) =>
+      splitBlock({
+        ...ctx,
+        transform: ({ block }) => {
+          block.type = 'bulletList';
+          block.attrs = {
+            ...block.attrs,
+            nesting,
+            spacing,
+            itemStyle,
+            start,
+            end,
+            uuid,
+          };
+          block.content = [
+            {
+              type: 'paragraph',
+              content: block.content || [],
+              attrs: {
+                start,
+                end,
+                uuid,
+              },
+            },
+          ];
+        },
+      }),
+  });
+};

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

@@ -0,0 +1,58 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { mantra } from './mantra';
+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: 'oṃ maṇi padme hūṃ',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 17,
+      type: 'mantra',
+      uuid: 'mantra-uuid-1',
+      start: 0,
+      content: [
+        {
+          lang: 'Sa-Ltn',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('mantra 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 mantra annotation correctly', () => {
+    const textNode = findTextNodeWithMarks(block);
+    expect(textNode).toBeDefined();
+    expect(textNode?.type).toBe('text');
+    expect(textNode?.marks).toBeDefined();
+    const mantraMark = textNode?.marks?.find((m: any) => m.type === 'mantra');
+    expect(mantraMark).toBeDefined();
+    expect(mantraMark?.attrs?.uuid).toBe('mantra-uuid-1');
+    expect(mantraMark?.attrs?.lang).toBe('Sa-Ltn');
+    expect(textNode?.text).toBe('oṃ maṇi padme hūṃ');
+  });
+});

package/src/lib/transformers/mantra.ts

@@ -0,0 +1,28 @@
+import { MantraAnnotation } from '@eightyfourthousand/data-access';
+import { Transformer } from './transformer';
+import { splitContent } from './split-content';
+import { recurse } from './recurse';
+
+export const mantra: Transformer = (ctx) => {
+  const { annotation } = ctx;
+
+  const { lang, uuid } = annotation as MantraAnnotation;
+  if (!lang) {
+    return;
+  }
+
+  recurse({
+    ...ctx,
+    until: ['text'],
+    transform: (ctx) =>
+      splitContent({
+        ...ctx,
+        transform: ({ block: item }) => {
+          item.marks = [
+            ...(item.marks || []),
+            { type: 'mantra', attrs: { uuid, lang } },
+          ];
+        },
+      }),
+  });
+};

package/src/lib/transformers/mention.ts

@@ -0,0 +1,70 @@
+import { MentionAnnotation } from '@eightyfourthousand/data-access';
+import { Transformer } from './transformer';
+import { recurse } from './recurse';
+import { splitAndInsert } from './split-insert';
+
+export const mention: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const {
+    entity,
+    linkType,
+    text,
+    displayText,
+    uuid,
+    start,
+    end,
+    isSameWork,
+    subtype,
+    linkToh,
+  } = annotation as MentionAnnotation;
+
+  const item = {
+    uuid,
+    entity,
+    linkType,
+    text,
+    displayText,
+    isSameWork,
+    subtype,
+    linkToh,
+  };
+  recurse({
+    ...ctx,
+    until: ['text'],
+    transform: (ctx) => {
+      splitAndInsert({
+        ...ctx,
+        transform: ({ block, parent }) => {
+          if (!parent || !parent.content) {
+            console.warn(
+              'mention transform: transformer expects to find a parent block with content.',
+            );
+            return;
+          }
+
+          // Check if a mention Node already exists at this position for batching
+          const mention = parent.content.find(
+            (child) =>
+              child.type === 'mention' &&
+              child.attrs?.start === start &&
+              child.attrs?.end === end,
+          );
+
+          if (mention) {
+            const items = mention.attrs?.items || [];
+            items.push(item);
+            mention.attrs = { ...mention.attrs, items };
+            return;
+          }
+
+          block.type = 'mention';
+          block.attrs = {
+            start,
+            end,
+            items: [item],
+          };
+        },
+      });
+    },
+  });
+};

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

@@ -0,0 +1,46 @@
+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 the first paragraph.',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 28,
+      type: 'paragraph',
+      uuid: 'paragraph-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('paragraph 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 paragraph annotation correctly', () => {
+    const paragraphNode = recurseForType({
+      until: 'paragraph',
+      block,
+    });
+    expect(paragraphNode).toBeDefined();
+    expect(paragraphNode?.type).toBe('paragraph');
+    expect(paragraphNode?.attrs?.uuid).toBe('paragraph-uuid-1');
+  });
+});

package/src/lib/transformers/paragraph.ts

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

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

@@ -0,0 +1,42 @@
+import { annotationsFromDTO, PassageDTO, passageFromDTO } from '@eightyfourthousand/data-access';
+import { blockFromPassage } from '../block';
+
+// The quote transformer is a no-op (pass), so we just verify it doesn't break
+const dto: PassageDTO = {
+  sort: 1,
+  type: 'root',
+  uuid: 'passage-uuid-1234',
+  label: '',
+  xmlId: 'test-passage',
+  parent: 'test-parent',
+  content: 'Some quoted text',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 16,
+      type: 'quote',
+      uuid: 'quote-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('quote 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 not transform quote annotation (pass-through)', () => {
+    // quote is a pass-through transformer, so the block structure should remain unchanged
+    expect(block).toBeDefined();
+    expect(block.content).toBeDefined();
+  });
+});

package/src/lib/transformers/quote.ts

@@ -0,0 +1,3 @@
+import { pass } from './transformer';
+
+export const quote = pass;

package/src/lib/transformers/quoted.ts

@@ -0,0 +1,3 @@
+import { pass } from './transformer';
+
+export const quoted = pass;

package/src/lib/transformers/recurse.ts

@@ -0,0 +1,76 @@
+import { AnnotationType } from '@eightyfourthousand/data-access';
+import { TransformationContextWithCallback, Transformer } from './transformer';
+import { TranslationEditorContentItem } from '../components';
+
+export const recurse: Transformer = (ctx) => {
+  if (trasformOnMatch(ctx)) {
+    return;
+  }
+
+  const { block } = ctx;
+  for (const child of block.content || []) {
+    if (trasformOnMatch({ ...ctx, parent: block, block: child })) {
+      return;
+    }
+
+    recurse({
+      ...ctx,
+      parent: block,
+      block: child,
+    });
+  }
+};
+
+const trasformOnMatch = (ctx: TransformationContextWithCallback) => {
+  const { block, annotation, until = [], transform } = ctx;
+  const type = block.type || 'unknown';
+  if (
+    block.attrs?.uuid !== annotation.uuid &&
+    block.attrs?.start <= annotation.start &&
+    block.attrs?.end >= annotation.end &&
+    (!until.length || until.includes(type as AnnotationType))
+  ) {
+    transform?.(ctx);
+    return true;
+  }
+
+  return false;
+};
+
+export const recurseForType = ({
+  block,
+  until,
+}: {
+  block: TranslationEditorContentItem;
+  until: AnnotationType;
+}): TranslationEditorContentItem | undefined => {
+  if (block.type === until) {
+    return block;
+  }
+
+  for (const child of block.content || []) {
+    const val = recurseForType({ block: child, until });
+    if (val) {
+      return val;
+    }
+  }
+};
+
+/**
+ * Recursively searches a node tree to find the first text node that has marks applied.
+ * Used in tests to verify that mark transformers (span, code, link, etc.) are working correctly.
+ */
+export const findTextNodeWithMarks = (
+  node: TranslationEditorContentItem,
+): TranslationEditorContentItem | null => {
+  if (node.type === 'text' && node.marks && node.marks.length > 0) {
+    return node;
+  }
+  if (node.content) {
+    for (const child of node.content) {
+      const found = findTextNodeWithMarks(child);
+      if (found) return found;
+    }
+  }
+  return null;
+};

package/src/lib/transformers/reference.ts

@@ -0,0 +1,3 @@
+import { pass } from './transformer';
+
+export const reference = pass;

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

@@ -0,0 +1,68 @@
+import {
+  Annotation,
+  annotationsFromDTO,
+  PassageDTO,
+  passageFromDTO,
+} from '@eightyfourthousand/data-access';
+import { span } from './span';
+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 bold text here',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 14,
+      type: 'span',
+      uuid: 'span-uuid-1',
+      start: 5,
+      content: [
+        {
+          'text-style': 'text-bold',
+        },
+      ],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('span 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 span annotation correctly', () => {
+    const annotation = passage.annotations.find(
+      (a: Annotation) => a.type === 'span',
+    ) as Annotation;
+    span({
+      root: block,
+      parent: block,
+      block,
+      annotation,
+    });
+
+    const textNode = findTextNodeWithMarks(block);
+    expect(textNode).toBeDefined();
+    expect(textNode?.type).toBe('text');
+    expect(textNode?.marks).toBeDefined();
+    const boldMark = textNode?.marks?.find((m: any) => m.type === 'bold');
+    expect(boldMark).toBeDefined();
+    expect(boldMark?.attrs?.uuid).toBe('span-uuid-1');
+    expect(boldMark?.attrs?.textStyle).toBe('text-bold');
+    expect(textNode?.text).toBe('bold text');
+  });
+});

package/src/lib/transformers/span.ts

@@ -0,0 +1,78 @@
+import { ExtendedTranslationLanguage, SpanAnnotation } from '@eightyfourthousand/data-access';
+import type { Transformer } from './transformer';
+import { type SpanMarkType, MARK_TYPES } from '../types';
+import { splitContent } from './split-content';
+import { ITALIC_LANGUAGES } from './annotate';
+import { recurse } from './recurse';
+
+const MARK_TYPE_FOR_SPAN_TYPE: {
+  [key: string]: (
+    lang?: ExtendedTranslationLanguage,
+  ) => SpanMarkType | undefined;
+} = {
+  distinct: () => 'italic',
+  emphasis: () => 'italic',
+  foreign: (lang) => {
+    if (lang && ITALIC_LANGUAGES.includes(lang)) {
+      return 'italic';
+    }
+    return undefined;
+  },
+  'small-caps': () => 'smallCaps',
+  subscript: () => 'subscript',
+  superscript: () => 'superscript',
+  'text-bold': () => 'bold',
+  underline: () => 'underline',
+};
+
+export const span: Transformer = (ctx) => {
+  const { annotation } = ctx;
+  const { textStyle, lang, uuid, start, end } = annotation as SpanAnnotation;
+  if (!textStyle) {
+    return;
+  }
+
+  const markType = MARK_TYPES.includes(textStyle)
+    ? textStyle
+    : MARK_TYPE_FOR_SPAN_TYPE[textStyle]?.(lang);
+  if (!markType) {
+    return;
+  }
+
+  recurse({
+    ...ctx,
+    until: ['text', 'glossaryInstance'],
+    transform: (ctx) => {
+      splitContent({
+        ...ctx,
+        transform: ({ block }) => {
+          // If the block already has the mark, skip it becuase the editor
+          // doesn't like multiple marks of the same type on a single block.
+          if (block.marks?.some((m) => m.type === markType)) {
+            return;
+          }
+
+          block.attrs = {
+            ...block.attrs,
+            start,
+            end,
+          };
+
+          block.marks = [
+            ...(block.marks || []),
+            {
+              type: markType,
+              attrs: {
+                ...block.attrs,
+                uuid,
+                type: 'span',
+                lang,
+                textStyle,
+              },
+            },
+          ];
+        },
+      });
+    },
+  });
+};

package/src/lib/transformers/split-at.ts

@@ -0,0 +1,58 @@
+import { Transformer } from './transformer';
+import { splitNode } from './split-node';
+import type { TranslationEditorContentItem } from '../components/editor';
+
+export const sort = (nodes: TranslationEditorContentItem[]) => {
+  return nodes.sort((a, b) => (a.attrs?.start ?? 0) - (b.attrs?.start ?? 0));
+};
+
+export const insert = (
+  node: TranslationEditorContentItem,
+  nodes: TranslationEditorContentItem[],
+) => {
+  // unshift to prioritize new block when sorting
+  nodes.unshift(node);
+  return sort(nodes);
+};
+
+export const splitContentAt: Transformer = (ctx) => {
+  const { root, parent, annotation, transform } = ctx;
+  const { start, end } = annotation;
+
+  if (start !== end) {
+    console.warn(
+      'splitContentAt: transformer expects to find an annotation with zero-length (insertion point).',
+    );
+    return;
+  }
+
+  if (!parent || !parent.content) {
+    console.warn(
+      'splitContentAt: transformer expects to find a parent block with content.',
+    );
+    return;
+  }
+
+  const annotationEnd = end;
+  const currentContent = parent.content || [];
+  const newContent = [];
+
+  for (const item of currentContent) {
+    const { prefix, middle, suffix } = splitNode(item, start, end);
+
+    const lastPrefix = prefix.at(-1);
+    const firstSuffix = suffix[0];
+
+    if (annotationEnd === lastPrefix?.attrs?.end) {
+      transform?.({ root, parent, block: lastPrefix, annotation });
+    } else if (annotationEnd === firstSuffix?.attrs?.end) {
+      transform?.({ root, parent, block: firstSuffix, annotation });
+    }
+
+    newContent.push(...prefix);
+    newContent.push(...middle);
+    newContent.push(...suffix);
+  }
+
+  parent.content = newContent;
+};