rubytui 1.2.3

data/lib/rubytui/widgets/popup.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # Popup renders an overlay on top of existing content.
+    # It clears its area, optionally draws a drop shadow, and draws its block;
+    # popup content is rendered separately into {#inner}.
+    #
+    # @example
+    #   popup = RubyTUI::Widgets::Popup.new(width: 40, height: 7, shadow: true)
+    #   popup.render(frame.area, frame.buffer)
+    #   inner = popup.inner(frame.area)  # draw popup content here
+    class Popup
+      include Widget
+
+      # @param width [Integer, nil] fixed width, clamped to the parent width
+      #   (default: nil, uses +width_percent+)
+      # @param height [Integer, nil] fixed height, clamped to the parent height
+      #   (default: nil, uses +height_percent+)
+      # @param width_percent [Integer] width as a percentage of the parent width when
+      #   +width+ is nil (default: 60)
+      # @param height_percent [Integer] height as a percentage of the parent height when
+      #   +height+ is nil (default: 60)
+      # @param x [Integer, nil] absolute column of the left edge (default: nil, centered
+      #   horizontally in the parent area)
+      # @param y [Integer, nil] absolute row of the top edge (default: nil, centered
+      #   vertically in the parent area)
+      # @param block [Widgets::Block, nil] border/title block (default: nil, a block with
+      #   all borders and {Symbols::ROUNDED} border characters)
+      # @param style [Style] style used to clear the popup area (default: {Style::DEFAULT})
+      # @param shadow [Boolean] draw a one-cell shadow to the right of and below the
+      #   popup (default: false)
+      # @param shadow_style [Style, nil] shadow style (default: bright black foreground
+      #   on a black background)
+      def initialize(
+        width: nil,          # fixed width or nil for percentage
+        height: nil,         # fixed height or nil for percentage
+        width_percent: 60,   # percentage of parent width
+        height_percent: 60,  # percentage of parent height
+        x: nil,              # fixed x position or nil for centered
+        y: nil,              # fixed y position or nil for centered
+        block: nil,          # Block widget for border/title
+        style: Style::DEFAULT,
+        shadow: false,
+        shadow_style: nil
+      )
+        @fixed_width = width
+        @fixed_height = height
+        @width_percent = width_percent
+        @height_percent = height_percent
+        @fixed_x = x
+        @fixed_y = y
+        @block = block || Widgets::Block.new(borders: :all, border_set: Symbols::ROUNDED)
+        @style = style
+        @shadow = shadow
+        @shadow_style = shadow_style || Style.new.fg(Color::BRIGHT_BLACK).bg(Color::BLACK)
+      end
+
+      # Calculate the popup area within the given parent area
+      #
+      # The size is clamped to the parent size. A fixed +x+ or +y+ is used as is and
+      # is not clamped to the parent area.
+      #
+      # @param parent_area [Rect] area the popup is sized and centered against
+      # @return [Rect] the popup's outer area, including the block's borders
+      def popup_area(parent_area)
+        w = @fixed_width || (parent_area.width * @width_percent / 100)
+        h = @fixed_height || (parent_area.height * @height_percent / 100)
+        w = [w, parent_area.width].min
+        h = [h, parent_area.height].min
+
+        px = @fixed_x || (parent_area.x + (parent_area.width - w) / 2)
+        py = @fixed_y || (parent_area.y + (parent_area.height - h) / 2)
+
+        Rect.new(x: px, y: py, width: w, height: h)
+      end
+
+      # Get the inner area (inside the popup's block)
+      #
+      # @param parent_area [Rect] area the popup is sized and centered against
+      # @return [Rect] the area inside the block's borders and padding, for popup content
+      def inner(parent_area)
+        @block.inner(popup_area(parent_area))
+      end
+
+      # Draw the shadow (if enabled), clear the popup area with +style+, then draw
+      # the block.
+      #
+      # +area+ is the parent area; the popup is placed within it by {#popup_area}.
+      #
+      # @param area [Rect] the parent area to place the popup in
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty?
+
+        pa = popup_area(area)
+        return if pa.empty?
+
+        # Draw shadow first (offset by 1,1)
+        if @shadow
+          render_shadow(pa, buf)
+        end
+
+        # Clear the popup area with background style
+        clear_area(pa, buf)
+
+        # Draw the block (border + title)
+        @block.render(pa, buf)
+      end
+
+      private
+
+      def clear_area(area, buf)
+        (area.y...area.bottom).each do |y|
+          (area.x...area.right).each do |x|
+            cell = buf[x, y]
+            cell&.set(" ", @style)
+          end
+        end
+      end
+
+      def render_shadow(popup_area, buf)
+        # Right shadow (1 column)
+        shadow_x = popup_area.right
+        (popup_area.y + 1...popup_area.bottom + 1).each do |y|
+          cell = buf[shadow_x, y]
+          cell&.set(" ", @shadow_style) if cell
+        end
+
+        # Bottom shadow (full width + 1)
+        shadow_y = popup_area.bottom
+        (popup_area.x + 1..popup_area.right).each do |x|
+          cell = buf[x, shadow_y]
+          cell&.set(" ", @shadow_style) if cell
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/widgets/scrollbar.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # Scrollbar renders a vertical or horizontal scroll indicator.
+    #
+    # @example Vertical scrollbar in the rightmost column
+    #   bar = RubyTUI::Widgets::Scrollbar.new(content_length: 100, position: offset, viewport_length: 20)
+    #   frame.render_widget(bar, Rect.new(area.right - 1, area.y, 1, area.height))
+    class Scrollbar
+      include Widget
+
+      # Vertical orientation, drawn in the first column of the area.
+      VERTICAL   = :vertical
+      # Horizontal orientation, drawn in the first row of the area.
+      HORIZONTAL = :horizontal
+
+      # Unicode characters for scrollbar parts
+
+      # Vertical track.
+      TRACK_V    = "\u2502"  # │
+      # Vertical thumb.
+      THUMB_V    = "\u2588"  # █
+      # Horizontal track.
+      TRACK_H    = "\u2500"  # ─
+      # Horizontal thumb.
+      THUMB_H    = "\u2588"  # █
+      # Up arrow.
+      ARROW_UP   = "\u25B2"  # ▲
+      # Down arrow.
+      ARROW_DOWN = "\u25BC"  # ▼
+      # Left arrow.
+      ARROW_LEFT = "\u25C0"  # ◀
+      # Right arrow.
+      ARROW_RIGHT = "\u25B6" # ▶
+
+      # @param content_length [Integer] total content length, clamped to >= 1
+      # @param position [Integer] scroll offset into the content, clamped to
+      #   <tt>0..(content_length - viewport_length)</tt> when drawing (default: 0)
+      # @param viewport_length [Integer, nil] visible length of the content
+      #   (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 show_arrows [Boolean] draw an arrow at each end (default: true)
+      def initialize(
+        content_length:,
+        position: 0,
+        viewport_length: nil,
+        orientation: VERTICAL,
+        style: Style::DEFAULT,
+        thumb_style: nil,
+        track_style: nil,
+        show_arrows: true
+      )
+        @content_length = [content_length, 1].max
+        @position = position
+        @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)
+        @show_arrows = show_arrows
+      end
+
+      # Draw the track, thumb and optional arrows along the first column (vertical)
+      # or first row (horizontal) of the area.
+      #
+      # The thumb fills the whole track when the content fits in the viewport.
+      # Nothing is drawn if no track cells remain after the arrows.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty?
+
+        if @orientation == VERTICAL
+          render_vertical(area, buf)
+        else
+          render_horizontal(area, buf)
+        end
+      end
+
+      private
+
+      def render_vertical(area, buf)
+        track_length = area.height
+        viewport = @viewport_length || track_length
+        arrow_offset = @show_arrows ? 1 : 0
+        usable = track_length - (arrow_offset * 2)
+
+        return if usable <= 0
+
+        # Calculate thumb size and position
+        thumb_size = calculate_thumb_size(usable, viewport)
+        thumb_pos = calculate_thumb_position(usable, thumb_size, viewport)
+
+        x = area.x
+
+        # Top arrow
+        if @show_arrows
+          buf[x, area.y]&.set(ARROW_UP, @track_style)
+        end
+
+        # Track and thumb
+        usable.times do |i|
+          y = area.y + arrow_offset + i
+          if i >= thumb_pos && i < thumb_pos + thumb_size
+            buf[x, y]&.set(THUMB_V, @thumb_style)
+          else
+            buf[x, y]&.set(TRACK_V, @track_style)
+          end
+        end
+
+        # Bottom arrow
+        if @show_arrows
+          buf[x, area.bottom - 1]&.set(ARROW_DOWN, @track_style)
+        end
+      end
+
+      def render_horizontal(area, buf)
+        track_length = area.width
+        viewport = @viewport_length || track_length
+        arrow_offset = @show_arrows ? 1 : 0
+        usable = track_length - (arrow_offset * 2)
+
+        return if usable <= 0
+
+        thumb_size = calculate_thumb_size(usable, viewport)
+        thumb_pos = calculate_thumb_position(usable, thumb_size, viewport)
+
+        y = area.y
+
+        # Left arrow
+        if @show_arrows
+          buf[area.x, y]&.set(ARROW_LEFT, @track_style)
+        end
+
+        # Track and thumb
+        usable.times do |i|
+          x = area.x + arrow_offset + i
+          if i >= thumb_pos && i < thumb_pos + thumb_size
+            buf[x, y]&.set(THUMB_H, @thumb_style)
+          else
+            buf[x, y]&.set(TRACK_H, @track_style)
+          end
+        end
+
+        # Right arrow
+        if @show_arrows
+          buf[area.right - 1, y]&.set(ARROW_RIGHT, @track_style)
+        end
+      end
+
+      def calculate_thumb_size(track, viewport)
+        return track if @content_length <= viewport
+
+        size = (track.to_f * viewport / @content_length).round
+        size.clamp(1, track)
+      end
+
+      def calculate_thumb_position(track, thumb_size, viewport)
+        return 0 if @content_length <= viewport
+
+        max_scroll = @content_length - viewport
+        pos = @position.clamp(0, max_scroll)
+        available = track - thumb_size
+        (available.to_f * pos / max_scroll).round.clamp(0, available)
+      end
+    end
+  end
+end

data/lib/rubytui/widgets/sparkline.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # Sparkline renders a mini bar chart from an array of numeric data.
+    # Each data point maps to a single column using Unicode block characters.
+    #
+    # @example
+    #   spark = RubyTUI::Widgets::Sparkline.new(data: [1, 4, 2, 8, 5], max: 10)
+    #   frame.render_widget(spark, area)
+    class Sparkline
+      include Widget
+
+      # Bar characters from empty to full (8 levels)
+      BARS = [" ", "\u2581", "\u2582", "\u2583", "\u2584", "\u2585", "\u2586", "\u2587", "\u2588"].freeze
+
+      # @param data [Array<Numeric>] values; the most recent values that fit the
+      #   width are drawn, right-aligned (default: [])
+      # @param style [Style] style of the empty cells above the bars (default: {Style::DEFAULT})
+      # @param bar_style [Style, nil] bar style (default: green foreground)
+      # @param max [Numeric, nil] value drawn at full height; larger values are clamped
+      #   to full height (default: nil, the largest visible value, or 1 if that is 0)
+      # @param block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        data: [],
+        style: Style::DEFAULT,
+        bar_style: nil,
+        max: nil,
+        block: nil
+      )
+        @data = data
+        @style = style
+        @bar_style = bar_style || Style.new.fg(Color::GREEN)
+        @max = max
+        @block = block
+      end
+
+      # Draw one column per value, bottom-up, with eighth-cell height precision.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @return [void]
+      def render(area, buf)
+        return if area.empty?
+
+        render_area = area
+        if @block
+          @block.render(area, buf)
+          render_area = @block.inner(area)
+        end
+
+        return if render_area.empty? || @data.empty?
+
+        width = render_area.width
+        height = render_area.height
+
+        # Use the most recent data points that fit
+        visible_data = @data.last(width)
+        max_val = @max || visible_data.max || 1
+        max_val = 1 if max_val == 0
+
+        visible_data.each_with_index do |val, i|
+          x = render_area.x + (width - visible_data.length) + i
+          next if x < render_area.x
+
+          # Scale value to available height * 8 (for sub-character precision)
+          scaled = ((val.to_f / max_val) * height * 8).round.clamp(0, height * 8)
+
+          # Render from bottom to top
+          (0...height).each do |row|
+            y = render_area.bottom - 1 - row
+            row_value = scaled - (row * 8)
+
+            if row_value >= 8
+              buf[x, y]&.set(BARS[8], @bar_style)
+            elsif row_value > 0
+              buf[x, y]&.set(BARS[row_value], @bar_style)
+            else
+              buf[x, y]&.set(" ", @style)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/widgets/table.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # @see Table
+    class TableState
+      attr_accessor :selected, :offset
+
+      # @param selected [Integer] initial selected row index (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.
+      #
+      # 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
+      end
+
+      # Select the previous row, wrapping from the first row to the last.
+      #
+      # 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
+      end
+    end
+
+    # Table renders tabular data with headers, rows, and configurable column widths.
+    #
+    # @example
+    #   state = RubyTUI::Widgets::TableState.new
+    #   table = RubyTUI::Widgets::Table.new(header: ["Name", "Size"],
+    #                                       rows: [["a.txt", "1K"], ["b.txt", "2K"]],
+    #                                       widths: [20, 8])
+    #   frame.render_stateful_widget(table, area, state)
+    #
+    # @see TableState
+    class Table
+      include StatefulWidget
+
+      # @param header [Array<String, Span, #to_s>, nil] header cells, each converted to
+      #   a {Span}; when set, a header row and a separator line are drawn (default: nil)
+      # @param rows [Array<Array<String, Span, #to_s>>] data rows (default: [])
+      # @param widths [Array<Integer>] column widths in cells; when empty, the available
+      #   width is split equally across the columns of +header+, or of the first row
+      #   (default: [])
+      # @param style [Style] base row style (default: {Style::DEFAULT})
+      # @param header_style [Style, nil] style of the header row and separator
+      #   (default: bold cyan foreground)
+      # @param highlight_style [Style, nil] patched onto +style+ for the selected row
+      #   (default: bold yellow foreground)
+      # @param highlight_symbol [String] prefix of the selected row; other rows and the
+      #   header are prefixed with spaces of the same width (default: "> ")
+      # @param column_spacing [Integer] blank cells between columns (default: 1)
+      # @param block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        header: nil,
+        rows: [],
+        widths: [],
+        style: Style::DEFAULT,
+        header_style: nil,
+        highlight_style: nil,
+        highlight_symbol: "> ",
+        column_spacing: 1,
+        block: nil
+      )
+        @header = header&.map { |h| normalize_cell(h) }
+        @rows = rows.map { |row| row.map { |c| normalize_cell(c) } }
+        @widths = widths
+        @style = style
+        @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)
+        @normal_symbol = " " * @highlight_symbol_width
+        @column_spacing = column_spacing
+        @block = block
+      end
+
+      # 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.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @param state [TableState] selection and scroll state, updated in place
+      # @return [void]
+      def render(area, buf, state)
+        return if area.empty?
+
+        render_area = area
+        if @block
+          @block.render(area, buf)
+          render_area = @block.inner(area)
+        end
+
+        return if render_area.empty?
+
+        # Resolve column widths
+        col_widths = resolve_widths(render_area.width - @highlight_symbol_width)
+        return if col_widths.empty?
+
+        y = render_area.y
+
+        # Render header
+        if @header
+          render_row(@header, col_widths, render_area.x, y, buf, @header_style, @normal_symbol)
+          y += 1
+
+          # Header separator
+          if y < render_area.bottom
+            x = render_area.x + @highlight_symbol_width
+            col_widths.each_with_index do |w, i|
+              buf.set_string(x, y, "\u2500" * w, @header_style)
+              x += w + (i < col_widths.length - 1 ? @column_spacing : 0)
+            end
+            y += 1
+          end
+        end
+
+        # Available height for rows
+        visible_height = render_area.bottom - y
+        return if visible_height <= 0
+
+        # 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
+        end
+        state.offset = state.offset.clamp(0, [total - visible_height, 0].max)
+
+        # Render visible rows
+        visible_rows = @rows[state.offset, visible_height] || []
+        visible_rows.each_with_index do |row, i|
+          break if y >= render_area.bottom
+
+          actual_index = state.offset + i
+          is_selected = actual_index == state.selected
+          row_style = is_selected ? @style.patch(@highlight_style) : @style
+          symbol = is_selected ? @highlight_symbol : @normal_symbol
+
+          render_row(row, col_widths, render_area.x, y, buf, row_style, symbol)
+
+          # Fill remaining width for highlight
+          if is_selected
+            row_end = render_area.x + @highlight_symbol_width
+            col_widths.each_with_index do |w, ci|
+              row_end += w + (ci < col_widths.length - 1 ? @column_spacing : 0)
+            end
+            if row_end < render_area.right
+              buf.set_string(row_end, y, " " * (render_area.right - row_end), row_style)
+            end
+          end
+
+          y += 1
+        end
+      end
+
+      private
+
+      def normalize_cell(cell)
+        case cell
+        when Span   then cell
+        when String then Span.new(cell)
+        else Span.new(cell.to_s)
+        end
+      end
+
+      def resolve_widths(available)
+        return @widths unless @widths.empty?
+
+        # Auto-calculate: equal widths based on column count
+        ncols = (@header&.length || @rows.first&.length || 0)
+        return [] if ncols == 0
+
+        total_spacing = @column_spacing * [ncols - 1, 0].max
+        usable = [available - total_spacing, 0].max
+        base = usable / ncols
+        remainder = usable % ncols
+
+        Array.new(ncols) { |i| i < remainder ? base + 1 : base }
+      end
+
+      def render_row(cells, col_widths, area_x, y, buf, row_style, symbol)
+        x = area_x
+        buf.set_string(x, y, symbol, row_style)
+        x += @highlight_symbol_width
+
+        cells.each_with_index do |cell, i|
+          break if i >= col_widths.length
+
+          w = col_widths[i]
+          text = Buffer.truncate_to_width(cell.content, w)
+          text_width = Buffer.string_width(text)
+          effective_style = row_style.patch(cell.style)
+          buf.set_string(x, y, text, effective_style)
+
+          # Pad remaining column width
+          pad = w - text_width
+          buf.set_string(x + text_width, y, " " * pad, row_style) if pad > 0
+
+          x += w
+          # Fill column spacing gap with row style
+          if i < col_widths.length - 1 && @column_spacing > 0
+            buf.set_string(x, y, " " * @column_spacing, row_style)
+            x += @column_spacing
+          end
+        end
+      end
+    end
+  end
+end