Feature/4935 subgraph title margin config option

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

@@ -874,4 +874,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,6 +5,7 @@ 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/getSubGraphTitleMargins.js';
 
 const rect = (parent, node) => {
   log.info('Creating subgraph rect for ', node.id, node);
@@ -63,17 +64,22 @@ const rect = (parent, node) => {
     .attr('width', width)
     .attr('height', node.height + padding);
 
+  const { subGraphTitleTopMargin } = getSubGraphTitleMargins();
   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
@@ -175,6 +181,7 @@ const roundedWithTitle = (parent, node) => {
     .attr('width', width + padding)
     .attr('height', node.height + padding - bbox.height - 3);
 
+  const { subGraphTitleTopMargin } = getSubGraphTitleMargins();
   // Center the label
   label.attr(
     'transform',
@@ -185,6 +192,7 @@ const roundedWithTitle = (parent, node) => {
         node.height / 2 -
         node.padding / 3 +
         (evaluate(getConfig().flowchart.htmlLabels) ? 5 : 3)) +
+      subGraphTitleTopMargin +
       ')'
   );
 

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

@@ -13,6 +13,9 @@ 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/getSubGraphTitleMargins.js';
+
+const { subGraphTitleTotalMargin } = getSubGraphTitleMargins();
 
 const recursiveRender = async (_elem, graph, diagramtype, id, parentCluster) => {
   log.info('Graph in recursive render: XXX', graphlibJson.write(graph), parentCluster);
@@ -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.spec.ts

@@ -1,5 +1,7 @@
 import { vi } from 'vitest';
 import utils, { calculatePoint, cleanAndMerge, detectDirective } from './utils.js';
+import { getSubGraphTitleMargins } from './utils/getSubGraphTitleMargins.js';
+import * as configApi from './config.js';
 import assignWithDepth from './assignWithDepth.js';
 import { detectType } from './diagram-api/detectType.js';
 import { addDiagrams } from './diagram-api/diagram-orchestration.js';
@@ -594,3 +596,23 @@ describe('calculatePoint', () => {
     );
   });
 });
+
+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()).toEqual({
+      subGraphTitleTopMargin: 10,
+      subGraphTitleBottomMargin: 5,
+      subGraphTitleTotalMargin: 15,
+    });
+  });
+});

packages/mermaid/src/utils/getSubGraphTitleMargins.ts

@@ -0,0 +1,17 @@
+import { getConfig } from '../diagram-api/diagramAPI.js';
+
+export const getSubGraphTitleMargins = (): {
+  subGraphTitleTopMargin: number;
+  subGraphTitleBottomMargin: number;
+  subGraphTitleTotalMargin: number;
+} => {
+  const subGraphTitleTopMargin = getConfig().flowchart?.subGraphTitleMargin?.top || 0;
+  const subGraphTitleBottomMargin = getConfig().flowchart?.subGraphTitleMargin?.bottom || 0;
+  const subGraphTitleTotalMargin = subGraphTitleTopMargin + subGraphTitleBottomMargin;
+
+  return {
+    subGraphTitleTopMargin,
+    subGraphTitleBottomMargin,
+    subGraphTitleTotalMargin,
+  };
+};