ratatui_ruby 1.2.2 → 1.3.0

data/lib/ratatui_ruby/event/mouse.rb

@@ -253,6 +253,39 @@ module RatatuiRuby
         else false
         end
       end
+
+      alias wheel_up? scroll_up?
+      alias wheel_down? scroll_down?
+
+      # Returns true for any scroll event.
+      #
+      #   event.scroll? # => true for scroll_up or scroll_down
+      def scroll?
+        scroll_up? || scroll_down?
+      end
+
+      alias primary? left?
+      alias secondary? right?
+      alias context_menu? right?
+      alias aux? middle?
+      alias auxiliary? aux?
+
+      # Returns true for mouse movement without button press.
+      #
+      #   event.moved? # => true for moved (no button)
+      def moved?
+        @kind == "moved"
+      end
+
+      alias hover? moved?
+      alias hovering? moved?
+      alias move? moved?
+      alias dragging? drag?
+
+      alias release? up?
+      alias released? up?
+      alias press? down?
+      alias pressed? down?
     end
   end
 end

data/lib/ratatui_ruby/event/paste.rb

@@ -67,6 +67,9 @@ module RatatuiRuby
       def paste?
         true
       end
+      alias clipboard? paste?
+      alias pasteboard? paste?
+      alias pasted? paste?
 
       # Creates a new Paste event.
       #
@@ -100,6 +103,28 @@ module RatatuiRuby
         return false unless other.is_a?(Paste)
         content == other.content
       end
+
+      # Returns true if the pasted content is empty.
+      def empty?
+        @content.empty?
+      end
+
+      # Returns true if the pasted content is empty or whitespace-only.
+      def blank?
+        @content.strip.empty?
+      end
+
+      # Returns true if the pasted content spans multiple lines.
+      def multiline?
+        @content.include?("\n")
+      end
+      alias multi_line? multiline?
+
+      # Returns true if the pasted content is a single line.
+      def single_line?
+        !multiline?
+      end
+      alias singleline? single_line?
     end
   end
 end

data/lib/ratatui_ruby/event/resize.rb

@@ -151,6 +151,71 @@ module RatatuiRuby
         else false
         end
       end
+
+      # Returns true. Unix <tt>SIGWINCH</tt> triggers terminal resize.
+      #
+      #   event.sigwinch? # => true
+      def sigwinch?
+        true
+      end
+
+      alias winch? sigwinch?
+      alias sig_winch? sigwinch?
+
+      alias terminal_resize? resize?
+      alias window_resize? resize?
+      alias window_change? resize?
+      alias viewport_resize? resize?
+      alias viewport_change? resize?
+      alias size_change? resize?
+      alias resized? resize?
+
+      VT100_WIDTH = 80 # :nodoc:
+      VT100_HEIGHT = 24 # :nodoc:
+
+      # Returns true if width exceeds height.
+      #
+      #   Event::Resize.new(width: 120, height: 24).landscape? # => true
+      def landscape?
+        @width > @height
+      end
+
+      # Returns true if height exceeds or equals width.
+      #
+      #   Event::Resize.new(width: 40, height: 80).portrait? # => true
+      def portrait?
+        @height >= @width
+      end
+
+      # Returns true if dimensions are exactly 80x24.
+      #
+      #   Event::Resize.new(width: 80, height: 24).vt100? # => true
+      def vt100?
+        @width == VT100_WIDTH && @height == VT100_HEIGHT
+      end
+
+      # Returns true if both dimensions meet or exceed 80x24.
+      #
+      #   Event::Resize.new(width: 120, height: 40).at_least_vt100? # => true
+      def at_least_vt100?
+        @width >= VT100_WIDTH && @height >= VT100_HEIGHT
+      end
+
+      # Returns true if both dimensions exceed 80x24.
+      #
+      #   Event::Resize.new(width: 81, height: 25).over_vt100? # => true
+      def over_vt100?
+        @width > VT100_WIDTH && @height > VT100_HEIGHT
+      end
+
+      # Returns true if either dimension falls below VT100 standard.
+      #
+      #   Event::Resize.new(width: 60, height: 24).cramped? # => true
+      def cramped?
+        @width < VT100_WIDTH || @height < VT100_HEIGHT
+      end
+
+      alias constrained? cramped?
     end
   end
 end

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.2.2"
+  VERSION = "1.3.0"
 end

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/mise.toml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[tools]
+ruby = "4.0.0"
+rust = "1.91.1"
+python = "3.12"
+pre-commit = "latest"

data/sig/ratatui_ruby/event.rbs

@@ -67,11 +67,46 @@ module RatatuiRuby
         private def match_system_dwim?: (String key_name, Symbol key_sym) -> bool
       end
 
+      # DWIM predicates for common key patterns
+      module Dwim
+        NAVIGATION_KEYS: Array[String]
+        ARROW_KEYS: Array[String]
+        VIM_MOVEMENT_KEYS: Array[String]
+        PUNCTUATION_NAMES: Hash[Symbol, String]
+
+        def space?: () -> bool
+        def cr?: () -> bool
+        def letter?: () -> bool
+        def digit?: () -> bool
+        def alphanumeric?: () -> bool
+        def punctuation?: () -> bool
+        def whitespace?: () -> bool
+        def interrupt?: () -> bool
+        def eof?: () -> bool
+        def cancel?: () -> bool
+        def sigint?: () -> bool
+        def suspend?: () -> bool
+        def quit?: () -> bool
+        def navigation?: () -> bool
+        def arrow?: () -> bool
+        def vim?: () -> bool
+        def vim_left?: () -> bool
+        def vim_down?: () -> bool
+        def vim_up?: () -> bool
+        def vim_right?: () -> bool
+        def vim_word_forward?: () -> bool
+        def vim_word_backward?: () -> bool
+        def vim_top?: () -> bool
+        def vim_bottom?: () -> bool
+        def quote?: () -> bool
+      end
+
       include Character
       include Modifier
       include Media
       include Navigation
       include System
+      include Dwim
 
       attr_reader code: String
       attr_reader modifiers: Array[String]
@@ -114,6 +149,23 @@ module RatatuiRuby
       def left?: () -> bool
       def right?: () -> bool
       def middle?: () -> bool
+      def scroll?: () -> bool
+      def moved?: () -> bool
+      def hover?: () -> bool
+      def hovering?: () -> bool
+      def move?: () -> bool
+      def primary?: () -> bool
+      def secondary?: () -> bool
+      def context_menu?: () -> bool
+      def aux?: () -> bool
+      def auxiliary?: () -> bool
+      def wheel_up?: () -> bool
+      def wheel_down?: () -> bool
+      def release?: () -> bool
+      def released?: () -> bool
+      def press?: () -> bool
+      def pressed?: () -> bool
+      def dragging?: () -> bool
       def to_sym: () -> Symbol
       def ==: (top other) -> bool
       def deconstruct_keys: (Array[Symbol]?) -> { type: :mouse, kind: String, x: Integer, y: Integer, button: String, modifiers: Array[String] }
@@ -127,6 +179,20 @@ module RatatuiRuby
       def to_sym: () -> Symbol
       def ==: (top other) -> bool
       def deconstruct_keys: (Array[Symbol]?) -> { type: :resize, width: Integer, height: Integer }
+
+      # DWIM predicates
+      VT100_WIDTH: Integer
+      VT100_HEIGHT: Integer
+      def sigwinch?: () -> bool
+      def winch?: () -> bool
+      def sig_winch?: () -> bool
+      def landscape?: () -> bool
+      def portrait?: () -> bool
+      def vt100?: () -> bool
+      def at_least_vt100?: () -> bool
+      def over_vt100?: () -> bool
+      def cramped?: () -> bool
+      def constrained?: () -> bool
     end
 
     class Paste < Event
@@ -134,14 +200,45 @@ module RatatuiRuby
 
       def initialize: (content: String) -> void
       def deconstruct_keys: (Array[Symbol]?) -> { type: :paste, content: String }
+
+      # DWIM predicates
+      def clipboard?: () -> bool
+      def pasteboard?: () -> bool
+      def pasted?: () -> bool
+      def empty?: () -> bool
+      def blank?: () -> bool
+      def multiline?: () -> bool
+      def multi_line?: () -> bool
+      def single_line?: () -> bool
+      def singleline?: () -> bool
     end
 
     class FocusGained < Event
       def deconstruct_keys: (Array[Symbol]?) -> { type: :focus_gained }
+
+      # DWIM predicates
+      def focus?: () -> bool
+      def gained?: () -> bool
+      def lost?: () -> bool
+      def blur?: () -> bool
+      def active?: () -> bool
+      def inactive?: () -> bool
+      def foreground?: () -> bool
+      def background?: () -> bool
     end
 
     class FocusLost < Event
       def deconstruct_keys: (Array[Symbol]?) -> { type: :focus_lost }
+
+      # DWIM predicates
+      def focus?: () -> bool
+      def gained?: () -> bool
+      def lost?: () -> bool
+      def blur?: () -> bool
+      def active?: () -> bool
+      def inactive?: () -> bool
+      def foreground?: () -> bool
+      def background?: () -> bool
     end
 
     class None < Event

data/tasks/autodoc/examples.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Autodoc
+  class Examples
+    def self.sync
+      new.sync
+    end
+
+    def sync
+      Dir.glob("{README.md,doc/**/*.md,examples/*/README.md}").each do |readme_path|
+        sync_readme(readme_path)
+      end
+    end
+
+    private def sync_readme(readme_path)
+      content = File.read(readme_path)
+      dir = File.dirname(readme_path)
+
+      new_content = content.gsub(/<!-- SYNC:START:([^ ]+) -->.*?<!-- SYNC:END -->/m) do
+        marker_info = $1
+        source_rel_path, segment_id = marker_info.split(":")
+
+        # Support both repo-root-relative paths (no leading ./) and file-relative paths
+        source_path = if source_rel_path.start_with?("./", "../")
+          File.join(dir, source_rel_path)
+        else
+          source_rel_path # Already relative to repo root
+        end
+
+        unless File.exist?(source_path)
+          warn "Warning: Source file not found: #{source_path}"
+          next $&
+        end
+
+        source_content = File.read(source_path)
+        extracted_content = if segment_id
+          extract_segment(source_content, segment_id, source_path)
+        else
+          source_content
+        end
+
+        # Detect language from extension
+        ext = File.extname(source_path).delete(".")
+        lang = (ext == "rb") ? "ruby" : ext
+
+        # Build replacement
+        "<!-- SYNC:START:#{marker_info} -->\n```#{lang}\n#{extracted_content}```\n<!-- SYNC:END -->"
+      end
+
+      if new_content != content
+        puts "Syncing #{readme_path}..."
+        File.write(readme_path, new_content)
+      end
+    end
+
+    def extract_segment(content, segment_id, source_path)
+      start_marker = /#\s*\[SYNC:START:#{segment_id}\]/
+      end_marker = /#\s*\[SYNC:END:#{segment_id}\]/
+
+      lines = content.lines
+      start_idx = lines.find_index { |l| l =~ start_marker }
+      end_idx = lines.find_index { |l| l =~ end_marker }
+
+      if start_idx && end_idx
+        "#{unindent(lines[(start_idx + 1)...end_idx].join).strip}\n"
+      else
+        warn "Warning: Segment '#{segment_id}' not found in #{source_path}"
+        content # Fallback to full content or error? Let's fallback to original for now.
+      end
+    end
+
+    def unindent(text)
+      lines = text.lines
+      # Don't unindent if empty or just one line
+      return text if lines.empty?
+
+      # Find common leading whitespace
+      indentation = lines.grep(/\S/).map { |l| l[/^\s*/].length }.min || 0
+      lines.map { |l| (l.length > indentation) ? l[indentation..-1] : "#{l.strip}\n" }.join
+    end
+  end
+end

data/tasks/autodoc/member.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Autodoc
+  module Member
+    class Delegate < Data.define(:name)
+      def rbs
+        "    def #{name}: (*untyped args, **untyped kwargs) ?{ (*untyped) -> untyped } -> untyped"
+      end
+
+      def rdoc
+        [
+          "    # :method: #{name}",
+          "    # :call-seq: #{name}(*args, **kwargs, &block)",
+          "    #",
+          "    # Delegates to RatatuiRuby.#{name}.",
+          "    #",
+        ]
+      end
+    end
+
+    class Factory < Data.define(:name, :const_name)
+      def rbs
+        "    def #{name}: (*untyped args, **untyped kwargs) ?{ (*untyped) -> untyped } -> untyped"
+      end
+
+      def rdoc
+        [
+          "    # :method: #{name}",
+          "    # :call-seq: #{name}(*args, **kwargs, &block)",
+          "    #",
+          "    # Factory for RatatuiRuby::#{const_name}.new.",
+          "    #",
+        ]
+      end
+    end
+
+    class Helper < Data.define(:name, :class_method, :const_name)
+      def rbs
+        "    def #{name}: (*untyped args, **untyped kwargs) ?{ (*untyped) -> untyped } -> untyped"
+      end
+
+      def rdoc
+        [
+          "    # :method: #{name}",
+          "    # :call-seq: #{name}(*args, **kwargs, &block)",
+          "    #",
+          "    # Helper for RatatuiRuby::#{const_name}.#{class_method}.",
+          "    #",
+        ]
+      end
+    end
+  end
+end

data/tasks/autodoc/name.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+module Autodoc
+  class Name < Data.define(:string)
+    def snake
+      string.to_s
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+    end
+
+    def to_s
+      string.to_s
+    end
+  end
+end

data/tasks/autodoc.rake

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "autodoc/examples"
+
+namespace :autodoc do
+  desc "Update all automatically generated documentation"
+  task all: [:examples]
+
+  desc "Sync code snippets in example READMEs with source files"
+  task :examples do
+    Autodoc::Examples.sync
+  end
+end
+
+desc "Update all automatically generated documentation"
+task autodoc: "autodoc:all"

data/tasks/bump/bump_workflow.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+require_relative "repository"
+require_relative "changelog"
+
+# Base class for version bump workflows.
+# Subclasses implement the template methods: prepare, release_on_branch, finalize.
+class BumpWorkflow
+  def initialize(gem:, repository: Repository.new)
+    @gem = gem
+    @repository = repository
+  end
+
+  def call(segment)
+    @repository.assert_can_bump!(segment)
+    @target = @gem.version.next(segment)
+
+    prepare(segment)
+    release_on_branch
+    finalize
+  end
+
+  attr_reader :target
+
+  private def release_on_branch
+    changelog = Changelog.new
+    @commit_message = changelog.commit_message(target)
+    changelog.release(target)
+    @gem.update_version(target)
+    generate_ci_manifests
+    @repository.commit_all(@commit_message)
+  end
+
+  private def generate_ci_manifests
+    Rake::Task["sourcehut:build:manifest"].reenable
+    Rake::Task["sourcehut:build"].reenable
+    Rake::Task["sourcehut"].reenable
+    Rake::Task["sourcehut"].invoke
+  end
+
+  # Template methods for subclasses
+  private def prepare(segment) = nil
+  private def finalize = nil
+end