ratatui_ruby 0.5.0 → 0.7.0

data/examples/widget_list_demo/app.rb

@@ -5,6 +5,7 @@
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
+require "faker" # Use Faker for large, realistic datasets
 
 # Demonstrates a selectable list of items with interactive attribute cycling.
 #
@@ -24,111 +25,18 @@ require "ratatui_ruby"
 class WidgetListDemo
   # Initializes the demo with example data and default configuration.
   def initialize
-    @selected_index = nil
+    Faker::Config.random = Random.new(12345)
+    @selected_index = 6 # Start at C# to avoid highlighting the rich text examples
+    @tui_for_setup = nil
 
     @item_sets = [
-      {
-        name: "Large List",
-        items: (1..200).map { |i| "Item #{i}" },
-      },
-      {
-        name: "Colors",
-        items: [
-          "Red",
-          "Orange",
-          "Yellow",
-          "Green",
-          "Cyan",
-          "Blue",
-          "Indigo",
-          "Violet",
-          "Scarlet",
-          "Crimson",
-          "Maroon",
-          "Brown",
-          "Tan",
-          "Beige",
-          "Khaki",
-          "Gold",
-          "Silver",
-          "White",
-          "Gray",
-          "Black",
-          "Pink",
-          "Magenta",
-          "Turquoise",
-          "Teal",
-          "Coral",
-          "Salmon",
-          "Peach",
-          "Lavender",
-          "Lilac",
-          "Olive",
-          "Lime",
-          "Navy",
-          "Charcoal",
-          "Ivory",
-          "Azure",
-        ],
-      },
-      {
-        name: "Fruits",
-        items: [
-          "Apple",
-          "Apricot",
-          "Avocado",
-          "Banana",
-          "Blueberry",
-          "Blackberry",
-          "Cherry",
-          "Cranberry",
-          "Cucumber",
-          "Date",
-          "Dragonfruit",
-          "Elderberry",
-          "Fig",
-          "Grape",
-          "Grapefruit",
-          "Guava",
-          "Honeydew",
-          "Huckleberry",
-          "Jackfruit",
-          "Kiwi",
-          "Kumquat",
-          "Lemon",
-          "Lime",
-          "Lychee",
-          "Mango",
-          "Melon",
-          "Mulberry",
-          "Nectarine",
-          "Olive",
-          "Orange",
-          "Papaya",
-          "Passion Fruit",
-          "Peach",
-          "Pear",
-          "Persimmon",
-          "Pineapple",
-          "Plum",
-          "Pomegranate",
-          "Prune",
-          "Rambutan",
-          "Raspberry",
-          "Starfruit",
-          "Strawberry",
-          "Tangerine",
-          "Watermelon",
-          "Ugli Fruit",
-        ],
-      },
       {
         name: "Programming",
         items: [
-          "Ruby",
-          "Rust",
-          "Python",
-          "JavaScript",
+          :ruby_styled, # Will be replaced with rich text in run()
+          :rust_styled, # Will be replaced with rich text in run()
+          :python_styled, # Will be replaced with rich text in run()
+          :javascript_styled, # Will be replaced with rich text in run()
           "Go",
           "C++",
           "C#",
@@ -175,6 +83,24 @@ class WidgetListDemo
           "BASIC",
         ],
       },
+      {
+        name: "Large List",
+        items: (1..200).map { |i| "Item #{i}" },
+      },
+      {
+        name: "Colors",
+        items: begin
+          Faker::Color.unique.clear
+          Array.new(100) { Faker::Color.color_name }
+        end,
+      },
+      {
+        name: "Fruits",
+        items: begin
+          Faker::Food.unique.clear
+          Array.new(100) { Faker::Food.fruits }
+        end,
+      },
     ]
     @item_set_index = 0
 
@@ -192,7 +118,7 @@ class WidgetListDemo
       { name: "Always", spacing: :always },
       { name: "Never", spacing: :never },
     ]
-    @highlight_spacing_index = 0
+    @highlight_spacing_index = 1
 
     @repeat_modes = [
       { name: "Off", repeat: false },
@@ -205,7 +131,15 @@ class WidgetListDemo
       { name: "1 item", padding: 1 },
       { name: "2 items", padding: 2 },
     ]
-    @scroll_padding_index = 0
+    @scroll_padding_index = 1
+
+    # Offset mode configurations to demonstrate offset + selection interaction
+    @offset_modes = [
+      { name: "Auto (No Offset)", offset: nil, allow_selection: true },
+      { name: "Offset Only", offset: 10, allow_selection: false },
+      { name: "Selection + Offset (Conflict)", offset: 0, allow_selection: true },
+    ]
+    @offset_mode_index = 0
   end
 
   # Runs the demo application.
@@ -214,8 +148,45 @@ class WidgetListDemo
   def run
     RatatuiRuby.run do |tui|
       @tui = tui
+
+      # Create rich text for "Ruby" - each letter with a different red style
+      ruby_line = @tui.text_line(spans: [
+        @tui.text_span(content: "R", style: @tui.style(fg: :red, modifiers: [:underlined])),
+        @tui.text_span(content: "u", style: @tui.style(fg: :light_red, modifiers: [:bold])),
+        @tui.text_span(content: "b", style: @tui.style(fg: :red, modifiers: [:italic])),
+        @tui.text_span(content: "y", style: @tui.style(fg: :light_red, modifiers: [:reversed])),
+      ])
+
+      # Create rich text for "Rust" - single styled Span
+      rust_span = @tui.text_span(
+        content: "Rust",
+        style: @tui.style(fg: :magenta, modifiers: [:bold, :underlined])
+      )
+
+      # Create ListItem for "Python" - demonstrates content + row background
+      python_item = @tui.list_item(
+        content: @tui.text_span(content: "Python", style: @tui.style(fg: :yellow)),
+        style: @tui.style(bg: :dark_gray)
+      )
+
+      # Create ListItem for "JavaScript" - demonstrates styled text with row background
+      javascript_item = @tui.list_item(
+        content: @tui.text_line(spans: [
+          @tui.text_span(content: "Java", style: @tui.style(fg: :yellow, modifiers: [:bold])),
+          @tui.text_span(content: "Script", style: @tui.style(fg: :light_yellow, modifiers: [:italic])),
+        ]),
+        style: @tui.style(bg: :blue)
+      )
+
+      # Replace the styled placeholders
+      @item_sets[0][:items][0] = ruby_line
+      @item_sets[0][:items][1] = rust_span
+      @item_sets[0][:items][2] = python_item
+      @item_sets[0][:items][3] = javascript_item
+
       # Initialize styles that require @tui
       @highlight_styles = [
+        { name: "Blue on White Bold", style: @tui.style(fg: :blue, bg: :white, modifiers: [:bold]) },
         { name: "Blue Bold", style: @tui.style(fg: :blue, modifiers: [:bold]) },
         { name: "Yellow on Black", style: @tui.style(fg: :yellow, bg: :black) },
         { name: "Green Italic", style: @tui.style(fg: :green, modifiers: [:italic]) },
@@ -245,7 +216,6 @@ class WidgetListDemo
   # :nodoc:
   private def render
     items = @item_sets[@item_set_index][:items]
-    selection_label = @selected_index.nil? ? "none" : @selected_index.to_s
     direction_config = @direction_configs[@direction_index]
     spacing_config = @highlight_spacing_configs[@highlight_spacing_index]
     repeat_config = @repeat_modes[@repeat_index]
@@ -253,6 +223,13 @@ class WidgetListDemo
     highlight_symbol = @highlight_symbol_names[@highlight_symbol_index]
     base_style_config = @base_styles[@base_style_index]
     scroll_padding_config = @scroll_padding_configs[@scroll_padding_index]
+    offset_mode_config = @offset_modes[@offset_mode_index]
+
+    # Determine selection/offset based on mode
+    effective_selection = offset_mode_config[:allow_selection] ? @selected_index : nil
+    effective_offset = offset_mode_config[:offset]
+    selection_label = effective_selection.nil? ? "none" : effective_selection.to_s
+    offset_label = effective_offset.nil? ? "auto" : effective_offset.to_s
 
     @tui.draw do |frame|
       # Split into main content and control panel
@@ -261,7 +238,7 @@ class WidgetListDemo
         direction: :vertical,
         constraints: [
           @tui.constraint_fill(1),
-          @tui.constraint_length(7),
+          @tui.constraint_length(8),
         ]
       )
 
@@ -282,7 +259,8 @@ class WidgetListDemo
       # Render list
       list = @tui.list(
         items:,
-        selected_index: @selected_index,
+        selected_index: effective_selection,
+        offset: effective_offset,
         style: base_style_config[:style],
         highlight_style: highlight_style_config[:style],
         highlight_symbol:,
@@ -291,7 +269,7 @@ class WidgetListDemo
         direction: direction_config[:direction],
         scroll_padding: scroll_padding_config[:padding],
         block: @tui.block(
-          title: "#{@item_sets[@item_set_index][:name]} (Selection: #{selection_label})",
+          title: "#{@item_sets[@item_set_index][:name]} | Sel: #{selection_label} | Offset: #{offset_label}",
           borders: [:all]
         )
       )
@@ -330,7 +308,11 @@ class WidgetListDemo
                 @tui.text_span(content: "b", style: @hotkey_style),
                 @tui.text_span(content: ": Base (#{base_style_config[:name]})  "),
                 @tui.text_span(content: "r", style: @hotkey_style),
-                @tui.text_span(content: ": Repeat (#{repeat_config[:name]})  "),
+                @tui.text_span(content: ": Repeat (#{repeat_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "o", style: @hotkey_style),
+                @tui.text_span(content: ": Offset Mode (#{offset_mode_config[:name]})  "),
                 @tui.text_span(content: "q", style: @hotkey_style),
                 @tui.text_span(content: ": Quit"),
               ]),
@@ -373,6 +355,8 @@ class WidgetListDemo
       @repeat_index = (@repeat_index + 1) % @repeat_modes.size
     in type: :key, code: "p"
       @scroll_padding_index = (@scroll_padding_index + 1) % @scroll_padding_configs.size
+    in type: :key, code: "o"
+      @offset_mode_index = (@offset_mode_index + 1) % @offset_modes.size
     else
       nil
     end

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

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

@@ -7,15 +7,15 @@ $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
-  include RatatuiRuby
+class WidgetMapDemo
+  include RatatuiRuby::Widgets
 
   COLORS = [:black, :blue, :white, nil].freeze
   MARKERS = [:braille, :half_block, :dot, :block, :bar, :quadrant, :sextant, :octant].freeze
 
   # Returns a Canvas view for the map demo with the given circle radius.
   #
-  # +tui+:: The RatatuiRuby::Session instance.
+  # +tui+:: The RatatuiRuby::TUI instance.
   # +radius+:: The radius of the animated circle.
   # +marker+:: The marker type.
   # +background_color+:: The background color of the canvas.
@@ -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/README.md

@@ -0,0 +1,36 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Overlay Widget Demo
+
+[![Overlay Demo](../../doc/images/widget_overlay_demo.png)](app.rb)
+
+This example demonstrates the `Overlay` composition pattern for layering widgets with depth. Modals, notifications, and floating panels all require stacking widgets on top of each other.
+
+## Key Concepts
+
+- **Layer Composition:** Rendering widgets in order creates visual depth — later renders appear "on top."
+- **Clear Widget:** Using `tui.clear` before rendering a modal erases the background, preventing content bleed-through.
+- **Dynamic Layer Control:** Toggle the number of visible overlay layers at runtime.
+- **Layer Ordering:** Swap which overlay appears in front to demonstrate z-ordering.
+
+## Hotkeys
+
+- `0`/`1`/`2`: Set number of visible overlay layers
+- `space`: Swap overlay order (which modal is on top)
+- `c`: Toggle Clear widget (on/off)
+- `q`: Quit
+
+## Usage
+
+```bash
+ruby examples/widget_overlay_demo/app.rb
+```
+
+## Learning Outcomes
+
+Use this example if you need to...
+- Build modal dialogs or confirmation popups.
+- Layer notifications over existing content.
+- Understand the Clear widget's role in opaque overlays.

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