@john-guerra/fisheye-nav 0.1.0

package/src/layout/bands.js

@@ -0,0 +1,135 @@
+/**
+ * Stage 3: slots + pixel boundaries -> rows.
+ *
+ * This is where "parents contain their children" stops being something a
+ * renderer has to be careful about. Every node already owns a leaf interval
+ * (`leafStart`..`leafEnd`, from hierarchy.js), and the slots partition that same
+ * leaf axis. So a node's band is just the pixel span of the slots its leaf
+ * interval covers — and since a child's leaf interval is a SUBSET of its
+ * parent's, its band is necessarily inside its parent's. Containment is
+ * arithmetic, not diligence.
+ *
+ * A node is drawn iff its leaf interval is a whole number of slots AND no closed
+ * ancestor is standing in for it.
+ */
+
+/** @typedef {{node: any|null, parent?: any, nodes?: any[], leafStart: number,
+ *             leafEnd: number, count?: number}} Slot */
+
+/**
+ * @param {any} root            decorated hierarchy (see hierarchy.js)
+ * @param {Slot[]} slots        contiguous partition of the leaf axis
+ * @param {number[]} pos        slots.length + 1 pixel boundaries
+ * @param {{focusSlot?: number}} [opts]
+ * @returns {{rows: any[], maxCount: number}}
+ */
+export function buildRows(root, slots, pos, opts = {}) {
+  const S = slots.length;
+  if (!S) return { rows: [], maxCount: 0 };
+
+  const nLeaves = slots[S - 1].leafEnd;
+  const slotOfLeaf = new Int32Array(nLeaves);
+  for (let j = 0; j < S; j++) {
+    for (let i = slots[j].leafStart; i < slots[j].leafEnd; i++)
+      slotOfLeaf[i] = j;
+  }
+
+  // Nodes that a closed slot is standing in for. Without this, a chain like
+  // 2019 > 12 > 31 that is closed at "2019" would draw all three bands stacked
+  // on the same pixels — they all happen to span exactly one slot.
+  const hidden = new Set();
+  const hide = (n) => n.each?.((d) => d !== n && hidden.add(d));
+  for (const slot of slots) {
+    if (slot.node?.children?.length) hide(slot.node);
+    if (slot.nodes) for (const n of slot.nodes) n.each((d) => hidden.add(d));
+  }
+
+  const focusSlot = opts.focusSlot;
+  const rows = [];
+  let maxCount = 0;
+
+  const push = (row) => {
+    rows.push(row);
+    if (row.terminal && row.count > maxCount) maxCount = row.count;
+  };
+
+  const band = (sStart, sEnd) => {
+    const y0 = pos[sStart];
+    const y1 = pos[sEnd];
+    return {
+      slotStart: sStart,
+      slotEnd: sEnd,
+      leafStart: slots[sStart].leafStart,
+      leafEnd: slots[sEnd - 1].leafEnd,
+      focused: focusSlot != null && focusSlot >= sStart && focusSlot < sEnd,
+      y0,
+      y1,
+      y: (y0 + y1) / 2,
+      thickness: y1 - y0,
+    };
+  };
+
+  root.each((node) => {
+    if (node.depth === 0) return; // the synthetic root is not a row
+    if (hidden.has(node)) return;
+    if (node.leafStart >= nLeaves) return;
+
+    const sStart = slotOfLeaf[node.leafStart];
+    const sEnd = slotOfLeaf[node.leafEnd - 1] + 1;
+    const aligned =
+      slots[sStart].leafStart === node.leafStart &&
+      slots[sEnd - 1].leafEnd === node.leafEnd;
+    if (!aligned) return;
+
+    const slot = slots[sStart];
+    const collapsed =
+      sEnd - sStart === 1 && slot.node === node && !!node.children?.length;
+    // Terminal rows carry the count histogram: real leaves and closed subtrees.
+    // Everything else is structure.
+    const terminal = collapsed || !node.children?.length;
+
+    push({
+      node,
+      parentNode: node.parent,
+      id: node.id,
+      depth: node.depth,
+      label: node.label,
+      path: node.keyPath,
+      count: node.count,
+      kind: node.data?.header
+        ? "header"
+        : collapsed
+          ? "collapsed"
+          : terminal
+            ? "leaf"
+            : "branch",
+      terminal,
+      elided: collapsed ? node.leafEnd - node.leafStart : 0,
+      ...band(sStart, sEnd),
+    });
+  });
+
+  // Elision slots have no node of their own, so they are not reachable from the
+  // walk above — emit them here.
+  slots.forEach((slot, j) => {
+    if (slot.node || !slot.nodes) return;
+    const first = slot.nodes[0];
+    push({
+      node: null,
+      parentNode: slot.parent,
+      nodes: slot.nodes,
+      id: `elision:${first.id}+${slot.nodes.length}`,
+      depth: first.depth,
+      label: `${slot.nodes.length} more`,
+      path: slot.parent.keyPath,
+      count: slot.count,
+      kind: "elision",
+      terminal: true,
+      elided: slot.leafEnd - slot.leafStart,
+      ...band(j, j + 1),
+    });
+  });
+
+  rows.sort((a, b) => a.y0 - b.y0 || a.depth - b.depth);
+  return { rows, maxCount };
+}

package/src/layout/index.js

@@ -0,0 +1,202 @@
+/**
+ * The layout: one signature, three named strategies, ONE row contract.
+ *
+ * The strategies are not three algorithms — they are three cells of a 2x2 over
+ * two independent stages, `selection` x `positioning`:
+ *
+ *                | uniform positions | fisheye positions
+ *   -------------+-------------------+-------------------
+ *   all leaves   | "uniform"         | "fisheye"
+ *   DOI-selected | "doi"             | "hybrid"
+ *
+ * Everything downstream (bands, renderers, tests) is shared, so adding a fourth
+ * strategy means adding a selector or a positioner, never a new pipeline.
+ *
+ * Note what this dissolves: AutoGallery's old `positioning: "rank" | "proportional"`
+ * knob existed only because decimation squashed the near-focus leaves into a
+ * sub-pixel sliver. Here, "fisheye" never decimates (so rank IS proportional),
+ * and "hybrid" magnifies over DOI-selected slots (so rank is simply correct).
+ * The knob has no reason to exist.
+ */
+
+import { selectAll, selectDOI } from "./select.js";
+import {
+  basePositions,
+  resolveFocus,
+  slotAtPixel,
+  distort,
+  clamp,
+  SIZE_BY,
+} from "./position.js";
+import { buildRows } from "./bands.js";
+import { leavesOf } from "../hierarchy.js";
+
+export const LAYOUTS = ["fisheye", "doi", "hybrid", "uniform"];
+export { SIZE_BY };
+
+export const LAYOUT_DEFAULTS = {
+  /** Fisheye strength. Higher = gentler. (Ported knob; same meaning as before.) */
+  distortion: 4,
+  /** Top/bottom inset, px. */
+  pad: 6,
+  /** Target minimum row height — sets the DOI row budget. */
+  minRowPx: 16,
+  /** What a band's HEIGHT encodes.
+   *  "slots" — every visible group gets equal room, so height reads as INTEREST.
+   *  "count" — height is proportional to photo mass, so a 40k-photo year visibly
+   *            dwarfs a 400-photo one. A true value-encoded partition diagram. */
+  sizeBy: "slots",
+  /** Under `sizeBy: "count"`, the fraction of the column split EQUALLY before the
+   * rest is divided by mass. Without it, a zero-count group gets a zero-height
+   * band: invisible and impossible to click. 1 collapses back to "slots", so the
+   * two modes are the ends of one continuum. */
+  sizeFloor: 0.25,
+  /** DOI: penalty for sitting at a different level than the focus. */
+  apiWeight: 0.5,
+  /** DOI: how fast interest falls off with distance from the focus. */
+  distanceWeight: 1,
+  /** DOI: 0 = distance measured purely along the leaf axis (a clean readable
+   * window, blind to structure); 1 = purely tree distance (keeps the focus's
+   * siblings and cousins, but scatters survivors down the column). */
+  treeWeight: 0.6,
+  /** DOI: how much photo mass earns a row. A weak tiebreaker by design — turn it
+   * up and the lens becomes a popularity chart instead of a "where am I". */
+  countWeight: 0.25,
+};
+
+/**
+ * @param {any} root  a decorated hierarchy (see hierarchy.js `normalize`)
+ * @param {object} options
+ * @param {number} options.height
+ * @param {"fisheye"|"doi"|"hybrid"|"uniform"} [options.layout="fisheye"]
+ * @param {{leaf?: number, px?: number}} [options.focus]  focus by leaf index, or
+ *   pinned to a cursor pixel. Pixel wins when both are given — that is what keeps
+ *   the magnified row exactly under the pointer.
+ * @returns {{rows: any[], maxCount: number, focusLeaf: number, focusPx: number,
+ *            slots: number, leaves: number}}
+ */
+export function layout(root, options = {}) {
+  const o = { ...LAYOUT_DEFAULTS, ...options };
+  const height = o.height ?? 0;
+  const leaves = leavesOf(root);
+  const n = leaves.length;
+
+  const min = o.pad;
+  const max = height - o.pad;
+  if (!n || max <= min) {
+    return {
+      rows: [],
+      maxCount: 0,
+      focusLeaf: 0,
+      focusPx: min,
+      slots: 0,
+      leaves: n,
+    };
+  }
+
+  const strategy = LAYOUTS.includes(o.layout) ? o.layout : "fisheye";
+  const usesDOI = strategy === "doi" || strategy === "hybrid";
+  const usesFisheye = strategy === "fisheye" || strategy === "hybrid";
+
+  const sizeBy = SIZE_BY.includes(o.sizeBy) ? o.sizeBy : "slots";
+  const sizing = { min, max, sizeBy, sizeFloor: o.sizeFloor };
+
+  const budget = Math.max(4, Math.floor((max - min) / o.minRowPx));
+
+  // Which leaf is the focus? Under DOI this looks circular — the slot axis exists
+  // only once DOI has run, DOI needs a focus leaf, and the focus leaf is whatever
+  // sits under the cursor — but it isn't, as long as the caller says which ROW it
+  // is pointing at. The widget reads that off the frame it just drew (only it can:
+  // a pixel means whatever was last painted there, and this function is pure), and
+  // one pass resolves everything:
+  //
+  //   seed leaf -> DOI selects the slots -> the slot at the cursor is the focus.
+  //
+  // The old code had no seed, so it mapped the cursor pixel onto the WHOLE-LEAF
+  // axis instead. On a real library that is about one leaf per pixel, while the
+  // rows on screen are the ~35 DOI slots at ~16px apart — so one row of mouse
+  // travel moved the focus by ~30 leaves. You could not hover from 06 Feb to
+  // 07 Feb; it jumped straight to 06 Mar.
+  //
+  // Resist the urge to iterate this to a fixed point (focus the slot under the
+  // cursor, re-select, repeat). It converges, and it is worse: pointing just past
+  // the last open day lands on the collapsed month below, and the chase then
+  // re-centres INSIDE it — 27 Jan jumps to 27 Feb. One pass steps into the month
+  // and lets the next hover open it.
+  const px = o.focus?.px != null ? clamp(o.focus.px, min, max) : null;
+  const seed =
+    o.focus?.leaf != null
+      ? clamp(o.focus.leaf, 0, n - 1)
+      : px != null
+        ? // No seed (the first frame, before anything has been drawn). The leaf
+          // axis is the only axis there is; it is a rough guess, and the very next
+          // pointermove replaces it with the real row.
+          resolveFocus({ px }, basePositions(leaves, sizing)).slot
+        : 0;
+
+  const slots = usesDOI
+    ? selectDOI(root, { ...o, budget, focusLeaf: seed })
+    : selectAll(root);
+  const S = slots.length;
+  const basePos = basePositions(slots, sizing);
+
+  // The row under the cursor. Safe to read off the BASE axis: the fisheye pins
+  // `px` as a fixed point, so the slot whose base band contains it is exactly the
+  // slot whose DRAWN band contains it — which is what makes the row you click the
+  // row you pointed at.
+  const focusSlot =
+    px != null ? slotAtPixel(basePos, px) : slotOfLeaf(slots, seed);
+  const focusLeaf = px != null ? slots[focusSlot].leafStart : seed;
+  const focus = {
+    px: px ?? (basePos[focusSlot] + basePos[focusSlot + 1]) / 2,
+    slot: focusSlot,
+  };
+
+  // The lens distorts whatever base it is handed — equal spans or mass-weighted.
+  // It only needs monotonicity, which both give it.
+  const pos = usesFisheye
+    ? distort(basePos, { focusPx: focus.px, distortion: o.distortion })
+    : basePos;
+
+  const { rows, maxCount } = buildRows(root, slots, pos, {
+    focusSlot: focus.slot,
+  });
+
+  return {
+    rows,
+    maxCount,
+    focusLeaf,
+    focusPx: focus.px,
+    focusSlot: focus.slot,
+    slots: S,
+    leaves: n,
+  };
+}
+
+/** Which slot holds a given leaf. Slots are ordered, so binary search. */
+function slotOfLeaf(slots, leaf) {
+  let lo = 0;
+  let hi = slots.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (slots[mid].leafEnd <= leaf) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+export {
+  selectAll,
+  selectDOI,
+  doiScore,
+  leafDistance,
+  treeDistance,
+} from "./select.js";
+export {
+  fisheyePosition,
+  basePositions,
+  distort,
+  slotAtPixel,
+} from "./position.js";
+export { buildRows } from "./bands.js";
+export { makeBarScale } from "./scales.js";

package/src/layout/position.js

@@ -0,0 +1,142 @@
+/**
+ * Stage 2 of the layout: turn a slot sequence into pixel boundaries.
+ *
+ * Two steps, deliberately separate:
+ *
+ *   basePositions()  how much column each slot gets BEFORE any lens. Either
+ *                    equal spans (`sizeBy: "slots"` — size encodes interest) or
+ *                    spans proportional to mass (`sizeBy: "count"` — size encodes
+ *                    photo count, a true value-encoded partition diagram).
+ *   distort()        the fisheye, applied on top of whatever base it is given.
+ *
+ * The fisheye only needs its input to be monotonic, so it composes with either
+ * base for free. `x === a` stays a fixed point, which is what keeps the row under
+ * the cursor the row you click — mass-weighted or not.
+ *
+ * A slot sequence of length S gets S+1 boundaries spanning [min, max]. Slot j
+ * owns [pos[j], pos[j+1]], so the last slot gets a real band instead of
+ * collapsing onto the bottom edge.
+ */
+
+export const SIZE_BY = ["slots", "count"];
+
+/**
+ * The fisheye scale, ported verbatim from AutoGallery's `fisheye.js`, which
+ * ported it from PhotoRing's `d3_fisheye_scale` (d3 v3). Maps a base position
+ * `x` in [min, max] to a distorted position that magnifies around focus pixel
+ * `a` and compresses away from it. Monotonic in `x`; `x === a` is a fixed point;
+ * the endpoints map to themselves. Larger `d` = gentler distortion.
+ *
+ * This math is correct and well covered — it is the one piece carried over
+ * untouched.
+ *
+ * @returns {number}
+ */
+export function fisheyePosition(x, a, min, max, d) {
+  const left = x < a;
+  let m = left ? a - min : max - a;
+  if (m === 0) m = max - min;
+  const dx = Math.abs(x - a);
+  if (dx < 1e-9) return a;
+  return ((left ? -1 : 1) * (m * (d + 1))) / (d + m / dx) + a;
+}
+
+export const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+
+/**
+ * Base (undistorted) boundaries for a sequence of weighted items.
+ *
+ * `sizeBy: "count"` is the honest icicle: a 40,000-photo year visibly dwarfs a
+ * 400-photo one. But a pure mass split gives a zero-count group a zero-height
+ * band — invisible, and impossible to click. So every item is guaranteed
+ * `sizeFloor` of an equal share, and only the remainder is divided by mass:
+ *
+ *     span(j) = (1 - sizeFloor) * mass(j)/total  +  sizeFloor * 1/S
+ *
+ * sizeFloor = 1 collapses back to equal spans, so the two modes are the ends of
+ * one continuum rather than two code paths.
+ *
+ * @param {Array<{count?: number}>} items
+ * @param {{min:number, max:number, sizeBy?:string, sizeFloor?:number}} o
+ * @returns {number[]} S+1 boundaries
+ */
+export function basePositions(
+  items,
+  { min, max, sizeBy = "slots", sizeFloor = 0.25 },
+) {
+  const S = items.length;
+  const span = max - min;
+  const pos = new Array(S + 1);
+  pos[0] = min;
+
+  if (sizeBy !== "count") {
+    for (let j = 1; j <= S; j++) pos[j] = min + (span * j) / S;
+    pos[S] = max;
+    return pos;
+  }
+
+  const total = items.reduce((s, it) => s + Math.max(0, it.count ?? 0), 0);
+  const f = total > 0 ? clamp(sizeFloor, 0, 1) : 1; // no mass anywhere -> equal
+  let acc = min;
+  for (let j = 0; j < S; j++) {
+    const mass = total > 0 ? Math.max(0, items[j].count ?? 0) / total : 0;
+    acc += span * ((1 - f) * mass + f / S);
+    pos[j + 1] = acc;
+  }
+  pos[S] = max; // absorb float drift into the endpoint, which is pinned anyway
+  return pos;
+}
+
+/** The slot whose base interval contains pixel `px`. Works for ANY spacing —
+ * which is why this is a search and not a `scale.invert()`. */
+export function slotAtPixel(basePos, px) {
+  const S = basePos.length - 1;
+  if (S <= 0) return 0;
+  let lo = 0;
+  let hi = S - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (basePos[mid] <= px) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo;
+}
+
+/**
+ * Resolve the focus into BOTH representations:
+ *   `px`   the focus pixel (what the lens magnifies around)
+ *   `slot` the slot sitting under that pixel (what gets highlighted)
+ *
+ * When the host pins the focus to the cursor (`focus.px`), the pixel is
+ * authoritative and the slot is derived — that is what keeps the magnified row
+ * exactly under the pointer, so a click never lands on a row that slid away.
+ * When the host drives the focus from its own state (`focus.slot`), the slot is
+ * authoritative and the pixel is derived (the middle of its band).
+ */
+export function resolveFocus(focus, basePos) {
+  const S = basePos.length - 1;
+  const min = basePos[0];
+  const max = basePos[S];
+  if (S <= 0) return { px: min, slot: 0 };
+
+  if (focus?.px != null) {
+    const px = clamp(focus.px, min, max);
+    return { px, slot: slotAtPixel(basePos, px) };
+  }
+  const slot = clamp(focus?.slot ?? 0, 0, S - 1);
+  return { px: (basePos[slot] + basePos[slot + 1]) / 2, slot };
+}
+
+/** Apply the fisheye to a base boundary array. */
+export function distort(basePos, { focusPx, distortion }) {
+  const S = basePos.length - 1;
+  const min = basePos[0];
+  const max = basePos[S];
+  const a = clamp(focusPx, min, max);
+  const pos = basePos.map((x) => fisheyePosition(x, a, min, max, distortion));
+  // The scale pins the endpoints analytically; clamp anyway so floating-point
+  // drift can never push a band a hair outside the padded column.
+  pos[0] = min;
+  pos[S] = max;
+  return pos;
+}

package/src/layout/scales.js

@@ -0,0 +1,41 @@
+import { scaleLinear, scaleSqrt } from "d3-scale";
+
+export const BAR_SCALES = ["log", "sqrt", "linear"];
+
+/**
+ * Bar-length scale for the count histogram: mass -> pixel length.
+ *
+ * The default is LOG, and that is not a stylistic choice. Real hierarchies of
+ * this kind have pathological count distributions — a photo library where one
+ * "Unknown date" bucket holds 113,656 of 114,125 photos is a true story. Under a
+ * linear scale every other bar is the 4px minimum; under sqrt, a busy 300-photo
+ * day still renders at 5% of the track. Both turn the histogram into a row of
+ * identical stubs that encode nothing. `log1p(300)/log1p(113656) = 49%` — the
+ * silhouette comes back.
+ *
+ * Use `linear` when the counts are known to be well-behaved and you want the
+ * bars to be honestly proportional.
+ *
+ * @param {number} maxCount
+ * @param {number} maxLenPx
+ * @param {{minLenPx?: number, type?: "log"|"sqrt"|"linear"}} [opts]
+ * @returns {(count: number) => number}
+ */
+export function makeBarScale(maxCount, maxLenPx, opts = {}) {
+  const { minLenPx = 4, type = "log" } = opts;
+  const hi = Math.max(1, maxCount);
+
+  if (type === "log") {
+    // log1p, not scaleLog: the domain starts at 0 (an empty group is legal) and
+    // log(0) is -Infinity.
+    const denom = Math.log1p(hi);
+    return (count) => {
+      const c = Math.max(0, Math.min(count, hi));
+      const t = denom > 0 ? Math.log1p(c) / denom : 0;
+      return minLenPx + (maxLenPx - minLenPx) * t;
+    };
+  }
+
+  const scale = type === "linear" ? scaleLinear() : scaleSqrt();
+  return scale.domain([0, hi]).range([minLenPx, maxLenPx]).clamp(true);
+}