tuile 0.11.0 → 0.13.0

data/lib/tuile/component/notification.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A transient message in the screen's top-right corner — the TTY toast:
+    #
+    #   Component::Notification.show("Saved")
+    #   Component::Notification.show("Disk full", color: Theme.ref(:error))
+    #
+    #   ┌─────────┐  ← flush: row 0, right edge at the last column
+    #   │Saved    │  ← oldest on top, retires in 3 s
+    #   │Disk full│  ← then this one, 3 s after that
+    #   └─────────┘
+    #
+    # {show} is the only entry point ({new} is private): it finds the live
+    # notification and appends to it, so a burst stacks as entries in one box
+    # instead of opening five overlapping ones.
+    #
+    # One repeating ticker retires the **oldest** entry every {DISPLAY_SECONDS}
+    # and closes the box when the last one goes — five messages raised together
+    # appear at once and drain over fifteen seconds. A message arriving mid-cycle
+    # waits its turn and does *not* restart the clock, so the bottom entry of a
+    # full box is visible for about `N × DISPLAY_SECONDS`. Past {MAX_MESSAGES} a
+    # message is dropped and reported to {Tuile.logger}; an app notifying faster
+    # than that wants a {Component::LogWindow}.
+    #
+    # The box is flush to the corner, at most {WIDTH_FRACTION} of the screen wide
+    # (floor {MIN_CAP_WIDTH}) and {HEIGHT_FRACTION} tall, and **grows but never
+    # shrinks** while it lives; a long message wraps to {MAX_ROWS_PER_MESSAGE}
+    # rows and is then ellipsized, and entries past the height cap wait unpainted.
+    # `DECISIONS.md` `D-notification` has why each of those is what it is.
+    #
+    # Three things it deliberately doesn't do:
+    #
+    # - **Take focus, or receive keys.** A non-modal popup sits off the
+    #   key-dispatch scope ({ScreenPane#handle_key}), so not even {Popup}'s
+    #   `q`/ESC arrives here. A left click *on the box* dismisses
+    #   ({#handle_mouse}); an app wanting a key registers a global shortcut and
+    #   calls {#close}. A click *elsewhere* does not — this is the one popup
+    #   with {Popup#close_on_outside_click?} false, since a toast is timed and
+    #   an unrelated click is not about it.
+    # - **Follow a theme flip.** A `Theme::Ref` `color:` is resolved once, when
+    #   the message is added — a toast lives seconds, so there is no
+    #   {Component#on_theme_changed} rebuild.
+    # - **Take a size.** {#size=} raises; the messages decide.
+    class Notification < Popup
+      # Most messages held at once, counting both the painted ones and any
+      # waiting for room. Chosen from reading time rather than geometry: the
+      # drain rate is one message per {DISPLAY_SECONDS}, so the queue length *is*
+      # a duration, and 5 × 3 s is about the longest a corner box should own the
+      # screen — and about as many short lines as anyone reads.
+      # @return [Integer]
+      MAX_MESSAGES = 5
+
+      # Rows a single message may occupy before it is ellipsized.
+      # @return [Integer]
+      MAX_ROWS_PER_MESSAGE = 3
+
+      # Seconds between retirements — how long the oldest message is held.
+      # @return [Float]
+      DISPLAY_SECONDS = 3.0
+
+      # Fraction of the screen width the box may not exceed (see {MIN_CAP_WIDTH}).
+      # @return [Float]
+      WIDTH_FRACTION = 0.4
+
+      # Fraction of the screen height the box may not exceed.
+      # @return [Float]
+      HEIGHT_FRACTION = 0.4
+
+      # Floor under the width cap, so 40 % of an 80-column terminal doesn't
+      # ellipsize every message down to five words.
+      # @return [Integer]
+      MIN_CAP_WIDTH = 34
+
+      # Separator for re-joining wrapped rows before ellipsizing.
+      # @return [StyledString]
+      SPACE = StyledString.parse(" ")
+
+      # Hard-line separator handed to {TextView#text=}.
+      # @return [StyledString]
+      ROW_BREAK = StyledString.parse("\n")
+      private_constant :SPACE, :ROW_BREAK
+
+      # Shows `text` in the corner, creating the box if none is open and
+      # appending to it if one is.
+      #
+      # @param text [String, StyledString, nil] the message. A `String` is parsed
+      #   via {StyledString.parse}, so embedded ANSI is honored. `nil` and the
+      #   empty string are no-ops (nothing is shown, nothing is created).
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      #   applied to every span of the message via {StyledString#with_fg}. A
+      #   {Theme::Ref} is resolved against the current theme *now* — see the
+      #   class docs on theme following. `nil` leaves the message's own colors
+      #   alone.
+      # @return [Notification, nil] the live notification, or `nil` when `text`
+      #   was empty.
+      # @raise [Tuile::Error] when the screen is closed, or when called from a
+      #   thread that doesn't currently own the UI — a background job raising a
+      #   notification must marshal it: `screen.event_queue.submit { ... }`.
+      def self.show(text, color: nil)
+        Screen.instance.check_locked
+        return nil if StyledString.parse(text).empty?
+
+        live = Screen.instance.pane.popups.find { _1.is_a?(Notification) }
+        return live.tap { _1.add_message(text, color: color) } unless live.nil?
+
+        # Message first, so the box is sized before it is mounted: opening an
+        # empty 0×0 popup and then growing it would paint a frame of nothing.
+        new.tap do |notification|
+          notification.add_message(text, color: color)
+          notification.open
+        end
+      end
+
+      private_class_method :new
+
+      def initialize
+        # Built before `super`, because Popup#initialize assigns the content and
+        # calls #reposition, and our override reads every one of these.
+        @messages = []
+        @high_water = 0
+        @ticker = nil
+        @view = TextView.new
+        @window = Window.new
+        @window.content = @view
+        super(content: @window, modal: false, close_on_outside_click: false)
+      end
+
+      # Load-bearing, not cosmetic: focus landing inside a non-modal popup sits
+      # outside the key-dispatch scope, where {ScreenPane#handle_key} delivers to
+      # nobody — every keystroke would go dead until the user pressed Tab.
+      # @return [Boolean] false.
+      def focusable? = false
+
+      # @return [Boolean] false — see {#focusable?}.
+      def tab_stop? = false
+
+      # Appends a message, dropping it (with a {Tuile.logger} warning) once
+      # {MAX_MESSAGES} are held. Public so a caller holding the instance can
+      # append without repeating {show}'s lookup.
+      # @param text [String, StyledString, nil] see {show}. Empty is a no-op.
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      #   see {show}.
+      # @return [void]
+      # @raise [Tuile::Error] see {show}.
+      def add_message(text, color: nil)
+        # Explicit rather than inherited-through-invalidate: this appends to
+        # @messages before anything repaints, so a wrong-thread call has to fail
+        # before the message is recorded, not after.
+        screen.check_locked
+        message = build_message(text, color)
+        return if message.empty?
+
+        if @messages.size >= MAX_MESSAGES
+          Tuile.logger.warn("Notification: dropping #{message.to_s.inspect}, " \
+                            "#{MAX_MESSAGES} messages already queued")
+          return
+        end
+
+        @messages << message
+        @high_water = [@high_water, natural_width(message)].max
+        reposition
+        sync_ticker
+      end
+
+      # Recomputes the box from its messages and re-anchors it to the screen's
+      # top-right corner — so a SIGWINCH re-wraps and re-anchors, where
+      # {Popup#reposition} would have kept the stale left column of a *derived*
+      # position (off-screen entirely if the terminal narrowed).
+      #
+      # Rebuilds the {TextView}'s text too, and every mutation routes through
+      # here, because the four are one computation: the wrap width *is* the box
+      # width, the height *is* the wrapped row count, the left edge *is* derived
+      # from the width.
+      # @return [void]
+      def reposition
+        if @messages.empty?
+          self.rect = Rect.new(0, 0, 0, 0)
+          return
+        end
+
+        width = box_width
+        rows = @messages.flat_map { |message| wrap_message(message, width - 2) }
+        height = [rows.size + 2, cap_height].min
+        @size = Size.new(width, height)
+        @view.text = join_rows(rows)
+        self.rect = Rect.new([screen.size.width - width, 0].max, 0, width, height)
+      end
+
+      # A notification is sized by its messages, so this always raises. Failing
+      # loudly beats accepting a size the next {#reposition} would discard.
+      # @param _new_size [Size, Fraction]
+      # @raise [Tuile::Error] always.
+      # @return [void]
+      def size=(_new_size)
+        raise Tuile::Error, "Notification sizes itself from its messages; #{self.class}#size= is not settable"
+      end
+
+      # A left click dismisses the whole box, every message with it. Other buttons
+      # are consumed and inert — including the scroll wheel, which would otherwise
+      # nuke the box on a stray spin.
+      #
+      # Deliberately *replaces* rather than augments: neither `super` nor
+      # {HasContent#handle_mouse} may run, since both end at a
+      # `screen.focused = …` inside this subtree (see {#focusable?}).
+      # @param event [MouseEvent]
+      # @return [void]
+      def handle_mouse(event)
+        close if event.button == :left
+      end
+
+      # @return [void]
+      def on_attached
+        super
+        sync_ticker
+      end
+
+      # @return [void]
+      def on_detached
+        super
+        sync_ticker
+      end
+
+      private
+
+      # Retires the oldest message, closing the box when it was the last. Runs on
+      # the event-loop thread, from the ticker.
+      # @return [void]
+      def retire_oldest
+        @messages.shift
+        @messages.empty? ? close : reposition
+        sync_ticker
+      end
+
+      # Syncs the retirement clock from the invariant "something to retire, and on
+      # screen" — the sole writer of `@ticker`. Four sites change whether it is
+      # wanted (append, a retirement that empties the queue, {#close}, detach),
+      # which is the 2×2 a start-in-{#on_attached} / cancel-in-{#on_detached} pair
+      # gets half wrong. The early return is also what keeps an append from
+      # *restarting* the clock and extending the oldest message's life.
+      # @return [void]
+      def sync_ticker
+        want = attached? && !@messages.empty?
+        return if want == !@ticker.nil?
+
+        if want
+          @ticker = screen.event_queue.tick(DISPLAY_SECONDS) { retire_oldest }
+        else
+          @ticker.cancel
+          @ticker = nil
+        end
+      end
+
+      # @param text [String, StyledString, nil]
+      # @param color [Color, Theme::Ref, Symbol, Integer, Array<Integer>, nil]
+      # @return [StyledString]
+      def build_message(text, color)
+        message = StyledString.parse(text)
+        return message if color.nil? || message.empty?
+
+        message.with_fg(color.is_a?(Theme::Ref) ? color.resolve(screen.theme) : color)
+      end
+
+      # Columns the message would like, ignoring wrapping — the *widest* of its
+      # hard lines, not the sum of its spans (which would add every line
+      # together for a message carrying `\n`).
+      # @param message [StyledString]
+      # @return [Integer]
+      def natural_width(message) = message.lines.map(&:display_width).max || 0
+
+      # Grow-only: the high-water mark is kept in *desired* columns and the cap
+      # is applied here, last. Storing the clamped value instead would let a
+      # SIGWINCH that narrows the terminal ratchet the box permanently down to
+      # the narrow cap, with nothing to restore it when the terminal widens.
+      # @return [Integer]
+      def box_width = [@high_water + 2, cap_width].min
+
+      # @return [Integer]
+      def cap_width
+        [[(screen.size.width * WIDTH_FRACTION).to_i, MIN_CAP_WIDTH].max, screen.size.width].min
+      end
+
+      # @return [Integer] at least 3: two border rows plus one row of message.
+      def cap_height
+        [[(screen.size.height * HEIGHT_FRACTION).to_i, 3].max, screen.size.height].min
+      end
+
+      # Wraps one message to `width` columns, capped at {MAX_ROWS_PER_MESSAGE}
+      # rows.
+      #
+      # The overflow is ellipsized from the *joined remainder*, not by
+      # ellipsizing the last kept row: that row usually already fits `width`, so
+      # {StyledString#ellipsize} would be a no-op and the message would be
+      # truncated with no `…` to say so.
+      # @param message [StyledString]
+      # @param width [Integer]
+      # @return [Array<StyledString>]
+      def wrap_message(message, width)
+        rows = message.wrap(width)
+        return rows if rows.size <= MAX_ROWS_PER_MESSAGE
+
+        kept = rows.take(MAX_ROWS_PER_MESSAGE - 1)
+        rest = rows[(MAX_ROWS_PER_MESSAGE - 1)..].inject { |joined, row| joined + SPACE + row }
+        kept + [rest.ellipsize(width)]
+      end
+
+      # Joins pre-wrapped rows into one {StyledString} with `\n` separators, so
+      # {TextView} takes them as hard lines and its own wrap is a no-op over
+      # them (each row already fits the width it will be painted at).
+      # @param rows [Array<StyledString>]
+      # @return [StyledString]
+      def join_rows(rows)
+        return StyledString::EMPTY if rows.empty?
+
+        rows.inject { |joined, row| joined + ROW_BREAK + row }
+      end
+    end
+  end
+end

data/lib/tuile/component/picker_window.rb

@@ -37,9 +37,10 @@ module Tuile
         @options = options.map { Option.new(_1[0], _1[1]) }
         @block = block
         list = Component::List.new
-        list.lines = @options.map { "#{_1.key} #{screen.theme.hint(_1.caption)}" }
+        list.renderer = ->(option) { "#{option.key} #{screen.theme.hint(option.caption)}" }
+        list.items = @options
         list.cursor = Component::List::Cursor.new
-        list.on_item_chosen = ->(index, _line) { select_option(@options[index].key) }
+        list.on_item_chosen = ->(_index, option) { select_option(option.key) }
         self.content = list
         # Optional hook for a containing Popup to dismiss itself after a pick.
         @on_pick = nil
@@ -65,11 +66,6 @@ module Tuile
         end
       end
 
-      # @return [String]
-      def keyboard_hint
-        @options.map { "#{_1.key} #{screen.theme.hint(_1.caption)}" }.join("  ")
-      end
-
       # Opens a picker as a popup. Picking an option fires `block`, then
       # closes the popup; ESC / `q` close without firing `block`.
       # @param caption [String]
@@ -83,7 +79,6 @@ module Tuile
         popup = Popup.new(content: picker)
         picker.on_pick = -> { popup.close }
         popup.open
-        popup
       end
 
       protected

data/lib/tuile/component/popup.rb

@@ -40,6 +40,10 @@ module Tuile
     # 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.
+    #
+    # A left click *outside* the popup closes it too, modal or not — see
+    # {#close_on_outside_click?} for the exact contract and {#on_close=} for
+    # the notice a driver hears when it happens.
     class Popup < Component
       include Component::HasContent
 
@@ -52,10 +56,16 @@ module Tuile
       # @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)
+      # @param close_on_outside_click [Boolean] true (default) to dismiss on a
+      #   left click that misses this popup. See {#close_on_outside_click?}.
+      def initialize(content: nil, modal: true, size: Fraction::HALF,
+                     close_on_outside_click: true)
         super()
         @modal = modal
         @size = size
+        @close_on_outside_click = close_on_outside_click
+        @owner = nil
+        @on_close = nil
         @content = nil
         self.content = content unless content.nil?
         reposition
@@ -67,6 +77,63 @@ module Tuile
       # @return [Boolean] whether this popup is modal. See {#initialize}.
       def modal? = @modal
 
+      # Whether a left click outside this popup closes it (default true, modal or
+      # not). The pane does the closing — {ScreenPane#handle_mouse} snapshots
+      # the open popups *before* routing the click and closes the dismissable
+      # ones *after*, so a widget that toggles its own overlay from a click on
+      # its face (a {Component::Select}, a {Component::MenuBar} title) still
+      # toggles correctly: the delivered click closes the overlay and the
+      # dismissal then no-ops on it, rather than closing and reopening it. Only
+      # `:left` dismisses; scroll and right clicks never do.
+      #
+      # **"Outside" spans the {#owner} chain, not just this rect.** A click
+      # counts as inside this popup when it lands in its rect *or* in any popup
+      # that belongs to it — so a dialog is not dismissed by a click on a
+      # dropdown its own field opened, and a menu cascade is not dismissed by a
+      # click on one of its deeper panels. Popups with no owner relationship are
+      # independent: clicking one dismisses the other, which is what a
+      # window-like overlay should do. A popup that must survive unrelated
+      # clicks entirely ({Component::Notification}) sets this false.
+      #
+      # Every dismissable popup closes, not just the topmost, and stacking order
+      # plays no part: a {Component::MenuBar} cascade must vanish whole on one
+      # click on the background, not peel one panel per click.
+      # @return [Boolean]
+      def close_on_outside_click? = @close_on_outside_click
+
+      # @return [Boolean] see {#close_on_outside_click?}.
+      attr_writer :close_on_outside_click
+
+      # The component this overlay is *part of*, or `nil` (the default) when it
+      # is an overlay in its own right. It exists for outside-click dismissal:
+      # a click inside this popup also counts as inside whatever popup encloses
+      # its owner, so the host is not dismissed by a click on a panel it put
+      # there. See {#close_on_outside_click?}.
+      #
+      # Set it to the *driver* — {Component::ComboBox} hands its dropdown
+      # `self` — rather than to the enclosing popup: the driver knows what it
+      # is, while the popup above it is a tree relationship the pane resolves
+      # at click time (so it cannot go stale). Any {Component} is accepted, and
+      # a `Popup` resolves to itself, which is how a
+      # {Component::MenuBar::Cascade} chains each panel to the one it dropped
+      # out of.
+      # @return [Component, nil]
+      attr_accessor :owner
+
+      # A callback taking no arguments, fired once this popup has left the
+      # screen — **however it left**: {#close}, a direct {Screen#remove_popup},
+      # an outside click, or teardown via {Screen#close}. That unconditionality
+      # is the point, so it hangs off {#on_detached} rather than {#close}; a
+      # driver keeping its own record of open popups reconciles it here and
+      # cannot drift ({Component::MenuBar::Cascade} is the worked example).
+      #
+      # It fires *after* the popup is detached, so {#open?} is already false and
+      # the usual {Component#on_detached} caveats apply: release state, don't
+      # inspect the tree, keep it trivial (it may run while the pane is mid-way
+      # through closing a batch of popups, and a raise propagates).
+      # @return [Proc, nil]
+      attr_accessor :on_close
+
       def focusable? = true
 
       # Sets the popup's size and repositions it. Accepts a {Fraction}
@@ -98,19 +165,17 @@ module Tuile
 
       # Mounts this popup on the {Screen}, re-resolving its {#size} against the
       # current screen first.
-      # @return [void]
+      #
+      #   popup = Component::Popup.new(content: window).open   # construct and mount
+      #
+      # There is deliberately no class-level `Popup.open` factory — see
+      # `DECISIONS.md` `D-popup-open`; returning `self` is what keeps the
+      # one-liner above available without one.
+      # @return [self]
       def open
         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, modal: true, size: Fraction::HALF)
-        Popup.new(content: content, modal: modal, size: size).tap(&:open)
+        self
       end
 
       # Removes this popup from the {Screen}. No-op if not currently open.
@@ -149,14 +214,6 @@ module Tuile
         self.rect = rect.centered(screen.size)
       end
 
-      # Hint for the status bar: own "q Close" plus the wrapped content's hint.
-      # @return [String]
-      def keyboard_hint
-        prefix = "q #{screen.theme.hint("Close")}"
-        child_hint = @content&.keyboard_hint.to_s
-        child_hint.empty? ? prefix : "#{prefix}  #{child_hint}"
-      end
-
       # `q` and ESC close the popup. The popup sits on the focus chain of
       # whatever it wraps, so the key reaches here by bubbling up from the
       # focused content after that content declined to handle it.
@@ -171,6 +228,13 @@ module Tuile
         end
       end
 
+      # Fires {#on_close}. A subclass overriding this **must** call `super`, or
+      # the popup's driver never hears that it closed.
+      # @return [void]
+      def on_detached
+        @on_close&.call
+      end
+
       protected
 
       # Content fills the popup's full rect — Popup has no border to subtract.

data/lib/tuile/component/progress_bar.rb

@@ -207,7 +207,7 @@ module Tuile
       def repaint
         return if rect.empty?
 
-        draw_line(rect.left, rect.top, StyledString.styled(glyphs(rect.width), fg: resolved_bar_color))
+        draw_text(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
 

data/lib/tuile/component/radio_group.rb

@@ -21,12 +21,13 @@ module Tuile
     # 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.
+    # 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.
     #
     # == The cursor is chrome
     # The cursor and the selection are two independent things, as in
@@ -50,7 +51,7 @@ module Tuile
     # == 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.
+    # independent, because a row resolves to its own item, never to its label.
     #
     # Rows are `(*) `/`( ) ` literals, mirroring {Checkbox}'s convention rather
     # than importing constants from it. ASCII deliberately: `(•)` would measure
@@ -69,7 +70,6 @@ module Tuile
       #   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
@@ -77,13 +77,14 @@ module Tuile
         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) }
+        list.renderer = method(:render_row)
+        list.on_item_chosen = ->(_index, item) { self.value = item }
+        list.items = items.to_a
         self.content = list
-        rebuild_rows
       end
 
       # @return [Array] the presented items.
-      attr_reader :items
+      def items = content.items
 
       # @return [Proc, Method] item -> row label (a `String`, {StyledString}, or
       #   anything with `#to_s`); `:to_s` by default.
@@ -97,18 +98,17 @@ module Tuile
       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
+        # 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
       end
 
       # @param proc [Proc, Method] item -> row label.
       # @return [void]
       def item_label=(proc)
         @item_label = proc
-        rebuild_rows
+        content.refresh_rows
       end
 
       # Selects `new_value`, firing {HasValue#on_value_change} when it really
@@ -122,7 +122,7 @@ module Tuile
         return if value == new_value
 
         super
-        rebuild_rows
+        content.refresh_rows
       end
 
       # Selects the cursor row on Space. Nothing else is claimed: the composed
@@ -147,33 +147,35 @@ module Tuile
 
       private
 
-      # Selects the item on row `index`; an index outside {#items} is ignored.
+      # Selects the item on row `index`; an index outside {#items} is ignored —
+      # {List::Cursor::None}'s `-1` would otherwise select the *last* item.
       # @param index [Integer]
       # @return [void]
       def select_at(index)
-        return unless index.between?(0, @items.size - 1)
+        return unless index.between?(0, items.size - 1)
 
-        self.value = @items[index]
+        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
+      # @param item [Object]
+      # @return [StyledString] the item's row: its label behind a selection
+      #   marker. The {List} calls this at paint time, so the marker tracks
+      #   {#value} without re-rendering anything but the visible rows.
+      def render_row(item)
+        StyledString.plain(item == value ? "(*) " : "( ) ") + label_for(item)
       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
+      # none). {List#items=} 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.
+      # @param item_count [Integer] size of the incoming item list.
       # @return [void]
-      def clamp_cursor
+      def clamp_cursor(item_count)
         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
+        cursor.go_to_last(item_count) if cursor.position >= item_count
       end
 
       # @param item [Object]