tuile 0.3.0 → 0.4.0

data/lib/tuile/component/text_field.rb

@@ -11,36 +11,14 @@ module Tuile
     # The caret is a logical index in `0..text.length`. The hardware cursor is
     # positioned by {Screen} after each repaint cycle when this component is
     # focused; see {Component#cursor_position}.
-    class TextField < Component
+    class TextField < TextInput
       def initialize
         super
-        @text = +""
-        @caret = 0
-        @on_escape = nil
-        @on_change = nil
         @on_key_up = nil
         @on_key_down = nil
         @on_enter = nil
       end
 
-      # @return [String] current text contents.
-      attr_reader :text
-
-      # @return [Integer] caret index in `0..text.length`.
-      attr_reader :caret
-
-      # Optional callback fired when ESC is pressed. When set, ESC is consumed
-      # by the field; when nil, ESC falls through to the parent (default
-      # behavior).
-      # @return [Proc, Method, nil] no-arg callable, or nil.
-      attr_accessor :on_escape
-
-      # Optional callback fired whenever {#text} changes. Receives the new text
-      # as a single argument. Not fired by {#caret=} (text unchanged) and not
-      # fired when a setter is a no-op.
-      # @return [Proc, Method, nil] one-arg callable, or nil.
-      attr_accessor :on_change
-
       # Optional callback fired when the UP arrow key is pressed. When set, UP
       # is consumed by the field; when nil, UP falls through to the parent
       # (default behavior). Only triggered by {Keys::UP_ARROW}, not by `k`,
@@ -61,60 +39,50 @@ module Tuile
       # @return [Proc, Method, nil] no-arg callable, or nil.
       attr_accessor :on_enter
 
-      # Sets the text. Truncates to fit if longer than `rect.width - 1`. Caret
-      # is clamped to the new text length.
-      # @param new_text [String]
-      def text=(new_text)
-        new_text = new_text.to_s
-        new_text = new_text[0, max_text_length] if new_text.length > max_text_length
-        return if @text == new_text
+      # @return [Point, nil]
+      def cursor_position
+        return nil unless rect.width.positive?
 
-        @text = +new_text
-        @caret = @caret.clamp(0, @text.length)
-        invalidate
-        @on_change&.call(@text)
+        Point.new(rect.left + @caret, rect.top)
       end
 
-      # Sets the caret position. Clamped to `0..text.length`.
-      # @param new_caret [Integer]
-      def caret=(new_caret)
-        new_caret = new_caret.clamp(0, @text.length)
-        return if @caret == new_caret
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        return unless event.button == :left && rect.contains?(event.point)
 
-        @caret = new_caret
-        invalidate
+        self.caret = (event.x - rect.left).clamp(0, @text.length)
       end
 
-      def focusable? = true
+      # @return [void]
+      def repaint
+        return if rect.empty?
 
-      def tab_stop? = true
+        bg = active? ? ACTIVE_BG_SGR : INACTIVE_BG_SGR
+        padded = @text + (" " * (rect.width - @text.length))
+        screen.print TTY::Cursor.move_to(rect.left, rect.top), bg, padded, Ansi::RESET
+      end
 
-      # @return [Point, nil]
-      def cursor_position
-        return nil unless rect.width.positive?
+      protected
 
-        Point.new(rect.left + @caret, rect.top)
+      # Truncate to fit `rect.width - 1` — single-line fields can't grow past
+      # their width.
+      # @param new_text [String]
+      # @return [String]
+      def preprocess_text(new_text)
+        new_text = new_text.to_s
+        new_text.length > max_text_length ? new_text[0, max_text_length] : new_text
       end
 
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
-        return false unless active?
-        return true if super
-
+      def handle_text_input_key(key)
         case key
-        when Keys::LEFT_ARROW then self.caret = @caret - 1
-        when Keys::RIGHT_ARROW then self.caret = @caret + 1
-        when Keys::CTRL_LEFT_ARROW then self.caret = word_left
-        when Keys::CTRL_RIGHT_ARROW then self.caret = word_right
         when *Keys::HOMES then self.caret = 0
         when *Keys::ENDS_ then self.caret = @text.length
         when *Keys::BACKSPACES then delete_before_caret
         when Keys::DELETE then delete_at_caret
-        when Keys::ESC
-          return false if @on_escape.nil?
-
-          @on_escape.call
         when Keys::UP_ARROW
           return false if @on_key_up.nil?
 
@@ -128,48 +96,13 @@ module Tuile
 
           @on_enter.call
         else
-          return insert(key) if printable?(key)
+          return insert(key) if Keys.printable?(key)
 
-          return false
+          return super
         end
         true
       end
 
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        return unless event.button == :left && rect.contains?(event.point)
-
-        self.caret = (event.x - rect.left).clamp(0, @text.length)
-      end
-
-      # 256-color SGR for the focused-button highlight (matches what
-      # `Rainbow(...).bg(:darkslategray)` emits, which is what
-      # {Component::Button#repaint} uses for its focused state).
-      # @return [String]
-      ACTIVE_BG_SGR = "\e[48;5;59m"
-      # 256-color SGR for the unfocused field's "well": index 238 sits in
-      # the grayscale ramp (~#444444), bright enough to stand out against
-      # non-pure-black terminal themes (Gruvbox/Solarized/OneDark base
-      # backgrounds sit in the #1d–#2d range), and still distinctly darker
-      # than the active highlight at index 59 (~#5f5f5f). Rainbow's
-      # RGB-to-256 mapping snaps everything dark to palette index 16
-      # (terminal black), so we emit the escape directly to reach the ramp.
-      # @return [String]
-      INACTIVE_BG_SGR = "\e[48;5;238m"
-
-      # @return [void]
-      def repaint
-        return if rect.empty?
-
-        bg = active? ? ACTIVE_BG_SGR : INACTIVE_BG_SGR
-        padded = @text + (" " * (rect.width - @text.length))
-        screen.print TTY::Cursor.move_to(rect.left, rect.top), bg, padded, Ansi::RESET
-      end
-
-      protected
-
       # @return [void]
       def on_width_changed
         super
@@ -191,61 +124,11 @@ module Tuile
       def insert(char)
         return false if @text.length >= max_text_length
 
-        @text = @text.dup.insert(@caret, char)
+        new_text = @text.dup.insert(@caret, char)
         @caret += 1
-        invalidate
-        @on_change&.call(@text)
+        self.text = new_text
         true
       end
-
-      # @return [void]
-      def delete_before_caret
-        return if @caret.zero?
-
-        @text = @text.dup
-        @text.slice!(@caret - 1)
-        @caret -= 1
-        invalidate
-        @on_change&.call(@text)
-      end
-
-      # @return [void]
-      def delete_at_caret
-        return if @caret >= @text.length
-
-        @text = @text.dup
-        @text.slice!(@caret)
-        invalidate
-        @on_change&.call(@text)
-      end
-
-      # @param key [String]
-      # @return [Boolean]
-      def printable?(key)
-        key.length == 1 && key.ord >= 0x20 && key.ord < 0x7f
-      end
-
-      # Caret target for ctrl+left: skip whitespace going left, then a run of
-      # non-whitespace. Lands at the beginning of the current word, or the
-      # beginning of the previous word if already there.
-      # @return [Integer]
-      def word_left
-        c = @caret
-        c -= 1 while c.positive? && @text[c - 1].match?(/\s/)
-        c -= 1 while c.positive? && !@text[c - 1].match?(/\s/)
-        c
-      end
-
-      # Caret target for ctrl+right: skip non-whitespace going right, then a
-      # run of whitespace. Lands at the beginning of the next word, or at the
-      # end of the text if no further word exists.
-      # @return [Integer]
-      def word_right
-        c = @caret
-        c += 1 while c < @text.length && !@text[c].match?(/\s/)
-        c += 1 while c < @text.length && @text[c].match?(/\s/)
-        c
-      end
     end
   end
 end

data/lib/tuile/component/text_input.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # Abstract base for editable text components ({TextField}, {TextArea}).
+    #
+    # Holds the shared state — a mutable {#text} buffer, a {#caret} index,
+    # {#on_change} and {#on_escape} callbacks — and the keyboard machinery
+    # that single-line and multi-line inputs both need: ESC handling,
+    # LEFT/RIGHT caret movement, CTRL+LEFT/CTRL+RIGHT word jumps, and the
+    # `focusable?`/`tab_stop?` flags.
+    #
+    # Subclasses implement the layout-specific pieces ({#cursor_position},
+    # {#repaint}) and add their own keys (HOME/END, ENTER, UP/DOWN,
+    # printable insertion) by overriding the protected
+    # {#handle_text_input_key} hook — `super` falls through to the common
+    # navigation handling.
+    #
+    # The mutation pipeline is a template method: {#text=} and {#caret=}
+    # detect no-ops, mutate state, fire {#on_change}, and invalidate.
+    # Subclasses inject their own behavior via two protected hooks:
+    #
+    # - {#preprocess_text} — input filter (e.g. {TextField} truncates to
+    #   fit `rect.width - 1`).
+    # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
+    #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
+    #   keep the caret visible).
+    class TextInput < Component
+      def initialize
+        super
+        @text = +""
+        @caret = 0
+        @on_change = nil
+        @on_escape = method(:default_on_escape)
+      end
+
+      # @return [String] current text contents.
+      attr_reader :text
+
+      # @return [Boolean] true iff {#text} is the empty string.
+      def empty? = @text.empty?
+
+      # @return [Integer] caret index in `0..text.length`.
+      attr_reader :caret
+
+      # Optional callback fired whenever {#text} changes. Receives the new text
+      # as a single argument. Not fired by {#caret=} (text unchanged) and not
+      # fired when a setter is a no-op.
+      # @return [Proc, Method, nil] one-arg callable, or nil.
+      attr_accessor :on_change
+
+      # Callback fired when ESC is pressed. Defaults to a closure that clears
+      # focus (`screen.focused = nil`) so ESC visibly cancels text entry instead
+      # of bubbling to the parent — and, in particular, instead of reaching the
+      # screen's default ESC-to-quit handler. Set to nil to let ESC fall through
+      # to the parent again; set to any other callable to replace the default.
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      attr_accessor :on_escape
+
+      def focusable? = true
+
+      def tab_stop? = true
+
+      # Sets the text. Runs {#preprocess_text} first (subclasses may filter or
+      # truncate). Caret is clamped to the new text length. Fires {#on_change}
+      # only on a real change.
+      # @param new_text [String]
+      def text=(new_text)
+        new_text = preprocess_text(new_text)
+        return if @text == new_text
+
+        @text = +new_text
+        @caret = @caret.clamp(0, @text.length)
+        on_text_mutated
+        invalidate
+        @on_change&.call(@text)
+      end
+
+      # Sets the caret position. Clamped to `0..text.length`. Fires
+      # {#on_caret_mutated} hook for subclasses (e.g. {TextArea} scrolls).
+      # @param new_caret [Integer]
+      def caret=(new_caret)
+        new_caret = new_caret.clamp(0, @text.length)
+        return if @caret == new_caret
+
+        @caret = new_caret
+        on_caret_mutated
+        invalidate
+      end
+
+      # 256-color SGR for the focused-button highlight (matches what
+      # `Rainbow(...).bg(:darkslategray)` emits, which is what
+      # {Component::Button#repaint} uses for its focused state).
+      # @return [String]
+      ACTIVE_BG_SGR = "\e[48;5;59m"
+      # 256-color SGR for the unfocused field's "well": index 238 sits in
+      # the grayscale ramp (~#444444), bright enough to stand out against
+      # non-pure-black terminal themes (Gruvbox/Solarized/OneDark base
+      # backgrounds sit in the #1d–#2d range), and still distinctly darker
+      # than the active highlight at index 59 (~#5f5f5f). Rainbow's
+      # RGB-to-256 mapping snaps everything dark to palette index 16
+      # (terminal black), so we emit the escape directly to reach the ramp.
+      # @return [String]
+      INACTIVE_BG_SGR = "\e[48;5;238m"
+
+      # Handles a key. Returns false when the component is inactive. Otherwise
+      # first runs the {Component#handle_key} shortcut search via `super`, then
+      # delegates to {#handle_text_input_key}.
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return false unless active?
+        return true if super
+
+        handle_text_input_key(key)
+      end
+
+      protected
+
+      # Input filter for {#text=}. Subclasses override to truncate or reject
+      # invalid input. Default coerces to String.
+      # @param new_text [String]
+      # @return [String] possibly transformed text.
+      def preprocess_text(new_text) = new_text.to_s
+
+      # Hook called after {#text} has been mutated, before invalidation /
+      # {#on_change}. Default no-op. Subclasses use this to invalidate caches
+      # ({TextArea}'s wrap cache) and update derived state.
+      # @return [void]
+      def on_text_mutated; end
+
+      # Hook called after {#caret} has been mutated, before invalidation.
+      # Default no-op. Subclasses use this to keep the caret visible
+      # ({TextArea}'s vertical scroll).
+      # @return [void]
+      def on_caret_mutated; end
+
+      # Dispatch hook for {#handle_key}. Handles ESC and the navigation keys
+      # that have identical semantics in single-line and multi-line inputs:
+      # LEFT/RIGHT arrows, CTRL+LEFT/CTRL+RIGHT for word jumps. Subclasses
+      # override to add their own keys (HOME/END, UP/DOWN, ENTER, BACKSPACE/
+      # DELETE, printable insertion) and call `super` to fall back to the
+      # common navigation handling.
+      # @param key [String]
+      # @return [Boolean] true if the key was handled.
+      def handle_text_input_key(key)
+        case key
+        when Keys::LEFT_ARROW then self.caret = @caret - 1
+        when Keys::RIGHT_ARROW then self.caret = @caret + 1
+        when Keys::CTRL_LEFT_ARROW then self.caret = word_left
+        when Keys::CTRL_RIGHT_ARROW then self.caret = word_right
+        when Keys::ESC
+          return false if @on_escape.nil?
+
+          @on_escape.call
+        else
+          return false
+        end
+        true
+      end
+
+      # @return [void]
+      def delete_before_caret
+        return if @caret.zero?
+
+        new_text = @text.dup
+        new_text.slice!(@caret - 1)
+        @caret -= 1
+        self.text = new_text
+      end
+
+      # @return [void]
+      def delete_at_caret
+        return if @caret >= @text.length
+
+        new_text = @text.dup
+        new_text.slice!(@caret)
+        self.text = new_text
+      end
+
+      private
+
+      # Default {#on_escape} action: clear focus. Component deactivates; user
+      # can re-focus by clicking or tabbing back in.
+      # @return [void]
+      def default_on_escape
+        screen.focused = nil
+      end
+
+      # Caret target for ctrl+left: skip whitespace going left, then a run of
+      # non-whitespace. Lands at the beginning of the current word, or the
+      # beginning of the previous word if already there.
+      # @return [Integer]
+      def word_left
+        c = @caret
+        c -= 1 while c.positive? && @text[c - 1].match?(/\s/)
+        c -= 1 while c.positive? && !@text[c - 1].match?(/\s/)
+        c
+      end
+
+      # Caret target for ctrl+right: skip non-whitespace going right, then a
+      # run of whitespace. Lands at the beginning of the next word, or at the
+      # end of the text if no further word exists.
+      # @return [Integer]
+      def word_right
+        c = @caret
+        c += 1 while c < @text.length && !@text[c].match?(/\s/)
+        c += 1 while c < @text.length && @text[c].match?(/\s/)
+        c
+      end
+    end
+  end
+end

data/lib/tuile/component/text_view.rb

@@ -12,9 +12,19 @@ module Tuile
     # ANSI-as-bytes wrapping, color does *not* get dropped on continuation
     # rows). {#text=} accepts a {String} (parsed via {StyledString.parse},
     # so embedded ANSI is honored) or a {StyledString} directly; {#text}
-    # always returns the {StyledString}. Use {#append} for incremental "log
-    # line" style updates; turn on {#auto_scroll} to keep the latest content
-    # in view.
+    # always returns the {StyledString}.
+    #
+    # For incremental updates pick the right primitive: {#append} (aliased
+    # as `<<`) is verbatim and stream-friendly — chunks are concatenated
+    # straight onto the buffer, with embedded `\n` becoming hard breaks.
+    # {#add_line} is the "log entry" convenience — it starts the content on
+    # a fresh line by inserting a leading `\n` when the buffer is non-empty.
+    # {#remove_last_n_lines} pops hard lines back off the tail — the
+    # inverse of building up a region with {#append} / {#add_line}, so a
+    # caller streaming reformattable content (e.g. partially-rendered
+    # Markdown that may need to retract its last paragraph) can replace
+    # the tail without rewriting the whole text. Turn on {#auto_scroll}
+    # to keep the latest content in view.
     #
     # TextView is meant to be the content of a {Window} — focus indication and
     # keyboard-hint surfacing rely on the surrounding window chrome.
@@ -76,35 +86,117 @@ module Tuile
         invalidate
       end
 
-      # Appends `str` as a new physical line. If the current text is empty,
-      # behaves like `text = str`; otherwise prepends a newline so the new
-      # content lands on a fresh line. Accepts the same input forms as
-      # {#text=}.
+      # @return [Boolean] true iff {#text} is empty (no hard lines).
+      def empty? = @hard_lines.empty?
+
+      # Appends `str` verbatim. Embedded `\n` characters become hard line
+      # breaks; otherwise the text is concatenated onto the current last
+      # hard line. Designed for streaming use (e.g. an LLM chat window
+      # receiving partial messages — feed each chunk straight in). Accepts
+      # the same input forms as {#text=}; empty/`nil` input is a no-op.
+      #
+      # For the "add an entry on a new line" pattern use {#add_line}.
       #
-      # Cost is O(appended) rather than O(total) — the existing wrapped
-      # buffer is reused, only the new hard line(s) are wrapped and padded,
-      # and `@content_size` is updated incrementally. The cached
-      # {#text} is invalidated and rebuilt on demand.
+      # Cost is O(appended + width-of-current-last-hard-line) — the
+      # previously last hard line is re-wrapped (because the extension may
+      # cause it to wrap differently), any additional hard lines created by
+      # embedded `\n` are wrapped fresh. The cached {#text} is invalidated
+      # and rebuilt on demand.
       # @param str [String, StyledString, nil]
       # @return [void]
       def append(str)
         screen.check_locked
         appended = StyledString.parse(str)
-        if @hard_lines.empty?
-          self.text = appended
-          return
+        return if appended.empty?
+
+        new_segments = appended.lines
+        width = wrap_width
+
+        if empty?
+          new_segments.each do |hl|
+            @hard_lines << hl
+            append_physical_lines(hl, width)
+          end
+        else
+          extension = new_segments.first
+          unless extension.empty?
+            old_last = @hard_lines.pop
+            drop_physical_rows_for(old_last, width)
+            extended = old_last + extension
+            @hard_lines << extended
+            append_physical_lines(extended, width)
+          end
+          new_segments[1..].each do |hl|
+            @hard_lines << hl
+            append_physical_lines(hl, width)
+          end
         end
 
-        new_hard_lines = appended.lines
         @text = nil
-        @hard_lines.concat(new_hard_lines)
-        new_width = new_hard_lines.map(&:display_width).max || 0
-        @content_size = Size.new(
-          [@content_size.width, new_width].max,
-          @content_size.height + new_hard_lines.size
-        )
+        @content_size = compute_content_size
+        update_top_line_if_auto_scroll
+        invalidate
+      end
+
+      # Verbatim append, returning `self` for chainability (`view << a << b`).
+      # @param str [String, StyledString, nil]
+      # @return [self]
+      def <<(str)
+        append(str)
+        self
+      end
+
+      # Appends `str` as a new entry: starts a fresh hard line first (when
+      # the buffer is non-empty) and then appends `str`. Equivalent to
+      # `append("\n" + str)` on a non-empty buffer, or `append(str)` on an
+      # empty one. `nil` and `""` produce a blank entry on a non-empty
+      # buffer and a no-op on an empty buffer (matches the old `append`
+      # semantics for "log line" callers).
+      # @param str [String, StyledString, nil]
+      # @return [void]
+      def add_line(str)
+        parsed = StyledString.parse(str)
+        if empty?
+          append(parsed)
+        else
+          append(StyledString.plain("\n") + parsed)
+        end
+      end
+
+      # Drops the last `n` hard lines from the buffer. The inverse of
+      # building up a tail region with {#append} / {#add_line}: a caller
+      # streaming partially-rendered content whose tail must occasionally
+      # be retracted (e.g. Markdown-to-ANSI where a new token reformats
+      # the table being built) can call `remove_last_n_lines(k)` followed
+      # by `append(new_tail)` to replace the damaged region in place.
+      #
+      # `n == 0` and the empty-buffer case are no-ops (no invalidation).
+      # `n >= hard-line count` empties the buffer.
+      #
+      # Operates on **hard lines** (the `\n`-delimited entries the
+      # buffer stores), not on wrapped physical rows — same granularity
+      # as {#add_line}. Cost is O(rendered-rows of the popped lines).
+      # @param n [Integer] number of hard lines to drop; must be >= 0.
+      # @raise [TypeError] if `n` isn't an `Integer`.
+      # @raise [ArgumentError] if `n` is negative.
+      # @return [void]
+      def remove_last_n_lines(n)
+        raise TypeError, "expected Integer, got #{n.inspect}" unless n.is_a?(Integer)
+        raise ArgumentError, "n must not be negative, got #{n}" if n.negative?
+
+        screen.check_locked
+        return if n.zero? || empty?
+
         width = wrap_width
-        new_hard_lines.each { |hl| append_physical_lines(hl, width) }
+        to_drop = [n, @hard_lines.size].min
+        to_drop.times do
+          popped = @hard_lines.pop
+          drop_physical_rows_for(popped, width)
+        end
+
+        @text = nil
+        @content_size = compute_content_size
+        @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
       end
@@ -255,6 +347,19 @@ module Tuile
         end
       end
 
+      # Pops from {@physical_lines} the rows that `hard_line` previously
+      # contributed (the inverse of {#append_physical_lines} for the same
+      # input). Used by {#append} when extending the last hard line: its
+      # old wrapped rows are dropped, then the extended hard line is
+      # re-wrapped and appended.
+      # @param hard_line [StyledString]
+      # @param width [Integer]
+      # @return [void]
+      def drop_physical_rows_for(hard_line, width)
+        count = hard_line.empty? || width <= 0 ? 1 : hard_line.wrap(width).size
+        count.times { @physical_lines.pop }
+      end
+
       # Rebuilds the joined {StyledString} from {@hard_lines}, inserting a
       # default-styled `"\n"` between hard lines. Called from the {#text}
       # reader when the cache is cold. Cost is O(total spans).

data/lib/tuile/component/window.rb

@@ -8,8 +8,9 @@ module Tuile
     #
     # The window's `content` is unset by default; assign one via {#content=}.
     #
-    # Window is considered invisible if {#rect} is empty or one of left/top is
-    # negative. The window won't draw when invisible.
+    # Window is considered invisible if {#rect} is empty. The window won't
+    # draw when invisible. (Repaint of detached windows is short-circuited
+    # by {Component#invalidate}; subclasses don't need to re-check.)
     class Window < Component
       include Component::HasContent
 
@@ -125,12 +126,6 @@ module Tuile
         Size.new(inner_w + 2, inner_h + 2)
       end
 
-      # @return [Boolean] true if {#rect} is off screen and the window won't
-      #   paint.
-      def visible?
-        !@rect.empty? && !@rect.top.negative? && !@rect.left.negative?
-      end
-
       # Fully repaints the window: both frame and contents.
       #
       # Window deliberately paints over its entire rect (border around the
@@ -143,7 +138,7 @@ module Tuile
       # cycle.
       # @return [void]
       def repaint
-        return unless visible?
+        return if rect.empty?
 
         super
         repaint_border
@@ -168,7 +163,7 @@ module Tuile
       # Paints the window border.
       # @return [void]
       def repaint_border
-        return unless visible?
+        return if rect.empty?
 
         frame = build_frame(frame_caption)
         frame = Rainbow(frame).green if active?