@davidsouther/agathon 0.0.0-stage → 0.0.0

package/src/layout/util.ts

@@ -0,0 +1,444 @@
+/**
+ * @fileoverview
+ *
+ * Topological layout has a number of internal properties used throughout the
+ * computation. Some are configurable by the user. To consistently get this
+ * data, instances of SmartGraph, Edge, and Node used for layout can have an
+ * optional `layout` property, with an object matching the exposed `Config`
+ * interfaces. These are merged into the default objects, in this file, before
+ * being stored in the [Symbol.Layout] property of each object. This ensures
+ * it's initialized a single time, and then always reused on future property
+ * lookups.
+ *
+ * This file also has utilities for adding virtual nodes and edges to a graph,
+ * an operation used in several places.
+ */
+
+import { assertFinite, checkExhaustive } from "../assert.ts";
+import type { Geometry } from "../geometry/types.ts";
+import { RNGon } from "../geometry.ts";
+import type { Edge, FullGraph, Node, NodeId, Point, Segment, SmartGraph } from "../types.ts";
+
+import {
+  clearEdgeProps,
+  clearGraphProps,
+  clearNodeProps,
+  clearSegmentProps,
+  getEdgeProps,
+  getGraphProps,
+  getNodeProps,
+  getSegmentProps,
+} from "./properties.ts";
+import type {
+  EdgeProperties,
+  LayoutEdge,
+  LayoutGraph,
+  LayoutNode,
+  NodeProperties,
+} from "./types.ts";
+
+// Reexport properties fns, for backwards compatibility.
+export {
+  clearEdgeProps,
+  clearGraphProps,
+  clearNodeProps,
+  clearSegmentProps,
+  getEdgeProps,
+  getGraphProps,
+  getNodeProps,
+  getSegmentProps,
+};
+
+const CacheAction = {
+  WRITE: "WRITE",
+  READ: "READ",
+} as const;
+type CacheAction = (typeof CacheAction)[keyof typeof CacheAction];
+
+/** Memoize virtual nodes' ranks and orders. */
+export function writeVirtualNodeLayoutCache(g: FullGraph): void {
+  virtualNodeLayoutCache(g, CacheAction.WRITE);
+}
+
+/** Read virtual nodes' ranks and orders from cache */
+export function readVirtualNodeLayoutCache(g: FullGraph): void {
+  virtualNodeLayoutCache(g, CacheAction.READ);
+}
+
+function virtualNodeLayoutCache(g: FullGraph, action: CacheAction): void {
+  const graphProps = getGraphProps(g);
+  const { virtualNodeLayout } = graphProps;
+
+  for (const node of g.allNodes) {
+    const nodeProps = getNodeProps(node);
+
+    if (nodeProps.virtual) {
+      switch (action) {
+        case CacheAction.WRITE:
+          virtualNodeLayout!.set(node.id, {
+            rank: nodeProps.rank,
+            order: nodeProps.order,
+          });
+          break;
+        case CacheAction.READ:
+          {
+            const vNodeLayoutCache = virtualNodeLayout!.get(node.id);
+            nodeProps.rank = vNodeLayoutCache!.rank;
+            nodeProps.order = vNodeLayoutCache!.order;
+          }
+          break;
+        default:
+          checkExhaustive(action);
+      }
+    }
+  }
+}
+
+/** Pull nodes into a 2d matrix of [rank, order] with a node id. */
+export function buildLayerMatrix(g: SmartGraph<Node, {}>): NodeId[][] {
+  const layers: NodeId[][] = range(maxRank(g) + 1).map(() => []);
+  for (const node of g.allNodes) {
+    const id = node.id;
+    const { rank, order } = getNodeProps(node);
+    // Position in the matrix row is associated with a node's order. If we have
+    // one node with {id: '1st', rank: 0, order: 0} and another with {id: '2nd',
+    // rank: 0, order: 3}, this would create a layer ['1st', empty x 2, '2nd'].
+    // These undefined elements in the layer matrix row can lead to
+    // ReferenceErrors further in the code...[CONT.]
+    layers[rank][order] = id;
+  }
+
+  //[CONT.]...to prevent that, holes in each layer are filtered out.
+  return layers.map((layer) => layer.filter(Boolean));
+}
+
+/** Return an edge with layout set. */
+export function makeEdge(
+  source: string,
+  target: string,
+  layout?: Partial<EdgeProperties>,
+  name?: string,
+): Edge<{ layout: Partial<EdgeProperties> | undefined }> {
+  return { source, target, name, layout };
+}
+
+/**
+ * Find the highest rank value in a graph.
+ */
+export function maxRank(g: SmartGraph<Node, {}>): number {
+  const ranks = Array.from(g.allNodes).map((node) =>
+    assertFinite(getNodeProps(node).rank, `Invalid rank ${getNodeProps(node).rank} for ${node.id}`),
+  );
+  // Include 0, so that no nodes still returns a valid max rank.
+  return Math.max(0, ...ranks);
+}
+
+/** Generate an array with n undefined values. */
+export function range(n: number): undefined[] {
+  return new Array(n).fill(undefined);
+}
+
+/** Virtual nodes have a type corresponding to their usage. */
+export const Virtual = {
+  EDGE: "edge",
+  BORDER: "border",
+  ROOT: "root",
+} as const;
+export type Virtual = (typeof Virtual)[keyof typeof Virtual];
+
+let vnodeIdx = 0;
+/**
+ * Create a virtual node.
+ */
+export function addVirtualNode(
+  g: FullGraph,
+  virtual: Virtual,
+  layout: Partial<NodeProperties>,
+  id?: NodeId,
+  prefix = "",
+): NodeId {
+  layout.virtual = virtual;
+
+  if (!id) {
+    do {
+      id = `(϶${prefix}${vnodeIdx++})`;
+    } while (g.hasNode(id));
+  }
+
+  const node: LayoutNode = { id, layout };
+  g.setNode(id, node);
+
+  return id;
+}
+
+/** Valid border directions */
+export const Border = {
+  TOP: "_bt_",
+  BOTTOM: "_bb_",
+} as const;
+export type Border = (typeof Border)[keyof typeof Border];
+
+/** Add a virtual border node */
+export function addBorderNode(g: FullGraph, prefix: Border, rank?: number, order?: number): NodeId {
+  const layout: Partial<NodeProperties> = {
+    geometry: RNGon.point(),
+    rank,
+    order,
+  };
+  return addVirtualNode(g, Virtual.BORDER, layout, undefined, prefix);
+}
+
+/**
+ * Create an initial layout matrix, with no ordering constraints. While this is
+ * a terrible order in practice, it's a convenient first step for further
+ * ordering calculations. When used for debugging, will use the order as set on
+ * the node if called after ordering has taken place.
+ */
+export function initOrder(g: FullGraph): NodeId[][] {
+  const visited = new Set<NodeId>();
+  // Working from the topmost rank down, assign initial ranks to subgraph leaf
+  // nodes.
+  const simpleNodes = Array.from(g.nodes)
+    .filter((id) => g.children(id).size === 0)
+    .sort((a, b) => {
+      const rankA = getNodeProps(g.node(a)!).rank;
+      const rankB = getNodeProps(g.node(b)!).rank;
+      return rankA - rankB;
+    });
+  const layers: NodeId[][] = [];
+  for (const id of simpleNodes) {
+    iterate(id);
+  }
+
+  // Ensure all layers are initialized
+  for (let i = 0; i < layers.length; i++) {
+    layers[i] = layers[i] || [];
+  }
+
+  return layers;
+
+  // Just push each node onto layers in whatever order it happens to be found.
+  function iterate(id: NodeId) {
+    if (visited.has(id)) return;
+    visited.add(id);
+
+    const { rank } = getNodeProps(g.node(id)!);
+    if (layers[rank] === undefined) {
+      layers[rank] = [];
+    }
+    layers[rank].push(id);
+
+    for (const cid of g.successors(id)) iterate(cid);
+  }
+}
+
+/**
+ * Get the correct coordinates for a node, taking fixed values over updated
+ * values.
+ */
+export function position(node: Node): Point {
+  const {
+    geometry: { x, y },
+    fx,
+    fy,
+  } = getNodeProps(node);
+  // Use "fixed" fx, fy if provided, otherwise
+  return {
+    x: fx ?? x,
+    y: fy ?? y,
+  };
+}
+
+/**
+ * Returns a line segment with ends on borders of given nodes and lying on the
+ * line defined by nodes center points.
+ */
+export function getLineSegmentBetweenNodes(
+  nodeA: Geometry,
+  nodeB: Geometry,
+): { source: Point; target: Point } {
+  const s = nodeA.clip([nodeB, nodeA]);
+  const t = nodeB.clip([nodeA, nodeB]);
+
+  return { source: s, target: t };
+}
+
+/**
+ * Given two points, P0 & P1, and a Y value, find the point P1' along P0->P1
+ * such that P1'.Y = Y. Update P1 to be P1'. This modifies the referenced point.
+ */
+export function projectPointAlongLineToYValue(p0: Readonly<Point>, p1: Point, endY: number): void {
+  const { x: x0, y: y0 } = p0;
+  const { x: x1, y: y1 } = p1;
+  const dx = x1 - x0;
+  const dy = y1 - y0;
+  const t = (endY - y0) / dy;
+  const endX = x0 + t * dx;
+  p1.x = endX;
+  p1.y = endY;
+}
+
+/**
+ * Given a graph and a node, find all segments that could be affected by
+ * moving that node. Those segments are the segment neighborhood of the root
+ * ancestor of the given node. Segments below collapsed nodes are not included.
+ * The iterable will iterate nodes from top to bottom.
+ */
+export function findSegmentNeighborhood(
+  graph: LayoutGraph,
+  id?: NodeId,
+): Iterable<Segment<LayoutEdge>> {
+  const neighborhood = new Set<Segment<LayoutEdge>>();
+
+  const findSegmentSegments = (segment: Segment<LayoutEdge>): void => {
+    for (const previous of segment.previous) {
+      if (!graph.node(previous.target)!.expanded) continue;
+      neighborhood.add(previous);
+      findNodeSegments(previous.source);
+      findSegmentSegments(previous);
+    }
+  };
+
+  const findNodeSegments = (id?: NodeId): void => {
+    if (graph.hasNode(id) && !graph.node(id)!.expanded) return;
+    for (const segment of graph.childSegments(id)) {
+      neighborhood.add(segment);
+      findSegmentSegments(segment);
+    }
+    for (const child of graph.children(id)) {
+      findNodeSegments(child);
+    }
+  };
+
+  // Include segments below this node
+  findNodeSegments(id);
+
+  // Include segments into and out from this node, if present
+  if (id) {
+    for (const segment of graph.nodeSegments(id)) {
+      neighborhood.add(segment);
+      findSegmentSegments(segment);
+    }
+  }
+
+  return neighborhood;
+}
+
+/**
+ * Given an item, determine at runtime whether it's a Node or a Segment.
+ */
+export function isSegment(entity: NodeId | Segment<LayoutEdge>): entity is Segment<LayoutEdge> {
+  return (entity as Segment<LayoutEdge>).source !== undefined;
+}
+
+/**
+ * Returns a bottom-up breadth-first traversal of topNode's children tree. If no
+ * topNode given, returns the entire tree's traversal. Nodes that have an
+ * unexpanded ancestor do not get into the traversal, as they do not need to be
+ * recalculated. Based on code taken from: https://stackoverflow.com/a/23981550
+ */
+export function bottomUpBFTraversal(graph: LayoutGraph, topNode?: NodeId): NodeId[] {
+  let neighborhood: NodeId[];
+  let hulls: Array<Set<NodeId>>;
+
+  if (topNode) {
+    hulls = [graph.children(topNode)];
+    neighborhood = [topNode];
+  } else {
+    hulls = [graph.children()];
+    neighborhood = [];
+  }
+
+  while (hulls.length > 0) {
+    const hull: Set<NodeId> = hulls.shift()!;
+    neighborhood.unshift(...hull);
+
+    for (const id of hull) {
+      if (graph.node(id)!.expanded && graph.hasChildren(id)) {
+        hulls.push(graph.children(id));
+      }
+    }
+  }
+
+  return neighborhood;
+}
+
+/**
+ * staggerRow will take a single rank and "stagger" adjacent items. This
+ * reduces visual density along long single ranks, and improves visibility
+ * of such ranks. It works by creating "rows" for every few items, as
+ * specified by staggerRows.
+ *
+ * For instance, with staggerRows = 3 and with 8 items, it would turn this
+ * rank
+ *
+ *    0 0 0 0 0 0 0 0
+ *
+ * into
+ *
+ *    0     0     0
+ *      0     0     0
+ *        0     0
+ *
+ * For further ranks, this rank's height is the sum of the height of the rows.
+ * rankSep does not apply between rows within ranks, it only applies between
+ * ranks. All nodes in a row have the same Y center position. A row's height
+ * is the height of the largest single node within the rank.
+ *
+ * The default staggerRows is set to 10.
+ */
+export function staggerRow(
+  g: LayoutGraph,
+  layer: NodeId[],
+  coordinates: Record<NodeId, number>,
+  staggerRows: number = Math.sqrt(layer.length),
+): number {
+  if (layer.length === 0) return 40;
+
+  const rowSpread = Math.ceil(layer.length / staggerRows);
+
+  const rowMaxHeights: number[] = [];
+  // Determine the max height for every staggered row.
+  for (let i = 0; i < layer.length; i++) {
+    const j = i % rowSpread;
+    const node = g.node(layer[i])!;
+    rowMaxHeights[j] = Math.max(
+      rowMaxHeights[j] || 0,
+      node ? getNodeProps(node).geometry.height : 0,
+    );
+  }
+
+  const rowHeights: number[] = [rowMaxHeights[0] / 2];
+  for (let i = 1; i < rowMaxHeights.length; i++) {
+    rowHeights[i] = rowHeights[i - 1] + rowMaxHeights[i] / 2;
+  }
+
+  for (let i = 0; i < layer.length; i++) {
+    const j = i % rowSpread;
+    const id = layer[i];
+    coordinates[id] = rowHeights[j];
+  }
+
+  return rowHeights[rowSpread - 1] + rowMaxHeights[rowMaxHeights.length - 1] / 2;
+}
+
+/**
+ * Given a layer of nodes, distribute them evenly along the horizontal axis.
+ */
+export function distributeHorizontalLayer(
+  g: LayoutGraph,
+  layer: NodeId[],
+  coordinates: Record<NodeId, number>,
+): number {
+  let width = 0;
+  const padding = getGraphProps(g).nodeSep;
+  for (const id of layer) {
+    const { geometry } = getNodeProps(g.node(id)!);
+    coordinates[id] = width + geometry.width / 2;
+    width += geometry.width;
+    width += padding;
+  }
+  width -= padding;
+
+  return width;
+}

package/src/layout.ts

@@ -0,0 +1,6 @@
+export * as grid from "./layout/grid.ts";
+export * from "./layout/hierarchic.ts";
+export * as manager from "./layout/manager.ts";
+export * as properties from "./layout/properties.ts";
+export * as types from "./layout/types.ts";
+export * as util from "./layout/util.ts";

package/src/samples/diff_graph.ts

@@ -0,0 +1,15 @@
+/** Basic diff test graph. */
+export const DIFF_GRAPH_TEST = `digraph {
+a [presence=both];
+b [presence="left"];
+c [presence=both];
+d [presence="right"];
+
+a -> b [presence="left"];
+b -> c [presence="left"];
+c -> a [presence="left"];
+
+a -> c [presence="right"];
+c -> d [presence="right"];
+d -> a [presence="right"];
+}`;

package/src/samples/edge_cases.ts

@@ -0,0 +1,168 @@
+/**
+ * Gansner graph from Gansner paper
+ *
+ *     a
+ *    /|\
+ *    bef
+ *    |||
+ *    c\|
+ *    | g
+ *    \ /
+ *     h
+ */
+export const GANSNER_GRAPH = `digraph {
+  a -> b;
+  b -> c;
+  c -> d;
+  d -> h;
+  a -> e;
+  e -> g;
+  g -> h;
+  a -> f;
+  f -> g;
+}`;
+
+/** Fixed rank diamond */
+export const FIXED_DIAMOND = `digraph {
+    a [rank=1; fixedRank=true];
+    b [rank=2; fixedRank=true];
+    c [rank=3; fixedRank=true];
+    d [rank=4; fixedRank=true];
+
+    a -> b;
+    a -> c;
+    b -> d;
+    c -> d;
+}`;
+
+/** A simple 2-hulled example showing traffic between cousins. */
+export const TWO_HULLS = `digraph {
+  A [status = good] {
+    AA { AAA {AAAA;} AAB; }
+  }
+  B [status = bad] {
+    BB;
+  }
+  AAA -> BB;
+  AAB -> BB;
+  AAAA -> BB;
+}`;
+
+/** Very deep hulls, to test child positioning. */
+export const DEEP_HULLS = `digraph {
+  A {
+    AA {
+      AAA { AAAA; AAAB; }
+      AAB { AABA; AABB; }
+    }
+    AB {
+      ABA { ABAA; ABAB; }
+      ABB { ABBA; ABBB; }
+    }
+  }
+  B {
+    BA {
+      BAA { BAAA; BAAB; }
+      BAB { BABA; BABB; }
+    }
+    BB {
+      BBA { BBAA; BBAB; }
+      BBB { BBBA; BBBB; }
+    }
+  }
+}`;
+
+/**
+ * A small cyclic graph who's edge c -> a should be reversed, as it's the
+ * lightest.
+ */
+export const SMALL_REVERSED = `digraph {
+  a -> b[weight=2;];
+  b -> c[weight=2;];
+  c -> a[weight=1;];
+  c -> d[weight=2;];
+  c -> e[weight=2;];
+  d -> e[weight=2;];
+}`;
+
+/**
+ * A large acyclic graph, loosely modeled after the GraphViz 0.11 Unices
+ * sample.
+ */
+export const LARGE_GRAPH = `digraph {
+    [printDebug=true]
+  Tiger -> Lion;
+  Tiger -> Alligator;
+  Lion -> Bison;
+  Lion -> Shark;
+  Lion -> Ant;
+  Lion -> Wollongong;
+  Lion -> Zebra;
+  Zebra -> Deer;
+  Zebra -> Hippo;
+  Zebra -> Pig;
+  Pig -> Giraffe;
+  Pig -> Crab;
+  Pig -> Cow;
+  Pig -> Oyster;
+  Pig -> Lemur;
+  Pig -> Jaguar;
+  Cow -> Oyster;
+  Giraffe -> Kangaroo;
+  Shark -> Otter;
+  Otter -> Goat;
+  Goat -> Oyster;
+  Goat -> Lynx;
+  Crab -> Koala;
+  Koala -> Kiwi;
+  Kiwi -> Horse;
+  Horse -> Frog;
+  Horse -> Goat;
+  Horse -> Giraffe;
+  Frog -> Newt;
+  Frog -> Magpie;
+  Alligator -> Duck;
+  Alligator -> Snake;
+  Duck -> Hippo;
+  Snake -> Chicken;
+  Snake -> Eagle;
+  Chicken -> Butterfly;
+  Butterfly -> Turtle;
+  Turtle -> Rabbit;
+  Turtle -> Parrot;
+  Eagle -> Owl;
+  Owl -> Deer;
+  Hippo -> Deer;
+  Sheep -> Deer;
+  Deer -> Monkey;
+  Rabbit -> Monkey;
+  Turtle -> Monkey;
+  Monkey -> Bird;
+  Bird -> Fish;
+  Fish -> Mole;
+}`;
+
+/** A graph with a search and a focus. */
+export const SEARCH_MATCH = `digraph {
+  [search="weasley"; match="fred";]
+  gryffindor;
+  ron_weasley;
+  fred_weasley;
+  george_weasley;
+}`;
+
+/** Small node-pool example for developing the expanded view */
+export const NODE_POOL = `digraph {
+  A; B; C;
+  N [expanded=true; type="parent";] { NA; NB; NC; }
+  A -> NA; B -> NB; C -> NC;
+}`;
+
+/** Graph that has multiple geometries */
+export const GEOMETRIES = `digraph {
+  A [geometry='{"type": "rngon", "n": 3, "radius": 12}'];
+  B [radius='35'];
+  C [geometry='{"type": "square", "side": 12}'];
+  A -> C;
+  B -> C;
+}`;

package/src/samples/gansner_with_states.ts

@@ -0,0 +1,67 @@
+/** Good bounds for snapshot tests. */
+export const GANSNER_WITH_STATES_BOUNDS = {
+  width: 800,
+  height: 1000,
+};
+
+/** The Marquee "Put everything in" graph. */
+export const GANSNER_WITH_STATES = `digraph {
+[search="a"; match="aa"; icon="icons:workload"]
+
+  a -> b;
+  b -> c;
+  c -> d;
+  d -> h;
+  a -> e;
+  e -> g [presence = left];
+  g -> h [presence = left];
+  a -> f;
+  f -> g [presence = left];
+
+b [chip="status-warning"];
+
+a [expanded=true; chip="status-success"] {
+  aa [expanded=true; chip="status-success"] {
+    aaa [chip="status-success"];
+    aab [chip="status-success"];
+  }
+  ab [chip="status-success"] {
+    aba [chip="status-success"];
+    abb [chip="status-success"];
+  }
+}
+
+c [expanded = true; chip="status-error"; filtered=true] {
+  ca [chip="status-error"; presence=left; filtered=true]{
+    caa [chip="status-error"; presence=left; filtered=true];
+    cab [chip="status-error"; presence=left; filtered=true];
+  }
+  cb [chip="status-error"; presence = right; filtered=true];
+}
+
+f [matched = true];
+
+g [expanded=true; selected=true; presence=left] {
+  ga [presence = left];
+  gb [presence = left];
+  gc [selected = true; presence=left];
+}
+
+ab -> b [presence = left];
+ab -> f [presence = right];
+aab -> e;
+aab -> f;
+aaa -> e;
+aaa -> f;
+aba -> e;
+b -> ca [presence=left];
+b -> cb [presence=right];
+ca -> d [presence=left];
+e -> gc [presence=left];
+e -> gb [presence=left];
+e -> ga [presence=left];
+f -> gc [presence=left];
+e -> h  [presence=right];
+f -> h  [presence=right];
+}
+`;