@statelyai/layout 0.0.1 → 0.0.3

package/src/spore.ts

@@ -0,0 +1,103 @@
+import type { Graph, VisualGraph, VisualNode } from "@statelyai/graph";
+import { getNodeSize, type LayoutOptions } from "@statelyai/graph/layout";
+import { getFixedLayout } from "./fixed";
+import type { LayoutPadding } from "./layered";
+import type { LayoutAlgorithm } from "./types";
+
+export interface SporeLayoutOptions extends Pick<LayoutOptions, "direction" | "measure"> {
+  spacing?: number;
+  padding?: number | Partial<LayoutPadding>;
+}
+
+function getPadding(value: SporeLayoutOptions["padding"]): LayoutPadding {
+  if (typeof value === "number") {
+    return { top: value, right: value, bottom: value, left: value };
+  }
+  return {
+    top: value?.top ?? 0,
+    right: value?.right ?? 0,
+    bottom: value?.bottom ?? 0,
+    left: value?.left ?? 0,
+  };
+}
+
+function getSporeLayout<N, E, G, P>(
+  graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>,
+  options: SporeLayoutOptions,
+  compact: boolean,
+): VisualGraph<N, E, G, P> {
+  const spacing = options.spacing ?? 20;
+  const padding = getPadding(options.padding);
+  const nodes: VisualNode<N, P>[] = [];
+
+  graph.nodes.forEach((node, index) => {
+    const size = getNodeSize(node, options);
+    const previous = graph.nodes[index - 1];
+    const placedPrevious = nodes[index - 1];
+    if (!previous || !placedPrevious) {
+      nodes.push({
+        ...node,
+        x: padding.left,
+        y: padding.top,
+        ...size,
+      } as VisualNode<N, P>);
+      return;
+    }
+    const deltaX = (node.x ?? 0) - (previous.x ?? 0);
+    const deltaY = (node.y ?? 0) - (previous.y ?? 0);
+    const requiredX = placedPrevious.width + spacing;
+    const requiredY = placedPrevious.height + spacing;
+    const distance = (delta: number, required: number): number => {
+      if (delta === 0) return 0;
+      const magnitude = compact ? required : Math.max(Math.abs(delta), required);
+      return Math.sign(delta) * magnitude;
+    };
+    nodes.push({
+      ...node,
+      x: placedPrevious.x + distance(deltaX, requiredX),
+      y: placedPrevious.y + distance(deltaY, requiredY),
+      ...size,
+    } as VisualNode<N, P>);
+  });
+
+  return getFixedLayout({ ...graph, nodes }, { direction: options.direction ?? graph.direction });
+}
+
+/** Compact an existing layout while preserving its relative directions. */
+export function getSporeCompactionLayout<N, E, G, P>(
+  graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>,
+  options: SporeLayoutOptions = {},
+): VisualGraph<N, E, G, P> {
+  return getSporeLayout(graph, options, true);
+}
+
+/** Remove overlap while preserving existing distances that already fit. */
+export function getSporeOverlapRemovalLayout<N, E, G, P>(
+  graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>,
+  options: SporeLayoutOptions = {},
+): VisualGraph<N, E, G, P> {
+  return getSporeLayout(graph, options, false);
+}
+
+function algorithm(
+  id: "sporeCompaction" | "sporeOverlap",
+  compact: boolean,
+): LayoutAlgorithm<SporeLayoutOptions> {
+  return {
+    id,
+    capabilities: {
+      full: true,
+      incremental: false,
+      partial: false,
+      routeOnly: false,
+      hierarchy: false,
+      ports: true,
+    },
+    layout(graph, options) {
+      return getSporeLayout(graph, options ?? {}, compact);
+    },
+  };
+}
+
+export const sporeCompactionAlgorithm = algorithm("sporeCompaction", true);
+export const sporeOverlapRemovalAlgorithm = algorithm("sporeOverlap", false);

package/src/types.ts

@@ -0,0 +1,84 @@
+import type { Graph, GraphPatch, VisualGraph } from "@statelyai/graph";
+
+export type AnyGraph = Graph<unknown, unknown, unknown, unknown>;
+
+export type LayoutDirection = "up" | "down" | "left" | "right";
+
+export type LayoutScope =
+  | { mode: "full" }
+  | {
+      mode: "incremental";
+      previous: VisualGraph;
+    }
+  | {
+      mode: "partial";
+      previous: VisualGraph;
+      nodeIds: readonly string[];
+    }
+  | {
+      mode: "route-only";
+      previous: VisualGraph;
+      edgeIds?: readonly string[];
+    };
+
+export interface LayoutDiagnostic {
+  severity: "info" | "warning" | "error";
+  code: string;
+  message: string;
+  entityIds?: readonly string[];
+  phase?: string;
+}
+
+export interface LayoutPhaseMetrics {
+  id: string;
+  durationMs: number;
+}
+
+export interface LayoutMetrics {
+  durationMs: number;
+  nodeCount: number;
+  edgeCount: number;
+  phases: readonly LayoutPhaseMetrics[];
+}
+
+export interface LayoutCapabilities {
+  full: boolean;
+  incremental: boolean;
+  partial: boolean;
+  routeOnly: boolean;
+  hierarchy: boolean;
+  ports: boolean;
+}
+
+export interface LayoutAlgorithm<Options = unknown> {
+  readonly id: string;
+  readonly capabilities: LayoutCapabilities;
+  layout<N, E, G, P>(
+    graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>,
+    options: Options,
+    context: LayoutExecutionContext,
+  ): VisualGraph<N, E, G, P> | Promise<VisualGraph<N, E, G, P>>;
+}
+
+export interface LayoutExecutionContext {
+  readonly scope: LayoutScope;
+  readonly signal?: AbortSignal;
+  readonly diagnostics: LayoutDiagnostic[];
+  measurePhase<T>(id: string, run: () => T): T;
+  throwIfAborted(): void;
+}
+
+export interface LayoutRequest<N = unknown, E = unknown, G = unknown, P = unknown, O = unknown> {
+  graph: Graph<N, E, G, P> | VisualGraph<N, E, G, P>;
+  algorithm?: string | LayoutAlgorithm<O>;
+  options?: O;
+  scope?: LayoutScope;
+  signal?: AbortSignal;
+}
+
+export interface LayoutResult<N = unknown, E = unknown, G = unknown, P = unknown> {
+  graph: VisualGraph<N, E, G, P>;
+  patches: readonly GraphPatch<N, E>[];
+  diagnostics: readonly LayoutDiagnostic[];
+  metrics: LayoutMetrics;
+}