@puredesktop/platform-editor 1.0.0-beta.1

package/src/extensions/footnote.ts

@@ -0,0 +1,186 @@
+import { Node, mergeAttributes } from '@tiptap/core'
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    footnote: {
+      /** Insert an empty footnote marker at the cursor and open it to edit. */
+      insertFootnote: () => ReturnType
+    }
+  }
+}
+
+/**
+ * Footnote — an inline, atomic reference marker.
+ *
+ * The body shows only a small superscript number; the note text is embedded on
+ * the node (the `text` attribute) and edited in a popover when the marker is
+ * clicked. Numbering is by document order, recomputed live. Serializes to
+ * `<sup data-footnote data-text="…">` for a clean HTML round-trip; the export
+ * pipeline (prepareFootnotes) turns markers into numbered links plus a
+ * footnotes section.
+ */
+export const Footnote = Node.create({
+  name: 'footnote',
+  group: 'inline',
+  inline: true,
+  atom: true,
+  selectable: true,
+
+  addAttributes() {
+    return {
+      text: {
+        default: '',
+        parseHTML: el => el.getAttribute('data-text') ?? '',
+        renderHTML: (attrs: { text?: string }) => ({
+          'data-text': attrs.text ?? '',
+        }),
+      },
+    }
+  },
+
+  parseHTML() {
+    return [{ tag: 'sup[data-footnote]' }]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return [
+      'sup',
+      mergeAttributes(HTMLAttributes, {
+        'data-footnote': '',
+        class: 'footnote-ref',
+      }),
+    ]
+  },
+
+  addCommands() {
+    return {
+      insertFootnote:
+        () =>
+        ({ commands }) =>
+          commands.insertContent({ type: this.name, attrs: { text: '' } }),
+    }
+  },
+
+  addNodeView() {
+    return ({ node, getPos, editor }) => {
+      let current = node
+      const dom = document.createElement('sup')
+      dom.className = 'footnote-ref'
+      dom.setAttribute('data-footnote', '')
+      dom.contentEditable = 'false'
+
+      const renderNumber = (): void => {
+        let count = 0
+        let mine = 0
+        const here = typeof getPos === 'function' ? getPos() : null
+        editor.state.doc.descendants((child, pos) => {
+          if (child.type.name === 'footnote') {
+            count += 1
+            if (here !== null && pos === here) mine = count
+          }
+          return true
+        })
+        dom.textContent = String(mine || count || 1)
+      }
+      renderNumber()
+
+      let popover: HTMLDivElement | null = null
+      const closePopover = (): void => {
+        popover?.remove()
+        popover = null
+        document.removeEventListener('mousedown', onDocPointerDown, true)
+      }
+      const onDocPointerDown = (event: MouseEvent): void => {
+        if (
+          popover &&
+          event.target !== dom &&
+          !popover.contains(event.target as globalThis.Node)
+        ) {
+          closePopover()
+        }
+      }
+      const openPopover = (): void => {
+        if (popover) return
+        popover = document.createElement('div')
+        popover.className = 'footnote-popover'
+        Object.assign(popover.style, {
+          position: 'fixed',
+          zIndex: '1002',
+          width: 'min(360px, calc(100vw - 24px))',
+          padding: '8px',
+          border: '1px solid var(--platform-colors-border, #d7dbe0)',
+          borderRadius: '8px',
+          background: 'var(--platform-colors-surface, #fff)',
+          boxShadow: '0 18px 42px rgb(23 29 36 / 0.18)',
+        })
+        const textarea = document.createElement('textarea')
+        textarea.value = current.attrs.text ?? ''
+        textarea.placeholder = 'Footnote text…'
+        textarea.rows = 3
+        Object.assign(textarea.style, {
+          width: '100%',
+          boxSizing: 'border-box',
+          resize: 'vertical',
+          border: '1px solid var(--platform-colors-border, #d7dbe0)',
+          borderRadius: '6px',
+          padding: '6px 8px',
+          font: 'inherit',
+          fontSize: '13px',
+          color: 'inherit',
+          background: 'var(--platform-colors-surface, #fff)',
+        })
+        popover.appendChild(textarea)
+
+        const rect = dom.getBoundingClientRect()
+        popover.style.left = `${Math.max(12, rect.left)}px`
+        popover.style.top = `${rect.bottom + 6}px`
+        document.body.appendChild(popover)
+        textarea.focus()
+
+        const commit = (): void => {
+          if (typeof getPos !== 'function') return
+          const pos = getPos()
+          if (typeof pos !== 'number') return
+          const next = textarea.value
+          if (next === (current.attrs.text ?? '')) return
+          editor.view.dispatch(
+            editor.state.tr.setNodeMarkup(pos, undefined, {
+              ...current.attrs,
+              text: next,
+            }),
+          )
+        }
+        textarea.addEventListener('blur', () => {
+          commit()
+          closePopover()
+        })
+        textarea.addEventListener('keydown', event => {
+          if (event.key === 'Escape') {
+            event.preventDefault()
+            commit()
+            closePopover()
+            editor.commands.focus()
+          }
+        })
+        document.addEventListener('mousedown', onDocPointerDown, true)
+      }
+
+      dom.addEventListener('mousedown', event => {
+        event.preventDefault()
+        openPopover()
+      })
+
+      return {
+        dom,
+        update: updated => {
+          if (updated.type.name !== 'footnote') return false
+          current = updated
+          renderNumber()
+          return true
+        },
+        ignoreMutation: () => true,
+        destroy: closePopover,
+      }
+    }
+  },
+})

package/src/extensions/indexMarker.ts

@@ -0,0 +1,88 @@
+import { Mark, mergeAttributes } from '@tiptap/core'
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    indexMarker: {
+      /**
+       * Wrap the current selection in an `<a class="ix" id="ix-{slug}">`
+       * marker. The slug is derived from the selected text. Multiple
+       * markers per term are fine — the render pipeline groups by term.
+       */
+      toggleIndexMarker: () => ReturnType
+    }
+  }
+}
+
+/**
+ * Inline index anchor. Renders as a faint dotted underline in the
+ * editor; invisible in print output (the wrapping `<a>` carries the
+ * data the index generator collects but is otherwise display-none in
+ * print.css). Markdown round-trip stores the marker as inline HTML
+ * since CommonMark has no native concept for this.
+ */
+export const IndexMarker = Mark.create({
+  name: 'indexMarker',
+  inclusive: false,
+  excludes: '',
+
+  addAttributes() {
+    return {
+      term: {
+        default: null,
+        parseHTML: el => el.getAttribute('data-term'),
+        renderHTML: (attrs: { term?: string }) =>
+          attrs.term ? { 'data-term': attrs.term } : {},
+      },
+    }
+  },
+
+  parseHTML() {
+    return [
+      {
+        tag: 'a.ix',
+        getAttrs: el => ({
+          term: (el as HTMLElement).getAttribute('data-term'),
+        }),
+      },
+    ]
+  },
+
+  renderHTML({ HTMLAttributes, mark }) {
+    const term = (mark.attrs as { term?: string }).term ?? ''
+    const id = term ? `ix-${slugify(term)}` : undefined
+    return [
+      'a',
+      mergeAttributes(HTMLAttributes, {
+        class: 'ix',
+        ...(id ? { id } : {}),
+        ...(term ? { 'data-term': term } : {}),
+      }),
+      0,
+    ]
+  },
+
+  addCommands() {
+    return {
+      toggleIndexMarker:
+        () =>
+        ({ state, chain }) => {
+          const { from, to } = state.selection
+          if (from === to) return false
+          const term = state.doc.textBetween(from, to, ' ').trim()
+          if (!term) return false
+          if (state.doc.rangeHasMark(from, to, this.type)) {
+            return chain().focus().unsetMark(this.name).run()
+          }
+          return chain().focus().setMark(this.name, { term }).run()
+        },
+    }
+  },
+})
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}

package/src/extensions/mathEditing.ts

@@ -0,0 +1,239 @@
+import { Extension } from '@tiptap/core'
+import type { Editor } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import katex from 'katex'
+
+/**
+ * Editing UX for the KaTeX math nodes (@tiptap/extension-mathematics only
+ * renders + fires onClick — it has no editor). This adds:
+ *  - a floating editor with a LIVE preview as you type;
+ *  - click a rendered equation to edit it;
+ *  - insert-and-edit commands so a new equation is editable immediately and
+ *    renders in place when you click out (empty equations are discarded).
+ */
+
+const MATH_TYPES = new Set(['inlineMath', 'blockMath'])
+
+let closeActive: (() => void) | null = null
+
+function findMathPosNear(editor: Editor, typeName: string): number | null {
+  const { from, to } = editor.state.selection
+  const docSize = editor.state.doc.content.size
+  let found: number | null = null
+  editor.state.doc.nodesBetween(
+    Math.max(0, from - 2),
+    Math.min(docSize, to + 2),
+    (node, pos) => {
+      if (node.type.name === typeName) found = pos
+    },
+  )
+  return found
+}
+
+/** Open the floating LaTeX editor for the math node at `pos`. */
+export function openMathEditor(editor: Editor, pos: number): void {
+  closeActive?.()
+  const node = editor.state.doc.nodeAt(pos)
+  if (!node || !MATH_TYPES.has(node.type.name)) return
+  const isInline = node.type.name === 'inlineMath'
+
+  const popover = document.createElement('div')
+  popover.className = 'math-editor-popover'
+  Object.assign(popover.style, {
+    position: 'fixed',
+    zIndex: '1003',
+    width: 'min(440px, calc(100vw - 24px))',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: '8px',
+    padding: '10px',
+    borderRadius: '8px',
+    border: '1px solid var(--platform-colors-border, #d7dbe0)',
+    background: 'var(--platform-colors-surface, #fff)',
+    boxShadow: '0 18px 42px rgb(23 29 36 / 0.18)',
+  })
+
+  const preview = document.createElement('div')
+  Object.assign(preview.style, {
+    minHeight: '30px',
+    padding: '6px 8px',
+    borderRadius: '6px',
+    background: 'var(--platform-colors-bg, #f5f6f7)',
+    color: 'var(--platform-colors-text, inherit)',
+    overflowX: 'auto',
+    textAlign: isInline ? 'left' : 'center',
+  })
+
+  const input = document.createElement('textarea')
+  // ' ' is the empty sentinel used by the insert-and-edit commands.
+  const initialLatex = (node.attrs.latex as string) ?? ''
+  input.value = initialLatex === ' ' ? '' : initialLatex
+  input.rows = 2
+  input.spellcheck = false
+  input.placeholder = isInline
+    ? 'Inline LaTeX — e.g. E = mc^2'
+    : 'Display LaTeX — e.g. \\frac{a}{b}'
+  Object.assign(input.style, {
+    width: '100%',
+    boxSizing: 'border-box',
+    resize: 'vertical',
+    border: '1px solid var(--platform-colors-border, #d7dbe0)',
+    borderRadius: '6px',
+    padding: '6px 8px',
+    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+    fontSize: '13px',
+    color: 'inherit',
+    background: 'var(--platform-colors-surface, #fff)',
+  })
+
+  const hint = document.createElement('div')
+  hint.textContent = 'Live preview · Esc to cancel · click away to apply'
+  Object.assign(hint.style, {
+    fontSize: '11px',
+    color: 'var(--platform-colors-text-secondary, #8a8f98)',
+  })
+
+  popover.append(preview, input, hint)
+  document.body.appendChild(popover)
+
+  const renderPreview = (): void => {
+    const latex = input.value.trim()
+    if (!latex) {
+      preview.textContent = ''
+      return
+    }
+    try {
+      katex.render(latex, preview, { displayMode: !isInline, throwOnError: false })
+    } catch {
+      preview.textContent = input.value
+    }
+  }
+  input.addEventListener('input', renderPreview)
+  renderPreview()
+
+  try {
+    const coords = editor.view.coordsAtPos(pos)
+    popover.style.left = `${Math.max(12, Math.min(coords.left, window.innerWidth - 460))}px`
+    popover.style.top = `${Math.min(coords.bottom + 6, window.innerHeight - 160)}px`
+  } catch {
+    popover.style.left = '50%'
+    popover.style.top = '140px'
+    popover.style.transform = 'translateX(-50%)'
+  }
+
+  input.focus()
+  input.select()
+
+  let closed = false
+  const teardown = (): void => {
+    if (closed) return
+    closed = true
+    popover.remove()
+    document.removeEventListener('mousedown', onDocPointerDown, true)
+    closeActive = null
+  }
+  const nodeRange = (): { from: number; size: number } | null => {
+    const current = editor.state.doc.nodeAt(pos)
+    if (!current || !MATH_TYPES.has(current.type.name)) return null
+    return { from: pos, size: current.nodeSize }
+  }
+  const apply = (): void => {
+    const range = nodeRange()
+    if (range) {
+      const latex = input.value
+      const current = editor.state.doc.nodeAt(pos)
+      if (!latex.trim()) {
+        editor.view.dispatch(editor.state.tr.delete(range.from, range.from + range.size))
+      } else if (current && latex !== current.attrs.latex) {
+        editor.view.dispatch(
+          editor.state.tr.setNodeMarkup(pos, undefined, {
+            ...current.attrs,
+            latex,
+          }),
+        )
+      }
+    }
+    teardown()
+    editor.commands.focus()
+  }
+  const cancel = (): void => {
+    const range = nodeRange()
+    const current = range ? editor.state.doc.nodeAt(pos) : null
+    // Discard an equation that was never given any LaTeX (just inserted).
+    if (range && current && !((current.attrs.latex as string) ?? '').trim()) {
+      editor.view.dispatch(editor.state.tr.delete(range.from, range.from + range.size))
+    }
+    teardown()
+    editor.commands.focus()
+  }
+
+  input.addEventListener('keydown', event => {
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      cancel()
+    } else if (
+      event.key === 'Enter' &&
+      (isInline ? !event.shiftKey : event.metaKey || event.ctrlKey)
+    ) {
+      event.preventDefault()
+      apply()
+    }
+  })
+  input.addEventListener('blur', () => {
+    window.setTimeout(apply, 0)
+  })
+  const onDocPointerDown = (event: MouseEvent): void => {
+    if (!popover.contains(event.target as globalThis.Node)) apply()
+  }
+  document.addEventListener('mousedown', onDocPointerDown, true)
+  closeActive = cancel
+}
+
+type MathChain = ReturnType<Editor['chain']> & {
+  insertInlineMath?: (options: { latex: string }) => ReturnType<Editor['chain']>
+  insertBlockMath?: (options: { latex: string }) => ReturnType<Editor['chain']>
+}
+
+/** Insert an empty inline equation and open its editor immediately. */
+export function insertEditableInlineMath(editor: Editor): void {
+  const chain = editor.chain().focus() as MathChain
+  if (typeof chain.insertInlineMath !== 'function') {
+    chain.run()
+    return
+  }
+  chain.insertInlineMath({ latex: ' ' }).run()
+  const pos = findMathPosNear(editor, 'inlineMath')
+  if (pos != null) openMathEditor(editor, pos)
+}
+
+/** Insert an empty display equation and open its editor immediately. */
+export function insertEditableBlockMath(editor: Editor): void {
+  const chain = editor.chain().focus() as MathChain
+  if (typeof chain.insertBlockMath !== 'function') {
+    chain.run()
+    return
+  }
+  chain.insertBlockMath({ latex: ' ' }).run()
+  const pos = findMathPosNear(editor, 'blockMath')
+  if (pos != null) openMathEditor(editor, pos)
+}
+
+export const MathEditing = Extension.create({
+  name: 'mathEditing',
+
+  addProseMirrorPlugins() {
+    const editor = this.editor
+    return [
+      new Plugin({
+        key: new PluginKey('mathEditing'),
+        props: {
+          handleClickOn: (_view, _pos, node, nodePos) => {
+            if (!MATH_TYPES.has(node.type.name)) return false
+            openMathEditor(editor, nodePos)
+            return true
+          },
+        },
+      }),
+    ]
+  },
+})