@likec4/generators 1.48.0 → 1.50.0

package/dist/index.d.mts

@@ -1,10 +1,138 @@
-import { DiagramView } from "@likec4/core";
-import { aux } from "@likec4/core/types";
+import { BBox, DiagramView, LikeC4Styles } from "@likec4/core";
+import { ProcessedView, aux } from "@likec4/core/types";
 import { AnyLikeC4Model, LikeC4Model, LikeC4ViewModel } from "@likec4/core/model";
 
 //#region src/d2/generate-d2.d.ts
 declare function generateD2(viewmodel: LikeC4ViewModel<aux.Unknown>): string;
 //#endregion
+//#region src/drawio/constants.d.ts
+/** Default filename when exporting all views into one .drawio file (CLI and playground). */
+declare const DEFAULT_DRAWIO_ALL_FILENAME = "diagrams.drawio";
+//#endregion
+//#region src/drawio/generate-drawio.d.ts
+/** Minimal view model shape for generateDrawio / generateDrawioMulti (single source of truth for call sites). */
+type DrawioViewModelLike = {
+  $view: ProcessedView<aux.Unknown>;
+  readonly $styles?: LikeC4Styles | null;
+};
+/** Optional overrides for round-trip (e.g. from parsed comment blocks). Keys are node/edge ids from the view. */
+type GenerateDrawioOptions = {
+  /** Node id -> bbox to use instead of viewmodel layout */layoutOverride?: Record<string, BBox>; /** Node id -> stroke color hex (e.g. from likec4.strokeColor.vertices comment) */
+  strokeColorByNodeId?: Record<string, string>; /** Node id -> stroke width (e.g. from likec4.strokeWidth.vertices comment) */
+  strokeWidthByNodeId?: Record<string, string>; /** Edge waypoints: key "source|target" or "source|target|edgeId" (FQN, optional id for parallel edges), value = [x,y][] (e.g. from likec4.edge.waypoints comment) */
+  edgeWaypoints?: Record<string, number[][]>;
+  /**
+   * If false, embed raw mxGraphModel XML inside <diagram> (no base64/deflate). Draw.io accepts both.
+   * generateDrawio/generateDiagramContent default to compressed when options omitted; buildDrawioExportOptionsFromSource defaults compressed: false so CLI/playground get readable XML unless overridden.
+   */
+  compressed?: boolean;
+  /**
+   * ISO timestamp for mxfile modified attribute. When omitted, uses current time (output non-deterministic).
+   * Set for deterministic output (e.g. tests, content-addressable storage).
+   */
+  modified?: string;
+};
+/**
+ * Generate a single DrawIO file from one view.
+ *
+ * @param viewmodel - Layouted LikeC4 view model (from model.view(id))
+ * @param options - Optional overrides for layout/colors (round-trip from comment blocks)
+ * @returns DrawIO .drawio XML string
+ */
+declare function generateDrawio(viewmodel: DrawioViewModelLike, options?: GenerateDrawioOptions): string;
+/**
+ * Generate a single DrawIO file with multiple diagrams (tabs).
+ * Each view becomes one tab in draw.io. Use this when exporting a project
+ * so all views open in one file with one tab per view.
+ *
+ * @param viewmodels - Layouted view models (e.g. from model.views())
+ * @param optionsByViewId - Optional per-view options (e.g. compressed: false for each tab)
+ * @param modified - Optional ISO timestamp for mxfile modified attribute (for deterministic output)
+ * @returns DrawIO .drawio XML string with multiple <diagram> elements
+ */
+declare function generateDrawioMulti(viewmodels: Array<DrawioViewModelLike>, optionsByViewId?: Record<string, GenerateDrawioOptions>, modified?: string): string;
+/**
+ * Build export options for one view from .c4 source (parses source once).
+ *
+ * @param viewId - View id for layoutOverride lookup.
+ * @param sourceContent - Full .c4 source (e.g. joined workspace files).
+ * @param overrides - Optional overrides (e.g. compressed: false).
+ * @returns GenerateDrawioOptions for this view.
+ */
+declare function buildDrawioExportOptionsFromSource(viewId: string, sourceContent: string | undefined, overrides?: Partial<GenerateDrawioOptions>): GenerateDrawioOptions;
+/**
+ * Build export options per view id from .c4 source (parses source once for all views).
+ *
+ * @param viewIds - View ids to build options for.
+ * @param sourceContent - Full .c4 source (e.g. joined workspace files).
+ * @param overrides - Optional overrides (e.g. compressed: false).
+ * @returns Record of viewId → GenerateDrawioOptions.
+ */
+declare function buildDrawioExportOptionsForViews(viewIds: string[], sourceContent: string | undefined, overrides?: Partial<GenerateDrawioOptions>): Record<string, GenerateDrawioOptions>;
+/**
+ * Generate a draw.io editor URL that opens the given drawio XML pre-loaded.
+ * Uses the `#create=` fragment with compressed XML data.
+ *
+ * @param xml - A .drawio XML string (output of generateDrawio / generateDrawioMulti).
+ * @returns URL string like "https://app.diagrams.net/#create=..."
+ */
+declare function generateDrawioEditUrl(xml: string): string;
+//#endregion
+//#region src/drawio/parse-drawio.d.ts
+/**
+ * One diagram's name, id and raw or compressed content from mxfile (single-tab or one tab in multi-tab).
+ * content is decompressed mxGraphModel XML when the source was compressed.
+ */
+interface DiagramInfo {
+  name: string;
+  id: string;
+  content: string;
+}
+/**
+ * Extract all diagram name, id and content from mxfile (for multi-tab .drawio).
+ * Uses indexOf-based extraction instead of regex to avoid S5852 (super-linear backtracking DoS).
+ * @param fullXml - Full .drawio mxfile XML string.
+ * @returns Array of DiagramInfo (one per <diagram>); content decompressed when needed.
+ */
+declare function getAllDiagrams(fullXml: string): DiagramInfo[];
+/**
+ * Convert DrawIO XML to LikeC4 source (.c4) string.
+ * Vertices → model elements (actor/container); edges → relations (->). Uses first diagram only.
+ * @param xml - Full .drawio mxfile XML (single or multi-tab).
+ * @returns LikeC4 .c4 source string (model + views + round-trip comments).
+ */
+declare function parseDrawioToLikeC4(xml: string): string;
+/**
+ * Convert DrawIO XML to LikeC4 source when file has multiple diagrams (tabs).
+ * Merges elements by FQN and relations by (source, target); one view per diagram.
+ * @param xml - Full .drawio mxfile XML with multiple <diagram> elements.
+ * @returns LikeC4 .c4 source string (model + views + round-trip comments).
+ */
+declare function parseDrawioToLikeC4Multi(xml: string): string;
+/** Data extracted from DrawIO round-trip comment blocks in .c4 source (for re-export). */
+type DrawioRoundtripData = {
+  layoutByView: Record<string, {
+    nodes: Record<string, {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+    }>;
+  }>;
+  strokeColorByFqn: Record<string, string>;
+  strokeWidthByFqn: Record<string, string>; /** Key = "src|tgt" or "src|tgt|edgeId" (FQN, optional edge id for parallel edges), value = array of [x, y] waypoints */
+  edgeWaypoints: Record<string, number[][]>;
+};
+/**
+ * Parse DrawIO round-trip comment blocks from .c4 source (layout, strokeColor, strokeWidth, waypoints).
+ * Used to build GenerateDrawioOptions for re-export after editing in draw.io.
+ * TODO: the four section parsers (layout, strokeColor, strokeWidth, waypoints) repeat the same
+ * "parse block between markers" pattern; consider a small helper to reduce duplication.
+ * @param c4Source - Full .c4 source string (e.g. concatenated workspace files).
+ * @returns DrawioRoundtripData or null if no likec4.* comment blocks found.
+ */
+declare function parseDrawioRoundtripComments(c4Source: string): DrawioRoundtripData | null;
+//#endregion
 //#region src/mmd/generate-mmd.d.ts
 declare function generateMermaid(viewmodel: LikeC4ViewModel<aux.Unknown>): string;
 //#endregion
@@ -56,4 +184,4 @@ declare function generateViewsDataTs(diagrams: Iterable<DiagramView>): string;
  */
 declare function generateViewsDataDTs(diagrams: Iterable<DiagramView>): string;
 //#endregion
-export { generateD2, generateLikeC4Model, generateMermaid, generatePuml, generateReactNext, generateReactTypes, generateViewsDataDTs, generateViewsDataJs, generateViewsDataTs };
+export { DEFAULT_DRAWIO_ALL_FILENAME, type DrawioViewModelLike, type GenerateDrawioOptions, buildDrawioExportOptionsForViews, buildDrawioExportOptionsFromSource, generateD2, generateDrawio, generateDrawioEditUrl, generateDrawioMulti, generateLikeC4Model, generateMermaid, generatePuml, generateReactNext, generateReactTypes, generateViewsDataDTs, generateViewsDataJs, generateViewsDataTs, getAllDiagrams, parseDrawioRoundtripComments, parseDrawioToLikeC4, parseDrawioToLikeC4Multi };