@llui/markdown-editor 0.2.12 → 0.2.14

package/src/plugins/slash.ts

@@ -0,0 +1,224 @@
+// Slash command menu — a `/` command palette built as a plugin. It uses both the
+// engine `register` hook (to detect the `/query` trigger and drive keyboard nav
+// from editor events) and the plugin-UI extension (state + the floating menu
+// view + command execution). The flagship demonstration that the plugin-UI seam
+// handles complex, stateful overlays.
+
+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 { CommandItem, MarkdownPlugin } from './types.js'
+
+interface MenuItem {
+  id: string
+  label: string
+}
+
+/** A rendered row — the `active` flag is row-local so `each` highlights reliably. */
+interface MenuRow {
+  id: string
+  label: string
+  active: boolean
+}
+
+interface SlashState {
+  open: boolean
+  query: string
+  items: MenuRow[]
+  index: number
+  x: number
+  y: number
+}
+
+function withActive(items: readonly MenuItem[], index: number): MenuRow[] {
+  return items.map((it, i) => ({ id: it.id, label: it.label, active: i === index }))
+}
+
+type SlashMsg =
+  | { type: 'show'; query: string; items: MenuItem[]; x: number; y: number }
+  | { type: 'hide' }
+  | { type: 'move'; delta: number }
+  | { type: 'choose' }
+  | { type: 'click'; index: number }
+
+type SlashEffect = { type: 'run'; id: string; query: string }
+
+const TRIGGER = /(?:^|\s)\/([\w-]*)$/
+
+/** Read the active slash query before the collapsed caret, or null. */
+function $readSlashQuery(): 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 }
+}
+
+function matches(item: CommandItem, query: string): boolean {
+  if (query === '') return true
+  const q = query.toLowerCase()
+  if (item.label.toLowerCase().includes(q) || item.id.toLowerCase().includes(q)) return true
+  return (item.keywords ?? []).some((k) => k.toLowerCase().includes(q))
+}
+
+export function slashPlugin(): MarkdownPlugin {
+  let slashItems: CommandItem[] = []
+
+  const filtered = (query: string): MenuItem[] =>
+    slashItems.filter((i) => matches(i, query)).map((i) => ({ id: i.id, label: i.label }))
+
+  return {
+    name: 'slash',
+    onItems: (items) => {
+      slashItems = items.filter((i) =>
+        i.surfaces
+          ? i.surfaces.includes('slash')
+          : ['block', 'list', 'insert'].includes(i.group ?? ''),
+      )
+    },
+    register: (editor, ctx) => {
+      const isActive = (): boolean => editor.getEditorState().read(() => $readSlashQuery() !== null)
+
+      const refresh = (): void => {
+        const query = editor.getEditorState().read(() => $readSlashQuery())
+        if (query === null) {
+          ctx.emit({ type: 'plugin', name: 'slash', msg: { type: 'hide' } })
+          return
+        }
+        const items = filtered(query)
+        const { x, y } = caretXY()
+        ctx.emit({ type: 'plugin', name: 'slash', 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: 'slash', 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: 'slash', msg: { type: 'choose' } })
+            return true
+          },
+          COMMAND_PRIORITY_HIGH,
+        ),
+        editor.registerCommand(
+          KEY_ESCAPE_COMMAND,
+          () => {
+            if (!isActive()) return false
+            ctx.emit({ type: 'plugin', name: 'slash', msg: { type: 'hide' } })
+            return true
+          },
+          COMMAND_PRIORITY_HIGH,
+        ),
+      )
+    },
+    ui: definePluginUI<SlashState, SlashMsg, SlashEffect>({
+      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: 'run', id: item.id, query: state.query }]]
+          }
+          case 'click': {
+            const item = state.items[msg.index]
+            if (!item) return state
+            return [{ ...state, open: false }, [{ type: 'run', id: item.id, query: state.query }]]
+          }
+        }
+      },
+      onEffect: (effect, ctx) => {
+        const editor = ctx.editor()
+        if (!editor) return
+        // Remove the typed "/query" before running the command.
+        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, '', true)
+        })
+        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.typeahead,
+          attrs: { 'data-scope': 'md-slash', 'data-part': 'root' },
+          children: () => [
+            each(state.at('items') as Signal<MenuRow[]>, {
+              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/table.ts

@@ -0,0 +1,284 @@
+// Table plugin — GFM tables backed by @lexical/table nodes, with a hand-written
+// multiline transformer that imports `| a | b |` syntax to a TableNode and
+// exports it back. Cells are ordinary editable paragraphs.
+//
+// Place `tablePlugin()` before `corePlugin()` so its multiline transformer is
+// tried ahead of the generic code-block one.
+
+import {
+  $createParagraphNode,
+  $createTextNode,
+  $getSelection,
+  $isRangeSelection,
+  type LexicalNode,
+} from 'lexical'
+import { $insertNodeToNearestRoot, mergeRegister } from '@lexical/utils'
+import {
+  $createTableCellNode,
+  $createTableNode,
+  $createTableRowNode,
+  $deleteTableColumnAtSelection,
+  $deleteTableRowAtSelection,
+  $getTableCellNodeFromLexicalNode,
+  $getTableNodeFromLexicalNodeOrThrow,
+  $insertTableColumnAtSelection,
+  $insertTableRowAtSelection,
+  $isTableNode,
+  $isTableSelection,
+  TableCellHeaderStates,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+} from '@lexical/table'
+import type { MultilineElementTransformer } from '@lexical/markdown'
+import { button, text } from '@llui/dom'
+import { definePluginUI } from './ui.js'
+import { OVERLAY_Z, hideOverlay, onViewportChange, overlayRoot } from './overlay.js'
+import type { MarkdownPlugin } from './types.js'
+
+interface TableToolsState {
+  open: boolean
+  x: number
+  y: number
+}
+
+type TableToolsMsg =
+  | { type: 'show'; x: number; y: number }
+  | { type: 'hide' }
+  | { type: 'op'; id: string }
+type TableToolsEffect = { type: 'run'; id: string }
+
+const TABLE_TOOLS: ReadonlyArray<{ id: string; label: string; title: string }> = [
+  { id: 'rowAbove', label: '↑＋', title: 'Insert row above' },
+  { id: 'rowBelow', label: '↓＋', title: 'Insert row below' },
+  { id: 'colLeft', label: '←＋', title: 'Insert column left' },
+  { id: 'colRight', label: '→＋', title: 'Insert column right' },
+  { id: 'delRow', label: '✕R', title: 'Delete row' },
+  { id: 'delCol', label: '✕C', title: 'Delete column' },
+  { id: 'delTable', label: '🗑', title: 'Delete table' },
+]
+
+/** Run a table editing operation against the current cell selection. */
+function $runTableOp(id: string): void {
+  switch (id) {
+    case 'rowAbove':
+      $insertTableRowAtSelection(false)
+      return
+    case 'rowBelow':
+      $insertTableRowAtSelection(true)
+      return
+    case 'colLeft':
+      $insertTableColumnAtSelection(false)
+      return
+    case 'colRight':
+      $insertTableColumnAtSelection(true)
+      return
+    case 'delRow':
+      $deleteTableRowAtSelection()
+      return
+    case 'delCol':
+      $deleteTableColumnAtSelection()
+      return
+    case 'delTable': {
+      const selection = $getSelection()
+      // A focused cell is a RangeSelection; a multi-cell drag is a TableSelection.
+      // Both carry an anchor pointing into a cell — accept either.
+      if (!$isRangeSelection(selection) && !$isTableSelection(selection)) return
+      const cell = $getTableCellNodeFromLexicalNode(selection.anchor.getNode())
+      if (cell) $getTableNodeFromLexicalNodeOrThrow(cell).remove()
+      return
+    }
+  }
+}
+
+function splitRow(line: string): string[] {
+  // Strip the OUTER table pipes (always unescaped delimiters), then split on
+  // unescaped `|` only — an escaped `\|` is literal cell content and must NOT
+  // split the cell (export writes `\|` for a pipe in a cell; see TABLE_TRANSFORMER
+  // export). Finally unescape `\|` → `|` so the round-trip is lossless.
+  const inner = line
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/(?<!\\)\|$/, '')
+  return inner.split(/(?<!\\)\|/).map((c) => c.trim().replace(/\\\|/g, '|'))
+}
+
+function isSeparator(line: string | undefined): boolean {
+  return !!line && /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/.test(line) && line.includes('-')
+}
+
+function isRow(line: string | undefined): boolean {
+  return !!line && /^\s*\|.*\|\s*$/.test(line.trim())
+}
+
+function makeCell(textValue: string, header: boolean): TableCellNode {
+  const cell = $createTableCellNode(
+    header ? TableCellHeaderStates.COLUMN : TableCellHeaderStates.NO_STATUS,
+  )
+  cell.append($createParagraphNode().append($createTextNode(textValue)))
+  return cell
+}
+
+function buildTable(header: string[], body: string[][]): TableNode {
+  const table = $createTableNode()
+  const headerRow = $createTableRowNode()
+  for (const h of header) headerRow.append(makeCell(h, true))
+  table.append(headerRow)
+  for (const row of body) {
+    const tr = $createTableRowNode()
+    for (let i = 0; i < header.length; i++) tr.append(makeCell(row[i] ?? '', false))
+    table.append(tr)
+  }
+  return table
+}
+
+const TABLE_TRANSFORMER: MultilineElementTransformer = {
+  dependencies: [TableNode, TableRowNode, TableCellNode],
+  export: (node: LexicalNode): string | null => {
+    if (!$isTableNode(node)) return null
+    const rows = node.getChildren() as TableRowNode[]
+    if (rows.length === 0) return null
+    const lines: string[] = []
+    rows.forEach((row, ri) => {
+      const cells = row.getChildren() as TableCellNode[]
+      const texts = cells.map((c) => c.getTextContent().replace(/\|/g, '\\|').replace(/\n/g, ' '))
+      lines.push('| ' + texts.join(' | ') + ' |')
+      if (ri === 0) lines.push('| ' + texts.map(() => '---').join(' | ') + ' |')
+    })
+    return lines.join('\n')
+  },
+  regExpStart: /^\s*\|(.+)\|\s*$/,
+  handleImportAfterStartMatch: ({ lines, rootNode, startLineIndex }) => {
+    if (!isSeparator(lines[startLineIndex + 1])) return null // header must be followed by a separator
+    let end = startLineIndex + 2
+    const body: string[][] = []
+    while (end < lines.length && isRow(lines[end]) && !isSeparator(lines[end])) {
+      body.push(splitRow(lines[end]!))
+      end++
+    }
+    rootNode.append(buildTable(splitRow(lines[startLineIndex]!), body))
+    return [true, end - 1]
+  },
+  // Import is handled manually above; a multiline transformer still needs replace.
+  replace: () => false,
+  type: 'multiline-element',
+}
+
+export function tablePlugin(): MarkdownPlugin {
+  return {
+    name: 'table',
+    nodes: [TableNode, TableRowNode, TableCellNode],
+    transformers: [TABLE_TRANSFORMER],
+    // A contextual toolbar appears above the table whenever the selection is in a
+    // cell. It tracks the table's viewport rect, so it repositions on scroll/resize
+    // (not just on editor updates) and only re-emits when the rect actually moves.
+    register: (editor, ctx) => {
+      let lastKey: string | null = null
+      let lastX = NaN
+      let lastY = NaN
+      const refresh = (): void => {
+        const tableKey = editor.getEditorState().read(() => {
+          const selection = $getSelection()
+          // RangeSelection = caret in a cell; TableSelection = multi-cell drag.
+          if (!$isRangeSelection(selection) && !$isTableSelection(selection)) return null
+          const cell = $getTableCellNodeFromLexicalNode(selection.anchor.getNode())
+          return cell ? $getTableNodeFromLexicalNodeOrThrow(cell).getKey() : null
+        })
+        const el = tableKey ? editor.getElementByKey(tableKey) : null
+        if (!el) {
+          if (lastKey !== null) {
+            lastKey = null
+            lastX = NaN
+            lastY = NaN
+            ctx.emit({ type: 'plugin', name: 'table', msg: { type: 'hide' } })
+          }
+          return
+        }
+        const rect = el.getBoundingClientRect()
+        // Typing inside a cell never moves the table's top-left; skip the redundant
+        // emit so the overlay isn't reconciled on every keystroke.
+        if (tableKey === lastKey && rect.left === lastX && rect.top === lastY) return
+        lastKey = tableKey
+        lastX = rect.left
+        lastY = rect.top
+        ctx.emit({
+          type: 'plugin',
+          name: 'table',
+          msg: { type: 'show', x: rect.left, y: rect.top },
+        })
+      }
+      return mergeRegister(
+        editor.registerUpdateListener(() => refresh()),
+        onViewportChange(refresh),
+      )
+    },
+    ui: definePluginUI<TableToolsState, TableToolsMsg, TableToolsEffect>({
+      init: () => ({ open: false, x: 0, y: 0 }),
+      update: (state, msg) => {
+        switch (msg.type) {
+          case 'show':
+            return state.open && state.x === msg.x && state.y === msg.y
+              ? state
+              : { open: true, x: msg.x, y: msg.y }
+          case 'hide':
+            return hideOverlay(state)
+          case 'op':
+            return [state, [{ type: 'run', id: msg.id }]]
+        }
+      },
+      onEffect: (effect, ctx) => {
+        const editor = ctx.editor()
+        if (editor) editor.update(() => $runTableOp(effect.id))
+      },
+      view: ({ state, send }) =>
+        overlayRoot({
+          open: state.at('open'),
+          x: state.at('x'),
+          y: state.at('y'),
+          zIndex: OVERLAY_Z.tableTools,
+          // Lift the bar above the table's top edge.
+          transform: 'transform:translateY(-118%)',
+          attrs: { 'data-scope': 'md-table-tools', 'data-part': 'bar' },
+          children: () =>
+            TABLE_TOOLS.map((tool) =>
+              button(
+                {
+                  type: 'button',
+                  'data-scope': 'md-table-tools',
+                  'data-part': 'tool',
+                  title: tool.title,
+                  'aria-label': tool.title,
+                  onMouseDown: (e: MouseEvent) => {
+                    e.preventDefault()
+                    send({ type: 'op', id: tool.id })
+                  },
+                },
+                [text(tool.label)],
+              ),
+            ),
+        }),
+    }),
+    items: [
+      {
+        id: 'table',
+        label: 'Table',
+        icon: 'table',
+        group: 'insert',
+        keywords: ['grid', 'rows', 'columns'],
+        run: (editor) =>
+          editor.update(() =>
+            $insertNodeToNearestRoot(
+              buildTable(
+                ['Column 1', 'Column 2'],
+                [
+                  ['', ''],
+                  ['', ''],
+                ],
+              ),
+            ),
+          ),
+        surfaces: ['toolbar', 'slash', 'context'],
+      },
+    ],
+  }
+}

package/src/plugins/types.ts

@@ -0,0 +1,50 @@
+// The markdown plugin contract: extends the engine-level LexicalPlugin with
+// markdown transformers and UI command items (toolbar / slash / context).
+
+import type { LexicalEditor } from 'lexical'
+import type { Transformer } from '@lexical/markdown'
+import type { LexicalPlugin } from '@llui/lexical'
+import type { EditorMsg, EditorOutMsg, FormatState } from '../state.js'
+import type { PluginUI } from './ui.js'
+
+/** Which surfaces a command item appears in (default: all). */
+export type ItemSurface = 'toolbar' | 'floating' | 'slash' | 'context'
+
+/** Handed to a command item's `run` so it can talk back to the host (e.g. open
+ * the link dialog) instead of only mutating the editor. */
+export interface CommandContext {
+  send: (msg: EditorMsg) => void
+}
+
+/** A user-invokable editor command surfaced to the chrome. Its reactive
+ * active/disabled state is read from {@link FormatState}; `run` mutates the
+ * live editor. */
+export interface CommandItem {
+  /** Stable id (also the `runCommand` payload). */
+  id: string
+  label: string
+  /** Optional icon hint (class / svg id); rendering is the consumer's CSS. */
+  icon?: string
+  /** Grouping key for menu sectioning. */
+  group?: string
+  /** Keyword aliases for slash/command-palette filtering. */
+  keywords?: readonly string[]
+  isActive?: (format: FormatState) => boolean
+  isDisabled?: (format: FormatState) => boolean
+  run: (editor: LexicalEditor, ctx: CommandContext) => void
+  surfaces?: readonly ItemSurface[]
+}
+
+/** A markdown editor plugin: engine wiring + transformers + UI items + an
+ * optional stateful UI extension (its own state slice, reducer, view, effects). */
+export interface MarkdownPlugin extends LexicalPlugin<EditorOutMsg> {
+  /** Markdown ↔ node transformers contributed to the registry. */
+  transformers?: readonly Transformer[]
+  /** Command items surfaced to the toolbar / slash / context menus. */
+  items?: readonly CommandItem[]
+  /** A stateful UI extension keyed by this plugin's `name` (see {@link definePluginUI}). */
+  ui?: PluginUI
+  /** Receive the merged command items from all plugins (e.g. a slash menu lists
+   * every plugin's items). Called once at editor construction. */
+  onItems?: (items: readonly CommandItem[]) => void
+}

package/src/plugins/ui.ts

@@ -0,0 +1,79 @@
+// Plugin UI/state extensions — the seam that makes stateful, UI-bearing features
+// (link editor, slash menu, @mentions, …) into plugins instead of core built-ins.
+//
+// A plugin may contribute a small TEA module: a namespaced state slice (stored
+// under `state.plugins[name]`), a reducer, a view (overlays/panels rendered by
+// the host), and effects (handled with live-editor access). Types are erased at
+// the registry boundary via {@link definePluginUI}, which keeps each plugin's
+// `State`/`Msg`/`Effect` fully typed at the definition site.
+
+import type { LexicalEditor } from 'lexical'
+import type { Renderable, Signal } from '@llui/dom'
+
+/** Context for a plugin's `onEffect` — reach the live editor and dispatch back. */
+export interface PluginEffectContext<M> {
+  /** The live Lexical editor (null before mount). */
+  editor: () => LexicalEditor | null
+  /** Dispatch a message back into this plugin. */
+  send: (msg: M) => void
+  /** Dispatch a host editor message (e.g. `{type:'runCommand', id}`). */
+  emit: (msg: unknown) => void
+}
+
+/** Args for a plugin's `view` — its reactive state slice + a scoped dispatcher. */
+export interface PluginViewArgs<S, M> {
+  state: Signal<S>
+  send: (msg: M) => void
+  editor: () => LexicalEditor | null
+}
+
+/** A typed plugin UI module (authored via {@link definePluginUI}). */
+export interface PluginUISpec<S, M, E = never> {
+  /** Initial slice state (JSON-serializable). */
+  init: () => S
+  /** Pure reducer over the slice; may return effects. */
+  update?: (state: S, msg: M) => S | [S, E[]]
+  /** View contribution (overlays/panels), rendered by the host. */
+  view?: (args: PluginViewArgs<S, M>) => Renderable
+  /** Effect handler with live-editor access + host dispatch. */
+  onEffect?: (effect: E, ctx: PluginEffectContext<M>) => void
+}
+
+/** The host message type a plugin effect may emit (the editor's full Msg). */
+export type HostEmit = (msg: unknown) => void
+
+/** The type-erased form stored on a plugin and consumed by the host. */
+export interface PluginUI {
+  init: () => unknown
+  update?: (state: unknown, msg: unknown) => unknown | [unknown, unknown[]]
+  view?: (args: PluginViewArgs<unknown, unknown>) => Renderable
+  onEffect?: (effect: unknown, ctx: PluginEffectContext<unknown>) => void
+}
+
+/**
+ * Author a plugin UI module with full `State`/`Msg`/`Effect` types, erased for
+ * storage. The casts are confined to this boundary (the host only knows
+ * `unknown`), exactly like the decorator bridge.
+ */
+export function definePluginUI<S, M, E = never>(spec: PluginUISpec<S, M, E>): PluginUI {
+  return {
+    init: spec.init,
+    update: spec.update ? (state, msg) => spec.update!(state as S, msg as M) : undefined,
+    view: spec.view
+      ? (args) =>
+          spec.view!({
+            state: args.state as Signal<S>,
+            send: args.send as (msg: M) => void,
+            editor: args.editor,
+          })
+      : undefined,
+    onEffect: spec.onEffect
+      ? (effect, ctx) =>
+          spec.onEffect!(effect as E, {
+            editor: ctx.editor,
+            send: ctx.send as (msg: M) => void,
+            emit: ctx.emit,
+          })
+      : undefined,
+  }
+}