tuile 0.14.0 → 0.16.0

data/lib/tuile/component/float_field.rb

@@ -10,12 +10,14 @@ module Tuile
     #   field.value = 19.99                               # field shows "19.99"
     #   field.clear                                       # empties it; value => nil
     #
-    # Only `0`–`9`, one leading `-` and one `.` can be typed; any other
-    # printable key is dropped without moving the caret. Up/Down step by `1.0`
-    # (an empty field counting as `0.0`). A `Float` is a binary double, so this
-    # is the wrong field for money — hold that as `Integer` cents in an
-    # {IntegerField} — and range checks (`min`/`max`) belong to a forms layer,
-    # not here.
+    # The buffer only ever holds `0`–`9`, one leading `-`, one `.` and an
+    # optional exponent: a key that would break that is dropped without moving
+    # the caret, and so is a *paste* that would (a European `"1,5"` lands
+    # nothing, rather than sieving through as the plausible, wrong `"15"`).
+    # Up/Down step by `1.0` (an empty field counting as `0.0`). A `Float` is a
+    # binary double, so this is the wrong field for money — hold that as
+    # `Integer` cents in an {IntegerField} — and range checks (`min`/`max`)
+    # belong to a forms layer, not here.
     #
     # == Implementation details
     # {#value} is a *derived parse*: the buffer is the single source of truth,
@@ -26,16 +28,21 @@ module Tuile
     # {#on_value_change} — which fires per keystroke, but only on a real *value*
     # change (`"7"`→`"07"` is silent). The parse also accepts the exponent
     # `Float#to_s` writes for extreme magnitudes, so `value = 1e-5` round-trips
-    # through the `"1.0e-05"` it displays, though no key types an `e`.
+    # through the `"1.0e-05"` it displays — and `e` is typeable, so what the
+    # field displays is always something the user can go on editing.
     #
-    # It *composes* a {TextField} (its single {HasContent} child) rather than
-    # subclassing one, so its face carries only the typed {HasValue} seam, never
-    # the widget's `String`-typed `text`.
+    # It *wraps* a {TextField} rather than subclassing one, so its face carries
+    # only the typed {HasValue} seam and never the widget's `String`-typed
+    # `text`; {AbstractWrappingField} supplies the wrapping.
     #
     # UI-thread-confined, like every component (see {Screen}).
-    class FloatField < Component
-      include HasContent
-      include HasValue
+    class FloatField < AbstractWrappingField
+      include HasBadInput
+
+      # @return [String] what {#bad_input_message} reports for a buffer that is
+      #   typeable but not a number.
+      BAD_INPUT_MESSAGE = "not a number"
+      private_constant :BAD_INPUT_MESSAGE
 
       # A buffer {#value} parses: an optional sign, digits with an optional
       # fractional part (either side may be empty, but not both), and the
@@ -44,19 +51,42 @@ module Tuile
       NUMERIC = /\A-?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][-+]?\d+)?\z/
       private_constant :NUMERIC
 
+      # The face: a {TextField} that admits only the buffers a float can be
+      # typed through, however the characters arrive.
+      class Field < TextField
+        # Buffers reachable by typing a float: an optional leading `-`, digits
+        # with at most one `.`, and an optional exponent. Looser than
+        # {NUMERIC} on purpose — `""`, `"-"`, `"1."` and `"1e"` are members, or
+        # the values past them could not be typed at all.
+        # @return [Regexp]
+        TYPEABLE = /\A-?\d*(?:\.\d*)?(?:[eE][-+]?\d*)?\z/
+        private_constant :TYPEABLE
+
+        protected
+
+        # Accepts the insertion only if the whole resulting buffer is still
+        # typeable, so a European `"1,5"` is dropped rather than sieved into the
+        # plausible, wrong `"15"`.
+        # @param str [String]
+        # @return [Boolean] true if the text changed.
+        def insert_text(str)
+          return false unless TYPEABLE.match?(@text.dup.insert(@caret, str))
+
+          super
+        end
+      end
+
       def initialize
-        super()
-        @last_value = nil
-        field = TextField.new
-        field.on_change = ->(_text) { fire_if_changed }
-        field.on_key = method(:field_key)
-        self.content = field
+        super(Field.new)
+        # Not the general on_key interceptor: that slot stays free for the app.
+        editor.on_key_up = -> { step(1.0) }
+        editor.on_key_down = -> { step(-1.0) }
       end
 
       # @return [Float, nil] the parsed buffer; `nil` when empty or not a
       #   number (e.g. a lone `"-"`).
       def value
-        text = content.text
+        text = editor.text
         text.match?(NUMERIC) ? text.to_f : nil
       end
 
@@ -68,34 +98,19 @@ module Tuile
       # @raise [TypeError] on a value `Float()` won't take at all (an `Array`).
       # @return [void]
       def value=(new_value)
-        content.text = new_value.nil? ? "" : coerce(new_value).to_s
-        content.caret = content.text.length
+        editor.text = new_value.nil? ? "" : coerce(new_value).to_s
+        editor.caret = editor.text.length
       end
 
       # `nil`, not `""`: a numeric field with no parseable number is empty.
       # @return [nil]
       def empty_value = nil
 
-      # @return [Point, nil] the field's caret (the hardware cursor is delegated
-      #   to the inner field).
-      def cursor_position = content.cursor_position
-
-      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
-      # @return [Proc, Method, nil] no-arg callable, or nil.
-      def on_enter = content.on_enter
-
-      # @param callback [Proc, Method, nil]
-      # @return [void]
-      def on_enter=(callback)
-        content.on_enter = callback
-      end
-
-      protected
-
-      # Places the wrapped field across the whole rect ({HasContent} hook).
-      # @param field [Component]
-      # @return [void]
-      def layout(field) = (field.rect = rect)
+      # `"-"`, `"."`, `"-."` and every exponent in progress (`"1e"`, `"1.0e-"`,
+      # …) are typeable and parse to nothing; an *empty* buffer is empty, not
+      # bad ({HasBadInput}).
+      # @return [String, nil]
+      def bad_input_message = value.nil? && !editor.text.empty? ? BAD_INPUT_MESSAGE : nil
 
       private
 
@@ -111,51 +126,11 @@ module Tuile
         float
       end
 
-      # The field's key interceptor, consulted *before* the field acts on the
-      # key — which is what lets a rejected character be swallowed without the
-      # caret ever moving.
-      # @param key [String]
-      # @return [Boolean] true to consume the key.
-      def field_key(key)
-        case key
-        when Keys::UP_ARROW then step(1.0)
-        when Keys::DOWN_ARROW then step(-1.0)
-        else return Keys.printable?(key) && !accepts?(key)
-        end
-        true
-      end
-
       # Nudges {#value} by `delta`, treating an empty/un-parseable field as
       # `0.0`.
       # @param delta [Float]
       # @return [void]
       def step(delta) = (self.value = (value || 0.0) + delta)
-
-      # Whether `char` may be inserted. Deliberately shallow: it keeps the
-      # buffer *typeable* rather than always-valid — a transient `"-"` or
-      # `"1."` has to be reachable — and {#value} decides what parses.
-      # @param char [String] a single printable character.
-      # @return [Boolean]
-      def accepts?(char)
-        case char
-        when /\A[0-9]\z/ then true
-        when "-" then content.caret.zero? && !content.text.start_with?("-")
-        when "." then !content.text.include?(".")
-        else false
-        end
-      end
-
-      # Re-emits {#on_value_change} with the freshly-parsed {#value}, but only
-      # when it differs from the last one fired — so a buffer edit that leaves
-      # the value unchanged (`"7"`→`"07"`) stays silent.
-      # @return [void]
-      def fire_if_changed
-        v = value
-        return if v == @last_value
-
-        @last_value = v
-        on_value_change&.call(v)
-      end
     end
   end
 end

data/lib/tuile/component/has_bad_input.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # The one fact a parsing field knows that {HasValue#on_value_change} cannot
+    # carry: the input is something the field's value cannot represent.
+    #
+    #   field = Component::IntegerField.new
+    #   # …the user types a lone minus, which no Integer can represent:
+    #   field.value                 # => nil, exactly as for an untouched field
+    #   field.empty?                # => true, likewise — empty of *value*
+    #   field.bad_input?            # => true
+    #   field.bad_input_message     # => "not a whole number"
+    #
+    # So a form asks this *before* `empty?`, on every field that can answer:
+    #
+    #   bad = fields.select { _1.respond_to?(:bad_input?) && _1.bad_input? }
+    #   Component::ConfirmWindow.alert("Cannot save", bad.map(&:bad_input_message).join("\n")) if bad.any?
+    #
+    # Include it in a field whose parse is *partial* — whose input can be
+    # something its value cannot represent, as a date field's can. Not in a
+    # {ComboBox}, the near miss: its input is a *filter* rather than a
+    # formatting of the value, so a no-match is not a failed conversion and it
+    # reverts the query instead.
+    #
+    # == Implementation details
+    # An includer overrides {#bad_input_message} and nothing else. Two rules
+    # bind that override, and `design/decisions.md` `D_bad_input` has the why:
+    #
+    # - **Empty input is not bad input.** Return `nil` for an empty buffer even
+    #   though it parses to nothing, or every blank *optional* field blocks a
+    #   save.
+    # - **One frozen constant per field kind, no interpolation** — `"not a
+    #   valid date"`, never `"'xyz' is not a valid date"`. It is read per call,
+    #   and a future error ink would read it per paint.
+    #
+    # Ask at the moment you need the answer and you always get the current one:
+    # it is derived on read, never stored. Which fields *can* answer is a class
+    # fact worth caching; what they answer is not. There is deliberately no
+    # change notice, because the fact is *continuous* — every prefix of a valid
+    # date is bad input — so anything reacting per keystroke flashes through the
+    # act of typing correctly, while a save gate consulted at a click sees one
+    # settled state. The **ink** is the one consumer that cannot be asked at a
+    # click, so it has {#bad_input_settled?}: a field whose whole grammar is
+    # prefix-bad latches the well on its commit gesture instead of painting it
+    # per keystroke.
+    module HasBadInput
+      # Pinned rather than relied on: {#error_ink?} calls `super`, so
+      # {HasValidation} must be below this module in the ancestor chain whatever
+      # order an includer writes its `include` lines in.
+      include HasValidation
+
+      # Why the current input cannot be turned into a {HasValue#value} — the
+      # single override point.
+      # @return [String, nil] the reason, or `nil` when the input converts (a
+      #   field holding *no* input converts: it is empty, not bad).
+      # @raise [NotImplementedError] unless the includer overrides it.
+      def bad_input_message = raise(NotImplementedError, "#{self.class} must implement bad_input_message")
+
+      # @return [Boolean] true iff the field is holding input its value cannot
+      #   represent.
+      def bad_input? = !bad_input_message.nil?
+
+      protected
+
+      # Widens {HasValidation#error_ink?}: bad input paints the invalid well
+      # too, with no verdict written — once {#bad_input_settled?} says the
+      # report may be shown.
+      # @return [Boolean]
+      def error_ink? = (bad_input? && bad_input_settled?) || super
+
+      # Whether bad input may paint the well *yet*. `true` here, so the well is
+      # as continuous as the report: a {FloatField} reddens at the half-typed
+      # `"1."`, which is a fair warning while the residue is one or two
+      # transient buffers. Override it to *latch* where the grammar makes
+      # **every** prefix bad input, or the well is red for the whole time the
+      # user types a correct value:
+      #
+      #   def bad_input_settled? = @settled   # set on commit, cleared on an edit
+      #
+      # It gates the **ink only**: {#bad_input?} is a pull, and a save gate
+      # asking at a click must get the answer settled or not (`design/decisions.md`
+      # `D_bad_input`).
+      # @return [Boolean]
+      def bad_input_settled? = true
+    end
+  end
+end

data/lib/tuile/component/has_caption.rb

@@ -39,6 +39,14 @@ module Tuile
         @caption = new_caption
         invalidate
       end
+
+      protected
+
+      # Adds `caption="…"` to {Component#inspect}, omitted while empty.
+      # @return [Array<String>]
+      def inspect_details
+        caption.empty? ? super : super + ["caption=#{caption.to_s.inspect}"]
+      end
     end
   end
 end

data/lib/tuile/component/has_content.rb

@@ -2,9 +2,20 @@
 
 module Tuile
   class Component
-    # A component that owns exactly one child *directly*, under the name
-    # `content`. The includer initializes `@content` to nil and provides a
-    # protected `layout(content)` positioning the child; the mixin owns the swap:
+    # A component with a *primary* child named `content`: **this is my content,
+    # which you populate; my other children are mine to manage, not yours to
+    # address**. Include it wherever addressing that child is the point — a
+    # {Slot} is a bare region for one, a {Window} frames one, an {Overlay}
+    # floats one.
+    #
+    # It says nothing about *arity*: {Window} has two app-settable children, and
+    # this mixin names which of them is *the* content. Nor about permanence — an
+    # {Overlay}'s body is permanent and public both. A container with *several*
+    # populatable regions gives each one a {Slot} rather than including this
+    # twice.
+    #
+    # The includer initializes `@content` to nil and provides a protected
+    # `layout(content)` positioning the child; the mixin owns the swap:
     #
     #   class Slot < Component
     #     include Component::HasContent
@@ -16,14 +27,20 @@ module Tuile
     #     def layout(content) = content.rect = rect
     #   end
     #
-    # Include it when the child is **permanent and integral** — a typed field's
-    # inner {TextField}, an {Overlay}'s body. It does *not* mean "a component
-    # with one child": an includer may hold others alongside, as {Window} does
-    # with its footer. For a region an app swaps, hold a {Slot} instead.
+    # **A child that is private machinery stays out**, because {#content=} ships
+    # public and re-checks nothing its owner depends on — swapping in a
+    # component of the wrong type succeeds, and breaks the owner at the next
+    # call. Such a component owns its child outright instead, with `add_child`
+    # in the constructor and placement from `rect=`. Both in-tree shapes are
+    # worth knowing: {AbstractWrappingField} hides its editor completely, while
+    # {CheckboxGroup} and {RadioGroup} expose theirs **read-only** as `list` —
+    # an app tunes that {List}, but never supplies it. *Populate* is the word
+    # doing the work here: addressable is not the same as yours.
     #
     # A tree walk finds content generically through `is_a?(HasContent)` plus a
     # `content` compare, which is why this is a mixin rather than a per-class
-    # accessor — the same reason {HasCaption} is one.
+    # accessor — the same reason {HasCaption} is one. Under the rule above such
+    # a walk reaches only *public* contents, never a widget's private editor.
     module HasContent
       # @return [Component, nil] the current content component.
       attr_reader :content
@@ -45,7 +62,7 @@ module Tuile
 
         old = self.content
         # Detached without notifying, and notified at the very end: the focus
-        # repair in on_child_removed cascades into whatever occupies the slot
+        # repair in handle_child_removed cascades into whatever occupies the slot
         # *now*, so it has to see the new content (window_spec pins it).
         detach_child(old) unless old.nil?
         @content = content
@@ -54,7 +71,7 @@ module Tuile
           content.invalidate
           layout(content)
         end
-        on_child_removed(old) unless old.nil?
+        handle_child_removed(old) unless old.nil?
       end
 
       # @param rect [Rect]
@@ -65,11 +82,13 @@ module Tuile
       end
 
       # @return [void]
-      def on_focus
+      def handle_focus
         super
         # Let the content component receive focus, so that it can immediately
-        # start responding to key presses.
-        screen.focused = content if !content.nil? && content.focusable?
+        # start responding to key presses. Hidden content is left alone, so
+        # focus parks here — where a container with nothing to forward to
+        # leaves it anyway.
+        screen.focused = content if !content.nil? && content.visible? && content.focusable?
       end
     end
   end

data/lib/tuile/component/has_placeholder.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # The hint a field paints in its own cells while it holds nothing — a format
+    # the user could not otherwise guess:
+    #
+    #   field = Component::TextField.new
+    #   field.placeholder = "dd.mm.yyyy"
+    #   field.text.empty?                # => true — the hint is not content
+    #
+    # Paint-only in every direction: it never enters {HasValue#value}, never
+    # fires `on_value_change`, is never reached by a paste, and never counts
+    # against {TextField#max_text_length}. That asymmetry *is* the feature — a
+    # placeholder living in the buffer would be a default value, and a form
+    # saving it would write `"dd.mm.yyyy"` to the database.
+    #
+    # Shown whenever the field is empty, **focus included**: the format hint is
+    # wanted most precisely while the user is typing into the field.
+    #
+    # Include it in a field whose *input shape* is unguessable from an empty
+    # well. Not in {Select}, the near miss: a blank face plus `▾` already reads
+    # as "nothing picked", so an absent enum *value* needs no hint the way an
+    # unguessable input *format* does (`design/decisions.md` `D_select`).
+    #
+    # == Implementation details
+    # The ink is {Theme#placeholder_color}, calibrated to be *barely* visible —
+    # which is why the hint is a plain `String`: a color baked in by the app
+    # would go stale on the next theme flip and defeat that calibration.
+    #
+    # Being a mixin is what lets a tree walk find every hintable field via
+    # `is_a?(HasPlaceholder)`, whatever their classes. A field that *composes*
+    # another overrides both accessors to delegate; this module's storage is the
+    # leaf's alone.
+    module HasPlaceholder
+      # @return [String, nil] the hint, or `nil` when there is none (default).
+      def placeholder = @placeholder
+
+      # Sets the hint and invalidates the component. No-op when unchanged.
+      # @param text [String, nil] `nil` removes it.
+      # @return [void]
+      # @raise [TypeError] unless `text` is a String or nil — notably a
+      #   {StyledString} is refused rather than flattened, since the ink is the
+      #   theme's to choose.
+      def placeholder=(text)
+        raise TypeError, "expected String or nil, got #{text.inspect}" unless text.nil? || text.instance_of?(String)
+        return if @placeholder == text
+
+        @placeholder = text
+        invalidate
+      end
+
+      protected
+
+      # Adds `placeholder="…"` to {Component#inspect}, omitted while unset.
+      # @return [Array<String>]
+      def inspect_details
+        placeholder.nil? ? super : super + ["placeholder=#{placeholder.inspect}"]
+      end
+    end
+  end
+end

data/lib/tuile/component/has_validation.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A field's verdict slot: one message, written from *outside* the field, and
+    # shown by the field as a red *well* — {Theme#error_bg_color}, or
+    # {Theme#error_active_bg_color} while focused.
+    #
+    #   login = Component::Button.new(caption: "Log in")
+    #   login.on_click = lambda do
+    #     username.error_message = username.empty? ? "Required" : nil
+    #     password.error_message = password.empty? ? "Required" : nil
+    #     next if [username, password].any?(&:error_message)
+    #
+    #     authenticate(username.value, password.value)
+    #   end
+    #
+    # The field turns red on its own; the *message* needs cells the field
+    # doesn't own, so whoever has them — a `FormLayout`, or an app's own
+    # {Label} — subscribes to {#on_error_message_change} and paints the text in
+    # {Theme#error_color}.
+    #
+    # Included by {HasValue}, so every field has it. Include it directly in a
+    # component that can be invalid without being a field (a form section
+    # wrapping several).
+    #
+    # == Implementation details
+    # **A well, not ink on the glyphs.** A field's background is what shows its
+    # boundary in the first place, so an invalid field gets a red one and loses
+    # nothing — where red *text* is invisible on the empty field that is the
+    # required-field case, and invisible again on content carrying colors of its
+    # own. It takes two tokens rather than one because a focused invalid field
+    # still has to look focused (`design/decisions.md` `D_has_validation`).
+    #
+    # The well reaches the whole widget with nothing forwarding it: a composed
+    # field's inner face is marked {Component::BG_INHERIT} and a group's {List}
+    # declares no background, so both walk up the ordinary background chain and
+    # land on the composer's answer.
+    #
+    # **The field never writes this.** It computes no verdicts — it cannot see
+    # the sibling a rule compares against — so it has nothing to write, and that
+    # is what leaves exactly one writer: whoever validates. The discipline that
+    # writer owes is one sentence: **set *or clear* it on every validate pass**,
+    # as the example above does with its `: nil` branches. Vaadin's custom-field
+    # guide warns that sharing one `invalid` cell between internal and external
+    # validation ends with each overriding the other; Tuile's answer is that the
+    # field's *own* report is a different member ({HasBadInput#bad_input?} —
+    # derived on read, never stored), so the two never share a cell.
+    #
+    # There is deliberately **no `invalid?`**: a second predicate beside
+    # `bad_input?` gives a caller no way to know which to ask, and invalid *is*
+    # a non-nil message. Assign `""` for a verdict with nothing to say.
+    #
+    # Unlike `bad_input?`, this fact is *discrete* — asserted at a click or a
+    # binder pass, not recomputed per keystroke — which is why it carries a
+    # change notice where `bad_input?` deliberately doesn't (`design/decisions.md`
+    # `D_bad_input`, `D_has_validation`).
+    module HasValidation
+      # @return [Proc, Method, nil] one-arg callable fired with the new message
+      #   (or `nil`) whenever {#error_message} actually changes — never on a
+      #   no-op set. Claimed by the container that paints the message; an app
+      #   painting its own takes it instead.
+      attr_accessor :on_error_message_change
+
+      # @return [StyledString, nil] why the field is invalid, or `nil` when it
+      #   is not; `nil` until something sets it.
+      def error_message = @error_message
+
+      # Sets the verdict and repaints the field in {Theme#error_color}; `nil`
+      # clears it. No-op (no repaint, no listener) when unchanged. A `String` is
+      # parsed via {StyledString.parse}, as {HasCaption#caption=} does.
+      #
+      # Safe on a detached field — an app validates a form it assembled but has
+      # not mounted, and {Component#invalidate} is already a no-op there.
+      # @param new_message [String, StyledString, nil]
+      # @return [void]
+      def error_message=(new_message)
+        new_message = StyledString.parse(new_message) unless new_message.nil?
+        return if error_message == new_message
+
+        @error_message = new_message
+        invalidate
+        on_error_message_change&.call(new_message)
+      end
+
+      protected
+
+      # The invalid well, picked up by everything this component paints —
+      # including the inner face of a composed field and the {List} of a group,
+      # neither of which forwards anything: both declare no background of their
+      # own, so the ordinary chain walks up to this (overrides
+      # {Component#error_bg_color}).
+      # @return [Color, nil]
+      def error_bg_color
+        return nil unless error_ink?
+
+        active? ? screen.theme.error_active_bg_color : screen.theme.error_bg_color
+      end
+
+      # Whether to paint the invalid well right now. Its own hook because
+      # {HasBadInput} widens it: a field holding input its value cannot
+      # represent is invalid on the face too, even with no verdict written.
+      # @return [Boolean]
+      def error_ink? = !error_message.nil?
+
+      # Adds `error_message=…` to {Component#inspect}, omitted while valid — so
+      # a {Testing.get} failure dump says which field is already flagged.
+      # @return [Array<String>]
+      def inspect_details
+        m = error_message
+        m.nil? ? super : super + ["error_message=#{m.to_s.inspect}"]
+      end
+    end
+  end
+end

data/lib/tuile/component/has_value.rb

@@ -18,11 +18,16 @@ module Tuile
     # ({AbstractStringField} backs them with its text buffer). Override {#empty_value}
     # when the empty sentinel isn't `nil` (a text field's is `""`).
     #
+    # {HasValidation} comes with it, so every field carries the
+    # `error_message` a validator writes and paints its own error ink.
+    #
     # == Implementation details
     # Deliberately smaller than Vaadin's `HasValue`: read-only,
     # required-indicator, the from-client/old-value event payload, and
     # converters all belong to the not-yet-built form layer, not here.
     module HasValue
+      include HasValidation
+
       # @return [Proc, Method, nil] one-arg callable fired with the new value
       #   whenever {#value} actually changes — never on a no-op set.
       attr_accessor :on_value_change
@@ -41,10 +46,18 @@ module Tuile
         on_value_change&.call(new_value)
       end
 
+      # Empty of *value*: a field whose parse is partial reports `true` while the
+      # user is looking at glyphs it could not use, so ask
+      # {HasBadInput#bad_input?} first.
       # @return [Boolean] true iff {#value} equals {#empty_value}.
       def empty? = value == empty_value
 
       # Resets {#value} to {#empty_value}.
+      #
+      # An includer whose input can outrun its value ({HasBadInput}) must clear
+      # the *input*: a field holding bad input already reads `empty_value`, so
+      # inheriting this default — over a {#value=} that returns early on a no-op
+      # set — is a `clear` that leaves the garbage on screen.
       # @return [void]
       def clear = (self.value = empty_value)
 
@@ -55,10 +68,24 @@ module Tuile
       # Input fields are focusable by default (overrides {Component#focusable?});
       # a read-only display field could override back to `false`. Only
       # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
-      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # composing wrappers, so it stays per-class (`design/decisions.md`
       # `D_integer_field`).
       # @return [Boolean]
       def focusable? = true
+
+      protected
+
+      # Adds `value=…` to {Component#inspect}, omitted while the value is nil.
+      # @return [Array<String>]
+      def inspect_details
+        v = value
+        return super if v.nil?
+
+        # Truncate before #inspect, not after: a TextArea's value is its whole
+        # buffer.
+        v = "#{v[0, 40]}…" if v.is_a?(String) && v.length > 40
+        super + ["value=#{v.inspect}"]
+      end
     end
   end
 end