tuile 0.13.0 → 0.14.0

data/lib/tuile/component/list_dropdown.rb

@@ -4,7 +4,7 @@ module Tuile
   class Component
     # A borderless, tinted, non-focusable floating selection list — the dropdown
     # a *driver* drops open, drives by forwarding movement keys, and commits a
-    # pick from: a non-modal {Popup} wrapping a {List} that never takes focus, so
+    # pick from: an {Overlay} wrapping a {List} that never takes focus, so
     # focus stays on the driver while the caller refills the rows, moves the
     # highlight, and reads the pick.
     #
@@ -34,7 +34,7 @@ module Tuile
     # different tint (a `Theme.ref(:token)` keeps the flip-tracking).
     #
     # UI-thread-confined, like every component (see {Screen}).
-    class ListDropdown < Popup
+    class ListDropdown < Overlay
       # The dropdown's {List}. Non-focusable on purpose: the driver forwards keys
       # while focus stays on it, and a mouse click selects an item without
       # stealing focus — so a driving text input never loses its caret
@@ -64,7 +64,7 @@ module Tuile
         @list = Menu.new
         @list.cursor = List::Cursor.new
         @list.show_cursor_when_inactive = true # highlight the selection though focus stays on the driver
-        super(content: @list, modal: false)
+        super(content: @list)
         self.bg_color = Theme.ref(:input_bg_color)
       end
 
@@ -124,7 +124,16 @@ module Tuile
       # Vertical flips but horizontal slides because covering the driver would
       # hide what is being chosen, while sharing its columns is the point.
       #
-      # @param anchor [Rect] the driver's rect; the dropdown never covers it.
+      # **`anchor` is the region actually occupied, and may be taller than one
+      # row** — "beneath" means the row *after* it, so a multi-row driver (a
+      # {Component::TextArea} carrying an autocomplete menu) is cleared entirely
+      # rather than overdrawn from its second row down. A widget that paints one
+      # row but may be *assigned* more height passes its face, not its rect:
+      # {ComboBox} and {Select} both do, since a {Window} content slot hands them
+      # the full inner height.
+      #
+      # @param anchor [Rect] the region the driver occupies, of any height; the
+      #   dropdown never covers it.
       # @param rows [Integer] how many rows there are to show — the content
       #   count, not the height: more than fits turns the scrollbar on. `0`
       #   collapses the dropdown to an empty rect (drivers close instead).
@@ -136,20 +145,20 @@ module Tuile
       # @return [void]
       def anchor_to(anchor, rows:, width: anchor.width, max_rows: MAX_VISIBLE_ROWS)
         desired = [rows, max_rows].min
-        below = screen.size.height - (anchor.top + 1)
+        beneath = anchor.top + anchor.height
+        below = screen.size.height - beneath
         above = anchor.top
         if desired <= below
-          top = anchor.top + 1
+          top = beneath
           height = desired
         elsif above >= below
           height = [desired, above].min
           top = anchor.top - height
         else
           height = below
-          top = anchor.top + 1
+          top = beneath
         end
         width = [width, screen.size.width].min
-        self.size = Size.new(width, height)
         self.rect = Rect.new([anchor.left, screen.size.width - width].min.clamp(0, nil), top, width, height)
         # After the geometry: the setter rebuilds the list's padded rows against
         # the width it can see, and the gutter takes a column off it.
@@ -182,7 +191,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
+      #   `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]
@@ -197,7 +206,6 @@ module Tuile
                end
         left = left.clamp(0, [screen.size.width - width, 0].max)
         top = [anchor.top, screen.size.height - height].min.clamp(0, nil)
-        self.size = Size.new(width, height)
         self.rect = Rect.new(left, top, width, height)
         # After the geometry, as in {#anchor_to}: the setter rebuilds the list's
         # padded rows against the width it can see.

data/lib/tuile/component/log_text_view.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A {TextView} purpose-built for log output: auto-scroll is on, the
+    # scrollbar is visible, and lines arrive via {#log} — from any thread.
+    # Point a logger at a {LogTextView::IO} to route its lines here:
+    #
+    #   view = Tuile::Component::LogTextView.new
+    #   logger = Logger.new(Tuile::Component::LogTextView::IO.new(view))
+    #   logger.info("started")   # appears in the view, from any thread
+    #
+    # Any logger that writes formatted lines to an IO works the same way —
+    # for example `TTY::Logger` configured with the `:console` handler and
+    # `output: LogTextView::IO.new(view)`.
+    #
+    # Add it to a layout as-is for a frameless log pane, or use {LogWindow}
+    # for the framed assembly. A {TextView} rather than a {List}: long lines
+    # (stacktraces, wide log records) word-wrap rather than ellipsize — a
+    # truncated log line hides the very detail you opened the log to read.
+    class LogTextView < TextView
+      def initialize
+        super
+        self.auto_scroll = true
+        self.scrollbar_visibility = :visible
+      end
+
+      # Appends the given line to the log. Safe to call from any thread —
+      # the one exception to the UI-thread confinement every component
+      # carries: the append is marshalled through `event_queue.submit`, so
+      # it lands once a loop drains the queue (deferred before the first
+      # loop; silently dropped after the loop has returned).
+      # @param string [String, nil] the line (or multiple lines) to log;
+      #   `nil` is a no-op.
+      # @return [void]
+      def log(string)
+        return if string.nil?
+
+        screen.event_queue.submit { add_line(string) }
+      end
+
+      # IO-shaped adapter that forwards each log line to its sink's `#log`.
+      # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
+      # call `output.puts`, e.g. `TTY::Logger`).
+      class IO
+        # @param sink [LogTextView, LogWindow] anything responding to `#log`.
+        def initialize(sink)
+          @sink = sink
+        end
+
+        # @param string [String]
+        # @return [void]
+        def write(string)
+          @sink.log(string.chomp)
+        end
+
+        # @param string [String]
+        # @return [void]
+        def puts(string)
+          @sink.log(string)
+        end
+
+        # Stdlib `Logger` only treats an object as an IO target when it
+        # responds to both {#write} and {#close}; otherwise it tries to
+        # interpret it as a filename. This is a no-op.
+        # @return [void]
+        def close; end
+      end
+    end
+  end
+end

data/lib/tuile/component/log_window.rb

@@ -2,65 +2,30 @@
 
 module Tuile
   class Component
-    # Shows a log. Construct your logger pointed at a {LogWindow::IO} to route
-    # log lines into this window:
+    # A {Window} framing a {LogTextView} — the framed log pane. All the log
+    # behavior lives on the view (see {LogTextView} for the adapter and the
+    # wrap rationale); the window adds the border, caption and delegation:
     #
     #   log_window = Tuile::Component::LogWindow.new
     #   logger = Logger.new(Tuile::Component::LogWindow::IO.new(log_window))
-    #
-    # Any logger that writes formatted lines to an IO works the same way —
-    # for example `TTY::Logger` configured with the `:console` handler and
-    # `output: LogWindow::IO.new(window)`.
     class LogWindow < Window
+      # Alias of {LogTextView::IO}, which accepts the window itself as its sink.
+      # @return [Class]
+      IO = LogTextView::IO
+
       # @param caption [String]
       def initialize(caption = "Log")
         super
-        view = Component::TextView.new
-        # Word-wrap long lines (stacktraces, wide log records) rather than
-        # ellipsizing them as a {List} would — a truncated log line hides the
-        # very detail you opened the log to read.
-        view.auto_scroll = true
-        self.content = view
-        self.scrollbar = true
+        self.content = LogTextView.new
       end
 
-      # Appends given line to the log. Can be called from any thread. Does nothing if nil is passed in.
-      # @param string [String, nil] the line (or multiple lines) to log.
+      # Appends the given line to the log, from any thread — delegates to
+      # {LogTextView#log}.
+      # @param string [String, nil] the line (or multiple lines) to log;
+      #   `nil` is a no-op.
       # @return [void]
       def log(string)
-        return if string.nil?
-
-        screen.event_queue.submit do
-          content.add_line(string)
-        end
-      end
-
-      # IO-shaped adapter that forwards each log line to the owning {LogWindow}.
-      # Implements both {#write} (stdlib `Logger`) and {#puts} (loggers that
-      # call `output.puts`, e.g. `TTY::Logger`).
-      class IO
-        # @param window [LogWindow]
-        def initialize(window)
-          @window = window
-        end
-
-        # @param string [String]
-        # @return [void]
-        def write(string)
-          @window.log(string.chomp)
-        end
-
-        # @param string [String]
-        # @return [void]
-        def puts(string)
-          @window.log(string)
-        end
-
-        # Stdlib `Logger` only treats an object as an IO target when it
-        # responds to both {#write} and {#close}; otherwise it tries to
-        # interpret it as a filename. This is a no-op.
-        # @return [void]
-        def close; end
+        content.log(string)
       end
     end
   end

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

@@ -19,7 +19,7 @@ module Tuile
       #
       # 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 (`DECISIONS.md` `D_select`).
       #
       # == Implementation details
       # While open it consumes **everything** except the two keys that mean
@@ -33,7 +33,7 @@ module Tuile
         # The affordance painted on a row that opens a submenu. U+25B8 rather
         # than the obvious `▶`: like {Component::Select}'s `▾` it is East-Asian
         # **Neutral**, so it measures one column even under ambiguous-as-wide and
-        # stays outside `D-ambiguous-width`'s bet, where `▶` and `▼` are
+        # stays outside `D_ambiguous_width`'s bet, where `▶` and `▼` are
         # Ambiguous and would need an ASCII opt-in.
         # @return [String]
         SUBMENU_ARROW = "▸"
@@ -179,7 +179,7 @@ module Tuile
           drop.on_cursor_changed = ->(_index, _child) { truncate(level + 1) }
           # The cascade's own record of what is open is reconciled from the
           # popup's own closure, not maintained alongside it: an outside click
-          # closes panels behind our back ({Popup#close_on_outside_click?}), and
+          # closes panels behind our back ({Overlay#close_on_outside_click?}), and
           # a level left in `@levels` after its panel is gone would have `depth`,
           # `deepest` and `highlighted` all lying. Identity-keyed and idempotent,
           # because the notice also arrives from `truncate` (which has already

data/lib/tuile/component/menu_bar.rb

@@ -43,7 +43,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`
-    # `D-menu-bar`.
+    # `D_menu_bar`.
     #
     # == Sizing
     # Assign a {#rect} (typically one {Layout::Fixed}`[1]` row at the top of a
@@ -244,11 +244,11 @@ module Tuile
       # 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
       # ungated by geometry.
-      # @return [Rect]
+      # @return [Size]
       def extent
-        return Rect.new(rect.left, rect.top, 0, 1) if rect.empty?
+        return Size.new(0, 1) if rect.empty?
 
-        Rect.new(rect.left, rect.top, [painted_width - @left_column, rect.width].min, 1)
+        Size.new([painted_width - @left_column, rect.width].min, 1)
       end
 
       # @param new_rect [Rect]
@@ -470,7 +470,7 @@ module Tuile
       # @return [Integer, nil] the index of the item painted at `point`; `nil`
       #   for the blank tail or a row the strip doesn't paint.
       def index_at(point)
-        return nil unless extent.contains?(point)
+        return nil unless extent_rect.contains?(point)
 
         column = point.x - rect.left + @left_column
         segments.index { |_item, start, width| column >= start && column < start + width }

data/lib/tuile/component/notification.rb

@@ -28,22 +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 *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.
+    # - **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*
@@ -116,26 +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, close_on_outside_click: 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
-
       # 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.
@@ -166,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
@@ -183,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)

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