tuile 0.16.0 → 0.17.0

data/lib/tuile/component/list.rb

@@ -6,14 +6,26 @@ module Tuile
     #
     #   list = Component::List.new
     #   list.items    = people
-    #   list.renderer = ->(p) { StyledString.plain(p.name) + screen.theme.fg(:muted, " #{p.email}") }
+    #   list.renderer = ->(p, _w) { StyledString.plain(p.name) + screen.theme.fg(:muted, " #{p.email}") }
     #   list.cursor   = List::Cursor.new                  # a bare list has none
-    #   list.on_item_chosen = ->(index, person) { open(person) }
+    #   list.on_item_chosen { |e| open(e.item) }
     #
-    # The {#renderer} turns an item into one row; the default renders an item
-    # as itself, so a list of `String`s or {StyledString}s needs none — which
-    # is what {#lines=} and {#build_lines} are, items that are their own
-    # rendering (split on `\n`, one row per line).
+    # The {#renderer} turns an item and the columns it gets into one row; the
+    # default renders an item as itself and ignores the width, so a list of
+    # `String`s or {StyledString}s needs none — which is what {#lines=} and
+    # {#build_lines} are, items that are their own rendering (split on `\n`,
+    # one row per line).
+    #
+    # A renderer that *uses* the width lays out against it — an aligned
+    # right-hand column, a path elided from the left — neither of which a
+    # trailing ellipsis can express:
+    #
+    #   counts_w = files.map { _1.counts.length }.max   # per snapshot, not per row
+    #   list.renderer = lambda do |file, w|
+    #     name = StyledString.plain(file.path).ellipsize(w - counts_w - 1, at: :start)
+    #     gap  = " " * (w - counts_w - name.display_width)
+    #     name + StyledString.plain(gap + file.counts)
+    #   end
     #
     # There are no appenders. The items are always assigned whole — an app that
     # grows a list keeps its own array and re-assigns it (`list.items = mine`) —
@@ -27,26 +39,38 @@ module Tuile
     # automatically; its highlight overlays {Theme#active_bg_color} while
     # preserving each span's foreground color.
     #
+    # {#scrollbar_visibility} turns on a {VerticalScrollBar} in the rightmost
+    # column: a child component, so its handle drags (wanting
+    # `run_event_loop(capture_mouse: :drag)`) and a press on its track pages.
+    # Under `:visible` the column stays reserved whether anything scrolls or
+    # not, so a growing list re-flows nothing; under `:auto` the bar shows only
+    # while the items outnumber the rows, and hands its column back to the
+    # rows while they fit (`D_scrollbar_ink`).
+    #
     # == Implementation details
     # Rendering is lazy: only the rows in the viewport are rendered, each
-    # memoized until {#items=}, {#renderer=} or a width change drops the cache.
+    # memoized until {#items=} or {#renderer=} drops the cache, or the row
+    # width moves off the one it was padded at.
     # So a renderer runs *at paint time*, on any frame — keep it pure and
     # cheap; work that reaches a service belongs in the item, not in the
-    # renderer. {#select_next} deliberately renders without memoizing: one
-    # failed scan would otherwise cache a row per item.
+    # renderer, and a measurement over the whole snapshot (the example's widest
+    # counts column) is computed where {#items=} is assigned, or it is an
+    # O(items²) pass on every resize. {#select_next} deliberately renders
+    # without memoizing: one failed scan would otherwise cache a row per item.
     class List < Component
-      # The default {#renderer}: an item renders as itself. Every renderer's
-      # output is coerced the same way — a {StyledString} passes through, a
-      # `String` is parsed (so embedded ANSI is honored), anything else is
-      # `#to_s`'d first.
+      # The default {#renderer}: an item renders as itself, whatever the width.
+      # Every renderer's output is coerced the same way — a {StyledString}
+      # passes through, a `String` is parsed (so embedded ANSI is honored),
+      # anything else is `#to_s`'d first.
       # @return [Proc]
-      DEFAULT_RENDERER = :itself.to_proc
+      DEFAULT_RENDERER = ->(item, _text_width) { item }
 
       def initialize
         super
         @items = []
         @renderer = DEFAULT_RENDERER
         @row_cache = {}
+        @row_cache_width = nil
         @blank_row = nil
         @auto_scroll = false
         @follow = true
@@ -54,27 +78,52 @@ module Tuile
         @cursor = Cursor::None.new
         @scrollbar_visibility = :gone
         @show_cursor_when_inactive = false
-        @on_item_chosen = nil
-        @on_cursor_changed = nil
+        @interactive = true
         @last_cursor_state = cursor_state
+        @scrollbar = VerticalScrollBar.new
+        @scrollbar.on_scroll_request { self.scroll_top_row = _1.scroll_top_row }
+        add_child(@scrollbar) # chrome, appended: a List has no content children
       end
 
-      # @return [Proc, nil] callback fired when an item is chosen — by pressing
-      #   Enter on the cursor's item, or by left-clicking it. Called as
-      #   `proc.call(index, item)` with the chosen 0-based index and the item
-      #   itself. 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, item)` tuple under
-      #   the cursor changes (items compared with `==`). Called as
-      #   `proc.call(index, item)`, with `item` `nil` when the cursor is
-      #   off-content ({Cursor::None}, empty list, or `index` past the last
-      #   item). Fires on cursor moves (key, mouse, search), on {#cursor=},
-      #   and on {#items=} when the item 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
+      # What {#on_item_chosen} fires.
+      #
+      # @!attribute [r] source
+      #   @return [List] the list the item was chosen in.
+      # @!attribute [r] position
+      #   @return [Integer] the chosen item's 0-based index.
+      # @!attribute [r] item
+      #   @return [Object] the chosen item itself.
+      ItemChosenEvent = Data.define(:source, :position, :item) { include Tuile::Event }
+
+      # What {#on_cursor_changed} fires.
+      #
+      # @!attribute [r] source
+      #   @return [List] the list whose cursor moved.
+      # @!attribute [r] position
+      #   @return [Integer] the cursor's 0-based index.
+      # @!attribute [r] item
+      #   @return [Object, nil] the item there, `nil` when the cursor is
+      #     off-content ({Cursor::None}, empty list, or `position` past the last
+      #     item).
+      CursorChangedEvent = Data.define(:source, :position, :item) { include Tuile::Event }
+
+      # @!method on_item_chosen
+      #   Fired with an {ItemChosenEvent} when an item is chosen — by pressing
+      #   Enter on the cursor's item, or by left-clicking it. Never fires when
+      #   the cursor's position is outside the content (e.g. {Cursor::None}, or
+      #   empty content).
+      #   @return [Listeners]
+      listener :on_item_chosen
+
+      # @!method on_cursor_changed
+      #   Fired with a {CursorChangedEvent} when the `(position, item)` tuple
+      #   under the cursor changes (items compared with `==`). Fires on cursor
+      #   moves (key, mouse, search), on {#cursor=}, and on {#items=} when the
+      #   item 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.
+      #   @return [Listeners]
+      listener :on_cursor_changed
 
       # @return [Boolean] if true and new content is set, auto-scrolls to the
       #   bottom — but only while the viewport is already pinned to the last
@@ -95,7 +144,9 @@ module Tuile
       # @return [Cursor] the list's cursor.
       attr_reader :cursor
 
-      # @return [Symbol] scrollbar visibility: `:gone` or `:visible`.
+      # @return [Symbol] scrollbar visibility: `:gone`, `:visible`, or `:auto`
+      #   — shown only while there are more {#items} than rows. `:gone` by
+      #   default.
       attr_reader :scrollbar_visibility
 
       # @return [Boolean] when true, the cursor highlight is painted even while
@@ -112,15 +163,42 @@ module Tuile
         invalidate
       end
 
+      # Whether the list is a control: focusable, a tab stop, and a press on a
+      # row moves the cursor and fires {#on_item_chosen}. `false` makes it a
+      # display-only pane — a sidebar summary beside the field the user types
+      # in — which Tab skips, a click doesn't focus, and a press on a row
+      # bubbles past, so no capability is left reachable only by the mouse.
+      # The wheel and the scrollbar still scroll it, and the app still drives
+      # {#cursor} and {#scroll_top_row}. `true` by default.
+      # @return [Boolean]
+      def interactive? = @interactive
+
+      # Turning it off while focus is inside the list hands focus to the
+      # parent, as hiding a focused component does.
+      # @param value [Boolean]
+      # @return [void]
+      def interactive=(value)
+        value = value ? true : false
+        return if @interactive == value
+
+        @interactive = value
+        repair_focus_after_hiding unless value
+        invalidate
+      end
+
       # Sets the scrollbar visibility.
-      # @param value [Symbol] `:gone` or `:visible`.
+      # @param value [Symbol] `:gone`, `:visible` or `:auto`.
+      # @raise [ArgumentError] on any other value.
+      # @return [void]
       def scrollbar_visibility=(value)
-        raise ArgumentError, "expected :gone or :visible, got #{value.inspect}" unless %i[gone visible].include?(value)
+        unless %i[gone visible auto].include?(value)
+          raise ArgumentError, "expected :gone, :visible or :auto, got #{value.inspect}"
+        end
         return if @scrollbar_visibility == value
 
         @scrollbar_visibility = value
-        drop_row_cache
         invalidate
+        invalidate_layout
       end
 
       # Sets the new auto_scroll. If true, re-engages tailing and immediately
@@ -153,14 +231,21 @@ module Tuile
         @scroll_top_row = new_row
         @follow = at_bottom?
         invalidate
+        invalidate_layout
       end
 
       # @return [Array] the items, one row each.
       attr_reader :items
 
-      # @return [Proc, Method] item -> row: a {StyledString}, a `String` (parsed,
-      #   so embedded ANSI is honored), or anything with `#to_s`. Only the first
-      #   line of a multi-line rendering is kept — one item is one row.
+      # The width is passed whether or not a renderer wants it, so a
+      # one-argument callable raises when a row is rendered.
+      # @return [Proc, Method] `(item, text_width) -> row`: a {StyledString}, a
+      #   `String` (parsed, so embedded ANSI is honored), or anything with
+      #   `#to_s`. Only the first line of a multi-line rendering is kept — one
+      #   item is one row. `text_width` is the display columns the row body
+      #   gets, gutters and scrollbar column already deducted; it is `0` before
+      #   the list has a rect, and every change to it drops the row cache, so a
+      #   width-dependent row is never left over from the old width.
       attr_reader :renderer
 
       # Replaces the items, leaving the cursor where it is — a cursor left past
@@ -178,9 +263,10 @@ module Tuile
         update_scroll_top_row_if_auto_scroll
         notify_cursor_changed
         invalidate
+        invalidate_layout # the bar's row_count follows @items.size
       end
 
-      # @param proc [Proc, Method] item -> row; see {#renderer}.
+      # @param proc [Proc, Method] `(item, text_width) -> row`; see {#renderer}.
       # @return [void]
       def renderer=(proc)
         @renderer = proc
@@ -192,9 +278,9 @@ module Tuile
       # it and {#items} stayed the same, e.g. one prefixing a marker read from
       # a selection it closes over:
       #
-      #   def value=(new_value)   # RadioGroup: the marked row moved
+      #   def set_value(new_value, from_user:)   # RadioGroup: the marked row moved
       #     super
-      #     content.refresh_rows
+      #     list.refresh_rows
       #   end
       #
       # @return [void]
@@ -243,9 +329,11 @@ module Tuile
         self.lines = buffer
       end
 
-      def focusable? = true
+      # @return [Boolean] {#interactive?}.
+      def focusable? = @interactive
 
-      def tab_stop? = true
+      # @return [Boolean] {#interactive?}.
+      def tab_stop? = @interactive
 
       # @param key [String] a key.
       # @return [Boolean] true if the key was handled.
@@ -317,13 +405,14 @@ module Tuile
       end
 
       # Moves the cursor to the pressed row and fires {#on_item_chosen}; what
-      # each {Cursor} does with a press is its own.
+      # each {Cursor} does with a press is its own. Declines every press while
+      # not {#interactive?}.
       # @param event [Mouse::DownEvent]
       # @return [Boolean]
       def handle_mouse_down?(event)
-        return false unless event.button == :left
+        return false unless @interactive && event.button == :left
 
-        item_index = event.y - rect.top + scroll_top_row
+        item_index = event.y + scroll_top_row
         if @cursor.handle_mouse_down?(item_index, event, @items.size)
           move_viewport_to_cursor
           notify_cursor_changed
@@ -348,24 +437,27 @@ module Tuile
       end
 
       # Paints the visible items into {#rect}, rendering the ones not already
-      # cached.
+      # cached. The scrollbar's column is the child {VerticalScrollBar}'s,
+      # reserved out of {#content_width}.
       #
       # 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. Rows go through {Component#draw_text}, so
-      # content *and* blank filler inherit {Component#effective_bg_color}
+      # without an upfront wipe — but not {Component#invalidate_children}, or
+      # the scrollbar goes stale under an ancestor's clear. Rows go through
+      # {Canvas#set_text}, so
+      # content *and* blank filler inherit {ComponentBackground#effective}
       # (a {#bg_color} set here or on an ancestor); the cursor row's
       # {Theme#active_bg_color} highlight composes on top of it.
+      # @param canvas [Canvas] see {Component#repaint}.
       # @return [void]
-      def repaint
+      def repaint(canvas)
         return if rect.empty?
 
-        scrollbar = if scrollbar_visible?
-                      VerticalScrollBar.new(rect.height, row_count: @items.size, scroll_top_row: @scroll_top_row)
-                    end
+        invalidate_children
+        sync_row_cache_width
         (0...rect.height).each do |row|
-          draw_text(rect.left, row + rect.top, paintable_row(row + @scroll_top_row, row, scrollbar))
+          canvas.set_text(0, row, paintable_row(row + @scroll_top_row))
         end
       end
 
@@ -573,18 +665,16 @@ module Tuile
 
       protected
 
-      # Drops the rendered-row cache when the wrap width changes. The wrap
-      # width depends on {#rect}`.width` and the scrollbar column, both of
-      # which trigger this hook. Also re-evaluates {#auto_scroll}: if items were
-      # assigned while the rect was empty (e.g. a {Popup}-wrapped list was
-      # populated before the popup was opened), the auto-scroll update
-      # was skipped because there was no viewport — re-run it now that there
-      # is one, so the list snaps to the bottom on first paint.
+      # The bar's whole state, pushed in one place: its column, and the two
+      # numbers it paints a handle from. {#auto_scroll} re-pins first, since a
+      # taller viewport moves the bottom, and a rect that was empty skipped the
+      # pin altogether.
       # @return [void]
-      def handle_width_changed
-        super
-        drop_row_cache
+      def relayout
         update_scroll_top_row_if_auto_scroll
+        @scrollbar.rect = scrollbar_visible? ? Rect.new(rect.width - 1, 0, 1, rect.height) : Rect.new(0, 0, 0, 0)
+        @scrollbar.row_count = @items.size
+        @scrollbar.scroll_top_row = @scroll_top_row
       end
 
       private
@@ -637,7 +727,7 @@ module Tuile
       # @return [void]
       def fire_item_chosen
         pos = @cursor.position
-        @on_item_chosen&.call(pos, @items[pos])
+        on_item_chosen.fire(ItemChosenEvent.new(source: self, position: pos, item: @items[pos]))
       end
 
       # @return [Array((Integer, Object, nil))]
@@ -657,7 +747,7 @@ module Tuile
         return if state == @last_cursor_state
 
         @last_cursor_state = state
-        @on_cursor_changed&.call(*state)
+        on_cursor_changed.fire(CursorChangedEvent.new(source: self, position: state[0], item: state[1]))
       end
 
       # @param query [String]
@@ -731,15 +821,13 @@ module Tuile
       # @return [Integer] the number of visible rows.
       def viewport_rows = rect.height
 
-      # Scrolls the list.
+      # Scrolls the list, clamped at both ends. Goes through
+      # {#scroll_top_row=}, so a wheel notch or a PgUp re-evaluates
+      # {#following?} exactly as an assignment does.
       # @param delta [Integer] negative scrolls up, positive scrolls down.
       # @return [void]
       def move_scroll_top_row_by(delta)
-        new_scroll_top_row = (@scroll_top_row + delta).clamp(0, scroll_top_row_max)
-        return if @scroll_top_row == new_scroll_top_row
-
-        @scroll_top_row = new_scroll_top_row
-        invalidate
+        self.scroll_top_row = (@scroll_top_row + delta).clamp(0, scroll_top_row_max)
       end
 
       # If auto-scrolling, recalculate the top row and snap the cursor to the
@@ -748,8 +836,7 @@ module Tuile
       # negating the auto-scroll. Skipped when {#rect} is empty: without a
       # viewport the "items minus viewport" formula yields `@items.size`,
       # which would leave `scroll_top_row` past the last item once a real rect
-      # arrives. {#handle_width_changed} re-runs this hook when the rect grows so
-      # the snap-to-bottom intent is preserved.
+      # arrives. {#relayout} re-runs it once one does.
       #
       # Gated on {#following?}: once the user scrolls up off the bottom the
       # cursor snap and viewport pin are both skipped, so reading older
@@ -768,11 +855,17 @@ module Tuile
         self.scroll_top_row = new_scroll_top_row
       end
 
+      # Derived on every read, never stored, so {#content_width} can't disagree
+      # with it.
       # @return [Boolean] whether the scrollbar should be drawn right now.
       def scrollbar_visible?
         return false if rect.empty?
 
-        @scrollbar_visibility == :visible
+        case @scrollbar_visibility
+        when :visible then true
+        when :auto then @items.size > rect.height
+        else false
+        end
       end
 
       # @return [Integer] column width available for row content (rect width
@@ -784,14 +877,35 @@ module Tuile
         rect.width - (scrollbar_visible? ? 1 : 0)
       end
 
+      # The budget handed to {#renderer} and the width {#pad_to_row} fits a row
+      # into: {#content_width} less the gutter either side. Clamped at `0` — a
+      # list with no rect still renders when {#search_and_go} scans it, and a
+      # renderer subtracting from a negative width would blow up at paint time.
+      # @return [Integer] display columns available to the row body.
+      def text_width
+        [content_width - 2, 0].max
+      end
+
       # Discards every rendered row, so the next paint re-renders the viewport
-      # against the current items, renderer and width.
+      # against the current items and renderer.
       # @return [void]
       def drop_row_cache
         @row_cache.clear
         @blank_row = nil
       end
 
+      # Drops the row cache when {#content_width} has moved off the width it
+      # was padded at. The width is compared rather than announced because an
+      # `:auto` bar moves it on a *height* change too — a list shrinking below
+      # its item count takes the bar and the column with it.
+      # @return [void]
+      def sync_row_cache_width
+        return if @row_cache_width == content_width
+
+        drop_row_cache
+        @row_cache_width = content_width
+      end
+
       # @param index [Integer] 0-based index into {#items}.
       # @return [StyledString] the item's padded row, rendered on first use and
       #   memoized until {#drop_row_cache}.
@@ -812,7 +926,7 @@ module Tuile
       #   {StyledString}, cut to its first line since a `\n` reaching the buffer
       #   would corrupt the frame.
       def render(item)
-        rendered = @renderer.call(item)
+        rendered = @renderer.call(item, text_width)
         rendered = StyledString.parse(rendered.to_s) unless rendered.is_a?(StyledString)
         return rendered unless rendered.spans.any? { _1.text.include?("\n") }
 
@@ -833,27 +947,16 @@ module Tuile
         return StyledString::EMPTY if cw <= 0
         return StyledString.plain(" " * cw) if cw < 2
 
-        text_width = cw - 2
-        body = row.ellipsize(text_width)
-        fill = cw - 2 - body.display_width
-        StyledString.plain(" ") + body + StyledString.plain(" " * (fill + 1))
+        StyledString.plain(" ") + row.ellipsize(text_width).ljust(cw - 1)
       end
 
       # @param index [Integer] 0-based index into {#items}.
-      # @param row_in_viewport [Integer] 0-based row within the viewport.
-      # @param scrollbar [VerticalScrollBar, nil] scrollbar instance, or nil
-      #   if not shown.
-      # @return [StyledString] paintable row exactly `rect.width` columns wide;
-      #   highlighted if cursor is here.
-      def paintable_row(index, row_in_viewport, scrollbar)
+      # @return [StyledString] paintable row exactly {#content_width} columns
+      #   wide — the bar's column is the child's; highlighted if cursor is here.
+      def paintable_row(index)
         base = index < @items.size ? padded_row(index) : blank_row
         is_cursor = (active? || @show_cursor_when_inactive) && index < @items.size && @cursor.position == index
-        styled = is_cursor ? base.with_bg(screen.theme.active_bg_color) : base
-        if scrollbar
-          styled += StyledString.styled(scrollbar.scrollbar_char(row_in_viewport),
-                                        fg: screen.theme.scrollbar_color)
-        end
-        styled
+        is_cursor ? base.with_bg(screen.theme.active_bg_color) : base
       end
     end
   end