ratatui_ruby 1.0.0 → 1.0.1

data/examples/widget_render/app.rb

@@ -1,186 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$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::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::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::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_render/app.rbs

@@ -1,41 +0,0 @@
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-#
-# SPDX-License-Identifier: MIT-0
-
-class DiagonalWidget
-  @widget_index: Integer
-  @widgets: Array[{ name: String, widget: (DiagonalWidget | CheckerboardWidget | BorderWidget) }]
-  @tui: RatatuiRuby::TUI
-
-  def run: () -> void
-
-  private def render: () -> void
-  private def handle_input: () -> Symbol?
-end
-
-class DiagonalWidget
-  def render: (RatatuiRuby::Rect area) -> Array[RatatuiRuby::Draw::StringCmd | RatatuiRuby::Draw::CellCmd]
-end
-
-class CheckerboardWidget
-  @char: String
-
-  def initialize: (?String char) -> void
-  def render: (RatatuiRuby::Rect area) -> Array[RatatuiRuby::Draw::StringCmd | RatatuiRuby::Draw::CellCmd]
-end
-
-class BorderWidget
-  def render: (RatatuiRuby::Rect area) -> Array[RatatuiRuby::Draw::StringCmd | RatatuiRuby::Draw::CellCmd]
-end
-
-class WidgetRender
-  @widget_index: Integer
-  @widgets: Array[{ name: String, widget: (DiagonalWidget | CheckerboardWidget | BorderWidget) }]
-  @tui: RatatuiRuby::TUI
-
-  def initialize: () -> void
-  def run: () -> void
-
-  private def render: () -> void
-  private def handle_input: () -> Symbol?
-end

data/examples/widget_rich_text/README.md

@@ -1,44 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Rich Text Example
-
-[![widget_rich_text](../../doc/images/widget_rich_text.png)](app.rb)
-
-Demonstrates styling individual words and characters.
-
-Standard strings are monochromatic. "Rich Text" is composed of `Lines` containing multiple `Spans`, where each Span has its own style. This allows for multi-colored, multi-styled text blocks.
-
-## Features Demonstrated
-
-- **Spans**: Chunks of text with a specific style (e.g., "Bold Red Word").
-- **Lines**: ordered collections of Spans that form a single row of text.
-- **Paragraphs**: Rendering lines of rich text.
-
-## Hotkeys
-
-- **q**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_rich_text/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Highlight keywords in code (Syntax highlighting).
-- Create status lines with icons (e.g., "✔ Success" where the checkmark is green).
-- Emphasize specific data points in a paragraph.
-
-[Read the source code →](app.rb)

data/examples/widget_rich_text/app.rb

@@ -1,193 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$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. Also demonstrates Line alignment methods.
-class WidgetRichText
-  def initialize
-    @scroll_pos = 0
-    @color_index = 0
-    @alignment_index = 0
-    @alignments = [:left, :center, :right]
-  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
-    # Create a base line with spans, then apply alignment using the fluent methods
-    alignment = @alignments[@alignment_index]
-    aligned_line = case alignment
-                   when :left then base_line.left_aligned
-                   when :center then base_line.centered
-                   when :right then base_line.right_aligned
-    end
-
-    @tui.paragraph(
-      text: [
-        aligned_line,
-        @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),
-          ]
-        ),
-        @tui.text_line(spans: []),
-        @tui.text_line(
-          spans: [
-            @tui.text_span(content: "A", style: @tui.style(modifiers: [:bold, :underlined])),
-            @tui.text_span(content: ": Alignment (#{alignment})", style: nil),
-          ]
-        ),
-      ],
-      block: @tui.block(
-        title: "Simple Rich Text",
-        borders: [:all]
-      )
-    )
-  end
-
-  private def base_line
-    # Demonstrates creating a styled line with various modifiers and colors
-    # Including: underline_color (distinct from fg) and remove_modifiers (to override inherited styles)
-    @tui.text_line(
-      spans: [
-        @tui.text_span(content: "Normal, ", style: nil),
-        @tui.text_span(content: "Bold", style: @tui.style(modifiers: [:bold])),
-        @tui.text_span(content: ", ", style: nil),
-        @tui.text_span(content: "Italic", style: @tui.style(modifiers: [:italic])),
-        @tui.text_span(content: ", ", style: nil),
-        @tui.text_span(content: "Red", style: @tui.style(fg: :red)),
-        @tui.text_span(content: ", ", style: nil),
-        # New: underline_color - underline in a different color than text
-        @tui.text_span(
-          content: "Red Underline",
-          style: @tui.style(fg: :white, modifiers: [:underlined], underline_color: :red)
-        ),
-        @tui.text_span(content: ".", style: nil),
-      ]
-    )
-  end
-
-  private def complex_example
-    # Example 2: Multiple lines with different styles
-    # Includes Symbols::Shade constants for density gradients
-    shade = RatatuiRuby::Symbols::Shade
-
-    @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: []),
-        # Demonstrate Symbols::Shade constants for density gradients
-        @tui.text_line(
-          spans: [
-            @tui.text_span(content: "Shade: ", style: @tui.style(fg: :cyan)),
-            @tui.text_span(content: shade::EMPTY * 4, style: nil),
-            @tui.text_span(content: shade::LIGHT * 4, style: @tui.style(fg: :dark_gray)),
-            @tui.text_span(content: shade::MEDIUM * 4, style: @tui.style(fg: :gray)),
-            @tui.text_span(content: shade::DARK * 4, style: @tui.style(fg: :white)),
-            @tui.text_span(content: shade::FULL * 4, style: @tui.style(fg: :white)),
-          ]
-        ),
-        @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: ": color by 1, ", style: nil),
-            @tui.text_span(content: "← →", style: @tui.style(modifiers: [:bold])),
-            @tui.text_span(content: ": 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
-    elsif event == "a"
-      @alignment_index = (@alignment_index + 1) % @alignments.size
-    end
-
-    nil
-  end
-end
-
-if __FILE__ == $0
-  WidgetRichText.new.run
-end

data/examples/widget_scroll_text/README.md

@@ -1,46 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Scroll Text Example
-
-[![widget_scroll_text](../../doc/images/widget_scroll_text.png)](app.rb)
-
-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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_scroll_text/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)

data/examples/widget_scroll_text/app.rb

@@ -1,109 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-
-# 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/README.md

@@ -1,46 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Scrollbar (Scroll) Example
-
-[![widget_scrollbar](../../doc/images/widget_scrollbar.png)](app.rb)
-
-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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_scrollbar/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)