tuile 0.1.0 → 0.2.0

data/lib/tuile/component/list.rb

@@ -22,6 +22,8 @@ module Tuile
         @scrollbar_visibility = :gone
         @show_cursor_when_inactive = false
         @on_item_chosen = nil
+        @on_cursor_changed = nil
+        @last_cursor_state = cursor_state
       end
 
       # @return [Proc, nil] callback fired when an item is chosen — by pressing
@@ -31,6 +33,16 @@ module Tuile
       #   {Cursor::None}, or empty content).
       attr_accessor :on_item_chosen
 
+      # @return [Proc, nil] callback fired when the `(index, line)` tuple under
+      #   the cursor changes. Called as `proc.call(index, line)` where `line`
+      #   is `nil` when the cursor is off-content ({Cursor::None}, empty list,
+      #   or `index` past the last line). Fires on cursor moves (key, mouse,
+      #   search), on {#cursor=}, and on {#lines=}/{#add_lines} when the line
+      #   at the cursor's index changes (or its in-range/out-of-range status
+      #   flips). Useful for keeping a details pane in sync with the
+      #   highlighted row.
+      attr_accessor :on_cursor_changed
+
       # @return [Boolean] if true and a line is added or new content is set,
       #   auto-scrolls to the bottom.
       attr_reader :auto_scroll
@@ -83,6 +95,7 @@ module Tuile
         old_position = @cursor.position
         @cursor = cursor
         invalidate if old_position != cursor.position
+        notify_cursor_changed
       end
 
       # Sets the top line.
@@ -107,6 +120,7 @@ module Tuile
         @lines = lines.flat_map { it.to_s.split("\n") }.map(&:rstrip)
         @content_size = nil
         update_top_line_if_auto_scroll
+        notify_cursor_changed
         invalidate
       end
 
@@ -146,6 +160,7 @@ module Tuile
         @lines += lines.flat_map { it.to_s.split("\n") }.map(&:rstrip)
         @content_size = nil
         update_top_line_if_auto_scroll
+        notify_cursor_changed
         invalidate
       end
 
@@ -160,6 +175,8 @@ module Tuile
 
       def focusable? = true
 
+      def tab_stop? = true
+
       # @param key [String] a key.
       # @return [Boolean] true if the key was handled.
       def handle_key(key)
@@ -178,6 +195,7 @@ module Tuile
           true
         elsif @cursor.handle_key(key, @lines.size, viewport_lines)
           move_viewport_to_cursor
+          notify_cursor_changed
           invalidate
           true
         else
@@ -222,6 +240,7 @@ module Tuile
           line = event.y - rect.top + top_line
           if @cursor.handle_mouse(line, event, @lines.size)
             move_viewport_to_cursor
+            notify_cursor_changed
             invalidate
           end
           fire_item_chosen if event.button == :left && line >= 0 && line < @lines.size && cursor_on_item?
@@ -229,9 +248,13 @@ module Tuile
       end
 
       # Paints the list items into {#rect}.
+      #
+      # Skips the {Component#repaint} default's auto-clear: every row of
+      # {#rect} is painted below (with padded content past the last item),
+      # so the parent contract — "fully draw over your rect" — is met
+      # without an upfront wipe.
       # @return [void]
       def repaint
-        super
         return if rect.empty?
 
         width = rect.width
@@ -302,9 +325,9 @@ module Tuile
             go_down_by(1, line_count)
           when *Keys::UP_ARROWS
             go_up_by(1)
-          when Keys::HOME
+          when *Keys::HOMES
             go_to_first
-          when Keys::END_
+          when *Keys::ENDS_
             go_to_last(line_count)
           when Keys::CTRL_U
             go_up_by(viewport_lines / 2)
@@ -446,6 +469,25 @@ module Tuile
         @on_item_chosen&.call(pos, @lines[pos])
       end
 
+      # @return [Array((Integer, String, nil))] `[position, line_at_position]`,
+      #   with `line` nil when the cursor is off-content.
+      def cursor_state
+        pos = @cursor.position
+        line = pos >= 0 && pos < @lines.size ? @lines[pos] : nil
+        [pos, line]
+      end
+
+      # Fires {#on_cursor_changed} if {#cursor_state} differs from the last
+      # fired state. Idempotent — safe to call after any mutation.
+      # @return [void]
+      def notify_cursor_changed
+        state = cursor_state
+        return if state == @last_cursor_state
+
+        @last_cursor_state = state
+        @on_cursor_changed&.call(*state)
+      end
+
       # @param query [String]
       # @param include_current [Boolean]
       # @param reverse [Boolean]
@@ -463,6 +505,7 @@ module Tuile
 
         @cursor.go(match)
         move_viewport_to_cursor
+        notify_cursor_changed
         invalidate
         true
       end
@@ -548,7 +591,7 @@ module Tuile
       def trim_to(str, width)
         return " " * width if str.empty?
 
-        truncated_line = Strings::Truncation.truncate(str, length: width)
+        truncated_line = Truncate.truncate(str, length: width)
         return truncated_line unless truncated_line == str
 
         length = Unicode::DisplayWidth.of(Rainbow.uncolor(str))

data/lib/tuile/component/text_area.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A multi-line, word-wrapping text input.
+    #
+    # Sized by the caller — {#rect} is fixed; the area does not grow with
+    # content. Text is wrapped to {Rect#width} columns and any text that
+    # doesn't fit vertically is reached by scrolling: {#top_display_row}
+    # follows the caret so the line being edited stays visible. There is no
+    # horizontal scrolling.
+    #
+    # The caret is a logical index in `0..text.length`. When the caret falls
+    # inside a whitespace run that was absorbed by a soft wrap, it displays
+    # at the end of the previous row (which is visually identical to the
+    # start of the next row in nearly all cases).
+    #
+    # Currently only {#on_change} is wired; Enter inserts a newline as in any
+    # plain `<textarea>` or text editor. A future `on_enter`/`on_submit`
+    # callback may opt out of that by consuming Enter instead.
+    class TextArea < Component
+      def initialize
+        super
+        @text = +""
+        @caret = 0
+        @top_display_row = 0
+        @on_change = nil
+        @display_rows = nil
+      end
+
+      # @return [String] current text contents (may contain embedded `\n`).
+      attr_reader :text
+
+      # @return [Integer] caret index in `0..text.length`.
+      attr_reader :caret
+
+      # @return [Integer] index of the topmost display row currently visible.
+      attr_reader :top_display_row
+
+      # Optional callback fired whenever {#text} changes. Receives the new text
+      # as a single argument. Not fired by {#caret=} (text unchanged), not
+      # fired by a no-op setter, and not fired by a re-wrap caused by a width
+      # change ({#text} itself is unchanged).
+      # @return [Proc, Method, nil] one-arg callable, or nil.
+      attr_accessor :on_change
+
+      # Sets the text. Caret is clamped to the new text length; vertical scroll
+      # is adjusted to keep the caret visible.
+      # @param new_text [String]
+      def text=(new_text)
+        new_text = new_text.to_s
+        return if @text == new_text
+
+        @text = +new_text
+        @caret = @caret.clamp(0, @text.length)
+        @display_rows = nil
+        adjust_top_display_row
+        invalidate
+        @on_change&.call(@text)
+      end
+
+      # Sets the caret position. Clamped to `0..text.length`; vertical scroll
+      # is adjusted to keep the caret visible.
+      # @param new_caret [Integer]
+      def caret=(new_caret)
+        new_caret = new_caret.clamp(0, @text.length)
+        return if @caret == new_caret
+
+        @caret = new_caret
+        adjust_top_display_row
+        invalidate
+      end
+
+      def focusable? = true
+
+      def tab_stop? = true
+
+      # @return [Point, nil]
+      def cursor_position
+        return nil if rect.empty?
+
+        row, col = caret_to_display(@caret)
+        screen_row = row - @top_display_row
+        return nil if screen_row.negative? || screen_row >= rect.height
+
+        # Cap so the hardware cursor never lands at rect.left+rect.width
+        # (one past the rect). Terminals with auto-wrap interpret that as
+        # column 0 of the row below; capping pins the cursor on the last
+        # visible cell instead.
+        Point.new(rect.left + col.clamp(0, rect.width - 1), rect.top + screen_row)
+      end
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return false unless active?
+        return true if super
+
+        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::UP_ARROW then move_caret_vertical(-1)
+        when Keys::DOWN_ARROW then move_caret_vertical(1)
+        when *Keys::HOMES then move_caret_to_row_start
+        when *Keys::ENDS_ then move_caret_to_row_end
+        when *Keys::BACKSPACES then delete_before_caret
+        when Keys::DELETE then delete_at_caret
+        when Keys::ENTER then insert_char("\n")
+        else
+          return insert_char(key) if printable?(key)
+
+          return false
+        end
+        true
+      end
+
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        super
+        return unless event.button == :left && rect.contains?(event.point)
+
+        target_row = (event.y - rect.top) + @top_display_row
+        target_col = event.x - rect.left
+        rows = display_rows
+        if target_row >= rows.size
+          self.caret = @text.length
+        else
+          r = rows[target_row]
+          self.caret = r[:start] + target_col.clamp(0, r[:length])
+        end
+      end
+
+      # Same SGR palette as {Component::TextField} for visual consistency.
+      # @return [String]
+      ACTIVE_BG_SGR = TextField::ACTIVE_BG_SGR
+      # @return [String]
+      INACTIVE_BG_SGR = TextField::INACTIVE_BG_SGR
+      # @return [String]
+      SGR_RESET = TextField::SGR_RESET
+
+      # @return [void]
+      def repaint
+        return if rect.empty?
+
+        bg = active? ? ACTIVE_BG_SGR : INACTIVE_BG_SGR
+        rows = display_rows
+        (0...rect.height).each do |screen_row|
+          row_idx = screen_row + @top_display_row
+          line = if row_idx >= rows.size
+                   " " * rect.width
+                 else
+                   r = rows[row_idx]
+                   chunk = @text[r[:start], r[:length]] || ""
+                   chunk + (" " * (rect.width - r[:length]))
+                 end
+          screen.print TTY::Cursor.move_to(rect.left, rect.top + screen_row), bg, line, SGR_RESET
+        end
+      end
+
+      protected
+
+      # @return [void]
+      def on_width_changed
+        super
+        @display_rows = nil
+        adjust_top_display_row
+      end
+
+      private
+
+      # @return [Array<Hash{Symbol=>Integer}>] cached wrap of {#text} for the
+      #   current {Rect#width}. Each entry is `{start:, length:}`.
+      def display_rows
+        @display_rows ||= compute_display_rows
+      end
+
+      # Greedy word-wrap. Whitespace at a soft-wrap break point is absorbed
+      # (not rendered on either row). A token longer than {Rect#width} hard-
+      # wraps inside the token. Newlines force a hard break and the wrap
+      # restarts on the next character.
+      # @return [Array<Hash{Symbol=>Integer}>]
+      def compute_display_rows
+        width = rect.width
+        return [{ start: 0, length: 0 }] if width <= 0 || @text.empty?
+
+        rows = []
+        pos = 0
+        n = @text.length
+
+        while pos < n
+          row_start = pos
+          row_chars = 0
+
+          while pos < n
+            c = @text[pos]
+            break if c == "\n"
+
+            if c.match?(/[ \t]/)
+              if row_chars < width
+                row_chars += 1
+                pos += 1
+              else
+                row_chars = trim_trailing_whitespace(row_start, row_chars)
+                pos += 1 while pos < n && @text[pos].match?(/[ \t]/)
+                break
+              end
+            else
+              word_end = pos
+              word_end += 1 while word_end < n && !@text[word_end].match?(/\s/)
+              word_len = word_end - pos
+
+              if row_chars + word_len <= width
+                row_chars += word_len
+                pos = word_end
+              elsif row_chars.zero?
+                row_chars = width
+                pos += width
+                break
+              else
+                row_chars = trim_trailing_whitespace(row_start, row_chars)
+                break
+              end
+            end
+          end
+
+          rows << { start: row_start, length: row_chars }
+
+          if pos < n && @text[pos] == "\n"
+            pos += 1
+            rows << { start: pos, length: 0 } if pos == n
+          end
+        end
+
+        rows << { start: 0, length: 0 } if rows.empty?
+        rows
+      end
+
+      # Trims trailing space/tab characters off a row's visible length so the
+      # whitespace at a soft-wrap point is absorbed (not rendered) rather than
+      # left at the end of the row. Without this, soft-wrapping `"foo bar"`
+      # to width 4 would yield row 0 length 4 (`"foo "`) and the natural
+      # end-of-row caret position would coincide with row 1's start.
+      # @param row_start [Integer]
+      # @param row_chars [Integer]
+      # @return [Integer] new row_chars.
+      def trim_trailing_whitespace(row_start, row_chars)
+        row_chars -= 1 while row_chars.positive? && @text[row_start + row_chars - 1].match?(/[ \t]/)
+        row_chars
+      end
+
+      # @param caret [Integer]
+      # @return [Array(Integer, Integer)] `[row_index, column]` for `caret`.
+      def caret_to_display(caret)
+        rows = display_rows
+        rows.each_with_index do |r, i|
+          next_start = i + 1 < rows.size ? rows[i + 1][:start] : @text.length + 1
+          next unless caret >= r[:start] && caret < next_start
+
+          return [i, (caret - r[:start]).clamp(0, r[:length])]
+        end
+        r = rows.last
+        [rows.size - 1, (caret - r[:start]).clamp(0, r[:length])]
+      end
+
+      # @param delta [Integer] `+1` for down, `-1` for up.
+      # @return [void]
+      def move_caret_vertical(delta)
+        rows = display_rows
+        cur_row, cur_col = caret_to_display(@caret)
+        new_row = (cur_row + delta).clamp(0, rows.size - 1)
+        if new_row == cur_row
+          # Already at the top/bottom display row. Snap to the absolute
+          # start/end of the text so the user has a quick way to reach it.
+          self.caret = delta.positive? ? @text.length : 0
+          return
+        end
+
+        r = rows[new_row]
+        self.caret = r[:start] + cur_col.clamp(0, r[:length])
+      end
+
+      # @return [void]
+      def move_caret_to_row_start
+        rows = display_rows
+        cur_row, = caret_to_display(@caret)
+        self.caret = rows[cur_row][:start]
+      end
+
+      # @return [void]
+      def move_caret_to_row_end
+        rows = display_rows
+        cur_row, = caret_to_display(@caret)
+        r = rows[cur_row]
+        self.caret = r[:start] + r[:length]
+      end
+
+      # @param char [String]
+      # @return [Boolean] always true.
+      def insert_char(char)
+        @text = @text.dup.insert(@caret, char)
+        @caret += char.length
+        @display_rows = nil
+        adjust_top_display_row
+        invalidate
+        @on_change&.call(@text)
+        true
+      end
+
+      # @return [void]
+      def delete_before_caret
+        return if @caret.zero?
+
+        @text = @text.dup
+        @text.slice!(@caret - 1)
+        @caret -= 1
+        @display_rows = nil
+        adjust_top_display_row
+        invalidate
+        @on_change&.call(@text)
+      end
+
+      # @return [void]
+      def delete_at_caret
+        return if @caret >= @text.length
+
+        @text = @text.dup
+        @text.slice!(@caret)
+        @display_rows = nil
+        adjust_top_display_row
+        invalidate
+        @on_change&.call(@text)
+      end
+
+      # Keeps the caret visible by scrolling vertically.
+      # @return [void]
+      def adjust_top_display_row
+        return if rect.empty?
+
+        rows = display_rows
+        cur_row, = caret_to_display(@caret)
+        if cur_row < @top_display_row
+          @top_display_row = cur_row
+        elsif cur_row >= @top_display_row + rect.height
+          @top_display_row = cur_row - rect.height + 1
+        end
+        max_top = (rows.size - rect.height).clamp(0, nil)
+        @top_display_row = @top_display_row.clamp(0, max_top)
+      end
+
+      # @param key [String]
+      # @return [Boolean]
+      def printable?(key)
+        key.length == 1 && key.ord >= 0x20 && key.ord < 0x7f
+      end
+
+      # Same semantics as {TextField}'s ctrl+left.
+      # @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
+
+      # Same semantics as {TextField}'s ctrl+right.
+      # @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_field.rb

@@ -87,6 +87,8 @@ module Tuile
 
       def focusable? = true
 
+      def tab_stop? = true
+
       # @return [Point, nil]
       def cursor_position
         return nil unless rect.width.positive?
@@ -103,8 +105,10 @@ module Tuile
         case key
         when Keys::LEFT_ARROW then self.caret = @caret - 1
         when Keys::RIGHT_ARROW then self.caret = @caret + 1
-        when Keys::HOME then self.caret = 0
-        when Keys::END_ then self.caret = @text.length
+        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
@@ -140,12 +144,31 @@ module Tuile
         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"
+      # SGR reset.
+      # @return [String]
+      SGR_RESET = "\e[0m"
+
       # @return [void]
       def repaint
-        clear_background
         return if rect.empty?
 
-        screen.print TTY::Cursor.move_to(rect.left, rect.top), @text
+        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, SGR_RESET
       end
 
       protected
@@ -204,6 +227,28 @@ module Tuile
       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/window.rb

@@ -132,13 +132,21 @@ module Tuile
       end
 
       # Fully repaints the window: both frame and contents.
+      #
+      # Window deliberately paints over its entire rect (border around the
+      # edge, content/footer over the interior), so we don't need the
+      # {Component#repaint} default's auto-clear — but we do still want its
+      # "re-invalidate children" effect, since the border overpaints
+      # whatever the content/footer drew on the perimeter. Calling super
+      # handles both: the auto-clear is harmless (we re-paint over it), and
+      # the invalidation queues content + footer for repaint in the same
+      # cycle.
       # @return [void]
       def repaint
+        return unless visible?
+
         super
         repaint_border
-        # Border paints over content: invalidate the content to have it
-        # repainted.
-        content&.invalidate
       end
 
       # @param key [String, nil]