ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/cell.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Represents a single cell in the terminal buffer.
+  #
+  # A terminal grid is made of cells. Each cell contains a character (symbol) and styling (colors, modifiers).
+  # When testing, you often need to verify that a specific cell renders correctly.
+  #
+  # This object encapsulates that state. It provides predicate methods for modifiers, making assertions readable.
+  #
+  # Use it to inspect the visual state of your application in tests.
+  #
+  # === Examples
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   cell = RatatuiRuby.get_cell_at(0, 0)
+  #   cell.char   # => "H"
+  #   cell.fg     # => :red
+  #   cell.bold?  # => true
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  class Cell
+    # The character displayed in the cell.
+    #
+    # Named to match Ratatui's Cell::symbol() method.
+    attr_reader :symbol
+
+    # Alias for Rubyists who prefer a shorter name.
+    alias char symbol
+
+    # The foreground color of the cell (e.g., :red, :blue, "#ff0000").
+    attr_reader :fg
+
+    # The background color of the cell (e.g., :black, nil).
+    attr_reader :bg
+
+    # The underline color of the cell.
+    #
+    # Distinct from foreground color. Some terminals support colored underlines.
+    attr_reader :underline_color
+
+    # The list of active modifiers (e.g., ["bold", "italic"]).
+
+    # Returns an empty cell (space character, no styles).
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   Cell.empty # => #<RatatuiRuby::Cell char=" ">
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def self.empty
+      new(symbol: " ", fg: nil, bg: nil, underline_color: nil, modifiers: [])
+    end
+
+    # Returns a default cell (alias for empty).
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   Cell.default # => #<RatatuiRuby::Cell char=" ">
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def self.default
+      empty
+    end
+
+    # Returns a cell with a specific character and no styles.
+    #
+    # [symbol] String (single character).
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   Cell.symbol("X") # => #<RatatuiRuby::Cell symbol="X">
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def self.symbol(symbol)
+      new(symbol:, fg: nil, bg: nil, underline_color: nil, modifiers: [])
+    end
+
+    # Alias for Rubyists who prefer a shorter name.
+    def self.char(char)
+      symbol(char)
+    end
+
+    # Creates a new Cell.
+    #
+    # [symbol] String (single character). Aliased as <tt>char:</tt>.
+    # [fg] Symbol or String (nullable).
+    # [bg] Symbol or String (nullable).
+    # [underline_color] Symbol or String (nullable).
+    # [modifiers] Array of Strings.
+    def initialize(symbol: nil, char: nil, fg: nil, bg: nil, underline_color: nil, modifiers: [])
+      @symbol = (symbol || char || " ").freeze
+      @fg = fg&.freeze
+      @bg = bg&.freeze
+      @underline_color = underline_color&.freeze
+      @modifiers = modifiers.map(&:freeze).freeze
+      freeze
+    end
+
+    # Returns true if the cell has the bold modifier.
+    def bold?
+      modifiers.include?("bold")
+    end
+
+    # Returns true if the cell has the dim modifier.
+    def dim?
+      modifiers.include?("dim")
+    end
+
+    # Returns true if the cell has the italic modifier.
+    def italic?
+      modifiers.include?("italic")
+    end
+
+    # Returns true if the cell has the underlined modifier.
+    def underlined?
+      modifiers.include?("underlined")
+    end
+
+    # Returns true if the cell has the slow_blink modifier.
+    def slow_blink?
+      modifiers.include?("slow_blink")
+    end
+
+    # Returns true if the cell has the rapid_blink modifier.
+    def rapid_blink?
+      modifiers.include?("rapid_blink")
+    end
+
+    # Returns true if the cell has the reversed modifier.
+    def reversed?
+      modifiers.include?("reversed")
+    end
+
+    # Returns true if the cell has the hidden modifier.
+    def hidden?
+      modifiers.include?("hidden")
+    end
+
+    # Returns true if the cell has the crossed_out modifier.
+    def crossed_out?
+      modifiers.include?("crossed_out")
+    end
+
+    # Checks equality with another Cell.
+    def ==(other)
+      other.is_a?(Cell) &&
+        char == other.char &&
+        fg == other.fg &&
+        bg == other.bg &&
+        underline_color == other.underline_color &&
+        modifiers == other.modifiers
+    end
+
+    # Returns a string representation of the cell.
+    def inspect
+      parts = ["symbol=#{symbol.inspect}"]
+      parts << "fg=#{fg.inspect}" if fg
+      parts << "bg=#{bg.inspect}" if bg
+      parts << "underline_color=#{underline_color.inspect}" if underline_color
+      parts << "modifiers=#{modifiers.inspect}" unless modifiers.empty?
+      "#<#{self.class} #{parts.join(' ')}>"
+    end
+
+    # Returns the cell's character.
+    def to_s
+      symbol
+    end
+
+    # Support for pattern matching.
+    # Supports both <tt>:symbol</tt> and <tt>:char</tt> keys.
+    def deconstruct_keys(keys)
+      { symbol:, char: symbol, fg:, bg:, underline_color:, modifiers: }
+    end
+  end
+end

data/lib/ratatui_ruby/debug.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Debug mode control for RatatuiRuby.
+  #
+  # TUI applications are hard to debug. Rust panics show cryptic stack traces.
+  # Ruby exceptions lack Rust context.
+  #
+  # This module controls debug visibility. Enable Rust backtraces only, or
+  # enable full debug mode for both Rust and Ruby-side features.
+  #
+  # == Activation Methods
+  #
+  # Three ways to enable debug features:
+  #
+  # [<tt>RUST_BACKTRACE=1</tt>] Rust backtraces only (no Ruby-side debug).
+  # [<tt>RR_DEBUG=1</tt>] Full debug mode (backtraces + Ruby features).
+  # [<tt>include RatatuiRuby::TestHelper</tt>] Auto-enables debug mode.
+  #
+  # === Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   # Programmatic activation
+  #   RatatuiRuby::Debug.enable!
+  #
+  #   # Or use the convenience alias
+  #   RatatuiRuby.debug_mode!
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  module Debug
+    @rust_backtrace_enabled = false
+    @debug_mode_enabled = false
+
+    class << self
+      ##
+      # Enables Rust backtraces only.
+      #
+      # Call this to get meaningful stack traces when Rust panics.
+      # Does not enable Ruby-side debug features.
+      #
+      # Safe to call multiple times; subsequent calls are no-ops.
+      def enable_rust_backtrace!
+        return if @rust_backtrace_enabled
+
+        @rust_backtrace_enabled = true
+        RatatuiRuby.__send__(:_enable_rust_backtrace)
+      end
+
+      ##
+      # Enables full debug mode.
+      #
+      # Activates Rust backtraces plus any Ruby-side debug features.
+      # Optionally enables remote debugging via the debug gem.
+      #
+      # Safe to call multiple times; subsequent calls are no-ops.
+      #
+      # [source] <tt>:env</tt> if called from RR_DEBUG env var,
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #          <tt>:test</tt> from TestHelper (skips remote debugging),
+      #          <tt>:programmatic</tt> otherwise.
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def enable!(source: :programmatic)
+        return @socket_path if @debug_mode_enabled
+
+        @debug_mode_enabled = true
+        enable_rust_backtrace!
+
+        # Tests don't need remote debugging — it would cause hangs
+        return if source == :test
+
+        @remote_debugging_mode = (source == :env) ? :open : :open_nonstop
+        @socket_path = enable_remote_debugging!
+      end
+
+      # rubocop:disable Lint/Debugger -- intentional debug gem integration
+      private def enable_remote_debugging!
+        # Suppress the "Debugger can attach via..." message that corrupts TUI displays
+        # Only suppress for programmatic activation; RR_DEBUG=1 users need to see it
+        old_log_level = ENV["RUBY_DEBUG_LOG_LEVEL"]
+        ENV["RUBY_DEBUG_LOG_LEVEL"] = "ERROR" if @remote_debugging_mode == :open_nonstop
+
+        case @remote_debugging_mode
+        when :open
+          # Stop at load so user can read socket path before TUI enters raw mode
+          ENV["RUBY_DEBUG_STOP_AT_LOAD"] = "1"
+          require "debug/open"
+        when :open_nonstop
+          require "debug/open_nonstop"
+        end
+
+        # Restore log level after require (the require is what prints the message)
+        ENV["RUBY_DEBUG_LOG_LEVEL"] = old_log_level if @remote_debugging_mode == :open_nonstop
+
+        # Return the socket path so apps can display it
+        ::DEBUGGER__.create_unix_domain_socket_name
+      rescue NameError
+        # Windows uses TCP/IP, not Unix sockets — DEBUGGER__ might not have this method
+        nil
+      # rubocop:enable Lint/Debugger
+      rescue LoadError
+        return unless @remote_debugging_mode == :open
+
+        raise LoadError,
+          "RR_DEBUG=1 requires the 'debug' gem for remote debugging. " \
+            "Add `gem 'debug'` to your Gemfile or install it with `gem install debug`."
+      end
+
+      ##
+      # Returns whether full debug mode is enabled.
+      public def enabled?
+        @debug_mode_enabled
+      end
+
+      ##
+      # Returns whether Rust backtraces are enabled.
+      public def rust_backtrace_enabled?
+        @rust_backtrace_enabled
+      end
+
+      ##
+      # Returns the remote debugging mode for debug gem integration.
+      #
+      # TUI apps run in raw terminal mode, making interactive debugging
+      # impossible. The debug gem's remote debugging feature lets you
+      # attach from another terminal via UNIX socket.
+      #
+      # Returns one of:
+      # <tt>:open</tt> Stop at program start, wait for debugger attach.
+      #                   Activated when <tt>RR_DEBUG=1</tt> is set at startup.
+      # <tt>:open_nonstop</tt> Continue running, attach whenever ready.
+      #                           Activated when <tt>enable!</tt> is called programmatically.
+      # <tt>nil</tt> No remote debugging configured.
+      public def remote_debugging_mode
+        @remote_debugging_mode
+      end
+
+      ##
+      # Triggers a Rust panic for backtrace verification.
+      #
+      # Debugging TUI apps is hard. Rust errors lack context. You want to
+      # confirm <tt>RUST_BACKTRACE=1</tt> actually shows stack traces before
+      # hitting a real bug.
+      #
+      # This method deliberately panics. The panic hook catches it and prints
+      # the Rust backtrace to stderr. If you see stack frames, your setup works.
+      #
+      # <b>WARNING</b>: Crashes your process. Use only for debugging.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   RUST_BACKTRACE=1 ruby -e 'require "ratatui_ruby"; RatatuiRuby::Debug.test_panic!'
+      #--
+      # SPDX-SnippetEnd
+      #++
+      public def test_panic!
+        RatatuiRuby.__send__(:_test_panic)
+      end
+
+      ##
+      # Temporarily suppresses Ruby-side debug mode checks.
+      #
+      # Rust backtraces remain enabled if previously activated; only
+      # Ruby-side features (like unknown-key errors) are suppressed
+      # within the block.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   RatatuiRuby::Debug.suppress_debug_mode do
+      #     tui.table({ unknown_key: 1 }) # Does not raise
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      public def suppress_debug_mode
+        old_value = @debug_mode_enabled
+        @debug_mode_enabled = false
+        yield
+      ensure
+        @debug_mode_enabled = old_value
+      end
+    end
+  end
+end
+
+# Auto-enable based on environment variables
+RatatuiRuby::Debug.enable_rust_backtrace! if ENV["RUST_BACKTRACE"]
+RatatuiRuby::Debug.enable!(source: :env) if ENV["RR_DEBUG"]

data/lib/ratatui_ruby/draw.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Draw commands for custom widgets.
+  #
+  # Custom widgets return an array of Draw commands instead of writing directly to a buffer.
+  # This keeps all pointers safely inside Rust while Ruby works with pure data.
+  #
+  # === Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   class MyWidget
+  #     def render(area)
+  #       [
+  #         RatatuiRuby::Draw.string(area.x, area.y, "Hello", {fg: :red}),
+  #         RatatuiRuby::Draw.cell(area.x + 6, area.y, RatatuiRuby::Cell.char("!"))
+  #       ]
+  #     end
+  #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
+  module Draw
+    # Command to draw a string at the given coordinates.
+    #
+    # [x] X coordinate (absolute).
+    # [y] Y coordinate (absolute).
+    # [string] The text to draw.
+    # [style] Style hash or Style object.
+    StringCmd = Data.define(:x, :y, :string, :style)
+
+    # Command to draw a cell at the given coordinates.
+    #
+    # [x] X coordinate (absolute).
+    # [y] Y coordinate (absolute).
+    # [cell] The Cell to draw.
+    CellCmd = Data.define(:x, :y, :cell)
+
+    # Creates a string draw command.
+    #
+    # [x] X coordinate (Integer, duck-typed via +to_int+).
+    # [y] Y coordinate (Integer, duck-typed via +to_int+).
+    # [string] Text to draw.
+    # [style] Optional style (Hash or Style).
+    def self.string(x, y, string, style = {}) = StringCmd.new(x: Integer(x), y: Integer(y), string:, style:)
+
+    # Creates a cell draw command.
+    #
+    # [x] X coordinate (Integer, duck-typed via +to_int+).
+    # [y] Y coordinate (Integer, duck-typed via +to_int+).
+    # [cell] Cell to draw.
+    def self.cell(x, y, cell) = CellCmd.new(x: Integer(x), y: Integer(y), cell:)
+  end
+end

data/lib/ratatui_ruby/event/focus_gained.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Event
+    # Signals that the application is now active.
+    #
+    # The user interacts with many windows. Your application needs to know when it has their attention.
+    #
+    # This event confirms visibility. It fires when the terminal window moves to the foreground.
+    #
+    # Use it to resume paused activities. Restart animations. Refresh data. The user is watching.
+    #
+    # Only supported by some terminals (e.g. iTerm2, Kitty, newer xterm).
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   if event.focus_gained?
+    #     puts "Focus gained"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class FocusGained < Event
+      # Returns true for FocusGained events.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   event.focus_gained? # => true
+      #   event.key?          # => false
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def focus_gained?
+        true
+      end
+
+      # Deconstructs the event for pattern matching.
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2025 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   case event
+      #   in type: :focus_gained
+      #     puts "Application gained focus"
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def deconstruct_keys(keys)
+        { type: :focus_gained }
+      end
+
+      ##
+      # Compares this event with another for equality.
+      def ==(other)
+        other.is_a?(FocusGained)
+      end
+
+      # =========================================================================
+      # DWIM Predicates
+      # =========================================================================
+
+      # Returns true. The terminal window is now in focus.
+      #
+      #   event.focus? # => true
+      def focus?
+        true
+      end
+      alias focused? focus?
+
+      # Returns true. The application gained focus.
+      #
+      #   event.gained? # => true
+      def gained?
+        true
+      end
+
+      # Returns false. This is not a focus lost event.
+      #
+      #   event.lost? # => false
+      def lost?
+        false
+      end
+
+      # Returns false. Blur is the opposite of focus gained.
+      #
+      #   event.blur? # => false
+      def blur?
+        false
+      end
+      alias blurred? blur?
+
+      # Returns true. The application is active.
+      #
+      #   event.active? # => true
+      def active?
+        true
+      end
+      alias foreground? active?
+
+      # Returns false. The application is not inactive.
+      #
+      #   event.inactive? # => false
+      def inactive?
+        false
+      end
+      alias background? inactive?
+    end
+  end
+end