tuile 0.7.0 → 0.9.0

data/lib/tuile/component/list.rb

@@ -147,7 +147,6 @@ module Tuile
         update_top_line_if_auto_scroll
         notify_cursor_changed
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Without a block, returns the current lines. With a block, fully
@@ -194,7 +193,6 @@ module Tuile
         update_top_line_if_auto_scroll
         notify_cursor_changed
         invalidate
-        grow_content_size(new_lines)
       end
 
       def focusable? = true
@@ -204,11 +202,7 @@ module Tuile
       # @param key [String] a key.
       # @return [Boolean] true if the key was handled.
       def handle_key(key)
-        if !active?
-          false
-        elsif super
-          true
-        elsif key == Keys::PAGE_UP
+        if key == Keys::PAGE_UP
           move_top_line_by(-viewport_lines)
           true
         elsif key == Keys::PAGE_DOWN
@@ -288,7 +282,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, row + rect.top), line
+          screen.buffer.set_line(rect.left, row + rect.top, line)
         end
       end
 
@@ -296,6 +290,8 @@ module Tuile
       class Cursor
         # @param position [Integer] the initial cursor position.
         def initialize(position: 0)
+          raise "invalid position #{position}" unless position.is_a? Integer
+
           @position = position
         end
 
@@ -430,6 +426,8 @@ module Tuile
           #   empty.
           # @param position [Integer] initial position.
           def initialize(positions, position: positions[0])
+            raise "positions are empty" if positions.empty?
+
             @positions = positions.sort
             position = @positions[@positions.rindex { _1 < position } || 0] unless @positions.include?(position)
             super(position: position)
@@ -508,30 +506,6 @@ module Tuile
 
       private
 
-      # Natural size from scratch: longest line's display width plus the two
-      # single-space gutters {#pad_to_row} adds, × line count. An empty list
-      # is {Size::ZERO} (no gutters for no content).
-      # @return [Size]
-      def compute_content_size
-        content_w = @lines.map(&:display_width).max || 0
-        width = @lines.empty? ? 0 : content_w + 2
-        Size.new(width, @lines.size)
-      end
-
-      # Incremental {#content_size} update for appends: folds just the
-      # appended lines into the running maximum, keeping {#add_lines}
-      # O(appended) instead of re-scanning the whole list (LogWindow appends
-      # a line per log statement).
-      # @param appended [Array<StyledString>] the just-appended lines
-      #   (already concatenated onto {@lines}).
-      # @return [void]
-      def grow_content_size(appended)
-        return if appended.empty?
-
-        appended_w = appended.map(&:display_width).max + 2
-        self.content_size = Size.new([content_size.width, appended_w].max, @lines.size)
-      end
-
       # Coerces and flattens a list of input entries into trimmed
       # {StyledString} lines. Each entry becomes a {StyledString} (String
       # via {StyledString.parse}, StyledString passed through, anything else
@@ -759,15 +733,14 @@ module Tuile
       # @param row_in_viewport [Integer] 0-based row within the viewport.
       # @param scrollbar [VerticalScrollBar, nil] scrollbar instance, or nil
       #   if not shown.
-      # @return [String] paintable ANSI-encoded line exactly `rect.width`
-      #   columns wide; highlighted if cursor is here.
+      # @return [StyledString] paintable line exactly `rect.width` columns wide;
+      #   highlighted if cursor is here.
       def paintable_line(index, row_in_viewport, scrollbar)
         base = index < @lines.size ? @padded_lines[index] : @blank_padded
         is_cursor = (active? || @show_cursor_when_inactive) && index < @lines.size && @cursor.position == index
         styled = is_cursor ? base.with_bg(screen.theme.active_bg_color) : base
-        out = styled.to_ansi
-        out += scrollbar.scrollbar_char(row_in_viewport) if scrollbar
-        out
+        styled += StyledString.plain(scrollbar.scrollbar_char(row_in_viewport)) if scrollbar
+        styled
       end
     end
   end

data/lib/tuile/component/log_window.rb

@@ -15,11 +15,12 @@ module Tuile
       # @param caption [String]
       def initialize(caption = "Log")
         super
-        list = Component::List.new
-        list.auto_scroll = true
-        # Allow scrolling when a long stacktrace is logged.
-        list.cursor = Component::List::Cursor.new
-        self.content = list
+        view = Component::TextView.new
+        # Word-wrap long lines (stacktraces, wide log records) rather than
+        # ellipsizing them as a {List} would — a truncated log line hides the
+        # very detail you opened the log to read.
+        view.auto_scroll = true
+        self.content = view
         self.scrollbar = true
       end
 

data/lib/tuile/component/picker_window.rb

@@ -50,11 +50,13 @@ module Tuile
       # @return [Proc, nil]
       attr_accessor :on_pick
 
+      # Handles an option-key press. Reached by bubbling: the inner {List}
+      # (the focused component) sees the key first and handles cursor/Enter
+      # picks; anything it declines bubbles up here, where a key matching an
+      # option's `key` picks that option.
       # @param key [String]
       # @return [Boolean]
       def handle_key(key)
-        return true if super
-
         if @options.any? { _1.key == key }
           select_option(key)
           true

data/lib/tuile/component/popup.rb

@@ -2,10 +2,32 @@
 
 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 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 (still painted on top) 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.
+    # Such a caller owns the list data, so it sizes the overlay itself
+    # (`overlay.size = Size.new(longest, [items.size, 8].min)`) — still
+    # caller-decides, top-down.
     #
     # The wrapped content fills the popup's full {#rect}; if you want a frame
     # and caption, wrap a {Component::Window} (or any subclass — including
@@ -26,15 +48,43 @@ module Tuile
       include Component::HasContent
 
       # @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)
+      #   {#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}
+      #   is clamped to the screen. Defaults to {Fraction::HALF}.
+      def initialize(content: nil, modal: true, size: Fraction::HALF)
         super()
+        @modal = modal
+        @size = size
         @content = nil
         self.content = content unless content.nil?
+        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
+
       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),
+      # 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
+        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
@@ -50,20 +100,21 @@ module Tuile
         screen.needs_full_repaint if open? && !new_rect.contains_rect?(old_rect)
       end
 
-      # Mounts this popup on the {Screen}. Recomputes the popup's size from
-      # the current content first, so reopening a popup whose content has
-      # grown or shrunk while closed picks up the new size.
+      # Mounts this popup on the {Screen}, re-resolving its {#size} against the
+      # current screen first.
       # @return [void]
       def open
-        update_rect unless @content.nil?
+        reposition
         screen.add_popup(self)
       end
 
       # Constructs and opens a popup in one call.
       # @param content [Component, nil]
+      # @param modal [Boolean] see {#initialize}.
+      # @param size [Size, Fraction] see {#initialize}.
       # @return [Popup] the opened popup.
-      def self.open(content: nil)
-        Popup.new(content: content).tap(&:open)
+      def self.open(content: nil, modal: true, size: Fraction::HALF)
+        Popup.new(content: content, modal: modal, size: size).tap(&:open)
       end
 
       # Removes this popup from the {Screen}. No-op if not currently open.
@@ -77,33 +128,29 @@ module Tuile
         screen.has_popup?(self)
       end
 
-      # Recenters the popup on the screen, preserving its current width/height.
-      # Called automatically by the screen's layout pass and by {#content=}
-      # when the popup is open.
+      # 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
+      # detection fire a full repaint on every resize.
       # @return [void]
-      def center
-        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
-
-      # Sets the popup's content and auto-sizes the popup to fit.
-      # @param new_content [Component, nil]
-      def content=(new_content)
-        super
-        update_rect unless new_content.nil?
+      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
       end
 
-      # Re-sizes (and recenters, when open) whenever the wrapped content's
-      # natural size changes — e.g. a {Label}'s `text=`, a {List}'s
-      # `add_line`, or a nested {Window} whose own content grew (the window
-      # recomputes its {Component#content_size} and the change bubbles here).
-      # @param _child [Component]
+      # Recenters the popup on the screen, preserving its current width/height.
       # @return [void]
-      def on_child_content_size_changed(_child)
-        update_rect
+      def center
+        self.rect = rect.centered(screen.size)
       end
 
       # Hint for the status bar: own "q Close" plus the wrapped content's hint.
@@ -114,11 +161,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
@@ -135,24 +183,6 @@ module Tuile
       def layout(content)
         content.rect = rect
       end
-
-      private
-
-      # Recompute width/height from {#content}'s natural size and recenter
-      # if currently open. Called whenever content is (re)assigned.
-      #
-      # Computes the final (centered) rect and assigns it in one step rather
-      # than positioning at the origin and then centering: the intermediate
-      # origin rect rarely covers the previous one, which would make
-      # {#rect=}'s shrink/move detection fire a full repaint on every resize.
-      # @return [void]
-      def update_rect
-        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?
-        self.rect = r
-      end
     end
   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

@@ -122,7 +122,6 @@ module Tuile
         rewrap
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Creates a new empty {Region} at the spatial tail of the document
@@ -191,7 +190,6 @@ module Tuile
         @text = nil
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Verbatim append, returning `self` for chainability (`view << a << b`).
@@ -266,7 +264,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Replaces a contiguous range of hard lines with the parsed content
@@ -327,7 +324,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Inserts `str` at hard-line index `at`. Equivalent to
@@ -386,13 +382,6 @@ module Tuile
 
       def tab_stop? = true
 
-      # @return [Size] longest hard-line's display width × number of hard
-      #   lines. Reported on the *unwrapped* text — wrap-aware sizing would
-      #   be circular (width depends on width). Empty text returns
-      #   `Size.new(0, 0)`. Maintained incrementally by {#text=} and
-      #   {#append}, so reads are O(1).
-      attr_reader :content_size
-
       # @param key [String]
       # @return [Boolean]
       def handle_key(key)
@@ -437,7 +426,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
 
@@ -544,7 +533,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Region-scoped {#replace}. Validates `range` against
@@ -570,7 +558,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Verbatim append into `region`.
@@ -610,7 +597,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Drops the last `n` hard lines from `region`'s tail via
@@ -632,7 +618,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Drops `region` from {@regions}: its hard lines are removed via
@@ -658,7 +643,6 @@ module Tuile
         @top_line = top_line_max if @top_line > top_line_max
         update_top_line_if_auto_scroll
         invalidate
-        self.content_size = compute_content_size
       end
 
       # Adjusts region line counts after a {@hard_lines} splice that
@@ -832,13 +816,6 @@ module Tuile
         StyledString.new(spans)
       end
 
-      # @return [Size] {#content_size} computed from {@hard_lines}.
-      def compute_content_size
-        return Size::ZERO if @hard_lines.empty?
-
-        Size.new(@hard_lines.map(&:display_width).max || 0, @hard_lines.size)
-      end
-
       # @return [Integer] column width available for wrapped text — viewport
       #   width minus the scrollbar gutter (when visible). `0` when {#rect}'s
       #   width is non-positive, which yields a degenerate "no wrap" result.
@@ -904,15 +881,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