refactor(vortex-web): label treemap layouts locally instead of a path header

Move each layout's name back onto its own block: container layouts label their
header band (which their children never occupy, so labels cannot collide) and
leaves label their body with name + bytes. Drop the top path header. The full
nested tree still renders down to the leaves so every physical block is visible,
coloured by dtype; hover drives the tooltip/sidebar and click selects (flat
blocks expand in place). Relies on the corrected header band (paddingTop set
after paddingOuter) so nested names stack cleanly without overlap.

Signed-off-by: Robert <robert@spiraldb.com>

Author: robert3005

vortex-web/README.md

@@ -8,11 +8,11 @@ The **Treemap** view (toggle in the header, next to the theme picker) renders a
 file's physical blocks all the way down to the leaves: layouts nest, flat
 layouts subdivide into their array-encoding buffers, and every block is sized by
 its byte footprint and coloured by dtype to match the swimlane and detail
-treemap. Only leaf blocks are labelled inline, so labels never collide; a header
-bar at the top is the path to the block under the cursor. Click a path segment
-to focus that subtree, and click a flat block to expand its buffers in place. It
-follows the app theme — dark by default, matching explore.vortex.dev — and the
-light theme via the theme picker.
+treemap. Each layout's name sits locally on the block — in a container's header
+band (which its children never occupy, so labels never collide) or in a leaf's
+body. Click a flat block to expand its buffers in place. It follows the app
+theme — dark by default, matching explore.vortex.dev — and the light theme via
+the theme picker.
 
 ![Treemap explorer overview](docs/img/treemap-explorer-overview.png)
 

vortex-web/docs/img/treemap-explorer-chunks-dark.png

@@ -10,8 +10,6 @@ import {
   getDtypeCategory,
   shortEncoding,
   collectSubtreeSegments,
-  findNodeById,
-  findPathToNode,
   isFlatLayout,
   formatBytes,
   DTYPE_COLORS,
@@ -45,6 +43,8 @@ interface TreeNode {
 
 type RectNode = HierarchyRectangularNode<TreeNode>;
 
+// Header band reserved at the top of each container layout for its own name.
+const HEADER = 16;
 const PAD = 2;
 
 function arraySubtreeBytes(node: LayoutTreeNode): number {
@@ -64,9 +64,9 @@ function subtreeBytes(node: LayoutTreeNode, segmentMap: Map<number, SegmentMapEn
   );
 }
 
-/** Build the full nested treemap for a subtree so every physical block is
- *  visible. Flat / array layouts expose their array-encoding children; other
- *  layouts hide array children until expanded. Tiles are coloured by dtype. */
+/** Build the full nested treemap for the file so every physical block is
+ *  visible down to the leaves. Flat / array layouts expose their array-encoding
+ *  children; other layouts hide array children until expanded. */
 function buildTree(node: LayoutTreeNode, segmentMap: Map<number, SegmentMapEntry>): TreeNode {
   const isArray = node.isArrayNode ?? false;
   const isFlatOrArray = isArray || node.encoding === 'vortex.flat';
@@ -118,20 +118,14 @@ export function BlockTreemap({
   const boxRef = useRef<HTMLDivElement>(null);
   const svgRef = useRef<SVGSVGElement>(null);
   const [size, setSize] = useState<{ w: number; h: number } | null>(null);
-  const [drillId, setDrillId] = useState(root.id);
   const [tooltip, setTooltip] = useState<Tooltip | null>(null);
   const [localHover, setLocalHover] = useState<string | null>(null);
 
   const { theme: themeChoice } = useTheme();
   const theme = useMemo(() => resolveThemeColors(themeChoice), [themeChoice]);
   const segmentMap = useMemo(() => new Map(segments.map((s) => [s.index, s])), [segments]);
+  const tree = useMemo(() => buildTree(root, segmentMap), [root, segmentMap]);
 
-  // Current drill root (the box shows this node's blocks). Falls back to the
-  // file root if the drilled node disappears.
-  const drillNode = useMemo(() => findNodeById(root, drillId) ?? root, [root, drillId]);
-  const tree = useMemo(() => buildTree(drillNode, segmentMap), [drillNode, segmentMap]);
-
-  // Track the box size (area below the path header).
   useEffect(() => {
     const el = boxRef.current;
     if (!el) return;
@@ -149,12 +143,22 @@ export function BlockTreemap({
       .sum((d) => (d.children ? 0 : d.bytes))
       .sort((a, b) => (b.value ?? 0) - (a.value ?? 0));
     treemap<TreeNode>()
-      .size([size.w, size.h])
+      // Lay out HEADER taller and shift up so the root's own header band sits
+      // off-screen — top-level fields start flush with the top.
+      .size([size.w, size.h + HEADER])
       .tile(treemapSquarify)
       .paddingInner(PAD)
       .paddingOuter(PAD)
+      // paddingTop MUST be set after paddingOuter (which also sets the top pad),
+      // or the header band collapses and container names overlap their children.
+      .paddingTop(HEADER)
       .round(true)(r);
-    return r.descendants() as RectNode[];
+    const desc = r.descendants() as RectNode[];
+    for (const n of desc) {
+      n.y0 -= HEADER;
+      n.y1 -= HEADER;
+    }
+    return desc;
   }, [tree, size]);
 
   const byId = useMemo(() => {
@@ -176,14 +180,9 @@ export function BlockTreemap({
   }, [selectedNodeId, byId]);
 
   const activeHover = localHover ?? hoveredNodeId;
-  const hoveredNode = activeHover ? findNodeById(root, activeHover) : null;
-
-  // Path shown in the header: to the hovered block while hovering (so any block
-  // can be identified), otherwise to the focused drill node.
-  const headerNode = hoveredNode ?? drillNode;
-  const headerPath = useMemo(() => findPathToNode(root, headerNode.id), [root, headerNode.id]);
 
-  /** Deepest tile (excluding the drill root itself) containing a point. */
+  /** Deepest tile (below the root) containing a point. A container's header band
+   *  is not covered by children, so clicking there selects the container. */
   const hitTest = useCallback(
     (px: number, py: number): RectNode | null => {
       let best: RectNode | null = null;
@@ -223,17 +222,6 @@ export function BlockTreemap({
     onHoverNode(null);
   }, [onHoverNode]);
 
-  /** Drill into a node: re-root the box at it and select it. */
-  const drillTo = useCallback(
-    (node: LayoutTreeNode) => {
-      if (isFlatLayout(node) && !node.children.some((c) => c.isArrayNode)) onExpand?.(node.id);
-      setDrillId(node.id);
-      onSelectNode(node.id);
-      setTooltip(null);
-    },
-    [onExpand, onSelectNode],
-  );
-
   const handleClick = useCallback(
     (e: React.MouseEvent<SVGSVGElement>) => {
       const p = localPoint(e.clientX, e.clientY);
@@ -249,106 +237,75 @@ export function BlockTreemap({
   );
 
   return (
-    <div className="flex flex-col w-full h-full">
-      {/* Path header — the box's title bar showing the current location. */}
-      <div className="flex items-center gap-1 flex-shrink-0 h-6 px-2 border-b border-vortex-grey-light/40 dark:border-white/[0.06] bg-vortex-grey-lightest dark:bg-white/[0.03] text-[11px] font-mono overflow-hidden">
-        {headerPath.map((node, i) => {
-          const isLast = i === headerPath.length - 1;
-          return (
-            <span key={node.id} className="flex items-center gap-1 min-w-0 flex-shrink-0">
-              {i > 0 && <span className="text-vortex-grey-dark opacity-40">/</span>}
-              {isLast ? (
-                <span className="text-vortex-fg-light dark:text-vortex-fg truncate">
-                  {getNodeDisplayName(node)}
-                </span>
-              ) : (
-                <button
-                  className="text-vortex-grey-dark hover:text-vortex-light-blue truncate"
-                  onClick={() => drillTo(node)}
-                  title={`Focus ${getNodeDisplayName(node)}`}
-                >
-                  {getNodeDisplayName(node)}
-                </button>
-              )}
-            </span>
-          );
-        })}
-        {hoveredNode && (
-          <span className="ml-auto flex-shrink-0 text-vortex-grey-dark truncate">
-            {shortEncoding(hoveredNode.encoding)} · {hoveredNode.dtype}
-          </span>
-        )}
-      </div>
-
-      {/* Box — the current node's blocks. */}
-      <div ref={boxRef} className="relative flex-1 min-h-0 overflow-hidden">
-        {size && (
-          <svg
-            ref={svgRef}
-            width={size.w}
-            height={size.h}
-            className="block select-none"
-            onMouseMove={handleMouseMove}
-            onMouseLeave={handleMouseLeave}
-            onClick={handleClick}
-          >
-            {nodes.map((n) => {
-              if (n.depth === 0) return null; // the drill root fills the box; shown in the header
-              const w = n.x1 - n.x0;
-              const h = n.y1 - n.y0;
-              if (w < 1 || h < 1) return null;
-
-              const d = n.data;
-              const isLeaf = !n.children || n.children.length === 0;
-              const isHovered = d.nodeId === activeHover;
-              const isSelected = selectedSubtreeIds.has(d.nodeId);
-              const maxChars = Math.floor((w - 6) / 6);
-              const label = maxChars < 2 ? '' : truncate(d.name, maxChars);
-
-              return (
-                <g key={d.nodeId} pointerEvents="none">
-                  <rect
-                    x={n.x0}
-                    y={n.y0}
-                    width={w}
-                    height={h}
-                    fill={d.color}
-                    fillOpacity={isSelected ? 0.4 : isLeaf ? 0.18 : 0.06}
-                    stroke={isHovered ? theme.highlight : theme.border}
-                    strokeWidth={isHovered ? 2 : isLeaf ? 0.5 : 1}
-                  />
-                  {/* Only leaf blocks are labelled, so labels never collide with
-                      nested content. Parent names come from the path header. */}
-                  {isLeaf && label && h > 14 && (
-                    <text
-                      x={n.x0 + 4}
-                      y={n.y0 + 12}
-                      fill={theme.fg}
-                      fontSize={10}
-                      fontFamily="'Geist Mono', monospace"
-                    >
-                      {label}
-                    </text>
-                  )}
-                  {isLeaf && w > 50 && h > 28 && (
-                    <text
-                      x={n.x0 + 4}
-                      y={n.y0 + 23}
-                      fill={theme.dim}
-                      fontSize={9}
-                      fontFamily="'Geist Mono', monospace"
-                    >
-                      {formatBytes(d.bytes)}
-                    </text>
-                  )}
-                </g>
-              );
-            })}
-          </svg>
-        )}
-
-        {tooltip && <TileTooltip tooltip={tooltip} segments={segments} fileSize={fileSize} />}
-      </div>
+    <div ref={boxRef} className="relative w-full h-full overflow-hidden">
+      {size && (
+        <svg
+          ref={svgRef}
+          width={size.w}
+          height={size.h}
+          className="block select-none cursor-pointer"
+          onMouseMove={handleMouseMove}
+          onMouseLeave={handleMouseLeave}
+          onClick={handleClick}
+        >
+          {nodes.map((n) => {
+            if (n.depth === 0) return null; // root fills the box; its band is shifted off-screen
+            const w = n.x1 - n.x0;
+            const h = n.y1 - n.y0;
+            if (w < 1 || h < 1) return null;
+
+            const d = n.data;
+            const isLeaf = !n.children || n.children.length === 0;
+            const isHovered = d.nodeId === activeHover;
+            const isSelected = selectedSubtreeIds.has(d.nodeId);
+            const maxChars = Math.floor((w - 6) / 6);
+            const label = maxChars < 2 ? '' : truncate(d.name, maxChars);
+
+            return (
+              <g key={d.nodeId} pointerEvents="none">
+                <rect
+                  x={n.x0}
+                  y={n.y0}
+                  width={w}
+                  height={h}
+                  fill={d.color}
+                  fillOpacity={isSelected ? 0.4 : isLeaf ? 0.18 : 0.06}
+                  stroke={isHovered ? theme.highlight : theme.border}
+                  strokeWidth={isHovered ? 2 : isLeaf ? 0.5 : 1}
+                />
+                {/* Name sits locally on the block: in a leaf's body, or in a
+                    container's header band (which children never occupy, so it
+                    cannot collide with them). */}
+                {label && h > 11 && (
+                  <text
+                    x={n.x0 + 4}
+                    y={n.y0 + 11}
+                    fill={theme.fg}
+                    fontSize={10}
+                    fontWeight={isLeaf ? 400 : 600}
+                    fontFamily="'Geist Mono', monospace"
+                  >
+                    {label}
+                  </text>
+                )}
+                {isLeaf && w > 50 && h > 26 && (
+                  <text
+                    x={n.x0 + 4}
+                    y={n.y0 + 22}
+                    fill={theme.dim}
+                    fontSize={9}
+                    fontFamily="'Geist Mono', monospace"
+                  >
+                    {formatBytes(d.bytes)}
+                  </text>
+                )}
+              </g>
+            );
+          })}
+        </svg>
+      )}
+
+      {tooltip && <TileTooltip tooltip={tooltip} segments={segments} fileSize={fileSize} />}
     </div>
   );
 }

vortex-web/docs/img/treemap-explorer-hover.png

@@ -57,9 +57,7 @@ export function TreemapExplorer() {
             {cat}
           </div>
         ))}
-        <span className="ml-auto flex-shrink-0">
-          click a block to select · click the path to focus a subtree
-        </span>
+        <span className="ml-auto flex-shrink-0">click a block to inspect it</span>
       </div>
 
       {/* Map + sidebar */}