@nuasite/cms-mdx-editor 0.43.0-beta.4

package/src/mdx-body-editor.tsx

@@ -0,0 +1,146 @@
+/**
+ * `MdxBodyEditor` — a Milkdown rich-text editor for a collection entry's markdown/
+ * MDX body. Component blocks round-trip via the MDX plugin (`mdx-plugin` + the
+ * React node-view in `mdx-view`); a picker inserts new ones. String in / string
+ * out (`value` / `onChange`) so it drops into any host's save flow.
+ *
+ * Pass `components` (from `cmsClient.getComponents()`) to drive the picker and the
+ * block-card prop labels; without it blocks still render and round-trip, just
+ * without rich labels.
+ */
+import { defaultValueCtx, Editor, rootCtx } from '@milkdown/core'
+import { listener, listenerCtx } from '@milkdown/plugin-listener'
+import { commonmark } from '@milkdown/preset-commonmark'
+import { gfm } from '@milkdown/preset-gfm'
+import { callCommand, replaceAll } from '@milkdown/utils'
+import type { ComponentDefinition } from '@nuasite/cms-types'
+import { useEffect, useRef, useState } from 'react'
+import { ComponentPicker } from './component-picker'
+import { FormatToolbar } from './format-toolbar'
+import type { MediaContext, MediaSource } from './media-source'
+import { insertMdxComponentCommand, mdxComponentNode, mdxEsmNode, remarkMdxPlugin } from './mdx-plugin'
+import { type ComponentResolver, createMdxComponentView } from './mdx-view'
+
+export interface MdxBodyEditorProps {
+	value: string
+	onChange: (markdown: string) => void
+	/** Project component definitions — drives the insert picker and prop labels. */
+	components?: ComponentDefinition[]
+	/**
+	 * Media source (the host's `CmsClient` satisfies it) — enables the toolbar's
+	 * image insert and image-prop browse/upload. Absent → those affordances hide.
+	 */
+	media?: MediaSource
+	/** Upload context (collection/entry) so uploads file against this entry. */
+	mediaContext?: MediaContext
+}
+
+const wrapper: React.CSSProperties = { border: '1px solid #d4d4d8', borderRadius: 6, background: '#fff' }
+const editorHost: React.CSSProperties = { padding: '8px 12px', minHeight: 240, outline: 'none' }
+
+export function MdxBodyEditor({ value, onChange, components, media, mediaContext }: MdxBodyEditorProps) {
+	const hostRef = useRef<HTMLDivElement>(null)
+	const editorRef = useRef<Editor | null>(null)
+	const latest = useRef(value)
+	const ready = useRef(false)
+	const settingExternal = useRef(false)
+	const onChangeRef = useRef(onChange)
+	onChangeRef.current = onChange
+
+	// Component map kept in a ref so the node-view resolver always sees the latest
+	// list even though the editor is created once.
+	const componentMap = useRef<Map<string, ComponentDefinition>>(new Map())
+	useEffect(() => {
+		componentMap.current = new Map((components ?? []).map(c => [c.name, c]))
+	}, [components])
+
+	// Read inside the create-effect via refs so an inline `mediaContext` object from
+	// the host doesn't re-create the editor every render (deps stay `[]`). Both hosts
+	// remount per entry, so the value captured at mount is the right one.
+	const mediaRef = useRef(media)
+	mediaRef.current = media
+	const mediaContextRef = useRef(mediaContext)
+	mediaContextRef.current = mediaContext
+
+	const [pickerOpen, setPickerOpen] = useState(false)
+	// The created editor, surfaced as state so the toolbar (re)attaches once ready.
+	const [editorInstance, setEditorInstance] = useState<Editor | null>(null)
+
+	useEffect(() => {
+		const el = hostRef.current
+		if (!el) return
+		let destroyed = false
+
+		const resolver: ComponentResolver = (name) => componentMap.current.get(name)
+
+		const init = async () => {
+			const editor = await Editor.make()
+				.config((ctx) => {
+					ctx.set(rootCtx, el)
+					ctx.set(defaultValueCtx, latest.current)
+					ctx.get(listenerCtx).markdownUpdated((_, md) => {
+						latest.current = md
+						if (ready.current && !settingExternal.current) onChangeRef.current(md)
+					})
+				})
+				.use(commonmark)
+				.use(gfm)
+				.use(listener)
+				.use(remarkMdxPlugin)
+				.use(mdxEsmNode)
+				.use(mdxComponentNode)
+				.use(createMdxComponentView(resolver, mediaRef.current, mediaContextRef.current))
+				.use(insertMdxComponentCommand)
+				.create()
+
+			if (destroyed) {
+				editor.destroy()
+				return
+			}
+			editorRef.current = editor
+			setEditorInstance(editor)
+			// Ignore the value-set that happens during creation; only user edits emit.
+			queueMicrotask(() => {
+				ready.current = true
+			})
+		}
+		void init()
+
+		return () => {
+			destroyed = true
+			ready.current = false
+			editorRef.current?.destroy()
+			editorRef.current = null
+			setEditorInstance(null)
+		}
+	}, [])
+
+	// Adopt external value changes (e.g. conflict resolution) without clobbering
+	// the user's own edits — when value already equals what we last emitted, skip.
+	useEffect(() => {
+		if (!editorRef.current || !ready.current) return
+		if (value === latest.current) return
+		settingExternal.current = true
+		editorRef.current.action(replaceAll(value))
+		latest.current = value
+		queueMicrotask(() => { settingExternal.current = false })
+	}, [value])
+
+	const insert = (componentName: string, props: Record<string, string>, children?: string) => {
+		editorRef.current?.action(callCommand(insertMdxComponentCommand.key, { componentName, props, children }))
+	}
+
+	return (
+		<div style={wrapper}>
+			<FormatToolbar
+				editor={editorInstance}
+				media={media}
+				mediaContext={mediaContext}
+				field="body"
+				onInsertComponent={() => setPickerOpen(true)}
+			/>
+			<div ref={hostRef} style={editorHost} />
+			<ComponentPicker open={pickerOpen} components={components ?? []} onInsert={insert} onClose={() => setPickerOpen(false)} />
+		</div>
+	)
+}

package/src/mdx-plugin.ts

@@ -0,0 +1,270 @@
+/**
+ * Milkdown plugin that round-trips MDX component blocks through the editor.
+ *
+ * Ported from `@nuasite/cms`'s in-iframe `milkdown-mdx-plugin.tsx` — the parse/
+ * serialize logic operates on the remark-mdx (mdast) AST and is framework-agnostic,
+ * so it moves here verbatim. The only piece that was preact-coupled — the node
+ * `$view` that renders the block-card — lives separately in `mdx-view.tsx` (React)
+ * and is composed into the plugin array by `MdxBodyEditor`.
+ *
+ * The mdast nodes are intentionally typed loosely (`any`): they are the dynamic
+ * remark-mdx AST, the same boundary the original treated as untyped.
+ */
+import type { Node as PmNode, NodeType } from '@milkdown/prose/model'
+import type { Command } from '@milkdown/prose/state'
+import type { MarkdownNode, SerializerState } from '@milkdown/transformer'
+import { $command, $node, $remark } from '@milkdown/utils'
+import remarkMdx from 'remark-mdx'
+import remarkParse from 'remark-parse'
+import { unified } from 'unified'
+
+/** Prefix marking expression attributes (`prop={value}`) vs string literals in serialized props. */
+export const MDX_EXPR_PREFIX = '__mdx_expr__:'
+
+/** HTML void elements that should not be treated as editable MDX components. */
+const HTML_VOID_ELEMENTS = new Set(['br', 'hr', 'img', 'input', 'meta', 'link', 'area', 'base', 'col', 'embed', 'source', 'track', 'wbr'])
+
+/** Cached unified processor for parsing markdown children during serialization. */
+const remarkParser = unified().use(remarkParse)
+
+export const remarkMdxPlugin: any = $remark('remarkMdx', () => remarkMdx)
+
+function parseJsxAttributes(attributes: any[]): { props: Record<string, string>; hasExpressions: boolean } {
+	const props: Record<string, string> = {}
+	let hasExpressions = false
+
+	if (!Array.isArray(attributes)) return { props, hasExpressions }
+
+	for (const attr of attributes) {
+		if (attr.type === 'mdxJsxAttribute' && attr.name) {
+			if (attr.value === null || attr.value === undefined) {
+				// Boolean attribute: <Component flag />
+				props[attr.name] = 'true'
+			} else if (typeof attr.value === 'string') {
+				props[attr.name] = attr.value
+			} else if (attr.value?.type === 'mdxJsxAttributeValueExpression') {
+				// Expression attribute: prop={value}
+				props[attr.name] = `${MDX_EXPR_PREFIX}${attr.value.value}`
+				hasExpressions = true
+			}
+		}
+		if (attr.type === 'mdxJsxExpressionAttribute') {
+			hasExpressions = true
+		}
+	}
+
+	return { props, hasExpressions }
+}
+
+function serializePropsToAttributes(props: Record<string, string>): any[] {
+	const attributes: any[] = []
+
+	for (const [name, value] of Object.entries(props)) {
+		if (value.startsWith(MDX_EXPR_PREFIX)) {
+			attributes.push({
+				type: 'mdxJsxAttribute',
+				name,
+				value: {
+					type: 'mdxJsxAttributeValueExpression',
+					value: value.slice(MDX_EXPR_PREFIX.length),
+				},
+			})
+		} else {
+			attributes.push({
+				type: 'mdxJsxAttribute',
+				name,
+				value,
+			})
+		}
+	}
+
+	return attributes
+}
+
+/** Serialize mdast children back to markdown text. */
+function serializeChildren(children: any[]): string {
+	if (!children || children.length === 0) return ''
+	const parts: string[] = []
+	for (const child of children) {
+		if (child.type === 'paragraph') {
+			const text = serializeInlineChildren(child.children ?? [])
+			parts.push(text)
+		} else if (child.type === 'text') {
+			parts.push(child.value ?? '')
+		} else if (child.type === 'mdxJsxFlowElement' || child.type === 'mdxJsxTextElement') {
+			// Nested JSX — reconstruct as string
+			const name = child.name ?? ''
+			const attrs = (child.attributes ?? [])
+				.map((a: any) => {
+					if (a.type === 'mdxJsxAttribute' && a.name) {
+						if (typeof a.value === 'string') return `${a.name}="${a.value}"`
+						if (a.value?.type === 'mdxJsxAttributeValueExpression') return `${a.name}={${a.value.value}}`
+					}
+					return ''
+				})
+				.filter(Boolean)
+				.join(' ')
+			const inner = serializeChildren(child.children ?? [])
+			if (inner) {
+				parts.push(`<${name}${attrs ? ' ' + attrs : ''}>${inner}</${name}>`)
+			} else {
+				parts.push(`<${name}${attrs ? ' ' + attrs : ''} />`)
+			}
+		} else {
+			// Fallback — use value if present
+			if (child.value) parts.push(child.value)
+		}
+	}
+	return parts.join('\n\n')
+}
+
+function serializeInlineChildren(children: any[]): string {
+	return children.map((c: any) => {
+		if (c.type === 'text') return c.value ?? ''
+		if (c.type === 'strong') return `**${serializeInlineChildren(c.children ?? [])}**`
+		if (c.type === 'emphasis') return `*${serializeInlineChildren(c.children ?? [])}*`
+		if (c.type === 'inlineCode') return `\`${c.value ?? ''}\``
+		if (c.type === 'link') return `[${serializeInlineChildren(c.children ?? [])}](${c.url ?? ''})`
+		return c.value ?? ''
+	}).join('')
+}
+
+export const mdxComponentNode = $node('mdx_component', () => ({
+	group: 'block',
+	atom: true,
+	isolating: true,
+	selectable: true,
+	draggable: false,
+	attrs: {
+		componentName: { default: '' },
+		props: { default: '{}' },
+		hasExpressions: { default: false },
+		children: { default: '' },
+	},
+	toDOM: (node: PmNode) => {
+		const div = document.createElement('div')
+		div.setAttribute('data-mdx-component', node.attrs.componentName)
+		div.setAttribute('data-mdx-props', node.attrs.props)
+		if (node.attrs.children) div.setAttribute('data-mdx-children', node.attrs.children)
+		if (node.attrs.hasExpressions) div.setAttribute('data-mdx-expressions', 'true')
+		div.className = 'mdx-component-block'
+		div.textContent = `<${node.attrs.componentName} />`
+		return div as any
+	},
+	parseDOM: [{
+		tag: 'div[data-mdx-component]',
+		getAttrs: (dom: HTMLElement) => ({
+			componentName: dom.getAttribute('data-mdx-component') || '',
+			props: dom.getAttribute('data-mdx-props') || '{}',
+			children: dom.getAttribute('data-mdx-children') || '',
+			hasExpressions: dom.getAttribute('data-mdx-expressions') === 'true',
+		}),
+	}],
+	parseMarkdown: {
+		match: (node: MarkdownNode) => node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement',
+		runner: (state, node, proseType: NodeType) => {
+			const name = (node as any).name as string | null
+			if (!name) return // Skip fragments
+			// Skip HTML void elements — they are not editable components
+			if (HTML_VOID_ELEMENTS.has(name.toLowerCase())) return
+
+			const { props, hasExpressions } = parseJsxAttributes((node as any).attributes)
+			const children = serializeChildren((node as any).children ?? [])
+
+			state.addNode(proseType, {
+				componentName: name,
+				props: JSON.stringify(props),
+				hasExpressions,
+				children,
+			})
+		},
+	},
+	toMarkdown: {
+		match: (node: PmNode) => node.type.name === 'mdx_component',
+		runner: (state: SerializerState, node: PmNode) => {
+			const componentName = node.attrs.componentName as string
+			const props: Record<string, string> = JSON.parse(node.attrs.props as string)
+			const childrenText = (node.attrs.children as string) || ''
+			const attributes = serializePropsToAttributes(props)
+
+			if (childrenText.trim()) {
+				// Parse children markdown into proper mdast nodes so headings, lists, etc. are preserved
+				const childrenAst = remarkParser.parse(childrenText)
+				state.addNode('mdxJsxFlowElement', undefined, undefined, {
+					name: componentName,
+					attributes,
+					children: childrenAst.children,
+				} as any)
+			} else {
+				state.addNode('mdxJsxFlowElement', undefined, undefined, {
+					name: componentName,
+					attributes,
+					children: [],
+				} as any)
+			}
+		},
+	},
+}))
+
+export interface InsertMdxComponentPayload {
+	componentName: string
+	props: Record<string, string>
+	children?: string
+}
+
+export const insertMdxComponentCommand = $command('insertMdxComponent', () => {
+	return (payload?: InsertMdxComponentPayload): Command => {
+		return (state, dispatch) => {
+			if (!payload) return false
+			const nodeType = state.schema.nodes.mdx_component
+			if (!nodeType) return false
+
+			const node = nodeType.create({
+				componentName: payload.componentName,
+				props: JSON.stringify(payload.props),
+				hasExpressions: false,
+				children: payload.children || '',
+			})
+
+			if (dispatch) {
+				const { from } = state.selection
+				const tr = state.tr.insert(from, node)
+				dispatch(tr)
+			}
+			return true
+		}
+	}
+})
+
+/**
+ * Hidden node that preserves `import ... from '...'` statements through the round-trip.
+ * remark-mdx parses these as `mdxjsEsm` — without a matching ProseMirror node Milkdown throws.
+ */
+export const mdxEsmNode = $node('mdx_esm', () => ({
+	group: 'block',
+	atom: true,
+	attrs: {
+		value: { default: '' },
+	},
+	toDOM: () => {
+		// Render nothing — imports are invisible in the editor
+		const span = document.createElement('span')
+		span.style.display = 'none'
+		return span as any
+	},
+	parseDOM: [],
+	parseMarkdown: {
+		match: (node: MarkdownNode) => node.type === 'mdxjsEsm',
+		runner: (state, node, proseType: NodeType) => {
+			state.addNode(proseType, { value: (node as any).value ?? '' })
+		},
+	},
+	toMarkdown: {
+		match: (node: PmNode) => node.type.name === 'mdx_esm',
+		runner: (state: SerializerState, node: PmNode) => {
+			state.addNode('mdxjsEsm', undefined, undefined, {
+				value: node.attrs.value as string,
+			} as any)
+		},
+	},
+}))

package/src/mdx-view.tsx

@@ -0,0 +1,116 @@
+/**
+ * React node-view for the `mdx_component` node. Replaces the original preact
+ * `render()` view: renders `MdxBlockCard` into the node-view container via a
+ * per-node React root, and writes edits back as ProseMirror node attrs.
+ *
+ * `getComponent` resolves a component's definition (props/slots) for labels and
+ * default-slot detection — supplied by the editor from the `components` prop.
+ */
+import type { Node as PmNode } from '@milkdown/prose/model'
+import { $view } from '@milkdown/utils'
+import type { ComponentDefinition } from '@nuasite/cms-types'
+import { createElement } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { MdxBlockCard } from './mdx-block-card'
+import type { MediaContext, MediaSource } from './media-source'
+import { mdxComponentNode } from './mdx-plugin'
+
+export type ComponentResolver = (name: string) => ComponentDefinition | undefined
+
+export function createMdxComponentView(getComponent: ComponentResolver, media?: MediaSource, mediaContext?: MediaContext) {
+	return $view(mdxComponentNode, () => {
+		return (pmNode, view, getPos) => {
+			const container = document.createElement('div')
+			container.className = 'mdx-block-card-wrapper'
+			container.setAttribute('data-cms-ui', '')
+			container.contentEditable = 'false'
+			const root: Root = createRoot(container)
+
+			let lastAttrs: { componentName: string; props: string; hasExpressions: boolean; children: string } | null = null
+
+			const updateNodeAttrs = (update: Record<string, unknown>) => {
+				const pos = typeof getPos === 'function' ? getPos() : null
+				if (pos == null) return
+				const currentNode = view.state.doc.nodeAt(pos)
+				if (!currentNode) return
+				const tr = view.state.tr.setNodeMarkup(pos, undefined, { ...currentNode.attrs, ...update })
+				view.dispatch(tr)
+			}
+
+			const removeNode = () => {
+				const pos = typeof getPos === 'function' ? getPos() : null
+				if (pos == null) return
+				const currentNode = view.state.doc.nodeAt(pos)
+				if (!currentNode) return
+				view.dispatch(view.state.tr.delete(pos, pos + currentNode.nodeSize))
+			}
+
+			const renderCard = (node: PmNode) => {
+				const componentName = node.attrs.componentName as string
+				const propsJson = node.attrs.props as string
+				const hasExpressions = node.attrs.hasExpressions as boolean
+				const children = (node.attrs.children as string) || ''
+
+				container.setAttribute('data-mdx-component', componentName)
+				container.setAttribute('data-mdx-props', propsJson)
+				container.setAttribute('data-mdx-children', children)
+
+				const props: Record<string, string> = JSON.parse(propsJson)
+				const definition = getComponent(componentName)
+				const hasDefaultSlot = (definition?.slots?.includes('default') ?? false) || children.trim() !== ''
+
+				lastAttrs = { componentName, props: propsJson, hasExpressions, children }
+
+				root.render(createElement(MdxBlockCard, {
+					componentName,
+					props,
+					hasExpressions,
+					slotContent: children,
+					definition,
+					media,
+					mediaContext,
+					onRemove: removeNode,
+					onSlotContentChange: hasDefaultSlot ? (newContent: string) => updateNodeAttrs({ children: newContent }) : undefined,
+					onPropsChange: hasExpressions ? undefined : (newProps: Record<string, string>) => updateNodeAttrs({ props: JSON.stringify(newProps) }),
+				}))
+			}
+
+			renderCard(pmNode)
+
+			return {
+				dom: container,
+				stopEvent: (event: Event) => {
+					const target = event.target as HTMLElement
+					if (target.tagName === 'TEXTAREA' || target.tagName === 'INPUT') return true
+					if (target.isContentEditable || target.closest('[contenteditable]')) return true
+					if (target.closest('[data-mdx-action]')) return true
+					if (event.type === 'mousedown' || event.type === 'click') {
+						if (target.closest('button') || target.closest('[data-mdx-action]')) return true
+					}
+					return false
+				},
+				ignoreMutation: () => true,
+				update: (updatedNode: PmNode) => {
+					if (updatedNode.type.name !== 'mdx_component') return false
+					const attrs = updatedNode.attrs
+					if (
+						lastAttrs
+						&& attrs.componentName === lastAttrs.componentName
+						&& attrs.props === lastAttrs.props
+						&& attrs.hasExpressions === lastAttrs.hasExpressions
+						&& attrs.children === lastAttrs.children
+					) {
+						return true
+					}
+					renderCard(updatedNode)
+					return true
+				},
+				destroy: () => {
+					// Defer unmount out of the ProseMirror dispatch tick (React forbids
+					// unmounting a root while it may still be rendering).
+					queueMicrotask(() => root.unmount())
+				},
+			}
+		}
+	})
+}