@eightyfourthousand/lib-editing 2026.3.0

package/src/lib/components/editor/extensions/Mantra/Mantra.ts

@@ -0,0 +1,88 @@
+import { TranslationLanguage } from '@eightyfourthousand/data-access';
+import { Mark, mergeAttributes } from '@tiptap/core';
+import { v4 as uuidv4 } from 'uuid';
+
+export interface MantraOptions {
+  HTMLAttributes: Record<string, unknown>;
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    mantra: {
+      setMantra: (lang?: TranslationLanguage) => ReturnType;
+      toggleMantra: (lang?: TranslationLanguage) => ReturnType;
+      unsetMantra: () => ReturnType;
+    };
+  }
+}
+
+export const MantraMark = Mark.create<MantraOptions>({
+  name: 'mantra',
+  addAttributes() {
+    return {
+      type: {
+        default: 'mantra',
+      },
+      lang: {
+        default: 'Sa-Ltn',
+      },
+    };
+  },
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+    };
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'span[type="mantra"]',
+      },
+    ];
+  },
+
+  renderHTML({ HTMLAttributes, mark }) {
+    const lang = mark.attrs.lang;
+    return [
+      'span',
+      mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {
+        lang,
+      }),
+      0,
+    ];
+  },
+
+  addCommands() {
+    return {
+      setMantra:
+        (lang?: TranslationLanguage) =>
+        ({ chain }) => {
+          return chain()
+            .setMark(this.name)
+            .updateAttributes(this.name, {
+              lang,
+              uuid: uuidv4(),
+            })
+            .run();
+        },
+      toggleMantra:
+        (lang?: TranslationLanguage) =>
+        ({ commands }) => {
+          if (this.editor.isActive(this.name, { lang })) {
+            return commands.unsetMantra();
+          }
+          return commands.setMantra(lang);
+        },
+      unsetMantra:
+        () =>
+        ({ chain }) => {
+          return chain()
+            .unsetMark(this.name)
+            .resetAttributes(this.name, 'lang')
+            .run();
+        },
+    };
+  },
+});

package/src/lib/components/editor/extensions/Mention/Mention.ts

@@ -0,0 +1,184 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+import { v4 as uuidv4 } from 'uuid';
+import { registerEditorElement } from '../../util';
+import { PANEL_FOR_SECTION, TAB_FOR_SECTION } from '../../../shared/types';
+
+export interface MentionOptions {
+  HTMLAttributes: Record<string, unknown>;
+}
+
+export interface MentionItem {
+  uuid: string;
+  entity: string;
+  linkType: string;
+  text?: string;
+  displayText?: string;
+  isSameWork?: boolean;
+  subtype?: string;
+  linkToh?: string;
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    mention: {
+      setMention: (entity: string, linkType: string) => ReturnType;
+    };
+  }
+}
+
+export const Mention = Node.create<MentionOptions>({
+  name: 'mention',
+  group: 'inline',
+  inline: true,
+  atom: true,
+
+  addOptions() {
+    return {
+      HTMLAttributes: {},
+    };
+  },
+
+  addAttributes() {
+    return {
+      items: {
+        default: [],
+        parseHTML: (element) => {
+          const itemsAttr = element.getAttribute('data-items');
+          if (itemsAttr) {
+            try {
+              return JSON.parse(itemsAttr);
+            } catch {
+              return [];
+            }
+          }
+          return [];
+        },
+      },
+    };
+  },
+
+  parseHTML() {
+    return [{ tag: 'span[data-type="mention"]' }];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      'span',
+      mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {
+        'data-type': 'mention',
+      }),
+    ];
+  },
+
+  addNodeView() {
+    return (props) => {
+      const isEditable = props.editor.isEditable;
+      const dom = document.createElement('span');
+      dom.classList.add('mention-container');
+
+      const items: MentionItem[] = props.node.attrs.items || [];
+
+      items.forEach((item) => {
+        const anchor = document.createElement('a');
+        anchor.classList.add('mention-link', 'pe-1');
+
+        // Display priority: text (custom override) > displayText (dynamic) > entity UUID (fallback)
+        anchor.textContent = item.text || item.displayText || item.entity;
+
+        // Compute href from linkType + entity
+        const href = `/entity/${item.linkType}/${item.entity}`;
+
+        if (item.isSameWork) {
+          // Same-work links navigate in-place via panel system
+          anchor.setAttribute('href', '#');
+          anchor.setAttribute('data-same-work', 'true');
+
+          if (item.subtype) {
+            anchor.setAttribute('data-subtype', item.subtype);
+          }
+          if (item.linkToh) {
+            anchor.setAttribute('data-link-toh', item.linkToh);
+          }
+
+          if (!isEditable) {
+            anchor.addEventListener('click', (e) => {
+              e.preventDefault();
+              const query = new URLSearchParams(window.location.search);
+
+              if (item.linkToh) {
+                query.set('toh', item.linkToh);
+              }
+
+              switch (item.linkType) {
+                case 'bibliography':
+                  query.set('right', `open:bibliography:${item.entity}`);
+                  break;
+                case 'glossary':
+                  query.set('right', `open:glossary:${item.entity}`);
+                  break;
+                case 'passage': {
+                  const panel =
+                    PANEL_FOR_SECTION[item.subtype || ''] || 'main';
+                  const tab =
+                    TAB_FOR_SECTION[item.subtype || ''] || 'translation';
+                  query.set(panel, `open:${tab}:${item.entity}`);
+                  break;
+                }
+                default:
+                  break;
+              }
+
+              window.history.pushState({}, '', `?${query.toString()}`);
+            });
+          }
+        } else {
+          // Cross-work links open in a new tab
+          anchor.setAttribute('href', href);
+          anchor.setAttribute('target', '_blank');
+          anchor.setAttribute('rel', 'noreferrer');
+        }
+
+        // Set DOM attrs for HoverCardProvider identification
+        if (item.uuid) {
+          anchor.setAttribute('uuid', item.uuid);
+        }
+        if (item.entity) {
+          anchor.setAttribute('entity', item.entity);
+        }
+        if (item.linkType) {
+          anchor.setAttribute('entity-type', item.linkType);
+        }
+
+        if (isEditable) {
+          anchor.setAttribute('type', 'mention');
+          registerEditorElement(anchor, props.editor);
+        }
+
+        dom.appendChild(anchor);
+      });
+
+      return { dom };
+    };
+  },
+
+  addCommands() {
+    return {
+      setMention:
+        (entity: string, linkType: string) =>
+          ({ commands }) => {
+            return commands.insertContent({
+              type: this.name,
+              attrs: {
+                items: [
+                  {
+                    uuid: uuidv4(),
+                    entity,
+                    linkType,
+                  },
+                ],
+              },
+            });
+          },
+    };
+  },
+});

package/src/lib/components/editor/extensions/Mention/MentionHoverContent.tsx

@@ -0,0 +1,158 @@
+import { Button } from '@eightyfourthousand/design-system';
+import { Editor } from '@tiptap/core';
+import { ChevronRightIcon, PencilIcon, Trash2Icon } from 'lucide-react';
+import { useCallback, useState } from 'react';
+import { InternalLinkInput } from '../InternalLink/InternalLinkInput';
+import { useHoverCard } from '../../../shared/HoverCardProvider';
+import type { MentionItem } from './Mention';
+
+const EDITOR_UPDATE_DELAY_MS = 100;
+
+/**
+ * Find a mention node in the document that contains an item with the given UUID.
+ */
+function findMentionNodeByItemUuid(
+  editor: Editor,
+  itemUuid: string,
+): { pos: number; node: ReturnType<Editor['state']['doc']['nodeAt']> } | undefined {
+  const { doc } = editor.state;
+  let result: { pos: number; node: ReturnType<typeof doc.nodeAt> } | undefined;
+
+  doc.descendants((node, pos) => {
+    if (result) return false;
+    if (node.type.name === 'mention') {
+      const items: MentionItem[] = node.attrs.items || [];
+      if (items.some((item) => item.uuid === itemUuid)) {
+        result = { pos, node };
+        return false;
+      }
+    }
+    return true;
+  });
+
+  return result;
+}
+
+export const MentionHoverContent = ({
+  uuid,
+  entityType,
+  entity,
+  editor,
+}: {
+  uuid: string;
+  entityType: string;
+  entity: string;
+  editor: Editor;
+  anchor: HTMLElement;
+}) => {
+  const [isEditing, setIsEditingLocal] = useState(false);
+  const { close, setIsEditing: setIsEditingContext } = useHoverCard();
+
+  const setIsEditing = useCallback(
+    (editing: boolean) => {
+      setIsEditingLocal(editing);
+      setIsEditingContext(editing);
+    },
+    [setIsEditingContext],
+  );
+
+  const deleteMention = useCallback(() => {
+    setIsEditing(false);
+    close();
+
+    setTimeout(() => {
+      const found = findMentionNodeByItemUuid(editor, uuid);
+      if (!found || !found.node) {
+        console.warn('Mention node not found in the document.');
+        return;
+      }
+
+      const { pos, node } = found;
+      const items: MentionItem[] = (node.attrs.items || []).filter(
+        (item: MentionItem) => item.uuid !== uuid,
+      );
+
+      const { tr } = editor.state;
+      if (items.length === 0) {
+        // Delete the entire node
+        tr.delete(pos, pos + node.nodeSize);
+      } else {
+        // Update items array without deleted item
+        tr.setNodeMarkup(pos, undefined, { ...node.attrs, items });
+      }
+      editor.view.dispatch(tr);
+    }, EDITOR_UPDATE_DELAY_MS);
+  }, [editor, uuid, close, setIsEditing]);
+
+  const updateMention = useCallback(
+    (newType: string, newEntity: string) => {
+      setIsEditing(false);
+      close();
+
+      setTimeout(() => {
+        const found = findMentionNodeByItemUuid(editor, uuid);
+        if (!found || !found.node) {
+          console.warn('Mention node not found in the document.');
+          return;
+        }
+
+        const { pos, node } = found;
+        const items: MentionItem[] = (node.attrs.items || []).map(
+          (item: MentionItem) =>
+            item.uuid === uuid
+              ? { ...item, entity: newEntity, linkType: newType }
+              : item,
+        );
+
+        const { tr } = editor.state;
+        tr.setNodeMarkup(pos, undefined, { ...node.attrs, items });
+        editor.view.dispatch(tr);
+      }, EDITOR_UPDATE_DELAY_MS);
+    },
+    [editor, uuid, close, setIsEditing],
+  );
+
+  return (
+    <div className="flex justify-between gap-2 p-2 w-fit max-w-80">
+      {isEditing ? (
+        <InternalLinkInput
+          type={entityType}
+          uuid={entity}
+          onSubmit={(type, entityVal) => {
+            if (type && entityVal) {
+              updateMention(type, entityVal);
+            } else {
+              deleteMention();
+            }
+            setIsEditing(false);
+          }}
+        />
+      ) : (
+        <>
+          <span className="text-primary text-sm my-auto">{entityType}</span>
+          <ChevronRightIcon className="my-auto size-4" />
+          <span className="truncate text-muted-foreground text-sm my-auto">
+            {entity}
+          </span>
+          <span className="flex-grow" />
+          <Button
+            variant="ghost"
+            size="icon"
+            className="size-6 [&_svg]:size-4"
+            onClick={() => setIsEditing(true)}
+          >
+            <PencilIcon className="text-primary my-auto" />
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon"
+            className="size-6 [&_svg]:size-4"
+            onClick={deleteMention}
+          >
+            <Trash2Icon className="text-destructive my-auto" />
+          </Button>
+        </>
+      )}
+    </div>
+  );
+};

package/src/lib/components/editor/extensions/NodeWrapper.tsx

@@ -0,0 +1,57 @@
+import {
+  NodeViewContent,
+  NodeViewProps,
+  NodeViewRendererOptions,
+  NodeViewWrapper,
+  ReactNodeViewRenderer,
+} from '@tiptap/react';
+import { JSX, ReactNode, useEffect } from 'react';
+import { validateAttrs } from '../util';
+
+export interface NodeWrapperProps extends NodeViewProps {
+  className?: string;
+  innerClassName?: string;
+  children?: ReactNode;
+  wrapperAs?: keyof JSX.IntrinsicElements;
+  contentAs?: keyof JSX.IntrinsicElements;
+}
+
+export const NodeWrapper = ({
+  node,
+  editor,
+  className,
+  innerClassName,
+  children,
+  wrapperAs = 'div',
+  contentAs = 'div',
+  getPos,
+  updateAttributes,
+}: NodeWrapperProps) => {
+  useEffect(() => {
+    validateAttrs({ node, editor, getPos, updateAttributes });
+  }, [node, editor, getPos, updateAttributes]);
+
+  return (
+    <NodeViewWrapper id={node.attrs.uuid} as={wrapperAs} className={className}>
+      {children}
+      {/* @ts-expect-error: NodeViewContent is only typed for div, but any element works */}
+      <NodeViewContent as={contentAs} className={innerClassName} />
+    </NodeViewWrapper>
+  );
+};
+
+export interface CreateNodeWrapperOptions extends NodeViewRendererOptions {
+  className?: string;
+  innerClassName?: string;
+  children?: ReactNode;
+  wrapperAs?: keyof JSX.IntrinsicElements;
+  contentAs?: keyof JSX.IntrinsicElements;
+}
+
+export const createNodeWrapper = (
+  options: Partial<Omit<NodeWrapperProps, keyof NodeViewProps>> = {},
+) => {
+  return ReactNodeViewRenderer((props: NodeViewProps) => (
+    <NodeWrapper {...props} {...options} />
+  ));
+};

package/src/lib/components/editor/extensions/Paragraph/Paragraph.ts

@@ -0,0 +1,25 @@
+import TiptapParagraph from '@tiptap/extension-paragraph';
+import { createNodeViewDom } from '../../util';
+
+export const Paragraph = TiptapParagraph.extend({
+  addNodeView() {
+    return ({ node, extension, editor, getPos, HTMLAttributes }) => {
+      const { dom } = createNodeViewDom({
+        editor,
+        getPos,
+        node,
+        extension,
+        HTMLAttributes,
+        element: 'p',
+        className: 'paragraph',
+      });
+
+      return {
+        dom,
+        contentDOM: dom,
+      };
+    };
+  },
+});
+
+export default Paragraph;

package/src/lib/components/editor/extensions/ParagraphIndent.ts

@@ -0,0 +1,87 @@
+import { Extension, mergeAttributes } from '@tiptap/core';
+
+export interface ParagraphIndentOptions {
+  types: string[];
+  defaultHasParagraphIndent: boolean;
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    paragraphIndent: {
+      /**
+       * Add an indent
+       */
+      setParagraphIndent: () => ReturnType;
+      /**
+       * Remove an indent
+       */
+      unsetParagraphIndent: () => ReturnType;
+
+      /**
+       * Toggle an indent
+       */
+      toggleParagraphIndent: () => ReturnType;
+    };
+  }
+}
+
+export const ParagraphIndent = Extension.create<ParagraphIndentOptions>({
+  name: 'paragraphIndent',
+  addOptions() {
+    return {
+      types: ['paragraph'],
+      defaultHasParagraphIndent: false,
+    };
+  },
+  addGlobalAttributes() {
+    return [
+      {
+        types: this.options.types,
+        attributes: {
+          hasParagraphIndent: {
+            default: this.options.defaultHasParagraphIndent,
+            parseHTML: (element) =>
+              element.className.includes('conditional-indent'),
+            renderHTML: (attributes) => {
+              if (attributes.hasParagraphIndent) {
+                return mergeAttributes(attributes, {
+                  class: 'conditional-indent',
+                });
+              }
+              return mergeAttributes(attributes, { class: 'no-indent' });
+            },
+          },
+        },
+      },
+    ];
+  },
+
+  addCommands() {
+    return {
+      setParagraphIndent:
+        () =>
+        ({ commands }) => {
+          return this.options.types
+            .map((type) =>
+              commands.updateAttributes(type, { hasParagraphIndent: true }),
+            )
+            .every((response) => response);
+        },
+      unsetParagraphIndent:
+        () =>
+        ({ commands }) => {
+          return this.options.types
+            .map((type) => commands.resetAttributes(type, 'hasParagraphIndent'))
+            .every((response) => response);
+        },
+      toggleParagraphIndent:
+        () =>
+        ({ editor, commands }) => {
+          if (editor.isActive({ hasParagraphIndent: true })) {
+            return commands.unsetParagraphIndent();
+          }
+          return commands.setParagraphIndent();
+        },
+    };
+  },
+});

package/src/lib/components/editor/extensions/Passage/EditLabel.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import {
+  Button,
+  DialogContent,
+  DialogDescription,
+  DialogTitle,
+  Input,
+} from '@eightyfourthousand/design-system';
+import { NodeViewProps } from '@tiptap/react';
+import { ChangeEvent, useCallback, useState } from 'react';
+
+export const EditLabel = ({
+  node,
+  updateAttributes,
+  close,
+}: NodeViewProps & { close: () => void }) => {
+  const [newLabel, setNewLabel] = useState(node.attrs.label || '');
+  const updateNewLabel = (event: ChangeEvent<HTMLInputElement>) => {
+    setNewLabel(event.target.value);
+  };
+
+  const save = useCallback(() => {
+    updateAttributes({ label: newLabel });
+    close();
+  }, [newLabel, updateAttributes, close]);
+
+  return (
+    <DialogContent className="sm:max-w-lg">
+      <DialogTitle>Edit Passage Label</DialogTitle>
+      <DialogDescription>{`Update the label for passage ${node.attrs.label}`}</DialogDescription>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          save();
+        }}
+      >
+        <Input
+          type="text"
+          value={newLabel}
+          onChange={updateNewLabel}
+          onBlur={updateNewLabel}
+          className="mt-2"
+          placeholder="X.X"
+        />
+        <div className="mt-4 flex justify-end gap-2">
+          <Button variant="outline" type="button" onClick={close}>
+            Cancel
+          </Button>
+          <Button variant="default" size="sm" type="submit" className="px-5">
+            Save
+          </Button>
+        </div>
+      </form>
+    </DialogContent>
+  );
+};

package/src/lib/components/editor/extensions/Passage/EditorOptions.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import { DropdownMenuItem, DropdownMenuSeparator } from '@eightyfourthousand/design-system';
+import { BracesIcon, PencilIcon, Trash2Icon } from 'lucide-react';
+
+export const EditorOptions = ({
+  onSelection,
+}: {
+  onSelection: (item: string) => void;
+}) => {
+  return (
+    <>
+      <DropdownMenuItem onSelect={() => onSelection('label')}>
+        <PencilIcon className="text-ochre" /> Edit Label
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuItem onSelect={() => onSelection('attributes')}>
+        <BracesIcon className="text-ochre" /> View Attributes
+      </DropdownMenuItem>
+      <DropdownMenuSeparator />
+      <DropdownMenuItem
+        onSelect={() => onSelection('delete')}
+        className="text-destructive"
+      >
+        <Trash2Icon className="text-destructive" /> Delete
+      </DropdownMenuItem>
+    </>
+  );
+};