tuile 0.14.0 → 0.16.0

data/lib/tuile/component/list.rb

@@ -6,7 +6,7 @@ module Tuile
     #
     #   list = Component::List.new
     #   list.items    = people
-    #   list.renderer = ->(p) { StyledString.plain(p.name) + screen.theme.hint(" #{p.email}") }
+    #   list.renderer = ->(p) { StyledString.plain(p.name) + screen.theme.fg(:muted, " #{p.email}") }
     #   list.cursor   = List::Cursor.new                  # a bare list has none
     #   list.on_item_chosen = ->(index, person) { open(person) }
     #
@@ -249,7 +249,7 @@ module Tuile
 
       # @param key [String] a key.
       # @return [Boolean] true if the key was handled.
-      def handle_key(key)
+      def handle_key?(key)
         if key == Keys::PAGE_UP
           move_scroll_top_row_by(-viewport_rows)
           true
@@ -259,7 +259,7 @@ module Tuile
         elsif key == Keys::ENTER && cursor_on_item?
           fire_item_chosen
           true
-        elsif @cursor.handle_key(key, @items.size, viewport_rows)
+        elsif @cursor.handle_key?(key, @items.size, viewport_rows)
           move_viewport_to_cursor
           notify_cursor_changed
           invalidate
@@ -316,25 +316,35 @@ module Tuile
         true
       end
 
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        if event.button == :scroll_down
-          move_scroll_top_row_by(4)
-        elsif event.button == :scroll_up
-          move_scroll_top_row_by(-4)
-        else
-          return unless rect.contains?(event.point)
+      # Moves the cursor to the pressed row and fires {#on_item_chosen}; what
+      # each {Cursor} does with a press is its own.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
-          item_index = event.y - rect.top + scroll_top_row
-          if @cursor.handle_mouse(item_index, event, @items.size)
-            move_viewport_to_cursor
-            notify_cursor_changed
-            invalidate
-          end
-          fire_item_chosen if event.button == :left && item_index >= 0 && item_index < @items.size && cursor_on_item?
+        item_index = event.y - rect.top + scroll_top_row
+        if @cursor.handle_mouse_down?(item_index, event, @items.size)
+          move_viewport_to_cursor
+          notify_cursor_changed
+          invalidate
         end
+        fire_item_chosen if item_index >= 0 && item_index < @items.size && cursor_on_item?
+        true
+      end
+
+      # Scrolls four rows a notch, and declines — so the notch bubbles to an
+      # ancestor scroller — once this list is at that end of its items.
+      # @param event [Mouse::ScrollEvent]
+      # @return [Boolean]
+      def handle_mouse_scroll?(event)
+        before = scroll_top_row
+        case event.direction
+        when :down then move_scroll_top_row_by(4)
+        when :up   then move_scroll_top_row_by(-4)
+        else return false
+        end
+        scroll_top_row != before
       end
 
       # Paints the visible items into {#rect}, rendering the ones not already
@@ -379,15 +389,15 @@ module Tuile
           # @param _item_count [Integer]
           # @param _viewport_rows [Integer]
           # @return [Boolean]
-          def handle_key(_key, _item_count, _viewport_rows)
+          def handle_key?(_key, _item_count, _viewport_rows)
             false
           end
 
           # @param _item_index [Integer]
-          # @param _event [MouseEvent]
+          # @param _event [Mouse::DownEvent]
           # @param _item_count [Integer]
           # @return [Boolean]
-          def handle_mouse(_item_index, _event, _item_count)
+          def handle_mouse_down?(_item_index, _event, _item_count)
             false
           end
 
@@ -422,7 +432,7 @@ module Tuile
         # @param item_count [Integer] number of items in the list.
         # @param viewport_rows [Integer] number of visible rows.
         # @return [Boolean] true if the cursor moved.
-        def handle_key(key, item_count, viewport_rows)
+        def handle_key?(key, item_count, viewport_rows)
           case key
           when *Keys::DOWN_ARROWS
             go_down_by(1, item_count)
@@ -441,11 +451,11 @@ module Tuile
           end
         end
 
-        # @param item_index [Integer] the item the cursor is hovering over.
-        # @param event [MouseEvent] the event.
+        # @param item_index [Integer] the item pressed on.
+        # @param event [Mouse::DownEvent] the event.
         # @param item_count [Integer] number of items in the list.
-        # @return [Boolean] true if the event was handled.
-        def handle_mouse(item_index, event, item_count)
+        # @return [Boolean] true if the cursor moved.
+        def handle_mouse_down?(item_index, event, item_count)
           if event.button == :left
             go(item_index.clamp(nil, item_count - 1))
           else
@@ -507,10 +517,10 @@ module Tuile
           end
 
           # @param item_index [Integer]
-          # @param event [MouseEvent]
+          # @param event [Mouse::DownEvent]
           # @param _item_count [Integer]
           # @return [Boolean]
-          def handle_mouse(item_index, event, _item_count)
+          def handle_mouse_down?(item_index, event, _item_count)
             if event.button == :left
               prev_pos = @positions.reverse_each.find { _1 <= item_index }
               return go_to_first if prev_pos.nil?
@@ -564,14 +574,14 @@ module Tuile
       protected
 
       # Drops the rendered-row cache when the wrap width changes. The wrap
-      # width depends on {#rect}`.width` and the scrollbar gutter, both of
+      # width depends on {#rect}`.width` and the scrollbar column, both of
       # which trigger this hook. Also re-evaluates {#auto_scroll}: if items were
       # assigned while the rect was empty (e.g. a {Popup}-wrapped list was
       # populated before the popup was opened), the auto-scroll update
       # was skipped because there was no viewport — re-run it now that there
       # is one, so the list snaps to the bottom on first paint.
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         drop_row_cache
         update_scroll_top_row_if_auto_scroll
@@ -738,7 +748,7 @@ module Tuile
       # negating the auto-scroll. Skipped when {#rect} is empty: without a
       # viewport the "items minus viewport" formula yields `@items.size`,
       # which would leave `scroll_top_row` past the last item once a real rect
-      # arrives. {#on_width_changed} re-runs this hook when the rect grows so
+      # arrives. {#handle_width_changed} re-runs this hook when the rect grows so
       # the snap-to-bottom intent is preserved.
       #
       # Gated on {#following?}: once the user scrolls up off the bottom the
@@ -766,7 +776,7 @@ module Tuile
       end
 
       # @return [Integer] column width available for row content (rect width
-      #   minus the scrollbar gutter, when visible). `0` when {#rect}'s width
+      #   minus the scrollbar column, when visible). `0` when {#rect}'s width
       #   is non-positive.
       def content_width
         return 0 if rect.width <= 0
@@ -809,9 +819,11 @@ module Tuile
         rendered.lines.first
       end
 
-      # Pads `row` to one full row of the viewport (scrollbar gutter
-      # excluded). Rows wider than the content area are ellipsized via
-      # {StyledString#ellipsize} (span styles survive the cut); shorter
+      # Pads `row` to one full row of the viewport (scrollbar column
+      # excluded), including the one-column gutter either side — the trailing
+      # one is what keeps a row off the bar, as {TextView#scrollbar_columns}
+      # reserves separately. Rows wider than the content area are ellipsized
+      # via {StyledString#ellipsize} (span styles survive the cut); shorter
       # ones are padded with default-styled spaces.
       # @param row [StyledString]
       # @return [StyledString] exactly {#content_width} display columns wide
@@ -837,7 +849,10 @@ module Tuile
         base = index < @items.size ? padded_row(index) : blank_row
         is_cursor = (active? || @show_cursor_when_inactive) && index < @items.size && @cursor.position == index
         styled = is_cursor ? base.with_bg(screen.theme.active_bg_color) : base
-        styled += StyledString.plain(scrollbar.scrollbar_char(row_in_viewport)) if scrollbar
+        if scrollbar
+          styled += StyledString.styled(scrollbar.scrollbar_char(row_in_viewport),
+                                        fg: screen.theme.scrollbar_color)
+        end
         styled
       end
     end

data/lib/tuile/component/list_dropdown.rb

@@ -51,6 +51,10 @@ module Tuile
       # caret; {Select} would spend a branch on what a second arrow press already
       # does) — and Enter/ESC, which carry driver-specific tails (see the class
       # docs).
+      #
+      # A driver only ever sees the keys its own children decline, so a
+      # {ComboBox} never gets Ctrl+U — its field claims it to clear the query —
+      # while {Select}, wrapping no editor, gets every one of these.
       # @return [Array<String>]
       MOVE_KEYS = [Keys::UP_ARROW, Keys::DOWN_ARROW, Keys::PAGE_UP, Keys::PAGE_DOWN,
                    Keys::CTRL_U, Keys::CTRL_D].freeze
@@ -191,7 +195,7 @@ module Tuile
       # @param width [Integer] the panel's width in columns, clamped to the
       #   screen. **Required, with no default:** `anchor.width` is the *parent's*
       #   width and would be meaningless here, so the caller measures (see
-      #   `DECISIONS.md` `D_select` on why the width policy stays with the
+      #   `design/decisions.md` `D_select` on why the width policy stays with the
       #   driver).
       # @param max_rows [Integer] rows shown before the list scrolls.
       # @return [void]
@@ -240,7 +244,7 @@ module Tuile
       def move(key)
         return false unless open? && MOVE_KEYS.include?(key)
 
-        @list.handle_key(key)
+        @list.handle_key?(key)
         true
       end
 
@@ -249,7 +253,7 @@ module Tuile
       # 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)
+      def choose = @list.handle_key?(Keys::ENTER)
     end
   end
 end

data/lib/tuile/component/menu_bar/cascade.rb

@@ -8,18 +8,18 @@ module Tuile
       # machinery of {MenuBar}; an app never names it.
       #
       #   cascade.open_below(segment_rect, item)   # Enter/Down on the strip
-      #   return true if cascade.handle_key(key)   # MenuBar#handle_key, first
+      #   return true if cascade.handle_key?(key)   # MenuBar#handle_key?, first
       #   cascade.close                            # focus lost, or rect changed
       #
       # A panel is a **non-modal overlay, not a child**, so it never takes focus:
       # focus stays on the {MenuBar} for the whole interaction and every key
-      # arrives via {MenuBar#handle_key}, which offers it here first. That is
+      # arrives via {MenuBar#handle_key?}, which offers it here first. That is
       # {Component::Select}'s architecture extended to N levels, and it is why
       # nothing in the key-dispatch ladder changes.
       #
       # Widths are measured here, per level — the panel is as wide as the level's
       # widest label — because {ListDropdown} deliberately measures nothing
-      # itself (`DECISIONS.md` `D_select`).
+      # itself (`design/decisions.md` `D_select`).
       #
       # == Implementation details
       # While open it consumes **everything** except the two keys that mean
@@ -73,7 +73,7 @@ module Tuile
         # @return [Boolean] `true` when consumed — almost always, while open.
         #   `false` when closed, and for the two sideways keys {MenuBar} answers
         #   (see the class docs).
-        def handle_key(key)
+        def handle_key?(key)
           return false unless open?
           return true if deepest.move(key)
 
@@ -105,7 +105,7 @@ module Tuile
         # @param key [String] a single printable, already downcased.
         # @return [Boolean] whether an item on the deepest level claimed it. A
         #   miss is never offered to a shallower level.
-        def handle_mnemonic(key)
+        def handle_mnemonic?(key)
           return false unless open?
 
           level = depth - 1

data/lib/tuile/component/menu_bar.rb

@@ -42,7 +42,7 @@ module Tuile
     #
     # {Item} handles are minted by {#add_item} and nest via the *same* method, so
     # depth is unlimited. There is no removal, no reordering and no dynamic
-    # rebuilding: a menu is built once, at construction. See `DECISIONS.md`
+    # rebuilding: a menu is built once, at construction. See `design/decisions.md`
     # `D_menu_bar`.
     #
     # == Sizing
@@ -242,7 +242,7 @@ module Tuile
       #
       # Both the 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 — opens
-      # nothing. It still *focuses*: {Component#handle_mouse}'s click-to-focus is
+      # nothing. It still *focuses*: {Mouse::Router}'s click-to-focus is
       # ungated by geometry.
       # @return [Size]
       def extent
@@ -275,7 +275,7 @@ module Tuile
       # panels on the pane — they are the {ScreenPane}'s children, not the bar's,
       # so nothing else would take them down.
       # @return [void]
-      def on_detached
+      def handle_detached
         super
         @cascade.close
       end
@@ -288,11 +288,11 @@ module Tuile
       # submenu — and both step to the sibling menu.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         # Ahead of the cascade: an open one swallows every printable it doesn't
         # recognize, so a letter would never reach the strip otherwise.
-        return true if handle_mnemonic(key)
-        return true if @cascade.handle_key(key)
+        return true if handle_mnemonic?(key)
+        return true if @cascade.handle_key?(key)
 
         if @cascade.open?
           case key
@@ -310,17 +310,16 @@ module Tuile
         end
       end
 
-      # Opens the menu under a left click, or closes it when it is already the
-      # open one; `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
+      # Opens the menu under a left press, or closes it when it is already the
+      # open one; a press on the strip's padding claims the press and does
+      # nothing else.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
+        return false unless event.button == :left
 
         index = index_at(event.point)
-        return if index.nil?
+        return true if index.nil?
 
         if @cascade.open? && index == @highlighted_index
           @cascade.close
@@ -328,6 +327,7 @@ module Tuile
           self.highlight = index
           open_highlighted
         end
+        true
       end
 
       # @return [void]
@@ -372,7 +372,7 @@ module Tuile
       # hook is the whole geometry story; {Component#rect=} invalidates for us,
       # and {#rect=} closes the cascade rather than re-anchoring it.
       # @return [void]
-      def on_width_changed
+      def handle_width_changed
         super
         adjust_left_column
       end
@@ -512,11 +512,11 @@ module Tuile
       # not offered to any other level.
       # @param key [String]
       # @return [Boolean] whether a mnemonic claimed the key.
-      def handle_mnemonic(key)
+      def handle_mnemonic?(key)
         return false unless Keys.printable?(key)
 
         down = key.downcase
-        return @cascade.handle_mnemonic(down) if @cascade.open?
+        return @cascade.handle_mnemonic?(down) if @cascade.open?
 
         index = items.index { |item| item.mnemonic == down }
         return false if index.nil?

data/lib/tuile/component/notification.rb

@@ -28,20 +28,20 @@ module Tuile
     # (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.
+    # `design/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.** An {Overlay} sits off the
-    #   key-dispatch scope ({ScreenPane#handle_key}), so no key arrives here at
-    #   all. A left click *on the box* dismisses ({#handle_mouse}); an app
+    #   key-dispatch scope ({ScreenPane#handle_key?}), so no key arrives here at
+    #   all. A left click *on the box* dismisses ({#handle_mouse_down?}); an app
     #   wanting a key registers a global shortcut and calls {Overlay#close}. A
     #   click *elsewhere* does not — this is the one overlay with
     #   {Overlay#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.
+    #   {Component#handle_theme_changed} rebuild.
     # - **Take a size.** An {Overlay} has no declared box; the messages decide
     #   this one's, in {#reposition}.
     class Notification < Overlay
@@ -122,7 +122,7 @@ module Tuile
         @messages = []
         @high_water = 0
         @ticker = nil
-        @view = TextView.new
+        @view = View.new
         @window = Window.new
         @window.content = @view
         super(content: @window, close_on_outside_click: false)
@@ -179,27 +179,41 @@ module Tuile
         self.rect = Rect.new([screen.size.width - width, 0].max, 0, width, height)
       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 {Overlay#focusable?}).
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
+      # A left press dismisses the whole box, every message with it. Every other
+      # press is claimed and inert, so nothing beneath the toast acts on it.
+      # @param event [Mouse::DownEvent]
+      # @return [Boolean]
+      def handle_mouse_down?(event)
         close if event.button == :left
+        true
+      end
+
+      # Claimed and inert: a stray wheel spin over the toast must neither nuke it
+      # nor reach whatever it covers.
+      # @param _event [Mouse::ScrollEvent]
+      # @return [Boolean]
+      def handle_mouse_scroll?(_event) = true
+
+      # The message rows, minus the wheel — the one thing a plain
+      # {Component::TextView} would add here. On a short terminal the queued
+      # messages are taller than the box, and the box is unfocusable, so
+      # scrolling them would be a capability the keyboard cannot reach
+      # (`D_mouse`); they are meant to *wait* until the ticker retires the ones
+      # above.
+      class View < TextView
+        # @param _event [Mouse::ScrollEvent]
+        # @return [Boolean] true — claimed on the box's behalf, and inert.
+        def handle_mouse_scroll?(_event) = true
       end
 
       # @return [void]
-      def on_attached
+      def handle_attached
         super
         sync_ticker
       end
 
       # @return [void]
-      def on_detached
+      def handle_detached
         super
         sync_ticker
       end
@@ -218,7 +232,7 @@ module Tuile
       # 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
+      # which is the 2×2 a start-in-{#handle_attached} / cancel-in-{#handle_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]

data/lib/tuile/component/overlay.rb

@@ -23,7 +23,7 @@ module Tuile
     # **{#focusable?} and {#modal?} move together — flip both or neither.** The
     # defaults here are inert (`false`, `false`): a bare overlay floats without
     # disturbing focus or key dispatch. {Component::Popup} flips both. What must
-    # not appear is a *focusable non-modal* overlay: {ScreenPane#handle_key}
+    # not appear is a *focusable non-modal* overlay: {ScreenPane#handle_key?}
     # scopes delivery to the topmost modal popup or else the tiled content, so
     # such an overlay would hold focus outside the key scope, where delivery
     # reaches nobody and *every* keystroke goes dead until Tab recovers. A
@@ -67,10 +67,27 @@ module Tuile
       #   (its content may still carry stops).
       def tab_stop? = false
 
+      # Refused: an overlay is **dismissed, not hidden**. Use {#close} and
+      # {#open} — which already keep it alive between showings, the one thing
+      # hiding would buy — or hide the *content* if only a piece of it comes
+      # and goes.
+      #
+      # The pane resolves clicks and key scope from its popup list, which does
+      # not consult this flag, so a hidden overlay would paint nothing while
+      # still swallowing every click and, if modal, scoping every key: the
+      # invisible-modal trap the class docs warn about for {#focusable?} and
+      # {#modal?}.
+      # @param _value [Boolean]
+      # @raise [Tuile::Error] always.
+      # @return [void]
+      def visible=(_value)
+        raise Tuile::Error, "#{self.class} cannot be hidden — close it instead (Overlay#close)"
+      end
+
       # Whether a left click outside this overlay closes it (default true). The
-      # pane does the closing — {ScreenPane#handle_mouse} snapshots the open
-      # overlays *before* routing the click and closes the dismissable ones
-      # *after*, so a widget that toggles its own overlay from a click on its
+      # pane does the closing — {ScreenPane#dismissing_popups_outside} snapshots
+      # the open overlays *before* the press is routed 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`
@@ -113,12 +130,12 @@ module Tuile
       # A callback taking no arguments, fired once this overlay 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
+      # is the point, so it hangs off {#handle_detached} rather than {#close}; a
       # driver keeping its own record of open overlays reconciles it here and
       # cannot drift ({Component::MenuBar::Cascade} is the worked example).
       #
       # It fires *after* the overlay is detached, so {#open?} is already false
-      # and the usual {Component#on_detached} caveats apply: release state, don't
+      # and the usual {Component#handle_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 overlays, and a raise propagates).
       # @return [Proc, nil]
@@ -144,7 +161,7 @@ module Tuile
       #   overlay = Component::Overlay.new(content: label).open   # construct and mount
       #
       # There is deliberately no class-level `Overlay.open` factory — see
-      # `DECISIONS.md` `D_popup_open`; returning `self` is what keeps the
+      # `design/decisions.md` `D_popup_open`; returning `self` is what keeps the
       # one-liner above available without one.
       # @return [self]
       def open
@@ -174,7 +191,8 @@ module Tuile
       # Fires {#on_close}. A subclass overriding this **must** call `super`, or
       # the overlay's driver never hears that it closed.
       # @return [void]
-      def on_detached
+      def handle_detached
+        super
         @on_close&.call
       end
 

data/lib/tuile/component/picker_window.rb

@@ -3,11 +3,26 @@
 module Tuile
   class Component
     # A {Window} that lists options identified by single keyboard keys, asks
-    # the user to pick one, and fires a callback with the picked key.
+    # the user to pick one, and fires a callback with the picked key. Each row
+    # is `"<key> <caption>"`:
+    #
+    #   PickerWindow.open("Sort by", [%w[n name], %w[s size]]) { sort_by(_1) }
+    #
+    #   ┌Sort by───────┐
+    #   │n name        │
+    #   │s size        │
+    #   └──────────────┘
     #
     # Usable tiled (just add to a {Layout} and read picks via the block) or
     # as a popup via {.open}, which wraps it in a {Popup} that closes itself
     # after a pick. ESC / `q` close without firing the callback.
+    #
+    # Captions paint in the terminal's own foreground. To color them, hand in
+    # {StyledString} captions — the picker styles nothing itself, so an app's
+    # own token applies per option:
+    #
+    #   PickerWindow.open("File", [["o", StyledString.plain("Open")],
+    #                              ["d", theme.fg(:danger, "Delete")]]) { … }
     class PickerWindow < Window
       # Scrolls the window when more items.
       # @return [Integer]
@@ -18,26 +33,30 @@ module Tuile
       # @!attribute [r] key
       #   @return [String] the keyboard key that picks this option.
       # @!attribute [r] caption
-      #   @return [String] the option caption.
+      #   @return [StyledString] the option caption, coerced from whatever the
+      #     constructor was handed.
       class Option < Data.define(:key, :caption)
       end
 
       # @param caption [String] the window caption.
-      # @param options [Array<Array(String, String)>] pairs of keyboard key and
-      #   option caption. No Rainbow formatting must be used.
+      # @param options [Array<Array(String, StyledString)>] pairs of
+      #   keyboard key and option caption. A caption goes through
+      #   {StyledString.parse}, so a plain String, an ANSI-coded one (what
+      #   {Theme#fg} returns) and a {StyledString} are all accepted.
       # @yield [key] called with the option key once one is selected by the
       #   user. Not called if the picker is dismissed without picking.
       # @yieldparam key [String] the picked option key.
       # @yieldreturn [void]
+      # @raise [ArgumentError] when `block` is missing or `options` is empty.
       def initialize(caption, options, &block)
         raise ArgumentError, "block required" unless block
         raise ArgumentError, "options must not be empty" if options.empty?
 
         super(caption)
-        @options = options.map { Option.new(_1[0], _1[1]) }
+        @options = options.map { Option.new(_1[0], StyledString.parse(_1[1])) }
         @block = block
         list = Component::List.new
-        list.renderer = ->(option) { "#{option.key} #{screen.theme.hint(option.caption)}" }
+        list.renderer = ->(option) { StyledString.plain("#{option.key} ") + option.caption }
         list.items = @options
         list.cursor = Component::List::Cursor.new
         list.on_item_chosen = ->(_index, option) { select_option(option.key) }
@@ -57,7 +76,7 @@ module Tuile
       # option's `key` picks that option.
       # @param key [String]
       # @return [Boolean]
-      def handle_key(key)
+      def handle_key?(key)
         if @options.any? { _1.key == key }
           select_option(key)
           true
@@ -69,7 +88,7 @@ module Tuile
       # Opens a picker as a popup. Picking an option fires `block`, then
       # closes the popup; ESC / `q` close without firing `block`.
       # @param caption [String]
-      # @param options [Array<Array(String, String)>]
+      # @param options [Array<Array(String, StyledString)>]
       # @yield [key]
       # @yieldparam key [String]
       # @yieldreturn [void]

data/lib/tuile/component/popup.rb

@@ -28,7 +28,7 @@ module Tuile
     #
     # `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
+    # 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.
     #
@@ -107,7 +107,7 @@ module Tuile
       # focused content after that content declined to handle it.
       # @param key [String]
       # @return [Boolean] true if the key was handled.
-      def handle_key(key)
+      def handle_key?(key)
         if [Keys::ESC, "q"].include?(key)
           close
           true