tuile 0.6.0 → 0.8.0

data/lib/tuile/component/window.rb

@@ -83,14 +83,6 @@ module Tuile
         @footer.nil? ? super : super + [@footer]
       end
 
-      # @param key [String]
-      # @return [Boolean]
-      def handle_key(key)
-        return @footer.handle_key(key) if @footer&.active?
-
-        super
-      end
-
       # @param event [MouseEvent]
       # @return [void]
       def handle_mouse(event)
@@ -197,14 +189,31 @@ module Tuile
         content.rect = Rect.new(rect.left + 1, rect.top + 1, rect.width - 1 - @border_right, rect.height - 2)
       end
 
-      # Paints the window border.
+      # Paints the window border into the {Screen#buffer}. Title is clipped to
+      # the inner width so the box never overflows {#rect}; when the window is
+      # active the whole border is drawn in {Theme#active_border_color}.
       # @return [void]
       def repaint_border
         return if rect.empty?
 
-        frame = build_frame(frame_caption)
-        frame = screen.theme.active_border(frame) if active?
-        screen.print frame
+        w = rect.width
+        h = rect.height
+        top = rect.top
+        left = rect.left
+        inner_w = [w - 2, 0].max
+        title = frame_caption.to_s
+        title = title[0, inner_w] if title.length > inner_w
+        dashes = "─" * (inner_w - title.length)
+
+        fg = active? ? screen.theme.active_border_color : nil
+        bar = StyledString::Style.new(fg: fg)
+        buf = screen.buffer
+        buf.set_line(left, top, StyledString.styled("┌#{title}#{dashes}┐", fg: fg))
+        (1..(h - 2)).each do |dy|
+          buf.set_char(left, top + dy, "│", bar)
+          buf.set_char(left + w - 1, top + dy, "│", bar)
+        end
+        buf.set_line(left, top + h - 1, StyledString.styled("└#{"─" * inner_w}┘", fg: fg)) if h >= 2
       end
 
       # The caption text as it appears in the rendered border, including the
@@ -215,32 +224,6 @@ module Tuile
         key_shortcut.nil? ? c : "[#{key_shortcut}]-#{c}"
       end
 
-      # Builds the border as a single string with embedded cursor-positioning
-      # escapes, mirroring the layout {TTY::Box.frame} used to produce. Title
-      # is clipped to fit the inner width so the box never overflows {#rect}.
-      # @param caption [String]
-      # @return [String]
-      def build_frame(caption)
-        w = @rect.width
-        h = @rect.height
-        top = @rect.top
-        left = @rect.left
-        inner_w = [w - 2, 0].max
-
-        title = caption.to_s
-        title = title[0, inner_w] if title.length > inner_w
-        dashes = "─" * (inner_w - title.length)
-
-        out = +""
-        out << TTY::Cursor.move_to(left, top) << "┌#{title}#{dashes}┐"
-        (1..(h - 2)).each do |dy|
-          out << TTY::Cursor.move_to(left, top + dy) << "│"
-          out << TTY::Cursor.move_to(left + w - 1, top + dy) << "│"
-        end
-        out << TTY::Cursor.move_to(left, top + h - 1) << "└#{"─" * inner_w}┘" if h >= 2
-        out
-      end
-
       private
 
       # Recomputes the window's natural size: content's natural size (or the

data/lib/tuile/component.rb

@@ -81,27 +81,22 @@ module Tuile
       children.each { |c| screen.invalidate(c) }
     end
 
-    # Called when a character is pressed on the keyboard.
+    # Called when a character is pressed on the keyboard. The default does
+    # nothing and reports the key as unhandled; input components
+    # ({Component::TextField}, {Component::List}, {Component::Button}, …)
+    # override it to act on keys they care about.
     #
-    # Also called for inactive components. Inactive component should just return
-    # false.
-    #
-    # Default implementation searches for a component with {#key_shortcut} and
-    # focuses it. The shortcut search is suppressed while the focused component
-    # owns the hardware cursor (e.g. a {Component::TextField} the user is
-    # typing into) so that hotkeys don't steal printable keys from the editor.
-    # @param key [String] a key.
+    # Dispatch is owned by {ScreenPane#handle_key}: a {#key_shortcut} match
+    # anywhere in the active scope is captured first (suppressed while a
+    # cursor-owner is mid-edit), then the key is delivered to {Screen#focused}
+    # and bubbles up its ancestor chain until some component handles it. A
+    # component therefore only ever receives keys when it is on the focus chain
+    # — or when app code hands it a key directly — so it acts on the key alone
+    # and must never gate on its own {#active?} state.
+    # @param _key [String] a key.
     # @return [Boolean] true if the key was handled, false if not.
-    def handle_key(key)
-      return false unless screen.cursor_position.nil?
-
-      c = find_shortcut_component(key)
-      if !c.nil?
-        screen.focused = c
-        true
-      else
-        false
-      end
+    def handle_key(_key)
+      false
     end
 
     # A global keyboard shortcut. When pressed, will focus this component.
@@ -190,7 +185,7 @@ 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.
@@ -293,6 +288,20 @@ module Tuile
     #   topmost popup. Empty by default; override to advertise shortcuts.
     def keyboard_hint = ""
 
+    # Advice to a wrapping {Component::Popup} on the minimum height this
+    # component prefers to occupy when shown in a popup. `nil` (the default)
+    # means no preference — the popup uses its own {Component::Popup#min_height}.
+    # Override in a content component that should not collapse to a couple of
+    # rows when sparse (e.g. {Component::LogWindow}).
+    # @return [Integer, nil]
+    def popup_min_height = nil
+
+    # Advice to a wrapping {Component::Popup} on the maximum height this
+    # component may grow to when shown in a popup. `nil` (the default) means
+    # no preference — the popup uses its own {Component::Popup#max_height}.
+    # @return [Integer, nil]
+    def popup_max_height = nil
+
     protected
 
     # @param parent [Component, nil]
@@ -354,12 +363,7 @@ module Tuile
     # component's rect.
     # @return [void]
     def clear_background
-      return if rect.empty?
-
-      spaces = " " * rect.width
-      (rect.top..(rect.top + rect.height - 1)).each do |row|
-        screen.print TTY::Cursor.move_to(rect.left, row), spaces
-      end
+      screen.buffer.fill(rect)
     end
   end
 end

data/lib/tuile/fake_screen.rb

@@ -25,10 +25,14 @@ module Tuile
       super
       @event_queue = FakeEventQueue.new
       @size = Size.new(160, 50)
+      @buffer.resize(@size) # super sized it to the test runner's TTY
       @prints = []
     end
 
-    # @return [Array<String>] whatever {#print} printed so far.
+    # @return [Array<String>] whatever {#print} / {#emit} produced so far.
+    #   Component painting lands in {#buffer}, not here — assert on
+    #   {Buffer#row_text} / {Buffer#row_ansi} / {Buffer#cell} for content, and
+    #   on `prints` for cursor and housekeeping escapes.
     attr_reader :prints
 
     # @return [void]
@@ -46,6 +50,15 @@ module Tuile
       @prints += args
     end
 
+    # Captures the assembled repaint frame instead of writing to the test
+    # runner's TTY. Lands in {#prints} so cursor/sync escapes can be asserted;
+    # painted content is read from {#buffer}.
+    # @param str [String]
+    # @return [void]
+    def emit(str)
+      @prints << str
+    end
+
     # @param component [Component] the component to check.
     # @return [Boolean]
     def invalidated?(component) = @invalidated.include?(component)

data/lib/tuile/keys.rb

@@ -156,9 +156,7 @@ 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
@@ -166,9 +164,7 @@ module Tuile
       # 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.
-      if char.start_with?("\e[?")
-        char += $stdin.read(1) until char.match?(/[\x40-\x7e]\z/)
-      end
+      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

@@ -45,6 +45,10 @@ module Tuile
       # App-level keyboard shortcuts dispatched by {#handle_key} before keys
       # reach the pane. See {#register_global_shortcut}.
       @global_shortcuts = {}
+      # The back buffer components paint into. {#repaint} flushes its diff to
+      # the terminal, so only changed cells are emitted (flicker-free on any
+      # terminal). Sized to the current viewport; {#layout} resizes it.
+      @buffer = Buffer.new(@size)
     end
 
     # Entry in the global shortcut registry: the block to run, whether it
@@ -56,6 +60,10 @@ module Tuile
     # @return [ScreenPane] the structural root of the component tree.
     attr_reader :pane
 
+    # @return [Buffer] the back buffer components paint into
+    #   ({Buffer#set_line} / {Buffer#fill} / {Buffer#set_char}).
+    attr_reader :buffer
+
     # Handler invoked when a {StandardError} escapes an event handler inside
     # the event loop (e.g. a {Component::TextField}'s `on_change` raises).
     #
@@ -206,7 +214,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
 
@@ -217,7 +225,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
@@ -232,7 +240,7 @@ module Tuile
     # @api private
     # @return [void]
     def refresh_status_bar
-      top_popup = @pane.popups.last
+      top_popup = @pane.modal_popup
       globals = global_shortcut_hints(popup_open: !top_popup.nil?)
       @pane.status_bar.text = if top_popup.nil?
                                 ["q #{@theme.hint("quit")}", *globals,
@@ -370,9 +378,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
@@ -391,7 +397,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
 
@@ -404,10 +410,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]
@@ -436,31 +457,16 @@ module Tuile
       @@instance&.close
     end
 
-    # Prints given strings. While {#repaint} is running, writes are
-    # accumulated into a frame buffer and flushed to the terminal as a
-    # single `$stdout.write` at the end of the cycle. This stops the
-    # emulator from rendering half-finished frames (e.g. a layout's
-    # clear-background pass before its children have re-painted), which
-    # was visible as a brief flicker when the auto-clear path triggers.
-    #
-    # Outside repaint, writes go straight to stdout. We deliberately
-    # don't raise on a "print outside repaint" — that would be a useful
-    # guardrail against components painting outside the repaint loop,
-    # but it'd force terminal-housekeeping writes (`Screen#clear`,
-    # mouse-tracking start/stop, cursor-show on teardown) to bypass
-    # this method entirely and write directly to `$stdout`. {FakeScreen}
-    # overrides `print` to capture every byte into its `@prints` array,
-    # and tests that exercise `run_event_loop` against a real {Screen}
-    # would otherwise leak escape sequences to the test runner's stdout.
-    # Keeping `print` as the single sink preserves that override seam.
+    # Writes terminal-housekeeping escapes straight to stdout: {#clear},
+    # mouse-tracking start/stop, the color-scheme notify toggles, cursor-show
+    # on teardown. Component painting does *not* go through here anymore — it
+    # writes into {#buffer}, which {#repaint} diffs and {#emit}s. {FakeScreen}
+    # overrides this (and {#emit}) to capture into `@prints` instead of the
+    # test runner's stdout.
     # @param args [String] stuff to print.
     # @return [void]
     def print(*args)
-      if @frame_buffer
-        args.each { |s| @frame_buffer << s.to_s }
-      else
-        Kernel.print(*args)
-      end
+      Kernel.print(*args)
     end
 
     # Repaints the screen; tries to be as effective as possible, by only
@@ -476,64 +482,61 @@ module Tuile
       # simple and very fast in common cases.
 
       did_paint = false
-      @frame_buffer = +""
-      begin
-        until @invalidated.empty?
-          # Defensive filter: a component can become detached between enqueue
-          # and drain (popup close, sibling removed mid-event-handling, focus
-          # repair). Detached components have no place on the screen and must
-          # never paint, even though Component#invalidate already gates them
-          # out — this catches the case where attachment changed since.
-          @invalidated.delete_if { |c| !c.attached? }
-          break if @invalidated.empty?
-
-          did_paint = true
-          popups = @pane.popups
-
-          # Partition invalidated components into tiled vs popup-tree. Sorting
-          # by depth across the whole tree would interleave them: a tiled
-          # 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) }
-
-          # Within the tiled tree, paint parents before children.
-          tiled.sort_by!(&:depth)
-
-          repaint = if tiled.empty?
-                      # Only popups need repaint — paint just their invalidated
-                      # components in depth order.
-                      popup_invalidated.sort_by(&:depth)
-                    else
-                      # Tiled components may overdraw popups; repaint each open
-                      # popup's full subtree on top, in stacking order
-                      # (parent-before-child within each popup).
-                      tiled + popups.flat_map { |p| collect_subtree(p) }
-                    end
-
-          @repainting = repaint.to_set
-          @invalidated.clear
-
-          # Don't call {#clear} before repaint — causes flickering, and only
-          # needed when @content doesn't cover the entire screen.
-          repaint.each(&:repaint)
-
-          # Repaint done, mark all components as up-to-date.
-          @repainting.clear
+      until @invalidated.empty?
+        # Defensive filter: a component can become detached between enqueue
+        # and drain (popup close, sibling removed mid-event-handling, focus
+        # repair). Detached components have no place on the screen and must
+        # never paint, even though Component#invalidate already gates them
+        # out — this catches the case where attachment changed since.
+        @invalidated.delete_if { |c| !c.attached? }
+        break if @invalidated.empty?
+
+        did_paint = true
+        popups = @pane.popups
+
+        # Build the repaint list in z-order, leaning on the tree itself rather
+        # than a depth sort. The pane's pre-order traversal already orders the
+        # tiled layer (content subtree + status bar) parent-before-child; the
+        # popups are the top layer and must paint last. The status bar is a
+        # *late* pane child yet sits under the popups, so a single pane.on_tree
+        # walk won't do — we collect the tiled layer first, then append popups.
+        popup_members = Set.new
+        popups.each { |p| p.on_tree { popup_members << _1 } }
+
+        # Tiled layer: invalidated non-popup components, in tree order.
+        repaint = []
+        tiled_invalidated = false
+        @pane.on_tree do |c|
+          next if popup_members.include?(c)
+          next unless @invalidated.include?(c)
+
+          repaint << c
+          tiled_invalidated = true
         end
-        position_cursor if did_paint
-        unless @frame_buffer.empty?
-          $stdout.write(@frame_buffer)
-          $stdout.flush
+
+        # Popups on top: the whole stack when a tiled repaint may have clobbered
+        # cells they share in the buffer, else just the invalidated popup
+        # components. Overdraw into the buffer is free (only net-visible cell
+        # changes reach the terminal), so reasserting the stack is cheap.
+        popups.each do |p|
+          p.on_tree { |c| repaint << c if tiled_invalidated || @invalidated.include?(c) }
         end
-      ensure
-        # Always release the frame buffer, even on exception, so any
-        # subsequent {#print} call (e.g. teardown emits during crash unwind)
-        # reaches stdout instead of being swallowed by a stranded buffer.
-        # The partial frame we hold here is incoherent — discard it.
-        @frame_buffer = nil
+
+        @repainting = repaint.to_set
+        @invalidated.clear
+
+        # Components write into @buffer; overdraw is free and correct here
+        # because the buffer only diffs net-visible changes to the terminal.
+        repaint.each(&:repaint)
+
+        # Repaint done, mark all components as up-to-date.
+        @repainting.clear
       end
+      return unless did_paint
+
+      # Flush only the changed cells, then reposition the cursor — all inside
+      # one synchronized-output batch so the terminal composites it atomically.
+      emit("#{Ansi::SYNC_BEGIN}#{@buffer.flush}#{cursor_sequence}#{Ansi::SYNC_END}")
     end
 
     # Returns the absolute screen coordinates where the hardware cursor should
@@ -575,7 +578,7 @@ module Tuile
     # @return [Boolean] true if focus moved.
     def cycle_focus(forward:)
       check_locked
-      scope = @pane.popups.last || @pane.content
+      scope = @pane.modal_popup || @pane.content
       return false if scope.nil?
 
       stops = []
@@ -594,25 +597,22 @@ module Tuile
       true
     end
 
-    # Collects a component and all its descendants in tree order
-    # (parent before children).
-    # @param component [Component]
-    # @return [Array<Component>]
-    def collect_subtree(component)
-      result = []
-      component.on_tree { result << it }
-      result
+    # The escape sequence positioning the hardware cursor for the current focus
+    # state: hidden when nothing owns it, else moved to the focused component's
+    # {Component#cursor_position} and shown. Appended to each frame's flush.
+    # @return [String]
+    def cursor_sequence
+      pos = cursor_position
+      pos.nil? ? TTY::Cursor.hide : "#{TTY::Cursor.move_to(pos.x, pos.y)}#{TTY::Cursor.show}"
     end
 
-    # Hides or moves the hardware cursor based on the current focus state.
+    # Writes an assembled frame (escape string) to the terminal. The single
+    # sink for repaint output; {FakeScreen} overrides it to capture instead.
+    # @param str [String]
     # @return [void]
-    def position_cursor
-      pos = cursor_position
-      if pos.nil?
-        print TTY::Cursor.hide
-      else
-        print TTY::Cursor.move_to(pos.x, pos.y), TTY::Cursor.show
-      end
+    def emit(str)
+      $stdout.write(str)
+      $stdout.flush
     end
 
     # Recalculates positions of all windows, and repaints the scene.
@@ -621,18 +621,12 @@ module Tuile
     # @return [void]
     def layout
       check_locked
+      @buffer.resize(size) unless @buffer.size == size
       needs_full_repaint
       @pane.rect = Rect.new(0, 0, size.width, size.height)
       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.
     #
@@ -643,10 +637,12 @@ module Tuile
     #      doesn't trap them.
     #   2. App-level shortcuts from {#register_global_shortcut}. An entry
     #      registered with `over_popups: true` always fires; one with the
-    #      default `over_popups: false` fires only when no popup is open
-    #      (otherwise the popup receives the key normally).
-    #   3. {ScreenPane#handle_key}, which routes to the topmost popup or
-    #      tiled content.
+    #      default `over_popups: false` fires only when no modal popup is open
+    #      (otherwise the modal popup receives the key normally). A non-modal
+    #      overlay doesn't suppress global shortcuts.
+    #   3. {ScreenPane#handle_key}, which captures a matching {#key_shortcut}
+    #      in the active scope, then delivers the key to {#focused} and bubbles
+    #      it up the focus chain.
     # @param key [String]
     # @return [Boolean] true if the key was handled by some window.
     def handle_key(key)
@@ -659,7 +655,7 @@ module Tuile
         true
       else
         shortcut = @global_shortcuts[key]
-        if !shortcut.nil? && (shortcut.over_popups || @pane.popups.empty?)
+        if !shortcut.nil? && (shortcut.over_popups || @pane.modal_popup.nil?)
           shortcut.block.call
           true
         else