Merge branch 'main' into pnpm-11

Author: nperez0111

CHANGELOG.md

@@ -1,3 +1,63 @@
+## 0.51.2 (2026-05-20)
+
+### 🩹 Fixes
+
+- color picker icons (BLO-1189) ([#2762](https://github.com/TypeCellOS/BlockNote/pull/2762))
+
+### ❤️ Thank You
+
+- Matthew Lipski @matthewlipski
+
+## 0.51.1 (2026-05-18)
+
+### 🩹 Fixes
+
+- backslash newlines when copying from a code block ([#2709](https://github.com/TypeCellOS/BlockNote/pull/2709))
+
+### ❤️ Thank You
+
+- Claude Opus 4.7 (1M context)
+- Nick Perez
+
+## 0.51.0 (2026-05-14)
+
+### 🚀 Features
+
+- Trailing block extension rewrite ([#2733](https://github.com/TypeCellOS/BlockNote/pull/2733))
+- **markdown:** replace unified.js with custom markdown parser/serializer ([#2624](https://github.com/TypeCellOS/BlockNote/pull/2624))
+- **react:** configurable portal targets for floating UI ([#2729](https://github.com/TypeCellOS/BlockNote/pull/2729), [#2692](https://github.com/TypeCellOS/BlockNote/issues/2692))
+
+### 🩹 Fixes
+
+- Pasting plain text from VSCode (BLO-366) ([#2713](https://github.com/TypeCellOS/BlockNote/pull/2713))
+- Parse new lines in `text/plain` as line breaks (BLO-1170) ([#2712](https://github.com/TypeCellOS/BlockNote/pull/2712))
+- Code block PDF export (BLO-987) ([#2725](https://github.com/TypeCellOS/BlockNote/pull/2725))
+- Formatting toolbar opening when inserting file block with `trailingBlock: false` (BLO-860) ([#2704](https://github.com/TypeCellOS/BlockNote/pull/2704))
+- numbered list item decorations missed on initial render ([#2734](https://github.com/TypeCellOS/BlockNote/pull/2734))
+- flicker-free mobile formatting toolbar via CSS custom properties ([#2617](https://github.com/TypeCellOS/BlockNote/pull/2617), [#2616](https://github.com/TypeCellOS/BlockNote/issues/2616))
+- add `bn-thread-orphaned` CSS class to distinguish orphaned threads ([#2737](https://github.com/TypeCellOS/BlockNote/pull/2737), [#2735](https://github.com/TypeCellOS/BlockNote/issues/2735))
+- set width attribute on image and video elements in editor render ([#2740](https://github.com/TypeCellOS/BlockNote/pull/2740), [#2726](https://github.com/TypeCellOS/BlockNote/issues/2726))
+- **a11y:** use figure/figcaption for media block captions ([#2717](https://github.com/TypeCellOS/BlockNote/pull/2717))
+- **ai:** loosen serialization of blocks in columns ([#2716](https://github.com/TypeCellOS/BlockNote/pull/2716), [#2718](https://github.com/TypeCellOS/BlockNote/pull/2718))
+- **core:** trigger codeblock input rule on Enter and place cursor inside ([#2686](https://github.com/TypeCellOS/BlockNote/pull/2686))
+- **core:** preserve list item type when pasting into empty list items ([#2722](https://github.com/TypeCellOS/BlockNote/pull/2722), [#2330](https://github.com/TypeCellOS/BlockNote/issues/2330))
+- **core:** unmount editors in transformPasted tests to prevent unhandled error ([e62880b21](https://github.com/TypeCellOS/BlockNote/commit/e62880b21))
+- **drag-n-drop:** support PDF block drag & drop (BLO-893) ([#2714](https://github.com/TypeCellOS/BlockNote/pull/2714))
+- **i18:** improve french translation for empty toggle list ([#2721](https://github.com/TypeCellOS/BlockNote/pull/2721))
+- **markdown:** emit tight lists when serializing blocks to markdown ([#2715](https://github.com/TypeCellOS/BlockNote/pull/2715))
+- **markdown:** skip placeholder text for empty files ([#434](https://github.com/TypeCellOS/BlockNote/pull/434), [#2719](https://github.com/TypeCellOS/BlockNote/pull/2719))
+- **markdown:** stable round-trip for tables, captions, and audio ([#2720](https://github.com/TypeCellOS/BlockNote/pull/2720))
+- **tests:** stabilize webkit keyboard handler tests with programmatic cursor positioning ([#2746](https://github.com/TypeCellOS/BlockNote/pull/2746))
+
+### ❤️ Thank You
+
+- Cyril G
+- Manuel Raynaud @lunika
+- Matthew Lipski @matthewlipski
+- Movm
+- Nick Perez
+- Nick the Sick @nperez0111
+
 ## 0.50.0 (2026-05-04)
 
 ### 🚀 Features

docs/content/docs/react/components/index.mdx

@@ -14,3 +14,23 @@ BlockNote includes a number of UI Components (like menus and toolbars) that can
   {/* - [Image Toolbar](/docs/react/components/image-toolbar) */}
 
 <CardTable path="/react/components" />
+
+## Configuring Portal Targets
+
+By default, all floating UI elements (toolbars, menus, table handles, etc.) portal into the editor's `bn-container` so they stay scoped to the editor. If your layout needs them to escape — e.g. an `overflow: hidden` ancestor that would clip large dropdowns, or a host modal with its own stacking context — pass a `portalElements` prop to `BlockNoteView`:
+
+```tsx
+<BlockNoteView
+  editor={editor}
+  portalElements={{
+    // Global default for any element not listed below.
+    default: document.body,
+    // Per-element overrides. Values can be HTMLElement, a CSS selector, or null (= document.body).
+    tableHandles: ".bn-container",
+  }}
+/>
+```
+
+Keys mirror the default UI flags (`formattingToolbar`, `linkToolbar`, `slashMenu`, `emojiPicker`, `sideMenu`, `filePanel`, `tableHandles`, `comments`). Manually-mounted Controllers also accept a `portalElement` prop that takes precedence over the map. See the [Portal Targets example](/examples/ui-components/portal-elements).
+
+Note: changing `portalElements.default` after mount requires remounting the editor (`editor.mount()` consults it once); per-element keys update reactively.

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

@@ -252,18 +252,26 @@ editor.replaceBlocks(
 #### Reordering Blocks
 
 ```typescript
-moveBlocksUp(): void
-moveBlocksDown(): void
+moveBlocksUp(blockIdentifier?: BlockIdentifier): void
+moveBlocksDown(blockIdentifier?: BlockIdentifier): void
 ```
 
-Moves the currently selected blocks up or down in the document.
+Moves the currently selected blocks up or down in the document. If a
+`blockIdentifier` is provided, that block is moved instead of the selection,
+and the selection is left unchanged.
 
 ```typescript
 // Move selected blocks up
 editor.moveBlocksUp();
 
 // Move selected blocks down
 editor.moveBlocksDown();
+
+// Move a specific block up, without changing the selection
+editor.moveBlocksUp("block-123");
+
+// Move a specific block down, without changing the selection
+editor.moveBlocksDown("block-123");
 ```
 
 ### Nesting Blocks

examples/01-basic/17-no-trailing-block/package.json

@@ -16,9 +16,8 @@
     "@blocknote/mantine": "latest",
     "@blocknote/react": "latest",
     "@blocknote/shadcn": "latest",
-    "@mantine/core": "^8.3.11",
-    "@mantine/hooks": "^8.3.11",
-    "@mantine/utils": "^6.0.22",
+    "@mantine/core": "^9.0.2",
+    "@mantine/hooks": "^9.0.2",
     "react": "^19.2.3",
     "react-dom": "^19.2.3"
   },

examples/03-ui-components/20-portal-elements/.bnexample.json

@@ -0,0 +1,6 @@
+{
+  "playground": true,
+  "docs": true,
+  "author": "nperez0111",
+  "tags": ["UI Components", "Advanced"]
+}

examples/03-ui-components/20-portal-elements/README.md

@@ -0,0 +1,16 @@
+# Configuring Portal Targets
+
+By default, BlockNote's floating UI elements (formatting toolbar, slash menu, table handles, etc.) mount inside the editor's `bn-container`. The `portalElements` prop on `BlockNoteView` lets you change that — globally via `default`, or per element by key.
+
+This example renders two editors side-by-side, both wrapped in a small `overflow: hidden` container. The left editor uses the default — the slash menu is clipped by the editor's bounds. The right editor passes `portalElements={{ default: document.body }}` so floating UI escapes the wrapper and renders fully.
+
+```tsx
+<BlockNoteView
+  editor={editor}
+  portalElements={{ default: document.body }}
+/>
+```
+
+**Relevant Docs:**
+
+- [UI Components](/docs/react/components)

examples/03-ui-components/20-portal-elements/index.html

@@ -0,0 +1,14 @@
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Configuring Portal Targets</title>
+    <script>
+      <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

examples/03-ui-components/20-portal-elements/main.tsx

@@ -0,0 +1,11 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./src/App.jsx";
+
+const root = createRoot(document.getElementById("root")!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

examples/03-ui-components/20-portal-elements/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@blocknote/example-ui-components-portal-elements",
+  "description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+  "type": "module",
+  "private": true,
+  "version": "0.12.4",
+  "scripts": {
+    "start": "vite",
+    "dev": "vite",
+    "build:prod": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@blocknote/ariakit": "latest",
+    "@blocknote/core": "latest",
+    "@blocknote/mantine": "latest",
+    "@blocknote/react": "latest",
+    "@blocknote/shadcn": "latest",
+    "@mantine/core": "^9.0.2",
+    "@mantine/hooks": "^9.0.2",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "vite": "^8.0.8"
+  }
+}

examples/03-ui-components/20-portal-elements/src/App.tsx

@@ -0,0 +1,58 @@
+import "@blocknote/core/fonts/inter.css";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import { useCreateBlockNote, type PortalElementsMap } from "@blocknote/react";
+
+import "./styles.css";
+
+const initialContent = [
+  {
+    type: "paragraph" as const,
+    content: "Click in this editor and press / to open the slash menu.",
+  },
+  {
+    type: "paragraph" as const,
+    content:
+      "Notice whether the menu fits inside the box or escapes it.",
+  },
+  {
+    type: "paragraph" as const,
+  },
+];
+
+function PortalDemoEditor({
+  label,
+  description,
+  portalElements,
+}: {
+  label: string;
+  description: string;
+  portalElements?: PortalElementsMap;
+}) {
+  const editor = useCreateBlockNote({ initialContent });
+  return (
+    <div className="view-wrapper">
+      <div className="view-label">{label}</div>
+      <div className="view-description">{description}</div>
+      <div className="view">
+        <BlockNoteView editor={editor} portalElements={portalElements} />
+      </div>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <div className="views">
+      <PortalDemoEditor
+        label="Default — clipped"
+        description="No portalElements prop. Floating UI mounts inside .bn-container — the slash menu is clipped by the editor's bounds."
+      />
+      <PortalDemoEditor
+        label="portalElements={{ default: document.body }} — escapes"
+        description="Every floating UI element escapes the editor container and renders directly under <body>."
+        portalElements={{ default: document.body }}
+      />
+    </div>
+  );
+}