feat: add toExternalHTML for custom inline content

Author: nperez0111

packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts

@@ -13,6 +13,7 @@ import {
   inlineContentToNodes,
   tableContentToNodes,
 } from "../../../nodeConversions/blockToNode.js";
+import { nodeToCustomInlineContent } from "../../../nodeConversions/nodeToBlock.js";
 
 function addAttributesAndRemoveClasses(element: HTMLElement) {
   // Removes all BlockNote specific class names.
@@ -53,16 +54,57 @@ export function serializeInlineContentExternalHTML<
     throw new UnreachableCaseError(blockContent.type);
   }
 
-  // We call the prosemirror serializer here because it handles Marks and Inline Content nodes nicely.
-  // If we'd want to support custom serialization or externalHTML for Inline Content, we'd have to implement
-  // a custom serializer here.
-  const dom = serializer.serializeFragment(Fragment.from(nodes), options);
+  // Check if any of the nodes are custom inline content with toExternalHTML
+  const doc = options?.document ?? document;
+  const fragment = doc.createDocumentFragment();
+
+  for (const node of nodes) {
+    // Check if this is a custom inline content node with toExternalHTML
+    if (
+      node.type &&
+      node.type.name &&
+      node.type.name in editor.schema.inlineContentSchema
+    ) {
+      const inlineContentImplementation =
+        editor.schema.inlineContentSpecs[node.type.name]?.implementation;
+
+      if (inlineContentImplementation?.toExternalHTML) {
+        // Convert the node to inline content format
+        const inlineContent = nodeToCustomInlineContent(
+          node,
+          editor.schema.inlineContentSchema,
+          editor.schema.styleSchema,
+        );
 
-  if (dom.nodeType === 1 /* Node.ELEMENT_NODE */) {
-    addAttributesAndRemoveClasses(dom as HTMLElement);
+        // Use the custom toExternalHTML method
+        const output = inlineContentImplementation.toExternalHTML(
+          inlineContent as any,
+          editor as any,
+        );
+
+        if (output) {
+          fragment.appendChild(output.dom);
+          continue;
+        }
+      }
+    }
+
+    // Fall back to default serialization for this node
+    const nodeFragment = serializer.serializeFragment(
+      Fragment.from([node]),
+      options,
+    );
+    fragment.appendChild(nodeFragment);
   }
 
-  return dom;
+  if (
+    fragment.childNodes.length === 1 &&
+    fragment.firstChild?.nodeType === 1 /* Node.ELEMENT_NODE */
+  ) {
+    addAttributesAndRemoveClasses(fragment.firstChild as HTMLElement);
+  }
+
+  return fragment;
 }
 
 /**

packages/core/src/api/exporters/html/util/serializeBlocksInternalHTML.ts

@@ -13,6 +13,7 @@ import {
   tableContentToNodes,
 } from "../../../nodeConversions/blockToNode.js";
 
+import { nodeToCustomInlineContent } from "../../../nodeConversions/nodeToBlock.js";
 export function serializeInlineContentInternalHTML<
   BSchema extends BlockSchema,
   I extends InlineContentSchema,
@@ -39,12 +40,50 @@ export function serializeInlineContentInternalHTML<
     throw new UnreachableCaseError(blockContent.type);
   }
 
-  // We call the prosemirror serializer here because it handles Marks and Inline Content nodes nicely.
-  // If we'd want to support custom serialization or externalHTML for Inline Content, we'd have to implement
-  // a custom serializer here.
-  const dom = serializer.serializeFragment(Fragment.from(nodes), options);
+  // Check if any of the nodes are custom inline content with toExternalHTML
+  const doc = options?.document ?? document;
+  const fragment = doc.createDocumentFragment();
+
+  for (const node of nodes) {
+    // Check if this is a custom inline content node with toExternalHTML
+    if (
+      node.type &&
+      node.type.name &&
+      editor.schema.inlineContentSchema[node.type.name]
+    ) {
+      const inlineContentImplementation =
+        editor.inlineContentImplementations[node.type.name]?.implementation;
+
+      if (inlineContentImplementation?.toExternalHTML) {
+        // Convert the node to inline content format
+        const inlineContent = nodeToCustomInlineContent(
+          node,
+          editor.schema.inlineContentSchema,
+          editor.schema.styleSchema,
+        );
+
+        // Use the custom toExternalHTML method
+        const output = inlineContentImplementation.toExternalHTML(
+          inlineContent as any,
+          editor as any,
+        );
+
+        if (output) {
+          fragment.appendChild(output.dom);
+          continue;
+        }
+      }
+    }
 
-  return dom;
+    // Fall back to default serialization for this node
+    const nodeFragment = serializer.serializeFragment(
+      Fragment.from([node]),
+      options,
+    );
+    fragment.appendChild(nodeFragment);
+  }
+
+  return fragment;
 }
 
 function serializeBlock<

packages/core/src/schema/inlineContent/createSpec.ts

@@ -57,6 +57,28 @@ export type CustomInlineContentImplementation<
     contentDOM?: HTMLElement;
     destroy?: () => void;
   };
+
+  /**
+   * Renders an inline content to external HTML elements for use outside the editor
+   * If not provided, falls back to the render method
+   */
+  toExternalHTML?: (
+    /**
+     * The custom inline content to render
+     */
+    inlineContent: InlineContentFromConfig<T, S>,
+    /**
+     * The BlockNote editor instance
+     * This is typed generically. If you want an editor with your custom schema, you need to
+     * cast it manually, e.g.: `const e = editor as BlockNoteEditor<typeof mySchema>;`
+     */
+    editor: BlockNoteEditor<any, any, S>,
+  ) =>
+    | {
+        dom: HTMLElement | DocumentFragment;
+        contentDOM?: HTMLElement;
+      }
+    | undefined;
 };
 
 export function getInlineContentParseRules<C extends CustomInlineContentConfig>(
@@ -112,9 +134,7 @@ export function createInlineContentSpec<
     group: "inline",
     selectable: inlineContentConfig.content === "styled",
     atom: inlineContentConfig.content === "none",
-    content: (inlineContentConfig.content === "styled"
-      ? "inline*"
-      : "") as T["content"] extends "styled" ? "inline*" : "",
+    content: inlineContentConfig.content === "styled" ? "inline*" : "",
 
     addAttributes() {
       return propsToAttributes(inlineContentConfig.propSchema);
@@ -189,5 +209,6 @@ export function createInlineContentSpec<
   return createInlineContentSpecFromTipTapNode(
     node,
     inlineContentConfig.propSchema,
-  ) as InlineContentSpec<T>; // TODO: fix cast
+    { toExternalHTML: inlineContentImplementation.toExternalHTML },
+  ) as InlineContentSpec<T>;
 }

packages/core/src/schema/inlineContent/internal.ts

@@ -86,14 +86,22 @@ export function createInternalInlineContentSpec<T extends InlineContentConfig>(
 export function createInlineContentSpecFromTipTapNode<
   T extends Node,
   P extends PropSchema,
->(node: T, propSchema: P) {
+>(
+  node: T,
+  propSchema: P,
+  implementation?: Omit<
+    InlineContentImplementation<InlineContentConfig>,
+    "node"
+  >,
+) {
   return createInternalInlineContentSpec(
     {
       type: node.name as T["name"],
       propSchema,
       content: node.config.content === "inline*" ? "styled" : "none",
     },
     {
+      ...implementation,
       node,
     },
   );

packages/core/src/schema/inlineContent/types.ts

@@ -1,6 +1,7 @@
 import { Node } from "@tiptap/core";
 import { PropSchema, Props } from "../propTypes.js";
 import { StyleSchema, Styles } from "../styles/types.js";
+import { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
 
 export type CustomInlineContentConfig = {
   type: string;
@@ -21,6 +22,15 @@ export type InlineContentImplementation<T extends InlineContentConfig> =
     ? undefined
     : {
         node: Node;
+        toExternalHTML?: (
+          inlineContent: any,
+          editor: BlockNoteEditor<any, any, any>,
+        ) =>
+          | {
+              dom: HTMLElement | DocumentFragment;
+              contentDOM?: HTMLElement;
+            }
+          | undefined;
       };
 
 export type InlineContentSchemaWithInlineContent<

tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/inlineContent/mentionWithToExternalHTML.html

@@ -0,0 +1,17 @@
+<div class="bn-block-group" data-node-type="blockGroup">
+  <div class="bn-block-outer" data-node-type="blockOuter" data-id="1">
+    <div class="bn-block" data-node-type="blockContainer" data-id="1">
+      <div class="bn-block-content" data-content-type="paragraph">
+        <p class="bn-inline-content">
+          I enjoy working with
+          <span
+            class="mention-external"
+            data-external="true"
+            data-inline-content-type="mention"
+            data-user="Matthew"
+          >@Matthew</span>
+        </p>
+      </div>
+    </div>
+  </div>
+</div>

tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/inlineContent/tagWithoutToExternalHTML.html

@@ -0,0 +1,15 @@
+<div class="bn-block-group" data-node-type="blockGroup">
+  <div class="bn-block-outer" data-node-type="blockOuter" data-id="1">
+    <div class="bn-block" data-node-type="blockContainer" data-id="1">
+      <div class="bn-block-content" data-content-type="paragraph">
+        <p class="bn-inline-content">
+          I love
+          <span data-inline-content-type="tag">
+            #
+            <span data-editable="">BlockNote</span>
+          </span>
+        </p>
+      </div>
+    </div>
+  </div>
+</div>

tests/src/unit/core/formatConversion/export/__snapshots__/html/inlineContent/mentionWithToExternalHTML.html

@@ -0,0 +1,9 @@
+<p>
+  I enjoy working with
+  <span
+    class="mention-external"
+    data-external="true"
+    data-inline-content-type="mention"
+    data-user="Matthew"
+  >@Matthew</span>
+</p>

tests/src/unit/core/formatConversion/export/__snapshots__/html/inlineContent/tagWithoutToExternalHTML.html

@@ -0,0 +1,7 @@
+<p>
+  I love
+  <span data-inline-content-type="tag">
+    #
+    <span data-editable="">BlockNote</span>
+  </span>
+</p>

tests/src/unit/core/formatConversion/export/__snapshots__/markdown/inlineContent/mentionWithToExternalHTML.md

@@ -0,0 +1 @@
+I enjoy working with @Matthew