ratatui_ruby 0.2.0 → 0.3.1

data/ext/ratatui_ruby/src/widgets/center.rs

@@ -5,7 +5,6 @@ use crate::rendering::render_node;
 use magnus::{prelude::*, Error, Value};
 use ratatui::{
     layout::{Constraint, Direction, Layout, Rect},
-    widgets::Clear,
     Frame,
 };
 
@@ -36,7 +35,6 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 
     let center_area = popup_layout_horizontal[1];
 
-    frame.render_widget(Clear, center_area);
     render_node(frame, center_area, child)?;
     Ok(())
 }

data/ext/ratatui_ruby/src/widgets/chart.rs

@@ -12,6 +12,7 @@ use ratatui::{
 };
 
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
     let class = node.class();
     let class_name = unsafe { class.name() };
 
@@ -37,7 +38,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         for j in 0..data_array.len() {
             let point_array_val: Value = data_array.entry(j as isize)?;
             let point_array = magnus::RArray::from_value(point_array_val).ok_or_else(|| {
-                Error::new(magnus::exception::type_error(), "expected array for point")
+                Error::new(ruby.exception_type_error(), "expected array for point")
             })?;
             let x: f64 = point_array.entry(0)?;
             let y: f64 = point_array.entry(1)?;
@@ -125,6 +126,7 @@ fn parse_axis(axis_val: Value) -> Result<Axis<'static>, Error> {
 }
 
 fn render_line_chart(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
     let datasets_val: magnus::RArray = node.funcall("datasets", ())?;
     let x_labels_val: magnus::RArray = node.funcall("x_labels", ())?;
     let y_labels_val: magnus::RArray = node.funcall("y_labels", ())?;
@@ -142,7 +144,7 @@ fn render_line_chart(frame: &mut Frame, area: Rect, node: Value) -> Result<(), E
         for j in 0..data_array.len() {
             let point_array_val: Value = data_array.entry(j as isize)?;
             let point_array = magnus::RArray::from_value(point_array_val).ok_or_else(|| {
-                Error::new(magnus::exception::type_error(), "expected array for point")
+                Error::new(ruby.exception_type_error(), "expected array for point")
             })?;
             let x: f64 = point_array.entry(0)?;
             let y: f64 = point_array.entry(1)?;
@@ -181,6 +183,11 @@ fn render_line_chart(frame: &mut Frame, area: Rect, node: Value) -> Result<(), E
         let label: String = y_labels_val.entry(i as isize)?;
         y_labels.push(Span::from(label));
     }
+    // Ratatui 0.29+ requires labels to be present for the axis line to render
+    if y_labels.is_empty() {
+        y_labels.push(Span::from(""));
+        y_labels.push(Span::from(""));
+    }
 
     let y_bounds: [f64; 2] = [y_bounds_val.entry(0)?, y_bounds_val.entry(1)?];
 
@@ -233,12 +240,12 @@ mod tests {
             .x_axis(
                 Axis::default()
                     .bounds([0.0, 1.0])
-                    .labels(vec!["XMIN".into(), "XMAX".into()]),
+                    .labels(vec!["XMIN".into(), "XMAX".into()] as Vec<ratatui::text::Line>),
             )
             .y_axis(
                 Axis::default()
                     .bounds([0.0, 1.0])
-                    .labels(vec!["YMIN".into(), "YMAX".into()]),
+                    .labels(vec!["YMIN".into(), "YMAX".into()] as Vec<ratatui::text::Line>),
             );
         let mut buf = Buffer::empty(Rect::new(0, 0, 40, 20));
         chart.render(Rect::new(0, 0, 40, 20), &mut buf);

data/ext/ratatui_ruby/src/widgets/clear.rs

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+use magnus::{prelude::*, Error, Value};
+use ratatui::{layout::Rect, widgets::Widget, Frame};
+
+pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    frame.render_widget(ratatui::widgets::Clear, area);
+
+    // If a block is provided, render it on top of the cleared area
+    if let Ok(block_val) = node.funcall::<_, _, Value>("block", ()) {
+        if !block_val.is_nil() {
+            let block = crate::style::parse_block(block_val)?;
+            block.render(area, frame.buffer_mut());
+        }
+    }
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use ratatui::{backend::TestBackend, layout::Rect, Terminal};
+
+    #[test]
+    fn test_clear_renders_without_error() {
+        let backend = TestBackend::new(10, 5);
+        let mut terminal = Terminal::new(backend).unwrap();
+
+        terminal
+            .draw(|frame| {
+                let area = Rect::new(0, 0, 10, 5);
+                frame.render_widget(ratatui::widgets::Clear, area);
+            })
+            .unwrap();
+    }
+}

data/ext/ratatui_ruby/src/widgets/cursor.rs

@@ -7,7 +7,7 @@ use ratatui::{layout::Rect, Frame};
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let x: u16 = node.funcall("x", ())?;
     let y: u16 = node.funcall("y", ())?;
-    frame.set_cursor(area.x + x, area.y + y);
+    frame.set_cursor_position((area.x + x, area.y + y));
     Ok(())
 }
 

data/ext/ratatui_ruby/src/widgets/layout.rs

@@ -9,10 +9,11 @@ use ratatui::{
 };
 
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
     let direction_sym: Symbol = node.funcall("direction", ())?;
     let children_val: Value = node.funcall("children", ())?;
     let children_array = magnus::RArray::from_value(children_val)
-        .ok_or_else(|| Error::new(magnus::exception::type_error(), "expected array"))?;
+        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array"))?;
 
     let constraints_val: Value = node.funcall("constraints", ())?;
     let constraints_array = magnus::RArray::from_value(constraints_val);

data/ext/ratatui_ruby/src/widgets/list.rs

@@ -10,9 +10,10 @@ use ratatui::{
 };
 
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
     let items_val: Value = node.funcall("items", ())?;
     let items_array = magnus::RArray::from_value(items_val)
-        .ok_or_else(|| Error::new(magnus::exception::type_error(), "expected array"))?;
+        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array"))?;
     let selected_index_val: Value = node.funcall("selected_index", ())?;
     let style_val: Value = node.funcall("style", ())?;
     let highlight_style_val: Value = node.funcall("highlight_style", ())?;
@@ -89,10 +90,11 @@ mod tests {
         assert!(content.contains(">> Item 2"));
 
         // Check colors
-        assert_eq!(buf.get(0, 0).fg, ratatui::style::Color::White);
-        assert_eq!(buf.get(0, 1).fg, ratatui::style::Color::Yellow);
+        assert_eq!(buf.cell((0, 0)).unwrap().fg, ratatui::style::Color::White);
+        assert_eq!(buf.cell((0, 1)).unwrap().fg, ratatui::style::Color::Yellow);
         assert!(buf
-            .get(0, 1)
+            .cell((0, 1))
+            .unwrap()
             .modifier
             .contains(ratatui::style::Modifier::BOLD));
     }

data/ext/ratatui_ruby/src/widgets/mod.rs

@@ -7,6 +7,7 @@ pub mod calendar;
 pub mod canvas;
 pub mod center;
 pub mod chart;
+pub mod clear;
 pub mod cursor;
 pub mod gauge;
 pub mod layout;

data/ext/ratatui_ruby/src/widgets/overlay.rs

@@ -6,9 +6,10 @@ use magnus::{prelude::*, Error, Value};
 use ratatui::{layout::Rect, Frame};
 
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
     let layers_val: Value = node.funcall("layers", ())?;
     let layers_array = magnus::RArray::from_value(layers_val)
-        .ok_or_else(|| Error::new(magnus::exception::type_error(), "expected array for layers"))?;
+        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for layers"))?;
 
     for i in 0..layers_array.len() {
         let layer: Value = layers_array.entry(i as isize)?;

data/ext/ratatui_ruby/src/widgets/paragraph.rs

@@ -15,6 +15,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let block_val: Value = node.funcall("block", ())?;
     let wrap: bool = node.funcall("wrap", ())?;
     let align_sym: Symbol = node.funcall("align", ())?;
+    let scroll_val: Value = node.funcall("scroll", ())?;
 
     let style = parse_style(style_val)?;
     let mut paragraph = Paragraph::new(text).style(style);
@@ -33,6 +34,15 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         _ => {}
     }
 
+    // Apply scroll offset if provided
+    // Ruby passes (y, x) array matching ratatui's convention
+    if !scroll_val.is_nil() {
+        let scroll_array: Vec<u16> = Vec::<u16>::try_convert(scroll_val)?;
+        if scroll_array.len() >= 2 {
+            paragraph = paragraph.scroll((scroll_array[0], scroll_array[1]));
+        }
+    }
+
     frame.render_widget(paragraph, area);
     Ok(())
 }

data/ext/ratatui_ruby/src/widgets/table.rs

@@ -5,25 +5,29 @@ use crate::style::{parse_block, parse_style};
 use magnus::{prelude::*, Error, Symbol, Value};
 use ratatui::{
     layout::{Constraint, Rect},
-    widgets::{Cell, Row, Table},
+    widgets::{Cell, Row, Table, TableState},
     Frame,
 };
 
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
     let header_val: Value = node.funcall("header", ())?;
     let rows_val: Value = node.funcall("rows", ())?;
     let rows_array = magnus::RArray::from_value(rows_val)
-        .ok_or_else(|| Error::new(magnus::exception::type_error(), "expected array for rows"))?;
+        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for rows"))?;
     let widths_val: Value = node.funcall("widths", ())?;
     let widths_array = magnus::RArray::from_value(widths_val)
-        .ok_or_else(|| Error::new(magnus::exception::type_error(), "expected array for widths"))?;
+        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for widths"))?;
+    let highlight_style_val: Value = node.funcall("highlight_style", ())?;
+    let highlight_symbol_val: Value = node.funcall("highlight_symbol", ())?;
+    let selected_row_val: Value = node.funcall("selected_row", ())?;
     let block_val: Value = node.funcall("block", ())?;
 
     let mut rows = Vec::new();
     for i in 0..rows_array.len() {
         let row_val: Value = rows_array.entry(i as isize)?;
         let row_array = magnus::RArray::from_value(row_val)
-            .ok_or_else(|| Error::new(magnus::exception::type_error(), "expected array for row"))?;
+            .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for row"))?;
 
         let mut cells = Vec::new();
         for j in 0..row_array.len() {
@@ -64,7 +68,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 
     if !header_val.is_nil() {
         let header_array = magnus::RArray::from_value(header_val).ok_or_else(|| {
-            Error::new(magnus::exception::type_error(), "expected array for header")
+            Error::new(ruby.exception_type_error(), "expected array for header")
         })?;
         let mut header_cells = Vec::new();
         for i in 0..header_array.len() {
@@ -89,7 +93,22 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         table = table.block(parse_block(block_val)?);
     }
 
-    frame.render_widget(table, area);
+    if !highlight_style_val.is_nil() {
+        table = table.row_highlight_style(parse_style(highlight_style_val)?);
+    }
+
+    if !highlight_symbol_val.is_nil() {
+        let symbol: String = highlight_symbol_val.funcall("to_s", ())?;
+        table = table.highlight_symbol(symbol);
+    }
+
+    let mut state = TableState::default();
+    if !selected_row_val.is_nil() {
+        let index: usize = selected_row_val.funcall("to_int", ())?;
+        state.select(Some(index));
+    }
+
+    frame.render_stateful_widget(table, area, &mut state);
     Ok(())
 }
 

data/ext/ratatui_ruby/src/widgets/tabs.rs

@@ -6,12 +6,13 @@ use magnus::{prelude::*, Error, Value};
 use ratatui::{layout::Rect, text::Line, widgets::Tabs, Frame};
 
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
     let titles_val: Value = node.funcall("titles", ())?;
     let selected_index: usize = node.funcall("selected_index", ())?;
     let block_val: Value = node.funcall("block", ())?;
 
     let titles_array = magnus::RArray::from_value(titles_val)
-        .ok_or_else(|| Error::new(magnus::exception::type_error(), "expected array for titles"))?;
+        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for titles"))?;
 
     let mut titles = Vec::new();
     for i in 0..titles_array.len() {

data/lib/ratatui_ruby/dsl.rb

@@ -46,6 +46,8 @@ module RatatuiRuby
 
     # 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)
 

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/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.2.0"
+  VERSION = "0.3.1"
 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"
@@ -16,6 +17,7 @@ require_relative "ratatui_ruby/schema/tabs"
 require_relative "ratatui_ruby/schema/bar_chart"
 require_relative "ratatui_ruby/schema/sparkline"
 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"
@@ -70,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)
 

data/mise.toml

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 [tools]
-ruby = "3.4.8"
+ruby = "4.0.0"
 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/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/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