ratatui_ruby 0.1.0 → 0.3.0

data/lib/ratatui_ruby/dsl.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  ##
+  # A wrapper class that provides a concise DSL for creating widgets and interacting
+  # with the terminal within the +main_loop+.
+  #
+  # This class is yielded to the block provided to {RatatuiRuby.main_loop}.
+  # It uses metaprogramming to delegate method calls to {RatatuiRuby} module functions
+  # and to act as a factory for {RatatuiRuby} widget classes.
+  #
+  # == Features
+  #
+  # 1. **Widget Shorthand**: Provides factory methods for every widget class.
+  #    Converts snake_case method calls (e.g., +paragraph+) into CamelCase class instantiations
+  #    (e.g., +RatatuiRuby::Paragraph.new+).
+  #
+  # 2. **Method Shorthand**: Aliases module functions of {RatatuiRuby}, allowing you
+  #    to call methods like +draw+ and +poll_event+ directly on the DSL object.
+  #
+  # == Example
+  #
+  #   RatatuiRuby.main_loop do |tui|
+  #     # Create UI using shorthand methods
+  #     view = tui.paragraph(
+  #       text: "Hello World",
+  #       block: tui.block(borders: [:all])
+  #     )
+  #
+  #     # Use module aliases to draw and handle events
+  #     tui.draw(view)
+  #     event = tui.poll_event
+  #
+  #     break if event && event[:code] == "q"
+  #   end
+  class DSL
+    # Wrap methods directly
+    RatatuiRuby.singleton_methods(false).each do |method_name|
+      define_method(method_name) do |*args, **kwargs, &block|
+        RatatuiRuby.public_send(method_name, *args, **kwargs, &block)
+      end
+    end
+
+    # Wrap classes as snake_case factories
+    RatatuiRuby.constants.each do |const_name|
+      next if const_name == :Buffer
+
+      klass = RatatuiRuby.const_get(const_name)
+      next unless klass.is_a?(Class)
+
+      method_name = const_name.to_s
+                              .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                              .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                              .downcase
+
+      define_method(method_name) do |*args, **kwargs, &block|
+        klass.new(*args, **kwargs, &block)
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/schema/calendar.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # A Monthly Calendar widget.
+  #
+  # [year] Integer (e.g., 2025)
+  # [month] Integer (1-12)
+  # [day_style] Style (Style for regular days)
+  # [header_style] Style (Style for the month title)
+  # [block] Block
+  class Calendar < Data.define(:year, :month, :day_style, :header_style, :block)
+    # Creates a new Calendar.
+    #
+    # [year] Integer (e.g., 2025)
+    # [month] Integer (1-12)
+    # [day_style] Style (Style for regular days)
+    # [header_style] Style (Style for the month title)
+    # [block] Block
+    def initialize(year:, month:, day_style: nil, header_style: nil, block: nil)
+      super
+    end
+  end
+end

data/lib/ratatui_ruby/schema/chart.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # Defines an Axis for a Chart
+  # [title] String
+  # [bounds] Array<Float> [min, max]
+  # [labels] Array<String>
+  # [style] Style
+  class Axis < Data.define(:title, :bounds, :labels, :style)
+    # Creates a new Axis.
+    #
+    # [title] String
+    # [bounds] Array<Float> [min, max]
+    # [labels] Array<String>
+    # [style] Style
+    def initialize(title: "", bounds: [0.0, 10.0], labels: [], style: nil)
+      super
+    end
+  end
+
+  # Defines a Dataset for a Chart.
+  # [name] The name of the dataset.
+  # [data] Array of arrays [[x, y], [x, y]] (Floats).
+  # [color] The color of the line.
+  # [marker] Symbol (:dot, :braille, :block, :bar)
+  # [graph_type] Symbol (:line, :scatter)
+  class Dataset < Data.define(:name, :data, :color, :marker, :graph_type)
+    # Creates a new Dataset.
+    #
+    # [name] The name of the dataset.
+    # [data] Array of arrays [[x, y], [x, y]] (Floats).
+    # [color] The color of the line.
+    # [marker] Symbol (:dot, :braille, :block, :bar)
+    # [graph_type] Symbol (:line, :scatter)
+    def initialize(name:, data:, color: "reset", marker: :dot, graph_type: :line)
+      super
+    end
+  end
+
+  # A generic Cartesian chart.
+  # [datasets] Array<Dataset>
+  # [x_axis] Axis
+  # [y_axis] Axis
+  # [block] Block
+  # [style] Style (base style)
+  class Chart < Data.define(:datasets, :x_axis, :y_axis, :block, :style)
+    # Creates a new Chart widget.
+    #
+    # [datasets] Array<Dataset>
+    # [x_axis] Axis
+    # [y_axis] Axis
+    # [block] Block
+    # [style] Style (base style)
+    def initialize(datasets:, x_axis:, y_axis:, block: nil, style: nil)
+      super
+    end
+  end
+
+  # A complex chart widget. (Legacy/Alias for Chart)
+  #
+  # [datasets] Array of Dataset objects.
+  # [x_labels] Array of Strings for the X-axis labels.
+  # [y_labels] Array of Strings for the Y-axis labels.
+  # [y_bounds] Array of two Floats [min, max] for the Y-axis.
+  # [block] Optional block widget to wrap the chart.
+  class LineChart < Data.define(:datasets, :x_labels, :y_labels, :y_bounds, :block)
+    # Creates a new LineChart widget.
+    #
+    # [datasets] Array of Dataset objects.
+    # [x_labels] Array of Strings for the X-axis labels.
+    # [y_labels] Array of Strings for the Y-axis labels.
+    # [y_bounds] Array of two Floats [min, max] for the Y-axis.
+    # [block] Optional block widget to wrap the chart.
+    def initialize(datasets:, x_labels: [], y_labels: [], y_bounds: [0.0, 100.0], block: nil)
+      super
+    end
+  end
+end

data/lib/ratatui_ruby/schema/clear.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # A widget that clears (resets) the terminal buffer in the area it is rendered into.
+  #
+  # The Clear widget is essential for creating opaque popups and modals. Without it,
+  # background content or styles (like background colors) will "bleed through"
+  # empty spaces or transparent widgets.
+  #
+  # > [!TIP]
+  # > Use `Clear` to prevent "Style Bleed". If a widget rendered behind the popup
+  # > has a background color, widgets rendered on top with `Style.default` will
+  # > inherit that background color unless you `Clear` the area first.
+  #
+  # == Usage with Overlay
+  #
+  # Because RatatuiRuby uses an immediate-mode UI pattern, you must use {Overlay} to
+  # layer widgets properly. The typical pattern for creating an opaque popup is:
+  #
+  #   background = Paragraph.new(text: "Background content...")
+  #   popup = Paragraph.new(
+  #     text: "Popup content",
+  #     block: Block.new(title: "Popup", borders: [:all])
+  #   )
+  #
+  #   # Create an opaque popup by layering: background -> Clear -> popup
+  #   ui = Overlay.new(
+  #     layers: [
+  #       background,
+  #       Center.new(
+  #         child: Overlay.new(
+  #           layers: [
+  #             Clear.new,  # Erases background in this area
+  #             popup       # Draws on top of cleared area
+  #           ]
+  #         ),
+  #         width_percent: 50,
+  #         height_percent: 40
+  #       )
+  #     ]
+  #   )
+  #
+  # Without the Clear widget, the background text would be visible through the
+  # empty spaces in the popup.
+  #
+  # == Optional Block Parameter
+  #
+  # You can optionally provide a {Block} to draw borders around the cleared area:
+  #
+  #   Clear.new(block: Block.new(title: "Cleared Area", borders: [:all]))
+  #
+  # This is equivalent to:
+  #
+  #   Overlay.new(
+  #     layers: [
+  #       Clear.new,
+  #       Block.new(title: "Cleared Area", borders: [:all])
+  #     ]
+  #   )
+  #
+  # [block] Optional {Block} widget to render on top of the cleared area.
+  #
+  # @see Overlay
+  # @see Center
+  # @see Block
+  class Clear < Data.define(:block)
+    # Creates a new Clear widget.
+    #
+    # @param block [Block, nil] Optional block widget to render on top of the cleared area.
+    #
+    # @example Basic usage
+    #   Clear.new
+    #
+    # @example With a border
+    #   Clear.new(block: Block.new(title: "Modal", borders: [:all]))
+    def initialize(block: nil)
+      super
+    end
+  end
+end

data/lib/ratatui_ruby/schema/list.rb

@@ -8,14 +8,20 @@ module RatatuiRuby
   #
   # [items] An array of strings to display in the list.
   # [selected_index] The index of the currently selected item, or nil if none.
+  # [style] The base style for all items.
+  # [highlight_style] The style for the selected item.
+  # [highlight_symbol] The symbol to display in front of the selected item.
   # [block] An optional Block widget to wrap the list.
-  class List < Data.define(:items, :selected_index, :block)
+  class List < Data.define(:items, :selected_index, :style, :highlight_style, :highlight_symbol, :block)
     # Creates a new List.
     #
     # [items] An array of strings to display in the list.
     # [selected_index] The index of the currently selected item, or nil if none.
+    # [style] The base style for all items.
+    # [highlight_style] The style for the selected item.
+    # [highlight_symbol] The symbol to display in front of the selected item.
     # [block] An optional Block widget to wrap the list.
-    def initialize(items: [], selected_index: nil, block: nil)
+    def initialize(items: [], selected_index: nil, style: nil, highlight_style: nil, highlight_symbol: "> ", block: nil)
       super
     end
   end

data/lib/ratatui_ruby/schema/paragraph.rb

@@ -9,7 +9,8 @@ module RatatuiRuby
   # [text] the text to display.
   # [style] the style to apply (Style object).
   # [block] an optional Block widget to wrap the paragraph.
-  class Paragraph < Data.define(:text, :style, :block, :wrap, :align)
+  # [scroll] scroll offset as (y, x) array matching ratatui convention.
+  class Paragraph < Data.define(:text, :style, :block, :wrap, :align, :scroll)
     # Creates a new Paragraph.
     #
     # [text] the text to display.
@@ -17,7 +18,8 @@ module RatatuiRuby
     # [block] the block to wrap the paragraph.
     # [wrap] whether to wrap text at width.
     # [align] alignment (:left, :center, :right).
-    def initialize(text:, style: Style.default, block: nil, wrap: false, align: :left)
+    # [scroll] scroll offset as (y, x) array (default: [0, 0]).
+    def initialize(text:, style: Style.default, block: nil, wrap: false, align: :left, scroll: [0, 0])
       super
     end
 
@@ -29,9 +31,10 @@ module RatatuiRuby
     # [block] the block to wrap the paragraph.
     # [wrap] whether to wrap text at width.
     # [align] alignment (:left, :center, :right).
-    def self.new(text:, style: nil, fg: nil, bg: nil, block: nil, wrap: false, align: :left)
+    # [scroll] scroll offset as (y, x) array (default: [0, 0]).
+    def self.new(text:, style: nil, fg: nil, bg: nil, block: nil, wrap: false, align: :left, scroll: [0, 0])
       style ||= Style.new(fg:, bg:)
-      super(text:, style:, block:, wrap:, align:)
+      super(text:, style:, block:, wrap:, align:, scroll:)
     end
   end
 end

data/lib/ratatui_ruby/schema/rect.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  # A rectangle in the terminal grid.
+  #
+  # [x] The x-coordinate of the top-left corner.
+  # [y] The y-coordinate of the top-left corner.
+  # [width] The width of the rectangle.
+  # [height] The height of the rectangle.
+  class Rect < Data.define(:x, :y, :width, :height)
+    # Creates a new Rect.
+    #
+    # [x] The x-coordinate of the top-left corner.
+    # [y] The y-coordinate of the top-left corner.
+    # [width] The width of the rectangle.
+    # [height] The height of the rectangle.
+    def initialize(x: 0, y: 0, width: 0, height: 0)
+      super
+    end
+  end
+end

data/lib/ratatui_ruby/schema/table.rb

@@ -9,15 +9,21 @@ module RatatuiRuby
   # [header] An array of strings or Paragraphs representing the header row.
   # [rows] An array of arrays of strings or Paragraphs representing the data rows.
   # [widths] An array of Constraint objects defining column widths.
+  # [highlight_style] The style for the selected row.
+  # [highlight_symbol] The symbol to display in front of the selected row.
+  # [selected_row] The index of the currently selected row, or nil if none.
   # [block] An optional Block widget to wrap the table.
-  class Table < Data.define(:header, :rows, :widths, :block)
+  class Table < Data.define(:header, :rows, :widths, :highlight_style, :highlight_symbol, :selected_row, :block)
     # Creates a new Table.
     #
     # [header] An array of strings or Paragraphs representing the header row.
     # [rows] An array of arrays of strings or Paragraphs representing the data rows.
     # [widths] An array of Constraint objects defining column widths.
+    # [highlight_style] The style for the selected row.
+    # [highlight_symbol] The symbol to display in front of the selected row.
+    # [selected_row] The index of the currently selected row, or nil if none.
     # [block] An optional Block widget to wrap the table.
-    def initialize(header: nil, rows: [], widths: [], block: nil)
+    def initialize(header: nil, rows: [], widths: [], highlight_style: nil, highlight_symbol: "> ", selected_row: nil, block: nil)
       super
     end
   end

data/lib/ratatui_ruby/version.rb

@@ -6,5 +6,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/ratatui_ruby.rb

@@ -4,6 +4,7 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 require_relative "ratatui_ruby/version"
+require_relative "ratatui_ruby/schema/rect"
 require_relative "ratatui_ruby/schema/paragraph"
 require_relative "ratatui_ruby/schema/layout"
 require_relative "ratatui_ruby/schema/block"
@@ -15,12 +16,14 @@ require_relative "ratatui_ruby/schema/table"
 require_relative "ratatui_ruby/schema/tabs"
 require_relative "ratatui_ruby/schema/bar_chart"
 require_relative "ratatui_ruby/schema/sparkline"
-require_relative "ratatui_ruby/schema/line_chart"
+require_relative "ratatui_ruby/schema/chart"
+require_relative "ratatui_ruby/schema/clear"
 require_relative "ratatui_ruby/schema/cursor"
 require_relative "ratatui_ruby/schema/overlay"
 require_relative "ratatui_ruby/schema/center"
 require_relative "ratatui_ruby/schema/scrollbar"
 require_relative "ratatui_ruby/schema/canvas"
+require_relative "ratatui_ruby/schema/calendar"
 
 begin
   require "ratatui_ruby/ratatui_ruby"
@@ -69,7 +72,7 @@ module RatatuiRuby
   # Polls for a keyboard event.
   #
   #   poll_event
-  #   # => { type: "key", code: "char", value: "a", modifiers: [] }
+  #   # => { type: :key, code: "a", modifiers: ["ctrl"] }
   #
   # (Native method implemented in Rust)
 
@@ -84,4 +87,23 @@ module RatatuiRuby
   #   inject_test_event("key", { code: "a" })
   #
   # (Native method implemented in Rust)
+
+  ##
+  # Provides a convenience wrapper for the main TUI loop.
+  # Initializes the terminal, runs the loop, and ensures the terminal is restored.
+  #
+  #   RatatuiRuby.main_loop do
+  #     draw RatatuiRuby::Paragraph.new(text: "Hello")
+  #     event = RatatuiRuby::poll_event
+  #     break if event && event[:type] == :key && event[:code] == "q"
+  #   end
+  def self.main_loop
+    require_relative "ratatui_ruby/dsl"
+    init_terminal
+    loop do
+      yield DSL.new
+    end
+  ensure
+    restore_terminal
+  end
 end

data/mise.toml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[tools]
+ruby = "3.4.8"
+rust = "1.91.1"
+python = "3.12"
+pre-commit = "latest"

data/sig/ratatui_ruby/buffer.rbs

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Buffer
+    def set_string: (Integer x, Integer y, String string, Style style) -> void
+    def area: () -> Rect
+  end
+end

data/sig/ratatui_ruby/schema/calendar.rbs

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Calendar < Data
+    attr_reader year: Integer
+    attr_reader month: Integer
+    attr_reader day_style: Style?
+    attr_reader header_style: Style?
+    attr_reader block: Block?
+    def self.new: (year: Integer, month: Integer, ?day_style: Style?, ?header_style: Style?, ?block: Block?) -> Calendar
+  end
+end

data/sig/ratatui_ruby/schema/{line_chart.rbs → chart.rbs}

@@ -2,11 +2,30 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 module RatatuiRuby
+  class Axis < Data
+    attr_reader title: String
+    attr_reader bounds: [Float, Float]
+    attr_reader labels: Array[String]
+    attr_reader style: Style?
+    def self.new: (?title: String, ?bounds: [Float, Float], ?labels: Array[String], ?style: Style?) -> Axis
+  end
+
   class Dataset < Data
     attr_reader name: String | Symbol
     attr_reader data: Array[[Float, Float]]
     attr_reader color: String | Symbol
-    def self.new: (name: String | Symbol, data: Array[[Float, Float]], ?color: String | Symbol) -> Dataset
+    attr_reader marker: Symbol
+    attr_reader graph_type: Symbol
+    def self.new: (name: String | Symbol, data: Array[[Float, Float]], ?color: String | Symbol, ?marker: Symbol, ?graph_type: Symbol) -> Dataset
+  end
+
+  class Chart < Data
+    attr_reader datasets: Array[Dataset]
+    attr_reader x_axis: Axis
+    attr_reader y_axis: Axis
+    attr_reader block: Block?
+    attr_reader style: Style?
+    def self.new: (datasets: Array[Dataset], x_axis: Axis, y_axis: Axis, ?block: Block?, ?style: Style?) -> Chart
   end
 
   class LineChart < Data

data/sig/ratatui_ruby/schema/list.rbs

@@ -5,7 +5,10 @@ module RatatuiRuby
   class List < Data
     attr_reader items: Array[String]
     attr_reader selected_index: Integer?
+    attr_reader style: Style?
+    attr_reader highlight_style: Style?
+    attr_reader highlight_symbol: String?
     attr_reader block: Block?
-    def self.new: (?items: Array[String], ?selected_index: Integer?, ?block: Block?) -> List
+    def self.new: (?items: Array[String], ?selected_index: Integer?, ?style: Style?, ?highlight_style: Style?, ?highlight_symbol: String?, ?block: Block?) -> List
   end
 end

data/sig/ratatui_ruby/schema/rect.rbs

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Rect < Data
+    attr_reader x: Integer
+    attr_reader y: Integer
+    attr_reader width: Integer
+    attr_reader height: Integer
+    def self.new: (x: Integer, y: Integer, width: Integer, height: Integer) -> instance
+  end
+end

data/tasks/bump/cargo_lockfile.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Lockfiles need to be refreshed by a tool after Manifests are changed.
+class CargoLockfile < Data.define(:path, :dir, :name)
+  def exists?
+    File.exist?(path)
+  end
+
+  def refresh
+    return unless exists?
+
+    Dir.chdir(dir) do
+      system("cargo update -p #{name} --offline")
+    end
+  end
+end

data/tasks/bump/changelog.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "comparison_links"
+require_relative "unreleased_section"
+require_relative "history"
+require_relative "header"
+
+# Changelog manages the project's CHANGELOG.md file.
+class Changelog
+  # Creates a new Changelog for the file at the given path.
+  def initialize(path: "CHANGELOG.md")
+    @path = path
+  end
+
+  # Releases a new version in the changelog.
+  # This moves the unreleased changes to a new version heading and resets the unreleased section.
+  def release(new_version)
+    content = File.read(@path)
+
+    header = Header.parse(content)
+    unreleased = UnreleasedSection.parse(content)
+    links = ComparisonLinks.parse(content)
+
+    raise "Could not parse CHANGELOG.md" unless header && unreleased && links
+
+    history = History.parse(content, header.length, unreleased.to_s.length, links.to_s)
+
+    links.update(new_version)
+    history.add(unreleased.as_version(new_version))
+
+    File.write(@path, "#{header}#{UnreleasedSection.fresh}\n\n#{history}\n#{links}")
+    nil
+  end
+end

data/tasks/bump/comparison_links.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# ComparisonLinks manages the git comparison links at the bottom of the changelog.
+class ComparisonLinks
+  PATTERN = /^(\[Unreleased\]: .*)$/m
+
+  # Extracts the comparison links from the given content.
+  def self.parse(content)
+    match = content.match(PATTERN)
+    new(match[1].strip) if match
+  end
+
+  # Creates a new ComparisonLinks from the given links text.
+  def initialize(links)
+    @links = links.dup
+  end
+
+  # Updates the comparison links for the new version.
+  def update(new_version)
+    pattern = %r{^\[Unreleased\]: (.*?/compare/)v(.*)\.\.\.HEAD$}
+    match = @links.match(pattern)
+    return unless match
+
+    base_url = match[1]
+    prev_version = match[2]
+
+    new_unreleased = "[Unreleased]: #{base_url}v#{new_version}...HEAD"
+    new_version_link = "[#{new_version}]: #{base_url}v#{prev_version}...v#{new_version}"
+
+    @links.sub!(pattern, "#{new_unreleased}\n#{new_version_link}")
+    nil
+  end
+
+  # Returns the current state of the links as a string.
+  def to_s
+    @links
+  end
+end

data/tasks/bump/header.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Header manages the header section of the changelog.
+class Header
+  PATTERN = /^(.*?)(?=## \[Unreleased\])/m
+
+  # Extracts the header section from the given content.
+  def self.parse(content)
+    match = content.match(PATTERN)
+    new(match[1]) if match
+  end
+
+  # Creates a new Header from the given content.
+  def initialize(content)
+    @content = content.dup
+  end
+
+  # Returns the length of the header content.
+  def length
+    @content.length
+  end
+
+  # Returns the current state of the header as a string.
+  def to_s
+    @content
+  end
+end