@zikojs/mind-elixir

Declarative Mind-Elixir integration for ZikoJS.

@zikojs/mind-elixir provides ZikoJS components and utilities for building interactive mind maps using a declarative API, native Mind-Elixir node data, valid YAML, or a simple tree syntax.

Features

• Declarative MindNode API
• Mind-Elixir integration through ZikoJS
• Support for raw Mind-Elixir nodeData
• Convert valid YAML into Mind-Elixir data
• Readable tree syntax for creating mind maps
• Configurable Mind-Elixir options
• Mind-Elixir events
• Node properties such as id, direction, tags, style, icons, and hyperLink
• Automatic UUID generation for nodes without an id
• Automatic root-node handling
• Convert Mind-Elixir data back to MindNode objects
• Access the underlying Mind-Elixir instance
• ZikoJS UIElement integration

Installation

npm install @zikojs/mind-elixir

Basic Usage

import { MindMap, MindNode } from "@zikojs/mind-elixir";

const map = MindMap(
  { height: "400px" },

  MindNode(
    "ZikoJS",
    MindNode("Core"),
    MindNode("Ecosystem"),
    MindNode("Tooling")
  )
);

map.mount(document.body);

Declarative Mind Maps

MindNode() can be nested to declaratively construct a mind map.

import { MindMap, MindNode } from "@zikojs/mind-elixir";

const map = MindMap(
  {
    height: "400px",
    direction: 2,
  },

  MindNode(
    "ZikoJS Architecture",
    { id: "root" },

    MindNode(
      "Core UI Engine",
      { direction: 0, tags: ["Core"] },

      MindNode("Virtual DOM-less Architecture"),
      MindNode("Reactive Signals & Getters"),
      MindNode("Hyperscript Support")
    ),

    MindNode(
      "Ecosystem Integrations",
      { direction: 1, tags: ["Integrations"] },

      MindNode("P52DObject (Canvas 2D)"),
      MindNode("UIChartCanvas (Chart.js)"),
      MindNode("UILeafletMap (Maps)"),
      MindNode("UIMindMap (Mind-Elixir)")
    ),

    MindNode(
      "Tooling & Routers",
      { direction: 1 },

      MindNode("UFBR Router"),
      MindNode("@zikojs/server")
    )
  )
);

map.mount(document.body);

Node Properties

Properties can be passed as the second argument to MindNode().

MindNode(
  "Core UI Engine",
  {
    id: "core",
    direction: 0,
    expanded: true,
    tags: ["Core"],
    icons: ["code"],
    hyperLink: "https://example.com",

    style: {
      fontSize: "18px",
      color: "#222",
      background: "#f5f5f5",
      fontWeight: "bold",
    },

    image: {
      url: "https://example.com/image.png",
      width: 200,
      height: 120,
    },

    branchColor: "#666",
  }
);

Supported node properties include:

| Property | Description | | ------------------------- | -------------------------------------- | | topic | Node topic/content | | id | Unique node identifier | | style | Node styling | | children | Child nodes | | tags | Node tags | | icons | Node icons | | hyperLink | Node hyperlink | | expanded | Whether the node is initially expanded | | direction | Node direction | | root | Whether the node is the root | | image | Image configuration | | branchColor | Branch color | | dangerouslySetInnerHTML | Directly insert HTML |

The parent property is generated by the program and should normally not be supplied manually.

Raw Node Data

You can provide Mind-Elixir-compatible node data directly.

const rawNodeData = {
  id: "root",
  topic: "Direct Object Input",

  children: [
    {
      id: "sub1",
      topic: "Subtopic",
    },
  ],
};

const map = MindMap(
  { height: "400px" },
  rawNodeData
);

map.mount(document.body);

This is useful when your mind map data already comes from JSON, an API, a database, or another application.

YAML

yaml2MindElixirData() converts valid YAML into Mind-Elixir node data.

import {
  MindMap,
  yaml2MindElixirData,
} from "@zikojs/mind-elixir";

const data = yaml2MindElixirData(`
topic: ZikoJS Architecture
direction: 2
tags:
  - ziko
  - javascript

children:
  - topic: Core UI Engine
    tags:
      - core

    children:
      - topic: UIElement
      - topic: Hooks
      - topic: Hyperscript

  - topic: Ecosystem
    children:
      - topic: Three.js
      - topic: Chart.js
      - topic: Mind-Elixir
`);

const map = MindMap(
  { height: "500px" },
  data
);

map.mount(document.body);

Automatic IDs

Node id values are optional.

When an id is not provided, yaml2MindElixirData() generates one using crypto.randomUUID().

topic: ZikoJS
children:
  - topic: Core
  - topic: Ecosystem

The resulting nodes receive generated UUIDs.

Root Node

The first node is always treated as the root node.

For example:

- topic: ZikoJS
  children:
    - topic: Core

- topic: Ecosystem

- topic: Tooling

The first node, ZikoJS, becomes the root:

ZikoJS
├── Core
├── Ecosystem
└── Tooling

There is no need to explicitly specify:

root: true

The utility sets the root node automatically.

Multiple Top-Level YAML Nodes

yaml2MindElixirData() accepts either a single node object or an array of nodes.

- topic: ZikoJS
  children:
    - topic: Core

- topic: Ecosystem
  children:
    - topic: Mind-Elixir

The first node becomes the root and the remaining top-level nodes are attached to it.

YAML Node Properties

Because this is actual YAML, complex properties can be represented naturally.

topic: Documentation
id: docs
expanded: true

style:
  fontSize: 18px
  color: "#222"
  background: "#f5f5f5"
  fontWeight: bold

tags:
  - documentation
  - ziko

icons:
  - book

hyperLink: https://zikojs.org

image:
  url: https://example.com/docs.png
  width: 300
  height: 200

Tree Syntax

For authoring mind maps manually, tree2MindElixirData() provides a more compact custom syntax.

Unlike yaml2MindElixirData(), this is not YAML. It is a small tree-oriented syntax designed specifically for mind maps.

import {
  MindMap,
  tree2MindElixirData,
} from "@zikojs/mind-elixir";

const data = tree2MindElixirData(`
ZikoJS Architecture
  @direction: 2
  @tags: [ziko, javascript]

  - Core UI Engine
    @tags: [core]

    - UIElement
    - Hooks
    - Hyperscript

  - Ecosystem
    - Three.js
    - Chart.js
    - Mind-Elixir

  - Tooling
    - UFBR Router
    - @zikojs/server
`);

const map = MindMap(
  { height: "500px" },
  data
);

map.mount(document.body);

Tree Syntax Rules

A normal line creates a node:

ZikoJS

A line beginning with - creates a child node:

ZikoJS
  - Core
  - Ecosystem
  - Tooling

Properties begin with @:

ZikoJS
  @direction: 2
  @tags: [ziko, javascript]

  - Core

The resulting tree is:

ZikoJS
├── Core
├── Ecosystem
└── Tooling

Properties

Properties use:

@property: value

For example:

ZikoJS
  @id: root
  @expanded: true
  @direction: 2
  @hyperLink: https://zikojs.org
  @tags: [ziko, javascript]

  - Core

Values support common scalar types:

@expanded: true
@direction: 2
@title: "ZikoJS"
@tags: [ziko, javascript]

Nested Properties

Complex properties can be represented using indentation.

Documentation
  @image:
    url: https://example.com/docs.png
    width: 300
    height: 200

Comments

Empty lines are ignored.

Lines beginning with # are treated as comments.

# Main topic

ZikoJS
  # Core technologies

  - Core
    - UIElement
    - Hooks

  - Ecosystem
    - Server
    - Router

YAML vs Tree Syntax

The two utilities serve different purposes:

| Utility | Format | Purpose | | ----------------------- | ------------------ | --------------------------------------------- | | yaml2MindElixirData() | Valid YAML | Structured data, configuration, serialization | | tree2MindElixirData() | Custom tree syntax | Human-friendly mind-map authoring |

Use YAML when interoperability and structured data are important.

Use tree syntax when readability and quick authoring are more important.

Both utilities produce the same Mind-Elixir-compatible node structure.

Mind Map Options

Options passed to MindMap() are forwarded to the Mind-Elixir instance.

const map = MindMap(
  {
    height: "500px",
    direction: 2,
    draggable: true,
    contextMenu: true,
    toolBar: true,
    nodeMenu: true,
    keypress: true,
    locale: "en",
  },

  MindNode(
    "My Project",
    MindNode("Frontend"),
    MindNode("Backend")
  )
);

Direction

Mind-Elixir supports different layout directions.

MindMap(
  {
    direction: 2,
  },
  root
);

Individual nodes can also specify a direction:

MindNode(
  "Left Branch",
  { direction: 0 }
);

MindNode(
  "Right Branch",
  { direction: 1 }
);

Node-level direction is only effective where supported by Mind-Elixir.

Events

Mind-Elixir events can be registered through the events option.

const map = MindMap(
  {
    height: "400px",

    events: {
      selectNode: (node) => {
        console.log("Selected node:", node);
      },

      // Other Mind-Elixir events can be registered here.
    },
  },

  MindNode(
    "Root",
    MindNode("Child")
  )
);

map.mount(document.body);

Accessing Mind-Elixir Data

The MindMap component exposes getData().

const map = MindMap(
  {},
  MindNode(
    "Root",
    MindNode("Child")
  )
);

map.mount(document.body);

const data = map.getData();

console.log(data);

The returned object contains the current Mind-Elixir data.

Convert Data Back to Mind Nodes

getMindNodes() converts the current Mind-Elixir data into UIMindNode objects.

const nodes = map.getMindNodes();

console.log(nodes);

This is useful when moving between the declarative ZikoJS representation and the native Mind-Elixir representation.

Refreshing a Mind Map

You can replace the current node tree with refresh().

const map = MindMap(
  {},

  MindNode(
    "Initial Root",
    MindNode("Child")
  )
);

map.mount(document.body);

map.refresh(
  MindNode(
    "New Root",
    MindNode("New Child")
  )
);

Raw node data can also be supplied:

map.refresh({
  id: "root",
  topic: "New Root",

  children: [
    {
      id: "child",
      topic: "New Child",
    },
  ],
});

Destroy

Destroy the underlying Mind-Elixir instance:

map.destroy();

Complete Example

import {
  MindMap,
  tree2MindElixirData,
} from "@zikojs/mind-elixir";

const data = tree2MindElixirData(`
ZikoJS
  @direction: 2
  @tags: [javascript, ecosystem]

  - Core
    @tags: [core]

    - UI Engine
    - Hooks
    - DOM

  - Ecosystem
    - Server
    - Router
    - MDX

  - Integrations
    - Three.js
    - Chart.js
    - Mind-Elixir
`);

const map = MindMap(
  {
    height: "500px",

    events: {
      selectNode: (node) => {
        console.log("Selected:", node);
      },
    },
  },

  data
);

map.mount(document.body);

API

MindMap(props?, data?)

Creates a ZikoJS Mind-Elixir component.

MindMap(props?, data?)

data can be:

• a MindNode
• a UIMindNode
• a Mind-Elixir-compatible node data object

MindNode(topic, props?, ...children)

Creates a declarative mind map node.

MindNode(
  "Topic",
  { id: "topic" },
  MindNode("Child")
);

yaml2MindElixirData(source)

Parses valid YAML and converts it into Mind-Elixir node data.

const data = yaml2MindElixirData(`
topic: Root
children:
  - topic: Child
`);

If a node has no id, a UUID is generated automatically.

The first node is automatically treated as the root.

tree2MindElixirData(source)

Parses the custom tree syntax and converts it into Mind-Elixir node data.

const data = tree2MindElixirData(`
Root
  - Child
    - Nested
`);

map.getData()

Returns the current Mind-Elixir data.

const data = map.getData();

map.getMindNodes()

Converts the current Mind-Elixir data into UIMindNode objects.

const nodes = map.getMindNodes();

map.refresh(data)

Replaces the current mind map data.

map.refresh(
  MindNode(
    "New Root",
    MindNode("New Child")
  )
);

map.destroy()

Destroys the Mind-Elixir instance.

map.destroy();

Design Philosophy

@zikojs/mind-elixir follows the ZikoJS approach of keeping the integration declarative without introducing a virtual DOM layer.

You can choose the representation that best fits your use case:

MindNode()
    ↓
Declarative JavaScript

yaml2MindElixirData()
    ↓
Valid YAML

tree2MindElixirData()
    ↓
Readable tree syntax

Raw NodeObj
    ↓
Existing application data

        ↓

   Mind-Elixir

The package provides a bridge between ZikoJS's declarative UI model and Mind-Elixir's native mind-map data model.