@davidsouther/agathon 0.0.0-stage → 2026.11.1

package/src/layout/manager/zoom_manager.ts

@@ -0,0 +1,263 @@
+import type { Geometry } from "../../geometry/types.ts";
+import { CircleGeometry } from "../../geometry.ts";
+import type { Point, Segment } from "../../types.ts";
+import type { LayoutEdge, LayoutNode, SegmentPosition } from "../types.ts";
+import {
+  getGraphProps,
+  getLineSegmentBetweenNodes,
+  getNodeProps,
+  getSegmentProps,
+} from "../util.ts";
+
+import type { NoopLayoutManager } from "./manager.ts";
+
+const ZOOM_LEVELS_PER_WHEEL = 1;
+const ZOOM_EXPANSION_RATIO = 10;
+
+/**
+ * Noop zoom manager which handles setting positions but does not update zoom
+ * level.
+ */
+export class NoopZoomManager {
+  protected zoomLevel = 0;
+  protected expansionFactor = 1;
+
+  get level(): number {
+    return this.zoomLevel;
+  }
+
+  protected readonly layoutManager: NoopLayoutManager;
+  constructor(layoutManager: NoopLayoutManager) {
+    this.layoutManager = layoutManager;
+  }
+
+  dragAmount({ x, y }: Point): Point {
+    return {
+      x: x / this.expansionFactor,
+      y: y / this.expansionFactor,
+    };
+  }
+
+  zoomIn(center?: Point): void {
+    this.zoom(this.zoomLevel + ZOOM_LEVELS_PER_WHEEL, center);
+  }
+
+  zoomOut(center?: Point): void {
+    this.zoom(this.zoomLevel - ZOOM_LEVELS_PER_WHEEL, center);
+  }
+
+  zoom(level: number, center: Point | undefined): void {
+    // noop
+  }
+
+  /**
+   * Given a point, project it along its axis away from the center of the
+   * layout by `expansionFactor` amount. That is, if the point was 5 units from
+   * the center, and the expansionFactor is 2 (zoom level 10), the new position
+   * would be 10 units away along the same line.
+   */
+  diffusePoint({ x, y }: Point, { x: cx, y: cy } = this.layoutManager.center): Point {
+    return {
+      x: place(x, this.expansionFactor, cx),
+      y: place(y, this.expansionFactor, cy),
+    };
+  }
+
+  undiffusePoint({ x, y }: Point, { x: cx, y: cy } = this.layoutManager.center): Point {
+    return {
+      x: place(x, 1 / this.expansionFactor, cx),
+      y: place(y, 1 / this.expansionFactor, cy),
+    };
+  }
+
+  /**
+   * Given a node and its position, calculate a new node position with all
+   * points diffused by expansionFactor away. Top level nodes are moved
+   * relative to the center of the layout; lower nodes are moved relative to the
+   * <0, 0> center of the hull. Hull sizes are recalculated as the smallest
+   * bounding circle.
+   */
+  diffuseNodePosition(node: LayoutNode, position: Geometry): Geometry {
+    const { baseRadius } = getGraphProps(this.layoutManager.graph);
+    const isTopLevel = !this.layoutManager.graph.hasNode(this.layoutManager.graph.parent(node.id));
+    position = position.clone();
+    position.moveTo(this.diffusePoint(position, isTopLevel ? undefined : { x: 0, y: 0 }));
+
+    if (node.expanded && this.layoutManager.graph.hasChildren(node.id)) {
+      // only recalculate node size if this expanded node has children. If it
+      // doesn't have children, the size is set by a constraint other than
+      // "smallest enclosing circle"
+      // Recursively layout all children first
+      const children: Geometry[] = [...this.layoutManager.graph.children(node.id)].map((cid) => {
+        try {
+          return this.layoutManager.getNodePosition(cid);
+        } catch (e: unknown) {
+          // TODO: Handle this exception better.
+          return getNodeProps(this.layoutManager.getNode(cid)).geometry;
+        }
+      });
+
+      // Find the smallest bounding circle
+      position.fitTo(children, baseRadius);
+    }
+
+    return position;
+  }
+
+  /**
+   * Given a segment, diffuse its position, but keep endpoints connected to
+   * their node positions. Node positions must be calculated before calculating
+   * segment positions.
+   */
+  diffuseSegmentPosition(segment: Segment<LayoutEdge>, position: SegmentPosition): SegmentPosition {
+    if (!segment.next) {
+      position = this.diffuseSiblingSegment(segment, position);
+    } else {
+      position = this.diffuseRisingSegment(segment, position);
+    }
+
+    position = this.diffuseSegmentLabel(segment, position);
+
+    return position;
+  }
+
+  protected diffuseSiblingSegment(
+    segment: Segment<LayoutEdge>,
+    position: SegmentPosition,
+  ): SegmentPosition {
+    const length = position.points.length;
+
+    const { points } = getSegmentProps(segment);
+    for (let i = 0; i < length; i++) {
+      position.points[i] = this.diffusePoint(points[i]);
+    }
+
+    return this.clipSiblingSegment(segment, position);
+  }
+
+  protected clipSiblingSegment(
+    segment: Segment<LayoutEdge>,
+    position: SegmentPosition,
+  ): SegmentPosition {
+    const length = position.points.length;
+    if (length < 2) {
+      // It's unclear how a segment will have less than two points. However that
+      // happened, there's no way to "correct" the end points relative to one
+      // another, so we skip fixing the first and last point to the node
+      // centers.
+      return position;
+    }
+
+    const source = this.layoutManager.getNodePosition(segment.source);
+    const target = this.layoutManager.getNodePosition(segment.target);
+
+    const hasIntermediatePoints = length > 2;
+    const nextPoint = hasIntermediatePoints ? CircleGeometry.point(position.points[1]) : target;
+    const lastPoint = hasIntermediatePoints
+      ? CircleGeometry.point(position.points[length - 2])
+      : source;
+
+    position.points[0] = getLineSegmentBetweenNodes(source, nextPoint).source;
+    position.points[length - 1] = getLineSegmentBetweenNodes(lastPoint, target).target;
+
+    return position;
+  }
+
+  protected diffuseRisingSegment(
+    segment: Segment<LayoutEdge>,
+    position: SegmentPosition,
+  ): SegmentPosition {
+    const next = segment.next;
+    if (!next) return this.diffuseSiblingSegment(segment, position);
+    const nextPosition = this.layoutManager.getSegmentPosition(next);
+
+    // source point is source node position, source node radius
+    const source = this.layoutManager.getNodePosition(segment.source);
+
+    // target point is segment.next.points[0] (or [l] if segment is
+    // top-level-reversed), translated to local node space
+    const nextPoint = next.source === segment.target ? 0 : nextPosition.points.length - 1;
+    const targetPoint = { ...nextPosition.points[nextPoint] };
+    const target = this.layoutManager.getNodePosition(segment.target);
+    targetPoint.x -= target.x;
+    targetPoint.y -= target.y;
+
+    const line = getLineSegmentBetweenNodes(source, CircleGeometry.point(targetPoint));
+    position.points[0] = line.source;
+    position.points[1] = line.target;
+    position.points.length = 2;
+
+    return position;
+  }
+
+  private diffuseSegmentLabel(
+    segment: Segment<LayoutEdge>,
+    position: SegmentPosition,
+  ): SegmentPosition {
+    if (position.points.length < 2) return position;
+
+    const median = (position.points.length / 2) | 0;
+    let { x: lsx, y: lsy } = position.points[median - 1];
+    let { x: ltx, y: lty } = position.points[median];
+    if (lsx > ltx) {
+      const [ttx, tty] = [ltx, lty];
+      [ltx, lty] = [lsx, lsy];
+      [lsx, lsy] = [ttx, tty];
+      position.label.flippedBy180 = true;
+    } else {
+      position.label.flippedBy180 = false;
+    }
+
+    position.label.position.x = Math.round(lsx / 2 + ltx / 2);
+    position.label.position.y = Math.round(lsy / 2 + lty / 2);
+    position.label.rotation = (Math.atan2(lty - lsy, ltx - lsx) * 180) / Math.PI;
+
+    return position;
+  }
+}
+
+/** Zoom manager which actually updates zoom based on requested levels. */
+export class ZoomManager extends NoopZoomManager {
+  constructor(layoutManager: NoopLayoutManager) {
+    super(layoutManager);
+  }
+
+  override zoom(
+    level: number,
+    center: Point = {
+      x: this.layoutManager.pageBounds.width / 2,
+      y: this.layoutManager.pageBounds.height / 2,
+    },
+  ): void {
+    // Given the center point relative to the layoutManager's page bounds,
+    // determine its equivalent position in the layout. The equivalent position
+    // is determined by having pan manager remove the relative offset and zoom
+    // values.
+    const projectedPointOnGraph = this.layoutManager.pan.pagePointToGraphPoint(center);
+
+    // Adjust level and expansion factor
+    this.zoomLevel = Math.min(level, this.layoutManager.depth * ZOOM_EXPANSION_RATIO);
+    this.expansionFactor = 2 ** (this.zoomLevel / ZOOM_EXPANSION_RATIO);
+
+    // After changing the expansion factor, convert the projected point back to
+    // page space, and calculate the delta necessary to adjust the graph to keep
+    // the center point at the same relative bounds position.
+    const correctedPointInScreenSpace =
+      this.layoutManager.pan.graphPointToPagePoint(projectedPointOnGraph);
+    const delta = {
+      x: center.x - correctedPointInScreenSpace.x,
+      y: center.y - correctedPointInScreenSpace.y,
+    };
+
+    // Recalculate positions and update the graph.
+    this.layoutManager.moveGraphBy(delta);
+    this.layoutManager.updateAt();
+  }
+}
+
+// Given two points on the real number line, return the point p such that the
+// distance from p to c is equal to the distance from n to c times a factor.
+// This call is highly homomorphic, and will get inlined
+function place(n: number, factor: number, c: number): number {
+  return c + factor * (n - c);
+}

package/src/layout/manager.ts

@@ -0,0 +1,6 @@
+export { ChildManager } from "./manager/child_manager.ts";
+export { DragManager } from "./manager/drag_manager.ts";
+export { NoopLayoutManager } from "./manager/manager.ts";
+export { PanManager } from "./manager/pan_manager.ts";
+export { VisibilityManager } from "./manager/visibility_manager.ts";
+export { ZoomManager } from "./manager/zoom_manager.ts";

package/src/layout/properties/defaults.ts

@@ -0,0 +1,99 @@
+import { CircleGeometry } from "../../geometry.ts";
+import type { NodeId } from "../../types.ts";
+
+import type {
+  EdgeConfig,
+  EdgeProperties,
+  GraphConfig,
+  GraphProperties,
+  NodeConfig,
+  NodeProperties,
+  SegmentConfig,
+  SegmentProperties,
+} from "../types.ts";
+
+/**
+ * Default properties for a node.
+ *
+ * Makes a fresh object every call.
+ */
+export function defaultNodeProperties(layout: Partial<NodeConfig> = {}): NodeProperties {
+  return {
+    geometry: new CircleGeometry({ radius: 20 }),
+    rank: 0,
+    // Start order at -1 so initOrder knows whether to push or assign
+    // in the row.
+    order: -1,
+    lim: Number.MAX_SAFE_INTEGER,
+    low: 1,
+    virtual: false,
+    fixedRank: false,
+    ...layout,
+  };
+}
+
+/**
+ * Default properties for an edge.
+ *
+ * Makes a fresh object every call.
+ */
+export function defaultEdgeProperties(layout: Partial<EdgeConfig> = {}): EdgeProperties {
+  return {
+    minLength: 1,
+    weight: 1,
+    cutValue: 0,
+    reversed: false,
+    nestingEdge: false,
+    points: [],
+    ...layout,
+  };
+}
+
+/**
+ * Default properties for a segment.
+ *
+ * Makes a fresh object every call.
+ */
+export function defaultSegmentProperties(layout: Partial<SegmentConfig> = {}): SegmentProperties {
+  return {
+    metrics: {
+      forward: undefined,
+      reverse: undefined,
+    },
+    annotations: {
+      forward: undefined,
+      reverse: undefined,
+    },
+    points: [],
+    label: {
+      position: { x: 0, y: 0 },
+      rotation: 0,
+      flippedBy180: false,
+    },
+    ...layout,
+  };
+}
+
+/**
+ * Default properties for a graph.
+ *
+ * Makes a fresh object every call.
+ */
+export function defaultGraphProperties(layout: Partial<GraphConfig> = {}): GraphProperties {
+  return {
+    rankSep: 50,
+    edgeSep: 10,
+    nodeSep: 50,
+    nodeRankFactor: 1,
+    baseRadius: 20,
+    hullRotation: 25,
+    childrenRelative: false,
+    bendLongEdges: true,
+    staggerRows: 10,
+    timing: false,
+    printDebug: false,
+    virtualNodeLayout: new Map<NodeId, { rank: number; order: number }>(),
+    fas: undefined,
+    ...layout,
+  };
+}

package/src/layout/properties/symbol.ts

@@ -0,0 +1,99 @@
+import type { Edge, Node, Segment, SmartGraph } from "../../types.ts";
+import type {
+  EdgeConfig,
+  EdgeProperties,
+  GraphProperties,
+  NodeConfig,
+  NodeProperties,
+  PropertiesStrategy,
+  SegmentConfig,
+  SegmentProperties,
+} from "../types.ts";
+
+import {
+  defaultEdgeProperties,
+  defaultGraphProperties,
+  defaultNodeProperties,
+  defaultSegmentProperties,
+} from "./defaults.ts";
+
+const LAYOUT: unique symbol = Symbol("Layout");
+
+/**
+ * A PropertiesStrategy which stores properties in a private Symbol on entities.
+ */
+export const LAYOUT_SYMBOL_PROPERTIES_STRATEGY: PropertiesStrategy = {
+  getNodeProps(
+    obj: Node & {
+      layout?: Partial<NodeConfig>;
+      [LAYOUT]?: NodeProperties;
+    },
+  ): NodeProperties {
+    return (obj[LAYOUT] = obj[LAYOUT] ?? {
+      ...defaultNodeProperties(obj.layout),
+    });
+  },
+
+  getEdgeProps(
+    obj: Edge & {
+      layout?: Partial<EdgeConfig>;
+      [LAYOUT]?: EdgeProperties;
+    },
+  ): EdgeProperties {
+    return (obj[LAYOUT] = obj[LAYOUT] ?? defaultEdgeProperties(obj.layout));
+  },
+
+  getSegmentProps(
+    obj: Segment & {
+      layout?: Partial<SegmentConfig>;
+      [LAYOUT]?: SegmentProperties;
+    },
+  ): SegmentProperties {
+    return (obj[LAYOUT] = obj[LAYOUT] ?? defaultSegmentProperties(obj.layout));
+  },
+
+  getGraphProps(
+    obj: SmartGraph<{}, {}> & {
+      layout?: Partial<GraphProperties>;
+      [LAYOUT]?: GraphProperties;
+    },
+  ): GraphProperties {
+    return (obj[LAYOUT] = obj[LAYOUT] ?? defaultGraphProperties(obj.layout));
+  },
+
+  clearNodeProps(
+    obj: Node & {
+      layout?: Partial<NodeProperties>;
+      [LAYOUT]?: NodeProperties;
+    },
+  ) {
+    obj[LAYOUT] = undefined;
+  },
+
+  clearEdgeProps(
+    obj: Edge & {
+      layout?: Partial<EdgeProperties>;
+      [LAYOUT]?: EdgeProperties;
+    },
+  ) {
+    obj[LAYOUT] = undefined;
+  },
+
+  clearSegmentProps(
+    obj: Segment & {
+      layout?: Partial<SegmentConfig>;
+      [LAYOUT]?: EdgeProperties;
+    },
+  ) {
+    obj[LAYOUT] = undefined;
+  },
+
+  clearGraphProps(
+    obj: SmartGraph<{}, {}> & {
+      layout?: Partial<GraphProperties>;
+      [LAYOUT]?: GraphProperties;
+    },
+  ) {
+    obj[LAYOUT] = undefined;
+  },
+};

package/src/layout/properties/weak_map.ts

@@ -0,0 +1,73 @@
+import type { Edge, Node, Segment, SmartGraph } from "../../types.ts";
+import type {
+  EdgeConfig,
+  EdgeProperties,
+  GraphProperties,
+  NodeConfig,
+  NodeProperties,
+  PropertiesStrategy,
+  SegmentConfig,
+  SegmentProperties,
+} from "../types.ts";
+
+import {
+  defaultEdgeProperties,
+  defaultGraphProperties,
+  defaultNodeProperties,
+  defaultSegmentProperties,
+} from "./defaults.ts";
+
+const EDGE_MAP = new WeakMap<Edge, EdgeProperties>();
+const GRAPH_MAP = new WeakMap<SmartGraph<{}, {}>, GraphProperties>();
+const NODE_MAP = new WeakMap<Node, NodeProperties>();
+const SEGMENT_MAP = new WeakMap<Segment, SegmentProperties>();
+
+/**
+ * A PropertiesStrategy which stores properties in a WeakMap from entity to
+ * properties.
+ */
+export const WEAK_MAP_PROPERTIES_STRATEGY: PropertiesStrategy = {
+  getNodeProps(obj: Node & { layout?: Partial<NodeConfig> }): NodeProperties {
+    const properties = NODE_MAP.get(obj) ?? {
+      ...defaultNodeProperties(obj.layout),
+    };
+    NODE_MAP.set(obj, properties);
+    return properties;
+  },
+
+  getEdgeProps(obj: Edge & { layout?: Partial<EdgeConfig> }): EdgeProperties {
+    const properties = EDGE_MAP.get(obj) ?? {
+      ...defaultEdgeProperties(obj.layout),
+    };
+    EDGE_MAP.set(obj, properties);
+    return properties;
+  },
+
+  getSegmentProps(obj: Segment & { layout?: Partial<SegmentConfig> }): SegmentProperties {
+    const properties = SEGMENT_MAP.get(obj) ?? defaultSegmentProperties(obj.layout);
+    SEGMENT_MAP.set(obj, properties);
+    return properties;
+  },
+
+  getGraphProps(obj: SmartGraph<{}, {}> & { layout?: Partial<GraphProperties> }): GraphProperties {
+    const properties = GRAPH_MAP.get(obj) ?? defaultGraphProperties(obj.layout);
+    GRAPH_MAP.set(obj, properties);
+    return properties;
+  },
+
+  clearNodeProps(obj: Node) {
+    NODE_MAP.delete(obj);
+  },
+
+  clearEdgeProps(obj: Edge) {
+    EDGE_MAP.delete(obj);
+  },
+
+  clearSegmentProps(obj: Segment) {
+    SEGMENT_MAP.delete(obj);
+  },
+
+  clearGraphProps(obj: SmartGraph<{}, {}>) {
+    GRAPH_MAP.delete(obj);
+  },
+};

package/src/layout/properties.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview utilities to track properties for Agathon entities.
+ *
+ * The Agathon layout engine tracks numerous properties about a graph and its
+ * nodes, edges, and segments. Historically, these were bundled per instance in
+ * a property grab bag hidden behind a symbol. While quick to implement at the
+ * time, and it certainly gets the job done, it is unclear whether how this
+ * approach handles a variety of situations from performance or other stand
+ * points.
+ *
+ * This centralized property lookup tool lets clients of Agathon choose which
+ * mechanism works best for their workload.
+ */
+export { LAYOUT_SYMBOL_PROPERTIES_STRATEGY } from "./properties/symbol.ts";
+export { WEAK_MAP_PROPERTIES_STRATEGY } from "./properties/weak_map.ts";
+
+import type { Edge, Node, Segment, SmartGraph } from "../types.ts";
+import { LAYOUT_SYMBOL_PROPERTIES_STRATEGY } from "./properties/symbol.ts";
+import type {
+  EdgeConfig,
+  EdgeProperties,
+  GraphProperties,
+  NodeConfig,
+  NodeProperties,
+  PropertiesStrategy,
+  SegmentConfig,
+  SegmentProperties,
+} from "./types.ts";
+
+let propertyStrategy: PropertiesStrategy;
+
+/**
+ * Choose a global PropertiesStrategy to be used for all Agathon layout
+ * calculations.
+ */
+export function setPropertiesStrategy(strategy: PropertiesStrategy): void {
+  propertyStrategy = strategy;
+}
+
+/**
+ * Reset the PropertiesStrategy to be used for Agathon layout calculations.
+ */
+export function resetPropertiesStrategy(): void {
+  setPropertiesStrategy(LAYOUT_SYMBOL_PROPERTIES_STRATEGY);
+}
+
+resetPropertiesStrategy();
+
+/**
+ * Initialize layout properties, pulling values from the layout properties if
+ * provided for initial values.
+ */
+export function getNodeProps(obj: Node & { layout?: Partial<NodeConfig> }): NodeProperties {
+  return propertyStrategy.getNodeProps(obj);
+}
+
+/**
+ * Initialize layout properties for an edge, pulling values from the layout
+ * properties if provided for initial values.
+ */
+export function getEdgeProps(obj: Edge & { layout?: Partial<EdgeConfig> }): EdgeProperties {
+  return propertyStrategy.getEdgeProps(obj);
+}
+
+/**
+ * Initialize layout properties for a segment, pulling values from the layout
+ * properties if provided for initial values.
+ */
+export function getSegmentProps(
+  obj: Segment & { layout?: Partial<SegmentConfig> },
+): SegmentProperties {
+  return propertyStrategy.getSegmentProps(obj);
+}
+
+/**
+ * Initialize layout properties for a graph, pulling values from the layout
+ * properties if provided for initial values.
+ */
+export function getGraphProps(
+  obj: SmartGraph<{}, {}> & { layout?: Partial<GraphProperties> },
+): GraphProperties {
+  return propertyStrategy.getGraphProps(obj);
+}
+
+/**
+ * Clear layout properties for a node.
+ */
+export function clearNodeProps(obj: Node): void {
+  propertyStrategy.clearNodeProps(obj);
+}
+
+/**
+ * Clear layout properties for an edge.
+ */
+export function clearEdgeProps(obj: Edge): void {
+  propertyStrategy.clearEdgeProps(obj);
+}
+
+/**
+ * Clear layout properties for a segment.
+ */
+export function clearSegmentProps(obj: Segment): void {
+  propertyStrategy.clearSegmentProps(obj);
+}
+
+/**
+ * Clear layout properties for a graph.
+ */
+export function clearGraphProps(obj: SmartGraph<{}, {}>): void {
+  propertyStrategy.clearGraphProps(obj);
+}