ea 0.3.1 → 0.5.0

data/lib/ea/svg/ea_emitter/label/end_label.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    module EaEmitter
+      module Label
+        # Renders the role + «property» + multiplicity cluster at one
+        # endpoint of a UML association connector.
+        #
+        # EA encodes end-labels in two geometry boxes per endpoint:
+        #
+        #   LLT/LRT - "label text" position (role name slot)
+        #   LLB/LRB - "label box" position (multiplicity slot)
+        #
+        # Each box carries OX/OY offsets from the connector anchor.
+        # The «property» stereotype renders one line below the role
+        # name. EA records qualified role names ("pkg::role") for
+        # cross-package associations but suppresses label rendering
+        # for those — only simple role names render.
+        class EndLabel
+          PROPERTY_STEREOTYPE = "«property»"
+
+          attr_reader :canvas, :model_index, :document, :theme,
+                      :font_family, :font_size, :font_unit
+
+          def initialize(canvas:, model_index:, document:, theme:,
+                         font_family:, font_size:, font_unit:)
+            @canvas = canvas
+            @model_index = model_index
+            @document = document
+            @theme = theme
+            @font_family = font_family
+            @font_size = font_size
+            @font_unit = font_unit
+          end
+
+          # Returns an Array of `<text>` SVG strings for one endpoint.
+          #
+          #   text_box   - LLT or LRT box geometry (role position)
+          #   mult_box   - LLB or LRB box geometry (mult position)
+          #   anchor     - [x, y] of the connector endpoint
+          #   connector  - the DiagramConnector (for relationship lookup)
+          #   end_kind   - :source or :target
+          def texts(text_box:, mult_box:, anchor:, connector:, end_kind:)
+            from_property, role, mult = role_and_multiplicity(connector, end_kind)
+            if role_empty?(role) && mult_empty?(mult)
+              other_from_prop, other_role, other_mult = role_and_multiplicity(connector,
+                                                              opposite(end_kind))
+              role = other_role if role_empty?(role)
+              mult ||= other_mult
+              from_property ||= other_from_prop
+            end
+            agg = aggregation_kind_for(connector, end_kind)
+            standalone = standalone_multiplicity(role, mult, aggregation: agg)
+            return [] if role_empty?(role) && (standalone.nil? || standalone.empty?)
+
+            text_pos = position_at(text_box, anchor)
+            mult_pos = position_at(mult_box, anchor) || text_pos
+            show_property = property_label?(connector)
+
+            build_texts(role:, mult:, standalone:,
+                        text_pos:, mult_pos:, show_property:)
+          end
+
+          private
+
+          def build_texts(role:, mult:, standalone:, text_pos:, mult_pos:,
+                          show_property:)
+            if role && !role.empty? && text_pos
+              x, y = text_pos
+              texts = [text_at(x, y, role)]
+              if show_property
+                texts << text_at(x, y + property_y_offset, PROPERTY_STEREOTYPE)
+              end
+              if mult && !mult.empty? && mult_pos
+                texts << text_at(*mult_pos, mult)
+              end
+              texts
+            elsif standalone && !standalone.empty? && mult_pos
+              [text_at(*mult_pos, standalone)]
+            else
+              []
+            end
+          end
+
+          # EA renders «property» between role name and multiplicity
+          # ONLY for directed associations/aggregations — those with
+          # t_connector.Direction set to "Source -> Destination" or
+          # "Destination -> Source". "Unspecified" / "Bi-Directional"
+          # connectors do NOT get the stereotype label.
+          #
+          # Verified against both QEAs (output by the same EA in the
+          # same run):
+          #   - basic.qea: 4 Associations with Direction="Unspecified"
+          #     and role+mult → 0 «property» labels.
+          #   - plateau QEA: aggregations with Direction="Destination
+          #     -> Source" → «property» rendered (737 instances across
+          #     137 diagrams).
+          UNDIRECTED_DIRECTIONS = %w[Unspecified Bi-Directional].freeze
+
+          def property_label?(connector)
+            direction = connector.direction.to_s
+            return false if direction.empty?
+            return false if UNDIRECTED_DIRECTIONS.include?(direction)
+
+            true
+          end
+
+          def role_empty?(role)
+            role.nil? || role.empty?
+          end
+
+          def mult_empty?(mult)
+            mult.nil? || mult.empty?
+          end
+
+          def opposite(end_kind)
+            end_kind == :source ? :target : :source
+          end
+
+          def role_and_multiplicity(connector, end_kind)
+            assoc = association_for(connector)
+            return [nil, nil, nil] unless assoc
+
+            prop = property_at_end(assoc, end_kind)
+            return [true, *property_role(prop)] if prop
+
+            [false, *association_role(assoc, end_kind)]
+          end
+
+          def property_at_end(association, end_kind)
+            id = end_kind == :source ? association.source_id : association.target_id
+            return nil unless id
+
+            return document.property_by_id(id) if document
+
+            fallback_property_lookup(id)
+          end
+
+          # Linear-scan fallback for callers that did not wire in
+          # the Document. Production paths go through Document's
+          # property_index for O(1) lookup.
+          def fallback_property_lookup(id)
+            return nil unless model_index
+
+            model_index.each_value do |obj|
+              next unless obj.is_a?(Ea::Model::Classifier)
+
+              found = (obj.properties || []).find { |p| p.id == id }
+              return found if found
+            end
+            nil
+          end
+
+          def property_role(property)
+            visibility = visibility_prefix(property)
+            name = property.name.to_s
+            role = name.empty? ? nil : "#{visibility}#{name}"
+            mult = multiplicity_text(property)
+            [role, mult]
+          end
+
+          def association_role(assoc, end_kind)
+            name = end_kind == :source ? assoc.source_role_name : assoc.target_role_name
+            lower = end_kind == :source ? assoc.source_multiplicity_lower : assoc.target_multiplicity_lower
+            upper = end_kind == :source ? assoc.source_multiplicity_upper : assoc.target_multiplicity_upper
+            return [nil, multiplicity_string(lower, upper)] if name.to_s.include?("::")
+
+            role = name.nil? || name.empty? ? nil : "+#{name}"
+            mult = multiplicity_string(lower, upper)
+            [role, mult]
+          end
+
+          def association_for(connector)
+            return nil unless model_index
+
+            rel = model_index[connector.relationship_ref]
+            return nil unless rel.is_a?(Ea::Model::Association)
+
+            rel
+          end
+
+          # Returns the aggregation kind for the given end (:shared,
+          # :composite, or nil). An aggregation marker on the OPPOSITE
+          # end means THIS end is the "part" end of an aggregation —
+          # EA shows "1" multiplicity for such ends.
+          def aggregation_kind_for(connector, end_kind)
+            assoc = association_for(connector)
+            return nil unless assoc
+
+            opposite_kind = opposite(end_kind)
+            agg = opposite_kind == :source ? assoc.source_aggregation : assoc.target_aggregation
+            return nil if agg.nil? || agg == "none"
+
+            agg.to_sym
+          end
+
+          def position_at(box, anchor)
+            return nil unless box
+
+            offset_x = box["ox"] || box[:ox]
+            offset_y = box["oy"] || box[:oy]
+            return nil if offset_x.nil? && offset_y.nil?
+
+            [anchor[0] + offset_x.to_i, anchor[1] + offset_y.to_i]
+          end
+
+          def property_y_offset
+            font_size + 6
+          end
+
+          def multiplicity_text(property)
+            multiplicity_string(property.multiplicity_lower,
+                                property.multiplicity_upper)
+          end
+
+          def multiplicity_string(lower, upper)
+            return nil if lower.nil? && upper.nil?
+            return "1" if lower == 1 && upper == 1
+
+            upper_str = upper == -1 ? "*" : upper.to_s
+            "#{lower || 0}..#{upper_str}"
+          end
+
+          # EA suppresses standalone multiplicity when it is
+          # unspecified (nil). Explicit multiplicity renders
+          # regardless of aggregation kind. The QEA parser now
+          # returns nil for absent SourceCard/DestCard so default
+          # "1" is no longer produced — only explicit "1" reaches
+          # this method.
+          def standalone_multiplicity(role, mult, aggregation: nil)
+            return nil if role && !role.empty?
+            return nil if mult.nil?
+
+            mult
+          end
+
+          def visibility_prefix(property)
+            case property.visibility
+            when "private"   then "-"
+            when "protected" then "#"
+            when "package"   then "~"
+            else "+"
+            end
+          end
+
+          def text_at(x, y, content)
+            return nil if content.nil? || content.empty?
+
+            x_t = canvas ? canvas.translate_x(x) : x
+            y_t = canvas ? canvas.translate_y(y) : y
+            TextRenderer.new(content:, x: x_t, y: y_t,
+                             family: font_family, size: font_size,
+                             size_unit: font_unit,
+                             fill: fill_color,
+                             text_length: content.length * 6).to_svg
+          end
+
+          def fill_color
+            "#000000"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ea/svg/ea_emitter/label/midpoint_label.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    module EaEmitter
+      module Label
+        # Renders the midpoint label for a connector. EA emits one
+        # of two things at the midpoint, but not both:
+        #
+        #   1. «stereotype» when the relationship has an applied
+        #      stereotype (e.g. «import», «realize»).
+        #   2. The relationship's Name when no stereotype is applied
+        #      and Name is non-empty (e.g. "Association A").
+        #
+        # Stereotype wins when both are present.
+        class MidpointLabel
+          attr_reader :canvas, :model_index, :font_family, :font_size,
+                      :font_unit
+
+          def initialize(canvas:, model_index:, font_family:, font_size:,
+                         font_unit:)
+            @canvas = canvas
+            @model_index = model_index
+            @font_family = font_family
+            @font_size = font_size
+            @font_unit = font_unit
+          end
+
+          # Returns the SVG `<text>` for the connector's midpoint
+          # label, or nil if there is no label to render.
+          def text_for(connector, points)
+            content = midpoint_content(connector)
+            return nil if content.nil?
+
+            mx, my = midpoint(points)
+            render_text(mx, my, content)
+          end
+
+          # Returns the formatted «stereotype» string or nil. Used
+          # by Label::Registry to dispatch end-label vs midpoint.
+          def stereotype_label(connector)
+            rel = relationship_for(connector)
+            return nil unless rel
+
+            stereotype = rel.stereotype
+            return nil if stereotype.nil? || stereotype.to_s.empty?
+
+            "«#{stereotype}»"
+          end
+
+          # Returns the midpoint label content: stereotype if
+          # present, else the relationship Name.
+          def midpoint_content(connector)
+            stereotype = stereotype_label(connector)
+            return stereotype if stereotype
+
+            rel = relationship_for(connector)
+            return nil unless rel
+
+            name = rel.name
+            return nil if name.nil? || name.to_s.empty?
+
+            name.to_s
+          end
+
+          def relationship_for(connector)
+            return nil unless model_index
+
+            rel = model_index[connector.relationship_ref]
+            return nil unless rel.is_a?(Ea::Model::Relationship)
+
+            rel
+          end
+
+          private
+
+          def midpoint(points)
+            mid_idx = points.size / 2
+            if points.size.odd?
+              points[mid_idx]
+            else
+              a = points[mid_idx - 1]
+              b = points[mid_idx]
+              [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2]
+            end
+          end
+
+          def render_text(x, y, content)
+            x_t = canvas ? canvas.translate_x(x) : x
+            y_t = canvas ? canvas.translate_y(y) : y
+            TextRenderer.new(content:, x: x_t, y: y_t,
+                             family: font_family, size: font_size,
+                             size_unit: font_unit,
+                             fill: "#000000",
+                             text_length: content.length * 6).to_svg
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ea/svg/ea_emitter/label/registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    module EaEmitter
+      module Label
+        # Dispatches a connector to the appropriate label renderer(s).
+        #
+        # Rules:
+        #   - Any relationship with an applied stereotype renders
+        #     «stereotype» at the midpoint (Associations included —
+        #     «import» on a Package connector is a common case).
+        #   - Associations without a stereotype render EndLabel at
+        #     each positioned LLT/LRT box.
+        #   - Other relationship kinds without a stereotype render
+        #     nothing.
+        #
+        # Open/closed: a new label kind registers here rather than
+        # forcing callers to edit case statements elsewhere.
+        class Registry
+          attr_reader :model_index
+
+          def initialize(model_index:)
+            @model_index = model_index
+          end
+
+          # Returns the formatted stereotype label when the
+          # connector should render at the midpoint, nil otherwise.
+          def midpoint?(connector)
+            MidpointLabel.new(canvas: nil, model_index: model_index,
+                              font_family: nil, font_size: nil,
+                              font_unit: nil).stereotype_label(connector)
+          end
+
+          # Returns true if the connector's relationship is an
+          # Association AND has no midpoint stereotype (the end-label
+          # path).
+          def end_label?(connector)
+            association?(connector) && !midpoint?(connector)
+          end
+
+          def association?(connector)
+            rel = model_index ? model_index[connector.relationship_ref] : nil
+            rel.is_a?(Ea::Model::Association)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ea/svg/ea_emitter/label.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    module EaEmitter
+      # Per-connector label renderers. Each renderer handles one
+      # visual label kind on a connector:
+      #
+      #   EndLabel       - role + «property» + multiplicity at
+      #                    LLT/LRT box positions (UML associations)
+      #   MidpointLabel  - «stereotype» at the connector midpoint
+      #                    (Package / Dependency / Realization)
+      #
+      # Registry dispatches by relationship kind so new label kinds
+      # register rather than editing the orchestrator (OCP).
+      module Label
+        autoload :EndLabel, "ea/svg/ea_emitter/label/end_label"
+        autoload :MidpointLabel, "ea/svg/ea_emitter/label/midpoint_label"
+        autoload :Registry, "ea/svg/ea_emitter/label/registry"
+      end
+    end
+  end
+end

data/lib/ea/svg/ea_emitter/labels.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    module EaEmitter
+      # Emits the labels layer: connector role/multiplicity end
+      # labels plus midpoint stereotype labels for non-association
+      # connectors.
+      #
+      # This class is the orchestrator. The actual label-shaping
+      # logic lives in dedicated, MECE collaborators under
+      # `Ea::Svg::EaEmitter::Label`:
+      #
+      #   Label::EndLabel      - role + «property» + mult at LLT/LRT
+      #   Label::MidpointLabel - «stereotype» at connector midpoint
+      #   Label::Registry      - dispatch by relationship kind (OCP)
+      #
+      # Theme is read once and threaded to collaborators so the
+      # rendering rules (font family/size, fill color) live in one
+      # place.
+      class Labels
+        DEFAULT_FAMILY = "Yu Gothic UI"
+        DEFAULT_SIZE = 13
+
+        attr_reader :diagram, :canvas, :model_index, :theme, :document
+
+        def initialize(diagram, canvas: nil, model_index: nil, theme: nil,
+                       document: nil)
+          @diagram = diagram
+          @canvas = canvas
+          @model_index = model_index
+          @theme = theme || Ea::Theme::Registry.default
+          @document = document
+        end
+
+        def render
+          texts = visible_connectors.flat_map { |c| texts_for(c) }
+          return "" if texts.empty?
+
+          %(<g style="stroke-width:1;stroke-linecap:round;stroke-linejoin:bevel; fill:#000000;fill-opacity:1.00; stroke:#000000; stroke-opacity:0.00">\n#{texts.join("\n")}\n</g>)
+        end
+
+        private
+
+        def visible_connectors
+          (diagram.connectors || []).select(&:renderable?)
+        end
+
+        def texts_for(connector)
+          points = waypoint_pairs(connector)
+          return [] if points.size < 2
+
+          texts = []
+
+          # Midpoint label: stereotype «import», or relationship
+          # Name ("Association A"). Renders at the path midpoint.
+          mid_text = midpoint_renderer.text_for(connector, points)
+          texts << mid_text if mid_text
+
+          # End-labels: role name + «property» + multiplicity at
+          # positioned LLT/LRT boxes. Only for associations without
+          # a midpoint stereotype (stereotyped associations route
+          # to midpoint only).
+          if registry.end_label?(connector)
+            end_label_texts(connector, points).each { |t| texts << t }
+          end
+
+          texts
+        end
+
+        def end_label_texts(connector, points)
+          source_pt = points.first
+          target_pt = points.last
+          boxes = connector.label_boxes || {}
+
+          texts = []
+          end_renderer.texts(text_box: boxes[:llt], mult_box: boxes[:llb],
+                             anchor: source_pt, connector: connector,
+                             end_kind: :source).each { |t| texts << t }
+          end_renderer.texts(text_box: boxes[:lrt], mult_box: boxes[:lrb],
+                             anchor: target_pt, connector: connector,
+                             end_kind: :target).each { |t| texts << t }
+          texts
+        end
+
+        def registry
+          @registry ||= Label::Registry.new(model_index: model_index)
+        end
+
+        def end_renderer
+          @end_renderer ||= Label::EndLabel.new(
+            canvas: canvas,
+            model_index: model_index,
+            document: document,
+            theme: theme,
+            font_family: label_font_family,
+            font_size: label_font_size,
+            font_unit: theme.font_size_unit
+          )
+        end
+
+        def midpoint_renderer
+          @midpoint_renderer ||= Label::MidpointLabel.new(
+            canvas: canvas,
+            model_index: model_index,
+            font_family: label_font_family,
+            font_size: label_font_size,
+            font_unit: theme.font_size_unit
+          )
+        end
+
+        def waypoint_pairs(connector)
+          (connector.waypoints || []).filter_map do |w|
+            next unless w.position
+
+            [w.position.x, w.position.y]
+          end
+        end
+
+        def label_font_family
+          theme.font_family || DEFAULT_FAMILY
+        end
+
+        def label_font_size
+          theme.font_size || DEFAULT_SIZE
+        end
+      end
+    end
+  end
+end

data/lib/ea/svg/ea_emitter/layer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    module EaEmitter
+      # A single `<g>` block ready for inclusion in the SVG output.
+      # Carries the style string and the body (one or more child
+      # elements: `<path>`, `<polygon>`, `<text>`, `<rect>`).
+      #
+      # Emitters return Arrays of Layer objects. The Document
+      # orchestrator either joins them as-is (per-entity ordering)
+      # or buckets them by `style_key` for EA-style grouped output.
+      Layer = Struct.new(:style_key, :style, :body, keyword_init: true) do
+        def to_svg
+          %(<g style="#{style}">\n#{body}\n</g>)
+        end
+      end
+    end
+  end
+end

data/lib/ea/svg/ea_emitter/layer_sequencer.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Ea
+  module Svg
+    module EaEmitter
+      # Sequences SVG layer output in EA's canonical order:
+      #
+      #   1. Background <g>
+      #   2. (optional) Diagram frame: border + tab + label
+      #   3. Per-element groups (shape, header, divider, attrs)
+      #   4. Connector + marker groups (merged by style)
+      #   5. Labels <g>
+      #
+      # Reads diagram.theme once and passes to all child renderers
+      # so theme settings (font, colors, stroke width) apply
+      # uniformly across the entire SVG output.
+      #
+      # Document delegates the layer assembly here so the Document
+      # class shrinks to SVG envelope construction.
+      class LayerSequencer
+        DEFAULT_STROKE_WIDTH = 2
+
+        attr_reader :diagram, :model_index, :canvas, :frame_enabled, :theme,
+                    :document
+
+        def initialize(diagram, model_index:, canvas:, frame: false, document: nil)
+          @diagram = diagram
+          @model_index = model_index
+          @canvas = canvas
+          @frame_enabled = frame
+          @theme = diagram.theme
+          @document = document
+        end
+
+        def layers
+          layers = [Background.render(canvas)]
+          layers += frame_layers if frame_enabled
+          layers += element_layers
+          layers += connector_layers
+          layers << labels_layer
+          layers << ghost_labels_layer
+          layers
+        end
+
+        private
+
+        def frame_layers
+          DiagramFrame.new(canvas: canvas, theme: theme).layers(diagram).map(&:to_svg)
+        end
+
+        def element_layers
+          Elements.new(diagram, model_index: model_index, canvas: canvas,
+                        document: document).groups
+        end
+
+        def connector_layers
+          connector_layers_raw = Connectors.new(diagram, canvas: canvas,
+                                                  grouped: true,
+                                                  stroke_width: DEFAULT_STROKE_WIDTH).layers
+          marker_layers_raw = Markers.new(diagram, model_index: model_index,
+                                           canvas: canvas, grouped: true,
+                                           stroke_width: DEFAULT_STROKE_WIDTH).layers
+          merge_layers_by_style(connector_layers_raw + marker_layers_raw).map(&:to_svg)
+        end
+
+        def labels_layer
+          Labels.new(diagram, canvas: canvas, model_index: model_index,
+                      theme: theme, document: document).render
+        end
+
+        def ghost_labels_layer
+          GhostLabels.new(diagram, canvas: canvas).render
+        end
+
+        def merge_layers_by_style(layers)
+          merged = {}
+          layers.each do |layer|
+            if merged[layer.style_key]
+              merged[layer.style_key] = Layer.new(
+                style_key: layer.style_key,
+                style: layer.style,
+                body: "#{merged[layer.style_key].body}\n  #{layer.body}"
+              )
+            else
+              merged[layer.style_key] = layer
+            end
+          end
+          merged.values
+        end
+      end
+    end
+  end
+end