tuile 0.11.0 → 0.12.0

data/lib/tuile/component/checkbox_group.rb

@@ -23,12 +23,13 @@ module Tuile
     # Treat it as *unordered*: it iterates in toggle order, so use
     # `cg.items & cg.value.to_a` when you need {#items} order.
     #
-    # Composes rather than subclasses, like {ComboBox}: a {List} is its single
-    # {HasContent} child, which is where the cursor, scrolling, the scrollbar and
-    # per-row mouse hit-testing come from. `content` is that list, so an app can
-    # tune it (`scrollbar_visibility`, `show_cursor_when_inactive`, …). Rows
-    # beyond {#rect}'s height scroll; the inner list is the tab stop, not the
-    # group.
+    # Composes rather than subclasses, like {ComboBox}: a {List} of the items is
+    # its single {HasContent} child, which is where the cursor, scrolling, the
+    # scrollbar and per-row mouse hit-testing come from — the group only supplies
+    # the {List#renderer} that puts the box in front of the label. `content` is
+    # that list, so an app can tune it (`scrollbar_visibility`,
+    # `show_cursor_when_inactive`, …). Rows beyond {#rect}'s height scroll; the
+    # inner list is the tab stop, not the group.
     #
     # == +items+ is chrome; +value+ is authoritative
     # {#items=} changes only what is *presented*. It never touches {#value} and
@@ -46,7 +47,7 @@ module Tuile
     # mutated after being selected becomes unfindable. Two `==`-equal items also
     # share one selection — their rows check and uncheck together — whereas two
     # *distinct* items that merely render the same label toggle independently,
-    # because a row resolves to an item by index.
+    # because a row resolves to its own item, never to its label.
     #
     # Rows repeat {Checkbox}'s `[x] `/`[ ] ` glyph convention rather than
     # importing a constant from it.
@@ -67,7 +68,6 @@ module Tuile
       #   matter to a form helper.
       def initialize(items: [], value: nil)
         super()
-        @items = items.to_a
         @item_label = :to_s.to_proc
         @value = coerce(value)
         @on_value_change = nil
@@ -75,13 +75,14 @@ module Tuile
         list = List.new
         # A List has no cursor at all by default (Cursor::None, position -1).
         list.cursor = List::Cursor.new
-        list.on_item_chosen = ->(index, _line) { toggle_at(index) }
+        list.renderer = method(:render_row)
+        list.on_item_chosen = ->(_index, item) { toggle(item) }
+        list.items = items.to_a
         self.content = list
-        rebuild_rows
       end
 
       # @return [Array] the presented items.
-      attr_reader :items
+      def items = content.items
 
       # @return [Proc, Method] item -> row label (a `String`, {StyledString}, or
       #   anything with `#to_s`); `:to_s` by default.
@@ -92,17 +93,14 @@ module Tuile
       # @raise [TypeError] unless `new_items` is an `Array`.
       # @return [void]
       def items=(new_items)
-        raise TypeError, "expected Array, got #{new_items.inspect}" unless new_items.is_a?(Array)
-
-        @items = new_items
-        rebuild_rows
+        content.items = new_items
       end
 
       # @param proc [Proc, Method] item -> row label.
       # @return [void]
       def item_label=(proc)
         @item_label = proc
-        rebuild_rows
+        content.refresh_rows
       end
 
       # @return [Set] the frozen empty set — {HasValue#empty?} means nothing is
@@ -122,7 +120,7 @@ module Tuile
         return if value == selected
 
         super(selected)
-        rebuild_rows
+        content.refresh_rows
       end
 
       # Toggles the cursor row on Space. Nothing else is claimed: the composed
@@ -148,22 +146,29 @@ module Tuile
       private
 
       # Flips membership of the item on row `index`; an index outside {#items} is
-      # ignored.
+      # ignored — {List::Cursor::None}'s `-1` would otherwise toggle the *last*
+      # item.
       # @param index [Integer]
       # @return [void]
       def toggle_at(index)
-        return unless index.between?(0, @items.size - 1)
+        return unless index.between?(0, items.size - 1)
 
-        item = @items[index]
-        self.value = value.include?(item) ? value - [item] : value + [item]
+        toggle(items[index])
       end
 
-      # Re-renders every row from the current items, labels and selection.
+      # Flips `item`'s membership of {#value}.
+      # @param item [Object]
       # @return [void]
-      def rebuild_rows
-        content.lines = @items.map do |item|
-          StyledString.plain(value.include?(item) ? "[x] " : "[ ] ") + label_for(item)
-        end
+      def toggle(item)
+        self.value = value.include?(item) ? value - [item] : value + [item]
+      end
+
+      # @param item [Object]
+      # @return [StyledString] the item's row: its label behind a checkmark box.
+      #   The {List} calls this at paint time, so the boxes track {#value}
+      #   without re-rendering anything but the visible rows.
+      def render_row(item)
+        StyledString.plain(value.include?(item) ? "[x] " : "[ ] ") + label_for(item)
       end
 
       # @param new_value [Enumerable, nil]

data/lib/tuile/component/combo_box.rb

@@ -52,7 +52,8 @@ module Tuile
         self.content = field
 
         @overlay = ListDropdown.new
-        @overlay.on_item_chosen = ->(index, _line) { commit(index) }
+        @overlay.renderer = ->(item) { @item_label.call(item) }
+        @overlay.on_item_chosen = ->(_index, item) { commit(item) }
       end
 
       # @return [Array] the candidate items.
@@ -195,7 +196,7 @@ module Tuile
         if @filtered.empty?
           close_menu
         else
-          @overlay.lines = @filtered.map { |item| @item_label.call(item) }
+          @overlay.items = @filtered
           @overlay.cursor = List::Cursor.new(position: @filtered.index(value) || 0)
           @overlay.open unless @overlay.open?
           anchor
@@ -214,12 +215,11 @@ module Tuile
         @items.select { |item| @item_label.call(item).to_s.downcase.include?(needle) }
       end
 
-      # Commits the item at the menu's `index`: closes the dropdown and adopts
-      # it as {#value} (which repaints the field with its label).
-      # @param index [Integer]
+      # Commits the item chosen from the menu: closes the dropdown and adopts it
+      # as {#value} (which repaints the field with its label).
+      # @param item [Object]
       # @return [void]
-      def commit(index)
-        item = @filtered[index]
+      def commit(item)
         close_menu
         self.value = item
       end
@@ -235,6 +235,9 @@ module Tuile
 
       # Sets the field's text without triggering a refilter — for programmatic
       # value changes and query reverts, which must not spring the dropdown.
+      # Every programmatic write to the field goes through here; a direct
+      # `content.text =` reaches the field's `on_change` and pops the dropdown
+      # open on a {#value=} the user never asked to browse.
       # Parks the caret at the end: `text=` only *clamps* the caret, so a
       # shorter query replaced by a longer label would otherwise strand it
       # mid-word (commit "Go", then pick "Kotlin" → caret after "Ko").

data/lib/tuile/component/info_window.rb

@@ -25,7 +25,7 @@ module Tuile
       #   list wraps and scrolls within it. Defaults to {Fraction::HALF}.
       # @return [Popup] the opened popup.
       def self.open(caption, lines, size: Fraction::HALF)
-        Popup.open(content: InfoWindow.new(caption, lines), size: size)
+        Popup.new(content: InfoWindow.new(caption, lines), size: size).open
       end
     end
   end

data/lib/tuile/component/label.rb

@@ -16,8 +16,8 @@ module Tuile
         super()
         @text = StyledString::EMPTY
         @bg = nil
-        @clipped_lines = []
-        @blank_line = ""
+        @rows = []
+        @blank_row = ""
         self.text = text unless text.nil?
       end
 
@@ -43,7 +43,7 @@ module Tuile
         return if @text == new_text
 
         @text = new_text
-        update_clipped_lines
+        update_rows
         invalidate
       end
 
@@ -60,7 +60,7 @@ module Tuile
         return if @bg == new_bg
 
         @bg = new_bg
-        update_clipped_lines
+        update_rows
         invalidate
       end
 
@@ -69,15 +69,15 @@ module Tuile
       # Skips the {Component#repaint} default's auto-clear: every row is
       # painted explicitly (with pre-padded blanks past the last line), so
       # the "fully draw over your rect" contract is met without an upfront
-      # wipe. Rows go through {Component#draw_line}, so the padding and blank
+      # wipe. Rows go through {Component#draw_text}, so the padding and blank
       # rows inherit {Component#effective_bg_color} when {#bg} is unset.
       # @return [void]
       def repaint
         return if rect.empty?
 
         (0...rect.height).each do |row|
-          line = @clipped_lines[row] || @blank_line
-          draw_line(rect.left, rect.top + row, line)
+          line = @rows[row] || @blank_row
+          draw_text(rect.left, rect.top + row, line)
         end
       end
 
@@ -86,22 +86,22 @@ module Tuile
       # @return [void]
       def on_width_changed
         super
-        update_clipped_lines
+        update_rows
       end
 
       private
 
-      # Recomputes {@clipped_lines} for the current text and rect width.
+      # Recomputes {@rows} for the current text and rect width.
       # Each line is ellipsized to fit and padded with trailing spaces out to
-      # the full width, so {#repaint} is just a lookup + {Buffer#set_line} per
-      # row. {@blank_line} covers rows past the last text line. When {#bg} is
+      # the full width, so {#repaint} is just a lookup + {Buffer#set_text} per
+      # row. {@blank_row} covers rows past the last text line. When {#bg} is
       # set, every produced line (and the blank row) has the bg applied
       # uniformly.
       # @return [void]
-      def update_clipped_lines
+      def update_rows
         width = rect.width.clamp(0, nil)
-        @blank_line = apply_bg(StyledString.plain(" " * width))
-        @clipped_lines = @text.lines.map { |line| apply_bg(pad_to(line.ellipsize(width), width)) }
+        @blank_row = apply_bg(StyledString.plain(" " * width))
+        @rows = @text.lines.map { |line| apply_bg(pad_to(line.ellipsize(width), width)) }
       end
 
       # @param line [StyledString]