@fnix/lexxy-mathjax 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# @fnix/lexxy-mathjax
+
+LaTeX equations for [Lexxy](https://lexxy.dev) (the rich text editor for Rails), rendered with [MathJax](https://www.mathjax.org).
+
+- Toolbar button (and `Cmd/Ctrl+Shift+E`) opens a dialog with a LaTeX input and live preview
+- Click any equation to edit it
+- Inline (`e^{i\pi} + 1 = 0` in a sentence) and display/block modes
+- Saved HTML stores the raw LaTeX in a `data-latex` attribute, so content round-trips cleanly and is typeset again on display pages
+
+## How it works
+
+Equations are stored in the document (and in what ActionText persists) as:
+
+```html
+<span class="lexxy-math" data-latex="\frac{a}{b}">\frac{a}{b}</span>   <!-- inline -->
+<div  class="lexxy-math" data-latex="\int_0^1 x\,dx">...</div>         <!-- display/block -->
+```
+
+Inside the editor the extension typesets these with the page's MathJax. **MathJax is host-provided, not bundled**: load MathJax v3 (`tex-chtml`) on any page that uses the editor or displays saved content.
+
+## Installation
+
+### With importmap-rails (no build)
+
+Vendor this package (or pin it) and pin lexxy's bare specifier so the extension resolves it:
+
+```ruby
+# config/importmap.rb
+pin "lexxy"                                        # from the lexxy gem, per lexxy's install docs
+pin "@37signals/lexxy", to: "lexxy.js"             # alias used by @fnix/lexxy-mathjax
+pin "@fnix/lexxy-mathjax", to: "lexxy-mathjax/index.js"  # vendored src/ of this package
+# ...pin the files under src/ as well if vendoring, e.g. via pin_all_from
+```
+
+### With a JS bundler (esbuild / vite / webpack)
+
+```bash
+npm install @fnix/lexxy-mathjax @37signals/lexxy
+```
+
+### Register the extension
+
+```js
+import { configure } from "@37signals/lexxy"
+import MathjaxExtension from "@fnix/lexxy-mathjax"
+
+configure({
+  global: { extensions: [ MathjaxExtension ] }
+})
+```
+
+Include the stylesheet (`@fnix/lexxy-mathjax/styles`, or copy `styles/lexxy-mathjax.css` into your assets).
+
+### Load MathJax
+
+```html
+<script>
+  window.MathJax = { chtml: { displayAlign: "center" } }
+</script>
+<script async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
+```
+
+If MathJax is missing, the editor still works and equations show their raw LaTeX.
+
+## Rails / ActionText integration
+
+**1. Allow `data-latex` through the server-side sanitizer** (ActionText strips unknown attributes when rendering):
+
+```ruby
+# config/initializers/lexxy_mathjax.rb
+ActiveSupport.on_load(:action_text_content) do
+  ActionText::ContentHelper.allowed_attributes += [ "data-latex" ]
+end
+```
+
+**2. Typeset saved content on display pages.** Load MathJax (as above) plus a small script that renders `[data-latex]` elements, Turbo-compatible:
+
+```js
+function typesetEquations() {
+  const elements = document.querySelectorAll(".trix-content [data-latex], .lexxy-content [data-latex]")
+  if (elements.length === 0 || !window.MathJax?.typesetPromise) return
+
+  elements.forEach((el) => { el.textContent = el.getAttribute("data-latex") })
+  window.MathJax.typesetPromise([ ...elements ])
+}
+
+document.addEventListener("turbo:load", typesetEquations)
+document.addEventListener("DOMContentLoaded", typesetEquations)
+```
+
+Note: `typesetPromise` scans for `\(...\)` delimiters by default; the snippet above instead sets each element's content from `data-latex` and typesets just those elements. If you prefer delimiter scanning, configure `tex.inlineMath` accordingly.
+
+## Demo
+
+Try it online: https://fnix.github.io/lexxy-mathjax/
+
+Or serve the repo statically and open the demo locally:
+
+```bash
+npx serve .
+# then visit http://localhost:3000/demo/
+```
+
+## Tests
+
+```bash
+npm install
+npm test
+```
+
+## Development notes
+
+The code follows lexxy's own conventions: plain ES modules, vanilla JS, no build step. Structure:
+
+- `src/nodes/math_node.js` — `DecoratorNode` storing `{ latex, display }`; `createDOM` typesets with MathJax, `exportDOM`/`importDOM` handle the `data-latex` HTML format
+- `src/extensions/mathjax_extension.js` — the `Lexxy.Extension`: registers the node, the `insertMath` command, the toolbar button, and click-to-edit
+- `src/elements/math_editor_dialog.js` — `<lexxy-math-editor>` dialog with live preview
+- `src/helpers/mathjax_helper.js` — serialized MathJax typesetting with graceful degradation

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@fnix/lexxy-mathjax",
+  "version": "0.1.0",
+  "description": "MathJax LaTeX equation extension for Lexxy, the rich text editor for Rails.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./styles": "./styles/lexxy-mathjax.css"
+  },
+  "files": [
+    "src",
+    "styles"
+  ],
+  "keywords": [
+    "lexxy",
+    "lexical",
+    "mathjax",
+    "latex",
+    "rails",
+    "actiontext"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnix/lexxy-mathjax.git"
+  },
+  "homepage": "https://github.com/fnix/lexxy-mathjax#readme",
+  "bugs": {
+    "url": "https://github.com/fnix/lexxy-mathjax/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@37signals/lexxy": ">= 0.9.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "demo": "npx serve ."
+  },
+  "devDependencies": {
+    "@37signals/lexxy": "^0.9.24",
+    "jsdom": "^27.0.0",
+    "vitest": "^4.0.0"
+  }
+}

package/src/elements/math_editor_dialog.js

@@ -0,0 +1,117 @@
+import { typesetInto } from "../helpers/mathjax_helper.js"
+
+const PREVIEW_DEBOUNCE_INTERVAL = 150
+
+export class MathEditorDialogElement extends HTMLElement {
+  #resolve = null
+  #previewTimer = null
+
+  connectedCallback() {
+    this.innerHTML = this.constructor.template
+    this.dialog = this.querySelector("dialog")
+    this.textarea = this.querySelector("textarea")
+    this.displayCheckbox = this.querySelector("input[name='display']")
+    this.preview = this.querySelector(".lexxy-math-editor__preview")
+
+    this.querySelector("form").addEventListener("submit", this.#handleSubmit)
+    this.dialog.addEventListener("close", this.#handleClose)
+    this.textarea.addEventListener("input", this.#schedulePreview)
+    this.textarea.addEventListener("keydown", this.#handleTextareaKeydown)
+    this.displayCheckbox.addEventListener("change", this.#refreshPreview)
+    this.querySelector("[data-behavior='cancel']").addEventListener("click", () => this.dialog.close())
+  }
+
+  disconnectedCallback() {
+    clearTimeout(this.#previewTimer)
+    this.#settle(null)
+  }
+
+  // Shows the dialog and resolves with { latex, display } on confirm, null on cancel.
+  open({ latex = "", display = false } = {}) {
+    this.textarea.value = latex
+    this.displayCheckbox.checked = display
+    this.#refreshPreview()
+
+    this.dialog.showModal()
+    this.textarea.focus()
+    this.textarea.select()
+
+    return new Promise((resolve) => {
+      this.#resolve = resolve
+    })
+  }
+
+  #handleSubmit = (event) => {
+    event.preventDefault()
+
+    const latex = this.textarea.value.trim()
+    this.#settle(latex ? { latex, display: this.displayCheckbox.checked } : null)
+    this.dialog.close()
+  }
+
+  #handleClose = () => {
+    this.#settle(null)
+  }
+
+  #handleTextareaKeydown = (event) => {
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault()
+      this.querySelector("form").requestSubmit()
+    }
+  }
+
+  #schedulePreview = () => {
+    clearTimeout(this.#previewTimer)
+    this.#previewTimer = setTimeout(this.#refreshPreview, PREVIEW_DEBOUNCE_INTERVAL)
+  }
+
+  #refreshPreview = () => {
+    const latex = this.textarea.value.trim()
+
+    if (latex) {
+      typesetInto(this.preview, latex, { display: this.displayCheckbox.checked })
+    } else {
+      this.preview.textContent = ""
+    }
+  }
+
+  #settle(result) {
+    if (this.#resolve) {
+      const resolve = this.#resolve
+      this.#resolve = null
+      resolve(result)
+    }
+  }
+
+  static get template() {
+    return `
+      <dialog class="lexxy-math-editor">
+        <form method="dialog" novalidate>
+          <label class="lexxy-math-editor__label">
+            LaTeX
+            <textarea name="latex" rows="3" spellcheck="false" autocomplete="off" placeholder="\\frac{a}{b}"></textarea>
+          </label>
+
+          <div class="lexxy-math-editor__preview" aria-live="polite"></div>
+
+          <div class="lexxy-math-editor__footer">
+            <label class="lexxy-math-editor__display-toggle">
+              <input type="checkbox" name="display"> Display as block
+            </label>
+
+            <div class="lexxy-math-editor__actions">
+              <button type="button" data-behavior="cancel">Cancel</button>
+              <button type="submit" data-behavior="confirm">Save</button>
+            </div>
+          </div>
+        </form>
+      </dialog>
+    `
+  }
+}
+
+export function defineMathEditorDialogElement() {
+  if (!customElements.get("lexxy-math-editor")) {
+    customElements.define("lexxy-math-editor", MathEditorDialogElement)
+  }
+}

package/src/extensions/mathjax_extension.js

@@ -0,0 +1,154 @@
+import { Extension, Lexical } from "@37signals/lexxy"
+import { MathNode, $createMathNode, $isMathNode } from "../nodes/math_node.js"
+import { defineMathEditorDialogElement } from "../elements/math_editor_dialog.js"
+
+const {
+  $getNearestNodeFromDOMNode,
+  $getNodeByKey,
+  $insertNodes,
+  COMMAND_PRIORITY_NORMAL,
+  createCommand
+} = Lexical
+
+export const INSERT_MATH_COMMAND = createCommand("INSERT_MATH_COMMAND")
+
+// Square root of x, drawn to match lexxy's 18x18 filled toolbar icons
+const MATH_ICON = `
+  <svg viewBox="0 0 18 18" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+    <path d="M17 3.5V5.3H10.1L6.7 15.5H5.2L3.3 10.9H1.5V9.1H4.5L5.9 12.5L8.8 3.5Z"/>
+    <path d="M10.4 7.9L14.6 13.1M14.6 7.9L10.4 13.1" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" fill="none"/>
+  </svg>
+`
+
+export class MathjaxExtension extends Extension {
+  #dialog = null
+  #editor = null
+
+  get enabled() {
+    return this.editorElement.supportsRichText
+  }
+
+  get allowedElements() {
+    return [
+      { tag: "span", attributes: [ "data-latex" ] },
+      { tag: "div", attributes: [ "data-latex" ] }
+    ]
+  }
+
+  get lexicalExtension() {
+    const extension = this
+
+    return this.defineExtension({
+      name: "lexxy/mathjax",
+      nodes: [ MathNode ],
+      register(editor) {
+        extension.#editor = editor
+
+        const unregisterInsert = editor.registerCommand(INSERT_MATH_COMMAND, () => {
+          extension.#promptNewEquation()
+          return true
+        }, COMMAND_PRIORITY_NORMAL)
+
+        // String command so toolbar buttons can use data-command="insertMath"
+        const unregisterToolbarInsert = editor.registerCommand("insertMath", () => {
+          extension.#promptNewEquation()
+          return true
+        }, COMMAND_PRIORITY_NORMAL)
+
+        const unregisterClicks = editor.registerRootListener((rootElement, previousRootElement) => {
+          previousRootElement?.removeEventListener("click", extension.#handleEquationClicked)
+          rootElement?.addEventListener("click", extension.#handleEquationClicked)
+        })
+
+        return () => {
+          unregisterInsert()
+          unregisterToolbarInsert()
+          unregisterClicks()
+        }
+      }
+    })
+  }
+
+  initializeToolbar(toolbar) {
+    const button = document.createElement("button")
+    button.type = "button"
+    button.name = "math"
+    button.className = "lexxy-editor__toolbar-button"
+    button.title = "Insert equation"
+    button.setAttribute("data-command", "insertMath")
+    button.setAttribute("data-hotkey", "cmd+shift+e ctrl+shift+e")
+    button.innerHTML = MATH_ICON
+
+    toolbar.appendChild(button)
+    toolbar.requestOverflowRefresh?.()
+  }
+
+  dispose() {
+    this.#dialog?.remove()
+    this.#dialog = null
+    this.#editor = null
+  }
+
+  async #promptNewEquation() {
+    const result = await this.#openDialog()
+    if (!result) return
+
+    this.#editor.update(() => {
+      $insertNodes([ $createMathNode(result.latex, result.display) ])
+    })
+    this.#editor.focus()
+  }
+
+  #handleEquationClicked = async (event) => {
+    const element = event.target.closest(".lexxy-math")
+    if (!element) return
+
+    let nodeKey = null
+    this.#editor.read(() => {
+      const node = $getNearestNodeFromDOMNode(element)
+      if ($isMathNode(node)) nodeKey = node.getKey()
+    })
+    if (nodeKey === null) return
+
+    event.preventDefault()
+
+    let currentValues = null
+    this.#editor.read(() => {
+      const node = $getNodeByKey(nodeKey)
+      if ($isMathNode(node)) {
+        currentValues = { latex: node.getLatex(), display: node.isDisplay() }
+      }
+    })
+    if (!currentValues) return
+
+    const result = await this.#openDialog(currentValues)
+    if (!result) return
+
+    this.#editor.update(() => {
+      const node = $getNodeByKey(nodeKey)
+      if (!$isMathNode(node)) return
+
+      if (node.isDisplay() === result.display) {
+        node.setLatex(result.latex)
+      } else {
+        // Inline vs block affects where the node may live in the tree, so
+        // swap in a fresh node instead of mutating in place.
+        node.replace($createMathNode(result.latex, result.display))
+      }
+    })
+    this.#editor.focus()
+  }
+
+  #openDialog(values = {}) {
+    return this.#findOrCreateDialog().open(values)
+  }
+
+  #findOrCreateDialog() {
+    if (!this.#dialog || !this.#dialog.isConnected) {
+      defineMathEditorDialogElement()
+      this.#dialog = document.createElement("lexxy-math-editor")
+      document.body.appendChild(this.#dialog)
+    }
+    return this.#dialog
+  }
+}

package/src/helpers/mathjax_helper.js

@@ -0,0 +1,62 @@
+const MATHJAX_WAIT_ATTEMPTS = 40
+const MATHJAX_WAIT_INTERVAL = 250
+
+let warnedAboutMissingMathJax = false
+let renderQueue = Promise.resolve()
+
+// Resolves with window.MathJax once its startup has finished, or null if
+// MathJax never shows up (the host page is responsible for loading it).
+export async function findMathJax() {
+  for (let attempt = 0; attempt < MATHJAX_WAIT_ATTEMPTS; attempt++) {
+    if (window.MathJax?.startup?.promise) {
+      await window.MathJax.startup.promise
+      return window.MathJax
+    }
+    await sleep(MATHJAX_WAIT_INTERVAL)
+  }
+
+  if (!warnedAboutMissingMathJax) {
+    warnedAboutMissingMathJax = true
+    console.warn("@fnix/lexxy-mathjax: window.MathJax not found. Equations will show raw LaTeX. " +
+      "Load MathJax v3 (tex-chtml) on pages that use the editor.")
+  }
+
+  return null
+}
+
+// Typesets LaTeX into the given element, replacing its content. Falls back to
+// showing the raw LaTeX when MathJax is unavailable or the LaTeX is invalid.
+// Calls are serialized because MathJax's conversion pipeline is not reentrant.
+export function typesetInto(element, latex, { display = false } = {}) {
+  element.textContent = latex
+
+  renderQueue = renderQueue.then(async () => {
+    const mathjax = await findMathJax()
+    if (!mathjax) return
+
+    try {
+      const rendered = await mathjax.tex2chtmlPromise(latex, {
+        display,
+        em: 16,
+        ex: 8,
+        containerWidth: element.clientWidth || 780
+      })
+      element.replaceChildren(rendered)
+      element.classList.remove("lexxy-math--error")
+
+      // Refresh MathJax's global stylesheet so glyphs used by this equation render.
+      mathjax.startup.document.clear()
+      mathjax.startup.document.updateDocument()
+    } catch (error) {
+      element.textContent = latex
+      element.classList.add("lexxy-math--error")
+      element.title = `${error}`
+    }
+  })
+
+  return renderQueue
+}
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds))
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { MathjaxExtension, INSERT_MATH_COMMAND } from "./extensions/mathjax_extension.js"
+export { MathNode, $createMathNode, $isMathNode } from "./nodes/math_node.js"
+export { MathjaxExtension as default } from "./extensions/mathjax_extension.js"

package/src/nodes/math_node.js

@@ -0,0 +1,115 @@
+import { Lexical } from "@37signals/lexxy"
+import { typesetInto } from "../helpers/mathjax_helper.js"
+
+const { DecoratorNode } = Lexical
+
+export class MathNode extends DecoratorNode {
+  static getType() {
+    return "lexxy-math"
+  }
+
+  static clone(node) {
+    return new MathNode(node.__latex, node.__display, node.__key)
+  }
+
+  static importJSON(serializedNode) {
+    return $createMathNode(serializedNode.latex, serializedNode.display)
+  }
+
+  static importDOM() {
+    return {
+      span: (element) => $mathConversionFor(element, false),
+      div: (element) => $mathConversionFor(element, true)
+    }
+  }
+
+  constructor(latex = "", display = false, key) {
+    super(key)
+    this.__latex = latex
+    this.__display = display
+  }
+
+  getLatex() {
+    return this.__latex
+  }
+
+  setLatex(latex) {
+    this.getWritable().__latex = latex
+  }
+
+  isDisplay() {
+    return this.__display
+  }
+
+  setDisplay(display) {
+    this.getWritable().__display = display
+  }
+
+  isInline() {
+    return !this.__display
+  }
+
+  isKeyboardSelectable() {
+    return true
+  }
+
+  getTextContent() {
+    return this.__latex
+  }
+
+  createDOM() {
+    const element = document.createElement(this.__display ? "div" : "span")
+    element.className = this.__display ? "lexxy-math lexxy-math--display" : "lexxy-math"
+    element.setAttribute("role", "math")
+    element.setAttribute("aria-label", `Equation: ${this.__latex}`)
+    element.setAttribute("data-latex", this.__latex)
+
+    typesetInto(element, this.__latex, { display: this.__display })
+
+    return element
+  }
+
+  updateDOM() {
+    return true
+  }
+
+  exportDOM() {
+    const element = document.createElement(this.__display ? "div" : "span")
+    element.className = "lexxy-math"
+    element.setAttribute("data-latex", this.__latex)
+    element.textContent = this.__latex
+    return { element }
+  }
+
+  exportJSON() {
+    return {
+      type: "lexxy-math",
+      version: 1,
+      latex: this.__latex,
+      display: this.__display
+    }
+  }
+
+  decorate() {
+    return null
+  }
+}
+
+export function $createMathNode(latex = "", display = false) {
+  return new MathNode(latex, display)
+}
+
+export function $isMathNode(node) {
+  return node instanceof MathNode
+}
+
+function $mathConversionFor(element, display) {
+  if (!element.hasAttribute("data-latex")) return null
+
+  return {
+    conversion: (domNode) => ({
+      node: $createMathNode(domNode.getAttribute("data-latex"), display)
+    }),
+    priority: 2
+  }
+}

package/styles/lexxy-mathjax.css

@@ -0,0 +1,111 @@
+/* Equations inside the editor and in rendered content */
+
+.lexxy-math {
+  display: inline-block;
+  padding: 0 0.1em;
+  border-radius: 0.2em;
+  cursor: pointer;
+}
+
+.lexxy-math--display {
+  display: block;
+  text-align: center;
+  margin: 0.5em 0;
+}
+
+lexxy-editor .lexxy-math:hover {
+  background-color: color-mix(in srgb, currentColor 8%, transparent);
+  outline: 1px solid color-mix(in srgb, currentColor 20%, transparent);
+}
+
+lexxy-editor .lexxy-math.selected,
+lexxy-editor [data-lexical-decorator="true"]:focus .lexxy-math {
+  outline: 2px solid var(--lexxy-focus-color, #2563eb);
+}
+
+.lexxy-math--error {
+  color: #b91c1c;
+  font-family: monospace;
+  outline: 1px dashed #b91c1c;
+}
+
+/* Equation editor dialog */
+
+.lexxy-math-editor::backdrop {
+  background: rgba(0, 0, 0, 0.35);
+}
+
+.lexxy-math-editor {
+  min-width: min(28rem, 90vw);
+  border: 1px solid #d4d4d8;
+  border-radius: 0.5rem;
+  padding: 1rem;
+  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.15);
+}
+
+.lexxy-math-editor form {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.lexxy-math-editor__label {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  font-size: 0.85rem;
+  color: #52525b;
+}
+
+.lexxy-math-editor textarea {
+  font-family: ui-monospace, monospace;
+  font-size: 0.95rem;
+  padding: 0.5rem;
+  border: 1px solid #d4d4d8;
+  border-radius: 0.375rem;
+  resize: vertical;
+}
+
+.lexxy-math-editor__preview {
+  min-height: 3rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.5rem;
+  border: 1px dashed #d4d4d8;
+  border-radius: 0.375rem;
+  overflow-x: auto;
+}
+
+.lexxy-math-editor__footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+}
+
+.lexxy-math-editor__display-toggle {
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+  font-size: 0.85rem;
+}
+
+.lexxy-math-editor__actions {
+  display: flex;
+  gap: 0.5rem;
+}
+
+.lexxy-math-editor__actions button {
+  padding: 0.35rem 0.9rem;
+  border-radius: 0.375rem;
+  border: 1px solid #d4d4d8;
+  background: white;
+  cursor: pointer;
+}
+
+.lexxy-math-editor__actions button[data-behavior="confirm"] {
+  background: var(--lexxy-focus-color, #2563eb);
+  border-color: var(--lexxy-focus-color, #2563eb);
+  color: white;
+}