@llui/markdown-editor 0.2.12 → 0.2.13

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,
+  }
+}

package/src/state.ts

@@ -0,0 +1,220 @@
+// The editor's TEA state, messages, effects, and pure reducer. Lexical owns the
+// live document; this state holds JSON-serializable mirrors/derivations only, so
+// `update` stays pure and DOM-free (fully unit-testable).
+
+import type { Alignment } from '@llui/lexical'
+
+/** The block kind at the selection — base rich-text kinds plus list/code,
+ * resolved by the markdown layer. */
+export type BlockType =
+  | 'paragraph'
+  | 'h1'
+  | 'h2'
+  | 'h3'
+  | 'h4'
+  | 'h5'
+  | 'h6'
+  | 'quote'
+  | 'code'
+  | 'bullet'
+  | 'number'
+  | 'check'
+  | 'other'
+
+/** The toolbar-facing format surface at the current selection (all primitives). */
+export interface FormatState {
+  bold: boolean
+  italic: boolean
+  strikethrough: boolean
+  code: boolean
+  link: boolean
+  blockType: BlockType
+  alignment: Alignment
+  canUndo: boolean
+  canRedo: boolean
+}
+
+export const EMPTY_FORMAT: FormatState = {
+  bold: false,
+  italic: false,
+  strikethrough: false,
+  code: false,
+  link: false,
+  blockType: 'paragraph',
+  alignment: null,
+  canUndo: false,
+  canRedo: false,
+}
+
+/** Which floating surface is currently open. */
+export type OverlayKind = 'none' | 'floating' | 'slash' | 'context' | 'link'
+
+/** Live collaborative-session status (mirror of the CRDT provider state).
+ * `enabled` is false unless the editor was created with a `collab` factory. */
+export interface CollabStatus {
+  enabled: boolean
+  connected: boolean
+  synced: boolean
+  /** Remote peers currently present (excludes this client). */
+  peers: number
+}
+
+export const COLLAB_OFF: CollabStatus = {
+  enabled: false,
+  connected: false,
+  synced: false,
+  peers: 0,
+}
+
+export interface EditorState {
+  /** Last serialized markdown (mirror of the live document). */
+  value: string
+  format: FormatState
+  wordCount: number
+  charCount: number
+  ui: {
+    activeOverlay: OverlayKind
+    slashQuery: string
+    menu: { x: number; y: number }
+  }
+  /** Per-plugin UI state slices, keyed by plugin name (see {@link PluginUI}). */
+  plugins: Record<string, unknown>
+  dirty: boolean
+  readonly: boolean
+  /** Collaborative-session status (always present; inert unless `collab` set). */
+  collab: CollabStatus
+}
+
+export type EditorMsg =
+  | { type: 'markdownChanged'; value: string }
+  | { type: 'formatChanged'; format: FormatState; wordCount: number; charCount: number }
+  | { type: 'runCommand'; id: string }
+  | { type: 'setValue'; value: string }
+  | { type: 'openOverlay'; overlay: OverlayKind; x?: number; y?: number }
+  | { type: 'closeOverlay' }
+  | { type: 'slashQuery'; query: string }
+  | { type: 'setReadOnly'; readonly: boolean }
+  | { type: 'collabStatus'; connected: boolean }
+  | { type: 'collabSync'; synced: boolean }
+  | { type: 'collabPeers'; peers: number }
+  /** Route a message to a plugin's UI reducer (see {@link PluginUI}). */
+  | { type: 'plugin'; name: string; msg: unknown }
+
+/** The subset of messages a plugin may emit through its `PluginContext` (e.g. a
+ * `register` listener routing an editor event into its own plugin UI). */
+export type EditorOutMsg = Extract<
+  EditorMsg,
+  { type: 'openOverlay' | 'closeOverlay' | 'slashQuery' | 'plugin' }
+>
+
+export type EditorEffect =
+  | { type: 'execCommand'; id: string }
+  | { type: 'applyValue'; value: string }
+  | { type: 'emitChange'; value: string }
+  | { type: 'emitFormat'; format: FormatState }
+  /** An effect produced by a plugin's UI reducer (see {@link PluginUI}). */
+  | { type: 'pluginEffect'; name: string; effect: unknown }
+
+export interface InitOptions {
+  value: string
+  readonly: boolean
+  /** Whether a collaborative session is wired (drives `collab.enabled`). */
+  collab?: boolean
+}
+
+export function init(opts: InitOptions): [EditorState, EditorEffect[]] {
+  const wordCount = countWords(opts.value)
+  return [
+    {
+      value: opts.value,
+      format: EMPTY_FORMAT,
+      wordCount,
+      charCount: opts.value.length,
+      ui: { activeOverlay: 'none', slashQuery: '', menu: { x: 0, y: 0 } },
+      plugins: {},
+      dirty: false,
+      readonly: opts.readonly,
+      collab: { ...COLLAB_OFF, enabled: opts.collab ?? false },
+    },
+    [],
+  ]
+}
+
+export function update(state: EditorState, msg: EditorMsg): [EditorState, EditorEffect[]] {
+  switch (msg.type) {
+    case 'markdownChanged': {
+      // Idempotent: re-emitting the current value is a no-op (echo safety).
+      if (msg.value === state.value) return [state, []]
+      return [
+        { ...state, value: msg.value, dirty: true },
+        [{ type: 'emitChange', value: msg.value }],
+      ]
+    }
+    case 'formatChanged': {
+      return [
+        { ...state, format: msg.format, wordCount: msg.wordCount, charCount: msg.charCount },
+        [{ type: 'emitFormat', format: msg.format }],
+      ]
+    }
+    case 'runCommand': {
+      return [state, [{ type: 'execCommand', id: msg.id }]]
+    }
+    case 'setValue': {
+      // External markdown push (via the component handle). Idempotent; does not
+      // re-emit onChange (the consumer already owns this value).
+      if (msg.value === state.value) return [state, []]
+      return [
+        { ...state, value: msg.value, dirty: true },
+        [{ type: 'applyValue', value: msg.value }],
+      ]
+    }
+    case 'openOverlay': {
+      return [
+        {
+          ...state,
+          ui: {
+            ...state.ui,
+            activeOverlay: msg.overlay,
+            slashQuery: msg.overlay === 'slash' ? '' : state.ui.slashQuery,
+            menu: { x: msg.x ?? state.ui.menu.x, y: msg.y ?? state.ui.menu.y },
+          },
+        },
+        [],
+      ]
+    }
+    case 'closeOverlay': {
+      if (state.ui.activeOverlay === 'none') return [state, []]
+      return [{ ...state, ui: { ...state.ui, activeOverlay: 'none', slashQuery: '' } }, []]
+    }
+    case 'slashQuery': {
+      return [{ ...state, ui: { ...state.ui, slashQuery: msg.query } }, []]
+    }
+    case 'setReadOnly': {
+      if (state.readonly === msg.readonly) return [state, []]
+      return [{ ...state, readonly: msg.readonly }, []]
+    }
+    case 'collabStatus': {
+      if (state.collab.connected === msg.connected) return [state, []]
+      return [{ ...state, collab: { ...state.collab, connected: msg.connected } }, []]
+    }
+    case 'collabSync': {
+      if (state.collab.synced === msg.synced) return [state, []]
+      return [{ ...state, collab: { ...state.collab, synced: msg.synced } }, []]
+    }
+    case 'collabPeers': {
+      if (state.collab.peers === msg.peers) return [state, []]
+      return [{ ...state, collab: { ...state.collab, peers: msg.peers } }, []]
+    }
+    case 'plugin': {
+      // Plugin messages are routed by the host's composed reducer (it holds the
+      // plugin registry); the pure core reducer treats them as a no-op.
+      return [state, []]
+    }
+  }
+}
+
+/** Count whitespace-delimited words (shared by init and the format handler). */
+export function countWords(text: string): number {
+  const trimmed = text.trim()
+  return trimmed === '' ? 0 : trimmed.split(/\s+/).length
+}