Treemap legibility: floors, plates, seams, labels and depth

src-tauri/src/scan.rs

@@ -168,6 +168,9 @@ pub struct TreemapRectDto {
     depth: u8,
     is_dir: bool,
     category: u8,
+    /// What the block is called; the canvas draws it inside the rect.
+    name: String,
+    size: u64,
 }
 
 #[derive(Clone, Serialize)]
@@ -338,6 +341,21 @@ pub fn get_path(state: State<'_, AppState>, generation: u64, id: NodeId) -> Resu
     Ok(tree.path(id))
 }
 
+/// The deepest the adaptive layout will go. Only a backstop — the legibility
+/// rules stop it long before this — but the tree's depth is unbounded, so
+/// something has to. Mirrored as `MAX_TREEMAP_DEPTH` in `ui/src/lib/prefs.ts`.
+const MAX_TREEMAP_DEPTH: u8 = 24;
+
+/// Legibility floor for a treemap rect, in CSS pixels. A child whose share of
+/// its directory falls under this is drawn at this size anyway — a directory
+/// has to tile edge to edge, or the small stuff reads as a hole rather than as
+/// small stuff. What no longer fits at this size is dropped smallest first, so
+/// the map still never turns into a mosaic of specks.
+const TREEMAP_MIN_SIDE_PX: f32 = 6.0;
+
+// The argument list mirrors the UI's query; grouping it into a struct would
+// only move the same list one level down.
+#[allow(clippy::too_many_arguments)]
 #[tauri::command(async)]
 pub fn get_treemap(
     state: State<'_, AppState>,
@@ -347,6 +365,8 @@ pub fn get_treemap(
     height: f32,
     hide_system: bool,
     filter: Option<String>,
+    force_open: Option<NodeId>,
+    max_depth: Option<u8>,
 ) -> Result<Vec<TreemapRectDto>, String> {
     let session = session_for(&state, generation)?;
     let builder = session.builder.read().unwrap();
@@ -358,19 +378,36 @@ pub fn get_treemap(
         return Ok(Vec::new());
     }
     let opts = TreemapOptions {
-        min_area_px: 3.0,
-        padding_px: 1.0,
-        max_depth: 24,
+        min_side_px: TREEMAP_MIN_SIDE_PX,
+        // The labels the UI can draw are a *view* of this geometry, never an
+        // input to it: nothing here knows whether they are on, so switching
+        // them cannot move a single block.
+        //
+        // `max_depth` is the Depth setting: absent means Auto, where the
+        // pixels decide how deep to go; present means the original fixed
+        // layout, which takes every level the cap allows and asks nothing.
+        max_depth: max_depth.unwrap_or(MAX_TREEMAP_DEPTH),
+        adaptive_depth: max_depth.is_none(),
         hide_system,
     };
     let viewport = Viewport {
         w: width,
         h: height,
     };
+    // `force_open` names a directory the user asked to see inside of. One that
+    // is not in this subtree, or no longer names a live directory, opens
+    // nothing rather than erroring: a stale id is what an accordion looks like
+    // from the other side of a delete, and it should close by itself.
     let rects = match overlay_for(&session, tree, filter.as_deref(), hide_system) {
-        Some(o) => treemap::layout_with_filter(tree, root_id, viewport, &opts, &o.bytes),
-        None => treemap::layout(tree, root_id, viewport, &opts),
+        Some(o) => {
+            treemap::layout_with_force(tree, root_id, viewport, &opts, Some(&o.bytes), force_open)
+        }
+        None => treemap::layout_with_force(tree, root_id, viewport, &opts, None, force_open),
     };
+    // The label's text rides along with the geometry: a rect the user can see
+    // is a rect they can read, and asking per node would be one round trip per
+    // rectangle. The floor in `opts` is what keeps the payload honest — what
+    // is sent is roughly what fits on screen, not the whole subtree.
     Ok(rects
         .into_iter()
         .map(|r| TreemapRectDto {
@@ -382,6 +419,8 @@ pub fn get_treemap(
             depth: r.depth,
             is_dir: r.is_dir,
             category: r.category,
+            name: tree.name(r.id).to_string(),
+            size: tree.node(r.id).size,
         })
         .collect())
 }

ui/src/App.tsx

@@ -17,6 +17,7 @@ import {
   type TreemapRect,
 } from "./lib/api";
 import { copyText } from "./lib/clipboard";
+import { layoutDepth } from "./lib/prefs";
 import { onUiError, reportUiError, reportUnlessStale } from "./lib/errors";
 
 const TREE_PANE_MIN = 320;
@@ -123,8 +124,10 @@ export default function App() {
 
   const handleTreemapSelect = useCallback(
     (rect: TreemapRect) => {
+      // Selecting only. Zooming is the treemap's own decision now — a click on
+      // a folder it drew as a plate opens that folder instead, and comes back
+      // through `onNavigate` if it turns out to want the whole view.
       select(rect.id);
-      if (rect.isDir) setViewRootId(rect.id);
       if (generation === 0) return;
       api
         .getAncestors(generation, rect.id)
@@ -357,13 +360,17 @@ export default function App() {
         viewRootId={viewRootId}
         startError={scan.startError}
         hideSystem={scan.hideSystem}
+        showLabels={scan.showLabels}
+        depth={scan.depth}
         filter={scan.filter}
         typePanelOpen={typePanelOpen}
         themePref={theme.pref}
         accent={theme.accent}
         onScan={handleScan}
         onCancel={scan.cancel}
         onToggleHideSystem={scan.toggleHideSystem}
+        onToggleShowLabels={scan.toggleShowLabels}
+        onDepth={scan.setDepth}
         onToggleTypePanel={() => setTypePanelOpen((v) => !v)}
         onSearchSelect={handleSearchSelect}
         onApplyFilter={scan.setFilter}
@@ -422,6 +429,8 @@ export default function App() {
             themeRev={theme.themeRev}
             hideSystem={scan.hideSystem}
             filter={scan.filter}
+            labels={scan.showLabels}
+            maxDepth={layoutDepth(scan.depth)}
             selected={selected}
             hoveredId={hoveredId}
             onSelect={handleTreemapSelect}

ui/src/components/SettingsMenu.tsx

@@ -5,6 +5,7 @@ import {
   type ThemePref,
   accentSwatch,
 } from "../lib/theme";
+import { DEPTH_OPTIONS, type DepthPref } from "../lib/prefs";
 import { PaletteIcon } from "./icons";
 
 const THEME_OPTIONS: { value: ThemePref; label: string }[] = [
@@ -15,18 +16,26 @@ const THEME_OPTIONS: { value: ThemePref; label: string }[] = [
 
 interface SettingsMenuProps {
   hideSystem: boolean;
+  showLabels: boolean;
+  depth: DepthPref;
   themePref: ThemePref;
   accent: AccentName;
   onToggleHideSystem: () => void;
+  onToggleShowLabels: () => void;
+  onDepth: (depth: DepthPref) => void;
   onThemePref: (pref: ThemePref) => void;
   onAccent: (accent: AccentName) => void;
 }
 
 export function SettingsMenu({
   hideSystem,
+  showLabels,
+  depth,
   themePref,
   accent,
   onToggleHideSystem,
+  onToggleShowLabels,
+  onDepth,
   onThemePref,
   onAccent,
 }: SettingsMenuProps) {
@@ -80,6 +89,43 @@ export function SettingsMenu({
             />
             Hide system files
           </label>
+          <label
+            className="mt-1.5 flex cursor-pointer items-center gap-2 text-[12px] text-ink-2"
+            title="Write each treemap block's name and size inside it"
+          >
+            <input
+              type="checkbox"
+              className="accent-accent"
+              checked={showLabels}
+              onChange={onToggleShowLabels}
+            />
+            Show names in treemap
+          </label>
+          <div className="mt-3 text-[11px] font-medium tracking-wide text-ink-4 uppercase">
+            Depth
+          </div>
+          <div className="mt-1.5 flex rounded-md border border-edge p-0.5">
+            {DEPTH_OPTIONS.map((opt) => (
+              <button
+                key={opt.label}
+                onClick={() => onDepth(opt.value)}
+                title={
+                  opt.value === "auto"
+                    ? "As deep as the pixels are worth — folders fold when nothing inside them would be readable"
+                    : opt.value === "all"
+                      ? "Every level that fits, and nothing folds"
+                      : `Exactly ${opt.label} level${opt.label === "1" ? "" : "s"}`
+                }
+                className={`h-6 flex-1 rounded text-[12px] ${
+                  depth === opt.value
+                    ? "bg-raised text-ink"
+                    : "text-ink-4 hover:text-ink-2"
+                }`}
+              >
+                {opt.label}
+              </button>
+            ))}
+          </div>
           <div className="mt-3 text-[11px] font-medium tracking-wide text-ink-4 uppercase">
             Theme
           </div>

ui/src/components/Toolbar.tsx

@@ -1,4 +1,5 @@
 import type { SearchHit } from "../lib/api";
+import type { DepthPref } from "../lib/prefs";
 import type { AccentName, ThemePref } from "../lib/theme";
 import { ExportMenu } from "./ExportMenu";
 import { ScanMenu } from "./ScanMenu";
@@ -13,13 +14,17 @@ interface ToolbarProps {
   viewRootId: number;
   startError: string | null;
   hideSystem: boolean;
+  showLabels: boolean;
+  depth: DepthPref;
   filter: string | null;
   typePanelOpen: boolean;
   themePref: ThemePref;
   accent: AccentName;
   onScan: (path: string) => void;
   onCancel: () => void;
   onToggleHideSystem: () => void;
+  onToggleShowLabels: () => void;
+  onDepth: (depth: DepthPref) => void;
   onToggleTypePanel: () => void;
   onSearchSelect: (hit: SearchHit) => void;
   onApplyFilter: (query: string | null) => void;
@@ -33,13 +38,17 @@ export function Toolbar({
   viewRootId,
   startError,
   hideSystem,
+  showLabels,
+  depth,
   filter,
   typePanelOpen,
   themePref,
   accent,
   onScan,
   onCancel,
   onToggleHideSystem,
+  onToggleShowLabels,
+  onDepth,
   onToggleTypePanel,
   onSearchSelect,
   onApplyFilter,
@@ -97,9 +106,13 @@ export function Toolbar({
       />
       <SettingsMenu
         hideSystem={hideSystem}
+        showLabels={showLabels}
+        depth={depth}
         themePref={themePref}
         accent={accent}
         onToggleHideSystem={onToggleHideSystem}
+        onToggleShowLabels={onToggleShowLabels}
+        onDepth={onDepth}
         onThemePref={onThemePref}
         onAccent={onAccent}
       />