diagrams-js 0.5.1 → 0.6.0

package/dist/index.d.ts

@@ -46,6 +46,10 @@ interface Cluster {
    * Changes here will be reflected in the rendered output.
    */
   clusterAttrs: Record<string, string>;
+  /** CSS class(es) to add to the rendered SVG element */
+  className: string | undefined;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs: Record<string, string>;
   /** The diagram this cluster belongs to */
   diagram: Diagram;
   /**
@@ -71,9 +75,10 @@ interface Cluster {
   /**
    * Create a nested cluster within this one
    * @param label - The label for the nested cluster
+   * @param options - Optional cluster configuration
    * @returns The created nested cluster
    */
-  cluster(label: string): Cluster;
+  cluster(label: string, options?: ClusterOptions): Cluster;
   /**
    * Get all nodes in this cluster
    * @returns Map of node IDs to node data
@@ -99,12 +104,19 @@ interface Cluster {
    * @returns The diagram this cluster belongs to
    */
   getDiagram(): Diagram;
+  /**
+   * Get the SVG element for this cluster.
+   * If no svg argument is provided, queries the current document.
+   * @param svg - Optional SVG string or Element to query within
+   * @returns The SVG element, or null if not found
+   */
+  getElement(svg?: string | Element): Element | null;
 }
 /**
  * Create a new cluster
  * @param label - The display label for the cluster
  * @param direction - Layout direction for the cluster
- * @param graphAttr - Optional Graphviz attributes
+ * @param options - Optional Graphviz attributes or ClusterOptions
  * @param diagram - The diagram this cluster belongs to
  * @param parent - Optional parent cluster for nesting
  * @returns A new Cluster instance
@@ -114,148 +126,7 @@ interface Cluster {
  * cluster.add(Server("Web"));
  * ```
  */
-declare function Cluster(label?: string, direction?: "TB" | "BT" | "LR" | "RL", graphAttr?: Record<string, string>, diagram?: Diagram, parent?: Cluster): Cluster;
-//#endregion
-//#region src/types.d.ts
-/**
- * Theme definitions for diagram styling.
- * Each theme defines cluster background colors (by depth), border color, and edge color.
- */
-declare const THEMES: {
-  /** Pastel colors - soft blues, greens, and purples */readonly pastel: {
-    readonly bgcolor: readonly ["#E5F5FD", "#EBF3E7", "#ECE8F6", "#FDF7E3"];
-    readonly pencolor: "#AEB6BE";
-    readonly edgecolor: "#7B8894";
-  }; /** Neutral grayscale theme */
-  readonly neutral: {
-    readonly bgcolor: readonly ["#F8F9FA", "#F1F3F5", "#E9ECEF", "#DEE2E6"];
-    readonly pencolor: "#ADB5BD";
-    readonly edgecolor: "#495057";
-  }; /** Blue color palette */
-  readonly blues: {
-    readonly bgcolor: readonly ["#E7F5FF", "#D0EBFF", "#A5D8FF", "#74C0FC"];
-    readonly pencolor: "#339AF0";
-    readonly edgecolor: "#1971C2";
-  }; /** Green color palette */
-  readonly greens: {
-    readonly bgcolor: readonly ["#EBFBEE", "#D3F9D8", "#B2F2BB", "#8CE99A"];
-    readonly pencolor: "#40C057";
-    readonly edgecolor: "#2F9E44";
-  }; /** Orange/warm color palette */
-  readonly orange: {
-    readonly bgcolor: readonly ["#FFF4E6", "#FFE8CC", "#FFD8A8", "#FFC078"];
-    readonly pencolor: "#FD7E14";
-    readonly edgecolor: "#E8590C";
-  };
-};
-/** Available theme names */
-type ThemeName = keyof typeof THEMES;
-/** Theme configuration type */
-type ThemeConfig = (typeof THEMES)[ThemeName];
-/**
- * Options for creating a diagram
- * @example
- * ```typescript
- * const options: DiagramOptions = {
- *   name: "My Architecture",
- *   direction: "TB",
- *   theme: "pastel",
- *   curvestyle: "ortho"
- * };
- * const diagram = Diagram("", options);
- * ```
- */
-interface DiagramOptions {
-  /** The name/title of the diagram (overrides the name parameter) */
-  name?: string;
-  /** The filename used when saving (defaults to name converted to snake_case) */
-  filename?: string;
-  /** Layout direction: TB (top-bottom), BT (bottom-top), LR (left-right), RL (right-left) */
-  direction?: "TB" | "BT" | "LR" | "RL";
-  /** Edge curve style: ortho (orthogonal), curved, spline, or polyline */
-  curvestyle?: "ortho" | "curved" | "spline" | "polyline";
-  /** Whether to automatically prefix node labels with their type */
-  autolabel?: boolean;
-  /** Whether to create a strict graph (no duplicate edges) */
-  strict?: boolean;
-  /** Color theme for the diagram */
-  theme?: ThemeName;
-  /** Graph-level Graphviz attributes */
-  graphAttr?: Record<string, string>;
-  /** Default node Graphviz attributes */
-  nodeAttr?: Record<string, string>;
-  /** Default edge Graphviz attributes */
-  edgeAttr?: Record<string, string>;
-  /** Custom plugin registry (creates new one if not provided) */
-  pluginRegistry?: PluginRegistry;
-}
-/**
- * Options for rendering a diagram
- * @example
- * ```typescript
- * const svg = await diagram.render({ format: "svg" });
- * const png = await diagram.render({ format: "png", scale: 2 });
- * ```
- */
-interface RenderOptions {
-  /** Output format: svg, png, jpg, dot, or json */
-  format?: "svg" | "png" | "jpg" | "dot" | "json";
-  /** Output filename */
-  filename?: string;
-  /** Output width in pixels (for PNG/JPG) */
-  width?: number;
-  /** Output height in pixels (for PNG/JPG) */
-  height?: number;
-  /** Scale factor for output (for PNG/JPG, default: 2) */
-  scale?: number;
-  /** Whether to inject icons into SVG output */
-  injectIcons?: boolean;
-  /** Whether to embed diagram metadata into SVG output (default: true) */
-  embedData?: boolean;
-  /** Whether to return output as data URL */
-  dataUrl?: boolean;
-}
-/**
- * Options for creating an edge
- * @example
- * ```typescript
- * const edge = Edge({ label: "HTTP", color: "blue", style: "dashed" });
- * ```
- */
-interface EdgeOptions {
-  /** The source node (internal use) */
-  node?: Node;
-  /** Whether this is a forward edge */
-  forward?: boolean;
-  /** Whether this is a reverse edge */
-  reverse?: boolean;
-  /** Edge label text */
-  label?: string;
-  /** Edge color */
-  color?: string;
-  /** Edge style (solid, dashed, dotted, etc.) */
-  style?: string;
-  /** Additional Graphviz edge attributes */
-  [key: string]: unknown;
-}
-/**
- * Options for creating a node
- * @example
- * ```typescript
- * const node = Node("My Service", { shape: "box", color: "blue" });
- * ```
- */
-interface NodeOptions {
-  /** Custom unique identifier for the node */
-  nodeId?: string;
-  /** @internal Node type for autolabel */
-  ["~type"]?: string;
-  /** @internal Icon data URL */
-  ["~iconDataUrl"]?: string;
-  /** Additional Graphviz node attributes */
-  [key: string]: unknown;
-}
-type Yaml = typeof yaml_d_exports;
+declare function Cluster(label?: string, direction?: "TB" | "BT" | "LR" | "RL", options?: Record<string, string> | ClusterOptions, diagram?: Diagram, parent?: Cluster): Cluster;
 //#endregion
 //#region src/Edge.d.ts
 /**
@@ -289,6 +160,14 @@ interface Edge {
    * Changes here will be reflected in the attrs getter.
    */
   edgeAttrs: Record<string, string>;
+  /** CSS class(es) to add to the rendered SVG element */
+  className: string | undefined;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs: Record<string, string>;
+  /** @internal Source node ID (set during connection) */
+  ["~fromNodeId"]: string;
+  /** @internal Target node ID (set during connection) */
+  ["~toNodeId"]: string;
   /**
    * Connect this edge to a node or merge with another edge
    * @param target - The target node or edge to merge
@@ -301,6 +180,13 @@ interface Edge {
    * @returns The source node or this edge
    */
   from(target: Node | Edge): Node | Edge;
+  /**
+   * Get the SVG element for this edge.
+   * If no svg argument is provided, queries the current document.
+   * @param svg - Optional SVG string or Element to query within
+   * @returns The SVG element, or null if not found
+   */
+  getElement(svg?: string | Element): Element | null;
 }
 /**
  * Create a new edge
@@ -392,6 +278,10 @@ interface Node {
   type?: string;
   /** The specific resource type (e.g., "EC2", "S3", "RDS") */
   resource?: string;
+  /** CSS class(es) to add to the rendered SVG element */
+  className: string | undefined;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs: Record<string, string>;
   /** @internal */
   ["~id"]: string;
   /** @internal */
@@ -462,6 +352,13 @@ interface Node {
    */
   with(edge: Edge, target: Node): Node;
   with(edge: Edge, targets: Node[]): Node[];
+  /**
+   * Get the SVG element for this node.
+   * If no svg argument is provided, queries the current document.
+   * @param svg - Optional SVG string or Element to query within
+   * @returns The SVG element, or null if not found
+   */
+  getElement(svg?: string | Element): Element | null;
   /**
    * Internal method to connect this node to another with an edge
    * @param target - The target node
@@ -682,6 +579,7 @@ declare enum HookEvent {
   AFTER_EXPORT = "after:export",
   BEFORE_RENDER = "before:render",
   AFTER_RENDER = "after:render",
+  AFTER_LAYOUT = "after:layout",
   BEFORE_SERIALIZE = "before:serialize",
   AFTER_DESERIALIZE = "after:deserialize",
   NODE_CREATE = "node:create",
@@ -784,6 +682,173 @@ declare class RuntimeError extends PluginError {
   constructor(pluginName: string, requiredRuntimes: RuntimeSupport, currentRuntime: string);
 }
 //#endregion
+//#region src/types.d.ts
+/**
+ * Theme definitions for diagram styling.
+ * Each theme defines cluster background colors (by depth), border color, and edge color.
+ */
+declare const THEMES: {
+  /** Pastel colors - soft blues, greens, and purples */readonly pastel: {
+    readonly bgcolor: readonly ["#E5F5FD", "#EBF3E7", "#ECE8F6", "#FDF7E3"];
+    readonly pencolor: "#AEB6BE";
+    readonly edgecolor: "#7B8894";
+  }; /** Neutral grayscale theme */
+  readonly neutral: {
+    readonly bgcolor: readonly ["#F8F9FA", "#F1F3F5", "#E9ECEF", "#DEE2E6"];
+    readonly pencolor: "#ADB5BD";
+    readonly edgecolor: "#495057";
+  }; /** Blue color palette */
+  readonly blues: {
+    readonly bgcolor: readonly ["#E7F5FF", "#D0EBFF", "#A5D8FF", "#74C0FC"];
+    readonly pencolor: "#339AF0";
+    readonly edgecolor: "#1971C2";
+  }; /** Green color palette */
+  readonly greens: {
+    readonly bgcolor: readonly ["#EBFBEE", "#D3F9D8", "#B2F2BB", "#8CE99A"];
+    readonly pencolor: "#40C057";
+    readonly edgecolor: "#2F9E44";
+  }; /** Orange/warm color palette */
+  readonly orange: {
+    readonly bgcolor: readonly ["#FFF4E6", "#FFE8CC", "#FFD8A8", "#FFC078"];
+    readonly pencolor: "#FD7E14";
+    readonly edgecolor: "#E8590C";
+  };
+};
+/** Available theme names */
+type ThemeName = keyof typeof THEMES;
+/** Theme configuration type */
+type ThemeConfig = (typeof THEMES)[ThemeName];
+/**
+ * Options for creating a diagram
+ * @example
+ * ```typescript
+ * const options: DiagramOptions = {
+ *   name: "My Architecture",
+ *   direction: "TB",
+ *   theme: "pastel",
+ *   curvestyle: "ortho"
+ * };
+ * const diagram = Diagram("", options);
+ * ```
+ */
+interface DiagramOptions {
+  /** The name/title of the diagram (overrides the name parameter) */
+  name?: string;
+  /** The filename used when saving (defaults to name converted to snake_case) */
+  filename?: string;
+  /** Layout direction: TB (top-bottom), BT (bottom-top), LR (left-right), RL (right-left) */
+  direction?: "TB" | "BT" | "LR" | "RL";
+  /** Edge curve style: ortho (orthogonal), curved, spline, or polyline */
+  curvestyle?: "ortho" | "curved" | "spline" | "polyline";
+  /** Whether to automatically prefix node labels with their type */
+  autolabel?: boolean;
+  /** Whether to create a strict graph (no duplicate edges) */
+  strict?: boolean;
+  /** Color theme for the diagram */
+  theme?: ThemeName;
+  /** Graph-level Graphviz attributes */
+  graphAttr?: Record<string, string>;
+  /** Default node Graphviz attributes */
+  nodeAttr?: Record<string, string>;
+  /** Default edge Graphviz attributes */
+  edgeAttr?: Record<string, string>;
+  /** Custom plugin registry (creates new one if not provided) */
+  pluginRegistry?: PluginRegistry;
+}
+/**
+ * Options for rendering a diagram
+ * @example
+ * ```typescript
+ * const svg = await diagram.render({ format: "svg" });
+ * const png = await diagram.render({ format: "png", scale: 2 });
+ * ```
+ */
+interface RenderOptions {
+  /** Output format: svg, png, jpg, dot, or json */
+  format?: "svg" | "png" | "jpg" | "dot" | "json";
+  /** Output filename */
+  filename?: string;
+  /** Output width in pixels (for PNG/JPG) */
+  width?: number;
+  /** Output height in pixels (for PNG/JPG) */
+  height?: number;
+  /** Scale factor for output (for PNG/JPG, default: 2) */
+  scale?: number;
+  /** Whether to inject icons into SVG output */
+  injectIcons?: boolean;
+  /** Whether to embed diagram metadata into SVG output (default: true) */
+  embedData?: boolean;
+  /** Whether to return output as data URL */
+  dataUrl?: boolean;
+}
+/**
+ * Options for creating an edge
+ * @example
+ * ```typescript
+ * const edge = Edge({ label: "HTTP", color: "blue", style: "dashed" });
+ * ```
+ */
+interface EdgeOptions {
+  /** The source node (internal use) */
+  node?: Node;
+  /** Whether this is a forward edge */
+  forward?: boolean;
+  /** Whether this is a reverse edge */
+  reverse?: boolean;
+  /** Edge label text */
+  label?: string;
+  /** Edge color */
+  color?: string;
+  /** Edge style (solid, dashed, dotted, etc.) */
+  style?: string;
+  /** CSS class(es) to add to the rendered SVG element */
+  className?: string;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs?: Record<string, string>;
+  /** Additional Graphviz edge attributes */
+  [key: string]: unknown;
+}
+/**
+ * Options for creating a node
+ * @example
+ * ```typescript
+ * const node = Node("My Service", { shape: "box", color: "blue" });
+ * ```
+ */
+interface NodeOptions {
+  /** Custom unique identifier for the node */
+  nodeId?: string;
+  /** @internal Node type for autolabel */
+  ["~type"]?: string;
+  /** @internal Icon data URL */
+  ["~iconDataUrl"]?: string;
+  /** CSS class(es) to add to the rendered SVG element */
+  className?: string;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs?: Record<string, string>;
+  /** Additional Graphviz node attributes */
+  [key: string]: unknown;
+}
+/**
+ * Options for creating a cluster
+ * @example
+ * ```typescript
+ * const cluster = diagram.cluster("VPC", {
+ *   className: "production",
+ *   dataAttrs: { region: "us-east-1" }
+ * });
+ * ```
+ */
+interface ClusterOptions {
+  /** Graphviz attributes for the cluster */
+  graphAttr?: Record<string, string>;
+  /** CSS class(es) to add to the rendered SVG element */
+  className?: string;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs?: Record<string, string>;
+}
+type Yaml = typeof yaml_d_exports;
+//#endregion
 //#region src/json.d.ts
 /**
  * JSON representation of a node in the diagram.
@@ -805,6 +870,10 @@ interface DiagramNodeJSON {
   attrs?: Record<string, string | number>;
   /** Metadata attached to this node (e.g., cloud provider specs, pricing) */
   metadata?: Record<string, any>;
+  /** CSS class(es) to add to the rendered SVG element */
+  className?: string;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs?: Record<string, string>;
 }
 /**
  * JSON representation of an edge (connection) between nodes.
@@ -824,6 +893,10 @@ interface DiagramEdgeJSON {
   style?: string;
   /** Additional Graphviz attributes */
   attrs?: Record<string, string>;
+  /** CSS class(es) to add to the rendered SVG element */
+  className?: string;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs?: Record<string, string>;
 }
 /**
  * JSON representation of a cluster (group) of nodes.
@@ -837,6 +910,10 @@ interface DiagramClusterJSON {
   graphAttr?: Record<string, string>;
   /** Nested clusters */
   clusters?: DiagramClusterJSON[];
+  /** CSS class(es) to add to the rendered SVG element */
+  className?: string;
+  /** Custom data attributes to add to the rendered SVG element */
+  dataAttrs?: Record<string, string>;
 }
 /**
  * A provider module mapping type names to factory functions.
@@ -1199,9 +1276,10 @@ interface Diagram {
   /**
    * Create a cluster (group) of nodes
    * @param label - The label for the cluster
+   * @param options - Optional cluster configuration
    * @returns The cluster object
    */
-  cluster(label: string): Cluster;
+  cluster(label: string, options?: ClusterOptions): Cluster;
   /**
    * Render the diagram to SVG or other formats
    * @param options - Rendering options
@@ -1512,7 +1590,7 @@ declare function createSVGPlugin(): DiagramsPlugin;
  */
 declare const svgPlugin: DiagramsPlugin;
 declare namespace index_d_exports {
-  export { ChangeKind, Cluster, ClusterDiff, CreatePlugin, Custom, DependencyError, Diagram, DiagramClusterJSON, DiagramDiffResult, DiagramEdgeJSON, DiagramJSON, DiagramNodeJSON, DiagramOptions, DiagramsPlugin, DiffMeta, DiffOptions, DiffSummary, Edge, EdgeDiff, EdgeOptions, ExportContext, ExporterCapability, FromJSONOptions, HookCapability, HookContext, HookEvent, HookHandler, Iconify, ImportContext, ImporterCapability, MetadataCapability, MetadataContext, Node, NodeDiff, NodeMetadata, NodeOptions, PluginCapability, PluginContext, PluginError, PluginRegistry, ProviderModule, RenderContext, RenderDiffOptions, RendererCapability, RuntimeError, RuntimeSupport, ThemeConfig, ThemeName, Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };
+  export { ChangeKind, Cluster, ClusterDiff, ClusterOptions, CreatePlugin, Custom, DependencyError, Diagram, DiagramClusterJSON, DiagramDiffResult, DiagramEdgeJSON, DiagramJSON, DiagramNodeJSON, DiagramOptions, DiagramsPlugin, DiffMeta, DiffOptions, DiffSummary, Edge, EdgeDiff, EdgeOptions, ExportContext, ExporterCapability, FromJSONOptions, HookCapability, HookContext, HookEvent, HookHandler, Iconify, ImportContext, ImporterCapability, MetadataCapability, MetadataContext, Node, NodeDiff, NodeMetadata, NodeOptions, PluginCapability, PluginContext, PluginError, PluginRegistry, ProviderModule, RenderContext, RenderDiffOptions, RendererCapability, RuntimeError, RuntimeSupport, ThemeConfig, ThemeName, Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };
 }
 //#endregion
-export { type ChangeKind, Cluster, type ClusterDiff, type CreatePlugin, Custom, DependencyError, Diagram, type DiagramClusterJSON, type DiagramDiffResult, type DiagramEdgeJSON, type DiagramJSON, type DiagramNodeJSON, type DiagramOptions, type DiagramsPlugin, type DiffMeta, type DiffOptions, type DiffSummary, Edge, type EdgeDiff, type EdgeOptions, type ExportContext, type ExporterCapability, type FromJSONOptions, type HookCapability, type HookContext, HookEvent, type HookHandler, Iconify, type ImportContext, type ImporterCapability, type MetadataCapability, type MetadataContext, type Node, type NodeDiff, type NodeMetadata, type NodeOptions, type PluginCapability, type PluginContext, PluginError, type PluginRegistry, type ProviderModule, type RenderContext, type RenderDiffOptions, type RendererCapability, RuntimeError, type RuntimeSupport, type ThemeConfig, type ThemeName, type Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };
+export { type ChangeKind, Cluster, type ClusterDiff, type ClusterOptions, type CreatePlugin, Custom, DependencyError, Diagram, type DiagramClusterJSON, type DiagramDiffResult, type DiagramEdgeJSON, type DiagramJSON, type DiagramNodeJSON, type DiagramOptions, type DiagramsPlugin, type DiffMeta, type DiffOptions, type DiffSummary, Edge, type EdgeDiff, type EdgeOptions, type ExportContext, type ExporterCapability, type FromJSONOptions, type HookCapability, type HookContext, HookEvent, type HookHandler, Iconify, type ImportContext, type ImporterCapability, type MetadataCapability, type MetadataContext, type Node, type NodeDiff, type NodeMetadata, type NodeOptions, type PluginCapability, type PluginContext, PluginError, type PluginRegistry, type ProviderModule, type RenderContext, type RenderDiffOptions, type RendererCapability, RuntimeError, type RuntimeSupport, type ThemeConfig, type ThemeName, type Yaml, computeDiff, createJSONPlugin, createPluginRegistry, createSVGPlugin, jsonPlugin, renderDiff, svgPlugin };