feat: concept of bundles vs. extensions

Author: nperez0111

adr/2025_06_13-extensions.md

@@ -8,8 +8,7 @@ What I identified was:
 
 - The ability to "eject" to the prosemirror API, if we don't provide something good enough. This is a core choice, and one I don't think we would ever need to walk back on. Fundamentally, we do not want to expose absolutely everything that Prosemirror can do, but also do not want to stop those with the know-how to actually get stuff done.
 - A unified store API, to make consuming extension state homogenous, this will be discussed further below
-- Life-cycle event handlers, by providing hooks for `create`, `mount`, and `unmount` we allow extensions to attach event handlers to DOM elements, and have a better general understanding of the current state of the editor. The `onCreate` handler will be very handy to guarantee access to the editor instance before anything is called.
-- Editing event handlers, by providing hooks for `change`, `selectionChange`, `beforeChange`, and `transaction` we give extensions access to the fundamental primitives of the editor.
+- Life-cycle event handlers, by providing hooks for `mount` and `unmount` we allow extensions to attach event handlers to DOM elements, and have a better general understanding of the current state of the editor.
 
 ## State Management
 
@@ -47,3 +46,15 @@ Not everything can be communicated through just state, so we need to be able to
 I propose that we have a `extensions` property on the `BlockNoteEditor` instance, which is a map of the extension key to the extension instance, but filtered out to only include non-blocknote methods (as defined by the `ExtensionMethods` type).
 
 This will allow the application to access the extension methods, and also allows us to keep the extension instance private to the editor (type-wise).
+
+# BlockNote Bundles
+
+Somewhat related, to extensions, we also need a way for bundling sets of editor elements in a single packaging. This will be a much higher-level API, which will aim to provide a single import for adding an entire set of functionality to the editor (e.g. adding multi-column support, or comments, etc.)
+
+## Core Requirements
+
+- A way to add blocks, inline content, and styles to the editor
+- A way to add extensions to the editor
+- A way to add to the dictionary of locales to the editor
+- A way to add to the slash menu
+- A way to add to the formatting toolbar

adr/BlockNoteBundle.ts

@@ -0,0 +1,80 @@
+import { BlockNoteBundle } from "./BlockNoteExtension";
+
+export interface BlockNoteBundleConfig<
+  Schema,
+  Extensions extends BlockNoteExtension<any>[],
+> {
+  /**
+   * The prosemirror plugins of the extension
+   */
+  extensions?: Extensions;
+
+  /**
+   * The schema that this extension adds to the editor
+   */
+  schema?: BlockNoteSchema<Schema>;
+
+  /**
+   * Add a dictionary of locales to the editor
+   */
+  dictionary?: Record<string, Locale>;
+
+  /**
+   * Items that are available to the slash menu
+   */
+  slashMenuItems?: (
+    | {
+        name: string;
+        icon?: any;
+        onClick: () => void;
+      }
+    // or return a component
+    | (() => any)
+  )[];
+
+  /**
+   * Items that are available to the formatting toolbar
+   */
+  formattingToolbar?: (
+    | {
+        name: string;
+        icon?: any;
+        onClick: () => void;
+      }
+    // or return a component
+    | (() => any)
+  )[];
+}
+
+export type Locale = Record<string, string | Record<string, string>>;
+
+/**
+ * This is an example of what an extension might look like
+ */
+export function multiColumnExtension(extensionOptions: {
+  dropCursor?: Record<string, string>;
+  columnResize?: Record<string, string>;
+}) {
+  return (editor) =>
+    ({
+      schema: withMultiColumnSchema(editor.schema),
+      extensions: [
+        multiColumnDropCursor(editor),
+        columnResizeExtension(editor),
+      ],
+      slashMenuItems: [
+        {
+          name: "2 Column",
+          icon: {},
+          onClick: () => {},
+        },
+      ],
+      formattingToolbar: [
+        {
+          name: "Multi Column",
+          icon: {},
+          onClick: () => {},
+        },
+      ],
+    }) satisfies BlockNoteBundleConfig<any, any[]>;
+}

adr/BlockNoteExtension.ts

@@ -1,54 +1,12 @@
-import {
-  BlockNoteEditor,
-  BlocksChanged,
-  Schema,
-  Selection,
-} from "@blocknote/core";
+import { BlockNoteEditor } from "@blocknote/core";
 import { Store } from "@tanstack/store";
-import { Plugin, Transaction } from "prosemirror-state";
+import { Plugin } from "prosemirror-state";
 
-/**
- * This is an abstract class to make it easier to implement an extension using a class.
- */
-export abstract class BlockNoteExtension<
-  State,
-  BSchema extends Schema = Schema,
-> {
-  public key = "not-implemented";
-  public store?: Store<State>;
-  public priority?: number;
-  public plugins?: Plugin[];
-  public keyboardShortcuts?: Record<
-    string,
-    (context: ExtensionContext<BSchema>) => boolean
-  >;
-  public onCreate?: (context: ExtensionContext<BSchema>) => void;
-  public onMount?: (context: ExtensionContext<BSchema>) => void;
-  public onUnmount?: (context: ExtensionContext<BSchema>) => void;
-  public onChange?: (
-    context: ExtensionContext<BSchema> & {
-      getChanges: () => BlocksChanged;
-    },
-  ) => void;
-  public onSelectionChange?: (
-    context: ExtensionContext<BSchema> & {
-      getSelection: () => Selection<any, any, any> | undefined;
-    },
-  ) => void;
-  public onBeforeChange?: (
-    context: ExtensionContext<BSchema> & {
-      getChanges: () => BlocksChanged;
-      tr: Transaction;
-    },
-  ) => boolean | void;
-  public onTransaction?: (
-    context: ExtensionContext<BSchema> & {
-      tr: Transaction;
-    },
-  ) => void;
-}
+export type BlockNoteExtension<State> = (
+  editor: BlockNoteEditor,
+) => BlockNoteExtensionConfig<State>;
 
-export interface BlockNoteExtension<State, BSchema extends Schema = Schema> {
+export interface BlockNoteExtensionConfig<State> {
   /**
    * The name of this extension, must be unique
    */
@@ -62,7 +20,7 @@ export interface BlockNoteExtension<State, BSchema extends Schema = Schema> {
    */
   priority?: number;
   /**
-   * The plugins of the extension
+   * The prosemirror plugins of the extension
    */
   plugins?: Plugin[];
   /**
@@ -71,118 +29,57 @@ export interface BlockNoteExtension<State, BSchema extends Schema = Schema> {
    * If the function returns `true`, the shortcut is considered handled and will not be passed to other extensions.
    * If the function returns `false`, the shortcut will be passed to other extensions.
    */
-  keyboardShortcuts?: Record<
-    string,
-    (context: ExtensionContext<BSchema>) => boolean
-  >;
-
-  /**
-   * Called on initialization of the editor
-   * @note the view is not yet mounted at this point
-   */
-  onCreate?: (context: ExtensionContext<BSchema>) => void;
+  keyboardShortcuts?: Record<string, (context) => boolean>;
 
   /**
    * Called when the editor is mounted
    * @note the view is available
    */
-  onMount?: (context: ExtensionContext<BSchema>) => void;
+  onMount?: () => void;
 
   /**
    * Called when the editor is unmounted
    * @note the view will no longer be available after this is executed
    */
-  onUnmount?: (context: ExtensionContext<BSchema>) => void;
-
-  /**
-   * Called when an editor transaction is applied
-   */
-  onTransaction?: (
-    context: ExtensionContext<BSchema> & {
-      tr: Transaction;
-    },
-  ) => void;
-
-  /**
-   * Called when the editor content changes
-   * @note the changes are available
-   */
-  onChange?: (
-    context: ExtensionContext<BSchema> & {
-      getChanges: () => BlocksChanged;
-    },
-  ) => void;
-
-  /**
-   * Called when the selection changes
-   * @note the selection is available
-   */
-  onSelectionChange?: (
-    context: ExtensionContext<BSchema> & {
-      getSelection: () => Selection<any, any, any> | undefined;
-    },
-  ) => void;
-
-  /**
-   * Called before an editor change is applied,
-   * Allowing the extension to cancel the change
-   */
-  onBeforeChange?: (
-    context: ExtensionContext<BSchema> & {
-      getChanges: () => BlocksChanged;
-      tr: Transaction;
-    },
-  ) => boolean | void;
-}
-
-export interface ExtensionContext<BSchema extends Schema> {
-  editor: BlockNoteEditor<BSchema>;
-}
-
-/**
- * This is the class-form, where it can extend the abstract class
- */
-export class MyExtension extends BlockNoteExtension<{ abc: number[] }> {
-  public key = "my-extension";
-  public store = new Store({ abc: [1, 2, 3] });
-
-  constructor(_extensionOptions: { myCustomOption: string }) {
-    super();
-  }
-
-  getFoo() {
-    return 8;
-  }
+  onUnmount?: () => void;
 }
 
 /**
  * This is the object-form, where it can be just a function that returns an object that implements the interface
  */
-export function myExtension(_extensionOptions: {
-  myCustomOption: string;
-}): BlockNoteExtension<{ state: number }> {
+export function myExtension(_extensionOptions: { myCustomOption: string }) {
   const myState = new Store({ state: 0 });
-  return {
+  return ((editor) => ({
     key: "my-extension",
     store: myState,
-    onMount(context) {
-      context.editor.extensions.myExtension = this;
+    onMount() {
+      editor.onChange((change) => {
+        console.log(change);
+      });
       myState.setState({ state: 1 });
     },
-  };
+    getFoo() {
+      return 8;
+    },
+  })) satisfies BlockNoteExtension<{ state: number }>;
 }
 
 /**
  * This type exposes the public API of an extension, excluding any {@link BlockNoteExtension} methods (for cleaner typing)
  */
 export type ExtensionMethods<Extension extends BlockNoteExtension<any>> =
   Extension extends BlockNoteExtension<infer State>
-    ? Omit<Extension, Exclude<keyof BlockNoteExtension<State>, "store" | "key">>
+    ? Omit<
+        ReturnType<Extension>,
+        Exclude<keyof BlockNoteExtensionConfig<State>, "store" | "key">
+      >
     : never;
 
 /**
  * You'll notice that the `getFoo` method is the only  included type in the `MyExtensionMethods` type,
  * This makes it convenient to expose the right amount of details to the rest of the application (keeping the blocknote called methods hidden)
  */
-export type MyExtensionMethods = ExtensionMethods<MyExtension>;
+export type MyExtensionMethods = ExtensionMethods<
+  ReturnType<typeof myExtension>
+>;
 // editor.extensions.myExtension.getFoo();