Restructure permanent link-label rendering: own sankey-link-label-set group (fixes z-order with entering link paths), thread the label selection through updateShapes/attachDragHandler/startForce instead of DOM-querying every drag frame, and build each link's model once via a shared linkModels cache instead of duplicating it for paths and labels; exiting labels now fade out like links, and per-link texttemplate lookups use pointNumber instead of the loop index. Also switch link.texttemplate to the shared texttemplateAttrs() helper for a standard description and %{meta} support. More details in draftlog.

Author: wfr

draftlogs/7888_add.md

@@ -1,3 +1,4 @@
-- Add permanent on-diagram link labels to the Sankey trace via new `link.textinfo`, `link.texttemplate`, `link.textfont`, `link.valueformat`, and `link.valuesuffix` attributes [[#7888](https://github.com/plotly/plotly.js/pull/7888)].
+- Add permanent on-diagram link labels to the Sankey trace via new `link.textinfo`, `link.texttemplate`, `link.texttemplatefallback`, `link.textfont`, `link.valueformat`, and `link.valuesuffix` attributes [[#7888](https://github.com/plotly/plotly.js/pull/7888)].
   - `link.textinfo` shows `label` and/or `value` directly on each link, opt-in and off by default
-  - `link.texttemplate` allows full custom formatting, with `%{label}`, `%{value}`, `%{valueLabel}`, `%{source}`, `%{target}`, and `%{customdata}` as available variables
+  - `link.texttemplate` allows full custom formatting, with `%{label}`, `%{value}`, `%{valueLabel}`, `%{source}`, `%{target}`, `%{customdata}` and `%{meta}` as available variables, resolved using the layout locale
+  - `link.texttemplatefallback`, `link.textfont`, `link.valueformat` and `link.valuesuffix` control the fallback text for missing template variables, the label font, and value formatting/suffix respectively, each falling back to the corresponding trace-level attribute when unset 

src/traces/sankey/attributes.js

@@ -5,7 +5,7 @@ var baseAttrs = require('../../plots/attributes');
 var colorAttrs = require('../../components/color/attributes');
 var fxAttrs = require('../../components/fx/attributes');
 var domainAttrs = require('../../plots/domain').attributes;
-const { hovertemplateAttrs, templatefallbackAttrs } = require('../../plots/template_attributes');
+const { hovertemplateAttrs, texttemplateAttrs, templatefallbackAttrs } = require('../../plots/template_attributes');
 var colorAttributes = require('../../components/colorscale/attributes');
 var templatedArray = require('../../plot_api/plot_template').templatedArray;
 var descriptionOnlyNumbers = require('../../plots/cartesian/axis_format_attributes').descriptionOnlyNumbers;
@@ -220,19 +220,13 @@ var attrs = (module.exports = overrideAll(
                     'Any combination of *label* and *value* joined with a *+* OR *none*.'
                 ].join(' ')
             },
-            texttemplate: {
-                valType: 'string',
-                dflt: '',
-                arrayOk: true,
+            texttemplate: texttemplateAttrs({editType: 'calc'}, {
                 description: [
-                    'Template string used for rendering the information text that appears',
-                    'permanently on the links. Note that this will override `textinfo`.',
-                    'Variables are inserted using %{variable}, for example',
-                    '*%{label}: %{value}*. Available variables are `label`, `value`,',
-                    '`valueLabel` (the value formatted with `valueformat`/`valuesuffix`),',
-                    '`source`, `target`, `customdata` and `meta`.'
-                ].join(' ')
-            },
+                    '*%{label}: %{valueLabel}* renders the link label and its formatted',
+                    'value; `valueLabel` is the value formatted with `valueformat`/`valuesuffix`.'
+                ].join(' '),
+                keys: ['label', 'value', 'valueLabel', 'source', 'target', 'customdata', 'meta']
+            }),
             texttemplatefallback: templatefallbackAttrs(),
             textfont: fontAttrs({
                 autoShadowDflt: true,

src/traces/sankey/constants.js

@@ -13,6 +13,7 @@ module.exports = {
         sankey: 'sankey',
         sankeyLinks: 'sankey-links',
         sankeyLink: 'sankey-link',
+        sankeyLinkLabelSet: 'sankey-link-label-set',
         sankeyLinkLabel: 'sankey-link-label',
         sankeyNodeSet: 'sankey-node-set',
         sankeyNode: 'sankey-node',

src/traces/sankey/render.js

@@ -346,6 +346,17 @@ function linkModel(d, l, i) {
     };
 }
 
+// The link paths and their permanent labels are two joins over the same links,
+// so the models are built once per draw and shared between both selections.
+function linkModels(d) {
+    if(!d._linkModels) {
+        d._linkModels = d.graph.links
+            .filter(function(l) {return l.value;})
+            .map(linkModel.bind(null, d));
+    }
+    return d._linkModels;
+}
+
 function createCircularClosedPathString(link, arrowLen) {
     // Using coordinates computed by d3-sankey-circular
     var pathString = '';
@@ -704,14 +715,11 @@ function updateNodeShapes(sankeyNode) {
     sankeyNode.call(updateNodePositions);
 }
 
-function updateShapes(sankeyNode, sankeyLink) {
+function updateShapes(sankeyNode, sankeyLink, sankeyLinkLabel) {
     sankeyNode.call(updateNodeShapes);
     sankeyLink.attr('d', linkPath());
-    var linkNode = sankeyLink.node();
-    if(linkNode) {
-        d3.select(linkNode.parentNode).selectAll('.' + c.cn.sankeyLinkLabel)
-            .attr('transform', linkLabelTransform);
-    }
+    // empty selection when the permanent labels are not opted in
+    sankeyLinkLabel.attr('transform', linkLabelTransform);
 }
 
 function sizeNode(rect) {
@@ -774,7 +782,7 @@ function attachPointerEvents(selection, sankey, eventSet) {
         });
 }
 
-function attachDragHandler(sankeyNode, sankeyLink, callbacks, gd) {
+function attachDragHandler(sankeyNode, sankeyLink, sankeyLinkLabel, callbacks, gd) {
     var dragBehavior = d3.behavior.drag()
         .origin(function(d) {
             return {
@@ -803,7 +811,7 @@ function attachDragHandler(sankeyNode, sankeyLink, callbacks, gd) {
                 } else { // make a forceLayout if needed
                     attachForce(sankeyNode, forceKey, d, gd);
                 }
-                startForce(sankeyNode, sankeyLink, d, forceKey, gd);
+                startForce(sankeyNode, sankeyLink, sankeyLinkLabel, d, forceKey, gd);
             }
         })
 
@@ -829,7 +837,7 @@ function attachDragHandler(sankeyNode, sankeyLink, callbacks, gd) {
             saveCurrentDragPosition(d.node);
             if(d.arrangement !== 'snap') {
                 d.sankey.update(d.graph);
-                updateShapes(sankeyNode.filter(sameLayer(d)), sankeyLink);
+                updateShapes(sankeyNode.filter(sameLayer(d)), sankeyLink, sankeyLinkLabel);
             }
         })
 
@@ -865,7 +873,7 @@ function attachForce(sankeyNode, forceKey, d, gd) {
         .stop();
 }
 
-function startForce(sankeyNode, sankeyLink, d, forceKey, gd) {
+function startForce(sankeyNode, sankeyLink, sankeyLinkLabel, d, forceKey, gd) {
     window.requestAnimationFrame(function faster() {
         var i;
         for(i = 0; i < c.forceTicksPerFrame; i++) {
@@ -876,7 +884,7 @@ function startForce(sankeyNode, sankeyLink, d, forceKey, gd) {
         switchToSankeyFormat(nodes);
 
         d.sankey.update(d.graph);
-        updateShapes(sankeyNode.filter(sameLayer(d)), sankeyLink);
+        updateShapes(sankeyNode.filter(sameLayer(d)), sankeyLink, sankeyLinkLabel);
 
         if(d.forceLayouts[forceKey].alpha() > 0) {
             window.requestAnimationFrame(faster);
@@ -1042,12 +1050,7 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         .style('fill', 'none');
 
     var sankeyLink = sankeyLinks.selectAll('.' + c.cn.sankeyLink)
-          .data(function(d) {
-              var links = d.graph.links;
-              return links
-                .filter(function(l) {return l.value;})
-                .map(linkModel.bind(null, d));
-          }, keyFun);
+          .data(linkModels, keyFun);
 
     sankeyLink
           .enter().append('path')
@@ -1074,16 +1077,26 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         .style('opacity', 0)
         .remove();
 
-    var sankeyLinkLabel = sankeyLinks.selectAll('.' + c.cn.sankeyLinkLabel)
+    // Own group, appended between the links and the nodes: entering link paths
+    // of a later draw must not end up on top of already rendered labels.
+    var sankeyLinkLabelSet = sankey.selectAll('.' + c.cn.sankeyLinkLabelSet)
+        .data(repeat, keyFun);
+
+    sankeyLinkLabelSet.enter()
+        .append('g')
+        .classed(c.cn.sankeyLinkLabelSet, true)
+        .style('pointer-events', 'none');
+
+    var sankeyLinkLabel = sankeyLinkLabelSet.selectAll('.' + c.cn.sankeyLinkLabel)
         .data(function(d) {
             var getText = linkTextGetter(gd, d.trace);
             if(!getText) return [];
             var out = [];
-            d.graph.links.forEach(function(l, i) {
-                if(!l.value) return;
-                var txt = getText(l, i);
+            linkModels(d).forEach(function(m) {
+                // pointNumber indexes the input arrays, so it is the one an
+                // arrayOk texttemplate has to be looked up with
+                var txt = getText(m.link, m.pointNumber);
                 if(!txt) return;
-                var m = linkModel(d, l, i);
                 m.linkLabelText = txt;
                 out.push(m);
             });
@@ -1093,8 +1106,7 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
     sankeyLinkLabel.enter()
         .append('text')
         .classed(c.cn.sankeyLinkLabel, true)
-        .attr('text-anchor', 'middle')
-        .style('pointer-events', 'none');
+        .attr('text-anchor', 'middle');
 
     sankeyLinkLabel
         .attr('data-notex', 1)
@@ -1143,7 +1155,7 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
 
     sankeyNode
         .call(attachPointerEvents, sankey, callbacks.nodeEvents)
-        .call(attachDragHandler, sankeyLink, callbacks, gd); // has to be here as it binds sankeyLink
+        .call(attachDragHandler, sankeyLink, sankeyLinkLabel, callbacks, gd); // has to be here as it binds sankeyLink
 
     sankeyNode
         .transition()

src/types/generated/schema.d.ts

@@ -7010,7 +7010,7 @@ export interface SankeyData {
          * @default 'none'
          */
         textinfo?: 'label' | 'value' | 'none' | (string & {});
-        /** Template string used for rendering the information text that appears permanently on the links. Note that this will override `textinfo`. Variables are inserted using %{variable}, for example *%{label}: %{value}*. Available variables are `label`, `value`, `valueLabel` (the value formatted with `valueformat`/`valuesuffix`), `source`, `target`, `customdata` and `meta`. */
+        /** Template string used for rendering the information text that appears on points. Note that this will override `textinfo`. Variables are inserted using %{variable}, for example "y: %{y}". Numbers are formatted using d3-format's syntax %{variable:d3-format}, for example "Price: %{y:$.2f}". https://github.com/d3/d3-format/tree/v1.4.5#d3-format for details on the formatting syntax. Dates are formatted using d3-time-format's syntax %{variable|d3-time-format}, for example "Day: %{2019-01-01|%A}". https://github.com/d3/d3-time-format/tree/v2.2.3#locale_format for details on the date formatting syntax. Variables that can't be found will be replaced with the specifier. For example, a template of "data: %{x}, %{y}" will result in a value of "data: 1, %{y}" if x is 1 and y is missing. Variables with an undefined value will be replaced with the fallback value. All attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.  Finally, the template string has access to variables `label`, `value`, `valueLabel`, `source`, `target`, `customdata` and `meta`. */
         texttemplate?: string | string[];
         /**
          * Fallback string that's displayed when a variable referenced in a template is missing. If the boolean value 'false' is passed in, the specifier with the missing variable will be displayed.