Update docs (#38)

* update docs

* update docs

* add doc

* disable cla

* small readme fixes

Author: YousefED

.github/workflows/cla.yml .github/workflows/cla.yml.disabled

@@ -73,6 +73,8 @@ blocknote
 └── tests               - Playwright end to end tests
 ```
 
+An introduction into the BlockNote Prosemirror schema can be found in [packages/core/ARCHITECTURE.md](https://github.com/YousefED/BlockNote/blob/main/packages/core/ARCHITECTURE.md).
+
 ## Running
 
 To run the project, open the command line in the project's root directory and enter the following commands:

LICENSE

@@ -0,0 +1,37 @@
+# Node structure
+
+We use a Prosemirror document structure where every element is a `block` with 1 `content` element and one optional group of children (`blockgroup`).
+
+- A `block` can only appear in a `blockgroup` (which is also the type of the root node)
+- Every `block` element can have attributes (e.g.: is it a heading or a list item)
+- Every `block` element can contain a `blockgroup` as second child. In this case the `blockgroup` is considered nested (indented in the UX)
+
+This architecture is different from the "default" Prosemirror / Tiptap implementation which would use more semantic HTML node types (`p`, `li`, etc.). We have designed this block structure instead to more easily:
+
+- support indentation of any node (without complex wrapping logic)
+- supporting animations (nodes stay the same type, only attrs are changed)
+
+## Example
+
+```xml
+<blockgroup>
+    <block>
+        <content>Parent element 1</content>
+        <blockgroup>
+            <block>
+                <content>Nested / child / indented item</content>
+            </block>
+        </blockgroup>
+    </block>
+    <block>
+        <content>Parent element 2</content>
+        <blockgroup>
+            <block>...</block>
+            <block>...</block>
+        </blockgroup>
+    </block>
+    <block>
+        <content>Element 3 without children</content>
+    </block>
+</blockgroup>
+```

README.md

@@ -2,7 +2,7 @@
   "name": "@blocknote/core",
   "homepage": "https://github.com/yousefed/blocknote",
   "private": false,
-  "license": "MIT",
+  "license": "MPL-2.0",
   "version": "0.1.0-alpha.3",
   "files": [
     "dist",

packages/core/ARCHITECTURE.md

@@ -1,17 +1,16 @@
 import { Extensions, extensions } from "@tiptap/core";
 
+import { Node } from "@tiptap/core";
 import Bold from "@tiptap/extension-bold";
 import Code from "@tiptap/extension-code";
 import DropCursor from "@tiptap/extension-dropcursor";
 import GapCursor from "@tiptap/extension-gapcursor";
 import HardBreak from "@tiptap/extension-hard-break";
-import Italic from "@tiptap/extension-italic";
-import Underline from "@tiptap/extension-underline";
-// import Placeholder from "@tiptap/extension-placeholder";
-import { Node } from "@tiptap/core";
 import { History } from "@tiptap/extension-history";
+import Italic from "@tiptap/extension-italic";
 import Strike from "@tiptap/extension-strike";
 import Text from "@tiptap/extension-text";
+import Underline from "@tiptap/extension-underline";
 import { blocks } from "./extensions/Blocks";
 import blockStyles from "./extensions/Blocks/nodes/Block.module.css";
 import { BubbleMenuExtension } from "./extensions/BubbleMenu/BubbleMenuExtension";
@@ -22,12 +21,16 @@ import { Placeholder } from "./extensions/Placeholder/PlaceholderExtension";
 import SlashMenuExtension from "./extensions/SlashMenu";
 import { TrailingNode } from "./extensions/TrailingNode/TrailingNodeExtension";
 import UniqueID from "./extensions/UniqueID/UniqueID";
+
 export const Document = Node.create({
   name: "doc",
   topNode: true,
   content: "block+",
 });
 
+/**
+ * Get all the Tiptap extensions BlockNote is configured with by default
+ */
 export const getBlockNoteExtensions = () => {
   const ret: Extensions = [
     extensions.ClipboardTextSerializer,
@@ -48,7 +51,7 @@ export const getBlockNoteExtensions = () => {
       showOnlyCurrent: false,
     }),
     UniqueID.configure({
-      types: ["tcblock"],
+      types: ["block"],
     }),
     HardBreak,
     // Comments,
@@ -64,26 +67,16 @@ export const getBlockNoteExtensions = () => {
     Underline,
     HyperlinkMark,
     FixedParagraph,
+
     // custom blocks:
     ...blocks,
     DraggableBlocksExtension,
     DropCursor.configure({ width: 5, color: "#ddeeff" }),
     BubbleMenuExtension,
     History,
-    SlashMenuExtension,
     // This needs to be at the bottom of this list, because Key events (such as enter, when selecting a /command),
     // should be handled before Enter handlers in other components like splitListItem
-    // SlashCommandExtension.configure({
-    //     // Extra commands can be registered here
-    //     commands: {},
-    // }),
-    // MentionsExtension.configure({
-    //     providers: {
-    //         people: (query) => {
-    //             return PEOPLE.filter((mention) => mention.match(query));
-    //         },
-    //     },
-    // }),
+    SlashMenuExtension,
     TrailingNode,
   ];
   return ret;

packages/core/package.json

@@ -1 +1,2 @@
-export { EditorContent } from "@tiptap/react";
+// BlockNote uses a similar pattern as Tiptap, so for now we can just export that
+export { EditorContent } from "@tiptap/react";

packages/core/src/BlockNoteExtensions.ts

@@ -11,12 +11,12 @@ export const OrderedListPlugin = () => {
       let count = 1;
       let skip = 0;
       newState.doc.descendants((node, pos) => {
-        if (node.type.name === "tcblock" && !node.attrs.listType) {
+        if (node.type.name === "block" && !node.attrs.listType) {
           count = 1;
         }
         if (
           skip === 0 &&
-          node.type.name === "tcblock" &&
+          node.type.name === "block" &&
           node.attrs.listType === "oli"
         ) {
           skip = node.content.childCount;

packages/core/src/EditorContent.tsx

@@ -1,3 +1,3 @@
 import { findParentNode } from "@tiptap/core";
 
-export const findBlock = findParentNode((node) => node.type.name === "tcblock");
+export const findBlock = findParentNode((node) => node.type.name === "block");

packages/core/src/extensions/Blocks/OrderedListPlugin.ts

@@ -43,7 +43,7 @@ declare module "@tiptap/core" {
  * The main "Block node" documents consist of
  */
 export const Block = Node.create<IBlock>({
-  name: "tcblock",
+  name: "block",
   group: "block",
   addOptions() {
     return {
@@ -52,7 +52,7 @@ export const Block = Node.create<IBlock>({
   },
 
   // A block always contains content, and optionally a blockGroup which contains nested blocks
-  content: "tccontent blockgroup?",
+  content: "content blockgroup?",
 
   defining: true,
 
@@ -172,7 +172,7 @@ export const Block = Node.create<IBlock>({
           const nodePos = tr.selection.$anchor.posAtIndex(0, -1) - 1;
 
           // const node2 = tr.doc.nodeAt(nodePos);
-          if (node.type.name === "tcblock" && node.attrs["listType"]) {
+          if (node.type.name === "block" && node.attrs["listType"]) {
             if (dispatch) {
               tr.setNodeMarkup(nodePos, undefined, {
                 ...node.attrs,
@@ -203,8 +203,7 @@ export const Block = Node.create<IBlock>({
 
           // Create new block after current block
           const endOfBlock = currentBlock.pos + currentBlock.node.nodeSize;
-          let newBlock =
-            state.schema.nodes["tcblock"].createAndFill(attributes)!;
+          let newBlock = state.schema.nodes["block"].createAndFill(attributes)!;
           if (dispatch) {
             tr.insert(endOfBlock, newBlock);
             tr.setSelection(new TextSelection(tr.doc.resolve(endOfBlock + 1)));
@@ -218,7 +217,7 @@ export const Block = Node.create<IBlock>({
           const nodePos = tr.selection.$anchor.posAtIndex(0, -1) - 1;
 
           // const node2 = tr.doc.nodeAt(nodePos);
-          if (node.type.name === "tcblock") {
+          if (node.type.name === "block") {
             if (dispatch) {
               tr.setNodeMarkup(nodePos, undefined, {
                 ...node.attrs,
@@ -268,11 +267,11 @@ export const Block = Node.create<IBlock>({
           commands.command(({ tr }) => {
             const isAtStartOfNode = tr.selection.$anchor.parentOffset === 0;
             const node = tr.selection.$anchor.node(-1);
-            if (isAtStartOfNode && node.type.name === "tcblock") {
+            if (isAtStartOfNode && node.type.name === "block") {
               // we're at the start of the block, so we're trying to "backspace" the bullet or indentation
               return commands.first([
                 () => commands.unsetList(), // first try to remove the "list" property
-                () => commands.liftListItem("tcblock"), // then try to remove a level of indentation
+                () => commands.liftListItem("block"), // then try to remove a level of indentation
               ]);
             }
             return false;
@@ -292,7 +291,7 @@ export const Block = Node.create<IBlock>({
               const isAtStartOfNode = tr.selection.$anchor.parentOffset === 0;
               const anchor = tr.selection.$anchor;
               const node = anchor.node(-1);
-              if (isAtStartOfNode && node.type.name === "tcblock") {
+              if (isAtStartOfNode && node.type.name === "block") {
                 if (node.childCount === 2) {
                   // BlockB has children. We want to go from this:
                   //
@@ -337,7 +336,7 @@ export const Block = Node.create<IBlock>({
     const handleEnter = () =>
       this.editor.commands.first(({ commands }) => [
         // Try to split the current block into 2 items:
-        () => commands.splitListItem("tcblock"),
+        () => commands.splitListItem("block"),
         // Otherwise, maybe we are in an empty list item. "Enter" should remove the list bullet
         ({ tr, dispatch }) => {
           const $from = tr.selection.$from;
@@ -348,7 +347,7 @@ export const Block = Node.create<IBlock>({
           const node = tr.selection.$anchor.node(-1);
           const nodePos = tr.selection.$anchor.posAtIndex(0, -1) - 1;
 
-          if (node.type.name === "tcblock" && node.attrs["listType"]) {
+          if (node.type.name === "block" && node.attrs["listType"]) {
             if (dispatch) {
               tr.setNodeMarkup(nodePos, undefined, {
                 ...node.attrs,
@@ -373,9 +372,9 @@ export const Block = Node.create<IBlock>({
     return {
       Backspace: handleBackspace,
       Enter: handleEnter,
-      Tab: () => this.editor.commands.sinkListItem("tcblock"),
+      Tab: () => this.editor.commands.sinkListItem("block"),
       "Shift-Tab": () => {
-        return this.editor.commands.liftListItem("tcblock");
+        return this.editor.commands.liftListItem("block");
       },
       "Mod-Alt-0": () =>
         this.editor.chain().unsetList().unsetBlockHeading().run(),

packages/core/src/extensions/Blocks/helpers/findBlock.ts

@@ -10,7 +10,7 @@ export const BlockGroup = Node.create({
     };
   },
 
-  content: "tcblock+",
+  content: "block+",
 
   parseHTML() {
     return [{ tag: "div" }];

packages/core/src/extensions/Blocks/nodes/Block.ts

@@ -5,7 +5,7 @@ export interface IBlock {
 }
 
 export const ContentBlock = Node.create<IBlock>({
-  name: "tccontent",
+  name: "content",
 
   addOptions() {
     return {

packages/core/src/extensions/Blocks/nodes/BlockGroup.ts

@@ -1,9 +1,10 @@
 import { Extension } from "@tiptap/core";
 import { PluginKey } from "prosemirror-state";
 import ReactDOM from "react-dom";
+import rootStyles from "../../root.module.css";
 import { createBubbleMenuPlugin } from "./BubbleMenuPlugin";
 import { BubbleMenu } from "./component/BubbleMenu";
-import rootStyles from "../../root.module.css";
+
 /**
  * The menu that is displayed when selecting a piece of text.
  */

packages/core/src/extensions/Blocks/nodes/Content.ts

@@ -1,27 +1,27 @@
+import DropdownMenu, { DropdownItemGroup } from "@atlaskit/dropdown-menu";
 import { Editor } from "@tiptap/core";
 import {
   RiBold,
   RiH1,
   RiH2,
   RiH3,
+  RiIndentDecrease,
+  RiIndentIncrease,
   RiItalic,
   RiLink,
-  RiStrikethrough,
-  RiUnderline,
-  RiIndentIncrease,
-  RiIndentDecrease,
-  RiText,
   RiListOrdered,
   RiListUnordered,
+  RiStrikethrough,
+  RiText,
+  RiUnderline,
 } from "react-icons/ri";
 import { SimpleToolbarButton } from "../../../shared/components/toolbar/SimpleToolbarButton";
 import { Toolbar } from "../../../shared/components/toolbar/Toolbar";
 import { useEditorForceUpdate } from "../../../shared/hooks/useEditorForceUpdate";
 import { findBlock } from "../../Blocks/helpers/findBlock";
 import formatKeyboardShortcut from "../../helpers/formatKeyboardShortcut";
-import LinkToolbarButton from "./LinkToolbarButton";
-import DropdownMenu, { DropdownItemGroup } from "@atlaskit/dropdown-menu";
 import DropdownBlockItem from "./DropdownBlockItem";
+import LinkToolbarButton from "./LinkToolbarButton";
 
 type ListType = "li" | "oli";
 
@@ -167,19 +167,15 @@ export const BubbleMenu = (props: { editor: Editor }) => {
         icon={RiStrikethrough}
       />
       <SimpleToolbarButton
-        onClick={() =>
-          props.editor.chain().focus().sinkListItem("tcblock").run()
-        }
-        isDisabled={!props.editor.can().sinkListItem("tcblock")}
+        onClick={() => props.editor.chain().focus().sinkListItem("block").run()}
+        isDisabled={!props.editor.can().sinkListItem("block")}
         mainTooltip="Indent"
         secondaryTooltip={formatKeyboardShortcut("Tab")}
         icon={RiIndentIncrease}
       />
 
       <SimpleToolbarButton
-        onClick={() =>
-          props.editor.chain().focus().liftListItem("tcblock").run()
-        }
+        onClick={() => props.editor.chain().focus().liftListItem("block").run()}
         isDisabled={
           !props.editor.can().command(({ state }) => {
             const block = findBlock(state.selection);

packages/core/src/extensions/Blocks/nodes/README.md

@@ -59,8 +59,7 @@ export const DragHandle = (props: {
     if (currentBlock.node.firstChild?.textContent.length !== 0) {
       // Create new block after current block
       const endOfBlock = currentBlock.pos + currentBlock.node.nodeSize;
-      let newBlock =
-        props.view.state.schema.nodes["tccontent"].createAndFill()!;
+      let newBlock = props.view.state.schema.nodes["content"].createAndFill()!;
       props.view.state.tr.insert(endOfBlock, newBlock);
       props.view.dispatch(props.view.state.tr.insert(endOfBlock, newBlock));
       props.view.dispatch(