rubytui 1.2.3

data/lib/rubytui/color_mode.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Detects and manages terminal color capabilities.
+  #
+  # @example
+  #   ColorMode.force(ColorMode::COLOR256)
+  #   ColorMode.downgrade(Color.rgb(255, 128, 0))  # => Color.indexed(214)
+  module ColorMode
+    # Basic 16-color ANSI palette.
+    BASIC16   = :basic16
+    # 256-color indexed palette.
+    COLOR256  = :color256
+    # 24-bit RGB truecolor.
+    TRUECOLOR = :truecolor
+
+    class << self
+      # Detect terminal color capability from environment variables.
+      #
+      # Returns {TRUECOLOR} when +COLORTERM+ is +truecolor+ or +24bit+, +TERM+
+      # contains +24bit+ or +truecolor+, or +TERM_PROGRAM+ is one of
+      # +iterm.app+, +hyper+, +wezterm+, +alacritty+, +kitty+;
+      # {COLOR256} when +TERM+ contains +256color+ or +COLORTERM+ is +256+;
+      # otherwise {BASIC16}. All comparisons are case-insensitive. The result
+      # is cached until {.reset!}, and {.force} overrides it.
+      #
+      # @return [Symbol] the detected (or forced) color mode
+      def detect
+        return @detected if defined?(@detected)
+
+        @detected = detect_from_env
+      end
+
+      # Reset cached detection (for testing)
+      #
+      # @return [void]
+      def reset!
+        remove_instance_variable(:@detected) if defined?(@detected)
+      end
+
+      # Force a specific color mode
+      #
+      # Replaces the cached value returned by {.detect} until {.reset!}.
+      #
+      # @param mode [Symbol] color mode to report, normally {BASIC16},
+      #   {COLOR256} or {TRUECOLOR}
+      # @return [Symbol] +mode+
+      def force(mode)
+        @detected = mode
+      end
+
+      # Downgrade a Color to fit the current terminal capability.
+      #
+      # {TRUECOLOR} (or an unrecognized mode) returns +color+ unchanged.
+      # {COLOR256} maps RGB colors to the nearest indexed color. {BASIC16}
+      # maps RGB and indexed colors to the nearest named color. Colors that
+      # already fit the mode are returned unchanged.
+      #
+      # @param color [Color, nil] color to convert
+      # @param mode [Symbol] target color mode (default: {.detect})
+      # @return [Color, nil] the converted color, or nil if +color+ is nil
+      def downgrade(color, mode = detect)
+        return color if color.nil?
+
+        case mode
+        when TRUECOLOR
+          color  # no downgrade needed
+        when COLOR256
+          downgrade_to_256(color)
+        when BASIC16
+          downgrade_to_16(color)
+        else
+          color
+        end
+      end
+
+      private
+
+      def detect_from_env
+        colorterm = ENV["COLORTERM"]&.downcase
+        term = ENV["TERM"]&.downcase || ""
+        term_program = ENV["TERM_PROGRAM"]&.downcase || ""
+
+        # Truecolor detection
+        if colorterm == "truecolor" || colorterm == "24bit"
+          return TRUECOLOR
+        end
+
+        if term.include?("24bit") || term.include?("truecolor")
+          return TRUECOLOR
+        end
+
+        # Known truecolor terminals
+        if %w[iterm.app hyper wezterm alacritty kitty].include?(term_program)
+          return TRUECOLOR
+        end
+
+        # 256 color detection
+        if term.include?("256color") || colorterm == "256"
+          return COLOR256
+        end
+
+        # Default to basic 16
+        BASIC16
+      end
+
+      # Convert RGB/truecolor to nearest 256-color index
+      def downgrade_to_256(color)
+        case color.kind
+        when :rgb
+          r, g, b = color.value
+          idx = rgb_to_256(r, g, b)
+          Color.indexed(idx)
+        else
+          color  # :named and :indexed already fit
+        end
+      end
+
+      # Convert any color to nearest basic 16 color
+      def downgrade_to_16(color)
+        case color.kind
+        when :rgb
+          r, g, b = color.value
+          rgb_to_named16(r, g, b)
+        when :indexed
+          indexed_to_named16(color.value)
+        else
+          color  # :named already fits
+        end
+      end
+
+      # Map RGB to nearest 256-color palette index
+      def rgb_to_256(r, g, b)
+        # Check grayscale ramp first (indices 232-255)
+        if r == g && g == b
+          return 16 if r < 8
+          return 231 if r > 248
+          return (((r - 8).to_f / 247) * 24).round + 232
+        end
+
+        # Map to 6x6x6 color cube (indices 16-231)
+        ri = (r.to_f / 255 * 5).round
+        gi = (g.to_f / 255 * 5).round
+        bi = (b.to_f / 255 * 5).round
+        16 + (36 * ri) + (6 * gi) + bi
+      end
+
+      # Map RGB to nearest named 16 color
+      def rgb_to_named16(r, g, b)
+        # Simple luminance-based mapping to basic 16
+        brightness = (r * 299 + g * 587 + b * 114) / 1000
+        bright = brightness > 128
+
+        # Determine dominant channel
+        max = [r, g, b].max
+        if max == 0
+          return bright ? Color::BRIGHT_BLACK : Color::BLACK
+        end
+
+        rn = r.to_f / max
+        gn = g.to_f / max
+        bn = b.to_f / max
+
+        if rn > 0.6 && gn > 0.6 && bn > 0.6
+          bright ? Color::WHITE : Color::BRIGHT_BLACK
+        elsif rn > 0.6 && gn > 0.6
+          bright ? Color::BRIGHT_YELLOW : Color::YELLOW
+        elsif rn > 0.6 && bn > 0.6
+          bright ? Color::BRIGHT_MAGENTA : Color::MAGENTA
+        elsif gn > 0.6 && bn > 0.6
+          bright ? Color::BRIGHT_CYAN : Color::CYAN
+        elsif rn > 0.5
+          bright ? Color::BRIGHT_RED : Color::RED
+        elsif gn > 0.5
+          bright ? Color::BRIGHT_GREEN : Color::GREEN
+        elsif bn > 0.5
+          bright ? Color::BRIGHT_BLUE : Color::BLUE
+        else
+          bright ? Color::BRIGHT_BLACK : Color::BLACK
+        end
+      end
+
+      # Map 256-color index to nearest named 16 color
+      def indexed_to_named16(idx)
+        if idx < 16
+          # Already a basic color
+          Color.new(:named, idx).freeze
+        elsif idx >= 232
+          # Grayscale ramp
+          level = (idx - 232) * 10 + 8
+          level > 128 ? Color::WHITE : Color::BRIGHT_BLACK
+        else
+          # 6x6x6 cube -> RGB -> named16
+          idx -= 16
+          b = (idx % 6) * 51
+          g = ((idx / 6) % 6) * 51
+          r = ((idx / 36) % 6) * 51
+          rgb_to_named16(r, g, b)
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Base class for all RubyTUI-specific errors.
+  class Error < StandardError; end
+  # Error category for terminal-related failures.
+  class TerminalError < Error; end
+  # Error category for layout-related failures.
+  class LayoutError < Error; end
+  # Raised by {Widgets::Image} when given image data in a format the Kitty
+  # graphics protocol path does not accept (JPEG, WebP, GIF or BMP).
+  class UnsupportedImageFormat < Error; end
+end

data/lib/rubytui/event.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Base class for input events: {KeyEvent}, {MouseEvent} and {ResizeEvent}.
+  class Event
+    # Base class for all events
+  end
+
+  # A keyboard event: key code, optional character and modifier flags.
+  #
+  # @example
+  #   event = KeyEvent.new(code: Input::Key::CHAR, char: "q", modifiers: Input::Key::CTRL)
+  #   event.ctrl?  # => true
+  #   event.to_s   # => "KeyEvent(Ctrl+q)"
+  class KeyEvent < Event
+    attr_reader :code, :char, :modifiers
+
+    # @param code [Symbol] key code, one of the {Input::Key} key-code constants
+    #   (e.g. {Input::Key::ENTER}, {Input::Key::CHAR})
+    # @param char [String, nil] the character, for {Input::Key::CHAR} events (default: nil)
+    # @param modifiers [Integer] bitmask of {Input::Key::SHIFT}, {Input::Key::ALT} and
+    #   {Input::Key::CTRL} (default: {Input::Key::NONE})
+    def initialize(code:, char: nil, modifiers: Input::Key::NONE)
+      @code = code
+      @char = char
+      @modifiers = modifiers
+    end
+
+    # @return [Boolean] true if the {Input::Key::CTRL} flag is set
+    def ctrl?  = (@modifiers & Input::Key::CTRL) != 0
+    # @return [Boolean] true if the {Input::Key::ALT} flag is set
+    def alt?   = (@modifiers & Input::Key::ALT) != 0
+    # @return [Boolean] true if the {Input::Key::SHIFT} flag is set
+    def shift? = (@modifiers & Input::Key::SHIFT) != 0
+
+    # Value equality: same code, character and modifiers.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if +other+ is a KeyEvent with equal {#code}, {#char}
+    #   and {#modifiers}
+    def ==(other)
+      other.is_a?(KeyEvent) && @code == other.code &&
+        @char == other.char && @modifiers == other.modifiers
+    end
+
+    # Human-readable form: modifier names, then the character (or the key
+    # code when there is no character), joined by <tt>+</tt>.
+    #
+    # @return [String] e.g. <tt>KeyEvent(Ctrl+q)</tt> or <tt>KeyEvent(enter)</tt>
+    def to_s
+      parts = []
+      parts << "Ctrl" if ctrl?
+      parts << "Alt" if alt?
+      parts << "Shift" if shift?
+      parts << (@char || @code.to_s)
+      "KeyEvent(#{parts.join("+")})"
+    end
+    alias_method :inspect, :to_s
+  end
+
+  # A mouse event: button, action, cell position and modifier flags.
+  #
+  # {Input::Parser} produces these from SGR (mode 1006) and legacy
+  # (<tt>ESC [ M</tt>) mouse reports, with 0-based cell coordinates.
+  class MouseEvent < Event
+    # @!group Mouse Buttons
+
+    # Left button.
+    LEFT      = :left
+    # Middle button.
+    MIDDLE    = :middle
+    # Right button.
+    RIGHT     = :right
+    # Scroll wheel up (reported with action {PRESS}).
+    SCROLL_UP   = :scroll_up
+    # Scroll wheel down (reported with action {PRESS}).
+    SCROLL_DOWN = :scroll_down
+    # No specific button (legacy-protocol release, or motion with no button held).
+    NONE      = :none
+
+    # @!endgroup
+
+    # @!group Mouse Actions
+
+    # Button pressed; also used for scroll-wheel events.
+    PRESS   = :press
+    # Button released.
+    RELEASE = :release
+    # Pointer motion reported by the terminal (motion flag set).
+    DRAG    = :drag
+    # Pointer motion with no button held. Currently never emitted by {Input::Parser}.
+    MOVE    = :move
+
+    # @!endgroup
+
+    attr_reader :button, :action, :x, :y, :modifiers
+
+    # @param button [Symbol] button constant ({LEFT}, {MIDDLE}, {RIGHT},
+    #   {SCROLL_UP}, {SCROLL_DOWN} or {NONE})
+    # @param action [Symbol] action constant ({PRESS}, {RELEASE}, {DRAG} or {MOVE})
+    # @param x [Integer] column (0-based cell coordinate)
+    # @param y [Integer] row (0-based cell coordinate)
+    # @param modifiers [Integer] bitmask of {Input::Key::SHIFT}, {Input::Key::ALT} and
+    #   {Input::Key::CTRL} (default: {Input::Key::NONE})
+    def initialize(button:, action:, x:, y:, modifiers: Input::Key::NONE)
+      @button = button
+      @action = action
+      @x = x
+      @y = y
+      @modifiers = modifiers
+    end
+
+    # @return [Boolean] true if the {Input::Key::CTRL} flag is set
+    def ctrl?  = (@modifiers & Input::Key::CTRL) != 0
+    # @return [Boolean] true if the {Input::Key::ALT} flag is set
+    def alt?   = (@modifiers & Input::Key::ALT) != 0
+    # @return [Boolean] true if the {Input::Key::SHIFT} flag is set
+    def shift? = (@modifiers & Input::Key::SHIFT) != 0
+
+    # Value equality: same button, action, position and modifiers.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if +other+ is a MouseEvent with equal {#button},
+    #   {#action}, {#x}, {#y} and {#modifiers}
+    def ==(other)
+      other.is_a?(MouseEvent) && @button == other.button &&
+        @action == other.action && @x == other.x && @y == other.y &&
+        @modifiers == other.modifiers
+    end
+
+    # Human-readable form: modifier names, then <tt>action(button)</tt>,
+    # joined by <tt>+</tt>, followed by the position.
+    #
+    # @return [String] e.g. <tt>MouseEvent(press(left) @10,5)</tt>
+    def to_s
+      parts = []
+      parts << "Ctrl" if ctrl?
+      parts << "Alt" if alt?
+      parts << "Shift" if shift?
+      parts << "#{@action}(#{@button})"
+      "MouseEvent(#{parts.join("+")} @#{@x},#{@y})"
+    end
+    alias_method :inspect, :to_s
+  end
+
+  # A terminal resize event carrying the new size in cells.
+  class ResizeEvent < Event
+    attr_reader :width, :height
+
+    # @param width [Integer] new width in columns
+    # @param height [Integer] new height in rows
+    def initialize(width:, height:)
+      @width = width
+      @height = height
+    end
+
+    # @return [String] human-readable form, e.g. <tt>ResizeEvent(80x24)</tt>
+    def to_s = "ResizeEvent(#{@width}x#{@height})"
+    alias_method :inspect, :to_s
+  end
+end

data/lib/rubytui/frame.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Rendering context yielded by {Terminal#draw} and {RubyTUI.render_once}.
+  #
+  # Frame wraps a {Buffer} and provides methods for rendering widgets.
+  # It is the primary interface for placing widgets during a draw call.
+  #
+  # @example Rendering widgets in a frame
+  #   terminal.draw do |frame|
+  #     frame.render_widget(block, frame.area)
+  #     frame.render_stateful_widget(list, chunks[1], list_state)
+  #   end
+  class Frame
+    # @return [Buffer] the buffer to render into
+    attr_reader :buffer
+    # @return [Rect] the total renderable area
+    attr_reader :area
+
+    # @param buffer [Buffer]
+    # @param area [Rect]
+    def initialize(buffer, area)
+      @buffer = buffer
+      @area = area
+      @cursor_position = nil
+    end
+
+    # Render a widget into a specific area of this frame.
+    #
+    # The widget must implement <tt>render(area, buf)</tt> (the {Widget} protocol).
+    #
+    # @param widget [#render] any object responding to <tt>render(area, buf)</tt>
+    # @param area [Rect] the area to render into
+    # @return [void]
+    def render_widget(widget, area)
+      widget.render(area, @buffer)
+    end
+
+    # Render a stateful widget with its state object.
+    #
+    # The widget must implement <tt>render(area, buf, state)</tt> (the {StatefulWidget} protocol).
+    #
+    # @param widget [#render] any object responding to <tt>render(area, buf, state)</tt>
+    # @param area [Rect] the area to render into
+    # @param state [Object] the widget's external state
+    # @return [void]
+    def render_stateful_widget(widget, area, state)
+      widget.render(area, @buffer, state)
+    end
+
+    # Request cursor placement at a specific position.
+    #
+    # Used by widgets like {Widgets::InputField} to position the terminal cursor.
+    #
+    # @param x [Integer] column position
+    # @param y [Integer] row position
+    # @return [void]
+    def set_cursor_position(x, y)
+      @cursor_position = [x, y]
+    end
+
+    # Get the requested cursor position.
+    #
+    # @return [Array(Integer, Integer), nil] [x, y] pair, or nil if not set
+    def cursor_position = @cursor_position
+
+    # @return [Rect] the total renderable area (alias for {#area})
+    def size = @area
+  end
+end

data/lib/rubytui/input/key.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Terminal input handling: key constants, byte-sequence {Parser} and
+  # non-blocking {Reader}.
+  module Input
+    # Key codes and modifier flags used by {KeyEvent} and {MouseEvent}.
+    #
+    # Key codes are Symbols stored in <tt>KeyEvent#code</tt>; modifier flags are
+    # Integer bits OR'd together in the +modifiers+ of {KeyEvent} and {MouseEvent}.
+    #
+    # @example
+    #   case event.code
+    #   when Input::Key::ENTER then submit
+    #   when Input::Key::CHAR  then insert(event.char)
+    #   end
+    module Key
+      # @!group Key Codes
+
+      # Character key; the character itself is in <tt>KeyEvent#char</tt>.
+      CHAR       = :char
+      # Enter / Return.
+      ENTER      = :enter
+      # Escape.
+      ESCAPE     = :escape
+      # Backspace.
+      BACKSPACE  = :backspace
+      # Delete (forward delete).
+      DELETE     = :delete
+      # Tab.
+      TAB        = :tab
+      # Shift+Tab (back-tab).
+      BACKTAB    = :backtab  # Shift+Tab
+      # Up arrow.
+      UP         = :up
+      # Down arrow.
+      DOWN       = :down
+      # Left arrow.
+      LEFT       = :left
+      # Right arrow.
+      RIGHT      = :right
+      # Home.
+      HOME       = :home
+      # End.
+      END_KEY    = :end
+      # Page Up.
+      PAGE_UP    = :page_up
+      # Page Down.
+      PAGE_DOWN  = :page_down
+      # Insert.
+      INSERT     = :insert
+      # Function key F1.
+      F1         = :f1
+      # Function key F2.
+      F2         = :f2
+      # Function key F3.
+      F3         = :f3
+      # Function key F4.
+      F4         = :f4
+      # Function key F5.
+      F5         = :f5
+      # Function key F6.
+      F6         = :f6
+      # Function key F7.
+      F7         = :f7
+      # Function key F8.
+      F8         = :f8
+      # Function key F9.
+      F9         = :f9
+      # Function key F10.
+      F10        = :f10
+      # Function key F11.
+      F11        = :f11
+      # Function key F12.
+      F12        = :f12
+
+      # @!endgroup
+
+      # @!group Modifier Flags
+
+      # No modifier keys held.
+      NONE  = 0
+      # Shift modifier bit.
+      SHIFT = 0b001
+      # Alt (Meta / Option) modifier bit.
+      ALT   = 0b010
+      # Ctrl modifier bit.
+      CTRL  = 0b100
+
+      # @!endgroup
+    end
+  end
+end