Feature/4935 subgraph title margin config option

cypress/integration/rendering/flowchart-v2.spec.js

@@ -886,4 +886,72 @@ end
       });
     });
   });
+  describe('Subgraph title margins', () => {
+    it('Should render subgraphs with title margins set (LR)', () => {
+      imgSnapshotTest(
+        `flowchart LR
+
+          subgraph TOP
+              direction TB
+              subgraph B1
+                  direction RL
+                  i1 -->f1
+              end
+              subgraph B2
+                  direction BT
+                  i2 -->f2
+              end
+          end
+          A --> TOP --> B
+          B1 --> B2
+        `,
+        { flowchart: { subGraphTitleMargin: { top: 10, bottom: 5 } } }
+      );
+    });
+    it('Should render subgraphs with title margins set (TD)', () => {
+      imgSnapshotTest(
+        `flowchart TD
+
+          subgraph TOP
+              direction LR
+              subgraph B1
+                  direction RL
+                  i1 -->f1
+              end
+              subgraph B2
+                  direction BT
+                  i2 -->f2
+              end
+          end
+          A --> TOP --> B
+          B1 --> B2
+        `,
+        { flowchart: { subGraphTitleMargin: { top: 8, bottom: 16 } } }
+      );
+    });
+    it('Should render subgraphs with title margins set (LR) and htmlLabels set to false', () => {
+      imgSnapshotTest(
+        `flowchart LR
+
+          subgraph TOP
+              direction TB
+              subgraph B1
+                  direction RL
+                  i1 -->f1
+              end
+              subgraph B2
+                  direction BT
+                  i2 -->f2
+              end
+          end
+          A --> TOP --> B
+          B1 --> B2
+        `,
+        {
+          htmlLabels: false,
+          flowchart: { htmlLabels: false, subGraphTitleMargin: { top: 10, bottom: 5 } },
+        }
+      );
+    });
+  });
 });

packages/mermaid/src/config.type.ts

@@ -1411,6 +1411,14 @@ export interface FlowchartDiagramConfig extends BaseDiagramConfig {
    * Margin top for the text over the diagram
    */
   titleTopMargin?: number;
+  /**
+   * Defines a top/bottom margin for subgraph titles
+   *
+   */
+  subGraphTitleMargin?: {
+    top?: number;
+    bottom?: number;
+  };
   arrowMarkerAbsolute?: boolean;
   /**
    * The amount of padding around the diagram as a whole so that embedded

packages/mermaid/src/dagre-wrapper/clusters.js

@@ -5,9 +5,11 @@ import { createText } from '../rendering-util/createText.js';
 import { select } from 'd3';
 import { getConfig } from '../diagram-api/diagramAPI.js';
 import { evaluate } from '../diagrams/common/common.js';
+import { getSubGraphTitleMargins } from '../utils/subGraphTitleMargins.js';
 
 const rect = (parent, node) => {
   log.info('Creating subgraph rect for ', node.id, node);
+  const siteConfig = getConfig();
 
   // Add outer g element
   const shapeSvg = parent
@@ -18,7 +20,7 @@ const rect = (parent, node) => {
   // add the rect
   const rect = shapeSvg.insert('rect', ':first-child');
 
-  const useHtmlLabels = evaluate(getConfig().flowchart.htmlLabels);
+  const useHtmlLabels = evaluate(siteConfig.flowchart.htmlLabels);
 
   // Create the label and insert it after the rect
   const label = shapeSvg.insert('g').attr('class', 'cluster-label');
@@ -34,7 +36,7 @@ const rect = (parent, node) => {
   // Get the size of the label
   let bbox = text.getBBox();
 
-  if (evaluate(getConfig().flowchart.htmlLabels)) {
+  if (evaluate(siteConfig.flowchart.htmlLabels)) {
     const div = text.children[0];
     const dv = select(text);
     bbox = div.getBoundingClientRect();
@@ -63,17 +65,18 @@ const rect = (parent, node) => {
     .attr('width', width)
     .attr('height', node.height + padding);
 
+  const { subGraphTitleTopMargin } = getSubGraphTitleMargins(siteConfig);
   if (useHtmlLabels) {
     label.attr(
       'transform',
       // This puts the labal on top of the box instead of inside it
-      'translate(' + (node.x - bbox.width / 2) + ', ' + (node.y - node.height / 2) + ')'
+      `translate(${node.x - bbox.width / 2}, ${node.y - node.height / 2 + subGraphTitleTopMargin})`
     );
   } else {
     label.attr(
       'transform',
       // This puts the labal on top of the box instead of inside it
-      'translate(' + node.x + ', ' + (node.y - node.height / 2) + ')'
+      `translate(${node.x}, ${node.y - node.height / 2 + subGraphTitleTopMargin})`
     );
   }
   // Center the label
@@ -127,6 +130,8 @@ const noteGroup = (parent, node) => {
   return shapeSvg;
 };
 const roundedWithTitle = (parent, node) => {
+  const siteConfig = getConfig();
+
   // Add outer g element
   const shapeSvg = parent.insert('g').attr('class', node.classes).attr('id', node.id);
 
@@ -143,7 +148,7 @@ const roundedWithTitle = (parent, node) => {
 
   // Get the size of the label
   let bbox = text.getBBox();
-  if (evaluate(getConfig().flowchart.htmlLabels)) {
+  if (evaluate(siteConfig.flowchart.htmlLabels)) {
     const div = text.children[0];
     const dv = select(text);
     bbox = div.getBoundingClientRect();
@@ -175,6 +180,7 @@ const roundedWithTitle = (parent, node) => {
     .attr('width', width + padding)
     .attr('height', node.height + padding - bbox.height - 3);
 
+  const { subGraphTitleTopMargin } = getSubGraphTitleMargins(siteConfig);
   // Center the label
   label.attr(
     'transform',
@@ -184,7 +190,8 @@ const roundedWithTitle = (parent, node) => {
       (node.y -
         node.height / 2 -
         node.padding / 3 +
-        (evaluate(getConfig().flowchart.htmlLabels) ? 5 : 3)) +
+        (evaluate(siteConfig.flowchart.htmlLabels) ? 5 : 3)) +
+      subGraphTitleTopMargin +
       ')'
   );
 

packages/mermaid/src/dagre-wrapper/index.js

@@ -13,6 +13,8 @@ import { insertNode, positionNode, clear as clearNodes, setNodeElem } from './no
 import { insertCluster, clear as clearClusters } from './clusters.js';
 import { insertEdgeLabel, positionEdgeLabel, insertEdge, clear as clearEdges } from './edges.js';
 import { log } from '../logger.js';
+import { getSubGraphTitleMargins } from '../utils/subGraphTitleMargins.js';
+import { getConfig } from '../diagram-api/diagramAPI.js';
 
 const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) => {
   log.info('Graph in recursive render: XXX', graphlibJson.write(graph), parentCluster);
@@ -101,6 +103,7 @@ const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) =>
   log.info('Graph after layout:', graphlibJson.write(graph));
   // Move the nodes to the correct place
   let diff = 0;
+  const { subGraphTitleTotalMargin } = getSubGraphTitleMargins(getConfig());
   sortNodesByHierarchy(graph).forEach(function (v) {
     const node = graph.node(v);
     log.info('Position ' + v + ': ' + JSON.stringify(graph.node(v)));
@@ -114,13 +117,14 @@ const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) =>
     );
     if (node && node.clusterNode) {
       // clusterDb[node.id].node = node;
-
+      node.y += subGraphTitleTotalMargin;
       positionNode(node);
     } else {
       // Non cluster node
       if (graph.children(v).length > 0) {
         // A cluster in the non-recursive way
         // positionCluster(node);
+        node.height += subGraphTitleTotalMargin * 2;
         insertCluster(clusters, node);
         clusterDb[node.id].node = node;
       } else {

packages/mermaid/src/schemas/config.schema.yaml

@@ -1863,6 +1863,7 @@ $defs: # JSON Schema definition (maybe we should move these to a separate file)
     unevaluatedProperties: false
     required:
       - titleTopMargin
+      - subGraphTitleMargin
       - diagramPadding
       - htmlLabels
       - nodeSpacing
@@ -1875,6 +1876,20 @@ $defs: # JSON Schema definition (maybe we should move these to a separate file)
       titleTopMargin:
         $ref: '#/$defs/GitGraphDiagramConfig/properties/titleTopMargin'
         default: 25
+      subGraphTitleMargin:
+        description: |
+          Defines a top/bottom margin for subgraph titles
+        type: object
+        properties:
+          top:
+            type: integer
+            minimum: 0
+          bottom:
+            type: integer
+            minimum: 0
+        default:
+          top: 0
+          bottom: 0
       arrowMarkerAbsolute:
         type: boolean # TODO, is this actually used here (it has no default value but was in types)
       diagramPadding:

packages/mermaid/src/utils/subGraphTitleMargins.spec.ts

@@ -0,0 +1,22 @@
+import { getSubGraphTitleMargins } from './subGraphTitleMargins.js';
+import * as configApi from '../config.js';
+
+describe('getSubGraphTitleMargins', () => {
+  it('should get subgraph title margins after config has been set', () => {
+    const config_0 = {
+      flowchart: {
+        subGraphTitleMargin: {
+          top: 10,
+          bottom: 5,
+        },
+      },
+    };
+
+    configApi.setSiteConfig(config_0);
+    expect(getSubGraphTitleMargins(config_0)).toEqual({
+      subGraphTitleTopMargin: 10,
+      subGraphTitleBottomMargin: 5,
+      subGraphTitleTotalMargin: 15,
+    });
+  });
+});

packages/mermaid/src/utils/subGraphTitleMargins.ts

@@ -0,0 +1,21 @@
+import type { FlowchartDiagramConfig } from '../config.type.js';
+
+export const getSubGraphTitleMargins = ({
+  flowchart,
+}: {
+  flowchart: FlowchartDiagramConfig;
+}): {
+  subGraphTitleTopMargin: number;
+  subGraphTitleBottomMargin: number;
+  subGraphTitleTotalMargin: number;
+} => {
+  const subGraphTitleTopMargin = flowchart?.subGraphTitleMargin?.top ?? 0;
+  const subGraphTitleBottomMargin = flowchart?.subGraphTitleMargin?.bottom ?? 0;
+  const subGraphTitleTotalMargin = subGraphTitleTopMargin + subGraphTitleBottomMargin;
+
+  return {
+    subGraphTitleTopMargin,
+    subGraphTitleBottomMargin,
+    subGraphTitleTotalMargin,
+  };
+};