@jupyterlab/mermaid 4.1.0-alpha.1

package/lib/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,2DAA2D;AAE3D,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAG1C,gCAAgC;AAChC,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AACpD,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAE5D,iBAAiB;AACjB,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC;AAC/C,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC,MAAM;AACN,MAAM,CAAC,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAClD,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAC;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG,4BAA4B,CAAC;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,4BAA4B,CAAC;AAE1D;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,KAAK,CACtC,qCAAqC,EACrC,qDAAqD,CACtD,CAAC;AAqDF;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,KAAK,CACvC,sCAAsC,EACtC,oFAAoF,CACrF,CAAC"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@jupyterlab/mermaid",
+  "version": "4.1.0-alpha.1",
+  "description": "JupyterLab - Mermaid Renderer",
+  "homepage": "https://github.com/jupyterlab/jupyterlab",
+  "bugs": {
+    "url": "https://github.com/jupyterlab/jupyterlab/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jupyterlab/jupyterlab.git"
+  },
+  "license": "BSD-3-Clause",
+  "author": "Project Jupyter",
+  "sideEffects": [
+    "style/*.css",
+    "style/index.js"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "style": "style/index.css",
+  "directories": {
+    "lib": "lib/"
+  },
+  "files": [
+    "lib/*.d.ts",
+    "lib/*.js.map",
+    "lib/*.js",
+    "style/*.css",
+    "style/index.js",
+    "src/**/*.{ts,tsx}"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rimraf lib && rimraf tsconfig.tsbuildinfo",
+    "docs": "typedoc src",
+    "test": "jest",
+    "test:cov": "jest --collect-coverage",
+    "test:debug": "node --inspect-brk ../../node_modules/.bin/jest --runInBand",
+    "test:debug:watch": "node --inspect-brk ../../node_modules/.bin/jest --runInBand --watch",
+    "watch": "tsc -b --watch"
+  },
+  "dependencies": {
+    "@jupyterlab/apputils": "^4.2.0-alpha.1",
+    "@jupyterlab/coreutils": "^6.1.0-alpha.1",
+    "@jupyterlab/rendermime-interfaces": "^3.8.3-alpha.0",
+    "@lumino/coreutils": "^2.1.2",
+    "@lumino/widgets": "^2.3.0",
+    "mermaid": "^10.3.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.2.0",
+    "jest": "^29.2.0",
+    "rimraf": "~3.0.0",
+    "typedoc": "~0.24.7",
+    "typescript": "~5.0.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "styleModule": "style/index.js"
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+/**
+ * @packageDocumentation
+ * @module mermaid
+ */
+
+export * from './manager';
+export * from './markdown';
+export * from './mime';
+export * from './tokens';

package/src/manager.ts

@@ -0,0 +1,325 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import type MermaidType from 'mermaid';
+
+import { PromiseDelegate } from '@lumino/coreutils';
+
+import { LruCache } from '@jupyterlab/coreutils';
+
+import { IThemeManager } from '@jupyterlab/apputils';
+
+import {
+  DETAILS_CLASS,
+  IMermaidManager,
+  MERMAID_CLASS,
+  MERMAID_CODE_CLASS,
+  MERMAID_DARK_THEME,
+  MERMAID_DEFAULT_THEME,
+  SUMMARY_CLASS,
+  WARNING_CLASS
+} from './tokens';
+
+/**
+ * A mermaid diagram manager with cache.
+ */
+export class MermaidManager implements IMermaidManager {
+  protected _diagrams: LruCache<string, HTMLElement>;
+  protected _themes: IThemeManager | null;
+
+  constructor(options: MermaidManager.IOptions = {}) {
+    this._diagrams = new LruCache({ maxSize: options.maxCacheSize || null });
+
+    // handle reacting to themes
+    if (options.themes) {
+      Private.initThemes(options.themes || null);
+      options.themes.themeChanged.connect(this.initialize, this);
+    }
+  }
+
+  /**
+   * Handle (re)-initializing mermaid based on external values.
+   */
+  initialize() {
+    this._diagrams.clear();
+    Private.initMermaid();
+  }
+
+  /**
+   * Get the underlying, potentially un-initialized mermaid module.
+   */
+  async getMermaid(): Promise<typeof MermaidType> {
+    return await Private.ensureMermaid();
+  }
+
+  /**
+   * Get the version of the currently-loaded mermaid module
+   */
+  getMermaidVersion(): string | null {
+    return Private.version();
+  }
+
+  /**
+   * Get a pre-cached mermaid figure.
+   *
+   * This primarily exists for the needs of `marked`, which supports async node
+   * visitors, but not async rendering.
+   */
+  getCachedFigure(text: string): HTMLElement | null {
+    return this._diagrams.get(text);
+  }
+
+  /**
+   * Attempt a raw rendering of mermaid to an SVG string, extracting some metadata.
+   */
+  async renderSvg(text: string): Promise<IMermaidManager.IRenderInfo> {
+    const _mermaid = await this.getMermaid();
+
+    const id = `jp-mermaid-${Private.nextMermaidId()}`;
+
+    // create temporary element into which to render
+    const el = document.createElement('div');
+    document.body.appendChild(el);
+    try {
+      const { svg } = await _mermaid.render(id, text, el);
+      const parser = new DOMParser();
+      const doc = parser.parseFromString(svg, 'image/svg+xml');
+
+      const info: IMermaidManager.IRenderInfo = { text, svg };
+      const svgEl = doc.querySelector('svg');
+      const { maxWidth } = svgEl?.style || {};
+      info.width = maxWidth ? parseFloat(maxWidth) : null;
+      const firstTitle = doc.querySelector('title');
+      const firstDesc = doc.querySelector('desc');
+      if (firstTitle) {
+        info.accessibleTitle = firstTitle.textContent;
+      }
+      if (firstDesc) {
+        info.accessibleDescription = firstDesc.textContent;
+      }
+      return info;
+    } finally {
+      el.remove();
+    }
+  }
+
+  /**
+   * Provide and cache a fully-rendered element, checking the cache first.
+   */
+  async renderFigure(text: string): Promise<HTMLElement> {
+    // bail if already cached
+    let output: HTMLElement | null = this._diagrams.get(text);
+
+    if (output != null) {
+      return output;
+    }
+
+    let className = MERMAID_CLASS;
+
+    let result: HTMLElement | null = null;
+
+    // the element that will be returned
+    output = document.createElement('div');
+    output.className = className;
+
+    try {
+      const response = await this.renderSvg(text);
+      result = this.makeMermaidFigure(response);
+    } catch (err) {
+      output.classList.add(WARNING_CLASS);
+      result = await this.makeMermaidError(text);
+    }
+
+    let version = this.getMermaidVersion();
+
+    if (version) {
+      result.dataset.jpMermaidVersion = version;
+    }
+
+    output.appendChild(result);
+
+    // update the cache for use when rendering synchronously
+    this._diagrams.set(text, output);
+
+    return output;
+  }
+
+  /**
+   * Provide a code block with the mermaid source.
+   */
+  makeMermaidCode(text: string): HTMLElement {
+    // append the source
+    const pre = document.createElement('pre');
+    const code = document.createElement('code');
+    code.innerText = text;
+    pre.appendChild(code);
+    code.className = MERMAID_CODE_CLASS;
+    code.textContent = text;
+    return pre;
+  }
+
+  /**
+   * Get the parser message element from a failed parse.
+   *
+   * This doesn't do much of anything if the text is successfully parsed.
+   */
+  async makeMermaidError(text: string): Promise<HTMLElement> {
+    const _mermaid = await this.getMermaid();
+    let errorMessage = '';
+    try {
+      await _mermaid.parse(text);
+    } catch (err) {
+      errorMessage = `${err}`;
+    }
+
+    const result = document.createElement('details');
+    result.className = DETAILS_CLASS;
+    const summary = document.createElement('summary');
+    summary.className = SUMMARY_CLASS;
+    summary.appendChild(this.makeMermaidCode(text));
+    result.appendChild(summary);
+
+    const warning = document.createElement('pre');
+    warning.innerText = errorMessage;
+    result.appendChild(warning);
+    return result;
+  }
+
+  /**
+   * Extract extra attributes to add to a generated figure.
+   */
+  makeMermaidFigure(info: IMermaidManager.IRenderInfo): HTMLElement {
+    const figure = document.createElement('figure');
+    const img = document.createElement('img');
+
+    figure.appendChild(img);
+    img.setAttribute(
+      'src',
+      `data:image/svg+xml,${encodeURIComponent(info.svg)}`
+    );
+
+    // add dimension information
+    if (info.width) {
+      img.width = info.width;
+    }
+
+    // add accessible alt title
+    if (info.accessibleTitle) {
+      img.setAttribute('alt', info.accessibleTitle);
+    }
+
+    figure.appendChild(this.makeMermaidCode(info.text));
+
+    // add accessible caption, with fallback to raw mermaid source
+    if (info.accessibleDescription) {
+      const caption = document.createElement('figcaption');
+      caption.className = 'sr-only';
+      caption.textContent = info.accessibleDescription;
+      figure.appendChild(caption);
+    }
+
+    return figure;
+  }
+}
+
+/**
+ * A namespace for implementation-specific details of this mermaid manager.
+ */
+export namespace MermaidManager {
+  /**
+   * Initialization options for the mermaid manager.
+   */
+  export interface IOptions {
+    maxCacheSize?: number | null;
+    themes?: IThemeManager | null;
+  }
+}
+
+/**
+ * A namespace for global, private mermaid data.
+ */
+namespace Private {
+  let _themes: IThemeManager | null = null;
+  let _mermaid: typeof MermaidType | null = null;
+  let _loading: PromiseDelegate<typeof MermaidType> | null = null;
+  let _nextMermaidId = 0;
+  let _version: string | null = null;
+
+  /**
+   * Cache a reference to the theme manager.
+   */
+  export function initThemes(themes: IThemeManager | null) {
+    _themes = themes;
+  }
+
+  /**
+   * Get the version of mermaid used for rendering.
+   */
+  export function version(): string | null {
+    return _version;
+  }
+
+  /**
+   * (Re-)initialize mermaid with lab-specific theme information
+   */
+  export function initMermaid(): boolean {
+    if (!_mermaid) {
+      return false;
+    }
+
+    let theme = MERMAID_DEFAULT_THEME;
+
+    if (_themes) {
+      const jpTheme = _themes.theme;
+      theme =
+        jpTheme && _themes.isLight(jpTheme)
+          ? MERMAID_DEFAULT_THEME
+          : MERMAID_DARK_THEME;
+    }
+
+    const fontFamily = window
+      .getComputedStyle(document.body)
+      .getPropertyValue('--jp-ui-font-family');
+
+    _mermaid.mermaidAPI.globalReset();
+    _mermaid.mermaidAPI.initialize({
+      theme,
+      fontFamily,
+      maxTextSize: 100000,
+      startOnLoad: false
+    });
+    return true;
+  }
+
+  /**
+   * Determine whether mermaid has been loaded yet.
+   */
+  export function getMermaid(): typeof MermaidType | null {
+    return _mermaid;
+  }
+
+  /**
+   * Provide a globally-unique, but unstable, ID for disambiguation.
+   */
+  export function nextMermaidId() {
+    return _nextMermaidId++;
+  }
+
+  /**
+   * Ensure mermaid has been lazily loaded once, initialized, and cached.
+   */
+  export async function ensureMermaid(): Promise<typeof MermaidType> {
+    if (_mermaid != null) {
+      return _mermaid;
+    }
+    if (_loading) {
+      return _loading.promise;
+    }
+    _loading = new PromiseDelegate();
+    _version = (await import('mermaid/package.json')).version;
+    _mermaid = (await import('mermaid')).default;
+    initMermaid();
+    _loading.resolve(_mermaid);
+    return _mermaid;
+  }
+}

package/src/markdown.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { IMermaidManager, IMermaidMarkdown } from './tokens';
+
+/**
+ * An implementation of mermaid fenced code blocks in markdown.
+ */
+export class MermaidMarkdown implements IMermaidMarkdown {
+  protected _mermaid: IMermaidManager;
+  readonly languages = ['mermaid'];
+  readonly rank = 100;
+
+  constructor(options: MermaidMarkdown.IOptions) {
+    this._mermaid = options.mermaid;
+  }
+
+  /**
+   * Pre-parse and cache the rendered text.
+   */
+  async walk(text: string): Promise<void> {
+    await this._mermaid.renderFigure(text);
+  }
+
+  /**
+   * Render the diagram.
+   */
+  render(text: string): string | null {
+    // handle pre-cached mermaid figures
+    let cachedFigure: HTMLElement | null = this._mermaid.getCachedFigure(text);
+    if (cachedFigure) {
+      return cachedFigure.outerHTML;
+    }
+    return null;
+  }
+}
+
+/**
+ * A namespace for mermaid markdown
+ */
+export namespace MermaidMarkdown {
+  /**
+   * Initialization options for mermaid markdown
+   */
+  export interface IOptions {
+    mermaid: IMermaidManager;
+  }
+}

package/src/mime.ts

@@ -0,0 +1,118 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+/**
+ * @packageDocumentation
+ * @module mermaid-extension
+ */
+
+import {
+  IMermaidManager,
+  MERMAID_CLASS,
+  MERMAID_MIME_TYPE,
+  WARNING_CLASS
+} from './tokens';
+import { IRenderMime } from '@jupyterlab/rendermime-interfaces';
+import { PromiseDelegate } from '@lumino/coreutils';
+import { Widget } from '@lumino/widgets';
+
+const SVG_MIME = 'image/svg+xml';
+
+/**
+ * A widget for rendering mermaid text-based diagrams, for usage with rendermime.
+ */
+export class RenderedMermaid extends Widget implements IRenderMime.IRenderer {
+  protected static _manager: IMermaidManager | null = null;
+  protected static _managerReady = new PromiseDelegate<IMermaidManager>();
+  protected _lastRendered: string | null = null;
+
+  /**
+   * Create a new widget for rendering Vega/Vega-Lite.
+   */
+  constructor(options: IRenderMime.IRendererOptions) {
+    super();
+    this._mimeType = options.mimeType;
+    this.addClass(MERMAID_CLASS);
+  }
+
+  static set manager(manager: IMermaidManager) {
+    if (RenderedMermaid._manager) {
+      console.warn('Mermaid manager may only be set once, and is already set.');
+      return;
+    }
+    RenderedMermaid._manager = manager;
+    RenderedMermaid._managerReady.resolve(manager);
+  }
+
+  /**
+   * Render mermaid text-based diagrams into this widget's node.
+   */
+  async renderModel(model: IRenderMime.IMimeModel): Promise<void> {
+    const manager = await RenderedMermaid._managerReady.promise;
+
+    const text = model.data[this._mimeType] as string | undefined;
+    if (text == null || text === this._lastRendered) {
+      return;
+    }
+
+    this._lastRendered = text;
+
+    // get a div containing a figure or parser message
+    const figure = await manager.renderFigure(text);
+
+    if (figure.classList.contains(WARNING_CLASS)) {
+      this.node.classList.add(WARNING_CLASS);
+    } else {
+      this.node.classList.remove(WARNING_CLASS);
+    }
+
+    if (!figure.firstChild) {
+      return;
+    }
+
+    if (this.node.innerHTML !== figure.innerHTML) {
+      this.node.innerHTML = figure.innerHTML;
+    }
+
+    // capture the version of mermaid used
+    const version = manager.getMermaidVersion();
+    const mermaidMetadata = {
+      ...((model.metadata[MERMAID_MIME_TYPE] as Record<string, any>) || {}),
+      version
+    };
+    const metadata = {
+      ...model.metadata,
+      [MERMAID_MIME_TYPE]: mermaidMetadata
+    };
+
+    // if available, set the fully-rendered SVG
+    const img = figure.querySelector('img');
+
+    if (img) {
+      const svg = decodeURIComponent(img.src.split(',')[1]);
+      const oldSvg = model.data[SVG_MIME];
+      if (svg !== oldSvg) {
+        model.setData({
+          data: { ...model.data, [SVG_MIME]: svg },
+          metadata
+        });
+      }
+    } else {
+      const dataWithoutSvg = { ...model.data };
+      delete dataWithoutSvg[SVG_MIME];
+      model.setData({ data: dataWithoutSvg, metadata });
+    }
+  }
+
+  private _mimeType: string;
+}
+
+/**
+ * A mime renderer factory for mermaid text-based diagrams.
+ */
+export const rendererFactory: IRenderMime.IRendererFactory = {
+  safe: true,
+  mimeTypes: [MERMAID_MIME_TYPE],
+  createRenderer: options => new RenderedMermaid(options)
+};

package/src/tokens.ts

@@ -0,0 +1,112 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { Token } from '@lumino/coreutils';
+import type MermaidType from 'mermaid';
+
+// documented upstream constants
+export const MERMAID_MIME_TYPE = 'text/vnd.mermaid';
+export const MERMAID_FILE_EXTENSIONS = ['.mmd', '.mermaid'];
+
+// mermaid themes
+export const MERMAID_DEFAULT_THEME = 'default';
+export const MERMAID_DARK_THEME = 'dark';
+
+// DOM
+export const MERMAID_CLASS = 'jp-RenderedMermaid';
+export const MERMAID_CODE_CLASS = 'mermaid';
+export const WARNING_CLASS = 'jp-mod-warning';
+export const DETAILS_CLASS = 'jp-RenderedMermaid-Details';
+export const SUMMARY_CLASS = 'jp-RenderedMermaid-Summary';
+
+/**
+ * The exported token for a mermaid manager
+ */
+export const IMermaidManager = new Token<IMermaidManager>(
+  '@jupyterlab/mermaid:IMermaidManager',
+  `a manager for rendering mermaid text-based diagrams`
+);
+
+/**
+ * A namespace for public mermaid interfaces.
+ */
+export interface IMermaidManager {
+  /**
+   * Get the (potentially uninitialized) mermaid module.
+   */
+  getMermaid(): Promise<typeof MermaidType>;
+
+  /**
+   * Get the version of the currently-loaded mermaid module
+   */
+  getMermaidVersion(): string | null;
+
+  /**
+   * Render mermaid source to an SVG string with extraced metadata.
+   */
+  renderSvg(text: string): Promise<IMermaidManager.IRenderInfo>;
+
+  /**
+   * Render and cache mermaid source as a figure of an image, or a unsuccessful parser message.
+   */
+  renderFigure(text: string): Promise<HTMLElement>;
+
+  /**
+   * Get the pre-cached element for a mermaid string, if available.
+   */
+  getCachedFigure(text: string): HTMLElement | null;
+}
+
+/**
+ * A namespace for the mermaid manager.
+ */
+export namespace IMermaidManager {
+  /**
+   * The results of a successful rendering of a mermaid text-based diagram.
+   */
+  export interface IRenderInfo {
+    /** the original source of the diagram. */
+    text: string;
+    /** The raw rendered SVG. */
+    svg: string;
+    /** The extracted accessible description, if found. */
+    accessibleDescription?: string | null;
+    /** The extracted accessible title, if found. */
+    accessibleTitle?: string | null;
+    /** The extracted width of the digaram, if found. */
+    width?: number | null;
+  }
+}
+
+/**
+ * The exported token for a mermaid manager
+ */
+export const IMermaidMarkdown = new Token<IMermaidMarkdown>(
+  '@jupyterlab/mermaid:IMermaidMarkdown',
+  `a manager for rendering mermaid text-based diagrams in markdown fenced code blocks`
+);
+
+/**
+ * A handler for mermaid fenced code blocks in markdown
+ *
+ * This duplicates the (currently) private `IFencedBlockRenderer` in
+ * `@jupyterlab/markedparser-extension`.
+ */
+export interface IMermaidMarkdown {
+  /**
+   * The languages this block accepts.
+   */
+  languages: string[];
+  /**
+   * The order in which the block would be processed
+   */
+  rank: number;
+  /**
+   * Handle up-front loading/parsing mermaid
+   */
+  walk: (text: string) => Promise<void>;
+  /**
+   * Provide pre-rendered diagram content
+   */
+  render: (text: string) => string | null;
+}