fix(container-blocks): simplify editing and support plain text

Author: nperez0111

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

@@ -56,6 +56,11 @@ type BlockConfig = {
   type: string;
   content: "inline" | "plain" | "none";
   readonly propSchema: PropSchema;
+  children?: {
+    allow: "blocks" | string[];
+    min?: number;
+  };
+  placeable?: "anywhere" | "namedOnly";
 };
 ```
 
@@ -73,11 +78,13 @@ type BlockConfig = {
 </Callout>
 
 <Callout type="info">
-  _A `content: "none"` block can also hold other blocks as its body by
-  declaring the `children` option. See [Container
+  _Custom blocks can also contain child blocks by declaring the `children`
+  option, with or without editable content of their own. See [Container
   Blocks](/docs/features/custom-schemas/container-blocks)._
 </Callout>
 
+`children?:` Defines which child blocks the block can contain. `placeable?:` Controls where a container block can be used. See [Container Blocks](/docs/features/custom-schemas/container-blocks) for the supported configurations.
+
 `propSchema:` The `PropSchema` specifies the props that the block supports. Block props (properties) are data stored with your Block in the document, and can be used to customize its appearance or behavior.
 
 ```typescript

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

@@ -145,7 +145,7 @@ insertBlocks(
 ): Block[]
 ```
 
-Inserts new blocks relative to an existing block. `"before"` and `"after"` make the new blocks siblings of the reference block; `"first-child"` and `"last-child"` nest them inside it. Returns the inserted blocks. See [Inserting into a container](/docs/features/custom-schemas/container-blocks#inserting-into-a-container).
+Inserts new blocks relative to an existing block. `"before"` and `"after"` make the new blocks siblings of the reference block; `"first-child"` and `"last-child"` nest them inside it. Returns the inserted blocks.
 
 ```typescript
 // Insert a paragraph before an existing block
@@ -173,6 +173,8 @@ editor.insertBlocks(
 );
 ```
 
+For [container blocks](/docs/features/custom-schemas/container-blocks), `"first-child"` inserts at the beginning of the container and `"last-child"` inserts at the end. Use `"before"` or `"after"` to insert next to the container instead.
+
 ### Updating Blocks
 
 #### Modifying Existing Blocks

docs/content/docs/reference/editor/manipulating-content.mdx

@@ -1,15 +1,21 @@
 import { BlockNoteSchema, defaultBlockSpecs } from "@blocknote/core";
 import {
+  SideMenuExtension,
   filterSuggestionItems,
   insertOrUpdateBlockForSlashMenu,
 } from "@blocknote/core/extensions";
 import "@blocknote/core/fonts/inter.css";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
 import {
+  SideMenu,
+  SideMenuController,
   SuggestionMenuController,
   getDefaultReactSlashMenuItems,
+  useBlockNoteEditor,
   useCreateBlockNote,
+  useEditorState,
+  useExtensionState,
 } from "@blocknote/react";
 import { useEffect, useState } from "react";
 import { RiChatQuoteLine } from "react-icons/ri";
@@ -41,6 +47,30 @@ const insertPanel = (editor: typeof schema.BlockNoteEditor) => ({
 
 type AppBlock = (typeof schema.BlockNoteEditor)["document"][number];
 
+function PanelSideMenu() {
+  const editor = useBlockNoteEditor<
+    typeof schema.blockSchema,
+    typeof schema.inlineContentSchema,
+    typeof schema.styleSchema
+  >();
+  const blockId = useExtensionState(SideMenuExtension, {
+    selector: (state) => state?.block.id,
+  });
+  const isFirstPanelChild = useEditorState({
+    editor,
+    selector: () => {
+      if (!blockId || !editor.getBlock(blockId)) {
+        return false;
+      }
+      const parent = editor.getParentBlock(blockId);
+      return parent?.type === "panel" && parent.children[0]?.id === blockId;
+    },
+  });
+
+  // The first child's gutter is occupied by the panel's flavor button.
+  return isFirstPanelChild ? null : <SideMenu />;
+}
+
 export default function App() {
   const [blocks, setBlocks] = useState<AppBlock[]>([]);
 
@@ -55,6 +85,11 @@ export default function App() {
         type: "panel",
         props: { flavor: "tip" },
         children: [
+          {
+            type: "heading",
+            props: { level: 3 },
+            content: "More than paragraphs",
+          },
           {
             type: "paragraph",
             content: "Panels can hold any block as their body.",
@@ -85,10 +120,12 @@ export default function App() {
         <BlockNoteView
           editor={editor}
           slashMenu={false}
+          sideMenu={false}
           onChange={() => {
             setBlocks(editor.document);
           }}
         >
+          <SideMenuController sideMenu={PanelSideMenu} />
           <SuggestionMenuController
             triggerCharacter={"/"}
             getItems={async (query) => {

examples/06-custom-schema/09-container-block/src/App.tsx

@@ -25,6 +25,9 @@
 }
 
 .panel {
+  /* The default flavor is omitted from the block's serialized attributes. */
+  --panel-accent: #b45309;
+  --panel-bg: #fff7ed;
   display: flex;
   align-items: flex-start;
   gap: 12px;
@@ -36,12 +39,12 @@
 }
 
 .panel[data-flavor="tip"] {
-  --panel-accent: #d97706;
+  --panel-accent: #b45309;
   --panel-bg: #fff7ed;
 }
 
 .panel[data-flavor="info"] {
-  --panel-accent: #507aff;
+  --panel-accent: #365bcc;
   --panel-bg: #e6ebff;
 }
 
@@ -51,23 +54,28 @@
 }
 
 .panel[data-flavor="success"] {
-  --panel-accent: #16a34a;
+  --panel-accent: #15803d;
   --panel-bg: #ecfdf5;
 }
 
+[data-color-scheme="dark"] .panel,
 [data-color-scheme="dark"] .panel[data-flavor="tip"] {
+  --panel-accent: #fbbf24;
   --panel-bg: #432e0e;
 }
 
 [data-color-scheme="dark"] .panel[data-flavor="info"] {
+  --panel-accent: #93b4ff;
   --panel-bg: #1e2a5c;
 }
 
 [data-color-scheme="dark"] .panel[data-flavor="warning"] {
+  --panel-accent: #fca5a5;
   --panel-bg: #4a1212;
 }
 
 [data-color-scheme="dark"] .panel[data-flavor="success"] {
+  --panel-accent: #86efac;
   --panel-bg: #0d3b21;
 }
 
@@ -84,7 +92,12 @@
 }
 
 .panel-icon-button:hover {
-  opacity: 0.75;
+  background-color: var(--bn-colors-hovered-background);
+}
+
+.panel-icon-button:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
 }
 
 .panel-body {

examples/06-custom-schema/09-container-block/src/styles.css

@@ -1,12 +1,45 @@
-import { EditorState } from "prosemirror-state";
+import { Fragment, type Node } from "prosemirror-model";
+import { EditorState, TextSelection } from "prosemirror-state";
 
 import {
+  type BlockInfo,
   getBlockInfoAt,
   getLastDescendantBlockInfo,
   getPrevBlockInfo,
   getParentBlockInfo,
 } from "../../../getBlockInfoFromPos.js";
 
+/** Returns compatible text to append, or undefined when the blocks cannot merge. */
+export function getMergeContent(
+  current: Extract<BlockInfo, { hasContent: true }>,
+  next: Extract<BlockInfo, { hasContent: true }>,
+): Fragment | undefined {
+  const inline =
+    current.contentKind === "inline" && next.contentKind === "inline";
+  const ownedText =
+    current.hasOwnedChildren &&
+    current.content.node.isTextblock &&
+    next.content.node.isTextblock;
+  if (!inline && !ownedText) {
+    return undefined;
+  }
+  if (current.contentKind === "plain") {
+    const type = current.content.node.type;
+    const children: Node[] = [];
+    next.content.node.forEach((child) => {
+      const text =
+        child.type === type.schema.linebreakReplacement
+          ? "\n"
+          : child.textContent;
+      if (text) {
+        children.push(type.schema.text(text, type.allowedMarks(child.marks)));
+      }
+    });
+    return Fragment.from(children);
+  }
+  return next.content.node.content;
+}
+
 /**
  * Merges the block starting at `posBetweenBlocks` into the block visually
  * above it, by deleting the boundary between the two.
@@ -16,9 +49,9 @@ import {
  * i.e. its `BlockInfo`'s `block.beforePos`. The block above is found by walking
  * back from there.
  * @returns A tiptap command that returns `false` (leaving the doc untouched)
- * when the two blocks can't merge: no block above, either side isn't an
- * inline-content block, or the block above is empty (deleting it is handled
- * elsewhere).
+ * when the two blocks can't merge: no compatible text block above, or the
+ * block above is empty (deleting it is handled elsewhere). An owning block
+ * can also merge plain text, dropping formatting that its schema disallows.
  */
 export const mergeBlocksCommand =
   (posBetweenBlocks: number) =>
@@ -51,13 +84,15 @@ export const mergeBlocksCommand =
 
     if (
       !prevBlockInfo.hasContent ||
-      prevBlockInfo.contentKind !== "inline" ||
       prevBlockInfo.isContentEmpty ||
-      !nextBlockInfo.hasContent ||
-      nextBlockInfo.contentKind !== "inline"
+      !nextBlockInfo.hasContent
     ) {
       return false;
     }
+    const content = getMergeContent(prevBlockInfo, nextBlockInfo);
+    if (content === undefined) {
+      return false;
+    }
 
     // Lift children before removing their parent. Tiptap's chainable state
     // returns the shared transaction, so the lift is included in dispatch.
@@ -82,9 +117,20 @@ export const mergeBlocksCommand =
     }
 
     if (dispatch) {
-      dispatch(
-        state.tr.delete(prevBlockInfo.contentEnd, nextBlockInfo.contentStart),
-      );
+      if (content !== nextBlockInfo.content.node.content) {
+        state.tr
+          .replaceWith(
+            prevBlockInfo.contentEnd,
+            nextBlockInfo.contentEnd,
+            content,
+          )
+          .setSelection(
+            TextSelection.create(state.tr.doc, prevBlockInfo.contentEnd),
+          );
+      } else {
+        state.tr.delete(prevBlockInfo.contentEnd, nextBlockInfo.contentStart);
+      }
+      dispatch(state.tr);
     }
 
     return true;

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

@@ -382,32 +382,33 @@ describe("repair edge cases", () => {
     },
   )();
 
-  const trayEditor = BlockNoteEditor.create({
-    schema: containerSchema.extend({
-      blockSpecs: { tray: Tray },
-    }),
-  }) as BlockNoteEditor<any, any, any>;
-
   it("keeps a `min: 0` container with zero children", () => {
-    trayEditor.replaceBlocks(trayEditor.document, [
-      {
-        type: "tray",
-        id: "t-0",
-        children: [{ id: "t-p-0", type: "paragraph", content: "" }],
-      },
-      { id: "trailing", type: "paragraph", content: "" },
-    ]);
-
-    // Removing its only (empty) child leaves zero children, which `min: 0`
-    // allows: the tray stays instead of dissolving, and nothing is padded
-    // back.
-    trayEditor.removeBlocks(["t-p-0"]);
-
-    expect(trayEditor.getBlock("t-0")).toBeDefined();
-    expect(trayEditor.getBlock("t-0")!.children).toHaveLength(0);
-    expect(() => trayEditor.prosemirrorState.doc.check()).not.toThrow();
-
-    trayEditor._tiptapEditor.destroy();
+    const trayEditor = BlockNoteEditor.create({
+      schema: containerSchema.extend({
+        blockSpecs: { tray: Tray },
+      }),
+    });
+    try {
+      trayEditor.replaceBlocks(trayEditor.document, [
+        {
+          type: "tray",
+          id: "t-0",
+          children: [{ id: "t-p-0", type: "paragraph", content: "" }],
+        },
+        { id: "trailing", type: "paragraph", content: "" },
+      ]);
+
+      // Removing its only (empty) child leaves zero children, which `min: 0`
+      // allows: the tray stays instead of dissolving, and nothing is padded
+      // back.
+      trayEditor.removeBlocks(["t-p-0"]);
+
+      expect(trayEditor.getBlock("t-0")).toBeDefined();
+      expect(trayEditor.getBlock("t-0")!.children).toHaveLength(0);
+      expect(() => trayEditor.prosemirrorState.doc.check()).not.toThrow();
+    } finally {
+      trayEditor._tiptapEditor.destroy();
+    }
   });
 
   it("keeps emptied regular blocks when the container survives", () => {