ratatui_ruby 0.4.0 → 0.6.0

data/ext/ratatui_ruby/src/frame.rs

@@ -0,0 +1,227 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Frame wrapper for exposing Ratatui's Frame to Ruby.
+//!
+//! This module provides `RubyFrame`, a struct that wraps `ratatui::Frame` and exposes
+//! it to Ruby via Magnus. It enables explicit widget placement through `render_widget`,
+//! aligning `RatatuiRuby` with native Rust Ratatui patterns.
+//!
+//! # Safety
+//!
+//! `RubyFrame` uses raw pointer casting to store a `Frame` reference with an erased
+//! lifetime. This is safe because:
+//! 1. `RubyFrame` is only created within `Terminal::draw()` callbacks
+//! 2. `RubyFrame` is never returned from or stored beyond the callback scope
+//! 3. The Ruby block receiving `RubyFrame` completes before the callback returns
+//!
+//! The `'static` lifetime is a lie, but a safe one within these constraints.
+
+use crate::rendering;
+use crate::widgets;
+use magnus::{prelude::*, Error, Value};
+use ratatui::layout::Rect;
+use ratatui::Frame;
+use std::cell::UnsafeCell;
+use std::ptr::NonNull;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+/// A wrapper around Ratatui's `Frame` that can be exposed to Ruby.
+///
+/// This struct uses raw pointers to hold a mutable reference to the frame,
+/// which is valid only for the duration of the draw callback.
+///
+/// # Safety
+///
+/// We implement `Send` manually because:
+/// 1. `RubyFrame` is only created and used within a single `Terminal::draw()` callback
+/// 2. The Ruby VM is single-threaded (GVL), so the frame pointer is never accessed
+///    from multiple threads simultaneously
+/// 3. `RubyFrame` never escapes the draw callback scope
+///
+/// The `active` flag provides runtime safety by preventing use after the draw
+/// callback completes. Without this, a user could store the frame and cause
+/// undefined behavior by accessing it after the underlying pointer is invalid.
+#[magnus::wrap(class = "RatatuiRuby::Frame")]
+pub struct RubyFrame {
+    /// Pointer to the underlying frame. Valid only during the draw callback.
+    inner: UnsafeCell<NonNull<Frame<'static>>>,
+    /// Shared flag to invalidate the frame when the block finishes.
+    /// Set to `true` during draw, `false` immediately after yield returns.
+    active: Arc<AtomicBool>,
+}
+
+// SAFETY: RubyFrame is only used within Terminal::draw() callbacks, which are
+// single-threaded. The Ruby VM's GVL ensures no concurrent access.
+unsafe impl Send for RubyFrame {}
+
+impl RubyFrame {
+    /// Creates a new `RubyFrame` wrapping the given frame reference.
+    ///
+    /// # Arguments
+    ///
+    /// * `frame` - Mutable reference to the underlying Ratatui frame
+    /// * `active` - Shared atomic flag that controls frame validity
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that:
+    /// 1. The `RubyFrame` does not outlive the frame reference
+    /// 2. No other mutable references to the frame exist while `RubyFrame` is in use
+    /// 3. The `active` flag is set to `false` after the draw callback completes
+    pub fn new(frame: &mut Frame<'_>, active: Arc<AtomicBool>) -> Self {
+        // SAFETY: We cast the frame pointer to 'static lifetime. This is safe because:
+        // - RubyFrame is only used within Terminal::draw() callbacks
+        // - The Ruby block completes before the callback returns
+        // - No reference to RubyFrame escapes the callback scope
+        let ptr = NonNull::from(frame);
+        let static_ptr: NonNull<Frame<'static>> =
+            // SAFETY: Lifetime erasure is safe within the draw callback scope.
+            // The frame pointer remains valid for the entire callback duration.
+            unsafe { std::mem::transmute(ptr) };
+
+        Self {
+            inner: UnsafeCell::new(static_ptr),
+            active,
+        }
+    }
+
+    /// Checks that the frame is still valid for use.
+    ///
+    /// Returns `Ok(())` if the frame can be used, or an error if the draw
+    /// callback has already completed.
+    fn ensure_active(&self) -> Result<(), Error> {
+        if self.active.load(Ordering::Relaxed) {
+            Ok(())
+        } else {
+            let ruby = magnus::Ruby::get().unwrap();
+            let module = ruby.define_module("RatatuiRuby")?;
+            let error_base = module.const_get::<_, magnus::RClass>("Error")?;
+            let error_class = error_base.const_get("Safety")?;
+            Err(Error::new(
+                error_class,
+                "Frame cannot be used outside of the draw block",
+            ))
+        }
+    }
+
+    /// Returns the terminal area as a Ruby `RatatuiRuby::Rect`.
+    ///
+    /// This mirrors `frame.area()` in Rust Ratatui.
+    pub fn area(&self) -> Result<Value, Error> {
+        self.ensure_active()?;
+        let ruby = magnus::Ruby::get().unwrap();
+
+        // SAFETY: The frame pointer is valid for the duration of the draw callback.
+        // We only read from the frame, which is safe with an immutable reference.
+        // The ensure_active() check above guarantees we're still in the callback.
+        let area = unsafe { (*self.inner.get()).as_ref().area() };
+
+        // Create a Ruby Rect object
+        let module = ruby.define_module("RatatuiRuby")?;
+        let class = module.const_get::<_, magnus::RClass>("Rect")?;
+        class.funcall("new", (area.x, area.y, area.width, area.height))
+    }
+
+    /// Renders a widget at the specified area.
+    ///
+    /// This mirrors `frame.render_widget(widget, area)` in Rust Ratatui.
+    ///
+    /// # Arguments
+    ///
+    /// * `widget` - A Ruby widget object (e.g., `RatatuiRuby::Paragraph`)
+    /// * `area` - A Ruby `Rect` or hash-like object with `x`, `y`, `width`, `height`
+    pub fn render_widget(&self, widget: Value, area: Value) -> Result<(), Error> {
+        self.ensure_active()?;
+
+        // Parse the Ruby area into a Rust Rect
+        let x: u16 = area.funcall("x", ())?;
+        let y: u16 = area.funcall("y", ())?;
+        let width: u16 = area.funcall("width", ())?;
+        let height: u16 = area.funcall("height", ())?;
+        let rect = Rect::new(x, y, width, height);
+
+        // SAFETY: The frame pointer is valid for the duration of the draw callback.
+        // We take a mutable reference which is safe because:
+        // 1. RubyFrame is only used within Terminal::draw() callbacks
+        // 2. Ruby's GVL ensures single-threaded access
+        // 3. No other code holds a reference to the frame during this call
+        // 4. ensure_active() above guarantees we're still in the callback
+        let frame = unsafe { (*self.inner.get()).as_mut() };
+
+        // Delegate to the existing render_node function
+        rendering::render_node(frame, rect, widget)
+    }
+
+    /// Renders a stateful widget at the specified area.
+    ///
+    /// This mirrors `frame.render_stateful_widget(widget, area, &mut state)` in Rust Ratatui.
+    /// The State object is the single source of truth for selection and offset.
+    /// Widget properties (`selected_index`, `selected_row`, `offset`) are ignored.
+    ///
+    /// # Arguments
+    ///
+    /// * `widget` - A Ruby widget object (e.g., `RatatuiRuby::List`)
+    /// * `area` - A Ruby `Rect`
+    /// * `state` - A Ruby state object (e.g., `RatatuiRuby::ListState`)
+    pub fn render_stateful_widget(
+        &self,
+        widget: Value,
+        area: Value,
+        state: Value,
+    ) -> Result<(), Error> {
+        self.ensure_active()?;
+        let ruby = magnus::Ruby::get().unwrap();
+
+        // Parse the Ruby area into a Rust Rect
+        let x: u16 = area.funcall("x", ())?;
+        let y: u16 = area.funcall("y", ())?;
+        let width: u16 = area.funcall("width", ())?;
+        let height: u16 = area.funcall("height", ())?;
+        let rect = Rect::new(x, y, width, height);
+
+        // SAFETY: The frame pointer is valid for the duration of the draw callback.
+        let frame = unsafe { (*self.inner.get()).as_mut() };
+
+        // SAFETY: Immediate conversion to owned string avoids GC-unsafe borrowed reference.
+        let widget_class = unsafe { widget.class().name() }.into_owned();
+        // SAFETY: Immediate conversion to owned string avoids GC-unsafe borrowed reference.
+        let state_class = unsafe { state.class().name() }.into_owned();
+
+        match (widget_class.as_str(), state_class.as_str()) {
+            ("RatatuiRuby::List", "RatatuiRuby::ListState") => {
+                widgets::list::render_stateful(frame, rect, widget, state)
+            }
+            ("RatatuiRuby::Table", "RatatuiRuby::TableState") => {
+                widgets::table::render_stateful(frame, rect, widget, state)
+            }
+            ("RatatuiRuby::Scrollbar", "RatatuiRuby::ScrollbarState") => {
+                widgets::scrollbar::render_stateful(frame, rect, widget, state)
+            }
+            _ => Err(Error::new(
+                ruby.exception_arg_error(),
+                format!("Unsupported widget/state combination: {widget_class} with {state_class}"),
+            )),
+        }
+    }
+
+    /// Sets the cursor position in the terminal.
+    ///
+    /// This mirrors `frame.set_cursor_position((x, y))` in Rust Ratatui.
+    /// Use this for text input fields to show the cursor at the correct location.
+    ///
+    /// # Arguments
+    ///
+    /// * `x` - Column position (0-indexed from left)
+    /// * `y` - Row position (0-indexed from top)
+    pub fn set_cursor_position(&self, x: u16, y: u16) -> Result<(), Error> {
+        self.ensure_active()?;
+
+        // SAFETY: The frame pointer is valid for the duration of the draw callback.
+        // ensure_active() above guarantees we're still in the callback.
+        let frame = unsafe { (*self.inner.get()).as_mut() };
+        frame.set_cursor_position((x, y));
+        Ok(())
+    }
+}

data/ext/ratatui_ruby/src/lib.rs

@@ -11,36 +11,97 @@
 #![allow(clippy::module_name_repetitions)]
 
 mod events;
+mod frame;
 mod rendering;
+mod string_width;
 mod style;
 mod terminal;
 mod text;
 mod widgets;
 
-use magnus::{function, Error, Module, Object, Value};
+use frame::RubyFrame;
+use magnus::{function, method, Error, Module, Object, Ruby, Value};
 use terminal::{init_terminal, restore_terminal, TERMINAL};
 
-fn draw(tree: Value) -> Result<(), Error> {
-    let ruby = magnus::Ruby::get().unwrap();
+/// Draw to the terminal.
+///
+/// Supports two calling conventions:
+/// - Legacy: `RatatuiRuby.draw(tree)` - Renders a widget tree to the full terminal area
+/// - New: `RatatuiRuby.draw { |frame| ... }` - Yields a Frame for explicit widget placement
+fn draw(args: &[Value]) -> Result<(), Error> {
+    let ruby = Ruby::get().unwrap();
+
+    // Parse arguments: check for optional tree argument
+    let tree: Option<Value> = if args.is_empty() {
+        None
+    } else if args.len() == 1 {
+        Some(args[0])
+    } else {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!(
+                "wrong number of arguments (given {}, expected 0..1)",
+                args.len()
+            ),
+        ));
+    };
+    let block_given = ruby.block_given();
+
+    // Validate: must have either tree or block, but not both
+    if tree.is_some() && block_given {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Cannot provide both a tree and a block to draw",
+        ));
+    }
+    if tree.is_none() && !block_given {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Must provide either a tree or a block to draw",
+        ));
+    }
+
     let mut term_lock = TERMINAL.lock().unwrap();
-    let mut render_error = None;
+    let mut render_error: Option<Error> = None;
+
+    // Helper closure to execute the draw callback logic for either terminal type
+    let mut draw_callback = |f: &mut ratatui::Frame<'_>| {
+        if block_given {
+            // New API: yield RubyFrame to block
+            // Create validity flag — set to true while the block is executing
+            let active = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(true));
+
+            let ruby_frame = RubyFrame::new(f, active.clone());
+            if let Err(e) = ruby.yield_value::<_, Value>(ruby_frame) {
+                render_error = Some(e);
+            }
+
+            // Invalidate frame immediately after block returns
+            // This prevents use-after-free if user stored the frame object
+            active.store(false, std::sync::atomic::Ordering::Relaxed);
+        } else if let Some(tree_value) = tree {
+            // Legacy API: render tree to full area
+            if let Err(e) = rendering::render_node(f, f.area(), tree_value) {
+                render_error = Some(e);
+            }
+        }
+    };
+
     if let Some(wrapper) = term_lock.as_mut() {
         match wrapper {
             terminal::TerminalWrapper::Crossterm(term) => {
-                term.draw(|f| {
-                    if let Err(e) = rendering::render_node(f, f.area(), tree) {
-                        render_error = Some(e);
-                    }
-                })
-                .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")?;
+                term.draw(&mut draw_callback)
+                    .map_err(|e| Error::new(error_class, e.to_string()))?;
             }
             terminal::TerminalWrapper::Test(term) => {
-                term.draw(|f| {
-                    if let Err(e) = rendering::render_node(f, f.area(), tree) {
-                        render_error = Some(e);
-                    }
-                })
-                .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")?;
+                term.draw(&mut draw_callback)
+                    .map_err(|e| Error::new(error_class, e.to_string()))?;
             }
         }
     } else {
@@ -59,15 +120,31 @@ fn init() -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let m = ruby.define_module("RatatuiRuby")?;
 
-
-
     m.define_module_function("_init_terminal", function!(init_terminal, 2))?;
     m.define_module_function("restore_terminal", function!(restore_terminal, 0))?;
-    m.define_module_function("draw", function!(draw, 1))?;
-    m.define_module_function("_poll_event", function!(events::poll_event, 0))?;
+    m.define_module_function("_draw", function!(draw, -1))?;
+
+    // Register Frame class
+    let frame_class = m.define_class("Frame", ruby.class_object())?;
+    frame_class.define_method("area", method!(RubyFrame::area, 0))?;
+    frame_class.define_method("render_widget", method!(RubyFrame::render_widget, 2))?;
+    frame_class.define_method(
+        "render_stateful_widget",
+        method!(RubyFrame::render_stateful_widget, 3),
+    )?;
+    frame_class.define_method(
+        "set_cursor_position",
+        method!(RubyFrame::set_cursor_position, 2),
+    )?;
+    m.define_module_function("_poll_event", function!(events::poll_event, 1))?;
     m.define_module_function("inject_test_event", function!(events::inject_test_event, 2))?;
     m.define_module_function("clear_events", function!(events::clear_events, 0))?;
 
+    // Register State classes
+    widgets::list_state::register(&ruby, m)?;
+    widgets::table_state::register(&ruby, m)?;
+    widgets::scrollbar_state::register(&ruby, m)?;
+
     // Test backend helpers
     m.define_module_function(
         "init_test_terminal",
@@ -81,23 +158,29 @@ fn init() -> Result<(), Error> {
         "get_cursor_position",
         function!(terminal::get_cursor_position, 0),
     )?;
-    m.define_module_function(
-        "_get_cell_at",
-        function!(terminal::get_cell_at, 2),
-    )?;
+    m.define_module_function("_get_cell_at", function!(terminal::get_cell_at, 2))?;
     m.define_module_function("resize_terminal", function!(terminal::resize_terminal, 2))?;
 
     // Register Layout.split on the Layout class
     let layout_class = m.const_get::<_, magnus::RClass>("Layout")?;
     layout_class.define_singleton_method("_split", function!(widgets::layout::split_layout, 4))?;
-    
+
     // Paragraph metrics
-    m.define_module_function("_paragraph_line_count", function!(widgets::paragraph::line_count, 2))?;
-    m.define_module_function("_paragraph_line_width", function!(widgets::paragraph::line_width, 1))?;
+    m.define_module_function(
+        "_paragraph_line_count",
+        function!(widgets::paragraph::line_count, 2),
+    )?;
+    m.define_module_function(
+        "_paragraph_line_width",
+        function!(widgets::paragraph::line_width, 1),
+    )?;
 
     // Tabs metrics
     m.define_module_function("_tabs_width", function!(widgets::tabs::width, 1))?;
 
+    // Text measurement
+    m.define_module_function("_text_width", function!(string_width::text_width, 1))?;
+
     Ok(())
 }
 

data/ext/ratatui_ruby/src/rendering.rs

@@ -22,7 +22,8 @@ pub fn render_node(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Err
         if let Some(arr) = RArray::from_value(commands) {
             for i in 0..arr.len() {
                 let ruby = magnus::Ruby::get().unwrap();
-                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 cmd: Value = arr.entry(index)?;
                 process_draw_command(frame.buffer_mut(), cmd)?;
             }
@@ -54,8 +55,10 @@ pub fn render_node(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Err
         "RatatuiRuby::Chart" | "RatatuiRuby::LineChart" => {
             widgets::chart::render(frame, area, node)?;
         }
-        "RatatuiRuby::RatatuiLogo" => widgets::ratatui_logo::render(frame, area, node)?,
-        "RatatuiRuby::RatatuiMascot" => widgets::ratatui_mascot::render_ratatui_mascot(frame, area, node)?,
+        "RatatuiRuby::RatatuiLogo" => widgets::ratatui_logo::render(frame, area, node),
+        "RatatuiRuby::RatatuiMascot" => {
+            widgets::ratatui_mascot::render_ratatui_mascot(frame, area, node)?;
+        }
         _ => {}
     }
     Ok(())
@@ -105,7 +108,8 @@ fn process_draw_command(buffer: &mut Buffer, cmd: Value) -> Result<(), Error> {
 
             if let Some(mods_array) = RArray::from_value(modifiers_val) {
                 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) = parse_modifier_str(&mod_str) {
                         style = style.add_modifier(modifier);

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);
+    }
+}