@zombie-mermaid/mermaid-parser 3.1.0 → 4.0.0

package/dist/index.d.cts

@@ -1,6 +1,8 @@
 import { Direction } from '@zombie-mermaid/core';
+import { MermaidGraph } from '@zombie-mermaid/core';
 import { NodeInteraction } from '@zombie-mermaid/core';
 import { NodeShape } from '@zombie-mermaid/core';
+import { Point } from '@zombie-mermaid/core';
 import { Statement } from '@zombie-mermaid/core';
 import { StyleDirectives } from '@zombie-mermaid/core';
 
@@ -11,6 +13,8 @@ export declare interface Activation {
     topY: number;
     bottomY: number;
     width: number;
+    /** Nesting level on this actor's lifeline: 0 for the outermost bar, 1 for a bar opened while one is already active, and so on */
+    depth: number;
 }
 
 export declare interface ActivationCheckResult {
@@ -88,6 +92,54 @@ export declare interface Actor {
     destroyedAt?: number;
 }
 
+export declare interface ArchitectureDiagram {
+    groups: ArchitectureGroup[];
+    services: ArchitectureService[];
+    junctions: ArchitectureJunction[];
+    edges: ArchitectureEdge[];
+}
+
+export declare interface ArchitectureEdge {
+    source: string;
+    sourcePort: ArchitecturePort;
+    /** `{group}` modifier: the edge attaches to the enclosing group's border. */
+    sourceGroup: boolean;
+    target: string;
+    targetPort: ArchitecturePort;
+    targetGroup: boolean;
+    /** `<--` / `<-->`: arrowhead at the source end. */
+    arrowStart: boolean;
+    /** `-->` / `<-->`: arrowhead at the target end. */
+    arrowEnd: boolean;
+}
+
+export declare interface ArchitectureGroup {
+    id: string;
+    /** Icon name from `(icon)`; kept for consumers, not drawn (see to-graph). */
+    icon?: string;
+    /** `[Title]`; falls back to the id. */
+    title: string;
+    /** Enclosing group id, from `in <parent>`. */
+    parent?: string;
+}
+
+export declare interface ArchitectureJunction {
+    id: string;
+    parent?: string;
+}
+
+/** A port on a service/junction: left, right, top, bottom. */
+export declare type ArchitecturePort = 'L' | 'R' | 'T' | 'B';
+
+export declare interface ArchitectureService {
+    id: string;
+    icon?: string;
+    title: string;
+    parent?: string;
+}
+
+export declare function architectureToGraph(diagram: ArchitectureDiagram): MermaidGraph;
+
 export declare interface AxisTick {
     /** Label text for this tick */
     label: string;
@@ -120,6 +172,111 @@ export declare interface Block {
     }>;
 }
 
+export declare interface C4Boundary {
+    alias: string;
+    label: string;
+    /** Boundary type (`Boundary(a, "x", "type")`) or deployment node type. */
+    type?: string;
+    description?: string;
+    /** Aliases of elements declared directly inside this boundary. */
+    elementAliases: string[];
+    children: C4Boundary[];
+}
+
+/** A boundary's type line (`[ENTERPRISE]`, `[Ubuntu]`), when it has a type. */
+export declare function c4BoundaryTypeLine(b: C4Boundary): string | undefined;
+
+export declare interface C4Diagram {
+    variant: C4Variant;
+    /**
+     * Top-level layout direction. Never set by the parser (C4 sources have no
+     * direction statement); only `RenderOptions.direction` sets it, via
+     * `withDirectionOverride`. Unset lays out top-to-bottom.
+     */
+    direction?: Direction;
+    title?: string;
+    /** Every element in declaration order, wherever it is nested. */
+    elements: C4Element[];
+    /** Top-level boundaries; elements outside any boundary are not listed. */
+    boundaries: C4Boundary[];
+    relationships: C4Relationship[];
+}
+
+export declare interface C4Element {
+    alias: string;
+    kind: C4ElementKind;
+    shape: C4ElementShape;
+    /** `*_Ext` variants: outside the system being described. */
+    external: boolean;
+    label: string;
+    technology?: string;
+    description?: string;
+}
+
+export declare type C4ElementKind = 'person' | 'system' | 'container' | 'component';
+
+/** Visual variant of an element: plain box, database cylinder, or queue. */
+export declare type C4ElementShape = 'default' | 'db' | 'queue';
+
+/**
+ * Layout placement hint carried by `Rel_U`/`Rel_D`/`Rel_L`/`Rel_R` (and their
+ * long-form aliases): where `to` should sit relative to `from`. Plain `Rel`,
+ * `BiRel`, `RelIndex` and `Rel_Back` carry none.
+ */
+export declare type C4LayoutHint = 'up' | 'down' | 'left' | 'right';
+
+/**
+ * How a relationship constrains placement. `source` is meant to sit before
+ * `target` along `axis`: above it for `'vertical'`, left of it for
+ * `'horizontal'`. `Rel_U`/`Rel_L` reverse the pair (the target sits above /
+ * left of the source); plain `Rel` is a vertical hint, since C4 diagrams flow
+ * top to bottom by default.
+ */
+export declare interface C4Placement {
+    source: string;
+    target: string;
+    axis: 'vertical' | 'horizontal';
+    /** True when the hint came from an explicit `Rel_U/D/L/R`. */
+    explicit: boolean;
+}
+
+export declare function c4Placement(rel: C4Relationship): C4Placement;
+
+export declare interface C4Relationship {
+    from: string;
+    to: string;
+    label: string;
+    technology?: string;
+    /** `BiRel`: arrowheads at both ends. */
+    bidirectional: boolean;
+    /**
+     * `Rel_Back`: the arrowhead points at `from` instead of `to`. `from`/`to`
+     * stay as declared, so layout and placement hints still follow them.
+     */
+    reversed?: boolean;
+    /** `RelIndex(n, ...)` in C4Dynamic diagrams. */
+    index?: string;
+    /** Placement hint from a directional `Rel_*` macro; see `C4LayoutHint`. */
+    layout?: C4LayoutHint;
+}
+
+/**
+ * The text lines of a relationship label: the label itself (prefixed with its
+ * sequence number in a C4Dynamic diagram), then the technology in brackets on its
+ * own line. Empty when the relationship has neither.
+ */
+export declare function c4RelLabelLines(rel: C4Relationship): string[];
+
+/**
+ * The bracketed type line under an element's name, as Mermaid draws it:
+ * `[Person]`, `[Software System]`, `[Container: PostgreSQL]`. External,
+ * database and queue variants share their base kind's line; the fill and the
+ * shape tell them apart.
+ */
+export declare function c4TypeLine(el: C4Element): string;
+
+export declare type C4Variant = 'context' | 'container' | 'component' | 'dynamic' | 'deployment';
+
 /**
  * Cardinality notation (crow's foot):
  *   'one'       ||  ||  exactly one
@@ -316,7 +473,7 @@ export declare function formatClassMember(m: ClassMember): string;
  * Get the hex color for a series index.
  * Index 0 returns the accent color as-is.
  * Index 1+ alternate between darker and lighter shades of the same hue
- * with subtle hue drift (±8-12° per tier) to stay in the same family.
+ * with subtle hue drift (-8° per tier for darker, -12° for lighter) to stay in the same family.
  *
  * When `bgColor` is provided, shade direction adapts to the background:
  *   - Light bg: odd = darker, even = lighter (default)
@@ -435,6 +592,12 @@ export declare interface Note {
     afterIndex: number;
 }
 
+/**
+ * Parse a Mermaid architecture diagram.
+ * Expects the first statement to be the `architecture-beta` header.
+ */
+export declare function parseArchitecture(lines: Statement[]): ArchitectureDiagram;
+
 /**
  * Split the text after the `box` keyword into a colour and a label, per
  * Mermaid's `parseBoxData`: the leading word (or function call) is the
@@ -447,6 +610,13 @@ export declare function parseBoxHeader(header: string): {
     label: string;
 };
 
+/**
+ * Parse a Mermaid C4 diagram. Expects the first statement to be a
+ * `C4Context` / `C4Container` / `C4Component` / `C4Dynamic` /
+ * `C4Deployment` header.
+ */
+export declare function parseC4Diagram(lines: Statement[]): C4Diagram;
+
 /**
  * Parse a Mermaid class diagram.
  * Expects the first line to be "classDiagram".
@@ -580,12 +750,79 @@ export declare interface PositionedBlock {
     }>;
 }
 
+export declare interface PositionedC4Boundary {
+    alias: string;
+    label: string;
+    type?: string;
+    description?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Nesting depth, 0 for a top-level boundary. */
+    depth: number;
+    /** Centre line of the title, below the frame's top edge (Mermaid's layout). */
+    labelY?: number;
+    /** Centre line of the `[type]` text, below the frame's top edge. */
+    typeY?: number;
+    /** Centre line of the description (deployment nodes), below the top edge. */
+    descrY?: number;
+}
+
+export declare interface PositionedC4Diagram {
+    variant: C4Variant;
+    title?: string;
+    width: number;
+    height: number;
+    /** Where the title baseline sits (centre x, y), when there is a title. */
+    titlePosition?: Point;
+    elements: PositionedC4Element[];
+    /** Outer boundaries first, so inner ones paint on top. */
+    boundaries: PositionedC4Boundary[];
+    relationships: PositionedC4Relationship[];
+}
+
+export declare interface PositionedC4Element extends C4Element {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Name wrapped to the box width, one entry per line. */
+    nameLines: string[];
+    /** Description wrapped to the box width, one entry per line. */
+    descriptionLines: string[];
+}
+
+export declare interface PositionedC4Relationship extends C4Relationship {
+    /** The start and end of the line (a straight chord when `curve` is unset). */
+    points: Point[];
+    /** Control point of a quadratic curve from the first to the last point. */
+    curve?: Point;
+    /** Centre of the label block, when the relationship has label text. */
+    labelPosition?: Point;
+    /** Centre x of the `[technology]` line, which Mermaid lays out on its own. */
+    technologyX?: number;
+}
+
 export declare interface PositionedClassDiagram {
     width: number;
     height: number;
     classes: PositionedClassNode[];
     relationships: PositionedClassRelationship[];
     notes: PositionedClassNote[];
+    /** Namespace frames, drawn behind their member classes */
+    namespaces: PositionedClassNamespace[];
+}
+
+/** A `namespace Name { ... }` block's frame, in diagram coordinates */
+export declare interface PositionedClassNamespace {
+    name: string;
+    /** Ids of the member classes the frame encloses */
+    classIds: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
 }
 
 export declare interface PositionedClassNode {
@@ -834,6 +1071,9 @@ export declare interface SequenceDiagram {
  */
 export declare function toBlockType(value: string): Block['type'];
 
+/** Greedy word wrap; a word longer than `width` stays on its own line. */
+export declare function wrapC4Text(text: string, width: number): string[];
+
 /** Axis configuration — categorical (labels) or numeric (range) */
 export declare interface XYAxis {
     /** Optional axis title/label */

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { Direction } from '@zombie-mermaid/core';
+import { MermaidGraph } from '@zombie-mermaid/core';
 import { NodeInteraction } from '@zombie-mermaid/core';
 import { NodeShape } from '@zombie-mermaid/core';
+import { Point } from '@zombie-mermaid/core';
 import { Statement } from '@zombie-mermaid/core';
 import { StyleDirectives } from '@zombie-mermaid/core';
 
@@ -11,6 +13,8 @@ export declare interface Activation {
     topY: number;
     bottomY: number;
     width: number;
+    /** Nesting level on this actor's lifeline: 0 for the outermost bar, 1 for a bar opened while one is already active, and so on */
+    depth: number;
 }
 
 export declare interface ActivationCheckResult {
@@ -88,6 +92,54 @@ export declare interface Actor {
     destroyedAt?: number;
 }
 
+export declare interface ArchitectureDiagram {
+    groups: ArchitectureGroup[];
+    services: ArchitectureService[];
+    junctions: ArchitectureJunction[];
+    edges: ArchitectureEdge[];
+}
+
+export declare interface ArchitectureEdge {
+    source: string;
+    sourcePort: ArchitecturePort;
+    /** `{group}` modifier: the edge attaches to the enclosing group's border. */
+    sourceGroup: boolean;
+    target: string;
+    targetPort: ArchitecturePort;
+    targetGroup: boolean;
+    /** `<--` / `<-->`: arrowhead at the source end. */
+    arrowStart: boolean;
+    /** `-->` / `<-->`: arrowhead at the target end. */
+    arrowEnd: boolean;
+}
+
+export declare interface ArchitectureGroup {
+    id: string;
+    /** Icon name from `(icon)`; kept for consumers, not drawn (see to-graph). */
+    icon?: string;
+    /** `[Title]`; falls back to the id. */
+    title: string;
+    /** Enclosing group id, from `in <parent>`. */
+    parent?: string;
+}
+
+export declare interface ArchitectureJunction {
+    id: string;
+    parent?: string;
+}
+
+/** A port on a service/junction: left, right, top, bottom. */
+export declare type ArchitecturePort = 'L' | 'R' | 'T' | 'B';
+
+export declare interface ArchitectureService {
+    id: string;
+    icon?: string;
+    title: string;
+    parent?: string;
+}
+
+export declare function architectureToGraph(diagram: ArchitectureDiagram): MermaidGraph;
+
 export declare interface AxisTick {
     /** Label text for this tick */
     label: string;
@@ -120,6 +172,111 @@ export declare interface Block {
     }>;
 }
 
+export declare interface C4Boundary {
+    alias: string;
+    label: string;
+    /** Boundary type (`Boundary(a, "x", "type")`) or deployment node type. */
+    type?: string;
+    description?: string;
+    /** Aliases of elements declared directly inside this boundary. */
+    elementAliases: string[];
+    children: C4Boundary[];
+}
+
+/** A boundary's type line (`[ENTERPRISE]`, `[Ubuntu]`), when it has a type. */
+export declare function c4BoundaryTypeLine(b: C4Boundary): string | undefined;
+
+export declare interface C4Diagram {
+    variant: C4Variant;
+    /**
+     * Top-level layout direction. Never set by the parser (C4 sources have no
+     * direction statement); only `RenderOptions.direction` sets it, via
+     * `withDirectionOverride`. Unset lays out top-to-bottom.
+     */
+    direction?: Direction;
+    title?: string;
+    /** Every element in declaration order, wherever it is nested. */
+    elements: C4Element[];
+    /** Top-level boundaries; elements outside any boundary are not listed. */
+    boundaries: C4Boundary[];
+    relationships: C4Relationship[];
+}
+
+export declare interface C4Element {
+    alias: string;
+    kind: C4ElementKind;
+    shape: C4ElementShape;
+    /** `*_Ext` variants: outside the system being described. */
+    external: boolean;
+    label: string;
+    technology?: string;
+    description?: string;
+}
+
+export declare type C4ElementKind = 'person' | 'system' | 'container' | 'component';
+
+/** Visual variant of an element: plain box, database cylinder, or queue. */
+export declare type C4ElementShape = 'default' | 'db' | 'queue';
+
+/**
+ * Layout placement hint carried by `Rel_U`/`Rel_D`/`Rel_L`/`Rel_R` (and their
+ * long-form aliases): where `to` should sit relative to `from`. Plain `Rel`,
+ * `BiRel`, `RelIndex` and `Rel_Back` carry none.
+ */
+export declare type C4LayoutHint = 'up' | 'down' | 'left' | 'right';
+
+/**
+ * How a relationship constrains placement. `source` is meant to sit before
+ * `target` along `axis`: above it for `'vertical'`, left of it for
+ * `'horizontal'`. `Rel_U`/`Rel_L` reverse the pair (the target sits above /
+ * left of the source); plain `Rel` is a vertical hint, since C4 diagrams flow
+ * top to bottom by default.
+ */
+export declare interface C4Placement {
+    source: string;
+    target: string;
+    axis: 'vertical' | 'horizontal';
+    /** True when the hint came from an explicit `Rel_U/D/L/R`. */
+    explicit: boolean;
+}
+
+export declare function c4Placement(rel: C4Relationship): C4Placement;
+
+export declare interface C4Relationship {
+    from: string;
+    to: string;
+    label: string;
+    technology?: string;
+    /** `BiRel`: arrowheads at both ends. */
+    bidirectional: boolean;
+    /**
+     * `Rel_Back`: the arrowhead points at `from` instead of `to`. `from`/`to`
+     * stay as declared, so layout and placement hints still follow them.
+     */
+    reversed?: boolean;
+    /** `RelIndex(n, ...)` in C4Dynamic diagrams. */
+    index?: string;
+    /** Placement hint from a directional `Rel_*` macro; see `C4LayoutHint`. */
+    layout?: C4LayoutHint;
+}
+
+/**
+ * The text lines of a relationship label: the label itself (prefixed with its
+ * sequence number in a C4Dynamic diagram), then the technology in brackets on its
+ * own line. Empty when the relationship has neither.
+ */
+export declare function c4RelLabelLines(rel: C4Relationship): string[];
+
+/**
+ * The bracketed type line under an element's name, as Mermaid draws it:
+ * `[Person]`, `[Software System]`, `[Container: PostgreSQL]`. External,
+ * database and queue variants share their base kind's line; the fill and the
+ * shape tell them apart.
+ */
+export declare function c4TypeLine(el: C4Element): string;
+
+export declare type C4Variant = 'context' | 'container' | 'component' | 'dynamic' | 'deployment';
+
 /**
  * Cardinality notation (crow's foot):
  *   'one'       ||  ||  exactly one
@@ -316,7 +473,7 @@ export declare function formatClassMember(m: ClassMember): string;
  * Get the hex color for a series index.
  * Index 0 returns the accent color as-is.
  * Index 1+ alternate between darker and lighter shades of the same hue
- * with subtle hue drift (±8-12° per tier) to stay in the same family.
+ * with subtle hue drift (-8° per tier for darker, -12° for lighter) to stay in the same family.
  *
  * When `bgColor` is provided, shade direction adapts to the background:
  *   - Light bg: odd = darker, even = lighter (default)
@@ -435,6 +592,12 @@ export declare interface Note {
     afterIndex: number;
 }
 
+/**
+ * Parse a Mermaid architecture diagram.
+ * Expects the first statement to be the `architecture-beta` header.
+ */
+export declare function parseArchitecture(lines: Statement[]): ArchitectureDiagram;
+
 /**
  * Split the text after the `box` keyword into a colour and a label, per
  * Mermaid's `parseBoxData`: the leading word (or function call) is the
@@ -447,6 +610,13 @@ export declare function parseBoxHeader(header: string): {
     label: string;
 };
 
+/**
+ * Parse a Mermaid C4 diagram. Expects the first statement to be a
+ * `C4Context` / `C4Container` / `C4Component` / `C4Dynamic` /
+ * `C4Deployment` header.
+ */
+export declare function parseC4Diagram(lines: Statement[]): C4Diagram;
+
 /**
  * Parse a Mermaid class diagram.
  * Expects the first line to be "classDiagram".
@@ -580,12 +750,79 @@ export declare interface PositionedBlock {
     }>;
 }
 
+export declare interface PositionedC4Boundary {
+    alias: string;
+    label: string;
+    type?: string;
+    description?: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Nesting depth, 0 for a top-level boundary. */
+    depth: number;
+    /** Centre line of the title, below the frame's top edge (Mermaid's layout). */
+    labelY?: number;
+    /** Centre line of the `[type]` text, below the frame's top edge. */
+    typeY?: number;
+    /** Centre line of the description (deployment nodes), below the top edge. */
+    descrY?: number;
+}
+
+export declare interface PositionedC4Diagram {
+    variant: C4Variant;
+    title?: string;
+    width: number;
+    height: number;
+    /** Where the title baseline sits (centre x, y), when there is a title. */
+    titlePosition?: Point;
+    elements: PositionedC4Element[];
+    /** Outer boundaries first, so inner ones paint on top. */
+    boundaries: PositionedC4Boundary[];
+    relationships: PositionedC4Relationship[];
+}
+
+export declare interface PositionedC4Element extends C4Element {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Name wrapped to the box width, one entry per line. */
+    nameLines: string[];
+    /** Description wrapped to the box width, one entry per line. */
+    descriptionLines: string[];
+}
+
+export declare interface PositionedC4Relationship extends C4Relationship {
+    /** The start and end of the line (a straight chord when `curve` is unset). */
+    points: Point[];
+    /** Control point of a quadratic curve from the first to the last point. */
+    curve?: Point;
+    /** Centre of the label block, when the relationship has label text. */
+    labelPosition?: Point;
+    /** Centre x of the `[technology]` line, which Mermaid lays out on its own. */
+    technologyX?: number;
+}
+
 export declare interface PositionedClassDiagram {
     width: number;
     height: number;
     classes: PositionedClassNode[];
     relationships: PositionedClassRelationship[];
     notes: PositionedClassNote[];
+    /** Namespace frames, drawn behind their member classes */
+    namespaces: PositionedClassNamespace[];
+}
+
+/** A `namespace Name { ... }` block's frame, in diagram coordinates */
+export declare interface PositionedClassNamespace {
+    name: string;
+    /** Ids of the member classes the frame encloses */
+    classIds: string[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
 }
 
 export declare interface PositionedClassNode {
@@ -834,6 +1071,9 @@ export declare interface SequenceDiagram {
  */
 export declare function toBlockType(value: string): Block['type'];
 
+/** Greedy word wrap; a word longer than `width` stays on its own line. */
+export declare function wrapC4Text(text: string, width: number): string[];
+
 /** Axis configuration — categorical (labels) or numeric (range) */
 export declare interface XYAxis {
     /** Optional axis title/label */