rubytui 1.2.3

data/lib/rubytui/widgets/input_field.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # InputState holds the mutable state for the InputField widget.
+    #
+    # +cursor+ is a character index into +text+. +scroll_offset+ is the index of
+    # the first visible character and is updated by {InputField#render}.
+    #
+    # @see InputField
+    class InputState
+      attr_accessor :text, :cursor, :scroll_offset
+
+      # @param text [String] initial text; a mutable copy is stored (default: "")
+      # @param cursor [Integer] initial cursor character index, not clamped to the
+      #   text length (default: 0)
+      def initialize(text: "", cursor: 0)
+        @text = String.new(text)  # ensure mutable copy
+        @cursor = cursor
+        @scroll_offset = 0
+      end
+
+      # Insert a character at the cursor position
+      #
+      # @param char [String] character (or string) to insert; the cursor advances by its length
+      # @return [void]
+      def insert(char)
+        @text.insert(@cursor, char)
+        @cursor += char.length
+      end
+
+      # Delete character before cursor (backspace)
+      #
+      # Does nothing when the cursor is at the start.
+      #
+      # @return [void]
+      def backspace
+        return if @cursor == 0
+
+        @text.slice!(@cursor - 1)
+        @cursor -= 1
+      end
+
+      # Delete character at cursor (delete key)
+      #
+      # Does nothing when the cursor is at the end.
+      #
+      # @return [void]
+      def delete
+        return if @cursor >= @text.length
+
+        @text.slice!(@cursor)
+      end
+
+      # Move cursor left
+      #
+      # @return [void]
+      def move_left
+        @cursor = [@cursor - 1, 0].max
+      end
+
+      # Move cursor right
+      #
+      # @return [void]
+      def move_right
+        @cursor = [@cursor + 1, @text.length].min
+      end
+
+      # Move cursor to start
+      #
+      # @return [void]
+      def home
+        @cursor = 0
+      end
+
+      # Move cursor to end
+      #
+      # @return [void]
+      def end_pos
+        @cursor = @text.length
+      end
+
+      # Delete from cursor to end of line
+      #
+      # The cursor does not move.
+      #
+      # @return [void]
+      def kill_to_end
+        @text.slice!(@cursor..)
+      end
+
+      # Delete from start to cursor
+      #
+      # The cursor moves to the start.
+      #
+      # @return [void]
+      def kill_to_start
+        @text.slice!(0...@cursor)
+        @cursor = 0
+      end
+
+      # 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.
+      #
+      # @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
+
+        @text.slice!(pos...@cursor)
+        @cursor = pos
+      end
+
+      # Handle a key event, returns true if the event was consumed
+      #
+      # Character keys without Ctrl insert <tt>event.char</tt>. Backspace, Delete,
+      # Left, Right, Home and End edit or move. Ctrl-A / Ctrl-E move to start / end,
+      # Ctrl-K / Ctrl-U delete to end / start, Ctrl-W deletes the previous word.
+      # Other Ctrl combinations, other keys and non-{KeyEvent} events are not consumed.
+      #
+      # @param event [Event] the input event
+      # @return [Boolean] true if the event was consumed
+      def handle_key(event)
+        return false unless event.is_a?(KeyEvent)
+
+        case event.code
+        when Input::Key::CHAR
+          if event.ctrl?
+            case event.char
+            when "a" then home; true
+            when "e" then end_pos; true
+            when "k" then kill_to_end; true
+            when "u" then kill_to_start; true
+            when "w" then delete_word_back; true
+            else false
+            end
+          else
+            insert(event.char) if event.char
+            true
+          end
+        when Input::Key::BACKSPACE then backspace; true
+        when Input::Key::DELETE    then delete; true
+        when Input::Key::LEFT      then move_left; true
+        when Input::Key::RIGHT     then move_right; true
+        when Input::Key::HOME      then home; true
+        when Input::Key::END_KEY   then end_pos; true
+        else
+          false
+        end
+      end
+    end
+
+    # InputField renders a single-line text input with cursor.
+    #
+    # @example
+    #   state = RubyTUI::Widgets::InputState.new
+    #   state.handle_key(event)  # in the event loop
+    #   field = RubyTUI::Widgets::InputField.new(placeholder: "Type here...")
+    #   frame.render_stateful_widget(field, area, state)
+    #
+    # @see InputState
+    class InputField
+      include StatefulWidget
+
+      # @param style [Style] text style (default: {Style::DEFAULT})
+      # @param cursor_style [Style, nil] style of the cell under the cursor
+      #   (default: reversed video)
+      # @param placeholder [String] text shown while the input is empty (default: "")
+      # @param placeholder_style [Style, nil] placeholder style (default: bright black foreground)
+      # @param block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        style: Style::DEFAULT,
+        cursor_style: nil,
+        placeholder: "",
+        placeholder_style: nil,
+        block: nil
+      )
+        @style = style
+        @cursor_style = cursor_style || Style.new.reversed
+        @placeholder = placeholder
+        @placeholder_style = placeholder_style || Style.new.fg(Color::BRIGHT_BLACK)
+        @block = block
+      end
+
+      # Render the visible part of the text, or the placeholder, on the first row of
+      # 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.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @param state [InputState] text, cursor and scroll state
+      # @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?
+
+        width = render_area.width
+
+        # 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
+        end
+
+        if state.text.empty?
+          # Show placeholder
+          visible = @placeholder[0, 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] || ""
+          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
+        if cursor_screen_x >= render_area.x && cursor_screen_x < render_area.right
+          cell = buf[cursor_screen_x, render_area.y]
+          if cell
+            char = cell.symbol == " " && state.cursor >= state.text.length ? " " : cell.symbol
+            cell.set(char, @cursor_style)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/widgets/list.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+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.
+    #
+    # @see List
+    class ListState
+      attr_accessor :selected, :offset
+
+      # @param selected [Integer] initial selected 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 item, wrapping from the last item to the first.
+      #
+      # 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
+      end
+
+      # Select the previous item, wrapping from the first item to the last.
+      #
+      # 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
+      end
+
+      # Select the first item and reset the scroll offset to 0.
+      #
+      # @return [void]
+      def select_first
+        @selected = 0
+        @offset = 0
+      end
+
+      # Select the last item.
+      #
+      # The offset is not changed; {List#render} scrolls to keep the selection visible.
+      #
+      # @param total [Integer] number of items in the list
+      # @return [void]
+      def select_last(total)
+        @selected = [total - 1, 0].max
+      end
+    end
+
+    # List renders a scrollable, selectable list of items.
+    #
+    # @example
+    #   state = RubyTUI::Widgets::ListState.new
+    #   list = RubyTUI::Widgets::List.new(items: ["One", "Two", "Three"])
+    #   frame.render_stateful_widget(list, area, state)
+    #   state.select_next(list.items.length)  # e.g. on a Down key press
+    #
+    # @see ListState
+    class List
+      include StatefulWidget
+
+      attr_reader :items
+
+      # @param items [Array<String, Span, Line, #to_s>] list items, each converted to a
+      #   {Line} (default: [])
+      # @param style [Style] base style of every item (default: {Style::DEFAULT})
+      # @param highlight_style [Style, nil] patched onto +style+ for the selected item
+      #   (default: bold yellow foreground)
+      # @param highlight_symbol [String] prefix of the selected item; other items are
+      #   prefixed with spaces of the same width (default: "> ")
+      # @param block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        items: [],
+        style: Style::DEFAULT,
+        highlight_style: nil,
+        highlight_symbol: "> ",
+        block: nil
+      )
+        @items = items.map { |item| normalize_item(item) }
+        @style = style
+        @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
+        @block = block
+      end
+
+      # Render the visible items, one per row, marking the selected item with
+      # +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.
+      #
+      # @param area [Rect] the rectangular area to render into
+      # @param buf [Buffer] the buffer to write cells into
+      # @param state [ListState] 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? || @items.empty?
+
+        # Adjust scroll offset to keep selected item visible
+        visible_height = render_area.height
+        clamp_state(state, visible_height)
+
+        # Render visible items
+        visible_items = @items[state.offset, visible_height] || []
+        visible_items.each_with_index do |item, i|
+          y = render_area.y + i
+          actual_index = state.offset + i
+          is_selected = actual_index == state.selected
+
+          symbol = is_selected ? @highlight_symbol : @normal_symbol
+          item_style = is_selected ? @style.patch(@highlight_style) : @style
+
+          # Write selection symbol
+          x = render_area.x
+          buf.set_string(x, y, symbol, item_style)
+          x += @highlight_symbol_width
+
+          # Write item text
+          available = render_area.width - @highlight_symbol_width
+          item.spans.each do |span|
+            break if available <= 0
+
+            text = Buffer.truncate_to_width(span.content, available)
+            text_width = Buffer.string_width(text)
+            effective_style = item_style.patch(span.style)
+            buf.set_string(x, y, text, effective_style)
+            x += text_width
+            available -= text_width
+          end
+
+          # Fill remaining width with style (for highlight background)
+          if is_selected && x < render_area.right
+            remaining = render_area.right - x
+            buf.set_string(x, y, " " * remaining, item_style)
+          end
+        end
+      end
+
+      private
+
+      def normalize_item(item)
+        case item
+        when Line then item
+        when Span then Line.new([item])
+        when String then Line.from(item)
+        else Line.from(item.to_s)
+        end
+      end
+
+      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
+        end
+
+        state.offset = state.offset.clamp(0, [total - visible_height, 0].max)
+      end
+    end
+  end
+end

data/lib/rubytui/widgets/paragraph.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # Paragraph renders styled text with wrapping and alignment.
+    #
+    # @example
+    #   para = RubyTUI::Widgets::Paragraph.new(text: "Hello\nWorld", alignment: :center)
+    #   frame.render_widget(para, area)
+    class Paragraph
+      include Widget
+
+      # Wrap at whitespace; a single word wider than the area is not broken.
+      WRAP_WORD = :word
+      # Wrap at any character.
+      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 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
+      # @param block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        text: nil,
+        style: Style::DEFAULT,
+        alignment: :left,
+        wrap: WRAP_WORD,
+        block: nil  # optional Block to render inside
+      )
+        @text = normalize_text(text)
+        @style = style
+        @alignment = alignment
+        @wrap = wrap
+        @block = block
+      end
+
+      # 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.
+      #
+      # @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?
+
+        # Apply background style to entire area
+        buf.set_style(render_area, @style) if @style != Style::DEFAULT
+
+        # Wrap and render lines
+        wrapped = wrap_lines(render_area.width)
+
+        wrapped.each_with_index do |line, i|
+          break if i >= render_area.height
+
+          render_line(line, render_area, i, buf)
+        end
+      end
+
+      private
+
+      def normalize_text(text)
+        case text
+        when Text   then text
+        when String then Text.from(text)
+        when Line   then Text.new([text])
+        when nil    then Text.new([])
+        else Text.from(text.to_s)
+        end
+      end
+
+      # Wrap text lines to fit within the given width.
+      # Returns an Array of Lines.
+      def wrap_lines(max_width)
+        return @text.lines if @wrap == WRAP_NONE || max_width <= 0
+
+        result = []
+        @text.lines.each do |line|
+          if line.width <= max_width
+            result << line
+          elsif @wrap == WRAP_WORD
+            result.concat(word_wrap(line, max_width))
+          else
+            result.concat(char_wrap(line, max_width))
+          end
+        end
+        result
+      end
+
+      def word_wrap(line, max_width)
+        plain = line.to_s
+        # Use the first span's style for wrapped text (simplification for v0.1)
+        line_style = line.spans.first&.style || Style::DEFAULT
+
+        words = plain.split(/(\s+)/)
+        wrapped = []
+        current = String.new
+        current_width = 0
+
+        words.each do |word|
+          word_width = Buffer.string_width(word)
+          if current.empty?
+            current << word
+            current_width = word_width
+          elsif current_width + word_width <= max_width
+            current << word
+            current_width += word_width
+          else
+            wrapped << Line.from(current.rstrip, line_style) unless current.strip.empty?
+            current = word.lstrip
+            current_width = Buffer.string_width(current)
+          end
+        end
+
+        wrapped << Line.from(current.rstrip, line_style) unless current.strip.empty?
+        wrapped << Line.new if wrapped.empty?
+        wrapped
+      end
+
+      def char_wrap(line, max_width)
+        plain = line.to_s
+        line_style = line.spans.first&.style || Style::DEFAULT
+
+        wrapped = []
+        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?
+            current = String.new
+            current_width = 0
+          end
+          current << ch
+          current_width += ch_width
+        end
+        wrapped << Line.from(current, line_style) unless current.empty?
+        wrapped << Line.new if wrapped.empty?
+        wrapped
+      end
+
+      def render_line(line, area, row, buf)
+        line_width = line.width
+        x_offset = case @alignment
+                   when :center then [(area.width - line_width) / 2, 0].max
+                   when :right  then [area.width - line_width, 0].max
+                   else 0
+                   end
+
+        x = area.x + x_offset
+        y = area.y + row
+
+        line.spans.each do |span|
+          effective_style = @style.patch(span.style)
+          count = buf.set_string(x, y, span.content, effective_style)
+          x += count
+        end
+      end
+    end
+  end
+end