ratatui_ruby 0.5.0 → 0.7.0

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
+
+[![widget_ratatui_logo_demo](../../doc/images/widget_ratatui_logo_demo.png)](app.rb)
+
+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.

data/examples/widget_ratatui_logo_demo/app.rb

@@ -66,7 +66,7 @@ class WidgetRatatuiLogoDemo
       )
 
       # Main content: The Logo
-      logo = RatatuiRuby::RatatuiLogo.new
+      logo = RatatuiRuby::Widgets::RatatuiLogo.new
       frame.render_widget(logo, h_center_layout[0])
 
       # Control Panel

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
+
+[![widget_ratatui_mascot_demo](../../doc/images/widget_ratatui_mascot_demo.png)](app.rb)
+
+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.

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
+
+[![widget_rect](../../doc/images/widget_rect.png)](app.rb)
+
+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.

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
+
+[![widget_render](../../doc/images/widget_render.png)](app.rb)
+
+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.

data/examples/widget_render/app.rb

@@ -21,7 +21,7 @@ class DiagonalWidget
         area.x + i,
         area.y + i,
         "\\",
-        RatatuiRuby::Style.new(fg: :red, modifiers: [:bold])
+        RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:bold])
       )
     end
   end
@@ -47,7 +47,7 @@ class CheckerboardWidget
           area.x + col,
           area.y + row,
           @char,
-          RatatuiRuby::Style.new(fg: :cyan)
+          RatatuiRuby::Style::Style.new(fg: :cyan)
         )
       end
     end
@@ -63,7 +63,7 @@ end
 class BorderWidget
   def render(area)
     result = []
-    style = RatatuiRuby::Style.new(fg: :green)
+    style = RatatuiRuby::Style::Style.new(fg: :green)
 
     # Top and bottom
     (0...area.width).each do |x| # rubocop:disable Lint/AmbiguousRange

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
+
+[![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
+
+```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.

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
+
+[![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
+
+```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.

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>

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
+
+[![widget_scrollbar_demo](../../doc/images/widget_scrollbar_demo.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
+
+```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.

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
+
+[![widget_sparkline_demo](../../doc/images/widget_sparkline_demo.png)](app.rb)
+
+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.

data/examples/widget_sparkline_demo/app.rb

@@ -57,7 +57,8 @@ class WidgetSparklineDemo
         data: [1, 5, 1, 8, 1, 6, 1, 9, 1, 7, 1, 10],
       },
     ]
-    @data_index = 0
+    @data_index = 2
+    srand(12345) # Ensure reproducible "Random" data for snapshots
 
     @directions = [
       { name: "Left to Right", direction: :left_to_right },
@@ -72,7 +73,7 @@ class WidgetSparklineDemo
       { name: "Cyan", style: @tui.style(fg: :cyan) },
       { name: "Magenta", style: @tui.style(fg: :magenta) },
     ]
-    @style_index = 0
+    @style_index = 3
 
     @absent_symbols = [
       { name: "None", symbol: nil },
@@ -89,7 +90,7 @@ class WidgetSparklineDemo
       { name: "Dim Red", style: @tui.style(fg: :red, modifiers: [:dim]) },
       { name: "Dim Yellow", style: @tui.style(fg: :yellow, modifiers: [:dim]) },
     ]
-    @absent_style_index = 0
+    @absent_style_index = 2
 
     @bar_sets = [
       { name: "Default (Block)", set: nil },

data/examples/widget_style_colors/README.md

@@ -0,0 +1,34 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Style Colors Example
+
+[![widget_style_colors](../../doc/images/widget_style_colors.png)](app.rb)
+
+Demonstrates high-fidelity color support.
+
+Terminals support millions of colors. This example generates a mathematically precise HSL gradient to prove the rendering engine's color fidelity.
+
+## Features Demonstrated
+
+- **HSL to RGB Conversion**: generating smooth color gradients programmatically.
+- **TrueColor Support**: Rendering arbitrary HEX colors.
+
+## Hotkeys
+
+- **q** / **Ctrl+c**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_style_colors/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Create meaningful heatmaps.
+- Generate color palettes dynamically.
+- Test your terminal's color support capabilities.

data/examples/widget_table_demo/README.md

@@ -0,0 +1,48 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Table Widget Example
+
+[![widget_table_demo](../../doc/images/widget_table_demo.png)](app.rb)
+
+Demonstrates advanced options for the `Table` widget, including selection, row-level highlighting, and column-level highlighting.
+
+Data grids are complex. Users expect to navigate them with keys, select rows, and clearly see which cell is active. The `Table` widget provides these features out of the box efficiently.
+
+## Features Demonstrated
+
+- **Selection State**: Managing `selected_row` and `selected_column` to track user focus.
+- **Complex Highlighting**:
+    - **Row**: Highlight the entire active row.
+    - **Highlight Symbol:** Adding a visual indicator (like `> `) to the selected row.
+- **Spacing:** Adjusting `column_spacing` and `highlight_spacing` to control layout density.
+- **Flex Layout:** Switching between different column distribution modes (`legacy`, `start`, `space_between`, etc.).
+- **Offset Control:** Manually controlling the scroll position using `offset`.
+
+## Hotkeys
+
+- **Arrows (↑/↓)**: Navigate Rows (`selected_row`)
+- **Arrows (←/→)**: Navigate Columns (`selected_column`)
+- **x**: Toggle Row Selection (`selected_row` = nil)
+- **s**: Cycle Table Style (`style`)
+- **p**: Cycle Spacing (`highlight_spacing`)
+- **c**: Toggle Column Highlight (`column_highlight_style`)
+- **z**: Toggle Cell Highlight (`cell_highlight_style`)
+- **o**: Cycle Offset Mode (`offset`)
+- **f**: Cycle Flex Mode (`flex`)
+- **q**: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_table_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Build a file explorer or process list.
+- Create a data-heavy dashboard.
+- Handle conflicting style requirements (e.g., "Highlight this row, but make this error cell red").