rubytui 1.2.3 → 1.2.4

data/lib/rubytui/widgets/canvas.rb

@@ -30,14 +30,20 @@ module RubyTUI
       # Code point of the empty Braille pattern (U+2800); dot bits are added to it.
       BRAILLE_BASE = 0x2800
 
-      attr_reader :width, :height
+      # @deprecated Always returns nil; will be removed in 2.0.
+      # @return [nil]
+      attr_reader :width
+
+      # @deprecated Always returns nil; will be removed in 2.0.
+      # @return [nil]
+      attr_reader :height
 
       # @param x_bounds [Array(Numeric, Numeric), nil] <tt>[min, max]</tt> data range
       #   mapped to the canvas width (default: nil, computed from the x coordinates
       #   of points and lines)
       # @param y_bounds [Array(Numeric, Numeric), nil] <tt>[min, max]</tt> data range
-      #   mapped to the canvas height, max at the top (default: nil; the automatic
-      #   range is currently also computed from the x coordinates of points and lines)
+      #   mapped to the canvas height, max at the top (default: nil, computed from
+      #   the y coordinates of points and lines)
       # @param style [Style] style for labels added without a style (default: {Style::DEFAULT})
       # @param marker_style [Style, nil] style for dots drawn without a style
       #   (default: white foreground)
@@ -97,7 +103,9 @@ module RubyTUI
       #
       # @param x [Numeric] x data coordinate
       # @param y [Numeric] y data coordinate
-      # @param text [String] text drawn starting at the cell that contains (x, y)
+      # @param text [String] text drawn starting at the cell that contains (x, y),
+      #   clipped at the right edge of the area (inside +block+); a two-column
+      #   character that would straddle the edge is not drawn
       # @param style [Style, nil] text style (default: nil, uses the canvas +style+)
       # @return [self]
       def label(x, y, text, style: nil)
@@ -109,7 +117,8 @@ module RubyTUI
       #
       # Lines are drawn first, then points, as Braille dots. Each cell takes the
       # style of the last styled dot drawn in it, otherwise +marker_style+. Labels
-      # are drawn last, on top of the dots. Added shapes are kept between renders.
+      # are drawn last, on top of the dots, and clipped at the area's right edge,
+      # so nothing is drawn outside the area. Added shapes are kept between renders.
       #
       # @param area [Rect] the rectangular area to render into
       # @param buf [Buffer] the buffer to write cells into
@@ -134,8 +143,8 @@ module RubyTUI
         style_grid = Array.new(render_area.height) { Array.new(render_area.width, nil) }
 
         # Compute bounds
-        x_min, x_max = compute_bounds(@x_bounds, canvas_w)
-        y_min, y_max = compute_bounds(@y_bounds, canvas_h)
+        x_min, x_max = compute_bounds(@x_bounds, canvas_w, 0)
+        y_min, y_max = compute_bounds(@y_bounds, canvas_h, 1)
 
         # Rasterize lines
         @lines.each do |x1, y1, x2, y2, lstyle|
@@ -161,26 +170,29 @@ module RubyTUI
           end
         end
 
-        # Render labels
+        # Render labels, clipped at the area's right edge (the start cell is always
+        # inside, as coordinates are clamped)
         @labels.each do |lx, ly, text, lstyle|
           cx, cy = data_to_canvas(lx, ly, x_min, x_max, y_min, y_max, canvas_w, canvas_h)
           cell_x = render_area.x + cx / 2
           cell_y = render_area.y + cy / 4
-          buf.set_string(cell_x, cell_y, text, lstyle || @style)
+          clipped = Unicode.truncate_to_width(text, render_area.right - cell_x)
+          buf.set_string(cell_x, cell_y, clipped, lstyle || @style)
         end
       end
 
       private
 
-      def compute_bounds(bounds, canvas_size)
+      # axis: 0 for x, 1 for y (index into points and into each line's endpoints)
+      def compute_bounds(bounds, canvas_size, axis)
         if bounds
           [bounds[0].to_f, bounds[1].to_f]
         else
-          all_x = @points.map { |p| p[0] } + @lines.flat_map { |l| [l[0], l[2]] }
-          return [0.0, canvas_size.to_f] if all_x.empty?
+          coords = @points.map { |p| p[axis] } + @lines.flat_map { |l| [l[axis], l[axis + 2]] }
+          return [0.0, canvas_size.to_f] if coords.empty?
 
-          mn = all_x.min.to_f
-          mx = all_x.max.to_f
+          mn = coords.min.to_f
+          mx = coords.max.to_f
           mx = mn + 1 if mx == mn
           [mn, mx]
         end

data/lib/rubytui/widgets/chart.rb

@@ -29,14 +29,24 @@ module RubyTUI
       # @param datasets [Array<Dataset>] series to plot; datasets with fewer than
       #   2 points are skipped (default: [])
       # @param x_axis [Array(String, Numeric, Numeric), nil] <tt>[label, min, max]</tt>;
-      #   +min+/+max+ may be nil for bounds computed from the data. When set, one row
-      #   is reserved for the axis and the label is drawn centered on it (default: nil,
-      #   bounds computed from the data and no row reserved)
+      #   +min+/+max+ may be nil for bounds computed from the data. The bottom row of
+      #   the area is always reserved for the x axis line and its min/max values;
+      #   when set, the label is also drawn centered on it, over the values. The
+      #   label and min value are truncated to the plot width (whole grapheme
+      #   clusters), and the max value is omitted when it would overlap the min
+      #   value (default: nil, bounds computed from the data and no label)
       # @param y_axis [Array(String, Numeric, Numeric), nil] <tt>[label, min, max]</tt>;
       #   +min+/+max+ may be nil for bounds computed from the data. When set, the
       #   min/max values are drawn left of a vertical axis line and the label's first
-      #   character at mid-height (default: nil, no y axis; bounds computed from the data)
-      # @param style [Style] currently unused by rendering (default: {Style::DEFAULT})
+      #   character at mid-height. The label column is as wide as the wider of the
+      #   min/max values drawn, i.e. of the final bounds (computed bounds with equal
+      #   min and max are widened to <tt>max = min + 1</tt>) (default: nil, no y
+      #   axis; bounds computed from the data)
+      # @param style [Style, nil] base style of the area inside +block+: when it is
+      #   not {Style::DEFAULT} it is patched onto every cell, and the axis lines,
+      #   labels and plotted dots are drawn with this style patched ({Style#patch})
+      #   with their own style, so e.g. a background shows through everywhere.
+      #   +nil+ is treated as {Style::DEFAULT} (default: {Style::DEFAULT})
       # @param axis_style [Style, nil] axis line style (default: bright black foreground)
       # @param label_style [Style, nil] style of axis labels and min/max values
       #   (default: white foreground)
@@ -53,15 +63,17 @@ module RubyTUI
         @datasets = datasets
         @x_axis = x_axis
         @y_axis = y_axis
-        @style = style
-        @axis_style = axis_style || Style.new.fg(Color::BRIGHT_BLACK)
-        @label_style = label_style || Style.new.fg(Color::WHITE)
+        @style = style || Style::DEFAULT
+        @axis_style = @style.patch(axis_style || Style.new.fg(Color::BRIGHT_BLACK))
+        @label_style = @style.patch(label_style || Style.new.fg(Color::WHITE))
         @block = block
       end
 
       # Render the axes and draw each dataset as connected line segments on a {Canvas}.
       #
-      # Nothing is drawn, not even +block+, when there are no datasets.
+      # The x axis occupies the bottom row of the area (inside +block+), so the
+      # plot is one row shorter than the area. Nothing is drawn outside the area;
+      # nothing at all, not even +block+, when there are no datasets.
       #
       # @param area [Rect] the rectangular area to render into
       # @param buf [Buffer] the buffer to write cells into
@@ -77,9 +89,15 @@ module RubyTUI
 
         return if render_area.empty?
 
-        # Reserve space for axes
-        y_label_width = compute_y_label_width
-        x_label_height = @x_axis ? 1 : 0
+        buf.set_style(render_area, @style) if @style != Style::DEFAULT
+
+        # Compute data bounds
+        x_min, x_max = compute_x_bounds
+        y_min, y_max = compute_y_bounds
+
+        # Reserve space for axes; the x axis row is drawn even without +x_axis+
+        y_label_width = compute_y_label_width(y_min, y_max)
+        x_label_height = 1
         y_label_area_width = y_label_width > 0 ? y_label_width + 1 : 0
 
         chart_area = Rect.new(
@@ -91,27 +109,25 @@ module RubyTUI
 
         return if chart_area.empty?
 
-        # Compute data bounds
-        x_min, x_max = compute_x_bounds
-        y_min, y_max = compute_y_bounds
-
         # Draw axes
         render_y_axis(render_area, chart_area, buf, y_min, y_max)
         render_x_axis(render_area, chart_area, buf, x_min, x_max)
 
-        # Draw data using Canvas
+        # Draw data using Canvas; a nil dataset style falls back to the marker style
         canvas = Canvas.new(
           x_bounds: [x_min, x_max],
-          y_bounds: [y_min, y_max]
+          y_bounds: [y_min, y_max],
+          marker_style: @style.patch(Style.new.fg(Color::WHITE))
         )
 
         @datasets.each do |ds|
           points = ds.data
           next if points.length < 2
 
+          line_style = ds.style && @style.patch(ds.style)
           # Draw lines between consecutive points
           points.each_cons(2) do |(x1, y1), (x2, y2)|
-            canvas.line(x1, y1, x2, y2, style: ds.style)
+            canvas.line(x1, y1, x2, y2, style: line_style)
           end
         end
 
@@ -120,18 +136,11 @@ module RubyTUI
 
       private
 
-      def compute_y_label_width
+      # Width of the y min/max labels as drawn, i.e. from the final bounds
+      def compute_y_label_width(y_min, y_max)
         return 0 unless @y_axis
 
-        _, y_min, y_max = @y_axis
-        if y_min && y_max
-          [format_num(y_min).length, format_num(y_max).length].max
-        else
-          all_y = @datasets.flat_map { |ds| ds.data.map { |_, y| y } }
-          return 0 if all_y.empty?
-
-          [format_num(all_y.min).length, format_num(all_y.max).length].max
-        end
+        [format_num(y_min).length, format_num(y_max).length].max
       end
 
       def compute_x_bounds
@@ -199,18 +208,22 @@ module RubyTUI
           buf[chart_area.x - 1, x_axis_y]&.set("\u2514", @axis_style)
         end
 
-        # X labels at left and right
-        min_str = format_num(x_min)
+        # X labels at left and right, truncated to the plot width; the max label
+        # is omitted when it would overlap the min label
+        min_str = Unicode.truncate_to_width(format_num(x_min), chart_area.width)
         max_str = format_num(x_max)
         buf.set_string(chart_area.x, x_axis_y, min_str, @label_style)
-        max_x = chart_area.right - Buffer.string_width(max_str)
-        buf.set_string([max_x, chart_area.x].max, x_axis_y, max_str, @label_style)
+        max_x = chart_area.right - Unicode.string_width(max_str)
+        if max_x >= chart_area.x + Unicode.string_width(min_str)
+          buf.set_string(max_x, x_axis_y, max_str, @label_style)
+        end
 
-        # X axis label (centered)
+        # X axis label (centered, truncated to the plot width)
         if @x_axis
           label = @x_axis[0]
           if label && !label.empty?
-            lx = chart_area.x + (chart_area.width - Buffer.string_width(label)) / 2
+            label = Unicode.truncate_to_width(label, chart_area.width)
+            lx = chart_area.x + (chart_area.width - Unicode.string_width(label)) / 2
             buf.set_string(lx, x_axis_y, label, @label_style)
           end
         end

data/lib/rubytui/widgets/gauge.rb

@@ -108,7 +108,7 @@ module RubyTUI
 
         # Render label centered, with per-character style blending
         label_text = @label || "#{(@ratio * 100).round}%"
-        label_width = Buffer.string_width(label_text)
+        label_width = Unicode.string_width(label_text)
         if label_width <= width
           label_x = render_area.x + (width - label_width) / 2
           label_y = render_area.y + render_area.height / 2
@@ -122,7 +122,7 @@ module RubyTUI
 
           cx = label_x
           label_text.each_char do |ch|
-            ch_w = Buffer.char_width(ch)
+            ch_w = Unicode.char_width(ch)
             col_offset = cx - render_area.x
             char_style = col_offset < boundary ? filled_label_style : empty_label_style
             buf[cx, label_y]&.set(ch, char_style)

data/lib/rubytui/widgets/image.rb

@@ -90,10 +90,12 @@ module RubyTUI
       # @param clip [Boolean] if true, clamp rendering to the available area (default: true)
       # @param cell_size [Array(Integer, Integer), nil] cell pixel dimensions [width, height] for aspect calculations
       #   (default: nil, uses <tt>[9, 18]</tt>)
-      # @raise [ArgumentError] if neither +path+ nor +data+ is given, if PNG data is
-      #   truncated, or if +pixel_width+/+pixel_height+ are missing for +:rgba+ data
-      #   (including data whose format is not recognized)
-      # @raise [UnsupportedImageFormat] if the image is JPEG, WebP, GIF or BMP
+      # @raise [ArgumentError] if neither +path+ nor +data+ is given, if +data+ is
+      #   given with a +format+ other than +:png+ or +:rgba+ (e.g. +:tiff+, a String
+      #   or +nil+), if PNG data is truncated, or if +pixel_width+/+pixel_height+ are
+      #   missing for +:rgba+ data (including data whose format is not recognized)
+      # @raise [UnsupportedImageFormat] if the image is JPEG, WebP, GIF or BMP (detected,
+      #   or given as +format+ with +data+)
       # @raise [SystemCallError] if +path+ cannot be read
       def initialize(path: nil, data: nil, pixel_width: nil, pixel_height: nil,
                      format: :png, style: Style::DEFAULT, block: nil,
@@ -306,6 +308,8 @@ module RubyTUI
           raise UnsupportedImageFormat,
             "BMP format not supported by Kitty graphics protocol. Convert to PNG first:\n" \
             "  system(\"magick\", \"input.bmp\", \"output.png\")"
+        else
+          raise ArgumentError, "Unknown image format #{fmt.inspect}; expected :png or :rgba"
         end
       end
 

data/lib/rubytui/widgets/input_field.rb

@@ -9,6 +9,10 @@ module RubyTUI
     #
     # @see InputField
     class InputState
+      # Characters that separate words for {#delete_word_back} (readline's
+      # whitespace: space and tab).
+      WORD_SEPARATORS = [" ", "\t"].freeze
+
       attr_accessor :text, :cursor, :scroll_offset
 
       # @param text [String] initial text; a mutable copy is stored (default: "")
@@ -101,19 +105,25 @@ module RubyTUI
 
       # Delete the word before the cursor
       #
-      # Deletes any spaces directly before the cursor and the run of non-space
-      # characters before them. Only the space character counts as a separator.
-      # Does nothing when the cursor is at the start.
+      # Readline-style Ctrl-W (unix-word-rubout): deletes the whitespace directly
+      # before the cursor, then the run of non-whitespace characters before it,
+      # stopping at (and keeping) the preceding whitespace. Space and tab count as
+      # whitespace. The cursor moves to the start of the deleted range. Does
+      # nothing when the cursor is at the start.
+      #
+      # @example
+      #   state = InputState.new(text: " foo bar  ", cursor: 10)
+      #   state.delete_word_back  # text: " foo ", cursor: 5
+      #   state.delete_word_back  # text: " ", cursor: 1
       #
       # @return [void]
       def delete_word_back
         return if @cursor == 0
 
         # Find start of previous word
-        pos = @cursor - 1
-        pos -= 1 while pos > 0 && @text[pos] == " "
-        pos -= 1 while pos > 0 && @text[pos] != " "
-        pos += 1 if pos > 0
+        pos = @cursor
+        pos -= 1 while pos > 0 && WORD_SEPARATORS.include?(@text[pos - 1])
+        pos -= 1 while pos > 0 && !WORD_SEPARATORS.include?(@text[pos - 1])
 
         @text.slice!(pos...@cursor)
         @cursor = pos
@@ -194,7 +204,14 @@ module RubyTUI
       # the area and apply +cursor_style+ to the cell at the cursor.
       #
       # Updates <tt>state.scroll_offset</tt> in place so the cursor stays visible.
-      # Scrolling and cursor placement count characters, not display columns.
+      # Scrolling and cursor placement count display columns per grapheme
+      # cluster: wide characters (CJK, emoji) take two columns, and the visible
+      # text and placeholder are truncated to the area width. The cursor is drawn
+      # at the column after the clusters that precede it; a cursor inside a
+      # multi-codepoint cluster (e.g. a letter plus a combining mark) is drawn on
+      # that cluster's cell. <tt>state.cursor</tt> and <tt>state.scroll_offset</tt>
+      # remain character indices; +scroll_offset+ is moved to the start of a
+      # cluster. Positions past the end of the text count as one column each.
       #
       # @param area [Rect] the rectangular area to render into
       # @param buf [Buffer] the buffer to write cells into
@@ -212,26 +229,41 @@ module RubyTUI
         return if render_area.empty?
 
         width = render_area.width
+        text = state.text
+
+        # Character index where each grapheme cluster starts, and its display width
+        starts = []
+        widths = []
+        pos = 0
+        text.grapheme_clusters.each do |gc|
+          starts << pos
+          widths << Unicode.cluster_width(gc)
+          pos += gc.length
+        end
 
-        # Adjust scroll offset to keep cursor visible
-        if state.cursor < state.scroll_offset
-          state.scroll_offset = state.cursor
-        elsif state.cursor >= state.scroll_offset + width
-          state.scroll_offset = state.cursor - width + 1
+        # Adjust scroll offset (in clusters) so the cursor cell fits in the area
+        cursor = cluster_index(starts, text.length, state.cursor)
+        first = [cluster_index(starts, text.length, state.scroll_offset), cursor].min
+        cursor_width = [widths[cursor] || 1, 1].max
+        cursor_col = (first...cursor).sum { |i| widths[i] || 1 }
+        while first < cursor && cursor_col + cursor_width > width
+          cursor_col -= widths[first] || 1
+          first += 1
         end
+        state.scroll_offset = first < starts.size ? starts[first] : text.length + first - starts.size
 
-        if state.text.empty?
+        if text.empty?
           # Show placeholder
-          visible = @placeholder[0, width]
+          visible = Unicode.truncate_to_width(@placeholder, width)
           buf.set_string(render_area.x, render_area.y, visible, @placeholder_style)
         else
           # Show text with scrolling
-          visible = state.text[state.scroll_offset, width] || ""
+          visible = Unicode.truncate_to_width(text[state.scroll_offset..] || "", width)
           buf.set_string(render_area.x, render_area.y, visible, @style)
         end
 
         # Draw cursor
-        cursor_screen_x = render_area.x + state.cursor - state.scroll_offset
+        cursor_screen_x = render_area.x + cursor_col
         if cursor_screen_x >= render_area.x && cursor_screen_x < render_area.right
           cell = buf[cursor_screen_x, render_area.y]
           if cell
@@ -240,6 +272,16 @@ module RubyTUI
           end
         end
       end
+
+      private
+
+      # Index of the grapheme cluster containing character +index+. Positions at
+      # or past the end of the text count as one single-column cluster each.
+      def cluster_index(starts, length, index)
+        return starts.size + index - length if index >= length
+
+        (starts.bsearch_index { |s| s > index } || starts.size) - 1
+      end
     end
   end
 end

data/lib/rubytui/widgets/list.rb

@@ -4,38 +4,42 @@ module RubyTUI
   module Widgets
     # ListState holds external state for the List widget.
     #
-    # +selected+ is the index of the selected item and +offset+ the index of the
-    # first visible item. {List#render} clamps both in place.
+    # +selected+ is the index of the selected item, or +nil+ for no selection, and
+    # +offset+ the index of the first visible item. {List#render} clamps both in
+    # place; a +nil+ +selected+ is left as +nil+.
     #
     # @see List
     class ListState
       attr_accessor :selected, :offset
 
-      # @param selected [Integer] initial selected index (default: 0)
+      # @param selected [Integer, nil] initial selected index; +nil+ selects no item
+      #   (default: 0)
       # @param offset [Integer] initial scroll offset (default: 0)
       def initialize(selected: 0, offset: 0)
         @selected = selected
         @offset = offset
       end
 
-      # Select the next item, wrapping from the last item to the first.
+      # Select the next item, wrapping from the last item to the first. With no
+      # selection (+nil+), selects the first item.
       #
       # Does nothing when +total+ is 0 or negative.
       #
       # @param total [Integer] number of items in the list
       # @return [void]
       def select_next(total)
-        @selected = (@selected + 1) % total if total > 0
+        @selected = ((@selected || -1) + 1) % total if total > 0
       end
 
-      # Select the previous item, wrapping from the first item to the last.
+      # Select the previous item, wrapping from the first item to the last. With no
+      # selection (+nil+), selects the last item.
       #
       # Does nothing when +total+ is 0 or negative.
       #
       # @param total [Integer] number of items in the list
       # @return [void]
       def select_previous(total)
-        @selected = (@selected - 1) % total if total > 0
+        @selected = ((@selected || 0) - 1) % total if total > 0
       end
 
       # Select the first item and reset the scroll offset to 0.
@@ -90,7 +94,7 @@ module RubyTUI
         @style = style
         @highlight_style = highlight_style || Style.new.fg(Color::YELLOW).bold
         @highlight_symbol = highlight_symbol
-        @highlight_symbol_width = Buffer.string_width(@highlight_symbol)
+        @highlight_symbol_width = Unicode.string_width(@highlight_symbol)
         @normal_symbol = " " * @highlight_symbol_width
         @block = block
       end
@@ -99,8 +103,11 @@ module RubyTUI
       # +highlight_symbol+ and +highlight_style+.
       #
       # Clamps <tt>state.selected</tt> to the item range and adjusts
-      # <tt>state.offset</tt> in place so the selected item is visible. Item text is
-      # truncated to the area width; span styles are patched onto the item style.
+      # <tt>state.offset</tt> in place so the selected item is visible. When
+      # <tt>state.selected</tt> is +nil+, no item is highlighted or prefixed with
+      # +highlight_symbol+, +selected+ stays +nil+ and +offset+ is only clamped to the
+      # item range. Item text is truncated to the area width; span styles are patched
+      # onto the item style.
       #
       # @param area [Rect] the rectangular area to render into
       # @param buf [Buffer] the buffer to write cells into
@@ -141,8 +148,8 @@ module RubyTUI
           item.spans.each do |span|
             break if available <= 0
 
-            text = Buffer.truncate_to_width(span.content, available)
-            text_width = Buffer.string_width(text)
+            text = Unicode.truncate_to_width(span.content, available)
+            text_width = Unicode.string_width(text)
             effective_style = item_style.patch(span.style)
             buf.set_string(x, y, text, effective_style)
             x += text_width
@@ -170,13 +177,15 @@ module RubyTUI
 
       def clamp_state(state, visible_height)
         total = @items.length
-        state.selected = state.selected.clamp(0, [total - 1, 0].max)
-
-        # Scroll to keep selected visible
-        if state.selected < state.offset
-          state.offset = state.selected
-        elsif state.selected >= state.offset + visible_height
-          state.offset = state.selected - visible_height + 1
+        if state.selected
+          state.selected = state.selected.clamp(0, [total - 1, 0].max)
+
+          # Scroll to keep selected visible
+          if state.selected < state.offset
+            state.offset = state.selected
+          elsif state.selected >= state.offset + visible_height
+            state.offset = state.selected - visible_height + 1
+          end
         end
 
         state.offset = state.offset.clamp(0, [total - visible_height, 0].max)