tuile 0.13.0 → 0.14.0

data/lib/tuile/component/popup.rb

@@ -2,210 +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.
+    # 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
-
+    # 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}.
       # @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?
+      #   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
-
-      # @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 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
 
-      # 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
+      # @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.
@@ -227,22 +115,6 @@ module Tuile
           false
         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.
-      # @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
@@ -156,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
 
@@ -220,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

data/lib/tuile/component/slot.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Tuile
+  class Component
+    # A one-child region: a place in the tree reserved for content that may be
+    # absent, arrive late, or be swapped. The occupant fills the slot's {#rect}.
+    #
+    # Wire one per region at construction, then swap occupants through
+    # {HasContent#content=} — which is how {Window} holds its footer:
+    #
+    #   @footer_slot = Slot.new
+    #   add_child(@footer_slot)             # the region, wired once
+    #   …
+    #   @footer_slot.content = new_footer   # the occupant, swapped at will
+    #
+    # Because the slot never leaves {Component#children}, a swap's insert index
+    # is always 0 — never a function of which *other* regions happen to be
+    # occupied, which is the whole reason to reach for one (`D_slots`).
+    #
+    # An empty slot does not collapse: it keeps its rect and clears it, so a
+    # dialog with no message shows the hole. Close the gap with a zero extent
+    # from the parent, or assign an empty {Rect} to suppress the clear entirely
+    # (what {Window} does with an absent footer); never detach it.
+    #
+    # Transparent to input: not {Component#focusable?},
+    # {Component#handle_mouse} descends through it, and a departing occupant's
+    # focus repair is handed to the container.
+    class Slot < Component
+      include Component::HasContent
+
+      # @param content [Component, nil] the initial occupant.
+      def initialize(content = nil)
+        super()
+        @content = nil
+        self.content = content unless content.nil?
+      end
+
+      # Hands the repair to the container rather than doing it here: the default
+      # would move focus to `self`, and a slot is inert — no cursor, no keys,
+      # nothing to bubble from.
+      # @param child [Component] the just-detached occupant.
+      # @return [void]
+      def on_child_removed(child)
+        parent&.on_child_removed(child)
+      end
+
+      protected
+
+      # @param content [Component]
+      # @return [void]
+      def layout(content) = content.rect = rect
+    end
+  end
+end

data/lib/tuile/component/tab_sheet.rb

@@ -166,17 +166,6 @@ module Tuile
         layout_pane
       end
 
-      # Forwards to whichever child the click landed on — the strip's row, or
-      # the pane below it.
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        super
-        children.each do |child|
-          child.handle_mouse(event) if child.rect.contains?(event.point)
-        end
-      end
-
       # Sends focus to the strip: a sheet is a container, and the strip is where
       # a tab switch is driven from. The pane is a Tab press away.
       # @return [void]

data/lib/tuile/component/tabs.rb

@@ -29,7 +29,7 @@ module Tuile
     #
     # {Tab} handles are minted by {#add_tab} and owned by the strip. There is no
     # `items=`: a tab is identity plus its own state, so the set grows and
-    # shrinks one tab at a time. See book ch7 and `DECISIONS.md` `D-tabs`.
+    # shrinks one tab at a time. See book ch7 and `DECISIONS.md` `D_tabs`.
     #
     # == Sizing
     # Assign a {#rect} (typically from the surrounding {Layout}). One wider than
@@ -277,11 +277,11 @@ module Tuile
       # blank tail — or on a lower row, when the rect is taller than one —
       # selects 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
 
       # @return [String]
@@ -435,7 +435,7 @@ module Tuile
       # @return [Tab, nil] the tab painted at `point`; `nil` for a separator
       #   column, the blank tail, or a row the strip doesn't paint.
       def tab_at(point)
-        return nil unless extent.contains?(point)
+        return nil unless extent_rect.contains?(point)
 
         column = point.x - rect.left + @left_column
         found = segments.find { |_tab, start, width| column >= start && column < start + width }

data/lib/tuile/component/window.rb

@@ -22,11 +22,10 @@ module Tuile
         @border_right = 1
         self.caption = caption
         @content = nil
-        # Optional bottom-row widget slot (e.g. a search field), spanning the
-        # full inner width; and optional bottom-border chrome text embedded in
-        # the border row (mutually exclusive — the component, when present,
-        # occupies the row and hides the text).
-        @footer = nil
+        # The bottom row holds either a widget or chrome text, never both; see
+        # the precedence note on #footer=.
+        @footer_slot = Slot.new
+        add_child(@footer_slot) # appended: the footer paints over the border row
         @footer_text = StyledString::EMPTY
       end
 
@@ -34,7 +33,7 @@ module Tuile
 
       # @return [Component, nil] optional focusable component occupying the
       #   bottom border row, always spanning the full inner width.
-      attr_reader :footer
+      def footer = @footer_slot.content
 
       # @return [StyledString] optional chrome embedded into the bottom border
       #   line, mirroring {#caption} on the top line. Empty by default; hidden
@@ -56,48 +55,19 @@ module Tuile
         invalidate # repaint the bottom border row
       end
 
-      # Sets the bottom-row widget slot. The footer occupies the bottom border
-      # row, spanning the full inner width, and is positioned automatically;
-      # pass `nil` to remove.
+      # Mounts a component in the bottom border row, spanning the full inner
+      # width and positioned automatically; `nil` removes it.
       #
       # Precedence: a footer component present hides {#footer_text}; absent, the
       # text embeds into the bottom border. No window needs both at once.
-      #
-      # Symmetric to {#content=}: validates the new component, swaps parent
-      # pointers, invalidates the old/new components and the window border, and
-      # repairs focus via {#on_child_removed} if the removed footer held it.
       # @param new_footer [Component, nil]
+      # @raise [TypeError] if `new_footer` is neither a {Component} nor nil.
+      # @raise [ArgumentError] if `new_footer` already has a parent.
+      # @return [void]
       def footer=(new_footer)
-        unless new_footer.nil? || new_footer.is_a?(Component)
-          raise TypeError, "expected Component or nil, got #{new_footer.inspect}"
-        end
-        return if @footer == new_footer
-        if !new_footer.nil? && !new_footer.parent.nil?
-          raise ArgumentError, "#{new_footer} already has a parent #{new_footer.parent}"
-        end
-
-        old = @footer
-        # Same slot-swap order as HasContent#content=: notified last, so the
-        # focus repair cascades into the new occupant rather than the old.
-        detach_child(old) unless old.nil?
-        @footer = new_footer
-        unless new_footer.nil?
-          add_child(new_footer) # appended: the footer paints over the border row
-          new_footer.invalidate
-          layout_footer
-        end
+        @footer_slot.content = new_footer
+        layout_footer
         invalidate # repaint border row that the footer covers/uncovers
-        on_child_removed(old) unless old.nil?
-      end
-
-      # @param event [MouseEvent]
-      # @return [void]
-      def handle_mouse(event)
-        if @footer&.rect&.contains?(event.point)
-          @footer.handle_mouse(event)
-        else
-          super
-        end
       end
 
       # @param new_rect [Rect]
@@ -196,7 +166,7 @@ module Tuile
       # @return [StyledString]
       def bottom_border(inner_w, fg)
         interior =
-          if @footer || @footer_text.empty?
+          if footer || @footer_text.empty?
             StyledString.styled("─" * inner_w, fg: fg)
           else
             embedded = @footer_text.slice(0, inner_w)
@@ -207,15 +177,21 @@ module Tuile
 
       private
 
-      # Positions the footer over the bottom border row, spanning the full
+      # Positions the footer slot over the bottom border row, spanning the full
       # inner width (the only dimension a bottom-row widget needs — the window
       # already knows it).
+      #
+      # An unoccupied slot gets an *empty* rect, not the row — a {Slot} clears
+      # whatever it is given, which would blank the border underneath.
       # @return [void]
       def layout_footer
-        return if @footer.nil? || rect.empty?
+        if footer.nil? || rect.empty?
+          @footer_slot.rect = Rect.new(0, 0, 0, 0)
+          return
+        end
 
         width = [rect.width - 2, 0].max
-        @footer.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
+        @footer_slot.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
       end
     end
   end