@growth-labs/cms 0.5.17 → 0.5.19

package/src/ui/editor/portable-text.ts

@@ -0,0 +1,582 @@
+// src/ui/editor/portable-text.ts
+// PURE Tiptap doc↔Portable Text serializer pair.
+// Operates exclusively on the ProseMirror JSONContent shape — no Editor,
+// no EditorView, no DOM, fully testable in vitest (Node env).
+//
+// Portable Text is the durable store (schema/portable-text.ts documents the
+// version 1 vocabulary); markdown stays a derived view produced by
+// serialize.ts from the same Tiptap doc. Both serializers here are total over
+// the editor's node set — an unknown node degrades to its text content on the
+// way out, and an unknown `_type` throws on the way in so a vocabulary drift
+// fails loudly instead of silently dropping content.
+//
+// Mark mapping (Tiptap ↔ Portable Text):
+//   bold ↔ strong, italic ↔ em, strike ↔ strike-through, code ↔ code,
+//   link ↔ markDef annotation { _type: 'link', href, title?, target? }
+// Lists are stored FLAT (listItem + level per block) per the Portable Text
+// convention; nesting is reconstructed on load. Hard breaks are stored as
+// newlines inside span text.
+
+import type { JSONContent } from '@tiptap/core'
+import type { PortableTextObject } from '../../schema/portable-text.js'
+import { normalizeBoundaryMarks } from './trim-boundary-marks.js'
+
+type KeyGenerator = () => string
+
+/** Deterministic 12-hex key sequence: identical docs serialize identically. */
+function createKeyGenerator(): KeyGenerator {
+	let n = 0
+	return () => {
+		n += 1
+		return n.toString(16).padStart(12, '0')
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// docToPortableText — JSONContent → PortableTextObject[]
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DECORATOR_BY_TIPTAP_MARK: Record<string, string> = {
+	bold: 'strong',
+	italic: 'em',
+	strike: 'strike-through',
+	code: 'code',
+}
+
+interface MarkDef {
+	_key: string
+	_type: string
+	[key: string]: unknown
+}
+
+/** Serialise a Tiptap JSONContent document to a Portable Text array. */
+export function docToPortableText(doc: JSONContent): PortableTextObject[] {
+	const normalized = normalizeBoundaryMarks(doc)
+	const nextKey = createKeyGenerator()
+	return serializeBlocks(normalized.content ?? [], nextKey)
+}
+
+function serializeBlocks(nodes: JSONContent[], nextKey: KeyGenerator): PortableTextObject[] {
+	const out: PortableTextObject[] = []
+	for (const node of nodes) serializeBlockNode(node, out, nextKey, null)
+	return out
+}
+
+interface ListContext {
+	kind: 'bullet' | 'number'
+	level: number
+}
+
+function serializeBlockNode(
+	node: JSONContent,
+	out: PortableTextObject[],
+	nextKey: KeyGenerator,
+	list: ListContext | null,
+): void {
+	switch (node.type ?? 'paragraph') {
+		case 'paragraph':
+			out.push(buildTextBlock('normal', node.content ?? [], nextKey, list))
+			return
+		case 'heading': {
+			const level = (node.attrs?.level as number) ?? 2
+			out.push(buildTextBlock(`h${level}`, node.content ?? [], nextKey, list))
+			return
+		}
+		case 'blockquote': {
+			for (const child of node.content ?? []) {
+				if (child.type === 'paragraph') {
+					out.push(buildTextBlock('blockquote', child.content ?? [], nextKey, list))
+				} else {
+					serializeBlockNode(child, out, nextKey, list)
+				}
+			}
+			return
+		}
+		case 'bulletList':
+			serializeList(node, out, nextKey, 'bullet', list ? list.level + 1 : 1)
+			return
+		case 'orderedList':
+			serializeList(node, out, nextKey, 'number', list ? list.level + 1 : 1)
+			return
+		case 'codeBlock': {
+			const code = (node.content ?? []).map((child) => child.text ?? '').join('')
+			out.push({
+				_type: 'code',
+				_key: nextKey(),
+				language: (node.attrs?.language as string | null) ?? null,
+				code,
+			})
+			return
+		}
+		case 'image':
+			out.push(imageObject(node, nextKey))
+			return
+		case 'tweetEmbed':
+			out.push({
+				_type: 'tweetEmbed',
+				_key: nextKey(),
+				url: (node.attrs?.url as string) ?? '',
+			})
+			return
+		case 'horizontalRule':
+			out.push({ _type: 'horizontalRule', _key: nextKey() })
+			return
+		case 'table':
+			out.push(serializeTable(node, nextKey))
+			return
+		case 'callout':
+			out.push({
+				_type: 'callout',
+				_key: nextKey(),
+				tone: (node.attrs?.tone as string) ?? 'note',
+				content: serializeBlocks(node.content ?? [], nextKey),
+			})
+			return
+		case 'pullQuote':
+			out.push({
+				_type: 'pullQuote',
+				_key: nextKey(),
+				attribution: (node.attrs?.attribution as string | null) ?? null,
+				content: serializeBlocks(node.content ?? [], nextKey),
+			})
+			return
+		case 'generatedFaq':
+			out.push({
+				_type: 'generatedFaq',
+				_key: nextKey(),
+				markdown: (node.attrs?.markdown as string) ?? '',
+			})
+			return
+		default: {
+			// Unknown block: keep its text content rather than dropping it.
+			const inline = node.content ?? []
+			if (inline.length > 0) out.push(buildTextBlock('normal', inline, nextKey, list))
+		}
+	}
+}
+
+function serializeList(
+	node: JSONContent,
+	out: PortableTextObject[],
+	nextKey: KeyGenerator,
+	kind: 'bullet' | 'number',
+	level: number,
+): void {
+	for (const item of node.content ?? []) {
+		for (const child of item.content ?? []) {
+			if (child.type === 'paragraph') {
+				out.push(buildTextBlock('normal', child.content ?? [], nextKey, { kind, level }))
+			} else if (child.type === 'bulletList') {
+				serializeList(child, out, nextKey, 'bullet', level + 1)
+			} else if (child.type === 'orderedList') {
+				serializeList(child, out, nextKey, 'number', level + 1)
+			} else {
+				serializeBlockNode(child, out, nextKey, { kind, level })
+			}
+		}
+	}
+}
+
+function imageObject(node: JSONContent, nextKey: KeyGenerator): PortableTextObject {
+	return {
+		_type: 'image',
+		_key: nextKey(),
+		src: (node.attrs?.src as string) ?? '',
+		alt: (node.attrs?.alt as string | null) ?? '',
+		title: (node.attrs?.title as string | null) ?? null,
+	}
+}
+
+function buildTextBlock(
+	style: string,
+	inline: JSONContent[],
+	nextKey: KeyGenerator,
+	list: ListContext | null,
+): PortableTextObject {
+	const markDefs: MarkDef[] = []
+	type PendingSpan = { marks: string[]; text: string }
+	const pending: Array<PendingSpan | PortableTextObject> = []
+
+	const pushText = (text: string, marks: string[]) => {
+		const previous = pending[pending.length - 1]
+		if (
+			previous &&
+			!('_type' in previous) &&
+			JSON.stringify(previous.marks) === JSON.stringify(marks)
+		) {
+			previous.text += text
+		} else {
+			pending.push({ marks, text })
+		}
+	}
+
+	for (const node of inline) {
+		if (node.type === 'hardBreak') {
+			pushText('\n', [])
+			continue
+		}
+		if (node.type === 'image') {
+			pending.push(imageObject(node, nextKey))
+			continue
+		}
+		const text = node.text ?? ''
+		if (text === '' && (node.marks ?? []).length === 0 && node.type !== 'text') continue
+		const marks: string[] = []
+		for (const mark of node.marks ?? []) {
+			const decorator = DECORATOR_BY_TIPTAP_MARK[mark.type ?? '']
+			if (decorator) {
+				marks.push(decorator)
+				continue
+			}
+			if (mark.type === 'link') {
+				marks.push(linkMarkDefKey(mark, markDefs, nextKey))
+				continue
+			}
+			if (mark.type === 'citation') {
+				marks.push(citationMarkDefKey(mark, markDefs, nextKey))
+			}
+			// Marks without a Portable Text form (legacy underline) are dropped,
+			// matching the markdown serializer.
+		}
+		pushText(text, marks)
+	}
+
+	const children: PortableTextObject[] = pending.map((entry) =>
+		'_type' in entry
+			? entry
+			: { _type: 'span', _key: nextKey(), text: entry.text, marks: entry.marks },
+	)
+	if (children.length === 0) {
+		children.push({ _type: 'span', _key: nextKey(), text: '', marks: [] })
+	}
+
+	const block: PortableTextObject = {
+		_type: 'block',
+		_key: nextKey(),
+		style,
+		markDefs,
+		children,
+	}
+	if (list) {
+		block.listItem = list.kind
+		block.level = list.level
+	}
+	return block
+}
+
+function linkMarkDefKey(
+	mark: NonNullable<JSONContent['marks']>[number],
+	markDefs: MarkDef[],
+	nextKey: KeyGenerator,
+): string {
+	const href = (mark.attrs?.href as string) ?? ''
+	const title = (mark.attrs?.title as string | null) ?? null
+	const target = (mark.attrs?.target as string | null) ?? null
+	const existing = markDefs.find(
+		(def) =>
+			def._type === 'link' &&
+			def.href === href &&
+			(def.title ?? null) === title &&
+			(def.target ?? null) === target,
+	)
+	if (existing) return existing._key
+	const def: MarkDef = { _key: nextKey(), _type: 'link', href }
+	if (title !== null) def.title = title
+	if (target !== null) def.target = target
+	markDefs.push(def)
+	return def._key
+}
+
+function citationMarkDefKey(
+	mark: NonNullable<JSONContent['marks']>[number],
+	markDefs: MarkDef[],
+	nextKey: KeyGenerator,
+): string {
+	const href = (mark.attrs?.href as string) ?? ''
+	const existing = markDefs.find((def) => def._type === 'citation' && def.href === href)
+	if (existing) return existing._key
+	const def: MarkDef = { _key: nextKey(), _type: 'citation', href }
+	markDefs.push(def)
+	return def._key
+}
+
+function serializeTable(node: JSONContent, nextKey: KeyGenerator): PortableTextObject {
+	const rows = (node.content ?? []).filter((row) => row.type === 'tableRow')
+	let headerRows = 0
+	for (const row of rows) {
+		const cells = row.content ?? []
+		if (cells.length > 0 && cells.every((cell) => cell.type === 'tableHeader')) headerRows += 1
+		else break
+	}
+	return {
+		_type: 'table',
+		_key: nextKey(),
+		headerRows,
+		rows: rows.map((row, rowIndex) => ({
+			_type: 'row',
+			_key: nextKey(),
+			cells: (row.content ?? []).map((cell) =>
+				serializeTableCell(cell, rowIndex, headerRows, nextKey),
+			),
+		})),
+	}
+}
+
+function serializeTableCell(
+	cell: JSONContent,
+	rowIndex: number,
+	headerRows: number,
+	nextKey: KeyGenerator,
+): PortableTextObject {
+	const out: PortableTextObject = {
+		_type: 'cell',
+		_key: nextKey(),
+		value: serializeBlocks(cell.content ?? [], nextKey),
+	}
+	if (cell.type === 'tableHeader' && rowIndex >= headerRows) out.header = true
+	const colspan = (cell.attrs?.colspan as number) ?? 1
+	const rowspan = (cell.attrs?.rowspan as number) ?? 1
+	const colwidth = (cell.attrs?.colwidth as number[] | null) ?? null
+	const align = (cell.attrs?.align as string | null) ?? null
+	if (colspan !== 1) out.colspan = colspan
+	if (rowspan !== 1) out.rowspan = rowspan
+	if (colwidth !== null) out.colwidth = colwidth
+	if (align !== null) out.align = align
+	return out
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// portableTextToDoc — PortableTextObject[] → JSONContent
+// ─────────────────────────────────────────────────────────────────────────────
+
+const TIPTAP_MARK_BY_DECORATOR: Record<string, string> = {
+	strong: 'bold',
+	em: 'italic',
+	'strike-through': 'strike',
+	code: 'code',
+}
+
+/** Parse a Portable Text array back into a Tiptap JSONContent document. */
+export function portableTextToDoc(blocks: PortableTextObject[]): JSONContent {
+	return { type: 'doc', content: parseBlocks(blocks) }
+}
+
+function parseBlocks(blocks: PortableTextObject[]): JSONContent[] {
+	const out: JSONContent[] = []
+	let index = 0
+	while (index < blocks.length) {
+		const block = blocks[index]
+		if (block._type === 'block' && typeof block.listItem === 'string') {
+			const run: PortableTextObject[] = []
+			while (
+				index < blocks.length &&
+				blocks[index]._type === 'block' &&
+				typeof blocks[index].listItem === 'string'
+			) {
+				run.push(blocks[index])
+				index += 1
+			}
+			out.push(...buildListNodes(run))
+			continue
+		}
+		if (block._type === 'block' && block.style === 'blockquote') {
+			const paragraphs: JSONContent[] = []
+			while (
+				index < blocks.length &&
+				blocks[index]._type === 'block' &&
+				blocks[index].style === 'blockquote' &&
+				typeof blocks[index].listItem !== 'string'
+			) {
+				paragraphs.push({ type: 'paragraph', content: parseInline(blocks[index]) })
+				index += 1
+			}
+			out.push({ type: 'blockquote', content: paragraphs })
+			continue
+		}
+		out.push(parseObject(block))
+		index += 1
+	}
+	return out
+}
+
+function parseObject(block: PortableTextObject): JSONContent {
+	switch (block._type) {
+		case 'block': {
+			const style = (block.style as string) ?? 'normal'
+			const heading = /^h([1-6])$/.exec(style)
+			if (heading) {
+				return {
+					type: 'heading',
+					attrs: { level: Number(heading[1]) },
+					content: parseInline(block),
+				}
+			}
+			return { type: 'paragraph', content: parseInline(block) }
+		}
+		case 'code': {
+			const code = (block.code as string) ?? ''
+			return {
+				type: 'codeBlock',
+				attrs: { language: (block.language as string | null) ?? null },
+				content: code ? [{ type: 'text', text: code }] : [],
+			}
+		}
+		case 'image':
+			return {
+				type: 'image',
+				attrs: {
+					src: (block.src as string) ?? '',
+					alt: (block.alt as string | null) ?? '',
+					title: (block.title as string | null) ?? null,
+				},
+			}
+		case 'tweetEmbed':
+			return { type: 'tweetEmbed', attrs: { url: (block.url as string) ?? '' } }
+		case 'horizontalRule':
+			return { type: 'horizontalRule' }
+		case 'table':
+			return parseTable(block)
+		case 'callout':
+			return {
+				type: 'callout',
+				attrs: { tone: (block.tone as string) ?? 'note' },
+				content: parseBlocks((block.content as PortableTextObject[] | undefined) ?? []),
+			}
+		case 'pullQuote':
+			return {
+				type: 'pullQuote',
+				attrs: { attribution: (block.attribution as string | null) ?? null },
+				content: parseBlocks((block.content as PortableTextObject[] | undefined) ?? []),
+			}
+		case 'generatedFaq':
+			return {
+				type: 'generatedFaq',
+				attrs: { markdown: (block.markdown as string) ?? '' },
+			}
+		default:
+			throw new Error(
+				`portableTextToDoc: unknown Portable Text _type "${block._type}" — the stored content is newer than this serializer`,
+			)
+	}
+}
+
+function buildListNodes(run: PortableTextObject[]): JSONContent[] {
+	const roots: JSONContent[] = []
+	type StackEntry = { list: JSONContent; kind: string; level: number }
+	const stack: StackEntry[] = []
+
+	for (const block of run) {
+		const kind = block.listItem === 'number' ? 'number' : 'bullet'
+		const level = typeof block.level === 'number' && block.level > 0 ? block.level : 1
+		const listType = kind === 'number' ? 'orderedList' : 'bulletList'
+
+		while (stack.length > 0 && stack[stack.length - 1].level > level) stack.pop()
+		let top = stack[stack.length - 1]
+		if (top && top.level === level && top.kind !== kind) {
+			stack.pop()
+			top = stack[stack.length - 1]
+		}
+
+		if (!top || top.level < level) {
+			const list: JSONContent = { type: listType, content: [] }
+			if (top && top.level < level) {
+				const items = top.list.content ?? []
+				const lastItem = items[items.length - 1]
+				if (lastItem) {
+					lastItem.content = [...(lastItem.content ?? []), list]
+				} else {
+					roots.push(list)
+				}
+			} else {
+				roots.push(list)
+			}
+			stack.push({ list, kind, level })
+			top = stack[stack.length - 1]
+		}
+
+		top.list.content = [
+			...(top.list.content ?? []),
+			{ type: 'listItem', content: [{ type: 'paragraph', content: parseInline(block) }] },
+		]
+	}
+
+	return roots
+}
+
+function parseInline(block: PortableTextObject): JSONContent[] {
+	const markDefs = (block.markDefs as MarkDef[] | undefined) ?? []
+	const out: JSONContent[] = []
+	for (const child of (block.children as PortableTextObject[] | undefined) ?? []) {
+		if (child._type === 'span') {
+			out.push(...parseSpan(child, markDefs))
+		} else if (child._type === 'image') {
+			out.push(parseObject(child))
+		} else {
+			throw new Error(`portableTextToDoc: unknown inline Portable Text _type "${child._type}"`)
+		}
+	}
+	return out
+}
+
+function parseSpan(span: PortableTextObject, markDefs: MarkDef[]): JSONContent[] {
+	const marks: NonNullable<JSONContent['marks']> = []
+	for (const name of (span.marks as string[] | undefined) ?? []) {
+		const def = markDefs.find((candidate) => candidate._key === name)
+		if (def) {
+			if (def._type === 'link') {
+				marks.push({
+					type: 'link',
+					attrs: {
+						href: (def.href as string) ?? '',
+						title: (def.title as string | null) ?? null,
+						target: (def.target as string | null) ?? null,
+					},
+				})
+			} else if (def._type === 'citation') {
+				marks.push({ type: 'citation', attrs: { href: (def.href as string) ?? '' } })
+			}
+			// Other annotation types have no Tiptap node yet; drop the mark but
+			// keep the text.
+			continue
+		}
+		const tiptapMark = TIPTAP_MARK_BY_DECORATOR[name]
+		if (tiptapMark) marks.push({ type: tiptapMark })
+	}
+
+	const text = (span.text as string) ?? ''
+	const segments = text.split('\n')
+	const out: JSONContent[] = []
+	segments.forEach((segment, index) => {
+		if (index > 0) out.push({ type: 'hardBreak' })
+		if (segment !== '') {
+			const node: JSONContent = { type: 'text', text: segment }
+			if (marks.length > 0) node.marks = marks.map((mark) => ({ ...mark }))
+			out.push(node)
+		}
+	})
+	return out
+}
+
+function parseTable(block: PortableTextObject): JSONContent {
+	const headerRows = typeof block.headerRows === 'number' ? block.headerRows : 0
+	const rows = (block.rows as PortableTextObject[] | undefined) ?? []
+	return {
+		type: 'table',
+		content: rows.map((row, rowIndex) => ({
+			type: 'tableRow',
+			content: ((row.cells as PortableTextObject[] | undefined) ?? []).map((cell) => {
+				const isHeader = rowIndex < headerRows || cell.header === true
+				return {
+					type: isHeader ? 'tableHeader' : 'tableCell',
+					attrs: {
+						colspan: (cell.colspan as number) ?? 1,
+						rowspan: (cell.rowspan as number) ?? 1,
+						colwidth: (cell.colwidth as number[] | null) ?? null,
+						align: (cell.align as string | null) ?? null,
+					},
+					content: parseBlocks((cell.value as PortableTextObject[] | undefined) ?? []),
+				}
+			}),
+		})),
+	}
+}