ratatui_ruby 1.0.0.pre.beta.2 → 1.0.0

data/ext/ratatui_ruby/src/terminal/query.rs

@@ -0,0 +1,338 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Terminal query trait and implementations.
+//!
+//! This module provides a compiler-enforced interface for querying terminal state.
+//! All queries go through `TerminalQuery` trait which has two implementations:
+//! - `LiveTerminal`: Used outside draw, queries actual terminal
+//! - `DrawSnapshot`: Used during draw, queries pre-captured snapshot
+
+use ratatui::buffer::Cell;
+use ratatui::layout::Rect;
+
+/// All terminal queries MUST go through this trait.
+/// Compiler enforces both implementations when adding new queries.
+pub trait TerminalQuery {
+    fn size(&self) -> Rect;
+    fn viewport_area(&self) -> Rect;
+    fn is_test_mode(&self) -> bool;
+    fn cursor_position(&self) -> Option<(u16, u16)>;
+    fn cell_at(&self, x: u16, y: u16) -> Option<Cell>;
+}
+
+/// Snapshot of terminal state captured before draw.
+/// Answers queries during draw without accessing terminal.
+#[derive(Clone)]
+pub struct DrawSnapshot {
+    pub size: Rect,
+    pub viewport_area: Rect,
+    pub is_test_mode: bool,
+    pub cursor_position: Option<(u16, u16)>,
+    pub buffer: Option<ratatui::buffer::Buffer>,
+}
+
+impl DrawSnapshot {
+    /// Capture snapshot from a `TerminalWrapper`.
+    pub fn capture(wrapper: &mut super::wrapper::TerminalWrapper) -> Self {
+        match wrapper {
+            super::wrapper::TerminalWrapper::Crossterm(t) => {
+                let size = t.size().unwrap_or_default();
+                let viewport = t.get_frame().area();
+                Self {
+                    size: Rect::new(0, 0, size.width, size.height),
+                    viewport_area: viewport,
+                    is_test_mode: false,
+                    cursor_position: None,
+                    buffer: None,
+                }
+            }
+            super::wrapper::TerminalWrapper::Test(t) => {
+                let size = t.size().unwrap_or_default();
+                let viewport = t.get_frame().area();
+                let cursor = t.get_cursor_position().ok().map(Into::into);
+                let buffer = t.backend().buffer().clone();
+                Self {
+                    size: Rect::new(0, 0, size.width, size.height),
+                    viewport_area: viewport,
+                    is_test_mode: true,
+                    cursor_position: cursor,
+                    buffer: Some(buffer),
+                }
+            }
+        }
+    }
+}
+
+impl TerminalQuery for DrawSnapshot {
+    fn size(&self) -> Rect {
+        self.size
+    }
+    fn viewport_area(&self) -> Rect {
+        self.viewport_area
+    }
+    fn is_test_mode(&self) -> bool {
+        self.is_test_mode
+    }
+    fn cursor_position(&self) -> Option<(u16, u16)> {
+        self.cursor_position
+    }
+    fn cell_at(&self, x: u16, y: u16) -> Option<Cell> {
+        self.buffer.as_ref()?.cell((x, y)).cloned()
+    }
+}
+
+/// Live queries against actual terminal (outside draw).
+/// Uses interior mutability since ratatui's API requires &mut for some queries.
+pub struct LiveTerminal<'a>(std::cell::RefCell<&'a mut super::wrapper::TerminalWrapper>);
+
+impl<'a> LiveTerminal<'a> {
+    pub fn new(wrapper: &'a mut super::wrapper::TerminalWrapper) -> Self {
+        Self(std::cell::RefCell::new(wrapper))
+    }
+}
+
+impl TerminalQuery for LiveTerminal<'_> {
+    fn size(&self) -> Rect {
+        match *self.0.borrow() {
+            super::wrapper::TerminalWrapper::Crossterm(ref t) => {
+                let s = t.size().unwrap_or_default();
+                Rect::new(0, 0, s.width, s.height)
+            }
+            super::wrapper::TerminalWrapper::Test(ref t) => {
+                let s = t.size().unwrap_or_default();
+                Rect::new(0, 0, s.width, s.height)
+            }
+        }
+    }
+
+    fn viewport_area(&self) -> Rect {
+        match *self.0.borrow_mut() {
+            super::wrapper::TerminalWrapper::Crossterm(ref mut t) => t.get_frame().area(),
+            super::wrapper::TerminalWrapper::Test(ref mut t) => t.get_frame().area(),
+        }
+    }
+    fn is_test_mode(&self) -> bool {
+        matches!(*self.0.borrow(), super::wrapper::TerminalWrapper::Test(_))
+    }
+    fn cursor_position(&self) -> Option<(u16, u16)> {
+        match *self.0.borrow_mut() {
+            super::wrapper::TerminalWrapper::Test(ref mut t) => {
+                t.get_cursor_position().ok().map(Into::into)
+            }
+            super::wrapper::TerminalWrapper::Crossterm(_) => None,
+        }
+    }
+    fn cell_at(&self, x: u16, y: u16) -> Option<Cell> {
+        match &*self.0.borrow() {
+            super::wrapper::TerminalWrapper::Test(t) => t.backend().buffer().cell((x, y)).cloned(),
+            super::wrapper::TerminalWrapper::Crossterm(_) => None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Test: TerminalQuery trait can be implemented by a simple struct
+    struct MockQuery {
+        size: Rect,
+    }
+
+    impl TerminalQuery for MockQuery {
+        fn size(&self) -> Rect {
+            self.size
+        }
+        fn viewport_area(&self) -> Rect {
+            Rect::default()
+        }
+        fn is_test_mode(&self) -> bool {
+            false
+        }
+        fn cursor_position(&self) -> Option<(u16, u16)> {
+            None
+        }
+        fn cell_at(&self, _x: u16, _y: u16) -> Option<Cell> {
+            None
+        }
+    }
+
+    #[test]
+    fn test_trait_can_be_implemented() {
+        let query = MockQuery {
+            size: Rect::new(0, 0, 80, 24),
+        };
+        assert_eq!(query.size(), Rect::new(0, 0, 80, 24));
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_size() {
+        let snapshot = super::DrawSnapshot {
+            size: Rect::new(0, 0, 120, 40),
+            viewport_area: Rect::new(0, 0, 120, 40),
+            is_test_mode: false,
+            cursor_position: None,
+            buffer: None,
+        };
+        assert_eq!(snapshot.size(), Rect::new(0, 0, 120, 40));
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_viewport_area() {
+        let snapshot = super::DrawSnapshot {
+            size: Rect::new(0, 0, 120, 40),
+            viewport_area: Rect::new(5, 10, 80, 20), // Different from size!
+            is_test_mode: false,
+            cursor_position: None,
+            buffer: None,
+        };
+        // This should return the stored viewport_area, not Rect::default()
+        assert_eq!(snapshot.viewport_area(), Rect::new(5, 10, 80, 20));
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_is_test_mode() {
+        let snapshot = super::DrawSnapshot {
+            size: Rect::default(),
+            viewport_area: Rect::default(),
+            is_test_mode: true, // TRUE!
+            cursor_position: None,
+            buffer: None,
+        };
+        assert!(snapshot.is_test_mode());
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_cursor_position() {
+        let snapshot = super::DrawSnapshot {
+            size: Rect::default(),
+            viewport_area: Rect::default(),
+            is_test_mode: false,
+            cursor_position: Some((15, 20)), // Not None!
+            buffer: None,
+        };
+        assert_eq!(snapshot.cursor_position(), Some((15, 20)));
+    }
+
+    #[test]
+    fn test_draw_snapshot_returns_cell_at() {
+        use ratatui::buffer::Buffer;
+
+        // Create a buffer with a known cell
+        let mut buffer = Buffer::empty(Rect::new(0, 0, 10, 10));
+        buffer[(5, 5)].set_char('X');
+
+        let snapshot = super::DrawSnapshot {
+            size: Rect::new(0, 0, 10, 10),
+            viewport_area: Rect::new(0, 0, 10, 10),
+            is_test_mode: true,
+            cursor_position: None,
+            buffer: Some(buffer),
+        };
+
+        let cell = snapshot.cell_at(5, 5);
+        assert!(cell.is_some());
+        assert_eq!(cell.unwrap().symbol(), "X");
+    }
+
+    #[test]
+    fn test_capture_from_terminal_wrapper() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let snapshot = super::DrawSnapshot::capture(&mut wrapper);
+
+        assert_eq!(snapshot.size(), Rect::new(0, 0, 80, 24));
+        assert!(snapshot.is_test_mode());
+    }
+
+    #[test]
+    fn test_live_terminal_exists() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        // LiveTerminal should exist and wrap a TerminalWrapper reference
+        let _live = super::LiveTerminal::new(&mut wrapper);
+    }
+
+    #[test]
+    fn test_live_terminal_returns_size() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(100, 50);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let live = super::LiveTerminal::new(&mut wrapper);
+        // LiveTerminal must implement TerminalQuery
+        let size = live.size();
+        assert_eq!(size.width, 100);
+        assert_eq!(size.height, 50);
+    }
+
+    #[test]
+    fn test_live_terminal_returns_is_test_mode() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(80, 24);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let live = super::LiveTerminal::new(&mut wrapper);
+        // TestBackend should return true for is_test_mode
+        assert!(live.is_test_mode());
+    }
+
+    #[test]
+    fn test_live_terminal_returns_viewport_area() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal};
+
+        let backend = TestBackend::new(120, 40);
+        let terminal = Terminal::new(backend).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let live = super::LiveTerminal::new(&mut wrapper);
+        let viewport = live.viewport_area();
+        // Viewport should match the terminal size for fullscreen mode
+        assert_eq!(viewport.width, 120);
+        assert_eq!(viewport.height, 40);
+    }
+
+    #[test]
+    fn test_live_terminal_viewport_area_differs_from_size_for_inline() {
+        use crate::terminal::TerminalWrapper;
+        use ratatui::{backend::TestBackend, Terminal, Viewport};
+
+        // Create terminal with inline viewport of height 5 in a 40-line terminal
+        let backend = TestBackend::new(80, 40);
+        let options = ratatui::TerminalOptions {
+            viewport: Viewport::Inline(5),
+        };
+        let terminal = Terminal::with_options(backend, options).unwrap();
+        let mut wrapper = TerminalWrapper::Test(terminal);
+
+        let live = super::LiveTerminal::new(&mut wrapper);
+        let size = live.size();
+        let viewport = live.viewport_area();
+
+        // Terminal size is 80x40
+        assert_eq!(size.width, 80);
+        assert_eq!(size.height, 40);
+
+        // But viewport is only 5 lines high (inline mode)
+        assert_eq!(viewport.width, 80);
+        assert_eq!(viewport.height, 5);
+    }
+}

data/ext/ratatui_ruby/src/terminal/storage.rs

@@ -0,0 +1,109 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Private terminal storage with safe accessor functions.
+//!
+//! This module provides thread-local storage for the terminal and draw snapshot,
+//! with functions that route queries correctly:
+//! - During draw: queries go to snapshot (no lock needed)
+//! - Outside draw: queries go to live terminal
+
+use super::query::{DrawSnapshot, LiveTerminal, TerminalQuery};
+use super::wrapper::TerminalWrapper;
+use std::cell::RefCell;
+
+thread_local! {
+    static TERMINAL: RefCell<Option<TerminalWrapper>> = const { RefCell::new(None) };
+    static DRAW_SNAPSHOT: RefCell<Option<DrawSnapshot>> = const { RefCell::new(None) };
+}
+
+/// Check if we're currently inside a draw operation.
+pub fn is_in_draw_mode() -> bool {
+    DRAW_SNAPSHOT.with(|cell| cell.borrow().is_some())
+}
+
+/// Execute a query. Routes to snapshot during draw, live terminal outside.
+pub fn with_query<R, F>(f: F) -> Option<R>
+where
+    F: Fn(&dyn TerminalQuery) -> R,
+{
+    // During draw: use snapshot
+    DRAW_SNAPSHOT
+        .with(|cell| cell.borrow().as_ref().map(|snapshot| f(snapshot)))
+        .or_else(|| {
+            // Outside draw: use live terminal from thread-local storage
+            TERMINAL.with(|cell| {
+                cell.borrow_mut().as_mut().map(|t| {
+                    let live = LiveTerminal::new(t);
+                    f(&live)
+                })
+            })
+        })
+}
+
+/// Mutable access to terminal. Only works OUTSIDE draw.
+pub fn with_terminal_mut<R, F>(f: F) -> Option<R>
+where
+    F: FnOnce(&mut TerminalWrapper) -> R,
+{
+    // During draw: reject
+    if is_in_draw_mode() {
+        return None;
+    }
+    TERMINAL.with(|cell| cell.borrow_mut().as_mut().map(f))
+}
+
+/// Execute draw with snapshot for queries.
+pub fn lend_for_draw<R, F>(f: F) -> Option<R>
+where
+    F: FnOnce(&mut TerminalWrapper) -> R,
+{
+    // Take terminal out of storage
+    let mut terminal = TERMINAL.with(|cell| cell.borrow_mut().take())?;
+
+    // Capture snapshot BEFORE draw (while we have &mut)
+    let snapshot = DrawSnapshot::capture(&mut terminal);
+    DRAW_SNAPSHOT.with(|cell| *cell.borrow_mut() = Some(snapshot));
+
+    let result = f(&mut terminal);
+
+    // Clear snapshot, restore terminal
+    DRAW_SNAPSHOT.with(|cell| *cell.borrow_mut() = None);
+    TERMINAL.with(|cell| *cell.borrow_mut() = Some(terminal));
+
+    Some(result)
+}
+
+/// Set the terminal (used during initialization).
+pub fn set_terminal(wrapper: TerminalWrapper) {
+    TERMINAL.with(|cell| {
+        *cell.borrow_mut() = Some(wrapper);
+    });
+}
+
+/// Take the terminal out of storage (used during cleanup).
+pub fn take_terminal() -> Option<TerminalWrapper> {
+    TERMINAL.with(|cell| cell.borrow_mut().take())
+}
+
+/// Check if terminal is initialized.
+pub fn is_initialized() -> bool {
+    TERMINAL.with(|cell| cell.borrow().is_some())
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::terminal::query::DrawSnapshot;
+    use ratatui::layout::Rect;
+
+    #[test]
+    fn test_is_in_draw_mode_false_by_default() {
+        assert!(!super::is_in_draw_mode());
+    }
+
+    #[test]
+    fn test_with_query_returns_none_when_not_initialized() {
+        let result = super::with_query(|q| q.size());
+        assert!(result.is_none());
+    }
+}

data/ext/ratatui_ruby/src/terminal/wrapper.rs

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Terminal wrapper enum for different backend types.
+
+use ratatui::{
+    backend::{CrosstermBackend, TestBackend},
+    Terminal,
+};
+use std::io;
+
+/// Unified terminal type supporting different backends.
+pub enum TerminalWrapper {
+    Crossterm(Terminal<CrosstermBackend<io::Stdout>>),
+    Test(Terminal<TestBackend>),
+}

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

@@ -28,6 +28,12 @@ module RatatuiRuby
 
         # Handles navigation-specific DWIM logic for method_missing.
         private def match_navigation_dwim?(key_name, key_sym)
+          # DWIM: back_tab?/backtab? matches back_tab code even with shift modifier
+          # (since back_tab semantically implies shift)
+          if (key_name == "back_tab" || key_name == "backtab") && @code == "back_tab" && (@modifiers.empty? || @modifiers == ["shift"])
+            return true
+          end
+
           # DWIM: reverse_tab? matches both BackTab key and Shift+Tab combo
           if key_name == "reverse_tab"
             return true if @code == "back_tab"

data/lib/ratatui_ruby/version.rb

@@ -8,5 +8,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "1.0.0-beta.2"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.beta.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Kerrick Long
@@ -101,7 +101,7 @@ description: |2-
   Ratatui[https://ratatui.rs], a leading TUI library written in
   Rust[https://rust-lang.org]. You get native performance with the joy of Ruby.
 
-    gem install ratatui_ruby --pre
+    gem install ratatui_ruby
 
   {rdoc-image:https://ratatui-ruby.dev/hero.gif}[https://www.ratatui-ruby.dev/docs/v0.10/examples/app_cli_rich_moments/README_md.html]
 
@@ -604,14 +604,16 @@ files:
 - ext/ratatui_ruby/src/events.rs
 - ext/ratatui_ruby/src/frame.rs
 - ext/ratatui_ruby/src/lib.rs
-- ext/ratatui_ruby/src/lib.rs.bak
 - ext/ratatui_ruby/src/rendering.rs
-- ext/ratatui_ruby/src/rendering.rs.bak
 - ext/ratatui_ruby/src/string_width.rs
 - ext/ratatui_ruby/src/style.rs
-- ext/ratatui_ruby/src/terminal.rs
-- ext/ratatui_ruby/src/terminal.rs.bak
-- ext/ratatui_ruby/src/terminal.rs.orig
+- ext/ratatui_ruby/src/terminal/init.rs
+- ext/ratatui_ruby/src/terminal/mod.rs
+- ext/ratatui_ruby/src/terminal/mutations.rs
+- ext/ratatui_ruby/src/terminal/queries.rs
+- ext/ratatui_ruby/src/terminal/query.rs
+- ext/ratatui_ruby/src/terminal/storage.rs
+- ext/ratatui_ruby/src/terminal/wrapper.rs
 - ext/ratatui_ruby/src/text.rs
 - ext/ratatui_ruby/src/widgets/barchart.rs
 - ext/ratatui_ruby/src/widgets/block.rs