ratatui_ruby 0.10.1 → 0.10.2

data/migrate_to_buffer.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# !/usr/bin/env ruby
+
+# Migration script to refactor widget renderers from Frame to Buffer
+
+require "fileutils"
+
+WIDGETS_DIR = "/Users/kerrick/Developer/ratatui_ruby/ext/ratatui_ruby/src/widgets"
+
+# Files to update (excluding block.rs which is already done)
+WIDGET_FILES = %w[
+  barchart.rs
+  calendar.rs
+  canvas.rs
+  center.rs
+  chart.rs
+  clear.rs
+  cursor.rs
+  gauge.rs
+  layout.rs
+  line_gauge.rs
+  list.rs
+  overlay.rs
+  paragraph.rs
+  ratatui_logo.rs
+  ratatui_mascot.rs
+  scrollbar.rs
+  sparkline.rs
+  table.rs
+  tabs.rs
+].freeze
+
+def migrate_file(filepath)
+  puts "Migrating #{File.basename(filepath)}..."
+
+  content = File.read(filepath)
+  original_content = content.dup
+
+  # 1. Update function signature
+  content.gsub!("pub fn render(frame: &mut Frame,", "pub fn render(buffer: &mut Buffer,")
+  content.gsub!("pub fn render_ratatui_mascot(frame: &mut Frame,", "pub fn render_ratatui_mascot(buffer: &mut Buffer,")
+
+  # 2. Update imports - Add Buffer, remove Frame
+  # Handle various import patterns
+  content.gsub!(/use ratatui::\{([^}]*),\s*Frame\s*\};/, 'use ratatui::{\1};')
+  content.gsub!(/use ratatui::\{Frame,\s*([^}]*)\};/, 'use ratatui::{\1};')
+  content.gsub!("use ratatui::Frame;", "")
+
+  # Add Buffer import if not present
+  unless content.match?(/use ratatui::(?:\{[^}]*)?buffer::Buffer/)
+    # Find the ratatui use statement and add buffer::Buffer
+    content.gsub!("use ratatui::{", "use ratatui::{buffer::Buffer, ")
+    content.gsub!("use ratatui::layout::Rect;", "use ratatui::{buffer::Buffer, layout::Rect};")
+  end
+
+  # 3. Update widget.render calls
+  # frame.render_widget(widget, area) → widget.render(area, buffer)
+  content.gsub!(/frame\.render_widget\(([^,]+),\s*([^)]+)\)/, '\1.render(\2, buffer)')
+
+  # 4. Update direct buffer access
+  content.gsub!("frame.buffer_mut()", "buffer")
+
+  # 5. Update recursive render_node calls
+  content.gsub!("render_node(frame,", "render_node(buffer,")
+
+  # 5.5. Update stateful widget rendering
+  # frame.render_stateful_widget(widget, area, state) → StatefulWidget::render(widget, area, buffer, state)
+  content.gsub!(/frame\.render_stateful_widget\(([^,]+),\s*([^,]+),\s*([^)]+)\)/, 'StatefulWidget::render(\1, \2, buffer, \3)')
+
+  # Add StatefulWidget import if stateful widgets are used
+  if content.match?(/StatefulWidget::render/) && !content.match?(/use ratatui::widgets::StatefulWidget/) && content.match?(/use ratatui::/)
+    content.sub!("use ratatui::{", "use ratatui::{widgets::StatefulWidget, ")
+  end
+
+  # 6. Clean up any double-added Buffer imports and duplicate Widget imports
+  content.gsub!(/buffer::Buffer,\s*buffer::Buffer,/, "buffer::Buffer,")
+  content.gsub!(/widgets::Widget,\s*widgets::Widget/, "widgets::Widget")
+  content.gsub!(/(use ratatui::\{[^}]*widgets::Widget[^}]*),\s*widgets::Widget/, '\1')
+
+  # 7. Fix Widget trait usage - make sure Widget is imported where .render is called
+  # Add Widget to imports if calling .render on widgets
+  if content.match?(/\.render\(area,\s*buffer\)/) && !content.match?(/use ratatui::widgets::Widget/) && content.match?(/use ratatui::\{/) && !content.match?(/widgets::Widget/)
+    content.sub!("use ratatui::{", "use ratatui::{widgets::Widget, ")
+  end
+
+  # 8. For files that don't have proper Buffer imports yet, add them
+  if !content.match?(/use ratatui::\{[^}]*buffer::Buffer/) && content.match?(/use ratatui::/)
+    # Try to add to first ratatui import
+    content.sub!("use ratatui::", "use ratatui::{buffer::Buffer};\nuse ratatui::")
+  end
+
+  # 9. Special case: cursor.rs uses frame.set_cursor_position which doesn't exist on Buffer
+  # Cursor widget needs special handling - it can't work with just Buffer
+  if File.basename(filepath) == "cursor.rs"
+    puts "  ⚠ cursor.rs requires special handling - skipping set_cursor_position"
+    # This widget can't be fully migrated as set_cursor_position is Frame-only
+    # Will need manual fix or different approach
+  end
+  # Only write if content changed
+  if content != original_content
+    File.write(filepath, content)
+    puts "  ✓ Updated #{File.basename(filepath)}"
+    true
+  else
+    puts "  - No changes needed for #{File.basename(filepath)}"
+    false
+  end
+end
+
+def main
+  puts "Starting widget renderer migration..."
+  puts "=" * 60
+
+  updated_count = 0
+
+  WIDGET_FILES.each do |filename|
+    filepath = File.join(WIDGETS_DIR, filename)
+
+    unless File.exist?(filepath)
+      puts "  ⚠ File not found: #{filename}"
+      next
+    end
+
+    # Create backup
+    backup_path = "#{filepath}.premigration"
+    FileUtils.cp(filepath, backup_path) unless File.exist?(backup_path)
+
+    updated_count += 1 if migrate_file(filepath)
+  end
+
+  puts "=" * 60
+  puts "Migration complete!"
+  puts "  Files updated: #{updated_count}/#{WIDGET_FILES.length}"
+  puts "\nBackups saved with .premigration extension"
+  puts "Run 'bundle exec rake compile' to verify the changes"
+end
+
+main if __FILE__ == $PROGRAM_NAME

data/sig/examples/app_cli_rich_moments/app.rbs

@@ -0,0 +1,12 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+class AppCliRichMoments
+  # @public
+  def self.new: () -> AppCliRichMoments
+
+  # @public
+  def run: () -> void
+end

data/sig/ratatui_ruby/labs.rbs

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# RBS type definitions for RatatuiRuby::Labs module
+
+# Dir.tmpdir is from stdlib tmpdir extension
+class Dir
+  def self.tmpdir: () -> String
+end
+
+# Interface for Data.define objects (widgets/nodes with to_h/members)
+interface _DataLike
+  def to_h: () -> Hash[Symbol, Object]
+  def members: () -> Array[Symbol]
+end
+
+# Minimal REXML stubs (no official RBS types available)
+module REXML
+  class Document
+    def self.new: (?untyped?) -> Document
+    def add: (untyped) -> void
+  end
+
+  class Element
+    def self.new: (String) -> Element
+    def add: (untyped) -> void
+    def add_attribute: (String, String) -> void
+    attr_accessor text: String?
+  end
+
+  class XMLDecl
+    def self.new: (String, String) -> XMLDecl
+  end
+
+  module Formatters
+    class Pretty
+      def self.new: (Integer) -> Pretty
+      attr_accessor compact: bool
+      def write: (untyped, untyped) -> void
+    end
+  end
+end
+
+module RatatuiRuby
+  module Labs
+    @enabled_lab: Symbol?
+    @warned: bool
+
+    def self.enabled?: (Symbol lab) -> bool
+    def self.enable!: (Symbol | String lab) -> void
+    def self.reset!: () -> void
+    def self.warn_once!: (String feature_name) -> void
+
+    module A11y
+      OUTPUT_PATH: String
+
+      def self.dump_widget_tree: ((_CustomWidget | widget) widget, ?Layout::Rect? area) -> void
+      def self.dump_widgets: (Array[[(_CustomWidget | widget), Layout::Rect]] widgets_with_areas) -> void
+      def self.startup_message: () -> String
+
+      # Private class methods (called via class << self)
+      # Duck-typed serialization accepts any widget/value that may have to_h/members
+      def self.write_document: (REXML::Document doc) -> void
+      def self.build_element_with_area: ((_CustomWidget | widget) widget, Layout::Rect area) -> REXML::Element
+      def self.build_element: (untyped node) -> REXML::Element
+      def self.add_members: (REXML::Element element, untyped node, ?parent_id: String?) -> void
+      def self.scalar?: (untyped value) -> bool
+      def self.build_child_element: (Symbol key, untyped value, ?is_wrapper: bool, ?parent_id: String?) -> REXML::Element
+    end
+  end
+
+  class Frame
+    prepend A11yCapture
+
+    module A11yCapture
+      @a11y_widgets: Array[[(_CustomWidget | widget), Layout::Rect]]?
+
+      def render_widget: ((_CustomWidget | widget) widget, Layout::Rect area) -> void
+      def render_stateful_widget: (widget widget, Layout::Rect area, Object state) -> void
+      def flush_a11y_capture: () -> void
+    end
+  end
+end

data/sig/ratatui_ruby/ratatui_ruby.rbs

@@ -32,17 +32,19 @@ module RatatuiRuby
     end
     class Invariant < Error
     end
+    class Internal < Error
+    end
   end
 
   # NullIO for headless mode
 
 
   # Core module methods
-  def self.init_terminal: (?focus_events: bool, ?bracketed_paste: bool) -> void
-  def self.init_test_terminal: (Integer width, Integer height) -> void
+  def self.init_terminal: (?focus_events: bool, ?bracketed_paste: bool, ?viewport: (Terminal::Viewport | :fullscreen | :inline)?, ?height: Integer?) -> void
+  def self.init_test_terminal: (Integer width, Integer height, ?String viewport_type, ?Integer? viewport_height) -> void
   def self.restore_terminal: () -> void
   def self.terminal_active?: () -> bool
-  def self.run: (?focus_events: bool, ?bracketed_paste: bool) { (TUI) -> void } -> void
+  def self.run: (?focus_events: bool, ?bracketed_paste: bool, ?viewport: (Terminal::Viewport | :fullscreen | :inline)?, ?height: Integer?) { (TUI) -> void } -> void
   def self.draw: (?widget? tree) -> void
                | () { (Frame) -> void } -> void
   # untyped: FFI boundary - Rust returns dynamic event hash with varying keys per event type
@@ -92,8 +94,14 @@ module RatatuiRuby
   def self.headless!: () -> void
   def self.headless?: () -> bool
 
-  # Terminal area accessor (internal, returns Hash with String keys from Rust FFI)
   def self._get_terminal_area: () -> Hash[String, Integer]
+  def self.get_viewport_area: () -> RatatuiRuby::Layout::Rect
+  def self.terminal_area: () -> RatatuiRuby::Layout::Rect
+  def self.viewport_area: () -> RatatuiRuby::Layout::Rect
+  def self.get_terminal_size: () -> RatatuiRuby::Layout::Rect
+  def self._get_terminal_size: () -> Hash[String, Integer]
+  def self._get_viewport_type: () -> String
+  def self.insert_before: (Integer height, ?widget? widget) ?{ () -> widget } -> void
 
   # Color conversion (internal, Rust FFI)
   def self._color_from_u32: (Integer) -> String

data/sig/ratatui_ruby/terminal/viewport.rbs

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+module RatatuiRuby
+  module Terminal
+    class Viewport < Data
+      attr_reader type: Symbol
+      attr_reader height: Integer?
+
+      def self.fullscreen: () -> Viewport
+      def self.inline: (Integer height) -> Viewport
+
+      def initialize: (type: Symbol, ?height: Integer?) -> void
+
+      def fullscreen?: () -> bool
+      def inline?: () -> bool
+    end
+  end
+end

data/sig/ratatui_ruby/terminal_lifecycle.rbs

@@ -14,16 +14,24 @@ module RatatuiRuby
     @tui_session_active: bool?
     @headless_mode: bool?
 
-    def init_terminal: (?focus_events: bool, ?bracketed_paste: bool) -> void
+    def init_terminal: (?focus_events: bool, ?bracketed_paste: bool, ?viewport: (Terminal::Viewport | :fullscreen | :inline)?, ?height: Integer?) -> void
     def restore_terminal: () -> void
     def terminal_active?: () -> (bool | nil)
-    def init_test_terminal: (Integer width, Integer height) -> void
-    def run: (?focus_events: bool, ?bracketed_paste: bool) { (TUI) -> void } -> void
+    def init_test_terminal: (Integer width, Integer height, ?String viewport_type, ?Integer? viewport_height) -> void
+    def run: (?focus_events: bool, ?bracketed_paste: bool, ?viewport: (Terminal::Viewport | :fullscreen | :inline)?, ?height: Integer?) { (TUI) -> void } -> void
+    def insert_before: (Integer height, ?widget? widget) ?{ () -> widget } -> void
+    def cursor_position=: (Layout::Position | [Integer, Integer] position) -> void
+    def cursor_position: () -> Layout::Position
+    def set_cursor_position: (Integer x, Integer y) -> void
+    def get_cursor_position: () -> [Integer, Integer]
 
     # Private native methods
-    def _init_terminal: (bool focus_events, bool bracketed_paste) -> void
-    def _init_test_terminal: (Integer width, Integer height) -> void
+    def _init_terminal: (bool focus_events, bool bracketed_paste, String viewport_type, Integer? viewport_height) -> void
+    def _init_test_terminal: (Integer width, Integer height, String viewport_type, Integer? viewport_height) -> void
     def _restore_terminal: () -> void
+    def _get_viewport_type: () -> String
+    def _insert_before: (Integer height, widget? content) -> void
+    def resolve_viewport: ((Terminal::Viewport | :fullscreen | :inline)? viewport, Integer? height) -> Terminal::Viewport
     def flush_warnings: () -> void
     def flush_panic_info: () -> void
   end

data/sig/ratatui_ruby/tui/core.rbs

@@ -15,6 +15,9 @@ module RatatuiRuby
       def poll_event: (?timeout: Float) -> Event
       def get_cell_at: (Integer x, Integer y) -> Buffer::Cell
       def draw_cell: (Integer x, Integer y, Buffer::Cell cell) -> Draw::CellCmd
+      def insert_before: (Integer height, ?widget? widget) ?{ () -> widget } -> void
+      def terminal_area: () -> RatatuiRuby::Layout::Rect
+      def viewport_area: () -> RatatuiRuby::Layout::Rect
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 0.10.1
+  version: 0.10.2
 platform: ruby
 authors:
 - Kerrick Long
@@ -135,14 +135,18 @@ files:
 - doc/contributors/design/rust_backend.md
 - doc/contributors/developing_examples.md
 - doc/contributors/documentation_style.md
-- doc/contributors/future_work.md
 - doc/contributors/index.md
+- doc/contributors/todo/align/api_completeness_audit-finished.md
+- doc/contributors/todo/align/api_completeness_audit-unfinished.md
+- doc/contributors/todo/align/terminal.md
+- doc/contributors/todo/future_work.md
 - doc/contributors/upstream_requests/tab_rects.md
 - doc/contributors/upstream_requests/title_rects.md
 - doc/custom.css
 - doc/getting_started/quickstart.md
 - doc/getting_started/why.md
 - doc/images/app_all_events.png
+- doc/images/app_cli_rich_moments.gif
 - doc/images/app_color_picker.png
 - doc/images/app_debugging_showcase.gif
 - doc/images/app_debugging_showcase.png
@@ -197,6 +201,8 @@ files:
 - examples/app_all_events/view/counts_view.rb
 - examples/app_all_events/view/live_view.rb
 - examples/app_all_events/view/log_view.rb
+- examples/app_cli_rich_moments/README.md
+- examples/app_cli_rich_moments/app.rb
 - examples/app_color_picker/README.md
 - examples/app_color_picker/app.rb
 - examples/app_color_picker/clipboard.rb
@@ -290,10 +296,14 @@ 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/text.rs
 - ext/ratatui_ruby/src/widgets/barchart.rs
 - ext/ratatui_ruby/src/widgets/block.rs
@@ -340,6 +350,9 @@ files:
 - lib/ratatui_ruby/event/resize.rb
 - lib/ratatui_ruby/event/sync.rb
 - lib/ratatui_ruby/frame.rb
+- lib/ratatui_ruby/labs.rb
+- lib/ratatui_ruby/labs/a11y.rb
+- lib/ratatui_ruby/labs/frame_a11y_capture.rb
 - lib/ratatui_ruby/layout.rb
 - lib/ratatui_ruby/layout/constraint.rb
 - lib/ratatui_ruby/layout/layout.rb
@@ -355,7 +368,9 @@ files:
 - lib/ratatui_ruby/symbols.rb
 - lib/ratatui_ruby/synthetic_events.rb
 - lib/ratatui_ruby/table_state.rb
+- lib/ratatui_ruby/terminal/viewport.rb
 - lib/ratatui_ruby/terminal_lifecycle.rb
+- lib/ratatui_ruby/terminal_lifecycle.rb.bak
 - lib/ratatui_ruby/test_helper.rb
 - lib/ratatui_ruby/test_helper/event_injection.rb
 - lib/ratatui_ruby/test_helper/snapshot.rb
@@ -423,6 +438,7 @@ files:
 - lib/ratatui_ruby/widgets/sparkline.rb
 - lib/ratatui_ruby/widgets/table.rb
 - lib/ratatui_ruby/widgets/tabs.rb
+- migrate_to_buffer.rb
 - mise.toml
 - sig/examples/app_all_events/app.rbs
 - sig/examples/app_all_events/model/app_model.rbs
@@ -434,6 +450,7 @@ files:
 - sig/examples/app_all_events/view/counts_view.rbs
 - sig/examples/app_all_events/view/live_view.rbs
 - sig/examples/app_all_events/view/log_view.rbs
+- sig/examples/app_cli_rich_moments/app.rbs
 - sig/examples/app_color_picker/app.rbs
 - sig/examples/app_login_form/app.rbs
 - sig/examples/app_stateful_interaction/app.rbs
@@ -475,6 +492,7 @@ files:
 - sig/ratatui_ruby/event.rbs
 - sig/ratatui_ruby/frame.rbs
 - sig/ratatui_ruby/interfaces.rbs
+- sig/ratatui_ruby/labs.rbs
 - sig/ratatui_ruby/layout/constraint.rbs
 - sig/ratatui_ruby/layout/layout.rbs
 - sig/ratatui_ruby/layout/position.rbs
@@ -491,6 +509,7 @@ files:
 - sig/ratatui_ruby/symbols.rbs
 - sig/ratatui_ruby/synthetic_events.rbs
 - sig/ratatui_ruby/table_state.rbs
+- sig/ratatui_ruby/terminal/viewport.rbs
 - sig/ratatui_ruby/terminal_lifecycle.rbs
 - sig/ratatui_ruby/test_helper.rbs
 - sig/ratatui_ruby/test_helper/event_injection.rbs