fix(core): normalize container parsing and export

Author: nperez0111

docs/content/docs/features/custom-schemas/container-blocks.mdx

@@ -206,8 +206,9 @@ Configurations are checked when the schema is created, and fail up front with a
 - an `allow` array naming an unknown type, or naming a regular block type (per-type filtering of regular blocks is [not supported](#restricting-children));
 - `children` combined with any `content` other than `"none"` or `"inline"`;
 - `placeable: "namedOnly"` on a regular block;
-- restricted child types or an explicit `min` on a titled block;
-- container cycles: a container that (transitively) requires a child that requires it back could never be created. An `allow` that permits regular blocks breaks the cycle, since they're always satisfiable.
+- restricted child types or an explicit `min` on a titled block.
+
+Recursive content expressions and automatic child filling are handled by ProseMirror.
 
 Documents are checked too. `initialContent` that doesn't fit the schema throws when the editor is created, rather than loading in a broken state. This matters when you change a `children` config on a schema whose documents are already saved somewhere: a stored document that no longer fits, say a `columnList` left with a single column, now fails at load. Migrate those documents before shipping the change.
 

packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.test.ts

@@ -7,16 +7,25 @@ import {
   getBlockInfoFromSelection,
   getNodeId,
 } from "../../../getBlockInfoFromPos.js";
-import { setupTestEnv } from "../../setupTestEnv.js";
+import { getNodeById } from "../../../nodeUtil.js";
+import { containerSchema } from "../../containers/containers.fixture.js";
+import { setupTestEnv, testDocument } from "../../setupTestEnv.js";
 import {
   moveBlocksDown,
   moveBlocksUp,
   moveSelectedBlocksAndSelection,
 } from "./moveBlocks.js";
 
-const getEditor = setupTestEnv();
+const getEditor = setupTestEnv<
+  typeof containerSchema.blockSchema,
+  typeof containerSchema.inlineContentSchema,
+  typeof containerSchema.styleSchema
+>({
+  schema: containerSchema,
+  document: testDocument,
+});
 
-function makeSelectionSpanContent(selectionType: "text" | "node" | "cell") {
+function makeSelectionSpanContent(selectionType: "text" | "cell") {
   const blockInfo = getEditor().transact((tr) => getBlockInfoFromSelection(tr));
   if (!blockInfo.hasContent) {
     throw new Error(
@@ -36,10 +45,6 @@ function makeSelectionSpanContent(selectionType: "text" | "node" | "cell") {
         ),
       ),
     );
-  } else if (selectionType === "node") {
-    editor.transact((tr) =>
-      tr.setSelection(NodeSelection.create(tr.doc, content.beforePos)),
-    );
   } else {
     editor.transact((tr) =>
       tr.setSelection(
@@ -69,19 +74,30 @@ describe("Test moveSelectedBlockAndSelection", () => {
     ).toBeTruthy();
   });
 
-  it("Node selection", () => {
-    getEditor().setTextCursorPosition("image-0");
-    makeSelectionSpanContent("node");
-
-    moveSelectedBlocksAndSelection(getEditor(), "paragraph-0", "before");
-
-    const selection = getEditor().transact((tr) => tr.selection);
-    getEditor().setTextCursorPosition("image-0");
-    makeSelectionSpanContent("node");
-
-    expect(
-      selection.eq(getEditor().transact((tr) => tr.selection)),
-    ).toBeTruthy();
+  it.each([
+    { type: "image", offset: 1 },
+    { type: "callout", offset: 0 },
+  ] as const)("Node selection: $type", ({ type, offset }) => {
+    const editor = getEditor();
+    editor.insertBlocks([{ id: "selected", type }], "paragraph-1", "after");
+    editor.transact((tr) => {
+      const block = getNodeById("selected", tr.doc)!;
+      tr.setSelection(
+        NodeSelection.create(tr.doc, block.posBeforeNode + offset),
+      );
+    });
+
+    moveSelectedBlocksAndSelection(editor, "paragraph-0", "before");
+
+    expect(editor.document[0].id).toBe("selected");
+    editor.transact((tr) => {
+      const moved = getNodeById("selected", tr.doc)!;
+      expect(
+        tr.selection.eq(
+          NodeSelection.create(tr.doc, moved.posBeforeNode + offset),
+        ),
+      ).toBe(true);
+    });
   });
 
   it("Cell selection", () => {

packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.ts

@@ -137,7 +137,11 @@ function updateBlockSelectionFromData(
       anchorBlockPos + data.headCellOffset,
     );
   } else if (data.type === "node") {
-    selection = NodeSelection.create(tr.doc, anchorBlockPos + 1);
+    const blockInfo = getBlockInfoAt(tr.doc, anchorBlockPos);
+    selection = NodeSelection.create(
+      tr.doc,
+      blockInfo.hasContent ? blockInfo.content.beforePos : anchorBlockPos,
+    );
   } else {
     const headBlockPos = getNodeById(data.headBlockId, tr.doc)?.posBeforeNode;
     if (headBlockPos === undefined) {

packages/core/src/api/blockManipulation/containers/containers.test.ts

@@ -48,23 +48,29 @@ beforeEach(() => {
 });
 
 describe("children insertion & filling", () => {
-  // Regression: nothing filled a container inserted without children, so
-  // inserting one threw a raw ProseMirror
-  // `RangeError: Invalid content for node ...`.
-  it("fills a container inserted without children, with real child ids", () => {
-    expect(() =>
-      editor.insertBlocks([{ type: "callout", id: "c-0" }], "p-1", "after"),
-    ).not.toThrow();
-
-    const callout = editor.getBlock("c-0")!;
-    expect(callout.children).toHaveLength(1);
-    expect(callout.children[0].type).toBe("paragraph");
-    // Auto-filled nodes come from the schema with `id: null`, and the
-    // UniqueID plugin never sees them because `insertBlocks` converts back
-    // through `nodeToBlock` before the transaction is dispatched.
-    expect(callout.children[0].id).toBeTruthy();
-    expect(editor.getBlock(callout.children[0].id)).toBeDefined();
-  });
+  it.each([
+    { block: { type: "callout" }, childType: "paragraph", min: 1 },
+    {
+      block: { type: "callout", children: [] },
+      childType: "paragraph",
+      min: 1,
+    },
+    { block: { type: "pair" }, childType: "paragraph", min: 2 },
+    { block: { type: "grid" }, childType: "gridCell", min: 2 },
+  ] satisfies { block: PartialBlock; childType: string; min: number }[])(
+    "fills $block to its minimum with identifiable $childType children",
+    ({ block, childType, min }) => {
+      editor.insertBlocks([{ ...block, id: "container" }], "p-1", "after");
+      const children = editor.getBlock("container")!.children;
+      expect(children.map((child) => child.type)).toEqual(
+        Array(min).fill(childType),
+      );
+      for (const child of children) {
+        expect(child.id).toBeTruthy();
+        expect(editor.getBlock(child.id)).toBeDefined();
+      }
+    },
+  );
 
   it("does not re-fill a container round-tripped through the document", () => {
     editor.insertBlocks([{ type: "callout", id: "c-0" }], "p-1", "after");
@@ -79,34 +85,6 @@ describe("children insertion & filling", () => {
     );
   });
 
-  // Regression: `children: []` was taken at face value, building a node below
-  // `min: 1`, and `insertBlocks` threw a raw
-  // `Invalid content for node callout: <>` from its `node.check()`.
-  it("fills an explicitly empty `children` array up to `min`", () => {
-    expect(() =>
-      editor.insertBlocks(
-        [{ type: "callout", id: "c-0", children: [] }],
-        "p-1",
-        "after",
-      ),
-    ).not.toThrow();
-
-    const callout = editor.getBlock("c-0")!;
-    expect(callout.children).toHaveLength(1);
-    expect(callout.children[0].type).toBe("paragraph");
-    expect(callout.children[0].id).toBeTruthy();
-  });
-
-  it("fills a container with a higher `min` up to it", () => {
-    editor.insertBlocks([{ type: "pair", id: "s-0" }], "p-1", "after");
-
-    const pair = editor.getBlock("s-0")!;
-    expect(pair.children).toHaveLength(2);
-    expect(pair.children.every((child) => child.type === "paragraph")).toBe(
-      true,
-    );
-  });
-
   it("accepts arbitrary block children, including nested containers", () => {
     editor.insertBlocks(
       [
@@ -339,6 +317,7 @@ describe("children repair", () => {
       "cell-b-p",
       "trailing",
     ]);
+    expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
   });
 
   // An emptied child of the container is dropped even when the container
@@ -382,45 +361,6 @@ describe("children repair", () => {
     const grid = editor.getBlock("g-0")!;
     expect(grid.children.map((cell) => cell.id)).toEqual(["cell-a", "cell-b"]);
   });
-
-  it("drops a namedOnly child emptied past its own minimum", () => {
-    editor.replaceBlocks(editor.document, [
-      {
-        type: "grid",
-        id: "g-0",
-        children: [
-          {
-            type: "gridCell",
-            id: "cell-a",
-            children: [
-              { id: "cell-a-p", type: "paragraph", content: "A" },
-              { id: "cell-a-extra", type: "paragraph", content: "A2" },
-            ],
-          },
-          {
-            type: "gridCell",
-            id: "cell-b",
-            children: [{ id: "cell-b-p", type: "paragraph", content: "B" }],
-          },
-        ],
-      },
-      { id: "trailing", type: "paragraph", content: "" },
-    ]);
-
-    // Removing both of cell A's blocks leaves the cell with no children,
-    // which its `min: 1` forbids. The cell only exists inside the grid, so
-    // the grid's repair drops it — and with one cell left, the grid itself
-    // unwraps into that cell's blocks.
-    editor.removeBlocks(["cell-a-extra"]);
-    editor.removeBlocks(["cell-a-p"]);
-
-    expect(editor.getBlock("g-0")).toBeUndefined();
-    expect(editor.document.map((block) => block.id)).toEqual([
-      "cell-b-p",
-      "trailing",
-    ]);
-    expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
-  });
 });
 
 describe("repair edge cases", () => {
@@ -565,22 +505,6 @@ describe("children selection", () => {
   });
 });
 
-describe("empty container insertion", () => {
-  // A container with a `min` above one and a restricted allow list used to
-  // build a schema-invalid node when inserted without children, so
-  // `node.check()` (run before the repair pass) threw a raw RangeError
-  // instead of inserting.
-  it("inserting a container without children does not throw", () => {
-    editor.replaceBlocks(editor.document, [
-      { id: "p-0", type: "paragraph", content: "Paragraph 0" },
-    ]);
-
-    expect(() =>
-      editor.insertBlocks([{ type: "grid" }] as any, "p-0", "after"),
-    ).not.toThrow();
-  });
-});
-
 // Every mutation that can empty a container records its ancestors with
 // `getAncestorContainers` and hands them to `fixContainersById`, which repairs
 // them deepest-first. Removing a block therefore repairs the whole chain it

packages/core/src/api/blockManipulation/containers/titledBlocks.test.ts

@@ -304,20 +304,6 @@ describe("blocks that declare no children are untouched", () => {
     editor._tiptapEditor.destroy();
   });
 
-  it("a titled block round-trips through HTML, keeping title and body", () => {
-    // Dragging a block, and copying one, both go through this: a titled block
-    // that serialized like a container would come back as a paragraph.
-    const editor = editorWith(withAlert());
-
-    const html = editor.blocksToFullHTML(editor.document as any);
-    const parsed = editor.tryParseHTMLToBlocks(html);
-
-    expect(shape(parsed)).toBe(
-      'paragraph"Before", alert"Title"[paragraph"One", paragraph"Two"], paragraph"After"',
-    );
-    editor._tiptapEditor.destroy();
-  });
-
   it("survives the clipboard round-trip that copy and drag use", () => {
     // Dragging a block inside the editor re-parses it from the HTML
     // ProseMirror serializes the dragged slice to, so a titled block whose

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

@@ -229,10 +229,11 @@ function serializeBlock<
 
   const blockImplementation = editor.blockImplementations[block.type as any]
     .implementation as BlockImplementation;
+  const blockWithDefaults = { ...block, props, children: block.children ?? [] };
   const ret =
     blockImplementation.toExternalHTML?.call(
       {},
-      { ...block, props } as any,
+      blockWithDefaults as any,
       editor as any,
       {
         nestingLevel,
@@ -241,7 +242,7 @@ function serializeBlock<
     renderBlockToDOM(
       blockImplementation,
       editor.schema.blockSchema[block.type as any] as any,
-      { ...block, props },
+      blockWithDefaults,
       editor,
       {},
     );

packages/core/src/api/getBlockInfoFromPos.ts

@@ -610,18 +610,14 @@ export function getInsertionPos(
  * an empty container.
  */
 export function getFirstLeafBlock(info: BlockInfo): BlockInfo | null {
-  if (info.hasContent) {
-    // Not a container: the block is its own first leaf.
-    return info;
-  }
-  const children = info.children;
-  const firstChild = children.node.firstChild;
-  if (!firstChild) {
-    return null;
+  while (!info.hasContent) {
+    const { node, childrenStart } = info.children;
+    if (!node.firstChild) {
+      return null;
+    }
+    info = getBlockInfoFromNode(node.firstChild, childrenStart);
   }
-  return getFirstLeafBlock(
-    getBlockInfoFromNode(firstChild, children.childrenStart),
-  );
+  return info;
 }
 
 /**