feat: Major Extensions & UI Refactor (#2143)

* refactor(extensions): rewrite to use new extension system

* chore: minor fixes

* Refactored almost all formatting toolbar components to use `useEditorState`

* Refactored remaining uses of hooks with `useEditorState` where possible (excl. `BlockTypeSelect`)

* feat: virtual element hooks

* Refactored formatting toolbar, file panel, and suggestion menu controllers

* Fixed popover position reference not updating when it should & fixed formatting toolbar items

* Cleaned up hooks

* - Cleaned up refactored UI plugins
- Fixed `useDismiss` not working on mouse click outside
- Cleaned up `LinkToolbarController`
- Made `BlockPopover` use actual block element as reference instead of virtual element
- Added more configuration props to `GenericPopover`
- Made `GenericPopover` set element reference when a real element, or virtual element with `contextElement`, is passed
- Added editor DOM element as `contextElement` in `PositionPopover`

* Refactored side menu & fixed issue with `GenericPopover` memoized `innerHTML` not getting updated

* Comment edit

* Fixed core build

* Misc fixes

* Small fix

* Refactored table handles

* Fixed various build & UI issues

* Fixed various UI issues

* Fixed link creation/editing throwing error

* Refactored comments

* chore: update prosemirror versions

* fix: y-prosemirror plugin ordering

* Updated comments to fully use new components APIs

* chore: fix build

* build: get multi-column building again

* refactor: rewrite the AI extension to use the new plugin API

* fix: make mounting and unmounting extensions actually work properly

* Fixed z-index clipping issues

* refactor: normalize extension naming no longer plugins

* refactor: always turn a DOMRect into JSON for easy comparisons

* refactor: change imports of extensions to be found at `@blocknote/core/extensions`

* fix: use an abort signal instead of sending an abortcontroller

* chore: fix circular import

* chore: use any blocknote editor

* refactor: less derived state

* refactor: rename `usePlugin` -> `useExtension`

* refactor: remove class member

* refactor: rename `plugins` -> `prosemirrorPlugins` and `init` -> `mount`

* Fixed suggestion menus closing when clicking scroll bar

* fix: always pull the latest extensions in React

* Fixed table handle issues

* add comments

* Fixed most remaining table handle issues

* fix: formatting toolbar, comments + cleanup

* refactor: filepanel unsubs it's listeners

* Fixed build

* refactor: rewrite how extensions work

* chore: fix lint

* Fixed formatting & link toolbar issues

* Small fix

* refactor: PR comments

* Small fix

* fix: handle collaboration again

* refactor: remove resolveUsers from editor

* refactor: cleanup some more off the editor

* remove zustand dep

* refactor: move comments to their sub-package

* refactor: rename extensions to have `Extension` suffix

* refactor: delete some un-used hooks

* fix: remove comments options from the editor instance

* Fixed suggestion menu issues

* Misc changes/fixes

* Small fix

* fix: put back menu handling

* Removed logs

* refactor(comments): make extension use store exclusively

* fix: break circular import

* fix: remove `onCreate` event since it is not needed with current system

* Formatting toolbar and file panel fixes

* test: add some checks for tests

* fix: use correct key

* Fixed tests

* Fixed collab tests

* test: fixes for test running

* test: get all unit tests passing again

* chore: fix lint

* build: lint depends on nothing

* Refactored/tested/fixed AI menu and other misc changes

* fix: use a single prosemirror plugin instance for all inputRules

* Fixed block keyboard shortcuts not getting registered and local unit test errors

* Updated e2e snaps

* Fixed e2e tests

* Updated e2e screenshot

* Fixed create link button not showing editor selection

* Fixed `SideMenu`/`BlockPositioner` updating bug

* Minor changes

* Fixed issues when editor is not editable

* Added comment

* small fix to aimenu

* Misc fixes after review

* Fixed build

* Updated docs

* Changed file panel extension state from object with block ID string to just block ID string

* Moved all `DOMRect` caching logic to `GenericPopover`

---------

Co-authored-by: Matthew Lipski <matthewlipski@gmail.com>
Co-authored-by: yousefed <yousefdardiry@gmail.com>

Author: 3 people

docs/content/docs/features/ai/custom-commands.mdx

@@ -26,8 +26,8 @@ First, we define a new AI command. Let's create one that makes selected text mor
 
 ```tsx
 import {
+  AIExtension,
   AIMenuSuggestionItem,
-  getAIExtension,
   aiDocumentFormats,
 } from "@blocknote/xl-ai";
 
@@ -40,7 +40,7 @@ export const makeInformal = (
   aliases: ["informal", "make informal", "casual"],
   icon: <RiEmotionHappyFill size={18} />,
   onItemClick: async () => {
-    await getAIExtension(editor).invokeAI({
+    await editor.getExtension(AIExtension)?.invokeAI({
       // The prompt to send to the LLM:
       userPrompt: "Give the selected text a more informal (casual) tone",
       // Tell the LLM to specifically use the selected content as context (instead of the whole document)

docs/content/docs/features/ai/reference.mdx

@@ -52,14 +52,6 @@ type AIRequestHelpers = {
 };
 ```
 
-## `getAIExtension`
-
-Use `getAIExtension` to retrieve the AI extension instance registered to the editor:
-
-```typescript
-function getAIExtension(editor: BlockNoteEditor): AIExtension;
-```
-
 ## `AIExtension`
 
 The `AIExtension` class is the main class for the AI extension. It exposes state and methods to interact with BlockNote's AI features.

docs/content/docs/features/extensions.mdx

@@ -14,10 +14,10 @@ BlockNote includes an extensions system which lets you expand the editor's behav
 
 ## Creating an extension
 
-An extension is an instance of the [`BlockNoteExtension`](https://github.com/TypeCellOS/BlockNote/blob/10cdbfb5f77ef82f3617c0fa1191e0bf5b7358c5/packages/core/src/editor/BlockNoteExtension.ts#L13) class. However, it's recommended for most use cases to create extensions using the `createBlockNoteExtension` function, rather than instanciating the class directly:
+You can create extensions using the `createExtension` function:
 
 ```typescript
-type BlockNoteExtensionOptions = {
+type Extension = {
   key: string;
   keyboardShortcuts?: Record<
     string,
@@ -35,18 +35,16 @@ type BlockNoteExtensionOptions = {
   tiptapExtensions?: AnyExtension[];
 }
 
-const customBlockExtensionOptions: BlockNoteExtensionOptions = {
+const CustomExtension = createExtension({
   key: "customBlockExtension",
   keyboardShortcuts: ...,
   inputRules: ...,
   plugins: ...,
   tiptapExtensions: ...,
-}
-
-const CustomExtension = createBlockNoteExtension(customBlockExtensionOptions);
+});
 ```
 
-Let's go over the options that can be passed into `createBlockNoteExtension`:
+Let's go over the options that can be passed into `createExtension`:
 
 `key:` The name of the extension.
 
@@ -68,20 +66,20 @@ Extensions can be added to the editor on their own via the [editor options](/doc
 
 ### Adding directly to the editor
 
-The `extensions` [editor option](/docs/reference/editor/overview#options) takes an array of `BlockNoteExtension`s to be added to the editor:
+The `extensions` [editor option](/docs/reference/editor/overview#options) takes an array of extensions to be added to the editor:
 
 ```typescript
 const editor = useCreateBlockNote({
   extensions: [
     // Add extensions here:
-    createBlockNoteExtension({ ... })
+    createExtension({ ... })
   ],
 });
 ```
 
 ### Adding to custom blocks
 
-When creating a [custom block](/docs/features/custom-schemas/custom-blocks#creating-a-custom-block-type) using `createReactBlockSpec`, you can pass an array of `BlockNoteExtension`s to the third parameter:
+When creating a [custom block](/docs/features/custom-schemas/custom-blocks#creating-a-custom-block-type) using `createReactBlockSpec`, you can pass an array of extensions to the third parameter:
 
 ```typescript
 const createCustomBlock = createReactBlockSpec(
@@ -95,7 +93,7 @@ const createCustomBlock = createReactBlockSpec(
   }
   [
     // Add extensions here:
-    createBlockNoteExtension({ ... })
+    createExtension({ ... })
   ],
 });
 ```

docs/content/docs/reference/editor/events.mdx

@@ -16,17 +16,6 @@ The editor emits events for:
 - **Content changes** - When blocks are inserted, updated, or deleted
 - **Selection changes** - When the cursor position or selection changes
 
-## `onCreate`
-
-The `onCreate` callback is called when the editor has been initialized and is ready for use.
-
-```typescript
-editor.onCreate(() => {
-  console.log("Editor is ready for use");
-  // Initialize plugins, set up event listeners, etc.
-});
-```
-
 ## `onMount`
 
 The `onMount` callback is called when the editor has been mounted.

docs/package.json

@@ -77,7 +77,7 @@
     "better-sqlite3": "^11.10.0",
     "classnames": "2.3.2",
     "clsx": "2.1.1",
-    "docx": "^9.0.2",
+    "docx": "^9.5.1",
     "framer-motion": "^11.18.2",
     "fumadocs-core": "15.5.4",
     "fumadocs-docgen": "2.0.1",

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

@@ -1,8 +1,8 @@
 import {
   BlockNoteSchema,
   combineByGroup,
-  filterSuggestionItems,
 } from "@blocknote/core";
+import { filterSuggestionItems } from "@blocknote/core/extensions";
 import * as locales from "@blocknote/core/locales";
 import "@blocknote/core/fonts/inter.css";
 import { BlockNoteView } from "@blocknote/mantine";

examples/03-ui-components/02-formatting-toolbar-buttons/src/BlueButton.tsx

@@ -2,10 +2,9 @@ import "@blocknote/mantine/style.css";
 import {
   useBlockNoteEditor,
   useComponentsContext,
-  useEditorContentOrSelectionChange,
+  useEditorState,
   useSelectedBlocks,
 } from "@blocknote/react";
-import { useState } from "react";
 
 // Custom Formatting Toolbar Button to toggle blue text & background color.
 export function BlueButton() {
@@ -14,18 +13,12 @@ export function BlueButton() {
   const Components = useComponentsContext()!;
 
   // Tracks whether the text & background are both blue.
-  const [isSelected, setIsSelected] = useState<boolean>(
-    editor.getActiveStyles().textColor === "blue" &&
-      editor.getActiveStyles().backgroundColor === "blue",
-  );
-
-  // Updates state on content or selection change.
-  useEditorContentOrSelectionChange(() => {
-    setIsSelected(
+  const isSelected = useEditorState({
+    editor,
+    selector: ({ editor }) =>
       editor.getActiveStyles().textColor === "blue" &&
-        editor.getActiveStyles().backgroundColor === "blue",
-    );
-  }, editor);
+      editor.getActiveStyles().backgroundColor === "blue",
+  });
 
   // Doesn't render unless a at least one block with inline content is
   // selected. You can use a similar pattern of returning `null` to

examples/03-ui-components/04-side-menu-buttons/src/App.tsx

@@ -39,7 +39,7 @@ export default function App() {
         sideMenu={(props) => (
           <SideMenu {...props}>
             {/* Button which removes the hovered block. */}
-            <RemoveBlockButton {...props} />
+            <RemoveBlockButton />
             <DragHandleButton {...props} />
           </SideMenu>
         )}

examples/03-ui-components/04-side-menu-buttons/src/RemoveBlockButton.tsx

@@ -1,24 +1,34 @@
+import {} from "@blocknote/core";
+import { SideMenuExtension } from "@blocknote/core/extensions";
 import {
-  SideMenuProps,
   useBlockNoteEditor,
   useComponentsContext,
+  useExtensionState,
 } from "@blocknote/react";
 import { MdDelete } from "react-icons/md";
 
 // Custom Side Menu button to remove the hovered block.
-export function RemoveBlockButton(props: SideMenuProps) {
+export function RemoveBlockButton() {
   const editor = useBlockNoteEditor();
 
   const Components = useComponentsContext()!;
 
+  const block = useExtensionState(SideMenuExtension, {
+    selector: (state) => state?.block,
+  });
+
+  if (!block) {
+    return null;
+  }
+
   return (
     <Components.SideMenu.Button
       label="Remove block"
       icon={
         <MdDelete
           size={24}
           onClick={() => {
-            editor.removeBlocks([props.block]);
+            editor.removeBlocks([block]);
           }}
         />
       }

examples/03-ui-components/05-side-menu-drag-handle-items/src/App.tsx

@@ -4,7 +4,6 @@ import "@blocknote/mantine/style.css";
 import {
   BlockColorsItem,
   DragHandleMenu,
-  DragHandleMenuProps,
   RemoveBlockItem,
   SideMenu,
   SideMenuController,
@@ -16,12 +15,12 @@ import { ResetBlockTypeItem } from "./ResetBlockTypeItem";
 // To avoid rendering issues, it's good practice to define your custom drag
 // handle menu in a separate component, instead of inline within the `sideMenu`
 // prop of `SideMenuController`.
-const CustomDragHandleMenu = (props: DragHandleMenuProps) => (
-  <DragHandleMenu {...props}>
-    <RemoveBlockItem {...props}>Delete</RemoveBlockItem>
-    <BlockColorsItem {...props}>Colors</BlockColorsItem>
+const CustomDragHandleMenu = () => (
+  <DragHandleMenu>
+    <RemoveBlockItem>Delete</RemoveBlockItem>
+    <BlockColorsItem>Colors</BlockColorsItem>
     {/* Item which resets the hovered block's type. */}
-    <ResetBlockTypeItem {...props}>Reset Type</ResetBlockTypeItem>
+    <ResetBlockTypeItem>Reset Type</ResetBlockTypeItem>
   </DragHandleMenu>
 );