Merge branch 'refs/heads/main' into releases

Author: matthewlipski

docs/pages/docs/advanced/nextjs.mdx

@@ -8,7 +8,7 @@ imageTitle: Next.js and BlockNote
 
 BlockNote is a component that should only be rendered client-side (and not on the server). If you're using Next.js, you need to make sure that Next.js does not try to render BlockNote as a server-side component.
 
-Make sure to use BlockNote in a [Client Component](https://nextjs.org/docs/getting-started/react-essentials#client-components). You can do this by creating a separate file for your component (**make sure this sits outside of your `pages` or `app` directory**), and starting that with `"use client";` [directive](https://react.dev/reference/react/use-client):
+Make sure to use BlockNote in a [Client Component](https://nextjs.org/docs/getting-started/react-essentials#client-components). You can do this by creating a separate file for your component (**make sure this sits outside of your `pages` or `app` directory, for example `components/Editor.tsx`**), and starting that with `"use client";` [directive](https://react.dev/reference/react/use-client):
 
 ```typescript jsx
 "use client"; // this registers <Editor> as a Client Component
@@ -36,7 +36,7 @@ You can import the component we just created above using `next/dynamic` in your
 ```typescript jsx
 import dynamic from "next/dynamic";
 
-const Editor = dynamic(() => import("./editor"), { ssr: false });
+const Editor = dynamic(() => import("../components/Editor"), { ssr: false });
 
 function App() {
   return (

docs/pages/docs/editor-api/manipulating-blocks.mdx

@@ -119,7 +119,7 @@ insertBlocks(
 ): void;
 
 // Usage
-editor.insertBlocks([{type: "paragraph", text: "Hello World"}], referenceBlock, placement)
+editor.insertBlocks([{type: "paragraph", content: "Hello World"}], referenceBlock, placement)
 ```
 
 `blocksToInsert:` An array of [partial blocks](/docs/editor-api/manipulating-blocks#partial-blocks) that should be inserted.

packages/core/src/api/exporters/html/__snapshots_fragment_edge_cases__/selectionLeavesBlockChildren.html

@@ -0,0 +1 @@
+<p class="bn-inline-content">Nested Paragraph 1</p><p class="bn-inline-content">Nested Paragraph 2</p><p class="bn-inline-content">Nested Paragraph 3</p><p class="bn-inline-content">Paragraph 2</p>

packages/core/src/api/exporters/html/__snapshots_fragment_edge_cases__/selectionSpansBlocksChildren.html

@@ -0,0 +1 @@
+<p class="bn-inline-content">Nested Paragraph 1</p><p class="bn-inline-content">Nested Paragraph 2</p><p class="bn-inline-content">Nested Paragraph 3</p><p class="bn-inline-content">Paragraph 2</p><p class="bn-inline-content">Nested Paragraph 1</p><p class="bn-inline-content">Nested Paragraph 2</p><p class="bn-inline-content">Nested Paragraph 3</p>

packages/core/src/api/exporters/html/__snapshots_fragment_edge_cases__/selectionWithinBlockChildren.html

@@ -0,0 +1 @@
+<p class="bn-inline-content">Nested Paragraph 1</p><p class="bn-inline-content">Nested Paragraph 2</p><p class="bn-inline-content">Nested Paragraph 3</p>

packages/core/src/api/exporters/html/htmlConversion.test.ts

@@ -1,3 +1,4 @@
+import { TextSelection } from "prosemirror-state";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { BlockNoteEditor } from "../../../editor/BlockNoteEditor";
 
@@ -101,3 +102,142 @@ describe("Test HTML conversion", () => {
     });
   }
 });
+
+// Fragments created from ProseMirror selections don't always conform to the
+// schema. This is because ProseMirror preserves the full ancestry of selected
+// nodes, but not the siblings of ancestor nodes. These tests are to verify that
+// Fragments like this are exported to HTML properly, as they can't be created
+// from Block objects like all the other test cases (Block object conversions
+// always conform to the schema).
+describe("Test ProseMirror fragment edge case conversion", () => {
+  let editor: BlockNoteEditor;
+  const div = document.createElement("div");
+  beforeEach(() => {
+    editor = BlockNoteEditor.create();
+    editor.mount(div);
+  });
+
+  afterEach(() => {
+    editor.mount(undefined);
+    editor._tiptapEditor.destroy();
+    editor = undefined as any;
+
+    delete (window as Window & { __TEST_OPTIONS?: any }).__TEST_OPTIONS;
+  });
+
+  // When the selection starts in a nested block, the Fragment from it omits the
+  // `blockContent` node of the parent `blockContainer` if it's not also
+  // included in the selection. In the schema, `blockContainer` nodes should
+  // contain a single `blockContent` node, so this edge case needs to be tested.
+  describe("No block content", () => {
+    const blocks: PartialBlock[] = [
+      {
+        type: "paragraph",
+        content: "Paragraph 1",
+        children: [
+          {
+            type: "paragraph",
+            content: "Nested Paragraph 1",
+          },
+          {
+            type: "paragraph",
+            content: "Nested Paragraph 2",
+          },
+          {
+            type: "paragraph",
+            content: "Nested Paragraph 3",
+          },
+        ],
+      },
+      {
+        type: "paragraph",
+        content: "Paragraph 2",
+        children: [
+          {
+            type: "paragraph",
+            content: "Nested Paragraph 1",
+          },
+          {
+            type: "paragraph",
+            content: "Nested Paragraph 2",
+          },
+          {
+            type: "paragraph",
+            content: "Nested Paragraph 3",
+          },
+        ],
+      },
+    ];
+
+    beforeEach(() => {
+      editor.replaceBlocks(editor.document, blocks);
+    });
+
+    it("Selection within a block's children", () => {
+      // Selection starts and ends within the first block's children.
+      editor.prosemirrorView.dispatch(
+        editor._tiptapEditor.state.tr.setSelection(
+          TextSelection.create(editor._tiptapEditor.state.doc, 18, 80)
+        )
+      );
+
+      const copiedFragment =
+        editor._tiptapEditor.state.selection.content().content;
+
+      const exporter = createExternalHTMLExporter(
+        editor._tiptapEditor.schema,
+        editor
+      );
+      const externalHTML = exporter.exportProseMirrorFragment(copiedFragment);
+      expect(externalHTML).toMatchFileSnapshot(
+        "./__snapshots_fragment_edge_cases__/" +
+          "selectionWithinBlockChildren.html"
+      );
+    });
+
+    it("Selection leaves a block's children", () => {
+      // Selection starts and ends within the first block's children and ends
+      // outside, at a shallower nesting level in the second block.
+      editor.prosemirrorView.dispatch(
+        editor._tiptapEditor.state.tr.setSelection(
+          TextSelection.create(editor._tiptapEditor.state.doc, 18, 97)
+        )
+      );
+
+      const copiedFragment =
+        editor._tiptapEditor.state.selection.content().content;
+
+      const exporter = createExternalHTMLExporter(
+        editor._tiptapEditor.schema,
+        editor
+      );
+      const externalHTML = exporter.exportProseMirrorFragment(copiedFragment);
+      expect(externalHTML).toMatchFileSnapshot(
+        "./__snapshots_fragment_edge_cases__/" +
+          "selectionLeavesBlockChildren.html"
+      );
+    });
+
+    it("Selection spans multiple blocks' children", () => {
+      // Selection starts and ends within the first block's children and ends
+      // within the second block's children.
+      editor.prosemirrorView.dispatch(
+        editor._tiptapEditor.state.tr.setSelection(
+          TextSelection.create(editor._tiptapEditor.state.doc, 18, 163)
+        )
+      );
+
+      const copiedFragment =
+        editor._tiptapEditor.state.selection.content().content;
+      const exporter = createExternalHTMLExporter(
+        editor._tiptapEditor.schema,
+        editor
+      );
+      const externalHTML = exporter.exportProseMirrorFragment(copiedFragment);
+      expect(externalHTML).toMatchFileSnapshot(
+        "./__snapshots_fragment_edge_cases__/" +
+          "selectionSpansBlocksChildren.html"
+      );
+    });
+  });
+});

packages/core/src/api/exporters/html/util/simplifyBlocksRehypePlugin.ts

@@ -41,11 +41,34 @@ export function simplifyBlocks(options: SimplifyBlocksOptions) {
     for (let i = 0; i < numChildElements; i++) {
       const blockOuter = tree.children[i] as HASTElement;
       const blockContainer = blockOuter.children[0] as HASTElement;
-      const blockContent = blockContainer.children[0] as HASTElement;
-      const blockGroup =
-        blockContainer.children.length === 2
-          ? (blockContainer.children[1] as HASTElement)
-          : null;
+      const blockContent = blockContainer.children.find((child) => {
+        const properties = (child as HASTElement).properties;
+        const classNames = properties?.["className"] as string[] | undefined;
+
+        return classNames?.includes("bn-block-content");
+      }) as HASTElement | undefined;
+      const blockGroup = blockContainer.children.find((child) => {
+        const properties = (child as HASTElement).properties;
+        const classNames = properties?.["className"] as string[] | undefined;
+
+        return classNames?.includes("bn-block-group");
+      }) as HASTElement | undefined;
+
+      // When the selection starts in a nested block, the Fragment from it omits
+      // the `blockContent` node of the parent `blockContainer` if it's not also
+      // included in the selection. This is because ProseMirror preserves the
+      // nesting hierarchy of the nested nodes, even if their ancestors aren't
+      // fully selected. In this case, we just lift the child `blockContainer`
+      // nodes up.
+      // NOTE: This only happens for the first `blockContainer`, since to get to
+      // any nested blocks later in the document, the selection must also
+      // include their parents.
+      if (!blockContent) {
+        tree.children.splice(i, 1, ...blockGroup!.children);
+        simplifyBlocksHelper(tree);
+
+        return;
+      }
 
       const isListItemBlock = listItemBlockTypes.has(
         blockContent.properties!["dataContentType"] as string
@@ -60,7 +83,7 @@ export function simplifyBlocks(options: SimplifyBlocksOptions) {
         : null;
 
       // Plugin runs recursively to process nested blocks.
-      if (blockGroup !== null) {
+      if (blockGroup) {
         simplifyBlocksHelper(blockGroup);
       }
 
@@ -101,13 +124,13 @@ export function simplifyBlocks(options: SimplifyBlocksOptions) {
         listItemElement.children.push(...blockContent.children);
         // Nested blocks have already been processed in the recursive function call, so the resulting elements are
         // also added to the active list.
-        if (blockGroup !== null) {
+        if (blockGroup) {
           listItemElement.children.push(...blockGroup.children);
         }
 
         // Adds the list item representing the block to the active list.
         activeList.children.push(listItemElement);
-      } else if (blockGroup !== null) {
+      } else if (blockGroup) {
         // Lifts all children out of the current block, as only list items should allow nesting.
         tree.children.splice(i + 1, 0, ...blockGroup.children);
         // Replaces the block with only the content inside it.

packages/core/src/editor/BlockNoteExtensions.ts

@@ -50,6 +50,7 @@ export const getBlockNoteExtensions = <
     user: {
       name: string;
       color: string;
+      [key: string]: string;
     };
     provider: any;
     renderCursor?: (user: any) => HTMLElement;

packages/core/src/i18n/locales/index.ts

@@ -8,4 +8,5 @@ export * from "./nl";
 export * from "./pl";
 export * from "./pt";
 export * from "./vi";
-export * from "./zh";
+export * from "./zh";
+export * from "./ru";