@docusaurus/theme-mermaid 0.0.0-5335

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Facebook, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# Docusaurus Theme Mermaid
+
+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,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 type mermaidAPI from 'mermaid/mermaidAPI';
+import type { ThemeConfig } from '@docusaurus/theme-mermaid';
+export declare const MermaidContainerClassName = "docusaurus-mermaid-container";
+export declare function useMermaidThemeConfig(): ThemeConfig['mermaid'];
+export declare function useMermaidConfig(): mermaidAPI.Config;
+export declare function useMermaidSvg(txt: string, mermaidConfigParam?: mermaidAPI.Config): string;

package/lib/client/index.js

@@ -0,0 +1,67 @@
+"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.useMermaidSvg = exports.useMermaidConfig = exports.useMermaidThemeConfig = exports.MermaidContainerClassName = void 0;
+const tslib_1 = require("tslib");
+const react_1 = require("react");
+const theme_common_1 = require("@docusaurus/theme-common");
+const mermaid_1 = tslib_1.__importDefault(require("mermaid"));
+// Stable className to allow users to easily target with CSS
+exports.MermaidContainerClassName = 'docusaurus-mermaid-container';
+function useMermaidThemeConfig() {
+    return (0, theme_common_1.useThemeConfig)().mermaid;
+}
+exports.useMermaidThemeConfig = useMermaidThemeConfig;
+function useMermaidConfig() {
+    const { colorMode } = (0, theme_common_1.useColorMode)();
+    const mermaidThemeConfig = useMermaidThemeConfig();
+    const theme = mermaidThemeConfig.theme[colorMode];
+    const { options } = mermaidThemeConfig;
+    return (0, react_1.useMemo)(() => ({ startOnLoad: false, ...options, theme }), [theme, options]);
+}
+exports.useMermaidConfig = useMermaidConfig;
+function useMermaidSvg(txt, mermaidConfigParam) {
+    /*
+    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 mermaidConfig = mermaidConfigParam ?? defaultMermaidConfig;
+    return (0, react_1.useMemo)(() => {
+        /*
+        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_1.default.mermaidAPI.initialize(mermaidConfig);
+        /*
+        Random client-only id, we don't care much about it
+        But mermaid want an id so...
+        */
+        const mermaidId = `mermaid-svg-${Math.round(Math.random() * 10000000)}`;
+        /*
+        Not even documented: mermaid.render returns the svg string
+        Using the documented form is un-necessary
+         */
+        return mermaid_1.default.render(mermaidId, txt);
+    }, [txt, mermaidConfig]);
+}
+exports.useMermaidSvg = useMermaidSvg;

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;
+function themeMermaid() {
+    return {
+        name: 'docusaurus-theme-mermaid',
+        getThemePath() {
+            return '../lib/theme';
+        },
+        getTypeScriptThemePath() {
+            return '../src/theme';
+        },
+    };
+}
+exports.default = themeMermaid;
+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.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/Mermaid';
+export default function Mermaid(props: Props): JSX.Element;

package/lib/theme/Mermaid/index.js

@@ -0,0 +1,26 @@
+/**
+ * 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 React from 'react';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import {
+  MermaidContainerClassName,
+  useMermaidSvg,
+} from '@docusaurus/theme-mermaid/client';
+import styles from './styles.module.css';
+function MermaidDiagram({value}) {
+  const svg = useMermaidSvg(value);
+  return (
+    <div
+      className={`${MermaidContainerClassName} ${styles.container}`}
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: svg}}
+    />
+  );
+}
+export default function Mermaid(props) {
+  return <BrowserOnly>{() => <MermaidDiagram {...props} />}</BrowserOnly>;
+}

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.validateThemeConfig = exports.Schema = exports.DEFAULT_THEME_CONFIG = void 0;
+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);
+}
+exports.validateThemeConfig = validateThemeConfig;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@docusaurus/theme-mermaid",
+  "version": "0.0.0-5335",
+  "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/facebook/docusaurus.git",
+    "directory": "packages/docusaurus-theme-mermaid"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc --build && node ../../admin/scripts/copyUntypedFiles.js && prettier --config ../../.prettierrc --write \"lib/theme/**/*.js\"",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --build --watch",
+    "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
+  },
+  "dependencies": {
+    "@docusaurus/core": "0.0.0-5335",
+    "@docusaurus/module-type-aliases": "0.0.0-5335",
+    "@docusaurus/theme-common": "0.0.0-5335",
+    "@docusaurus/types": "0.0.0-5335",
+    "@docusaurus/utils-validation": "0.0.0-5335",
+    "@mdx-js/react": "^1.6.22",
+    "mermaid": "^9.1.1",
+    "tslib": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/mdx-js__react": "^1.5.5",
+    "@types/mermaid": "^8.2.9",
+    "react-test-renderer": "^17.0.2"
+  },
+  "peerDependencies": {
+    "react": "^16.8.4 || ^17.0.0",
+    "react-dom": "^16.8.4 || ^17.0.0"
+  },
+  "engines": {
+    "node": ">=16.14"
+  },
+  "gitHead": "42c59e0828b093f765f6c37d522c02ef74846a31"
+}

package/src/client/index.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 {useMemo} from 'react';
+import {useColorMode, useThemeConfig} from '@docusaurus/theme-common';
+import mermaid from 'mermaid';
+import type mermaidAPI from 'mermaid/mermaidAPI';
+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(): mermaidAPI.Config {
+  const {colorMode} = useColorMode();
+  const mermaidThemeConfig = useMermaidThemeConfig();
+
+  const theme = mermaidThemeConfig.theme[colorMode];
+  const {options} = mermaidThemeConfig;
+
+  return useMemo(
+    () => ({startOnLoad: false, ...options, theme}),
+    [theme, options],
+  );
+}
+
+export function useMermaidSvg(
+  txt: string,
+  mermaidConfigParam?: mermaidAPI.Config,
+): string {
+  /*
+  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 mermaidConfig = mermaidConfigParam ?? defaultMermaidConfig;
+
+  return useMemo(() => {
+    /*
+    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.mermaidAPI.initialize(mermaidConfig);
+
+    /*
+    Random client-only id, we don't care much about it
+    But mermaid want an id so...
+    */
+    const mermaidId = `mermaid-svg-${Math.round(Math.random() * 10000000)}`;
+
+    /*
+    Not even documented: mermaid.render returns the svg string
+    Using the documented form is un-necessary
+     */
+    return mermaid.render(mermaidId, txt);
+  }, [txt, mermaidConfig]);
+}

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,32 @@
+/**
+ * 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 React from 'react';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import {
+  MermaidContainerClassName,
+  useMermaidSvg,
+} from '@docusaurus/theme-mermaid/client';
+
+import type {Props} from '@theme/Mermaid';
+
+import styles from './styles.module.css';
+
+function MermaidDiagram({value}: Props): JSX.Element {
+  const svg = useMermaidSvg(value);
+  return (
+    <div
+      className={`${MermaidContainerClassName} ${styles.container}`}
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: svg}}
+    />
+  );
+}
+
+export default function Mermaid(props: Props): JSX.Element {
+  return <BrowserOnly>{() => <MermaidDiagram {...props} />}</BrowserOnly>;
+}

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,35 @@
+/**
+ * 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 mermaidAPI from 'mermaid/mermaidAPI';
+  import type {Plugin} from '@docusaurus/types';
+
+  export type ThemeConfig = {
+    mermaid: {
+      theme: {
+        light: mermaidAPI.Theme;
+        dark: mermaidAPI.Theme;
+      };
+      options: mermaidAPI.Config;
+    };
+  };
+  export type UserThemeConfig = DeepPartial<ThemeConfig>;
+
+  export default function themeMermaid(): Plugin<undefined>;
+}
+
+declare module '@theme/Mermaid' {
+  export interface Props {
+    value: string;
+  }
+
+  export default function Mermaid(props: Props): JSX.Element;
+}

package/src/validateThemeConfig.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 mermaidAPI from 'mermaid/mermaidAPI';
+import type {ThemeConfigValidationContext} from '@docusaurus/types';
+
+export const DEFAULT_THEME_CONFIG: ThemeConfig = {
+  mermaid: {
+    theme: {
+      dark: 'dark' as mermaidAPI.Theme,
+      light: 'default' as mermaidAPI.Theme,
+    },
+    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);
+}