ratatui_ruby 0.4.0 → 0.5.0

data/examples/widget_render/app.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# Custom widget that draws a diagonal line.
+#
+# Demonstrates absolute coordinate rendering respecting the given area bounds.
+# This pattern is essential when custom widgets need to coexist with bordered blocks.
+class DiagonalWidget
+  def render(area)
+    # Draw a diagonal line within the area's bounds.
+    # The area parameter respects parent block borders and padding automatically.
+    (0..10).filter_map do |i|
+      next if i >= area.width || i >= area.height
+
+      RatatuiRuby::Draw.string(
+        area.x + i,
+        area.y + i,
+        "\\",
+        RatatuiRuby::Style.new(fg: :red, modifiers: [:bold])
+      )
+    end
+  end
+end
+
+# Custom widget that draws a checkerboard pattern.
+#
+# This pattern shows using the area's x, y offset correctly when rendering
+# absolute coordinates. The area parameter may have x, y > 0 when rendered
+# inside a positioned block. Always use area.x and area.y as offsets.
+class CheckerboardWidget
+  def initialize(char = "□")
+    @char = char
+  end
+
+  def render(area)
+    result = []
+    (0...area.height).each do |row| # rubocop:disable Lint/AmbiguousRange
+      (0...area.width).each do |col| # rubocop:disable Lint/AmbiguousRange
+        next if (row + col).even?
+
+        result << RatatuiRuby::Draw.string(
+          area.x + col,
+          area.y + row,
+          @char,
+          RatatuiRuby::Style.new(fg: :cyan)
+        )
+      end
+    end
+    result
+  end
+end
+
+# Custom widget that draws a border inside the area.
+#
+# Demonstrates that custom widgets can compose complex shapes using the area's bounds.
+# Here we draw a complete box (corners and edges) that fits within the area,
+# respecting width and height constraints automatically.
+class BorderWidget
+  def render(area)
+    result = []
+    style = RatatuiRuby::Style.new(fg: :green)
+
+    # Top and bottom
+    (0...area.width).each do |x| # rubocop:disable Lint/AmbiguousRange
+      result << RatatuiRuby::Draw.string(area.x + x, area.y, "─", style)
+      result << RatatuiRuby::Draw.string(area.x + x, area.y + area.height - 1, "─", style)
+    end
+
+    # Left and right
+    (0...area.height).each do |y| # rubocop:disable Lint/AmbiguousRange
+      result << RatatuiRuby::Draw.string(area.x, area.y + y, "│", style)
+      result << RatatuiRuby::Draw.string(area.x + area.width - 1, area.y + y, "│", style)
+    end
+
+    # Corners
+    result << RatatuiRuby::Draw.string(area.x, area.y, "┌", style)
+    result << RatatuiRuby::Draw.string(area.x + area.width - 1, area.y, "┐", style)
+    result << RatatuiRuby::Draw.string(area.x, area.y + area.height - 1, "└", style)
+    result << RatatuiRuby::Draw.string(area.x + area.width - 1, area.y + area.height - 1, "┘", style)
+
+    result
+  end
+end
+
+class WidgetRender
+  def initialize
+    @widget_index = 0
+    @widgets = [
+      { name: "Diagonal", widget: DiagonalWidget.new },
+      { name: "Checkerboard", widget: CheckerboardWidget.new("□") },
+      { name: "Border", widget: BorderWidget.new },
+    ]
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def render
+    @tui.draw do |frame|
+      layout = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(4),
+        ]
+      )
+
+      # Render a border block to frame widget area
+      current_name = @widgets[@widget_index][:name]
+      widget_block = @tui.block(
+        title: "Custom Widget: #{current_name}",
+        borders: [:all]
+      )
+      frame.render_widget(widget_block, layout[0])
+
+      # Calculate the inner area, accounting for the block's 1-character border on all sides.
+      # This is the key pattern: compute the available space INSIDE the block before
+      # passing it to the custom widget's render method.
+      # When the custom widget receives this area, all its absolute coordinates will
+      # respect the block's boundaries automatically.
+      inner_area = @tui.rect(
+        x: layout[0].x + 1,
+        y: layout[0].y + 1,
+        width: [layout[0].width - 2, 0].max,
+        height: [layout[0].height - 2, 0].max
+      )
+
+      # Render the custom widget inside the bordered area.
+      # The widget's render method receives the inner_area and draws within it.
+      frame.render_widget(@widgets[@widget_index][:widget], inner_area)
+
+      # Render control panel with current widget info
+      control_lines = [
+        @tui.text_line(
+          spans: [
+            @tui.text_span(content: "n", style: @tui.style(modifiers: [:bold, :underlined])),
+            @tui.text_span(content: ": Next  "),
+            @tui.text_span(content: "p", style: @tui.style(modifiers: [:bold, :underlined])),
+            @tui.text_span(content: ": Previous  "),
+            @tui.text_span(content: "q", style: @tui.style(modifiers: [:bold, :underlined])),
+            @tui.text_span(content: ": Quit"),
+          ]
+        ),
+      ]
+      controls = @tui.paragraph(
+        text: control_lines,
+        block: @tui.block(
+          title: "Controls",
+          borders: [:all]
+        )
+      )
+      frame.render_widget(controls, layout[1])
+    end
+  end
+
+  private def handle_input
+    event = @tui.poll_event
+    case event
+    in { type: :key, code: "q" }
+      :quit
+    in { type: :key, code: "n" }
+      @widget_index = (@widget_index + 1) % @widgets.length
+    in { type: :key, code: "p" }
+      @widget_index = (@widget_index - 1) % @widgets.length
+    else
+      # Ignore other events
+    end
+  end
+end
+
+WidgetRender.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_rich_text/app.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# Rich Text Example
+# Demonstrates the Span and Line objects for styling individual words
+# within a block of text.
+class WidgetRichText
+  def initialize
+    @scroll_pos = 0
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      loop do
+        render
+        event = handle_input
+        break if event == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def render
+    @tui.draw do |frame|
+      layout = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_percentage(50),
+          @tui.constraint_percentage(50),
+        ]
+      )
+      frame.render_widget(simple_text_line_example, layout[0])
+      frame.render_widget(complex_example, layout[1])
+    end
+  end
+
+  private def simple_text_line_example
+    # Example 1: A line with mixed styles
+    @tui.paragraph(
+      text: @tui.text_line(
+        spans: [
+          @tui.text_span(
+            content: "Normal text, ",
+            style: nil
+          ),
+          @tui.text_span(
+            content: "Bold Text",
+            style: @tui.style(modifiers: [:bold])
+          ),
+          @tui.text_span(
+            content: ", ",
+            style: nil
+          ),
+          @tui.text_span(
+            content: "Italic Text",
+            style: @tui.style(modifiers: [:italic])
+          ),
+          @tui.text_span(
+            content: ", ",
+            style: nil
+          ),
+          @tui.text_span(
+            content: "Red Text",
+            style: @tui.style(fg: :red)
+          ),
+          @tui.text_span(
+            content: ".",
+            style: nil
+          ),
+        ]
+      ),
+      block: @tui.block(
+        title: "Simple Rich Text",
+        borders: [:all]
+      )
+    )
+  end
+
+  private def complex_example
+    # Example 2: Multiple lines with different styles
+    @tui.paragraph(
+      text: [
+        @tui.text_line(
+          spans: [
+            @tui.text_span(content: "✓ ", style: @tui.style(fg: :green, modifiers: [:bold])),
+            @tui.text_span(content: "Feature Complete", style: nil),
+            @tui.text_span(content: " - All tests passing", style: @tui.style(fg: :gray)),
+          ]
+        ),
+        @tui.text_line(
+          spans: [
+            @tui.text_span(content: "⚠ ", style: @tui.style(fg: :yellow, modifiers: [:bold])),
+            @tui.text_span(content: "Warning", style: nil),
+            @tui.text_span(content: " - Documentation pending", style: @tui.style(fg: :gray)),
+          ]
+        ),
+        @tui.text_line(
+          spans: [
+            @tui.text_span(content: "✗ ", style: @tui.style(fg: :red, modifiers: [:bold])),
+            @tui.text_span(content: "Not Started", style: nil),
+            @tui.text_span(content: " - Performance benchmarks", style: @tui.style(fg: :gray)),
+          ]
+        ),
+        @tui.text_line(spans: []),
+        @tui.text_line(
+          spans: [
+            @tui.text_span(content: "Press ", style: nil),
+            @tui.text_span(content: "Q", style: @tui.style(modifiers: [:bold])),
+            @tui.text_span(content: " to quit", style: nil),
+          ]
+        ),
+      ],
+      block: @tui.block(
+        title: "Status Report",
+        borders: [:all]
+      )
+    )
+  end
+
+  private def handle_input
+    event = @tui.poll_event
+    return :quit if event == "q" || event == :esc || event == :ctrl_c
+
+    nil
+  end
+end
+
+if __FILE__ == $0
+  WidgetRichText.new.run
+end

data/examples/widget_scroll_text/app.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# Demo: Scrollable Paragraph
+# Shows how to scroll through long text content using arrow keys
+#
+# Helper: Disable experimental warnings since we use line_count/line_width
+RatatuiRuby.experimental_warnings = false
+
+class WidgetScrollText
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      @scroll_x = 0
+      @scroll_y = 0
+
+      @lines = (1..100).map do |i|
+        "Line #{i}: " + ("This is a long line of text that can be scrolled horizontally. " * 3) + "End of line #{i}"
+      end
+      @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+
+      loop do
+        draw
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  def render
+    # No-op for compatibility if needed, or alias to draw, but draw now uses @tui
+    draw
+  end
+
+  def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "up"
+      @scroll_y = [@scroll_y - 1, 0].max
+    in type: :key, code: "down"
+      @scroll_y = [@scroll_y + 1, @lines.length].min
+    in type: :key, code: "left"
+      @scroll_x = [@scroll_x - 1, 0].max
+    in type: :key, code: "right"
+      @scroll_x = [@scroll_x + 1, 100].min
+    else
+      nil
+    end
+  end
+
+  private def draw
+    @tui.draw do |frame|
+      layout = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(5),
+        ]
+      )
+
+      text = @lines.join("\n")
+
+      # Main content
+      main_paragraph = @tui.paragraph(
+        text:,
+        scroll: [@scroll_y, @scroll_x],
+        block: @tui.block(
+          title: "Scrollable Text (#{text.lines.count} lines)",
+          borders: [:all]
+        )
+      )
+      frame.render_widget(main_paragraph, layout[0])
+
+      # Bottom control panel
+      control_text = [
+        @tui.text_line(spans: [
+          @tui.text_span(content: "NAVIGATION (Size: #{main_paragraph.line_count(65535)}x#{main_paragraph.line_width})", style: @tui.style(modifiers: [:bold])),
+        ]),
+        @tui.text_line(spans: [
+          @tui.text_span(content: "↑/↓", style: @hotkey_style),
+          @tui.text_span(content: ": Vert Scroll (#{@scroll_y}/#{main_paragraph.line_count(65535)})  "),
+          @tui.text_span(content: "←/→", style: @hotkey_style),
+          @tui.text_span(content: ": Horz Scroll (#{@scroll_x}/#{main_paragraph.line_width})  "),
+          @tui.text_span(content: "q", style: @hotkey_style),
+          @tui.text_span(content: ": Quit"),
+        ]),
+      ]
+
+      control_paragraph = @tui.paragraph(
+        text: control_text,
+        block: @tui.block(
+          title: "Controls",
+          borders: [:all]
+        )
+      )
+      frame.render_widget(control_paragraph, layout[1])
+    end
+  end
+end
+
+WidgetScrollText.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_scrollbar_demo/app.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# Demonstrates viewport navigation with interactive theme and orientation cycling.
+#
+# Content overflows. Users get lost in long lists without landmarks. They need to know where they are and how much is left.
+#
+# This demo showcases the <tt>Scrollbar</tt> widget. It provides an interactive playground where you can toggle orientations and cycle through different themes (Standard, Rounded, ASCII, Minimal) in real-time.
+#
+# Use it to understand how to provide spatial awareness and navigation cues for overflowing content.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_scrollbar_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_scrollbar_demo.png
+class WidgetScrollbarDemo
+  def initialize
+    @scroll_position = 0
+    @content_length = 50
+    @lines = (1..@content_length).map { |i| "Line #{i}" }
+    @orientation_index = 0
+    @orientations = [
+      :vertical,
+      :vertical_right,
+      :vertical_left,
+      :horizontal,
+      :horizontal_bottom,
+      :horizontal_top,
+    ]
+    @theme_index = 0
+    @themes = [
+      {
+        name: "Standard",
+        track_symbol: nil,
+        thumb_symbol: "█",
+        track_style: nil,
+        thumb_style: nil,
+        begin_symbol: nil,
+        end_symbol: nil,
+      },
+      {
+        name: "Rounded",
+        track_symbol: "│",
+        thumb_symbol: "┃",
+        track_style: { fg: "dark_gray" },
+        thumb_style: { fg: "cyan" },
+        begin_symbol: "▲",
+        end_symbol: "▼",
+      },
+      {
+        name: "ASCII",
+        track_symbol: "|",
+        thumb_symbol: "#",
+        track_style: { fg: "white" },
+        thumb_style: { fg: "red" },
+        begin_symbol: "^",
+        end_symbol: "v",
+      },
+      {
+        name: "Minimal",
+        track_symbol: " ",
+        thumb_symbol: "▐",
+        track_style: nil,
+        thumb_style: { fg: "yellow" },
+        begin_symbol: nil,
+        end_symbol: nil,
+      },
+    ]
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      loop do
+        draw
+        event = @tui.poll_event
+        break if event == "q" || event == :ctrl_c
+
+        handle_event(event)
+      end
+    end
+  end
+
+  private def handle_event(event)
+    if event.mouse?
+      case event.kind
+      when "scroll_up"
+        @scroll_position = [@scroll_position - 1, 0].max
+      when "scroll_down"
+        @scroll_position = [@scroll_position + 1, @content_length].min
+      end
+    end
+
+    if event.key? && event.to_s == "s"
+      @theme_index = (@theme_index + 1) % @themes.length
+    end
+
+    if event.key? && event.to_s == "o"
+      @orientation_index = (@orientation_index + 1) % @orientations.length
+    end
+  end
+
+  private def draw
+    @tui.draw do |frame|
+      # Calculate visible lines based on scroll position
+      # In a real app, you'd want to know the height of the available area.
+      # For this demo, we'll just show all lines but offset the text.
+      visible_lines = @lines[@scroll_position..-1] || []
+
+      # Paragraph with content
+      theme = @themes[@theme_index]
+      orientation = @orientations[@orientation_index]
+
+      p = @tui.paragraph(
+        text: visible_lines.join("\n"),
+        block: @tui.block(
+          titles: [
+            { content: "Scroll with Mouse Wheel | Theme: #{theme[:name]} | Orientation: #{orientation}" },
+            { content: "Press 's' to cycle theme, 'o' to cycle orientation", position: :bottom, alignment: :center },
+          ],
+          borders: [:all]
+        )
+      )
+
+      # Scrollbar
+      s = @tui.scrollbar(
+        content_length: @content_length,
+        position: @scroll_position,
+        orientation:,
+        track_symbol: theme[:track_symbol],
+        thumb_symbol: theme[:thumb_symbol],
+        track_style: theme[:track_style],
+        thumb_style: theme[:thumb_style],
+        begin_symbol: theme[:begin_symbol],
+        end_symbol: theme[:end_symbol]
+      )
+
+      # Render paragraph first, then scrollbar on top
+      frame.render_widget(p, frame.area)
+      frame.render_widget(s, frame.area)
+    end
+  end
+end
+
+WidgetScrollbarDemo.new.run if __FILE__ == $PROGRAM_NAME