diff --git a/.claude/skills/testing-skill/SKILL.md b/.claude/skills/testing-skill/SKILL.md
index 6ff6af56a9..969d4b0375 100644
--- a/.claude/skills/testing-skill/SKILL.md
+++ b/.claude/skills/testing-skill/SKILL.md
@@ -21,6 +21,21 @@ In most cases, once a feature, bug fix, or other modification has been written,
`packages/*/src/**/*.browser.test.{ts,tsx}`: Unit tests for browser-only implementations (e.g. canvas or DOM-dependent code) live next to the code they test, with a `.browser.test` suffix. They run as part of the browser suite in Docker (the `tests` package's browser config includes them); the packages' own node-mode vitest configs exclude them. Use this when the unit under test genuinely needs a real browser — everything else should be a plain node unit test.
+### Choosing between `/tests/src/unit` and a colocated test
+
+Both are unit tests, so "is this a unit or an integration test" is the wrong question. Pick by harness:
+
+- `/tests/src/unit` exists to fan a **single case** out across many output formats (BlockNote HTML, external HTML, Markdown, PM nodes) and across clipboard and selection behaviour, all against the one shared `testSchema`. You contribute a case by appending to a `*TestInstances.ts` array, not by adding a test file. If the schema needs a new block type to express the case, add it to `tests/src/unit/core/testSchema.ts` (or `react/testSchema.tsx`).
+- A colocated test in `packages/*/src` pins the behaviour of one function or module, and is free to declare its own schema fixture. Use it when the assertion is about internal shape (node structure, transaction steps, return values) rather than about a serialization format.
+
+If a case belongs in both, prefer `/tests/src/unit`: one entry there produces coverage in every format at once.
+
+### Naming a colocated test file
+
+- When the suite covers one source file, mirror its name: `blockToNode.ts` gets `blockToNode.test.ts`.
+- When it covers a behaviour spanning several modules, name it after the behaviour and put it in the directory that owns that behaviour: `containers/containers.test.ts`, `commands/insertBlocks/insertPlacement.test.ts`. This is common and fine; roughly a third of colocated test files have no same-named source file.
+- Don't name a file after a schema or config feature (`contentContainers.test.ts`). Those names go stale when the feature is renamed or dropped, and the file is then stranded under a name that no longer maps to anything. Name it after the code that implements the feature instead.
+
### End-to-End Tests
`tests/src/end-to-end`: Tests that need a real browser and span multiple packages go here — chiefly tests which interact with the editor UI or simulate user interaction, but also browser integration tests that exercise complete flows without interaction (e.g. exporting a full document, static rendering). New subdirectories can be added if the functionality being tested is not covered by any of the existing ones. Important note about existing E2E tests - many are written poorly and should only loosely be used as reference. We want to avoid abstraction layers and `waitForTimeout` as much as possible.
diff --git a/docs/content/docs/features/custom-schemas/container-blocks.mdx b/docs/content/docs/features/custom-schemas/container-blocks.mdx
new file mode 100644
index 0000000000..0d03aace2e
--- /dev/null
+++ b/docs/content/docs/features/custom-schemas/container-blocks.mdx
@@ -0,0 +1,205 @@
+---
+title: Container Blocks
+description: Learn how to create custom blocks that hold other blocks as their body
+---
+
+# Container Blocks
+
+A *container block* is a custom block that holds other blocks as its body, like a Notion-style callout wrapping a paragraph and a code block, or a multi-column layout.
+
+## Declaring a Container Block
+
+Add the `children` option to your block config (created with [`createBlockSpec` or `createReactBlockSpec`](/docs/features/custom-schemas/custom-blocks)). The only required field is `allow`, so the smallest container is:
+
+```typescript
+import { createReactBlockSpec } from "@blocknote/react";
+
+const createCallout = createReactBlockSpec(
+ {
+ type: "callout",
+ propSchema: {},
+ content: "none",
+ // Makes this a container: its body is other blocks.
+ children: { allow: "any" },
+ },
+ {
+ // Child blocks mount into the element you attach `contentRef` to.
+ render: (props) => ,
+ },
+);
+```
+
+`children: { allow: "any" }` accepts any block, requires at least one, and never throws. When a container is created without children, BlockNote fills it with whatever its schema requires.
+
+A container block always declares `content: "none"`: its body is its children. Combining `children` with any other `content` is a schema-creation error. For an editable title or caption, use a string prop rendered as an ``, as the demo below does.
+
+At runtime the contained blocks live on `block.children`, the same field used for indented (nested) blocks. In fact, every regular block behaves as if it were declared with `children: { allow: "any", min: 0 }`; declaring `children` yourself is how you take control of the counts, the allowed types, and the rendering of that same field:
+
+```json
+{
+ "id": "callout-1",
+ "type": "callout",
+ "props": {},
+ "children": [
+ {
+ "id": "para-1",
+ "type": "paragraph",
+ "content": [{ "type": "text", "text": "Hello", "styles": {} }],
+ "children": []
+ }
+ ]
+}
+```
+
+### Where children render
+
+There is only one placement mechanism, and it is the one you already use for inline content. `contentRef` (React) / `contentDOM` (vanilla) marks the block's editable region. What goes in that region depends on the block:
+
+| block | `contentRef` element holds |
+| --- | --- |
+| `content: "inline"`, no `children` | its inline content |
+| `content: "none"` + `children` | its child blocks |
+
+A `content: "none"` block *without* `children` is the only kind with nothing to place, and it's the only kind that isn't offered a `contentRef` at all.
+
+Container blocks own their entire outer DOM. BlockNote doesn't wrap them in the usual block element: whatever element your `render` returns *is* the block's element, and BlockNote stamps the attributes it relies on for parsing and UI positioning onto it (`data-node-type`, `data-id`, and each non-default prop as a `data-*` attribute). You write a plain `
` and `data-flavor="info"` lands on it, in the live editor and in serialized HTML alike.
+
+
+ _The framework wrappers React puts above your element carry `display:
+ contents`, so they contribute no box and your element lays out exactly as if
+ it were the block's root. Selection is mirrored onto it as a `data-selected`
+ attribute, so `[data-selected]` is what you style for the selected state._
+
+
+The demo below puts this together: a callout block that can contain any other blocks. Its title is a regular `` backed by a string prop rather than document content — the pattern to reach for whenever a container needs an editable heading, caption, or label of its own:
+
+
+
+## `children` options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `allow` | (required) | What may appear as a child: `"any"`, `"blocks"`, `"containers"`, or an array of container block types. See [Restricting children](#restricting-children). |
+| `min` / `max` | `1` / unbounded | How many children are allowed. Compiled into the editor schema. |
+| `default` | none | Partial blocks to create the container with when it's inserted without an explicit `children` array, and the source of `"refill"` top-ups. Validated against the rest of the config when the schema is created. See [Defaults and refilling](#defaults-and-refilling). |
+| `whenEmptied` | `"refill"` | What happens when fewer non-empty children remain than `min`: `"refill"` tops the container back up from `default`; `"unwrap"` replaces the container with its surviving children, or removes it entirely when none are left. Column lists use `"unwrap"` so emptied columns disappear and a one-column list dissolves. |
+| `boundary` | `"open"` | Whether editing gestures cross the container's edge. See [Boundaries](#boundaries). |
+
+`placement` sits next to `children` on the block config rather than inside it, because it's a fact about *this* block rather than about its children:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `placement` | `"anywhere"` | `"containerOnly"` restricts the block to containers that name it in their `children.allow` array, like a `column`, which only makes sense inside a `columnList`. It also requires the block to be a container itself. `"anywhere"` is valid on any block; on a regular block it simply restates the default. |
+
+Purely behavioral options that apply to *every* block kind stay in the block implementation's `meta`:
+
+| Meta option | Default | Description |
+| --- | --- | --- |
+| `draggable` | `true` | Whether the block gets a side menu drag handle. A block that opts out is skipped when looking for a handle, so the handle falls through to the nearest draggable ancestor. |
+
+
+ _`whenEmptied` never destroys typed text: only empty children are dropped._
+
+
+## Defaults and refilling
+
+`default` is an insertion template: a container inserted without an explicit `children` array is created with those blocks. Omit it and BlockNote fills the container with empty blocks its schema accepts.
+
+The same template drives `whenEmptied: "refill"`. When a refill container's non-empty children drop below `min`, say `k` remain, BlockNote appends `default[k]` through `default[min - 1]` at the end, falling back to empty blocks where `default` is absent or has no entry for a position. A checklist with `min: 2` and a two-entry `default` that loses its second item gets `default[1]` back, not a bare paragraph.
+
+## Boundaries
+
+`boundary` declares whether editing gestures cross a container's edge. On an open edge they move blocks across it: Backspace at the start of the first child moves that child out, and Enter on an empty last child escapes below the container. A sealed edge blocks all of that, so the container behaves as a single unit.
+
+| Value | Crosses the edge | Use for |
+| --- | --- | --- |
+| `"open"` (default) | The caret and editing gestures. | Containers that are part of the surrounding flow of text, like a callout or the columns of a `columnList`. |
+| `"sealed"` | Nothing implicitly. The caret won't wander in, and from outside the container selects and deletes as one unit. | Compartments that should stay put, like a table cell. |
+
+A seal binds gestures only. A text selection may span any edge, so a drag out of a sealed container still selects across it.
+
+```typescript
+// A cell: holds any blocks, but nothing crosses its edge implicitly.
+children: { allow: "any", boundary: "sealed" },
+placement: "containerOnly",
+```
+
+The block manipulation API ignores `boundary` entirely. An `insertBlocks` call is an intentional crossing, so it can always place content inside a sealed container.
+
+## Restricting children
+
+`allow` takes one of four forms:
+
+```typescript
+allow: "any" | "blocks" | "containers" | string[]
+```
+
+- `"any"`: any regular block, plus any container placeable anywhere.
+- `"blocks"`: regular blocks only, no containers.
+- `"containers"`: any anywhere-placeable container, no regular blocks.
+- `string[]`: only the named container block types.
+
+The wildcard forms (`"any"`, `"containers"`) exclude `placement: "containerOnly"` types: a `column` never shows up inside your callout just because the callout accepts "any" block. A containerOnly type appears only where a parent names it in an array.
+
+The array form is exact because each container block type is distinct in the schema, while every regular block (paragraph, heading, code block) shares one underlying type. So "only headings" is not something the schema can enforce yet. Naming a regular block type in the array is a startup error; per-type filtering of regular blocks is not yet supported, and the array is where it will land later with no API change.
+
+This is exactly how the multi-column blocks are defined:
+
+```typescript
+// The outer container: only columns, at least two of them;
+// unwraps when it drops to one, and selections span its columns.
+children: {
+ allow: ["column"],
+ min: 2,
+ whenEmptied: "unwrap",
+ boundary: "open",
+}
+
+// The column: holds any blocks, but only lives inside a columnList.
+children: { allow: "any" },
+placement: "containerOnly",
+```
+
+## Inserting into a container
+
+[`editor.insertBlocks`](/docs/reference/editor/manipulating-content#inserting-blocks) takes two nested placements alongside the sibling ones:
+
+```typescript
+// Siblings of the reference block:
+editor.insertBlocks([{ type: "paragraph" }], calloutId, "before");
+editor.insertBlocks([{ type: "paragraph" }], calloutId, "after");
+
+// Nested inside it, as its first or last child:
+editor.insertBlocks([{ type: "paragraph" }], calloutId, "first-child");
+editor.insertBlocks([{ type: "paragraph" }], calloutId, "last-child");
+```
+
+The nested placements are what addresses a container with no children to point at. A `min: 0` container that is currently empty has no child block to insert before or after. Whether a block fits is answered by the schema, so it's your `children` config that decides.
+
+## Validation
+
+Configurations are checked when the schema is created, and fail up front with a message naming the block. Beyond unknown block types and impossible `default` children, this catches:
+
+- an `allow` that permits nothing: an empty array, or a wildcard form when no anywhere-placeable container exists;
+- an `allow` array naming an unknown type, or naming a regular block type (per-type filtering of regular blocks is [not yet supported](#restricting-children));
+- `children` combined with any `content` other than `"none"`;
+- a `placement: "containerOnly"` block that no container's `allow` array names, or `placement: "containerOnly"` on a regular 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. `allow: "containers"` with `min: 1` is the same problem, since the container counts as a container itself.
+
+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.
+
+## Parsing HTML into a container
+
+Containers parse like any other custom block. The default rule matches `[data-node-type=""]` so BlockNote's own HTML round-trips, and `implementation.parse` recognizes foreign HTML. Both work exactly as described for [custom blocks](/docs/features/custom-schemas/custom-blocks).
+
+What's specific to a container is its body. By default BlockNote parses the element's children with the normal block rules, so `
…
…
` becomes a card with a paragraph and a heading. Supply `parseContent` only when you need to build the body yourself.
+
+
+ _`allow` does not filter what a user pastes. Content your container rejects is
+ placed after the container rather than dropped. `allow` constrains the
+ document model, not the parser._
+
+
+## Interop behavior
+
+Containers serialize to a `
` with their children nested inside, and round-trip losslessly. For lossy targets you place the children yourself: return a `childrenDOM` from `toExternalHTML` (this is how toggles export as ``), and give container blocks an explicit mapping in the DOCX, ODT, email, Typst, and PDF exporters, which throw on a missing one. That mapping receives the container's rendered children as its last argument and decides where they go — the exporters do not append them after the container's own output. Markdown flattens containers, exporting their children in order.
diff --git a/docs/content/docs/features/custom-schemas/custom-blocks.mdx b/docs/content/docs/features/custom-schemas/custom-blocks.mdx
index ff25cf838c..204381e785 100644
--- a/docs/content/docs/features/custom-schemas/custom-blocks.mdx
+++ b/docs/content/docs/features/custom-schemas/custom-blocks.mdx
@@ -72,6 +72,12 @@ type BlockConfig = {
alert, so we set `content` to `"inline"`._
+
+ _A `content: "none"` block can also hold other blocks as its body by
+ declaring the `children` option. See [Container
+ Blocks](/docs/features/custom-schemas/container-blocks)._
+
+
`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
diff --git a/docs/content/docs/features/export/typst.mdx b/docs/content/docs/features/export/typst.mdx
index 4a5e0ddaa3..39e908cba7 100644
--- a/docs/content/docs/features/export/typst.mdx
+++ b/docs/content/docs/features/export/typst.mdx
@@ -120,6 +120,22 @@ For a block with inline content, render it the way the default mappings do:
`exporter.transformInlineContent(block.content).join("")` (inline results are
markup strings, so plain concatenation composes them).
+### Container blocks
+
+A [container block](/docs/features/custom-schemas/container-blocks) holds
+child blocks, and its mapping decides where they go: the exporter renders the
+children first and passes them in as the mapping's last argument, rather than
+appending them after the container's own output. A container without a
+mapping is an error rather than a silent omission, since dropping it would
+drop its children too.
+
+```typescript
+myContainer: (block, exporter, nestingLevel, numberedListIndex, children) =>
+ `#rect(width: 100%)[${children.join("\n\n")}]`,
+```
+
+Separate the children with a blank line, as above, if each should stay its own
+block — a single `\n` is only a soft break in Typst markup.
### Math & diagram blocks
diff --git a/docs/content/docs/reference/editor/manipulating-content.mdx b/docs/content/docs/reference/editor/manipulating-content.mdx
index 1a9c97c222..5cde60c29c 100644
--- a/docs/content/docs/reference/editor/manipulating-content.mdx
+++ b/docs/content/docs/reference/editor/manipulating-content.mdx
@@ -141,11 +141,11 @@ editor.forEachBlock((block) => {
insertBlocks(
blocksToInsert: PartialBlock[],
referenceBlock: BlockIdentifier,
- placement: "before" | "after" = "before"
+ placement: "before" | "after" | "first-child" | "last-child" = "before"
): void
```
-Inserts new blocks relative to an existing 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. See [Inserting into a container](/docs/features/custom-schemas/container-blocks#inserting-into-a-container).
```typescript
// Insert a paragraph before an existing block
@@ -164,6 +164,13 @@ editor.insertBlocks(
"existing-block-id",
"after",
);
+
+// Insert a paragraph as the last child of a container block
+editor.insertBlocks(
+ [{ type: "paragraph", content: "Nested paragraph" }],
+ "container-block-id",
+ "last-child",
+);
```
### Updating Blocks
diff --git a/examples/06-custom-schema/09-container-block/.bnexample.json b/examples/06-custom-schema/09-container-block/.bnexample.json
new file mode 100644
index 0000000000..3de7330631
--- /dev/null
+++ b/examples/06-custom-schema/09-container-block/.bnexample.json
@@ -0,0 +1,15 @@
+{
+ "playground": true,
+ "docs": true,
+ "author": "nickthesick",
+ "tags": [
+ "Intermediate",
+ "Blocks",
+ "Custom Schemas",
+ "Suggestion Menus",
+ "Slash Menu"
+ ],
+ "dependencies": {
+ "react-icons": "^5.5.0"
+ }
+}
diff --git a/examples/06-custom-schema/09-container-block/README.md b/examples/06-custom-schema/09-container-block/README.md
new file mode 100644
index 0000000000..070dd71987
--- /dev/null
+++ b/examples/06-custom-schema/09-container-block/README.md
@@ -0,0 +1,22 @@
+# Container Block
+
+In this example, we create a custom `Callout` block that holds other blocks as its body, like a Notion-style callout wrapping a paragraph followed by a code block.
+
+The block declares the `children` config on `BlockConfig`. `children: { min: 1, default: [{ type: "paragraph" }] }` makes it a container: its child blocks mount into the element the render passes `contentRef` to, and live on `block.children` at runtime.
+
+The callout's **title** demonstrates the complementary "string prop slot" pattern: a field that doesn't need rich text, comments, or multiplayer cursors can live in a plain string prop, edited through a regular `` rendered inside the block (in a `contentEditable={false}` wrapper) and committed via `editor.updateBlock`. A field that _is_ prose belongs in the block's own `content: "inline"` instead.
+
+We also wire up a Slash Menu item to insert the callout, and render the document JSON next to the editor so you can inspect the structure of the nested blocks.
+
+**Try it out:**
+
+- Press the "/" key inside the callout's body and add a code block, heading, or list.
+- Type a title into the title field. It's stored on `block.props.title`, not as document content.
+- Watch the JSON panel on the right update as you edit; the callout's children appear in `block.children`.
+- Insert a new callout via the Slash Menu (search "callout").
+
+**Relevant Docs:**
+
+- [Container Blocks](/docs/features/custom-schemas/container-blocks)
+- [Custom Blocks](/docs/features/custom-schemas/custom-blocks)
+- [Editor Setup](/docs/getting-started/editor-setup)
diff --git a/examples/06-custom-schema/09-container-block/index.html b/examples/06-custom-schema/09-container-block/index.html
new file mode 100644
index 0000000000..19321f77b5
--- /dev/null
+++ b/examples/06-custom-schema/09-container-block/index.html
@@ -0,0 +1,14 @@
+
+
+
+
+ Container Block
+
+
+
+
+
+
+
diff --git a/examples/06-custom-schema/09-container-block/main.tsx b/examples/06-custom-schema/09-container-block/main.tsx
new file mode 100644
index 0000000000..1260513388
--- /dev/null
+++ b/examples/06-custom-schema/09-container-block/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(
+
+
+ ,
+);
diff --git a/examples/06-custom-schema/09-container-block/package.json b/examples/06-custom-schema/09-container-block/package.json
new file mode 100644
index 0000000000..29778f9255
--- /dev/null
+++ b/examples/06-custom-schema/09-container-block/package.json
@@ -0,0 +1,31 @@
+{
+ "name": "@blocknote/example-custom-schema-container-block",
+ "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",
+ "react-icons": "^5.5.0"
+ },
+ "devDependencies": {
+ "@types/react": "^19.2.3",
+ "@types/react-dom": "^19.2.3",
+ "@vitejs/plugin-react": "^6.0.1",
+ "vite": "^8.0.0"
+ }
+}
diff --git a/examples/06-custom-schema/09-container-block/src/App.tsx b/examples/06-custom-schema/09-container-block/src/App.tsx
new file mode 100644
index 0000000000..3d6cf55ba1
--- /dev/null
+++ b/examples/06-custom-schema/09-container-block/src/App.tsx
@@ -0,0 +1,118 @@
+import { BlockNoteSchema, defaultBlockSpecs } from "@blocknote/core";
+import {
+ filterSuggestionItems,
+ insertOrUpdateBlockForSlashMenu,
+} from "@blocknote/core/extensions";
+import "@blocknote/core/fonts/inter.css";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import {
+ SuggestionMenuController,
+ getDefaultReactSlashMenuItems,
+ useCreateBlockNote,
+} from "@blocknote/react";
+import { useEffect, useState } from "react";
+import { RiChatQuoteLine } from "react-icons/ri";
+
+import { createCallout } from "./Callout";
+import "./styles.css";
+
+// Schema with the default blocks plus our custom Callout container block.
+const schema = BlockNoteSchema.create().extend({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ callout: createCallout(),
+ },
+});
+
+// Slash menu item to insert a Callout. Because Callout is a container block,
+// inserting one with no children causes BlockNote to seed it with the block's
+// configured `children.default` (a single paragraph here).
+const insertCallout = (editor: typeof schema.BlockNoteEditor) => ({
+ title: "Callout",
+ subtext: "Container block that wraps other blocks",
+ onItemClick: () =>
+ insertOrUpdateBlockForSlashMenu(editor, {
+ type: "callout",
+ }),
+ aliases: ["callout", "container", "alert", "note", "tip", "info"],
+ group: "Basic blocks",
+ icon: ,
+});
+
+type AppBlock = (typeof schema.BlockNoteEditor)["document"][number];
+
+export default function App() {
+ const [blocks, setBlocks] = useState([]);
+
+ const editor = useCreateBlockNote({
+ schema,
+ initialContent: [
+ {
+ type: "paragraph",
+ content: "Welcome! This demo shows the new container block kind.",
+ },
+ {
+ type: "callout",
+ props: { flavor: "tip" },
+ children: [
+ {
+ type: "paragraph",
+ content: "Callouts can hold any block as their body.",
+ },
+ {
+ type: "paragraph",
+ content:
+ "Try pressing '/' inside this callout to add a heading or code block.",
+ },
+ ],
+ },
+ {
+ type: "paragraph",
+ content: "Press '/' anywhere to insert a new Callout.",
+ },
+ {
+ type: "paragraph",
+ },
+ ],
+ });
+
+ useEffect(() => setBlocks(editor.document), [editor]);
+
+ return (
+
+ );
+}
diff --git a/examples/06-custom-schema/09-container-block/src/Callout.tsx b/examples/06-custom-schema/09-container-block/src/Callout.tsx
new file mode 100644
index 0000000000..b150cead50
--- /dev/null
+++ b/examples/06-custom-schema/09-container-block/src/Callout.tsx
@@ -0,0 +1,104 @@
+import { createReactBlockSpec } from "@blocknote/react";
+import { MdCheckCircle, MdInfo, MdLightbulb, MdWarning } from "react-icons/md";
+
+import "./styles.css";
+
+// The flavors of callout the user can switch between.
+export const calloutTypes = [
+ { value: "tip", title: "Tip", icon: MdLightbulb },
+ { value: "info", title: "Info", icon: MdInfo },
+ { value: "warning", title: "Warning", icon: MdWarning },
+ { value: "success", title: "Success", icon: MdCheckCircle },
+] as const;
+
+// The Callout block. Declared with `content: "none"` plus the `children`
+// config: the block hosts arbitrary child blocks in its body, exposed at
+// runtime as `block.children`.
+//
+// The callout's title shows a related pattern: content that shouldn't be
+// part of the rich-text document (no formatting, comments, or multiplayer
+// cursors needed) can live in a plain string prop, edited through a regular
+// rendered inside the block.
+export const createCallout = createReactBlockSpec(
+ {
+ type: "callout",
+ propSchema: {
+ flavor: {
+ default: "tip",
+ values: ["tip", "info", "warning", "success"],
+ },
+ title: {
+ default: "",
+ },
+ },
+ content: "none",
+ // `children: { allow: "any" }` is the entire container declaration: any
+ // block is allowed, at least one is required, and BlockNote fills the
+ // callout with an empty paragraph when it's created. `min` / `max` /
+ // `default` / `whenEmptied` / `boundary` tune this.
+ children: { allow: "any" },
+ },
+ {
+ render: (props) => {
+ const flavor =
+ calloutTypes.find((c) => c.value === props.block.props.flavor) ??
+ calloutTypes[0];
+ const Icon = flavor.icon;
+
+ const cycleFlavor = () => {
+ const idx = calloutTypes.findIndex(
+ (c) => c.value === props.block.props.flavor,
+ );
+ const next = calloutTypes[(idx + 1) % calloutTypes.length];
+ props.editor.updateBlock(props.block, {
+ type: "callout",
+ props: { flavor: next.value },
+ });
+ };
+
+ const commitTitle = (title: string) => {
+ if (title !== props.block.props.title) {
+ props.editor.updateBlock(props.block, {
+ type: "callout",
+ props: { title },
+ });
+ }
+ };
+
+ return (
+
+
+
+ {/* The title lives in a string prop, not in document content,
+ and is edited via a plain input. `contentEditable={false}`
+ keeps ProseMirror from treating typing here as document
+ input. */}
+
+ );
+}
diff --git a/examples/06-custom-schema/12-container-table/src/Table.tsx b/examples/06-custom-schema/12-container-table/src/Table.tsx
new file mode 100644
index 0000000000..e63b916db4
--- /dev/null
+++ b/examples/06-custom-schema/12-container-table/src/Table.tsx
@@ -0,0 +1,346 @@
+import {
+ createExtension,
+ type Block,
+ type BlockNoteEditor,
+} from "@blocknote/core";
+import { createReactBlockSpec } from "@blocknote/react";
+
+import "./styles.css";
+
+// A table built entirely out of container blocks, without `prosemirror-tables`
+// or the special `"table"` content type. A table is a container of rows, a row
+// is a container of cells, and a cell is a container of arbitrary blocks:
+//
+// table > tableRow > tableCell / tableHeader > (any blocks)
+//
+// The JSON shape is the same `children` array every other container block
+// uses, and every structural operation (add/remove row or column, toggle the
+// header row) is a plain `insertBlocks` / `removeBlocks` / `updateBlock` call.
+
+type AnyEditor = BlockNoteEditor;
+type AnyBlock = Block;
+
+function isCellType(type: string): boolean {
+ return type === "tableCell" || type === "tableHeader";
+}
+
+// ---------------------------------------------------------------------------
+// Cell navigation (Tab / Shift-Tab)
+// ---------------------------------------------------------------------------
+
+// Finds the cell / row / table the text cursor is currently inside, by
+// walking up the ancestor chain with `editor.getParentBlock`. Returns
+// undefined when the cursor isn't in a table.
+function getCellContext(
+ editor: AnyEditor,
+): { cell: AnyBlock; row: AnyBlock; table: AnyBlock } | undefined {
+ let current: AnyBlock | undefined = editor.getTextCursorPosition().block;
+ while (current && !isCellType(current.type)) {
+ current = editor.getParentBlock(current);
+ }
+ if (!current) {
+ return undefined;
+ }
+
+ const row = editor.getParentBlock(current);
+ if (!row || row.type !== "tableRow") {
+ return undefined;
+ }
+ const table = editor.getParentBlock(row);
+ if (!table || table.type !== "table") {
+ return undefined;
+ }
+
+ return { cell: current, row, table };
+}
+
+// Places the cursor inside a cell. Descends through nested tables so the
+// cursor always lands on a block that can actually hold it.
+function placeCursorInCell(
+ editor: AnyEditor,
+ cell: AnyBlock,
+ placement: "start" | "end",
+) {
+ let target = cell;
+ while (
+ target.children.length > 0 &&
+ (target.type === "table" ||
+ target.type === "tableRow" ||
+ isCellType(target.type))
+ ) {
+ target =
+ placement === "start"
+ ? target.children[0]
+ : target.children[target.children.length - 1];
+ }
+ editor.setTextCursorPosition(target, placement);
+}
+
+function createRow(
+ numColumns: number,
+ cellType: "tableCell" | "tableHeader" = "tableCell",
+) {
+ return {
+ type: "tableRow" as const,
+ children: Array.from({ length: numColumns }, () => ({ type: cellType })),
+ };
+}
+
+// Moves the cursor to the next/previous cell, wrapping across rows. Tab past
+// the last cell grows the table by a row, like in a spreadsheet, with a
+// single `insertBlocks` call.
+function moveToAdjacentCell(editor: AnyEditor, direction: 1 | -1): boolean {
+ const context = getCellContext(editor);
+ if (!context) {
+ // Not in a table: let BlockNote's default Tab (indent) behavior run.
+ return false;
+ }
+ const { cell, row, table } = context;
+
+ const rows = table.children;
+ const rowIndex = rows.findIndex((r) => r.id === row.id);
+ const cellIndex = row.children.findIndex((c) => c.id === cell.id);
+
+ let targetRowIndex = rowIndex;
+ let targetCellIndex = cellIndex + direction;
+ if (targetCellIndex >= row.children.length) {
+ targetRowIndex += 1;
+ targetCellIndex = 0;
+ } else if (targetCellIndex < 0) {
+ targetRowIndex -= 1;
+ targetCellIndex =
+ targetRowIndex >= 0 ? rows[targetRowIndex].children.length - 1 : 0;
+ }
+
+ // Shift-Tab at the very first cell: stay put (but consume the key so the
+ // cell's content isn't un-indented out of the table).
+ if (targetRowIndex < 0) {
+ return true;
+ }
+
+ // Tab at the very last cell: append a new row and move into it.
+ if (targetRowIndex >= rows.length) {
+ editor.insertBlocks(
+ [createRow(row.children.length)],
+ rows[rows.length - 1],
+ "after",
+ );
+ const updatedTable = editor.getBlock(table.id);
+ const newRow = updatedTable?.children[updatedTable.children.length - 1];
+ if (newRow) {
+ placeCursorInCell(editor, newRow.children[0], "start");
+ }
+ return true;
+ }
+
+ placeCursorInCell(
+ editor,
+ rows[targetRowIndex].children[targetCellIndex],
+ direction === 1 ? "start" : "end",
+ );
+ return true;
+}
+
+// Registered on the `table` block spec, so the shortcuts are only added when
+// the block is in the schema. Block-spec extensions run before BlockNote's
+// default keyboard handlers, so Tab reaches us before the default indent.
+const TableKeyboardExtension = createExtension({
+ key: "containerTableKeyboard",
+ keyboardShortcuts: {
+ Tab: ({ editor }) => moveToAdjacentCell(editor, 1),
+ "Shift-Tab": ({ editor }) => moveToAdjacentCell(editor, -1),
+ },
+});
+
+// ---------------------------------------------------------------------------
+// Structural operations, using only the public block manipulation API
+// ---------------------------------------------------------------------------
+
+function getTable(editor: AnyEditor, tableId: string): AnyBlock | undefined {
+ const table = editor.getBlock(tableId);
+ return table?.type === "table" ? table : undefined;
+}
+
+export function addRow(editor: AnyEditor, tableId: string) {
+ const table = getTable(editor, tableId);
+ if (!table) {
+ return;
+ }
+ const lastRow = table.children[table.children.length - 1];
+ editor.insertBlocks([createRow(lastRow.children.length)], lastRow, "after");
+}
+
+export function removeRow(editor: AnyEditor, tableId: string) {
+ const table = getTable(editor, tableId);
+ if (!table || table.children.length <= 1) {
+ return;
+ }
+ editor.removeBlocks([table.children[table.children.length - 1]]);
+}
+
+export function addColumn(editor: AnyEditor, tableId: string) {
+ const table = getTable(editor, tableId);
+ if (!table) {
+ return;
+ }
+ editor.transact(() => {
+ for (const row of table.children) {
+ const lastCell = row.children[row.children.length - 1];
+ // Match the row's cell kind, so a header row grows a header cell.
+ editor.insertBlocks([{ type: lastCell.type }], lastCell, "after");
+ }
+ });
+}
+
+export function removeColumn(editor: AnyEditor, tableId: string) {
+ const table = getTable(editor, tableId);
+ if (!table || table.children.some((row) => row.children.length <= 1)) {
+ return;
+ }
+ editor.transact(() => {
+ for (const row of table.children) {
+ editor.removeBlocks([row.children[row.children.length - 1]]);
+ }
+ });
+}
+
+// Flips the first row between header cells and regular cells. Because header
+// cells are a distinct block type (not table metadata), this is just
+// `updateBlock` with a new type. Children are carried over automatically.
+export function toggleHeaderRow(editor: AnyEditor, tableId: string) {
+ const table = getTable(editor, tableId);
+ if (!table) {
+ return;
+ }
+ const firstRow = table.children[0];
+ const allHeaders = firstRow.children.every((c) => c.type === "tableHeader");
+ const type = allHeaders ? "tableCell" : "tableHeader";
+ editor.transact(() => {
+ for (const cell of firstRow.children) {
+ editor.updateBlock(cell, { type });
+ }
+ });
+}
+
+// ---------------------------------------------------------------------------
+// The four block specs
+// ---------------------------------------------------------------------------
+
+// The table itself: a container that only accepts rows. Inserting one with
+// no explicit children seeds it from `children.default`: a header row plus
+// two body rows, three columns wide.
+export const createTable = createReactBlockSpec(
+ {
+ type: "table",
+ propSchema: {},
+ content: "none",
+ children: {
+ allow: ["tableRow"],
+ default: [
+ createRow(3, "tableHeader"),
+ createRow(3, "tableCell"),
+ createRow(3, "tableCell"),
+ ],
+ },
+ },
+ {
+ render: (props) => {
+ // `props.block` is captured at render time; the control handlers
+ // re-fetch the table by id so they always operate on fresh children.
+ const { editor } = props;
+ const tableId = props.block.id;
+
+ // Keep focus (and the text selection) in the editor when clicking the
+ // controls.
+ const keepFocus = (event: React.MouseEvent) => event.preventDefault();
+
+ return (
+
+
+
+
+
+
+
+
+
+
+ );
+ },
+ // Recognizes pasted foreign HTML tables.
+ parse: (el) => (el.tagName === "TABLE" ? {} : undefined),
+ },
+ [TableKeyboardExtension],
+);
+
+// A row: only lives inside a table (`placement: "containerOnly"`), only
+// holds cells.
+export const createTableRow = createReactBlockSpec(
+ {
+ type: "tableRow",
+ propSchema: {},
+ content: "none",
+ children: { allow: ["tableCell", "tableHeader"] },
+ placement: "containerOnly",
+ },
+ {
+ // No drag handle of its own; the side menu handle falls through to the
+ // table.
+ meta: { draggable: false },
+ render: (props) => (
+
+ ),
+ parse: (el) => (el.tagName === "TR" ? {} : undefined),
+ },
+);
+
+// A cell: holds any blocks, and is `boundary: "sealed"`, so the caret and
+// content never implicitly cross its edge (Backspace at the start of a cell
+// does nothing, Delete at its end doesn't pull the next block in, arrow keys
+// from outside treat the table as a unit). Enter inside a cell just adds
+// another block to the cell.
+export const createTableCell = createReactBlockSpec(
+ {
+ type: "tableCell",
+ propSchema: {},
+ content: "none",
+ children: { allow: "any", boundary: "sealed" },
+ placement: "containerOnly",
+ },
+ {
+ meta: { draggable: false },
+ render: (props) => (
+
+ ),
+ parse: (el) => (el.tagName === "TD" ? {} : undefined),
+ },
+);
+
+// A header cell: identical to a regular cell, but a distinct block type.
+// The structure itself encodes which cells are headers, instead of
+// `headerRows` metadata on the table.
+export const createTableHeader = createReactBlockSpec(
+ {
+ type: "tableHeader",
+ propSchema: {},
+ content: "none",
+ children: { allow: "any", boundary: "sealed" },
+ placement: "containerOnly",
+ },
+ {
+ meta: { draggable: false },
+ render: (props) => (
+
+ ),
+ parse: (el) => (el.tagName === "TH" ? {} : undefined),
+ },
+);
diff --git a/examples/06-custom-schema/12-container-table/src/styles.css b/examples/06-custom-schema/12-container-table/src/styles.css
new file mode 100644
index 0000000000..cfb39149f8
--- /dev/null
+++ b/examples/06-custom-schema/12-container-table/src/styles.css
@@ -0,0 +1,100 @@
+.wrapper {
+ display: flex;
+ flex-direction: column;
+ height: 100%;
+}
+
+.item {
+ border-radius: 0.5rem;
+ flex: 1;
+ overflow: hidden;
+}
+
+.item.bordered {
+ border: 1px solid gray;
+}
+
+.item pre {
+ border-radius: 0.5rem;
+ height: 100%;
+ overflow: auto;
+ padding-block: 1rem;
+ padding-inline: 54px;
+ width: 100%;
+ white-space: pre-wrap;
+}
+
+/* The grid is plain CSS tables on divs. The React node-view wrappers between
+ the regions carry `display: contents`, so the row and cell boxes end up
+ direct children of the table box as far as layout is concerned. */
+.container-table {
+ flex-grow: 1;
+ min-width: 0;
+}
+
+.container-table-rows {
+ display: table;
+ border-collapse: collapse;
+ width: 100%;
+ table-layout: fixed;
+}
+
+.container-table-row {
+ display: table-row;
+}
+
+.container-table-cell {
+ display: table-cell;
+ border: 1px solid #d0d0d0;
+ padding: 4px 8px;
+ vertical-align: top;
+}
+
+.container-table-header {
+ background-color: #f3f4f6;
+ font-weight: 600;
+}
+
+[data-color-scheme="dark"] .container-table-cell {
+ border-color: #4b4b4b;
+}
+
+[data-color-scheme="dark"] .container-table-header {
+ background-color: #2e2e2e;
+}
+
+.container-table-controls {
+ display: flex;
+ gap: 4px;
+ padding-top: 4px;
+ /* Only reveal the controls while working in the table. */
+ opacity: 0;
+ transition: opacity 0.15s;
+}
+
+.container-table:hover .container-table-controls,
+.container-table:focus-within .container-table-controls {
+ opacity: 1;
+}
+
+.container-table-controls button {
+ border: 1px solid #d0d0d0;
+ border-radius: 4px;
+ background: none;
+ color: inherit;
+ font-size: 0.75rem;
+ padding: 2px 8px;
+ cursor: pointer;
+}
+
+.container-table-controls button:hover {
+ background-color: #f3f4f6;
+}
+
+[data-color-scheme="dark"] .container-table-controls button {
+ border-color: #4b4b4b;
+}
+
+[data-color-scheme="dark"] .container-table-controls button:hover {
+ background-color: #2e2e2e;
+}
diff --git a/examples/06-custom-schema/12-container-table/tsconfig.json b/examples/06-custom-schema/12-container-table/tsconfig.json
new file mode 100644
index 0000000000..2aa62c56e6
--- /dev/null
+++ b/examples/06-custom-schema/12-container-table/tsconfig.json
@@ -0,0 +1,32 @@
+{
+ "__comment": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+ "compilerOptions": {
+ "target": "ESNext",
+ "useDefineForClassFields": true,
+ "lib": ["DOM", "DOM.Iterable", "ESNext"],
+ "allowJs": false,
+ "skipLibCheck": true,
+ "allowSyntheticDefaultImports": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "noEmit": true,
+ "jsx": "react-jsx",
+ "composite": true,
+ "paths": {
+ "@shared/*": ["../../../shared/*"]
+ }
+ },
+ "include": ["."],
+ "__ADD_FOR_LOCAL_DEV_references": [
+ {
+ "path": "../../../packages/core/"
+ },
+ {
+ "path": "../../../packages/react/"
+ }
+ ]
+}
diff --git a/examples/06-custom-schema/12-container-table/vite-env.d.ts b/examples/06-custom-schema/12-container-table/vite-env.d.ts
new file mode 100644
index 0000000000..11f02fe2a0
--- /dev/null
+++ b/examples/06-custom-schema/12-container-table/vite-env.d.ts
@@ -0,0 +1 @@
+///
diff --git a/examples/06-custom-schema/12-container-table/vite.config.ts b/examples/06-custom-schema/12-container-table/vite.config.ts
new file mode 100644
index 0000000000..a96f1f04ff
--- /dev/null
+++ b/examples/06-custom-schema/12-container-table/vite.config.ts
@@ -0,0 +1,35 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import react from "@vitejs/plugin-react";
+import * as fs from "fs";
+import * as path from "path";
+import { defineConfig } from "vite";
+// https://vitejs.dev/config/
+export default defineConfig(((conf: { command: string }) => ({
+ plugins: [react()],
+ optimizeDeps: {},
+ build: {
+ sourcemap: true,
+ },
+ resolve: {
+ alias:
+ conf.command === "build" ||
+ !fs.existsSync(path.resolve(__dirname, "../../packages/core/src"))
+ ? {}
+ : ({
+ // The repo-wide alias for the shared test-utils directory (private,
+ // so it only resolves inside the monorepo). Harmless for examples
+ // that don't use it.
+ "@shared": path.resolve(__dirname, "../../../shared/"),
+ // Comment out the lines below to load a built version of blocknote
+ // or, keep as is to load live from sources with live reload working
+ "@blocknote/core": path.resolve(
+ __dirname,
+ "../../packages/core/src/",
+ ),
+ "@blocknote/react": path.resolve(
+ __dirname,
+ "../../packages/react/src/",
+ ),
+ } as any),
+ },
+})) as Parameters[0]);
diff --git a/packages/core/package.json b/packages/core/package.json
index eb2700636d..8b9f1ee69b 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -72,6 +72,11 @@
"import": "./dist/extensions.js",
"require": "./dist/extensions.cjs"
},
+ "./internal": {
+ "types": "./types/src/internal.d.ts",
+ "import": "./dist/internal.js",
+ "require": "./dist/internal.cjs"
+ },
"./yjs": {
"types": "./types/src/yjs/index.d.ts",
"import": "./dist/yjs.js",
diff --git a/packages/core/src/api/blockManipulation/commands/insertBlocks/insertBlocks.ts b/packages/core/src/api/blockManipulation/commands/insertBlocks/insertBlocks.ts
index b41b268617..7f57dfbe9c 100644
--- a/packages/core/src/api/blockManipulation/commands/insertBlocks/insertBlocks.ts
+++ b/packages/core/src/api/blockManipulation/commands/insertBlocks/insertBlocks.ts
@@ -1,4 +1,4 @@
-import { Fragment, Slice } from "prosemirror-model";
+import { Fragment, Node, NodeType, Slice } from "prosemirror-model";
import type { Transaction } from "prosemirror-state";
import { ReplaceStep } from "prosemirror-transform";
import { Block, PartialBlock } from "../../../../blocks/defaultBlocks.js";
@@ -8,10 +8,83 @@ import {
InlineContentSchema,
StyleSchema,
} from "../../../../schema/index.js";
+import { getBlockInfoFromNode } from "../../../getBlockInfoFromPos.js";
import { blockToNode } from "../../../nodeConversions/blockToNode.js";
import { nodeToBlock } from "../../../nodeConversions/nodeToBlock.js";
import { getNodeById } from "../../../nodeUtil.js";
import { getPmSchema } from "../../../pmUtil.js";
+import { descendToInsertionPos } from "../../containers/containerNav.js";
+
+/**
+ * Where blocks go relative to a reference block. `"before"`/`"after"` make
+ * them siblings of it; `"first-child"`/`"last-child"` nest them inside it.
+ *
+ * The nested placements cover containers that have no children to point at:
+ * a `min: 0` container that is currently empty has no child block to insert
+ * before or after.
+ */
+export type BlockPlacement = "before" | "after" | "first-child" | "last-child";
+
+/**
+ * Resolves a `placement` against a reference block into the document position
+ * a node of `nodeType` should be inserted at, or `null` when the reference
+ * block cannot take it there.
+ *
+ * Shared by `insertBlocks` and the move commands, so "does this block fit
+ * here?" is answered in one place. The answer comes from the schema's content
+ * matches rather than from a hand-written rule, so a container's `children`
+ * config decides it.
+ *
+ * `wrapIn` is set when the position only becomes valid once the nodes are
+ * wrapped: a regular block with no children yet has no `blockGroup` for them
+ * to go in, so one is created around them.
+ */
+export function getInsertionPos(
+ doc: Node,
+ reference: { node: Node; posBeforeNode: number },
+ placement: BlockPlacement,
+ nodeType: NodeType,
+): { pos: number; wrapIn?: NodeType } | null {
+ const { node, posBeforeNode } = reference;
+
+ if (placement === "before" || placement === "after") {
+ const pos =
+ placement === "before" ? posBeforeNode : posBeforeNode + node.nodeSize;
+ const $pos = doc.resolve(pos);
+
+ // `canReplaceWith` rather than a bare content match: the nodes already
+ // after the position have to still fit once the new one is spliced in.
+ return $pos.parent.canReplaceWith($pos.index(), $pos.index(), nodeType)
+ ? { pos }
+ : null;
+ }
+
+ const info = getBlockInfoFromNode(node, posBeforeNode);
+
+ if (info.children) {
+ // The navigation helpers stop at sealed boundaries but this caller lets
+ // them cross: an explicit `insertBlocks` placement is an intentional
+ // crossing.
+ const { pos } = descendToInsertionPos(
+ info,
+ nodeType,
+ placement === "first-child" ? "first" : "last",
+ { allowCrossingSeals: true },
+ );
+
+ return pos === undefined ? null : { pos };
+ }
+
+ // No children holder implies a `blockContainer` with no children yet
+ // (containers always have one): its `blockGroup` is lazy (`blockContent
+ // blockGroup?`), so the position after the content node only becomes valid
+ // once the nodes are wrapped in a new group.
+ const blockGroupType = nodeType.schema.nodes["blockGroup"];
+
+ return info.hasContent && blockGroupType?.contentMatch.matchType(nodeType)
+ ? { pos: info.content.afterPos, wrapIn: blockGroupType }
+ : null;
+}
export function insertBlocks<
BSchema extends BlockSchema,
@@ -21,7 +94,7 @@ export function insertBlocks<
tr: Transaction,
blocksToInsert: PartialBlock[],
referenceBlock: BlockIdentifier,
- placement: "before" | "after" = "before",
+ placement: BlockPlacement = "before",
): Block[] {
const id =
typeof referenceBlock === "string" ? referenceBlock : referenceBlock.id;
@@ -37,14 +110,57 @@ export function insertBlocks<
throw new Error(`Block with ID ${id} not found`);
}
- let pos = posInfo.posBeforeNode;
- if (placement === "after") {
- pos += posInfo.node.nodeSize;
+ if (nodesToInsert.length === 0) {
+ return [];
+ }
+
+ function reject(): never {
+ const what =
+ nodesToInsert.length === 1
+ ? `a block of type "${blocksToInsert[0].type ?? "paragraph"}"`
+ : `${nodesToInsert.length} blocks`;
+ const them = nodesToInsert.length === 1 ? "it" : "them";
+
+ throw new Error(
+ `Cannot insert ${what} ` +
+ (placement === "before" || placement === "after"
+ ? `${placement} block with ID ${id}: its parent does not accept ${them}.`
+ : `as the ${placement} of block with ID ${id}: the block does not accept ${them} as ${nodesToInsert.length === 1 ? "a child" : "children"}.`),
+ );
}
- tr.step(
- new ReplaceStep(pos, pos, new Slice(Fragment.from(nodesToInsert), 0, 0)),
+ const target = getInsertionPos(
+ tr.doc,
+ posInfo,
+ placement,
+ nodesToInsert[0].type,
);
+ if (!target) {
+ reject();
+ }
+
+ // `getInsertionPos` can only answer for the first node's type: the fragment
+ // doesn't exist yet when it runs. The whole fragment still has to fit — a
+ // `max: 1` container accepts one paragraph but not three — so it is checked
+ // here, where the nodes are known, rather than left to `tr.step` to reject
+ // with a ProseMirror-level message.
+ if (
+ target.wrapIn &&
+ !target.wrapIn.validContent(Fragment.from(nodesToInsert))
+ ) {
+ reject();
+ }
+
+ const fragment = target.wrapIn
+ ? Fragment.from(target.wrapIn.create(null, nodesToInsert))
+ : Fragment.from(nodesToInsert);
+
+ const $target = tr.doc.resolve(target.pos);
+ if (!$target.parent.canReplace($target.index(), $target.index(), fragment)) {
+ reject();
+ }
+
+ tr.step(new ReplaceStep(target.pos, target.pos, new Slice(fragment, 0, 0)));
// Now that the `PartialBlock`s have been converted to nodes, we can
// re-convert them into full `Block`s.
diff --git a/packages/core/src/api/blockManipulation/commands/insertBlocks/insertPlacement.test.ts b/packages/core/src/api/blockManipulation/commands/insertBlocks/insertPlacement.test.ts
new file mode 100644
index 0000000000..7bf8e4f137
--- /dev/null
+++ b/packages/core/src/api/blockManipulation/commands/insertBlocks/insertPlacement.test.ts
@@ -0,0 +1,262 @@
+// @vitest-environment node
+import {
+ afterAll,
+ beforeAll,
+ beforeEach,
+ describe,
+ expect,
+ it,
+} from "vite-plus/test";
+
+import { BlockNoteSchema } from "../../../../blocks/BlockNoteSchema.js";
+import { defaultBlockSpecs } from "../../../../blocks/defaultBlocks.js";
+import { BlockNoteEditor } from "../../../../editor/BlockNoteEditor.js";
+import { createBlockSpec } from "../../../../schema/blocks/createSpec.js";
+
+// The editor stays headless, so these blocks are never rendered. `render`
+// only has to exist for `createBlockSpec` to accept the spec.
+const container = (type: string, config: Record) =>
+ createBlockSpec({ type, propSchema: {}, ...config } as any, {
+ render: () => {
+ throw new Error("not rendered in this suite");
+ },
+ })();
+
+const schema = BlockNoteSchema.create().extend({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ // Why `"first-child"`/`"last-child"` exist: a container that may legally
+ // hold nothing has no child block to address, so `"before"`/`"after"`
+ // cannot reach inside it.
+ box: container("box", {
+ content: "none",
+ children: { allow: "any", min: 0 },
+ }),
+ // A container that only accepts other containers, so an insertion has to
+ // descend a level to find a place for a regular block.
+ grid: container("grid", {
+ content: "none",
+ children: { allow: ["cell"], min: 2 },
+ }),
+ cell: container("cell", {
+ content: "none",
+ children: { allow: "any" },
+ placement: "containerOnly",
+ }),
+ // A container that is full once it has one child.
+ single: container("single", {
+ content: "none",
+ children: { allow: "any", max: 1 },
+ }),
+ // Same, but legally empty: room for the first of a batch, but not for
+ // the batch.
+ emptySingle: container("emptySingle", {
+ content: "none",
+ children: { allow: "any", min: 0, max: 1 },
+ }),
+ } as const,
+});
+
+let editor: BlockNoteEditor;
+
+beforeAll(() => {
+ editor = BlockNoteEditor.create({ schema }) as any;
+});
+
+afterAll(() => {
+ editor._tiptapEditor.destroy();
+ editor = undefined as any;
+});
+
+beforeEach(() => {
+ editor.replaceBlocks(editor.document, [
+ { id: "p-0", type: "paragraph", content: "Paragraph 0" },
+ ]);
+});
+
+describe('insertBlocks "first-child" / "last-child"', () => {
+ it("inserts into a childless container", () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "b-0", type: "box" },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+ expect(editor.getBlock("b-0")!.children).toHaveLength(0);
+
+ editor.insertBlocks(
+ [{ id: "first", type: "paragraph" }],
+ "b-0",
+ "first-child",
+ );
+ editor.insertBlocks(
+ [{ id: "last", type: "paragraph" }],
+ "b-0",
+ "last-child",
+ );
+
+ expect(editor.getBlock("b-0")!.children.map((child) => child.id)).toEqual([
+ "first",
+ "last",
+ ]);
+ });
+
+ it("prepends and appends around existing children", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ id: "b-0",
+ type: "box",
+ children: [{ id: "existing", type: "paragraph", content: "Existing" }],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ editor.insertBlocks(
+ [{ id: "first", type: "paragraph" }],
+ "b-0",
+ "first-child",
+ );
+ editor.insertBlocks(
+ [{ id: "last", type: "paragraph" }],
+ "b-0",
+ "last-child",
+ );
+
+ expect(editor.getBlock("b-0")!.children.map((child) => child.id)).toEqual([
+ "first",
+ "existing",
+ "last",
+ ]);
+ });
+
+ it("descends into a nested container that accepts the block", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ id: "g-0",
+ type: "grid",
+ children: [
+ { id: "c-0", type: "cell" },
+ { id: "c-1", type: "cell" },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ // `grid` itself only accepts `cell`s, so both placements have to find the
+ // leading/trailing cell rather than giving up.
+ editor.insertBlocks(
+ [{ id: "first", type: "paragraph" }],
+ "g-0",
+ "first-child",
+ );
+ editor.insertBlocks(
+ [{ id: "last", type: "paragraph" }],
+ "g-0",
+ "last-child",
+ );
+
+ const grid = editor.getBlock("g-0")!;
+ expect(grid.children[0].children.map((child: any) => child.id)).toContain(
+ "first",
+ );
+ expect(grid.children[1].children.map((child: any) => child.id)).toContain(
+ "last",
+ );
+ });
+
+ it("nests under a regular block, with or without existing children", () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "p-0", type: "paragraph", content: "Paragraph 0" },
+ ]);
+
+ editor.insertBlocks(
+ [{ id: "existing", type: "paragraph" }],
+ "p-0",
+ "last-child",
+ );
+ editor.insertBlocks(
+ [{ id: "first", type: "paragraph" }],
+ "p-0",
+ "first-child",
+ );
+
+ expect(editor.getBlock("p-0")!.children.map((child) => child.id)).toEqual([
+ "first",
+ "existing",
+ ]);
+ });
+
+ it("throws when the container has no room for the block", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ id: "s-0",
+ type: "single",
+ children: [{ id: "only", type: "paragraph" }],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ expect(() =>
+ editor.insertBlocks([{ type: "paragraph" }], "s-0", "last-child"),
+ ).toThrow(/does not accept it as a child/);
+ });
+
+ it("throws when a sibling placement isn't allowed either", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ id: "g-0",
+ type: "grid",
+ children: [
+ { id: "c-0", type: "cell" },
+ { id: "c-1", type: "cell" },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ // `grid`'s children are `cell`s only, so a paragraph can't become one's
+ // sibling. Previously this threw a raw ProseMirror `ReplaceError`.
+ expect(() =>
+ editor.insertBlocks([{ type: "paragraph" }], "c-0", "after"),
+ ).toThrow(/its parent does not accept it/);
+ });
+
+ it("throws when only the first of several blocks would fit", () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "e-0", type: "emptySingle", children: [] },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ // The container is empty and takes one child, so the first paragraph
+ // fits. Validating only that one used to let the batch through and fail
+ // later with a raw ProseMirror `ReplaceError`.
+ expect(() =>
+ editor.insertBlocks(
+ [{ type: "paragraph" }, { type: "paragraph" }],
+ "e-0",
+ "last-child",
+ ),
+ ).toThrow(/does not accept them as children/);
+
+ expect(editor.getBlock("e-0")!.children).toEqual([]);
+ });
+
+ it("still inserts a batch that fits in full", () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "b-0", type: "box", children: [] },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ editor.insertBlocks(
+ [
+ { id: "one", type: "paragraph" },
+ { id: "two", type: "paragraph" },
+ ],
+ "b-0",
+ "last-child",
+ );
+
+ expect(editor.getBlock("b-0")!.children.map((child) => child.id)).toEqual([
+ "one",
+ "two",
+ ]);
+ });
+});
diff --git a/packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.test.ts b/packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.test.ts
index ebe8ae9eff..532da5aaef 100644
--- a/packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.test.ts
+++ b/packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.test.ts
@@ -2,7 +2,10 @@ import { describe, expect, it } from "vite-plus/test";
import { getBlockInfoFromSelection } from "../../../getBlockInfoFromPos.js";
import { setupTestEnv } from "../../setupTestEnv.js";
-import { getParentBlockInfo, mergeBlocksCommand } from "./mergeBlocks.js";
+import { getParentBlockInfo } from "../../../getBlockInfoFromPos.js";
+import { getNodeById } from "../../../nodeUtil.js";
+import { containerSchema } from "../../containers/containers.fixture.js";
+import { mergeBlocksCommand } from "./mergeBlocks.js";
const getEditor = setupTestEnv();
@@ -14,7 +17,7 @@ function mergeBlocks(posBetweenBlocks: number) {
function getPosBeforeSelectedBlock() {
return getEditor().transact(
- (tr) => getBlockInfoFromSelection(tr).bnBlock.beforePos,
+ (tr) => getBlockInfoFromSelection(tr).block.beforePos,
);
}
@@ -145,3 +148,87 @@ describe("Test mergeBlocks", () => {
expect(ret).toBeFalsy();
});
});
+
+describe("Test mergeBlocks at container boundaries", () => {
+ const getContainerEditor = setupTestEnv({
+ schema: containerSchema,
+ document: [
+ { id: "before-callout", type: "paragraph", content: "Before callout" },
+ {
+ id: "callout-0",
+ type: "callout",
+ children: [
+ {
+ id: "callout-child-0",
+ type: "paragraph",
+ content: "Callout child 0",
+ },
+ {
+ id: "callout-child-1",
+ type: "paragraph",
+ content: "Callout child 1",
+ },
+ ],
+ },
+ { id: "after-callout", type: "paragraph", content: "After callout" },
+ ],
+ });
+
+ function mergeContainerBlocks(posBetweenBlocks: number) {
+ return getContainerEditor()._tiptapEditor.commands.command(
+ mergeBlocksCommand(posBetweenBlocks),
+ );
+ }
+
+ function getPosBefore(id: string) {
+ return getContainerEditor().transact((tr) => {
+ const node = getNodeById(id, tr.doc);
+ if (!node) {
+ throw new Error(`No block with id "${id}" in the test document`);
+ }
+ return node.posBeforeNode;
+ });
+ }
+
+ // A container's first child has no previous sibling, so there is nothing to
+ // merge it into. The block above it on screen sits outside the container.
+ it("Does not merge a container's first child out of the container", () => {
+ const originalDocument = getContainerEditor().document;
+ const ret = mergeContainerBlocks(getPosBefore("callout-child-0"));
+
+ expect(ret).toBeFalsy();
+ expect(getContainerEditor().document).toEqual(originalDocument);
+ });
+
+ // A container has no content of its own, so there is nothing to merge.
+ it("Does not merge a container into the block above it", () => {
+ const originalDocument = getContainerEditor().document;
+ const ret = mergeContainerBlocks(getPosBefore("callout-0"));
+
+ expect(ret).toBeFalsy();
+ expect(getContainerEditor().document).toEqual(originalDocument);
+ });
+
+ // `mergeBlocksCommand` treats a container like any other block with children
+ // and merges into its last descendant, which puts the merged text inside the
+ // container. Backspace never produces this, because
+ // `KeyboardShortcutsExtension` bails out when the previous sibling has no
+ // inline content and moves the block into the container instead. So this is
+ // the command's behaviour on its own, not the editor's; it is pinned here
+ // because `mergeBlocks.ts` documents the opposite.
+ it("Merges a block into the last descendant of the container above it", () => {
+ const ret = mergeContainerBlocks(getPosBefore("after-callout"));
+
+ expect(ret).toBeTruthy();
+
+ const document = getContainerEditor().document;
+
+ expect(document.map((block) => block.id)).toEqual([
+ "before-callout",
+ "callout-0",
+ ]);
+ expect(document[1].children[1].content).toEqual([
+ { type: "text", text: "Callout child 1After callout", styles: {} },
+ ]);
+ });
+});
diff --git a/packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.ts b/packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.ts
index ce1a9455db..c9ffb6003d 100644
--- a/packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.ts
+++ b/packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.ts
@@ -1,170 +1,11 @@
-import { Node } from "prosemirror-model";
import { EditorState } from "prosemirror-state";
import {
- BlockInfo,
- getBlockInfoFromResolvedPos,
+ getBlockInfoAt,
+ getLastDescendantBlockInfo,
+ getPrevBlockInfo,
} from "../../../getBlockInfoFromPos.js";
-/**
- * Returns the block info from the parent block
- * or undefined if we're at the root
- */
-export const getParentBlockInfo = (
- doc: Node,
- beforePos: number,
-): BlockInfo | undefined => {
- const $pos = doc.resolve(beforePos);
- const depth = $pos.depth - 1;
-
- if (depth < 1) {
- return undefined;
- }
-
- const parentBeforePos = $pos.before(depth);
- const parentNode = doc.resolve(parentBeforePos).nodeAfter;
-
- if (!parentNode) {
- return undefined;
- }
-
- if (!parentNode.type.spec.group?.includes("bnBlock")) {
- return getParentBlockInfo(doc, parentBeforePos);
- }
-
- const parentBlockInfo = getBlockInfoFromResolvedPos(
- doc.resolve(parentBeforePos),
- );
-
- return parentBlockInfo;
-};
-
-/**
- * Returns the block info from the sibling block before (above) the given block,
- * or undefined if the given block is the first sibling.
- */
-export const getPrevBlockInfo = (doc: Node, beforePos: number) => {
- const $pos = doc.resolve(beforePos);
-
- const indexInParent = $pos.index();
-
- if (indexInParent === 0) {
- return undefined;
- }
-
- const prevBlockBeforePos = $pos.posAtIndex(indexInParent - 1);
-
- const prevBlockInfo = getBlockInfoFromResolvedPos(
- doc.resolve(prevBlockBeforePos),
- );
- return prevBlockInfo;
-};
-
-/**
- * Returns the block info from the sibling block after (below) the given block,
- * or undefined if the given block is the last sibling.
- */
-export const getNextBlockInfo = (doc: Node, beforePos: number) => {
- const $pos = doc.resolve(beforePos);
-
- const indexInParent = $pos.index();
-
- if (indexInParent === $pos.node().childCount - 1) {
- return undefined;
- }
-
- const nextBlockBeforePos = $pos.posAtIndex(indexInParent + 1);
-
- const nextBlockInfo = getBlockInfoFromResolvedPos(
- doc.resolve(nextBlockBeforePos),
- );
- return nextBlockInfo;
-};
-
-/**
- * If a block has children like this:
- * A
- * - B
- * - C
- * -- D
- *
- * Then the bottom nested block returned is D.
- */
-export const getBottomNestedBlockInfo = (doc: Node, blockInfo: BlockInfo) => {
- while (blockInfo.childContainer) {
- const group = blockInfo.childContainer.node;
-
- const newPos = doc
- .resolve(blockInfo.childContainer.beforePos + 1)
- .posAtIndex(group.childCount - 1);
- blockInfo = getBlockInfoFromResolvedPos(doc.resolve(newPos));
- }
-
- return blockInfo;
-};
-
-const canMerge = (prevBlockInfo: BlockInfo, nextBlockInfo: BlockInfo) => {
- return (
- prevBlockInfo.isBlockContainer &&
- prevBlockInfo.blockContent.node.type.spec.content === "inline*" &&
- prevBlockInfo.blockContent.node.childCount > 0 &&
- nextBlockInfo.isBlockContainer &&
- nextBlockInfo.blockContent.node.type.spec.content === "inline*"
- );
-};
-
-const mergeBlocks = (
- state: EditorState,
- dispatch: ((args?: any) => any) | undefined,
- prevBlockInfo: BlockInfo,
- nextBlockInfo: BlockInfo,
-) => {
- // Un-nests all children of the next block.
- if (!nextBlockInfo.isBlockContainer) {
- throw new Error(
- `Attempted to merge block at position ${nextBlockInfo.bnBlock.beforePos} into previous block at position ${prevBlockInfo.bnBlock.beforePos}, but next block is not a block container`,
- );
- }
-
- // Removes a level of nesting all children of the next block by 1 level, if it contains both content and block
- // group nodes.
- if (nextBlockInfo.childContainer) {
- const childBlocksStart = state.doc.resolve(
- nextBlockInfo.childContainer.beforePos + 1,
- );
- const childBlocksEnd = state.doc.resolve(
- nextBlockInfo.childContainer.afterPos - 1,
- );
- const childBlocksRange = childBlocksStart.blockRange(childBlocksEnd);
-
- if (dispatch) {
- const pos = state.doc.resolve(nextBlockInfo.bnBlock.beforePos);
- state.tr.lift(childBlocksRange!, pos.depth);
- }
- }
-
- // Deletes the boundary between the two blocks. Can be thought of as
- // removing the closing tags of the first block and the opening tags of the
- // second one to stitch them together.
- if (dispatch) {
- if (!prevBlockInfo.isBlockContainer) {
- throw new Error(
- `Attempted to merge block at position ${nextBlockInfo.bnBlock.beforePos} into previous block at position ${prevBlockInfo.bnBlock.beforePos}, but previous block is not a block container`,
- );
- }
-
- // TODO: test merging between a columnList and paragraph, between two columnLists, and v.v.
- dispatch(
- state.tr.delete(
- prevBlockInfo.blockContent.afterPos - 1,
- nextBlockInfo.blockContent.beforePos + 1,
- ),
- );
- }
-
- return true;
-};
-
export const mergeBlocksCommand =
(posBetweenBlocks: number) =>
({
@@ -174,26 +15,75 @@ export const mergeBlocksCommand =
state: EditorState;
dispatch: ((args?: any) => any) | undefined;
}) => {
- const $pos = state.doc.resolve(posBetweenBlocks);
- const nextBlockInfo = getBlockInfoFromResolvedPos($pos);
+ const nextBlockInfo = getBlockInfoAt(state.doc, posBetweenBlocks);
const prevBlockInfo = getPrevBlockInfo(
state.doc,
- nextBlockInfo.bnBlock.beforePos,
+ nextBlockInfo.block.beforePos,
);
if (!prevBlockInfo) {
return false;
}
- const bottomNestedBlockInfo = getBottomNestedBlockInfo(
+ // The block we merge into is the last descendant of the previous block:
+ // visually, that's the block directly above the boundary.
+ const bottomNestedBlockInfo = getLastDescendantBlockInfo(
state.doc,
prevBlockInfo,
);
- if (!canMerge(bottomNestedBlockInfo, nextBlockInfo)) {
+ // Only inline-content blocks can merge, and merging into an empty block
+ // is handled elsewhere (by deleting the empty block instead). Merging
+ // into or out of container blocks (columnLists, callouts, ...) is
+ // intentionally unsupported; the container-boundary Backspace/Delete
+ // branches in `KeyboardShortcutsExtension` handle those cases by moving
+ // blocks across the boundary instead of merging their content.
+ if (
+ !bottomNestedBlockInfo.hasContent ||
+ bottomNestedBlockInfo.contentKind !== "inline" ||
+ bottomNestedBlockInfo.isContentEmpty ||
+ !nextBlockInfo.hasContent ||
+ nextBlockInfo.contentKind !== "inline"
+ ) {
return false;
}
- return mergeBlocks(state, dispatch, bottomNestedBlockInfo, nextBlockInfo);
+ // Un-nests the next block's children by one level, so they survive as
+ // siblings of the merged block rather than as children of a block that no
+ // longer exists once the boundary below is deleted.
+ //
+ // Note `state.tr` is tiptap's chainable state, whose getter returns the one
+ // transaction shared by the command chain (not a fresh `Transaction` like
+ // `EditorState.tr`), so this lift carries over into the `dispatch` below.
+ if (dispatch && nextBlockInfo.children) {
+ const childBlocksRange = state.doc
+ .resolve(nextBlockInfo.children.childrenStart)
+ .blockRange(state.doc.resolve(nextBlockInfo.children.childrenEnd));
+
+ if (!childBlocksRange) {
+ throw new Error(
+ "Children of a block are expected to form a block range",
+ );
+ }
+
+ state.tr.lift(
+ childBlocksRange,
+ state.doc.resolve(nextBlockInfo.block.beforePos).depth,
+ );
+ }
+
+ // Deletes the boundary between the two blocks. Can be thought of as
+ // removing the closing tags of the first block and the opening tags of the
+ // second one to stitch them together.
+ if (dispatch) {
+ dispatch(
+ state.tr.delete(
+ bottomNestedBlockInfo.contentEnd,
+ nextBlockInfo.contentStart,
+ ),
+ );
+ }
+
+ return true;
};
diff --git a/packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.test.ts b/packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.test.ts
index 61964a49ee..f9bba17c3f 100644
--- a/packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.test.ts
+++ b/packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.test.ts
@@ -3,7 +3,7 @@ import { CellSelection } from "prosemirror-tables";
import { describe, expect, it } from "vite-plus/test";
import {
- getBlockInfoAtNearest,
+ getBlockInfoNearPos,
getBlockInfoFromSelection,
getNodeId,
} from "../../../getBlockInfoFromPos.js";
@@ -18,12 +18,12 @@ const getEditor = setupTestEnv();
function makeSelectionSpanContent(selectionType: "text" | "node" | "cell") {
const blockInfo = getEditor().transact((tr) => getBlockInfoFromSelection(tr));
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
throw new Error(
`Selection points to a ${blockInfo.blockNoteType} node, not a blockContainer node`,
);
}
- const { blockContent } = blockInfo;
+ const { content } = blockInfo;
const editor = getEditor();
if (selectionType === "cell") {
@@ -31,22 +31,22 @@ function makeSelectionSpanContent(selectionType: "text" | "node" | "cell") {
tr.setSelection(
CellSelection.create(
tr.doc,
- tr.doc.resolve(blockContent.beforePos + 3).before(),
- tr.doc.resolve(blockContent.afterPos - 3).before(),
+ tr.doc.resolve(content.beforePos + 3).before(),
+ tr.doc.resolve(content.afterPos - 3).before(),
),
),
);
} else if (selectionType === "node") {
editor.transact((tr) =>
- tr.setSelection(NodeSelection.create(tr.doc, blockContent.beforePos)),
+ tr.setSelection(NodeSelection.create(tr.doc, content.beforePos)),
);
} else {
editor.transact((tr) =>
tr.setSelection(
TextSelection.create(
tr.doc,
- blockContent.beforePos + 1,
- blockContent.afterPos - 1,
+ content.beforePos + 1,
+ content.afterPos - 1,
),
),
);
@@ -223,11 +223,11 @@ describe("Test moveBlocksUp", () => {
const { anchorBlockId, headBlockId } = getEditor().transact((tr) => ({
anchorBlockId: getNodeId(
- getBlockInfoAtNearest(tr, tr.selection.anchor).bnBlock.node,
+ getBlockInfoNearPos(tr, tr.selection.anchor).block.node,
tr.doc,
),
headBlockId: getNodeId(
- getBlockInfoAtNearest(tr, tr.selection.head).bnBlock.node,
+ getBlockInfoNearPos(tr, tr.selection.head).block.node,
tr.doc,
),
}));
@@ -347,11 +347,11 @@ describe("Test moveBlocksDown", () => {
const { anchorBlockId, headBlockId } = getEditor().transact((tr) => ({
anchorBlockId: getNodeId(
- getBlockInfoAtNearest(tr, tr.selection.anchor).bnBlock.node,
+ getBlockInfoNearPos(tr, tr.selection.anchor).block.node,
tr.doc,
),
headBlockId: getNodeId(
- getBlockInfoAtNearest(tr, tr.selection.head).bnBlock.node,
+ getBlockInfoNearPos(tr, tr.selection.head).block.node,
tr.doc,
),
}));
diff --git a/packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.ts b/packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.ts
index 71598b7d69..267a23b27c 100644
--- a/packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.ts
+++ b/packages/core/src/api/blockManipulation/commands/moveBlocks/moveBlocks.ts
@@ -1,3 +1,4 @@
+import type { Node, Schema } from "prosemirror-model";
import {
NodeSelection,
Selection,
@@ -10,13 +11,43 @@ import { Block } from "../../../../blocks/defaultBlocks.js";
import type { BlockNoteEditor } from "../../../../editor/BlockNoteEditor";
import { BlockIdentifier } from "../../../../schema/index.js";
import {
- getBlockInfoAtNearest,
+ isBlockGroupInsertable,
+ isContainerNode,
+ isSealed,
+} from "../../../../schema/blocks/children.js";
+import {
+ getBlockInfoNearPos,
getNodeId,
} from "../../../getBlockInfoFromPos.js";
import { getNodeById } from "../../../nodeUtil.js";
-import { insertBlocks } from "../insertBlocks/insertBlocks.js";
+import { getInsertionPos, insertBlocks } from "../insertBlocks/insertBlocks.js";
import { removeAndInsertBlocks } from "../replaceBlocks/replaceBlocks.js";
+/**
+ * Dissolves `placement: "containerOnly"` blocks into their children.
+ *
+ * A `containerOnly` block (a `column`, say) is defined only in terms of the
+ * container that holds it, so it can't land anywhere a regular block goes —
+ * moving one out of its container moves its children instead. Every other
+ * block passes through as itself.
+ */
+function dissolveContainerOnlyBlocks(
+ blocks: Block[],
+ pmSchema: Schema,
+): Block[] {
+ return blocks.flatMap((block) => {
+ const nodeType = pmSchema.nodes[block.type];
+ // A container denied the `blockGroupChild` group is one declared
+ // `placement: "containerOnly"`.
+ const isContainerOnly =
+ isContainerNode(nodeType) && !isBlockGroupInsertable(nodeType);
+
+ return isContainerOnly
+ ? dissolveContainerOnlyBlocks(block.children, pmSchema)
+ : [block];
+ });
+}
+
type BlockSelectionData = (
| {
type: "text";
@@ -49,18 +80,18 @@ function getBlockSelectionData(
editor: BlockNoteEditor,
): BlockSelectionData {
return editor.transact((tr) => {
- const anchorBlockPosInfo = getBlockInfoAtNearest(tr, tr.selection.anchor);
+ const anchorBlockPosInfo = getBlockInfoNearPos(tr, tr.selection.anchor);
- const anchorBlockId = getNodeId(anchorBlockPosInfo.bnBlock.node, tr.doc);
+ const anchorBlockId = getNodeId(anchorBlockPosInfo.block.node, tr.doc);
if (tr.selection instanceof CellSelection) {
return {
type: "cell" as const,
anchorBlockId,
anchorCellOffset:
- tr.selection.$anchorCell.pos - anchorBlockPosInfo.bnBlock.beforePos,
+ tr.selection.$anchorCell.pos - anchorBlockPosInfo.block.beforePos,
headCellOffset:
- tr.selection.$headCell.pos - anchorBlockPosInfo.bnBlock.beforePos,
+ tr.selection.$headCell.pos - anchorBlockPosInfo.block.beforePos,
};
} else if (tr.selection instanceof NodeSelection) {
return {
@@ -68,15 +99,14 @@ function getBlockSelectionData(
anchorBlockId,
};
} else {
- const headBlockPosInfo = getBlockInfoAtNearest(tr, tr.selection.head);
+ const headBlockPosInfo = getBlockInfoNearPos(tr, tr.selection.head);
return {
type: "text" as const,
anchorBlockId,
- headBlockId: getNodeId(headBlockPosInfo.bnBlock.node, tr.doc),
- anchorOffset:
- tr.selection.anchor - anchorBlockPosInfo.bnBlock.beforePos,
- headOffset: tr.selection.head - headBlockPosInfo.bnBlock.beforePos,
+ headBlockId: getNodeId(headBlockPosInfo.block.node, tr.doc),
+ anchorOffset: tr.selection.anchor - anchorBlockPosInfo.block.beforePos,
+ headOffset: tr.selection.head - headBlockPosInfo.block.beforePos,
};
}
});
@@ -131,16 +161,6 @@ function updateBlockSelectionFromData(
tr.setSelection(selection);
}
-// Replaces top-level `column` blocks with their children, as a `column` is not
-// a valid block outside a `columnList`. Other blocks are returned as-is.
-function flattenColumns(
- blocks: Block[],
-): Block[] {
- return blocks.flatMap((block) =>
- block.type === "column" ? block.children : [block],
- );
-}
-
/**
* Removes the given blocks from the editor, then inserts them before/after a
* reference block.
@@ -169,10 +189,10 @@ export function moveBlocks(
//
// When the non-empty block is moved up, the column is seen as empty and
// collapsed in the removal step, so the following insertion fails.
- removeAndInsertBlocks(tr, blocks, [], { fixColumns: false });
+ removeAndInsertBlocks(tr, blocks, [], { fixContainers: false });
insertBlocks(
tr,
- flattenColumns(blocks),
+ dissolveContainerOnlyBlocks(blocks, editor.pmSchema),
referenceBlock,
placement,
);
@@ -207,12 +227,66 @@ export function moveSelectedBlocksAndSelection(
});
}
-// Checks if a block is in a valid place after being moved. This check is
-// primitive at the moment and only returns false if the block's parent is a
-// `columnList` block. This is because regular blocks cannot be direct children
-// of `columnList` blocks.
-function checkPlacementIsValid(parentBlock?: Block): boolean {
- return !parentBlock || parentBlock.type !== "columnList";
+// The nearest sealed container a position sits in, or `undefined` if there
+// isn't one.
+function sealedAncestorId(doc: Node, pos: number): string | undefined {
+ const $pos = doc.resolve(pos);
+
+ for (let depth = $pos.depth; depth > 0; depth--) {
+ const ancestor = $pos.node(depth);
+ if (isSealed(ancestor)) {
+ return ancestor.attrs.id;
+ }
+ }
+
+ return undefined;
+}
+
+// Checks if a regular block would be in a valid place after being moved
+// before/after `referenceBlock`. A regular block nests under any non-container
+// block (it goes into that block's `blockGroup`), but a container block (e.g. a
+// `columnList`) only accepts what its content expression allows.
+//
+// Deferred to `getInsertionPos` so that "can a block go here?" has exactly
+// one answer, shared with `insertBlocks`, and comes from the schema rather
+// than from a rule restated here.
+function checkPlacementIsValid(
+ editor: BlockNoteEditor,
+ referenceBlock: Block,
+ placement: "before" | "after",
+ movedBlock: Block,
+): boolean {
+ // The PM node type to validate the destination against: the first block
+ // `moveBlocks` would actually insert, which is `movedBlock` itself unless it
+ // dissolves. A container (e.g. a `callout`) is inserted as its own node
+ // type; anything else goes in as a generic `blockContainer` wrapper.
+ const first = dissolveContainerOnlyBlocks([movedBlock], editor.pmSchema)[0];
+ const firstType = first ? editor.pmSchema.nodes[first.type] : undefined;
+ const nodeType =
+ firstType && isContainerNode(firstType)
+ ? firstType
+ : editor.pmSchema.nodes["blockContainer"];
+
+ return editor.transact((tr) => {
+ const posInfo = getNodeById(referenceBlock.id, tr.doc);
+ const movedPosInfo = getNodeById(movedBlock.id, tr.doc);
+ if (!posInfo || !movedPosInfo) {
+ return false;
+ }
+
+ const target = getInsertionPos(tr.doc, posInfo, placement, nodeType);
+ if (!target) {
+ return false;
+ }
+
+ // Moving is a gesture, so it can't take a block across a seal: the block
+ // and its destination have to sit inside the same sealed container (or
+ // outside any of them).
+ return (
+ sealedAncestorId(tr.doc, target.pos) ===
+ sealedAncestorId(tr.doc, movedPosInfo.posBeforeNode)
+ );
+ });
}
// Gets the placement for moving a block up. This has 3 cases:
@@ -227,6 +301,7 @@ function checkPlacementIsValid(parentBlock?: Block): boolean {
// the block is already at the top of the document.
function getMoveUpPlacement(
editor: BlockNoteEditor,
+ movedBlock: Block,
prevBlock?: Block,
parentBlock?: Block,
):
@@ -253,10 +328,11 @@ function getMoveUpPlacement(
return undefined;
}
- const referenceBlockParent = editor.getParentBlock(referenceBlock);
- if (!checkPlacementIsValid(referenceBlockParent)) {
+ if (!checkPlacementIsValid(editor, referenceBlock, placement, movedBlock)) {
+ const referenceBlockParent = editor.getParentBlock(referenceBlock);
return getMoveUpPlacement(
editor,
+ movedBlock,
placement === "after"
? referenceBlock
: editor.getPrevBlock(referenceBlock),
@@ -279,6 +355,7 @@ function getMoveUpPlacement(
// the block is already at the bottom of the document.
function getMoveDownPlacement(
editor: BlockNoteEditor,
+ movedBlock: Block,
nextBlock?: Block,
parentBlock?: Block,
):
@@ -305,10 +382,11 @@ function getMoveDownPlacement(
return undefined;
}
- const referenceBlockParent = editor.getParentBlock(referenceBlock);
- if (!checkPlacementIsValid(referenceBlockParent)) {
+ if (!checkPlacementIsValid(editor, referenceBlock, placement, movedBlock)) {
+ const referenceBlockParent = editor.getParentBlock(referenceBlock);
return getMoveDownPlacement(
editor,
+ movedBlock,
placement === "before"
? referenceBlock
: editor.getNextBlock(referenceBlock),
@@ -338,6 +416,7 @@ export function moveBlocksUp(
const moveUpPlacement = getMoveUpPlacement(
editor,
+ sourceBlock,
editor.getPrevBlock(sourceBlock),
editor.getParentBlock(sourceBlock),
);
@@ -369,20 +448,28 @@ export function moveBlocksDown(
) {
editor.transact(() => {
let sourceBlock: Block | undefined;
+ // The block whose position anchors the move (the last of a selection when
+ // moving down) vs. the first block that gets inserted, which is what the
+ // placement check must validate against.
+ let firstMovedBlock: Block | undefined;
if (blockIdentifier) {
sourceBlock = editor.getBlock(blockIdentifier);
if (!sourceBlock) {
return;
}
+ firstMovedBlock = sourceBlock;
} else {
const selection = editor.getSelection();
sourceBlock =
selection?.blocks[selection?.blocks.length - 1] ||
editor.getTextCursorPosition().block;
+ firstMovedBlock =
+ selection?.blocks[0] || editor.getTextCursorPosition().block;
}
const moveDownPlacement = getMoveDownPlacement(
editor,
+ firstMovedBlock,
editor.getNextBlock(sourceBlock),
editor.getParentBlock(sourceBlock),
);
diff --git a/packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.test.ts b/packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.test.ts
index 8247e9391c..da69161218 100644
--- a/packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.test.ts
+++ b/packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.test.ts
@@ -3,6 +3,7 @@ import { describe, expect, it } from "vite-plus/test";
import { afterAll, beforeAll } from "vite-plus/test";
import { PartialBlock } from "../../../../blocks/defaultBlocks.js";
import { BlockNoteEditor } from "../../../../editor/BlockNoteEditor.js";
+import { containerSchema } from "../../containers/containers.fixture.js";
/**
* Custom test setup with a document designed to reproduce nesting/unnesting bugs.
@@ -646,6 +647,132 @@ describe("unnestBlock / liftListItem", () => {
});
});
+// A second editor, on a schema that has container blocks. `setupNestTestEnv`
+// builds a default-schema editor, which can't express any of the cases below.
+function setupContainerNestTestEnv() {
+ let editor: BlockNoteEditor;
+ const div = document.createElement("div");
+
+ beforeAll(() => {
+ editor = BlockNoteEditor.create({ schema: containerSchema });
+ editor.mount(div);
+ });
+
+ afterAll(() => {
+ editor._tiptapEditor.destroy();
+ editor = undefined as any;
+ });
+
+ return (doc: PartialBlock[]) => {
+ editor.replaceBlocks(editor.document, doc);
+ return editor;
+ };
+}
+
+// `canNestBlock` and `canUnnestBlock` run the real command on a transaction
+// that is thrown away, rather than restating its preconditions. The cases here
+// are the ones where the old, restated preconditions gave the wrong answer:
+// they looked at a previous sibling's mere existence and at the block's depth,
+// neither of which knows anything about containers.
+describe("canNestBlock / canUnnestBlock around containers", () => {
+ const withContainerEditor = setupContainerNestTestEnv();
+
+ it("Reports that a block cannot be nested under a container sibling", () => {
+ const editor = withContainerEditor([
+ {
+ id: "callout-0",
+ type: "callout",
+ children: [
+ { id: "callout-child", type: "paragraph", content: "Callout child" },
+ ],
+ },
+ { id: "paragraph-0", type: "paragraph", content: "Paragraph 0" },
+ ]);
+
+ editor.setTextCursorPosition("paragraph-0", "start");
+
+ const before = editor.document;
+ expect(editor.canNestBlock()).toBe(false);
+
+ // And the answer matches what nesting actually does.
+ editor.nestBlock();
+ expect(editor.document).toEqual(before);
+ });
+
+ it("Reports that a container's child cannot be unnested out of it", () => {
+ const editor = withContainerEditor([
+ {
+ id: "callout-0",
+ type: "callout",
+ children: [
+ { id: "callout-child", type: "paragraph", content: "Callout child" },
+ ],
+ },
+ ]);
+
+ editor.setTextCursorPosition("callout-child", "start");
+
+ const before = editor.document;
+ expect(editor.canUnnestBlock()).toBe(false);
+
+ editor.unnestBlock();
+ expect(editor.document).toEqual(before);
+ });
+
+ it("Reports that a block with a plain previous sibling can be nested", () => {
+ const editor = withContainerEditor([
+ { id: "paragraph-0", type: "paragraph", content: "Paragraph 0" },
+ { id: "paragraph-1", type: "paragraph", content: "Paragraph 1" },
+ ]);
+
+ editor.setTextCursorPosition("paragraph-1", "start");
+
+ const before = editor.document;
+ expect(editor.canNestBlock()).toBe(true);
+ // The probe runs the command on a transaction it never dispatches, so
+ // answering must not change the document.
+ expect(editor.document).toEqual(before);
+
+ editor.nestBlock();
+ expect(editor.getBlock("paragraph-0")!.children.map((c) => c.id)).toEqual([
+ "paragraph-1",
+ ]);
+ expect(editor.canUnnestBlock()).toBe(true);
+ });
+
+ it("Nests and unnests a block inside a container's children", () => {
+ const editor = withContainerEditor([
+ {
+ id: "callout-0",
+ type: "callout",
+ children: [
+ { id: "child-0", type: "paragraph", content: "Child 0" },
+ { id: "child-1", type: "paragraph", content: "Child 1" },
+ ],
+ },
+ ]);
+
+ const before = editor.document;
+
+ editor.setTextCursorPosition("child-1", "start");
+ expect(editor.canNestBlock()).toBe(true);
+ editor.nestBlock();
+
+ expect(editor.getBlock("callout-0")!.children.map((c) => c.id)).toEqual([
+ "child-0",
+ ]);
+ expect(editor.getBlock("child-0")!.children.map((c) => c.id)).toEqual([
+ "child-1",
+ ]);
+
+ editor.setTextCursorPosition("child-1", "start");
+ expect(editor.canUnnestBlock()).toBe(true);
+ editor.unnestBlock();
+
+ expect(editor.document).toEqual(before);
+ });
+});
+
/** Recursively collects all block IDs from a document */
function flattenBlockIds(blocks: any[]): string[] {
const ids: string[] = [];
diff --git a/packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.ts b/packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.ts
index a0f76fdff0..b7b091b8f4 100644
--- a/packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.ts
+++ b/packages/core/src/api/blockManipulation/commands/nestBlock/nestBlock.ts
@@ -3,7 +3,6 @@ import { Transaction } from "prosemirror-state";
import { canJoin, liftTarget, ReplaceAroundStep } from "prosemirror-transform";
import { BlockNoteEditor } from "../../../../editor/BlockNoteEditor.js";
-import { getBlockInfoFromSelection } from "../../../getBlockInfoFromPos.js";
/**
* Modified version of prosemirror-schema-list's sinkItem.
@@ -19,9 +18,7 @@ function sinkItem(tr: Transaction, itemType: NodeType, groupType: NodeType) {
const { $from, $to } = tr.selection;
const range = $from.blockRange(
$to,
- (node) =>
- node.childCount > 0 &&
- (node.type.name === "blockGroup" || node.type.name === "column"), // change 1
+ (node) => node.childCount > 0 && node.type.isInGroup("childContainer"), // change 1
);
if (!range) {
return false;
@@ -64,14 +61,17 @@ function sinkItem(tr: Transaction, itemType: NodeType, groupType: NodeType) {
return true;
}
-export function nestBlock(editor: BlockNoteEditor) {
- return editor.transact((tr) => {
- return sinkItem(
+function nestCommand(editor: BlockNoteEditor) {
+ return (tr: Transaction) =>
+ sinkItem(
tr,
editor.pmSchema.nodes["blockContainer"],
editor.pmSchema.nodes["blockGroup"],
);
- });
+}
+
+export function nestBlock(editor: BlockNoteEditor) {
+ return editor.transact(nestCommand(editor));
}
/**
@@ -163,9 +163,7 @@ export function liftItem(
const { $from, $to } = tr.selection;
const range = $from.blockRange(
$to,
- (node) =>
- node.childCount > 0 &&
- (node.type.name === "blockGroup" || node.type.name === "column"), // change 1
+ (node) => node.childCount > 0 && node.type.isInGroup("childContainer"), // change 1
);
if (!range) {
return false;
@@ -181,28 +179,28 @@ export function liftItem(
return false;
}
-export function unnestBlock(editor: BlockNoteEditor) {
- return editor.transact((tr) =>
+function unnestCommand(editor: BlockNoteEditor) {
+ return (tr: Transaction) =>
liftItem(
tr,
editor.pmSchema.nodes["blockContainer"],
editor.pmSchema.nodes["blockGroup"],
- ),
- );
+ );
}
-export function canNestBlock(editor: BlockNoteEditor) {
- return editor.transact((tr) => {
- const { bnBlock: blockContainer } = getBlockInfoFromSelection(tr);
+export function unnestBlock(editor: BlockNoteEditor) {
+ return editor.transact(unnestCommand(editor));
+}
- return tr.doc.resolve(blockContainer.beforePos).nodeBefore !== null;
- });
+// `canExec` hands the command a transaction it never dispatches, so "can I
+// nest?" is answered by nesting and throwing the result away. A second
+// statement of the preconditions would drift from the command it describes —
+// and did: it read a previous sibling's mere existence, so a container block
+// before the cursor enabled the button while `nestBlock` did nothing.
+export function canNestBlock(editor: BlockNoteEditor) {
+ return editor.canExec((state) => nestCommand(editor)(state.tr));
}
export function canUnnestBlock(editor: BlockNoteEditor) {
- return editor.transact((tr) => {
- const { bnBlock: blockContainer } = getBlockInfoFromSelection(tr);
-
- return tr.doc.resolve(blockContainer.beforePos).depth > 1;
- });
+ return editor.canExec((state) => unnestCommand(editor)(state.tr));
}
diff --git a/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.test.ts b/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.test.ts
index 5a968c49bf..4951b09fb4 100644
--- a/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.test.ts
+++ b/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, it } from "vite-plus/test";
import { setupTestEnv } from "../../setupTestEnv.js";
+import { updateBlock } from "../updateBlock/updateBlock.js";
import { removeAndInsertBlocks } from "./replaceBlocks.js";
import { BlockNoteEditor } from "../../../../editor/BlockNoteEditor.js";
import { PartialBlock } from "../../../../blocks/defaultBlocks.js";
@@ -233,3 +234,73 @@ describe("Test replaceBlocks", () => {
expect(getEditor().document).toMatchSnapshot();
});
});
+
+// `removeAndInsertBlocks` walks the document while mutating it, so the
+// positions it reads go stale as it goes. It corrects for that with
+// `tr.mapping.slice(stepsBefore)`, where `stepsBefore` is the step count on
+// entry. The slice is what makes the function safe to call on a transaction
+// that already carries steps: an unsliced `tr.mapping` would re-apply the
+// caller's earlier steps to positions that already account for them, and the
+// resulting delete ranges would land on the wrong nodes.
+describe("Test replaceBlocks on a transaction that already has steps", () => {
+ it("Removes the right blocks across two calls in one transaction", () => {
+ const editor = getEditor();
+ const before = editor.document;
+
+ editor.transact((tr) => {
+ removeAndInsertBlocks(tr, ["paragraph-0"], []);
+ removeAndInsertBlocks(tr, ["paragraph-2"], []);
+ });
+
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+ expect(editor.document).toEqual(
+ before.filter(
+ (block) => block.id !== "paragraph-0" && block.id !== "paragraph-2",
+ ),
+ );
+ });
+
+ it("Removes the right block after the caller has already updated one", () => {
+ const editor = getEditor();
+ const before = editor.document;
+
+ editor.transact((tr) => {
+ // Changes the size of a block that sits before the one removed below,
+ // so the removal's positions are only correct if the earlier step is
+ // accounted for exactly once.
+ updateBlock(tr, "paragraph-0", {
+ type: "heading",
+ content: "Updated heading",
+ });
+ const inserted: PartialBlock[] = [
+ { id: "inserted-paragraph", type: "paragraph", content: "Inserted" },
+ ];
+ removeAndInsertBlocks(tr, ["paragraph-2"], inserted);
+ });
+
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+
+ const updated = editor.getBlock("paragraph-0")!;
+ expect(updated.type).toBe("heading");
+ expect(updated.content).toEqual([
+ { type: "text", text: "Updated heading", styles: {} },
+ ]);
+
+ expect(editor.document.map((block) => block.id)).toEqual(
+ before.map((block) =>
+ block.id === "paragraph-2" ? "inserted-paragraph" : block.id,
+ ),
+ );
+ // Every block the two operations didn't target is left exactly as it was.
+ expect(
+ editor.document.filter(
+ (block) =>
+ block.id !== "paragraph-0" && block.id !== "inserted-paragraph",
+ ),
+ ).toEqual(
+ before.filter(
+ (block) => block.id !== "paragraph-0" && block.id !== "paragraph-2",
+ ),
+ );
+ });
+});
diff --git a/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.ts b/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.ts
index d9e1e72981..3b8a364c2c 100644
--- a/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.ts
+++ b/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.ts
@@ -11,7 +11,8 @@ import type {
import { blockToNode } from "../../../nodeConversions/blockToNode.js";
import { nodeToBlock } from "../../../nodeConversions/nodeToBlock.js";
import { getPmSchema } from "../../../pmUtil.js";
-import { fixColumnList } from "./util/fixColumnList.js";
+import { fixContainersById } from "../../containers/fixContainer.js";
+import { getAncestorContainers } from "../../containers/containerNav.js";
export function removeAndInsertBlocks<
BSchema extends BlockSchema,
@@ -22,7 +23,7 @@ export function removeAndInsertBlocks<
blocksToRemove: BlockIdentifier[],
blocksToInsert: PartialBlock[],
options: {
- fixColumns?: boolean;
+ fixContainers?: boolean;
} = {},
): {
insertedBlocks: Block[];
@@ -43,13 +44,21 @@ export function removeAndInsertBlocks<
),
);
const removedBlocks: Block[] = [];
- const columnListPositions = new Set();
+ // Ancestor containers of removed blocks, to repair afterwards. Tracked by
+ // node id (not position) since the removals and earlier repairs shift
+ // positions; recorded with their depth so repairs run deepest-first.
+ const containersToFix: { id: string; depth: number }[] = [];
const idOfFirstBlock =
typeof blocksToRemove[0] === "string"
? blocksToRemove[0]
: blocksToRemove[0].id;
- let removedSize = 0;
+
+ // The walk below reads the document as it is now, but mutates it as it
+ // goes, so its positions go stale. `tr.mapping` already tracks exactly
+ // that; sliced from here so it ignores steps the caller added earlier.
+ const stepsBefore = tr.steps.length;
+ const mapPos = (pos: number) => tr.mapping.slice(stepsBefore).map(pos);
tr.doc.descendants((node, pos) => {
// Skips traversing nodes after all target blocks have been removed.
@@ -73,39 +82,35 @@ export function removeAndInsertBlocks<
idsOfBlocksToRemove.delete(nodeId);
if (blocksToInsert.length > 0 && nodeId === idOfFirstBlock) {
- const oldDocSize = tr.doc.nodeSize;
- tr.insert(pos, nodesToInsert);
- const newDocSize = tr.doc.nodeSize;
-
- removedSize += oldDocSize - newDocSize;
+ tr.insert(mapPos(pos), nodesToInsert);
}
- const oldDocSize = tr.doc.nodeSize;
+ const $pos = tr.doc.resolve(mapPos(pos));
- const $pos = tr.doc.resolve(pos - removedSize);
-
- if ($pos.node().type.name === "column") {
- columnListPositions.add($pos.before(-1));
- } else if ($pos.node().type.name === "columnList") {
- columnListPositions.add($pos.before());
+ for (const container of getAncestorContainers($pos.doc, $pos.pos)) {
+ if (!containersToFix.some((c) => c.id === container.id)) {
+ containersToFix.push(container);
+ }
}
+ // When the block is the only child of a nested `blockGroup`, delete the
+ // group with it (`blockGroup` acting as a `min: 1, whenEmptied: "unwrap"`
+ // container). This can't route through `fixContainer`: repair runs after
+ // the delete, and by then ProseMirror's replace-fitting has padded the
+ // `blockGroupChild+` group with a fresh empty `blockContainer`
+ // indistinguishable from an intentional one. Only here, before the
+ // delete, is "this was the group's last child" still knowable.
+ const parent = $pos.node();
if (
- $pos.node().type.name === "blockGroup" &&
+ parent.type.name === "blockGroup" &&
$pos.node($pos.depth - 1).type.name !== "doc" &&
- $pos.node().childCount === 1
+ parent.childCount === 1
) {
- // Checks if the block is the only child of a parent `blockGroup` node.
- // In this case, we need to delete the parent `blockGroup` node instead
- // of just the `blockContainer`.
tr.delete($pos.before(), $pos.after());
} else {
- tr.delete(pos - removedSize, pos - removedSize + node.nodeSize);
+ tr.delete($pos.pos, $pos.pos + node.nodeSize);
}
- const newDocSize = tr.doc.nodeSize;
- removedSize += oldDocSize - newDocSize;
-
return false;
});
@@ -119,11 +124,12 @@ export function removeAndInsertBlocks<
);
}
- // Collapses empty columns/columnLists. Callers where the removal isn't a
- // deletion can opt out - e.g. `moveBlocks` re-inserts the blocks elsewhere
- // and deliberately leaves emptied columns as-is.
- if (options.fixColumns !== false) {
- columnListPositions.forEach((pos) => fixColumnList(tr, pos));
+ // Repairs the containers the removed blocks lived in (e.g. collapses
+ // emptied columns/columnLists), deepest-first. Callers where the removal
+ // isn't a deletion can opt out, e.g. `moveBlocks` re-inserts the blocks
+ // elsewhere and deliberately leaves emptied containers as-is.
+ if (options.fixContainers !== false) {
+ fixContainersById(tr, containersToFix);
}
// Converts the nodes created from `blocksToInsert` into full `Block`s.
diff --git a/packages/core/src/api/blockManipulation/commands/replaceBlocks/util/fixColumnList.ts b/packages/core/src/api/blockManipulation/commands/replaceBlocks/util/fixColumnList.ts
deleted file mode 100644
index 3097851f47..0000000000
--- a/packages/core/src/api/blockManipulation/commands/replaceBlocks/util/fixColumnList.ts
+++ /dev/null
@@ -1,173 +0,0 @@
-import { Slice, type Node } from "prosemirror-model";
-import { type Transaction } from "prosemirror-state";
-import { ReplaceAroundStep } from "prosemirror-transform";
-
-/**
- * Checks if a `column` node is empty, i.e. if it has only a single empty
- * paragraph.
- * @param column The column to check.
- * @returns Whether the column is empty.
- */
-export function isEmptyColumn(column: Node) {
- if (!column || column.type.name !== "column") {
- throw new Error("Invalid columnPos: does not point to column node.");
- }
-
- const blockContainer = column.firstChild;
- if (!blockContainer) {
- throw new Error("Invalid column: does not have child node.");
- }
-
- const blockContent = blockContainer.firstChild;
- if (!blockContent) {
- throw new Error("Invalid blockContainer: does not have child node.");
- }
-
- return (
- column.childCount === 1 &&
- blockContainer.childCount === 1 &&
- blockContent.type.name === "paragraph" &&
- blockContent.content.content.length === 0
- );
-}
-
-/**
- * Removes all empty `column` nodes in a `columnList`. A `column` node is empty
- * if it has only a single empty block. If, however, removing the `column`s
- * leaves the `columnList` that has fewer than two, ProseMirror will re-add
- * empty columns.
- * @param tr The `Transaction` to add the changes to.
- * @param columnListPos The position just before the `columnList` node.
- */
-export function removeEmptyColumns(tr: Transaction, columnListPos: number) {
- const $columnListPos = tr.doc.resolve(columnListPos);
- const columnList = $columnListPos.nodeAfter;
- if (!columnList || columnList.type.name !== "columnList") {
- throw new Error(
- "Invalid columnListPos: does not point to columnList node.",
- );
- }
-
- for (
- let columnIndex = columnList.childCount - 1;
- columnIndex >= 0;
- columnIndex--
- ) {
- const columnPos = tr.doc
- .resolve($columnListPos.pos + 1)
- .posAtIndex(columnIndex);
- const $columnPos = tr.doc.resolve(columnPos);
- const column = $columnPos.nodeAfter;
- if (!column || column.type.name !== "column") {
- throw new Error("Invalid columnPos: does not point to column node.");
- }
-
- if (isEmptyColumn(column)) {
- tr.delete(columnPos, columnPos + column.nodeSize);
- }
- }
-}
-
-/**
- * Fixes potential issues in a `columnList` node after a
- * `blockContainer`/`column` node is (re)moved from it:
- *
- * - Removes all empty `column` nodes. A `column` node is empty if it has only
- * a single empty block.
- * - If all but one `column` nodes are empty, replaces the `columnList` with
- * the content of the non-empty `column`.
- * - If all `column` nodes are empty, removes the `columnList` entirely.
- * @param tr The `Transaction` to add the changes to.
- * @param columnListPos
- * @returns The position just before the `columnList` node.
- */
-export function fixColumnList(tr: Transaction, columnListPos: number) {
- removeEmptyColumns(tr, columnListPos);
-
- const $columnListPos = tr.doc.resolve(columnListPos);
- const columnList = $columnListPos.nodeAfter;
- if (!columnList || columnList.type.name !== "columnList") {
- throw new Error(
- "Invalid columnListPos: does not point to columnList node.",
- );
- }
-
- if (columnList.childCount > 2) {
- // Do nothing if the `columnList` has more than two non-empty `column`s. In
- // the case that the `columnList` has exactly two columns, we may need to
- // still remove it, as it's possible that one or both columns are empty.
- // This is because after `removeEmptyColumns` is called, if the
- // `columnList` has fewer than two `column`s, ProseMirror will re-add empty
- // `column`s until there are two total, in order to fit the schema.
- return;
- }
-
- if (columnList.childCount < 2) {
- // Throw an error if the `columnList` has fewer than two columns. After
- // `removeEmptyColumns` is called, if the `columnList` has fewer than two
- // `column`s, ProseMirror will re-add empty `column`s until there are two
- // total, in order to fit the schema. So if there are fewer than two here,
- // either the schema, or ProseMirror's internals, must have changed.
- throw new Error("Invalid columnList: contains fewer than two children.");
- }
-
- const firstColumnBeforePos = columnListPos + 1;
- const $firstColumnBeforePos = tr.doc.resolve(firstColumnBeforePos);
- const firstColumn = $firstColumnBeforePos.nodeAfter;
-
- const lastColumnAfterPos = columnListPos + columnList.nodeSize - 1;
- const $lastColumnAfterPos = tr.doc.resolve(lastColumnAfterPos);
- const lastColumn = $lastColumnAfterPos.nodeBefore;
-
- if (!firstColumn || !lastColumn) {
- throw new Error("Invalid columnList: does not contain children.");
- }
-
- const firstColumnEmpty = isEmptyColumn(firstColumn);
- const lastColumnEmpty = isEmptyColumn(lastColumn);
-
- if (firstColumnEmpty && lastColumnEmpty) {
- // Removes `columnList`
- tr.delete(columnListPos, columnListPos + columnList.nodeSize);
-
- return;
- }
-
- if (firstColumnEmpty) {
- tr.step(
- new ReplaceAroundStep(
- // Replaces `columnList`.
- columnListPos,
- columnListPos + columnList.nodeSize,
- // Replaces with content of last `column`.
- lastColumnAfterPos - lastColumn.nodeSize + 1,
- lastColumnAfterPos - 1,
- // Doesn't append anything.
- Slice.empty,
- 0,
- false,
- ),
- );
-
- return;
- }
-
- if (lastColumnEmpty) {
- tr.step(
- new ReplaceAroundStep(
- // Replaces `columnList`.
- columnListPos,
- columnListPos + columnList.nodeSize,
- // Replaces with content of first `column`.
- firstColumnBeforePos + 1,
- firstColumnBeforePos + firstColumn.nodeSize - 1,
- // Doesn't append anything.
- Slice.empty,
- 0,
- false,
- ),
- );
-
- return;
- }
-}
diff --git a/packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.test.ts b/packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.test.ts
index ab02a865f0..eb57e39c85 100644
--- a/packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.test.ts
+++ b/packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.test.ts
@@ -3,11 +3,12 @@ import { TextSelection } from "prosemirror-state";
import { describe, expect, it } from "vite-plus/test";
import {
- getBlockInfo,
+ getBlockInfoFromNode,
getBlockInfoFromSelection,
getNodeId,
} from "../../../getBlockInfoFromPos.js";
import { getNodeById } from "../../../nodeUtil.js";
+import { containerSchema } from "../../containers/containers.fixture.js";
import { setupTestEnv } from "../../setupTestEnv.js";
import { splitBlockCommand } from "./splitBlock.js";
@@ -33,15 +34,15 @@ function setSelectionWithOffset(
throw new Error(`Block with ID ${targetBlockId} not found`);
}
- const info = getBlockInfo(posInfo);
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
- if (!info.isBlockContainer) {
+ if (!info.hasContent) {
throw new Error("Target block is not a block container");
}
getEditor().transact((tr) =>
tr.setSelection(
- TextSelection.create(doc, info.blockContent.beforePos + offset + 1),
+ TextSelection.create(doc, info.content.beforePos + offset + 1),
),
);
}
@@ -139,7 +140,7 @@ describe("Test splitBlocks", () => {
splitBlock(getEditor().transact((tr) => tr.selection.anchor));
const blockId = getEditor().transact((tr) =>
- getNodeId(getBlockInfoFromSelection(tr).bnBlock.node, tr.doc),
+ getNodeId(getBlockInfoFromSelection(tr).block.node, tr.doc),
);
const anchorIsAtStartOfNewBlock =
@@ -149,3 +150,155 @@ describe("Test splitBlocks", () => {
expect(anchorIsAtStartOfNewBlock).toBeTruthy();
});
});
+
+// `splitBlockTr` splits two levels deep (`blockContent` and its
+// `blockContainer`), which assumes the block's parent is a children holder that
+// accepts another `blockContainer`. A container's children holder is a
+// different node type than `blockGroup`, so these pin that the split lands
+// inside the container rather than tearing it open.
+describe("Test splitBlocks inside containers", () => {
+ const getContainerEditor = setupTestEnv({
+ schema: containerSchema,
+ document: [
+ { id: "before", type: "paragraph", content: "Before" },
+ {
+ id: "callout-0",
+ type: "callout",
+ children: [
+ {
+ id: "callout-child-0",
+ type: "paragraph",
+ content: "Callout child",
+ },
+ {
+ id: "callout-child-1",
+ type: "heading",
+ content: "Callout heading",
+ children: [
+ {
+ id: "nested-child",
+ type: "paragraph",
+ content: "Nested child",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ id: "grid-0",
+ type: "grid",
+ children: [
+ {
+ id: "cell-0",
+ type: "gridCell",
+ children: [
+ { id: "cell-0-p", type: "paragraph", content: "Cell zero" },
+ ],
+ },
+ {
+ id: "cell-1",
+ type: "gridCell",
+ children: [
+ { id: "cell-1-p", type: "paragraph", content: "Cell one" },
+ ],
+ },
+ ],
+ },
+ ],
+ });
+
+ function splitContainerBlock(blockId: string, offset: number) {
+ const editor = getContainerEditor();
+
+ const posInBlock = editor.transact((tr) => {
+ const posInfo = getNodeById(blockId, tr.doc);
+ if (!posInfo) {
+ throw new Error(`Block with ID ${blockId} not found`);
+ }
+
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+
+ // A container has no content to offset into, so we aim at the node
+ // itself, which is where a `NodeSelection` on it would put the anchor.
+ return info.hasContent
+ ? info.content.beforePos + offset + 1
+ : info.block.beforePos;
+ });
+
+ return editor._tiptapEditor.commands.command(
+ splitBlockCommand(posInBlock, true),
+ );
+ }
+
+ function textOf(block: { content?: any }) {
+ return (block.content as { text: string }[]).map((c) => c.text).join("");
+ }
+
+ it("Splits a block inside a container in place", () => {
+ expect(splitContainerBlock("callout-child-0", 7)).toBe(true);
+
+ const document = getContainerEditor().document;
+
+ expect(document.map((block) => block.id)).toEqual([
+ "before",
+ "callout-0",
+ "grid-0",
+ ]);
+
+ const callout = document[1];
+ expect(callout.type).toBe("callout");
+ expect(callout.children.map(textOf)).toEqual([
+ "Callout",
+ " child",
+ "Callout heading",
+ ]);
+
+ expect(() =>
+ getContainerEditor().prosemirrorState.doc.check(),
+ ).not.toThrow();
+ });
+
+ it("Moves the block's children onto the second half of the split", () => {
+ expect(splitContainerBlock("callout-child-1", 7)).toBe(true);
+
+ const callout = getContainerEditor().document[1];
+
+ expect(callout.children.map(textOf)).toEqual([
+ "Callout child",
+ "Callout",
+ " heading",
+ ]);
+ // The children follow the trailing half, as they do at the top level.
+ expect(callout.children[1].children).toEqual([]);
+ expect(callout.children[2].children.map((child) => child.id)).toEqual([
+ "nested-child",
+ ]);
+
+ expect(() =>
+ getContainerEditor().prosemirrorState.doc.check(),
+ ).not.toThrow();
+ });
+
+ it("Splits a block inside a nested container", () => {
+ expect(splitContainerBlock("cell-0-p", 4)).toBe(true);
+
+ const grid = getContainerEditor().document[2];
+
+ expect(grid.type).toBe("grid");
+ expect(grid.children.map((cell) => cell.id)).toEqual(["cell-0", "cell-1"]);
+ expect(grid.children[0].children.map(textOf)).toEqual(["Cell", " zero"]);
+ expect(grid.children[1].children.map(textOf)).toEqual(["Cell one"]);
+
+ expect(() =>
+ getContainerEditor().prosemirrorState.doc.check(),
+ ).not.toThrow();
+ });
+
+ it("Does not split a container block itself", () => {
+ const before = getContainerEditor().document;
+
+ expect(splitContainerBlock("callout-0", 0)).toBe(false);
+
+ expect(getContainerEditor().document).toEqual(before);
+ });
+});
diff --git a/packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.ts b/packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.ts
index 1e73471d23..d5229da6bf 100644
--- a/packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.ts
+++ b/packages/core/src/api/blockManipulation/commands/splitBlock/splitBlock.ts
@@ -1,7 +1,7 @@
import { EditorState, Transaction } from "prosemirror-state";
import {
- getBlockInfo,
+ getBlockInfoFromNode,
getNearestBlockPos,
} from "../../../getBlockInfoFromPos.js";
import { getPmSchema } from "../../../pmUtil.js";
@@ -34,21 +34,24 @@ export const splitBlockTr = (
): boolean => {
const nearestBlockContainerPos = getNearestBlockPos(tr.doc, posInBlock);
- const info = getBlockInfo(nearestBlockContainerPos);
+ const info = getBlockInfoFromNode(
+ nearestBlockContainerPos.node,
+ nearestBlockContainerPos.posBeforeNode,
+ );
- if (!info.isBlockContainer) {
+ if (!info.hasContent) {
return false;
}
const schema = getPmSchema(tr);
const types = [
{
- type: info.bnBlock.node.type, // always keep blockcontainer type
- attrs: keepProps ? { ...info.bnBlock.node.attrs, id: undefined } : {},
+ type: info.block.node.type, // always keep blockcontainer type
+ attrs: keepProps ? { ...info.block.node.attrs, id: undefined } : {},
},
{
- type: keepType ? info.blockContent.node.type : schema.nodes["paragraph"],
- attrs: keepProps ? { ...info.blockContent.node.attrs } : {},
+ type: keepType ? info.content.node.type : schema.nodes["paragraph"],
+ attrs: keepProps ? { ...info.content.node.attrs } : {},
},
];
diff --git a/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.test.ts b/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.test.ts
index e44e4a6380..2d6dc782fa 100644
--- a/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.test.ts
+++ b/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.test.ts
@@ -1,8 +1,9 @@
import { describe, expect, it } from "vite-plus/test";
import type { PartialBlock } from "../../../../blocks/defaultBlocks.js";
-import { getBlockInfo } from "../../../getBlockInfoFromPos.js";
+import { getBlockInfoFromNode } from "../../../getBlockInfoFromPos.js";
import { getNodeById } from "../../../nodeUtil.js";
+import { containerSchema } from "../../containers/containers.fixture.js";
import { setupTestEnv } from "../../setupTestEnv.js";
import { updateBlock } from "./updateBlock.js";
@@ -177,11 +178,13 @@ describe("Test updateBlock", () => {
});
it("Update partial (offset start)", () => {
- const info = getBlockInfo(
- getNodeById("heading-with-everything", getEditor().prosemirrorState.doc)!,
- );
+ const posInfo = getNodeById(
+ "heading-with-everything",
+ getEditor().prosemirrorState.doc,
+ )!;
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
- if (!info.isBlockContainer) {
+ if (!info.hasContent) {
throw new Error("heading-with-everything is not a block container");
}
@@ -198,7 +201,7 @@ describe("Test updateBlock", () => {
},
],
},
- info.blockContent.beforePos + 9,
+ info.content.beforePos + 9,
),
);
@@ -206,11 +209,13 @@ describe("Test updateBlock", () => {
});
it("Update partial (offset start + end)", () => {
- const info = getBlockInfo(
- getNodeById("heading-with-everything", getEditor().prosemirrorState.doc)!,
- );
+ const posInfo = getNodeById(
+ "heading-with-everything",
+ getEditor().prosemirrorState.doc,
+ )!;
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
- if (!info.isBlockContainer) {
+ if (!info.hasContent) {
throw new Error("heading-with-everything is not a block container");
}
@@ -227,8 +232,8 @@ describe("Test updateBlock", () => {
},
],
},
- info.blockContent.beforePos + 9,
- info.blockContent.beforePos + 9,
+ info.content.beforePos + 9,
+ info.content.beforePos + 9,
),
);
@@ -236,11 +241,13 @@ describe("Test updateBlock", () => {
});
it("Update partial (props + offset end)", () => {
- const info = getBlockInfo(
- getNodeById("heading-with-everything", getEditor().prosemirrorState.doc)!,
- );
+ const posInfo = getNodeById(
+ "heading-with-everything",
+ getEditor().prosemirrorState.doc,
+ )!;
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
- if (!info.isBlockContainer) {
+ if (!info.hasContent) {
throw new Error("heading-with-everything is not a block container");
}
@@ -261,7 +268,7 @@ describe("Test updateBlock", () => {
],
},
undefined,
- info.blockContent.beforePos + 8,
+ info.content.beforePos + 8,
);
});
@@ -269,15 +276,14 @@ describe("Test updateBlock", () => {
});
it("Update partial (table cell)", () => {
- const info = getBlockInfo(
- getNodeById("table-0", getEditor().prosemirrorState.doc)!,
- );
+ const posInfo = getNodeById("table-0", getEditor().prosemirrorState.doc)!;
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
- if (!info.isBlockContainer) {
+ if (!info.hasContent) {
throw new Error("table-0 is not a block container");
}
- const cell = info.blockContent.node.resolve(2);
+ const cell = info.content.node.resolve(2);
getEditor().transact((tr) =>
updateBlock(
@@ -290,8 +296,8 @@ describe("Test updateBlock", () => {
rows: [{ cells: ["updated cell 1"] }],
},
},
- info.blockContent.beforePos + 2,
- info.blockContent.beforePos + 2 + cell.node().nodeSize,
+ info.content.beforePos + 2,
+ info.content.beforePos + 2 + cell.node().nodeSize,
),
);
@@ -299,15 +305,14 @@ describe("Test updateBlock", () => {
});
it("Update partial (table row)", () => {
- const info = getBlockInfo(
- getNodeById("table-0", getEditor().prosemirrorState.doc)!,
- );
+ const posInfo = getNodeById("table-0", getEditor().prosemirrorState.doc)!;
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
- if (!info.isBlockContainer) {
+ if (!info.hasContent) {
throw new Error("table-0 is not a block container");
}
- const cell = info.blockContent.node.resolve(1);
+ const cell = info.content.node.resolve(1);
getEditor().transact((tr) =>
updateBlock(
@@ -324,8 +329,8 @@ describe("Test updateBlock", () => {
],
},
},
- info.blockContent.beforePos + 1,
- info.blockContent.beforePos + 1 + cell.node().nodeSize,
+ info.content.beforePos + 1,
+ info.content.beforePos + 1 + cell.node().nodeSize,
),
);
@@ -934,13 +939,12 @@ describe("Test updateBlock minimal steps", () => {
it("Type change with offset content replace stays minimal and valid", () => {
const editor = getEditor();
- const info = getBlockInfo(
- getNodeById(
- "paragraph-with-styled-content",
- editor.prosemirrorState.doc,
- )!,
- );
- if (!info.isBlockContainer) {
+ const posInfo = getNodeById(
+ "paragraph-with-styled-content",
+ editor.prosemirrorState.doc,
+ )!;
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+ if (!info.hasContent) {
throw new Error("paragraph-with-styled-content is not a block container");
}
@@ -959,8 +963,8 @@ describe("Test updateBlock minimal steps", () => {
props: { level: 3 },
content: [{ type: "text", text: " with NEW ", styles: {} }],
},
- info.blockContent.beforePos + 1 + "Paragraph".length,
- info.blockContent.beforePos + 1 + "Paragraph with styled ".length,
+ info.content.beforePos + 1 + "Paragraph".length,
+ info.content.beforePos + 1 + "Paragraph with styled ".length,
);
steps = tr.steps.map((s) => s.toJSON());
});
@@ -976,3 +980,194 @@ describe("Test updateBlock minimal steps", () => {
expect(() => editor._tiptapEditor.state.doc.check()).not.toThrow();
});
});
+
+// Changing a block's type across the content/container divide can't happen in
+// place, so `updateBlock` rebuilds the node and has to decide what to do with
+// the content the old shape held and the new one can't. These tests pin that
+// decision. Assertions are explicit rather than snapshotted because the point
+// is *where* the carried content ends up.
+describe("Test updateBlock content carry-over", () => {
+ const getContainerEditor = setupTestEnv({
+ schema: containerSchema,
+ document: [
+ {
+ id: "paragraph-with-text",
+ type: "paragraph",
+ content: "Paragraph with text",
+ },
+ {
+ id: "empty-paragraph",
+ type: "paragraph",
+ },
+ {
+ id: "paragraph-with-text-and-children",
+ type: "paragraph",
+ content: "Parent text",
+ children: [
+ {
+ id: "existing-child",
+ type: "paragraph",
+ content: "Existing child",
+ },
+ ],
+ },
+ {
+ id: "table-0",
+ type: "table",
+ content: {
+ type: "tableContent",
+ rows: [{ cells: ["Cell 1", "Cell 2"] }],
+ },
+ },
+ {
+ id: "callout-0",
+ type: "callout",
+ children: [
+ {
+ id: "callout-child",
+ type: "paragraph",
+ content: "Callout child",
+ },
+ ],
+ },
+ ],
+ });
+
+ // A block that changes shape is rebuilt rather than updated in place, and the
+ // rebuilt node is minted a fresh ID. That is long-standing behaviour, not
+ // something the container work introduced, but converting a paragraph into a
+ // container is a far more ordinary action than the paragraph/column
+ // conversions that used to be the only way to reach this path. These tests
+ // therefore address blocks by position, and the first one pins the ID loss so
+ // that fixing it shows up as a deliberate change.
+ it("Moves inline content into a child paragraph when becoming a container", () => {
+ const editor = getContainerEditor();
+ editor.transact((tr) =>
+ updateBlock(tr, "paragraph-with-text", { type: "callout" }),
+ );
+
+ const block = editor.document[0] as any;
+ expect(block.type).toBe("callout");
+ expect(block.id).not.toBe("paragraph-with-text");
+ expect(block.children).toHaveLength(1);
+ expect(block.children[0].type).toBe("paragraph");
+ expect(block.children[0].content).toEqual([
+ { type: "text", text: "Paragraph with text", styles: {} },
+ ]);
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+ });
+
+ it("Seeds a container's default children when there is no content to carry", () => {
+ const editor = getContainerEditor();
+ editor.transact((tr) =>
+ updateBlock(tr, "empty-paragraph", { type: "seededPair" }),
+ );
+
+ // An empty paragraph carries nothing, so the rebuilt node must be passed no
+ // `children` at all: `blockToNode` seeds from the spec's `default` only
+ // when `children` is absent, and pads with empty blocks when it is an
+ // empty array. `seededPair` is used here rather than `callout` because its
+ // `default` and its padding differ — for `callout` both are one empty
+ // paragraph, so the distinction is invisible.
+ const block = editor.document[1] as any;
+ expect(block.type).toBe("seededPair");
+ expect(block.children.map((child: any) => child.content[0]?.text)).toEqual([
+ "Seed A",
+ "Seed B",
+ ]);
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+ });
+
+ it("Puts carried content before existing children", () => {
+ const editor = getContainerEditor();
+ editor.transact((tr) =>
+ updateBlock(tr, "paragraph-with-text-and-children", { type: "callout" }),
+ );
+
+ // The paragraph holding the carried text takes the place the text used to
+ // occupy, i.e. above the children that were already nested under it.
+ const block = editor.document[2] as any;
+ expect(block.type).toBe("callout");
+ expect(block.children.map((child: any) => child.content[0].text)).toEqual([
+ "Parent text",
+ "Existing child",
+ ]);
+ expect(block.children[1].id).toBe("existing-child");
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+ });
+
+ it("Drops table content when becoming a container", () => {
+ const editor = getContainerEditor();
+ // Table content isn't an inline array, so there is no sensible paragraph to
+ // wrap it in. It's dropped, and the container seeds as if the block had
+ // been empty.
+ expect(() =>
+ editor.transact((tr) => updateBlock(tr, "table-0", { type: "callout" })),
+ ).not.toThrow();
+
+ const block = editor.document[3] as any;
+ expect(block.type).toBe("callout");
+ expect(block.content).toBeUndefined();
+ expect(block.children).toHaveLength(1);
+ expect(block.children[0].type).toBe("paragraph");
+ expect(block.children[0].content).toEqual([]);
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+ });
+
+ it("Drops carried content for a container that holds only containers", () => {
+ const editor = getContainerEditor();
+ // `grid` holds `gridCell`s, so there is no slot for the paragraph the
+ // content would be carried over in. Handing it one used to build a node
+ // that failed `check()`, aborting the conversion; instead the content is
+ // dropped and the grid seeds as if the block had been empty. Same shape
+ // as a column list, down to `whenEmptied: "unwrap"` and `min: 2`.
+ expect(() =>
+ editor.transact((tr) =>
+ updateBlock(tr, "paragraph-with-text", { type: "grid" }),
+ ),
+ ).not.toThrow();
+
+ const block = editor.document[0] as any;
+ expect(block.type).toBe("grid");
+ expect(block.content).toBeUndefined();
+ expect(block.children.map((child: any) => child.type)).toEqual([
+ "gridCell",
+ "gridCell",
+ ]);
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+ });
+
+ it("Keeps existing children when a container-only container drops the content", () => {
+ const editor = getContainerEditor();
+ // The carried content has nowhere to go, but the block's own children are
+ // regular blocks the grid's cells can still hold.
+ expect(() =>
+ editor.transact((tr) =>
+ updateBlock(tr, "paragraph-with-text-and-children", {
+ type: "sealedGrid",
+ }),
+ ),
+ ).not.toThrow();
+
+ const block = editor.document[2] as any;
+ expect(block.type).toBe("sealedGrid");
+ expect(block.children.map((child: any) => child.type)).toEqual([
+ "sealedBox",
+ ]);
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+ });
+
+ it("Keeps a container's children and invents no content when becoming a block", () => {
+ const editor = getContainerEditor();
+ editor.transact((tr) =>
+ updateBlock(tr, "callout-0", { type: "paragraph" }),
+ );
+
+ const block = editor.document[4] as any;
+ expect(block.type).toBe("paragraph");
+ expect(block.content).toEqual([]);
+ expect(block.children).toHaveLength(1);
+ expect(block.children[0].id).toBe("callout-child");
+ expect(() => editor.prosemirrorState.doc.check()).not.toThrow();
+ });
+});
diff --git a/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts b/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts
index 6edfc434d5..f73b804f9e 100644
--- a/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts
+++ b/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts
@@ -2,6 +2,7 @@ import {
Fragment,
type NodeType,
type Node as PMNode,
+ type Schema,
Slice,
} from "prosemirror-model";
import { TextSelection, Transaction } from "prosemirror-state";
@@ -18,16 +19,20 @@ import type { StyleSchema } from "../../../../schema/styles/types.js";
import { UnreachableCaseError } from "../../../../util/typescript.js";
import {
type BlockInfo,
- getBlockInfoFromResolvedPos,
+ getBlockInfoAt,
} from "../../../getBlockInfoFromPos.js";
+import { blockToNode } from "../../../nodeConversions/blockToNode.js";
import {
- blockToNode,
inlineContentToNodes,
tableContentToNodes,
} from "../../../nodeConversions/blockToNode.js";
import { nodeToBlock } from "../../../nodeConversions/nodeToBlock.js";
import { getNodeById } from "../../../nodeUtil.js";
-import { getPmSchema } from "../../../pmUtil.js";
+import { getBlockSchema, getPmSchema } from "../../../pmUtil.js";
+import {
+ createBlockGroup,
+ isContainerNode,
+} from "../../../../schema/blocks/children.js";
// for compatibility with tiptap. TODO: remove as we want to remove dependency on tiptap command interface
export const updateBlockCommand = <
@@ -63,7 +68,7 @@ export function updateBlockTr<
replaceFromPos?: number,
replaceToPos?: number,
) {
- const blockInfo = getBlockInfoFromResolvedPos(tr.doc.resolve(posBeforeBlock));
+ const blockInfo = getBlockInfoAt(tr.doc, posBeforeBlock);
let cellAnchor: CellAnchor | null = null;
if (blockInfo.blockNoteType === "table") {
@@ -82,44 +87,33 @@ export function updateBlockTr<
// Adds blockGroup node with child blocks if necessary.
- const oldNodeType = pmSchema.nodes[blockInfo.blockNoteType];
- const newNodeType = pmSchema.nodes[block.type || blockInfo.blockNoteType];
+ const newBlockType = block.type || blockInfo.blockNoteType;
+ const newNodeType = pmSchema.nodes[newBlockType];
const newBnBlockNodeType = newNodeType.isInGroup("bnBlock")
? newNodeType
: pmSchema.nodes["blockContainer"];
- if (blockInfo.isBlockContainer && newNodeType.isInGroup("blockContent")) {
- const replaceFromOffset =
- replaceFromPos !== undefined &&
- replaceFromPos > blockInfo.blockContent.beforePos &&
- replaceFromPos < blockInfo.blockContent.afterPos
- ? replaceFromPos - blockInfo.blockContent.beforePos - 1
- : undefined;
-
- const replaceToOffset =
- replaceToPos !== undefined &&
- replaceToPos > blockInfo.blockContent.beforePos &&
- replaceToPos < blockInfo.blockContent.afterPos
- ? replaceToPos - blockInfo.blockContent.beforePos - 1
- : undefined;
-
- updateChildren(block, tr, blockInfo);
- // The code below determines the new content of the block.
- // or "keep" to keep as-is
- updateBlockContentNode(
- block,
- tr,
- oldNodeType,
- newNodeType,
- blockInfo,
- replaceFromOffset,
- replaceToOffset,
- );
- } else if (!blockInfo.isBlockContainer && newNodeType.isInGroup("bnBlock")) {
- updateChildren(block, tr, blockInfo);
- // old node was a bnBlock type (like column or columnList) and new block as well
- // No op, we just update the bnBlock below (at end of function) and have already updated the children
- } else {
+ const replaceFromOffset =
+ blockInfo.hasContent &&
+ replaceFromPos !== undefined &&
+ replaceFromPos >= blockInfo.contentStart &&
+ replaceFromPos <= blockInfo.contentEnd
+ ? replaceFromPos - blockInfo.contentStart
+ : undefined;
+
+ const replaceToOffset =
+ blockInfo.hasContent &&
+ replaceToPos !== undefined &&
+ replaceToPos >= blockInfo.contentStart &&
+ replaceToPos <= blockInfo.contentEnd
+ ? replaceToPos - blockInfo.contentStart
+ : undefined;
+
+ // `hasContent` is exactly `blockContainer`-ness, and a block type resolves
+ // to either a `blockContent` node (a regular block) or a `bnBlock` one (a
+ // container), so the two together say whether the update keeps the block's
+ // shape. Only a same-shape update can happen in place.
+ if (blockInfo.hasContent !== newNodeType.isInGroup("blockContent")) {
// switching from blockContainer to non-blockContainer or v.v.
// currently breaking for column slash menu items converting empty block
// to column.
@@ -127,29 +121,61 @@ export function updateBlockTr<
// currently, we calculate the new node and replace the entire node with the desired new node.
// for this, we do a nodeToBlock on the existing block to get the children.
// it would be cleaner to use a ReplaceAroundStep, but this is a bit simpler and it's quite an edge case
- const existingBlock = nodeToBlock(blockInfo.bnBlock.node, tr.doc);
+ const existingBlock = nodeToBlock(blockInfo.block.node, tr.doc);
+ const carried = carryOverContent(
+ existingBlock.content,
+ newBlockType,
+ pmSchema,
+ );
+ // If no children are passed in, use the existing block's, but only when
+ // there actually are some. `nodeToBlock` always emits an array, and an
+ // empty one would read as "explicitly childless", suppressing the seeding
+ // a container needs when converting from a childless block.
+ const children = acceptedChildren(
+ [...carried.children, ...existingBlock.children],
+ newNodeType,
+ pmSchema,
+ );
+
const replacementNode = blockToNode(
{
- children: existingBlock.children, // if no children are passed in, use existing children
+ ...(carried.content ? { content: carried.content } : {}),
+ ...(children.length > 0 ? { children } : {}),
...block,
},
pmSchema,
);
replacementNode.check(); // `blockToNode` is lenient; validate before mutating the doc
tr.replaceWith(
- blockInfo.bnBlock.beforePos,
- blockInfo.bnBlock.afterPos,
+ blockInfo.block.beforePos,
+ blockInfo.block.afterPos,
replacementNode,
);
return;
}
+ updateChildren(block, tr, blockInfo);
+
+ if (blockInfo.hasContent) {
+ // The code below determines the new content of the block.
+ // or "keep" to keep as-is
+ updateBlockContentNode(
+ block,
+ tr,
+ pmSchema.nodes[blockInfo.blockNoteType],
+ newNodeType,
+ blockInfo,
+ replaceFromOffset,
+ replaceToOffset,
+ );
+ }
+
// Adds all provided props as attributes to the parent blockContainer node too, and also preserves existing
// attributes. Uses minimal steps so that an unchanged container (e.g. when
// only children or content changed) doesn't emit a step at all.
- setNodeMarkupMinimal(tr, blockInfo.bnBlock.beforePos, newBnBlockNodeType, {
+ setNodeMarkupMinimal(tr, blockInfo.block.beforePos, newBnBlockNodeType, {
...block.props,
});
@@ -158,6 +184,75 @@ export function updateBlockTr<
}
}
+function carryOverContent(
+ existingContent: Block["content"],
+ newBlockType: string,
+ pmSchema: Schema,
+): {
+ content?: PartialBlock["content"];
+ children: PartialBlock[];
+} {
+ const nothing = { children: [] };
+
+ if (!existingContent || !Array.isArray(existingContent)) {
+ return nothing;
+ }
+ if (existingContent.length === 0) {
+ return nothing;
+ }
+
+ const targetConfig = getBlockSchema(pmSchema)[newBlockType];
+ if (!targetConfig) {
+ return nothing;
+ }
+
+ if (targetConfig.content === "inline" || targetConfig.content === "plain") {
+ return { content: existingContent, children: [] };
+ }
+
+ if (targetConfig.children !== undefined) {
+ // Offered as a child rather than as content; whether the container can
+ // actually hold it is decided by `acceptedChildren` in the caller, which
+ // asks the same of the block's pre-existing children.
+ return {
+ children: [{ type: "paragraph", content: existingContent } as any],
+ };
+ }
+
+ return nothing;
+}
+
+/**
+ * The subset of `children` a block of `newNodeType` can hold.
+ *
+ * A container that takes only other containers (a column list takes columns)
+ * has no slot for a paragraph, so a conversion into one has to drop the
+ * children that don't fit rather than build a node that fails `check()` and
+ * aborts the whole update. Regular blocks nest in a `blockGroup`, which takes
+ * anything, so only containers filter.
+ */
+function acceptedChildren(
+ children: PartialBlock[],
+ newNodeType: NodeType,
+ pmSchema: Schema,
+): PartialBlock[] {
+ if (!isContainerNode(newNodeType)) {
+ return children;
+ }
+
+ return children.filter((child) => {
+ // Every regular block is the same ProseMirror node, so a child that isn't
+ // a container type is a `blockContainer`.
+ const childType = child.type ? pmSchema.nodes[child.type] : undefined;
+ const asNodeType =
+ childType && isContainerNode(childType)
+ ? childType
+ : pmSchema.nodes["blockContainer"];
+
+ return !!newNodeType.contentMatch.matchType(asNodeType);
+ });
+}
+
function updateBlockContentNode<
BSchema extends BlockSchema,
I extends InlineContentSchema,
@@ -168,10 +263,10 @@ function updateBlockContentNode<
oldNodeType: NodeType,
newNodeType: NodeType,
blockInfo: {
- childContainer?:
+ children?:
| { node: PMNode; beforePos: number; afterPos: number }
| undefined;
- blockContent: { node: PMNode; beforePos: number; afterPos: number };
+ content: { node: PMNode; beforePos: number; afterPos: number };
},
replaceFromOffset?: number,
replaceToOffset?: number,
@@ -201,8 +296,8 @@ function updateBlockContentNode<
// no custom content has been provided, use existing content IF possible
// Since some block types contain inline content and others don't,
// we either need to call setNodeMarkup to just update type &
- // attributes, or replaceWith to replace the whole blockContent.
- const oldContent = blockInfo.blockContent.node.content;
+ // attributes, or replaceWith to replace the whole content.
+ const oldContent = blockInfo.content.node.content;
if (oldNodeType.spec.content === "") {
// keep old content, because it's empty anyway and should be compatible with
// any newContentType
@@ -217,7 +312,7 @@ function updateBlockContentNode<
// for the new type (e.g. converting styled/complex inline content into a
// plain block that disallows formatting marks and inline nodes). Preserve
// the text, dropping the styling the new type can't represent.
- const text = blockInfo.blockContent.node.textContent;
+ const text = blockInfo.content.node.textContent;
content = text.length > 0 ? [pmSchema.text(text)] : [];
} else {
// the content type changed and is incompatible, replace the previous content
@@ -225,7 +320,7 @@ function updateBlockContentNode<
}
}
- // Now, changes the blockContent node type and adds the provided props
+ // Now, changes the content node type and adds the provided props
// as attributes. Also preserves all existing attributes that are
// compatible with the new type.
//
@@ -233,7 +328,7 @@ function updateBlockContentNode<
// content is being replaced or not.
if (content === "keep") {
// only update the type and attributes, keeping the content as-is
- setNodeMarkupMinimal(tr, blockInfo.blockContent.beforePos, newNodeType, {
+ setNodeMarkupMinimal(tr, blockInfo.content.beforePos, newNodeType, {
...block.props,
});
} else if (replaceFromOffset !== undefined || replaceToOffset !== undefined) {
@@ -241,7 +336,7 @@ function updateBlockContentNode<
// position back.
const contentBeforePos = setNodeMarkupMinimalAndRemap(
tr,
- blockInfo.blockContent.beforePos,
+ blockInfo.content.beforePos,
newNodeType,
{ ...block.props },
);
@@ -250,7 +345,7 @@ function updateBlockContentNode<
const end =
contentBeforePos +
1 +
- (replaceToOffset ?? blockInfo.blockContent.node.content.size);
+ (replaceToOffset ?? blockInfo.content.node.content.size);
// for content like table cells (where the blockcontent has nested PM nodes),
// we need to figure out the correct openStart and openEnd for the slice when replacing
@@ -270,7 +365,7 @@ function updateBlockContentNode<
);
} else if (
newNodeType === oldNodeType ||
- newNodeType.validContent(blockInfo.blockContent.node.content)
+ newNodeType.validContent(blockInfo.content.node.content)
) {
// The new type can hold the existing content, so we can update the markup
// first and then diff the content. This keeps both steps minimal.
@@ -280,7 +375,7 @@ function updateBlockContentNode<
// get its (possibly shifted) position back.
const contentBeforePos = setNodeMarkupMinimalAndRemap(
tr,
- blockInfo.blockContent.beforePos,
+ blockInfo.content.beforePos,
newNodeType,
{ ...block.props },
);
@@ -293,11 +388,11 @@ function updateBlockContentNode<
// between inline content, table content, and no content). We can't update
// the markup in-place, so replace the whole content node atomically.
tr.replaceWith(
- blockInfo.blockContent.beforePos,
- blockInfo.blockContent.afterPos,
+ blockInfo.content.beforePos,
+ blockInfo.content.afterPos,
newNodeType.createChecked(
{
- ...blockInfo.blockContent.node.attrs,
+ ...blockInfo.content.node.attrs,
...block.props,
},
content,
@@ -510,24 +605,23 @@ function updateChildren<
return node;
});
- // Checks if a blockGroup node already exists.
- if (blockInfo.childContainer) {
- // Replaces the child nodes in the existing blockGroup, only touching the
- // range that actually changed (keeping unchanged leading/trailing
- // children untouched).
+ if (blockInfo.children) {
+ // Replaces the child nodes in the existing children holder, only
+ // touching the range that actually changed (keeping unchanged
+ // leading/trailing children untouched).
replaceContentMinimal(
tr,
- blockInfo.childContainer.beforePos,
+ blockInfo.children.beforePos,
Fragment.from(childNodes),
);
- } else {
- if (!blockInfo.isBlockContainer) {
- throw new Error("impossible");
- }
- // Inserts a new blockGroup containing the child nodes created earlier.
+ } else if (blockInfo.hasContent) {
+ // A `blockContainer` with no children yet: its `blockGroup` is lazy
+ // (`blockContent blockGroup?`), so create it around the child nodes and
+ // insert it after the content node. (Containers always have a children
+ // holder, so no holder implies a `blockContainer`.)
tr.insert(
- blockInfo.blockContent.afterPos,
- pmSchema.nodes["blockGroup"].createChecked({}, childNodes),
+ blockInfo.content.afterPos,
+ createBlockGroup(pmSchema, childNodes),
);
}
}
@@ -559,11 +653,14 @@ export function updateBlock<
replaceToPos,
);
- const blockContainerNode = tr.doc
- .resolve(posInfo.posBeforeNode + 1) // TODO: clean?
- .node();
+ // `updateBlockTr` may have replaced the node, so re-resolve it at the same
+ // position (an update never moves the block).
+ const updatedNode = tr.doc.resolve(posInfo.posBeforeNode).nodeAfter;
+ if (!updatedNode) {
+ throw new Error(`Block with ID ${id} not found after update`);
+ }
- return nodeToBlock(blockContainerNode, tr.doc);
+ return nodeToBlock(updatedNode, tr.doc);
}
type CellAnchor = { row: number; col: number; offset: number };
@@ -637,12 +734,12 @@ function restoreCellAnchor(
// 1) Resolve the table node in the current document
let tablePos = -1;
- if (blockInfo.isBlockContainer) {
- // Prefer the blockContent position when available (points directly at the PM table node)
- tablePos = tr.mapping.map(blockInfo.blockContent.beforePos);
+ if (blockInfo.hasContent) {
+ // Prefer the content position when available (points directly at the PM table node)
+ tablePos = tr.mapping.map(blockInfo.content.beforePos);
} else {
- // Fallback: scan within the mapped bnBlock range to find the inner table node
- const start = tr.mapping.map(blockInfo.bnBlock.beforePos);
+ // Fallback: scan within the mapped block range to find the inner table node
+ const start = tr.mapping.map(blockInfo.block.beforePos);
const end = start + (tr.doc.nodeAt(start)?.nodeSize || 0);
tr.doc.nodesBetween(start, end, (node, pos) => {
if (node.type.name === "table") {
diff --git a/packages/core/src/api/blockManipulation/containers/containerNav.ts b/packages/core/src/api/blockManipulation/containers/containerNav.ts
new file mode 100644
index 0000000000..6e5cb87e27
--- /dev/null
+++ b/packages/core/src/api/blockManipulation/containers/containerNav.ts
@@ -0,0 +1,149 @@
+import type { Node, NodeType } from "prosemirror-model";
+
+import { isContainerNode, isSealed } from "../../../schema/blocks/children.js";
+import {
+ type BlockInfo,
+ getBlockInfoFromNode,
+} from "../../getBlockInfoFromPos.js";
+
+/**
+ * The outcome of a descent. `blockedBy` says why no position was found: a
+ * sealed container on the path ("seal"), or nothing on that edge accepting
+ * the type ("schema"). Gesture code tells the two apart to select a sealed
+ * container rather than move content into it.
+ */
+export type InsertionPos =
+ | { pos: number; blockedBy?: undefined }
+ | { pos?: undefined; blockedBy: "seal" | "schema" };
+
+/**
+ * Seal handling for the navigation helpers below. They respect seals, so
+ * content never implicitly crosses a sealed boundary. The block manipulation
+ * API opts out with `allowCrossingSeals`, since an explicit placement is an
+ * intentional crossing.
+ */
+type SealOpts = { allowCrossingSeals?: boolean };
+
+/**
+ * Walks one edge of a block's children, descending through nested containers,
+ * to the deepest position where `nodeType` fits. `edge` picks the trailing
+ * edge (where a new last child goes) or the leading edge.
+ */
+export function descendToInsertionPos(
+ info: BlockInfo,
+ nodeType: NodeType,
+ edge: "first" | "last",
+ opts?: SealOpts,
+): InsertionPos {
+ const children = info.children;
+ if (!children) {
+ return { blockedBy: "schema" };
+ }
+ if (!opts?.allowCrossingSeals && isSealed(children.node)) {
+ return { blockedBy: "seal" };
+ }
+
+ const last = edge === "last";
+ const index = last ? children.node.childCount : 0;
+ // `canReplaceWith` rather than a bare content match: the children already
+ // after the position have to still fit once the new node is spliced in.
+ if (children.node.canReplaceWith(index, index, nodeType)) {
+ return { pos: last ? children.childrenEnd : children.childrenStart };
+ }
+
+ const child = last ? children.node.lastChild : children.node.firstChild;
+ if (!child || !isContainerNode(child.type)) {
+ return { blockedBy: "schema" };
+ }
+ return descendToInsertionPos(
+ getBlockInfoFromNode(
+ child,
+ last ? children.childrenEnd - child.nodeSize : children.childrenStart,
+ ),
+ nodeType,
+ edge,
+ opts,
+ );
+}
+
+/**
+ * Resolves a block to its first leaf block: the block itself when it is not a
+ * container, otherwise the first leaf of its first child. Returns `null` for
+ * an empty container, or when reaching the leaf would cross a sealed
+ * container's boundary.
+ */
+export function getFirstLeafBlock(info: BlockInfo): BlockInfo | null {
+ const children = info.children;
+ if (!children || !isContainerNode(info.block.node.type)) {
+ // Not a container: the block is its own first leaf.
+ return info;
+ }
+ // A sealed container's leaf blocks are not reachable from outside.
+ if (isSealed(info.block.node)) {
+ return null;
+ }
+ const firstChild = children.node.firstChild;
+ if (!firstChild) {
+ return null;
+ }
+ return getFirstLeafBlock(
+ getBlockInfoFromNode(firstChild, children.childrenStart),
+ );
+}
+
+/**
+ * Climbs out of containers until it reaches a position where `nodeType` fits.
+ * `side` picks which edge of each climbed container to land on: `"before"` for
+ * moves that put a block above the containers it leaves (Backspace move-out),
+ * `"after"` for moves that put it below them (Enter-exit).
+ *
+ * Position-based rather than `BlockInfo`-based (unlike the descend/leaf
+ * helpers above) because its input is an arbitrary gap position — a point
+ * between blocks, not a block.
+ */
+export function ascendToInsertablePos(
+ doc: Node,
+ pos: number,
+ nodeType: NodeType,
+ side: "before" | "after" = "before",
+): number | undefined {
+ for (;;) {
+ const $pos = doc.resolve(pos);
+ const parent = $pos.node();
+ if (parent.canReplaceWith($pos.index(), $pos.index(), nodeType)) {
+ return pos;
+ }
+ if ($pos.depth > 0 && isContainerNode(parent.type)) {
+ // Climbing out of a sealed container would move content across its
+ // boundary.
+ if (isSealed(parent)) {
+ return undefined;
+ }
+ pos = side === "before" ? $pos.before() : $pos.after();
+ continue;
+ }
+ return undefined;
+ }
+}
+
+/**
+ * The container ancestors of a position, outermost last, each with its block
+ * id and resolution depth. Used to re-run container repair (`fixContainersById`)
+ * on every container a mutation may have emptied. Position-based for the same
+ * reason as `ascendToInsertablePos`: selections and mapped positions are the
+ * natural inputs.
+ */
+export function getAncestorContainers(
+ doc: Node,
+ pos: number,
+): { id: string; depth: number }[] {
+ const $pos = doc.resolve(pos);
+ const containers: { id: string; depth: number }[] = [];
+ for (let depth = $pos.depth; depth > 0; depth--) {
+ const ancestor = $pos.node(depth);
+ if (isContainerNode(ancestor.type) && ancestor.attrs.id) {
+ containers.push({ id: ancestor.attrs.id, depth });
+ }
+ }
+ return containers;
+}
diff --git a/packages/core/src/api/blockManipulation/containers/containerUI.ts b/packages/core/src/api/blockManipulation/containers/containerUI.ts
new file mode 100644
index 0000000000..ad17e8381f
--- /dev/null
+++ b/packages/core/src/api/blockManipulation/containers/containerUI.ts
@@ -0,0 +1,72 @@
+import type { BlockNoteEditor } from "../../../editor/BlockNoteEditor.js";
+
+export type ContainerUIInfo = {
+ containerTypes: ReadonlySet;
+ draggableContainerTypes: ReadonlySet;
+ /**
+ * Regular (non-container) block types whose spec sets `meta.draggable:
+ * false`. Container types are tracked separately in
+ * `draggableContainerTypes`, because they're identified in the DOM by
+ * `data-node-type` while regular blocks all share the `blockContainer` node
+ * and are identified by their content's `data-content-type`.
+ */
+ nonDraggableBlockTypes: ReadonlySet;
+ containerSelector: string | null;
+};
+
+function buildSelector(types: ReadonlySet): string | null {
+ if (types.size === 0) {
+ return null;
+ }
+ return [...types].map((type) => `[data-node-type="${type}"]`).join(",");
+}
+
+// The schema never changes over an editor's lifetime, so the info is derived
+// once. It's read on every mousemove, which would otherwise walk every block
+// spec each time.
+const cache = new WeakMap();
+
+export function getContainerUIInfo(
+ editor: Pick, "schema">,
+): ContainerUIInfo {
+ const cached = cache.get(editor.schema);
+ if (cached) {
+ return cached;
+ }
+
+ const containerTypes = new Set();
+ const draggableContainerTypes = new Set();
+ const nonDraggableBlockTypes = new Set();
+
+ for (const [type, spec] of Object.entries(
+ editor.schema.blockSpecs as Record<
+ string,
+ {
+ config: any;
+ implementation?: { meta?: { draggable?: boolean } };
+ }
+ >,
+ )) {
+ const draggable = spec.implementation?.meta?.draggable !== false;
+
+ if (spec.config.children === undefined) {
+ if (!draggable) {
+ nonDraggableBlockTypes.add(type);
+ }
+ continue;
+ }
+ containerTypes.add(type);
+ if (draggable) {
+ draggableContainerTypes.add(type);
+ }
+ }
+
+ const info: ContainerUIInfo = {
+ containerTypes,
+ draggableContainerTypes,
+ nonDraggableBlockTypes,
+ containerSelector: buildSelector(containerTypes),
+ };
+ cache.set(editor.schema, info);
+ return info;
+}
diff --git a/packages/core/src/api/blockManipulation/containers/containers.browser.test.ts b/packages/core/src/api/blockManipulation/containers/containers.browser.test.ts
new file mode 100644
index 0000000000..a313b69901
--- /dev/null
+++ b/packages/core/src/api/blockManipulation/containers/containers.browser.test.ts
@@ -0,0 +1,480 @@
+import {
+ afterAll,
+ beforeAll,
+ beforeEach,
+ describe,
+ expect,
+ it,
+} from "vite-plus/test";
+import { userEvent } from "vite-plus/test/browser";
+
+import { BlockNoteEditor } from "../../../editor/BlockNoteEditor.js";
+import { containerSchema } from "./containers.fixture.js";
+
+// Keymap tests for container blocks, split off from the node-environment
+// `containers.test.ts`. tiptap can only reach `handleKeyDown` through a
+// mounted view, so the editor is mounted and focused here and the keys are
+// pressed for real.
+
+const schema = containerSchema;
+
+let editor: BlockNoteEditor<
+ typeof schema.blockSchema,
+ typeof schema.inlineContentSchema,
+ typeof schema.styleSchema
+>;
+let div: HTMLElement;
+
+beforeAll(() => {
+ div = document.createElement("div");
+ document.body.appendChild(div);
+ editor = BlockNoteEditor.create({ schema });
+ editor.mount(div);
+});
+
+afterAll(() => {
+ editor._tiptapEditor.destroy();
+ div.remove();
+ editor = undefined as any;
+});
+
+beforeEach(() => {
+ editor.replaceBlocks(editor.document, [
+ { id: "p-0", type: "paragraph", content: "Paragraph 0" },
+ { id: "p-1", type: "paragraph", content: "Paragraph 1" },
+ ]);
+});
+
+/** Puts the caret at the given position and presses the key. */
+async function pressKey(
+ key: string,
+ at: { block: string; placement: "start" | "end" },
+) {
+ editor.setTextCursorPosition(at.block, at.placement);
+ editor.focus();
+ await userEvent.keyboard(`{${key}}`);
+}
+
+describe("children keyboard handling", () => {
+ it("Enter on an empty last child escapes the container", async () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "callout",
+ id: "c-0",
+ children: [
+ { id: "c-p-0", type: "paragraph", content: "Hello" },
+ { id: "c-p-1", type: "paragraph", content: "" },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ await pressKey("Enter", { block: "c-p-1", placement: "end" });
+
+ const callout = editor.getBlock("c-0")!;
+ expect(callout.children.map((child) => child.id)).toEqual(["c-p-0"]);
+ expect(editor.document.map((block) => block.type)).toEqual([
+ "callout",
+ "paragraph",
+ "paragraph",
+ ]);
+ expect(editor.document.map((block) => block.id)).toEqual([
+ "c-0",
+ "c-p-1",
+ "trailing",
+ ]);
+ // The caret moves out with the block.
+ expect(editor.getTextCursorPosition().block.id).toBe("c-p-1");
+ });
+
+ it("Enter escape ascends past levels that can't hold the block", async () => {
+ // A grid holds only cells, so a block escaping the last cell can't stop
+ // at the grid level. It lands below the grid itself.
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "grid",
+ id: "g-0",
+ children: [
+ {
+ type: "gridCell",
+ id: "g-c-0",
+ children: [{ id: "g-p-0", type: "paragraph", content: "A" }],
+ },
+ {
+ type: "gridCell",
+ id: "g-c-1",
+ children: [
+ { id: "g-p-1", type: "paragraph", content: "B" },
+ { id: "g-p-2", type: "paragraph", content: "" },
+ ],
+ },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ await pressKey("Enter", { block: "g-p-2", placement: "end" });
+
+ expect(editor.getBlock("g-c-1")!.children.map((child) => child.id)).toEqual(
+ ["g-p-1"],
+ );
+ expect(editor.document.map((block) => block.id)).toEqual([
+ "g-0",
+ "g-p-2",
+ "trailing",
+ ]);
+ expect(editor.getTextCursorPosition().block.id).toBe("g-p-2");
+ });
+
+ it("Enter on an empty block mid-container stays inside", async () => {
+ // The escape only fires at the end of the container. An empty block with
+ // siblings after it never ejects.
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "callout",
+ id: "c-0",
+ children: [
+ { id: "c-p-0", type: "paragraph", content: "Hello" },
+ { id: "c-p-1", type: "paragraph", content: "" },
+ { id: "c-p-2", type: "paragraph", content: "World" },
+ ],
+ },
+ ]);
+
+ await pressKey("Enter", { block: "c-p-1", placement: "end" });
+
+ expect(editor.document.map((block) => block.id)).toEqual(["c-0"]);
+ expect(editor.getBlock("c-0")!.children).toHaveLength(4);
+ });
+
+ it("Backspace at the start of a container's first child moves it out", async () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "before", type: "paragraph", content: "Before" },
+ {
+ type: "callout",
+ id: "c-0",
+ children: [
+ { id: "c-p-0", type: "paragraph", content: "First" },
+ { id: "c-p-1", type: "paragraph", content: "Second" },
+ ],
+ },
+ ]);
+
+ await pressKey("Backspace", { block: "c-p-0", placement: "start" });
+
+ expect(editor.getBlock("c-0")!.children.map((child) => child.id)).toEqual([
+ "c-p-1",
+ ]);
+ expect(editor.document.map((block) => block.id)).toEqual([
+ "before",
+ "c-p-0",
+ "c-0",
+ ]);
+ expect(editor.getBlock("c-p-0")!.content).toEqual([
+ { type: "text", text: "First", styles: {} },
+ ]);
+ });
+
+ it("Backspace at the start of a block after a container moves it inside", async () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "callout",
+ id: "c-0",
+ children: [{ id: "c-p-0", type: "paragraph", content: "In callout" }],
+ },
+ { id: "after", type: "paragraph", content: "After" },
+ ]);
+
+ await pressKey("Backspace", { block: "after", placement: "start" });
+
+ expect(editor.getBlock("c-0")!.children.map((child) => child.id)).toEqual([
+ "c-p-0",
+ "after",
+ ]);
+ expect(editor.document.map((block) => block.id)).toEqual(["c-0"]);
+ expect(editor.getBlock("after")!.content).toEqual([
+ { type: "text", text: "After", styles: {} },
+ ]);
+ });
+
+ it("Delete at the end of a block before a container pulls its first child out", async () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "before", type: "paragraph", content: "Before" },
+ {
+ type: "callout",
+ id: "c-0",
+ children: [
+ { id: "c-p-0", type: "paragraph", content: "First" },
+ { id: "c-p-1", type: "paragraph", content: "Second" },
+ ],
+ },
+ ]);
+
+ await pressKey("Delete", { block: "before", placement: "end" });
+
+ expect(editor.document.map((block) => block.id)).toEqual([
+ "before",
+ "c-p-0",
+ "c-0",
+ ]);
+ expect(editor.getBlock("c-0")!.children.map((child) => child.id)).toEqual([
+ "c-p-1",
+ ]);
+ });
+
+ it("Delete at the end of a container's last child pulls the next block in", async () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "callout",
+ id: "c-0",
+ children: [{ id: "c-p-0", type: "paragraph", content: "In callout" }],
+ },
+ { id: "after", type: "paragraph", content: "After" },
+ ]);
+
+ await pressKey("Delete", { block: "c-p-0", placement: "end" });
+
+ expect(editor.getBlock("c-0")!.children.map((child) => child.id)).toEqual([
+ "c-p-0",
+ "after",
+ ]);
+ expect(editor.document.map((block) => block.id)).toEqual(["c-0"]);
+ });
+});
+
+// Sealed-boundary counterparts to the open cases above. Every implicit
+// crossing must be a no-op on a sealed container, while edits within the
+// container keep working.
+describe("sealed boundary keyboard handling", () => {
+ function documentShape() {
+ return editor.document.map((block) => [
+ block.id,
+ block.children.map((child) => child.id),
+ ]);
+ }
+
+ it("Backspace at the start of the first child does not move it out", async () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "before", type: "paragraph", content: "Before" },
+ {
+ type: "sealedBox",
+ id: "s-0",
+ children: [
+ { id: "s-p-0", type: "paragraph", content: "First" },
+ { id: "s-p-1", type: "paragraph", content: "Second" },
+ ],
+ },
+ ]);
+ const shape = documentShape();
+
+ await pressKey("Backspace", { block: "s-p-0", placement: "start" });
+
+ expect(documentShape()).toEqual(shape);
+ expect(editor.getTextCursorPosition().block.id).toBe("s-p-0");
+ });
+
+ it("Backspace at the start of the second child still merges within", async () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "sealedBox",
+ id: "s-0",
+ children: [
+ { id: "s-p-0", type: "paragraph", content: "First" },
+ { id: "s-p-1", type: "paragraph", content: "Second" },
+ ],
+ },
+ ]);
+
+ await pressKey("Backspace", { block: "s-p-1", placement: "start" });
+
+ // Asserting the merge guards against the suite passing because
+ // keystrokes never arrive.
+ const children = editor.getBlock("s-0")!.children;
+ expect(children).toHaveLength(1);
+ expect(children[0].content).toEqual([
+ { type: "text", text: "FirstSecond", styles: {} },
+ ]);
+ });
+
+ it("Backspace after the container does not move the block inside", async () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "sealedBox",
+ id: "s-0",
+ children: [{ id: "s-p-0", type: "paragraph", content: "Sealed" }],
+ },
+ { id: "after", type: "paragraph", content: "After" },
+ ]);
+ const shape = documentShape();
+
+ await pressKey("Backspace", { block: "after", placement: "start" });
+
+ expect(documentShape()).toEqual(shape);
+ // With no way in, the fallback node-selects the container, so a second
+ // Backspace deletes it explicitly.
+ const selection = editor.transact((tr) => tr.selection);
+ expect("node" in selection && (selection.node as any).type.name).toBe(
+ "sealedBox",
+ );
+ });
+
+ it("Backspace after the container does not replace its trailing empty block", async () => {
+ // The previous case falls through the "descend into the previous
+ // container" branch; this one targets the "previous block is empty"
+ // branch, which descends to the bottom nested block, here the empty
+ // paragraph inside the sealed container.
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "sealedBox",
+ id: "s-0",
+ children: [
+ { id: "s-p-0", type: "paragraph", content: "Sealed" },
+ { id: "s-p-1", type: "paragraph", content: "" },
+ ],
+ },
+ { id: "after", type: "paragraph", content: "After" },
+ ]);
+ const shape = documentShape();
+
+ await pressKey("Backspace", { block: "after", placement: "start" });
+
+ expect(documentShape()).toEqual(shape);
+ });
+
+ it("Delete before the container does not pull its first child out", async () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "before", type: "paragraph", content: "Before" },
+ {
+ type: "sealedBox",
+ id: "s-0",
+ children: [
+ { id: "s-p-0", type: "paragraph", content: "First" },
+ { id: "s-p-1", type: "paragraph", content: "Second" },
+ ],
+ },
+ ]);
+ const shape = documentShape();
+
+ await pressKey("Delete", { block: "before", placement: "end" });
+
+ expect(documentShape()).toEqual(shape);
+ });
+
+ it("Delete at the end of the last child does not pull the next block in", async () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "sealedBox",
+ id: "s-0",
+ children: [{ id: "s-p-0", type: "paragraph", content: "Sealed" }],
+ },
+ { id: "after", type: "paragraph", content: "After" },
+ ]);
+ const shape = documentShape();
+
+ await pressKey("Delete", { block: "s-p-0", placement: "end" });
+
+ expect(documentShape()).toEqual(shape);
+ });
+
+ it("Delete at the end of a nested last block does not reach past the boundary", async () => {
+ // The climb in "delete next block at any level" starts from a nested
+ // block, where the direct last-child branch doesn't apply. Without its
+ // own gate, Delete here would consume "after" into the sealed container.
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "sealedBox",
+ id: "s-0",
+ children: [
+ {
+ id: "s-p-0",
+ type: "paragraph",
+ content: "Parent",
+ children: [{ id: "s-n-0", type: "paragraph", content: "Nested" }],
+ },
+ ],
+ },
+ { id: "after", type: "paragraph", content: "After" },
+ ]);
+ const shape = documentShape();
+
+ await pressKey("Delete", { block: "s-n-0", placement: "end" });
+
+ expect(documentShape()).toEqual(shape);
+ });
+
+ it("Backspace after an isolated container of sealed ones selects it", async () => {
+ // Same shape as tables: the grid itself is not sealed, but every place a
+ // descent could land is sealed. The block can't move in, so the grid is
+ // selected for an explicit second-Backspace delete instead.
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "sealedGrid",
+ id: "g-0",
+ children: [
+ {
+ type: "sealedBox",
+ id: "g-c-0",
+ children: [{ id: "g-p-0", type: "paragraph", content: "Cell" }],
+ },
+ ],
+ },
+ { id: "after", type: "paragraph", content: "After" },
+ ]);
+ const shape = documentShape();
+
+ await pressKey("Backspace", { block: "after", placement: "start" });
+
+ expect(documentShape()).toEqual(shape);
+ const selection = editor.transact((tr) => tr.selection);
+ expect("node" in selection && (selection.node as any).type.name).toBe(
+ "sealedGrid",
+ );
+ });
+
+ it("Enter on an empty last child stays inside the container", async () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "sealedBox",
+ id: "s-0",
+ children: [
+ { id: "s-p-0", type: "paragraph", content: "Hello" },
+ { id: "s-p-1", type: "paragraph", content: "" },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ await pressKey("Enter", { block: "s-p-1", placement: "end" });
+
+ // A sealed boundary means Enter never moves content out, so there is no
+ // double-Enter escape. The new block is created inside.
+ expect(editor.document.map((block) => block.type)).toEqual([
+ "sealedBox",
+ "paragraph",
+ ]);
+ const children = editor.getBlock("s-0")!.children;
+ expect(children).toHaveLength(3);
+ expect(editor.getTextCursorPosition().block.id).toBe(children[2].id);
+ });
+});
+
+// HTML round-trips (full, external, clipboard) live with the parse rules in
+// `schema/blocks/containerParse.browser.test.ts`.
+describe("children conversion", () => {
+ it("flattens containers to their children in markdown export", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "callout",
+ id: "c-0",
+ children: [
+ { id: "c-p-0", type: "paragraph", content: "In callout" },
+ { id: "c-p-1", type: "heading", content: "Heading in callout" },
+ ],
+ },
+ ]);
+
+ const markdown = editor.blocksToMarkdownLossy(editor.document);
+ expect(markdown).toContain("In callout");
+ expect(markdown).toContain("# Heading in callout");
+ });
+});
diff --git a/packages/core/src/api/blockManipulation/containers/containers.fixture.ts b/packages/core/src/api/blockManipulation/containers/containers.fixture.ts
new file mode 100644
index 0000000000..934f5a727c
--- /dev/null
+++ b/packages/core/src/api/blockManipulation/containers/containers.fixture.ts
@@ -0,0 +1,133 @@
+import { BlockNoteSchema } from "../../../blocks/BlockNoteSchema.js";
+import { defaultBlockSpecs } from "../../../blocks/defaultBlocks.js";
+import { createBlockSpec } from "../../../schema/blocks/createSpec.js";
+
+const renderDiv = () => {
+ const dom = document.createElement("div");
+ return { dom, contentDOM: dom };
+};
+
+const Callout = createBlockSpec(
+ {
+ type: "callout" as const,
+ propSchema: {
+ flavor: {
+ default: "tip",
+ values: ["tip", "info", "warning", "success"],
+ },
+ },
+ content: "none",
+ children: {
+ allow: "any",
+ default: [{ type: "paragraph" }],
+ },
+ },
+ { render: renderDiv },
+)();
+
+// A compartment-style container, like a table cell. Content never implicitly
+// crosses its boundary.
+const SealedBox = createBlockSpec(
+ {
+ type: "sealedBox" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: "any", boundary: "sealed" },
+ },
+ { render: renderDiv },
+)();
+
+// An open container, like a column list: editing gestures cross its edge.
+// Same as leaving `boundary` out, spelled explicitly.
+const OpenBox = createBlockSpec(
+ {
+ type: "openBox" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: "any", boundary: "open" },
+ },
+ { render: renderDiv },
+)();
+
+// Same shape as tables: a container that holds only sealed ones, so any
+// descent into it bottoms out at a sealed boundary.
+const SealedGrid = createBlockSpec(
+ {
+ type: "sealedGrid" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: ["sealedBox"] },
+ },
+ { render: renderDiv },
+)();
+
+const Grid = createBlockSpec(
+ {
+ type: "grid" as const,
+ propSchema: {},
+ content: "none",
+ children: {
+ allow: ["gridCell"],
+ min: 2,
+ whenEmptied: "unwrap",
+ },
+ },
+ { render: renderDiv },
+)();
+
+const GridCell = createBlockSpec(
+ {
+ type: "gridCell" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: "any" },
+ placement: "containerOnly",
+ },
+ { render: renderDiv },
+)();
+
+// A refill (default `whenEmptied`) container whose `default` has content.
+// Dropping below `min` tops it back up from the unconsumed tail of `default`.
+const SeededPair = createBlockSpec(
+ {
+ type: "seededPair" as const,
+ propSchema: {},
+ content: "none",
+ children: {
+ allow: "any",
+ min: 2,
+ default: [
+ { type: "paragraph", content: "Seed A" },
+ { type: "paragraph", content: "Seed B" },
+ ],
+ },
+ },
+ { render: renderDiv },
+)();
+
+// A container that only accepts regular blocks, not other container blocks.
+// Used to check that placement validation matches on the moved block's real
+// node type rather than always assuming a `blockContainer`.
+const BlocksOnlyBox = createBlockSpec(
+ {
+ type: "blocksOnlyBox" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: "blocks" },
+ },
+ { render: renderDiv },
+)();
+
+export const containerSchema = BlockNoteSchema.create().extend({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ callout: Callout,
+ sealedBox: SealedBox,
+ openBox: OpenBox,
+ sealedGrid: SealedGrid,
+ grid: Grid,
+ gridCell: GridCell,
+ seededPair: SeededPair,
+ blocksOnlyBox: BlocksOnlyBox,
+ } as const,
+});
diff --git a/packages/core/src/api/blockManipulation/containers/containers.test.ts b/packages/core/src/api/blockManipulation/containers/containers.test.ts
new file mode 100644
index 0000000000..b5c06522e8
--- /dev/null
+++ b/packages/core/src/api/blockManipulation/containers/containers.test.ts
@@ -0,0 +1,530 @@
+// @vitest-environment node
+import { TextSelection } from "prosemirror-state";
+import {
+ afterAll,
+ beforeAll,
+ beforeEach,
+ describe,
+ expect,
+ it,
+} from "vite-plus/test";
+
+import { BlockNoteEditor } from "../../../editor/BlockNoteEditor.js";
+import { getParentBlockInfo } from "../../getBlockInfoFromPos.js";
+import { getNodeById } from "../../nodeUtil.js";
+import { containerSchema } from "./containers.fixture.js";
+
+type PartialBlock = (typeof containerSchema)["PartialBlock"];
+
+// Document-model behaviour of container blocks: seeding, schema enforcement,
+// repair and selection. Everything is `Block` JSON in and out, so the editor
+// runs headless with no DOM.
+//
+// The keymap (tiptap can only reach it through a mounted view) and
+// HTML/markdown serialization (builds real DOM) are tested in
+// `containers.browser.test.ts`.
+
+const schema = containerSchema;
+
+let editor: BlockNoteEditor<
+ typeof schema.blockSchema,
+ typeof schema.inlineContentSchema,
+ typeof schema.styleSchema
+>;
+
+beforeAll(() => {
+ editor = BlockNoteEditor.create({ schema });
+});
+
+afterAll(() => {
+ editor._tiptapEditor.destroy();
+ editor = undefined as any;
+});
+
+beforeEach(() => {
+ editor.replaceBlocks(editor.document, [
+ { id: "p-0", type: "paragraph", content: "Paragraph 0" },
+ { id: "p-1", type: "paragraph", content: "Paragraph 1" },
+ ]);
+});
+
+describe("children insertion & seeding", () => {
+ it("seeds `default` when inserted without children", () => {
+ editor.insertBlocks([{ type: "callout", id: "c-0" }], "p-1", "after");
+
+ const callout = editor.getBlock("c-0")!;
+ expect(callout.children).toHaveLength(1);
+ expect(callout.children[0].type).toBe("paragraph");
+ });
+
+ // Regression: `min` defaults to 1 and nothing seeded a container without
+ // `default`, so inserting one threw a raw ProseMirror
+ // `RangeError: Invalid content for node ...`.
+ it("fills a container that has no `default`, with real child ids", () => {
+ expect(() =>
+ editor.insertBlocks([{ type: "sealedBox", id: "b-0" }], "p-1", "after"),
+ ).not.toThrow();
+
+ const box = editor.getBlock("b-0")!;
+ expect(box.children).toHaveLength(1);
+ expect(box.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(box.children[0].id).toBeTruthy();
+ expect(editor.getBlock(box.children[0].id)).toBeDefined();
+ });
+
+ it("does not re-seed a container round-tripped through the document", () => {
+ editor.insertBlocks([{ type: "callout", id: "c-0" }], "p-1", "after");
+ const inserted = editor.getBlock("c-0")!;
+
+ // `nodeToBlock` always emits an array, so a round-trip must not read an
+ // empty one as "unspecified" and seed on top of it.
+ editor.replaceBlocks([inserted], [inserted]);
+
+ expect(editor.getBlock("c-0")!.children).toHaveLength(
+ inserted.children.length,
+ );
+ });
+
+ // 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();
+ });
+
+ // A container that unwraps as it empties is the one case explicit children
+ // are not padded: adding a second column to a one-column columnList would
+ // invent content the next repair pass deletes anyway.
+ it("refuses rather than pads a container that unwraps when emptied", () => {
+ expect(() =>
+ editor.insertBlocks(
+ [{ type: "grid", id: "g-1", children: [{ type: "gridCell" }] }],
+ "p-1",
+ "after",
+ ),
+ ).toThrow();
+ });
+
+ it("accepts arbitrary block children, including nested containers", () => {
+ editor.insertBlocks(
+ [
+ {
+ type: "callout",
+ id: "c-0",
+ children: [
+ { type: "heading", content: "In callout" },
+ {
+ type: "callout",
+ id: "c-1",
+ children: [{ type: "paragraph", content: "Nested" }],
+ },
+ ],
+ },
+ ],
+ "p-1",
+ "after",
+ );
+
+ const callout = editor.getBlock("c-0")!;
+ expect(callout.children.map((child) => child.type)).toEqual([
+ "heading",
+ "callout",
+ ]);
+ expect(editor.getBlock("c-1")!.children[0].type).toBe("paragraph");
+ });
+
+ it("enforces a restricted container's allow list", () => {
+ editor.insertBlocks(
+ [
+ {
+ type: "grid",
+ id: "g-0",
+ children: [{ type: "gridCell" }, { type: "gridCell" }],
+ },
+ ],
+ "p-1",
+ "after",
+ );
+ expect(editor.getBlock("g-0")!.children.map((child) => child.type)).toEqual(
+ ["gridCell", "gridCell"],
+ );
+
+ expect(() =>
+ editor.insertBlocks(
+ [
+ {
+ type: "grid",
+ children: [
+ { type: "paragraph", content: "not a cell" },
+ { type: "paragraph", content: "not a cell" },
+ ],
+ },
+ ],
+ "p-1",
+ "after",
+ ),
+ ).toThrow();
+ });
+
+ // The `allow: "any"` wildcard compiles to the containers placeable
+ // anywhere, so a containerOnly block only fits where a parent names it
+ // explicitly: not at the root, and not under a wildcard container.
+ it("rejects a containerOnly block outside a parent that names it", () => {
+ expect(() =>
+ editor.insertBlocks(
+ [{ type: "gridCell", children: [{ type: "paragraph" }] }],
+ "p-1",
+ "after",
+ ),
+ ).toThrow();
+
+ expect(() =>
+ editor.insertBlocks(
+ [
+ {
+ type: "callout",
+ children: [{ type: "gridCell", children: [{ type: "paragraph" }] }],
+ },
+ ],
+ "p-1",
+ "after",
+ ),
+ ).toThrow();
+ });
+});
+
+describe("boundary", () => {
+ // No container is `isolating`, whatever its boundary. PM only honours that
+ // flag while no selection spans the edge, and nothing prevents one: given a
+ // spanning slice, `Fitter` refuses to open into the container and wraps the
+ // content in a spurious `blockGroup`, corrupting the document. Seals are
+ // enforced by BlockNote's own `isSealed` guards instead.
+ it("leaves every container non-isolating, seal or no seal", () => {
+ const nodes = editor.pmSchema.nodes;
+ for (const type of ["openBox", "callout", "sealedBox", "gridCell"]) {
+ expect(nodes[type].spec.isolating).toBeFalsy();
+ }
+ });
+
+ // The corruption the line above avoids, pinned end to end: copy a selection
+ // running from inside a container to after it, paste it back over itself,
+ // and the document must come back unchanged. Marking the container
+ // `isolating` instead re-nests the whole fragment a level too deep.
+ it.each(["openBox", "callout", "sealedBox"])(
+ "round-trips a paste across a %s's edge",
+ (type) => {
+ editor.replaceBlocks(editor.document, [
+ {
+ id: "c",
+ type,
+ children: [
+ { id: "c1", type: "paragraph", content: "Inner one" },
+ { id: "c2", type: "paragraph", content: "Inner two" },
+ ],
+ },
+ { id: "a", type: "paragraph", content: "After" },
+ ] as PartialBlock[]);
+
+ const before = JSON.stringify(editor.document);
+
+ editor.transact((tr) => {
+ let from = 0;
+ let to = 0;
+ tr.doc.descendants((node, pos) => {
+ if (node.isText && node.text === "Inner two") {
+ from = pos;
+ }
+ if (node.isText && node.text === "After") {
+ to = pos + node.nodeSize;
+ }
+ });
+
+ const selection = TextSelection.create(tr.doc, from, to);
+ tr.setSelection(selection).replace(from, to, selection.content());
+ });
+
+ expect(JSON.stringify(editor.document)).toBe(before);
+ },
+ );
+});
+
+// `initialContent` is the only path that builds a document without validating
+// it, since `blockToNode` is deliberately lenient and `createDocument` builds
+// from JSON. Regression: blocks that `insertBlocks` rejects loaded without
+// error, and a container below its `min` stayed there for the life of the
+// document.
+describe("initialContent enforcement", () => {
+ const createWith = (initialContent: PartialBlock[]) => {
+ return BlockNoteEditor.create({ schema, initialContent });
+ };
+
+ it("fills an explicitly empty `children` array up to `min`", () => {
+ const loaded = createWith([{ type: "callout", id: "c-0", children: [] }]);
+
+ const callout = loaded.getBlock("c-0")!;
+ expect(callout.children).toHaveLength(1);
+ expect(callout.children[0].type).toBe("paragraph");
+
+ loaded._tiptapEditor.destroy();
+ });
+
+ it("rejects a container it cannot legally fill", () => {
+ expect(() =>
+ createWith([
+ { type: "grid", id: "g-0", children: [{ type: "gridCell" }] },
+ ]),
+ ).toThrow(/initialContent/);
+ });
+});
+
+describe("children repair", () => {
+ it("keeps a default container when its only child is removed (refilled)", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "callout",
+ id: "c-0",
+ children: [{ id: "c-p-0", type: "paragraph", content: "Only child" }],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ editor.removeBlocks(["c-p-0"]);
+
+ const callout = editor.getBlock("c-0")!;
+ expect(callout).toBeDefined();
+ expect(callout.children).toHaveLength(1);
+ expect(callout.children[0].type).toBe("paragraph");
+ expect(callout.children[0].content).toEqual([]);
+ });
+
+ it("refills below `min` from the unconsumed tail of `default`", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "seededPair",
+ id: "s-0",
+ children: [
+ { id: "s-p-0", type: "paragraph", content: "Kept" },
+ { id: "s-p-1", type: "paragraph", content: "Removed" },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ editor.removeBlocks(["s-p-1"]);
+
+ // One child survives (k = 1), so the top-up seeds `default[1]`, not an
+ // empty paragraph and not `default[0]`.
+ const pair = editor.getBlock("s-0")!;
+ expect(pair.children).toHaveLength(2);
+ expect(pair.children[0].content).toEqual([
+ { type: "text", text: "Kept", styles: {} },
+ ]);
+ expect(pair.children[1].content).toEqual([
+ { type: "text", text: "Seed B", styles: {} },
+ ]);
+ });
+
+ it("unwraps a repair-configured container when only one non-empty child remains", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "grid",
+ id: "g-0",
+ children: [
+ {
+ type: "gridCell",
+ id: "cell-a",
+ children: [{ id: "cell-a-p", type: "paragraph", content: "A" }],
+ },
+ {
+ type: "gridCell",
+ id: "cell-b",
+ children: [{ id: "cell-b-p", type: "paragraph", content: "B" }],
+ },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ editor.removeBlocks(["cell-a-p"]);
+
+ expect(editor.getBlock("g-0")).toBeUndefined();
+ expect(editor.document.map((block) => block.id)).toEqual([
+ "cell-b-p",
+ "trailing",
+ ]);
+ });
+
+ // Unlike `refillContainer` (which leaves empty children alone at or above
+ // `min` — they may be intentional), the unwrap repair drops emptied
+ // children unconditionally: an emptied third column disappears rather than
+ // lingering, even though the list stays valid without unwrapping. The
+ // multicolumn e2e snapshots pin the same behavior from the keyboard side.
+ it("drops emptied children of an unwrap container even at or above `min`", () => {
+ 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" }],
+ },
+ {
+ type: "gridCell",
+ id: "cell-c",
+ children: [{ id: "cell-c-p", type: "paragraph", content: "" }],
+ },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ // Removing a block inside cell A runs repair on the grid; the emptied
+ // cell C is dropped, and with cells A and B still meeting `min: 2` the
+ // grid itself survives.
+ editor.removeBlocks(["cell-a-extra"]);
+
+ const grid = editor.getBlock("g-0")!;
+ expect(grid.children.map((cell) => cell.id)).toEqual(["cell-a", "cell-b"]);
+ });
+});
+
+describe("parent lookups for container children", () => {
+ // Regression: `getParentBlockInfo` used to skip the container level for
+ // container children (returning the grid for a block inside a gridCell),
+ // which made the Delete-at-end climb run its sealed-container check on the
+ // wrong node. The parent of a block is the block whose `children` contains
+ // it: the cell.
+ it("returns the container as the parent of its direct children", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "grid",
+ id: "g-0",
+ children: [
+ {
+ type: "gridCell",
+ id: "cell-a",
+ children: [{ id: "cell-a-p", type: "paragraph", content: "A" }],
+ },
+ {
+ type: "gridCell",
+ id: "cell-b",
+ children: [{ id: "cell-b-p", type: "paragraph", content: "B" }],
+ },
+ ],
+ },
+ { id: "trailing", type: "paragraph", content: "" },
+ ]);
+
+ editor.transact((tr) => {
+ // The block directly containing a cell's paragraph is the cell.
+ const cellChild = getNodeById("cell-a-p", tr.doc)!;
+ expect(
+ getParentBlockInfo(tr.doc, cellChild.posBeforeNode)?.blockNoteType,
+ ).toBe("gridCell");
+
+ // The parent of a cell is the grid; the parent of the grid (a
+ // top-level block) is undefined.
+ const cell = getNodeById("cell-a", tr.doc)!;
+ expect(
+ getParentBlockInfo(tr.doc, cell.posBeforeNode)?.blockNoteType,
+ ).toBe("grid");
+
+ const grid = getNodeById("g-0", tr.doc)!;
+ expect(getParentBlockInfo(tr.doc, grid.posBeforeNode)).toBeUndefined();
+ });
+ });
+});
+
+describe("children selection", () => {
+ it("getSelectionCutBlocks handles selections reaching into a container", () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "before", type: "paragraph", content: "Before" },
+ {
+ type: "callout",
+ id: "c-0",
+ children: [
+ { id: "c-p-0", type: "paragraph", content: "First" },
+ { id: "c-p-1", type: "paragraph", content: "Second" },
+ ],
+ },
+ ]);
+ editor.setSelection("before", "c-p-0");
+
+ // Previously threw "unexpected" for any partial selection touching a
+ // container (breaking comments/AI selection handling).
+ const result = editor.getSelectionCutBlocks();
+ expect(result.blocks.length).toBeGreaterThanOrEqual(1);
+ expect(result.blocks.map((block) => block.id)).toContain("before");
+ });
+});
+
+describe("empty unwrap container", () => {
+ // A `min >= 1`, `whenEmptied: "unwrap"` container with no `default` used to
+ // build a schema-invalid node, so `node.check()` (run before the repair
+ // pass) threw a raw RangeError instead of inserting.
+ it("inserting an empty unwrap container 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();
+ });
+});
+
+describe("moveBlocks placement validation", () => {
+ // `checkPlacementIsValid` used to probe with `blockContainer`, so it accepted
+ // a placement inside a blocks-only container for a container block (e.g. a
+ // `callout`) that `insertBlocks` then rejected, throwing. It must validate
+ // against the moved block's real node type and skip the invalid placement.
+ it("moving a container block past a blocks-only container does not throw", () => {
+ editor.replaceBlocks(editor.document, [
+ { id: "p-0", type: "paragraph", content: "Paragraph 0" },
+ {
+ id: "box",
+ type: "blocksOnlyBox",
+ children: [{ id: "box-p", type: "paragraph", content: "Inside" }],
+ },
+ {
+ id: "c-0",
+ type: "callout",
+ children: [{ id: "c-p", type: "paragraph", content: "Callout" }],
+ },
+ ]);
+
+ expect(() => editor.moveBlocksUp("c-0")).not.toThrow();
+ // The callout can't nest in the blocks-only box, so it lands directly
+ // above it as a top-level sibling rather than being forced inside.
+ expect(editor.getParentBlock("c-0")).toBeUndefined();
+ expect(editor.document.map((block) => block.id)).toEqual([
+ "p-0",
+ "c-0",
+ "box",
+ ]);
+ });
+});
diff --git a/packages/core/src/api/blockManipulation/containers/fixContainer.ts b/packages/core/src/api/blockManipulation/containers/fixContainer.ts
new file mode 100644
index 0000000000..b2bffa3848
--- /dev/null
+++ b/packages/core/src/api/blockManipulation/containers/fixContainer.ts
@@ -0,0 +1,274 @@
+import { Fragment, Slice, type Node, type NodeType } from "prosemirror-model";
+import { type Transaction } from "prosemirror-state";
+import { ReplaceAroundStep } from "prosemirror-transform";
+
+import {
+ type BlockInfo,
+ getBlockInfoFromNode,
+} from "../../getBlockInfoFromPos.js";
+
+import {
+ isBlockGroupInsertable,
+ isContainerNode,
+ resolveChildren,
+} from "../../../schema/blocks/children.js";
+import type { ResolvedChildren } from "../../../schema/blocks/children.js";
+import type { PartialBlock } from "../../../blocks/defaultBlocks.js";
+import { blockToNode } from "../../nodeConversions/blockToNode.js";
+import { getNodeById } from "../../nodeUtil.js";
+
+// Defined in `children.ts` (it answers a schema-level question); re-exported
+// here because the public root export (`index.ts`) imports it from this
+// module.
+export { isContainerNode };
+
+export function isEmptyContainerChild(node: Node): boolean {
+ if (node.type.name === "blockContainer") {
+ const blockContent = node.firstChild;
+ return (
+ node.childCount === 1 &&
+ !!blockContent &&
+ blockContent.type.name === "paragraph" &&
+ blockContent.childCount === 0
+ );
+ }
+ if (isContainerNode(node.type)) {
+ return node.childCount === 1 && isEmptyContainerChild(node.firstChild!);
+ }
+ return false;
+}
+
+export function removeEmptyChildren(tr: Transaction, containerPos: number) {
+ const container = tr.doc.resolve(containerPos).nodeAfter;
+ if (!container || !isContainerNode(container.type)) {
+ throw new Error(
+ "Invalid containerPos: does not point to a container node.",
+ );
+ }
+
+ // Collected before deleting anything, so every position is taken from the
+ // same (untouched) container, then applied back to front so the earlier
+ // ones stay valid.
+ const emptyChildren: { from: number; to: number }[] = [];
+ container.forEach((child, offset) => {
+ if (isEmptyContainerChild(child)) {
+ const from = containerPos + 1 + offset;
+ emptyChildren.push({ from, to: from + child.nodeSize });
+ }
+ });
+
+ for (let i = emptyChildren.length - 1; i >= 0; i--) {
+ tr.delete(emptyChildren[i].from, emptyChildren[i].to);
+ }
+}
+
+/**
+ * The container's BlockInfo at `containerPos` in `tr`'s current doc, or
+ * `undefined` when the node there is gone or no longer of `type`.
+ */
+function getContainerInfo(
+ tr: Transaction,
+ containerPos: number,
+ type: NodeType,
+): Extract | undefined {
+ const node = tr.doc.resolve(containerPos).nodeAfter;
+ if (!node || node.type !== type) {
+ return undefined;
+ }
+ const info = getBlockInfoFromNode(node, containerPos);
+ if (info.hasContent) {
+ // `type` is a container node type, so its BlockInfo always takes the
+ // no-content arm.
+ throw new Error(
+ `Container node "${type.name}" unexpectedly resolved with a content node.`,
+ );
+ }
+ return info;
+}
+
+export function fixContainer(tr: Transaction, containerPos: number) {
+ const node = tr.doc.resolve(containerPos).nodeAfter;
+ if (!node || !isContainerNode(node.type)) {
+ throw new Error(
+ "Invalid containerPos: does not point to a container node.",
+ );
+ }
+
+ const blockConfig = node.type.spec.blockConfig;
+ const childrenConfig = blockConfig?.children;
+ const config = childrenConfig ? resolveChildren(childrenConfig) : undefined;
+
+ if (!config) {
+ return;
+ }
+
+ if (config.whenEmptied === "unwrap") {
+ unwrapContainer(tr, containerPos, node.type, config);
+ } else {
+ refillContainer(tr, containerPos, node.type, config);
+ }
+}
+
+function unwrapContainer(
+ tr: Transaction,
+ containerPos: number,
+ type: NodeType,
+ config: ResolvedChildren,
+) {
+ // Emptied children are dropped unconditionally, even when the container
+ // sits at or above `min` afterwards: for an unwrap container (a
+ // columnList), a child the user emptied is done for — an emptied third
+ // column disappears rather than lingering. This deliberately differs from
+ // `refillContainer`, which leaves empty children alone at or above `min`.
+ removeEmptyChildren(tr, containerPos);
+
+ const info = getContainerInfo(tr, containerPos, type);
+ if (!info) {
+ return;
+ }
+ const { childrenStart } = info.children;
+
+ const nonEmptyChildren: { child: Node; offset: number }[] = [];
+ info.children.node.forEach((child, offset) => {
+ if (!isEmptyContainerChild(child)) {
+ nonEmptyChildren.push({ child, offset });
+ }
+ });
+
+ if (nonEmptyChildren.length >= config.min) {
+ return;
+ }
+
+ const blockEnd = info.block.afterPos;
+
+ if (nonEmptyChildren.length === 0) {
+ tr.delete(info.block.beforePos, blockEnd);
+ return;
+ }
+
+ // Unwrap: replace the container with its remaining non-empty children.
+ if (nonEmptyChildren.length === 1) {
+ const { child, offset } = nonEmptyChildren[0];
+ const childStart = childrenStart + offset;
+
+ const [gapFrom, gapTo] = isBlockGroupInsertable(child.type)
+ ? [childStart, childStart + child.nodeSize]
+ : [childStart + 1, childStart + child.nodeSize - 1];
+
+ tr.step(
+ new ReplaceAroundStep(
+ info.block.beforePos,
+ blockEnd,
+ gapFrom,
+ gapTo,
+ Slice.empty,
+ 0,
+ false,
+ ),
+ );
+ return;
+ }
+
+ // Several survivors but still below `min`: rebuild replacement content.
+ const replacement: Node[] = [];
+ for (const { child } of nonEmptyChildren) {
+ if (isBlockGroupInsertable(child.type)) {
+ replacement.push(child);
+ } else {
+ child.forEach((grandChild) => replacement.push(grandChild));
+ }
+ }
+ tr.replaceWith(info.block.beforePos, blockEnd, Fragment.from(replacement));
+}
+
+/**
+ * The `whenEmptied: "refill"` repair: when fewer than `min` non-empty
+ * children remain, drop the emptied ones and top the container back up.
+ * Position `k..min-1` (k = surviving count) is seeded from the container's
+ * `default`, falling back to `fillBefore`-style empty fill when `default` is
+ * absent. Deterministic, appended at the end.
+ *
+ * Rebuilt in a single replace: removing an empty child first would make
+ * ProseMirror's schema fitting instantly pad the container back to `min` with
+ * a fresh empty child, hiding the deficit from the seeding step.
+ */
+function refillContainer(
+ tr: Transaction,
+ containerPos: number,
+ type: NodeType,
+ config: ResolvedChildren,
+) {
+ const info = getContainerInfo(tr, containerPos, type);
+ if (!info) {
+ return;
+ }
+ const { node: children, childrenStart, childrenEnd } = info.children;
+
+ const survivors: Node[] = [];
+ children.forEach((child) => {
+ if (!isEmptyContainerChild(child)) {
+ survivors.push(child);
+ }
+ });
+ // At or above the minimum, empty children are left alone: they may be
+ // intentional.
+ if (survivors.length >= config.min) {
+ return;
+ }
+
+ // The refill seeds are the unconsumed tail of the container's `default`
+ // (`default[survivors.length..min-1]`), each converted exactly like an
+ // inserted block. Empty when the container has no `default`; the remainder
+ // is padded with empty fill below.
+ const seeds = (config.default ?? [])
+ .slice(survivors.length, config.min)
+ .map((child) =>
+ blockToNode(child as PartialBlock, tr.doc.type.schema),
+ );
+
+ if (seeds.length === 0) {
+ // No `default` to seed from, so empty children are the right fill, and
+ // ProseMirror's schema fitting has usually already padded the container
+ // back to `min` with them. Complete the fill only when it hasn't.
+ const match = children.type.contentMatch.matchFragment(children.content);
+ const fill = match?.fillBefore(Fragment.empty, true);
+ if (fill && fill.size > 0) {
+ tr.insert(childrenEnd, fill);
+ }
+ return;
+ }
+
+ // Survivors keep their place; the seeds land at the end, replacing the
+ // emptied (or schema-padded) children.
+ let content = Fragment.from([...survivors, ...seeds]);
+ const match = children.type.contentMatch.matchFragment(content);
+ const fill = match?.fillBefore(Fragment.empty, true);
+ if (fill) {
+ content = content.append(fill);
+ }
+
+ tr.replaceWith(childrenStart, childrenEnd, content);
+}
+
+/**
+ * Runs `fixContainer` on each of the given containers, looked up by ID in
+ * `tr`'s current doc. Containers are repaired deepest-first so that an inner
+ * repair (e.g. a column emptying out) is observed by the outer container's
+ * repair (e.g. its columnList unwrapping) in the same pass. Containers that
+ * no longer exist by the time their turn comes are skipped — an earlier
+ * repair may have removed them.
+ */
+export function fixContainersById(
+ tr: Transaction,
+ containers: { id: string; depth: number }[],
+) {
+ [...containers]
+ .sort((a, b) => b.depth - a.depth)
+ .forEach(({ id }) => {
+ const target = getNodeById(id, tr.doc);
+ if (!target) {
+ return;
+ }
+ fixContainer(tr, target.posBeforeNode);
+ });
+}
diff --git a/packages/core/src/api/blockManipulation/getBlock/getBlock.ts b/packages/core/src/api/blockManipulation/getBlock/getBlock.ts
index 1d87f58b49..98fc3b7eef 100644
--- a/packages/core/src/api/blockManipulation/getBlock/getBlock.ts
+++ b/packages/core/src/api/blockManipulation/getBlock/getBlock.ts
@@ -6,6 +6,7 @@ import type {
InlineContentSchema,
StyleSchema,
} from "../../../schema/index.js";
+import { getParentBlockInfo } from "../../getBlockInfoFromPos.js";
import { nodeToBlock } from "../../nodeConversions/nodeToBlock.js";
import { getNodeById } from "../../nodeUtil.js";
@@ -94,18 +95,10 @@ export function getParentBlock<
return undefined;
}
- const $posBeforeNode = doc.resolve(posInfo.posBeforeNode);
- const parentNode = $posBeforeNode.node();
- const grandparentNode = $posBeforeNode.node(-1);
- const nodeToConvert =
- grandparentNode.type.name !== "doc"
- ? parentNode.type.name === "blockGroup"
- ? grandparentNode
- : parentNode
- : undefined;
- if (!nodeToConvert) {
+ const parentInfo = getParentBlockInfo(doc, posInfo.posBeforeNode);
+ if (!parentInfo) {
return undefined;
}
- return nodeToBlock(nodeToConvert, doc);
+ return nodeToBlock(parentInfo.block.node, doc);
}
diff --git a/packages/core/src/api/blockManipulation/selections/selection.ts b/packages/core/src/api/blockManipulation/selections/selection.ts
index d6229a3f0a..34591c8c8d 100644
--- a/packages/core/src/api/blockManipulation/selections/selection.ts
+++ b/packages/core/src/api/blockManipulation/selections/selection.ts
@@ -1,5 +1,4 @@
import { TextSelection, type Transaction } from "prosemirror-state";
-import { TableMap } from "prosemirror-tables";
import { Block } from "../../../blocks/defaultBlocks.js";
import { Selection } from "../../../editor/selectionTypes.js";
import {
@@ -9,13 +8,16 @@ import {
StyleSchema,
} from "../../../schema/index.js";
import { expandPMRangeToWords } from "../../../util/expandToWords.js";
-import { getBlockInfo, getNearestBlockPos } from "../../getBlockInfoFromPos.js";
+import {
+ blockEdgePos,
+ getBlockInfoFromNode,
+ getNearestBlockPos,
+} from "../../getBlockInfoFromPos.js";
import {
nodeToBlock,
prosemirrorSliceToSlicedBlocks,
} from "../../nodeConversions/nodeToBlock.js";
import { getNodeById } from "../../nodeUtil.js";
-import { getBlockNoteSchema, getPmSchema } from "../../pmUtil.js";
export function getSelection<
BSchema extends BlockSchema,
@@ -140,8 +142,6 @@ export function setSelection(
const startBlockId =
typeof startBlock === "string" ? startBlock : startBlock.id;
const endBlockId = typeof endBlock === "string" ? endBlock : endBlock.id;
- const pmSchema = getPmSchema(tr);
- const schema = getBlockNoteSchema(pmSchema);
if (startBlockId === endBlockId) {
throw new Error(
@@ -157,62 +157,28 @@ export function setSelection(
throw new Error(`Block with ID ${endBlockId} not found`);
}
- const anchorBlockInfo = getBlockInfo(anchorPosInfo);
- const headBlockInfo = getBlockInfo(headPosInfo);
-
- const anchorBlockConfig =
- schema.blockSchema[
- anchorBlockInfo.blockNoteType as keyof typeof schema.blockSchema
- ];
- const headBlockConfig =
- schema.blockSchema[
- headBlockInfo.blockNoteType as keyof typeof schema.blockSchema
- ];
+ const anchorBlockInfo = getBlockInfoFromNode(
+ anchorPosInfo.node,
+ anchorPosInfo.posBeforeNode,
+ );
+ const headBlockInfo = getBlockInfoFromNode(
+ headPosInfo.node,
+ headPosInfo.posBeforeNode,
+ );
- if (
- !anchorBlockInfo.isBlockContainer ||
- anchorBlockConfig.content === "none"
- ) {
+ const startPos = blockEdgePos(anchorBlockInfo, "start");
+ if (startPos === null) {
throw new Error(
`Attempting to set selection anchor in block without content (id ${startBlockId})`,
);
}
- if (!headBlockInfo.isBlockContainer || headBlockConfig.content === "none") {
+ const endPos = blockEdgePos(headBlockInfo, "end");
+ if (endPos === null) {
throw new Error(
- `Attempting to set selection anchor in block without content (id ${endBlockId})`,
+ `Attempting to set selection head in block without content (id ${endBlockId})`,
);
}
- let startPos: number;
- let endPos: number;
-
- if (anchorBlockConfig.content === "table") {
- const tableMap = TableMap.get(anchorBlockInfo.blockContent.node);
- const firstCellPos =
- anchorBlockInfo.blockContent.beforePos +
- tableMap.positionAt(0, 0, anchorBlockInfo.blockContent.node) +
- 1;
- startPos = firstCellPos + 2;
- } else {
- startPos = anchorBlockInfo.blockContent.beforePos + 1;
- }
-
- if (headBlockConfig.content === "table") {
- const tableMap = TableMap.get(headBlockInfo.blockContent.node);
- const lastCellPos =
- headBlockInfo.blockContent.beforePos +
- tableMap.positionAt(
- tableMap.height - 1,
- tableMap.width - 1,
- headBlockInfo.blockContent.node,
- ) +
- 1;
- const lastCellNodeSize = tr.doc.resolve(lastCellPos).nodeAfter!.nodeSize;
- endPos = lastCellPos + lastCellNodeSize - 2;
- } else {
- endPos = headBlockInfo.blockContent.afterPos - 1;
- }
-
// TODO: We should polish up the `MultipleNodeSelection` and use that instead.
// Right now it's missing a few things like a jsonID and styling to show
// which nodes are selected. `TextSelection` is ok for now, but has the
diff --git a/packages/core/src/api/blockManipulation/selections/textCursorPosition.ts b/packages/core/src/api/blockManipulation/selections/textCursorPosition.ts
index b0b2cc078d..0130af1992 100644
--- a/packages/core/src/api/blockManipulation/selections/textCursorPosition.ts
+++ b/packages/core/src/api/blockManipulation/selections/textCursorPosition.ts
@@ -1,9 +1,4 @@
-import type { Node } from "prosemirror-model";
-import {
- NodeSelection,
- TextSelection,
- type Transaction,
-} from "prosemirror-state";
+import { type Transaction } from "prosemirror-state";
import type { TextCursorPosition } from "../../../editor/cursorPositionTypes.js";
import type {
BlockIdentifier,
@@ -11,43 +6,34 @@ import type {
InlineContentSchema,
StyleSchema,
} from "../../../schema/index.js";
-import { UnreachableCaseError } from "../../../util/typescript.js";
import {
- getBlockInfo,
+ blockEdgeSelection,
+ getBlockInfoFromNode,
getBlockInfoFromSelection,
- getNodeId,
+ getParentBlockInfo,
} from "../../getBlockInfoFromPos.js";
import { nodeToBlock } from "../../nodeConversions/nodeToBlock.js";
import { getNodeById } from "../../nodeUtil.js";
-import { getBlockNoteSchema, getPmSchema } from "../../pmUtil.js";
export function getTextCursorPosition<
BSchema extends BlockSchema,
I extends InlineContentSchema,
S extends StyleSchema,
>(tr: Transaction): TextCursorPosition {
- const { bnBlock } = getBlockInfoFromSelection(tr);
+ const { block } = getBlockInfoFromSelection(tr);
- const resolvedPos = tr.doc.resolve(bnBlock.beforePos);
+ const resolvedPos = tr.doc.resolve(block.beforePos);
// Gets previous blockContainer node at the same nesting level, if the current node isn't the first child.
const prevNode = resolvedPos.nodeBefore;
// Gets next blockContainer node at the same nesting level, if the current node isn't the last child.
- const nextNode = tr.doc.resolve(bnBlock.afterPos).nodeAfter;
+ const nextNode = tr.doc.resolve(block.afterPos).nodeAfter;
- // Gets parent blockContainer node, if the current node is nested.
- let parentNode: Node | undefined = undefined;
- if (resolvedPos.depth > 1) {
- // for nodes nested in bnBlocks
- parentNode = resolvedPos.node();
- if (!parentNode.type.isInGroup("bnBlock")) {
- // for blockGroups, we need to go one level up
- parentNode = resolvedPos.node(resolvedPos.depth - 1);
- }
- }
+ // Gets the parent block's node, if the current block is nested.
+ const parentNode = getParentBlockInfo(tr.doc, block.beforePos)?.block.node;
return {
- block: nodeToBlock(bnBlock.node, tr.doc),
+ block: nodeToBlock(block.node, tr.doc),
prevBlock: prevNode === null ? undefined : nodeToBlock(prevNode, tr.doc),
nextBlock: nextNode === null ? undefined : nodeToBlock(nextNode, tr.doc),
parentBlock:
@@ -61,58 +47,17 @@ export function setTextCursorPosition(
placement: "start" | "end" = "start",
) {
const id = typeof targetBlock === "string" ? targetBlock : targetBlock.id;
- const pmSchema = getPmSchema(tr.doc);
- const schema = getBlockNoteSchema(pmSchema);
const posInfo = getNodeById(id, tr.doc);
if (!posInfo) {
throw new Error(`Block with ID ${id} not found`);
}
- const info = getBlockInfo(posInfo);
-
- const contentType: "none" | "inline" | "table" | "plain" =
- schema.blockSchema[info.blockNoteType]!.content;
-
- if (info.isBlockContainer) {
- const blockContent = info.blockContent;
- if (contentType === "none") {
- tr.setSelection(NodeSelection.create(tr.doc, blockContent.beforePos));
- return;
- }
-
- if (contentType === "inline" || contentType === "plain") {
- if (placement === "start") {
- tr.setSelection(
- TextSelection.create(tr.doc, blockContent.beforePos + 1),
- );
- } else {
- tr.setSelection(
- TextSelection.create(tr.doc, blockContent.afterPos - 1),
- );
- }
- } else if (contentType === "table") {
- if (placement === "start") {
- // Need to offset the position as we have to get through the `tableRow`
- // and `tableCell` nodes to get to the `tableParagraph` node we want to
- // set the selection in.
- tr.setSelection(
- TextSelection.create(tr.doc, blockContent.beforePos + 4),
- );
- } else {
- tr.setSelection(
- TextSelection.create(tr.doc, blockContent.afterPos - 4),
- );
- }
- } else {
- throw new UnreachableCaseError(contentType);
- }
- } else {
- const child =
- placement === "start"
- ? info.childContainer.node.firstChild!
- : info.childContainer.node.lastChild!;
-
- setTextCursorPosition(tr, getNodeId(child, tr.doc), placement);
- }
+ tr.setSelection(
+ blockEdgeSelection(
+ tr.doc,
+ getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode),
+ placement,
+ ),
+ );
}
diff --git a/packages/core/src/api/blockManipulation/setupTestEnv.ts b/packages/core/src/api/blockManipulation/setupTestEnv.ts
index c1da2be25e..c54fea1f09 100644
--- a/packages/core/src/api/blockManipulation/setupTestEnv.ts
+++ b/packages/core/src/api/blockManipulation/setupTestEnv.ts
@@ -1,14 +1,43 @@
import { afterAll, beforeAll, beforeEach } from "vite-plus/test";
-import { PartialBlock } from "../../blocks/defaultBlocks.js";
+import { BlockNoteSchema } from "../../blocks/BlockNoteSchema.js";
+import {
+ DefaultBlockSchema,
+ DefaultInlineContentSchema,
+ DefaultStyleSchema,
+ PartialBlock,
+} from "../../blocks/defaultBlocks.js";
import { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
+import {
+ BlockSchema,
+ InlineContentSchema,
+ StyleSchema,
+} from "../../schema/index.js";
-export function setupTestEnv() {
- let editor: BlockNoteEditor;
+/**
+ * Mounts an editor for a test file and resets its document before each test.
+ *
+ * Called without arguments it uses the default schema and {@link testDocument}.
+ * A custom schema and document have to be passed together, since a document is
+ * only valid against the schema it was written for.
+ */
+export function setupTestEnv<
+ B extends BlockSchema = DefaultBlockSchema,
+ I extends InlineContentSchema = DefaultInlineContentSchema,
+ S extends StyleSchema = DefaultStyleSchema,
+>(options?: {
+ schema: BlockNoteSchema;
+ document: PartialBlock[];
+}): () => BlockNoteEditor {
+ let editor: BlockNoteEditor;
const div = document.createElement("div");
beforeAll(() => {
- editor = BlockNoteEditor.create();
+ // `B`/`I`/`S` fall back to the default schema's types, but TS can't see
+ // that from inside the body, so the no-options branch needs a cast.
+ editor = options
+ ? BlockNoteEditor.create({ schema: options.schema })
+ : (BlockNoteEditor.create() as unknown as BlockNoteEditor);
editor.mount(div);
});
@@ -18,13 +47,16 @@ export function setupTestEnv() {
});
beforeEach(() => {
- editor.replaceBlocks(editor.document, testDocument);
+ editor.replaceBlocks(
+ editor.document,
+ options?.document ?? (testDocument as unknown as PartialBlock[]),
+ );
});
return () => editor;
}
-const testDocument: PartialBlock[] = [
+export const testDocument: PartialBlock[] = [
{
id: "paragraph-0",
type: "paragraph",
diff --git a/packages/core/src/api/clipboard/fromClipboard/handleFileInsertion.ts b/packages/core/src/api/clipboard/fromClipboard/handleFileInsertion.ts
index aa422bb23a..74af5ba031 100644
--- a/packages/core/src/api/clipboard/fromClipboard/handleFileInsertion.ts
+++ b/packages/core/src/api/clipboard/fromClipboard/handleFileInsertion.ts
@@ -5,7 +5,7 @@ import {
InlineContentSchema,
StyleSchema,
} from "../../../schema/index.js";
-import { getBlockInfoAtNearest, getNodeId } from "../../getBlockInfoFromPos.js";
+import { getBlockInfoNearPos, getNodeId } from "../../getBlockInfoFromPos.js";
import { acceptedMIMETypes } from "./acceptedMIMETypes.js";
function checkFileExtensionsMatch(
@@ -159,8 +159,8 @@ export async function handleFileInsertion<
}
insertedBlockId = editor.transact((tr) => {
- const blockInfo = getBlockInfoAtNearest(tr, pos.pos);
- const id = getNodeId(blockInfo.bnBlock.node, tr.doc);
+ const blockInfo = getBlockInfoNearPos(tr, pos.pos);
+ const id = getNodeId(blockInfo.block.node, tr.doc);
// TODO technically data-id will always be the non-rewritten id, so there might be multiple in the document.
// getNodeId might find the wrong one (aka point to a deleted node when it should be a non-deleted on)
// This is acceptable right now, given that we don't expect edits on the document content
diff --git a/packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts b/packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts
index e2274140f7..759bb4bbd6 100644
--- a/packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts
+++ b/packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts
@@ -8,6 +8,8 @@ import {
InlineContentSchema,
StyleSchema,
} from "../../../../schema/index.js";
+import { fillContainerAttributes } from "../../../../schema/blocks/containerAttributes.js";
+import { containerRootDOM } from "../../../../schema/blocks/createSpec.js";
import { UnreachableCaseError } from "../../../../util/typescript.js";
import {
inlineContentToNodes,
@@ -241,10 +243,15 @@ function serializeBlock<
const elementFragment = doc.createDocumentFragment();
- if ((ret.dom as HTMLElement).classList.contains("bn-block-content")) {
+ // A fragment `dom` (the shape a React render produces) can't hold classes
+ // or attributes itself; its resolved root element (the single element it
+ // wraps, if any) stands in for it everywhere below.
+ const rootElement = containerRootDOM(ret);
+
+ if (rootElement?.classList.contains("bn-block-content")) {
const blockContentDataAttributes = [
...attrs,
- ...Array.from((ret.dom as HTMLElement).attributes),
+ ...Array.from(rootElement.attributes),
].filter(
(attr) =>
attr.name.startsWith("data") &&
@@ -256,26 +263,49 @@ function serializeBlock<
attr.name !== "data-editable",
);
- // ret.dom = ret.dom.firstChild! as any;
for (const attr of blockContentDataAttributes) {
- (ret.dom.firstChild! as HTMLElement).setAttribute(attr.name, attr.value);
+ (rootElement.firstChild! as HTMLElement).setAttribute(
+ attr.name,
+ attr.value,
+ );
}
- addAttributesAndRemoveClasses(ret.dom.firstChild! as HTMLElement);
+ addAttributesAndRemoveClasses(rootElement.firstChild! as HTMLElement);
if (nestingLevel > 0) {
- (ret.dom.firstChild! as HTMLElement).setAttribute(
+ (rootElement.firstChild! as HTMLElement).setAttribute(
"data-nesting-level",
nestingLevel.toString(),
);
}
- elementFragment.append(...Array.from(ret.dom.childNodes));
+ // Discard the `bn-block-content` wrapper (and, for a fragment `dom`, the
+ // fragment around it) and keep only its children.
+ elementFragment.append(...Array.from(rootElement.childNodes));
} else {
+ // Asked of the block config rather than of its ProseMirror node. See the
+ // same check in `serializeBlocksInternalHTML`.
+ if (editor.schema.blockSchema[block.type as any].children !== undefined) {
+ // Container blocks own their outer DOM. Make sure the attributes
+ // needed to parse the HTML back (the type marker and non-default
+ // props, in the same `data-*` convention `propsToAttributes` reads)
+ // are present even when the block's render didn't add them.
+ // Author-set attributes win.
+ fillContainerAttributes(
+ rootElement,
+ block.type!,
+ props,
+ editor.schema.blockSchema[block.type as any].propSchema,
+ );
+
+ // Mark where the children live, mirroring the internal serializer, so
+ // the container's parse rule can scope itself to this element
+ // (`contentElement` in `getParseRules`) when the HTML is pasted back.
+ // Without the marker, non-content UI the render puts elsewhere in its
+ // DOM (button labels, captions, ...) parses back as document content.
+ ret.contentDOM?.setAttribute("data-children-of", block.type!);
+ }
elementFragment.append(ret.dom);
if (nestingLevel > 0) {
- (ret.dom as HTMLElement).setAttribute(
- "data-nesting-level",
- nestingLevel.toString(),
- );
+ rootElement?.setAttribute("data-nesting-level", nestingLevel.toString());
}
}
@@ -301,11 +331,9 @@ function serializeBlock<
// tables) fill their `contentDOM` with child blocks later on, and code
// blocks would turn the placeholder into literal content.
const blockNodeType = editor.pmSchema.nodes[block.type as any];
- if (
- blockNodeType?.inlineContent &&
- !blockNodeType.spec.code &&
- ret.contentDOM.childNodes.length === 0
- ) {
+ const needsPlaceholder =
+ !!blockNodeType?.inlineContent && !blockNodeType.spec.code;
+ if (needsPlaceholder && ret.contentDOM.childNodes.length === 0) {
ret.contentDOM.appendChild(doc.createTextNode(EMPTY_BLOCK_PLACEHOLDER));
}
}
diff --git a/packages/core/src/api/exporters/html/util/serializeBlocksInternalHTML.ts b/packages/core/src/api/exporters/html/util/serializeBlocksInternalHTML.ts
index 0f890b77ab..319cafd3fc 100644
--- a/packages/core/src/api/exporters/html/util/serializeBlocksInternalHTML.ts
+++ b/packages/core/src/api/exporters/html/util/serializeBlocksInternalHTML.ts
@@ -7,6 +7,8 @@ import {
InlineContentSchema,
StyleSchema,
} from "../../../../schema/index.js";
+import { fillContainerAttributes } from "../../../../schema/blocks/containerAttributes.js";
+import { containerRootDOM } from "../../../../schema/blocks/createSpec.js";
import { UnreachableCaseError } from "../../../../util/typescript.js";
import {
inlineContentToNodes,
@@ -159,6 +161,9 @@ function serializeBlock<
editor as any,
);
+ const blockConfig = editor.schema.blockSchema[block.type as any];
+ const isContainer = blockConfig.children !== undefined;
+
if (ret.contentDOM && block.content) {
const ic = serializeInlineContentInternalHTML(
editor,
@@ -170,9 +175,26 @@ function serializeBlock<
ret.contentDOM.appendChild(ic);
}
- const pmType = editor.pmSchema.nodes[block.type as any];
+ if (isContainer) {
+ // Container blocks own their outer DOM. Internal HTML must round-trip
+ // losslessly, so make sure the attributes the generated parse rules read
+ // (the type marker and non-default props as `data-*`) are present even
+ // when the block's render didn't add them. Author-set attributes win.
+ fillContainerAttributes(
+ containerRootDOM(ret),
+ block.type!,
+ props,
+ blockConfig.propSchema,
+ );
- if (pmType.isInGroup("bnBlock")) {
+ // Mark where the children live so the container's round-trip parse rule
+ // can scope itself to this element (`contentElement` in `getParseRules`).
+ // A render is free to put non-content UI text elsewhere in its DOM
+ // (button labels, captions, ...), and without the marker that text would
+ // parse back as document content.
+ if (ret.contentDOM) {
+ ret.contentDOM.setAttribute("data-children-of", block.type!);
+ }
if (block.children && block.children.length > 0) {
const fragment = serializeBlocks(
editor,
diff --git a/packages/core/src/api/getBlockInfoFromPos.test.ts b/packages/core/src/api/getBlockInfoFromPos.test.ts
index 6af6e7b6d8..3787b64879 100644
--- a/packages/core/src/api/getBlockInfoFromPos.test.ts
+++ b/packages/core/src/api/getBlockInfoFromPos.test.ts
@@ -1,9 +1,17 @@
-import { Schema } from "prosemirror-model";
+import { Node, Schema } from "prosemirror-model";
import { describe, expect, it } from "vite-plus/test";
import { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
+import { blockToNode } from "./nodeConversions/blockToNode.js";
import { docToBlocks } from "./nodeConversions/nodeToBlock.js";
-import { getNodeId } from "./getBlockInfoFromPos.js";
+import {
+ getBlockInfoFromNode,
+ getLastDescendantBlockInfo,
+ getNextBlockInfo,
+ getNodeId,
+ getParentBlockInfo,
+ getPrevBlockInfo,
+} from "./getBlockInfoFromPos.js";
import { YAttributionMarksExtension } from "../y/extensions/YAttributionMarks.js";
/**
@@ -168,6 +176,227 @@ describe("getNodeId", () => {
});
});
+describe("derived position and content fields", () => {
+ let editor: BlockNoteEditor;
+
+ // Only the schema is needed to construct nodes; a single non-mounted editor
+ // instance is enough for all cases here.
+ function getSchema() {
+ if (!editor) {
+ editor = BlockNoteEditor.create();
+ }
+ return editor.pmSchema;
+ }
+
+ it("precomputes content bounds for an inline-content block", () => {
+ const schema = getSchema();
+ const node = blockToNode(
+ { id: "0", type: "paragraph", content: "Hello" } as any,
+ schema,
+ );
+
+ // A non-zero offset, so the derived positions provably include it.
+ const info = getBlockInfoFromNode(node, 10);
+
+ expect(info.hasContent).toBe(true);
+ expect(info.contentStart).toBe(info.content!.beforePos + 1);
+ expect(info.contentEnd).toBe(info.content!.afterPos - 1);
+ expect(info.contentKind).toBe("inline");
+ expect(info.isContentEmpty).toBe(false);
+ expect(info.children).toBeUndefined();
+ });
+
+ it("flags an empty inline-content block", () => {
+ const schema = getSchema();
+ const node = blockToNode(
+ { id: "0", type: "paragraph", content: "" } as any,
+ schema,
+ );
+
+ const info = getBlockInfoFromNode(node, 0);
+
+ expect(info.contentKind).toBe("inline");
+ expect(info.isContentEmpty).toBe(true);
+ // An empty content node still has an inside: start and end coincide.
+ expect(info.contentStart).toBe(info.contentEnd);
+ });
+
+ it("precomputes children bounds when a block has children", () => {
+ const schema = getSchema();
+ const node = blockToNode(
+ {
+ id: "0",
+ type: "paragraph",
+ content: "Parent",
+ children: [{ id: "1", type: "paragraph", content: "Child" }],
+ } as any,
+ schema,
+ );
+
+ const info = getBlockInfoFromNode(node, 0);
+
+ expect(info.children).toBeDefined();
+ expect(info.children!.childrenStart).toBe(info.children!.beforePos + 1);
+ expect(info.children!.childrenEnd).toBe(info.children!.afterPos - 1);
+ });
+
+ it("classifies a table's content", () => {
+ const schema = getSchema();
+ const node = blockToNode(
+ {
+ id: "0",
+ type: "table",
+ content: { type: "tableContent", rows: [{ cells: ["A"] }] },
+ } as any,
+ schema,
+ );
+
+ const info = getBlockInfoFromNode(node, 0);
+
+ expect(info.contentKind).toBe("table");
+ expect(info.isContentEmpty).toBe(false);
+ });
+
+ it("classifies a content-less block", () => {
+ const schema = getSchema();
+ const node = blockToNode({ id: "0", type: "image" } as any, schema);
+
+ const info = getBlockInfoFromNode(node, 0);
+
+ // The block HAS a content node; that node just accepts no content.
+ expect(info.hasContent).toBe(true);
+ expect(info.contentKind).toBe("none");
+ expect(info.isContentEmpty).toBe(true);
+ });
+
+ it("classifies plain-text content as plain", () => {
+ const schema = getSchema();
+ const node = blockToNode(
+ { id: "0", type: "codeBlock", content: "let x;" } as any,
+ schema,
+ );
+
+ const info = getBlockInfoFromNode(node, 0);
+
+ expect(info.contentKind).toBe("plain");
+ });
+});
+
+describe("navigation helpers on plain nested blocks", () => {
+ let editor: BlockNoteEditor;
+
+ function getSchema() {
+ if (!editor) {
+ editor = BlockNoteEditor.create();
+ }
+ return editor.pmSchema;
+ }
+
+ // doc
+ // └ blockGroup
+ // ├ A
+ // │ ├ B
+ // │ └ C
+ // │ └ D
+ // └ E
+ function buildDoc() {
+ const schema = getSchema();
+ const nodeA = blockToNode(
+ {
+ id: "A",
+ type: "paragraph",
+ content: "A",
+ children: [
+ { id: "B", type: "paragraph", content: "B" },
+ {
+ id: "C",
+ type: "paragraph",
+ content: "C",
+ children: [{ id: "D", type: "paragraph", content: "D" }],
+ },
+ ],
+ } as any,
+ schema,
+ );
+ const nodeE = blockToNode(
+ { id: "E", type: "paragraph", content: "E" } as any,
+ schema,
+ );
+ return schema.nodes["doc"].createChecked(
+ {},
+ schema.nodes["blockGroup"].createChecked({}, [nodeA, nodeE]),
+ );
+ }
+
+ function posOf(doc: Node, id: string): number {
+ let found: number | undefined;
+ doc.descendants((node, pos) => {
+ if (node.attrs.id === id) {
+ found = pos;
+ return false;
+ }
+ return true;
+ });
+ if (found === undefined) {
+ throw new Error(`Block ${id} not found`);
+ }
+ return found;
+ }
+
+ it("finds the parent block, or undefined at the top level", () => {
+ const doc = buildDoc();
+ expect(getParentBlockInfo(doc, posOf(doc, "B"))?.block.node.attrs.id).toBe(
+ "A",
+ );
+ expect(getParentBlockInfo(doc, posOf(doc, "D"))?.block.node.attrs.id).toBe(
+ "C",
+ );
+ expect(getParentBlockInfo(doc, posOf(doc, "A"))).toBeUndefined();
+ });
+
+ it("finds the previous sibling, or undefined for a first child", () => {
+ const doc = buildDoc();
+ expect(getPrevBlockInfo(doc, posOf(doc, "C"))?.block.node.attrs.id).toBe(
+ "B",
+ );
+ expect(getPrevBlockInfo(doc, posOf(doc, "E"))?.block.node.attrs.id).toBe(
+ "A",
+ );
+ expect(getPrevBlockInfo(doc, posOf(doc, "B"))).toBeUndefined();
+ });
+
+ it("finds the next sibling, or undefined for a last child", () => {
+ const doc = buildDoc();
+ expect(getNextBlockInfo(doc, posOf(doc, "B"))?.block.node.attrs.id).toBe(
+ "C",
+ );
+ expect(getNextBlockInfo(doc, posOf(doc, "A"))?.block.node.attrs.id).toBe(
+ "E",
+ );
+ expect(getNextBlockInfo(doc, posOf(doc, "C"))).toBeUndefined();
+ });
+
+ it("descends to the deepest last block", () => {
+ const doc = buildDoc();
+ const infoA = getBlockInfoFromNode(
+ doc.nodeAt(posOf(doc, "A"))!,
+ posOf(doc, "A"),
+ );
+ expect(getLastDescendantBlockInfo(doc, infoA).block.node.attrs.id).toBe(
+ "D",
+ );
+
+ const infoE = getBlockInfoFromNode(
+ doc.nodeAt(posOf(doc, "E"))!,
+ posOf(doc, "E"),
+ );
+ // No children: the block itself is the bottom one.
+ expect(getLastDescendantBlockInfo(doc, infoE).block.node.attrs.id).toBe(
+ "E",
+ );
+ });
+});
+
describe("docToBlocks round trip with suggested deletions", () => {
let editor: BlockNoteEditor;
diff --git a/packages/core/src/api/getBlockInfoFromPos.ts b/packages/core/src/api/getBlockInfoFromPos.ts
index 04ed789c98..4ab02d85e2 100644
--- a/packages/core/src/api/getBlockInfoFromPos.ts
+++ b/packages/core/src/api/getBlockInfoFromPos.ts
@@ -1,5 +1,30 @@
-import { Node, ResolvedPos } from "prosemirror-model";
-import { EditorState, Transaction } from "prosemirror-state";
+import { Node } from "prosemirror-model";
+import {
+ EditorState,
+ NodeSelection,
+ Selection,
+ TextSelection,
+ Transaction,
+} from "prosemirror-state";
+
+import {
+ CHILD_CONTAINER_GROUP,
+ getBlockRegions,
+ isSealed,
+} from "../schema/blocks/children.js";
+
+/**
+ * Producers for {@link BlockInfo}, named by the input you already have:
+ *
+ * - `getBlockInfoFromNode(node, beforePos)` — you hold the block's ProseMirror
+ * node and the position just before it.
+ * - `getBlockInfoAt(doc, posBeforeBlock)` — you know the exact position just
+ * before a block node (throws if no node starts there).
+ * - `getBlockInfoNearPos(source, pos)` — you have an arbitrary position; walks
+ * up/over to the nearest block.
+ * - `getBlockInfoFromSelection(source)` — you want the block containing the
+ * current selection anchor.
+ */
type SingleBlockInfo = {
node: Node;
@@ -7,43 +32,169 @@ type SingleBlockInfo = {
afterPos: number;
};
+/**
+ * The node holding a block's children, plus the bounds of the child range.
+ */
+export type ChildrenInfo = SingleBlockInfo & {
+ /**
+ * `beforePos + 1`: the position of the first child; also the insertion
+ * position for a new first child.
+ */
+ childrenStart: number;
+ /** `afterPos - 1`: the position just after the last child. */
+ childrenEnd: number;
+};
+
+/**
+ * What a block's content node holds, derived from its ProseMirror content
+ * expression.
+ */
+export type BlockContentKind = "inline" | "plain" | "none" | "table" | "other";
+
+function getContentKind(contentNode: Node): BlockContentKind {
+ const content = contentNode.type.spec.content;
+ return content === "inline*"
+ ? "inline"
+ : content === "text*"
+ ? "plain"
+ : content === ""
+ ? "none"
+ : content === "tableRow+"
+ ? "table"
+ : "other";
+}
+
+function toChildrenInfo(info: SingleBlockInfo): ChildrenInfo {
+ return {
+ ...info,
+ childrenStart: info.beforePos + 1,
+ childrenEnd: info.afterPos - 1,
+ };
+}
+
export type BlockInfo = {
/**
* The outer node that represents a BlockNote block. This is the node that has the ID.
* Most of the time, this will be a blockContainer node, but it could also be a Column or ColumnList
*/
- bnBlock: SingleBlockInfo;
+ block: SingleBlockInfo;
/**
* The type of BlockNote block that this node represents.
- * When dealing with a blockContainer, this is retrieved from the blockContent node, otherwise it's retrieved from the bnBlock node.
+ * When dealing with a blockContainer, this is retrieved from the content node, otherwise it's retrieved from the block node.
*/
blockNoteType: string;
} & (
| {
- // In case we're not dealing with a BlockContainer, we're dealing with a "wrapper node" (like a Column or ColumnList), so it will always have children
+ // A container block (Column, ColumnList, a custom container): its own
+ // node holds its children directly, and it has no content node of
+ // its own.
/**
- * The Prosemirror node that holds block.children. For non-blockContainer, this node will be the same as bnBlock.
+ * The Prosemirror node that holds block.children. For a container block,
+ * this node is the same as `block`.
*/
- childContainer: SingleBlockInfo;
- isBlockContainer: false;
+ children: ChildrenInfo;
+ content?: undefined;
+ hasContent: false;
+ contentStart?: undefined;
+ contentEnd?: undefined;
+ contentKind?: undefined;
+ isContentEmpty?: undefined;
}
| {
/**
* The Prosemirror node that holds block.children. For blockContainers, this is the blockGroup node, if it exists.
*/
- childContainer?: SingleBlockInfo;
+ children?: ChildrenInfo;
/**
* The Prosemirror node that wraps block.content and has most of the props
*/
- blockContent: SingleBlockInfo;
+ content: SingleBlockInfo;
+ /** `content.beforePos + 1`: the first position inside the content. */
+ contentStart: number;
+ /** `content.afterPos - 1`: the last position inside the content. */
+ contentEnd: number;
+ /** What the content node holds, from its ProseMirror content expression. */
+ contentKind: BlockContentKind;
+ /** `content.node.childCount === 0`. */
+ isContentEmpty: boolean;
/**
- * Whether bnBlock is a blockContainer node
+ * Whether the block has a content node: a `blockContainer` (an
+ * ordinary block wrapped for nesting), shaped as a content node
+ * followed by an optional child container.
+ *
+ * Note this is the opposite of "is a container block": a column has
+ * `hasContent: false`.
*/
- isBlockContainer: true;
+ hasContent: true;
}
);
+/**
+ * The caret position at an edge of a table content region: 4 levels in
+ * (`table` → `tableRow` → `tableCell` → `tableParagraph`) from the region's
+ * boundary — the first cell's paragraph start, or the last cell's paragraph
+ * end.
+ */
+export function tableContentCaretPos(
+ content: { beforePos: number; afterPos: number },
+ edge: "start" | "end",
+): number {
+ return edge === "start" ? content.beforePos + 4 : content.afterPos - 4;
+}
+
+/**
+ * The caret position at an edge of a block's content, or `null` when the block
+ * has none there: a container block, or content that holds no text (an image).
+ */
+export function blockEdgePos(
+ info: BlockInfo,
+ edge: "start" | "end",
+): number | null {
+ if (!info.hasContent || info.contentKind === "none") {
+ return null;
+ }
+ return info.contentKind === "table"
+ ? tableContentCaretPos(info.content, edge)
+ : edge === "start"
+ ? info.contentStart
+ : info.contentEnd;
+}
+
+/**
+ * A selection at an edge of a block. A container resolves to the same edge of
+ * its first/last child, recursively. Where there is no caret position the
+ * nearest node is selected instead: the content node of a block holding no
+ * text, or the block itself for a container holding no children.
+ */
+export function blockEdgeSelection(
+ doc: Node,
+ info: BlockInfo,
+ edge: "start" | "end",
+): Selection {
+ const pos = blockEdgePos(info, edge);
+ if (pos !== null) {
+ return TextSelection.create(doc, pos);
+ }
+ if (info.hasContent) {
+ return NodeSelection.create(doc, info.content.beforePos);
+ }
+
+ const { node, childrenStart, childrenEnd } = info.children;
+ const child = edge === "start" ? node.firstChild : node.lastChild;
+ if (!child) {
+ return NodeSelection.create(doc, info.block.beforePos);
+ }
+ return blockEdgeSelection(
+ doc,
+ getBlockInfoFromNode(
+ child,
+ edge === "start" ? childrenStart : childrenEnd - child.nodeSize,
+ ),
+ edge,
+ );
+}
+
export function isSuggestedDeletionNode(node: Node): boolean {
return node.marks.some((m) => ["y-attributed-delete"].includes(m.type.name));
}
@@ -154,138 +305,208 @@ export function getNearestBlockPos(doc: Node, pos: number) {
/**
* Gets information regarding the ProseMirror nodes that make up a block in a
- * BlockNote document. This includes the main `blockContainer` node, the
- * `blockContent` node with the block's main body, and the optional `blockGroup`
- * node which contains the block's children. As well as the nodes, also returns
- * the ProseMirror positions just before & after each node.
- * @param node The main `blockContainer` node that the block information should
- * be retrieved from,
- * @param bnBlockBeforePosOffset the position just before the
- * `blockContainer` node in the document.
+ * BlockNote document, given the block's outer node and the position just
+ * before it. This includes the outer node with the block's ID, the content
+ * node with the block's main body, and the optional node which contains the
+ * block's children. As well as the nodes, also returns the ProseMirror
+ * positions just before & after each node.
+ * @param node The outer node that the block information should be retrieved
+ * from.
+ * @param beforePos The position just before the outer node in the document.
*/
-export function getBlockInfoWithManualOffset(
- node: Node,
- bnBlockBeforePosOffset: number,
-): BlockInfo {
+export function getBlockInfoFromNode(node: Node, beforePos: number): BlockInfo {
if (!node.type.isInGroup("bnBlock")) {
throw new Error(
- `Attempted to get bnBlock node at position but found node of different type ${node.type.name}`,
+ `Attempted to get block node at position but found node of different type ${node.type.name}`,
);
}
- const bnBlockNode = node;
- const bnBlockBeforePos = bnBlockBeforePosOffset;
- const bnBlockAfterPos = bnBlockBeforePos + bnBlockNode.nodeSize;
+ // The one place block shape is resolved; everything below is position
+ // annotation over the regions.
+ const regions = getBlockRegions(node);
- const bnBlock: SingleBlockInfo = {
- node: bnBlockNode,
- beforePos: bnBlockBeforePos,
- afterPos: bnBlockAfterPos,
+ const block: SingleBlockInfo = {
+ node,
+ beforePos,
+ afterPos: beforePos + node.nodeSize,
};
- if (bnBlockNode.type.name === "blockContainer") {
- let blockContent: SingleBlockInfo | undefined;
- let blockGroup: SingleBlockInfo | undefined;
-
- bnBlockNode.forEach((node, offset) => {
- if (node.type.spec.group === "blockContent") {
- // console.log(beforePos, offset);
- const blockContentNode = node;
- const blockContentBeforePos = bnBlockBeforePos + offset + 1;
- const blockContentAfterPos = blockContentBeforePos + node.nodeSize;
-
- blockContent = {
- node: blockContentNode,
- beforePos: blockContentBeforePos,
- afterPos: blockContentAfterPos,
- };
- } else if (node.type.name === "blockGroup") {
- const blockGroupNode = node;
- const blockGroupBeforePos = bnBlockBeforePos + offset + 1;
- const blockGroupAfterPos = blockGroupBeforePos + node.nodeSize;
-
- blockGroup = {
- node: blockGroupNode,
- beforePos: blockGroupBeforePos,
- afterPos: blockGroupAfterPos,
- };
- }
- });
-
- if (!blockContent) {
- throw new Error(
- // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
- `blockContainer node does not contain a blockContent node in its children: ${bnBlockNode}`,
- );
- }
-
- return {
- isBlockContainer: true,
- bnBlock,
- blockContent,
- childContainer: blockGroup,
- blockNoteType: blockContent.node.type.name,
+ if (regions.content) {
+ const content: SingleBlockInfo = {
+ node: regions.content.node,
+ beforePos: beforePos + regions.content.offset,
+ afterPos:
+ beforePos + regions.content.offset + regions.content.node.nodeSize,
};
- } else {
- if (!bnBlock.node.type.isInGroup("childContainer")) {
- throw new Error(
- // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
- `bnBlock node is not in the childContainer group: ${bnBlock.node}`,
- );
- }
-
+ const holder = regions.childrenHolder;
return {
- isBlockContainer: false,
- bnBlock: bnBlock,
- childContainer: bnBlock,
- blockNoteType: bnBlock.node.type.name,
+ hasContent: true,
+ block,
+ content,
+ children: holder
+ ? toChildrenInfo({
+ node: holder.node,
+ beforePos: beforePos + holder.offset,
+ afterPos: beforePos + holder.offset + holder.node.nodeSize,
+ })
+ : undefined,
+ contentStart: content.beforePos + 1,
+ contentEnd: content.afterPos - 1,
+ contentKind: getContentKind(content.node),
+ isContentEmpty: content.node.childCount === 0,
+ // A `blockContainer` is a generic wrapper, so its type comes from the
+ // content node inside it.
+ blockNoteType: content.node.type.name,
};
}
-}
-/**
- * Gets information regarding the ProseMirror nodes that make up a block in a
- * BlockNote document. This includes the main `blockContainer` node, the
- * `blockContent` node with the block's main body, and the optional `blockGroup`
- * node which contains the block's children. As well as the nodes, also returns
- * the ProseMirror positions just before & after each node.
- * @param posInfo An object with the main `blockContainer` node that the block
- * information should be retrieved from, and the position just before it in the
- * document.
- */
-export function getBlockInfo(posInfo: { posBeforeNode: number; node: Node }) {
- return getBlockInfoWithManualOffset(posInfo.node, posInfo.posBeforeNode);
+ return {
+ hasContent: false,
+ block,
+ // A container holds its children directly, so the holder is the block
+ // node itself.
+ children: toChildrenInfo(block),
+ blockNoteType: node.type.name,
+ };
}
/**
- * Gets information regarding the ProseMirror nodes that make up a block from a
- * resolved position just before the `blockContainer` node in the document that
- * corresponds to it.
- * @param resolvedPos The resolved position just before the `blockContainer`
- * node.
+ * Gets information regarding the ProseMirror nodes that make up a block, given
+ * a position known to be just before a block node. Throws if no node starts at
+ * that position.
+ * @param doc The ProseMirror doc.
+ * @param posBeforeBlock The position just before the block's outer node.
*/
-export function getBlockInfoFromResolvedPos(resolvedPos: ResolvedPos) {
- if (!resolvedPos.nodeAfter) {
+export function getBlockInfoAt(doc: Node, posBeforeBlock: number): BlockInfo {
+ const $pos = doc.resolve(posBeforeBlock);
+ if (!$pos.nodeAfter) {
throw new Error(
- `Attempted to get blockContainer node at position ${resolvedPos.pos} but a node at this position does not exist`,
+ `Attempted to get block node at position ${posBeforeBlock} but a node at this position does not exist`,
);
}
- return getBlockInfoWithManualOffset(resolvedPos.nodeAfter, resolvedPos.pos);
+ return getBlockInfoFromNode($pos.nodeAfter, $pos.pos);
}
/**
- * Gets information regarding the ProseMirror nodes that make up a block. The
- * block chosen is the one currently containing the current ProseMirror
- * selection.
- * @param source The ProseMirror editor state.
+ * Gets information regarding the ProseMirror nodes that make up the block
+ * nearest to an arbitrary position (see {@link getNearestBlockPos}).
+ * @param source The ProseMirror editor state or transaction.
+ * @param pos An integer position in the document.
+ */
+export function getBlockInfoNearPos(
+ source: EditorState | Transaction,
+ pos: number,
+): BlockInfo {
+ const posInfo = getNearestBlockPos(source.doc, pos);
+ return getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+}
+
+/**
+ * Gets information regarding the ProseMirror nodes that make up the block
+ * containing the current ProseMirror selection anchor.
+ * @param source The ProseMirror editor state or transaction.
*/
export function getBlockInfoFromSelection(source: EditorState | Transaction) {
- return getBlockInfoAtNearest(source, source.selection.anchor);
+ return getBlockInfoNearPos(source, source.selection.anchor);
}
-export function getBlockInfoAtNearest(
- source: EditorState | Transaction,
- pos: number,
-) {
- return getBlockInfo(getNearestBlockPos(source.doc, pos));
+/**
+ * The parent block's info: the block whose `children` contains the block at
+ * `posBeforeBlock`, or `undefined` for a top-level block. A container is the
+ * parent of its direct children (a block inside a column → the column, not
+ * the columnList); a regular block's children live in its `blockGroup`, so
+ * the parent is the group's own parent.
+ */
+export function getParentBlockInfo(
+ doc: Node,
+ posBeforeBlock: number,
+): BlockInfo | undefined {
+ const $pos = doc.resolve(posBeforeBlock);
+ const parent = $pos.node();
+
+ if (parent.type.isInGroup("bnBlock")) {
+ return getBlockInfoAt(doc, $pos.before($pos.depth));
+ }
+ // A `blockGroup`: its own parent block is the real parent, unless it's the
+ // document root group.
+ if (parent.type.isInGroup(CHILD_CONTAINER_GROUP) && $pos.depth > 1) {
+ return getBlockInfoAt(doc, $pos.before($pos.depth - 1));
+ }
+ return undefined;
+}
+
+/**
+ * Returns the block info from the sibling block before (above) the given block,
+ * or undefined if the given block is the first sibling.
+ */
+export function getPrevBlockInfo(
+ doc: Node,
+ beforePos: number,
+): BlockInfo | undefined {
+ const $pos = doc.resolve(beforePos);
+
+ const indexInParent = $pos.index();
+
+ if (indexInParent === 0) {
+ return undefined;
+ }
+
+ const prevBlockBeforePos = $pos.posAtIndex(indexInParent - 1);
+
+ return getBlockInfoAt(doc, prevBlockBeforePos);
+}
+
+/**
+ * Returns the block info from the sibling block after (below) the given block,
+ * or undefined if the given block is the last sibling.
+ */
+export function getNextBlockInfo(
+ doc: Node,
+ beforePos: number,
+): BlockInfo | undefined {
+ const $pos = doc.resolve(beforePos);
+
+ const indexInParent = $pos.index();
+
+ if (indexInParent === $pos.node().childCount - 1) {
+ return undefined;
+ }
+
+ const nextBlockBeforePos = $pos.posAtIndex(indexInParent + 1);
+
+ return getBlockInfoAt(doc, nextBlockBeforePos);
+}
+
+/**
+ * If a block has children like this:
+ * A
+ * - B
+ * - C
+ * -- D
+ *
+ * Then the last descendant block returned is D.
+ *
+ * The descent stops at a sealed container, returning the container itself
+ * rather than a block inside it. Every caller is a keyboard gesture, and
+ * seals bind gestures.
+ */
+export function getLastDescendantBlockInfo(
+ doc: Node,
+ blockInfo: BlockInfo,
+): BlockInfo {
+ // A container that allows zero children can have an empty child container,
+ // in which case the block itself is the bottom one.
+ while (blockInfo.children && blockInfo.children.node.childCount) {
+ if (isSealed(blockInfo.children.node)) {
+ break;
+ }
+ const group = blockInfo.children.node;
+
+ const newPos = doc
+ .resolve(blockInfo.children.beforePos + 1)
+ .posAtIndex(group.childCount - 1);
+ blockInfo = getBlockInfoAt(doc, newPos);
+ }
+
+ return blockInfo;
}
diff --git a/packages/core/src/api/getBlocksChangedByTransaction.test.ts b/packages/core/src/api/getBlocksChangedByTransaction.test.ts
index 828894cf1d..b2853b9181 100644
--- a/packages/core/src/api/getBlocksChangedByTransaction.test.ts
+++ b/packages/core/src/api/getBlocksChangedByTransaction.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, beforeEach } from "vite-plus/test";
import { setupTestEnv } from "./blockManipulation/setupTestEnv.js";
import { getBlocksChangedByTransaction } from "./getBlocksChangedByTransaction.js";
-import { getBlockInfo } from "./getBlockInfoFromPos.js";
+import { getBlockInfoFromNode } from "./getBlockInfoFromPos.js";
import { getNodeById } from "./nodeUtil.js";
import { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
import { PartialBlock } from "../blocks/defaultBlocks.js";
@@ -651,15 +651,15 @@ describe("getBlocksChangedByTransaction - ranged optimization", () => {
if (!posInfo) {
throw new Error("block not found");
}
- const info = getBlockInfo(posInfo);
- if (!info.isBlockContainer) {
- throw new Error("expected a block container");
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+ if (!info.hasContent) {
+ throw new Error("expected a wrapped block");
}
// Adding a mark produces an AddMarkStep, whose StepMap is empty — the case
// getChangedRange has to recover from the step's own from/to.
tr.addMark(
- info.blockContent.beforePos + 1,
- info.blockContent.afterPos - 1,
+ info.content.beforePos + 1,
+ info.content.afterPos - 1,
editor.pmSchema.marks.bold.create(),
);
return getBlocksChangedByTransaction(tr);
diff --git a/packages/core/src/api/nodeConversions/blockToNode.ts b/packages/core/src/api/nodeConversions/blockToNode.ts
index af5c0ba1b7..77d5585d4c 100644
--- a/packages/core/src/api/nodeConversions/blockToNode.ts
+++ b/packages/core/src/api/nodeConversions/blockToNode.ts
@@ -16,10 +16,22 @@ import {
isPartialLinkInlineContent,
isStyledTextInlineContent,
} from "../../schema/inlineContent/types.js";
+// `isContainerNode` comes from `children.js` directly (rather than via its
+// `fixContainer.js` re-export) because `fixContainer.js` imports `blockToNode`
+// below; going through it would create an import cycle.
+import {
+ createBlockGroup,
+ isContainerNode,
+ resolveChildren,
+} from "../../schema/blocks/children.js";
import { getColspan, isPartialTableCell } from "../../util/table.js";
import { UnreachableCaseError } from "../../util/typescript.js";
import { getAbsoluteTableCells } from "../blockManipulation/tables/tables.js";
-import { getStyleSchema, isPlainContentNodeType } from "../pmUtil.js";
+import {
+ getBlockSchema,
+ getStyleSchema,
+ isPlainContentNodeType,
+} from "../pmUtil.js";
/**
* Convert a StyledText inline element to a
@@ -288,13 +300,17 @@ export function tableContentToNodes<
return rowNodes;
}
+/**
+ * Converts a block's (or custom inline content element's) `content` field to a
+ * `blockContent` (or custom inline content) prosemirror node.
+ */
function blockOrInlineContentToContentNode(
block:
| PartialBlock
| PartialCustomInlineContentFromConfig,
schema: Schema,
styleSchema: StyleSchema,
-) {
+): Node {
let contentNode: Node;
let type = block.type;
@@ -334,6 +350,32 @@ function blockOrInlineContentToContentNode(
return contentNode;
}
+const EMPTY_SEEDING: ReadonlySet = new Set();
+
+function unwrapsWhenEmptied(blockType: string, schema: Schema): boolean {
+ const children = getBlockSchema(schema)[blockType]?.children;
+ return !!children && resolveChildren(children).whenEmptied === "unwrap";
+}
+
+// `createAndFill` fills with schema defaults, which leaves `id: null`. Always
+// rebuilds: the only inputs are freshly created nodes, so there is no shared
+// structure worth preserving.
+function withGeneratedIds(node: Node): Node {
+ if (node.isText) {
+ return node;
+ }
+
+ const children: Node[] = [];
+ node.forEach((child) => children.push(withGeneratedIds(child)));
+
+ const needsId = node.type.isInGroup("bnBlock") && node.attrs.id === null;
+ return node.type.create(
+ needsId ? { ...node.attrs, id: UniqueID.options.generateID() } : node.attrs,
+ Fragment.from(children),
+ node.marks,
+ );
+}
+
/**
* Converts a BlockNote block to a Prosemirror node.
*/
@@ -341,6 +383,7 @@ export function blockToNode(
block: PartialBlock,
schema: Schema,
styleSchema: StyleSchema = getStyleSchema(schema),
+ seedingTypes: ReadonlySet = EMPTY_SEEDING,
) {
let id = block.id;
@@ -352,7 +395,7 @@ export function blockToNode(
if (block.children) {
for (const child of block.children) {
- children.push(blockToNode(child, schema, styleSchema));
+ children.push(blockToNode(child, schema, styleSchema, seedingTypes));
}
}
@@ -361,8 +404,6 @@ export function blockToNode(
schema.nodes[block.type].isInGroup("blockContent");
if (isBlockContent) {
- // Blocks with a type that matches "blockContent" group always need to be wrapped in a blockContainer
-
const contentNode = blockOrInlineContentToContentNode(
block,
schema,
@@ -370,9 +411,7 @@ export function blockToNode(
);
const groupNode =
- children.length > 0
- ? schema.nodes["blockGroup"].createChecked({}, children)
- : undefined;
+ children.length > 0 ? createBlockGroup(schema, children) : undefined;
return schema.nodes["blockContainer"].createChecked(
{
@@ -381,16 +420,64 @@ export function blockToNode(
},
groupNode ? [contentNode, groupNode] : contentNode,
);
- } else if (schema.nodes[block.type].isInGroup("bnBlock")) {
- // `create` (not `createChecked`) so partial container blocks pass through;
- // callers that mutate the doc validate via `node.check()` before inserting.
- return schema.nodes[block.type].create(
- {
- id: id,
- ...block.props,
- },
- children,
- );
+ } else if (isContainerNode(schema.nodes[block.type])) {
+ const type = schema.nodes[block.type];
+ const attrs = { id: id, ...block.props };
+
+ // Explicit children are padded up to the container's `min` so that even a
+ // `children: []` satisfies the content expression, and so survives the
+ // `node.check()` callers run before touching the doc. The exception is a
+ // non-empty child list on a container that unwraps as it empties: padding
+ // it would invent content the next repair pass deletes anyway, so it is
+ // passed through as given and `node.check()` reports the shortfall.
+ if (block.children !== undefined) {
+ const padded =
+ children.length === 0 || !unwrapsWhenEmptied(block.type, schema)
+ ? type.createAndFill(attrs, children)
+ : null;
+
+ return withGeneratedIds(padded ?? type.create(attrs, children));
+ }
+
+ // No explicit `children`: seed the container from its `children` config's
+ // `default`, converting each default child exactly like an inserted block.
+ // `seedingTypes` tracks the container types currently being seeded so a
+ // cyclic `default` (a container whose default children seed it again)
+ // fails loudly instead of recursing forever.
+ const childrenConfig = getBlockSchema(schema)[block.type]?.children;
+ const defaultChildren = childrenConfig
+ ? resolveChildren(childrenConfig).default
+ : undefined;
+
+ let seeded: Node[] | undefined;
+ if (defaultChildren && defaultChildren.length > 0) {
+ if (seedingTypes.has(block.type)) {
+ throw new Error(
+ `Seeding "${block.type}" ends up seeding it again (${[...seedingTypes, block.type].join(" -> ")}). ` +
+ "Give the cyclic default explicit children, or remove the self-reference.",
+ );
+ }
+
+ const nextSeeding = new Set(seedingTypes).add(block.type);
+ seeded = defaultChildren.map((child) =>
+ blockToNode(
+ child as PartialBlock,
+ schema,
+ styleSchema,
+ nextSeeding,
+ ),
+ );
+ }
+
+ const node = type.createAndFill(attrs, seeded);
+ if (!node) {
+ throw new Error(
+ `Cannot create block "${block.type}": its \`default\` children don't fit its \`children\` config ` +
+ `(it accepts \`${type.spec.content}\`).`,
+ );
+ }
+
+ return withGeneratedIds(node);
} else {
throw new Error(
`block type ${block.type} doesn't match blockContent or bnBlock group`,
diff --git a/packages/core/src/api/nodeConversions/fragmentToBlocks.ts b/packages/core/src/api/nodeConversions/fragmentToBlocks.ts
index 19f063d8bb..5b67cdb3bc 100644
--- a/packages/core/src/api/nodeConversions/fragmentToBlocks.ts
+++ b/packages/core/src/api/nodeConversions/fragmentToBlocks.ts
@@ -1,60 +1,56 @@
-import { Fragment } from "@tiptap/pm/model";
+import { Fragment, Node } from "@tiptap/pm/model";
import {
BlockNoDefaults,
BlockSchema,
InlineContentSchema,
StyleSchema,
} from "../../schema/index.js";
+import {
+ isContainerNode,
+ resolveChildren,
+} from "../../schema/blocks/children.js";
+import { getBlockSchema } from "../pmUtil.js";
import { nodeToBlock } from "./nodeToBlock.js";
-/**
- * Converts all Blocks within a fragment to BlockNote blocks.
- */
+function isSelfContainedContainer(node: Node): boolean {
+ if (!isContainerNode(node.type)) {
+ return false;
+ }
+ const blockConfig = getBlockSchema(node.type.schema)[node.type.name];
+ const childrenConfig = blockConfig?.children;
+ if (!blockConfig || !childrenConfig) {
+ return false;
+ }
+ return (
+ blockConfig.placement !== "containerOnly" &&
+ node.childCount >= resolveChildren(childrenConfig).min
+ );
+}
+
export function fragmentToBlocks<
B extends BlockSchema,
I extends InlineContentSchema,
S extends StyleSchema,
>(fragment: Fragment) {
- // first convert selection to blocknote-style blocks, and then
- // pass these to the exporter
const blocks: BlockNoDefaults[] = [];
+
+ const pushFlattened = (node: Node, root: Node) => {
+ if (isContainerNode(node.type) && !isSelfContainedContainer(node)) {
+ node.forEach((child) => pushFlattened(child, root));
+ return;
+ }
+ blocks.push(nodeToBlock(node, root));
+ };
+
fragment.descendants((node) => {
if (node.type.name === "blockContainer") {
if (node.firstChild?.type.name === "blockGroup") {
- // selection started within a block group
- // in this case the fragment starts with:
- //
- //
- //
- //
- //
- //
- //
- // instead of:
- //
- //
- //
- //
- //
- //
- //
- //
- // so we don't need to serialize this block, just descend into the children of the blockGroup
return true;
}
}
- if (node.type.name === "columnList" && node.childCount === 1) {
- // column lists with a single column should be flattened (not the entire column list has been selected)
- node.firstChild?.forEach((child) => {
- blocks.push(nodeToBlock(child, node));
- });
- return false;
- }
-
if (node.type.isInGroup("bnBlock")) {
- blocks.push(nodeToBlock(node, node));
- // don't descend into children, as they're already included in the block returned by nodeToBlock
+ pushFlattened(node, node);
return false;
}
return true;
diff --git a/packages/core/src/api/nodeConversions/nodeToBlock.ts b/packages/core/src/api/nodeConversions/nodeToBlock.ts
index fead006657..43b5b0780e 100644
--- a/packages/core/src/api/nodeConversions/nodeToBlock.ts
+++ b/packages/core/src/api/nodeConversions/nodeToBlock.ts
@@ -1,5 +1,6 @@
import { Mark, Node, Slice } from "@tiptap/pm/model";
import type { Block } from "../../blocks/defaultBlocks.js";
+import { isContainerNode } from "../../schema/blocks/children.js";
import UniqueID from "../../extensions/tiptap-extensions/UniqueID/UniqueID.js";
import type {
BlockSchema,
@@ -18,10 +19,8 @@ import {
isStyledTextInlineContent,
} from "../../schema/inlineContent/types.js";
import { UnreachableCaseError } from "../../util/typescript.js";
-import {
- getBlockInfoWithManualOffset,
- getNodeId,
-} from "../getBlockInfoFromPos.js";
+import { getBlockInfoFromNode, getNodeId } from "../getBlockInfoFromPos.js";
+import type { BlockInfo } from "../getBlockInfoFromPos.js";
import {
getBlockCache,
getBlockSchema,
@@ -388,6 +387,17 @@ export function nodeToCustomInlineContent<
return ic;
}
+// A config declaring content and a node shaped to hold it state the same
+// fact, but nothing ties them together in the type system.
+function contentNode(blockInfo: BlockInfo, declared: string): Node {
+ if (!blockInfo.hasContent) {
+ throw new Error(
+ `Block "${blockInfo.blockNoteType}" declares ${declared} content but holds children.`,
+ );
+ }
+ return blockInfo.content.node;
+}
+
/**
* Convert a Prosemirror node to a BlockNote block.
*/
@@ -402,7 +412,7 @@ export function nodeToBlock<
const styleSchema = getStyleSchema(schema) as S;
const blockCache = getBlockCache(schema);
if (!node.type.isInGroup("bnBlock")) {
- throw Error("Node should be a bnBlock, but is instead: " + node.type.name);
+ throw Error("Node should be a block, but is instead: " + node.type.name);
}
const cachedBlock = blockCache?.get(node);
@@ -411,28 +421,28 @@ export function nodeToBlock<
return cachedBlock;
}
- const blockInfo = getBlockInfoWithManualOffset(node, 0);
+ const blockInfo = getBlockInfoFromNode(node, 0);
let id: string;
try {
- id = getNodeId(blockInfo.bnBlock.node, doc);
+ id = getNodeId(blockInfo.block.node, doc);
} catch {
// Only used for blocks converted from other formats.
id = UniqueID.options.generateID();
}
- const blockSpec = blockSchema[blockInfo.blockNoteType];
+ const blockConfig = blockSchema[blockInfo.blockNoteType];
- if (!blockSpec) {
+ if (!blockConfig) {
throw Error("Block is of an unrecognized type: " + blockInfo.blockNoteType);
}
const props: any = {};
for (const [attr, value] of Object.entries({
...node.attrs,
- ...(blockInfo.isBlockContainer ? blockInfo.blockContent.node.attrs : {}),
+ ...(blockInfo.hasContent ? blockInfo.content.node.attrs : {}),
})) {
- const propSchema = blockSpec.propSchema;
+ const propSchema = blockConfig.propSchema;
if (
attr in propSchema &&
@@ -442,40 +452,29 @@ export function nodeToBlock<
}
}
- const blockConfig = blockSchema[blockInfo.blockNoteType];
-
const children: Block[] = [];
- blockInfo.childContainer?.node.forEach((child) => {
+ blockInfo.children?.node.forEach((child) => {
children.push(nodeToBlock(child, doc));
});
let content: Block["content"];
if (blockConfig.content === "inline") {
- if (!blockInfo.isBlockContainer) {
- throw new Error("impossible");
- }
content = contentNodeToInlineContent(
- blockInfo.blockContent.node,
+ contentNode(blockInfo, blockConfig.content),
inlineContentSchema,
styleSchema,
);
} else if (blockConfig.content === "table") {
- if (!blockInfo.isBlockContainer) {
- throw new Error("impossible");
- }
content = contentNodeToTableContent(
- blockInfo.blockContent.node,
+ contentNode(blockInfo, blockConfig.content),
inlineContentSchema,
styleSchema,
);
} else if (blockConfig.content === "plain") {
- if (!blockInfo.isBlockContainer) {
- throw new Error("impossible");
- }
// Plain content is a single unstyled text item; an empty block is an
// empty array, matching inline content.
- const text = blockInfo.blockContent.node.textContent;
+ const text = contentNode(blockInfo, blockConfig.content).textContent;
content = text.length > 0 ? [{ type: "text", text, styles: {} }] : [];
} else if (blockConfig.content === "none") {
content = undefined;
@@ -563,14 +562,65 @@ export function prosemirrorSliceToSlicedBlocks<
blockCutAtStart: string | undefined;
blockCutAtEnd: string | undefined;
} {
- if (node.type.name !== "blockGroup") {
+ // Both `blockGroup` and container nodes (columnList, column, callout,
+ // ...) hold block children directly, so both can be processed here.
+ if (node.type.name !== "blockGroup" && !isContainerNode(node.type)) {
throw new Error("unexpected");
}
const blocks: Block[] = [];
let blockCutAtStart: string | undefined;
let blockCutAtEnd: string | undefined;
+ // Descends into a child-holding node the slice boundary is open inside
+ // of: the holder wrapper is skipped and the included children are spliced
+ // in, propagating cut ids from whichever ends are open. Shared by open
+ // container children and the degenerate `blockContainer`-around-
+ // `blockGroup` wrapper — regular nesting's version of the same shape.
+ function descendOpenHolder(
+ holder: Node,
+ openAtStart: boolean,
+ openAtEnd: boolean,
+ ) {
+ const ret = processNode(
+ holder,
+ openAtStart ? Math.max(0, openStart - 1) : 0,
+ openAtEnd ? Math.max(0, openEnd - 1) : 0,
+ );
+ if (openAtStart) {
+ blockCutAtStart = ret.blockCutAtStart;
+ }
+ if (openAtEnd) {
+ blockCutAtEnd = ret.blockCutAtEnd;
+ }
+ blocks.push(...ret.blocks);
+ }
+
node.forEach((blockContainer, _offset, index) => {
+ const isFirstBlock = index === 0;
+ const isLastBlock = index === node.childCount - 1;
+
+ if (isContainerNode(blockContainer.type)) {
+ // A container child. When the slice boundary is open inside it, the
+ // selection covers part of its children; when fully enclosed, convert
+ // it wholesale.
+ const openAtStart = isFirstBlock && openStart > 0;
+ const openAtEnd = isLastBlock && openEnd > 0;
+
+ if (openAtStart || openAtEnd) {
+ descendOpenHolder(blockContainer, openAtStart, openAtEnd);
+ return;
+ }
+
+ blocks.push(
+ nodeToBlock(blockContainer, slice.content.firstChild!) as Block<
+ BSchema,
+ I,
+ S
+ >,
+ );
+ return;
+ }
+
if (blockContainer.type.name !== "blockContainer") {
throw new Error("unexpected");
}
@@ -583,9 +633,6 @@ export function prosemirrorSliceToSlicedBlocks<
);
}
- const isFirstBlock = index === 0;
- const isLastBlock = index === node.childCount - 1;
-
if (blockContainer.firstChild!.type.name === "blockGroup") {
// this is the parent where a selection starts within one of its children,
// e.g.:
@@ -596,16 +643,11 @@ export function prosemirrorSliceToSlicedBlocks<
if (!isFirstBlock) {
throw new Error("unexpected");
}
- const ret = processNode(
- blockContainer.firstChild!,
- Math.max(0, openStart - 1),
- isLastBlock ? Math.max(0, openEnd - 1) : 0,
- );
- blockCutAtStart = ret.blockCutAtStart;
- if (isLastBlock) {
- blockCutAtEnd = ret.blockCutAtEnd;
- }
- blocks.push(...ret.blocks);
+ // Open at the start by construction (a `blockContainer` can only lead
+ // with its `blockGroup` when the slice cut its content node away);
+ // open at the end whenever it is also the last block, matching the
+ // pre-refactor cut propagation.
+ descendOpenHolder(blockContainer.firstChild!, true, isLastBlock);
return;
}
diff --git a/packages/core/src/api/nodeUtil.ts b/packages/core/src/api/nodeUtil.ts
index 9214a9ad42..efb41ba1c2 100644
--- a/packages/core/src/api/nodeUtil.ts
+++ b/packages/core/src/api/nodeUtil.ts
@@ -18,7 +18,7 @@ export function getNodeById(
}
// Keeps traversing nodes if block with target ID has not been found. Some
- // bnBlock nodes we merely pass over (e.g. `column`/`columnList`) may not
+ // block nodes we merely pass over (e.g. `column`/`columnList`) may not
// carry an id — skip them without calling the throwing `getNodeId`, which
// errors on id-less nodes. Only nodes that actually have an id are compared.
if (!isNodeBlock(node) || !node.attrs.id || getNodeId(node, doc) !== id) {
diff --git a/packages/core/src/api/pmUtil.ts b/packages/core/src/api/pmUtil.ts
index 17ed2aa943..51317b699d 100644
--- a/packages/core/src/api/pmUtil.ts
+++ b/packages/core/src/api/pmUtil.ts
@@ -67,7 +67,9 @@ export function isPlainContentNodeType(
schema: Schema,
nodeType: NodeType,
): boolean {
- if (getBlockSchema(schema)[nodeType.name]?.content === "plain") {
+ const blockSchema = getBlockSchema(schema);
+
+ if (blockSchema[nodeType.name]?.content === "plain") {
return true;
}
diff --git a/packages/core/src/blocks/ListItem/ListItemKeyboardShortcuts.ts b/packages/core/src/blocks/ListItem/ListItemKeyboardShortcuts.ts
index 0b33335788..218618ca1f 100644
--- a/packages/core/src/blocks/ListItem/ListItemKeyboardShortcuts.ts
+++ b/packages/core/src/blocks/ListItem/ListItemKeyboardShortcuts.ts
@@ -11,17 +11,17 @@ export const handleEnter = (editor: BlockNoteEditor) => {
};
});
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { bnBlock: blockContainer, blockContent } = blockInfo;
+ const { block: blockContainer, content } = blockInfo;
if (
!(
- blockContent.node.type.name === "toggleListItem" ||
- blockContent.node.type.name === "bulletListItem" ||
- blockContent.node.type.name === "numberedListItem" ||
- blockContent.node.type.name === "checkListItem"
+ content.node.type.name === "toggleListItem" ||
+ content.node.type.name === "bulletListItem" ||
+ content.node.type.name === "numberedListItem" ||
+ content.node.type.name === "checkListItem"
) ||
!selectionEmpty
) {
@@ -32,7 +32,7 @@ export const handleEnter = (editor: BlockNoteEditor) => {
() =>
// Changes list item block to a paragraph block if the content is empty.
commands.command(() => {
- if (blockContent.node.childCount === 0) {
+ if (blockInfo.isContentEmpty) {
return commands.command(
updateBlockCommand(blockContainer.beforePos, {
type: "paragraph",
@@ -48,7 +48,7 @@ export const handleEnter = (editor: BlockNoteEditor) => {
// Splits the current block, moving content inside that's after the cursor
// to a new block of the same type below.
commands.command(() => {
- if (blockContent.node.childCount > 0) {
+ if (content.node.childCount > 0) {
chain()
.deleteSelection()
.command(splitBlockCommand(state.selection.from, true))
diff --git a/packages/core/src/blocks/ListItem/NumberedListItem/IndexingPlugin.ts b/packages/core/src/blocks/ListItem/NumberedListItem/IndexingPlugin.ts
index b268598218..0222fff46a 100644
--- a/packages/core/src/blocks/ListItem/NumberedListItem/IndexingPlugin.ts
+++ b/packages/core/src/blocks/ListItem/NumberedListItem/IndexingPlugin.ts
@@ -3,7 +3,7 @@ import type { Transaction } from "@tiptap/pm/state";
import { Plugin, PluginKey } from "@tiptap/pm/state";
import { Decoration, DecorationSet } from "@tiptap/pm/view";
-import { getBlockInfo } from "../../../api/getBlockInfoFromPos.js";
+import { getBlockInfoFromNode } from "../../../api/getBlockInfoFromPos.js";
// Loosely based on https://github.com/ueberdosis/tiptap/blob/7ac01ef0b816a535e903b5ca92492bff110a71ae/packages/extension-mathematics/src/MathematicsPlugin.ts (MIT)
@@ -31,11 +31,11 @@ function calculateListItemIndex(
const hasStart = !!node.firstChild!.attrs["start"];
// Fast path: previous sibling already in cache
- const blockInfo = getBlockInfo({ posBeforeNode: pos, node });
- if (!blockInfo.isBlockContainer) {
+ const blockInfo = getBlockInfoFromNode(node, pos);
+ if (!blockInfo.hasContent) {
throw new Error("impossible");
}
- const prevBlock = tr.doc.resolve(blockInfo.bnBlock.beforePos).nodeBefore;
+ const prevBlock = tr.doc.resolve(blockInfo.block.beforePos).nodeBefore;
const prevBlockIndex = prevBlock ? map.get(prevBlock) : undefined;
if (prevBlockIndex !== undefined) {
const index = prevBlockIndex + 1;
@@ -48,7 +48,7 @@ function calculateListItemIndex(
// or the start of the parent.
const chain: { node: Node; pos: number }[] = [{ node, pos }];
let curNode = prevBlock;
- let curBeforePos = blockInfo.bnBlock.beforePos;
+ let curBeforePos = blockInfo.block.beforePos;
while (curNode) {
const cachedIndex = map.get(curNode);
@@ -56,16 +56,16 @@ function calculateListItemIndex(
// Found a cached predecessor — start counting from here
break;
}
- const curInfo = getBlockInfo({
- posBeforeNode: curBeforePos - curNode.nodeSize,
- node: curNode,
- });
+ const curInfo = getBlockInfoFromNode(
+ curNode,
+ curBeforePos - curNode.nodeSize,
+ );
if (curInfo.blockNoteType !== "numberedListItem") {
break;
}
chain.push({ node: curNode, pos: curBeforePos - curNode.nodeSize });
- const nextPrev = tr.doc.resolve(curInfo.bnBlock.beforePos).nodeBefore;
- curBeforePos = curInfo.bnBlock.beforePos;
+ const nextPrev = tr.doc.resolve(curInfo.block.beforePos).nodeBefore;
+ curBeforePos = curInfo.block.beforePos;
curNode = nextPrev;
}
@@ -76,14 +76,11 @@ function calculateListItemIndex(
// Determine starting index from the block just before the chain
const lastInChain = chain[chain.length - 1];
- const lastInfo = getBlockInfo({
- posBeforeNode: lastInChain.pos,
- node: lastInChain.node,
- });
- if (!lastInfo.isBlockContainer) {
+ const lastInfo = getBlockInfoFromNode(lastInChain.node, lastInChain.pos);
+ if (!lastInfo.hasContent) {
throw new Error("impossible");
}
- const predecessorNode = tr.doc.resolve(lastInfo.bnBlock.beforePos).nodeBefore;
+ const predecessorNode = tr.doc.resolve(lastInfo.block.beforePos).nodeBefore;
const predecessorIndex = predecessorNode
? map.get(predecessorNode)
: undefined;
diff --git a/packages/core/src/blocks/utils/listItemEnterHandler.ts b/packages/core/src/blocks/utils/listItemEnterHandler.ts
index 12e558a453..6008c1a023 100644
--- a/packages/core/src/blocks/utils/listItemEnterHandler.ts
+++ b/packages/core/src/blocks/utils/listItemEnterHandler.ts
@@ -14,16 +14,16 @@ export const handleEnter = (
};
});
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { bnBlock: blockContainer, blockContent } = blockInfo;
+ const { block: blockContainer, content } = blockInfo;
- if (!(blockContent.node.type.name === listItemType) || !selectionEmpty) {
+ if (!(content.node.type.name === listItemType) || !selectionEmpty) {
return false;
}
- if (blockContent.node.childCount === 0) {
+ if (blockInfo.isContentEmpty) {
editor.transact((tr) => {
updateBlockTr(tr, blockContainer.beforePos, {
type: "paragraph",
@@ -31,7 +31,7 @@ export const handleEnter = (
});
});
return true;
- } else if (blockContent.node.childCount > 0) {
+ } else if (content.node.childCount > 0) {
return editor.transact((tr) => {
tr.deleteSelection();
tr.scrollIntoView();
diff --git a/packages/core/src/editor/BlockNoteEditor.test.ts b/packages/core/src/editor/BlockNoteEditor.test.ts
index bf4253711e..680a663b98 100644
--- a/packages/core/src/editor/BlockNoteEditor.test.ts
+++ b/packages/core/src/editor/BlockNoteEditor.test.ts
@@ -2,7 +2,7 @@ import { afterEach, expect, it } from "vite-plus/test";
import * as Y from "yjs";
import {
- getBlockInfo,
+ getBlockInfoFromNode,
getNearestBlockPos,
} from "../api/getBlockInfoFromPos.js";
import { BlockNoteEditor } from "./BlockNoteEditor.js";
@@ -26,7 +26,7 @@ it("creates an editor", () => {
const editor = BlockNoteEditor.create();
editorsToCleanup.push(editor);
const posInfo = editor.transact((tr) => getNearestBlockPos(tr.doc, 2));
- const info = getBlockInfo(posInfo);
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
expect(info.blockNoteType).toEqual("paragraph");
});
diff --git a/packages/core/src/editor/BlockNoteEditor.ts b/packages/core/src/editor/BlockNoteEditor.ts
index 25b93d03f4..d685993714 100644
--- a/packages/core/src/editor/BlockNoteEditor.ts
+++ b/packages/core/src/editor/BlockNoteEditor.ts
@@ -7,6 +7,7 @@ import {
} from "@tiptap/core";
import { type Command, type Transaction } from "@tiptap/pm/state";
import { Node, Schema } from "prosemirror-model";
+import type { BlockPlacement } from "../api/blockManipulation/commands/insertBlocks/insertBlocks.js";
import type { BlocksChanged } from "../api/getBlocksChangedByTransaction.js";
import { blockToNode } from "../api/nodeConversions/blockToNode.js";
import {
@@ -558,6 +559,13 @@ export class BlockNoteEditor<
tiptapOptions.parseOptions,
);
+ // `blockToNode` is lenient, and `createDocument` builds from JSON
+ // without validating, so without this check the initial document is
+ // never validated. A container below its `children.min` would reach
+ // the editor and stay there, while the same blocks passed to
+ // `insertBlocks` would have been rejected.
+ doc.check();
+
this._tiptapEditor = new TiptapEditor({
...tiptapOptions,
content: doc.toJSON(),
@@ -1051,13 +1059,14 @@ export class BlockNoteEditor<
* error if the reference block could not be found.
* @param blocksToInsert An array of partial blocks that should be inserted.
* @param referenceBlock An identifier for an existing block, at which the new blocks should be inserted.
- * @param placement Whether the blocks should be inserted just before, just after, or nested inside the
- * `referenceBlock`.
+ * @param placement Where the blocks go relative to the `referenceBlock`: as its previous (`"before"`) or next
+ * (`"after"`) sibling, or nested inside it as its first (`"first-child"`) or last (`"last-child"`) children. Throws
+ * an error if the `referenceBlock` (or its parent, for `"before"`/`"after"`) doesn't accept the blocks there.
*/
public insertBlocks(
blocksToInsert: PartialBlock[],
referenceBlock: BlockIdentifier,
- placement: "before" | "after" = "before",
+ placement: BlockPlacement = "before",
) {
return this._blockManager.insertBlocks(
blocksToInsert,
diff --git a/packages/core/src/editor/managers/BlockManager.ts b/packages/core/src/editor/managers/BlockManager.ts
index f086444ecc..ca4c62555e 100644
--- a/packages/core/src/editor/managers/BlockManager.ts
+++ b/packages/core/src/editor/managers/BlockManager.ts
@@ -1,4 +1,7 @@
-import { insertBlocks } from "../../api/blockManipulation/commands/insertBlocks/insertBlocks.js";
+import {
+ BlockPlacement,
+ insertBlocks,
+} from "../../api/blockManipulation/commands/insertBlocks/insertBlocks.js";
import {
moveBlocksDown,
moveBlocksUp,
@@ -150,13 +153,13 @@ export class BlockManager<
* error if the reference block could not be found.
* @param blocksToInsert An array of partial blocks that should be inserted.
* @param referenceBlock An identifier for an existing block, at which the new blocks should be inserted.
- * @param placement Whether the blocks should be inserted just before, just after, or nested inside the
- * `referenceBlock`.
+ * @param placement Where the blocks go relative to the `referenceBlock`: as its previous (`"before"`) or next
+ * (`"after"`) sibling, or nested inside it as its first (`"first-child"`) or last (`"last-child"`) children.
*/
public insertBlocks(
blocksToInsert: PartialBlock[],
referenceBlock: BlockIdentifier,
- placement: "before" | "after" = "before",
+ placement: BlockPlacement = "before",
) {
return this.editor.transact((tr) =>
insertBlocks(tr, blocksToInsert, referenceBlock, placement),
diff --git a/packages/core/src/editor/managers/ExtensionManager/extensions.ts b/packages/core/src/editor/managers/ExtensionManager/extensions.ts
index 853cca2493..3d2a3e5bda 100644
--- a/packages/core/src/editor/managers/ExtensionManager/extensions.ts
+++ b/packages/core/src/editor/managers/ExtensionManager/extensions.ts
@@ -62,7 +62,16 @@ export function getDefaultTiptapExtensions(
UniqueID.configure({
// everything from bnBlock group (nodes that represent a BlockNote block should have an id)
- types: ["blockContainer", "columnList", "column"],
+ types: [
+ "blockContainer",
+ // Container block specs whose PM node is itself in the `bnBlock`
+ // group (column, columnList, callout, etc.). The bnBlock node is the
+ // block itself, so the id lives on its attrs rather than on a
+ // wrapping blockContainer.
+ ...Object.entries(editor.schema.blockSpecs)
+ .filter(([, spec]) => (spec as any).config.children !== undefined)
+ .map(([type]) => type),
+ ],
setIdAttribute: options.setIdAttribute,
isWithinEditor: editor.isWithinEditor,
}),
diff --git a/packages/core/src/editor/managers/ExtensionManager/index.ts b/packages/core/src/editor/managers/ExtensionManager/index.ts
index 5cf6e74c1c..b8973e3394 100644
--- a/packages/core/src/editor/managers/ExtensionManager/index.ts
+++ b/packages/core/src/editor/managers/ExtensionManager/index.ts
@@ -563,7 +563,7 @@ export class ExtensionManager {
const blockInfo = getBlockInfoFromSelection(tr);
if (
- !blockInfo.isBlockContainer ||
+ !blockInfo.hasContent ||
this.editor.schema.blockSchema[blockInfo.blockNoteType]
?.content !== "inline"
) {
@@ -571,14 +571,14 @@ export class ExtensionManager {
}
tr.deleteRange(start, end);
- updateBlockTr(tr, blockInfo.bnBlock.beforePos, replaceWith);
+ updateBlockTr(tr, blockInfo.block.beforePos, replaceWith);
// updateBlockTr's replaceWith path leaves the selection after
// the new block when the content is replaced wholesale (e.g.
// when the rule returns content: []). Move the cursor back
// inside the new block so the user can keep typing.
setTextCursorPosition(
tr,
- getNodeId(blockInfo.bnBlock.node, tr.doc),
+ getNodeId(blockInfo.block.node, tr.doc),
"start",
);
return tr;
diff --git a/packages/core/src/editor/transformPasted.ts b/packages/core/src/editor/transformPasted.ts
index 4f0515df95..935e2b5bd2 100644
--- a/packages/core/src/editor/transformPasted.ts
+++ b/packages/core/src/editor/transformPasted.ts
@@ -66,7 +66,7 @@ function removeChild(node: Fragment, n: number) {
* Wrap adjacent tableRow items in a table.
*
* This makes sure the content that we paste is always a table (and not a tableRow)
- * A table works better for the remaing paste handling logic, as it's actually a blockContent node
+ * A table works better for the remaing paste handling logic, as it's actually a content node
*/
export function wrapTableRows(f: Fragment, schema: Schema) {
const newItems: any[] = [];
@@ -118,7 +118,11 @@ export function transformPasted(slice: Slice, view: EditorView) {
return retyped;
}
- if (isInTableCell(view)) {
+ // `tableParagraph` only exists in schemas with the default table blocks. A
+ // schema with a custom table implementation (e.g. container-block cells,
+ // which hold real blocks and need no inline conversion) skips this branch.
+ const tableParagraph = view.state.schema.nodes.tableParagraph;
+ if (tableParagraph && isInTableCell(view)) {
let hasTableContent = false;
f.descendants((node) => {
if (node.type.isInGroup("tableContent")) {
@@ -128,7 +132,7 @@ export function transformPasted(slice: Slice, view: EditorView) {
if (
!hasTableContent &&
// is the content valid for a table paragraph?
- !view.state.schema.nodes.tableParagraph.validContent(f)
+ !tableParagraph.validContent(f)
) {
// if not, convert the content to inline content
return new Slice(
@@ -213,17 +217,15 @@ function retypeLeadingParagraphForEmptyTarget(
}
const blockInfo = getBlockInfoFromSelection(view.state);
- const target = blockInfo.isBlockContainer
- ? blockInfo.blockContent.node
- : null;
if (
- !target ||
- target.type.name === "paragraph" ||
- target.type.spec.content !== "inline*" ||
- target.childCount > 0
+ !blockInfo.hasContent ||
+ blockInfo.content.node.type.name === "paragraph" ||
+ blockInfo.contentKind !== "inline" ||
+ !blockInfo.isContentEmpty
) {
return null;
}
+ const target = blockInfo.content.node;
const blockGroup = fragment.firstChild;
const blockContainer = blockGroup?.firstChild;
@@ -275,9 +277,8 @@ function shouldApplyFix(fragment: Fragment, view: EditorView) {
// for both paste and drop events. Drop events can potentially cause
// issues as they don't always happen at the current selection.
const blockInfo = getBlockInfoFromSelection(view.state);
- if (blockInfo.isBlockContainer) {
- const selectedBlockHasTableContent =
- blockInfo.blockContent.node.type.spec.content === "tableRow+";
+ if (blockInfo.hasContent) {
+ const selectedBlockHasTableContent = blockInfo.contentKind === "table";
// Case for when we paste a single node with table content, i.e. a
// table. Normally, we return true as we want to ensure the table is
diff --git a/packages/core/src/exporter/Exporter.test.ts b/packages/core/src/exporter/Exporter.test.ts
index 98e7b34f1c..729680d69b 100644
--- a/packages/core/src/exporter/Exporter.test.ts
+++ b/packages/core/src/exporter/Exporter.test.ts
@@ -184,3 +184,31 @@ describe("Exporter missing mappings", () => {
).toThrow('missing a style mapping for style "bold"');
});
});
+
+describe("Exporter block types outside its schema", () => {
+ it("treats a childless block of an unknown type as a regular block", () => {
+ // Block packages (math, diagram, ...) commonly supply only a mapping,
+ // which reads the block's JSON - their specs need not be in the schema.
+ expect(
+ new EmptyMappingsExporter().isContainerBlock({
+ type: "mathBlock",
+ children: [],
+ }),
+ ).toBe(false);
+ });
+
+ it("throws when a block of an unknown type has children", () => {
+ // Ambiguous: without the spec there is no way to tell whether the
+ // mapping places these children itself (container) or the exporter
+ // appends them (regular block), and guessing puts them in the wrong
+ // place silently.
+ expect(() =>
+ new EmptyMappingsExporter().isContainerBlock({
+ type: "columnList",
+ children: [{ type: "column" }],
+ }),
+ ).toThrow(
+ 'Exporter has no block spec for block type "columnList", and blocks of that type in this document have children',
+ );
+ });
+});
diff --git a/packages/core/src/exporter/Exporter.ts b/packages/core/src/exporter/Exporter.ts
index 6ca0efa222..26b1184cc3 100644
--- a/packages/core/src/exporter/Exporter.ts
+++ b/packages/core/src/exporter/Exporter.ts
@@ -60,15 +60,54 @@ export abstract class Exporter<
RS,
TS,
> {
+ // Stored with erased generics: a generically-typed property would change
+ // the class's variance in B/I/S and break mapping inference at subclass
+ // construction sites (the schema param was previously inference-only).
+ private readonly blockNoteSchema: BlockNoteSchema;
+
public constructor(
- _schema: BlockNoteSchema, // only used for type inference
+ schema: BlockNoteSchema,
protected readonly mappings: {
blockMapping: BlockMapping;
inlineContentMapping: InlineContentMapping;
styleMapping: StyleMapping;
},
public readonly options: ExporterOptions,
- ) {}
+ ) {
+ this.blockNoteSchema = schema;
+ }
+
+ /**
+ * Whether a block type is a container block (declares `children`, e.g.
+ * `columnList`, `column`, or a custom callout). Container mappings own the
+ * placement of their children, so exporters must not append the children
+ * after the container's own output.
+ *
+ * A block whose type isn't in the exporter's schema can only be answered
+ * for when it has no children - then there is nothing to place and the
+ * answer is "no" either way. (Block packages commonly supply a mapping
+ * without adding the spec: the mapping just reads the block's JSON.) A
+ * block that *does* have children is ambiguous, and guessing "not a
+ * container" silently exports them in the wrong place - after the block
+ * instead of wherever its mapping puts them - so that throws instead.
+ */
+ public isContainerBlock(block: {
+ type: string;
+ children?: unknown[];
+ }): boolean {
+ const spec = (this.blockNoteSchema.blockSpecs as Record)[
+ block.type
+ ];
+ if (!spec) {
+ if (block.children?.length) {
+ throw new Error(
+ `Exporter has no block spec for block type "${block.type}", and blocks of that type in this document have children. Without the spec the exporter cannot tell whether the type is a container block (whose mapping places its own children) or a regular one (whose children it appends itself), so it would place them by guesswork. Add the block's spec to the schema passed to the exporter, not just its mapping.`,
+ );
+ }
+ return false;
+ }
+ return spec.config.children !== undefined;
+ }
/**
* The strings this exporter renders into the produced document - the
@@ -147,7 +186,9 @@ export abstract class Exporter<
const mapping = this.mappings.blockMapping[block.type];
if (!mapping) {
throw new Error(
- `Exporter is missing a block mapping for block type "${block.type}". If this block comes from a separate package, spread that package's exporter mappings into your blockMapping.`,
+ this.isContainerBlock(block)
+ ? `No mapping found for container block type "${block.type}". Container blocks require an explicit block mapping that places their children.`
+ : `Exporter is missing a block mapping for block type "${block.type}". If this block comes from a separate package, spread that package's exporter mappings into your blockMapping.`,
);
}
return mapping(block, this, nestingLevel, numberedListIndex, children);
diff --git a/packages/core/src/extensions/SideMenu/SideMenu.ts b/packages/core/src/extensions/SideMenu/SideMenu.ts
index fddd2712e9..ede9633ff5 100644
--- a/packages/core/src/extensions/SideMenu/SideMenu.ts
+++ b/packages/core/src/extensions/SideMenu/SideMenu.ts
@@ -20,8 +20,17 @@ import {
InlineContentSchema,
StyleSchema,
} from "../../schema/index.js";
+import {
+ ContainerUIInfo,
+ getContainerUIInfo,
+} from "../../api/blockManipulation/containers/containerUI.js";
import { getDraggableBlockFromElement } from "../getDraggableBlockFromElement.js";
import { dragStart, unsetDragImage } from "./dragging.js";
+import {
+ getContainerChildAtCursor,
+ getDirectChildBlocks,
+ hasHorizontalContainerAncestor,
+} from "./sideMenuContainerGeometry.js";
export type SideMenuState<
BSchema extends BlockSchema,
@@ -37,7 +46,8 @@ const DISTANCE_TO_CONSIDER_EDITOR_BOUNDS = 250;
function getBlockFromCoords(
view: EditorView,
coords: { left: number; top: number },
- adjustForColumns = true,
+ containerUIInfo: ContainerUIInfo,
+ adjustForHorizontalContainers = true,
) {
const elements = view.root.elementsFromPoint(coords.left, coords.top);
@@ -46,21 +56,28 @@ function getBlockFromCoords(
// probably a ui overlay like formatting toolbar etc
continue;
}
- if (adjustForColumns) {
- const column = element.closest("[data-node-type=columnList]");
- if (column) {
- return getBlockFromCoords(
- view,
- {
- // TODO can we do better than this?
- left: coords.left + 50, // bit hacky, but if we're inside a column, offset x position to right to account for the width of sidemenu itself
- top: coords.top,
- },
- false,
- );
+ if (
+ adjustForHorizontalContainers &&
+ containerUIInfo.containerSelector &&
+ // Inside a container with side-by-side children (e.g. a columnList),
+ // the cursor is in the side menu's own gutter, so it lands on the
+ // container itself rather than on the block it lines up with. The
+ // horizontal container can be any ancestor (the element may sit inside
+ // a vertical child of it, like a block inside a column).
+ hasHorizontalContainerAncestor(element, containerUIInfo)
+ ) {
+ // Walk down through the containers by their children's measured rects
+ // instead, which finds that block without guessing an x offset.
+ const cursor = { x: coords.left, y: coords.top };
+ let target = element;
+ let child = getContainerChildAtCursor(target, cursor, containerUIInfo);
+ while (child) {
+ target = child;
+ child = getContainerChildAtCursor(target, cursor, containerUIInfo);
}
+ return getDraggableBlockFromElement(target, view, containerUIInfo);
}
- return getDraggableBlockFromElement(element, view);
+ return getDraggableBlockFromElement(element, view, containerUIInfo);
}
return undefined;
}
@@ -71,6 +88,7 @@ function getBlockFromMousePos(
y: number;
},
view: EditorView,
+ containerUIInfo: ContainerUIInfo,
): { node: HTMLElement; id: string } | undefined {
// Editor itself may have padding or other styling which affects
// size/position, so we get the boundingRect of the first child (i.e. the
@@ -94,7 +112,7 @@ function getBlockFromMousePos(
top: mousePos.y,
};
- const referenceBlock = getBlockFromCoords(view, coords);
+ const referenceBlock = getBlockFromCoords(view, coords, containerUIInfo);
if (!referenceBlock) {
// could not find the reference block
@@ -109,15 +127,26 @@ function getBlockFromMousePos(
* ```
* Hovering at position x (left edge of BlockB) would return BlockA.
* Instead, we check at position y (right edge of BlockA) to correctly identify BlockB.
+ * `elementsFromPoint` returns the deepest element at a point, so this single
+ * probe descends through any depth of regular nesting.
+ *
+ * When the reference block is a (draggable) container block, the probe is
+ * aimed at the direct child under the cursor instead of the container
+ * itself. The container's own padding can exceed the probe inset, which
+ * would keep resolving the container even though the cursor is aligned with
+ * one of its children (making the child's menu jump away as the cursor
+ * moves towards it).
*/
- const referenceBlocksBoundingBox =
- referenceBlock.node.getBoundingClientRect();
+ const probeTarget =
+ getContainerChildAtCursor(referenceBlock.node, mousePos, containerUIInfo) ??
+ referenceBlock.node;
return getBlockFromCoords(
view,
{
- left: referenceBlocksBoundingBox.right - 10,
+ left: probeTarget.getBoundingClientRect().right - 10,
top: mousePos.y,
},
+ containerUIInfo,
false,
);
}
@@ -214,7 +243,12 @@ export class SideMenuView<
return;
}
- const block = getBlockFromMousePos(this.mousePos, this.pmView);
+ const containerUIInfo = getContainerUIInfo(this.editor);
+ const block = getBlockFromMousePos(
+ this.mousePos,
+ this.pmView,
+ containerUIInfo,
+ );
// Closes the menu if the mouse cursor is beyond the editor vertically.
if (!block || !this.editor.isEditable) {
@@ -240,7 +274,14 @@ export class SideMenuView<
// Shows or updates elements.
if (this.editor.isEditable) {
const blockContentBoundingBox = block.node.getBoundingClientRect();
- const column = block.node.closest("[data-node-type=column]");
+ // The closest container ancestor (a column, callout, ...), excluding
+ // the hovered block itself, which may be a draggable container. Blocks
+ // inside a container anchor the side menu to the container's block
+ // area rather than the editor's left edge, which would put the menu
+ // over unrelated content (or off-screen inside columns).
+ const container = containerUIInfo.containerSelector
+ ? block.node.parentElement?.closest(containerUIInfo.containerSelector)
+ : undefined;
const sideMenuBlock = this.editor.getBlock(
this.hoveredBlock!.getAttribute("data-id")!,
);
@@ -255,12 +296,17 @@ export class SideMenuView<
this.state = {
show: true,
referencePos: new DOMRect(
- column
- ? // We take the first child as column elements have some default
- // padding. This is a little weird since this child element will
- // be the first block, but since it's always non-nested and we
- // only take the x coordinate, it's ok.
- column.firstElementChild!.getBoundingClientRect().x
+ container
+ ? // We anchor to the container's first child block (rather than
+ // the container itself, which may have padding or its own
+ // chrome around the block area). This is a little weird since
+ // this element is the first block, but since it's always
+ // non-nested and we only take the x coordinate, it's ok.
+ (
+ getDirectChildBlocks(container, containerUIInfo)[0] ??
+ container.firstElementChild ??
+ container
+ ).getBoundingClientRect().x
: (
this.pmView.dom.firstChild as HTMLElement
).getBoundingClientRect().x,
diff --git a/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.browser.test.ts b/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.browser.test.ts
new file mode 100644
index 0000000000..d4f3156c63
--- /dev/null
+++ b/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.browser.test.ts
@@ -0,0 +1,209 @@
+import { afterEach, describe, expect, it } from "vite-plus/test";
+
+import type { ContainerUIInfo } from "../../api/blockManipulation/containers/containerUI.js";
+import {
+ getContainerChildAtCursor,
+ getDirectChildBlocks,
+ hasHorizontalContainerAncestor,
+ isHorizontalContainer,
+} from "./sideMenuContainerGeometry.js";
+
+// The side-menu container geometry that reads live layout: the
+// `querySelectorAll`/`closest` walks and the rect measurements behind them. A
+// container whose children happen to sit side-by-side must be recognised as
+// horizontal without declaring anything. (The pure rect arithmetic these
+// build on is unit-tested in `sideMenuContainerGeometry.test.ts`.)
+//
+// The DOM trees are attached to the real document and laid out by the real
+// engine; nothing stubs `getBoundingClientRect`. A column list inside a real
+// editor is covered end-to-end by
+// `tests/src/end-to-end/multicolumn/multicolumn.test.tsx`.
+
+/** Attaches a tree to the document so the browser actually lays it out. */
+function mount(el: T): T {
+ document.body.appendChild(el);
+ mounted.push(el);
+ return el;
+}
+
+let mounted: HTMLElement[] = [];
+
+afterEach(() => {
+ mounted.forEach((el) => el.remove());
+ mounted = [];
+});
+
+function el(nodeType: string): HTMLElement {
+ const node = document.createElement("div");
+ node.setAttribute("data-node-type", nodeType);
+ return node;
+}
+
+/** The `blockOuter > blockContainer` chrome BlockNote renders around every
+ * regular block, with real text in it so it has a real height. */
+function regularChild(text = "block"): {
+ outer: HTMLElement;
+ blockContainer: HTMLElement;
+} {
+ const outer = el("blockOuter");
+ const blockContainer = el("blockContainer");
+ blockContainer.textContent = text;
+ outer.append(blockContainer);
+ return { outer, blockContainer };
+}
+
+function uiInfo(containerTypes: string[]): ContainerUIInfo {
+ const set = new Set(containerTypes);
+ return {
+ containerTypes: set,
+ draggableContainerTypes: set,
+ nonDraggableBlockTypes: new Set(),
+ containerSelector: containerTypes.length
+ ? containerTypes.map((t) => `[data-node-type="${t}"]`).join(",")
+ : null,
+ };
+}
+
+/**
+ * A column list laid out the way the real one is: a flex row of two columns,
+ * each holding one block. Nothing declares "horizontal". The browser puts the
+ * columns side by side and the module has to notice.
+ */
+function buildColumnList() {
+ const info = uiInfo(["columnList", "column"]);
+
+ const columnList = el("columnList");
+ columnList.style.display = "flex";
+ columnList.style.width = "400px";
+
+ const columnA = el("column");
+ const columnB = el("column");
+ for (const column of [columnA, columnB]) {
+ column.style.flex = "1";
+ }
+
+ const childA = regularChild("A");
+ const childB = regularChild("B");
+ columnA.append(childA.outer);
+ columnB.append(childB.outer);
+ columnList.append(columnA, columnB);
+ mount(columnList);
+
+ return { info, columnList, columnA, columnB, childA, childB };
+}
+
+/** A callout: an ordinary block-flow container, so its children stack. */
+function buildVerticalContainer() {
+ const info = uiInfo(["callout"]);
+
+ const callout = el("callout");
+ callout.style.width = "400px";
+ const first = regularChild("first");
+ const second = regularChild("second");
+ callout.append(first.outer, second.outer);
+ mount(callout);
+
+ return { info, callout, first, second };
+}
+
+describe("getDirectChildBlocks", () => {
+ it("returns direct child blocks, skipping nested grandchildren", () => {
+ const { info, columnList, columnA, columnB } = buildColumnList();
+
+ // The blocks inside each column must not come back as the list's own
+ // children. The `closest` check stops the walk one level down.
+ expect(getDirectChildBlocks(columnList, info)).toEqual([columnA, columnB]);
+ });
+
+ it("sees through blockOuter wrappers to the blockContainer child", () => {
+ const { info, columnA, childA } = buildColumnList();
+
+ // The column's own direct child is the wrapped blockContainer, not the
+ // blockOuter chrome (which isn't a block in the selector's sense).
+ expect(getDirectChildBlocks(columnA, info)).toEqual([
+ childA.blockContainer,
+ ]);
+ });
+});
+
+describe("isHorizontalContainer", () => {
+ it("recognises a real flex row as horizontal", () => {
+ const { info, columnList, columnA, columnB } = buildColumnList();
+
+ // Nothing declares the column list horizontal and no rect is stubbed;
+ // the detection runs against real layout.
+ expect(isHorizontalContainer(columnList, info)).toBe(true);
+
+ // Also asserted as raw geometry, so a failure shows whether the layout
+ // or the detection broke.
+ const a = columnA.getBoundingClientRect();
+ const b = columnB.getBoundingClientRect();
+ expect(a.width).toBeGreaterThan(0);
+ expect(b.left).toBeGreaterThanOrEqual(a.right - 1);
+ expect(a.top).toBe(b.top);
+ });
+
+ it("is false for a container whose children stack", () => {
+ const { info, callout } = buildVerticalContainer();
+
+ expect(isHorizontalContainer(callout, info)).toBe(false);
+ });
+
+ it("is false for a column holding a single block", () => {
+ const { info, columnA } = buildColumnList();
+
+ expect(isHorizontalContainer(columnA, info)).toBe(false);
+ });
+});
+
+describe("hasHorizontalContainerAncestor", () => {
+ it("is true for a block nested inside a column of a column list", () => {
+ const { info, childA } = buildColumnList();
+
+ // The block sits inside a (vertical) column, whose parent column list is
+ // the horizontal one, so the walk must climb past the column.
+ expect(hasHorizontalContainerAncestor(childA.blockContainer, info)).toBe(
+ true,
+ );
+ });
+
+ it("is false for a block inside a purely vertical container", () => {
+ const { info, first } = buildVerticalContainer();
+
+ expect(hasHorizontalContainerAncestor(first.blockContainer, info)).toBe(
+ false,
+ );
+ });
+});
+
+describe("getContainerChildAtCursor", () => {
+ it("returns undefined for a non-container element", () => {
+ const { info, childA } = buildColumnList();
+
+ expect(
+ getContainerChildAtCursor(childA.blockContainer, { x: 10, y: 10 }, info),
+ ).toBeUndefined();
+ });
+
+ it("resolves the hovered column of a real row", () => {
+ const { info, columnList, columnA, columnB } = buildColumnList();
+ const b = columnB.getBoundingClientRect();
+
+ expect(
+ getContainerChildAtCursor(
+ columnList,
+ { x: b.left + b.width / 2, y: b.top + b.height / 2 },
+ info,
+ ),
+ ).toBe(columnB);
+
+ const a = columnA.getBoundingClientRect();
+ expect(
+ getContainerChildAtCursor(
+ columnList,
+ { x: a.left + a.width / 2, y: a.top + a.height / 2 },
+ info,
+ ),
+ ).toBe(columnA);
+ });
+});
diff --git a/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.test.ts b/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.test.ts
new file mode 100644
index 0000000000..2d987c0ab0
--- /dev/null
+++ b/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ rectIndexAtCursor,
+ rectsAreSideBySide,
+ type BlockRect,
+} from "./sideMenuContainerGeometry.js";
+
+// The pure rect arithmetic behind the side menu's container handling: which
+// of a container's children the cursor is over, and whether they sit
+// side-by-side (a column list) or stacked (a callout). Plain functions over
+// plain rects, so they need no DOM - the walks that read real layout live in
+// `sideMenuContainerGeometry.browser.test.ts`.
+
+const rect = (
+ top: number,
+ bottom: number,
+ left: number,
+ right: number,
+): BlockRect => ({ top, bottom, left, right });
+
+// Two columns of a column list: same vertical band, adjacent horizontally.
+const SIDE_BY_SIDE = [rect(0, 100, 0, 100), rect(0, 100, 100, 200)];
+// Two blocks of a callout: same horizontal band, stacked vertically.
+const STACKED = [rect(0, 40, 0, 200), rect(50, 90, 0, 200)];
+
+describe("rectsAreSideBySide", () => {
+ it("is true when two rects overlap vertically, false when stacked", () => {
+ expect(rectsAreSideBySide(SIDE_BY_SIDE)).toBe(true);
+ expect(rectsAreSideBySide(STACKED)).toBe(false);
+ // Degenerate inputs are never a row.
+ expect(rectsAreSideBySide([rect(0, 100, 0, 100)])).toBe(false);
+ expect(rectsAreSideBySide([])).toBe(false);
+ });
+
+ it("treats abutting rects as stacked, but counts a one-pixel overlap", () => {
+ // The second rect's top exactly meets the first's bottom. A stack with no
+ // gap must not be misread as a row.
+ expect(
+ rectsAreSideBySide([rect(0, 40, 0, 200), rect(40, 80, 0, 200)]),
+ ).toBe(false);
+ expect(
+ rectsAreSideBySide([rect(0, 41, 0, 100), rect(40, 80, 0, 100)]),
+ ).toBe(true);
+ });
+
+ it("finds an overlapping pair that isn't the first two", () => {
+ // The loop is over every pair, not just neighbours. A column list whose
+ // first two children happen to be stacked is still a row.
+ expect(
+ rectsAreSideBySide([
+ rect(0, 40, 0, 100),
+ rect(40, 80, 0, 100),
+ rect(40, 80, 100, 200),
+ ]),
+ ).toBe(true);
+ });
+});
+
+describe("rectIndexAtCursor", () => {
+ it("returns the rect whose x range contains the cursor (side-by-side)", () => {
+ // Both rects share the y range, so only x distinguishes them. The
+ // vertical-only fallback recorded for the first must not win over an x
+ // match found later in the list; otherwise hovering the second column of
+ // a row would resolve to its neighbour.
+ expect(rectIndexAtCursor(SIDE_BY_SIDE, { x: 150, y: 50 })).toBe(1);
+ expect(rectIndexAtCursor(SIDE_BY_SIDE, { x: 10, y: 50 })).toBe(0);
+ });
+
+ it("falls back to the first vertical match when x is in the gutter", () => {
+ // The cursor's y is in the first block's band but its x is left of it (the
+ // side-menu gutter). The first vertical match wins.
+ expect(rectIndexAtCursor(STACKED, { x: -20, y: 20 })).toBe(0);
+ });
+
+ it("returns undefined when the cursor misses every rect vertically", () => {
+ expect(rectIndexAtCursor(STACKED, { x: 10, y: 999 })).toBeUndefined();
+ expect(rectIndexAtCursor(STACKED, { x: 10, y: -999 })).toBeUndefined();
+ expect(rectIndexAtCursor([], { x: 10, y: 10 })).toBeUndefined();
+ });
+
+ it("includes the rect edges", () => {
+ const single = [rect(0, 40, 0, 200)];
+ expect(rectIndexAtCursor(single, { x: 0, y: 0 })).toBe(0);
+ expect(rectIndexAtCursor(single, { x: 200, y: 40 })).toBe(0);
+ });
+});
diff --git a/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.ts b/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.ts
new file mode 100644
index 0000000000..87f13f9c13
--- /dev/null
+++ b/packages/core/src/extensions/SideMenu/sideMenuContainerGeometry.ts
@@ -0,0 +1,107 @@
+import type { ContainerUIInfo } from "../../api/blockManipulation/containers/containerUI.js";
+
+function containerChildSelector(containerUIInfo: ContainerUIInfo): string {
+ return containerUIInfo.containerSelector
+ ? `[data-node-type="blockContainer"],${containerUIInfo.containerSelector}`
+ : `[data-node-type="blockContainer"]`;
+}
+
+export function getDirectChildBlocks(
+ container: Element,
+ containerUIInfo: ContainerUIInfo,
+): Element[] {
+ const childSelector = containerChildSelector(containerUIInfo);
+
+ const children: Element[] = [];
+ for (const child of container.querySelectorAll(childSelector)) {
+ if (child.parentElement?.closest(childSelector) === container) {
+ children.push(child);
+ }
+ }
+ return children;
+}
+
+export type BlockRect = {
+ top: number;
+ bottom: number;
+ left: number;
+ right: number;
+};
+
+export function rectsAreSideBySide(rects: BlockRect[]): boolean {
+ for (let i = 0; i < rects.length; i++) {
+ for (let j = i + 1; j < rects.length; j++) {
+ if (rects[i].top < rects[j].bottom && rects[j].top < rects[i].bottom) {
+ return true;
+ }
+ }
+ }
+ return false;
+}
+
+// X-match wins over y-only match (disambiguates side-by-side children).
+export function rectIndexAtCursor(
+ rects: BlockRect[],
+ mousePos: { x: number; y: number },
+): number | undefined {
+ let verticalMatch: number | undefined = undefined;
+ for (let i = 0; i < rects.length; i++) {
+ const rect = rects[i];
+ if (mousePos.y < rect.top || mousePos.y > rect.bottom) {
+ continue;
+ }
+ if (mousePos.x >= rect.left && mousePos.x <= rect.right) {
+ return i;
+ }
+ verticalMatch = verticalMatch ?? i;
+ }
+ return verticalMatch;
+}
+
+export function isHorizontalContainer(
+ container: Element,
+ containerUIInfo: ContainerUIInfo,
+): boolean {
+ return rectsAreSideBySide(
+ getDirectChildBlocks(container, containerUIInfo).map((child) =>
+ child.getBoundingClientRect(),
+ ),
+ );
+}
+
+export function hasHorizontalContainerAncestor(
+ element: Element,
+ containerUIInfo: ContainerUIInfo,
+): boolean {
+ if (!containerUIInfo.containerSelector) {
+ return false;
+ }
+ let container = element.closest(containerUIInfo.containerSelector);
+ while (container) {
+ if (isHorizontalContainer(container, containerUIInfo)) {
+ return true;
+ }
+ container =
+ container.parentElement?.closest(containerUIInfo.containerSelector) ??
+ null;
+ }
+ return false;
+}
+
+export function getContainerChildAtCursor(
+ element: Element,
+ mousePos: { x: number; y: number },
+ containerUIInfo: ContainerUIInfo,
+): Element | undefined {
+ const nodeType = element.getAttribute("data-node-type");
+ if (!nodeType || !containerUIInfo.containerTypes.has(nodeType)) {
+ return undefined;
+ }
+
+ const children = getDirectChildBlocks(element, containerUIInfo);
+ const index = rectIndexAtCursor(
+ children.map((child) => child.getBoundingClientRect()),
+ mousePos,
+ );
+ return index === undefined ? undefined : children[index];
+}
diff --git a/packages/core/src/extensions/getDraggableBlockFromElement.browser.test.ts b/packages/core/src/extensions/getDraggableBlockFromElement.browser.test.ts
new file mode 100644
index 0000000000..3c4cac4442
--- /dev/null
+++ b/packages/core/src/extensions/getDraggableBlockFromElement.browser.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { getDraggableBlockFromElement } from "./getDraggableBlockFromElement.js";
+
+// These are pure DOM walks (`closest`/`querySelector` over the block chrome),
+// so we build detached trees rather than booting an editor. Only `view.dom` is
+// read, as the stop condition for the upward walk. No layout is involved, but
+// the unit under test is the DOM API itself, so it runs against a real
+// browser engine rather than jsdom's re-implementation of it.
+
+/** Builds the `blockOuter > blockContainer > blockContent` chrome BlockNote
+ * renders around every regular block. */
+function regularBlock(
+ id: string,
+ contentType: string,
+): { outer: HTMLElement; blockContainer: HTMLElement; content: HTMLElement } {
+ const outer = document.createElement("div");
+ outer.setAttribute("data-node-type", "blockOuter");
+
+ const blockContainer = document.createElement("div");
+ blockContainer.setAttribute("data-node-type", "blockContainer");
+ blockContainer.setAttribute("data-id", id);
+
+ const content = document.createElement("div");
+ content.setAttribute("data-content-type", contentType);
+
+ blockContainer.append(content);
+ outer.append(blockContainer);
+ return { outer, blockContainer, content };
+}
+
+/** Nests `child` under `parent` in a `blockGroup`, as list nesting does. */
+function nest(parent: HTMLElement, child: HTMLElement) {
+ const group = document.createElement("div");
+ group.setAttribute("data-node-type", "blockGroup");
+ group.append(child);
+ parent.append(group);
+}
+
+function viewWith(root: HTMLElement) {
+ const dom = document.createElement("div");
+ dom.append(root);
+ return { dom };
+}
+
+describe("getDraggableBlockFromElement", () => {
+ it("returns the block container for a regular block", () => {
+ const { outer, blockContainer, content } = regularBlock("a", "paragraph");
+
+ expect(getDraggableBlockFromElement(content, viewWith(outer))).toEqual({
+ node: blockContainer,
+ id: "a",
+ });
+ });
+
+ it("skips a block whose type opts out of dragging", () => {
+ const { outer, content } = regularBlock("a", "lockedBlock");
+
+ expect(
+ getDraggableBlockFromElement(content, viewWith(outer), {
+ nonDraggableBlockTypes: new Set(["lockedBlock"]),
+ }),
+ ).toBeUndefined();
+ });
+
+ it("falls through to the nearest draggable ancestor", () => {
+ const parent = regularBlock("parent", "paragraph");
+ const child = regularBlock("child", "lockedBlock");
+ nest(parent.blockContainer, child.outer);
+
+ // Dragging from inside the locked child should hand back the parent's
+ // handle rather than no handle at all.
+ expect(
+ getDraggableBlockFromElement(child.content, viewWith(parent.outer), {
+ nonDraggableBlockTypes: new Set(["lockedBlock"]),
+ }),
+ ).toEqual({ node: parent.blockContainer, id: "parent" });
+ });
+
+ it("reads the block's own content type, not a nested block's", () => {
+ const parent = regularBlock("parent", "lockedBlock");
+ const child = regularBlock("child", "paragraph");
+ nest(parent.blockContainer, child.outer);
+
+ // `parent`'s own content element precedes the nested `blockGroup`, so the
+ // first `[data-content-type]` match inside it must be "lockedBlock".
+ expect(
+ getDraggableBlockFromElement(parent.content, viewWith(parent.outer), {
+ nonDraggableBlockTypes: new Set(["lockedBlock"]),
+ }),
+ ).toBeUndefined();
+ });
+
+ it("returns a container block only when its type is draggable", () => {
+ const column = document.createElement("div");
+ column.setAttribute("data-node-type", "column");
+ column.setAttribute("data-id", "col");
+
+ expect(
+ getDraggableBlockFromElement(column, viewWith(column), {
+ draggableContainerTypes: new Set(["columnList"]),
+ }),
+ ).toBeUndefined();
+
+ expect(
+ getDraggableBlockFromElement(column, viewWith(column), {
+ draggableContainerTypes: new Set(["column"]),
+ }),
+ ).toEqual({ node: column, id: "col" });
+ });
+});
diff --git a/packages/core/src/extensions/getDraggableBlockFromElement.ts b/packages/core/src/extensions/getDraggableBlockFromElement.ts
index abc6bd2906..7423faf9fa 100644
--- a/packages/core/src/extensions/getDraggableBlockFromElement.ts
+++ b/packages/core/src/extensions/getDraggableBlockFromElement.ts
@@ -1,18 +1,59 @@
import { EditorView } from "prosemirror-view";
+const EMPTY_SET: ReadonlySet = new Set();
+
+/**
+ * Walks up from `element` to the closest element that can host a side-menu
+ * drag handle. Both sets are derived from each spec's `meta.draggable` (see
+ * `getContainerUIInfo`); a block that opts out is skipped, so the handle falls
+ * through to the nearest draggable ancestor rather than disappearing.
+ */
export function getDraggableBlockFromElement(
element: Element,
- view: EditorView,
+ // Only `dom` is read, as the stop condition for the upward walk.
+ view: Pick,
+ types: {
+ draggableContainerTypes?: ReadonlySet;
+ nonDraggableBlockTypes?: ReadonlySet;
+ } = {},
) {
+ const draggableContainerTypes = types.draggableContainerTypes ?? EMPTY_SET;
+ const nonDraggableBlockTypes = types.nonDraggableBlockTypes ?? EMPTY_SET;
+
+ const isDraggable = (el: Element) => {
+ const nodeType = el.getAttribute?.("data-node-type");
+
+ if (nodeType === "blockContainer") {
+ if (nonDraggableBlockTypes.size === 0) {
+ return true;
+ }
+ // Every regular block shares the `blockContainer` node, so its actual
+ // block type only shows up on its content element. That element comes
+ // before any nested `blockGroup`, so the first match in document order
+ // is this block's own content rather than a descendant's.
+ const contentType = el
+ .querySelector("[data-content-type]")
+ ?.getAttribute("data-content-type");
+
+ return !contentType || !nonDraggableBlockTypes.has(contentType);
+ }
+
+ return (
+ nodeType !== null &&
+ nodeType !== undefined &&
+ draggableContainerTypes.has(nodeType)
+ );
+ };
+
while (
element &&
element.parentElement &&
element.parentElement !== view.dom &&
- element.getAttribute?.("data-node-type") !== "blockContainer"
+ !isDraggable(element)
) {
element = element.parentElement;
}
- if (element.getAttribute?.("data-node-type") !== "blockContainer") {
+ if (!isDraggable(element)) {
return undefined;
}
return { node: element as HTMLElement, id: element.getAttribute("data-id")! };
diff --git a/packages/core/src/extensions/tiptap-extensions/KeyboardShortcuts/KeyboardShortcutsExtension.test.ts b/packages/core/src/extensions/tiptap-extensions/KeyboardShortcuts/KeyboardShortcutsExtension.test.ts
index 2f1e601a35..2f3464a2db 100644
--- a/packages/core/src/extensions/tiptap-extensions/KeyboardShortcuts/KeyboardShortcutsExtension.test.ts
+++ b/packages/core/src/extensions/tiptap-extensions/KeyboardShortcuts/KeyboardShortcutsExtension.test.ts
@@ -110,6 +110,352 @@ function getTextContent(editor: BlockNoteEditor) {
return text;
}
+/**
+ * Characterization tests for the Backspace/Delete/Enter/Tab handlers: they pin
+ * the current document transformations so the BlockInfo migration inside the
+ * handlers is provably behavior-preserving.
+ */
+function createEditorWithBlocks(
+ initialContent: any[],
+ cursor: { id: string; placement: "start" | "end" },
+) {
+ const editor = BlockNoteEditor.create({ schema, initialContent });
+ editor.mount(document.createElement("div"));
+ editor.setTextCursorPosition(cursor.id, cursor.placement);
+ return editor;
+}
+
+/** Compact structural view of the document for snapshotting. */
+function outline(blocks: any[]): any[] {
+ return blocks.map((b) => ({
+ type: b.type,
+ text: Array.isArray(b.content)
+ ? b.content.map((c: any) => c.text ?? "").join("")
+ : undefined,
+ ...(b.children.length > 0 ? { children: outline(b.children) } : {}),
+ }));
+}
+
+describe("KeyboardShortcutsExtension Backspace", () => {
+ it("merges a block into the previous one at block start", () => {
+ const editor = createEditorWithBlocks(
+ [
+ { id: "a", type: "paragraph", content: "Hello" },
+ { id: "b", type: "paragraph", content: "World" },
+ ],
+ { id: "b", placement: "start" },
+ );
+
+ pressKeys(editor, "Backspace");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "HelloWorld",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+
+ it("merges into the previous block's deepest descendant", () => {
+ const editor = createEditorWithBlocks(
+ [
+ {
+ id: "a",
+ type: "paragraph",
+ content: "Parent",
+ children: [{ id: "a1", type: "paragraph", content: "Nested" }],
+ },
+ { id: "b", type: "paragraph", content: "World" },
+ ],
+ { id: "b", placement: "start" },
+ );
+
+ pressKeys(editor, "Backspace");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "children": [
+ {
+ "text": "NestedWorld",
+ "type": "paragraph",
+ },
+ ],
+ "text": "Parent",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+
+ it("lifts a nested first child at block start", () => {
+ const editor = createEditorWithBlocks(
+ [
+ {
+ id: "a",
+ type: "paragraph",
+ content: "Parent",
+ children: [{ id: "a1", type: "paragraph", content: "Nested" }],
+ },
+ ],
+ { id: "a1", placement: "start" },
+ );
+
+ pressKeys(editor, "Backspace");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "Parent",
+ "type": "paragraph",
+ },
+ {
+ "text": "Nested",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+
+ it("deletes an empty block, moving its children out", () => {
+ const editor = createEditorWithBlocks(
+ [
+ { id: "a", type: "paragraph", content: "Before" },
+ {
+ id: "b",
+ type: "paragraph",
+ content: "",
+ children: [{ id: "b1", type: "paragraph", content: "Child" }],
+ },
+ ],
+ { id: "b", placement: "start" },
+ );
+
+ pressKeys(editor, "Backspace");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "Before",
+ "type": "paragraph",
+ },
+ {
+ "text": "Child",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+});
+
+describe("KeyboardShortcutsExtension Delete", () => {
+ it("merges the next block in at block end", () => {
+ const editor = createEditorWithBlocks(
+ [
+ { id: "a", type: "paragraph", content: "Hello" },
+ { id: "b", type: "paragraph", content: "World" },
+ ],
+ { id: "a", placement: "end" },
+ );
+
+ pressKeys(editor, "Delete");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "HelloWorld",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+
+ it("merges a next block that has children, un-nesting them", () => {
+ const editor = createEditorWithBlocks(
+ [
+ { id: "a", type: "paragraph", content: "Hello" },
+ {
+ id: "b",
+ type: "paragraph",
+ content: "World",
+ children: [
+ { id: "b1", type: "paragraph", content: "Child 1" },
+ { id: "b2", type: "paragraph", content: "Child 2" },
+ ],
+ },
+ ],
+ { id: "a", placement: "end" },
+ );
+
+ pressKeys(editor, "Delete");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "HelloWorld",
+ "type": "paragraph",
+ },
+ {
+ "text": "Child 1",
+ "type": "paragraph",
+ },
+ {
+ "text": "Child 2",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+
+ it("removes an empty next block, adopting its children", () => {
+ const editor = createEditorWithBlocks(
+ [
+ { id: "a", type: "paragraph", content: "Hello" },
+ {
+ id: "b",
+ type: "paragraph",
+ content: "",
+ children: [{ id: "b1", type: "paragraph", content: "Child" }],
+ },
+ ],
+ { id: "a", placement: "end" },
+ );
+
+ pressKeys(editor, "Delete");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "Hello",
+ "type": "paragraph",
+ },
+ {
+ "text": "Child",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+
+ it("removes an empty current block on Delete", () => {
+ const editor = createEditorWithBlocks(
+ [
+ { id: "a", type: "paragraph", content: "" },
+ { id: "b", type: "paragraph", content: "After" },
+ ],
+ { id: "a", placement: "start" },
+ );
+
+ pressKeys(editor, "Delete");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "After",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+});
+
+describe("KeyboardShortcutsExtension Enter", () => {
+ it("inserts an empty block above when Enter is pressed at the start", () => {
+ const editor = createEditorWithBlocks(
+ [{ id: "a", type: "paragraph", content: "Hello" }],
+ { id: "a", placement: "start" },
+ );
+
+ pressKeys(editor, "Enter");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "",
+ "type": "paragraph",
+ },
+ {
+ "text": "Hello",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+
+ it("lifts an empty nested block on Enter", () => {
+ const editor = createEditorWithBlocks(
+ [
+ {
+ id: "a",
+ type: "paragraph",
+ content: "Parent",
+ children: [{ id: "a1", type: "paragraph", content: "" }],
+ },
+ ],
+ { id: "a1", placement: "start" },
+ );
+
+ pressKeys(editor, "Enter");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "Parent",
+ "type": "paragraph",
+ },
+ {
+ "text": "",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+});
+
+describe("KeyboardShortcutsExtension Shift-Tab", () => {
+ it("un-nests a nested block", () => {
+ const editor = createEditorWithBlocks(
+ [
+ {
+ id: "a",
+ type: "paragraph",
+ content: "Parent",
+ children: [{ id: "a1", type: "paragraph", content: "Nested" }],
+ },
+ ],
+ { id: "a1", placement: "start" },
+ );
+
+ pressKeys(editor, "Shift-Tab");
+
+ expect(outline(editor.document)).toMatchInlineSnapshot(`
+ [
+ {
+ "text": "Parent",
+ "type": "paragraph",
+ },
+ {
+ "text": "Nested",
+ "type": "paragraph",
+ },
+ ]
+ `);
+ editor._tiptapEditor.destroy();
+ });
+});
+
describe("KeyboardShortcutsExtension hardBreakShortcut", () => {
it("inserts a hard break on Shift-Enter by default", () => {
const editor = createEditor("paragraph");
diff --git a/packages/core/src/extensions/tiptap-extensions/KeyboardShortcuts/KeyboardShortcutsExtension.ts b/packages/core/src/extensions/tiptap-extensions/KeyboardShortcuts/KeyboardShortcutsExtension.ts
index 4d1758094a..db6ef22305 100644
--- a/packages/core/src/extensions/tiptap-extensions/KeyboardShortcuts/KeyboardShortcutsExtension.ts
+++ b/packages/core/src/extensions/tiptap-extensions/KeyboardShortcuts/KeyboardShortcutsExtension.ts
@@ -1,30 +1,104 @@
-import { Extension } from "@tiptap/core";
+import { CommandProps, Extension } from "@tiptap/core";
import { Fragment, Node } from "prosemirror-model";
-import { TextSelection } from "prosemirror-state";
+import { NodeSelection, TextSelection, Transaction } from "prosemirror-state";
-import {
- getBottomNestedBlockInfo,
- getNextBlockInfo,
- getParentBlockInfo,
- getPrevBlockInfo,
- mergeBlocksCommand,
-} from "../../../api/blockManipulation/commands/mergeBlocks/mergeBlocks.js";
+import { mergeBlocksCommand } from "../../../api/blockManipulation/commands/mergeBlocks/mergeBlocks.js";
import {
liftItem,
nestBlock,
unnestBlock,
} from "../../../api/blockManipulation/commands/nestBlock/nestBlock.js";
-import { fixColumnList } from "../../../api/blockManipulation/commands/replaceBlocks/util/fixColumnList.js";
+import {
+ fixContainersById,
+ isContainerNode,
+} from "../../../api/blockManipulation/containers/fixContainer.js";
+import {
+ ascendToInsertablePos,
+ descendToInsertionPos,
+ getAncestorContainers,
+ getFirstLeafBlock,
+} from "../../../api/blockManipulation/containers/containerNav.js";
+import { isSealed } from "../../../schema/blocks/children.js";
import { splitBlockCommand } from "../../../api/blockManipulation/commands/splitBlock/splitBlock.js";
import { updateBlockCommand } from "../../../api/blockManipulation/commands/updateBlock/updateBlock.js";
import {
- getBlockInfoFromResolvedPos,
+ getBlockInfoAt,
+ getBlockInfoFromNode,
getBlockInfoFromSelection,
+ getLastDescendantBlockInfo,
+ getNextBlockInfo,
+ getParentBlockInfo,
+ getPrevBlockInfo,
+ tableContentCaretPos,
} from "../../../api/getBlockInfoFromPos.js";
import { BlockNoteEditor } from "../../../editor/BlockNoteEditor.js";
import { FilePanelExtension } from "../../FilePanel/FilePanel.js";
import { FormattingToolbarExtension } from "../../FormattingToolbar/FormattingToolbar.js";
+// Moves `node` out of its container to `insertAt` (a position in the pre-delete
+// doc): deletes it from `[from, to]`, re-inserts it, repairs the containers it
+// left behind (their `whenEmptied` min/unwrap/refill), and places the caret
+// inside the moved block. Every position is mapped through the deletion and the
+// repair, so the caret lands correctly even when the repair rewrites the source
+// container. Shared by the Backspace/Delete/Enter container-boundary branches.
+function moveBlockOutAndPlaceCaret(
+ tr: Transaction,
+ {
+ from,
+ to,
+ node,
+ insertAt,
+ }: { from: number; to: number; node: Node; insertAt: number },
+) {
+ const containersToFix = getAncestorContainers(tr.doc, from);
+ tr.delete(from, to);
+ const insertionPos = tr.mapping.map(insertAt);
+ tr.insert(insertionPos, node);
+ const stepsBeforeFix = tr.steps.length;
+ fixContainersById(tr, containersToFix);
+ tr.setSelection(
+ TextSelection.near(
+ tr.doc.resolve(tr.mapping.slice(stepsBeforeFix).map(insertionPos) + 1),
+ ),
+ );
+}
+
+// If the sibling in `direction` of the current block is a sealed container,
+// selects it (a NodeSelection) instead of merging across its sealed boundary,
+// so a second Backspace/Delete can delete the container explicitly. Returns a
+// command: `false` when nothing to select, `true` once handled. Shared by the
+// Backspace (prev) and Delete (next) boundary branches.
+function selectSealedSiblingCommand(direction: "prev" | "next") {
+ return ({ state, tr, dispatch }: CommandProps) => {
+ const blockInfo = getBlockInfoFromSelection(state);
+ if (!blockInfo.hasContent) {
+ return false;
+ }
+
+ const atEdge =
+ direction === "prev"
+ ? state.selection.from === blockInfo.contentStart
+ : state.selection.from === blockInfo.contentEnd;
+ if (!atEdge || !state.selection.empty) {
+ return false;
+ }
+
+ const sibling = (
+ direction === "prev" ? getPrevBlockInfo : getNextBlockInfo
+ )(state.doc, blockInfo.block.beforePos);
+ if (!sibling || !isSealed(sibling.block.node)) {
+ return false;
+ }
+
+ if (dispatch && NodeSelection.isSelectable(sibling.block.node)) {
+ tr.setSelection(
+ NodeSelection.create(tr.doc, sibling.block.beforePos),
+ ).scrollIntoView();
+ }
+ return true;
+ };
+}
+
export const KeyboardShortcutsExtension = Extension.create<{
editor: BlockNoteEditor;
tabBehavior: "prefer-navigate-ui" | "prefer-indent";
@@ -45,18 +119,18 @@ export const KeyboardShortcutsExtension = Extension.create<{
() =>
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const selectionAtBlockStart =
- state.selection.from === blockInfo.blockContent.beforePos + 1;
+ state.selection.from === blockInfo.contentStart;
const isParagraph =
- blockInfo.blockContent.node.type.name === "paragraph";
+ blockInfo.content.node.type.name === "paragraph";
if (selectionAtBlockStart && !isParagraph) {
return commands.command(
- updateBlockCommand(blockInfo.bnBlock.beforePos, {
+ updateBlockCommand(blockInfo.block.beforePos, {
type: "paragraph",
props: {},
}),
@@ -69,13 +143,12 @@ export const KeyboardShortcutsExtension = Extension.create<{
() =>
commands.command(({ state, tr }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { blockContent } = blockInfo;
const selectionAtBlockStart =
- state.selection.from === blockContent.beforePos + 1;
+ state.selection.from === blockInfo.contentStart;
if (selectionAtBlockStart) {
return liftItem(
@@ -87,33 +160,36 @@ export const KeyboardShortcutsExtension = Extension.create<{
return false;
}),
+ // If the previous sibling is a sealed container, selects it instead
+ // of merging into it.
+ () => commands.command(selectSealedSiblingCommand("prev")),
// Merges block with the previous one if it isn't indented, and the selection is at the start of the
// block. The target block for merging must contain inline content.
() =>
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { bnBlock: blockContainer, blockContent } = blockInfo;
+ const { block: blockContainer } = blockInfo;
const prevBlockInfo = getPrevBlockInfo(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
// If the previous block has no inline content, it can't be merged.
// It's instead deleted, which is done later in the chan, so we
// return early here.
if (
!prevBlockInfo ||
- !prevBlockInfo.isBlockContainer ||
- prevBlockInfo.blockContent.node.type.spec.content !== "inline*"
+ !prevBlockInfo.hasContent ||
+ prevBlockInfo.contentKind !== "inline"
) {
return false;
}
const selectionAtBlockStart =
- state.selection.from === blockContent.beforePos + 1;
+ state.selection.from === blockInfo.contentStart;
const selectionEmpty = state.selection.empty;
const posBetweenBlocks = blockContainer.beforePos;
@@ -127,64 +203,86 @@ export const KeyboardShortcutsExtension = Extension.create<{
return false;
}),
- // If the previous block is a columnList, moves the current block to
- // the end of the last column in it.
+ // If the previous block is a container (e.g. a columnList or a
+ // callout), moves the current block to its deepest trailing insertion
+ // slot, descending through nested containers (e.g. to the end of the
+ // last column).
() =>
commands.command(({ state, tr, dispatch }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const selectionAtBlockStart =
- state.selection.from === blockInfo.blockContent.beforePos + 1;
+ state.selection.from === blockInfo.contentStart;
if (!selectionAtBlockStart) {
return false;
}
const prevBlockInfo = getPrevBlockInfo(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
- if (!prevBlockInfo || prevBlockInfo.isBlockContainer) {
+ if (!prevBlockInfo || prevBlockInfo.hasContent) {
return false;
}
- if (dispatch) {
- const columnAfterPos = prevBlockInfo.bnBlock.afterPos - 1;
- const $blockAfterPos = tr.doc.resolve(columnAfterPos - 1);
-
- tr.delete(
- blockInfo.bnBlock.beforePos,
- blockInfo.bnBlock.afterPos,
- );
- tr.insert($blockAfterPos.pos, blockInfo.bnBlock.node);
- tr.setSelection(
- TextSelection.near(tr.doc.resolve($blockAfterPos.pos + 1)),
- );
+ const blockContainerType = state.schema.nodes["blockContainer"];
+ const insertion = descendToInsertionPos(
+ prevBlockInfo,
+ blockContainerType,
+ "last",
+ );
+ if (insertion.pos === undefined) {
+ // A sealed container can't be entered, so it's selected instead,
+ // and a second Backspace deletes it explicitly. A container with
+ // nowhere a `blockContainer` can land falls through as before.
+ if (
+ insertion.blockedBy === "seal" &&
+ NodeSelection.isSelectable(prevBlockInfo.block.node)
+ ) {
+ if (dispatch) {
+ tr.setSelection(
+ NodeSelection.create(tr.doc, prevBlockInfo.block.beforePos),
+ ).scrollIntoView();
+ }
+ return true;
+ }
+ return false;
+ }
+ if (dispatch) {
+ moveBlockOutAndPlaceCaret(tr, {
+ from: blockInfo.block.beforePos,
+ to: blockInfo.block.afterPos,
+ node: blockInfo.block.node,
+ insertAt: insertion.pos,
+ });
return true;
}
return false;
}),
- // If the block is the first in a column, moves it to the end of the
- // previous column. If there is no previous column, moves it above the
- // columnList.
+ // If the block is the first in a container (e.g. a column or a
+ // callout), moves it out: to the end of the previous sibling
+ // container if there is one (e.g. the previous column), otherwise to
+ // just before the closest enclosing boundary that accepts it (e.g.
+ // above the columnList / callout).
() =>
commands.command(({ state, tr, dispatch }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const selectionAtBlockStart =
- tr.selection.from === blockInfo.blockContent.beforePos + 1;
+ tr.selection.from === blockInfo.contentStart;
if (!selectionAtBlockStart) {
return false;
}
- const $pos = tr.doc.resolve(blockInfo.bnBlock.beforePos);
+ const $pos = tr.doc.resolve(blockInfo.block.beforePos);
const prevBlock = $pos.nodeBefore;
if (prevBlock) {
@@ -192,32 +290,56 @@ export const KeyboardShortcutsExtension = Extension.create<{
}
const parentBlock = $pos.node();
- if (parentBlock.type.name !== "column") {
+ if (!isContainerNode(parentBlock.type)) {
return false;
}
- const $blockPos = tr.doc.resolve(blockInfo.bnBlock.beforePos);
- const $columnPos = tr.doc.resolve($blockPos.before());
- const columnListPos = $columnPos.before();
-
- if (dispatch) {
- tr.delete(
- blockInfo.bnBlock.beforePos,
- blockInfo.bnBlock.afterPos,
- );
- fixColumnList(tr, columnListPos);
+ // A sealed container swallows Backspace at its first block:
+ // moving the block out would cross the boundary.
+ if (isSealed(parentBlock)) {
+ return true;
+ }
- if ($columnPos.pos === columnListPos + 1) {
- tr.insert(columnListPos, blockInfo.bnBlock.node);
- tr.setSelection(
- TextSelection.near(tr.doc.resolve(columnListPos)),
- );
- } else {
- tr.insert($columnPos.pos - 1, blockInfo.bnBlock.node);
- tr.setSelection(
- TextSelection.near(tr.doc.resolve($columnPos.pos)),
+ const blockContainerType = state.schema.nodes["blockContainer"];
+ const containerBeforePos = $pos.before();
+ const $containerPos = tr.doc.resolve(containerBeforePos);
+
+ // A previous sibling inside an enclosing container (e.g. the
+ // previous column) is a target to descend into. A sibling at a
+ // regular block position is not; there the block moves out to
+ // before the container instead.
+ const prevSibling =
+ isContainerNode($containerPos.node().type) &&
+ $containerPos.nodeBefore &&
+ isContainerNode($containerPos.nodeBefore.type)
+ ? $containerPos.nodeBefore
+ : null;
+
+ const insertionPos = prevSibling
+ ? descendToInsertionPos(
+ getBlockInfoFromNode(
+ prevSibling,
+ containerBeforePos - prevSibling.nodeSize,
+ ),
+ blockContainerType,
+ "last",
+ ).pos
+ : ascendToInsertablePos(
+ tr.doc,
+ containerBeforePos,
+ blockContainerType,
);
- }
+ if (insertionPos === undefined) {
+ return false;
+ }
+
+ if (dispatch) {
+ moveBlockOutAndPlaceCaret(tr, {
+ from: blockInfo.block.beforePos,
+ to: blockInfo.block.afterPos,
+ node: blockInfo.block.node,
+ insertAt: insertionPos,
+ });
}
return true;
@@ -227,69 +349,57 @@ export const KeyboardShortcutsExtension = Extension.create<{
() =>
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const blockEmpty =
- blockInfo.blockContent.node.childCount === 0 &&
- blockInfo.blockContent.node.type.spec.content === "inline*";
+ blockInfo.isContentEmpty && blockInfo.contentKind === "inline";
if (blockEmpty) {
const prevBlockInfo = getPrevBlockInfo(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
if (!prevBlockInfo) {
return false;
}
- const bottomNestedPrevBlockInfo = getBottomNestedBlockInfo(
+ const bottomNestedPrevBlockInfo = getLastDescendantBlockInfo(
state.doc,
prevBlockInfo,
);
- if (!bottomNestedPrevBlockInfo.isBlockContainer) {
- return false;
- }
- if (
- !bottomNestedPrevBlockInfo ||
- !bottomNestedPrevBlockInfo.isBlockContainer
- ) {
+ if (!bottomNestedPrevBlockInfo.hasContent) {
return false;
}
let chainedCommands = chain();
// Moves the children the current block.
- if (blockInfo.childContainer) {
+ if (blockInfo.children) {
chainedCommands.insertContentAt(
- blockInfo.bnBlock.afterPos,
- blockInfo.childContainer?.node.content,
+ blockInfo.block.afterPos,
+ blockInfo.children?.node.content,
);
}
if (
- bottomNestedPrevBlockInfo.blockContent.node.type.spec
- .content === "tableRow+"
+ bottomNestedPrevBlockInfo.content.node.type.spec.content ===
+ "tableRow+"
) {
- const tableBlockEndPos = blockInfo.bnBlock.beforePos - 1;
- const tableBlockContentEndPos = tableBlockEndPos - 1;
- const lastRowEndPos = tableBlockContentEndPos - 1;
- const lastCellEndPos = lastRowEndPos - 1;
- const lastCellParagraphEndPos = lastCellEndPos - 1;
-
chainedCommands = chainedCommands.setTextSelection(
- lastCellParagraphEndPos,
+ tableContentCaretPos(
+ bottomNestedPrevBlockInfo.content,
+ "end",
+ ),
);
} else if (
- bottomNestedPrevBlockInfo.blockContent.node.type.spec
- .content === ""
+ bottomNestedPrevBlockInfo.content.node.type.spec.content === ""
) {
chainedCommands = chainedCommands.setNodeSelection(
- bottomNestedPrevBlockInfo.blockContent.beforePos,
+ bottomNestedPrevBlockInfo.content.beforePos,
);
} else {
- const blockContentEndPos =
- bottomNestedPrevBlockInfo.blockContent.afterPos - 1;
+ const blockContentEndPos = bottomNestedPrevBlockInfo.contentEnd;
chainedCommands =
chainedCommands.setTextSelection(blockContentEndPos);
@@ -297,8 +407,8 @@ export const KeyboardShortcutsExtension = Extension.create<{
return chainedCommands
.deleteRange({
- from: blockInfo.bnBlock.beforePos,
- to: blockInfo.bnBlock.afterPos,
+ from: blockInfo.block.beforePos,
+ to: blockInfo.block.afterPos,
})
.scrollIntoView()
.run();
@@ -313,47 +423,50 @@ export const KeyboardShortcutsExtension = Extension.create<{
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const selectionAtBlockStart =
- state.selection.from === blockInfo.blockContent.beforePos + 1;
+ state.selection.from === blockInfo.contentStart;
const selectionEmpty = state.selection.empty;
const prevBlockInfo = getPrevBlockInfo(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
if (prevBlockInfo && selectionAtBlockStart && selectionEmpty) {
- const bottomBlock = getBottomNestedBlockInfo(
+ // The descent stops at a sealed container instead of finding an
+ // (empty) block inside it, so the current block is never cut in
+ // across the boundary. A container has no content, so the guard
+ // below rejects it.
+ const bottomBlock = getLastDescendantBlockInfo(
state.doc,
prevBlockInfo,
);
- if (!bottomBlock.isBlockContainer) {
+ if (!bottomBlock.hasContent) {
return false;
}
const prevBlockNotTableAndNoContent =
- bottomBlock.blockContent.node.type.spec.content === "" ||
- (bottomBlock.blockContent.node.type.spec.content ===
- "inline*" &&
- bottomBlock.blockContent.node.childCount === 0);
+ bottomBlock.contentKind === "none" ||
+ (bottomBlock.contentKind === "inline" &&
+ bottomBlock.isContentEmpty);
if (prevBlockNotTableAndNoContent) {
return chain()
.cut(
{
- from: blockInfo.bnBlock.beforePos,
- to: blockInfo.bnBlock.afterPos,
+ from: blockInfo.block.beforePos,
+ to: blockInfo.block.afterPos,
},
- bottomBlock.bnBlock.afterPos,
+ bottomBlock.block.afterPos,
)
.deleteRange({
- from: bottomBlock.bnBlock.beforePos,
- to: bottomBlock.bnBlock.afterPos,
+ from: bottomBlock.block.beforePos,
+ to: bottomBlock.block.afterPos,
})
.run();
}
@@ -375,48 +488,54 @@ export const KeyboardShortcutsExtension = Extension.create<{
() =>
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer || !blockInfo.childContainer) {
+ if (!blockInfo.hasContent || !blockInfo.children) {
+ return false;
+ }
+ const { children } = blockInfo;
+
+ // A container allowed to hold no children still has a child
+ // container node, but no first child to pull anything out of.
+ if (children.node.childCount === 0) {
return false;
}
- const { blockContent, childContainer } = blockInfo;
const selectionAtBlockEnd =
- state.selection.from === blockContent.afterPos - 1;
+ state.selection.from === blockInfo.contentEnd;
const selectionEmpty = state.selection.empty;
- const firstChildBlockInfo = getBlockInfoFromResolvedPos(
- state.doc.resolve(childContainer.beforePos + 1),
+ const firstChildBlockInfo = getBlockInfoAt(
+ state.doc,
+ children.childrenStart,
);
- if (!firstChildBlockInfo.isBlockContainer) {
+ if (!firstChildBlockInfo.hasContent) {
return false;
}
if (selectionAtBlockEnd && selectionEmpty) {
- const firstChildBlockContent =
- firstChildBlockInfo.blockContent.node;
+ const firstChildBlockContent = firstChildBlockInfo.content.node;
const firstChildBlockHasInlineContent =
- firstChildBlockContent.type.spec.content === "inline*";
- const blockHasInlineContent =
- blockContent.node.type.spec.content === "inline*";
+ firstChildBlockInfo.contentKind === "inline";
+ const blockHasInlineContent = blockInfo.contentKind === "inline";
return (
chain()
// Un-nests child block's children if necessary.
.insertContentAt(
- firstChildBlockInfo.bnBlock.afterPos,
- firstChildBlockInfo.childContainer?.node.content ||
+ firstChildBlockInfo.block.afterPos,
+ firstChildBlockInfo.children?.node.content ||
Fragment.empty,
)
.deleteRange(
- // Deletes whole child container if there's only one child.
- childContainer.node.childCount === 1
+ // Deletes whole child container if there's only one
+ // child.
+ children.node.childCount === 1
? {
- from: childContainer.beforePos,
- to: childContainer.afterPos,
+ from: children.beforePos,
+ to: children.afterPos,
}
: {
- from: firstChildBlockInfo.bnBlock.beforePos,
- to: firstChildBlockInfo.bnBlock.afterPos,
+ from: firstChildBlockInfo.block.beforePos,
+ to: firstChildBlockInfo.block.afterPos,
},
)
// Appends inline content from child block if possible.
@@ -434,27 +553,31 @@ export const KeyboardShortcutsExtension = Extension.create<{
return false;
}),
+ // If the next sibling is a sealed container, selects it instead of
+ // merging it in. Delete counterpart of the sealed-previous-sibling
+ // Backspace case.
+ () => commands.command(selectSealedSiblingCommand("next")),
// Merges block with the next one (at the same nesting level or lower),
// if one exists, the block has no children, and the selection is at the
// end of the block.
() =>
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { bnBlock: blockContainer, blockContent } = blockInfo;
+ const { block: blockContainer } = blockInfo;
const nextBlockInfo = getNextBlockInfo(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
- if (!nextBlockInfo || !nextBlockInfo.isBlockContainer) {
+ if (!nextBlockInfo || !nextBlockInfo.hasContent) {
return false;
}
const selectionAtBlockEnd =
- state.selection.from === blockContent.afterPos - 1;
+ state.selection.from === blockInfo.contentEnd;
const selectionEmpty = state.selection.empty;
const posBetweenBlocks = blockContainer.afterPos;
@@ -468,65 +591,65 @@ export const KeyboardShortcutsExtension = Extension.create<{
return false;
}),
- // If the next block is a columnList, moves the first block from its
- // first column to after the current block.
+ // If the next block is a container (e.g. a columnList or a callout),
+ // moves its first leaf block out, to after the current block.
() =>
commands.command(({ state, tr, dispatch }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const selectionAtBlockEnd =
- state.selection.from === blockInfo.blockContent.afterPos - 1;
+ state.selection.from === blockInfo.contentEnd;
if (!selectionAtBlockEnd) {
return false;
}
const nextBlockInfo = getNextBlockInfo(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
- if (!nextBlockInfo || nextBlockInfo.isBlockContainer) {
+ if (!nextBlockInfo || nextBlockInfo.hasContent) {
return false;
}
- if (dispatch) {
- const columnBeforePos = nextBlockInfo.bnBlock.beforePos + 1;
- const $blockBeforePos = tr.doc.resolve(columnBeforePos + 1);
+ const firstLeaf = getFirstLeafBlock(nextBlockInfo);
+ if (!firstLeaf) {
+ return false;
+ }
- tr.delete(
- $blockBeforePos.pos,
- $blockBeforePos.pos + $blockBeforePos.nodeAfter!.nodeSize,
- );
- fixColumnList(tr, nextBlockInfo.bnBlock.beforePos);
- tr.insert(blockInfo.bnBlock.afterPos, $blockBeforePos.nodeAfter!);
- tr.setSelection(
- TextSelection.near(tr.doc.resolve($blockBeforePos.pos)),
- );
+ if (dispatch) {
+ moveBlockOutAndPlaceCaret(tr, {
+ from: firstLeaf.block.beforePos,
+ to: firstLeaf.block.afterPos,
+ node: firstLeaf.block.node,
+ insertAt: blockInfo.block.afterPos,
+ });
return true;
}
return false;
}),
- // If the block is the last in a column, moves it to the start of the
- // next column. If there is no next column, moves it below the
- // columnList.
+ // If the block is the last in a container (e.g. a column or a
+ // callout), moves the next block to after it. The next block is the
+ // first leaf of the next sibling container, or the block following
+ // the enclosing containers.
() =>
commands.command(({ state, tr, dispatch }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const selectionAtBlockEnd =
- tr.selection.from === blockInfo.blockContent.afterPos - 1;
+ tr.selection.from === blockInfo.contentEnd;
if (!selectionAtBlockEnd) {
return false;
}
- const $pos = tr.doc.resolve(blockInfo.bnBlock.afterPos);
+ const $pos = tr.doc.resolve(blockInfo.block.afterPos);
const nextBlock = $pos.nodeAfter;
if (nextBlock) {
@@ -534,37 +657,47 @@ export const KeyboardShortcutsExtension = Extension.create<{
}
const parentBlock = $pos.node();
- if (parentBlock.type.name !== "column") {
+ if (!isContainerNode(parentBlock.type)) {
+ return false;
+ }
+
+ // Climbs out of the containers the block is the last child of,
+ // to the first position with a following node.
+ let $boundary = $pos;
+ while (
+ $boundary.nodeAfter === null &&
+ $boundary.depth > 0 &&
+ isContainerNode($boundary.node().type)
+ ) {
+ // Pulling a block in from past a sealed boundary would cross
+ // it, so the keystroke is swallowed instead.
+ if (isSealed($boundary.node())) {
+ return true;
+ }
+ $boundary = tr.doc.resolve($boundary.after());
+ }
+
+ const nextNode = $boundary.nodeAfter;
+ if (!nextNode) {
return false;
}
- const $blockEndPos = tr.doc.resolve(blockInfo.bnBlock.afterPos);
- const $columnEndPos = tr.doc.resolve($blockEndPos.after());
- const columnListEndPos = $columnEndPos.after();
+ // The block to pull in: the next node itself, or its first leaf
+ // block when it's a container.
+ const target = getFirstLeafBlock(
+ getBlockInfoFromNode(nextNode, $boundary.pos),
+ );
+ if (!target) {
+ return false;
+ }
if (dispatch) {
- // Position before first block in next column, or first block
- // after columnList if there is no next column.
- const nextBlockBeforePos =
- $columnEndPos.pos === columnListEndPos - 1
- ? columnListEndPos
- : $columnEndPos.pos + 1;
- const nextBlockInfo = getBlockInfoFromResolvedPos(
- tr.doc.resolve(nextBlockBeforePos),
- );
-
- tr.delete(
- nextBlockInfo.bnBlock.beforePos,
- nextBlockInfo.bnBlock.afterPos,
- );
- fixColumnList(
- tr,
- columnListEndPos - $columnEndPos.node().nodeSize,
- );
- tr.insert($blockEndPos.pos, nextBlockInfo.bnBlock.node);
- tr.setSelection(
- TextSelection.near(tr.doc.resolve(nextBlockBeforePos)),
- );
+ moveBlockOutAndPlaceCaret(tr, {
+ from: target.block.beforePos,
+ to: target.block.afterPos,
+ node: target.block.node,
+ insertAt: blockInfo.block.afterPos,
+ });
}
return true;
@@ -577,13 +710,12 @@ export const KeyboardShortcutsExtension = Extension.create<{
() =>
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { blockContent } = blockInfo;
const selectionAtBlockEnd =
- state.selection.from === blockContent.afterPos - 1;
+ state.selection.from === blockInfo.contentEnd;
const selectionEmpty = state.selection.empty;
if (selectionAtBlockEnd && selectionEmpty) {
@@ -597,41 +729,44 @@ export const KeyboardShortcutsExtension = Extension.create<{
}
const parentBlockInfo = getParentBlockInfo(doc, beforePos);
- if (!parentBlockInfo) {
+ if (
+ !parentBlockInfo ||
+ // Never climbs past a sealed boundary. A block found
+ // there would be pulled in across it.
+ isSealed(parentBlockInfo.block.node)
+ ) {
return undefined;
}
return getNextBlockInfoAtAnyLevel(
doc,
- parentBlockInfo.bnBlock.beforePos,
+ parentBlockInfo.block.beforePos,
);
};
const nextBlockInfo = getNextBlockInfoAtAnyLevel(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
- if (!nextBlockInfo || !nextBlockInfo.isBlockContainer) {
+ if (!nextBlockInfo || !nextBlockInfo.hasContent) {
return false;
}
- const nextBlockContent = nextBlockInfo.blockContent.node;
+ const nextBlockContent = nextBlockInfo.content.node;
const nextBlockHasInlineContent =
- nextBlockContent.type.spec.content === "inline*";
- const blockHasInlineContent =
- blockContent.node.type.spec.content === "inline*";
+ nextBlockInfo.contentKind === "inline";
+ const blockHasInlineContent = blockInfo.contentKind === "inline";
return (
chain()
// Un-nests next block's children if necessary.
.insertContentAt(
- nextBlockInfo.bnBlock.afterPos,
- nextBlockInfo.childContainer?.node.content ||
- Fragment.empty,
+ nextBlockInfo.block.afterPos,
+ nextBlockInfo.children?.node.content || Fragment.empty,
)
.deleteRange({
- from: nextBlockInfo.bnBlock.beforePos,
- to: nextBlockInfo.bnBlock.afterPos,
+ from: nextBlockInfo.block.beforePos,
+ to: nextBlockInfo.block.afterPos,
})
// Appends inline content from child block if possible.
.insertContentAt(
@@ -653,54 +788,42 @@ export const KeyboardShortcutsExtension = Extension.create<{
() =>
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const blockEmpty =
- blockInfo.blockContent.node.childCount === 0 &&
- blockInfo.blockContent.node.type.spec.content === "inline*";
+ blockInfo.isContentEmpty && blockInfo.contentKind === "inline";
if (blockEmpty) {
const nextBlockInfo = getNextBlockInfo(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
- if (!nextBlockInfo || !nextBlockInfo.isBlockContainer) {
+ if (!nextBlockInfo || !nextBlockInfo.hasContent) {
return false;
}
let chainedCommands = chain();
- if (
- nextBlockInfo.blockContent.node.type.spec.content ===
- "tableRow+"
- ) {
- const tableBlockStartPos = blockInfo.bnBlock.afterPos + 1;
- const tableBlockContentStartPos = tableBlockStartPos + 1;
- const firstRowStartPos = tableBlockContentStartPos + 1;
- const firstCellStartPos = firstRowStartPos + 1;
- const firstCellParagraphStartPos = firstCellStartPos + 1;
-
+ if (nextBlockInfo.contentKind === "table") {
chainedCommands = chainedCommands.setTextSelection(
- firstCellParagraphStartPos,
+ tableContentCaretPos(nextBlockInfo.content, "start"),
);
- } else if (
- nextBlockInfo.blockContent.node.type.spec.content === ""
- ) {
+ } else if (nextBlockInfo.contentKind === "none") {
chainedCommands = chainedCommands.setNodeSelection(
- nextBlockInfo.blockContent.beforePos,
+ nextBlockInfo.content.beforePos,
);
} else {
chainedCommands = chainedCommands.setTextSelection(
- nextBlockInfo.blockContent.beforePos + 1,
+ nextBlockInfo.contentStart,
);
}
return chainedCommands
.deleteRange({
- from: blockInfo.bnBlock.beforePos,
- to: blockInfo.bnBlock.afterPos,
+ from: blockInfo.block.beforePos,
+ to: blockInfo.block.afterPos,
})
.scrollIntoView()
.run();
@@ -715,45 +838,40 @@ export const KeyboardShortcutsExtension = Extension.create<{
commands.command(({ state }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
const selectionAtBlockEnd =
- state.selection.from === blockInfo.blockContent.afterPos - 1;
+ state.selection.from === blockInfo.contentEnd;
const selectionEmpty = state.selection.empty;
const nextBlockInfo = getNextBlockInfo(
state.doc,
- blockInfo.bnBlock.beforePos,
+ blockInfo.block.beforePos,
);
if (!nextBlockInfo) {
return false;
}
- if (!nextBlockInfo.isBlockContainer) {
+ if (!nextBlockInfo.hasContent) {
return false;
}
if (nextBlockInfo && selectionAtBlockEnd && selectionEmpty) {
const nextBlockNotTableAndNoContent =
- nextBlockInfo.blockContent.node.type.spec.content === "" ||
- (nextBlockInfo.blockContent.node.type.spec.content ===
- "inline*" &&
- nextBlockInfo.blockContent.node.childCount === 0);
+ nextBlockInfo.contentKind === "none" ||
+ (nextBlockInfo.contentKind === "inline" &&
+ nextBlockInfo.isContentEmpty);
if (nextBlockNotTableAndNoContent) {
- const childBlocks =
- nextBlockInfo.bnBlock.node.lastChild!.content;
return chain()
.deleteRange({
- from: nextBlockInfo.bnBlock.beforePos,
- to: nextBlockInfo.bnBlock.afterPos,
+ from: nextBlockInfo.block.beforePos,
+ to: nextBlockInfo.block.afterPos,
})
.insertContentAt(
- blockInfo.bnBlock.afterPos,
- nextBlockInfo.bnBlock.node.childCount === 2
- ? childBlocks
- : null,
+ blockInfo.block.afterPos,
+ nextBlockInfo.children?.node.content ?? null,
)
.run();
}
@@ -770,10 +888,10 @@ export const KeyboardShortcutsExtension = Extension.create<{
() =>
commands.command(({ state, tr }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { bnBlock: blockContainer, blockContent } = blockInfo;
+ const { block: blockContainer } = blockInfo;
const { depth } = state.doc.resolve(blockContainer.beforePos);
@@ -781,7 +899,7 @@ export const KeyboardShortcutsExtension = Extension.create<{
state.selection.$anchor.parentOffset === 0;
const selectionEmpty =
state.selection.anchor === state.selection.head;
- const blockEmpty = blockContent.node.childCount === 0;
+ const blockEmpty = blockInfo.isContentEmpty;
const blockIndented = depth > 1;
if (
@@ -859,21 +977,80 @@ export const KeyboardShortcutsExtension = Extension.create<{
return false;
}),
+ // If the block is empty and the last child of a non-sealed container,
+ // moves the block out (double Enter exits the container). The block
+ // lands at the nearest enclosing position that accepts it. E.g. out
+ // of a column it skips the columnList, which holds only columns, and
+ // lands below it. Without this, Enter only ever creates new blocks
+ // within the container, so the cursor could never leave a trailing
+ // container. Shift+Enter still adds spacing inside a container.
+ () =>
+ commands.command(({ state, tr, dispatch }) => {
+ const blockInfo = getBlockInfoFromSelection(state);
+ if (!blockInfo.hasContent) {
+ return false;
+ }
+
+ const selectionEmpty =
+ state.selection.anchor === state.selection.head;
+ const blockEmpty = blockInfo.isContentEmpty;
+ if (!selectionEmpty || !blockEmpty) {
+ return false;
+ }
+
+ const $pos = tr.doc.resolve(blockInfo.block.beforePos);
+ const parentBlock = $pos.node();
+ if (!isContainerNode(parentBlock.type)) {
+ return false;
+ }
+
+ // Only fires on the container's last child.
+ if (tr.doc.resolve(blockInfo.block.afterPos).nodeAfter !== null) {
+ return false;
+ }
+
+ // A sealed boundary means Enter never moves content out.
+ if (isSealed(parentBlock)) {
+ return false;
+ }
+
+ const containerAfterPos = ascendToInsertablePos(
+ tr.doc,
+ $pos.after(),
+ state.schema.nodes["blockContainer"],
+ "after",
+ );
+ if (containerAfterPos === undefined) {
+ return false;
+ }
+
+ if (dispatch) {
+ moveBlockOutAndPlaceCaret(tr, {
+ from: blockInfo.block.beforePos,
+ to: blockInfo.block.afterPos,
+ node: blockInfo.block.node,
+ insertAt: containerAfterPos,
+ });
+ tr.scrollIntoView();
+ }
+
+ return true;
+ }),
// Creates a new block and moves the selection to it if the current one is empty, while the selection is also
// empty & at the start of the block.
() =>
commands.command(({ state, dispatch, tr }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { bnBlock: blockContainer, blockContent } = blockInfo;
+ const { block: blockContainer } = blockInfo;
const selectionAtBlockStart =
state.selection.$anchor.parentOffset === 0;
const selectionEmpty =
state.selection.anchor === state.selection.head;
- const blockEmpty = blockContent.node.childCount === 0;
+ const blockEmpty = blockInfo.isContentEmpty;
if (selectionAtBlockStart && selectionEmpty && blockEmpty) {
const newBlockInsertionPos = blockContainer.afterPos;
@@ -889,7 +1066,7 @@ export const KeyboardShortcutsExtension = Extension.create<{
[
state.schema.nodes["paragraph"].createAndFill() ||
undefined,
- blockInfo.childContainer?.node,
+ blockInfo.children?.node,
].filter((node) => node !== undefined),
)!;
@@ -902,10 +1079,10 @@ export const KeyboardShortcutsExtension = Extension.create<{
// Deletes old block's children, as they have been moved to
// the new one.
- if (blockInfo.childContainer) {
+ if (blockInfo.children) {
tr.delete(
- blockInfo.childContainer.beforePos,
- blockInfo.childContainer.afterPos,
+ blockInfo.children.beforePos,
+ blockInfo.children.afterPos,
);
}
}
@@ -920,14 +1097,13 @@ export const KeyboardShortcutsExtension = Extension.create<{
() =>
commands.command(({ state, chain }) => {
const blockInfo = getBlockInfoFromSelection(state);
- if (!blockInfo.isBlockContainer) {
+ if (!blockInfo.hasContent) {
return false;
}
- const { blockContent } = blockInfo;
const selectionAtBlockStart =
state.selection.$anchor.parentOffset === 0;
- const blockEmpty = blockContent.node.childCount === 0;
+ const blockEmpty = blockInfo.isContentEmpty;
if (!blockEmpty) {
chain()
diff --git a/packages/core/src/extensions/tiptap-extensions/UniqueID/UniqueID.ts b/packages/core/src/extensions/tiptap-extensions/UniqueID/UniqueID.ts
index 7ab30b78aa..c6c57a72c9 100644
--- a/packages/core/src/extensions/tiptap-extensions/UniqueID/UniqueID.ts
+++ b/packages/core/src/extensions/tiptap-extensions/UniqueID/UniqueID.ts
@@ -67,9 +67,12 @@ const UniqueID = Extension.create({
setIdAttribute: false,
isWithinEditor: undefined as ((element: Element) => boolean) | undefined,
generateID: () => {
- // Use mock ID if tests are running.
- if (typeof window !== "undefined" && (window as any).__TEST_OPTIONS) {
- const testOptions = (window as any).__TEST_OPTIONS;
+ // Use mock ID if tests are running. Resolved off `globalThis` rather
+ // than a bare `window` so that tests running in the plain `node`
+ // environment (no `window`) still get deterministic IDs.
+ const testHost: any = (globalThis as any).window ?? globalThis;
+ if (testHost.__TEST_OPTIONS) {
+ const testOptions = testHost.__TEST_OPTIONS;
if (testOptions.mockID === undefined) {
testOptions.mockID = 0;
} else {
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index b4f220e1e2..240b0c762a 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1,6 +1,11 @@
export * from "./api/blockManipulation/commands/insertBlocks/insertBlocks.js";
export * from "./api/blockManipulation/commands/replaceBlocks/replaceBlocks.js";
-export * from "./api/blockManipulation/commands/replaceBlocks/util/fixColumnList.js";
+// The rest of the container machinery is on `@blocknote/core/internal`:
+// repair, navigation, UI info, the node groups and the generated node names.
+// `isContainerNode` stays here: it answers a schema-level question ("is this
+// node type a container?") that integrations legitimately ask. It is defined
+// in `children.ts` and re-exported via `fixContainer.ts`.
+export { isContainerNode } from "./api/blockManipulation/containers/fixContainer.js";
export * from "./api/blockManipulation/commands/updateBlock/updateBlock.js";
export * from "./api/exporters/html/externalHTMLExporter.js";
export * from "./api/exporters/html/internalHTMLSerializer.js";
diff --git a/packages/core/src/internal.ts b/packages/core/src/internal.ts
new file mode 100644
index 0000000000..5fe72ad8ff
--- /dev/null
+++ b/packages/core/src/internal.ts
@@ -0,0 +1,52 @@
+/**
+ * `@blocknote/core/internal`
+ *
+ * BlockNote's own machinery, exposed so the packages built on top of core
+ * (`@blocknote/react`, `@blocknote/xl-multi-column`, …) and BlockNote's tests
+ * can use it. Not part of the public API: anything here may change in any
+ * release, without a major version bump or a deprecation.
+ *
+ * The public counterparts stay on the root entrypoint: `isContainerNode` and
+ * the `children` config types (`ChildrenConfig`, `ChildrenAllow`).
+ */
+
+// How a `children` config compiles to a ProseMirror content expression, and
+// the node groups derived from it.
+export {
+ ANY_CONTAINER_GROUP,
+ BLOCK_GROUP_CHILD_GROUP,
+ CHILD_CONTAINER_GROUP,
+ CONTAINER_NODE_PRIORITY,
+ childrenContentExpression,
+ containerNodePriority,
+ resolveChildren,
+} from "./schema/blocks/children.js";
+
+// The attributes a container block's root element carries, and the three ways
+// they get there (node view, HTML serialization, framework render).
+export {
+ applyContainerAttributes,
+ fillContainerAttributes,
+} from "./schema/blocks/containerAttributes.js";
+
+// Repairing a container after its children changed.
+export {
+ fixContainer,
+ fixContainersById,
+ isEmptyContainerChild,
+ removeEmptyChildren,
+} from "./api/blockManipulation/containers/fixContainer.js";
+
+// Position-based navigation through arbitrarily nested containers.
+export {
+ ascendToInsertablePos,
+ descendToInsertionPos,
+ getAncestorContainers,
+ getFirstLeafBlock,
+} from "./api/blockManipulation/containers/containerNav.js";
+
+// What the side menu and drag handle need to know about a schema's containers.
+export {
+ getContainerUIInfo,
+ type ContainerUIInfo,
+} from "./api/blockManipulation/containers/containerUI.js";
diff --git a/packages/core/src/pm-nodes/README.md b/packages/core/src/pm-nodes/README.md
index be57ead212..4577caf841 100644
--- a/packages/core/src/pm-nodes/README.md
+++ b/packages/core/src/pm-nodes/README.md
@@ -99,6 +99,10 @@ We use Prosemirror "groups" to help organize this schema. Here is a list of the
_Note that the last two groups, `bnBlock` and `childContainer`, are not used anywhere in the schema. They are however helpful while programming. For example, we can check whether a node is a `bnBlock`, and then we know it corresponds to a BlockNote Block. Or, we can check whether a node is a `childContainer`, and then we know it's a container of a BlockNote Block's `children`. See `getBlockInfoFromPos` for an example of how this is used._
+## Relation to container blocks
+
+The `blockContainer` + `blockGroup` pair predates the container-blocks API, but it behaves exactly like a container block configured `children: { allow: "any", min: 1, whenEmptied: "unwrap", boundary: "open" }`: any block may nest, a nested `blockGroup` disappears when its last child does, and nothing blocks selections at its edge. The code shares what it can (reading children through `BlockInfo.children`, writing them through `childrenHolder.ts`, the group-membership predicates in `children.ts`), but the node pair itself stays: collapsing regular blocks onto the container mechanism would change the ProseMirror tree of every existing document, which is a document-format migration (collaboration data, HTML round-trip, and snapshots all pin the current shape), not a refactor.
+
## Example document
```xml
diff --git a/packages/core/src/schema/blocks/children.test.ts b/packages/core/src/schema/blocks/children.test.ts
new file mode 100644
index 0000000000..e9cf16c064
--- /dev/null
+++ b/packages/core/src/schema/blocks/children.test.ts
@@ -0,0 +1,172 @@
+// @vitest-environment node
+import { describe, expect, it } from "vite-plus/test";
+
+import { childrenContentExpression, resolveChildren } from "./children.js";
+import type { ChildrenConfig } from "./types.js";
+import { validateChildrenConfigs } from "./validateChildren.js";
+
+// All enforcement happens through the content expression. If this table is
+// right, `allow`/`min`/`max` are enforced by ProseMirror itself.
+const CASES: [string, ChildrenConfig, string][] = [
+ [
+ "any block, at least one (the minimal config)",
+ { allow: "any" },
+ "blockGroupChild+",
+ ],
+ ["any block, possibly none", { allow: "any", min: 0 }, "blockGroupChild*"],
+ [
+ "any block, exactly one",
+ { allow: "any", min: 1, max: 1 },
+ "blockGroupChild",
+ ],
+ ["any block, two or more", { allow: "any", min: 2 }, "blockGroupChild{2,}"],
+ [
+ "any block, two to four",
+ { allow: "any", min: 2, max: 4 },
+ "blockGroupChild{2,4}",
+ ],
+ [
+ "any block, at most one",
+ { allow: "any", min: 0, max: 1 },
+ "blockGroupChild?",
+ ],
+ [
+ "any block, exactly three",
+ { allow: "any", min: 3, max: 3 },
+ "blockGroupChild{3}",
+ ],
+ ["regular blocks only", { allow: "blocks" }, "blockContainer+"],
+ ["one container type only", { allow: ["column"], min: 2 }, "column{2,}"],
+ [
+ "several container types",
+ { allow: ["column", "card"] },
+ "(column | card)+",
+ ],
+ [
+ "any container but no regular blocks",
+ { allow: "containers" },
+ "anyContainer+",
+ ],
+];
+
+describe("childrenContentExpression", () => {
+ it.each(CASES)("%s", (_name, config, expected) => {
+ expect(childrenContentExpression(config)).toBe(expected);
+ });
+});
+
+describe("resolveChildren", () => {
+ // The four `allow` forms and what they desugar to. The compiled expressions
+ // above are a direct function of this table.
+ it.each([
+ ["any", { blocks: true, containers: true }],
+ ["blocks", { blocks: true, containers: [] }],
+ ["containers", { blocks: false, containers: true }],
+ [["column"], { blocks: false, containers: ["column"] }],
+ ] as const)("resolves allow %j", (allow, expected) => {
+ expect(resolveChildren({ allow })).toMatchObject(expected);
+ });
+
+ it("applies the defaults: min 1, unbounded, refill, open", () => {
+ const resolved = resolveChildren({ allow: "any" });
+ expect(resolved.min).toBe(1);
+ expect(resolved.max).toBeUndefined();
+ expect(resolved.whenEmptied).toBe("refill");
+ expect(resolved.boundary).toBe("open");
+ });
+
+ it("returns the same object for the same config, without mutating it", () => {
+ // Downstream code resolves the same config object on every node build and
+ // repair pass, and must never mutate the user's object.
+ const config: ChildrenConfig = { allow: "any", min: 1 };
+ expect(resolveChildren(config)).toBe(resolveChildren(config));
+ expect(config).toEqual({ allow: "any", min: 1 });
+ });
+});
+
+type ContainerFixture = {
+ children: ChildrenConfig;
+ placement?: "anywhere" | "containerOnly";
+};
+
+function configsWith(containers: Record) {
+ return {
+ paragraph: { type: "paragraph", content: "inline" as const },
+ heading: { type: "heading", content: "inline" as const },
+ ...Object.fromEntries(
+ Object.entries(containers).map(([type, { children, placement }]) => [
+ type,
+ { type, content: "none" as const, children, placement },
+ ]),
+ ),
+ };
+}
+
+const validate = (containers: Record) => () =>
+ validateChildrenConfigs(configsWith(containers));
+
+describe("validateChildrenConfigs", () => {
+ it("accepts valid shapes: minimal and columnList-style", () => {
+ expect(validate({ callout: { children: { allow: "any" } } })).not.toThrow();
+ expect(
+ validate({
+ grid: { children: { allow: ["gridCell"], min: 2 } },
+ gridCell: { children: { allow: "any" }, placement: "containerOnly" },
+ }),
+ ).not.toThrow();
+ });
+
+ // Only what nothing else catches. ProseMirror parses `{min,max}` without
+ // comparing the two, so an inverted range silently becomes "exactly min";
+ // and `allow: ["heading"]` compiles to a perfectly valid schema that
+ // quietly restricts nothing, since every regular block is the same node.
+ // Every other way a `children` config can be wrong is reported by
+ // TypeScript at compile time or by ProseMirror with a message of its own.
+ it.each<[string, ContainerFixture["children"], RegExp]>([
+ [
+ "a maximum smaller than the minimum",
+ { allow: "any", min: 3, max: 2 },
+ /greater than or equal/,
+ ],
+ [
+ "a regular block type in the allow array",
+ { allow: ["heading"] },
+ /not yet supported/,
+ ],
+ // The wildcard is a group the container itself joins, so requiring a
+ // container child means requiring a copy of itself: the same stack
+ // overflow as a named cycle, just spelled without a second type.
+ [
+ "a container-only wildcard that requires children",
+ { allow: "containers", min: 1 },
+ /nested inside itself/,
+ ],
+ ])("rejects %s", (_name, children, message) => {
+ expect(validate({ box: { children } })).toThrow(message);
+ });
+
+ // `fillBefore` recurses across node types, so a cycle blows the stack
+ // rather than returning null. It has to be caught before the schema is
+ // built. A mutual reference is fine as soon as one side can be filled with
+ // a paragraph instead.
+ it("rejects a container cycle but accepts a breakable mutual reference", () => {
+ expect(
+ validate({
+ card: { children: { allow: ["cardBody"] } },
+ cardBody: {
+ children: { allow: ["card"] },
+ placement: "containerOnly",
+ },
+ }),
+ ).toThrow(/requires it back/);
+ expect(
+ validate({
+ card: { children: { allow: ["cardBody"] } },
+ cardBody: {
+ children: { allow: "any" },
+ placement: "containerOnly",
+ },
+ }),
+ ).not.toThrow();
+ });
+});
diff --git a/packages/core/src/schema/blocks/children.ts b/packages/core/src/schema/blocks/children.ts
new file mode 100644
index 0000000000..cef124319c
--- /dev/null
+++ b/packages/core/src/schema/blocks/children.ts
@@ -0,0 +1,241 @@
+import type { Node, NodeType, Schema } from "prosemirror-model";
+
+import type { ChildDefault, ChildrenAllow, ChildrenConfig } from "./types.js";
+
+/** A {@link ChildrenConfig} with every default filled in. */
+export type ResolvedChildren = {
+ blocks: boolean;
+ /** `true` for any container type; a (possibly empty) list otherwise. */
+ containers: true | readonly string[];
+ /** What `whenEmptied` compares against. */
+ min: number;
+ max: number | undefined;
+ default: readonly ChildDefault[] | undefined;
+ whenEmptied: "refill" | "unwrap";
+ boundary: "open" | "sealed";
+};
+
+export const CHILD_CONTAINER_GROUP = "childContainer";
+
+export const BLOCK_GROUP_CHILD_GROUP = "blockGroupChild";
+
+// Joined by every container block placeable anywhere (`placement` other than
+// `"containerOnly"`). It's what the `allow` container wildcards (`"any"`,
+// `"containers"`) compile to: a containerOnly type only ever lives where a
+// container names it explicitly, so it stays out of the group.
+export const ANY_CONTAINER_GROUP = "anyContainer";
+
+// Whether `type` is a node that holds child blocks directly: a container
+// block's own node. A container is a child-holding node that is itself a
+// block; `blockGroup` also holds children but is not a block (it's regular
+// blocks' nesting machinery), so the `bnBlock` check excludes it.
+export function isContainerNode(type: NodeType): boolean {
+ return type.isInGroup(CHILD_CONTAINER_GROUP) && type.isInGroup("bnBlock");
+}
+
+/**
+ * The regions a block node resolves into, answered once for every shape so no
+ * other code asks "which shape am I":
+ *
+ * - a container block: its own node holds the children (`childrenHolder.node
+ * === outer`, offset 0), no content region;
+ * - a `blockContainer`: a content head at offset 1, and a `blockGroup`
+ * children holder only once it has children.
+ *
+ * `offset` measures from just before `outer` to just before the region's
+ * node, so with `beforePos` pointing at `outer`, a region's node starts at
+ * `beforePos + offset` and its inside begins at `beforePos + offset + 1` —
+ * uniformly across shapes.
+ */
+export type BlockRegions = {
+ outer: Node;
+ content?: { node: Node; offset: number };
+ childrenHolder?: { node: Node; offset: number };
+};
+
+export function getBlockRegions(node: Node): BlockRegions {
+ if (isContainerNode(node.type)) {
+ return { outer: node, childrenHolder: { node, offset: 0 } };
+ }
+
+ if (node.type.name === "blockContainer") {
+ const content = node.firstChild;
+ if (!content) {
+ throw new Error(
+ "blockContainer node has no content node. This is a bug in BlockNote.",
+ );
+ }
+ const lastChild = node.lastChild;
+ const holder =
+ lastChild !== content &&
+ lastChild &&
+ lastChild.type.isInGroup(CHILD_CONTAINER_GROUP)
+ ? { node: lastChild, offset: 1 + content.nodeSize }
+ : undefined;
+
+ return {
+ outer: node,
+ content: { node: content, offset: 1 },
+ ...(holder ? { childrenHolder: holder } : {}),
+ };
+ }
+
+ throw new Error(
+ `Node "${node.type.name}" is not a block node (container or blockContainer).`,
+ );
+}
+
+// Builds the `blockGroup` node that holds a block's children when converting
+// blocks to nodes. Transaction-level nesting (`sinkItem`, `findWrapping` in the
+// keyboard shortcuts) wraps existing nodes in a `blockGroup` instead, and the
+// document's root `blockGroup` is created by the parsers and `y`/`yjs` utils.
+export function createBlockGroup(
+ schema: Schema,
+ children: readonly Node[],
+): Node {
+ return schema.nodes["blockGroup"].createChecked({}, children as Node[]);
+}
+
+// Whether a node of `type` can sit where regular blocks go: as a direct child
+// of a `blockGroup` or of an `allow: "any"` container. `blockContainer` and
+// every anywhere-placeable container qualify; `containerOnly` containers
+// don't, and must be dissolved into their children before landing in such a
+// slot (see `dissolveContainerOnlyBlocks` in `moveBlocks.ts`).
+export function isBlockGroupInsertable(type: NodeType): boolean {
+ return type.isInGroup(BLOCK_GROUP_CHILD_GROUP);
+}
+
+// Below `blockContainer`'s priority (50) so PM's `fillBefore` picks
+// `blockContainer` first, avoiding recursion through nested containers.
+export const CONTAINER_NODE_PRIORITY = 40;
+
+const CONTAINER_PRIORITY_BAND = { min: 30, max: 49 };
+const DEFAULT_SPEC_PRIORITY = 101;
+
+// Maps `sortByDependencies` priority into the container band (30–49).
+// Preserves relative order but keeps all containers below regular blocks.
+export function containerNodePriority(priority: number | undefined): number {
+ if (priority === undefined) {
+ return CONTAINER_NODE_PRIORITY;
+ }
+
+ const steps = Math.round((priority - DEFAULT_SPEC_PRIORITY) / 10);
+
+ return Math.min(
+ CONTAINER_PRIORITY_BAND.max,
+ Math.max(CONTAINER_PRIORITY_BAND.min, CONTAINER_NODE_PRIORITY + steps),
+ );
+}
+
+const resolvedCache = new WeakMap();
+
+export function resolveChildren(children: ChildrenConfig): ResolvedChildren {
+ const cached = resolvedCache.get(children);
+ if (cached) {
+ return cached;
+ }
+
+ const resolved: ResolvedChildren = {
+ ...resolveAllow(children.allow),
+ min: children.min ?? 1,
+ max: children.max,
+ default: children.default && withoutIds(children.default),
+ whenEmptied: children.whenEmptied ?? "refill",
+ boundary: children.boundary ?? "open",
+ };
+
+ resolvedCache.set(children, resolved);
+ return resolved;
+}
+
+// Clears any id an untyped config wrote into a default, so each copy of the
+// container gets a freshly generated one instead of a shared duplicate.
+function withoutIds(blocks: readonly ChildDefault[]): ChildDefault[] {
+ return blocks.map((block) => ({
+ ...block,
+ id: undefined,
+ ...(block.children ? { children: withoutIds(block.children) } : {}),
+ }));
+}
+
+function resolveAllow(
+ allow: ChildrenAllow,
+): Pick {
+ if (allow === "any") {
+ return { blocks: true, containers: true };
+ }
+ if (allow === "blocks") {
+ return { blocks: true, containers: [] };
+ }
+ if (allow === "containers") {
+ return { blocks: false, containers: true };
+ }
+ return { blocks: false, containers: allow };
+}
+
+/**
+ * Whether `node` belongs to a container with a `"sealed"` boundary, one whose
+ * edge content may never implicitly cross (a table cell rather than a column).
+ * Reads the block config off the node's spec.
+ */
+export function isSealed(node: Node): boolean {
+ const children = node.type.spec.blockConfig?.children;
+ return (
+ children !== undefined && resolveChildren(children).boundary === "sealed"
+ );
+}
+
+export function childrenContentExpression(children: ChildrenConfig): string {
+ const resolved = resolveChildren(children);
+ return allowTerm(resolved) + quantifier(resolved.min, resolved.max);
+}
+
+function allowTerm(resolved: ResolvedChildren): string {
+ // "Anything" is already a group, so use it rather than spelling out a union
+ // that would need rebuilding whenever the schema gains a container type.
+ if (resolved.blocks && resolved.containers === true) {
+ return BLOCK_GROUP_CHILD_GROUP;
+ }
+
+ const terms: string[] = [];
+ // `blockContainer` FIRST: PM's `fillBefore` picks the first matching type in
+ // a union, and filling with `blockContainer` (rather than another container)
+ // keeps auto-fill from recursing through nested containers.
+ if (resolved.blocks) {
+ terms.push("blockContainer");
+ }
+ // The wildcard is the `anyContainer` group, not `childContainer`. The
+ // latter also contains `blockGroup`, which is not a block.
+ if (resolved.containers === true) {
+ terms.push(ANY_CONTAINER_GROUP);
+ } else {
+ terms.push(...resolved.containers);
+ }
+
+ if (terms.length === 0) {
+ throw new Error(
+ "Container `allow` permits nothing. A container must accept at least one block or container type; drop `children` entirely for a block that holds none.",
+ );
+ }
+
+ return terms.length === 1 ? terms[0] : `(${terms.join(" | ")})`;
+}
+
+function quantifier(min: number, max: number | undefined): string {
+ if (max === undefined) {
+ if (min === 0) {
+ return "*";
+ }
+ if (min === 1) {
+ return "+";
+ }
+ return `{${min},}`;
+ }
+ if (min === max) {
+ return max === 1 ? "" : `{${min}}`;
+ }
+ if (min === 0 && max === 1) {
+ return "?";
+ }
+ return `{${min},${max}}`;
+}
diff --git a/packages/core/src/schema/blocks/containerAttributes.ts b/packages/core/src/schema/blocks/containerAttributes.ts
new file mode 100644
index 0000000000..ee01f9cc09
--- /dev/null
+++ b/packages/core/src/schema/blocks/containerAttributes.ts
@@ -0,0 +1,81 @@
+import { camelToDataKebab } from "../../util/string.js";
+import { PropSchema, Props } from "../propTypes.js";
+
+function getContainerAttributes(
+ blockType: string,
+ blockProps: Partial>,
+ propSchema: PSchema,
+ id: string | undefined,
+): Record {
+ const attributes: Record = {};
+
+ for (const [prop, value] of Object.entries(blockProps)) {
+ if (value === undefined || value === propSchema[prop]?.default) {
+ continue;
+ }
+ attributes[camelToDataKebab(prop)] = `${value}`;
+ }
+
+ // Emit the reserved markers after the prop loop so a prop whose name
+ // kebab-cases to `data-node-type` or `data-id` can't overwrite them.
+ attributes["data-node-type"] = blockType;
+ if (id) {
+ attributes["data-id"] = id;
+ }
+
+ return attributes;
+}
+
+export function applyContainerAttributes(
+ element: HTMLElement | undefined | null,
+ blockType: string,
+ blockProps: Partial>,
+ propSchema: PSchema,
+ id: string | undefined,
+) {
+ if (!element) {
+ return;
+ }
+
+ const attributes = getContainerAttributes(
+ blockType,
+ blockProps,
+ propSchema,
+ id,
+ );
+
+ for (const prop of Object.keys(blockProps)) {
+ const attr = camelToDataKebab(prop);
+ if (!(attr in attributes)) {
+ element.removeAttribute(attr);
+ }
+ }
+ for (const [attr, value] of Object.entries(attributes)) {
+ element.setAttribute(attr, value);
+ }
+}
+
+// Like `applyContainerAttributes` but won't overwrite existing attributes.
+export function fillContainerAttributes(
+ element: HTMLElement | undefined | null,
+ blockType: string,
+ blockProps: Partial>,
+ propSchema: PSchema,
+) {
+ if (!element) {
+ return;
+ }
+
+ const attributes = getContainerAttributes(
+ blockType,
+ blockProps,
+ propSchema,
+ undefined,
+ );
+
+ for (const [attr, value] of Object.entries(attributes)) {
+ if (!element.hasAttribute(attr)) {
+ element.setAttribute(attr, value);
+ }
+ }
+}
diff --git a/packages/core/src/schema/blocks/containerParse.browser.test.ts b/packages/core/src/schema/blocks/containerParse.browser.test.ts
new file mode 100644
index 0000000000..31e1a4ebfd
--- /dev/null
+++ b/packages/core/src/schema/blocks/containerParse.browser.test.ts
@@ -0,0 +1,357 @@
+import { Fragment } from "prosemirror-model";
+import {
+ afterAll,
+ beforeAll,
+ beforeEach,
+ describe,
+ expect,
+ it,
+} from "vite-plus/test";
+
+import { BlockNoteSchema } from "../../blocks/BlockNoteSchema.js";
+import { defaultBlockSpecs } from "../../blocks/defaultBlocks.js";
+import { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
+import { createBlockSpec } from "./createSpec.js";
+
+// Every test here goes through `tryParseHTMLToBlocks`, which parses real HTML
+// into a real DOM (`document.implementation.createHTMLDocument` in
+// `api/parsers/html/util/nestedLists.ts`) before ProseMirror's parser ever
+// runs. Parsing HTML is the capability under test, so the whole suite runs
+// against a real browser engine rather than jsdom's.
+
+const renderDiv = () => {
+ const dom = document.createElement("div");
+ return { dom, contentDOM: dom };
+};
+
+// A pure container that recognizes its own external HTML. Before containers
+// went through `getParseRules`, `parse` was silently dropped for them and this
+// produced nothing at all.
+const Card = createBlockSpec(
+ {
+ type: "card" as const,
+ propSchema: { tone: { default: "neutral" } },
+ content: "none",
+ children: { allow: "any" },
+ },
+ {
+ render: renderDiv,
+ parse: (el) =>
+ el.classList.contains("card")
+ ? { tone: el.getAttribute("data-tone") ?? undefined }
+ : undefined,
+ },
+)();
+
+// The same, but taking over the parsing of its own body.
+const Quote = createBlockSpec(
+ {
+ type: "quote" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: "any" },
+ },
+ {
+ render: renderDiv,
+ parse: (el) => (el.tagName === "BLOCKQUOTE" ? {} : undefined),
+ // Returns inline nodes, the natural thing to build from an element, and
+ // relies on `toContainerChildren` to place them.
+ parseContent: ({ el, schema }) =>
+ Fragment.from(schema.text(el.textContent?.trim() || "empty")),
+ },
+)();
+
+// A pure container whose render puts non-content UI text next to the children
+// host, the table-with-controls shape. That text must never round-trip into
+// document content.
+const Widget = createBlockSpec(
+ {
+ type: "widget" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: "any" },
+ },
+ {
+ render: () => {
+ const dom = document.createElement("div");
+ const contentDOM = document.createElement("div");
+ const controls = document.createElement("div");
+ controls.contentEditable = "false";
+ controls.textContent = "UI LABEL";
+ dom.append(contentDOM, controls);
+ return { dom, contentDOM };
+ },
+ },
+)();
+
+const schema = BlockNoteSchema.create().extend({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ card: Card,
+ quote: Quote,
+ widget: Widget,
+ } as const,
+});
+
+let editor: BlockNoteEditor;
+const div = document.createElement("div");
+
+beforeAll(() => {
+ document.body.appendChild(div);
+ editor = BlockNoteEditor.create({ schema }) as any;
+ editor.mount(div);
+});
+
+afterAll(() => {
+ editor._tiptapEditor.destroy();
+ div.remove();
+ editor = undefined as any;
+});
+
+beforeEach(() => {
+ editor.replaceBlocks(editor.document, [
+ { id: "p-0", type: "paragraph", content: "Paragraph 0" },
+ ]);
+});
+
+describe("container `parse`", () => {
+ it("parses an external element into a container, children intact", () => {
+ const blocks = editor.tryParseHTMLToBlocks(
+ '
First
Second
',
+ );
+
+ expect(blocks).toHaveLength(1);
+ expect(blocks[0].type).toBe("card");
+ expect(blocks[0].props.tone).toBe("warning");
+ // No `getContent` is supplied, so ProseMirror parses the children with the
+ // normal block rules and `findWrapping` adds the `blockContainer`s.
+ expect(blocks[0].children.map((child: any) => child.type)).toEqual([
+ "paragraph",
+ "heading",
+ ]);
+ expect(blocks[0].children[0].content).toEqual([
+ { type: "text", text: "First", styles: {} },
+ ]);
+ });
+
+ it("places inline nodes returned by `parseContent` into a child block", () => {
+ const blocks = editor.tryParseHTMLToBlocks(
+ "
Quoted text
",
+ );
+
+ expect(blocks).toHaveLength(1);
+ expect(blocks[0].type).toBe("quote");
+ expect(blocks[0].children.map((child: any) => child.type)).toEqual([
+ "paragraph",
+ ]);
+ expect(blocks[0].children[0].content).toEqual([
+ { type: "text", text: "Quoted text", styles: {} },
+ ]);
+ });
+});
+
+describe("container HTML round-trip", () => {
+ // Regression: internal HTML renders the block's full DOM, so a render with
+ // non-content UI text next to the children host (control buttons, labels)
+ // used to leak that text into the document as extra blocks on re-parse.
+ // The serializer marks the children host with `data-children-of` and the
+ // round-trip rule scopes itself to it.
+ it("excludes a render's non-content UI text from a pure container's round-trip", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ id: "w-0",
+ type: "widget" as const,
+ children: [
+ { id: "w-p-0", type: "paragraph" as const, content: "Inside" },
+ ],
+ },
+ ]);
+
+ const html = editor.blocksToFullHTML(editor.document);
+ expect(html).toContain('data-children-of="widget"');
+ expect(html).toContain("UI LABEL");
+
+ const parsed = editor.tryParseHTMLToBlocks(html);
+ expect(parsed).toHaveLength(1);
+ expect(parsed[0].type).toBe("widget");
+ expect(
+ (parsed[0] as any).children.map((child: any) => [
+ child.type,
+ child.content?.[0]?.text,
+ ]),
+ ).toEqual([["paragraph", "Inside"]]);
+ expect(JSON.stringify(parsed)).not.toContain("UI LABEL");
+ });
+
+ // Same regression on the external HTML path, which is what lands on the
+ // clipboard — so it's the one a paste actually goes through. The marker used
+ // to be emitted only by the internal serializer.
+ it("excludes a render's non-content UI text from external HTML too", () => {
+ editor.replaceBlocks(editor.document, [
+ {
+ id: "w-1",
+ type: "widget" as const,
+ children: [
+ { id: "w-p-1", type: "paragraph" as const, content: "Inside" },
+ ],
+ },
+ ]);
+
+ const html = editor.blocksToHTMLLossy(editor.document);
+ expect(html).toContain('data-children-of="widget"');
+ expect(html).toContain("UI LABEL");
+
+ const parsed = editor.tryParseHTMLToBlocks(html);
+ expect(parsed).toHaveLength(1);
+ expect(parsed[0].type).toBe("widget");
+ expect(
+ (parsed[0] as any).children.map((child: any) => [
+ child.type,
+ child.content?.[0]?.text,
+ ]),
+ ).toEqual([["paragraph", "Inside"]]);
+ expect(JSON.stringify(parsed)).not.toContain("UI LABEL");
+ });
+});
+
+describe("container fragment root", () => {
+ // A container whose render returns a `DocumentFragment` wrapping a single
+ // element and no `rootDOM`, the shape a React render produces. The fragment
+ // itself can't hold attributes, so `containerRootDOM` must resolve to the
+ // wrapped element for the round-trip markers (`data-node-type`, prop
+ // `data-*`) to survive serialization.
+ const Panel = createBlockSpec(
+ {
+ type: "panel" as const,
+ propSchema: { tone: { default: "neutral" } },
+ content: "none",
+ children: { allow: "any" },
+ },
+ {
+ render: () => {
+ const root = document.createElement("div");
+ const fragment = document.createDocumentFragment();
+ fragment.append(root);
+ return { dom: fragment, contentDOM: root };
+ },
+ },
+ )();
+
+ const panelBlocks = [
+ {
+ id: "pn-0",
+ type: "panel" as const,
+ props: { tone: "warning" },
+ children: [{ id: "pn-p-0", type: "paragraph" as const, content: "Body" }],
+ },
+ ];
+
+ const expectRoundTripped = (parsed: any[]) => {
+ expect(parsed).toHaveLength(1);
+ expect(parsed[0].type).toBe("panel");
+ expect(parsed[0].props.tone).toBe("warning");
+ expect(
+ parsed[0].children.map((child: any) => [
+ child.type,
+ child.content?.[0]?.text,
+ ]),
+ ).toEqual([["paragraph", "Body"]]);
+ };
+
+ // Headless: a fragment `dom` is only valid for serialization renders, not
+ // as a mounted node view's root, which ProseMirror requires to be an
+ // element.
+ const makeEditor = () =>
+ BlockNoteEditor.create({
+ schema: BlockNoteSchema.create().extend({
+ blockSpecs: { ...defaultBlockSpecs, panel: Panel } as const,
+ }),
+ }) as BlockNoteEditor;
+
+ it("round-trips a fragment-rendered container through full HTML", () => {
+ const other = makeEditor();
+ try {
+ other.replaceBlocks(other.document, panelBlocks);
+
+ const html = other.blocksToFullHTML(other.document);
+ expect(html).toContain('data-node-type="panel"');
+ expect(html).toContain('data-tone="warning"');
+
+ expectRoundTripped(other.tryParseHTMLToBlocks(html));
+ } finally {
+ other._tiptapEditor.destroy();
+ }
+ });
+
+ it("round-trips a fragment-rendered container through external HTML", () => {
+ const other = makeEditor();
+ try {
+ other.replaceBlocks(other.document, panelBlocks);
+
+ const html = other.blocksToHTMLLossy(other.document);
+ expect(html).toContain('data-node-type="panel"');
+ expect(html).toContain('data-tone="warning"');
+
+ expectRoundTripped(other.tryParseHTMLToBlocks(html));
+ } finally {
+ other._tiptapEditor.destroy();
+ }
+ });
+});
+
+describe("container `runsBefore`", () => {
+ const ambiguous = (type: string) =>
+ createBlockSpec(
+ {
+ type,
+ propSchema: {},
+ content: "none",
+ children: { allow: "any" },
+ } as any,
+ {
+ render: renderDiv,
+ parse: (el: HTMLElement) =>
+ el.classList.contains("shared") ? {} : undefined,
+ },
+ );
+
+ const makeEditor = (betaRunsBefore?: string[]) => {
+ const alpha = ambiguous("alpha")();
+ const beta = ambiguous("beta")();
+ if (betaRunsBefore) {
+ (beta.implementation as any).runsBefore = betaRunsBefore;
+ }
+
+ return BlockNoteEditor.create({
+ schema: BlockNoteSchema.create().extend({
+ blockSpecs: { ...defaultBlockSpecs, alpha, beta } as any,
+ }),
+ }) as BlockNoteEditor;
+ };
+
+ it("orders a container's parse rules before another container's", () => {
+ // Declaration order wins by default; `runsBefore` overrides it.
+ for (const [runsBefore, winner] of [
+ [undefined, "alpha"],
+ [["alpha"], "beta"],
+ ] as const) {
+ const other = makeEditor(runsBefore ? [...runsBefore] : undefined);
+ try {
+ expect(
+ other.tryParseHTMLToBlocks('
x
')[0]
+ .type,
+ ).toBe(winner);
+ } finally {
+ other._tiptapEditor.destroy();
+ }
+ }
+ });
+
+ it("rejects a `runsBefore` naming a regular block", () => {
+ // Container nodes all register below `blockContainer`, so this ordering is
+ // not something the schema could ever produce.
+ expect(() => makeEditor(["paragraph"])).toThrow(
+ /can never be ordered before a regular block/,
+ );
+ });
+});
diff --git a/packages/core/src/schema/blocks/createSpec.ts b/packages/core/src/schema/blocks/createSpec.ts
index b1e54d640a..fe2f3fe500 100644
--- a/packages/core/src/schema/blocks/createSpec.ts
+++ b/packages/core/src/schema/blocks/createSpec.ts
@@ -1,11 +1,13 @@
-import { Editor, Node } from "@tiptap/core";
+import { Editor, Node, NodeViewRendererProps } from "@tiptap/core";
import {
DOMParser,
Fragment,
Node as PMNode,
+ Schema as PMSchema,
TagParseRule,
} from "@tiptap/pm/model";
import { NodeView } from "@tiptap/pm/view";
+import { nodeToBlock } from "../../api/nodeConversions/nodeToBlock.js";
import { mergeParagraphs } from "../../blocks/defaultBlockHelpers.js";
import {
Extension,
@@ -13,9 +15,20 @@ import {
} from "../../editor/BlockNoteExtension.js";
import { nonFormattingMarks } from "../markGroups.js";
import { ignoreNonContentMutations } from "../nodeViewMutations.js";
+import { suggestionMarks } from "../../pm-nodes/suggestionMarks.js";
import { PropSchema } from "../propTypes.js";
import {
+ ANY_CONTAINER_GROUP,
+ BLOCK_GROUP_CHILD_GROUP,
+ CHILD_CONTAINER_GROUP,
+ childrenContentExpression,
+ containerNodePriority,
+} from "./children.js";
+import { applyContainerAttributes } from "./containerAttributes.js";
+import {
+ applyDOMAttributes,
getBlockFromNodeView,
+ isDocumentFragment,
propsToAttributes,
wrapInBlockStructure,
} from "./internal.js";
@@ -45,9 +58,61 @@ export function applyNonSelectableBlockFix(nodeView: NodeView, editor: Editor) {
};
}
-// Function that uses the 'parse' function of a blockConfig to create a
-// TipTap node's `parseHTML` property. This is only used for parsing content
-// from the clipboard.
+// Wraps inline runs from `parseContent` into paragraphs so they fit a
+// container's block content expression.
+function toContainerChildren(fragment: Fragment, schema: PMSchema): Fragment {
+ const out: PMNode[] = [];
+ let inlineRun: PMNode[] = [];
+
+ const flush = () => {
+ if (inlineRun.length === 0) {
+ return;
+ }
+ out.push(schema.nodes["paragraph"].create(null, inlineRun));
+ inlineRun = [];
+ };
+
+ fragment.forEach((child) => {
+ if (child.isInline) {
+ inlineRun.push(child);
+ return;
+ }
+ flush();
+ out.push(child);
+ });
+ flush();
+
+ return Fragment.fromArray(out);
+}
+
+// Finds the element holding a serialized container block's children, marked
+// `data-children-of` by the internal HTML serializer. Returns undefined when
+// no marker belonging to *this* block (rather than a same-typed nested
+// container) is present.
+function findContainerContentElement(
+ el: HTMLElement,
+ config: { type: string },
+): HTMLElement | undefined {
+ const selector = `[data-children-of="${config.type}"]`;
+
+ // The block's root may itself be the children host (a render that passes
+ // its own root to `contentRef`). `querySelectorAll` only sees descendants.
+ if (el.matches(selector)) {
+ return el;
+ }
+
+ for (const host of el.querySelectorAll(selector)) {
+ // Skip hosts of same-typed *nested* containers: this block's own host is
+ // the one with no other container root between it and `el`.
+ if (host.parentElement?.closest("[data-node-type]") === el) {
+ return host;
+ }
+ }
+
+ return undefined;
+}
+
+// Creates `parseHTML` rules for clipboard parsing.
export function getParseRules<
TName extends string,
TProps extends PropSchema,
@@ -55,12 +120,28 @@ export function getParseRules<
>(
config: BlockConfig,
implementation: BlockImplementation,
+ kind: "regular" | "container" = "regular",
) {
+ const isContainer = kind === "container";
+
const rules: TagParseRule[] = [
- {
- tag: "[data-content-type=" + config.type + "]",
- contentElement: ".bn-inline-content",
- },
+ isContainer
+ ? {
+ tag: `[data-node-type=${config.type}]`,
+ // Scope the round-trip parse to the block's content region, so text
+ // the render puts elsewhere in its DOM (button labels, captions,
+ // ...) doesn't parse back as document content. The internal HTML
+ // serializer marks the region with `data-children-of`; HTML without
+ // the marker (older or hand-written) falls back to the whole
+ // element, the previous behavior.
+ contentElement: (el) =>
+ findContainerContentElement(el as HTMLElement, config) ??
+ (el as HTMLElement),
+ }
+ : {
+ tag: "[data-content-type=" + config.type + "]",
+ contentElement: ".bn-inline-content",
+ },
];
if (implementation.parse) {
@@ -81,10 +162,24 @@ export function getParseRules<
},
// Because we do the parsing ourselves, we want to preserve whitespace for content we've parsed
preserveWhitespace: true,
- getContent:
- config.content === "inline" ||
- config.content === "none" ||
- config.content === "plain"
+ getContent: isContainer
+ ? implementation.parseContent
+ ? (node, schema) =>
+ toContainerChildren(
+ implementation.parseContent!({
+ el: node as HTMLElement,
+ schema,
+ }) ??
+ DOMParser.fromSchema(schema).parse(node as HTMLElement, {
+ topNode: schema.nodes["blockGroup"].create(),
+ preserveWhitespace: true,
+ }).content,
+ schema,
+ )
+ : undefined
+ : config.content === "inline" ||
+ config.content === "none" ||
+ config.content === "plain"
? (node, schema) => {
if (implementation.parseContent) {
const result = implementation.parseContent({
@@ -167,137 +262,338 @@ export function getParseRules<
return rules;
}
-// A function to create custom block for API consumers
-// we want to hide the tiptap node from API consumers and provide a simpler API surface instead
-export function addNodeAndExtensionsToSpec<
+function buildContainerNode(
+ blockConfig: BlockConfig,
+ blockImplementation: BlockImplementation,
+ priority?: number,
+) {
+ const children = blockConfig.children!;
+
+ const groups = ["bnBlock", CHILD_CONTAINER_GROUP];
+ if (blockConfig.placement !== "containerOnly") {
+ groups.push(BLOCK_GROUP_CHILD_GROUP, ANY_CONTAINER_GROUP);
+ }
+
+ return Node.create({
+ name: blockConfig.type,
+ content: childrenContentExpression(children),
+ group: groups.join(" "),
+ marks() {
+ return suggestionMarks(this.editor);
+ },
+ selectable: blockImplementation.meta?.selectable ?? true,
+ // Deliberately not `isolating`, not even for a sealed container. PM only
+ // honours that flag while no selection spans the edge, and nothing stops
+ // one being made: given a spanning slice, `Fitter` refuses to open into
+ // the container and wraps the content in a spurious `blockGroup` instead,
+ // so a copy-paste across the edge corrupts the document. Seals bind
+ // editing gestures, and those are enforced by BlockNote's own `isSealed`
+ // guards (see `containerNav.ts` and `KeyboardShortcutsExtension.ts`),
+ // which need no help from the schema.
+ defining: true,
+ priority: containerNodePriority(priority),
+ addAttributes() {
+ return propsToAttributes(blockConfig.propSchema);
+ },
+
+ parseHTML() {
+ return getParseRules(blockConfig, blockImplementation, "container");
+ },
+
+ renderHTML({ HTMLAttributes }) {
+ const dom = document.createElement("div");
+ dom.setAttribute("data-node-type", blockConfig.type);
+ for (const [attribute, value] of Object.entries(HTMLAttributes)) {
+ dom.setAttribute(attribute, value as string);
+ }
+ return { dom, contentDOM: dom };
+ },
+
+ addNodeView() {
+ return (props) =>
+ containerNodeView(blockConfig, blockImplementation, props, {
+ editor: this.options.editor,
+ tiptapEditor: this.editor,
+ blockContentDOMAttributes:
+ this.options.domAttributes?.blockContent || {},
+ });
+ },
+ });
+}
+
+export function containerRootDOM(output: {
+ dom: HTMLElement | DocumentFragment;
+ rootDOM?: HTMLElement | null;
+}): HTMLElement | null {
+ if (output.rootDOM !== undefined) {
+ return output.rootDOM;
+ }
+ if (isDocumentFragment(output.dom)) {
+ // A fragment can't hold attributes, so the round-trip markers
+ // (`data-node-type`, prop `data-*`) would be lost with it as the root.
+ // When it wraps a single element (the shape a React render produces),
+ // that element is the block's real root. A multi-element fragment has no
+ // root to mark, so its container HTML can't parse back.
+ return output.dom.children.length === 1
+ ? (output.dom.children[0] as HTMLElement)
+ : null;
+ }
+ return output.dom;
+}
+
+/**
+ * Marks a container block's rendered root with the attributes its round-trip
+ * parse needs (`data-node-type`, the prop `data-*`s, the id). Pairs the root
+ * resolution with the attribute application, which every render path needs
+ * together.
+ */
+function markContainerRoot(
+ output: { dom: HTMLElement | DocumentFragment; rootDOM?: HTMLElement | null },
+ blockConfig: { type: string; propSchema: PropSchema },
+ block: { props: Record; id: string },
+) {
+ applyContainerAttributes(
+ containerRootDOM(output),
+ blockConfig.type,
+ block.props,
+ blockConfig.propSchema,
+ block.id,
+ );
+}
+
+function containerNodeView(
+ blockConfig: BlockConfig,
+ blockImplementation: BlockImplementation,
+ props: NodeViewRendererProps,
+ context: {
+ editor: unknown;
+ tiptapEditor: Editor;
+ blockContentDOMAttributes: Record;
+ },
+): NodeView {
+ const block = nodeToBlock(props.node, props.view.state.doc);
+
+ const nodeView = blockImplementation.render.call(
+ {
+ blockContentDOMAttributes: context.blockContentDOMAttributes,
+ props,
+ renderType: "nodeView",
+ propSchema: blockConfig.propSchema,
+ },
+ block as any,
+ context.editor as any,
+ );
+
+ markContainerRoot(nodeView, blockConfig, block as any);
+
+ const typedNodeView = nodeView as unknown as NodeView;
+
+ // Mark the children host in the live DOM, mirroring what the internal HTML
+ // serializer emits, so the container's round-trip parse rule can scope
+ // itself to it (`contentElement` in `getParseRules`) when ProseMirror
+ // re-reads editor DOM.
+ if (typedNodeView.contentDOM) {
+ (typedNodeView.contentDOM as HTMLElement).setAttribute(
+ "data-children-of",
+ blockConfig.type,
+ );
+ }
+
+ if (blockImplementation.meta?.selectable === false) {
+ applyNonSelectableBlockFix(typedNodeView, context.tiptapEditor);
+ }
+
+ ignoreNonContentMutations(typedNodeView);
+
+ const update = typedNodeView.update?.bind(typedNodeView);
+ if (update) {
+ typedNodeView.update = (node, decorations, innerDecorations) => {
+ if (node.type.name !== blockConfig.type) {
+ return false;
+ }
+ if (update(node, decorations, innerDecorations) === false) {
+ return false;
+ }
+ markContainerRoot(nodeView, blockConfig, {
+ props: nodeToBlock(node, props.view.state.doc).props as any,
+ id: node.attrs.id,
+ });
+ return true;
+ };
+ }
+
+ return typedNodeView;
+}
+
+function buildRegularNode<
TName extends string,
TProps extends PropSchema,
TContent extends "inline" | "none" | "table" | "plain",
>(
blockConfig: BlockConfig,
blockImplementation: BlockImplementation,
- extensions?: (ExtensionFactoryInstance | Extension)[],
priority?: number,
-): LooseBlockSpec {
- const node =
- ((blockImplementation as any).node as Node) ||
- Node.create({
- name: blockConfig.type,
- content: (blockConfig.content === "inline"
- ? "inline*"
- : blockConfig.content === "plain"
- ? "text*"
- : blockConfig.content === "none"
- ? ""
- : blockConfig.content) as TContent extends "inline"
- ? "inline*"
- : TContent extends "plain"
- ? "text*"
- : "",
- // "plain" blocks hold unstyled text, so they disallow formatting marks.
- // They still allow the non-formatting marks (comments and
- // suggestions/diffs) — those annotate content without changing it and are
- // ignored by the block model. `nonFormattingMarks` resolves the group only
- // when at least one such mark is registered, so a plain block in an editor
- // without any of them doesn't reference an empty (unknown) mark group.
- marks() {
- return blockConfig.content === "plain"
- ? nonFormattingMarks(this.editor)
- : undefined;
- },
- group: "blockContent",
- selectable: blockImplementation.meta?.selectable ?? true,
- isolating: blockImplementation.meta?.isolating ?? true,
- code: blockImplementation.meta?.code ?? false,
- defining: blockImplementation.meta?.defining ?? true,
- priority,
- addAttributes() {
- return propsToAttributes(blockConfig.propSchema);
- },
+) {
+ return Node.create({
+ name: blockConfig.type,
+ content: (blockConfig.content === "inline"
+ ? "inline*"
+ : blockConfig.content === "plain"
+ ? "text*"
+ : blockConfig.content === "none"
+ ? ""
+ : blockConfig.content) as TContent extends "inline"
+ ? "inline*"
+ : TContent extends "plain"
+ ? "text*"
+ : "",
+ // "plain" blocks hold unstyled text, so they disallow formatting marks.
+ // They still allow the non-formatting marks (comments and
+ // suggestions/diffs), which annotate content without changing it and are
+ // ignored by the block model. `nonFormattingMarks` resolves the group only
+ // when at least one such mark is registered, so a plain block in an editor
+ // without any of them doesn't reference an empty (unknown) mark group.
+ marks() {
+ return blockConfig.content === "plain"
+ ? nonFormattingMarks(this.editor)
+ : undefined;
+ },
+ group: "blockContent",
+ selectable: blockImplementation.meta?.selectable ?? true,
+ isolating: blockImplementation.meta?.isolating ?? true,
+ code: blockImplementation.meta?.code ?? false,
+ defining: blockImplementation.meta?.defining ?? true,
+ priority,
+ addAttributes() {
+ return propsToAttributes(blockConfig.propSchema);
+ },
- parseHTML() {
- return getParseRules(blockConfig, blockImplementation);
- },
+ parseHTML() {
+ return getParseRules(blockConfig, blockImplementation);
+ },
- renderHTML({ HTMLAttributes }) {
- // renderHTML is used for copy/pasting content from the editor back into
- // the editor, so we need to make sure the `blockContent` element is
- // structured correctly as this is what's used for parsing blocks. We
- // just render a placeholder div inside as the `blockContent` element
- // already has all the information needed for proper parsing.
- const div = document.createElement("div");
- return wrapInBlockStructure(
+ renderHTML({ HTMLAttributes }) {
+ // renderHTML is used for copy/pasting content from the editor back into
+ // the editor, so we need to make sure the `blockContent` element is
+ // structured correctly as this is what's used for parsing blocks. We
+ // just render a placeholder div inside as the `blockContent` element
+ // already has all the information needed for proper parsing.
+ const div = document.createElement("div");
+ return wrapInBlockStructure(
+ {
+ dom: div,
+ contentDOM:
+ blockConfig.content === "inline" || blockConfig.content === "plain"
+ ? div
+ : undefined,
+ },
+ blockConfig.type,
+ {},
+ blockConfig.propSchema,
+ blockImplementation.meta?.fileBlockAccept !== undefined,
+ HTMLAttributes,
+ );
+ },
+
+ addNodeView() {
+ return (props) => {
+ // Gets the BlockNote editor instance
+ const editor = this.options.editor;
+ // Gets the block. Resolving this can't rely on `getPos()` alone:
+ // node views are constructed part-way through ProseMirror's
+ // reconciliation, where positions don't always line up with
+ // `view.state.doc` yet (see `getBlockFromNodeView`).
+ const block = getBlockFromNodeView(
+ props.getPos,
+ props.node,
+ props.view.state.doc,
+ );
+ // Gets the custom HTML attributes for `blockContent` nodes
+ const blockContentDOMAttributes =
+ this.options.domAttributes?.blockContent || {};
+
+ const nodeView = blockImplementation.render.call(
{
- dom: div,
- contentDOM:
- blockConfig.content === "inline" ||
- blockConfig.content === "plain"
- ? div
- : undefined,
+ blockContentDOMAttributes,
+ props,
+ renderType: "nodeView",
+ propSchema: blockConfig.propSchema,
},
- blockConfig.type,
- {},
- blockConfig.propSchema,
- blockImplementation.meta?.fileBlockAccept !== undefined,
- HTMLAttributes,
+ block as any,
+ editor as any,
);
- },
-
- addNodeView() {
- return (props) => {
- // Gets the BlockNote editor instance
- const editor = this.options.editor;
- // Gets the block. Resolving this can't rely on `getPos()` alone —
- // node views are constructed part-way through ProseMirror's
- // reconciliation, where positions don't always line up with
- // `view.state.doc` yet (see `getBlockFromNodeView`).
- const block = getBlockFromNodeView(
- props.getPos,
- props.node,
- props.view.state.doc,
- );
- // Gets the custom HTML attributes for `blockContent` nodes
- const blockContentDOMAttributes =
- this.options.domAttributes?.blockContent || {};
-
- const nodeView = blockImplementation.render.call(
- {
- blockContentDOMAttributes,
- props,
- renderType: "nodeView",
- propSchema: blockConfig.propSchema,
- },
- block as any,
- editor as any,
- );
-
- // Cast needed because render returns `dom: HTMLElement | DocumentFragment`
- // but tiptap's NodeView expects `dom: HTMLElement`
- const typedNodeView = nodeView as unknown as NodeView;
- if (blockImplementation.meta?.selectable === false) {
- applyNonSelectableBlockFix(typedNodeView, this.editor);
- }
+ // Cast needed because render returns `dom: HTMLElement | DocumentFragment`
+ // but tiptap's NodeView expects `dom: HTMLElement`
+ const typedNodeView = nodeView as unknown as NodeView;
- // Ignores DOM mutations that don't affect the block's content, so
- // that browser extensions which rewrite the DOM (e.g. Dark Reader)
- // can't trigger an infinite re-render loop that freezes the tab.
- ignoreNonContentMutations(typedNodeView);
+ if (blockImplementation.meta?.selectable === false) {
+ applyNonSelectableBlockFix(typedNodeView, this.editor);
+ }
- // See explanation for why `update` is not implemented for NodeViews
- // https://github.com/TypeCellOS/BlockNote/pull/1904#discussion_r2313461464
- // https://github.com/TypeCellOS/BlockNote/issues/220
- return typedNodeView;
- };
- },
- });
+ // Ignores DOM mutations that don't affect the block's content, so
+ // that browser extensions which rewrite the DOM (e.g. Dark Reader)
+ // can't trigger an infinite re-render loop that freezes the tab.
+ ignoreNonContentMutations(typedNodeView);
+
+ // See explanation for why `update` is not implemented for NodeViews
+ // https://github.com/TypeCellOS/BlockNote/pull/1904#discussion_r2313461464
+ // TODO: in a future version, we might want to implement updates so that
+ // vanilla blocks don't always re-render entirely (https://github.com/TypeCellOS/BlockNote/issues/220)
+ return typedNodeView;
+ };
+ },
+ });
+}
- if (node.name !== blockConfig.type) {
+// A function to create custom block for API consumers
+// we want to hide the tiptap node from API consumers and provide a simpler API surface instead
+export function addNodeAndExtensionsToSpec<
+ TName extends string,
+ TProps extends PropSchema,
+ TContent extends "inline" | "none" | "table" | "plain",
+>(
+ blockConfig: BlockConfig,
+ blockImplementation: BlockImplementation,
+ extensions?: (ExtensionFactoryInstance | Extension)[],
+ priority?: number,
+): LooseBlockSpec {
+ // A `children` config combined with any `content` other than `"none"` is
+ // rejected by `validateChildrenConfigs` when the schema is built.
+ const childrenConfig = blockConfig.children;
+
+ const isContainer = childrenConfig !== undefined;
+
+ const builtNode: Node = (blockImplementation as any).node
+ ? ((blockImplementation as any).node as Node)
+ : childrenConfig
+ ? buildContainerNode(
+ blockConfig as unknown as BlockConfig,
+ blockImplementation as unknown as BlockImplementation<
+ TName,
+ TProps,
+ "none"
+ >,
+ priority,
+ )
+ : buildRegularNode(blockConfig, blockImplementation, priority);
+
+ if (builtNode.name !== blockConfig.type) {
throw new Error(
"Node name does not match block type. This is a bug in BlockNote.",
);
}
+ // The block's config is stored on its node's PM spec
+ // (`NodeSpec.blockConfig`), so code holding a bare `Node` can consult it
+ // without an editor or schema reference. (`extendNodeSchema` hooks run
+ // for every node in the schema, hence the name gate.)
+ const node = builtNode.extend({
+ extendNodeSchema(extension) {
+ return extension.name === builtNode.name ? { blockConfig } : {};
+ },
+ });
+
return {
config: blockConfig,
implementation: {
@@ -307,7 +603,7 @@ export function addNodeAndExtensionsToSpec<
const blockContentDOMAttributes =
node.options.domAttributes?.blockContent || {};
- return blockImplementation.render.call(
+ const output = blockImplementation.render.call(
{
blockContentDOMAttributes,
props: undefined,
@@ -317,6 +613,12 @@ export function addNodeAndExtensionsToSpec<
block as any,
editor as any,
);
+
+ if (isContainer) {
+ markContainerRoot(output, blockConfig, block as any);
+ }
+
+ return output;
},
// TODO: this should not have wrapInBlockStructure and generally be a lot simpler
// post-processing in externalHTMLExporter should not be necessary
@@ -324,7 +626,7 @@ export function addNodeAndExtensionsToSpec<
const blockContentDOMAttributes =
node.options.domAttributes?.blockContent || {};
- return (
+ const output =
blockImplementation.toExternalHTML?.call(
{ blockContentDOMAttributes, propSchema: blockConfig.propSchema },
block as any,
@@ -340,8 +642,13 @@ export function addNodeAndExtensionsToSpec<
},
block as any,
editor as any,
- )
- );
+ );
+
+ if (output && isContainer) {
+ markContainerRoot(output, blockConfig, block as any);
+ }
+
+ return output;
},
},
extensions,
@@ -452,6 +759,8 @@ export function createBlockSpec<
: extensionsOrCreator
: undefined;
+ const isContainer = blockConfig.children !== undefined;
+
return {
config: blockConfig,
implementation: {
@@ -470,6 +779,11 @@ export function createBlockSpec<
return undefined;
}
+ if (isContainer) {
+ applyDOMAttributes(output.dom, this.blockContentDOMAttributes);
+ return output;
+ }
+
return wrapInBlockStructure(
output,
block.type,
@@ -489,6 +803,11 @@ export function createBlockSpec<
editor as any,
);
+ if (isContainer) {
+ applyDOMAttributes(output.dom, this.blockContentDOMAttributes);
+ return output;
+ }
+
const nodeView = wrapInBlockStructure(
output,
block.type,
diff --git a/packages/core/src/schema/blocks/internal.ts b/packages/core/src/schema/blocks/internal.ts
index cfd17b9d11..295059abcc 100644
--- a/packages/core/src/schema/blocks/internal.ts
+++ b/packages/core/src/schema/blocks/internal.ts
@@ -6,7 +6,7 @@ import type { ExtensionFactoryInstance } from "../../editor/BlockNoteExtension.j
import { mergeCSSClasses } from "../../util/browser.js";
import { camelToDataKebab } from "../../util/string.js";
import { PropSchema, Props } from "../propTypes.js";
-import { LooseBlockSpec } from "./types.js";
+import { BlockConfig, ChildrenConfig, LooseBlockSpec } from "./types.js";
// Function that uses the 'propSchema' of a blockConfig to create a TipTap
// node's `addAttributes` property.
@@ -157,6 +157,39 @@ export function getBlockFromNodeView(
}
}
+/**
+ * `Node.DOCUMENT_FRAGMENT_NODE`, inlined. Server-side rendering shims only
+ * `document` and `window` onto the global scope, so `Node` and
+ * `DocumentFragment` are undefined there and `instanceof` throws.
+ */
+const DOCUMENT_FRAGMENT_NODE = 11;
+
+export function isDocumentFragment(
+ node: HTMLElement | DocumentFragment,
+): node is DocumentFragment {
+ return node.nodeType === DOCUMENT_FRAGMENT_NODE;
+}
+
+/**
+ * Applies custom `blockContent` DOM attributes to an element, merging (rather
+ * than overwriting) its class list.
+ */
+export function applyDOMAttributes(
+ dom: HTMLElement | DocumentFragment,
+ domAttributes: Record | undefined,
+) {
+ if (!domAttributes || isDocumentFragment(dom)) {
+ return;
+ }
+ for (const [attr, value] of Object.entries(domAttributes)) {
+ if (attr === "class") {
+ dom.className = mergeCSSClasses(dom.className, value);
+ } else {
+ dom.setAttribute(attr, value);
+ }
+ }
+}
+
// Function that wraps the `dom` element returned from 'blockConfig.render' in a
// `blockContent` div, which contains the block type and props as HTML
// attributes. If `blockConfig.render` also returns a `contentDOM`, it also adds
@@ -232,6 +265,12 @@ export function createBlockSpecFromTiptapNode<
node: Node;
type: string;
content: "inline" | "table" | "none" | "plain";
+ // Declares the block's container semantics (child counts/repair etc.)
+ // even though the node itself is hand-written. The node's own content
+ // expression stays authoritative for the PM schema, while BlockNote-level
+ // behavior (repair, seeding, validation) reads this config.
+ children?: ChildrenConfig;
+ placement?: BlockConfig["placement"];
},
P extends PropSchema,
>(
@@ -244,6 +283,10 @@ export function createBlockSpecFromTiptapNode<
type: config.type as T["type"],
content: config.content,
propSchema,
+ ...(config.children !== undefined ? { children: config.children } : {}),
+ ...(config.placement !== undefined
+ ? { placement: config.placement }
+ : {}),
},
implementation: {
node: config.node,
diff --git a/packages/core/src/schema/blocks/types.ts b/packages/core/src/schema/blocks/types.ts
index 8d7e203e61..4c010a57ef 100644
--- a/packages/core/src/schema/blocks/types.ts
+++ b/packages/core/src/schema/blocks/types.ts
@@ -1,11 +1,7 @@
/** Define the main block types **/
// import { Extension, Node } from "@tiptap/core";
import type { Node, NodeViewRendererProps } from "@tiptap/core";
-import type {
- Fragment,
- Node as ProsemirrorNode,
- Schema,
-} from "prosemirror-model";
+import type { Fragment, Node as PMNode, Schema } from "prosemirror-model";
import type { ViewMutationRecord } from "prosemirror-view";
import type { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
import type {
@@ -67,6 +63,16 @@ export interface BlockConfigMeta<
*/
isolating?: boolean;
+ /**
+ * Whether this block type gets a side menu drag handle (and can be dragged
+ * by it). Applies to any block type, container or not: e.g. a
+ * "locked" block can opt out of dragging entirely. A block that opts out is
+ * skipped when looking for a drag handle, so the handle falls through to the
+ * nearest draggable ancestor.
+ * @default true
+ */
+ draggable?: boolean;
+
/**
* Enables syntax highlighting of the contents of the block with the result of this callback
*/
@@ -80,6 +86,105 @@ export interface BlockConfigMeta<
hasPreview?: boolean;
}
+/**
+ * What may appear as a child of a container block.
+ *
+ * - `"any"`: any regular block, or any container block placeable anywhere.
+ * - `"blocks"`: regular (non-container) blocks only. This cannot be narrowed
+ * to specific block types: every regular block is the *same* ProseMirror
+ * node (`blockContainer`), so paragraphs, headings and code blocks are
+ * indistinguishable at the node level.
+ * - `"containers"`: any container block placeable anywhere, no regular blocks.
+ * - `readonly string[]`: only these types, enforced exactly by the schema.
+ * Today the array may only name *container* block types (naming a regular
+ * block type is a startup error); per-type regular-block filtering can be
+ * added to this same form later, with no API change.
+ *
+ * The wildcards (`"any"`, `"containers"`) never include
+ * `placement: "containerOnly"` types. Those appear only where a parent names
+ * them explicitly in an array.
+ */
+export type ChildrenAllow = "any" | "blocks" | "containers" | readonly string[];
+
+/**
+ * One entry of {@link ChildrenConfig.default}: a partial block with no `id`.
+ *
+ * A default describes every copy of the container, but an id names one block
+ * in one document. An id written here would be stamped onto every copy, so
+ * `id` is rejected at the type level and ignored at runtime.
+ */
+export type ChildDefault = Omit, "id"> & {
+ id?: never;
+ children?: ChildDefault[];
+};
+
+/**
+ * Marks a block as a *container*: a block whose body is other blocks, exposed
+ * as `block.children` at runtime.
+ *
+ * The config describes one uniform body, semantically a single implicit
+ * slot. Ordered multi-slot bodies (a `sequence` of slots) can be added later
+ * as a sibling form.
+ */
+export type ChildrenConfig = {
+ /** What may appear as a child. See {@link ChildrenAllow}. */
+ allow: ChildrenAllow;
+ /** @default 1 */
+ min?: number;
+ /** @default unbounded */
+ max?: number;
+ /**
+ * Children to create the container with when it is inserted without an
+ * explicit `children` array. When omitted, BlockNote fills the container
+ * with whatever its content expression requires (usually one empty
+ * paragraph), so a container can never be created in an invalid state.
+ *
+ * Also the seed that `whenEmptied: "refill"` tops up from, when children
+ * drop below `min`.
+ */
+ default?: readonly ChildDefault[];
+ /**
+ * What happens as children are emptied out (Backspace merges the last child
+ * away, `removeBlocks` deletes children, ...) and fewer than `min` non-empty
+ * children remain:
+ *
+ * - `"refill"` (the default): drop the emptied children and top the
+ * container back up to `min`, seeding the missing positions from the
+ * unconsumed tail of `default` (falling back to empty blocks when
+ * `default` is absent or too short).
+ * - `"unwrap"`: drop the emptied children and replace the container with its
+ * survivors, or remove it entirely when none remain. Column lists use this
+ * so emptied columns disappear and a one-column list unwraps.
+ *
+ * Coupled to the child count, so it lives here rather than in `meta`:
+ * ProseMirror's schema fitting always pads a container back up to its
+ * minimum with empty children, so "effectively below the minimum" can only
+ * be detected by discounting those.
+ * @default "refill"
+ */
+ whenEmptied?: "refill" | "unwrap";
+ /**
+ * Whether editing gestures cross the container's edge.
+ *
+ * - `"open"` (the default): they do. Right for a callout or a column list,
+ * where the container is a region of the same flow of text.
+ * - `"sealed"`: they don't, like a table cell. The caret doesn't enter via
+ * arrows/Backspace, and the block selects as a unit. Key-agnostic, so
+ * compartments need no hand-written keyboard handlers.
+ *
+ * A seal binds gestures only. A text selection may span any edge, and the
+ * block manipulation API (`insertBlocks` etc.) ignores seals entirely.
+ * @default "open"
+ */
+ boundary?: "open" | "sealed";
+};
+
+// `ResolvedChildren`, the fully-defaulted, desugared shape a `ChildrenConfig`
+// compiles to, is internal machinery, not part of the consumer-facing config
+// surface. So it lives in `./children.ts` (which is not re-exported wholesale)
+// rather than here, where `export *` would leak it onto `@blocknote/core`'s
+// public types.
+
/**
* BlockConfig contains the "schema" info about a Block type
* i.e. what props it supports, what content it supports, etc.
@@ -106,8 +211,44 @@ export interface BlockConfig<
* The content that the block supports
*/
content: C;
- // TODO: how do you represent things that have nested content?
- // e.g. tables, alerts (with title & content)
+ /**
+ * Makes this a *container* block: a block whose body is other blocks,
+ * exposed on `block.children`. The block's `render` places them via
+ * `contentRef` (React) / `contentDOM` (vanilla), the same way it would place
+ * inline content.
+ *
+ * Only `content: "none"` may be combined with `children`; a container
+ * block has no content of its own. Combining `children` with any other
+ * `content` is a schema-creation error. (Content-bearing containers may be
+ * supported in a future version, at which point this restriction lifts.)
+ *
+ * `children: { allow: "any" }` is the minimal container.
+ */
+ children?: ChildrenConfig;
+ /**
+ * Where this block may be placed.
+ *
+ * - `"anywhere"` (default): anywhere a regular block goes, the document
+ * root or nested under any other block.
+ * - `"containerOnly"`: only inside a container that names this type in its
+ * `children.allow` array (e.g. a `column` inside a `columnList`).
+ *
+ * Only meaningful for container blocks; regular blocks are always placeable
+ * anywhere.
+ */
+ placement?: "anywhere" | "containerOnly";
+}
+
+declare module "prosemirror-model" {
+ interface NodeSpec {
+ /**
+ * The config of the BlockNote block this node was built from, so code
+ * holding a bare `Node` can read block-level facts (children config,
+ * placement, ...) without an editor or schema reference. Set on every
+ * node built from a block spec.
+ */
+ blockConfig?: BlockConfig;
+ }
}
/**
@@ -227,9 +368,11 @@ export type LooseBlockSpec<
) => {
dom: HTMLElement | DocumentFragment;
contentDOM?: HTMLElement;
+ /** See {@link BlockImplementation.render}'s `rootDOM`. */
+ rootDOM?: HTMLElement | null;
ignoreMutation?: (mutation: ViewMutationRecord) => boolean;
- update?: (node: ProsemirrorNode) => boolean;
destroy?: () => void;
+ update?: (node: PMNode) => boolean | void;
};
toExternalHTML?: (
block: any,
@@ -286,9 +429,11 @@ export type BlockSpecs = {
) => {
dom: HTMLElement | DocumentFragment;
contentDOM?: HTMLElement;
+ /** See {@link BlockImplementation.render}'s `rootDOM`. */
+ rootDOM?: HTMLElement | null;
ignoreMutation?: (mutation: ViewMutationRecord) => boolean;
- update?: (node: ProsemirrorNode) => boolean;
destroy?: () => void;
+ update?: (node: PMNode) => boolean | void;
};
toExternalHTML?: (
block: any,
@@ -590,19 +735,31 @@ export type BlockImplementation<
) => {
dom: HTMLElement | DocumentFragment;
contentDOM?: HTMLElement;
+ /**
+ * The block author's own root element, when it isn't `dom` itself. React
+ * renders a node view through wrapper elements of its own, so the element
+ * ProseMirror is handed is not the one the author wrote. This points at
+ * the author's element, which container attributes (`data-node-type`,
+ * `data-id`, prop `data-*`) are applied to.
+ * @default dom
+ */
+ rootDOM?: HTMLElement | null;
ignoreMutation?: (mutation: ViewMutationRecord) => boolean;
+ destroy?: () => void;
/**
- * Called by ProseMirror when this block's node is updated (e.g. its content
- * or props change). Return `true` to handle the update in place - keeping
- * the existing DOM - or `false` to have the node view recreated via
- * `render`. When omitted, ProseMirror keeps the node view and reconciles its
- * `contentDOM` in place as long as the node type stays the same.
+ * Optional NodeView update hook. Called when the underlying ProseMirror
+ * node's attributes change (or its decorations change). Return `false` to
+ * tell ProseMirror to destroy and recreate the NodeView (i.e. re-run
+ * `render` from scratch). Return `true` (or `undefined`) when you have
+ * patched `dom` in-place and PM should keep the existing view.
*
- * Useful for blocks whose `render` builds custom DOM that needs to stay in
- * sync with the node (e.g. a code block rendering a preview of its content).
+ * Only honored for container blocks (blocks with `children`), where
+ * recreating the node view would remount every child block: e.g. column
+ * resizing patches widths in place through this hook. Non-container
+ * blocks always recreate on attr changes (see
+ * https://github.com/TypeCellOS/BlockNote/pull/1904#discussion_r2313461464).
*/
- update?: (node: ProsemirrorNode) => boolean;
- destroy?: () => void;
+ update?: (node: PMNode) => boolean | void;
};
/**
diff --git a/packages/core/src/schema/blocks/validateChildren.ts b/packages/core/src/schema/blocks/validateChildren.ts
new file mode 100644
index 0000000000..a1495f21ba
--- /dev/null
+++ b/packages/core/src/schema/blocks/validateChildren.ts
@@ -0,0 +1,153 @@
+import { resolveChildren } from "./children.js";
+import type { BlockConfig, ChildrenConfig } from "./types.js";
+
+type ValidatableConfig = Pick & {
+ children?: ChildrenConfig;
+ placement?: BlockConfig["placement"];
+ /** From the block's implementation rather than its config. */
+ runsBefore?: string[];
+};
+
+/**
+ * Validates the parts of a container block's declaration that nothing else
+ * catches.
+ *
+ * Deliberately narrow: TypeScript already rejects malformed configs at compile
+ * time, and ProseMirror already reports unknown types, unsatisfiable content
+ * expressions and unfillable containers with usable messages of its own. Only
+ * the cases below fail silently or catastrophically without help.
+ *
+ * @param blockConfigs The configs of every block in the schema, keyed by type.
+ */
+export function validateChildrenConfigs(
+ blockConfigs: Record,
+) {
+ const isContainerBlockType = (blockType: string) =>
+ blockConfigs[blockType]?.children !== undefined;
+
+ for (const [type, config] of Object.entries(blockConfigs)) {
+ if (!config.children) {
+ continue;
+ }
+
+ const { blocks, min, max, containers } = resolveChildren(config.children);
+
+ // ProseMirror's content-expression parser never compares the two, so an
+ // inverted range is silently read as "exactly `min`".
+ if (max !== undefined && max < min) {
+ fail(
+ type,
+ `maximum child count (${max}) must be greater than or equal to the minimum (${min}).`,
+ );
+ }
+
+ // `allow: "containers"` compiles to a group that the container itself is
+ // in, so "must hold a container" includes "must hold a copy of itself".
+ // ProseMirror fills that by nesting the container inside itself until the
+ // stack overflows, and which type it picks depends on the order block
+ // types were registered in — so this is rejected rather than left to
+ // chance. The cycle check below covers the same shape for named types.
+ if (containers === true && !blocks && min >= 1) {
+ fail(
+ type,
+ 'a container that allows only containers (`allow: "containers"`) cannot require any, as it counts as a container itself and would be nested inside itself forever. ' +
+ 'Use `min: 0`, allow regular blocks as well (`allow: "any"`), or name the container types it accepts.',
+ );
+ }
+
+ // An `allow` array is exact by construction: each named type is its own
+ // ProseMirror node. Every *regular* block, by contrast, is the same node
+ // (`blockContainer`), so naming one here compiles to a valid schema that
+ // quietly fails to restrict anything.
+ if (containers !== true) {
+ for (const allowed of containers) {
+ if (allowed in blockConfigs && !isContainerBlockType(allowed)) {
+ fail(
+ type,
+ `\`allow\` contains "${allowed}", which is a regular block, not a container block. ` +
+ "Restricting which regular block types a container accepts is not yet supported, as every regular block is the same ProseMirror node. " +
+ 'Use `allow: "blocks"` to accept all regular blocks, or name only container block types.',
+ );
+ }
+ }
+ }
+
+ // ProseMirror never sees `runsBefore`, so an entry it cannot act on is a
+ // silent no-op rather than an error. Container nodes register in a
+ // priority band below every regular block (see `containerNodePriority`),
+ // so ordering a container ahead of one is not something the schema could
+ // ever produce.
+ for (const other of config.runsBefore ?? []) {
+ // "default" is `sortByDependencies`' reference point rather than a block
+ // type. A type that isn't in the schema is not this check's concern.
+ if (other === "default" || !(other in blockConfigs)) {
+ continue;
+ }
+
+ if (!isContainerBlockType(other)) {
+ throw new Error(
+ `Invalid \`runsBefore\` for container block "${type}": it names "${other}", which is a regular block, not a container block. ` +
+ "Container block nodes always register below regular ones, so a container can never be ordered before a regular block. " +
+ "`runsBefore` on a container can only name other container blocks.",
+ );
+ }
+ }
+ }
+
+ validateNoCycles(blockConfigs, isContainerBlockType);
+}
+
+function fail(type: string, message: string): never {
+ throw new Error(
+ `Invalid \`children\` config for block "${type}": ${message}`,
+ );
+}
+
+/**
+ * A container that requires a child which in turn requires it back can never
+ * be created: ProseMirror's `fillBefore` recurses across node types and
+ * overflows the stack rather than returning `null`. So this has to be caught
+ * statically, before the schema is built.
+ */
+function validateNoCycles(
+ blockConfigs: Record,
+ isContainerBlockType: (blockType: string) => boolean,
+) {
+ // A container that allows regular blocks can always be filled with a plain
+ // paragraph, so it never forces recursion. Only container-only lists do.
+ const requiredContainers = (type: string): string[] => {
+ const children = blockConfigs[type].children;
+ if (!children) {
+ return [];
+ }
+ const resolved = resolveChildren(children);
+ return resolved.min >= 1 && !resolved.blocks && resolved.containers !== true
+ ? resolved.containers.filter(isContainerBlockType)
+ : [];
+ };
+
+ const state = new Map();
+
+ const visit = (type: string, path: string[]) => {
+ const seen = state.get(type);
+ if (seen === "done") {
+ return;
+ }
+ if (seen === "visiting") {
+ fail(
+ type,
+ `it requires a child that requires it back (${[...path, type].join(" -> ")}), so it could never be created. Allow regular blocks in one of the containers to break the cycle.`,
+ );
+ }
+
+ state.set(type, "visiting");
+ for (const next of requiredContainers(type)) {
+ visit(next, [...path, type]);
+ }
+ state.set(type, "done");
+ };
+
+ for (const type of Object.keys(blockConfigs)) {
+ visit(type, []);
+ }
+}
diff --git a/packages/core/src/schema/index.ts b/packages/core/src/schema/index.ts
index 2f1e703007..e64132cb28 100644
--- a/packages/core/src/schema/index.ts
+++ b/packages/core/src/schema/index.ts
@@ -1,3 +1,9 @@
+// `children.js` and `validateChildren.js` are deliberately *not* re-exported
+// wholesale: almost everything in them is machinery for compiling a `children`
+// config into a ProseMirror content expression, which lives on
+// `@blocknote/core/internal` (see `src/internal.ts`). Only the question a
+// block author asks, "is this a container?", belongs here; the config types
+// come from `./blocks/types.js` below.
export * from "./blocks/createSpec.js";
export * from "./blocks/internal.js";
export * from "./blocks/types.js";
diff --git a/packages/core/src/schema/schema.ts b/packages/core/src/schema/schema.ts
index a7a04e93dc..94e9d9fed6 100644
--- a/packages/core/src/schema/schema.ts
+++ b/packages/core/src/schema/schema.ts
@@ -16,6 +16,7 @@ import {
getInlineContentSchemaFromSpecs,
getStyleSchemaFromSpecs,
} from "./index.js";
+import { validateChildrenConfigs } from "./blocks/validateChildren.js";
function removeUndefined | undefined>(obj: T): T {
if (!obj) {
@@ -91,6 +92,20 @@ export class CustomBlockNoteSchema<
})),
);
+ // Validation runs before the nodes are built, so the misconfigurations
+ // ProseMirror cannot report on its own surface as clear errors.
+ validateChildrenConfigs(
+ Object.fromEntries(
+ Object.entries(this.opts.blockSpecs).map(([key, blockSpec]) => [
+ key,
+ {
+ ...blockSpec.config,
+ runsBefore: blockSpec.implementation?.runsBefore,
+ },
+ ]),
+ ),
+ );
+
const blockSpecs = Object.fromEntries(
Object.entries(this.opts.blockSpecs).map(([key, blockSpec]) => {
return [
diff --git a/packages/core/src/yjs/extensions/FixUpSchema.ts b/packages/core/src/yjs/extensions/FixUpSchema.ts
index 37fb1fd4e9..42234c9b45 100644
--- a/packages/core/src/yjs/extensions/FixUpSchema.ts
+++ b/packages/core/src/yjs/extensions/FixUpSchema.ts
@@ -25,6 +25,12 @@ export const FixUpSchemaExtension = createExtension(({ editor }) => {
// create a copy that we can mutate (otherwise, assigning attrs is not safe and corrupts the pm state)
const jsonNode = JSON.parse(JSON.stringify(ret.toJSON()));
+ // The first fill of the doc's blockGroup is always a `blockContainer`:
+ // container block nodes are clamped below its priority
+ // (`containerNodePriority`) precisely so auto-fill picks it first. If
+ // that ever stops holding, throwing here is better than silently
+ // leaving the id unset, which would let every peer generate its own
+ // initial block id.
jsonNode.content[0].content[0].attrs.id = "initialBlockId";
cache = Node.fromJSON(schema, jsonNode);
diff --git a/packages/core/vite.config.ts b/packages/core/vite.config.ts
index 4c449800c9..c633b99b8d 100644
--- a/packages/core/vite.config.ts
+++ b/packages/core/vite.config.ts
@@ -37,6 +37,7 @@ export default defineConfig({
blocks: path.resolve(__dirname, "src/blocks/index.ts"),
locales: path.resolve(__dirname, "src/i18n/index.ts"),
extensions: path.resolve(__dirname, "src/extensions/index.ts"),
+ internal: path.resolve(__dirname, "src/internal.ts"),
yjs: path.resolve(__dirname, "src/yjs/index.ts"),
y: path.resolve(__dirname, "src/y/index.ts"),
},
diff --git a/packages/core/vitestSetup.ts b/packages/core/vitestSetup.ts
index bf9678c8f8..cc3bdd45f1 100644
--- a/packages/core/vitestSetup.ts
+++ b/packages/core/vitestSetup.ts
@@ -1,11 +1,18 @@
import { afterEach, beforeEach } from "vite-plus/test";
+// This setup file also runs for test files that opt into the plain `node`
+// environment (`@vitest-environment node`), where there is no `window` at
+// all. `__TEST_OPTIONS` (which drives deterministic block IDs) is therefore
+// set on `window` when there is one and on `globalThis` otherwise, matching
+// the resolution `UniqueID`'s `generateID` uses.
+const testHost: any = (globalThis as any).window ?? globalThis;
+
beforeEach(() => {
- (window as Window & { __TEST_OPTIONS?: any }).__TEST_OPTIONS = {};
+ testHost.__TEST_OPTIONS = {};
});
afterEach(() => {
- delete (window as Window & { __TEST_OPTIONS?: any }).__TEST_OPTIONS;
+ delete testHost.__TEST_OPTIONS;
});
// Mock ClipboardEvent
@@ -19,7 +26,7 @@ class ClipboardEventMock extends Event {
},
};
}
-(global as any).ClipboardEvent = ClipboardEventMock;
+(globalThis as any).ClipboardEvent = ClipboardEventMock;
// Mock DragEvent
class DragEventMock extends Event {
@@ -32,4 +39,4 @@ class DragEventMock extends Event {
},
};
}
-(global as any).DragEvent = DragEventMock;
+(globalThis as any).DragEvent = DragEventMock;
diff --git a/packages/react/src/components/Popovers/BlockPopover.tsx b/packages/react/src/components/Popovers/BlockPopover.tsx
index 2bf0e4fa57..572164b409 100644
--- a/packages/react/src/components/Popovers/BlockPopover.tsx
+++ b/packages/react/src/components/Popovers/BlockPopover.tsx
@@ -1,4 +1,4 @@
-import { getNodeById } from "@blocknote/core";
+import { getNodeById, isContainerNode } from "@blocknote/core";
import { ReactNode, useMemo } from "react";
import { useBlockNoteEditor } from "../../hooks/useBlockNoteEditor.js";
@@ -29,6 +29,33 @@ export const BlockPopover = (
return undefined;
}
+ // For container blocks the PM node is the block itself, so a
+ // position inside it resolves to its contentDOM (the child-blocks
+ // area), which would anchor the popover to the first child's rows
+ // instead of the block's own element.
+ if (isContainerNode(nodePosInfo.node.type)) {
+ const dom = editor.prosemirrorView.nodeDOM(nodePosInfo.posBeforeNode);
+ // Frameworks like React wrap the node view in a `display: contents`
+ // element that has no box of its own (a zero-size bounding rect), so
+ // anchoring to it would place the popover at (0, 0). The block's
+ // actual box is the author's root element inside it, which core
+ // stamps with `data-node-type`; vanilla containers render that boxed
+ // element directly as the node view's DOM.
+ if (dom instanceof Element) {
+ // Scoped to this block's own type: an unscoped descendant search
+ // would match a nested child container's root when the author's
+ // root hasn't been stamped, anchoring the popover to a child.
+ const selector = `[data-node-type="${nodePosInfo.node.type.name}"]`;
+ const boxed = dom.matches(selector)
+ ? dom
+ : dom.querySelector(selector);
+ // No stamped root to anchor to, so fall back to the container's
+ // own node element rather than descending into its contentDOM,
+ // which is the first child's box.
+ return { element: boxed ?? dom };
+ }
+ }
+
const { node } = editor.prosemirrorView.domAtPos(
nodePosInfo.posBeforeNode + 1,
);
diff --git a/packages/react/src/editor/styles.css b/packages/react/src/editor/styles.css
index 507f2cd46f..c3a39005a5 100644
--- a/packages/react/src/editor/styles.css
+++ b/packages/react/src/editor/styles.css
@@ -111,6 +111,13 @@
width: 100%;
}
+/* Container blocks own their outer DOM: the block's root element is the one
+ its `render` returned, so the wrapper React needs around it must not be a
+ box of its own. */
+.bn-react-node-view-renderer.bn-container-node-view {
+ display: contents;
+}
+
/* Indent line styling */
.bn-block-group
.bn-block:not(:has(.bn-toggle-wrapper))
diff --git a/packages/react/src/schema/ReactBlockSpec.container.browser.test.tsx b/packages/react/src/schema/ReactBlockSpec.container.browser.test.tsx
new file mode 100644
index 0000000000..588469916b
--- /dev/null
+++ b/packages/react/src/schema/ReactBlockSpec.container.browser.test.tsx
@@ -0,0 +1,156 @@
+import { BlockNoteEditor, BlockNoteSchema } from "@blocknote/core";
+import { flushSync } from "react-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it } from "vite-plus/test";
+
+import { BlockNoteViewRaw } from "../editor/BlockNoteView.js";
+import { createReactBlockSpec } from "./ReactBlockSpec.js";
+
+/**
+ * Tests for React container blocks in a real browser.
+ *
+ * Everything here needs a real DOM: the external-HTML path renders the block
+ * through a temporary `createRoot` (see `@util/ReactRenderUtil`), and a React
+ * node view only runs once `contentComponent` is set, which happens when
+ * `BlockNoteViewRaw` mounts the editor. Document-model behaviour of
+ * containers in general is covered by the core suites in
+ * `api/blockManipulation/containers/`.
+ */
+
+// A container: its `contentRef` element holds its child blocks.
+const createCallout = createReactBlockSpec(
+ {
+ type: "callout",
+ propSchema: { flavor: { default: "tip" } },
+ content: "none",
+ children: { allow: "any", default: [{ type: "paragraph" }] },
+ },
+ {
+ render: (props) => (
+
+
+
+ ),
+ },
+);
+
+const schema = BlockNoteSchema.create().extend({
+ blockSpecs: {
+ callout: createCallout(),
+ },
+});
+
+describe("React container block external HTML", () => {
+ it("serializes the author's own root element, unwrapped", () => {
+ const editor = BlockNoteEditor.create({ schema });
+
+ const html = editor.blocksToHTMLLossy([
+ {
+ type: "callout",
+ id: "c-0",
+ children: [{ id: "c-p-0", type: "paragraph", content: "Hello" }],
+ },
+ ] as any);
+
+ // Container blocks own their outer DOM entirely. Regression test for the
+ // React `toExternalHTML` path wrapping them in a spurious
+ // `bn-block-content` div (core's `createBlockSpec` passes them through).
+ // The root is the element `render` returned, with no React wrapper in
+ // between, so `.callout[data-*]` CSS matches it here exactly as in the
+ // live editor.
+ expect(html).not.toContain('data-content-type="callout"');
+ expect(html).not.toContain("data-node-view-wrapper");
+ expect(html).toContain('class="callout"');
+ expect(html).toContain('data-node-type="callout"');
+ expect(html).toContain("Hello");
+
+ editor._tiptapEditor.destroy();
+ });
+});
+
+let root: Root | undefined;
+let div: HTMLDivElement | undefined;
+let editor: BlockNoteEditor | undefined;
+
+afterEach(() => {
+ root?.unmount();
+ root = undefined;
+ if (div) {
+ document.body.removeChild(div);
+ div = undefined;
+ }
+ editor?._tiptapEditor.destroy();
+ editor = undefined;
+});
+
+/** Lets TipTap's deferred node-view render and React's commit run. */
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+async function mountEditor(initialContent: any[]) {
+ div = document.createElement("div");
+ document.body.appendChild(div);
+
+ editor = BlockNoteEditor.create({
+ schema,
+ trailingBlock: false,
+ initialContent,
+ }) as BlockNoteEditor;
+
+ root = createRoot(div);
+ flushSync(() => {
+ root!.render();
+ });
+ // TipTap only renders a node view synchronously when this is set; BlockNote
+ // mounts the editor itself and never does, so the first batch of node views
+ // takes the deferred path (see `tests/src/unit/react/staleNodeViewPos.test.tsx`).
+ (editor as any)._tiptapEditor.isEditorContentInitialized = true;
+ await tick();
+
+ return { editor: editor!, div: div! };
+}
+
+describe("React container block node view", () => {
+ it("stamps only non-default props onto the block's own root, and keeps them in sync", async () => {
+ const mounted = await mountEditor([
+ { id: "c-0", type: "callout", children: [{ type: "paragraph" }] },
+ ]);
+
+ const calloutRoot = mounted.div.querySelector(".callout")!;
+ // The author's element, not `div.react-renderer` or the node view
+ // wrapper: exactly the class the author wrote, and nothing else.
+ expect(calloutRoot.className).toBe("callout");
+ expect(calloutRoot.getAttribute("data-id")).toBe("c-0");
+ // `flavor` is at its default, so no attribute is written for it.
+ expect(calloutRoot.hasAttribute("data-flavor")).toBe(false);
+
+ mounted.editor.updateBlock("c-0", { props: { flavor: "warning" } } as any);
+ await tick();
+
+ // Re-queried: a prop change must land on whatever element is now the
+ // block's root, so `.callout[data-flavor="warning"]` selects in the live
+ // editor exactly as it does in the serialized HTML above.
+ expect(
+ mounted.div
+ .querySelector(".callout")!
+ .getAttribute("data-flavor"),
+ ).toBe("warning");
+ });
+
+ it("mounts a pure container's children inside its `contentRef` element", async () => {
+ const mounted = await mountEditor([
+ {
+ id: "c-0",
+ type: "callout",
+ children: [{ id: "c-child", type: "paragraph", content: "Child" }],
+ },
+ ]);
+
+ const body = mounted.div.querySelector(".callout-body")!;
+ // A container with no content of its own puts its children where the
+ // author placed `contentRef`, not somewhere else in the node view. The
+ // child's own block element is a descendant, so this checks structure,
+ // not just text that happened to bubble up.
+ expect(body.querySelector('[data-id="c-child"]')).not.toBeNull();
+ expect(body.textContent).toBe("Child");
+ });
+});
diff --git a/packages/react/src/schema/ReactBlockSpec.tsx b/packages/react/src/schema/ReactBlockSpec.tsx
index 5311d4e37d..9c72da3e41 100644
--- a/packages/react/src/schema/ReactBlockSpec.tsx
+++ b/packages/react/src/schema/ReactBlockSpec.tsx
@@ -1,3 +1,4 @@
+import { applyContainerAttributes } from "@blocknote/core/internal";
import {
BlockConfig,
BlockConfigOrCreator,
@@ -6,11 +7,13 @@ import {
BlockNoteEditor,
BlockSpec,
camelToDataKebab,
+ ChildrenConfig,
CustomBlockImplementation,
Extension,
ExtensionFactoryInstance,
ExtractBlockConfigFromConfigOrCreator,
mergeCSSClasses,
+ nodeToBlock,
Props,
PropSchema,
} from "@blocknote/core";
@@ -20,12 +23,17 @@ import {
ReactNodeViewRenderer,
useReactNodeView,
} from "@tiptap/react";
-import { FC, ReactNode } from "react";
+import { CSSProperties, FC, ReactNode, useLayoutEffect } from "react";
import { renderToDOMSpec } from "./@util/ReactRenderUtil.js";
import { useNodeViewBlock } from "./useNodeViewBlock.js";
// this file is mostly analogoues to `customBlocks.ts`, but for React blocks
+// A container block's root element is the block's own element, so every
+// wrapper React puts above it has to contribute no box of its own. Module
+// scope so the style object is referentially stable across renders.
+const DISPLAY_CONTENTS: CSSProperties = { display: "contents" };
+
export type ReactCustomBlockRenderProps<
B extends BlockConfigOrCreator,
Config extends ExtractBlockConfigFromConfigOrCreator =
@@ -33,11 +41,15 @@ export type ReactCustomBlockRenderProps<
> = {
block: BlockNoDefaults, any, any>;
editor: BlockNoteEditor, any, any>;
-} & (Config["content"] extends "inline" | "plain"
- ? {
- contentRef: (node: HTMLElement | null) => void;
- }
- : object);
+ // A block gets a `contentRef` for its `render` to mount its editable region:
+ // its inline content, or, for a container, its child blocks. Only a
+ // `content: "none"` block without `children` (and the table block, whose
+ // content is managed separately) has nothing to place.
+} & (Config extends { children: ChildrenConfig }
+ ? { contentRef: (node: HTMLElement | null) => void }
+ : Config["content"] extends "inline" | "plain"
+ ? { contentRef: (node: HTMLElement | null) => void }
+ : object);
// extend BlockConfig but use a React render function
export type ReactCustomBlockImplementation<
@@ -131,20 +143,20 @@ export function createReactBlockSpec<
const TName extends string,
const TProps extends PropSchema,
const TContent extends "inline" | "none" | "plain",
+ // Inferred from the config object itself rather than widened to
+ // `BlockConfig<...>`, so `children` survives into the render props and
+ // `contentRef` is offered exactly when the block has an editable region.
+ const BlockConf extends BlockConfig,
const TOptions extends Record | undefined = undefined,
>(
- blockConfigOrCreator: BlockConfig,
+ blockConfigOrCreator: BlockConf,
blockImplementationOrCreator:
- | ReactCustomBlockImplementation>
+ | ReactCustomBlockImplementation
| (TOptions extends undefined
- ? () => ReactCustomBlockImplementation<
- BlockConfig
- >
+ ? () => ReactCustomBlockImplementation
: (
options: Partial,
- ) => ReactCustomBlockImplementation<
- BlockConfig
- >),
+ ) => ReactCustomBlockImplementation),
extensionsOrCreator?:
| (ExtensionFactoryInstance | Extension)[]
| (TOptions extends undefined
@@ -152,7 +164,13 @@ export function createReactBlockSpec<
: (
options: Partial,
) => (ExtensionFactoryInstance | Extension)[]),
-): (options?: Partial) => BlockSpec;
+): (
+ options?: Partial,
+) => BlockSpec<
+ BlockConf["type"],
+ BlockConf["propSchema"],
+ BlockConf["content"]
+>;
export function createReactBlockSpec<
const TName extends string,
const TProps extends PropSchema,
@@ -225,42 +243,73 @@ export function createReactBlockSpec<
: extensionsOrCreator
: undefined;
+ // Container-ness is fixed per spec, so every render path can decide once.
+ const isContainer = blockConfig.children !== undefined;
+
+ // Shared by the two paths that render to plain DOM (`toExternalHTML` and
+ // `render` outside a node view). A container block's output is the
+ // block's root element, with no wrapper: the attributes core stamps
+ // afterwards then land on the author's own element, the same element they
+ // land on in the live editor.
+ function renderStatic(args: {
+ BlockContent: FC;
+ block: any;
+ editor: any;
+ domAttributes?: Record;
+ isFileBlock?: boolean;
+ context?: any;
+ }) {
+ const { BlockContent, block, editor } = args;
+
+ return renderToDOMSpec((refCB) => {
+ const content = (
+ {
+ refCB(element);
+ if (element && !isContainer) {
+ element.className = mergeCSSClasses(
+ "bn-inline-content",
+ element.className,
+ );
+ }
+ }}
+ context={args.context}
+ />
+ );
+
+ return isContainer ? (
+ content
+ ) : (
+
+ {content}
+
+ );
+ }, editor);
+ }
+
return {
config: blockConfig,
implementation: {
...blockImplementation,
toExternalHTML(block, editor, context) {
- const BlockContent =
- blockImplementation.toExternalHTML || blockImplementation.render;
- const output = renderToDOMSpec((refCB) => {
- return (
-
- {
- refCB(element);
- if (element) {
- element.className = mergeCSSClasses(
- "bn-inline-content",
- element.className,
- );
- }
- }}
- context={context}
- />
-
- );
- }, editor);
- return output;
+ return renderStatic({
+ BlockContent: (blockImplementation.toExternalHTML ||
+ blockImplementation.render) as FC,
+ block,
+ editor,
+ domAttributes: this.blockContentDOMAttributes,
+ isFileBlock:
+ blockImplementation.meta?.fileBlockAccept !== undefined,
+ context,
+ });
},
render(block, editor) {
if (this.renderType === "nodeView") {
@@ -268,80 +317,177 @@ export function createReactBlockSpec<
// constructed (itself guarded, via `getBlockFromNodeView`). Seeds
// the fallback below so there is always something to render.
const initialBlock = block;
+ // Each node-view variant uses only the hooks and wrappers it
+ // needs, so the component is chosen once from `isContainer`.
+ const BlockContent = blockImplementation.render as FC;
+ const blockContentDOMAttributes = this.blockContentDOMAttributes;
+
+ // Set by the container node view's `NodeViewWrapper` below. The
+ // author's own root element is that wrapper's first element child;
+ // it's read lazily because React may not have committed yet when
+ // this node view is handed to core, and because the author's
+ // component is free to swap its root element on a re-render.
+ const wrapper: { current: HTMLElement | null } = { current: null };
+ const authorRootDOM = () =>
+ (wrapper.current?.firstElementChild as HTMLElement | null) ??
+ null;
+
+ // Vanilla JS node views are recreated on each update. However,
+ // using `ReactNodeViewRenderer` makes it so the node view is only
+ // created once, so the block we get in the node view will be
+ // outdated. Therefore, both variants have to (re-)resolve the
+ // block inside the `ReactNodeViewRenderer` component.
- return ReactNodeViewRenderer(
- (props: NodeViewProps) => {
- // Vanilla JS node views are recreated on each update. However,
- // using `ReactNodeViewRenderer` makes it so the node view is
- // only created once, so the block we get in the node view will
- // be outdated. Therefore, we have to get the block in the
- // `ReactNodeViewRenderer` instead. That position can be stale,
- // so resolving it is guarded (see `useNodeViewBlock`).
- const block = useNodeViewBlock(props, initialBlock);
+ const ContainerNodeView = (props: NodeViewProps) => {
+ // Container blocks are bnBlock nodes (no `blockContainer`
+ // wrapper), so the id lives on the node's own attrs and the
+ // block resolves by id. Position-based resolution
+ // (`useNodeViewBlock`) would walk up to a parent bnBlock,
+ // which is the wrong block here. Ids are also immune to the
+ // stale positions it has to guard against.
+ const id = (props.node.attrs as Record).id;
+ if (!id) {
+ throw new Error(
+ `Container block "${blockConfig.type}" is missing an id attribute.`,
+ );
+ }
+ // Converted from the node the view was handed rather than
+ // looked up by id: the conversion is cached per node, while a
+ // lookup would scan the whole document on every render, and it
+ // also covers a node that was just removed from the document
+ // (e.g. a suggestion-mode deletion still rendering).
+ const block = nodeToBlock(props.node, props.view.state.doc);
+
+ const ref = useReactNodeView().nodeViewContentRef;
+ if (!ref) {
+ throw new Error("nodeViewContentRef is not set");
+ }
- const ref = useReactNodeView().nodeViewContentRef;
+ const selected = props.selected;
- if (!ref) {
- throw new Error("nodeViewContentRef is not set");
+ // Stamped imperatively rather than spread as JSX props: the root
+ // element belongs to the block's author, so there is nothing to
+ // spread onto. `block` is derived from the node, so a new one
+ // also means the author's root may have been swapped.
+ useLayoutEffect(() => {
+ const root = authorRootDOM();
+ if (!root) {
+ return;
}
- const BlockContent = blockImplementation.render;
- return (
-
- {
- ref(element);
- if (element) {
- element.className = mergeCSSClasses(
- "bn-inline-content",
- element.className,
- );
- element.dataset.nodeViewContent = "";
- }
- }}
- />
-
+ applyContainerAttributes(
+ root,
+ blockConfig.type,
+ block.props as any,
+ blockConfig.propSchema,
+ block.id,
);
- },
- {
- className: "bn-react-node-view-renderer",
- },
- )(this.props!) as ReturnType;
- } else {
- const BlockContent = blockImplementation.render;
- const output = renderToDOMSpec((refCB) => {
+
+ // ProseMirror marks the outermost element with
+ // `ProseMirror-selectednode`, but for containers that element
+ // has `display: contents`, which suppresses any outline drawn
+ // on it. So the state is mirrored onto the author's root,
+ // which is the block's actual box.
+ if (selected) {
+ root.setAttribute("data-selected", "");
+ } else {
+ root.removeAttribute("data-selected");
+ }
+ }, [block, selected]);
+
+ return (
+
+ {
+ ref(element);
+ if (element) {
+ element.dataset.nodeViewContent = "";
+ // Mark the children host of a container so the
+ // round-trip parse rule can scope itself to it (see
+ // `getParseRules`).
+ element.setAttribute(
+ "data-children-of",
+ blockConfig.type,
+ );
+ }
+ }}
+ />
+
+ );
+ };
+
+ const RegularNodeView = (props: NodeViewProps) => {
+ // The node view's position can be stale mid-render, so
+ // resolving it is guarded (see `useNodeViewBlock`).
+ const block = useNodeViewBlock(props, initialBlock);
+
+ const ref = useReactNodeView().nodeViewContentRef;
+ if (!ref) {
+ throw new Error("nodeViewContentRef is not set");
+ }
+
return (
{
- refCB(element);
+ contentRef={(element: HTMLElement | null) => {
+ ref(element);
if (element) {
element.className = mergeCSSClasses(
"bn-inline-content",
element.className,
);
+ element.dataset.nodeViewContent = "";
}
}}
/>
);
- }, editor);
- return output;
+ };
+
+ const nodeView = ReactNodeViewRenderer(
+ isContainer ? ContainerNodeView : RegularNodeView,
+ {
+ // The container class is separate because it removes the
+ // box the regular class relies on (see `Block.css`).
+ className: isContainer
+ ? "bn-react-node-view-renderer bn-container-node-view"
+ : "bn-react-node-view-renderer",
+ },
+ )(this.props!) as ReturnType;
+
+ if (isContainer) {
+ // TipTap appends its content host into whichever element the
+ // block passed `contentRef` to. `display: contents` keeps that
+ // host from contributing a box, so the block's editable region
+ // lays out exactly where the author put the ref.
+ if (nodeView.contentDOM) {
+ nodeView.contentDOM.style.display = "contents";
+ }
+ // Where core stamps the container attributes: the author's own
+ // element, not React's outermost wrapper (`dom`).
+ Object.defineProperty(nodeView, "rootDOM", {
+ get: authorRootDOM,
+ });
+ }
+
+ return nodeView;
+ } else {
+ return renderStatic({
+ BlockContent: blockImplementation.render as FC,
+ block,
+ editor,
+ domAttributes: this.blockContentDOMAttributes,
+ });
}
},
},
diff --git a/packages/react/src/schema/useNodeViewBlock.ts b/packages/react/src/schema/useNodeViewBlock.ts
index 02393a2fd0..2577150aec 100644
--- a/packages/react/src/schema/useNodeViewBlock.ts
+++ b/packages/react/src/schema/useNodeViewBlock.ts
@@ -42,6 +42,17 @@ export function useNodeViewBlock(
const lastBlockRef = useRef(initialBlock);
const doc = props.view.state.doc;
+ // Position-based resolution finds the nearest bnBlock parent of the
+ // position. That is correct for blockContent node views, but wrong for
+ // container blocks, whose node is itself the bnBlock: it would return an
+ // ancestor block. This guard throws so a container node view can't
+ // silently render the wrong block.
+ if (props.node.type.isInGroup("bnBlock")) {
+ throw new Error(
+ `useNodeViewBlock cannot resolve container block "${props.node.type.name}": position-based resolution returns the nearest bnBlock parent, which is the wrong block when the node view's node is the block itself. Resolve container blocks by id instead, e.g. editor.getBlock(props.node.attrs.id).`,
+ );
+ }
+
try {
// Deliberate render-phase write: a monotonic "last good value" cache, so a
// repeated render (e.g. StrictMode's double invoke) recomputes the same
diff --git a/packages/react/vite.config.ts b/packages/react/vite.config.ts
index d4e59a60b4..1001b8cbe8 100644
--- a/packages/react/vite.config.ts
+++ b/packages/react/vite.config.ts
@@ -1,7 +1,7 @@
import react from "@vitejs/plugin-react";
import * as path from "path";
import { webpackStats } from "rollup-plugin-webpack-stats";
-import { defineConfig, type UserConfig } from "vite-plus";
+import { configDefaults, defineConfig, type UserConfig } from "vite-plus";
import pkg from "./package.json";
// import eslintPlugin from "vite-plugin-eslint";
@@ -26,6 +26,9 @@ export default defineConfig(
test: {
environment: "jsdom",
setupFiles: ["./vitestSetup.ts"],
+ // `.browser.test` files need a real browser; the tests package's
+ // browser suite runs them.
+ exclude: [...configDefaults.exclude, "**/*.browser.test.*"],
},
plugins: [react(), webpackStats()],
// used so that vitest resolves the core package from the sources instead of the built version
diff --git a/packages/react/vitestSetup.ts b/packages/react/vitestSetup.ts
index beafe25357..07c283c583 100644
--- a/packages/react/vitestSetup.ts
+++ b/packages/react/vitestSetup.ts
@@ -1,11 +1,21 @@
import { afterEach, beforeEach } from "vite-plus/test";
+// This setup file also runs for test files that opt into the plain `node`
+// environment (`@vitest-environment node`), where there is no `window` at
+// all. The DOM mocks below are a no-op there.
+const hasWindow = typeof window !== "undefined";
+
+// Match the core setup: the deterministic-ID options live on `window` when it
+// exists and on `globalThis` in the node environment, since `generateID` reads
+// them from `(globalThis.window ?? globalThis).__TEST_OPTIONS`.
+const testHost: any = (globalThis as any).window ?? globalThis;
+
beforeEach(() => {
- (window as Window & { __TEST_OPTIONS?: any }).__TEST_OPTIONS = {};
+ testHost.__TEST_OPTIONS = {};
});
afterEach(() => {
- delete (window as Window & { __TEST_OPTIONS?: any }).__TEST_OPTIONS;
+ delete testHost.__TEST_OPTIONS;
});
// Mock ClipboardEvent
@@ -19,7 +29,7 @@ class ClipboardEventMock extends Event {
},
};
}
-(global as any).ClipboardEvent = ClipboardEventMock;
+(globalThis as any).ClipboardEvent = ClipboardEventMock;
// Mock DragEvent
class DragEventMock extends Event {
@@ -32,28 +42,30 @@ class DragEventMock extends Event {
},
};
}
-Object.defineProperty(window, "matchMedia", {
- writable: true,
- value: (query: string) => ({
- matches: false,
- media: query,
- onchange: null,
- addListener: () => {
- //
- }, // Deprecated
- removeListener: () => {
- //
- }, // Deprecated
- addEventListener: () => {
- //
- },
- removeEventListener: () => {
- //
- },
- dispatchEvent: () => {
- //
- },
- }),
-});
+if (hasWindow) {
+ Object.defineProperty(window, "matchMedia", {
+ writable: true,
+ value: (query: string) => ({
+ matches: false,
+ media: query,
+ onchange: null,
+ addListener: () => {
+ //
+ }, // Deprecated
+ removeListener: () => {
+ //
+ }, // Deprecated
+ addEventListener: () => {
+ //
+ },
+ removeEventListener: () => {
+ //
+ },
+ dispatchEvent: () => {
+ //
+ },
+ }),
+ });
+}
-(global as any).DragEvent = DragEventMock;
+(globalThis as any).DragEvent = DragEventMock;
diff --git a/packages/xl-ai/src/api/formats/html-blocks/collabUpdate.test.ts b/packages/xl-ai/src/api/formats/html-blocks/collabUpdate.test.ts
index fec31293a5..b8a4405285 100644
--- a/packages/xl-ai/src/api/formats/html-blocks/collabUpdate.test.ts
+++ b/packages/xl-ai/src/api/formats/html-blocks/collabUpdate.test.ts
@@ -10,7 +10,7 @@
import {
BlockNoteEditor,
expandPMRangeToWords,
- getBlockInfo,
+ getBlockInfoFromNode,
getNodeById,
} from "@blocknote/core";
import type { ForkYDocExtension } from "@blocknote/core/yjs";
@@ -79,12 +79,13 @@ function createCollabEditor(text: string) {
*/
function selectWholeFirstBlock(editor: BlockNoteEditor) {
const id = editor.document[0].id;
- const info = getBlockInfo(getNodeById(id, editor.prosemirrorState.doc)!);
- if (!info.isBlockContainer) {
+ const posInfo = getNodeById(id, editor.prosemirrorState.doc)!;
+ const info = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+ if (!info.hasContent) {
throw new Error("not a block container");
}
- const from = info.blockContent.beforePos + 1;
- const to = info.blockContent.afterPos - 1;
+ const from = info.content.beforePos + 1;
+ const to = info.content.afterPos - 1;
editor.transact((tr) => {
tr.setSelection(TextSelection.create(tr.doc, from, to));
diff --git a/packages/xl-ai/src/prosemirror/agent.test.ts b/packages/xl-ai/src/prosemirror/agent.test.ts
index 44d87c8108..bc3392941c 100644
--- a/packages/xl-ai/src/prosemirror/agent.test.ts
+++ b/packages/xl-ai/src/prosemirror/agent.test.ts
@@ -1,7 +1,7 @@
import {
BlockNoteEditor,
expandPMRangeToWords,
- getBlockInfo,
+ getBlockInfoFromNode,
getNodeById,
} from "@blocknote/core";
import { Fragment, Slice } from "prosemirror-model";
@@ -38,12 +38,12 @@ describe.skip("getStepsAsAgent", () => {
const doc = editor.prosemirrorState.doc;
// Get the position of the content in the paragraph
const blockPos = getNodeById("1", doc)!;
- const block = getBlockInfo(blockPos);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(blockPos.node, blockPos.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a container");
}
- const contentStart = block.blockContent.beforePos;
+ const contentStart = block.content.beforePos;
// Create a ReplaceStep that replaces "Hello" with "Hi"
const from = contentStart + 1; // +1 to skip the initial position
@@ -71,13 +71,13 @@ describe.skip("getStepsAsAgent", () => {
const doc = editor.prosemirrorState.doc;
// Get the position of the content in the paragraph
const blockPos = getNodeById("1", doc)!;
- const block = getBlockInfo(blockPos);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(blockPos.node, blockPos.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a container");
}
const tr = editor.prosemirrorState.tr.setNodeMarkup(
- block.blockContent.beforePos,
+ block.content.beforePos,
editor.pmSchema.nodes.heading,
);
@@ -97,13 +97,13 @@ describe.skip("getStepsAsAgent", () => {
const doc = editor.prosemirrorState.doc;
// Get the position of the content in the paragraph
const blockPos = getNodeById("1", doc)!;
- const block = getBlockInfo(blockPos);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(blockPos.node, blockPos.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a container");
}
const tr = editor.prosemirrorState.tr.setNodeMarkup(
- block.blockContent.beforePos,
+ block.content.beforePos,
undefined,
{
textAlignment: "right",
@@ -127,17 +127,17 @@ describe.skip("getStepsAsAgent", () => {
const doc = editor.prosemirrorState.doc;
// Get the position of the content in the paragraph
const blockPos = getNodeById("1", doc)!;
- const block = getBlockInfo(blockPos);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(blockPos.node, blockPos.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a container");
}
const step = new ReplaceStep(
- block.blockContent.beforePos,
- block.blockContent.beforePos + 3,
+ block.content.beforePos,
+ block.content.beforePos + 3,
// for simplicity, we're not actually changing the node type and content, but we just use the existing document
// as replacement content
- doc.slice(block.blockContent.beforePos, block.blockContent.beforePos + 3),
+ doc.slice(block.content.beforePos, block.content.beforePos + 3),
);
const tr = new Transform(doc);
@@ -156,12 +156,12 @@ describe.skip("getStepsAsAgent", () => {
// Get the position of the content in the paragraph
const blockPos = getNodeById("1", doc)!;
- const block = getBlockInfo(blockPos);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(blockPos.node, blockPos.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a container");
}
- const contentStart = block.blockContent.beforePos;
+ const contentStart = block.content.beforePos;
// Create two ReplaceSteps
// 1. Replace "Hello" with "Hi"
diff --git a/packages/xl-ai/src/prosemirror/rebaseTool.test.ts b/packages/xl-ai/src/prosemirror/rebaseTool.test.ts
index 21454b7b79..24b0e712ee 100644
--- a/packages/xl-ai/src/prosemirror/rebaseTool.test.ts
+++ b/packages/xl-ai/src/prosemirror/rebaseTool.test.ts
@@ -1,4 +1,8 @@
-import { BlockNoteEditor, getBlockInfo, getNodeById } from "@blocknote/core";
+import {
+ BlockNoteEditor,
+ getBlockInfoFromNode,
+ getNodeById,
+} from "@blocknote/core";
import { expect, it } from "vite-plus/test";
import { AttributionMarksExtension } from "./AttributionMarks.js";
import { getApplySuggestionsTr, rebaseTool } from "./rebaseTool.js";
@@ -20,21 +24,21 @@ function getExampleEditorWithSuggestions() {
const blockPos = getNodeById("1", editor.prosemirrorState.doc)!;
- const block = getBlockInfo(blockPos);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(blockPos.node, blockPos.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a container");
}
editor.transact((tr) => {
tr.addMark(
- block.blockContent.beforePos + 1,
- block.blockContent.beforePos + 6,
+ block.content.beforePos + 1,
+ block.content.beforePos + 6,
editor.pmSchema.mark("deletion", { id: 1 }),
);
tr.addMark(
- block.blockContent.beforePos + 6,
- block.blockContent.beforePos + 8,
+ block.content.beforePos + 6,
+ block.content.beforePos + 8,
editor.pmSchema.mark("insertion", { id: 2 }),
);
});
@@ -54,13 +58,13 @@ it("should be able to apply changes to a clean doc (use invertMap)", async () =>
const blockPos = getNodeById("1", cleaned.doc)!;
- const block = getBlockInfo(blockPos);
+ const block = getBlockInfoFromNode(blockPos.node, blockPos.posBeforeNode);
- if (!block.isBlockContainer) {
+ if (!block.hasContent) {
throw new Error("Block is not a container");
}
- const start = block.blockContent.beforePos + 1;
+ const start = block.content.beforePos + 1;
const end = start + 2;
expect(cleaned.doc.textBetween(start, end)).toBe("Hi");
@@ -83,13 +87,13 @@ it("should be able to apply changes to a clean doc (use rebaseTr)", async () =>
const blockPos = getNodeById("1", cleaned.doc)!;
- const block = getBlockInfo(blockPos);
+ const block = getBlockInfoFromNode(blockPos.node, blockPos.posBeforeNode);
- if (!block.isBlockContainer) {
+ if (!block.hasContent) {
throw new Error("Block is not a container");
}
- const start = block.blockContent.beforePos + 1;
+ const start = block.content.beforePos + 1;
const end = start + 2;
expect(cleaned.doc.textBetween(start, end)).toBe("Hi");
diff --git a/packages/xl-ai/src/testUtil/cases/combinedOperationsTestCases.ts b/packages/xl-ai/src/testUtil/cases/combinedOperationsTestCases.ts
index 6262f505cb..8b004c9130 100644
--- a/packages/xl-ai/src/testUtil/cases/combinedOperationsTestCases.ts
+++ b/packages/xl-ai/src/testUtil/cases/combinedOperationsTestCases.ts
@@ -1,5 +1,5 @@
-// import { BlockNoteEditor, getBlockInfo, getNodeById } from "@blocknote/core";
-import { getBlockInfo, getNodeById } from "@blocknote/core";
+// import { BlockNoteEditor, getBlockInfoFromNode, getNodeById } from "@blocknote/core";
+import { getBlockInfoFromNode, getNodeById } from "@blocknote/core";
import { getEditorWithFormattingAndMentions } from "./editors/formattingAndMentions.js";
import { DocumentOperationTestCase } from "./index.js";
@@ -46,13 +46,13 @@ export const combinedOperationsTestCases: DocumentOperationTestCase[] = [
getTestSelection: (editor) => {
const posInfo = getNodeById("ref2", editor.prosemirrorState.doc)!;
- const block = getBlockInfo(posInfo);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a block container");
}
return {
- from: block.blockContent.beforePos + 1,
- to: block.blockContent.beforePos + 1 + "Hello".length,
+ from: block.content.beforePos + 1,
+ to: block.content.beforePos + 1 + "Hello".length,
};
},
userPrompt:
diff --git a/packages/xl-ai/src/testUtil/cases/updateOperationTestCases.ts b/packages/xl-ai/src/testUtil/cases/updateOperationTestCases.ts
index 2261863430..d483314f06 100644
--- a/packages/xl-ai/src/testUtil/cases/updateOperationTestCases.ts
+++ b/packages/xl-ai/src/testUtil/cases/updateOperationTestCases.ts
@@ -1,4 +1,8 @@
-import { BlockNoteEditor, getBlockInfo, getNodeById } from "@blocknote/core";
+import {
+ BlockNoteEditor,
+ getBlockInfoFromNode,
+ getNodeById,
+} from "@blocknote/core";
import { AIExtension } from "../../AIExtension.js";
import { getEditorWithBlockFormatting } from "./editors/blockFormatting.js";
import { getEditorWithFormattingAndMentions } from "./editors/formattingAndMentions.js";
@@ -40,13 +44,13 @@ export const updateOperationTestCases: DocumentOperationTestCase[] = [
],
getTestSelection: (editor: BlockNoteEditor) => {
const posInfo = getNodeById("ref2", editor.prosemirrorState.doc)!;
- const block = getBlockInfo(posInfo);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a block container");
}
return {
- from: block.blockContent.beforePos + 1,
- to: block.blockContent.beforePos + 1 + "Hello".length,
+ from: block.content.beforePos + 1,
+ to: block.content.beforePos + 1 + "Hello".length,
};
},
userPrompt: "translate to German",
@@ -67,14 +71,14 @@ export const updateOperationTestCases: DocumentOperationTestCase[] = [
],
getTestSelection: (editor: BlockNoteEditor) => {
const posInfo = getNodeById("ref1", editor.prosemirrorState.doc)!;
- const block = getBlockInfo(posInfo);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a block container");
}
// 'ello, world! Dow are yo'
return {
- from: block.blockContent.beforePos + 2,
- to: block.blockContent.afterPos - 3,
+ from: block.content.beforePos + 2,
+ to: block.content.afterPos - 3,
};
},
userPrompt: "fix spelling",
@@ -736,12 +740,12 @@ export const updateOperationTestCases: DocumentOperationTestCase[] = [
userPrompt: "turn into list (update existing blocks)",
getTestSelection(editor) {
const posInfo = getNodeById("ref2", editor.prosemirrorState.doc)!;
- const block = getBlockInfo(posInfo);
- if (!block.isBlockContainer) {
+ const block = getBlockInfoFromNode(posInfo.node, posInfo.posBeforeNode);
+ if (!block.hasContent) {
throw new Error("Block is not a block container");
}
return {
- from: block.blockContent.beforePos + 1,
+ from: block.content.beforePos + 1,
to: editor.prosemirrorState.doc.content.size,
};
},
diff --git a/packages/xl-docx-exporter/src/docx/docxExporter.test.ts b/packages/xl-docx-exporter/src/docx/docxExporter.test.ts
index 11367c90f2..0f55ad7fa0 100644
--- a/packages/xl-docx-exporter/src/docx/docxExporter.test.ts
+++ b/packages/xl-docx-exporter/src/docx/docxExporter.test.ts
@@ -1,5 +1,6 @@
import {
BlockNoteSchema,
+ createBlockSpec,
defaultBlockSpecs,
createPageBreakBlockSpec,
PartialBlock,
@@ -416,6 +417,82 @@ describe("exporter", () => {
);
});
+describe("custom container blocks", () => {
+ const Box = createBlockSpec(
+ {
+ type: "box" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: "any" },
+ },
+ {
+ render: (block: any) => {
+ const dom = document.createElement("div");
+ dom.setAttribute("data-node-type", "box");
+ dom.setAttribute("data-id", block.id);
+ return { dom, contentDOM: dom };
+ },
+ },
+ )();
+
+ const boxSchema = BlockNoteSchema.create({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ box: Box,
+ },
+ });
+
+ const boxDocument = partialBlocksToBlocksForTesting(boxSchema, [
+ {
+ type: "box",
+ children: [
+ { type: "paragraph", content: "First" },
+ { type: "paragraph", content: "Second" },
+ ],
+ },
+ ] as any);
+
+ it("passes children to a custom container mapping", async () => {
+ const exporter = new DOCXExporter(
+ boxSchema,
+ {
+ ...docxDefaultSchemaMappings,
+ blockMapping: {
+ ...docxDefaultSchemaMappings.blockMapping,
+ box: (
+ _block: any,
+ _exporter: any,
+ _nesting: any,
+ _index: any,
+ children: any,
+ ) =>
+ new Paragraph({
+ children: [new TextRun(`BOX(${children?.length ?? 0})`)],
+ }),
+ },
+ } as any,
+ { resolveFileUrl: testResolveFileUrl },
+ );
+
+ const transformed = await exporter.transformBlocks(boxDocument as any);
+ expect(transformed).toHaveLength(1);
+ const xml = JSON.stringify(transformed[0]);
+ expect(xml).toContain("BOX(2)");
+ });
+
+ it("throws a clear error for an unmapped container block", async () => {
+ const exporter = new DOCXExporter(
+ boxSchema,
+ docxDefaultSchemaMappings as any,
+ { resolveFileUrl: testResolveFileUrl },
+ );
+
+ await expect(exporter.transformBlocks(boxDocument as any)).rejects.toThrow(
+ /container block type "box"/,
+ );
+ });
+});
+
function prettify(sourceXml: string) {
let ret = xmlFormat(sourceXml);
diff --git a/packages/xl-docx-exporter/src/docx/docxExporter.ts b/packages/xl-docx-exporter/src/docx/docxExporter.ts
index f27a4b6bcb..b18b236c85 100644
--- a/packages/xl-docx-exporter/src/docx/docxExporter.ts
+++ b/packages/xl-docx-exporter/src/docx/docxExporter.ts
@@ -158,7 +158,7 @@ export class DOCXExporter<
let children = await this.transformBlocks(b.children, nestingLevel + 1);
- if (!["columnList", "column"].includes(b.type)) {
+ if (!this.isContainerBlock(b)) {
children = children.map((c, _i) => {
// NOTE: nested tables not supported (we can't insert the new Tab before a table)
if (
@@ -183,12 +183,11 @@ export class DOCXExporter<
numberingInstance,
children,
); // TODO: any
- if (["columnList", "column"].includes(b.type)) {
- ret.push(self as Table);
- } else if (Array.isArray(self)) {
- ret.push(...self, ...children);
- } else {
- ret.push(self, ...children);
+ ret.push(...(Array.isArray(self) ? self : [self]));
+ // A container's mapping is handed its children and places them itself,
+ // so they must not be appended after it as well.
+ if (!this.isContainerBlock(b)) {
+ ret.push(...children);
}
}
return ret;
diff --git a/packages/xl-email-exporter/src/react-email/defaultSchema/blocks.tsx b/packages/xl-email-exporter/src/react-email/defaultSchema/blocks.tsx
index a3ba8b653e..716dd41d8a 100644
--- a/packages/xl-email-exporter/src/react-email/defaultSchema/blocks.tsx
+++ b/packages/xl-email-exporter/src/react-email/defaultSchema/blocks.tsx
@@ -542,10 +542,19 @@ export const createReactEmailBlockMappingForDefaultSchema = (
);
},
// Email clients handle side-by-side layout poorly, so columns are stacked:
- // these wrappers render nothing themselves and the exporter's generic child
- // rendering stacks the column contents vertically.
- column: () => <>,
- columnList: () => <>,
+ // these container mappings place their children (which the exporter passes
+ // in) one after another, with no wrapper of their own - so the column
+ // contents render flat, in document order.
+ column: (_block, _exporter, _nestingLevel, _numberedListIndex, children) => (
+ <>{children}
+ ),
+ columnList: (
+ _block,
+ _exporter,
+ _nestingLevel,
+ _numberedListIndex,
+ children,
+ ) => <>{children},
});
// Export the original mapping for backward compatibility
diff --git a/packages/xl-email-exporter/src/react-email/reactEmailExporter.test.tsx b/packages/xl-email-exporter/src/react-email/reactEmailExporter.test.tsx
index 91ef40cf36..38a005d477 100644
--- a/packages/xl-email-exporter/src/react-email/reactEmailExporter.test.tsx
+++ b/packages/xl-email-exporter/src/react-email/reactEmailExporter.test.tsx
@@ -6,12 +6,26 @@ import {
createPageBreakBlockSpec,
defaultBlockSpecs,
} from "@blocknote/core";
+import { ColumnBlock, ColumnListBlock } from "@blocknote/xl-multi-column";
import { testDocument } from "@shared/testDocument.js";
+// Schema including the multi-column blocks, matching the shared testDocument.
+// The columns are container blocks, so the exporter only recognizes them as
+// such (and lets their mappings place the children) when they're in the
+// schema it was constructed with.
+const fullSchema = BlockNoteSchema.create({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ pageBreak: createPageBreakBlockSpec(),
+ column: ColumnBlock,
+ columnList: ColumnListBlock,
+ },
+});
+
describe("react email exporter", () => {
it("should export a document (HTML snapshot)", async () => {
const exporter = new ReactEmailExporter(
- BlockNoteSchema.create(),
+ fullSchema,
reactEmailDefaultSchemaMappings,
);
@@ -21,12 +35,7 @@ describe("react email exporter", () => {
it("should export a document with preview", async () => {
const exporter = new ReactEmailExporter(
- BlockNoteSchema.create({
- blockSpecs: {
- ...defaultBlockSpecs,
- pageBreak: createPageBreakBlockSpec(),
- },
- }),
+ fullSchema,
reactEmailDefaultSchemaMappings,
);
@@ -38,12 +47,7 @@ describe("react email exporter", () => {
it("should export a document with multiple preview lines", async () => {
const exporter = new ReactEmailExporter(
- BlockNoteSchema.create({
- blockSpecs: {
- ...defaultBlockSpecs,
- pageBreak: createPageBreakBlockSpec(),
- },
- }),
+ fullSchema,
reactEmailDefaultSchemaMappings,
);
@@ -655,7 +659,7 @@ describe("react email exporter", () => {
it("should handle document with custom body styles", async () => {
const exporter = new ReactEmailExporter(
- BlockNoteSchema.create(),
+ fullSchema,
reactEmailDefaultSchemaMappings,
);
diff --git a/packages/xl-email-exporter/src/react-email/reactEmailExporter.tsx b/packages/xl-email-exporter/src/react-email/reactEmailExporter.tsx
index c0d19108ae..7b3c617baa 100644
--- a/packages/xl-email-exporter/src/react-email/reactEmailExporter.tsx
+++ b/packages/xl-email-exporter/src/react-email/reactEmailExporter.tsx
@@ -246,22 +246,24 @@ export class ReactEmailExporter<
i = nextIndex;
continue;
}
- // Multi-column blocks stack their content vertically in email (their
- // mappings render nothing themselves). The columns' children are
- // structural, not nested sub-content, so they render flat - no
- // indentation wrapper, and at the *same* nesting level (a level bump
- // per wrapper would report column content as deeply nested to
- // level-sensitive mappings).
- if (b.type === "columnList" || b.type === "column") {
- ret.push(
-
- {await this.transformBlocks(b.children, nestingLevel)}
- ,
+ if (this.isContainerBlock(b)) {
+ // Container blocks (columnList, column, custom containers): the
+ // mapping owns the placement of the children, so they are passed in
+ // and not rendered as an indented sibling list.
+ const containerChildren = await this.transformBlocks(
+ b.children,
+ nestingLevel + 1,
);
+ const containerSelf = (await this.mapBlock(
+ b as any,
+ nestingLevel,
+ 0,
+ containerChildren as any,
+ )) as any;
+ ret.push({containerSelf});
i++;
continue;
}
-
// Non-list blocks
const children = await this.transformBlocks(b.children, nestingLevel + 1);
const self = (await this.mapBlock(b as any, nestingLevel, 0)) as any;
diff --git a/packages/xl-multi-column/src/blocks/Columns/index.ts b/packages/xl-multi-column/src/blocks/Columns/index.ts
index 2e49261ec6..198de85923 100644
--- a/packages/xl-multi-column/src/blocks/Columns/index.ts
+++ b/packages/xl-multi-column/src/blocks/Columns/index.ts
@@ -1,28 +1,82 @@
+import { createBlockSpec } from "@blocknote/core";
+
+import { ColumnResizeExtension } from "../../extensions/ColumnResize/ColumnResizeExtension.js";
import { MultiColumnDropHandlerExtension } from "../../extensions/DropCursor/multiColumnHandleDropPlugin.js";
-import { Column } from "../../pm-nodes/Column.js";
-import { ColumnList } from "../../pm-nodes/ColumnList.js";
-import { createBlockSpecFromTiptapNode } from "@blocknote/core";
+const COLUMN_WIDTH_DEFAULT = 1;
-export const ColumnBlock = createBlockSpecFromTiptapNode(
+export const ColumnBlock = createBlockSpec(
{
- node: Column,
- type: "column",
+ type: "column" as const,
+ propSchema: {
+ width: {
+ default: COLUMN_WIDTH_DEFAULT,
+ },
+ },
content: "none",
+ children: { allow: "any" },
+ placement: "containerOnly",
},
{
- width: {
- default: 1,
+ meta: {
+ draggable: false,
+ },
+ render: (block) => {
+ const dom = document.createElement("div");
+ dom.className = "bn-block-column";
+ dom.style.flexGrow = String(block.props.width ?? COLUMN_WIDTH_DEFAULT);
+
+ return {
+ dom,
+ contentDOM: dom,
+ update: (newNode: {
+ type: { name: string };
+ attrs: { width?: number };
+ }) => {
+ if (newNode.type.name !== "column") {
+ return false;
+ }
+ dom.style.flexGrow = String(
+ newNode.attrs.width ?? COLUMN_WIDTH_DEFAULT,
+ );
+ return true;
+ },
+ };
},
},
- [MultiColumnDropHandlerExtension()],
-);
+ [MultiColumnDropHandlerExtension(), ColumnResizeExtension()],
+)();
-export const ColumnListBlock = createBlockSpecFromTiptapNode(
+export const ColumnListBlock = createBlockSpec(
{
- node: ColumnList,
- type: "columnList",
+ type: "columnList" as const,
+ propSchema: {},
content: "none",
+ children: {
+ allow: ["column"],
+ min: 2,
+ whenEmptied: "unwrap",
+ // Everything crosses the column list's edge, e.g. a text selection
+ // dragged across columns.
+ boundary: "open",
+ },
+ },
+ {
+ meta: {
+ draggable: false,
+ },
+ render: () => {
+ const dom = document.createElement("div");
+ dom.className = "bn-block-column-list";
+ dom.style.display = "flex";
+
+ return {
+ dom,
+ contentDOM: dom,
+ update: (newNode: { type: { name: string } }) => {
+ return newNode.type.name === "columnList";
+ },
+ };
+ },
},
- {},
-);
+)();
diff --git a/packages/xl-multi-column/src/extensions/ColumnResize/ColumnResizeExtension.ts b/packages/xl-multi-column/src/extensions/ColumnResize/ColumnResizeExtension.ts
index 5713466a6d..1d2da18690 100644
--- a/packages/xl-multi-column/src/extensions/ColumnResize/ColumnResizeExtension.ts
+++ b/packages/xl-multi-column/src/extensions/ColumnResize/ColumnResizeExtension.ts
@@ -1,6 +1,5 @@
-import { BlockNoteEditor, getNodeById } from "@blocknote/core";
+import { BlockNoteEditor, createExtension, getNodeById } from "@blocknote/core";
import { SideMenuExtension } from "@blocknote/core/extensions";
-import { Extension } from "@tiptap/core";
import { Node } from "prosemirror-model";
import { Plugin, PluginKey, PluginView } from "prosemirror-state";
import { Decoration, DecorationSet, EditorView } from "prosemirror-view";
@@ -41,13 +40,71 @@ type ColumnResizeState = {
columnList: ColumnData;
};
-type ColumnState =
+// Exported for tests only - not part of the package's public API.
+export type ColumnState =
| ColumnDefaultState
| ColumnHoverState
| ColumnHoverColumnListState
| ColumnResizeState;
-const columnResizePluginKey = new PluginKey("ColumnResizePlugin");
+// Exported for tests only - not part of the package's public API.
+export const columnResizePluginKey = new PluginKey(
+ "ColumnResizePlugin",
+);
+
+// Re-resolves stored column data against a (possibly changed) doc, since the
+// stored node and position may be stale. Returns undefined if the node no
+// longer exists in the doc.
+function refreshColumnData(
+ data: T,
+ doc: Node,
+): T | undefined {
+ const nodeAndPos = getNodeById(data.id, doc);
+ if (!nodeAndPos) {
+ return undefined;
+ }
+
+ return { ...data, ...nodeAndPos };
+}
+
+// Re-resolves all column data stored in the plugin state against a (possibly
+// changed) doc. Falls back to the default state if any of the referenced
+// nodes no longer exist - e.g. when a backspace removes a hovered column, or
+// unwraps the column list entirely - so decorations are never built from
+// positions that are invalid in the new doc.
+function refreshColumnState(state: ColumnState, doc: Node): ColumnState {
+ switch (state.type) {
+ case "default":
+ return state;
+ case "hover-column-list": {
+ const columnList = refreshColumnData(state.columnList, doc);
+
+ return columnList ? { ...state, columnList } : { type: "default" };
+ }
+ case "hover-column": {
+ const columnList = refreshColumnData(state.columnList, doc);
+ const leftColumn = refreshColumnData(state.leftColumn, doc);
+ const rightColumn = refreshColumnData(state.rightColumn, doc);
+
+ if (!columnList || !leftColumn || !rightColumn) {
+ return { type: "default" };
+ }
+
+ return { ...state, columnList, leftColumn, rightColumn };
+ }
+ case "resize": {
+ const columnList = refreshColumnData(state.columnList, doc);
+ const leftColumn = refreshColumnData(state.leftColumn, doc);
+ const rightColumn = refreshColumnData(state.rightColumn, doc);
+
+ if (!columnList || !leftColumn || !rightColumn) {
+ return { type: "default" };
+ }
+
+ return { ...state, columnList, leftColumn, rightColumn };
+ }
+ }
+}
class ColumnResizePluginView implements PluginView {
editor: BlockNoteEditor;
@@ -428,22 +485,26 @@ const createColumnResizePlugin = (editor: BlockNoteEditor) =>
state: {
init: () => ({ type: "default" }) as ColumnState,
apply: (tr, oldPluginState) => {
- const newPluginState = tr.getMeta(columnResizePluginKey) as
+ const metaPluginState = tr.getMeta(columnResizePluginKey) as
| ColumnState
| undefined;
- return newPluginState === undefined ? oldPluginState : newPluginState;
+ const pluginState =
+ metaPluginState === undefined ? oldPluginState : metaPluginState;
+
+ // The stored column nodes & positions were resolved against an older
+ // doc, so when the doc changes they must be re-resolved against the
+ // new one - a backspace may have removed a hovered column or
+ // unwrapped the column list entirely.
+ return tr.docChanged
+ ? refreshColumnState(pluginState, tr.doc)
+ : pluginState;
},
},
view: (view) => new ColumnResizePluginView(editor, view),
});
-export const createColumnResizeExtension = (
- editor: BlockNoteEditor,
-) =>
- Extension.create({
- name: "columnResize",
- addProseMirrorPlugins() {
- return [createColumnResizePlugin(editor)];
- },
- });
+export const ColumnResizeExtension = createExtension(({ editor }) => ({
+ key: "columnResize",
+ prosemirrorPlugins: [createColumnResizePlugin(editor)],
+}));
diff --git a/packages/xl-multi-column/src/extensions/DropCursor/multiColumnDropCursor.ts b/packages/xl-multi-column/src/extensions/DropCursor/multiColumnDropCursor.ts
index 77d93b7f4a..8f05068da3 100644
--- a/packages/xl-multi-column/src/extensions/DropCursor/multiColumnDropCursor.ts
+++ b/packages/xl-multi-column/src/extensions/DropCursor/multiColumnDropCursor.ts
@@ -1,4 +1,8 @@
-import { type DropCursorHooks, getNearestBlockPos } from "@blocknote/core";
+import {
+ type DropCursorHooks,
+ getNearestBlockPos,
+ isContainerNode,
+} from "@blocknote/core";
import type { EditorState } from "prosemirror-state";
import type { EditorView } from "prosemirror-view";
@@ -31,10 +35,16 @@ export function detectEdgePosition(
const blockPos = getNearestBlockPos(state.doc, eventPos.pos);
- // If we're at a block that's in a column, we want to compare the mouse position to the column, not the block inside it
- // Why? Because we want to insert a new column in the columnList, instead of a new columnList inside of the column
+ // If we're at a block inside a column of a columnList, we want to compare
+ // the mouse position to the column, not the block inside it.
+ // Why? Because we want to insert a new sibling column in the columnList
+ // instead of a new container inside the column.
let resolved = state.doc.resolve(blockPos.posBeforeNode);
- if (resolved.parent.type.name === "column") {
+ if (
+ isContainerNode(resolved.parent.type) &&
+ resolved.depth > 0 &&
+ state.doc.resolve(resolved.before()).parent.type.name === "columnList"
+ ) {
resolved = state.doc.resolve(resolved.before());
}
diff --git a/packages/xl-multi-column/src/extensions/DropCursor/multiColumnHandleDropPlugin.ts b/packages/xl-multi-column/src/extensions/DropCursor/multiColumnHandleDropPlugin.ts
index a762f78d96..f12865903e 100644
--- a/packages/xl-multi-column/src/extensions/DropCursor/multiColumnHandleDropPlugin.ts
+++ b/packages/xl-multi-column/src/extensions/DropCursor/multiColumnHandleDropPlugin.ts
@@ -3,7 +3,8 @@ import {
UniqueID,
createExtension,
fragmentToBlocks,
- getBlockInfo,
+ getBlockInfoFromNode,
+ isContainerNode,
nodeToBlock,
} from "@blocknote/core";
import { Plugin } from "prosemirror-state";
@@ -26,7 +27,10 @@ export function createMultiColumnHandleDropPlugin(
return false; // Let ProseMirror handle the drop (e.g. outside editor bounds)
}
- const blockInfo = getBlockInfo(edgePos);
+ const blockInfo = getBlockInfoFromNode(
+ edgePos.node,
+ edgePos.posBeforeNode,
+ );
// Only handle edge drops (left/right)
if (edgePos.position === "regular") {
@@ -42,13 +46,24 @@ export function createMultiColumnHandleDropPlugin(
}
const draggedBlockIds = new Set(draggedBlocks.map((block) => block.id));
- if (blockInfo.blockNoteType === "column") {
+ // Whether the edge target is a `columnList` (after `detectEdgePosition`
+ // hoisted blocks inside a column to the column itself, the target's
+ // parent is the columnList).
+ const $target = view.state.doc.resolve(blockInfo.block.beforePos);
+ const targetInHorizontalContainer =
+ $target.node().type.name === "columnList";
+
+ if (targetInHorizontalContainer) {
// The user is dropping the target column's entire contents on the
// column's own edge - the new column would just replace the
// emptied target in the same position, so do nothing. This also
// keeps the column's ID and width instead of resetting them.
let allTargetChildrenDragged = true;
- blockInfo.bnBlock.node.forEach((child) => {
+ // A column is a pure container: its `children` node is the column
+ // node itself.
+ const columnChildren =
+ blockInfo.children?.node ?? blockInfo.block.node;
+ columnChildren.forEach((child) => {
if (!draggedBlockIds.has(child.attrs.id)) {
allTargetChildrenDragged = false;
}
@@ -57,16 +72,22 @@ export function createMultiColumnHandleDropPlugin(
return true;
}
- // Insert new column in existing columnList
- const parentBlock = view.state.doc
- .resolve(blockInfo.bnBlock.beforePos)
- .node();
+ // Insert a new sibling child in the existing horizontal container
+ // (e.g. a new column in the columnList).
+ const parentBlock = $target.node();
const columnList = nodeToBlock(
parentBlock,
view.state.doc,
);
+ // Whether the horizontal container's children are typed child
+ // containers (like `column`) that wrap the actual blocks, or plain
+ // blocks spliced in directly.
+ const targetIsChildContainer = isContainerNode(
+ blockInfo.block.node.type,
+ );
+
// Normalize column widths to average of 1
// In a `columnList`, we expect that the average width of each column
// is 1. However, there are cases in which this stops being true. For
@@ -74,27 +95,43 @@ export function createMultiColumnHandleDropPlugin(
// the average width to go down. This isn't really an issue until the
// user tries to add a new column, which will, in this case, be wider
// than expected. Therefore, we normalize the column widths to an
- // average of 1 here to avoid this issue.
- let sumColumnWidthPercent = 0;
- columnList.children.forEach((column) => {
- sumColumnWidthPercent += column.props.width as number;
- });
- const avgColumnWidthPercent =
- sumColumnWidthPercent / columnList.children.length;
-
- // If the average column width is not 1, normalize it. We're dealing
- // with floats so we need a small margin to account for precision
- // errors.
- if (avgColumnWidthPercent < 0.99 || avgColumnWidthPercent > 1.01) {
- const scalingFactor = 1 / avgColumnWidthPercent;
-
+ // average of 1 here to avoid this issue. (Only applies to child
+ // containers with a numeric `width` prop, i.e. columns.)
+ if (
+ columnList.children.every(
+ (column) => typeof column.props.width === "number",
+ )
+ ) {
+ let sumColumnWidthPercent = 0;
columnList.children.forEach((column) => {
- column.props.width =
- (column.props.width as number) * scalingFactor;
+ sumColumnWidthPercent += column.props.width as number;
});
+ const avgColumnWidthPercent =
+ sumColumnWidthPercent / columnList.children.length;
+
+ // If the average column width is not 1, normalize it. We're
+ // dealing with floats so we need a small margin to account for
+ // precision errors.
+ if (avgColumnWidthPercent < 0.99 || avgColumnWidthPercent > 1.01) {
+ const scalingFactor = 1 / avgColumnWidthPercent;
+
+ columnList.children.forEach((column) => {
+ column.props.width =
+ (column.props.width as number) * scalingFactor;
+ });
+ }
}
- const targetColumnId = blockInfo.bnBlock.node.attrs.id;
+ const targetColumnId = blockInfo.block.node.attrs.id;
+
+ // The target itself is one of the dragged blocks (only possible
+ // when the container holds plain blocks directly) - the dragged
+ // blocks would be re-inserted around their own position, so do
+ // nothing, same as dropping a typed target's entire contents on
+ // its own edge.
+ if (!targetIsChildContainer && draggedBlockIds.has(targetColumnId)) {
+ return true;
+ }
// Tracks which of the dragged blocks were already in the column
// list - removing those from their old position is handled by
@@ -103,20 +140,36 @@ export function createMultiColumnHandleDropPlugin(
const remainingColumns = columnList.children
// If any of the dragged blocks are in one of the columns, remove
// them.
- .map((column) => ({
- ...column,
- children: column.children.filter((block) => {
- if (!draggedBlockIds.has(block.id)) {
- return true;
- }
-
- blocksAlreadyInColumnList.add(block.id);
- return false;
- }),
- }))
+ .map((column) =>
+ targetIsChildContainer
+ ? {
+ ...column,
+ children: column.children.filter((block) => {
+ if (!draggedBlockIds.has(block.id)) {
+ return true;
+ }
+
+ blocksAlreadyInColumnList.add(block.id);
+ return false;
+ }),
+ }
+ : column,
+ )
// Remove empty columns (can happen when dragged blocks are
- // removed).
- .filter((column) => column.children.length > 0);
+ // removed) and, when the container holds plain blocks directly,
+ // dragged direct children (which are re-inserted at the drop
+ // position).
+ .filter((column) => {
+ if (targetIsChildContainer) {
+ return column.children.length > 0;
+ }
+ if (!draggedBlockIds.has(column.id)) {
+ return true;
+ }
+
+ blocksAlreadyInColumnList.add(column.id);
+ return false;
+ });
// The insertion index is computed on the remaining columns, as
// removing an emptied column before the drop target shifts the
@@ -134,15 +187,25 @@ export function createMultiColumnHandleDropPlugin(
const insertionIndex =
edgePos.position === "left" ? targetIndex : targetIndex + 1;
- // Insert the dragged blocks as a new column in the correct
- // position.
- const newChildren = remainingColumns.toSpliced(insertionIndex, 0, {
- type: "column",
- children: draggedBlocks,
- props: {},
- content: undefined,
- id: UniqueID.options.generateID(),
- });
+ // Insert the dragged blocks in the correct position, wrapped in a
+ // new child container (e.g. a new `column`) when the container's
+ // children are typed containers, or spliced in directly otherwise.
+ const insertedChildren = targetIsChildContainer
+ ? [
+ {
+ type: blockInfo.blockNoteType,
+ children: draggedBlocks,
+ props: {},
+ content: undefined,
+ id: UniqueID.options.generateID(),
+ },
+ ]
+ : draggedBlocks;
+ const newChildren = remainingColumns.toSpliced(
+ insertionIndex,
+ 0,
+ ...insertedChildren,
+ );
const blocksToRemove = draggedBlocks.filter(
(block) =>
@@ -158,7 +221,7 @@ export function createMultiColumnHandleDropPlugin(
});
} else {
// Create new columnList with blocks as columns
- const block = nodeToBlock(blockInfo.bnBlock.node, view.state.doc);
+ const block = nodeToBlock(blockInfo.block.node, view.state.doc);
// The user is dropping next to one of the blocks being dragged - do
// nothing.
diff --git a/packages/xl-multi-column/src/pm-nodes/Column.ts b/packages/xl-multi-column/src/pm-nodes/Column.ts
deleted file mode 100644
index dccf60c74b..0000000000
--- a/packages/xl-multi-column/src/pm-nodes/Column.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-import { suggestionMarks } from "@blocknote/core";
-import { Node } from "@tiptap/core";
-
-import { createColumnResizeExtension } from "../extensions/ColumnResize/ColumnResizeExtension.js";
-
-export const Column = Node.create({
- name: "column",
- group: "bnBlock childContainer",
- // A block always contains content, and optionally a blockGroup which contains nested blocks
- content: "blockContainer+",
- priority: 40,
- defining: true,
- marks() {
- return suggestionMarks(this.editor);
- },
- addAttributes() {
- return {
- width: {
- // Why does each column have a default width of 1, i.e. 100%? Because
- // when creating a new column, we want to make sure that existing
- // column widths are preserved, while the new one also has a sensible
- // width. If we'd set it so all column widths must add up to 100%
- // instead, then each time a new column is created, we'd have to assign
- // it a width depending on the total number of columns and also adjust
- // the widths of the other columns. The same can be said for using px
- // instead of percent widths and making them add to the editor width. So
- // using this method is both simpler and computationally cheaper. This
- // is possible because we can set the `flex-grow` property to the width
- // value, which handles all the resizing for us, instead of manually
- // having to set the `width` property of each column.
- default: 1,
- parseHTML: (element) => {
- const attr = element.getAttribute("data-width");
- if (attr === null) {
- return null;
- }
-
- const parsed = parseFloat(attr);
- if (isFinite(parsed)) {
- return parsed;
- }
-
- return null;
- },
- renderHTML: (attributes) => {
- return {
- "data-width": (attributes.width as number).toString(),
- style: `flex-grow: ${attributes.width as number};`,
- };
- },
- },
- };
- },
-
- parseHTML() {
- return [
- {
- tag: "div",
- getAttrs: (element) => {
- if (typeof element === "string") {
- return false;
- }
-
- if (element.getAttribute("data-node-type") === this.name) {
- return {};
- }
-
- return false;
- },
- },
- ];
- },
-
- renderHTML({ HTMLAttributes }) {
- const column = document.createElement("div");
- column.className = "bn-block-column";
- column.setAttribute("data-node-type", this.name);
- for (const [attribute, value] of Object.entries(HTMLAttributes)) {
- column.setAttribute(attribute, value as any); // TODO as any
- }
-
- return {
- dom: column,
- contentDOM: column,
- };
- },
-
- addExtensions() {
- return [createColumnResizeExtension(this.options.editor)];
- },
-});
diff --git a/packages/xl-multi-column/src/pm-nodes/ColumnList.ts b/packages/xl-multi-column/src/pm-nodes/ColumnList.ts
deleted file mode 100644
index eeb06f4d4e..0000000000
--- a/packages/xl-multi-column/src/pm-nodes/ColumnList.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { suggestionMarks } from "@blocknote/core";
-import { Node } from "@tiptap/core";
-
-export const ColumnList = Node.create({
- name: "columnList",
- group: "childContainer bnBlock blockGroupChild",
- // A block always contains content, and optionally a blockGroup which contains nested blocks
- content: "column column+", // min two columns
- priority: 40, // should be below blockContainer
- defining: true,
- marks() {
- return suggestionMarks(this.editor);
- },
- parseHTML() {
- return [
- {
- tag: "div",
- getAttrs: (element) => {
- if (typeof element === "string") {
- return false;
- }
-
- if (element.getAttribute("data-node-type") === this.name) {
- return {};
- }
-
- return false;
- },
- },
- ];
- },
-
- renderHTML({ HTMLAttributes }) {
- const columnList = document.createElement("div");
- columnList.className = "bn-block-column-list";
- columnList.setAttribute("data-node-type", this.name);
- for (const [attribute, value] of Object.entries(HTMLAttributes)) {
- columnList.setAttribute(attribute, value as any); // TODO as any
- }
- columnList.style.display = "flex";
-
- return {
- dom: columnList,
- contentDOM: columnList,
- };
- },
-});
diff --git a/packages/xl-multi-column/src/test/commands/__snapshots__/insertBlocks.test.ts.snap b/packages/xl-multi-column/src/test/commands/__snapshots__/insertBlocks.test.ts.snap
index 476357f363..c6019e4dd8 100644
--- a/packages/xl-multi-column/src/test/commands/__snapshots__/insertBlocks.test.ts.snap
+++ b/packages/xl-multi-column/src/test/commands/__snapshots__/insertBlocks.test.ts.snap
@@ -429,6 +429,226 @@ exports[`Test insertBlocks > Insert column with paragraph into column list 1`] =
]
`;
+exports[`Test insertBlocks > Insert empty column list 1`] = `
+[
+ {
+ "children": [
+ {
+ "children": [],
+ "content": [
+ {
+ "styles": {},
+ "text": "Nested Paragraph 0",
+ "type": "text",
+ },
+ ],
+ "id": "nested-paragraph-0",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ ],
+ "content": [
+ {
+ "styles": {},
+ "text": "Paragraph 0",
+ "type": "text",
+ },
+ ],
+ "id": "paragraph-0",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ {
+ "children": [
+ {
+ "children": [
+ {
+ "children": [],
+ "content": [],
+ "id": "1",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ ],
+ "content": undefined,
+ "id": "2",
+ "props": {
+ "width": 1,
+ },
+ "type": "column",
+ },
+ {
+ "children": [
+ {
+ "children": [],
+ "content": [],
+ "id": "3",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ ],
+ "content": undefined,
+ "id": "4",
+ "props": {
+ "width": 1,
+ },
+ "type": "column",
+ },
+ ],
+ "content": undefined,
+ "id": "0",
+ "props": {},
+ "type": "columnList",
+ },
+ {
+ "children": [],
+ "content": [
+ {
+ "styles": {},
+ "text": "Paragraph 1",
+ "type": "text",
+ },
+ ],
+ "id": "paragraph-1",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ {
+ "children": [
+ {
+ "children": [
+ {
+ "children": [],
+ "content": [
+ {
+ "styles": {},
+ "text": "Column Paragraph 0",
+ "type": "text",
+ },
+ ],
+ "id": "column-paragraph-0",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ {
+ "children": [],
+ "content": [
+ {
+ "styles": {},
+ "text": "Column Paragraph 1",
+ "type": "text",
+ },
+ ],
+ "id": "column-paragraph-1",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ ],
+ "content": undefined,
+ "id": "column-0",
+ "props": {
+ "width": 1,
+ },
+ "type": "column",
+ },
+ {
+ "children": [
+ {
+ "children": [],
+ "content": [
+ {
+ "styles": {},
+ "text": "Column Paragraph 2",
+ "type": "text",
+ },
+ ],
+ "id": "column-paragraph-2",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ {
+ "children": [],
+ "content": [
+ {
+ "styles": {},
+ "text": "Column Paragraph 3",
+ "type": "text",
+ },
+ ],
+ "id": "column-paragraph-3",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+ ],
+ "content": undefined,
+ "id": "column-1",
+ "props": {
+ "width": 1,
+ },
+ "type": "column",
+ },
+ ],
+ "content": undefined,
+ "id": "column-list-0",
+ "props": {},
+ "type": "columnList",
+ },
+ {
+ "children": [],
+ "content": [
+ {
+ "styles": {},
+ "text": "Paragraph 2",
+ "type": "text",
+ },
+ ],
+ "id": "paragraph-2",
+ "props": {
+ "backgroundColor": "default",
+ "textAlignment": "left",
+ "textColor": "default",
+ },
+ "type": "paragraph",
+ },
+]
+`;
+
exports[`Test insertBlocks > Insert paragraph into column 1`] = `
[
{
diff --git a/packages/xl-multi-column/src/test/commands/enter.test.ts b/packages/xl-multi-column/src/test/commands/enter.test.ts
new file mode 100644
index 0000000000..9c121b97b3
--- /dev/null
+++ b/packages/xl-multi-column/src/test/commands/enter.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { BlockNoteEditor } from "@blocknote/core";
+
+import { setupTestEnv } from "../setupTestEnv.js";
+
+const getEditor = setupTestEnv();
+
+function pressEnter(editor: BlockNoteEditor) {
+ const view = editor._tiptapEditor.view;
+ const event = new KeyboardEvent("keydown", {
+ key: "Enter",
+ code: "Enter",
+ keyCode: 13,
+ bubbles: true,
+ });
+ view.someProp("handleKeyDown", (f: any) => f(view, event));
+}
+
+// Columns have no special Enter config: like any non-sealed container, an
+// empty last block escapes on Enter. The generic mechanics (escape, ascent
+// past levels that can't hold the block, mid-container stays) are covered in
+// core's `containers.browser.test.ts`; these two tests use the real column
+// schema and its interaction with the column-list repair.
+describe("Enter exit from columns", () => {
+ it("typing then double-Enter escapes in two presses", () => {
+ const editor = getEditor();
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "columnList",
+ id: "cl-0",
+ children: [
+ {
+ type: "column",
+ id: "col-1",
+ children: [{ id: "col1-para", type: "paragraph", content: "col1" }],
+ },
+ {
+ type: "column",
+ id: "col-2",
+ children: [{ id: "col2-para", type: "paragraph", content: "col2" }],
+ },
+ ],
+ },
+ ]);
+
+ editor.setTextCursorPosition("col2-para", "end");
+ pressEnter(editor);
+
+ // First press: a new empty block inside the column.
+ expect(editor.document.map((block) => block.id)).toEqual(["cl-0"]);
+ const children = editor.getBlock("col-2")!.children;
+ expect(children).toHaveLength(2);
+ const created = children[1].id;
+ expect(editor.getTextCursorPosition().block.id).toBe(created);
+
+ pressEnter(editor);
+
+ // Second press: that block moves below the column list (a block can't sit
+ // between columns, so the escape lands below the whole list), caret along.
+ expect(editor.getBlock("col-2")!.children.map((child) => child.id)).toEqual(
+ ["col2-para"],
+ );
+ expect(editor.document.map((block) => block.id)).toEqual(["cl-0", created]);
+ expect(editor.getTextCursorPosition().block.id).toBe(created);
+ });
+
+ it("escaping a column's only block dissolves it and unwraps the list", () => {
+ // The exit empties the column, so the column list's `whenEmptied: "unwrap"`
+ // repair kicks in: the emptied column disappears, and the one-column
+ // list unwraps to the surviving column's blocks.
+ const editor = getEditor();
+ editor.replaceBlocks(editor.document, [
+ {
+ type: "columnList",
+ id: "cl-0",
+ children: [
+ {
+ type: "column",
+ id: "col-1",
+ children: [{ id: "col1-para", type: "paragraph", content: "col1" }],
+ },
+ {
+ type: "column",
+ id: "col-2",
+ children: [{ id: "col2-empty", type: "paragraph", content: "" }],
+ },
+ ],
+ },
+ ]);
+
+ editor.setTextCursorPosition("col2-empty", "end");
+ pressEnter(editor);
+
+ expect(editor.document.map((block) => block.id)).toEqual([
+ "col1-para",
+ "col2-empty",
+ ]);
+ });
+});
diff --git a/packages/xl-multi-column/src/test/commands/insertBlocks.test.ts b/packages/xl-multi-column/src/test/commands/insertBlocks.test.ts
index 319ceda379..17372c5668 100644
--- a/packages/xl-multi-column/src/test/commands/insertBlocks.test.ts
+++ b/packages/xl-multi-column/src/test/commands/insertBlocks.test.ts
@@ -6,14 +6,11 @@ const getEditor = setupTestEnv();
describe("Test insertBlocks", () => {
it("Insert empty column list", () => {
- // should throw an error as we don't allow empty column lists
- expect(() => {
- getEditor().insertBlocks(
- [{ type: "columnList" }],
- "paragraph-0",
- "after",
- );
- }).toThrow();
+ // An empty column list is filled to a valid two-column list (each with an
+ // empty paragraph) instead of throwing.
+ getEditor().insertBlocks([{ type: "columnList" }], "paragraph-0", "after");
+
+ expect(getEditor().document).toMatchSnapshot();
});
it("Insert column list with empty column", () => {
diff --git a/packages/xl-multi-column/src/test/commands/util/__snapshots__/fixColumnLists.test.ts.snap b/packages/xl-multi-column/src/test/commands/util/__snapshots__/fixContainer.test.ts.snap
similarity index 95%
rename from packages/xl-multi-column/src/test/commands/util/__snapshots__/fixColumnLists.test.ts.snap
rename to packages/xl-multi-column/src/test/commands/util/__snapshots__/fixContainer.test.ts.snap
index 87b5f2e588..a5d8ddf91f 100644
--- a/packages/xl-multi-column/src/test/commands/util/__snapshots__/fixColumnLists.test.ts.snap
+++ b/packages/xl-multi-column/src/test/commands/util/__snapshots__/fixContainer.test.ts.snap
@@ -1,6 +1,6 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-exports[`Test fixColumnList > First of two columns empty 1`] = `
+exports[`Test fixContainer > First of two columns empty 1`] = `
{
"content": [
{
@@ -35,7 +35,7 @@ exports[`Test fixColumnList > First of two columns empty 1`] = `
}
`;
-exports[`Test fixColumnList > Last of two columns empty 1`] = `
+exports[`Test fixContainer > Last of two columns empty 1`] = `
{
"content": [
{
@@ -70,7 +70,7 @@ exports[`Test fixColumnList > Last of two columns empty 1`] = `
}
`;
-exports[`Test fixColumnList > Two empty columns 1`] = `
+exports[`Test fixContainer > Two empty columns 1`] = `
{
"content": [
{
@@ -99,7 +99,7 @@ exports[`Test fixColumnList > Two empty columns 1`] = `
}
`;
-exports[`Test removeEmptyColumns > First of two columns empty 1`] = `
+exports[`Test removeEmptyChildren > First of two columns empty 1`] = `
{
"content": [
{
@@ -176,7 +176,7 @@ exports[`Test removeEmptyColumns > First of two columns empty 1`] = `
}
`;
-exports[`Test removeEmptyColumns > Last of two columns empty 1`] = `
+exports[`Test removeEmptyChildren > Last of two columns empty 1`] = `
{
"content": [
{
@@ -253,7 +253,7 @@ exports[`Test removeEmptyColumns > Last of two columns empty 1`] = `
}
`;
-exports[`Test removeEmptyColumns > Start and end columns empty 1`] = `
+exports[`Test removeEmptyChildren > Start and end columns empty 1`] = `
{
"content": [
{
@@ -336,7 +336,7 @@ exports[`Test removeEmptyColumns > Start and end columns empty 1`] = `
}
`;
-exports[`Test removeEmptyColumns > Two empty columns 1`] = `
+exports[`Test removeEmptyChildren > Two empty columns 1`] = `
{
"content": [
{
diff --git a/packages/xl-multi-column/src/test/commands/util/fixColumnLists.test.ts b/packages/xl-multi-column/src/test/commands/util/fixContainer.test.ts
similarity index 91%
rename from packages/xl-multi-column/src/test/commands/util/fixColumnLists.test.ts
rename to packages/xl-multi-column/src/test/commands/util/fixContainer.test.ts
index b5bd190c6d..d41cc00f72 100644
--- a/packages/xl-multi-column/src/test/commands/util/fixColumnLists.test.ts
+++ b/packages/xl-multi-column/src/test/commands/util/fixContainer.test.ts
@@ -2,14 +2,14 @@ import { describe, expect, it } from "vite-plus/test";
import { setupTestEnv } from "../../setupTestEnv.js";
import {
- fixColumnList,
- isEmptyColumn,
- removeEmptyColumns,
-} from "@blocknote/core";
+ fixContainer,
+ isEmptyContainerChild,
+ removeEmptyChildren,
+} from "@blocknote/core/internal";
const getEditor = setupTestEnv();
-describe("Test isEmptyColumn", () => {
+describe("Test isEmptyContainerChild", () => {
it("Empty blocks", () => {
const schema = getEditor()._tiptapEditor.schema;
@@ -19,7 +19,7 @@ describe("Test isEmptyColumn", () => {
]),
]);
- expect(isEmptyColumn(column)).toBeTruthy();
+ expect(isEmptyContainerChild(column)).toBeTruthy();
});
it("Multiple blocks", () => {
@@ -34,7 +34,7 @@ describe("Test isEmptyColumn", () => {
]),
]);
- expect(isEmptyColumn(column)).toBeFalsy();
+ expect(isEmptyContainerChild(column)).toBeFalsy();
});
it("Block with children", () => {
@@ -51,7 +51,7 @@ describe("Test isEmptyColumn", () => {
]),
]);
- expect(isEmptyColumn(column)).toBeFalsy();
+ expect(isEmptyContainerChild(column)).toBeFalsy();
});
it("Block with text", () => {
@@ -65,7 +65,7 @@ describe("Test isEmptyColumn", () => {
]),
]);
- expect(isEmptyColumn(column)).toBeFalsy();
+ expect(isEmptyContainerChild(column)).toBeFalsy();
});
it("Non-text block", () => {
@@ -77,11 +77,11 @@ describe("Test isEmptyColumn", () => {
]),
]);
- expect(isEmptyColumn(column)).toBeFalsy();
+ expect(isEmptyContainerChild(column)).toBeFalsy();
});
});
-describe("Test removeEmptyColumns", () => {
+describe("Test removeEmptyChildren", () => {
it("Start and end columns empty", () => {
const editor = getEditor();
const schema = editor._tiptapEditor.schema;
@@ -116,7 +116,7 @@ describe("Test removeEmptyColumns", () => {
const tr = editor.prosemirrorState.tr;
tr.replaceRangeWith(1, tr.doc.firstChild!.content.size, columnList);
- removeEmptyColumns(tr, 1);
+ removeEmptyChildren(tr, 1);
expect(tr.doc).toMatchSnapshot();
});
@@ -143,7 +143,7 @@ describe("Test removeEmptyColumns", () => {
const tr = editor.prosemirrorState.tr;
tr.replaceRangeWith(1, tr.doc.firstChild!.content.size, columnList);
- removeEmptyColumns(tr, 1);
+ removeEmptyChildren(tr, 1);
expect(tr.doc).toMatchSnapshot();
});
@@ -170,7 +170,7 @@ describe("Test removeEmptyColumns", () => {
const tr = editor.prosemirrorState.tr;
tr.replaceRangeWith(1, tr.doc.firstChild!.content.size, columnList);
- removeEmptyColumns(tr, 1);
+ removeEmptyChildren(tr, 1);
expect(tr.doc).toMatchSnapshot();
});
@@ -195,13 +195,13 @@ describe("Test removeEmptyColumns", () => {
const tr = editor.prosemirrorState.tr;
tr.replaceRangeWith(1, tr.doc.firstChild!.content.size, columnList);
- removeEmptyColumns(tr, 1);
+ removeEmptyChildren(tr, 1);
expect(tr.doc).toMatchSnapshot();
});
});
-describe("Test fixColumnList", () => {
+describe("Test fixContainer", () => {
it("First of two columns empty", () => {
const editor = getEditor();
const schema = editor._tiptapEditor.schema;
@@ -224,7 +224,7 @@ describe("Test fixColumnList", () => {
const tr = editor.prosemirrorState.tr;
tr.replaceRangeWith(1, tr.doc.firstChild!.content.size, columnList);
- fixColumnList(tr, 1);
+ fixContainer(tr, 1);
expect(tr.doc).toMatchSnapshot();
});
@@ -251,7 +251,7 @@ describe("Test fixColumnList", () => {
const tr = editor.prosemirrorState.tr;
tr.replaceRangeWith(1, tr.doc.firstChild!.content.size, columnList);
- fixColumnList(tr, 1);
+ fixContainer(tr, 1);
expect(tr.doc).toMatchSnapshot();
});
@@ -276,7 +276,7 @@ describe("Test fixColumnList", () => {
const tr = editor.prosemirrorState.tr;
tr.replaceRangeWith(1, tr.doc.firstChild!.content.size, columnList);
- fixColumnList(tr, 1);
+ fixContainer(tr, 1);
expect(tr.doc).toMatchSnapshot();
});
diff --git a/packages/xl-multi-column/src/test/conversions/__snapshots__/multi-column/undefined/external.html b/packages/xl-multi-column/src/test/conversions/__snapshots__/multi-column/undefined/external.html
index 2237513b6b..3c8a8e4273 100644
--- a/packages/xl-multi-column/src/test/conversions/__snapshots__/multi-column/undefined/external.html
+++ b/packages/xl-multi-column/src/test/conversions/__snapshots__/multi-column/undefined/external.html
@@ -1 +1 @@
-
Column Paragraph 0
Column Paragraph 1
Column Paragraph 2
Column Paragraph 3
\ No newline at end of file
+
Column Paragraph 0
Column Paragraph 1
Column Paragraph 2
Column Paragraph 3
\ No newline at end of file
diff --git a/packages/xl-multi-column/src/test/conversions/__snapshots__/multi-column/undefined/internal.html b/packages/xl-multi-column/src/test/conversions/__snapshots__/multi-column/undefined/internal.html
index 5876b3bd03..0d6612056e 100644
--- a/packages/xl-multi-column/src/test/conversions/__snapshots__/multi-column/undefined/internal.html
+++ b/packages/xl-multi-column/src/test/conversions/__snapshots__/multi-column/undefined/internal.html
@@ -1 +1 @@
-
Column Paragraph 0
Column Paragraph 1
Column Paragraph 2
Column Paragraph 3
\ No newline at end of file
+
Column Paragraph 0
Column Paragraph 1
Column Paragraph 2
Column Paragraph 3
\ No newline at end of file
diff --git a/packages/xl-multi-column/src/test/extensions/columnResize.test.ts b/packages/xl-multi-column/src/test/extensions/columnResize.test.ts
new file mode 100644
index 0000000000..964a61de1a
--- /dev/null
+++ b/packages/xl-multi-column/src/test/extensions/columnResize.test.ts
@@ -0,0 +1,101 @@
+import { getNodeById } from "@blocknote/core";
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ ColumnState,
+ columnResizePluginKey,
+} from "../../extensions/ColumnResize/ColumnResizeExtension.js";
+import { setupTestEnv } from "../setupTestEnv.js";
+
+const getEditor = setupTestEnv();
+
+// Puts the column resize plugin into the state it would be in when the user
+// hovers the boundary between the two columns of "column-list-0" in the test
+// document, as the plugin's mouse handlers would.
+function hoverColumnBoundary() {
+ const editor = getEditor();
+ const view = editor._tiptapEditor.view;
+
+ const columnList = getNodeById("column-list-0", view.state.doc);
+ const leftColumn = getNodeById("column-0", view.state.doc);
+ const rightColumn = getNodeById("column-1", view.state.doc);
+
+ if (!columnList || !leftColumn || !rightColumn) {
+ throw new Error("Test document is missing expected columns");
+ }
+
+ const hoverState: ColumnState = {
+ type: "hover-column",
+ columnList: {
+ element: document.createElement("div"),
+ id: "column-list-0",
+ ...columnList,
+ },
+ leftColumn: {
+ element: document.createElement("div"),
+ id: "column-0",
+ ...leftColumn,
+ },
+ rightColumn: {
+ element: document.createElement("div"),
+ id: "column-1",
+ ...rightColumn,
+ },
+ };
+
+ view.dispatch(view.state.tr.setMeta(columnResizePluginKey, hoverState));
+}
+
+describe("Column resize plugin state after doc changes", () => {
+ it("falls back to default when a hovered column's removal unwraps the column list", () => {
+ const editor = getEditor();
+
+ hoverColumnBoundary();
+
+ // Removing one of the two columns brings the column list below its
+ // minimum of 2 children, so it gets unwrapped entirely. This used to
+ // throw a RangeError from the plugin's decorations, as they were built
+ // from positions resolved against the old, larger doc.
+ editor.removeBlocks(["column-1"]);
+
+ expect(
+ columnResizePluginKey.getState(editor._tiptapEditor.view.state),
+ ).toEqual({ type: "default" });
+ // The surviving column's two paragraphs are unwrapped to the top level.
+ expect(editor.document.map((block) => block.type)).toEqual([
+ "paragraph",
+ "paragraph",
+ "paragraph",
+ "paragraph",
+ "paragraph",
+ ]);
+ });
+
+ it("falls back to default when the whole doc is replaced", () => {
+ const editor = getEditor();
+
+ hoverColumnBoundary();
+
+ // Mimics select-all + backspace clearing the document while columns are
+ // hovered.
+ editor.replaceBlocks(editor.document, [{ type: "paragraph" }]);
+
+ expect(
+ columnResizePluginKey.getState(editor._tiptapEditor.view.state),
+ ).toEqual({ type: "default" });
+ expect(editor.document).toHaveLength(1);
+ });
+
+ it("keeps the hover state when an unrelated block changes", () => {
+ const editor = getEditor();
+
+ hoverColumnBoundary();
+
+ editor.updateBlock("paragraph-1", { content: "Updated Paragraph 1" });
+
+ const pluginState = columnResizePluginKey.getState(
+ editor._tiptapEditor.view.state,
+ );
+ expect(pluginState?.type).toBe("hover-column");
+ });
+});
diff --git a/packages/xl-odt-exporter/src/odt/odtExporter.tsx b/packages/xl-odt-exporter/src/odt/odtExporter.tsx
index fc72dc1be0..92844fe7e8 100644
--- a/packages/xl-odt-exporter/src/odt/odtExporter.tsx
+++ b/packages/xl-odt-exporter/src/odt/odtExporter.tsx
@@ -155,7 +155,13 @@ export class ODTExporter<
numberedListIndex = 0;
}
- if (["columnList", "column"].includes(block.type)) {
+ if (this.isContainerBlock(block)) {
+ // A container's mapping places its children, so it owns their layout
+ // context too - in ODT the columns become a table, whose cells start
+ // a fresh one. Nesting depth is rendered here as literal ``
+ // indentation (see `getTabs`), which would be wrong inside that
+ // context, so it restarts at 0 rather than accumulating through the
+ // container.
const children = await this.transformBlocks(block.children, 0);
const content = await this.mapBlock(
block as any,
diff --git a/packages/xl-pdf-exporter/src/react-pdf/pdfExporter.tsx b/packages/xl-pdf-exporter/src/react-pdf/pdfExporter.tsx
index f6242c0bb7..67f74a697b 100644
--- a/packages/xl-pdf-exporter/src/react-pdf/pdfExporter.tsx
+++ b/packages/xl-pdf-exporter/src/react-pdf/pdfExporter.tsx
@@ -184,7 +184,7 @@ export class PDFExporter<
children,
); // TODO: any
- if (["pageBreak", "columnList", "column"].includes(b.type)) {
+ if (b.type === "pageBreak" || this.isContainerBlock(b)) {
ret.push(self);
continue;
}
diff --git a/packages/xl-typst-exporter/src/__snapshots__/testDocument.typ b/packages/xl-typst-exporter/src/__snapshots__/testDocument.typ
index 7beb8b3135..51eeea8aab 100644
--- a/packages/xl-typst-exporter/src/__snapshots__/testDocument.typ
+++ b/packages/xl-typst-exporter/src/__snapshots__/testDocument.typ
@@ -169,19 +169,20 @@
#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#strong("Some inline code: ")#raw("var foo = 'bar';")]
-#grid(
- columns: (0.8fr, 1.4fr, 0.8fr),
- column-gutter: 1em,
- [#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#"This paragraph is in a column!"]],
- [#block(width: 100%, inset: (top: (8pt + 6.9pt), bottom: 6.9pt))[#heading(level: 1, outlined: true)[#"So is this heading!"]]],
- [#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#"You can have multiple blocks in a column too"]
+#{
+ let cols = (
+ (width: 0.8, body: [#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#"This paragraph is in a column!"]]),
+ (width: 1.4, body: [#block(width: 100%, inset: (top: (8pt + 6.9pt), bottom: 6.9pt))[#heading(level: 1, outlined: true)[#"So is this heading!"]]]),
+ (width: 0.8, body: [#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#"You can have multiple blocks in a column too"]
#list(
[#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#"Block 1"]],
[#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#"Block 2"]],
[#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#"Block 3"]]
-)]
-)
+)]),
+ )
+ grid(columns: cols.map(c => c.width * 1fr), column-gutter: 1em, ..cols.map(c => c.body))
+}
#block(width: 100%, inset: (top: 6.9pt, bottom: 6.9pt))[#line(length: 100%, stroke: 1pt + rgb("#7D797A"))]
diff --git a/packages/xl-typst-exporter/src/defaultSchema/blocks.ts b/packages/xl-typst-exporter/src/defaultSchema/blocks.ts
index daeb3733bf..33046bfb91 100644
--- a/packages/xl-typst-exporter/src/defaultSchema/blocks.ts
+++ b/packages/xl-typst-exporter/src/defaultSchema/blocks.ts
@@ -159,11 +159,36 @@ export const typstBlockMappingForDefaultSchema: BlockMapping<
divider: () => `#line(length: 100%, stroke: 1pt + rgb("#7D797A"))`,
pageBreak: () => `#pagebreak(weak: true)`,
- // Multi-column layout is assembled by TypstExporter.transformBlocks (columns
- // become grid cells). These entries exist only to satisfy the BlockMapping
- // type — they are never invoked.
- column: () => "",
- columnList: () => "",
+ // A column only ever exists as a columnList's child (its config is
+ // `placement: "containerOnly"`), so rather than content it returns the
+ // Typst *value* its parent needs: the width and the cell body. Typst takes
+ // a grid's track sizes on the grid, not on the cell, so the width has to
+ // reach the parent - the same reason the DOCX mapping hands its columnList
+ // a width-carrying table cell.
+ column: (block, _exporter, _nestingLevel, _numberedListIndex, children) =>
+ `(width: ${block.props.width ?? 1}, body: [${(children ?? []).join("\n\n")}])`,
+
+ // Lays the columns out side-by-side as a Typst `grid`, assembled in Typst
+ // code from the columns' (width, body) pairs so the fractional (`fr`)
+ // tracks keep their relative sizes. `grid` is a layout primitive (not a
+ // `table`), so it isn't tagged as a data table in the PDF. The trailing
+ // comma matters: `(x)` in Typst is a parenthesized value, not a one-element
+ // array.
+ columnList: (
+ _block,
+ _exporter,
+ _nestingLevel,
+ _numberedListIndex,
+ children,
+ ) =>
+ [
+ `#{`,
+ ` let cols = (`,
+ ...(children ?? []).map((c) => ` ${c},`),
+ ` )`,
+ ` grid(columns: cols.map(c => c.width * 1fr), column-gutter: 1em, ..cols.map(c => c.body))`,
+ `}`,
+ ].join("\n"),
// --- media -> Figure + Alt --------------------------------------------------
image: (block, exporter) =>
diff --git a/packages/xl-typst-exporter/src/typstExporter.test.ts b/packages/xl-typst-exporter/src/typstExporter.test.ts
index 890545d4d2..753f626280 100644
--- a/packages/xl-typst-exporter/src/typstExporter.test.ts
+++ b/packages/xl-typst-exporter/src/typstExporter.test.ts
@@ -1,5 +1,6 @@
import {
BlockNoteSchema,
+ createBlockSpec,
createPageBreakBlockSpec,
defaultBlockSpecs,
} from "@blocknote/core";
@@ -29,6 +30,42 @@ const fullSchema = BlockNoteSchema.create({
},
});
+// A minimal custom container, standing in for a callout/card: content-less,
+// holding child blocks. Its mapping is what has to place them.
+const Box = createBlockSpec(
+ {
+ type: "box" as const,
+ propSchema: {},
+ content: "none",
+ children: { allow: "any" },
+ },
+ {
+ render: (block: any) => {
+ const dom = document.createElement("div");
+ dom.setAttribute("data-node-type", "box");
+ dom.setAttribute("data-id", block.id);
+ return { dom, contentDOM: dom };
+ },
+ },
+)();
+
+const boxSchema = BlockNoteSchema.create({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ box: Box,
+ },
+});
+
+const boxDocument = partialBlocksToBlocksForTesting(boxSchema, [
+ {
+ type: "box",
+ children: [
+ { type: "paragraph", content: "First" },
+ { type: "paragraph", content: "Second" },
+ ],
+ },
+] as any);
+
describe("TypstExporter", () => {
it("exports a real BlockNote document to Typst", async () => {
// fullSchema (incl. multi-column) matches the shared testDocument. The
@@ -435,3 +472,78 @@ describe("TypstExporter", () => {
).toHaveLength(0);
});
});
+
+describe("container blocks", () => {
+ it("lays a columnList out as a grid with proportional tracks", async () => {
+ const exporter = new TypstExporter(fullSchema, typstDefaultSchemaMappings);
+
+ const typ = await exporter.toTypst(
+ partialBlocksToBlocksForTesting(fullSchema, [
+ {
+ type: "columnList",
+ children: [
+ {
+ type: "column",
+ props: { width: 2 },
+ children: [{ type: "paragraph", content: "Left" }],
+ },
+ {
+ type: "column",
+ children: [{ type: "paragraph", content: "Right" }],
+ },
+ ],
+ },
+ ] as any),
+ );
+
+ // Each column contributes its width and body; the grid derives its
+ // fractional tracks from them, so the relative sizes survive.
+ expect(typ).toContain("(width: 2, body: [");
+ expect(typ).toContain("(width: 1, body: [");
+ expect(typ).toContain(
+ "grid(columns: cols.map(c => c.width * 1fr), column-gutter: 1em, ..cols.map(c => c.body))",
+ );
+ // A layout grid, not a `table` - it must not be tagged as a data table.
+ expect(typ).not.toContain("#table(");
+
+ // The assembled markup is real Typst, not just a plausible string.
+ await compileTypstForTesting(typ, { assets: exporter.assetFiles });
+ });
+
+ it("passes its children to a custom container's mapping", async () => {
+ const typ = await new TypstExporter(boxSchema, {
+ ...typstDefaultSchemaMappings,
+ blockMapping: {
+ ...typstDefaultSchemaMappings.blockMapping,
+ box: (
+ _block: any,
+ _exporter: any,
+ _nestingLevel: any,
+ _numberedListIndex: any,
+ children?: string[],
+ ) => `#rect[${(children ?? []).join("\n\n")}]`,
+ },
+ } as any).toTypst(boxDocument);
+
+ // The children sit *inside* the container's own output - the mapping
+ // owns their placement - rather than following it as an indented run.
+ expect(typ).toContain("#rect[");
+ expect(typ.indexOf('#"First"')).toBeGreaterThan(typ.indexOf("#rect["));
+ expect(typ).toContain('#"Second"');
+ expect(typ).not.toContain("#pad(left: 1.5em)");
+ });
+
+ it("throws a clear error for an unmapped container block", async () => {
+ // The missing `box` mapping is the point of the test, and it's exactly
+ // what `BlockMapping` refuses to type - hence the cast (as in the DOCX
+ // exporter's equivalent test).
+ const exporter = new TypstExporter(
+ boxSchema,
+ typstDefaultSchemaMappings as any,
+ );
+
+ await expect(exporter.toTypst(boxDocument)).rejects.toThrow(
+ /container block type "box"/,
+ );
+ });
+});
diff --git a/packages/xl-typst-exporter/src/typstExporter.ts b/packages/xl-typst-exporter/src/typstExporter.ts
index 1c8f6af33c..9dbb0a372e 100644
--- a/packages/xl-typst-exporter/src/typstExporter.ts
+++ b/packages/xl-typst-exporter/src/typstExporter.ts
@@ -253,11 +253,23 @@ export class TypstExporter<
continue;
}
- // A columnList lays its column children out side-by-side. transformBlocks
- // owns this (rather than the block mapping) because the columns must
- // become grid cells, not the generic indented-children wrapper.
- if (b.type === "columnList") {
- out.push(await this.renderColumnList(b, nestingLevel));
+ // A container block's mapping owns where its children go - a columnList
+ // makes them grid cells, a callout puts them in its body - so they are
+ // passed in, and not appended after the block's own output as the
+ // generic indented run below.
+ if (this.isContainerBlock(b)) {
+ const containerChildren = await this.transformBlocks(
+ b.children,
+ nestingLevel + 1,
+ );
+ out.push(
+ (await this.mapBlock(
+ b as any,
+ nestingLevel,
+ 0,
+ containerChildren,
+ )) as string,
+ );
i++;
continue;
}
@@ -324,32 +336,6 @@ export class TypstExporter<
);
}
- /**
- * Render a columnList as a Typst `grid`: each child column becomes a grid
- * cell, its `width` prop mapped to a fractional (`fr`) track so relative
- * column sizes are preserved. `grid` is a layout primitive (not a `table`),
- * so it isn't tagged as a data table in the PDF.
- */
- private async renderColumnList(
- block: Block,
- nestingLevel: number,
- ): Promise {
- const columns = block.children;
- const tracks = columns
- .map((c) => `${(c.props as { width?: number }).width ?? 1}fr`)
- .join(", ");
- const cells: string[] = [];
- for (const col of columns) {
- const inner = (
- await this.transformBlocks(col.children, nestingLevel)
- ).join("\n\n");
- cells.push(`[${inner}]`);
- }
- return `#grid(\n columns: (${tracks}),\n column-gutter: 1em,\n ${cells.join(
- ",\n ",
- )}\n)`;
- }
-
private wrapList(
kind: "bullet" | "numbered" | "check",
items: string[],
diff --git a/playground/src/examples.gen.tsx b/playground/src/examples.gen.tsx
index 2d32e8c524..f34f2ec8bb 100644
--- a/playground/src/examples.gen.tsx
+++ b/playground/src/examples.gen.tsx
@@ -1487,6 +1487,33 @@ export const examples = {
readme:
"In this example, we create a custom block which renders a simple HTML paragraph with placeholder text. The block has no editable content.\n\n**Relevant Docs:**\n\n- [Custom Blocks](/docs/features/custom-schemas/custom-blocks)\n- [Editor Setup](/docs/getting-started/editor-setup)",
},
+ {
+ projectSlug: "container-block",
+ fullSlug: "custom-schema/container-block",
+ pathFromRoot: "examples/06-custom-schema/09-container-block",
+ config: {
+ playground: true,
+ docs: true,
+ author: "nickthesick",
+ tags: [
+ "Intermediate",
+ "Blocks",
+ "Custom Schemas",
+ "Suggestion Menus",
+ "Slash Menu",
+ ],
+ dependencies: {
+ "react-icons": "^5.5.0",
+ } as any,
+ },
+ title: "Container Block",
+ group: {
+ pathFromRoot: "examples/06-custom-schema",
+ slug: "custom-schema",
+ },
+ readme:
+ 'In this example, we create a custom `Callout` block that holds other blocks as its body, like a Notion-style callout wrapping a paragraph followed by a code block.\n\nThe block declares the `children` config on `BlockConfig`. `children: { min: 1, default: [{ type: "paragraph" }] }` makes it a container: its child blocks mount into the element the render passes `contentRef` to, and live on `block.children` at runtime.\n\nThe callout\'s **title** demonstrates the complementary "string prop slot" pattern: a field that doesn\'t need rich text, comments, or multiplayer cursors can live in a plain string prop, edited through a regular `` rendered inside the block (in a `contentEditable={false}` wrapper) and committed via `editor.updateBlock`. A field that _is_ prose belongs in the block\'s own `content: "inline"` instead.\n\nWe also wire up a Slash Menu item to insert the callout, and render the document JSON next to the editor so you can inspect the structure of the nested blocks.\n\n**Try it out:**\n\n- Press the "/" key inside the callout\'s body and add a code block, heading, or list.\n- Type a title into the title field. It\'s stored on `block.props.title`, not as document content.\n- Watch the JSON panel on the right update as you edit; the callout\'s children appear in `block.children`.\n- Insert a new callout via the Slash Menu (search "callout").\n\n**Relevant Docs:**\n\n- [Container Blocks](/docs/features/custom-schemas/container-blocks)\n- [Custom Blocks](/docs/features/custom-schemas/custom-blocks)\n- [Editor Setup](/docs/getting-started/editor-setup)',
+ },
{
projectSlug: "math-block",
fullSlug: "custom-schema/math-block",
@@ -1566,6 +1593,33 @@ export const examples = {
readme:
'In this example, we build custom blocks on the source-with-preview pattern — the same building blocks behind BlockNote\'s math and diagram blocks. A custom "CSV table" block renders its comma-separated source as a table, and a custom "color" inline content renders a CSS color as a swatch. Both show the rendered preview in place, while the source is edited in a popup.\n\n**Try it out:** Click the table or a color chip to edit its source!\n\n**Relevant Docs:**\n\n- [Source with Preview Blocks](/docs/features/custom-schemas/source-with-preview)\n- [Custom Blocks](/docs/features/custom-schemas/custom-blocks)\n- [Custom Inline Content](/docs/features/custom-schemas/custom-inline-content)',
},
+ {
+ projectSlug: "container-table",
+ fullSlug: "custom-schema/container-table",
+ pathFromRoot: "examples/06-custom-schema/12-container-table",
+ config: {
+ playground: true,
+ docs: true,
+ author: "nickthesick",
+ tags: [
+ "Advanced",
+ "Blocks",
+ "Custom Schemas",
+ "Suggestion Menus",
+ "Slash Menu",
+ ],
+ dependencies: {
+ "react-icons": "^5.5.0",
+ } as any,
+ },
+ title: "Table Built From Container Blocks",
+ group: {
+ pathFromRoot: "examples/06-custom-schema",
+ slug: "custom-schema",
+ },
+ readme:
+ 'In this example, we rebuild BlockNote\'s table as four container blocks: `table`, `tableRow`, `tableCell`, and `tableHeader`. There is no `prosemirror-tables` and no special `"table"` content type. A table is a container of rows, a row is a container of cells, and a cell is a container of arbitrary blocks, so cells can hold lists, headings, images, or even nested tables. The JSON shape is the same `children` array every other block uses.\n\nCells declare `boundary: "sealed"`, which makes them behave like compartments: Backspace, Delete, and arrow keys never implicitly move content or the caret across a cell\'s edge, and Enter adds another block _inside_ the cell. Header cells are a distinct block type rather than table metadata, so toggling the header row is just `updateBlock` with a new type. All structural operations, from adding and removing rows and columns to Tab-to-next-cell, are plain calls to the public block manipulation API: `insertBlocks`, `removeBlocks`, `updateBlock`, `getParentBlock`, and `setTextCursorPosition`.\n\n**Try it out:**\n\n- Press Tab / Shift-Tab to move between cells. Tab in the last cell adds a new row.\n- Press Enter inside a cell to stack more blocks in it, or "/" to add a list or heading.\n- Hover the table to reveal the row/column controls, and watch the JSON panel update.\n\n**Relevant Docs:**\n\n- [Container Blocks](/docs/features/custom-schemas/container-blocks)\n- [Custom Blocks](/docs/features/custom-schemas/custom-blocks)\n- [Manipulating Blocks](/docs/reference/editor/manipulating-content)\n- [Editor Setup](/docs/getting-started/editor-setup)',
+ },
{
projectSlug: "draggable-inline-content",
fullSlug: "custom-schema/draggable-inline-content",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0a4aeb2f0e..44967fe0b5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3511,6 +3511,52 @@ importers:
specifier: ^8.0.0
version: 8.0.8(@types/node@25.6.0)(esbuild@0.27.5)(jiti@2.6.1)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0)
+ examples/06-custom-schema/09-container-block:
+ dependencies:
+ '@blocknote/ariakit':
+ specifier: latest
+ version: link:../../../packages/ariakit
+ '@blocknote/core':
+ specifier: latest
+ version: link:../../../packages/core
+ '@blocknote/mantine':
+ specifier: latest
+ version: link:../../../packages/mantine
+ '@blocknote/react':
+ specifier: latest
+ version: link:../../../packages/react
+ '@blocknote/shadcn':
+ specifier: latest
+ version: link:../../../packages/shadcn
+ '@mantine/core':
+ specifier: ^9.0.2
+ version: 9.1.1(@mantine/hooks@9.1.1(react@19.2.5))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+ '@mantine/hooks':
+ specifier: ^9.0.2
+ version: 9.1.1(react@19.2.5)
+ react:
+ specifier: ^19.2.3
+ version: 19.2.5
+ react-dom:
+ specifier: ^19.2.3
+ version: 19.2.5(react@19.2.5)
+ react-icons:
+ specifier: ^5.5.0
+ version: 5.6.0(react@19.2.5)
+ devDependencies:
+ '@types/react':
+ specifier: ^19.2.3
+ version: 19.2.14
+ '@types/react-dom':
+ specifier: ^19.2.3
+ version: 19.2.3(@types/react@19.2.14)
+ '@vitejs/plugin-react':
+ specifier: ^6.0.1
+ version: 6.0.1(babel-plugin-react-compiler@1.0.0)(vite@8.0.8(@types/node@25.6.0)(esbuild@0.27.5)(jiti@2.6.1)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0))
+ vite:
+ specifier: ^8.0.0
+ version: 8.0.8(@types/node@25.6.0)(esbuild@0.27.5)(jiti@2.6.1)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0)
+
examples/06-custom-schema/09-math-block:
dependencies:
'@blocknote/ariakit':
@@ -3661,6 +3707,52 @@ importers:
specifier: ^8.0.0
version: 8.0.8(@types/node@25.6.0)(esbuild@0.27.5)(jiti@2.6.1)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0)
+ examples/06-custom-schema/12-container-table:
+ dependencies:
+ '@blocknote/ariakit':
+ specifier: latest
+ version: link:../../../packages/ariakit
+ '@blocknote/core':
+ specifier: latest
+ version: link:../../../packages/core
+ '@blocknote/mantine':
+ specifier: latest
+ version: link:../../../packages/mantine
+ '@blocknote/react':
+ specifier: latest
+ version: link:../../../packages/react
+ '@blocknote/shadcn':
+ specifier: latest
+ version: link:../../../packages/shadcn
+ '@mantine/core':
+ specifier: ^9.0.2
+ version: 9.1.1(@mantine/hooks@9.1.1(react@19.2.5))(@types/react@19.2.14)(react-dom@19.2.5(react@19.2.5))(react@19.2.5)
+ '@mantine/hooks':
+ specifier: ^9.0.2
+ version: 9.1.1(react@19.2.5)
+ react:
+ specifier: ^19.2.3
+ version: 19.2.5
+ react-dom:
+ specifier: ^19.2.3
+ version: 19.2.5(react@19.2.5)
+ react-icons:
+ specifier: ^5.5.0
+ version: 5.6.0(react@19.2.5)
+ devDependencies:
+ '@types/react':
+ specifier: ^19.2.3
+ version: 19.2.14
+ '@types/react-dom':
+ specifier: ^19.2.3
+ version: 19.2.3(@types/react@19.2.14)
+ '@vitejs/plugin-react':
+ specifier: ^6.0.1
+ version: 6.0.1(babel-plugin-react-compiler@1.0.0)(vite@8.0.8(@types/node@25.6.0)(esbuild@0.27.5)(jiti@2.6.1)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0))
+ vite:
+ specifier: ^8.0.0
+ version: 8.0.8(@types/node@25.6.0)(esbuild@0.27.5)(jiti@2.6.1)(terser@5.46.2)(tsx@4.21.0)(yaml@2.9.0)
+
examples/06-custom-schema/draggable-inline-content:
dependencies:
'@blocknote/ariakit':
diff --git a/tests/src/end-to-end/exporters/exporterTestUtil.tsx b/tests/src/end-to-end/exporters/exporterTestUtil.tsx
index bd857d6ef9..a8e740b163 100644
--- a/tests/src/end-to-end/exporters/exporterTestUtil.tsx
+++ b/tests/src/end-to-end/exporters/exporterTestUtil.tsx
@@ -1,4 +1,5 @@
import { BlockNoteSchema, defaultBlockSpecs } from "@blocknote/core";
+import { ColumnBlock, ColumnListBlock } from "@blocknote/xl-multi-column";
import { expect } from "vite-plus/test";
import { screenshotFull } from "../../utils/screenshotFull.js";
@@ -38,8 +39,19 @@ export const invalidMathBlock = {
children: [],
} as any;
+// Includes the multi-column blocks, which the shared test document contains.
+// They have to be in the *schema*, not just the mappings: the exporters read
+// the schema to tell a container block from a regular one, and a container
+// the exporter doesn't recognize gets its children appended after it instead
+// of placed by its mapping.
export function schema() {
- return BlockNoteSchema.create({ blockSpecs: defaultBlockSpecs });
+ return BlockNoteSchema.create({
+ blockSpecs: {
+ ...defaultBlockSpecs,
+ column: ColumnBlock,
+ columnList: ColumnListBlock,
+ },
+ });
}
/**
diff --git a/tests/src/end-to-end/keyboardhandlers/keyboardhandlers.test.tsx b/tests/src/end-to-end/keyboardhandlers/keyboardhandlers.test.tsx
index c33f704dd2..3e9d9af22c 100644
--- a/tests/src/end-to-end/keyboardhandlers/keyboardhandlers.test.tsx
+++ b/tests/src/end-to-end/keyboardhandlers/keyboardhandlers.test.tsx
@@ -313,6 +313,14 @@ describe("Check Keyboard Handlers' Behaviour", () => {
await insertParagraph();
await userEvent.keyboard("{ArrowUp}");
+ // ArrowUp moves the caret by visual x-position, and the target block above
+ // is nested (indented 24px further right than the block the caret starts
+ // in), so the caret lands mid-text rather than at the block's end.
+ // Normalize to the end of the word/line before deleting, like the "with
+ // children" variant below does, so Delete exercises the merge-with-next
+ // branch this test is about.
+ await userEvent.keyboard(`{${MOD}>}{ArrowLeft}{/${MOD}}`);
+ await userEvent.keyboard(`{${MOD}>}{ArrowRight}{/${MOD}}`);
await userEvent.keyboard("{Delete}");
await compareDocToSnapshot("deleteShallowerBlock");
diff --git a/tests/src/end-to-end/multicolumn/multicolumn.test.tsx b/tests/src/end-to-end/multicolumn/multicolumn.test.tsx
index 77cd1cd21d..97116684d2 100644
--- a/tests/src/end-to-end/multicolumn/multicolumn.test.tsx
+++ b/tests/src/end-to-end/multicolumn/multicolumn.test.tsx
@@ -11,6 +11,7 @@ import {
import {
compareDocToSnapshot,
focusOnEditor,
+ sleep,
waitForSelector,
} from "../../utils/editor.js";
import {
@@ -134,3 +135,53 @@ describe("Check Multi-Column Behaviour", () => {
await compareDocToSnapshot("deleteEndOfColumnList");
});
});
+
+// Which block the side menu attaches to is resolved from live layout
+// (`elementsFromPoint` / `posAtCoords`); the geometry pieces below that are
+// unit-tested in `packages/core/src/extensions/SideMenu/
+// sideMenuContainerGeometry.browser.test.ts`. This tests the whole path,
+// through a real column list. Hovering a column's left padding hands the
+// lookup coordinates that horizontally overlap the previous column, and
+// `SideMenu.ts` only resolves the right block by re-probing further right
+// once `isHorizontalContainer` recognises the column list. If that
+// compensation (or the detection) breaks, the menu attaches to a block in
+// the previous column.
+describe("Check side menu placement inside a column list", () => {
+ /** Vertical centre of a rect, which the menu lines itself up with. */
+ const centerY = (rect: DOMRect) => rect.y + rect.height / 2;
+
+ test("Check drag handle resolves the block on the hovered row of a column", async () => {
+ await focusOnEditor();
+
+ // The last column is the only one holding several blocks, so it's the only
+ // place a wrongly resolved block is distinguishable by its row.
+ const target = page.getByText("Block 2").element();
+ const columnRect = getRect(target.closest(".bn-block-column")!);
+
+ await mouseSequence([
+ {
+ type: "move",
+ x: columnRect.x + 5,
+ y: centerY(getRect(target)),
+ steps: 5,
+ },
+ ]);
+ await waitForSelector(DRAG_HANDLE_SELECTOR);
+ await sleep(150);
+ const handleRect = getRect(DRAG_HANDLE_SELECTOR);
+
+ expect(handleRect.x).toBeLessThan(getRect(target).x);
+
+ // The handle lines up with the hovered block's row rather than any other
+ // block's. This is a stronger check than a pixel tolerance, since every
+ // candidate is only a line-height away, and it is what distinguishes
+ // this column's blocks from the neighbouring column's.
+ const distance = (rect: DOMRect) =>
+ Math.abs(centerY(handleRect) - centerY(rect));
+ for (const other of ["Block 1", "Block 3", "So is this heading!"]) {
+ expect(distance(getRect(target))).toBeLessThan(
+ distance(getRect(page.getByText(other).element())),
+ );
+ }
+ });
+});
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerChildToSiblingAfter.html b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerChildToSiblingAfter.html
new file mode 100644
index 0000000000..a2d0a35be9
--- /dev/null
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerChildToSiblingAfter.html
@@ -0,0 +1,6 @@
+
+
+
Callout child 2
+
+
+
After callout
\ No newline at end of file
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerChildren.html b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerChildren.html
new file mode 100644
index 0000000000..20d8aa97db
--- /dev/null
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerChildren.html
@@ -0,0 +1,6 @@
+
+
+
Callout child 1
+
Callout child 2
+
+
\ No newline at end of file
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerNestedChild.html b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerNestedChild.html
new file mode 100644
index 0000000000..65339aa967
--- /dev/null
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/html/containerNestedChild.html
@@ -0,0 +1 @@
+Inner child
\ No newline at end of file
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerChildToSiblingAfter.md b/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerChildToSiblingAfter.md
new file mode 100644
index 0000000000..f313aa5cda
--- /dev/null
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerChildToSiblingAfter.md
@@ -0,0 +1,3 @@
+Callout child 2
+
+After callout
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerChildren.md b/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerChildren.md
new file mode 100644
index 0000000000..054a153e1c
--- /dev/null
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerChildren.md
@@ -0,0 +1,3 @@
+Callout child 1
+
+Callout child 2
diff --git a/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerNestedChild.md b/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerNestedChild.md
new file mode 100644
index 0000000000..72d309cf51
--- /dev/null
+++ b/tests/src/unit/core/clipboard/copy/__snapshots__/text/plain/containerNestedChild.md
@@ -0,0 +1 @@
+Inner child
diff --git a/tests/src/unit/core/clipboard/copy/copyTestInstances.ts b/tests/src/unit/core/clipboard/copy/copyTestInstances.ts
index 4bd34489c0..996d90b2c4 100644
--- a/tests/src/unit/core/clipboard/copy/copyTestInstances.ts
+++ b/tests/src/unit/core/clipboard/copy/copyTestInstances.ts
@@ -722,6 +722,80 @@ export const copyTestInstancesHTML: TestInstance<
},
executeTest: testCopyHTML,
},
+ {
+ // The whole of a container's children, selected from inside it.
+ testCase: {
+ name: "containerChildren",
+ document: [
+ {
+ type: "callout",
+ children: [
+ { type: "paragraph", content: "Callout child 1" },
+ { type: "paragraph", content: "Callout child 2" },
+ ],
+ },
+ ],
+ getCopySelection: (doc) => {
+ const startPos = getPosOfTextNode(doc, "Callout child 1");
+ const endPos = getPosOfTextNode(doc, "Callout child 2", true);
+
+ return TextSelection.create(doc, startPos, endPos);
+ },
+ },
+ executeTest: testCopyHTML,
+ },
+ {
+ // A selection that leaves the container partway through, so the copied
+ // fragment is cut open on one side.
+ testCase: {
+ name: "containerChildToSiblingAfter",
+ document: [
+ {
+ type: "callout",
+ children: [
+ { type: "paragraph", content: "Callout child 1" },
+ { type: "paragraph", content: "Callout child 2" },
+ ],
+ },
+ { type: "paragraph", content: "After callout" },
+ ],
+ getCopySelection: (doc) => {
+ const startPos = getPosOfTextNode(doc, "Callout child 2");
+ const endPos = getPosOfTextNode(doc, "After callout", true);
+
+ return TextSelection.create(doc, startPos, endPos);
+ },
+ },
+ executeTest: testCopyHTML,
+ },
+ {
+ // A single block two containers deep, so the fragment is cut open on both
+ // sides at two different levels.
+ testCase: {
+ name: "containerNestedChild",
+ document: [
+ {
+ type: "callout",
+ props: { flavor: "warning" },
+ children: [
+ { type: "paragraph", content: "Outer child" },
+ {
+ type: "callout",
+ props: { flavor: "info" },
+ children: [{ type: "paragraph", content: "Inner child" }],
+ },
+ ],
+ },
+ ],
+ getCopySelection: (doc) => {
+ const startPos = getPosOfTextNode(doc, "Inner child");
+ const endPos = getPosOfTextNode(doc, "Inner child", true);
+
+ return TextSelection.create(doc, startPos, endPos);
+ },
+ },
+ executeTest: testCopyHTML,
+ },
];
// text/plain payloads — exercises the same selections as above but snapshots
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/basic.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/basic.html
new file mode 100644
index 0000000000..039f688a1b
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/basic.html
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+
Callout child
+
+
+
+
+
+
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/emptyChildren.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/emptyChildren.html
new file mode 100644
index 0000000000..68454f648d
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/emptyChildren.html
@@ -0,0 +1,5 @@
+
+
+
+
+
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/nested.html b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/nested.html
new file mode 100644
index 0000000000..79dd38484a
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/blocknoteHTML/container/nested.html
@@ -0,0 +1,24 @@
+
+
+
+
+
+
+
Nested heading
+
+
+
+
+
+
+
+
+
Inner callout child
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/basic.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/basic.html
new file mode 100644
index 0000000000..fe07a47f15
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/basic.html
@@ -0,0 +1,5 @@
+
+
+
Callout child
+
+
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/emptyChildren.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/emptyChildren.html
new file mode 100644
index 0000000000..f3c2c65ce8
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/emptyChildren.html
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/nested.html b/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/nested.html
new file mode 100644
index 0000000000..d8f13e62a1
--- /dev/null
+++ b/tests/src/unit/core/formatConversion/export/__snapshots__/html/container/nested.html
@@ -0,0 +1,16 @@
+
`,
+ },
+ executeTest: testParseHTML,
+ },
+ {
+ // A container nested inside another, with a non-default prop on each.
+ testCase: {
+ name: "containerNested",
+ content: `
+
+
+
+
+
+
Nested heading
+
+
+
+
+
+
+
+
+
Inner callout child
+
+
+
+
+
+
+
+
`,
+ },
+ executeTest: testParseHTML,
+ },
+ {
+ // A container whose children holder is serialized empty. Parsing goes
+ // through a real document, so the spec's `default` children fill it back
+ // in. This is why `container/emptyChildren` is excluded from the
+ // export/parse equality matrix.
+ testCase: {
+ name: "containerEmptyChildren",
+ content: `
+
+
+
+
`,
+ },
+ executeTest: testParseHTML,
+ },
+ {
+ // The external (`blocksToHTMLLossy`) form, which is what lands on the
+ // clipboard and what another app would paste in. The holder carries no
+ // `data-children-of` marker.
+ testCase: {
+ name: "containerExternalHTML",
+ content: `
+
+
Nested heading
+
+
+
Inner callout child
+
+
+
+
`,
+ },
+ executeTest: testParseHTML,
+ },
];
export const parseTestInstancesMarkdown: TestInstance<
diff --git a/tests/src/unit/core/schema/__snapshots__/blocks.json b/tests/src/unit/core/schema/__snapshots__/blocks.json
index ee48987244..9ae0749202 100644
--- a/tests/src/unit/core/schema/__snapshots__/blocks.json
+++ b/tests/src/unit/core/schema/__snapshots__/blocks.json
@@ -73,6 +73,36 @@
"toExternalHTML": [Function],
},
},
+ "callout": {
+ "config": {
+ "children": {
+ "allow": "any",
+ "default": [
+ {
+ "type": "paragraph",
+ },
+ ],
+ },
+ "content": "none",
+ "propSchema": {
+ "flavor": {
+ "default": "tip",
+ "values": [
+ "tip",
+ "info",
+ "warning",
+ ],
+ },
+ },
+ "type": "callout",
+ },
+ "extensions": undefined,
+ "implementation": {
+ "node": null,
+ "render": [Function],
+ "toExternalHTML": [Function],
+ },
+ },
"checkListItem": {
"config": {
"content": "inline",
diff --git a/tests/src/unit/core/testSchema.ts b/tests/src/unit/core/testSchema.ts
index eca37363fa..c3e03c3227 100644
--- a/tests/src/unit/core/testSchema.ts
+++ b/tests/src/unit/core/testSchema.ts
@@ -99,6 +99,41 @@ const SimpleCustomParagraph = createBlockSpec(
},
);
+// A container block: it holds no inline content of its own, and its `contentDOM`
+// is where its child blocks go. Covers containers in the format-conversion,
+// clipboard and selection matrices, which otherwise never see one.
+const Callout = createBlockSpec(
+ {
+ type: "callout" as const,
+ propSchema: {
+ flavor: {
+ default: "tip" as const,
+ values: ["tip", "info", "warning"] as const,
+ },
+ },
+ content: "none",
+ children: {
+ allow: "any",
+ default: [{ type: "paragraph" }],
+ },
+ },
+ {
+ render: () => {
+ const callout = document.createElement("div");
+ callout.className = "callout";
+
+ const body = document.createElement("div");
+ body.className = "callout-body";
+ callout.appendChild(body);
+
+ return {
+ dom: callout,
+ contentDOM: body,
+ };
+ },
+ },
+);
+
// INLINE CONTENT --------------------------------------------------------------
const Mention = createInlineContentSpec(
@@ -222,6 +257,7 @@ export const testSchema = BlockNoteSchema.create().extend({
customParagraph: CustomParagraph(),
simpleCustomParagraph: SimpleCustomParagraph(),
simpleImage: SimpleImage(),
+ callout: Callout(),
},
inlineContentSpecs: {
mention: Mention,
diff --git a/tests/src/unit/react/useNodeViewBlock.test.tsx b/tests/src/unit/react/useNodeViewBlock.test.tsx
index 71101c7fa7..397c75019b 100644
--- a/tests/src/unit/react/useNodeViewBlock.test.tsx
+++ b/tests/src/unit/react/useNodeViewBlock.test.tsx
@@ -27,8 +27,15 @@ const createReproBlock = createReactBlockSpec(
{ render: (props) => },
);
+// A container block, whose node view's node is itself the bnBlock, resolved
+// by id instead of by position.
+const createBoxBlock = createReactBlockSpec(
+ { type: "box", propSchema: {}, content: "none", children: { allow: "any" } },
+ { render: (props) => },
+);
+
const schema = BlockNoteSchema.create().extend({
- blockSpecs: { repro: createReproBlock() },
+ blockSpecs: { repro: createReproBlock(), box: createBoxBlock() },
});
let editor: BlockNoteEditor;
@@ -43,6 +50,7 @@ beforeEach(() => {
{ type: "paragraph", content: "first" },
{ type: "repro", content: "target block" },
{ type: "paragraph", content: "last" },
+ { type: "box", children: [{ type: "paragraph", content: "inside" }] },
],
}) as BlockNoteEditor;
@@ -78,11 +86,14 @@ function renderHook(
return resolved;
}
-// Only the two fields `useNodeViewBlock` reads. Built structurally so `tests`
-// doesn't need a dependency on `@tiptap/react` just for its prop types.
-function makeProps(getPos: () => number | undefined) {
+// Only the fields `useNodeViewBlock` reads. Built structurally so `tests`
+// doesn't need a dependency on `@tiptap/react` just for its prop types. The
+// `node` defaults to a regular (non-container) block's node shape; container
+// tests pass the real PM node instead.
+function makeProps(getPos: () => number | undefined, node?: unknown) {
return {
getPos,
+ node: node ?? { type: { isInGroup: () => false } },
view: { state: { doc: editor.prosemirrorState.doc } },
} as unknown as Parameters[0];
}
@@ -170,4 +181,34 @@ describe("useNodeViewBlock", () => {
expect(resolved.id).toBe(target.id);
expect(resolved).not.toBe(seed);
});
+
+ it("rejects container blocks loudly instead of resolving the wrong block", () => {
+ const box = editor.document.find((block) => block.type === "box")!;
+ const { node } = getNodeById(box.id, editor.prosemirrorState.doc)!;
+ const props = makeProps(() => undefined, node);
+
+ let captured: unknown;
+
+ function Probe() {
+ useNodeViewBlock(props, box);
+ return null;
+ }
+
+ root = createRoot(div, {
+ // React 19 reports uncaught render errors here instead of rethrowing
+ // out of `flushSync`.
+ onUncaughtError: (error: unknown) => {
+ captured = error;
+ },
+ });
+ try {
+ flushSync(() => {
+ root!.render();
+ });
+ } catch (error) {
+ captured = error;
+ }
+
+ expect(String(captured)).toMatch(/cannot resolve container block "box"/);
+ });
});
diff --git a/tests/vitestSetup.browser.ts b/tests/vitestSetup.browser.ts
index 469a859137..70b3220bab 100644
--- a/tests/vitestSetup.browser.ts
+++ b/tests/vitestSetup.browser.ts
@@ -23,6 +23,20 @@ beforeAll(async () => {
const style = document.createElement("style");
style.textContent = `.bn-container { max-width: 731px; margin: 0 auto; padding-top: 8px; }`;
document.head.appendChild(style);
+
+ // Disable CSS transitions & animations for the whole suite. The editor
+ // animates block geometry (e.g. `.bn-block-outer { transition: margin 0.2s }`
+ // driven by the PreviousBlockType depth-change decorations), so for ~200ms
+ // after a Tab/Shift+Tab the blocks' x-positions are mid-flight. Visual caret
+ // movement (ArrowUp/ArrowDown) then lands at a timing-dependent text offset,
+ // which made document snapshots race the animation clock under CPU
+ // contention. With motion disabled, layout is always in its settled state and
+ // caret geometry is deterministic. (No product code listens for
+ // transitionend/animationend, and no keyframes rely on fill-mode, so
+ // suppressing motion only removes the timing dependency.)
+ const noMotion = document.createElement("style");
+ noMotion.textContent = `*, *::before, *::after { transition: none !important; animation: none !important; }`;
+ document.head.appendChild(noMotion);
});
beforeEach(() => {