@growth-labs/cms 0.5.16 → 0.5.18

package/src/schema/portable-text.ts

@@ -0,0 +1,110 @@
+// src/schema/portable-text.ts
+// The Portable Text durable-store contract: envelope shape, schema version,
+// and the boundary validator. The envelope — `{ version, content }` — is what
+// `article_content.body_portable_text` holds as JSON text. Consumers (routes,
+// site renderers) parse through here so malformed payloads fail loudly at the
+// boundary instead of corrupting a render.
+//
+// Version 1 vocabulary (custom `_type`s follow the @portabletext/markdown
+// canonical shapes so ecosystem tooling understands them):
+//   block          standard Portable Text block (style, children, markDefs,
+//                  listItem, level; decorators strong/em/code/strike-through;
+//                  link annotations via markDefs)
+//   image          { src, alt, title }
+//   code           { language, code }
+//   tweetEmbed     { url }
+//   horizontalRule {}
+//   table          { headerRows, rows: [{ _type: 'row', cells: [{ _type:
+//                  'cell', value: block[] }] }] } — cells hold full Portable
+//                  Text arrays so in-cell links are ordinary annotations.
+//                  Cell extension fields: header, colspan, rowspan, colwidth,
+//                  align.
+
+import { z } from 'zod'
+
+export const PORTABLE_TEXT_VERSION = 1
+
+/** Any Portable Text object: a typed object, optionally keyed. */
+export interface PortableTextObject {
+	_type: string
+	_key?: string
+	[key: string]: unknown
+}
+
+export interface PortableTextEnvelope {
+	version: typeof PORTABLE_TEXT_VERSION
+	content: PortableTextObject[]
+}
+
+const typedObjectSchema = z
+	.object({
+		_type: z.string().min(1),
+		_key: z.string().optional(),
+	})
+	.passthrough()
+	.superRefine((obj, ctx) => {
+		const record = obj as Record<string, unknown>
+		const children = record.children
+		if (children !== undefined) {
+			if (
+				!Array.isArray(children) ||
+				children.some(
+					(child) =>
+						child === null ||
+						typeof child !== 'object' ||
+						typeof (child as Record<string, unknown>)._type !== 'string',
+				)
+			) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: 'children must be an array of _type-bearing objects',
+				})
+			}
+		}
+		const markDefs = record.markDefs
+		if (markDefs !== undefined) {
+			if (
+				!Array.isArray(markDefs) ||
+				markDefs.some(
+					(def) =>
+						def === null ||
+						typeof def !== 'object' ||
+						typeof (def as Record<string, unknown>)._type !== 'string' ||
+						typeof (def as Record<string, unknown>)._key !== 'string',
+				)
+			) {
+				ctx.addIssue({
+					code: z.ZodIssueCode.custom,
+					message: 'markDefs must be an array of objects with _type and _key',
+				})
+			}
+		}
+	})
+
+export const portableTextEnvelopeSchema = z.object({
+	version: z.literal(PORTABLE_TEXT_VERSION),
+	content: z.array(typedObjectSchema),
+})
+
+/** Wrap serialized blocks in the versioned storage envelope. */
+export function wrapPortableText(content: PortableTextObject[]): PortableTextEnvelope {
+	return { version: PORTABLE_TEXT_VERSION, content }
+}
+
+/**
+ * Parse the stored JSON text into a validated envelope. Returns null for
+ * anything malformed — absent value, bad JSON, wrong shape, unknown version —
+ * so callers fall back to the markdown path instead of rendering garbage.
+ */
+export function parsePortableTextEnvelope(raw: unknown): PortableTextEnvelope | null {
+	if (typeof raw !== 'string' || raw === '') return null
+	let decoded: unknown
+	try {
+		decoded = JSON.parse(raw)
+	} catch {
+		return null
+	}
+	const parsed = portableTextEnvelopeSchema.safeParse(decoded)
+	if (!parsed.success) return null
+	return parsed.data as PortableTextEnvelope
+}

package/src/schema/types.ts

@@ -91,6 +91,8 @@ export interface ArticleContentRow {
 	content_id: string
 	body_markdown: string
 	body_html: string | null
+	/** Portable Text envelope JSON (migration 0024); NULL → render markdown. */
+	body_portable_text: string | null
 	word_count: number | null
 	read_time_minutes: number | null
 	subtitle: string | null

package/src/ui/editor/ContentForm.tsx

@@ -109,6 +109,7 @@ interface ExistingContentItem {
 interface ExistingContentPayload {
 	body_markdown?: string | null
 	body_html?: string | null
+	body_portable_text?: string | null
 	subtitle?: string | null
 	script?: string | null
 	video_id?: string | null
@@ -131,6 +132,8 @@ interface FormState {
 	title: string
 	dek: string
 	body: string
+	/** Serialized Portable Text envelope paired with `body`; null until the editor emits one. */
+	bodyPortableText: string | null
 	slug: string
 	byline: string | null
 	authorId: string | null
@@ -176,6 +179,7 @@ function createEmptyFormState(docId: string | null): FormState {
 		title: '',
 		dek: '',
 		body: '',
+		bodyPortableText: null,
 		slug: '',
 		byline: null,
 		authorId: null,
@@ -508,8 +512,8 @@ export function ContentForm({
 		scheduleAutosave(next)
 	}
 
-	function handleBodyChange(md: string) {
-		const next = { ...latestForm.current, body: md }
+	function handleBodyChange(md: string, portableText: string) {
+		const next = { ...latestForm.current, body: md, bodyPortableText: portableText }
 		setForm(next)
 		publishDraft(next)
 		scheduleAutosave(next)
@@ -940,6 +944,7 @@ export function ContentForm({
 						)}
 						<Rte
 							value={form.body}
+							portableText={form.bodyPortableText}
 							onChange={handleBodyChange}
 							onImageUpload={handleEditorImageUpload}
 						/>
@@ -1365,6 +1370,7 @@ function contentResponseToFormState(
 
 	if (contentType === 'article' || contentType === 'newsletter' || contentType === 'page') {
 		next.body = toStringValue(content.body_markdown) || toStringValue(content.body_html)
+		next.bodyPortableText = toNullableString(content.body_portable_text)
 	}
 
 	if (contentType === 'video') {

package/src/ui/editor/Rte.tsx

@@ -5,20 +5,42 @@
 // so the module can be imported in Node/SSR contexts without throwing.
 //
 // Serialization: the internal state is a Tiptap JSON doc; onChange emits
-// docToMarkdown(json) so callers work with markdown (matching the P0 engine
-// body_markdown storage format).
+// docToMarkdown(json) — the derived body_markdown — AND the serialized
+// Portable Text envelope (the durable store, schema/portable-text.ts). On
+// load, a valid stored envelope takes precedence over markdown so structure
+// that markdown cannot express (cell spans, alignment) survives an edit
+// session; rows without Portable Text fall back to markdownToDoc.
 //
 // The toolbar maps RTE_TOOLS to editor.chain() toggle commands.
 //
 // Compile-gated: all Tiptap/React usage verified by `pnpm run build` (tsc).
 // Runtime/visual verification is done via the Playwright smoke (SMOKE.md P2 section).
 
-import { Editor } from '@tiptap/core'
+import { Editor, type JSONContent } from '@tiptap/core'
 import { useEffect, useRef, useState } from 'react'
+import { parsePortableTextEnvelope, wrapPortableText } from '../../schema/portable-text.js'
 import { Icon } from '../icons.js'
 import { createRteExtensions } from './extensions.js'
+import { docToPortableText, portableTextToDoc } from './portable-text.js'
 import { docToMarkdown, markdownToDoc } from './serialize.js'
 
+/** Editor doc for a stored (markdown, Portable Text) pair: envelope wins. */
+function docFromStored(md: string, portableText: string | null | undefined): JSONContent {
+	const envelope = parsePortableTextEnvelope(portableText ?? null)
+	if (envelope) {
+		try {
+			return portableTextToDoc(envelope.content)
+		} catch {
+			// Unknown _type (content newer than this editor): fall back to markdown.
+		}
+	}
+	return markdownToDoc(md)
+}
+
+function serializeDocPortableText(doc: JSONContent): string {
+	return JSON.stringify(wrapPortableText(docToPortableText(doc)))
+}
+
 // ---------------------------------------------------------------------------
 // Toolbar config
 // ---------------------------------------------------------------------------
@@ -35,6 +57,13 @@ type ToolCmd =
 	| 'ordered'
 	| 'link'
 	| 'image'
+	| 'table'
+	| 'tableAddRow'
+	| 'tableAddCol'
+	| 'tableHeaderRow'
+	| 'tableDelRow'
+	| 'tableDelCol'
+	| 'tableDelete'
 
 interface ToolDef {
 	cmd: ToolCmd
@@ -54,6 +83,17 @@ const RTE_TOOLS: ToolDef[] = [
 	{ cmd: 'ordered', label: 'Ordered list', icon: 'rows' },
 	{ cmd: 'link', label: 'Link', icon: 'link' },
 	{ cmd: 'image', label: 'Image', icon: 'image' },
+	{ cmd: 'table', label: 'Insert table', icon: 'grid' },
+]
+
+/** Shown only while the selection sits inside a table. */
+const TABLE_TOOLS: ToolDef[] = [
+	{ cmd: 'tableAddRow', label: 'Add row below', icon: 'rows' },
+	{ cmd: 'tableAddCol', label: 'Add column right', icon: 'columns' },
+	{ cmd: 'tableHeaderRow', label: 'Toggle header row', icon: 'layers' },
+	{ cmd: 'tableDelRow', label: 'Delete row', icon: 'x' },
+	{ cmd: 'tableDelCol', label: 'Delete column', icon: 'x' },
+	{ cmd: 'tableDelete', label: 'Delete table', icon: 'trash' },
 ]
 
 // ---------------------------------------------------------------------------
@@ -63,8 +103,17 @@ const RTE_TOOLS: ToolDef[] = [
 export interface RteProps {
 	/** Current markdown value (controlled). */
 	value: string
-	/** Called with the updated markdown on every doc change. */
-	onChange: (md: string) => void
+	/**
+	 * Stored Portable Text envelope JSON for the same body, if any. When it
+	 * parses, it takes precedence over `value` for (re)loading editor content.
+	 */
+	portableText?: string | null
+	/**
+	 * Called with the updated markdown AND the serialized Portable Text
+	 * envelope on every doc change. The two are always derived from the same
+	 * doc — persist them together.
+	 */
+	onChange: (md: string, portableText: string) => void
 	/** Optional editor image uploader. When present, the image tool opens a file picker. */
 	onImageUpload?: (file: File) => Promise<{ url: string }>
 	/** Optional placeholder text. */
@@ -79,6 +128,7 @@ export interface RteProps {
 
 export function Rte({
 	value,
+	portableText = null,
 	onChange,
 	onImageUpload,
 	placeholder: _placeholder,
@@ -96,7 +146,11 @@ export function Rte({
 	// clobbering the cursor.  The editor is mounted once; callbacks stay fresh
 	// via the ref.
 	const initialValueRef = useRef(value)
+	const initialPortableTextRef = useRef(portableText)
 	const lastAppliedValueRef = useRef(value)
+	const lastAppliedPortableTextRef = useRef(portableText ?? '')
+	const portableTextRef = useRef(portableText)
+	portableTextRef.current = portableText
 	const onChangeRef = useRef(onChange)
 	onChangeRef.current = onChange
 
@@ -109,13 +163,20 @@ export function Rte({
 		const editor = new Editor({
 			element: el,
 			extensions: createRteExtensions(),
-			content: markdownToDoc(initialValueRef.current),
+			content: docFromStored(initialValueRef.current, initialPortableTextRef.current),
 			editable: !readOnly,
 			onUpdate({ editor: e }) {
-				const md = docToMarkdown(e.getJSON())
-				if (md === lastAppliedValueRef.current) return
+				const json = e.getJSON()
+				const md = docToMarkdown(json)
+				const pt = serializeDocPortableText(json)
+				// Markdown alone is not enough to detect a change: cell spans and
+				// alignment have no markdown form, so compare both serializations.
+				if (md === lastAppliedValueRef.current && pt === lastAppliedPortableTextRef.current) {
+					return
+				}
 				lastAppliedValueRef.current = md
-				onChangeRef.current(md)
+				lastAppliedPortableTextRef.current = pt
+				onChangeRef.current(md, pt)
 			},
 			onSelectionUpdate() {
 				// Re-render to reflect active state changes in the toolbar
@@ -139,7 +200,17 @@ export function Rte({
 		if (!editor) return
 		if (value === lastAppliedValueRef.current) return
 		lastAppliedValueRef.current = value
-		editor.commands.setContent(markdownToDoc(value))
+		// Trust the Portable Text prop only when it is NEW (differs from what
+		// the editor last emitted or applied). A markdown-only external update —
+		// e.g. an AI writeback — means the stored envelope is stale for this
+		// value, so parse the markdown instead of resurrecting old content.
+		const incomingPortableText = portableTextRef.current ?? ''
+		const freshPortableText =
+			incomingPortableText !== '' && incomingPortableText !== lastAppliedPortableTextRef.current
+				? incomingPortableText
+				: null
+		if (freshPortableText !== null) lastAppliedPortableTextRef.current = freshPortableText
+		editor.commands.setContent(docFromStored(value, freshPortableText))
 	}, [value])
 
 	const editor = editorRef.current
@@ -179,6 +250,14 @@ export function Rte({
 							disabled={tool.cmd === 'image' && uploadingImage}
 						/>
 					))}
+					{editor?.isActive('table') && (
+						<>
+							<span style={toolbarDivider} aria-hidden="true" />
+							{TABLE_TOOLS.map((tool) => (
+								<ToolButton key={tool.cmd} tool={tool} editor={editor} />
+							))}
+						</>
+					)}
 					{onImageUpload && (
 						<input
 							ref={imageInputRef}
@@ -265,6 +344,27 @@ function ToolButton({
 				}
 				break
 			}
+			case 'table':
+				chain.insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run()
+				break
+			case 'tableAddRow':
+				chain.addRowAfter().run()
+				break
+			case 'tableAddCol':
+				chain.addColumnAfter().run()
+				break
+			case 'tableHeaderRow':
+				chain.toggleHeaderRow().run()
+				break
+			case 'tableDelRow':
+				chain.deleteRow().run()
+				break
+			case 'tableDelCol':
+				chain.deleteColumn().run()
+				break
+			case 'tableDelete':
+				chain.deleteTable().run()
+				break
 		}
 	}
 
@@ -289,6 +389,8 @@ function ToolButton({
 				return editor.isActive('bulletList')
 			case 'ordered':
 				return editor.isActive('orderedList')
+			case 'table':
+				return editor.isActive('table')
 			default:
 				return false
 		}
@@ -342,6 +444,14 @@ const rteWrap: React.CSSProperties = {
 	minHeight: 240,
 }
 
+const toolbarDivider: React.CSSProperties = {
+	width: 1,
+	height: 18,
+	margin: '0 4px',
+	alignSelf: 'center',
+	background: 'var(--border)',
+}
+
 const toolbarStyle: React.CSSProperties = {
 	display: 'flex',
 	flexWrap: 'wrap',

package/src/ui/editor/content-payload.ts

@@ -5,6 +5,8 @@ export interface ContentDraftFields {
 	title: string
 	dek: string
 	body: string
+	/** Serialized Portable Text envelope for the body; null until the editor emits one. */
+	bodyPortableText?: string | null
 	videoUrl: string
 	videoSourceKind?: string | null
 	videoId?: string | null
@@ -104,6 +106,7 @@ export function buildContentUpdatePayload(
 		const wordCount = countWords(draft.body)
 		payload.content = {
 			bodyMarkdown: draft.body,
+			bodyPortableText: draft.bodyPortableText || null,
 			wordCount,
 			readTimeMinutes: estimateReadTime(wordCount),
 		}

package/src/ui/editor/extensions.ts

@@ -1,5 +1,6 @@
 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 { TrimBoundaryMarks } from './trim-boundary-marks.js'
 import { TweetEmbed } from './tweet-embed.js'
@@ -19,5 +20,8 @@ export function createRteExtensions() {
 		TrimBoundaryMarks,
 		Image,
 		TweetEmbed,
+		// One consolidated package registers table/tableRow/tableHeader/tableCell.
+		// Gapcursor (via StarterKit) lets the caret sit before/after a table.
+		TableKit.configure({ table: { resizable: true } }),
 	]
 }