rubytui 1.2.3

data/lib/rubytui/modifier.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Text modifier flags stored as a bitmask on {Style#modifiers}.
+  #
+  # @example Check if bold is set
+  #   Modifier.contains?(style.modifiers, Modifier::BOLD)
+  #
+  # @example Or use Style query methods
+  #   style.bold?
+  module Modifier
+    # Bold text (SGR 1, cleared by SGR 22).
+    BOLD          = 0b000001
+    # Dim / faint text (SGR 2, cleared by SGR 22).
+    DIM           = 0b000010
+    # Italic text (SGR 3, cleared by SGR 23).
+    ITALIC        = 0b000100
+    # Underlined text (SGR 4, cleared by SGR 24).
+    UNDERLINED    = 0b001000
+    # Reverse video: swap foreground and background (SGR 7, cleared by SGR 27).
+    REVERSED      = 0b010000
+    # Strikethrough text (SGR 9, cleared by SGR 29).
+    STRIKETHROUGH = 0b100000
+
+    # No modifiers set.
+    NONE = 0
+
+    # Map of flag => human-readable name.
+    ALL = {
+      BOLD => "bold",
+      DIM => "dim",
+      ITALIC => "italic",
+      UNDERLINED => "underlined",
+      REVERSED => "reversed",
+      STRIKETHROUGH => "strikethrough"
+    }.freeze
+
+    # ANSI SGR codes for enabling modifiers.
+    SGR_ON = {
+      BOLD => "1",
+      DIM => "2",
+      ITALIC => "3",
+      UNDERLINED => "4",
+      REVERSED => "7",
+      STRIKETHROUGH => "9"
+    }.freeze
+
+    # ANSI SGR codes for disabling modifiers.
+    SGR_OFF = {
+      BOLD => "22",
+      DIM => "22",
+      ITALIC => "23",
+      UNDERLINED => "24",
+      REVERSED => "27",
+      STRIKETHROUGH => "29"
+    }.freeze
+
+    class << self
+      # Check if a modifier flag is set in a bitmask.
+      #
+      # @param modifiers [Integer] the bitmask to check
+      # @param flag [Integer] the modifier constant (e.g., {BOLD})
+      # @return [Boolean]
+      def contains?(modifiers, flag) = modifiers.anybits?(flag)
+    end
+  end
+end

data/lib/rubytui/rect.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # A rectangle defined by position and size, used throughout the layout
+  # and rendering system to define widget areas.
+  #
+  # @example Create with keyword arguments
+  #   Rect.new(x: 0, y: 0, width: 80, height: 24)
+  #
+  # @example Create with positional arguments
+  #   Rect.new(0, 0, 80, 24)
+  class Rect
+    attr_reader :x, :y, :width, :height
+
+    # Create a new Rect.
+    #
+    # Supports both positional and keyword arguments.
+    #
+    # @overload initialize(x, y, width, height)
+    #   @param x [Integer] left edge position
+    #   @param y [Integer] top edge position
+    #   @param width [Integer] width (clamped to >= 0)
+    #   @param height [Integer] height (clamped to >= 0)
+    #
+    # @overload initialize(x:, y:, width:, height:)
+    #   @param x [Integer] left edge position
+    #   @param y [Integer] top edge position
+    #   @param width [Integer] width (clamped to >= 0)
+    #   @param height [Integer] height (clamped to >= 0)
+    #
+    # @raise [ArgumentError] if argument format is invalid
+    def initialize(*args, x: nil, y: nil, width: nil, height: nil)
+      if args.length == 4
+        @x, @y, w, h = args
+      elsif args.empty? && x && y && width && height
+        @x = x
+        @y = y
+        w = width
+        h = height
+      else
+        raise ArgumentError, "Rect.new(x, y, width, height) or Rect.new(x:, y:, width:, height:)"
+      end
+      @width = [w, 0].max
+      @height = [h, 0].max
+    end
+
+    # @return [Integer] right edge (x + width)
+    def right  = @x + @width
+    # @return [Integer] bottom edge (y + height)
+    def bottom = @y + @height
+    # @return [Integer] left edge (alias for {#x})
+    def left   = @x
+    # @return [Integer] top edge (alias for {#y})
+    def top    = @y
+    # @return [Integer] total cell count (width * height)
+    def area   = @width * @height
+    # @return [Boolean] true if width or height is zero
+    def empty? = @width == 0 || @height == 0
+
+    # Return a Rect inset by the given margin on all sides.
+    #
+    # @param margin [Integer] inset distance for all four sides
+    # @return [Rect] the inner rectangle
+    def inner(margin)
+      margin_h = [margin * 2, @width].min
+      margin_v = [margin * 2, @height].min
+      Rect.new(
+        x: @x + margin_h / 2,
+        y: @y + margin_v / 2,
+        width: @width - margin_h,
+        height: @height - margin_v
+      )
+    end
+
+    # Return a Rect inset by individual margins per side.
+    #
+    # @param top [Integer] inset from top
+    # @param right [Integer] inset from right
+    # @param bottom [Integer] inset from bottom
+    # @param left [Integer] inset from left
+    # @return [Rect] the inner rectangle
+    def inner_rect(top: 0, right: 0, bottom: 0, left: 0)
+      Rect.new(
+        x: @x + left,
+        y: @y + top,
+        width: @width - left - right,
+        height: @height - top - bottom
+      )
+    end
+
+    # Value equality: same position and size.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if +other+ is a Rect with equal x, y, width and height
+    def ==(other)
+      other.is_a?(Rect) && @x == other.x && @y == other.y &&
+        @width == other.width && @height == other.height
+    end
+    alias_method :eql?, :==
+
+    # @return [Integer] hash derived from x, y, width and height
+    def hash = [@x, @y, @width, @height].hash
+
+    # @return [String] human-readable form, e.g. <tt>Rect(0, 0, 80x24)</tt>
+    def to_s = "Rect(#{@x}, #{@y}, #{@width}x#{@height})"
+    # @return [String] same as {#to_s}
+    def inspect = to_s
+
+    # Shorthand positional constructor.
+    #
+    # @example
+    #   Rect[0, 0, 80, 24]
+    #
+    # @param x [Integer] left edge
+    # @param y [Integer] top edge
+    # @param width [Integer] width
+    # @param height [Integer] height
+    # @return [Rect]
+    def self.[](x, y, width, height)
+      new(x, y, width, height)
+    end
+
+    # Empty rectangle at the origin (0, 0, 0x0).
+    ZERO = new(x: 0, y: 0, width: 0, height: 0).freeze
+  end
+end

data/lib/rubytui/stateful_widget.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # StatefulWidget protocol for widgets with external state.
+  # State persists across frames and is owned by the application, not the widget.
+  module StatefulWidget
+    # Render this widget with external state.
+    #
+    # Including classes override this method.
+    #
+    # @param area [Rect] the rectangular area to render into
+    # @param buf [Buffer] the buffer to write cells into
+    # @param state [Object] external state object
+    # @return [void]
+    # @raise [NotImplementedError] always, unless overridden by the including class
+    def render(area, buf, state)
+      raise NotImplementedError, "#{self.class}#render(area, buf, state) not implemented"
+    end
+  end
+end

data/lib/rubytui/style.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Composable text style with foreground/background colors and modifiers.
+  #
+  # Style is immutable — builder methods return new Style instances.
+  # Use {#patch} to merge styles for overlay composition.
+  #
+  # @example Builder pattern
+  #   style = Style.new.fg(Color::RED).bold.italic
+  #
+  # @example Merge styles
+  #   base = Style.new.fg(Color::WHITE)
+  #   highlight = Style.new.bold.underlined
+  #   combined = base.patch(highlight)  # white, bold, underlined
+  class Style
+    # @return [Integer] modifier bitmask (see {Modifier} constants)
+    attr_reader :modifiers
+
+    # Sentinel for unset color arguments. Private — not part of the public API.
+    UNSET = Object.new.freeze
+    private_constant :UNSET
+
+    # @param fg [Color, nil] foreground color
+    # @param bg [Color, nil] background color
+    # @param modifiers [Integer] modifier bitmask (default: {Modifier::NONE})
+    def initialize(fg: nil, bg: nil, modifiers: Modifier::NONE)
+      @fg = fg
+      @bg = bg
+      @modifiers = modifiers
+    end
+
+    # Get or set the foreground color.
+    #
+    # @overload fg
+    #   @return [Color, nil] current foreground color
+    #
+    # @overload fg(color)
+    #   @param color [Color] new foreground color
+    #   @return [Style] new Style with the given foreground color
+    def fg(color = UNSET)
+      return @fg if color.equal?(UNSET)
+
+      Style.new(fg: color, bg: @bg, modifiers: @modifiers)
+    end
+
+    # Get or set the background color.
+    #
+    # @overload bg
+    #   @return [Color, nil] current background color
+    #
+    # @overload bg(color)
+    #   @param color [Color] new background color
+    #   @return [Style] new Style with the given background color
+    def bg(color = UNSET)
+      return @bg if color.equal?(UNSET)
+
+      Style.new(fg: @fg, bg: color, modifiers: @modifiers)
+    end
+
+    # @!group Modifier Builders
+    # Each returns a new Style with the modifier flag added.
+
+    # @return [Style] new Style with bold enabled
+    def bold             = add_modifier(Modifier::BOLD)
+    # @return [Style] new Style with dim enabled
+    def dim              = add_modifier(Modifier::DIM)
+    # @return [Style] new Style with italic enabled
+    def italic           = add_modifier(Modifier::ITALIC)
+    # @return [Style] new Style with underline enabled
+    def underlined       = add_modifier(Modifier::UNDERLINED)
+    # @return [Style] new Style with reverse video enabled
+    def reversed         = add_modifier(Modifier::REVERSED)
+    # @return [Style] new Style with strikethrough enabled
+    def strikethrough    = add_modifier(Modifier::STRIKETHROUGH)
+
+    # @!endgroup
+
+    # @!group Modifier Queries
+
+    # @return [Boolean] true if bold is enabled
+    def bold?            = Modifier.contains?(@modifiers, Modifier::BOLD)
+    # @return [Boolean] true if dim is enabled
+    def dim?             = Modifier.contains?(@modifiers, Modifier::DIM)
+    # @return [Boolean] true if italic is enabled
+    def italic?          = Modifier.contains?(@modifiers, Modifier::ITALIC)
+    # @return [Boolean] true if underline is enabled
+    def underlined?      = Modifier.contains?(@modifiers, Modifier::UNDERLINED)
+    # @return [Boolean] true if reverse video is enabled
+    def reversed?        = Modifier.contains?(@modifiers, Modifier::REVERSED)
+    # @return [Boolean] true if strikethrough is enabled
+    def strikethrough?   = Modifier.contains?(@modifiers, Modifier::STRIKETHROUGH)
+
+    # @!endgroup
+
+    # Add a modifier flag.
+    #
+    # @param mod [Integer] modifier constant from {Modifier}
+    # @return [Style] new Style with the flag added
+    def add_modifier(mod)
+      Style.new(fg: @fg, bg: @bg, modifiers: @modifiers | mod)
+    end
+
+    # Remove a modifier flag.
+    #
+    # @param mod [Integer] modifier constant from {Modifier}
+    # @return [Style] new Style with the flag removed
+    def remove_modifier(mod)
+      Style.new(fg: @fg, bg: @bg, modifiers: @modifiers & ~mod)
+    end
+
+    # Merge another style on top of this one.
+    #
+    # The other style's non-nil colors override this style's colors.
+    # Modifiers are OR'd together (additive).
+    #
+    # @param other [Style] style to merge on top
+    # @return [Style] merged style
+    def patch(other)
+      Style.new(
+        fg: other.fg || @fg,
+        bg: other.bg || @bg,
+        modifiers: @modifiers | other.modifiers
+      )
+    end
+
+    # Value equality: same colors and modifiers.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if +other+ is a Style with equal foreground,
+    #   background and {#modifiers}
+    def ==(other)
+      other.is_a?(Style) && @fg == other.fg && @bg == other.bg && @modifiers == other.modifiers
+    end
+    alias_method :eql?, :==
+
+    # @return [Integer] hash derived from foreground, background and modifiers
+    def hash = [@fg, @bg, @modifiers].hash
+
+    # Default style: no colors, no modifiers.
+    DEFAULT = new.freeze
+  end
+end

data/lib/rubytui/symbols.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Predefined box-drawing glyph sets for widget borders.
+  #
+  # @example
+  #   Widgets::Block.new(borders: :all, border_set: Symbols::DOUBLE)
+  module Symbols
+    # Immutable set of the glyphs used to draw a border.
+    #
+    # @!attribute [r] top_left
+    #   @return [String] top-left corner glyph
+    # @!attribute [r] top_right
+    #   @return [String] top-right corner glyph
+    # @!attribute [r] bottom_left
+    #   @return [String] bottom-left corner glyph
+    # @!attribute [r] bottom_right
+    #   @return [String] bottom-right corner glyph
+    # @!attribute [r] horizontal
+    #   @return [String] horizontal line glyph
+    # @!attribute [r] vertical
+    #   @return [String] vertical line glyph
+    # @!attribute [r] cross
+    #   @return [String] four-way junction glyph
+    # @!attribute [r] tee_left
+    #   @return [String] T-junction glyph with its branch pointing left
+    # @!attribute [r] tee_right
+    #   @return [String] T-junction glyph with its branch pointing right
+    # @!attribute [r] tee_top
+    #   @return [String] T-junction glyph with its branch pointing up
+    # @!attribute [r] tee_bottom
+    #   @return [String] T-junction glyph with its branch pointing down
+    BorderSet = Data.define(
+      :top_left, :top_right, :bottom_left, :bottom_right,
+      :horizontal, :vertical,
+      :cross,
+      :tee_left, :tee_right, :tee_top, :tee_bottom
+    )
+
+    # ASCII-only borders using <tt>+</tt>, <tt>-</tt> and <tt>|</tt>.
+    PLAIN = BorderSet.new(
+      top_left: "+", top_right: "+", bottom_left: "+", bottom_right: "+",
+      horizontal: "-", vertical: "|",
+      cross: "+",
+      tee_left: "+", tee_right: "+", tee_top: "+", tee_bottom: "+"
+    ).freeze
+
+    # Light lines with rounded corners (╭ ╮ ╰ ╯).
+    ROUNDED = BorderSet.new(
+      top_left: "\u256D", top_right: "\u256E",   # ╭ ╮
+      bottom_left: "\u2570", bottom_right: "\u256F", # ╰ ╯
+      horizontal: "\u2500", vertical: "\u2502",   # ─ │
+      cross: "\u253C",                             # ┼
+      tee_left: "\u2524", tee_right: "\u251C",     # ┤ ├
+      tee_top: "\u2534", tee_bottom: "\u252C"      # ┴ ┬
+    ).freeze
+
+    # Double lines (═ ║ ╔ ╗ ╚ ╝).
+    DOUBLE = BorderSet.new(
+      top_left: "\u2554", top_right: "\u2557",     # ╔ ╗
+      bottom_left: "\u255A", bottom_right: "\u255D", # ╚ ╝
+      horizontal: "\u2550", vertical: "\u2551",     # ═ ║
+      cross: "\u256C",                               # ╬
+      tee_left: "\u2563", tee_right: "\u2560",       # ╣ ╠
+      tee_top: "\u2569", tee_bottom: "\u2566"        # ╩ ╦
+    ).freeze
+
+    # Heavy lines (━ ┃ ┏ ┓ ┗ ┛).
+    THICK = BorderSet.new(
+      top_left: "\u250F", top_right: "\u2513",     # ┏ ┓
+      bottom_left: "\u2517", bottom_right: "\u251B", # ┗ ┛
+      horizontal: "\u2501", vertical: "\u2503",     # ━ ┃
+      cross: "\u254B",                               # ╋
+      tee_left: "\u252B", tee_right: "\u2523",       # ┫ ┣
+      tee_top: "\u253B", tee_bottom: "\u2533"        # ┻ ┳
+    ).freeze
+
+    # Light lines with square corners (─ │ ┌ ┐ └ ┘).
+    LIGHT = BorderSet.new(
+      top_left: "\u250C", top_right: "\u2510",     # ┌ ┐
+      bottom_left: "\u2514", bottom_right: "\u2518", # └ ┘
+      horizontal: "\u2500", vertical: "\u2502",     # ─ │
+      cross: "\u253C",                               # ┼
+      tee_left: "\u2524", tee_right: "\u251C",       # ┤ ├
+      tee_top: "\u2534", tee_bottom: "\u252C"        # ┴ ┬
+    ).freeze
+  end
+end

data/lib/rubytui/terminal.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Orchestrates the rendering pipeline with double buffering.
+  #
+  # Terminal manages two buffers and diffs them each frame to send only
+  # changed cells to the backend. This is the core of the immediate-mode
+  # rendering system.
+  #
+  # @example Drawing a frame
+  #   terminal.draw do |frame|
+  #     frame.buffer.set_string(0, 0, "Hello!")
+  #     frame.render_widget(my_widget, frame.area)
+  #   end
+  class Terminal
+    # @return [Backend] the rendering backend (AnsiBackend or TestBackend)
+    attr_reader :backend
+
+    # Create a terminal that renders through +backend+.
+    #
+    # Allocates both buffers at the backend's current {Backend#size} and,
+    # where supported, installs a +SIGWINCH+ trap (replacing any existing
+    # handler) so the buffers are reallocated and the screen cleared on the
+    # next {#draw} after a resize.
+    #
+    # @param backend [Backend] the rendering backend
+    def initialize(backend:)
+      @backend = backend
+      @needs_resize = false
+      @current = 0
+      allocate_buffers
+      setup_resize_handler
+    end
+
+    # Main draw method — the heart of the rendering pipeline.
+    #
+    # Resets the current buffer, yields a {Frame} for the caller to render
+    # widgets into, diffs against the previous buffer, sends changes to
+    # the backend, and swaps buffers.
+    #
+    # The cursor is hidden while drawing and shown again only if the frame
+    # requested a position via {Frame#set_cursor_position}. Image
+    # placement changes are sent to the backend, and the backend is
+    # flushed before returning.
+    #
+    # @yield [frame] a Frame to render widgets into
+    # @yieldparam frame [Frame]
+    # @return [Frame] the rendered frame
+    def draw
+      check_resize
+
+      # A pending full repaint (image placements changed last frame, or
+      # force_redraw!): clear the screen and forget the previous buffer so
+      # every cell and image is re-emitted. Image pixels live on a layer
+      # separate from text cells, so placement changes can reveal stale
+      # terminal content that the cell diff alone cannot detect.
+      if @full_repaint
+        @full_repaint = false
+        @force_images = true
+        # Cells only — image placements must survive so deletions and
+        # changes still diff correctly against the previous frame.
+        previous_buffer.reset_cells!
+        @backend.clear
+      end
+
+      # Reset the current (next) buffer
+      current_buffer.reset!
+
+      # Create frame and yield to caller
+      frame = Frame.new(current_buffer, current_buffer.area)
+      yield frame
+
+      # Diff against the previous buffer
+      changes = current_buffer.diff(previous_buffer)
+
+      # Send changes to backend
+      @backend.hide_cursor
+      @backend.draw(changes)
+
+      # Handle image placements (Kitty graphics protocol)
+      draw_images(current_buffer, previous_buffer)
+
+      # Handle cursor position
+      if (pos = frame.cursor_position)
+        @backend.show_cursor
+        @backend.move_cursor(pos[0], pos[1])
+      end
+
+      @backend.flush
+
+      # Swap buffers
+      @current = 1 - @current
+
+      frame
+    end
+
+    # Get current terminal size as a Rect.
+    #
+    # @return [Rect] a Rect at origin with terminal dimensions
+    def size
+      w, h = @backend.size
+      Rect.new(x: 0, y: 0, width: w, height: h)
+    end
+
+    # Get cell pixel dimensions for aspect-ratio calculations.
+    #
+    # Queries the terminal via CSI 16 t if not already cached.
+    # Use this with {Widgets::Image.fit_area} for proper image sizing.
+    #
+    # @return [Array(Integer, Integer)] cell dimensions [width_px, height_px]
+    def cell_pixel_size
+      @backend.query_cell_pixel_size
+    end
+
+    # Clear all Kitty graphics protocol images.
+    #
+    # Useful during transitions or when precise tracking isn't possible.
+    #
+    # @return [void]
+    def clear_all_images!
+      @backend.clear_all_images!
+    end
+
+    # Delegate alternate screen management to backend.
+    # @return [void]
+    def enter_alternate_screen
+      @backend.enter_alternate_screen
+    end
+
+    # Leave the alternate screen buffer via the backend.
+    #
+    # @return [void]
+    def leave_alternate_screen
+      @backend.leave_alternate_screen
+    end
+
+    # Force a full redraw on the next {#draw} call.
+    #
+    # The next frame clears the screen, re-sends every cell, and
+    # re-transmits current image placements.
+    #
+    # @return [void]
+    def force_redraw!
+      @full_repaint = true
+    end
+
+    private
+
+    def current_buffer  = @buffers[@current]
+    def previous_buffer = @buffers[1 - @current]
+
+    def allocate_buffers
+      w, h = @backend.size
+      area = Rect.new(x: 0, y: 0, width: w, height: h)
+      @buffers = [Buffer.new(area), Buffer.new(area)]
+    end
+
+    def setup_resize_handler
+      Signal.trap("WINCH") do
+        @needs_resize = true
+      end
+    rescue ArgumentError, SignalException
+      # Signal not available on this platform (e.g., Windows)
+    end
+
+    def draw_images(current, previous)
+      force = @force_images
+      @force_images = false
+
+      prev_placements = previous.image_placements
+      curr_placements = current.image_placements
+      changed = false
+
+      # Delete images that are no longer present or have changed.
+      # Keys include content_hash, so same-position different-content
+      # will have different keys and trigger proper delete + redraw.
+      prev_placements.each do |key, prev_placement|
+        unless curr_placements.key?(key)
+          @backend.delete_kitty_image(prev_placement)
+          changed = true
+        end
+      end
+
+      # Transmit new or changed images
+      curr_placements.each do |key, placement|
+        prev = prev_placements[key]
+
+        # Identical placement (same key means same content hash): only
+        # re-transmit when a full repaint cleared the screen.
+        identical = prev &&
+                    prev[:cols] == placement[:cols] &&
+                    prev[:rows] == placement[:rows] &&
+                    prev[:src_x] == placement[:src_x] &&
+                    prev[:src_y] == placement[:src_y] &&
+                    prev[:src_w] == placement[:src_w] &&
+                    prev[:src_h] == placement[:src_h]
+        changed = true unless identical
+        next if identical && !force
+
+        @backend.draw_kitty_image(placement)
+      end
+
+      # Placement changes can reveal stale terminal content beneath the
+      # old image area — schedule a one-off full repaint for the next frame.
+      @full_repaint = true if changed
+    end
+
+    def check_resize
+      return unless @needs_resize
+
+      @needs_resize = false
+      @current = 0
+      allocate_buffers
+      @backend.clear
+      @backend.flush
+    end
+  end
+end