tuile 0.16.0 → 0.17.0

data/lib/tuile/component/form_item.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # One row of a form: a {#caption} above a field, and whatever the field has
+    # to say against itself below it.
+    #
+    #   item = Component::FormItem.new(username, caption: "Username", required: true)
+    #   username.error_message = "Must not be blank"
+    #
+    #   Username ∙            ← the caption, with the required marker
+    #   [________________]    ← the content, whatever you wrapped
+    #   Must not be blank     ← the message, here the verdict just written
+    #
+    # Wrap a field and drop the item wherever a component goes — a
+    # {Layout::Vertical} stacking items is already a form:
+    #
+    #   column.add(Component::FormItem.new(notes, caption: "Notes"), Fixed[7])
+    #
+    # The chrome is the item's, the face is the field's: a {Checkbox} or a
+    # {Button} paints its own text and takes no caption here, so the item is
+    # built without one and simply reserves no caption row.
+    #
+    # **Hide the item, never the field** — `item.visible = false` takes the
+    # caption and the message with it, while `field.visible = false` blanks the
+    # field's rows and leaves its caption stranded above them.
+    #
+    # == Implementation details
+    # **The message row is also the gap row**, which is why the item's pitch is
+    # a flat three rows and nothing ever reflows: a form that grew a row when a
+    # field went invalid would push the fields below it down *while the user is
+    # typing into one of them*. See `D_form_item`.
+    #
+    # **It measures nothing.** The rect it is handed is divided top-down —
+    # caption, content, message — so there is no `rows` property here and no
+    # question asked of the field. Rows are served content-first when there are
+    # too few: the content never drops below one row, then the caption takes the
+    # next row it can, then the message.
+    #
+    # **The message comes from two channels and the item orders neither.** A
+    # validator's verdict ({HasValidation#error_message}) and the field's own
+    # report of input its value cannot represent ({HasBadInput#bad_input?}) both
+    # land in this row; the item registers on both notices and paints
+    # {HasValidation#shown_message}, which is where the precedence lives — bad
+    # input wins, and a latched field says nothing until it settles
+    # (`D_bad_input`). So the row can fill while `error_message` is still `nil`.
+    #
+    # **The message is claimed ink.** It is painted in {Theme#error_color}
+    # whatever colors the {StyledString} carried, so the row always reads as an
+    # error — the matching half of the red well the field paints for itself
+    # (`D_has_validation`).
+    #
+    # Both that message and the required marker are {StyledString}s this item
+    # authors, so they bake their colors and are rebuilt from
+    # {Component#handle_theme_changed} — and from {Component#handle_attached},
+    # for a tree assembled before there was a {Screen} to read a theme from.
+    class FormItem < Component
+      include Component::HasContent
+      include Component::HasCaption
+
+      class << self
+        # The glyph marking a {#required?} item, `∙` (U+2219 BULLET OPERATOR)
+        # by default:
+        #
+        #   Tuile::Component::FormItem.required_marker = "*"
+        #
+        # An app-global, like {VerticalScrollBar.handle_char} — the marker is a
+        # house style, not a per-item decision.
+        #
+        # The default is deliberately not one of `•`, `●` or `·`: those are
+        # East-Asian *Ambiguous* and would measure two columns under the other
+        # policy, enlarging the inventory that keeps `D_ambiguous_width`'s bet
+        # cheap to reverse. `∙` and `◦` measure one under both.
+        # @return [String]
+        attr_reader :required_marker
+
+        # @param glyph [String] one grapheme cluster, one column wide.
+        # @return [String] frozen.
+        # @raise [TypeError] when `glyph` is not a String.
+        # @raise [ArgumentError] when it is not exactly one cluster one column wide.
+        def required_marker=(glyph)
+          @required_marker = StyledString.validate_glyph(glyph, :required_marker)
+        end
+      end
+
+      self.required_marker = "∙"
+
+      # @param content [Component, nil] the field to wrap; assignable later
+      #   through {#content=}.
+      # @param caption [String, StyledString, nil] the text above it; omit it
+      #   for a widget painting its own, such as a {Checkbox} or a {Button}.
+      # @param required [Boolean] whether to paint {.required_marker} beside
+      #   the caption.
+      # @raise [ArgumentError] when `required` is true and there is no caption
+      #   for the marker to sit beside.
+      def initialize(content = nil, caption: nil, required: false)
+        super()
+        @content = nil
+        @required = false
+        @caption_label = Label.new
+        @message_label = Label.new
+        add_child(@caption_label) # appended: HasContent forces the content to index 0
+        add_child(@message_label)
+        self.caption = caption
+        self.required = required
+        self.content = content unless content.nil?
+      end
+
+      # @return [Boolean] whether the caption carries {.required_marker}.
+      def required? = @required
+
+      # Paints {.required_marker} beside the caption. The field never learns it
+      # is required — nothing here validates, and this is not a rule.
+      # @param flag [Boolean]
+      # @return [void]
+      # @raise [ArgumentError] when true and {#caption} is empty — the marker
+      #   rides the caption, so without one it has nowhere to go.
+      def required=(flag)
+        flag = flag ? true : false
+        return if @required == flag
+        raise ArgumentError, "a required FormItem needs a caption for the marker" if flag && caption.empty?
+
+        @required = flag
+        refresh_chrome
+      end
+
+      # Sets the caption, adding or dropping the caption row as it becomes
+      # non-empty or empty.
+      # @param new_caption [String, StyledString, nil]
+      # @return [void]
+      # @raise [ArgumentError] when clearing the caption of a {#required?} item.
+      def caption=(new_caption)
+        new_caption = StyledString.parse(new_caption)
+        if required? && new_caption.empty?
+          raise ArgumentError, "a required FormItem keeps its caption: the marker has nowhere else to go"
+        end
+
+        had_row = !caption.empty?
+        super
+        refresh_chrome
+        invalidate_layout unless had_row == !caption.empty?
+      end
+
+      # Mounts the field, moving the message subscriptions onto it: the outgoing
+      # occupant is unsubscribed in the same call, which is the one choke point
+      # {HasContent} gives for it.
+      #
+      # A content component without {HasValidation} is fine — the message row
+      # then simply stays empty — and one that cannot hold bad input skips that
+      # slot.
+      # @param new_content [Component, nil]
+      # @return [void]
+      def content=(new_content)
+        return if content == new_content
+
+        old = content
+        super
+        # Both channels paint this row, and either can move without the other.
+        old.on_error_message_change.remove(method(:refresh_chrome)) if old.respond_to?(:on_error_message_change)
+        old.on_bad_input_change.remove(method(:refresh_chrome)) if old.respond_to?(:on_bad_input_change)
+        content.on_error_message_change << method(:refresh_chrome) if content.respond_to?(:on_error_message_change)
+        content.on_bad_input_change << method(:refresh_chrome) if content.respond_to?(:on_bad_input_change)
+        refresh_chrome
+      end
+
+      # @return [Boolean] true, so clicking the caption forwards focus into the
+      #   field through {HasContent#handle_focus}. Never a {Component#tab_stop?}:
+      #   the field it wraps is the one stop.
+      def focusable? = true
+
+      # Asks for the whole item, so a field scrolled into view brings its
+      # caption and message along — then for `rect` itself, which wins when the
+      # item is taller than the viewport (a caret row over the caption).
+      # @param rect [Rect] in this component's coordinates.
+      # @return [void]
+      def scroll_to_visible(rect = local_extent_rect)
+        super(local_rect)
+        super
+      end
+
+      protected
+
+      # The caption, the content and the message each take one row of three.
+      # @return [void]
+      def relayout
+        content&.rect = row_rects[1]
+        layout_chrome
+      end
+
+      # @return [void]
+      def handle_theme_changed
+        super
+        refresh_chrome
+      end
+
+      # @return [void]
+      def handle_attached
+        super
+        refresh_chrome
+      end
+
+      # @return [Array<String>]
+      def inspect_details = required? ? super + ["required"] : super
+
+      private
+
+      # Rebuilds both chrome strings from the current caption, marker and
+      # verdict — the single writer, idempotent, so every input that can change
+      # one of them just calls this.
+      # @return [void]
+      def refresh_chrome
+        # The marker shares the message's red rather than earning a theme token
+        # of its own — a required field is not yet invalid; see `D_form_item`.
+        ink = Screen.instance? ? screen.theme.error_color : nil
+        marker = StyledString.styled(" #{self.class.required_marker}", fg: ink)
+        @caption_label.text = required? ? caption + marker : caption
+        # `shown_message` orders the two channels, and hands back a plain
+        # String for a field's own report — hence the parse.
+        message = StyledString.parse(content.respond_to?(:shown_message) ? content.shown_message : nil)
+        @message_label.text = message.empty? ? StyledString::EMPTY : message.with_fg(ink)
+      end
+
+      # @return [void]
+      def layout_chrome
+        caption_rect, _content_rect, message_rect = row_rects
+        @caption_label.rect = caption_rect
+        @message_label.rect = message_rect
+      end
+
+      # Divides {Component#rect} top-down. A part with no row left gets a rect
+      # of zero height — empty, so the {Label} in it paints nothing — rather
+      # than a stale one (`D_empty_ancestor`).
+      # @return [Array(Rect, Rect, Rect)] the caption, content and message rects.
+      def row_rects
+        height = rect.height
+        caption_rows = caption.empty? || height < 2 ? 0 : 1
+        message_rows = height - caption_rows < 2 ? 0 : 1
+        content_rows = height - caption_rows - message_rows
+        [row_rect(0, caption_rows),
+         row_rect(caption_rows, content_rows),
+         row_rect(caption_rows + content_rows, message_rows)]
+      end
+
+      # @param top [Integer]
+      # @param rows [Integer]
+      # @return [Rect] the full width, `rows` tall.
+      def row_rect(top, rows) = Rect.new(0, top, rect.width, rows)
+    end
+  end
+end

data/lib/tuile/component/form_layout.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A column of {FormItem}s. Hand it a field and a caption; it builds the item
+    # and stacks it below the last one.
+    #
+    #   form = Component::FormLayout.new
+    #   form.add(username, caption: "Username", required: true)
+    #   form.add(notes,    caption: "Notes", rows: 5)
+    #   form.add(logging)   # a Checkbox paints its own "[x] Enable logging"
+    #   form.add(save)      # a Button, so no caption row at all
+    #
+    #   Username ∙            ← the caption row, with the required marker
+    #   [______________]      ← `rows:` content rows, 1 by default
+    #   Must not be blank     ← the message row, which is also the gap
+    #   Notes
+    #   [              ]
+    #
+    # **You hand it fields, it holds items.** {#add} wraps whatever you give it
+    # and returns the {FormItem} it built, so the chrome is the item's from the
+    # start — `add(field, caption:)` reads as though it set the *field*'s
+    # caption, and does not (`D_caption_ownership`). Name that field again
+    # wherever this class takes one — {#remove}, {#constrain}, {#field_for}'s
+    # answer — and the item around it responds. Hide that item, never the field:
+    # its caption and message go with it and the rows come back here.
+    #
+    # == Implementation details
+    # **Every row count is the caller's.** Nothing here measures and nothing is
+    # asked of a field: a captioned item is handed `1 + rows + 1` rows, a
+    # captionless one `rows + 1`. The message row doubles as the gap, which is
+    # why there is no `spacing` — and why `rows:` is a placement constraint in
+    # this layout's per-child map, exactly as `Fixed[n]` is in a {Layout::Box},
+    # rather than a property of the item. See `D_form_layout`.
+    #
+    # **Overflow clips, and there is no scrolling.** Items are laid from the top
+    # edge; the one straddling the bottom takes the rows that are left — a
+    # {FormItem} serves its content first — and everything past it gets an empty
+    # rect rather than a stale one (`D_empty_ancestor`).
+    #
+    # **The caption is read at every pass and nothing announces a change to it**,
+    # so one that appears or disappears after the item is placed resizes it at
+    # the next `rect=` rather than at once. Pass it to {#add} and the question
+    # never arises.
+    class FormLayout < Layout
+      # Placement for an item wired in through `add_child` instead of {#add}.
+      # @return [Hash{Symbol => Object}]
+      DEFAULT_PLACEMENT = { rows: 1 }.freeze
+
+      def initialize
+        super
+        # Identity-keyed: two == items are still two distinct slots.
+        @placements = {}.compare_by_identity
+      end
+
+      # Wraps `field` in a {FormItem}, adds it, and re-runs the layout.
+      #
+      #   item = form.add(notes, caption: "Notes", rows: 5)
+      #   item.required = true   # the chrome is the item's, so tune it there
+      #
+      # @param field [Component] the field to wrap — or a ready-made {FormItem},
+      #   which is adopted as it stands.
+      # @param caption [String, StyledString, nil] the caption row's text. Omit
+      #   it for a widget that paints its own face, such as a {Checkbox} or a
+      #   {Button}, and the item reserves no caption row.
+      # @param required [Boolean] paints {FormItem.required_marker} beside the
+      #   caption.
+      # @param rows [Integer] content rows for the field; `>= 1`.
+      # @param at [Integer, nil] position among the existing items; appends when
+      #   nil. The index is part of the contract — it is paint and Tab order.
+      # @raise [TypeError] unless `field` is a {Component}.
+      # @raise [ArgumentError] on a `rows` below 1, on `caption:` or `required:`
+      #   passed alongside a ready-made item, or from {FormItem} when `required:`
+      #   has no caption to sit beside.
+      # @return [FormItem] the item, whether built here or handed in.
+      def add(field, caption: nil, required: false, rows: 1, at: nil)
+        validate_rows(rows)
+        item = wrap(field, caption, required)
+        add_child(item, at:)
+        @placements[item] = { rows: }
+        invalidate_layout
+        item
+      end
+
+      # Re-sizes an item's content rows and re-runs the layout.
+      #
+      #   form.constrain(notes, 8)
+      #
+      # @param field [Component] the field, or the item around it.
+      # @param rows [Integer] content rows; `>= 1`.
+      # @raise [ArgumentError] when `field` is in no item of this form, or on a
+      #   `rows` below 1.
+      # @return [void]
+      def constrain(field, rows)
+        item = item_for(field)
+        validate_rows(rows)
+        return if placement(item)[:rows] == rows
+
+        @placements[item] = { rows: }
+        invalidate_layout
+      end
+
+      # Removes the item, forgets its placement, and closes the rows it left.
+      #
+      # The item keeps the field, so hand the *item* back to {#add} to put the
+      # row back where it was — the {Layout::Box} idiom, with `rows:` on your
+      # side because the placement is gone:
+      #
+      #   form.remove(notes)               # out, siblings move up
+      #   form.add(item, rows: 5, at: 1)   # back where it was
+      #
+      # @param field [Component] the field, or the item around it.
+      # @raise [ArgumentError] when `field` is in no item of this form.
+      # @return [void]
+      def remove(field)
+        item = item_for(field)
+        super(item)
+        @placements.delete(item)
+        invalidate_layout
+      end
+
+      # The field under a caption — sugar, since the association is a {FormItem}
+      # in the tree and an ordinary walk answers the same question.
+      #
+      #   form.field_for(caption: "Username").value = "admin"
+      #
+      # @param caption [String, StyledString] matched against {FormItem#caption}
+      #   as plain text; with duplicates, the first item wins.
+      # @return [Component, nil] the wrapped field, or nil when no item matches
+      #   or the matching one holds nothing.
+      def field_for(caption:)
+        wanted = caption.to_s
+        children.find { _1.caption.to_s == wanted }&.content
+      end
+
+      private
+
+      # Stacks the items from the top edge, each {#item_height} tall, and clips
+      # at the bottom. A hidden item gives up its content rows *and* the fused
+      # gap row below them, and everything under it moves up.
+      #
+      # Deliberately *no* `return if rect.empty?` guard: that strands the items
+      # at the coordinates they last had, and the next full repaint paints them
+      # there (`D_empty_ancestor`).
+      # @return [void]
+      def relayout
+        collapsed = Rect.new(0, 0, 0, 0)
+        top = 0
+        bottom = rect.empty? ? 0 : rect.height
+        children.each do |item|
+          rows = item.visible? ? [item_height(item), bottom - top].min : 0
+          item.rect = rows.positive? ? Rect.new(0, top, rect.width, rows) : collapsed
+          top += rows
+        end
+      end
+
+      # @param item [FormItem]
+      # @return [Integer] the rows it is handed: a caption row when it carries a
+      #   caption, its content rows, and the message row that doubles as the gap.
+      def item_height(item) = (item.caption.empty? ? 0 : 1) + placement(item)[:rows] + 1
+
+      # @param item [FormItem]
+      # @return [Hash{Symbol => Object}] the item's `rows`.
+      def placement(item) = @placements[item] || DEFAULT_PLACEMENT
+
+      # @param field [Component]
+      # @param caption [String, StyledString, nil]
+      # @param required [Boolean]
+      # @raise [TypeError] unless `field` is a {Component}.
+      # @raise [ArgumentError] when a ready-made item is handed chrome arguments.
+      # @return [FormItem]
+      def wrap(field, caption, required)
+        raise TypeError, "expected Component, got #{field.inspect}" unless field.is_a?(Component)
+        return FormItem.new(field, caption:, required:) unless field.is_a?(FormItem)
+
+        unless caption.nil? && !required
+          raise ArgumentError, "#{field} is already a FormItem: it carries its own caption and marker"
+        end
+
+        field
+      end
+
+      # @param field [Component] a field, or an item of this form.
+      # @raise [ArgumentError] when neither.
+      # @return [FormItem]
+      def item_for(field)
+        return field if children.any? { _1.equal?(field) }
+
+        item = children.find { _1.content.equal?(field) }
+        raise ArgumentError, "#{field} is in no item of #{self}" if item.nil?
+
+        item
+      end
+
+      # @param rows [Integer]
+      # @raise [ArgumentError] unless `rows` is a positive Integer.
+      # @return [void]
+      def validate_rows(rows)
+        return if rows.is_a?(Integer) && rows.positive?
+
+        raise ArgumentError, "rows expects a positive Integer, got #{rows.inspect} — " \
+                             "hide an item with visible = false rather than starving it"
+      end
+    end
+  end
+end

data/lib/tuile/component/has_bad_input.rb

@@ -23,6 +23,19 @@ module Tuile
     # formatting of the value, so a no-match is not a failed conversion and it
     # reverts the query instead.
     #
+    # == A pull and a push, answering differently on purpose
+    # {#bad_input?} is derived on read and always current, which is what a save
+    # gate asked at a click wants. A consumer with *cells* — the form item
+    # painting the message beside the field — cannot be asked at a click, so it
+    # registers on {#on_bad_input_change} and paints {HasValidation#shown_message}:
+    #
+    #   field.on_bad_input_change { |e| message_label.caption = e.message.to_s }
+    #
+    # The push carries the *showable* report, {#bad_input_message} gated by
+    # {#bad_input_settled?} and diffed, because the underlying fact is
+    # continuous — every prefix of a valid date is bad input — and a display
+    # following it raw would flash through the act of typing correctly.
+    #
     # == 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:
@@ -32,23 +45,43 @@ module Tuile
     #   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.
+    #   the error ink reads it per paint, and the push diffs it per edit.
+    #
+    # The status is never stored: `@last_bad_input` is the diff guard the push
+    # needs and nothing reads it back, as {AbstractWrappingField}'s `@last_value`
+    # is for the value notice. Which fields *can* answer is a class fact worth
+    # caching; what they answer is not.
     #
-    # 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.
+    # An includer wrapping an editor is wired by this module — every buffer edit
+    # funnels through `handle_editor_change`, and the sole writer rides it. One
+    # that latches {#bad_input_settled?} or relays a child's report calls
+    # `sync_bad_input` from wherever *that* moves ({DateField}, {DateTimeField}).
     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
+      extend Listeners::Declare
+
+      # What {#on_bad_input_change} fires.
+      #
+      # @!attribute [r] source
+      #   @return [Component] the field whose report changed.
+      # @!attribute [r] message
+      #   @return [String, nil] the showable report, `nil` when there is none to
+      #     show — the input converts, or the latch has not settled yet.
+      BadInputChangeEvent = Data.define(:source, :message) { include Tuile::Event }
+
+      # @!method on_bad_input_change
+      #   Fired with a {BadInputChangeEvent} whenever the **showable** report
+      #   changes — see the class doc for what that is and why it is not
+      #   {#bad_input?}.
+      #
+      #   **Empty means nobody outside the field is showing the report**, which
+      #   is the common case: the red well needs no notice, since it reads the
+      #   pull on every paint.
+      #   @return [Listeners]
+      listener :on_bad_input_change
 
       # Why the current input cannot be turned into a {HasValue#value} — the
       # single override point.
@@ -61,28 +94,66 @@ module Tuile
       #   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
+      # Whether the report may be *shown* yet. `true` here, so the well and the
+      # notice are 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 field 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`).
+      # It gates what is shown — the ink and the push — and never {#bad_input?},
+      # the pull a save gate asks at the click (`design/decisions.md`
+      # `D_bad_input`). Public because its readers are the app and a composite
+      # relaying a child's report, the same reason {#bad_input_message} is.
       # @return [Boolean]
       def bad_input_settled? = true
+
+      # The field's own report when it is showable, else whatever
+      # {HasValidation#shown_message} has — bad input outranks a verdict.
+      # @return [StyledString, String, nil]
+      def shown_message = (bad_input_message if bad_input_settled?) || super
+
+      protected
+
+      # Widens {HasValidation#error_ink?}: bad input paints the invalid well
+      # too, with no verdict written — once it is showable, and unless a child
+      # wears it instead.
+      # @return [Boolean]
+      def error_ink? = (bad_input? && bad_input_settled? && wears_bad_input_ink?) || super
+
+      # Whether *this* component paints the well for its own report. `true`
+      # here; a composite relaying a child's report answers `false` while that
+      # child is the one holding it, so the fault reddens where it happened
+      # rather than across the whole widget ({DateTimeField}).
+      # @return [Boolean]
+      def wears_bad_input_ink? = true
+
+      # Rides {AbstractWrappingField}'s edit funnel, so every includer wrapping
+      # an editor announces its report with no wiring of its own.
+      #
+      # `super` is guarded because an includer need not wrap an editor —
+      # {DateTimeField} is a {Layout::Horizontal} and never calls this.
+      # @return [void]
+      def handle_editor_change
+        super if defined?(super)
+        sync_bad_input
+      end
+
+      private
+
+      # Fires {#on_bad_input_change} when the showable report has really
+      # changed — the sole writer of `@last_bad_input`, called from wherever an
+      # input of that expression moves.
+      # @return [void]
+      def sync_bad_input
+        showable = bad_input_settled? ? bad_input_message : nil
+        return if showable == @last_bad_input
+
+        @last_bad_input = showable
+        on_bad_input_change.fire(BadInputChangeEvent.new(source: self, message: showable))
+      end
     end
   end
 end

data/lib/tuile/component/has_caption.rb

@@ -16,11 +16,20 @@ module Tuile
     # Includers own the *rendering* — clipping, width arithmetic, decoration
     # such as {Window}'s `[key]-` shortcut prefix; this holds only the text.
     #
-    # == Implementation details
-    # Being a mixin is what lets tree-walking code find "the {Button} captioned
-    # Submit" via `is_a?(HasCaption)` plus a caption compare, rather than a
-    # hardcoded list of classes that happen to respond to `caption`. Don't
-    # collapse it back into per-class accessors.
+    # == What this mixin is for
+    # **Nomenclature, plus one shared value rule**: the coercion, the
+    # no-op-when-unchanged short-circuit, the {Component#invalidate} and the
+    # {Component#inspect} line, held in one place so its includers cannot drift
+    # on them. `is_a?(HasCaption)` is a marker saying *this component wears
+    # chrome text*, and nothing in `lib/` consults it.
+    #
+    # **It is not a lookup seam, and must not become one.** {Tuile::Testing}
+    # used to filter by `caption:` on exactly this `is_a?`, which made a
+    # component's mixin membership answerable by what a test locator found
+    # convenient — a library is never shaped to suit its tests. Structural
+    # handles do that job ({Component#id}, the class, a subtree), and a spec
+    # that really wants the text says so per-class in a block. See
+    # `D_component_lookup`.
     module HasCaption
       # Read through *this* method, never `@caption` — the ivar stays nil until
       # the first non-empty set ({#caption=} short-circuits when unchanged).