feature: file exporters (docx and pdf) (#1143)

* cleaned serialization code

* comments

* update snapshot

* add comment

* address comments

* fix lint

* fix build

* fix server test

* wip

* wip

* wip

* react pdf

* misc

* move files and clean partialBlocksToBlocksForTesting

* wip

* refactor

* fix build

* update packagejson

* fix lint

* fix lint

* wip

* wip

* wip

* fix numbered list bug

* wip

* small fixes

* fix build

* fix lint

* wip

* fix build

* fix numbering, image

* fix build

* docx font

* update template

* full doc

* fix examples

* refactor

* fix build

* add option for resolveFile

* add resolveFileUrl_DEV_ONLY to examples

* fix build

* fix emoji pdf

* fix pdf numbering and checkmarks

* support colors

* fix build

* fix package lock

* fix tables

* fix word hyperlink / caption styles

* file handling docx, and start of code block

* file blocks pdf

* split packages

* wip

* fix 2 pdf bugs

* tests

* fix lint

* fix build

* fix test

* remove example pdf

* remove react email

* header / footer support

* don't write files in tests

* corsproxy + docs

* add license

* fix build

* update docs

* small fix

Author: YousefED

Diff for: .vscode/settings.json

@@ -11,5 +11,8 @@
     "packages/website/docs/.vitepress": false,
     "**/.*": false
   },
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "[xml]": {
+    "editor.defaultFormatter": "redhat.vscode-xml"
+  }
 }

Diff for: docs/components/pages/pricing/faq.tsx

@@ -17,7 +17,7 @@ const faqs = [
     question:
       "What License is BlockNote using? Can I use it for commercial projects?",
     answer: `BlockNote is open source software licensed under the MPL 2.0 license, which allows you to use BlockNote in commercial (and closed-source) applications - even without a subscription. 
-    If you make changes to the BlockNote source files, you're expected to publish these changes so the wider community can benefit as well.`,
+    If you make changes to the BlockNote source files, you're expected to publish these changes so the wider community can benefit as well. \nThe XL packages are dual-licensed and available under AGPL-3.0 or a commercial license as part of the BlockNote Business subscription or above.`,
   },
   // More questions...
 ];

Diff for: docs/pages/docs/editor-api/_meta.json

@@ -3,5 +3,7 @@
   "manipulating-inline-content": "",
   "cursor-selections": "",
   "converting-blocks": "",
-  "server-processing": ""
+  "server-processing": "",
+  "export-to-pdf": "",
+  "export-to-docx": ""
 }

Diff for: docs/pages/docs/editor-api/export-to-docx.mdx

@@ -0,0 +1,129 @@
+---
+title: Export to docx (Office Open XML)
+description: Export BlockNote documents to a docx word (Office Open XML) file.
+imageTitle: Export to docx
+path: /docs/export-to-docx
+---
+
+import { Example } from "@/components/example";
+import { Callout } from "nextra/components";
+
+# Exporting blocks to docx
+
+It's possible to export BlockNote documents to docx, completely client-side.
+
+<Callout type={"info"}>
+  This feature is provided by the `@blocknote/xl-docx-exporter`. `xl-` packages
+  are fully open source, but released under a copyleft license. A commercial
+  license for usage in closed source, proprietary products comes as part of the
+  [Business subscription](/pricing).
+</Callout>
+
+First, install the `@blocknote/xl-docx-exporter` and `docx` packages:
+
+```bash
+npm install @blocknote/xl-docx-exporter docx
+```
+
+Then, create an instance of the `DOCXExporter` class. This exposes the following methods:
+
+```typescript
+import {
+  DOCXExporter,
+  docxDefaultSchemaMappings,
+} from "@blocknote/xl-docx-exporter";
+import { Packer } from "docx";
+
+// Create the exporter
+const exporter = new DOCXExporter(editor.schema, docxDefaultSchemaMappings);
+
+// Convert the blocks to a docxjs document
+const docxDocument = await exporter.toDocxJsDocument(editor.document);
+
+// Use docx to write to file:
+await Packer.toBuffer(docxDocument);
+```
+
+See the [full example](/examples/interoperability/converting-blocks-to-docx) below:
+
+<Example name="interoperability/converting-blocks-to-docx" />
+
+### Customizing the Docx output file
+
+`toDocxJsDocument` takes an optional `options` parameter, which allows you to customize document metadata (like the author) and section options (like headers and footers).
+
+Example usage:
+
+```typescript
+import { Paragraph, TextRun } from "docx";
+
+const doc = await exporter.toDocxJsDocument(testDocument, {
+  documentOptions: {
+    creator: "John Doe",
+  },
+  sectionOptions: {
+    headers: {
+      default: {
+        options: {
+          children: [new Paragraph({ children: [new TextRun("Header")] })],
+        },
+      },
+    },
+    footers: {
+      default: {
+        options: {
+          children: [new Paragraph({ children: [new TextRun("Footer")] })],
+        },
+      },
+    },
+  },
+});
+```
+
+### Custom mappings / custom schemas
+
+The `DOCXExporter` constructor takes a `schema`, `mappings` and `options` parameter.
+A _mapping_ defines how to convert a BlockNote schema element (a Block, Inline Content, or Style) to a [docxjs](https://docx.js.org/) element.
+If you're using a [custom schema](/docs/custom-schemas) in your editor, or if you want to overwrite how default BlockNote elements are converted to docx, you can pass your own `mappings`:
+
+For example, use the following code in case your schema has an `extraBlock` type:
+
+```typescript
+import {
+  DOCXExporter,
+  docxDefaultSchemaMappings,
+} from "@blocknote/xl-docx-exporter";
+import { Paragraph, TextRun } from "docx";
+
+new DOCXExporter(schema, {
+  blockMapping: {
+    ...docxDefaultSchemaMappings.blockMapping,
+    myCustomBlock: (block, exporter) => {
+      return new Paragraph({
+        children: [
+          new TextRun({
+            text: "My custom block",
+          }),
+        ],
+      });
+    },
+  },
+  inlineContentMapping: docxDefaultSchemaMappings.inlineContentMapping,
+  styleMapping: docxDefaultSchemaMappings.styleMapping,
+});
+```
+
+### Exporter options
+
+The `DOCXExporter` constructor takes an optional `options` parameter.
+While conversion happens on the client-side, the default setup uses a server hosted proxy to resolve files:
+
+```typescript
+const defaultOptions = {
+  // a function to resolve external resources in order to avoid CORS issues
+  // by default, this calls a BlockNote hosted server-side proxy to resolve files
+  resolveFileUrl: corsProxyResolveFileUrl,
+  // the colors to use in the Docx for things like highlighting, background colors and font colors.
+  colors: COLORS_DEFAULT, // defaults from @blocknote/core
+};
+```

Diff for: docs/pages/docs/editor-api/export-to-pdf.mdx

@@ -0,0 +1,108 @@
+---
+title: Export to PDF
+description: Export BlockNote documents to a PDF.
+imageTitle: Export to PDF
+path: /docs/export-to-pdf
+---
+
+import { Example } from "@/components/example";
+import { Callout } from "nextra/components";
+
+# Exporting blocks to PDF
+
+It's possible to export BlockNote documents to PDF, completely client-side.
+
+<Callout type={"info"}>
+  This feature is provided by the `@blocknote/xl-pdf-exporter`. `xl-` packages
+  are fully open source, but released under a copyleft license. A commercial
+  license for usage in closed source, proprietary products comes as part of the
+  [Business subscription](/pricing).
+</Callout>
+
+First, install the `@blocknote/xl-pdf-exporter` and `@react-pdf/renderer` packages:
+
+```bash
+npm install @blocknote/xl-pdf-exporter @react-pdf/renderer
+```
+
+Then, create an instance of the `PDFExporter` class. This exposes the following methods:
+
+```typescript
+import {
+  PDFExporter,
+  pdfDefaultSchemaMappings,
+} from "@blocknote/xl-pdf-exporter";
+import * as ReactPDF from "@react-pdf/renderer";
+
+// Create the exporter
+const exporter = new PDFExporter(editor.schema, pdfDefaultSchemaMappings);
+
+// Convert the blocks to a react-pdf document
+const pdfDocument = await exporter.toReactPDFDocument(editor.document);
+
+// Use react-pdf to write to file:
+await ReactPDF.render(pdfDocument, `filename.pdf`);
+```
+
+See the [full example](/examples/interoperability/converting-blocks-to-pdf) with live PDF preview below:
+
+<Example name="interoperability/converting-blocks-to-pdf" />
+
+### Customizing the PDF
+
+`toReactPDFDocument` takes an optional `options` parameter, which allows you to customize the header and footer of the PDF:
+
+Example usage:
+
+```typescript
+import { Text } from "@react-pdf/renderer";
+const pdfDocument = await exporter.toReactPDFDocument(editor.document, {
+  header: <Text>Header</Text>,
+  footer: <Text>Footer</Text>,
+});
+```
+
+### Custom mappings / custom schemas
+
+The `PDFExporter` constructor takes a `schema` and `mappings` parameter.
+A _mapping_ defines how to convert a BlockNote schema element (a Block, Inline Content, or Style) to a React-PDF element.
+If you're using a [custom schema](/docs/custom-schemas) in your editor, or if you want to overwrite how default BlockNote elements are converted to PDF, you can pass your own `mappings`:
+
+For example, use the following code in case your schema has an `extraBlock` type:
+
+```typescript
+import { PDFExporter, pdfDefaultSchemaMappings } from "@blocknote/xl-pdf-exporter";
+import { Text } from "@react-pdf/renderer";
+
+new PDFExporter(schema, {
+    blockMapping: {
+        ...pdfDefaultSchemaMappings.blockMapping,
+        myCustomBlock: (block, exporter) => {
+            return <Text>My custom block</Text>;
+        },
+    },
+    inlineContentMapping: pdfDefaultSchemaMappings.inlineContentMapping,
+    styleMapping: pdfDefaultSchemaMappings.styleMapping,
+});
+```
+
+### Exporter options
+
+The `PDFExporter` constructor takes an optional `options` parameter.
+While conversion happens on the client-side, the default setup uses two server based resources:
+
+```typescript
+const defaultOptions = {
+  // emoji source, this is passed to the react-pdf library (https://react-pdf.org/fonts#registeremojisource)
+  // these are loaded from cloudflare + twemoji by default
+  emojiSource: {
+    format: "png",
+    url: "https://cdnjs.cloudflare.com/ajax/libs/twemoji/14.0.2/72x72/",
+  },
+  // a function to resolve external resources in order to avoid CORS issues
+  // by default, this calls a BlockNote hosted server-side proxy to resolve files
+  resolveFileUrl: corsProxyResolveFileUrl,
+  // the colors to use in the PDF for things like highlighting, background colors and font colors.
+  colors: COLORS_DEFAULT, // defaults from @blocknote/core
+};
+```

Diff for: docs/pages/pricing.mdx

@@ -24,8 +24,9 @@ export default function Pricing() {
       price: { month: 90, year: 24 },
       features: [
         "Access to all Pro Examples",
-        "Prioritized Bug Reports and Feature Requests on GitHub",
+        "Prioritized Bug Reports on GitHub",
         "Keep the open source library running and maintained",
+        "XL packages available for open source projects under AGPL-3.0"
       ],
       githubTierId: "291733",
     },
@@ -35,16 +36,19 @@ export default function Pricing() {
       mostPopular: true,
       description:
         "Best for companies that want a direct line to the team.",
-      price: { month: 189, year: 48 },
+      price: { month: 390, year: 48 },
       features: [
+        "Commercial license for XL packages:",
+        "XL: Multi-column layouts",
+        "XL: Export to PDF, Docx",
         "Access to all Pro Examples",
-        "Prioritized Bug Reports and Feature Requests on GitHub",
+        "Prioritized Bug Reports on GitHub",
         "Keep the open source library running and maintained",
         "Logo on our website and repositories",
         "Access to a private Discord channel with the maintainers",
         "Up to 2 hours of individual support per month",
       ],
-      githubTierId: "413994",
+      githubTierId: "440968",
     },
     {
       id: "tier-enterprise",

Diff for: examples/01-basic/05-removing-default-blocks/App.tsx

@@ -6,14 +6,13 @@ import { useCreateBlockNote } from "@blocknote/react";
 
 export default function App() {
   // Disable the Audio and Image blocks from the built-in schema
+  // This is done by picking out the blocks you want to disable
+  const { audio, image, ...remainingBlockSpecs } = defaultBlockSpecs;
+
   const schema = BlockNoteSchema.create({
     blockSpecs: {
-      //first pass all the blockspecs from the built in, default block schema
-      ...defaultBlockSpecs,
-
-      // disable blocks you don't want
-      audio: undefined as any,
-      image: undefined as any,
+      // remainingBlockSpecs contains all the other blocks
+      ...remainingBlockSpecs,
     },
   });
 

Diff for: examples/05-interoperability/01-converting-blocks-to-html/App.tsx

@@ -1,8 +1,8 @@
 import "@blocknote/core/fonts/inter.css";
-import { useCreateBlockNote } from "@blocknote/react";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
-import { useState } from "react";
+import { useCreateBlockNote } from "@blocknote/react";
+import { useEffect, useState } from "react";
 
 import "./styles.css";
 
@@ -35,6 +35,12 @@ export default function App() {
     setHTML(html);
   };
 
+  useEffect(() => {
+    // on mount, trigger initial conversion of the initial content to html
+    onChange();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   // Renders the editor instance, and its contents as HTML below.
   return (
     <div className="wrapper">

Diff for: examples/05-interoperability/03-converting-blocks-to-md/App.tsx

@@ -1,8 +1,8 @@
 import "@blocknote/core/fonts/inter.css";
-import { useCreateBlockNote } from "@blocknote/react";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
-import { useState } from "react";
+import { useCreateBlockNote } from "@blocknote/react";
+import { useEffect, useState } from "react";
 
 import "./styles.css";
 
@@ -35,6 +35,12 @@ export default function App() {
     setMarkdown(markdown);
   };
 
+  useEffect(() => {
+    // on mount, trigger initial conversion of the initial content to md
+    onChange();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   // Renders the editor instance, and its contents as Markdown below.
   return (
     <div className={"wrapper"}>

Diff for: examples/05-interoperability/05-converting-blocks-to-pdf/.bnexample.json

@@ -0,0 +1,11 @@
+{
+  "playground": true,
+  "docs": true,
+  "author": "yousefed",
+  "tags": [""],
+  "dependencies": {
+    "@blocknote/xl-pdf-exporter": "latest",
+    "@react-pdf/renderer": "^4.0.0"
+  },
+  "pro": true
+}