ratatui_ruby 0.4.0 → 0.6.0

data/examples/{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 MapDemoApp
+class WidgetMapDemo
   include RatatuiRuby
 
   COLORS = [:black, :blue, :white, nil].freeze
@@ -15,40 +15,41 @@ class MapDemoApp
 
   # Returns a Canvas view for the map demo with the given circle radius.
   #
+  # +tui+:: The RatatuiRuby::Session instance.
   # +radius+:: The radius of the animated circle.
   # +marker+:: The marker type.
   # +background_color+:: The background color of the canvas.
   # +show_labels+:: Whether to show city labels.
-  def view(radius, marker = :braille, background_color = nil, show_labels: true)
+  def view(tui, radius, marker = :braille, background_color = nil, show_labels: true)
     shapes = [
-      Shape::Map.new(color: :green, resolution: :high),
-      Shape::Circle.new(x: 0.0, y: 0.0, radius:, color: :red),
-      Shape::Line.new(x1: 0.0, y1: 0.0, x2: 50.0, y2: 25.0, color: :yellow),
+      tui.shape_map(color: :green, resolution: :high),
+      tui.shape_circle(x: 0.0, y: 0.0, radius:, color: :red),
+      tui.shape_line(x1: 0.0, y1: 0.0, x2: 50.0, y2: 25.0, color: :yellow),
     ]
 
     if show_labels
       shapes += [
-        Shape::Label.new(x: -0.1, y: 51.5, text: "London", style: Style.new(fg: :cyan)),
-        Shape::Label.new(x: 139.7, y: 35.7, text: "Tokyo", style: Style.new(fg: :magenta)),
-        Shape::Label.new(x: -74.0, y: 40.7, text: "New York", style: Style.new(fg: :yellow)),
-        Shape::Label.new(x: -122.4, y: 37.8, text: "San Francisco", style: Style.new(fg: :blue)),
-        Shape::Label.new(x: 151.2, y: -33.9, text: "Sydney", style: Style.new(fg: :green)),
+        tui.shape_label(x: -0.1, y: 51.5, text: "London", style: tui.style(fg: :cyan)),
+        tui.shape_label(x: 139.7, y: 35.7, text: "Tokyo", style: tui.style(fg: :magenta)),
+        tui.shape_label(x: -74.0, y: 40.7, text: "New York", style: tui.style(fg: :yellow)),
+        tui.shape_label(x: -122.4, y: 37.8, text: "San Francisco", style: tui.style(fg: :blue)),
+        tui.shape_label(x: 151.2, y: -33.9, text: "Sydney", style: tui.style(fg: :green)),
       ]
     end
 
-    Canvas.new(
-      shapes: shapes,
+    tui.canvas(
+      shapes:,
       x_bounds: [-180.0, 180.0],
       y_bounds: [-90.0, 90.0],
-      marker: marker,
-      block: Block.new(title: "World Map ['b' bg, 'm' marker: #{marker}, 'l' labels: #{show_labels ? 'on' : 'off'}]", borders: :all),
-      background_color: background_color
+      marker:,
+      block: tui.block(title: "World Map ['b' bg, 'm' marker: #{marker}, 'l' labels: #{show_labels ? 'on' : 'off'}]", borders: :all),
+      background_color:
     )
   end
 
   # Runs the map demo loop.
   def run
-    RatatuiRuby.run do
+    RatatuiRuby.run do |tui|
       radius = 0.0
       direction = 1
       bg_index = 0
@@ -63,13 +64,15 @@ class MapDemoApp
         end
 
         # Define the view
-        v = view(radius, MARKERS[marker_index], COLORS[bg_index], show_labels:)
+        canvas = view(tui, radius, MARKERS[marker_index], COLORS[bg_index], show_labels:)
 
-        RatatuiRuby.draw(v)
+        tui.draw do |frame|
+          frame.render_widget(canvas, frame.area)
+        end
 
-        event = RatatuiRuby.poll_event
+        event = tui.poll_event
         case event
-        in {type: :key, code: "q"} | {type: :key, code: :ctrl_c}
+        in { type: :key, code: "q" } | { type: :key, code: :ctrl_c }
           break
         in type: :key, code: "b"
           bg_index = (bg_index + 1) % COLORS.size
@@ -87,4 +90,4 @@ class MapDemoApp
   end
 end
 
-MapDemoApp.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_popup_demo/app.rb

@@ -0,0 +1,104 @@
+# 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"
+
+# Popup Demo Example
+# Demonstrates the Clear widget for creating opaque popups.
+
+class WidgetPopupDemo
+  def initialize
+    @clear_enabled = false
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        tui.draw do |frame|
+          render(tui, frame)
+        end
+        break if handle_input(tui) == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def render(tui, frame)
+    area = frame.area
+
+    # 1. Background: Loud Red Background
+    # This demonstrates "Style Bleed" where the background color persists
+    # unless explicitly cleared or overwritten.
+    background = tui.paragraph(
+      text: "BACKGROUND RED " * 100,
+      style: tui.style(bg: :red, fg: :white),
+      wrap: true
+    )
+    frame.render_widget(background, area)
+
+    # 2. Popup Area Calculation
+    # Center the popup vertically and horizontally
+    vertical_layout = tui.layout_split(
+      area,
+      direction: :vertical,
+      constraints: [
+        tui.constraint_percentage(25),
+        tui.constraint_percentage(50), # 50% height
+        tui.constraint_percentage(25),
+      ]
+    )
+    popup_area_vertical = vertical_layout[1]
+
+    horizontal_layout = tui.layout_split(
+      popup_area_vertical,
+      direction: :horizontal,
+      constraints: [
+        tui.constraint_percentage(20),
+        tui.constraint_percentage(60), # 60% width
+        tui.constraint_percentage(20),
+      ]
+    )
+    popup_area = horizontal_layout[1]
+
+    # 3. Popup Content
+    # Without Clear, this will "inherit" the red background from underneath.
+    popup_text = if @clear_enabled
+      "✓ Clear is ENABLED\n\nResets background to default\n(Usually Black/Transparent)\n\nPress Space to toggle"
+    else
+      "✗ Clear is DISABLED\n\nStyle Bleed: Popup is RED!\n(Inherits background style)\n\nPress Space to toggle"
+    end
+
+    popup_content = tui.paragraph(
+      text: popup_text,
+      alignment: :center,
+      block: tui.block(
+        title: "Popup Demo (q to quit, space to toggle)",
+        borders: [:all]
+      )
+    )
+
+    # 4. Render Popup
+    if @clear_enabled
+      # With Clear: Resets the style in the popup area before rendering content
+      frame.render_widget(tui.clear, popup_area)
+    end
+
+    frame.render_widget(popup_content, popup_area)
+  end
+
+  private def handle_input(tui)
+    case tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    in type: :key, code: " "
+      @clear_enabled = !@clear_enabled
+    else
+      nil
+    end
+  end
+end
+
+WidgetPopupDemo.new.run if __FILE__ == $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
+
+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_logo_demo/app.rb

@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+
+# Demonstrates branding visualization with the official logo.
+#
+# Branding is important for identity. Users need to recognize the tools they use.
+#
+# This demo showcases the <tt>RatatuiLogo</tt> widget. It renders the logo in a centered layout.
+#
+# Use it to understand how to incorporate the project's visual identity into your terminal application.
+#
+# === Example
+#
+# Run the demo from the terminal:
+#
+#   ruby examples/widget_ratatui_logo_demo/app.rb
+#
+# rdoc-image:/doc/images/widget_ratatui_logo_demo.png
+class WidgetRatatuiLogoDemo
+  def run
+    RatatuiRuby.run do |tui|
+      loop do
+        render(tui)
+        break if handle_input(tui) == :quit
+      end
+    end
+  end
+
+  private def render(tui)
+    tui.draw do |frame|
+      # Layout
+      layout = tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          tui.constraint_fill(1), # Fill remaining space
+          tui.constraint_length(3),
+        ]
+      )
+
+      # Main Area
+      main_area = layout[0]
+
+      # Center the logo using nested Layouts
+      # Logo is roughly 47x8
+      # Vertical Center
+      v_center_layout = tui.layout_split(
+        main_area,
+        direction: :vertical,
+        flex: :center,
+        constraints: [tui.constraint_length(10)] # Height + margin
+      )
+
+      # Horizontal Center
+      h_center_layout = tui.layout_split(
+        v_center_layout[0],
+        direction: :horizontal,
+        flex: :center,
+        constraints: [tui.constraint_length(50)] # Width + margin
+      )
+
+      # Main content: The Logo
+      logo = RatatuiRuby::RatatuiLogo.new
+      frame.render_widget(logo, h_center_layout[0])
+
+      # Control Panel
+      control_area = layout[1]
+
+      control_text = tui.text_line(spans: [
+        tui.text_span(content: "q", style: tui.style(modifiers: [:bold, :underlined])),
+        tui.text_span(content: ": Quit"),
+      ])
+
+      control_panel = tui.paragraph(
+        text: [control_text],
+        block: tui.block(
+          title: "Controls",
+          borders: [:top],
+          style: tui.style(fg: :dark_gray)
+        )
+      )
+
+      frame.render_widget(control_panel, control_area)
+    end
+  end
+
+  private def handle_input(tui)
+    case tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+    else
+      nil
+    end
+  end
+end
+
+WidgetRatatuiLogoDemo.new.run if __FILE__ == $0

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)