fix: multi-column UX - trailing blocks in columns, hover borders, drop cursor left edge

Fixes #2820.

- Trailing block widgets are now also rendered in columns, filling the
  empty space below a column's last block. Clicking one appends a block
  inside that column, instead of blocks silently landing below the
  multi-column area.
- Hovering a column list shows light separators between its columns, and
  the resize border now actually appears when nearing a column boundary
  (it was suppressed by a side menu check that was almost always true).
  The side menu is no longer stretched next to headings (which blocked
  the resize handle) - it keeps its natural size and is positioned with
  a floating-ui offset instead.
- The drop cursor only treats a drop as a "left edge" drop when the
  cursor is actually left of the block, instead of within a margin
  inside the block.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: YousefED

packages/core/src/editor/Block.css

@@ -723,6 +723,46 @@ NESTED BLOCKS
   padding: 12px 20px;
   /* scroll if we overflow, for example when tables or images are in the column */
   overflow-x: auto;
+  /* Lets the trailing block widget grow to fill the column's leftover height
+  when a sibling column is taller. */
+  display: flex;
+  flex-direction: column;
+}
+
+/* Shows separators between a column list's columns while the mouse is over
+it. This clarifies where each column (and its clickable empty space) ends.
+The class is managed by the multi-column package's column resize plugin. The
+transition delay stops the separators from flashing in when the mouse just
+passes through the column list. */
+.bn-editor[contenteditable="true"]
+  .bn-column-list-hovered
+  > .bn-block-column:not(:last-child) {
+  box-shadow: 4px 0 0 #eee;
+  transition: box-shadow 0.2s ease 0.2s;
+}
+
+/* The border between two columns when the cursor is near their boundary or
+they're being resized, rendered on the boundary's left column. The class is
+managed by the multi-column package's column resize plugin. Unlike the
+lighter separators, it appears instantly, so the delayed transition is
+overridden. */
+.bn-editor[contenteditable="true"]
+  .bn-column-list-hovered
+  > .bn-block-column.bn-column-resize-border {
+  box-shadow: 4px 0 0 #ccc;
+  cursor: col-resize;
+  transition: none;
+}
+
+.bn-editor[contenteditable="true"]
+  .bn-block-column.bn-column-resize-border
+  + .bn-block-column {
+  cursor: col-resize;
+}
+
+.bn-block-column > .bn-trailing-block {
+  height: auto;
+  flex-grow: 1;
 }
 
 .bn-block-column:first-child {

packages/core/src/extensions/SideMenu/SideMenu.ts

@@ -756,6 +756,14 @@ export const SideMenuExtension = createExtension(({ editor }) => {
       editor.blur();
     },
 
+    /**
+     * Whether the side menu is currently frozen (e.g. because the drag handle
+     * menu is open).
+     */
+    get menuFrozen() {
+      return view!.menuFrozen;
+    },
+
     /**
      * Freezes the side menu. When frozen, the side menu will stay
      * attached to the same block regardless of which block is hovered by the

packages/core/src/extensions/TrailingNode/TrailingNode.ts

@@ -13,15 +13,10 @@ import {
 
 const PLUGIN_KEY = new PluginKey<DecorationSet>("trailingNode");
 
-// Skip the widget when the editor isn't editable, or when the document already
-// ends with an empty paragraph block (since the user can just type into it).
-function shouldShowTrailingWidget(doc: PMNode, isEditable: boolean): boolean {
-  if (!isEditable) {
-    return false;
-  }
-
-  const rootGroup = doc.lastChild;
-  const lastBlock = rootGroup?.lastChild;
+// Skip the widget when the container already ends with an empty paragraph
+// block (since the user can just type into it).
+function containerNeedsTrailingWidget(container: PMNode): boolean {
+  const lastBlock = container.lastChild;
   const lastContent = lastBlock?.firstChild;
 
   return !(
@@ -31,12 +26,48 @@ function shouldShowTrailingWidget(doc: PMNode, isEditable: boolean): boolean {
   );
 }
 
+// Returns the position at the end of each container that should render a
+// trailing widget: the root blockGroup, and columns from the multi-column
+// package. Nested blockGroups (a block's children) are excluded, as they have
+// no empty space below them for a widget to occupy.
+function getTrailingWidgetPositions(doc: PMNode): number[] {
+  // When the schema has no columns, the root blockGroup is the only possible
+  // container, so traversing the doc to find others can be skipped.
+  if (!doc.type.schema.nodes["column"]) {
+    const rootGroup = doc.lastChild;
+    return rootGroup && containerNeedsTrailingWidget(rootGroup)
+      ? [doc.content.size - 1]
+      : [];
+  }
+
+  const positions: number[] = [];
+
+  doc.descendants((node, pos, parent) => {
+    if (node.isTextblock) {
+      return false;
+    }
+
+    const isContainer =
+      node.type.name === "column" ||
+      (node.type.name === "blockGroup" && parent?.type.name === "doc");
+
+    if (isContainer && containerNeedsTrailingWidget(node)) {
+      positions.push(pos + node.nodeSize - 1);
+    }
+
+    return true;
+  });
+
+  return positions;
+}
+
 /**
  * Renders a fake trailing block as a widget decoration after the last block of
- * the document. Clicking it inserts a real trailing block and moves the
- * selection into it. This way the trailing block is not part of the document
- * content, so it doesn't appear when the editor is read-only or when the
- * content is exported.
+ * the document, as well as of any other container that blocks can be appended
+ * to (e.g. columns). Clicking it inserts a real trailing block in the
+ * container and moves the selection into it. This way the trailing block is
+ * not part of the document content, so it doesn't appear when the editor is
+ * read-only or when the content is exported.
  */
 export const TrailingNodeExtension = createExtension(
   ({ editor }: ExtensionOptions) => {
@@ -52,47 +83,78 @@ export const TrailingNodeExtension = createExtension(
             // based on this click.
             event.preventDefault();
 
+            const view = editor.prosemirrorView;
+            if (!view) {
+              return;
+            }
+
+            // The widget may have been remapped since it was created, so its
+            // container is resolved from its current DOM position instead of
+            // captured up front.
+            const container = view.state.doc.resolve(
+              view.posAtDOM(el, 0),
+            ).parent;
+            const lastBlockId = container.lastChild?.attrs["id"];
+            if (!lastBlockId) {
+              return;
+            }
+
             editor.transact((tr) => {
               const [insertedBlock] = editor.insertBlocks(
                 [{ type: "paragraph" }],
-                editor.document[editor.document.length - 1],
+                lastBlockId,
                 "after",
               );
               editor.setTextCursorPosition(insertedBlock, "start");
               tr.scrollIntoView();
             });
 
-            editor.prosemirrorView?.focus();
+            view.focus();
           });
           return el;
         },
         { side: 1 },
       );
     }
 
-    // Maps the existing DecorationSet through the transaction, then
-    // incrementally adds or removes the widget only if the show/hide state
-    // crossed over. The underlying Decoration (and its rendered DOM) stays
-    // reference-stable across transactions.
+    // Maps the existing DecorationSet through the transaction, then diffs it
+    // against the containers that should currently show a widget, only adding
+    // and removing where the two differ. Decorations (and their rendered DOM)
+    // stay reference-stable across transactions for unchanged containers.
     function nextDecorationSet(
       tr: Transaction,
       oldSet: DecorationSet,
       isEditable: boolean,
     ): DecorationSet {
       const mapped = oldSet.map(tr.mapping, tr.doc);
-      const existing = mapped.find();
-      const wasShowing = existing.length > 0;
-      const shouldShow = shouldShowTrailingWidget(tr.doc, isEditable);
+      const desiredPositions = new Set(
+        isEditable ? getTrailingWidgetPositions(tr.doc) : [],
+      );
+
+      const keptPositions = new Set<number>();
+      const stale: Decoration[] = [];
+      for (const decoration of mapped.find()) {
+        if (
+          desiredPositions.has(decoration.from) &&
+          !keptPositions.has(decoration.from)
+        ) {
+          keptPositions.add(decoration.from);
+        } else {
+          stale.push(decoration);
+        }
+      }
+      const missing = [...desiredPositions].filter(
+        (pos) => !keptPositions.has(pos),
+      );
 
-      if (wasShowing === shouldShow) {
-        return mapped;
+      let next = mapped;
+      if (stale.length > 0) {
+        next = next.remove(stale);
       }
-      if (wasShowing) {
-        return mapped.remove(existing);
+      if (missing.length > 0) {
+        next = next.add(tr.doc, missing.map(createTrailingWidget));
       }
-      return mapped.add(tr.doc, [
-        createTrailingWidget(tr.doc.content.size - 1),
-      ]);
+      return next;
     }
 
     return {
@@ -133,8 +195,9 @@ export const TrailingNodeExtension = createExtension(
           props: {
             decorations: (state) => PLUGIN_KEY.getState(state),
             // Prevents ProseMirror from trying to move the selection into the
-            // trailing block, which causes the text caret to flicker in it
-            // before returning to its previous position.
+            // trailing block at the end of the document, which causes the text
+            // caret to flicker in it before returning to its previous
+            // position.
             handleKeyDown: (view, event) => {
               if (event.key !== "ArrowRight" && event.key !== "ArrowDown") {
                 return false;
@@ -150,8 +213,11 @@ export const TrailingNodeExtension = createExtension(
                 return false;
               }
 
+              const rootGroup = view.state.doc.lastChild;
               if (
-                !shouldShowTrailingWidget(view.state.doc, editor.isEditable)
+                !editor.isEditable ||
+                !rootGroup ||
+                !containerNeedsTrailingWidget(rootGroup)
               ) {
                 return false;
               }

packages/react/src/components/SideMenu/SideMenu.tsx

@@ -1,9 +1,6 @@
-import { SideMenuExtension } from "@blocknote/core/extensions";
-import { ReactNode, useMemo } from "react";
+import { ReactNode } from "react";
 
 import { useComponentsContext } from "../../editor/ComponentsContext.js";
-import { useBlockNoteEditor } from "../../hooks/useBlockNoteEditor.js";
-import { useExtensionState } from "../../hooks/useExtension.js";
 import { AddBlockButton } from "./DefaultButtons/AddBlockButton.js";
 import { DragHandleButton } from "./DefaultButtons/DragHandleButton.js";
 import { SideMenuProps } from "./SideMenuProps.js";
@@ -20,41 +17,8 @@ import { SideMenuProps } from "./SideMenuProps.js";
 export const SideMenu = (props: SideMenuProps & { children?: ReactNode }) => {
   const Components = useComponentsContext()!;
 
-  const editor = useBlockNoteEditor<any, any, any>();
-
-  const block = useExtensionState(SideMenuExtension, {
-    editor,
-    selector: (state) => state?.block,
-  });
-
-  const dataAttributes = useMemo(() => {
-    if (block === undefined) {
-      return {};
-    }
-
-    const attrs: Record<string, string> = {
-      "data-block-type": block.type,
-    };
-
-    if (block.type === "heading") {
-      attrs["data-level"] = (block.props as any).level.toString();
-    }
-
-    if (
-      editor.schema.blockSpecs[block.type].implementation.meta?.fileBlockAccept
-    ) {
-      if (block.props.url) {
-        attrs["data-url"] = "true";
-      } else {
-        attrs["data-url"] = "false";
-      }
-    }
-
-    return attrs;
-  }, [block, editor.schema.blockSpecs]);
-
   return (
-    <Components.SideMenu.Root className={"bn-side-menu"} {...dataAttributes}>
+    <Components.SideMenu.Root className={"bn-side-menu"}>
       {props.children || (
         <>
           <AddBlockButton />

packages/react/src/components/SideMenu/SideMenuController.tsx

@@ -1,5 +1,6 @@
+import { Block, BlockNoteEditor } from "@blocknote/core";
 import { SideMenuExtension } from "@blocknote/core/extensions";
-import { autoUpdate, ReferenceElement } from "@floating-ui/react";
+import { autoUpdate, offset, ReferenceElement } from "@floating-ui/react";
 import { FC, useCallback, useMemo } from "react";
 
 import { useBlockNoteEditor } from "../../hooks/useBlockNoteEditor.js";
@@ -9,6 +10,50 @@ import { FloatingUIOptions } from "../Popovers/FloatingUIOptions.js";
 import { SideMenu } from "./SideMenu.js";
 import { SideMenuProps } from "./SideMenuProps.js";
 
+// Returns the vertical offset of the side menu for the given block. Blocks
+// whose first line is taller than the side menu need the menu shifted down to
+// stay vertically centered on that line. This is done with a position offset
+// instead of stretching the menu element to the first line's height, as the
+// taller (invisible) element would block mouse interactions with content
+// rendered next to the block, e.g. the column resize borders.
+function getBlockOffset(
+  editor: BlockNoteEditor<any, any, any>,
+  block: Block<any, any, any>,
+): number {
+  if (block.type === "heading") {
+    switch (block.props.level) {
+      case 1:
+        return 39;
+      case 2:
+        return 27;
+      case 3:
+        return 18.5;
+      default:
+        return 0;
+    }
+  }
+
+  // File blocks without a URL all render the same "Add file" button,
+  // regardless of their type.
+  if (
+    editor.schema.blockSpecs[block.type]?.implementation.meta
+      ?.fileBlockAccept &&
+    !block.props.url
+  ) {
+    return 12;
+  }
+
+  if (block.type === "file") {
+    return 4;
+  }
+
+  if (block.type === "audio" || block.type === "table") {
+    return 15;
+  }
+
+  return 0;
+}
+
 export const SideMenuController = (props: {
   sideMenu?: FC<SideMenuProps>;
   floatingUIOptions?: Partial<FloatingUIOptions>;
@@ -71,6 +116,13 @@ export const SideMenuController = (props: {
       useFloatingOptions: {
         open: show,
         placement: "left-start",
+        // Vertically centers the menu on the block's first line. On the
+        // "left-start" placement, the cross axis is the vertical one.
+        middleware: [
+          offset({
+            crossAxis: block ? getBlockOffset(editor, block) : 0,
+          }),
+        ],
         whileElementsMounted,
         ...props.floatingUIOptions?.useFloatingOptions,
       },
@@ -89,7 +141,7 @@ export const SideMenuController = (props: {
         ...props.floatingUIOptions?.elementProps,
       },
     }),
-    [props.floatingUIOptions, show, whileElementsMounted],
+    [props.floatingUIOptions, show, block, editor, whileElementsMounted],
   );
 
   const Component = props.sideMenu || SideMenu;