tuile 0.15.0 → 0.16.0

data/examples/sampler.rb

@@ -12,11 +12,25 @@
 # Keys: ←→ along the strip, Enter/↓ to open a menu, or a letter for the
 # underlined mnemonic. Tab / Shift+Tab move focus between the strip, the jump
 # box and the demo's widgets. q or ESC quits.
+#
+# Runs at `capture_mouse: :hover` — the Mouse demo needs it, and the level is
+# one app-wide choice made at the event loop.
 
 require "rainbow"
 require "tuile"
 
 module SamplerExample
+  # `hint` is the app's token, not Tuile's: the framework carries accents for
+  # the chrome *it* paints, and the status row below is the sampler's own
+  # (`D_status_bar` — Tuile draws none). Paired in a ThemeDef so it survives an
+  # OS appearance flip, where a bare `theme=` would be replaced. Both greys
+  # quantize to :bright_black on a 16-color terminal, so the description stays
+  # dimmer than the key beside it even there.
+  APP_THEME = Tuile::ThemeDef.new(
+    dark: Tuile::Theme::DARK.with(custom: { hint: Tuile::Color::GREY54 }),
+    light: Tuile::Theme::LIGHT.with(custom: { hint: Tuile::Color::GREY62 })
+  )
+
   # Sampler-local container: a {Tuile::Component::Layout::Absolute} that runs a
   # caller-supplied block on `rect=` to position its children. Most demos are
   # plain stacks and use the box layouts instead; this is what's left for the
@@ -49,18 +63,18 @@ module SamplerExample
     # @return [Proc, nil] called with no arguments on each frame.
     attr_writer :on_tick
 
-    def on_attached
+    def handle_attached
       @ticker = screen.event_queue.tick_fps(@fps) { @on_tick&.call }
     end
 
-    def on_detached
+    def handle_detached
       @ticker&.cancel
       @ticker = nil
     end
   end
 
   # A {Tuile::Component::Layout::Vertical} that claims one key for itself. An
-  # ancestor's `handle_key` is where a scope-wide binding belongs (key-dispatch
+  # ancestor's `handle_key?` is where a scope-wide binding belongs (key-dispatch
   # rung 3); the Select demo uses one to show the letter still arriving while a
   # Select has focus — the capability a ComboBox, which eats every printable
   # unconditionally, cannot offer.
@@ -73,7 +87,7 @@ module SamplerExample
     # @return [Proc, nil] called with no arguments when the shortcut arrives.
     attr_writer :on_shortcut
 
-    def handle_key(key)
+    def handle_key?(key)
       return false unless key == @shortcut
 
       @on_shortcut&.call
@@ -100,7 +114,7 @@ module SamplerExample
 
     protected
 
-    def handle_text_input_key(key)
+    def handle_text_input_key?(key)
       return super unless key == Tuile::Keys::ENTER
 
       @on_submit&.call(text)
@@ -115,8 +129,8 @@ module SamplerExample
   # a newline with no menu up — stays the TextArea's own.
   #
   # Subclassing *is* the seam for this. A component receives keys through
-  # `handle_key`, so one that wants different keys overrides it (here its
-  # `handle_text_input_key` hook) and calls `super` for the rest, which composes
+  # `handle_key?`, so one that wants different keys overrides it (here its
+  # `handle_text_input_key?` hook) and calls `super` for the rest, which composes
   # and stacks. None of this is baked into TextArea.
   class SlashCommandTextArea < Tuile::Component::TextArea
     # @param overlay [Tuile::Component::ListDropdown] the menu to steer.
@@ -127,7 +141,7 @@ module SamplerExample
 
     protected
 
-    def handle_text_input_key(key)
+    def handle_text_input_key?(key)
       return super unless @overlay.open?
       return true if @overlay.move(key) # Up/Down/PgUp/PgDn/^U/^D
 
@@ -140,6 +154,291 @@ module SamplerExample
     end
   end
 
+  # A drawing surface answering every mouse handler, in two inks that both
+  # persist: a left-drag strokes `X`, a plain hover leaves a `.` trail behind
+  # the pointer, and a right-drag lifts marks again.
+  #
+  #      X          a diagonal drag, then one hover sweep across it
+  #       X
+  #        X
+  #         X
+  #     .....X........
+  #           X
+  #
+  # A trail never overwrites a stroke, so the picture stays a readout of which
+  # channel drew which cell — an eraser-on-hover would instead make the drawing
+  # unviewable with the pointer over it.
+  #
+  #   canvas = Canvas.new
+  #   canvas.on_event = ->(line) { log.log(line) }
+  #   canvas.on_move = ->(event, count) { label.text = "#{event.x},#{event.y} (#{count})" }
+  #
+  # Two slots, because the traffic is two: {#on_event} carries the discrete
+  # events to a log, {#on_move} the ~84-a-second moves to one replaced row.
+  # Feeding both to a log would drown enter/exit inside 12 ms.
+  #
+  # Every gesture owes a key (`D_mouse`): the arrows move the caret, space or
+  # `x` strokes it, Delete lifts it, `c` clears. The trail, the enter/exit lines
+  # and {#on_move} need `capture_mouse: :hover` and arrive as nothing below it;
+  # the drag works from `:drag`, a single-cell stroke from `:clicks`.
+  #
+  # == Implementation details
+  # Both glyphs are ASCII on purpose: `·` is East-Asian Ambiguous, so a
+  # two-column trail cell would push every painted row past `rect.width`
+  # (`D_ambiguous_width`).
+  #
+  # It paints every cell of its rect itself, one {Tuile::Component#draw_text}
+  # per run of like cells, and so skips `super` in {#repaint} — whose
+  # auto-clear blanks the whole rect, which would re-emit every cell this widget
+  # is about to paint over anyway. Repainting whole on every move still costs
+  # one cell on the wire, since a cell dirties only on a real change.
+  #
+  # Marks are keyed by rect-local {Tuile::Point}: ink beyond a narrowed rect
+  # stops painting and comes back when the rect grows again.
+  class Canvas < Tuile::Component
+    # @return [String] the drag/keyboard ink.
+    STROKE = "X"
+    # @return [String] the hover ink.
+    TRAIL = "."
+
+    # Which ink each button drags — `nil` erases. The middle button is absent:
+    # a press this component declines bubbles on to the window around it.
+    # @return [Hash{Symbol => String, nil}]
+    DRAG_INK = { left: STROKE, right: nil }.freeze
+
+    # @return [Proc, nil] called with one line (String) per discrete event.
+    attr_accessor :on_event
+
+    # @return [Proc, nil] called with the {Tuile::Mouse::Event} and the number
+    #   of moves so far (Integer), on every move and every drag.
+    attr_accessor :on_move
+
+    # @return [Tuile::Point] the keyboard caret, in rect-local coordinates.
+    attr_reader :caret
+
+    # The marks, keyed by rect-local {Tuile::Point} — read-only in practice:
+    # writing one behind {#paint}'s back skips the `invalidate`.
+    # @return [Hash{Tuile::Point => String}]
+    attr_reader :ink
+
+    def initialize
+      super
+      @ink = {}
+      @caret = Tuile::Point.new(0, 0)
+      @moves = 0
+      @drag_ink = nil
+      @drag_outside = false
+    end
+
+    def focusable? = true
+
+    def tab_stop? = true
+
+    # @return [Tuile::Point, nil]
+    def cursor_position
+      return nil if rect.empty?
+
+      Tuile::Point.new(rect.left + @caret.x, rect.top + @caret.y)
+    end
+
+    # @return [Tuile::Color]
+    def default_bg_color = active? ? screen.theme.active_bg_color : screen.theme.input_bg_color
+
+    # Clamps the caret into the new rect, so a shrink cannot strand it — and
+    # with it the hardware cursor — outside what this widget paints.
+    # @param new_rect [Tuile::Rect]
+    def rect=(new_rect)
+      super
+      @caret = Tuile::Point.new(@caret.x.clamp(0, [new_rect.width - 1, 0].max),
+                                @caret.y.clamp(0, [new_rect.height - 1, 0].max))
+    end
+
+    # @return [void]
+    def repaint
+      return if rect.empty?
+
+      # The clear is what a self-painter opts out of; the cascade never is
+      # (`D_repaint_cascade`), leaf or not.
+      invalidate_children
+      trail_color = screen.theme[:hint]
+      rect.height.times { |row| draw_row(row, trail_color) }
+    end
+
+    # @param event [Tuile::Mouse::DownEvent]
+    # @return [Boolean]
+    def handle_mouse_down?(event)
+      unless DRAG_INK.key?(event.button)
+        report("down #{event.button} at #{event.x},#{event.y} — declined, bubbles to the window")
+        return false
+      end
+
+      report("down #{event.button} at #{event.x},#{event.y} — claimed, grab held")
+      @drag_ink = DRAG_INK.fetch(event.button)
+      @drag_outside = false
+      mark(cell_at(event))
+      true
+    end
+
+    # @param event [Tuile::Mouse::DragEvent]
+    # @return [void]
+    def handle_mouse_drag(event)
+      super
+      cell = cell_at(event)
+      if @drag_outside != cell.nil?
+        @drag_outside = cell.nil?
+        report(@drag_outside ? "drag left the canvas — the grab still delivers" : "drag back inside")
+      end
+      mark(cell)
+      report_move(event)
+    end
+
+    # @param event [Tuile::Mouse::UpEvent]
+    # @return [void]
+    def handle_mouse_up(event)
+      super
+      report("up at #{event.x},#{event.y} — grab released")
+      @drag_ink = nil
+    end
+
+    # @param event [Tuile::Mouse::MoveEvent]
+    # @return [Boolean]
+    def handle_mouse_move?(event)
+      cell = cell_at(event)
+      paint(cell, TRAIL) if cell && @ink[cell].nil?
+      report_move(event)
+      true
+    end
+
+    # @return [void]
+    def handle_mouse_enter
+      super
+      report("enter")
+    end
+
+    # @return [void]
+    def handle_mouse_exit
+      super
+      report("exit")
+    end
+
+    # Declines the notch — nothing here scrolls — which is what lets it bubble
+    # on to an ancestor that does.
+    # @param event [Tuile::Mouse::ScrollEvent]
+    # @return [Boolean] always false.
+    def handle_mouse_scroll?(event)
+      report("wheel #{event.direction} — declined, bubbles on")
+      false
+    end
+
+    # @param key [String]
+    # @return [Boolean]
+    def handle_key?(key)
+      case key
+      when Tuile::Keys::UP_ARROW then move_caret(0, -1)
+      when Tuile::Keys::DOWN_ARROW then move_caret(0, 1)
+      when Tuile::Keys::LEFT_ARROW then move_caret(-1, 0)
+      when Tuile::Keys::RIGHT_ARROW then move_caret(1, 0)
+      when " ", "x" then stroke_caret(STROKE)
+      when Tuile::Keys::DELETE, *Tuile::Keys::BACKSPACES then stroke_caret(nil)
+      when "c" then clear_marks
+      else return super
+      end
+      true
+    end
+
+    private
+
+    # One row, as runs of like cells: every cell is painted exactly once, so
+    # none is blanked and then painted over (`D_progress_bar`).
+    # @param row [Integer] rect-local row.
+    # @param trail_color [Tuile::Color]
+    # @return [void]
+    def draw_row(row, trail_color)
+      column = 0
+      while column < rect.width
+        glyph = @ink[Tuile::Point.new(column, row)]
+        run = 1
+        run += 1 while column + run < rect.width && @ink[Tuile::Point.new(column + run, row)] == glyph
+        text = (glyph || " ") * run
+        styled = glyph == TRAIL ? Tuile::StyledString.styled(text, fg: trail_color) : Tuile::StyledString.plain(text)
+        draw_text(rect.left + column, rect.top + row, styled)
+        column += run
+      end
+    end
+
+    # The event's cell in rect-local coordinates, or nil when it lands outside
+    # — which a grabbed {Tuile::Mouse::DragEvent} routinely does.
+    # @param event [Tuile::Mouse::Event]
+    # @return [Tuile::Point, nil]
+    def cell_at(event)
+      column = event.x - rect.left
+      row = event.y - rect.top
+      return nil unless (0...rect.width).cover?(column) && (0...rect.height).cover?(row)
+
+      Tuile::Point.new(column, row)
+    end
+
+    # Lays the dragged ink at `cell` and takes the caret with it, so a stroke
+    # can be continued from the keyboard. Outside the rect (`nil`) it is a
+    # no-op, which is a grabbed drag's normal case.
+    # @param cell [Tuile::Point, nil] rect-local.
+    # @return [void]
+    def mark(cell)
+      return if cell.nil?
+
+      paint(cell, @drag_ink)
+      @caret = cell
+    end
+
+    # @param cell [Tuile::Point] rect-local.
+    # @param ink [String, nil] nil lifts the mark.
+    # @return [void]
+    def paint(cell, ink)
+      return if @ink[cell] == ink
+
+      ink.nil? ? @ink.delete(cell) : @ink.store(cell, ink)
+      invalidate
+    end
+
+    # @param ink [String, nil]
+    # @return [void]
+    def stroke_caret(ink)
+      paint(@caret, ink)
+      report("#{ink || "lift"} at #{@caret.x},#{@caret.y} — from the keyboard")
+    end
+
+    # @param columns [Integer]
+    # @param rows [Integer]
+    # @return [void]
+    def move_caret(columns, rows)
+      return if rect.empty?
+
+      @caret = Tuile::Point.new((@caret.x + columns).clamp(0, rect.width - 1),
+                                (@caret.y + rows).clamp(0, rect.height - 1))
+      invalidate # the hardware cursor is placed from #cursor_position at flush
+    end
+
+    # @return [void]
+    def clear_marks
+      return if @ink.empty?
+
+      @ink.clear
+      report("cleared")
+      invalidate
+    end
+
+    # @param line [String]
+    # @return [void]
+    def report(line) = @on_event&.call(line)
+
+    # @param event [Tuile::Mouse::Event]
+    # @return [void]
+    def report_move(event)
+      @moves += 1
+      @on_move&.call(event, @moves)
+    end
+  end
+
   # Top-level sampler component: a shell row across the top — a
   # {Tuile::Component::MenuBar} of the demos, grouped, and a
   # {Tuile::Component::ComboBox} jump box at its right end — over one demo
@@ -172,7 +471,8 @@ module SamplerExample
     def refresh_status
       focused = screen.focused
       name = focused ? focused.class.name.sub("Tuile::Component::", "") : "(none)"
-      @status.text = "q #{screen.theme.hint("quit")}  ⇥ #{screen.theme.hint(name)}"
+      t = screen.theme
+      @status.text = "q #{t.fg(:hint, "quit")}  ⇥ #{t.fg(:hint, name)}"
     end
 
     # Chrome for a demo pane: a blank row top and bottom, two columns either
@@ -208,9 +508,10 @@ module SamplerExample
     # as a live index of the catalogue and any drift between the two is visible.
     #
     # Mnemonics are *hand-picked*: {Tuile::Component::MenuBar#add_item} raises on
-    # a duplicate among siblings, and five leaves therefore answer to a letter
+    # a duplicate among siblings, and six leaves therefore answer to a letter
     # other than their initial (Past`e`, Checkbox`G`roup, C`o`mboBox,
-    # Pic`k`erWindow, S`l`ash menu) — the underline shows which. No item may use
+    # Pic`k`erWindow, S`l`ash menu, DateTi`m`eField) — the underline shows which.
+    # No item may use
     # `q`: quit is the unhandled-key fallback, so a `q` on the live level would
     # swallow it while the bar has focus.
     MENUS = [
@@ -233,6 +534,7 @@ module SamplerExample
                             Entry.new("BigDecimalField", :build_big_decimal_field, "b"),
                             Entry.new("DateField", :build_date_field, "d"),
                             Entry.new("TimeField", :build_time_field, "t"),
+                            Entry.new("DateTimeField", :build_date_time_field, "m"),
                             Entry.new("Bad input", :build_bad_input, "a"),
                             Entry.new("Validation", :build_validation, "v")
                           ]),
@@ -246,7 +548,7 @@ module SamplerExample
                           ])
                ]),
       # One entry, so it is the item and not a menu — a top-level leaf on the
-      # strip is a button, which nothing else here demos.
+      # strip is a button rather than a drop-down.
       Entry.new("Button", :build_buttons, "b"),
       Menu.new("Overlay", "o", [
                  Entry.new("Popup", :build_popup_launcher, "p"),
@@ -264,7 +566,10 @@ module SamplerExample
                  Entry.new("Background", :build_background, "b"),
                  Entry.new("Visibility", :build_visibility, "v"),
                  Entry.new("Focus & Tab", :build_focus_demo, "f")
-               ])
+               ]),
+      # The one demo needing a tracking level above the default, which is why
+      # the runner asks for `capture_mouse: :hover` for the whole app.
+      Entry.new("Mouse", :build_mouse_demo, "m")
     ].freeze
 
     # Every {Entry} in strip order — what the jump box offers.
@@ -568,6 +873,39 @@ module SamplerExample
       end
     end
 
+    # DateTimeField: the ink rule, which neither half can show alone. Leave the
+    # time empty and the *whole* widget reddens — half-filled is a fault no
+    # single half committed — where garbage in the date half reddens that half
+    # by itself. Both only on the way out, which is why pressing Enter first
+    # visibly changes nothing.
+    #
+    # The echo row carries the value and Save the verdict, the division
+    # `D_bad_input` draws: the notice is a push, fired when a half commits;
+    # `bad_input?` is a pull, read at the click. The Saved alert spells the
+    # value out with the `+00:00` the halves cannot fill in — `D_time_field`'s
+    # epoch cost, visible rather than hidden.
+    def build_date_time_field
+      prompt = Tuile::Component::Label.new
+      prompt.text = "Tab here, type 2026-09-14, leave the time empty — then press Enter: nothing reddens.\n" \
+                    "Tab away and both halves redden at once: half-filled is the composite's own fault.\n" \
+                    "Now type 2026-99-99 in the date half instead — it reddens alone, the time half stays clean.\n" \
+                    "Save asks bad_input? at the click and names whichever fault it found."
+      field = Tuile::Component::DateTimeField.new
+      status = Tuile::Component::Label.new
+      # strftime, not inspect: DateTime#inspect spells out the Julian day, noise
+      # next to the one fact this row carries.
+      report = -> { status.text = "value: #{field.value&.strftime("%Y-%m-%d %H:%M") || "nil"}" }
+      report.call
+      field.on_value_change = ->(_value) { report.call }
+      save = Tuile::Component::Button.new("Save") { save_form("Starts at" => field) }
+      form do |f|
+        f.add(prompt, Fixed[4])
+        f.add(labelled("Starts at", field, field_width: 20), Fixed[1], cross: Fixed[36])
+        f.add(status, Fixed[1])
+        f.add(save, Fixed[1], cross: Fixed[button_width(save)])
+      end
+    end
+
     # HasBadInput: the one fact on_value_change cannot carry. Type a lone "-"
     # and watch the echo row stay silent — the value was nil before and is nil
     # after, so there is no diff to report — while Save, which asks bad_input?
@@ -945,7 +1283,7 @@ module SamplerExample
     # *items* — LogLevel objects, not their labels — so the filter below is plain
     # set membership, no lookup table. Rows come from `item_label`, which may
     # return styled text (these colors are inherent to the data, not theme
-    # accents, so they need no on_theme_changed hook).
+    # accents, so they need no handle_theme_changed hook).
     def build_checkbox_group
       prompt = Tuile::Component::Label.new
       # Kept under 48 columns a line, so an 80-column terminal shows it whole.
@@ -1014,7 +1352,7 @@ module SamplerExample
     SAMPLE_FILES = [
       SampleFile.new("AGENTS.md", 31_402, "2026-07-30"),
       SampleFile.new("CHANGELOG.md", 4118, "2026-07-05"),
-      SampleFile.new("DECISIONS.md", 48_990, "2026-07-31"),
+      SampleFile.new("design/decisions.md", 48_990, "2026-07-31"),
       SampleFile.new("Gemfile", 312, "2026-06-18"),
       SampleFile.new("README.md", 9674, "2026-07-12"),
       SampleFile.new("Rakefile", 2118, "2026-06-18"),
@@ -1205,7 +1543,7 @@ module SamplerExample
       # the tint flows down to every descendant without its own background — the
       # label and the list — while the input widgets (the combo, the field) keep
       # their own well. Theme::Ref picks re-resolve on a scheme flip with no hook;
-      # the hard-coded Colors are fixed by design, so no on_theme_changed here.
+      # the hard-coded Colors are fixed by design, so no handle_theme_changed here.
       outer = nil
       derived = terminal_tint_choice
       combo = Tuile::Component::ComboBox.new(items: bg_choices(derived))
@@ -1543,9 +1881,14 @@ module SamplerExample
         "PickerWindow asks the user to pick one option by a single keystroke.",
         "Open PickerWindow"
       ) do
+        # Captions paint in the terminal's own foreground — the picker
+        # recommends no color of its own. Styling one is the app's call, and
+        # per option: a caption may be a String, an ANSI-coded String (what
+        # `theme.fg` hands back) or a StyledString.
         Tuile::Component::PickerWindow.open(
           "Pick a fruit",
-          [%w[a Apple], %w[b Banana], %w[c Cherry]]
+          [%w[a Apple], %w[b Banana],
+           ["c", "Cherry #{screen.theme.fg(:hint, "(in season)")}"]]
         ) { |key| Tuile.logger.info("Picked: #{key}") }
       end
     end
@@ -1578,6 +1921,31 @@ module SamplerExample
       end
     end
 
+    def build_mouse_demo
+      intro = Tuile::Component::Label.new
+      intro.text = "Drag on the canvas to draw X; right-drag erases; just hovering leaves a dim\n" \
+                   "trail. Arrows move the caret, space or x strokes it, Delete lifts it, c clears.\n" \
+                   "Discrete events go to the log; the row below is the live pointer."
+      canvas = Canvas.new
+      pointer = Tuile::Component::Label.new
+      pointer.text = "pointer: (move over the canvas)"
+      log = Tuile::Component::LogWindow.new("Events")
+      canvas.on_event = ->(line) { log.log(line) }
+      canvas.on_move = lambda do |event, count|
+        kind = event.is_a?(Tuile::Mouse::DragEvent) ? "drag" : "move"
+        pointer.text = "pointer: #{event.x},#{event.y}  (#{kind}, #{count} reported so far)"
+      end
+      surface = row do |r|
+        r.add(Tuile::Component::Window.new("Canvas").tap { _1.content = canvas }, Percent[55])
+        r.add(log, Expand[1])
+      end
+      form do |f|
+        f.add(intro, Fixed[3])
+        f.add(surface, Expand[1])
+        f.add(pointer, Fixed[1])
+      end
+    end
+
     # --- Helpers -----------------------------------------------------------
 
     def panel(*children, &layout_block)
@@ -1678,13 +2046,19 @@ end
 # component tree without spinning up the real event loop.
 if $PROGRAM_NAME == __FILE__
   screen = Tuile::Screen.new
+  screen.theme_def = SamplerExample::APP_THEME
   sampler = SamplerExample::Sampler.new
   screen.content = sampler
   screen.on_focus_changed = -> { sampler.refresh_status }
   sampler.refresh_status
   sampler.menu_bar.focus
   begin
-    screen.run_event_loop
+    # `:hover` for the whole app, because the level is set once here and is
+    # all-or-nothing: the Mouse demo's trail and enter/exit lines arrive at no
+    # lower one. The upgrade from the default `:clicks` costs the ~84 motion
+    # reports a second (`R_mouse_reporting`) — not select-to-copy, which mode
+    # 1000 had already taken.
+    screen.run_event_loop(capture_mouse: :hover)
   ensure
     screen.close
   end

data/lib/tuile/component/abstract_string_field.rb

@@ -24,7 +24,7 @@ module Tuile
     #   f.text  = "e\u{0301}x"   # a decomposed e-acute then "x": 3 chars, 2 glyphs
     #   f.caret = 1              # into the middle of the e-acute …
     #   f.caret                  # => 2, its end — where the caret already drew
-    #   f.handle_key(Keys::BACKSPACE)
+    #   f.handle_key?(Keys::BACKSPACE)
     #   f.text                   # => "x": the whole glyph went, not its accent
     #
     # Insertion stays character-native, so `String#insert` merges a typed
@@ -34,11 +34,11 @@ module Tuile
     # 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
+    # {#handle_text_input_key?} hook — `super` falls through to the common
     # navigation handling.
     #
     # == Customizing a field is subclassing it, and there are two seams
-    # To change what **keys** do, override {#handle_text_input_key}; to
+    # To change what **keys** do, override {#handle_text_input_key?}; to
     # constrain what the buffer may **hold**, override {#insert_text}, which
     # every insertion runs through — typed, pasted, or the ENTER newline:
     #
@@ -46,7 +46,7 @@ module Tuile
     #     protected
     #
     #     # ENTER submits instead of falling through to the parent.
-    #     def handle_text_input_key(key)
+    #     def handle_text_input_key?(key)
     #       return super unless key == Keys::ENTER
     #
     #       submit(text)
@@ -76,7 +76,7 @@ module Tuile
     #   which insertion does *not* pass through.
     # - {#preprocess_paste} — sanitizer for {#handle_paste}, run before the
     #   clipboard reaches {#insert_text} ({TextField} keeps its first line).
-    # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
+    # - {#handle_text_mutated} / {#handle_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
     class AbstractStringField < Component
@@ -141,7 +141,7 @@ module Tuile
 
         @text = +new_text
         @caret = snap_to_cluster(@caret.clamp(0, @text.length))
-        on_text_mutated
+        handle_text_mutated
         invalidate
         @on_change&.call(@text)
         on_value_change&.call(@text)
@@ -149,7 +149,7 @@ module Tuile
 
       # Clamps to `0..text.length`, then snaps forward onto a grapheme-cluster
       # boundary, so an index that fell inside a cluster reads back as that
-      # cluster's end. Fires the {#on_caret_mutated} hook for subclasses (e.g.
+      # cluster's end. Fires the {#handle_caret_mutated} hook for subclasses (e.g.
       # {TextArea} scrolls).
       # @param new_caret [Integer]
       def caret=(new_caret)
@@ -157,27 +157,25 @@ module Tuile
         return if @caret == new_caret
 
         @caret = new_caret
-        on_caret_mutated
+        handle_caret_mutated
         invalidate
       end
 
-      # Handles a key, by delegating to the {#handle_text_input_key} hook a
-      # subclass overrides. Dispatch ({ScreenPane#handle_key}) only routes keys
+      # Handles a key, by delegating to the {#handle_text_input_key?} hook a
+      # subclass overrides. Dispatch ({ScreenPane#handle_key?}) only routes keys
       # here when this input is on the focus chain, so there is no {#active?}
       # gate.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key) = handle_text_input_key(key)
+      def handle_key?(key) = handle_text_input_key?(key)
 
       # Inserts pasted text at the caret as **one** mutation, so {#on_change}
       # fires once for the whole paste rather than once per character.
       # {#preprocess_paste} filters it first.
       # @param text [String]
-      # @return [Boolean] always true — a field consumes every paste: an empty
-      #   one, and one its {#insert_text} rejects wholesale.
+      # @return [void]
       def handle_paste(text)
         insert_text(preprocess_paste(text))
-        true
       end
 
       protected
@@ -259,15 +257,15 @@ module Tuile
       # {#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
+      def handle_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
+      def handle_caret_mutated; end
 
-      # Dispatch hook for {#handle_key}. Handles ESC and the editing keys that
+      # Dispatch hook for {#handle_key?}. Handles ESC and the editing keys that
       # have identical semantics in single-line and multi-line inputs:
       # LEFT/RIGHT arrows (one grapheme cluster per press, so a press always
       # moves), CTRL+LEFT/CTRL+RIGHT for word jumps, and CTRL+W, which deletes
@@ -277,7 +275,7 @@ module Tuile
       # `super` to fall back to the common handling.
       # @param key [String]
       # @return [Boolean] true if the key was handled.
-      def handle_text_input_key(key)
+      def handle_text_input_key?(key)
         case key
         when Keys::LEFT_ARROW then self.caret = cluster_boundary_before(@caret)
         when Keys::RIGHT_ARROW then self.caret = cluster_boundary_after(@caret)