@llui/markdown-editor 0.2.11 → 0.2.13

package/src/plugins/math.ts

@@ -0,0 +1,116 @@
+// Math plugin — a block math node ($$…$$) rendered via the decorator bridge. The
+// TeX source is editable inline (persists on blur); an optional `render` callback
+// (e.g. KaTeX) turns it into a typeset preview. Round-trips to `$$tex$$`.
+
+import { type ElementNode, type LexicalNode } from 'lexical'
+import { $insertNodeToNearestRoot } from '@lexical/utils'
+import type { ElementTransformer } from '@lexical/markdown'
+import {
+  $createLLuiDecoratorNode,
+  $isLLuiDecoratorNode,
+  LLuiDecoratorNode,
+  decoratorBridge,
+} from '@llui/lexical'
+import { component, div, span, text, type Mountable, type Signal } from '@llui/dom'
+import type { MarkdownPlugin } from './types.js'
+import { renderedPreview, type PreviewRender } from './_preview.js'
+
+const BRIDGE_TYPE = 'math'
+
+interface MathData {
+  tex: string
+}
+
+function isMathData(value: unknown): value is MathData {
+  return typeof value === 'object' && value !== null && typeof (value as MathData).tex === 'string'
+}
+
+type MathMsg = { type: 'commit'; tex: string }
+
+const stop = (e: Event): void => e.stopPropagation()
+
+export interface MathPluginOptions {
+  /** Typeset TeX to an HTML string (e.g. via KaTeX). When omitted, the raw TeX is
+   * shown in a styled box. */
+  /** Render the TeX source to a preview. Return a DOM `Node` (mounted
+   * directly, no sanitization) or a **trusted HTML string** (injected as-is
+   * — sanitize it yourself, e.g. via DOMPurify, since it carries document
+   * content). See `renderedPreview`. */
+  render?: PreviewRender
+}
+
+export function mathPlugin(opts: MathPluginOptions = {}): MarkdownPlugin {
+  const bridge = decoratorBridge<MathData, MathData, MathMsg, never>(BRIDGE_TYPE, (data, api) =>
+    component<MathData, MathMsg, never>({
+      name: 'Math',
+      init: () => ({ tex: data.tex }),
+      update: (state, msg) => {
+        if (msg.type === 'commit') {
+          if (msg.tex === state.tex) return state
+          api.update({ tex: msg.tex })
+          return { tex: msg.tex }
+        }
+        return state
+      },
+      view: ({ state, send }) => {
+        const children: Mountable[] = [
+          span(
+            {
+              'data-part': 'source',
+              contenteditable: 'true',
+              role: 'textbox',
+              'aria-label': 'TeX source',
+              onKeyDown: stop,
+              onBeforeInput: stop,
+              onPaste: stop,
+              onBlur: (e: FocusEvent) =>
+                send({ type: 'commit', tex: (e.target as HTMLElement).textContent ?? '' }),
+            },
+            [text(state.at('tex') as Signal<string>)],
+          ),
+        ]
+        if (opts.render) {
+          children.push(renderedPreview(state.at('tex') as Signal<string>, opts.render, 'span'))
+        }
+        return [
+          div({ 'data-scope': 'md-math', 'data-part': 'root', contenteditable: 'false' }, children),
+        ]
+      },
+    }),
+  )
+
+  const transformer: ElementTransformer = {
+    dependencies: [LLuiDecoratorNode],
+    export: (node: LexicalNode): string | null => {
+      if (!$isLLuiDecoratorNode(node) || node.getBridgeType() !== BRIDGE_TYPE) return null
+      const data = node.getData()
+      return isMathData(data) ? `$$${data.tex}$$` : null
+    },
+    regExp: /^\$\$(.+)\$\$$/,
+    replace: (parentNode: ElementNode, _children, match): void => {
+      parentNode.replace($createLLuiDecoratorNode(BRIDGE_TYPE, { tex: match[1] ?? '' }))
+    },
+    type: 'element',
+  }
+
+  return {
+    name: 'math',
+    nodes: [LLuiDecoratorNode],
+    decorators: [bridge],
+    transformers: [transformer],
+    items: [
+      {
+        id: 'math',
+        label: 'Math block',
+        icon: 'math',
+        group: 'insert',
+        keywords: ['latex', 'tex', 'equation', 'formula'],
+        run: (editor) =>
+          editor.update(() =>
+            $insertNodeToNearestRoot($createLLuiDecoratorNode(BRIDGE_TYPE, { tex: 'e = mc^2' })),
+          ),
+        surfaces: ['slash', 'context'],
+      },
+    ],
+  }
+}

package/src/plugins/mention.ts

@@ -0,0 +1,224 @@
+// Mention plugin — an `@`-triggered typeahead. Same shape as the slash menu, but
+// the candidates come from a configurable `source`, and choosing inserts the
+// mention text (`@label`) rather than running a command. Demonstrates a second
+// typeahead built on the plugin-UI seam with no new machinery.
+
+import {
+  $getSelection,
+  $isRangeSelection,
+  $isTextNode,
+  COMMAND_PRIORITY_HIGH,
+  KEY_ARROW_DOWN_COMMAND,
+  KEY_ARROW_UP_COMMAND,
+  KEY_ENTER_COMMAND,
+  KEY_ESCAPE_COMMAND,
+} from 'lexical'
+import { mergeRegister } from '@lexical/utils'
+import { div, each, text, type Signal } from '@llui/dom'
+import { definePluginUI } from './ui.js'
+import { OVERLAY_Z, hideOverlay, overlayRoot } from './overlay.js'
+import type { MarkdownPlugin } from './types.js'
+
+export interface Mention {
+  id: string
+  label: string
+}
+
+interface Row {
+  id: string
+  label: string
+  active: boolean
+}
+
+interface MentionState {
+  open: boolean
+  query: string
+  items: Row[]
+  index: number
+  x: number
+  y: number
+}
+
+type MentionMsg =
+  | { type: 'show'; query: string; items: Mention[]; x: number; y: number }
+  | { type: 'hide' }
+  | { type: 'move'; delta: number }
+  | { type: 'choose' }
+  | { type: 'click'; index: number }
+
+type MentionEffect = { type: 'insert'; label: string; query: string }
+
+const TRIGGER = /(?:^|\s)@(\w*)$/
+
+const DEFAULT_MENTIONS: readonly Mention[] = [
+  { id: 'franco', label: 'Franco' },
+  { id: 'ada', label: 'Ada' },
+  { id: 'grace', label: 'Grace' },
+  { id: 'linus', label: 'Linus' },
+  { id: 'margaret', label: 'Margaret' },
+]
+
+function withActive(items: readonly Mention[], index: number): Row[] {
+  return items.map((it, i) => ({ id: it.id, label: it.label, active: i === index }))
+}
+
+function $readQuery(): string | null {
+  const selection = $getSelection()
+  if (!$isRangeSelection(selection) || !selection.isCollapsed()) return null
+  const node = selection.anchor.getNode()
+  if (!$isTextNode(node)) return null
+  const before = node.getTextContent().slice(0, selection.anchor.offset)
+  const match = before.match(TRIGGER)
+  return match ? (match[1] ?? '') : null
+}
+
+function caretXY(): { x: number; y: number } {
+  if (typeof window === 'undefined') return { x: 0, y: 0 }
+  const sel = window.getSelection()
+  if (sel && sel.rangeCount > 0) {
+    const rect = sel.getRangeAt(0).getBoundingClientRect()
+    return { x: rect.left, y: rect.bottom + 4 }
+  }
+  return { x: 0, y: 0 }
+}
+
+export interface MentionPluginOptions {
+  /** Resolve candidates for a query (default: a small sample list). */
+  source?: (query: string) => readonly Mention[]
+}
+
+export function mentionPlugin(opts: MentionPluginOptions = {}): MarkdownPlugin {
+  const source =
+    opts.source ??
+    ((query: string) =>
+      DEFAULT_MENTIONS.filter((m) => m.label.toLowerCase().includes(query.toLowerCase())))
+
+  return {
+    name: 'mention',
+    register: (editor, ctx) => {
+      const isActive = (): boolean => editor.getEditorState().read(() => $readQuery() !== null)
+
+      const refresh = (): void => {
+        const query = editor.getEditorState().read(() => $readQuery())
+        if (query === null) {
+          ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'hide' } })
+          return
+        }
+        const items = [...source(query)].slice(0, 8)
+        const { x, y } = caretXY()
+        ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'show', query, items, x, y } })
+      }
+
+      const nav = (delta: number, e: KeyboardEvent | null): boolean => {
+        if (!isActive()) return false
+        e?.preventDefault()
+        ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'move', delta } })
+        return true
+      }
+
+      return mergeRegister(
+        editor.registerUpdateListener(() => refresh()),
+        editor.registerCommand(KEY_ARROW_DOWN_COMMAND, (e) => nav(1, e), COMMAND_PRIORITY_HIGH),
+        editor.registerCommand(KEY_ARROW_UP_COMMAND, (e) => nav(-1, e), COMMAND_PRIORITY_HIGH),
+        editor.registerCommand(
+          KEY_ENTER_COMMAND,
+          (e) => {
+            if (!isActive()) return false
+            e?.preventDefault()
+            ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'choose' } })
+            return true
+          },
+          COMMAND_PRIORITY_HIGH,
+        ),
+        editor.registerCommand(
+          KEY_ESCAPE_COMMAND,
+          () => {
+            if (!isActive()) return false
+            ctx.emit({ type: 'plugin', name: 'mention', msg: { type: 'hide' } })
+            return true
+          },
+          COMMAND_PRIORITY_HIGH,
+        ),
+      )
+    },
+    ui: definePluginUI<MentionState, MentionMsg, MentionEffect>({
+      init: () => ({ open: false, query: '', items: [], index: 0, x: 0, y: 0 }),
+      update: (state, msg) => {
+        switch (msg.type) {
+          case 'show':
+            return {
+              open: msg.items.length > 0,
+              query: msg.query,
+              items: withActive(msg.items, 0),
+              index: 0,
+              x: msg.x,
+              y: msg.y,
+            }
+          case 'hide':
+            return hideOverlay(state)
+          case 'move': {
+            if (!state.open || state.items.length === 0) return state
+            const index = (state.index + msg.delta + state.items.length) % state.items.length
+            return { ...state, index, items: withActive(state.items, index) }
+          }
+          case 'choose': {
+            const item = state.items[state.index]
+            if (!state.open || !item) return hideOverlay(state)
+            return [
+              { ...state, open: false },
+              [{ type: 'insert', label: item.label, query: state.query }],
+            ]
+          }
+          case 'click': {
+            const item = state.items[msg.index]
+            if (!item) return state
+            return [
+              { ...state, open: false },
+              [{ type: 'insert', label: item.label, query: state.query }],
+            ]
+          }
+        }
+      },
+      onEffect: (effect, ctx) => {
+        const editor = ctx.editor()
+        if (!editor) return
+        editor.update(() => {
+          const selection = $getSelection()
+          if (!$isRangeSelection(selection) || !selection.isCollapsed()) return
+          const node = selection.anchor.getNode()
+          if (!$isTextNode(node)) return
+          const offset = selection.anchor.offset
+          const start = offset - effect.query.length - 1
+          if (start >= 0) node.spliceText(start, effect.query.length + 1, `@${effect.label} `, true)
+        })
+      },
+      view: ({ state, send }) =>
+        overlayRoot({
+          open: state.at('open'),
+          x: state.at('x'),
+          y: state.at('y'),
+          zIndex: OVERLAY_Z.typeahead,
+          attrs: { 'data-scope': 'md-slash', 'data-part': 'root' },
+          children: () => [
+            each(state.at('items') as Signal<Row[]>, {
+              key: (it) => it.id,
+              render: (item, index) => [
+                div(
+                  {
+                    'data-scope': 'md-slash',
+                    'data-part': 'option',
+                    'data-active': item.map((it) => (it.active ? '' : undefined)),
+                    onMouseDown: (e: MouseEvent) => {
+                      e.preventDefault()
+                      send({ type: 'click', index: index.peek() })
+                    },
+                  },
+                  [text(item.map((it) => `@${it.label}`))],
+                ),
+              ],
+            }),
+          ],
+        }),
+    }),
+  }
+}

package/src/plugins/mermaid.ts

@@ -0,0 +1,134 @@
+// Mermaid plugin — a fenced ```mermaid block rendered via the decorator bridge.
+// The diagram source is editable (persists on blur); an optional `render` callback
+// (e.g. the mermaid library) produces the diagram. Round-trips to a ```mermaid
+// fence.
+//
+// NOTE: place `mermaidPlugin()` BEFORE `corePlugin()` in the plugins array so its
+// multiline transformer matches ```mermaid before the generic code-block one.
+
+import { type LexicalNode } from 'lexical'
+import { $insertNodeToNearestRoot } from '@lexical/utils'
+import type { MultilineElementTransformer } from '@lexical/markdown'
+import {
+  $createLLuiDecoratorNode,
+  $isLLuiDecoratorNode,
+  LLuiDecoratorNode,
+  decoratorBridge,
+} from '@llui/lexical'
+import { component, div, text, type Mountable, type Signal } from '@llui/dom'
+import type { MarkdownPlugin } from './types.js'
+import { renderedPreview, type PreviewRender } from './_preview.js'
+
+const BRIDGE_TYPE = 'mermaid'
+
+interface MermaidData {
+  code: string
+}
+
+function isMermaidData(value: unknown): value is MermaidData {
+  return (
+    typeof value === 'object' && value !== null && typeof (value as MermaidData).code === 'string'
+  )
+}
+
+type MermaidMsg = { type: 'commit'; code: string }
+
+const stop = (e: Event): void => e.stopPropagation()
+
+export interface MermaidPluginOptions {
+  /** Render the diagram source to an HTML string (e.g. mermaid). When omitted,
+   * the raw source is shown in a styled box. */
+  /** Render the mermaid source to a preview. Return a DOM `Node` (mounted
+   * directly, no sanitization) or a **trusted HTML string** (injected as-is
+   * — sanitize it yourself, e.g. via DOMPurify, since it carries document
+   * content). See `renderedPreview`. */
+  render?: PreviewRender
+}
+
+export function mermaidPlugin(opts: MermaidPluginOptions = {}): MarkdownPlugin {
+  const bridge = decoratorBridge<MermaidData, MermaidData, MermaidMsg, never>(
+    BRIDGE_TYPE,
+    (data, api) =>
+      component<MermaidData, MermaidMsg, never>({
+        name: 'Mermaid',
+        init: () => ({ code: data.code }),
+        update: (state, msg) => {
+          if (msg.type === 'commit') {
+            if (msg.code === state.code) return state
+            api.update({ code: msg.code })
+            return { code: msg.code }
+          }
+          return state
+        },
+        view: ({ state, send }) => {
+          const children: Mountable[] = [
+            div(
+              {
+                'data-part': 'source',
+                contenteditable: 'true',
+                role: 'textbox',
+                'aria-label': 'Mermaid source',
+                onKeyDown: stop,
+                onBeforeInput: stop,
+                onPaste: stop,
+                onBlur: (e: FocusEvent) =>
+                  send({ type: 'commit', code: (e.target as HTMLElement).textContent ?? '' }),
+              },
+              [text(state.at('code') as Signal<string>)],
+            ),
+          ]
+          if (opts.render) {
+            children.push(renderedPreview(state.at('code') as Signal<string>, opts.render))
+          }
+          return [
+            div(
+              { 'data-scope': 'md-mermaid', 'data-part': 'root', contenteditable: 'false' },
+              children,
+            ),
+          ]
+        },
+      }),
+  )
+
+  const transformer: MultilineElementTransformer = {
+    dependencies: [LLuiDecoratorNode],
+    export: (node: LexicalNode): string | null => {
+      if (!$isLLuiDecoratorNode(node) || node.getBridgeType() !== BRIDGE_TYPE) return null
+      const data = node.getData()
+      return isMermaidData(data) ? '```mermaid\n' + data.code + '\n```' : null
+    },
+    regExpStart: /^```mermaid$/,
+    regExpEnd: /^```$/,
+    replace: (rootNode, _children, _startMatch, _endMatch, linesInBetween): boolean => {
+      const lines = [...(linesInBetween ?? [])]
+      while (lines.length > 0 && lines[0] === '') lines.shift()
+      while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+      rootNode.append($createLLuiDecoratorNode(BRIDGE_TYPE, { code: lines.join('\n') }))
+      return true
+    },
+    type: 'multiline-element',
+  }
+
+  return {
+    name: 'mermaid',
+    nodes: [LLuiDecoratorNode],
+    decorators: [bridge],
+    transformers: [transformer],
+    items: [
+      {
+        id: 'mermaid',
+        label: 'Diagram',
+        icon: 'mermaid',
+        group: 'insert',
+        keywords: ['mermaid', 'diagram', 'flowchart', 'graph'],
+        run: (editor) =>
+          editor.update(() =>
+            $insertNodeToNearestRoot(
+              $createLLuiDecoratorNode(BRIDGE_TYPE, { code: 'graph TD\n  A --> B' }),
+            ),
+          ),
+        surfaces: ['slash', 'context'],
+      },
+    ],
+  }
+}

package/src/plugins/overlay.ts

@@ -0,0 +1,138 @@
+// Shared overlay primitive for plugin-UI surfaces (context menu, slash/mention
+// typeaheads, floating toolbar, table tools). Every one of these is a portaled,
+// viewport-positioned panel whose `{ open, x, y }` lives in pure, JSON state and
+// is rendered with `show → portal → fixed-positioned div`. Factoring that single
+// shape here keeps positioning testable (a plain style string, not imperative
+// floating-ui calls) and removes the copy-paste that otherwise accumulates one
+// near-identical state machine per overlay plugin.
+//
+// Anchored positioning via `@llui/components`' `attachFloating` (floating-ui) was
+// considered: it gives flip/shift/auto-update for free but needs a live element
+// ref and async, jsdom-untestable DOM writes — a poor fit for overlays whose
+// position is derived from a transient caret/pointer/element rect each `register`
+// tick. The pure-state idiom below covers scroll/resize via {@link onViewportChange}.
+//
+// ## Stacking order (z-index)
+// A single documented scale so overlays never tie and obscure each other:
+//   60 — typeaheads (slash, mention)        — caret-anchored, lowest
+//   61 — context menu                        — pointer-anchored
+//   62 — floating selection toolbar          — selection-anchored bubble
+//   63 — table tools                         — element-anchored, sits over a table
+// The values live with each plugin's view; this comment is the source of truth.
+
+import {
+  div,
+  derived,
+  onMount,
+  portal,
+  show,
+  type Mountable,
+  type Renderable,
+  type Signal,
+} from '@llui/dom'
+import { registerNestedLayer } from '@llui/components/utils'
+
+export const OVERLAY_Z = {
+  typeahead: 60,
+  contextMenu: 61,
+  floatingToolbar: 62,
+  tableTools: 63,
+} as const
+
+const toMountables = (r: Renderable): Mountable[] => [...r]
+
+// Unique marker per overlay instance so its portal root can be located while
+// open. Every overlayRoot is a body-level sibling portal; without declaring it
+// as a nested layer, a host `dialog.overlay()` mis-reads an interaction inside
+// it as "outside" and dismisses (see @llui/components registerNestedLayer).
+let layerSeq = 0
+const NESTED_LAYER_ATTR = 'data-llui-nested-layer'
+
+export interface OverlayRootConfig {
+  /** Whether the overlay is shown. */
+  open: Signal<boolean>
+  /** Viewport x of the anchor point (px). */
+  x: Signal<number>
+  /** Viewport y of the anchor point (px). */
+  y: Signal<number>
+  /** Stacking level — use {@link OVERLAY_Z}. */
+  zIndex: number
+  /** Extra CSS appended after positioning (e.g. a centering/lift transform). */
+  transform?: string
+  /** Attributes for the positioned element (`data-scope`/`data-part`, handlers). */
+  attrs: Record<string, unknown>
+  /** Optional siblings rendered inside the portal before the root (e.g. a backdrop). */
+  before?: () => Renderable
+  /** The positioned element's children. */
+  children: () => Renderable
+}
+
+/**
+ * A portaled, `position:fixed` overlay placed at `(x, y)` and shown while `open`.
+ * Returns the `Renderable` a plugin's `view` yields directly. The emitted style is
+ * a deterministic string — `position:fixed;left:${x}px;top:${y}px;z-index:${z}` plus
+ * an optional `transform` — so positioning is unit-testable.
+ */
+export function overlayRoot(cfg: OverlayRootConfig): Renderable {
+  const style = derived(
+    cfg.x,
+    cfg.y,
+    (x, y) =>
+      `position:fixed;left:${x}px;top:${y}px;z-index:${cfg.zIndex}` +
+      (cfg.transform ? `;${cfg.transform}` : ''),
+  ) as Signal<string>
+  const layerId = `mdo-${++layerSeq}`
+  return [
+    // Register once for the overlay's lifetime; the resolver returns the live
+    // portal root only while open (and nothing when closed/unmounted), so the
+    // single registration tracks open/closed without per-toggle churn.
+    onMount(() =>
+      registerNestedLayer(() => {
+        if (typeof document === 'undefined') return []
+        const el = document.querySelector(`[${NESTED_LAYER_ATTR}="${layerId}"]`)
+        return el ? [el] : []
+      }),
+    ),
+    show(cfg.open, () => [
+      portal(() => [
+        ...(cfg.before ? toMountables(cfg.before()) : []),
+        div({ ...cfg.attrs, [NESTED_LAYER_ATTR]: layerId, style }, toMountables(cfg.children())),
+      ]),
+    ]),
+  ]
+}
+
+/** Guarded close: collapse `open` to false, preserving the reference when already
+ * closed so the host doesn't reconcile a no-op. */
+export function hideOverlay<S extends { open: boolean }>(state: S): S {
+  return state.open ? { ...state, open: false } : state
+}
+
+/**
+ * Run `run` (debounced to one call per animation frame) whenever the viewport
+ * changes — any ancestor scroll or a window resize. Overlays anchored to a
+ * persistent element (a table) or a live selection must reposition on scroll;
+ * editor update listeners alone never fire for a plain scroll. Returns a cleanup
+ * that removes the listeners. No-op (and cleanup is a no-op) outside the browser.
+ */
+export function onViewportChange(run: () => void): () => void {
+  if (typeof window === 'undefined' || typeof requestAnimationFrame !== 'function') {
+    return () => {}
+  }
+  let pending = 0
+  const handler = (): void => {
+    if (pending) return
+    pending = requestAnimationFrame(() => {
+      pending = 0
+      run()
+    })
+  }
+  // Capture phase so scrolls in any nested scroll container are caught.
+  window.addEventListener('scroll', handler, true)
+  window.addEventListener('resize', handler)
+  return () => {
+    window.removeEventListener('scroll', handler, true)
+    window.removeEventListener('resize', handler)
+    if (pending) cancelAnimationFrame(pending)
+  }
+}