elkrb 1.0.0

data/lib/elkrb/layout/layout_engine.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "algorithm_registry"
+
+module Elkrb
+  module Layout
+    # Main entry point for graph layout operations.
+    #
+    # The LayoutEngine provides a high-level interface for applying layout
+    # algorithms to graphs. It handles algorithm selection, graph conversion,
+    # and delegates to the appropriate algorithm implementation.
+    #
+    # @example Basic usage with hash input
+    #   graph = {
+    #     id: "root",
+    #     layoutOptions: { "elk.algorithm" => "layered" },
+    #     children: [
+    #       { id: "n1", width: 100, height: 60 },
+    #       { id: "n2", width: 100, height: 60 }
+    #     ],
+    #     edges: [
+    #       { id: "e1", sources: ["n1"], targets: ["n2"] }
+    #     ]
+    #   }
+    #   result = Elkrb::Layout::LayoutEngine.layout(graph)
+    #
+    # @example Using Graph model objects
+    #   graph = Elkrb::Graph::Graph.new(id: "root")
+    #   node1 = Elkrb::Graph::Node.new(id: "n1", width: 100, height: 60)
+    #   node2 = Elkrb::Graph::Node.new(id: "n2", width: 100, height: 60)
+    #   graph.children = [node1, node2]
+    #   result = Elkrb::Layout::LayoutEngine.layout(graph, algorithm: "force")
+    #
+    # @example Querying available algorithms
+    #   algorithms = Elkrb::Layout::LayoutEngine.known_layout_algorithms
+    #   algorithms.each do |name, info|
+    #     puts "#{name}: #{info[:description]}"
+    #   end
+    class LayoutEngine
+      class << self
+        # Applies a layout algorithm to a graph.
+        #
+        # This method is the primary entry point for graph layout. It accepts
+        # either a Hash representation or a Graph model object, selects the
+        # appropriate algorithm based on options, and computes node positions
+        # and edge routes.
+        #
+        # The algorithm is selected in this order:
+        # 1. options[:algorithm] or options["algorithm"]
+        # 2. graph.layoutOptions["elk.algorithm"]
+        # 3. Default: "layered"
+        #
+        # @param graph [Hash, Elkrb::Graph::Graph] The graph to layout. Can be:
+        #   - A Hash with keys: :id, :children, :edges, :layoutOptions
+        #   - A Graph model object
+        # @param options [Hash] Layout options including:
+        #   - :algorithm (String) - Algorithm name (layered, force, etc.)
+        #   - Algorithm-specific options
+        # @return [Elkrb::Graph::Graph] The input graph with computed positions
+        # @raise [Elkrb::Error] If the specified algorithm is not found
+        #
+        # @example With specific algorithm
+        #   result = Elkrb::Layout::LayoutEngine.layout(
+        #     graph,
+        #     algorithm: "force",
+        #     "elk.force.repulsion" => 5.0
+        #   )
+        #
+        # @example With hierarchical layout
+        #   result = Elkrb::Layout::LayoutEngine.layout(
+        #     graph,
+        #     algorithm: "layered",
+        #     hierarchical: true
+        #   )
+        def layout(graph, options = {})
+          # Convert hash to Graph if needed
+          graph = convert_to_graph(graph) if graph.is_a?(Hash)
+
+          # Get algorithm name from options
+          algorithm_name = options[:algorithm] ||
+            options["algorithm"] ||
+            "layered"
+
+          algorithm_class = AlgorithmRegistry.get(algorithm_name)
+
+          raise Error, "Unknown layout algorithm: #{algorithm_name}" unless
+            algorithm_class
+
+          # Create and run algorithm with options
+          algorithm = algorithm_class.new(options)
+          algorithm.layout(graph)
+
+          graph
+        end
+
+        # Returns metadata for all registered layout algorithms.
+        #
+        # This method provides information about each available algorithm
+        # including its name, description, category, and capabilities.
+        #
+        # @return [Hash{String => Hash}] A hash mapping algorithm names to their metadata.
+        #   Each metadata hash contains:
+        #   - :name (String) - Display name of the algorithm
+        #   - :description (String) - Brief description
+        #   - :category (String, nil) - Algorithm category (e.g., "hierarchical", "force")
+        #   - :supports_hierarchy (Boolean, nil) - Whether it supports hierarchical graphs
+        #
+        # @example List all algorithms
+        #   algorithms = Elkrb::Layout::LayoutEngine.known_layout_algorithms
+        #   algorithms.each do |name, info|
+        #     puts "#{name}: #{info[:description]}"
+        #   end
+        #   # Output:
+        #   # layered: Hierarchical layout using the Sugiyama framework
+        #   # force: Physics-based layout using attractive and repulsive forces
+        #   # ...
+        #
+        # @example Filter by category
+        #   force_algs = Elkrb::Layout::LayoutEngine.known_layout_algorithms
+        #     .select { |_, info| info[:category] == "force" }
+        def known_layout_algorithms
+          AlgorithmRegistry.all_algorithm_info
+        end
+
+        # Exports a graph to Graphviz DOT format.
+        #
+        # This method serializes an ELK graph structure to DOT format,
+        # which can be rendered by Graphviz or other DOT-compatible tools.
+        #
+        # @param graph [Hash, Elkrb::Graph::Graph] The graph to export
+        # @param options [Hash] Serialization options (see DotSerializer)
+        # @return [String] DOT format string
+        #
+        # @example Basic export
+        #   dot = Elkrb::Layout::LayoutEngine.export_dot(graph)
+        #   File.write("output.dot", dot)
+        #
+        # @example With custom options
+        #   dot = Elkrb::Layout::LayoutEngine.export_dot(
+        #     graph,
+        #     directed: true,
+        #     rankdir: "LR",
+        #     graph_name: "MyGraph"
+        #   )
+        def export_dot(graph, options = {})
+          # Convert hash to Graph if needed
+          graph = convert_to_graph(graph) if graph.is_a?(Hash)
+
+          serializer = Elkrb::Serializers::DotSerializer.new
+          serializer.serialize(graph, options)
+        end
+
+        # Returns metadata for all supported layout options.
+        #
+        # @return [Array<Hash>] Array of option metadata
+        # @note Currently returns an empty array. Full implementation planned.
+        def known_layout_options
+          # TODO: Build from all algorithms' supported options
+          []
+        end
+
+        private
+
+        def convert_to_graph(hash)
+          Graph::Graph.from_hash(hash)
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/port_constraint_processor.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    # Port Constraint Processor
+    #
+    # This module provides port constraint processing functionality for
+    # layout algorithms. It handles:
+    # - Automatic port side detection from positions
+    # - Port grouping by side
+    # - Port ordering within each side
+    # - Port positioning on node boundaries
+    module PortConstraintProcessor
+      # Apply port constraints to all nodes in the graph
+      #
+      # @param graph [Elkrb::Graph::Graph] The graph to process
+      def apply_port_constraints(graph)
+        return unless graph.children
+
+        graph.children.each do |node|
+          process_node_ports(node)
+        end
+      end
+
+      private
+
+      # Process ports for a single node
+      #
+      # @param node [Elkrb::Graph::Node] The node to process
+      def process_node_ports(node)
+        return unless node.ports && !node.ports.empty?
+        return unless node.width && node.height && node.width.positive? && node.height.positive?
+
+        # Detect sides if not specified
+        detect_port_sides(node)
+
+        # Group ports by side
+        ports_by_side = group_ports_by_side(node.ports)
+
+        # Apply ordering within each side
+        ports_by_side.each do |side, ports|
+          order_ports_on_side(node, side, ports)
+        end
+
+        # Position ports on node boundaries
+        position_ports_on_boundaries(node, ports_by_side)
+      end
+
+      # Detect port sides for ports with UNDEFINED side
+      #
+      # @param node [Elkrb::Graph::Node] The node containing the ports
+      def detect_port_sides(node)
+        node.ports.each do |port|
+          if port.side == Graph::Port::UNDEFINED
+            detected_side = port.detect_side(node.width, node.height)
+            port.side = detected_side
+          end
+        end
+      end
+
+      # Group ports by their side
+      #
+      # @param ports [Array<Elkrb::Graph::Port>] The ports to group
+      # @return [Hash<String, Array<Elkrb::Graph::Port>>] Ports grouped by side
+      def group_ports_by_side(ports)
+        ports.group_by(&:side)
+      end
+
+      # Order ports on a specific side
+      #
+      # Ports are sorted by:
+      # 1. Index (if specified and >= 0)
+      # 2. Position along the side (x for horizontal sides, y for vertical)
+      #
+      # @param node [Elkrb::Graph::Node] The node containing the ports
+      # @param side [String] The side to order ports on
+      # @param ports [Array<Elkrb::Graph::Port>] The ports on this side
+      def order_ports_on_side(_node, side, ports)
+        # Sort by index if specified, otherwise by position
+        ports.sort_by! do |port|
+          if port.index >= 0
+            port.index
+          elsif [Graph::Port::NORTH, Graph::Port::SOUTH].include?(side)
+            # Horizontal sides: sort by x position
+            port.x || 0
+          else
+            # Vertical sides: sort by y position
+            port.y || 0
+          end
+        end
+
+        # Assign sequential indices to ports without explicit index
+        ports.each_with_index do |port, idx|
+          port.index = idx if port.index.negative?
+        end
+      end
+
+      # Position ports on node boundaries
+      #
+      # @param node [Elkrb::Graph::Node] The node containing the ports
+      # @param ports_by_side [Hash<String, Array<Elkrb::Graph::Port>>] Ports grouped by side
+      def position_ports_on_boundaries(node, ports_by_side)
+        # NORTH: top edge, distributed horizontally
+        if ports_by_side[Graph::Port::NORTH]
+          distribute_ports_horizontally(
+            node,
+            ports_by_side[Graph::Port::NORTH],
+            0,
+          )
+        end
+
+        # SOUTH: bottom edge, distributed horizontally
+        if ports_by_side[Graph::Port::SOUTH]
+          distribute_ports_horizontally(
+            node,
+            ports_by_side[Graph::Port::SOUTH],
+            node.height,
+          )
+        end
+
+        # WEST: left edge, distributed vertically
+        if ports_by_side[Graph::Port::WEST]
+          distribute_ports_vertically(
+            node,
+            ports_by_side[Graph::Port::WEST],
+            0,
+          )
+        end
+
+        # EAST: right edge, distributed vertically
+        if ports_by_side[Graph::Port::EAST]
+          distribute_ports_vertically(
+            node,
+            ports_by_side[Graph::Port::EAST],
+            node.width,
+          )
+        end
+      end
+
+      # Distribute ports horizontally along a horizontal edge
+      #
+      # @param node [Elkrb::Graph::Node] The node containing the ports
+      # @param ports [Array<Elkrb::Graph::Port>] The ports to distribute
+      # @param y_pos [Float] The y position of the edge
+      def distribute_ports_horizontally(node, ports, y_pos)
+        count = ports.length
+        spacing = node.width / (count + 1).to_f
+
+        ports.each_with_index do |port, idx|
+          port.x = spacing * (idx + 1)
+          port.y = y_pos
+          port.offset = port.x
+        end
+      end
+
+      # Distribute ports vertically along a vertical edge
+      #
+      # @param node [Elkrb::Graph::Node] The node containing the ports
+      # @param ports [Array<Elkrb::Graph::Port>] The ports to distribute
+      # @param x_pos [Float] The x position of the edge
+      def distribute_ports_vertically(node, ports, x_pos)
+        count = ports.length
+        spacing = node.height / (count + 1).to_f
+
+        ports.each_with_index do |port, idx|
+          port.x = x_pos
+          port.y = spacing * (idx + 1)
+          port.offset = port.y
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/options/elk_padding.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Options
+    # ElkPadding parser for padding specifications
+    #
+    # Parses padding strings in the format:
+    #   "[left=2, top=3, right=3, bottom=2]"
+    class ElkPadding
+      attr_reader :left, :top, :right, :bottom
+
+      def initialize(left: 0, top: 0, right: 0, bottom: 0)
+        @left = left.to_f
+        @top = top.to_f
+        @right = right.to_f
+        @bottom = bottom.to_f
+      end
+
+      # Parse padding from string or hash
+      #
+      # @param value [String, Hash, ElkPadding] The padding specification
+      # @return [ElkPadding] Parsed padding object
+      def self.parse(value)
+        return value if value.is_a?(ElkPadding)
+        return from_hash(value) if value.is_a?(Hash)
+        return from_string(value) if value.is_a?(String)
+
+        raise ArgumentError, "Invalid padding value: #{value.inspect}"
+      end
+
+      # Parse from hash
+      #
+      # @param hash [Hash] Hash with :left, :top, :right, :bottom keys
+      # @return [ElkPadding] Parsed padding object
+      def self.from_hash(hash)
+        new(
+          left: hash[:left] || hash["left"] || 0,
+          top: hash[:top] || hash["top"] || 0,
+          right: hash[:right] || hash["right"] || 0,
+          bottom: hash[:bottom] || hash["bottom"] || 0,
+        )
+      end
+
+      # Parse from string
+      #
+      # @param str [String] String like "[left=2, top=3, right=3, bottom=2]"
+      # @return [ElkPadding] Parsed padding object
+      def self.from_string(str)
+        # Remove brackets and split by comma
+        content = str.strip.gsub(/^\[|\]$/, "")
+        parts = {}
+
+        content.split(",").each do |part|
+          key, value = part.split("=").map(&:strip)
+          parts[key.to_sym] = value.to_f
+        end
+
+        new(**parts)
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          left: @left,
+          top: @top,
+          right: @right,
+          bottom: @bottom,
+        }
+      end
+
+      # Convert to string
+      #
+      # @return [String] String representation
+      def to_s
+        "[left=#{@left}, top=#{@top}, right=#{@right}, bottom=#{@bottom}]"
+      end
+
+      # Check equality
+      #
+      # @param other [ElkPadding] Other padding object
+      # @return [Boolean] True if equal
+      def ==(other)
+        return false unless other.is_a?(ElkPadding)
+
+        @left == other.left &&
+          @top == other.top &&
+          @right == other.right &&
+          @bottom == other.bottom
+      end
+    end
+  end
+end

data/lib/elkrb/options/k_vector.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Options
+    # KVector parser for coordinate pairs
+    #
+    # Parses coordinate strings in the format:
+    #   "(23, 43)" or "(23,43)"
+    class KVector
+      attr_reader :x, :y
+
+      def initialize(x, y)
+        @x = x.to_f
+        @y = y.to_f
+      end
+
+      # Parse KVector from string, hash, or array
+      #
+      # @param value [String, Hash, Array, KVector] The coordinate specification
+      # @return [KVector] Parsed coordinate object
+      def self.parse(value)
+        return value if value.is_a?(KVector)
+        return from_hash(value) if value.is_a?(Hash)
+        return from_array(value) if value.is_a?(Array)
+        return from_string(value) if value.is_a?(String)
+
+        raise ArgumentError, "Invalid KVector value: #{value.inspect}"
+      end
+
+      # Parse from hash
+      #
+      # @param hash [Hash] Hash with :x and :y keys
+      # @return [KVector] Parsed coordinate object
+      def self.from_hash(hash)
+        new(
+          hash[:x] || hash["x"] || 0,
+          hash[:y] || hash["y"] || 0,
+        )
+      end
+
+      # Parse from array
+      #
+      # @param array [Array] Array with [x, y] values
+      # @return [KVector] Parsed coordinate object
+      def self.from_array(array)
+        raise ArgumentError, "Array must have 2 elements" unless array.size == 2
+
+        new(array[0], array[1])
+      end
+
+      # Parse from string
+      #
+      # @param str [String] String like "(23, 43)" or "(23,43)"
+      # @return [KVector] Parsed coordinate object
+      def self.from_string(str)
+        # Remove parentheses and split by comma
+        content = str.strip.gsub(/^\(|\)$/, "")
+        parts = content.split(",").map(&:strip)
+
+        unless parts.size == 2
+          raise ArgumentError,
+                "Invalid KVector format: #{str}"
+        end
+
+        new(parts[0], parts[1])
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        { x: @x, y: @y }
+      end
+
+      # Convert to array
+      #
+      # @return [Array] Array representation
+      def to_a
+        [@x, @y]
+      end
+
+      # Convert to string
+      #
+      # @return [String] String representation
+      def to_s
+        "(#{@x}, #{@y})"
+      end
+
+      # Check equality
+      #
+      # @param other [KVector] Other coordinate object
+      # @return [Boolean] True if equal
+      def ==(other)
+        return false unless other.is_a?(KVector)
+
+        @x == other.x && @y == other.y
+      end
+    end
+  end
+end

data/lib/elkrb/options/k_vector_chain.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative "k_vector"
+
+module Elkrb
+  module Options
+    # KVectorChain parser for coordinate chains
+    #
+    # Parses coordinate chain strings in the format:
+    #   "( {1,2}, {3,4} )" or "({1,2},{3,4})"
+    class KVectorChain
+      attr_reader :vectors
+
+      def initialize(vectors = [])
+        @vectors = vectors.map { |v| KVector.parse(v) }
+      end
+
+      # Parse KVectorChain from string or array
+      #
+      # @param value [String, Array, KVectorChain] The coordinate chain
+      # @return [KVectorChain] Parsed coordinate chain object
+      def self.parse(value)
+        return value if value.is_a?(KVectorChain)
+        return from_array(value) if value.is_a?(Array)
+        return from_string(value) if value.is_a?(String)
+
+        raise ArgumentError, "Invalid KVectorChain value: #{value.inspect}"
+      end
+
+      # Parse from array
+      #
+      # @param array [Array] Array of coordinate pairs or KVectors
+      # @return [KVectorChain] Parsed coordinate chain object
+      def self.from_array(array)
+        new(array)
+      end
+
+      # Parse from string
+      #
+      # @param str [String] String like "( {1,2}, {3,4} )"
+      # @return [KVectorChain] Parsed coordinate chain object
+      def self.from_string(str)
+        # Remove outer parentheses
+        content = str.strip.gsub(/^\(\s*|\s*\)$/, "")
+
+        # Split by },{  or } , {
+        parts = content.split(/\}\s*,\s*\{/)
+
+        # Clean up first and last parts
+        parts[0] = parts[0].sub(/^\{/, "") if parts[0]
+        parts[-1] = parts[-1].sub(/\}$/, "") if parts[-1]
+
+        # Parse each coordinate pair
+        vectors = parts.map do |part|
+          coords = part.split(",").map(&:strip)
+          unless coords.size == 2
+            raise ArgumentError,
+                  "Invalid coordinate pair: #{part}"
+          end
+
+          KVector.new(coords[0], coords[1])
+        end
+
+        new(vectors)
+      end
+
+      # Add a vector to the chain
+      #
+      # @param vector [KVector, Array, Hash] Vector to add
+      # @return [KVectorChain] Self for chaining
+      def add(vector)
+        @vectors << KVector.parse(vector)
+        self
+      end
+      alias << add
+
+      # Get vector at index
+      #
+      # @param index [Integer] Index of vector
+      # @return [KVector] Vector at index
+      def [](index)
+        @vectors[index]
+      end
+
+      # Number of vectors in chain
+      #
+      # @return [Integer] Count of vectors
+      def size
+        @vectors.size
+      end
+      alias length size
+
+      # Check if chain is empty
+      #
+      # @return [Boolean] True if empty
+      def empty?
+        @vectors.empty?
+      end
+
+      # Iterate over vectors
+      #
+      # @yield [KVector] Each vector in chain
+      def each(&)
+        @vectors.each(&)
+      end
+
+      # Convert to array
+      #
+      # @return [Array<KVector>] Array of vectors
+      def to_a
+        @vectors.dup
+      end
+
+      # Convert to string
+      #
+      # @return [String] String representation
+      def to_s
+        return "()" if @vectors.empty?
+
+        vector_strs = @vectors.map { |v| "{#{v.x}, #{v.y}}" }
+        "( #{vector_strs.join(', ')} )"
+      end
+
+      # Check equality
+      #
+      # @param other [KVectorChain] Other coordinate chain
+      # @return [Boolean] True if equal
+      def ==(other)
+        return false unless other.is_a?(KVectorChain)
+
+        @vectors == other.vectors
+      end
+    end
+  end
+end