@gen-epix/ui-phylogenetic-tree 2.0.0

package/dist/utils/NewickUtil/index.js

@@ -0,0 +1,50 @@
+import { i as e, n as t, r as n, t as r } from "../../_chunks/identity.js";
+import { StringUtil as i } from "@gen-epix/ui-core/utils/StringUtil";
+//#region ../../node_modules/.pnpm/lodash@4.18.1/node_modules/lodash/_baseSum.js
+var a = /* @__PURE__ */ n(((e, t) => {
+	function n(e, t) {
+		for (var n, r = -1, i = e.length; ++r < i;) {
+			var a = t(e[r]);
+			a !== void 0 && (n = n === void 0 ? a : n + a);
+		}
+		return n;
+	}
+	t.exports = n;
+})), o = /* @__PURE__ */ e((/* @__PURE__ */ n(((e, t) => {
+	var n = a(), i = r();
+	function o(e) {
+		return e && e.length ? n(e, i) : 0;
+	}
+	t.exports = o;
+})))(), 1), s = class e {
+	static getSortedNames(t) {
+		return [...(t.children ?? []).map((t) => e.getSortedNames(t)).flat(), ...t.children ? [] : [t.name]];
+	}
+	static parse(e) {
+		let n = [], r = {}, a = e.split(/(;|\(|\)|,|:)/).map((e) => e.trim()).filter((e) => e);
+		for (let e = 0; e < a.length; e++) {
+			let s = a[e], c = {}, l = a[e - 1];
+			switch (s) {
+				case ",":
+					n[n.length - 1].children.push(c), r = c;
+					break;
+				case ";": break;
+				case ":": break;
+				case "(":
+					r.children = [c], n.push(r), r = c;
+					break;
+				case ")":
+					r = n.pop(), r.children.forEach((e) => {
+						e.children || (e.size = 1, e.maxBranchLength = new t(e.branchLength ?? 0), e.subTreeLeaveNames = [e.name], e.subTreeNames = e.subTreeNames ?? []);
+					}), r.size = (0, o.default)(r.children.map((e) => e.size)), r.subTreeNames = r.children.map((e) => e.subTreeNames).flat().filter((e) => e), r.subTreeLeaveNames = r.children.map((e) => e.subTreeLeaveNames).flat().filter((e) => e), r.maxBranchLength = t.max(...r.children.map((e) => e.maxBranchLength));
+					break;
+				default: l === ")" || l === "(" || l === "," ? r.name = s : l === ":" && (r.branchLength = new t(s), r.subTreeNames = (r.children ?? []).map((e) => [e.name, ...e.subTreeNames]).flat().filter((e) => e), r.subTreeLeaveNames = (r.children ?? []).map((e) => e.subTreeLeaveNames).flat().filter((e) => e), r.maxBranchLength = r.branchLength.add(r.children?.length ? t.max(...r.children.map((e) => e.maxBranchLength)) : 0), r.name = r.name || `Generated-${i.createHash(r.subTreeNames.join(","))}`);
+			}
+		}
+		return r.branchLength = r.branchLength ?? new t(0), r.maxBranchLength = r.children?.length ? t.max(...r.children.map((e) => e.maxBranchLength)) : new t(0), r.name = "Root", r;
+	}
+};
+//#endregion
+export { s as NewickUtil };
+
+//# sourceMappingURL=index.js.map

package/dist/utils/NewickUtil/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../../node_modules/.pnpm/lodash@4.18.1/node_modules/lodash/_baseSum.js","../../../../../node_modules/.pnpm/lodash@4.18.1/node_modules/lodash/sum.js","../../../src/utils/NewickUtil/NewickUtil.ts"],"sourcesContent":["/**\n * The base implementation of `_.sum` and `_.sumBy` without support for\n * iteratee shorthands.\n *\n * @private\n * @param {Array} array The array to iterate over.\n * @param {Function} iteratee The function invoked per iteration.\n * @returns {number} Returns the sum.\n */\nfunction baseSum(array, iteratee) {\n  var result,\n      index = -1,\n      length = array.length;\n\n  while (++index < length) {\n    var current = iteratee(array[index]);\n    if (current !== undefined) {\n      result = result === undefined ? current : (result + current);\n    }\n  }\n  return result;\n}\n\nmodule.exports = baseSum;\n","var baseSum = require('./_baseSum'),\n    identity = require('./identity');\n\n/**\n * Computes the sum of the values in `array`.\n *\n * @static\n * @memberOf _\n * @since 3.4.0\n * @category Math\n * @param {Array} array The array to iterate over.\n * @returns {number} Returns the sum.\n * @example\n *\n * _.sum([4, 2, 8, 6]);\n * // => 20\n */\nfunction sum(array) {\n  return (array && array.length)\n    ? baseSum(array, identity)\n    : 0;\n}\n\nmodule.exports = sum;\n","import { Decimal } from 'decimal.js';\nimport sum from 'lodash/sum';\nimport { StringUtil } from '@gen-epix/ui-core/utils/StringUtil';\n\nimport type { TreeNode } from '../../models/tree';\n\nexport class NewickUtil {\n  public static getSortedNames(node: TreeNode): string[] {\n    return [\n      ...(node.children ?? []).map(child => NewickUtil.getSortedNames(child)).flat(),\n      ...(!node.children ? [node.name] : []),\n    ];\n  }\n\n  public static parse(newick: string): TreeNode {\n    const ancestors: Array<Partial<TreeNode>> = [];\n    let tree: Partial<TreeNode> = {};\n    const tokens = newick.split(/(;|\\(|\\)|,|:)/).map(x => x.trim()).filter(x => x);\n    for (let i = 0; i < tokens.length; i++) {\n      const token = tokens[i];\n      const subtree: Partial<TreeNode> = {};\n      const x = tokens[i - 1];\n      switch (token) {\n        case ',': // another branch\n          ancestors[ancestors.length - 1].children.push(subtree);\n          tree = subtree;\n          break;\n        case ';': // end of tree, nothing to do\n          break;\n        case ':': // optional length next\n          break;\n        case '(': // new children\n          tree.children = [subtree];\n          ancestors.push(tree);\n          tree = subtree;\n          break;\n        case ')': // optional name next\n          tree = ancestors.pop();\n          tree.children.forEach(child => {\n            if (!child.children) {\n              child.size = 1;\n              child.maxBranchLength = new Decimal(child.branchLength ?? 0);\n              child.subTreeLeaveNames = [child.name];\n              child.subTreeNames = child.subTreeNames ?? [];\n            }\n          });\n          tree.size = sum(tree.children.map(child => child.size));\n          tree.subTreeNames = tree.children.map(child => child.subTreeNames).flat().filter(n => n);\n          tree.subTreeLeaveNames = tree.children.map(child => child.subTreeLeaveNames).flat().filter(n => n);\n          tree.maxBranchLength = Decimal.max(...tree.children.map(child => child.maxBranchLength));\n          break;\n        default:\n          if (x === ')' || x === '(' || x === ',') {\n            tree.name = token;\n          } else if (x === ':') {\n            tree.branchLength = new Decimal(token);\n            tree.subTreeNames = (tree.children ?? []).map(child => [child.name, ...child.subTreeNames]).flat().filter(n => n);\n            tree.subTreeLeaveNames = (tree.children ?? []).map(child => child.subTreeLeaveNames).flat().filter(n => n);\n            tree.maxBranchLength = tree.branchLength.add(tree.children?.length ? Decimal.max(...tree.children.map(child => child.maxBranchLength)) : 0);\n            tree.name = tree.name || `Generated-${StringUtil.createHash(tree.subTreeNames.join(','))}`;\n          }\n      }\n    }\n    tree.branchLength = tree.branchLength ?? new Decimal(0);\n    tree.maxBranchLength = tree.children?.length ? Decimal.max(...tree.children.map(child => child.maxBranchLength)) : new Decimal(0);\n    tree.name = 'Root';\n    return tree;\n  }\n}\n"],"x_google_ignoreList":[0,1],"mappings":"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"}

package/dist/utils/TreeUtil/TreeUtil.d.ts

@@ -0,0 +1,496 @@
+import { Decimal } from 'decimal.js';
+import { TreeAssembly, TreeNode, TreePathProperties } from '../../models/tree';
+type TickerMarkScale = [number, number, number];
+export declare class TreeUtil {
+    /**
+     * Traverses the tree and produces a {@link TreeAssembly} containing all
+     * pre-computed `Path2D` shapes and metadata needed to render the tree.
+     *
+     * Leaf nodes are assembled in DFS order (incrementing `leafIndex`), which
+     * determines their vertical position. Ancestor nodes are positioned vertically
+     * at the midpoint of their first and last child.
+     *
+     * @param params.rootNode - The root of the tree to assemble.
+     * @param params.treeCanvasWidth - Width of the tree canvas in pixels, used for support lines.
+     * @param params.pixelToGeneticDistanceRatio - Pixels per unit of genetic distance.
+     * @param params.itemHeight - Height of each row/item in pixels.
+     * @param params.sortedLeafNames - Custom sorting order of leaf nodes by name, derived from ordering (e.g. table row order). Must contain all leaf node names.
+     * @returns A fully populated {@link TreeAssembly} ready for rendering.
+     */
+    static assembleTree(params: {
+        ancestorDotRadius: number;
+        itemHeight: number;
+        leafDotRadius: number;
+        minimumDistancePercentageToShowLabel: number;
+        pixelToGeneticDistanceRatio: number;
+        rootNode: TreeNode;
+        sortedLeafNames: string[];
+        treeCanvasWidth: number;
+        treePadding: number;
+    }): TreeAssembly;
+    /**
+     * Assigns a dot-notation address to every node in the tree, representing its
+     * position in the hierarchy (e.g. `"1.2.1"`). Zero-branch-length children are
+     * always placed at index `1`; other children are indexed starting at `1` or
+     * `2` depending on whether a zero-branch sibling is present.
+     *
+     * @param rootNode - The root of the tree to address.
+     * @returns A map from node name to its dot-notation address string.
+     */
+    static createTreeAddresses(rootNode: TreeNode): {
+        [key: string]: string;
+    };
+    /**
+     * Draws a thin horizontal divider line across the full canvas width.
+     *
+     * Used to visually separate the scale header from the tree body.
+     *
+     * @param params.canvas - The canvas element to draw onto.
+     * @param params.y - Vertical position of the divider in logical pixels.
+     * @param params.devicePixelRatio - Screen DPR for correct positioning.
+     */
+    static drawDivider(params: {
+        canvas: HTMLCanvasElement;
+        devicePixelRatio: number;
+        y: number;
+    }): void;
+    /**
+     * Draws vertical dashed guide lines on the canvas at each tick mark position.
+     *
+     * @param params.canvas - The canvas element to draw onto.
+     * @param params.tickerMarkScale - Scale tuple from {@link getTickMarkScale}.
+     * @param params.geneticTreeWidth - Total genetic width of the tree.
+     * @param params.pixelToGeneticDistanceRatio - Pixels per unit of genetic distance.
+     * @param params.devicePixelRatio - Screen DPR.
+     * @param params.startY - Top of the drawn range in logical pixels (default 0).
+     * @param params.endY - Bottom of the drawn range in logical pixels (default canvas height).
+     * @param params.zoomLevel - Current zoom level.
+     * @param params.horizontalScrollPosition - Current horizontal scroll offset in pixels.
+     * @param params.regularFillColorSupportLine - Color for the guide lines.
+     */
+    static drawGuides(params: {
+        canvas: HTMLCanvasElement;
+        devicePixelRatio: number;
+        endY?: number;
+        geneticTreeWidth: Decimal;
+        horizontalScrollPosition: number;
+        paddingBottom?: number;
+        paddingTop?: number;
+        pixelToGeneticDistanceRatio: number;
+        regularFillColorSupportLine: string;
+        startY?: number;
+        tickerMarkScale: TickerMarkScale;
+        treePadding: number;
+        zoomLevel: number;
+    }): void;
+    /**
+     * Draws the genetic distance scale labels onto the canvas header area.
+     *
+     * Labels are drawn in reverse order (right-to-left distance decreasing) so
+     * the leftmost label shows the largest genetic distance.
+     *
+     * @param params.canvas - The canvas element to draw onto.
+     * @param params.fontFamily - Font family for the scale labels.
+     * @param params.scaleColor - Fill colour for the label text.
+     * @param params.headerHeight - Height of the header area in logical pixels.
+     * @param params.tickerMarkScale - Scale tuple from {@link getTickMarkScale}.
+     * @param params.geneticTreeWidth - Total genetic width of the tree.
+     * @param params.pixelToGeneticDistanceRatio - Pixels per unit of genetic distance.
+     * @param params.zoomLevel - Current zoom level.
+     * @param params.devicePixelRatio - Screen DPR.
+     * @param params.horizontalScrollPosition - Current horizontal scroll offset in pixels.
+     */
+    static drawScale(params: {
+        canvas: HTMLCanvasElement;
+        devicePixelRatio: number;
+        fontFamily: string;
+        geneticTreeWidth: Decimal;
+        headerHeight: number;
+        horizontalScrollPosition: number;
+        pixelToGeneticDistanceRatio: number;
+        scaleColor: string;
+        tickerMarkScale: TickerMarkScale;
+        treePadding: number;
+        zoomLevel: number;
+    }): void;
+    /**
+     * Renders the pre-assembled tree shapes onto a canvas using the 2D context.
+     *
+     * Applies a transform for zoom and scroll, then draws in order:
+     * vertical ancestor lines -> horizontal ancestor lines -> (linked) support lines
+     * -> (highlighted) distance labels -> ancestor dots -> leaf branch lines -> leaf dots.
+     *
+     * When nodes are highlighted, non-highlighted shapes are dimmed via `dimFn`.
+     * Leaf dot colours come from `nodeNameColors` when available.
+     *
+     * @param params.canvas - The canvas element to draw onto.
+     * @param params.treeAssembly - Pre-computed tree shapes from {@link assembleTree}.
+     * @param params.nodeNameColors - Colour mapping per node name for leaf dots.
+     * @param params.treeColor - Base colour for tree lines and dots.
+     * @param params.treeFont - CSS font string for distance labels.
+     * @param params.dimFn - Returns a dimmed version of a colour for non-highlighted shapes.
+     * @param params.supportLineColorLinked - Colour for support lines when linked.
+     * @param params.supportLineColorUnlinked - Colour for support lines when unlinked.
+     * @param params.zoomLevel - Current zoom level applied as a canvas transform.
+     * @param params.highlightedNodeNames - Node names to highlight; all others are dimmed.
+     * @param params.verticalScrollPosition - Vertical scroll offset in pixels.
+     * @param params.horizontalScrollPosition - Horizontal scroll offset in pixels.
+     * @param params.shouldShowDistances - Whether to render branch distance labels.
+     * @param params.devicePixelRatio - Screen DPR for crisp rendering on HiDPI displays.
+     * @param params.isLinked - Whether to draw the dashed support lines linking leaf nodes to the table.
+     * @param params.shouldShowSupportLinesWhenUnlinked - Whether to render support lines when unlinked.
+     */
+    static drawTree(params: {
+        canvas: HTMLCanvasElement;
+        devicePixelRatio: number;
+        dimFn: (color: string) => string;
+        headerHeight?: number;
+        highlightedNodeNames: string[];
+        horizontalScrollPosition: number;
+        isLinked: boolean;
+        itemHeight: number;
+        nodeNameColors: {
+            [key: string]: string;
+        } | null;
+        range: {
+            endIndex: number;
+            startIndex: number;
+        };
+        scrollPosition?: number;
+        shouldShowDistances: boolean;
+        shouldShowSupportLinesWhenUnlinked: boolean;
+        supportLineColorLinked: string;
+        supportLineColorUnlinked: string;
+        treeAssembly: TreeAssembly;
+        treeColor: string;
+        treeFont: string;
+        verticalScrollPosition: number;
+        zoomLevel: number;
+    }): void;
+    /**
+     * Fully redraws the tree canvas from scratch.
+     *
+     * Resets the canvas, resizes it to match its CSS layout size at the current
+     * DPR, then sequentially calls {@link drawBackground}, {@link drawGuides},
+     * {@link drawScale}, and {@link drawTree}.
+     *
+     * @param params.canvas - The canvas element to draw onto.
+     * @param params.backgroundColor - Fill colour for the canvas background.
+     * @param params.treeAssembly - Pre-computed tree shapes from {@link assembleTree}.
+     * @param params.nodeNameColors - Colour mapping per node name for leaf dots.
+     * @param params.treeColor - Base colour for tree lines and dots.
+     * @param params.treeFont - CSS font string for distance labels.
+     * @param params.dimFn - Returns a dimmed version of a colour for non-highlighted shapes.
+     * @param params.fontFamily - Font family for scale labels.
+     * @param params.scaleColor - Fill colour for scale label text.
+     * @param params.supportLineColorLinked - Colour for support lines when linked.
+     * @param params.supportLineColorUnlinked - Colour for support lines when unlinked.
+     * @param params.regularFillColorSupportLine - Colour for the dashed guide lines.
+     * @param params.zoomLevel - Current zoom level.
+     * @param params.isLinked - Whether to draw dashed support lines.
+     * @param params.highlightedNodeNames - Node names to highlight.
+     * @param params.verticalScrollPosition - Vertical scroll offset in pixels.
+     * @param params.horizontalScrollPosition - Horizontal scroll offset in pixels.
+     * @param params.treeCanvasWidth - Logical canvas width in pixels.
+     * @param params.treeCanvasHeight - Logical canvas height in pixels.
+     * @param params.headerHeight - Height of the scale header area in logical pixels.
+     * @param params.pixelToGeneticDistanceRatio - Pixels per unit of genetic distance.
+     * @param params.tickerMarkScale - Scale tuple from {@link getTickMarkScale}.
+     * @param params.shouldShowDistances - Whether to render branch labels.
+     * @param params.shouldShowSupportLinesWhenUnlinked - Whether to render support lines when unlinked.
+     * @param params.devicePixelRatio - Screen DPR for HiDPI rendering.
+     * @param params.geneticTreeWidth - Total genetic width of the tree.
+     */
+    static drawTreeCanvas(params: {
+        backgroundColor: string;
+        canvas: HTMLCanvasElement;
+        devicePixelRatio: number;
+        dimFn: (color: string) => string;
+        fontFamily: string;
+        geneticTreeWidth: Decimal;
+        headerHeight?: number;
+        highlightedNodeNames?: string[];
+        horizontalScrollPosition: number;
+        isLinked: boolean;
+        itemHeight: number;
+        nodeNameColors: {
+            [key: string]: string;
+        } | null;
+        pixelToGeneticDistanceRatio: number;
+        range: {
+            endIndex: number;
+            startIndex: number;
+        };
+        regularFillColorSupportLine: string;
+        scaleColor: string;
+        scrollPosition?: number;
+        shouldShowDistances: boolean;
+        shouldShowSupportLinesWhenUnlinked: boolean;
+        supportLineColorLinked: string;
+        supportLineColorUnlinked: string;
+        tickerMarkScale: TickerMarkScale;
+        treeAssembly: TreeAssembly;
+        treeCanvasHeight: number;
+        treeCanvasWidth: number;
+        treeColor: string;
+        treeFont: string;
+        treePadding: number;
+        verticalScrollPosition: number;
+        zoomLevel: number;
+    }): void;
+    /**
+     * Finds and returns a new root node for re-rooting the tree.
+     *
+     * When `selector` is `'node'`, the node with the given name becomes the new root.
+     * When `selector` is `'parent'`, the parent of the node with the given name is returned.
+     *
+     * The returned node has its `branchLength` reset to `0` and its `maxBranchLength`
+     * adjusted by subtracting the original branch length, so the scale remains consistent.
+     *
+     * @param rootNode - The current root of the tree.
+     * @param nodeName - Name of the node to search for.
+     * @param selector - Whether to return the matching node itself (`'node'`) or its parent (`'parent'`).
+     * @returns A shallow copy of the new root with adjusted branch length properties.
+     */
+    static findNewTreeRoot(rootNode: TreeNode, nodeName: string, selector: 'node' | 'parent'): TreeNode;
+    /**
+     * Finds the smallest non-zero branch length among all leaf nodes in the tree.
+     *
+     * This value is used as the minimum scale unit when computing tick mark
+     * intervals, ensuring the scale never subdivides below a single measurable step.
+     *
+     * @param tree - The root node of the tree to inspect.
+     * @returns The minimum positive branch length found on any leaf, or `Infinity`
+     *   if the tree is empty or all leaves have zero/undefined branch lengths.
+     */
+    static getMinGeneticScaleUnit(tree: TreeNode): number;
+    /**
+     * Calculates the new scroll position after a zoom level change so that the
+     * point under the cursor stays in the same visual position.
+     *
+     * @param params.eventOffset - Pixel offset of the zoom event (e.g. mouse position) within the canvas.
+     * @param params.scrollPosition - Current scroll position before the zoom change.
+     * @param params.dimensionSize - Full logical size of the scrollable dimension in pixels.
+     * @param params.currentZoomLevel - The zoom level before the change.
+     * @param params.newZoomLevel - The zoom level after the change.
+     * @returns The adjusted scroll position that keeps the cursor-point visually stable.
+     */
+    static getNewScrollPositionForZoomLevel(params: {
+        currentZoomLevel: number;
+        dimensionSize: number;
+        eventOffset: number;
+        newZoomLevel: number;
+        scrollPosition: number;
+    }): number;
+    /**
+     * Performs a hit-test against the tree assembly's path maps to find the
+     * tree node or line segment under the mouse cursor.
+     *
+     * Checks in priority order: node dots (via `isPointInPath`) -> horizontal
+     * branch lines (with ±1 px vertical tolerance) -> vertical connector lines
+     * (with ±1 px horizontal tolerance).
+     *
+     * @param params.canvas - The canvas element that received the mouse event.
+     * @param params.event - The mouse event providing cursor coordinates.
+     * @param params.treeAssembly - The assembly containing path maps to hit-test against.
+     * @param params.devicePixelRatio - Screen DPR for correct coordinate scaling.
+     * @returns The {@link TreePathProperties} of the hit shape, or `undefined` if nothing was hit.
+     */
+    static getPathPropertiesFromCanvas(params: {
+        canvas: HTMLCanvasElement;
+        devicePixelRatio: number;
+        event: MouseEvent;
+        treeAssembly: TreeAssembly;
+    }): TreePathProperties;
+    /**
+     * Clamps X and Y scroll positions to their valid ranges for the current
+     * canvas dimensions, zoom level, and link state.
+     *
+     * When the tree is linked and at zoom level 1, y-scrolling is constrained
+     * tightly to the tree's pixel height. When unlinked or zoomed, the bounds
+     * include the full canvas extent to allow free panning.
+     *
+     * Also applies a device-pixel-ratio-dependent correction offset to prevent
+     * subtle over-scroll artefacts at non-integer DPR values (e.g. browser zoom).
+     *
+     * @param params.positionX - Requested horizontal scroll position.
+     * @param params.positionY - Requested vertical scroll position.
+     * @param params.treeCanvasWidth - Logical canvas width in pixels.
+     * @param params.treeCanvasHeight - Logical canvas height in pixels.
+     * @param params.treeHeight - Total rendered height of the full tree in pixels.
+     * @param params.devicePixelRatio - Current screen DPR.
+     * @param params.internalZoomLevel - Internal zoom level of the tree canvas.
+     * @param params.isLinked - Whether the tree is linked to the case list scroll position.
+     * @returns Clamped `{ newPositionX, newPositionY }` values.
+     */
+    static getSanitizedScrollPosition(params: {
+        devicePixelRatio: number;
+        headerHeight: number;
+        internalZoomLevel: number;
+        isLinked: boolean;
+        positionX: number;
+        positionY: number;
+        treeCanvasHeight: number;
+        treeCanvasWidth: number;
+        treeHeight: number;
+        treePadding: number;
+    }): {
+        newPositionX: number;
+        newPositionY: number;
+    };
+    /**
+     * Calculates the vertical scroll position for a tree canvas based on the
+     * currently visible rows in a linked table/list view.
+     *
+     * The goal is to keep the visible portion of the tree centered on the same
+     * items that are currently visible in the linked view, accounting for zoom.
+     *
+     * @param kwArgs.treeCanvasHeight - Height of the visible tree canvas area in pixels.
+     * @param kwArgs.treeHeight - Total rendered height of the full tree in pixels.
+     * @param kwArgs.treeSize - Total number of leaf items (rows) in the tree.
+     * @param kwArgs.verticalScrollPosition - Current vertical scroll position of the linked view in pixels.
+     * @param kwArgs.zoomLevel - Current zoom level (>1 means zoomed out, items appear smaller).
+     * @returns The new vertical scroll position for the tree canvas, clamped to [0, treeHeight - treeCanvasHeight].
+     */
+    static getScrollPositionFromTreeVisibility(kwArgs: {
+        itemHeight: number;
+        treeCanvasHeight: number;
+        treeHeight: number;
+        treeSize: number;
+        verticalScrollPosition: number;
+        zoomLevel: number;
+    }): number;
+    /**
+     * Determines the optimal tick mark scale for the genetic distance axis.
+     *
+     * Selects the number of scale lines and the genetic distance represented by
+     * each interval by searching for the combination with the least leftover
+     * (i.e. the product of `numLines × increment` closest to `geneticTreeWidth`).
+     * Increments are drawn from `SCALE_INCREMENTS` scaled by an order-of-magnitude
+     * multiplier derived from `geneticTreeWidth`, and those smaller than
+     * `minGeneticScaleUnit` are skipped.
+     *
+     * @param params.treeWidthMinusPadding - Width of the drawable canvas area in pixels (excluding padding).
+     * @param params.geneticTreeWidth - Total genetic distance represented by the full tree width.
+     * @param params.minGeneticScaleUnit - The smallest meaningful genetic distance unit (see {@link getMinGeneticScaleUnit}).
+     * @param params.zoomLevel - Current zoom level; divides the effective pixel width.
+     * @returns A {@link TickerMarkScale} tuple: `[numberOfLines, geneticDistancePerLine, minGeneticScaleUnit]`.
+     *   Returns `[0, 0, 0]` when any required input is falsy.
+     */
+    static getTickMarkScale(params: {
+        geneticTreeWidth: Decimal;
+        maxScaleWidthPx: number;
+        minGeneticScaleUnit: number;
+        minScaleWidthPx: number;
+        scaleIncrements: number[];
+        treeWidthMinusPadding: number;
+        zoomLevel: number;
+    }): TickerMarkScale;
+    /**
+     * Sanitizes the tree by collapsing intermediate ancestor nodes that have a
+     * zero branch length, hoisting their children up to the parent level.
+     *
+     * This normalises Newick-parsed trees where polytomies or zero-distance
+     * internal nodes would otherwise produce visually redundant branching points.
+     *
+     * @param rootNode - The root of the tree to sanitize. Mutated in place.
+     * @returns The sanitized root node.
+     */
+    static sanitizeTree(rootNode: TreeNode, fallbackDistance: number): TreeNode;
+    /**
+     * Assembles the visual elements for an ancestor (internal) node and appends
+     * them to the tree assembly.
+     *
+     * Produces: vertical connector lines from each child toward the ancestor's
+     * Y midpoint (split into two sorted groups above and below center to allow
+     * per-segment highlighting), a horizontal branch line, an optional distance
+     * label, and a filled dot when all children have positive branch lengths.
+     *
+     * @param treeAssemblyContext - Shared context holding the assembly target and canvas dimensions.
+     * @param node - The ancestor tree node to assemble.
+     * @param childRenderResults - Assembly results returned by all direct children.
+     * @returns The pixel coordinates of the branch start and aggregated case IDs, for use by the parent.
+     */
+    private static assembleAncestorNode;
+    /**
+     * Assembles the visual elements for a single leaf node and appends them to
+     * the tree assembly.
+     *
+     * Produces: a horizontal branch line, an optional distance label, a dashed
+     * support line extending to the canvas edge, and a filled dot.
+     *
+     * @param treeAssemblyContext - Shared context holding the assembly target and canvas dimensions.
+     * @param node - The leaf tree node to assemble.
+     * @param distance - Accumulated genetic distance from the root to the start of this node's branch.
+     * @param leafIndex - Zero-based vertical index of this leaf, determining its Y position.
+     * @param sortingIndex - Sorting index of this leaf derived from linked view order. Used to draw the support line.
+     * @returns The pixel coordinates of the branch start and the node name, for use by the parent.
+     */
+    private static assembleLeafNode;
+    /**
+     * Helper that wraps a canvas drawing callback with a DPR-aware scale/translate
+     * transform, then restores the context to its pre-call state.
+     *
+     * @param canvas - The canvas element whose 2D context to use.
+     * @param devicePixelRatio - Screen DPR to scale up for HiDPI rendering.
+     * @param callback - Drawing operations to perform inside the transform.
+     */
+    private static draw;
+    /**
+     * Fills the tree canvas background with the theme's paper colour.
+     *
+     * @param params.canvas - The canvas element to draw onto.
+     * @param params.theme - MUI theme providing the background colour.
+     * @param params.treeCanvasWidth - Width of the area to fill in pixels.
+     * @param params.treeCanvasHeight - Height of the area to fill in pixels.
+     * @param params.devicePixelRatio - Screen DPR for HiDPI rendering.
+     */
+    private static drawBackground;
+    /**
+     * Iterates over each scale line position and invokes a callback with its
+     * canvas X coordinate.
+     *
+     * Computes the pixel offset for each tick so that the rightmost line aligns
+     * with the genetic tree width, accounting for the current scroll and zoom.
+     *
+     * @param params.tickerMarkScale - Scale tuple from {@link getTickMarkScale}.
+     * @param params.geneticTreeWidth - Total genetic width of the tree.
+     * @param params.pixelToGeneticDistanceRatio - Pixels per unit of genetic distance.
+     * @param params.zoomLevel - Current zoom level.
+     * @param params.devicePixelRatio - Screen DPR.
+     * @param params.horizontalScrollPosition - Current horizontal scroll offset in pixels (default 0).
+     * @param params.callback - Called for each line with `(x, index, numberOfLines)`.
+     */
+    private static forEachScaleLine;
+    private static getCanvasContext;
+    /**
+     * Returns a formatted distance label string for a branch, or `null` if the
+     * label should be suppressed.
+     *
+     * A label is suppressed when:
+     * - The tree has no maximum branch length, or it is zero.
+     * - The branch length is zero or undefined.
+     * - The branch is shorter than `MINIMUM_DISTANCE_PERCENTAGE_TO_SHOW_LABEL`
+     *   percent of the maximum branch length in the tree.
+     *
+     * Precision is derived from the magnitude of `maxBranchLength` to avoid
+     * excessive decimal places for large values.
+     *
+     * @param treeAssemblyContext - Context containing the root node (for `maxBranchLength`).
+     * @param branchLength - The genetic distance of the branch to label.
+     * @returns A rounded numeric string, or `null` if the label should be hidden.
+     */
+    private static getDistanceLabel;
+    /**
+     * Returns the fill/stroke colour for a shape, dimming it when highlighted
+     * nodes are active and the shape is not among them.
+     *
+     * @param color - The full-brightness colour to use when highlighted or no highlight is active.
+     * @param dimFn - A function that returns a dimmed version of the colour.
+     * @param highlightedNodeNames - The currently highlighted node names.
+     * @param nodeNames - The node name(s) associated with the shape being drawn.
+     * @returns The resolved colour string.
+     */
+    private static getFillStyle;
+}
+export {};

package/dist/utils/TreeUtil/index.d.ts

@@ -0,0 +1 @@
+export * from './TreeUtil';