tuile 0.7.0 → 0.8.0

data/lib/tuile/component/popup.rb

@@ -2,10 +2,20 @@
 
 module Tuile
   class Component
-    # A modal overlay that wraps any {Component} as its content. Popup itself
-    # paints nothing — it's a transparent host that handles modality
-    # ({#open} / {#close} / {#open?}, ESC/q to close), centers itself on the
-    # screen, and auto-sizes to the wrapped content.
+    # 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 auto-sizes to the
+    # wrapped content.
+    #
+    # 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 (still painted on top, still auto-sized)
+    # without taking focus or capturing input — the caller positions it (via
+    # {#rect=}) and drives it from app code. That is the building block for an
+    # autocomplete/slash-command list anchored to a {Component::TextField} or
+    # {Component::TextArea} caret: typing keeps focus (and the cursor) in the
+    # input, an {Component::TextInput#on_change} listener refills the list, and
+    # an {Component::TextInput#on_key} interceptor forwards Up/Down/Enter to it.
     #
     # The wrapped content fills the popup's full {#rect}; if you want a frame
     # and caption, wrap a {Component::Window} (or any subclass — including
@@ -27,12 +37,19 @@ module Tuile
 
       # @param content [Component, nil] initial content; can be set later via
       #   {#content=}. When provided here, the popup auto-sizes to fit.
-      def initialize(content: nil)
+      # @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).
+      def initialize(content: nil, modal: true)
         super()
+        @modal = modal
         @content = nil
         self.content = content unless content.nil?
       end
 
+      # @return [Boolean] whether this popup is modal. See {#initialize}.
+      def modal? = @modal
+
       def focusable? = true
 
       # Reassigns the popup's rect, escalating to a full scene repaint when an
@@ -85,9 +102,20 @@ module Tuile
         self.rect = rect.centered(screen.size)
       end
 
-      # @return [Integer] max height the popup will grow to fit its content,
-      #   defaults to 12. Override in a subclass to allow taller popups.
-      def max_height = 12
+      # @return [Integer] max height the popup will grow to fit its content.
+      #   Defers to the content's {Component#popup_max_height} advice when it
+      #   gives one, else defaults to 12. Override in a subclass to allow
+      #   taller popups regardless of content.
+      def max_height = @content&.popup_max_height || 12
+
+      # @return [Integer] min height the popup occupies even when its content
+      #   is shorter. Defers to the content's {Component#popup_min_height}
+      #   advice when it gives one, else defaults to 0 (size purely to
+      #   content) — so a {Component::LogWindow} stays readable while only a
+      #   few lines are in without callers wiring up a subclass. Override in a
+      #   subclass to keep any popup from collapsing to a couple of rows.
+      #   Capped at the same 4/5-of-screen ceiling {#update_rect} applies.
+      def min_height = @content&.popup_min_height || 0
 
       # Sets the popup's content and auto-sizes the popup to fit.
       # @param new_content [Component, nil]
@@ -114,11 +142,12 @@ module Tuile
         child_hint.empty? ? prefix : "#{prefix}  #{child_hint}"
       end
 
+      # `q` and ESC close the popup. The popup sits on the focus chain of
+      # whatever it wraps, so the key reaches here by bubbling up from the
+      # focused content after that content declined to handle it.
       # @param key [String]
       # @return [Boolean] true if the key was handled.
       def handle_key(key)
-        return true if super
-
         if [Keys::ESC, "q"].include?(key)
           close
           true
@@ -147,10 +176,16 @@ module Tuile
       # {#rect=}'s shrink/move detection fire a full repaint on every resize.
       # @return [void]
       def update_rect
+        ceiling = screen.size.height * 4 / 5
         size = @content.content_size.clamp_height(max_height)
-        size = size.clamp(Size.new(screen.size.width * 4 / 5, screen.size.height * 4 / 5))
-        r = Rect.new(0, 0, size.width, size.height)
-        r = r.centered(screen.size) if open?
+        size = size.clamp(Size.new(screen.size.width * 4 / 5, ceiling))
+        floor = min_height.clamp(0, ceiling)
+        size = Size.new(size.width, floor) if size.height < floor
+        # A non-modal overlay is positioned by the caller, so an open one keeps
+        # its current top-left when its content resizes; a modal popup recenters.
+        origin = open? && !modal? ? Point.new(rect.left, rect.top) : Point.new(0, 0)
+        r = Rect.new(origin.x, origin.y, size.width, size.height)
+        r = r.centered(screen.size) if open? && modal?
         self.rect = r
       end
     end

data/lib/tuile/component/text_area.rb

@@ -80,7 +80,7 @@ module Tuile
                    chunk = @text[r[:start], r[:length]] || ""
                    chunk + (" " * (rect.width - r[:length]))
                  end
-          screen.print TTY::Cursor.move_to(rect.left, rect.top + screen_row), background(line)
+          screen.buffer.set_line(rect.left, rect.top + screen_row, background(line))
         end
       end
 

data/lib/tuile/component/text_field.rb

@@ -60,7 +60,7 @@ module Tuile
         return if rect.empty?
 
         padded = @text + (" " * (rect.width - @text.length))
-        screen.print TTY::Cursor.move_to(rect.left, rect.top), background(padded)
+        screen.buffer.set_line(rect.left, rect.top, background(padded))
       end
 
       protected

data/lib/tuile/component/text_input.rb

@@ -31,6 +31,7 @@ module Tuile
         @text = +""
         @caret = 0
         @on_change = nil
+        @on_key = nil
         @on_escape = method(:default_on_escape)
       end
 
@@ -49,6 +50,20 @@ module Tuile
       # @return [Proc, Method, nil] one-arg callable, or nil.
       attr_accessor :on_change
 
+      # Optional interceptor consulted before the input's own key handling.
+      # Receives the pressed key; return a truthy value to consume it (the
+      # input then ignores that key), falsy to let normal editing proceed.
+      #
+      # The keyboard analog of {#on_change}: it lets app code layer behavior
+      # onto an input without subclassing. The motivating case is an
+      # autocomplete / slash-command overlay (a non-modal {Component::Popup}):
+      # while it is open the interceptor claims Up/Down/Enter/ESC and forwards
+      # them to the overlay's list, but lets ordinary characters fall through
+      # so typing keeps editing the field (and {#on_change} keeps refilling the
+      # list).
+      # @return [Proc, Method, nil] one-arg callable, or nil.
+      attr_accessor :on_key
+
       # Callback fired when ESC is pressed. Defaults to a closure that clears
       # focus (`screen.focused = nil`) so ESC visibly cancels text entry instead
       # of bubbling to the parent — and, in particular, instead of reaching the
@@ -88,14 +103,15 @@ module Tuile
         invalidate
       end
 
-      # Handles a key. Returns false when the component is inactive. Otherwise
-      # first runs the {Component#handle_key} shortcut search via `super`, then
-      # delegates to {#handle_text_input_key}.
+      # Handles a key. An {#on_key} interceptor (if set) gets first refusal —
+      # a truthy return consumes the key — otherwise it delegates to
+      # {#handle_text_input_key}. Dispatch ({ScreenPane#handle_key}) only routes
+      # keys here when this input is on the focus chain, so there is no
+      # {#active?} gate.
       # @param key [String]
       # @return [Boolean]
       def handle_key(key)
-        return false unless active?
-        return true if super
+        return true if @on_key&.call(key)
 
         handle_text_input_key(key)
       end
@@ -103,13 +119,13 @@ module Tuile
       protected
 
       # Renders `text` on the field's background well, looked up from the
-      # current {Screen#theme} at paint time: {Theme#active_bg} when this
-      # input is on the active (focus) chain, {Theme#input_bg} otherwise —
+      # current {Screen#theme} at paint time: {Theme#active_bg_color} when this
+      # input is on the active (focus) chain, {Theme#input_bg_color} otherwise —
       # visibly a field either way, distinctly highlighted when active.
       # @param text [String]
-      # @return [String] ANSI-rendered text.
+      # @return [StyledString] text on the field's background well.
       def background(text)
-        active? ? screen.theme.active_bg(text) : screen.theme.input_bg(text)
+        StyledString.styled(text, bg: active? ? screen.theme.active_bg_color : screen.theme.input_bg_color)
       end
 
       # Input filter for {#text=}. Subclasses override to truncate or reject

data/lib/tuile/component/text_view.rb

@@ -437,7 +437,7 @@ module Tuile
                     end
         (0...rect.height).each do |row|
           line = paintable_line(row + @top_line, row, scrollbar)
-          screen.print TTY::Cursor.move_to(rect.left, rect.top + row), line
+          screen.buffer.set_line(rect.left, rect.top + row, line)
         end
       end
 
@@ -904,15 +904,14 @@ module Tuile
       # @param index [Integer] 0-based index into `@physical_lines`.
       # @param row_in_viewport [Integer] 0-based row within the viewport.
       # @param scrollbar [VerticalScrollBar, nil]
-      # @return [String] paintable ANSI-encoded line exactly `rect.width`
-      #   columns wide. Body lines come pre-padded from {#rewrap}, so this
-      #   reduces to a memoized {StyledString#to_ansi} read plus an
-      #   ASCII-string concat of the scrollbar glyph when one is present.
+      # @return [StyledString] paintable line exactly `rect.width` columns wide.
+      #   Body lines come pre-padded from {#rewrap}, so this reduces to a lookup
+      #   plus a concat of the scrollbar glyph when one is present.
       def paintable_line(index, row_in_viewport, scrollbar)
         line = @physical_lines[index] || @blank_line
-        return line.to_ansi unless scrollbar
+        return line unless scrollbar
 
-        line.to_ansi + scrollbar.scrollbar_char(row_in_viewport)
+        line + StyledString.plain(scrollbar.scrollbar_char(row_in_viewport))
       end
 
       # A logical section of a {TextView}'s text — a contiguous run of

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.
@@ -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)