feat: initial version of the blocknote extension API

Author: nperez0111

adr/2025_06_13-extensions.md

@@ -0,0 +1,253 @@
+# BlockNote Extension API
+
+## Status
+
+Proposed
+
+## Context
+
+BlockNote needs a flexible and powerful extension system to allow developers to add custom functionality to the editor. The extension system should be type-safe, easy to use, and provide hooks into various editor lifecycle events.
+
+## Decision
+
+We will implement an extension system based on a class/interface-based approach that provides:
+
+1. Type-safe extension development
+2. Lifecycle hooks for editor events
+3. State management capabilities
+4. Plugin integration
+5. Keyboard shortcut handling
+
+## Implementation Details
+
+### Extension Definition
+
+Extensions can be implemented in two ways:
+
+1. **Class-based approach** - Extending the abstract `BlockNoteExtension` class
+2. **Object-based approach** - Implementing the `BlockNoteExtension` interface
+
+### Core Properties
+
+- `key`: Unique identifier for the extension
+- `store`: Optional state management using @tanstack/store
+- `priority`: Optional number to determine extension execution order
+- `plugins`: Optional array of ProseMirror plugins
+- `keyboardShortcuts`: Optional record of keyboard shortcut handlers
+
+### Lifecycle Hooks
+
+Extensions can implement the following lifecycle hooks:
+
+#### `onCreate`
+
+- Called during editor initialization
+- View is not yet mounted
+- Use for initial setup
+
+#### `onMount`
+
+- Called when editor is mounted
+- View is available
+- Use for DOM-related setup
+
+#### `onUnmount`
+
+- Called when editor is unmounted
+- View will be unavailable after execution
+- Use for cleanup
+
+### Event Handlers
+
+#### `onChange`
+
+- Triggered when editor content changes
+- Provides access to change information via `getChanges()`
+
+#### `onSelectionChange`
+
+- Triggered when editor selection changes
+- Provides access to current selection via `getSelection()`
+
+#### `onBeforeChange`
+
+- Called before changes are applied
+- Can cancel changes by returning `false`
+- Provides access to changes and transaction
+
+#### `onTransaction`
+
+- Called when a ProseMirror transaction is applied
+- Provides access to the transaction object
+
+### Example Implementation
+
+```typescript
+// Class-based approach
+class MyExtension extends BlockNoteExtension<{ abc: number[] }> {
+  public key = "my-extension";
+  public store = new Store({ abc: [1, 2, 3] });
+
+  constructor(options: { myCustomOption: string }) {
+    super();
+  }
+}
+
+// Object-based approach
+function myExtension(options: { 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 });
+    },
+  };
+}
+```
+
+## API Reference
+
+### Types
+
+```typescript
+type Schema = [BlockSchema, InlineContentSchema, StyleSchema];
+
+interface BlockNoteExtension<State, BSchema extends Schema = Schema> {
+  key: string;
+  store?: Store<State>;
+  priority?: number;
+  plugins?: Plugin[];
+  keyboardShortcuts?: Record<string, (context: BlockNoteExtensionContext<BSchema>) => boolean>;
+  onCreate?: (context: BlockNoteExtensionContext<BSchema>) => void;
+  onMount?: (context: BlockNoteExtensionContext<BSchema>) => void;
+  onUnmount?: (context: BlockNoteExtensionContext<BSchema>) => void;
+  onChange?: (context: BlockNoteExtensionContext<BSchema> & { getChanges: () => BlocksChanged }) => void;
+  onSelectionChange?: (context: BlockNoteExtensionContext<BSchema> & { getSelection: () => Selection<any, any, any> | undefined }) => void;
+  onBeforeChange?: (context: BlockNoteExtensionContext<BSchema> & { getChanges: () => BlocksChanged; tr: Transaction }) => boolean | void;
+  onTransaction?: (context: BlockNoteExtensionContext<BSchema> & { tr: Transaction }) => void;
+}
+
+interface BlockNoteExtensionContext<BSchema extends Schema> {
+  editor: BlockNoteEditor<BSchema[0], BSchema[1], BSchema[2]>;
+}
+```
+
+### Properties
+
+#### `key`
+
+- **Type**: `string`
+- **Required**: Yes
+- **Description**: Unique identifier for the extension. Must be unique across all extensions.
+
+#### `store`
+
+- **Type**: `Store<State>`
+- **Required**: No
+- **Description**: State management store using @tanstack/store. Used to maintain extension state.
+
+#### `priority`
+
+- **Type**: `number`
+- **Required**: No
+- **Description**: Determines the order in which extensions are applied. Higher numbers are applied first.
+
+#### `plugins`
+
+- **Type**: `Plugin[]`
+- **Required**: No
+- **Description**: Array of ProseMirror plugins to be added to the editor.
+
+#### `keyboardShortcuts`
+
+- **Type**: `Record<string, (context: BlockNoteExtensionContext<BSchema>) => boolean>`
+- **Required**: No
+- **Description**: Map of keyboard shortcuts to handler functions. Return `true` to prevent other extensions from handling the shortcut.
+
+### Methods
+
+#### `onCreate(context: BlockNoteExtensionContext<BSchema>)`
+
+- **Called**: During editor initialization
+- **Context**: Editor instance available, view not mounted
+- **Use Case**: Initial setup, configuration
+
+#### `onMount(context: BlockNoteExtensionContext<BSchema>)`
+
+- **Called**: When editor is mounted
+- **Context**: Editor instance and view available
+- **Use Case**: DOM-related setup, event listeners
+
+#### `onUnmount(context: BlockNoteExtensionContext<BSchema>)`
+
+- **Called**: When editor is unmounted
+- **Context**: Editor instance available, view will be removed
+- **Use Case**: Cleanup, removing event listeners
+
+#### `onChange(context: BlockNoteExtensionContext<BSchema> & { getChanges: () => BlocksChanged })`
+
+- **Called**: When editor content changes
+- **Context**: Editor instance and change information
+- **Use Case**: Reacting to content changes
+
+#### `onSelectionChange(context: BlockNoteExtensionContext<BSchema> & { getSelection: () => Selection<any, any, any> | undefined })`
+
+- **Called**: When editor selection changes
+- **Context**: Editor instance and selection information
+- **Use Case**: Reacting to selection changes
+
+#### `onBeforeChange(context: BlockNoteExtensionContext<BSchema> & { getChanges: () => BlocksChanged; tr: Transaction })`
+
+- **Called**: Before changes are applied
+- **Context**: Editor instance, changes, and transaction
+- **Return**: `boolean | void` - Return `false` to cancel the change
+- **Use Case**: Validating or modifying changes before they're applied
+
+#### `onTransaction(context: BlockNoteExtensionContext<BSchema> & { tr: Transaction })`
+
+- **Called**: When a ProseMirror transaction is applied
+- **Context**: Editor instance and transaction
+- **Use Case**: Reacting to or modifying transactions
+
+### Usage Examples
+
+#### Basic Extension
+
+```typescript
+const basicExtension: BlockNoteExtension<{ count: number }> = {
+  key: "basic",
+  store: new Store({ count: 0 }),
+  onMount(context) {
+    console.log("Editor mounted");
+  }
+};
+```
+
+#### Extension with Keyboard Shortcuts
+
+```typescript
+const shortcutExtension: BlockNoteExtension<{}> = {
+  key: "shortcuts",
+  keyboardShortcuts: {
+    "Mod-b": (context) => {
+      // Handle bold shortcut
+      return true; // Prevent other extensions from handling
+    }
+  }
+};
+```
+
+#### Extension with State Management
+
+```typescript
+class StatefulExtension extends BlockNoteExtension<{ items: string[] }> {
+  key = "stateful";
+  store = new Store({ items: [] });
+
+  onMount(context) {
+    this.store.setState({ items: ["new item"] });
+  }
+}
+```