tuile 0.16.0 → 0.17.0

data/lib/tuile/screen_pane.rb

@@ -13,7 +13,7 @@ module Tuile
   # The pane owns no chrome of its own — no status bar, no reserved row.
   # {#content} gets the full pane rect, and an app that wants a status line
   # builds one into its own layout and drives it from
-  # {Screen#on_focus_changed=} (`D_status_bar`).
+  # {Screen#on_focus_changed} (`D_status_bar`).
   #
   # The pane is not a {Component::Layout}: popups deliberately overlap content
   # (Z-ordered, full overdraw, no clipping) and key/mouse dispatch follows
@@ -27,6 +27,10 @@ module Tuile
       # user was, instead of falling through to {#content} and getting
       # cascaded to the first focusable child.
       @popup_prior_focus = {}
+      # Where each open popup wants to be, and the anchor rect its last
+      # placement used (`:lost` once the anchor went away) — see #relayout.
+      @placements = {}.compare_by_identity
+      @placed_anchors = {}.compare_by_identity
     end
 
     # @return [Component, nil] the tiled content component.
@@ -52,14 +56,13 @@ module Tuile
       remove_child(@content) unless @content.nil?
       @content = content
       add_child(content, at: 0) # the tiled layer paints beneath everything else
-      layout
     end
 
-    # Adds an overlay and invalidates it for repaint. A {Component::Popup} is
-    # centered and grabs focus; a bare {Component::Overlay} is left wherever
-    # the caller positioned it and does *not* take focus, so the component that
-    # was focused keeps the cursor and keeps receiving keys — the overlay
-    # floats above the content, driven from app code.
+    # Adds an overlay at `placement` and invalidates it for repaint; the next
+    # settle gives it its rect. A {Component::Popup} grabs focus; a bare
+    # {Component::Overlay} does *not*, so the component that was focused keeps
+    # the cursor and keeps receiving keys — the overlay floats above the
+    # content, driven from app code.
     #
     # The *whole subtree* is invalidated, not just the overlay wrapper (which
     # paints nothing on its own): a reopened popup may land on cells that the
@@ -67,21 +70,48 @@ module Tuile
     # last time its content components won't re-invalidate themselves — so
     # without this the overlay's contents would stay blank on reopen.
     # @param window [Component::Overlay] any overlay, modal or not.
+    # @param placement [Component::Overlay::Placement, nil] where it wants to
+    #   be; `nil` takes its {Component::Overlay#default_placement}.
+    # @raise [TypeError] if `placement` does not include
+    #   {Component::Overlay::Placement}.
     # @return [void]
-    def add_popup(window)
+    def add_popup(window, placement = nil)
       raise TypeError, "expected Overlay, got #{window.inspect}" unless window.is_a? Component::Overlay
       raise ArgumentError, "#{window} already has a parent #{window.parent}" unless window.parent.nil?
 
+      placement ||= window.default_placement
+      check_placement(placement)
       @popup_prior_focus[window] = screen.focused
+      @placements[window] = placement
       @popups << window
       add_child(window) # appended: popups paint over the tiled content
-      if window.modal?
-        window.center
-        screen.focused = window
-      end
+      screen.focused = window if window.modal?
       window.walk_tree { |c| screen.invalidate(c) }
     end
 
+    # @param popup [Component::Overlay] an open popup.
+    # @return [Component::Overlay::Placement, nil] where it wants to be; `nil`
+    #   if it isn't open here.
+    def placement(popup) = @placements[popup]
+
+    # Moves an open popup; it takes the new rect on the next settle.
+    # {Component::Overlay#placement=} is the usual way in.
+    # @param popup [Component::Overlay] an open popup.
+    # @param placement [Component::Overlay::Placement] where it wants to be.
+    # @raise [ArgumentError] if `popup` isn't open on this pane.
+    # @raise [TypeError] if `placement` does not include
+    #   {Component::Overlay::Placement}.
+    # @return [void]
+    def constrain(popup, placement)
+      raise ArgumentError, "#{popup} is not an open popup on this pane" unless has_popup?(popup)
+
+      check_placement(placement)
+      return if @placements[popup] == placement
+
+      @placements[popup] = placement
+      invalidate_layout
+    end
+
     # Removes a popup. If the popup held focus, focus shifts to the now-topmost
     # remaining popup, falling back to the focus snapshotted when the popup
     # was opened (if still attached), then to {#content}, then to nil.
@@ -91,6 +121,8 @@ module Tuile
       raise Tuile::Error, "#{window} is not an open popup on this pane" unless @popups.delete(window)
 
       prior = @popup_prior_focus.delete(window)
+      @placements.delete(window)
+      @placed_anchors.delete(window)
       @removing_popup_prior = prior
       remove_child(window)
       # Runs after the detach, so a prior pointing *inside* the removed popup is
@@ -118,6 +150,8 @@ module Tuile
       @content = nil
       @popups.clear
       @popup_prior_focus.clear
+      @placements.clear
+      @placed_anchors.clear
     end
 
     # @param window [Component]
@@ -131,30 +165,40 @@ module Tuile
     #   content without capturing input.
     def modal_popup = @popups.reverse_each.find(&:modal?)
 
-    # Re-lays out children whenever the pane's own rect changes.
-    # @param new_rect [Rect]
-    # @return [void]
-    def rect=(new_rect)
-      super
-      layout
-    end
+    # The root of the current **key scope**: the topmost modal popup when one
+    # is open, else the tiled {#content}. Keys bubble up to it and no further,
+    # a paste reaches only a focus chain inside it, and Tab cycles only the
+    # stops beneath it — so a component outside it is one the keyboard cannot
+    # reach at all. The mouse resolves against a *point* instead
+    # ({#mouse_root_at}).
+    # @return [Component, nil] nil when the pane holds neither.
+    def key_scope = modal_popup || @content
 
     # Gives {#content} the whole pane rect — the pane reserves nothing for
-    # itself. Each popup re-resolves its {Component::Popup#declared_size} against the new
-    # screen via {Component::Popup#reposition} — so a {Fraction} size tracks
-    # resize — repositioning itself (modal popups recenter; non-modal overlays
-    # keep the top-left their owner assigned).
+    # itself — and each popup the rect its placement asks for, in stacking
+    # order, so a submenu is placed after the panel it hangs from.
+    #
+    # Re-running it moves nothing that stood still: a placement is a rule, so
+    # a second popup opening re-derives the first one's rect unchanged.
+    #
+    # An empty pane collapses every popup rather than placing it — an `At` rect
+    # would otherwise stand in a pane with no cells — and has no `return if
+    # rect.empty?` guard, which would strand the content at its last rect
+    # (`D_empty_ancestor`).
     # @return [void]
-    def layout
-      return if rect.empty?
-
-      @content&.rect = rect
-      @popups.each(&:reposition)
+    def relayout
+      @content&.rect = local_rect
+      if rect.empty?
+        @popups.each { _1.rect = Rect.new(0, 0, 0, 0) }
+      else
+        @popups.each { place(_1) }
+      end
     end
 
     # Pane paints nothing itself; its children paint over the entire rect.
+    # @param _canvas [Canvas] see {Component#repaint}.
     # @return [void]
-    def repaint; end
+    def repaint(_canvas); end
 
     # Delivers a key to {Screen#focused}, then bubbles it up the focus chain —
     # the first component whose `handle_key?` returns true wins.
@@ -174,7 +218,7 @@ module Tuile
     # @param key [String]
     # @return [Boolean] true if the key was handled.
     def handle_key?(key)
-      scope = modal_popup || @content
+      scope = key_scope
       return false if scope.nil?
 
       bubble_key(key, scope)
@@ -190,7 +234,7 @@ module Tuile
     # @param text [String]
     # @return [void]
     def handle_paste(text)
-      scope = modal_popup || @content
+      scope = key_scope
       return if scope.nil?
 
       chain = focus_chain(scope)
@@ -283,6 +327,75 @@ module Tuile
 
     private
 
+    # Rejects a non-placement where the app named it, rather than mid-pass: the
+    # layout is deferred, so the `NoMethodError` from a missing `rect_for` would
+    # otherwise surface a turn later, under this file's backtrace.
+    # @param placement [Object]
+    # @raise [TypeError] unless it includes {Component::Overlay::Placement}.
+    # @return [void]
+    def check_placement(placement)
+      return if placement.is_a?(Component::Overlay::Placement)
+
+      raise TypeError, "#{placement.class} must include Tuile::Component::Overlay::Placement"
+    end
+
+    # A placement's {Component::Overlay::Placement#anchor} in screen
+    # coordinates: a `Rect` passes through, a component resolves while it is on
+    # screen, and `nil` means either unanchored or gone — {#place} tells those
+    # apart by whether an anchor was declared at all.
+    # @param anchor [Component, Rect, nil]
+    # @return [Rect, nil]
+    def resolve_anchor(anchor)
+      return anchor if anchor.nil? || anchor.is_a?(Rect)
+
+      ComponentUtil.effectively_visible?(anchor) ? anchor.absolute_extent_rect : nil
+    end
+
+    # @param popup [Component::Overlay]
+    # @return [void]
+    def place(popup)
+      placement = @placements.fetch(popup)
+      anchor = placement.anchor
+      anchor_rect = resolve_anchor(anchor)
+      unless anchor.nil?
+        return lose_anchor(popup) if anchor_rect.nil?
+
+        @placed_anchors[popup] = anchor_rect
+      end
+      popup.rect = placement.rect_for(popup, rect.size, anchor_rect)
+    end
+
+    # Leaves a popup whose anchor was detached or hidden at its last rect. It
+    # warns, once, because closing the popup is its owner's job and an owner
+    # that forgot leaves it floating over nothing.
+    # @param popup [Component::Overlay]
+    # @return [void]
+    def lose_anchor(popup)
+      return if @placed_anchors[popup] == :lost
+
+      @placed_anchors[popup] = :lost
+      Tuile.logger.warn("#{popup} lost its anchor; left where it was — close it when the anchor goes")
+    end
+
+    # Re-marks the pane when an anchored popup's anchor now resolves elsewhere
+    # than where its last placement read it. {Screen#flush_layout} asks once
+    # its drain is empty, because this pane's pass runs *before* the content an
+    # anchor sits in, so a settle that moved the content handed the pass a
+    # stale anchor. Anchors in `lib/` converge in one more round — the content
+    # never moves for a popup, and a cascade anchors to a `Rect` — but a popup
+    # anchored inside another takes one round per level.
+    # @return [Boolean] whether it marked, so the screen drains again.
+    def remark_moved_anchors
+      return false if rect.empty? # #relayout collapses rather than places then, so nothing records
+
+      moved = @popups.any? do |popup|
+        anchor = @placements[popup].anchor
+        !anchor.nil? && (resolve_anchor(anchor) || :lost) != @placed_anchors[popup]
+      end
+      invalidate_layout if moved
+      moved
+    end
+
     # The overlays a click counts as landing *inside*: the one it hit, plus
     # every overlay that one belongs to, up the {Component::Overlay#owner}
     # chain. An owner is any component, so it is resolved to the overlay

data/lib/tuile/strict_layout.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Tuile
+  # The stale-rect diagnostic: a {Component#rect} read taken while an ancestor
+  # still owes a {Component#relayout} says so, instead of handing back the
+  # previous pass's rectangle in silence. **On wherever a {FakeScreen} is the
+  # installed screen** — a spec suite needs no setup to get it — and off in an
+  # app, which {Tuile.strict_layout} overrides either way:
+  #
+  #   holder.constrain(pane, Rect.new(0, 0, 100, 26))
+  #   pane.left.rect        # => Tuile::Error: read the rect of #<Tuile::Component::Label
+  #                         #    rect=(0,0 80x50)> while #<TwoPane rect=(0,0 100x26)> owes a
+  #                         #    relayout … at spec/two_pane_spec.rb:42
+  #
+  # `:warn` logs the same line to {Tuile.logger} and hands the rectangle over,
+  # for watching a running app; `:raise` is the default and what a spec wants,
+  # since the backtrace names the read and a suite that never set a logger
+  # would see nothing at all. For the read that is pre-settle *on purpose*,
+  # {Tuile.without_strict_layout}.
+  #
+  # Reading `size`, `width`, `height`, `local_rect`, `absolute_rect` or
+  # `to_screen` reports too — they all go through the one reader.
+  #
+  # **Only reads the app makes are reported** ({PLUMBING}): a read `lib/` makes
+  # on the app's behalf mid-handler is not the app's to fix.
+  #
+  # == Implementation details
+  #
+  # {Tuile.strict_layout=} and {FakeScreen} prepend this module into
+  # {Component}, so `rect` stays the bare `attr_reader` — the hottest read in
+  # the toolkit — in every process that never asks. Nothing unprepends; turning
+  # the mode off leaves the check inert. See `D_strict_layout`.
+  module StrictLayout
+    # Where the gem's own frames live, so the site the message names is the
+    # app's — `to_screen` and the `size` / `width` / `height` trio all read
+    # `rect` from inside `component.rb`.
+    # @return [String]
+    LIB_DIR = File.expand_path("..", __dir__)
+
+    # The thread-local marking a report in progress: {Component#inspect} prints
+    # the rect, so building the message re-enters `rect` on the very component
+    # that is being complained about.
+    # @return [Symbol]
+    REPORTING = :tuile_strict_layout_reporting
+
+    # The readers that only forward to `rect`. A frame of one of these between
+    # the read and the app's own code carries no decision of the framework's, so
+    # the read still counts as the app's.
+    # @return [Array<String>]
+    PLUMBING = %w[rect size width height local_rect local_extent_rect absolute_rect absolute_extent_rect
+                  to_screen to_local].freeze
+
+    class << self
+      # Makes {Component#rect} consult {Tuile.strict_layout} — idempotent, and
+      # permanent for the process.
+      # @return [void]
+      def install = Component.prepend(self)
+
+      # Reports `component`'s rect read as stale, the way `mode` asks for.
+      #
+      # @param component [Component] the component whose rect was read.
+      # @param ancestor [Component] the ancestor owing the relayout.
+      # @param mode [Symbol] `:raise` or `:warn`.
+      # @raise [Error] in `:raise` mode, unless the read was the framework's own.
+      # @return [void]
+      def report(component, ancestor, mode)
+        return unless app_read?
+
+        message = message_for(component, ancestor)
+        raise Error, message if mode == :raise
+
+        Tuile.logger.warn(message)
+      end
+
+      private
+
+      # @param component [Component]
+      # @param ancestor [Component]
+      # @return [String]
+      def message_for(component, ancestor)
+        Thread.current[REPORTING] = true
+        "Tuile: read the rect of #{component.inspect} while #{ancestor.inspect} owes a relayout — " \
+          "that rectangle is the previous pass's. Call flush_layout before reading it (a spec), or " \
+          "read it after the next event (an app)#{site}"
+      ensure
+        Thread.current[REPORTING] = false
+      end
+
+      # Whether the app asked the question rather than the framework on its
+      # behalf: the frames between the read and the first one outside the gem
+      # are {PLUMBING} and nothing else.
+      # @return [Boolean]
+      def app_read?
+        frames.each do |frame|
+          return true unless frame.path.start_with?(LIB_DIR)
+          return false unless PLUMBING.include?(frame.base_label)
+        end
+        false
+      end
+
+      # @return [String] ` at <path>:<line>` for the frame that made the read,
+      #   or `""` when there is none outside the gem.
+      def site
+        frame = frames.find { !_1.path.start_with?(LIB_DIR) }
+        frame.nil? ? "" : " at #{frame.path}:#{frame.lineno}"
+      end
+
+      # The stack above this file, asked from wherever in it — dropping our own
+      # frames by path rather than by a `caller_locations` offset, which would
+      # be two different numbers and would drift on any refactor here.
+      # @return [Array<Object>] `Thread::Backtrace::Location`s.
+      def frames = caller_locations.drop_while { _1.path == __FILE__ }
+    end
+
+    # {Component#rect}, reporting first when it is about to answer the previous
+    # pass's rectangle.
+    # @return [Rect]
+    def rect
+      mode = Tuile.strict_layout
+      if mode && !Thread.current[REPORTING]
+        ancestor = stale_layout_ancestor
+        StrictLayout.report(self, ancestor, mode) unless ancestor.nil?
+      end
+      super
+    end
+  end
+end

data/lib/tuile/styled_string.rb

@@ -403,6 +403,37 @@ module Tuile
           raise TypeError, "cannot parse #{input.class}"
         end
       end
+
+      # Checks a glyph knob's value at assignment: exactly one grapheme
+      # cluster, one column wide. A component painting one glyph per cell
+      # spills a wider one onto its neighbour — silently, with nothing in the
+      # frame to point at — so every glyph knob asks here rather than at paint.
+      #
+      #   def track_char=(char)
+      #     @track_char = StyledString.validate_glyph(char, :track_char)
+      #   end
+      #
+      # East-Asian-Ambiguous glyphs pass: Tuile measures them one column by
+      # construction (`D_ambiguous_width`), so no check can catch a terminal
+      # drawing them two.
+      # @param char [String]
+      # @param name [Symbol, String] the knob, for the message.
+      # @return [String] `char`, frozen.
+      # @raise [TypeError] when `char` is not a String.
+      # @raise [ArgumentError] when `char` is not exactly one grapheme cluster
+      #   one column wide.
+      def validate_glyph(char, name)
+        raise TypeError, "#{name} must be a String, got #{char.inspect}" unless char.is_a?(String)
+
+        unless char.each_grapheme_cluster.take(2).size == 1
+          raise ArgumentError, "#{name} must be exactly one grapheme cluster, got #{char.inspect}"
+        end
+
+        width = plain(char).display_width
+        raise ArgumentError, "#{name} must be one column wide, got #{char.inspect} (#{width})" unless width == 1
+
+        -char
+      end
     end
 
     # The framework's single emoji-width policy, passed to every
@@ -500,27 +531,88 @@ module Tuile
       slice_spans(start, len)
     end
 
-    # Truncates to a target column width, appending an ellipsis when
-    # characters were dropped. The ellipsis counts toward the target — the
-    # returned {StyledString}'s `display_width` never exceeds
-    # `display_width`. When `self` already fits, `self` is returned. When
-    # `display_width` is smaller than the ellipsis's own width, the ellipsis
-    # is sliced down to fit and no original content is included.
+    # Truncates to a target column width, marking the cut end with an ellipsis.
+    # The ellipsis counts toward the target — the returned {StyledString}'s
+    # `display_width` never exceeds `display_width`, and comes out a column
+    # short when the cut lands mid-cluster, since a wide glyph straddling the
+    # boundary is dropped rather than halved. When `self` already fits, `self`
+    # is returned. When `display_width` is smaller than the ellipsis's own
+    # width, the ellipsis is sliced down to fit and no original content is
+    # included.
+    #
+    # `at: :start` keeps the *tail* instead, for text whose end identifies it
+    # and whose head is context — a path (`…/shared/markdown/`), a log line's
+    # message after its prefix.
     #
     # @param display_width [Integer] target column width.
-    # @param ellipsis [String, StyledString] appended when truncation
+    # @param ellipsis [String, StyledString] added when truncation
     #   occurs. Defaults to the Unicode horizontal-ellipsis `…` (one
     #   column). A `String` is parsed via {.parse}, so ANSI in it is
     #   preserved.
+    # @param at [Symbol] which end is cut: `:end` (the default) keeps the head
+    #   and appends, `:start` keeps the tail and prepends.
+    # @raise [ArgumentError] unless `at` is `:start` or `:end`.
     # @return [StyledString]
-    def ellipsize(display_width, ellipsis = "…")
+    def ellipsize(display_width, ellipsis = "…", at: :end)
+      raise ArgumentError, "expected :start or :end, got #{at.inspect}" unless %i[start end].include?(at)
       return self.class.new if display_width <= 0
       return self if self.display_width <= display_width
 
       ellipsis = self.class.parse(ellipsis)
       return ellipsis.slice(0, display_width) if ellipsis.display_width >= display_width
 
-      slice(0, display_width - ellipsis.display_width) + ellipsis
+      keep = display_width - ellipsis.display_width
+      return ellipsis + slice(self.display_width - keep, keep) if at == :start
+
+      slice(0, keep) + ellipsis
+    end
+
+    # Pads on the right out to `width` display columns — {String#ljust}
+    # counted in columns, so a CJK glyph or an emoji measures what it paints.
+    #
+    #   StyledString.plain("日本").ljust(6).to_s   # => "日本  "
+    #   row.ellipsize(w).ljust(w)                  # exactly w columns
+    #
+    # Never truncates: `self` comes back when already at least `width` wide,
+    # a negative gap included. The fill is unstyled, so it shows whatever
+    # background is painted under it.
+    # @param width [Integer] target display width.
+    # @param pad [String] the fill, one grapheme cluster one column wide.
+    # @return [StyledString]
+    # @raise [ArgumentError] when `pad` is not one cluster one column wide.
+    def ljust(width, pad = " ")
+      gap = gap_to(width, pad)
+      gap.zero? ? self : self + self.class.plain(pad * gap)
+    end
+
+    # Pads on the left out to `width` display columns; see {#ljust}.
+    #
+    #   StyledString.plain("42").rjust(5).to_s   # => "   42"
+    #
+    # @param width [Integer] target display width.
+    # @param pad [String] the fill, one grapheme cluster one column wide.
+    # @return [StyledString]
+    # @raise [ArgumentError] when `pad` is not one cluster one column wide.
+    def rjust(width, pad = " ")
+      gap = gap_to(width, pad)
+      gap.zero? ? self : self.class.plain(pad * gap) + self
+    end
+
+    # Pads both sides out to `width` display columns; see {#ljust}. An odd gap
+    # puts the extra column on the right, as {String#center} does.
+    #
+    #   StyledString.plain("ab").center(5, "·").to_s   # => "·ab··"
+    #
+    # @param width [Integer] target display width.
+    # @param pad [String] the fill, one grapheme cluster one column wide.
+    # @return [StyledString]
+    # @raise [ArgumentError] when `pad` is not one cluster one column wide.
+    def center(width, pad = " ")
+      gap = gap_to(width, pad)
+      return self if gap.zero?
+
+      left = gap / 2
+      self.class.plain(pad * left) + self + self.class.plain(pad * (gap - left))
     end
 
     # Splits on `"\n"`, preserving spans on each side. A trailing newline
@@ -646,6 +738,34 @@ module Tuile
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(fg: fg)) })
     end
 
+    # Returns a copy with `fg` set **only on spans that have none**; a span with
+    # an explicit fg is left untouched. The foreground counterpart of
+    # {#under_bg} — it gives a caption a default tone while keeping the parts
+    # the app colored itself:
+    #
+    #   caption = StyledString.plain("Queue ") + StyledString.styled("3", fg: theme[:notice])
+    #   caption.under_fg(theme[:hint])   # "Queue " in :hint, "3" stays :notice
+    #
+    # An `inverse` span is skipped even when its `fg` member is nil, as
+    # {#under_bg} skips it: SGR 7 swaps the pair, so a filled fg would become
+    # the span's *background*.
+    #
+    # @param fg [Color, Symbol, Integer, Array<Integer>, nil] foreground color,
+    #   coerced via {Color.coerce}. `nil` returns `self` unchanged.
+    # @return [StyledString]
+    def under_fg(fg)
+      return self if fg.nil?
+
+      fg = Color.coerce(fg)
+      self.class.new(@spans.map do |span|
+        if span.style.fg.nil? && !span.style.inverse
+          Span.new(text: span.text, style: span.style.merge(fg: fg))
+        else
+          span
+        end
+      end)
+    end
+
     # Returns a new {StyledString} with `bold` applied to every span, preserving
     # each span's text and other style attributes (`fg`, `bg`, `italic`,
     # `underline`, `strikethrough`). The bold-attribute counterpart of
@@ -740,6 +860,16 @@ module Tuile
       result
     end
 
+    # @param width [Integer]
+    # @param pad [String]
+    # @return [Integer] columns {#ljust} and friends must fill, never negative.
+    # @raise [ArgumentError] when `pad` is not one cluster one column wide.
+    def gap_to(width, pad)
+      # The default skips validation: the fill runs once per painted row.
+      self.class.validate_glyph(pad, :pad) unless pad == " "
+      (width - display_width).clamp(0, nil)
+    end
+
     # @param start_or_range [Integer, Range]
     # @param len [Integer, nil]
     # @param total [Integer] receiver's full display width.

data/lib/tuile/testing/gestures.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Tuile
+  module Testing
+    # Receiver syntax for {Tuile::Testing}'s gestures, so a located component
+    # is driven in one line instead of passed back as an argument:
+    #
+    #   using Tuile::Testing::Gestures
+    #
+    #   Testing.get(Component::TextField, id: :name)._value = "Zaphod"
+    #   Testing.get(Component::Button) { _1.caption.to_s == "Save" }._click
+    #
+    # A **refinement**, so it exists only where `using` says so — per file or
+    # per `describe` block, never leaking to a sibling — and nothing lands on
+    # {Component} itself. That is `D_component_lookup`'s standing answer for
+    # wanting receiver syntax.
+    #
+    # **The leading underscore is the mark**, borrowed from Karibu-Testing: it
+    # says *testing API, not the component's own*, which matters most for
+    # `_value=` sitting one character from a real `value=`. The unrefined
+    # spellings keep plain names, since `Testing.` already marks them.
+    module Gestures
+      refine Component do
+        # @return [void] see {Testing.click}.
+        def _click = Testing.click(self)
+
+        # @param value [Object] see {Testing.set_value}.
+        # @return [void]
+        def _value=(value)
+          Testing.set_value(self, value)
+        end
+      end
+    end
+  end
+end