@llui/markdown-editor 0.2.12 → 0.2.14

package/src/index.ts

@@ -0,0 +1,93 @@
+// `@llui/markdown-editor` — WYSIWYG Markdown editor for LLui, built on Lexical.
+
+export {
+  type EditorConfig,
+  type EditorParts,
+  type CollabBinding,
+  type CollabHooks,
+  type CollabFactory,
+  markdownEditor,
+} from './editor.js'
+
+export {
+  type BlockType,
+  type FormatState,
+  type OverlayKind,
+  type CollabStatus,
+  type EditorState,
+  type EditorMsg,
+  type EditorOutMsg,
+  type EditorEffect,
+  type InitOptions,
+  EMPTY_FORMAT,
+  COLLAB_OFF,
+  init,
+  update,
+  countWords,
+} from './state.js'
+
+export {
+  type ItemSurface,
+  type CommandItem,
+  type CommandContext,
+  type MarkdownPlugin,
+} from './plugins/types.js'
+
+export {
+  type PluginUI,
+  type PluginUISpec,
+  type PluginViewArgs,
+  type PluginEffectContext,
+  definePluginUI,
+} from './plugins/ui.js'
+
+export { type CorePluginOptions, corePlugin } from './plugins/core.js'
+export {
+  type InlineFormat,
+  type SingleBlockPluginOptions,
+  singleBlockPlugin,
+} from './plugins/single-block.js'
+export { type LinkPluginOptions, linkPlugin } from './plugins/link.js'
+export {
+  type CalloutKind,
+  type CalloutData,
+  type CalloutPluginOptions,
+  calloutPlugin,
+  $insertCallout,
+} from './plugins/callout.js'
+export { hrPlugin, $insertHorizontalRule } from './plugins/hr.js'
+export { slashPlugin } from './plugins/slash.js'
+export { contextMenuPlugin } from './plugins/context-menu.js'
+export { floatingToolbarPlugin } from './plugins/floating-toolbar.js'
+export { type MathPluginOptions, mathPlugin } from './plugins/math.js'
+export { type MermaidPluginOptions, mermaidPlugin } from './plugins/mermaid.js'
+export { type Mention, type MentionPluginOptions, mentionPlugin } from './plugins/mention.js'
+export { type EmojiPluginOptions, DEFAULT_EMOJI, emojiPlugin } from './plugins/emoji.js'
+export { type ImagePluginOptions, imagePlugin } from './plugins/image.js'
+export { tablePlugin } from './plugins/table.js'
+
+export { $insertMarkdownAtSelection, registerMarkdownPaste } from './paste.js'
+
+export { GFM_NODES, GFM_TRANSFORMERS } from './transformers/gfm.js'
+export { buildTransformers, orderTransformers } from './transformers/registry.js'
+
+export { computeFormatState } from './format.js'
+
+export {
+  STRIKETHROUGH_CLASS,
+  UNDERLINE_CLASS,
+  UNDERLINE_STRIKETHROUGH_CLASS,
+  defaultTheme,
+  mergeTheme,
+} from './theme.js'
+
+export {
+  type ToolbarItemParts,
+  type ToolbarParts,
+  type ToolbarOptions,
+  DEFAULT_GLYPHS,
+  connectToolbar,
+  toolbar,
+} from './surfaces/toolbar.js'
+
+export { type LinkDialogOptions, linkDialog } from './surfaces/link-dialog.js'

package/src/paste.ts

@@ -0,0 +1,96 @@
+// Markdown-on-paste: when the user pastes plain text into the editor, parse it
+// as Markdown and insert the resulting rich nodes at the caret instead of the
+// literal source. Rich pastes (clipboards carrying `text/html`) are left to
+// Lexical's own HTML import so copy-from-the-web keeps its formatting. Disabled
+// per-editor via the `pasteMarkdown: false` config option.
+
+import {
+  $createParagraphNode,
+  $getSelection,
+  $insertNodes,
+  $isRangeSelection,
+  $setSelection,
+  COMMAND_PRIORITY_HIGH,
+  PASTE_COMMAND,
+  isDOMNode,
+  isSelectionCapturedInDecoratorInput,
+  type LexicalEditor,
+} from 'lexical'
+import { $convertFromMarkdownString, type Transformer } from '@lexical/markdown'
+import { $sanitizeLinkNodes } from './security.js'
+
+/**
+ * Parse `markdown` with `transformers` and insert the produced nodes at the
+ * current range selection. The document is parsed into a detached scratch
+ * container (so the live root is never cleared) and the selection captured
+ * before the import — which moves the caret into the scratch node — is restored
+ * before the nodes are spliced in. Returns `true` only when nodes were actually
+ * inserted; `false` (a no-op) when there is no range selection to insert into or
+ * the markdown parsed to nothing — letting the caller fall back to the default
+ * paste behaviour instead of silently swallowing the event.
+ */
+export function $insertMarkdownAtSelection(
+  markdown: string,
+  transformers: Array<Transformer>,
+): boolean {
+  const selection = $getSelection()
+  if (!$isRangeSelection(selection)) return false
+  const saved = selection.clone()
+
+  // Import into a detached element so `$convertFromMarkdownString`'s `root.clear()`
+  // touches the scratch node, not the live document.
+  const scratch = $createParagraphNode()
+  $convertFromMarkdownString(markdown, transformers, scratch)
+  // Untrusted source: neutralize any `javascript:`/`data:` link the markdown
+  // carried BEFORE the nodes are spliced into the live document. (Image src is
+  // enforced in the image transformer; links go through here.)
+  $sanitizeLinkNodes(scratch)
+  const nodes = scratch.getChildren()
+  if (nodes.length === 0) return false
+
+  // The import re-homes the selection to the scratch node's start; restore the
+  // real caret, then splice the parsed nodes in (splitting blocks as needed).
+  $setSelection(saved)
+  $insertNodes(nodes)
+  return true
+}
+
+/**
+ * Register the markdown-on-paste handler on `editor`. Returns a disposer.
+ *
+ * Plain-text pastes are converted as Markdown. Pastes that also carry
+ * `text/html` are ignored so Lexical's richer HTML import handles them.
+ */
+export function registerMarkdownPaste(
+  editor: LexicalEditor,
+  transformers: Array<Transformer>,
+): () => void {
+  return editor.registerCommand(
+    PASTE_COMMAND,
+    (event: ClipboardEvent) => {
+      // Let native inputs inside a DecoratorNode paste themselves (mirrors
+      // Lexical's own rich-text paste guard).
+      if (isDOMNode(event.target) && isSelectionCapturedInDecoratorInput(event.target)) return false
+      const clipboard = event.clipboardData
+      if (!clipboard) return false
+      // Defer to Lexical's HTML import when the source provides rich content.
+      if (clipboard.types.includes('text/html')) return false
+      const text = clipboard.getData('text/plain')
+      if (!text) return false
+
+      // Command listeners run inside a read context, so we can inspect the
+      // selection synchronously. Only claim the event when there is a range
+      // selection to insert into; otherwise fall through to Lexical's default
+      // paste handler (e.g. a selected decorator/NodeSelection) rather than
+      // swallowing the paste.
+      if (!$isRangeSelection($getSelection())) return false
+
+      event.preventDefault()
+      editor.update(() => {
+        $insertMarkdownAtSelection(text, transformers)
+      })
+      return true
+    },
+    COMMAND_PRIORITY_HIGH,
+  )
+}

package/src/plugins/_preview.ts

@@ -0,0 +1,51 @@
+// Shared rendered-preview seam for the math / mermaid decorator plugins.
+//
+// SECURITY: a consumer-supplied `render` turns editor-document content
+// (TeX / mermaid source the user typed) into a preview. To avoid forcing
+// that through an unsanitized HTML sink, `render` may return EITHER:
+//
+//   - a DOM `Node` — mounted directly with no HTML round-trip and NO
+//     sanitization needed (prefer this: hand back the element KaTeX /
+//     mermaid already produced); or
+//   - a `string` — injected as **trusted HTML**. The renderer owns
+//     sanitization in this branch; document content flows into it, so a
+//     vulnerable/misconfigured renderer is an XSS sink. Return sanitized
+//     markup (e.g. via DOMPurify) or prefer the Node form.
+
+import { foreign, type Mountable, type Signal } from '@llui/dom'
+
+/** A preview renderer: source string → safe DOM node, or trusted HTML string. */
+export type PreviewRender = (source: string) => string | Node
+
+interface PreviewInstance {
+  unbind: () => void
+}
+
+/**
+ * Build a reactive `data-part="preview"` region that re-renders whenever
+ * `source` changes. String results are set as trusted HTML; Node results
+ * are mounted directly (no sanitization). See the module header.
+ */
+export function renderedPreview(
+  source: Signal<string>,
+  render: PreviewRender,
+  tag = 'div',
+): Mountable {
+  return foreign<PreviewInstance, { source: Signal<string> }>({
+    tag,
+    state: { source },
+    mount: ({ el, state }) => {
+      el.setAttribute('data-part', 'preview')
+      el.setAttribute('contenteditable', 'false')
+      const apply = (value: string): void => {
+        const out = render(value)
+        if (typeof out === 'string') el.innerHTML = out
+        else el.replaceChildren(out)
+      }
+      // `bind` fires immediately with the current value, then on change.
+      const unbind = state.source.bind(apply)
+      return { unbind }
+    },
+    unmount: (instance) => instance.unbind(),
+  })
+}

package/src/plugins/callout.ts

@@ -0,0 +1,180 @@
+// Callout (admonition) plugin — the custom-rendering showcase. A callout is a
+// block decorator: it stores `{ kind, text }`, renders an LLui sub-view (its own
+// TEA loop) with a clickable kind badge, and round-trips to `:::kind text`
+// markdown via a contributed element transformer.
+
+import { type ElementNode, type LexicalEditor, type LexicalNode } from 'lexical'
+import { $insertNodeToNearestRoot } from '@lexical/utils'
+import type { ElementTransformer } from '@lexical/markdown'
+import {
+  $createLLuiDecoratorNode,
+  $isLLuiDecoratorNode,
+  LLuiDecoratorNode,
+  decoratorBridge,
+} from '@llui/lexical'
+import { button, div, span, text, type Signal } from '@llui/dom'
+import type { MarkdownPlugin } from './types.js'
+
+export type CalloutKind = 'note' | 'tip' | 'warning' | 'danger'
+
+export interface CalloutData {
+  kind: CalloutKind
+  text: string
+}
+
+const KIND_CYCLE: readonly CalloutKind[] = ['note', 'tip', 'warning', 'danger']
+const KIND_LABEL: Readonly<Record<CalloutKind, string>> = {
+  note: 'Note',
+  tip: 'Tip',
+  warning: 'Warning',
+  danger: 'Danger',
+}
+
+const BRIDGE_TYPE = 'callout'
+
+function nextKind(kind: CalloutKind): CalloutKind {
+  const idx = KIND_CYCLE.indexOf(kind)
+  return KIND_CYCLE[(idx + 1) % KIND_CYCLE.length]!
+}
+
+function isCalloutData(value: unknown): value is CalloutData {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as CalloutData).kind === 'string' &&
+    typeof (value as CalloutData).text === 'string'
+  )
+}
+
+// Keep keyboard/input/paste events from bubbling to the outer Lexical editor so
+// the nested editable text island edits natively without Lexical intercepting.
+const stop = (e: Event): void => e.stopPropagation()
+
+/** The LLui sub-view rendered inside a callout DecoratorNode. The badge cycles
+ * the kind; the text is an editable island that persists into the Lexical node
+ * on blur (both round-trip to markdown). `data` is a reactive signal fed by the
+ * bridge, so a data commit updates the view IN PLACE — the editable island keeps
+ * its focus/caret instead of the whole sub-app remounting. */
+const calloutBridge = decoratorBridge<CalloutData>(BRIDGE_TYPE, (data, api) => [
+  div(
+    {
+      'data-scope': 'md-callout',
+      'data-part': 'root',
+      'data-kind': data.at('kind') as Signal<string>,
+      contenteditable: 'false',
+      onKeyDown: stop,
+      onBeforeInput: stop,
+      onPaste: stop,
+    },
+    [
+      button(
+        {
+          type: 'button',
+          'data-part': 'badge',
+          'aria-label': 'Change callout kind',
+          onClick: () => {
+            const cur = data.peek()
+            api.update({ kind: nextKind(cur.kind), text: cur.text })
+          },
+        },
+        [text(data.at('kind').map((k) => KIND_LABEL[k]))],
+      ),
+      span(
+        {
+          'data-part': 'text',
+          contenteditable: 'true',
+          role: 'textbox',
+          'aria-label': 'Callout text',
+          onBlur: (e: FocusEvent) => {
+            const cur = data.peek()
+            const value = (e.target as HTMLElement).textContent ?? ''
+            if (value !== cur.text) api.update({ kind: cur.kind, text: value })
+          },
+        },
+        [text(data.at('text') as Signal<string>)],
+      ),
+    ],
+  ),
+])
+
+/** `:::kind text` element transformer (single-line admonition). */
+const CALLOUT_TRANSFORMER: ElementTransformer = {
+  dependencies: [LLuiDecoratorNode],
+  export: (node: LexicalNode): string | null => {
+    if (!$isLLuiDecoratorNode(node) || node.getBridgeType() !== BRIDGE_TYPE) return null
+    const data = node.getData()
+    if (!isCalloutData(data)) return null
+    return `:::${data.kind} ${data.text}`
+  },
+  regExp: /^:::(note|tip|warning|danger)[ \t]+(.+)$/,
+  replace: (parentNode: ElementNode, _children, match): void => {
+    const kind = match[1] as CalloutKind
+    const callout = $createLLuiDecoratorNode(BRIDGE_TYPE, { kind, text: match[2] ?? '' })
+    parentNode.replace(callout)
+  },
+  type: 'element',
+}
+
+/** Insert a fresh callout at the current selection; returns the created node. */
+export function $insertCallout(
+  kind: CalloutKind = 'note',
+  textValue = 'New callout',
+): LLuiDecoratorNode {
+  return $insertNodeToNearestRoot($createLLuiDecoratorNode(BRIDGE_TYPE, { kind, text: textValue }))
+}
+
+/** Move focus into a callout's editable text island once it has decorated, and
+ * select its placeholder text so the next keystroke replaces it. */
+function focusCalloutText(editor: LexicalEditor, key: string, attempt = 0): void {
+  if (typeof requestAnimationFrame !== 'function') return
+  requestAnimationFrame(() => {
+    const span = editor.getElementByKey(key)?.querySelector('[data-part="text"]')
+    if (span instanceof HTMLElement) {
+      span.focus()
+      try {
+        const range = document.createRange()
+        range.selectNodeContents(span)
+        const sel = window.getSelection()
+        sel?.removeAllRanges()
+        sel?.addRange(range)
+      } catch {
+        /* selection API unavailable */
+      }
+    } else if (attempt < 3) {
+      focusCalloutText(editor, key, attempt + 1)
+    }
+  })
+}
+
+export interface CalloutPluginOptions {
+  /** Default kind for the toolbar/slash insert action. */
+  defaultKind?: CalloutKind
+}
+
+export function calloutPlugin(opts: CalloutPluginOptions = {}): MarkdownPlugin {
+  const defaultKind = opts.defaultKind ?? 'note'
+  return {
+    name: 'callout',
+    nodes: [LLuiDecoratorNode],
+    decorators: [calloutBridge],
+    transformers: [CALLOUT_TRANSFORMER],
+    items: [
+      {
+        id: 'callout',
+        label: 'Callout',
+        icon: 'callout',
+        group: 'insert',
+        keywords: ['note', 'admonition', 'aside', 'tip', 'warning'],
+        run: (editor) => {
+          let key = ''
+          editor.update(() => {
+            key = $insertCallout(defaultKind).getKey()
+          })
+          // Land the caret inside the new callout's text, not after the block.
+          focusCalloutText(editor, key)
+        },
+        surfaces: ['toolbar', 'slash', 'context'],
+      },
+    ],
+  }
+}

package/src/plugins/context-menu.ts

@@ -0,0 +1,118 @@
+// Right-click context menu — a plugin-UI overlay. `register` installs a
+// `contextmenu` listener on the editor root and opens the menu at the pointer;
+// the plugin-UI renders the menu and runs the chosen command.
+
+import { div, each, text, type Signal } from '@llui/dom'
+import { definePluginUI } from './ui.js'
+import { OVERLAY_Z, hideOverlay, overlayRoot } from './overlay.js'
+import type { CommandItem, MarkdownPlugin } from './types.js'
+
+interface MenuItem {
+  id: string
+  label: string
+}
+
+interface ContextState {
+  open: boolean
+  x: number
+  y: number
+  items: MenuItem[]
+}
+
+type ContextMsg =
+  | { type: 'open'; x: number; y: number; items: MenuItem[] }
+  | { type: 'close' }
+  | { type: 'choose'; index: number }
+
+type ContextEffect = { type: 'run'; id: string }
+
+export function contextMenuPlugin(): MarkdownPlugin {
+  let contextItems: CommandItem[] = []
+
+  return {
+    name: 'contextMenu',
+    onItems: (items) => {
+      // Curated: only items that explicitly opt into the context menu (insert
+      // actions, links, history). Inline formatting lives in the floating bar.
+      contextItems = items.filter((i) => i.surfaces?.includes('context') ?? false)
+    },
+    register: (editor, ctx) => {
+      const onContext = (e: Event): void => {
+        const me = e as MouseEvent
+        e.preventDefault()
+        ctx.emit({
+          type: 'plugin',
+          name: 'contextMenu',
+          msg: {
+            type: 'open',
+            x: me.clientX,
+            y: me.clientY,
+            items: contextItems.map((i) => ({ id: i.id, label: i.label })),
+          },
+        })
+      }
+      const root = editor.getRootElement()
+      root?.addEventListener('contextmenu', onContext)
+      return () => {
+        editor.getRootElement()?.removeEventListener('contextmenu', onContext)
+      }
+    },
+    ui: definePluginUI<ContextState, ContextMsg, ContextEffect>({
+      init: () => ({ open: false, x: 0, y: 0, items: [] }),
+      update: (state, msg) => {
+        switch (msg.type) {
+          case 'open':
+            return { open: msg.items.length > 0, x: msg.x, y: msg.y, items: msg.items }
+          case 'close':
+            return hideOverlay(state)
+          case 'choose': {
+            const item = state.items[msg.index]
+            if (!item) return hideOverlay(state)
+            return [{ ...state, open: false }, [{ type: 'run', id: item.id }]]
+          }
+        }
+      },
+      onEffect: (effect, ctx) => {
+        ctx.emit({ type: 'runCommand', id: effect.id })
+      },
+      view: ({ state, send }) =>
+        overlayRoot({
+          open: state.at('open'),
+          x: state.at('x'),
+          y: state.at('y'),
+          zIndex: OVERLAY_Z.contextMenu,
+          attrs: { 'data-scope': 'md-context', 'data-part': 'root' },
+          // Backdrop closes the menu on any outside interaction.
+          before: () => [
+            div({
+              'data-scope': 'md-context',
+              'data-part': 'backdrop',
+              onMouseDown: () => send({ type: 'close' }),
+              onContextMenu: (e: Event) => {
+                e.preventDefault()
+                send({ type: 'close' })
+              },
+            }),
+          ],
+          children: () => [
+            each(state.at('items') as Signal<MenuItem[]>, {
+              key: (it) => it.id,
+              render: (item, index) => [
+                div(
+                  {
+                    'data-scope': 'md-context',
+                    'data-part': 'option',
+                    onMouseDown: (e: MouseEvent) => {
+                      e.preventDefault()
+                      send({ type: 'choose', index: index.peek() })
+                    },
+                  },
+                  [text(item.map((it) => it.label))],
+                ),
+              ],
+            }),
+          ],
+        }),
+    }),
+  }
+}