tuile 0.15.0 → 0.17.0

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
@@ -410,11 +441,11 @@ module Tuile
     #
     # `:rgi` credits width 2 only to [RGI](https://www.unicode.org/reports/tr51/)
     # sequences — the ones vendors actually ship a single glyph for — and *sums*
-    # the parts of anything else. That is the one setting never wrong in the
-    # dangerous direction: under-measuring lets a glyph overrun its cell, which
-    # shifts the rest of the row, desyncs the cursor and escapes the component's
-    # rect, while over-measuring leaves a blank column. `D_cluster_width` has the
-    # per-setting reasoning.
+    # the parts of anything else, erring only in the direction that cannot escape
+    # a component: {Buffer#flush} emits a dirty run contiguously, so a mis-measure
+    # of either sign shifts the rest of that run, but only an under-measure shifts
+    # it right, into a neighbour whose cells are clean and so never repainted.
+    # `D_cluster_width` has the per-setting reasoning.
     # @return [Symbol]
     EMOJI_WIDTH = :rgi
 
@@ -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