ratatui_ruby 0.4.0 → 0.6.0

data/examples/widget_rich_text/app.rb

@@ -0,0 +1,166 @@
+# 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
+    @color_index = 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
+            ),
+          ]
+        ),
+        @tui.text_line(spans: []),
+        @tui.text_line(
+          spans: [
+            @tui.text_span(content: "Integer Color Test: "),
+            @tui.text_span(content: "Color #{@color_index}", style: @tui.style(fg: @color_index)),
+            @tui.text_span(content: " (Use "),
+            @tui.text_span(content: "↑ ↓", style: @tui.style(modifiers: [:bold])),
+            @tui.text_span(content: " for +/- 1,", style: nil),
+            @tui.text_span(content: "→ ←", style: @tui.style(modifiers: [:bold])),
+            @tui.text_span(content: " for +/- 10)", 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),
+            @tui.text_span(content: "↑ ↓", style: @tui.style(modifiers: [:bold])),
+            @tui.text_span(content: " to adjust color by 1, ", style: nil),
+            @tui.text_span(content: "← →", style: @tui.style(modifiers: [:bold])),
+            @tui.text_span(content: " to adjust color by 10.", 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
+
+    if event.left?
+      @color_index = (@color_index - 10) % 256
+    elsif event.right?
+      @color_index = (@color_index + 10) % 256
+    elsif event.up?
+      @color_index = (@color_index + 1) % 256
+    elsif event.down?
+      @color_index = (@color_index - 1) % 256
+    end
+
+    nil
+  end
+end
+
+if __FILE__ == $0
+  WidgetRichText.new.run
+end

data/examples/widget_scroll_text/README.md

@@ -0,0 +1,37 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Scroll Text Example
+
+Demonstrates scrolling long text content within a fixed viewport.
+
+Sometimes text exceeds the available space. The `Paragraph` widget supports a `scroll` parameter to simulate a viewport, allowing users to pan vertically and horizontally.
+
+## Features Demonstrated
+
+- **Vertical Scrolling**: Moving through lines of text.
+- **Horizontal Scrolling**: Panning across long, unwrapped lines.
+- **State Management**: tracking `scroll_x` and `scroll_y` offsets in the application state.
+
+## Hotkeys
+
+- **Arrows (↑/↓)**: Scroll Vertically (`scroll`)
+- **Arrows (←/→)**: Scroll Horizontally (`scroll`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_scroll_text/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Build a log viewer.
+- Create a "terms and conditions" scrollbox.
+- Display code snippets that might be wider than the terminal.
+
+![Demo](/doc/images/widget_scroll_text.png)

data/examples/widget_scroll_text/app.rb

@@ -0,0 +1,107 @@
+# 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/README.md

@@ -0,0 +1,37 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Scrollbar Widget Example
+
+Demonstrates explicit scrollbars for navigation feedback.
+
+Content overflows. Users get lost in long lists. Scrollbars provide essential spatial awareness ("How far down am I?") and navigation controls.
+
+## Features Demonstrated
+
+- **Orientation**: Vertical, Horizontal, and variation modes (Right/Left, Top/Bottom).
+- **Styling**: Custom characters for Track, Thumb, and arrows.
+- **State Integration**: Linking the scrollbar `position` to the content view state.
+
+## Hotkeys
+
+- **Mouse Wheel**: Scroll content (`position`)
+- **s**: Cycle Scrollbar Theme (Standard, Rounded, ASCII, Minimal)
+- **o**: Cycle Orientation (`orientation`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_scrollbar_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Add visual scroll indicators to Lists or Tables.
+- Implement specialized inputs like sliders or volume controls.
+
+![Demo](/doc/images/widget_scrollbar_demo.png)

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

data/examples/widget_sparkline_demo/README.md

@@ -0,0 +1,42 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Sparkline Widget Example
+
+Demonstrates high-density data visualization in a condensed footprint.
+
+Users need context. A single number ("90% CPU") tells you status, but not the trend. Full charts take up too much space. Sparklines condense history into a single line, perfect for headers and dashboards.
+
+## Features Demonstrated
+
+- **High Density**: Showing dozens of data points in a small area.
+- **Direction**: Rendering Left-to-Right (standard) or Right-to-Left (like a scrolling ticker).
+- **Gaps**: Handling `nil` values with "absent symbols" to indicate missing data.
+- **Styling**: Using colors and custom characters to indicate severity or type.
+
+## Hotkeys
+
+- **Up/Down (↑/↓)**: Cycle Data Set (`data`)
+- **d**: Cycle Direction (`direction`)
+- **c**: Cycle Color (`style`)
+- **m**: Cycle Absent Value Marker Symbol (`absent_value_symbol`)
+- **s**: Cycle Absent Value Marker Style (`absent_value_style`)
+- **b**: Cycle Bar Character Set (`bar_set`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_sparkline_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Add a "CPU Load" graph to your header.
+- Visualize stock price trends in a list row.
+- Monitor memory usage over the last 60 seconds.
+
+![Demo](/doc/images/widget_sparkline_demo.png)