@eightyfourthousand/lib-editing 2026.3.0

package/src/lib/components/editor/menus/selectors/TranslationTextButtons.tsx

@@ -0,0 +1,125 @@
+'use client';
+
+import { cn } from '@eightyfourthousand/lib-utils';
+import { Editor } from '@tiptap/core';
+import { useEditorState } from '@tiptap/react';
+import {
+  BoldIcon,
+  CaseUpperIcon,
+  ItalicIcon,
+  SubscriptIcon,
+  SuperscriptIcon,
+  UnderlineIcon,
+} from 'lucide-react';
+import { Button, Separator } from '@eightyfourthousand/design-system';
+import { LinkSelector } from './LinkSelector';
+import { MantraSelector } from './MantraSelector';
+import { EndNoteSelector } from './EndNoteSelector';
+import { GlossarySelector } from './GlossarySelector';
+
+interface SelectorResult {
+  isBold: boolean;
+  isItalic: boolean;
+  isSmallCaps: boolean;
+  isSubscript: boolean;
+  isSuperscript: boolean;
+  isUnderline: boolean;
+}
+
+const items = [
+  {
+    icon: BoldIcon,
+    onClick: (editor: Editor, state: SelectorResult) =>
+      state.isBold
+        ? editor.chain().focus().unsetBold().run()
+        : editor.chain().focus().setBold().run(),
+    isActive: (state: SelectorResult) => state.isBold,
+  },
+  {
+    icon: ItalicIcon,
+    onClick: (editor: Editor, state: SelectorResult) =>
+      state.isItalic
+        ? editor.chain().focus().unsetItalic().run()
+        : editor.chain().focus().setItalic().run(),
+    isActive: (state: SelectorResult) => state.isItalic,
+  },
+  {
+    icon: UnderlineIcon,
+    onClick: (editor: Editor, state: SelectorResult) =>
+      state.isUnderline
+        ? editor.chain().focus().unsetUnderline().run()
+        : editor.chain().focus().setUnderline().run(),
+    isActive: (state: SelectorResult) => state.isUnderline,
+  },
+  {
+    icon: SubscriptIcon,
+    onClick: (editor: Editor, state: SelectorResult) =>
+      state.isSubscript
+        ? editor.chain().focus().unsetSubscript().run()
+        : editor.chain().focus().setSubscript().run(),
+    isActive: (state: SelectorResult) => state.isSubscript,
+  },
+  {
+    icon: SuperscriptIcon,
+    onClick: (editor: Editor, state: SelectorResult) =>
+      state.isSuperscript
+        ? editor.chain().focus().unsetSuperscript().run()
+        : editor.chain().focus().setSuperscript().run(),
+    isActive: (state: SelectorResult) => state.isSuperscript,
+  },
+  {
+    icon: CaseUpperIcon,
+    onClick: (editor: Editor, state: SelectorResult) =>
+      state.isSmallCaps
+        ? editor.chain().focus().unsetSmallCaps().run()
+        : editor.chain().focus().setSmallCaps().run(),
+    isActive: (state: SelectorResult) => state.isSmallCaps,
+  },
+];
+
+export const TranslationTextButtons = ({ editor }: { editor: Editor }) => {
+  const editorState = useEditorState<SelectorResult>({
+    editor,
+    selector: (instance) => ({
+      isBold: instance.editor.isActive('bold'),
+      isItalic: instance.editor.isActive('italic'),
+      isUnderline: instance.editor.isActive('underline'),
+      isSmallCaps: instance.editor.isActive('smallCaps'),
+      isSubscript: instance.editor.isActive('subscript'),
+      isSuperscript: instance.editor.isActive('superscript'),
+    }),
+  });
+
+  return (
+    <>
+      {items.map((item, i) => {
+        return (
+          <Button
+            key={i}
+            variant="ghost"
+            size="icon"
+            className="rounded-none flex-shrink-0"
+            onClick={() => {
+              item.onClick(editor, editorState);
+            }}
+          >
+            <item.icon
+              className={cn(
+                'size-4',
+                item.isActive(editorState)
+                  ? 'text-foreground'
+                  : 'text-muted-foreground',
+              )}
+              strokeWidth={2.5}
+            />
+          </Button>
+        );
+      })}
+      <MantraSelector editor={editor} />
+      <Separator orientation="vertical" className="h-10" />
+      <GlossarySelector editor={editor} />
+      <LinkSelector editor={editor} />
+      <EndNoteSelector editor={editor} />
+    </>
+  );
+};

package/src/lib/components/editor/menus/selectors/index.ts

@@ -0,0 +1,5 @@
+export * from './LinkSelector';
+export * from './TextAlignSelector';
+export * from './TextButtons';
+export * from './TranslationNodeSelector';
+export * from './NodeSelector';

package/src/lib/components/editor/save-filter.spec.ts

@@ -0,0 +1,94 @@
+import { computeSavePayload } from './save-filter';
+
+describe('computeSavePayload', () => {
+  it('should return dirty UUIDs as uuidsToSave when no deletions', () => {
+    const result = computeSavePayload({
+      dirtyUuids: new Set(['a', 'b']),
+      deletedUuids: new Set(),
+    });
+
+    expect(result.uuidsToSave).toEqual(['a', 'b']);
+    expect(result.uuidsToDelete).toEqual([]);
+    expect(result.hasChanges).toBe(true);
+  });
+
+  it('should return deleted UUIDs as uuidsToDelete when no dirty', () => {
+    const result = computeSavePayload({
+      dirtyUuids: new Set(),
+      deletedUuids: new Set(['x']),
+    });
+
+    expect(result.uuidsToSave).toEqual([]);
+    expect(result.uuidsToDelete).toEqual(['x']);
+    expect(result.hasChanges).toBe(true);
+  });
+
+  it('should exclude deleted UUIDs from the save list', () => {
+    const result = computeSavePayload({
+      dirtyUuids: new Set(['a', 'b', 'c']),
+      deletedUuids: new Set(['b']),
+    });
+
+    expect(result.uuidsToSave).toEqual(['a', 'c']);
+    expect(result.uuidsToDelete).toEqual(['b']);
+    expect(result.hasChanges).toBe(true);
+  });
+
+  it('should handle a UUID that is both dirty and deleted', () => {
+    const result = computeSavePayload({
+      dirtyUuids: new Set(['a']),
+      deletedUuids: new Set(['a']),
+    });
+
+    expect(result.uuidsToSave).toEqual([]);
+    expect(result.uuidsToDelete).toEqual(['a']);
+    expect(result.hasChanges).toBe(true);
+  });
+
+  it('should report no changes when both sets are empty', () => {
+    const result = computeSavePayload({
+      dirtyUuids: new Set(),
+      deletedUuids: new Set(),
+    });
+
+    expect(result.uuidsToSave).toEqual([]);
+    expect(result.uuidsToDelete).toEqual([]);
+    expect(result.hasChanges).toBe(false);
+  });
+
+  it('should handle split scenario: original dirty + new dirty, none deleted', () => {
+    const result = computeSavePayload({
+      dirtyUuids: new Set(['original', 'new-split']),
+      deletedUuids: new Set(),
+    });
+
+    expect(result.uuidsToSave).toEqual(
+      expect.arrayContaining(['original', 'new-split']),
+    );
+    expect(result.uuidsToSave).toHaveLength(2);
+    expect(result.uuidsToDelete).toEqual([]);
+    expect(result.hasChanges).toBe(true);
+  });
+
+  it('should handle merge scenario: merged passage dirty + old passage deleted', () => {
+    const result = computeSavePayload({
+      dirtyUuids: new Set(['passage-a', 'passage-b']),
+      deletedUuids: new Set(['passage-b']),
+    });
+
+    expect(result.uuidsToSave).toEqual(['passage-a']);
+    expect(result.uuidsToDelete).toEqual(['passage-b']);
+    expect(result.hasChanges).toBe(true);
+  });
+
+  it('should handle delete-only scenario: passage deleted without edits', () => {
+    const result = computeSavePayload({
+      dirtyUuids: new Set(),
+      deletedUuids: new Set(['deleted-passage']),
+    });
+
+    expect(result.uuidsToSave).toEqual([]);
+    expect(result.uuidsToDelete).toEqual(['deleted-passage']);
+    expect(result.hasChanges).toBe(true);
+  });
+});

package/src/lib/components/editor/save-filter.ts

@@ -0,0 +1,27 @@
+/**
+ * Compute which passage UUIDs should be saved and which should be deleted.
+ * Passages that are both dirty and deleted are excluded from the save list
+ * (they no longer exist in the editor).
+ */
+export const computeSavePayload = ({
+  dirtyUuids,
+  deletedUuids,
+}: {
+  dirtyUuids: Set<string>;
+  deletedUuids: Set<string>;
+}): {
+  uuidsToSave: string[];
+  uuidsToDelete: string[];
+  hasChanges: boolean;
+} => {
+  const uuidsToDelete = Array.from(deletedUuids);
+  const uuidsToSave = Array.from(dirtyUuids).filter(
+    (uuid) => !deletedUuids.has(uuid),
+  );
+
+  return {
+    uuidsToSave,
+    uuidsToDelete,
+    hasChanges: uuidsToSave.length > 0 || uuidsToDelete.length > 0,
+  };
+};

package/src/lib/components/editor/util.ts

@@ -0,0 +1,304 @@
+import {
+  MarkViewProps,
+  mergeAttributes,
+  NodeViewProps,
+  NodeViewRendererProps,
+} from '@tiptap/react';
+import { Editor } from '@tiptap/core';
+import { HTMLElementType } from 'react';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * WeakMap to associate DOM elements with their editor instances.
+ * Used by HoverCardProvider to find the correct editor for a hovered element.
+ */
+const editorElementMap = new WeakMap<HTMLElement, Editor>();
+
+/**
+ * Registers an editor for a DOM element.
+ * Call this when creating mark/node views to enable hover card functionality.
+ */
+export const registerEditorElement = (element: HTMLElement, editor: Editor) => {
+  editorElementMap.set(element, editor);
+};
+
+/**
+ * Gets the editor associated with a DOM element.
+ */
+export const getEditorForElement = (
+  element: HTMLElement,
+): Editor | undefined => {
+  return editorElementMap.get(element);
+};
+
+/**
+ * Validates and updates the attributes of a Node.
+ * Specifically, it ensures that the node has a unique 'uuid' attribute.
+ * If the 'uuid' is missing or duplicates the previous node's 'uuid',
+ * a new UUID is generated and assigned. In the case of duplication, all
+ * global attributes are set to their default values.
+ */
+export const validateAttrs = ({
+  node,
+  editor,
+  getPos,
+  updateAttributes,
+}: Partial<NodeViewProps>) => {
+  if (!node?.attrs.uuid) {
+    updateAttributes?.({ uuid: uuidv4() });
+    return;
+  }
+
+  const pos = getPos?.();
+  if (pos === null || pos === undefined) {
+    return;
+  }
+
+  // check if previous node has same uuid, if so, set a new one
+  const $pos = editor?.state.doc.resolve(pos);
+  const parent = $pos?.parent;
+  const index = $pos?.index();
+  if (!parent || index === null || index === undefined) {
+    return;
+  }
+
+  if (index > 0 && parent.child(index - 1).attrs.uuid === node.attrs.uuid) {
+    const attrs: { [attr: string]: unknown } = {
+      ...node.attrs,
+      uuid: uuidv4(),
+    };
+
+    // reset all global attributes to default values
+    if (attrs.leadingSpaceUuid) {
+      attrs.leadSpaceUuid = undefined;
+    }
+
+    if (attrs.hasLeadingSpace) {
+      attrs.hasLeadingSpace = false;
+    }
+
+    if (attrs.indentUuid) {
+      attrs.indentUuid = undefined;
+    }
+
+    if (attrs.hasIndent) {
+      attrs.hasIndent = false;
+    }
+
+    if (attrs.hasParagraphIndent) {
+      attrs.hasParagraphIndent = false;
+    }
+
+    updateAttributes?.(attrs);
+  }
+};
+
+/**
+ * Finds the range of a given mark in the editor's document by its reference.
+ * Returns an object with 'from' and 'to' positions if found, otherwise undefined.
+ */
+export const findMarkRange = ({ editor, mark }: Partial<MarkViewProps>) => {
+  if (!editor || !mark) {
+    return undefined;
+  }
+
+  const { state } = editor;
+  const { doc, tr } = state;
+
+  let foundRange: { from: number; to: number } | undefined = undefined;
+
+  const thisMark = mark;
+  doc.descendants((node, pos) => {
+    let foundMark = false;
+    const from = tr.mapping.map(pos);
+    const to = from + node.nodeSize;
+
+    node.marks.forEach((m) => {
+      if (m === thisMark) {
+        foundMark = true;
+        foundRange = { from, to };
+        return;
+      }
+    });
+
+    return !foundMark;
+  });
+
+  return foundRange;
+};
+
+/**
+ * Finds a mark in the editor's document by its UUID attribute.
+ * Returns an object with 'from', 'to', and 'mark' if found, otherwise undefined.
+ */
+export const findMarkByUuid = ({
+  editor,
+  uuid,
+  markType,
+  comparator = (mark, uuid) => mark.attrs.uuid === uuid,
+}: {
+  editor: {
+    state: {
+      doc: MarkViewProps['editor']['state']['doc'];
+      tr: MarkViewProps['editor']['state']['tr'];
+    };
+  };
+  uuid: string;
+  markType: string;
+  comparator?: (mark: MarkViewProps['mark'], uuid: string) => boolean;
+}): { from: number; to: number; mark: MarkViewProps['mark'] } | undefined => {
+  const { state } = editor;
+  const { doc, tr } = state;
+
+  let foundRange:
+    | { from: number; to: number; mark: MarkViewProps['mark'] }
+    | undefined = undefined;
+
+  doc.descendants((node, pos) => {
+    if (foundRange) return false;
+
+    const from = tr.mapping.map(pos);
+    const to = from + node.nodeSize;
+
+    for (const m of node.marks) {
+      if (m.type.name === markType && comparator(m, uuid)) {
+        foundRange = { from, to, mark: m };
+        return false;
+      }
+    }
+
+    return true;
+  });
+
+  return foundRange;
+};
+
+export const findEndnoteMarkByUuid = ({
+  editor,
+  uuid,
+}: {
+  editor: {
+    state: {
+      doc: MarkViewProps['editor']['state']['doc'];
+      tr: MarkViewProps['editor']['state']['tr'];
+    };
+  };
+  uuid: string;
+}): { from: number; to: number; mark: MarkViewProps['mark'] } | undefined => {
+  return findMarkByUuid({
+    editor,
+    uuid,
+    markType: 'endNoteLink',
+    comparator: (mark, uuid) =>
+      mark.attrs.notes?.some((note: { uuid: string }) => note.uuid === uuid),
+  });
+};
+
+/**
+ * Find a passage node in any editor by UUID.
+ * Returns { pos, node } or undefined.
+ */
+export const findPassageNode = (
+  editor: Editor,
+  passageUuid: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): { pos: number; node: any } | undefined => {
+  const { doc } = editor.state;
+  let result: { pos: number; node: typeof doc } | undefined;
+
+  doc.descendants((node, pos) => {
+    if (result) return false;
+    if (node.type.name === 'passage' && node.attrs.uuid === passageUuid) {
+      result = { pos, node };
+      return false;
+    }
+    return true;
+  });
+
+  return result;
+};
+
+/**
+ * Creates a function to update the attributes of a given HTML element.
+ * The returned function takes an object of attributes and sets them on the element.
+ */
+export const createUpdateAttributes = (element: HTMLElement) => {
+  return (attrs: { [key: string]: unknown }) => {
+    Object.keys(attrs).forEach((key) => {
+      element.setAttribute(key, attrs[key] as string);
+    });
+  };
+};
+
+/**
+ * Creates a NodeView DOM element for a given node and extension.
+ * It sets up the element with merged attributes and validates them.
+ */
+export const createNodeViewDom = ({
+  editor,
+  getPos,
+  node,
+  extension,
+  HTMLAttributes,
+  element,
+  className,
+}: Partial<NodeViewRendererProps> & {
+  element: HTMLElementType;
+  className?: string;
+}) => {
+  const dom = document.createElement(element);
+  const updateAttributes = createUpdateAttributes(dom);
+
+  const attributes = mergeAttributes(
+    node?.attrs || {},
+    extension?.options.HTMLAttributes,
+    HTMLAttributes || {},
+    {
+      class: className,
+      type: extension?.name,
+    },
+  );
+
+  updateAttributes(attributes);
+
+  validateAttrs({
+    node,
+    editor,
+    getPos,
+    updateAttributes,
+  });
+
+  return { dom, updateAttributes };
+};
+
+/**
+ * Creates a MarkView DOM element for a given mark and extension.
+ * It sets up the element with merged attributes.
+ */
+export const createMarkViewDom = ({
+  mark,
+  extension,
+  HTMLAttributes,
+  element,
+  className,
+}: Partial<MarkViewProps> & {
+  element: HTMLElementType;
+  className?: string;
+}) => {
+  const dom = document.createElement(element);
+  const updateElementAttributes = createUpdateAttributes(dom);
+
+  const attributes = mergeAttributes(
+    mark?.attrs || {},
+    extension?.options.HTMLAttributes,
+    HTMLAttributes || {},
+    {
+      class: className,
+      type: extension?.name,
+    },
+  );
+
+  updateElementAttributes(attributes);
+
+  return { dom, updateAttributes: updateElementAttributes };
+};

package/src/lib/components/index.ts

@@ -0,0 +1,3 @@
+export * from './editor';
+export * from './shared';
+export * from './reader';

package/src/lib/components/reader/ReaderBackMatterPage.tsx

@@ -0,0 +1,62 @@
+import {
+  createBuildGraphQLClient,
+  getTranslationBlocks,
+  getWorkGlossaryTerms,
+  getWorkBibliography,
+} from '@eightyfourthousand/client-graphql/ssr';
+import { isStaticFeatureEnabled } from '@eightyfourthousand/lib-instr/static';
+import { ReaderBackMatterPanel } from './ReaderBackMatterPanel';
+import { isUuid } from '@eightyfourthousand/lib-utils';
+import { notFound } from 'next/navigation';
+
+export const ReaderBackMatterPage = async ({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) => {
+  const { slug } = await params;
+
+  if (!isUuid(slug)) {
+    return notFound();
+  }
+
+  const graphqlClient = createBuildGraphQLClient();
+  const withAttestations = isStaticFeatureEnabled('glossary-attestations');
+
+  const [
+    { blocks: endnotes },
+    { blocks: abbreviations },
+    glossary,
+    bibliography,
+  ] = await Promise.all([
+    getTranslationBlocks({
+      client: graphqlClient,
+      uuid: slug,
+      type: 'endnotes',
+    }),
+    getTranslationBlocks({
+      client: graphqlClient,
+      uuid: slug,
+      type: 'abbreviations',
+    }),
+    getWorkGlossaryTerms({
+      client: graphqlClient,
+      uuid: slug,
+      withAttestations,
+    }),
+    getWorkBibliography({
+      client: graphqlClient,
+      uuid: slug,
+    }),
+  ]);
+
+  return (
+    <ReaderBackMatterPanel
+      workUuid={slug}
+      abbreviations={abbreviations}
+      bibliography={bibliography}
+      endnotes={endnotes}
+      glossary={glossary}
+    />
+  );
+};

package/src/lib/components/reader/ReaderBackMatterPanel.tsx

@@ -0,0 +1,53 @@
+'use client';
+
+import { useCallback } from 'react';
+import { BibliographyEntries } from '@eightyfourthousand/data-access';
+import type { GlossaryTermsPage } from '@eightyfourthousand/client-graphql';
+import { BackMatterPanel } from '../shared/BackMatterPanel';
+import { TranslationRenderer } from '../shared/types';
+import { TranslationReader } from '.';
+import { TranslationEditorContent } from '../editor';
+import { useNavigation } from '../shared/NavigationProvider';
+
+export const ReaderBackMatterPanel = ({
+  workUuid,
+  endnotes,
+  glossary,
+  bibliography,
+  abbreviations,
+}: {
+  workUuid: string;
+  endnotes: TranslationEditorContent;
+  glossary: GlossaryTermsPage;
+  bibliography: BibliographyEntries;
+  abbreviations: TranslationEditorContent;
+}) => {
+  const { hasTranslationContent } = useNavigation();
+  if (!hasTranslationContent) {
+    return null;
+  }
+
+  const renderTranslation = useCallback(
+    ({ content, name, className }: TranslationRenderer) => (
+      <TranslationReader
+        content={content}
+        name={name}
+        className={className}
+        filter={name}
+        panel="right"
+      />
+    ),
+    [],
+  );
+
+  return (
+    <BackMatterPanel
+      workUuid={workUuid}
+      endnotes={endnotes}
+      glossary={glossary}
+      bibliography={bibliography}
+      abbreviations={abbreviations}
+      renderTranslation={renderTranslation}
+    />
+  );
+};