Skip to content

feat(web): add mermaid-editor app for standalone .mmd diagrams - #12676

Open
dj4oC wants to merge 4 commits into
owncloud:masterfrom
dj4oC:feat/web-app-mermaid-editor
Open

feat(web): add mermaid-editor app for standalone .mmd diagrams#12676
dj4oC wants to merge 4 commits into
owncloud:masterfrom
dj4oC:feat/web-app-mermaid-editor

Conversation

@dj4oC

@dj4oC dj4oC commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Problem

md-editor-v3's Mermaid support only fires for ```mermaid fenced code blocks
inside a Markdown document being previewed — there was no way to open a
standalone .mmd/.mermaid diagram file and get a live-rendered preview
without wrapping it in Markdown first.

What this adds

A new web-app-mermaid-editor package (packages/web-app-mermaid-editor),
structurally mirroring web-app-html-editor's split-pane editor/preview shape:

  • Registers the mmd/mermaid file extensions and a "New > Mermaid diagram"
    menu entry.
  • Left pane: a plain CodeMirror editor (no dedicated Mermaid CodeMirror
    language exists, so this stays a plain-text pane — line numbers/history/
    bracket-matching only).
  • Right pane: calls mermaid.parse(..., { suppressErrors: true }) then
    mermaid.render() directly on the raw file content — no Markdown
    fence involved. Invalid syntax shows an inline error instead of crashing
    the pane, and a token counter discards stale in-flight renders so a slow
    keystroke can never clobber a newer one.
  • The rendered SVG is re-sanitized with DOMPurify using the same
    ADD_TAGS: ['foreignObject'] config the existing embedded-in-Markdown
    Mermaid renderer already uses (TextEditor.vue), since some diagram types
    embed real HTML via <foreignObject>.
  • Registered in config/config.json.dist and config.json.sample-ocis
    (the same files html-editor was added to).

Testing

  • Unit: 25 new tests across the app/toolbar/editor-pane/preview-pane/
    helpers, covering valid rendering, invalid-syntax handling, theme
    reactivity, the large-file preview pause, and a stale-render race guard.
    eslint clean, full-workspace vue-tsc --noEmit clean.
  • e2e: a new Playwright spec (specs/file-action/mermaidEditor.spec.ts)
    wires the mmdFile resource type into the existing create/edit e2e
    helpers (mirroring txtFile/mdFile) and covers diagram rendering,
    invalid-syntax error surfacing, and the view-mode toggle.
  • Accessibility: every mermaid-editor e2e interaction asserts the
    existing WCAG 2.1 baseline every other spec in this repo uses, plus an
    additional WCAG 2.2 tag scan (wcag22aa — covers things like target size
    and focus appearance) scoped to this app only. The shared a11y helper used
    by every other spec in the repo is untouched and stays on WCAG 2.1 — widening
    it repo-wide is a separate decision with its own pre-existing-violation
    triage cost, out of scope here.
  • Manual verification: confirmed live against a running ocis_full
    deployment that WEB_ASSET_CORE_PATH + WEB_UI_CONFIG_FILE correctly
    serve the new bundle and register the app in the live config.json.
    Full live Playwright e2e execution was blocked by local Docker/network
    environment flakiness unrelated to this change (see note below), not
    completed as part of this PR.

Note: found a pre-existing bug while verifying (not fixed here)

While hand-verifying via WEB_UI_CONFIG_FILE, a config missing the optional
options.editor/accountEditLink/feedbackLink/upload/embed keys (which
is exactly what a real generated config.json looks like, since they're all
omitempty) crashes services/web/pkg/config/defaults.Sanitize with a nil
pointer dereference — it dereferences those Options sub-struct pointers
without a nil-check when deciding whether to null them back out. Flagging
separately since it's out of scope for this PR; happy to file an issue if
useful.

Risk

Low. New, self-contained package; no existing app's code path is touched
except the two apps array config files and the e2e test helper additions
(both purely additive).

🤖 Generated with Claude Code

dj4oC added 2 commits July 29, 2026 11:04
md-editor-v3's mermaid support only fires inside a Markdown fenced
code block, so there was no way to edit a Mermaid diagram on its own.
This adds a dedicated split-pane editor/preview app (mirroring
web-app-html-editor's shape) for the mmd/mermaid extensions, feeding
raw diagram source straight into mermaid.render() - no Markdown
wrapping involved. Invalid syntax surfaces an inline error instead of
crashing the preview pane, and the rendered SVG is sanitized with
DOMPurify the same way the embedded markdown-mermaid renderer already
does.

🤖 Generated with Claude Code
Signed-off-by: David Walter <[email protected]>
Wires the new 'mmdFile' resource type into the create/edit e2e
resource helpers (mirroring txtFile/mdFile) and adds a spec covering
diagram rendering, invalid-syntax error surfacing, and the view-mode
toggle. The new mermaidEditor.ts page-object asserts the existing
WCAG 2.1 a11y baseline every other e2e spec uses, plus an additional
WCAG 2.2 tag scan (target-size, focus-appearance, etc.) scoped to
this file only - the shared a11y helper used by every other spec
stays on its current WCAG 2.1 tag set, since widening it repo-wide is
a separate decision with its own pre-existing-violation triage cost.

🤖 Generated with Claude Code
Signed-off-by: David Walter <[email protected]>
@dj4oC
dj4oC requested a review from a team as a code owner July 29, 2026 09:05
@update-docs

update-docs Bot commented Jul 29, 2026

Copy link
Copy Markdown

Thanks for opening this pull request! The maintainers of this repository would appreciate it if you would create a changelog item based on your changes.

@kw-security

kw-security commented Jul 29, 2026

Copy link
Copy Markdown

Snyk checks have passed. No issues have been found so far.

Status Scan Engine Critical High Medium Low Total (0)
Open Source Security 0 0 0 0 0 issues
Licenses 0 0 0 0 0 issues
Code Security 0 0 0 0 0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

CI's e2e run for the new mermaid-editor app timed out waiting for the
"New > Mermaid diagram" menu entry: config.json.dist (a reference/dev
file) had "mermaid-editor" added, but the actual runtime default config
a packaged oCIS binary serves comes from services/web's Go defaults,
which didn't. Also runs Prettier over the 3 files check:format flagged.

🤖 Generated with Claude Code
Signed-off-by: David Walter <[email protected]>

@LukasHirt LukasHirt left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

web/packages/web-app-mermaid-editor/package.jsonvue3-gettext is pinned to "2.4.0" (exact, no ^), while every other web app package (web-app-html-editor, web-app-text-editor) and the root web/package.json use "^4.0.1". This pulls a separate v2 dependency tree into the lockfile with its own deprecated transitive deps ([email protected], [email protected], etc. — both flagged deprecated in the lockfile itself). Looks like a typo rather than intentional — should be ^4.0.1.

services/web/pkg/config/defaults/defaultconfig.go:101mermaid-editor was added to DefaultConfig().Web.Config.Apps, but html-editor (the app this PR mirrors) was never added there — it's only in config.json.dist/config.json.sample-ocis. This Go list is a separate registry that seeds the default runtime config. Was touching this file intentional, or should this app follow the same pattern as html-editor and skip it?

No changelog entry — other recent feature additions (e.g. #12648) include one under changelog/unreleased/. Add one.

vue3-gettext was pinned to an exact "2.4.0" in web-app-mermaid-editor's
package.json (a copy-paste slip) instead of "^4.0.1" like every other
web app package, pulling in a stray v2 dependency tree with its own
deprecated transitives ([email protected], [email protected]). Also adds the
changelog/unreleased entry this PR was missing.

🤖 Generated with Claude Code
Signed-off-by: David Walter <[email protected]>
@dj4oC

dj4oC commented Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review, addressed in 8992703:

  • vue3-gettext: yes, a copy-paste slip — fixed to ^4.0.1 and re-ran
    pnpm install, which dropped the stray v2 tree (175 lines out of the
    lockfile, including the deprecated [email protected]/[email protected]).
  • Changelog: added changelog/unreleased/enhancement-add-mermaid-editor.md.

defaultconfig.go — intentional, here's the reasoning:

I noticed the same gap you did (html-editor isn't in this list either) while
debugging why the e2e test's "New" file menu never showed a "Mermaid diagram"
entry in CI — without this, the app is invisible in any deployment that
doesn't ship a custom WEB_UI_CONFIG_FILE/web.yaml, since this Go list is
what actually seeds a real running instance's config (config.json.dist is
only a reference/dev-server file, it isn't read by the packaged binary).

I chose to add it here rather than mirror html-editor's opt-in stance because
the two apps have a meaningfully different risk profile: html-editor renders
a live preview of arbitrary HTML (sandboxed, but still a page-rendering
surface), whereas mermaid-editor only ever turns validated Mermaid diagram
syntax into an SVG that's re-sanitized with DOMPurify before it's ever
injected — there's no arbitrary-markup or script-execution surface here.
Given that, and that the whole point of the app is to make .mmd files
usable out of the box, defaulting it on seemed like the right call rather
than requiring every deployment to opt in manually.

Happy to revert to match html-editor's pattern instead if you'd rather keep
new apps opt-in-by-default as a hard rule regardless of risk profile — let me
know which way you want it and I'll adjust.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants