@5cover/mermaid-ast 0.0.0-stage → 0.9.0

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# Mermaid Tools Monorepo
 
-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.
+This repository contains tools for working with Mermaid diagrams.
+
+## Packages
+
+| Package | Description | npm | JSR |
+|---------|-------------|-----|-----|
+| [mermaid-ast](./packages/mermaid-ast/) | Parse and render Mermaid diagrams to/from AST | [![npm](https://img.shields.io/npm/v/mermaid-ast)](https://www.npmjs.com/package/mermaid-ast) | [![JSR](https://jsr.io/badges/@emily/mermaid-ast)](https://jsr.io/@emily/mermaid-ast) |
+| [mermaid-svg](./packages/mermaid-svg/) | Render Mermaid diagrams to SVG | - | - |
+
+## mermaid-ast
+
+**Parses all 18 diagram types supported by mermaid.js and renders them back to text.**
+
+Features:
+- Full round-trip fidelity: `render(parse(text))` produces semantically equivalent diagrams
+- Wrapper classes for programmatic diagram manipulation
+- Works in Bun, Node.js, and Deno
+
+See the [mermaid-ast README](./packages/mermaid-ast/README.md) for full documentation, API reference, and examples.
+
+## Development
+
+```bash
+bun install  # Install dependencies
+just test    # Run all tests
+just         # See all available commands
+```
+
+## Releasing
+
+> **IMPORTANT:** Follow the release procedure exactly. Do not release manually.
+>
+> See [.agents/procedures/release.md](.agents/procedures/release.md) for the complete release procedure.
+
+## License
+
+MIT

package/dist/block.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Block Diagram Wrapper Class
+ *
+ * Provides a fluent API for creating and manipulating block-beta diagrams.
+ */
+import { DiagramWrapper } from './diagram-wrapper.js';
+import type { BlockAST, BlockArrowDirection, BlockComposite, BlockEdge, BlockEdgeType, BlockNode, BlockNodeShape, BlockSpace } from './types/block.js';
+import type { RenderOptions } from './types/render-options.js';
+/**
+ * Options for adding a node
+ */
+export interface AddBlockNodeOptions {
+    /** Node label (defaults to id if not provided) */
+    label?: string;
+    /** Node shape */
+    shape?: BlockNodeShape;
+    /** Width in columns */
+    widthInColumns?: number;
+    /** Directions for block arrows */
+    directions?: BlockArrowDirection[];
+}
+/**
+ * Options for adding an edge
+ */
+export interface AddBlockEdgeOptions {
+    /** Edge label */
+    label?: string;
+    /** Edge type */
+    edgeType?: BlockEdgeType;
+}
+/**
+ * Block diagram wrapper class
+ */
+export declare class Block extends DiagramWrapper<BlockAST> {
+    private constructor();
+    /**
+     * Creates an empty block diagram
+     */
+    static create(): Block;
+    /**
+     * Creates a Block from an existing AST
+     */
+    static from(ast: BlockAST): Block;
+    /**
+     * Parses Mermaid block-beta syntax into a Block
+     */
+    static parse(text: string): Block;
+    /**
+     * Renders the block diagram to Mermaid syntax
+     */
+    render(options?: RenderOptions): string;
+    /**
+     * Creates a deep clone of this diagram
+     */
+    clone(): Block;
+    /**
+     * Sets the number of columns for the layout
+     */
+    setColumns(columns: number | 'auto'): this;
+    /**
+     * Gets the current column setting
+     */
+    getColumns(): number | 'auto' | undefined;
+    /**
+     * Adds a node to the diagram
+     */
+    addNode(id: string, options?: AddBlockNodeOptions): this;
+    /**
+     * Gets a node by id
+     */
+    getNode(id: string): BlockNode | undefined;
+    /**
+     * Finds all nodes in the diagram (including nested)
+     */
+    findNodes(): BlockNode[];
+    /**
+     * Removes a node by id
+     */
+    removeNode(id: string): this;
+    /**
+     * Gets the number of nodes
+     */
+    get nodeCount(): number;
+    /**
+     * Adds an edge between two nodes
+     */
+    addEdge(from: string, to: string, options?: AddBlockEdgeOptions): this;
+    /**
+     * Finds all edges in the diagram
+     */
+    findEdges(): BlockEdge[];
+    /**
+     * Removes an edge by id or by source/target
+     */
+    removeEdge(idOrFrom: string, to?: string): this;
+    /**
+     * Gets the number of edges
+     */
+    get edgeCount(): number;
+    /**
+     * Adds a space block for layout
+     */
+    addSpace(width?: number): this;
+    /**
+     * Finds all space blocks
+     */
+    findSpaces(): BlockSpace[];
+    /**
+     * Adds a composite (nested) block
+     */
+    addComposite(id: string, label?: string): this;
+    /**
+     * Gets a composite block by id
+     */
+    getComposite(id: string): BlockComposite | undefined;
+    /**
+     * Finds all composite blocks
+     */
+    findComposites(): BlockComposite[];
+    /**
+     * Defines a CSS class
+     */
+    defineClass(name: string, css: string): this;
+    /**
+     * Applies a class to nodes
+     */
+    applyClass(nodeIds: string | string[], className: string): this;
+    /**
+     * Applies inline styles to nodes
+     */
+    applyStyles(nodeIds: string | string[], styles: string): this;
+    /**
+     * Gets all defined classes
+     */
+    getClassDefs(): Map<string, string>;
+    /**
+     * Sets the accessibility title
+     */
+    setAccTitle(title: string): this;
+    /**
+     * Gets the accessibility title
+     */
+    getAccTitle(): string | undefined;
+    /**
+     * Sets the accessibility description
+     */
+    setAccDescr(descr: string): this;
+    /**
+     * Gets the accessibility description
+     */
+    getAccDescr(): string | undefined;
+    /**
+     * Gets the total number of elements
+     */
+    get elementCount(): number;
+}
+//# sourceMappingURL=block.d.ts.map

package/dist/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../src/block.ts"],"names":[],"mappings":"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"}

package/dist/block.js

@@ -0,0 +1,295 @@
+/**
+ * Block Diagram Wrapper Class
+ *
+ * Provides a fluent API for creating and manipulating block-beta diagrams.
+ */
+import { DiagramWrapper } from './diagram-wrapper.js';
+import { parseBlock } from './parser/block-parser.js';
+import { renderBlock } from './renderer/block-renderer.js';
+import { createEmptyBlockAST, isBlockComposite, isBlockEdge, isBlockNode, isBlockSpace, } from './types/block.js';
+/**
+ * Block diagram wrapper class
+ */
+export class Block extends DiagramWrapper {
+    constructor(ast) {
+        super(ast);
+    }
+    /**
+     * Creates an empty block diagram
+     */
+    static create() {
+        return new Block(createEmptyBlockAST());
+    }
+    /**
+     * Creates a Block from an existing AST
+     */
+    static from(ast) {
+        return new Block(ast);
+    }
+    /**
+     * Parses Mermaid block-beta syntax into a Block
+     */
+    static parse(text) {
+        return new Block(parseBlock(text));
+    }
+    /**
+     * Renders the block diagram to Mermaid syntax
+     */
+    render(options) {
+        return renderBlock(this.ast, options);
+    }
+    /**
+     * Creates a deep clone of this diagram
+     */
+    clone() {
+        return Block.parse(this.render());
+    }
+    // ============ Column Operations ============
+    /**
+     * Sets the number of columns for the layout
+     */
+    setColumns(columns) {
+        // Remove any existing column settings
+        this.ast.elements = this.ast.elements.filter((e) => !('type' in e && e.type === 'column-setting'));
+        // Add new column setting at the beginning
+        const setting = {
+            type: 'column-setting',
+            columns: columns === 'auto' ? -1 : columns,
+        };
+        this.ast.elements.unshift(setting);
+        return this;
+    }
+    /**
+     * Gets the current column setting
+     */
+    getColumns() {
+        const setting = this.ast.elements.find((e) => 'type' in e && e.type === 'column-setting');
+        if (!setting)
+            return undefined;
+        return setting.columns === -1 ? 'auto' : setting.columns;
+    }
+    // ============ Node Operations ============
+    /**
+     * Adds a node to the diagram
+     */
+    addNode(id, options) {
+        const node = {
+            id,
+            label: options?.label,
+            shape: options?.shape || 'square',
+            widthInColumns: options?.widthInColumns || 1,
+            directions: options?.directions,
+        };
+        this.ast.elements.push(node);
+        return this;
+    }
+    /**
+     * Gets a node by id
+     */
+    getNode(id) {
+        return this.findNodes().find((n) => n.id === id);
+    }
+    /**
+     * Finds all nodes in the diagram (including nested)
+     */
+    findNodes() {
+        const nodes = [];
+        const collectNodes = (elements) => {
+            for (const elem of elements) {
+                if (isBlockNode(elem)) {
+                    nodes.push(elem);
+                }
+                else if (isBlockComposite(elem)) {
+                    collectNodes(elem.children);
+                }
+            }
+        };
+        collectNodes(this.ast.elements);
+        return nodes;
+    }
+    /**
+     * Removes a node by id
+     */
+    removeNode(id) {
+        this.ast.elements = this.ast.elements.filter((e) => !isBlockNode(e) || e.id !== id);
+        return this;
+    }
+    /**
+     * Gets the number of nodes
+     */
+    get nodeCount() {
+        return this.findNodes().length;
+    }
+    // ============ Edge Operations ============
+    /**
+     * Adds an edge between two nodes
+     */
+    addEdge(from, to, options) {
+        const edge = {
+            id: `${from}-${to}`,
+            start: from,
+            end: to,
+            label: options?.label,
+            edgeType: options?.edgeType || 'arrow',
+        };
+        this.ast.elements.push(edge);
+        return this;
+    }
+    /**
+     * Finds all edges in the diagram
+     */
+    findEdges() {
+        return this.ast.elements.filter(isBlockEdge);
+    }
+    /**
+     * Removes an edge by id or by source/target
+     */
+    removeEdge(idOrFrom, to) {
+        if (to) {
+            // Remove by source/target
+            this.ast.elements = this.ast.elements.filter((e) => !isBlockEdge(e) || !(e.start === idOrFrom && e.end === to));
+        }
+        else {
+            // Remove by id
+            this.ast.elements = this.ast.elements.filter((e) => !isBlockEdge(e) || e.id !== idOrFrom);
+        }
+        return this;
+    }
+    /**
+     * Gets the number of edges
+     */
+    get edgeCount() {
+        return this.findEdges().length;
+    }
+    // ============ Space Operations ============
+    /**
+     * Adds a space block for layout
+     */
+    addSpace(width = 1) {
+        const space = {
+            id: `space_${Date.now()}`,
+            type: 'space',
+            width,
+        };
+        this.ast.elements.push(space);
+        return this;
+    }
+    /**
+     * Finds all space blocks
+     */
+    findSpaces() {
+        return this.ast.elements.filter(isBlockSpace);
+    }
+    // ============ Composite Block Operations ============
+    /**
+     * Adds a composite (nested) block
+     */
+    addComposite(id, label) {
+        const composite = {
+            id,
+            type: 'composite',
+            label,
+            children: [],
+        };
+        this.ast.elements.push(composite);
+        return this;
+    }
+    /**
+     * Gets a composite block by id
+     */
+    getComposite(id) {
+        return this.ast.elements.find((e) => isBlockComposite(e) && e.id === id);
+    }
+    /**
+     * Finds all composite blocks
+     */
+    findComposites() {
+        return this.ast.elements.filter(isBlockComposite);
+    }
+    // ============ Style Operations ============
+    /**
+     * Defines a CSS class
+     */
+    defineClass(name, css) {
+        const classDef = {
+            type: 'classDef',
+            id: name,
+            css,
+        };
+        this.ast.classDefs.set(name, css);
+        this.ast.elements.push(classDef);
+        return this;
+    }
+    /**
+     * Applies a class to nodes
+     */
+    applyClass(nodeIds, className) {
+        const ids = Array.isArray(nodeIds) ? nodeIds.join(', ') : nodeIds;
+        const applyClass = {
+            type: 'applyClass',
+            id: ids,
+            styleClass: className,
+        };
+        for (const nodeId of Array.isArray(nodeIds) ? nodeIds : [nodeIds]) {
+            this.ast.classAssignments.set(nodeId, className);
+        }
+        this.ast.elements.push(applyClass);
+        return this;
+    }
+    /**
+     * Applies inline styles to nodes
+     */
+    applyStyles(nodeIds, styles) {
+        const ids = Array.isArray(nodeIds) ? nodeIds.join(', ') : nodeIds;
+        const applyStyles = {
+            type: 'applyStyles',
+            id: ids,
+            stylesStr: styles,
+        };
+        for (const nodeId of Array.isArray(nodeIds) ? nodeIds : [nodeIds]) {
+            this.ast.styleAssignments.set(nodeId, styles);
+        }
+        this.ast.elements.push(applyStyles);
+        return this;
+    }
+    /**
+     * Gets all defined classes
+     */
+    getClassDefs() {
+        return new Map(this.ast.classDefs);
+    }
+    // ============ Accessibility ============
+    /**
+     * Sets the accessibility title
+     */
+    setAccTitle(title) {
+        this.ast.accTitle = title;
+        return this;
+    }
+    /**
+     * Gets the accessibility title
+     */
+    getAccTitle() {
+        return this.ast.accTitle;
+    }
+    /**
+     * Sets the accessibility description
+     */
+    setAccDescr(descr) {
+        this.ast.accDescr = descr;
+        return this;
+    }
+    /**
+     * Gets the accessibility description
+     */
+    getAccDescr() {
+        return this.ast.accDescr;
+    }
+    // ============ Element Count ============
+    /**
+     * Gets the total number of elements
+     */
+    get elementCount() {
+        return this.ast.elements.length;
+    }
+}