ratatui_ruby 0.5.0 → 0.6.0

data/examples/widget_map_demo/README.md

@@ -0,0 +1,39 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Canvas Widget Example
+
+Demonstrates drawing custom graphics and maps using the standard Braille and Block patterns.
+
+Standard widgets are great for text, but sometimes you need to draw. The `Canvas` widget gives you a high-resolution coordinate system (x, y) to render shapes, lines, and data visualizations that go beyond the grid.
+
+## Features Demonstrated
+
+- **High-Resolution Drawing**: Using Braille patterns (`⣿`) to effectively double the vertical and horizontal resolution of the terminal.
+- **Layers**: Drawing multiple shapes (Map, Circles, Lines) in a specific order.
+- **Animation**: Updating coordinates in a loop to create smooth motion.
+- **World Map**: Using the built-in `Map` shape for geographic data.
+
+## Hotkeys
+
+- **b**: Cycle Background Color (`background_color`)
+- **m**: Cycle Marker Type (`marker`)
+- **l**: Toggle Labels (modifies `shapes`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_map_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Render geographic data (World, USA, Europe).
+- Overlay custom labels and markers on a map.
+- Animate visual elements on top of a static background.
+
+![Demo](/doc/images/widget_map_demo.png)

data/examples/{app_map_demo → widget_map_demo}/app.rb

@@ -7,7 +7,7 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 
 # An example of the Canvas widget showing a world map and animated shapes.
-class AppMapDemo
+class WidgetMapDemo
   include RatatuiRuby
 
   COLORS = [:black, :blue, :white, nil].freeze
@@ -90,4 +90,4 @@ class AppMapDemo
   end
 end
 
-AppMapDemo.new.run if __FILE__ == $PROGRAM_NAME
+WidgetMapDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_overlay_demo/app.rb

@@ -0,0 +1,248 @@
+# 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"
+
+HEADLINES = [
+  "Scientists Discover New Species of Deep-Sea Octopus Near Hawaii",
+  "Global Climate Summit Reaches Historic Agreement on Emissions",
+  "Tech Giant Announces Breakthrough in Quantum Computing Research",
+  "Local Community Garden Initiative Expands to Ten More Cities",
+  "Astronomers Detect Unusual Radio Signals from Distant Galaxy",
+  "New Study Links Mediterranean Diet to Improved Heart Health",
+  "Electric Vehicle Sales Surge as Battery Technology Improves",
+  "Ancient Manuscripts Reveal Previously Unknown Trading Routes",
+  "Renewable Energy Now Powers 40% of National Grid",
+  "Robotics Team Develops AI System for Disaster Response",
+  "Archaeological Dig Uncovers Evidence of Early Human Settlement",
+  "Major Airline Commits to Carbon-Neutral Flights by 2035",
+  "Breakthrough Treatment Shows Promise for Rare Genetic Disease",
+  "City Council Approves Expanded Public Transportation Network",
+  "Marine Biologists Track Migration Patterns of Endangered Whales",
+  "New App Helps Farmers Optimize Water Usage During Drought",
+  "International Space Station Extends Mission Timeline to 2030",
+  "Local Schools Implement Innovative STEM Education Program",
+  "Wildlife Conservation Efforts Lead to Species Population Recovery",
+  "Research Team Creates Biodegradable Alternative to Plastic Packaging",
+  "Historic Theater Restoration Project Nears Completion",
+  "Cybersecurity Experts Warn of Emerging Online Threats",
+  "Community Food Bank Serves Record Number of Families This Year",
+  "Innovative Urban Planning Reduces Traffic Congestion by 30%",
+].freeze
+
+# Overlay Demo Example
+# Demonstrates the Overlay widget for layering widgets with depth.
+class WidgetOverlayDemo
+  def initialize
+    @layer_count = 2 # Start with 2 layers visible
+    @swapped = false
+    @clear = true
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      loop do
+        tui.draw do |frame|
+          render(frame)
+        end
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def render(frame)
+    area = frame.area
+
+    # Split into main area and control panel
+    layout = @tui.layout_split(
+      area,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_fill(1),
+        @tui.constraint_length(5),
+      ]
+    )
+
+    main_area = layout[0]
+    control_area = layout[1]
+
+    # Render background layer - RSS reader
+    frame.render_widget(background_layer, main_area)
+
+    # Render upper layers based on layer_count and swap state
+    if @swapped
+      render_beta_layer(frame, main_area) if @layer_count >= 2
+      render_notification_layer(frame, main_area) if @layer_count >= 1
+    else
+      render_notification_layer(frame, main_area) if @layer_count >= 1
+      render_beta_layer(frame, main_area) if @layer_count >= 2
+    end
+
+    # Render control panel
+    frame.render_widget(control_panel, control_area)
+  end
+
+  def background_layer
+    @background_layer ||= @tui.list(
+      items: HEADLINES,
+      block: @tui.block(
+        title: "RSS Reader",
+        borders: [:all]
+      )
+    )
+  end
+
+  def render_notification_layer(frame, area)
+    # Position modal: 20% from top, 60% height, 15% from left, 70% width
+
+    vertical_sections = @tui.layout_split(
+      area,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_fill(2),
+        @tui.constraint_fill(5),
+        @tui.constraint_fill(3),
+      ]
+    )
+
+    horizontal_sections = @tui.layout_split(
+      vertical_sections[1],
+      direction: :horizontal,
+      constraints: [
+        @tui.constraint_fill(1),
+        @tui.constraint_fill(5),
+        @tui.constraint_fill(1),
+      ]
+    )
+
+    modal_rect = horizontal_sections[1]
+
+    frame.render_widget(@tui.clear, modal_rect) if @clear
+
+    # Render the modal content
+    frame.render_widget(
+      @tui.paragraph(
+        text: "Your feeds have been updated",
+        wrap: true,
+        alignment: :center,
+        block: @tui.block(
+          title: "Notification",
+          borders: [:all],
+          border_style: @tui.style(fg: :black),
+          style: @tui.style(bg: :red, fg: :black)
+        )
+      ),
+      modal_rect
+    )
+  end
+
+  def render_beta_layer(frame, area)
+    # Position modal: 30% from top, 40% height, 25% from left, 50% width
+
+    vertical_sections = @tui.layout_split(
+      area,
+      direction: :vertical,
+      constraints: [
+        @tui.constraint_fill(3),
+        @tui.constraint_fill(4),
+        @tui.constraint_fill(2),
+      ]
+    )
+
+    horizontal_sections = @tui.layout_split(
+      vertical_sections[1],
+      direction: :horizontal,
+      constraints: [
+        @tui.constraint_fill(2),
+        @tui.constraint_fill(3),
+        @tui.constraint_fill(2),
+      ]
+    )
+
+    modal_rect = horizontal_sections[1]
+
+    frame.render_widget(@tui.clear, modal_rect) if @clear
+
+    # Render the modal content
+    frame.render_widget(
+      beta_paragraph,
+      modal_rect
+    )
+  end
+
+  def beta_paragraph
+    @beta_paragraph ||= @tui.paragraph(
+      text: "Thank you for being a beta tester. To give feedback, shout very loudly and we will hear you. Be careful not to scare the llamas.",
+      wrap: true,
+      alignment: :left,
+      block: @tui.block(
+        title: "Beta Program",
+        borders: [:all],
+        border_style: @tui.style(fg: :black),
+        style: @tui.style(bg: :blue, fg: :black)
+      )
+    )
+  end
+
+  def control_panel
+    bold_underline = @tui.style(modifiers: [:bold, :underlined])
+
+    first_controls = [
+      @tui.text_span(content: "0", style: bold_underline),
+      @tui.text_span(content: "/"),
+      @tui.text_span(content: "1", style: bold_underline),
+      @tui.text_span(content: "/"),
+      @tui.text_span(content: "2", style: bold_underline),
+      @tui.text_span(content: ": Change number of overlays | "),
+      @tui.text_span(content: "space", style: bold_underline),
+      @tui.text_span(content: ": Swap overlay order"),
+    ]
+    second_controls = [
+      @tui.text_span(content: "c", style: bold_underline),
+      @tui.text_span(content: ": Toggle clear (currently #{@clear ? 'on' : 'off'})"),
+    ]
+    third_controls = [
+      @tui.text_span(content: "q", style: bold_underline),
+      @tui.text_span(content: ": Quit"),
+    ]
+
+    first = @tui.text_line(spans: first_controls)
+    second = @tui.text_line(spans: second_controls)
+    third = @tui.text_line(spans: third_controls)
+
+    @tui.paragraph(
+      text: [first, second, third],
+      alignment: :center,
+      block: @tui.block(
+        title: "Controls",
+        borders: [:all]
+      )
+    )
+  end
+
+  def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in { type: :key, code: "0" }
+      @layer_count = 0
+    in { type: :key, code: "1" }
+      @layer_count = 1
+    in { type: :key, code: "2" }
+      @layer_count = 2
+    in { type: :key, code: " " }
+      @swapped = !@swapped
+    in { type: :key, code: "c" }
+      @clear = !@clear
+    else
+      nil
+    end
+  end
+end
+
+WidgetOverlayDemo.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_popup_demo/README.md

@@ -0,0 +1,36 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Popup (Clear) Widget Example
+
+Demonstrates how to render opaque overlays on top of content.
+
+Terminal renders are additive. If you draw a new widget over an old one, the background colors might mix if not handled correctly. The `Clear` widget resets the area to default (usually transparent/black) to ensure a clean canvas for popups.
+
+## Features Demonstrated
+
+- **The `Clear` Widget**: Printing spaces over an area to "erase" what was underneath.
+- **Centering**: Using `Layout` constraints to perfectly center a block on screen.
+- **Style Bleed**: showing what happens when you *don't* use `Clear` (background colors leak through).
+
+## Hotkeys
+
+- **Space**: Toggle Clear Widget (Observe the red background effect when disabled)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_popup_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Create a modal dialog (Confirm, Alert, Form).
+- Implement a dropdown menu that overlays other content.
+- Fix visual artifacts where old text shows through new widgets.
+
+![Demo](/doc/images/widget_popup_demo.png)

data/examples/widget_ratatui_logo_demo/README.md

@@ -0,0 +1,34 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Ratatui Logo Example
+
+Demonstrates branding with the official logo widget.
+
+A polished application often needs an "About" screen or a splash screen. This widget provides the standardized project branding.
+
+## Features Demonstrated
+
+- **RatatuiLogo Widget**: Renders the Ratatui ASCII art logo.
+- **Centering**: Techniques for centering fixed-size content in a fluid layout.
+
+## Hotkeys
+
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_ratatui_logo_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Create a splash screen.
+- Add an "About" modal to your application.
+- See how to center a widget both vertically and horizontally.
+
+![Demo](/doc/images/widget_ratatui_logo_demo.png)

data/examples/widget_ratatui_mascot_demo/README.md

@@ -0,0 +1,34 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Ratatui Mascot Example
+
+Demonstrates the project mascot widget for adding personality.
+
+Interfaces can feel clinical. A friendly mascot adds charm and brand identity to your terminal application.
+
+## Features Demonstrated
+
+- **RatatuiMascot Widget**: Renders the ASCII art mascot.
+- **Block Integration**: Wrapping the mascot in a bordered block title.
+
+## Hotkeys
+
+- **b**: Toggle Block Border (`block`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_ratatui_mascot_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Add visual flair to your UI.
+- Create a friendly empty state or success screen.
+
+![Demo](/doc/images/widget_ratatui_mascot_demo.png)

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_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_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)

data/examples/widget_rich_text/app.rb

@@ -12,6 +12,7 @@ require "ratatui_ruby"
 class WidgetRichText
   def initialize
     @scroll_pos = 0
+    @color_index = 0
   end
 
   def run
@@ -44,38 +45,52 @@ class WidgetRichText
   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
-          ),
-        ]
-      ),
+      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]
@@ -113,7 +128,11 @@ class WidgetRichText
           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: " 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),
           ]
         ),
       ],
@@ -128,6 +147,16 @@ class WidgetRichText
     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

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

@@ -1,4 +1,3 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>