refactor: less use of PartialBlocks and type cleanup #2111

YousefED · 2025-10-16T04:37:21Z

Summary

Clean types and Partial / full block concepts

Rationale

#2089 (review)

Changes

Removes a lot of uses of PartialBlock internally, where it's not necessary
Cleans up some of the internal types by removing / not exporting types

Impact

Testing

Should mostly be covered by existing unit tests

Manual testing still needed

Screenshots/Video

Checklist

Code follows the project's coding standards.
Unit tests covering the new feature have been added.
All existing tests pass.
The documentation has been updated to reflect the new feature

Additional Notes

TODO:

manual testing
fix remaining unit tests
get the build of examples to work.

Follow up:

clean more of blockToNode (there's logic there that handles partial content / blocks which is not needed anymore)
potentially, we could move the definition of Block and Partial lock to Zod as well, and use a transformer to distinguish between input and output types

vercel · 2025-10-16T04:37:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
blocknote	Error		Oct 17, 2025 6:30am
blocknote-website	Error		Oct 17, 2025 6:30am

YousefED · 2025-10-16T04:38:17Z

packages/core/src/api/blockManipulation/commands/insertBlocks/insertBlocks.ts

  S extends StyleSchema,
 >(
  tr: Transaction,
+  // TBD: allow PartialBlock here?


I think we could move it a layer up to the BlockNoteEditor (and only allow partials there, not in the commands. However, for updateBlock I don't think that's feasible, so maybe better to keep it here

These don't get run anywhere but from the editor instance, so imo it doesn't make too much a difference anyway

YousefED · 2025-10-16T04:40:10Z

packages/core/src/api/blockManipulation/tables/tables.ts

 * @returns an {@link OccupancyGrid}
 */
 export function getTableCellOccupancyGrid(
-  block: BlockFromConfigNoChildren<DefaultBlockSchema["table"], any, any>,


Stopped exporting BlockFromConfigNoChildren so we have more consistency in the codebase

While we are cleaning up types, I believe that:

BlockFromConfig<DefaultBlockSchema["table"], any, any>

Should only be:

BlockFromConfig<DefaultBlockSchema["table"]>

Most of the time we don't care about the other parameters, and have to remove their defaults with any. This goes for most instances of B, I, S

YousefED · 2025-10-16T04:40:48Z

packages/core/src/api/exporters/html/util/serializeBlocksExternalHTML.ts

-      (props as any)[name] = spec._zod.def.defaultValue;
-    }
-  }
+  // const props = block.props || {};


TODO: this code can now be deleted

YousefED · 2025-10-16T04:43:52Z

packages/core/src/editor/BlockNoteEditor.ts

-  StyleSpecs,
+import {
+  partialBlockToFullBlock,
+  type BlockIdentifier,


fyi, some of the changes in type imports were to fix a circular dependency issue that was breaking the build during development

YousefED · 2025-10-16T04:44:32Z

packages/core/src/editor/BlockNoteEditor.ts

   */
  public blocksToHTMLLossy(
-    blocks: PartialBlock<BSchema, ISchema, SSchema>[] = this.document,
+    blocks: Block<BSchema, ISchema, SSchema>[] = this.document,


breaking API change, should be documented in PR / release notes

YousefED · 2025-10-16T04:47:27Z

packages/core/src/extensions/TableHandles/TableHandlesPlugin.ts

    }

    // Hide handles if the table block has been removed.
-    this.state.block = this.editor.getBlock(this.state.block.id)!;


TODO: In the old version we were potentially setting this.state.block to undefined. Now, it will keep the old (unavailable block). can this break anything?

It isn't clear to me why this was modified, but it certainly is a change in behavior that would need to be validated

YousefED · 2025-10-16T04:48:16Z

packages/core/src/schema/blocks/types.ts

- *
- */
-
-export type PartialTableCell<


moved to separate table file

YousefED · 2025-10-16T04:48:24Z

packages/core/src/schema/blocks/types.ts

    children: PartialBlockNoDefaults<BSchema, I, S>[];
  }>;

-export type SpecificPartialBlock<


unused, removed

YousefED · 2025-10-16T04:49:38Z

packages/core/src/util/table.ts

        }
      : {
          type: "tableCell",
+          // FIXME: content can actually be Partial, we should probably handle this as well


This comment is to document a finding Matthew earlier found while writing the partialToFull function

YousefED · 2025-10-16T05:09:52Z

.vscode/settings.json

  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.addMissingImports": "explicit"


fyi, this makes sure missing imports are added automatically on save, I kept finding myself to do this manually (or AI-powered)

nperez0111 · 2025-10-16T05:56:31Z

packages/core/src/api/blockManipulation/commands/insertBlocks/insertBlocks.ts

  S extends StyleSchema,
 >(
  tr: Transaction,
+  // TBD: allow PartialBlock here?


These don't get run anywhere but from the editor instance, so imo it doesn't make too much a difference anyway

nperez0111 · 2025-10-16T05:59:11Z

packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts

    // for this, we do a nodeToBlock on the existing block to get the children.
    // it would be cleaner to use a ReplaceAroundStep, but this is a bit simpler and it's quite an edge case
-    const existingBlock = nodeToBlock(blockInfo.bnBlock.node, pmSchema);
+    const newFullBlock = partialBlockToFullBlock(schema, block);


Suggested change

const newFullBlock = partialBlockToFullBlock(schema, block);

const newBlock = partialBlockToFullBlock(schema, block);

There are partial blocks & blocks. Full block gives a third name which is not helpful

nperez0111 · 2025-10-16T06:02:52Z

packages/core/src/api/blockManipulation/tables/tables.ts

+    // TODO: what happened here?
+    return isCellEmpty(cell);


Is this wrong? It is recursing, what you've written is an infinite loop no?

nperez0111 · 2025-10-16T06:05:18Z

packages/core/src/api/blockManipulation/tables/tables.ts

 * @returns an {@link OccupancyGrid}
 */
 export function getTableCellOccupancyGrid(
-  block: BlockFromConfigNoChildren<DefaultBlockSchema["table"], any, any>,


While we are cleaning up types, I believe that:

BlockFromConfig<DefaultBlockSchema["table"], any, any>

Should only be:

BlockFromConfig<DefaultBlockSchema["table"]>

Most of the time we don't care about the other parameters, and have to remove their defaults with any. This goes for most instances of B, I, S

nperez0111 · 2025-10-16T06:06:23Z

packages/core/src/api/exporters/html/externalHTMLExporter.ts

      const domFragment = serializeInlineContentExternalHTML(
        editor,
-        inlineContent as any,
+        inlineContent as unknown as never,


~~ as never? Why so? ~~
nvm, I see the todo

nperez0111 · 2025-10-16T06:10:32Z

packages/core/src/api/nodeConversions/blockToNode.ts

-  let id = block.id;
-
-  if (id === undefined) {
-    id = UniqueID.options.generateID();
-  }
-


I'm actually ok with this function generating ids if the block doesn't have one. I think this makes the caller's life more difficult to be forced to present an ID

nperez0111 · 2025-10-16T06:18:05Z

packages/core/src/extensions/TableHandles/TableHandlesPlugin.ts

+      blockHasType(
+        block,
+        this.editor,
+        "table",
+        defaultBlockSpecs.table.config.propSchema,
+      )


Why are we changing this?

Am I right to assume that this would mean that it can now only match the block if it is both a table & conforming to the propSchema? Why does the propSchema matter here? What if someone extends the table to have additional props, wouldn't this break?

nperez0111 · 2025-10-16T06:18:46Z

packages/core/src/extensions/TableHandles/TableHandlesPlugin.ts

    }

    // Hide handles if the table block has been removed.
-    this.state.block = this.editor.getBlock(this.state.block.id)!;


It isn't clear to me why this was modified, but it certainly is a change in behavior that would need to be validated

nperez0111 · 2025-10-16T06:24:54Z

packages/core/src/schema/partialBlockToFullBlock.ts

+  // TODO: I think this should be a CustomBlockNoteSchema,
+  // but that breaks docxExporter etc


Yep, it should be

refactor types and partial / full

bd154ed

vercel bot had a problem deploying to Preview – blocknote October 16, 2025 04:38 Failure

vercel bot had a problem deploying to Preview – blocknote-website October 16, 2025 04:39 Failure

YousefED added 5 commits October 16, 2025 06:41

remove unneeded code

30c5581

fix !

f2d191e

fix build

75bd4e5

remove SpecificBlock

5eb10ec

fix build

b99822a

YousefED commented Oct 16, 2025

View reviewed changes

YousefED changed the title ~~refactor types and partial / full~~ refactor: less use of PartialBlocks and type cleanup Oct 16, 2025

vercel bot had a problem deploying to Preview – blocknote October 16, 2025 05:10 Failure

fix core tests

53bd6d7

vercel bot had a problem deploying to Preview – blocknote-website October 16, 2025 05:14 Failure

nperez0111 reviewed Oct 16, 2025

View reviewed changes

vercel bot had a problem deploying to Preview – blocknote-website October 17, 2025 06:28 Failure

vercel bot had a problem deploying to Preview – blocknote October 17, 2025 06:30 Failure

	const newFullBlock = partialBlockToFullBlock(schema, block);
	const newBlock = partialBlockToFullBlock(schema, block);

		// TODO: I think this should be a CustomBlockNoteSchema,
		// but that breaks docxExporter etc

Uh oh!

refactor: less use of PartialBlocks and type cleanup #2111

Are you sure you want to change the base?

refactor: less use of PartialBlocks and type cleanup #2111

Uh oh!

Conversation

YousefED commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Rationale

Changes

Impact

Testing

Screenshots/Video

Checklist

Additional Notes

Uh oh!

vercel bot commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

YousefED commented Oct 16, 2025 •

edited

Loading

vercel bot commented Oct 16, 2025 •

edited

Loading