rubytui 1.2.3

data/lib/rubytui/widgets/tabs.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  module Widgets
+    # Tabs renders a horizontal tab bar with selectable tabs.
+    #
+    # @example
+    #   tabs = RubyTUI::Widgets::Tabs.new(titles: ["Home", "Logs", "Help"], selected: 1)
+    #   frame.render_widget(tabs, area)
+    class Tabs
+      include Widget
+
+      # @param titles [Array<#to_s>] tab titles (default: [])
+      # @param selected [Integer] index of the active tab (default: 0)
+      # @param style [Style] base style, patched with +active_style+ or +inactive_style+
+      #   (default: {Style::DEFAULT})
+      # @param active_style [Style, nil] style of the active tab (default: bold yellow foreground)
+      # @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 block [Widgets::Block, nil] optional wrapping block
+      def initialize(
+        titles: [],
+        selected: 0,
+        style: Style::DEFAULT,
+        active_style: nil,
+        inactive_style: nil,
+        divider: " \u2502 ",
+        highlight_style: nil,
+        block: nil
+      )
+        @titles = titles
+        @selected = selected
+        @style = style
+        @active_style = active_style || Style.new.fg(Color::YELLOW).bold
+        @inactive_style = inactive_style || Style.new.fg(Color::BRIGHT_BLACK)
+        @divider = divider
+        @highlight_style = highlight_style
+        @block = block
+      end
+
+      # Draw the titles left to right on the first row of the area, separated by
+      # +divider+ and truncated at the right edge.
+      #
+      # @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? || @titles.empty?
+
+        x = render_area.x
+        y = render_area.y
+
+        @titles.each_with_index do |title, i|
+          break if x >= render_area.right
+
+          is_active = i == @selected
+          tab_style = is_active ? @style.patch(@active_style) : @style.patch(@inactive_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)
+
+          buf.set_string(x, y, display, tab_style)
+          x += display_width
+
+          # 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)
+            buf.set_string(x, y, divider_text, @style.patch(@inactive_style))
+            x += divider_width
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubytui.rb

@@ -0,0 +1,389 @@
+# frozen_string_literal: true
+
+# Core primitives
+require_relative "rubytui/version"
+require_relative "rubytui/errors"
+require_relative "rubytui/modifier"
+require_relative "rubytui/color"
+require_relative "rubytui/color_mode"
+require_relative "rubytui/rect"
+require_relative "rubytui/style"
+require_relative "rubytui/cell"
+require_relative "rubytui/unicode"
+require_relative "rubytui/buffer"
+require_relative "rubytui/symbols"
+
+# Layout
+require_relative "rubytui/layout/flex"
+require_relative "rubytui/layout/constraint"
+require_relative "rubytui/layout/layout"
+
+# Widget protocol
+require_relative "rubytui/widget"
+require_relative "rubytui/stateful_widget"
+
+# Backend
+require_relative "rubytui/backend"
+require_relative "rubytui/backends/test_backend"
+require_relative "rubytui/backends/ansi_backend"
+
+# Rendering pipeline
+require_relative "rubytui/frame"
+require_relative "rubytui/terminal"
+
+# Text primitives
+require_relative "rubytui/text/span"
+require_relative "rubytui/text/line"
+require_relative "rubytui/text/text"
+
+# Widgets
+require_relative "rubytui/widgets/block"
+require_relative "rubytui/widgets/paragraph"
+require_relative "rubytui/widgets/list"
+require_relative "rubytui/widgets/table"
+require_relative "rubytui/widgets/gauge"
+require_relative "rubytui/widgets/sparkline"
+require_relative "rubytui/widgets/scrollbar"
+require_relative "rubytui/widgets/tabs"
+require_relative "rubytui/widgets/canvas"
+require_relative "rubytui/widgets/popup"
+require_relative "rubytui/widgets/input_field"
+require_relative "rubytui/widgets/chart"
+require_relative "rubytui/widgets/image"
+require_relative "rubytui/widgets/async_image"
+
+# Input
+require_relative "rubytui/input/key"
+require_relative "rubytui/event"
+require_relative "rubytui/input/parser"
+require_relative "rubytui/input/reader"
+
+# App framework
+require_relative "rubytui/app"
+
+# A pure Ruby terminal user interface library.
+#
+# RubyTUI provides immediate-mode rendering with double buffering,
+# constraint-based layouts, and a duck-typed widget protocol.
+#
+# @example Interactive TUI application
+#   RubyTUI.run do |terminal, reader|
+#     loop do
+#       terminal.draw do |frame|
+#         frame.buffer.set_string(0, 0, "Hello!", Style.new.fg(Color::GREEN))
+#       end
+#       event = reader.poll(timeout_ms: 50)
+#       break if event.is_a?(RubyTUI::KeyEvent) && event.char == 'q'
+#     end
+#   end
+#
+# @example One-shot styled output (no event loop)
+#   RubyTUI.render_once(width: 80) do |frame|
+#     block = RubyTUI::Widgets::Block.new(title: " Info ", borders: :all)
+#     frame.render_widget(block, frame.area)
+#   end
+#
+# @example Quick table print
+#   RubyTUI.print_table(
+#     header: ["Name", "Value"],
+#     rows: [["Alice", "100"], ["Bob", "200"]],
+#     title: " Data "
+#   )
+module RubyTUI
+  # Convenience alias for {Layout::Constraint}
+  Constraint = Layout::Constraint
+
+  class << self
+    # Initialize a terminal with ANSI backend.
+    #
+    # Enables raw mode, hides the cursor, and optionally enters alternate screen.
+    # Use {.restore} to undo these changes, or prefer {.run} for automatic cleanup.
+    #
+    # @param output [IO] output stream (default: $stdout)
+    # @param input [IO] input stream (default: $stdin)
+    # @param mouse [Boolean] enable mouse event reporting (default: false)
+    # @param alternate_screen [Boolean] enter alternate screen buffer (default: true)
+    # @return [Array(Terminal, Input::Reader)] terminal and reader pair
+    # @see .run
+    # @see .restore
+    def init(output: $stdout, input: $stdin, mouse: false, alternate_screen: true)
+      backend = AnsiBackend.new(output: output, input: input)
+      terminal = Terminal.new(backend: backend)
+      reader = Input::Reader.new(input: input)
+
+      backend.enable_raw_mode
+      backend.hide_cursor
+      terminal.enter_alternate_screen if alternate_screen
+      backend.enable_mouse if mouse
+      backend.flush
+
+      [terminal, reader]
+    end
+
+    # Restore terminal to normal state.
+    #
+    # Disables mouse, shows cursor, leaves alternate screen, and disables raw mode.
+    #
+    # @param terminal [Terminal] the terminal to restore
+    # @param alternate_screen [Boolean] whether alternate screen was used (must match {.init})
+    #   (default: true)
+    # @return [void]
+    def restore(terminal, alternate_screen: true)
+      terminal.backend.disable_mouse
+      terminal.backend.show_cursor
+      terminal.leave_alternate_screen if alternate_screen
+      terminal.backend.disable_raw_mode
+      terminal.backend.flush
+    end
+
+    # Run a TUI application with automatic setup and teardown.
+    #
+    # Sets up the terminal (raw mode, hidden cursor, alternate screen) and
+    # yields a terminal and reader. Restores the terminal when the block exits.
+    #
+    # @param output [IO] output stream (default: $stdout)
+    # @param input [IO] input stream (default: $stdin)
+    # @param mouse [Boolean] enable mouse event reporting (default: false)
+    # @param alternate_screen [Boolean] use alternate screen buffer (default: true).
+    #   Set to +false+ to keep output in terminal scrollback after exit.
+    # @yield [terminal, reader] the initialized terminal and input reader
+    # @yieldparam terminal [Terminal]
+    # @yieldparam reader [Input::Reader]
+    # @return [void]
+    #
+    # @example Basic interactive app
+    #   RubyTUI.run do |terminal, reader|
+    #     loop do
+    #       terminal.draw { |frame| frame.buffer.set_string(0, 0, "Hi!") }
+    #       event = reader.poll(timeout_ms: 50)
+    #       break if event.is_a?(RubyTUI::KeyEvent) && event.char == 'q'
+    #     end
+    #   end
+    #
+    # @example Non-alternate-screen mode (output persists after exit)
+    #   RubyTUI.run(alternate_screen: false) do |terminal, reader|
+    #     terminal.draw { |frame| frame.buffer.set_string(0, 0, "Stays visible") }
+    #   end
+    def run(output: $stdout, input: $stdin, mouse: false, alternate_screen: true)
+      terminal, reader = init(output: output, input: input, mouse: mouse,
+                              alternate_screen: alternate_screen)
+      yield terminal, reader
+    ensure
+      restore(terminal, alternate_screen: alternate_screen) if terminal
+    end
+
+    # Render widgets once and print to stdout.
+    #
+    # No event loop, no alternate screen, no raw mode. Output stays in
+    # terminal scrollback. Ideal for CLI tools that want styled output
+    # using the widget/layout system without a full TUI.
+    #
+    # @param width [Integer, nil] output width in columns (default: auto-detect)
+    # @param height [Integer, nil] output height in rows (default: auto-detect)
+    # @param output [IO] output stream (default: $stdout)
+    # @yield [frame] a Frame to render widgets into
+    # @yieldparam frame [Frame]
+    # @return [Frame] the rendered frame
+    #
+    # @example Render a block widget
+    #   RubyTUI.render_once(width: 60, height: 10) do |frame|
+    #     block = RubyTUI::Widgets::Block.new(title: " Info ", borders: :all)
+    #     frame.render_widget(block, frame.area)
+    #   end
+    def render_once(width: nil, height: nil, output: $stdout)
+      w = width || terminal_width(output)
+      h = height || terminal_height(output)
+      area = Rect.new(0, 0, w, h)
+      buf = Buffer.new(area)
+      frame = Frame.new(buf, area)
+      yield frame
+      output.write(buf.to_ansi)
+      output.write("\n")
+      frame
+    end
+
+    # Print a styled table to stdout. No event loop needed.
+    #
+    # Renders a {Widgets::Table} with optional header, borders, and title,
+    # then prints the ANSI output directly. Auto-calculates the required height.
+    #
+    # @param header [Array<String>, nil] column header labels
+    # @param rows [Array<Array<String>>] table data rows
+    # @param widths [Array<Integer>] column widths (auto-calculated if empty)
+    # @param title [String, nil] box title rendered on the top border
+    # @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})
+    # @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 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)
+    # @return [void]
+    #
+    # @example
+    #   RubyTUI.print_table(
+    #     header: ["Name", "Price", "Change"],
+    #     rows: [["AAPL", "150.00", "+2.3%"], ["GOOG", "2800", "-1.1%"]],
+    #     border: :rounded,
+    #     title: " Stocks "
+    #   )
+    def print_table(header: nil, rows: [], widths: [], title: nil,
+                    border: :rounded, border_style: Style::DEFAULT,
+                    header_style: nil, style: Style::DEFAULT,
+                    highlight_symbol: "  ", column_spacing: 1,
+                    width: nil, output: $stdout)
+      border_set = resolve_border_set(border)
+      block_widget = title ? Widgets::Block.new(
+        title: title, borders: :all, border_set: border_set,
+        border_style: border_style
+      ) : nil
+
+      table = Widgets::Table.new(
+        header: header, rows: rows, widths: widths, style: style,
+        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
+
+      # Calculate height: header(1) + separator(1) + rows + border(2)
+      h = rows.length + (header ? 2 : 0) + (title ? 2 : 0)
+      w = width || terminal_width(output)
+
+      area = Rect.new(0, 0, w, h)
+      buf = Buffer.new(area)
+      table.render(area, buf, state)
+      output.write(buf.to_ansi)
+      output.write("\n")
+    end
+
+    # Print a styled box with text content to stdout. No event loop needed.
+    #
+    # Renders a {Widgets::Paragraph} inside a {Widgets::Block} with borders,
+    # 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 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})
+    # @param style [Style] background style for the box area (default: {Style::DEFAULT})
+    # @param text_style [Style] style for the text content (default: {Style::DEFAULT})
+    # @param alignment [Symbol] text alignment — +:left+, +:center+, +:right+ (default: +:left+)
+    # @param width [Integer, nil] total width in columns (default: auto-detect)
+    # @param output [IO] output stream (default: $stdout)
+    # @return [void]
+    #
+    # @example
+    #   RubyTUI.print_box(
+    #     title: " Summary ",
+    #     content: "Total: $1,234\nProfit: +5.2%",
+    #     border_style: Style.new.fg(Color::YELLOW)
+    #   )
+    def print_box(title: nil, content: "", border: :rounded,
+                  border_style: Style::DEFAULT, style: Style::DEFAULT,
+                  text_style: Style::DEFAULT, alignment: :left,
+                  width: nil, output: $stdout)
+      border_set = resolve_border_set(border)
+      block_widget = Widgets::Block.new(
+        title: title, borders: :all, border_set: border_set,
+        border_style: border_style, style: style
+      )
+
+      text = case content
+             when String then Text.from(content)
+             when Array  then Text.from(content.join("\n"))
+             else content
+             end
+
+      para = Widgets::Paragraph.new(
+        text: text, style: text_style, alignment: alignment,
+        block: block_widget
+      )
+
+      w = width || terminal_width(output)
+      line_count = case content
+                   when String then content.count("\n") + 1
+                   when Array  then content.length
+                   else 1
+                   end
+      h = line_count + 2  # +2 for borders
+
+      area = Rect.new(0, 0, w, h)
+      buf = Buffer.new(area)
+      para.render(area, buf)
+      output.write(buf.to_ansi)
+      output.write("\n")
+    end
+
+    # Print a styled gauge/progress bar to stdout. No event loop needed.
+    #
+    # Renders a {Widgets::Gauge} with optional title block, then prints
+    # the ANSI output directly.
+    #
+    # @param ratio [Float] progress value between 0.0 and 1.0 (default: 0.0)
+    # @param label [String, nil] custom label (default: percentage)
+    # @param width [Integer, nil] total width in columns (default: auto-detect)
+    # @param gauge_style [Style, nil] style for the filled portion (default: green)
+    # @param title [String, nil] box title rendered on the top border
+    # @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})
+    # @param output [IO] output stream (default: $stdout)
+    # @return [void]
+    #
+    # @example
+    #   RubyTUI.print_gauge(ratio: 0.75, title: " Progress ", width: 40)
+    def print_gauge(ratio: 0.0, label: nil, width: nil,
+                    gauge_style: nil, title: nil,
+                    border: :rounded, border_style: Style::DEFAULT,
+                    output: $stdout)
+      block_widget = title ? Widgets::Block.new(
+        title: title, borders: :all,
+        border_set: resolve_border_set(border),
+        border_style: border_style
+      ) : nil
+
+      gauge = Widgets::Gauge.new(
+        ratio: ratio, label: label, gauge_style: gauge_style,
+        block: block_widget
+      )
+
+      w = width || terminal_width(output)
+      h = title ? 3 : 1
+
+      area = Rect.new(0, 0, w, h)
+      buf = Buffer.new(area)
+      gauge.render(area, buf)
+      output.write(buf.to_ansi)
+      output.write("\n")
+    end
+
+    private
+
+    def terminal_width(output)
+      output.respond_to?(:winsize) ? output.winsize[1] : 80
+    rescue Errno::ENOTTY, Errno::ENODEV, NoMethodError
+      80
+    end
+
+    def terminal_height(output)
+      output.respond_to?(:winsize) ? output.winsize[0] : 24
+    rescue Errno::ENOTTY, Errno::ENODEV, NoMethodError
+      24
+    end
+
+    def resolve_border_set(border)
+      case border
+      when :rounded then Symbols::ROUNDED
+      when :double  then Symbols::DOUBLE
+      when :thick   then Symbols::THICK
+      when :light   then Symbols::LIGHT
+      when :plain   then Symbols::PLAIN
+      else
+        border.is_a?(Symbols::BorderSet) ? border : Symbols::ROUNDED
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: rubytui
+version: !ruby/object:Gem::Version
+  version: 1.2.3
+platform: ruby
+authors:
+- CoCL
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A pure Ruby, 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.
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/rubytui.rb
+- lib/rubytui/app.rb
+- lib/rubytui/backend.rb
+- lib/rubytui/backends/ansi_backend.rb
+- lib/rubytui/backends/test_backend.rb
+- lib/rubytui/buffer.rb
+- lib/rubytui/cell.rb
+- lib/rubytui/color.rb
+- lib/rubytui/color_mode.rb
+- lib/rubytui/errors.rb
+- lib/rubytui/event.rb
+- lib/rubytui/frame.rb
+- lib/rubytui/input/key.rb
+- lib/rubytui/input/parser.rb
+- lib/rubytui/input/reader.rb
+- lib/rubytui/layout/constraint.rb
+- lib/rubytui/layout/flex.rb
+- lib/rubytui/layout/layout.rb
+- lib/rubytui/modifier.rb
+- lib/rubytui/rect.rb
+- lib/rubytui/stateful_widget.rb
+- lib/rubytui/style.rb
+- lib/rubytui/symbols.rb
+- lib/rubytui/terminal.rb
+- lib/rubytui/text/line.rb
+- lib/rubytui/text/span.rb
+- lib/rubytui/text/text.rb
+- lib/rubytui/unicode.rb
+- lib/rubytui/version.rb
+- lib/rubytui/widget.rb
+- lib/rubytui/widgets/async_image.rb
+- lib/rubytui/widgets/block.rb
+- lib/rubytui/widgets/canvas.rb
+- lib/rubytui/widgets/chart.rb
+- lib/rubytui/widgets/gauge.rb
+- lib/rubytui/widgets/image.rb
+- lib/rubytui/widgets/input_field.rb
+- lib/rubytui/widgets/list.rb
+- lib/rubytui/widgets/paragraph.rb
+- lib/rubytui/widgets/popup.rb
+- lib/rubytui/widgets/scrollbar.rb
+- lib/rubytui/widgets/sparkline.rb
+- lib/rubytui/widgets/table.rb
+- lib/rubytui/widgets/tabs.rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.19
+specification_version: 4
+summary: Pure Ruby, zero-dependency terminal user interface library
+test_files: []