feature: v0.10: tables, custom inline content, custom styles, better copy / paste handling

[YousefED]

This PR is a major overhaul of BlockNote and brings in several new features.

The following PRs are part of this:

• Tables: feat: tables #413
• Better copy / paste handling: feat: Custom block serialization #257 feat: HTML paste handling #422 Custom inline content and styles commands/copy & paste fixes #425
• Support for custom inline content, custom styles, and related refactors: refactor types for blocks #412 feat: custom styles and custom inline content #418 use refs for blocks #424

(note that these PRs have been merged into each other, so the code change view will not be ideal)

Features

Some nice new stuff now possible with BlockNote!

Tables

Closes #194

Custom Inline Content and Custom Styles

Until now, it was only possible to create your own custom Blocks. Now, you can also create custom Styles and Inline Content. Styles are markup that can be enabled on text (think bold, italic, etc.). Custom Inline Content can be used for "inline blocks", for example for Mentions.

Closes #267

Better copy paste handling

The copy / paste and Blocks to / from Markdown / HTML system has been overhauled and should be more robust. Copying and pasting of custom blocks is now also supported!

Closes #221 #69 #361 #381 #282 #226 #249

Breaking changes:

Custom Block API

If you're using Custom Blocks (createReactBlockSpec), there are 3 major changes:

• The "schema" of your block and the "implementation" are now separated
• The <InlineContent /> element has been removed in favor of contentRef
• Use content: "inline" | "none" instead of containsInlineContent: boolean

Old (deprecated) code example:

const ImageBlock = createReactBlockSpec({
  type: "image",
  propSchema: {
    src: {
      default: "https://via.placeholder.com/1000",
    },
  },
  containsInlineContent: true,
  render: ({ block }) => (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
      }}>
      <img
        style={{
          width: "100%",
        }}
        src={block.props.src}
        alt={"Image"}
        contentEditable={false}
      />
      <InlineContent />
    </div>
  ),
});

New version:

const ImageBlock = createReactBlockSpec({
  type: "image",
  propSchema: {
    src: {
      default: "https://via.placeholder.com/1000",
    },
  },
  content: "inline"
}, {
  render: ({ block, contentRef }) => (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
      }}>
      <img
        style={{
          width: "100%",
        }}
        src={block.props.src}
        alt={"Image"}
        contentEditable={false}
      />
      <span ref={contentRef} />
    </div>
  ),
});

Additionally, blockSchemas are now blockSpecs, so to pass in the blocks that you want the editor to use:

const editor = useBlockNote({
  blockSpecs: {
    ...defaultBlockSpecs,
    image: ImageBlock
  }
});

In functions that still require a BlockSchema type, you can use the getBlockSchemaFromSpecs function, e.g. for getDefaultReactSlashMenuItems:

const blockSpecs = {
  ...defaultBlockSpecs,
  image: ImageBlock
}

const blockSchema = getBlockSchemaFromSpecs(blockSpecs);

const editor = useBlockNote({
  blockSpecs: blockSpecs,
  slashMenuItems: {
    ...getDefaultReactSlashMenuItems(blockSchema),
    insertImageBlock
  }
});

Naming of export / parse functions

To better indicate the conversion to / from Markdown and HTML is lossy, the following functions have been renamed:

• editor.blocksToHTML -> editor.blocksToHTMLLossy
• editor.HTMLToBlocks -> editor.tryParseHTMLToBlocks
• editor.blocksToMarkdown -> editor.blocksToMarkdownLossy
• editor.markdownToBlocks -> editor.tryParseMarkdownToBlocks

Vanilla (non-react) constructor usage

Instead of new BlockNoteEditor(...), now use BlockNoteEditor.create(...)

TODO (before merging)

• @YousefED : review Inline Content selection
• @YousefED : Disable Inline Content elements with content -> @matthewlipski fix backspace behavior
• Update APIs that have been changed in docs
• Document breaking changes in this PR
• @YousefED : Readd tests for markdown conversions
• @matthewlipski, review feat: HTML paste handling #422 (code + testcases), feat: custom styles and custom inline content #418 and Custom inline content and styles commands/copy & paste fixes #425 (+ address todos)
• @matthewlipski Add more tests + playground examples of custom blocks. We only now have very basic custom blocks, but for example, blocks with both "static" and editable content are missing
• Review this PR
• Good moment to discuss possible naming changes
• @matthewlipski fix hardbreaks
• @YousefED review slash menu item typings
• Fix e2e tests / CI
• @matthewlipski Add vanilla styles and non-editable custom block to playground
• Add table GIF to this PR

TODO (separately, can be done after merging)

Docs:

• Maybe it makes sense to revisit docs + examples + playground completely, but at least:
• Add custom styles and inline content to docs
• Add Table to docs
• Add serialization related information to docs
• Figure out what to do with theming now that the CSS classes are accessible

Tests:

• Add test for this Commit
• Add more tests for tables (e2e + unit)
• @YousefED : Add "typescript tests" that enforce strict typing of schemas
• Add tests for creating custom blocks / IC / Styles that can parse "external HTML"
• Add copy / paste tests with examples from copying from gdocs / notion / other websites
• Add playwright test for custom blocks / ic / styles? (and keyhandling)

Other:

• Create an API for mentions (similar to slash menu)
• lowprio: make sure "external" HTML is sanitized from unnecessary classes & attributes?
• Now we've deprecated CSS Modules, we might want to document the possibility of styling via CSS directly

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
blocknote-website	✅ Ready (Inspect)	Visit Preview	Dec 4, 2023 5:01pm

[matthewlipski]

Looks good! Reviewed changes from #422

[YousefED]

review Inline Content selection

Clicking a react mention results in a "hidden cursor" and selection stays the same. This is different from e.g.: https://embed.tiptap.dev/src/nodes/mention/react/

The reason the selection is different from the tiptap example is that we're using a NodeView for React inline content, and TipTap's implementation of stopEvent and ignoreMutation blocks the selection changes / click propagation. It's fixable, but atm I don't think it's super blocking.

Might be better to fix if at some point we move away from tiptap, or if a critical reason comes up
(note to self): I tested it by comparing a "vanilla" inline content mention with the react version. The vanilla version works ok, the react doesn't (because the node view blocks some things)