fix(sankey): address PR review feedback

- Restore SankeyLinkColor gradient meta:enum and default that were accidentally deleted
- Rename labelStyle 'default' to 'outlined', default to 'legacy' (non-breaking)
- Restore original position-based label positioning for legacy mode
- Validate nodeColors values as CSS colors in sanitizeDirective
- Use theme variables instead of hardcoded colors in styles.js
- Add changeset

Author: xinbenlv

.changeset/sankey-apple-style.md

@@ -0,0 +1,5 @@
+---
+'mermaid': minor
+---
+
+feat(sankey): add outlined label style, configurable nodeWidth/nodePadding, and custom node colors

cypress/integration/rendering/sankey.spec.ts

@@ -152,12 +152,13 @@ describe('Sankey Diagram', () => {
       ).as('graph');
     });
 
-    it('should render with outlined style by default', function () {
+    it('should render with legacy style by default', function () {
       renderGraph(this.graph, { sankey: {} });
 
-      // Default style should create background and foreground label elements
-      cy.get('.node-labels .sankey-label-bg').should('exist');
-      cy.get('.node-labels .sankey-label-fg').should('exist');
+      // Default (legacy) style should not have the outlined label classes
+      cy.get('.node-labels .sankey-label-bg').should('not.exist');
+      cy.get('.node-labels .sankey-label-fg').should('not.exist');
+      cy.get('.node-labels text').should('exist');
     });
 
     it('should render legacy (plain) labels when labelStyle is legacy', function () {
@@ -169,8 +170,8 @@ describe('Sankey Diagram', () => {
       cy.get('.node-labels text').should('exist');
     });
 
-    it('should render outlined labels when labelStyle is default', function () {
-      renderGraph(this.graph, { sankey: { labelStyle: 'default' } });
+    it('should render outlined labels when labelStyle is outlined', function () {
+      renderGraph(this.graph, { sankey: { labelStyle: 'outlined' } });
 
       cy.get('.node-labels .sankey-label-bg').should('exist');
       cy.get('.node-labels .sankey-label-fg').should('exist');
@@ -228,7 +229,7 @@ describe('Sankey Diagram', () => {
         Op Profit,Tax,19
         Op Profit,Net Profit,100
         `,
-        { sankey: { width: 800, height: 500, labelStyle: 'default' } }
+        { sankey: { width: 800, height: 500, labelStyle: 'outlined' } }
       );
     });
   });
@@ -298,7 +299,7 @@ describe('Sankey Diagram', () => {
           sankey: {
             width: 800,
             height: 500,
-            labelStyle: 'default',
+            labelStyle: 'outlined',
             showValues: true,
             prefix: '$',
             suffix: 'B',

packages/mermaid/src/config.type.ts

@@ -57,7 +57,7 @@ export type DOMPurifyConfiguration = import('dompurify').Config;
  * This interface was referenced by `MermaidConfig`'s JSON-Schema
  * via the `definition` "SankeyLabelStyle".
  */
-export type SankeyLabelStyle = 'default' | 'legacy';
+export type SankeyLabelStyle = 'legacy' | 'outlined';
 /**
  * The font size to use
  */
@@ -1614,7 +1614,7 @@ export interface SankeyDiagramConfig extends BaseDiagramConfig {
    * The style of labels in the sankey diagram. 'outlined' provides better readability with a white stroke behind the text.
    *
    */
-  labelStyle?: 'default' | 'legacy';
+  labelStyle?: 'legacy' | 'outlined';
   /**
    * A mapping of node IDs to their colors. Nodes not specified will use the default color scheme.
    *

packages/mermaid/src/defaultConfig.ts

@@ -273,7 +273,7 @@ const config: RequiredDeep<MermaidConfig> = {
   },
   sankey: {
     ...defaultConfigJson.sankey,
-    // Define nodeColors so it's included in configKeys (allows it through sanitizeDirective)
+    // Set so that `configKeys` includes this key for sanitizeDirective
     nodeColors: undefined,
   },
   treemap: {

packages/mermaid/src/diagrams/sankey/sankeyRenderer.ts

@@ -92,7 +92,7 @@ export const draw = function (text: string, id: string, _version: string, diagOb
   // New config options with defaults
   const nodeWidth = conf?.nodeWidth ?? defaultSankeyConfig.nodeWidth ?? 10;
   const nodePadding = conf?.nodePadding ?? defaultSankeyConfig.nodePadding ?? 12;
-  const labelStyle = conf?.labelStyle ?? defaultSankeyConfig.labelStyle ?? 'default';
+  const labelStyle = conf?.labelStyle ?? defaultSankeyConfig.labelStyle ?? 'legacy';
   const nodeColors: Record<string, string> = conf?.nodeColors ?? {};
 
   // Prepare data for construction based on diagObj.db
@@ -173,29 +173,34 @@ export const draw = function (text: string, id: string, _version: string, diagOb
   };
 
   /**
-   * Determines label position based on node layer relative to central node.
-   * Left-of-center nodes get labels on the left, right-of-center on the right.
+   * Determines label position based on node position or layer.
+   * For 'outlined' style, uses layer-based positioning relative to central node.
+   * For 'legacy' style, uses position-based positioning (original behavior).
    *
-   * @param d - Node data with layer information
+   * @param d - Node data with layer/position information
    * @returns Object with x position and text-anchor
    */
   const getLabelPosition = (d: any): { x: number; anchor: string } => {
-    const nodeLayer = d.layer ?? 0;
-
-    if (nodeLayer < centralNodeLayer) {
-      // Left of center: label on the left
-      return { x: d.x0 - 6, anchor: 'end' };
-    } else {
-      // Right of center (or at center): label on the right
+    if (labelStyle === 'outlined') {
+      // Layer-based: left-of-center nodes get labels on the left
+      const nodeLayer = d.layer ?? 0;
+      if (nodeLayer < centralNodeLayer) {
+        return { x: d.x0 - 6, anchor: 'end' };
+      }
+      return { x: d.x1 + 6, anchor: 'start' };
+    }
+    // Legacy: position-based (original behavior)
+    if (d.x0 < width / 2) {
       return { x: d.x1 + 6, anchor: 'start' };
     }
+    return { x: d.x0 - 6, anchor: 'end' };
   };
 
   // Create labels for nodes
   const labelsGroup = svg.append('g').attr('class', 'node-labels').attr('font-size', 14);
 
-  if (labelStyle === 'default') {
-    // Default style: render background stroke first, then foreground text for readability
+  if (labelStyle === 'outlined') {
+    // Outlined style: render background stroke first, then foreground text for readability
     // Background text with white stroke for readability
     labelsGroup
       .selectAll('.sankey-label-bg')

packages/mermaid/src/diagrams/sankey/styles.js

@@ -9,15 +9,15 @@ const getStyles = (options) =>
 
   /* Outlined label style - background stroke for better readability */
   .sankey-label-bg {
-    stroke: rgba(255, 255, 255, 0.9);
+    stroke: ${options.mainBkg || options.background || '#fff'};
     stroke-width: 4px;
     stroke-linejoin: round;
     paint-order: stroke;
   }
 
   /* Foreground label text */
   .sankey-label-fg {
-    fill: ${options.textColor || '#1d1d1f'};
+    fill: ${options.textColor};
   }
 
   /* Node styling */

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

@@ -2219,17 +2219,19 @@ $defs: # JSON Schema definition (maybe we should move these to a separate file)
     meta:enum:
       source: Use the source of sankey link for the color of the link.
       target: Use the target of sankey link for the color of the link.
+      gradient: Use a gradient of the source and target for the color of the link.
+    default: gradient
   SankeyLabelStyle:
     description: |
       The style of labels in the sankey diagram.
     type: string
     enum:
-      - default
       - legacy
+      - outlined
     meta:enum:
-      default: Labels with a white outline for better readability against colored backgrounds.
       legacy: Plain text labels (original style).
-    default: default
+      outlined: Labels with a white outline for better readability against colored backgrounds.
+    default: legacy
 
   SankeyNodeAlignment:
     description: |
@@ -2303,9 +2305,9 @@ $defs: # JSON Schema definition (maybe we should move these to a separate file)
         default: 12
       labelStyle:
         description: |
-          The style of labels in the sankey diagram. 'default' provides better readability with a white stroke behind the text.
+          The style of labels in the sankey diagram. 'outlined' provides better readability with a white stroke behind the text.
         $ref: '#/$defs/SankeyLabelStyle'
-        default: default
+        default: legacy
       nodeColors:
         description: |
           A mapping of node IDs to their colors. Nodes not specified will use the default color scheme.

packages/mermaid/src/utils/sanitizeDirective.ts

@@ -35,12 +35,22 @@ export const sanitizeDirective = (args: any): void => {
       continue;
     }
 
-    // Recurse if an object, but skip known dictionary-style configs
-    // that allow arbitrary keys (like nodeColors for sankey diagrams)
-    const dictionaryConfigKeys = ['nodeColors'];
-    if (typeof args[key] === 'object' && !dictionaryConfigKeys.includes(key)) {
-      log.debug('sanitizing object', key);
-      sanitizeDirective(args[key]);
+    // Recurse if an object, but handle dictionary-style configs specially
+    // (like nodeColors for sankey diagrams) by validating values as CSS colors
+    if (typeof args[key] === 'object') {
+      if (key === 'nodeColors') {
+        // Validate each value is a valid CSS color
+        const colorPattern = /^#[\dA-Fa-f]{3,8}$|^rgb\([\d\s,.%]+\)$|^hsl\([\d\s,.%]+\)$|^[a-z]+$/i;
+        for (const colorKey of Object.keys(args[key])) {
+          if (typeof args[key][colorKey] !== 'string' || !colorPattern.test(args[key][colorKey])) {
+            log.debug('sanitize deleting invalid color:', colorKey, args[key][colorKey]);
+            delete args[key][colorKey];
+          }
+        }
+      } else {
+        log.debug('sanitizing object', key);
+        sanitizeDirective(args[key]);
+      }
       continue;
     }