tuile 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23a6288632a551240d224975faee1f71d477bb1465126d70915950f67c187650
-  data.tar.gz: 33e26892d2a625e85d5d2f2fd058a04080ef12ea38825cb2f9727a346f36c6a2
+  metadata.gz: bf132f33d9f0dfd061a502d0b974a9906436bbc585bf363eb0ec7d97a2b223ae
+  data.tar.gz: 2d91fe558079a4b5c43abd3818c3bb47cd50dc4ac3372c4afe011ef33dc97045
 SHA512:
-  metadata.gz: 233960b007d8c81281e6726e605ab48e9bdc389399b796a4d9a19314e1be2bfab019a787ddc6ab8b421221010cb9402fdc102737fef085aaa326641b76275eed
-  data.tar.gz: 68b2425566e2a2586d686699df135a4a7fce835b0f2ca5f090204b3b82f6d3b6d7813375f9129e5256eea627be8df72e667694869d4ba475de55221c0db5ae8e
+  metadata.gz: 8258e9e552143470a5642559f6db98e5292e14fa2fa52c30a06e26bf505e44ff1c889da73792bc262def396997861187d02d95d4189ced1f853ab91333e606b5
+  data.tar.gz: 99c03866f8d65ec2c6ca61381078b69616a3e23b3dada3cc11a3d4e2e1fc2973e1d15ac2ac0147e0e583edd20fae247e5be85ad974cf53e245a8cc109b3fe084

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-21
+
+- Add `Tuile::Color` — a value type wrapping the four color forms ANSI understands (named Symbol, 256-color Integer, RGB Array, or `nil`). Pre-defined constants `Color::RED`, `Color::BRIGHT_BLUE`, … cover the 16 named ANSI colors; `Color.coerce` accepts raw forms transparently.
+- `Component::Label`: add `bg` accessor — applies a background color uniformly across every painted row (text, trailing pad, and blank rows past the last line). Accepts anything `Color.coerce` accepts.
+- Add `Component::TextView::Region` — opaque handle to a contiguous run of hard lines, so apps can stream into logical sections without tracking line indices across sibling mutations. Create with `view.create_region`; mutate via `region.append`/`#<<`/`#text=`/`#add_line`/`#remove_last_n_lines`/`#replace`/`#insert`/`#remove`. Detached handles raise on every reader / mutator (except `#remove`, which is idempotent). `view.text=` / `clear` detach all region handles and install a fresh internal default.
+- Add `Component::TextView#replace(range, str)` and `#insert(at, str)` for mid-buffer hard-line splices (Integer or Range, inclusive/exclusive end, empty range == insertion, `begin == hard-line count` valid for end-insertion).
+- `Component::TextView`: incremental wrap via a per-hard-line row-count cache — mid-buffer mutations now re-wrap only the affected slice instead of the whole buffer. Speeds up the LLM streaming path (mid-document `region.append`, tombstone-style `region.text=`, `view.replace`/`view.insert`). `view.append` on the spatial tail keeps its existing fast path; `view.text=` and `on_width_changed` still do a full rewrap (now rebuilding the cache too).
+- Add `EventQueue#tick(fps) { |n| ... }` returning a `Ticker` backed by `Concurrent::TimerTask`; fires on the event-loop thread with a 0-based monotonic counter. Intended for spinner animations, periodic refresh, or surfacing background-task progress. Auto-cancels on raise.
+- Add `FakeEventQueue#tick` and `FakeTicker` — synchronous test double that drives ticks deterministically.
+- **Breaking:** `StyledString::Style#fg` and `#bg` now return `Color` (or `nil`) instead of the raw `Symbol`/`Integer`/`Array`. `Style.new` and `#merge` continue to accept the raw forms via `Color.coerce`.
+- **Breaking:** Remove `StyledString::Style::COLOR_SYMBOLS` — moved to `Color::COLOR_SYMBOLS`.
+- **Breaking:** `EventQueue#run_loop` now yields submitted `Proc` events to its consumer block instead of dispatching them inline, so a raise from a `submit{}` block is routed through `Screen#on_error` like any other event. Custom `run_loop` consumers must `call` Procs in their case statement.
+
 ## [0.4.0] - 2026-05-20
 
 - Add `Screen#register_global_shortcut` for app-level hotkeys; registered shortcuts surface in the status bar via `hint:`.

data/lib/tuile/color.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Tuile
+  # An immutable terminal color. Accepts the three forms ANSI/SGR understands:
+  #
+  # - a Symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright named colors
+  #   (SGR 30..37 / 90..97 for fg, 40..47 / 100..107 for bg)
+  # - an Integer 0..255 — the 256-color palette (SGR 38;5;N / 48;5;N)
+  # - an Array of three Integers 0..255 — 24-bit RGB (SGR 38;2;R;G;B / 48;2;R;G;B)
+  #
+  # A constant per named color is pre-defined (`Color::RED`, `Color::BRIGHT_BLUE`,
+  # …) so callers can reach for `Color::RED` instead of building one each time.
+  # {.coerce} accepts anything {.new} accepts plus `nil` (terminal default) and
+  # an existing {Color} (returned as-is), so APIs that accept colors typically
+  # take `[Color, nil]` and pass through {.coerce}.
+  #
+  # ```ruby
+  # Color.new(:red)              # named
+  # Color.new(42)                # 256-color palette
+  # Color.new([255, 100, 0])     # RGB
+  # Color::RED                   # constant
+  # Color.coerce(:red)           # accepts raw forms, returns Color
+  # Color.coerce(nil)            # nil → nil
+  # ```
+  #
+  # {#to_ansi} renders a full SGR escape (`"\e[31m"`); {#sgr_codes} returns the
+  # raw numeric codes so callers (notably {StyledString}) can combine them with
+  # other SGR attributes in a single sequence.
+  class Color
+    # Symbolic color names. Order is significant: indices 0..7 map to the
+    # standard ANSI colors (SGR 30..37 fg / 40..47 bg); indices 8..15 map to
+    # bright variants (SGR 90..97 / 100..107).
+    # @return [Array<Symbol>]
+    COLOR_SYMBOLS = %i[
+      black red green yellow blue magenta cyan white
+      bright_black bright_red bright_green bright_yellow
+      bright_blue bright_magenta bright_cyan bright_white
+    ].freeze
+
+    # Coerces the input to a {Color}. `nil` passes through unchanged (callers
+    # use `nil` for the terminal default); an existing {Color} is returned
+    # as-is; otherwise the value is fed to {.new}.
+    #
+    # @param value [Color, Symbol, Integer, Array<Integer>, nil]
+    # @return [Color, nil]
+    # @raise [ArgumentError] when `value` is not one of the accepted forms.
+    def self.coerce(value)
+      case value
+      when nil, Color then value
+      else new(value)
+      end
+    end
+
+    # @param value [Symbol, Integer, Array<Integer>] see class-level docs for
+    #   the three accepted forms.
+    # @raise [ArgumentError] when `value` is not one of the accepted forms.
+    def initialize(value)
+      unless COLOR_SYMBOLS.include?(value) ||
+             (value.is_a?(Integer) && value.between?(0, 255)) ||
+             (value.is_a?(Array) && value.length == 3 &&
+              value.all? { |v| v.is_a?(Integer) && v.between?(0, 255) })
+        raise ArgumentError, "invalid color: #{value.inspect}"
+      end
+
+      @value = value.is_a?(Array) ? value.dup.freeze : value
+      freeze
+    end
+
+    # The underlying raw representation — a Symbol, Integer, or frozen
+    # Array<Integer>.
+    # @return [Symbol, Integer, Array<Integer>]
+    attr_reader :value
+
+    # SGR parameter codes for emitting this color as either a foreground
+    # (`target: :fg`) or background (`target: :bg`). Returned as an array so
+    # callers can splice them into a multi-attribute SGR (e.g. bold + color).
+    #
+    # @param target [Symbol] `:fg` or `:bg`.
+    # @return [Array<Integer>]
+    # @raise [ArgumentError] when `target` is neither `:fg` nor `:bg`.
+    def sgr_codes(target = :fg)
+      base, ext = case target
+                  when :fg then [30, 38]
+                  when :bg then [40, 48]
+                  else raise ArgumentError, "target must be :fg or :bg, got #{target.inspect}"
+                  end
+      case @value
+      when Symbol
+        idx = COLOR_SYMBOLS.index(@value)
+        idx < 8 ? [base + idx] : [base + 60 + (idx - 8)]
+      when Integer then [ext, 5, @value]
+      when Array then [ext, 2, *@value]
+      end
+    end
+
+    # Full SGR escape sequence for this color (e.g. `"\e[31m"`). Useful for
+    # `print`-style direct emission; for composing with other attributes use
+    # {#sgr_codes} instead.
+    #
+    # @param target [Symbol] `:fg` or `:bg`.
+    # @return [String]
+    def to_ansi(target = :fg)
+      "\e[#{sgr_codes(target).join(";")}m"
+    end
+
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Color) && @value == other.value
+    end
+    alias eql? ==
+
+    # @return [Integer]
+    def hash
+      [self.class, @value].hash
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class.name} #{@value.inspect}>"
+    end
+
+    COLOR_SYMBOLS.each do |sym|
+      const_set(sym.upcase, new(sym))
+    end
+  end
+end

data/lib/tuile/component/label.rb

@@ -11,6 +11,7 @@ module Tuile
       def initialize
         super
         @text = StyledString::EMPTY
+        @bg = nil
         @clipped_lines = []
         @blank_line = ""
       end
@@ -19,6 +20,11 @@ module Tuile
       #   {StyledString}.
       attr_reader :text
 
+      # @return [Color, nil] background color applied uniformly across every
+      #   painted row (including padding past the text). `nil` (default)
+      #   leaves whatever bg the text's own styling carries.
+      attr_reader :bg
+
       # Replaces the text. A `String` is parsed via {StyledString.parse}
       # (embedded ANSI is honored); a `StyledString` is used as-is; `nil` is
       # coerced to an empty {StyledString}. Lines wider than {#rect} are
@@ -35,6 +41,23 @@ module Tuile
         invalidate
       end
 
+      # Sets the background color. Coerced via {Color.coerce}, so a Symbol,
+      # Integer, Array, {Color}, or `nil` all work. `nil` clears the override
+      # — the label paints with whatever bg the text's own styling provides.
+      # Otherwise the bg overlays every span (including the trailing pad and
+      # blank rows past the last text line).
+      #
+      # @param value [Color, Symbol, Integer, Array<Integer>, nil]
+      # @return [void]
+      def bg=(value)
+        new_bg = Color.coerce(value)
+        return if @bg == new_bg
+
+        @bg = new_bg
+        update_clipped_lines
+        invalidate
+      end
+
       # @return [Size] longest hard-line's display width × number of hard
       #   lines. Reported on the *unclipped* text — sizing is intrinsic to
       #   the content, not the viewport. Empty text returns `Size.new(0, 0)`.
@@ -79,12 +102,19 @@ module Tuile
       # Each line is ellipsized to fit, padded with trailing spaces out to
       # the full width, and pre-rendered to ANSI so {#repaint} is just a
       # lookup + screen.print per row. {@blank_line} covers rows past the
-      # last text line.
+      # last text line. When {#bg} is set, every produced line (and the
+      # blank row) has the bg applied uniformly.
       # @return [void]
       def update_clipped_lines
         width = rect.width.clamp(0, nil)
-        @blank_line = " " * width
-        @clipped_lines = @text.lines.map { |line| pad_to(line.ellipsize(width), width).to_ansi }
+        @blank_line = apply_bg(StyledString.plain(" " * width)).to_ansi
+        @clipped_lines = @text.lines.map { |line| apply_bg(pad_to(line.ellipsize(width), width)).to_ansi }
+      end
+
+      # @param line [StyledString]
+      # @return [StyledString]
+      def apply_bg(line)
+        @bg ? line.with_bg(@bg) : line
       end
 
       # @param line [StyledString]