tuile 0.8.0 → 0.10.0

data/lib/tuile/component/popup.rb

@@ -4,18 +4,25 @@ module Tuile
   class Component
     # An overlay that wraps any {Component} as its content. Popup itself
     # paints nothing — it's a transparent host that handles its lifecycle
-    # ({#open} / {#close} / {#open?}, ESC/q to close) and auto-sizes to the
-    # wrapped content.
+    # ({#open} / {#close} / {#open?}, ESC/q to close) and holds a top-down
+    # {#size} the {Screen} applies.
+    #
+    # The popup does *not* size itself to its content. Its box is declared by
+    # {#size} — a {Fraction} (resolved against the screen every layout pass, so
+    # it tracks resize) or an absolute {Size} (clamped to the screen). The
+    # default is {Fraction::HALF}: half the screen, centered. The wrapped
+    # content then fills that box and handles its own overflow by wrapping and
+    # scrolling, so use content that can — a {Component::TextView} or
+    # {Component::TextArea} — for anything longer than fits. A
+    # {Component::Label} only truncates.
     #
     # Modal by default: it centers on the screen, grabs focus, eats keys, and
     # blocks clicks beneath it. Pass `modal: false` for a non-modal overlay
-    # that floats above the content (still painted on top, still auto-sized)
-    # without taking focus or capturing input — the caller positions it (via
-    # {#rect=}) and drives it from app code. That is the building block for an
-    # autocomplete/slash-command list anchored to a {Component::TextField} or
-    # {Component::TextArea} caret: typing keeps focus (and the cursor) in the
-    # input, an {Component::TextInput#on_change} listener refills the list, and
-    # an {Component::TextInput#on_key} interceptor forwards Up/Down/Enter to it.
+    # that floats above the content without taking focus or capturing input —
+    # the caller positions it (via {#rect=}), sizes it, and drives it from app
+    # code. That's the building block for an autocomplete/slash-command list
+    # anchored to a text field's caret: typing keeps focus in the input while
+    # the caller refills and drives the overlay.
     #
     # The wrapped content fills the popup's full {#rect}; if you want a frame
     # and caption, wrap a {Component::Window} (or any subclass — including
@@ -28,30 +35,52 @@ module Tuile
     # Bare content also works (a {Component::Label}, a {Component::List}…), in
     # which case the popup is borderless.
     #
-    # `q` and ESC close the popup. Any nested {Component::TextField} that owns
-    # the hardware cursor swallows printable keys first via the standard
-    # cursor-owner suppression in {Component#handle_key}, so typing `q` into a
-    # text field doesn't dismiss the popup.
+    # `q` and ESC close the popup — handled here, at the top of the popup's own
+    # subtree, so the key only arrives after every component on the focus chain
+    # declined it (see {ScreenPane#handle_key}). That's why typing `q` into a
+    # nested {Component::TextField} doesn't dismiss the popup: the field
+    # consumes it first.
     class Popup < Component
       include Component::HasContent
 
       # @param content [Component, nil] initial content; can be set later via
-      #   {#content=}. When provided here, the popup auto-sizes to fit.
+      #   {#content=}. The content fills the popup's {#rect}; it does not
+      #   determine the popup's size.
       # @param modal [Boolean] true (default) for a centered, focus-grabbing,
       #   input-capturing modal; false for a non-modal overlay the caller
       #   positions and drives (see the class docs).
-      def initialize(content: nil, modal: true)
+      # @param size [Size, Fraction] the popup's size, applied top-down. A
+      #   {Fraction} is resolved against the screen each layout pass; a {Size}
+      #   is clamped to the screen. Defaults to {Fraction::HALF}.
+      def initialize(content: nil, modal: true, size: Fraction::HALF)
         super()
         @modal = modal
+        @size = size
         @content = nil
         self.content = content unless content.nil?
+        reposition
       end
 
+      # @return [Size, Fraction] the popup's declared size. See {#size=}.
+      attr_reader :size
+
       # @return [Boolean] whether this popup is modal. See {#initialize}.
       def modal? = @modal
 
       def focusable? = true
 
+      # Sets the popup's size and repositions it. Accepts a {Fraction}
+      # (resolved against the screen every layout pass, so it tracks resize) or
+      # an absolute {Size} (clamped to the screen). This is **authoritative**,
+      # not a preference: the screen applies exactly what you ask for (clamped),
+      # with no negotiation — a popup has no siblings to compete with.
+      # @param new_size [Size, Fraction]
+      # @return [void]
+      def size=(new_size)
+        @size = new_size
+        reposition
+      end
+
       # Reassigns the popup's rect, escalating to a full scene repaint when an
       # open popup shrinks or moves so its new rect no longer covers the cells
       # it previously painted. A popup overdraws the scene without clipping and
@@ -67,20 +96,21 @@ module Tuile
         screen.needs_full_repaint if open? && !new_rect.contains_rect?(old_rect)
       end
 
-      # Mounts this popup on the {Screen}. Recomputes the popup's size from
-      # the current content first, so reopening a popup whose content has
-      # grown or shrunk while closed picks up the new size.
+      # Mounts this popup on the {Screen}, re-resolving its {#size} against the
+      # current screen first.
       # @return [void]
       def open
-        update_rect unless @content.nil?
+        reposition
         screen.add_popup(self)
       end
 
       # Constructs and opens a popup in one call.
       # @param content [Component, nil]
+      # @param modal [Boolean] see {#initialize}.
+      # @param size [Size, Fraction] see {#initialize}.
       # @return [Popup] the opened popup.
-      def self.open(content: nil)
-        Popup.new(content: content).tap(&:open)
+      def self.open(content: nil, modal: true, size: Fraction::HALF)
+        Popup.new(content: content, modal: modal, size: size).tap(&:open)
       end
 
       # Removes this popup from the {Screen}. No-op if not currently open.
@@ -94,44 +124,29 @@ module Tuile
         screen.has_popup?(self)
       end
 
-      # Recenters the popup on the screen, preserving its current width/height.
-      # Called automatically by the screen's layout pass and by {#content=}
-      # when the popup is open.
+      # Re-resolves {#size} against the current screen and repositions the popup
+      # *itself* (this is not laying out content — the popup's own rect): a
+      # modal popup recenters; a non-modal overlay keeps its caller-assigned
+      # top-left (only its size follows the screen). Called on {#open}, on
+      # {#size=}, and by the screen's layout pass (so a {Fraction} size tracks
+      # SIGWINCH).
+      #
+      # The final rect is computed and assigned in one step rather than sizing
+      # at the origin and then centering: the intermediate origin rect rarely
+      # covers the previous one, which would make {#rect=}'s shrink/move
+      # detection fire a full repaint on every resize.
       # @return [void]
-      def center
-        self.rect = rect.centered(screen.size)
-      end
-
-      # @return [Integer] max height the popup will grow to fit its content.
-      #   Defers to the content's {Component#popup_max_height} advice when it
-      #   gives one, else defaults to 12. Override in a subclass to allow
-      #   taller popups regardless of content.
-      def max_height = @content&.popup_max_height || 12
-
-      # @return [Integer] min height the popup occupies even when its content
-      #   is shorter. Defers to the content's {Component#popup_min_height}
-      #   advice when it gives one, else defaults to 0 (size purely to
-      #   content) — so a {Component::LogWindow} stays readable while only a
-      #   few lines are in without callers wiring up a subclass. Override in a
-      #   subclass to keep any popup from collapsing to a couple of rows.
-      #   Capped at the same 4/5-of-screen ceiling {#update_rect} applies.
-      def min_height = @content&.popup_min_height || 0
-
-      # Sets the popup's content and auto-sizes the popup to fit.
-      # @param new_content [Component, nil]
-      def content=(new_content)
-        super
-        update_rect unless new_content.nil?
+      def reposition
+        size = @size.is_a?(Fraction) ? @size.resolve(screen.size) : @size.clamp(screen.size)
+        r = Rect.new(rect.left, rect.top, size.width, size.height)
+        r = r.centered(screen.size) if modal?
+        self.rect = r
       end
 
-      # Re-sizes (and recenters, when open) whenever the wrapped content's
-      # natural size changes — e.g. a {Label}'s `text=`, a {List}'s
-      # `add_line`, or a nested {Window} whose own content grew (the window
-      # recomputes its {Component#content_size} and the change bubbles here).
-      # @param _child [Component]
+      # Recenters the popup on the screen, preserving its current width/height.
       # @return [void]
-      def on_child_content_size_changed(_child)
-        update_rect
+      def center
+        self.rect = rect.centered(screen.size)
       end
 
       # Hint for the status bar: own "q Close" plus the wrapped content's hint.
@@ -164,30 +179,6 @@ module Tuile
       def layout(content)
         content.rect = rect
       end
-
-      private
-
-      # Recompute width/height from {#content}'s natural size and recenter
-      # if currently open. Called whenever content is (re)assigned.
-      #
-      # Computes the final (centered) rect and assigns it in one step rather
-      # than positioning at the origin and then centering: the intermediate
-      # origin rect rarely covers the previous one, which would make
-      # {#rect=}'s shrink/move detection fire a full repaint on every resize.
-      # @return [void]
-      def update_rect
-        ceiling = screen.size.height * 4 / 5
-        size = @content.content_size.clamp_height(max_height)
-        size = size.clamp(Size.new(screen.size.width * 4 / 5, ceiling))
-        floor = min_height.clamp(0, ceiling)
-        size = Size.new(size.width, floor) if size.height < floor
-        # A non-modal overlay is positioned by the caller, so an open one keeps
-        # its current top-left when its content resizes; a modal popup recenters.
-        origin = open? && !modal? ? Point.new(rect.left, rect.top) : Point.new(0, 0)
-        r = Rect.new(origin.x, origin.y, size.width, size.height)
-        r = r.centered(screen.size) if open? && modal?
-        self.rect = r
-      end
     end
   end
 end

data/lib/tuile/component/progress_bar.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A one-row progress bar: a run of `█` growing left to right across {#rect},
+    # over a `░` track.
+    #
+    #   ████████░░░░░░░░░░░░
+    #
+    #   bar   = Component::ProgressBar.new(range: 0..files.size)
+    #   label = Component::Label.new
+    #   add(bar)
+    #   add(label)
+    #
+    #   def rect=(new_rect)             # the enclosing Layout positions both
+    #     super
+    #     bar.rect   = Rect.new(rect.left, rect.top, rect.width, 1)
+    #     label.rect = Rect.new(rect.left, rect.top + 1, rect.width, 1)
+    #   end
+    #
+    #   bar.value  = done
+    #   label.text = "#{bar.percent}% — #{done}/#{files.size}"
+    #
+    # The bar paints no text of its own: put a {Label} beside it and feed it
+    # {#percent} or {#fraction}, so the app words it ("42% — 3/7 files") and
+    # places it freely. Display-only — not focusable, no keys, no mouse.
+    #
+    # While the total is still unknown, {#indeterminate=} swaps the fill for a
+    # block sliding across the bar:
+    #
+    #   ░░░░░░░████░░░░░░░░░
+    #
+    # Both endpoints are exact: the bar is full only at {#max} and empty only at
+    # {#min}, so a full bar always means done. Assign a one-row {#rect}; a taller
+    # one paints the bar on its first row and leaves the rest to the background.
+    #
+    # == Implementation details
+    # 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
+    # beats a third convention, and if that bet is ever reversed both swap
+    # together.
+    class ProgressBar < Component
+      # Range covering the whole bar when none is given.
+      # @return [Range]
+      DEFAULT_RANGE = (0.0..1.0)
+
+      # Frames per second of the indeterminate animation. The block advances one
+      # cell per frame, so this is also its speed in cells/second.
+      # @return [Integer]
+      INDETERMINATE_FPS = 5
+
+      # The indeterminate block is this fraction of the bar, at least one cell.
+      # @return [Integer]
+      BLOCK_DIVISOR = 5
+
+      # @param range [Range] initial {#range=}.
+      # @param value [Numeric, nil] initial {#value=}; `nil` starts at the range's
+      #   lower bound.
+      # @param indeterminate [Boolean] initial {#indeterminate=}.
+      def initialize(range: DEFAULT_RANGE, value: nil, indeterminate: false)
+        super()
+        @value = 0.0
+        @min = 0.0
+        @max = 1.0
+        @phase = 0
+        @ticker = nil
+        @indeterminate = false
+        @bar_color = nil
+        self.range = range
+        self.value = value unless value.nil?
+        self.indeterminate = indeterminate
+      end
+
+      # @return [Float] lower bound of {#range}.
+      attr_reader :min
+
+      # @return [Float] upper bound of {#range}.
+      attr_reader :max
+
+      # @return [Color, nil] the value as set, so a {Theme::Ref} comes back
+      #   unresolved. Both glyphs paint in it; `nil` (the default) is the
+      #   terminal's default foreground.
+      attr_reader :bar_color
+
+      # @return [Range] the scale {#value} is measured against.
+      def range = @min..@max
+
+      # Replaces the scale, re-clamping {#value} into it. `min == max` is legal
+      # and reads as complete — a zero-length job has nothing outstanding — so
+      # `bar.range = 0..files.size` needs no special case for an empty list.
+      #
+      # @param new_range [Range] inclusive; endpoints Numeric and finite.
+      # @return [void]
+      # @raise [ArgumentError] on an exclusive, inverted or non-finite range, or
+      #   an endpoint `Float()` cannot parse.
+      # @raise [TypeError] on a beginless or endless range — its `nil` endpoint
+      #   is what `Float()` refuses — or any other type it refuses outright.
+      def range=(new_range)
+        raise ArgumentError, "range must be inclusive, got #{new_range.inspect}" if new_range.exclude_end?
+
+        min = Float(new_range.begin)
+        max = Float(new_range.end)
+        raise ArgumentError, "range end #{max} is below its start #{min}" if max < min
+
+        unless min.finite? && max.finite?
+          raise ArgumentError, "range endpoints must be finite (use indeterminate = true)"
+        end
+
+        @min = min
+        @max = max
+        self.value = @value
+        invalidate # the scale moved even when the clamped value did not
+      end
+
+      # @return [Float] the progress, clamped into {#range} when assigned — so
+      #   `bar.value = 999` on a `0..250` bar reads back as `250.0`.
+      attr_reader :value
+
+      # @param new_value [Numeric] clamped into {#range}.
+      # @return [void]
+      # @raise [ArgumentError] on NaN — typically `done.to_f / total` with a zero
+      #   total, which wants {#indeterminate=} instead — or on a String `Float()`
+      #   cannot parse.
+      # @raise [TypeError] on `nil` and other types `Float()` refuses outright.
+      def value=(new_value)
+        new_value = Float(new_value)
+        raise ArgumentError, "value must be a number, got NaN" if new_value.nan?
+
+        new_value = new_value.clamp(@min, @max)
+        return if @value == new_value
+
+        @value = new_value
+        invalidate
+      end
+
+      # @return [Float] {#value} as `0.0..1.0`. `1.0` when the range is empty.
+      def fraction
+        return 1.0 if @max == @min
+
+        (@value - @min) / (@max - @min)
+      end
+
+      # @return [Integer] {#fraction} as `0..100`, floored — `100` means done and
+      #   nothing else does, matching the painted bar exactly.
+      def percent = scale(100)
+
+      # 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).
+      #
+      #   bar.bar_color = Color::GREEN
+      #   bar.bar_color = Theme.ref(:brand_ok)   # an app #custom token
+      #
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      #   coerced via {Color.coerce} unless it is a {Theme::Ref}; `nil` is the
+      #   terminal default.
+      # @return [void]
+      # @raise [KeyError] when a {Theme::Ref} names a token the current theme
+      #   lacks.
+      def bar_color=(color)
+        color = Color.coerce(color) unless color.is_a?(Theme::Ref)
+        return if @bar_color == color
+
+        color.resolve(screen.theme) if color.is_a?(Theme::Ref) # fail fast on a bad token
+
+        @bar_color = color
+        invalidate
+      end
+
+      # @return [Boolean] whether the sliding-block animation is showing.
+      def indeterminate? = @indeterminate
+
+      # Switches between the fill and the sliding block. {#value} keeps working
+      # while indeterminate — it is simply not painted — so switching back shows
+      # the progress that accumulated meanwhile.
+      #
+      # The animation only runs while the bar is {Component#attached? attached},
+      # and stops on detach. It also keeps the event loop awake at
+      # {INDETERMINATE_FPS}, so turn it off (or remove the bar) when the job ends.
+      #
+      # @param flag [Boolean] coerced; truthiness decides.
+      # @return [void]
+      def indeterminate=(flag)
+        flag = flag ? true : false
+        return if @indeterminate == flag
+
+        @indeterminate = flag
+        sync_ticker
+        invalidate # the picture changes now, not on the next frame
+      end
+
+      # @return [void]
+      def on_attached = sync_ticker
+
+      # @return [void]
+      def on_detached = sync_ticker
+
+      # Paints the bar on the first row of {#rect} and blanks the rest.
+      #
+      # Deliberately not `super`: {Component#repaint}'s default blanks the
+      # *whole* rect, which dirties every cell of the bar's own row before it is
+      # painted over — so {Buffer#flush} re-emits the entire row every frame
+      # instead of the one or two cells that actually moved.
+      # @return [void]
+      def repaint
+        return if rect.empty?
+
+        draw_line(rect.left, rect.top, StyledString.styled(glyphs(rect.width), fg: resolved_bar_color))
+        clear_background(Rect.new(rect.left, rect.top + 1, rect.width, rect.height - 1)) if rect.height > 1
+      end
+
+      private
+
+      # Filled cells out of `steps` — the rect width when painting, 100 for
+      # {#percent}, so the bar and a {Label} showing the percentage can never
+      # disagree about being done.
+      # @param steps [Integer]
+      # @return [Integer]
+      def scale(steps)
+        return 0 if fraction <= 0.0
+        return steps if fraction >= 1.0
+        return 0 if steps < 2 # no interior to land in; fills only when done
+
+        (fraction * steps).floor.clamp(1, steps - 1)
+      end
+
+      # @param width [Integer] columns available.
+      # @return [String] the row, `width` glyphs wide.
+      def glyphs(width)
+        start, length = @indeterminate ? block_at(width) : [0, scale(width)]
+        [("░" * start), ("█" * length), ("░" * (width - start - length))].join
+      end
+
+      # Where the sliding block sits this frame: it enters at the left edge and
+      # leaves at the right, one cell per frame, then loops. The period is one
+      # short of `width + block` so at least one cell is always lit — a full
+      # `width + block` blanks the bar for exactly one frame per cycle.
+      # @param width [Integer] columns available.
+      # @return [Array(Integer, Integer)] start column and length, clipped.
+      def block_at(width)
+        block = [width / BLOCK_DIVISOR, 1].max
+        start = (@phase % (width + block - 1)) - (block - 1)
+        first = [start, 0].max
+        last = [start + block, width].min
+        [first, last - first]
+      end
+
+      # @return [Color, nil]
+      def resolved_bar_color
+        @bar_color.is_a?(Theme::Ref) ? @bar_color.resolve(screen.theme) : @bar_color
+      end
+
+      # Brings the ticker in line with "animating and on screen". The sole writer
+      # of `@ticker`, and idempotent, so the attach/detach hooks and
+      # {#indeterminate=} are all the same call and a repeated `indeterminate =
+      # true` cannot start a second one.
+      # @return [void]
+      def sync_ticker
+        want = attached? && @indeterminate
+        return if want == !@ticker.nil?
+
+        if want
+          @ticker = screen.event_queue.tick_fps(INDETERMINATE_FPS) do |tick|
+            # The paint that already happened is frame 0; a ticker's first
+            # firing is one interval later, so it is frame 1.
+            @phase = tick + 1
+            invalidate
+          end
+        else
+          @ticker.cancel
+          @ticker = nil
+        end
+      end
+    end
+  end
+end

data/lib/tuile/component/radio_group.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # Single-select from a set of typed items, one row each. Arrows move a
+    # cursor; Space, Enter or a left click selects the row under it:
+    #
+    #    (*) Ascending
+    #    ( ) Descending    <- cursor row, highlighted across the full width
+    #    ( ) Unsorted
+    #   ^ the composed {List}'s one-column gutter
+    #
+    #   rg = Component::RadioGroup.new(items: %w[Ascending Descending Unsorted])
+    #   rg.value = "Descending"                      # or seed it via the ctor
+    #   rg.on_value_change = ->(order) { resort(order) }
+    #   rg.value                                     # => "Descending"
+    #   rg.item_label = ->(o) { o.title }            # default :to_s
+    #
+    # {#value} is **the selected item itself** — of whatever type {#items}
+    # holds, never its label. `nil` means nothing is selected: that is the
+    # initial state, and assigning it is the only way back, since Space on the
+    # already-selected row is a no-op rather than a deselect.
+    #
+    # Composes rather than subclasses, like {ComboBox}: a {List} is its single
+    # {HasContent} child, which is where the cursor, scrolling, the scrollbar
+    # and per-row mouse hit-testing come from. `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.
+    #
+    # == The cursor is chrome
+    # The cursor and the selection are two independent things, as in
+    # {CheckboxGroup} — arrows roam without changing {#value}, so a listener
+    # that resorts a pane fires once on intent instead of once per row crossed.
+    # {#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))
+    #
+    # {#items=} is the one thing that moves it, clamping it back into range.
+    #
+    # == +items+ is chrome; +value+ is authoritative
+    # {#items=} changes only what is *presented*. It never touches {#value} and
+    # never fires {HasValue#on_value_change}, and a selected item absent from
+    # {#items} renders no marked row while surviving intact — so a form saved
+    # without the user editing anything changes nothing silently. Keeping the
+    # two in sync is the app's job. Same contract as {ComboBox#value} and
+    # {CheckboxGroup#value}.
+    #
+    # == Implementation details
+    # Two `==`-equal items share one selection, so selecting either marks both
+    # rows; two *distinct* items that merely render the same label stay
+    # independent, because a row resolves to an item by index.
+    #
+    # Rows are `(*) `/`( ) ` literals, mirroring {Checkbox}'s convention rather
+    # than importing constants from it. ASCII deliberately: `(•)` would measure
+    # two columns in a terminal configured for East-Asian-Ambiguous glyphs and
+    # shift every row's text, which no test would catch.
+    #
+    # 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
+      #   via {#items=}.
+      # @param value [Object, nil] the initially selected item. Seeds the
+      #   backing ivar directly, so no listener fires and assignment order
+      #   doesn't matter to a form helper.
+      def initialize(items: [], value: nil)
+        super()
+        @items = items.to_a
+        @item_label = :to_s.to_proc
+        @value = value
+        @on_value_change = nil
+
+        list = List.new
+        # A List has no cursor at all by default (Cursor::None, position -1).
+        list.cursor = List::Cursor.new
+        list.on_item_chosen = ->(index, _line) { select_at(index) }
+        self.content = list
+        rebuild_rows
+      end
+
+      # @return [Array] the presented items.
+      attr_reader :items
+
+      # @return [Proc, Method] item -> row label (a `String`, {StyledString}, or
+      #   anything with `#to_s`); `:to_s` by default.
+      attr_reader :item_label
+
+      # Replaces the presented rows, leaving {#value} untouched and clamping the
+      # cursor back into range.
+      # @param new_items [Array]
+      # @raise [TypeError] unless `new_items` is an `Array`.
+      # @return [void]
+      def items=(new_items)
+        raise TypeError, "expected Array, got #{new_items.inspect}" unless new_items.is_a?(Array)
+
+        @items = new_items
+        # Before the rebuild, so the single {List#on_cursor_changed} that
+        # {List#lines=} fires reports the final row rather than a stale one.
+        clamp_cursor
+        rebuild_rows
+      end
+
+      # @param proc [Proc, Method] item -> row label.
+      # @return [void]
+      def item_label=(proc)
+        @item_label = proc
+        rebuild_rows
+      end
+
+      # Selects `new_value`, firing {HasValue#on_value_change} when it really
+      # changed. The cursor stays where it is.
+      # @param new_value [Object, nil] `nil` selects nothing; an item outside
+      #   {#items} is kept but renders no marked row.
+      # @return [void]
+      def value=(new_value)
+        # HasValue#value= no-ops on an unchanged value; this guard is what also
+        # skips the row rebuild.
+        return if value == new_value
+
+        super
+        rebuild_rows
+      end
+
+      # Selects the cursor row on Space. Nothing else is claimed: the composed
+      # {List} — being the focused component — has already had its chance at the
+      # key (its arrows, Home/End, PgUp/PgDn, ^U/^D and Enter), and whatever
+      # neither of us wants bubbles on to an ancestor.
+      # @param key [String]
+      # @return [Boolean]
+      def handle_key(key)
+        return false unless key == " "
+
+        select_at(content.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.
+      # @param index [Integer]
+      # @return [void]
+      def select_at(index)
+        return unless index.between?(0, @items.size - 1)
+
+        self.value = @items[index]
+      end
+
+      # Re-renders every row from the current items, labels and selection.
+      # @return [void]
+      def rebuild_rows
+        content.lines = @items.map do |item|
+          StyledString.plain(item == value ? "(*) " : "( ) ") + label_for(item)
+        end
+      end
+
+      # Pulls an over-range cursor back onto the last row (row 0 when there are
+      # none). {List#lines=} leaves a stale cursor alone, which would strand it
+      # off-content: no highlight, a dead Enter, and a Space that resolves to
+      # `nil` and silently clears the selection.
+      # @return [void]
+      def clamp_cursor
+        cursor = content.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(@items.size) if cursor.position >= @items.size
+      end
+
+      # @param item [Object]
+      # @return [StyledString, String] whichever {StyledString#+} accepts on the
+      #   right — so a styled label keeps its spans and a plain one is parsed.
+      def label_for(item)
+        label = @item_label.call(item)
+        label.is_a?(StyledString) ? label : label.to_s
+      end
+    end
+  end
+end