tuile 0.5.0 → 0.7.0

data/lib/tuile/component/window.rb

@@ -19,9 +19,12 @@ module Tuile
         super()
         @border_right = 1
         @caption = caption
+        @content = nil
         # Optional bottom-row chrome that overlays the bottom border (e.g. a
         # search field).
         @footer = nil
+        @footer_sizing = Sizing::FILL
+        update_content_size
       end
 
       def focusable? = true
@@ -30,8 +33,25 @@ module Tuile
       #   row.
       attr_reader :footer
 
-      # Sets the bottom-row chrome slot. The footer overlays the bottom border at
-      # full inner width and is positioned automatically; pass `nil` to remove.
+      # @return [Sizing] how the footer's width is computed from the window's
+      #   inner width; defaults to {Sizing::FILL} (the footer spans the full
+      #   inner width). The footer's height is always 1 (the border row).
+      attr_reader :footer_sizing
+
+      # Sets the footer width policy and re-lays-out the footer.
+      # @param sizing [Sizing]
+      def footer_sizing=(sizing)
+        raise TypeError, "expected Sizing, got #{sizing.inspect}" unless sizing.is_a?(Sizing)
+        return if @footer_sizing == sizing
+
+        @footer_sizing = sizing
+        layout_footer
+        invalidate # repaint border cells the footer may have just vacated
+      end
+
+      # Sets the bottom-row chrome slot. The footer overlays the bottom border
+      # row and is positioned automatically — its width is governed by
+      # {#footer_sizing}; pass `nil` to remove.
       #
       # Symmetric to {#content=}: validates the new component, swaps parent
       # pointers, invalidates the old/new components and the window border, and
@@ -110,20 +130,36 @@ module Tuile
       def caption=(new_caption)
         @caption = new_caption
         invalidate
+        update_content_size
       end
 
-      # @return [Size] the size needed to fit the window's content, footer
-      #   (width only — footer overlays the bottom border), and caption,
-      #   plus the 2-character border. Returns {Size}`.new(2, 2)` when the
-      #   window has no content, footer, or caption.
-      def content_size
-        inner_w = [
-          content&.content_size&.width || 0,
-          @footer&.content_size&.width || 0,
-          frame_caption.length
-        ].max
-        inner_h = content&.content_size&.height || 0
-        Size.new(inner_w + 2, inner_h + 2)
+      # Sets the new content. Also recomputes the window's natural size.
+      # @param new_content [Component, nil]
+      def content=(new_content)
+        super
+        update_content_size
+      end
+
+      # Re-lays-out a {Sizing::WRAP_CONTENT} footer when the footer's natural
+      # size changes, and folds a content resize into the window's own
+      # natural size (whose change then bubbles to the window's parent — e.g.
+      # a {Popup} re-self-sizes). The footer deliberately does *not*
+      # participate in the window's {#content_size}: it is decoration
+      # overlaying the border, and must not drive the window's size — if it
+      # doesn't fit, it is clipped to the inner width.
+      # @param child [Component]
+      # @return [void]
+      def on_child_content_size_changed(child)
+        if child.equal?(@footer)
+          old_rect = @footer.rect
+          layout_footer
+          # Repaint on any footer geometry change: a shrinking footer vacates
+          # border cells that must be re-dashed (a growing one merely
+          # overdraws, but distinguishing isn't worth the code).
+          invalidate if @footer.rect != old_rect
+        else
+          update_content_size
+        end
       end
 
       # Fully repaints the window: both frame and contents.
@@ -150,6 +186,7 @@ module Tuile
         super
         # The shortcut key is shown in the caption — repaint.
         invalidate
+        update_content_size
       end
 
       protected
@@ -166,7 +203,7 @@ module Tuile
         return if rect.empty?
 
         frame = build_frame(frame_caption)
-        frame = Rainbow(frame).green if active?
+        frame = screen.theme.active_border(frame) if active?
         screen.print frame
       end
 
@@ -206,11 +243,28 @@ module Tuile
 
       private
 
+      # Recomputes the window's natural size: content's natural size (or the
+      # caption, whichever is wider) plus the 2-character border. The footer
+      # is deliberately excluded — see {#on_child_content_size_changed}. A
+      # window with no content or caption sizes to `Size.new(2, 2)` (bare
+      # border).
+      # @return [void]
+      def update_content_size
+        inner_w = [content&.content_size&.width || 0, frame_caption.length].max
+        inner_h = content&.content_size&.height || 0
+        self.content_size = Size.new(inner_w + 2, inner_h + 2)
+      end
+
+      # Positions the footer over the bottom border row, with its width
+      # resolved by {#footer_sizing} against the inner width. A
+      # {Sizing::WRAP_CONTENT} footer with zero natural width gets an empty
+      # rect — i.e. it is invisible, as if never assigned.
       # @return [void]
       def layout_footer
         return if @footer.nil? || rect.empty?
 
-        width = [rect.width - 2, 0].max
+        available = [rect.width - 2, 0].max
+        width = @footer_sizing.resolve(available, @footer.content_size.width)
         @footer.rect = Rect.new(rect.left + 1, rect.top + rect.height - 1, width, 1)
       end
     end

data/lib/tuile/component.rb

@@ -12,6 +12,8 @@ module Tuile
     def initialize
       @rect = Rect.new(0, 0, 0, 0)
       @active = false
+      @content_size = Size::ZERO
+      @on_theme_changed = nil
     end
 
     # @return [Rect] the rectangle the component occupies on screen.
@@ -188,13 +190,45 @@ module Tuile
     # @return [void]
     def on_tree(&block)
       block.call(self)
-      children.each { it.on_tree(&block) }
+      children.each { _1.on_tree(&block) }
     end
 
     # Called when the component receives focus.
     # @return [void]
     def on_focus; end
 
+    # Optional zero-arg listener fired by the base {#on_theme_changed} — the
+    # composition-style alternative to overriding the method, for apps that
+    # assemble stock components rather than subclass:
+    #
+    #   label.on_theme_changed = -> { label.text = render_status_line }
+    #
+    # @return [Proc, nil]
+    attr_writer :on_theme_changed
+
+    # Called on every attached component (pre-order, popups included) when
+    # {Screen#theme} changes — at {Screen#theme=} / {Screen#theme_def=}
+    # assignment and on OS appearance flips.
+    #
+    # Built-in components read {Screen#theme} at paint time, so their accents
+    # restyle automatically; this hook exists for *content* whose colors the
+    # app baked in from the old theme — a {Label#text} / {List#lines} /
+    # {TextView#text} {StyledString} styled with `theme[:accent]` and the
+    # like. Only the app knows which of its colors were theme-derived (as
+    # opposed to inherent to the data, e.g. log-level colors), so it rebuilds
+    # them here, re-running the same code that rendered them initially.
+    #
+    # Runs on the UI thread; {Screen#theme} already returns the new theme.
+    # Mutating content (`text=`, `lines=`, …) is safe — repaint coalesces per
+    # event-loop tick. Do not assign {Screen#theme=} from inside the hook.
+    #
+    # Subclasses overriding this should call `super` so an assigned
+    # {#on_theme_changed=} listener keeps firing.
+    # @return [void]
+    def on_theme_changed
+      @on_theme_changed&.call
+    end
+
     # @return [Boolean] true if this component's tree is currently mounted on
     #   the {Screen}, i.e. its root is the {ScreenPane}.
     def attached? = root == screen.pane
@@ -225,12 +259,27 @@ module Tuile
 
     # The {Size} big enough to show the entire component contents without
     # scrolling. Plain components have no intrinsic content and report
-    # {Size::ZERO}; container/decorative components (e.g. {Label}, {List},
-    # {Layout}, {Window}) override this to fold in their content's natural
-    # extent. Used by callers like {Component::Popup} to auto-size to
-    # whatever content was assigned, regardless of its concrete type.
+    # {Size::ZERO}; content-bearing components (e.g. {Label}, {List},
+    # {TextView}, {Window}) maintain it eagerly via {#content_size=} from
+    # their mutators, so reads are O(1). Used by callers like
+    # {Component::Popup} to auto-size to whatever content was assigned,
+    # regardless of its concrete type, and by {Sizing::WRAP_CONTENT} slots.
     # @return [Size]
-    def content_size = Size::ZERO
+    attr_reader :content_size
+
+    # Called by a child component whose {#content_size} just changed (fired
+    # from the child's {#content_size=}). Does nothing by default — a plain
+    # container is not size-coupled to its children. Containers that derive
+    # their own natural size or child layout from a child's natural size
+    # override this (e.g. {Component::Window} re-lays-out a
+    # {Sizing::WRAP_CONTENT} footer and recomputes its own size from content;
+    # {Component::Popup} re-self-sizes). If the receiver's own
+    # {#content_size} changes as a consequence, its {#content_size=} notifies
+    # *its* parent in turn — so the event bubbles exactly as far as geometry
+    # keeps changing, and stops where it doesn't.
+    # @param child [Component] the resized direct child.
+    # @return [void]
+    def on_child_content_size_changed(child); end
 
     # Where the hardware terminal cursor should sit when this component is the
     # cursor owner. Returns `nil` to indicate the cursor should be hidden. The
@@ -253,6 +302,26 @@ module Tuile
     # @return [void]
     def on_width_changed; end
 
+    # Memoizes the component's natural size and notifies {#parent} via
+    # {#on_child_content_size_changed} when the value actually changed.
+    # Subclasses call this from their content mutators (`text=`, `add_lines`,
+    # `caption=`, …) instead of caching ad-hoc.
+    #
+    # Call this as the *last* step of a mutator: the parent hook may
+    # reentrantly reposition this component (assign {#rect} — e.g. {Window}
+    # re-laying-out a wrap-content footer, or {Popup} re-self-sizing), which
+    # triggers {#on_width_changed} and {#repaint}-related recomputation, so
+    # all internal state must already be consistent.
+    # @param new_size [Size]
+    # @return [void]
+    def content_size=(new_size)
+      raise TypeError, "expected Size, got #{new_size.inspect}" unless new_size.is_a?(Size)
+      return if @content_size == new_size
+
+      @content_size = new_size
+      parent&.on_child_content_size_changed(self)
+    end
+
     # Invalidates the component: {Screen} records this component as
     # needs-repaint and once all events are processed, will call {#repaint}.
     #

data/lib/tuile/event_queue.rb

@@ -184,6 +184,31 @@ module Tuile
       def size = Size.new(width, height)
     end
 
+    # The terminal's color scheme changed — the user flipped the OS between
+    # light and dark appearance. Terminals supporting mode 2031 (kitty,
+    # foot, contour, ghostty, …) push the DSR-style report `\e[?997;1n`
+    # (dark) / `\e[?997;2n` (light) once {Screen#run_event_loop} enables
+    # the mode via {TerminalBackground::NOTIFY_ON}; the key thread parses
+    # it into this event and {Screen#event_loop} follows by assigning the
+    # matching {Theme}.
+    #
+    # @!attribute [r] scheme
+    #   @return [Symbol] `:light` or `:dark`.
+    class ColorSchemeEvent < Data.define(:scheme)
+      # The DSR-style color-scheme report: `\e[?997;1n` dark, `\e[?997;2n`
+      # light.
+      # @return [Regexp]
+      REPORT = /\A\e\[\?997;([12])n\z/
+
+      # @param key [String] key read via {Keys.getkey}.
+      # @return [ColorSchemeEvent, nil] nil when `key` is not a
+      #   color-scheme report.
+      def self.parse(key)
+        match = REPORT.match(key)
+        match && new(match[1] == "2" ? :light : :dark)
+      end
+    end
+
     # Emitted once when the queue is cleared, all messages are processed and the
     # event loop will block waiting for more messages. Perfect time for
     # repainting windows.
@@ -278,8 +303,7 @@ module Tuile
       @key_thread = Thread.new do
         loop do
           key = Keys.getkey
-          event = MouseEvent.parse(key)
-          event = KeyEvent.new(key) if event.nil?
+          event = MouseEvent.parse(key) || ColorSchemeEvent.parse(key) || KeyEvent.new(key)
           post event
         end
       rescue StandardError => e

data/lib/tuile/fake_screen.rb

@@ -54,5 +54,13 @@ module Tuile
     def invalidated_clear
       @invalidated.clear
     end
+
+    private
+
+    # No terminal probing in tests: skip {TerminalBackground.detect}
+    # (which would write an OSC 11 query to the test runner's TTY and
+    # steal its input) and pin the deterministic default.
+    # @return [Symbol]
+    def detect_scheme = :dark
   end
 end

data/lib/tuile/keys.rb

@@ -156,9 +156,15 @@ module Tuile
       # sequence is fixed-length: 3 bytes after `\e[M`), drain the remainder
       # with a blocking read so the parser downstream sees a complete event
       # instead of leaking tail bytes as keypresses.
-      if char.start_with?("\e[M") && char.bytesize < 6
-        char += $stdin.read(6 - char.bytesize)
-      end
+      char += $stdin.read(6 - char.bytesize) if char.start_with?("\e[M") && char.bytesize < 6
+
+      # Private-mode CSI reports (`\e[?` params… final byte in 0x40..0x7E)
+      # can outgrow the 5-byte gulp above — the mode-2031 color-scheme
+      # notification `\e[?997;1n` (see {EventQueue::ColorSchemeEvent}) is 8
+      # bytes after the `\e`. Drain to the final byte with blocking 1-byte
+      # reads so the tail doesn't surface as phantom keypresses. Keyboard
+      # sequences never start with `\e[?`, so this can't eat a regular key.
+      char += $stdin.read(1) while char.start_with?("\e[?") && !char.match?(/[\x40-\x7e]\z/)
 
       char
     end

data/lib/tuile/rect.rb

@@ -49,6 +49,18 @@ module Tuile
       point.x >= left && point.x < left + width && point.y >= top && point.y < top + height
     end
 
+    # @param other [Rect] another rectangle.
+    # @return [Boolean] true if `other` lies entirely within this rectangle.
+    #   Uses the same half-open edges as {#contains?} (right/bottom exclusive).
+    #   An {#empty? empty} `other` covers no cells, so it is trivially contained.
+    def contains_rect?(other)
+      return true if other.empty?
+
+      other.left >= left && other.top >= top &&
+        other.left + other.width <= left + width &&
+        other.top + other.height <= top + height
+    end
+
     # @return [Size]
     def size = Size.new(width, height)
 

data/lib/tuile/screen.rb

@@ -35,6 +35,9 @@ module Tuile
       @repainting = Set.new
       # Until the event loop is run, we pretend we're in the UI thread.
       @pretend_ui_lock = true
+      @scheme = detect_scheme
+      @theme_def = ThemeDef.default
+      @theme = @theme_def.for(@scheme)
       # Structural root of the component tree: holds tiled content, popup
       # stack and status bar.
       @pane = ScreenPane.new
@@ -93,6 +96,66 @@ module Tuile
     # @return [Size] current screen size.
     attr_reader :size
 
+    # The color {Theme} built-in components read at paint time: the member
+    # of {#theme_def} matching the terminal background detected at
+    # construction (see {TerminalBackground.detect}; inconclusive means
+    # dark). While the event loop runs, terminals supporting mode 2031
+    # push OS appearance changes ({EventQueue::ColorSchemeEvent}) and the
+    # screen re-picks from {#theme_def}.
+    # @return [Theme]
+    attr_reader :theme
+
+    # The app's {ThemeDef} — the dark/light {Theme} pair the screen picks
+    # {#theme} from, at startup and on every OS appearance flip. Starts as
+    # {ThemeDef.default} ({ThemeDef::DEFAULT} unless reassigned — tests
+    # do, see {ThemeDef.default=}). Assigning a custom definition is the
+    # durable way to theme an app: unlike a bare {#theme=}, it survives
+    # the user toggling the OS appearance.
+    # @return [ThemeDef]
+    attr_reader :theme_def
+
+    # Replaces the theme definition and immediately applies the member
+    # matching the current color scheme (via {#theme=}, so the whole UI
+    # restyles — or nothing repaints if that member equals the current
+    # theme).
+    # @param theme_def [ThemeDef]
+    # @return [void]
+    def theme_def=(theme_def)
+      raise TypeError, "expected ThemeDef, got #{theme_def.inspect}" unless theme_def.is_a?(ThemeDef)
+
+      check_locked
+      @theme_def = theme_def
+      self.theme = @theme_def.for(@scheme)
+    end
+
+    # Replaces the theme and restyles the whole UI: fires
+    # {Component#on_theme_changed} across the attached tree (so the app can
+    # rebuild styled content whose colors were derived from the old theme),
+    # refreshes the status bar and invalidates every attached component so
+    # the next repaint uses the new colors. No-op when `new_theme` equals
+    # the current theme.
+    #
+    # This is a transient override: the next OS appearance flip re-picks
+    # from {#theme_def} and replaces it. To theme an app durably, assign
+    # {#theme_def=} instead.
+    #
+    # Note status-bar hints supplied by the host as preformatted strings
+    # (see {#register_global_shortcut}) have their colors baked in and are
+    # not restyled by this.
+    # @param new_theme [Theme]
+    # @return [void]
+    def theme=(new_theme)
+      raise TypeError, "expected Theme, got #{new_theme.inspect}" unless new_theme.is_a?(Theme)
+
+      check_locked
+      return if @theme == new_theme
+
+      @theme = new_theme
+      @pane&.on_tree(&:on_theme_changed)
+      refresh_status_bar
+      needs_full_repaint
+    end
+
     # @return [Array<Component>] currently active popup components (forwarded
     #   to {ScreenPane}). The array must not be modified!
     def popups = @pane.popups
@@ -143,7 +206,7 @@ module Tuile
       check_locked
       if focused.nil?
         @focused = nil
-        @pane.on_tree { it.active = false }
+        @pane.on_tree { _1.active = false }
       else
         raise Tuile::Error, "#{focused} is not attached to this screen" if focused.root != @pane
 
@@ -154,7 +217,7 @@ module Tuile
           active << cursor
           cursor = cursor.parent
         end
-        @pane.on_tree { it.active = active.include?(it) }
+        @pane.on_tree { _1.active = active.include?(_1) }
         @focused.on_focus
       end
       refresh_status_bar
@@ -172,7 +235,7 @@ module Tuile
       top_popup = @pane.popups.last
       globals = global_shortcut_hints(popup_open: !top_popup.nil?)
       @pane.status_bar.text = if top_popup.nil?
-                                ["q #{Rainbow("quit").cadetblue}", *globals,
+                                ["q #{@theme.hint("quit")}", *globals,
                                  active_window&.keyboard_hint].compact.reject(&:empty?).join("  ")
                               else
                                 [*globals, top_popup.keyboard_hint].reject(&:empty?).join("  ")
@@ -224,10 +287,15 @@ module Tuile
       @pretend_ui_lock = false
       $stdin.echo = false
       print MouseEvent.start_tracking if capture_mouse
+      # Follow OS light/dark flips live: terminals supporting mode 2031
+      # push color-scheme reports that the key thread turns into
+      # {EventQueue::ColorSchemeEvent}s.
+      print TerminalBackground::NOTIFY_ON
       $stdin.raw do
         event_loop
       end
     ensure
+      print TerminalBackground::NOTIFY_OFF
       print MouseEvent.stop_tracking if capture_mouse
       print TTY::Cursor.show
       $stdin.echo = true
@@ -272,7 +340,7 @@ module Tuile
     #
     #   screen.register_global_shortcut(Keys::CTRL_L,
     #                                   over_popups: true,
-    #                                   hint: "^L #{Rainbow("log").cadetblue}") do
+    #                                   hint: "^L #{screen.theme.hint("log")}") do
     #     log_popup.open
     #   end
     #
@@ -283,8 +351,9 @@ module Tuile
     #   (default), the shortcut is suppressed while any popup is open and
     #   the popup gets the key instead.
     # @param hint [String, nil] preformatted status-bar hint (e.g.
-    #   `"^L #{Rainbow("log").cadetblue}"`). When nil (default) the shortcut
-    #   is silent in the status bar.
+    #   `"^L #{screen.theme.hint("log")}"`). When nil (default) the shortcut
+    #   is silent in the status bar. The colors are baked into the string,
+    #   so a later {#theme=} does not restyle it — re-register if needed.
     # @yield invoked with no arguments when `key` is pressed.
     # @return [void]
     def register_global_shortcut(key, over_popups: false, hint: nil, &block)
@@ -301,9 +370,7 @@ module Tuile
         raise ArgumentError,
               "#{key == Keys::TAB ? "TAB" : "SHIFT_TAB"} is reserved for focus navigation"
       end
-      unless hint.nil? || hint.is_a?(String)
-        raise ArgumentError, "hint must be a String or nil, got #{hint.inspect}"
-      end
+      raise ArgumentError, "hint must be a String or nil, got #{hint.inspect}" unless hint.nil? || hint.is_a?(String)
 
       @global_shortcuts[key] = Shortcut.new(block: block, over_popups: over_popups, hint: hint)
       refresh_status_bar
@@ -322,7 +389,7 @@ module Tuile
     def active_window
       check_locked
       result = nil
-      @pane.content&.on_tree { result = it if it.is_a?(Component::Window) && it.active? }
+      @pane.content&.on_tree { result = _1 if _1.is_a?(Component::Window) && _1.active? }
       result
     end
 
@@ -335,10 +402,25 @@ module Tuile
     # @return [void]
     def remove_popup(window)
       check_locked
+      return unless @pane.has_popup?(window)
+
       @pane.remove_popup(window)
       needs_full_repaint
     end
 
+    # Invalidates the entire attached tree, forcing every component to repaint
+    # on the next cycle. Needed whenever something overdraws the scene without
+    # clipping and then exposes what was underneath — a closing popup
+    # ({#remove_popup}), or a popup that shrinks or moves so its new {#rect} no
+    # longer covers the cells it previously painted ({Component::Popup#rect=}).
+    # The popup-only fast path in {#repaint} can't clear those vacated cells on
+    # its own, so we accept the cost of a full repaint.
+    # @api private
+    # @return [void]
+    def needs_full_repaint
+      @pane&.on_tree { invalidate _1 }
+    end
+
     # Internal — use {Component::Popup#open?} instead.
     # @api private
     # @param window [Component::Popup]
@@ -426,8 +508,8 @@ module Tuile
           # grandchild (depth 3) sorts after a popup's content (depth 2) and
           # overdraws it.
           popup_tree = Set.new
-          popups.each { |p| p.on_tree { popup_tree << it } }
-          tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(it) }
+          popups.each { |p| p.on_tree { popup_tree << _1 } }
+          tiled, popup_invalidated = @invalidated.to_a.partition { !popup_tree.include?(_1) }
 
           # Within the tiled tree, paint parents before children.
           tiled.sort_by!(&:depth)
@@ -476,6 +558,27 @@ module Tuile
 
     private
 
+    # Startup color scheme: `:light` when {TerminalBackground.detect}
+    # reports a light terminal background, `:dark` otherwise (including
+    # when detection is inconclusive). Runs in the constructor — the
+    # OSC 11 reply arrives on stdin, which is only safe to read before
+    # {EventQueue#start_key_thread} owns it. {FakeScreen} overrides this
+    # to pin `:dark`, keeping specs deterministic and off the test
+    # runner's TTY.
+    # @return [Symbol] `:dark` or `:light`.
+    def detect_scheme
+      TerminalBackground.detect == :light ? :light : :dark
+    end
+
+    # An OS appearance flip arrived (mode-2031 report): remember the
+    # scheme and apply the matching member of {#theme_def}.
+    # @param scheme [Symbol] `:dark` or `:light`.
+    # @return [void]
+    def on_color_scheme(scheme)
+      @scheme = scheme
+      self.theme = @theme_def.for(@scheme)
+    end
+
     # Walks the current modal scope in pre-order, collects tab stops, and
     # advances focus by one (wrapping). When the focused component isn't in
     # the tab order (e.g. focus is parked on a popup/window chrome with no
@@ -510,7 +613,7 @@ module Tuile
     # @return [Array<Component>]
     def collect_subtree(component)
       result = []
-      component.on_tree { result << it }
+      component.on_tree { result << _1 }
       result
     end
 
@@ -536,13 +639,6 @@ module Tuile
       repaint
     end
 
-    # Called after a popup is closed. Since a popup can cover any window,
-    # top-level component or other popups, we need to redraw everything.
-    # @return [void]
-    def needs_full_repaint
-      @pane&.on_tree { invalidate it }
-    end
-
     # A key has been pressed on the keyboard. Handle it, or forward to active
     # window.
     #
@@ -596,6 +692,8 @@ module Tuile
         when EventQueue::TTYSizeEvent
           @size = event.size
           layout
+        when EventQueue::ColorSchemeEvent
+          on_color_scheme(event.scheme)
         when EventQueue::EmptyQueueEvent
           repaint
         when Proc

data/lib/tuile/screen_pane.rb

@@ -140,7 +140,7 @@ module Tuile
     # @param event [MouseEvent]
     # @return [void]
     def handle_mouse(event)
-      clicked = @popups.reverse_each.find { it.rect.contains?(event.point) }
+      clicked = @popups.reverse_each.find { _1.rect.contains?(event.point) }
       clicked = @content if clicked.nil? && @popups.empty?
       clicked&.handle_mouse(event)
     end

data/lib/tuile/sizing.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Tuile
+  # A sizing policy for a slot whose position is managed by a parent
+  # component (e.g. {Component::Window#footer}). Resolves one dimension at a
+  # time via {#resolve}, so the same value works for widths and heights.
+  #
+  # Three policies exist:
+  #
+  # - {FILL} — take everything the slot offers;
+  # - {WRAP_CONTENT} — take the component's natural extent (its
+  #   {Component#content_size}), clamped to the slot;
+  # - {.fixed} — take exactly the given number of cells, clamped to the slot.
+  #
+  # Note that {WRAP_CONTENT} only makes sense for components that report a
+  # natural {Component#content_size} ({Component::Label}, {Component::Button},
+  # {Component::List}, …). Input components ({Component::TextField} et al.)
+  # report {Size::ZERO}, so a wrap-content slot collapses to zero width —
+  # i.e. the component becomes invisible. Use {.fixed} or {FILL} for those.
+  #
+  # @!attribute [r] mode
+  #   @return [Symbol] `:fill`, `:wrap_content` or `:fixed`.
+  # @!attribute [r] amount
+  #   @return [Integer, nil] the cell count for `:fixed`; `nil` otherwise.
+  class Sizing < Data.define(:mode, :amount)
+    # @param amount [Integer] the number of cells to occupy; 0 or greater.
+    # @return [Sizing] a fixed-size policy.
+    def self.fixed(amount)
+      raise TypeError, "expected Integer, got #{amount.inspect}" unless amount.is_a?(Integer)
+      raise ArgumentError, "amount must not be negative, got #{amount}" if amount.negative?
+
+      new(mode: :fixed, amount: amount)
+    end
+
+    # Resolves one dimension of a slot.
+    # @param available [Integer] cells the slot offers; 0 or greater.
+    # @param content [Integer] the component's natural extent on this axis
+    #   (one dimension of its {Component#content_size}).
+    # @return [Integer] the resolved extent, always in `0..available`.
+    def resolve(available, content)
+      case mode
+      when :fill then available
+      when :fixed then amount.clamp(0, available)
+      when :wrap_content then content.clamp(0, available)
+      else raise ArgumentError, "unknown mode #{mode.inspect}"
+      end
+    end
+
+    # Occupy everything the slot offers.
+    # @return [Sizing]
+    FILL = new(mode: :fill, amount: nil)
+
+    # Occupy the component's natural {Component#content_size}, clamped to the
+    # slot. Components reporting {Size::ZERO} collapse to invisibility — see
+    # the class doc.
+    # @return [Sizing]
+    WRAP_CONTENT = new(mode: :wrap_content, amount: nil)
+  end
+end