feat: API design feedback

adr/2025_06_13-document-transforms.md

@@ -0,0 +1,65 @@
+# 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.
+
+```ts
+editor.transform.insertBlocks(ctx:{
+  at: Location,
+  blocks: Block | Block[]
+});
+
+editor.transform.replaceBlocks(ctx: {
+  at: Location,
+  with: Block | Block[]
+})
+
+editor.transform.replaceContent(ctx: {
+  at: Location,
+  with: InlineContent | InlineContent[]
+})
+
+editor.transform.deleteContent(ctx: {
+  at: Location,
+})
+```
+
+## References
+
+Currently, we do not have a good way to reference things about content within a document, except by block id. With Locations, we can be much more granular & more powerful.
+
+I think one application of this would be to introduce the concept of "references" to content within a document. For example, we currently do not store comments into the blocknote json, taking the position that it really is not part of the document, but rather metadata about the document.
+
+With references, we could store comments with references to the blocks that they are about. And map those references through changes if they are ever modified. For example, if someone commented on the text within block id `123`, and then the block was moved to a new location, we could update the comment to reference the new block id.
+
+So, this would allow a comment to still be a separate entity, but be able to "hydrate" within the editor and keep track of the content that it was about.
+
+```ts
+type Reference<Metadata extends Record<string, any>> = {
+  to: Location,
+  metadata: Metadata
+}
+
+type Comment = Reference<{
+  threadId: string
+}>
+
+editor.references.add(reference: Reference, onUpdate: (reference: Reference) => void);
+```
+
+This is inspired by [bluesky's concept of facets for rich text content](https://docs.bsky.app/docs/advanced-guides/post-richtext) which is a great example of how to make block note content more inter-operable between different applications.

adr/2025_06_13-extensions.md

@@ -0,0 +1,60 @@
+# 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 `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
+
+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>
+
+## Exposing extension methods
+
+Not everything can be communicated through just state, so we need to be able to expose additional methods to the application.
+
+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/2025_06_13-packages.md

@@ -0,0 +1,36 @@
+# BlockNote Packages & Sub-Packages
+
+## Core
+
+The `@blocknote/core` package should contain everything needed to build a pure JS editor instance. It has no opinion on the UI layer, and is only concerned with the core editor functionality.
+
+It contains sub-packages for:
+
+- `@blocknote/core/blocks` - Contains the default blocks, inline content, styles and their implementations (excluding things like blockContainer, blockGroup, etc which are core to the editor but should not be part of the schema).
+  - `@blocknote/core/blocks/header` - Contains the header block.
+  - `@blocknote/core/blocks/code-block` - Contains the code block block.
+  - etc...
+- `@blocknote/core/extensions` - Re-exports the extension packages below.
+  - `@blocknote/core/extensions/comments` - Contains the comments extension.
+- `@blocknote/core/exporter` - Contains the exporter package.
+  - `@blocknote/core/exporter/html` - Contains the html exporter package.
+  - `@blocknote/core/exporter/markdown` - Contains the markdown exporter package.
+- `@blocknote/core/server-util` - Contains the server util package.
+- `@blocknote/core/locales` - Contains the locales package.
+
+## React
+
+The `@blocknote/react` package should contain everything needed to build a React editor instance. It has no opinion on the core editor functionality, and is only concerned with the React UI layer.
+
+It contains sub-packages for:
+
+- `@blocknote/react/editor` - Contains the editor package.
+  - `@blocknote/react/comments` - Contains the comments package.
+  - `@blocknote/react/table-handles` - Contains the table handles package.
+  - etc... (need to figure out what needs to be exported vs. available and how coupled this all is)
+
+## Editor instance
+
+The editor instance has been growing in complexity, and handles too many different concerns. To focus it, we should split it up into something like: the `BlockNoteEditor.ts` file.
+
+The goal would be to group the functionality of the editor instance in such a way that it is easier to navigate and understand.

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/2025_06_16-configuration.md

@@ -0,0 +1,28 @@
+# BlockNote Configuration
+
+Editors are widely different across applications, often with users having opposing requirements. Most editors explode with complexity when trying to support all of these use cases. So, there needs to be a guide for the different ways to configure so that there is not just a single overwhelming list of options.
+
+Fundamentally, there are few different kinds of things to be configured:
+
+- **block-configuration**: The configuration for a specific kind of block
+  - e.g. the `table` block might have toggles for enabling/disabling the header rows/columns
+- **schema-configuration**: The configuration of what blocks, inline content, and styles are available in the editor
+  - e.g. whether to include the `table` block at all
+- **extension-level-configuration**: The configuration of the extension itself
+  - e.g. what ydoc should the collaboration extension use
+- **extension-configuration**: The configuration of the extensions that are available in the editor
+  - e.g. whether to add collaboration to the editor
+- **editor-view-configuration**: The configuration of the editor views
+  - e.g. whether to show the sidebar, the toolbar, etc.
+- **editor-configuration**: The configuration of the editor itself
+  - e.g. how to handle paste events
+
+These forms of configuration are not mutually exclusive, and can be combined in different ways. For example, knowing that the editor has collaboration enabled, might change the what the keybindings do for undo/redo.
+
+In an ideal world, these configurations would be made at the "lowest possible level", like configuring the number of levels of headings would be configured when composing the schema for the editor, rather than at the editor level.
+
+Configuration should be publicly accessible, so that mixed combinations can be created (i.e. different behaviors for an editor with or without collaboration).
+
+## TODO
+
+- Describe how you configure at the block level, then compose that into a schema, the compose that into an editor, and then compose that into a view.

adr/2025_06_16-nested-blocks.md

@@ -0,0 +1,155 @@
+# BlockNote Nested Blocks
+
+There are two separate problems when it comes to "nested blocks" support in BlockNote:
+
+- **nested-blocks** The first is the ability for a block to contain other blocks within it (e.g. a table cell having not just inline content, but actual other blocks inside it)
+- **content-fields** The second is the ability for a block to contain multiple pieces of content within it (e.g. an alert block having a title & description field (which contain inline content))
+
+Let's start with the first problem, nested blocks. By describing existing block relationships:
+
+## Block with inline content
+
+This is the simplest case, and the only one that is currently supported by BlockNote.
+
+```json
+{
+  "type": "block-type",
+  "content": [
+    {
+      "type": "text",
+      "text": "Hello, world!"
+    }
+  ],
+}
+```
+
+There is a 1:1 relationship between the block type and it's content. And, no restrictions of the inline content allowed within the block.
+
+> TODO come up with a description of the sorts of keybinds & cursor behavior that should be supported for this block type
+
+## Block with nested blocks
+
+This is a proposal for how to support nested blocks.
+
+```json
+{
+  "type": "custom-block-type",
+  "props": {
+    "abc": 123
+  },
+  "content": null,
+  "children": [
+    {
+      "type": "nested-block",
+      "content": [
+        {
+          "type": "block",
+          "content": [
+            {
+              "type": "text",
+              "text": "Hello, world!"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+This would completely enclose all nested blocks within the `custom-block-type` block. And, works the same way as the multi-column example.
+
+> TODO come up with a description of the sorts of keybinds & cursor behavior that should be supported for this block type
+
+## Block with structured inline content fields
+
+This is a proposal for how to support multiple inline content fields within a block.
+
+```json
+{
+  "type": "alert",
+  "content": null,
+  "children": [
+    {
+      "type": "alert-title",
+      "content": [
+        {
+          "type": "text",
+          "text": "Hello, world!"
+        }
+      ]
+    },
+    {
+      "type": "alert-content",
+      "content": [
+        {
+          "type": "text",
+          "text": "Hello, world!"
+        }
+      ]
+    }
+  ]
+}
+```
+
+The core idea is that the `parent` block restricts what content is allowed within it's children.
+
+> TODO come up with a description of the sorts of keybinds & cursor behavior that should be supported for this block type
+
+## Examples
+
+### Rebuilding tables with nested blocks
+
+Using this new structure, we can rebuild tables if we had this new API:
+
+```json
+{
+  "type": "table",
+  "content": null,
+  "props": {
+    "backgroundColor": "default",
+    "textColor": "default",
+    "columnWidths": [100, 100, 100],
+    "headerRows": 1,
+    "headerCols": 1,
+  },
+  "children": [
+    {
+      "type": "table-row",
+      "content": null,
+      "children": [
+        {
+          "type": "table-cell",
+          "content": null,
+          "children": [
+            {
+              "type": "paragraph",
+              "content": [
+                {
+                  "type": "text",
+                  "text": "Hello, world!"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "table-cell",
+          "content": null,
+          "children": [
+            {
+              "type": "paragraph",
+              "content": [
+                {
+                  "type": "text",
+                  "text": "Hello, world!"
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```