feat(wardley): opt-in automatic label placement

Adds an opt-in `autoPlaceLabels` config flag to the wardley-beta diagram.
When enabled, component/anchor/link/annotation labels are repositioned to
avoid overlapping each other, node markers, pipeline boxes, the chart
boundary and link lines, with leader lines for far-placed labels. A
collision-free manual `label [x, y]` is kept as authored; pipeline child
labels prefer placement underneath. Placement is a pure, deterministic,
unit-tested module (wardleyLabelPlacement.ts); the renderer path is
unchanged when the flag is off.

Stacked on #7696 (wardley ecosystem/attitudes).

Author: tractorjuice

.changeset/wardley-autoplace-labels.md

@@ -0,0 +1,18 @@
+---
+'mermaid': minor
+---
+
+feat(wardley): opt-in automatic label placement (`autoPlaceLabels`)
+
+New opt-in `autoPlaceLabels` config flag for the `wardley-beta` diagram. When
+enabled, component, anchor, link and annotation labels are automatically
+repositioned to avoid overlapping each other, node markers, pipeline boxes,
+the chart boundary and link lines. Labels moved far from their node get a thin
+leader line; a collision-free manual `label [x, y]` is kept exactly as
+authored, and pipeline child labels prefer to sit underneath their node.
+
+Off by default — existing maps render unchanged. Enable it via config:
+
+```js
+mermaid.initialize({ 'wardley-beta': { autoPlaceLabels: true } });
+```

cypress/integration/rendering/wardley/wardley.spec.js

@@ -304,4 +304,84 @@ component Commodity Service [0.30, 0.85]
       {}
     );
   });
+
+  it('should render dense map labels without overlap when autoPlaceLabels is enabled', () => {
+    // Seven long-named components packed into a tiny coordinate box. Without
+    // auto-placement their default NE-offset labels collide into an unreadable
+    // blob, so this map genuinely exercises the placement algorithm.
+    imgSnapshotTest(
+      `
+wardley-beta
+title Overlapping Label Stress Test
+size [1100, 800]
+
+component Customer Service Portal [0.55, 0.62]
+component Customer Support Desk [0.58, 0.60]
+component Customer Records Store [0.52, 0.64]
+component Customer Data Platform [0.56, 0.585]
+component Account Management API [0.53, 0.59]
+component Billing And Invoicing [0.57, 0.635]
+component Identity Provider [0.545, 0.61]
+
+Customer Service Portal -> Customer Data Platform
+Customer Support Desk -> Customer Records Store
+Account Management API -> Billing And Invoicing
+Identity Provider -> Customer Data Platform
+      `,
+      { 'wardley-beta': { autoPlaceLabels: true } }
+    );
+  });
+
+  it('should keep collision-free manual labels when autoPlaceLabels is enabled', () => {
+    // Three cases: `Kept Manual Label` is isolated with a manual label that
+    // lands in clear space and has no link touching it -> kept untouched.
+    // `Colliding Manual` has a manual label dropped onto a node cluster ->
+    // re-placed. The remaining components are untuned -> auto-placed.
+    imgSnapshotTest(
+      `
+wardley-beta
+title Manual Label Mix
+size [1100, 800]
+
+component Kept Manual Label [0.25, 0.30] label [20, -18]
+component Colliding Manual [0.55, 0.60] label [-90, 2]
+component Crowded Node A [0.52, 0.62]
+component Crowded Node B [0.56, 0.585]
+component Crowded Node C [0.53, 0.59]
+component Untuned Component [0.78, 0.40]
+
+Colliding Manual -> Crowded Node B
+Crowded Node A -> Untuned Component
+      `,
+      { 'wardley-beta': { autoPlaceLabels: true } }
+    );
+  });
+
+  it('should place pipeline child labels underneath when autoPlaceLabels is enabled', () => {
+    // Pipeline child components have no manual `label [x,y]`, so they are
+    // auto-placed; their preferred direction is straight down.
+    imgSnapshotTest(
+      `
+wardley-beta
+title Pipeline Autoplace
+size [1100, 800]
+
+component Kettle [0.57, 0.45]
+component Power [0.10, 0.70]
+
+Kettle -> Power
+
+pipeline Kettle {
+  component Campfire Kettle [0.30]
+  component Electric Kettle [0.52]
+  component Smart Kettle [0.74]
+}
+
+Campfire Kettle -> Kettle
+Electric Kettle -> Kettle
+Smart Kettle -> Kettle
+      `,
+      { 'wardley-beta': { autoPlaceLabels: true } }
+    );
+  });
 });

packages/mermaid/src/config.type.ts

@@ -1815,6 +1815,14 @@ export interface WardleyDiagramConfig extends BaseDiagramConfig {
    * Whether to display a background grid.
    */
   showGrid?: boolean;
+  /**
+   * When `true`, component, anchor, link, and annotation labels are
+   * automatically repositioned to avoid overlapping each other, node
+   * markers, the chart boundary, and link lines. Manual `label [x, y]`
+   * offsets are ignored while this is enabled.
+   *
+   */
+  autoPlaceLabels?: boolean;
 }
 /**
  * This interface was referenced by `MermaidConfig`'s JSON-Schema

packages/mermaid/src/diagrams/wardley/styles.ts

@@ -84,6 +84,12 @@ export const styles: DiagramStylesProvider = ({
   .wardley-notes text {
     fill: ${w.axisTextColor};
   }
+  .wardley-leader-line {
+    stroke: ${w.annotationStroke};
+    stroke-width: 1px;
+    stroke-opacity: 0.6;
+    fill: none;
+  }
   `;
 };