tuile 0.1.0 → 0.3.0

data/lib/tuile/component/layout.rb

@@ -5,9 +5,11 @@ module Tuile
     # A layout doesn't paint anything by itself: its job is to position child
     # components.
     #
-    # All children must completely cover the contents of a layout: that way,
-    # the layout itself doesn't have to draw and no clipping algorithm is
-    # necessary.
+    # Children that fully tile the layout's rect repaint themselves and
+    # cover everything; children that leave gaps (e.g. a form with widgets
+    # of varying widths) trigger {Component#repaint}'s default behavior —
+    # the background is cleared and children are re-invalidated so they
+    # paint over a clean surface.
     class Layout < Component
       def initialize
         super
@@ -17,6 +19,16 @@ module Tuile
       # @return [Array<Component>]
       def children = @children.to_a
 
+      # Layouts are focusable containers — like {Window} and {Popup}, they
+      # don't accept input themselves but they need to participate in the
+      # {HasContent} focus cascade so a Popup wrapping a Layout wrapping a
+      # {TextField} ends up focusing the field rather than parking focus on
+      # the popup. Layouts don't paint any visible chrome of their own
+      # (the auto-cleared background is just blank space), so this has no
+      # mouse-routing consequences — clicks on a gap area land back on the
+      # Layout itself and the on_focus cascade forwards to a tab stop.
+      def focusable? = true
+
       # Adds a child component to this layout.
       # @param child [Component, Array<Component>]
       # @return [void]
@@ -53,11 +65,6 @@ module Tuile
         Size.new(right - rect.left, bottom - rect.top)
       end
 
-      # @return [void]
-      def repaint
-        clear_background if @children.empty?
-      end
-
       # Dispatches the event to the child under the mouse cursor.
       # @param event [MouseEvent]
       # @return [void]
@@ -83,10 +90,20 @@ module Tuile
       # @return [void]
       def on_focus
         super
-        # Let the content component receive focus, so that it can immediately
-        # start responding to key presses.
-        first_focusable = @children.find(&:focusable?)
-        screen.focused = first_focusable unless first_focusable.nil?
+        # Forward focus to the first interactive widget in the subtree so the
+        # user can start typing / cursoring immediately. Prefer a {#tab_stop?}
+        # descendant (TextField, List, Button…) so we skip past intermediate
+        # containers like a {Window} or another {Layout}. Fall back to the
+        # first focusable direct child for the rare case where the layout has
+        # focusable but non-tab-stop children (e.g. an empty {Window}).
+        first_tab_stop = nil
+        on_tree { |c| first_tab_stop ||= c if !c.equal?(self) && c.tab_stop? }
+        if first_tab_stop
+          screen.focused = first_tab_stop
+        else
+          first_focusable = @children.find(&:focusable?)
+          screen.focused = first_focusable unless first_focusable.nil?
+        end
       end
 
       # Absolute layout. Extend this class, register any children, and

data/lib/tuile/component/list.rb

@@ -2,35 +2,58 @@
 
 module Tuile
   class Component
-    # A scrollable list of String items with cursor support.
+    # A scrollable list of items with cursor support.
     #
-    # Items are lines painted directly into the component's {#rect}. Lines are
-    # automatically clipped horizontally. Vertical scrolling is supported via
-    # {#top_line}; the list can also automatically scroll to the bottom if
-    # {#auto_scroll} is enabled.
+    # Items are modeled as {StyledString}s and painted directly into the
+    # component's {#rect}. Lines wider than the viewport are ellipsized via
+    # {StyledString#ellipsize} (span styles are preserved across the cut —
+    # unlike the older ANSI-as-bytes truncation, color does *not* get
+    # dropped on the surviving characters). Vertical scrolling is supported
+    # via {#top_line}; the list can also automatically scroll to the bottom
+    # if {#auto_scroll} is enabled.
     #
     # Cursor is supported; call {#cursor=} to change cursor behavior. The
-    # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the list
-    # automatically.
+    # cursor responds to arrows, `jk`, Home/End, Ctrl+U/D and scrolls the
+    # list automatically. The cursor highlight overlays a dark background
+    # while preserving each span's foreground color.
     class List < Component
+      # 256-color SGR index for the cursor-row background highlight. Matches
+      # what `Rainbow(...).bg(:darkslategray)` emits.
+      # @return [Integer]
+      CURSOR_BG = 59
+
       def initialize
         super
         @lines = []
+        @padded_lines = []
+        @blank_padded = StyledString::EMPTY
         @auto_scroll = false
         @top_line = 0
         @cursor = Cursor::None.new
         @scrollbar_visibility = :gone
         @show_cursor_when_inactive = false
         @on_item_chosen = nil
+        @on_cursor_changed = nil
+        @last_cursor_state = cursor_state
       end
 
       # @return [Proc, nil] callback fired when an item is chosen — by pressing
       #   Enter on the cursor's item, or by left-clicking an item. Called as
-      #   `proc.call(index, line)` with the chosen 0-based index and its line.
-      #   Never fires when the cursor's position is outside the content (e.g.
-      #   {Cursor::None}, or empty content).
+      #   `proc.call(index, line)` with the chosen 0-based index and its
+      #   {StyledString} line. Never fires when the cursor's position is
+      #   outside the content (e.g. {Cursor::None}, or empty content).
       attr_accessor :on_item_chosen
 
+      # @return [Proc, nil] callback fired when the `(index, line)` tuple under
+      #   the cursor changes. Called as `proc.call(index, line)` where `line`
+      #   is the {StyledString} at the cursor, or `nil` when the cursor is
+      #   off-content ({Cursor::None}, empty list, or `index` past the last
+      #   line). Fires on cursor moves (key, mouse, search), on {#cursor=},
+      #   and on {#lines=}/{#add_lines} when the line at the cursor's index
+      #   changes (or its in-range/out-of-range status flips). Useful for
+      #   keeping a details pane in sync with the highlighted row.
+      attr_accessor :on_cursor_changed
+
       # @return [Boolean] if true and a line is added or new content is set,
       #   auto-scrolls to the bottom.
       attr_reader :auto_scroll
@@ -65,6 +88,7 @@ module Tuile
         return if @scrollbar_visibility == value
 
         @scrollbar_visibility = value
+        rebuild_padded_lines
         invalidate
       end
 
@@ -83,6 +107,7 @@ module Tuile
         old_position = @cursor.position
         @cursor = cursor
         invalidate if old_position != cursor.position
+        notify_cursor_changed
       end
 
       # Sets the top line.
@@ -96,17 +121,24 @@ module Tuile
         invalidate
       end
 
-      # Sets new lines. Each entry is coerced via `#to_s`, split on `\n` into
-      # separate lines, and trailing whitespace stripped — symmetric with
-      # {#add_lines}, so the stored `@lines` is always `Array<String>`.
-      # @param lines [Array] new lines. Entries need only respond to `#to_s`.
+      # Sets new lines. Each entry is coerced into a {StyledString} (a
+      # `String` is parsed via {StyledString.parse}, so embedded ANSI is
+      # honored; a {StyledString} is used as-is; anything else is stringified
+      # via `#to_s` first), then split on `\n` into separate lines via
+      # {StyledString#lines}, with trailing empty pieces dropped and trailing
+      # ASCII whitespace stripped — symmetric with {#add_lines}, so the
+      # stored `@lines` is always `Array<StyledString>`.
+      # @param lines [Array] entries are `String`, `StyledString`, or anything
+      #   that responds to `#to_s`.
       # @return [void]
       def lines=(lines)
         raise TypeError, "expected Array, got #{lines.inspect}" unless lines.is_a? Array
 
-        @lines = lines.flat_map { it.to_s.split("\n") }.map(&:rstrip)
+        @lines = parse_input_lines(lines)
         @content_size = nil
+        rebuild_padded_lines
         update_top_line_if_auto_scroll
+        notify_cursor_changed
         invalidate
       end
 
@@ -118,9 +150,11 @@ module Tuile
       # end
       # ```
       # @yield [buffer]
-      # @yieldparam buffer [Array<String>] mutable buffer to push lines into.
+      # @yieldparam buffer [Array] mutable buffer to push lines into. Each
+      #   entry is parsed the same way as the items passed to {#lines=}.
       # @yieldreturn [void]
-      # @return [Array<String>] current lines (when called without a block).
+      # @return [Array<StyledString>] current lines (when called without a
+      #   block).
       def lines
         return @lines unless block_given?
 
@@ -130,36 +164,42 @@ module Tuile
       end
 
       # Adds a line.
-      # @param line [String]
+      # @param line [String, StyledString, #to_s]
       # @return [void]
       def add_line(line)
         add_lines [line]
       end
 
-      # Appends given lines. Each entry is coerced via `#to_s`, split on `\n`
-      # into separate lines, and trailing whitespace stripped — symmetric with
-      # {#lines=}.
-      # @param lines [Array] entries need only respond to `#to_s`.
+      # Appends given lines. Each entry is parsed the same way as in
+      # {#lines=}: coerced to a {StyledString}, split on `\n`, with trailing
+      # empty pieces dropped and trailing ASCII whitespace stripped.
+      # @param lines [Array] entries are `String`, `StyledString`, or anything
+      #   that responds to `#to_s`.
       # @return [void]
       def add_lines(lines)
         screen.check_locked
-        @lines += lines.flat_map { it.to_s.split("\n") }.map(&:rstrip)
+        new_lines = parse_input_lines(lines)
+        @lines += new_lines
         @content_size = nil
+        @padded_lines += new_lines.map { |line| pad_to_row(line) }
         update_top_line_if_auto_scroll
+        notify_cursor_changed
         invalidate
       end
 
       # @return [Size]
       def content_size
         @content_size ||= begin
-          content_width = @lines.map { |line| Unicode::DisplayWidth.of(Rainbow.uncolor(line)) }.max || 0
-          width = @lines.empty? ? 0 : content_width + 2
+          content_w = @lines.map(&:display_width).max || 0
+          width = @lines.empty? ? 0 : content_w + 2
           Size.new(width, @lines.size)
         end
       end
 
       def focusable? = true
 
+      def tab_stop? = true
+
       # @param key [String] a key.
       # @return [Boolean] true if the key was handled.
       def handle_key(key)
@@ -178,6 +218,7 @@ module Tuile
           true
         elsif @cursor.handle_key(key, @lines.size, viewport_lines)
           move_viewport_to_cursor
+          notify_cursor_changed
           invalidate
           true
         else
@@ -188,6 +229,8 @@ module Tuile
       # Moves the cursor to the next line whose text contains `query`
       # (case-insensitive substring match). Search wraps around the end of the
       # list. Only lines reachable by the current {#cursor} are considered.
+      # Matching uses the line's plain text — span styles do not affect the
+      # match.
       #
       # @param query [String] substring to match. Empty query never matches.
       # @param include_current [Boolean] when true, the current cursor position
@@ -222,6 +265,7 @@ module Tuile
           line = event.y - rect.top + top_line
           if @cursor.handle_mouse(line, event, @lines.size)
             move_viewport_to_cursor
+            notify_cursor_changed
             invalidate
           end
           fire_item_chosen if event.button == :left && line >= 0 && line < @lines.size && cursor_on_item?
@@ -229,19 +273,21 @@ module Tuile
       end
 
       # Paints the list items into {#rect}.
+      #
+      # Skips the {Component#repaint} default's auto-clear: every row of
+      # {#rect} is painted below (with blank padding past the last item),
+      # so the parent contract — "fully draw over your rect" — is met
+      # without an upfront wipe.
       # @return [void]
       def repaint
-        super
         return if rect.empty?
 
-        width = rect.width
         scrollbar = if scrollbar_visible?
                       VerticalScrollBar.new(rect.height, line_count: @lines.size, top_line: @top_line)
                     end
-        (0..(rect.height - 1)).each do |line_no|
-          line_index = line_no + @top_line
-          line = paintable_line(line_index, line_no, width, scrollbar)
-          screen.print TTY::Cursor.move_to(rect.left, line_no + rect.top), line
+        (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
         end
       end
 
@@ -302,9 +348,9 @@ module Tuile
             go_down_by(1, line_count)
           when *Keys::UP_ARROWS
             go_up_by(1)
-          when Keys::HOME
+          when *Keys::HOMES
             go_to_first
-          when Keys::END_
+          when *Keys::ENDS_
             go_to_last(line_count)
           when Keys::CTRL_U
             go_up_by(viewport_lines / 2)
@@ -430,8 +476,56 @@ module Tuile
         end
       end
 
+      protected
+
+      # Rebuilds pre-padded lines when the wrap width changes. The wrap width
+      # depends on {#rect}`.width` and the scrollbar gutter, both of which
+      # trigger this hook.
+      # @return [void]
+      def on_width_changed
+        super
+        rebuild_padded_lines
+      end
+
       private
 
+      # 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
+      # via `#to_s`), then split on `\n` via {StyledString#lines} — with
+      # trailing empty pieces dropped (matching `String#split("\n")`'s
+      # default behavior, so `add_line ""` is a no-op) — and trailing ASCII
+      # whitespace stripped on each resulting line.
+      # @param entries [Array]
+      # @return [Array<StyledString>]
+      def parse_input_lines(entries)
+        entries.flat_map { |entry| split_to_lines(entry) }
+      end
+
+      # @param entry [Object]
+      # @return [Array<StyledString>]
+      def split_to_lines(entry)
+        styled = entry.is_a?(StyledString) ? entry : StyledString.parse(entry.to_s)
+        parts = styled.lines
+        parts.pop while parts.last && parts.last.empty?
+        parts.map { |line| rstrip_styled(line) }
+      end
+
+      # Returns `line` with trailing ASCII whitespace (space/tab) dropped,
+      # preserving span styles on the surviving prefix. Whitespace chars are
+      # all single-column ASCII, so byte-count delta equals column-count
+      # delta and {StyledString#slice} can do the cut.
+      # @param line [StyledString]
+      # @return [StyledString]
+      def rstrip_styled(line)
+        plain = line.to_s
+        trailing = plain.length - plain.rstrip.length
+        return line if trailing.zero?
+        return StyledString::EMPTY if trailing == plain.length
+
+        line.slice(0, line.display_width - trailing)
+      end
+
       # @return [Boolean] true if the cursor sits on a real content line.
       def cursor_on_item?
         pos = @cursor.position
@@ -446,6 +540,26 @@ module Tuile
         @on_item_chosen&.call(pos, @lines[pos])
       end
 
+      # @return [Array((Integer, StyledString, nil))]
+      #   `[position, line_at_position]`, with `line` nil when the cursor is
+      #   off-content.
+      def cursor_state
+        pos = @cursor.position
+        line = pos >= 0 && pos < @lines.size ? @lines[pos] : nil
+        [pos, line]
+      end
+
+      # Fires {#on_cursor_changed} if {#cursor_state} differs from the last
+      # fired state. Idempotent — safe to call after any mutation.
+      # @return [void]
+      def notify_cursor_changed
+        state = cursor_state
+        return if state == @last_cursor_state
+
+        @last_cursor_state = state
+        @on_cursor_changed&.call(*state)
+      end
+
       # @param query [String]
       # @param include_current [Boolean]
       # @param reverse [Boolean]
@@ -458,11 +572,12 @@ module Tuile
 
         ordered = order_for_search(candidates, @cursor.position, include_current: include_current, reverse: reverse)
         query_lc = query.downcase
-        match = ordered.find { |idx| Rainbow.uncolor(@lines[idx]).downcase.include?(query_lc) }
+        match = ordered.find { |idx| @lines[idx].to_s.downcase.include?(query_lc) }
         return false unless match
 
         @cursor.go(match)
         move_viewport_to_cursor
+        notify_cursor_changed
         invalidate
         true
       end
@@ -541,42 +656,56 @@ module Tuile
         @scrollbar_visibility == :visible
       end
 
-      # Trims string exactly to `width` columns.
-      # @param str [String]
-      # @param width [Integer]
-      # @return [String]
-      def trim_to(str, width)
-        return " " * width if str.empty?
+      # @return [Integer] column width available for line content (rect width
+      #   minus the scrollbar gutter, when visible). `0` when {#rect}'s width
+      #   is non-positive.
+      def content_width
+        return 0 if rect.width <= 0
+
+        rect.width - (scrollbar_visible? ? 1 : 0)
+      end
 
-        truncated_line = Strings::Truncation.truncate(str, length: width)
-        return truncated_line unless truncated_line == str
+      # Recomputes {@padded_lines} for the current rect width and scrollbar
+      # visibility. Each line is ellipsized to fit and pre-padded with
+      # single-space gutters on each side, so {#paintable_line} only has to
+      # apply the cursor highlight (if any) and append the scrollbar glyph.
+      # @return [void]
+      def rebuild_padded_lines
+        @padded_lines = @lines.map { |line| pad_to_row(line) }
+        @blank_padded = pad_to_row(StyledString::EMPTY)
+      end
 
-        length = Unicode::DisplayWidth.of(Rainbow.uncolor(str))
-        str += " " * (width - length) if length < width
-        str
+      # Pads `line` to one full row of the viewport (scrollbar gutter
+      # excluded). Lines wider than the content area are ellipsized via
+      # {StyledString#ellipsize} (span styles survive the cut); shorter
+      # lines are padded with default-styled spaces.
+      # @param line [StyledString]
+      # @return [StyledString] exactly {#content_width} display columns wide
+      #   (or {StyledString::EMPTY} when content_width is non-positive).
+      def pad_to_row(line)
+        cw = content_width
+        return StyledString::EMPTY if cw <= 0
+        return StyledString.plain(" " * cw) if cw < 2
+
+        text_width = cw - 2
+        body = line.ellipsize(text_width)
+        fill = cw - 2 - body.display_width
+        StyledString.plain(" ") + body + StyledString.plain(" " * (fill + 1))
       end
 
       # @param index [Integer] 0-based index into {#lines}.
       # @param row_in_viewport [Integer] 0-based row within the viewport.
-      # @param width [Integer] number of columns the line should occupy.
-      # @param scrollbar [VerticalScrollBar, nil] scrollbar instance, or nil if
-      #   not shown.
-      # @return [String] paintable line exactly `width` columns wide;
-      #   highlighted if cursor is here.
-      def paintable_line(index, row_in_viewport, width, scrollbar)
-        content_width = scrollbar ? width - 1 : width
-        line = @lines[index] || ""
-        line = trim_to(line, content_width - 2)
-        line = " #{line} "
+      # @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.
+      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
-        line = if is_cursor
-                 Rainbow(Rainbow.uncolor(line)).bg(:darkslategray)
-               else
-                 line
-               end
-        return line unless scrollbar
-
-        line + scrollbar.scrollbar_char(row_in_viewport)
+        styled = is_cursor ? base.with_bg(CURSOR_BG) : base
+        out = styled.to_ansi
+        out += scrollbar.scrollbar_char(row_in_viewport) if scrollbar
+        out
       end
     end
   end