@diagrammo/dgmo 0.8.21 → 0.8.23

package/src/boxes-and-lines/layout.ts

@@ -87,13 +87,125 @@ export interface BLLayoutResult {
 
 // ── Node sizing ────────────────────────────────────────────
 
-function computeNodeSize(_node: BLNode): { width: number; height: number } {
-  // Golden ratio (φ ≈ 1.618), uniform size
-  const PHI = 1.618;
-  const NODE_HEIGHT = 60;
-  const NODE_WIDTH = Math.round(NODE_HEIGHT * PHI); // ≈ 97
+const PHI = 1.618;
+const NODE_HEIGHT = 60;
+const NODE_WIDTH = Math.round(NODE_HEIGHT * PHI); // ≈ 97
+const DESC_NODE_WIDTH = 140; // wider nodes when descriptions are shown
+const DESC_FONT_SIZE = 10; // matches infra META_FONT_SIZE
+const DESC_LINE_HEIGHT = 1.4; // 14px row height at 10px (matches infra META_LINE_HEIGHT)
+const DESC_PADDING = 8;
+const SEPARATOR_GAP = 4; // matches infra NODE_SEPARATOR_GAP
+const MAX_DESC_LINES = 6;
+const MAX_LABEL_LINES = 3;
+const LABEL_LINE_HEIGHT = 1.3;
+const LABEL_PAD = 12; // top + bottom padding around label area
+
+/** Split on camelCase boundaries */
+function splitCamelCase(word: string): string[] {
+  const parts: string[] = [];
+  let start = 0;
+  for (let i = 1; i < word.length; i++) {
+    const prev = word[i - 1];
+    const curr = word[i];
+    const next = i + 1 < word.length ? word[i + 1] : '';
+    const lowerToUpper =
+      prev >= 'a' && prev <= 'z' && curr >= 'A' && curr <= 'Z';
+    const upperRunEnd =
+      prev >= 'A' &&
+      prev <= 'Z' &&
+      curr >= 'A' &&
+      curr <= 'Z' &&
+      next >= 'a' &&
+      next <= 'z';
+    if (lowerToUpper || upperRunEnd) {
+      parts.push(word.slice(start, i));
+      start = i;
+    }
+  }
+  parts.push(word.slice(start));
+  return parts.length > 1 ? parts : [word];
+}
 
-  return { width: NODE_WIDTH, height: NODE_HEIGHT };
+/** Estimate how many lines a label needs (split on spaces/dashes/camelCase, font shrink 13→9) */
+function estimateLabelLines(label: string, nodeWidth = NODE_WIDTH): number {
+  // Split on spaces and dashes, then camelCase
+  const rawParts = label.split(/[\s-]+/);
+  const words: string[] = [];
+  for (const part of rawParts) {
+    if (!part) continue;
+    words.push(...splitCamelCase(part));
+  }
+
+  for (let fontSize = 13; fontSize >= 9; fontSize--) {
+    const charWidth = fontSize * 0.6;
+    const maxChars = Math.floor((nodeWidth - 24) / charWidth);
+    if (maxChars < 2) continue;
+
+    let lines = 1;
+    let current = '';
+    for (const word of words) {
+      const test = current ? `${current} ${word}` : word;
+      if (test.length <= maxChars) {
+        current = test;
+      } else {
+        lines++;
+        current = word;
+      }
+    }
+    if (lines <= MAX_LABEL_LINES) return Math.min(lines, MAX_LABEL_LINES);
+  }
+  return MAX_LABEL_LINES;
+}
+
+function computeNodeSize(node: BLNode): { width: number; height: number } {
+  if (!node.description || node.description.length === 0) {
+    return { width: NODE_WIDTH, height: NODE_HEIGHT };
+  }
+
+  const w = DESC_NODE_WIDTH;
+
+  // Estimate label height (up to 3 lines)
+  const labelLines = estimateLabelLines(node.label, w);
+  const labelHeight = labelLines * 13 * LABEL_LINE_HEIGHT + LABEL_PAD;
+
+  // Estimate wrapped line count using word-boundary wrapping (matches renderer)
+  const charsPerLine = Math.floor((w - 24) / (DESC_FONT_SIZE * 0.6));
+  let totalRenderedLines = 0;
+  for (const line of node.description) {
+    if (line.length <= charsPerLine) {
+      totalRenderedLines += 1;
+    } else {
+      const words = line.split(/\s+/);
+      let current = '';
+      let lineCount = 0;
+      for (const word of words) {
+        // Words wider than line get truncated with "…" in renderer (1 line)
+        const fitted =
+          word.length > charsPerLine ? word.slice(0, charsPerLine) : word;
+        const test = current ? `${current} ${fitted}` : fitted;
+        if (test.length <= charsPerLine) {
+          current = test;
+        } else {
+          if (current) lineCount++;
+          current = fitted;
+        }
+      }
+      if (current) lineCount++;
+      totalRenderedLines += lineCount;
+    }
+  }
+  totalRenderedLines = Math.min(totalRenderedLines, MAX_DESC_LINES);
+
+  const descriptionHeight =
+    totalRenderedLines * DESC_FONT_SIZE * DESC_LINE_HEIGHT;
+  const totalHeight =
+    labelHeight +
+    SEPARATOR_GAP +
+    DESC_PADDING +
+    descriptionHeight +
+    DESC_PADDING;
+
+  return { width: w, height: Math.max(NODE_HEIGHT, totalHeight) };
 }
 
 // ── Main layout ────────────────────────────────────────────
@@ -103,8 +215,10 @@ export function layoutBoxesAndLines(
   collapseInfo?: {
     collapsedChildCounts: Map<string, number>;
     originalGroups: import('./types').BLGroup[];
-  }
+  },
+  layoutOptions?: { hideDescriptions?: boolean }
 ): BLLayoutResult {
+  const hideDescriptions = layoutOptions?.hideDescriptions ?? false;
   const g = new dagre.graphlib.Graph({ compound: true, multigraph: true });
   g.setGraph({
     rankdir: parsed.direction,
@@ -137,12 +251,9 @@ export function layoutBoxesAndLines(
   }
 
   // Add collapsed groups as regular nodes — same golden-ratio dimensions
-  const PHI = 1.618;
-  const COLLAPSED_H = 60;
-  const COLLAPSED_W = Math.round(COLLAPSED_H * PHI);
   for (const label of collapsedGroupLabels) {
     const gid = `__group_${label}`;
-    g.setNode(gid, { label, width: COLLAPSED_W, height: COLLAPSED_H });
+    g.setNode(gid, { label, width: NODE_WIDTH, height: NODE_HEIGHT });
   }
 
   // Add expanded group nodes as compound parents
@@ -176,9 +287,31 @@ export function layoutBoxesAndLines(
     }
   }
 
+  // Compute node sizes — described nodes share uniform height (unless hidden)
+  const nodeSizes = new Map<string, { width: number; height: number }>();
+  let maxDescHeight = 0;
+  for (const node of parsed.nodes) {
+    const size = hideDescriptions
+      ? { width: NODE_WIDTH, height: NODE_HEIGHT }
+      : computeNodeSize(node);
+    nodeSizes.set(node.label, size);
+    if (!hideDescriptions && node.description && node.description.length > 0) {
+      maxDescHeight = Math.max(maxDescHeight, size.height);
+    }
+  }
+  // Apply uniform height to all described nodes
+  if (maxDescHeight > 0) {
+    for (const node of parsed.nodes) {
+      if (node.description && node.description.length > 0) {
+        const size = nodeSizes.get(node.label)!;
+        nodeSizes.set(node.label, { width: size.width, height: maxDescHeight });
+      }
+    }
+  }
+
   // Add nodes
   for (const node of parsed.nodes) {
-    const size = computeNodeSize(node);
+    const size = nodeSizes.get(node.label)!;
     g.setNode(node.label, {
       label: node.label,
       width: size.width,
@@ -219,8 +352,22 @@ export function layoutBoxesAndLines(
     expandedGroupIds.add(`__group_${group.label}`);
   }
 
+  // Map expanded group IDs to their first child node (for proxy edges)
+  const groupFirstChild = new Map<string, string>();
+  for (const group of parsed.groups) {
+    const gid = `__group_${group.label}`;
+    // Find first child that is a plain node (not a sub-group)
+    const firstChild = group.children.find(
+      (c) => !groupLabelSet.has(c) && g.hasNode(c)
+    );
+    if (firstChild) {
+      groupFirstChild.set(gid, firstChild);
+    }
+  }
+
   // Add edges — skip edges where either endpoint is an expanded compound parent
   const deferredEdgeIndices: number[] = [];
+  let proxyIdx = 0;
   for (let i = 0; i < parsed.edges.length; i++) {
     const edge = parsed.edges[i];
     const src = edge.source;
@@ -228,6 +375,21 @@ export function layoutBoxesAndLines(
     if (!g.hasNode(src) || !g.hasNode(tgt)) continue;
     if (expandedGroupIds.has(src) || expandedGroupIds.has(tgt)) {
       deferredEdgeIndices.push(i);
+      // Add invisible proxy edge between child nodes so dagre ranks the groups
+      const proxySrc = expandedGroupIds.has(src)
+        ? groupFirstChild.get(src)
+        : src;
+      const proxyTgt = expandedGroupIds.has(tgt)
+        ? groupFirstChild.get(tgt)
+        : tgt;
+      if (proxySrc && proxyTgt && proxySrc !== proxyTgt) {
+        g.setEdge(
+          proxySrc,
+          proxyTgt,
+          { label: '', minlen: 1 },
+          `proxy${proxyIdx++}`
+        );
+      }
       continue;
     }
     g.setEdge(src, tgt, { label: edge.label ?? '', minlen: 1 }, `e${i}`);
@@ -285,6 +447,88 @@ export function layoutBoxesAndLines(
     });
   }
 
+  // Center-align groups connected by group-to-group edges.
+  // Dagre can't rank expanded compound parents directly, and collapsed groups
+  // may also end up misaligned. Post-process to share a common center axis.
+  // Track per-group shifts so regular edge points can be adjusted too.
+  const groupAlignShifts = new Map<string, number>(); // gid → shift in alignment axis
+  {
+    // Find all group-to-group edges (both deferred and regular)
+    const groupEdges: { source: string; target: string }[] = [];
+    for (const edge of parsed.edges) {
+      if (
+        edge.source.startsWith('__group_') &&
+        edge.target.startsWith('__group_')
+      ) {
+        groupEdges.push(edge);
+      }
+    }
+
+    if (groupEdges.length > 0) {
+      // Build connected components via union-find
+      const groupParent = new Map<string, string>();
+      const find = (x: string): string => {
+        while (groupParent.has(x) && groupParent.get(x) !== x) {
+          groupParent.set(x, groupParent.get(groupParent.get(x)!)!);
+          x = groupParent.get(x)!;
+        }
+        return x;
+      };
+      const union = (a: string, b: string) => {
+        const ra = find(a),
+          rb = find(b);
+        if (ra !== rb) groupParent.set(ra, rb);
+      };
+
+      for (const edge of groupEdges) {
+        if (!groupParent.has(edge.source))
+          groupParent.set(edge.source, edge.source);
+        if (!groupParent.has(edge.target))
+          groupParent.set(edge.target, edge.target);
+        union(edge.source, edge.target);
+      }
+
+      // Group layout groups by connected component
+      const components = new Map<string, BLLayoutGroup[]>();
+      for (const lg of layoutGroups) {
+        const gid = `__group_${lg.label}`;
+        if (!groupParent.has(gid)) continue;
+        const root = find(gid);
+        if (!components.has(root)) components.set(root, []);
+        components.get(root)!.push(lg);
+      }
+
+      // For each component, align on the widest group's center
+      const axis = parsed.direction === 'TB' ? 'x' : 'y';
+      for (const groups of components.values()) {
+        if (groups.length < 2) continue;
+        const dim = axis === 'x' ? 'width' : 'height';
+        let widest = groups[0];
+        for (const g of groups) {
+          if (g[dim] > widest[dim]) widest = g;
+        }
+        const targetCenter = widest[axis];
+
+        for (const grp of groups) {
+          const dx = targetCenter - grp[axis];
+          if (dx === 0) continue;
+          grp[axis] += dx;
+          groupAlignShifts.set(`__group_${grp.label}`, dx);
+          // Shift child nodes in this group (expanded groups only)
+          const parsedGroup = parsed.groups.find(
+            (pg) => pg.label === grp.label
+          );
+          if (parsedGroup) {
+            for (const childLabel of parsedGroup.children) {
+              const childNode = layoutNodes.find((n) => n.label === childLabel);
+              if (childNode) childNode[axis] += dx;
+            }
+          }
+        }
+      }
+    }
+  }
+
   // Compute parallel edge offsets
   const edgeYOffsets: number[] = new Array(parsed.edges.length).fill(0);
   const edgeParallelCounts: number[] = new Array(parsed.edges.length).fill(1);
@@ -326,32 +570,64 @@ export function layoutBoxesAndLines(
     let points: { x: number; y: number }[];
 
     if (deferredSet.has(i)) {
-      // Deferred edge (compound parent endpoint) — compute points clipped to border
-      const srcNode = g.node(edge.source);
-      const tgtNode = g.node(edge.target);
-      if (!srcNode || !tgtNode) continue;
-      const srcPt = clipToRectBorder(
-        srcNode.x,
-        srcNode.y,
-        srcNode.width,
-        srcNode.height,
-        tgtNode.x,
-        tgtNode.y
+      // Deferred edge (compound parent endpoint) — use post-alignment layout
+      // positions and emit from center of the relevant border face
+      const srcLayout = layoutGroups.find(
+        (lg) => `__group_${lg.label}` === edge.source
       );
-      const tgtPt = clipToRectBorder(
-        tgtNode.x,
-        tgtNode.y,
-        tgtNode.width,
-        tgtNode.height,
-        srcNode.x,
-        srcNode.y
+      const tgtLayout = layoutGroups.find(
+        (lg) => `__group_${lg.label}` === edge.target
       );
-      const midX = (srcPt.x + tgtPt.x) / 2;
-      const midY = (srcPt.y + tgtPt.y) / 2;
-      points = [srcPt, { x: midX, y: midY }, tgtPt];
+      if (!srcLayout || !tgtLayout) {
+        // Fallback to dagre node positions for collapsed groups / mixed endpoints
+        const srcNode = g.node(edge.source);
+        const tgtNode = g.node(edge.target);
+        if (!srcNode || !tgtNode) continue;
+        const srcPt = clipToRectBorder(
+          srcNode.x,
+          srcNode.y,
+          srcNode.width,
+          srcNode.height,
+          tgtNode.x,
+          tgtNode.y
+        );
+        const tgtPt = clipToRectBorder(
+          tgtNode.x,
+          tgtNode.y,
+          tgtNode.width,
+          tgtNode.height,
+          srcNode.x,
+          srcNode.y
+        );
+        const midX = (srcPt.x + tgtPt.x) / 2;
+        const midY = (srcPt.y + tgtPt.y) / 2;
+        points = [srcPt, { x: midX, y: midY }, tgtPt];
+      } else if (parsed.direction === 'TB') {
+        // TB: straight vertical line from bottom-center to top-center
+        const cx = (srcLayout.x + tgtLayout.x) / 2;
+        const srcPt = { x: cx, y: srcLayout.y + srcLayout.height / 2 };
+        const tgtPt = { x: cx, y: tgtLayout.y - tgtLayout.height / 2 };
+        const midY = (srcPt.y + tgtPt.y) / 2;
+        points = [srcPt, { x: cx, y: midY }, tgtPt];
+      } else {
+        // LR: straight horizontal line from right-center to left-center
+        const cy = (srcLayout.y + tgtLayout.y) / 2;
+        const srcPt = { x: srcLayout.x + srcLayout.width / 2, y: cy };
+        const tgtPt = { x: tgtLayout.x - tgtLayout.width / 2, y: cy };
+        const midX = (srcPt.x + tgtPt.x) / 2;
+        points = [srcPt, { x: midX, y: cy }, tgtPt];
+      }
     } else {
       const dagreEdge = g.edge(edge.source, edge.target, `e${i}`);
       points = dagreEdge?.points ?? [];
+      // If endpoints were shifted by center-alignment, adjust edge points
+      const srcShift = groupAlignShifts.get(edge.source) ?? 0;
+      const tgtShift = groupAlignShifts.get(edge.target) ?? 0;
+      if (srcShift !== 0 || tgtShift !== 0) {
+        const avgShift = (srcShift + tgtShift) / 2;
+        const prop = parsed.direction === 'TB' ? 'x' : 'y';
+        points = points.map((p) => ({ ...p, [prop]: p[prop] + avgShift }));
+      }
     }
 
     // Compute label position at midpoint

package/src/boxes-and-lines/parser.ts

@@ -45,9 +45,9 @@ function measureIndent(line: string): number {
 function parsePipeMetadata(
   segment: string,
   aliasMap: Map<string, string>
-): { metadata: Record<string, string>; description?: string } {
+): { metadata: Record<string, string>; description?: string[] } {
   const metadata: Record<string, string> = {};
-  let description: string | undefined;
+  let description: string[] | undefined;
 
   const items = segment.split(',');
   for (const item of items) {
@@ -59,7 +59,7 @@ function parsePipeMetadata(
       const rawKey = trimmed.slice(0, colonIdx).trim().toLowerCase();
       const value = trimmed.slice(colonIdx + 1).trim();
       if (rawKey === 'description') {
-        description = value;
+        description = [value];
       } else {
         const resolvedKey = aliasMap.get(rawKey) ?? rawKey;
         metadata[resolvedKey] = value;
@@ -98,6 +98,25 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
   let lastNodeLabel: string | null = null;
   let lastSourceIsGroup = false;
 
+  // Description collection state
+  let descState: {
+    nodeLabel: string;
+    indent: number;
+    lines: string[];
+    edgeSeen: boolean;
+  } | null = null;
+
+  function flushDescription() {
+    if (descState && descState.lines.length > 0) {
+      const node = result.nodes.find((n) => n.label === descState!.nodeLabel);
+      if (node) {
+        const existing = node.description ?? [];
+        node.description = [...existing, ...descState!.lines];
+      }
+    }
+    descState = null;
+  }
+
   // Group stack for nesting
   interface GroupState {
     group: BLGroup;
@@ -283,7 +302,51 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
 
     // Non-indented line closes tag group
     if (currentTagGroup && indent === 0) {
-      currentTagGroup = null; // eslint-disable-line no-useless-assignment
+      currentTagGroup = null;
+    }
+
+    // Description collection: indented non-edge lines under a node
+    if (descState !== null) {
+      if (indent > descState.indent) {
+        // Check if this is an edge line
+        if (trimmed.includes('->') || trimmed.includes('<->')) {
+          descState.edgeSeen = true;
+          // Fall through to normal edge processing
+        } else if (descState.edgeSeen) {
+          // Text after edges — emit warning
+          result.diagnostics.push(
+            makeDgmoError(
+              lineNum,
+              `Move description lines above edges for '${descState.nodeLabel}' — descriptions must come before -> lines`,
+              'warning'
+            )
+          );
+          continue;
+        } else if (
+          /^-\s*\w/.test(trimmed) &&
+          !trimmed.startsWith('- ') &&
+          !trimmed.includes('->') &&
+          !trimmed.includes('<->')
+        ) {
+          // Looks like a malformed edge (e.g. "-Target" but not "- list item")
+          result.diagnostics.push(
+            makeDgmoError(
+              lineNum,
+              `Looks like an incomplete edge — did you mean "-> ${trimmed.slice(1).trim()}"?`,
+              'warning'
+            )
+          );
+          descState.lines.push(trimmed);
+          continue;
+        } else {
+          // Collect as description
+          descState.lines.push(trimmed);
+          continue;
+        }
+      } else {
+        // Indent decreased — flush description
+        flushDescription();
+      }
     }
 
     // Close groups that are no longer scoped by indent
@@ -358,6 +421,7 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
     if (groupMatch && !trimmed.includes('->') && !trimmed.includes('<->')) {
       contentStarted = true;
       currentTagGroup = null;
+      flushDescription();
       const label = groupMatch[1];
 
       // Check nesting depth
@@ -416,7 +480,18 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
 
       // Indented shorthand: `-> Target` or `-label-> Target`
       if (trimmed.startsWith('->') || /^-[^>].*->/.test(trimmed)) {
-        if (!lastNodeLabel) {
+        // If the edge is at group-child indent level, use the containing group
+        const gs = currentGroupState();
+        const inGroup = gs && indent > gs.indent;
+        if (inGroup) {
+          const sourcePrefix = `[${gs.group.label}]`;
+          edgeText = `${sourcePrefix} ${trimmed}`;
+        } else if (lastNodeLabel) {
+          const sourcePrefix = lastSourceIsGroup
+            ? `[${lastNodeLabel}]`
+            : lastNodeLabel;
+          edgeText = `${sourcePrefix} ${trimmed}`;
+        } else {
           result.diagnostics.push(
             makeDgmoError(
               lineNum,
@@ -426,10 +501,6 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
           );
           continue;
         }
-        const sourcePrefix = lastSourceIsGroup
-          ? `[${lastNodeLabel}]`
-          : lastNodeLabel;
-        edgeText = `${sourcePrefix} ${trimmed}`;
       }
 
       const edge = parseEdgeLine(
@@ -449,6 +520,7 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
     // Node: everything else
     contentStarted = true;
     currentTagGroup = null;
+    flushDescription(); // Flush any pending description from previous node
     const node = parseNodeLine(trimmed, lineNum, aliasMap, result.diagnostics);
     if (!node) {
       result.diagnostics.push(
@@ -486,8 +558,12 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
     }
 
     result.nodes.push(node);
+    descState = { nodeLabel: node.label, indent, lines: [], edgeSeen: false };
   }
 
+  // Flush any remaining description
+  flushDescription();
+
   // Close any remaining groups
   while (groupStack.length > 0) {
     const gs = groupStack.pop()!;
@@ -562,7 +638,7 @@ function parseNodeLine(
   _diagnostics: DgmoError[]
 ): BLNode | null {
   let metadata: Record<string, string> = {};
-  let description: string | undefined;
+  let description: string[] | undefined;
 
   // Split on pipe for metadata
   const pipeIdx = trimmed.indexOf('|');