@azerion/bunosaurus-theme-mermaid 0.0.0-stage → 4.0.0

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# `@docusaurus/theme-mermaid`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The mermaid components for Docusaurus.
+
+## Installation
+
+Add `docusaurus/theme-mermaid` to your package:
+
+```bash
+npm i @docusaurus/theme-mermaid
+# or
+yarn add @docusaurus/theme-mermaid
+```
+
+## Swizzling components
+
+```bash
+$ npm swizzle @docusaurus/theme-mermaid [component name]
+```
+
+All components used by this theme can be found [here](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-mermaid/src/theme)

package/lib/client/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { RenderResult, MermaidConfig } from 'mermaid';
+import type { ThemeConfig } from '@docusaurus/theme-mermaid';
+export declare const MermaidContainerClassName = "docusaurus-mermaid-container";
+export declare function useMermaidThemeConfig(): ThemeConfig['mermaid'];
+export declare function useMermaidConfig(): MermaidConfig;
+export declare function useMermaidRenderResult({ text, config: providedConfig, }: {
+    text: string;
+    config?: MermaidConfig;
+}): RenderResult | null;

package/lib/client/index.js

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useState, useEffect, useMemo, useId, useRef } from 'react';
+import { useColorMode, useThemeConfig } from '@docusaurus/theme-common';
+import { loadMermaid } from './loadMermaid';
+// Stable className to allow users to easily target with CSS
+export const MermaidContainerClassName = 'docusaurus-mermaid-container';
+export function useMermaidThemeConfig() {
+    return useThemeConfig().mermaid;
+}
+export function useMermaidConfig() {
+    const { colorMode } = useColorMode();
+    const mermaidThemeConfig = useMermaidThemeConfig();
+    const theme = mermaidThemeConfig.theme[colorMode];
+    const { options } = mermaidThemeConfig;
+    return useMemo(() => ({ startOnLoad: false, ...options, theme }), [theme, options]);
+}
+async function renderMermaid({ id, text, config, }) {
+    const mermaid = await loadMermaid();
+    /*
+    Mermaid API is really weird :s
+    It is a big mutable singleton with multiple config levels
+    Note: most recent API type definitions are missing
+  
+    There are 2 kind of configs:
+  
+    - siteConfig: some kind of global/protected shared config
+      you can only set with "initialize"
+  
+    - config/currentConfig
+      the config the renderer will use
+      it is reset to siteConfig before each render
+      but it can be altered by the mermaid txt content itself through directives
+  
+    To use a new mermaid config (on colorMode change for example) we should
+    update siteConfig, and it can only be done with initialize()
+     */
+    mermaid.initialize(config);
+    try {
+        return await mermaid.render(id, text);
+    }
+    catch (e) {
+        // Because Mermaid add a weird SVG/Message to the DOM on error
+        // https://github.com/mermaid-js/mermaid/issues/3205#issuecomment-1719620183
+        document.querySelector(`#d${id}`)?.remove();
+        throw e;
+    }
+}
+export function useMermaidRenderResult({ text, config: providedConfig, }) {
+    const [result, setResult] = useState(null);
+    const id = useId();
+    const renderCount = useRef(0);
+    /*
+    For flexibility, we allow the hook to receive a custom Mermaid config
+    The user could inject a modified version of the default config for example
+     */
+    const defaultMermaidConfig = useMermaidConfig();
+    const config = providedConfig ?? defaultMermaidConfig;
+    useEffect(() => {
+        // Mermaid removes existing DOM elements with the requested ID. Reusing an
+        // ID can delete the displayed SVG, which React won't restore if the new
+        // SVG markup is identical. Give every render its own ID instead.
+        renderMermaid({ id: `${id}-${renderCount.current++}`, text, config })
+            // TODO maybe try to use Suspense here and throw the promise?
+            // See also https://github.com/pmndrs/suspend-react
+            .then(setResult)
+            .catch((e) => {
+            // Funky way to trigger parent React error boundary
+            // See https://x.com/sebastienlorber/status/1628340871899893768
+            setResult(() => {
+                throw e;
+            });
+        });
+    }, [id, text, config]);
+    return result;
+}

package/lib/client/loadMermaid.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { Mermaid } from 'mermaid';
+export declare function loadMermaid(): Promise<Mermaid>;

package/lib/client/loadMermaid.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+// We load Mermaid with a dynamic import to code split / lazy load the library
+// It is only called inside a useEffect, so loading can be deferred
+export async function loadMermaid() {
+    return (await import('mermaid')).default;
+}

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { Plugin } from '@docusaurus/types';
+export default function themeMermaid(): Plugin<void>;
+export { validateThemeConfig } from './validateThemeConfig';

package/lib/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateThemeConfig = void 0;
+exports.default = themeMermaid;
+function themeMermaid() {
+    return {
+        name: 'docusaurus-theme-mermaid',
+        getThemePath() {
+            return '../lib/theme';
+        },
+        getTypeScriptThemePath() {
+            return '../src/theme';
+        },
+    };
+}
+var validateThemeConfig_1 = require("./validateThemeConfig");
+Object.defineProperty(exports, "validateThemeConfig", { enumerable: true, get: function () { return validateThemeConfig_1.validateThemeConfig; } });

package/lib/theme/Mermaid/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { type ReactNode } from 'react';
+import type { Props } from '@theme/Mermaid';
+export default function Mermaid(props: Props): ReactNode;

package/lib/theme/Mermaid/index.js

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import {useEffect, useRef} from 'react';
+import ErrorBoundary from '@docusaurus/ErrorBoundary';
+import {ErrorBoundaryErrorMessageFallback} from '@docusaurus/theme-common';
+import {
+  MermaidContainerClassName,
+  useMermaidRenderResult,
+} from '@docusaurus/theme-mermaid/client';
+import styles from './styles.module.css';
+function MermaidRenderResult({renderResult}) {
+  const ref = useRef(null);
+  useEffect(() => {
+    const div = ref.current;
+    renderResult.bindFunctions?.(div);
+  }, [renderResult]);
+  return (
+    <div
+      ref={ref}
+      className={`${MermaidContainerClassName} ${styles.container}`}
+      dangerouslySetInnerHTML={{__html: renderResult.svg}}
+    />
+  );
+}
+function MermaidRenderer({value}) {
+  const renderResult = useMermaidRenderResult({text: value});
+  if (renderResult === null) {
+    return null;
+  }
+  return <MermaidRenderResult renderResult={renderResult} />;
+}
+export default function Mermaid(props) {
+  return (
+    <ErrorBoundary
+      fallback={(params) => <ErrorBoundaryErrorMessageFallback {...params} />}>
+      <MermaidRenderer {...props} />
+    </ErrorBoundary>
+  );
+}

package/lib/theme/Mermaid/styles.module.css

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.container {
+  max-width: 100%;
+}
+
+.container > svg {
+  max-width: 100%;
+}

package/lib/validateThemeConfig.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { Joi } from '@docusaurus/utils-validation';
+import type { ThemeConfig } from '@docusaurus/theme-mermaid';
+import type { ThemeConfigValidationContext } from '@docusaurus/types';
+export declare const DEFAULT_THEME_CONFIG: ThemeConfig;
+export declare const Schema: Joi.ObjectSchema<ThemeConfig>;
+export declare function validateThemeConfig({ validate, themeConfig, }: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig;

package/lib/validateThemeConfig.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Schema = exports.DEFAULT_THEME_CONFIG = void 0;
+exports.validateThemeConfig = validateThemeConfig;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+exports.DEFAULT_THEME_CONFIG = {
+    mermaid: {
+        theme: {
+            dark: 'dark',
+            light: 'default',
+        },
+        options: {},
+    },
+};
+exports.Schema = utils_validation_1.Joi.object({
+    mermaid: utils_validation_1.Joi.object({
+        theme: utils_validation_1.Joi.object({
+            dark: utils_validation_1.Joi.string().default(exports.DEFAULT_THEME_CONFIG.mermaid.theme.dark),
+            light: utils_validation_1.Joi.string().default(exports.DEFAULT_THEME_CONFIG.mermaid.theme.light),
+        }).default(exports.DEFAULT_THEME_CONFIG.mermaid.theme),
+        options: utils_validation_1.Joi.object().default(exports.DEFAULT_THEME_CONFIG.mermaid.options),
+    }).default(exports.DEFAULT_THEME_CONFIG.mermaid),
+});
+function validateThemeConfig({ validate, themeConfig, }) {
+    return validate(exports.Schema, themeConfig);
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@azerion/bunosaurus-theme-mermaid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "Mermaid components for Docusaurus.",
+  "main": "lib/index.js",
+  "types": "src/theme-mermaid.d.ts",
+  "sideEffects": false,
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./src/*": "./src/*",
+    "./client": {
+      "type": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    ".": {
+      "types": "./src/theme-mermaid.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azerion/bunosaurus.git",
+    "directory": "packages/docusaurus-theme-mermaid"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc --build && copy-untyped-files && oxfmt \"lib/theme/**/*.js\"",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --build --watch",
+    "copy:watch": "copy-untyped-files --watch"
+  },
+  "dependencies": {
+    "@docusaurus/core": "npm:@azerion/bunosaurus-core@4.0.0",
+    "@docusaurus/module-type-aliases": "npm:@azerion/bunosaurus-module-type-aliases@4.0.0",
+    "@docusaurus/theme-common": "npm:@azerion/bunosaurus-theme-common@4.0.0",
+    "@docusaurus/types": "npm:@azerion/bunosaurus-types@4.0.0",
+    "@docusaurus/utils-validation": "npm:@azerion/bunosaurus-utils-validation@4.0.0",
+    "mermaid": "^12.0.0",
+    "tslib": "^2.8.1"
+  },
+  "peerDependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {useState, useEffect, useMemo, useId, useRef} from 'react';
+import {useColorMode, useThemeConfig} from '@docusaurus/theme-common';
+import {loadMermaid} from './loadMermaid';
+
+import type {RenderResult, MermaidConfig} from 'mermaid';
+import type {ThemeConfig} from '@docusaurus/theme-mermaid';
+
+// Stable className to allow users to easily target with CSS
+export const MermaidContainerClassName = 'docusaurus-mermaid-container';
+
+export function useMermaidThemeConfig(): ThemeConfig['mermaid'] {
+  return (useThemeConfig() as unknown as ThemeConfig).mermaid;
+}
+
+export function useMermaidConfig(): MermaidConfig {
+  const {colorMode} = useColorMode();
+  const mermaidThemeConfig = useMermaidThemeConfig();
+
+  const theme = mermaidThemeConfig.theme[colorMode];
+  const {options} = mermaidThemeConfig;
+
+  return useMemo(
+    () => ({startOnLoad: false, ...options, theme}),
+    [theme, options],
+  );
+}
+
+async function renderMermaid({
+  id,
+  text,
+  config,
+}: {
+  id: string;
+  text: string;
+  config: MermaidConfig;
+}): Promise<RenderResult> {
+  const mermaid = await loadMermaid();
+
+  /*
+  Mermaid API is really weird :s
+  It is a big mutable singleton with multiple config levels
+  Note: most recent API type definitions are missing
+
+  There are 2 kind of configs:
+
+  - siteConfig: some kind of global/protected shared config
+    you can only set with "initialize"
+
+  - config/currentConfig
+    the config the renderer will use
+    it is reset to siteConfig before each render
+    but it can be altered by the mermaid txt content itself through directives
+
+  To use a new mermaid config (on colorMode change for example) we should
+  update siteConfig, and it can only be done with initialize()
+   */
+  mermaid.initialize(config);
+
+  try {
+    return await mermaid.render(id, text);
+  } catch (e) {
+    // Because Mermaid add a weird SVG/Message to the DOM on error
+    // https://github.com/mermaid-js/mermaid/issues/3205#issuecomment-1719620183
+    document.querySelector(`#d${id}`)?.remove();
+    throw e;
+  }
+}
+
+export function useMermaidRenderResult({
+  text,
+  config: providedConfig,
+}: {
+  text: string;
+  config?: MermaidConfig;
+}): RenderResult | null {
+  const [result, setResult] = useState<RenderResult | null>(null);
+  const id = useId();
+  const renderCount = useRef(0);
+
+  /*
+  For flexibility, we allow the hook to receive a custom Mermaid config
+  The user could inject a modified version of the default config for example
+   */
+  const defaultMermaidConfig = useMermaidConfig();
+  const config = providedConfig ?? defaultMermaidConfig;
+
+  useEffect(() => {
+    // Mermaid removes existing DOM elements with the requested ID. Reusing an
+    // ID can delete the displayed SVG, which React won't restore if the new
+    // SVG markup is identical. Give every render its own ID instead.
+    renderMermaid({id: `${id}-${renderCount.current++}`, text, config})
+      // TODO maybe try to use Suspense here and throw the promise?
+      // See also https://github.com/pmndrs/suspend-react
+      .then(setResult)
+      .catch((e) => {
+        // Funky way to trigger parent React error boundary
+        // See https://x.com/sebastienlorber/status/1628340871899893768
+        setResult(() => {
+          throw e;
+        });
+      });
+  }, [id, text, config]);
+
+  return result;
+}

package/src/client/loadMermaid.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {Mermaid} from 'mermaid';
+
+// We load Mermaid with a dynamic import to code split / lazy load the library
+// It is only called inside a useEffect, so loading can be deferred
+export async function loadMermaid(): Promise<Mermaid> {
+  return (await import('mermaid')).default;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {Plugin} from '@docusaurus/types';
+
+export default function themeMermaid(): Plugin<void> {
+  return {
+    name: 'docusaurus-theme-mermaid',
+
+    getThemePath() {
+      return '../lib/theme';
+    },
+    getTypeScriptThemePath() {
+      return '../src/theme';
+    },
+  };
+}
+
+export {validateThemeConfig} from './validateThemeConfig';

package/src/theme/Mermaid/index.tsx

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {useEffect, useRef, type ReactNode} from 'react';
+import ErrorBoundary from '@docusaurus/ErrorBoundary';
+import {ErrorBoundaryErrorMessageFallback} from '@docusaurus/theme-common';
+import {
+  MermaidContainerClassName,
+  useMermaidRenderResult,
+} from '@docusaurus/theme-mermaid/client';
+import type {Props} from '@theme/Mermaid';
+import type {RenderResult} from 'mermaid';
+
+import styles from './styles.module.css';
+
+function MermaidRenderResult({
+  renderResult,
+}: {
+  renderResult: RenderResult;
+}): ReactNode {
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const div = ref.current!;
+    renderResult.bindFunctions?.(div);
+  }, [renderResult]);
+
+  return (
+    <div
+      ref={ref}
+      className={`${MermaidContainerClassName} ${styles.container}`}
+      dangerouslySetInnerHTML={{__html: renderResult.svg}}
+    />
+  );
+}
+
+function MermaidRenderer({value}: Props): ReactNode {
+  const renderResult = useMermaidRenderResult({text: value});
+  if (renderResult === null) {
+    return null;
+  }
+  return <MermaidRenderResult renderResult={renderResult} />;
+}
+
+export default function Mermaid(props: Props): ReactNode {
+  return (
+    <ErrorBoundary
+      fallback={(params) => <ErrorBoundaryErrorMessageFallback {...params} />}>
+      <MermaidRenderer {...props} />
+    </ErrorBoundary>
+  );
+}

package/src/theme/Mermaid/styles.module.css

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+.container {
+  max-width: 100%;
+}
+
+.container > svg {
+  max-width: 100%;
+}

package/src/theme-mermaid.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/// <reference types="@docusaurus/module-type-aliases" />
+
+declare module '@docusaurus/theme-mermaid' {
+  import type {DeepPartial} from 'utility-types';
+  import type {MermaidConfig} from 'mermaid';
+  import type {Plugin} from '@docusaurus/types';
+
+  export type ThemeConfig = {
+    mermaid: {
+      theme: {
+        light: NonNullable<MermaidConfig['theme']>;
+        dark: NonNullable<MermaidConfig['theme']>;
+      };
+      options: MermaidConfig;
+    };
+  };
+  export type UserThemeConfig = DeepPartial<ThemeConfig>;
+
+  export default function themeMermaid(): Plugin<undefined>;
+}
+
+declare module '@theme/Mermaid' {
+  import {type ReactNode} from 'react';
+
+  export interface Props {
+    value: string;
+  }
+
+  export default function Mermaid(props: Props): ReactNode;
+}

package/src/validateThemeConfig.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {Joi} from '@docusaurus/utils-validation';
+import type {ThemeConfig} from '@docusaurus/theme-mermaid';
+import type {ThemeConfigValidationContext} from '@docusaurus/types';
+
+export const DEFAULT_THEME_CONFIG: ThemeConfig = {
+  mermaid: {
+    theme: {
+      dark: 'dark',
+      light: 'default',
+    },
+    options: {},
+  },
+};
+
+export const Schema = Joi.object<ThemeConfig>({
+  mermaid: Joi.object({
+    theme: Joi.object({
+      dark: Joi.string().default(DEFAULT_THEME_CONFIG.mermaid.theme.dark),
+      light: Joi.string().default(DEFAULT_THEME_CONFIG.mermaid.theme.light),
+    }).default(DEFAULT_THEME_CONFIG.mermaid.theme),
+    options: Joi.object().default(DEFAULT_THEME_CONFIG.mermaid.options),
+  }).default(DEFAULT_THEME_CONFIG.mermaid),
+});
+
+export function validateThemeConfig({
+  validate,
+  themeConfig,
+}: ThemeConfigValidationContext<ThemeConfig>): ThemeConfig {
+  return validate(Schema, themeConfig);
+}