29:null 2a:["$","title",null,{"children":"Hyperbolic Tree Viewer - v2 | Observable Ambassadors | Observable"}] 2f:T53c,// CELL: intro — title, concepts overview (notebook header) display(md` # Hyperbolic Tree Viewer - v2 My first notebook with the chat AI agent. An interactive **focus + context** tree browser rendered with Observable Plot, using true hyperbolic (Poincaré disk) geometry for layout and navigation — in the tradition of Lamping & Rao's classic "hyperbolic browser" (Xerox PARC, 1995). ## Concepts - **Poincaré disk model.** The entire (infinite) tree is mapped into a unit disk. Points near the center appear large and well-spaced ("focus"); points near the boundary are compressed but still present ("context"). No point ever reaches the boundary — it represents hyperbolic infinity. - **Möbius transforms as navigation.** Panning, zooming, and click-to-focus are all implemented as elements of **PSU(1,1)**, the isometry group of the disk. This is why navigation feels "infinite": you can never run out of space, and every view is a mathematically valid re-projection of the *same* underlying tree — nothing is ever recomputed or re-laid-out. - **Focus + context.** Because Möbius transforms are conformal, moving a node to the center doesn't just translate it — it locally *expands* the space around it (revealing more detail) while compressing everything else toward the edge (preserving overview). `);30:T4dd,// CELL: flare-viewer — live demo on the flare dataset, with a right-hand control panel // (reset, a theme toggle, a drag-to-pan joystick with an "Animation demo" auto-play journey, an // edge-style toggle, and experimental sliders — see ht_buildControlPanel). Defaults to "geodesic" // edge style (the true hyperbolic straight line) — switch to "Radial tidy tree" any time via the // panel's "Edge style" dropdown if you prefer edges that stay confined to the wedge between // endpoints for nodes with many children. ht_alignPanelToPlot keeps the panel vertically aligned // with the disk itself, not the whole viewer div (which also includes the title/subtitle/legend // block above the disk). const ht_flareViewer4 = ht_viewer4(ht_flareNodes, { title: "Hyperbolic tree viewer — Flare class hierarchy (252 nodes)", subtitleBase: "Drag to pan · scroll to zoom · double-click to focus · squares = leaves, circles = branches · all nodes always visible ·" }); const ht_flarePanel = ht_buildControlPanel(ht_flareViewer4, { baseDomainR: 1.05 }); ht_alignPanelToPlot(ht_flareViewer4.element, ht_flarePanel); display(html`

${ht_flareViewer4.element}${ht_flarePanel}

`);31:T988,// CELL: math-and-layout — SU(1,1) Möbius transform primitives + ht_layout() static layout function // ---- fully self-contained rewrite (fresh names, no dependency on earlier possibly-tainted bindings) ---- function ht_cx(re, im = 0) { return { re, im }; } function ht_add(a, b) { return { re: a.re + b.re, im: a.im + b.im }; } function ht_mul(a, b) { return { re: a.re * b.re - a.im * b.im, im: a.re * b.im + a.im * b.re }; } function ht_conj(a) { return { re: a.re, im: -a.im }; } function ht_div(a, b) { const d = b.re * b.re + b.im * b.im; return { re: (a.re * b.re + a.im * b.im) / d, im: (a.im * b.re - a.re * b.im) / d }; } function ht_abs2(a) { return a.re * a.re + a.im * a.im; } const ht_identity = { a: ht_cx(1, 0), b: ht_cx(0, 0) }; function ht_apply(M, z) { const num = ht_add(ht_mul(M.a, z), M.b); const den = ht_add(ht_mul(ht_conj(M.b), z), ht_conj(M.a)); return ht_div(num, den); } function ht_composeAfter(M2, M1) { const a = ht_add(ht_mul(M2.a, M1.a), ht_mul(M2.b, ht_conj(M1.b))); const b = ht_add(ht_mul(M2.a, M1.b), ht_mul(M2.b, ht_conj(M1.a))); return { a, b }; } function ht_translateTo(p) { const r2 = Math.min(0.999999, ht_abs2(p)); const s = 1 / Math.sqrt(Math.max(1e-9, 1 - r2)); return { a: ht_cx(s, 0), b: ht_cx(p.re * s, p.im * s) }; } function ht_translateFrom(f) { const r2 = Math.min(0.999999, ht_abs2(f)); const s = 1 / Math.sqrt(Math.max(1e-9, 1 - r2)); return { a: ht_cx(s, 0), b: ht_cx(-f.re * s, -f.im * s) }; } function ht_normalize(M) { const norm = Math.sqrt(Math.max(1e-9, ht_abs2(M.a) - ht_abs2(M.b))); return { a: ht_cx(M.a.re / norm, M.a.im / norm), b: ht_cx(M.b.re / norm, M.b.im / norm) }; } function ht_layout(root, { k = 2.2 } = {}) { const tree = d3.tree() .size([2 * Math.PI, root.height || 1]) .separation((a, b) => (a.parent === b.parent ? 1 : 2) / Math.max(1, a.depth)); tree(root); const maxY = d3.max(root.descendants(), (d) => d.y) || 1; root.each((d) => { const rDisk = Math.tanh((k * d.y) / maxY); const angle = d.x - Math.PI / 2; d.z0 = { re: rDisk * Math.cos(angle), im: rDisk * Math.sin(angle) }; }); return root.descendants(); } // small generic helper used by the "edge treatment" options in ht_viewer4 function ht_smoothstep(edge0, edge1, x) { const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0))); return t * t * (3 - 2 * t); } display("Functions for math and layout"); display(ht_layout);32:T97a,// CELL: edge-curves — hyperbolic geodesic edge rendering: returns a sampled polyline // (array of {re,im} points) approximating the true hyperbolic straight line from z1 to z2. // Operates in the *projected* (screen-space, post-Möbius) disk coordinates, since that's // what's drawn each frame — it doesn't require re-running the static layout. // True hyperbolic geodesics: the mathematically "straight" line of the hyperbolic metric. // In the Poincaré disk model a geodesic is a circular arc orthogonal to the boundary circle // (or a diameter, when it passes through the center). Möbius-invariant: because ht_apply is // a disk automorphism, this looks like a "clean" hyperbolic line in *every* view, not just // the untransformed one — and it directly avoids overlap problems like a centered node's // edges slicing through a neighboring branch's fan, because geodesics bow back toward the // metrically "cheaper" middle of the disk instead of cutting a straight Euclidean chord. function ht_geodesicPoints(z1, z2, { n = 24 } = {}) { const x1 = z1.re, y1 = z1.im, x2 = z2.re, y2 = z2.im; const det = x1 * y2 - y1 * x2; // near-collinear with the origin (or either endpoint essentially at the center) => the // "circle" degenerates to a straight diameter; fall back to a straight segment. const nearOrigin = Math.hypot(x1, y1) < 1e-6 || Math.hypot(x2, y2) < 1e-6; if (Math.abs(det) < 1e-9 || nearOrigin) { const pts = []; for (let i = 0; i <= n; i++) { const t = i / n; pts.push({ re: x1 + (x2 - x1) * t, im: y1 + (y2 - y1) * t }); } return pts; } const b1 = (x1 * x1 + y1 * y1 + 1) / 2, b2 = (x2 * x2 + y2 * y2 + 1) / 2; const cx = (b1 * y2 - b2 * y1) / det, cy = (x1 * b2 - x2 * b1) / det; const r = Math.sqrt(Math.max(0, cx * cx + cy * cy - 1)); let a0 = Math.atan2(y1 - cy, x1 - cx), a1 = Math.atan2(y2 - cy, x2 - cx); let da = a1 - a0; da -= 2 * Math.PI * Math.round(da / (2 * Math.PI)); // orthogonal-circle property guarantees |da|<=pi here const pts = []; for (let i = 0; i <= n; i++) { const t = i / n; const a = a0 + da * t; pts.push({ re: cx + r * Math.cos(a), im: cy + r * Math.sin(a) }); } return pts; } display("Hyperbolic geodesic edge rendering: ht_geodesicPoints — the true hyperbolic straight line between two projected points, drawn as a circular arc orthogonal to the boundary circle"); display(ht_geodesicPoints);33:Tb6a,// CELL: edge-curves-radial — alternative "radial tidy tree" style edge curve, matching the // classic d3.linkRadial() bump curve (as seen in https://observablehq.com/@d3/radial-tree/2) // instead of a true hyperbolic geodesic. Same signature as ht_geodesicPoints (operates on the // *projected*, screen-space endpoints and returns a sampled polyline), so it's a drop-in // alternative edge-drawing function. // // WHY: true hyperbolic geodesics bow back toward the disk's center (the metrically "cheapest" // path between two points) — this is great for avoiding cross-branch overlap, but it means that // for a node with MANY children, every one of its outgoing edges bows toward the origin, so they // can read as a chaotic fan of big arcs sweeping through the middle of the disk. d3's radial-tree // link instead computes a Bezier curve in (angle, radius) polar coordinates — which keeps each // edge visually confined to the narrow "wedge" between its two endpoints' angles — giving the // familiar, tidy radial-dendrogram look, with no edge ever ballooning across the disk. // // IMPLEMENTATION: mirrors d3-shape's curveBumpRadial exactly. The 4 cubic-Bezier control points // are first computed in (angle, radius) space — start, (angle0, midRadius), (angle1, midRadius), // end (the same "hold angle, move to the mean radius" shape as curveBumpY) — and only THEN is // each of those 4 points individually converted to Cartesian (r·cosθ, r·sinθ) and used directly // as a literal Cartesian Bezier control point. That's the same trick d3 uses internally: the // curve's *shape* is defined in polar space, but the actual Bezier math runs in Cartesian on the // polar-projected control points. function ht_radialBumpPoints(z1, z2, { n = 24 } = {}) { const r1 = Math.hypot(z1.re, z1.im), a1 = Math.atan2(z1.im, z1.re); const r2 = Math.hypot(z2.re, z2.im); let a2 = Math.atan2(z2.im, z2.re); // unwrap so the curve sweeps the short way around (never the "long way" through the back) while (a2 - a1 > Math.PI) a2 -= 2 * Math.PI; while (a2 - a1 < -Math.PI) a2 += 2 * Math.PI; const midR = (r1 + r2) / 2; const toXY = (a, r) => ({ re: r * Math.cos(a), im: r * Math.sin(a) }); const P0 = toXY(a1, r1), P1 = toXY(a1, midR), P2 = toXY(a2, midR), P3 = toXY(a2, r2); const pts = []; for (let i = 0; i <= n; i++) { const t = i / n, u = 1 - t; const b0 = u * u * u, b1 = 3 * u * u * t, b2 = 3 * u * t * t, b3 = t * t * t; pts.push({ re: b0 * P0.re + b1 * P1.re + b2 * P2.re + b3 * P3.re, im: b0 * P0.im + b1 * P1.im + b2 * P2.im + b3 * P3.im }); } return pts; } display("Radial-tidy-tree-style edge curve — ht_radialBumpPoints: a d3.linkRadial()-style polar Bezier (drop-in alternative to ht_geodesicPoints) that keeps each edge confined to the wedge between its endpoints' angles, instead of bowing through the disk's center"); display(ht_radialBumpPoints);34:T4eb,// CELL: viewer-geometry — small pure geometry helpers used by ht_viewer4's render loop. // Extracted out so ht_viewer4 itself can stay focused on option handling and the Plot marks. // the Poincaré disk itself always has radius 1 in data-space, regardless of any rendering // margin — panning/zooming/clicking should only engage inside this circle. function ht_inDisk(z, maxR = 1) { return z.re * z.re + z.im * z.im <= maxR * maxR; } // clamps (x,y) to lie within radius maxR of the origin, preserving its angle — used to keep // the root visible (pinned) even when pushed toward/past the boundary. function ht_clampToDisk(x, y, maxR) { const r = Math.hypot(x, y); if (r <= maxR || r === 0) return { x, y, clamped: false }; const s = maxR / r; return { x: x * s, y: y * s, clamped: true }; } // projects every node through the current Möbius transform M, returning {n, x, y, r2} for each. function ht_projectNodes(nodes, M) { const out = new Array(nodes.length); for (let i = 0; i < nodes.length; i++) { const n = nodes[i]; const z = ht_apply(M, n.z0); out[i] = { n, x: z.re, y: z.im, r2: z.re * z.re + z.im * z.im }; } return out; } display("Viewer geometry helpers — ht_inDisk, ht_clampToDisk, ht_projectNodes");35:T1023,// CELL: viewer-node-data — per-frame node data prep for ht_viewer4: color legend domain, // node size/opacity computation (per edgeStyle), leaf-square rotation, and nearest-node hit-testing. // color legend domain, computed ONCE from every node (not just whatever's currently visible) so // Plot never auto-refits the legend's swatch list as nodes pan in/out of view. function ht_computeColorDomain(nodes, label) { return Array.from(new Set( nodes.map((n) => label(n.depth <= 1 ? n : n.ancestors().reverse()[1])) )).sort(); } // computes each non-root node's rendered radius (`vr`) and opacity according to `edgeStyle` // ("shrinkFloor" keeps every node visible, shrinking to a floor; "fade" shrinks+fades out near // edgeHorizon; "cutoff" is a hard cutoff), then applies `renderBudget` (keeps the nodes nearest // the center if there are more than the budget allows). Mutates and returns the surviving subset // of `othersAll`. // // `sizeFactorFn(n)` (default: always 1) is an extra PER-NODE multiplier folded in alongside the // existing uniform `nodeSizeScale` — this is what lets the "Node size" Mappings control scale // each node individually by a chosen data field (e.g. employee count) while the existing // shrink-by-distance curve and the uniform nodeSizeScale slider keep working exactly as before // (sizeFactorFn simply defaults to a no-op 1× when sizing is "uniform"). function ht_computeVisibleNodes(othersAll, { edgeStyle, edgeStart, edgeHorizon, edgeFloorSize, nodeSizeScale, zoomFactor, renderBudget, sizeFactorFn = () => 1 }) { for (const d of othersAll) d.r = Math.sqrt(d.r2); let others; if (edgeStyle === "shrinkFloor") { others = othersAll; // nothing is ever dropped — every node stays visible at all times for (const d of others) { const t = ht_smoothstep(edgeStart, edgeHorizon, d.r); d.vr = (3 - (3 - edgeFloorSize) * t) * nodeSizeScale * sizeFactorFn(d.n) * zoomFactor; d.opacity = 1; } } else if (edgeStyle === "fade") { others = othersAll.filter((d) => d.r < edgeHorizon); for (const d of others) { const t = ht_smoothstep(edgeStart, edgeHorizon, d.r); d.vr = 3 * (1 - 0.75 * t) * nodeSizeScale * sizeFactorFn(d.n) * zoomFactor; d.opacity = 1 - 0.88 * t; } } else { // "cutoff" — legacy hard cutoff others = othersAll.filter((d) => d.r2 < edgeHorizon * edgeHorizon); for (const d of others) d.vr = 3 * nodeSizeScale * sizeFactorFn(d.n) * zoomFactor; } if (others.length > renderBudget - 1) { others.sort((a, b) => a.r2 - b.r2); others = others.slice(0, renderBudget - 1); } return others; } // computes the on-screen angle of each node's incoming edge (parent -> node), stored as `d.rotate` // (degrees), so leaf squares can be rotated to sit "square" to their own edge. Negates the y-delta // since data-space y increases upward but SVG rotate() operates in pixel space (y increases down). function ht_computeLeafRotations(others, rootNode, rootEntry, M) { for (const d of others) { const p = d.n.parent; if (p) { const zp = p === rootNode ? { re: rootEntry.x, im: rootEntry.y } : ht_apply(M, p.z0); d.rotate = Math.atan2(-(d.y - zp.im), d.x - zp.re) * (180 / Math.PI); } else { d.rotate = 0; } } } // finds the nearest hit-test entry (in screen-pixel distance) to a data-space point `p`, within // `maxPx` pixels — used to resolve double-clicks/taps regardless of which exact DOM element // (dot, tip box, label) was actually under the pointer. function ht_findNearestNode(hitTest, p, maxPx) { let best = null, bestDistPx = Infinity; for (const c of hitTest.entries) { const dxPx = (p.re - c.x) * hitTest.pxPerUnitX; const dyPx = (p.im - c.y) * hitTest.pxPerUnitY; const distPx = Math.hypot(dxPx, dyPx); if (distPx < bestDistPx) { bestDistPx = distPx; best = c; } } return bestDistPx <= maxPx ? best : null; } display("Viewer node-data helpers — ht_computeColorDomain, ht_computeVisibleNodes (now takes an optional per-node sizeFactorFn for field-based node sizing), ht_computeLeafRotations, ht_findNearestNode");36:T13db,// CELL: viewer-edges-labels-data — per-frame edge polyline + label data prep for ht_viewer4. // builds edge polylines: each edge is a run of {x,y,e} sample points (unique edge id `e`) so // Plot.line can draw them as separate series via the z channel, rather than a single Plot.link. // `edgeCurveFn` is whichever curve function edgeCurve selects (ht_geodesicPoints / ht_radialBumpPoints). // `edgeAttrIndex`, if given (see ht_buildEdgeAttrIndex), is an id-pair-keyed lookup into a SEPARATE, // optionally-provided edge-data table; each point of a matched edge gets that row attached as // `edgeRow`, so the "Edge color"/"Edge width" Mappings controls can read arbitrary fields from it // (an edge with no matching row simply gets `edgeRow: undefined`, which callers treat as "use the // default/uniform style" — the mapping is opt-in per edge, not required for every edge). // `edgeOpacityFn(parent, child)`, if given (see ht_viewer4's edgeFilterOpacityOf), returns this // edge's current category-filter opacity FRACTION (1 = fully shown, down to a low floor when // filtered out, or any value in between while a filter fade transition is in flight — see the // doc note above filterSet/filterFadeValue in ht_viewer4). Stored per point as `filterFrac` and // used directly as a stroke-opacity multiplier by the caller. Omitting `edgeOpacityFn` makes // every edge `filterFrac: 1`, i.e. a no-op (no active filter). function ht_buildEdgeLinkData(others, rootNode, rootEntry, visibleSet, M, edgeCurveFn, edgeSamples, edgeAttrIndex, edgeOpacityFn) { const linkData = []; let edgeId = 0; for (const d of others) { const p = d.n.parent; if (p && visibleSet.has(p)) { const zp = p === rootNode ? { re: rootEntry.x, im: rootEntry.y } : ht_apply(M, p.z0); const zc = { re: d.x, im: d.y }; const pts = edgeCurveFn(zp, zc, { n: edgeSamples }); const id = edgeId++; const edgeRow = edgeAttrIndex ? edgeAttrIndex.get(`${p.id}->${d.n.id}`) : undefined; const filterFrac = edgeOpacityFn ? edgeOpacityFn(p, d.n) : 1; for (const pt of pts) linkData.push({ x: pt.re, y: pt.im, e: id, edgeRow, filterFrac }); } } return linkData; } // selects labelable non-root nodes (within labelRadius + labelFadeWidth of center) and computes, // for each one: // - `labelOpacity`: full opacity within labelRadius, smoothly eased to 0 across the fade ring, // so labels fade out instead of abruptly vanishing at a hard cutoff. // - `labelY`: a data-space y position, offset upward from the node's own position by exactly // THAT node's own rendered radius (`d.vr`) plus a gap — not a single shared "worst case" // constant. This matters because node radii vary continuously (the shrinkFloor/fade curves // shrink nodes smoothly as they approach the boundary, and now node size can also vary by a // data field), so a shared constant clearance would either overlap larger nodes or // over-space smaller ones. // // WHY THIS WORKS AS A "y" CHANNEL WHEN A CONSTANT "dy" WOULDN'T: Plot.text's `dy` option only // accepts a plain constant (a per-datum function is silently ignored — confirmed empirically, // see the doc note on the root's label), but `y` is a normal per-datum channel, just like // `vr`/`opacity`/`rotate` already are on the dot mark. So instead of a post-scale pixel `dy`, // we bake the desired *pixel* clearance directly into the *data-space* position fed into the // `y` channel — converting a pixel amount into a data-space delta via `pxPerUnitY` (this // conversion is exact, not approximate, because Plot's default continuous position scale is // a plain affine/linear map from data domain to pixel range: see `render()` for how // `pxPerUnitY` is derived analytically from `height`/`margin`/`domainR`, before Plot.plot() // even runs). // // Also returns the outer fade-ring radius (used to draw the optional dashed "showLabelRadius" // circles). Note: the ROOT's label does NOT need this treatment — it already gets an exactly // correct constant `dy` from its own dedicated single-row Plot.text mark, since a mark with // exactly one row has no "shared constant vs. varying values" tension to begin with. function ht_computeLabelData(others, { labelRadius, labelFadeWidth, labelBudget, labelGap, zoomFactor, pxPerUnitY }) { const labelFadeRadius = labelRadius + labelFadeWidth; const labelData = others.filter((d) => d.r < labelFadeRadius).slice(0, labelBudget); for (const d of labelData) { d.labelOpacity = 1 - ht_smoothstep(labelRadius, labelFadeRadius, d.r); d.labelY = d.y + (d.vr + labelGap * zoomFactor) / pxPerUnitY; } return { labelData, labelFadeRadius }; } display("Viewer edge/label data helpers — ht_buildEdgeLinkData (now optionally attaches a matched row from a separate edge-data table as `edgeRow`, via edgeAttrIndex, AND a continuous `filterFrac` opacity fraction via an optional `edgeOpacityFn(parent, child)` — see ht_viewer4's applyFilter/clearFilter/startFilterTransition), ht_computeLabelData"); 37:T1d45,// CELL: viewer-dom-helpers — DOM/SVG construction & calibration helpers for ht_viewer4. // builds the persistent DOM chrome for a viewer instance: the outer container, an inner slot the // live Plot figure gets swapped into on every render (leaving statsOverlay untouched), and a // small fixed-position overlay for live stats (see ht_formatStatsText) that's updated via // textContent rather than ever being re-inserted into Plot's own DOM. function ht_buildViewerChrome() { const container = html`

`; const plotSlot = html`

`; const statsOverlay = html`

`; container.append(plotSlot, statsOverlay); return { container, plotSlot, statsOverlay }; } // draws a dashed circle of a given data-space radius (used for the disk boundary and, optionally, // the label-radius rings) by sampling points and mapping them through Plot's own x/y scales. // `strokeWidth` lets the ring's line weight scale with zoomFactor, just like everything else. function ht_makeCirclePath(xScaleObj, yScaleObj, radius, color, strokeWidth = 1) { const pts = d3.range(0, 2 * Math.PI + 0.1, 0.1).map((t) => [xScaleObj.apply(radius * Math.cos(t)), yScaleObj.apply(radius * Math.sin(t))]); const el = document.createElementNS("http://www.w3.org/2000/svg", "path"); el.setAttribute("d", d3.line()(pts)); el.setAttribute("fill", "none"); el.setAttribute("stroke", color); el.setAttribute("stroke-width", strokeWidth); el.setAttribute("stroke-dasharray", "2,3"); return el; } // builds a curved text label that follows the top (or bottom) arc of a circle of the given // data-space radius — used to caption the "full label area" / "fade label area" rings drawn by // ht_makeCirclePath. Returns [invisibleArcPath, textEl]; append BOTH to the svg (the text // references the arc path by id via , so the arc must be present in the DOM, but its // stroke is "none" — it's purely a curve for the text to follow, not a visible mark). // Deliberately uses a serif/italic font, distinct from the node labels' sans-serif Plot font, so // these ring captions are never confused with actual node labels. // // `liftPx` lifts the caption clear of the ring's own dashed line rather than sitting directly on // top of it. NOTE: this is done by nudging the (invisible) guide arc's *radius* itself slightly // larger than the visible ring — NOT via a `dy` attribute on , which turns out not to // be a supported attribute on that element (browsers silently ignore it; confirmed empirically it // has no visible effect), unlike on plain /. `fontSize` and `liftPx` are both // expected to be pre-multiplied by the caller's zoomFactor, so the caption (and its clearance // from the ring) scales consistently with everything else when zooming. function ht_makeCircleLabel(xScaleObj, yScaleObj, radius, text, pathId, { position = "top", fontSize = 10, color = "#666", liftPx = 2 } = {}) { // convert the desired pixel lift into a data-space radius delta using the scale's local // derivative (Plot's continuous scales are affine, so this is exact, not an approximation). const pxPerUnitY = Math.abs(yScaleObj.apply(1) - yScaleObj.apply(0)); const liftRadius = pxPerUnitY > 0 ? liftPx / pxPerUnitY : 0; const effectiveRadius = radius + liftRadius; // slightly outside the visible ring => lifted clear of its line // an invisible semicircular guide path swept left-to-right across the top (or bottom) of the // circle, so lays the text out curving naturally with the circle instead of upside // down or backwards (the sweep direction here is chosen specifically to read left-to-right). const n = 40; const pts = d3.range(0, n + 1).map((i) => { const t = position === "top" ? Math.PI - (Math.PI * i) / n : Math.PI + (Math.PI * i) / n; return [xScaleObj.apply(effectiveRadius * Math.cos(t)), yScaleObj.apply(effectiveRadius * Math.sin(t))]; }); const arcPath = document.createElementNS("http://www.w3.org/2000/svg", "path"); arcPath.setAttribute("d", d3.line()(pts)); arcPath.setAttribute("fill", "none"); arcPath.setAttribute("stroke", "none"); arcPath.setAttribute("id", pathId); const textPath = document.createElementNS("http://www.w3.org/2000/svg", "textPath"); textPath.setAttribute("href", `#${pathId}`); textPath.setAttribute("startOffset", "50%"); textPath.setAttribute("text-anchor", "middle"); textPath.textContent = text; const textEl = document.createElementNS("http://www.w3.org/2000/svg", "text"); textEl.setAttribute("font-size", fontSize); textEl.setAttribute("fill", color); textEl.setAttribute("font-family", "Georgia, 'Times New Roman', serif"); textEl.setAttribute("font-style", "italic"); textEl.setAttribute("letter-spacing", "0.4"); textEl.style.userSelect = "none"; textEl.appendChild(textPath); return [arcPath, textEl]; } // derives a data-space <-> pixel-space calibration from a rendered Plot figure's scales: // `toData(clientX, clientY)` converts a pointer event's viewport coordinates to data space, and // `pxPerUnitX`/`pxPerUnitY` convert data-space distances to pixel distances (used for hit-testing). function ht_makeScaleCalibration(svg, xScaleObj, yScaleObj, domainR) { const pxAtNeg = xScaleObj.apply(-domainR), pxAtPos = xScaleObj.apply(domainR); const pyAtNeg = yScaleObj.apply(-domainR), pyAtPos = yScaleObj.apply(domainR); const toData = (clientX, clientY) => { const rect = svg.getBoundingClientRect(); const px = clientX - rect.left, py = clientY - rect.top; const x = -domainR + ((px - pxAtNeg) / (pxAtPos - pxAtNeg)) * (2 * domainR); const y = -domainR + ((py - pyAtNeg) / (pyAtPos - pyAtNeg)) * (2 * domainR); return { re: x, im: y }; }; return { toData, pxPerUnitX: (pxAtPos - pxAtNeg) / (2 * domainR), pxPerUnitY: (pyAtPos - pyAtNeg) / (2 * domainR) }; } // assembles the hit-testing index used by ht_findNearestNode (see viewer-node-data cell). function ht_buildHitTestIndex(others, rootEntry, pxPerUnitX, pxPerUnitY) { return { entries: [ ...others.map((d) => ({ n: d.n, x: d.x, y: d.y })), { n: rootEntry.n, x: rootEntry.x, y: rootEntry.y } ], pxPerUnitX, pxPerUnitY }; } // belt-and-suspenders: explicitly forbid text selection on everything Plot renders (tip boxes, // labels, legend) so a click-drag never turns into a native text-selection drag instead of panning. function ht_disableTextSelection(svg) { svg.style.userSelect = "none"; svg.style.webkitUserSelect = "none"; } // formats the small fixed-position live-stats readout text. function ht_formatStatsText(visibleCount, totalCount, ms, rootPinned) { return `${visibleCount.toLocaleString()}/${totalCount.toLocaleString()} nodes · ${ms.toFixed(1)}ms${rootPinned ? " · root pinned" : ""}`; } display("Viewer DOM/SVG helpers — ht_buildViewerChrome, ht_makeCirclePath (takes strokeWidth), ht_makeCircleLabel (lifts the caption clear of its ring by nudging the invisible guide arc's radius outward — NOT via , which isn't actually a supported attribute there), ht_makeScaleCalibration, ht_buildHitTestIndex, ht_disableTextSelection, ht_formatStatsText");38:T1392,// CELL: mapping-helpers — field discovery + self-managed (non-Plot) scales that back the four // "Mappings" pane controls: node color, node size, edge color, edge width. // // WHY SELF-MANAGED SCALES (not Plot's built-in color/size scales) FOR EDGES AND FOR NODE SIZE: // Plot only gives you ONE shared "color" scale by default (fill and stroke both draw from it // unless you go out of your way to define a second named scale) — but node color-by-field and // edge color-by-field are two totally independent mappings with unrelated domains, so sharing one // scale would be wrong. Rather than fight Plot's scale-sharing, edge color/width (and node size) // are computed here as LITERAL values (a real CSS color string, a real pixel width, a real pixel // radius factor) using plain d3 scales — confirmed empirically that a mark's color channel, when // every value already looks like a valid CSS color, is rendered as-is and never touches any scale // or legend (see the test cell above this one). Node color-by-field, by contrast, DOES go through // Plot's real scale (see viewer-main), specifically so it still gets an automatic legend — that's // a feature worth keeping for the *node* mapping (the primary one), even though it means edges and // node color use two different mechanisms under the hood. // classifies a set of raw values as "numeric" (every non-null/non-empty value is a finite number) // or "categorical" (anything else) — used to decide continuous vs. discrete treatment. function ht_fieldKind(values) { let sawAny = false; for (const v of values) { if (v == null || v === "") continue; sawAny = true; if (typeof v !== "number" || !Number.isFinite(v)) return "categorical"; } return sawAny ? "numeric" : "categorical"; } // collects every field name found across a set of plain data rows (e.g. `.data` of each tree // node, or rows of an optional edge-data table), excluding structural id-like fields, along with // each field's kind ("numeric" | "categorical") — used to populate the Mappings dropdowns. function ht_collectFields(rows, excludeKeys = ["id", "parentId", "source", "target"]) { const keys = new Set(); for (const row of rows) for (const k of Object.keys(row)) if (!excludeKeys.includes(k)) keys.add(k); return Array.from(keys).sort().map((name) => ({ name, kind: ht_fieldKind(rows.map((r) => r[name])) })); } // builds an O(1) lookup from an optional edge-data table (rows with `source`/`target` fields // matching the tree's own node ids) to that row's extra fields — used to color/size-by-field an // edge whose two endpoint ids match a row in a SEPARATE, optionally-provided dataset (distinct // from the main hierarchical node data). function ht_buildEdgeAttrIndex(edgesData, sourceKey = "source", targetKey = "target") { const m = new Map(); for (const row of edgesData) m.set(`${row[sourceKey]}->${row[targetKey]}`, row); return m; } // a categorical (d3.scaleOrdinal) or continuous (sequential) literal-color function for a given // field's values — returns a plain CSS color string (or null for missing/invalid values, which // callers should then fall back to a default constant color for). function ht_buildLiteralColorScale(values, kind) { if (kind === "numeric") { const nums = values.map(Number).filter(Number.isFinite); const [mn, mx] = d3.extent(nums); const interp = d3.interpolateBlues; return (v) => { const n = Number(v); if (!Number.isFinite(n)) return null; return interp(mn === mx ? 0.5 : (n - mn) / (mx - mn)); }; } const domain = Array.from(new Set(values.filter((v) => v != null && v !== ""))).sort(); const ord = d3.scaleOrdinal(domain, d3.schemeTableau10); return (v) => (v == null || v === "" ? null : ord(v)); } // maps a numeric field's values to a multiplicative size factor (area-true via sqrt), clamped to // a reasonable [0.5x, 2.4x] range — used to scale node radii by a chosen numeric field. function ht_buildSizeFactorScale(values) { const nums = values.map(Number).filter(Number.isFinite); const [mn, mx] = d3.extent(nums); const scale = d3.scaleSqrt().domain([mn ?? 0, mx ?? 1]).range([0.5, 2.4]).clamp(true); return (v) => { const n = Number(v); return Number.isFinite(n) ? scale(n) : 1; }; } // maps a numeric field's values to a literal pixel stroke width, centered on `baseWidth` (area // analog for lines: sqrt scale so visual "weight" scales roughly linearly with the field). function ht_buildWidthScale(values, baseWidth) { const nums = values.map(Number).filter(Number.isFinite); const [mn, mx] = d3.extent(nums); const scale = d3.scaleSqrt().domain([mn ?? 0, mx ?? 1]).range([baseWidth * 0.4, baseWidth * 2.5]).clamp(true); return (v) => { const n = Number(v); return Number.isFinite(n) ? scale(n) : baseWidth; }; } display("Mapping helpers — ht_fieldKind, ht_collectFields, ht_buildEdgeAttrIndex, ht_buildLiteralColorScale, ht_buildSizeFactorScale, ht_buildWidthScale");39:T2050,// CELL: root-wave — a lightweight D3-driven "radar ping" animation that stays locked onto the // root node's on-screen position and scale, completely decoupled from ht_viewer4's own per-frame // Plot re-render (which recreates a brand new

/

) and the color-legend swatches block are all rendered as HTML // elements that are SIBLINGS of the
s with no color of // their own, so ordinary inheritance carries the figure's color down to them) — but NOT the // title/subtitle: this notebook's own page stylesheet has a rule `h1,h2,h3,h4,h5,h6 { color: // var(--theme-foreground-alt) }` which, despite its low specificity, still beats plain // inheritance (confirmed empirically: h2/h3's computed color stayed page-default even after // setting the figure's color) — CSS gives ANY explicit rule targeting an element priority over // inheritance from an ancestor, regardless of how unspecific that rule is. So the title/ // subtitle need `color` set directly (inline) on the
/
elements themselves, which, as // inline styles, outrank that external rule. plotFigure.style.color = plotText; // still needed for the legend labels const titleEl = plotFigure.querySelector(":scope > h2"); const subtitleEl = plotFigure.querySelector(":scope > h3"); if (titleEl) titleEl.style.color = plotText; if (subtitleEl) subtitleEl.style.color = plotText; const svg = plotFigure.querySelector(":scope > svg"); const xScaleObj = plotFigure.scale("x"), yScaleObj = plotFigure.scale("y"); const calib = ht_makeScaleCalibration(svg, xScaleObj, yScaleObj, domainR); toData = calib.toData; // Plot's Tip mark box fill uses `fill="var(--plot-background)"` (confirmed by inspecting the // rendered element), and Plot's own generated stylesheet hardcodes // `--plot-background: white` via a zero-specificity `:where(.plot-xxx)` rule. Passing // `--plot-background` through Plot.plot's `style` option does NOT work — Plot's style // application silently drops custom-property keys (confirmed empirically: it never lands in // the rendered `style="..."` attribute) — so it must be set directly on the svg element via // the real DOM API instead, which — being an inline style — has higher specificity than the // `:where()` rule and correctly overrides it. This is what makes hover tooltips render as a // black box in dark mode instead of white-text-on-white. svg.style.setProperty("--plot-background", plotBg); svg.prepend(ht_makeCirclePath(xScaleObj, yScaleObj, 1, diskStrokeColor)); if (showLabelRadius) { // ring stroke width and caption font size/lift all scale with zoomFactor, same as every // other rendered pixel size in the viewer, so zooming in makes these bigger too, not just // farther apart. svg.prepend(ht_makeCirclePath(xScaleObj, yScaleObj, labelFadeRadius, labelOuterColor, 1 * zoomFactor)); // outer: fade boundary svg.prepend(ht_makeCirclePath(xScaleObj, yScaleObj, labelRadius, labelInnerColor, 1 * zoomFactor)); // inner: full-opacity zone // curved captions on top of BOTH rings (appended, not prepended, so they paint above // everything else and stay readable), each lifted a couple pixels clear of its own ring's // dashed line (via a radius nudge on the invisible guide arc — see ht_makeCircleLabel for // why a doesn't actually work for this). svg.append(...ht_makeCircleLabel(xScaleObj, yScaleObj, labelRadius, "full label area", `${instanceId}-fullArc`, { position: "top", color: labelInnerColor, fontSize: 10 * zoomFactor, liftPx: 2 * zoomFactor })); svg.append(...ht_makeCircleLabel(xScaleObj, yScaleObj, labelFadeRadius, "fade label area", `${instanceId}-fadeArc`, { position: "top", color: labelOuterTextColor, fontSize: 10 * zoomFactor, liftPx: 2 * zoomFactor })); } ht_disableTextSelection(svg); hitTest = ht_buildHitTestIndex(others, rootEntry, calib.pxPerUnitX, calib.pxPerUnitY); plotSlot.replaceChildren(plotFigure); // statsOverlay is a separate, untouched sibling // keep the root-wave overlay glued to the root's current on-screen position/scale — a // persistent, separately-animating
${svgEl}
drag to pan
`, // programmatically holds the knob in direction (dirX, dirY) at `intensity` (0..1) of the // track's radius, continuously panning until stopExternal() — ignored while the user is // actively dragging (their input always wins). driveExternal(dirX, dirY, intensity = 0.5) { if (mode === "userDrag") return; mode = "external"; const mag = Math.hypot(dirX, dirY) || 1; setKnobVisual((dirX / mag) * intensity * trackR, (dirY / mag) * intensity * trackR); startLoopIfNeeded(); }, stopExternal() { if (mode !== "external") return; mode = "idle"; if (raf) { cancelAnimationFrame(raf); raf = null; } setKnobVisual(0, 0); }, onUserDragStart(cb) { onUserDragStartCb = cb; } }; } // Builds a slider bound to a live viewer option via setOptions(). `toOption`/`format` let the // slider's raw UI value map onto a differently-scaled option value. // // `label`, if given, renders as leading text next to the current value (the original layout); // if omitted (`null`, the default), only the current value is shown (right-aligned) with no // leading text — used where a slider sits directly under its OWN section heading, so repeating // the same word as both a heading and a label would be redundant (see the "Node size"/"Edge // width" Mappings sections in ht_buildMappingsPane). // // Returns `{ element, update(rawValue) }` rather than just the element: `update` sets the // slider's displayed position/text WITHOUT firing the `input` event or calling // `viewer.setOptions` — this is what lets external code (see the "Zoom" slider below) keep the // slider in sync when the underlying option changes for some other reason (scroll-wheel zoom, // or `reset()` animating it back), without creating a feedback loop back into the viewer. function ht_buildSlider(viewer, { label = null, min, max, step = 1, value, toOption = (v) => ({ }), format = (v) => String(v) } = {}) { const out = html`${format(value)}`; const input = html``; input.addEventListener("input", () => { const v = +input.value; out.textContent = format(v); viewer.setOptions(toOption(v)); }); const header = label ? html`
${label}${out}
` : html`
${out}
`; const element = html`
${header}${input}
`; function update(rawValue) { input.value = rawValue; out.textContent = format(rawValue); } return { element, update }; } // Builds a labeled checkbox bound to a live viewer option via setOptions(). // // Returns `{ element, update(checked) }` — same pattern as ht_buildSlider: `update` sets the // checkbox's checked state WITHOUT firing the `input` event or calling `viewer.setOptions`, so // external code can keep the checkbox in sync when the underlying option changes for some OTHER // reason (e.g. applyFilter() auto-disabling `showRootWave` — see the "highlight root node" // checkbox's `viewer.onChange` subscription in ht_buildControlPanel below), without creating a // feedback loop back into the viewer. function ht_buildCheckbox(viewer, { label, checked = false, toOption = (v) => ({}) } = {}) { const input = html``; input.checked = checked; input.addEventListener("input", () => viewer.setOptions(toOption(input.checked))); const element = html`${input}${label}`; function update(v) { input.checked = v; } return { element, update }; } // Builds a labeled ${optionsList.map( (o) => html`` )}`; select.addEventListener("input", () => { viewer.setOptions(toOption(select.value)); onInput?.(select.value); }); return html`${label}${select}`; } // Builds a labeled native color-picker () bound to a live viewer option via // setOptions() — used by the "Node color" / "Edge color" single-color controls. function ht_buildColorInput(viewer, { label, value = "#4269d0", toOption = (v) => ({}) } = {}) { const input = html``; input.addEventListener("input", () => viewer.setOptions(toOption(input.value))); return html`${label}${input}`; } // Builds one "Mappings" pane row that lets the user choose HOW something is colored/sized: a // dropdown of modes — always including the given `fixedModes` (e.g. "Branch (default)" / // "Single color", or "Uniform (default)") — plus one entry per available data field (encoded as // `field:`, optionally annotated with its kind, e.g. "gender (categorical)"). Selecting a // fixed mode with an associated extra control (e.g. "Single color" needs a color picker) reveals // that control; selecting a field mode reveals nothing extra (the field IS the mapping). Only one // extra control is shown at a time, toggled via plain `style.display` swaps on `input` — there's // no data-binding framework here, just a handful of DOM nodes and one event listener. // // `label`, if given, renders as a leading `` above the dropdown (the original layout); if // omitted (`null`, the default), the dropdown is rendered bare — used where the dropdown sits // directly under its OWN section heading + a sibling slider (see "Node size"/"Edge width" below), // so a third repeated label would be redundant. // `fixedModes`: array of `{value, label, extra?}` — `extra`, if given, is a DOM element to reveal // when that mode is selected (e.g. the color-picker for "single"). // `fields`: array of `{name, kind}` (see ht_collectFields) to offer as `field:` entries. // `toOption({mode, field})`: called with the parsed selection on every change. function ht_buildMappingModeRow({ label = null, fixedModes, fields, initialValue, toOption }) { const fieldOptions = fields.map((f) => ({ value: `field:${f.name}`, label: `${f.name} (${f.kind})` })); const optionsList = [...fixedModes.map((m) => ({ value: m.value, label: m.label })), ...fieldOptions]; const extrasByValue = new Map(fixedModes.filter((m) => m.extra).map((m) => [m.value, m.extra])); const select = html``; function applyVisibility(v) { for (const el of extrasByValue.values()) el.style.display = "none"; extrasByValue.get(v)?.style && (extrasByValue.get(v).style.display = ""); } applyVisibility(initialValue); select.addEventListener("input", () => { applyVisibility(select.value); const v = select.value; const parsed = v.startsWith("field:") ? { mode: "field", field: v.slice(6) } : { mode: v, field: null }; toOption(parsed); }); const selectWrap = label ? html`${label}${select}` : select; const extrasContainer = html`
${fixedModes.filter((m) => m.extra).map((m) => m.extra)}
`; return html`
${selectWrap}${extrasContainer}
`; } // Builds the full "Mappings" pane: four independent sections (Node color, Node size, Edge color, // Edge width), each driving the corresponding ht_viewer4 option pair via setOptions. Reads // `viewer.nodeFields`/`viewer.edgeFields`/`viewer.hasEdgesData` (computed once at construction — // see the viewer-main cell) to populate each dropdown with whatever fields actually exist in the // data, so e.g. the flare demo (no extra fields, no edge data) simply shows fewer choices than the // gender/employees org-chart demo, with no dead ends either way. // // LAYOUT: "Node size" and "Edge width" both follow the same consistent shape — a single bold // section heading, then a SLIDER (the uniform value — nodeSizeScale / edgeWidth), then the mode // DROPDOWN (Uniform (default) / by a field) directly underneath, with NEITHER the slider nor the // dropdown repeating their own label — the section heading already says what they're both about. // "Node color" and "Edge color" don't have a uniform-value slider (a color isn't a single scalar // the way a size/width is), so their dropdown keeps its own label as the section's only heading. // // UNITS: both sliders also share the exact same "×" MULTIPLIER currency (range 0.3–3, step 0.1, // default 1.0×) rather than raw pixels — even though under the hood `edgeWidth` is still a plain // px value (the number ht_viewer4 actually multiplies by zoomFactor and passes to Plot as // strokeWidth). The edge-width slider's raw 0.3–3 reading is converted to that px value via a // fixed base (`edgeWidthBasePx`, the original default of 1.5px, i.e. what "1.0×" means) — purely // a presentation-layer rescaling in this one call to `toOption`, so every other part of the // viewer (the "field" width mapping's base width, the zoom multiplier, etc.) keeps working in // px exactly as before. function ht_buildMappingsPane(viewer) { const numericNodeFields = viewer.nodeFields.filter((f) => f.kind === "numeric"); const numericEdgeFields = viewer.edgeFields.filter((f) => f.kind === "numeric"); const sectionHeadingStyle = "font-size:11px; font-weight:600; color:var(--ht-text,#333);"; // ---- 1. Node color ---- const nodeColorPicker = ht_buildColorInput(viewer, { label: "Color", value: "#4269d0", toOption: (v) => ({ nodeColorSingle: v }) }); const nodeColorRow = ht_buildMappingModeRow({ label: "Node color", fixedModes: [ { value: "branch", label: "By branch (default)" }, { value: "single", label: "Single color", extra: nodeColorPicker } ], fields: viewer.nodeFields, initialValue: "branch", toOption: ({ mode, field }) => viewer.setOptions({ nodeColorMode: mode, nodeColorField: field }) }); // ---- 2. Node size — heading, then slider (nodeSizeScale, "×" multiplier), then dropdown ---- const nodeSizeSlider = ht_buildSlider(viewer, { min: 0.3, max: 3, step: 0.1, value: 1, toOption: (v) => ({ nodeSizeScale: v }), format: (v) => `${v.toFixed(1)}×` }); const nodeSizeRow = ht_buildMappingModeRow({ fixedModes: [{ value: "uniform", label: "Uniform (default)" }], fields: numericNodeFields, initialValue: "uniform", toOption: ({ mode, field }) => viewer.setOptions({ nodeSizeMode: mode, nodeSizeField: field }) }); const nodeSizeNote = numericNodeFields.length ? null : html`
no numeric node fields available
`; const nodeSizeSection = html`
Node size
${nodeSizeSlider.element}${nodeSizeRow}${nodeSizeNote}
`; // ---- 3. Edge color ---- const edgeColorPicker = ht_buildColorInput(viewer, { label: "Color", value: "#999999", toOption: (v) => ({ edgeColorSingle: v }) }); const edgeColorRow = ht_buildMappingModeRow({ label: "Edge color", fixedModes: [{ value: "single", label: "Single color (default)", extra: edgeColorPicker }], fields: viewer.hasEdgesData ? viewer.edgeFields : [], initialValue: "single", toOption: ({ mode, field }) => viewer.setOptions({ edgeColorMode: mode, edgeColorField: field }) }); const edgeColorNote = viewer.hasEdgesData ? null : html`
no separate edge data provided
`; // ---- 4. Edge width — heading, then slider ("×" multiplier onto edgeWidthBasePx px), then dropdown ---- const edgeWidthBasePx = 1.5; // what the slider's "1.0×" reading maps to — the original default edgeWidth const edgeWidthSlider = ht_buildSlider(viewer, { min: 0.3, max: 3, step: 0.1, value: 1, toOption: (v) => ({ edgeWidth: edgeWidthBasePx * v }), format: (v) => `${v.toFixed(1)}×` }); const edgeWidthRow = ht_buildMappingModeRow({ fixedModes: [{ value: "uniform", label: "Uniform (default)" }], fields: viewer.hasEdgesData ? numericEdgeFields : [], initialValue: "uniform", toOption: ({ mode, field }) => viewer.setOptions({ edgeWidthMode: mode, edgeWidthField: field }) }); const edgeWidthNote = viewer.hasEdgesData ? (numericEdgeFields.length ? null : html`
no numeric edge fields available
`) : html`
no separate edge data provided
`; const edgeWidthSection = html`
Edge width
${edgeWidthSlider.element}${edgeWidthRow}${edgeWidthNote}
`; return html`

${nodeColorRow}
${nodeSizeSection}

${edgeColorRow}${edgeColorNote}
${edgeWidthSection}
`; } // Builds the "filter by attribute" section of the Filter pane (see ht_buildFilterPane below): // search-and-highlight-a-subtree by a categorical node attribute (see ht_viewer4's // applyFilter/clearFilter/getFieldValues). Two dropdowns sit side by side in one row — the first // picks WHICH categorical field of the node data to filter by, the second picks WHICH distinct // value (category) of that field to match — followed by a smaller "Apply filter" / "Clear // filter" button pair, ALSO sitting side by side in one row directly below (rather than each // taking its own full-width row, since these two short labels don't need the extra vertical space // that would otherwise separate them). // // The second dropdown is populated (and re-populated every time the first one changes) straight // from `viewer.getFieldValues(fieldName)` — the actual distinct, non-empty values present in the // data for whichever field is currently selected — so it's never stale or showing values that // don't exist for the current attribute. // // Pressing "Apply filter" calls `viewer.applyFilter(attr, category)`, which does all the actual // work (top-down search for the first matching node, take its whole subtree, fade every node/edge // toward its new target opacity while CONCURRENTLY panning the matched node to the disk's center // — both over the same fixed 0.8s — auto-turning off the root-wave highlight if it's on and the // matched node isn't the actual root — see ht_viewer4's doc note); this pane just reports back // whether a match was found. "Clear filter" calls `viewer.clearFilter()` to fade everything back // to full opacity. // // Returns `null` (rather than an element) if the data has no categorical fields at all, so // ht_buildFilterPane can show its own placeholder note instead of a pair of dropdowns with // nothing useful to offer (same pattern as the Mappings pane's various "no X available" notes). function ht_buildFilterByAttributeSection(viewer) { const categoricalFields = viewer.nodeFields.filter((f) => f.kind === "categorical"); if (!categoricalFields.length) return null; const selectStyle = "flex:1; min-width:0; background:var(--ht-input-bg,#fff); color:var(--ht-text,#333); border:1px solid var(--ht-border,#ccc); border-radius:4px; padding:2px;"; const attrSelect = html``; const valueSelect = html``; // (re)populates the second dropdown with every distinct, non-empty value of whichever attribute // is currently selected in the first dropdown — called once up front, and again on every change. function populateValues() { const values = viewer.getFieldValues(attrSelect.value); valueSelect.replaceChildren(...values.map((v) => html``)); } populateValues(); attrSelect.addEventListener("input", populateValues); // smaller than the panel's other full-width buttons (padding:3px 0 instead of 4px, font-size // pinned to 11px rather than inheriting the browser's default button font size), and `flex:1` // instead of `width:100%` so the two share one row edge-to-edge rather than each spanning it. const btnStyle = "flex:1; background:var(--ht-input-bg,#fff); color:var(--ht-text,#333); border:1px solid var(--ht-border,#ccc); border-radius:4px; padding:3px 0; font-size:11px;"; const applyBtn = html``; const clearBtn = html``; const statusEl = html`
`; applyBtn.addEventListener("click", () => { const attr = attrSelect.value; const category = valueSelect.value; const match = viewer.applyFilter(attr, category); statusEl.textContent = match ? `Showing the subtree rooted at the first node where ${attr} = "${category}".` : `No node found where ${attr} = "${category}".`; }); clearBtn.addEventListener("click", () => { viewer.clearFilter(); statusEl.textContent = ""; }); return html`

Filter by attribute

${attrSelect}${valueSelect}

${applyBtn}${clearBtn}
${statusEl}
`; } // escapes the 5 HTML-significant characters — used below so a label containing them (e.g. a // literal "<" or "&" in someone's data) can still be safely interpolated into a plain string that // gets fed into innerHTML-like DOM construction, without ever being misinterpreted as markup. function ht_escapeHtml(s) { return s.replace(/&/g, "&").replace(//g, ">").replace(/"/g, """); } // builds a `` rendering `text` with every case-insensitive occurrence of `query` wrapped in // a highlighted `` — used by the search results list below to visually show where the // typed substring actually matched within each candidate label. Handles the (rare but possible) // case of `query` appearing more than once in the same label by highlighting every occurrence, // not just the first. Falls back to plain, unhighlighted text if `query` is empty. function ht_highlightSubstring(text, query) { if (!query) return html`${text}`; const lower = text.toLowerCase(); const q = query.toLowerCase(); let html_ = ""; let i = 0; while (i < text.length) { const idx = lower.indexOf(q, i); if (idx < 0) { html_ += ht_escapeHtml(text.slice(i)); break; } html_ += ht_escapeHtml(text.slice(i, idx)); html_ += `${ht_escapeHtml(text.slice(idx, idx + q.length))}`; i = idx + q.length; } const span = document.createElement("span"); span.innerHTML = html_; return span; } // Builds the "search for a node" section of the Filter pane (see ht_buildFilterPane below): a // single-line text field that live-searches every node's own label text (the same display string // shown as its label/tooltip — see ht_viewer4's `label` option), rather than a categorical data // field the way "filter by attribute" does. // // As the user types (or deletes — the `input` event fires for both), the results list right below // the text field is recomputed on every single keystroke from `viewer.findLabelsBySubstring(...)` // — every distinct node label containing the current text as a case-insensitive substring, each // rendered with the matching portion highlighted (see ht_highlightSubstring), capped at // `maxResults` entries and scrollable beyond that. The list is hidden entirely while the field is // empty. Clicking a result COPIES that label into the text field (and re-filters the list down to // it) — it does NOT immediately jump there; the user still has to press "Search node" themselves // (per spec), which also works just as well if they instead type the full label out by hand // without ever touching the list. // // Pressing "Search node" calls `viewer.goToLabel(term, 800)` — an EXACT (not substring) match // against the current text field contents, panning to dead center over a fixed 800ms (0.8s) if // found. If nothing matches exactly, nothing happens to the view at all (per spec) — the status // line below just reports that no match was found, exactly mirroring how the "filter by // attribute" section above reports a failed match. function ht_buildNodeSearchSection(viewer) { const maxResults = 20; const input = html``; const resultsList = html`
`; const searchBtnStyle = "width:100%; background:var(--ht-input-bg,#fff); color:var(--ht-text,#333); border:1px solid var(--ht-border,#ccc); border-radius:4px; padding:4px 0; font-size:12px;"; const searchBtn = html``; const statusEl = html`
`; function updateResults() { const q = input.value; if (!q.trim()) { resultsList.style.display = "none"; resultsList.replaceChildren(); return; } const matches = viewer.findLabelsBySubstring(q).slice(0, maxResults); if (!matches.length) { resultsList.style.display = "none"; resultsList.replaceChildren(); return; } resultsList.style.display = "flex"; resultsList.replaceChildren(...matches.map((matchLabel) => { const item = html`
`; item.append(ht_highlightSubstring(matchLabel, q)); // clicking a result COPIES it into the text field (and re-runs the search against that // full text — which will normally narrow the list down to just this one exact match) — // it deliberately does NOT jump to the node itself; the user still presses "Search node". item.addEventListener("click", () => { input.value = matchLabel; updateResults(); input.focus(); }); item.addEventListener("mouseenter", () => { item.style.background = "var(--ht-divider,#eee)"; }); item.addEventListener("mouseleave", () => { item.style.background = ""; }); return item; })); } input.addEventListener("input", updateResults); function runSearch() { const term = input.value.trim(); if (!term) return; const target = viewer.goToLabel(term, 800); // fixed 0.8s pan, independent of animDuration statusEl.textContent = target ? `Centered on "${term}".` : `No node found matching "${term}".`; } searchBtn.addEventListener("click", runSearch); // Enter in the text field is a natural, expected shortcut for "run the search" (mirrors how a // browser's own address bar / a typical search box behaves) — doesn't replace the button, just // supplements it. input.addEventListener("keydown", (e) => { if (e.key === "Enter") runSearch(); }); return html`

Search for a node
${input} ${resultsList} ${searchBtn} ${statusEl}
`; } // Builds the full "Filter" pane: two independent sections, stacked with a divider between them // when both are present — "Filter by attribute" (see ht_buildFilterByAttributeSection; highlights // an entire subtree matching a categorical data field) and "Search for a node" (see // ht_buildNodeSearchSection; jumps straight to any single node by its label text, with a live, // highlighted substring-match results list). The first section is entirely omitted (no divider // either) if the data has no categorical fields at all — the search section works regardless, // since it only depends on `label`, which every node always has. function ht_buildFilterPane(viewer) { const filterSection = ht_buildFilterByAttributeSection(viewer); const searchSection = ht_buildNodeSearchSection(viewer); const divider = filterSection ? html`
` : null; const filterFallback = filterSection ? null : html`
no categorical node fields available to filter by
`; return html`
${filterSection ?? filterFallback} ${divider} ${searchSection}
`; } // Builds the "Animation demo" auto-play journey's Play/Stop buttons, wired to the single // ht_buildExplorerConditional implementation (see the viewer-exploration cell). Also auto-stops // the moment the user grabs the joystick themselves (see ht_buildJoystick's onUserDragStart). // // Laid out as a small flex column with an explicit, small `gap` between the two buttons, CENTERED // (via justify-content:center) within a fixed-height (`joystickSize`) box. This keeps the two // buttons close together while still landing their combined block's own center exactly at the // box's center — which lines up with the joystick knob's vertical center, so long as this sits in // a column with the same heading+gap prefix as the joystick's own column (see // ht_buildControlPanel below). Unlike splitting the box into two halves (the previous approach), // an explicit `gap` doesn't depend on — or need to counteract — the buttons' actual rendered // height to control how close together they are; it's a small, exact, directly-chosen value. function ht_buildExplorationControls(viewer, joystick, joystickSize = 88) { const explorer = ht_buildExplorerConditional(viewer, joystick); const btnStyle = "width:100%; background:var(--ht-input-bg,#fff); color:var(--ht-text,#333); border:1px solid var(--ht-border,#ccc); border-radius:4px; padding:4px 0;"; const playBtn = html``; const stopBtn = html``; function setPlaying(playing) { playBtn.disabled = playing; stopBtn.disabled = !playing; } playBtn.addEventListener("click", () => { explorer.play(); setPlaying(true); }); stopBtn.addEventListener("click", () => { explorer.stop(); setPlaying(false); }); joystick.onUserDragStart(() => setPlaying(false)); // explorer.stop() already runs via driveExternal's user-priority check, but the buttons still need to reflect it return html`
${playBtn}${stopBtn}
`; } // Builds a simple tab strip + pane switcher. `panes` is an array of `{label, content}` (content // is any DOM node). Only one pane's content is visible at a time (toggled via `display:none`); // the first pane is active by default. Returns the combined `{element}` — the tab strip stacked // above whichever pane is currently showing. // // IMPORTANT: each pane's ORIGINAL `display` value (e.g. "flex", for panes authored as flex // columns) is captured up front and restored when re-showing it — setting `style.display = ""` // to "show" an element does NOT restore its authored inline value, it just removes the // `display` declaration entirely, silently reverting to the browser default ("block" for a // `
`), which would break a pane's `flex-direction:column` layout (confirmed empirically: an // authored `display:flex; flex-direction:column;` pane rendered with the `flex-direction` intact // but `display` missing after being toggled, collapsing it back to normal block flow). function ht_buildTabbedPanes(panes) { const tabBar = html`
`; const buttons = panes.map((pane) => html``); tabBar.append(...buttons); const originalDisplays = panes.map((pane) => pane.content.style.display || "block"); function setActive(activeIndex) { panes.forEach((pane, i) => { pane.content.style.display = i === activeIndex ? originalDisplays[i] : "none"; buttons[i].style.color = i === activeIndex ? "var(--ht-text, #333)" : "var(--ht-faint, #999)"; buttons[i].style.borderBottomColor = i === activeIndex ? "#4269d0" : "transparent"; }); } buttons.forEach((btn, i) => btn.addEventListener("click", () => setActive(i))); setActive(0); // "General" (the first pane) is visible by default const paneContainer = html`
${panes.map((pane) => pane.content)}
`; return { element: html`
${tabBar}${paneContainer}
` }; } // Keeps `panelEl` vertically aligned with the actual plotted disk inside `viewerEl` — not the // whole viewer div, which also includes the title/subtitle text and the color legend sitting // above the disk. Measures the main plot
`; const edgeCurveSelect = ht_buildSelect(viewer, { label: "Edge curve", optionsList: [ { value: "geodesic", label: "geodesic" }, { value: "radial", label: "radial" } ], value: edgeCurve, toOption: (v) => ({ edgeCurve: v }) }); const zoomSlider = ht_buildSlider(viewer, { label: "Zoom", min: 50, max: 300, step: 5, value: 100, toOption: (v) => ({ domainR: baseDomainR * 100 / v }), format: (v) => `${Math.round(v)}%` }); // keep the Zoom slider synchronized with the viewer's true domainR at all times — see the // doc comment above the function. viewer.onChange(({ domainR }) => { const percent = Math.min(300, Math.max(50, (baseDomainR * 100) / domainR)); zoomSlider.update(percent); }); const labelRadiusSlider = ht_buildSlider(viewer, { label: "Radius for labels shown", min: 0.05, max: 1, step: 0.01, value: 0.28, toOption: (v) => ({ labelRadius: v }), format: (v) => v.toFixed(2) }); const labelRadiusCheckbox = ht_buildCheckbox(viewer, { label: "show radius", checked: false, toOption: (v) => ({ showLabelRadius: v }) }); const fontSizeSlider = ht_buildSlider(viewer, { label: "Label font size", min: 6, max: 20, step: 1, value: 9, toOption: (v) => ({ labelFontSize: v }), format: (v) => `${v}px` }); // "General" pane: everything the panel used to show, unconditionally (minus "Node size", // which now lives in the Mappings pane next to its mode dropdown). const generalPane = html`

${resetBtn}${themeSelect}${rootWaveCheckbox.element}

Pan

Interactive
${joystick.element}
${panDivider}

Animation
${explorationControls}

${edgeCurveSelect} ${zoomSlider.element}
${labelRadiusSlider.element}${labelRadiusCheckbox.element}
${fontSizeSlider.element}

`; // "Mappings": four data-driven mapping controls (node color/size, edge color/width). const mappingsPane = ht_buildMappingsPane(viewer); // "Filter": filter-by-attribute (subtree) + search-for-a-node (single node, by label). const filterPane = ht_buildFilterPane(viewer); const tabs = ht_buildTabbedPanes([ { label: "General", content: generalPane }, { label: "Mappings", content: mappingsPane }, { label: "Filter", content: filterPane } ]); panelRoot = html`

Controls

${tabs.element}
`; ht_applyPanelTheme(panelRoot, theme); // sync initial CSS vars (and color-scheme) with the `theme` option return panelRoot; } display("Control-panel builder — the \"Filter\" pane now has TWO sections: the existing \"Filter by attribute\" (ht_buildFilterByAttributeSection, unchanged behavior, refactored out of the old ht_buildFilterPane and now returns null when there are no categorical fields instead of pre-empting the whole pane) plus a new \"Search for a node\" section (ht_buildNodeSearchSection): a single-line text field that live-searches every node's own label text on every keystroke (added OR removed) via viewer.findLabelsBySubstring, showing a scrollable, capped results list with the matching substring highlighted in each candidate (ht_highlightSubstring) — clicking a result copies it into the text field (doesn't jump there itself); pressing \"Search node\" (or Enter) calls viewer.goToLabel(term, 800) to pan there over a fixed 0.8s if the typed text matches a label exactly, doing nothing at all otherwise. Everything else unchanged: General (reset, theme, pan joystick + animation demo, edge-curve toggle, zoom/label sliders), Mappings (node/edge color+size)."); display(ht_buildControlPanel); 3d:T2864,// CELL: doc-architecture — written docs: math/layout/viewer architecture display(md` ## Architecture and design ### 1. Math layer — SU(1,1) Möbius transforms A set of small pure functions operating on complex numbers (\`{re, im}\`) and 2×2 matrices of the form \`{a, b}\` representing \`z ↦ (az+b)/(b̄z+ā)\` with the constraint \`|a|²−|b|²=1\`. | Function | Purpose | |---|---| | \`ht_apply(M, z)\` | Apply transform \`M\` to point \`z\` | | \`ht_composeAfter(M2, M1)\` | Compose: apply \`M1\` then \`M2\` | | \`ht_translateTo(p)\` | Transform sending \`0 → p\` | | \`ht_translateFrom(f)\` | Transform sending \`f → 0\` (used for click-to-focus) | | \`ht_normalize(M)\` | Re-enforces the SU(1,1) constraint (abs(a)² − abs(b)² = 1) to correct floating-point drift | | \`ht_lerpM(M0, M1, t)\` | Smooth interpolation between two transforms (for animation) | All navigation (drag, scroll, click) works by composing small incremental transforms onto one persistent state variable \`M\`, rather than recomputing any layout. ### 2. Layout layer — \`ht_layout(root, options)\` Takes a [d3.hierarchy](https://d3js.org/d3-hierarchy) root (built by you, see below) and computes a static "world" position \`z0\` for every node, once: 1. \`d3.tree()\` assigns each node a radial angle and depth (a standard radial tree layout). 2. Depth is compressed with \`tanh\` so deeper nodes crowd toward the disk boundary: \`r = tanh(k · depth / maxDepth)\`. 3. The resulting \`{re, im}\` is stored as \`node.z0\`. \`\`\`js function ht_layout(root, { k = 2.2 } = {}) { /* ... / return root.descendants(); } \`\`\` | Option | Default | Description | |---|---|---| | \`k\` | \`2.2\` | Compression constant. Higher = more nodes pushed toward the edge (more "context", less "focus" spread). | Returns a flat array of nodes (\`root.descendants()\`), each now carrying a \`.z0\` property. This is computed once and reused for every frame — it's why the viewer stays fast even for large trees (layout is O(n), independent of how much you pan/zoom afterward). ### 3. Viewer layer — \`ht_viewer4(nodes, options)\` Takes the array returned by \`ht_layout\` and returns a live, interactive DOM element. Each frame: 1. Projects every node through the current transform \`M\` (\`ht_apply(M, n.z0)\`). 2. Pins the root: it's always included and, if pushed past \`rootClampR\`, is clamped back onto the visible disk (same angle, smaller radius) so you never lose your anchor. 3. Renders with \`Plot.line\` (edges, sampled from one of two curve styles — see below) + \`Plot.dot\` (nodes) + \`Plot.text\` (labels, faded by radius — see below). 4. Draws a dashed boundary circle and re-binds interaction calibration. ### 4. Nodes 1. Internal nodes are drawn as circles. Leaves are represented as squares which remain perpendicular to their incoming edge. 2. Nodes shrink up to a point, but then their size freezes* at a small floor — they never shrink further, never fade, and are never removed. Every single node stays visible at all times, no matter how far out it gets pushed. As you pan/zoom and nodes get pulled further toward the boundary, their fixed-size dots simply get closer together and the edges connecting them visibly get shorter — since hyperbolic space compresses infinitely more room into the same area near the edge — rather than anything disappearing. ### 5. Edges — two selectable curve styles (\`edgeCurve\`) Every parent→child edge is resampled fresh every frame from the current projected positions (never from the static \`z0\` layout), as a small polyline tagged with a unique id and drawn as its own \`Plot.line\` series (grouped via the \`z\` channel) rather than a single \`Plot.link\` mark. Which curve shape is used is controlled by the \`edgeCurve\` option — both functions share the exact same signature, \`(z1, z2, {n}) => points[]\`, so they're interchangeable: \`edgeCurve: "geodesic"\` (default) — \`ht_geodesicPoints\` (see the "edge-curves" cell): the mathematically "straight line" of the Poincaré disk's own hyperbolic metric, which appears as a circular arc orthogonal to the boundary circle (a diameter when it passes through the disk's center). - Möbius-invariant. Because \`ht_apply\` is a disk automorphism and a geodesic is defined purely in terms of the hyperbolic metric, an edge drawn this way looks like a clean hyperbolic line in every view — panned, zoomed, or freshly reset. - Avoids overlap by construction. The metrically "cheapest" path between two points cuts closer to the disk's center, so geodesics naturally bow back toward the origin instead of slicing a straight Euclidean chord across unrelated branches. - Tradeoff: for a node with many children, every one of its outgoing edges bows toward the origin — so a wide fan-out can read as a busy tangle of big arcs sweeping through the middle of the disk, rather than a tidy fan. \`edgeCurve: "radial"\` — \`ht_radialBumpPoints\` (see the "edge-curves-radial" cell): matches the classic [d3 radial tree](https://observablehq.com/@d3/radial-tree/2) look, i.e. what you'd get from \`d3.linkRadial()\`'s default curve. It's a cubic Bezier computed in (angle, radius) polar space — control points at \`(angle0, midRadius)\` and \`(angle1, midRadius)\` (the same "hold angle, move to the mean radius" shape as d3's \`curveBumpY\`) — with each of the resulting 4 control points individually converted to Cartesian only at the very end and used directly as literal SVG Bezier control points (the same trick d3-shape's \`curveBumpRadial\` uses internally). - Stays confined to the wedge. Because the curve is built in polar coordinates around the disk's own origin rather than following the hyperbolic metric between the two specific endpoints, each edge never sweeps outside the angular wedge between its two endpoints — so a node with many children fans out tidily instead of ballooning through the center. This is the behavior the notebook now defaults to for the flare demo. - Not Möbius-invariant — it's recomputed from the current projected endpoints every frame (so it still updates correctly as you pan/zoom), but it isn't defined by the hyperbolic metric the way a geodesic is, so it doesn't have quite the same "this is the one true hyperbolic path" mathematical pedigree. In exchange it gives the familiar, calmer tidy-radial-dendrogram look, which is often what people expect from a hierarchy visualization. Both options considered (and rejected) two cheaper alternatives along the way — a plain quadratic Bezier pulling the chord's midpoint toward the center, and a naive straight Euclidean chord — before landing on these two as the ones worth exposing as a live, switchable option (see the "Edge style" dropdown in the control panel). ### 6. Labels — shown by radius, with a smooth fade ring (not a hard cutoff), positioned per-node Labels are only useful near the current focus (elsewhere they'd overplot each other into illegibility), so only nodes within some radius of the center are labeled at all. An early version of this used a single hard cutoff radius, \`labelRadius\`: a label was fully shown right up until the instant its node's distance from center crossed that threshold — at which point it vanished outright. In practice (especially while panning) this reads as an abrupt "pop" as labels blink in and out right at the boundary, rather than a smooth transition. The fix: a second, slightly larger radius, \`labelRadius + labelFadeWidth\` (default \`+0.1\`), forms a fade ring around the full-opacity zone: - Inside \`labelRadius\`: label opacity \`1\` (fully shown). - Between \`labelRadius\` and \`labelRadius + labelFadeWidth\`: opacity eases smoothly from \`1\` down to \`0\` via \`ht_smoothstep\` (the same easing helper used for the node-size shrink curve). - Beyond the fade ring: the label is dropped from the rendered set entirely (not just invisible — this keeps the number of text elements Plot has to lay out bounded). Enabling \`showLabelRadius\` draws both rings as dashed circles, each captioned with curved text that follows the circle's own curvature — "full label area" / "fade label area", both along the top of their respective ring — via \`ht_makeCircleLabel\` (see the "viewer-dom-helpers" cell). The captions deliberately use a serif/italic font, distinct from the sans-serif font Plot uses for actual node labels, so they always read as chart annotations rather than being mistaken for node labels themselves. (An SVG \`\` needs an actual \`\` element to bind to via \`href="#id"\`, so each caption is backed by an invisible guide path built at the ring's own radius nudged slightly outward — not via a \`dy\` on \`\`, which isn't actually a supported attribute there, confirmed empirically to have no effect.) Each label's vertical position respects THAT node's own rendered radius, not a shared constant. Node radii vary continuously — the shrinkFloor/fade curves shrink nodes smoothly as they approach the boundary — so a single shared clearance would either overlap larger nodes or over-space smaller ones. This turns out to hinge on a subtlety of \`Plot.text\`: its \`dy\` option only accepts a plain constant (a per-datum function is silently ignored, confirmed empirically), but \`y\` is a normal per-datum channel, exactly like \`vr\`/\`opacity\`/\`rotate\` already are on the dot mark. So instead of a post-scale pixel \`dy\`, \`ht_computeLabelData\` bakes each label's desired pixel clearance directly into its data-space \`y\` position — converting the pixel amount via \`pxPerUnitY\`, a conversion factor derived analytically from \`height\`/\`margin\`/\`domainR\` (exact, not approximate, because Plot's default continuous position scale is a plain affine map — verified empirically to match Plot's own scale object to floating-point precision). The root is the one exception: it still gets its own dedicated single-row \`Plot.text\` mark with a literal constant \`dy\` — but that's not an approximation needing generalization, since a mark with exactly one row has no "shared constant vs. varying values" tension to begin with. `)3e:Tfd8,### Data-driven mappings (the "Mappings" panel tab) Beyond the fixed options above, `ht_viewer4` supports four independent, optional data-driven mappings, each defaulting to the exact original fixed behavior — these are what the control panel's Mappings tab exposes live (see `ht_buildMappingsPane`): | Option | Default | Description | |---|---|---| | `nodeColorMode` | `"branch"` | `"branch"` (color by top-level ancestor, unchanged) \| `"single"` (one flat color, via `nodeColorSingle`) \| `"field"` (color by a chosen field of the node's own `.data`, e.g. `gender`) | | `nodeColorField` | `null` | Field name to use when `nodeColorMode: "field"`. Auto-detected as continuous (numeric → sequential blues scale) or discrete (anything else → categorical scale) — both go through Plot's real color scale, so both still get an automatic legend. | | `nodeColorSingle` | `"#4269d0"` | Flat color used when `nodeColorMode: "single"` | | `nodeSizeMode` | `"uniform"` | `"uniform"` (unchanged) \| `"field"` (size by a chosen numeric field of the node's own `.data`, e.g. `employees`) | | `nodeSizeField` | `null` | Field name to use when `nodeSizeMode: "field"` — scaled area-true (sqrt) into a 0.5×–2.4× multiplier on top of the existing `nodeSizeScale` slider and shrink-by-distance curve | | `edgesData` | `null` | An optional, separate dataset of `{source, target, ...fields}` rows (ids matching the tree's own node ids — the same ids passed to `d3.stratify().id(...)`, as strings), used only by the two edge mappings below. Individual edges aren't part of the main hierarchical node dataset (a node only knows its own data, not its incoming edge), so edge-level attributes need their own table. | | `edgeColorMode` | `"single"` | `"single"` (one flat color, via `edgeColorSingle`, unchanged) \| `"field"` (color by a chosen field from `edgesData`) | | `edgeColorField` | `null` | Field name (from `edgesData`) to use when `edgeColorMode: "field"` | | `edgeColorSingle` | `null` | Flat edge color; `null` means "use the theme's default gray" | | `edgeWidthMode` | `"uniform"` | `"uniform"` (unchanged, using the plain `edgeWidth` px value) \| `"field"` (width by a chosen numeric field from `edgesData`) | | `edgeWidthField` | `null` | Field name (from `edgesData`) to use when `edgeWidthMode: "field"` — scaled area-true (sqrt) into a range centered on `edgeWidth` | Why edge color/width don't go through Plot's color scale the way node color does: Plot only gives you one shared `color` scale by default, and node color-by-field and edge color-by-field are two unrelated mappings with unrelated domains. Rather than fight Plot's scale-sharing, edge color/width are computed as literal values (a real CSS color string, a real pixel width) via plain d3 scales — confirmed empirically that once every value in a mark's color channel already looks like a valid CSS color string, Plot renders it as-is and never touches any scale or legend, so this can never collide with the node mark's own (possibly very different) color scale running at the same time. The tradeoff is that edge color-by-field doesn't get an automatic legend the way node color-by-field does. ```js const viewer = ht_viewer4(nodes, { label: (d) => d.data.name, edgesData: myEdgeRows, // [{source: "1", target: "2", channel: "remote", strength: 5}, ...] nodeColorMode: "field", nodeColorField: "gender", nodeSizeMode: "field", nodeSizeField: "employees", edgeColorMode: "field", edgeColorField: "channel", edgeWidthMode: "field", edgeWidthField: "strength" }); ``` `viewer.nodeFields` / `viewer.edgeFields` (arrays of `{name, kind}`, `kind` being `"numeric"` or `"categorical"`) and `viewer.hasEdgesData` are also exposed on the returned viewer object — this is how the Mappings panel populates its dropdowns with only the fields that actually exist in your data, gracefully showing an italic note (e.g. "no numeric node fields available") wherever a mapping has nothing to offer instead of a dead-end control.3f:T43a8,// CELL: doc-api-reference — full parameter/return-value reference for ht_viewer4() display(md` ## API Reference ### \`ht_viewer4(nodes, options)\` Parameters | Option | Default | Description | |---|---|---| | \`width\`, \`height\` | \`700\` | Pixel size of the plot | | \`renderBudget\` | \`600\` | Max nodes drawn per frame. Bounds render cost regardless of tree size — this is the key scalability knob. Lower it (e.g. \`200\`) for smoother interaction on huge trees or slow devices. | | \`labelRadius\` | \`0.28\` | Data-space radius (0..1) within which node labels are shown at full opacity — the primary "how many labels" control. | | \`labelFadeWidth\` | \`0.1\` | Additional data-space radius beyond \`labelRadius\` over which labels smoothly fade from opacity 1 to 0 (via \`ht_smoothstep\`), instead of abruptly vanishing right at \`labelRadius\` (which used to read as a "pop" while panning). A label is only dropped from rendering entirely once past \`labelRadius + labelFadeWidth\`. | | \`showLabelRadius\` | \`false\` | Draw two dashed circles marking the full-opacity zone (\`labelRadius\`) and the outer fade boundary (\`labelRadius + labelFadeWidth\`), each captioned with curved text following the circle's own curvature — "full label area" / "fade label area", both along the top of their own ring — in a serif/italic font distinct from the node labels' font (see \`ht_makeCircleLabel\`, "Architecture → 6. Labels" above). | | \`labelBudget\` | \`150\` | Internal safety cap on label count (avoids pathological over-plotting); \`labelRadius\` is the knob you actually want to tune | | \`labelFontSize\` | \`9\` | Base font size (px) for non-root labels before the zoom multiplier (see \`sizeZoomExponent\`); the root's label is always \`labelFontSize + 2\` | | \`labelGap\` | \`6\` | Base px gap (before \`zoomFactor\`) between a node's own edge and its label. Applied per-node exactly — each label's vertical offset is computed from that specific node's own rendered radius (\`d.vr\`), not a shared worst-case constant, so labels stay correctly clear of their node however that node's radius happens to vary (shrink curve, a future per-node size option, etc.) — see "Architecture → 6. Labels" above. | | \`title\`, \`subtitleBase\` | — | Passed through to \`Plot.plot\`'s title/subtitle. These are rendered as pure static strings — never mutated with live per-frame data — so the figure's layout never reflows/jerks during pan, zoom, or animation. | | \`domainR\` | \`1.05\` | Half-width of the plotted domain (disk radius is 1, so this just adds a small margin). Shrinking it magnifies the disk within the fixed pixel canvas — this is the "zoom" knob, driven live by both the scroll wheel and the control panel's Zoom slider. \`reset()\` restores this to its original value. | | \`minDomainR\` / \`maxDomainR\` | \`0.15\` / \`3\` | Clamp range for scroll-wheel zoom (smaller \`domainR\` = more magnified) | | \`sizeZoomExponent\` | \`1\` | How strongly zooming also scales rendered sizes. Every render computes \`zoomFactor = (initialDomainR / domainR) ^ sizeZoomExponent\` and multiplies it into node radii, edge stroke width, node stroke width, and label font size — so zooming in doesn't just spread nodes farther apart, it visibly enlarges them too (matching how a real camera zoom looks). \`1\` = fully proportional (default), values between \`0\` and \`1\` soften the effect, \`0\` disables it entirely (sizes stay fixed regardless of zoom, the old behavior). | | \`edgeWidth\` | \`1.5\` | Base edge stroke width in px, before the \`zoomFactor\` multiplier described above | | \`label\` | \`d => d.data.name ?? d.data.id ?? String(d.data)\` | Function mapping a d3 node → display string. This is the one option you'll always want to customize for your own data (see below). This is also the exact text the "Search for a node" panel section matches against (see \`goToLabel\`/\`findLabelsBySubstring\` below). | | \`animDuration\` | \`500\` | Milliseconds for the focus / reset animation. The category-filter transition (fade + pan — see \`applyFilter\` below) and the search pane's centering pan (see \`goToLabel\` below) both use their own separate, fixed 800ms duration instead, independent of this option. | | \`rootClampR\` | \`0.95\` | Max radius the root is allowed to reach on screen — it's clamped here instead of disappearing | | \`edgeCurve\` | \`"geodesic"\` | The shape of parent→child edges. \`"geodesic"\` — true hyperbolic geodesic arcs (Möbius-invariant, bows toward the disk center; can look like a busy fan of big arcs for nodes with many children). \`"radial"\` — a d3.linkRadial()-style polar Bezier matching the classic [d3 radial tree](https://observablehq.com/@d3/radial-tree/2) look (stays confined to the wedge between endpoints, avoiding big cross-disk arcs even for wide fan-outs; not Möbius-invariant). See "Architecture → 5. Edges" above. | | \`edgeSamples\` | \`20\` | Points sampled per edge to draw its curve (either style) — higher looks smoother but costs more per frame | | \`nodeSizeScale\` | \`1\` | Uniform multiplier on every non-root node's rendered radius — the "node size" control, independent of and multiplicative with the zoom-driven \`zoomFactor\` above. Bigger value = bigger nodes, always. | | \`edgeFloorSize\` | \`1.4\` | Advanced: shape of the node-shrink curve — the minimum radius (before \`nodeSizeScale\`/\`zoomFactor\`) far-away nodes shrink down to and hold at. Usually leave this alone and use \`nodeSizeScale\` instead. (Unrelated to \`edgeCurve\` — this is about node dot size near the boundary, not edge line shape.) | | \`clickRadius\` | \`20\` | Pixels a double-click/tap can land from a node's center and still count as selecting it — hit-testing is done centrally in screen-pixel space (see below), not by requiring a pixel-perfect hit on the (possibly tiny) rendered dot | All options above are live-tunable, not just construction-time — see \`setOptions\` below. Returns \`{ element, reset(), goToRoot(), goToNode(predicate), setOptions(partial), panByPixels(dxPx, dyPx), transform, domainR, applyFilter(attr, category), clearFilter(), getFieldValues(fieldName), hasActiveFilter, goToLabel(targetLabel, duration), findLabelsBySubstring(query) }\` | Property | Description | |---|---| | \`element\` | The DOM node to \`display()\` — a \`
\` wrapping the live Plot figure | | \`reset()\` | Animate back to the identity transform and the original \`domainR\` — the exact, canonical original view, discarding any accumulated pan/zoom/rotation/scroll-zoom. Also instantly discards any active category filter (see \`applyFilter\` below). | | \`goToRoot()\` | Animate so the root is recentered, while preserving any rotation ("holonomy") your panning has accumulated and the current zoom level — differs visibly from \`reset()\` only after non-straight pan paths or any scroll-zooming | | \`goToNode(predicate)\` | Animate so the first node whose \`.data\` matches \`predicate(data, node)\` becomes the focus — a scriptable alternative to double-clicking, handy for demos/comparisons | | \`setOptions(partial)\` | Merge a partial options object into the running viewer and immediately re-render — e.g. \`viewer.setOptions({ labelRadius: 0.5 })\` or \`viewer.setOptions({ edgeCurve: "radial" })\`. This is what powers the live control-panel sliders/dropdown (see below). | | \`panByPixels(dxPx, dyPx)\` | Pan by a pixel offset, using the same conversion the mouse-drag handler uses internally — lets any alternate input device (e.g. a joystick knob) drive panning with identical direction/feel to a real drag. | | \`transform\` | (getter) the current \`{a, b}\` SU(1,1) matrix — mostly useful for debugging | | \`domainR\` | (getter) the current Euclidean zoom level — mostly useful for debugging | | \`applyFilter(attr, category)\` | Category filter (backs the control panel's "Filter" pane — see below). Searches the tree top-down for the first node whose \`.data[attr]\` equals \`category\` (compared as strings), then takes that node plus its entire subtree as the filter's resulting tree — a subtree is what "additional nodes chosen so they form a tree" means, since it's always connected, unlike an arbitrary set of matching nodes. Visualizes this as two concurrent animations, both running over a fixed 800ms (0.8s): every node/edge NOT in that subtree eases down to a low floor opacity (while anything newly included fades UP from it, and anything whose membership didn't change stays constant — no flash) at the same time as the view pans so the matched node animates to the exact center of the disk — the fade doesn't need to finish before the pan starts. Returns the matched d3 node, or \`null\` if nothing matched. | | \`clearFilter()\` | Fades everything back to full opacity (over the same fixed 800ms) and discards the active filter (does not undo any panning — pair with \`reset()\` for a full return to the original view) | | \`getFieldValues(fieldName)\` | Distinct, sorted, non-empty values of a given node-data field — used to populate the Filter pane's "category" dropdown from the actual data | | \`hasActiveFilter\` | (getter) whether a category filter is currently active | | \`goToLabel(targetLabel, duration = animDuration)\` | Node search — jump to an exact match (backs the Filter pane's "Search for a node" section — see below). Finds the first node whose \`label(n)\` equals \`targetLabel\` exactly and pans it to the exact center of the disk over \`duration\` ms — the search pane always passes \`800\` (0.8s). Returns the matched node, or \`null\` — and does nothing to the view at all — if nothing matches exactly. | | \`findLabelsBySubstring(query)\` | Node search — live substring lookup. Returns every distinct node label containing \`query\` as a case-insensitive substring (sorted alphabetically), or an empty array for an empty/whitespace-only \`query\`. Used to populate the search pane's results list on every keystroke; doesn't itself move the view. | Interactions built in — drag only pans, scroll only zooms, with no overlap between the two: - Drag pans the hyperbolic view (composes a Möbius translation onto \`M\`) — this is the only thing that moves nodes' underlying positions. - Scroll wheel does a pure Euclidean rescale of \`domainR\` around the fixed center — the exact same mechanism as the control panel's "Zoom" slider. It deliberately does not translate the hyperbolic view toward the cursor: an earlier version did this (a Möbius "zoom toward cursor"), but since that's a translation, it also shifted every node's position the same way a drag would — which could feel like scrolling was panning the view. Now scrolling only ever changes magnification, never position. Zooming also scales every rendered pixel size (node radius, edge width, node border width, label font size) via \`sizeZoomExponent\`, so zooming in genuinely makes everything bigger, not just farther apart. - Both only engage inside the disk boundary, not the full rectangular plot area (scrolling outside the disk passes through to the page as a normal scroll). Edges themselves are drawn using whichever curve style \`edgeCurve\` selects (see "Architecture → 5. Edges" above) — independent of both interactions above. Labels fade smoothly in/out across a "fade ring" as nodes move past \`labelRadius\`, and are positioned above each node using that specific node's own radius (see "Architecture → 6. Labels" above) — independent of all of the above. Focusing a node is done with a double-click, not a single click. Two earlier attempts at telling a single click apart from a drag ourselves (first by data-space delta on each \`pointermove\`, then by total screen-pixel displacement on \`pointerup\`) both still required clicking twice in practice — pointer-capture/timing quirks around the very first gesture on a freshly rendered element are genuinely finicky to fully iron out by hand. \`dblclick\` sidesteps the whole problem: it's a native, battle-tested browser event that simply never fires if the pointer moved appreciably between the two presses, so it can never be confused with an in-progress pan and there's no custom threshold to get wrong. On \`dblclick\`, the nearest visible node within \`clickRadius\` pixels of the pointer is found and animated to center — regardless of which exact DOM element (dot, tip box, label) happened to be under the pointer — so double-clicking near a node, including right on top of its tooltip, reliably focuses it. The whole viewer is also \`user-select: none\`, so click-dragging over a visible tooltip pans the view instead of highlighting its text. ### \`ht_buildControlPanel(viewer, options)\` A ready-made right-hand side panel (see it live next to the flare demo above) that exercises the live-tunable API above, so different interaction styles can be tried and compared directly. It's organized into three tabs: General - Reset view button, wired to \`viewer.reset()\`. - A light/dark theme dropdown and a "highlight root node" checkbox (toggles the animated "radar ping" locked onto the root — \`showRootWave\`). - A drag-to-pan joystick (\`ht_buildJoystick\`): a small track-and-knob widget — hold the knob away from center and it continuously pans (proportional to how far it's pushed) via \`viewer.panByPixels()\`, springing back to center on release — plus an "Animation demo" auto-play journey next to it. - Edge curve — a dropdown mapping to \`edgeCurve\` ("geodesic" vs. "radial"), so the two edge-drawing approaches can be compared live on the same tree. - Zoom — maps to \`domainR\` (inverted: higher % = more zoomed in) — the same knob scrolling uses, and (via \`sizeZoomExponent\`) also visibly enlarges nodes/edges/labels as you zoom in. - Radius for labels shown — maps to \`labelRadius\`, plus a show radius checkbox (\`showLabelRadius\`). - Label font size — maps to \`labelFontSize\`. Mappings — four independent data-driven mappings for node/edge color and size (see the "Data-driven mappings" doc section above and \`ht_buildMappingsPane\`). Filter (\`ht_buildFilterPane\`) — two independent sections: - Filter by attribute (\`ht_buildFilterByAttributeSection\`) — search-and-highlight a subtree by a categorical node attribute: two dropdowns sit side by side — the first picks WHICH categorical field of the node data to filter by, the second (repopulated from \`viewer.getFieldValues(...)\` every time the first changes) picks WHICH distinct value of that field to match. Below that, a smaller Apply filter / Clear filter button pair (also side by side, in their own row): Apply filter calls \`viewer.applyFilter(attr, category)\` (see the Returns table above for exactly what that does); Clear filter calls \`viewer.clearFilter()\`. Omitted entirely (no divider either) if the data has no categorical fields at all, replaced by a placeholder note. - Search for a node (\`ht_buildNodeSearchSection\`) — a single-line text field that live-searches every node's own label text (not a data field) as you type: on every keystroke (letters added or removed), a scrollable results list right below shows every distinct label containing the typed text as a substring, each rendered with the matching portion highlighted, via \`viewer.findLabelsBySubstring(...)\`. Clicking a result copies it into the text field (it does not jump there by itself — you still choose when to search) and re-filters the list against the now-complete text. Pressing Search node (or hitting Enter in the field) calls \`viewer.goToLabel(term, 800)\`: if the current text matches a label exactly, the view pans so that node lands dead-center over a fixed 0.8s; if nothing matches exactly, nothing happens to the view at all, and a small status line reports that no match was found. Each control calls \`viewer.setOptions(...)\` (or \`panByPixels\`/\`applyFilter\`/\`clearFilter\`/ \`goToLabel\`) on input, so changes apply immediately without recreating the viewer. \`ht_buildControlPanel(viewer, { baseDomainR, panelWidth, edgeCurve })\` returns a single \`
\` (pass the same \`edgeCurve\` value the viewer was constructed with so the dropdown's initial selection matches reality). Pair it with \`ht_alignPanelToPlot(viewerEl, panelEl)\`, which keeps the panel's top edge vertically aligned with the plotted disk itself — not the whole viewer div, which also includes the title, subtitle, and color legend sitting above the disk — by measuring the actual plot \`
\${viewer.element}\${panel}
\`); \`\`\` `);40:T1022,display(md` ## Formatting Your Own Data The viewer doesn't consume raw data directly — it consumes a [d3.hierarchy](https://d3js.org/d3-hierarchy) root (a tree of linked node objects with \`.children\`, \`.parent\`, \`.depth\`, etc.). You build that root from your data first, then pass it to \`ht_layout\`. There are two common shapes your source data can be in: ### Shape A — Already nested (JSON tree with \`children\` arrays) If your data already looks like a tree: \`\`\`json { "name": "CEO", "children": [ { "name": "VP Engineering", "children": [ { "name": "Engineer A" }, { "name": "Engineer B" } ]}, { "name": "VP Sales", "children": [ { "name": "Sales Rep A" } ]} ] } \`\`\` use \`d3.hierarchy\` directly — no conversion needed: \`\`\`js const root = d3.hierarchy(myNestedData); // .children is the default accessor const nodes = ht_layout(root, { k: 2.2 }); const viewer = ht_viewer4(nodes, { label: (d) => d.data.name, // <- point this at whatever field holds your label title: "My Org Chart" }); display(viewer.element); \`\`\` ### Shape B — Flat table (rows with an id + a parent reference) This is the more common real-world case — e.g. a CSV export, a database table, or file paths. Each row needs a unique id and a reference to its parent's id (or \`null\`/ missing for the root). Two typical flavors: B1. Explicit parent-id column | id | parentId | name | |---|---|---| | 1 | | CEO | | 2 | 1 | VP Engineering | | 3 | 2 | Engineer A | | 4 | 2 | Engineer B | | 5 | 1 | VP Sales | \`\`\`js const root = d3.stratify() .id((d) => d.id) .parentId((d) => d.parentId || null) (myFlatRows); const nodes = ht_layout(root, { k: 2.2 }); const viewer = ht_viewer4(nodes, { label: (d) => d.data.name }); \`\`\` B2. Dotted path names (no separate id/parentId column) — this is what the built-in \`flare\` example uses: \`"flare.util.Strings"\` implies its parent is \`"flare.util"\`. \`\`\`js const root = d3.stratify() .id((d) => d.name) .parentId((d) => d.name.includes(".") ? d.name.slice(0, d.name.lastIndexOf(".")) : null) (myFlatRows); // rows need a unique dotted "name" field const nodes = ht_layout(root, { k: 2.2 }); const viewer = ht_viewer4(nodes, { label: (d) => d.data.name }); \`\`\` The same pattern works for file paths (split on \`"/"\` instead of \`"."\`) or any other delimiter-based hierarchy. ### Requirements & gotchas - Every id must be unique. \`d3.stratify\` throws if two rows share an id. - Exactly one root. Every row's parent chain must terminate at a single row with a \`null\`/missing \`parentId\` (or an implicit root, e.g. a name with no dot). If you have multiple disconnected trees, wrap them under a synthetic root row first. - No cycles. A row can't (directly or transitively) be its own ancestor. - The \`label\` option must match your fields. The default tries \`d.data.name\` then \`d.data.id\`; if your field is called something else (e.g. \`d.data.title\`), pass your own function — this also controls the color grouping (by top-level ancestor) and the tooltip text. ### Loading data from a file In Observable, load your file first in its own cell, then build the hierarchy in a second cell: \`\`\`js const rows = await FileAttachment("org-chart.csv").csv({typed: true}); \`\`\` \`\`\`js const root = d3.stratify().id(d => d.id).parentId(d => d.parentId || null)(rows); const nodes = ht_layout(root, { k: 2.2 }); const viewer = ht_viewer4(nodes, { label: d => d.data.name, title: "Org Chart" }); display(viewer.element); \`\`\` ### Tuning for size | Tree size | Suggested \`renderBudget\` | |---|---| | < 500 nodes | \`600\` (default — shows everything) | | 1,000 – 10,000 | \`400\`–\`600\` | | 10,000+ | \`200\`–\`400\` (keeps every frame under ~2ms regardless of total size) | The static layout step (\`ht_layout\`) itself is O(n) and fast even for tens of thousands of nodes (≈4ms for 8,000 nodes in testing) — the budget only affects rendering, not layout, so it's safe to lower without losing any underlying data. `);41:T4a6,1. Concepts — what the Poincaré disk model is and why Möbius transforms give you genuinely infinite pan/zoom 2. Architecture — the three layers (math primitives → static layout → interactive viewer) and how they fit together, including the pointer-capture bug we found and fixed 3. API Reference — full parameter tables for `ht_layout` and `ht_viewer4`, plus the returned methods (`reset`, `goToRoot`, `transform`) 4. Formatting Your Own Data (the part you asked for) — covers both data shapes you'll typically encounter: - Shape A: already-nested JSON (`{name, children: [...]}`) → use `d3.hierarchy` directly - Shape B: flat tables (CSV/database rows) → use `d3.stratify`, with two sub-recipes (explicit `id`/`parentId` columns, or dotted path names like the `flare` example) - Requirements (unique ids, single root, no cycles), how to point `label` at your own field names, loading from `FileAttachment`, and a sizing guide for tuning `renderBudget` 5. Worked Example — a complete, runnable 10-row org chart proving the documented recipe actually works, live above 6. Quick Reference Card — a copy-pasteable minimal template42:T460,// Shape B1 again, extended with two more fields per row: gender and employees (headcount // managed, including the person themself) — everything else about the recipe is unchanged. const myOrgRows2 = [ { id: 1, parentId: null, name: "CEO", gender: "female", employees: 10 }, { id: 2, parentId: 1, name: "VP Engineering", gender: "male", employees: 4 }, { id: 3, parentId: 2, name: "Engineer A", gender: "female", employees: 1 }, { id: 4, parentId: 2, name: "Engineer B", gender: "male", employees: 1 }, { id: 5, parentId: 2, name: "Engineer C", gender: "female", employees: 1 }, { id: 6, parentId: 1, name: "VP Sales", gender: "female", employees: 3 }, { id: 7, parentId: 6, name: "Sales Rep A", gender: "male", employees: 1 }, { id: 8, parentId: 6, name: "Sales Rep B", gender: "female", employees: 1 }, { id: 9, parentId: 1, name: "VP Marketing", gender: "male", employees: 2 }, { id: 10, parentId: 9, name: "Marketer A", gender: "female", employees: 1 } ]; display(Inputs.table(myOrgRows2));43:T4ea,// Edges aren't part of the main hierarchical node dataset (a node only knows its OWN data, not // anything about its incoming edge) — so edge-level attributes ride along in a SEPARATE, optional // table instead: one row per parent->child pair, keyed by `source`/`target` matching the tree's // own node ids (the same ids d3.stratify assigned above — confirmed to be strings, e.g. "2", not // the original numeric `id` field). Here each reporting-line edge additionally carries a // `channel` (how that pair primarily works together) and a `strength` (a 1–10 collaboration score). const myOrgEdges2 = [ { source: "1", target: "2", channel: "in-person", strength: 8 }, { source: "1", target: "6", channel: "remote", strength: 5 }, { source: "1", target: "9", channel: "in-person", strength: 6 }, { source: "2", target: "3", channel: "in-person", strength: 9 }, { source: "2", target: "4", channel: "remote", strength: 4 }, { source: "2", target: "5", channel: "in-person", strength: 7 }, { source: "6", target: "7", channel: "remote", strength: 3 }, { source: "6", target: "8", channel: "in-person", strength: 8 }, { source: "9", target: "10", channel: "remote", strength: 5 } ]; display(Inputs.table(myOrgEdges2));44:[] 2d:{"id":"25a072e6b0864c7f","slug":"hyperbolic-tree-viewer-v2","title":"Hyperbolic Tree Viewer - v2","thumbnail":"ac7cda5c0ca58bcf1b1dd7ded80823e225c8b5c7b0f9128efac886cd885cbc4c","access_level":"unlisted","create_time":"$D2026-09-04T14:07:22.690Z","update_time":"$D2026-09-09T23:20:16.452Z","view_time":null,"first_public_time":"$D2026-09-04T15:26:38.185Z","has_unpublished_edits":null,"fork":{"id":"214bf2e31d6c906d","slug":"hyperbolic-tree-viewer","title":"Hyperbolic Tree Viewer","owner":{"id":"11bfeb572ddbe905","login":"ambassadors","name":"Observable Ambassadors"}},"stars":2,"starred":false,"owner":{"type":"team","id":"11bfeb572ddbe905","login":"ambassadors","name":"Observable Ambassadors","avatar_url":"https://avatars-next.observableusercontent.com/93bf798c058a2bf8d3bb90c0754f774b6278b8b16748784f520b07a8800ef772","tier":"pro_2024"},"version":1192,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"9ba5e0b68d3e7972","login":"ee2dev","name":"","avatar_url":"https://avatars-next.observableusercontent.com/c41b514d64cff7415ffc87106c620e16cefe80b6d853fb3a05e19a000c3612c0","tier":null}],"members":[{"type":"team","id":"11bfeb572ddbe905","login":"ambassadors","name":"Observable Ambassadors","avatar_url":"https://avatars-next.observableusercontent.com/93bf798c058a2bf8d3bb90c0754f774b6278b8b16748784f520b07a8800ef772","tier":"pro_2024","role":"editor"}],"comments":[],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"title":"Hyperbolic Tree Viewer - v2","cells":[{"id":118,"value":"$2f","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Documentation: overview and concepts","output":"$undefined","database":"$undefined"},{"id":108,"value":"$30","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Mount viewer with pinned root and add go-to-root button","output":"$undefined","database":"$undefined"},{"id":139,"value":"// CELL: section-implementation — markdown section header\ndisplay(md`\n## Implementation`)","pinned":false,"hidden":false,"mode":"ts","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":64,"value":"$31","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Self-contained rewrite of math and layout helpers with fresh names","output":"$undefined","database":"$undefined"},{"id":137,"value":"// CELL: flare-data — builds the flare class-hierarchy d3 tree + static hyperbolic layout (ht_flareNodes)\nconst ht_flareRoot = d3.stratify()\n .id((d) => d.name)\n .parentId((d) => d.name.includes(\".\") ? d.name.slice(0, d.name.lastIndexOf(\".\")) : null)\n (flare);\nconst ht_flareNodes = ht_layout(ht_flareRoot, { k: 2.2 });\ndisplay(\"Functions for the flare dataset\");\ndisplay(ht_flareNodes);","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":140,"value":"$32","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":159,"value":"$33","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":94,"value":"// CELL: lerp-easing — ht_lerpM (transform interpolation) + easing function, used for animations\n// smooth interpolation between two SU(1,1) transforms (nlerp-style: lerp components + renormalize,\n// with hemisphere alignment since M and -M represent the same transform — avoids \"long way round\" spins)\nfunction ht_lerpM(M0, M1, t) {\n const dot = M0.a.reM1.a.re + M0.a.imM1.a.im + M0.b.reM1.b.re + M0.b.imM1.b.im;\n const s = dot < 0 ? -1 : 1;\n const a = { re: M0.a.re(1-t) + sM1.a.ret, im: M0.a.im(1-t) + sM1.a.imt };\n const b = { re: M0.b.re(1-t) + sM1.b.ret, im: M0.b.im(1-t) + sM1.b.imt };\n return ht_normalize({ a, b });\n}\nfunction ht_easeInOutCubic(t) { return t < 0.5 ? 4ttt : 1 - Math.pow(-2t+2, 3)/2; }\n\n display(`Function for smooth transition using eased interpolation when node is selected`);\n display(ht_lerpM);","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Define and test smooth SU(1,1) interpolation for animated focus transitions","output":"$undefined","database":"$undefined"},{"id":171,"value":"$34","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":172,"value":"$35","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":173,"value":"$36","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":174,"value":"$37","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":190,"value":"$38","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":196,"value":"$39","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":106,"value":"$3a","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Define viewer with always-visible pinned root","output":"$undefined","database":"$undefined"},{"id":181,"value":"$3b","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":152,"value":"$3c","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":119,"value":"$3d","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Documentation: architecture","output":"$undefined","database":"$undefined"},{"id":195,"value":"$3e","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":122,"value":"\nNow let's document the full API reference for `ht_viewer4`:","pinned":false,"hidden":false,"mode":"md","author":"agent","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":123,"value":"$3f","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Documentation: API reference for viewer","output":"$undefined","database":"$undefined"},{"id":125,"value":"$40","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Documentation: how to format your own data section","output":"$undefined","database":"$undefined"},{"id":126,"value":"Let's also include a live, runnable example using a small custom dataset (Shape B1 — explicit parent-id column) to prove the documented recipe actually works end-to-end:","pinned":false,"hidden":false,"mode":"md","author":"agent","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":127,"value":"display(md`\n## An Example with your Own Flat Table\n\nHere's the full recipe from above, executed on a tiny made-up org chart to prove it\nworks end-to-end.\n`);\n\n// Shape B1: flat rows with id + parentId\nconst myOrgRows = [\n { id: 1, parentId: null, name: \"CEO\" },\n { id: 2, parentId: 1, name: \"VP Engineering\" },\n { id: 3, parentId: 2, name: \"Engineer A\" },\n { id: 4, parentId: 2, name: \"Engineer B\" },\n { id: 5, parentId: 2, name: \"Engineer C\" },\n { id: 6, parentId: 1, name: \"VP Sales\" },\n { id: 7, parentId: 6, name: \"Sales Rep A\" },\n { id: 8, parentId: 6, name: \"Sales Rep B\" },\n { id: 9, parentId: 1, name: \"VP Marketing\" },\n { id: 10, parentId: 9, name: \"Marketer A\" }\n];\ndisplay(Inputs.table(myOrgRows));","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Worked example intro and sample flat data","output":"$undefined","database":"$undefined"},{"id":128,"value":"// exactly the recipe from the docs (Shape B1):\nconst myOrgRoot = d3.stratify()\n .id((d) => d.id)\n .parentId((d) => d.parentId || null)\n (myOrgRows);\n\nconst myOrgNodes = ht_layout(myOrgRoot, { k: 2.2 });\ndisplay(`built hierarchy: ${myOrgNodes.length} nodes`);","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Build hierarchy from custom flat data using documented recipe","output":"$undefined","database":"$undefined"},{"id":129,"value":"const myOrgViewer = ht_viewer4(myOrgNodes, {\n label: (d) => d.data.name,\n title: \"Worked Example — Small Org Chart from a Flat Table\",\n subtitleBase: \"Built with d3.stratify + ht_layout + ht_viewer4 · drag/scroll/double-click to explore ·\",\n width: 500,\n height: 500\n});\nconst myOrgPanel = ht_buildControlPanel(myOrgViewer, { baseDomainR: 1.05, edgeCurve: \"geodesic\" });\nht_alignPanelToPlot(myOrgViewer.element, myOrgPanel);\ndisplay(html`
${myOrgViewer.element}${myOrgPanel}
`);","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Mount worked example viewer from custom flat data","output":"$undefined","database":"$undefined"},{"id":130,"value":"The worked example is live above (500×500) — showing the CEO (root, pinned) with the three VPs visible; scroll/zoom in to reveal the individual reports underneath, exactly as documented.","pinned":false,"hidden":false,"mode":"md","author":"agent","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":131,"value":"display(md`\n## Quick Reference Card\n\n\\`\\`\\`js\n// 1. Load/define your data (a nested tree OR a flat table with id+parentId)\n\n// 2a. Nested tree:\nconst root = d3.hierarchy(myNestedData);\n\n// 2b. Flat table:\nconst root = d3.stratify()\n .id(d => d.id)\n .parentId(d => d.parentId || null)\n (myFlatRows);\n\n// 3. Compute the static hyperbolic layout (once)\nconst nodes = ht_layout(root, { k: 2.2 });\n\n// 4. Create the interactive viewer\nconst viewer = ht_viewer4(nodes, {\n label: d => d.data.name, // <- match your data's label field\n title: \"My Tree\",\n renderBudget: 600 // <- lower for very large trees\n});\n\n// 5. Display it\ndisplay(viewer.element);\n\n// Optional controls:\n// viewer.reset() — animate back to initial view\n// viewer.goToRoot() — animate so root is centered\n// viewer.transform — current view matrix (read-only)\n\\`\\`\\`\n\nThat's the entire surface area — everything else (pan, zoom, click-to-focus animation,\nroot-pinning, culling for scale) happens automatically inside \\`ht_viewer4\\`.\n`);","pinned":false,"hidden":false,"mode":"js","author":"agent","summary":"Documentation: quick reference card summary","output":"$undefined","database":"$undefined"},{"id":132,"value":"$41","pinned":false,"hidden":false,"mode":"md","author":"agent","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":185,"value":"## A Second Example — Same Org Chart, Extended with More Fields\n\nThe same flat-table recipe (Shape B1) works with as many extra data columns as you like — they\njust ride along on each node's `.data` and are available to `label`, tooltips, or any future\nper-node styling. Here the same 10-row CEO org chart is extended with a `gender` (`\"male\"` /\n`\"female\"`) and an `employees` (headcount managed, including self) field per row.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":186,"value":"$42","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":187,"value":"// exactly the recipe from the docs (Shape B1), same as the first worked example\nconst myOrgRoot2 = d3.stratify()\n .id((d) => d.id)\n .parentId((d) => d.parentId || null)\n (myOrgRows2);\n\nconst myOrgNodes2 = ht_layout(myOrgRoot2, { k: 2.2 });\ndisplay(`built hierarchy: ${myOrgNodes2.length} nodes`);","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":191,"value":"$43","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":188,"value":"const myOrgViewer2 = ht_viewer4(myOrgNodes2, {\n label: (d) => d.data.name,\n title: \"Second Worked Example — Org Chart with Gender & Employee Count\",\n subtitleBase: \"Same flat-table recipe as the first example, extended with gender + employees fields per node, plus a separate edge dataset · try the \\\"Mappings\\\" tab ·\",\n width: 500,\n height: 500,\n edgesData: myOrgEdges2\n});\nconst myOrgPanel2 = ht_buildControlPanel(myOrgViewer2, { baseDomainR: 1.05, edgeCurve: \"geodesic\" });\nht_alignPanelToPlot(myOrgViewer2.element, myOrgPanel2);\ndisplay(html`
${myOrgViewer2.element}${myOrgPanel2}
`);","pinned":false,"hidden":false,"mode":"js","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W44","stdlib":"2","titling":"auto"}} 2e:"$2d:body"