rubytui 1.2.3

data/lib/rubytui/buffer.rb

@@ -0,0 +1,400 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # 2D grid of styled {Cell}s used for rendering.
+  #
+  # Buffer is the core rendering target. Widgets write into a Buffer via
+  # {#set_string} and {#set_style}. The {Terminal} then diffs two buffers
+  # to send only changed cells to the backend.
+  #
+  # For one-shot CLI output, use {#to_ansi} or {#print} to convert the
+  # buffer contents to an ANSI-styled string without needing a Terminal.
+  #
+  # @example Create and render text
+  #   buf = Buffer.new(80, 24)
+  #   buf.set_string(0, 0, "Hello!", Style.new.fg(Color::GREEN).bold)
+  #   puts buf.to_ansi
+  class Buffer
+    # @return [Rect] the rectangular bounds of this buffer
+    attr_reader :area
+    # @return [Hash{Array => Hash{Symbol => Object}}]
+    #   image placements keyed by [x, y, content_hash] (or [x, y] when no content
+    #   hash is given), registered via {#set_image} by {Widgets::Image#render}
+    attr_reader :image_placements
+
+    # Create a new Buffer.
+    #
+    # @overload initialize(width, height)
+    #   Shorthand that creates a buffer at origin (0, 0).
+    #   @param width [Integer] buffer width in columns
+    #   @param height [Integer] buffer height in rows
+    #
+    # @overload initialize(area)
+    #   @param area [Rect] the rectangular bounds
+    def initialize(area_or_width, height = nil)
+      @area = if height
+        Rect.new(0, 0, area_or_width, height)
+      else
+        area_or_width
+      end
+      @cells = Array.new(@area.area) { Cell.new }
+      @image_placements = {}
+    end
+
+    # Get the cell at position (x, y).
+    #
+    # @param x [Integer] column position
+    # @param y [Integer] row position
+    # @return [Cell, nil] the cell, or nil if out of bounds
+    def [](x, y)
+      idx = index(x, y)
+      idx ? @cells[idx] : nil
+    end
+
+    # Set the cell at position (x, y).
+    #
+    # @param x [Integer] column position
+    # @param y [Integer] row position
+    # @param cell [Cell] the cell to place
+    # @return [void]
+    def []=(x, y, cell)
+      idx = index(x, y)
+      @cells[idx] = cell if idx
+    end
+
+    # @!group Deprecated Unicode utilities — use the Unicode module instead
+
+    # @deprecated Use {Unicode.string_width} instead.
+    # @param string [String] the string to measure
+    # @return [Integer] display width in terminal columns
+    def self.string_width(string) = Unicode.string_width(string)
+    # @deprecated Use {Unicode.cluster_width} instead.
+    # @param cluster [String] a grapheme cluster (one or more codepoints)
+    # @return [Integer] 0, 1, or 2
+    def self.cluster_width(cluster) = Unicode.cluster_width(cluster)
+    # @deprecated Use {Unicode.truncate_to_width} instead.
+    # @param string [String] the string to truncate
+    # @param max_width [Integer] maximum display width in columns
+    # @return [String] truncated string
+    def self.truncate_to_width(string, max_width) = Unicode.truncate_to_width(string, max_width)
+    # @deprecated Use {Unicode.char_width} instead.
+    # @param ch [String] a single character
+    # @return [Integer] 0 for combining marks, 2 for wide characters, 1 otherwise
+    def self.char_width(ch) = Unicode.char_width(ch)
+    # @deprecated Use {Unicode.combining_mark?} instead.
+    # @param cp [Integer] Unicode codepoint
+    # @return [Boolean] true if codepoint is a combining mark (zero-width)
+    def self.combining_mark?(cp) = Unicode.combining_mark?(cp)
+    # @deprecated Use {Unicode.wide_char?} instead.
+    # @param cp [Integer] Unicode codepoint
+    # @return [Boolean] true if codepoint is a wide character (2-column)
+    def self.wide_char?(cp) = Unicode.wide_char?(cp)
+
+    # @!endgroup
+
+    # Write a styled string starting at (x, y).
+    #
+    # Iterates by grapheme cluster so that combining sequences (Devanagari
+    # matras/virama, emoji ZWJ, Latin diacritics) are stored as a single
+    # cell symbol.  Wide clusters (2-column) mark the next cell as a spacer.
+    # Clips at buffer boundaries.
+    #
+    # @param x [Integer] starting column
+    # @param y [Integer] row
+    # @param string [String] text to write
+    # @param style [Style] style to apply (default: {Style::DEFAULT})
+    # @return [Integer] number of terminal columns consumed
+    def set_string(x, y, string, style = Style::DEFAULT)
+      return 0 unless y >= @area.y && y < @area.bottom
+
+      count = 0
+      col = x
+
+      string.grapheme_clusters.each do |gc|
+        break if col >= @area.right
+
+        w = Unicode.cluster_width(gc)
+
+        if col >= @area.x
+          idx = index(col, y)
+          if idx
+            @cells[idx].symbol = gc
+            @cells[idx].style = style
+            count += w
+
+            # For wide clusters, mark the next cell as a spacer
+            if w == 2 && col + 1 < @area.right
+              next_idx = index(col + 1, y)
+              if next_idx
+                @cells[next_idx].symbol = ""
+                @cells[next_idx].style = style
+              end
+            end
+          end
+        end
+        col += w
+      end
+      count
+    end
+
+    # Apply a style to all cells within the given area.
+    #
+    # Uses {Style#patch} so the applied style merges with existing cell styles.
+    #
+    # @param area [Rect] the area to style
+    # @param style [Style] the style to apply
+    # @return [void]
+    def set_style(area, style)
+      each_cell_in(area) do |idx|
+        @cells[idx].style = @cells[idx].style.patch(style)
+      end
+    end
+
+    # Diff this buffer against another, returning changed cells.
+    #
+    # Used by {Terminal#draw} for minimal screen updates.
+    #
+    # @param other [Buffer] the previous buffer to diff against
+    # @return [Array<Array(Integer, Integer, Cell)>] changed cells as [x, y, cell]
+    def diff(other)
+      changes = []
+      @cells.each_with_index do |cell, i|
+        next if cell == other.cells[i]
+
+        x = @area.x + (i % @area.width)
+        y = @area.y + (i / @area.width)
+        changes << [x, y, cell]
+      end
+      changes
+    end
+
+    # Reset all cells to empty (space character, default style).
+    #
+    # @return [void]
+    def reset!
+      reset_cells!
+      @image_placements.clear
+    end
+
+    # Reset cells only, keeping image placements — used by {Terminal} for
+    # full repaints, where placements must still diff against the previous
+    # frame to detect deletions.
+    #
+    # @return [void]
+    def reset_cells!
+      @cells.each(&:reset!)
+    end
+
+    # Register an image placement for Kitty graphics protocol rendering.
+    #
+    # Called by {Widgets::Image#render}. The placement is stored and later
+    # emitted by the backend during {Terminal#draw}.
+    #
+    # @param x [Integer] column position
+    # @param y [Integer] row position
+    # @param cols [Integer] display width in columns
+    # @param rows [Integer] display height in rows
+    # @param data [String] raw image bytes (PNG or RGBA)
+    # @param pixel_width [Integer] image width in pixels
+    # @param pixel_height [Integer] image height in pixels
+    # @param format [Symbol] :png or :rgba
+    # @param content_hash [String, nil] hash of image content for change detection
+    # @param src_x [Integer, nil] source rectangle X offset in pixels
+    # @param src_y [Integer, nil] source rectangle Y offset in pixels
+    # @param src_w [Integer, nil] source rectangle width in pixels
+    # @param src_h [Integer, nil] source rectangle height in pixels
+    # @return [void]
+    def set_image(x:, y:, cols:, rows:, data:, pixel_width:, pixel_height:, format:,
+                  content_hash: nil, src_x: nil, src_y: nil, src_w: nil, src_h: nil)
+      # Key by position + content hash to detect when image changes at same position
+      key = content_hash ? [x, y, content_hash] : [x, y]
+
+      placement = {
+        x: x, y: y, cols: cols, rows: rows,
+        data: data, pixel_width: pixel_width, pixel_height: pixel_height,
+        format: format, content_hash: content_hash
+      }
+
+      # Add source rectangle if specified
+      if src_x && src_y && src_w && src_h
+        placement[:src_x] = src_x
+        placement[:src_y] = src_y
+        placement[:src_w] = src_w
+        placement[:src_h] = src_h
+      end
+
+      @image_placements[key] = placement
+    end
+
+    # Merge another buffer on top of this one (for overlays).
+    #
+    # Non-empty cells from the other buffer overwrite cells in this buffer.
+    #
+    # @param other [Buffer] the overlay buffer
+    # @return [void]
+    def merge(other)
+      other.each_cell_with_position do |x, y, cell|
+        next if cell.empty?
+
+        idx = index(x, y)
+        @cells[idx] = cell if idx
+      end
+    end
+
+    # Iterate over all cells with their absolute positions.
+    #
+    # @yield [x, y, cell] for each cell in the buffer
+    # @yieldparam x [Integer] column position
+    # @yieldparam y [Integer] row position
+    # @yieldparam cell [Cell]
+    # @return [void]
+    def each_cell_with_position
+      @cells.each_with_index do |cell, i|
+        x = @area.x + (i % @area.width)
+        y = @area.y + (i / @area.width)
+        yield x, y, cell
+      end
+    end
+
+    # Convert buffer contents to an ANSI-styled string for one-shot printing.
+    #
+    # Each row becomes a line separated by +\n+. Styles are emitted as
+    # ANSI SGR escape codes with reset at end of each styled row.
+    #
+    # @return [String] ANSI-escaped string ready for terminal output
+    #
+    # @example
+    #   buf = Buffer.new(40, 5)
+    #   buf.set_string(0, 0, "Hello", Style.new.fg(Color::GREEN))
+    #   puts buf.to_ansi
+    def to_ansi
+      csi = "\e["
+      result = String.new(capacity: @area.area * 2)
+      prev_style = nil
+
+      @area.height.times do |row|
+        # Build the row content and track the last non-empty column
+        row_buf = String.new(capacity: @area.width * 2)
+        last_styled_col = -1
+        col = 0
+        display_col = 0  # track actual terminal column for cursor correction
+
+        while col < @area.width
+          cell = @cells[row * @area.width + col]
+
+          # Skip spacer cells from wide characters
+          if cell.symbol.empty?
+            col += 1
+            next
+          end
+
+          # Apply style changes
+          style = cell.style
+          unless style == prev_style
+            codes = style_to_sgr_codes(style, prev_style)
+            row_buf << "#{csi}#{codes.join(";")}m" unless codes.empty?
+            prev_style = style
+          end
+
+          row_buf << cell.symbol
+
+          # Track last non-default cell for trimming
+          unless cell.empty?
+            last_styled_col = col
+          end
+
+          w = Unicode.string_width(cell.symbol)
+          display_col += w
+          col += [w, 1].max
+
+          # After wide characters, emit cursor column to correct any
+          # terminal rendering drift (terminals may disagree about emoji width)
+          if w >= 2 && col < @area.width
+            row_buf << "#{csi}#{display_col + 1}G"
+          end
+        end
+
+        # Reset at end of row if we had any styling
+        if prev_style && prev_style != Style::DEFAULT
+          row_buf << "#{csi}0m"
+          prev_style = nil
+        end
+
+        result << row_buf
+        result << "\n" unless row == @area.height - 1
+      end
+
+      result
+    end
+
+    # Print the buffer's ANSI output to a stream.
+    #
+    # Convenience wrapper around {#to_ansi}.
+    #
+    # @param output [IO] output stream (default: $stdout)
+    # @return [void]
+    def print(output = $stdout)
+      output.write(to_ansi)
+    end
+
+    protected
+
+    attr_reader :cells
+
+    private
+
+    def index(x, y)
+      return nil unless x >= @area.x && x < @area.right &&
+                        y >= @area.y && y < @area.bottom
+
+      (y - @area.y) * @area.width + (x - @area.x)
+    end
+
+    def char_width(ch) = Unicode.char_width(ch)
+
+    # Generate SGR codes to transition from prev_style to style
+    def style_to_sgr_codes(style, prev_style)
+      codes = []
+      prev = prev_style || Style::DEFAULT
+
+      # Check if we need a full reset
+      removed_mods = prev.modifiers & ~style.modifiers
+      if removed_mods != 0 || (prev.fg && !style.fg) || (prev.bg && !style.bg)
+        codes << "0"
+        prev = Style::DEFAULT
+      end
+
+      # Foreground
+      if style.fg != prev.fg
+        codes << (style.fg ? style.fg.to_fg_ansi : "39")
+      end
+
+      # Background
+      if style.bg != prev.bg
+        codes << (style.bg ? style.bg.to_bg_ansi : "49")
+      end
+
+      # Modifiers added
+      added = style.modifiers & ~prev.modifiers
+      Modifier::SGR_ON.each do |flag, code|
+        codes << code if Modifier.contains?(added, flag)
+      end
+
+      codes
+    end
+
+    def each_cell_in(area)
+      y_start = [area.y, @area.y].max
+      y_end = [area.bottom, @area.bottom].min
+      x_start = [area.x, @area.x].max
+      x_end = [area.right, @area.right].min
+
+      (y_start...y_end).each do |y|
+        (x_start...x_end).each do |x|
+          idx = index(x, y)
+          yield idx if idx
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/cell.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # The atomic unit of the rendering grid: a single character with a style.
+  #
+  # Each cell in a {Buffer} holds one character (or empty string for wide-char
+  # spacers) and an associated {Style}.
+  class Cell
+    # @return [String] the character displayed in this cell
+    attr_accessor :symbol
+    # @return [Style] the style applied to this cell
+    attr_accessor :style
+
+    # Default empty character (space).
+    EMPTY_CHAR = " "
+
+    # @param symbol [String] the character (default: space)
+    # @param style [Style] the style (default: {Style::DEFAULT})
+    def initialize(symbol = EMPTY_CHAR, style = Style::DEFAULT)
+      @symbol = symbol
+      @style = style
+    end
+
+    # Reset this cell to empty (space character, default style).
+    #
+    # @return [self]
+    def reset!
+      @symbol = EMPTY_CHAR
+      @style = Style::DEFAULT
+      self
+    end
+
+    # Set this cell's character and style.
+    #
+    # @param symbol [String] the character
+    # @param style [Style] the style (default: {Style::DEFAULT})
+    # @return [self]
+    def set(symbol, style = Style::DEFAULT)
+      @symbol = symbol
+      @style = style
+      self
+    end
+
+    # Compare by symbol and style.
+    #
+    # @param other [Object] object to compare against
+    # @return [Boolean] true if +other+ is a Cell with an equal symbol and style
+    def ==(other)
+      other.is_a?(Cell) && @symbol == other.symbol && @style == other.style
+    end
+
+    # @return [Boolean] true if this cell has default content (space + default style)
+    def empty? = @symbol == EMPTY_CHAR && @style == Style::DEFAULT
+  end
+end

data/lib/rubytui/color.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Terminal color supporting named (16), indexed (256), and RGB truecolor.
+  #
+  # Use the predefined constants for the standard 16 colors, or the factory
+  # methods for indexed and RGB colors.
+  #
+  # @example Named colors
+  #   Style.new.fg(Color::RED).bg(Color::BLACK)
+  #
+  # @example 256-color palette
+  #   Style.new.fg(Color.indexed(208))  # orange
+  #
+  # @example RGB truecolor
+  #   Style.new.fg(Color.rgb(255, 128, 0))
+  class Color
+    # @return [Symbol] color kind — +:named+, +:indexed+, +:rgb+, or +:reset+
+    attr_reader :kind
+    # @return [Integer, Array<Integer>, nil] color value (index, [r,g,b], or named index)
+    attr_reader :value
+
+    # @param kind [Symbol] color kind
+    # @param value [Integer, Array<Integer>, nil] color value
+    def initialize(kind, value = nil)
+      @kind = kind
+      @value = value
+    end
+
+    # Value equality: same kind and value.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if +other+ is a Color with equal {#kind} and {#value}
+    def ==(other)
+      other.is_a?(Color) && @kind == other.kind && @value == other.value
+    end
+    alias_method :eql?, :==
+
+    # @return [Integer] hash derived from {#kind} and {#value}
+    def hash = [@kind, @value].hash
+
+    class << self
+      # Create a color from the 256-color indexed palette.
+      #
+      # @param n [Integer] color index (0-255)
+      # @return [Color]
+      # @raise [ArgumentError] if n is outside 0-255
+      def indexed(n)
+        raise ArgumentError, "Color index must be 0-255, got #{n}" unless (0..255).cover?(n)
+
+        new(:indexed, n).freeze
+      end
+
+      # Create an RGB truecolor.
+      #
+      # @param r [Integer] red component (0-255)
+      # @param g [Integer] green component (0-255)
+      # @param b [Integer] blue component (0-255)
+      # @return [Color]
+      def rgb(r, g, b)
+        new(:rgb, [r, g, b].freeze).freeze
+      end
+    end
+
+    # Generate ANSI foreground escape code fragment (without ESC[ prefix or m suffix).
+    #
+    # @return [String] SGR code fragment (e.g., "31", "38;5;208", "38;2;255;128;0")
+    def to_fg_ansi
+      case @kind
+      when :reset   then "39"
+      when :named   then (@value < 8 ? "#{30 + @value}" : "#{90 + @value - 8}")
+      when :indexed then "38;5;#{@value}"
+      when :rgb     then "38;2;#{@value[0]};#{@value[1]};#{@value[2]}"
+      end
+    end
+
+    # Generate ANSI background escape code fragment.
+    #
+    # @return [String] SGR code fragment (e.g., "41", "48;5;208", "48;2;255;128;0")
+    def to_bg_ansi
+      case @kind
+      when :reset   then "49"
+      when :named   then (@value < 8 ? "#{40 + @value}" : "#{100 + @value - 8}")
+      when :indexed then "48;5;#{@value}"
+      when :rgb     then "48;2;#{@value[0]};#{@value[1]};#{@value[2]}"
+      end
+    end
+
+    # @!group Standard Named Colors (16-color palette)
+
+    # Terminal default color (SGR 39 / 49).
+    RESET          = new(:reset).freeze
+    # Black (SGR 30 / 40).
+    BLACK          = new(:named, 0).freeze
+    # Red (SGR 31 / 41).
+    RED            = new(:named, 1).freeze
+    # Green (SGR 32 / 42).
+    GREEN          = new(:named, 2).freeze
+    # Yellow (SGR 33 / 43).
+    YELLOW         = new(:named, 3).freeze
+    # Blue (SGR 34 / 44).
+    BLUE           = new(:named, 4).freeze
+    # Magenta (SGR 35 / 45).
+    MAGENTA        = new(:named, 5).freeze
+    # Cyan (SGR 36 / 46).
+    CYAN           = new(:named, 6).freeze
+    # White (SGR 37 / 47).
+    WHITE          = new(:named, 7).freeze
+    # Bright black, usually rendered as gray (SGR 90 / 100).
+    BRIGHT_BLACK   = new(:named, 8).freeze
+    # Bright red (SGR 91 / 101).
+    BRIGHT_RED     = new(:named, 9).freeze
+    # Bright green (SGR 92 / 102).
+    BRIGHT_GREEN   = new(:named, 10).freeze
+    # Bright yellow (SGR 93 / 103).
+    BRIGHT_YELLOW  = new(:named, 11).freeze
+    # Bright blue (SGR 94 / 104).
+    BRIGHT_BLUE    = new(:named, 12).freeze
+    # Bright magenta (SGR 95 / 105).
+    BRIGHT_MAGENTA = new(:named, 13).freeze
+    # Bright cyan (SGR 96 / 106).
+    BRIGHT_CYAN    = new(:named, 14).freeze
+    # Bright white (SGR 97 / 107).
+    BRIGHT_WHITE   = new(:named, 15).freeze
+
+    # @!endgroup
+
+    # @!group Color Aliases
+
+    # Alias for {BRIGHT_BLACK}.
+    GRAY    = BRIGHT_BLACK
+    # Alias for {BRIGHT_BLACK}.
+    GREY    = BRIGHT_BLACK
+    # Alias for {BRIGHT_BLACK}.
+    DARK_GRAY  = BRIGHT_BLACK
+    # Alias for {BRIGHT_BLACK}.
+    DARK_GREY  = BRIGHT_BLACK
+    # Alias for {BRIGHT_RED}.
+    LIGHT_RED  = BRIGHT_RED
+    # Alias for {BRIGHT_GREEN}.
+    LIGHT_GREEN  = BRIGHT_GREEN
+    # Alias for {BRIGHT_YELLOW}.
+    LIGHT_YELLOW = BRIGHT_YELLOW
+    # Alias for {BRIGHT_BLUE}.
+    LIGHT_BLUE   = BRIGHT_BLUE
+    # Alias for {BRIGHT_MAGENTA}.
+    LIGHT_MAGENTA = BRIGHT_MAGENTA
+    # Alias for {BRIGHT_CYAN}.
+    LIGHT_CYAN   = BRIGHT_CYAN
+
+    # @!endgroup
+  end
+end