ratatui_ruby 0.4.0 → 0.6.0

data/examples/widget_ratatui_mascot_demo/app.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: CC-BY-SA-4.0
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# Demonstrates personality and charm with the project mascot.
+#
+# Interfaces without personality feel clinical and dry. Users appreciate a friendly face in their terminal.
+#
+# This demo showcases the <tt>RatatuiMascot</tt> widget. It provides an interactive playground where you can toggle the surrounding block.
+#
+# Use it to understand how to add a playful touch to your terminal dashboards or about screens.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_ratatui_mascot_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_ratatui_mascot_demo.png
+class WidgetRatatuiMascotDemo
+  def initialize
+    @show_block = true
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        tui.draw do |frame|
+          # Layout: Top (Mascot), Bottom (Controls)
+          layout = tui.layout_split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              tui.constraint_fill(1),
+              tui.constraint_length(4),
+            ]
+          )
+
+          mascot_area = layout[0]
+          controls_area = layout[1]
+
+          # Mascot Widget
+          block = if @show_block
+            tui.block(
+              title: "Ratatui Mascot",
+              borders: [:all],
+              border_type: :rounded,
+              border_style: { fg: :green }
+            )
+          end
+
+          mascot = tui.ratatui_mascot(block:)
+          frame.render_widget(mascot, mascot_area)
+
+          # Controls
+          controls_text = [
+            tui.text_span(content: "q", style: tui.style(modifiers: [:bold, :underlined])),
+            tui.text_span(content: " Quit"),
+            tui.text_span(content: "   "),
+            tui.text_span(content: "b", style: tui.style(modifiers: [:bold, :underlined])),
+            tui.text_span(content: " Toggle Block #{@show_block ? '(On)' : '(Off)'}"),
+          ]
+
+          controls_paragraph = tui.paragraph(
+            text: tui.text_line(spans: controls_text),
+            block: tui.block(borders: [:top], title: "Controls")
+          )
+          frame.render_widget(controls_paragraph, controls_area)
+        end
+        break if handle_input(tui) == :quit
+      end
+    end
+  end
+
+  private def handle_input(tui)
+    event = tui.poll_event
+
+    if event.key?
+      case event.char
+      when "q" then :quit
+      when "b" then @show_block = !@show_block
+      end
+    elsif event.ctrl_c?
+      :quit
+    end
+  end
+end
+
+WidgetRatatuiMascotDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_rect/README.md

@@ -0,0 +1,38 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Rect (Geometry) Widget Example
+
+Demonstrates the Rect geometry primitive and hit-testing patterns.
+
+TUI layouts are composed of rectangles. Understanding how to manipulate `Rect` objects, reuse them from the layout phase, and use them for mouse interaction is critical for building interactive apps.
+
+## Features Demonstrated
+
+- **Rect Attributes**: Investigating x, y, width, and height.
+- **Cached Layout Pattern**: Computing constraints in the render loop and reusing the resulting `Rect`s in the event loop for logic.
+- **Hit Testing**: Using `Rect#contains?(x, y)` to determine if a mouse click happened inside a specific panel.
+
+## Hotkeys
+
+- **Arrows (←/→)**: Expand/Shrink Sidebar Width (Layout Constraint)
+- **Arrows (↑/↓)**: Navigate Menu Selection (`selected_index`)
+- **Mouse Click**: Click anywhere to see which Rect detects the hit (`contains?`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_rect/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Handle mouse clicks on specific buttons or areas.
+- Create resizable panes (like a split pane in an IDE).
+- Debug layout issues by inspecting Rect coordinates.
+
+![Demo](/doc/images/widget_rect.png)

data/examples/widget_rect/app.rb

@@ -0,0 +1,205 @@
+# 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"
+
+# Rect Widget Showcase
+#
+# Demonstrates the Rect class and the Cached Layout Pattern.
+#
+# Rect is the fundamental geometry primitive for TUI layout. This example shows:
+# - Rect attributes: x, y, width, height
+# - Rect#contains? for hit testing mouse clicks
+# - Layout.split returning cached rects for reuse
+# - The layout caching pattern: compute in draw, reuse in handle_input
+#
+# Controls:
+#   ←/→: Adjust sidebar width
+#   ↑/↓: Navigate menu items
+#   Mouse: Click panels to test Rect#contains?
+#   q: Quit
+class WidgetRect
+  MENU_ITEMS = ["Dashboard", "Analytics", "Settings", "Logs", "Help"].freeze
+
+  def initialize
+    @sidebar_width = 20
+    @selected_index = 0
+    @last_action = "Click any panel to test Rect#contains?"
+    @click_count = 0
+    @sidebar_rect = nil
+    @main_rect = nil
+    @controls_rect = nil
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+      @label_style = @tui.style(modifiers: [:bold])
+      @dim_style = @tui.style(fg: :dark_gray)
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def render
+    @tui.draw do |frame|
+      @main_rect, @controls_rect = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(8),
+        ]
+      )
+
+      @sidebar_rect, @content_rect = @tui.layout_split(
+        @main_rect,
+        direction: :horizontal,
+        constraints: [
+          @tui.constraint_length(@sidebar_width),
+          @tui.constraint_fill(1),
+        ]
+      )
+
+      render_sidebar(frame)
+      render_content(frame)
+      render_controls(frame)
+    end
+  end
+
+  private def render_sidebar(frame)
+    sidebar = @tui.list(
+      items: MENU_ITEMS,
+      selected_index: @selected_index,
+      highlight_style: @tui.style(fg: :black, bg: :white, modifiers: [:bold]),
+      highlight_symbol: "> ",
+      block: @tui.block(title: "Menu", borders: [:all])
+    )
+    frame.render_widget(sidebar, @sidebar_rect)
+  end
+
+  private def render_content(frame)
+    text_content = [
+      @tui.text_line(spans: [
+        @tui.text_span(content: "Active View: ", style: @label_style),
+        @tui.text_span(content: MENU_ITEMS[@selected_index], style: @tui.style(fg: :green)),
+      ]),
+      "",
+      @tui.text_line(spans: [
+        @tui.text_span(content: "Rect Attributes ", style: @label_style),
+        @tui.text_span(content: "(from Layout.split):", style: @dim_style),
+      ]),
+      "  Sidebar: Rect(x:#{@sidebar_rect.x}, y:#{@sidebar_rect.y}, " \
+        "width:#{@sidebar_rect.width}, height:#{@sidebar_rect.height})",
+      "  Content: Rect(x:#{@content_rect.x}, y:#{@content_rect.y}, " \
+        "width:#{@content_rect.width}, height:#{@content_rect.height})",
+      "",
+      @tui.text_line(spans: [
+        @tui.text_span(content: "Hit Testing ", style: @label_style),
+        @tui.text_span(content: "(Rect#contains?):", style: @dim_style),
+      ]),
+      "  Clicks: #{@click_count}  |  #{@last_action}",
+    ]
+
+    paragraph = @tui.paragraph(
+      text: text_content,
+      block: @tui.block(title: "Content", borders: [:all])
+    )
+    frame.render_widget(paragraph, @content_rect)
+  end
+
+  private def render_controls(frame)
+    controls = @tui.block(
+      title: "Controls",
+      borders: [:all],
+      children: [
+        @tui.paragraph(
+          text: [
+            @tui.text_line(spans: [
+              @tui.text_span(content: "LAYOUT", style: @label_style),
+              @tui.text_span(content: "  "),
+              @tui.text_span(content: "←", style: @hotkey_style),
+              @tui.text_span(content: ": Shrink sidebar  "),
+              @tui.text_span(content: "→", style: @hotkey_style),
+              @tui.text_span(content: ": Expand sidebar  "),
+              @tui.text_span(content: "(width: #{@sidebar_width})"),
+            ]),
+            @tui.text_line(spans: [
+              @tui.text_span(content: "NAVIGATION", style: @label_style),
+              @tui.text_span(content: "  "),
+              @tui.text_span(content: "↑↓", style: @hotkey_style),
+              @tui.text_span(content: ": Select menu item  "),
+              @tui.text_span(content: "q", style: @hotkey_style),
+              @tui.text_span(content: ": Quit"),
+            ]),
+            "",
+            @tui.text_line(spans: [
+              @tui.text_span(content: "HIT TESTING", style: @label_style),
+              @tui.text_span(content: "  Click any panel → Rect#contains?(x, y) determines which rect was hit."),
+            ]),
+          ]
+        ),
+      ]
+    )
+    frame.render_widget(controls, @controls_rect)
+  end
+
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: "left"
+      @sidebar_width = [@sidebar_width - 2, 10].max
+      @last_action = "Layout changed: sidebar_width=#{@sidebar_width}"
+      nil
+    in type: :key, code: "right"
+      @sidebar_width = [@sidebar_width + 2, 40].min
+      @last_action = "Layout changed: sidebar_width=#{@sidebar_width}"
+      nil
+    in type: :key, code: "up"
+      @selected_index = (@selected_index - 1) % MENU_ITEMS.size
+      @last_action = "Selected: #{MENU_ITEMS[@selected_index]}"
+      nil
+    in type: :key, code: "down"
+      @selected_index = (@selected_index + 1) % MENU_ITEMS.size
+      @last_action = "Selected: #{MENU_ITEMS[@selected_index]}"
+      nil
+    in type: :mouse, kind: "down", x: click_x, y: click_y
+      handle_click(click_x, click_y)
+      nil
+    else
+      nil
+    end
+  end
+
+  private def handle_click(x, y)
+    @click_count += 1
+
+    if @sidebar_rect&.contains?(x, y)
+      relative_y = y - @sidebar_rect.y - 1
+      if relative_y >= 0 && relative_y < MENU_ITEMS.size
+        old_item = MENU_ITEMS[@selected_index]
+        @selected_index = relative_y
+        new_item = MENU_ITEMS[@selected_index]
+        @last_action = "sidebar.contains?(#{x},#{y})=true → #{old_item}→#{new_item}"
+      else
+        @last_action = "sidebar.contains?(#{x},#{y})=true (empty area)"
+      end
+    elsif @content_rect&.contains?(x, y)
+      @last_action = "content.contains?(#{x},#{y})=true"
+    elsif @controls_rect&.contains?(x, y)
+      @last_action = "controls.contains?(#{x},#{y})=true"
+    else
+      @last_action = "No rect contains (#{x},#{y})"
+    end
+  end
+end
+
+WidgetRect.new.run if __FILE__ == $0

data/examples/widget_render/README.md

@@ -0,0 +1,37 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Render (Custom Widget) Example
+
+Demonstrates how to build Custom Widgets using absolute coordinates.
+
+Sometimes standard widgets aren't enough. You need to draw custom shapes, games, or graphs. This example shows how to implement the `render(area)` contract to draw anything you want while respecting layout boundaries.
+
+## Features Demonstrated
+
+- **Custom Widget Contract**: Implementing a class with `render(area)`.
+- **Coordinate Offsets**: Creating drawing logic that works regardless of where the widget is placed on screen (using `area.x + offset`).
+- **Composability**: Wrapping custom widgets in standard `Block`s with borders.
+
+## Hotkeys
+
+- **n**: Next Widget (Diagonal -> Checkerboard -> Border)
+- **p**: Previous Widget
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_render/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Build a game (Snake, Tetris) inside the terminal.
+- Create a specialized visualization (Network topology graph).
+- Draw custom UI elements not provided by the library.
+
+![Demo](/doc/images/widget_render.png)

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/README.md

@@ -0,0 +1,35 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Rich Text Example
+
+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
+
+```bash
+ruby examples/widget_rich_text/app.rb
+```
+
+## 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.
+
+![Demo](/doc/images/widget_rich_text.png)