textLayout option

Author: Fil

docs/marks/tree.md

@@ -75,7 +75,7 @@ Plot.plot({
 ```
 :::
 
-The **treeLayout** option specifies the layout algorithm. The tree mark uses the Reingold–Tilford “tidy” tree algorithm, [d3.tree](https://github.com/d3/d3-hierarchy/blob/main/README.md#tree), by default. The [cluster](#cluster-data-options) convenience method sets **treeLayout** to [d3.cluster](https://github.com/d3/d3-hierarchy/blob/main/README.md#cluster), aligning the leaf nodes. Both default the **textBalanced** option to true, drawing non-leaf node labels to the left of the node.
+The **treeLayout** option specifies the layout algorithm. The tree mark uses the Reingold–Tilford “tidy” tree algorithm, [d3.tree](https://github.com/d3/d3-hierarchy/blob/main/README.md#tree), by default. The [cluster](#cluster-data-options) convenience method sets **treeLayout** to [d3.cluster](https://github.com/d3/d3-hierarchy/blob/main/README.md#cluster), aligning the leaf nodes.
 
 :::plot https://observablehq.com/@observablehq/plot-cluster-flare
 ```js
@@ -151,13 +151,16 @@ The following options are supported:
 * **title** - the text and dot title; defaults to *node:path*
 * **text** - the text label; defaults to *node:name*
 * **textStroke** - the text stroke; defaults to *white*
-* **textBalanced** - the orientation of non-leaf labels
-* **dx** - the text horizontal offset; defaults to 6 if left-anchored, or -6 if right-anchored
+* **textLayout** - the text anchoring layout
+* **dx** - the text horizontal offset; defaults to 6
 * **dy** - the text vertical offset; defaults to 0
 
 Any additional *options* are passed through to the constituent link, dot, and text marks and their corresponding treeLink or treeNode transform.
 
-Text labels for leaf nodes are drawn to the right of the node; the **textBalanced** option controls whether labels for non-leaf nodes are drawn to the left of the node. It defaults to true, unless a **treeLayout** is specified (*e.g.*, the custom indent layout above).
+The **textLayout** option controls how text labels are anchored to the node. Two layouts are supported:
+
+* *mirrored* - leaf-node labels are left-anchored, and non-leaf nodes right-anchored (with a -dx offset); default unless a **treeLayout** is specified
+* *normal* - all labels are left-anchored; default if a **treeLayout** is specified
 
 ## tree(*data*, *options*)
 
@@ -173,4 +176,4 @@ Returns a new tree mark with the given *data* and *options*.
 Plot.cluster(flare, {path: "name", delimiter: "."})
 ```
 
-Like [tree](#tree-data-options), except sets the **treeLayout** option to [d3.cluster](https://github.com/d3/d3-hierarchy/blob/main/README.md#cluster), aligning leaf nodes.
+Like [tree](#tree-data-options), except sets the **treeLayout** option to [d3.cluster](https://github.com/d3/d3-hierarchy/blob/main/README.md#cluster), aligning leaf nodes, and defaults the **textLayout** option to *mirrored*.

src/marks/tree.d.ts

@@ -21,10 +21,12 @@ export interface TreeOptions extends DotOptions, LinkOptions, TextOptions, TreeT
   textStroke?: MarkOptions["stroke"];
 
   /**
-   * Whether labels for non-leaf nodes are drawn to the left of the node;
-   * defaults to true unless a **treeLayout** is specified.
+   * Layout for node labels: if *mirrored*, leaf-node labels are left-anchored,
+   * and non-leaf nodes right-anchored (with a -dx offset). If *normal*, all
+   * labels are left-anchored. Defaults to *mirrored* unless a **treeLayout**
+   * has been specified.
    */
-  textBalanced?: boolean;
+  textLayout?: "mirrored" | "normal";
 }
 
 /**
@@ -46,7 +48,7 @@ export function tree(data?: Data, options?: TreeOptions): CompoundMark;
  * option, placing leaf nodes of the tree at the same depth. Equivalent to:
  *
  * ```js
- * Plot.tree(data, {...options, treeLayout: d3.cluster})
+ * Plot.tree(data, {...options, treeLayout: d3.cluster, textLayout: "mirrored"})
  * ```
  *
  * [1]: https://github.com/d3/d3-hierarchy/blob/main/README.md#cluster

src/marks/tree.js

@@ -1,10 +1,11 @@
-import {tree as Tree, cluster as Cluster} from "d3";
+import {cluster as Cluster} from "d3";
 import {marks} from "../mark.js";
 import {isNoneish} from "../options.js";
 import {maybeTreeAnchor, treeLink, treeNode} from "../transforms/tree.js";
 import {dot} from "./dot.js";
 import {link} from "./link.js";
 import {text} from "./text.js";
+import {keyword} from "../options.js";
 
 export function tree(
   data,
@@ -28,14 +29,17 @@ export function tree(
     dx,
     dy,
     textAnchor,
-    textBalanced,
+    textLayout,
     ...options
   } = {}
 ) {
-  const {treeLayout = Tree} = options;
   if (dx === undefined) dx = maybeTreeAnchor(options.treeAnchor).dx;
   if (textAnchor !== undefined) throw new Error("textAnchor is not a configurable tree option");
-  if (textBalanced === undefined) textBalanced = treeLayout === Tree || treeLayout === Cluster;
+  textLayout = keyword(
+    textLayout === undefined ? (options.treeLayout === undefined ? "mirrored" : "normal") : textLayout,
+    "textLayout",
+    ["mirrored", "normal"]
+  );
   function treeText(textOptions) {
     return text(
       data,
@@ -71,7 +75,7 @@ export function tree(
     ),
     dotDot ? dot(data, treeNode({fill: fill === undefined ? "node:internal" : fill, title, ...options})) : null,
     textText != null
-      ? textBalanced
+      ? textLayout === "mirrored"
         ? [
             treeText({textAnchor: "start", treeFilter: "node:external"}),
             treeText({textAnchor: "end", treeFilter: "node:internal", dx: -dx})
@@ -82,5 +86,5 @@ export function tree(
 }
 
 export function cluster(data, options) {
-  return tree(data, {...options, treeLayout: Cluster});
+  return tree(data, {textLayout: "mirrored", ...options, treeLayout: Cluster});
 }