@eightyfourthousand/lib-editing 2026.3.0

package/src/fixtures/types.ts

@@ -0,0 +1,8 @@
+export const SLUGS = ['basic', 'toh251'];
+export type Slug = (typeof SLUGS)[number];
+
+export const FORMATS = ['json', 'passages', 'html', 'text'] as const;
+export type Format = (typeof FORMATS)[number];
+
+export const EDITORS = ['translation', 'block'];
+export type EditorType = (typeof EDITORS)[number];

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/block';
+export * from './lib/components';
+export * from './lib/passage';
+export * from './lib/titles';

package/src/lib/block.ts

@@ -0,0 +1,226 @@
+import type {
+  Alignment,
+  AnnotationType,
+  BodyItemType,
+  Passage,
+  TranslationEditorContentItem,
+  TranslationEditorContent,
+} from '@eightyfourthousand/data-access';
+import { annotateBlock } from './transformers/annotate';
+
+const passageTemplate = (passage: Passage): TranslationEditorContentItem => {
+  const alignments: { [key: string]: Alignment } =
+    passage.alignments?.reduce(
+      (acc, alignment) => {
+        acc[alignment.toh] = alignment;
+        return acc;
+      },
+      {} as { [key: string]: Alignment },
+    ) || {};
+  const block: TranslationEditorContentItem = {
+    type: 'passage',
+    attrs: {
+      uuid: passage.uuid,
+      sort: passage.sort,
+      type: passage.type,
+      label: passage.label,
+      toh: passage.toh,
+      alignments,
+      ...(passage.references?.length ? { references: passage.references } : {}),
+    },
+    content: [],
+  };
+
+  const template =
+    TEMPLATES_FOR_BLOCK_TYPE[passage.type] ||
+    TEMPLATES_FOR_BLOCK_TYPE['translation'];
+  block.content = [template(passage)];
+
+  return block;
+};
+
+const textTemplate = (text: string): TranslationEditorContentItem => ({
+  type: 'text',
+  text,
+  attrs: {
+    start: 0,
+    end: text.length,
+  },
+});
+
+const headingTemplate = (passage: Passage): TranslationEditorContentItem => {
+  const block: TranslationEditorContentItem = {
+    type: 'heading',
+    attrs: {
+      level: 1,
+      start: 0,
+      end: passage.content.length,
+      uuid: passage.uuid,
+    },
+    content: [],
+  };
+  block.content = [textTemplate(passage.content)];
+  return block;
+};
+
+const paragraphTemplate = (passage: Passage): TranslationEditorContentItem => {
+  const block: TranslationEditorContentItem = {
+    type: 'paragraph',
+    attrs: {
+      start: 0,
+      end: passage.content.length,
+      uuid: passage.uuid,
+    },
+    content: [],
+  };
+
+  block.content = [textTemplate(passage.content)];
+  return block;
+};
+
+const abbreviationTemplate = (
+  passage: Passage,
+): TranslationEditorContentItem => {
+  const block: TranslationEditorContentItem = {
+    type: 'paragraph',
+    attrs: {
+      class: 'flex flex-row gap-2',
+      start: 0,
+      end: passage.content.length,
+      uuid: passage.uuid,
+    },
+    content: [],
+  };
+
+  block.content = [textTemplate(passage.content)];
+  return block;
+};
+
+const TEMPLATES_FOR_BLOCK_TYPE: {
+  [key in BodyItemType]: (passage: Passage) => TranslationEditorContentItem;
+} = {
+  acknowledgment: paragraphTemplate,
+  acknowledgmentHeader: headingTemplate,
+  abbreviations: abbreviationTemplate,
+  abbreviationsHeader: headingTemplate,
+  appendix: paragraphTemplate,
+  appendixHeader: headingTemplate,
+  colophon: paragraphTemplate,
+  colophonHeader: headingTemplate,
+  endnotes: paragraphTemplate,
+  endnotesHeader: headingTemplate,
+  homage: paragraphTemplate,
+  homageHeader: headingTemplate,
+  introduction: paragraphTemplate,
+  introductionHeader: headingTemplate,
+  prelude: paragraphTemplate,
+  preludeHeader: headingTemplate,
+  prologue: paragraphTemplate,
+  prologueHeader: headingTemplate,
+  summary: paragraphTemplate,
+  summaryHeader: headingTemplate,
+  translation: paragraphTemplate,
+  translationHeader: headingTemplate,
+  unknown: paragraphTemplate,
+};
+
+enum BlockPriority {
+  OuterBlock = 0,
+  ParentBlock = 1,
+  Block = 2,
+  Attribute = 3,
+  Inline = 4,
+  Mark = 5,
+  Unknown = Number.MIN_SAFE_INTEGER,
+}
+
+const PRIORITY_FOR_ANNOTAION_TYPE: { [key in AnnotationType]: BlockPriority } =
+  {
+    abbreviation: BlockPriority.Inline,
+    audio: BlockPriority.Inline,
+    blockquote: BlockPriority.OuterBlock,
+    code: BlockPriority.Inline,
+    deprecated: BlockPriority.Unknown,
+    endNoteLink: BlockPriority.Mark,
+    glossaryInstance: BlockPriority.Mark,
+    hasAbbreviation: BlockPriority.Inline,
+    heading: BlockPriority.OuterBlock,
+    indent: BlockPriority.Attribute,
+    image: BlockPriority.Inline,
+    inlineTitle: BlockPriority.Mark,
+    internalLink: BlockPriority.Mark,
+    leadingSpace: BlockPriority.Attribute,
+    line: BlockPriority.Block,
+    lineGroup: BlockPriority.ParentBlock,
+    link: BlockPriority.Mark,
+    list: BlockPriority.ParentBlock,
+    listItem: BlockPriority.Block,
+    mantra: BlockPriority.Mark,
+    mention: BlockPriority.Inline,
+    paragraph: BlockPriority.OuterBlock,
+    quote: BlockPriority.Inline,
+    quoted: BlockPriority.Unknown,
+    reference: BlockPriority.Unknown,
+    span: BlockPriority.Mark,
+    table: BlockPriority.OuterBlock,
+    tableBodyData: BlockPriority.Block,
+    tableBodyHeader: BlockPriority.ParentBlock,
+    tableBodyRow: BlockPriority.ParentBlock,
+    trailer: BlockPriority.OuterBlock,
+    unknown: BlockPriority.Unknown,
+  };
+
+export const blocksFromTranslationBody = (
+  passages: Passage[],
+): TranslationEditorContent => {
+  const blocks: TranslationEditorContent = [];
+  passages.forEach((passage) => {
+    if (!passage.content) {
+      console.warn('passage has no content');
+      console.warn(passage);
+      return;
+    }
+
+    const block = blockFromPassage(passage);
+
+    if (!block) {
+      console.warn('unknown block type');
+      console.warn(passage);
+      return;
+    }
+
+    blocks.push(block);
+  });
+
+  return blocks;
+};
+
+export const blockFromPassage = (
+  passage: Passage,
+): TranslationEditorContentItem => {
+  const block = passageTemplate(passage);
+
+  // Sort annotations by start position, then by end position in descending
+  // order to ensure that the longest annotations are processed first. If two
+  // annotations have the same start and end positions, sort by processing
+  // priority.
+  passage.annotations?.sort((a, b) => {
+    if (a.start !== b.start) {
+      return a.start - b.start;
+    }
+
+    if (a.end !== b.end) {
+      return b.end - a.end;
+    }
+
+    const aPriority =
+      PRIORITY_FOR_ANNOTAION_TYPE[a.type] || BlockPriority.Unknown;
+    const bPriority =
+      PRIORITY_FOR_ANNOTAION_TYPE[b.type] || BlockPriority.Unknown;
+    return aPriority - bPriority;
+  });
+
+  annotateBlock(block, passage.annotations);
+
+  return block;
+};

package/src/lib/components/editor/BlockEditor.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import {
+  EditorContent,
+  type Content,
+  type UseEditorOptions,
+} from '@tiptap/react';
+import { useBlockEditor, useDefaultExtensions } from './hooks';
+import { MainBubbleMenu } from './menus/MainBubbleMenu';
+
+export type BlockEditorContent = Content;
+
+export const BlockEditor = ({
+  content,
+  isEditable = true,
+  onUpdate,
+  onCreate,
+}: UseEditorOptions & {
+  content: BlockEditorContent;
+  isEditable?: boolean;
+}) => {
+  const { extensions } = useDefaultExtensions();
+  const { editor } = useBlockEditor({
+    extensions,
+    content,
+    isEditable,
+    onCreate,
+    onUpdate,
+  });
+  return (
+    <div className="relative flex flex-col flex-1 h-full">
+      <EditorContent className="flex-1" editor={editor} />
+      <MainBubbleMenu editor={editor} />
+    </div>
+  );
+};
+
+export default BlockEditor;

package/src/lib/components/editor/EditorBackMatterPage.tsx

@@ -0,0 +1,95 @@
+'use client';
+
+import {
+  createGraphQLClient,
+  getTranslationBlocks,
+  getWorkGlossaryTerms,
+  getWorkBibliography,
+  type GlossaryTermsPage,
+} from '@eightyfourthousand/client-graphql';
+import type { BibliographyEntries } from '@eightyfourthousand/data-access';
+import { BackMatterPanel } from '../shared/BackMatterPanel';
+import { TranslationRenderer } from '../shared/types';
+import { useEditorState } from './EditorProvider';
+import { useCallback, useEffect, useState } from 'react';
+import { TranslationEditorContent } from '../editor';
+import { TranslationSkeleton } from '../shared/TranslationSkeleton';
+import { TranslationBuilder } from '../editor';
+import { isStaticFeatureEnabled } from '@eightyfourthousand/lib-instr/static';
+
+export const EditorBackMatterPage = () => {
+  const { work } = useEditorState();
+  const [endnotes, setEndnotes] = useState<TranslationEditorContent>();
+  const [abbreviations, setAbbreviations] =
+    useState<TranslationEditorContent>();
+  const [glossary, setGlossary] = useState<GlossaryTermsPage>();
+  const [bibliography, setBibliography] = useState<BibliographyEntries>();
+
+  useEffect(() => {
+    (async () => {
+      const { uuid } = work;
+      const graphqlClient = createGraphQLClient();
+      const withAttestations = isStaticFeatureEnabled('glossary-attestations');
+
+      const [
+        { blocks: endnoteBlocks },
+        { blocks: abbreviationBlocks },
+        glossaryData,
+        bibliographyData,
+      ] = await Promise.all([
+        getTranslationBlocks({
+          client: graphqlClient,
+          uuid,
+          type: 'endnotes',
+        }),
+        getTranslationBlocks({
+          client: graphqlClient,
+          uuid,
+          type: 'abbreviations',
+        }),
+        getWorkGlossaryTerms({
+          client: graphqlClient,
+          uuid,
+          withAttestations,
+        }),
+        getWorkBibliography({
+          client: graphqlClient,
+          uuid,
+        }),
+      ]);
+
+      setEndnotes(endnoteBlocks);
+      setAbbreviations(abbreviationBlocks);
+      setGlossary(glossaryData);
+      setBibliography(bibliographyData);
+    })();
+  }, [work]);
+
+  const renderTranslation = useCallback(
+    ({ content, name, className }: TranslationRenderer) => (
+      <TranslationBuilder
+        content={content}
+        name={name}
+        className={className}
+        filter={name}
+        panel="right"
+      />
+    ),
+    [],
+  );
+
+  if (!endnotes || !glossary || !bibliography || !abbreviations) {
+    return <TranslationSkeleton />;
+  }
+
+  return (
+    <BackMatterPanel
+      workUuid={work.uuid}
+      endnotes={endnotes}
+      glossary={glossary}
+      bibliography={bibliography}
+      abbreviations={abbreviations}
+      renderTranslation={renderTranslation}
+    />
+  );
+};

package/src/lib/components/editor/EditorBodyPage.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import {
+  createGraphQLClient,
+  BODY_MATTER_FILTER,
+  FRONT_MATTER_FILTER,
+  getTranslationBlocks,
+  getTranslationTitles,
+} from '@eightyfourthousand/client-graphql';
+import type { Title } from '@eightyfourthousand/data-access';
+import { BodyPanel } from '../shared/BodyPanel';
+import { TitlesRenderer, TranslationRenderer } from '../shared/types';
+import { useEditorState } from './EditorProvider';
+import { useCallback, useEffect, useState } from 'react';
+import { TranslationBuilder, TranslationEditorContent } from '.';
+import { TranslationSkeleton } from '../shared/TranslationSkeleton';
+import { TitlesBuilder } from './TitlesBuilder';
+
+const INITIAL_PASSAGES = 100;
+
+export const EditorBodyPage = () => {
+  const { work } = useEditorState();
+  const [body, setBody] = useState<TranslationEditorContent>();
+  const [frontMatter, setFrontMatter] = useState<TranslationEditorContent>();
+  const [titles, setTitles] = useState<Title[]>();
+
+  useEffect(() => {
+    (async () => {
+      const client = createGraphQLClient();
+
+      const [{ blocks: frontBlocks }, { blocks: bodyBlocks }, titlesData] =
+        await Promise.all([
+          getTranslationBlocks({
+            client,
+            uuid: work.uuid,
+            type: FRONT_MATTER_FILTER,
+            maxPassages: INITIAL_PASSAGES,
+          }),
+          getTranslationBlocks({
+            client,
+            uuid: work.uuid,
+            type: BODY_MATTER_FILTER,
+            maxPassages: INITIAL_PASSAGES,
+          }),
+          getTranslationTitles({ client, uuid: work.uuid }),
+        ]);
+
+      setTitles(titlesData);
+      setFrontMatter(frontBlocks);
+      setBody(bodyBlocks);
+    })();
+  }, [work.uuid]);
+
+  const renderTitles = useCallback(
+    ({ titles, imprint }: TitlesRenderer) => (
+      <TitlesBuilder titles={titles} imprint={imprint} />
+    ),
+    [],
+  );
+
+  const renderTranslation = useCallback(
+    ({ content, name, className }: TranslationRenderer) => (
+      <TranslationBuilder
+        content={content}
+        name={name}
+        className={className}
+        filter={name === 'front' ? FRONT_MATTER_FILTER : BODY_MATTER_FILTER}
+        panel="main"
+      />
+    ),
+    [],
+  );
+
+  if (!titles || !frontMatter || !body) {
+    return <TranslationSkeleton />;
+  }
+
+  return (
+    <BodyPanel
+      titles={titles}
+      frontMatter={frontMatter}
+      body={body}
+      renderTitles={renderTitles}
+      renderTranslation={renderTranslation}
+    />
+  );
+};

package/src/lib/components/editor/EditorHeader.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import { SaveButton } from '@eightyfourthousand/design-system';
+import { useEditorState } from './EditorProvider';
+
+export const EditorHeader = () => {
+  const { dirtyStore, save } = useEditorState();
+
+  // Subscribe to dirty state directly
+  const isDirty = useSyncExternalStore(
+    dirtyStore.subscribe.bind(dirtyStore),
+    dirtyStore.getSnapshot.bind(dirtyStore),
+    () => false,
+  );
+
+  return (
+    <div className="px-4 py-3 flex justify-end h-12 z-10 gap-2">
+      {isDirty && <SaveButton size="xs" onClick={save} />}
+    </div>
+  );
+};

package/src/lib/components/editor/EditorLayout.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { ReactNode, use, useEffect, useState } from 'react';
+import { EditorContextProvider } from './EditorProvider';
+import {
+  createGraphQLClient,
+  getTranslationMetadataByUuid,
+  Work,
+} from '@eightyfourthousand/client-graphql';
+import { ThreeColumnRenderer, TranslationSkeleton } from '../shared';
+import {
+  LeftPanel,
+  MainPanel,
+  MainPanelHeader,
+  RightPanel,
+} from '@eightyfourthousand/design-system';
+import { EditorHeader } from './EditorHeader';
+
+export const EditorLayout = ({
+  left,
+  main,
+  right,
+  params,
+}: {
+  left: ReactNode;
+  main: ReactNode;
+  right: ReactNode;
+  params: Promise<{ slug: string }>;
+}) => {
+  const { slug } = use(params);
+  const [work, setWork] = useState<Work>();
+
+  useEffect(() => {
+    (async () => {
+      const client = createGraphQLClient();
+      const work = await getTranslationMetadataByUuid({
+        client,
+        uuid: slug,
+      });
+      if (work) {
+        setWork(work);
+      }
+    })();
+  }, [slug]);
+
+  if (!work) {
+    return <TranslationSkeleton />;
+  }
+
+  return (
+    <EditorContextProvider work={work}>
+      <ThreeColumnRenderer withHeader={true}>
+        <LeftPanel>{left}</LeftPanel>
+        <MainPanelHeader>
+          <EditorHeader />
+        </MainPanelHeader>
+        <MainPanel>{main}</MainPanel>
+        <RightPanel>{right}</RightPanel>
+      </ThreeColumnRenderer>
+    </EditorContextProvider>
+  );
+};

package/src/lib/components/editor/EditorLeftPanelPage.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import { createGraphQLClient, getTranslationToc } from '@eightyfourthousand/client-graphql';
+import type { Toc } from '@eightyfourthousand/data-access';
+import { LeftPanel } from '../shared/LeftPanel';
+import { useEditorState } from './EditorProvider';
+import { useEffect, useState } from 'react';
+import { TranslationSkeleton } from '../shared/TranslationSkeleton';
+
+export const EditorLeftPanelPage = () => {
+  const { work } = useEditorState();
+  const [toc, setToc] = useState<Toc>();
+
+  useEffect(() => {
+    (async () => {
+      const client = createGraphQLClient();
+      const toc = await getTranslationToc({ client, uuid: work.uuid });
+      setToc(toc);
+    })();
+  }, [work.uuid]);
+
+  if (!toc) {
+    return <TranslationSkeleton />;
+  }
+
+  return <LeftPanel toc={toc} work={work} />;
+};