data-navigator 2.4.1 → 3.2.0

package/dist/index.js

@@ -17,6 +17,28 @@ var __spreadValues = (a, b) => {
   return a;
 };
 var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __accessCheck = (obj, member, msg) => {
+  if (!member.has(obj))
+    throw TypeError("Cannot " + msg);
+};
+var __privateGet = (obj, member, getter) => {
+  __accessCheck(obj, member, "read from private field");
+  return getter ? getter.call(obj) : member.get(obj);
+};
+var __privateAdd = (obj, member, value) => {
+  if (member.has(obj))
+    throw TypeError("Cannot add the same private member more than once");
+  member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+};
+var __privateSet = (obj, member, value, setter) => {
+  __accessCheck(obj, member, "write to private field");
+  setter ? setter.call(obj, value) : member.set(obj, value);
+  return value;
+};
+var __privateMethod = (obj, member, method) => {
+  __accessCheck(obj, member, "access private method");
+  return method;
+};
 var __async = (__this, __arguments, generator) => {
   return new Promise((resolve, reject) => {
     var fulfilled = (value) => {
@@ -55,12 +77,12 @@ var defaultKeyBindings = {
   ArrowDown: "down",
   Period: "forward",
   Comma: "backward",
-  Escape: "parent",
-  Enter: "child"
+  Escape: "drill-out",
+  Enter: "drill-in"
 };
-var TypicallyUnreservedKeys = ["KeyW", "KeyJ", "LeftBracket", "RightBracket", "Slash", "Backslash"];
+var TypicallyUnreservedKeys = ["KeyW", "KeyJ", "BracketLeft", "BracketRight", "Slash", "Backslash"];
 var TypicallyUnreservedKeyPairs = [
-  ["LeftBracket", "RightBracket"],
+  ["BracketLeft", "BracketRight"],
   ["Slash", "Backslash"]
 ];
 var GenericFullNavigationRules = {
@@ -80,11 +102,11 @@ var GenericFullNavigationRules = {
     key: "ArrowDown",
     direction: "target"
   },
-  child: {
+  "drill-in": {
     key: "Enter",
     direction: "target"
   },
-  parent: {
+  "drill-out": {
     key: "Backspace",
     direction: "source"
   },
@@ -140,11 +162,11 @@ var GenericLimitedNavigationRules = {
     key: "ArrowUp",
     direction: "source"
   },
-  child: {
+  "drill-in": {
     key: "Enter",
     direction: "target"
   },
-  parent: {
+  "drill-out": {
     key: "Backspace",
     direction: "source"
   },
@@ -187,6 +209,47 @@ var NodeElementDefaults = {
     spatialProperties: void 0
   }
 };
+var KeyLabels = {
+  ArrowLeft: "\u2190",
+  ArrowRight: "\u2192",
+  ArrowUp: "\u2191",
+  ArrowDown: "\u2193",
+  Enter: "Enter",
+  Backspace: "Backspace",
+  Escape: "Esc",
+  Space: "Space",
+  Tab: "Tab",
+  BracketLeft: "[",
+  BracketRight: "]",
+  Backslash: "\\",
+  Slash: "/",
+  Comma: ",",
+  Period: ".",
+  Semicolon: ";",
+  Quote: "'",
+  Minus: "-",
+  Equal: "="
+};
+var GenericNavigationRuleCommands = {
+  "drill-in": { label: "Enter", description: "Drill in" },
+  "drill-out": { label: "Backspace", description: "Drill out" },
+  exit: { label: "Esc", description: "Exit" },
+  left: { label: "\u2190", description: "Previous data point" },
+  right: { label: "\u2192", description: "Next data point" },
+  up: { label: "\u2191", description: "Previous data point" },
+  down: { label: "\u2193", description: "Next data point" },
+  backward: { label: ",", description: "Move backward" },
+  forward: { label: ".", description: "Move forward" },
+  previous: { label: ";", description: "Previous" },
+  next: { label: "'", description: "Next" },
+  undo: { label: "Z", description: "Undo" },
+  help: { label: "Y", description: "Help" },
+  legend: { label: "L", description: "Legend" }
+};
+var commandsTableDefaultColumns = [
+  { label: "Command", id: "description" },
+  { label: "Key", id: "label" }
+];
 
 // src/utilities.ts
 var describeNode = (d, descriptionOptions) => {
@@ -201,6 +264,422 @@ var describeNode = (d, descriptionOptions) => {
 var createValidId = (s) => {
   return "_" + s.replace(/[^a-zA-Z0-9_-]+/g, "_");
 };
+var keyLabel = (code) => {
+  if (!code)
+    return "";
+  return KeyLabels[code] || code.replace(/^Key/, "").replace(/^Digit/, "");
+};
+var humanizeRule = (navId) => {
+  const text = navId.replace(/[-_]+/g, " ").trim();
+  return text.charAt(0).toUpperCase() + text.slice(1);
+};
+function getGenericCommandsFromNavRules(navigationRules, descriptions) {
+  if (!navigationRules) {
+    return [];
+  }
+  return Object.keys(navigationRules).map((navId) => {
+    const rule = navigationRules[navId];
+    const generic = GenericNavigationRuleCommands[navId];
+    return {
+      label: (rule == null ? void 0 : rule.key) ? keyLabel(rule.key) : (generic == null ? void 0 : generic.label) || "",
+      description: (descriptions == null ? void 0 : descriptions[navId]) || (generic == null ? void 0 : generic.description) || humanizeRule(navId),
+      command: navId
+    };
+  });
+}
+
+// src/edge-utils.ts
+var makeEdgeCreator = (nodes, edges, useDirectedEdges) => {
+  const addEdgeToNode = (nodeId, edgeId) => {
+    const node = nodes[nodeId];
+    if (!node) {
+      console.error(`Building edges. Node ${nodeId} does not exist, so edge ${edgeId} was not added to it.`);
+      return;
+    }
+    if (!node.edges) {
+      node.edges = [];
+    }
+    if (node.edges.indexOf(edgeId) === -1) {
+      node.edges.push(edgeId);
+    }
+  };
+  return (source, target, rules, addTo) => {
+    if (!source || !target || source === target) {
+      return;
+    }
+    const id = `${source}-${target}`;
+    const targetId = !useDirectedEdges ? id : `${target}-${id}`;
+    const addToSource = !addTo || addTo === "source";
+    const addToTarget = !addTo || addTo === "target";
+    const checkEdgeRules = (eId) => {
+      if (edges[eId]) {
+        (rules || []).forEach((r) => {
+          if (edges[eId].navigationRules.indexOf(r) === -1) {
+            edges[eId].navigationRules.push(r);
+          }
+        });
+      } else {
+        edges[eId] = {
+          source,
+          target,
+          navigationRules: rules ? [...rules] : []
+        };
+      }
+    };
+    checkEdgeRules(id);
+    if (useDirectedEdges && addToTarget) {
+      checkEdgeRules(targetId);
+    }
+    if (addToSource) {
+      addEdgeToNode(source, id);
+    }
+    if (addToTarget) {
+      addEdgeToNode(target, targetId);
+    }
+  };
+};
+var chain = (createEdge, ids, rules, extents = "terminal") => {
+  for (let i = 0; i < ids.length - 1; i++) {
+    createEdge(ids[i], ids[i + 1], rules);
+  }
+  if (extents === "circular" && ids.length > 1) {
+    createEdge(ids[ids.length - 1], ids[0], rules);
+  }
+};
+
+// src/frame.ts
+var prepareFrameOptions = (options) => {
+  var _a, _b, _c;
+  const f = options.frame;
+  const dimCount = ((_b = (_a = options.dimensions) == null ? void 0 : _a.values) == null ? void 0 : _b.length) || 0;
+  if (!f || dimCount < 2 || ((_c = options.dimensions.parentOptions) == null ? void 0 : _c.addLevel0)) {
+    return options;
+  }
+  const data = f.data || { id: "data", edges: [], semantics: { label: "Data" } };
+  return __spreadProps(__spreadValues({}, options), {
+    dimensions: __spreadProps(__spreadValues({}, options.dimensions), {
+      parentOptions: __spreadProps(__spreadValues({}, options.dimensions.parentOptions || {}), {
+        addLevel0: __spreadProps(__spreadValues({}, data), { edges: data.edges || [] })
+      })
+    })
+  });
+};
+var buildFrame = (options, nodes, edges, topId) => {
+  var _a, _b, _c;
+  const f = options.frame;
+  if (!f)
+    return;
+  if (!topId || !nodes[topId]) {
+    console.error("Building frame. No top data node was found to place under the frame.");
+    return;
+  }
+  const createEdge = makeEdgeCreator(nodes, edges, options.useDirectedEdges);
+  const siblingRules = ((_a = f.navigationRules) == null ? void 0 : _a.sibling_sibling) || ["left", "right"];
+  const parentRules = ((_b = f.navigationRules) == null ? void 0 : _b.parent_child) || ["drill-out", "drill-in"];
+  const extents = ((_c = f.behavior) == null ? void 0 : _c.extents) || "circular";
+  const root = f.root;
+  nodes[root.id] = __spreadProps(__spreadValues({}, root), { edges: [...root.edges || []], depth: 0, frameRole: "root" });
+  const elementIds = (f.elements || []).map((e) => {
+    nodes[e.id] = __spreadProps(__spreadValues({}, e), {
+      edges: [...e.edges || []],
+      depth: 1,
+      parentId: root.id,
+      frameRole: "element"
+    });
+    return e.id;
+  });
+  let dataId = topId;
+  if (f.data && f.data.id !== topId) {
+    nodes[f.data.id] = __spreadProps(__spreadValues({}, f.data), { edges: [...f.data.edges || []] });
+    createEdge(f.data.id, topId, parentRules, "source");
+    createEdge(f.data.id, topId, parentRules, "target");
+    nodes[topId].parentId = f.data.id;
+    dataId = f.data.id;
+  }
+  const dataNode = nodes[dataId];
+  dataNode.frameRole = "data";
+  dataNode.depth = 1;
+  dataNode.parentId = root.id;
+  const children = [...elementIds, dataId];
+  createEdge(root.id, children[0], parentRules, "source");
+  children.forEach((c) => createEdge(root.id, c, parentRules, "target"));
+  chain(createEdge, children, siblingRules, extents);
+  return { rootId: root.id, elementIds, dataId, parentRules };
+};
+
+// src/spatial-grid.ts
+var buildSpatialGrid = (options, nodes, edges) => {
+  var _a, _b, _c;
+  const g = options.spatialGrid;
+  if (!g)
+    return;
+  const createEdge = makeEdgeCreator(nodes, edges, options.useDirectedEdges);
+  const xRules = ((_a = g.navigationRules) == null ? void 0 : _a.x) || ["left", "right"];
+  const yRules = ((_b = g.navigationRules) == null ? void 0 : _b.y) || ["up", "down"];
+  const parentRules = ((_c = g.navigationRules) == null ? void 0 : _c.parent_child) || ["drill-out", "drill-in"];
+  const extents = g.extents || "terminal";
+  const across = g.levelNavigation !== "within";
+  const skipEmpty = g.skipEmpty !== false;
+  const leafMode = g.leaves || "points";
+  const idOf = (d) => d[typeof options.idKey === "function" ? options.idKey(d) : options.idKey];
+  const rows = options.data.filter((d) => typeof d[g.xKey] === "number" && typeof d[g.yKey] === "number");
+  const ext = (key, given) => {
+    if (given)
+      return given;
+    let min = Infinity;
+    let max = -Infinity;
+    rows.forEach((d) => {
+      min = Math.min(min, d[key]);
+      max = Math.max(max, d[key]);
+    });
+    return [min, max];
+  };
+  const xExtent = ext(g.xKey, g.xExtent);
+  const yExtent = ext(g.yKey, g.yExtent);
+  const indexOf = (v, [lo, hi], n) => {
+    if (hi === lo)
+      return 0;
+    return Math.max(0, Math.min(n - 1, Math.floor((v - lo) / (hi - lo) * n)));
+  };
+  const rootDefaults = { id: "grid", edges: [], semantics: { label: "Grid" } };
+  const root = __spreadValues(__spreadValues({}, rootDefaults), g.root || {});
+  root.edges = root.edges || [];
+  root.depth = 0;
+  root.data = __spreadProps(__spreadValues({}, root.data || {}), {
+    xKey: g.xKey,
+    yKey: g.yKey,
+    xExtent,
+    yExtent,
+    levels: g.levels,
+    count: rows.length
+  });
+  nodes[root.id] = root;
+  const cellId = (level, col, row) => g.cellIds ? g.cellIds(level, col, row) : createValidId(`${root.id}_L${level}_${col}_${row}`);
+  const cellsByLevel = [];
+  g.levels.forEach((n, level) => {
+    const cells = {};
+    const add = (col, row) => {
+      const key = `${col}_${row}`;
+      if (cells[key])
+        return cells[key];
+      const id = cellId(level, col, row);
+      const xStep = (xExtent[1] - xExtent[0]) / n;
+      const yStep = (yExtent[1] - yExtent[0]) / n;
+      let parent = root.id;
+      if (level > 0) {
+        const pn = g.levels[level - 1];
+        const parentCell = cellsByLevel[level - 1][`${Math.floor(col * pn / n)}_${Math.floor(row * pn / n)}`];
+        parent = parentCell == null ? void 0 : parentCell.id;
+        parentCell == null ? void 0 : parentCell.children.push(id);
+      }
+      cells[key] = { id, col, row, parent, children: [] };
+      nodes[id] = {
+        id,
+        renderId: id,
+        edges: [],
+        depth: level + 1,
+        parentId: parent,
+        data: {
+          level,
+          col,
+          row,
+          cellsPerAxis: n,
+          xExtent: [xExtent[0] + col * xStep, xExtent[0] + (col + 1) * xStep],
+          yExtent: [yExtent[0] + row * yStep, yExtent[0] + (row + 1) * yStep],
+          count: 0
+        }
+      };
+      return cells[key];
+    };
+    if (!skipEmpty) {
+      for (let c = 0; c < n; c++)
+        for (let r = 0; r < n; r++)
+          add(c, r);
+    }
+    rows.forEach((d) => add(indexOf(d[g.xKey], xExtent, n), indexOf(d[g.yKey], yExtent, n)));
+    cellsByLevel.push(cells);
+  });
+  const finest = cellsByLevel[cellsByLevel.length - 1];
+  const fn = g.levels[g.levels.length - 1];
+  const leafIds = [];
+  const leafParent = {};
+  rows.forEach((d) => {
+    const id = idOf(d);
+    if (!nodes[id])
+      return;
+    g.levels.forEach((n, level) => {
+      const c = cellsByLevel[level][`${indexOf(d[g.xKey], xExtent, n)}_${indexOf(d[g.yKey], yExtent, n)}`];
+      nodes[c.id].data.count++;
+    });
+    const cell = finest[`${indexOf(d[g.xKey], xExtent, fn)}_${indexOf(d[g.yKey], yExtent, fn)}`];
+    cell.children.push(id);
+    leafParent[id] = cell.id;
+    leafIds.push(id);
+    nodes[id].parentId = cell.id;
+    nodes[id].depth = g.levels.length + 1;
+  });
+  const topLeftFirst = (a, b) => b.row - a.row || a.col - b.col;
+  const rootChildren = Object.values(cellsByLevel[0]).sort(topLeftFirst);
+  if (rootChildren.length)
+    createEdge(root.id, rootChildren[0].id, parentRules, "source");
+  rootChildren.forEach((c) => createEdge(root.id, c.id, parentRules, "target"));
+  const pos = (id) => nodes[id].data;
+  cellsByLevel.forEach((cells, level) => {
+    Object.values(cells).forEach((c) => {
+      if (!c.children.length)
+        return;
+      let first;
+      if (level === cellsByLevel.length - 1) {
+        first = [...c.children].sort((a, b) => leafOrderX(a, b))[0];
+      } else {
+        first = [...c.children].sort((a, b) => topLeftFirst(pos(a), pos(b)))[0];
+      }
+      createEdge(c.id, first, parentRules, "source");
+      c.children.forEach((k) => createEdge(c.id, k, parentRules, "target"));
+    });
+  });
+  const linkCells = (ids) => {
+    const byRow = {};
+    const byCol = {};
+    ids.forEach((id) => {
+      const p = pos(id);
+      (byRow[p.row] = byRow[p.row] || []).push(id);
+      (byCol[p.col] = byCol[p.col] || []).push(id);
+    });
+    Object.values(byRow).forEach(
+      (r) => chain(
+        createEdge,
+        r.sort((a, b) => pos(a).col - pos(b).col),
+        xRules,
+        extents
+      )
+    );
+    Object.values(byCol).forEach(
+      (c) => chain(
+        createEdge,
+        c.sort((a, b) => pos(b).row - pos(a).row),
+        yRules,
+        extents
+      )
+    );
+  };
+  cellsByLevel.forEach((cells, level) => {
+    const list = Object.values(cells);
+    if (across || level === 0) {
+      linkCells(list.map((c) => c.id));
+    } else {
+      const groups = {};
+      list.forEach((c) => (groups[c.parent] = groups[c.parent] || []).push(c.id));
+      Object.values(groups).forEach(linkCells);
+    }
+  });
+  function leafOrderX(a, b) {
+    const da = nodes[a].data;
+    const db = nodes[b].data;
+    return da[g.xKey] - db[g.xKey] || db[g.yKey] - da[g.yKey];
+  }
+  const leafOrderY = (a, b) => {
+    const da = nodes[a].data;
+    const db = nodes[b].data;
+    return db[g.yKey] - da[g.yKey] || da[g.xKey] - db[g.xKey];
+  };
+  const linkLeaves = (ids) => {
+    if (leafMode === "cells") {
+      const byY = {};
+      const byX = {};
+      ids.forEach((id) => {
+        const d = nodes[id].data;
+        (byY[d[g.yKey]] = byY[d[g.yKey]] || []).push(id);
+        (byX[d[g.xKey]] = byX[d[g.xKey]] || []).push(id);
+      });
+      Object.values(byY).forEach((r) => chain(createEdge, r.sort(leafOrderX), xRules, extents));
+      Object.values(byX).forEach((c) => chain(createEdge, c.sort(leafOrderY), yRules, extents));
+    } else {
+      chain(createEdge, [...ids].sort(leafOrderX), xRules, extents);
+      chain(createEdge, [...ids].sort(leafOrderY), yRules, extents);
+    }
+  };
+  if (across) {
+    linkLeaves(leafIds);
+  } else {
+    Object.values(finest).forEach((c) => linkLeaves(c.children));
+  }
+  return {
+    rootId: root.id,
+    levels: g.levels,
+    cellsByLevel: cellsByLevel.map((cells) => Object.values(cells).map((c) => c.id)),
+    leafIds,
+    parentRules
+  };
+};
+
+// src/hierarchy.ts
+var buildHierarchy = (options, nodes, edges) => {
+  var _a, _b;
+  const h = options.hierarchy;
+  if (!h)
+    return;
+  const createEdge = makeEdgeCreator(nodes, edges, options.useDirectedEdges);
+  const siblingRules = ((_a = h.navigationRules) == null ? void 0 : _a.sibling_sibling) || ["left", "right"];
+  const parentRules = ((_b = h.navigationRules) == null ? void 0 : _b.parent_child) || ["drill-out", "drill-in"];
+  const extents = h.extents || "circular";
+  const idOf = (d) => d[typeof options.idKey === "function" ? options.idKey(d) : options.idKey];
+  const children = {};
+  let rootId;
+  options.data.forEach((d) => {
+    const id = idOf(d);
+    const parent = d[h.parentKey];
+    if (parent === void 0 || parent === null || parent === "") {
+      if (rootId) {
+        console.error(
+          `Building hierarchy. More than one root was found: ${rootId} and ${id}. Using ${rootId}.`
+        );
+        return;
+      }
+      rootId = id;
+    } else {
+      if (!children[parent])
+        children[parent] = [];
+      children[parent].push(d);
+    }
+  });
+  if (!rootId) {
+    console.error("Building hierarchy. No root row was found. One row must have an empty parent.");
+    return;
+  }
+  const byDepth = [];
+  const visit = (id, parentId, depth) => {
+    const node = nodes[id];
+    if (!node) {
+      console.error(`Building hierarchy. Row ${id} has no node. Check idKey.`);
+      return;
+    }
+    node.depth = depth;
+    if (parentId)
+      node.parentId = parentId;
+    if (!byDepth[depth])
+      byDepth[depth] = [];
+    byDepth[depth].push(id);
+    let kids = children[id] || [];
+    if (h.sortFunction)
+      kids = [...kids].sort((a, b) => h.sortFunction(a, b));
+    const kidIds = kids.map(idOf);
+    node.childCount = kidIds.length;
+    if (kidIds.length) {
+      createEdge(id, kidIds[0], parentRules, "source");
+      kidIds.forEach((k) => createEdge(id, k, parentRules, "target"));
+      if (h.levelNavigation !== "across") {
+        chain(createEdge, kidIds, siblingRules, extents);
+      }
+    }
+    kidIds.forEach((k) => visit(k, id, depth + 1));
+  };
+  visit(rootId, void 0, 0);
+  if (h.levelNavigation === "across") {
+    byDepth.forEach((ids) => chain(createEdge, ids, siblingRules, extents));
+  }
+  return { rootId, depthCount: byDepth.length, parentRules };
+};
 
 // src/structure.ts
 var structure_default = (options) => {
@@ -277,7 +756,7 @@ var buildNodeStructureFromVegaLite = (options) => {
           edges[firstChildEdge] = {
             source: node.id,
             target: firstChildId,
-            navigationRules: ["parent", "child"]
+            navigationRules: ["drill-out", "drill-in"]
           };
         }
       }
@@ -290,7 +769,7 @@ var buildNodeStructureFromVegaLite = (options) => {
           edges[parentEdge] = {
             source: parentId,
             target: node.id,
-            navigationRules: ["parent", "child"]
+            navigationRules: ["drill-out", "drill-in"]
           };
         }
       }
@@ -491,7 +970,7 @@ var scaffoldDimensions = (options, nodes) => {
               },
               navigationRules: dim.navigationRules || {
                 sibling_sibling: rules.length ? [...rules.shift()] : ["previous_" + dim.dimensionKey, "next_" + dim.dimensionKey],
-                parent_child: ["parent_" + dim.dimensionKey, "child"]
+                parent_child: ["drill-out_" + dim.dimensionKey, "drill-in"]
               }
             };
             nodes[id2] = {
@@ -678,9 +1157,9 @@ var scaffoldDimensions = (options, nodes) => {
   }
   return dimensions;
 };
-var buildEdges = (options, nodes, dimensions) => {
+var buildEdges = (options, nodes, dimensions, existingEdges) => {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j;
-  let edges = {};
+  let edges = existingEdges || {};
   const addEdgeToNode = (nodeId, edgeId) => {
     if (nodes[nodeId].edges.indexOf(edgeId) === -1) {
       nodes[nodeId].edges.push(edgeId);
@@ -721,7 +1200,7 @@ var buildEdges = (options, nodes, dimensions) => {
     let po = ((_d = options.dimensions) == null ? void 0 : _d.parentOptions) || {};
     let extents = ((_f = (_e = po.level1Options) == null ? void 0 : _e.behavior) == null ? void 0 : _f.extents) || "terminal";
     let level0 = po.addLevel0;
-    let parentRules = level0 ? ((_h = (_g = po.level1Options) == null ? void 0 : _g.navigationRules) == null ? void 0 : _h.parent_child) || ["parent", "child"] : [];
+    let parentRules = level0 ? ((_h = (_g = po.level1Options) == null ? void 0 : _g.navigationRules) == null ? void 0 : _h.parent_child) || ["drill-out", "drill-in"] : [];
     let siblingRules = ((_j = (_i = po.level1Options) == null ? void 0 : _i.navigationRules) == null ? void 0 : _j.sibling_sibling) || ["left", "right"];
     let firstLevel1Node = typeof order[0] === "string" ? hasOrder ? nodes[order[0]] : nodes[dimensions[order[0]].nodeId] : order[0];
     if (level0) {
@@ -754,7 +1233,7 @@ var buildEdges = (options, nodes, dimensions) => {
         createEdge(level1Node.id, nextLevel1Node.id, siblingRules);
       }
       if (!l && extents === "bridgedCustom") {
-        createEdge(po.level1Options.behavior.customBridgePost, level1Node.id, siblingRules);
+        createEdge(po.level1Options.behavior.customBridgePrevious, level1Node.id, siblingRules);
       }
       l++;
     });
@@ -941,7 +1420,7 @@ var buildEdges = (options, nodes, dimensions) => {
   return edges;
 };
 var buildRules = (options, edges, dimensions) => {
-  var _a, _b, _c, _d;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r;
   let rules = options.navigationRules;
   if (!rules) {
     let dimKeys = Object.keys(dimensions || {});
@@ -1033,8 +1512,8 @@ var buildRules = (options, edges, dimensions) => {
     if (dimKeys.length) {
       if ((_b = (_a = options.dimensions) == null ? void 0 : _a.parentOptions) == null ? void 0 : _b.addLevel0) {
         let rules2 = ((_d = (_c = options.dimensions.parentOptions.level1Options) == null ? void 0 : _c.navigationRules) == null ? void 0 : _d.parent_child) || [
-          "parent",
-          "child"
+          "drill-out",
+          "drill-in"
         ];
         checkKeys(rules2[0], rules2[1]);
       }
@@ -1045,6 +1524,20 @@ var buildRules = (options, edges, dimensions) => {
         checkKeys(ss[0], ss[1]);
       });
     }
+    const extraPairs = [
+      (_f = (_e = options.frame) == null ? void 0 : _e.navigationRules) == null ? void 0 : _f.parent_child,
+      (_h = (_g = options.frame) == null ? void 0 : _g.navigationRules) == null ? void 0 : _h.sibling_sibling,
+      (_j = (_i = options.spatialGrid) == null ? void 0 : _i.navigationRules) == null ? void 0 : _j.x,
+      (_l = (_k = options.spatialGrid) == null ? void 0 : _k.navigationRules) == null ? void 0 : _l.y,
+      (_n = (_m = options.spatialGrid) == null ? void 0 : _m.navigationRules) == null ? void 0 : _n.parent_child,
+      (_p = (_o = options.hierarchy) == null ? void 0 : _o.navigationRules) == null ? void 0 : _p.parent_child,
+      (_r = (_q = options.hierarchy) == null ? void 0 : _q.navigationRules) == null ? void 0 : _r.sibling_sibling
+    ];
+    extraPairs.forEach((pair) => {
+      if (pair && !used[pair[0]] && !used[pair[1]]) {
+        checkKeys(pair[0], pair[1]);
+      }
+    });
     Object.keys(edges).forEach((e) => {
       edges[e].navigationRules.forEach((rule) => {
         if (!used[rule]) {
@@ -1079,20 +1572,38 @@ var buildRules = (options, edges, dimensions) => {
   }
   return rules;
 };
-var buildStructure = (options) => {
-  if (options.addIds) {
-    addSimpleDataIDs(options);
+var buildStructure = (inputOptions) => {
+  var _a, _b, _c;
+  if (inputOptions.addIds) {
+    addSimpleDataIDs(inputOptions);
   }
+  const options = prepareFrameOptions(inputOptions);
   let nodes = buildNodes(options);
   let dimensions = scaffoldDimensions(options, nodes);
-  let edges = buildEdges(options, nodes, dimensions);
+  let edges = {};
+  const spatialGrid = buildSpatialGrid(options, nodes, edges);
+  const hierarchy = buildHierarchy(options, nodes, edges);
+  let frame;
+  if (options.frame) {
+    const dimKeys = Object.keys(dimensions || {});
+    const topId = (spatialGrid == null ? void 0 : spatialGrid.rootId) || (hierarchy == null ? void 0 : hierarchy.rootId) || ((_c = (_b = (_a = options.dimensions) == null ? void 0 : _a.parentOptions) == null ? void 0 : _b.addLevel0) == null ? void 0 : _c.id) || (dimKeys.length === 1 ? dimensions[dimKeys[0]].nodeId : void 0);
+    frame = buildFrame(options, nodes, edges, topId);
+  }
+  edges = buildEdges(options, nodes, dimensions, edges);
   let navigationRules = buildRules(options, edges, dimensions);
-  return {
+  const structure = {
     nodes,
     edges,
     dimensions,
     navigationRules
   };
+  if (frame)
+    structure.frame = frame;
+  if (spatialGrid)
+    structure.spatialGrid = spatialGrid;
+  if (hierarchy)
+    structure.hierarchy = hierarchy;
+  return structure;
 };
 
 // src/input.ts
@@ -1190,6 +1701,124 @@ var input_default = (options) => {
   return inputHandler;
 };
 
+// src/commands-table.ts
+var _commands, _columns, _kbdColumn, _connected, _render, render_fn;
+var CommandsTable = class extends HTMLElement {
+  constructor() {
+    super(...arguments);
+    __privateAdd(this, _render);
+    __privateAdd(this, _commands, []);
+    __privateAdd(this, _columns, commandsTableDefaultColumns);
+    __privateAdd(this, _kbdColumn, "label");
+    __privateAdd(this, _connected, false);
+  }
+  static get observedAttributes() {
+    return ["title"];
+  }
+  set commands(value) {
+    __privateSet(this, _commands, value);
+    if (!__privateGet(this, _connected))
+      return;
+    __privateMethod(this, _render, render_fn).call(this);
+  }
+  get commands() {
+    return __privateGet(this, _commands);
+  }
+  set columns(value) {
+    __privateSet(this, _columns, value);
+    if (!__privateGet(this, _connected))
+      return;
+    __privateMethod(this, _render, render_fn).call(this);
+  }
+  get columns() {
+    return __privateGet(this, _columns);
+  }
+  /** Column id whose cells are wrapped in <kbd>. Defaults to 'label'. Set to null to disable. */
+  set kbdColumn(value) {
+    __privateSet(this, _kbdColumn, value);
+    if (!__privateGet(this, _connected))
+      return;
+    __privateMethod(this, _render, render_fn).call(this);
+  }
+  get kbdColumn() {
+    return __privateGet(this, _kbdColumn);
+  }
+  attributeChangedCallback() {
+    if (!__privateGet(this, _connected))
+      return;
+    __privateMethod(this, _render, render_fn).call(this);
+  }
+  connectedCallback() {
+    __privateSet(this, _connected, true);
+    __privateMethod(this, _render, render_fn).call(this);
+  }
+  disconnectedCallback() {
+    __privateSet(this, _connected, false);
+  }
+};
+_commands = new WeakMap();
+_columns = new WeakMap();
+_kbdColumn = new WeakMap();
+_connected = new WeakMap();
+_render = new WeakSet();
+render_fn = function() {
+  this.replaceChildren();
+  const headerCells = [];
+  for (const column of __privateGet(this, _columns)) {
+    const headerCell = document.createElement("th");
+    headerCell.classList.add("dn-commands-table-th");
+    headerCell.textContent = column.label;
+    headerCells.push(headerCell);
+  }
+  const headerRow = document.createElement("tr");
+  headerRow.classList.add("dn-commands-table-thead-tr");
+  for (const headerCell of headerCells) {
+    headerRow.appendChild(headerCell);
+  }
+  const thead = document.createElement("thead");
+  thead.classList.add("dn-commands-table-thead");
+  thead.appendChild(headerRow);
+  const tbody = document.createElement("tbody");
+  tbody.classList.add("dn-commands-table-tbody");
+  for (const command of __privateGet(this, _commands)) {
+    const rowCells = [];
+    for (const column of __privateGet(this, _columns)) {
+      const cellValue = command[column.id];
+      const rowCell = document.createElement("td");
+      rowCell.classList.add("dn-commands-table-td");
+      if (__privateGet(this, _kbdColumn) !== null && column.id === __privateGet(this, _kbdColumn) && cellValue) {
+        const kbd = document.createElement("kbd");
+        kbd.classList.add("dn-commands-table-td-kbd");
+        kbd.textContent = cellValue;
+        rowCell.append(kbd);
+      } else {
+        rowCell.textContent = cellValue;
+      }
+      rowCells.push(rowCell);
+    }
+    const row = document.createElement("tr");
+    row.classList.add("dn-commands-table-tbody-tr");
+    for (const rowCell of rowCells) {
+      row.appendChild(rowCell);
+    }
+    tbody.appendChild(row);
+  }
+  const table = document.createElement("table");
+  table.classList.add("dn-commands-table");
+  const title = this.getAttribute("title");
+  if (title) {
+    const caption = document.createElement("caption");
+    caption.classList.add("dn-commands-table-caption");
+    caption.textContent = title;
+    table.appendChild(caption);
+  } else {
+    table.setAttribute("aria-label", "Commands table");
+  }
+  table.appendChild(thead);
+  table.appendChild(tbody);
+  this.appendChild(table);
+};
+
 // src/rendering.ts
 var rendering_default = (options) => {
   const setActiveDescendant = (e) => {
@@ -1215,7 +1844,7 @@ var rendering_default = (options) => {
     defaults.existingElement = options.defaults.existingElement ? __spreadValues(__spreadValues({}, defaults.existingElement), options.defaults.existingElement) : defaults.existingElement;
   }
   renderer.initialize = () => {
-    var _a;
+    var _a, _b;
     if (initialized) {
       console.error(
         `The renderer wrapper has already been initialized successfully, RenderingOptions.suffixId is: ${options.suffixId}. No further action was taken.`
@@ -1246,6 +1875,9 @@ var rendering_default = (options) => {
     if (options.root && options.root.height) {
       renderer.wrapper.style.height = options.root.height;
     }
+    if ((_a = options.commandsElement) == null ? void 0 : _a.include) {
+      renderer.initializeCommands(options.commandsElement);
+    }
     if (options.entryButton && options.entryButton.include) {
       renderer.entryButton = document.createElement("button");
       renderer.entryButton.id = "dn-entry-button-" + options.suffixId;
@@ -1260,7 +1892,7 @@ var rendering_default = (options) => {
       renderer.wrapper.appendChild(renderer.entryButton);
     }
     renderer.root.appendChild(renderer.wrapper);
-    if ((_a = options.exitElement) == null ? void 0 : _a.include) {
+    if ((_b = options.exitElement) == null ? void 0 : _b.include) {
       renderer.exitElement = document.createElement("div");
       renderer.exitElement.id = "dn-exit-" + options.suffixId;
       renderer.exitElement.classList.add("dn-exit-position");
@@ -1270,17 +1902,17 @@ var rendering_default = (options) => {
       renderer.exitElement.setAttribute("tabindex", "-1");
       renderer.exitElement.style.display = "none";
       renderer.exitElement.addEventListener("focus", (e) => {
-        var _a2, _b;
+        var _a2, _b2;
         renderer.exitElement.style.display = "block";
         renderer.clearStructure();
-        if ((_b = (_a2 = options.exitElement) == null ? void 0 : _a2.callbacks) == null ? void 0 : _b.focus) {
+        if ((_b2 = (_a2 = options.exitElement) == null ? void 0 : _a2.callbacks) == null ? void 0 : _b2.focus) {
           options.exitElement.callbacks.focus(e);
         }
       });
       renderer.exitElement.addEventListener("blur", (e) => {
-        var _a2, _b;
+        var _a2, _b2;
         renderer.exitElement.style.display = "none";
-        if ((_b = (_a2 = options.exitElement) == null ? void 0 : _a2.callbacks) == null ? void 0 : _b.blur) {
+        if ((_b2 = (_a2 = options.exitElement) == null ? void 0 : _a2.callbacks) == null ? void 0 : _b2.blur) {
           options.exitElement.callbacks.blur(e);
         }
       });
@@ -1337,15 +1969,15 @@ var rendering_default = (options) => {
     const attributes = resolveProp("semantics", "attributes");
     if (typeof attributes === "object") {
       Object.keys(attributes).forEach((attribute) => {
-        node.setAttribute(attribute, attributes[attribute]);
+        nodeText.setAttribute(attribute, attributes[attribute]);
       });
     }
     nodeText.setAttribute("role", resolveProp("semantics", "role"));
     nodeText.classList.add("dn-node-text");
+    const label = resolveProp("semantics", "label");
     if (d.showText) {
-      nodeText.innerText = d.semantics.label;
+      nodeText.innerText = label;
     }
-    const label = resolveProp("semantics", "label");
     if (!label) {
       console.error(
         "Accessibility error: a label must be supplied to every rendered element using semantics.label."
@@ -1393,6 +2025,34 @@ var rendering_default = (options) => {
       }
     });
   };
+  renderer.initializeCommands = (commandOptions) => {
+    const root = document.getElementById(commandOptions == null ? void 0 : commandOptions.rootId);
+    if (!root) {
+      console.error("Commands root element not found in document.");
+      return;
+    }
+    const optionsCommands = commandOptions.commands;
+    const genericCommandsFromRules = getGenericCommandsFromNavRules(
+      commandOptions.navigationRules,
+      commandOptions.descriptions
+    );
+    const commands = optionsCommands ? typeof optionsCommands === "function" ? optionsCommands(genericCommandsFromRules) : optionsCommands : genericCommandsFromRules;
+    if (!customElements.get("dn-commands-table")) {
+      customElements.define("dn-commands-table", CommandsTable);
+    }
+    const commandsElement = document.createElement("dn-commands-table");
+    if (commandOptions == null ? void 0 : commandOptions.title) {
+      commandsElement.setAttribute("title", commandOptions.title);
+    }
+    commandsElement.commands = commands;
+    if (commandOptions.columns) {
+      commandsElement.columns = commandOptions.columns;
+    }
+    root.appendChild(commandsElement);
+    return commandsElement;
+  };
+  renderer.getGenericCommandsFromNavRules = getGenericCommandsFromNavRules;
+  renderer.CommandsTable = CommandsTable;
   return renderer;
 };
 
@@ -1567,7 +2227,7 @@ var searchNodes = (query, structure, describeFn, limit = 10) => {
   return results;
 };
 var text_chat_default = (options) => {
-  var _a;
+  var _a, _b, _c, _d;
   const {
     structure,
     container,
@@ -1585,7 +2245,9 @@ var text_chat_default = (options) => {
   if (!rootEl) {
     throw new Error(`textChat: container "${container}" not found`);
   }
-  const resolvedEntryPoint = entryPoint || (structure.dimensions ? (_a = structure.dimensions[Object.keys(structure.dimensions)[0]]) == null ? void 0 : _a.nodeId : Object.keys(structure.nodes)[0]);
+  const level0Id = Object.keys(structure.nodes).find((id) => structure.nodes[id].dimensionLevel === 0);
+  const firstDimensionId = structure.dimensions ? (_a = structure.dimensions[Object.keys(structure.dimensions)[0]]) == null ? void 0 : _a.nodeId : void 0;
+  const resolvedEntryPoint = entryPoint || ((_b = structure.frame) == null ? void 0 : _b.rootId) || level0Id || ((_c = structure.spatialGrid) == null ? void 0 : _c.rootId) || ((_d = structure.hierarchy) == null ? void 0 : _d.rootId) || firstDimensionId || Object.keys(structure.nodes)[0];
   const inputHandler = input_default({
     structure,
     navigationRules: structure.navigationRules || {},
@@ -1949,8 +2611,203 @@ var text_chat_default = (options) => {
   };
 };
 
+// src/geometry.ts
+function grahamScan(points) {
+  if (points.length < 3)
+    return [...points];
+  let pivot = points[0];
+  for (const p of points) {
+    if (p.y < pivot.y || p.y === pivot.y && p.x < pivot.x)
+      pivot = p;
+  }
+  const sorted = [...points].sort((a, b) => {
+    const ax = a.x - pivot.x, ay = a.y - pivot.y;
+    const bx = b.x - pivot.x, by = b.y - pivot.y;
+    const cross2 = ax * by - ay * bx;
+    if (cross2 !== 0)
+      return -cross2;
+    return ax * ax + ay * ay - (bx * bx + by * by);
+  });
+  const hull = [];
+  for (const p of sorted) {
+    while (hull.length >= 2 && cross(hull[hull.length - 2], hull[hull.length - 1], p) <= 0) {
+      hull.pop();
+    }
+    hull.push(p);
+  }
+  return hull;
+}
+function cross(O, A, B) {
+  return (A.x - O.x) * (B.y - O.y) - (A.y - O.y) * (B.x - O.x);
+}
+function convexHullPath(points) {
+  if (points.length === 0)
+    return "";
+  if (points.length === 1) {
+    const p = points[0];
+    return `M${p.x},${p.y}Z`;
+  }
+  const hull = grahamScan(points);
+  if (hull.length === 0)
+    return "";
+  const [first, ...rest] = hull;
+  return `M${fmt(first.x)},${fmt(first.y)}` + rest.map((p) => `L${fmt(p.x)},${fmt(p.y)}`).join("") + "Z";
+}
+function expandHull(hullPoints, padPx) {
+  if (padPx === 0 || hullPoints.length === 0)
+    return hullPoints;
+  const cx = hullPoints.reduce((s, p) => s + p.x, 0) / hullPoints.length;
+  const cy = hullPoints.reduce((s, p) => s + p.y, 0) / hullPoints.length;
+  return hullPoints.map((p) => {
+    const dx = p.x - cx;
+    const dy = p.y - cy;
+    const dist = Math.hypot(dx, dy);
+    if (dist === 0)
+      return p;
+    return { x: p.x + dx / dist * padPx, y: p.y + dy / dist * padPx };
+  });
+}
+function rectCorners(r) {
+  return [
+    { x: r.x, y: r.y },
+    { x: r.x + r.width, y: r.y },
+    { x: r.x + r.width, y: r.y + r.height },
+    { x: r.x, y: r.y + r.height }
+  ];
+}
+function padRect(r, pad) {
+  return { x: r.x - pad, y: r.y - pad, width: r.width + pad * 2, height: r.height + pad * 2 };
+}
+function convexHullOfRects(rects, padPx = 0) {
+  if (rects.length === 0)
+    return "";
+  const corners = rects.flatMap(rectCorners);
+  const hull = grahamScan(corners);
+  const expanded = padPx > 0 ? expandHull(hull, padPx) : hull;
+  return hullToPath(expanded);
+}
+function unionOfRectPaths(rects, padPx = 0) {
+  if (rects.length === 0)
+    return "";
+  return rects.map((r) => {
+    const pr = padPx > 0 ? padRect(r, padPx) : r;
+    const { x, y, width: w, height: h } = pr;
+    return `M${fmt(x)},${fmt(y)}L${fmt(x + w)},${fmt(y)}L${fmt(x + w)},${fmt(y + h)}L${fmt(x)},${fmt(y + h)}Z`;
+  }).join("");
+}
+function boundingRectPath(rects, padPx = 0) {
+  if (rects.length === 0)
+    return "";
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const r of rects) {
+    minX = Math.min(minX, r.x);
+    minY = Math.min(minY, r.y);
+    maxX = Math.max(maxX, r.x + r.width);
+    maxY = Math.max(maxY, r.y + r.height);
+  }
+  minX -= padPx;
+  minY -= padPx;
+  maxX += padPx;
+  maxY += padPx;
+  return `M${fmt(minX)},${fmt(minY)}L${fmt(maxX)},${fmt(minY)}L${fmt(maxX)},${fmt(maxY)}L${fmt(minX)},${fmt(maxY)}Z`;
+}
+function convexHullOfCircles(circles, padPx = 0) {
+  if (circles.length === 0)
+    return "";
+  const SAMPLES = 16;
+  const points = [];
+  for (const { x, y, r } of circles) {
+    const effectiveR = r + padPx;
+    for (let i = 0; i < SAMPLES; i++) {
+      const angle = 2 * Math.PI * i / SAMPLES;
+      points.push({
+        x: x + effectiveR * Math.cos(angle),
+        y: y + effectiveR * Math.sin(angle)
+      });
+    }
+  }
+  return convexHullPath(points);
+}
+function offsetLinePath(points, offsetPx) {
+  if (points.length < 2) {
+    if (points.length === 1) {
+      const p = points[0];
+      return convexHullOfCircles([{ x: p.x, y: p.y, r: offsetPx }]);
+    }
+    return "";
+  }
+  const normals = [];
+  for (let i = 0; i < points.length - 1; i++) {
+    const dx = points[i + 1].x - points[i].x;
+    const dy = points[i + 1].y - points[i].y;
+    const len = Math.hypot(dx, dy);
+    normals.push(len === 0 ? { x: 0, y: -1 } : { x: -dy / len, y: dx / len });
+  }
+  const vertexNormals = [];
+  for (let i = 0; i < points.length; i++) {
+    if (i === 0) {
+      vertexNormals.push(normals[0]);
+    } else if (i === points.length - 1) {
+      vertexNormals.push(normals[normals.length - 1]);
+    } else {
+      const n1 = normals[i - 1];
+      const n2 = normals[i];
+      const avg = { x: (n1.x + n2.x) / 2, y: (n1.y + n2.y) / 2 };
+      const len = Math.hypot(avg.x, avg.y);
+      vertexNormals.push(len === 0 ? n1 : { x: avg.x / len, y: avg.y / len });
+    }
+  }
+  const left = points.map((p, i) => ({
+    x: p.x + vertexNormals[i].x * offsetPx,
+    y: p.y + vertexNormals[i].y * offsetPx
+  }));
+  const right = points.map((p, i) => ({
+    x: p.x - vertexNormals[i].x * offsetPx,
+    y: p.y - vertexNormals[i].y * offsetPx
+  })).reverse();
+  const firstLeft = left[0];
+  let d = `M${fmt(firstLeft.x)},${fmt(firstLeft.y)}`;
+  for (let i = 1; i < left.length; i++) {
+    d += `L${fmt(left[i].x)},${fmt(left[i].y)}`;
+  }
+  const lastLeft = left[left.length - 1];
+  const firstRight = right[0];
+  d += arcCap(lastLeft, firstRight, offsetPx);
+  for (let i = 1; i < right.length; i++) {
+    d += `L${fmt(right[i].x)},${fmt(right[i].y)}`;
+  }
+  const lastRight = right[right.length - 1];
+  d += arcCap(lastRight, firstLeft, offsetPx);
+  d += "Z";
+  return d;
+}
+function arcCap(from, to, r) {
+  return `A${fmt(r)},${fmt(r)},0,0,0,${fmt(to.x)},${fmt(to.y)}`;
+}
+function fmt(n) {
+  return Math.round(n * 100) / 100 + "";
+}
+function hullToPath(hull) {
+  if (hull.length === 0)
+    return "";
+  const [first, ...rest] = hull;
+  return `M${fmt(first.x)},${fmt(first.y)}` + rest.map((p) => `L${fmt(p.x)},${fmt(p.y)}`).join("") + "Z";
+}
+
 // src/index.ts
 var src_default = { structure: structure_default, input: input_default, rendering: rendering_default, textChat: text_chat_default };
 export {
-  src_default as default
+  boundingRectPath,
+  convexHullOfCircles,
+  convexHullOfRects,
+  convexHullPath,
+  createValidId,
+  src_default as default,
+  describeNode,
+  expandHull,
+  getGenericCommandsFromNavRules,
+  grahamScan,
+  keyLabel,
+  offsetLinePath,
+  unionOfRectPaths
 };