diagram 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4af5a1be5db0b92fbdd6a3c6d41eec3d78dd3bd36c6ba6bb70897f552bfdf27
-  data.tar.gz: 967838b7e5d58ee6ffa188cfc623a130fdb0223e586118c3e11ea1c66fff16cc
+  metadata.gz: b6a7329e68d37cab7fe076fb763b56fddff42b23e81619bd70f3a89ef82ebff8
+  data.tar.gz: 3eac3513c7ebb76307967f12f3c9d189e35022203ce817e3fbc90be310ac7b10
 SHA512:
-  metadata.gz: 90b0513c6e57596f3c769f01a693b1615cbd9044f8dfc2d97a17432073b9f5415b23b0724c91f121219b767f892d4977eac598e33159d4ca83cd892bf00235f3
-  data.tar.gz: 1dac456dbecc729f32da2a863bd0605e9ee4b830982920b56c54b68dae4ce27ad635e0ad68bd6fc5029838a5f994553da9592dd09390301f465b1f4ceea09ca9
+  metadata.gz: 0b59a02a496318c080f8ff72bbfb6bb224ae4dfeb3657eda3e262ac401cca6871f8a18a487fbe012699c7016ae8ef07cfc565f224e7697cc3a6aba9abb60907b
+  data.tar.gz: 6cee2aa87b44ae4aab58a99fcf9cfadfbde2f9496523d7e02e5dcb00f6c4ec14abce8b36ff79c1b276e44eec407fe09db6dcaabd9a14c83a050b7684df854f41

data/lib/diagram.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'diagrams'

data/lib/diagrams/base.rb

@@ -1,9 +1,5 @@
 # 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,
@@ -69,12 +65,14 @@ module Diagrams
         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)
+        # Determine identifier method (prefer id, then name, then title, then label, fallback to object itself)
+        identifier_method = if self_collection.first&.respond_to?(:id)
                               :id
-                            elsif self_collection.first.respond_to?(:name)
+                            elsif self_collection.first&.respond_to?(:name)
                               :name
-                            elsif self_collection.first.respond_to?(:label) # For Slice
+                            elsif self_collection.first&.respond_to?(:title) # For TimelineSection
+                              :title
+                            elsif self_collection.first&.respond_to?(:label) # For Slice, TimelinePeriod
                               :label
                             else
                               :itself # Fallback to object identity/equality

data/lib/diagrams/class_diagram.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-require_relative 'elements/class_entity'
-require_relative 'elements/relationship'
-
 module Diagrams
   # Represents a UML Class Diagram consisting of classes and relationships between them.
   class ClassDiagram < Base

data/lib/diagrams/elements/class_entity.rb

@@ -1,10 +1,6 @@
 # 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

data/lib/diagrams/elements/edge.rb

@@ -1,10 +1,6 @@
 # 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.

data/lib/diagrams/elements/event.rb

@@ -1,10 +1,6 @@
 # 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

data/lib/diagrams/elements/git_branch.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a branch in a Gitgraph diagram.
+    class GitBranch < Dry::Struct
+      include Elements::Types
+
+      attribute :name, Types::Strict::String.constrained(min_size: 1)
+      # head_commit_id can be nil initially if the branch is created before any commits
+      attribute :head_commit_id, Types::Strict::String.optional.default(nil)
+      attribute :start_commit_id, Types::Strict::String.constrained(min_size: 1)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String}]
+      def to_h
+        hash = {
+          name:,
+          start_commit_id:
+        }
+        hash[:head_commit_id] = head_commit_id if head_commit_id
+        hash
+      end
+    end
+  end
+end

data/lib/diagrams/elements/git_commit.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a commit in a Gitgraph diagram.
+    class GitCommit < Dry::Struct
+      include Elements::Types
+
+      attribute :id, Types::Strict::String.constrained(min_size: 1)
+      attribute :parent_ids, Types::Strict::Array.of(Types::Strict::String).default([].freeze)
+      attribute :branch_name, Types::Strict::String.constrained(min_size: 1)
+      attribute :message, Types::Strict::String.optional.default(nil)
+      attribute :tag, Types::Strict::String.optional.default(nil)
+      attribute :type, Types::Strict::Symbol.default(:NORMAL).enum(:NORMAL, :REVERSE, :HIGHLIGHT, :MERGE, :CHERRY_PICK)
+      attribute :cherry_pick_source_id, Types::Strict::String.optional.default(nil)
+
+      # Returns a hash representation suitable for serialization.
+      # Dry::Struct provides to_h, but explicit definition ensures desired keys/structure.
+      # Optional attributes are included only if they have non-nil values.
+      #
+      # @return [Hash{Symbol => String | Array<String> | Symbol}]
+      def to_h
+        hash = {
+          id:,
+          parent_ids:,
+          branch_name:,
+          type:
+        }
+        hash[:message] = message if message
+        hash[:tag] = tag if tag
+        hash[:cherry_pick_source_id] = cherry_pick_source_id if cherry_pick_source_id
+        hash
+      end
+    end
+  end
+end

data/lib/diagrams/elements/node.rb

@@ -1,17 +1,9 @@
 # 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

data/lib/diagrams/elements/relationship.rb

@@ -1,10 +1,6 @@
 # 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.

data/lib/diagrams/elements/slice.rb

@@ -1,10 +1,6 @@
 # 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

data/lib/diagrams/elements/state.rb

@@ -1,10 +1,6 @@
 # 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

data/lib/diagrams/elements/task.rb

@@ -1,10 +1,6 @@
 # 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

data/lib/diagrams/elements/timeline_event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a single event description within a timeline period.
+    class TimelineEvent < Dry::Struct
+      include Elements::Types
+
+      attribute :description, Types::Strict::String.constrained(min_size: 1)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String}]
+      def to_h
+        {
+          description:
+        }
+      end
+    end
+  end
+end

data/lib/diagrams/elements/timeline_period.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a specific time period on the timeline, containing one or more events.
+    class TimelinePeriod < Dry::Struct
+      include Elements::Types
+
+      attribute :label, Types::Strict::String.constrained(min_size: 1)
+      attribute :events, Types::Strict::Array.of(TimelineEvent).constrained(min_size: 1)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Array<Hash>}]
+      def to_h
+        {
+          label:,
+          events: events.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/diagrams/elements/timeline_section.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Diagrams
+  module Elements
+    # Represents a section or age within the timeline, grouping multiple time periods.
+    class TimelineSection < Dry::Struct
+      include Elements::Types
+
+      attribute :title, Types::Strict::String.constrained(min_size: 1)
+      attribute :periods, Types::Strict::Array.of(TimelinePeriod).default([].freeze)
+
+      # Returns a hash representation suitable for serialization.
+      #
+      # @return [Hash{Symbol => String | Array<Hash>}]
+      def to_h
+        {
+          title:,
+          periods: periods.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/diagrams/elements/transition.rb

@@ -1,10 +1,6 @@
 # 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

data/lib/diagrams/elements.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Diagrams
+  # Namespace for diagram element value objects.
+
+  module Elements
+    # Common Dry::Types definitions for elements.
+    module Types
+      include Dry.Types()
+    end
+  end
+end

data/lib/diagrams/flowchart_diagram.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-require_relative 'elements/node'
-require_relative 'elements/edge'
-
 module Diagrams
   # Represents a flowchart diagram consisting of nodes and edges connecting them.
   class FlowchartDiagram < Base
@@ -28,7 +24,6 @@ module Diagrams
     # @raise [ArgumentError] if a node with the same ID already exists.
     # @return [Element::Node] The added node.
     def add_node(node)
-
       raise ArgumentError, 'Node must be a Diagrams::Element::Node' unless node.is_a?(Diagrams::Elements::Node)
       raise ArgumentError, "Node with ID '#{node.id}' already exists" if find_node(node.id)
 
@@ -43,7 +38,6 @@ module Diagrams
     # @raise [ArgumentError] if the edge refers to non-existent node IDs.
     # @return [Element::Edge] The added edge.
     def add_edge(edge)
-
       raise ArgumentError, 'Edge must be a Diagrams::Element::Edge' unless edge.is_a?(Diagrams::Elements::Edge)
       unless find_node(edge.source_id) && find_node(edge.target_id)
         raise ArgumentError, "Edge refers to non-existent node IDs ('#{edge.source_id}' or '#{edge.target_id}')"

data/lib/diagrams/gantt_diagram.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-require_relative 'elements/task'
-
 module Diagrams
   # Represents a Gantt Chart diagram consisting of tasks over time.
   class GanttDiagram < Base

data/lib/diagrams/gitgraph_diagram.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+require 'digest' # For generating default commit IDs if needed
+
+module Diagrams
+  # Represents a Gitgraph diagram, tracking commits, branches, and their relationships.
+  class GitgraphDiagram < Base
+    attr_reader :commits, :branches, :commit_order, :current_branch_name
+
+    # Initializes a new GitgraphDiagram.
+    # Starts with a 'master' branch by default.
+    #
+    # @param version [String, Integer, nil] User-defined version identifier.
+    def initialize(version: 1)
+      super
+      @commits = {} # Hash { commit_id => GitCommit }
+      @branches = {} # Hash { branch_name => GitBranch }
+      @commit_order = [] # Array<String> - IDs of commits in order of creation/operation
+      @current_branch_name = 'master'
+
+      # Initialize main branch conceptually. Its start/head commit will be set by the first commit.
+      # We need a placeholder start_commit_id; using a special value or handling nil in GitBranch might be better.
+      # For now, let's use a placeholder that signifies it's the root.
+      # A better approach might be to create the branch *during* the first commit. Let's refine this.
+      # --> Refinement: Don't create the branch object here. Create it during the first 'commit' or 'branch' operation.
+      #                 Initialize @current_branch_name = 'master' conceptually.
+
+      update_checksum! # Initial checksum for an empty graph
+    end
+
+    # --- Git Operations ---
+
+    # Adds a commit to the current branch.
+    # Handles the creation of the initial 'master' branch on the first commit.
+    #
+    # @param id [String, nil] Optional custom ID for the commit. Auto-generated if nil.
+    # @param message [String, nil] Optional commit message.
+    # @param tag [String, nil] Optional tag for the commit.
+    # @param type [Symbol] Type of the commit (:NORMAL, :REVERSE, :HIGHLIGHT).
+    # @raise [ArgumentError] if a commit with the given ID already exists.
+    # @return [Elements::GitCommit] The created commit object.
+    def commit(id: nil, message: nil, tag: nil, type: :NORMAL)
+      parent_id = current_head_commit_id
+      parent_ids = parent_id ? [parent_id] : []
+
+      commit_id = id || generate_commit_id(parent_ids, message)
+      raise ArgumentError, "Commit with ID '#{commit_id}' already exists" if @commits.key?(commit_id)
+
+      # Handle first commit: create the master branch
+      if @commits.empty? && @current_branch_name == 'master' && !@branches.key?('master')
+        # The first commit *is* the starting point of the master branch
+        master_branch = Elements::GitBranch.new(name: 'master', start_commit_id: commit_id, head_commit_id: commit_id)
+        @branches['master'] = master_branch
+      elsif !@branches.key?(@current_branch_name)
+        # This case shouldn't typically happen if branch/checkout is used correctly,
+        # but defensively handle committing to a non-existent branch (other than initial master).
+        raise ArgumentError, "Cannot commit: Branch '#{@current_branch_name}' does not exist."
+      end
+
+      new_commit = Elements::GitCommit.new(
+        id: commit_id,
+        parent_ids:,
+        branch_name: @current_branch_name,
+        message:,
+        tag:,
+        type:
+      )
+
+      @commits[commit_id] = new_commit
+      @commit_order << commit_id
+
+      # Update the head of the current branch
+      current_branch = @branches[@current_branch_name]
+      current_branch.attributes[:head_commit_id] = commit_id # Update using Dry::Struct's way if needed, direct assign might work
+
+      update_checksum!
+      new_commit
+    end
+
+    # Creates a new branch pointing to a specific commit (or the current head)
+    # and switches the current context to the new branch.
+    #
+    # @param name [String] The name for the new branch.
+    # @param start_commit_id [String, nil] Optional ID of the commit where the branch should start.
+    #                                     Defaults to the head commit of the current branch.
+    # @raise [ArgumentError] if the branch name already exists or if trying to branch before any commits exist.
+    # @raise [ArgumentError] if a specified `start_commit_id` does not exist.
+    # @return [Elements::GitBranch] The created branch object.
+    def branch(name:, start_commit_id: nil)
+      raise ArgumentError, "Branch name '#{name}' already exists" if @branches.key?(name)
+
+      effective_start_commit_id = start_commit_id || current_head_commit_id
+
+      # Ensure there's a commit to branch from
+      raise ArgumentError, 'Cannot create a branch before the first commit' unless effective_start_commit_id
+
+      unless @commits.key?(effective_start_commit_id)
+        raise ArgumentError,
+              "Start commit ID '#{effective_start_commit_id}' does not exist"
+      end
+
+      new_branch = Elements::GitBranch.new(
+        name:,
+        # The new branch initially points to the commit it was created from
+        start_commit_id: effective_start_commit_id,
+        head_commit_id: effective_start_commit_id
+      )
+
+      @branches[name] = new_branch
+      @current_branch_name = name # Switch to the new branch
+
+      update_checksum!
+      new_branch
+    end
+
+    # Switches the current context to an existing branch.
+    #
+    # @param name [String] The name of the branch to switch to.
+    # @raise [ArgumentError] if the branch name does not exist.
+    # @return [String] The name of the branch checked out.
+    def checkout(name:)
+      raise ArgumentError, "Branch '#{name}' does not exist. Cannot checkout." unless @branches.key?(name)
+
+      @current_branch_name = name
+      # NOTE: Checkout does not change the diagram structure itself (commits/branches),
+      # so we do NOT update the checksum here.
+      name
+    end
+
+    # Merges the head of a specified branch into the current branch.
+    # Creates a merge commit on the current branch.
+    #
+    # @param from_branch_name [String] The name of the branch to merge from.
+    # @param id [String, nil] Optional custom ID for the merge commit. Auto-generated if nil.
+    # @param tag [String, nil] Optional tag for the merge commit.
+    # @param type [Symbol] Type of the merge commit (defaults to :MERGE, can be overridden e.g., :REVERSE).
+    # @raise [ArgumentError] if `from_branch_name` does not exist, is the same as the current branch,
+    #                        or if either branch has no commits.
+    # @raise [ArgumentError] if a commit with the given ID already exists.
+    # @return [Elements::GitCommit] The created merge commit object.
+    def merge(from_branch_name:, id: nil, tag: nil, type: :MERGE)
+      if from_branch_name == @current_branch_name
+        raise ArgumentError,
+              "Cannot merge branch '#{from_branch_name}' into itself"
+      end
+      unless @branches.key?(from_branch_name)
+        raise ArgumentError,
+              "Branch '#{from_branch_name}' does not exist. Cannot merge."
+      end
+      unless @branches.key?(@current_branch_name)
+        raise ArgumentError, "Current branch '#{@current_branch_name}' does not exist. Cannot merge."
+      end
+
+      target_branch = @branches[@current_branch_name]
+      source_branch = @branches[from_branch_name]
+
+      target_head_id = target_branch.head_commit_id
+      source_head_id = source_branch.head_commit_id
+
+      unless target_head_id
+        raise ArgumentError,
+              "Current branch '#{@current_branch_name}' has no commits to merge into."
+      end
+      raise ArgumentError, "Source branch '#{from_branch_name}' has no commits to merge from." unless source_head_id
+
+      # Merge commit parents are the heads of the two branches being merged
+      parent_ids = [target_head_id, source_head_id].sort # Sort for consistent checksumming/comparison
+
+      merge_commit_id = id || generate_commit_id(parent_ids,
+                                                 "Merge branch '#{from_branch_name}' into #{@current_branch_name}")
+      raise ArgumentError, "Commit with ID '#{merge_commit_id}' already exists" if @commits.key?(merge_commit_id)
+
+      merge_commit = Elements::GitCommit.new(
+        id: merge_commit_id,
+        parent_ids:,
+        branch_name: @current_branch_name, # Merge commit belongs to the target branch
+        message: "Merge branch '#{from_branch_name}' into #{@current_branch_name}", # Default message
+        tag:,
+        type: # Use provided type, default :MERGE
+      )
+
+      @commits[merge_commit_id] = merge_commit
+      @commit_order << merge_commit_id
+
+      # Update the head of the current (target) branch
+      target_branch.attributes[:head_commit_id] = merge_commit_id
+
+      update_checksum!
+      merge_commit
+    end
+
+    # Cherry-picks an existing commit onto the current branch.
+    # Creates a new commit on the current branch that mirrors the specified commit.
+    #
+    # @param commit_id [String] The ID of the commit to cherry-pick.
+    # @param parent_override_id [String, nil] Optional: If cherry-picking a merge commit, specifies which parent lineage to follow.
+    #                                         (Note: Basic implementation might ignore this for simplicity initially).
+    # @raise [ArgumentError] if the commit_id does not exist, is already on the current branch,
+    #                        or if the current branch has no commits.
+    # @return [Elements::GitCommit] The created cherry-pick commit object.
+    # Basic implementation ignores parent_override_id for now
+    def cherry_pick(commit_id:, parent_override_id: nil)
+      unless @commits.key?(commit_id)
+        raise ArgumentError,
+              "Commit with ID '#{commit_id}' does not exist. Cannot cherry-pick."
+      end
+
+      source_commit = @commits[commit_id]
+      current_branch_head_id = current_head_commit_id
+
+      unless current_branch_head_id
+        raise ArgumentError,
+              "Current branch '#{@current_branch_name}' has no commits. Cannot cherry-pick onto it."
+      end
+      if source_commit.branch_name == @current_branch_name
+        raise ArgumentError,
+              "Commit '#{commit_id}' is already on the current branch '#{@current_branch_name}'. Cannot cherry-pick."
+      end
+
+      # More robust check: walk history? For now, simple branch name check.
+
+      # TODO: Handle cherry-picking merge commits and parent_override_id if needed later.
+      if source_commit.parent_ids.length > 1 && !parent_override_id
+        warn "Cherry-picking a merge commit (#{commit_id}) without specifying a parent override is ambiguous. Picking first parent lineage by default."
+        # Or raise ArgumentError: "Cherry-picking a merge commit requires specifying parent_override_id."
+      end
+
+      parent_ids = [current_branch_head_id] # Cherry-pick commit's parent is the current head
+      new_commit_id = generate_commit_id(parent_ids, "Cherry-pick: #{source_commit.message || source_commit.id}")
+      if @commits.key?(new_commit_id)
+        raise ArgumentError,
+              "Generated commit ID '#{new_commit_id}' conflicts with existing commit."
+      end
+
+      cherry_pick_commit = Elements::GitCommit.new(
+        id: new_commit_id,
+        parent_ids:,
+        branch_name: @current_branch_name,
+        message: source_commit.message || "Cherry-pick of #{source_commit.id}", # Copy message or use default
+        tag: nil, # Cherry-picks usually don't copy tags directly
+        type: :CHERRY_PICK,
+        cherry_pick_source_id: commit_id # Link back to the original commit
+      )
+
+      @commits[new_commit_id] = cherry_pick_commit
+      @commit_order << new_commit_id
+
+      # Update the head of the current branch
+      current_branch = @branches[@current_branch_name]
+      current_branch.attributes[:head_commit_id] = new_commit_id
+
+      update_checksum!
+      cherry_pick_commit
+    end
+
+    # --- Base Class Implementation ---
+
+    # Returns the specific content of the gitgraph diagram as a hash.
+    # @return [Hash]
+    def to_h_content
+      {
+        commits: @commits.values.map(&:to_h),
+        branches: @branches.values.map(&:to_h),
+        commit_order: @commit_order,
+        current_branch_name: @current_branch_name # Useful for resuming state? Maybe not needed in content hash.
+        # Consider if current_branch_name should be part of the checksummable content.
+        # For now, let's include it for potential deserialization needs.
+      }
+    end
+
+    # Returns a hash mapping element types to their collections for diffing.
+    # @return [Hash{Symbol => Array<Elements::GitCommit | Elements::GitBranch>}]
+    def identifiable_elements
+      {
+        commits: @commits.values,
+        branches: @branches.values
+      }
+    end
+
+    # Class method to create a GitgraphDiagram from a hash.
+    # @param data_hash [Hash] Hash containing diagram data.
+    # @param version [String, Integer, nil] Diagram version.
+    # @param checksum [String, nil] Expected checksum (optional).
+    # @return [GitgraphDiagram] The instantiated diagram.
+    def self.from_h(data_hash, version:, checksum:)
+      diagram = new(version:)
+
+      # Restore commits
+      commits_data = data_hash[:commits] || data_hash['commits'] || []
+      commits_data.each do |commit_h|
+        # Convert type back to symbol if it's a string
+        commit_data = commit_h.transform_keys(&:to_sym)
+        commit_data[:type] = commit_data[:type].to_sym if commit_data[:type].is_a?(String)
+        commit = Elements::GitCommit.new(commit_data)
+        diagram.commits[commit.id] = commit
+      end
+
+      # Restore branches
+      branches_data = data_hash[:branches] || data_hash['branches'] || []
+      branches_data.each do |branch_h|
+        branch = Elements::GitBranch.new(branch_h.transform_keys(&:to_sym))
+        diagram.branches[branch.name] = branch
+      end
+
+      # Restore commit order
+      diagram.instance_variable_set(:@commit_order, data_hash[:commit_order] || data_hash['commit_order'] || [])
+
+      # Restore current branch name
+      diagram.instance_variable_set(:@current_branch_name,
+                                    data_hash[:current_branch_name] || data_hash['current_branch_name'] || 'master')
+
+      # Recalculate checksum after loading all data
+      diagram.send(:update_checksum!) # Use send to call protected method from class scope
+
+      # Optional: Verify checksum if provided
+      if checksum && diagram.checksum != checksum
+        warn "Checksum mismatch for loaded GitgraphDiagram (version: #{version}). Expected #{checksum}, got #{diagram.checksum}."
+      end
+
+      diagram
+    end
+
+    private
+
+    # Generates a unique ID for a commit if one isn't provided.
+    # Placeholder - could use SHA1/SHA256 of content or simple counter.
+    # Using a simple counter based on commit order for now.
+    def generate_commit_id(parent_ids, message)
+      # Simple approach: use commit count + part of parent hash if available
+      base = @commit_order.size.to_s
+      parent_part = parent_ids.first ? parent_ids.first[0..5] : 'root'
+      # NOTE: This is NOT cryptographically secure or git-like. Just for basic uniqueness.
+      "commit-#{base}-#{parent_part}-#{Digest::SHA1.hexdigest(message || Time.now.to_s)[0..5]}"
+    end
+
+    # Helper to get the head commit ID of the current branch.
+    def current_head_commit_id
+      current_branch = @branches[@current_branch_name]
+      current_branch&.head_commit_id # Returns nil if branch doesn't exist yet
+    end
+
+    # Protected method access for from_h
+    protected :update_checksum!
+  end
+end

data/lib/diagrams/pie_diagram.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-require_relative 'elements/slice'
-
 module Diagrams
   # Represents a Pie Chart diagram consisting of slices.
   class PieDiagram < Base

data/lib/diagrams/state_diagram.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'base'
-require_relative 'elements/state'
-require_relative 'elements/transition'
-require_relative 'elements/event' # Assuming events are still desired
-
 module Diagrams
   # Represents a State Diagram consisting of states and transitions between them.
   class StateDiagram < Base

data/lib/diagrams/timeline_diagram.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Diagrams
+  # Represents a timeline diagram illustrating a chronology of events.
+  class TimelineDiagram < Base
+    DEFAULT_SECTION_TITLE = 'Default Section'
+
+    attr_reader :title, :sections
+
+    # Initializes a new TimelineDiagram.
+    #
+    # @param title [String, nil] Optional title for the timeline.
+    # @param sections [Array<Element::TimelineSection>] Initial sections (optional).
+    # @param version [String, Integer, nil] User-defined version identifier.
+    def initialize(title: nil, sections: [], version: 1)
+      super(version:)
+      @title = title&.strip
+      @sections = sections.is_a?(Array) ? sections : []
+      # Ensure there's always at least a default section if none provided initially
+      ensure_default_section if @sections.empty?
+      update_checksum!
+    end
+
+    # Sets the title of the timeline.
+    #
+    # @param new_title [String] The title text.
+    # @return [String] The new title.
+    def set_title(new_title)
+      @title = new_title.strip
+      update_checksum!
+      @title
+    end
+
+    # Adds a new section to the timeline.
+    # Subsequent periods/events will be added to this section.
+    #
+    # @param section_title [String] The title of the section.
+    # @raise [ArgumentError] if a section with the same title already exists.
+    # @return [Elements::TimelineSection] The newly added section.
+    def add_section(section_title)
+      clean_title = section_title.strip
+      raise ArgumentError, "Section title '#{clean_title}' cannot be empty" if clean_title.empty?
+      if find_section(clean_title)
+        raise ArgumentError, "Section with title '#{clean_title}' already exists"
+      end
+
+      # Remove default section if it's empty and we're adding a real one
+      if @sections.size == 1 && @sections.first.title == DEFAULT_SECTION_TITLE && @sections.first.periods.empty?
+        @sections.clear
+      end
+
+      new_section = Elements::TimelineSection.new(title: clean_title)
+      @sections << new_section
+      update_checksum!
+      new_section
+    end
+
+    # Adds a time period with one or more events to the current (last) section.
+    #
+    # @param period_label [String] The label for the time period (e.g., "2004", "Bronze Age").
+    # @param events [Array<String> | String] A single event description or an array of event descriptions.
+    # @raise [ArgumentError] if period_label or any event description is empty.
+    # @raise [StandardError] if no sections exist (shouldn't happen due to default section).
+    # @return [Elements::TimelinePeriod] The newly added period.
+    def add_period(period_label:, events:)
+      clean_label = period_label.strip
+      raise ArgumentError, "Period label cannot be empty" if clean_label.empty?
+
+      event_list = Array(events).map(&:strip).reject(&:empty?)
+      raise ArgumentError, "Events cannot be empty" if event_list.empty?
+
+      timeline_events = event_list.map { |desc| Elements::TimelineEvent.new(description: desc) }
+      new_period = Elements::TimelinePeriod.new(label: clean_label, events: timeline_events)
+
+      current_section = @sections.last
+      raise StandardError, "Cannot add period: No section available." unless current_section
+
+      # Add period to the current section's periods array
+      # Dry::Struct arrays are immutable, so we need to create a new section object
+      updated_periods = current_section.periods + [new_period]
+      # Create a completely new section instance with the updated periods array
+      updated_section = Elements::TimelineSection.new(title: current_section.title, periods: updated_periods)
+
+      # Find the index of the current section and update it in place
+      # Rebuild the sections array, replacing the modified section
+      current_section_title = current_section.title
+      # Rebuild the sections array by mapping, replacing the target section
+      @sections = @sections.map do |section|
+        section.title == current_section_title ? updated_section : section
+      end
+
+      update_checksum!
+      new_period
+    end
+
+    # --- Base Class Implementation ---
+
+    def to_h_content
+      content = {
+        sections: @sections.map(&:to_h)
+      }
+      content[:title] = @title if @title
+      content
+    end
+
+    def identifiable_elements
+      # Sections and Periods are the main identifiable structures. Events are nested.
+      # Use section title and period label as identifiers.
+      {
+        sections: @sections,
+        periods: @sections.flat_map(&:periods) # Flatten periods from all sections
+      }
+    end
+
+    def self.from_h(data_hash, version:, checksum:)
+      title = data_hash[:title] || data_hash['title']
+      sections_data = data_hash[:sections] || data_hash['sections'] || []
+
+      sections = sections_data.map do |section_h|
+        section_data = section_h.transform_keys(&:to_sym)
+        periods_data = section_data[:periods] || []
+        periods = periods_data.map do |period_h|
+          period_data = period_h.transform_keys(&:to_sym)
+          events_data = period_data[:events] || []
+          events = events_data.map do |event_h|
+            event_data = event_h.transform_keys(&:to_sym)
+            Elements::TimelineEvent.new(event_data)
+          end
+          Elements::TimelinePeriod.new(period_data.merge(events:))
+        end
+        Elements::TimelineSection.new(section_data.merge(periods:))
+      end
+
+      diagram = new(title:, sections:, version:)
+
+      # Optional: Verify checksum
+      if checksum && diagram.checksum != checksum
+        warn "Checksum mismatch for loaded TimelineDiagram (version: #{version}). Expected #{checksum}, got #{diagram.checksum}."
+      end
+
+      diagram
+    end
+
+    private
+
+    # Ensures a default section exists if the sections array is empty.
+    def ensure_default_section
+      unless @sections.any? { |s| s.title == DEFAULT_SECTION_TITLE }
+        @sections << Elements::TimelineSection.new(title: DEFAULT_SECTION_TITLE)
+      end
+    end
+
+    # Finds a section by its title.
+    def find_section(section_title)
+      @sections.find { |s| s.title == section_title }
+    end
+
+    # Protected method access for from_h
+    protected :update_checksum!
+  end
+end

data/lib/diagrams/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Diagrams
-  VERSION = '0.3.0'
+  VERSION = '0.3.2'
 end

data/lib/diagrams.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
 
 require 'zeitwerk'
-require_relative 'diagrams/version' # Keep this for gemspec access before setup
+require 'digest'
+require 'json'
+require 'dry-equalizer'
+require 'dry-struct'
+require_relative 'diagrams/version'
 
 loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/diagram.rb")
 loader.setup
 
 # This module handles diagrams creation and manipulation.

data/sig/diagrams/elements/git_branch.rbs

@@ -0,0 +1,19 @@
+module Diagrams
+  module Elements
+    # Represents a branch in a Gitgraph diagram.
+    class GitBranch < ::Dry::Struct
+      include Elements::Types
+
+      # Attributes
+      attr_reader name: String
+      attr_reader head_commit_id: String?
+      attr_reader start_commit_id: String
+
+      # Methods
+      def initialize: (name: String, ?head_commit_id: String?, start_commit_id: String) -> void
+                     | (Hash[Symbol, untyped]) -> void # Allow hash initialization
+
+      def to_h: () -> Hash[Symbol, String]
+    end
+  end
+end

data/sig/diagrams/elements/git_commit.rbs

@@ -0,0 +1,23 @@
+module Diagrams
+  module Elements
+    # Represents a commit in a Gitgraph diagram.
+    class GitCommit < ::Dry::Struct
+      include Elements::Types
+
+      # Attributes
+      attr_reader id: String
+      attr_reader parent_ids: Array[String]
+      attr_reader branch_name: String
+      attr_reader message: String?
+      attr_reader tag: String?
+      attr_reader type: Symbol # :NORMAL | :REVERSE | :HIGHLIGHT | :MERGE | :CHERRY_PICK
+      attr_reader cherry_pick_source_id: String?
+
+      # Methods
+      def initialize: (id: String, ?parent_ids: Array[String], branch_name: String, ?message: String?, ?tag: String?, ?type: Symbol, ?cherry_pick_source_id: String?) -> void
+                     | (Hash[Symbol, untyped]) -> void # Allow hash initialization
+
+      def to_h: () -> Hash[Symbol, String | Array[String] | Symbol]
+    end
+  end
+end

data/sig/diagrams/elements/timeline_event.rbs

@@ -0,0 +1,17 @@
+module Diagrams
+  module Elements
+    # Represents a single event description within a timeline period.
+    class TimelineEvent < ::Dry::Struct
+      include Elements::Types
+
+      # Attributes
+      attr_reader description: String
+
+      # Methods
+      def initialize: (description: String) -> void
+                     | (Hash[Symbol, untyped]) -> void # Allow hash initialization
+
+      def to_h: () -> Hash[Symbol, String]
+    end
+  end
+end

data/sig/diagrams/elements/timeline_period.rbs

@@ -0,0 +1,18 @@
+module Diagrams
+  module Elements
+    # Represents a specific time period on the timeline, containing one or more events.
+    class TimelinePeriod < ::Dry::Struct
+      include Elements::Types
+
+      # Attributes
+      attr_reader label: String
+      attr_reader events: Array[TimelineEvent]
+
+      # Methods
+      def initialize: (label: String, events: Array[TimelineEvent]) -> void
+                     | (Hash[Symbol, untyped]) -> void # Allow hash initialization
+
+      def to_h: () -> Hash[Symbol, String | Array[Hash[Symbol, String]]]
+    end
+  end
+end

data/sig/diagrams/elements/timeline_section.rbs

@@ -0,0 +1,18 @@
+module Diagrams
+  module Elements
+    # Represents a section or age within the timeline, grouping multiple time periods.
+    class TimelineSection < ::Dry::Struct
+      include Elements::Types
+
+      # Attributes
+      attr_reader title: String
+      attr_reader periods: Array[TimelinePeriod]
+
+      # Methods
+      def initialize: (title: String, ?periods: Array[TimelinePeriod]) -> void
+                     | (Hash[Symbol, untyped]) -> void # Allow hash initialization
+
+      def to_h: () -> Hash[Symbol, String | Array[Hash[Symbol, untyped]]]
+    end
+  end
+end

data/sig/diagrams/gitgraph_diagram.rbs

@@ -0,0 +1,35 @@
+module Diagrams
+  # Represents a Gitgraph diagram, tracking commits, branches, and their relationships.
+  class GitgraphDiagram < Base
+    # Instance Variables (via attr_reader)
+    attr_reader commits: Hash[String, Elements::GitCommit]
+    attr_reader branches: Hash[String, Elements::GitBranch]
+    attr_reader commit_order: Array[String]
+    attr_reader current_branch_name: String
+
+    # Initialization
+    def initialize: (?version: String | Integer) -> void
+
+    # --- Git Operations ---
+    def commit: (?id: String?, ?message: String?, ?tag: String?, ?type: Symbol) -> Elements::GitCommit
+    def branch: (name: String, ?start_commit_id: String?) -> Elements::GitBranch
+    def checkout: (name: String) -> String
+    def merge: (from_branch_name: String, ?id: String?, ?tag: String?, ?type: Symbol) -> Elements::GitCommit
+    def cherry_pick: (commit_id: String, ?parent_override_id: String?) -> Elements::GitCommit
+
+    # --- Base Class Implementation ---
+    def to_h_content: () -> Hash[Symbol, untyped] # More specific: Hash[Symbol, Array[Hash[Symbol, untyped]] | Array[String] | String]
+    def identifiable_elements: () -> Hash[Symbol, Array[Elements::GitCommit | Elements::GitBranch]]
+
+    # Class method for deserialization
+    def self.from_h: (Hash[Symbol, untyped] data_hash, version: String | Integer | nil, checksum: String?) -> GitgraphDiagram
+
+    # --- Private/Protected Methods ---
+    private
+    def generate_commit_id: (Array[String] parent_ids, String? message) -> String
+    def current_head_commit_id: () -> String?
+
+    # Inherited protected method
+    # def update_checksum!: () -> String # Defined in Base, but accessible via send in from_h
+  end
+end

data/sig/diagrams/timeline_diagram.rbs

@@ -0,0 +1,33 @@
+module Diagrams
+  # Represents a timeline diagram illustrating a chronology of events.
+  class TimelineDiagram < Base
+    DEFAULT_SECTION_TITLE: String
+
+    # Instance Variables (via attr_reader)
+    attr_reader title: String?
+    attr_reader sections: Array[Elements::TimelineSection]
+
+    # Initialization
+    def initialize: (?title: String?, ?sections: Array[Elements::TimelineSection], ?version: String | Integer) -> void
+
+    # Public Methods
+    def set_title: (String new_title) -> String
+    def add_section: (String section_title) -> Elements::TimelineSection
+    def add_period: (period_label: String, events: String | Array[String]) -> Elements::TimelinePeriod
+
+    # --- Base Class Implementation ---
+    def to_h_content: () -> Hash[Symbol, untyped] # More specific: Hash[:title?, String | :sections, Array[Hash]]
+    def identifiable_elements: () -> Hash[Symbol, Array[Elements::TimelineSection | Elements::TimelinePeriod]]
+
+    # Class method for deserialization
+    def self.from_h: (Hash[Symbol, untyped] data_hash, version: String | Integer | nil, checksum: String?) -> TimelineDiagram
+
+    # --- Private Methods ---
+    private
+    def ensure_default_section: () -> void
+    def find_section: (String section_title) -> Elements::TimelineSection?
+
+    # Inherited protected method
+    # def update_checksum!: () -> String
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: diagram
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Abdelkader Boudih
 bindir: bin
 cert_chain: []
-date: 2025-03-31 00:00:00.000000000 Z
+date: 2025-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-equalizer
@@ -212,39 +212,55 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/diagram.rb
 - lib/diagrams.rb
 - lib/diagrams/base.rb
 - lib/diagrams/class_diagram.rb
+- lib/diagrams/elements.rb
 - lib/diagrams/elements/class_entity.rb
 - lib/diagrams/elements/edge.rb
 - lib/diagrams/elements/event.rb
+- lib/diagrams/elements/git_branch.rb
+- lib/diagrams/elements/git_commit.rb
 - lib/diagrams/elements/node.rb
 - lib/diagrams/elements/relationship.rb
 - lib/diagrams/elements/slice.rb
 - lib/diagrams/elements/state.rb
 - lib/diagrams/elements/task.rb
+- lib/diagrams/elements/timeline_event.rb
+- lib/diagrams/elements/timeline_period.rb
+- lib/diagrams/elements/timeline_section.rb
 - lib/diagrams/elements/transition.rb
 - lib/diagrams/flowchart_diagram.rb
 - lib/diagrams/gantt_diagram.rb
+- lib/diagrams/gitgraph_diagram.rb
 - lib/diagrams/pie_diagram.rb
 - lib/diagrams/state_diagram.rb
+- lib/diagrams/timeline_diagram.rb
 - lib/diagrams/version.rb
 - sig/diagrams/base.rbs
 - sig/diagrams/class_diagram.rbs
 - sig/diagrams/elements/class_entity.rbs
 - sig/diagrams/elements/edge.rbs
 - sig/diagrams/elements/event.rbs
+- sig/diagrams/elements/git_branch.rbs
+- sig/diagrams/elements/git_commit.rbs
 - sig/diagrams/elements/node.rbs
 - sig/diagrams/elements/relationship.rbs
 - sig/diagrams/elements/slice.rbs
 - sig/diagrams/elements/state.rbs
 - sig/diagrams/elements/task.rbs
+- sig/diagrams/elements/timeline_event.rbs
+- sig/diagrams/elements/timeline_period.rbs
+- sig/diagrams/elements/timeline_section.rbs
 - sig/diagrams/elements/transition.rbs
 - sig/diagrams/elements/types.rbs
 - sig/diagrams/flowchart_diagram.rbs
 - sig/diagrams/gantt_diagram.rbs
+- sig/diagrams/gitgraph_diagram.rbs
 - sig/diagrams/pie_diagram.rbs
 - sig/diagrams/state_diagram.rbs
+- sig/diagrams/timeline_diagram.rbs
 homepage: https://github.com/seuros/diagram-ruby
 licenses:
 - MIT