[COMMS-1057] Enable math formula support in BlockNote on documents

extensions/op-blocknote-hocuspocus/package.json

@@ -32,6 +32,7 @@
   },
   "devDependencies": {
     "@blocknote/core": "^0.55.0",
+    "@blocknote/math-block": "^0.55.0",
     "@eslint/js": "^10.0.1",
     "@eslint/json": "^2.1.1",
     "@hocuspocus/provider": "^4.7.0",
@@ -46,6 +47,11 @@
     "typescript-eslint": "^8.71.2",
     "vitest": "^5.0.5"
   },
+  "overrides": {
+    "@blocknote/math-block": {
+      "katex": "^0.18.11"
+    }
+  },
   "allowScripts": {
     "esbuild@0.28.1": true,
     "fsevents@2.3.3": true,

extensions/op-blocknote-hocuspocus/src/extensions/openProjectApi.ts

@@ -35,16 +35,19 @@ import {
 } from "@openproject/op-blocknote-extensions/server";
 import * as Y from "yjs";
 import { TokenExpired, TokenExpiryMissing, unauthorized } from "../closeEvents";
+import { mathBlockStaticSpec, mathInlineStaticSpec } from "../mathSpecs";
 import { decryptAndValidateToken } from "../services/tokenValidationService";
 import type { ApiResponseDocument } from "../types";
 import { fetchResource } from "../services/resourceService";
 
 export const editorSchema = BlockNoteSchema.create().extend({
   blockSpecs: {
     openProjectWorkPackageBlock: openProjectWorkPackageStaticBlockSpec(),
+    mathBlock: mathBlockStaticSpec(),
   },
   inlineContentSpecs: {
     openProjectWorkPackageInline: openProjectWorkPackageStaticInlineSpec,
+    math: mathInlineStaticSpec,
   },
 });
 

extensions/op-blocknote-hocuspocus/src/mathSpecs.ts

@@ -0,0 +1,63 @@
+//-- copyright
+// OpenProject is an open source project management software.
+// Copyright (C) the OpenProject GmbH
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License version 3.
+//
+// OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+// Copyright (C) 2006-2013 Jean-Philippe Lang
+// Copyright (C) 2010-2013 the ChiliProject Team
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License
+// as published by the Free Software Foundation; either version 2
+// of the License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+//
+// See COPYRIGHT and LICENSE files for more details.
+//++
+
+import { createBlockSpec, createInlineContentSpec, plainContentToString } from "@blocknote/core";
+
+// `@blocknote/math-block` cannot be loaded in Node (it imports KaTeX's CSS), and with React's development
+// build its rendering crashes the process after an export, so these mirror its specs. The math tests
+// guard that they stay in sync with the package. The markdown exporter reads the LaTeX from the
+// `application/x-tex` annotation.
+function mathElement(latex:string, display:"block" | "inline") {
+  const namespace = "http://www.w3.org/1998/Math/MathML";
+  const math = document.createElementNS(namespace, "math");
+  const semantics = document.createElementNS(namespace, "semantics");
+  const annotation = document.createElementNS(namespace, "annotation");
+
+  math.setAttribute("display", display);
+  annotation.setAttribute("encoding", "application/x-tex");
+  annotation.textContent = latex;
+  semantics.append(annotation);
+  math.append(semantics);
+
+  return math as unknown as HTMLElement;
+}
+
+export const mathBlockStaticSpec = createBlockSpec(
+  { type: "mathBlock", propSchema: {}, content: "plain" },
+  {
+    meta: { code: true, defining: true, isolating: false },
+    render: (block) => ({ dom: mathElement(plainContentToString(block.content), "block") }),
+  },
+);
+
+export const mathInlineStaticSpec = createInlineContentSpec(
+  { type: "math", propSchema: {}, content: "plain" },
+  {
+    meta: { code: true },
+    render: (inlineContent) => ({ dom: mathElement(plainContentToString(inlineContent.content), "inline") }),
+  },
+);

extensions/op-blocknote-hocuspocus/test/extensions/math.test.ts

@@ -0,0 +1,79 @@
+//-- copyright
+// OpenProject is an open source project management software.
+// Copyright (C) the OpenProject GmbH
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License version 3.
+//
+// OpenProject is a fork of ChiliProject, which is a fork of Redmine. The copyright follows:
+// Copyright (C) 2006-2013 Jean-Philippe Lang
+// Copyright (C) 2010-2013 the ChiliProject Team
+//
+// This program is free software; you can redistribute it and/or
+// modify it under the terms of the GNU General Public License
+// as published by the Free Software Foundation; either version 2
+// of the License, or (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+//
+// See COPYRIGHT and LICENSE files for more details.
+//++
+
+import {
+  createMathBlockConfig,
+  createReactInlineMathSpec,
+  createReactMathBlockSpec,
+  mathInlineContentConfig,
+} from "@blocknote/math-block";
+import { describe, expect, test } from "vitest";
+import * as Y from "yjs";
+import { createEditor } from "../../src/extensions/openProjectApi";
+import { mathBlockStaticSpec, mathInlineStaticSpec } from "../../src/mathSpecs";
+
+async function storedMarkdown(blocks:unknown[]) {
+  const editor = createEditor();
+  const fragment = new Y.Doc().getXmlFragment("document-store");
+  // @ts-expect-error BlockNote types are complicated
+  editor.blocksToYXmlFragment(blocks, fragment);
+  return editor.blocksToMarkdownLossy(editor.yXmlFragmentToBlocks(fragment));
+}
+
+describe("math", () => {
+  test("stores a math block as a $$ block", async () => {
+    const markdown = await storedMarkdown([
+      { type: "mathBlock", content: "a^2 = \\sqrt{b^2 + c^2}" },
+    ]);
+
+    expect(markdown).toBe("$$\na^2 = \\sqrt{b^2 + c^2}\n$$\n");
+  });
+
+  test("stores inline math as a $ span", async () => {
+    const markdown = await storedMarkdown([
+      { type: "paragraph", content: ["Euler: ", { type: "math", content: "e^{i\\pi} + 1 = 0" }, "."] },
+    ]);
+
+    expect(markdown).toBe("Euler: $e^{i\\pi} + 1 = 0$.\n");
+  });
+});
+
+describe("math specs", () => {
+  test("match the math block of @blocknote/math-block", () => {
+    const { code, defining, isolating } = createReactMathBlockSpec().implementation.meta ?? {};
+
+    expect(mathBlockStaticSpec().config).toEqual(createMathBlockConfig());
+    expect(mathBlockStaticSpec().implementation.meta).toEqual({ code, defining, isolating });
+  });
+
+  test("match the inline math of @blocknote/math-block", () => {
+    const { code } = createReactInlineMathSpec().implementation.meta ?? {};
+
+    expect(mathInlineStaticSpec.config).toEqual(mathInlineContentConfig);
+    expect(mathInlineStaticSpec.implementation.meta).toEqual({ code });
+  });
+});

extensions/op-blocknote-hocuspocus/vitest.config.mjs

@@ -31,5 +31,7 @@ export default defineConfig({
   test: {
     include: ["test/**/*.test.ts"],
     setupFiles: ["test/setup.ts"],
+    // Lets Vite handle the KaTeX stylesheet `@blocknote/math-block` imports, which Node cannot load.
+    server: { deps: { inline: ["@blocknote/math-block"] } },
   },
 });

frontend/angular.json

@@ -54,6 +54,7 @@
               "src/styles.scss",
               "node_modules/codemirror/lib/codemirror.css",
               "node_modules/flatpickr/dist/flatpickr.min.css",
+              "node_modules/katex/dist/katex.min.css",
               "src/vendor/ckeditor/ckeditor.css"
             ],
             "stylePreprocessorOptions": {

frontend/esbuild/plugins.ts

@@ -105,4 +105,20 @@ if (hadPreviousDollar) {
   },
 };
 
-export default [customConfigPlugin, jqueryInjectionPlugin];
+// The production build cannot bundle KaTeX's fonts; angular.json loads the stylesheet instead.
+const katexStylesheetFromJsPlugin:Plugin = {
+  name: 'katex-stylesheet-from-js',
+  setup(build) {
+    build.onResolve({ filter: /^katex\/dist\/katex\.min\.css$/ }, (args) => {
+      if (args.kind !== 'import-statement') {
+        return undefined;
+      }
+
+      return { path: args.path, namespace: 'katex-stylesheet-from-js' };
+    });
+
+    build.onLoad({ filter: /.*/, namespace: 'katex-stylesheet-from-js' }, () => ({ contents: '', loader: 'empty' }));
+  },
+};
+
+export default [customConfigPlugin, jqueryInjectionPlugin, katexStylesheetFromJsPlugin];