named treeSort; document node columns

Author: mbostock

README.md

@@ -2061,19 +2061,43 @@ The following options control how the node-link diagram is laid out:
 
 * **treeLayout** - a tree layout algorithm; defaults to [d3.tree](https://github.com/d3/d3-hierarchy/blob/main/README.md#tree)
 * **treeAnchor** - a tree layout orientation, either *left* or *right*; defaults to *left*
-* **treeSort** - a node comparator function, or null to preserve input order
+* **treeSort** - a node comparator, or null to preserve input order
 * **treeSeparation** - a node separation function, or null for uniform separation
 
-The default **treeLayout** implements the Reingold–Tilford “tidy” algorithm based on Buchheim _et al._’s linear time approach. Use [d3.cluster](https://github.com/d3/d3-hierarchy/blob/main/README.md#cluster) instead to align leaf nodes; see also [Plot.cluster](#plotclusterdata-options). If the **treeAnchor** is *left*, the root of the tree will be aligned with the left side of the frame; if **treeAnchor** is *right*, the root of the tree will be aligned with the right side of the frame; use the **insetLeft** and **insetRight** [scale options](#scale-options) if horizontal padding is desired, say to make room for labels.  If the **treeSort** option is not null, it is a function that is passed two nodes in the hierarchy and compares them, similar to [_array_.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort); see [d3-hierarchy’s _node_.sort](https://github.com/d3/d3-hierarchy/blob/main/README.md#node_sort) for more. If the **treeSeparation** is not null, it is a function that is passed two nodes in the hierarchy and returns the desired (relative) amount of separation; see [d3-hierarchy’s _tree_.separation](https://github.com/d3/d3-hierarchy/blob/main/README.md#tree_separation) for more. By default, non-siblings are at least twice as far apart as siblings.
+The default **treeLayout** implements the Reingold–Tilford “tidy” algorithm based on Buchheim _et al._’s linear time approach. Use [d3.cluster](https://github.com/d3/d3-hierarchy/blob/main/README.md#cluster) instead to align leaf nodes; see also [Plot.cluster](#plotclusterdata-options). If the **treeAnchor** is *left*, the root of the tree will be aligned with the left side of the frame; if **treeAnchor** is *right*, the root of the tree will be aligned with the right side of the frame; use the **insetLeft** and **insetRight** [scale options](#scale-options) if horizontal padding is desired, say to make room for labels.  If the **treeSort** option is not null, it is typically a function that is passed two nodes in the hierarchy and compares them, similar to [_array_.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort); see [d3-hierarchy’s _node_.sort](https://github.com/d3/d3-hierarchy/blob/main/README.md#node_sort) for more. The **treeSort** option can also be specified as a string, in which case it refers either to a named column in data, or if it starts with “node:”, a node value (see below). If the **treeSeparation** is not null, it is a function that is passed two nodes in the hierarchy and returns the desired (relative) amount of separation; see [d3-hierarchy’s _tree_.separation](https://github.com/d3/d3-hierarchy/blob/main/README.md#tree_separation) for more. By default, non-siblings are at least twice as far apart as siblings.
 
 ### Plot.treeNode(*options*)
 
 Based on the tree options described above, populates the **x** and **y** channels with the positions for each node. The following defaults are also applied: the default **frameAnchor** inherits the **treeAnchor**. This transform is intended to be used with [dot](#dot), [text](#text), and other point-based marks. This transform is rarely used directly; see the [Plot.tree compound mark](#plottreedata-options).
 
+The treeNode transform will derive output columns for any *options* that have one of the following named node values:
+
+* *node:name* - the node’s name (the last part of its path)
+* *node:path* - the node’s full path
+* *node:internal* - true if the node is internal, or false for leaves
+* *node:depth* - the distance from the node to the root
+* *node:height* - the distance from the node to its deepest descendant
+
+In addition, if any option value is specified as an object with a **node** method, a derived output column will be generated by invoking the **node** method for each node in the tree.
+
 ### Plot.treeLink(*options*)
 
 Based on the tree options described above, populates the **x1**, **y1**, **x2**, and **y2** channels. The following defaults are also applied: the default **curve** is *bump-x*, the default **stroke** is #555, the default **strokeWidth** is 1.5, and the default **strokeOpacity** is 0.5. This transform is intended to be used with [link](#link), [arrow](#arrow), and other two-point-based marks. This transform is rarely used directly; see the [Plot.tree compound mark](#plottreedata-options).
 
+The treeLink transform will derive output columns for any *options* that have one of the following named link values:
+
+* *node:name* - the child node’s name (the last part of its path)
+* *node:path* - the child node’s full path
+* *node:internal* - true if the child node is internal, or false for leaves
+* *node:depth* - the distance from the child node to the root
+* *node:height* - the distance from the child node to its deepest descendant
+* *parent:name* - the parent node’s name (the last part of its path)
+* *parent:path* - the parent node’s full path
+* *parent:depth* - the distance from the parent node to the root
+* *parent:height* - the distance from the parent node to its deepest descendant
+
+In addition, if any option value is specified as an object with a **node** method, a derived output column will be generated by invoking the **node** method for each child node in the tree; likewise if any option value is specified as an object with a **link** method, a derived output column will be generated by invoking the **link** method for each link in the tree, being passed two node arguments, the child and the parent.
+
 ### Plot.tree(*data*, *options*)
 
 A convenience compound mark for rendering a tree diagram, including a [link](#link) to render links from parent to child, an optional [dot](#dot) for nodes, and a [text](#text) for node labels. The link mark uses the [treeLink transform](#plottreelinkoptions), while the dot and text marks use the [treeNode transform](#plottreenodeoptions). The following options are supported:

src/transforms/tree.js

@@ -1,4 +1,5 @@
 import {stratify, tree} from "d3";
+import {ascendingDefined} from "../defined.js";
 import {channel, isObject, one, valueof} from "../options.js";
 import {basic} from "./basic.js";
 
@@ -13,6 +14,7 @@ export function treeNode({
   ...options
 } = {}) {
   treeAnchor = maybeTreeAnchor(treeAnchor);
+  treeSort = maybeTreeSort(treeSort);
   if (frameAnchor === undefined) frameAnchor = treeAnchor.frameAnchor;
   const normalize = normalizer(delimiter);
   const outputs = treeOutputs(options, maybeNodeValue);
@@ -36,13 +38,13 @@ export function treeNode({
       for (const o of outputs) o[output_values] = o[output_setValues]([]);
       for (const facet of facets) {
         const treeFacet = [];
-        const root = rootof(facet);
+        const root = rootof(facet).each(node => node.data = data[node.data]);
         if (treeSort != null) root.sort(treeSort);
         layout(root);
         for (const node of root.descendants()) {
           treeFacet.push(++treeIndex);
+          treeData[treeIndex] = node.data;
           treeAnchor.position(node, treeIndex, X, Y);
-          if (node.data !== undefined) treeData[treeIndex] = data[node.data];
           for (const o of outputs) o[output_values][treeIndex] = o[output_evaluate](node);
         }
         treeFacets.push(treeFacet);
@@ -67,6 +69,7 @@ export function treeLink({
   ...options
 } = {}) {
   treeAnchor = maybeTreeAnchor(treeAnchor);
+  treeSort = maybeTreeSort(treeSort);
   options = {curve, stroke, strokeWidth, strokeOpacity, ...options};
   const normalize = normalizer(delimiter);
   const outputs = treeOutputs(options, maybeLinkValue);
@@ -95,14 +98,14 @@ export function treeLink({
       for (const o of outputs) o[output_values] = o[output_setValues]([]);
       for (const facet of facets) {
         const treeFacet = [];
-        const root = rootof(facet);
+        const root = rootof(facet).each(node => node.data = data[node.data]);
         if (treeSort != null) root.sort(treeSort);
         layout(root);
         for (const {source, target} of root.links()) {
           treeFacet.push(++treeIndex);
+          treeData[treeIndex] = target.data;
           treeAnchor.position(source, treeIndex, X1, Y1);
           treeAnchor.position(target, treeIndex, X2, Y2);
-          if (target.data !== undefined) treeData[treeIndex] = data[target.data];
           for (const o of outputs) o[output_values][treeIndex] = o[output_evaluate](target, source);
         }
         treeFacets.push(treeFacet);
@@ -139,6 +142,20 @@ const treeAnchorRight = {
   }
 };
 
+function maybeTreeSort(sort) {
+  return sort == null || typeof sort === "function" ? sort
+    : `${sort}`.trim().toLowerCase().startsWith("node:") ? nodeSort(maybeNodeValue(sort))
+    : nodeSort(nodeData(sort));
+}
+
+function nodeSort(value) {
+  return (a, b) => ascendingDefined(value(a), value(b));
+}
+
+function nodeData(field) {
+  return node => node.data?.[field];
+}
+
 function normalizer(delimiter = "/") {
   return `${delimiter}` === "/"
     ? P => P // paths are already slash-separated