elkrb 1.0.2 → 2.0.0

data/lib/elkrb/layout/label_placer.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "../options/resolver"
+
 module Elkrb
   module Layout
     # Module to add automatic label placement to layout algorithms.
     # Handles positioning of node labels, edge labels, and port labels.
+    # The including class sets @resolver, as BaseAlgorithm does.
     module LabelPlacer
+      OPPOSITE_SIDE = { left: :right, right: :left, top: :bottom, bottom: :top }.freeze
+      private_constant :OPPOSITE_SIDE
+
       # Place all labels in the graph after layout is complete.
       #
       # @param graph [Graph::Graph] The laid out graph
@@ -16,115 +22,135 @@ module Elkrb
 
         # Place edge labels
         place_edge_labels(graph) if graph.edges
-
-        # Recursively place labels in hierarchical graphs
-        place_hierarchical_labels(graph) if graph.hierarchical?
       end
 
       private
 
-      # Place labels for all nodes in the graph.
+      # ELK treats a missing width/height as 0 (compound nodes and
+      # deserialized labels commonly omit size).
+      def width_of(element)
+        element.width || 0.0
+      end
+
+      def height_of(element)
+        element.height || 0.0
+      end
+
+      # Place labels for all nodes in the graph. Node and port labels are
+      # owner-relative: (0, 0) is the owner's top-left corner.
       def place_node_labels(graph)
         graph.children.each do |node|
-          next unless node.labels && !node.labels.empty?
-
-          node.labels.each_with_index do |label, index|
-            place_node_label(node, label, index)
+          if node.labels && !node.labels.empty?
+            node.labels.each_with_index do |label, index|
+              place_node_label(node, label, index)
+            end
           end
 
-          # Place port labels if node has ports
           place_port_labels(node) if node.ports && !node.ports.empty?
         end
       end
 
-      # Place a single node label.
+      # Place a single node label. Without a placement option the label is
+      # not moved, as in ELK: it keeps its coordinates, or (0, 0) if it has
+      # none.
       def place_node_label(node, label, index = 0)
-        placement = label_placement_option(node, "node.label.placement") ||
-          "INSIDE CENTER"
-
-        case placement.upcase
-        when /INSIDE/
-          place_label_inside_node(node, label, placement, index)
-        when /OUTSIDE/
-          place_label_outside_node(node, label, placement, index)
-        else
-          # Default: center inside
-          place_label_center(node, label)
+        placement = label_placement_option(node, "elk.nodeLabels.placement")
+        tokens = placement_tokens(placement)
+        if tokens.empty?
+          label.x ||= 0.0
+          label.y ||= 0.0
+          return
         end
-      end
 
-      # Place label inside the node bounds.
-      def place_label_inside_node(node, label, placement, index)
-        case placement.upcase
-        when /TOP/
-          place_label_inside_top(node, label, index)
-        when /BOTTOM/
-          place_label_inside_bottom(node, label, index)
-        when /LEFT/
-          place_label_inside_left(node, label, index)
-        when /RIGHT/
-          place_label_inside_right(node, label, index)
+        vertical = vertical_of(tokens)
+        horizontal = horizontal_of(tokens)
+
+        if tokens.include?("OUTSIDE")
+          place_label_outside_node(node, label, vertical, horizontal, index)
         else
-          place_label_center(node, label)
+          place_label_inside_node(node, label, vertical, horizontal, index)
         end
       end
 
-      # Place label outside the node bounds.
-      def place_label_outside_node(node, label, placement, _index)
-        margin = label_margin_option(node)
-
-        case placement.upcase
-        when /TOP/
-          label.x = node.x + ((node.width - label.width) / 2.0)
-          label.y = node.y - label.height - margin
-        when /BOTTOM/
-          label.x = node.x + ((node.width - label.width) / 2.0)
-          label.y = node.y + node.height + margin
-        when /LEFT/
-          label.x = node.x - label.width - margin
-          label.y = node.y + ((node.height - label.height) / 2.0)
-        when /RIGHT/
-          label.x = node.x + node.width + margin
-          label.y = node.y + ((node.height - label.height) / 2.0)
-        end
+      # The upcased tokens of a placement value. Accepts ELK's
+      # "[H_CENTER,V_CENTER,INSIDE]" and the space-separated
+      # "INSIDE V_CENTER H_CENTER".
+      def placement_tokens(placement)
+        placement.to_s.upcase.split(/[\s,\[\]]+/).reject(&:empty?)
       end
 
-      # Place label at various inside positions.
-      def place_label_inside_top(node, label, index)
-        padding = label_padding_option(node)
-        y_offset = index * (label.height + padding)
+      # :top, :center or :bottom. V_TOP is also spelled TOP.
+      def vertical_of(tokens)
+        return :top if tokens.intersect?(%w[V_TOP TOP])
+        return :bottom if tokens.intersect?(%w[V_BOTTOM BOTTOM])
 
-        label.x = node.x + ((node.width - label.width) / 2.0)
-        label.y = node.y + padding + y_offset
+        :center
       end
 
-      def place_label_inside_bottom(node, label, index)
-        padding = label_padding_option(node)
-        y_offset = index * (label.height + padding)
+      # :left, :center or :right. H_LEFT is also spelled LEFT.
+      def horizontal_of(tokens)
+        return :left if tokens.intersect?(%w[H_LEFT LEFT])
+        return :right if tokens.intersect?(%w[H_RIGHT RIGHT])
 
-        label.x = node.x + ((node.width - label.width) / 2.0)
-        label.y = node.y + node.height - label.height - padding - y_offset
+        :center
       end
 
-      def place_label_inside_left(node, label, index)
+      # Place a label inside the node, relative to the node's origin.
+      def place_label_inside_node(node, label, vertical, horizontal, index)
         padding = label_padding_option(node)
-        y_offset = index * (label.height + padding)
+        offset = index * (height_of(label) + padding)
+
+        label.x = inside_x(node, label, horizontal, padding)
+        label.y =
+          case vertical
+          when :top then padding + offset
+          when :bottom then height_of(node) - height_of(label) - padding - offset
+          else (height_of(node) - height_of(label)) / 2.0
+          end
+      end
 
-        label.x = node.x + padding
-        label.y = node.y + padding + y_offset
+      def inside_x(node, label, horizontal, padding)
+        case horizontal
+        when :left then padding
+        when :right then width_of(node) - width_of(label) - padding
+        else (width_of(node) - width_of(label)) / 2.0
+        end
       end
 
-      def place_label_inside_right(node, label, index)
-        padding = label_padding_option(node)
-        y_offset = index * (label.height + padding)
+      # Place a label outside the node, relative to the node's origin. Above
+      # or below when a vertical side is named, otherwise beside. Naming no
+      # side at all places it above.
+      def place_label_outside_node(node, label, vertical, horizontal, index)
+        margin = label_margin_option(node)
+        offset = index * (height_of(label) + margin)
 
-        label.x = node.x + node.width - label.width - padding
-        label.y = node.y + padding + y_offset
+        if vertical == :center && horizontal != :center
+          place_label_beside_node(node, label, horizontal, margin)
+        elsif vertical == :bottom
+          label.x = outside_x(node, label, horizontal)
+          label.y = height_of(node) + margin + offset
+        else
+          label.x = outside_x(node, label, horizontal)
+          label.y = -height_of(label) - margin - offset
+        end
       end
 
-      def place_label_center(node, label)
-        label.x = node.x + ((node.width - label.width) / 2.0)
-        label.y = node.y + ((node.height - label.height) / 2.0)
+      def outside_x(node, label, horizontal)
+        case horizontal
+        when :left then 0.0
+        when :right then width_of(node) - width_of(label)
+        else (width_of(node) - width_of(label)) / 2.0
+        end
+      end
+
+      def place_label_beside_node(node, label, horizontal, margin)
+        label.x =
+          if horizontal == :left
+            -width_of(label) - margin
+          else
+            width_of(node) + margin
+          end
+        label.y = (height_of(node) - height_of(label)) / 2.0
       end
 
       # Place labels for all ports on a node.
@@ -138,27 +164,16 @@ module Elkrb
         end
       end
 
-      # Place a port label.
-      def place_port_label(node, port, label, _index)
-        # Port position relative to node
-        port_x = node.x + (port.x || 0)
-        port_y = node.y + (port.y || 0)
-
-        placement = label_placement_option(port, "port.label.placement") ||
+      # Place a port label, relative to the port's origin. OUTSIDE (the
+      # default) puts it beside the port away from the node, INSIDE on the
+      # node's side of the port.
+      def place_port_label(node, port, label, index)
+        placement = label_placement_option(port, "elk.portLabels.placement") ||
           "OUTSIDE"
+        side = port_side(node, port)
+        side = OPPOSITE_SIDE.fetch(side) if placement_tokens(placement).include?("INSIDE")
 
-        margin = label_margin_option(port)
-
-        case placement.upcase
-        when /INSIDE/
-          # Place inside port (if port is large enough)
-          label.x = port_x + ((port.width - label.width) / 2.0)
-          label.y = port_y + ((port.height - label.height) / 2.0)
-        else
-          # Default: outside, positioned based on port side
-          side = port_side(node, port)
-          place_port_label_by_side(label, port_x, port_y, port, side, margin)
-        end
+        place_port_label_by_side(label, port, side, label_margin_option(port), index)
       end
 
       # Determine which side of the node the port is on.
@@ -168,9 +183,9 @@ module Elkrb
 
         # Check which edge the port is closest to
         left_dist = port_x
-        right_dist = node.width - port_x
+        right_dist = width_of(node) - port_x
         top_dist = port_y
-        bottom_dist = node.height - port_y
+        bottom_dist = height_of(node) - port_y
 
         min_dist = [left_dist, right_dist, top_dist, bottom_dist].min
 
@@ -182,21 +197,21 @@ module Elkrb
         end
       end
 
-      # Place port label based on port side.
-      def place_port_label_by_side(label, port_x, port_y, port, side, margin)
+      # Place a port label on the given side of the port. Stacked labels
+      # step along the side by their own height.
+      def place_port_label_by_side(label, port, side, margin, index)
+        step = index * (height_of(label) + margin)
+
         case side
-        when :left
-          label.x = port_x - label.width - margin
-          label.y = port_y + ((port.height - label.height) / 2.0)
-        when :right
-          label.x = port_x + port.width + margin
-          label.y = port_y + ((port.height - label.height) / 2.0)
+        when :left, :right
+          label.x = side == :left ? -width_of(label) - margin : width_of(port) + margin
+          label.y = ((height_of(port) - height_of(label)) / 2.0) + step
         when :top
-          label.x = port_x + ((port.width - label.width) / 2.0)
-          label.y = port_y - label.height - margin
+          label.x = (width_of(port) - width_of(label)) / 2.0
+          label.y = -height_of(label) - margin - step
         when :bottom
-          label.x = port_x + ((port.width - label.width) / 2.0)
-          label.y = port_y + port.height + margin
+          label.x = (width_of(port) - width_of(label)) / 2.0
+          label.y = height_of(port) + margin + step
         end
       end
 
@@ -215,33 +230,37 @@ module Elkrb
       def place_edge_label(edge, label, index)
         # Get edge path (sections with bend points)
         if edge.sections && !edge.sections.empty?
-          place_edge_label_on_section(edge.sections.first, label, index)
+          place_edge_label_on_section(edge, edge.sections.first, label, index)
         else
           # No sections, estimate from source/target
           place_edge_label_estimated(edge, label, index)
         end
       end
 
-      # Place edge label on an edge section.
-      def place_edge_label_on_section(section, label, index)
-        # Calculate center point of the edge path
-        center = calculate_edge_center(section)
-
-        placement = "CENTER" # Could be configurable
-
-        offset = index * (label.height + 2) # Stack multiple labels
-
-        case placement.upcase
-        when /CENTER/
-          label.x = center[:x] - (label.width / 2.0)
-          label.y = center[:y] - (label.height / 2.0) + offset
-        when /HEAD/
-          label.x = section.end_point.x - (label.width / 2.0)
-          label.y = section.end_point.y - label.height - 5 + offset
-        when /TAIL/
-          label.x = section.start_point.x - (label.width / 2.0)
-          label.y = section.start_point.y - label.height - 5 + offset
-        end
+      # Place an edge label on an edge section, in the section's frame. The
+      # label's own elk.edgeLabels.placement wins over the edge's.
+      def place_edge_label_on_section(edge, section, label, index)
+        tokens = placement_tokens(
+          @resolver.get("elk.edgeLabels.placement", label, edge),
+        )
+        offset = index * (height_of(label) + 2) # Stack multiple labels
+
+        anchor =
+          if tokens.include?("HEAD")
+            above(section.end_point, label)
+          elsif tokens.include?("TAIL")
+            above(section.start_point, label)
+          else
+            calculate_edge_center(section)
+          end
+
+        label.x = anchor[:x] - (width_of(label) / 2.0)
+        label.y = anchor[:y] - (height_of(label) / 2.0) + offset
+      end
+
+      # HEAD and TAIL labels sit just above the end point they name.
+      def above(point, label)
+        { x: point.x, y: point.y - (height_of(label) / 2.0) - 5 }
       end
 
       # Calculate the center point of an edge section.
@@ -262,6 +281,8 @@ module Elkrb
           total_length += length
         end
 
+        return { x: points.first.x, y: points.first.y } if total_length.zero?
+
         # Find point at half the total length
         target_length = total_length / 2.0
         current_length = 0.0
@@ -269,7 +290,7 @@ module Elkrb
         (0...lengths.length).each do |i|
           if current_length + lengths[i] >= target_length
             # Interpolate between points[i] and points[i+1]
-            ratio = (target_length - current_length) / lengths[i]
+            ratio = lengths[i].zero? ? 0.0 : (target_length - current_length) / lengths[i]
             p1 = points[i]
             p2 = points[i + 1]
 
@@ -294,44 +315,31 @@ module Elkrb
         label.y = 0
       end
 
-      # Place labels in hierarchical child nodes.
-      def place_hierarchical_labels(graph)
-        return unless graph.children
-
-        graph.children.each do |node|
-          next unless node.hierarchical?
-
-          # Create temporary graph for children
-          child_graph = Graph::Graph.new(
-            children: node.children,
-            edges: node.edges,
-          )
-
-          # Recursively place labels
-          place_labels(child_graph)
+      # Get the label placement an element names, or nil. The element's own
+      # options come before the call's: for a port, `label.placement` is one
+      # of them, though the registry aliases it to nodes. Because it is that
+      # alias, a port that names elk.nodeLabels.placement is read the same way.
+      def label_placement_option(element, option_id)
+        [option_id, "label.placement"].each do |id|
+          own = own_option(id, element)
+          return own if own
         end
+        @resolver.get(option_id, element, default: nil)
       end
 
-      # Get label placement option from node/port layout options.
-      def label_placement_option(element, option_key)
-        return nil unless element.layout_options
-
-        element.layout_options.properties&.[](option_key) ||
-          element.layout_options.properties&.[]("label.placement")
+      # An element's own option, ignoring the call's options.
+      def own_option(id, element)
+        (@own_options ||= Options::Resolver.new).get(id, element, default: nil)
       end
 
       # Get label padding option.
       def label_padding_option(element)
-        return 5.0 unless element.layout_options
-
-        element.layout_options.properties&.[]("label.padding") || 5.0
+        @resolver.get("label.padding", element)
       end
 
       # Get label margin option.
       def label_margin_option(element)
-        return 5.0 unless element.layout_options
-
-        element.layout_options.properties&.[]("label.margin") || 5.0
+        @resolver.get("label.margin", element)
       end
     end
   end

data/lib/elkrb/layout/layout_engine.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require_relative "algorithm_registry"
+require_relative "../options/registry"
+require_relative "../options/resolver"
 
 module Elkrb
   module Layout
@@ -45,11 +47,24 @@ module Elkrb
         # 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"]
+        # The algorithm is the first of these that names one:
+        # 1. The graph's own selector -- layoutOptions under "elk.algorithm",
+        #    "algorithm" or the "org.eclipse.elk.algorithm" long form, then
+        #    properties
+        # 2. The :algorithm call option, under a Symbol or String key
         # 3. Default: "layered"
         #
+        # A graph that pins an algorithm keeps it; the caller's option is
+        # the fallback for graphs that pin none.
+        #
+        # With the call option strict: true, an option in the graph's
+        # layoutOptions that elkrb does not know, or does not fully honour,
+        # raises Elkrb::Error instead of logging a warning. So does a
+        # registered option in an element's properties or in +options+ that
+        # is not fully honoured; an unknown property name or key in +options+
+        # is not reported. An option only some algorithms read is accepted
+        # where the algorithm laying out its element is one of them.
+        #
         # @param graph [Hash, Elkrb::Graph::Graph] The graph to layout. Can be:
         #   - A Hash with keys: :id, :children, :edges, :layoutOptions
         #   - A Graph model object
@@ -57,7 +72,9 @@ module Elkrb
         #   - :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
+        # @raise [ArgumentError] If graph is neither a Hash nor a Graph::Graph
+        # @raise [Elkrb::AlgorithmNotFoundError] If the algorithm is not found
+        # @raise [Elkrb::Error] In strict mode, for an unknown or unhonoured option
         #
         # @example With specific algorithm
         #   result = Elkrb::Layout::LayoutEngine.layout(
@@ -66,27 +83,20 @@ module Elkrb
         #     "elk.force.repulsion" => 5.0
         #   )
         #
-        # @example With hierarchical layout
-        #   result = Elkrb::Layout::LayoutEngine.layout(
-        #     graph,
-        #     algorithm: "layered",
-        #     hierarchical: true
-        #   )
+        # Hierarchy is detected from compound nodes; no call flag is needed.
         def layout(graph, options = {})
-          # Convert hash to Graph if needed
-          graph = convert_to_graph(graph) if graph.is_a?(Hash)
+          graph = graph_argument(graph)
 
-          # Get algorithm name from options
-          algorithm_name = options[:algorithm] ||
-            options["algorithm"] ||
-            "layered"
+          resolver = Options::Resolver.new(options)
+          algorithm_name = resolver.get("elk.algorithm", graph)
 
           algorithm_class = AlgorithmRegistry.get(algorithm_name)
+          raise AlgorithmNotFoundError, algorithm_name unless algorithm_class
 
-          raise Error, "Unknown layout algorithm: #{algorithm_name}" unless
-            algorithm_class
+          resolver.report_unhonoured(
+            graph, algorithm_name: AlgorithmRegistry.method(:registered_name)
+          )
 
-          # Create and run algorithm with options
           algorithm = algorithm_class.new(options)
           algorithm.layout(graph)
 
@@ -104,6 +114,7 @@ module Elkrb
         #   - :description (String) - Brief description
         #   - :category (String, nil) - Algorithm category (e.g., "hierarchical", "force")
         #   - :supports_hierarchy (Boolean, nil) - Whether it supports hierarchical graphs
+        #   - :supported_options (Array<String>) - Canonical option ids scoped to this algorithm
         #
         # @example List all algorithms
         #   algorithms = Elkrb::Layout::LayoutEngine.known_layout_algorithms
@@ -152,11 +163,10 @@ module Elkrb
 
         # Returns metadata for all supported layout options.
         #
-        # @return [Array<Hash>] Array of option metadata
-        # @note Currently returns an empty array. Full implementation planned.
+        # @return [Hash{String => Hash}] Same shape and content as
+        #   Elkrb.known_layout_options, keyed by canonical id.
         def known_layout_options
-          # TODO: Build from all algorithms' supported options
-          []
+          Options::Registry.render_known_options(algorithm_values: AlgorithmRegistry.available_algorithms)
         end
 
         private
@@ -164,6 +174,19 @@ module Elkrb
         def convert_to_graph(hash)
           Graph::Graph.from_hash(hash)
         end
+
+        # Takes the two documented shapes and nothing else. The check lives
+        # here, not in Elkrb.layout, so the CLI and every other caller of the
+        # engine get the same clear error instead of a NoMethodError deep
+        # inside an algorithm.
+        def graph_argument(graph)
+          return convert_to_graph(graph) if graph.is_a?(::Hash)
+          return graph if graph.is_a?(Graph::Graph)
+
+          raise ArgumentError,
+                "graph must be a Hash or Elkrb::Graph::Graph, " \
+                "got #{graph.class}"
+        end
       end
     end
   end