emdash 0.36.0 → 0.37.0

package/src/content/converters/portable-text-to-prosemirror.ts

@@ -15,6 +15,12 @@ import {
 	normalizeListId,
 	normalizeListStart,
 } from "./numbered-list.js";
+import {
+	PORTABLE_TEXT_BLOCK_ATTR,
+	PORTABLE_TEXT_BLOCK_NODE,
+	PORTABLE_TEXT_SPAN_MARK,
+	attrsWithPortableTextKey,
+} from "./portable-text-identity.js";
 import type {
 	ProseMirrorDocument,
 	ProseMirrorNode,
@@ -28,10 +34,19 @@ import type {
 	PortableTextCodeBlock,
 } from "./types.js";
 
-/**
- * Convert Portable Text to ProseMirror document
- */
-export function portableTextToProsemirror(blocks: PortableTextBlock[]): ProseMirrorDocument {
+export interface PortableTextToProsemirrorOptions {
+	/**
+	 * Preserve custom blocks and Portable Text keys through a ProseMirror round trip.
+	 * Add `portableTextIdentityExtensions` to the TipTap schema when this is enabled.
+	 */
+	preserveIdentity?: boolean;
+}
+
+/** Convert Portable Text to a ProseMirror document. */
+export function portableTextToProsemirror(
+	blocks: PortableTextBlock[],
+	options: PortableTextToProsemirrorOptions = {},
+): ProseMirrorDocument {
 	if (!blocks || blocks.length === 0) {
 		return {
 			type: "doc",
@@ -39,6 +54,7 @@ export function portableTextToProsemirror(blocks: PortableTextBlock[]): ProseMir
 		};
 	}
 	assertPortableTextMarksSupported(blocks);
+	const preserveIdentity = options.preserveIdentity === true;
 
 	const content: ProseMirrorNode[] = [];
 	let i = 0;
@@ -80,7 +96,7 @@ export function portableTextToProsemirror(blocks: PortableTextBlock[]): ProseMir
 				}
 			}
 
-			content.push(convertList(listBlocks, listType, `root:${runStart}`));
+			content.push(convertList(listBlocks, listType, `root:${runStart}`, preserveIdentity));
 		} else if (isTextBlock(block) && block.style === "blockquote") {
 			// Collect a blockquote "run": Portable Text is flat, so a
 			// multi-paragraph quote is stored as consecutive blocks with
@@ -105,15 +121,20 @@ export function portableTextToProsemirror(blocks: PortableTextBlock[]): ProseMir
 			content.push({
 				type: "blockquote",
 				content: quoteBlocks.map((quoteBlock) => {
-					const paragraph = convertSpans(quoteBlock.children, quoteBlock.markDefs || []);
+					const paragraph = convertSpans(
+						quoteBlock.children,
+						quoteBlock.markDefs || [],
+						preserveIdentity,
+					);
 					return {
 						type: "paragraph",
+						attrs: identityAttrs(undefined, quoteBlock._key, preserveIdentity),
 						content: paragraph.length > 0 ? paragraph : undefined,
 					};
 				}),
 			});
 		} else {
-			const converted = convertBlock(block);
+			const converted = convertBlock(block, preserveIdentity);
 			if (converted) {
 				content.push(converted);
 			}
@@ -127,6 +148,14 @@ export function portableTextToProsemirror(blocks: PortableTextBlock[]): ProseMir
 	});
 }
 
+function identityAttrs(
+	attrs: Record<string, unknown> | undefined,
+	key: string,
+	preserveIdentity: boolean,
+): Record<string, unknown> | undefined {
+	return preserveIdentity ? attrsWithPortableTextKey(attrs, key) : attrs;
+}
+
 function getListMetadata(
 	item: PortableTextTextBlock,
 	fallbackSeed: string,
@@ -176,8 +205,8 @@ function isImageBlock(block: PortableTextBlock): block is PortableTextImageBlock
 }
 
 /**
- * Type guard for gallery blocks. Requires an `images` array — a gallery
- * without one is malformed and falls through to the unknown-block path.
+ * Type guard for gallery blocks that carry a usable `images` array.
+ * Galleries without one are handled separately in `convertBlock`.
  */
 function isGalleryBlock(block: PortableTextBlock): block is PortableTextGalleryBlock {
 	return block._type === "gallery" && "images" in block && Array.isArray(block.images);
@@ -193,40 +222,70 @@ function isCodeBlock(block: PortableTextBlock): block is PortableTextCodeBlock {
 /**
  * Convert a single Portable Text block to ProseMirror node
  */
-function convertBlock(block: PortableTextBlock): ProseMirrorNode | null {
+function convertBlock(block: PortableTextBlock, preserveIdentity: boolean): ProseMirrorNode | null {
 	if (isTextBlock(block)) {
-		return convertTextBlock(block);
+		return convertTextBlock(block, preserveIdentity);
 	}
 	if (isImageBlock(block)) {
-		return convertImage(block);
+		return convertImage(block, preserveIdentity);
 	}
 	if (block._type === "image") {
 		// Malformed image block (no asset wrapper) — extract url from top level
-		return convertMalformedImage(block);
+		return convertMalformedImage(block, preserveIdentity);
 	}
 	if (isGalleryBlock(block)) {
 		return {
 			type: "gallery",
-			attrs: {
-				images: sanitizeGalleryImages(block.images),
-				columns: typeof block.columns === "number" ? block.columns : undefined,
-			},
+			attrs: identityAttrs(
+				{
+					images: sanitizeGalleryImages(block.images),
+					columns: typeof block.columns === "number" ? block.columns : undefined,
+				},
+				block._key,
+				preserveIdentity,
+			),
 		};
 	}
 	if (isCodeBlock(block)) {
-		return convertCodeBlock(block);
+		return convertCodeBlock(block, preserveIdentity);
 	}
 	if (block._type === "htmlBlock") {
 		const hb = block as PortableTextBlock & { html?: string };
 		return {
 			type: "htmlBlock",
-			attrs: { html: hb.html || "" },
+			attrs: identityAttrs({ html: hb.html || "" }, block._key, preserveIdentity),
 		};
 	}
 	if (block._type === "break") {
-		return { type: "horizontalRule" };
+		return {
+			type: "horizontalRule",
+			attrs: identityAttrs(undefined, block._key, preserveIdentity),
+		};
+	}
+	if (block._type === "gallery") {
+		if (preserveIdentity) {
+			return {
+				type: PORTABLE_TEXT_BLOCK_NODE,
+				attrs: { [PORTABLE_TEXT_BLOCK_ATTR]: block },
+			};
+		}
+		return {
+			type: "paragraph",
+			content: [
+				{
+					type: "text",
+					text: `[Unknown block type: ${block._type}]`,
+					marks: [{ type: "code" }],
+				},
+			],
+		};
+	}
+	if (preserveIdentity) {
+		return {
+			type: PORTABLE_TEXT_BLOCK_NODE,
+			attrs: { [PORTABLE_TEXT_BLOCK_ATTR]: block },
+		};
 	}
-	// Unknown block - wrap in a div or preserve as placeholder
 	return {
 		type: "paragraph",
 		content: [
@@ -242,11 +301,14 @@ function convertBlock(block: PortableTextBlock): ProseMirrorNode | null {
 /**
  * Convert text block to ProseMirror paragraph or heading
  */
-function convertTextBlock(block: PortableTextTextBlock): ProseMirrorNode | null {
+function convertTextBlock(
+	block: PortableTextTextBlock,
+	preserveIdentity: boolean,
+): ProseMirrorNode | null {
 	const { style = "normal", children, markDefs = [] } = block;
 
 	// Convert children to ProseMirror nodes
-	const content = convertSpans(children, markDefs);
+	const content = convertSpans(children, markDefs, preserveIdentity);
 
 	// Determine node type based on style
 	switch (style) {
@@ -259,10 +321,14 @@ function convertTextBlock(block: PortableTextTextBlock): ProseMirrorNode | null
 			const level = parseInt(style.substring(1), 10);
 			return {
 				type: "heading",
-				attrs: {
-					level,
-					...(block.textAlign ? { textAlign: block.textAlign } : {}),
-				},
+				attrs: identityAttrs(
+					{
+						level,
+						...(block.textAlign ? { textAlign: block.textAlign } : {}),
+					},
+					block._key,
+					preserveIdentity,
+				),
 				content: content.length > 0 ? content : undefined,
 			};
 		}
@@ -270,6 +336,7 @@ function convertTextBlock(block: PortableTextTextBlock): ProseMirrorNode | null
 		case "blockquote":
 			return {
 				type: "blockquote",
+				attrs: identityAttrs(undefined, block._key, preserveIdentity),
 				content: [
 					{
 						type: "paragraph",
@@ -282,7 +349,11 @@ function convertTextBlock(block: PortableTextTextBlock): ProseMirrorNode | null
 		default:
 			return {
 				type: "paragraph",
-				attrs: block.textAlign ? { textAlign: block.textAlign } : undefined,
+				attrs: identityAttrs(
+					block.textAlign ? { textAlign: block.textAlign } : undefined,
+					block._key,
+					preserveIdentity,
+				),
 				content: content.length > 0 ? content : undefined,
 			};
 	}
@@ -295,6 +366,7 @@ function convertList(
 	items: PortableTextTextBlock[],
 	listType: "bullet" | "number",
 	context: string,
+	preserveIdentity: boolean,
 ): ProseMirrorNode {
 	// Group items by level
 	const rootItems: ProseMirrorNode[] = [];
@@ -315,11 +387,19 @@ function convertList(
 			}
 
 			rootItems.push(
-				convertListItem(item, nestedItems, listType, `${context}:${rootItems.length}`),
+				convertListItem(
+					item,
+					nestedItems,
+					listType,
+					`${context}:${rootItems.length}`,
+					preserveIdentity,
+				),
 			);
 		} else {
 			// Orphan nested item - treat as root
-			rootItems.push(convertListItem(item, [], listType, `${context}:${rootItems.length}`));
+			rootItems.push(
+				convertListItem(item, [], listType, `${context}:${rootItems.length}`, preserveIdentity),
+			);
 			i++;
 		}
 	}
@@ -342,13 +422,15 @@ function convertListItem(
 	nestedItems: PortableTextTextBlock[],
 	parentListType: "bullet" | "number",
 	context: string,
+	preserveIdentity: boolean,
 ): ProseMirrorNode {
 	const content: ProseMirrorNode[] = [];
 
 	// Add paragraph content
-	const spans = convertSpans(item.children, item.markDefs || []);
+	const spans = convertSpans(item.children, item.markDefs || [], preserveIdentity);
 	content.push({
 		type: "paragraph",
+		attrs: identityAttrs(undefined, item._key, preserveIdentity),
 		content: spans.length > 0 ? spans : undefined,
 	});
 
@@ -358,11 +440,9 @@ function convertListItem(
 		// item's nested subtree. A new sub-list only starts when we hit
 		// another block at that root level with a different `listItem` type;
 		// deeper blocks (level > minLevel) belong to the current group as
-		// descendants regardless of their own `listItem`. The previous
-		// grouping broke on any type change at any depth, so a deep mixed
-		// tree like `bullet L1 → number L2 → bullet L3 → number L2` would
-		// emit C(L3) as a sibling list under A(L1) instead of nesting it
-		// under B(L2), then degrade C to L2 on round-trip.
+		// descendants regardless of their own `listItem`. A deep mixed tree
+		// like `bullet L1 → number L2 → bullet L3 → number L2` stays nested
+		// under B(L2) and preserves its original level on round-trip.
 		let minLevel = Infinity;
 		for (const ni of nestedItems) {
 			const level = ni.level || 2;
@@ -390,7 +470,12 @@ function convertListItem(
 					level: (ni.level || 2) - 1,
 				}));
 				content.push(
-					convertList(adjustedGroup, anchorType, `${context}:nested:${j - nestedGroup.length}`),
+					convertList(
+						adjustedGroup,
+						anchorType,
+						`${context}:nested:${j - nestedGroup.length}`,
+						preserveIdentity,
+					),
 				);
 			}
 		}
@@ -408,12 +493,14 @@ function convertListItem(
 function convertSpans(
 	spans: PortableTextSpan[],
 	markDefs: PortableTextMarkDef[],
+	preserveIdentity: boolean,
 ): ProseMirrorNode[] {
 	const nodes: ProseMirrorNode[] = [];
 	const markDefsMap = new Map(markDefs.map((md) => [md._key, md]));
 
 	for (const span of spans) {
 		if (span._type !== "span") continue;
+		const referencedMarkDefs = markDefs.filter((markDef) => span.marks?.includes(markDef._key));
 
 		// Handle newlines in text
 		const parts = span.text.split("\n");
@@ -424,19 +511,35 @@ function convertSpans(
 			// Add text node
 			if (text.length > 0) {
 				const marks = convertMarks(span.marks || [], markDefsMap);
+				if (preserveIdentity) {
+					marks.push({
+						type: PORTABLE_TEXT_SPAN_MARK,
+						attrs: { key: span._key, markDefs: referencedMarkDefs },
+					});
+				}
 				const node: ProseMirrorNode = {
 					type: "text",
 					text,
 				};
-				if (marks.length > 0) {
-					node.marks = marks;
-				}
+				if (marks.length > 0) node.marks = marks;
 				nodes.push(node);
 			}
 
 			// Add hard break between parts (not after last)
 			if (i < parts.length - 1) {
-				nodes.push({ type: "hardBreak" });
+				nodes.push(
+					preserveIdentity
+						? {
+								type: "hardBreak",
+								marks: [
+									{
+										type: PORTABLE_TEXT_SPAN_MARK,
+										attrs: { key: span._key, markDefs: referencedMarkDefs },
+									},
+								],
+							}
+						: { type: "hardBreak" },
+				);
 			}
 		}
 	}
@@ -507,23 +610,38 @@ function convertMarks(
 	return pmMarks;
 }
 
+function imageAlignment(value: unknown): PortableTextImageBlock["alignment"] {
+	return value === "left" ||
+		value === "center" ||
+		value === "right" ||
+		value === "wide" ||
+		value === "full"
+		? value
+		: undefined;
+}
+
 /**
  * Convert image block to ProseMirror
  */
-function convertImage(block: PortableTextImageBlock): ProseMirrorNode {
+function convertImage(block: PortableTextImageBlock, preserveIdentity: boolean): ProseMirrorNode {
 	return {
 		type: "image",
-		attrs: {
-			src: block.asset.url || block.asset._ref,
-			alt: block.alt || "",
-			title: block.caption || "",
-			mediaId: block.asset._ref,
-			provider: block.asset.provider,
-			width: block.width,
-			height: block.height,
-			displayWidth: block.displayWidth,
-			displayHeight: block.displayHeight,
-		},
+		attrs: identityAttrs(
+			{
+				src: block.asset.url || block.asset._ref,
+				alt: block.alt || "",
+				title: block.caption || "",
+				mediaId: block.asset._ref,
+				provider: block.asset.provider,
+				width: block.width,
+				height: block.height,
+				displayWidth: block.displayWidth,
+				displayHeight: block.displayHeight,
+				alignment: imageAlignment(block.alignment),
+			},
+			block._key,
+			preserveIdentity,
+		),
 	};
 }
 
@@ -532,7 +650,10 @@ function convertImage(block: PortableTextImageBlock): ProseMirrorNode {
  * Handles blocks like `{ _type: "image", url: "...", alt: "..." }` that may
  * originate from migrations or third-party imports.
  */
-function convertMalformedImage(block: PortableTextBlock): ProseMirrorNode {
+function convertMalformedImage(
+	block: PortableTextBlock,
+	preserveIdentity: boolean,
+): ProseMirrorNode {
 	// PortableTextUnknownBlock allows indexed access via [key: string]: unknown
 	const url = "url" in block && typeof block.url === "string" ? block.url : "";
 	const alt = "alt" in block && typeof block.alt === "string" ? block.alt : "";
@@ -549,29 +670,41 @@ function convertMalformedImage(block: PortableTextBlock): ProseMirrorNode {
 			: undefined;
 	return {
 		type: "image",
-		attrs: {
-			src: url,
-			alt,
-			title: caption,
-			mediaId: undefined,
-			provider: undefined,
-			width,
-			height,
-			displayWidth,
-			displayHeight,
-		},
+		attrs: identityAttrs(
+			{
+				src: url,
+				alt,
+				title: caption,
+				mediaId: undefined,
+				provider: undefined,
+				width,
+				height,
+				displayWidth,
+				displayHeight,
+				alignment: imageAlignment("alignment" in block ? block.alignment : undefined),
+			},
+			block._key,
+			preserveIdentity,
+		),
 	};
 }
 
 /**
  * Convert code block to ProseMirror
  */
-function convertCodeBlock(block: PortableTextCodeBlock): ProseMirrorNode {
+function convertCodeBlock(
+	block: PortableTextCodeBlock,
+	preserveIdentity: boolean,
+): ProseMirrorNode {
 	return {
 		type: "codeBlock",
-		attrs: {
-			language: block.language || null,
-		},
+		attrs: identityAttrs(
+			{
+				language: block.language || null,
+			},
+			block._key,
+			preserveIdentity,
+		),
 		content: block.code ? [{ type: "text", text: block.code }] : undefined,
 	};
 }