@john-guerra/fisheye-nav 0.1.0

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@john-guerra/fisheye-nav",
+  "version": "0.1.0",
+  "description": "A focus+context navigator for hierarchies: an icicle whose leaf axis is fisheyed, or a flat list indented by level. Vanilla reactive widget, with Svelte and React wrappers.",
+  "type": "module",
+  "main": "dist/fisheye-nav.min.js",
+  "module": "dist/fisheye-nav.esm.js",
+  "svelte": "./src/svelte/FisheyeNav.svelte",
+  "browser": "dist/fisheye-nav.min.js",
+  "unpkg": "dist/fisheye-nav.min.js",
+  "jsdelivr": "dist/fisheye-nav.min.js",
+  "exports": {
+    ".": {
+      "import": "./dist/fisheye-nav.esm.js",
+      "default": "./dist/fisheye-nav.min.js"
+    },
+    "./core": "./src/index.js",
+    "./svelte": "./src/svelte/FisheyeNav.svelte",
+    "./react": "./dist/react.esm.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "concurrently \"rollup -c -w\" \"vite example\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src test example",
+    "format": "prettier --write \"{src,test,example,site}/**/*.{js,jsx,svelte,html,css}\" \"*.{js,json,md}\"",
+    "prepublishOnly": "npm run build && npm test",
+    "format:check": "prettier --check \"{src,test,example,site}/**/*.{js,jsx,svelte,html,css}\" \"*.{js,json,md}\"",
+    "site": "npm run build && mkdir -p _site && cp site/index.html _site/ && cp example/demo.js _site/ && cp dist/fisheye-nav.esm.js _site/ && npx http-server _site -p 5191"
+  },
+  "keywords": [
+    "fisheye",
+    "focus+context",
+    "icicle",
+    "hierarchy",
+    "tree",
+    "navigator",
+    "d3",
+    "reactive-widget",
+    "degree-of-interest",
+    "visualization"
+  ],
+  "dependencies": {
+    "d3-hierarchy": "^3.1.2",
+    "d3-scale": "^4.0.2",
+    "d3-selection": "^3.0.0",
+    "reactive-widget-helper": "^0.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "svelte": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "concurrently": "^9.1.0",
+    "eslint": "^9.8.0",
+    "eslint-config-prettier": "^9.1.0",
+    "fast-check": "^3.23.1",
+    "jsdom": "^25.0.1",
+    "prettier": "^3.3.3",
+    "prettier-plugin-svelte": "^4.1.1",
+    "rollup": "^4.20.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "vite": "^5.4.11",
+    "vitest": "^2.1.8"
+  },
+  "author": {
+    "name": "John Alexis Guerra Gómez",
+    "url": "https://johnguerra.co"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/john-guerra/fisheye-nav.git"
+  },
+  "bugs": {
+    "url": "https://github.com/john-guerra/fisheye-nav/issues"
+  },
+  "homepage": "https://john-guerra.github.io/fisheye-nav/",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/fisheyeNav.js

@@ -0,0 +1,305 @@
+/**
+ * The widget: a reactivewidgets-style DOM node.
+ *
+ *   const nav = fisheyeNav({ data, keys: ["year","month","day"] });
+ *   nav.addEventListener("input", () => console.log(nav.value));  // the path
+ *   nav.value = [{key:"year", value:"2024"}];                     // set silently
+ *
+ * `value` is the path to whatever the user clicked, truncated at that depth:
+ * click a day and you get the full 3-level path; click the "2024" band and you
+ * get just [{key:"year", value:"2024"}]. Hover drives the LENS and never fires
+ * `input` — otherwise every mousemove would look like a selection.
+ */
+
+// Subpath, not the bare specifier: reactive-widget-helper@0.0.3 declares
+// `"type": "module"` but points `main` at a UMD bundle, so Node's ESM resolver
+// loads it, finds no exports, and hands back `undefined`. Browsers and bundlers
+// dodge this by preferring the `module` field; Node (vitest, SSR) does not.
+// Remove this once upstream ships an `exports` map.
+import ReactiveWidget from "reactive-widget-helper/dist/ReactiveWidget.es.js";
+import { pointer } from "d3-selection";
+import { normalize, leavesOf, idOfPath } from "./hierarchy.js";
+import { layout, LAYOUT_DEFAULTS } from "./layout/index.js";
+import { render, RENDER_DEFAULTS, STYLES } from "./render/index.js";
+import { injectStyle } from "./render/style.js";
+import {
+  buildControls,
+  readStore,
+  writeStore,
+  sanitize,
+  PERSIST_KEYS,
+} from "./render/controls.js";
+
+export const NAV_DEFAULTS = {
+  ...LAYOUT_DEFAULTS,
+  ...RENDER_DEFAULTS,
+  style: "flat",
+  /** A ⚙ that live-tunes the lens. Pass false to drive the options yourself. */
+  controls: true,
+  /** localStorage key, so a tuned lens survives a reload. Omit and listen for
+   * the "settings" event to use your own store instead. */
+  persistKey: null,
+  // `hybrid`, not `fisheye`, is the default: pure fisheye draws every leaf, which
+  // on a real library (thousands of days) means thousands of sub-pixel bands —
+  // honest about density, unreadable as a navigator. Hybrid bounds the row count
+  // to what actually fits and stays readable at any library size. Pick `fisheye`
+  // deliberately when you want the undecimated silhouette.
+  layout: "hybrid",
+  width: null, // null = measure the container
+  height: null,
+};
+
+export function fisheyeNav(options = {}) {
+  const doc = options.document ?? globalThis.document;
+  const el = doc.createElement("div");
+  el.className = "fisheye-nav";
+  injectStyle(doc);
+
+  const svg = doc.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("preserveAspectRatio", "none");
+  svg.setAttribute("role", "listbox");
+  el.appendChild(svg);
+
+  // A persisted lens wins over the defaults but NOT over what the caller passed
+  // explicitly — a host pinning `style: "icicle"` in code means it, and a stale
+  // localStorage entry must not silently override it.
+  const stored = sanitize(readStore(options.persistKey), {});
+  let opts = { ...NAV_DEFAULTS, ...stored, ...options };
+  let root = null; // the normalized hierarchy
+  let model = null; // the last layout result
+  let hoverPx = null; // the pinned cursor pixel, or null when not hovering
+  // Where DOI opens its window. Moves ONLY on a click (see the click handler) —
+  // never on hover, or the rows reshuffle under the cursor. Null = follow the
+  // selection.
+  let anchorLeaf = null;
+  let size = { width: 0, height: 0 };
+  let controls = null;
+
+  // --- state derivation -----------------------------------------------------
+
+  const rebuild = () => {
+    root = normalize({
+      data: opts.data,
+      keys: opts.keys,
+      root: opts.root,
+      children: opts.children,
+      value: opts.value,
+      count: opts.count,
+      label: opts.label,
+      // Flat mode needs a real row per internal node to have something to indent;
+      // an icicle gives parents a column instead, so headers would be redundant.
+      headers: opts.style === "flat",
+    });
+  };
+
+  /** The leaf the current selection sits on — where the lens rests when not hovering. */
+  const selectedLeaf = () => {
+    const path = el.value;
+    if (!path?.length || !root) return 0;
+    let node = root;
+    for (const step of path) {
+      const next = (node.children ?? []).find(
+        (c) =>
+          !c.data.header &&
+          c.data.key === step.key &&
+          c.data.value === step.value,
+      );
+      if (!next) break;
+      node = next;
+    }
+    return node.leafStart ?? 0;
+  };
+
+  // `idOfPath`, not a second copy of the same join. This built the id with a
+  // SPACE while the rows built it with PATH_SEP, so any selection deeper than one
+  // level failed to match its row: selecting a day never highlighted it (and,
+  // once the label floor learned about the selection, never labelled it either).
+  const selectedId = () => {
+    const path = el.value;
+    return path?.length ? idOfPath(path) : null;
+  };
+
+  const measure = () => {
+    const w = opts.width ?? el.clientWidth;
+    const h = opts.height ?? el.clientHeight;
+    size = { width: Math.max(0, w), height: Math.max(0, h) };
+  };
+
+  const draw = () => {
+    if (!root) rebuild();
+    measure();
+    if (!size.width || !size.height) return;
+
+    model = layout(root, {
+      ...opts,
+      height: size.height,
+      // Two focuses, and keeping them apart is the whole trick: the PIXEL steers
+      // the lens, continuously; the LEAF decides which rows DOI opens, and it
+      // moves only on a click. See the pointermove and click handlers.
+      focus: { px: hoverPx ?? undefined, leaf: anchorLeaf ?? selectedLeaf() },
+    });
+
+    render(svg, model, { ...opts, ...size, selectedId: selectedId() });
+  };
+
+  // --- interaction ----------------------------------------------------------
+
+  /**
+   * HOVER MOVES THE LENS. IT DOES NOT RE-SELECT. This is load-bearing.
+   *
+   * A lens is only stable over a FIXED set of rows. DOI selection is not fixed —
+   * it is a function of the focus — so re-running it on every mousemove reshuffles
+   * the rows under the cursor and the leaf you are pointing at changes
+   * discontinuously: hovering down through January you get 27 Jan, Feb, 23 Feb,
+   * 27 Feb, Mar, and whole weeks are simply unreachable. (Plain `fisheye` selects
+   * every leaf, so its set is fixed, and it never does this.)
+   *
+   * Re-anchoring DOI on whatever the cursor touches does not fix it either: the
+   * row budget is fixed, so opening one region collapses another, and the tail
+   * oscillates — 9 more, 8 more, ... 2 more, 9 more, forever.
+   *
+   * So which rows are open changes only when the user SAYS so, by clicking. Hover
+   * magnifies what is there; a click drills in and re-opens the window around it
+   * (via `selectedLeaf`). That is the DOI-browser tradition, and it is what the
+   * original AutoGallery sidebar did — its decimated set was fixed too, which is
+   * precisely why hovering it never jumped.
+   */
+  svg.addEventListener("pointermove", (e) => {
+    hoverPx = pointer(e, svg)[1];
+    draw();
+  });
+
+  svg.addEventListener("pointerleave", () => {
+    hoverPx = null; // the lens snaps back to the selection
+    draw();
+  });
+
+  /**
+   * EVERY ITEM MUST BE SELECTABLE. The column shows ~40 rows of a library that
+   * may hold thousands of leaves, so most of them are, at any moment, folded into
+   * a closed subtree or an elision. Reaching them therefore has to be a matter of
+   * DRILLING IN — and every click must make progress toward that, or some leaves
+   * are unreachable forever.
+   *
+   * Which is why a click moves the DOI anchor INTO what was clicked, rather than
+   * relying on the selection to do it:
+   *
+   *   - a leaf, a header, a closed subtree -> select it; the window opens there.
+   *   - an ELISION (a run of closed siblings, "7 more") stands for no single node,
+   *     so there is no path to select. It used to select the elision's PARENT —
+   *     which, if the parent was already selected, changed nothing at all: click
+   *     it forever and the days inside it never open. A dead end, and a whole
+   *     region of the library you could see but never reach.
+   *
+   * So the anchor goes to the first leaf the clicked row stands for. That run
+   * always scores highest next time, so it always opens. Drill enough and any
+   * leaf gets its own row.
+   */
+  svg.addEventListener("click", (e) => {
+    const g = e.target.closest?.("g.fn-row");
+    if (!g) return;
+    const row = model?.rows.find((r) => r.id === g.getAttribute("data-id"));
+    if (!row) return;
+
+    anchorLeaf = row.leafStart; // always progress: open where you clicked
+
+    // `row.path` — NOT `row.parentNode.path`. An elision row already carries its
+    // parent's path (bands.js), and `parentNode` is a d3 hierarchy node, whose
+    // `.path` is d3's own path(target) METHOD. Reading it got a function, whose
+    // `.length` is 1 (its arity), so the emptiness guard passed and `.map` threw —
+    // killing the handler before it could redraw. The anchor moved, the screen did
+    // not, and clicking a "2 more" row did nothing at all, forever: the two years
+    // it stood for could be seen and never reached.
+    const path = row.path;
+    if (!path?.length) {
+      draw(); // an elision at the root: nothing to select, but still drill in
+      return;
+    }
+    el.setValue(path.map((p) => ({ ...p })));
+  });
+
+  // --- reactive-widget contract --------------------------------------------
+
+  const widget = ReactiveWidget(el, {
+    value: options.selected ?? null,
+    // Called on `input` AND on a silent `.value = x` set — so a host pushing the
+    // selection in gets the highlight without an event echoing back out.
+    showValue: () => draw(),
+  });
+
+  /** Merge new options and redraw. Re-normalizes only when it has to. */
+  el.update = (next = {}) => {
+    const restructure =
+      ("data" in next && next.data !== opts.data) ||
+      ("root" in next && next.root !== opts.root) ||
+      ("keys" in next && String(next.keys) !== String(opts.keys)) ||
+      ("style" in next && next.style !== opts.style); // headers on/off
+    opts = { ...opts, ...next };
+    if (!STYLES.includes(opts.style)) opts.style = "flat";
+    if (restructure) rebuild();
+    controls?.sync();
+    draw();
+  };
+
+  // --- settings -------------------------------------------------------------
+
+  /** Apply a settings change: persist it, tell the host, redraw. */
+  const applySettings = (patch) => {
+    el.update(patch);
+    writeStore(opts.persistKey, opts);
+    // A host that wants its own store (or wants to mirror the lens elsewhere)
+    // listens for this instead of passing a persistKey.
+    el.dispatchEvent(
+      new CustomEvent("settings", { detail: el.getSettings(), bubbles: true }),
+    );
+  };
+
+  /** The tunable lens settings — the subset that is persisted. */
+  el.getSettings = () => {
+    const out = {};
+    for (const k of PERSIST_KEYS) out[k] = opts[k];
+    return out;
+  };
+
+  el.setSettings = (patch) =>
+    applySettings(sanitize({ ...el.getSettings(), ...patch }, {}));
+
+  el.resetSettings = () => {
+    const defaults = {};
+    for (const k of PERSIST_KEYS) defaults[k] = NAV_DEFAULTS[k];
+    applySettings(defaults);
+  };
+
+  if (opts.controls !== false) {
+    controls = buildControls(el, {
+      get: () => opts,
+      set: applySettings,
+      reset: () => el.resetSettings(),
+    });
+  }
+
+  el.getRows = () => model?.rows ?? [];
+  el.getRoot = () => root;
+  // Real leaves only. The synthetic header cells are an internal device for the
+  // flat view's outline; leaking them here would make the count depend on the
+  // current style, which is nobody's idea of a leaf count.
+  el.getLeafCount = () =>
+    root ? leavesOf(root).filter((n) => !n.data.header).length : 0;
+
+  if (typeof ResizeObserver !== "undefined") {
+    const ro = new ResizeObserver(() => draw());
+    ro.observe(el);
+    el.destroy = () => {
+      ro.disconnect();
+      controls?.destroy();
+    };
+  } else {
+    el.destroy = () => controls?.destroy();
+  }
+
+  rebuild();
+  draw();
+  return widget;
+}
+
+export default fisheyeNav;

package/src/hierarchy.js

@@ -0,0 +1,259 @@
+/**
+ * Input normalization: both accepted input shapes collapse into ONE decorated
+ * `d3.hierarchy`, so every layout strategy and every renderer downstream sees
+ * exactly one data structure.
+ *
+ *   A) flat rows + keys   { data: [...], keys: ["year","month","day"] }
+ *   B) nested tree        { root: {...}, children: d => d.children }
+ *
+ * (A) is the "tidy long table" form — a sorted list of value-tuples, which is
+ * what a single SQL `GROUP BY` hands you. (B) is for ragged/precomputed trees.
+ */
+
+import { hierarchy } from "d3-hierarchy";
+
+/** Field on every node.data. `value` is the node's own key-value (e.g. "2024"),
+ * NOT a count — counts live on `node.count`.
+ * @typedef {{key: string|null, value: any, label: string, row: any}} NodeDatum */
+
+// A separator that cannot occur inside a key or a value. Written as an ESCAPE,
+// never as a literal NUL byte: a raw \0 in the source makes the whole file look
+// like binary data, and grep silently reports no matches in it. That cost an hour.
+const PATH_SEP = "\u0000";
+
+/**
+ * The id of a path — the ONE place it is spelled.
+ *
+ * `fisheyeNav` used to build the selected id by joining with a space while the
+ * rows joined with PATH_SEP, so a selection deeper than one level could never
+ * match a row: selecting a DAY never highlighted it, and never labelled it. It
+ * hid because the only test selected a depth-1 path, where the two joins produce
+ * the same string.
+ */
+export const idOfPath = (path) =>
+  path.map((p) => p.key + "=" + p.value).join(PATH_SEP);
+
+/**
+ * Roll a flat, pre-sorted row list up into a nested tree, preserving the row
+ * order as the child order at every level. Order matters: the host (AutoGallery)
+ * hands us rows already sorted the way its feed is sorted, and the navigator
+ * must mirror that exactly — so we never re-sort, we just group.
+ */
+function rollup(rows, keys, valueOf, countOf) {
+  const root = { key: null, value: null, children: [], row: null };
+  const byPath = new Map([["", root]]);
+
+  for (const row of rows) {
+    let node = root;
+    let path = "";
+    for (const key of keys) {
+      const value = valueOf(row, key);
+      path += PATH_SEP + key + "=" + value;
+      let child = byPath.get(path);
+      if (!child) {
+        child = { key, value, children: [], row: null };
+        byPath.set(path, child);
+        node.children.push(child);
+      }
+      node = child;
+    }
+    // `node` is now the leaf for this row's key-tuple. Several rows can land on
+    // the same leaf; their counts add up and the last row wins as the exemplar.
+    node.row = row;
+    node.ownCount = (node.ownCount ?? 0) + countOf(row);
+  }
+  return root;
+}
+
+/**
+ * Give every internal node a synthetic HEADER pseudo-leaf as its first child.
+ *
+ * This is what makes the flat (indented outline) view possible without a second
+ * layout engine. The layout distributes pixels over the LEAF axis, and a
+ * parent's band is exactly the span of its children — so there is no vertical
+ * space anywhere for a parent's own label to live. In an icicle that's fine (the
+ * parent owns a column); in a flat list it means an internal node has no row,
+ * and with nothing to indent relative to, "indent by level" says nothing.
+ *
+ * A header cell costs one slot on the leaf axis and carries `count: 0`, so mass
+ * conservation is untouched, and it sits INSIDE its parent's interval, so
+ * containment is untouched. Every downstream stage needs zero changes.
+ */
+function withHeaders(raw, childrenOf, isRoot = true) {
+  const kids = childrenOf(raw);
+  if (!kids?.length) return raw;
+  const nested = kids.map((k) => withHeaders(k, childrenOf, false));
+  // The root is never drawn (depth 0), so a header for it would surface as a
+  // stray depth-1 row labelled with nothing.
+  if (isRoot) return { ...raw, children: nested };
+  return {
+    ...raw,
+    children: [{ __header: true, __of: raw, children: null }, ...nested],
+  };
+}
+
+/** Depth-first, in child order. */
+function walk(node, visit) {
+  visit(node);
+  if (node.children) for (const c of node.children) walk(c, visit);
+}
+
+/**
+ * Decorate a d3.hierarchy in place with everything the layouts and renderers
+ * need, so neither has to re-derive it:
+ *   node.count      photo mass (leaf: from the data; internal: sum of children)
+ *   node.leafStart  index of its first descendant leaf   } the interval the
+ *   node.leafEnd    index past its last descendant leaf  } fisheye distorts
+ *   node.path       [{key, value}, …] from the root down to this node
+ *   node.id         stable string id (survives relayout; keys the DOM)
+ *   node.label      display string
+ *
+ * `leafStart`/`leafEnd` are the load-bearing bit of the redesign: once every
+ * node owns a LEAF INTERVAL, a parent's band is just the union of its children's
+ * bands, and "parents contain their children" stops being something a renderer
+ * has to be careful about and becomes true by construction.
+ */
+function decorate(root, labelOf) {
+  const leaves = [];
+  walk(root, (n) => {
+    if (!n.children?.length) leaves.push(n);
+  });
+
+  leaves.forEach((leaf, i) => {
+    leaf.leafStart = i;
+    leaf.leafEnd = i + 1;
+  });
+
+  // Pre-order: a node's path extends its PARENT's, so parents go first.
+  root.eachBefore((n) => {
+    const d = n.data;
+    // Coerce here, once. A host's `label` accessor is arbitrary user code and
+    // may well return undefined for a key it doesn't know about (an unknown
+    // dimension, the synthetic root's null key). The renderer must never be the
+    // place that discovers this — a widget that throws because a consumer's
+    // accessor came back empty is a broken widget.
+    n.label = String(labelOf(d.value, d.key, n) ?? d.value ?? "");
+    if (d.header) {
+      // A header stands in for its parent: same path (so clicking it selects the
+      // parent, which is what you mean when you click "2024"), distinct id.
+      n.keyPath = n.parent.keyPath;
+      n.id = n.parent.id + "#header";
+      return;
+    }
+    // `keyPath`, NOT `path` — d3's HierarchyNode already has a `.path(target)`
+    // method, and an own property would silently shadow it.
+    n.keyPath =
+      n.depth === 0
+        ? []
+        : [...n.parent.keyPath, { key: d.key, value: d.value }];
+    n.id = idOfPath(n.keyPath);
+  });
+
+  // Post-order: a node's count and leaf interval aggregate its CHILDREN's, so
+  // children go first.
+  root.eachAfter((n) => {
+    if (!n.children?.length) {
+      n.count = n.data.ownCount ?? n.data.count ?? 0;
+      return;
+    }
+    n.count = 0;
+    n.leafStart = Infinity;
+    n.leafEnd = -Infinity;
+    for (const c of n.children) {
+      n.count += c.count;
+      if (c.leafStart < n.leafStart) n.leafStart = c.leafStart;
+      if (c.leafEnd > n.leafEnd) n.leafEnd = c.leafEnd;
+    }
+  });
+
+  root.leaves_ = leaves;
+  return root;
+}
+
+const defaultLabel = (value) => (value == null ? "" : String(value));
+
+/**
+ * Normalize either input shape into one decorated hierarchy.
+ *
+ * @param {object} spec
+ * @param {any[]} [spec.data]      flat, pre-sorted rows (shape A)
+ * @param {string[]} [spec.keys]   the levels, outermost first (shape A)
+ * @param {any} [spec.root]        a nested tree (shape B)
+ * @param {(d:any)=>any[]} [spec.children]  child accessor (shape B)
+ * @param {(row:any, key:string)=>any} [spec.value]  how to read a key off a row
+ * @param {(d:any)=>number} [spec.count]    leaf mass; defaults to `d.count ?? 1`
+ * @param {(value:any, key:string, node:any)=>string} [spec.label]
+ * @returns {import("d3-hierarchy").HierarchyNode<NodeDatum> & {leaves_: any[]}}
+ */
+export function normalize(spec = {}) {
+  const {
+    data,
+    keys,
+    root: treeRoot,
+    children = (d) => d.children,
+    value = (row, key) => row[key],
+    count = (d) => d.count ?? 1,
+    label = defaultLabel,
+    headers = false,
+  } = spec;
+
+  const maybeHeaders = (raw, childrenOf) =>
+    headers ? withHeaders(raw, childrenOf) : raw;
+
+  let root;
+  if (treeRoot != null) {
+    root = hierarchy(maybeHeaders(treeRoot, children), (d) =>
+      headers ? d.children : children(d),
+    );
+    // Shape B nodes carry their own key/value/count; mirror them onto the
+    // NodeDatum contract so `decorate` and the renderers stay shape-agnostic.
+    root.each((n) => {
+      const d = n.data ?? {};
+      const of = d.__header ? d.__of : d;
+      n.data = {
+        key: of.key ?? null,
+        value: of.value ?? of.name ?? of.id ?? null,
+        row: of,
+        header: !!d.__header,
+        ownCount: d.__header ? 0 : n.children?.length ? undefined : count(of),
+      };
+    });
+  } else if (Array.isArray(data) && Array.isArray(keys)) {
+    root = hierarchy(
+      maybeHeaders(rollup(data, keys, value, count), (d) => d.children),
+      (d) => d.children,
+    );
+    if (headers) {
+      root.each((n) => {
+        if (!n.data.__header) return;
+        const of = n.data.__of;
+        n.data = {
+          key: of.key,
+          value: of.value,
+          row: of.row,
+          header: true,
+          ownCount: 0,
+        };
+      });
+    }
+  } else {
+    // An empty widget is a normal state (no library loaded yet), not an error.
+    root = hierarchy({ key: null, value: null, children: [], ownCount: 0 });
+  }
+
+  return decorate(root, label);
+}
+
+/** The ordered leaf list — the sequence the fisheye lens distorts. */
+export function leavesOf(root) {
+  return root.leaves_ ?? root.leaves();
+}
+
+/** Every node except the synthetic root, in depth-first (visual) order. */
+export function nodesOf(root) {
+  const out = [];
+  walk(root, (n) => {
+    if (n.depth > 0) out.push(n);
+  });
+  return out;
+}

package/src/index.js

@@ -0,0 +1,18 @@
+export { fisheyeNav, fisheyeNav as default } from "./fisheyeNav.js";
+export { normalize, leavesOf, nodesOf } from "./hierarchy.js";
+export {
+  layout,
+  LAYOUTS,
+  LAYOUT_DEFAULTS,
+  selectAll,
+  selectDOI,
+  doiScore,
+  leafDistance,
+  fisheyePosition,
+  basePositions,
+  distort,
+  slotAtPixel,
+  buildRows,
+  makeBarScale,
+} from "./layout/index.js";
+export { STYLES } from "./render/index.js";