MindViz

MindViz is an interactive mind map visualization tool that lets users dynamically create, edit, delete, and style nodes on an infinite canvas. The core functionality is split into two main parts:

• The model layer, represented by the MindMap and MindNode classes.
• The visualization layer, provided by the VisualMindMap class that renders the mind map to an HTML container, supports freeform dragging, zooming, and exporting as SVG.

Features

• Mind Map Model:

  • Create, update, and delete nodes.
  • Maintain parent-child relationships and node properties such as background color, description, and expansion state.
  • Export and import the mind map as JSON.

• Visual Mind Map:

  • Render nodes with modern styling on an infinite canvas.
  • Support for radial and tree layouts.
  • Interactive operations including node selection, dragging, freeform repositioning, and zoom controls.
  • Toolbar actions for re-centering the canvas, exporting the map as SVG, clearing nodes, and more.
  • React integration via the static method VisualMindMap.fromReactRef.

Installation

For use in your project:

npm i mindviz

For people looking to help development:

Clone this repository, then run

npm i

Build

Compile the TypeScript sources and copy declaration files by running:

npm run build

The compiled JavaScript and types will be available in the dist folder.

Run

To start the application (if serving an HTML page) execute:

npm start

Ensure that your HTML page (e.g., index.html) is configured to load the compiled JavaScript.

Testing

MindViz uses Playwright for browser-based tests. To run the tests:

npm run test

The tests currently cover only the underyling mindmap model and base operations.

Usage

Using the Mind Map Model

The model is defined in src/mindmap.ts. Create a new mind map by instantiating a MindMap with a root MindNode:

// Example:
import { MindNode, MindMap } from "./src/mindmap";

const rootNode = new MindNode(1, "Root");
const mindMap = new MindMap(rootNode);

// Add a new node under the root
const newNode = mindMap.addMindNode(1, "Child Node");

// Update a node
mindMap.updateMindNode(newNode.id, "Updated Label", "A brief description");

// Delete a node (except the root)
mindMap.deleteMindNode(newNode.id);

// Export and import as JSON:
const exported = mindMap.toJSON();
mindMap.fromJSON(exported);

Visualizing the Mind Map

The visualization is handled in src/visualMindmap.ts. Render your mind map by providing an HTML container and the MindMap instance:

// Example with plain JavaScript/TypeScript:
import { VisualMindMap } from "./src/visualMindmap";
import { MindNode, MindMap } from "./src/mindmap";

// Assume "container" is a valid HTMLElement
const container = document.getElementById("mindmapContainer") as HTMLElement;
const rootNode = new MindNode(1, "Root");
const mindMap = new MindMap(rootNode);

const visualMindMap = new VisualMindMap(container, mindMap);
visualMindMap.render();

React Integration

To use in a React application, pass a ref of a container DIV to the static method fromReactRef:

import React, { useRef, useEffect } from "react";
import { VisualMindMap } from "./src/visualMindmap";
import { MindNode, MindMap } from "./src/mindmap";

const MindVizComponent: React.FC = () => {
  const containerRef = useRef<HTMLDivElement>(null);
  
  useEffect(() => {
    if (containerRef.current) {
      const rootNode = new MindNode(1, "Root");
      const mindMap = new MindMap(rootNode);
      const visualMindMap = VisualMindMap.fromReactRef(containerRef, mindMap);
      visualMindMap.render();
    }
  }, []);
  
  return <div ref={containerRef} style={{ width: "800px", height: "600px" }} />;
};

export default MindVizComponent;

Programmatic Editing & AI Integration

MindViz exposes helper methods for automated tools or AI assistants to modify a map without direct user interaction. Use the public APIs on MindMap and VisualMindMap to inspect and mutate nodes:

// Access all nodes
const nodes = visualMindMap.getAllNodes();

// Update multiple properties on a node
mindMap.updateMindNodeProperties(1, {
  label: "New label",
  description: "Generated by AI"
});

// Apply a batch of operations generated elsewhere
visualMindMap.applyOperations([
  { type: 'node_add', parentId: 1, label: 'AI Node', nodeId: 99 },
  { type: 'node_props', nodeId: 99, props: { background: '#ff0' } }
]);

Vercel AI SDK Helpers

MindViz includes convenience functions backed by Vercel's AI SDK to quickly integrate generative features. Set OPENAI_API_KEY in your environment and use these helpers. You can also choose your own provider and model:

import { summarizeMindMap, generateOperations } from 'mindviz';

const summary = await summarizeMindMap(mindMap);
console.log(summary);

const ops = await generateOperations('Add a node about project goals');
visualMindMap.applyOperations(ops);

By default the helpers use openai('gpt-4o'). Pass options to select any provider supported by the AI SDK:

import { anthropic } from '@ai-sdk/anthropic';

const summary = await summarizeMindMap(mindMap, {
  provider: anthropic,
  model: 'claude-3-opus-20240229'
});

Configuration

• TypeScript:
  The project uses a modern TypeScript setup targeting ES2020. Adjust settings in the tsconfig.json file as needed.

• Dependencies:
  Make sure you have Node.js (v14 or newer) installed.

License

MindViz is released under the ISC License.