ratatui_ruby 0.4.0 → 0.5.0

data/examples/widget_list_styles/app.rb

@@ -0,0 +1,141 @@
+# 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"
+
+# Styled List Example
+# Demonstrates advanced styling options for the List widget.
+class WidgetListStyles
+  attr_reader :selected_index, :highlight_spacing
+
+  def initialize
+    @items = ["Item 1", "Item 2", "Item 3"]
+    @selected_index = nil
+
+    @directions = [
+      { name: "Top to Bottom", direction: :top_to_bottom },
+      { name: "Bottom to Top", direction: :bottom_to_top },
+    ]
+    @direction_index = 0
+
+    @highlight_spacings = [
+      { name: "When Selected", spacing: :when_selected },
+      { name: "Always", spacing: :always },
+      { name: "Never", spacing: :never },
+    ]
+    @highlight_spacing_index = 0
+
+    @repeat_modes = [
+      { name: "Off", repeat: false },
+      { name: "On", repeat: true },
+    ]
+    @repeat_index = 0
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+      @hotkey_style = @tui.style(modifiers: [:bold, :underlined])
+
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    end
+  end
+
+  private def render
+    selection_label = @selected_index.nil? ? "none" : @selected_index.to_s
+    direction_config = @directions[@direction_index]
+    spacing_config = @highlight_spacings[@highlight_spacing_index]
+    repeat_config = @repeat_modes[@repeat_index]
+
+    @tui.draw do |frame|
+      # Split into main content and control panel
+      main_area, control_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(5),
+        ]
+      )
+
+      # Render list
+      main_list = @tui.list(
+        items: @items,
+        selected_index: @selected_index,
+        style: @tui.style(fg: :white, bg: :black),
+        highlight_style: @tui.style(fg: :blue, bg: :white, modifiers: [:bold]),
+        highlight_symbol: ">> ",
+        repeat_highlight_symbol: repeat_config[:repeat],
+        highlight_spacing: spacing_config[:spacing],
+        direction: direction_config[:direction],
+        block: @tui.block(
+          title: "Items",
+          borders: [:all]
+        )
+      )
+      frame.render_widget(main_list, main_area)
+
+      # Render control panel
+      control_panel = @tui.block(
+        title: "Controls",
+        borders: [:all],
+        children: [
+          @tui.paragraph(
+            text: [
+              @tui.text_line(spans: [
+                @tui.text_span(content: "↑/↓", style: @hotkey_style),
+                @tui.text_span(content: ": Select (#{selection_label})  "),
+                @tui.text_span(content: "x", style: @hotkey_style),
+                @tui.text_span(content: ": Toggle Selection  "),
+                @tui.text_span(content: "q", style: @hotkey_style),
+                @tui.text_span(content: ": Quit"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "d", style: @hotkey_style),
+                @tui.text_span(content: ": Direction (#{direction_config[:name]})  "),
+                @tui.text_span(content: "s", style: @hotkey_style),
+                @tui.text_span(content: ": Spacing (#{spacing_config[:name]})"),
+              ]),
+              @tui.text_line(spans: [
+                @tui.text_span(content: "r", style: @hotkey_style),
+                @tui.text_span(content: ": Repeat Symbol (#{repeat_config[:name]})"),
+              ]),
+            ]
+          ),
+        ]
+      )
+      frame.render_widget(control_panel, control_area)
+    end
+  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: "up"
+      @selected_index = (@selected_index || 0) - 1
+      @selected_index = @items.size - 1 if @selected_index.negative?
+    in type: :key, code: "down"
+      @selected_index = ((@selected_index || -1) + 1) % @items.size
+    in type: :key, code: "d"
+      @direction_index = (@direction_index + 1) % @directions.size
+    in type: :key, code: "s"
+      @highlight_spacing_index = (@highlight_spacing_index + 1) % @highlight_spacings.size
+    in type: :key, code: "r"
+      @repeat_index = (@repeat_index + 1) % @repeat_modes.size
+    in type: :key, code: "x"
+      @selected_index = @selected_index.nil? ? 0 : nil
+    else
+      nil
+    end
+  end
+end
+
+WidgetListStyles.new.run if __FILE__ == $PROGRAM_NAME

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/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/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/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