ea 0.3.1 → 0.5.0

data/lib/ea/mdg/xml/technology.rb

@@ -0,0 +1,28 @@
+# frozen_string: true
+
+require "lutaml/model"
+
+module Ea
+  module Mdg
+    module Xml
+      class Technology < Lutaml::Model::Serializable
+        attribute :version, :string
+        attribute :documentation, Documentation
+        attribute :uml_profiles, UmlProfiles
+        # Some MDG files place additional <UMLProfile> elements
+        # as direct children of <MDG.Technology> alongside
+        # <UMLProfiles>, not inside it.
+        attribute :standalone_profiles, UmlProfile, collection: true,
+                                                   initialize_empty: true
+
+        xml do
+          root "MDG.Technology"
+          map_attribute "version", to: :version
+          map_element "Documentation", to: :documentation
+          map_element "UMLProfiles", to: :uml_profiles
+          map_element "UMLProfile", to: :standalone_profiles
+        end
+      end
+    end
+  end
+end

data/lib/ea/mdg/xml/uml_profile.rb

@@ -0,0 +1,22 @@
+# frozen_string: true
+
+require "lutaml/model"
+
+module Ea
+  module Mdg
+    module Xml
+      class UmlProfile < Lutaml::Model::Serializable
+        attribute :profiletype, :string
+        attribute :documentation, Documentation
+        attribute :content, Content
+
+        xml do
+          root "UMLProfile"
+          map_attribute "profiletype", to: :profiletype
+          map_element "Documentation", to: :documentation
+          map_element "Content", to: :content
+        end
+      end
+    end
+  end
+end

data/lib/ea/mdg/xml/uml_profiles.rb

@@ -0,0 +1,18 @@
+# frozen_string: true
+
+require "lutaml/model"
+
+module Ea
+  module Mdg
+    module Xml
+      class UmlProfiles < Lutaml::Model::Serializable
+        attribute :profiles, UmlProfile, collection: true, initialize_empty: true
+
+        xml do
+          root "UMLProfiles"
+          map_element "UMLProfile", to: :profiles
+        end
+      end
+    end
+  end
+end

data/lib/ea/mdg/xml.rb

@@ -0,0 +1,24 @@
+# frozen_string: true
+
+require "lutaml/model"
+
+module Ea
+  module Mdg
+    # lutaml-model classes for the EA MDG.Technology XML format.
+    # These are the deserialization models — use `from_xml` on
+    # MdgTechnology to parse an MDG.Technology file.
+    module Xml
+      autoload :Technology, "ea/mdg/xml/technology"
+      autoload :Documentation, "ea/mdg/xml/documentation"
+      autoload :UmlProfiles, "ea/mdg/xml/uml_profiles"
+      autoload :UmlProfile, "ea/mdg/xml/uml_profile"
+      autoload :Content, "ea/mdg/xml/content"
+      autoload :Stereotypes, "ea/mdg/xml/stereotypes"
+      autoload :Stereotype, "ea/mdg/xml/stereotype"
+      autoload :TaggedValues, "ea/mdg/xml/tagged_values"
+      autoload :Tag, "ea/mdg/xml/tag"
+      autoload :AppliesTo, "ea/mdg/xml/applies_to"
+      autoload :Apply, "ea/mdg/xml/apply"
+    end
+  end
+end

data/lib/ea/mdg.rb

@@ -0,0 +1,25 @@
+# frozen_string: true
+
+require "lutaml/model"
+
+module Ea
+  # MDG (Model Driven Generation) Technology support.
+  #
+  # EA's MDG technologies bundle UML profiles, reference models,
+  # and toolbox definitions in a single XMI file. When EA loads
+  # an MDG, the MDG's classes/attributes/stereotypes become
+  # available to all models — including inherited attribute
+  # rendering when a classifier's stereotype maps to an MDG-
+  # defined metaclass.
+  #
+  # This namespace is standalone: it does not depend on QEA or
+  # XMI source adapters. Source adapters OPTIONALLY consume an
+  # Mdg::Registry to merge MDG-defined inherited attributes.
+  module Mdg
+    autoload :Document, "ea/mdg/document"
+    autoload :Loader, "ea/mdg/loader"
+    autoload :Registry, "ea/mdg/registry"
+    autoload :StereotypeAliasRegistry, "ea/mdg/stereotype_alias_registry"
+    autoload :Xml, "ea/mdg/xml"
+  end
+end

data/lib/ea/model/classifier.rb

@@ -13,6 +13,7 @@ module Ea
     class Classifier < Base
       attribute :qualified_name, :string
       attribute :package_id, :string # containing package
+      attribute :package_name, :string # containing package name
       attribute :is_abstract, :boolean, default: false
       attribute :visibility, :string
       attribute :model_kind, :string, default: -> { "classifier" }
@@ -20,6 +21,7 @@ module Ea
       attribute :operations, Operation, collection: true, initialize_empty: true
       attribute :stereotype_refs, :string, collection: true, initialize_empty: true
       attribute :tagged_values, TaggedValue, collection: true, initialize_empty: true
+      attribute :constraints, Constraint, collection: true, initialize_empty: true
       attribute :annotations, Annotation, collection: true, initialize_empty: true
 
       json do
@@ -27,6 +29,7 @@ module Ea
         map "name", to: :name
         map "qualifiedName", to: :qualified_name
         map "packageId", to: :package_id
+        map "packageName", to: :package_name
         map "isAbstract", to: :is_abstract, render_default: true
         map "visibility", to: :visibility
         map "modelKind", to: :model_kind, render_default: true
@@ -34,6 +37,7 @@ module Ea
         map "operations", to: :operations, render_empty: true
         map "stereotypeRefs", to: :stereotype_refs, render_empty: true
         map "taggedValues", to: :tagged_values, render_empty: true
+        map "constraints", to: :constraints, render_empty: true
         map "annotations", to: :annotations, render_empty: true
       end
     end

data/lib/ea/model/constraint.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ea
+  module Model
+    # A UML/OCL constraint attached to a classifier or other model
+    # element. EA stores these in t_objectconstraint; the `name` is
+    # the constraint label (rendered as "{name}" in the constraints
+    # compartment), and the body holds the OCL expression.
+    class Constraint < Base
+      attribute :name, :string
+      attribute :kind, :string # "OCL", "Invariant", "Postcondition", etc.
+      attribute :body, :string
+      attribute :status, :string
+
+      json do
+        map "id", to: :id
+        map "name", to: :name
+        map "kind", to: :kind
+        map "body", to: :body
+        map "status", to: :status
+      end
+    end
+  end
+end

data/lib/ea/model/diagram.rb

@@ -9,6 +9,13 @@ module Ea
       attribute :package_id, :string
       attribute :diagram_type, :string  # logical|class|sequence|use_case|...
       attribute :bounds, Bounds         # canvas size
+      attribute :style, :string         # raw t_diagram.Style (HideAtts=1;HideOps=0;...)
+      attribute :style_ex, :string      # raw t_diagram.StyleEx (Theme=:NNN;SuppressFOC=1;...)
+      attribute :theme_override_id, :string # set by theme= when given an ID
+      attribute :show_package_contents, :boolean, default: false
+      attribute :hand_draw, :boolean, default: false
+      attribute :show_notes, :boolean, default: false
+      attribute :show_parents, :boolean, default: true
       attribute :elements, DiagramElement, collection: true, initialize_empty: true
       attribute :connectors, DiagramConnector, collection: true, initialize_empty: true
       attribute :annotations, Annotation, collection: true, initialize_empty: true
@@ -19,10 +26,88 @@ module Ea
         map "packageId", to: :package_id
         map "diagramType", to: :diagram_type
         map "bounds", to: :bounds
+        map "style", to: :style
+        map "styleEx", to: :style_ex
+        map "themeOverrideId", to: :theme_override_id
+        map "showPackageContents", to: :show_package_contents
+        map "handDraw", to: :hand_draw
+        map "showNotes", to: :show_notes
+        map "showParents", to: :show_parents
         map "elements", to: :elements, render_empty: true
         map "connectors", to: :connectors, render_empty: true
         map "annotations", to: :annotations, render_empty: true
       end
+
+      # Parses style_ex into a Hash of flag => value. Returns empty
+      # Hash when style_ex is nil/empty.
+      #
+      # Example: "Theme=:119;SuppressFOC=1;AttPkg=1" →
+      #   { "Theme" => ":119", "SuppressFOC" => "1", "AttPkg" => "1" }
+      def style_ex_flags
+        return {} if style_ex.nil? || style_ex.empty?
+
+        style_ex.split(";").filter_map do |pair|
+          next nil unless pair.include?("=")
+
+          key, value = pair.split("=", 2)
+          [key, value.to_s] if key && !key.empty?
+        end.to_h
+      end
+
+      # Returns the effective theme ID. Resolved from (in order):
+      #   1. theme_override_id (set by theme=)
+      #   2. style_ex_flags["Theme"]
+      #
+      # @return [String, nil]
+      def theme_id
+        theme_override_id || style_ex_flags["Theme"]
+      end
+
+      # Returns the resolved Theme Definition. Looks up from the
+      # Registry by theme_id, falling back to default.
+      #
+      # @return [Ea::Theme::Definition]
+      def theme
+        Ea::Theme::Registry.lookup(theme_id)
+      end
+
+      # Returns the DisplayConfig parsed from style + style_ex.
+      # Controls behavioral rendering flags (HideAtts, HideOps,
+      # SuppressFOC, AttPub, ShowNotes, etc.).
+      #
+      # @return [Ea::Diagram::DisplayConfig]
+      def display_config
+        Ea::Diagram::DisplayConfig.from_style(style:, style_ex:)
+      end
+
+      # Set the diagram's theme. Accepts:
+      #
+      #   diagram.theme = :119          # by Symbol ID
+      #   diagram.theme = ":119"        # by String ID
+      #   diagram.theme = "119"         # by String ID (no colon)
+      #   diagram.theme = definition    # by Definition object
+      #
+      # When given an ID, sets theme_override_id. When given a
+      # Definition, registers it in the Registry and stores its ID.
+      #
+      # @param value [Symbol, String, Ea::Theme::Definition]
+      def theme=(value)
+        case value
+        when Ea::Theme::Definition
+          Ea::Theme::Registry.register(value)
+          @theme_override_id = value.id
+        else
+          @theme_override_id = normalize_theme_id(value)
+        end
+      end
+
+      private
+
+      def normalize_theme_id(value)
+        return nil if value.nil?
+
+        value.to_s.gsub(/^:/, "")
+      end
     end
   end
 end

data/lib/ea/model/diagram_connector.rb

@@ -5,15 +5,33 @@ module Ea
     # A connector drawn on a diagram between two DiagramElements.
     # References the underlying Relationship (by id) and the source
     # and target DiagramElements (by id). Carries ordered waypoints
-    # for routing.
+    # for routing plus the EA EDGE codes (1=top, 2=right, 3=bottom,
+    # 4=left, 5..8=diagonal variants) which tell the renderer where
+    # to anchor the line on each end.
     class DiagramConnector < Base
       attribute :diagram_id, :string
       attribute :relationship_ref, :string
       attribute :source_element_ref, :string
       attribute :target_element_ref, :string
+      attribute :source_duid, :string
+      attribute :target_duid, :string
+      attribute :source_edge, :integer
+      attribute :target_edge, :integer
+      attribute :connector_type, :string
+      attribute :direction, :string
       attribute :waypoints, Waypoint, collection: true, initialize_empty: true
       attribute :label, :string
       attribute :style, :hash, default: -> { {} }
+      attribute :line_color, :integer
+      attribute :line_width, :integer
+      attribute :hidden, :boolean
+      attribute :label_boxes, :hash, default: -> { {} }
+      attribute :ghost_labels, GhostLabel, collection: true, initialize_empty: true
+      # True when the t_diagramlinks.Geometry string carries explicit
+      # SX/SY/EX/EY offset fields. EA renders the «import» package_anchor
+      # marker only for connectors with explicit offsets — auto-routed
+      # connectors (no SX/SY) get a plain solid line.
+      attribute :has_geometry_offsets, :boolean, default: false
 
       json do
         map "id", to: :id
@@ -21,9 +39,43 @@ module Ea
         map "relationshipRef", to: :relationship_ref
         map "sourceElementRef", to: :source_element_ref
         map "targetElementRef", to: :target_element_ref
+        map "sourceDuid", to: :source_duid
+        map "targetDuid", to: :target_duid
+        map "sourceEdge", to: :source_edge
+        map "targetEdge", to: :target_edge
+        map "connectorType", to: :connector_type
+        map "direction", to: :direction
         map "waypoints", to: :waypoints, render_empty: true
         map "label", to: :label
         map "style", to: :style
+        map "lineColor", to: :line_color
+        map "lineWidth", to: :line_width
+        map "hidden", to: :hidden, render_default: true
+        map "labelBoxes", to: :label_boxes
+        map "ghostLabels", to: :ghost_labels, render_empty: true
+        map "hasGeometryOffsets", to: :has_geometry_offsets, render_default: true
+      end
+
+      # EA encodes package nesting and other implicit relationships
+      # as connector rows in t_diagramlinks. These are typically
+      # not rendered as paths in the SVG output — the containment
+      # is implied by visual position. However, when a connector
+      # has the `tree` style attribute (e.g. "V" for vertical tree
+      # routing), EA renders it as a real visible connector with
+      # a "+" marker at the contained end.
+      IMPLICIT_TYPES = %w[Nesting].freeze
+
+      # True when this connector should appear in SVG output. False
+      # when hidden via the Hidden flag. Implicit-type connectors
+      # (e.g. Nesting) are filtered out UNLESS they carry a `tree`
+      # style attribute marking them as visible (basic.qea's
+      # "Package Contents" diagram has visible nesting; simple.qea's
+      # "Package Contents" diagram has invisible implicit nesting).
+      def renderable?
+        return false if hidden
+        return true unless IMPLICIT_TYPES.include?(connector_type.to_s)
+
+        (style || {}).key?(:tree) || (style || {}).key?("tree")
       end
     end
   end

data/lib/ea/model/diagram_element.rb

@@ -5,18 +5,62 @@ module Ea
     # A single placed element on a diagram. References the model
     # element it visualizes (by id), carries pixel bounds and a
     # parsed style map (fill color, line color, font, etc.).
+    #
+    # Carries two distinct bounds:
+    # - `bounds` — logical rect (EA's Left/Top/Right/Bottom)
+    # - `image_bounds` — visual rect including padding (EA's
+    #   imgL/imgT/imgR/imgB); used by EA's SVG renderer for the
+    #   actual `<rect>` width/height
     class DiagramElement < Base
       attribute :diagram_id, :string
       attribute :model_element_ref, :string # id of Classifier/Package/etc.
       attribute :bounds, Bounds
+      attribute :image_bounds, Bounds
       attribute :style, :hash, default: -> { {} } # parsed style fields
+      attribute :background_color, :integer # EA BGR integer
+      attribute :line_color, :integer
+      attribute :line_width, :integer
+      attribute :font_family, :string
+      attribute :font_size, :integer
+      attribute :font_bold, :boolean
+      attribute :font_italic, :boolean
+      attribute :font_underline, :boolean
+      attribute :show_tagged_values, :boolean
+      # EA's per-element "HideIcon" flag — tri-state:
+      #   "shown"  → HideIcon=0, render the type icon
+      #   "hidden" → HideIcon=1, suppress the type icon
+      #   nil      → not set in source; renderer applies the
+      #              diagram default (typically hidden).
+      attribute :icon_visibility, :string
+      attribute :z_order, :integer # seqno
+      attribute :duid, :string # EA's per-placement DUID for connector resolution
+      # UMLDI keyword text EA emitted for this shape (e.g. "Type",
+      # "FeatureType"). When present, this is the authoritative
+      # label EA rendered in the SVG header — the source XMI is
+      # canonical. Falls back to the classifier's stereotype when
+      # absent (basic.qea has no UMLDI metadata).
+      attribute :umldi_keyword, :string
 
       json do
         map "id", to: :id
         map "diagramId", to: :diagram_id
         map "modelElementRef", to: :model_element_ref
         map "bounds", to: :bounds
+        map "imageBounds", to: :image_bounds
         map "style", to: :style
+        map "backgroundColor", to: :background_color
+        map "lineColor", to: :line_color
+        map "lineWidth", to: :line_width
+        map "fontFamily", to: :font_family
+        map "fontSize", to: :font_size
+        map "fontBold", to: :font_bold, render_default: true
+        map "fontItalic", to: :font_italic, render_default: true
+        map "fontUnderline", to: :font_underline, render_default: true
+        map "showTaggedValues", to: :show_tagged_values, render_default: true
+        map "iconVisibility", to: :icon_visibility
+        map "zOrder", to: :z_order
+        map "duid", to: :duid
+        map "umldiKeyword", to: :umldi_keyword
       end
     end
   end

data/lib/ea/model/document.rb

@@ -13,7 +13,8 @@ module Ea
         "data_type" => "Ea::Model::DataType",
         "primitive_type" => "Ea::Model::PrimitiveType",
         "enumeration" => "Ea::Model::Enumeration",
-        "interface" => "Ea::Model::Interface"
+        "interface" => "Ea::Model::Interface",
+        "signal" => "Ea::Model::Signal"
       }
     }.freeze
 
@@ -43,18 +44,31 @@ module Ea
       attribute :relationships, Relationship, collection: true, initialize_empty: true,
                                               polymorphic: RELATIONSHIP_POLYMORPHIC_MAP
       attribute :stereotypes, Stereotype, collection: true, initialize_empty: true
+      attribute :notes, Note, collection: true, initialize_empty: true
+      attribute :instance_specifications, InstanceSpecification, collection: true,
+                                          initialize_empty: true
       attribute :diagrams, Diagram, collection: true, initialize_empty: true
 
       # Flat lookup indexes, built lazily by consumers. Not
       # serialized — they're derived from the element collections.
+      #
+      # EA XMI stores packages with `EAPK_<guid>` ids inside the
+      # uml:Model hierarchy, but diagram element `subject=` refs use
+      # `EAID_<guid>`. We alias packages under both prefixes so
+      # `model_element_ref` lookups from diagram elements resolve.
       def index_by_id
         @index_by_id ||= begin
           idx = {}
-          packages.each { |p| idx[p.id] = p }
+          packages.each do |p|
+            idx[p.id] = p
+            alias_eaid_for_package(idx, p)
+          end
           classifiers.each { |c| idx[c.id] = c }
           relationships.each { |r| idx[r.id] = r }
           stereotypes.each { |s| idx[s.id] = s }
+          instance_specifications.each { |i| idx[i.id] = i }
           diagrams.each { |d| idx[d.id] = d }
+          notes.each { |n| idx[n.id] = n }
           diagrams.each do |d|
             d.elements.each { |e| idx[e.id] = e }
             d.connectors.each { |c| idx[c.id] = c }
@@ -63,6 +77,33 @@ module Ea
         end
       end
 
+      # Flat lookup of Properties by id across all classifiers. Built
+      # lazily; not serialized. Used by connector label rendering to
+      # resolve association-end properties in O(1) rather than
+      # walking every classifier's property list per lookup.
+      def property_index
+        @property_index ||= begin
+          idx = {}
+          classifiers.each do |cls|
+            (cls.properties || []).each { |p| idx[p.id] = p }
+          end
+          idx
+        end
+      end
+
+      # O(1) Property lookup by id. Returns nil when not found.
+      def property_by_id(id)
+        return nil unless id
+
+        property_index[id]
+      end
+
+      def alias_eaid_for_package(idx, package)
+        return unless package.id&.start_with?("EAPK_")
+
+        idx["EAID_#{package.id[5..]}"] = package
+      end
+
       def root_packages
         packages.select { |p| p.parent_id.nil? }
       end
@@ -90,6 +131,7 @@ module Ea
 
       def reset_indexes
         @index_by_id = nil
+        @property_index = nil
       end
 
       json do
@@ -100,6 +142,9 @@ module Ea
         map "relationships", to: :relationships, render_empty: true,
                              polymorphic: RELATIONSHIP_POLYMORPHIC_MAP
         map "stereotypes", to: :stereotypes, render_empty: true
+        map "notes", to: :notes, render_empty: true
+        map "instanceSpecifications", to: :instance_specifications,
+            render_empty: true
         map "diagrams", to: :diagrams, render_empty: true
       end
     end

data/lib/ea/model/ghost_label.rb

@@ -0,0 +1,32 @@
+# frozen_string: true
+
+module Ea
+  module Model
+    # A "ghost" classifier name rendered near a connector endpoint
+    # that references a classifier NOT placed on the current diagram.
+    # EA shows the name as italic text at the connector's off-canvas
+    # end so the reader knows what the connector attaches to.
+    #
+    # Carries:
+    #   - name: the classifier's display name (simple or qualified)
+    #   - end_kind: :source or :target (which end is ghost)
+    #   - anchor: [x, y] canvas-space coordinates of the label
+    #
+    # Multiple connectors can reference the same ghost classifier;
+    # each produces its own GhostLabel at its own anchor.
+    class GhostLabel < Base
+      attribute :name, :string
+      attribute :end_kind, :string
+      attribute :anchor_x, :integer
+      attribute :anchor_y, :integer
+
+      json do
+        map "id", to: :id
+        map "name", to: :name
+        map "endKind", to: :end_kind
+        map "anchorX", to: :anchor_x
+        map "anchorY", to: :anchor_y
+      end
+    end
+  end
+end

data/lib/ea/model/instance_specification.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ea
+  module Model
+    # A UML InstanceSpecification — an instance of a Classifier shown
+    # on an Object diagram. Carries a name, a reference to the
+    # classifier it instantiates, and a list of Slots (variable =
+    # value pairs parsed from EA's RunState field).
+    class InstanceSpecification < Base
+      attribute :name, :string
+      attribute :classifier_id, :string
+      attribute :classifier_name, :string
+      attribute :package_id, :string
+      attribute :package_name, :string
+      attribute :qualified_name, :string
+      attribute :slots, Slot, collection: true, initialize_empty: true
+      attribute :role_name, :string
+      attribute :annotations, Annotation, collection: true, initialize_empty: true
+
+      json do
+        map "id", to: :id
+        map "name", to: :name
+        map "classifierId", to: :classifier_id
+        map "classifierName", to: :classifier_name
+        map "packageId", to: :package_id
+        map "packageName", to: :package_name
+        map "qualifiedName", to: :qualified_name
+        map "slots", to: :slots, render_empty: true
+        map "roleName", to: :role_name
+        map "annotations", to: :annotations, render_empty: true
+      end
+    end
+  end
+end

data/lib/ea/model/legend.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ea
+  module Model
+    # An auto-generated legend block. EA emits these from a
+    # `t_object` row of Object_Type="Text" whose StyleEx carries
+    # `LegendOpts=...`. The visible block — title, colored icon
+    # rects, and per-item labels — is configured by a sibling
+    # `t_xref` row of name="CustomProperties" on the same GUID.
+    #
+    # Colors are stored as EA's BGR-packed integers (same encoding
+    # as t_object.BCol). Convert to "#RRGGBB" at render time via
+    # Ea::Svg::EaEmitter::Element::BColDecoder.
+    class Legend < Base
+      DEFAULT_TITLE = "凡例"
+      DEFAULT_HEADING_SIZE = 12
+      DEFAULT_ITEM_SIZE = 9
+      DEFAULT_FONT_COLOR = 0x603000     # BGR for #003060
+      DEFAULT_BACKGROUND_COLOR = 0xF0F0F0 # BGR for #F0F0F0
+      DEFAULT_BORDER_COLOR = 0xD7D7D7     # BGR for #D7D7D7
+
+      attribute :title, :string, default: -> { DEFAULT_TITLE }
+      attribute :heading_size, :integer
+      attribute :font_color, :integer, default: -> { DEFAULT_FONT_COLOR }
+      attribute :background_color, :integer, default: -> { DEFAULT_BACKGROUND_COLOR }
+      attribute :border_color, :integer, default: -> { DEFAULT_BORDER_COLOR }
+      attribute :background_is_default, :boolean, default: -> { true }
+      attribute :items, LegendItem, collection: true, initialize_empty: true
+
+      json do
+        map "id", to: :id
+        map "name", to: :name
+        map "title", to: :title
+        map "headingSize", to: :heading_size
+        map "fontColor", to: :font_color
+        map "backgroundColor", to: :background_color
+        map "borderColor", to: :border_color
+        map "backgroundIsDefault", to: :background_is_default
+        map "items", to: :items, render_empty: true
+      end
+    end
+  end
+end

data/lib/ea/model/legend_item.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ea
+  module Model
+    # One item in an auto-generated legend block: a colored icon
+    # paired with a label string. The background_color is the icon's
+    # fill, encoded as EA's BGR-packed integer (same encoding as
+    # t_object.BCol). sort_index is the 0-based display order.
+    class LegendItem < Base
+      attribute :name, :string
+      attribute :background_color, :integer
+      attribute :pen_color, :integer, default: -> { 0 }
+      attribute :pen_size, :integer, default: -> { 1 }
+      attribute :sort_index, :integer, default: -> { 0 }
+
+      json do
+        map "id", to: :id
+        map "name", to: :name
+        map "backgroundColor", to: :background_color
+        map "penColor", to: :pen_color
+        map "penSize", to: :pen_size
+        map "sortIndex", to: :sort_index
+      end
+    end
+  end
+end