tuile 0.12.0 → 0.14.0

data/lib/tuile/component/notification.rb

@@ -28,19 +28,23 @@ 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.
+    # `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 dismisses ({#handle_mouse}); an app
-    #   wanting a key registers a global shortcut and calls {#close}.
+    # - **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
+    #   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.
-    # - **Take a size.** {#size=} raises; the messages decide.
-    class Notification < Popup
+    # - **Take a size.** An {Overlay} has no declared box; the messages decide
+    #   this one's, in {#reposition}.
+    class Notification < Overlay
       # 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*
@@ -113,32 +117,17 @@ module Tuile
       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.
+        # Built before `super`, because Overlay#initialize assigns the content
+        # and our #reposition 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)
+        super(content: @window, 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
-
-      # Empty: a non-modal popup never owns the status bar, and {Popup}'s
-      # inherited `q Close` hint would be a lie here — no key ever reaches a
-      # notification.
-      # @return [String]
-      def keyboard_hint = ""
-
       # 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.
@@ -169,7 +158,7 @@ module Tuile
 
       # 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*
+      # {Overlay#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
@@ -186,27 +175,17 @@ module Tuile
         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?}).
+      # `screen.focused = …` inside this subtree (see {Overlay#focusable?}).
       # @param event [MouseEvent]
       # @return [void]
       def handle_mouse(event)
@@ -214,10 +193,16 @@ module Tuile
       end
 
       # @return [void]
-      def on_attached = sync_ticker
+      def on_attached
+        super
+        sync_ticker
+      end
 
       # @return [void]
-      def on_detached = sync_ticker
+      def on_detached
+        super
+        sync_ticker
+      end
 
       private
 

data/lib/tuile/component/overlay.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A component mounted on the {Screen}'s overlay stack rather than in the
+    # tiled tree: it floats above the content at a rect the caller assigns, and
+    # has an open/close lifecycle instead of a parent that lays it out.
+    #
+    #   overlay = Component::Overlay.new(content: Component::Label.new("saved"))
+    #   overlay.rect = Rect.new(10, 4, 20, 1)   # you place it — nothing else does
+    #   overlay.open                            # mounts it on the Screen
+    #   overlay.close
+    #
+    # That is the whole of it — floating, plus the lifecycle, {#on_close},
+    # outside-click dismissal and {#owner}. {Component::Popup} is the subclass
+    # that adds a declared size, self-centering, focus and key handling.
+    #
+    # The wrapped content fills the overlay's whole {#rect}; for a frame and a
+    # caption, wrap a {Component::Window} and let it draw its own border.
+    #
+    # == Implementation details
+    #
+    # **{#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}
+    # 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
+    # non-modal overlay is therefore driven from its owner's key handler
+    # ({Component::Select} forwarding to its dropdown) instead of claiming focus.
+    #
+    # **A derived position needs a {#reposition} override.** The default is a
+    # no-op: the rect is whatever the caller last assigned. An overlay whose
+    # position is computed — from the screen, or from an anchor — must recompute
+    # it there, or it keeps a stale rect after a SIGWINCH and sits off-screen
+    # entirely if the terminal narrowed. Closing on resize is equally legal
+    # ({Component::MenuBar} drops its cascade from `rect=` rather than walking
+    # every level to re-anchor it).
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class Overlay < Component
+      include Component::HasContent
+
+      # @param content [Component, nil] initial content; can be set later via
+      #   {#content=}. It fills the overlay's {#rect} and does not determine it.
+      # @param close_on_outside_click [Boolean] true (default) to dismiss on a
+      #   left click that misses this overlay. See {#close_on_outside_click?}.
+      def initialize(content: nil, close_on_outside_click: true)
+        super()
+        @close_on_outside_click = close_on_outside_click
+        @owner = nil
+        @on_close = nil
+        @content = nil
+        self.content = content unless content.nil?
+      end
+
+      # @return [Boolean] false — a bare overlay scopes no keys and blocks no
+      #   clicks. {Component::Popup} overrides it, together with {#focusable?}.
+      def modal? = false
+
+      # @return [Boolean] false — a bare overlay leaves focus where it was. See
+      #   the class docs: override it only together with {#modal?}.
+      def focusable? = false
+
+      # @return [Boolean] false — Tab never lands on the overlay wrapper itself
+      #   (its content may still carry stops).
+      def tab_stop? = false
+
+      # 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
+      # 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 overlay when it lands in its rect *or* in any
+      # overlay 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. Overlays with no owner relationship
+      # are independent: clicking one dismisses the other, which is what a
+      # window-like overlay should do. One that must survive unrelated clicks
+      # entirely ({Component::Notification}) sets this false.
+      #
+      # Every dismissable overlay 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 overlay also counts as inside whatever overlay 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 overlay: the driver knows what it is,
+      # while the overlay above it is a tree relationship the pane resolves at
+      # click time (so it cannot go stale). Any {Component} is accepted, and an
+      # `Overlay` 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 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
+      # 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
+      # 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]
+      attr_accessor :on_close
+
+      # Reassigns the overlay's rect, escalating to a full scene repaint when an
+      # open overlay shrinks or moves so its new rect no longer covers the cells
+      # it previously painted. An overlay overdraws the scene without clipping
+      # and nothing clears underneath it, so {Screen#repaint}'s overlay-only fast
+      # path would repaint into the new rect and leave the vacated cells showing
+      # stale content. When the new rect fully covers the old one (the overlay
+      # only grew), the fast path is correct and the full repaint is skipped.
+      # @param new_rect [Rect]
+      # @return [void]
+      def rect=(new_rect)
+        old_rect = rect
+        super
+        screen.needs_full_repaint if open? && !new_rect.contains_rect?(old_rect)
+      end
+
+      # Mounts this overlay on the {Screen}.
+      #
+      #   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
+      # one-liner above available without one.
+      # @return [self]
+      def open
+        reposition
+        screen.add_popup(self)
+        self
+      end
+
+      # Removes this overlay from the {Screen}. No-op if not currently open.
+      # @return [void]
+      def close
+        screen.remove_popup(self)
+      end
+
+      # @return [Boolean] true if this overlay is currently mounted on the screen.
+      def open?
+        screen.has_popup?(self)
+      end
+
+      # Recomputes this overlay's own rect (not its content's layout). A no-op
+      # here — the rect is whatever the caller assigned — and the hook a subclass
+      # with a *derived* position overrides; see the class docs. Called on
+      # {#open} and by the screen's layout pass, so an override tracks SIGWINCH.
+      # @return [void]
+      def reposition; end
+
+      # 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
+        @on_close&.call
+      end
+
+      protected
+
+      # Content fills the overlay's full rect — an Overlay has no border to
+      # subtract.
+      # @param content [Component]
+      # @return [void]
+      def layout(content)
+        content.rect = rect
+      end
+    end
+  end
+end

data/lib/tuile/component/picker_window.rb

@@ -66,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]

data/lib/tuile/component/popup.rb

@@ -2,143 +2,98 @@
 
 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 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 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
-    # {Component::LogWindow}) and let it draw its own border:
+    # A modal dialog: an {Component::Overlay} that centers itself on the screen,
+    # grabs focus, scopes keys to its own subtree, blocks clicks beneath it, and
+    # closes on ESC or `q`.
     #
     #   window = Component::Window.new("Help")
     #   window.content = Component::List.new.tap { _1.lines = lines }
     #   Component::Popup.new(content: window).open
     #
     # Bare content also works (a {Component::Label}, a {Component::List}…), in
-    # which case the popup is borderless.
+    # which case the popup is borderless. For a floating layer that does *not*
+    # take focus or capture input — an autocomplete list anchored to a field, a
+    # toast — use {Component::Overlay} directly.
+    #
+    # The popup does *not* size itself to its content. Its box is set by
+    # {#declared_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.
+    #
+    # == Implementation details
     #
     # `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
-
+    # nested {Component::TextField} doesn't dismiss the popup: the field consumes
+    # it first.
+    #
+    # A left click *outside* the popup closes it too — see
+    # {Overlay#close_on_outside_click?} for the exact contract and
+    # {Overlay#on_close=} for the notice a driver hears when it happens.
+    #
+    # UI-thread-confined, like every component (see {Screen}).
+    class Popup < Overlay
       # @param content [Component, nil] initial content; can be set later via
       #   {#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).
-      # @param size [Size, Fraction] the popup's size, applied top-down. A
-      #   {Fraction} is resolved against the screen each layout pass; a {Size}
+      # @param declared_size [Size, Fraction] the popup's box, 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?
+      # @param close_on_outside_click [Boolean] true (default) to dismiss on a
+      #   left click that misses this popup. See
+      #   {Overlay#close_on_outside_click?}.
+      def initialize(content: nil, declared_size: Fraction::HALF, close_on_outside_click: true)
+        super(content: content, close_on_outside_click: close_on_outside_click)
+        @declared_size = declared_size
         reposition
       end
 
-      # @return [Size, Fraction] the popup's declared size. See {#size=}.
-      attr_reader :size
+      # The box this popup asks for, *as set* — a {Fraction} comes back
+      # unresolved. {#rect} is the resolved answer. Named apart from `size`
+      # because a component's `size` is its `rect.size`, which this is not: it
+      # is an input re-read on every layout pass, not a report of the current
+      # geometry.
+      # @return [Size, Fraction] see {#declared_size=}.
+      attr_reader :declared_size
 
-      # @return [Boolean] whether this popup is modal. See {#initialize}.
-      def modal? = @modal
+      # @return [Boolean] true — a Popup scopes key dispatch, grabs focus on
+      #   open, and blocks clicks on the content beneath it.
+      def modal? = true
 
+      # @return [Boolean] true — {ScreenPane#add_popup} focuses a popup on open,
+      #   and focus repair falls back to it when its subtree has no tab stop.
       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),
+      # Sets the popup's box 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
+      def declared_size=(new_size)
+        @declared_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
-      # nothing clears underneath it, so {Screen#repaint}'s popup-only fast path
-      # would repaint into the new rect and leave the vacated cells showing
-      # stale content. When the new rect fully covers the old one (the popup
-      # only grew), the fast path is correct and the full repaint is skipped.
-      # @param new_rect [Rect]
-      # @return [void]
-      def rect=(new_rect)
-        old_rect = rect
-        super
-        screen.needs_full_repaint if open? && !new_rect.contains_rect?(old_rect)
-      end
-
-      # Mounts this popup on the {Screen}, re-resolving its {#size} against the
-      # current screen first.
-      #
-      #   popup = Component::Popup.new(content: window).open   # construct and mount
+      # Re-resolves {#declared_size} against the current screen and recenters the popup
+      # *itself* (this is not laying out content — the popup's own rect). Called
+      # on {Overlay#open}, on {#declared_size=}, and by the screen's layout pass,
+      # so a {Fraction} tracks SIGWINCH.
       #
-      # 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)
-        self
-      end
-
-      # Removes this popup from the {Screen}. No-op if not currently open.
-      # @return [void]
-      def close
-        screen.remove_popup(self)
-      end
-
-      # @return [Boolean] true if this popup is currently mounted on the screen.
-      def open?
-        screen.has_popup?(self)
-      end
-
-      # 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
+      # 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 {Overlay#rect=}'s shrink/move
       # detection fire a full repaint on every resize.
       # @return [void]
       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
+        size = @declared_size.is_a?(Fraction) ? @declared_size.resolve(screen.size) : @declared_size.clamp(screen.size)
+        self.rect = Rect.new(rect.left, rect.top, size.width, size.height).centered(screen.size)
       end
 
       # Recenters the popup on the screen, preserving its current width/height.
@@ -147,14 +102,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.
@@ -168,15 +115,6 @@ module Tuile
           false
         end
       end
-
-      protected
-
-      # Content fills the popup's full rect — Popup has no border to subtract.
-      # @param content [Component]
-      # @return [void]
-      def layout(content)
-        content.rect = rect
-      end
     end
   end
 end

data/lib/tuile/component/progress_bar.rb

@@ -38,7 +38,7 @@ module Tuile
     # 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
+    # `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

data/lib/tuile/component/select.rb

@@ -42,7 +42,7 @@ module Tuile
     # Home/End are declined too, so they stay available app-wide.
     #
     # There is no type-ahead: a hidden prefix buffer *is* the ComboBox query with
-    # the feedback removed (`DECISIONS.md` `D-select`). Which is also why labels
+    # the feedback removed (`DECISIONS.md` `D_select`). Which is also why labels
     # need no prefix-disambiguation.
     #
     # == Implementation details
@@ -72,6 +72,9 @@ module Tuile
         @value = value
         @on_value_change = nil
         @overlay = ListDropdown.new
+        # Outside-click dismissal spans the owner chain, so a click on this
+        # select's dropdown must not dismiss a dialog the select sits in.
+        @overlay.owner = self
         @overlay.renderer = method(:label_for)
         @overlay.on_item_chosen = ->(_index, item) { commit(item) }
       end
@@ -108,7 +111,6 @@ module Tuile
       end
 
       # @return [String]
-      def keyboard_hint = "⏎ #{screen.theme.hint("open")}  ↑↓ #{screen.theme.hint("select")}"
 
       # Re-anchors the (open) dropdown after a move or resize.
       # @param new_rect [Rect]
@@ -154,24 +156,32 @@ module Tuile
         end
       end
 
-      # Toggles the dropdown on a left click anywhere in {#rect} — a field's
+      # The one row this Select paints — the full width, at the top of {#rect}.
+      # A single-slot container ({Component::Window}, {Component::Popup}) hands
+      # its content the whole inner rect, so a Select is routinely assigned more
+      # height than it uses; {#repaint} clears that tail, {#handle_mouse} refuses
+      # clicks in it, and the dropdown hangs under this rather than under the
+      # unused space.
+      # @return [Size]
+      def extent = Size.new(rect.width, 1)
+
+      # Toggles the dropdown on a left click anywhere in {#extent} — a field's
       # affordance is its whole row, as the well advertises; `super` runs first,
       # so the click also 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_rect.contains?(event.point)
 
         @overlay.open? ? close_menu : open_menu
       end
 
       # @return [void]
       def repaint
+        super
         return if rect.empty?
 
-        tail = Rect.new(rect.left, rect.top + 1, rect.width, rect.height - 1)
-        clear_background(tail) unless tail.empty?
         draw_text(rect.left, rect.top, face_row)
       end
 
@@ -218,7 +228,7 @@ module Tuile
       end
 
       # @return [void]
-      def anchor = @overlay.anchor_to(rect, rows: @items.size, width: menu_width)
+      def anchor = @overlay.anchor_to(extent_rect, rows: @items.size, width: menu_width)
 
       # The dropdown's width: the widest label plus {List}'s two row gutters, plus
       # the scrollbar column when the rows can't all be shown at once — but never