ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/table_state.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Mutable state object for Table widgets.
+  #
+  # When using {Frame#render_stateful_widget}, the State object is the
+  # *single source of truth* for selection and scroll offset. Widget
+  # properties (+selected_row+, +selected_column+, +offset+) are *ignored*
+  # in stateful mode.
+  #
+  # == Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   @table_state = RatatuiRuby::TableState.new
+  #   @table_state.select(1)        # Select second row
+  #   @table_state.select_column(0) # Select first column
+  #
+  #   RatatuiRuby.draw do |frame|
+  #     table = RatatuiRuby::Widgets::Table.new(rows: [...], widths: [...])
+  #     frame.render_stateful_widget(table, frame.area, @table_state)
+  #   end
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  class TableState
+    ##
+    # :method: new
+    # :call-seq: new(selected = nil) -> TableState
+    #
+    # Creates a new TableState with optional initial row selection.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select
+    # :call-seq: select(index) -> nil
+    #
+    # Sets the selected row index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected
+    # :call-seq: selected() -> Integer or nil
+    #
+    # Returns the currently selected row index.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_column
+    # :call-seq: select_column(index) -> nil
+    #
+    # Sets the selected column index. Pass +nil+ to deselect.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected_column
+    # :call-seq: selected_column() -> Integer or nil
+    #
+    # Returns the currently selected column index.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: offset
+    # :call-seq: offset() -> Integer
+    #
+    # Returns the current scroll offset.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_down_by
+    # :call-seq: scroll_down_by(n) -> nil
+    #
+    # Scrolls down by +n+ rows.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: scroll_up_by
+    # :call-seq: scroll_up_by(n) -> nil
+    #
+    # Scrolls up by +n+ rows.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: selected_cell
+    # :call-seq: selected_cell() -> Array or nil
+    #
+    # Returns the currently selected cell as <tt>[row, column]</tt>.
+    # Returns +nil+ if either row or column is not selected.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_next_column
+    # :call-seq: select_next_column() -> nil
+    #
+    # Selects the next column, or column 0 if none selected.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_previous_column
+    # :call-seq: select_previous_column() -> nil
+    #
+    # Selects the previous column. Saturates at 0.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_first_column
+    # :call-seq: select_first_column() -> nil
+    #
+    # Selects column 0.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_last_column
+    # :call-seq: select_last_column() -> nil
+    #
+    # Selects the last column. The index is clamped during rendering.
+    #
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_next
+    # :call-seq: select_next() -> nil
+    #
+    # Moves selection to the next row. Selects first row if nothing selected.
+    #
+    # === Optimistic Indexing
+    #
+    # Increments the index immediately, even past table bounds. The renderer
+    # clamps to valid range on draw. Reading <tt>selected</tt> between this
+    # call and render may return an out-of-bounds value.
+    #
+    # To detect actual selection changes, check bounds first:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   max_index = rows.size - 1
+    #   return if (state.selected || 0) >= max_index
+    #   state.select_next
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_previous
+    # :call-seq: select_previous() -> nil
+    #
+    # Moves selection to the previous row. Selects last row if nothing selected.
+    #
+    # === Optimistic Indexing
+    #
+    # At index 0, does nothing. With no selection, sets index to maximum value;
+    # the renderer clamps to actual last row on draw.
+    #
+    # To detect actual selection changes, check bounds first:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   return if (state.selected || 0) <= 0
+    #   state.select_previous
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_first
+    # :call-seq: select_first() -> nil
+    #
+    # Jumps selection to the first row (index 0).
+    #
+    # To detect actual selection changes:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   return if (state.selected || 0) == 0
+    #   state.select_first
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: select_last
+    # :call-seq: select_last() -> nil
+    #
+    # Jumps selection to the last row.
+    #
+    # === Optimistic Indexing
+    #
+    # Sets index to maximum possible value. The renderer clamps to actual last
+    # row on draw. To get or check the real last index, track row count:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   max_index = rows.size - 1
+    #   return if (state.selected || 0) == max_index
+    #   state.select(max_index)
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :singleton-method: with_selected_cell
+    # :call-seq: with_selected_cell(cell) -> TableState
+    #
+    # Creates a new TableState with both row and column selected.
+    #
+    # [cell] <tt>[row, column]</tt> array, or +nil+.
+    #
+    # (Native method implemented in Rust)
+  end
+end

data/lib/ratatui_ruby/terminal/capabilities.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "timeout"
+
+module RatatuiRuby
+  class Terminal
+    # Environment-based terminal capability detection.
+    #
+    # TUI applications need to know what the terminal supports. Color depth
+    # varies. Some terminals lack escape sequence support entirely. Users
+    # set environment variables like <tt>NO_COLOR</tt> to express preferences.
+    #
+    # This module detects terminal capabilities from environment variables.
+    # It checks <tt>TERM</tt>, <tt>COLORTERM</tt>, <tt>NO_COLOR</tt>, and
+    # <tt>FORCE_COLOR</tt> to determine what the terminal supports.
+    #
+    # Use these methods before initializing a Terminal instance to decide
+    # whether TUI mode is appropriate for the current environment.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   if RatatuiRuby::Terminal.interactive?
+    #     RatatuiRuby.run { |tui| ... }
+    #   else
+    #     puts "TUI mode not available"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module Capabilities
+      # Checks if stdout connects to a terminal device.
+      #
+      # Terminal apps render escape sequences. Piped output or log files
+      # cannot interpret them. If your app writes ANSI codes to a non-TTY,
+      # logs fill with garbage like <tt>[32m</tt> instead of green text.
+      #
+      # This method checks <tt>$stdout.tty?</tt>. Use it to skip TUI mode
+      # when output is redirected. Print plain text instead.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if RatatuiRuby::Terminal.tty?
+      #     start_tui
+      #   else
+      #     print_plain_output
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def tty?
+        $stdout.tty?
+      end
+
+      # Checks if the terminal declared itself "dumb."
+      #
+      # Dumb terminals exist. Emacs shell-mode sets <tt>TERM=dumb</tt>.
+      # Serial consoles do too. These terminals cannot interpret escape
+      # sequences. If your app sends cursor movements or colors, output
+      # becomes unreadable.
+      #
+      # This method checks for explicit <tt>TERM=dumb</tt>. Empty or unset
+      # <tt>TERM</tt> means "unknown," not "dumb." Use it to fall back to
+      # plain text rendering.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if RatatuiRuby::Terminal.dumb?
+      #     render_plain_table(data)
+      #   else
+      #     render_styled_table(data)
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def dumb?
+        ENV["TERM"] == "dumb"
+      end
+
+      # Checks if the user disabled color output.
+      #
+      # Users with visual impairments or screen readers often disable
+      # colors. The NO_COLOR standard (no-color.org) provides a universal
+      # way to request this. Ignoring it frustrates accessibility-conscious
+      # users.
+      #
+      # This method checks for <tt>NO_COLOR</tt> in the environment. The
+      # value does not matter; presence alone disables color. Respect it.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   style = RatatuiRuby::Terminal.no_color? ? :plain : :colored
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def no_color?
+        ENV.key?("NO_COLOR")
+      end
+
+      # Checks if color output is explicitly forced.
+      #
+      # Some CI systems and logging pipelines detect non-TTY and strip
+      # colors. Users want colors anyway for readability. <tt>FORCE_COLOR</tt>
+      # overrides the TTY check.
+      #
+      # This method checks for <tt>FORCE_COLOR</tt> in the environment.
+      # When set, your app should emit colors even when <tt>tty?</tt>
+      # returns false.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   use_color = RatatuiRuby::Terminal.tty? ||
+      #               RatatuiRuby::Terminal.force_color?
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def force_color?
+        ENV.key?("FORCE_COLOR")
+      end
+
+      # Checks if the terminal supports interactive TUI mode.
+      #
+      # A TUI needs a real terminal. Piped output breaks cursor control.
+      # Dumb terminals corrupt escape sequences. Starting TUI mode in
+      # these environments wastes resources and confuses users.
+      #
+      # This method combines <tt>tty?</tt> and <tt>dumb?</tt> checks.
+      # Returns +true+ only when both conditions allow TUI operation.
+      # Use it as the gatekeeper before calling <tt>run</tt>.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if RatatuiRuby::Terminal.interactive?
+      #     RatatuiRuby.run { |tui| main_loop(tui) }
+      #   else
+      #     abort "Interactive terminal required"
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def interactive?
+        tty? && !dumb?
+      end
+
+      # Queries how many colors the terminal can display.
+      #
+      # Modern terminals vary wildly in capability. Some only support 8 ANSI
+      # colors. Others display 256. High-end terminals render 16 million
+      # truecolor shades. If your app uses rich color palettes without
+      # checking, users on basic terminals see garbled output or crashes.
+      #
+      # This method queries crossterm (which checks <tt>COLORTERM</tt> and
+      # <tt>TERM</tt>) and returns the raw count. Use it to select color
+      # palettes or degrade gracefully.
+      #
+      # Returns 8, 256, or 65535 (truecolor).
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   colors = RatatuiRuby::Terminal.available_color_count
+      #   palette = colors >= 256 ? :rich : :basic
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def available_color_count
+        _available_color_count
+      end
+
+      # Returns the terminal's color capability as a symbol.
+      #
+      # Comparing integers is annoying. You want to know: can I use
+      # gradients? Do I need a fallback palette? This method translates
+      # the raw count into semantic symbols.
+      #
+      # Returns <tt>:none</tt> when <tt>NO_COLOR</tt> is set or terminal is
+      # dumb. Returns <tt>:basic</tt> (8 colors), <tt>:ansi256</tt> (256),
+      # or <tt>:truecolor</tt> (16M) based on capability.
+      #
+      # Use it to switch rendering strategies or skip color entirely.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   case RatatuiRuby::Terminal.color_support
+      #   when :truecolor then use_gradient_theme
+      #   when :ansi256   then use_256_palette
+      #   when :basic     then use_ansi_colors
+      #   when :none      then use_monochrome
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def color_support
+        return :none if no_color?
+        return :none if dumb?
+
+        count = available_color_count
+        return :truecolor if count >= 65_535
+        return :ansi256 if count >= 256
+
+        :basic
+      end
+
+      # Checks for Kitty keyboard protocol support.
+      #
+      # Standard terminal input is ambiguous. Escape key and arrow keys
+      # share prefixes. Modifier keys get lost. Applications that need
+      # precise key handling (editors, games) struggle with the limitations.
+      #
+      # The Kitty keyboard protocol solves this. Terminals that support it
+      # report key presses unambiguously, with full modifier information.
+      # This method queries support so you can enable enhanced input or
+      # fall back gracefully.
+      #
+      # Returns <tt>false</tt> immediately if <tt>tty?</tt> returns false.
+      # Otherwise queries crossterm with a 0.5s timeout.
+      # Returns <tt>true</tt> only if the terminal responds affirmatively.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if RatatuiRuby::Terminal.supports_keyboard_enhancement?
+      #     enable_vim_style_keybindings
+      #   else
+      #     use_simple_navigation
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def supports_keyboard_enhancement?
+        return false unless tty?
+
+        Timeout.timeout(0.5) { _supports_keyboard_enhancement }
+      rescue
+        false
+      end
+
+      # Globally override NO_COLOR detection.
+      #
+      # The NO_COLOR environment variable tells applications to disable color.
+      # Sometimes users want colors anyway, like in CI pipelines that log to
+      # files but display logs with color. Passing +true+ forces color output
+      # regardless of NO_COLOR.
+      #
+      # This method calls crossterm's global override. The effect is immediate
+      # and affects all subsequent color detection queries. Pass +false+ to
+      # restore normal NO_COLOR behavior.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   if options[:color] == :always
+      #     RatatuiRuby::Terminal.force_color_output(true)
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def force_color_output(enable)
+        _force_color_output(enable)
+      end
+    end
+
+    extend Capabilities
+  end
+end

data/lib/ratatui_ruby/terminal/viewport.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  ##
+  # Terminal configuration and viewport settings.
+  #
+  # Your app needs to choose how it occupies the terminal.
+  # Fullscreen apps take over the whole screen and clear on exit.
+  # Inline apps run in a fixed region and persist in scrollback.
+  # Configuring this manually is error-prone.
+  #
+  # This module handles the choice. It defines viewport modes and their parameters.
+  #
+  # @see Terminal::Viewport
+  class Terminal
+    ##
+    # Viewport configuration for terminal initialization.
+    #
+    # Determines how RatatuiRuby interacts with the terminal:
+    # - **Fullscreen**: Uses alternate screen, clears on exit (default)
+    # - **Inline**: Fixed-height region, persists in scrollback after exit
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Fullscreen (default behavior)
+    #   RatatuiRuby.run { |tui| ... }
+    #
+    #   # Inline with 8 lines
+    #   RatatuiRuby.run(viewport: :inline, height: 8) { |tui| ... }
+    #--
+    # SPDX-SnippetEnd
+    #++
+    class Viewport < Data.define(:type, :height)
+      ##
+      # Creates a fullscreen viewport (alternate screen).
+      def self.fullscreen
+        new(type: :fullscreen)
+      end
+
+      ##
+      # Creates an inline viewport with the given height.
+      def self.inline(height)
+        new(type: :inline, height:)
+      end
+
+      ##
+      # Creates a new viewport configuration.
+      #
+      # [type] Symbol representing viewport type (:fullscreen or :inline).
+      # [height] Integer height in lines (required for :inline, ignored for :fullscreen).
+      #
+      # Most developers use {.fullscreen} or {.inline} factory methods instead.
+      def initialize(type:, height: nil)
+        super
+      end
+
+      ##
+      # Returns true if this is a fullscreen viewport.
+      def fullscreen?
+        type == :fullscreen
+      end
+
+      ##
+      # Returns true if this is an inline viewport.
+      def inline?
+        type == :inline
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/terminal.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require_relative "terminal/capabilities"
+
+module RatatuiRuby
+  # Terminal object for managing terminal lifecycle and rendering.
+  #
+  # Instance-based API aligned with upstream Ratatui Terminal struct.
+  #
+  # === Example
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   terminal = RatatuiRuby::Terminal.new
+  #   terminal.draw { |frame| ... }
+  #   terminal.restore
+  #--
+  # SPDX-SnippetEnd
+  #++
+  class Terminal
+    ##
+    # :attr_reader: terminal_id
+    # Unique identifier for this terminal instance in Rust (Integer).
+    attr_reader :terminal_id
+
+    # Creates a new Terminal instance.
+    #
+    # [viewport] Symbol or Viewport object (:fullscreen or :inline)
+    # [height] Integer height for inline viewports
+    def initialize(viewport: :fullscreen, height: nil)
+      @viewport = resolve_viewport(viewport, height)
+
+      # Call Rust FFI to create instance and get ID
+      # For now, only test backend is supported (real crossterm coming later)
+      @terminal_id = self.class._init_test_terminal_instance(
+        80, # default width for test
+        24, # default height for test
+        @viewport.type.to_s,
+        @viewport.height
+      )
+    end
+
+    # Returns the terminal size as a Layout::Rect
+    # Rust constructs the Rect object directly (not a hash!)
+    def size
+      self.class._get_terminal_size_instance(@terminal_id)
+    end
+
+    private def resolve_viewport(viewport, height)
+      case viewport
+      when nil, :fullscreen then Terminal::Viewport.fullscreen
+      when :inline then Terminal::Viewport.inline(height || 8)
+      when Terminal::Viewport then viewport
+      else raise ArgumentError, "Unknown viewport: #{viewport.inspect}"
+      end
+    end
+  end
+end