ratatui_ruby 1.0.0 → 1.1.0

data/lib/ratatui_ruby/layout/alignment.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Layout
+    # Horizontal content alignment within a layout area.
+    #
+    # Use these constants for discoverability, or pass symbols directly
+    # (<tt>:left</tt>, <tt>:center</tt>, <tt>:right</tt>).
+    #
+    # Mirrors +ratatui::layout::HorizontalAlignment+ from upstream Ratatui.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Using constants (discoverable)
+    #   paragraph = Paragraph.new(
+    #     text: "Hello",
+    #     alignment: HorizontalAlignment::CENTER
+    #   )
+    #
+    #   # Using symbols directly (idiomatic Ruby)
+    #   paragraph = Paragraph.new(text: "Hello", alignment: :center)
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module HorizontalAlignment
+      # Align content to the left edge.
+      LEFT = :left
+
+      # Align content to the center.
+      CENTER = :center
+
+      # Align content to the right edge.
+      RIGHT = :right
+
+      # All valid alignment values.
+      ALL = [LEFT, CENTER, RIGHT].freeze
+    end
+
+    # Vertical content alignment within a layout area.
+    #
+    # Use these constants for discoverability, or pass symbols directly
+    # (<tt>:top</tt>, <tt>:center</tt>, <tt>:bottom</tt>).
+    #
+    # Mirrors +ratatui::layout::VerticalAlignment+ from upstream Ratatui.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Using constants (discoverable)
+    #   widget.vertical_alignment = VerticalAlignment::CENTER
+    #
+    #   # Using symbols directly (idiomatic Ruby)
+    #   widget.vertical_alignment = :center
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module VerticalAlignment
+      # Align content to the top edge.
+      TOP = :top
+
+      # Align content to the center.
+      CENTER = :center
+
+      # Align content to the bottom edge.
+      BOTTOM = :bottom
+
+      # All valid alignment values.
+      ALL = [TOP, CENTER, BOTTOM].freeze
+    end
+
+    # Type alias for HorizontalAlignment.
+    #
+    # Provided for upstream API parity. In Ratatui, +Alignment+ was the
+    # original name before +HorizontalAlignment+ was introduced in v0.30.0.
+    Alignment = HorizontalAlignment
+  end
+end

data/lib/ratatui_ruby/layout/layout.rb

@@ -49,8 +49,7 @@ module RatatuiRuby
       #
       # One of <tt>:legacy</tt>, <tt>:start</tt>, <tt>:center</tt>, <tt>:end</tt>, <tt>:space_between</tt>, <tt>:space_around</tt>.
 
-      # :nodoc:
-      FLEX_MODES = %i[legacy start center end space_between space_around space_evenly].freeze
+      FLEX_MODES = %i[legacy start center end space_between space_around space_evenly].freeze # :nodoc:
 
       ##
       # Direction: split vertically (top to bottom).

data/lib/ratatui_ruby/layout/size.rb

@@ -7,7 +7,7 @@
 
 module RatatuiRuby
   module Layout
-    # Terminal dimensions as width and height.
+    # Generic dimensions as width and height.
     #
     # Layout calculations need sizes. Passing width and height
     # as separate arguments is verbose and easy to swap by mistake.
@@ -15,6 +15,13 @@ module RatatuiRuby
     # This class bundles dimensions into a single immutable object.
     # Extract it from a Rect or create it directly for sizing operations.
     #
+    # Following upstream Ratatui's design, the same Size type represents
+    # both character-grid dimensions (columns × rows) and pixel dimensions.
+    # The semantic meaning depends on the source:
+    #
+    # - From <tt>Terminal.size</tt> or <tt>WindowSize#columns_rows</tt>: columns and rows
+    # - From <tt>WindowSize#pixels</tt>: pixel width and height
+    #
     # Use it for terminal dimensions, widget sizing constraints,
     # or anywhere you need width/height without position.
     #
@@ -37,11 +44,11 @@ module RatatuiRuby
     class Size < Data.define(:width, :height)
       ##
       # :attr_reader: width
-      # Width in terminal columns.
+      # Width dimension (columns for character grids, pixels for pixel sizes).
 
       ##
       # :attr_reader: height
-      # Height in terminal rows.
+      # Height dimension (rows for character grids, pixels for pixel sizes).
 
       # Creates a new Size.
       #

data/lib/ratatui_ruby/layout.rb

@@ -14,10 +14,14 @@ module RatatuiRuby
   # - {Size} — Terminal dimensions
   # - {Constraint} — Sizing rules
   # - {Layout} — Space distribution
+  # - {HorizontalAlignment} — Horizontal alignment constants
+  # - {VerticalAlignment} — Vertical alignment constants
+  # - {Alignment} — Alias for HorizontalAlignment
   module Layout
   end
 end
 
+require_relative "layout/alignment"
 require_relative "layout/rect"
 require_relative "layout/position"
 require_relative "layout/size"

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

@@ -17,7 +17,7 @@ module RatatuiRuby
   # This module handles the choice. It defines viewport modes and their parameters.
   #
   # @see Terminal::Viewport
-  module Terminal
+  class Terminal
     ##
     # Viewport configuration for terminal initialization.
     #

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

data/lib/ratatui_ruby/test_helper/global_state.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module TestHelper
+    ##
+    # Helpers for testing code that reads global state.
+    #
+    # Applications often read +ARGV+ and +ENV+ at startup. Testing these code
+    # paths requires stubbing those constants. Doing it manually is brittle —
+    # tests that forget to restore the original values leak state.
+    #
+    # These helpers swap the constants, yield to the block, and restore the
+    # originals automatically.
+    #
+    # == Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   def test_parses_command_line_flags
+    #     with_argv(["--verbose", "--log=debug.log"]) do
+    #       app = MyApp.new
+    #       assert app.verbose?
+    #       assert_equal "debug.log", app.log_path
+    #     end
+    #   end
+    #
+    #   def test_reads_api_key_from_environment
+    #     with_env("API_KEY", "test-key-1234") do
+    #       client = APIClient.new
+    #       assert_equal "test-key-1234", client.api_key
+    #     end
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    module GlobalState
+      # Temporarily replaces ARGV for the duration of the block.
+      #
+      # [argv] An array of strings to use as ARGV.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   with_argv(["--help"]) do
+      #     # Code here sees ARGV as ["--help"]
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def with_argv(argv)
+        original_argv = ARGV.dup
+        ARGV.replace(argv)
+        yield
+      ensure
+        ARGV.replace(original_argv)
+      end
+
+      # Temporarily replaces an environment variable for the duration of the block.
+      #
+      # If +value+ is +nil+, the variable is deleted for the block's duration.
+      #
+      # [key] The environment variable name (String).
+      # [value] The value to set, or +nil+ to delete.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   with_env("DEBUG", "1") do
+      #     # Code here sees ENV["DEBUG"] as "1"
+      #   end
+      #
+      #   with_env("DEBUG", nil) do
+      #     # Code here does not see ENV["DEBUG"]
+      #   end
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def with_env(key, value)
+        original_value = ENV[key]
+        if value.nil?
+          ENV.delete(key)
+        else
+          ENV[key] = value
+        end
+        yield
+      ensure
+        if original_value.nil?
+          ENV.delete(key)
+        else
+          ENV[key] = original_value
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/test_helper.rb

@@ -11,6 +11,7 @@ require_relative "test_helper/snapshot"
 require_relative "test_helper/event_injection"
 require_relative "test_helper/style_assertions"
 require_relative "test_helper/test_doubles"
+require_relative "test_helper/global_state"
 
 module RatatuiRuby
   ##
@@ -30,6 +31,7 @@ module RatatuiRuby
   # [EventInjection] Simulates keypresses, mouse clicks, and resize events.
   # [StyleAssertions] Checks foreground color, background color, and text modifiers.
   # [TestDoubles] Provides mocks and stubs for testing views in isolation.
+  # [GlobalState] Provides with_argv and with_env helpers for testing global state access.
   #
   # == Example
   #
@@ -106,5 +108,6 @@ module RatatuiRuby
     include EventInjection
     include StyleAssertions
     include TestDoubles
+    include GlobalState
   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.0.0"
+  VERSION = "1.1.0"
 end