@john-guerra/fisheye-nav 0.1.0

package/src/render/index.js

@@ -0,0 +1,215 @@
+/**
+ * The renderers. Both consume the SAME rows, so neither knows (or can know)
+ * which layout strategy produced them — that is what keeps `style` and `layout`
+ * genuinely orthogonal instead of a 6-way switch.
+ *
+ *   flat    one column, indented by depth. Internal nodes get a real row (their
+ *           synthetic header cell), so "what level am I on" is answerable at a
+ *           glance. This is an outline.
+ *   icicle  one column per depth; a node's band is its children's span. This is
+ *           a partition diagram whose vertical axis happens to be fisheyed.
+ */
+
+import { select } from "d3-selection";
+import { makeBarScale } from "../layout/scales.js";
+import { injectStyle } from "./style.js";
+
+export const STYLES = ["flat", "icicle"];
+
+export const RENDER_DEFAULTS = {
+  /** px of indent per level (flat). */
+  indent: 11,
+  /** Draw the count histogram INSIDE each band (the row is the bar's track, the
+   * label sits on top). False hides it. */
+  bars: true,
+  /** px of clear space kept at the right edge. */
+  gutter: 6,
+  /** don't draw a label in a band thinner than this — it would just be noise. */
+  minLabelPx: 9,
+  /** count-histogram scale. Log by default — see scales.js for why. */
+  barScale: "log",
+  /** count formatter for the histogram tooltip/label. */
+  format: (n) => n.toLocaleString(),
+};
+
+/**
+ * @param {SVGElement} svg
+ * @param {{rows: any[], maxCount: number}} model  a `layout()` result
+ * @param {object} opts  width, height, style, selectedId, + RENDER_DEFAULTS
+ */
+export function render(svg, model, opts) {
+  const o = { ...RENDER_DEFAULTS, ...opts };
+  injectStyle(svg.ownerDocument);
+
+  const root = select(svg);
+  const { rows, maxCount } = model;
+  const { width, height, style } = o;
+
+  root.attr("viewBox", `0 0 ${width} ${height}`);
+
+  if (!rows.length) {
+    root.selectAll(".fn-row").remove();
+    root
+      .selectAll(".fn-empty")
+      .data([0])
+      .join("text")
+      .attr("class", "fn-empty")
+      .attr("x", width / 2)
+      .attr("y", height / 2)
+      .text(o.emptyLabel ?? "Nothing to show");
+    return;
+  }
+  root.selectAll(".fn-empty").remove();
+
+  // The bar's track is the ROW, not a column of its own: length encodes photo
+  // mass while the band's height encodes the lens, so the column reads as a
+  // histogram silhouette (the original AutoGallery design). The label is drawn
+  // over it.
+  const trackW = width - o.gutter;
+  const maxDepth = rows.reduce((m, r) => Math.max(m, r.depth), 1);
+  const geom =
+    style === "icicle"
+      ? icicleGeom(maxDepth, trackW)
+      : flatGeom(o.indent, trackW);
+
+  // Which rows get a bar. In an icicle the inner nodes own a column of their own,
+  // so they show their AGGREGATE — the count of the whole subtree they stand for.
+  // In flat mode they don't: a branch's band spans all of its children, so a bar
+  // across it would just be a block sitting behind them.
+  const barred = (d) =>
+    o.bars &&
+    d.count > 0 &&
+    (d.terminal || (style === "icicle" && d.kind === "branch"));
+
+  // Flat: ONE scale, absolute lengths, because every row shares one track — a
+  // per-row scale would draw equal counts at different lengths depending on how
+  // deep the row sits, which is a lie. A deeper row starts further right, so its
+  // bar is clipped to its own band.
+  const flatScale = makeBarScale(maxCount, Math.max(1, trackW), {
+    type: o.barScale,
+  });
+
+  // Icicle: each depth is a column, so each depth is its OWN histogram. A year
+  // (40,000 photos) and a day (300) do not belong on one scale — shared, every
+  // year's bar pegs at full width and the column encodes nothing. So the bar is a
+  // fraction of the row's own width, taken from a scale over that depth's max.
+  const depthScale = new Map();
+  if (style === "icicle") {
+    const maxAt = new Map();
+    for (const r of rows)
+      if (barred(r))
+        maxAt.set(r.depth, Math.max(maxAt.get(r.depth) ?? 0, r.count));
+    for (const [depth, m] of maxAt)
+      depthScale.set(
+        depth,
+        makeBarScale(m, 1, { type: o.barScale, minLenPx: 0.05 }),
+      );
+  }
+
+  const barLen = (d) => {
+    if (!barred(d)) return 0;
+    const w = Math.max(0, geom.w(d));
+    return style === "icicle"
+      ? (depthScale.get(d.depth)?.(d.count) ?? 0) * w
+      : Math.min(flatScale(d.count), w);
+  };
+
+  const g = root
+    .selectAll("g.fn-row")
+    .data(rows, (d) => d.id)
+    .join((enter) => {
+      const e = enter.append("g").attr("class", "fn-row");
+      e.append("rect").attr("class", "fn-band");
+      e.append("rect").attr("class", "fn-bar");
+      e.append("text").attr("class", "fn-label");
+      e.append("title");
+      return e;
+    });
+
+  g.attr("data-kind", (d) => d.kind)
+    .attr("data-depth", (d) => d.depth)
+    .attr("data-id", (d) => d.id)
+    .attr("data-focused", (d) => (d.focused ? "true" : null))
+    .classed("fn-selected", (d) => d.id === o.selectedId);
+
+  g.select("title").text(
+    (d) =>
+      `${d.label}\n${o.format(d.count)}` +
+      (d.elided ? ` · ${d.elided} groups collapsed` : ""),
+  );
+
+  g.select("rect.fn-band")
+    .attr("x", (d) => geom.x(d))
+    .attr("y", (d) => d.y0)
+    .attr("width", (d) => Math.max(0, geom.w(d)))
+    // Hairline bands still need to be clickable; 1px floor keeps the hit target.
+    .attr("height", (d) => Math.max(1, d.thickness))
+    // Drop the border on sub-pixel bands. In the compressed tail of an
+    // undecimated fisheye, hundreds of hairline bands stack their 0.5px strokes
+    // into a solid wall that swallows both the fill and the labels — the
+    // silhouette turns into a white smear. Inline style, because a stylesheet
+    // rule would beat a presentation attribute.
+    .style("stroke-width", (d) => (d.thickness >= 2 ? 0.5 : 0));
+
+  // Same x and same height as the band it fills — so the lens magnifies the bar
+  // along with its row, and the label (drawn after) sits over it.
+  g.select("rect.fn-bar")
+    .attr("x", (d) => geom.x(d))
+    .attr("y", (d) => d.y0)
+    .attr("width", barLen)
+    .attr("height", (d) => Math.max(1, d.thickness));
+
+  g.select("text.fn-label")
+    .attr("x", (d) => geom.x(d) + 4)
+    .attr("y", (d) => d.y)
+    .attr("font-weight", (d) =>
+      d.kind === "header" || d.kind === "branch" ? 600 : 400,
+    )
+    .attr("opacity", (d) => (labelled(d, style, o) ? 1 : 0))
+    .text((d) => (labelled(d, style, o) ? labelFor(d, geom.w(d)) : ""));
+}
+
+/** flat: indent by depth, span the rest of the track. */
+const flatGeom = (indent, barX) => ({
+  x: (d) => (d.depth - 1) * indent,
+  w: (d) => barX - (d.depth - 1) * indent,
+});
+
+/**
+ * icicle: one column per level. A terminal row spans from its own column to the
+ * end of the track, so a leaf that stops short in a ragged tree still reads as a
+ * leaf rather than leaving a hole (same convention as d3's icicle).
+ */
+const icicleGeom = (maxDepth, barX) => {
+  const colW = barX / maxDepth;
+  return {
+    x: (d) => (d.depth - 1) * colW,
+    w: (d) => (d.terminal ? barX - (d.depth - 1) * colW : colW),
+  };
+};
+
+/**
+ * A branch's band spans its whole subtree, so a label centred in it would land
+ * ON TOP of its children. In flat mode the branch's synthetic header row already
+ * carries the name, so the branch itself stays silent — shading only. In icicle
+ * mode the branch owns a column of its own, so it must be labelled.
+ */
+function labelled(d, style, o) {
+  if (style !== "icicle" && d.kind === "branch") return false;
+  // The row you are ON and the row you have CHOSEN always say what they are, at
+  // any thickness. The floor exists to stop hundreds of unreadable labels piling
+  // up — it must never silence the two rows the user is actually asking about.
+  // Without this, `fisheye` (which draws every leaf, so every band is a couple of
+  // pixels) is a lens onto a column of anonymous stripes: you hover, and nothing
+  // tells you where you are.
+  if (d.focused || d.id === o.selectedId) return true;
+  return d.thickness >= o.minLabelPx;
+}
+
+function labelFor(d, w) {
+  const text = d.kind === "elision" ? `⋯ ${d.label}` : (d.label ?? "");
+  // ~6px per char at 11px system-ui; cheap and good enough to avoid measuring
+  // text in a hot path that runs on every mousemove.
+  const max = Math.max(0, Math.floor((w - 8) / 6));
+  return text.length > max ? text.slice(0, Math.max(1, max - 1)) + "…" : text;
+}

package/src/render/style.js

@@ -0,0 +1,135 @@
+/**
+ * One stylesheet, injected once. Everything is expressed as a CSS custom
+ * property on `.fisheye-nav`, so a host restyles the widget without a build step
+ * and without the widget knowing anything about the host's design system.
+ *
+ * Colors are derived from a single hue + the host's text color, and the widget
+ * inherits `color-scheme`, so it lands correctly in a light or a dark app
+ * without being told which it is in.
+ */
+const CSS = `
+.fisheye-nav {
+  --fn-accent: #3b82f6;
+  --fn-fg: currentColor;
+  --fn-muted: color-mix(in oklab, currentColor 55%, transparent);
+  --fn-band: color-mix(in oklab, currentColor 8%, transparent);
+  --fn-band-hover: color-mix(in oklab, currentColor 16%, transparent);
+  --fn-rule: color-mix(in oklab, currentColor 18%, transparent);
+  --fn-bar: color-mix(in oklab, var(--fn-accent) 45%, transparent);
+  --fn-font: system-ui, -apple-system, "Segoe UI", sans-serif;
+  --fn-size: 11px;
+
+  position: relative;
+  display: block;
+  width: 100%;
+  height: 100%;
+  font-family: var(--fn-font);
+  font-size: var(--fn-size);
+  color: var(--fn-fg);
+  user-select: none;
+}
+.fisheye-nav svg { display: block; width: 100%; height: 100%; overflow: hidden; }
+.fisheye-nav .fn-row { cursor: pointer; }
+.fisheye-nav .fn-band {
+  fill: var(--fn-band);
+  stroke: var(--fn-rule);
+  stroke-width: 0.5;
+  shape-rendering: crispEdges;
+}
+.fisheye-nav .fn-row:hover .fn-band { fill: var(--fn-band-hover); }
+.fisheye-nav .fn-row[data-kind="branch"] .fn-band { fill: color-mix(in oklab, currentColor 4%, transparent); }
+.fisheye-nav .fn-row[data-kind="elision"] .fn-band { fill: none; stroke-dasharray: 2 2; }
+.fisheye-nav .fn-row[data-focused="true"] .fn-band {
+  fill: color-mix(in oklab, var(--fn-accent) 22%, transparent);
+  stroke: var(--fn-accent);
+  stroke-width: 1;
+}
+.fisheye-nav .fn-selected .fn-band {
+  stroke: var(--fn-accent);
+  stroke-width: 1.5;
+}
+.fisheye-nav .fn-bar { fill: var(--fn-bar); }
+.fisheye-nav .fn-label {
+  fill: var(--fn-fg);
+  dominant-baseline: middle;
+  pointer-events: none;
+  white-space: pre;
+}
+.fisheye-nav .fn-row[data-kind="branch"] .fn-label,
+.fisheye-nav .fn-row[data-kind="elision"] .fn-label { fill: var(--fn-muted); }
+.fisheye-nav .fn-count { fill: var(--fn-muted); text-anchor: end; dominant-baseline: middle; pointer-events: none; }
+.fisheye-nav .fn-spine { fill: var(--fn-rule); }
+.fisheye-nav .fn-empty { fill: var(--fn-muted); text-anchor: middle; }
+
+/* ── Settings gear + popover (opt out with controls: false) ──────────────────
+   Neutral defaults driven by the same --fn-* variables as the chart, so a host
+   restyles the panel without patching the library. */
+.fisheye-nav .fn-gear {
+  position: absolute; top: 2px; right: 4px; z-index: 6;
+  width: 18px; height: 18px; padding: 0; border: none; border-radius: 4px;
+  background: transparent; color: var(--fn-muted);
+  font-size: 12px; line-height: 18px; cursor: pointer;
+}
+.fisheye-nav .fn-gear:hover,
+.fisheye-nav .fn-gear.on { color: var(--fn-fg); background: var(--fn-band-hover); }
+/* Visibility is driven by the .fn-open CLASS, not by the hidden attribute: the
+   UA's "[hidden] { display: none }" is a single-attribute selector, so any rule
+   here that sets display outranks it and setting .hidden silently does nothing.
+   (It did exactly that — every popover in the demo rendered open.) The hidden
+   attribute is still kept in sync, for assistive tech.
+   NB: no backticks in this comment — the whole stylesheet is a JS template
+   literal, and a backtick here would terminate it. */
+/* The popover is the ONE place the widget paints its own background, so it is
+   the one place "inherit the host's color" stops working: an inherited
+   foreground over a system background is a coin toss (a dark app's near-white
+   text landed on Canvas-white and vanished). Background and foreground must
+   come from the same place — so they are a system PAIR by default, and a host
+   overriding one is expected to override the other. color-scheme makes the
+   pair, and the native selects and sliders inside, follow the host's theme. */
+.fisheye-nav .fn-panel {
+  position: absolute; top: 22px; right: 4px; z-index: 7;
+  width: 220px; padding: 8px; display: none; flex-direction: column; gap: 6px;
+  color-scheme: var(--fn-scheme, light dark);
+  background: var(--fn-panel, Canvas);
+  color: var(--fn-panel-fg, CanvasText);
+  border: 1px solid var(--fn-rule); border-radius: 6px;
+  box-shadow: 0 6px 20px rgb(0 0 0 / 0.28);
+}
+.fisheye-nav .fn-panel.fn-open { display: flex; }
+.fisheye-nav .fn-row-ctl { display: flex; align-items: center; gap: 6px; }
+.fisheye-nav .fn-ctl-label { flex: 0 0 76px; opacity: 0.75; }
+.fisheye-nav .fn-ctl-select {
+  flex: 1; min-width: 0; font: inherit; padding: 2px 4px;
+  color: inherit; background: transparent;
+  border: 1px solid var(--fn-rule); border-radius: 4px;
+}
+.fisheye-nav .fn-ctl-slider { flex: 1; display: flex; align-items: center; gap: 6px; min-width: 0; }
+.fisheye-nav .fn-ctl-slider input { flex: 1; min-width: 0; accent-color: var(--fn-accent); }
+.fisheye-nav .fn-ctl-val {
+  flex: 0 0 30px; text-align: right; opacity: 0.6;
+  font-variant-numeric: tabular-nums;
+}
+.fisheye-nav .fn-ctl-more summary { cursor: pointer; opacity: 0.75; margin-bottom: 4px; }
+.fisheye-nav .fn-ctl-more[open] { border-top: 1px solid var(--fn-rule); padding-top: 6px; }
+.fisheye-nav .fn-ctl-reset {
+  align-self: flex-start; font: inherit; padding: 2px 8px; cursor: pointer;
+  color: inherit; background: transparent;
+  border: 1px solid var(--fn-rule); border-radius: 4px;
+}
+/* A control that cannot affect the current lens says so, rather than silently
+   doing nothing when dragged. */
+.fisheye-nav .fn-disabled { opacity: 0.4; }
+`;
+
+let injected = false;
+
+export function injectStyle(doc = globalThis.document) {
+  if (injected || !doc?.head) return;
+  const el = doc.createElement("style");
+  el.setAttribute("data-fisheye-nav", "");
+  el.textContent = CSS;
+  doc.head.appendChild(el);
+  injected = true;
+}
+
+export { CSS };

package/src/svelte/FisheyeNav.svelte

@@ -0,0 +1,72 @@
+<script>
+  /**
+   * Svelte 4 wrapper. Owns the mount/teardown and the two-way `selected` binding,
+   * nothing else — all behaviour lives in the vanilla widget.
+   *
+   *   <FisheyeNav {data} keys={["year","month","day"]} bind:selected
+   *               on:select={(e) => jumpToPath(e.detail)} />
+   */
+  import { createEventDispatcher } from "svelte";
+  import { fisheyeNav } from "../fisheyeNav.js";
+
+  /** Flat rows (shape A) + the levels. */
+  export let data = undefined;
+  export let keys = undefined;
+  /** Or a nested tree (shape B). */
+  export let root = undefined;
+  export let children = undefined;
+
+  /**
+   * These are UNSET by default on purpose. Every prop we pass is an *explicit*
+   * option, and an explicit option beats the user's persisted choice — so a
+   * wrapper that always passed `style: "flat"` would both ignore `persistKey`
+   * and stomp the gear's selection on the next reactive update. Pass them only
+   * to pin the lens in code.
+   */
+  export let style = undefined; // "flat" | "icicle"
+  export let layout = undefined; // "fisheye" | "doi" | "hybrid" | "uniform"
+  /** The selected path, [{key, value}, …]. Bindable. */
+  export let selected = null;
+  /** Any other widget knob: distortion, minRowPx, label, count, persistKey, … */
+  export let options = {};
+
+  const dispatch = createEventDispatcher();
+  let nav = null;
+
+  const defined = (o) =>
+    Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+
+  $: opts = defined({ data, keys, root, children, style, layout, ...options });
+
+  function mount(node) {
+    nav = fisheyeNav({ ...opts, selected });
+    nav.addEventListener("input", () => {
+      // Write the binding BEFORE dispatching, so a parent reading `selected` in
+      // the handler sees the new value rather than the previous one.
+      selected = nav.value;
+      dispatch("select", nav.value);
+    });
+    node.appendChild(nav);
+    return {
+      destroy() {
+        nav?.destroy?.();
+        nav?.remove();
+        nav = null;
+      },
+    };
+  }
+
+  $: if (nav) nav.update(opts);
+  // Assigning `.value` is the SILENT path — it repaints the highlight without
+  // firing `input`, so a parent pushing the selection in cannot echo back out.
+  $: if (nav && selected !== nav.value) nav.value = selected;
+</script>
+
+<div class="fisheye-nav-host" use:mount></div>
+
+<style>
+  .fisheye-nav-host {
+    width: 100%;
+    height: 100%;
+  }
+</style>