@eightyfourthousand/lib-editing 2026.3.0

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

@@ -0,0 +1,110 @@
+import { AnnotationType } from '@eightyfourthousand/data-access';
+import { isBlockAnnotation } from './annotate';
+import { splitNode } from './split-node';
+import { Transformer } from './transformer';
+import { TranslationEditorContentItem } from '../components/editor';
+import { filterAttrs } from './util';
+
+export const splitBlock: Transformer = ({
+  root,
+  parent,
+  block,
+  annotation,
+  transform,
+}) => {
+  if (!isBlockAnnotation((block.type || 'unknown') as AnnotationType)) {
+    console.warn(
+      `splitBlock transformer expects to find a block annotation, but found: ${block?.type}`,
+    );
+    return;
+  }
+
+  if (!parent?.content?.length) {
+    console.warn(
+      'splitBlock transformer expects to find a parent block for the block.',
+    );
+    return;
+  }
+
+  const blockIndex = parent.content.findIndex(
+    (item) => item.attrs?.uuid === block.attrs?.uuid,
+  );
+
+  if (blockIndex === -1) {
+    console.warn(
+      'splitBlock transformer expects to find the block in its parent.',
+    );
+    return;
+  }
+
+  const annStart = annotation?.start ?? 0;
+  const annEnd = annotation?.end ?? 0;
+
+  if (annStart === annEnd) {
+    console.warn(
+      'splitBlock transformer expects to find an annotation with non-zero length.',
+    );
+    return;
+  }
+
+  const currentContent = block.content || [];
+  const prefixContent: typeof currentContent = [];
+  const midContent: typeof currentContent = [];
+  const suffixContent: typeof currentContent = [];
+
+  for (const item of currentContent) {
+    const { prefix, middle, suffix } = splitNode(item, annStart, annEnd);
+    prefixContent.push(...prefix);
+    midContent.push(...middle);
+    suffixContent.push(...suffix);
+  }
+
+  const attrs = filterAttrs(block.attrs);
+  const newBlocks: TranslationEditorContentItem[] = [];
+  if (prefixContent.length) {
+    newBlocks.push({
+      ...block,
+      content: prefixContent,
+      attrs: {
+        ...attrs,
+        start: prefixContent[0].attrs?.start ?? 0,
+        end: prefixContent[prefixContent.length - 1].attrs?.end ?? 0,
+      },
+    });
+  }
+
+  if (midContent.length) {
+    const newBlock: TranslationEditorContentItem = {
+      ...block,
+      type: annotation.type,
+      content: midContent,
+      attrs: {
+        ...attrs,
+        start: midContent[0].attrs?.start ?? annStart,
+        end: midContent[midContent.length - 1].attrs?.end ?? annEnd,
+        uuid: annotation.uuid,
+      },
+    };
+    transform?.({
+      root,
+      parent,
+      block: newBlock,
+      annotation,
+    });
+    newBlocks.push(newBlock);
+  }
+
+  if (suffixContent.length) {
+    newBlocks.push({
+      ...block,
+      content: suffixContent,
+      attrs: {
+        ...attrs,
+        start: suffixContent[0].attrs?.start ?? 0,
+        end: suffixContent[suffixContent.length - 1].attrs?.end ?? 0,
+      },
+    });
+  }
+
+  parent.content.splice(blockIndex, 1, ...newBlocks);
+};

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

@@ -0,0 +1,67 @@
+import { AnnotationType } from '@eightyfourthousand/data-access';
+import { isInlineAnnotation } from './annotate';
+import { Transformer } from './transformer';
+import { splitNode } from './split-node';
+import type { TranslationEditorContentItem } from '../components/editor';
+import { filterAttrs } from './util';
+
+export const splitContent: Transformer = ({
+  root,
+  parent,
+  block,
+  annotation,
+  transform,
+}) => {
+  if (!isInlineAnnotation(block.type as AnnotationType)) {
+    console.warn(
+      `splitContent: block type expects to find an inline annotation, but found: ${block.type}.`,
+    );
+    return;
+  }
+
+  if (!parent || !parent.content) {
+    console.warn(
+      'splitContent: transformer expects to find a parent block with content.',
+    );
+    return;
+  }
+
+  const annStartAbs = annotation.start;
+  const annEndAbs = annotation.end;
+  const currentContent = parent.content || [];
+  const newContent = [];
+  const attrs = filterAttrs(block.attrs);
+
+  for (const item of currentContent) {
+    const { prefix, middle, suffix } = splitNode(item, annStartAbs, annEndAbs);
+
+    newContent.push(...prefix);
+    // Only transform the middle segments
+    for (const midItem of middle) {
+      transform?.({
+        root,
+        parent,
+        block: midItem,
+        annotation,
+      });
+      newContent.push(midItem);
+    }
+    newContent.push(...suffix);
+  }
+
+  if (annStartAbs === annEndAbs && annStartAbs === attrs?.end) {
+    const newBlock: TranslationEditorContentItem = {
+      type: annotation.type,
+      attrs: {
+        ...attrs,
+        start: annStartAbs,
+        end: annEndAbs,
+      },
+    };
+    transform?.({ root, parent, block: newBlock, annotation });
+    newContent.push(newBlock);
+  }
+
+  newContent.sort((a, b) => (a.attrs?.start ?? 0) - (b.attrs?.start ?? 0));
+  parent.content = newContent;
+};

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

@@ -0,0 +1,76 @@
+import { Transformer } from './transformer';
+import { splitNode } from './split-node';
+import type { TranslationEditorContentItem } from '../components/editor';
+import { filterAttrs } from './util';
+
+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 splitAndInsert: Transformer = (ctx) => {
+  const { root, parent, block, annotation, transform } = ctx;
+  const { start, end } = annotation;
+
+  if (start !== end) {
+    console.warn(
+      'splitAndInsert: transformer expects to find an annotation with zero-length (insertion point).',
+    );
+    return;
+  }
+
+  if (!parent || !parent.content) {
+    console.warn(
+      'splitAndInsert: transformer expects to find a parent block with content.',
+    );
+    return;
+  }
+
+  const newBlock: TranslationEditorContentItem = {
+    type: annotation.type,
+    attrs: {
+      ...filterAttrs(block.attrs),
+      start,
+      end,
+    },
+  };
+  transform?.({ root, parent, block: newBlock, annotation });
+
+  if (start <= block.attrs?.start || start >= block.attrs?.end) {
+    parent.content = insert(newBlock, parent.content || []);
+    return;
+  }
+
+  const currentContent = parent.content || [];
+  const newContent = [];
+
+  let wasInserted = false;
+  for (const item of currentContent) {
+    const { prefix, middle, suffix } = splitNode(item, start, end);
+
+    newContent.push(...prefix);
+    for (const midItem of middle) {
+      newContent.push(midItem);
+      if (!wasInserted && midItem.attrs?.end === start) {
+        newContent.push(newBlock);
+        wasInserted = true;
+      }
+    }
+
+    if (!wasInserted) {
+      newContent.push(newBlock);
+      wasInserted = true;
+    }
+    newContent.push(...suffix);
+  }
+
+  parent.content = sort(newContent);
+};

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

@@ -0,0 +1,42 @@
+export type TranslationMark = {
+  type: string;
+  attrs?: {
+    start?: number;
+    end?: number;
+    [key: string]: unknown;
+  };
+};
+
+export const splitMarks = ({
+  marks,
+  start,
+  end,
+}: {
+  marks?: TranslationMark[];
+  start: number;
+  end: number;
+}) => {
+  if (!marks) {
+    return;
+  }
+
+  const nextMarks = marks
+    .filter(
+      (mark) =>
+        (mark.attrs?.end ?? 0) <= end && (mark.attrs?.start ?? 0) <= end,
+    )
+    .map((mark) => {
+      const markStart = Math.max(mark.attrs?.start ?? 0, start);
+      const markEnd = Math.min(mark.attrs?.end ?? 0, end);
+      return {
+        ...mark,
+        attrs: {
+          ...mark.attrs,
+          start: markStart,
+          end: markEnd,
+        },
+      };
+    });
+
+  return nextMarks;
+};

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

@@ -0,0 +1,138 @@
+import type { TranslationEditorContentItem } from '../components/editor';
+import { splitMarks } from './split-marks';
+import { filterAttrs } from './util';
+
+type SplitBlock = {
+  prefix: TranslationEditorContentItem[];
+  middle: TranslationEditorContentItem[];
+  suffix: TranslationEditorContentItem[];
+};
+
+/**
+ * Splits a node (text or block) by an absolute annotation range.
+ * Returns an object with arrays: prefix, middle, suffix.
+ * Each array contains 0 or more items.
+ * All returned nodes have correct absolute start/end.
+ */
+export function splitNode(
+  item: TranslationEditorContentItem,
+  rangeStart: number,
+  rangeEnd: number,
+): SplitBlock {
+  const itemStart = item.attrs?.start ?? 0;
+  const text = item.text ?? '';
+  const itemEnd =
+    typeof item.text === 'string'
+      ? itemStart + text.length
+      : (item.attrs?.end ?? itemStart);
+
+  if (itemEnd <= rangeStart) {
+    return { prefix: [item], middle: [], suffix: [] };
+  }
+
+  if (itemStart >= rangeEnd) {
+    return { prefix: [], middle: [], suffix: [item] };
+  }
+
+  const preLen = Math.max(rangeStart - itemStart, 0);
+  const midLen = Math.max(
+    Math.min(itemEnd, rangeEnd) - Math.max(itemStart, rangeStart),
+    0,
+  );
+  const postStartIdx = preLen + midLen;
+
+  const splits: SplitBlock = { prefix: [], middle: [], suffix: [] };
+  const attrs = filterAttrs(item.attrs);
+  const marks = item.marks ? [...item.marks] : undefined;
+
+  if (preLen > 0) {
+    const preText = text.slice(0, preLen);
+    if (preText) {
+      const prefixStart = itemStart;
+      const prefixEnd = prefixStart + preText.length;
+
+      const prefix = {
+        ...item,
+        text: preText,
+        attrs: {
+          ...attrs,
+          start: prefixStart,
+          end: prefixEnd,
+        },
+      };
+
+      const prefixMarks = splitMarks({
+        marks,
+        start: prefixStart,
+        end: prefixEnd,
+      });
+
+      if (prefixMarks?.length) {
+        prefix.marks = prefixMarks;
+      }
+
+      splits.prefix.push(prefix);
+    }
+  }
+
+  if (midLen > 0) {
+    const midText = text.slice(preLen, preLen + midLen);
+    if (midText) {
+      const midStart = itemStart + preLen;
+      const midEnd = midStart + midText.length;
+
+      const mid = {
+        ...item,
+        text: midText,
+        attrs: {
+          ...attrs,
+          start: midStart,
+          end: midEnd,
+        },
+      };
+
+      const midMarks = splitMarks({
+        marks,
+        start: midStart,
+        end: midEnd,
+      });
+
+      if (midMarks?.length) {
+        mid.marks = midMarks;
+      }
+
+      splits.middle.push(mid);
+    }
+  }
+
+  if (postStartIdx < text.length) {
+    const postText = text.slice(postStartIdx);
+    if (postText) {
+      const postStart = itemStart + postStartIdx;
+      const postEnd = postStart + postText.length;
+      const post = {
+        ...item,
+        text: postText,
+        attrs: {
+          ...attrs,
+          start: postStart,
+          end: postEnd,
+        },
+      };
+
+      const postMarks = splitMarks({
+        marks,
+        start: postStart,
+        end: postEnd,
+      });
+
+      if (postMarks?.length) {
+        post.marks = postMarks;
+      }
+
+      splits.suffix.push(post);
+    }
+  }
+
+  return splits;
+}

package/src/lib/transformers/table-body-data.spec.ts

@@ -0,0 +1,44 @@
+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: 'Cell data',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 9,
+      type: 'table-body-data',
+      uuid: 'table-data-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('tableBodyData 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 tableBodyData annotation correctly', () => {
+    // The tableCell should be in block.content[0]
+    const tableCellNode = block.content?.[0];
+    expect(tableCellNode).toBeDefined();
+    expect(tableCellNode?.type).toBe('tableCell');
+    expect(tableCellNode?.content).toBeDefined();
+    expect(tableCellNode?.content?.[0]?.type).toBe('paragraph');
+  });
+});

package/src/lib/transformers/table-body-data.ts

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

package/src/lib/transformers/table-body-header.spec.ts

@@ -0,0 +1,44 @@
+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: 'Header cell',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 11,
+      type: 'table-body-header',
+      uuid: 'table-header-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('tableBodyHeader 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 tableBodyHeader annotation correctly', () => {
+    // The tableHeader should be in block.content[0]
+    const tableHeaderNode = block.content?.[0];
+    expect(tableHeaderNode).toBeDefined();
+    expect(tableHeaderNode?.type).toBe('tableHeader');
+    expect(tableHeaderNode?.content).toBeDefined();
+    expect(tableHeaderNode?.content?.[0]?.type).toBe('paragraph');
+  });
+});

package/src/lib/transformers/table-body-header.ts

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

package/src/lib/transformers/table-body-row.spec.ts

@@ -0,0 +1,44 @@
+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: 'Row data',
+  work_uuid: 'work-uuid-5678',
+  annotations: [
+    {
+      end: 8,
+      type: 'table-body-row',
+      uuid: 'table-row-uuid-1',
+      start: 0,
+      content: [],
+      passage_uuid: 'passage-uuid-1234',
+    },
+  ],
+};
+
+describe('tableBodyRow 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 tableBodyRow annotation correctly', () => {
+    // The tableRow should be in block.content[0]
+    const tableRowNode = block.content?.[0];
+    expect(tableRowNode).toBeDefined();
+    expect(tableRowNode?.type).toBe('tableRow');
+    expect(tableRowNode?.content).toBeDefined();
+    expect(tableRowNode?.content?.[0]?.type).toBe('paragraph');
+  });
+});

package/src/lib/transformers/table-body-row.ts

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

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

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