[ihordubas99]

Ticket

https://community.openproject.org/wp/COMMS-1059

Stacked on #26126 (COMMS-1058), which is stacked on #26049 (COMMS-1057). Please review those first.

What are you trying to accomplish?

Documents can contain Mermaid diagrams. A diagram is inserted from the slash menu (/diagram, /mermaid, /flowchart), its Mermaid source is edited in a popup with a live preview, and invalid source shows an error placeholder instead of breaking the editor. The stored markdown keeps the source as a ```mermaid code block. The menu texts follow the user's locale.

Screenshots

What approach did you choose and why?

Editor. The diagram block from @blocknote/diagram-block (0.54.2, matching our BlockNote version) is added to the schema in OpBlockNoteEditor, and its slash menu item joins the math items in the "Advanced" group. The diagram dictionary of the user's locale is merged into the editor dictionary next to the math one. The source popup is highlighted by the syntaxHighlighter extension from COMMS-1058, since the block declares mermaid as its language.

Markdown in hocuspocus. Hocuspocus builds the stored markdown from its own schema, and without the diagram block every diagram would be dropped from it. The package renders through Mermaid and React, which cannot run in Node, so diagramSpec.ts defines a static twin with the same type, content and code meta, as already done for math. It renders a <pre><code class="language-mermaid">, which BlockNote's markdown exporter turns into a fenced code block. The markdown test helper is now shared by the math and diagram tests.

Dark mode. The block initializes Mermaid without a theme, so in OpenProject's dark mode the edges were dark grey on a dark background and practically invisible. Every mermaid.initialize call resets Mermaid's whole configuration, so diagram-theme.ts lets the block initialize first and then initializes again with the block's own options plus the theme matching the OpenProject color mode. The block's later initialization calls are no-ops. It runs in a layout effect, before the previews render in their effects.

Dependencies. Mermaid depends on katex ^0.16, which is affected by GHSA-238p-pmpm-9mq7. It gets the same override as math-block, so the whole tree uses KaTeX 0.18.11. The lockfile only adds Mermaid and its dependencies, nothing existing changes. Mermaid stays out of the main bundle, because the editor controller is loaded lazily and every diagram type is its own chunk. Mermaid runs with its default strict security level, which strips HTML and click handlers from labels in these shared documents.

Known limitations

• The formatting toolbar's block type select has no "Diagram" entry, as for math, since the toolbar lives in op-blocknote-extensions.

Tests

• A hocuspocus unit test pins the stored markdown for a diagram.
• Frontend unit tests cover the merged locale and the Mermaid theme, including that the block's own initialization keeps the theme. The latter was verified red without the preceding initialization.
• A feature spec inserts a diagram via the slash menu, checks that Mermaid rendered an SVG and checks the stored markdown.

Merge checklist

• Added/updated tests
• Added/updated documentation in Lookbook (patterns, previews, etc)
• Tested major browsers (Chrome, Firefox, Edge, ...)

[github-actions]

Warning

Flaky specs

• rspec ./modules/bim/spec/features/viewer/create_viewpoint_spec.rb[1:2:1:1]

🤖 Ask Copilot to investigate

Copy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer.

@copilot The following spec(s) are flaky in CI (first seen on PR #26157, linked for reference only):

- `rspec ./modules/bim/spec/features/viewer/create_viewpoint_spec.rb[1:2:1:1]`

Treat this as a standalone task, unrelated to PR #26157. Create a new branch from origin/dev and open a new pull request targeting dev — do not stack it on PR #26157 or reuse that branch.

Follow the playbook in docs/development/testing/handling-flaky-tests/README.md to find the root cause and fix the underlying race — do not skip, delete, or weaken the spec to make it pass; disabling is a last resort per the playbook, and only with a bug ticket. Verify the fix by running the spec(s) repeatedly (e.g. `script/bulk_run_rspec --run-count 10`).

If you cannot reproduce the flake or are not confident in a fix after reasonable investigation, do not fabricate a change or skip the spec to force CI green. Instead, leave the pull request in draft and document what you tried, the suspected cause, and any leads in its description, then assign @ihordubas99 to take over.

Once the fix is verified, title the PR after the spec(s) it fixes, and use the PR description to explain the root cause, how the change resolves it, and the before/after results. Label the PR `flaky-spec`, assign @ihordubas99, and request a review from @ihordubas99.
On every commit, set @ihordubas99 as the sole co-author with a `Co-authored-by:` trailer (use their GitHub no-reply email so it links to their account), so it is traceable who dispatched the fix.

[github-actions]

Caution

The provided work package version does not match the core version

Details:

• Work package URL: https://community.openproject.org/wp/COMMS-1059
• Work package version: not set
• Core version: 18.0.0

Please make sure that:

• The work package version OR your pull request target branch is correct

[github-actions]

Caution

The Enterprise plan field is not set on the work package

Details:

• Work package URL: https://community.openproject.org/wp/COMMS-1059

Please make sure that:

• The work package Enterprise plan field is set

[ihordubas99]

Following the review of #26049, I added the same drift guard here. @blocknote/diagram-block is a hocuspocus devDependency now (with the katex override for Mermaid), and the diagram test checks that the static server spec matches its config and meta.