@dxos/plugin-mermaid 0.8.4-main.fd6878d → 0.9.0

package/package.json

@@ -1,57 +1,85 @@
 {
   "name": "@dxos/plugin-mermaid",
-  "version": "0.8.4-main.fd6878d",
+  "version": "0.9.0",
   "description": "Mermaid markdown plugin",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
+  "imports": {
+    "#capabilities": {
+      "source": "./src/capabilities/index.ts",
+      "types": "./dist/types/src/capabilities/index.d.ts",
+      "default": "./dist/lib/neutral/capabilities/index.mjs"
+    },
+    "#meta": {
+      "source": "./src/meta.ts",
+      "types": "./dist/types/src/meta.d.ts",
+      "default": "./dist/lib/neutral/meta.mjs"
+    },
+    "#plugin": {
+      "source": "./src/MermaidPlugin.tsx",
+      "types": "./dist/types/src/MermaidPlugin.d.ts",
+      "default": "./dist/lib/neutral/MermaidPlugin.mjs"
+    }
+  },
   "exports": {
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs"
+      "default": "./dist/lib/neutral/index.mjs"
+    },
+    "./assets/PLUGIN.mdl": "./PLUGIN.mdl",
+    "./plugin": {
+      "source": "./src/plugin.ts",
+      "types": "./dist/types/src/plugin.d.ts",
+      "default": "./dist/lib/neutral/plugin.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
-    "src"
+    "src",
+    "PLUGIN.mdl"
   ],
   "dependencies": {
-    "@codemirror/language": "^6.10.3",
-    "@codemirror/state": "^6.4.1",
-    "@codemirror/view": "^6.34.1",
-    "@preact-signals/safe-react": "^0.9.0",
-    "effect": "3.17.7",
-    "mermaid": "^10.6.1",
-    "@dxos/plugin-markdown": "0.8.4-main.fd6878d",
-    "@dxos/app-framework": "0.8.4-main.fd6878d",
-    "@dxos/plugin-space": "0.8.4-main.fd6878d",
-    "@dxos/react-ui-editor": "0.8.4-main.fd6878d"
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.43.0",
+    "mermaid": "^10.9.4",
+    "@dxos/app-framework": "0.9.0",
+    "@dxos/app-toolkit": "0.9.0",
+    "@dxos/operation": "0.9.0",
+    "@dxos/react-ui-editor": "0.9.0",
+    "@dxos/plugin-markdown": "0.9.0",
+    "@dxos/util": "0.9.0",
+    "@dxos/keys": "0.9.0",
+    "@dxos/ui-editor": "0.9.0"
   },
   "devDependencies": {
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "vite": "5.4.7",
-    "@dxos/echo-schema": "0.8.4-main.fd6878d",
-    "@dxos/storybook-utils": "0.8.4-main.fd6878d",
-    "@dxos/react-ui": "0.8.4-main.fd6878d",
-    "@dxos/react-ui-theme": "0.8.4-main.fd6878d"
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "effect": "3.21.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "vite": "^8.0.16",
+    "@dxos/echo": "0.9.0",
+    "@dxos/react-ui": "0.9.0",
+    "@dxos/storybook-utils": "0.9.0",
+    "@dxos/ui-theme": "0.9.0"
   },
   "peerDependencies": {
-    "effect": "^3.13.3",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "@dxos/react-ui": "0.8.4-main.fd6878d",
-    "@dxos/react-ui-theme": "0.8.4-main.fd6878d"
+    "effect": "3.21.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/react-ui": "0.9.0",
+    "@dxos/ui-theme": "0.9.0"
   },
   "publishConfig": {
     "access": "public"

package/src/MermaidPlugin.test.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { ProcessManagerPlugin } from '@dxos/app-framework';
+import { createTestApp } from '@dxos/app-framework/testing';
+import { MarkdownEvents } from '@dxos/plugin-markdown';
+
+import { MermaidPlugin } from '#plugin';
+
+import { meta } from './meta';
+
+const moduleId = (name: string) => `${meta.id}.module.${name}`;
+
+describe('MermaidPlugin', () => {
+  test('modules activate on the expected events', async ({ expect }) => {
+    // Use createTestApp directly — only ProcessManagerPlugin and ProcessManagerPlugin are needed.
+    // MermaidPlugin has no surface module so SetupReactSurface firing harmlessly is fine.
+    await using harness = await createTestApp({
+      plugins: [ProcessManagerPlugin(), MermaidPlugin()],
+    });
+
+    // The markdown module activates on MarkdownEvents.SetupExtensions,
+    // which is fired by MarkdownPlugin before its ReactSurface activates.
+    await harness.fire(MarkdownEvents.SetupExtensions);
+    expect(harness.manager.getActive()).toContain(moduleId('markdown'));
+  });
+});

package/src/MermaidPlugin.tsx

@@ -2,17 +2,26 @@
 // Copyright 2023 DXOS.org
 //
 
-import { contributes, defineModule, definePlugin } from '@dxos/app-framework';
-import { MarkdownCapabilities, MarkdownEvents } from '@dxos/plugin-markdown';
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+import { MarkdownEvents } from '@dxos/plugin-markdown';
 
-import { mermaid } from './extensions';
-import { meta } from './meta';
+import { MarkdownExtension } from '#capabilities';
+import { meta } from '#meta';
 
-export const MermaidPlugin = () =>
-  definePlugin(meta, [
-    defineModule({
-      id: `${meta.id}/module/markdown`,
-      activatesOn: MarkdownEvents.SetupExtensions,
-      activate: () => contributes(MarkdownCapabilities.Extensions, [mermaid]),
-    }),
-  ]);
+// eslint-disable-next-line import/no-relative-packages
+import pluginSpec from '../PLUGIN.mdl?raw';
+
+export const MermaidPlugin = Plugin.define(meta).pipe(
+  Plugin.addModule({
+    id: 'markdown',
+    activatesOn: MarkdownEvents.SetupExtensions,
+    activate: MarkdownExtension,
+  }),
+  AppPlugin.addPluginAssetModule({
+    asset: { pluginId: meta.id, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
+  }),
+  Plugin.make,
+);
+
+export default MermaidPlugin;

package/src/capabilities/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const MarkdownExtension = Capability.lazy('MarkdownExtension', () => import('./markdown-extension'));

package/src/capabilities/markdown-extension.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { MarkdownCapabilities } from '@dxos/plugin-markdown/types';
+
+import { mermaid } from '../extensions';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(Capability.contributes(MarkdownCapabilities.ExtensionProvider, [mermaid])),
+);

package/src/extensions/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './mermaid';
+export * from './mermaid-extension';

package/src/extensions/mermaid-extension.ts

@@ -0,0 +1,215 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { syntaxTree } from '@codemirror/language';
+import { type Extension } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate, WidgetType } from '@codemirror/view';
+import _mermaid from 'mermaid';
+
+export type MermaidOptions = {};
+
+/**
+ * Extension to create mermaid diagrams.
+ */
+export const mermaid = (_options: MermaidOptions = {}): Extension => {
+  return [
+    ViewPlugin.fromClass(
+      class {
+        decorations: DecorationSet;
+
+        constructor(view: EditorView) {
+          this.decorations = this.buildDecorations(view);
+        }
+
+        update(update: ViewUpdate) {
+          // Always rebuild decorations when selection changes to handle arrow key navigation.
+          if (update.docChanged || update.viewportChanged || update.selectionSet || update.focusChanged) {
+            this.decorations = this.buildDecorations(update.view);
+          }
+        }
+
+        buildDecorations(view: EditorView): DecorationSet {
+          const decorations: Array<{ from: number; to: number; decoration: Decoration }> = [];
+
+          syntaxTree(view.state).iterate({
+            enter: (node) => {
+              if (node.name === 'FencedCode') {
+                const cursor = view.state.selection.main.head;
+                // Show widget when cursor is outside the code block.
+                // Add a buffer of 1 position before and after to handle edge cases.
+                const showWidget = view.state.readOnly || cursor < node.from - 1 || cursor > node.to + 1;
+                if (showWidget) {
+                  const info = node.node.getChild('CodeInfo');
+                  if (info) {
+                    const type = view.state.sliceDoc(info.from, info.to);
+                    const text = node.node.getChild('CodeText');
+                    if (type === 'mermaid' && text) {
+                      const content = view.state.sliceDoc(text.from, text.to).trim();
+                      const label = content.split(' ')[0];
+
+                      // Create widget.
+                      const widget = new MermaidWidget(`mermaid-${node.from}`, content, label);
+
+                      // Find the line after the code block to place the widget.
+                      const endLine = view.state.doc.lineAt(node.to);
+                      const nextLinePos = endLine.to + 1;
+
+                      // Add widget after the code block.
+                      if (nextLinePos <= view.state.doc.length) {
+                        decorations.push({
+                          from: nextLinePos,
+                          to: nextLinePos,
+                          decoration: Decoration.widget({
+                            widget,
+                          }),
+                        });
+                      } else {
+                        // Check if at the end of the document.
+                        decorations.push({
+                          from: endLine.to,
+                          to: endLine.to,
+                          decoration: Decoration.widget({
+                            widget,
+                            side: 1,
+                          }),
+                        });
+                      }
+
+                      // Hide each line of the code block.
+                      const startLine = view.state.doc.lineAt(node.from);
+                      for (let lineNum = startLine.number; lineNum <= endLine.number; lineNum++) {
+                        const line = view.state.doc.line(lineNum);
+                        decorations.push({
+                          from: line.from,
+                          to: line.from,
+                          decoration: Decoration.line({
+                            class: 'cm-mermaid-hidden',
+                          }),
+                        });
+                      }
+                    }
+                  }
+                }
+              }
+            },
+          });
+
+          return Decoration.set(
+            decorations.sort((a, b) => a.from - b.from || a.to - b.to).map((d) => d.decoration.range(d.from, d.to)),
+          );
+        }
+      },
+      {
+        decorations: (v) => v.decorations,
+      },
+    ),
+    EditorView.theme({
+      '& .cm-mermaid': {
+        position: 'relative',
+        display: 'inline-flex',
+        width: '100%',
+        maring: '4px 0',
+        padding: '16px',
+        justifyContent: 'center',
+        backgroundColor: 'var(--color-group-surface)',
+        borderRadius: '8px',
+      },
+      '& .cm-mermaid-label': {
+        position: 'absolute',
+        right: '16px',
+        fontFamily: 'unset',
+        color: 'var(--color-subdued)',
+      },
+      '& .cm-mermaid-error': {
+        display: 'inline-block',
+        color: 'var(--color-error)',
+      },
+      '& .cm-mermaid-hidden': {
+        display: 'none !important',
+      },
+    }),
+  ];
+};
+
+class MermaidWidget extends WidgetType {
+  _svg: string | undefined;
+  _error: string | undefined;
+
+  // TODO(burdon): Mermaid API requires unique id.
+  constructor(
+    private readonly _id: string,
+    private readonly _source: string,
+    private readonly _label?: string,
+  ) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this._source === other._source;
+  }
+
+  override ignoreEvent(ev: Event) {
+    return !/^mouse/.test(ev.type);
+  }
+
+  override toDOM(view: EditorView) {
+    const div = document.createElement('div');
+    div.className = 'cm-mermaid';
+
+    setTimeout(async () => {
+      // https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/config.type.ts
+      _mermaid.initialize({
+        darkMode: view.state.facet(EditorView.darkTheme),
+        theme: 'neutral',
+        // TODO(burdon): Styles.
+        // NOTE: Must specify 'base' in order to override.
+        // theme: 'base',
+        // themeVariables: {
+        //   primaryColor: getToken('extend.colors.red.100'),
+        //   primaryBorderColor: getToken('extend.colors.neutral.200'),
+        // },
+        // https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagrams/flowchart/styles.ts
+        // https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagrams/sequence/styles.js
+        // https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/diagrams/state/styles.js
+        // themeCSS: '.node rect { fill: red; }',
+      });
+
+      // TODO(burdon): Cache?
+      const svg = await this.render(div);
+      if (this._error) {
+        div.className = 'cm-mermaid-error';
+        div.innerText = this._error;
+      } else {
+        div.className = 'cm-mermaid';
+        div.innerHTML = svg!;
+
+        if (this._label) {
+          const label = document.createElement('span');
+          label.innerText = this._label;
+          label.className = 'cm-mermaid-label';
+          div.appendChild(label);
+          view.requestMeasure();
+        }
+      }
+    });
+
+    return div;
+  }
+
+  async render(_container: Element): Promise<string | undefined> {
+    try {
+      // https://github.com/mermaid-js/mermaid
+      const valid = await _mermaid.parse(this._source);
+      if (valid) {
+        const result = await _mermaid.render(this._id, this._source);
+        this._error = undefined;
+        this._svg = result.svg;
+        return result.svg;
+      }
+    } catch (err: any) {
+      this._error = String(err);
+      this._svg = undefined;
+    }
+  }
+}

package/src/extensions/mermaid.stories.tsx

@@ -2,39 +2,36 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
-import { type Meta } from '@storybook/react-vite';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { useThemeContext } from '@dxos/react-ui';
+import { useTextEditor } from '@dxos/react-ui-editor';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import {
   createBasicExtensions,
   createMarkdownExtensions,
   createThemeExtensions,
   decorateMarkdown,
-  useTextEditor,
-} from '@dxos/react-ui-editor';
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+} from '@dxos/ui-editor';
 
-import { mermaid } from './mermaid';
+import { mermaid } from './mermaid-extension';
 
 const str = (...lines: string[]) => lines.join('\n');
 
-type StoryProps = {
+type DefaultStoryProps = {
   text?: string;
 };
 
-const DefaultStory = ({ text }: StoryProps) => {
+const DefaultStory = ({ text }: DefaultStoryProps) => {
   const { themeMode } = useThemeContext();
   const { parentRef, focusAttributes } = useTextEditor(
     () => ({
       initialValue: text,
       extensions: [
         createBasicExtensions(),
-        createMarkdownExtensions({ themeMode }),
+        createMarkdownExtensions(),
         createThemeExtensions({ themeMode, syntaxHighlighting: true }),
-        // TODO(burdon): Bug if mermaid extension is provided after decorateMarkdown.
         mermaid(),
         decorateMarkdown(),
       ],
@@ -45,7 +42,17 @@ const DefaultStory = ({ text }: StoryProps) => {
   return <div className='w-[50rem]' ref={parentRef} {...focusAttributes} />;
 };
 
-export const Default = {
+const meta = {
+  title: 'plugins/plugin-mermaid/extensions/mermaid',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
   args: {
     text: str(
       '# Mermaid',
@@ -68,7 +75,7 @@ export const Default = {
   },
 };
 
-export const Error = {
+export const Error: Story = {
   args: {
     text: str(
       '# Mermaid',
@@ -85,11 +92,3 @@ export const Error = {
     ),
   },
 };
-
-const meta: Meta = {
-  title: 'plugins/plugin-mermaid/extensions',
-  render: DefaultStory,
-  decorators: [withTheme, withLayout({ fullscreen: true, classNames: 'justify-center' })],
-};
-
-export default meta;

package/src/index.ts

@@ -2,5 +2,4 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './MermaidPlugin';
 export * from './meta';

package/src/meta.ts

@@ -2,14 +2,34 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
+import { trim } from '@dxos/util';
 
-export const MERMAID_PLUGIN = 'dxos.org/plugin/mermaid';
-
-export const meta: PluginMeta = {
-  id: MERMAID_PLUGIN,
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.mermaid'),
   name: 'Mermaid',
-  description: 'Tool that renders text definitions to create diagrams.',
+  author: 'DXOS',
+  description: trim`
+    Generate diagrams from simple text-based definitions using Mermaid syntax.
+    Create flowcharts, sequence diagrams, class diagrams, state diagrams, entity-relationship
+    diagrams, Gantt charts, pie charts, Git graphs, mindmaps, and timelines — all from
+    plain-text source embedded directly in your documents.
+
+    The plugin integrates with the markdown editor as a CodeMirror extension.
+    Any fenced code block tagged with the \`mermaid\` language identifier is automatically
+    detected and replaced with a live SVG preview rendered by the Mermaid JS library.
+    The raw source is revealed for editing whenever the cursor moves inside the block,
+    then the rendered diagram is restored when the cursor moves away, providing a seamless
+    live-preview experience without leaving the editor.
+
+    Diagram rendering adapts to the editor's current color scheme: dark-mode documents
+    use Mermaid's dark theme while light-mode documents use the neutral theme.
+    Parse and render errors are shown inline in place of the diagram so that
+    invalid syntax is immediately visible without disrupting the rest of the document.
+  `,
   icon: 'ph--anchor-simple--regular',
+  iconHue: 'cyan',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-mermaid',
-};
+  spec: 'PLUGIN.mdl',
+});

package/src/plugin.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const MermaidPlugin = Plugin.lazy(meta, () => import('#plugin'));

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}