tuile 0.3.0 → 0.5.0

data/lib/tuile/component/text_area.rb

@@ -18,63 +18,22 @@ module Tuile
     # 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
+    class TextArea < TextInput
       def initialize
         super
-        @text = +""
-        @caret = 0
         @top_display_row = 0
-        @on_change = nil
+        # Lazy cache of the word-wrapped layout: an
+        # `Array<Hash{Symbol=>Integer}>` whose entries are
+        # `{start: <text-index>, length: <chars>}`, one per display row, built
+        # by {#compute_display_rows}. `nil` means "stale, recompute on next
+        # read". Reset to nil whenever {#text} mutates or the width changes;
+        # see {#on_text_mutated} and {#on_width_changed}.
         @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?
@@ -90,32 +49,6 @@ module Tuile
         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)
@@ -133,12 +66,6 @@ module Tuile
         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 [void]
       def repaint
         return if rect.empty?
@@ -160,6 +87,36 @@ module Tuile
 
       protected
 
+      # @return [void]
+      def on_text_mutated
+        @display_rows = nil
+        adjust_top_display_row
+      end
+
+      # @return [void]
+      def on_caret_mutated
+        adjust_top_display_row
+      end
+
+      # @param key [String]
+      # @return [Boolean]
+      def handle_text_input_key(key)
+        case key
+        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 Keys.printable?(key)
+
+          return super
+        end
+        true
+      end
+
       # @return [void]
       def on_width_changed
         super
@@ -298,40 +255,12 @@ module Tuile
       # @param char [String]
       # @return [Boolean] always true.
       def insert_char(char)
-        @text = @text.dup.insert(@caret, char)
+        new_text = @text.dup.insert(@caret, char)
         @caret += char.length
-        @display_rows = nil
-        adjust_top_display_row
-        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
-        @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
@@ -347,30 +276,6 @@ module Tuile
         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

@@ -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