@john-guerra/fisheye-nav 0.1.0

package/src/layout/select.js

@@ -0,0 +1,256 @@
+/**
+ * Stage 1: choose the SLOTS — the contiguous partition of the leaf axis that
+ * the positioner lays out. A slot is one of:
+ *
+ *   leaf      one real leaf
+ *   collapsed one closed subtree, standing in for all its leaves ("2019 · 1,204")
+ *   elision   a RUN of adjacent closed siblings, merged ("4 more groups")
+ *
+ * Two selectors, same output shape, so the positioner and renderers never learn
+ * which one ran:
+ *
+ *   selectAll  every leaf is its own slot. Honest, proportional, no elision.
+ *   selectDOI  Furnas degree-of-interest: score the leaves, keep the best ones
+ *              that fit the row budget, close everything else.
+ *
+ * Why score LEAVES and not internal nodes: a selector that can only choose which
+ * subtrees to *open* cannot be bounded. To show the focused leaf you must open
+ * its whole ancestor chain, and each open node drags in its siblings — on a
+ * 10-year library that is already 48 rows before you have chosen anything. So
+ * the budget has to bite at the leaf level, and structure falls out of it:
+ * a node is open iff it still holds a kept leaf.
+ */
+
+import { leavesOf } from "../hierarchy.js";
+
+/** @typedef {{node: any|null, parent?: any, nodes?: any[], leafStart: number,
+ *             leafEnd: number, count?: number}} Slot */
+
+/** One slot per leaf. Carries `count` like every other slot — `sizeBy: "count"`
+ * weights the column by slot mass, and a slot without it silently weighs zero. */
+export function selectAll(root) {
+  return leavesOf(root).map((node) => ({
+    node,
+    leafStart: node.leafStart,
+    leafEnd: node.leafEnd,
+    count: node.count,
+  }));
+}
+
+/** Distance from a node's leaf interval to the focused leaf; 0 if it contains it. */
+export function leafDistance(node, focusLeaf) {
+  if (focusLeaf >= node.leafStart && focusLeaf < node.leafEnd) return 0;
+  return focusLeaf < node.leafStart
+    ? node.leafStart - focusLeaf
+    : focusLeaf - (node.leafEnd - 1);
+}
+
+/**
+ * Hops from `a` up to the lowest common ancestor and back down to `b`. This is
+ * Furnas's tree distance, and it is the thing a purely positional distance
+ * cannot see: the day before the focused day might be three rows up but a whole
+ * YEAR away in the tree, while the focused day's own siblings are structurally
+ * adjacent no matter where they land on the axis.
+ */
+export function treeDistance(a, b) {
+  let x = a;
+  let y = b;
+  let d = 0;
+  while (x.depth > y.depth) {
+    x = x.parent;
+    d++;
+  }
+  while (y.depth > x.depth) {
+    y = y.parent;
+    d++;
+  }
+  while (x !== y && x.parent && y.parent) {
+    x = x.parent;
+    y = y.parent;
+    d += 2;
+  }
+  return d;
+}
+
+/**
+ * Furnas's degree of interest: how badly does the user want to see this leaf,
+ * given where they are looking?
+ *
+ *     DOI(leaf) = importance(leaf) - distance(leaf, focus) + mass(leaf)
+ *
+ * Leaves are ranked by this and the best ones that fit the budget keep a full
+ * row; the rest close into their ancestors. This function alone decides what a
+ * DOI tree FEELS like, so each term is deliberate:
+ *
+ *  - **importance** is depth measured RELATIVE to the focus, not absolutely. The
+ *    textbook `-depth` says a deep leaf matters less — true for the *root*'s
+ *    importance, false for leaves. In a ragged tree a depth-5 leaf isn't less
+ *    interesting than a depth-2 one, it's just more nested; what actually reads
+ *    badly is jumping between levels, so we penalise the level CHANGE.
+ *
+ *  - **distance** blends the two notions of "far", because each alone fails:
+ *    the leaf axis alone gives a clean readable window but is blind to
+ *    structure; the tree alone keeps the focus's siblings but scatters the
+ *    survivors across the column. `treeWeight` slides between them.
+ *    Axis distance goes through `log1p` so the falloff is smooth — a linear
+ *    penalty makes rank flip sharply as the focus moves, which is exactly what
+ *    makes rows pop in and out while you drag the cursor.
+ *
+ *  - **mass** is a weak tiebreaker, never a driver. Let it dominate and the lens
+ *    stops being about where you are and becomes a popularity chart.
+ *
+ * @param {any} leaf   hierarchy node (.depth, .count, .leafStart, .leafEnd, .parent)
+ * @param {{leaf: number, node: any}} focus  focused leaf index and its node
+ * @param {{apiWeight, distanceWeight, countWeight, treeWeight}} opts
+ * @returns {number}  higher = more interesting = more likely to keep its own row
+ */
+export function doiScore(leaf, focus, opts) {
+  const importance = -Math.abs(leaf.depth - focus.node.depth) * opts.apiWeight;
+
+  const axis = Math.log1p(leafDistance(leaf, focus.leaf));
+  const tree = treeDistance(leaf, focus.node);
+  const t = opts.treeWeight;
+  const distance = ((1 - t) * axis + t * tree) * opts.distanceWeight;
+
+  const mass = Math.log1p(leaf.count) * opts.countWeight;
+
+  return importance - distance + mass;
+}
+
+/**
+ * Keep the highest-DOI leaves that fit the row budget; close the rest.
+ *
+ * Guarantees the property tests lean on:
+ *  - slots partition [0, nLeaves) contiguously, so mass is always conserved;
+ *  - the focused leaf ALWAYS keeps its own slot — you can never lose the row you
+ *    are pointing at, whatever the budget;
+ *  - slot count <= budget (that is what the K search below is for).
+ *
+ * @param {any} root
+ * @param {{budget: number, focusLeaf: number} & Record<string, number>} opts
+ * @returns {Slot[]}
+ */
+export function selectDOI(root, opts) {
+  const leaves = leavesOf(root);
+  const n = leaves.length;
+  if (!n) return [];
+
+  const budget = Math.max(1, Math.floor(opts.budget ?? n));
+  if (n <= budget) return selectAll(root);
+
+  const focusLeaf = Math.max(0, Math.min(opts.focusLeaf ?? 0, n - 1));
+  const focus = { leaf: focusLeaf, node: leaves[focusLeaf] };
+
+  // Rank once. Header cells are excluded: they are force-kept whenever their
+  // node is open, so ranking them would just burn budget entries on rows we were
+  // going to draw anyway. Ties break toward the focus, then by leaf order, so the
+  // result is deterministic (a property test asserts it).
+  const ranked = leaves
+    .map((leaf, i) => ({ leaf, i, score: doiScore(leaf, focus, opts) }))
+    .filter(({ leaf }) => !leaf.data?.header)
+    .sort(
+      (a, b) =>
+        b.score - a.score ||
+        Math.abs(a.i - focusLeaf) - Math.abs(b.i - focusLeaf) ||
+        a.i - b.i,
+    );
+
+  // Closing leaves ADDS rows back (a closed subtree is still one row), so K is
+  // not simply the budget. Walk K down until the realized slot count fits. It
+  // converges fast — closed rows only ever shrink as K shrinks.
+  for (let K = Math.min(budget, n); K >= 1; K--) {
+    const keep = new Set(ranked.slice(0, K).map((r) => r.leaf));
+    keep.add(focus.node);
+    const slots = buildSlots(root, keep);
+    if (slots.length <= budget) return slots;
+  }
+  return buildSlots(root, new Set([focus.node]));
+}
+
+/**
+ * Turn a set of kept leaves into the slot partition.
+ *
+ * A node is OPEN iff it still contains a kept leaf. Under an open node, each
+ * child is either open (recurse) or closed (one slot). Adjacent closed children
+ * merge into a single elision slot — without that merge, a wide node whose
+ * children are all closed would spend one row per child and blow the budget it
+ * was supposed to be saving.
+ */
+function buildSlots(root, keep) {
+  const holdsKept = new Map();
+  root.eachAfter((n) => {
+    if (!n.children?.length) return holdsKept.set(n, keep.has(n));
+    holdsKept.set(
+      n,
+      n.children.some((c) => holdsKept.get(c)),
+    );
+  });
+
+  const slots = [];
+  let run = null; // the closed run currently being accumulated
+
+  const flush = () => {
+    if (!run) return;
+    slots.push(
+      run.nodes.length === 1
+        ? {
+            node: run.nodes[0],
+            leafStart: run.leafStart,
+            leafEnd: run.leafEnd,
+            count: run.count,
+          }
+        : {
+            node: null,
+            parent: run.parent,
+            nodes: run.nodes,
+            leafStart: run.leafStart,
+            leafEnd: run.leafEnd,
+            count: run.count,
+          },
+    );
+    run = null;
+  };
+
+  (function descend(node) {
+    for (const child of node.children ?? []) {
+      // A header always survives while its parent is open — a node that shows
+      // its children but not its own label is worse than useless.
+      const isHeader = child.data?.header;
+      const open = holdsKept.get(child) && child.children?.length;
+      const kept =
+        isHeader || (holdsKept.get(child) && !child.children?.length);
+
+      if (open || kept) {
+        flush(); // a visible child breaks the closed run
+        if (open) descend(child);
+        else
+          slots.push({
+            node: child,
+            leafStart: child.leafStart,
+            leafEnd: child.leafEnd,
+            count: child.count,
+          });
+        continue;
+      }
+
+      // Closed: accumulate into the current run of adjacent closed siblings.
+      if (run && run.parent === node) {
+        run.nodes.push(child);
+        run.leafEnd = child.leafEnd;
+        run.count += child.count;
+      } else {
+        flush();
+        run = {
+          parent: node,
+          nodes: [child],
+          leafStart: child.leafStart,
+          leafEnd: child.leafEnd,
+          count: child.count,
+        };
+      }
+    }
+    flush(); // a run never spans out of its parent — that would break containment
+  })(root);
+
+  return slots;
+}

package/src/react/index.js

@@ -0,0 +1,81 @@
+/**
+ * React wrapper. Written with createElement rather than JSX so the package needs
+ * no Babel step — the whole point of the vanilla core is that the wrappers stay
+ * this thin.
+ *
+ *   <FisheyeNav data={rows} keys={["year","month","day"]}
+ *               selected={path} onSelect={setPath} />
+ */
+
+import { createElement, useEffect, useRef } from "react";
+import { fisheyeNav } from "../fisheyeNav.js";
+
+export function FisheyeNav({
+  data,
+  keys,
+  root,
+  children,
+  style = "flat",
+  layout = "hybrid",
+  selected = null,
+  onSelect,
+  className,
+  ...options
+}) {
+  const hostRef = useRef(null);
+  const navRef = useRef(null);
+  // The handler is read at event time, so a re-render with a new closure does not
+  // require tearing the widget down and rebuilding it.
+  const onSelectRef = useRef(onSelect);
+  onSelectRef.current = onSelect;
+
+  useEffect(() => {
+    const nav = fisheyeNav({
+      data,
+      keys,
+      root,
+      children,
+      style,
+      layout,
+      selected,
+      ...options,
+    });
+    nav.addEventListener("input", () => onSelectRef.current?.(nav.value));
+    hostRef.current.appendChild(nav);
+    navRef.current = nav;
+    return () => {
+      nav.destroy?.();
+      nav.remove();
+      navRef.current = null;
+    };
+    // Mount once; every prop change flows through the update effects below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    navRef.current?.update({
+      data,
+      keys,
+      root,
+      children,
+      style,
+      layout,
+      ...options,
+    });
+  });
+
+  useEffect(() => {
+    const nav = navRef.current;
+    // `.value =` is the silent setter: it repaints the highlight without firing
+    // `input`, so a controlled parent cannot loop.
+    if (nav && nav.value !== selected) nav.value = selected;
+  }, [selected]);
+
+  return createElement("div", {
+    ref: hostRef,
+    className,
+    style: { width: "100%", height: "100%" },
+  });
+}
+
+export default FisheyeNav;

package/src/render/controls.js

@@ -0,0 +1,282 @@
+/**
+ * The settings gear + popover, owned by the widget.
+ *
+ * Same contract as @john-guerra/d3-zoomable-axis's scent controls, deliberately:
+ *   controls    a ⚙ that live-tunes the lens. On by default; pass false to
+ *               suppress it and drive the options from your own UI.
+ *   persistKey  a localStorage key, so a user's tuned lens survives a reload.
+ *               Pass none and listen for the "settings" event to use your own
+ *               store instead.
+ *
+ * A consumer should not have to hand-roll this — AutoGallery did, and every
+ * other consumer would have too.
+ */
+
+import { LAYOUTS } from "../layout/index.js";
+import { SIZE_BY } from "../layout/position.js";
+import { BAR_SCALES } from "../layout/scales.js";
+import { STYLES } from "./index.js";
+
+/** What the panel tunes AND persists. Never data, accessors, or sizes. */
+export const PERSIST_KEYS = [
+  "style",
+  "layout",
+  "sizeBy",
+  "distortion",
+  "minRowPx",
+  "barScale",
+  "apiWeight",
+  "distanceWeight",
+  "treeWeight",
+  "countWeight",
+];
+
+export function readStore(key) {
+  if (!key || typeof localStorage === "undefined") return null;
+  try {
+    const s = JSON.parse(localStorage.getItem(key) ?? "null");
+    return s && typeof s === "object" ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeStore(key, obj) {
+  if (!key || typeof localStorage === "undefined") return;
+  try {
+    const picked = {};
+    for (const k of PERSIST_KEYS) if (k in obj) picked[k] = obj[k];
+    localStorage.setItem(key, JSON.stringify(picked));
+  } catch {
+    /* quota / disabled storage — persistence is best-effort */
+  }
+}
+
+/** Keep only known keys with sane values: a stale or hand-edited store must not
+ * be able to wedge the widget into an unrenderable state. */
+export function sanitize(raw, defaults) {
+  const out = {};
+  if (!raw) return out;
+  const num = (v, lo, hi) => {
+    const n = Number(v);
+    return Number.isFinite(n) ? Math.min(hi, Math.max(lo, n)) : undefined;
+  };
+  const oneOf = (v, list) => (list.includes(v) ? v : undefined);
+  const put = (k, v) => {
+    if (v !== undefined) out[k] = v;
+  };
+
+  put("style", oneOf(raw.style, STYLES));
+  put("layout", oneOf(raw.layout, LAYOUTS));
+  put("sizeBy", oneOf(raw.sizeBy, SIZE_BY));
+  put("barScale", oneOf(raw.barScale, BAR_SCALES));
+  put("distortion", num(raw.distortion, 1, 12));
+  put("minRowPx", num(raw.minRowPx, 8, 48));
+  put("apiWeight", num(raw.apiWeight, 0, 3));
+  put("distanceWeight", num(raw.distanceWeight, 0, 3));
+  put("treeWeight", num(raw.treeWeight, 0, 1));
+  put("countWeight", num(raw.countWeight, 0, 2));
+  return { ...defaults, ...out };
+}
+
+const SELECTS = [
+  {
+    key: "style",
+    label: "View",
+    options: [
+      ["flat", "List (indented)"],
+      ["icicle", "Icicle (columns)"],
+    ],
+  },
+  {
+    key: "layout",
+    label: "Lens",
+    options: [
+      ["hybrid", "Hybrid — magnify + fold"],
+      ["fisheye", "Fisheye — every group"],
+      ["doi", "Interest — full rows"],
+      ["uniform", "Uniform — no lens"],
+    ],
+  },
+  {
+    key: "sizeBy",
+    label: "Band size",
+    options: [
+      ["slots", "Interest (equal)"],
+      ["count", "Photos (mass)"],
+    ],
+  },
+  {
+    key: "barScale",
+    label: "Bars",
+    options: [
+      ["log", "Log"],
+      ["sqrt", "Square root"],
+      ["linear", "Linear"],
+    ],
+  },
+];
+
+const SLIDERS = [
+  { key: "distortion", label: "Distortion", min: 1, max: 12, step: 0.5 },
+  { key: "minRowPx", label: "Row size", min: 8, max: 48, step: 1, unit: "px" },
+];
+
+// The DOI weights live behind a disclosure: they are where the lens's FEEL comes
+// from, but four extra sliders up front would bury the two knobs most people
+// actually want.
+const WEIGHTS = [
+  { key: "distanceWeight", label: "Focus falloff", min: 0, max: 3, step: 0.1 },
+  {
+    key: "treeWeight",
+    label: "Structure vs. list",
+    min: 0,
+    max: 1,
+    step: 0.05,
+  },
+  { key: "countWeight", label: "Busy groups", min: 0, max: 2, step: 0.05 },
+  { key: "apiWeight", label: "Same-level bias", min: 0, max: 3, step: 0.1 },
+];
+
+/**
+ * @param {HTMLElement} host      the widget root
+ * @param {{get:()=>object, set:(patch:object)=>void, reset:()=>void}} io
+ * @returns {{sync:()=>void, destroy:()=>void}}
+ */
+export function buildControls(host, io) {
+  const doc = host.ownerDocument;
+  const el = (tag, cls, props) =>
+    Object.assign(doc.createElement(tag), { className: cls, ...props });
+
+  const gear = el("button", "fn-gear", {
+    type: "button",
+    innerHTML: "⚙",
+    title: "Lens settings",
+  });
+  gear.setAttribute("aria-label", "Lens settings");
+  gear.setAttribute("aria-expanded", "false");
+
+  const panel = el("div", "fn-panel");
+  panel.hidden = true;
+  panel.setAttribute("role", "group");
+  panel.setAttribute("aria-label", "Lens settings");
+
+  const inputs = new Map();
+
+  const row = (label, control) => {
+    const r = el("label", "fn-row-ctl");
+    r.appendChild(el("span", "fn-ctl-label", { textContent: label }));
+    r.appendChild(control);
+    return r;
+  };
+
+  for (const s of SELECTS) {
+    const sel = el("select", "fn-ctl-select");
+    for (const [value, text] of s.options) {
+      sel.appendChild(el("option", "", { value, textContent: text }));
+    }
+    sel.addEventListener("change", () => io.set({ [s.key]: sel.value }));
+    inputs.set(s.key, sel);
+    panel.appendChild(row(s.label, sel));
+  }
+
+  const slider = (s) => {
+    const wrap = el("span", "fn-ctl-slider");
+    const input = el("input", "", {
+      type: "range",
+      min: String(s.min),
+      max: String(s.max),
+      step: String(s.step),
+    });
+    const out = el("span", "fn-ctl-val");
+    input.addEventListener("input", () => {
+      out.textContent = input.value + (s.unit ?? "");
+      io.set({ [s.key]: Number(input.value) });
+    });
+    wrap.append(input, out);
+    inputs.set(s.key, input);
+    return { wrap, input, out, spec: s };
+  };
+
+  const sliders = [];
+  for (const s of SLIDERS) {
+    const made = slider(s);
+    sliders.push(made);
+    panel.appendChild(row(s.label, made.wrap));
+  }
+
+  const details = el("details", "fn-ctl-more");
+  details.appendChild(el("summary", "", { textContent: "Interest weights" }));
+  for (const s of WEIGHTS) {
+    const made = slider(s);
+    sliders.push(made);
+    details.appendChild(row(s.label, made.wrap));
+  }
+  panel.appendChild(details);
+
+  const reset = el("button", "fn-ctl-reset", {
+    type: "button",
+    textContent: "Reset",
+  });
+  reset.addEventListener("click", () => io.reset());
+  panel.appendChild(reset);
+
+  // `.fn-open` is what actually shows the panel — see style.js. `hidden` is kept
+  // in sync for assistive tech, but it cannot be trusted to hide anything on its
+  // own once the stylesheet sets `display`.
+  const toggle = (open = panel.hidden) => {
+    panel.hidden = !open;
+    panel.classList.toggle("fn-open", open);
+    gear.classList.toggle("on", open);
+    gear.setAttribute("aria-expanded", String(open));
+  };
+  gear.addEventListener("click", () => toggle());
+
+  // Esc closes; a click outside closes. Both are what a popover is expected to
+  // do, and neither is worth making every consumer reimplement.
+  const onKey = (e) => {
+    if (e.key === "Escape" && !panel.hidden) toggle(false);
+  };
+  const onDocClick = (e) => {
+    if (panel.hidden) return;
+    if (!panel.contains(e.target) && e.target !== gear) toggle(false);
+  };
+  host.addEventListener("keydown", onKey);
+  doc.addEventListener("click", onDocClick, true);
+
+  host.append(gear, panel);
+
+  const sync = () => {
+    const o = io.get();
+    for (const [key, input] of inputs) {
+      const v = o[key];
+      if (input.tagName === "SELECT") input.value = String(v);
+      else input.value = String(v);
+    }
+    for (const s of sliders) {
+      s.out.textContent = String(o[s.spec.key]) + (s.spec.unit ?? "");
+    }
+    // Distortion means nothing without a lens; say so rather than letting the
+    // user drag a slider that does nothing.
+    const lensed = o.layout === "fisheye" || o.layout === "hybrid";
+    const dist = inputs.get("distortion");
+    dist.disabled = !lensed;
+    dist.closest(".fn-row-ctl").classList.toggle("fn-disabled", !lensed);
+    // Likewise the interest weights only matter when DOI is doing the selecting.
+    const doi = o.layout === "doi" || o.layout === "hybrid";
+    details.classList.toggle("fn-disabled", !doi);
+    for (const w of WEIGHTS) inputs.get(w.key).disabled = !doi;
+  };
+
+  sync();
+
+  return {
+    sync,
+    destroy() {
+      host.removeEventListener("keydown", onKey);
+      doc.removeEventListener("click", onDocClick, true);
+      gear.remove();
+      panel.remove();
+    },
+  };
+}