rubytui 1.2.3

data/lib/rubytui/text/line.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # A Line is a sequence of Spans forming a single line of styled text.
+  #
+  # @example
+  #   Line.new([Span.new("Name: ", Style.new.bold), Span.new("Ada")])
+  class Line
+    attr_reader :spans, :style
+
+    # @param spans [String, Span, Array<Span>] content; a String becomes one
+    #   unstyled Span, a single Span is wrapped in an Array, an Array is used
+    #   as-is (default: empty)
+    # @param style [Style] line-level style, stored as {#style}
+    #   (default: {Style::DEFAULT})
+    # @raise [ArgumentError] if +spans+ is not a String, Span or Array
+    def initialize(spans = [], style = Style::DEFAULT)
+      @spans = case spans
+               when String then [Span.new(spans)]
+               when Span   then [spans]
+               when Array  then spans
+               else raise ArgumentError, "Line expects String, Span, or Array, got #{spans.class}"
+               end
+      @style = style
+    end
+
+    # Factory: from a plain string
+    #
+    # @param content [String] text of the line
+    # @param style [Style] style of the single Span (default: {Style::DEFAULT})
+    # @return [Line] a Line containing one Span
+    def self.from(content, style = Style::DEFAULT)
+      new([Span.new(content, style)])
+    end
+
+    # Factory: from a styled string
+    #
+    # @param content [String] text of the line
+    # @param style [Style] style of the single Span
+    # @return [Line] a Line containing one Span
+    def self.styled(content, style)
+      new([Span.new(content, style)])
+    end
+
+    # Total display width of all spans
+    #
+    # @return [Integer] sum of {Span#width} over {#spans}, in terminal columns
+    def width
+      @spans.sum(&:width)
+    end
+
+    # Plain text content (no styling)
+    #
+    # @return [String] concatenated span contents
+    def to_s
+      @spans.map(&:to_s).join
+    end
+
+    # Value equality: same spans and style.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if +other+ is a Line with equal {#spans} and {#style}
+    def ==(other)
+      other.is_a?(Line) && @spans == other.spans && @style == other.style
+    end
+  end
+end

data/lib/rubytui/text/span.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # A Span is a styled fragment of text.
+  # It is the atomic unit for rich text rendering.
+  #
+  # @example
+  #   Span.new("error", Style.new.fg(Color::RED).bold)
+  class Span
+    attr_reader :content, :style
+
+    # @param content [String] text of the span
+    # @param style [Style] style applied to the text (default: {Style::DEFAULT})
+    def initialize(content, style = Style::DEFAULT)
+      @content = content
+      @style = style
+    end
+
+    # @return [Integer] display width of {#content} in terminal columns
+    #   (see {Unicode.string_width})
+    def width = Unicode.string_width(@content)
+
+    # Value equality: same content and style.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if +other+ is a Span with equal {#content} and {#style}
+    def ==(other)
+      other.is_a?(Span) && @content == other.content && @style == other.style
+    end
+
+    # @return [String] the unstyled text ({#content})
+    def to_s = @content
+  end
+end

data/lib/rubytui/text/text.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Text is a collection of Lines, representing multi-line styled text.
+  #
+  # @example
+  #   Text.new("first\nsecond").height  # => 2
+  class Text
+    attr_reader :lines, :style
+
+    # @param lines [String, Line, Array<Line, #to_s>] content; a String is split
+    #   on newlines into unstyled Lines (trailing empty lines are dropped), a
+    #   single Line is wrapped in an Array, and Array elements that are not
+    #   Lines become unstyled Lines of their +to_s+ (default: empty)
+    # @param style [Style] text-level style, stored as {#style}
+    #   (default: {Style::DEFAULT})
+    # @raise [ArgumentError] if +lines+ is not a String, Line or Array
+    def initialize(lines = [], style = Style::DEFAULT)
+      @lines = case lines
+               when String then lines.split("\n").map { |l| Line.new(l) }
+               when Line   then [lines]
+               when Array  then lines.map { |l| l.is_a?(Line) ? l : Line.new(l.to_s) }
+               else raise ArgumentError, "Text expects String, Line, or Array, got #{lines.class}"
+               end
+      @style = style
+    end
+
+    # Factory: from a plain string (splits on newlines)
+    #
+    # @param content [String] text; see {#initialize} for the other accepted types
+    # @param style [Style] text-level style stored as {#style}; not applied to
+    #   the spans (default: {Style::DEFAULT})
+    # @return [Text]
+    # @raise [ArgumentError] if +content+ is not a String, Line or Array
+    def self.from(content, style = Style::DEFAULT)
+      new(content, style)
+    end
+
+    # Factory: from an array of Lines
+    #
+    # @param lines [Array<Line>] the lines
+    # @return [Text]
+    def self.from_lines(lines)
+      new(lines)
+    end
+
+    # Factory: styled single-line text
+    #
+    # @param content [String] text of the line (not split on newlines)
+    # @param style [Style] style of the single Span
+    # @return [Text] a Text with one Line containing one Span
+    def self.styled(content, style)
+      new([Line.styled(content, style)])
+    end
+
+    # @return [Integer] number of lines
+    def height = @lines.length
+
+    # Maximum width across all lines
+    #
+    # @return [Integer] largest {Line#width} in terminal columns (0 if there
+    #   are no lines)
+    def width
+      @lines.map(&:width).max || 0
+    end
+
+    # Plain text content (no styling).
+    #
+    # @return [String] line texts joined with newlines
+    def to_s
+      @lines.map(&:to_s).join("\n")
+    end
+
+    # Value equality: same lines and style.
+    #
+    # @param other [Object] object to compare
+    # @return [Boolean] true if +other+ is a Text with equal {#lines} and {#style}
+    def ==(other)
+      other.is_a?(Text) && @lines == other.lines && @style == other.style
+    end
+  end
+end

data/lib/rubytui/unicode.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "set"
+
+module RubyTUI
+  # Unicode text width utilities for terminal rendering.
+  #
+  # Handles display width calculation for wide characters (CJK, emoji),
+  # combining marks (Devanagari, diacritics), variation selectors (FE0F),
+  # and grapheme cluster segmentation.
+  #
+  # @example Measure display width
+  #   Unicode.string_width("Hello")   # => 5
+  #   Unicode.string_width("Hi🔥")   # => 4
+  #
+  # @example Truncate to fit
+  #   Unicode.truncate_to_width("Hello World", 5)  # => "Hello"
+  module Unicode
+    # Unicode Emoji_Presentation codepoints below U+3000.
+    # These render as 2-wide by default (without FE0F) in modern terminals.
+    # Source: Unicode 16.0 emoji-data.txt
+    EMOJI_PRESENTATION = Set[
+      0x231A, 0x231B,                                           # watch, hourglass
+      0x23E9, 0x23EA, 0x23EB, 0x23EC, 0x23F0, 0x23F3,         # fast-forward etc.
+      0x25FD, 0x25FE,                                           # medium small squares
+      0x2614, 0x2615,                                           # umbrella, hot beverage
+      0x2648, 0x2649, 0x264A, 0x264B, 0x264C, 0x264D,          # zodiac signs
+      0x264E, 0x264F, 0x2650, 0x2651, 0x2652, 0x2653,
+      0x267F,                                                    # wheelchair
+      0x2693,                                                    # anchor
+      0x26A1,                                                    # high voltage
+      0x26AA, 0x26AB,                                           # circles
+      0x26BD, 0x26BE,                                           # soccer, baseball
+      0x26C4, 0x26C5,                                           # snowman, sun behind cloud
+      0x26CE,                                                    # ophiuchus
+      0x26D4,                                                    # no entry
+      0x26EA,                                                    # church
+      0x26F2, 0x26F3,                                           # fountain, golf
+      0x26F5,                                                    # sailboat
+      0x26FA,                                                    # tent
+      0x26FD,                                                    # fuel pump
+      0x2705,                                                    # check mark
+      0x270A, 0x270B,                                           # fists
+      0x2728,                                                    # sparkles
+      0x274C, 0x274E,                                           # cross marks
+      0x2753, 0x2754, 0x2755,                                   # question/exclamation
+      0x2757,                                                    # exclamation
+      0x2795, 0x2796, 0x2797,                                   # plus/minus/division
+      0x27B0, 0x27BF,                                           # curly loops
+      0x2B1B, 0x2B1C,                                           # large squares
+      0x2B50,                                                    # star
+      0x2B55,                                                    # circle
+    ].freeze
+
+    module_function
+
+    # Calculate display width of a string in terminal columns.
+    #
+    # Operates on grapheme clusters so that combining sequences (Devanagari
+    # matras/virama, Latin diacritics, emoji ZWJ sequences) are measured as
+    # a single unit. Wide characters (CJK, emoji) count as 2 columns.
+    #
+    # @param string [String] the string to measure
+    # @return [Integer] display width in terminal columns
+    def string_width(string)
+      string.grapheme_clusters.sum { |gc| cluster_width(gc) }
+    end
+
+    # Calculate display width of a single grapheme cluster.
+    #
+    # @param cluster [String] a grapheme cluster (one or more codepoints)
+    # @return [Integer] 0, 1, or 2
+    def cluster_width(cluster)
+      return char_width(cluster) if cluster.bytesize == 1
+
+      codepoints = cluster.codepoints
+      has_fe0f = codepoints.include?(0xFE0F)
+
+      codepoints.each do |cp|
+        next if combining_mark?(cp)
+        return 2 if wide_char?(cp)
+        return 2 if has_fe0f
+      end
+
+      1
+    end
+
+    # Truncate a string to fit within a maximum display width.
+    #
+    # Unlike simple character slicing, this respects grapheme clusters and
+    # wide characters that take 2 columns.
+    #
+    # @param string [String] the string to truncate
+    # @param max_width [Integer] maximum display width in columns
+    # @return [String] truncated string
+    def truncate_to_width(string, max_width)
+      return "" if max_width <= 0
+
+      result = String.new
+      width = 0
+
+      string.grapheme_clusters.each do |gc|
+        w = cluster_width(gc)
+        break if width + w > max_width
+
+        result << gc
+        width += w
+      end
+
+      result
+    end
+
+    # Estimate the display width of a single character.
+    #
+    # @param ch [String] a single character
+    # @return [Integer] 0 for control characters and combining marks, 2 for wide
+    #   characters, 1 otherwise
+    def char_width(ch)
+      cp = ch.ord
+      return 1 if cp >= 0x20 && cp < 0x7F
+      return 0 if cp < 0x20 || cp == 0x7F
+      return 0 if combining_mark?(cp)
+      return 2 if wide_char?(cp)
+      1
+    end
+
+    # @param cp [Integer] Unicode codepoint
+    # @return [Boolean] true if codepoint is a combining mark (zero-width)
+    def combining_mark?(cp)
+      (cp >= 0x0300 && cp <= 0x036F) ||   # Combining Diacritical Marks
+      (cp >= 0x0900 && cp <= 0x097F &&     # Devanagari dependent vowels, virama, anusvara
+        ((cp >= 0x0901 && cp <= 0x0903) || (cp >= 0x093A && cp <= 0x094F) ||
+         (cp >= 0x0951 && cp <= 0x0957) || cp == 0x0962 || cp == 0x0963)) ||
+      (cp >= 0x1AB0 && cp <= 0x1AFF) ||   # Combining Diacritical Marks Extended
+      (cp >= 0x1DC0 && cp <= 0x1DFF) ||   # Combining Diacritical Marks Supplement
+      (cp >= 0x20D0 && cp <= 0x20FF) ||   # Combining Marks for Symbols
+      (cp >= 0xFE00 && cp <= 0xFE0F) ||   # Variation Selectors
+      (cp >= 0xFE20 && cp <= 0xFE2F) ||   # Combining Half Marks
+      (cp >= 0xE0100 && cp <= 0xE01EF)    # Variation Selectors Supplement
+    end
+
+    # @param cp [Integer] Unicode codepoint
+    # @return [Boolean] true if codepoint is a wide character (2-column)
+    def wide_char?(cp)
+      (cp >= 0x1100 && cp <= 0x115F) ||   # Hangul Jamo
+      EMOJI_PRESENTATION.include?(cp) ||   # Emoji with default 2-wide presentation
+      (cp >= 0x2E80 && cp <= 0x303E) ||   # CJK Radicals, Kangxi, CJK Symbols
+      (cp >= 0x3040 && cp <= 0x33BF) ||   # Hiragana, Katakana, CJK Compat
+      (cp >= 0x3400 && cp <= 0x4DBF) ||   # CJK Unified Extension A
+      (cp >= 0x4E00 && cp <= 0x9FFF) ||   # CJK Unified Ideographs
+      (cp >= 0xA960 && cp <= 0xA97F) ||   # Hangul Jamo Extended-A
+      (cp >= 0xAC00 && cp <= 0xD7AF) ||   # Hangul Syllables
+      (cp >= 0xF900 && cp <= 0xFAFF) ||   # CJK Compatibility Ideographs
+      (cp >= 0xFE10 && cp <= 0xFE19) ||   # Vertical Forms
+      (cp >= 0xFE30 && cp <= 0xFE6F) ||   # CJK Compatibility Forms
+      (cp >= 0xFF01 && cp <= 0xFF60) ||   # Fullwidth Forms
+      (cp >= 0xFFE0 && cp <= 0xFFE6) ||   # Fullwidth Sign
+      (cp >= 0x1F000 && cp <= 0x1FAFF) || # Emoji & Symbols
+      (cp >= 0x20000 && cp <= 0x2FA1F)    # CJK Unified Extensions B-F
+    end
+  end
+end

data/lib/rubytui/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Gem version string.
+  VERSION = "1.2.3"
+end

data/lib/rubytui/widget.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Widget protocol for immediate-mode rendering.
+  # Any object with #render(area, buf) is a widget.
+  # Include this module for documentation and a default NotImplementedError.
+  module Widget
+    # Render this widget into the buffer at the given area.
+    #
+    # Including classes override this method.
+    #
+    # @param area [Rect] the rectangular area to render into
+    # @param buf [Buffer] the buffer to write cells into
+    # @return [void]
+    # @raise [NotImplementedError] always, unless overridden by the including class
+    def render(area, buf)
+      raise NotImplementedError, "#{self.class}#render(area, buf) not implemented"
+    end
+  end
+end

data/lib/rubytui/widgets/async_image.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require "thread"
+
+module RubyTUI
+  module Widgets
+    # Asynchronously loads and renders images with placeholder support.
+    #
+    # Handles background image loading with thread-safe cache handoff,
+    # displays a placeholder while loading, and signals when ready for redraw.
+    #
+    # @example Basic async image
+    #   async_img = RubyTUI::Widgets::AsyncImage.new(
+    #     loader: -> { File.binread("large_image.png") }
+    #   )
+    #   frame.render_widget(async_img, area)
+    #
+    # @example With placeholder and callback
+    #   async_img = RubyTUI::Widgets::AsyncImage.new(
+    #     loader: -> { download_and_convert(url) },
+    #     placeholder: "Loading...",
+    #     on_ready: -> { needs_redraw = true }
+    #   )
+    #
+    # @example From URL with caching
+    #   cache = {}
+    #   async_img = RubyTUI::Widgets::AsyncImage.new(
+    #     key: url,
+    #     cache: cache,
+    #     loader: -> { fetch_and_convert_to_png(url) }
+    #   )
+    class AsyncImage
+      include Widget
+
+      # Loading states
+
+      # Loading not started (<tt>auto_start: false</tt> and no cache hit).
+      STATE_PENDING = :pending
+      # Loader running on the background thread.
+      STATE_LOADING = :loading
+      # Image data loaded and ready to render.
+      STATE_READY = :ready
+      # Loading or image validation failed; see {#error}.
+      STATE_ERROR = :error
+
+      # @return [Symbol] current loading state
+      attr_reader :state
+
+      # @return [String, nil] error message if state is :error
+      attr_reader :error
+
+      # @param loader [Proc] proc that returns PNG data (called in background thread)
+      # @param key [Object, nil] cache key (uses loader.object_id if nil)
+      # @param cache [Hash, nil] shared cache hash for storing loaded images; if it
+      #   already holds +key+, the widget is ready immediately and +loader+ is not
+      #   called (default: nil, uses a private Hash)
+      # @param placeholder [String, Widget, nil] widget or text to show while the
+      #   image is not ready. A {Widget} is rendered in the pending, loading and
+      #   error states. A String is drawn centered only while pending; while loading
+      #   the text <tt>"Loading..."</tt> is shown instead (default: nil)
+      # @param error_placeholder [String, nil] text to show on error unless
+      #   +placeholder+ is a {Widget} (default: nil, shows <tt>"[Error]"</tt>)
+      # @param on_ready [Proc, nil] callback invoked when image is ready (for triggering redraw).
+      #   Called with no arguments on the loading thread after +loader+ returns; not
+      #   called on a cache hit
+      # @param on_error [Proc, nil] callback invoked on load error. Called on the loading
+      #   thread with the exception raised by +loader+
+      # @param style [Style] background style, also used for placeholder text
+      #   (default: {Style::DEFAULT})
+      # @param block [Widgets::Block, nil] optional wrapping block
+      # @param fit [Symbol, nil] aspect-ratio mode for the loaded image (see {Image#initialize})
+      # @param cell_size [Array(Integer, Integer), nil] cell dimensions for aspect calculations
+      # @param auto_start [Boolean] start loading immediately (default: true)
+      def initialize(loader:, key: nil, cache: nil, placeholder: nil,
+                     error_placeholder: nil, on_ready: nil, on_error: nil,
+                     style: Style::DEFAULT, block: nil, fit: nil,
+                     cell_size: nil, auto_start: true)
+        @loader = loader
+        @key = key || loader.object_id
+        @cache = cache || {}
+        @placeholder = placeholder
+        @error_placeholder = error_placeholder || "[Error]"
+        @on_ready = on_ready
+        @on_error = on_error
+        @style = style
+        @block = block
+        @fit = fit
+        @cell_size = cell_size
+
+        @mutex = Mutex.new
+        @state = STATE_PENDING
+        @image_data = nil
+        @image_widget = nil
+        @error = nil
+        @thread = nil
+
+        # Check cache first
+        if @cache.key?(@key)
+          @image_data = @cache[@key]
+          @state = STATE_READY
+          build_image_widget
+        elsif auto_start
+          start_loading
+        end
+      end
+
+      # Start background loading if not already started.
+      #
+      # Does nothing unless the state is +:pending+. Otherwise sets the state to
+      # +:loading+ and calls +loader+ on a new thread. On success the data is
+      # stored in the cache and the state becomes +:ready+; if +loader+ raises a
+      # StandardError the state becomes +:error+.
+      #
+      # @return [self]
+      def start_loading
+        @mutex.synchronize do
+          return self unless @state == STATE_PENDING
+
+          @state = STATE_LOADING
+        end
+
+        @thread = Thread.new do
+          begin
+            data = @loader.call
+            @mutex.synchronize do
+              @image_data = data
+              @cache[@key] = data
+              @state = STATE_READY
+            end
+            build_image_widget
+            @on_ready&.call
+          rescue => e
+            @mutex.synchronize do
+              @error = e.message
+              @state = STATE_ERROR
+            end
+            @on_error&.call(e)
+          end
+        end
+
+        self
+      end
+
+      # Check if the image is ready for rendering.
+      #
+      # @return [Boolean]
+      def ready?
+        @state == STATE_READY
+      end
+
+      # Check if loading is in progress.
+      #
+      # @return [Boolean]
+      def loading?
+        @state == STATE_LOADING
+      end
+
+      # Check if loading failed.
+      #
+      # @return [Boolean]
+      def error?
+        @state == STATE_ERROR
+      end
+
+      # Cancel the background loading thread.
+      #
+      # Kills the thread if one is running. The state is not changed, so a load
+      # cancelled mid-flight stays +:loading+ and {#start_loading} will not restart it.
+      #
+      # @return [void]
+      def cancel
+        @thread&.kill
+        @thread = nil
+      end
+
+      # Render the async image or placeholder.
+      #
+      # When ready, the loaded {Image} is rendered; otherwise the placeholder
+      # described in {#initialize} is drawn.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty?
+
+        render_area = area
+        if @block
+          @block.render(area, buf)
+          render_area = @block.inner(area)
+        end
+
+        return if render_area.empty?
+
+        case @state
+        when STATE_READY
+          @image_widget&.render(render_area, buf)
+        when STATE_LOADING
+          render_placeholder(render_area, buf, "Loading...")
+        when STATE_ERROR
+          render_placeholder(render_area, buf, @error_placeholder)
+        when STATE_PENDING
+          render_placeholder(render_area, buf, @placeholder || "")
+        end
+      end
+
+      private
+
+      def build_image_widget
+        return unless @image_data
+
+        @mutex.synchronize do
+          @image_widget = Image.new(
+            data: @image_data,
+            style: @style,
+            fit: @fit,
+            cell_size: @cell_size,
+            clip: true
+          )
+        end
+      rescue ArgumentError, UnsupportedImageFormat => e
+        @mutex.synchronize do
+          @error = e.message
+          @state = STATE_ERROR
+        end
+      end
+
+      def render_placeholder(area, buf, text)
+        case @placeholder
+        when Widget
+          @placeholder.render(area, buf)
+        when String
+          display_text = text || @placeholder
+          # Center the placeholder text
+          x = area.x + [(area.width - Unicode.string_width(display_text)) / 2, 0].max
+          y = area.y + area.height / 2
+          buf.set_string(x, y, display_text, @style)
+        else
+          # Default: show text centered
+          display_text = text.to_s
+          x = area.x + [(area.width - Unicode.string_width(display_text)) / 2, 0].max
+          y = area.y + area.height / 2
+          buf.set_string(x, y, display_text, @style)
+        end
+      end
+    end
+  end
+end