feature: Column based layouts

docs/components/pages/landing/hero/DemoEditor.tsx

@@ -1,7 +1,14 @@
-import { uploadToTmpFilesDotOrg_DEV_ONLY } from "@blocknote/core";
+import {
+  BlockNoteSchema,
+  uploadToTmpFilesDotOrg_DEV_ONLY,
+} from "@blocknote/core";
 import "@blocknote/core/fonts/inter.css";
 import { useCreateBlockNote } from "@blocknote/react";
 import { BlockNoteView } from "@blocknote/mantine";
+import {
+  multiColumnDropCursor,
+  withMultiColumn,
+} from "@blocknote/xl-multi-column";
 import "@blocknote/mantine/style.css";
 import { useCallback, useMemo, useState } from "react";
 import YPartyKitProvider from "y-partykit/provider";
@@ -67,6 +74,8 @@ export default function DemoEditor(props: { theme?: "light" | "dark" }) {
 
   const editor = useCreateBlockNote(
     {
+      schema: withMultiColumn(BlockNoteSchema.create()),
+      dropCursor: multiColumnDropCursor,
       collaboration: {
         provider,
         fragment: doc.getXmlFragment("blocknote"),

docs/package.json

@@ -14,6 +14,7 @@
     "@blocknote/mantine": "^0.18.1",
     "@blocknote/react": "^0.18.1",
     "@blocknote/shadcn": "^0.18.1",
+    "@blocknote/xl-multi-column": "^0.18.1",
     "@headlessui/react": "^1.7.18",
     "@heroicons/react": "^2.1.4",
     "@mantine/core": "^7.10.1",

docs/pages/docs/editor-basics/document-structure.mdx

@@ -43,6 +43,34 @@ type Block = {
 
 `children:` Any blocks nested inside the block. The nested blocks are also represented using `Block` objects.
 
+### Column Blocks
+
+The `@blocknote/xl-multi-column` package allows you to organize blocks side-by-side in columns. It introduces 2 additional block types, the column and column list:
+
+```typescript
+type ColumnBlock = {
+  id: string;
+  type: "column";
+  props: { width: number };
+  content: undefined;
+  children: Block[];
+};
+
+type ColumnListBlock = {
+  id: string;
+  type: "columnList";
+  props: {};
+  content: undefined;
+  children: ColumnBlock[];
+};
+```
+
+While both of these act as regular blocks, there are a few additional restrictions to have in mind when working with them:
+
+- Children of columns must be regular blocks
+- Children of column lists must be columns
+- There must be at least 2 columns in a column list
+
 ## Inline Content
 
 The `content` field of a block contains the rich-text content of a block. This is defined as an array of `InlineContent` objects. Inline content can either be styled text or a link (or a custom inline content type if you customize the editor schema).

examples/01-basic/03-multi-column/.bnexample.json

@@ -0,0 +1,9 @@
+{
+  "playground": true,
+  "docs": true,
+  "author": "yousefed",
+  "tags": ["Basic", "Blocks"],
+  "dependencies": {
+    "@blocknote/xl-multi-column": "latest"
+  }
+}

examples/01-basic/03-multi-column/App.tsx

@@ -0,0 +1,118 @@
+import {
+  BlockNoteSchema,
+  combineByGroup,
+  filterSuggestionItems,
+  locales,
+} from "@blocknote/core";
+import "@blocknote/core/fonts/inter.css";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import {
+  SuggestionMenuController,
+  getDefaultReactSlashMenuItems,
+  useCreateBlockNote,
+} from "@blocknote/react";
+import {
+  getMultiColumnSlashMenuItems,
+  multiColumnDropCursor,
+  locales as multiColumnLocales,
+  withMultiColumn,
+} from "@blocknote/xl-multi-column";
+import { useMemo } from "react";
+export default function App() {
+  // Creates a new editor instance.
+  const editor = useCreateBlockNote({
+    // Adds column and column list blocks to the schema.
+    schema: withMultiColumn(BlockNoteSchema.create()),
+    // The default drop cursor only shows up above and below blocks - we replace
+    // it with the multi-column one that also shows up on the sides of blocks.
+    dropCursor: multiColumnDropCursor,
+    // Merges the default dictionary with the multi-column dictionary.
+    dictionary: {
+      ...locales.en,
+      multi_column: multiColumnLocales.en,
+    },
+    initialContent: [
+      {
+        type: "paragraph",
+        content: "Welcome to this demo!",
+      },
+      {
+        type: "columnList",
+        children: [
+          {
+            type: "column",
+            props: {
+              width: 0.8,
+            },
+            children: [
+              {
+                type: "paragraph",
+                content: "This paragraph is in a column!",
+              },
+            ],
+          },
+          {
+            type: "column",
+            props: {
+              width: 1.4,
+            },
+            children: [
+              {
+                type: "heading",
+                content: "So is this heading!",
+              },
+            ],
+          },
+          {
+            type: "column",
+            props: {
+              width: 0.8,
+            },
+            children: [
+              {
+                type: "paragraph",
+                content: "You can have multiple blocks in a column too",
+              },
+              {
+                type: "bulletListItem",
+                content: "Block 1",
+              },
+              {
+                type: "bulletListItem",
+                content: "Block 2",
+              },
+              {
+                type: "bulletListItem",
+                content: "Block 3",
+              },
+            ],
+          },
+        ],
+      },
+      {
+        type: "paragraph",
+      },
+    ],
+  });
+
+  // Merges the default slash menu items with the multi-column ones.
+  const slashMenuItems = useMemo(() => {
+    return combineByGroup(
+      getDefaultReactSlashMenuItems(editor),
+      getMultiColumnSlashMenuItems(editor)
+    );
+  }, [editor]);
+
+  // Renders the editor instance using a React component.
+  return (
+    <BlockNoteView editor={editor} slashMenu={false}>
+      {/* Replaces the default slash menu with one that has both the default
+      items and the multi-column ones. */}
+      <SuggestionMenuController
+        triggerCharacter={"/"}
+        getItems={async (query) => filterSuggestionItems(slashMenuItems, query)}
+      />
+    </BlockNoteView>
+  );
+}

examples/01-basic/03-multi-column/README.md

@@ -0,0 +1,8 @@
+# Multi-Column Blocks
+
+This example showcases multi-column blocks, allowing you to stack blocks next to each other. These come as part of the `@blocknote/xl-multi-column` package.
+
+**Relevant Docs:**
+
+- [Editor Setup](/docs/editor-basics/setup)
+- [Document Structure](/docs/editor-basics/document-structure)

examples/01-basic/03-multi-column/index.html

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

examples/01-basic/03-multi-column/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@blocknote/example-multi-column",
+  "description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+  "private": true,
+  "version": "0.12.4",
+  "scripts": {
+    "start": "vite",
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "lint": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@blocknote/core": "latest",
+    "@blocknote/react": "latest",
+    "@blocknote/ariakit": "latest",
+    "@blocknote/mantine": "latest",
+    "@blocknote/shadcn": "latest",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@blocknote/xl-multi-column": "latest"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.25",
+    "@types/react-dom": "^18.0.9",
+    "@vitejs/plugin-react": "^4.3.1",
+    "eslint": "^8.10.0",
+    "vite": "^5.3.4"
+  },
+  "eslintConfig": {
+    "extends": [
+      "../../../.eslintrc.js"
+    ]
+  },
+  "eslintIgnore": [
+    "dist"
+  ]
+}

examples/01-basic/04-all-blocks/.bnexample.json

@@ -0,0 +1,9 @@
+{
+  "playground": true,
+  "docs": true,
+  "author": "yousefed",
+  "tags": ["Basic", "Blocks", "Inline Content"],
+  "dependencies": {
+    "@blocknote/xl-multi-column": "latest"
+  }
+}

examples/01-basic/03-all-blocks/App.tsx → examples/01-basic/04-all-blocks/App.tsx

@@ -1,11 +1,33 @@
+import {
+  BlockNoteSchema,
+  combineByGroup,
+  filterSuggestionItems,
+  locales,
+} from "@blocknote/core";
 import "@blocknote/core/fonts/inter.css";
-import { useCreateBlockNote } from "@blocknote/react";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
-
+import {
+  SuggestionMenuController,
+  getDefaultReactSlashMenuItems,
+  useCreateBlockNote,
+} from "@blocknote/react";
+import {
+  getMultiColumnSlashMenuItems,
+  multiColumnDropCursor,
+  locales as multiColumnLocales,
+  withMultiColumn,
+} from "@blocknote/xl-multi-column";
+import { useMemo } from "react";
 export default function App() {
   // Creates a new editor instance.
   const editor = useCreateBlockNote({
+    schema: withMultiColumn(BlockNoteSchema.create()),
+    dropCursor: multiColumnDropCursor,
+    dictionary: {
+      ...locales.en,
+      multi_column: multiColumnLocales.en,
+    },
     initialContent: [
       {
         type: "paragraph",
@@ -28,6 +50,35 @@ export default function App() {
         type: "paragraph",
         content: "Paragraph",
       },
+      {
+        type: "columnList",
+        children: [
+          {
+            type: "column",
+            props: {
+              width: 0.8,
+            },
+            children: [
+              {
+                type: "paragraph",
+                content: "Hello to the left!",
+              },
+            ],
+          },
+          {
+            type: "column",
+            props: {
+              width: 1.2,
+            },
+            children: [
+              {
+                type: "paragraph",
+                content: "Hello to the right!",
+              },
+            ],
+          },
+        ],
+      },
       {
         type: "heading",
         content: "Heading",
@@ -137,6 +188,20 @@ export default function App() {
     ],
   });
 
+  const slashMenuItems = useMemo(() => {
+    return combineByGroup(
+      getDefaultReactSlashMenuItems(editor),
+      getMultiColumnSlashMenuItems(editor)
+    );
+  }, [editor]);
+
   // Renders the editor instance using a React component.
-  return <BlockNoteView editor={editor} />;
+  return (
+    <BlockNoteView editor={editor} slashMenu={false}>
+      <SuggestionMenuController
+        triggerCharacter={"/"}
+        getItems={async (query) => filterSuggestionItems(slashMenuItems, query)}
+      />
+    </BlockNoteView>
+  );
 }

examples/01-basic/03-all-blocks/README.md → examples/01-basic/04-all-blocks/README.md

@@ -4,5 +4,6 @@ This example showcases each block and inline content type in BlockNote's default
 
 **Relevant Docs:**
 
+- [Editor Setup](/docs/editor-basics/setup)
 - [Document Structure](/docs/editor-basics/document-structure)
 - [Default Schema](/docs/editor-basics/default-schema)

examples/01-basic/03-all-blocks/package.json → examples/01-basic/04-all-blocks/package.json

@@ -17,7 +17,8 @@
     "@blocknote/mantine": "latest",
     "@blocknote/shadcn": "latest",
     "react": "^18.3.1",
-    "react-dom": "^18.3.1"
+    "react-dom": "^18.3.1",
+    "@blocknote/xl-multi-column": "latest"
   },
   "devDependencies": {
     "@types/react": "^18.0.25",