@data-navigator/inspector 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Carnegie Mellon University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# Data Navigator
+
+![Data Navigator provides visualization toolkits with rich, accessible navigation structures, robust input handling, and flexible, semantic rendering.](https://raw.githubusercontent.com/cmudig/data-navigator/main/assets/data_navigator.png)
+
+Data Navigator is a JavaScript library that enables keyboard, screen reader, and multi-modal navigation of data structures and visualizations. It works with any rendering technology — SVG, Canvas, images, or WebGL — by creating a semantic, accessible HTML layer on top of your graphics.
+
+**[Documentation](https://dig.cmu.edu/data-navigator/)** · **[Getting Started](https://dig.cmu.edu/data-navigator/getting-started/)** · **[Demo](https://dig.cmu.edu/data-navigator/demo)** · **[npm](https://www.npmjs.com/package/data-navigator)**
+
+## Install
+
+```
+npm install data-navigator
+```
+
+```js
+import dataNavigator from 'data-navigator';
+```
+
+## How it works
+
+Data Navigator is organized into 3 composable modules:
+
+1. **Structure** — a graph of nodes and edges that defines navigation paths through your data
+2. **Input** — handles keyboard, touch, voice, gesture, and custom input modalities
+3. **Rendering** — creates semantic HTML elements overlaid on your visualization
+
+These modules can be used together or independently. Visit [the docs](https://dig.cmu.edu/data-navigator/getting-started/) for a step-by-step guide to building your first navigable chart.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions and development workflow.
+
+## Credit
+
+Data Navigator was developed at CMU's [Data Interaction Group](https://dig.cmu.edu/) (CMU DIG), primarily by [Frank Elavsky](https://frank.computer).
+
+## Citing Data Navigator
+
+```bib
+@article{2023-data-navigator,
+  title = {{Data Navigator}: An Accessibility-Centered Data Navigation Toolkit},
+  publisher = {{IEEE}},
+  author = {Frank Elavsky and Lucas Nadolskis and Dominik Moritz},
+  journal = {{IEEE} Transactions on Visualization and Computer Graphics},
+  year = {2023},
+  url = {http://dig.cmu.edu/data-navigator/}
+}
+```

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@data-navigator/inspector",
+    "version": "1.0.0",
+    "type": "module",
+    "author": "Frank Elavsky",
+    "license": "MIT",
+    "description": "Optional inspector companion for data-navigator.",
+    "main": "./src/index.js",
+    "module": "./src/index.js",
+    "files": [
+        "src/**/*",
+        "README.md",
+        "LICENSE"
+    ],
+    "exports": {
+        ".": {
+            "import": "./src/index.js",
+            "default": "./src/index.js"
+        }
+    },
+    "keywords": [
+        "visualization",
+        "accessibility",
+        "data-navigator",
+        "inspector",
+        "d3"
+    ],
+    "scripts": {
+        "dev": "vitepress dev docs",
+        "build:docs": "vitepress build docs",
+        "preview": "vitepress preview docs",
+        "prepublishOnly": "cp ../../README.md ../../LICENSE ."
+    },
+    "peerDependencies": {
+        "d3-array": "^3.0.0",
+        "d3-drag": "^3.0.0",
+        "d3-force": "^3.0.0",
+        "d3-scale": "^4.0.0",
+        "d3-scale-chromatic": "^3.0.0",
+        "d3-selection": "^3.0.0",
+        "data-navigator": ">=2.0.0"
+    },
+    "devDependencies": {
+        "d3-array": "^3.0.0",
+        "d3-drag": "^3.0.0",
+        "d3-force": "^3.0.0",
+        "d3-scale": "^4.0.0",
+        "d3-scale-chromatic": "^3.0.0",
+        "d3-selection": "^3.0.0",
+        "data-navigator": "*",
+        "vitepress": "^1.4.0",
+        "vue": "^3.5.0"
+    }
+}

package/src/force-graph.js

@@ -0,0 +1,169 @@
+// Copyright 2021-2024 Observable, Inc.
+// Released under the ISC license.
+// https://observablehq.com/@d3/force-directed-graph
+// Adapted for data-navigator-inspector with modular D3 imports.
+
+import { map, sort } from 'd3-array';
+import { drag } from 'd3-drag';
+import { forceSimulation, forceManyBody, forceLink, forceCenter } from 'd3-force';
+import { scaleOrdinal } from 'd3-scale';
+import { schemeTableau10 } from 'd3-scale-chromatic';
+import { create } from 'd3-selection';
+
+export function ForceGraph(
+    {
+        nodes, // an iterable of node objects (typically [{id}, …])
+        links // an iterable of link objects (typically [{source, target}, …])
+    },
+    {
+        nodeId = d => d.id,
+        nodeGroup,
+        nodeGroups,
+        nodeTitle,
+        nodeFill = 'currentColor',
+        nodeStroke = '#fff',
+        nodeStrokeWidth = 1.5,
+        nodeStrokeOpacity = 1,
+        nodeRadius = 5,
+        nodeStrength,
+        linkSource = ({ source }) => source,
+        linkTarget = ({ target }) => target,
+        linkStroke = '#999',
+        linkStrokeOpacity = 0.6,
+        linkStrokeWidth = 1.5,
+        linkStrokeLinecap = 'round',
+        linkStrength,
+        colors = schemeTableau10,
+        width = 640,
+        height = 400,
+        invalidation,
+        description,
+        hide
+    } = {}
+) {
+    // Compute values.
+    const N = map(nodes, nodeId).map(intern);
+    const R = typeof nodeRadius !== 'function' ? null : map(nodes, nodeRadius);
+    const LS = map(links, linkSource).map(intern);
+    const LT = map(links, linkTarget).map(intern);
+    if (nodeTitle === undefined) nodeTitle = (_, i) => N[i];
+    const T = nodeTitle == null ? null : map(nodes, nodeTitle);
+    const G = nodeGroup == null ? null : map(nodes, nodeGroup).map(intern);
+    const W = typeof linkStrokeWidth !== 'function' ? null : map(links, linkStrokeWidth);
+    const L = typeof linkStroke !== 'function' ? null : map(links, linkStroke);
+
+    // Replace the input nodes and links with mutable objects for the simulation.
+    nodes = map(nodes, (_, i) => ({ id: N[i] }));
+    links = map(links, (_, i) => ({ source: LS[i], target: LT[i] }));
+
+    description =
+        (typeof description === 'function' ? description(nodes, links) : description) ||
+        `Node-link graph. Contains ${nodes.length} node${nodes.length !== 1 ? 's' : ''} and ${links.length} link${
+            links.length !== 1 ? 's' : ''
+        }.`;
+
+    // Compute default domains.
+    if (G && nodeGroups === undefined) nodeGroups = sort(G);
+
+    // Construct the scales.
+    const color = nodeGroup == null ? null : scaleOrdinal(nodeGroups, colors);
+
+    // Construct the forces.
+    const forceNode = forceManyBody();
+    const simForceLink = forceLink(links).id(({ index: i }) => N[i]);
+    if (nodeStrength !== undefined) forceNode.strength(nodeStrength);
+    if (linkStrength !== undefined) simForceLink.strength(linkStrength);
+
+    const simulation = forceSimulation(nodes)
+        .force('link', simForceLink)
+        .force('charge', forceNode)
+        .force('center', forceCenter())
+        .on('tick', ticked);
+
+    const svg = create('svg')
+        .attr('width', width)
+        .attr('height', height)
+        .attr('viewBox', [-width / 2, -height / 2, width, height])
+        .attr('role', hide ? 'presentation' : 'img')
+        .attr('aria-label', hide ? null : description)
+        .attr('style', 'max-width: 100%; height: auto; height: intrinsic;');
+
+    const link = svg
+        .append('g')
+        .attr('stroke', typeof linkStroke !== 'function' ? linkStroke : null)
+        .attr('stroke-opacity', linkStrokeOpacity)
+        .attr('stroke-width', typeof linkStrokeWidth !== 'function' ? linkStrokeWidth : null)
+        .attr('stroke-linecap', linkStrokeLinecap)
+        .selectAll('line')
+        .data(links)
+        .join('line');
+
+    const node = svg
+        .append('g')
+        .attr('fill', nodeFill)
+        .attr('stroke', nodeStroke)
+        .attr('stroke-opacity', nodeStrokeOpacity)
+        .attr('stroke-width', nodeStrokeWidth)
+        .selectAll('circle')
+        .data(nodes)
+        .join('circle')
+        .attr('r', nodeRadius)
+        .attr('role', 'presentation')
+        .call(makeDrag(simulation));
+
+    if (W) link.attr('stroke-width', ({ index: i }) => W[i]);
+    if (L) link.attr('stroke', ({ index: i }) => L[i]);
+    if (G) node.attr('fill', ({ index: i }) => color(G[i]));
+    if (R) node.attr('r', ({ index: i }) => R[i]);
+    if (T) node.append('title').text(({ index: i }) => T[i]);
+    if (invalidation != null) invalidation.then(() => simulation.stop());
+
+    function intern(value) {
+        return value !== null && typeof value === 'object' ? value.valueOf() : value;
+    }
+
+    function ticked() {
+        link.attr('x1', d => d.source.x)
+            .attr('y1', d => d.source.y)
+            .attr('x2', d => d.target.x)
+            .attr('y2', d => d.target.y);
+
+        node.attr('cx', d => {
+            // Keep nodes within the svg bounds
+            let limit = width / 2 - nodeRadius;
+            if (d.x > limit || d.x < -limit) {
+                return limit;
+            }
+            return d.x;
+        }).attr('cy', d => {
+            let limit = height / 2 - nodeRadius;
+            if (d.y > limit || d.y < -limit) {
+                return limit;
+            }
+            return d.y;
+        });
+    }
+
+    function makeDrag(simulation) {
+        function dragstarted(event) {
+            if (!event.active) simulation.alphaTarget(0.3).restart();
+            event.subject.fx = event.subject.x;
+            event.subject.fy = event.subject.y;
+        }
+
+        function dragged(event) {
+            event.subject.fx = event.x;
+            event.subject.fy = event.y;
+        }
+
+        function dragended(event) {
+            if (!event.active) simulation.alphaTarget(0);
+            event.subject.fx = null;
+            event.subject.fy = null;
+        }
+
+        return drag().on('start', dragstarted).on('drag', dragged).on('end', dragended);
+    }
+
+    return Object.assign(svg.node(), { scales: { color } });
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { ForceGraph } from './force-graph.js';
+export { TreeGraph } from './tree-graph.js';
+export { Inspector, buildLabel } from './inspector.js';

package/src/inspector.js

@@ -0,0 +1,225 @@
+import { ForceGraph } from './force-graph.js';
+import { TreeGraph } from './tree-graph.js';
+
+/**
+ * Converts a structure's nodes or edges object into an array for D3.
+ * Optionally includes extra node IDs or excludes certain edge IDs.
+ */
+const convertToArray = (obj, include, exclude) => {
+    let arr = [];
+    if (include) {
+        include.forEach(id => {
+            arr.push({ id });
+        });
+    }
+    Object.keys(obj).forEach(k => {
+        if (exclude && exclude.indexOf(k) !== -1) {
+            return;
+        }
+        arr.push(obj[k]);
+    });
+    return arr;
+};
+
+/**
+ * Builds a tooltip label for a structure node.
+ */
+export const buildLabel = (node, colorBy) => {
+    if (node.semantics?.label) return node.semantics.label;
+    if (!node.derivedNode) {
+        if (node.data) {
+            return (
+                Object.keys(node.data)
+                    .map(key => `${key}: ${node.data[key]}`)
+                    .join('. ') + '. Data point.'
+            );
+        }
+        return node.id;
+    }
+    if (node.data?.dimensionKey) {
+        let count = 0;
+        let divisions = Object.keys(node.data.divisions || {});
+        divisions.forEach(div => {
+            count += Object.keys(node.data.divisions[div].values || {}).length;
+        });
+        let label = `${node.derivedNode}.`;
+        label +=
+            divisions.length && count
+                ? ` Contains ${divisions.length} division${
+                      divisions.length > 1 ? 's' : ''
+                  } which contain ${count} datapoint${count > 1 ? 's' : ''} total.`
+                : ' Contains no child data points.';
+        label += ` ${node.data.type} dimension.`;
+        return label;
+    }
+    return `${node.derivedNode}: ${node.data?.[node.derivedNode]}. Contains ${
+        Object.keys(node.data?.values || {}).length
+    } child data point${Object.keys(node.data?.values || {}).length > 1 ? 's' : ''}. Division of ${
+        node.derivedNode
+    } dimension.`;
+};
+
+/**
+ * Shows the tooltip next to the force graph.
+ */
+const showTooltip = (node, tooltipEl, graphWidth, graphHeight, colorBy) => {
+    tooltipEl.classList.remove('dn-inspector-hidden');
+    tooltipEl.innerText =
+        buildLabel(node, colorBy) ||
+        `${node.id}${node.data?.[colorBy] ? ', ' + node.data[colorBy] : ''} (generic node, edges hidden).`;
+    const bbox = tooltipEl.getBoundingClientRect();
+    const yOffset = bbox.height / 2;
+    tooltipEl.style.textAlign = 'left';
+    tooltipEl.style.transform = `translate(${graphWidth}px,${graphHeight / 2 - yOffset}px)`;
+};
+
+/**
+ * Hides the tooltip and optionally the focus indicator.
+ */
+const hideTooltip = (tooltipEl, indicatorEl) => {
+    tooltipEl.classList.add('dn-inspector-hidden');
+    if (indicatorEl) {
+        indicatorEl.classList.add('dn-inspector-hidden');
+    }
+};
+
+/**
+ * Moves the SVG focus indicator circle to the target node.
+ */
+const highlightNode = (nodeId, svgEl, indicatorEl) => {
+    let target = svgEl.querySelector('#svg' + nodeId);
+    if (!target || !indicatorEl) return;
+    indicatorEl.setAttribute('cx', target.getAttribute('cx'));
+    indicatorEl.setAttribute('cy', target.getAttribute('cy'));
+    indicatorEl.classList.remove('dn-inspector-hidden');
+};
+
+/**
+ * Creates and returns a focus indicator circle element inside the SVG.
+ */
+const createFocusIndicator = (svgEl, id) => {
+    let indicator = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+    indicator.id = id + '-focus-indicator';
+    indicator.setAttribute('class', 'dn-inspector-focus-indicator dn-inspector-hidden');
+    indicator.setAttribute('cx', 0);
+    indicator.setAttribute('cy', 0);
+    indicator.setAttribute('r', 6.5);
+    indicator.setAttribute('fill', 'none');
+    indicator.setAttribute('stroke', '#000');
+    indicator.setAttribute('stroke-width', '2');
+    svgEl.appendChild(indicator);
+    return indicator;
+};
+
+/**
+ * Inspector: creates a passive force-directed graph visualization of a
+ * data-navigator structure. Does not drive navigation — call highlight()
+ * and clear() from your own navigation lifecycle to keep the graph in sync.
+ *
+ * @param {Object} options
+ * @param {Object} options.structure - A data-navigator structure object (nodes, edges, navigationRules)
+ * @param {string|HTMLElement} options.container - DOM element or ID to mount in
+ * @param {number} [options.size=300] - Width and height of the force graph
+ * @param {string} [options.colorBy='dimensionLevel'] - Field to color nodes by
+ * @param {number} [options.nodeRadius=5] - Radius of node circles
+ * @param {string[]} [options.edgeExclusions=[]] - Edge IDs to exclude from the graph
+ * @param {string[]} [options.nodeInclusions=[]] - Extra pseudo-node IDs to include
+ * @param {'force'|'tree'} [options.mode='force'] - Visualization mode: 'force' for force-directed, 'tree' for hierarchy layout
+ *
+ * @returns {{ svg: SVGElement, highlight: Function, clear: Function, destroy: Function }}
+ */
+export function Inspector({
+    structure,
+    container,
+    size = 300,
+    colorBy = 'dimensionLevel',
+    nodeRadius = 5,
+    edgeExclusions = [],
+    nodeInclusions = [],
+    mode = 'force'
+}) {
+    const rootEl = typeof container === 'string' ? document.getElementById(container) : container;
+    const rootId = rootEl.id || 'dn-inspector-' + Math.random().toString(36).slice(2, 8);
+    if (!rootEl.id) rootEl.id = rootId;
+
+    // Build the graph SVG
+    const graphWidth = mode === 'tree' ? size * 2 : size;
+    const graphHeight = mode === 'tree' ? Math.round(size * 1.5) : size;
+    const nodeArray = convertToArray(structure.nodes, nodeInclusions);
+    const linkArray = convertToArray(structure.edges, [], edgeExclusions);
+    const graphOptions = {
+        nodeId: d => d.id,
+        nodeGroup: d => (colorBy === 'dimensionLevel' ? d.dimensionLevel : d.data?.[colorBy]),
+        width: graphWidth,
+        height: graphHeight,
+        nodeRadius,
+        hide: true
+    };
+
+    const graph = mode === 'tree'
+        ? TreeGraph(
+            { nodes: nodeArray, links: linkArray },
+            { ...graphOptions, dimensions: structure.dimensions }
+          )
+        : ForceGraph(
+            { nodes: nodeArray, links: linkArray },
+            graphOptions
+          );
+
+    // Create wrapper structure
+    const wrapperEl = document.createElement('div');
+    wrapperEl.className = 'dn-inspector-wrapper';
+    wrapperEl.style.position = 'relative';
+
+    const graphContainer = document.createElement('div');
+    graphContainer.className = 'dn-inspector-graph';
+    graphContainer.appendChild(graph);
+    wrapperEl.appendChild(graphContainer);
+
+    // Create tooltip
+    const tooltipEl = document.createElement('div');
+    tooltipEl.id = rootId + '-tooltip';
+    tooltipEl.className = 'dn-inspector-tooltip dn-inspector-hidden';
+    tooltipEl.setAttribute('role', 'presentation');
+    tooltipEl.setAttribute('focusable', 'false');
+    wrapperEl.appendChild(tooltipEl);
+
+    rootEl.appendChild(wrapperEl);
+
+    // Assign IDs to SVG circles for targeting
+    const svgEl = graphContainer.querySelector('svg');
+    graphContainer.querySelectorAll('circle').forEach(c => {
+        if (c.__data__?.id) {
+            c.id = 'svg' + c.__data__.id;
+        }
+        c.addEventListener('mousemove', e => {
+            if (e.target?.__data__?.id) {
+                let d = e.target.__data__;
+                showTooltip(structure.nodes[d.id] || d, tooltipEl, graphWidth, graphHeight, colorBy);
+            }
+        });
+        c.addEventListener('mouseleave', () => {
+            hideTooltip(tooltipEl);
+        });
+    });
+
+    // Create focus indicator
+    const indicatorEl = createFocusIndicator(svgEl, rootId);
+
+    // Public API
+    return {
+        svg: svgEl,
+        highlight(nodeId) {
+            highlightNode(nodeId, svgEl, indicatorEl);
+            if (structure.nodes[nodeId]) {
+                showTooltip(structure.nodes[nodeId], tooltipEl, graphWidth, graphHeight, colorBy);
+            }
+        },
+        clear() {
+            hideTooltip(tooltipEl, indicatorEl);
+        },
+        destroy() {
+            rootEl.removeChild(wrapperEl);
+        }
+    };
+}

package/src/tree-graph.js

@@ -0,0 +1,327 @@
+// Tree layout visualization for data-navigator structures.
+// Arranges dimension, division, and leaf nodes in a deterministic hierarchy.
+// For 2+ dimensions, leaf nodes are placed in a grid layout.
+
+import { map, sort } from 'd3-array';
+import { scaleOrdinal } from 'd3-scale';
+import { schemeTableau10 } from 'd3-scale-chromatic';
+import { create } from 'd3-selection';
+
+export function TreeGraph(
+    {
+        nodes,
+        links
+    },
+    {
+        nodeId = d => d.id,
+        nodeGroup,
+        nodeGroups,
+        nodeRadius = 5,
+        colors = schemeTableau10,
+        width = 640,
+        height = 400,
+        dimensions,
+        description,
+        hide
+    } = {}
+) {
+    // Compute values (same pattern as ForceGraph).
+    const N = map(nodes, nodeId).map(intern);
+    const G = nodeGroup == null ? null : map(nodes, nodeGroup).map(intern);
+
+    // Build a lookup from node id to original node data.
+    const nodeById = {};
+    nodes.forEach((n, i) => { nodeById[N[i]] = n; });
+
+    // Replace input nodes with positioned objects.
+    nodes = map(nodes, (_, i) => ({ id: N[i], x: 0, y: 0 }));
+    const nodeObjById = {};
+    nodes.forEach(n => { nodeObjById[n.id] = n; });
+
+    // Map links to source/target ids.
+    const linkData = map(links, (l) => ({
+        source: intern(l.source),
+        target: intern(l.target),
+        navigationRules: l.navigationRules || []
+    }));
+
+    description =
+        (typeof description === 'function' ? description(nodes, linkData) : description) ||
+        `Tree layout. Contains ${nodes.length} node${nodes.length !== 1 ? 's' : ''} and ${linkData.length} link${
+            linkData.length !== 1 ? 's' : ''
+        }.`;
+
+    // Compute default domains and color scale.
+    if (G && nodeGroups === undefined) nodeGroups = sort(G);
+    const color = nodeGroup == null ? null : scaleOrdinal(nodeGroups, colors);
+
+    // Build set of parent-child navigation rule names.
+    const parentChildRules = new Set(['parent', 'child']);
+    if (dimensions) {
+        Object.values(dimensions).forEach(dim => {
+            (dim.navigationRules?.parent_child || []).forEach(r => parentChildRules.add(r));
+        });
+    }
+
+    // Classify links.
+    const parentChildLinks = [];
+    const siblingLinks = [];
+    linkData.forEach(l => {
+        const rules = l.navigationRules;
+        if (!rules || rules.length === 0) return;
+        // Skip exit/undo edges
+        if (rules.includes('exit') || rules.includes('undo')) return;
+        const isParentChild = rules.some(r => parentChildRules.has(r));
+        if (isParentChild) {
+            parentChildLinks.push(l);
+        } else {
+            siblingLinks.push(l);
+        }
+    });
+
+    // Classify nodes by level.
+    const level0 = [];
+    const level1 = [];
+    const level2 = [];
+    const leafNodes = [];
+    const otherNodes = [];
+
+    nodes.forEach(n => {
+        const orig = nodeById[n.id];
+        if (!orig) { otherNodes.push(n); return; }
+        const dl = orig.dimensionLevel;
+        const dn = orig.derivedNode;
+        if (dl === 0) level0.push(n);
+        else if (dl === 1) level1.push(n);
+        else if (dl === 2) level2.push(n);
+        else if (dl === undefined && dn === undefined && orig.data) leafNodes.push(n);
+        else otherNodes.push(n);
+    });
+
+    // Build leaf-to-division mapping from dimensions.
+    // leafDivisions[leafId] = { dimensionKey: divisionId, ... }
+    const leafDivisions = {};
+    const dimKeys = dimensions ? Object.keys(dimensions) : [];
+    const dimOrder = []; // ordered list of dimension keys
+    if (dimensions) {
+        dimKeys.forEach(key => {
+            dimOrder.push(key);
+            const dim = dimensions[key];
+            const divIds = Object.keys(dim.divisions || {});
+            // Skip the "single division" case where divId === dim.nodeId
+            const isSingleDiv = divIds.length === 1 && divIds[0] === dim.nodeId;
+            divIds.forEach(divId => {
+                const div = dim.divisions[divId];
+                Object.keys(div.values || {}).forEach(leafId => {
+                    if (!leafDivisions[leafId]) leafDivisions[leafId] = {};
+                    leafDivisions[leafId][key] = isSingleDiv ? dim.nodeId : divId;
+                });
+            });
+        });
+    }
+
+    // Organize level2 nodes by their parent dimension.
+    const divisionsByDim = {};
+    dimOrder.forEach(key => { divisionsByDim[key] = []; });
+    level2.forEach(n => {
+        const orig = nodeById[n.id];
+        if (orig && orig.derivedNode && divisionsByDim[orig.derivedNode]) {
+            divisionsByDim[orig.derivedNode].push(n);
+        }
+    });
+
+    // Compute layout positions.
+    const padding = { top: 30, bottom: 20, left: 30, right: 30 };
+    const usableWidth = width - padding.left - padding.right;
+    const usableHeight = height - padding.top - padding.bottom;
+
+    // Determine rows: level0 (optional), level1, level2, leaves
+    const hasLevel0 = level0.length > 0;
+    const rowCount = (hasLevel0 ? 1 : 0) + 1 + 1 + 1; // l0?, l1, l2, leaves
+    const rowSpacing = usableHeight / (rowCount - 1 || 1);
+
+    let currentRow = 0;
+    const yFor = (row) => padding.top + row * rowSpacing;
+
+    // Level 0
+    if (hasLevel0) {
+        const y = yFor(currentRow);
+        level0.forEach((n, i) => {
+            n.x = padding.left + usableWidth / 2;
+            n.y = y;
+        });
+        currentRow++;
+    }
+
+    // Level 1 (dimensions) — evenly spaced
+    const dimY = yFor(currentRow);
+    const dimCount = level1.length || 1;
+    // Map dimension nodeId to its horizontal allocation
+    const dimAlloc = {};
+    level1.forEach((n, i) => {
+        const x = padding.left + (usableWidth / (dimCount + 1)) * (i + 1);
+        n.x = x;
+        n.y = dimY;
+        dimAlloc[n.id] = {
+            x,
+            idx: i,
+            rangeStart: padding.left + (usableWidth / dimCount) * i,
+            rangeEnd: padding.left + (usableWidth / dimCount) * (i + 1)
+        };
+    });
+    currentRow++;
+
+    // Level 2 (divisions) — grouped under their parent dimension
+    const divY = yFor(currentRow);
+    const divAlloc = {}; // divisionId -> { x, dimKey }
+    dimOrder.forEach(key => {
+        const dim = dimensions ? dimensions[key] : null;
+        if (!dim) return;
+        const alloc = dimAlloc[dim.nodeId];
+        if (!alloc) return;
+        const divs = divisionsByDim[key] || [];
+        if (divs.length === 0) return;
+        const range = alloc.rangeEnd - alloc.rangeStart;
+        const divSpacing = range / (divs.length + 1);
+        divs.forEach((n, i) => {
+            n.x = alloc.rangeStart + divSpacing * (i + 1);
+            n.y = divY;
+            divAlloc[n.id] = { x: n.x, dimKey: key, idx: i };
+        });
+    });
+    currentRow++;
+
+    // Leaf nodes
+    const leafY = yFor(currentRow);
+    if (dimOrder.length === 0 || !dimensions) {
+        // No dimensions — flat row
+        leafNodes.forEach((n, i) => {
+            n.x = padding.left + (usableWidth / (leafNodes.length + 1)) * (i + 1);
+            n.y = leafY;
+        });
+    } else if (dimOrder.length === 1) {
+        // Single dimension — spread leaves under their division parent
+        const key = dimOrder[0];
+        const dim = dimensions[key];
+        const divIds = Object.keys(dim.divisions || {});
+        divIds.forEach(divId => {
+            const div = dim.divisions[divId];
+            const leafIds = Object.keys(div.values || {});
+            const parentX = divAlloc[divId]?.x || width / 2;
+            const spreadWidth = usableWidth / (divIds.length || 1);
+            const leafSpacing = spreadWidth / (leafIds.length + 1);
+            leafIds.forEach((leafId, i) => {
+                const n = nodeObjById[leafId];
+                if (n) {
+                    n.x = parentX - spreadWidth / 2 + leafSpacing * (i + 1);
+                    n.y = leafY;
+                }
+            });
+        });
+    } else {
+        // 2+ dimensions — grid layout
+        // First dimension controls columns, second controls rows
+        const dim1Key = dimOrder[0];
+        const dim2Key = dimOrder[1];
+        const dim1 = dimensions[dim1Key];
+        const dim2 = dimensions[dim2Key];
+        const div1Ids = Object.keys(dim1.divisions || {});
+        const div2Ids = Object.keys(dim2.divisions || {});
+
+        const cols = div1Ids.length || 1;
+        const rows = div2Ids.length || 1;
+
+        // Grid occupies the leaf area but may expand vertically
+        const gridTop = leafY - rowSpacing * 0.3;
+        const gridBottom = height - padding.bottom;
+        const gridHeight = gridBottom - gridTop;
+        const colSpacing = usableWidth / (cols + 1);
+        const rowSpacingGrid = gridHeight / (rows + 1);
+
+        leafNodes.forEach(n => {
+            const ld = leafDivisions[n.id];
+            if (!ld) {
+                // Unaffiliated leaf — place to the right
+                n.x = width - padding.right;
+                n.y = leafY;
+                return;
+            }
+            const colDivId = ld[dim1Key];
+            const rowDivId = ld[dim2Key];
+            const colIdx = div1Ids.indexOf(colDivId);
+            const rowIdx = div2Ids.indexOf(rowDivId);
+            n.x = padding.left + colSpacing * ((colIdx >= 0 ? colIdx : 0) + 1);
+            n.y = gridTop + rowSpacingGrid * ((rowIdx >= 0 ? rowIdx : 0) + 1);
+        });
+    }
+
+    // Other nodes (exit, etc.) — placed bottom-right
+    otherNodes.forEach((n, i) => {
+        n.x = width - padding.right - (i * nodeRadius * 3);
+        n.y = height - padding.bottom;
+    });
+
+    // Build the SVG.
+    const svg = create('svg')
+        .attr('width', width)
+        .attr('height', height)
+        .attr('viewBox', [0, 0, width, height])
+        .attr('role', hide ? 'presentation' : 'img')
+        .attr('aria-label', hide ? null : description)
+        .attr('style', 'max-width: 100%; height: auto; height: intrinsic;');
+
+    // Draw sibling links (dashed, behind parent-child links).
+    svg.append('g')
+        .attr('class', 'tree-sibling-links')
+        .selectAll('line')
+        .data(siblingLinks)
+        .join('line')
+        .attr('x1', d => nodeObjById[d.source]?.x || 0)
+        .attr('y1', d => nodeObjById[d.source]?.y || 0)
+        .attr('x2', d => nodeObjById[d.target]?.x || 0)
+        .attr('y2', d => nodeObjById[d.target]?.y || 0)
+        .attr('stroke', '#bbb')
+        .attr('stroke-opacity', 0.25)
+        .attr('stroke-width', 1)
+        .attr('stroke-dasharray', '3,2');
+
+    // Draw parent-child links (solid).
+    svg.append('g')
+        .attr('class', 'tree-parent-child-links')
+        .selectAll('line')
+        .data(parentChildLinks)
+        .join('line')
+        .attr('x1', d => nodeObjById[d.source]?.x || 0)
+        .attr('y1', d => nodeObjById[d.source]?.y || 0)
+        .attr('x2', d => nodeObjById[d.target]?.x || 0)
+        .attr('y2', d => nodeObjById[d.target]?.y || 0)
+        .attr('stroke', '#666')
+        .attr('stroke-opacity', 0.5)
+        .attr('stroke-width', 1.5);
+
+    // Draw nodes.
+    const node = svg
+        .append('g')
+        .attr('fill', 'currentColor')
+        .attr('stroke', '#fff')
+        .attr('stroke-opacity', 1)
+        .attr('stroke-width', 1.5)
+        .selectAll('circle')
+        .data(nodes)
+        .join('circle')
+        .attr('cx', d => d.x)
+        .attr('cy', d => d.y)
+        .attr('r', nodeRadius)
+        .attr('role', 'presentation');
+
+    if (G) node.attr('fill', ({ id }) => {
+        const idx = N.indexOf(id);
+        return idx >= 0 ? color(G[idx]) : '#999';
+    });
+
+    function intern(value) {
+        return value !== null && typeof value === 'object' ? value.valueOf() : value;
+    }
+
+    return Object.assign(svg.node(), { scales: { color } });
+}