diagram 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ef3c343a2636e4f7ffda61678ff784b5d0b083d25ab83364e0285cb5c150acd
-  data.tar.gz: 9988256feb04b4eee350d792cc697cdb3bee87371a0211f5f714a4f1c380d2e8
+  metadata.gz: b4af5a1be5db0b92fbdd6a3c6d41eec3d78dd3bd36c6ba6bb70897f552bfdf27
+  data.tar.gz: 967838b7e5d58ee6ffa188cfc623a130fdb0223e586118c3e11ea1c66fff16cc
 SHA512:
-  metadata.gz: b9bf6af4e963b22981ce1eec3205e1d35e3a25752183fc2b91b1650148e3eb08f738522535b6234eca33cab21be7070132f8f41f4dff9663fa35bff8cf1d742d
-  data.tar.gz: 4ce8d1844a7bd0c961a89ed838d3541cbf10a9794f897622aea05f81b654937acc9054c7a09a114d625e22bfe12af524ea7832e3a20a1f40f0ca1e9c39548fb1
+  metadata.gz: 90b0513c6e57596f3c769f01a693b1615cbd9044f8dfc2d97a17432073b9f5415b23b0724c91f121219b767f892d4977eac598e33159d4ca83cd892bf00235f3
+  data.tar.gz: 1dac456dbecc729f32da2a863bd0605e9ee4b830982920b56c54b68dae4ce27ad635e0ad68bd6fc5029838a5f994553da9592dd09390301f465b1f4ceea09ca9

data/lib/diagrams/base.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'dry-equalizer'
+
+module Diagrams
+  # Abstract base class for all diagram types.
+  # Provides common functionality like versioning, checksum calculation,
+  # serialization, and equality comparison.
+  class Base
+    # Provides `==`, `eql?`, and `hash` methods based on specified attributes.
+    # Diagrams are equal if they are of the same class and have the same content (checksum).
+    include Dry::Equalizer(:class, :checksum)
+
+    attr_reader :version, :checksum
+
+    # Initializes the base diagram attributes.
+    # Subclasses should call super.
+    #
+    # @param version [String, Integer, nil] User-defined version identifier. Defaults to 1.
+    def initialize(version: 1)
+      # Prevent direct instantiation of the base class
+      raise NotImplementedError, 'Cannot instantiate abstract class Diagrams::Base' if instance_of?(Diagrams::Base)
+
+      @version = version
+      @checksum = nil # Will be calculated by subclasses via #update_checksum! after content is set
+    end
+
+    # Abstract method: Subclasses must implement this to return a hash
+    # representing their specific content, suitable for serialization.
+    #
+    # @return [Hash]
+    def to_h_content
+      raise NotImplementedError, "#{self.class.name} must implement #to_h_content"
+    end
+
+    # Abstract method: Subclasses must implement this to return a hash
+    # mapping element type symbols (e.g., :nodes, :edges) to arrays
+    # of the corresponding element objects within the diagram.
+    # Used for comparison and diffing.
+    #
+    # @return [Hash{Symbol => Array<Diagrams::Elements::*>}]
+    def identifiable_elements
+      raise NotImplementedError, "#{self.class.name} must implement #identifiable_elements"
+    end
+
+    # Performs a basic diff against another diagram object.
+    # Only compares diagrams of the same type.
+    # Identifies added and removed elements based on common identifiers (id/name) or object equality.
+    # Does NOT currently detect modified elements.
+    #
+    # @param other [Diagrams::Base] The diagram to compare against.
+    # @return [Hash{Symbol => Hash{Symbol => Array<Diagrams::Elements::*>}}] A hash describing differences,
+    #   e.g., { nodes: { added: [...], removed: [...] }, edges: { added: [...], removed: [...] } }
+    #   Returns an empty hash if diagrams are identical or of different types.
+    def diff(other)
+      diff_result = {}
+      return diff_result unless other.is_a?(self.class) # Only compare same types
+      return diff_result if self == other # Use existing equality check for quick exit
+
+      self_elements = identifiable_elements
+      other_elements = other.identifiable_elements
+
+      # Ensure both diagrams define the same element types for comparison
+      element_types = self_elements.keys & other_elements.keys
+
+      element_types.each do |type|
+        self_collection = self_elements[type] || []
+        other_collection = other_elements[type] || []
+
+        # Determine identifier method (prefer id, then name, fallback to object itself)
+        identifier_method = if self_collection.first.respond_to?(:id)
+                              :id
+                            elsif self_collection.first.respond_to?(:name)
+                              :name
+                            elsif self_collection.first.respond_to?(:label) # For Slice
+                              :label
+                            else
+                              :itself # Fallback to object identity/equality
+                            end
+
+        self_ids = self_collection.map(&identifier_method)
+        other_ids = other_collection.map(&identifier_method)
+
+        added_ids = other_ids - self_ids
+        removed_ids = self_ids - other_ids
+
+        added_elements = other_collection.select { |el| added_ids.include?(el.send(identifier_method)) }
+        removed_elements = self_collection.select { |el| removed_ids.include?(el.send(identifier_method)) }
+
+        # Basic check for modified elements (same ID, different content via checksum/hash if available, or simple !=)
+        # This is a very basic modification check
+        potential_modified_ids = self_ids & other_ids
+        modified_elements = []
+        potential_modified_ids.each do |id|
+          self_el = self_collection.find { |el| el.send(identifier_method) == id }
+          other_el = other_collection.find { |el| el.send(identifier_method) == id }
+          # Use Dry::Struct equality if available, otherwise basic !=
+          next unless self_el != other_el
+
+          modified_elements << { old: self_el, new: other_el }
+          # Remove from added/removed if detected as modified
+          added_elements.delete(other_el)
+          removed_elements.delete(self_el)
+        end
+
+        type_diff = {}
+        type_diff[:added] = added_elements if added_elements.any?
+        type_diff[:removed] = removed_elements if removed_elements.any?
+        type_diff[:modified] = modified_elements if modified_elements.any? # Add modified info
+
+        diff_result[type] = type_diff if type_diff.any?
+      end
+
+      diff_result
+    end
+
+    # Returns a hash representation of the diagram, suitable for serialization.
+    # Includes common metadata and calls `#to_h_content` for specific data.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        # Extract class name without module prefix (e.g., "FlowchartDiagram")
+        # Convert class name to snake_case (e.g., FlowchartDiagram -> flowchart_diagram)
+        type: camel_to_snake_case(self.class.name.split('::').last),
+        version: @version,
+        checksum: @checksum, # Ensure checksum is up-to-date before calling
+        data: to_h_content
+      }
+    end
+
+    # Returns a JSON string representation of the diagram.
+    # Delegates to `#to_h` and uses `JSON.generate`.
+    # Accepts any arguments valid for `JSON.generate`.
+    #
+    # @param _args Any arguments accepted by `JSON.generate` (ignored by method signature but passed along).
+    # @return [String]
+    def to_json(*)
+      JSON.generate(to_h, *)
+    end
+
+    # --- Class methods for Deserialization ---
+
+    class << self
+      # Deserializes a diagram from a hash representation.
+      # Acts as a factory, dispatching to the appropriate subclass based on the 'type' field.
+      #
+      # @param hash [Hash] The hash representation (typically from parsed JSON).
+      # @return [Diagrams::Base] An instance of the specific diagram subclass.
+      # @raise [ArgumentError] if the hash is missing the 'type' key.
+      # @raise [NameError] if the type string doesn't correspond to a known Diagram class.
+      # @raise [TypeError] if the resolved class is not a subclass of Diagrams::Base.
+      def from_hash(hash)
+        # Ensure keys are symbols for consistent access
+        symbolized_hash = hash.transform_keys(&:to_sym)
+
+        type_string = symbolized_hash[:type]
+        raise ArgumentError, "Input hash must include a 'type' key." unless type_string
+
+        data_hash = symbolized_hash[:data] || {}
+        version = symbolized_hash[:version]
+        checksum = symbolized_hash[:checksum] # Pass checksum for potential verification
+
+        begin
+          # Convert snake_case type string back to CamelCase class name part
+          camel_case_type = snake_to_camel_case(type_string)
+          # Construct full class name (e.g., "Diagrams::FlowchartDiagram")
+          klass_name = "Diagrams::#{camel_case_type}"
+          klass = Object.const_get(klass_name)
+        rescue NameError
+          raise NameError, "Unknown diagram type '#{type_string}' corresponding to class '#{klass_name}'"
+        end
+
+        # Ensure the resolved class is actually a diagram type
+        raise TypeError, "'#{klass_name}' is not a valid subclass of Diagrams::Base" unless klass < Diagrams::Base
+
+        # Delegate to the specific subclass's from_h method
+        # Each subclass must implement `from_h(data_hash, version:, checksum:)`
+        klass.from_h(data_hash, version:, checksum:)
+      end
+
+      # Deserializes a diagram from a JSON string.
+      # Parses the JSON and delegates to `.from_hash`.
+      #
+      # @param json_string [String] The JSON representation of the diagram.
+      # @return [Diagrams::Base] An instance of the specific diagram subclass.
+      def from_json(json_string)
+        hash = JSON.parse(json_string)
+        from_hash(hash)
+      rescue JSON::ParserError => e
+        raise JSON::ParserError, "Failed to parse JSON: #{e.message}"
+      end
+
+      private # Make helper private to the class methods
+
+      # Simple helper to convert snake_case to CamelCase
+      # (Avoids ActiveSupport dependency)
+      def snake_to_camel_case(string)
+        string.split('_').collect(&:capitalize).join
+      end
+    end
+
+    # --- End Deserialization Methods ---
+
+    protected
+
+    # Recalculates the diagram's checksum based on its current content
+    # and updates the @checksum instance variable.
+    # Subclasses should call this after initialization and any mutation.
+    def update_checksum!
+      @checksum = compute_checksum
+    end
+
+    # Simple helper to convert CamelCase to snake_case
+    # (Avoids ActiveSupport dependency)
+    def camel_to_snake_case(string)
+      string.gsub('::', '/')
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_')
+            .downcase
+    end
+
+    # Computes the SHA256 checksum of the diagram's content.
+    # The content is obtained from `#to_h_content` and serialized to JSON
+    # to ensure a consistent representation for hashing.
+    #
+    # @return [String] The hex digest of the checksum.
+    def compute_checksum
+      # Ensure content is available before computing checksum
+      content_hash = respond_to?(:to_h_content, true) ? to_h_content : {}
+      # Generate JSON. Sorting keys isn't strictly necessary for SHA256
+      # but can help if comparing JSON strings directly elsewhere.
+      # For checksum purposes, consistency is key, which JSON.generate provides.
+      content_json = JSON.generate(content_hash || {}) # Handle potential nil from to_h_content
+      Digest::SHA256.hexdigest(content_json)
+    end
+  end
+
+  ## Errors (Kept from original file)
+  class ValidationError < StandardError; end
+  class EmptyDiagramError < ValidationError; end
+  class DuplicateLabelError < ValidationError; end
+end

data/lib/diagrams/class_diagram.rb

@@ -1,7 +1,132 @@
 # frozen_string_literal: true
 
+require_relative 'base'
+require_relative 'elements/class_entity'
+require_relative 'elements/relationship'
+
 module Diagrams
-  class ClassDiagram < AbstractDiagram
-    attribute :classes, ClassDiagram::Types::Array.of(Class)
+  # Represents a UML Class Diagram consisting of classes and relationships between them.
+  class ClassDiagram < Base
+    attr_reader :classes, :relationships
+
+    # Initializes a new ClassDiagram.
+    #
+    # @param classes [Array<Element::ClassEntity>] An array of class entity objects.
+    # @param relationships [Array<Element::Relationship>] An array of relationship objects.
+    # @param version [String, Integer, nil] User-defined version identifier.
+    def initialize(classes: [], relationships: [], version: 1)
+      super(version:)
+      @classes = classes.is_a?(Array) ? classes : []
+      @relationships = relationships.is_a?(Array) ? relationships : []
+      validate_elements!
+      update_checksum!
+    end
+
+    # Adds a class entity to the diagram.
+    #
+    # @param class_entity [Element::ClassEntity] The class entity object to add.
+    # @raise [ArgumentError] if a class with the same name already exists.
+    # @return [Element::ClassEntity] The added class entity.
+    def add_class(class_entity)
+      unless class_entity.is_a?(Diagrams::Elements::ClassEntity)
+        raise ArgumentError,
+              'Class entity must be a Diagrams::Elements::ClassEntity'
+      end
+      raise ArgumentError, "Class with name '#{class_entity.name}' already exists" if find_class(class_entity.name)
+
+      @classes << class_entity
+      update_checksum!
+      class_entity
+    end
+
+    # Adds a relationship to the diagram.
+    #
+    # @param relationship [Element::Relationship] The relationship object to add.
+    # @raise [ArgumentError] if the relationship refers to non-existent class names.
+    # @return [Element::Relationship] The added relationship.
+    def add_relationship(relationship)
+      unless relationship.is_a?(Diagrams::Elements::Relationship)
+        raise ArgumentError,
+              'Relationship must be a Diagrams::Elements::Relationship'
+      end
+      unless find_class(relationship.source_class_name) && find_class(relationship.target_class_name)
+        raise ArgumentError,
+              "Relationship refers to non-existent class names ('#{relationship.source_class_name}' or '#{relationship.target_class_name}')"
+      end
+
+      @relationships << relationship
+      update_checksum!
+      relationship
+    end
+
+    # Finds a class entity by its name.
+    #
+    # @param class_name [String] The name of the class to find.
+    # @return [Element::ClassEntity, nil] The found class entity or nil.
+    def find_class(class_name)
+      @classes.find { |c| c.name == class_name }
+    end
+
+    # Returns the specific content of the class diagram as a hash.
+    # Called by `Diagrams::Base#to_h`.
+    #
+    # @return [Hash{Symbol => Array<Hash>}]
+    def to_h_content
+      {
+        classes: @classes.map(&:to_h),
+        relationships: @relationships.map(&:to_h)
+      }
+    end
+
+    # Returns a hash mapping element types to their collections for diffing.
+    # @see Diagrams::Base#identifiable_elements
+    # @return [Hash{Symbol => Array<Diagrams::Elements::ClassEntity | Diagrams::Elements::Relationship>}]
+    def identifiable_elements
+      {
+        classes: @classes,
+        relationships: @relationships
+      }
+    end
+
+    # Class method to create a ClassDiagram from a hash.
+    # Used by the deserialization factory in `Diagrams::Base`.
+    #
+    # @param data_hash [Hash] Hash containing `:classes` and `:relationships` arrays.
+    # @param version [String, Integer, nil] Diagram version.
+    # @param checksum [String, nil] Expected checksum (optional, for verification).
+    # @return [ClassDiagram] The instantiated diagram.
+    def self.from_h(data_hash, version:, checksum:)
+      classes_data = data_hash[:classes] || data_hash['classes'] || []
+      relationships_data = data_hash[:relationships] || data_hash['relationships'] || []
+
+      classes = classes_data.map { |class_h| Diagrams::Elements::ClassEntity.new(class_h.transform_keys(&:to_sym)) }
+      relationships = relationships_data.map do |rel_h|
+        Diagrams::Elements::Relationship.new(rel_h.transform_keys(&:to_sym))
+      end
+
+      diagram = new(classes:, relationships:, version:)
+
+      if checksum && diagram.checksum != checksum
+        warn "Checksum mismatch for loaded ClassDiagram (version: #{version}). Expected #{checksum}, got #{diagram.checksum}."
+        # Or raise an error: raise "Checksum mismatch..."
+      end
+
+      diagram
+    end
+
+    private
+
+    # Validates the consistency of classes and relationships during initialization.
+    def validate_elements!
+      class_names = @classes.map(&:name)
+      raise ArgumentError, 'Duplicate class names found' unless class_names.uniq.size == @classes.size
+
+      @relationships.each do |rel|
+        unless class_names.include?(rel.source_class_name) && class_names.include?(rel.target_class_name)
+          raise ArgumentError,
+                "Relationship refers to non-existent class names ('#{rel.source_class_name}' or '#{rel.target_class_name}')"
+        end
+      end
+    end
   end
 end

data/lib/diagrams/elements/class_entity.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require_relative 'node' # Load Types module defined in node.rb
+
+module Diagrams
+
+  module Elements
+    # Represents a class entity in a UML Class Diagram.
+    class ClassEntity < Dry::Struct
+      # Use the shared Types module
+      include Elements::Types
+
+      # Name of the class
+      attribute :name, Types::Strict::String.constrained(min_size: 1)
+
+      # List of attributes (e.g., "id: Integer", "name: String")
+      attribute :attributes, Types::Strict::Array.of(Types::Strict::String).default([].freeze)
+
+      # List of methods (e.g., "save()", "find(id: Integer)")
+      attribute :methods, Types::Strict::Array.of(Types::Strict::String).default([].freeze)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Array<String>}]
+    end
+  end
+end

data/lib/diagrams/elements/edge.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require_relative 'node' # Load Types module defined in node.rb
+
+module Diagrams
+
+  module Elements
+    # Represents an edge or link between two nodes in a diagram.
+    # Typically connects nodes via their IDs and can have an optional label.
+    class Edge < Dry::Struct
+      # Use the shared Types module defined in node.rb (or a dedicated types file)
+      include Elements::Types
+
+      # Consider if an edge needs its own ID, or if source/target/label is sufficient identity.
+      # attribute :id, Types::Strict::String
+
+      attribute :source_id, Types::Strict::String.constrained(min_size: 1)
+      attribute :target_id, Types::Strict::String.constrained(min_size: 1)
+      attribute :label, Types::Strict::String.optional.default(nil)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | nil}]
+      def to_h
+        # Rely on Dry::Struct's default to_h, which includes all attributes.
+        # Filter out nil label if desired.
+        super.compact
+      end
+    end
+  end
+end

data/lib/diagrams/elements/event.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require_relative 'node' # Load Types module defined in node.rb
+
+module Diagrams
+
+  module Elements
+    # Represents an event, potentially used in State Diagrams or others.
+    class Event < Dry::Struct
+      # Use the shared Types module
+      include Elements::Types
+
+      attribute :id, Types::Strict::String.constrained(min_size: 1)
+      attribute :label, Types::Strict::String.optional.default(nil)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | nil}]
+      def to_h
+        # Rely on Dry::Struct's default to_h, filtering out nil label.
+        super.compact
+      end
+    end
+  end
+end

data/lib/diagrams/elements/node.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require 'dry-types'
+
+module Diagrams
+  # Namespace for diagram element value objects.
+
+  module Elements
+    # Common Dry::Types definitions for elements.
+    module Types
+      include Dry.Types()
+    end
+
+    # Represents a node in various diagram types (e.g., Flowchart).
+    # Typically has an identifier and a display label.
+    class Node < Dry::Struct
+      # Use the shared Types module
+      include Elements::Types
+
+      attribute :id, Types::Strict::String.constrained(min_size: 1)
+      attribute :label, Types::Strict::String.constrained(min_size: 1)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String}]
+      def to_h
+        {
+          id:,
+          label:
+        }
+        # Dry::Struct automatically provides a to_h method,
+        # but defining it explicitly ensures the desired structure.
+        # super # Alternatively, call super if the default is sufficient.
+      end
+    end
+  end
+end

data/lib/diagrams/elements/relationship.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require_relative 'node' # Load Types module defined in node.rb
+
+module Diagrams
+
+  module Elements
+    # Represents a relationship (e.g., association, inheritance) between two classes
+    # in a UML Class Diagram.
+    class Relationship < Dry::Struct
+      # Use the shared Types module
+      include Elements::Types
+
+      # Name of the source class
+      attribute :source_class_name, Types::Strict::String.constrained(min_size: 1)
+
+      # Name of the target class
+      attribute :target_class_name, Types::Strict::String.constrained(min_size: 1)
+
+      # Type of relationship (e.g., "association", "inheritance", "composition")
+      # Consider using a constrained string or enum type later if needed.
+      attribute :type, Types::Strict::String.constrained(min_size: 1)
+
+      # Optional label for the relationship (e.g., multiplicity, role name)
+      attribute :label, Types::Strict::String.optional.default(nil)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | nil}]
+      def to_h
+        # Rely on Dry::Struct's default to_h, filtering out nil label.
+        super.compact
+      end
+    end
+  end
+end

data/lib/diagrams/elements/slice.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require_relative 'node' # Load Types module defined in node.rb
+
+module Diagrams
+
+  module Elements
+    # Represents a slice in a Pie Diagram.
+    class Slice < Dry::Struct
+      # Use the shared Types module
+      include Elements::Types
+
+      attribute :label, Types::Strict::String.constrained(min_size: 1)
+      # Represents the raw value of the slice (not percentage)
+      attribute :value, Types::Coercible::Float.constrained(gteq: 0)
+      # Calculated percentage (read-only)
+      attribute :percentage, Types::Strict::Float.optional.default(nil).meta(reader: true)
+      # Consider adding optional color attribute later.
+      # attribute :color, Types::Strict::String.optional.default(nil)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Float | nil}]
+    end
+  end
+end

data/lib/diagrams/elements/state.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require_relative 'node' # Load Types module defined in node.rb
+
+module Diagrams
+
+  module Elements
+    # Represents a state in a State Diagram.
+    class State < Dry::Struct
+      # Use the shared Types module
+      include Elements::Types
+
+      attribute :id, Types::Strict::String.constrained(min_size: 1)
+      attribute :label, Types::Strict::String.optional.default(nil)
+      # TODO: Consider adding back type attribute (e.g., start, end, state)
+      # attribute :type, Types::Strict::String.enum('state', 'start', 'end', 'fork', 'join').default('state')
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | nil}]
+      def to_h
+        # Rely on Dry::Struct's default to_h, filtering out nil label.
+        super.compact
+      end
+    end
+  end
+end

data/lib/diagrams/elements/task.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require_relative 'node' # Load Types module defined in node.rb
+
+module Diagrams
+
+  module Elements
+    # Represents a task in a Gantt Diagram.
+    class Task < Dry::Struct
+      # Use the shared Types module
+      include Elements::Types
+
+      attribute :id, Types::Strict::String.constrained(min_size: 1)
+      attribute :name, Types::Strict::String.constrained(min_size: 1)
+      # Using String for dates initially for simplicity.
+      # Consider Types::Strict::Date or custom coercible types later.
+      attribute :start_date, Types::Strict::String.constrained(min_size: 1) # Basic check
+      attribute :end_date, Types::Strict::String.constrained(min_size: 1)   # Basic check
+      # TODO: Add dependencies attribute (e.g., Types::Strict::Array.of(Types::Strict::String))
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String}]
+    end
+  end
+end

data/lib/diagrams/elements/transition.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'dry-struct'
+require_relative 'node' # Load Types module defined in node.rb
+
+module Diagrams
+
+  module Elements
+    # Represents a transition between two states in a State Diagram.
+    class Transition < Dry::Struct
+      # Use the shared Types module
+      include Elements::Types
+
+      # Consider if a transition needs its own ID.
+      # attribute :id, Types::Strict::String
+
+      attribute :source_state_id, Types::Strict::String.constrained(min_size: 1)
+      attribute :target_state_id, Types::Strict::String.constrained(min_size: 1)
+      # Label often represents the event or condition triggering the transition.
+      attribute :label, Types::Strict::String.optional.default(nil)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | nil}]
+      def to_h
+        # Rely on Dry::Struct's default to_h, filtering out nil label.
+        super.compact
+      end
+    end
+  end
+end