@davidsouther/agathon 0.0.0-stage → 2026.11.1

package/src/layout/types.ts

@@ -0,0 +1,470 @@
+import type { Geometry } from "../geometry/types.ts";
+import type {
+  AttributeSet,
+  Bounds,
+  Box,
+  DiffableGraphElement,
+  Edge,
+  Node,
+  NodeId,
+  Point,
+  ReadonlySmartGraph,
+  Segment,
+  SmartGraph,
+} from "../types.ts";
+
+/**
+ * Properties to store client configuration values for a LayoutGraph.
+ */
+export interface LayoutGraphProperties {
+  layout?: Partial<GraphProperties>;
+  data?: AttributeSet;
+}
+
+/** Convenience type for a graph with an optional, partial property set. */
+export interface LayoutGraph extends SmartGraph<LayoutNode, LayoutEdge>, LayoutGraphProperties {}
+
+/**
+ * A ReadonlyLayoutGraph is a non-mutable interface for renderers, layouts, and
+ * other compute-only modules to use.
+ */
+export interface ReadonlyLayoutGraph
+  extends ReadonlySmartGraph<Readonly<LayoutNode>, Readonly<LayoutEdge>>,
+    Readonly<LayoutGraphProperties> {}
+
+/**
+ * Configuration settings for a force graph layout engine.
+ */
+export interface ForceGraphConfig {
+  linkDistance: number;
+  linkStrength: number;
+  charge: number;
+  chargeDistance: number;
+  collisionStrength: number;
+  theta: number;
+  friction: number;
+  collapse: boolean;
+  center: number;
+}
+
+/** User-setable properties for node layout calculations. */
+export interface NodeConfig {
+  /** Geometry of the node to cover during layout and rendering. */
+  geometry: Geometry;
+
+  // TODO: Refactor Hiererachical-specific properties
+
+  /** Rank is the row a node will get positioned on. */
+  rank: number;
+  /** When fixedRank is set, this node will not be adjusted during ranking. */
+  fixedRank: boolean;
+  /** Order specifies the order of nodes within a rank. */
+  order: number;
+}
+
+/**
+ * A NodeLayout contains all necessary internal information when calculating
+ * where to put a node in a particular layout.
+ */
+export interface NodeProperties extends NodeConfig {
+  /**
+   * When computing ranks, low and lim will be used for building the feasible
+   * spanning tree. When initially creating the spanning tree, lim is the
+   * postorder traversal number of the tree, and low is the smallest lim of a
+   * node's descendants. This makes testing descendants in a tree a pair of
+   * integer comparisons.
+   *
+   *     (1, 5)
+   *     /    \
+   *   (1, 3) (4, 4)
+   *   /    \
+   * (1, 1) (2, 2)
+   *
+   * See [Gansner] Figure 2.5 for a larger example.
+   */
+  low: number;
+  lim: number;
+  /**
+   * Virtual indicates this node was created at some point during the layout
+   * process for internal processing, and will be removed before finishing.
+   */
+  virtual: boolean | "border" | "edge" | "root";
+  virtualEdge?: Edge;
+  virtualEdgeLayout?: EdgeProperties;
+  top?: NodeId;
+  bottom?: NodeId;
+
+  /* Properties for force graph simulation */
+  vx?: number; // the node's current x velocity
+  vy?: number; // the node's current y velocity
+
+  /* Properties to use when fixing position or dragged. */
+  fx?: number; // the node's fixed x position
+  fy?: number; // the node's fixed y position
+  dragging?: boolean; // the node is being actively dragged; unset is false
+}
+
+/** Convenience type for a node with an optional, partial property set. */
+export interface LayoutNode extends Node, DiffableGraphElement {
+  expanded?: boolean;
+  layout?: Partial<NodeProperties>;
+  data?: AttributeSet;
+}
+
+/**
+ * User definable edge configuration properties.
+ */
+export interface EdgeConfig {
+  /**
+   * The minimum number of ranks this Edge must span. Defaults to 1, but forcing
+   * some edges longer can create interesting layouts.
+   */
+  minLength: number;
+  /**
+   * The weight of an edge forces stronger vertical alignment of that node.
+   * Consider these
+   */
+  weight: number;
+  /**
+   * When calculating ranks, cutValue is used as a heuristic for which edges to
+   * attempt to remove first when creating a minimum spanning tree.
+   */
+  cutValue: number;
+}
+
+/**
+ * An EdgeLayout has all necessary information on an edge when calculating a
+ * layout.
+ */
+export interface EdgeProperties extends EdgeConfig {
+  /** When removing cycles, some edges will get reversed. */
+  reversed: boolean;
+  /*
+   * When a node is reversed, this is the original edge to be restored.
+   */
+  original?: Edge;
+
+  /**
+   * As with virtual nodes, this edge was inserted by layout to normalize some
+   * operations.
+   */
+  nestingEdge: boolean;
+  points: Point[];
+}
+
+/** Convenience type for an edge with an optional, partial property set. */
+export interface LayoutEdge extends Edge, DiffableGraphElement {
+  layout?: Partial<EdgeProperties>;
+  data?: AttributeSet;
+}
+
+interface SegmentLabel<V extends string | number> {
+  /**
+   * Metric along the segment's path.
+   */
+  forward?: V;
+
+  /**
+   * Metric in the opposite direction to the segment's path.
+   */
+  reverse?: V;
+}
+
+/**
+ * Data model representing a metrics flow along a segment, following its path
+ * direction or the opposite direction. Objects of this class are bound to a
+ * single line of a label attached to a segment and are used to aggregate
+ * values originating from multiple links.
+ */
+export interface LabelAnnotation<T> {
+  rawValue: T;
+  formattedValue: string;
+  /** Whether the metric flows in the segment path direction. */
+  forward: boolean;
+  drawArrow: boolean;
+}
+
+/**
+ * User specified layout & rendering information for segments.
+ */
+export interface SegmentConfig {
+  metrics: SegmentLabel<number>;
+
+  annotations: SegmentLabel<string>;
+}
+
+/**
+ * Layout & rendering information for segments.
+ */
+export interface SegmentProperties extends SegmentConfig {
+  points: ReadonlyArray<Readonly<Point>>;
+
+  label: LabelProperties;
+}
+
+/**
+ * Properties to describe how to layout a label on a segment.
+ */
+export interface LabelProperties {
+  /**
+   * Where to place the label of the node, in the same coordinate space as
+   * `points`.
+   */
+  position: Point;
+
+  /**
+   * What angle, in degrees, to rotate the label.
+   */
+  rotation: number;
+
+  /**
+   * Tells us whether the label has been rendered with an additional rotation
+   * by 180 degrees to prevent upside-down text.
+   */
+  flippedBy180: boolean;
+}
+
+/**
+ * User-definable graph configuration properties.
+ */
+export interface GraphConfig {
+  /**
+   * The amount of separation between two ranks, in pixels. That is, a second
+   * row will be rankSep pixels below the bottom of the row above it.
+   */
+  rankSep: number;
+
+  /**
+   * The amount of separation between two nodes on the same rank, in pixels.
+   * That is, a second node will be nodeSep pixels after the node before it.
+   */
+  nodeSep: number;
+
+  /**
+   * The amount of "empty" space to leave for edges that span multiple ranks and
+   * cross between nodes.
+   */
+  edgeSep: number;
+
+  /**
+   * When laying out nodes, some minimum size is useful in several places.
+   */
+  baseRadius: number;
+
+  /**
+   * When laying out hulls, long labels can have improved overlap by providing
+   * some rotation. Specified in degrees.
+   */
+  hullRotation: number;
+
+  /**
+   * When laying out children, positions can either be absolute (default) or
+   * relative to the parent (with this flag).
+   */
+  childrenRelative: boolean;
+
+  /**
+   * Whether to bend long edges through virtual nodes, or make them always
+   * direct. Defaults to true.
+   */
+  bendLongEdges: boolean;
+
+  /**
+   * Number of items in a row before triggering staggered layout.
+   */
+  staggerRows: number;
+
+  /**
+   * When set, write timing information for each of the major steps to the
+   * console using `console.time`.
+   */
+  timing: boolean;
+
+  /**
+   * When set, write debugging information after each step of layout.
+   */
+  printDebug: boolean;
+}
+
+/**
+ * A GraphLayout has all necessary information on a graph when calculating a
+ * layout.
+ */
+export interface GraphProperties extends GraphConfig {
+  /** The NodeId of the inserted virtual root */
+  root?: NodeId;
+
+  /** The NodeId of the inserted nesting root, to track  */
+  nestingRoot?: NodeId;
+
+  /**
+   * When inserting virtual nodes, nodeRankFactor describes how many "virtual"
+   * ranks were inserted between each original set of ranks.
+   */
+  nodeRankFactor: number;
+
+  /**
+   * When calculating ordering cross-cutting, having consistent sized ranks is
+   * helpful. Between ranking and ordering, virtual nodes are inserted at each
+   * (rank, order) pair that does not already have a node in it. To clean these
+   * up later, each of the highest-ranked nodes are tracked to remove them when
+   * finished ordering.
+   */
+  virtualChains?: Set<NodeId>;
+
+  /**
+   * Cached value of FAS for decycling. Result of initial run of greedyFas() in
+   * acyclic.ts::decycle() is cached here, and subsequently accessed in the same
+   * function.
+   */
+  fas?: Edge[];
+
+  /**
+   * Cached layout positions of virtual nodes.  Results of rank() and order()
+   * from layout()'s first run get cached in virtualNodeLayout, and then used as
+   * a part of simplified partialLayout() pipeline.
+   *
+   * virtualNodeLayout is initialized in
+   * layout() => virtualNodeLayoutCache(...,'write'), and subsequently accessed
+   * in partialLayout() => virtualNodeLayoutCache(..., 'read').
+   */
+  virtualNodeLayout?: Map<NodeId, { rank: number; order: number }>;
+}
+
+/**
+ * Rendeing layout position information for segments.
+ */
+export interface SegmentPosition {
+  /**
+   * Points the segment must pass through. The first and last points are the
+   * coordinates on the edge of the source and target node foreground circles
+   * that are closest to the adjacent point in the array. Intermediate values
+   * are specific points the line segment should pass through.
+   *
+   * Set after layout is complete.
+   */
+  points: Point[];
+
+  label: LabelProperties;
+}
+
+/**
+ * PropertiesStrategy are a collection of functions which control how to access
+ * properties on an Agathon entity.
+ */
+export interface PropertiesStrategy {
+  getNodeProps(obj: Node & { layout?: Partial<NodeProperties> }): NodeProperties;
+  getEdgeProps(obj: Edge & { layout?: Partial<EdgeProperties> }): EdgeProperties;
+  getSegmentProps(obj: Segment & { layout?: Partial<SegmentProperties> }): SegmentProperties;
+  getGraphProps(obj: SmartGraph<{}, {}> & { layout?: Partial<GraphProperties> }): GraphProperties;
+  clearNodeProps(obj: Node): void;
+  clearEdgeProps(obj: Edge): void;
+  clearSegmentProps(obj: Segment): void;
+  clearGraphProps(obj: SmartGraph<{}, {}>): void;
+}
+
+/**
+ * A GraphLayout is used by the Topology Graph renderer to decide where and how
+ * to position nodes and segments. The renderer uses a LayoutManager's run
+ * method to either update an existing or get a new instance of GraphLayout,
+ * which it then uses to set node and segment positions. The renderer will then
+ * call `run` with LayoutChange items to change, update, or otherwise modify the
+ * generated layout.
+ */
+export interface GraphLayout {
+  readonly panOffset: Point;
+  readonly box: Box;
+  readonly zoomLevel: number;
+  readonly draggable: boolean;
+  readonly isDragging: boolean;
+
+  didUpdate(entity: NodeId | Segment<LayoutEdge>): boolean;
+  getNodePosition(node: NodeId): Geometry;
+  getSegmentPosition(segment: Segment<LayoutEdge>): SegmentPosition;
+
+  isNodeVisible(node: NodeId): boolean;
+  isSegmentVisible(segment: Segment<LayoutEdge>): boolean;
+}
+
+/**
+ * A LayoutManager is the client-created and configured class which provides a
+ * method, `run`, which takes a graph and collection of LayoutChanges to
+ * apply.
+ */
+export interface LayoutManager {
+  /** Run layout calculations for a graph. */
+  run(graph: ReadonlyLayoutGraph): void;
+
+  /**
+   * Mark the layout as finished. Position will not change until the next run or
+   * update. Calls to didUpdate between runFinished and the next run or update
+   * will return false.
+   */
+  runFinished(): void;
+
+  /** An instance of the current layout. */
+  readonly layout: GraphLayout;
+
+  /**
+   * Mark the height and width of the primary viewport, which is assumed to
+   * always be rooted at <0, 0>. Using a Manager should only include one primary
+   * viewport.
+   */
+  setPageBounds(bounds: Bounds): void;
+
+  /** Increase the cumulative graph panning by `delta`.  */
+  moveGraphBy(delta: Point): void;
+
+  /** Resets the graph panning to {0,0} */
+  resetGraphPan(): void;
+
+  /**
+   * Adjust pan so that given node is centered in the graph. If node is not
+   * renderable, or is not present, no change happens.
+   */
+  panToNode(id: NodeId): void;
+
+  /** Resets the graph zoom level to 0 */
+  resetGraphZoom(): void;
+
+  /**
+   * Indicate to the layout manager that the graph intends to start moving a
+   * node. Future calls to moveNodeBy should be against this node, until
+   * stopMovingNode is called. If no node is being moved, and moveNodeBy is
+   * called, startMovingNode is implicitly called. If moveNodeBy uses a node
+   * that isn't the currently moving node, stopMovingNode is called as well.
+   */
+  startMovingNode(id: NodeId): void;
+
+  /** Indicate that a node is finished moving. */
+  stopMovingNode(): void;
+
+  /** Move a node by a delta offset. */
+  moveNodeBy(id: NodeId, delta: Point): void;
+
+  /**
+   * Re-run the layout algorithm as if this node has just been expanded.  Should
+   * be called after a node goes from being unexpanded to being expanded. This
+   * does NOT set the given node to be expanded if it is not already, it merely
+   * informs the layout algorithm to behave as if that node just became
+   * expanded.
+   */
+  runLayoutAfterNodeExpanded(id: NodeId): void;
+
+  /**
+   *  Re-run the layout algorithm as if this node has just been collapsed. See
+   * runLayoutAfterNodeExpanded for more details.
+   */
+  runLayoutAfterNodeCollapsed(id: NodeId): void;
+
+  /**
+   * Apply fisheye zooming to all nodes. If not provided, uses the center of
+   * the visible graph as the target point.
+   */
+  zoomIn(center?: Point): void;
+  zoomOut(center?: Point): void;
+
+  /** LayoutManagers can inform listeners when the layout has been updated. */
+  registerUpdateCallback(cb: () => void): void;
+  unregisterUpdateCallback(cb: () => void): void;
+}