@llui/markdown-editor 0.2.12 → 0.2.14

package/src/surfaces/toolbar.ts

@@ -0,0 +1,246 @@
+// Toolbar surface. `connectToolbar` returns a parts bag (the @llui/components
+// idiom) driven reactively by the format signal; `toolbar` is a ready-made
+// grouped toolbar Mountable for consumers who don't want to hand-render buttons.
+
+import {
+  button,
+  div,
+  option,
+  select,
+  span,
+  text,
+  tagSend,
+  unsafeHtml,
+  type Mountable,
+  type Send,
+  type Signal,
+} from '@llui/dom'
+import type { CommandItem } from '../plugins/types.js'
+import type { CollabStatus, EditorMsg, FormatState } from '../state.js'
+
+export interface ToolbarItemParts {
+  type: 'button'
+  'data-scope': 'md-toolbar'
+  'data-part': 'item'
+  'data-id': string
+  'aria-label': string
+  title: string
+  'aria-pressed': Signal<'true' | 'false'>
+  'aria-disabled': Signal<'true' | undefined>
+  disabled: Signal<boolean>
+  'data-active': Signal<'' | undefined>
+  onClick: (e: MouseEvent) => void
+}
+
+export interface ToolbarParts {
+  root: {
+    role: 'toolbar'
+    'aria-label': string
+    'data-scope': 'md-toolbar'
+    'data-part': 'root'
+  }
+  item: (id: string) => ToolbarItemParts
+}
+
+/** Build reactive toolbar parts from the format signal. Spread `item(id)` onto a
+ * `<button>`; `aria-pressed` / `data-active` / `disabled` track the format. */
+export function connectToolbar(
+  format: Signal<FormatState>,
+  send: Send<EditorMsg>,
+  items: readonly CommandItem[],
+): ToolbarParts {
+  const byId = new Map(items.map((i) => [i.id, i]))
+  return {
+    root: {
+      role: 'toolbar',
+      'aria-label': 'Formatting',
+      'data-scope': 'md-toolbar',
+      'data-part': 'root',
+    },
+    item: (id) => {
+      const item = byId.get(id)
+      const label = item?.label ?? id
+      return {
+        type: 'button',
+        'data-scope': 'md-toolbar',
+        'data-part': 'item',
+        'data-id': id,
+        'aria-label': label,
+        title: label,
+        'aria-pressed': format.map((f) => (item?.isActive?.(f) ? 'true' : 'false')),
+        'aria-disabled': format.map((f) => (item?.isDisabled?.(f) ? 'true' : undefined)),
+        disabled: format.map((f) => item?.isDisabled?.(f) ?? false),
+        'data-active': format.map((f) => (item?.isActive?.(f) ? '' : undefined)),
+        onClick: tagSend(send, ['runCommand'], () => send({ type: 'runCommand', id })),
+      }
+    },
+  }
+}
+
+/** Inline SVG icon (monochrome, inherits `currentColor`) used where a glyph
+ * reads poorly. A glyph string starting with `<svg` is rendered as markup. */
+const LINK_ICON =
+  '<svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M9.5 13.5a3.5 3.5 0 0 0 5 0l3-3a3.5 3.5 0 1 0-5-5l-1 1"/><path d="M14.5 10.5a3.5 3.5 0 0 0-5 0l-3 3a3.5 3.5 0 1 0 5 5l1-1"/></svg>'
+
+const IMAGE_ICON =
+  '<svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="16" rx="2"/><circle cx="9" cy="9.5" r="1.6"/><path d="m4 18 5-5 4 4 3-3 4 4"/></svg>'
+
+/** Compact glyphs so the default toolbar reads as a real toolbar without icon
+ * assets. SVG strings render as icons; everything else as text. Override via
+ * `ToolbarOptions.glyphs`. */
+export const DEFAULT_GLYPHS: Readonly<Record<string, string>> = {
+  bold: 'B',
+  italic: 'I',
+  strikethrough: 'S',
+  code: '</>',
+  link: LINK_ICON,
+  image: IMAGE_ICON,
+  hr: '—',
+  table: '▦',
+  paragraph: '¶',
+  h1: 'H1',
+  h2: 'H2',
+  h3: 'H3',
+  quote: '❝',
+  codeBlock: '{ }',
+  bulletList: '•',
+  numberList: '1.',
+  checkList: '☑',
+  undo: '↺',
+  redo: '↻',
+}
+
+const GROUP_ORDER = ['inline', 'block', 'list', 'insert', 'history']
+
+function groupItems(items: readonly CommandItem[]): string[][] {
+  const groups = new Map<string, string[]>()
+  for (const item of items) {
+    const key = item.group ?? 'other'
+    const list = groups.get(key) ?? []
+    list.push(item.id)
+    groups.set(key, list)
+  }
+  const ordered: string[][] = []
+  for (const key of GROUP_ORDER) {
+    const list = groups.get(key)
+    if (list) ordered.push(list)
+  }
+  for (const [key, list] of groups) {
+    if (!GROUP_ORDER.includes(key)) ordered.push(list)
+  }
+  return ordered
+}
+
+export interface ToolbarOptions {
+  format: Signal<FormatState>
+  send: Send<EditorMsg>
+  items: readonly CommandItem[]
+  /** Explicit grouped layout of ids; defaults to grouping by `item.group`. */
+  groups?: readonly (readonly string[])[]
+  /** Glyph overrides (id → text/emoji). Merged over {@link DEFAULT_GLYPHS}. */
+  glyphs?: Readonly<Record<string, string>>
+  /** Render the `block` group as a `<select>` dropdown instead of buttons
+   * (default true). */
+  blockSelect?: boolean
+  /** Collaborative-session status. When supplied AND `enabled`, the toolbar
+   * appends a presence indicator (connection dot + live peer count). */
+  collab?: Signal<CollabStatus>
+  'aria-label'?: string
+}
+
+/** Connection/presence indicator for a collaborative session. */
+function presenceIndicator(collab: Signal<CollabStatus>): Mountable {
+  const statusOf = (c: CollabStatus): string =>
+    c.connected ? (c.synced ? 'synced' : 'connecting') : 'offline'
+  return div({ 'data-scope': 'md-toolbar', 'data-part': 'presence' }, [
+    span({
+      'data-part': 'presence-status',
+      'data-status': collab.map(statusOf),
+      'aria-hidden': 'true',
+      title: collab.map(statusOf),
+    }),
+    span(
+      {
+        'data-part': 'presence-peers',
+        role: 'status',
+        'aria-live': 'polite',
+      },
+      [text(collab.map((c) => (c.peers === 0 ? 'Only you' : `${c.peers + 1} editing`)))],
+    ),
+  ])
+}
+
+/** Render the `block` group as a native `<select>` of block types. */
+function blockTypeSelect(
+  format: Signal<FormatState>,
+  send: Send<EditorMsg>,
+  blockItems: readonly CommandItem[],
+): Mountable {
+  return select(
+    {
+      'data-scope': 'md-toolbar',
+      'data-part': 'block-select',
+      'aria-label': 'Block type',
+      value: format.map((f) => blockItems.find((i) => i.isActive?.(f))?.id ?? ''),
+      onChange: (e: Event) => {
+        const id = (e.currentTarget as HTMLSelectElement).value
+        if (id) send({ type: 'runCommand', id })
+      },
+    },
+    [
+      option({ value: '', hidden: true }, [text('—')]),
+      ...blockItems.map((i) => option({ value: i.id }, [text(i.label)])),
+    ],
+  )
+}
+
+/** A ready-made grouped toolbar. Items not surfaced to `'toolbar'` are dropped. */
+export function toolbar(opts: ToolbarOptions): Mountable {
+  const surfaceItems = opts.items.filter((i) => i.surfaces?.includes('toolbar') ?? true)
+  const byId = new Map(surfaceItems.map((i) => [i.id, i]))
+  const parts = connectToolbar(opts.format, opts.send, surfaceItems)
+  const glyphs = { ...DEFAULT_GLYPHS, ...(opts.glyphs ?? {}) }
+
+  const useBlockSelect = opts.blockSelect !== false && !opts.groups
+  const blockItems = useBlockSelect ? surfaceItems.filter((i) => i.group === 'block') : []
+  const buttonItems = useBlockSelect
+    ? surfaceItems.filter((i) => i.group !== 'block')
+    : surfaceItems
+  const groups = opts.groups ?? groupItems(buttonItems)
+
+  const children: Mountable[] = []
+  if (blockItems.length > 0) {
+    children.push(
+      div({ 'data-scope': 'md-toolbar', 'data-part': 'group' }, [
+        blockTypeSelect(opts.format, opts.send, blockItems),
+      ]),
+    )
+  }
+  for (const ids of groups) {
+    const present = ids.filter((id) => byId.has(id))
+    if (present.length === 0) continue
+    children.push(
+      div(
+        { 'data-scope': 'md-toolbar', 'data-part': 'group' },
+        present.map((id) => {
+          const item = byId.get(id)!
+          const glyph = glyphs[id] ?? item.label
+          const glyphNode = glyph.trimStart().startsWith('<svg') ? unsafeHtml(glyph) : text(glyph)
+          return button({ ...parts.item(id) }, [
+            span({ 'data-part': 'glyph', 'aria-hidden': 'true' }, [glyphNode]),
+          ])
+        }),
+      ),
+    )
+  }
+
+  // Presence indicator (constant `enabled` after init, so a one-shot peek is safe).
+  if (opts.collab && opts.collab.peek().enabled) {
+    children.push(presenceIndicator(opts.collab))
+  }
+
+  return div(
+    { ...parts.root, ...(opts['aria-label'] ? { 'aria-label': opts['aria-label'] } : {}) },
+    children,
+  )
+}

package/src/theme.ts

@@ -0,0 +1,42 @@
+// Default Lexical theme for the markdown editor.
+//
+// Lexical styles most inline formats through semantic tags that carry
+// browser-default styling — bold→<strong>, italic→<em>, code→<code>. But
+// `strikethrough` (and `underline`) render as a bare <span> whose ONLY styling
+// hook is a `theme.text.<format>` class. With no theme the format is applied to
+// the model but is visually invisible. This default theme supplies those class
+// names; the bundled `styles/editor.css` gives them their `text-decoration`.
+//
+// Consumers can override any entry via `markdownEditor({ theme })` — the user's
+// theme is merged over this default (see `mergeTheme`).
+
+import type { EditorThemeClasses } from 'lexical'
+
+export const STRIKETHROUGH_CLASS = 'md-strikethrough'
+export const UNDERLINE_CLASS = 'md-underline'
+export const UNDERLINE_STRIKETHROUGH_CLASS = 'md-underline-strikethrough'
+
+/** The class hooks Lexical needs for text-decoration formats it renders as a
+ * plain <span>. (`underlineStrikethrough` is Lexical's special composite key for
+ * the case where both apply — both want `text-decoration`.) */
+export const defaultTheme: EditorThemeClasses = {
+  text: {
+    strikethrough: STRIKETHROUGH_CLASS,
+    underline: UNDERLINE_CLASS,
+    underlineStrikethrough: UNDERLINE_STRIKETHROUGH_CLASS,
+  },
+}
+
+/** Merge a consumer theme over the default. `text` is merged per-key so a
+ * consumer overriding (say) `strikethrough` keeps the default `underline`.
+ *
+ * Always returns a FRESH theme (never the shared `defaultTheme` singleton):
+ * Lexical caches resolved class arrays by MUTATING the `text` object it is
+ * handed (`text.__lexicalClassNameCache`). Handing it a fresh copy keeps the
+ * exported singleton clean, and stripping any inherited cache prevents a stale
+ * entry from a previously-used theme object shadowing an overridden class. */
+export function mergeTheme(theme?: EditorThemeClasses): EditorThemeClasses {
+  const text = { ...defaultTheme.text, ...theme?.text }
+  delete (text as { __lexicalClassNameCache?: unknown }).__lexicalClassNameCache
+  return { ...theme, text }
+}

package/src/transformers/gfm.ts

@@ -0,0 +1,69 @@
+// The built-in GFM superset: node classes + the explicit transformer set that
+// maps exactly to those nodes (no surprise nodes — HR/tables are opt-in plugins).
+
+import type { Klass, LexicalNode } from 'lexical'
+import { HeadingNode, QuoteNode } from '@lexical/rich-text'
+import { ListNode, ListItemNode } from '@lexical/list'
+import { LinkNode } from '@lexical/link'
+// `@lexical/code-core` (not `@lexical/code`) keeps Prism out of the bundle — we
+// never register syntax highlighting, so plain CodeNode is all we need.
+import { CodeNode, CodeHighlightNode } from '@lexical/code-core'
+import {
+  type Transformer,
+  HEADING,
+  QUOTE,
+  UNORDERED_LIST,
+  ORDERED_LIST,
+  CHECK_LIST,
+  CODE,
+  BOLD_ITALIC_STAR,
+  BOLD_ITALIC_UNDERSCORE,
+  BOLD_STAR,
+  BOLD_UNDERSCORE,
+  ITALIC_STAR,
+  ITALIC_UNDERSCORE,
+  STRIKETHROUGH,
+  INLINE_CODE,
+  HIGHLIGHT,
+  LINK,
+} from '@lexical/markdown'
+
+/** Node classes required to render the GFM superset. */
+export const GFM_NODES: ReadonlyArray<Klass<LexicalNode>> = [
+  HeadingNode,
+  QuoteNode,
+  ListNode,
+  ListItemNode,
+  CodeNode,
+  CodeHighlightNode,
+  LinkNode,
+]
+
+/** Inline text-format transformers (no block nodes, no node registration). These
+ * are the only transformers a single-block / inline-only editor needs; `LINK` is
+ * kept separate since it requires `LinkNode` to be registered. */
+export const INLINE_TEXT_TRANSFORMERS: readonly Transformer[] = [
+  BOLD_ITALIC_STAR,
+  BOLD_ITALIC_UNDERSCORE,
+  BOLD_STAR,
+  BOLD_UNDERSCORE,
+  ITALIC_STAR,
+  ITALIC_UNDERSCORE,
+  STRIKETHROUGH,
+  INLINE_CODE,
+  HIGHLIGHT,
+]
+
+/** Markdown ↔ node transformers for the GFM superset. */
+export const GFM_TRANSFORMERS: readonly Transformer[] = [
+  HEADING,
+  QUOTE,
+  // CHECK_LIST must precede the plain list transformers: `- [ ]`/`- [x]` also
+  // match `- `, so UNORDERED_LIST would otherwise swallow it as bullet text.
+  CHECK_LIST,
+  UNORDERED_LIST,
+  ORDERED_LIST,
+  CODE,
+  ...INLINE_TEXT_TRANSFORMERS,
+  LINK,
+]

package/src/transformers/registry.ts

@@ -0,0 +1,47 @@
+// The transformer registry: flatten plugin transformer contributions into a
+// single, correctly-ordered Lexical TRANSFORMERS array. Ordering is the single
+// place markdown round-trip fidelity is governed.
+
+import type { Transformer } from '@lexical/markdown'
+import type { MarkdownPlugin } from '../plugins/types.js'
+
+// Lexical resolves transformers in array order. Element/multiline constructs
+// must be tried before inline text matching, and longer text-format patterns
+// (e.g. `***`) before shorter (`**`, `*`) so they aren't shadowed.
+const TYPE_RANK: Record<string, number> = {
+  'multiline-element': 0,
+  element: 1,
+  'text-format': 2,
+  'text-match': 3,
+}
+
+/** Stable-sort transformers into the order Lexical expects. */
+export function orderTransformers(transformers: readonly Transformer[]): Transformer[] {
+  return [...transformers].sort((a, b) => {
+    const ra = TYPE_RANK[a.type] ?? 9
+    const rb = TYPE_RANK[b.type] ?? 9
+    if (ra !== rb) return ra - rb
+    if (a.type === 'text-format' && b.type === 'text-format') {
+      // Longer trigger (`***`) before shorter (`**`, `*`).
+      return b.tag.length - a.tag.length
+    }
+    return 0
+  })
+}
+
+/** Collect every plugin's transformers (de-duplicated by reference) and order
+ * them. The result is passed to `$convertTo/FromMarkdownString` and
+ * `registerMarkdownShortcuts`. */
+export function buildTransformers(plugins: readonly MarkdownPlugin[]): Transformer[] {
+  const seen = new Set<Transformer>()
+  const collected: Transformer[] = []
+  for (const plugin of plugins) {
+    for (const transformer of plugin.transformers ?? []) {
+      if (!seen.has(transformer)) {
+        seen.add(transformer)
+        collected.push(transformer)
+      }
+    }
+  }
+  return orderTransformers(collected)
+}