ratatui_ruby 0.1.0 → 0.2.0

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

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+use crate::style::{parse_block, parse_style};
+use magnus::{prelude::*, Error, Value};
+use ratatui::{
+    layout::Rect,
+    widgets::calendar::{CalendarEventStore, Monthly},
+    Frame,
+};
+use std::convert::TryFrom;
+use time::{Date, Month};
+
+pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let year: i32 = node.funcall("year", ())?;
+    let month_u8: u8 = node.funcall("month", ())?;
+    let day_style_val: Value = node.funcall("day_style", ())?;
+    let header_style_val: Value = node.funcall("header_style", ())?;
+    let block_val: Value = node.funcall("block", ())?;
+
+    let month = Month::try_from(month_u8)
+        .map_err(|e| Error::new(magnus::exception::arg_error(), e.to_string()))?;
+
+    let date = Date::from_calendar_date(year, month, 1)
+        .map_err(|e| Error::new(magnus::exception::arg_error(), e.to_string()))?;
+
+    let mut calendar = Monthly::new(date, CalendarEventStore::default());
+
+    let header_style = if !header_style_val.is_nil() {
+        parse_style(header_style_val)?
+    } else {
+        ratatui::style::Style::default()
+    };
+    calendar = calendar
+        .show_month_header(header_style)
+        .show_weekdays_header(header_style);
+
+    if !day_style_val.is_nil() {
+        calendar = calendar.default_style(parse_style(day_style_val)?);
+    }
+
+    if !block_val.is_nil() {
+        calendar = calendar.block(parse_block(block_val)?);
+    }
+
+    frame.render_widget(calendar, area);
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ratatui::buffer::Buffer;
+    use ratatui::widgets::Widget;
+
+    #[test]
+    fn test_calendar_rendering() {
+        let date = Date::from_calendar_date(2025, Month::December, 1).unwrap();
+        let calendar = Monthly::new(date, CalendarEventStore::default())
+            .show_month_header(ratatui::style::Style::default());
+        let mut buf = Buffer::empty(Rect::new(0, 0, 40, 20));
+        calendar.render(Rect::new(0, 0, 40, 20), &mut buf);
+        let mut content = String::new();
+        for y in 0..20 {
+            for x in 0..40 {
+                content.push_str(buf.get(x, y).symbol());
+            }
+            content.push('\n');
+        }
+        assert!(
+            content.contains("December"),
+            "Content did not contain December: \n{}",
+            content
+        );
+        assert!(
+            content.contains("2025"),
+            "Content did not contain 2025: \n{}",
+            content
+        );
+    }
+}

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

@@ -0,0 +1,253 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+use crate::style::{parse_block, parse_style};
+use magnus::{prelude::*, Error, Symbol, Value};
+use ratatui::{
+    layout::Rect,
+    symbols,
+    text::Span,
+    widgets::{Axis, Chart, Dataset, GraphType},
+    Frame,
+};
+
+pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    let class = node.class();
+    let class_name = unsafe { class.name() };
+
+    if class_name == "RatatuiRuby::LineChart" {
+        return render_line_chart(frame, area, node);
+    }
+
+    let datasets_val: magnus::RArray = node.funcall("datasets", ())?;
+    let x_axis_val: Value = node.funcall("x_axis", ())?;
+    let y_axis_val: Value = node.funcall("y_axis", ())?;
+    let block_val: Value = node.funcall("block", ())?;
+    let style_val: Value = node.funcall("style", ())?;
+
+    let mut datasets = Vec::new();
+    // We need to keep the data alive until the chart is rendered
+    let mut data_storage: Vec<Vec<(f64, f64)>> = Vec::new();
+
+    for i in 0..datasets_val.len() {
+        let ds_val: Value = datasets_val.entry(i as isize)?;
+        let data_array: magnus::RArray = ds_val.funcall("data", ())?;
+
+        let mut points = Vec::new();
+        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")
+            })?;
+            let x: f64 = point_array.entry(0)?;
+            let y: f64 = point_array.entry(1)?;
+            points.push((x, y));
+        }
+        data_storage.push(points);
+    }
+
+    for (i, points) in data_storage.iter().enumerate() {
+        let ds_val: Value = datasets_val.entry(i as isize)?;
+        let name: String = ds_val.funcall("name", ())?;
+        let marker_sym: Symbol = ds_val.funcall("marker", ())?;
+        let graph_type_sym: Symbol = ds_val.funcall("graph_type", ())?;
+
+        let marker = match marker_sym.to_string().as_str() {
+            "dot" => symbols::Marker::Dot,
+            "braille" => symbols::Marker::Braille,
+            "block" => symbols::Marker::Block,
+            "bar" => symbols::Marker::Bar,
+            _ => symbols::Marker::Dot,
+        };
+
+        let graph_type = match graph_type_sym.to_string().as_str() {
+            "line" => GraphType::Line,
+            "scatter" => GraphType::Scatter,
+            _ => GraphType::Line,
+        };
+
+        let mut ds_style = ratatui::style::Style::default();
+        let color_val: Value = ds_val.funcall("color", ())?;
+        if !color_val.is_nil() {
+            let color_str: String = color_val.funcall("to_s", ())?;
+            if let Some(color) = crate::style::parse_color(&color_str) {
+                ds_style = ds_style.fg(color);
+            }
+        }
+
+        let ds = Dataset::default()
+            .name(name)
+            .marker(marker)
+            .graph_type(graph_type)
+            .style(ds_style)
+            .data(points);
+        datasets.push(ds);
+    }
+
+    let x_axis = parse_axis(x_axis_val)?;
+    let y_axis = parse_axis(y_axis_val)?;
+
+    let mut chart = Chart::new(datasets).x_axis(x_axis).y_axis(y_axis);
+
+    if !block_val.is_nil() {
+        chart = chart.block(parse_block(block_val)?);
+    }
+
+    if !style_val.is_nil() {
+        chart = chart.style(parse_style(style_val)?);
+    }
+
+    frame.render_widget(chart, area);
+    Ok(())
+}
+
+fn parse_axis(axis_val: Value) -> Result<Axis<'static>, Error> {
+    let title: String = axis_val.funcall("title", ())?;
+    let bounds_val: magnus::RArray = axis_val.funcall("bounds", ())?;
+    let labels_val: magnus::RArray = axis_val.funcall("labels", ())?;
+    let style_val: Value = axis_val.funcall("style", ())?;
+
+    let bounds: [f64; 2] = [bounds_val.entry(0)?, bounds_val.entry(1)?];
+
+    let mut labels = Vec::new();
+    for i in 0..labels_val.len() {
+        let label: String = labels_val.entry(i as isize)?;
+        labels.push(Span::from(label));
+    }
+
+    let mut axis = Axis::default().title(title).bounds(bounds).labels(labels);
+
+    if !style_val.is_nil() {
+        axis = axis.style(parse_style(style_val)?);
+    }
+
+    Ok(axis)
+}
+
+fn render_line_chart(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+    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", ())?;
+    let y_bounds_val: magnus::RArray = node.funcall("y_bounds", ())?;
+    let block_val: Value = node.funcall("block", ())?;
+
+    let mut datasets = Vec::new();
+    let mut data_storage: Vec<Vec<(f64, f64)>> = Vec::new();
+
+    for i in 0..datasets_val.len() {
+        let ds_val: Value = datasets_val.entry(i as isize)?;
+        let data_array: magnus::RArray = ds_val.funcall("data", ())?;
+
+        let mut points = Vec::new();
+        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")
+            })?;
+            let x: f64 = point_array.entry(0)?;
+            let y: f64 = point_array.entry(1)?;
+            points.push((x, y));
+        }
+        data_storage.push(points);
+    }
+
+    for (i, points) in data_storage.iter().enumerate() {
+        let ds_val: Value = datasets_val.entry(i as isize)?;
+        let name: String = ds_val.funcall("name", ())?;
+
+        let mut ds_style = ratatui::style::Style::default();
+        let color_val: Value = ds_val.funcall("color", ())?;
+        let color_str: String = color_val.funcall("to_s", ())?;
+        if let Some(color) = crate::style::parse_color(&color_str) {
+            ds_style = ds_style.fg(color);
+        }
+
+        let ds = Dataset::default()
+            .name(name)
+            .marker(symbols::Marker::Braille)
+            .style(ds_style)
+            .data(points);
+        datasets.push(ds);
+    }
+
+    let mut x_labels = Vec::new();
+    for i in 0..x_labels_val.len() {
+        let label: String = x_labels_val.entry(i as isize)?;
+        x_labels.push(Span::from(label));
+    }
+
+    let mut y_labels = Vec::new();
+    for i in 0..y_labels_val.len() {
+        let label: String = y_labels_val.entry(i as isize)?;
+        y_labels.push(Span::from(label));
+    }
+
+    let y_bounds: [f64; 2] = [y_bounds_val.entry(0)?, y_bounds_val.entry(1)?];
+
+    let mut min_x = 0.0;
+    let mut max_x = 0.0;
+    let mut first = true;
+    for ds_data in &data_storage {
+        for (x, _) in ds_data {
+            if first {
+                min_x = *x;
+                max_x = *x;
+                first = false;
+            } else {
+                if *x < min_x {
+                    min_x = *x;
+                }
+                if *x > max_x {
+                    max_x = *x;
+                }
+            }
+        }
+    }
+    if min_x == max_x {
+        max_x = min_x + 1.0;
+    }
+
+    let x_axis = Axis::default().labels(x_labels).bounds([min_x, max_x]);
+    let y_axis = Axis::default().labels(y_labels).bounds(y_bounds);
+
+    let mut chart = Chart::new(datasets).x_axis(x_axis).y_axis(y_axis);
+    if !block_val.is_nil() {
+        chart = chart.block(parse_block(block_val)?);
+    }
+
+    frame.render_widget(chart, area);
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use ratatui::buffer::Buffer;
+    use ratatui::widgets::Widget;
+
+    #[test]
+    fn test_chart_rendering() {
+        let data = vec![(0.0, 0.0), (1.0, 1.0)];
+        let datasets = vec![Dataset::default().name("TestDS").data(&data)];
+        let chart = Chart::new(datasets)
+            .x_axis(
+                Axis::default()
+                    .bounds([0.0, 1.0])
+                    .labels(vec!["XMIN".into(), "XMAX".into()]),
+            )
+            .y_axis(
+                Axis::default()
+                    .bounds([0.0, 1.0])
+                    .labels(vec!["YMIN".into(), "YMAX".into()]),
+            );
+        let mut buf = Buffer::empty(Rect::new(0, 0, 40, 20));
+        chart.render(Rect::new(0, 0, 40, 20), &mut buf);
+        assert!(buf.content().iter().any(|c| c.symbol() != " "));
+        let content = buf.content().iter().map(|c| c.symbol()).collect::<String>();
+        assert!(content.contains("XMIN"));
+        assert!(content.contains("XMAX"));
+        assert!(content.contains("YMIN"));
+        assert!(content.contains("YMAX"));
+        assert!(content.contains("TestDS"));
+    }
+}

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

@@ -1,8 +1,8 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-use crate::style::parse_block;
-use magnus::{prelude::*, Error, Value};
+use crate::style::{parse_block, parse_style};
+use magnus::{prelude::*, Error, TryConvert, Value};
 use ratatui::{
     layout::Rect,
     widgets::{List, ListState},
@@ -14,6 +14,9 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let items_array = magnus::RArray::from_value(items_val)
         .ok_or_else(|| Error::new(magnus::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", ())?;
+    let highlight_symbol_val: Value = node.funcall("highlight_symbol", ())?;
     let block_val: Value = node.funcall("block", ())?;
 
     let mut items = Vec::new();
@@ -22,13 +25,32 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         items.push(item);
     }
 
+    let symbol: String = if !highlight_symbol_val.is_nil() {
+        let s: String = String::try_convert(highlight_symbol_val)?;
+        s
+    } else {
+        String::new()
+    };
+
     let mut state = ListState::default();
     if !selected_index_val.is_nil() {
         let index: usize = selected_index_val.funcall("to_int", ())?;
         state.select(Some(index));
     }
 
-    let mut list = List::new(items).highlight_symbol(">> ");
+    let mut list = List::new(items);
+
+    if !highlight_symbol_val.is_nil() {
+        list = list.highlight_symbol(&symbol);
+    }
+
+    if !style_val.is_nil() {
+        list = list.style(parse_style(style_val)?);
+    }
+
+    if !highlight_style_val.is_nil() {
+        list = list.highlight_style(parse_style(highlight_style_val)?);
+    }
 
     if !block_val.is_nil() {
         list = list.block(parse_block(block_val)?);
@@ -47,7 +69,14 @@ mod tests {
     #[test]
     fn test_list_rendering() {
         let items = vec!["Item 1", "Item 2"];
-        let list = List::new(items).highlight_symbol(">> ");
+        let list = List::new(items)
+            .highlight_symbol(">> ")
+            .style(ratatui::style::Style::default().fg(ratatui::style::Color::White))
+            .highlight_style(
+                ratatui::style::Style::default()
+                    .fg(ratatui::style::Color::Yellow)
+                    .add_modifier(ratatui::style::Modifier::BOLD),
+            );
         let mut state = ListState::default();
         state.select(Some(1));
 
@@ -58,5 +87,13 @@ mod tests {
         let content = buf.content().iter().map(|c| c.symbol()).collect::<String>();
         assert!(content.contains("Item 1"));
         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!(buf
+            .get(0, 1)
+            .modifier
+            .contains(ratatui::style::Modifier::BOLD));
     }
 }

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

@@ -3,12 +3,13 @@
 
 pub mod barchart;
 pub mod block;
+pub mod calendar;
 pub mod canvas;
 pub mod center;
+pub mod chart;
 pub mod cursor;
 pub mod gauge;
 pub mod layout;
-pub mod linechart;
 pub mod list;
 pub mod overlay;
 pub mod paragraph;

data/lib/ratatui_ruby/dsl.rb

@@ -0,0 +1,62 @@
+# 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|
+      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/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/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.2.0"
 end

data/lib/ratatui_ruby.rb

@@ -15,12 +15,13 @@ 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/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"
@@ -84,4 +85,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"