tuile 0.16.0 → 0.17.0

data/lib/tuile/buffer.rb

@@ -3,7 +3,7 @@
 module Tuile
   # An in-memory grid of styled cells mirroring the terminal screen. This is
   # the back buffer behind flicker-free rendering: components paint into it
-  # (via {#set_text} / {#set_char} / {#fill}) instead of writing escape
+  # through a {Canvas}, whose {Canvas::Backend} it is, instead of writing escape
   # sequences straight to the terminal, and {#flush} emits the minimal escape
   # string needed to bring a terminal — one that already matches the buffer's
   # state as of the previous flush — up to date. Only cells that actually
@@ -34,6 +34,10 @@ module Tuile
   # Overwriting either half of a wide glyph blanks the orphaned half, so the
   # grid never holds a dangling continuation or a headless one.
   class Buffer
+    # The three primitives below are exactly {Canvas::Backend}'s, so a canvas
+    # paints into a buffer with no adapter between them.
+    include Canvas::Backend
+
     # One screen cell: a single grapheme cluster, the {StyledString::Style} it's
     # drawn in, and a dirty flag. Mutable by design (see {Buffer} "Dirty
     # tracking") — the grid rewrites cells in place. A continuation cell (right
@@ -317,6 +321,13 @@ module Tuile
       region_cells(rect).map { |row| row.map(&:grapheme).join }
     end
 
+    # {#region_text} over the whole buffer, for one {Testing.paint} returned:
+    #
+    #   Testing.paint(window).text   # => ["┌Caption─────┐", "│ alpha      │", …]
+    #
+    # @return [Array<String>] the plain text of every row, top to bottom.
+    def text = region_text(Rect.new(0, 0, @width, @height))
+
     # @param rect [Rect]
     # @return [Array<String>] each row within `rect` rendered to ANSI, top to
     #   bottom — byte-identical to what a component's per-row `set_text` over

data/lib/tuile/canvas/backend.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Canvas
+    # Where a {Canvas}'s cells land: three primitives taking a fully resolved
+    # style. Include it to *be* one — {Tuile::Buffer} does, and needs no adapter:
+    #
+    #   Canvas.new(screen.buffer)
+    #
+    # A backend is dumb by contract: no theme, no component, no background
+    # chain, no translation, and no default arguments — the canvas resolves all
+    # of that and hands down a whole style at a coordinate in the backend's own
+    # grid. What varies here is only *where* the cells go;
+    # how a write is transformed on the way there belongs to the {Canvas}, which
+    # is final. See `D_canvas`.
+    #
+    # **`include`, never `prepend`.** A class's own methods win over an included
+    # module's, which is what lets {Tuile::Buffer} carry this while defining all
+    # three itself; prepended, these bodies would sit *ahead* of the class and
+    # every write would raise.
+    #
+    # Out-of-range writes are **dropped, not raised** — the terminal-edge clip
+    # belongs here, which is what lets a component paint a row the terminal is
+    # too narrow for without checking first.
+    module Backend
+      # @param x [Integer] starting column, in this backend's own grid —
+      #   the canvas has already applied its {Canvas#origin}.
+      # @param y [Integer] row, likewise.
+      # @param styled [StyledString] the text of one row; newlines are not handled.
+      # @return [void]
+      def set_text(x, y, styled) = raise(NotImplementedError, "#{self.class}#set_text")
+
+      # @param x [Integer] column, in this backend's own grid.
+      # @param y [Integer] row, likewise.
+      # @param grapheme [String] one grapheme cluster.
+      # @param style [StyledString::Style] fully resolved.
+      # @return [void]
+      def set_char(x, y, grapheme, style) = raise(NotImplementedError, "#{self.class}#set_char")
+
+      # @param rect [Rect] in this backend's own grid.
+      # @param style [StyledString::Style] fully resolved; only its `bg` shows.
+      # @return [void]
+      def fill(rect, style) = raise(NotImplementedError, "#{self.class}#fill")
+    end
+  end
+end

data/lib/tuile/canvas.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Tuile
+  # The paint context a component draws through: a {Backend} that says where
+  # cells land, plus the state every write needs — the {#origin} that puts
+  # `(0, 0)` at the component's own top-left, and the background to fill in
+  # behind content that carries none.
+  #
+  # A component never builds one. It paints onto the canvas its
+  # {Component#repaint} was handed, already loaded with that component's
+  # {ComponentBackground#effective} and positioned at its {Component#rect}, and
+  # derives a second for the cells that are not its own ink:
+  #
+  #   def repaint(canvas)
+  #     canvas.set_text(0, 0, label)                              # my well
+  #     canvas.with(bg_color: bg.ambient) { _1.fill(tail) }       # not my ink
+  #   end
+  #
+  # Three methods, in **paint coordinates**: `(0, 0)` is the component's own
+  # top-left, not the screen's, and {Component#local_rect} is its whole rect
+  # over here. Passing {Component#rect} instead lands the write at twice the
+  # offset, silently. Everything outside painting stays screen-space — `rect`,
+  # {Mouse::Event}, {Component#cursor_position} — which `D_canvas` argues.
+  #
+  # A `nil` {#bg_color} is the terminal default, never "inherit" — inheritance
+  # is resolved before a canvas is built ({Screen#canvas_for}).
+  #
+  # == Implementation details
+  #
+  # Frozen, and final by convention: {#with} yields a *derived* canvas and never
+  # mutates, so there are no save/restore pairs and no state to leave dangling
+  # for whatever paints next. Subclassing is not the extension point — {Backend}
+  # is, and it is the half that varies. See `D_canvas`.
+  #
+  # UI-thread-confined.
+  class Canvas
+    # @return [Backend] where the cells land.
+    attr_reader :backend
+
+    # @return [Color, nil] the background painted behind content that states
+    #   none; `nil` leaves the terminal default showing.
+    attr_reader :bg_color
+
+    # Where this canvas's `(0, 0)` sits in {#backend} coordinates — the
+    # component's {Component#rect}`.top_left`, as {Screen#canvas_for} built it.
+    # A component never reads it: adding the offset back by hand is the one
+    # thing it exists to make unnecessary.
+    # @return [Point]
+    attr_reader :origin
+
+    # The region of the {#backend}'s grid this canvas may write to —
+    # {Screen#clip_for}'s answer moved into backend coordinates, or `nil` for a
+    # canvas nobody bounded, which costs one test per write and nothing else.
+    # Every canvas {Screen#canvas_for} builds carries one; {Screen#canvas}, the
+    # root, is the `nil` case.
+    #
+    # In **backend** coordinates, like {#origin} and unlike every argument the
+    # three paint methods take: a canvas's *state* says where it sits in the
+    # world, its arguments are in paint coordinates (`D_clip`).
+    #
+    # An {Rect#empty? empty} clip is not `nil`: it means *paint nothing*, and it
+    # is what a component that can show nothing gets — collapsed, or scrolled
+    # clean out of its viewport. Every write is judged against the clip on its
+    # own terms, so this needs no special case; it is simply the case where they
+    # all fail.
+    #
+    # The one cell it does not protect: {Buffer#put_char} blanks the head of a
+    # wide glyph whose continuation half a clipped write overwrites, one column
+    # outside. That is the terminal's physical truth, and better than the
+    # dangling half-glyph the alternative leaves.
+    # @return [Rect, nil]
+    attr_reader :clip
+
+    # @param backend [Backend]
+    # @param bg_color [Color, nil] already resolved — a canvas consults no
+    #   component and no theme.
+    # @param origin [Point] the {#origin}; the default paints in backend
+    #   coordinates, which is what {Screen#canvas} is.
+    # @param clip [Rect, nil] the {#clip}, in backend coordinates —
+    #   {Screen#canvas_for} converts.
+    # @raise [Error] if `backend` does not include {Backend}, which is worth
+    #   catching here rather than mid-paint.
+    def initialize(backend, bg_color: nil, origin: Point::ZERO, clip: nil)
+      raise Error, "#{backend.class} must include Tuile::Canvas::Backend" unless backend.is_a?(Backend)
+
+      @backend = backend
+      @bg_color = bg_color
+      @origin = origin
+      @clip = clip
+      @blank_style = bg_color ? StyledString::Style.new(bg: bg_color) : StyledString::Style::DEFAULT
+      freeze
+    end
+
+    # Yields a canvas onto the same backend with a different background, for the
+    # span of the block — the *only* way to change it.
+    #
+    #   canvas.with(bg_color: bg.ambient) do |c|
+    #     c.fill(right)
+    #     c.fill(below)
+    #   end
+    #
+    # The receiver is untouched, so nothing has to be restored afterwards and
+    # the block cannot leave the wrong background on for whatever paints next.
+    # The {#origin} and the {#clip} ride along, so a derived canvas paints in
+    # the same coordinates and is bounded the same way.
+    # @param bg_color [Color, nil] the background inside the block.
+    # @return [Object] the block's value.
+    # @raise [Error] if no block is given — a derived canvas nobody scoped is
+    #   the dangling state this shape exists to make impossible.
+    def with(bg_color:)
+      raise Error, "Canvas#with needs a block: with(bg_color:) { |canvas| … }" unless block_given?
+      return yield self if bg_color == @bg_color
+
+      yield Canvas.new(@backend, bg_color:, origin: @origin, clip: @clip)
+    end
+
+    # Writes a {StyledString}, filling {#bg_color} behind any span that states
+    # no background of its own — so an inherited tint, or an invalid field's
+    # error well, shows through content the component did not colour.
+    # @param x [Integer] starting column, relative to {#origin}.
+    # @param y [Integer] row, relative to {#origin}.
+    # @param styled [StyledString] the text of one row; newlines are not handled.
+    # @return [void]
+    def set_text(x, y, styled)
+      col = x + @origin.x
+      row = y + @origin.y
+      return @backend.set_text(col, row, styled.under_bg(@bg_color)) if @clip.nil?
+      return unless clipped_row?(row)
+
+      write_clipped_text(col, row, styled)
+    end
+
+    # {#set_text}'s single-grapheme counterpart.
+    # @param x [Integer] column, relative to {#origin}.
+    # @param y [Integer] row, relative to {#origin}.
+    # @param grapheme [String] one grapheme cluster.
+    # @param style [StyledString::Style] its `bg`, when set, wins over {#bg_color}.
+    # @return [void]
+    def set_char(x, y, grapheme, style = StyledString::Style::DEFAULT)
+      style = style.merge(bg: @bg_color) if @bg_color && style.bg.nil?
+      col = x + @origin.x
+      row = y + @origin.y
+      return @backend.set_char(col, row, grapheme, style) if @clip.nil?
+      return unless clipped_row?(row)
+
+      # A zero-width cluster still lands in one cell, and that cell is what the
+      # clip judges.
+      width = [Buffer.display_width(grapheme), 1].max
+      from = [col, @clip.left].max
+      to = [col + width, @clip.left + @clip.width].min
+      return if to <= from
+
+      # Half of a wide glyph is unrenderable, so the columns the clip keeps are
+      # blanked instead — {Buffer#put_char}'s own policy at the terminal's edge.
+      return @backend.fill(Rect.new(from, row, to - from, 1), @blank_style) if to - from < width
+
+      @backend.set_char(col, row, grapheme, style)
+    end
+
+    # Blanks `area` to {#bg_color}.
+    #
+    # Only for cells nothing is about to paint over: {Buffer::Cell#set} dirties
+    # on a real change, so blanking a cell that is then redrawn re-emits it.
+    # @param area [Rect] relative to {#origin} — {Component#local_rect} for the
+    #   whole of a component, never its {Component#rect}.
+    # @return [void]
+    def fill(area)
+      # The early-out {#set_text} gets from `clipped_row?`: an empty clip keeps
+      # no cell at all, so neither rectangle below is worth building.
+      return if @clip && @clip.empty?
+
+      area = area.moved_by(@origin)
+      @backend.fill(@clip.nil? ? area : area.intersect(@clip), @blank_style)
+    end
+
+    private
+
+    # @param row [Integer] a row in backend coordinates.
+    # @return [Boolean] whether {#clip} keeps it. Callers have already checked
+    #   that there *is* a clip.
+    def clipped_row?(row) = row >= @clip.top && row < @clip.top + @clip.height
+
+    # {#set_text} for the case that has to think: cut `styled` to the clip's
+    # columns and write what survived where it really belongs.
+    #
+    # {StyledString#slice} **drops** a cluster the boundary falls inside rather
+    # than splitting one, at the start as readily as at the end — so the kept
+    # text can begin a column later than the cut asked for, and the write
+    # position is derived from it rather than assumed. The column a dropped
+    # cluster half-covered is blanked (`D_clip`).
+    # @param col [Integer] starting column, in backend coordinates.
+    # @param row [Integer] row, likewise; the caller has checked the clip keeps it.
+    # @param styled [StyledString] the text of one row, uncoloured as handed in.
+    # @return [void]
+    def write_clipped_text(col, row, styled)
+      right = @clip.left + @clip.width
+      width = styled.display_width
+      from = [col, @clip.left].max
+      to = [col + width, right].min
+      return if to <= from
+
+      kept = col < @clip.left ? styled.slice(@clip.left - col, width) : styled
+      start = col + width - kept.display_width
+      kept = kept.slice(0, right - start) if start + kept.display_width > right
+      stop = start + kept.display_width
+
+      @backend.fill(Rect.new(from, row, start - from, 1), @blank_style) if start > from
+      @backend.fill(Rect.new(stop, row, to - stop, 1), @blank_style) if to > stop
+      @backend.set_text(start, row, kept.under_bg(@bg_color)) unless kept.empty?
+    end
+  end
+end

data/lib/tuile/color.rb

@@ -122,6 +122,27 @@ module Tuile
     # @return [Symbol, Integer, Array<Integer>]
     attr_reader :value
 
+    # This color's red, green and blue, for an app doing color math — a
+    # contrast check, a tint derived from {Screen#background_color}:
+    #
+    #   Color.hex("#ff6400").rgb   # => [255, 100, 0]
+    #   Color::DEEP_SKY_BLUE1.rgb  # => [0, 175, 255], palette cell 39
+    #   Color::MAGENTA.rgb         # => nil, the terminal's scheme decides
+    #   Color.palette(5).rgb       # => nil, likewise
+    #
+    # `nil` for the 16 named colors, in either spelling, because the scheme
+    # remaps them and any answer would be a guess. Indices 16..255 answer
+    # xterm's cube and grey ramp: a terminal *may* redefine those too (OSC 4),
+    # but in practice none does.
+    #
+    # @return [Array<Integer>, nil] frozen, each channel 0..255.
+    def rgb
+      case @value
+      when Array then @value
+      when Integer then PALETTE_RGB[@value]
+      end
+    end
+
     # SGR parameter codes for emitting this color as either a foreground
     # (`target: :fg`) or background (`target: :bg`). Returned as an array so
     # callers can splice them into a multi-attribute SGR (e.g. bold + color).
@@ -214,17 +235,12 @@ module Tuile
 
     private
 
-    # This color's RGB — the palette cell's own coordinates when the value is
-    # an index. Only ever asked of a non-Symbol value; a named color has no
-    # RGB of its own, since the terminal's scheme decides what it looks like.
+    # {#rgb}, except an index 0..15 answers xterm's default for it — the guess
+    # `:ansi16` quantization needs something to match against, and {#rgb}
+    # must not hand out. Only ever asked of a non-Symbol value.
     # @return [Array<Integer>] red, green and blue, each 0..255.
     def rgb_triple
-      return @value if @value.is_a?(Array)
-      return ANSI16_RGB[@value] if @value < 16
-      return [8 + (10 * (@value - 232))] * 3 if @value >= 232
-
-      cube = @value - 16
-      [CUBE_LEVELS[cube / 36], CUBE_LEVELS[(cube / 6) % 6], CUBE_LEVELS[cube % 6]]
+      rgb || ANSI16_RGB[@value]
     end
 
     # Written flat — destructured rather than splatted, `x * x` rather than
@@ -293,6 +309,19 @@ module Tuile
     CUBE_INDEX = Array.new(256) { |c| (0...6).min_by { |i| (CUBE_LEVELS[i] - c).abs } }.freeze
     private_constant :CUBE_INDEX
 
+    # Palette index 0..255 → its RGB, frozen, or nil for 0..15 — what {#rgb}
+    # answers for an index, precomputed so it allocates nothing.
+    # @return [Array<Array<Integer>, nil>]
+    PALETTE_RGB = Array.new(256) do |index|
+      if index < 16 then nil
+      elsif index >= 232 then ([8 + (10 * (index - 232))] * 3).freeze
+      else
+        cube = index - 16
+        [CUBE_LEVELS[cube / 36], CUBE_LEVELS[(cube / 6) % 6], CUBE_LEVELS[cube % 6]].freeze
+      end
+    end.freeze
+    private_constant :PALETTE_RGB
+
     # xterm's default RGB for each of the 16 named colors, in {COLOR_SYMBOLS}
     # order — what `:ansi16` quantization matches against. A terminal scheme
     # may redefine these; see {#quantize}.

data/lib/tuile/component/abstract_string_field.rb

@@ -9,9 +9,9 @@ module Tuile
     # drag this String-typed `text`/`value` seam onto its face alongside the
     # real typed one.
     #
-    # 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,
+    # Holds the shared state — a mutable {#text} buffer, a {#caret} index, the
+    # {#on_escape} slot — 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, CTRL+W
     # word-delete, and the `tab_stop?` flag (`focusable?` comes from
     # {HasValue}).
@@ -21,14 +21,14 @@ module Tuile
     # forward onto the enclosing cluster's end, and every edit steps by a whole
     # cluster:
     #
-    #   f.text  = "e\u{0301}x"   # a decomposed e-acute then "x": 3 chars, 2 glyphs
+    #   f.value = "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.text                   # => "x": the whole glyph went, not its accent
     #
     # Insertion stays character-native, so `String#insert` merges a typed
-    # combining mark into its base; {#text=}'s snap covers the case where that
+    # combining mark into its base; {#set_value}'s snap covers the case where that
     # re-segments the text around the caret.
     #
     # Subclasses implement the layout-specific pieces ({#cursor_position},
@@ -66,13 +66,15 @@ module Tuile
     # share one slot, and a filter written on a *key* callback let the same
     # characters in through a paste (`D_input_filters`, book ch7).
     #
-    # The mutation pipeline is a template method: {#text=} and {#caret=}
-    # detect no-ops, mutate state, fire {#on_change}, and invalidate.
+    # The mutation pipeline is a template method: {#set_value} and {#caret=}
+    # detect no-ops, mutate state, fire {HasValue#on_value_change}, and invalidate.
+    # Typing, a paste and the deleting keys write with `from_user: true`, every
+    # other write with `false` ({HasValue::ValueChangeEvent#from_user?}).
     # Subclasses inject their own behavior via four protected hooks:
     #
     # - {#insert_text} — **the one filter seam**: every insertion runs through
     #   it, typed or pasted, so what the buffer may hold is decided here.
-    # - {#preprocess_text} — filter for a whole assignment to {#text=},
+    # - {#preprocess_text} — filter for a whole assignment to {#set_value},
     #   which insertion does *not* pass through.
     # - {#preprocess_paste} — sanitizer for {#handle_paste}, run before the
     #   clipboard reaches {#insert_text} ({TextField} keeps its first line).
@@ -86,24 +88,41 @@ module Tuile
         super
         @text = +""
         @caret = 0
-        @on_change = nil
-        @on_value_change = nil
-        @on_escape = method(:default_on_escape)
+        @escape_clears_focus = true
+        # Unconditional on purpose: a field used as the face of a composed one
+        # ({ComboBox}, {IntegerField} …) is *told* to drop its well with
+        # {ComponentBackground::INHERIT} — a second well would make the
+        # composer's own bg_color inert over the very cells this field paints.
+        bg.default_color = ComponentBackground::INPUT_WELL
       end
 
       # @return [String] current text contents.
       attr_reader :text
 
-      # A text component's value *is* its text: {#value}/{#value=} are the
-      # {HasValue} seam over the same buffer as {#text}/{#text=}, so a form can
-      # drive it alongside typed fields. `text` stays the text-native name.
+      # A text component's value *is* its text: {#value} reads the same buffer
+      # as {#text}, and {#set_value} is its one writer.
       # @return [String]
       def value = text
 
+      # Replaces the text. Runs {#preprocess_text} first, then clamps the caret
+      # to the new text and snaps it onto a cluster boundary of it. Fires
+      # {HasValue#on_value_change} only on a real change — never on {#caret=}.
+      #
+      #   field.value = "admin"
+      #   field.caret = field.text.length   # the caret is clamped, never moved to the end
+      #
       # @param new_value [String, #to_s]
+      # @param from_user [Boolean] see {HasValue#set_value}.
       # @return [void]
-      def value=(new_value)
-        self.text = new_value.to_s
+      def set_value(new_value, from_user:)
+        new_value = preprocess_text(new_value)
+        return if @text == new_value
+
+        @text = +new_value
+        @caret = snap_to_cluster(@caret.clamp(0, @text.length))
+        handle_text_mutated
+        invalidate
+        on_value_change.fire(HasValue::ValueChangeEvent.new(source: self, value: @text, from_user:))
       end
 
       # `""` (not `nil`): a text field is empty when its buffer is blank.
@@ -114,39 +133,37 @@ module Tuile
       #   and always on a grapheme-cluster boundary (see the class doc).
       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
+      # What {#on_escape} fires.
+      #
+      # @!attribute [r] source
+      #   @return [AbstractStringField] the field ESC reached.
+      EscapeEvent = Data.define(:source) { include Tuile::Event }
+
+      # @!method on_escape
+      #   Fired with an {EscapeEvent} when ESC is pressed, after
+      #   {#escape_clears_focus} has had its say. Append to react as well as
+      #   blur; turn that flag off first to react *instead*:
+      #
+      #     field.escape_clears_focus = false
+      #     field.on_escape << method(:close_search)
+      #
+      #   **Empty means the field declines ESC** — but only while
+      #   {#escape_clears_focus} is off too, since a field that blurs has
+      #   handled the key. With both, ESC bubbles to the parent, and on to the
+      #   screen's ESC-to-quit.
+      #   @return [Listeners]
+      listener :on_escape
+
+      # Whether ESC clears focus (`true` by default), so text entry visibly
+      # cancels instead of quitting the app. It runs before {#on_escape} fires,
+      # and it — not a listener an app must remove by identity — is the whole
+      # representation of the default, so turning it off is the one way to give
+      # ESC another meaning. See `D_escape_opt_out`.
+      # @return [Boolean]
+      attr_accessor :escape_clears_focus
 
       def tab_stop? = true
 
-      # Sets the text. Runs {#preprocess_text} first (subclasses may filter or
-      # truncate). Caret is clamped to the new text length, then snapped back
-      # onto a cluster boundary of the *new* text. 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 = snap_to_cluster(@caret.clamp(0, @text.length))
-        handle_text_mutated
-        invalidate
-        @on_change&.call(@text)
-        on_value_change&.call(@text)
-      end
-
       # 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 {#handle_caret_mutated} hook for subclasses (e.g.
@@ -169,8 +186,9 @@ module Tuile
       # @return [Boolean]
       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.
+      # Inserts pasted text at the caret as **one** mutation, so
+      # {HasValue#on_value_change} fires once for the whole paste rather than
+      # once per character.
       # {#preprocess_paste} filters it first.
       # @param text [String]
       # @return [void]
@@ -210,8 +228,10 @@ module Tuile
       # (a date — `"2020-13-45"` is well-formed at every character) reports bad
       # input rather than filtering it (`D_input_filters`, book ch7).
       #
-      # {#text=} does *not* pass through here: only user input is filtered, so a
-      # programmatic {HasValue#value=} may still write what no key types.
+      # {#set_value} does *not* pass through here: only user input is filtered,
+      # so a programmatic write may still hold what no key types. The same line
+      # decides the origin: an insertion is the user's, so it writes with
+      # `from_user: true`.
       # @param str [String]
       # @return [Boolean] true if the text changed.
       def insert_text(str)
@@ -219,25 +239,11 @@ module Tuile
 
         new_text = @text.dup.insert(@caret, str)
         @caret += str.length
-        self.text = new_text
+        set_value(new_text, from_user: true)
         true
       end
 
-      # The field's background well, looked up from the current {Screen#theme}
-      # at paint time: {Theme#active_bg_color} while this input is on the active
-      # (focus) chain, {Theme#input_bg_color} otherwise — visibly a field either
-      # way, distinctly highlighted when focused. An app overrides the pair by
-      # setting {Component#bg_color}, which wins over this.
-      #
-      # Unconditional on purpose. A field used as the face of a composed one
-      # ({Component::ComboBox}, {Component::IntegerField} …) is *told* to drop
-      # its well — that widget assigns {Component::BG_INHERIT} at construction,
-      # since it owns the surface and a second well would make its own
-      # {Component#bg_color} inert over the very cells this field paints.
-      # @return [Color]
-      def default_bg_color = active? ? screen.theme.active_bg_color : screen.theme.input_bg_color
-
-      # Input filter for a whole assignment to {#text=}. Nothing overrides it
+      # Input filter for a whole assignment to {#set_value}. Nothing overrides it
       # today; a subclass that does is filtering the *programmatic* setter, not
       # user input — that is {#insert_text}.
       # @param new_text [String]
@@ -254,8 +260,8 @@ module Tuile
       def columns_of(str) = str.each_grapheme_cluster.sum { |g| Buffer.display_width(g) }
 
       # 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.
+      # {HasValue#on_value_change}. Default no-op. Subclasses use this to
+      # invalidate caches ({TextArea}'s wrap cache) and update derived state.
       # @return [void]
       def handle_text_mutated; end
 
@@ -283,9 +289,10 @@ module Tuile
         when Keys::CTRL_RIGHT_ARROW then self.caret = word_right
         when Keys::CTRL_W then delete_back_to(word_left)
         when Keys::ESC
-          return false if @on_escape.nil?
+          return false if !@escape_clears_focus && on_escape.empty?
 
-          @on_escape.call
+          screen.focused = nil if @escape_clears_focus
+          on_escape.fire(EscapeEvent.new(source: self))
         else
           return false
         end
@@ -299,7 +306,8 @@ module Tuile
       def delete_before_caret = delete_back_to(cluster_boundary_before(@caret))
 
       # Removes the text between `index` and the caret, leaving the caret at
-      # `index` — one mutation, so {#on_change} fires once.
+      # `index` — one mutation, so {HasValue#on_value_change} fires once, as the
+      # user's: every caller is a deleting key.
       #
       # `index` is snapped forward onto a grapheme-cluster boundary, so a
       # caller may compute it by counting characters.
@@ -312,7 +320,7 @@ module Tuile
         new_text = @text.dup
         new_text.slice!(start...@caret)
         @caret = start
-        self.text = new_text
+        set_value(new_text, from_user: true)
       end
 
       # Removes the whole grapheme cluster at the caret.
@@ -322,7 +330,7 @@ module Tuile
 
         new_text = @text.dup
         new_text.slice!(@caret...cluster_boundary_after(@caret))
-        self.text = new_text
+        set_value(new_text, from_user: true)
       end
 
       private
@@ -366,13 +374,6 @@ module Tuile
         offset
       end
 
-      # 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.