@euphrasiologist/lwphylo 1.4.0 → 1.5.1

package/README.md

@@ -10,16 +10,22 @@ Visit https://euphrasiologist.github.io/lwPhylo/ to see examples and live render
 
 Newick trees can be parsed using the `readTree()` function. This object can then be wrapped in three main functions; `rectangleLayout()` to produce a "regular" phylogenetic tree, `radialLayout()` to produce a circular phylogeny, and `unrooted()` to produce an unrooted tree via the equal angle layout algorithm.
 
-Need a tree to experiment with? `randomTree(nTips, { maxBranchLength, labelPrefix, seed })` generates a random bifurcating tree in the same node shape as `readTree()`, ready to pass straight into any of the layout functions. `toNewick(tree)` serializes one of these parsed tree objects back to a Newick string, so it can be handed to `drawPhylogeny()` (which expects Newick text): `drawPhylogeny(toNewick(randomTree(20)))`.
+Need a tree to experiment with? `randomTree(nTips, { maxBranchLength, labelPrefix, seed })` generates a random bifurcating tree in the same node shape as `readTree()`, ready to pass straight into any of the layout functions. `toNewick(tree)` serializes one of these parsed tree objects back to a Newick string.
 
 `ladderize(tree, { ascending })` and `rotate(tree, nodeId)` change tip order by reordering a node's children in place — ladderize sorts every clade by descendant tip count (smallest first by default), rotate flips the child order at one node (the root, if no id is given).
 
-`drawPhylogeny(newick, options)` accepts, in addition to `layout`/`width`/`height`/`tipLabels`/`labelFontSize`/`highlightTips`:
+`drawPhylogeny(input, options)` accepts either a Newick string or an already-parsed tree object (from `readTree()`/`randomTree()`) as `input`. Passing the same parsed tree object back in across re-renders — e.g. after mutating it with `rotate()` — keeps node ids stable, which `onNodeClick` (below) relies on. Options, in addition to `layout`/`width`/`height`/`tipLabels`/`labelFontSize`/`highlightTips`:
 - `tipRadius` — px radius of tip circles.
 - `internalNodeCircles` (bool) + `internalNodeRadius` — draw a circle at every internal node.
 - `nodeLabels` (bool) + `nodeLabelFontSize` — draw text labels (e.g. clade/support values) at internal nodes that have one.
 - `scaleBar` — `true` for an auto-sized branch-length scale bar, a number for an explicit length in branch-length units, or `{ length, x, y, label }` for full control.
 - `alignTipLabels` (bool, rect & radial layouts) — align tip labels to a common column/ring, with dashed guide lines back to each tip's true position.
+- `onNodeClick(node, event)` — fires when an internal node circle is clicked (requires `internalNodeCircles: true`).
+- `container` (DOM element or CSS selector) + `rotateOnClick` (bool) — the batteries-included version of click-to-rotate: with both set, `drawPhylogeny` mounts the SVG into `container` itself and, on every internal-node click, rotates that clade and redraws back into the same container — no manual render loop needed:
+  ```js
+  drawPhylogeny(newickString, { layout: "rect", container: "#tree", rotateOnClick: true });
+  ```
+  `rotateOnClick` auto-enables `internalNodeCircles` unless you set it explicitly. A supplied `onNodeClick` still fires too, before the rotate. Without a `container`, `rotateOnClick` throws — there'd be nowhere to put the redrawn SVG. For finer control (e.g. wrapping the SVG in your own zoom/pan `<g>`, as the demo site does), skip `container`/`rotateOnClick` and drive it yourself with `onNodeClick` + `rotate()` as shown in the demo's own source.
 
 ### Acknowledgements
 

package/dist/drawPhylogeny.cjs

@@ -837,6 +837,20 @@ function unrooted (node) {
   return data;
 }
 
+/**
+ * Reverse the child order at one node, flipping which side of the tree
+ * that clade's descendants are drawn on. Defaults to the root. Mutates
+ * the tree in place.
+ */
+function rotate(tree, nodeId = tree.id) {
+  const target = preorder(tree).find((n) => n.id === nodeId);
+  if (!target) {
+    throw new Error(`No node with id ${nodeId} found in tree`);
+  }
+  target.children.reverse();
+  return tree;
+}
+
 /**
  * Parse a Newick tree string into a doubly-linked list of JS Objects.
  * Assigns labels, branch lengths, and node IDs (tips before internals if input emits them that way).
@@ -946,9 +960,12 @@ function addScaleBar(svg, { scale, basis, defaultX, defaultY, scaleBar, fontSize
     .text(opts.label ?? String(length));
 }
 
-function drawPhylogeny(
-  treeText,
-  {
+// input: a Newick string, or an already-parsed tree (the node shape returned
+// by readTree()/randomTree()). Passing the same parsed tree object back in
+// across re-renders (e.g. after mutating it with rotate()) keeps node ids
+// stable, which onNodeClick below relies on.
+function drawPhylogeny(input, options = {}) {
+  const {
     layout = "rect", // rect/radial/unrooted
     width = 800,
     height = 800,
@@ -959,12 +976,14 @@ function drawPhylogeny(
     tipLabels = true,
     labelFontSize = 10, // font size (px) for tip labels
     tipRadius, // px radius of tip dots; defaults to each layout's original size
-    internalNodeCircles = false, // draw a circle at every internal (non-tip) node
     internalNodeRadius = 3, // px radius for internal node circles
     nodeLabels = false, // draw text labels at internal nodes (e.g. clade/support labels)
     nodeLabelFontSize, // defaults to labelFontSize
     scaleBar = false, // false | true | number (branch-length units) | { length, x, y, label }
     alignTipLabels = false, // rect & radial only: align tip labels to a common column/ring, with dashed guide lines back to the true tip position
+    container, // DOM element or CSS selector — if given, drawPhylogeny mounts the SVG itself instead of just returning it
+    rotateOnClick = false, // click an internal node circle to rotate its children in place and auto-redraw (requires container)
+    onNodeClick, // (node, event) => void — fires when an internal node circle is clicked (requires internalNodeCircles: true)
     showTooltips = true,
     tooltipFormatter = (d, rtt) =>
       `${d.thisLabel ?? "(unnamed)"}\nroot→tip: ${(+rtt).toFixed(4)}`,
@@ -973,12 +992,46 @@ function drawPhylogeny(
     highlightTips = [], // array of tip labels or ids for static highlight (optional)
     highlightStroke = "#e63946",
     highlightWidth = 2.5
-  } = {}
-) {
+  } = options;
+  // rotateOnClick needs internal node circles to click on; auto-enable them
+  // unless the caller explicitly said otherwise.
+  const internalNodeCircles = options.internalNodeCircles ?? rotateOnClick;
 
   // shared helpers
   const isNumber = (x) => typeof x === "number" && Number.isFinite(x);
   const nodeLabelSize = nodeLabelFontSize ?? labelFontSize;
+  const parsedTree = (input && typeof input === "object" && Array.isArray(input.children))
+    ? input
+    : readTree(input);
+
+  const mountEl = typeof container === "string"
+    ? (typeof document !== "undefined" ? document.querySelector(container) : null)
+    : (container ?? null);
+
+  if (rotateOnClick && !mountEl) {
+    throw new Error(
+      "rotateOnClick requires a `container` (a DOM element or CSS selector) so drawPhylogeny can mount the redrawn SVG after each rotation."
+    );
+  }
+
+  // fires the caller's onNodeClick (if any), then handles the rotate+redraw itself
+  const effectiveOnNodeClick = (onNodeClick || rotateOnClick)
+    ? (node, event) => {
+      if (typeof onNodeClick === "function") onNodeClick(node, event);
+      if (rotateOnClick) {
+        rotate(parsedTree, node.thisId);
+        drawPhylogeny(parsedTree, options);
+      }
+    }
+    : undefined;
+
+  function mount(svgNode) {
+    if (mountEl) {
+      mountEl.innerHTML = "";
+      mountEl.appendChild(svgNode);
+    }
+    return svgNode;
+  }
   // Works for both radial (uses `r`) and rect (uses `x1`).
   // Falls back to summing branchLength up to the root if neither is present.
   function makeRootToTipGetter(byId, { prefer = "auto" } = {}) {
@@ -1007,7 +1060,7 @@ function drawPhylogeny(
 
   if (layout === "rect") {
     // RECTANGULAR LAYOUT
-    const tree_df = rectangleLayout(readTree(treeText));
+    const tree_df = rectangleLayout(parsedTree);
     const horizontal = tree_df.horizontal_lines;
     const vertical = tree_df.vertical_lines;
     const tips = horizontal.filter((d) => d.isTip);
@@ -1118,6 +1171,12 @@ function drawPhylogeny(
           .append("title")
           .text((d) => tooltipFormatter(d, rootToTip(d.thisId)));
       }
+
+      if (effectiveOnNodeClick) {
+        internalDots
+          .style("cursor", "pointer")
+          .on("click", (event, d) => effectiveOnNodeClick(d, event));
+      }
     }
 
     // internal node labels (optional)
@@ -1247,13 +1306,12 @@ function drawPhylogeny(
       });
     }
 
-    return svg.node();
+    return mount(svg.node());
   } else if (layout === "radial") {
     // RADIAL LAYOUT
     if (width !== height) {
       throw new Error("width and height must be the same for radial layout");
     }
-    const parsedTree = readTree(treeText);
     const rad = radialLayout(parsedTree, {
       angleStrategy: "fan",
       arcsStyle: "fan"
@@ -1473,6 +1531,12 @@ function drawPhylogeny(
           .append("title")
           .text((d) => tooltipFormatter(d, rootToTip(d.thisId)));
       }
+
+      if (effectiveOnNodeClick) {
+        internalDots
+          .style("cursor", "pointer")
+          .on("click", (event, d) => effectiveOnNodeClick(d, event));
+      }
     }
 
     // ===== INTERNAL NODE LABELS (optional) =====
@@ -1670,10 +1734,9 @@ function drawPhylogeny(
       });
     }
 
-    return svg.node();
+    return mount(svg.node());
   } else if (layout === "unrooted") {
     // UNROOTED LAYOUT
-    const parsedTree = readTree(treeText);
     const unrootedPhylo = unrooted(parsedTree);
 
     const w = width;
@@ -1735,6 +1798,13 @@ function drawPhylogeny(
       .attr("stroke-width", 2)
       .attr("fill", (d) => (d.isTip ? "black" : "white"));
 
+    if (internalNodeCircles && effectiveOnNodeClick) {
+      nodes
+        .filter((d) => !d.isTip)
+        .style("cursor", "pointer")
+        .on("click", (event, d) => effectiveOnNodeClick(d, event));
+    }
+
     if (nodeLabels) {
       const labeledInternalNodes = unrootedPhylo.data.filter((d) => !d.isTip && d.thisLabel);
       group
@@ -1897,7 +1967,7 @@ function drawPhylogeny(
       });
     }
 
-    return svg.node();
+    return mount(svg.node());
   } else {
     throw new Error(
       "Unsupported layout type. Use 'rect', 'radial', or 'unrooted'."