ratatui_ruby 0.4.0 → 0.6.0

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

@@ -0,0 +1,169 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! `ScrollbarState` wrapper for exposing Ratatui's `ScrollbarState` to Ruby.
+//!
+//! This module provides `RubyScrollbarState`, a Magnus-wrapped struct that holds
+//! a `RefCell<ScrollbarState>` for interior mutability during stateful rendering.
+
+use magnus::{function, method, prelude::*, Error, Module, Ruby};
+use ratatui::widgets::ScrollbarState;
+use std::cell::RefCell;
+
+/// A wrapper around Ratatui's `ScrollbarState` exposed to Ruby.
+///
+/// Ratatui's `ScrollbarState` doesn't expose getters for `position`, `content_length`,
+/// or `viewport_content_length`. We track these values internally.
+#[magnus::wrap(class = "RatatuiRuby::ScrollbarState")]
+pub struct RubyScrollbarState {
+    inner: RefCell<ScrollbarState>,
+    /// We store these values ourselves since Ratatui's `ScrollbarState`
+    /// doesn't expose getters for them.
+    position_val: RefCell<usize>,
+    content_len: RefCell<usize>,
+    viewport_len: RefCell<usize>,
+}
+
+impl RubyScrollbarState {
+    /// Creates a new `RubyScrollbarState` with the given content length.
+    pub fn new(content_length: usize) -> Self {
+        Self {
+            inner: RefCell::new(ScrollbarState::new(content_length)),
+            position_val: RefCell::new(0),
+            content_len: RefCell::new(content_length),
+            viewport_len: RefCell::new(0),
+        }
+    }
+
+    /// Returns the current scroll position.
+    pub fn position(&self) -> usize {
+        *self.position_val.borrow()
+    }
+
+    /// Sets the current scroll position.
+    pub fn set_position(&self, position: usize) {
+        *self.position_val.borrow_mut() = position;
+        let mut state = self.inner.borrow_mut();
+        *state = state.position(position);
+    }
+
+    /// Returns the total content length.
+    pub fn content_length(&self) -> usize {
+        *self.content_len.borrow()
+    }
+
+    /// Sets the total content length.
+    pub fn set_content_length(&self, length: usize) {
+        *self.content_len.borrow_mut() = length;
+        let mut state = self.inner.borrow_mut();
+        *state = state.content_length(length);
+    }
+
+    /// Returns the viewport content length.
+    pub fn viewport_content_length(&self) -> usize {
+        *self.viewport_len.borrow()
+    }
+
+    /// Sets the viewport content length.
+    pub fn set_viewport_content_length(&self, length: usize) {
+        *self.viewport_len.borrow_mut() = length;
+        let mut state = self.inner.borrow_mut();
+        *state = state.viewport_content_length(length);
+    }
+
+    /// Scrolls to the first position.
+    pub fn first(&self) {
+        *self.position_val.borrow_mut() = 0;
+        self.inner.borrow_mut().first();
+    }
+
+    /// Scrolls to the last position.
+    pub fn last(&self) {
+        let content_len = *self.content_len.borrow();
+        let new_pos = content_len.saturating_sub(1);
+        *self.position_val.borrow_mut() = new_pos;
+        self.inner.borrow_mut().last();
+    }
+
+    /// Scrolls to the next position.
+    pub fn next(&self) {
+        let content_len = *self.content_len.borrow();
+        let current = *self.position_val.borrow();
+        let new_pos = (current + 1).min(content_len.saturating_sub(1));
+        *self.position_val.borrow_mut() = new_pos;
+        self.inner.borrow_mut().next();
+    }
+
+    /// Scrolls to the previous position.
+    pub fn prev(&self) {
+        let current = *self.position_val.borrow();
+        let new_pos = current.saturating_sub(1);
+        *self.position_val.borrow_mut() = new_pos;
+        self.inner.borrow_mut().prev();
+    }
+
+    /// Borrows the inner `ScrollbarState` mutably for rendering.
+    pub fn borrow_mut(&self) -> std::cell::RefMut<'_, ScrollbarState> {
+        self.inner.borrow_mut()
+    }
+}
+
+/// Registers the `ScrollbarState` class with Ruby.
+pub fn register(ruby: &Ruby, module: magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("ScrollbarState", ruby.class_object())?;
+    class.define_singleton_method("new", function!(RubyScrollbarState::new, 1))?;
+    class.define_method("position", method!(RubyScrollbarState::position, 0))?;
+    class.define_method("position=", method!(RubyScrollbarState::set_position, 1))?;
+    class.define_method(
+        "content_length",
+        method!(RubyScrollbarState::content_length, 0),
+    )?;
+    class.define_method(
+        "content_length=",
+        method!(RubyScrollbarState::set_content_length, 1),
+    )?;
+    class.define_method(
+        "viewport_content_length",
+        method!(RubyScrollbarState::viewport_content_length, 0),
+    )?;
+    class.define_method(
+        "viewport_content_length=",
+        method!(RubyScrollbarState::set_viewport_content_length, 1),
+    )?;
+    class.define_method("first", method!(RubyScrollbarState::first, 0))?;
+    class.define_method("last", method!(RubyScrollbarState::last, 0))?;
+    class.define_method("next", method!(RubyScrollbarState::next, 0))?;
+    class.define_method("prev", method!(RubyScrollbarState::prev, 0))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_new_with_content_length() {
+        let state = RubyScrollbarState::new(100);
+        assert_eq!(state.content_length(), 100);
+        assert_eq!(state.position(), 0);
+    }
+
+    #[test]
+    fn test_position_navigation() {
+        let state = RubyScrollbarState::new(10);
+        state.next();
+        assert_eq!(state.position(), 1);
+        state.prev();
+        assert_eq!(state.position(), 0);
+    }
+
+    #[test]
+    fn test_first_and_last() {
+        let state = RubyScrollbarState::new(10);
+        state.set_position(5);
+        state.first();
+        assert_eq!(state.position(), 0);
+        state.last();
+        assert_eq!(state.position(), 9);
+    }
+}

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

@@ -1,10 +1,10 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-use crate::style::{parse_block, parse_style, parse_bar_set};
+use crate::style::{parse_bar_set, parse_block, parse_style};
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, RString, Value};
-use ratatui::{layout::Rect, widgets::Sparkline, widgets::RenderDirection, Frame};
+use ratatui::{layout::Rect, widgets::RenderDirection, widgets::Sparkline, Frame};
 
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let bump = Bump::new();
@@ -20,7 +20,8 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 
     let mut data_vec = Vec::new();
     for i in 0..data_val.len() {
-        let index = isize::try_from(i).map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
         let val: Value = data_val.entry(index)?;
         if val.is_nil() {
             data_vec.push(None);
@@ -100,22 +101,24 @@ mod tests {
     fn test_sparkline_absent_value_symbol() {
         // Data with absent (None) and present values: [Some(5), None, Some(8), None]
         let data = vec![Some(5), None, Some(8), None];
-        let sparkline = Sparkline::default()
-            .data(&data)
-            .absent_value_symbol("-");
+        let sparkline = Sparkline::default().data(&data).absent_value_symbol("-");
         let mut buf = Buffer::empty(Rect::new(0, 0, 4, 1));
         sparkline.render(Rect::new(0, 0, 4, 1), &mut buf);
-        
+
         // Collect all rendered symbols
         let symbols: Vec<&str> = buf.content().iter().map(|c| c.symbol()).collect();
-        
+
         // Check that we have 4 cells rendered
-        assert_eq!(symbols.len(), 4, "Should have 4 cells rendered for 4 data points");
-        
+        assert_eq!(
+            symbols.len(),
+            4,
+            "Should have 4 cells rendered for 4 data points"
+        );
+
         // Absent values (None) should render as "-"
         assert_eq!(symbols[1], "-", "Second value (None) should render as dash");
         assert_eq!(symbols[3], "-", "Fourth value (None) should render as dash");
-        
+
         // Present values should not be dashes
         assert_ne!(symbols[0], "-", "First value (Some(5)) should not be dash");
         assert_ne!(symbols[2], "-", "Third value (Some(8)) should not be dash");

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

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use crate::style::{parse_block, parse_style};
+use crate::widgets::table_state::RubyTableState;
 use bumpalo::Bump;
-use magnus::{prelude::*, Error, Symbol, Value};
+use magnus::{prelude::*, Error, Symbol, TryConvert, Value};
 use ratatui::{
     layout::{Constraint, Flex, Rect},
     widgets::{Cell, HighlightSpacing, Row, Table, TableState},
@@ -33,7 +34,8 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 
     let mut rows = Vec::new();
     for i in 0..rows_array.len() {
-        let index = isize::try_from(i).map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
         let row_val: Value = rows_array.entry(index)?;
         rows.push(parse_row(row_val)?);
     }
@@ -109,10 +111,121 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         state.select_column(Some(index));
     }
 
+    let offset_val: Value = node.funcall("offset", ())?;
+    if !offset_val.is_nil() {
+        let offset: usize = offset_val.funcall("to_int", ())?;
+        *state.offset_mut() = offset;
+    }
+
     frame.render_stateful_widget(table, area, &mut state);
     Ok(())
 }
 
+/// Renders a Table with an external state object.
+///
+/// This function ignores `selected_row`, `selected_column`, and `offset` from the widget.
+/// The State object is the single source of truth for selection and scroll position.
+pub fn render_stateful(
+    frame: &mut Frame,
+    area: Rect,
+    node: Value,
+    state_wrapper: Value,
+) -> Result<(), Error> {
+    let bump = Bump::new();
+    let ruby = magnus::Ruby::get().unwrap();
+
+    // Extract the RubyTableState wrapper
+    let state: &RubyTableState = TryConvert::try_convert(state_wrapper)?;
+
+    // Parse rows
+    let rows_value: Value = node.funcall("rows", ())?;
+    let rows_array = magnus::RArray::from_value(rows_value)
+        .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(ruby.exception_type_error(), "expected array for widths"))?;
+
+    let mut rows = Vec::new();
+    for i in 0..rows_array.len() {
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let row_val: Value = rows_array.entry(index)?;
+        rows.push(parse_row(row_val)?);
+    }
+
+    let constraints = parse_constraints(widths_array)?;
+
+    // Build table (ignoring selected_row, selected_column, offset — State is truth)
+    let header_val: Value = node.funcall("header", ())?;
+    let footer_val: Value = node.funcall("footer", ())?;
+    let highlight_style_val: Value = node.funcall("highlight_style", ())?;
+    let column_highlight_style_val: Value = node.funcall("column_highlight_style", ())?;
+    let cell_highlight_style_val: Value = node.funcall("cell_highlight_style", ())?;
+    let highlight_symbol_val: Value = node.funcall("highlight_symbol", ())?;
+    let block_val: Value = node.funcall("block", ())?;
+    let flex_sym: Symbol = node.funcall("flex", ())?;
+    let highlight_spacing_sym: Symbol = node.funcall("highlight_spacing", ())?;
+    let style_val: Value = node.funcall("style", ())?;
+    let column_spacing_val: Value = node.funcall("column_spacing", ())?;
+
+    let flex = match flex_sym.to_string().as_str() {
+        "start" => Flex::Start,
+        "center" => Flex::Center,
+        "end" => Flex::End,
+        "space_between" => Flex::SpaceBetween,
+        "space_around" => Flex::SpaceAround,
+        "space_evenly" => Flex::SpaceEvenly,
+        _ => Flex::Legacy,
+    };
+
+    let mut table = Table::new(rows, constraints).flex(flex);
+
+    let highlight_spacing = match highlight_spacing_sym.to_string().as_str() {
+        "always" => HighlightSpacing::Always,
+        "never" => HighlightSpacing::Never,
+        _ => HighlightSpacing::WhenSelected,
+    };
+    table = table.highlight_spacing(highlight_spacing);
+
+    if !header_val.is_nil() {
+        table = table.header(parse_row(header_val)?);
+    }
+    if !footer_val.is_nil() {
+        table = table.footer(parse_row(footer_val)?);
+    }
+    if !block_val.is_nil() {
+        table = table.block(parse_block(block_val, &bump)?);
+    }
+    if !highlight_style_val.is_nil() {
+        table = table.row_highlight_style(parse_style(highlight_style_val)?);
+    }
+    if !column_highlight_style_val.is_nil() {
+        table = table.column_highlight_style(parse_style(column_highlight_style_val)?);
+    }
+    if !cell_highlight_style_val.is_nil() {
+        table = table.cell_highlight_style(parse_style(cell_highlight_style_val)?);
+    }
+    if !highlight_symbol_val.is_nil() {
+        let symbol: String = highlight_symbol_val.funcall("to_s", ())?;
+        table = table.highlight_symbol(symbol);
+    }
+    if !style_val.is_nil() {
+        table = table.style(parse_style(style_val)?);
+    }
+    if !column_spacing_val.is_nil() {
+        let spacing: u16 = column_spacing_val.funcall("to_int", ())?;
+        table = table.column_spacing(spacing);
+    }
+
+    // Borrow the inner TableState, render, and release the borrow immediately
+    {
+        let mut inner_state = state.borrow_mut();
+        frame.render_stateful_widget(table, area, &mut inner_state);
+    }
+
+    Ok(())
+}
+
 fn parse_row(row_val: Value) -> Result<Row<'static>, Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let row_array = magnus::RArray::from_value(row_val)
@@ -120,7 +233,8 @@ fn parse_row(row_val: Value) -> Result<Row<'static>, Error> {
 
     let mut cells = Vec::new();
     for i in 0..row_array.len() {
-        let index = isize::try_from(i).map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
         let cell_val: Value = row_array.entry(index)?;
         cells.push(parse_cell(cell_val)?);
     }
@@ -159,7 +273,8 @@ fn parse_cell(cell_val: Value) -> Result<Cell<'static>, Error> {
         if let Some(mods_array) = magnus::RArray::from_value(modifiers_val) {
             let ruby = magnus::Ruby::get().unwrap();
             for i in 0..mods_array.len() {
-                let index = isize::try_from(i).map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+                let index = isize::try_from(i)
+                    .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
                 let mod_str: String = mods_array.entry::<String>(index)?;
                 if let Some(modifier) = crate::style::parse_modifier_str(&mod_str) {
                     style = style.add_modifier(modifier);
@@ -177,7 +292,8 @@ fn parse_constraints(widths_array: magnus::RArray) -> Result<Vec<Constraint>, Er
     let ruby = magnus::Ruby::get().unwrap();
     let mut constraints = Vec::new();
     for i in 0..widths_array.len() {
-        let index = isize::try_from(i).map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
         let constraint_obj: Value = widths_array.entry(index)?;
         let type_sym: Symbol = constraint_obj.funcall("type", ())?;
         let value_obj: Value = constraint_obj.funcall("value", ())?;

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

@@ -0,0 +1,121 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! `TableState` wrapper for exposing Ratatui's `TableState` to Ruby.
+//!
+//! This module provides `RubyTableState`, a Magnus-wrapped struct that holds
+//! a `RefCell<TableState>` for interior mutability during stateful rendering.
+//!
+//! # Design
+//!
+//! When using `render_stateful_widget`, the State object is the single source
+//! of truth for selection and offset. Widget properties (`selected_row`,
+//! `selected_column`, `offset`) are ignored in stateful mode.
+
+use magnus::{function, method, prelude::*, Error, Module, Ruby};
+use ratatui::widgets::TableState;
+use std::cell::RefCell;
+
+/// A wrapper around Ratatui's `TableState` exposed to Ruby.
+#[magnus::wrap(class = "RatatuiRuby::TableState")]
+pub struct RubyTableState {
+    inner: RefCell<TableState>,
+}
+
+impl RubyTableState {
+    /// Creates a new `RubyTableState` with optional initial selection.
+    pub fn new(selected: Option<usize>) -> Self {
+        let mut state = TableState::default();
+        if let Some(idx) = selected {
+            state.select(Some(idx));
+        }
+        Self {
+            inner: RefCell::new(state),
+        }
+    }
+
+    /// Sets the selected row index.
+    pub fn select(&self, index: Option<usize>) {
+        self.inner.borrow_mut().select(index);
+    }
+
+    /// Returns the currently selected row index.
+    pub fn selected(&self) -> Option<usize> {
+        self.inner.borrow().selected()
+    }
+
+    /// Sets the selected column index.
+    pub fn select_column(&self, index: Option<usize>) {
+        self.inner.borrow_mut().select_column(index);
+    }
+
+    /// Returns the currently selected column index.
+    pub fn selected_column(&self) -> Option<usize> {
+        self.inner.borrow().selected_column()
+    }
+
+    /// Returns the current scroll offset.
+    pub fn offset(&self) -> usize {
+        self.inner.borrow().offset()
+    }
+
+    /// Scrolls down by the given number of rows.
+    pub fn scroll_down_by(&self, amount: u16) {
+        self.inner.borrow_mut().scroll_down_by(amount);
+    }
+
+    /// Scrolls up by the given number of rows.
+    pub fn scroll_up_by(&self, amount: u16) {
+        self.inner.borrow_mut().scroll_up_by(amount);
+    }
+
+    /// Borrows the inner `TableState` mutably for rendering.
+    pub fn borrow_mut(&self) -> std::cell::RefMut<'_, TableState> {
+        self.inner.borrow_mut()
+    }
+}
+
+/// Registers the `TableState` class with Ruby.
+pub fn register(ruby: &Ruby, module: magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("TableState", ruby.class_object())?;
+    class.define_singleton_method("new", function!(RubyTableState::new, 1))?;
+    class.define_method("select", method!(RubyTableState::select, 1))?;
+    class.define_method("selected", method!(RubyTableState::selected, 0))?;
+    class.define_method("select_column", method!(RubyTableState::select_column, 1))?;
+    class.define_method(
+        "selected_column",
+        method!(RubyTableState::selected_column, 0),
+    )?;
+    class.define_method("offset", method!(RubyTableState::offset, 0))?;
+    class.define_method("scroll_down_by", method!(RubyTableState::scroll_down_by, 1))?;
+    class.define_method("scroll_up_by", method!(RubyTableState::scroll_up_by, 1))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_new_with_no_selection() {
+        let state = RubyTableState::new(None);
+        assert_eq!(state.selected(), None);
+        assert_eq!(state.selected_column(), None);
+        assert_eq!(state.offset(), 0);
+    }
+
+    #[test]
+    fn test_new_with_selection() {
+        let state = RubyTableState::new(Some(3));
+        assert_eq!(state.selected(), Some(3));
+    }
+
+    #[test]
+    fn test_column_selection() {
+        let state = RubyTableState::new(None);
+        state.select_column(Some(2));
+        assert_eq!(state.selected_column(), Some(2));
+        state.select_column(None);
+        assert_eq!(state.selected_column(), None);
+    }
+}

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

@@ -15,7 +15,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 
 use crate::text::parse_line;
 
-fn create_tabs<'a>(node: Value, bump: &'a Bump) -> Result<Tabs<'a>, Error> {
+fn create_tabs(node: Value, bump: &Bump) -> Result<Tabs<'_>, Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let titles_val: Value = node.funcall("titles", ())?;
     let selected_index: usize = node.funcall("selected_index", ())?;
@@ -30,7 +30,8 @@ fn create_tabs<'a>(node: Value, bump: &'a Bump) -> Result<Tabs<'a>, Error> {
 
     let mut titles = Vec::new();
     for i in 0..titles_array.len() {
-        let index = isize::try_from(i).map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
         let val: Value = titles_array.entry(index)?;
         if let Ok(line) = parse_line(val) {
             titles.push(line);
@@ -81,10 +82,11 @@ pub fn width(node: Value) -> Result<usize, Error> {
         .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array for titles"))?;
 
     let mut total_width = padding_left + padding_right;
-    
+
     let mut titles_count = 0;
     for i in 0..titles_array.len() {
-        let index = isize::try_from(i).map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
         let val: Value = titles_array.entry(index)?;
         let line_width = if let Ok(line) = parse_line(val) {
             line.width()
@@ -97,11 +99,11 @@ pub fn width(node: Value) -> Result<usize, Error> {
     }
 
     if titles_count > 1 {
-        let divider_width = if !divider_val.is_nil() {
+        let divider_width = if divider_val.is_nil() {
+            1 // Default divider is "|"
+        } else {
             let d: String = divider_val.funcall("to_s", ())?;
             ratatui::text::Span::raw(d).width()
-        } else {
-            1 // Default divider is "|"
         };
         total_width += (titles_count - 1) * divider_width;
     }
@@ -134,10 +136,8 @@ mod tests {
     fn test_tabs_highlight_style() {
         let titles = vec![Line::from("Tab1"), Line::from("Tab2")];
         let highlight_style = Style::default().fg(Color::Red).add_modifier(Modifier::BOLD);
-        let tabs = Tabs::new(titles)
-            .select(0)
-            .highlight_style(highlight_style);
-        
+        let tabs = Tabs::new(titles).select(0).highlight_style(highlight_style);
+
         let mut buf = Buffer::empty(Rect::new(0, 0, 15, 1));
         tabs.render(Rect::new(0, 0, 15, 1), &mut buf);
 

data/lib/ratatui_ruby/cell.rb

@@ -67,7 +67,7 @@ module RatatuiRuby
     #   Cell.symbol("X") # => #<RatatuiRuby::Cell symbol="X">
     #
     def self.symbol(symbol)
-      new(symbol: symbol, fg: nil, bg: nil, modifiers: [])
+      new(symbol:, fg: nil, bg: nil, modifiers: [])
     end
 
     # Alias for Rubyists who prefer a shorter name.
@@ -82,10 +82,10 @@ module RatatuiRuby
     # [bg] Symbol or String (nullable).
     # [modifiers] Array of Strings.
     def initialize(symbol: nil, char: nil, fg: nil, bg: nil, modifiers: [])
-      @symbol = symbol || char || " "
-      @fg = fg
-      @bg = bg
-      @modifiers = modifiers.freeze
+      @symbol = (symbol || char || " ").freeze
+      @fg = fg&.freeze
+      @bg = bg&.freeze
+      @modifiers = modifiers.map(&:freeze).freeze
       freeze
     end
 
@@ -149,7 +149,7 @@ module RatatuiRuby
       parts << "fg=#{fg.inspect}" if fg
       parts << "bg=#{bg.inspect}" if bg
       parts << "modifiers=#{modifiers.inspect}" unless modifiers.empty?
-      "#<#{self.class} #{parts.join(" ")}>"
+      "#<#{self.class} #{parts.join(' ')}>"
     end
 
     # Returns the cell's character.
@@ -160,7 +160,7 @@ module RatatuiRuby
     # Support for pattern matching.
     # Supports both <tt>:symbol</tt> and <tt>:char</tt> keys.
     def deconstruct_keys(keys)
-      { symbol: symbol, char: symbol, fg: fg, bg: bg, modifiers: modifiers }
+      { symbol:, char: symbol, fg:, bg:, modifiers: }
     end
   end
 end

data/lib/ratatui_ruby/event/key/character.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # Methods for handling printable characters.
+      module Character
+        # Returns true if the key represents a single printable character.
+        #
+        #   RatatuiRuby::Event::Key.new(code: "a").text?       # => true
+        #   RatatuiRuby::Event::Key.new(code: "enter").text?   # => false
+        #   RatatuiRuby::Event::Key.new(code: "space").text?   # => false ("space" is not 1 char, " " is)
+        def text?
+          @code.length == 1
+        end
+
+        # Returns the key as a printable character (if applicable).
+        #
+        # [Printable Characters]
+        #   Returns the character itself (e.g., <tt>"a"</tt>, <tt>"1"</tt>, <tt>" "</tt>).
+        # [Special Keys]
+        #   Returns <tt>nil</tt> (e.g., <tt>"enter"</tt>, <tt>"up"</tt>, <tt>"f1"</tt>).
+        #
+        #   RatatuiRuby::Event::Key.new(code: "a").char      # => "a"
+        #   RatatuiRuby::Event::Key.new(code: "enter").char  # => nil
+        def char
+          text? ? @code : nil
+        end
+      end
+    end
+  end
+end