@llui/markdown-editor 0.2.12 → 0.2.13

package/README.md

@@ -0,0 +1,44 @@
+# @llui/markdown-editor
+
+WYSIWYG Markdown editor for [LLui](https://github.com/fponticelli/llui) — hides Markdown behind a rich, pluggable editing widget built on Lexical.
+
+```bash
+pnpm add @llui/markdown-editor @llui/lexical @llui/components lexical
+```
+
+## Usage
+
+```ts
+import { mountApp } from '@llui/dom'
+import { markdownEditor } from '@llui/markdown-editor'
+import '@llui/markdown-editor/styles/editor.css'
+
+// `markdownEditor()` returns a component definition; mount it (or compose it).
+mountApp(
+  document.getElementById('editor')!,
+  markdownEditor({
+    defaultValue: '# Hello\n\nStart typing…',
+    toolbar: true,
+    onChange: (markdown) => console.log(markdown),
+  }),
+)
+```
+
+## What it provides
+
+- **`markdownEditor()`** — the editor component, built on the [`@llui/lexical`](https://www.npmjs.com/package/@llui/lexical) seam.
+- **Transformer registry** — GFM and callout plugins (`./plugins/core`, `./plugins/callout`) that map Markdown constructs to Lexical nodes.
+- **Toolbar surface** — an optional formatting toolbar (`./surfaces/toolbar`).
+- **`collab` seam** — opt-in collaborative editing via [`@llui/lexical-collab`](https://www.npmjs.com/package/@llui/lexical-collab).
+
+## Entry points
+
+| Import                                    | Purpose                        |
+| ----------------------------------------- | ------------------------------ |
+| `@llui/markdown-editor`                   | `markdownEditor()` component   |
+| `@llui/markdown-editor/plugins/core`      | Core GFM transformers          |
+| `@llui/markdown-editor/plugins/callout`   | Callout/admonition transformer |
+| `@llui/markdown-editor/surfaces/toolbar`  | Toolbar surface                |
+| `@llui/markdown-editor/styles/editor.css` | Editor styles                  |
+
+Peers on `@llui/dom`, `@llui/lexical`, `@llui/components`, `lexical`, and the relevant `@lexical/*` packages (`^0.46`).

package/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@llui/markdown-editor",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
     "./plugins/core": {
-      "import": "./dist/plugins/core.js",
-      "types": "./dist/plugins/core.d.ts"
+      "types": "./dist/plugins/core.d.ts",
+      "import": "./dist/plugins/core.js"
     },
     "./plugins/callout": {
-      "import": "./dist/plugins/callout.js",
-      "types": "./dist/plugins/callout.d.ts"
+      "types": "./dist/plugins/callout.d.ts",
+      "import": "./dist/plugins/callout.js"
     },
     "./surfaces/toolbar": {
-      "import": "./dist/surfaces/toolbar.js",
-      "types": "./dist/surfaces/toolbar.d.ts"
+      "types": "./dist/surfaces/toolbar.d.ts",
+      "import": "./dist/surfaces/toolbar.js"
     },
     "./styles/editor.css": "./dist/styles/editor.css"
   },
@@ -50,9 +50,9 @@
     "typescript": "^6.0.0",
     "vitest": "^4.1.2",
     "@lexical/code-core": "^0.46.0",
-    "@llui/dom": "0.11.5",
-    "@llui/lexical": "0.2.8",
-    "@llui/components": "0.12.2"
+    "@llui/dom": "0.11.7",
+    "@llui/lexical": "0.2.9",
+    "@llui/components": "0.12.3"
   },
   "sideEffects": [
     "./dist/styles/editor.css"
@@ -78,8 +78,12 @@
   },
   "homepage": "https://github.com/fponticelli/llui/tree/main/packages/markdown-editor#readme",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && mkdir -p dist/styles && cp src/styles/editor.css dist/styles/",
     "check": "tsc --noEmit -p tsconfig.check.json",

package/src/editor.ts

@@ -0,0 +1,303 @@
+// `markdownEditor(config)` — the high-level component. Lexical owns the live
+// document; this wires the foreign seam to the markdown transformer converters,
+// surfaces the format state for the chrome, routes command intents back to the
+// live editor through effects, and COMPOSES plugin UI extensions (each plugin's
+// state slice + reducer + view + effects) into the single component.
+
+import { $getRoot, $setSelection, type EditorThemeClasses, type LexicalEditor } from 'lexical'
+import {
+  $convertFromMarkdownString,
+  $convertToMarkdownString,
+  registerMarkdownShortcuts,
+} from '@lexical/markdown'
+import { component, div, type Renderable, type Signal, type SignalComponentDef } from '@llui/dom'
+import {
+  lexicalForeign,
+  registerDecoratorBridges,
+  PROGRAMMATIC_TAG,
+  type DecoratorBridge,
+} from '@llui/lexical'
+import { corePlugin } from './plugins/core.js'
+import { linkPlugin } from './plugins/link.js'
+import { registerMarkdownPaste } from './paste.js'
+import { toolbar as renderToolbar } from './surfaces/toolbar.js'
+import type { CommandItem, MarkdownPlugin } from './plugins/types.js'
+import type { PluginUI } from './plugins/ui.js'
+import { buildTransformers } from './transformers/registry.js'
+import { mergeTheme } from './theme.js'
+import { computeFormatState } from './format.js'
+import { makeOnEffect } from './effects.js'
+import {
+  countWords,
+  init,
+  update,
+  type EditorEffect,
+  type EditorMsg,
+  type EditorOutMsg,
+  type EditorState,
+  type FormatState,
+} from './state.js'
+
+export interface EditorConfig {
+  /** Plugins composing the feature set; order defines transformer precedence.
+   * Defaults to `[corePlugin(), linkPlugin()]` so the minimal editor has GFM + links. */
+  plugins?: readonly MarkdownPlugin[]
+  /** Initial markdown (uncontrolled seed). */
+  defaultValue?: string
+  /** Controlled: the consumer owns this signal; the editor follows it. */
+  value?: Signal<string>
+  /** Debounced markdown-emission window (ms). Default 300. */
+  changeDebounceMs?: number
+  placeholder?: string
+  readonly?: boolean
+  /** Lexical theme class map. */
+  theme?: EditorThemeClasses
+  /** Editor namespace (instance isolation). */
+  namespace?: string
+  /** Outbound markdown (after debounce). */
+  onChange?: (markdown: string) => void
+  /** Outbound format surface (for chrome built outside this package). */
+  onFormatChange?: (format: FormatState) => void
+  /** Receives the live Lexical editor at mount (imperative access, collab hooks). */
+  onReady?: (editor: LexicalEditor) => void
+  /** Render the built-in toolbar above the editor. Default false (minimal). */
+  toolbar?: boolean
+  /** Convert plain-text Markdown to rich content on paste. Default true.
+   * Pastes that carry `text/html` are always left to Lexical's HTML import,
+   * regardless of this flag. Set false to paste Markdown as literal text. */
+  pasteMarkdown?: boolean
+  /** Enable collaborative editing. The editor hands you a markdown `seed` and
+   * status sinks; return a binding (build it with `yjsCollab` from
+   * `@llui/lexical-collab`, wiring your own provider). Mutually exclusive with
+   * `value` — the shared CRDT document, not a markdown signal, owns the content.
+   * `defaultValue` becomes the seed the bootstrapping peer writes. */
+  collab?: CollabFactory
+}
+
+/** Disposer-returning binding the collab layer installs on the live editor.
+ * `@llui/lexical-collab`'s `YjsCollab` satisfies this structurally, so
+ * `@llui/markdown-editor` needs no Yjs dependency of its own. */
+export interface CollabBinding {
+  register: (editor: LexicalEditor) => () => void
+}
+
+/** Hooks the editor injects into the {@link CollabFactory}: a markdown `seed`
+ * (run once by the bootstrapping peer to fill an empty shared doc from
+ * `defaultValue`) plus status sinks the editor mirrors into `state.collab`.
+ * Spread straight into `yjsCollab({ id, provider, user, ...hooks })`. */
+export interface CollabHooks {
+  seed: (editor: LexicalEditor) => void
+  onStatus: (connected: boolean) => void
+  onSync: (synced: boolean) => void
+  onPeers: (count: number) => void
+}
+
+/** Builds the collab binding from the editor-supplied hooks. */
+export type CollabFactory = (hooks: CollabHooks) => CollabBinding
+
+/** Hooks the chrome layer (toolbar/menus) uses to compose around the editor. */
+export interface EditorParts {
+  /** The merged, surface-filtered command items. */
+  items: readonly CommandItem[]
+  /** Reactive format signal for `connect`-style toolbars. */
+  format: Signal<FormatState>
+}
+
+/** Default plugin set when the consumer supplies none. */
+function defaultPlugins(): MarkdownPlugin[] {
+  return [corePlugin(), linkPlugin()]
+}
+
+/**
+ * Build the markdown editor component. Embed it with `mountApp(el, markdownEditor(...))`
+ * or compose it inside a larger component.
+ */
+export function markdownEditor(
+  config: EditorConfig = {},
+): SignalComponentDef<EditorState, EditorMsg, EditorEffect> {
+  const plugins = config.plugins && config.plugins.length > 0 ? config.plugins : defaultPlugins()
+  const transformers = buildTransformers(plugins)
+
+  const items: CommandItem[] = plugins.flatMap((p) => p.items ?? [])
+  const itemsById = new Map(items.map((i) => [i.id, i]))
+  // Share the merged item list with plugins that want it (e.g. the slash menu).
+  for (const plugin of plugins) plugin.onItems?.(items)
+  const decorators: DecoratorBridge[] = plugins.flatMap((p) => p.decorators ?? [])
+  const pluginUIs: Array<{ name: string; ui: PluginUI }> = plugins
+    .filter((p): p is MarkdownPlugin & { ui: PluginUI } => p.ui !== undefined)
+    .map((p) => ({ name: p.name, ui: p.ui }))
+  const pluginUIByName = new Map(pluginUIs.map((p) => [p.name, p.ui]))
+
+  // The live editor, captured at mount; effects dispatch through it.
+  let editorRef: LexicalEditor | null = null
+  const getEditor = (): LexicalEditor | null => editorRef
+
+  const baseOnEffect = makeOnEffect(getEditor, itemsById, {
+    onChange: config.onChange,
+    onFormatChange: config.onFormatChange,
+    applyValue: (editor, value) =>
+      editor.update(
+        () => {
+          $convertFromMarkdownString(value, transformers)
+          // Clear selection so the reconciler doesn't pull DOM focus into the
+          // editor on an external push (e.g. typing in a bound source textarea).
+          $setSelection(null)
+        },
+        { tag: PROGRAMMATIC_TAG },
+      ),
+  })
+
+  if (config.collab && config.value) {
+    throw new Error(
+      'markdownEditor: `collab` and `value` are mutually exclusive — in a collaborative ' +
+        'session the shared CRDT document owns the content, not a markdown signal. ' +
+        'Use `defaultValue` as the bootstrap seed instead.',
+    )
+  }
+
+  const collabEnabled = !!config.collab
+  const seedValue = config.value ? config.value.peek() : (config.defaultValue ?? '')
+
+  // ── Composed TEA: core + plugin UI slices ──────────────────────────────────
+  const composedInit = (): [EditorState, EditorEffect[]] => {
+    const [core, effects] = init({
+      value: seedValue,
+      readonly: config.readonly ?? false,
+      collab: collabEnabled,
+    })
+    const slices: Record<string, unknown> = {}
+    for (const { name, ui } of pluginUIs) slices[name] = ui.init()
+    return [{ ...core, plugins: slices }, effects]
+  }
+
+  const composedUpdate = (state: EditorState, msg: EditorMsg): [EditorState, EditorEffect[]] => {
+    if (msg.type === 'plugin') {
+      const ui = pluginUIByName.get(msg.name)
+      if (!ui?.update) return [state, []]
+      const result = ui.update(state.plugins[msg.name], msg.msg)
+      const [slice, effects] = (Array.isArray(result) ? result : [result, []]) as [
+        unknown,
+        unknown[],
+      ]
+      return [
+        { ...state, plugins: { ...state.plugins, [msg.name]: slice } },
+        effects.map((effect) => ({ type: 'pluginEffect' as const, name: msg.name, effect })),
+      ]
+    }
+    return update(state, msg)
+  }
+
+  const composedOnEffect = (
+    effect: EditorEffect,
+    api: { send: (msg: EditorMsg) => void; state: Signal<EditorState> },
+  ): void => {
+    if (effect.type === 'pluginEffect') {
+      const ui = pluginUIByName.get(effect.name)
+      ui?.onEffect?.(effect.effect, {
+        editor: getEditor,
+        send: (msg) => api.send({ type: 'plugin', name: effect.name, msg }),
+        emit: (msg) => api.send(msg as EditorMsg),
+      })
+      return
+    }
+    baseOnEffect(effect, api)
+  }
+
+  const view = ({
+    state,
+    send,
+  }: {
+    state: Signal<EditorState>
+    send: (msg: EditorMsg) => void
+  }): Renderable => {
+    // Build the collab binding (once, at mount) from the consumer's factory,
+    // injecting the markdown seed + status sinks that mirror into `state.collab`.
+    const collabBinding: CollabBinding | null = config.collab
+      ? config.collab({
+          seed: () => {
+            $convertFromMarkdownString(seedValue, transformers)
+            $setSelection(null)
+          },
+          onStatus: (connected) => send({ type: 'collabStatus', connected }),
+          onSync: (synced) => send({ type: 'collabSync', synced }),
+          onPeers: (peers) => send({ type: 'collabPeers', peers }),
+        })
+      : null
+
+    const host = lexicalForeign<EditorOutMsg>({
+      namespace: config.namespace ?? 'llui-markdown',
+      theme: mergeTheme(config.theme),
+      plugins,
+      serialize: (editor) =>
+        editor.getEditorState().read(() => $convertToMarkdownString(transformers)),
+      deserialize: (_editor, value) => {
+        $convertFromMarkdownString(value, transformers)
+        $setSelection(null)
+      },
+      // In collab mode the shared CRDT owns the document: the local undo stack
+      // and the boot-time seed are disabled — the binding supplies a scoped undo
+      // manager and a sync-gated bootstrap instead.
+      ...(collabBinding ? { history: false, seedMode: 'deferred' as const } : {}),
+      defaultValue: collabBinding || config.value ? undefined : (config.defaultValue ?? ''),
+      ...(config.value && !collabBinding ? { value: config.value } : {}),
+      readonly: state.at('readonly'),
+      ...(config.changeDebounceMs !== undefined
+        ? { changeDebounceMs: config.changeDebounceMs }
+        : {}),
+      register: (editor) => {
+        const disposers = [registerMarkdownShortcuts(editor, transformers)]
+        if (config.pasteMarkdown !== false)
+          disposers.push(registerMarkdownPaste(editor, transformers))
+        if (decorators.length > 0) disposers.push(registerDecoratorBridges(editor, decorators))
+        if (collabBinding) disposers.push(collabBinding.register(editor))
+        return () => {
+          for (const dispose of disposers) dispose()
+        }
+      },
+      onReady: (editor) => {
+        editorRef = editor
+        if (config.placeholder) {
+          editor.getRootElement()?.setAttribute('data-placeholder', config.placeholder)
+        }
+        config.onReady?.(editor)
+      },
+      onChange: (value) => send({ type: 'markdownChanged', value }),
+      onSelectionChange: (ctx) => {
+        const format = computeFormatState(ctx.editor, ctx)
+        const text = ctx.editor.getEditorState().read(() => $getRoot().getTextContent())
+        // Toggle an empty marker so CSS can show the placeholder.
+        ctx.editor.getRootElement()?.setAttribute('data-empty', text === '' ? 'true' : 'false')
+        send({ type: 'formatChanged', format, wordCount: countWords(text), charCount: text.length })
+      },
+      emit: (msg) => send(msg),
+    })
+
+    // Plugin view contributions (overlays/panels) — each gets its own slice + send.
+    const pluginViews: Renderable = pluginUIs.flatMap(({ name, ui }) => {
+      if (!ui.view) return []
+      const rendered = ui.view({
+        state: state.at(`plugins.${name}`),
+        send: (msg) => send({ type: 'plugin', name, msg }),
+        editor: getEditor,
+      })
+      return Array.isArray(rendered) ? rendered : [rendered]
+    })
+
+    if (!config.toolbar) return [host, ...pluginViews]
+    return [
+      div({ 'data-scope': 'md-editor', 'data-part': 'root' }, [
+        renderToolbar({ format: state.at('format'), send, items, collab: state.at('collab') }),
+        div({ 'data-scope': 'md-editor', 'data-part': 'surface' }, [host]),
+      ]),
+      ...pluginViews,
+    ]
+  }
+
+  return component<EditorState, EditorMsg, EditorEffect>({
+    name: 'MarkdownEditor',
+    init: composedInit,
+    update: composedUpdate,
+    view,
+    onEffect: composedOnEffect,
+  })
+}

package/src/effects.ts

@@ -0,0 +1,51 @@
+// Effect handler: the only place TEA reaches back into the live Lexical editor.
+// `execCommand` looks an id up in the merged command-item map and runs it on the
+// editor captured at mount; emit* forward to the consumer's callbacks.
+
+import type { LexicalEditor } from 'lexical'
+import type { CommandItem } from './plugins/types.js'
+import type { EditorEffect, EditorMsg, FormatState } from './state.js'
+
+/** The api the component passes to `onEffect` (send + state). */
+export interface EffectApi {
+  send: (msg: EditorMsg) => void
+}
+
+export interface EffectConfig {
+  onChange?: (markdown: string) => void
+  onFormatChange?: (format: FormatState) => void
+  /** Push markdown into the live editor (deserialize), without echoing onChange. */
+  applyValue: (editor: LexicalEditor, value: string) => void
+}
+
+/** Build the component's `onEffect`. `getEditor` returns the live editor (set at
+ * mount via the foreign `onReady`); `items` is the merged id → command map. */
+export function makeOnEffect(
+  getEditor: () => LexicalEditor | null,
+  items: ReadonlyMap<string, CommandItem>,
+  config: EffectConfig,
+): (effect: EditorEffect, api: EffectApi) => void {
+  return (effect, api) => {
+    switch (effect.type) {
+      case 'execCommand': {
+        const editor = getEditor()
+        const item = items.get(effect.id)
+        if (editor && item) item.run(editor, { send: api.send })
+        return
+      }
+      case 'applyValue': {
+        const editor = getEditor()
+        if (editor) config.applyValue(editor, effect.value)
+        return
+      }
+      case 'emitChange': {
+        config.onChange?.(effect.value)
+        return
+      }
+      case 'emitFormat': {
+        config.onFormatChange?.(effect.format)
+        return
+      }
+    }
+  }
+}

package/src/format.ts

@@ -0,0 +1,57 @@
+// Compute the full toolbar FormatState from a Lexical selection — the base
+// rich-text format (from @llui/lexical) refined with list/code/link detection
+// (which needs the list/code/link packages this layer depends on).
+
+import { $getSelection, $isRangeSelection, type LexicalEditor } from 'lexical'
+import { $findMatchingParent, $getNearestNodeOfType } from '@lexical/utils'
+import { ListNode, $isListItemNode } from '@lexical/list'
+import { $isCodeNode } from '@lexical/code-core'
+import { $isLinkNode } from '@lexical/link'
+import { $readBaseFormat } from '@llui/lexical'
+import type { SelectionContext } from '@llui/lexical'
+import { EMPTY_FORMAT, type BlockType, type FormatState } from './state.js'
+
+/** Read the full format surface at the current selection (opens a read ctx). */
+export function computeFormatState(
+  editor: LexicalEditor,
+  history: Pick<SelectionContext, 'canUndo' | 'canRedo'>,
+): FormatState {
+  return editor.getEditorState().read(() => {
+    const base = $readBaseFormat()
+    if (!base.hasSelection) {
+      return { ...EMPTY_FORMAT, canUndo: history.canUndo, canRedo: history.canRedo }
+    }
+
+    let blockType: BlockType = base.blockType
+    let link = false
+
+    const selection = $getSelection()
+    if ($isRangeSelection(selection)) {
+      const anchorNode = selection.anchor.getNode()
+      link = $findMatchingParent(anchorNode, (node) => $isLinkNode(node)) !== null
+
+      if (base.blockType === 'other') {
+        const listItem = $findMatchingParent(anchorNode, (node) => $isListItemNode(node))
+        if (listItem) {
+          const list = $getNearestNodeOfType(anchorNode, ListNode)
+          if (list) blockType = list.getListType()
+        } else {
+          const top = anchorNode.getKey() === 'root' ? null : anchorNode.getTopLevelElement()
+          if (top && $isCodeNode(top)) blockType = 'code'
+        }
+      }
+    }
+
+    return {
+      bold: base.bold,
+      italic: base.italic,
+      strikethrough: base.strikethrough,
+      code: base.code,
+      link,
+      blockType,
+      alignment: base.alignment,
+      canUndo: history.canUndo,
+      canRedo: history.canRedo,
+    }
+  })
+}

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'