elkrb 1.0.0

data/examples/layout_constraints_demo.rb

@@ -0,0 +1,272 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/elkrb"
+
+puts "=" * 70
+puts "ElkRb Layout Constraints Demonstration"
+puts "=" * 70
+puts
+
+# Example 1: Fixed Position Constraint
+puts "Example 1: Fixed Position - API Gateway stays at top center"
+puts "-" * 70
+
+graph1 = Elkrb::Graph::Graph.new(id: "fixed_example")
+
+# API Gateway fixed at (500, 100)
+gateway = Elkrb::Graph::Node.new(
+  id: "gateway",
+  width: 120,
+  height: 60,
+  x: 500,
+  y: 100,
+  constraints: Elkrb::Graph::NodeConstraints.new(fixed_position: true),
+)
+
+# Other services positioned automatically
+auth = Elkrb::Graph::Node.new(id: "auth", width: 100, height: 60)
+user = Elkrb::Graph::Node.new(id: "user", width: 100, height: 60)
+
+graph1.children = [gateway, auth, user]
+graph1.edges = [
+  Elkrb::Graph::Edge.new(id: "e1", sources: ["gateway"], targets: ["auth"]),
+  Elkrb::Graph::Edge.new(id: "e2", sources: ["gateway"], targets: ["user"]),
+]
+
+result1 = Elkrb.layout(graph1, algorithm: "layered")
+
+puts "Gateway position: (#{result1.children[0].x}, #{result1.children[0].y})"
+puts "  Expected: (500.0, 100.0)"
+puts "  Status: #{result1.children[0].x == 500 && result1.children[0].y == 100 ? '✓' : '✗'}"
+puts
+
+# Example 2: Alignment Constraint
+puts "Example 2: Alignment - All databases aligned horizontally"
+puts "-" * 70
+
+graph2 = Elkrb::Graph::Graph.new(id: "alignment_example")
+
+# Three databases, all aligned horizontally
+db1 = Elkrb::Graph::Node.new(
+  id: "db1",
+  width: 80,
+  height: 50,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    align_group: "databases",
+    align_direction: "horizontal",
+  ),
+)
+
+db2 = Elkrb::Graph::Node.new(
+  id: "db2",
+  width: 80,
+  height: 50,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    align_group: "databases",
+    align_direction: "horizontal",
+  ),
+)
+
+db3 = Elkrb::Graph::Node.new(
+  id: "db3",
+  width: 80,
+  height: 50,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    align_group: "databases",
+    align_direction: "horizontal",
+  ),
+)
+
+graph2.children = [db1, db2, db3]
+
+result2 = Elkrb.layout(graph2, algorithm: "box")
+
+y1 = result2.children[0].y
+y2 = result2.children[1].y
+y3 = result2.children[2].y
+
+puts "Database positions:"
+puts "  db1 y: #{y1}"
+puts "  db2 y: #{y2}"
+puts "  db3 y: #{y3}"
+puts "  Aligned: #{y1 == y2 && y2 == y3 ? '✓' : '✗'}"
+puts
+
+# Example 3: Layer Constraint
+puts "Example 3: Layer - Three-tier architecture"
+puts "-" * 70
+
+graph3 = Elkrb::Graph::Graph.new(id: "layer_example")
+
+# Tier 0: Frontend
+frontend = Elkrb::Graph::Node.new(
+  id: "frontend",
+  width: 100,
+  height: 60,
+  constraints: Elkrb::Graph::NodeConstraints.new(layer: 0),
+)
+
+# Tier 1: Backend
+backend = Elkrb::Graph::Node.new(
+  id: "backend",
+  width: 100,
+  height: 60,
+  constraints: Elkrb::Graph::NodeConstraints.new(layer: 1),
+)
+
+# Tier 2: Database
+database = Elkrb::Graph::Node.new(
+  id: "database",
+  width: 100,
+  height: 60,
+  constraints: Elkrb::Graph::NodeConstraints.new(layer: 2),
+)
+
+graph3.children = [frontend, backend, database]
+graph3.edges = [
+  Elkrb::Graph::Edge.new(id: "e1", sources: ["frontend"], targets: ["backend"]),
+  Elkrb::Graph::Edge.new(id: "e2", sources: ["backend"], targets: ["database"]),
+]
+
+result3 = Elkrb.layout(graph3, algorithm: "layered")
+
+puts "Layer positions (y coordinates):"
+puts "  Frontend (layer 0): y = #{result3.children[0].y.round(1)}"
+puts "  Backend (layer 1):  y = #{result3.children[1].y.round(1)}"
+puts "  Database (layer 2): y = #{result3.children[2].y.round(1)}"
+puts "  Ordered correctly: #{result3.children[0].y < result3.children[1].y && result3.children[1].y < result3.children[2].y ? '✓' : '✗'}"
+puts
+
+# Example 4: Relative Position Constraint
+puts "Example 4: Relative Position - API next to backend service"
+puts "-" * 70
+
+graph4 = Elkrb::Graph::Graph.new(id: "relative_example")
+
+# Backend service (positioned by algorithm)
+backend_svc = Elkrb::Graph::Node.new(
+  id: "backend_svc",
+  width: 100,
+  height: 60,
+)
+
+# API positioned 150px to the right of backend
+offset = Elkrb::Graph::RelativeOffset.new(x: 150, y: 0)
+api = Elkrb::Graph::Node.new(
+  id: "api",
+  width: 100,
+  height: 60,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    relative_to: "backend_svc",
+    relative_offset: offset,
+  ),
+)
+
+graph4.children = [backend_svc, api]
+
+result4 = Elkrb.layout(graph4, algorithm: "box")
+
+backend_x = result4.children[0].x
+api_x = result4.children[1].x
+expected_offset = 150
+
+puts "Backend position: x = #{backend_x}"
+puts "API position:     x = #{api_x}"
+puts "Offset:           #{(api_x - backend_x).round(1)} (expected: #{expected_offset})"
+puts "Correct offset:   #{(api_x - backend_x - expected_offset).abs < 0.1 ? '✓' : '✗'}"
+puts
+
+# Example 5: Combined Constraints
+puts "Example 5: Combined - Microservices architecture with multiple constraints"
+puts "-" * 70
+
+graph5 = Elkrb::Graph::Graph.new(id: "microservices")
+
+# API Gateway (fixed position, layer 0)
+gateway5 = Elkrb::Graph::Node.new(
+  id: "api_gateway",
+  width: 120,
+  height: 60,
+  x: 500,
+  y: 100,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    fixed_position: true,
+    layer: 0,
+  ),
+)
+
+# Backend services (aligned, layer 1)
+auth5 = Elkrb::Graph::Node.new(
+  id: "auth_svc",
+  width: 100,
+  height: 60,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    layer: 1,
+    align_group: "backend",
+    align_direction: "horizontal",
+  ),
+)
+
+user5 = Elkrb::Graph::Node.new(
+  id: "user_svc",
+  width: 100,
+  height: 60,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    layer: 1,
+    align_group: "backend",
+    align_direction: "horizontal",
+  ),
+)
+
+# Databases (aligned, layer 2, relative to services)
+auth_db = Elkrb::Graph::Node.new(
+  id: "auth_db",
+  width: 80,
+  height: 50,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    layer: 2,
+    align_group: "databases",
+    align_direction: "horizontal",
+  ),
+)
+
+user_db = Elkrb::Graph::Node.new(
+  id: "user_db",
+  width: 80,
+  height: 50,
+  constraints: Elkrb::Graph::NodeConstraints.new(
+    layer: 2,
+    align_group: "databases",
+    align_direction: "horizontal",
+  ),
+)
+
+graph5.children = [gateway5, auth5, user5, auth_db, user_db]
+graph5.edges = [
+  Elkrb::Graph::Edge.new(id: "e1", sources: ["api_gateway"],
+                         targets: ["auth_svc"]),
+  Elkrb::Graph::Edge.new(id: "e2", sources: ["api_gateway"],
+                         targets: ["user_svc"]),
+  Elkrb::Graph::Edge.new(id: "e3", sources: ["auth_svc"], targets: ["auth_db"]),
+  Elkrb::Graph::Edge.new(id: "e4", sources: ["user_svc"], targets: ["user_db"]),
+]
+
+result5 = Elkrb.layout(graph5, algorithm: "layered", "elk.direction" => "DOWN")
+
+puts "Results:"
+puts "  Gateway (fixed):     (#{result5.children[0].x}, #{result5.children[0].y})"
+puts "  Backend services:"
+puts "    auth: y = #{result5.children[1].y.round(1)}"
+puts "    user: y = #{result5.children[2].y.round(1)}"
+puts "    Aligned: #{result5.children[1].y == result5.children[2].y ? '✓' : '✗'}"
+puts "  Databases:"
+puts "    auth_db: y = #{result5.children[3].y.round(1)}"
+puts "    user_db: y = #{result5.children[4].y.round(1)}"
+puts "    Aligned: #{result5.children[3].y == result5.children[4].y ? '✓' : '✗'}"
+puts
+
+puts "=" * 70
+puts "All examples completed successfully!"
+puts "See docs/LAYOUT_CONSTRAINTS_GUIDE.md for detailed documentation"
+puts "=" * 70

data/examples/port_constraints_demo.rb

@@ -0,0 +1,291 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/elkrb"
+
+# Example 1: Manual Port Sides
+puts "=" * 60
+puts "Example 1: Manual Port Sides"
+puts "=" * 60
+
+graph1 = Elkrb::Graph::Graph.new(id: "g1")
+
+# Create a node with ports on specific sides
+node1 = Elkrb::Graph::Node.new(
+  id: "n1",
+  width: 100,
+  height: 60,
+  x: 50,
+  y: 50,
+)
+
+# Input ports on the left (WEST)
+node1.ports = [
+  Elkrb::Graph::Port.new(id: "in1", side: "WEST", index: 0),
+  Elkrb::Graph::Port.new(id: "in2", side: "WEST", index: 1),
+]
+
+# Output port on the right (EAST)
+node2 = Elkrb::Graph::Node.new(
+  id: "n2",
+  width: 100,
+  height: 60,
+  x: 200,
+  y: 50,
+)
+node2.ports = [
+  Elkrb::Graph::Port.new(id: "out1", side: "EAST", index: 0),
+]
+
+graph1.children = [node1, node2]
+
+# Create edges connecting the ports
+graph1.edges = [
+  Elkrb::Graph::Edge.new(
+    id: "e1",
+    sources: ["in1"],
+    targets: ["out1"],
+  ),
+]
+
+# Apply layout
+engine = Elkrb::Layout::LayoutEngine.new
+result1 = engine.layout(graph1)
+
+puts "\nNode 1 Ports (after layout):"
+result1.children[0].ports.each do |port|
+  puts "  #{port.id}: side=#{port.side}, x=#{port.x}, y=#{port.y}, " \
+       "index=#{port.index}"
+end
+
+puts "\nNode 2 Ports (after layout):"
+result1.children[1].ports.each do |port|
+  puts "  #{port.id}: side=#{port.side}, x=#{port.x}, y=#{port.y}, " \
+       "index=#{port.index}"
+end
+
+# Example 2: Automatic Side Detection
+puts "\n"
+puts "=" * 60
+puts "Example 2: Automatic Side Detection from Positions"
+puts "=" * 60
+
+graph2 = Elkrb::Graph::Graph.new(id: "g2")
+
+# Create node with ports at specific positions
+# The layout engine will detect which side each port belongs to
+node3 = Elkrb::Graph::Node.new(
+  id: "n3",
+  width: 120,
+  height: 80,
+  x: 50,
+  y: 50,
+)
+
+node3.ports = [
+  Elkrb::Graph::Port.new(id: "p1", x: 60, y: 0),    # Top - should detect NORTH
+  Elkrb::Graph::Port.new(id: "p2", x: 60, y: 80),   # Bottom - should detect SOUTH
+  Elkrb::Graph::Port.new(id: "p3", x: 0, y: 40),    # Left - should detect WEST
+  Elkrb::Graph::Port.new(id: "p4", x: 120, y: 40), # Right - should detect EAST
+]
+
+graph2.children = [node3]
+
+# Apply layout
+result2 = engine.layout(graph2)
+
+puts "\nPort Side Detection Results:"
+result2.children[0].ports.each do |port|
+  puts "  #{port.id}: detected side=#{port.side}, position=(#{port.x}, #{port.y})"
+end
+
+# Example 3: Port Ordering
+puts "\n"
+puts "=" * 60
+puts "Example 3: Port Ordering within Sides"
+puts "=" * 60
+
+graph3 = Elkrb::Graph::Graph.new(id: "g3")
+
+# Create node with multiple ports on the same side
+node4 = Elkrb::Graph::Node.new(
+  id: "n4",
+  width: 150,
+  height: 100,
+  x: 50,
+  y: 50,
+)
+
+# Multiple ports on NORTH side with explicit ordering
+node4.ports = [
+  Elkrb::Graph::Port.new(id: "north3", side: "NORTH", index: 2),
+  Elkrb::Graph::Port.new(id: "north1", side: "NORTH", index: 0),
+  Elkrb::Graph::Port.new(id: "north2", side: "NORTH", index: 1),
+  Elkrb::Graph::Port.new(id: "south1", side: "SOUTH", index: 0),
+  Elkrb::Graph::Port.new(id: "south2", side: "SOUTH", index: 1),
+]
+
+graph3.children = [node4]
+
+# Apply layout
+result3 = engine.layout(graph3)
+
+puts "\nNORTH Side Ports (ordered):"
+north_ports = result3.children[0].ports.select { |p| p.side == "NORTH" }
+north_ports.sort_by(&:index).each do |port|
+  puts "  #{port.id}: index=#{port.index}, x=#{port.x.round(2)}, " \
+       "offset=#{port.offset.round(2)}"
+end
+
+puts "\nSOUTH Side Ports (ordered):"
+south_ports = result3.children[0].ports.select { |p| p.side == "SOUTH" }
+south_ports.sort_by(&:index).each do |port|
+  puts "  #{port.id}: index=#{port.index}, x=#{port.x.round(2)}, " \
+       "offset=#{port.offset.round(2)}"
+end
+
+# Example 4: Port Constraints in Layout Options
+puts "\n"
+puts "=" * 60
+puts "Example 4: Port Constraints via Layout Options"
+puts "=" * 60
+
+graph4 = Elkrb::Graph::Graph.new(id: "g4")
+
+# Set port constraint options
+graph4.layout_options = Elkrb::Graph::LayoutOptions.new
+graph4.layout_options["elk.portConstraints"] = "FIXED_SIDE"
+graph4.layout_options["elk.portSideAssignment"] = "AUTOMATIC"
+graph4.layout_options["elk.portOrdering"] = "INDEX"
+
+puts "\nLayout Options:"
+puts "  Port Constraints: #{graph4.layout_options.port_constraints}"
+puts "  Port Side Assignment: #{graph4.layout_options.port_side_assignment}"
+puts "  Port Ordering: #{graph4.layout_options.port_ordering}"
+
+# Create node with ports
+node5 = Elkrb::Graph::Node.new(
+  id: "n5",
+  width: 100,
+  height: 60,
+  x: 50,
+  y: 50,
+)
+
+node5.ports = [
+  Elkrb::Graph::Port.new(id: "p1", x: 25, y: 0),
+  Elkrb::Graph::Port.new(id: "p2", x: 75, y: 0),
+  Elkrb::Graph::Port.new(id: "p3", x: 0, y: 30),
+]
+
+graph4.children = [node5]
+
+# Apply layout
+result4 = engine.layout(graph4)
+
+puts "\nPorts after layout with constraints:"
+result4.children[0].ports.each do |port|
+  puts "  #{port.id}: side=#{port.side}, index=#{port.index}, " \
+       "pos=(#{port.x.round(2)}, #{port.y.round(2)})"
+end
+
+# Example 5: Complete Diagram with Port-Based Routing
+puts "\n"
+puts "=" * 60
+puts "Example 5: Complete Diagram with Port-Based Routing"
+puts "=" * 60
+
+graph5 = Elkrb::Graph::Graph.new(id: "g5")
+graph5.layout_options = Elkrb::Graph::LayoutOptions.new
+graph5.layout_options["elk.algorithm"] = "layered"
+graph5.layout_options["elk.edgeRouting"] = "ORTHOGONAL"
+
+# Create multiple nodes with ports
+nodeA = Elkrb::Graph::Node.new(
+  id: "A",
+  width: 80,
+  height: 50,
+  labels: [Elkrb::Graph::Label.new(text: "Node A")],
+)
+nodeA.ports = [
+  Elkrb::Graph::Port.new(id: "a_out1", side: "EAST", index: 0),
+  Elkrb::Graph::Port.new(id: "a_out2", side: "EAST", index: 1),
+]
+
+nodeB = Elkrb::Graph::Node.new(
+  id: "B",
+  width: 80,
+  height: 50,
+  labels: [Elkrb::Graph::Label.new(text: "Node B")],
+)
+nodeB.ports = [
+  Elkrb::Graph::Port.new(id: "b_in", side: "WEST", index: 0),
+  Elkrb::Graph::Port.new(id: "b_out", side: "EAST", index: 0),
+]
+
+nodeC = Elkrb::Graph::Node.new(
+  id: "C",
+  width: 80,
+  height: 50,
+  labels: [Elkrb::Graph::Label.new(text: "Node C")],
+)
+nodeC.ports = [
+  Elkrb::Graph::Port.new(id: "c_in1", side: "WEST", index: 0),
+  Elkrb::Graph::Port.new(id: "c_in2", side: "WEST", index: 1),
+]
+
+graph5.children = [nodeA, nodeB, nodeC]
+
+# Connect nodes via ports
+graph5.edges = [
+  Elkrb::Graph::Edge.new(
+    id: "e1",
+    sources: ["a_out1"],
+    targets: ["b_in"],
+  ),
+  Elkrb::Graph::Edge.new(
+    id: "e2",
+    sources: ["a_out2"],
+    targets: ["c_in1"],
+  ),
+  Elkrb::Graph::Edge.new(
+    id: "e3",
+    sources: ["b_out"],
+    targets: ["c_in2"],
+  ),
+]
+
+# Apply layout
+result5 = engine.layout(graph5)
+
+puts "\nFinal Node Positions:"
+result5.children.each do |node|
+  puts "  #{node.id}: (#{node.x.round(2)}, #{node.y.round(2)})"
+  node.ports.each do |port|
+    abs_x = node.x + port.x
+    abs_y = node.y + port.y
+    puts "    #{port.id}: side=#{port.side}, " \
+         "absolute_pos=(#{abs_x.round(2)}, #{abs_y.round(2)})"
+  end
+end
+
+puts "\nEdge Routing:"
+result5.edges.each do |edge|
+  section = edge.sections&.first
+  next unless section
+
+  puts "  #{edge.id}:"
+  puts "    Start: (#{section.start_point.x.round(2)}, " \
+       "#{section.start_point.y.round(2)})"
+  if section.bend_points&.any?
+    section.bend_points.each_with_index do |bp, idx|
+      puts "    Bend #{idx + 1}: (#{bp.x.round(2)}, #{bp.y.round(2)})"
+    end
+  end
+  puts "    End: (#{section.end_point.x.round(2)}, " \
+       "#{section.end_point.y.round(2)})"
+end
+
+puts "\n#{'=' * 60}"
+puts "Port Constraints Demo Complete!"
+puts "=" * 60