@diagrammo/dgmo 0.33.0 → 0.35.0

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

@@ -78,7 +78,6 @@ const GROUP_LABEL_ZONE = 32;
 const RAMP_FLOOR = 15;
 const VALUE_FONT_SIZE = 11;
 
-type D3G = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
 type D3Svg = d3Selection.Selection<SVGSVGElement, unknown, null, undefined>;
 
 // ── Edge path generators ───────────────────────────────────
@@ -352,78 +351,6 @@ function ensureArrowMarkers(
   }
 }
 
-// ── Edge label placement ───────────────────────────────────
-
-/** Point at the half-way arc length along an edge polyline — the geometric
- *  centre of the connector, so a label sits in the gap BETWEEN the two nodes
- *  (ELK's own label anchor drifts toward the target and ends up clipped under
- *  it). Falls back gracefully for degenerate point lists. */
-function edgePolylineMidpoint(
-  points: ReadonlyArray<{ readonly x: number; readonly y: number }>
-): { x: number; y: number } {
-  if (points.length === 0) return { x: 0, y: 0 };
-  if (points.length === 1) return { x: points[0]!.x, y: points[0]!.y };
-  let total = 0;
-  const segLen: number[] = [];
-  for (let k = 1; k < points.length; k++) {
-    const len = Math.hypot(
-      points[k]!.x - points[k - 1]!.x,
-      points[k]!.y - points[k - 1]!.y
-    );
-    segLen.push(len);
-    total += len;
-  }
-  let half = total / 2;
-  for (let k = 1; k < points.length; k++) {
-    const len = segLen[k - 1]!;
-    if (half <= len || k === points.length - 1) {
-      const t = len === 0 ? 0 : Math.min(1, half / len);
-      return {
-        x: points[k - 1]!.x + (points[k]!.x - points[k - 1]!.x) * t,
-        y: points[k - 1]!.y + (points[k]!.y - points[k - 1]!.y) * t,
-      };
-    }
-    half -= len;
-  }
-  const last = points[points.length - 1]!;
-  return { x: last.x, y: last.y };
-}
-
-// ── Edge label overlap resolution ──────────────────────────
-
-function resolveEdgeLabelOverlaps(
-  labels: { x: number; y: number; width: number; height: number }[]
-): void {
-  const MAX_PASSES = 8;
-  const PAD = 4;
-  for (let pass = 0; pass < MAX_PASSES; pass++) {
-    let moved = false;
-    for (let i = 0; i < labels.length; i++) {
-      for (let j = i + 1; j < labels.length; j++) {
-        // In-bounds by loop guard.
-        const a = labels[i]!;
-        const b = labels[j]!;
-        const dx = Math.abs(a.x - b.x);
-        const dy = Math.abs(a.y - b.y);
-        const overlapX = (a.width + b.width) / 2 + PAD - dx;
-        const overlapY = (a.height + b.height) / 2 + PAD - dy;
-        if (overlapX > 0 && overlapY > 0) {
-          const shift = overlapY / 2 + 1;
-          if (a.y < b.y) {
-            a.y -= shift;
-            b.y += shift;
-          } else {
-            a.y += shift;
-            b.y -= shift;
-          }
-          moved = true;
-        }
-      }
-    }
-    if (!moved) break;
-  }
-}
-
 // ── Main render function ───────────────────────────────────
 
 interface BLRenderOptions {
@@ -847,18 +774,8 @@ export function renderBoxesAndLines(
   }
 
   // ── Render edges ───────────────────────────────────────
-  // Collect label positions for overlap resolution
-  const labelPositions: {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-    idx: number;
-  }[] = [];
-
-  // Store edge group elements for label pass
-  const edgeGroups = new Map<number, D3G>();
-
+  // Edge labels are placed in layout (label-placement.ts) and drawn AFTER the
+  // node loop (see the bl-edge-labels layer) so boxes never clip them.
   for (let i = 0; i < layout.edges.length; i++) {
     // In-bounds by loop guard.
     const le = layout.edges[i]!;
@@ -885,7 +802,6 @@ export function renderBoxesAndLines(
           .append('g')
           .attr('class', 'bl-edge-group')
           .attr('data-line-number', String(le.lineNumber));
-        edgeGroups.set(i, edgeG as unknown as D3G);
 
         const markerId = `bl-arrow-${color.replace('#', '')}`;
         const cx = nodeLayout.x;
@@ -950,7 +866,6 @@ export function renderBoxesAndLines(
       .append('g')
       .attr('class', 'bl-edge-group')
       .attr('data-line-number', String(le.lineNumber));
-    edgeGroups.set(i, edgeG as unknown as D3G);
 
     const markerId = `bl-arrow-${color.replace('#', '')}`;
     const gen = le.straight
@@ -971,58 +886,6 @@ export function renderBoxesAndLines(
       const revId = `bl-arrow-rev-${color.replace('#', '')}`;
       path.attr('marker-start', `url(#${revId})`);
     }
-
-    // Edge label — centred on the connector's polyline midpoint (the gap
-    // between the two nodes), NOT ELK's target-biased anchor. For parallel
-    // edges, nudge above/below so each line's label clears the line.
-    if (le.label && le.points.length > 0) {
-      const lw = measureText(le.label, sEdgeLabelFontSize);
-      const labelH = sEdgeLabelFontSize + 6;
-      const mid = edgePolylineMidpoint(le.points);
-      let ly = mid.y;
-      if (le.parallelCount > 1 && le.yOffset !== 0) {
-        ly += (le.yOffset < 0 ? -labelH : labelH) * 0.5;
-      }
-      labelPositions.push({
-        x: mid.x,
-        y: ly,
-        width: lw + 8,
-        height: labelH,
-        idx: i,
-      });
-    }
-  }
-
-  // Resolve overlaps
-  resolveEdgeLabelOverlaps(labelPositions);
-
-  // Render edge labels into their edge groups
-  for (const lp of labelPositions) {
-    // In-bounds: lp.idx was set from a valid index into layout.edges above.
-    const le = layout.edges[lp.idx]!;
-    if (!le.label) continue;
-
-    const edgeG = edgeGroups.get(lp.idx);
-    const target = edgeG ?? diagramG;
-
-    target
-      .append('rect')
-      .attr('x', lp.x - lp.width / 2)
-      .attr('y', lp.y - lp.height / 2)
-      .attr('width', lp.width)
-      .attr('height', lp.height)
-      .attr('rx', 3)
-      .attr('fill', palette.bg)
-      .attr('opacity', 0.85);
-
-    target
-      .append('text')
-      .attr('x', lp.x)
-      .attr('y', lp.y + sEdgeLabelFontSize / 3)
-      .attr('text-anchor', 'middle')
-      .attr('font-size', sEdgeLabelFontSize)
-      .attr('fill', palette.textMuted)
-      .text(le.label);
   }
 
   // ── Render nodes ───────────────────────────────────────
@@ -1396,6 +1259,71 @@ export function renderBoxesAndLines(
     }
   }
 
+  // ── Render edge labels ─────────────────────────────────
+  // Drawn AFTER nodes (and groups) so the halo + text always paint on top and
+  // are never clipped by a box. Positions/wrapping come from label-placement
+  // (layout); this is a pure consumer. Labels stay in their own layer rather
+  // than inside each edge group, but carry data-line-number so line-hover/click
+  // still highlights the matching label.
+  const labelLayer = diagramG.append('g').attr('class', 'bl-edge-labels');
+  const labelLineHeight = sEdgeLabelFontSize * 1.3;
+  for (const le of layout.edges) {
+    if (!le.labelLines || le.labelLines.length === 0) continue;
+    if (le.labelX === undefined || le.labelY === undefined) continue;
+    const lx = le.labelX;
+    const ly = le.labelY;
+
+    // Honour the same tag-value hiding as the edges themselves.
+    if (hidden.size > 0) {
+      let isHidden = false;
+      for (const [groupKey, hiddenVals] of hidden) {
+        const val = le.metadata[groupKey];
+        if (val && hiddenVals.has(val.toLowerCase())) {
+          isHidden = true;
+          break;
+        }
+      }
+      if (isHidden) continue;
+    }
+
+    const lw = le.labelWidth ?? 0;
+    const lh = le.labelHeight ?? sEdgeLabelFontSize + 6;
+    const lines = le.labelLines;
+    const labelG = labelLayer
+      .append('g')
+      .attr('class', 'bl-edge-label')
+      .attr('data-line-number', String(le.lineNumber));
+
+    labelG
+      .append('rect')
+      .attr('x', lx - lw / 2)
+      .attr('y', ly - lh / 2)
+      .attr('width', lw)
+      .attr('height', lh)
+      .attr('rx', 3)
+      .attr('fill', palette.bg)
+      // No border; semi-transparent so the line stays faintly visible behind the
+      // label while the (full-opacity) text on top stays crisp.
+      .attr('opacity', 0.72);
+
+    const text = labelG
+      .append('text')
+      .attr('x', lx)
+      .attr('text-anchor', 'middle')
+      .attr('font-family', FONT_FAMILY)
+      .attr('font-size', sEdgeLabelFontSize)
+      .attr('fill', palette.textMuted);
+    const firstY =
+      ly - ((lines.length - 1) / 2) * labelLineHeight + sEdgeLabelFontSize / 3;
+    lines.forEach((line, k) => {
+      text
+        .append('tspan')
+        .attr('x', lx)
+        .attr('y', firstY + k * labelLineHeight)
+        .text(line);
+    });
+  }
+
   // ── Render legend ──────────────────────────────────────
   const hasDescriptions = parsed.nodes.some(
     (n) => n.description && n.description.length > 0

package/src/c4/parser.ts

@@ -516,7 +516,7 @@ export function parseC4(content: string, palette?: PaletteColors): ParsedC4 {
           } else {
             pushError(
               lineNumber,
-              `"container ${refName}" must be inside a deployment node`
+              `"container ${refName}" must be indented under a deployment node (e.g. under 'Prod is a deployment-node')`
             );
           }
           continue;
@@ -585,7 +585,10 @@ export function parseC4(content: string, palette?: PaletteColors): ParsedC4 {
           indent,
         });
       } else {
-        pushError(lineNumber, `"${sectionType}" must be inside an element`);
+        pushError(
+          lineNumber,
+          `"${sectionType}" must be indented under an element (e.g. under 'Web App is a container')`
+        );
       }
       continue;
     }
@@ -618,7 +621,10 @@ export function parseC4(content: string, palette?: PaletteColors): ParsedC4 {
           indent,
         });
       } else {
-        pushError(lineNumber, `Group [${groupName}] must be inside an element`);
+        pushError(
+          lineNumber,
+          `Group [${groupName}] must be indented under an element (e.g. under 'Web App is a container')`
+        );
       }
       continue;
     }
@@ -1049,7 +1055,10 @@ export function parseC4(content: string, palette?: PaletteColors): ParsedC4 {
       }
       desc.push(descResult.text);
     } else {
-      pushError(lineNumber, `Unexpected content: "${trimmed}"`);
+      pushError(
+        lineNumber,
+        `Unexpected content: "${trimmed}". Expected an element ('Web App is a container'), a relationship ('-Uses-> Database'), indented metadata ('tech: React'), or a group ('[Backend]'). (§8)`
+      );
     }
   }
 
@@ -1154,7 +1163,7 @@ function validateRelationshipTargets(
     for (const el of elements) {
       for (const rel of el.relationships) {
         if (!knownNames.has(normalizeName(rel.target))) {
-          let msg = `Relationship target "${rel.target}" not found`;
+          let msg = `Relationship target "${rel.target}" not found — declare it first (e.g. '${rel.target} is a container'), then reference it in the arrow`;
           const hint = suggest(normalizeName(rel.target), allNames);
           if (hint) msg += `. ${hint}`;
           pushWarning(rel.lineNumber, msg, 'warning');
@@ -1193,7 +1202,7 @@ function validateDeploymentRefs(
     for (const node of nodes) {
       for (const ref of node.containerRefs) {
         if (!knownNames.has(normalizeName(ref))) {
-          let msg = `Deployment reference "container ${ref}" not found`;
+          let msg = `Deployment reference "container ${ref}" not found — declare the container element first, then reference it under the deployment node`;
           const hint = suggest(normalizeName(ref), allNames);
           if (hint) msg += `. ${hint}`;
           pushWarning(node.lineNumber, msg, 'warning');

package/src/chart.ts

@@ -174,7 +174,7 @@ export function parseChart(
       result.diagnostics.push(
         makeDgmoError(
           lineNumber,
-          `'${trimmed}' — ## syntax is no longer supported. Use [Group] containers instead`
+          `'${trimmed}' removed — use a bracket container '[${trimmed.replace(/^#+\s*/, '')}]' instead (## headers are no longer supported).`
         )
       );
       continue;

package/src/class/parser.ts

@@ -308,7 +308,7 @@ export function parseClassDiagram(
         result.diagnostics.push(
           makeDgmoError(
             lineNumber,
-            '"no-auto-color" has been removed.',
+            '"no-auto-color" was removed — colors are always auto-assigned from the palette; delete this line.',
             'warning'
           )
         );
@@ -458,7 +458,11 @@ export function parseClassDiagram(
 
     // Catch-all: nothing matched this line
     result.diagnostics.push(
-      makeDgmoError(lineNumber, `Unexpected line: '${trimmed}'.`, 'warning')
+      makeDgmoError(
+        lineNumber,
+        `Unexpected line: '${trimmed}'. Classes start uppercase at indent 0 ('Ship'); members are indented and colon-typed ('+ name: string', '+ sail(): void'); relationships are indented arrows ('--|> Vessel'). (§10)`,
+        'warning'
+      )
     );
   }
 

package/src/cli-banner.ts

@@ -7,9 +7,8 @@
 // sampled from the default `slate` palette (corporate blue → teal →
 // steel cyan) so the wordmark matches the brand.
 //
-// Honors the same guards as `dgmo cat`: color only when stdout is a TTY
-// and NO_COLOR is unset; otherwise prints plain ASCII so pipes/CI stay
-// clean.
+// Color only when stdout is a TTY and NO_COLOR is unset; otherwise prints
+// plain ASCII so pipes/CI stay clean.
 
 import { getPalette } from './palettes';