@ateeducacion/mind-elixir-export-mermaid 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Área de Tecnología Educativa (Gobierno de Canarias) and contributors
+
+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,120 @@
+# Mind Elixir export to Mermaid
+
+[![CI](https://github.com/ateeducacion/mind-elixir-export-mermaid/actions/workflows/ci.yml/badge.svg)](https://github.com/ateeducacion/mind-elixir-export-mermaid/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/ateeducacion/mind-elixir-export-mermaid/branch/main/graph/badge.svg)](https://codecov.io/gh/ateeducacion/mind-elixir-export-mermaid)
+[![npm](https://img.shields.io/npm/v/@ateeducacion/mind-elixir-export-mermaid)](https://www.npmjs.com/package/@ateeducacion/mind-elixir-export-mermaid)
+[![Publish](https://github.com/ateeducacion/mind-elixir-export-mermaid/actions/workflows/publish.yml/badge.svg)](https://github.com/ateeducacion/mind-elixir-export-mermaid/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Converts [Mind Elixir](https://github.com/SSShooter/mind-elixir-core) mind maps to
+[Mermaid `mindmap`](https://mermaid.js.org/syntax/mindmap.html) source.
+
+Mermaid text is tiny, and it can be rendered to a sharp, lightweight SVG by
+[Mermaid](https://mermaid.js.org) or by [Pele](https://github.com/obsidianmd/pele), which
+needs no DOM and also runs on a server. GitHub, GitLab, Obsidian, Notion and many
+documentation tools display it as well. For a 16-node map, the SVG that Pele renders from
+this output is 8 KB (1.7 KB gzip), against 84 KB for a PNG screenshot of the same map.
+
+No runtime dependencies, no DOM, and it works in browsers, Node.js, Bun and Deno.
+
+## Install
+
+```sh
+npm install @ateeducacion/mind-elixir-export-mermaid
+```
+
+## Use
+
+```ts
+import MindElixir from "mind-elixir";
+import { mindElixirToMermaid } from "@ateeducacion/mind-elixir-export-mermaid";
+
+const mind = new MindElixir({ el: "#map" });
+mind.init(MindElixir.new("Science"));
+
+const source = mindElixirToMermaid(mind.getData());
+// mindmap
+//   n0(("Science"))
+```
+
+It takes the data returned by `mind.getData()`, or a single node and its descendants.
+
+Render it with Pele:
+
+```ts
+import { render } from "pele";
+
+const { svg } = render(source);
+```
+
+or with Mermaid:
+
+```ts
+import mermaid from "mermaid";
+
+const { svg } = await mermaid.render("mindmap", source);
+```
+
+## Options
+
+```ts
+mindElixirToMermaid(data, {
+  rootShape: "circle",
+  nodeShape: "rounded",
+  shape: (node, depth) => (depth === 1 ? "cloud" : undefined),
+  className: (node) => (node.branchColor === "#c0392b" ? "red" : undefined),
+  icon: (node) => (node.tags?.includes("book") ? "fa fa-book" : undefined),
+  markdown: true,
+  omitCollapsed: false,
+  indent: 2,
+});
+```
+
+| Option                   | Default     | Description                                                                                                                                                                                                      |
+| ------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rootShape`              | `"circle"`  | Shape of the root: `square`, `rounded`, `circle`, `bang`, `cloud` or `hexagon`.                                                                                                                                  |
+| `nodeShape`              | `"rounded"` | Shape of the other nodes.                                                                                                                                                                                        |
+| `shape(node, depth)`     |             | Shape of one node; return `undefined` to use the defaults.                                                                                                                                                       |
+| `className(node, depth)` |             | CSS classes written as `:::name` (letters, digits, `-` and `_`).                                                                                                                                                 |
+| `icon(node, depth)`      |             | Icon classes written as `::icon(...)`, for example `"fa fa-book"`.                                                                                                                                               |
+| `markdown`               | `false`     | Write [markdown strings](https://mermaid.js.org/syntax/mindmap.html#markdown-strings), keeping bold (`fontWeight: "bold"`), italic (`fontStyle: "italic"`) and line breaks. Otherwise line breaks become spaces. |
+| `omitCollapsed`          | `false`     | Leave out the children of folded nodes (`expanded: false`).                                                                                                                                                      |
+| `indent`                 | `2`         | Spaces per level, from 1 to 8.                                                                                                                                                                                   |
+
+`escapeLabel(text, markdown?)` is exported too, for building labels by hand.
+
+## What is exported
+
+The hierarchy, the order and the text of every node. Text is written with Mermaid's
+entity codes (`#quot;`, `#lt;`, `#35;`, …), so a topic can contain quotes, brackets,
+`#`, `*`, `_` or HTML-like text and still renders exactly as typed, never as markup.
+
+Mermaid's `mindmap` syntax has no equivalent for per-node colours and font styles (other
+than bold and italic in markdown mode), branch sides, folded state, arrows, summaries,
+links, images or tags, so those are not exported. Keep the Mind Elixir data as the source
+of your map and use this output as a view of it. The `className` option can carry some of
+that information as CSS classes if your page styles them.
+
+Invalid input throws a `TypeError`, and an invalid option, class name or icon throws a
+`RangeError`, rather than writing source that Mermaid cannot parse.
+
+## Background
+
+This package was proposed in
+[mind-elixir-core#386](https://github.com/SSShooter/mind-elixir-core/issues/386). Thanks
+to [@SSShooter](https://github.com/SSShooter) for Mind Elixir and for the suggestion to
+make it a separate package. It is used by [eXeLearning](https://github.com/exelearning/exelearning),
+an open-source authoring tool for educational content, whose published content needs a
+static image of each mind map.
+
+## Develop
+
+```sh
+npm ci
+npm run check         # format, typecheck, tests with 100% coverage, build
+npm run test:package  # pack, install the tarball in an empty project and import it
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Converts Mind Elixir mind maps to Mermaid `mindmap` source.
+ *
+ * The output can be rendered to SVG by Mermaid (https://mermaid.js.org) or by Pele
+ * (https://github.com/obsidianmd/pele), and is understood by GitHub, GitLab, Obsidian and
+ * other tools. It keeps the hierarchy, the order and the text of the map. Mermaid mindmaps
+ * have no per-node colours, branch sides, arrows or summaries, so those are not exported.
+ */
+/** The fields of a Mind Elixir node this module reads (compatible with `NodeObj`). */
+export interface MindElixirNode {
+    topic: string;
+    children?: readonly MindElixirNode[] | undefined;
+    expanded?: boolean | undefined;
+    style?: {
+        fontWeight?: string | undefined;
+        fontStyle?: string | undefined;
+    } | undefined;
+}
+/** The fields of Mind Elixir data this module reads (compatible with `MindElixirData`). */
+export interface MindElixirData {
+    nodeData: MindElixirNode;
+}
+/** Mermaid mindmap node shapes. */
+export type MermaidShape = "square" | "rounded" | "circle" | "bang" | "cloud" | "hexagon";
+/**
+ * Options. `N` is the node type of your data (Mind Elixir's `NodeObj`, for example), which
+ * the callbacks receive.
+ */
+export interface MermaidExportOptions<N extends MindElixirNode = MindElixirNode> {
+    /** Shape of the root node. Default: `"circle"`. */
+    rootShape?: MermaidShape;
+    /** Shape of the other nodes. Default: `"rounded"`. */
+    nodeShape?: MermaidShape;
+    /** Shape of one node, overriding the two options above when it returns a shape. */
+    shape?: (node: N, depth: number) => MermaidShape | undefined;
+    /** CSS classes for a node, written as `:::name`. Names may contain letters, digits, `-` and `_`. */
+    className?: (node: N, depth: number) => string | readonly string[] | undefined;
+    /** Icon classes for a node, written as `::icon(...)`, for example `"fa fa-book"`. */
+    icon?: (node: N, depth: number) => string | undefined;
+    /**
+     * Write labels as Mermaid markdown strings, which keep bold (`fontWeight: "bold"`),
+     * italic (`fontStyle: "italic"`) and line breaks. Default: `false` (plain labels, line
+     * breaks become spaces).
+     */
+    markdown?: boolean;
+    /** Leave out the children of folded nodes (`expanded: false`). Default: `false`. */
+    omitCollapsed?: boolean;
+    /** Spaces per level. Default: `2`. */
+    indent?: number;
+}
+/** Escapes a topic for a quoted Mermaid label. */
+export declare function escapeLabel(text: string, markdown?: boolean): string;
+/**
+ * Converts Mind Elixir data (as returned by `mind.getData()`) or a single node and its
+ * descendants to Mermaid `mindmap` source.
+ *
+ * @throws {TypeError} when the input is not a Mind Elixir node or data.
+ * @throws {RangeError} when an option or a class name/icon returned by a callback is invalid.
+ */
+export declare function mindElixirToMermaid<N extends MindElixirNode>(data: {
+    nodeData: N;
+} | N, options?: MermaidExportOptions<N>): string;
+export default mindElixirToMermaid;

package/dist/index.js

@@ -0,0 +1,139 @@
+/**
+ * Converts Mind Elixir mind maps to Mermaid `mindmap` source.
+ *
+ * The output can be rendered to SVG by Mermaid (https://mermaid.js.org) or by Pele
+ * (https://github.com/obsidianmd/pele), and is understood by GitHub, GitLab, Obsidian and
+ * other tools. It keeps the hierarchy, the order and the text of the map. Mermaid mindmaps
+ * have no per-node colours, branch sides, arrows or summaries, so those are not exported.
+ */
+const SHAPES = {
+    square: ["[", "]"],
+    rounded: ["(", ")"],
+    circle: ["((", "))"],
+    bang: [")", "("],
+    cloud: ["))", "(("],
+    hexagon: ["{{", "}}"],
+};
+const CLASS_NAME = /^[A-Za-z_][\w-]*$/;
+const ICON = /^[\w -]+$/;
+/**
+ * Mermaid entity codes for the characters Mermaid would otherwise read as syntax, markup,
+ * entities or formatting (Pele formats `*` and `_` even outside markdown strings). `#` comes
+ * first, so the codes added afterwards are not encoded again.
+ */
+const ENTITIES = [
+    [/#/g, "#35;"],
+    [/"/g, "#quot;"],
+    [/</g, "#lt;"],
+    [/>/g, "#gt;"],
+    [/'/g, "#39;"],
+    [/`/g, "#96;"],
+    [/\*/g, "#42;"],
+    [/_/g, "#95;"],
+];
+/** Escapes a topic for a quoted Mermaid label. */
+export function escapeLabel(text, markdown = false) {
+    let label = String(text).replace(/\r\n?/g, "\n").replace(/\t/g, " ");
+    for (const [pattern, code] of ENTITIES)
+        label = label.replace(pattern, code);
+    if (markdown) {
+        label = label
+            .split("\n")
+            .map((line) => line.trim())
+            .join("\n")
+            .trim();
+    }
+    else {
+        label = label.replace(/\s*\n\s*/g, " ").trim();
+    }
+    // An empty quoted label is a syntax error
+    return label || " ";
+}
+function label(node, markdown) {
+    const text = escapeLabel(node.topic, markdown);
+    if (!markdown)
+        return `"${text}"`;
+    let formatted = text;
+    if (text.trim()) {
+        if (node.style?.fontStyle === "italic")
+            formatted = `*${formatted}*`;
+        if (node.style?.fontWeight === "bold")
+            formatted = `**${formatted}**`;
+    }
+    return `"\`${formatted}\`"`;
+}
+function classes(value) {
+    if (value === undefined)
+        return [];
+    const names = (typeof value === "string" ? value.split(/\s+/) : [...value]).filter(Boolean);
+    for (const name of names) {
+        if (!CLASS_NAME.test(name))
+            throw new RangeError(`Invalid Mermaid class name: ${JSON.stringify(name)}`);
+    }
+    return names;
+}
+function isNode(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.topic === "string");
+}
+/**
+ * Converts Mind Elixir data (as returned by `mind.getData()`) or a single node and its
+ * descendants to Mermaid `mindmap` source.
+ *
+ * @throws {TypeError} when the input is not a Mind Elixir node or data.
+ * @throws {RangeError} when an option or a class name/icon returned by a callback is invalid.
+ */
+export function mindElixirToMermaid(data, options = {}) {
+    const root = isNode(data)
+        ? data
+        : data?.nodeData;
+    if (!isNode(root))
+        throw new TypeError("Expected Mind Elixir data or a node with a string topic");
+    const indent = options.indent ?? 2;
+    if (!Number.isInteger(indent) || indent < 1 || indent > 8) {
+        throw new RangeError("indent must be an integer from 1 to 8");
+    }
+    const markdown = options.markdown === true;
+    const rootShape = options.rootShape ?? "circle";
+    const nodeShape = options.nodeShape ?? "rounded";
+    for (const shape of [rootShape, nodeShape]) {
+        if (!(shape in SHAPES))
+            throw new RangeError(`Unknown Mermaid shape: ${JSON.stringify(shape)}`);
+    }
+    const lines = ["mindmap"];
+    let count = 0;
+    // Iterative, so a very deep map cannot overflow the call stack
+    const stack = [
+        { node: root, depth: 0 },
+    ];
+    while (stack.length > 0) {
+        const { node: current, depth } = stack.pop();
+        // Every node of the map has the caller's node type
+        const node = current;
+        if (!isNode(node))
+            throw new TypeError("Every node must have a string topic");
+        const shape = options.shape?.(node, depth) ?? (depth === 0 ? rootShape : nodeShape);
+        const brackets = SHAPES[shape];
+        if (!brackets)
+            throw new RangeError(`Unknown Mermaid shape: ${JSON.stringify(shape)}`);
+        const pad = " ".repeat(indent * (depth + 1));
+        lines.push(`${pad}n${count++}${brackets[0]}${label(node, markdown)}${brackets[1]}`);
+        const icon = options.icon?.(node, depth);
+        if (icon !== undefined) {
+            if (!ICON.test(icon))
+                throw new RangeError(`Invalid Mermaid icon: ${JSON.stringify(icon)}`);
+            lines.push(`${pad}::icon(${icon})`);
+        }
+        const names = classes(options.className?.(node, depth));
+        if (names.length > 0)
+            lines.push(`${pad}:::${names.join(" ")}`);
+        if (options.omitCollapsed && node.expanded === false)
+            continue;
+        const children = node.children ?? [];
+        for (let i = children.length - 1; i >= 0; i--)
+            stack.push({ node: children[i], depth: depth + 1 });
+    }
+    return lines.join("\n");
+}
+export default mindElixirToMermaid;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@ateeducacion/mind-elixir-export-mermaid",
+  "version": "0.1.0",
+  "description": "Export Mind Elixir mind maps to Mermaid mindmap syntax, for lightweight vector output with Mermaid or Pele",
+  "license": "MIT",
+  "author": "Ernesto Serrano",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ateeducacion/mind-elixir-export-mermaid.git"
+  },
+  "homepage": "https://github.com/ateeducacion/mind-elixir-export-mermaid#readme",
+  "bugs": {
+    "url": "https://github.com/ateeducacion/mind-elixir-export-mermaid/issues"
+  },
+  "keywords": [
+    "mind-elixir",
+    "mermaid",
+    "mindmap",
+    "mind-map",
+    "pele",
+    "svg",
+    "export"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "check": "npm run format:check && npm run typecheck && npm test && npm run build",
+    "prepack": "npm run build",
+    "test:package": "node scripts/test-package.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "26.6.4",
+    "@vitest/coverage-v8": "5.0.3",
+    "mind-elixir": "5.15.1",
+    "pele": "1.6.0",
+    "prettier": "3.9.9",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  }
+}