@davidsouther/agathon 0.0.0-stage → 2026.11.1

package/src/layout/manager/manager.ts

@@ -0,0 +1,425 @@
+import { assertExists } from "../../assert.ts";
+import type { Geometry } from "../../geometry/types.ts";
+import { segmentId } from "../../tsabre/graph.ts";
+import type { Bounds, Box, NodeId, Point, Segment, SegmentId } from "../../types.ts";
+import type {
+  GraphLayout,
+  LayoutEdge,
+  LayoutGraph,
+  LayoutManager,
+  LayoutNode,
+  SegmentPosition,
+  SegmentProperties,
+} from "../types.ts";
+import { findSegmentNeighborhood, getNodeProps, getSegmentProps, isSegment } from "../util.ts";
+
+import { ChildManager } from "./child_manager.ts";
+import { DragManager, NoopDragManager } from "./drag_manager.ts";
+import { NoopPanManager, PanManager } from "./pan_manager.ts";
+import { VisibilityManager } from "./visibility_manager.ts";
+import { NoopZoomManager, ZoomManager } from "./zoom_manager.ts";
+
+/**
+ * NoopLayoutManager provides the minimal functionality for handling graph
+ * layouts, but does not include mechanisms for pan/zoom/drag behaviors. There
+ * is a lot of machinery between asking for node positions in `doLayout` and
+ * having the full featureset for the renderer, including visibility culling,
+ * renderability checks, segment positioning, etc. This class gives the base
+ * minimum with no interaction functionality, rather than needing to turn off
+ * interactions in future subclasses. Most clients should use
+ * AbstractLayoutManager.
+ */
+export abstract class NoopLayoutManager implements LayoutManager, GraphLayout {
+  protected readonly nodePositions = new Map<NodeId, Geometry>();
+  protected readonly segmentPositions = new Map<string, SegmentPosition>();
+  protected readonly entityTouched = new Set<NodeId | SegmentId>();
+
+  readonly layout = this;
+  private deepestExpandedNode = 0;
+  get depth(): number {
+    return this.deepestExpandedNode;
+  }
+
+  get zoomLevel(): number {
+    return this.zoom.level;
+  }
+
+  get box(): Box {
+    return this.pan.box;
+  }
+
+  get center(): Point {
+    return this.pan.center;
+  }
+
+  get panOffset(): Point {
+    return this.pan.panOffset;
+  }
+
+  get pageBounds(): Bounds {
+    return this.pan.pageBounds;
+  }
+
+  get draggable(): boolean {
+    return this.drag.draggable;
+  }
+
+  get isDragging(): boolean {
+    return this.drag.isDragging();
+  }
+
+  // These internal helpers handle the individual parts of layout management.
+
+  // pan handles positioning the viewbox relative to the graph layout.
+  readonly pan = this.buildPanManager();
+  // drag handles moving individual nodes around the layout.
+  readonly drag = this.buildDragManager();
+  // visibility handles calculations for whether an item is visible in the view.
+  readonly visibility = this.buildVisibilityManager();
+  readonly zoom = this.buildZoomManager();
+  readonly children = this.buildChildManager();
+
+  // Update listeners
+  private readonly updateCallbacks = new Set<() => void>();
+
+  public graph: LayoutGraph;
+  constructor(graph: LayoutGraph) {
+    this.graph = graph;
+  }
+
+  // buildPanManager, buildDragManager, and buildVisibilityManager allow
+  // extending classes to replace the sub-manager behaviors.
+
+  protected buildPanManager(): PanManager {
+    return new NoopPanManager(this);
+  }
+
+  protected buildDragManager(): DragManager {
+    return new NoopDragManager(this);
+  }
+
+  protected buildVisibilityManager(): VisibilityManager {
+    return new VisibilityManager(this);
+  }
+
+  protected buildChildManager(): ChildManager {
+    return new ChildManager(this);
+  }
+
+  protected buildZoomManager(): ZoomManager {
+    return new NoopZoomManager(this);
+  }
+
+  /**
+   * doLayout allows extending classes to use their own calculations to lay out
+   * nodes in the graph. It is responsible for setting the x, y, and radius node
+   * properties for every node in an expanded parent. Additionally, it can
+   * assign points: Point to each top-level segment, to make bendy rather than
+   * straight edges.
+   * @param triggeredNodeId - See the same parameter for run()
+   */
+  protected abstract doLayout(triggeredNodeId?: NodeId): void;
+
+  /**
+   * Rerun the layout.
+   * @param graph - The graph that is being recalculated
+   * @param triggeredNodeId - ID of the expanded/collapsed node. Each such event
+   * triggers a partial layout recalculation. If no event fired and/or we need
+   * the complete layout recalculation, no triggeredNodeId is passed.
+   * @param panToCenter - Whether or not to pan the viewport to center after
+   * layout.
+   */
+  run(graph: LayoutGraph, triggeredNodeId?: NodeId, panToCenter = true): void {
+    this.graph = graph;
+
+    this.nodePositions.clear();
+    this.segmentPositions.clear();
+    this.entityTouched.clear();
+    this.deepestExpandedNode = 0;
+
+    this.doLayout(triggeredNodeId);
+    this.updateAt(undefined, panToCenter);
+  }
+
+  runFinished(): void {
+    this.entityTouched.clear();
+  }
+
+  setPageBounds(pageBounds: Bounds): void {
+    this.pan.setPageBounds(pageBounds);
+    this.updateVisibility();
+  }
+
+  moveGraphBy(move: Point): void {
+    this.pan.moveGraphBy(move);
+    this.updateVisibility();
+  }
+
+  panToNode(id: NodeId): void {
+    if (this.graph.hasNode(id) && this.isNodeRenderable(id)) {
+      this.pan.panToPoint(this.getNodePosition(id));
+      this.updateVisibility();
+    }
+  }
+
+  resetGraphPan(): void {
+    this.pan.reset();
+    this.updateAt();
+  }
+
+  resetGraphZoom(): void {
+    this.zoom.zoom(0);
+    this.updateAt();
+  }
+
+  updateVisibility(): void {
+    this.visibility.update();
+  }
+
+  moveNodeBy(id: NodeId, delta: Point): void {
+    this.drag.moveNodeBy(id, this.zoom.dragAmount(delta));
+  }
+
+  startMovingNode(id: NodeId): void {
+    this.drag.startMovingNode(id);
+  }
+
+  stopMovingNode(): void {
+    this.drag.stopMovingNode();
+  }
+
+  didUpdate(entity: NodeId | Segment<LayoutEdge>): boolean {
+    const id = isSegment(entity) ? segmentId(entity) : entity;
+    return this.entityTouched.has(id);
+  }
+
+  runLayoutAfterNodeExpanded(id: NodeId): void {
+    this.children.runLayoutAfterNodeExpanded(id);
+  }
+
+  runLayoutAfterNodeCollapsed(id: NodeId): void {
+    this.children.runLayoutAfterNodeCollapsed(id);
+  }
+
+  /**
+   * Zoom the graph in one zoom level. If provided, point is treated as a
+   * position relative to the page bounds (which start at <0,0>, usually the
+   * top-left corner of the containing SVG) to keep at a consistent screen
+   * location while zooming, with everything moving away from that point.
+   */
+  zoomIn(point?: Point): void {
+    this.zoom.zoomIn(point);
+  }
+
+  /**
+   * Zoom the graph out one zoom level. If provided, point is treated as a
+   * position relative to the page bounds (which start at <0,0>, usually the
+   * top-left corner of the containing SVG) to keep at a consistent screen
+   * location while zooming, with everything moving towards from that point.
+   */
+  zoomOut(point?: Point): void {
+    this.zoom.zoomOut(point);
+  }
+
+  hasNodePosition(id: NodeId): boolean {
+    return this.nodePositions.has(id);
+  }
+
+  getNodePosition(id: NodeId): Geometry {
+    const msg = `AbstractLayoutManager::getNodePosition ${id} missing`;
+    return assertExists(this.nodePositions.get(id), msg);
+  }
+
+  hasSegmentPosition(segment: Segment<LayoutEdge>): boolean {
+    const id = segmentId(segment);
+    return this.segmentPositions.has(id);
+  }
+
+  getSegmentPosition(segment: Segment<LayoutEdge>): Readonly<SegmentPosition> {
+    const id = segmentId(segment);
+    const msg = `AbstractLayoutManager::getSegmentPosition ${id} missing`;
+    return assertExists(this.segmentPositions.get(id), msg);
+  }
+
+  isNodeVisible(id: NodeId): boolean {
+    return this.visibility.isNodeVisible(id) || this.drag.isDragging(id);
+  }
+
+  isSegmentVisible(segment: Segment<LayoutEdge>): boolean {
+    return this.visibility.isSegmentVisible(segment);
+  }
+
+  /**
+   * A node is renderable if all its ancestors are expanded.
+   */
+  isNodeRenderable(id: NodeId): boolean {
+    // Ancestors returns id as the first item
+    for (const pid of this.graph.ancestors(id).slice(1)) {
+      if (!this.getNode(pid).expanded) return false;
+    }
+    return true;
+  }
+
+  /**
+   * A segment is renderable if it is a rising segment and the target is
+   * expanded, or if it is a level segment and the parent is expanded.
+   */
+  isSegmentRenderable(segment: Segment): boolean {
+    return this.isNodeRenderable(segment.source);
+  }
+
+  getNode(id: NodeId): LayoutNode {
+    const msg = `AbstractLayoutManager::getNode: ${id} missing`;
+    return assertExists(this.graph.node(id), msg);
+  }
+
+  updateAt(root?: NodeId, panToCenter = false): void {
+    this.updateNodes(root);
+    this.updateSegments(root);
+
+    // Calculate the new center of the page
+    if (panToCenter) {
+      this.pan.updateCenter();
+      this.pan.updateOffset();
+    }
+
+    this.updateVisibility();
+    this.callUpdateCallbacks();
+  }
+
+  updateLayout(root?: NodeId, panToCenter?: boolean): void {
+    this.doLayout();
+    this.updateAt(root, panToCenter);
+  }
+
+  registerUpdateCallback(cb: () => void): void {
+    this.updateCallbacks.add(cb);
+  }
+
+  unregisterUpdateCallback(cb: () => void): void {
+    this.updateCallbacks.delete(cb);
+  }
+
+  protected updateNodes(root?: NodeId): void {
+    const traversal = root ? [root] : this.graph.children();
+    const depth = root ? this.graph.ancestors(root).length : 1;
+    for (const id of traversal) {
+      this.updateNode(id, depth);
+    }
+  }
+
+  protected updateNode(id: NodeId, depth: number): void {
+    if (id && !this.isNodeRenderable(id)) {
+      this.clearNode(id);
+      return;
+    }
+
+    this.deepestExpandedNode = Math.max(this.deepestExpandedNode, depth);
+
+    // Update nodes from bottom to top, to have children resolved before
+    // parent hulls.
+    for (const child of this.graph.children(id)) {
+      this.updateNode(child, depth + 1);
+    }
+
+    if (!id) return;
+
+    const node = this.getNode(id);
+    const position = getNodeProps(node).geometry.clone();
+    // Remove drag from clone, to simplify zoom later
+    position.move((position as Geometry & { dragPt: Point }).dragPt);
+    position.dragTo({ x: 0, y: 0 });
+    this.assignNode(node, position);
+  }
+
+  protected clearNode(id: NodeId): void {
+    this.nodePositions.delete(id);
+    this.entityTouched.delete(id);
+  }
+
+  protected assignNode(node: LayoutNode, position: Geometry): void {
+    position = this.zoom.diffuseNodePosition(node, position);
+    this.nodePositions.set(node.id, position);
+    this.entityTouched.add(node.id);
+  }
+
+  protected updateSegments(id?: NodeId): void {
+    const segments = findSegmentNeighborhood(this.graph, id);
+    const completed = new Set<Segment>();
+
+    // Assign segments top to bottom, so that upper segments have always been
+    // assigned their positions before lower segments. Lower segments need the
+    // position of their upper segments to calculate their target position, so
+    // going from the top ensures the upper segments are always set first.
+    const assignSegmentTree = (segment: Segment<LayoutEdge>) => {
+      if (completed.has(segment)) return;
+      completed.add(segment);
+      if (segment.next) assignSegmentTree(segment.next);
+      if (this.isSegmentRenderable(segment)) {
+        this.assignSegment(segment, getSegmentProps(segment));
+      }
+    };
+
+    for (const segment of segments) {
+      assignSegmentTree(segment);
+    }
+  }
+
+  protected assignSegment(segment: Segment<LayoutEdge>, pos: SegmentProperties): void {
+    const id = segmentId(segment);
+
+    // update existing values, when present, to cut down on object allocations.
+    if (this.segmentPositions.has(id)) {
+      const current = this.segmentPositions.get(id)!;
+      current.points = [...pos.points];
+      current.label.position.x = pos.label.position.x;
+      current.label.position.y = pos.label.position.y;
+      current.label.rotation = pos.label.rotation;
+      current.label.flippedBy180 = pos.label.flippedBy180;
+    } else {
+      this.segmentPositions.set(id, {
+        points: [...pos.points],
+        label: {
+          position: {
+            x: pos.label.position.x,
+            y: pos.label.position.y,
+          },
+          rotation: pos.label.rotation,
+          flippedBy180: pos.label.flippedBy180,
+        },
+      });
+    }
+
+    // Apply zoom transformations to local data copy
+    this.segmentPositions.set(
+      id,
+      this.zoom.diffuseSegmentPosition(segment, this.segmentPositions.get(id)!),
+    );
+
+    this.entityTouched.add(id);
+  }
+
+  protected callUpdateCallbacks(): void {
+    for (const cb of this.updateCallbacks) {
+      cb();
+    }
+  }
+}
+
+/**
+ * AbstractLayoutManager tracks node and segment positions for a LayoutGraph,
+ * allowing sub classes to define the mechanism to choose the position of items.
+ */
+export abstract class AbstractLayoutManager extends NoopLayoutManager {
+  protected override buildPanManager(): PanManager {
+    return new PanManager(this);
+  }
+
+  protected override buildDragManager(): DragManager {
+    return new DragManager(this);
+  }
+
+  protected override buildZoomManager(): ZoomManager {
+    return new ZoomManager(this);
+  }
+}

package/src/layout/manager/pan_manager.ts

@@ -0,0 +1,146 @@
+import type { Bounds, Box, Point } from "../../types.ts";
+
+import type { NoopLayoutManager } from "./manager.ts";
+
+/**
+ * A PanManager which tracks pan offset and center of graph, but does not
+ * update offset on interactions.
+ */
+export class NoopPanManager {
+  // The cumulative pan offset
+  protected pan: Point = { x: 0, y: 0 };
+  // The calculated center of the graph
+  center: Point = { x: 0, y: 0 };
+  // The total bounds of the graph covered
+  bounds: Box = { x: 0, y: 0, width: 0, height: 0 };
+  // The bounds of the primary viewing window this graph is in
+  pageBounds: Bounds = { height: 0, width: 0 };
+  // The vector offset to move `center` to the middle of the `pageBounds`
+  protected offset: Point = { x: 0, y: 0 };
+
+  get box(): Box {
+    return {
+      x: -this.panOffset.x,
+      y: -this.panOffset.y,
+      width: this.pageBounds.width,
+      height: this.pageBounds.height,
+    };
+  }
+
+  get panOffset(): Point {
+    return {
+      x: this.offset.x + this.pan.x,
+      y: this.offset.y + this.pan.y,
+    };
+  }
+
+  protected readonly layoutManager: NoopLayoutManager;
+  constructor(layoutManager: NoopLayoutManager) {
+    this.layoutManager = layoutManager;
+  }
+
+  /**
+   * Given a point relative to the pageBounds, calculate the equivalent layout
+   * coordinate by first removing the panOffset, and then applying the reverse
+   * zoom diffusion to project from zoomed space to layout space.
+   */
+  pagePointToGraphPoint(point: Point): Point {
+    return this.layoutManager.zoom.undiffusePoint({
+      x: point.x - this.panOffset.x,
+      y: point.y - this.panOffset.y,
+    });
+  }
+
+  graphPointToPagePoint(point: Point): Point {
+    const p = this.layoutManager.zoom.diffusePoint(point);
+    return {
+      x: this.panOffset.x + p.x,
+      y: this.panOffset.y + p.y,
+    };
+  }
+
+  moveGraphBy(move: Point): void {
+    // noop
+  }
+
+  panToPoint(graphPoint: Point): void {
+    // noop
+  }
+
+  reset(): void {
+    this.pan.x = this.pan.y = 0;
+    this.updateOffset();
+  }
+
+  setPageBounds(pageBounds: Bounds): void {
+    this.pageBounds = pageBounds;
+    this.updateOffset();
+  }
+
+  /**
+   * Find the simple geometric center of the graph by looking at the points +/-
+   * radius of all top-level nodes.
+   */
+  updateCenter(): void {
+    let minX = Number.MAX_SAFE_INTEGER;
+    let minY = Number.MAX_SAFE_INTEGER;
+    let maxX = Number.MIN_SAFE_INTEGER;
+    let maxY = Number.MIN_SAFE_INTEGER;
+
+    for (const id of this.layoutManager.graph.children()) {
+      const geometry = this.layoutManager.getNodePosition(id);
+
+      // Round to 0 (cast to int then bitwise or) for numerical robustness
+      minX = Math.min(minX, geometry.x - geometry.radius) | 0;
+      minY = Math.min(minY, geometry.y - geometry.radius) | 0;
+      maxX = Math.max(maxX, geometry.x + geometry.radius) | 0;
+      maxY = Math.max(maxY, geometry.y + geometry.radius) | 0;
+    }
+
+    if (minX > maxX) [minX, maxX] = [maxX, minX];
+    if (minY > maxY) [minY, maxY] = [maxY, minY];
+
+    this.bounds.x = minX;
+    this.bounds.width = maxX - minX;
+    this.bounds.y = minY;
+    this.bounds.height = maxY - minY;
+
+    // Distribute the division for better numerical stability
+    this.center.x = (maxX / 2 + minX / 2) | 0;
+    this.center.y = (maxY / 2 + minY / 2) | 0;
+  }
+
+  updateOffset(): void {
+    // offset is the vector which moves the center of the layout C to the
+    // center of the graph bounds B or O = B - C.
+    this.offset = {
+      x: this.pageBounds.width / 2 - this.center.x,
+      y: this.pageBounds.height / 2 - this.center.y,
+    };
+  }
+}
+
+/** A class to delegate box panning management for layout mananagers. */
+export class PanManager extends NoopPanManager {
+  constructor(layoutManager: NoopLayoutManager) {
+    super(layoutManager);
+  }
+
+  override moveGraphBy(move: Point): void {
+    this.pan.x += move.x;
+    this.pan.y += move.y;
+  }
+
+  override panToPoint(graphPoint: Point): void {
+    // Calculate a new pan which will put this graph point in the center of the
+    // pageBounds, N = (B - P) - O
+    const zoomPoint = this.layoutManager.zoom.diffusePoint(graphPoint);
+    const b = {
+      x: this.pageBounds.width / 2 - zoomPoint.x,
+      y: this.pageBounds.height / 2 - zoomPoint.y,
+    };
+
+    this.pan.x = b.x - this.offset.x;
+    this.pan.y = b.y - this.offset.y;
+  }
+}

package/src/layout/manager/visibility_manager.ts

@@ -0,0 +1,84 @@
+import { circleIntersectsBox, lineIntersectsBox } from "../../geometry/box.ts";
+import { segmentId } from "../../tsabre/graph.ts";
+import type { NodeId, Point, Segment, SegmentId } from "../../types.ts";
+import type { LayoutEdge } from "../types.ts";
+
+import type { NoopLayoutManager } from "./manager.ts";
+
+/** A class to delegate visibility checking for layout managers. */
+export class VisibilityManager {
+  protected readonly entityVisible = new Map<NodeId | SegmentId, boolean>();
+
+  protected get offset(): Point {
+    return {
+      x: -this.layoutManager.panOffset.x,
+      y: -this.layoutManager.panOffset.y,
+    };
+  }
+
+  protected readonly layoutManager: NoopLayoutManager;
+  constructor(layoutManager: NoopLayoutManager) {
+    this.layoutManager = layoutManager;
+  }
+
+  isNodeVisible(id: NodeId): boolean {
+    return this.entityVisible.get(id) || false;
+  }
+
+  isSegmentVisible(segment: Segment<LayoutEdge>): boolean {
+    if (!this.layoutManager.graph.isTopSegment(segment)) return true;
+    const id = segmentId(segment);
+    return this.entityVisible.get(id) || false;
+  }
+
+  update(): void {
+    const graph = this.layoutManager.graph;
+    for (const id of graph.children()) {
+      this.entityVisible.set(id, this.nodeVisibility(id));
+    }
+
+    // lower level segments are either renderered or not based on the hull,
+    // and don't need visibility checks.
+    for (const segment of graph.topSegments) {
+      const id = segmentId(segment);
+      this.entityVisible.set(id, this.segmentVisibility(segment));
+    }
+  }
+
+  /**
+   * A node is visible when it's top level, or its parent is expanded. If
+   * (x, y, r) are provided, a node is visible when any part of it is in page
+   * bounds.
+   */
+  private nodeVisibility(id: NodeId): boolean {
+    const pid = this.layoutManager.graph.parent(id);
+    // Children use parent visibility
+    if (this.layoutManager.graph.hasNode(pid)) return this.nodeVisibility(pid);
+
+    // If the node hasn't been lain out yet, it's not visible.
+    if (!this.layoutManager.hasNodePosition(id)) return false;
+
+    const position = this.layoutManager.getNodePosition(id);
+    if (!position) return false;
+    return circleIntersectsBox(
+      position,
+      position.radius,
+      this.offset,
+      this.layoutManager.pageBounds,
+    );
+  }
+
+  protected segmentVisibility(segment: Segment<LayoutEdge>): boolean {
+    // The segment is top level, check if its path passes through the
+    // bounding box.
+    if (!this.layoutManager.hasSegmentPosition(segment)) return false;
+    const segmentPosition = this.layoutManager.getSegmentPosition(segment);
+    const { points } = segmentPosition;
+    for (let i = 0; i < points.length - 1; i++) {
+      if (lineIntersectsBox(points[i], points[i + 1], this.offset, this.layoutManager.pageBounds)) {
+        return true;
+      }
+    }
+    return false;
+  }
+}