feat: bunch of proposals

Author: nperez0111

adr/2025_06_13-document-transforms.md

@@ -0,0 +1,20 @@
+# Document Transforms
+
+A core part of the BlockNote API is the ability to make changes to the document, using BlockNote's core design of blocks, this is much easier to do programmatically than with other editors.
+
+We've done pretty well with our existing API, but there are a few things that could be improved.
+
+Referencing content within the document is either awkward or non-existent. Right now we essentially really only have an API for referencing blocks by their id with no further level of granularity.
+
+## Locations
+
+[Looking at Slate](https://docs.slatejs.org/concepts/03-locations) (highly recommend reading the docs), they have the concept of a `Location` which is a way to reference a specific point in the document, but it does not have to be so specific as positions, it has levels of granularity.
+
+This gives us a unified way to reference content within the document, allowing for much more granular editing. Take a look at the `Location.ts` file for more details around this.
+
+## Transforms separation of concerns
+
+Right now all transformation functions are defined directly on the `Editor` instance, this is not ideal because it only further muddles the API.
+
+Instead, we should have a separate `Transform` class which defines methods that operate on the editor's document to make changes to it. This will also be very useful for doing server-side transformations.
+

adr/2025_06_13-extensions.md

@@ -0,0 +1,41 @@
+# BlockNote Extension API
+
+It is definitely more designed by accident than intention, so let's put some thought into the sort of API we would want people to build extensions with.
+
+## Core Requirements
+
+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.
+
+## State Management
+
+What I had the most trepidation about was deciding on whether we should prescribe a state management library, and if so, which one.
+
+I think the answer is _yes_, we should prescribe a state management library, and I think the answer is @tanstack/store.
+
+<details>
+<summary>Why @tanstack/store? And not something else?</summary>
+It comes with a few benefits:
+
+- It gives a single API for all state management, which is more convenient/consistent for consumers
+
+As for which library to use, I think we should use @tanstack/store.
+
+- The store is very simple, and can easily be re-implemented if needed
+- There is already bindings for most major frameworks, but can be used without them
+- It seems that anything tanstack does will be widely adopted so it should be a pretty safe bet
+
+What I had trouble with is there are a few different use-cases for state management, events like we have now aren't great because they put the burden on the consumer to manage the state. Or, they can emit an event (e.g. `update`), but then have to round-trip back to the extension to get the state (and somehow store it on their side again).
+
+Something like observables have a nicer API for this, but they are for pushing data (i.e. multiple readers), not for pulling it (i.e. any writers). They also have the same problem of putting the burden on the consumer.
+
+Signals are a nice middle ground, being that they are for both pushing & pulling data. The problem is that there are many implementations, and not super well-known in the React ecosystem.
+
+Zustand is a popular library, but allowing partial states makes it somewhat unsafe in TypeScript.
+
+Jotai is probably my second choice, but it makes it a bit awkward to update states because it relies on a separate store instance rather than the "atom" being able to update itself <https://jotai.org/docs/guides/using-store-outside-react>.
+</details>

adr/2025_06_13-schema.md

@@ -0,0 +1,21 @@
+# BlockNote Schema
+
+Right now it is overly burdensome to have to pass around 3 different types to the editor, and it is also not very type-safe (when you just end up with `any` everywhere).
+
+The idea is to have a single type that is a union of the 3 types, and then make type predicates available to check if accessed properties are valid (and likely just assertions too).
+
+You'll see some of what I came up with in the `Schema.ts` file.
+
+You'll also notice that the default blocks, inline content, styles, and groups are all defined in the `@blocknote/core/blocks` package. This is assuming that we have already moved them to the blocknote API and out of the core package.
+
+## Groups
+
+In a somewhat similar vein, I think there might be use for having an indirection layer for referring to specific blocks, inline content, styles, etc. Reason being that it allows callers to refer to a group of things with a single identifier, and allow customizing that membership by just modifying that group.
+
+Examples include:
+
+- Keyboard shortcuts can refer to a group of blocks/inline-content/styles without modification to the handler
+- Relationships between blocks/inline-content/styles can be defined (e.g. allow for a todo block to only have todo item children)
+- Properties of blocks/inline-content/styles can be defined (e.g. adding `heading` to the `toggleable` group)
+
+This may or may not be useful, but it is a thought.

adr/BlockNoteExtension.ts

@@ -0,0 +1,169 @@
+import {
+  BlockNoteEditor,
+  BlocksChanged,
+  Schema,
+  Selection,
+} from "@blocknote/core";
+import { Store } from "@tanstack/store";
+import { Plugin, Transaction } 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 interface BlockNoteExtension<State, BSchema extends Schema = Schema> {
+  /**
+   * The name of this extension, must be unique
+   */
+  key: string;
+  /**
+   * The state of the extension, this is a @tanstack/store store instance
+   */
+  store?: Store<State>;
+  /**
+   * The priority of this extension, used to determine the order in which extensions are applied
+   */
+  priority?: number;
+  /**
+   * The plugins of the extension
+   */
+  plugins?: Plugin[];
+  /**
+   * Keyboard shortcuts this extension adds to the editor.
+   * The key is the keyboard shortcut, and the value is a function that returns a boolean indicating whether the shortcut was handled.
+   * 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;
+
+  /**
+   * Called when the editor is mounted
+   * @note the view is available
+   */
+  onMount?: (context: ExtensionContext<BSchema>) => 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();
+  }
+}
+
+/**
+ * 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 }> {
+  const myState = new Store({ state: 0 });
+  return {
+    key: "my-extension",
+    store: myState,
+    onMount(context) {
+      context.editor.extensions.myExtension = this;
+      myState.setState({ state: 1 });
+    },
+  };
+}

adr/Schema.ts

@@ -0,0 +1,70 @@
+import { Schema } from "@blocknote/core";
+import {
+  defaultBlocks,
+  defaultInlineContent,
+  defaultStyles,
+  defaultGroups,
+} from "@blocknote/core/blocks";
+
+type Schema = {
+  blocks: Record<string, BlockSchema>;
+  inlineContent: Record<string, InlineContentSchema>;
+  styles: Record<string, StyleSchema>;
+  groups: Record<string, Set<string>>;
+} & {
+  // Some sort of a type predicate to make sure the block is in the schema, and type better if it is
+  hasBlock(
+    editor: BlockNoteEditor<Schema>,
+    block: string,
+  ): editor is BlockNoteEditor<Schema>;
+  // Other predicates
+  hasInlineContent: (inlineContent: string) => boolean;
+  hasStyle: (style: string) => boolean;
+  getGroup: (group: string) => string[];
+  // etc
+};
+
+// One thing, instead of 3!
+// Pass around just this single type.
+// If we need each type explicitly, we can do something like:
+// type Schema = [BlockSchema, InlineContentSchema, StyleSchema]
+// And destructure if needed
+export const schema = Schema.create({
+  /**
+   * Which blocks are in my editor?
+   */
+  blocks: {
+    ...defaultBlocks,
+    // todoList:
+  },
+  /**
+   * Which inline content is in my editor?
+   */
+  inlineContent: {
+    ...defaultInlineContent,
+    // todoItem:
+  },
+  /**
+   * Which styles are in my editor?
+   */
+  styles: {
+    ...defaultStyles,
+  },
+  /**
+   * Which groups are in my editor?
+   *
+   * A group is a set of editor blocks/inline-content/styles that are related to each other in some way.
+   * This allows for referring to a bunch of blocks/inline-content/styles at once.
+   *
+   * This is useful for things like:
+   * - Keyboard shortcuts can refer to a group of blocks/inline-content/styles without modification to the handler
+   * - relationships between blocks/inline-content/styles can be defined (e.g. allow for a todo block to only have todo item children)
+   */
+  groups: {
+    ...defaultGroups,
+    todoList: new Set(["todoList", "todoItem"]),
+  },
+});
+
+// This instance would live under the editor instance and needed for instantiating the editor
+editor.schema = schema;

packages/core/package.json

@@ -76,6 +76,7 @@
   "dependencies": {
     "@emoji-mart/data": "^1.2.1",
     "@shikijs/types": "3.2.1",
+    "@tanstack/store": "0.7.1",
     "@tiptap/core": "^2.12.0",
     "@tiptap/extension-bold": "^2.11.5",
     "@tiptap/extension-code": "^2.11.5",
@@ -91,6 +92,7 @@
     "@tiptap/extension-text": "^2.11.5",
     "@tiptap/extension-underline": "^2.11.5",
     "@tiptap/pm": "^2.12.0",
+    "alien-signals": "2.0.5",
     "emoji-mart": "^5.6.0",
     "hast-util-from-dom": "^5.0.1",
     "prosemirror-dropcursor": "^1.8.1",
@@ -110,6 +112,7 @@
     "remark-stringify": "^11.0.0",
     "unified": "^11.0.5",
     "uuid": "^8.3.2",
+    "valtio": "2.1.5",
     "y-prosemirror": "^1.3.4",
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.15"