tuile 0.9.0 → 0.11.0

data/lib/tuile/component/{text_input.rb → abstract_string_field.rb}

@@ -2,13 +2,33 @@
 
 module Tuile
   class Component
-    # Abstract base for editable text components ({TextField}, {TextArea}).
+    # Abstract base for the **String-valued** editable text components
+    # ({TextField}, {TextArea}): a field whose {HasValue#value} *is* its text.
+    # A field whose value is a different type (an `Integer`, a domain object)
+    # *composes* one of these rather than subclassing it — subclassing would
+    # drag this String-typed `text`/`value` seam onto its face alongside the
+    # real typed one.
     #
     # Holds the shared state — a mutable {#text} buffer, a {#caret} index,
     # {#on_change} and {#on_escape} callbacks — and the keyboard machinery
     # that single-line and multi-line inputs both need: ESC handling,
     # LEFT/RIGHT caret movement, CTRL+LEFT/CTRL+RIGHT word jumps, and the
-    # `focusable?`/`tab_stop?` flags.
+    # `tab_stop?` flag (`focusable?` comes from {HasValue}).
+    #
+    # {#caret} counts *characters* into {#text} but may only sit *between*
+    # grapheme clusters — the glyphs a terminal draws. Both write sites snap it
+    # forward onto the enclosing cluster's end, and every edit steps by a whole
+    # cluster:
+    #
+    #   f.text  = "e\u{0301}x"   # a decomposed e-acute then "x": 3 chars, 2 glyphs
+    #   f.caret = 1              # into the middle of the e-acute …
+    #   f.caret                  # => 2, its end — where the caret already drew
+    #   f.handle_key(Keys::BACKSPACE)
+    #   f.text                   # => "x": the whole glyph went, not its accent
+    #
+    # Insertion stays character-native, so `String#insert` merges a typed
+    # combining mark into its base; {#text=}'s snap covers the case where that
+    # re-segments the text around the caret.
     #
     # Subclasses implement the layout-specific pieces ({#cursor_position},
     # {#repaint}) and add their own keys (HOME/END, ENTER, UP/DOWN,
@@ -25,12 +45,15 @@ module Tuile
     # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
-    class TextInput < Component
+    class AbstractStringField < Component
+      include HasValue
+
       def initialize
         super
         @text = +""
         @caret = 0
         @on_change = nil
+        @on_value_change = nil
         @on_key = nil
         @on_escape = method(:default_on_escape)
       end
@@ -38,10 +61,24 @@ module Tuile
       # @return [String] current text contents.
       attr_reader :text
 
-      # @return [Boolean] true iff {#text} is the empty string.
-      def empty? = @text.empty?
+      # A text component's value *is* its text: {#value}/{#value=} are the
+      # {HasValue} seam over the same buffer as {#text}/{#text=}, so a form can
+      # drive it alongside typed fields. `text` stays the text-native name.
+      # @return [String]
+      def value = text
 
-      # @return [Integer] caret index in `0..text.length`.
+      # @param new_value [String, #to_s]
+      # @return [void]
+      def value=(new_value)
+        self.text = new_value.to_s
+      end
+
+      # `""` (not `nil`): a text field is empty when its buffer is blank.
+      # @return [String]
+      def empty_value = ""
+
+      # @return [Integer] caret index in `0..text.length`, counting characters
+      #   and always on a grapheme-cluster boundary (see the class doc).
       attr_reader :caret
 
       # Optional callback fired whenever {#text} changes. Receives the new text
@@ -72,30 +109,32 @@ module Tuile
       # @return [Proc, Method, nil] no-arg callable, or nil.
       attr_accessor :on_escape
 
-      def focusable? = true
-
       def tab_stop? = true
 
       # Sets the text. Runs {#preprocess_text} first (subclasses may filter or
-      # truncate). Caret is clamped to the new text length. Fires {#on_change}
-      # only on a real change.
+      # truncate). Caret is clamped to the new text length, then snapped back
+      # onto a cluster boundary of the *new* text. Fires {#on_change} only on a
+      # real change.
       # @param new_text [String]
       def text=(new_text)
         new_text = preprocess_text(new_text)
         return if @text == new_text
 
         @text = +new_text
-        @caret = @caret.clamp(0, @text.length)
+        @caret = snap_to_cluster(@caret.clamp(0, @text.length))
         on_text_mutated
         invalidate
         @on_change&.call(@text)
+        on_value_change&.call(@text)
       end
 
-      # Sets the caret position. Clamped to `0..text.length`. Fires
-      # {#on_caret_mutated} hook for subclasses (e.g. {TextArea} scrolls).
+      # Clamps to `0..text.length`, then snaps forward onto a grapheme-cluster
+      # boundary, so an index that fell inside a cluster reads back as that
+      # cluster's end. Fires the {#on_caret_mutated} hook for subclasses (e.g.
+      # {TextArea} scrolls).
       # @param new_caret [Integer]
       def caret=(new_caret)
-        new_caret = new_caret.clamp(0, @text.length)
+        new_caret = snap_to_cluster(new_caret.clamp(0, @text.length))
         return if @caret == new_caret
 
         @caret = new_caret
@@ -134,6 +173,15 @@ module Tuile
       # @return [String] possibly transformed text.
       def preprocess_text(new_text) = new_text.to_s
 
+      # The one measurement primitive both inputs share: a caret index counts
+      # characters, but every rect, cursor and click counts columns, and only
+      # this converts between them.
+      # @param str [String]
+      # @return [Integer] `str`'s width in terminal columns, measured per
+      #   grapheme cluster — so a combining mark adds nothing and a fullwidth
+      #   glyph adds two.
+      def columns_of(str) = str.each_grapheme_cluster.sum { |g| Buffer.display_width(g) }
+
       # Hook called after {#text} has been mutated, before invalidation /
       # {#on_change}. Default no-op. Subclasses use this to invalidate caches
       # ({TextArea}'s wrap cache) and update derived state.
@@ -148,7 +196,8 @@ module Tuile
 
       # Dispatch hook for {#handle_key}. Handles ESC and the navigation keys
       # that have identical semantics in single-line and multi-line inputs:
-      # LEFT/RIGHT arrows, CTRL+LEFT/CTRL+RIGHT for word jumps. Subclasses
+      # LEFT/RIGHT arrows (one grapheme cluster per press, so a press always
+      # moves), CTRL+LEFT/CTRL+RIGHT for word jumps. Subclasses
       # override to add their own keys (HOME/END, UP/DOWN, ENTER, BACKSPACE/
       # DELETE, printable insertion) and call `super` to fall back to the
       # common navigation handling.
@@ -156,8 +205,8 @@ module Tuile
       # @return [Boolean] true if the key was handled.
       def handle_text_input_key(key)
         case key
-        when Keys::LEFT_ARROW then self.caret = @caret - 1
-        when Keys::RIGHT_ARROW then self.caret = @caret + 1
+        when Keys::LEFT_ARROW then self.caret = cluster_boundary_before(@caret)
+        when Keys::RIGHT_ARROW then self.caret = cluster_boundary_after(@caret)
         when Keys::CTRL_LEFT_ARROW then self.caret = word_left
         when Keys::CTRL_RIGHT_ARROW then self.caret = word_right
         when Keys::ESC
@@ -170,27 +219,71 @@ module Tuile
         true
       end
 
+      # Removes the whole grapheme cluster before the caret — one press, one
+      # glyph, whatever it is built from (a ZWJ emoji family and a three-jamo
+      # Hangul syllable each go whole).
       # @return [void]
       def delete_before_caret
         return if @caret.zero?
 
+        start = cluster_boundary_before(@caret)
         new_text = @text.dup
-        new_text.slice!(@caret - 1)
-        @caret -= 1
+        new_text.slice!(start...@caret)
+        @caret = start
         self.text = new_text
       end
 
+      # Removes the whole grapheme cluster at the caret.
       # @return [void]
       def delete_at_caret
         return if @caret >= @text.length
 
         new_text = @text.dup
-        new_text.slice!(@caret)
+        new_text.slice!(@caret...cluster_boundary_after(@caret))
         self.text = new_text
       end
 
       private
 
+      # @param index [Integer] a {#text} index in `0..text.length`.
+      # @return [Integer] the smallest grapheme-cluster boundary `>= index`.
+      def snap_to_cluster(index)
+        offset = 0
+        @text.each_grapheme_cluster do |g|
+          return offset if offset >= index
+
+          offset += g.length
+        end
+        offset
+      end
+
+      # @param index [Integer]
+      # @return [Integer] the greatest grapheme-cluster boundary `< index`, or
+      #   0 at the start of the text.
+      def cluster_boundary_before(index)
+        last = 0
+        offset = 0
+        @text.each_grapheme_cluster do |g|
+          offset += g.length
+          return last if offset >= index
+
+          last = offset
+        end
+        last
+      end
+
+      # @param index [Integer]
+      # @return [Integer] the smallest grapheme-cluster boundary `> index`, or
+      #   `text.length` at the end of the text.
+      def cluster_boundary_after(index)
+        offset = 0
+        @text.each_grapheme_cluster do |g|
+          offset += g.length
+          return offset if offset > index
+        end
+        offset
+      end
+
       # Default {#on_escape} action: clear focus. Component deactivates; user
       # can re-focus by clicking or tabbing back in.
       # @return [void]

data/lib/tuile/component/big_decimal_field.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+# The gem's one *optional* dependency, deliberately absent from the gemspec so
+# that only an app naming this component pays for it. Zeitwerk loads this file
+# on the first reference to {Tuile::Component::BigDecimalField} and not before.
+begin
+  require "bigdecimal"
+rescue LoadError
+  raise LoadError, "Tuile::Component::BigDecimalField needs the bigdecimal gem. Add `gem \"bigdecimal\"` " \
+                   "to your Gemfile — since Ruby 3.4 it is a bundled gem, so Bundler no longer puts it " \
+                   "on the load path for free."
+end
+
+module Tuile
+  class Component
+    # A single-line field whose {#value} is a `BigDecimal` (or `nil` when
+    # empty) — the numeric field for money, where {FloatField}'s binary double
+    # would round. Give it a single-row {#rect}:
+    #
+    #   price = Component::BigDecimalField.new
+    #   price.on_value_change = ->(d) { total.value = d }   # BigDecimal or nil
+    #   price.value = BigDecimal("19.99")                   # field shows "19.99"
+    #   price.value = 19.99                                 # ArgumentError: a Float can't be exact
+    #
+    # Only `0`–`9`, one leading `-` and one `.` can be typed; any other
+    # printable key is dropped without moving the caret. Up/Down step by one.
+    # Range checks (`min`/`max`) and a display scale (`19.9` → `19.90`) belong
+    # to a forms layer, not here — nothing rounds or pads what you typed.
+    #
+    # Requires the `bigdecimal` gem, which Tuile does *not* depend on: it is a
+    # bundled gem from Ruby 3.4 on, so a `Gemfile` naming it is what puts it on
+    # the load path. Referencing this class without it raises `LoadError`.
+    #
+    # == Implementation details
+    # {#value} is a *derived parse*: the buffer is the single source of truth,
+    # recomputed on read and left exactly as typed (`"19.90"` keeps its zero,
+    # which `BigDecimal#to_s` would not). It reads `nil` for a buffer that
+    # isn't a number (`""`, a lone `"-"`) but `1` / `0.5` for a half-typed
+    # `"1."` / `".5"`, so reaching for the decimal point doesn't blink the
+    # value to `nil` and back through {#on_value_change} — which fires per
+    # keystroke, but only on a real *value* change (`"1.0"`→`"1.00"` is silent,
+    # since the two compare equal).
+    #
+    # Both ends of that round-trip are written here rather than left to the
+    # library, because `bigdecimal` 3.1 (Ruby 3.3's default gem) and 4.x
+    # disagree about them: 3.1 rejects `BigDecimal("1.")` and `BigDecimal(0.1)`
+    # where 4.x accepts both. So the buffer is normalized before parsing, a
+    # `Float` is refused on both, and display goes through `to_s("F")` — plain
+    # notation, never `BigDecimal#to_s`'s `"0.1999e2"`.
+    #
+    # It *composes* a {TextField} (its single {HasContent} child) rather than
+    # subclassing one, so its face carries only the typed {HasValue} seam,
+    # never the widget's `String`-typed `text`.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class BigDecimalField < Component
+      include HasContent
+      include HasValue
+
+      # A buffer {#value} parses: an optional sign and digits with an optional
+      # fractional part (either side may be empty, but not both). No exponent —
+      # `to_s("F")` never writes one and no key types an `e`.
+      # @return [Regexp]
+      NUMERIC = /\A-?(?:\d+(?:\.\d*)?|\.\d+)\z/
+      private_constant :NUMERIC
+
+      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 [::BigDecimal, nil] the parsed buffer; `nil` when empty or not a
+      #   number (e.g. a lone `"-"`).
+      def value
+        text = content.text
+        text.match?(NUMERIC) ? BigDecimal(normalize(text)) : nil
+      end
+
+      # Writes `new_value` into the buffer in plain notation and parks the
+      # caret at its end; fires {#on_value_change} only if the value actually
+      # changed.
+      # @param new_value [::BigDecimal, Integer, String, nil] `nil` empties the
+      #   field. A `Float` is refused, not converted — see the raise.
+      # @raise [ArgumentError] on a `Float` (its binary value is not the
+      #   decimal you wrote, which is the whole reason to use this field), a
+      #   non-numeric `String`, a NaN or an infinity.
+      # @raise [TypeError] on a value `BigDecimal()` won't take at all.
+      # @return [void]
+      def value=(new_value)
+        content.text = new_value.nil? ? "" : coerce(new_value).to_s("F")
+        content.caret = content.text.length
+      end
+
+      # `nil`, not `""`: a numeric 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
+
+      # Rewrites the half-typed shapes {NUMERIC} admits into ones every
+      # `bigdecimal` version parses: `".5"` → `"0.5"`, `"1."` → `"1"`.
+      # @param text [String] a buffer matching {NUMERIC}.
+      # @return [String]
+      def normalize(text)
+        text = text.sub(".", "0.") if text.start_with?(".", "-.")
+        text.chomp(".")
+      end
+
+      # @param new_value [::BigDecimal, Integer, String]
+      # @return [::BigDecimal]
+      # @raise [ArgumentError] on a `Float` — `bigdecimal` 4.x would take it
+      #   and 3.1 would not, and neither answer is the one a money field wants
+      #   to give silently. Also on a NaN or an infinity: `to_s("F")` writes
+      #   `"NaN"`, which no parse reads back, so writing one would silently
+      #   turn the value `nil`.
+      def coerce(new_value)
+        if new_value.is_a?(Float)
+          raise ArgumentError, "a Float is not exact — pass BigDecimal(#{new_value.to_s.inspect}) or the String"
+        end
+
+        big = BigDecimal(new_value)
+        raise ArgumentError, "value must be finite, got #{big}" unless big.finite?
+
+        big
+      end
+
+      # The field's key interceptor, consulted *before* the field acts on the
+      # key — which is what lets a rejected character be swallowed without the
+      # caret ever moving.
+      # @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
+      # zero.
+      # @param delta [Integer]
+      # @return [void]
+      def step(delta) = (self.value = (value || BigDecimal(0)) + delta)
+
+      # Whether `char` may be inserted. Deliberately shallow: it keeps the
+      # buffer *typeable* rather than always-valid — a transient `"-"` or
+      # `"1."` has to be reachable — and {#value} decides what parses.
+      # @param char [String] a single printable character.
+      # @return [Boolean]
+      def accepts?(char)
+        case char
+        when /\A[0-9]\z/ then true
+        when "-" then content.caret.zero? && !content.text.start_with?("-")
+        when "." then !content.text.include?(".")
+        else false
+        end
+      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 (`"1.0"`→`"1.00"`) 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/button.rb

@@ -12,34 +12,26 @@ module Tuile
     # {Component#handle_mouse}.
     #
     # Assign a {#rect} (typically by the surrounding {Layout}) wide enough to
-    # show `[ caption ]` — that natural width is `caption.length + 4`.
+    # show `[ caption ]` — that natural width is `caption.display_width + 4`.
+    # A narrower {#rect} truncates the label with an ellipsis; a wider one leaves
+    # a tail that focuses but doesn't activate (see {#extent}).
     class Button < Component
-      # @param caption [String] the button's label.
+      include Component::HasCaption
+
+      # @param caption [String, StyledString, nil] the button's label, coerced
+      #   the same way {HasCaption#caption=} coerces it.
       # @yield optional `on_click` callback; same as assigning {#on_click=}.
-      def initialize(caption = "", &on_click)
+      def initialize(caption = nil, &on_click)
         super()
-        @caption = caption.to_s
+        self.caption = caption
         @on_click = on_click
       end
 
-      # @return [String] the button's label.
-      attr_reader :caption
-
       # Callback fired when the button is activated (Enter, Space, or
       # left-click). The callable receives no arguments.
       # @return [Proc, Method, nil] no-arg callable, or nil.
       attr_accessor :on_click
 
-      # Sets a new caption and invalidates the button. No-op if unchanged.
-      # @param new_caption [String]
-      def caption=(new_caption)
-        new_caption = new_caption.to_s
-        return if @caption == new_caption
-
-        @caption = new_caption
-        invalidate
-      end
-
       def focusable? = true
 
       def tab_stop? = true
@@ -56,11 +48,23 @@ module Tuile
         end
       end
 
+      # The cells the button actually paints: one row, `caption.display_width + 4`
+      # columns, clipped to {#rect}. Both the focus highlight and the click hit
+      # test use it, so a click on the blank tail of an over-wide rect — or on a
+      # lower row, when the rect is taller than one — does not fire {#on_click}.
+      # It still *focuses*: {Component#handle_mouse}'s click-to-focus is ungated
+      # by geometry. Same rule as {Checkbox#extent}, which documents the two
+      # traps behind it.
+      # @return [Rect]
+      def extent = Rect.new(rect.left, rect.top, [caption.display_width + 4, rect.width].min, 1)
+
+      # Fires {#on_click} on a left click within {#extent}; `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 && rect.contains?(event.point)
+        return unless event.button == :left && extent.contains?(event.point)
 
         @on_click&.call
       end
@@ -70,9 +74,9 @@ module Tuile
         super
         return if rect.empty?
 
-        label = "[ #{@caption} ]"[0, rect.width]
-        styled = active? ? StyledString.styled(label, bg: screen.theme.active_bg_color) : StyledString.plain(label)
-        screen.buffer.set_line(rect.left, rect.top, styled)
+        label = (StyledString.plain("[ ") + caption + StyledString.plain(" ]")).ellipsize(rect.width)
+        label = label.with_bg(screen.theme.active_bg_color) if active?
+        draw_line(rect.left, rect.top, label)
       end
     end
   end

data/lib/tuile/component/checkbox.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A boolean input on one row. Space, Enter or a left click toggles it:
+    #
+    #   [x] Enable syslog forwarding
+    #   [ ] Enable syslog forwarding
+    #
+    #   cb = Component::Checkbox.new("Enable syslog forwarding", value: true)
+    #   cb.on_value_change = ->(on) { config.syslog = on }
+    #   cb.toggle       # unchecks it, firing the listener with false
+    #   cb.checked?     # => false
+    #
+    # {#value} is the canonical seam ({HasValue}), always `true`/`false` and
+    # never `nil`; {#checked?} / {#checked=} / {#toggle} are the domain-word face
+    # over it — one piece of state, four names. Unchecked is the
+    # {#empty_value}, so a fresh checkbox is {HasValue#empty? empty} and
+    # {HasValue#clear} unchecks.
+    #
+    # Space and Enter both toggle — same as a checkable row in a
+    # {Component::List} ({CheckboxGroup}, {RadioGroup}), so the gesture reads the
+    # same standalone and grouped. A focused checkbox therefore *consumes* Enter:
+    # a form's Enter-to-submit on an ancestor won't see it, exactly as with a
+    # focused {Button} or {TextArea}. Which widget lets Enter through is per
+    # widget, never a framework guarantee — book ch5's Enter table is the list.
+    #
+    # A tab stop, so Tab lands on it, and the widget highlights while on the focus
+    # chain. Assign a {#rect} (typically from the surrounding {Layout}) at least
+    # `caption.display_width + 4` wide; a narrower one ellipsizes the caption, a
+    # wider one leaves a dead tail — see {#extent}.
+    #
+    # == Implementation details
+    # The glyphs are a house convention rather than constants: three columns plus
+    # a trailing space (`[x] `, `[ ] `), ASCII because `☑`/`☐` are absent from
+    # most monospace fonts and the fallback glyph bleeds over its cell. A widget
+    # painting checkbox-like rows without instantiating a Checkbox — checkable
+    # rows in a {Component::List} — repeats those literals to match.
+    class Checkbox < Component
+      include Component::HasValue
+      include Component::HasCaption
+
+      # @param caption [String, StyledString, nil] the label, coerced as
+      #   {HasCaption#caption=} coerces it.
+      # @param value [Boolean] initial state. Assigned through {#value=}, which
+      #   also seeds the backing ivar — an unseeded checkbox would read `nil` and
+      #   so report itself non-{HasValue#empty? empty} while fresh.
+      def initialize(caption = nil, value: false)
+        super()
+        self.caption = caption
+        self.value = value
+      end
+
+      def tab_stop? = true
+
+      # @return [Boolean] `false` — {HasValue#empty?} means unchecked.
+      def empty_value = false
+
+      # Coerces to `true`/`false` before storing, so the two-state invariant holds
+      # whatever a caller assigns — and `cb.value = nil` on a fresh checkbox is
+      # the no-op it looks like rather than a spurious change event.
+      # @param new_value [Object] anything; truthiness decides.
+      # @return [void]
+      def value=(new_value)
+        super(new_value ? true : false)
+      end
+
+      # @return [Boolean] {#value} under its domain word — `license.checked?`
+      #   reads better than `license.value`. Not a second piece of state.
+      def checked? = value
+
+      # {#value=} under its domain word. A delegator rather than an `alias`, so it
+      # keeps routing through the one write path even if a subclass overrides
+      # {#value=} (an `alias` would freeze this onto the body defined here).
+      # @param new_value [Object] anything; truthiness decides.
+      # @return [void]
+      def checked=(new_value)
+        self.value = new_value
+      end
+
+      # Flips {#value}.
+      # @return [void]
+      def toggle = (self.value = !value)
+
+      # The cells the widget actually paints: one row, `caption.display_width + 4`
+      # columns, clipped to {#rect}. A form column routinely hands a checkbox a
+      # 40-column rect for a 22-column `[ ] Enable syslog forwarding` — the extent
+      # is those 22 columns.
+      #
+      # 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 — does
+      # not toggle. It still *focuses*: {Component#handle_mouse}'s click-to-focus
+      # is ungated by geometry, and the tail is the field's own row.
+      #
+      # The extent ignores {Component#bg_color}: an inherited tint paints the dead
+      # tail, but a hit test that silently widened with a background would be a
+      # mode switch invisible in the code and untestable by inspection.
+      # @return [Rect]
+      def extent = Rect.new(rect.left, rect.top, [caption.display_width + 4, rect.width].min, 1)
+
+      # Toggles on Space or Enter. Every other key is left unhandled so it bubbles
+      # to an ancestor.
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return false unless [" ", Keys::ENTER].include?(key)
+
+        toggle
+        true
+      end
+
+      # Toggles on a left click within {#extent}; `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 && extent.contains?(event.point)
+
+        toggle
+      end
+
+      # @return [void]
+      def repaint
+        super
+        return if rect.empty?
+
+        label = (StyledString.plain(value ? "[x] " : "[ ] ") + caption).ellipsize(rect.width)
+        label = label.with_bg(screen.theme.active_bg_color) if active?
+        draw_line(rect.left, rect.top, label)
+      end
+    end
+  end
+end