tuile 0.14.0 → 0.16.0

data/lib/tuile/component/progress_bar.rb

@@ -38,7 +38,7 @@ module Tuile
     # The `█`/`░` pair is the same one {VerticalScrollBar} uses — East-Asian
     # Ambiguous and Neutral respectively, so under an ambiguous-as-wide terminal
     # the rendered length would vary with the fill level. Shipped anyway, per
-    # `DECISIONS.md` `D_ambiguous_width`: a bar that rhymes with the scrollbar
+    # `design/decisions.md` `D_ambiguous_width`: a bar that rhymes with the scrollbar
     # beats a third convention, and if that bet is ever reversed both swap
     # together.
     class ProgressBar < Component
@@ -148,7 +148,7 @@ module Tuile
 
       # Sets the color of both glyphs, live-resolved at paint time when given a
       # {Theme::Ref} (so it follows a {Screen#theme=} with no
-      # {Component#on_theme_changed} hook).
+      # {Component#handle_theme_changed} hook).
       #
       #   bar.bar_color = Color::GREEN
       #   bar.bar_color = Theme.ref(:brand_ok)   # an app #custom token
@@ -192,10 +192,16 @@ module Tuile
       end
 
       # @return [void]
-      def on_attached = sync_ticker
+      def handle_attached
+        super
+        sync_ticker
+      end
 
       # @return [void]
-      def on_detached = sync_ticker
+      def handle_detached
+        super
+        sync_ticker
+      end
 
       # Paints the bar on the first row of {#rect} and blanks the rest.
       #

data/lib/tuile/component/radio_group.rb

@@ -22,12 +22,13 @@ module Tuile
     # already-selected row is a no-op rather than a deselect.
     #
     # Composes rather than subclasses, like {ComboBox}: a {List} of the items
-    # is its single {HasContent} child, which is where the cursor, scrolling,
-    # the scrollbar and per-row mouse hit-testing come from — the group only
-    # supplies the {List#renderer} that puts the marker in front of the label.
-    # `content` is that list, so an app can tune it (`scrollbar_visibility`,
-    # `show_cursor_when_inactive`, …). Rows beyond {#rect}'s height scroll; the
-    # inner list is the tab stop, not the group.
+    # is its single child, which is where the cursor, scrolling, the scrollbar
+    # and per-row mouse hit-testing come from — the group only supplies the
+    # {List#renderer} that puts the marker in front of the label. {#list} is
+    # that list, exposed read-only so an app can tune it
+    # (`scrollbar_visibility`, `show_cursor_when_inactive`, …) but never swap it
+    # out. Rows beyond {#rect}'s height scroll; the inner list is the tab stop,
+    # not the group.
     #
     # == The cursor is chrome
     # The cursor and the selection are two independent things, as in
@@ -36,7 +37,7 @@ module Tuile
     # {#value=} therefore does *not* move the cursor. An app that wants it
     # parked on the selection parks it:
     #
-    #   rg.content.cursor = List::Cursor.new(position: rg.items.index(rg.value))
+    #   rg.list.cursor = List::Cursor.new(position: rg.items.index(rg.value))
     #
     # {#items=} is the one thing that moves it, clamping it back into range.
     #
@@ -60,7 +61,6 @@ module Tuile
     #
     # UI-thread-confined, like every component (see {Screen}).
     class RadioGroup < Component
-      include HasContent
       include HasValue
 
       # @param items [Array] the items to present, one row each; also settable
@@ -80,11 +80,36 @@ module Tuile
         list.renderer = method(:render_row)
         list.on_item_chosen = ->(_index, item) { self.value = item }
         list.items = items.to_a
-        self.content = list
+        @list = list
+        add_child(list, at: 0)
+      end
+
+      # The composed {List}: an app may *tune* it — its scrollbar, its cursor,
+      # `show_cursor_when_inactive` — but never replace it, since this group's
+      # renderer and selection are wired into this one (`design/decisions.md`
+      # `D_has_content`). Those knobs are {List} concepts rather than group
+      # concepts, which is why they are reached here instead of forwarded
+      # (`D_wrapping_field`).
+      # @return [List]
+      attr_reader :list
+
+      # @param new_rect [Rect]
+      # @return [void]
+      def rect=(new_rect)
+        super
+        list.rect = rect
+      end
+
+      # @return [void]
+      def handle_focus
+        super
+        # The list is what the arrows drive, so it takes the focus this group
+        # was given; the group itself claims only Space.
+        screen.focused = list if list.focusable?
       end
 
       # @return [Array] the presented items.
-      def items = content.items
+      def items = list.items
 
       # @return [Proc, Method] item -> row label (a `String`, {StyledString}, or
       #   anything with `#to_s`); `:to_s` by default.
@@ -101,14 +126,14 @@ module Tuile
         # Before the items land, so the single {List#on_cursor_changed} that
         # {List#items=} fires reports the final row rather than a stale one.
         clamp_cursor(new_items.size)
-        content.items = new_items
+        list.items = new_items
       end
 
       # @param proc [Proc, Method] item -> row label.
       # @return [void]
       def item_label=(proc)
         @item_label = proc
-        content.refresh_rows
+        list.refresh_rows
       end
 
       # Selects `new_value`, firing {HasValue#on_value_change} when it really
@@ -122,7 +147,7 @@ module Tuile
         return if value == new_value
 
         super
-        content.refresh_rows
+        list.refresh_rows
       end
 
       # Selects the cursor row on Space. Nothing else is claimed: the composed
@@ -131,20 +156,13 @@ module Tuile
       # neither of us wants bubbles on to an ancestor.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         return false unless key == " "
 
-        select_at(content.cursor.position)
+        select_at(list.cursor.position)
         true
       end
 
-      protected
-
-      # Places the composed list across the whole rect ({HasContent} hook).
-      # @param list [Component]
-      # @return [void]
-      def layout(list) = (list.rect = rect)
-
       private
 
       # Selects the item on row `index`; an index outside {#items} is ignored —
@@ -172,7 +190,7 @@ module Tuile
       # @param item_count [Integer] size of the incoming item list.
       # @return [void]
       def clamp_cursor(item_count)
-        cursor = content.cursor
+        cursor = list.cursor
         # go_to_last funnels through Cursor#go's clamp(0, nil), so an empty
         # items list floors at 0 instead of going negative.
         cursor.go_to_last(item_count) if cursor.position >= item_count

data/lib/tuile/component/select.rb

@@ -42,7 +42,7 @@ module Tuile
     # Home/End are declined too, so they stay available app-wide.
     #
     # There is no type-ahead: a hidden prefix buffer *is* the ComboBox query with
-    # the feedback removed (`DECISIONS.md` `D_select`). Which is also why labels
+    # the feedback removed (`design/decisions.md` `D_select`). Which is also why labels
     # need no prefix-disambiguation.
     #
     # == Implementation details
@@ -138,7 +138,7 @@ module Tuile
       # is left unhandled so it bubbles to an ancestor.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         if @overlay.open?
           return true if @overlay.move(key)
 
@@ -159,22 +159,21 @@ module Tuile
       # The one row this Select paints — the full width, at the top of {#rect}.
       # A single-slot container ({Component::Window}, {Component::Popup}) hands
       # its content the whole inner rect, so a Select is routinely assigned more
-      # height than it uses; {#repaint} clears that tail, {#handle_mouse} refuses
-      # clicks in it, and the dropdown hangs under this rather than under the
+      # height than it uses; {#repaint} clears that tail, a press in it never reaches
+      # {#handle_mouse_down?}, and the dropdown hangs under this rather than under the
       # unused space.
       # @return [Size]
       def extent = Size.new(rect.width, 1)
 
-      # Toggles the dropdown on a left click anywhere in {#extent} — a field's
-      # affordance is its whole row, as the well advertises; `super` runs first,
-      # so the click also focuses.
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        return unless event.button == :left && extent_rect.contains?(event.point)
+      # Toggles the dropdown on a left press anywhere in {#extent} — a field's
+      # affordance is its whole row, as the well advertises.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
         @overlay.open? ? close_menu : open_menu
+        true
       end
 
       # @return [void]
@@ -185,17 +184,25 @@ module Tuile
         draw_text(rect.left, rect.top, face_row)
       end
 
+      # The field well this Select's face sits on — {Theme#active_bg_color}
+      # while on the focus chain, {Theme#input_bg_color} otherwise. A Select has
+      # no caret, so the focus shade is its only indicator: an app that flattens
+      # it with a plain {Component#bg_color} is choosing that, and can keep the
+      # pair with `bg_color = { normal: …, active: … }`.
+      # @return [Color]
+      def default_bg_color = active? ? screen.theme.active_bg_color : screen.theme.input_bg_color
+
       private
 
       # The painted row: the value's label padded across all but the last column,
-      # then the `▾`, all on the field well — {Theme#active_bg_color} while on the
-      # focus chain, {Theme#input_bg_color} otherwise.
+      # then the `▾`. The well underneath is {#default_bg_color}, applied by
+      # {Component#draw_text} — so a label span carrying its own background keeps
+      # it, where the old override-all fill flattened it.
       # @return [StyledString]
       def face_row
         width = [rect.width - 1, 0].max
         label = label_for(value).ellipsize(width)
-        row = label + StyledString.plain("#{" " * (width - label.display_width)}▾")
-        row.with_bg(active? ? screen.theme.active_bg_color : screen.theme.input_bg_color)
+        label + StyledString.plain("#{" " * (width - label.display_width)}▾")
       end
 
       # Rebuilds the dropdown's rows, highlight and geometry, opening it if

data/lib/tuile/component/slot.rb

@@ -23,7 +23,7 @@ module Tuile
     # (what {Window} does with an absent footer); never detach it.
     #
     # Transparent to input: not {Component#focusable?},
-    # {Component#handle_mouse} descends through it, and a departing occupant's
+    # the mouse routes straight through it, and a departing occupant's
     # focus repair is handed to the container.
     class Slot < Component
       include Component::HasContent
@@ -40,8 +40,8 @@ module Tuile
       # nothing to bubble from.
       # @param child [Component] the just-detached occupant.
       # @return [void]
-      def on_child_removed(child)
-        parent&.on_child_removed(child)
+      def handle_child_removed(child)
+        parent&.handle_child_removed(child)
       end
 
       protected

data/lib/tuile/component/tab_sheet.rb

@@ -26,11 +26,11 @@ module Tuile
     # designing around:
     #
     # - A hidden pane is invisible to *everything*: the Tab cycle, focus
-    #   cascades, repaint, the cursor, `on_tree` walks. No gates anywhere.
+    #   cascades, repaint, the cursor, `walk_tree` walks. No gates anywhere.
     # - Its state survives, because state is ivars — scroll position, caret,
     #   list cursor, text are all exactly as the user left them, and mutating a
     #   hidden pane is safe (`invalidate` while detached is a silent no-op).
-    # - {Component#on_detached} / {Component#on_attached} fire on every switch,
+    # - {Component#handle_detached} / {Component#handle_attached} fire on every switch,
     #   so a pane holding a mounted-lifetime resource — a {Component::ProgressBar}'s
     #   ticker — releases it while hidden and re-acquires it on return. A pane
     #   that must keep something alive while hidden can't; that something
@@ -40,7 +40,7 @@ module Tuile
     # `children` is `[strip, pane]`, the strip pinned at index 0, so pre-order
     # traversal gives the strip-then-pane Tab order for free. The swap follows
     # the slot-swap recipe {Component#detach_child} documents — detach, rewire,
-    # `on_child_removed` last, so the focus repair sees the new occupant.
+    # `handle_child_removed` last, so the focus repair sees the new occupant.
     #
     # Panes live in an identity-keyed `Tab => Component` map here rather than in
     # a slot on {Tabs::Tab}: the strip's tab array stays the sole ordering
@@ -169,7 +169,7 @@ module Tuile
       # Sends focus to the strip: a sheet is a container, and the strip is where
       # a tab switch is driven from. The pane is a Tab press away.
       # @return [void]
-      def on_focus
+      def handle_focus
         super
         screen.focused = @strip
       end
@@ -179,7 +179,7 @@ module Tuile
       # action was a tab switch.
       # @param child [Component]
       # @return [void]
-      def on_child_removed(child)
+      def handle_child_removed(child)
         super
         screen.focused = @strip if attached? && screen.focused.equal?(self)
       end
@@ -205,7 +205,7 @@ module Tuile
           layout_pane
         end
         invalidate
-        on_child_removed(old) unless old.nil?
+        handle_child_removed(old) unless old.nil?
       end
 
       # Drops entries whose tab is gone. {Tabs::Tab#remove} takes a tab off the

data/lib/tuile/component/tabs.rb

@@ -29,7 +29,7 @@ module Tuile
     #
     # {Tab} handles are minted by {#add_tab} and owned by the strip. There is no
     # `items=`: a tab is identity plus its own state, so the set grows and
-    # shrinks one tab at a time. See book ch7 and `DECISIONS.md` `D_tabs`.
+    # shrinks one tab at a time. See book ch7 and `design/decisions.md` `D_tabs`.
     #
     # == Sizing
     # Assign a {#rect} (typically from the surrounding {Layout}). One wider than
@@ -275,7 +275,7 @@ module Tuile
       #
       # Both the focus highlight and the click hit test use it, so a click on the
       # blank tail — or on a lower row, when the rect is taller than one —
-      # selects nothing. It still *focuses*: {Component#handle_mouse}'s
+      # selects nothing. It still *focuses*: {Mouse::Router}'s
       # click-to-focus is ungated by geometry.
       # @return [Size]
       def extent
@@ -291,7 +291,7 @@ module Tuile
       # bubbles to an ancestor; an empty strip handles nothing at all.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         case key
         when Keys::LEFT_ARROW then select_previous
         when Keys::RIGHT_ARROW then select_next
@@ -299,16 +299,16 @@ module Tuile
         end
       end
 
-      # Selects the tab under a left click; `super` runs first, so a click
-      # anywhere in {#rect} still focuses.
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        return unless event.button == :left
+      # Selects the tab under a left press; a press between tabs selects
+      # nothing and still claims the strip.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
         tab = tab_at(event.point)
         self.selected = tab if tab
+        true
       end
 
       # @return [void]
@@ -339,7 +339,7 @@ module Tuile
       # The rect's *width* is the only part of it the offset depends on, so this
       # hook is the whole geometry story; {Component#rect=} invalidates for us.
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         adjust_left_column
       end

data/lib/tuile/component/text_area.rb

@@ -31,7 +31,7 @@ module Tuile
     #   class PromptArea < Component::TextArea
     #     protected
     #
-    #     def handle_text_input_key(key)
+    #     def handle_text_input_key?(key)
     #       return recall_previous if key == Keys::UP_ARROW && caret_row.zero?
     #       return recall_next if key == Keys::DOWN_ARROW && caret_row == row_count - 1
     #
@@ -39,8 +39,7 @@ module Tuile
     #     end
     #   end
     #
-    # Both recalls return `true` to consume the key; app code that would rather
-    # not subclass claims the same keys through {AbstractStringField#on_key}.
+    # Both recalls return `true` to consume the key.
     #
     # == Implementation details
     #
@@ -88,11 +87,10 @@ module Tuile
         Point.new(rect.left + col.clamp(0, rect.width - 1), rect.top + row_in_viewport)
       end
 
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        return unless event.button == :left && rect.contains?(event.point)
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
         target_row = (event.y - rect.top) + @scroll_top_row
         self.caret = if target_row >= wrap.row_count
@@ -100,6 +98,7 @@ module Tuile
                      else
                        wrap.index_at(target_row, event.x - rect.left)
                      end
+        true
       end
 
       # @return [void]
@@ -108,31 +107,36 @@ module Tuile
 
         (0...rect.height).each do |row_in_viewport|
           line = wrap.row_text(row_in_viewport + @scroll_top_row)
-          screen.buffer.set_text(rect.left, rect.top + row_in_viewport, background(line))
+          draw_text(rect.left, rect.top + row_in_viewport, StyledString.plain(line))
         end
       end
 
       protected
 
       # @return [void]
-      def on_text_mutated
+      def handle_text_mutated
+        super
         @wrap = nil
         adjust_scroll_top_row
       end
 
       # @return [void]
-      def on_caret_mutated
+      def handle_caret_mutated
+        super
         adjust_scroll_top_row
       end
 
+      # HOME/END and CTRL+U act on the caret's **row** — the wrapped one, not
+      # the `\n` line — so CTRL+U kills back to exactly where HOME would go.
       # @param key [String]
       # @return [Boolean]
-      def handle_text_input_key(key)
+      def handle_text_input_key?(key)
         case key
         when Keys::UP_ARROW then move_caret_vertical(-1)
         when Keys::DOWN_ARROW then move_caret_vertical(1)
         when *Keys::HOMES then move_caret_to_row_start
         when *Keys::ENDS_ then move_caret_to_row_end
+        when Keys::CTRL_U then delete_back_to(caret_row_start)
         when *Keys::BACKSPACES then delete_before_caret
         when Keys::DELETE then delete_at_caret
         when Keys::ENTER, Keys::CTRL_J then insert_char("\n")
@@ -145,7 +149,7 @@ module Tuile
       end
 
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         @wrap = nil
         adjust_scroll_top_row
@@ -173,9 +177,12 @@ module Tuile
         self.caret = wrap.index_at(new_row, cur_col)
       end
 
+      # @return [Integer] index of the first character of the caret's row.
+      def caret_row_start = wrap.row_start(wrap.row_at(@caret))
+
       # @return [void]
       def move_caret_to_row_start
-        self.caret = wrap.row_start(wrap.row_at(@caret))
+        self.caret = caret_row_start
       end
 
       # @return [void]
@@ -183,12 +190,13 @@ module Tuile
         self.caret = wrap.row_end(wrap.row_at(@caret))
       end
 
+      # Routes a typed character (or the ENTER newline) through
+      # {AbstractStringField#insert_text}, the same mutation a paste lands on.
       # @param char [String]
-      # @return [Boolean] always true.
+      # @return [Boolean] always true — a rejected character is swallowed rather
+      #   than declined, so typing never falls through to a scope-wide binding.
       def insert_char(char)
-        new_text = @text.dup.insert(@caret, char)
-        @caret += char.length
-        self.text = new_text
+        insert_text(char)
         true
       end
 

data/lib/tuile/component/text_field.rb

@@ -12,7 +12,8 @@ module Tuile
     #   f.caret = 0                      # paints "hello " — left_column 0
     #
     # The field's width never bounds its contents — {#max_text_length} does, and
-    # only for typing.
+    # only for typing. An empty field paints its {HasPlaceholder#placeholder}
+    # instead, when it has one.
     #
     # == Implementation details
     #
@@ -21,7 +22,7 @@ module Tuile
     # - an **index** counts characters into {#text} — {#caret},
     #   {#max_text_length}, `text[i]`, every edit;
     # - a **column** counts terminal cells — {#rect}, {#cursor_position}, a
-    #   {MouseEvent}, and the private horizontal scroll offset `left_column`.
+    #   {Mouse::DownEvent}, and the private horizontal scroll offset `left_column`.
     #
     # They coincide only while every glyph is one column wide. A fullwidth CJK
     # char is two columns and a combining mark zero, so index 3 of `"日本語"` is
@@ -40,8 +41,11 @@ module Tuile
     # overriding the paint alone leaves the measurements on the buffer while the
     # cells show the substitute, and the two drift apart by a growing offset.
     class TextField < AbstractStringField
+      include HasPlaceholder
+
       def initialize
         super
+        @placeholder = nil
         @left_column = 0
         @max_text_length = nil
         @on_key_up = nil
@@ -99,32 +103,37 @@ module Tuile
         Point.new(rect.left + offset, rect.top)
       end
 
-      # Places the caret at the clicked column. A click on the right half of a
+      # Places the caret at the pressed column. A press on the right half of a
       # wide glyph lands *after* it, as in any editor.
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        return unless event.button == :left && rect.contains?(event.point)
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
         self.caret = index_at(event.x - rect.left + @left_column)
+        true
       end
 
       # @return [void]
       def repaint
         return if rect.empty?
 
-        screen.buffer.set_text(rect.left, rect.top, background(visible_text))
+        return draw_text(rect.left, rect.top, placeholder_row) if show_placeholder?
+
+        draw_text(rect.left, rect.top, StyledString.plain(visible_text))
       end
 
       protected
 
+      # CTRL+U kills back to the start of the field — with the caret at the end,
+      # "clear what I typed".
       # @param key [String]
       # @return [Boolean]
-      def handle_text_input_key(key)
+      def handle_text_input_key?(key)
         case key
         when *Keys::HOMES then self.caret = 0
         when *Keys::ENDS_ then self.caret = @text.length
+        when Keys::CTRL_U then delete_back_to(0)
         when *Keys::BACKSPACES then delete_before_caret
         when Keys::DELETE then delete_at_caret
         when Keys::UP_ARROW
@@ -147,31 +156,38 @@ module Tuile
         true
       end
 
-      # Flattens the paste onto the field's one row — newlines become spaces —
-      # and trims it to what {#max_text_length} still allows. Trimming rather
-      # than rejecting: a paste that overshoots the cap fills the field, which
-      # is what typing the same characters would have done.
+      # Keeps the paste's **first line** and drops the rest, then trims what's
+      # left to what {#max_text_length} still allows:
+      #
+      #   f.handle_paste("name\nstreet\ncity")
+      #   f.text                                 # => "name"
+      #
+      # Overshooting the cap trims rather than rejects, which is what typing the
+      # same characters would have done. Why the first line, and not a
+      # newline-to-space flattening: `D_paste_newlines`.
       # @param text [String]
       # @return [String]
       def preprocess_paste(text)
-        flat = super.tr("\n", " ")
-        return flat if @max_text_length.nil?
+        first_line = super[/\A[^\n]*/]
+        return first_line if @max_text_length.nil?
 
-        flat[0, [@max_text_length - @text.length, 0].max] || ""
+        first_line[0, [@max_text_length - @text.length, 0].max] || ""
       end
 
       # @return [void]
-      def on_text_mutated
+      def handle_text_mutated
+        super
         adjust_left_column
       end
 
       # @return [void]
-      def on_caret_mutated
+      def handle_caret_mutated
+        super
         adjust_left_column
       end
 
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         adjust_left_column
       end
@@ -186,16 +202,16 @@ module Tuile
 
       private
 
+      # Routes a typed character through {AbstractStringField#insert_text}, the
+      # same mutation a paste lands on.
       # @param char [String]
-      # @return [Boolean] always true — a field at {#max_text_length} swallows the
-      #   key rather than declining it, so typing can never fall through to a
-      #   scope-wide binding.
+      # @return [Boolean] always true — a field that is at {#max_text_length},
+      #   or that rejected the character, swallows the key rather than declining
+      #   it, so typing can never fall through to a scope-wide binding.
       def insert(char)
         return true if @max_text_length && @text.length >= @max_text_length
 
-        new_text = @text.dup.insert(@caret, char)
-        @caret += 1
-        self.text = new_text
+        insert_text(char)
         true
       end
 
@@ -221,6 +237,19 @@ module Tuile
         i
       end
 
+      # @return [Boolean] true when the empty field should paint its
+      #   {HasPlaceholder#placeholder} instead of its (blank) contents.
+      def show_placeholder? = @text.empty? && !placeholder.to_s.empty?
+
+      # {#repaint} does not call `super`, so this padded row is the only thing
+      # that clears the rect: it *is* the well.
+      # @return [StyledString] the hint, ellipsized to `rect.width` and padded
+      #   back out to it.
+      def placeholder_row
+        hint = StyledString.styled(placeholder, fg: screen.theme.placeholder_color).ellipsize(rect.width)
+        hint + StyledString.plain(" " * [rect.width - hint.display_width, 0].max)
+      end
+
       # @return [Integer] total display width of {#text}.
       def text_columns = column_at(@text.length)