tuile 0.11.0 → 0.13.0

data/lib/tuile/ansi.rb

@@ -12,6 +12,16 @@ module Tuile
     # @return [String]
     RESET = "\e[0m"
 
+    # The bell (`BEL`, `\a`, 0x07) — the "that keystroke went nowhere" signal.
+    # Ring it with {Screen#beep} rather than printing it: the bell is terminal
+    # IO, which is {Screen}'s job.
+    #
+    # What the user gets is the *terminal's* business — an audible beep, a
+    # visual flash, or nothing at all — and Tuile keeps no preference of its
+    # own about that.
+    # @return [String]
+    BEL = "\a"
+
     # Begin Synchronized Update (DEC private mode 2026, "Synchronized
     # Output"). The terminal stops refreshing its display and buffers every
     # subsequent write until {SYNC_END}, then composites the whole batch

data/lib/tuile/buffer.rb

@@ -3,7 +3,7 @@
 module Tuile
   # An in-memory grid of styled cells mirroring the terminal screen. This is
   # the back buffer behind flicker-free rendering: components paint into it
-  # (via {#set_line} / {#set_char} / {#fill}) instead of writing escape
+  # (via {#set_text} / {#set_char} / {#fill}) instead of writing escape
   # sequences straight to the terminal, and {#flush} emits the minimal escape
   # string needed to bring a terminal — one that already matches the buffer's
   # state as of the previous flush — up to date. Only cells that actually
@@ -133,7 +133,7 @@ module Tuile
     # @param x [Integer] column.
     # @param y [Integer] row.
     # @return [Cell, nil] the live cell at `(x, y)` (do not mutate — paint via
-    #   {#set_char} / {#set_line} so dirty tracking stays correct), or nil when
+    #   {#set_char} / {#set_text} so dirty tracking stays correct), or nil when
     #   out of bounds.
     def cell(x, y)
       return nil unless in_bounds?(x, y)
@@ -160,12 +160,12 @@ module Tuile
 
     # Writes a {StyledString} starting at `(x, y)`, advancing by each grapheme's
     # display width and clipping at the right edge. Newlines are not handled —
-    # pass one physical line.
+    # pass the text of one row.
     # @param x [Integer] starting column.
     # @param y [Integer] row.
     # @param styled [StyledString]
     # @return [void]
-    def set_line(x, y, styled)
+    def set_text(x, y, styled)
       col = x
       styled.spans.each do |span|
         span.text.grapheme_clusters.each do |g|
@@ -281,7 +281,7 @@ module Tuile
     # @param y [Integer] row.
     # @return [String] row `y` rendered to ANSI across its full width — the
     #   minimal-SGR encoding of its cells, equivalent to what a component's
-    #   `set_line` of the whole row would have printed. Intended for tests that
+    #   `set_text` of the whole row would have printed. Intended for tests that
     #   assert on styled output (see {FakeScreen}); empty for an out-of-range row.
     def row_ansi(y)
       return "" unless y >= 0 && y < @height
@@ -304,7 +304,7 @@ module Tuile
 
     # @param rect [Rect]
     # @return [Array<String>] each row within `rect` rendered to ANSI, top to
-    #   bottom — byte-identical to what a component's per-row `set_line` over
+    #   bottom — byte-identical to what a component's per-row `set_text` over
     #   that rect emitted. The region equivalent of {#row_ansi}. Intended for
     #   tests asserting styled output.
     def region_ansi(rect)
@@ -316,7 +316,7 @@ module Tuile
     private
 
     # Core of {#set_char} with the grapheme's display width already known.
-    # {#set_line} computes each width once while advancing the column and passes
+    # {#set_text} computes each width once while advancing the column and passes
     # it straight through, so the paint hot path measures every grapheme exactly
     # once (and that once is a {.display_width} memo read). See {#set_char} for
     # the wide-glyph / clipping / out-of-bounds contract.

data/lib/tuile/component/abstract_string_field.rb

@@ -42,6 +42,8 @@ module Tuile
     #
     # - {#preprocess_text} — input filter (e.g. {TextField} truncates to
     #   fit `rect.width - 1`).
+    # - {#preprocess_paste} — the same for {#handle_paste}, which lands a
+    #   whole clipboard at the caret in one mutation.
     # - {#on_text_mutated} / {#on_caret_mutated} — post-mutation side
     #   effects (e.g. {TextArea} invalidates its wrap cache and scrolls to
     #   keep the caret visible).
@@ -155,8 +157,42 @@ module Tuile
         handle_text_input_key(key)
       end
 
+      # Inserts pasted text at the caret as **one** mutation, so {#on_change}
+      # fires once for the whole paste rather than once per character.
+      # {#preprocess_paste} filters it first.
+      # @param text [String]
+      # @return [Boolean] always true — a field consumes every paste, an empty
+      #   one included.
+      def handle_paste(text)
+        insert_text(preprocess_paste(text))
+        true
+      end
+
       protected
 
+      # Input filter for {#handle_paste}, the paste-side counterpart of
+      # {#preprocess_text}. Strips the C0 control characters a text buffer
+      # cannot hold — a raw `\e` or `\t` reaching {Buffer} would move the real
+      # terminal cursor mid-frame — keeping `\n`, and turning a tab into a
+      # single space so pasted code keeps its word gaps. {TextField} narrows it
+      # further; an app wanting tab *expansion* overrides {#handle_paste}.
+      # @param text [String]
+      # @return [String]
+      def preprocess_paste(text) = text.tr("\t", " ").gsub(/[\x00-\x09\x0b-\x1f\x7f]/, "")
+
+      # Inserts `str` at the caret, leaving the caret behind it. The bulk
+      # counterpart of a subclass's per-key insert.
+      # @param str [String]
+      # @return [Boolean] true if the text changed.
+      def insert_text(str)
+        return false if str.empty?
+
+        new_text = @text.dup.insert(@caret, str)
+        @caret += str.length
+        self.text = new_text
+        true
+      end
+
       # Renders `text` on the field's background well, looked up from the
       # current {Screen#theme} at paint time: {Theme#active_bg_color} when this
       # input is on the active (focus) chain, {Theme#input_bg_color} otherwise —

data/lib/tuile/component/button.rb

@@ -76,7 +76,7 @@ module Tuile
 
         label = (StyledString.plain("[ ") + caption + StyledString.plain(" ]")).ellipsize(rect.width)
         label = label.with_bg(screen.theme.active_bg_color) if active?
-        draw_line(rect.left, rect.top, label)
+        draw_text(rect.left, rect.top, label)
       end
     end
   end

data/lib/tuile/component/checkbox.rb

@@ -127,7 +127,7 @@ module Tuile
 
         label = (StyledString.plain(value ? "[x] " : "[ ] ") + caption).ellipsize(rect.width)
         label = label.with_bg(screen.theme.active_bg_color) if active?
-        draw_line(rect.left, rect.top, label)
+        draw_text(rect.left, rect.top, label)
       end
     end
   end

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,11 @@ module Tuile
         self.content = field
 
         @overlay = ListDropdown.new
-        @overlay.on_item_chosen = ->(index, _line) { commit(index) }
+        # Outside-click dismissal spans the owner chain, so a click on this
+        # combo's dropdown must not dismiss a dialog the combo sits in.
+        @overlay.owner = self
+        @overlay.renderer = ->(item) { @item_label.call(item) }
+        @overlay.on_item_chosen = ->(_index, item) { commit(item) }
       end
 
       # @return [Array] the candidate items.
@@ -97,7 +101,6 @@ module Tuile
       def cursor_position = content.cursor_position
 
       # @return [String]
-      def keyboard_hint = "↑↓ #{screen.theme.hint("select")}  ⏎ #{screen.theme.hint("accept")}"
 
       # Re-anchors the (open) dropdown after {HasContent#rect=} has resized the
       # field via {#layout}.
@@ -195,7 +198,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 +217,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 +237,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]