rubytui 1.2.3 → 1.2.4

data/lib/rubytui/widgets/paragraph.rb

@@ -10,24 +10,30 @@ module RubyTUI
     class Paragraph
       include Widget
 
-      # Wrap at whitespace; a single word wider than the area is not broken.
+      # Wrap at whitespace; a single word wider than the area is not broken
+      # and is clipped at the area's right edge.
       WRAP_WORD = :word
-      # Wrap at any character.
+      # Wrap between any two grapheme clusters (see {Unicode.cluster_width}), so a
+      # Devanagari conjunct or an emoji ZWJ sequence is never split and a
+      # two-column cluster moves to the next line rather than straddle the edge.
       WRAP_CHAR = :char
       # Do not wrap.
       WRAP_NONE = :none
 
       attr_reader :text, :style, :alignment, :wrap
 
-      # @param text [String, Line, Text, nil, #to_s] content; a String is split into
-      #   lines on newlines, +nil+ means no text, other objects are converted with
-      #   +to_s+ (default: nil)
-      # @param style [Style] base style under each span's style; when it is not
-      #   {Style::DEFAULT} it is also patched onto every cell of the area
-      #   (default: {Style::DEFAULT})
+      # @param text [String, Line, Text, Span, nil, #to_s] content; a String is split
+      #   into lines on newlines, a Span is split the same way into one-span Lines
+      #   that keep its {Span#style}, +nil+ means no text, other objects are
+      #   converted with +to_s+ (default: nil)
+      # @param style [Style] base style of the text. Each span is drawn with this
+      #   style patched ({Style#patch}) with {Text#style}, then {Line#style}, then
+      #   {Span#style}, so later layers win. When it is not {Style::DEFAULT} it is
+      #   also patched onto every cell of the area (default: {Style::DEFAULT})
       # @param alignment [Symbol] +:left+ (default), +:center+ or +:right+
       # @param wrap [Symbol] {WRAP_WORD} (default), {WRAP_CHAR} or {WRAP_NONE}. Wrapped
-      #   lines take the style of the original line's first span
+      #   lines take the style of the original line's first span and keep the
+      #   original line's {Line#style}
       # @param block [Widgets::Block, nil] optional wrapping block
       def initialize(
         text: nil,
@@ -46,8 +52,9 @@ module RubyTUI
       # Render the wrapped lines from the top of the area; lines beyond its height
       # are not drawn.
       #
-      # Lines are not clipped at the right edge of the area, only at the buffer
-      # edge, so unwrapped lines wider than the area extend past it.
+      # Lines wider than the area (with {WRAP_NONE}, or a long word with
+      # {WRAP_WORD}) are clipped at its right edge: nothing is drawn at or beyond
+      # it, and a two-column character that would straddle it is not drawn.
       #
       # @param area [Rect] the rectangular area to render into
       # @param buf [Buffer] the buffer to write cells into
@@ -76,6 +83,22 @@ module RubyTUI
         end
       end
 
+      # Number of lines {#render} draws, before clipping to the area's height, when
+      # the text is wrapped with {#wrap} to +width+ columns.
+      #
+      # @param width [Integer] width of the area the text is drawn in: the area
+      #   inside +block+ when the paragraph has one. A width of 0 or less does not
+      #   wrap
+      # @return [Integer] wrapped line count (0 when there is no text); empty lines
+      #   count as one line each
+      #
+      # @example Height needed to show all of the text
+      #   para = RubyTUI::Widgets::Paragraph.new(text: "alpha beta gamma delta")
+      #   para.line_count(10)  # => 3
+      def line_count(width)
+        wrap_lines(width).length
+      end
+
       private
 
       def normalize_text(text)
@@ -83,6 +106,7 @@ module RubyTUI
         when Text   then text
         when String then Text.from(text)
         when Line   then Text.new([text])
+        when Span   then Text.new(text.content.split("\n").map { |l| Line.from(l, text.style) })
         when nil    then Text.new([])
         else Text.from(text.to_s)
         end
@@ -117,7 +141,7 @@ module RubyTUI
         current_width = 0
 
         words.each do |word|
-          word_width = Buffer.string_width(word)
+          word_width = Unicode.string_width(word)
           if current.empty?
             current << word
             current_width = word_width
@@ -125,13 +149,13 @@ module RubyTUI
             current << word
             current_width += word_width
           else
-            wrapped << Line.from(current.rstrip, line_style) unless current.strip.empty?
+            wrapped << Line.new([Span.new(current.rstrip, line_style)], line.style) unless current.strip.empty?
             current = word.lstrip
-            current_width = Buffer.string_width(current)
+            current_width = Unicode.string_width(current)
           end
         end
 
-        wrapped << Line.from(current.rstrip, line_style) unless current.strip.empty?
+        wrapped << Line.new([Span.new(current.rstrip, line_style)], line.style) unless current.strip.empty?
         wrapped << Line.new if wrapped.empty?
         wrapped
       end
@@ -144,17 +168,18 @@ module RubyTUI
         current = String.new
         current_width = 0
 
-        plain.each_char do |ch|
-          ch_width = Buffer.char_width(ch)
-          if current_width + ch_width > max_width
-            wrapped << Line.from(current, line_style) unless current.empty?
+        # Break only between grapheme clusters, so conjuncts and ZWJ sequences stay whole
+        plain.grapheme_clusters.each do |gc|
+          gc_width = Unicode.cluster_width(gc)
+          if current_width + gc_width > max_width
+            wrapped << Line.new([Span.new(current, line_style)], line.style) unless current.empty?
             current = String.new
             current_width = 0
           end
-          current << ch
-          current_width += ch_width
+          current << gc
+          current_width += gc_width
         end
-        wrapped << Line.from(current, line_style) unless current.empty?
+        wrapped << Line.new([Span.new(current, line_style)], line.style) unless current.empty?
         wrapped << Line.new if wrapped.empty?
         wrapped
       end
@@ -169,11 +194,15 @@ module RubyTUI
 
         x = area.x + x_offset
         y = area.y + row
+        line_style = @style.patch(@text.style).patch(line.style)
 
         line.spans.each do |span|
-          effective_style = @style.patch(span.style)
-          count = buf.set_string(x, y, span.content, effective_style)
+          # Clip at the area's right edge; a wide cluster that would straddle it is dropped
+          content = Unicode.truncate_to_width(span.content, area.right - x)
+          effective_style = line_style.patch(span.style)
+          count = buf.set_string(x, y, content, effective_style)
           x += count
+          break if content.length < span.content.length
         end
       end
     end

data/lib/rubytui/widgets/scrollbar.rb

@@ -41,9 +41,12 @@ module RubyTUI
       #   (default: nil, the track length in cells, arrows included)
       # @param orientation [Symbol] {VERTICAL} (default) or {HORIZONTAL}; any other
       #   value is drawn horizontally
-      # @param style [Style] currently unused by rendering (default: {Style::DEFAULT})
-      # @param thumb_style [Style, nil] thumb style (default: white foreground)
-      # @param track_style [Style, nil] track and arrow style (default: bright black foreground)
+      # @param style [Style] base style; +thumb_style+ and +track_style+ are patched
+      #   onto it with {Style#patch} (default: {Style::DEFAULT})
+      # @param thumb_style [Style, nil] thumb style, patched onto +style+ (default: nil,
+      #   white foreground unless +style+ sets one)
+      # @param track_style [Style, nil] track and arrow style, patched onto +style+
+      #   (default: nil, bright black foreground unless +style+ sets one)
       # @param show_arrows [Boolean] draw an arrow at each end (default: true)
       def initialize(
         content_length:,
@@ -60,8 +63,8 @@ module RubyTUI
         @viewport_length = viewport_length
         @orientation = orientation
         @style = style
-        @thumb_style = thumb_style || Style.new.fg(Color::WHITE)
-        @track_style = track_style || Style.new.fg(Color::BRIGHT_BLACK)
+        @thumb_style = thumb_style ? style.patch(thumb_style) : Style.new.fg(Color::WHITE).patch(style)
+        @track_style = track_style ? style.patch(track_style) : Style.new.fg(Color::BRIGHT_BLACK).patch(style)
         @show_arrows = show_arrows
       end
 

data/lib/rubytui/widgets/table.rb

@@ -4,38 +4,42 @@ module RubyTUI
   module Widgets
     # TableState holds external state for the Table widget.
     #
-    # +selected+ is the index of the selected row and +offset+ the index of the
-    # first visible row. {Table#render} clamps both in place.
+    # +selected+ is the index of the selected row, or +nil+ for no selection, and
+    # +offset+ the index of the first visible row. {Table#render} clamps both in
+    # place; a +nil+ +selected+ is left as +nil+.
     #
     # @see Table
     class TableState
       attr_accessor :selected, :offset
 
-      # @param selected [Integer] initial selected row index (default: 0)
+      # @param selected [Integer, nil] initial selected row index; +nil+ selects no
+      #   row (default: 0)
       # @param offset [Integer] initial scroll offset (default: 0)
       def initialize(selected: 0, offset: 0)
         @selected = selected
         @offset = offset
       end
 
-      # Select the next row, wrapping from the last row to the first.
+      # Select the next row, wrapping from the last row to the first. With no
+      # selection (+nil+), selects the first row.
       #
       # Does nothing when +total+ is 0 or negative.
       #
       # @param total [Integer] number of rows in the table
       # @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 row, wrapping from the first row to the last.
+      # Select the previous row, wrapping from the first row to the last. With no
+      # selection (+nil+), selects the last row.
       #
       # Does nothing when +total+ is 0 or negative.
       #
       # @param total [Integer] number of rows in the table
       # @return [void]
       def select_previous(total)
-        @selected = (@selected - 1) % total if total > 0
+        @selected = ((@selected || 0) - 1) % total if total > 0
       end
     end
 
@@ -85,7 +89,7 @@ module RubyTUI
         @header_style = header_style || Style.new.fg(Color::CYAN).bold
         @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
         @column_spacing = column_spacing
         @block = block
@@ -94,8 +98,11 @@ module RubyTUI
       # Render the header, separator and visible rows.
       #
       # Clamps <tt>state.selected</tt> to the row range and adjusts
-      # <tt>state.offset</tt> in place so the selected row is visible. Cell text is
-      # truncated to its column width; explicit +widths+ are not reduced to fit the area.
+      # <tt>state.offset</tt> in place so the selected row is visible. When
+      # <tt>state.selected</tt> is +nil+, no row is highlighted or prefixed with
+      # +highlight_symbol+, +selected+ stays +nil+ and +offset+ is only clamped to the
+      # row range. Cell text is truncated to its column width; explicit +widths+ are
+      # not reduced to fit the area.
       #
       # @param area [Rect] the rectangular area to render into
       # @param buf [Buffer] the buffer to write cells into
@@ -140,11 +147,13 @@ module RubyTUI
 
         # Clamp state
         total = @rows.length
-        state.selected = state.selected.clamp(0, [total - 1, 0].max)
-        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)
+          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)
 
@@ -209,8 +218,8 @@ module RubyTUI
           break if i >= col_widths.length
 
           w = col_widths[i]
-          text = Buffer.truncate_to_width(cell.content, w)
-          text_width = Buffer.string_width(text)
+          text = Unicode.truncate_to_width(cell.content, w)
+          text_width = Unicode.string_width(text)
           effective_style = row_style.patch(cell.style)
           buf.set_string(x, y, text, effective_style)
 

data/lib/rubytui/widgets/tabs.rb

@@ -18,7 +18,8 @@ module RubyTUI
       # @param inactive_style [Style, nil] style of inactive tabs and dividers
       #   (default: bright black foreground)
       # @param divider [String] separator drawn between tabs (default: <tt>" │ "</tt>)
-      # @param highlight_style [Style, nil] currently unused by rendering (default: nil)
+      # @param highlight_style [Style, nil] patched onto the active tab's style after
+      #   +active_style+ (default: nil, no extra styling)
       # @param block [Widgets::Block, nil] optional wrapping block
       def initialize(
         titles: [],
@@ -65,12 +66,13 @@ module RubyTUI
 
           is_active = i == @selected
           tab_style = is_active ? @style.patch(@active_style) : @style.patch(@inactive_style)
+          tab_style = tab_style.patch(@highlight_style) if is_active && @highlight_style
 
           # Render tab title
           display = title.to_s
           available = render_area.right - x
-          display = Buffer.truncate_to_width(display, available)
-          display_width = Buffer.string_width(display)
+          display = Unicode.truncate_to_width(display, available)
+          display_width = Unicode.string_width(display)
 
           buf.set_string(x, y, display, tab_style)
           x += display_width
@@ -78,8 +80,8 @@ module RubyTUI
           # Render divider (except after last tab)
           if i < @titles.length - 1
             available = render_area.right - x
-            divider_text = Buffer.truncate_to_width(@divider, available)
-            divider_width = Buffer.string_width(divider_text)
+            divider_text = Unicode.truncate_to_width(@divider, available)
+            divider_width = Unicode.string_width(divider_text)
             buf.set_string(x, y, divider_text, @style.patch(@inactive_style))
             x += divider_width
           end

data/lib/rubytui.rb

@@ -61,7 +61,7 @@ require_relative "rubytui/input/reader"
 # App framework
 require_relative "rubytui/app"
 
-# A pure Ruby terminal user interface library.
+# A zero-dependency terminal user interface library.
 #
 # RubyTUI provides immediate-mode rendering with double buffering,
 # constraint-based layouts, and a duck-typed widget protocol.
@@ -206,6 +206,7 @@ module RubyTUI
     #
     # Renders a {Widgets::Table} with optional header, borders, and title,
     # then prints the ANSI output directly. Auto-calculates the required height.
+    # No row is selected, so no row is drawn in the highlight style.
     #
     # @param header [Array<String>, nil] column header labels
     # @param rows [Array<Array<String>>] table data rows
@@ -216,7 +217,8 @@ module RubyTUI
     # @param border_style [Style] style for the border characters (default: {Style::DEFAULT})
     # @param header_style [Style, nil] style for header row (default: cyan bold)
     # @param style [Style] base style for data rows (default: {Style::DEFAULT})
-    # @param highlight_symbol [String] prefix for the selected row (default: "  ")
+    # @param highlight_symbol [String] only its display width is used: every row is
+    #   prefixed with that many spaces, as no row is selected (default: "  ")
     # @param column_spacing [Integer] gap between columns (default: 1)
     # @param width [Integer, nil] total width in columns (default: auto-detect)
     # @param output [IO] output stream (default: $stdout)
@@ -245,7 +247,7 @@ module RubyTUI
         header_style: header_style, highlight_symbol: highlight_symbol,
         column_spacing: column_spacing, block: block_widget
       )
-      state = Widgets::TableState.new(selected: -1)  # No selection for one-shot
+      state = Widgets::TableState.new(selected: nil)  # No selection for one-shot
 
       # Calculate height: header(1) + separator(1) + rows + border(2)
       h = rows.length + (header ? 2 : 0) + (title ? 2 : 0)
@@ -264,7 +266,13 @@ module RubyTUI
     # then prints the ANSI output directly.
     #
     # @param title [String, nil] box title rendered on the top border
-    # @param content [String, Array<String>] text content (newlines or array of lines)
+    # @param content [String, Array<String>, Text, Line, Span, nil] text content: a
+    #   String split on newlines, an Array of lines (an element may itself contain
+    #   newlines), or a {Text}, {Line} or {Span}. Lines are word-wrapped to the box's
+    #   inner width (+width+ - 2) and the box is tall enough for every wrapped line
+    #   ({Widgets::Paragraph#line_count}). Trailing empty lines of a String or Array
+    #   are dropped (see {Text#initialize}); empty content (+nil+, <tt>""</tt>,
+    #   <tt>[]</tt>) gives one empty row
     # @param border [Symbol, Symbols::BorderSet] border style — +:rounded+, +:double+,
     #   +:thick+, +:light+, +:plain+, or a {Symbols::BorderSet} (default: +:rounded+)
     # @param border_style [Style] style for the border characters (default: {Style::DEFAULT})
@@ -303,11 +311,8 @@ module RubyTUI
       )
 
       w = width || terminal_width(output)
-      line_count = case content
-                   when String then content.count("\n") + 1
-                   when Array  then content.length
-                   else 1
-                   end
+      # Lines after wrapping to the inner width; at least one (empty) row
+      line_count = [para.line_count(w - 2), 1].max
       h = line_count + 2  # +2 for borders
 
       area = Rect.new(0, 0, w, h)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rubytui
 version: !ruby/object:Gem::Version
-  version: 1.2.3
+  version: 1.2.4
 platform: ruby
 authors:
 - CoCL
@@ -10,7 +10,7 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  A pure Ruby, zero-dependency terminal user interface library featuring
+  A zero-dependency terminal user interface library featuring
   immediate-mode rendering with double buffering, constraint-based layouts,
   a duck-typed widget system, cross-platform input handling, and Kitty
   graphics protocol support for inline images.
@@ -85,5 +85,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.19
 specification_version: 4
-summary: Pure Ruby, zero-dependency terminal user interface library
+summary: Zero-dependency terminal user interface library
 test_files: []