elkrb 1.0.0

data/lib/elkrb/layout/algorithms/vertiflex.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative "base_algorithm"
+
+module Elkrb
+  module Layout
+    module Algorithms
+      # VertiFlex layout algorithm
+      #
+      # A vertical flexible layout algorithm that arranges nodes in vertical
+      # columns with optimized spacing. Ideal for timeline-style layouts,
+      # Kanban boards, and vertical flowcharts.
+      #
+      # The algorithm distributes nodes into vertical columns and positions
+      # them with flexible column widths based on the widest node in each
+      # column.
+      #
+      # This is an experimental algorithm matching the Java ELK implementation.
+      class VertiFlex < BaseAlgorithm
+        def initialize(options = {})
+          super
+        end
+
+        # Layout nodes in vertical columns
+        #
+        # @param graph [Elkrb::Graph::Graph] The graph to layout
+        # @param options [Hash] Layout options
+        # @return [Elkrb::Graph::Graph] The graph with updated positions
+        def layout_flat(graph, _options = {})
+          return graph if graph.children.empty?
+
+          if graph.children.size == 1
+            # Single node at origin
+            graph.children.first.x = 0.0
+            graph.children.first.y = 0.0
+            apply_padding(graph)
+            return graph
+          end
+
+          nodes = graph.children
+          layout_opts = graph.layout_options || {}
+
+          # Get layout options
+          column_count = get_option(layout_opts, "vertiflex.columnCount",
+                                    3).to_i
+          column_count = 1 if column_count < 1
+
+          column_spacing = get_option(
+            layout_opts,
+            "vertiflex.columnSpacing",
+            50.0,
+          ).to_f
+
+          vertical_spacing = get_option(
+            layout_opts,
+            "vertiflex.verticalSpacing",
+            30.0,
+          ).to_f
+
+          # Override with elk.spacing.nodeNode if present
+          node_node_spacing = get_option(layout_opts, "elk.spacing.nodeNode")
+          vertical_spacing = node_node_spacing.to_f if node_node_spacing
+
+          balance_columns = get_option(
+            layout_opts,
+            "vertiflex.balanceColumns",
+            true,
+          )
+
+          # Distribute nodes into columns
+          columns = distribute_nodes(nodes, column_count, balance_columns)
+
+          # Position columns horizontally
+          position_columns(columns, column_spacing, vertical_spacing)
+
+          apply_padding(graph)
+
+          graph
+        end
+
+        private
+
+        # Get option value from layout options or default
+        #
+        # @param layout_opts [Hash, LayoutOptions] The layout options
+        # @param key [String] The option key
+        # @param default [Object] The default value
+        # @return [Object] The option value or default
+        def get_option(layout_opts, key, default = nil)
+          return default unless layout_opts
+
+          value = if layout_opts.respond_to?(:[])
+                    layout_opts[key]
+                  end
+
+          value.nil? ? default : value
+        end
+
+        # Distribute nodes into columns
+        #
+        # @param nodes [Array<Elkrb::Graph::Node>] Nodes to distribute
+        # @param column_count [Integer] Number of columns
+        # @param balance [Boolean] Whether to balance distribution
+        # @return [Array<Array<Elkrb::Graph::Node>>] Array of columns
+        def distribute_nodes(nodes, column_count, balance)
+          # Initialize columns
+          columns = Array.new(column_count) { [] }
+
+          if balance
+            # Balanced distribution: round-robin assignment
+            nodes.each_with_index do |node, index|
+              column_index = index % column_count
+              columns[column_index] << node
+            end
+          else
+            # Sequential distribution: fill columns in order
+            nodes_per_column = (nodes.size.to_f / column_count).ceil
+            nodes.each_slice(nodes_per_column).with_index do |slice, index|
+              columns[index] = slice if index < column_count
+            end
+          end
+
+          # Remove empty columns
+          columns.reject(&:empty?)
+        end
+
+        # Position columns horizontally with flexible widths
+        #
+        # @param columns [Array<Array<Elkrb::Graph::Node>>] Columns of nodes
+        # @param column_spacing [Float] Spacing between columns
+        # @param vertical_spacing [Float] Vertical spacing within columns
+        def position_columns(columns, column_spacing, vertical_spacing)
+          current_x = 0.0
+
+          columns.each do |column_nodes|
+            # Calculate column width based on widest node
+            column_width = column_nodes.map(&:width).max || 100.0
+
+            # Position nodes vertically in this column
+            position_column_nodes(
+              column_nodes,
+              current_x,
+              column_width,
+              vertical_spacing,
+            )
+
+            # Advance to next column position
+            current_x += column_width + column_spacing
+          end
+        end
+
+        # Position nodes vertically within a column
+        #
+        # @param nodes [Array<Elkrb::Graph::Node>] Nodes in the column
+        # @param column_x [Float] X position of the column
+        # @param column_width [Float] Width of the column (unused, kept for API)
+        # @param vertical_spacing [Float] Vertical spacing between nodes
+        def position_column_nodes(nodes, column_x, _column_width,
+vertical_spacing)
+          current_y = 0.0
+
+          nodes.each do |node|
+            # Position node at column x (no centering for simpler layout)
+            node.x = column_x
+            node.y = current_y
+
+            # Advance to next vertical position
+            current_y += node.height + vertical_spacing
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/constraints/alignment_constraint.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "base_constraint"
+
+module Elkrb
+  module Layout
+    module Constraints
+      # Alignment constraint
+      #
+      # Aligns nodes horizontally (same y) or vertically (same x) based on
+      # their align_group setting.
+      #
+      # @example Horizontal alignment
+      #   db1.constraints = NodeConstraints.new(
+      #     align_group: "databases",
+      #     align_direction: "horizontal"
+      #   )
+      #   db2.constraints = NodeConstraints.new(
+      #     align_group: "databases",
+      #     align_direction: "horizontal"
+      #   )
+      #   # Both nodes will have same y coordinate
+      #
+      # @example Vertical alignment
+      #   ui1.constraints = NodeConstraints.new(
+      #     align_group: "ui_layer",
+      #     align_direction: "vertical"
+      #   )
+      #   ui2.constraints = NodeConstraints.new(
+      #     align_group: "ui_layer",
+      #     align_direction: "vertical"
+      #   )
+      #   # Both nodes will have same x coordinate
+      class AlignmentConstraint < BaseConstraint
+        # Apply alignment constraint
+        #
+        # Groups nodes by align_group and aligns them according to
+        # align_direction.
+        #
+        # @param graph [Graph::Graph] The graph
+        # @return [Graph::Graph] The modified graph
+        def apply(graph)
+          # Group nodes by alignment group and direction
+          alignment_groups = group_by_alignment(all_nodes(graph))
+
+          # Apply alignment to each group
+          alignment_groups.each do |key, nodes|
+            next if nodes.length < 2
+
+            _group_name, direction = key
+            align_nodes(nodes, direction)
+          end
+
+          graph
+        end
+
+        # Validate alignment constraints
+        #
+        # Checks that aligned nodes have matching coordinates.
+        #
+        # @param graph [Graph::Graph] The graph to validate
+        # @return [Array<String>] List of validation errors
+        def validate(graph)
+          errors = []
+          alignment_groups = group_by_alignment(all_nodes(graph))
+
+          alignment_groups.each do |key, nodes|
+            next if nodes.length < 2
+
+            group_name, direction = key
+            errors.concat(validate_group_alignment(nodes, group_name,
+                                                   direction))
+          end
+
+          errors
+        end
+
+        private
+
+        # Group nodes by align_group and align_direction
+        def group_by_alignment(nodes)
+          nodes_with_alignment = nodes.select do |node|
+            node.constraints&.align_group &&
+              node.constraints.align_direction
+          end
+
+          nodes_with_alignment.group_by do |node|
+            [node.constraints.align_group,
+             node.constraints.align_direction]
+          end
+        end
+
+        # Align nodes in a group
+        def align_nodes(nodes, direction)
+          return if nodes.empty?
+
+          case direction
+          when Graph::NodeConstraints::HORIZONTAL
+            align_horizontally(nodes)
+          when Graph::NodeConstraints::VERTICAL
+            align_vertically(nodes)
+          end
+        end
+
+        # Align nodes horizontally (same y)
+        def align_horizontally(nodes)
+          # Use average y position
+          avg_y = nodes.filter_map(&:y).sum / nodes.length.to_f
+
+          nodes.each do |node|
+            node.y = avg_y
+          end
+        end
+
+        # Align nodes vertically (same x)
+        def align_vertically(nodes)
+          # Use average x position
+          avg_x = nodes.filter_map(&:x).sum / nodes.length.to_f
+
+          nodes.each do |node|
+            node.x = avg_x
+          end
+        end
+
+        # Validate group alignment
+        def validate_group_alignment(nodes, group_name, direction)
+          errors = []
+          return errors if nodes.empty?
+
+          case direction
+          when Graph::NodeConstraints::HORIZONTAL
+            y_values = nodes.filter_map(&:y).uniq
+            if y_values.length > 1
+              errors << "Alignment group '#{group_name}' (horizontal) " \
+                        "has nodes with different y coordinates: #{y_values}"
+            end
+          when Graph::NodeConstraints::VERTICAL
+            x_values = nodes.filter_map(&:x).uniq
+            if x_values.length > 1
+              errors << "Alignment group '#{group_name}' (vertical) " \
+                        "has nodes with different x coordinates: #{x_values}"
+            end
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/constraints/base_constraint.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Elkrb
+  module Layout
+    module Constraints
+      # Base class for all layout constraints
+      #
+      # Constraints modify node positions before or after layout to enforce
+      # specific positioning rules. Each constraint type handles one specific
+      # kind of positioning requirement.
+      #
+      # Subclasses must implement:
+      # - apply(graph): Modify graph to enforce constraint
+      # - validate(graph): Check if constraint is satisfied
+      #
+      # @abstract
+      class BaseConstraint
+        # Apply the constraint to the graph
+        #
+        # @param graph [Graph::Graph] The graph to apply constraint to
+        # @return [Graph::Graph] The modified graph
+        def apply(graph)
+          raise NotImplementedError,
+                "#{self.class} must implement #apply"
+        end
+
+        # Validate that the constraint is satisfied
+        #
+        # @param graph [Graph::Graph] The graph to validate
+        # @return [Array<String>] List of validation errors (empty if valid)
+        def validate(_graph)
+          []
+        end
+
+        # Check if constraint applies to this node
+        #
+        # @param node [Graph::Node] The node to check
+        # @return [Boolean] True if constraint applies
+        def applies_to?(node)
+          node.constraints.present?
+        end
+
+        protected
+
+        # Find node by ID in graph
+        #
+        # @param graph [Graph::Graph] The graph to search
+        # @param node_id [String] The node ID to find
+        # @return [Graph::Node, nil] The found node or nil
+        def find_node(graph, node_id)
+          return nil unless graph.children
+
+          graph.children.each do |node|
+            found = node.find_node(node_id)
+            return found if found
+          end
+          nil
+        end
+
+        # Get all nodes from graph (including nested)
+        #
+        # @param graph [Graph::Graph] The graph
+        # @return [Array<Graph::Node>] All nodes
+        def all_nodes(graph)
+          return [] unless graph.children
+
+          graph.children.flat_map(&:all_nodes)
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/constraints/constraint_processor.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "base_constraint"
+require_relative "fixed_position_constraint"
+require_relative "alignment_constraint"
+require_relative "layer_constraint"
+require_relative "relative_position_constraint"
+
+module Elkrb
+  module Layout
+    module Constraints
+      # Constraint processor
+      #
+      # Orchestrates the application and validation of all layout constraints.
+      # Constraints are applied in a specific order to handle dependencies:
+      # 1. Fixed position (locks nodes)
+      # 2. Layer constraints (assigns layers)
+      # 3. Relative position (depends on reference nodes)
+      # 4. Alignment (adjusts positions)
+      #
+      # @example
+      #   processor = ConstraintProcessor.new
+      #   processor.apply_all(graph)  # Apply before layout
+      #   # ... layout algorithm runs ...
+      #   processor.validate_all(graph)  # Validate after layout
+      class ConstraintProcessor
+        # Pre-layout constraints (mark nodes for algorithm)
+        PRE_LAYOUT_CONSTRAINTS = [
+          FixedPositionConstraint,
+          LayerConstraint,
+        ].freeze
+
+        # Post-layout constraints (enforce after algorithm runs)
+        POST_LAYOUT_CONSTRAINTS = [
+          RelativePositionConstraint,
+          AlignmentConstraint,
+        ].freeze
+
+        def initialize
+          @pre_constraints = PRE_LAYOUT_CONSTRAINTS.map(&:new)
+          @post_constraints = POST_LAYOUT_CONSTRAINTS.map(&:new)
+          @all_constraints = (@pre_constraints + @post_constraints)
+        end
+
+        # Apply pre-layout constraints
+        #
+        # These constraints mark nodes for special handling by algorithms.
+        #
+        # @param graph [Graph::Graph] The graph to constrain
+        # @return [Graph::Graph] The constrained graph
+        def apply_pre_layout(graph)
+          return graph unless has_constraints?(graph)
+
+          @pre_constraints.each do |constraint|
+            constraint.apply(graph)
+          end
+
+          graph
+        end
+
+        # Enforce post-layout constraints
+        #
+        # These constraints adjust positions after layout completes.
+        # Also restores fixed positions that may have been moved.
+        #
+        # @param graph [Graph::Graph] The graph to constrain
+        # @return [Graph::Graph] The constrained graph
+        def enforce_post_layout(graph)
+          return graph unless has_constraints?(graph)
+
+          # First restore any fixed positions
+          fixed_constraint = @pre_constraints.find do |c|
+            c.is_a?(FixedPositionConstraint)
+          end
+          fixed_constraint&.restore_fixed_positions(graph)
+
+          # Then apply post-layout constraints
+          @post_constraints.each do |constraint|
+            constraint.apply(graph)
+          end
+
+          graph
+        end
+
+        # Apply all constraints (legacy method)
+        #
+        # @deprecated Use apply_pre_layout and enforce_post_layout instead
+        # @param graph [Graph::Graph] The graph to constrain
+        # @return [Graph::Graph] The constrained graph
+        def apply_all(graph)
+          apply_pre_layout(graph)
+          enforce_post_layout(graph)
+        end
+
+        # Validate all constraints after layout
+        #
+        # Checks that layout algorithm respected all constraints.
+        #
+        # @param graph [Graph::Graph] The graph to validate
+        # @return [Array<String>] List of validation errors
+        def validate_all(graph)
+          return [] unless has_constraints?(graph)
+
+          @all_constraints.flat_map do |constraint|
+            constraint.validate(graph)
+          end
+        end
+
+        # Check if graph has any constraints
+        #
+        # @param graph [Graph::Graph] The graph to check
+        # @return [Boolean] True if any node has constraints
+        def has_constraints?(graph)
+          return false unless graph.children
+
+          graph.children.any? do |node|
+            has_constraints_recursive?(node)
+          end
+        end
+
+        private
+
+        # Check if node or its children have constraints
+        def has_constraints_recursive?(node)
+          return true if node.constraints
+
+          return false unless node.children
+
+          node.children.any? { |child| has_constraints_recursive?(child) }
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/constraints/fixed_position_constraint.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "base_constraint"
+
+module Elkrb
+  module Layout
+    module Constraints
+      # Fixed position constraint
+      #
+      # Prevents nodes from being moved by the layout algorithm.
+      # Nodes with fixed_position: true keep their existing x,y coordinates.
+      #
+      # @example
+      #   node.x = 500
+      #   node.y = 800
+      #   node.constraints = NodeConstraints.new(fixed_position: true)
+      #   # After layout, node remains at (500, 800)
+      class FixedPositionConstraint < BaseConstraint
+        # Apply fixed position constraint (pre-layout)
+        #
+        # Stores original positions of fixed nodes so they can be
+        # restored after layout.
+        #
+        # @param graph [Graph::Graph] The graph
+        # @return [Graph::Graph] The modified graph
+        def apply(graph)
+          all_nodes(graph).each do |node|
+            next unless node.constraints&.fixed_position
+            next if node.x.nil? || node.y.nil?
+
+            # Store original position
+            node.properties ||= {}
+            node.properties["_constraint_fixed"] = true
+            node.properties["_constraint_original_x"] = node.x
+            node.properties["_constraint_original_y"] = node.y
+          end
+
+          graph
+        end
+
+        # Restore fixed positions (called post-layout as well)
+        #
+        # This is called both pre and post layout to ensure fixed positions
+        # are preserved even if algorithms modify them.
+        #
+        # @param graph [Graph::Graph] The graph
+        # @return [Graph::Graph] The modified graph
+        def restore_fixed_positions(graph)
+          all_nodes(graph).each do |node|
+            next unless node.properties&.[]("_constraint_fixed")
+
+            # Restore original position
+            node.x = node.properties["_constraint_original_x"]
+            node.y = node.properties["_constraint_original_y"]
+          end
+
+          graph
+        end
+
+        # Validate fixed positions were respected
+        #
+        # Checks that nodes marked as fixed didn't move during layout.
+        #
+        # @param graph [Graph::Graph] The graph to validate
+        # @return [Array<String>] List of validation errors
+        def validate(graph)
+          errors = []
+
+          all_nodes(graph).each do |node|
+            next unless node.properties&.[]("_constraint_fixed")
+
+            original_x = node.properties["_constraint_original_x"]
+            original_y = node.properties["_constraint_original_y"]
+
+            if node.x != original_x || node.y != original_y
+              errors << "Node '#{node.id}' has fixed_position constraint " \
+                        "but was moved from (#{original_x}, #{original_y}) " \
+                        "to (#{node.x}, #{node.y})"
+            end
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/elkrb/layout/constraints/layer_constraint.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "base_constraint"
+
+module Elkrb
+  module Layout
+    module Constraints
+      # Layer constraint
+      #
+      # Forces nodes into specific layers for layered (Sugiyama) algorithm.
+      # Primarily useful for hierarchical diagrams where certain nodes must
+      # appear in specific tiers.
+      #
+      # @example Three-tier architecture
+      #   frontend.constraints = NodeConstraints.new(layer: 0)   # Top
+      #   backend.constraints = NodeConstraints.new(layer: 1)    # Middle
+      #   database.constraints = NodeConstraints.new(layer: 2)   # Bottom
+      #   # Enforces tier structure
+      class LayerConstraint < BaseConstraint
+        # Apply layer constraint
+        #
+        # Marks nodes with layer assignment that layered algorithm
+        # must respect.
+        #
+        # @param graph [Graph::Graph] The graph
+        # @return [Graph::Graph] The modified graph
+        def apply(graph)
+          all_nodes(graph).each do |node|
+            next unless node.constraints&.layer
+
+            # Mark node with its required layer
+            node.properties ||= {}
+            node.properties["_constraint_layer"] = node.constraints.layer
+          end
+
+          graph
+        end
+
+        # Validate layer constraints
+        #
+        # Checks that nodes assigned to layers are in correct layers.
+        # Note: This validation only applies if the layered algorithm
+        # was used and layer information is available.
+        #
+        # @param graph [Graph::Graph] The graph to validate
+        # @return [Array<String>] List of validation errors
+        def validate(graph)
+          errors = []
+
+          # Check if layer information is available
+          # (only present if layered algorithm was used)
+          all_nodes(graph).each do |node|
+            next unless node.constraints&.layer
+            next unless node.properties&.[]("_assigned_layer")
+
+            expected_layer = node.constraints.layer
+            actual_layer = node.properties["_assigned_layer"]
+
+            if expected_layer != actual_layer
+              errors << "Node '#{node.id}' constrained to layer " \
+                        "#{expected_layer} but assigned to layer " \
+                        "#{actual_layer}"
+            end
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end