ratatui_ruby 0.5.0 → 0.7.0

data/ext/ratatui_ruby/src/string_width.rs

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+use magnus::{prelude::*, Error, Value};
+
+/// Calculate the display width of a string in terminal cells.
+///
+/// Handles unicode correctly, including:
+/// - Regular ASCII characters: 1 cell each
+/// - CJK characters: 2 cells each (full-width)
+/// - Emoji: typically 2 cells each (varies by terminal)
+/// - Combining marks and zero-width characters: 0 cells
+///
+/// This uses the same `unicode-width` crate that Ratatui uses internally.
+///
+/// Returns the total display width in cells (not bytes or characters).
+pub fn text_width(string: Value) -> Result<usize, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    let s: String = String::try_convert(string).map_err(|_| {
+        Error::new(
+            ruby.exception_type_error(),
+            "expected a String or object that converts to String",
+        )
+    })?;
+
+    // Use unicode_width's width calculation.
+    // This is the same mechanism Ratatui uses internally for Paragraph.line_width().
+    let width = s
+        .chars()
+        .map(|c| unicode_width::UnicodeWidthChar::width(c).unwrap_or(0))
+        .sum();
+
+    Ok(width)
+}
+
+#[cfg(test)]
+mod tests {
+    use unicode_width::UnicodeWidthChar;
+
+    fn measure_width(s: &str) -> usize {
+        s.chars()
+            .map(|c| UnicodeWidthChar::width(c).unwrap_or(0))
+            .sum()
+    }
+
+    #[test]
+    fn test_ascii_width() {
+        // ASCII is 1 cell per character
+        assert_eq!(measure_width("hello"), 5);
+        assert_eq!(measure_width("Hello, World!"), 13);
+    }
+
+    #[test]
+    fn test_emoji_width() {
+        // Emoji typically take 2 cells
+        // 👍 is U+1F44D THUMBS UP SIGN, width 2
+        assert_eq!(measure_width("👍"), 2);
+        // 🌍 is U+1F30D EARTH GLOBE EUROPE-AFRICA, width 2
+        assert_eq!(measure_width("🌍"), 2);
+        // "Hello 👍" = 5 + 1 + 2 = 8
+        assert_eq!(measure_width("Hello 👍"), 8);
+    }
+
+    #[test]
+    fn test_cjk_width() {
+        // CJK characters are full-width, 2 cells each
+        // 你 (U+4F60) is width 2
+        assert_eq!(measure_width("你"), 2);
+        // 好 (U+597D) is width 2
+        assert_eq!(measure_width("好"), 2);
+        // "你好" should be 4
+        assert_eq!(measure_width("你好"), 4);
+    }
+
+    #[test]
+    fn test_mixed_width() {
+        // "a你b好" = 1 + 2 + 1 + 2 = 6
+        assert_eq!(measure_width("a你b好"), 6);
+    }
+
+    #[test]
+    fn test_empty_string() {
+        assert_eq!(measure_width(""), 0);
+    }
+
+    #[test]
+    fn test_spaces_and_punctuation() {
+        // Regular ASCII space and punctuation are 1 cell each
+        assert_eq!(measure_width("a b c"), 5);
+        assert_eq!(measure_width("!!!"), 3);
+    }
+
+    #[test]
+    fn test_combining_marks() {
+        // Zero-width marks don't add to width
+        // "a" + combining acute accent (U+0301)
+        let combining = "a\u{0301}";
+        assert_eq!(measure_width(combining), 1);
+    }
+}

data/ext/ratatui_ruby/src/terminal.rs

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use magnus::value::ReprValue;
-use magnus::Error;
+use magnus::{Error, Module};
 use ratatui::{
     backend::{CrosstermBackend, TestBackend},
     Terminal,
@@ -21,28 +21,32 @@ pub fn init_terminal(focus_events: bool, bracketed_paste: bool) -> Result<(), Er
     let ruby = magnus::Ruby::get().unwrap();
     let mut term_lock = TERMINAL.lock().unwrap();
     if term_lock.is_none() {
+        let module = ruby.define_module("RatatuiRuby")?;
+        let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+        let error_class = error_base.const_get("Terminal")?;
+
         ratatui::crossterm::terminal::enable_raw_mode()
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+            .map_err(|e| Error::new(error_class, e.to_string()))?;
         let mut stdout = io::stdout();
         ratatui::crossterm::execute!(
             stdout,
             ratatui::crossterm::terminal::EnterAlternateScreen,
             ratatui::crossterm::event::EnableMouseCapture
         )
-        .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+        .map_err(|e| Error::new(error_class, e.to_string()))?;
 
         if focus_events {
             ratatui::crossterm::execute!(stdout, ratatui::crossterm::event::EnableFocusChange)
-                .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+                .map_err(|e| Error::new(error_class, e.to_string()))?;
         }
         if bracketed_paste {
             ratatui::crossterm::execute!(stdout, ratatui::crossterm::event::EnableBracketedPaste)
-                .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+                .map_err(|e| Error::new(error_class, e.to_string()))?;
         }
 
         let backend = CrosstermBackend::new(stdout);
-        let terminal = Terminal::new(backend)
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+        let terminal =
+            Terminal::new(backend).map_err(|e| Error::new(error_class, e.to_string()))?;
         *term_lock = Some(TerminalWrapper::Crossterm(terminal));
     }
     Ok(())
@@ -52,8 +56,10 @@ pub fn init_test_terminal(width: u16, height: u16) -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let mut term_lock = TERMINAL.lock().unwrap();
     let backend = TestBackend::new(width, height);
-    let terminal = Terminal::new(backend)
-        .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+    let module = ruby.define_module("RatatuiRuby")?;
+    let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+    let error_class = error_base.const_get("Terminal")?;
+    let terminal = Terminal::new(backend).map_err(|e| Error::new(error_class, e.to_string()))?;
     *term_lock = Some(TerminalWrapper::Test(terminal));
     Ok(())
 }
@@ -93,8 +99,11 @@ pub fn get_buffer_content() -> Result<String, Error> {
         }
         Ok(result)
     } else {
+        let module = ruby.define_module("RatatuiRuby")?;
+        let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+        let error_class = error_base.const_get("Terminal")?;
         Err(Error::new(
-            ruby.exception_runtime_error(),
+            error_class,
             "Terminal is not initialized as TestBackend",
         ))
     }
@@ -104,13 +113,19 @@ pub fn get_cursor_position() -> Result<Option<(u16, u16)>, Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let mut term_lock = TERMINAL.lock().unwrap();
     if let Some(TerminalWrapper::Test(terminal)) = term_lock.as_mut() {
+        let module = ruby.define_module("RatatuiRuby")?;
+        let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+        let error_class = error_base.const_get("Terminal")?;
         let pos = terminal
             .get_cursor_position()
-            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+            .map_err(|e| Error::new(error_class, e.to_string()))?;
         Ok(Some(pos.into()))
     } else {
+        let module = ruby.define_module("RatatuiRuby")?;
+        let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+        let error_class = error_base.const_get("Terminal")?;
         Err(Error::new(
-            ruby.exception_runtime_error(),
+            error_class,
             "Terminal is not initialized as TestBackend",
         ))
     }
@@ -125,7 +140,10 @@ pub fn resize_terminal(width: u16, height: u16) -> Result<(), Error> {
             TerminalWrapper::Test(terminal) => {
                 terminal.backend_mut().resize(width, height);
                 if let Err(e) = terminal.resize(ratatui::layout::Rect::new(0, 0, width, height)) {
-                    return Err(Error::new(ruby.exception_runtime_error(), e.to_string()));
+                    let module = ruby.define_module("RatatuiRuby")?;
+                    let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+                    let error_class = error_base.const_get("Terminal")?;
+                    return Err(Error::new(error_class, e.to_string()));
                 }
             }
         }
@@ -148,14 +166,20 @@ pub fn get_cell_at(x: u16, y: u16) -> Result<magnus::RHash, Error> {
             hash.aset("modifiers", modifiers_to_value(cell.modifier))?;
             Ok(hash)
         } else {
+            let module = ruby.define_module("RatatuiRuby")?;
+            let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+            let error_class = error_base.const_get("Terminal")?;
             Err(Error::new(
-                ruby.exception_runtime_error(),
+                error_class,
                 format!("Coordinates ({x}, {y}) out of bounds"),
             ))
         }
     } else {
+        let module = ruby.define_module("RatatuiRuby")?;
+        let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+        let error_class = error_base.const_get("Terminal")?;
         Err(Error::new(
-            ruby.exception_runtime_error(),
+            error_class,
             "Terminal is not initialized as TestBackend",
         ))
     }

data/ext/ratatui_ruby/src/text.rs

@@ -90,7 +90,7 @@ pub fn parse_text(value: Value) -> Result<Vec<Line<'static>>, Error> {
 }
 
 /// Parses a Ruby Span object into a ratatui Span.
-fn parse_span(value: Value) -> Result<Span<'static>, Error> {
+pub fn parse_span(value: Value) -> Result<Span<'static>, Error> {
     let ruby = magnus::Ruby::get().unwrap();
 
     // Get class name
@@ -131,6 +131,8 @@ pub fn parse_line(value: Value) -> Result<Line<'static>, Error> {
 
     // Extract spans from the Ruby Line
     let spans_val: Value = value.funcall("spans", ())?;
+    // v0.7.0: Extract style from the Ruby Line
+    let style_val: Value = value.funcall("style", ())?;
 
     if spans_val.is_nil() {
         return Ok(Line::from(""));
@@ -164,11 +166,18 @@ pub fn parse_line(value: Value) -> Result<Line<'static>, Error> {
         }
     }
 
-    if spans.is_empty() {
-        Ok(Line::from(""))
+    let mut line = if spans.is_empty() {
+        Line::from("")
     } else {
-        Ok(Line::from(spans))
+        Line::from(spans)
+    };
+
+    // v0.7.0: Apply line-level style if present
+    if !style_val.is_nil() {
+        line = line.style(parse_style(style_val)?);
     }
+
+    Ok(line)
 }
 
 #[cfg(test)]

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

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use crate::style::{parse_bar_set, parse_block, parse_style};
+use crate::text::{parse_line, parse_span};
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, RArray, Symbol, Value};
 use ratatui::{
@@ -11,6 +12,7 @@ use ratatui::{
     Frame,
 };
 
+#[allow(clippy::too_many_lines)]
 pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let bump = Bump::new();
     let data_val: Value = node.funcall("data", ())?;
@@ -66,16 +68,32 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 
                 let label_val: Value = bar_obj.funcall("label", ())?;
                 if !label_val.is_nil() {
-                    let s: String = label_val.funcall("to_s", ())?;
-                    let s_ref = bump.alloc_str(&s) as &str;
-                    bar = bar.label(Line::from(s_ref));
+                    // Try to parse as Line (rich text)
+                    if let Ok(line) = parse_line(label_val) {
+                        bar = bar.label(line);
+                    } else if let Ok(span) = parse_span(label_val) {
+                        bar = bar.label(Line::from(vec![span]));
+                    } else {
+                        // Fallback to string
+                        let s: String = label_val.funcall("to_s", ())?;
+                        let s_ref = bump.alloc_str(&s) as &str;
+                        bar = bar.label(Line::from(s_ref));
+                    }
                 }
 
                 let text_val: Value = bar_obj.funcall("text_value", ())?;
                 if !text_val.is_nil() {
-                    let s: String = text_val.funcall("to_s", ())?;
-                    let s_ref = bump.alloc_str(&s) as &str;
-                    bar = bar.text_value(s_ref);
+                    // Try to parse as Line (rich text)
+                    if let Ok(line) = parse_line(text_val) {
+                        bar = bar.text_value(line);
+                    } else if let Ok(span) = parse_span(text_val) {
+                        bar = bar.text_value(Line::from(vec![span]));
+                    } else {
+                        // Fallback to string
+                        let s: String = text_val.funcall("to_s", ())?;
+                        let s_ref = bump.alloc_str(&s) as &str;
+                        bar = bar.text_value(s_ref);
+                    }
                 }
 
                 let style_val: Value = bar_obj.funcall("style", ())?;

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

@@ -57,7 +57,7 @@ pub fn render(frame: &mut Frame, area: ratatui::layout::Rect, node: Value) -> Re
             let class_name = unsafe { class.name() }.into_owned();
 
             match class_name.as_str() {
-                "RatatuiRuby::Shape::Line" => {
+                "RatatuiRuby::Widgets::Shape::Line" => {
                     let x1: f64 = shape_val.funcall("x1", ()).unwrap_or(0.0);
                     let y1: f64 = shape_val.funcall("y1", ()).unwrap_or(0.0);
                     let x2: f64 = shape_val.funcall("x2", ()).unwrap_or(0.0);
@@ -73,7 +73,7 @@ pub fn render(frame: &mut Frame, area: ratatui::layout::Rect, node: Value) -> Re
                         color,
                     });
                 }
-                "RatatuiRuby::Shape::Rectangle" => {
+                "RatatuiRuby::Widgets::Shape::Rectangle" => {
                     let x: f64 = shape_val.funcall("x", ()).unwrap_or(0.0);
                     let y: f64 = shape_val.funcall("y", ()).unwrap_or(0.0);
                     let width: f64 = shape_val.funcall("width", ()).unwrap_or(0.0);
@@ -89,7 +89,7 @@ pub fn render(frame: &mut Frame, area: ratatui::layout::Rect, node: Value) -> Re
                         color,
                     });
                 }
-                "RatatuiRuby::Shape::Circle" => {
+                "RatatuiRuby::Widgets::Shape::Circle" => {
                     let x: f64 = shape_val.funcall("x", ()).unwrap_or(0.0);
                     let y: f64 = shape_val.funcall("y", ()).unwrap_or(0.0);
                     let radius: f64 = shape_val.funcall("radius", ()).unwrap_or(0.0);
@@ -103,7 +103,7 @@ pub fn render(frame: &mut Frame, area: ratatui::layout::Rect, node: Value) -> Re
                         color,
                     });
                 }
-                "RatatuiRuby::Shape::Map" => {
+                "RatatuiRuby::Widgets::Shape::Map" => {
                     let color_val: Value = shape_val.funcall("color", ()).unwrap();
                     let color =
                         parse_color(&color_val.to_string()).unwrap_or(ratatui::style::Color::Reset);
@@ -114,7 +114,7 @@ pub fn render(frame: &mut Frame, area: ratatui::layout::Rect, node: Value) -> Re
                     };
                     ctx.draw(&Map { color, resolution });
                 }
-                "RatatuiRuby::Shape::Label" => {
+                "RatatuiRuby::Widgets::Shape::Label" => {
                     let x: f64 = shape_val.funcall("x", ()).unwrap_or(0.0);
                     let y: f64 = shape_val.funcall("y", ()).unwrap_or(0.0);
                     let text_val: Value = shape_val.funcall("text", ()).unwrap();

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

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use crate::style::{parse_block, parse_style};
+use crate::text::parse_span;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Value};
 use ratatui::{layout::Rect, widgets::Gauge, Frame};
@@ -17,8 +18,14 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let mut gauge = Gauge::default().ratio(ratio).use_unicode(use_unicode);
 
     if !label_val.is_nil() {
-        let label_str: String = label_val.funcall("to_s", ())?;
-        gauge = gauge.label(label_str);
+        // Try to parse as a Span (rich text)
+        if let Ok(span) = parse_span(label_val) {
+            gauge = gauge.label(span);
+        } else {
+            // Fallback to string
+            let label_str: String = label_val.funcall("to_s", ())?;
+            gauge = gauge.label(label_str);
+        }
     }
 
     if !style_val.is_nil() {

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

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use crate::style::{parse_block, parse_style};
+use crate::text::parse_span;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Value};
 use ratatui::{layout::Rect, widgets::LineGauge, Frame};
@@ -23,8 +24,14 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         .unfilled_symbol(&unfilled_symbol_val);
 
     if !label_val.is_nil() {
-        let label_str: String = label_val.funcall("to_s", ())?;
-        gauge = gauge.label(label_str);
+        // Try to parse as a Span (rich text)
+        if let Ok(span) = parse_span(label_val) {
+            gauge = gauge.label(span);
+        } else {
+            // Fallback to string
+            let label_str: String = label_val.funcall("to_s", ())?;
+            gauge = gauge.label(label_str);
+        }
     }
 
     if !style_val.is_nil() {

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

@@ -2,12 +2,14 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use crate::style::{parse_block, parse_style};
+use crate::text::{parse_line, parse_span};
+use crate::widgets::list_state::RubyListState;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Symbol, TryConvert, Value};
 use ratatui::{
     layout::Rect,
     text::Line,
-    widgets::{HighlightSpacing, List, ListState},
+    widgets::{HighlightSpacing, List, ListItem, ListState},
     Frame,
 };
 
@@ -27,11 +29,12 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     let scroll_padding_val: Value = node.funcall("scroll_padding", ())?;
     let block_val: Value = node.funcall("block", ())?;
 
-    let mut items: Vec<String> = Vec::new();
+    let mut items: Vec<ListItem> = Vec::new();
     for i in 0..items_array.len() {
         let index = isize::try_from(i)
             .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
-        let item: String = items_array.entry(index)?;
+        let item_val: Value = items_array.entry(index)?;
+        let item = parse_list_item(item_val)?;
         items.push(item);
     }
 
@@ -47,6 +50,12 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         state.select(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;
+    }
+
     let mut list = List::new(items);
 
     let highlight_spacing = match highlight_spacing_sym.to_string().as_str() {
@@ -101,6 +110,173 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     Ok(())
 }
 
+/// Renders a List with an external state object.
+///
+/// This function ignores `selected_index` 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 RubyListState wrapper
+    let state: &RubyListState = TryConvert::try_convert(state_wrapper)?;
+
+    // Build items
+    let items_val: Value = node.funcall("items", ())?;
+    let items_array = magnus::RArray::from_value(items_val)
+        .ok_or_else(|| Error::new(ruby.exception_type_error(), "expected array"))?;
+
+    let mut items: Vec<ListItem> = Vec::new();
+    for i in 0..items_array.len() {
+        let index = isize::try_from(i)
+            .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+        let item_val: Value = items_array.entry(index)?;
+        let item = parse_list_item(item_val)?;
+        items.push(item);
+    }
+
+    // Build widget (ignoring selected_index and offset — State is truth)
+    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 repeat_highlight_symbol_val: Value = node.funcall("repeat_highlight_symbol", ())?;
+    let highlight_spacing_sym: Symbol = node.funcall("highlight_spacing", ())?;
+    let direction_val: Value = node.funcall("direction", ())?;
+    let scroll_padding_val: Value = node.funcall("scroll_padding", ())?;
+    let block_val: Value = node.funcall("block", ())?;
+
+    let symbol: String = if highlight_symbol_val.is_nil() {
+        String::new()
+    } else {
+        String::try_convert(highlight_symbol_val)?
+    };
+
+    let mut list = List::new(items);
+
+    let highlight_spacing = match highlight_spacing_sym.to_string().as_str() {
+        "always" => HighlightSpacing::Always,
+        "never" => HighlightSpacing::Never,
+        _ => HighlightSpacing::WhenSelected,
+    };
+    list = list.highlight_spacing(highlight_spacing);
+
+    if !highlight_symbol_val.is_nil() {
+        list = list.highlight_symbol(Line::from(symbol));
+    }
+
+    if !repeat_highlight_symbol_val.is_nil() {
+        let repeat: bool = TryConvert::try_convert(repeat_highlight_symbol_val)?;
+        list = list.repeat_highlight_symbol(repeat);
+    }
+
+    if !direction_val.is_nil() {
+        let direction_sym: magnus::Symbol = TryConvert::try_convert(direction_val)?;
+        let direction_str = direction_sym.name().unwrap();
+        match direction_str.as_ref() {
+            "top_to_bottom" => list = list.direction(ratatui::widgets::ListDirection::TopToBottom),
+            "bottom_to_top" => list = list.direction(ratatui::widgets::ListDirection::BottomToTop),
+            _ => {
+                return Err(Error::new(
+                    ruby.exception_arg_error(),
+                    "direction must be :top_to_bottom or :bottom_to_top",
+                ))
+            }
+        }
+    }
+
+    if !scroll_padding_val.is_nil() {
+        let padding: usize = TryConvert::try_convert(scroll_padding_val)?;
+        list = list.scroll_padding(padding);
+    }
+
+    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, &bump)?);
+    }
+
+    // Borrow the inner ListState, render, and release the borrow immediately
+    {
+        let mut inner_state = state.borrow_mut();
+        frame.render_stateful_widget(list, area, &mut inner_state);
+    }
+    // Borrow is now released
+
+    Ok(())
+}
+
+/// Parses a Ruby list item into a ratatui `ListItem`.
+///
+/// Accepts:
+/// - `String`: Plain text item
+/// - `Text::Span`: A single styled fragment
+/// - `Text::Line`: A line composed of multiple spans
+/// - `RatatuiRuby::ListItem`: A `ListItem` object with content and optional style
+fn parse_list_item(value: Value) -> Result<ListItem<'static>, Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+
+    // Check if it's a RatatuiRuby::ListItem
+    if let Ok(class_obj) = value.funcall::<_, _, Value>("class", ()) {
+        if let Ok(class_name) = class_obj.funcall::<_, _, String>("name", ()) {
+            if class_name.contains("ListItem") {
+                // Extract content and style from the ListItem
+                let content_val: Value = value.funcall("content", ())?;
+                let style_val: Value = value.funcall("style", ())?;
+
+                // Parse content as a Line
+                let line = if let Ok(s) = String::try_convert(content_val) {
+                    Line::from(s)
+                } else if let Ok(line) = parse_line(content_val) {
+                    line
+                } else if let Ok(span) = parse_span(content_val) {
+                    Line::from(vec![span])
+                } else {
+                    Line::from("")
+                };
+
+                // Parse and apply style if present
+                let mut item = ListItem::new(line);
+                if !style_val.is_nil() {
+                    item = item.style(parse_style(style_val)?);
+                }
+                return Ok(item);
+            }
+        }
+    }
+
+    // Try as String
+    if let Ok(s) = String::try_convert(value) {
+        return Ok(ListItem::new(Line::from(s)));
+    }
+
+    // Try as Line
+    if let Ok(line) = parse_line(value) {
+        return Ok(ListItem::new(line));
+    }
+
+    // Try as Span
+    if let Ok(span) = parse_span(value) {
+        return Ok(ListItem::new(Line::from(vec![span])));
+    }
+
+    // Fallback
+    Err(Error::new(
+        ruby.exception_type_error(),
+        "expected String, Text::Span, Text::Line, or ListItem",
+    ))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;