ratatui_ruby 0.5.0 → 0.7.0

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

@@ -0,0 +1,137 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! `ListState` wrapper for exposing Ratatui's `ListState` to Ruby.
+//!
+//! This module provides `RubyListState`, a Magnus-wrapped struct that holds
+//! a `RefCell<ListState>` 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_index`, `offset`)
+//! are ignored in stateful mode.
+//!
+//! # Safety
+//!
+//! The `RefCell` is borrowed only during the `render_stateful_widget` call.
+//! The borrow is released immediately after to avoid double-borrow panics
+//! if a user inspects state inside a custom widget's render method.
+
+use magnus::{function, method, prelude::*, Error, Module, Ruby};
+use ratatui::widgets::ListState;
+use std::cell::RefCell;
+
+/// A wrapper around Ratatui's `ListState` exposed to Ruby.
+///
+/// This struct uses `RefCell` for interior mutability, allowing the state
+/// to be updated during rendering while remaining accessible from Ruby.
+#[magnus::wrap(class = "RatatuiRuby::ListState")]
+pub struct RubyListState {
+    inner: RefCell<ListState>,
+}
+
+impl RubyListState {
+    /// Creates a new `RubyListState` with optional initial selection.
+    ///
+    /// # Arguments
+    ///
+    /// * `selected` - Optional initial selection index
+    pub fn new(selected: Option<usize>) -> Self {
+        let mut state = ListState::default();
+        if let Some(idx) = selected {
+            state.select(Some(idx));
+        }
+        Self {
+            inner: RefCell::new(state),
+        }
+    }
+
+    /// Sets the selected index.
+    ///
+    /// Pass `nil` to deselect.
+    pub fn select(&self, index: Option<usize>) {
+        self.inner.borrow_mut().select(index);
+    }
+
+    /// Returns the currently selected index, or `nil` if nothing is selected.
+    pub fn selected(&self) -> Option<usize> {
+        self.inner.borrow().selected()
+    }
+
+    /// Returns the current scroll offset.
+    ///
+    /// This is the critical read-back method. After `render_stateful_widget`,
+    /// this returns the scroll position calculated by Ratatui to keep the
+    /// selection visible.
+    pub fn offset(&self) -> usize {
+        self.inner.borrow().offset()
+    }
+
+    /// Scrolls down by the given number of items.
+    pub fn scroll_down_by(&self, amount: u16) {
+        self.inner.borrow_mut().scroll_down_by(amount);
+    }
+
+    /// Scrolls up by the given number of items.
+    pub fn scroll_up_by(&self, amount: u16) {
+        self.inner.borrow_mut().scroll_up_by(amount);
+    }
+
+    /// Borrows the inner `ListState` mutably for rendering.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure the borrow is released before returning
+    /// control to Ruby to avoid double-borrow panics.
+    pub fn borrow_mut(&self) -> std::cell::RefMut<'_, ListState> {
+        self.inner.borrow_mut()
+    }
+}
+
+/// Registers the `ListState` class with Ruby.
+pub fn register(ruby: &Ruby, module: magnus::RModule) -> Result<(), Error> {
+    let class = module.define_class("ListState", ruby.class_object())?;
+    class.define_singleton_method("new", function!(RubyListState::new, 1))?;
+    class.define_method("select", method!(RubyListState::select, 1))?;
+    class.define_method("selected", method!(RubyListState::selected, 0))?;
+    class.define_method("offset", method!(RubyListState::offset, 0))?;
+    class.define_method("scroll_down_by", method!(RubyListState::scroll_down_by, 1))?;
+    class.define_method("scroll_up_by", method!(RubyListState::scroll_up_by, 1))?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_new_with_no_selection() {
+        let state = RubyListState::new(None);
+        assert_eq!(state.selected(), None);
+        assert_eq!(state.offset(), 0);
+    }
+
+    #[test]
+    fn test_new_with_selection() {
+        let state = RubyListState::new(Some(5));
+        assert_eq!(state.selected(), Some(5));
+    }
+
+    #[test]
+    fn test_select_and_deselect() {
+        let state = RubyListState::new(None);
+        state.select(Some(3));
+        assert_eq!(state.selected(), Some(3));
+        state.select(None);
+        assert_eq!(state.selected(), None);
+    }
+
+    #[test]
+    fn test_scroll_operations() {
+        let state = RubyListState::new(None);
+        state.scroll_down_by(5);
+        // Note: scroll operations affect offset, but the exact behavior
+        // depends on the list size which is determined during rendering
+    }
+}

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

@@ -13,11 +13,14 @@ pub mod gauge;
 pub mod layout;
 pub mod line_gauge;
 pub mod list;
+pub mod list_state;
 pub mod overlay;
 pub mod paragraph;
 pub mod ratatui_logo;
 pub mod ratatui_mascot;
 pub mod scrollbar;
+pub mod scrollbar_state;
 pub mod sparkline;
 pub mod table;
+pub mod table_state;
 pub mod tabs;

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

@@ -2,8 +2,9 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use crate::style::parse_block;
+use crate::widgets::scrollbar_state::RubyScrollbarState;
 use bumpalo::Bump;
-use magnus::{prelude::*, Error, Symbol, Value};
+use magnus::{prelude::*, Error, Symbol, TryConvert, Value};
 use ratatui::{
     layout::Rect,
     widgets::{Scrollbar, ScrollbarOrientation, ScrollbarState},
@@ -89,6 +90,97 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     Ok(())
 }
 
+/// Renders a Scrollbar with an external state object.
+///
+/// The State object is the single source of truth for position and `content_length`.
+/// Widget properties (`position`, `content_length`) are ignored.
+pub fn render_stateful(
+    frame: &mut Frame,
+    area: Rect,
+    node: Value,
+    state_wrapper: Value,
+) -> Result<(), Error> {
+    // Extract the RubyScrollbarState wrapper
+    let state: &RubyScrollbarState = TryConvert::try_convert(state_wrapper)?;
+
+    let orientation_sym: Symbol = node.funcall("orientation", ())?;
+    let thumb_symbol_val: Value = node.funcall("thumb_symbol", ())?;
+    let thumb_style_val: Value = node.funcall("thumb_style", ())?;
+    let track_symbol_val: Value = node.funcall("track_symbol", ())?;
+    let track_style_val: Value = node.funcall("track_style", ())?;
+    let begin_symbol_val: Value = node.funcall("begin_symbol", ())?;
+    let begin_style_val: Value = node.funcall("begin_style", ())?;
+    let end_symbol_val: Value = node.funcall("end_symbol", ())?;
+    let end_style_val: Value = node.funcall("end_style", ())?;
+    let style_val: Value = node.funcall("style", ())?;
+    let block_val: Value = node.funcall("block", ())?;
+
+    let mut scrollbar = Scrollbar::default();
+
+    scrollbar = match orientation_sym.to_string().as_str() {
+        "vertical_left" => scrollbar.orientation(ScrollbarOrientation::VerticalLeft),
+        "horizontal_bottom" | "horizontal" => {
+            scrollbar.orientation(ScrollbarOrientation::HorizontalBottom)
+        }
+        "horizontal_top" => scrollbar.orientation(ScrollbarOrientation::HorizontalTop),
+        _ => scrollbar.orientation(ScrollbarOrientation::VerticalRight),
+    };
+
+    // Hoisted strings to extend lifetime
+    let thumb_str: String;
+    let track_str: String;
+    let begin_str: String;
+    let end_str: String;
+
+    if !thumb_symbol_val.is_nil() {
+        thumb_str = thumb_symbol_val.funcall("to_s", ())?;
+        scrollbar = scrollbar.thumb_symbol(&thumb_str);
+    }
+    if !thumb_style_val.is_nil() {
+        scrollbar = scrollbar.thumb_style(crate::style::parse_style(thumb_style_val)?);
+    }
+    if !track_symbol_val.is_nil() {
+        track_str = track_symbol_val.funcall("to_s", ())?;
+        scrollbar = scrollbar.track_symbol(Some(&track_str));
+    }
+    if !track_style_val.is_nil() {
+        scrollbar = scrollbar.track_style(crate::style::parse_style(track_style_val)?);
+    }
+    if !begin_symbol_val.is_nil() {
+        begin_str = begin_symbol_val.funcall("to_s", ())?;
+        scrollbar = scrollbar.begin_symbol(Some(&begin_str));
+    }
+    if !begin_style_val.is_nil() {
+        scrollbar = scrollbar.begin_style(crate::style::parse_style(begin_style_val)?);
+    }
+    if !end_symbol_val.is_nil() {
+        end_str = end_symbol_val.funcall("to_s", ())?;
+        scrollbar = scrollbar.end_symbol(Some(&end_str));
+    }
+    if !end_style_val.is_nil() {
+        scrollbar = scrollbar.end_style(crate::style::parse_style(end_style_val)?);
+    }
+    if !style_val.is_nil() {
+        scrollbar = scrollbar.style(crate::style::parse_style(style_val)?);
+    }
+
+    // Borrow the inner ScrollbarState, render, and release the borrow immediately
+    {
+        let mut inner_state = state.borrow_mut();
+        if block_val.is_nil() {
+            frame.render_stateful_widget(scrollbar, area, &mut inner_state);
+        } else {
+            let bump = Bump::new();
+            let block = parse_block(block_val, &bump)?;
+            let inner_area = block.inner(area);
+            frame.render_widget(block, area);
+            frame.render_stateful_widget(scrollbar, inner_area, &mut inner_state);
+        }
+    }
+
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

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