ratatui_ruby 0.10.1 → 0.10.2

data/doc/getting_started/quickstart.md

@@ -214,69 +214,69 @@ end
 
 ## Examples
 
-These examples showcase the full power of **ratatui_ruby**. You can find their source code in the [examples directory](../examples).
+These examples showcase the full power of **ratatui_ruby**. You can find their source code in the [examples directory](../../examples).
 
 ### Widget Demos
 
 Focused examples for individual widgets. Each demonstrates a single widget and its configuration options.
 
-| Widget | What it demonstrates |
-|--------|---------------------|
-| [Bar Chart](../examples/widget_barchart/app.rb) | Grouped bars, data visualization, custom bar styling |
-| [Block](../examples/widget_block/app.rb) | Borders, titles, padding, nested widgets |
-| [Box](../examples/widget_box/app.rb) | Block + Paragraph composition, text wrapping |
-| [Calendar](../examples/widget_calendar/app.rb) | Date highlighting, month display, event markers |
-| [Chart](../examples/widget_chart/app.rb) | Line/scatter plots, axes, legends, datasets |
-| [Gauge](../examples/widget_gauge/app.rb) | Progress bars, percentage display, unicode blocks |
-| [Layout Split](../examples/widget_layout_split/app.rb) | Constraint types, flex modes, responsive layouts |
-| [Line Gauge](../examples/widget_line_gauge/app.rb) | Horizontal progress, labels, thin-style gauges |
-| [List](../examples/widget_list/app.rb) | Selection, scrolling, highlight styles, rich text items |
-| [Map](../examples/widget_map/app.rb) | Canvas widget, world map rendering, coordinates |
-| [Popup](../examples/widget_popup/app.rb) | Clear widget, modal dialogs, overlay composition |
-| [Ratatui Logo](../examples/widget_ratatui_logo/app.rb) | Decorative branding widget |
-| [Ratatui Mascot](../examples/widget_ratatui_mascot/app.rb) | ASCII art Ferris mascot |
-| [Rect](../examples/widget_rect/app.rb) | Geometry helpers, area calculations, contains/intersection |
-| [Rich Text](../examples/widget_rich_text/app.rb) | Spans, lines, inline styling, mixed colors |
-| [Scrollbar](../examples/widget_scrollbar/app.rb) | Orientations, thumb/track styling, scroll state |
-| [Scroll Text](../examples/widget_scroll_text/app.rb) | Paragraph scrolling, viewport control, long content |
-| [Sparkline](../examples/widget_sparkline/app.rb) | Mini charts, time series, bar sets |
-| [Style Colors](../examples/widget_style_colors/app.rb) | Named colors, RGB, indexed 256-color palette |
-| [Table](../examples/widget_table/app.rb) | Row selection, column widths, per-cell styling |
-| [Tabs](../examples/widget_tabs/app.rb) | Tab navigation, highlighting, dividers |
-| [Text Width](../examples/widget_text_width/app.rb) | Unicode-aware width measurement, CJK support |
-| [Canvas](../examples/widget_canvas/app.rb) | Drawing shapes, markers, custom graphics |
-| [Cell](../examples/widget_cell/app.rb) | Buffer cell inspection, styling attributes |
-| [Center](../examples/widget_center/app.rb) | Centering content, horizontal/vertical alignment |
-| [Overlay](../examples/widget_overlay/app.rb) | Layering widgets, modal backgrounds |
-| [Custom Render](../examples/widget_render/app.rb) | Low-level Draw API, escape hatch for custom widgets |
+| Widget                                                        | What it demonstrates                                       |
+| ------------------------------------------------------------- | ---------------------------------------------------------- |
+| [Bar Chart](../../examples/widget_barchart/app.rb)            | Grouped bars, data visualization, custom bar styling       |
+| [Block](../../examples/widget_block/app.rb)                   | Borders, titles, padding, nested widgets                   |
+| [Box](../../examples/widget_box/app.rb)                       | Block + Paragraph composition, text wrapping               |
+| [Calendar](../../examples/widget_calendar/app.rb)             | Date highlighting, month display, event markers            |
+| [Chart](../../examples/widget_chart/app.rb)                   | Line/scatter plots, axes, legends, datasets                |
+| [Gauge](../../examples/widget_gauge/app.rb)                   | Progress bars, percentage display, unicode blocks          |
+| [Layout Split](../../examples/widget_layout_split/app.rb)     | Constraint types, flex modes, responsive layouts           |
+| [Line Gauge](../../examples/widget_line_gauge/app.rb)         | Horizontal progress, labels, thin-style gauges             |
+| [List](../../examples/widget_list/app.rb)                     | Selection, scrolling, highlight styles, rich text items    |
+| [Map](../../examples/widget_map/app.rb)                       | Canvas widget, world map rendering, coordinates            |
+| [Popup](../../examples/widget_popup/app.rb)                   | Clear widget, modal dialogs, overlay composition           |
+| [Ratatui Logo](../../examples/widget_ratatui_logo/app.rb)     | Decorative branding widget                                 |
+| [Ratatui Mascot](../../examples/widget_ratatui_mascot/app.rb) | ASCII art Ferris mascot                                    |
+| [Rect](../../examples/widget_rect/app.rb)                     | Geometry helpers, area calculations, contains/intersection |
+| [Rich Text](../../examples/widget_rich_text/app.rb)           | Spans, lines, inline styling, mixed colors                 |
+| [Scrollbar](../../examples/widget_scrollbar/app.rb)           | Orientations, thumb/track styling, scroll state            |
+| [Scroll Text](../../examples/widget_scroll_text/app.rb)       | Paragraph scrolling, viewport control, long content        |
+| [Sparkline](../../examples/widget_sparkline/app.rb)           | Mini charts, time series, bar sets                         |
+| [Style Colors](../../examples/widget_style_colors/app.rb)     | Named colors, RGB, indexed 256-color palette               |
+| [Table](../../examples/widget_table/app.rb)                   | Row selection, column widths, per-cell styling             |
+| [Tabs](../../examples/widget_tabs/app.rb)                     | Tab navigation, highlighting, dividers                     |
+| [Text Width](../../examples/widget_text_width/app.rb)         | Unicode-aware width measurement, CJK support               |
+| [Canvas](../../examples/widget_canvas/app.rb)                 | Drawing shapes, markers, custom graphics                   |
+| [Cell](../../examples/widget_cell/app.rb)                     | Buffer cell inspection, styling attributes                 |
+| [Center](../../examples/widget_center/app.rb)                 | Centering content, horizontal/vertical alignment           |
+| [Overlay](../../examples/widget_overlay/app.rb)               | Layering widgets, modal backgrounds                        |
+| [Custom Render](../../examples/widget_render/app.rb)          | Low-level Draw API, escape hatch for custom widgets        |
 
 ### Sample Applications
 
 These larger examples combine widgets into complete applications, demonstrating real-world TUI patterns and architectures.
 
-| Application | Architecture | What you'll learn |
-|-------------|--------------|-------------------|
-| [All Events](../examples/app_all_events/app.rb) | Model-View-Update | Event handling, unidirectional data flow, scalable structure |
-| [Color Picker](../examples/app_color_picker/app.rb) | Component-Based | Hit testing, modal dialogs, encapsulated state |
-| [Debugging Showcase](../examples/app_debugging_showcase/app.rb) | Simple Loop | Remote debugging, Rust backtraces, improved error messages |
-| [Login Form](../examples/app_login_form/app.rb) | Overlay + Center | Modal forms, cursor positioning, text input |
-| [Stateful Interaction](../examples/app_stateful_interaction/app.rb) | State Objects | ListState/TableState, offset read-back, mouse click-to-row |
+| Application                                                            | Architecture      | What you'll learn                                            |
+| ---------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------ |
+| [All Events](../../examples/app_all_events/app.rb)                     | Model-View-Update | Event handling, unidirectional data flow, scalable structure |
+| [Color Picker](../../examples/app_color_picker/app.rb)                 | Component-Based   | Hit testing, modal dialogs, encapsulated state               |
+| [Debugging Showcase](../../examples/app_debugging_showcase/app.rb)     | Simple Loop       | Remote debugging, Rust backtraces, improved error messages   |
+| [Login Form](../../examples/app_login_form/app.rb)                     | Overlay + Center  | Modal forms, cursor positioning, text input                  |
+| [Stateful Interaction](../../examples/app_stateful_interaction/app.rb) | State Objects     | ListState/TableState, offset read-back, mouse click-to-row   |
 
 #### All Events
 
-[![all_events](../images/app_all_events.png)](../examples/app_all_events/README.md)
+[![all_events](../images/app_all_events.png)](../../examples/app_all_events/README.md)
 
 #### Color Picker
 
-[![color_picker](../images/app_color_picker.png)](../examples/app_color_picker/README.md)
+[![color_picker](../images/app_color_picker.png)](../../examples/app_color_picker/README.md)
 
 #### Debugging Showcase
 
-[![debugging_showcase](../images/app_debugging_showcase.gif)](../examples/app_debugging_showcase/README.md)
+[![debugging_showcase](../images/app_debugging_showcase.gif)](../../examples/app_debugging_showcase/README.md)
 
 #### Login Form
 
-[![login_form](../images/app_login_form.png)](../examples/app_login_form/README.md)
+[![login_form](../images/app_login_form.png)](../../examples/app_login_form/README.md)
 
 
 ## Next Steps

data/examples/app_cli_rich_moments/README.md

@@ -0,0 +1,81 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# CLI Rich Moments Example
+
+[![CLI Rich Moments](../../doc/images/app_cli_rich_moments.gif)](app.rb)
+
+Demonstrates inline viewport usage for CLI tools that need brief moments of rich interactivity without full-screen commitment.
+
+## Context
+
+CLI applications often need moments of richness—a spinner while connecting, a quick menu selection, or a brief editor. But committing to a full-screen TUI feels wrong when 90% of the app is traditional CLI output.
+
+## Problem
+
+Standard full-screen TUIs (alternate screen) erase themselves on exit. Your carefully formatted CLI output disappears. Users lose their history. The terminal scrollback becomes useless.
+
+## Solution
+
+This example shows how **inline viewports** solve this problem. Inline regions persist in terminal scrollback after exit. You can mix inline and fullscreen viewports across multiple `RatatuiRuby.run` calls in a single application flow.
+
+## Flow
+
+The application demonstrates four distinct phases:
+
+1. **1-line inline**: Braille spinner (⠋ ⠙ ⠹ etc.) + "Connecting..." status
+2. **5-line inline**: Radio button menu with up/down/enter navigation  
+3. **Fullscreen**: Configuration editor showing legitimate use of alternate screen
+4. **1-line inline**: Braille spinner + "Saving..." confirmation
+
+After exit, all inline outputs remain visible in terminal history. The fullscreen portion disappears cleanly.
+
+## Running
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```bash
+cd examples/app_cli_rich_moments
+ruby app.rb
+```
+<!-- SPDX-SnippetEnd -->
+
+## Architecture
+
+Each phase is a separate `RatatuiRuby.run` block with its own viewport configuration. State (like menu selection) must be passed between phases via instance variables.
+
+**Spinner phases**:
+- Use `viewport: :inline, height: 1`
+- Animate Braille frames with short delays
+- No input handling needed
+
+**Menu phase**:
+- Uses `viewport: :inline, height: 5`  
+- Handles up/down arrow keys for selection
+- Returns selected choice for next phase
+
+**Editor phase**:
+- Uses default fullscreen viewport
+- Demonstrates when alternate screen is appropriate
+- Full 80×24 available
+
+## Key Concepts
+
+- **Viewport independence**: Each `run` block can use different viewport modes
+- **Scrollback persistence**: Inline content remains after exit
+- **State management**: Pass data between phases via instance variables
+- **Appropriate contexts**: Inline for brief moments, fullscreen for sustained interaction
+
+## Learning Outcomes
+
+After studying this example, you'll understand:
+
+- When to use inline vs fullscreen viewports
+- How to mix viewport modes in a single application
+- Why inline viewports improve CLI UX for transient interactions
+- How to manage state across multiple `run` blocks

data/examples/app_cli_rich_moments/app.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+class AppCliRichMoments
+  SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"].freeze
+  MENU_OPTIONS = [
+    "Development Environment",
+    "Staging Environment",
+    "Production Environment",
+  ].freeze
+
+  def initialize
+    @selected_index = 0
+    @choice = nil
+    @tui = RatatuiRuby::TUI.new
+  end
+
+  def run
+    phase_connecting
+    @choice = phase_menu
+    phase_editor
+    phase_saving
+  end
+
+  private def phase_connecting
+    RatatuiRuby.run(viewport: :inline, height: 1) do
+      10.times do |i|
+        render_spinner(SPINNER_FRAMES[i % SPINNER_FRAMES.length], "Connecting to server...")
+        sleep 0.1
+      end
+
+      # Insert success message above viewport into scrollback
+      status = "✓ Connected to server"
+      @tui.insert_before(1, @tui.paragraph(text: status, style: @tui.style(fg: :green)))
+    end
+  end
+
+  private def phase_menu
+    RatatuiRuby.run(viewport: :inline, height: 5) do
+      loop do
+        render_menu
+        case handle_menu_input
+        when :quit, :select
+          # Position cursor after viewport for next phase
+          area = @tui.viewport_area
+
+          # # If you wanted to remove the menu from scrollback, you could do:
+          # @tui.draw { |frame| frame.render_widget(@tui.clear, frame.area) }
+          # # And move the cursor to avoid extra blank space.
+          # RatatuiRuby.cursor_position = [0, area.y]
+
+          # But instead, we'll leave it in scrollback for reference.
+          # Move the cursor to avoid overwriting it.
+          RatatuiRuby.cursor_position = [0, area.y + area.height]
+
+          return MENU_OPTIONS[@selected_index]
+        end
+      end
+    end
+  end
+
+  private def phase_editor
+    RatatuiRuby.run do # Fullscreen by default
+      loop do
+        render_editor
+        break if handle_editor_input == :quit
+      end
+    end
+  end
+
+  private def phase_saving
+    RatatuiRuby.run(viewport: :inline, height: 1) do
+      10.times do |i|
+        render_spinner(SPINNER_FRAMES[i % SPINNER_FRAMES.length], "Saving configuration...")
+        sleep 0.1
+      end
+
+      status = "✓ Configuration saved to #{@choice.downcase.gsub(' ', '_')}.yml"
+      @tui.insert_before(1, @tui.paragraph(text: status, style: @tui.style(fg: :green)))
+    end
+  end
+
+  private def render_spinner(frame, message)
+    @tui.draw do |f|
+      text = "#{frame} #{message}"
+      widget = @tui.paragraph(text:, style: @tui.style(fg: :cyan))
+      f.render_widget(widget, f.area)
+    end
+  end
+
+  private def render_menu
+    @tui.draw do |f|
+      lines = MENU_OPTIONS.map.with_index do |option, idx|
+        prefix = (idx == @selected_index) ? "→ " : "  "
+        style = (idx == @selected_index) ? @tui.style(fg: :cyan, modifiers: [:bold]) : @tui.style(fg: :white)
+        @tui.text_line(spans: [@tui.text_span(content: "#{prefix}#{option}", style:)])
+      end
+
+      widget = @tui.paragraph(
+        text: lines,
+        block: @tui.block(borders: :all, title: "Select Environment")
+      )
+      f.render_widget(widget, f.area)
+    end
+  end
+
+  private def render_editor
+    @tui.draw do |f|
+      areas = @tui.layout_split(
+        f.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(3),
+        ]
+      )
+
+      # Main content area
+      content_text = [
+        "Editing: #{@choice}",
+        "",
+        "# Database Configuration",
+        "database:",
+        "  adapter: postgresql",
+        "  host: db.example.com",
+        "  port: 5432",
+        "",
+        "# Cache Configuration",
+        "cache:",
+        "  provider: redis",
+        "  ttl: 3600",
+      ].join("\n")
+
+      content = @tui.paragraph(
+        text: content_text,
+        block: @tui.block(borders: :all, title: "Configuration Editor"),
+        style: @tui.style(fg: :yellow)
+      )
+      f.render_widget(content, areas[0])
+
+      # Help panel
+      help_text = "q: Save and Exit  |  Ctrl+C: Cancel"
+      help = @tui.paragraph(
+        text: help_text,
+        block: @tui.block(borders: :all),
+        style: @tui.style(fg: :dark_gray),
+        alignment: :center
+      )
+      f.render_widget(help, areas[1])
+    end
+  end
+
+  private def handle_menu_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in { type: :key, code: "enter" }
+      :select
+    in { type: :key, code: "up" }
+      @selected_index = (@selected_index - 1) % MENU_OPTIONS.length
+      nil
+    in { type: :key, code: "down" }
+      @selected_index = (@selected_index + 1) % MENU_OPTIONS.length
+      nil
+    else
+      nil
+    end
+  end
+
+  private def handle_editor_input
+    case @tui.poll_event
+    in { type: :key, code: "q" }
+      :quit # "and save," presumably
+    in { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    else
+      nil
+    end
+  end
+end
+
+AppCliRichMoments.new.run if __FILE__ == $PROGRAM_NAME

data/ext/ratatui_ruby/Cargo.lock

@@ -1059,7 +1059,7 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "0.10.1"
+version = "0.10.2"
 dependencies = [
  "bumpalo",
  "lazy_static",

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "0.10.1"
+version = "0.10.2"
 edition = "2021"
 
 [lib]

data/ext/ratatui_ruby/src/frame.rs

@@ -151,8 +151,18 @@ impl RubyFrame {
         // 4. ensure_active() above guarantees we're still in the callback
         let frame = unsafe { (*self.inner.get()).as_mut() };
 
+        // Special case: Cursor widget requires Frame.set_cursor_position
+        // SAFETY: Immediate conversion to owned string avoids GC-unsafe borrowed reference.
+        let widget_class = unsafe { widget.class().name() }.into_owned();
+        if widget_class == "RatatuiRuby::Widgets::Cursor" {
+            let cursor_x: u16 = widget.funcall("x", ())?;
+            let cursor_y: u16 = widget.funcall("y", ())?;
+            frame.set_cursor_position((rect.x + cursor_x, rect.y + cursor_y));
+            return Ok(());
+        }
+
         // Delegate to the existing render_node function
-        rendering::render_node(frame, rect, widget)
+        rendering::render_node(frame.buffer_mut(), rect, widget)
     }
 
     /// Renders a stateful widget at the specified area.
@@ -192,13 +202,16 @@ impl RubyFrame {
 
         match (widget_class.as_str(), state_class.as_str()) {
             ("RatatuiRuby::Widgets::List", "RatatuiRuby::ListState") => {
-                widgets::list::render_stateful(frame, rect, widget, state)
+                let buffer = frame.buffer_mut();
+                widgets::list::render_stateful(buffer, rect, widget, state)
             }
             ("RatatuiRuby::Widgets::Table", "RatatuiRuby::TableState") => {
-                widgets::table::render_stateful(frame, rect, widget, state)
+                let buffer = frame.buffer_mut();
+                widgets::table::render_stateful(buffer, rect, widget, state)
             }
             ("RatatuiRuby::Widgets::Scrollbar", "RatatuiRuby::ScrollbarState") => {
-                widgets::scrollbar::render_stateful(frame, rect, widget, state)
+                let buffer = frame.buffer_mut();
+                widgets::scrollbar::render_stateful(buffer, rect, widget, state)
             }
             _ => Err(Error::new(
                 ruby.exception_arg_error(),

data/ext/ratatui_ruby/src/lib.rs

@@ -83,7 +83,8 @@ fn draw(args: &[Value]) -> Result<(), Error> {
             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) {
+            let area = f.area();
+            if let Err(e) = rendering::render_node(f.buffer_mut(), area, tree_value) {
                 render_error = Some(e);
             }
         }
@@ -159,7 +160,7 @@ 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("_init_terminal", function!(init_terminal, 4))?;
     m.define_module_function("_restore_terminal", function!(restore_terminal, 0))?;
     m.define_module_function("_draw", function!(draw, -1))?;
     m.define_module_function(
@@ -193,7 +194,7 @@ fn init() -> Result<(), Error> {
     // Test backend helpers
     m.define_module_function(
         "_init_test_terminal",
-        function!(terminal::init_test_terminal, 2),
+        function!(terminal::init_test_terminal, 4),
     )?;
     m.define_module_function(
         "get_buffer_content",
@@ -203,12 +204,25 @@ fn init() -> Result<(), Error> {
         "get_cursor_position",
         function!(terminal::get_cursor_position, 0),
     )?;
+    m.define_module_function(
+        "set_cursor_position",
+        function!(terminal::set_cursor_position, 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))?;
     m.define_module_function(
         "_get_terminal_area",
         function!(terminal::get_terminal_area, 0),
     )?;
+    m.define_module_function(
+        "_get_terminal_size",
+        function!(terminal::get_terminal_size, 0),
+    )?;
+    m.define_module_function("_insert_before", function!(terminal::insert_before, 2))?;
+    m.define_module_function(
+        "_get_viewport_type",
+        function!(terminal::get_viewport_type, 0),
+    )?;
 
     // Register Layout.split on the Layout::Layout class (inside the Layout module)
     let layout_mod = m.const_get::<_, magnus::RModule>("Layout")?;