@growth-labs/cms 0.5.18 → 0.5.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growth-labs/cms",
-  "version": "0.5.18",
+  "version": "0.5.20",
   "type": "module",
   "bin": {
     "growth-labs-cms-migrations": "./dist/cli/migrations.js"
@@ -15,6 +15,10 @@
       "types": "./dist/schema/index.d.ts",
       "import": "./dist/schema/index.js"
     },
+    "./content": {
+      "types": "./dist/content/index.d.ts",
+      "import": "./dist/content/index.js"
+    },
     "./engine": {
       "types": "./dist/engine/index.d.ts",
       "import": "./dist/engine/index.js"
@@ -60,11 +64,17 @@
   },
   "dependencies": {
     "@tiptap/core": "3.24.0",
+    "@tiptap/extension-collaboration": "3.24.0",
+    "@tiptap/extension-drag-handle": "3.24.0",
     "@tiptap/extension-image": "3.24.0",
     "@tiptap/extension-link": "3.24.0",
+    "@tiptap/extension-node-range": "3.24.0",
     "@tiptap/extension-table": "3.24.0",
     "@tiptap/pm": "3.24.0",
     "@tiptap/starter-kit": "3.24.0",
+    "@tiptap/suggestion": "3.24.0",
+    "@tiptap/y-tiptap": "^3.0.9",
+    "yjs": "^13.6.32",
     "zod": "^3.24.0"
   },
   "devDependencies": {

package/src/content/index.ts

@@ -0,0 +1,16 @@
+// src/content/index.ts
+// Site-side content tooling surface (`@growth-labs/cms/content`): the pure
+// serializer quartet plus the envelope contract, for backfills, gates, and
+// import tooling that must convert between markdown, Tiptap JSON, and
+// Portable Text OUTSIDE the editor. No Editor/EditorView/DOM anywhere on
+// this import path.
+
+export {
+	PORTABLE_TEXT_VERSION,
+	type PortableTextEnvelope,
+	type PortableTextObject,
+	parsePortableTextEnvelope,
+	wrapPortableText,
+} from '../schema/portable-text.js'
+export { docToPortableText, portableTextToDoc } from '../ui/editor/portable-text.js'
+export { docToMarkdown, markdownToDoc } from '../ui/editor/serialize.js'

package/src/schema/portable-text.ts

@@ -19,6 +19,14 @@
 //                  Text arrays so in-cell links are ordinary annotations.
 //                  Cell extension fields: header, colspan, rowspan, colwidth,
 //                  align.
+//   callout        { tone: note|tip|important|warning|caution, content:
+//                  block[] } (@portabletext/markdown callout shape; markdown
+//                  form is a GFM alert)
+//   pullQuote      { attribution: string|null, content: block[] }
+//   generatedFaq   { markdown } — the machine-owned <!-- generated-faq -->
+//                  region as an opaque atom
+//   citation       annotation markDef { _type: 'citation', href } (markdown
+//                  form [[label]](href))
 
 import { z } from 'zod'
 

package/src/ui/editor/Rte.tsx

@@ -57,6 +57,9 @@ type ToolCmd =
 	| 'ordered'
 	| 'link'
 	| 'image'
+	| 'callout'
+	| 'pullquote'
+	| 'citation'
 	| 'table'
 	| 'tableAddRow'
 	| 'tableAddCol'
@@ -82,7 +85,10 @@ const RTE_TOOLS: ToolDef[] = [
 	{ cmd: 'bullet', label: 'Bullet list', icon: 'rows' },
 	{ cmd: 'ordered', label: 'Ordered list', icon: 'rows' },
 	{ cmd: 'link', label: 'Link', icon: 'link' },
+	{ cmd: 'citation', label: 'Citation', icon: 'globe' },
 	{ cmd: 'image', label: 'Image', icon: 'image' },
+	{ cmd: 'callout', label: 'Callout', icon: 'flag' },
+	{ cmd: 'pullquote', label: 'Pull quote', icon: 'star' },
 	{ cmd: 'table', label: 'Insert table', icon: 'grid' },
 ]
 
@@ -344,6 +350,19 @@ function ToolButton({
 				}
 				break
 			}
+			case 'callout':
+				chain.toggleWrap('callout', { tone: 'note' }).run()
+				break
+			case 'pullquote':
+				chain.toggleWrap('pullQuote').run()
+				break
+			case 'citation': {
+				const href = window.prompt('Citation URL')
+				if (href) {
+					chain.toggleMark('citation', { href }).run()
+				}
+				break
+			}
 			case 'table':
 				chain.insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run()
 				break
@@ -389,6 +408,12 @@ function ToolButton({
 				return editor.isActive('bulletList')
 			case 'ordered':
 				return editor.isActive('orderedList')
+			case 'callout':
+				return editor.isActive('callout')
+			case 'pullquote':
+				return editor.isActive('pullQuote')
+			case 'citation':
+				return editor.isActive('citation')
 			case 'table':
 				return editor.isActive('table')
 			default:

package/src/ui/editor/blocks.ts

@@ -0,0 +1,140 @@
+// src/ui/editor/blocks.ts
+// Pure Tiptap specs for the Phase 1 typed blocks. Like tweet-embed.ts these
+// NEVER instantiate Editor/EditorView; the HTML encodings exist for Tiptap's
+// clipboard pipeline. Durable forms live in the serializers:
+//   callout      ↔ PT { tone, content } ↔ GFM alert (> [!NOTE] …)
+//   pullQuote    ↔ PT { attribution, content } ↔ :::pullquote directive
+//   generatedFaq ↔ PT { markdown } ↔ <!-- generated-faq --> comment block
+//   citation     ↔ PT markDef { _type: 'citation', href } ↔ [[label]](href)
+
+import { Mark, mergeAttributes, Node } from '@tiptap/core'
+
+export const CALLOUT_TONES = ['note', 'tip', 'important', 'warning', 'caution'] as const
+export type CalloutTone = (typeof CALLOUT_TONES)[number]
+
+/** Editorial callout: an aside with a tone, rendered as a GFM alert in markdown. */
+export const Callout = Node.create({
+	name: 'callout',
+
+	group: 'block',
+
+	content: 'paragraph+',
+
+	defining: true,
+
+	addAttributes() {
+		return {
+			tone: {
+				default: 'note',
+				parseHTML: (element: HTMLElement) => {
+					const tone = element.getAttribute('data-tone')
+					return tone && (CALLOUT_TONES as readonly string[]).includes(tone) ? tone : 'note'
+				},
+				renderHTML: (attributes: Record<string, unknown>) => ({
+					'data-tone': attributes.tone,
+				}),
+			},
+		}
+	},
+
+	parseHTML() {
+		return [{ tag: 'div[data-callout]' }]
+	},
+
+	renderHTML({ HTMLAttributes }) {
+		return ['div', mergeAttributes(HTMLAttributes, { 'data-callout': '' }), 0]
+	},
+})
+
+/** Pull quote with an optional attribution line. */
+export const PullQuote = Node.create({
+	name: 'pullQuote',
+
+	group: 'block',
+
+	content: 'paragraph+',
+
+	defining: true,
+
+	addAttributes() {
+		return {
+			attribution: {
+				default: null,
+				parseHTML: (element: HTMLElement) => element.getAttribute('data-attribution'),
+				renderHTML: (attributes: Record<string, unknown>) =>
+					attributes.attribution ? { 'data-attribution': attributes.attribution } : {},
+			},
+		}
+	},
+
+	parseHTML() {
+		return [{ tag: 'figure[data-pull-quote]' }]
+	},
+
+	renderHTML({ HTMLAttributes }) {
+		return ['figure', mergeAttributes(HTMLAttributes, { 'data-pull-quote': '' }), 0]
+	},
+})
+
+/**
+ * Generated-FAQ block: an opaque, machine-owned region. The editor shows a
+ * read-only marker; the inner markdown (without the comment markers) rides in
+ * the attrs and re-serializes byte-identically so the FAQ/JSON-LD consumers
+ * of body_markdown never notice the editor round trip.
+ */
+export const GeneratedFaq = Node.create({
+	name: 'generatedFaq',
+
+	group: 'block',
+
+	atom: true,
+
+	addAttributes() {
+		return {
+			markdown: {
+				default: '',
+				parseHTML: (element: HTMLElement) => element.getAttribute('data-markdown') ?? '',
+				renderHTML: (attributes: Record<string, unknown>) => ({
+					'data-markdown': attributes.markdown,
+				}),
+			},
+		}
+	},
+
+	parseHTML() {
+		return [{ tag: 'div[data-generated-faq]' }]
+	},
+
+	renderHTML({ HTMLAttributes }) {
+		return [
+			'div',
+			mergeAttributes(HTMLAttributes, { 'data-generated-faq': '' }),
+			'Generated FAQ block (machine-managed)',
+		]
+	},
+})
+
+/** Citation annotation: a source reference rendered as [[label]](href) in markdown. */
+export const Citation = Mark.create({
+	name: 'citation',
+
+	addAttributes() {
+		return {
+			href: {
+				default: '',
+				parseHTML: (element: HTMLElement) => element.getAttribute('href') ?? '',
+				renderHTML: (attributes: Record<string, unknown>) => ({
+					href: attributes.href,
+				}),
+			},
+		}
+	},
+
+	parseHTML() {
+		return [{ tag: 'a[data-citation]' }]
+	},
+
+	renderHTML({ HTMLAttributes }) {
+		return ['a', mergeAttributes(HTMLAttributes, { 'data-citation': '' }), 0]
+	},
+})

package/src/ui/editor/extensions.ts

@@ -1,10 +1,20 @@
+import { DragHandle } from '@tiptap/extension-drag-handle'
 import Image from '@tiptap/extension-image'
 import Link from '@tiptap/extension-link'
 import { TableKit } from '@tiptap/extension-table'
 import StarterKit from '@tiptap/starter-kit'
+import { Callout, Citation, GeneratedFaq, PullQuote } from './blocks.js'
+import { SlashMenu } from './slash-menu.js'
 import { TrimBoundaryMarks } from './trim-boundary-marks.js'
 import { TweetEmbed } from './tweet-embed.js'
 
+function renderDragHandle(): HTMLElement {
+	const handle = document.createElement('div')
+	handle.className = 'drag-handle'
+	handle.textContent = '⋮⋮'
+	return handle
+}
+
 /** The single extension set used by Masthead and its behavioral editor tests.
  *
  * Underline is deliberately ABSENT. It has no markdown form — the serializer
@@ -23,5 +33,15 @@ export function createRteExtensions() {
 		// One consolidated package registers table/tableRow/tableHeader/tableCell.
 		// Gapcursor (via StarterKit) lets the caret sit before/after a table.
 		TableKit.configure({ table: { resizable: true } }),
+		Callout,
+		PullQuote,
+		GeneratedFaq,
+		Citation,
+		SlashMenu,
+		// DragHandle constructs its handle element (render()) during plugin
+		// setup, not lazily — browser-only, unlike every other extension here.
+		...(typeof document !== 'undefined'
+			? [DragHandle.configure({ render: renderDragHandle })]
+			: []),
 	]
 }

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

@@ -124,6 +124,29 @@ function serializeBlockNode(
 		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 ?? []
@@ -207,6 +230,10 @@ function buildTextBlock(
 			}
 			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.
@@ -260,6 +287,19 @@ function linkMarkDefKey(
 	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
@@ -396,6 +436,23 @@ function parseObject(block: PortableTextObject): JSONContent {
 			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`,
@@ -475,8 +532,10 @@ function parseSpan(span: PortableTextObject, markDefs: MarkDef[]): JSONContent[]
 						target: (def.target as string | null) ?? null,
 					},
 				})
+			} else if (def._type === 'citation') {
+				marks.push({ type: 'citation', attrs: { href: (def.href as string) ?? '' } })
 			}
-			// Unknown annotation types have no Tiptap node yet; drop the mark but
+			// Other annotation types have no Tiptap node yet; drop the mark but
 			// keep the text.
 			continue
 		}

package/src/ui/editor/serialize.ts

@@ -22,6 +22,11 @@
 //   | GFM | pipe | tables | (header row + `| --- |` separator; `\|` escapes a
 //   literal pipe; colspan/rowspan/colwidth/align do NOT survive markdown —
 //   Portable Text is the durable store, markdown is the derived lossy view)
+//   > [!NOTE] GFM alert = callout (tones NOTE/TIP/IMPORTANT/WARNING/CAUTION)
+//   :::pullquote\n<text>\n[-- attribution]\n::: pull-quote directive
+//   [[label]](href) citation annotation
+//   <!-- generated-faq -->…<!-- /generated-faq --> opaque machine-owned atom
+//   (inner markdown re-serializes byte-identically)
 
 import type { JSONContent } from '@tiptap/core'
 import { normalizeBoundaryMarks } from './trim-boundary-marks.js'
@@ -101,6 +106,30 @@ function serializeBlock(node: JSONContent): string | null {
 		case 'table': {
 			return serializeTableMarkdown(node)
 		}
+		case 'callout': {
+			const tone = ((node.attrs?.tone as string) ?? 'note').toUpperCase()
+			const inner = (node.content ?? [])
+				.map((child) => serializeBlock(child))
+				.filter((s) => s !== null)
+				.join('\n\n')
+			const quoted = inner
+				.split('\n')
+				.map((line) => (line === '' ? '>' : `> ${line}`))
+				.join('\n')
+			return `> [!${tone}]\n${quoted}`
+		}
+		case 'pullQuote': {
+			const inner = (node.content ?? [])
+				.map((child) => serializeBlock(child))
+				.filter((s) => s !== null)
+				.join('\n\n')
+			const attribution = node.attrs?.attribution ? `\n-- ${node.attrs.attribution as string}` : ''
+			return `:::pullquote\n${inner}${attribution}\n:::`
+		}
+		case 'generatedFaq': {
+			const inner = (node.attrs?.markdown as string) ?? ''
+			return `<!-- generated-faq -->\n${inner}\n<!-- /generated-faq -->`
+		}
 		default: {
 			// Fall back to serializing any text content
 			const fallback = serializeInlineContent(node.content ?? [])
@@ -203,6 +232,7 @@ function serializeInlineNode(node: JSONContent): string {
 	const hasItalic = marks.some((m) => m.type === 'italic')
 	const hasStrike = marks.some((m) => m.type === 'strike')
 	const linkMark = marks.find((m) => m.type === 'link')
+	const citationMark = marks.find((m) => m.type === 'citation')
 
 	if (hasCode) return `\`${result}\``
 
@@ -214,7 +244,10 @@ function serializeInlineNode(node: JSONContent): string {
 	// Word paste underlined whole runs.
 	if (hasStrike) result = `~~${result}~~`
 
-	if (linkMark) {
+	if (citationMark) {
+		const href = (citationMark.attrs?.href as string) ?? ''
+		result = `[[${result}]](${href})`
+	} else if (linkMark) {
 		const href = (linkMark.attrs?.href as string) ?? ''
 		const title = linkMark.attrs?.title ? ` "${linkMark.attrs.title as string}"` : ''
 		result = `[${result}](${href}${title})`
@@ -272,6 +305,45 @@ function parseBlocks(md: string): JSONContent[] {
 			continue
 		}
 
+		// Generated-FAQ block — the comment-delimited region becomes one atom
+		// that re-serializes byte-identically (the markers stay authoritative
+		// for every body_markdown consumer).
+		if (line.trim() === '<!-- generated-faq -->') {
+			const inner: string[] = []
+			i++
+			while (i < lines.length && lines[i].trim() !== '<!-- /generated-faq -->') {
+				inner.push(lines[i])
+				i++
+			}
+			i++ // consume the closing marker
+			nodes.push({ type: 'generatedFaq', attrs: { markdown: inner.join('\n') } })
+			continue
+		}
+
+		// Pull-quote directive :::pullquote (optional trailing `-- attribution`)
+		if (/^:::pullquote/.test(line)) {
+			i++
+			const inner: string[] = []
+			while (i < lines.length && lines[i].trim() !== ':::') {
+				inner.push(lines[i])
+				i++
+			}
+			i++ // consume :::
+			let attribution: string | null = null
+			const last = inner[inner.length - 1]
+			if (last?.startsWith('-- ')) {
+				attribution = last.slice(3)
+				inner.pop()
+			}
+			const content = parseBlocks(inner.join('\n'))
+			nodes.push({
+				type: 'pullQuote',
+				attrs: { attribution },
+				content: content.length ? content : [{ type: 'paragraph', content: [] }],
+			})
+			continue
+		}
+
 		// Tweet-embed directive :::tweet
 		if (/^:::tweet/.test(line)) {
 			i++
@@ -286,13 +358,26 @@ function parseBlocks(md: string): JSONContent[] {
 			continue
 		}
 
-		// Blockquote — collect contiguous > lines
+		// Blockquote — collect contiguous > lines. A `[!TONE]` first line is a
+		// GFM alert and parses as a callout instead.
 		if (/^>/.test(line)) {
 			const bqLines: string[] = []
 			while (i < lines.length && /^>/.test(lines[i])) {
 				bqLines.push(lines[i].replace(/^>\s?/, ''))
 				i++
 			}
+			const alertMatch = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]$/.exec(
+				bqLines[0]?.trim() ?? '',
+			)
+			if (alertMatch) {
+				const inner = parseBlocks(bqLines.slice(1).join('\n'))
+				nodes.push({
+					type: 'callout',
+					attrs: { tone: alertMatch[1].toLowerCase() },
+					content: inner.length ? inner : [{ type: 'paragraph', content: [] }],
+				})
+				continue
+			}
 			const inner = parseBlocks(bqLines.join('\n'))
 			nodes.push({
 				type: 'blockquote',
@@ -364,6 +449,7 @@ function parseBlocks(md: string): JSONContent[] {
 			!/^[-*+]\s/.test(lines[i]) &&
 			!/^\d+\.\s/.test(lines[i]) &&
 			!/^---+$/.test(lines[i].trim()) &&
+			lines[i].trim() !== '<!-- generated-faq -->' &&
 			!isTableStart(lines, i)
 		) {
 			paraLines.push(lines[i])
@@ -502,6 +588,18 @@ function parseInline(text: string): JSONContent[] {
 			continue
 		}
 
+		// ── citation ([[label]](href)) — must run before the link matcher ──
+		const citationMatch = /^\[\[([^\]]+)\]\]\(([^)]+)\)/.exec(remaining)
+		if (citationMatch) {
+			const inner = parseInline(citationMatch[1]).map((n) => ({
+				...n,
+				marks: [...(n.marks ?? []), { type: 'citation', attrs: { href: citationMatch[2] } }],
+			}))
+			nodes.push(...inner)
+			remaining = remaining.slice(citationMatch[0].length)
+			continue
+		}
+
 		// ── link ───────────────────────────────────────────────────────────
 		const linkMatch = /^\[([^\]]+)\]\(([^)]+)\)/.exec(remaining)
 		if (linkMatch) {