@llui/markdown-editor 0.2.14 → 0.4.0

package/src/plugins/frontmatter.ts

@@ -0,0 +1,324 @@
+// YAML frontmatter plugin — the leading `---` … `---` metadata block.
+//
+// ## Why the block is an OPAQUE STRING, not parsed YAML
+//
+// Deliberate choice, and the requirement that drove it is round-trip fidelity:
+// what the author wrote must come back out byte-for-byte. Two options exist —
+// parse YAML properly, or don't parse it at all — and only the second is
+// achievable here:
+//
+//   - Parsing correctly means a real YAML 1.2 implementation (anchors, aliases,
+//     tags, flow/block collections, the five scalar styles, folded/literal block
+//     scalars with their indentation-indicator and chomping rules). Nothing
+//     smaller is *correct*, and a correct parser is not enough by itself: a
+//     round-trip also needs a comment- and style-preserving EMITTER, because
+//     `parse` → `stringify` normalizes quoting, key order, indentation and drops
+//     comments outright. That is a large dependency (this package deliberately
+//     dropped Prism from `@lexical/code` for exactly this reason — see
+//     `code-language.ts`) to buy a feature the editor does not need: it never
+//     interprets frontmatter, it only has to preserve it.
+//
+//   - The naive middle ground — split each line on the first `:` into a
+//     `Record<string, string>` — is what the reference implementation this was
+//     modelled on does, and it is strictly WORSE than not parsing. Nested maps,
+//     sequences, block scalars, quoted values containing `:`, comments and blank
+//     lines are all silently flattened or destroyed. A lossy parse presented as
+//     structured data is a data-loss bug wearing a feature's clothes.
+//
+// So the block is stored verbatim as a single `source` string and re-emitted
+// between two fences. Consumers that *want* structure own that choice: hand
+// `$getFrontmatter()` to whatever YAML library they already ship, or supply
+// `render` to draw a preview. The editor stays honest about not understanding it.
+//
+// The one unavoidable deviation from byte-for-byte: `$convertFromMarkdownString`
+// runs `normalizeMarkdown`, which `trimEnd()`s every line BEFORE any transformer
+// is consulted, so trailing whitespace inside the block is lost. That happens
+// upstream of every transformer and cannot be intercepted from one. YAML treats
+// trailing spaces as insignificant, so nothing meaningful changes. Likewise a
+// body that is empty or only blank lines normalizes to the canonical `---\n---`.
+//
+// ## The `---` collision with `hrPlugin`
+//
+// `hrPlugin`'s ELEMENT transformer matches `/^(---|\*\*\*|___)\s*$/`, so before
+// this plugin existed a leading frontmatter block parsed as a horizontal rule
+// followed by loose prose. Telling consumers to drop `hrPlugin` is not a fix:
+// `---` is legitimately both things, and which one it is depends on POSITION and
+// CLOSURE, not on which plugin is loaded.
+//
+// The resolution is structural, not ordering-based. `@lexical/markdown`'s
+// importer tries EVERY multiline-element transformer on a line before ANY
+// element transformer (`$importMultiline` runs first in `$importMarkdownNodes`;
+// export mirrors it with `[...multilineElement, ...element]`). This is therefore
+// a `multiline-element` transformer, which means it is consulted ahead of the
+// `hr` element transformer no matter where the two plugins sit in the array —
+// plugin ORDER cannot change the outcome, and neither can loading or omitting
+// `hrPlugin`.
+//
+// Claiming the line is then narrowed by `handleImportAfterStartMatch`, which
+// returns `null` — "not mine, try the next transformer" — unless BOTH hold:
+//
+//   1. the fence is on line 0 (frontmatter is only frontmatter at the very top
+//      of the document), and
+//   2. a closing `---` line exists somewhere below it.
+//
+// Declining falls through to `hrPlugin` (when loaded), so a `---` that is
+// genuinely a thematic break — mid-document, or an unclosed one on line 1 —
+// still becomes an `<hr>`. `replace` returns `false` so that TYPING `---` in the
+// editor is likewise left to the hr shortcut; frontmatter is only ever created
+// by importing markdown or by calling `$setFrontmatter`.
+//
+// The block closes at the FIRST subsequent line that is exactly `---`, which is
+// the rule Jekyll / gray-matter / Hugo apply. A `---` *inside* a value (e.g.
+// `title: a --- b`) is not a whole line and is preserved untouched.
+
+import { $getRoot, type LexicalEditor, type LexicalNode } from 'lexical'
+import type { MultilineElementTransformer } from '@lexical/markdown'
+import {
+  $createLLuiDecoratorNode,
+  $isLLuiDecoratorNode,
+  LLuiDecoratorNode,
+  decoratorBridge,
+} from '@llui/lexical'
+import { div, textarea, type Mountable, type Signal } from '@llui/dom'
+import type { MarkdownPlugin } from './types.js'
+import { renderedPreview, type PreviewRender } from './_preview.js'
+
+/** The decorator bridge id for the frontmatter block. */
+export const FRONTMATTER_BRIDGE_TYPE = 'frontmatter'
+
+/** The frontmatter node's payload: the block body, verbatim, with no fences. */
+export interface FrontmatterData {
+  /** The raw text between the opening and closing `---`. Never interpreted. */
+  source: string
+}
+
+function isFrontmatterData(value: unknown): value is FrontmatterData {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as FrontmatterData).source === 'string'
+  )
+}
+
+/** A line consisting solely of `---` (trailing tabs/spaces tolerated — they are
+ * not content, and `normalizeMarkdown` has usually already trimmed them). */
+const FENCE = /^---[ \t]*$/
+
+/** Render the fences back around an opaque body. An empty (or blank-only) body
+ * collapses to the canonical two-line form so the result stays idempotent. */
+export function serializeFrontmatter(source: string): string {
+  return source === '' ? '---\n---' : `---\n${source}\n---`
+}
+
+/**
+ * The index of the closing fence, or `-1` when `lines` does not open a
+ * frontmatter block (no fence on line 0) or never closes one.
+ *
+ * The single definition of "is this frontmatter?", shared by the importer and
+ * {@link splitFrontmatter} so the two can never disagree. A returned index is
+ * always `>= 1`, which is the property the importer's anti-rewind invariant
+ * rests on (see `handleImportAfterStartMatch`).
+ */
+function closingFenceIndex(lines: readonly string[]): number {
+  const first = lines[0]
+  if (first === undefined || !FENCE.test(first)) return -1
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i]
+    if (line !== undefined && FENCE.test(line)) return i
+  }
+  return -1
+}
+
+/**
+ * Split a leading frontmatter block off a markdown string: `[body, rest]`, or
+ * `null` when the document has none (no line-0 fence, or no closing fence).
+ * Exported because a consumer often needs the metadata BEFORE building an
+ * editor — the same predicate the importer uses, so the two never disagree.
+ */
+export function splitFrontmatter(markdown: string): [source: string, rest: string] | null {
+  const lines = markdown.split('\n')
+  const end = closingFenceIndex(lines)
+  if (end === -1) return null
+  return [lines.slice(1, end).join('\n'), lines.slice(end + 1).join('\n')]
+}
+
+// ── Document accessors (run inside `editor.read` / `editor.update`) ──────────
+
+/** The frontmatter node, if the document starts with one. */
+function $frontmatterNode(): LexicalNode | null {
+  const first = $getRoot().getFirstChild()
+  return $isLLuiDecoratorNode(first) && first.getBridgeType() === FRONTMATTER_BRIDGE_TYPE
+    ? first
+    : null
+}
+
+/** The document's frontmatter body, or `null` when it has none. */
+export function $getFrontmatter(): string | null {
+  const node = $frontmatterNode()
+  if (!node || !$isLLuiDecoratorNode(node)) return null
+  const data = node.getData()
+  return isFrontmatterData(data) ? data.source : null
+}
+
+/**
+ * Set (or, with `null`, remove) the document's frontmatter. The block is always
+ * kept as the FIRST child of the root — it is only frontmatter there, and the
+ * exporter relies on that position (see the transformer's `export`).
+ */
+export function $setFrontmatter(source: string | null): void {
+  const existing = $frontmatterNode()
+  if (source === null) {
+    existing?.remove()
+    return
+  }
+  if (existing && $isLLuiDecoratorNode(existing)) {
+    existing.setData({ source })
+    return
+  }
+  const node = $createLLuiDecoratorNode(FRONTMATTER_BRIDGE_TYPE, { source })
+  const root = $getRoot()
+  const first = root.getFirstChild()
+  if (first) first.insertBefore(node)
+  else root.append(node)
+}
+
+// ── Transformer ─────────────────────────────────────────────────────────────
+
+const FRONTMATTER_TRANSFORMER: MultilineElementTransformer = {
+  dependencies: [LLuiDecoratorNode],
+  export: (node: LexicalNode): string | null => {
+    if (!$isLLuiDecoratorNode(node) || node.getBridgeType() !== FRONTMATTER_BRIDGE_TYPE) return null
+    const data = node.getData()
+    if (!isFrontmatterData(data)) return null
+    // Only the document's FIRST block can be emitted as fences: `---` anywhere
+    // else re-imports as a thematic break, which would silently destroy the
+    // metadata on the next round-trip. A stray block (dragged out of position,
+    // pasted into a quote, …) degrades to a visible ```yaml code fence instead —
+    // lossy in node type, but the text survives and the author can see why.
+    if ($getRoot().getFirstChild() !== node) return '```yaml\n' + data.source + '\n```'
+    return serializeFrontmatter(data.source)
+  },
+  regExpStart: FENCE,
+  // Never consulted: `handleImportAfterStartMatch` below always returns a
+  // decision, so the default open/close scan is not reached. Declared because
+  // the shape requires the pair to be meaningful together.
+  regExpEnd: FENCE,
+  handleImportAfterStartMatch: ({ lines, rootNode, startLineIndex }) => {
+    // Frontmatter exists only at the very top of the document. Anywhere else a
+    // `---` is a thematic break — decline so `hrPlugin` (or plain prose) gets it.
+    //
+    // INVARIANT — do not relax this guard without also fixing the scan below.
+    // `$importMarkdownNodes` assigns `i = shiftedIndex` from the returned tuple,
+    // so a returned index <= `startLineIndex` REWINDS its loop and the importer
+    // spins forever (not a wrong parse — a hang). The scan starts at line 1, so
+    // pinning `startLineIndex` to 0 is what makes every returned index strictly
+    // greater. A positional relaxation must start the scan at `startLineIndex + 1`.
+    if (startLineIndex !== 0) return null
+    const end = closingFenceIndex(lines)
+    if (end !== -1) {
+      // Verbatim body: no trimming, no interpretation, blank lines preserved.
+      const source = lines.slice(1, end).join('\n')
+      rootNode.append($createLLuiDecoratorNode(FRONTMATTER_BRIDGE_TYPE, { source }))
+      return [true, end]
+    }
+    // Unclosed: this is a lone `---` on line 1, i.e. a horizontal rule.
+    return null
+  },
+  // Typing `---` must never produce frontmatter — returning false hands the
+  // markdown shortcut back to `hrPlugin`. Use `$setFrontmatter` to create one.
+  replace: () => false,
+  type: 'multiline-element',
+}
+
+export { FRONTMATTER_TRANSFORMER }
+
+// ── Plugin ──────────────────────────────────────────────────────────────────
+
+export interface FrontmatterPluginOptions {
+  /** Render the raw block to a preview (e.g. parse with your own YAML library
+   * and draw a table). Return a DOM `Node` (mounted directly) or a **trusted**
+   * HTML string — see `renderedPreview`'s security note. */
+  render?: PreviewRender
+  /** Accessible label for the raw-source editor (default `'Frontmatter'`). */
+  label?: string
+  /** Placeholder shown for an empty block (default `'key: value'`). */
+  placeholder?: string
+  /** Show the raw source editor. Set false for a `render`-only presentation
+   * (the block still round-trips; it just isn't editable in place). Default true. */
+  editable?: boolean
+}
+
+/** Keep editor-level key/paste handling out of the frontmatter island. */
+const stop = (e: Event): void => e.stopPropagation()
+
+export function frontmatterPlugin(opts: FrontmatterPluginOptions = {}): MarkdownPlugin {
+  const editable = opts.editable ?? true
+
+  const bridge = decoratorBridge<FrontmatterData>(FRONTMATTER_BRIDGE_TYPE, (data, api) => {
+    const children: Mountable[] = []
+    if (editable) {
+      children.push(
+        // A <textarea>, NOT a contenteditable div: newlines are load-bearing in
+        // YAML, and a contenteditable's `textContent` drops the <br>/<div> line
+        // structure the browser inserts, so committing from one silently
+        // flattens a multi-line block into a single line.
+        textarea({
+          'data-scope': 'md-frontmatter',
+          'data-part': 'source',
+          'aria-label': opts.label ?? 'Frontmatter',
+          placeholder: opts.placeholder ?? 'key: value',
+          spellcheck: 'false',
+          autocapitalize: 'off',
+          autocomplete: 'off',
+          value: data.at('source') as Signal<string>,
+          // Grow with the content so the whole block stays visible.
+          rows: (data.at('source') as Signal<string>).map((source) =>
+            String(Math.max(1, source.split('\n').length)),
+          ),
+          onKeyDown: stop,
+          onBeforeInput: stop,
+          onPaste: stop,
+          // Commit on blur only: while the caret is inside, the node data is
+          // deliberately stale so the reactive `value` binding cannot rewrite
+          // what is being typed.
+          onBlur: (e: FocusEvent) => {
+            const source = (e.target as HTMLTextAreaElement).value
+            if (source !== data.peek().source) api.update({ source })
+          },
+        }),
+      )
+    }
+    if (opts.render) {
+      children.push(renderedPreview(data.at('source') as Signal<string>, opts.render))
+    }
+    return [
+      div(
+        { 'data-scope': 'md-frontmatter', 'data-part': 'root', contenteditable: 'false' },
+        children,
+      ),
+    ]
+  })
+
+  return {
+    name: 'frontmatter',
+    nodes: [LLuiDecoratorNode],
+    decorators: [bridge],
+    transformers: [FRONTMATTER_TRANSFORMER],
+    items: [
+      {
+        id: 'frontmatter',
+        label: 'Frontmatter',
+        icon: 'frontmatter',
+        group: 'insert',
+        keywords: ['frontmatter', 'yaml', 'metadata', 'front matter'],
+        // Idempotent: a document already carrying frontmatter is left alone
+        // rather than having its metadata blanked.
+        run: (editor: LexicalEditor) =>
+          editor.update(() => {
+            if ($getFrontmatter() === null) $setFrontmatter('')
+          }),
+        surfaces: ['slash', 'context'],
+      },
+    ],
+  }
+}

package/src/plugins/overlay.ts

@@ -18,6 +18,8 @@
 //   61 — context menu                        — pointer-anchored
 //   62 — floating selection toolbar          — selection-anchored bubble
 //   63 — table tools                         — element-anchored, sits over a table
+//   64 — code-block language badge           — element-anchored, may sit INSIDE a
+//                                              table cell, so it must clear 63
 // The values live with each plugin's view; this comment is the source of truth.
 
 import {
@@ -37,6 +39,11 @@ export const OVERLAY_Z = {
   contextMenu: 61,
   floatingToolbar: 62,
   tableTools: 63,
+  // Strictly above `tableTools`: a fenced code block can live inside a table
+  // cell, in which case both surfaces are open at once. At an equal z-index the
+  // clickable one was decided by portal insertion order — i.e. by plugin array
+  // order — which is exactly the no-tie rule this scale exists to prevent.
+  codeLanguage: 64,
 } as const
 
 const toMountables = (r: Renderable): Mountable[] => [...r]

package/src/plugins/table.ts

@@ -7,9 +7,10 @@
 
 import {
   $createParagraphNode,
-  $createTextNode,
   $getSelection,
   $isRangeSelection,
+  type ElementFormatType,
+  type ElementNode,
   type LexicalNode,
 } from 'lexical'
 import { $insertNodeToNearestRoot, mergeRegister } from '@lexical/utils'
@@ -30,12 +31,26 @@ import {
   TableNode,
   TableRowNode,
 } from '@lexical/table'
-import type { MultilineElementTransformer } from '@lexical/markdown'
+import {
+  $convertFromMarkdownString,
+  LINK,
+  type MultilineElementTransformer,
+  type Transformer,
+} from '@lexical/markdown'
 import { button, text } from '@llui/dom'
 import { definePluginUI } from './ui.js'
 import { OVERLAY_Z, hideOverlay, onViewportChange, overlayRoot } from './overlay.js'
+import { INLINE_TEXT_TRANSFORMERS } from '../transformers/gfm.js'
 import type { MarkdownPlugin } from './types.js'
 
+/** Transformers used to parse/serialize a single table cell's INLINE content
+ * (bold/italic/strikethrough/inline-code and links). No block/element or
+ * multiline transformers, so a cell's markdown is always a single inline run —
+ * this is what makes bold/link cells survive an export∘import round-trip instead
+ * of being flattened to bare text. `LINK` needs `LinkNode`, which the core plugin
+ * registers (tables are used alongside it). */
+const CELL_TRANSFORMERS: readonly Transformer[] = [...INLINE_TEXT_TRANSFORMERS, LINK]
+
 interface TableToolsState {
   open: boolean
   x: number
@@ -107,26 +122,71 @@ function isSeparator(line: string | undefined): boolean {
   return !!line && /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/.test(line) && line.includes('-')
 }
 
+/** Is `line` a GFM table row? GFM makes the leading and trailing pipes OPTIONAL
+ * (`a | b` is as valid as `| a | b |`); the only requirement is at least one
+ * unescaped cell delimiter. The old `\|.*\|` test rejected valid pipe-less-edge
+ * rows, truncating imported tables. */
 function isRow(line: string | undefined): boolean {
-  return !!line && /^\s*\|.*\|\s*$/.test(line.trim())
+  if (line === undefined) return false
+  const trimmed = line.trim()
+  return trimmed !== '' && /(?<!\\)\|/.test(trimmed)
 }
 
-function makeCell(textValue: string, header: boolean): TableCellNode {
+/** Map a GFM separator cell (`:---`, `:---:`, `---:`, `---`) to a cell alignment. */
+function parseAlignment(separatorCell: string): ElementFormatType {
+  const t = separatorCell.trim()
+  const left = t.startsWith(':')
+  const right = t.endsWith(':')
+  if (left && right) return 'center'
+  if (right) return 'right'
+  if (left) return 'left'
+  return ''
+}
+
+/** Map a cell's alignment back to its GFM separator token. */
+function alignmentSeparator(format: ElementFormatType): string {
+  switch (format) {
+    case 'center':
+      return ':---:'
+    case 'right':
+    case 'end':
+      return '---:'
+    case 'left':
+    case 'start':
+      return ':---'
+    default:
+      return '---'
+  }
+}
+
+/** Build a cell from its inline markdown, parsing bold/italic/link/etc. through
+ * {@link CELL_TRANSFORMERS} (not a bare text node) and applying its column's
+ * alignment. */
+function makeCell(cellMarkdown: string, header: boolean, align: ElementFormatType): TableCellNode {
   const cell = $createTableCellNode(
     header ? TableCellHeaderStates.COLUMN : TableCellHeaderStates.NO_STATUS,
   )
-  cell.append($createParagraphNode().append($createTextNode(textValue)))
+  // Parse the cell's inline markdown into a paragraph of formatted text nodes.
+  $convertFromMarkdownString(cellMarkdown, [...CELL_TRANSFORMERS], cell)
+  // A blank cell yields no paragraph — keep the cell a well-formed single-paragraph.
+  if (cell.getChildrenSize() === 0) cell.append($createParagraphNode())
+  if (align !== '') cell.setFormat(align)
   return cell
 }
 
-function buildTable(header: string[], body: string[][]): TableNode {
+function buildTable(
+  header: string[],
+  body: string[][],
+  aligns: readonly ElementFormatType[],
+): TableNode {
   const table = $createTableNode()
   const headerRow = $createTableRowNode()
-  for (const h of header) headerRow.append(makeCell(h, true))
+  header.forEach((h, i) => headerRow.append(makeCell(h, true, aligns[i] ?? '')))
   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))
+    for (let i = 0; i < header.length; i++)
+      tr.append(makeCell(row[i] ?? '', false, aligns[i] ?? ''))
     table.append(tr)
   }
   return table
@@ -134,29 +194,42 @@ function buildTable(header: string[], body: string[][]): TableNode {
 
 const TABLE_TRANSFORMER: MultilineElementTransformer = {
   dependencies: [TableNode, TableRowNode, TableCellNode],
-  export: (node: LexicalNode): string | null => {
+  export: (node: LexicalNode, traverseChildren: (node: ElementNode) => string): 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, ' '))
+      // Serialize each cell's INLINE content through the full transformer set
+      // (so bold/italic/links survive), then escape `|` and flatten newlines so
+      // the cell can't break the row.
+      const texts = cells.map((c) =>
+        traverseChildren(c).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ').trim(),
+      )
       lines.push('| ' + texts.join(' | ') + ' |')
-      if (ri === 0) lines.push('| ' + texts.map(() => '---').join(' | ') + ' |')
+      if (ri === 0) {
+        // Reconstruct the alignment row from the header cells' alignments.
+        const seps = cells.map((c) => alignmentSeparator(c.getFormatType()))
+        lines.push('| ' + seps.join(' | ') + ' |')
+      }
     })
     return lines.join('\n')
   },
-  regExpStart: /^\s*\|(.+)\|\s*$/,
+  // Leading/trailing pipes are optional in GFM; require only one internal pipe.
+  // A false positive is harmless — the header is only accepted when the NEXT line
+  // is a delimiter row (checked below).
+  regExpStart: /^\s*\|?.*(?<!\\)\|.*\|?\s*$/,
   handleImportAfterStartMatch: ({ lines, rootNode, startLineIndex }) => {
     if (!isSeparator(lines[startLineIndex + 1])) return null // header must be followed by a separator
+    const aligns = splitRow(lines[startLineIndex + 1]!).map(parseAlignment)
     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))
+    rootNode.append(buildTable(splitRow(lines[startLineIndex]!), body, aligns))
     return [true, end - 1]
   },
   // Import is handled manually above; a multiline transformer still needs replace.
@@ -274,6 +347,7 @@ export function tablePlugin(): MarkdownPlugin {
                   ['', ''],
                   ['', ''],
                 ],
+                ['', ''],
               ),
             ),
           ),