elkrb 1.0.0 → 2.0.0

data/lib/elkrb/graph/graph.rb

@@ -10,17 +10,21 @@ module Elkrb
       attribute :y, :float
       attribute :width, :float
       attribute :height, :float
+      attribute :labels, Label, collection: true
+      attribute :ports, Port, collection: true
       attribute :children, Node, collection: true
       attribute :edges, Edge, collection: true
-      attribute :layout_options, LayoutOptions
+      attribute :layout_options, :hash
       attribute :properties, :hash
 
-      json do
+      key_value do
         map "id", to: :id
         map "x", to: :x
         map "y", to: :y
         map "width", to: :width
         map "height", to: :height
+        map "labels", to: :labels
+        map "ports", to: :ports
         map "children", to: :children
         map "edges", to: :edges
         map "layoutOptions", to: :layout_options
@@ -33,6 +37,8 @@ module Elkrb
         map "y", to: :y
         map "width", to: :width
         map "height", to: :height
+        map "labels", to: :labels
+        map "ports", to: :ports
         map "children", to: :children
         map "edges", to: :edges
         map "layout_options", to: :layout_options
@@ -46,10 +52,28 @@ module Elkrb
         @y ||= 0.0
         @width ||= 0.0
         @height ||= 0.0
-        @children ||= []
-        @edges ||= []
+        set_collection_defaults
         @properties ||= {}
-        @layout_options ||= LayoutOptions.new
+        @layout_options ||= {}
+      end
+
+      def set_collection_defaults
+        @labels = [] if @labels.nil?
+        @ports = [] if @ports.nil?
+        @children = [] if @children.nil?
+        @edges = [] if @edges.nil?
+      end
+      private :set_collection_defaults
+
+      # Normalizes a Symbol key however the options arrive — a constructor,
+      # a plain setter, or lutaml's own deserialization, which routes through
+      # here too. This is the single normalization point: a :hash-typed
+      # attribute otherwise stores a raw, unnormalized Hash.
+      def layout_options=(value)
+        value_set_for(:layout_options)
+        attr = self.class.attributes(lutaml_register)[:layout_options]
+        cast = attr.cast_value(DeepStringifyKeys.call(value), lutaml_register)
+        instance_variable_set(:@layout_options, NormalizeOptionKeys.call(cast))
       end
 
       def find_node(node_id)
@@ -69,21 +93,25 @@ module Elkrb
       end
 
       def all_edges
-        edges = @edges.dup
-        @children.each do |child|
-          edges.concat(child.edges) if child.respond_to?(:edges)
-          next unless child.respond_to?(:children)
-
-          child.children.each do |grandchild|
-            edges.concat(grandchild.all_edges) if
-              grandchild.respond_to?(:all_edges)
-          end
+        edges = (@edges || []).dup
+        (@children || []).each do |child|
+          edges.concat(descendant_edges(child))
         end
         edges
       end
 
       def hierarchical?
-        @children.any?(&:hierarchical?)
+        (@children || []).any?(&:hierarchical?)
+      end
+
+      private
+
+      def descendant_edges(node)
+        edges = (node.edges || []).dup
+        (node.children || []).each do |child|
+          edges.concat(descendant_edges(child))
+        end
+        edges
       end
     end
   end

data/lib/elkrb/graph/label.rb

@@ -11,9 +11,10 @@ module Elkrb
       attribute :y, :float
       attribute :width, :float
       attribute :height, :float
-      attribute :layout_options, LayoutOptions
+      attribute :layout_options, :hash
+      attribute :properties, :hash
 
-      json do
+      key_value do
         map "id", to: :id
         map "text", to: :text
         map "x", to: :x
@@ -21,6 +22,7 @@ module Elkrb
         map "width", to: :width
         map "height", to: :height
         map "layoutOptions", to: :layout_options
+        map "properties", to: :properties
       end
 
       yaml do
@@ -31,6 +33,7 @@ module Elkrb
         map "width", to: :width
         map "height", to: :height
         map "layout_options", to: :layout_options
+        map "properties", to: :properties
       end
 
       def initialize(**attributes)
@@ -40,6 +43,17 @@ module Elkrb
         @width ||= 0.0
         @height ||= 0.0
       end
+
+      # Normalizes a Symbol key however the options arrive — a constructor,
+      # a plain setter, or lutaml's own deserialization, which routes through
+      # here too. This is the single normalization point: a :hash-typed
+      # attribute otherwise stores a raw, unnormalized Hash.
+      def layout_options=(value)
+        value_set_for(:layout_options)
+        attr = self.class.attributes(lutaml_register)[:layout_options]
+        cast = attr.cast_value(DeepStringifyKeys.call(value), lutaml_register)
+        instance_variable_set(:@layout_options, NormalizeOptionKeys.call(cast))
+      end
     end
   end
 end

data/lib/elkrb/graph/node.rb

@@ -15,11 +15,11 @@ module Elkrb
       attribute :ports, Port, collection: true
       attribute :children, Node, collection: true
       attribute :edges, Edge, collection: true
-      attribute :layout_options, LayoutOptions
+      attribute :layout_options, :hash
       attribute :constraints, NodeConstraints
       attribute :properties, :hash
 
-      json do
+      key_value do
         map "id", to: :id
         map "x", to: :x
         map "y", to: :y
@@ -49,6 +49,17 @@ module Elkrb
         map "properties", to: :properties
       end
 
+      # Normalizes a Symbol key however the options arrive — a constructor,
+      # a plain setter, or lutaml's own deserialization, which routes through
+      # here too. This is the single normalization point: a :hash-typed
+      # attribute otherwise stores a raw, unnormalized Hash.
+      def layout_options=(value)
+        value_set_for(:layout_options)
+        attr = self.class.attributes(lutaml_register)[:layout_options]
+        cast = attr.cast_value(DeepStringifyKeys.call(value), lutaml_register)
+        instance_variable_set(:@layout_options, NormalizeOptionKeys.call(cast))
+      end
+
       def hierarchical?
         @children && !@children.empty?
       end

data/lib/elkrb/graph/node_constraints.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "lutaml/model"
+require_relative "read_only_mapping"
 
 module Elkrb
   module Graph
@@ -15,7 +16,7 @@ module Elkrb
       attribute :x, :float, default: -> { 0.0 }
       attribute :y, :float, default: -> { 0.0 }
 
-      json do
+      key_value do
         map "x", to: :x
         map "y", to: :y
       end
@@ -60,6 +61,8 @@ module Elkrb
     #   )
     #   # Node positioned 150px right of backend_service
     class NodeConstraints < Lutaml::Model::Serializable
+      include ReadOnlyMapping
+
       attribute :fixed_position, :boolean, default: -> { false }
       attribute :layer, :integer
       attribute :align_group, :string
@@ -68,7 +71,29 @@ module Elkrb
       attribute :relative_offset, RelativeOffset
       attribute :position_priority, :integer, default: -> { 0 }
 
-      json do
+      # Legacy camelCase YAML spellings, still readable so documents written
+      # against the old mapping keep working. Output is snake_case only.
+      LEGACY_YAML_KEYS = {
+        "fixedPosition" => :fixed_position,
+        "alignGroup" => :align_group,
+        "alignDirection" => :align_direction,
+        "relativeTo" => :relative_to,
+        "relativeOffset" => :relative_offset,
+        "positionPriority" => :position_priority,
+      }.freeze
+      private_constant :LEGACY_YAML_KEYS
+
+      # Every snake_case key, applied by the same hook just before the legacy
+      # spellings so a legacy spelling still wins.
+      CANONICAL_YAML_KEYS =
+        LEGACY_YAML_KEYS.values.to_h { |name| [name.to_s, name] }
+          .merge("layer" => :layer).freeze
+      private_constant :CANONICAL_YAML_KEYS
+
+      ALL_YAML_KEYS = CANONICAL_YAML_KEYS.merge(LEGACY_YAML_KEYS).freeze
+      private_constant :ALL_YAML_KEYS
+
+      key_value do
         map "fixedPosition", to: :fixed_position
         map "layer", to: :layer
         map "alignGroup", to: :align_group
@@ -78,14 +103,100 @@ module Elkrb
         map "positionPriority", to: :position_priority
       end
 
+      # YAML is snake_case like every other model here. The camelCase spellings
+      # stay readable so existing documents keep working, and a legacy spelling
+      # wins when a document carries both -- but only once the canonical rules
+      # have run. They run first, so a canonical value that fails to cast or
+      # validate raises before the hook is reached: `align_direction: sideways`
+      # alongside a valid `alignDirection: horizontal` raises rather than
+      # yielding "horizontal". The base had no snake_case key at all, so it
+      # could not hit this.
+      #
+      # The hook also re-applies every snake_case key, just before the legacy
+      # ones. Newer lutaml 0.8.x releases no longer run the cardinality check
+      # or the public setter for a canonical key (`layer: [1]` parses, and
+      # `align_direction: sideways` is stored), so the hook does both for the
+      # canonical spelling as well, and the two spellings reject the same input
+      # (an array for align_direction fails with a different error class).
+      #
+      # For every value shape -- scalar, wrong-typed, array and blank -- the
+      # hook casts through the attribute the way lutaml's own deserializer
+      # does, applies the same cardinality check, and assigns through the
+      # public setter, so it produces the same Ruby types and runs
+      # align_direction's validation.
+      #
+      # Two things about the shape of the rule, neither of them free choices:
+      #
+      # * It is ONE root-document rule, not six per-key ones. A per-key custom
+      #   rule is dropped before its hook runs when its value is blank
+      #   (key_value/transform.rb:251), which would turn `alignDirection: ''`
+      #   from a parse error into a silent nil. A plain `map ... to:` alias is
+      #   no good either -- it fires even when its key is absent, overwriting a
+      #   canonical-only read: with nil for an attribute that has no default,
+      #   and with the declared default otherwise (`fixed_position` back to
+      #   false, `position_priority` back to 0).
+      # * Its `to:` names a sentinel rather than a real attribute. lutaml
+      #   unwraps a root rule when the document has exactly one key equal to
+      #   `to:`, handing over that key's VALUE instead of the document
+      #   (services/rule_value_extractor.rb:36-47). It does that whatever the
+      #   value's type, whether or not `to:` names an attribute, and for the
+      #   key spelled as EITHER a String or a Symbol -- line 41 is the
+      #   size == 1 guard, line 43 tests the two spellings. So
+      #   the sentinel REDUCES the collision to documents whose sole key is
+      #   `__legacy_yaml_aliases` in either spelling; it does not eliminate it.
+      #   Naming a real attribute instead would collide on an ordinary key such
+      #   as `layer`, which is why the sentinel is still the better target. The
+      #   guard in the hook makes a NONBLANK NON-HASH collision inert -- a
+      #   scalar or a nonempty Array, neither of which answers to `key?`; a
+      #   nonempty Hash is still merged as though it were the document, which
+      #   is an accepted residual pinned in the spec. A blank unwrapped value
+      #   never reaches the hook at all -- transform.rb:251 drops the rule via
+      #   Utils.present? (utils.rb:119) for nil, "", [] and {}.
+      #
+      #   `to:` cannot simply be dropped: without it `nil.to_sym` raises for a
+      #   single-key document -- except a sole
+      #   empty-string key, which matches `nil.to_s` and short-circuits first.
+      #   A custom-method rule does not require the attribute to exist
+      #   (valid_rule? is `attribute || rule.custom_methods[:from]`).
       yaml do
-        map "fixedPosition", to: :fixed_position
+        map "fixed_position", to: :fixed_position
         map "layer", to: :layer
-        map "alignGroup", to: :align_group
-        map "alignDirection", to: :align_direction
-        map "relativeTo", to: :relative_to
-        map "relativeOffset", to: :relative_offset
-        map "positionPriority", to: :position_priority
+        map "align_group", to: :align_group
+        map "align_direction", to: :align_direction
+        map "relative_to", to: :relative_to
+        map "relative_offset", to: :relative_offset
+        map "position_priority", to: :position_priority
+        # Declared last, so a legacy spelling wins. See the note above the
+        # block for why this is one rule and why `to:` names no attribute.
+        map nil, to: :__legacy_yaml_aliases,
+                 with: { from: :__elkrb_merge_legacy_aliases,
+                         to: :__elkrb_omit_from_output }
+      end
+
+      # Serialization hook for every legacy camelCase spelling. Receives the
+      # whole YAML document, so a key that is present with a blank value is
+      # still seen. Public because lutaml invokes it with `public_send`; the
+      # `__elkrb_` prefix keeps a subclass from taking the name by accident.
+      # Not part of the supported API.
+      #
+      # @api private
+      def __elkrb_merge_legacy_aliases(model, doc)
+        # Only a NONBLANK value reaches here: transform.rb:251 drops the
+        # rule for nil, "", [] and {} before the hook runs. So a non-Hash
+        # arrives only when lutaml unwrapped a sole `__legacy_yaml_aliases`
+        # key holding a nonblank non-Hash value -- a scalar or a nonempty
+        # Array -- and ignoring it keeps that case inert. A nonempty Hash is
+        # still merged -- see the note above `yaml do`.
+        return unless doc.respond_to?(:key?) && doc.respond_to?(:[])
+
+        ALL_YAML_KEYS.each do |key_name, name|
+          # The standard YAML adapter preserves Symbol keys, and lutaml's own
+          # mappings resolve either spelling, so both are honoured here.
+          key = [key_name, key_name.to_sym].find { |candidate| doc.key?(candidate) }
+          next unless key
+
+          model.public_send(:"#{name}=", cast_legacy(model, name, doc[key]))
+        end
       end
 
       # Valid alignment directions
@@ -102,6 +213,26 @@ module Elkrb
         end
         @align_direction = value&.to_s&.downcase
       end
+
+      private
+
+      # Mirrors what lutaml's own deserializer does for a canonical
+      # `map ... to:` rule (key_value/transform.rb:261-266): cast through the
+      # attribute -- wired to the same parent and root -- then apply the
+      # cardinality check. Skipping the cast leaks lutaml wrapper objects into
+      # public attributes; skipping valid_collection! lets an array through for
+      # a scalar attribute, which the canonical spelling rejects and which
+      # reaches the layout engine as an Array.
+      def cast_legacy(model, name, value)
+        register = model.lutaml_register
+        attribute = model.class.attributes(register)[name]
+        cast = attribute.cast(
+          value, :yaml, register,
+          lutaml_parent: model, lutaml_root: model.lutaml_root || model
+        )
+        attribute.valid_collection!(cast, model.class)
+        cast
+      end
     end
   end
 end

data/lib/elkrb/graph/normalize_option_keys.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Elkrb
+  # Reopened only to attach NormalizeOptionKeys below. Graph is elkrb's data
+  # model namespace, collectively defined across lib/elkrb/graph/*.rb --
+  # there is no single file that owns it.
+  module Graph
+    # Normalizes the result of `attr.cast_value` for an options map, and
+    # rejects the one shape that result can take when a caller used a key
+    # lutaml-model has reserved.
+    #
+    # A non-Hash here is an INFERENCE, not a direct observation: lutaml reads
+    # a bare `text` or `elements` key as its own wrapper and casts the map
+    # down to that key's value, so anything but a Hash means a reserved key
+    # was used. Saying so beats letting the next line fail with a bare
+    # NoMethodError. The message is pinned by a matcher in
+    # spec/elkrb/graph/layout_options_spec.rb and must stay verbatim.
+    #
+    # Stringifies the TOP LEVEL only, matching the constructor this replaces.
+    # Deliberately not DeepStringifyKeys: that one walks nested Hashes and
+    # Arrays, this never did, and the models already ran it on the way in.
+    module NormalizeOptionKeys
+      module_function
+
+      def call(cast)
+        return cast if cast.nil?
+
+        unless cast.is_a?(::Hash)
+          raise Elkrb::ValidationError,
+                "layoutOptions cannot use `text` or `elements` as a key; " \
+                "both are reserved by lutaml-model"
+        end
+
+        cast.transform_keys(&:to_s)
+      end
+    end
+    private_constant :NormalizeOptionKeys
+  end
+end

data/lib/elkrb/graph/port.rb

@@ -11,11 +11,11 @@ module Elkrb
       attribute :width, :float
       attribute :height, :float
       attribute :labels, Label, collection: true
-      attribute :layout_options, LayoutOptions
+      attribute :layout_options, :hash
       attribute :properties, :hash
-      attribute :side, :string, default: -> { "UNDEFINED" }
-      attribute :index, :integer, default: -> { -1 }
-      attribute :offset, :float, default: -> { 0.0 }
+      attribute :side, :string
+      attribute :index, :integer
+      attribute :offset, :float
 
       # Port sides
       NORTH = "NORTH"
@@ -29,7 +29,7 @@ module Elkrb
       # Node reference (not serialized)
       attr_accessor :node
 
-      json do
+      key_value do
         map "id", to: :id
         map "x", to: :x
         map "y", to: :y
@@ -57,19 +57,21 @@ module Elkrb
         map "offset", to: :offset
       end
 
-      # Validate and set port side
-      #
-      # @param value [String] The port side (NORTH, SOUTH, EAST, WEST, UNDEFINED)
-      # @raise [ArgumentError] If the side value is invalid
-      def side=(value)
-        return if value.nil?
+      # Normalizes a Symbol key however the options arrive — a constructor,
+      # a plain setter, or lutaml's own deserialization, which routes through
+      # here too. This is the single normalization point: a :hash-typed
+      # attribute otherwise stores a raw, unnormalized Hash.
+      def layout_options=(value)
+        value_set_for(:layout_options)
+        attr = self.class.attributes(lutaml_register)[:layout_options]
+        cast = attr.cast_value(DeepStringifyKeys.call(value), lutaml_register)
+        instance_variable_set(:@layout_options, NormalizeOptionKeys.call(cast))
+      end
 
-        normalized = value.to_s.upcase
-        unless SIDES.include?(normalized)
-          raise ArgumentError,
-                "Invalid port side: #{value}. Must be one of #{SIDES.join(', ')}"
-        end
-        @side = normalized
+      # @param value [Object] candidate side
+      # @return [Boolean] whether the value is a canonical port side
+      def valid_side?(value)
+        SIDES.include?(value)
       end
 
       # Detect port side from position relative to node
@@ -82,11 +84,17 @@ module Elkrb
       # @return [String] The detected side (NORTH, SOUTH, EAST, WEST, UNDEFINED)
       def detect_side(node_width, node_height)
         return UNDEFINED if x.nil? || y.nil? || node_width.nil? || node_height.nil?
-        return UNDEFINED if node_width <= 0 || node_height <= 0
+        return UNDEFINED unless node_width.finite? && node_height.finite?
+        return UNDEFINED if node_width.zero? || node_height.zero?
 
-        # Calculate relative position (0.0 to 1.0)
-        rel_x = x / node_width.to_f
-        rel_y = y / node_height.to_f
+        # Relative position (0.0 to 1.0) from the real left/top edge, not
+        # from local x=0/y=0 -- for a negative dimension, local 0 is the
+        # real RIGHT/BOTTOM edge, so dividing by the raw signed value alone
+        # (as this used to) mislabels EAST ports as WEST and vice versa.
+        left = [0, node_width].min
+        top = [0, node_height].min
+        rel_x = (x - left) / node_width.abs.to_f
+        rel_y = (y - top) / node_height.abs.to_f
 
         # Calculate distance to each side
         distances = {

data/lib/elkrb/graph/read_only_mapping.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Elkrb
+  # Reopened only to attach ReadOnlyMapping below. Graph is elkrb's data
+  # model namespace, collectively defined across lib/elkrb/graph/*.rb --
+  # there is no single file that owns it.
+  module Graph
+    # The write half of a read-only `with:` mapping. lutaml requires both
+    # halves of a `with:` pair, and a legacy alias must contribute nothing to
+    # output -- one output vocabulary -- so this writes nothing on purpose.
+    module ReadOnlyMapping
+      # Public because lutaml invokes it with `public_send`; the `__elkrb_`
+      # prefix keeps a subclass from taking the name by accident. Not part of
+      # the supported API.
+      #
+      # @api private
+      def __elkrb_omit_from_output(model, doc); end
+    end
+    private_constant :ReadOnlyMapping
+  end
+end