tuile 0.8.0 → 0.10.0

data/lib/tuile/component/has_value.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # The value seam every input component shares: a settable/gettable {#value}
+    # of *any* type, an {#on_value_change} listener, {#empty?}, and {#clear}. A
+    # form (a future binder) drives a mix of field types uniformly through it,
+    # not caring that a {TextField}'s value is a `String` while another field's
+    # is a domain object.
+    #
+    #   field.on_value_change = ->(v) { puts "now: #{v.inspect}" }
+    #   field.value = "hello"   # fires the listener
+    #   field.clear             # value = empty_value, fires again
+    #
+    # The default {#value=}/{#value} keep the value in `@value` and are enough
+    # for a component with nothing more natural — you get a repaint and the
+    # listener for free. An includer whose value lives elsewhere overrides both
+    # ({AbstractStringField} backs them with its text buffer). Override {#empty_value}
+    # when the empty sentinel isn't `nil` (a text field's is `""`).
+    #
+    # == Implementation details
+    # Deliberately smaller than Vaadin's `HasValue`: read-only,
+    # required-indicator, the from-client/old-value event payload, and
+    # converters all belong to the not-yet-built form layer, not here.
+    module HasValue
+      # @return [Proc, Method, nil] one-arg callable fired with the new value
+      #   whenever {#value} actually changes — never on a no-op set.
+      attr_accessor :on_value_change
+
+      # @return [Object] the current value; `nil` until first set.
+      def value = @value
+
+      # No-op (no repaint, no listener) when equal to the current value.
+      # @param new_value [Object]
+      # @return [void]
+      def value=(new_value)
+        return if value == new_value
+
+        @value = new_value
+        invalidate
+        on_value_change&.call(new_value)
+      end
+
+      # @return [Boolean] true iff {#value} equals {#empty_value}.
+      def empty? = value == empty_value
+
+      # Resets {#value} to {#empty_value}.
+      # @return [void]
+      def clear = (self.value = empty_value)
+
+      # @return [Object] the value {#empty?}/{#clear} treat as empty; `nil`
+      #   unless an includer overrides it.
+      def empty_value = nil
+
+      # Input fields are focusable by default (overrides {Component#focusable?});
+      # a read-only display field could override back to `false`. Only
+      # `focusable?` lives here — `tab_stop?` diverges between leaf fields and
+      # composing wrappers, so it stays per-class (`DECISIONS.md`
+      # `D-integer-field`).
+      # @return [Boolean]
+      def focusable? = true
+    end
+  end
+end

data/lib/tuile/component/info_window.rb

@@ -21,9 +21,11 @@ module Tuile
       # Opens the info window as a popup.
       # @param caption [String]
       # @param lines [Array<String>] the content, may contain formatting.
+      # @param size [Size, Fraction] the popup's size, applied top-down; the
+      #   list wraps and scrolls within it. Defaults to {Fraction::HALF}.
       # @return [Popup] the opened popup.
-      def self.open(caption, lines)
-        Popup.open(content: InfoWindow.new(caption, lines))
+      def self.open(caption, lines, size: Fraction::HALF)
+        Popup.open(content: InfoWindow.new(caption, lines), size: size)
       end
     end
   end

data/lib/tuile/component/integer_field.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A single-line field whose {#value} is an `Integer` (or `nil` when empty).
+    # The user may type only `0`–`9` and a single leading `-`; anything else is
+    # silently rejected without moving the caret. Up/Down step the value by one
+    # (an empty field counting as `0`). An empty or otherwise un-parseable
+    # buffer reads back as `nil`:
+    #
+    #   field = Component::IntegerField.new
+    #   field.on_value_change = ->(n) { puts n.inspect }  # Integer or nil, per change
+    #   field.value = 42                                   # field shows "42"
+    #   field.value                                        # => 42
+    #   field.clear                                        # empties it; value => nil
+    #
+    # Like {ComboBox}, it *composes* a {TextField} (its single {HasContent}
+    # child) rather than subclassing one — its face carries only the typed
+    # {HasValue} value seam, never the widget's `String`-typed `text`. It's the
+    # same wrapper shape as {ComboBox} minus the dropdown: a digit-filtered text
+    # field re-exposed as a typed input. Give it a single-row {#rect}.
+    #
+    # == The value is a *derived parse* of the buffer
+    # {#value} is `Integer(buffer, 10)` (or `nil`), recomputed on read — the
+    # buffer is the single source of truth, {#value=} just writes it. So `"-"`
+    # alone and `""` both read as `nil`, and `on_value_change` fires eagerly
+    # once per real *value* change: typing `0`→`7` in `"07"` shifts the buffer
+    # but not the value (`7`), so it does not fire. No normalization — a typed
+    # `"007"` stays `"007"` on screen though its value is `7`.
+    #
+    # `min`/`max`, a `+` sign, and thousands separators are deliberately out of
+    # scope (range and formatting are a forms concern).
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class IntegerField < Component
+      include HasContent
+      include HasValue
+
+      def initialize
+        super()
+        @last_value = nil
+        field = TextField.new
+        field.on_change = ->(_text) { fire_if_changed }
+        field.on_key = method(:field_key)
+        self.content = field
+      end
+
+      # @return [Integer, nil] the parsed buffer; `nil` when empty or not a
+      #   valid integer (e.g. a lone `"-"`).
+      def value
+        Integer(content.text, 10)
+      rescue ArgumentError
+        nil
+      end
+
+      # Writes `new_value` into the buffer and parks the caret at its end; fires
+      # {#on_value_change} only if the value actually changed.
+      # @param new_value [Integer, nil] `nil` empties the field.
+      # @return [void]
+      def value=(new_value)
+        content.text = new_value.nil? ? "" : new_value.to_s
+        content.caret = content.text.length
+      end
+
+      # `nil`, not `""`: an integer field with no parseable number is empty.
+      # @return [nil]
+      def empty_value = nil
+
+      # @return [Point, nil] the field's caret (the hardware cursor is delegated
+      #   to the inner field).
+      def cursor_position = content.cursor_position
+
+      # Fired when ENTER is pressed in the field; see {TextField#on_enter}.
+      # @return [Proc, Method, nil] no-arg callable, or nil.
+      def on_enter = content.on_enter
+
+      # @param callback [Proc, Method, nil]
+      # @return [void]
+      def on_enter=(callback)
+        content.on_enter = callback
+      end
+
+      protected
+
+      # Places the wrapped field across the whole rect ({HasContent} hook).
+      # @param field [Component]
+      # @return [void]
+      def layout(field) = (field.rect = rect)
+
+      private
+
+      # The field's key interceptor, consulted *before* the field acts on the
+      # key: Up/Down step the value; a printable key the field mustn't accept is
+      # swallowed (so a rejected key never moves the caret); everything else —
+      # digits, the leading sign, and all editing/navigation keys — falls
+      # through.
+      # @param key [String]
+      # @return [Boolean] true to consume the key.
+      def field_key(key)
+        case key
+        when Keys::UP_ARROW then step(1)
+        when Keys::DOWN_ARROW then step(-1)
+        else return Keys.printable?(key) && !accepts?(key)
+        end
+        true
+      end
+
+      # Nudges {#value} by `delta`, treating an empty/un-parseable field as `0`.
+      # @param delta [Integer]
+      # @return [void]
+      def step(delta) = (self.value = (value || 0) + delta)
+
+      # A digit anywhere, or a `-` only as the very first character.
+      # @param char [String] a single printable character.
+      # @return [Boolean]
+      def accepts?(char)
+        return true if char.match?(/\A[0-9]\z/)
+
+        char == "-" && content.caret.zero? && !content.text.start_with?("-")
+      end
+
+      # Re-emits {#on_value_change} with the freshly-parsed {#value}, but only
+      # when it differs from the last one fired — so a buffer edit that leaves
+      # the value unchanged (`"7"`→`"07"`) stays silent.
+      # @return [void]
+      def fire_if_changed
+        v = value
+        return if v == @last_value
+
+        @last_value = v
+        on_value_change&.call(v)
+      end
+    end
+  end
+end

data/lib/tuile/component/label.rb

@@ -8,21 +8,28 @@ module Tuile
     # embedded ANSI is honored) or a {StyledString} directly. {#text}
     # always returns the {StyledString}.
     class Label < Component
-      def initialize
-        super
+      # @param text [String, StyledString, nil] initial text, coerced the same
+      #   way {#text=} coerces it (a `String` is parsed via
+      #   {StyledString.parse}; `nil` is an empty label). Equivalent to
+      #   constructing empty and assigning {#text=}.
+      def initialize(text = nil)
+        super()
         @text = StyledString::EMPTY
         @bg = nil
         @clipped_lines = []
         @blank_line = ""
+        self.text = text unless text.nil?
       end
 
       # @return [StyledString] the current text. Defaults to an empty
       #   {StyledString}.
       attr_reader :text
 
-      # @return [Color, nil] background color applied uniformly across every
-      #   painted row (including padding past the text). `nil` (default)
-      #   leaves whatever bg the text's own styling carries.
+      # @return [Color, nil] a local background laid over *every* span and the
+      #   row padding (via {StyledString#with_bg}), overriding the text's own
+      #   span bgs — stronger than the inherited {#bg_color}. `nil` (default)
+      #   keeps each span's bg and lets the inherited {#effective_bg_color}
+      #   fill the rest.
       attr_reader :bg
 
       # Replaces the text. A `String` is parsed via {StyledString.parse}
@@ -38,14 +45,13 @@ module Tuile
         @text = new_text
         update_clipped_lines
         invalidate
-        self.content_size = compute_content_size
       end
 
-      # Sets the background color. Coerced via {Color.coerce}, so a Symbol,
-      # Integer, Array, {Color}, or `nil` all work. `nil` clears the override
-      # — the label paints with whatever bg the text's own styling provides.
-      # Otherwise the bg overlays every span (including the trailing pad and
-      # blank rows past the last text line).
+      # Sets a local background painted over every span and the row padding
+      # (trailing pad and blank rows included), overriding the text's own span
+      # bgs. Coerced via {Color.coerce} (Symbol, Integer, Array, {Color}, or
+      # `nil`). `nil` clears the override — spans keep their own bg and the
+      # inherited {#bg_color} fills the rest.
       #
       # @param value [Color, Symbol, Integer, Array<Integer>, nil]
       # @return [void]
@@ -63,14 +69,15 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row is
       # painted explicitly (with pre-padded blanks past the last line), so
       # the "fully draw over your rect" contract is met without an upfront
-      # wipe.
+      # wipe. Rows go through {Component#draw_line}, so the padding and blank
+      # rows inherit {Component#effective_bg_color} when {#bg} is unset.
       # @return [void]
       def repaint
         return if rect.empty?
 
         (0...rect.height).each do |row|
           line = @clipped_lines[row] || @blank_line
-          screen.buffer.set_line(rect.left, rect.top + row, line)
+          draw_line(rect.left, rect.top + row, line)
         end
       end
 
@@ -84,18 +91,6 @@ module Tuile
 
       private
 
-      # Natural size: longest hard-line's display width × number of hard
-      # lines. Computed on the *unclipped* text — sizing is intrinsic to the
-      # content, not the viewport. Empty text yields {Size::ZERO}.
-      # @return [Size]
-      def compute_content_size
-        return Size::ZERO if @text.empty?
-
-        hard_lines = @text.lines
-        width = hard_lines.map(&:display_width).max || 0
-        Size.new(width, hard_lines.size)
-      end
-
       # Recomputes {@clipped_lines} for the current text and rect width.
       # Each line is ellipsized to fit and padded with trailing spaces out to
       # the full width, so {#repaint} is just a lookup + {Buffer#set_line} per

data/lib/tuile/component/layout.rb

@@ -11,14 +11,6 @@ module Tuile
     # the background is cleared and children are re-invalidated so they
     # paint over a clean surface.
     class Layout < Component
-      def initialize
-        super
-        @children = []
-      end
-
-      # @return [Array<Component>]
-      def children = @children.to_a
-
       # Layouts are focusable containers — like {Window} and {Popup}, they
       # don't accept input themselves but they need to participate in the
       # {HasContent} focus cascade so a Popup wrapping a Layout wrapping a
@@ -36,11 +28,7 @@ module Tuile
         if child.is_a? Enumerable
           child.each { add(_1) }
         else
-          raise TypeError, "expected Component, got #{child.inspect}" unless child.is_a? Component
-          raise ArgumentError, "#{child} already has a parent #{child.parent}" unless child.parent.nil?
-
-          @children << child
-          child.parent = self
+          add_child(child)
         end
       end
 
@@ -50,19 +38,8 @@ module Tuile
         raise TypeError, "expected Component, got #{child.inspect}" unless child.is_a? Component
         raise ArgumentError, "#{child}'s parent is #{child.parent}, not this layout #{self}" if child.parent != self
 
-        child.parent = nil
-        @children.delete(child)
-        invalidate if @children.empty?
-        on_child_removed(child)
-      end
-
-      # @return [Size]
-      def content_size
-        return Size::ZERO if @children.empty?
-
-        right  = @children.map { |c| c.rect.left + c.rect.width  }.max
-        bottom = @children.map { |c| c.rect.top  + c.rect.height }.max
-        Size.new(right - rect.left, bottom - rect.top)
+        remove_child(child)
+        invalidate if @children.empty? # nothing left to paint over the gap
       end
 
       # Dispatches the event to the child under the mouse cursor.

data/lib/tuile/component/list.rb

@@ -6,11 +6,9 @@ module Tuile
     #
     # Items are modeled as {StyledString}s and painted directly into the
     # component's {#rect}. Lines wider than the viewport are ellipsized via
-    # {StyledString#ellipsize} (span styles are preserved across the cut —
-    # unlike the older ANSI-as-bytes truncation, color does *not* get
-    # dropped on the surviving characters). Vertical scrolling is supported
-    # via {#top_line}; the list can also automatically scroll to the bottom
-    # if {#auto_scroll} is enabled.
+    # {StyledString#ellipsize} with span styles preserved across the cut.
+    # Vertical scrolling is via {#top_line}; enable {#auto_scroll} to keep the
+    # bottom in view.
     #
     # Cursor is supported; call {#cursor=} to change cursor behavior. The
     # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the
@@ -147,7 +145,6 @@ module Tuile
         update_top_line_if_auto_scroll
         notify_cursor_changed
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Without a block, returns the current lines. With a block, fully
@@ -194,7 +191,6 @@ module Tuile
         update_top_line_if_auto_scroll
         notify_cursor_changed
         invalidate
-        grow_content_size(new_lines)
       end
 
       def focusable? = true
@@ -274,7 +270,10 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row of
       # {#rect} is painted below (with blank padding past the last item),
       # so the parent contract — "fully draw over your rect" — is met
-      # without an upfront wipe.
+      # without an upfront wipe. Rows go through {Component#draw_line}, so
+      # content *and* blank filler inherit {Component#effective_bg_color}
+      # (a {#bg_color} set here or on an ancestor); the cursor row's
+      # {Theme#active_bg_color} highlight composes on top of it.
       # @return [void]
       def repaint
         return if rect.empty?
@@ -284,7 +283,7 @@ module Tuile
                     end
         (0...rect.height).each do |row|
           line = paintable_line(row + @top_line, row, scrollbar)
-          screen.buffer.set_line(rect.left, row + rect.top, line)
+          draw_line(rect.left, row + rect.top, line)
         end
       end
 
@@ -508,30 +507,6 @@ module Tuile
 
       private
 
-      # Natural size from scratch: longest line's display width plus the two
-      # single-space gutters {#pad_to_row} adds, × line count. An empty list
-      # is {Size::ZERO} (no gutters for no content).
-      # @return [Size]
-      def compute_content_size
-        content_w = @lines.map(&:display_width).max || 0
-        width = @lines.empty? ? 0 : content_w + 2
-        Size.new(width, @lines.size)
-      end
-
-      # Incremental {#content_size} update for appends: folds just the
-      # appended lines into the running maximum, keeping {#add_lines}
-      # O(appended) instead of re-scanning the whole list (LogWindow appends
-      # a line per log statement).
-      # @param appended [Array<StyledString>] the just-appended lines
-      #   (already concatenated onto {@lines}).
-      # @return [void]
-      def grow_content_size(appended)
-        return if appended.empty?
-
-        appended_w = appended.map(&:display_width).max + 2
-        self.content_size = Size.new([content_size.width, appended_w].max, @lines.size)
-      end
-
       # Coerces and flattens a list of input entries into trimmed
       # {StyledString} lines. Each entry becomes a {StyledString} (String
       # via {StyledString.parse}, StyledString passed through, anything else

data/lib/tuile/component/list_dropdown.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A borderless, tinted, non-focusable floating selection list — the dropdown
+    # a text input drops open, drives by forwarding movement keys, and commits a
+    # pick from: a non-modal {Popup} wrapping a {List} that never takes focus, so
+    # the caret stays in the driving input while the caller refills the rows,
+    # moves the highlight, and reads the pick.
+    #
+    #   drop = Component::ListDropdown.new
+    #   drop.on_item_chosen = ->(index, _line) { commit(index) } # caller commits
+    #   # …then, per keystroke in the driving input's key handler:
+    #   drop.lines = matches.map { |m| render(m) }  # caller filters + renders
+    #   drop.rect  = Rect.new(...)                   # caller anchors + sizes it
+    #   drop.open
+    #   return true if drop.move(key)  # Up/Down/PgUp/PgDn/^U/^D → list scroll
+    #   drop.choose if key == Keys::ENTER            # commit the highlight
+    #
+    # It owns only what every such dropdown shares; everything that varies stays
+    # with the driver: geometry/anchoring, filtering, row rendering, the commit
+    # action, and ESC/Enter handling. ESC and Enter carry driver-specific tails
+    # (ESC may revert a query; Enter may commit via {#choose} *or* via a separate
+    # submit path), so {#move} claims neither — the driver calls {#choose} and
+    # {#close} from its own branches.
+    #
+    # == Theming
+    # Borderless, told apart from the content beneath by a background tint —
+    # {Theme#input_bg_color} by default, assigned as a live {Theme::Ref} so it
+    # tracks light/dark flips with no hook. Reassign {Component#bg_color=} for a
+    # different tint (a `Theme.ref(:token)` keeps the flip-tracking).
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class ListDropdown < Popup
+      # The dropdown's {List}. Non-focusable on purpose: the driver forwards keys
+      # while focus (and the caret) stay in its input, and a mouse click selects
+      # an item without stealing focus — so the input never loses the cursor
+      # mid-interaction.
+      class Menu < List
+        def focusable? = false
+        def tab_stop? = false
+      end
+
+      # Cursor-movement keys forwarded to the list by {#move}: the two vertical
+      # arrows, page up/down, and Ctrl+U/D half-page jumps. Deliberately excludes
+      # Home/End and `j`/`k` (they belong to the driving field — caret movement
+      # and typing) and Enter/ESC (they carry driver-specific tails — see the
+      # class docs).
+      # @return [Array<String>]
+      MOVE_KEYS = [Keys::UP_ARROW, Keys::DOWN_ARROW, Keys::PAGE_UP, Keys::PAGE_DOWN,
+                   Keys::CTRL_U, Keys::CTRL_D].freeze
+
+      def initialize
+        @list = Menu.new
+        @list.cursor = List::Cursor.new
+        @list.show_cursor_when_inactive = true # highlight the selection though focus stays in the input
+        super(content: @list, modal: false)
+        self.bg_color = Theme.ref(:input_bg_color)
+      end
+
+      # @param lines [Array] the rows to show; see {List#lines=}.
+      # @return [void]
+      def lines=(lines)
+        @list.lines = lines
+      end
+
+      # @return [Array<StyledString>] the current rows.
+      def lines = @list.lines
+
+      # @param proc [Proc, Method, nil] commit callback; see {List#on_item_chosen}.
+      # @return [void]
+      def on_item_chosen=(proc)
+        @list.on_item_chosen = proc
+      end
+
+      # @param cursor [List::Cursor] the highlight; see {List#cursor=}.
+      # @return [void]
+      def cursor=(cursor)
+        @list.cursor = cursor
+      end
+
+      # @return [List::Cursor] the list's cursor (the current highlight).
+      def cursor = @list.cursor
+
+      # Forwards a cursor-movement key to the list. The driver calls this from
+      # its own key handler; a truthy return means "consumed — stop here", falsy
+      # means "not mine — proceed with normal editing/dispatch". Only {MOVE_KEYS}
+      # are claimed, and only while open.
+      # @param key [String]
+      # @return [Boolean] true iff the key was consumed.
+      def move(key)
+        return false unless open? && MOVE_KEYS.include?(key)
+
+        @list.handle_key(key)
+        true
+      end
+
+      # Commits the highlighted row by firing {List#on_item_chosen}, exactly as
+      # pressing Enter on the focused list would — the driver calls this from its
+      # own Enter branch.
+      # @return [Boolean] true iff a row was chosen (false when the cursor is
+      #   off-content).
+      def choose = @list.handle_key(Keys::ENTER)
+    end
+  end
+end

data/lib/tuile/component/log_window.rb

@@ -24,20 +24,6 @@ module Tuile
         self.scrollbar = true
       end
 
-      # Keep the log pane at least half the screen tall even when only a few
-      # lines have been logged: a {Component::Popup} sizes to its content, which
-      # would collapse a near-empty log to two or three rows. Advice consulted
-      # by {Component::Popup#min_height} when this window is a popup's content.
-      # @return [Integer]
-      def popup_min_height = screen.size.height / 2
-
-      # Let a busy log grow past the popup's base 12-row cap (up to the
-      # 4/5-of-screen ceiling {Component::Popup#update_rect} applies) so the
-      # diagnostic stream stays scrollable in a tall window. Advice consulted
-      # by {Component::Popup#max_height} when this window is a popup's content.
-      # @return [Integer]
-      def popup_max_height = screen.size.height
-
       # Appends given line to the log. Can be called from any thread. Does nothing if nil is passed in.
       # @param string [String, nil] the line (or multiple lines) to log.
       # @return [void]

data/lib/tuile/component/password_field.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A {TextField} that paints one mask glyph per character instead of the
+    # text. Editing, caret, clicks and horizontal scrolling are the field's,
+    # unchanged:
+    #
+    #   pf = Component::PasswordField.new
+    #   pf.rect  = Rect.new(0, 0, 20, 1)
+    #   pf.value                          # => the plaintext String
+    #   pf.mask_char = "•"                # default "*"
+    #   pf.revealed  = true               # show the plaintext, e.g. behind a Checkbox
+    #
+    # A password's value *is* its text, so this subclasses {TextField} rather
+    # than composing one the way {IntegerField} does — the delta is presentation
+    # only, and it lands entirely on {TextField#display_text}.
+    #
+    # == What it hides, and what it doesn't
+    # The plaintext is an ordinary Ruby `String`: not pinned, not wiped, not
+    # kept out of GC. Anything stronger needs a frozen-buffer type and the
+    # cooperation of every consumer, which is out of scope for a widget.
+    #
+    # The mask shows the text's *length* — accepted, since a caret has to sit
+    # somewhere. Its *word structure* is hidden: CTRL+LEFT / CTRL+RIGHT jump to
+    # the ends while masked instead of hopping the spaces a watcher could then
+    # read off the caret. They resume word-jumping when {#revealed}.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class PasswordField < TextField
+      def initialize
+        super
+        @mask_char = "*"
+        @revealed = false
+      end
+
+      # @return [String] the glyph painted per character; `"*"` by default.
+      attr_reader :mask_char
+
+      # The default is `"*"` rather than a prettier `"•"` because U+2022 is
+      # East-Asian-*Ambiguous*: a CJK-configured terminal draws it two columns
+      # wide, shifting every column past the caret. Validation can't catch that
+      # one — Tuile measures Ambiguous as 1 by construction — so the default
+      # carries it, and this setter is the knob for someone who knows their
+      # terminal.
+      # @param char [String] one grapheme cluster, one column wide.
+      # @return [void]
+      # @raise [TypeError] unless `char` is a String.
+      # @raise [ArgumentError] if `char` isn't exactly one single-column
+      #   grapheme cluster — a multi-cluster mask would break the
+      #   one-glyph-per-character contract {TextField#display_text} rests on,
+      #   a wide one the column axis.
+      def mask_char=(char)
+        raise TypeError, "expected String, got #{char.inspect}" unless char.is_a?(String)
+        raise ArgumentError, "expected one grapheme cluster, got #{char.inspect}" unless single_cluster?(char)
+        raise ArgumentError, "expected a 1-column glyph, got #{char.inspect}" unless Buffer.display_width(char) == 1
+
+        return if @mask_char == char
+
+        @mask_char = char
+        invalidate
+      end
+
+      # @return [Boolean] whether the plaintext is shown; `false` by default.
+      attr_reader :revealed
+
+      # @return [Boolean] {#revealed} in predicate form.
+      def revealed? = @revealed
+
+      # Shows or re-masks the plaintext. There is no built-in reveal *button* —
+      # a TTY field has no room for an in-field affordance — so an app flips
+      # this from a key binding or a sibling {Checkbox}.
+      # @param flag [Object] anything; truthiness decides.
+      # @return [void]
+      def revealed=(flag)
+        flag = flag ? true : false
+        return if @revealed == flag
+
+        @revealed = flag
+        # The plaintext and the mask differ in *columns* (a CJK passphrase is
+        # wider than its mask), so the scroll window has to be recomputed —
+        # the caret index it must keep visible has not moved.
+        adjust_left_column
+        invalidate
+      end
+
+      protected
+
+      # @return [String] the mask, one glyph per character, unless {#revealed}.
+      def display_text = revealed? ? super : @mask_char * @text.length
+
+      private
+
+      # @param char [String]
+      # @return [Boolean]
+      def single_cluster?(char) = char.each_grapheme_cluster.take(2).size == 1
+
+      # @return [Integer] caret target for CTRL+LEFT: the start, while masked.
+      def word_left = revealed? ? super : 0
+
+      # @return [Integer] caret target for CTRL+RIGHT: the end, while masked.
+      def word_right = revealed? ? super : @text.length
+    end
+  end
+end