ratatui_ruby 1.0.0 → 1.0.1

data/examples/widget_map/README.md

@@ -1,48 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Map (World Map, Canvas) Example
-
-[![widget_map](../../doc/images/widget_map.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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_map/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)

data/examples/widget_map/app.rb

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$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 WidgetMap
-  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::TUI 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(tui, radius, marker = :braille, background_color = nil, show_labels: true)
-    shapes = [
-      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 += [
-        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
-
-    tui.canvas(
-      shapes:,
-      x_bounds: [-180.0, 180.0],
-      y_bounds: [-90.0, 90.0],
-      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 |tui|
-      radius = 0.0
-      direction = 1
-      bg_index = 0
-      marker_index = 0
-      show_labels = true
-
-      loop do
-        # Animate the circle radius
-        radius += 0.5 * direction
-        if radius > 10.0 || radius < 0.0
-          direction *= -1
-        end
-
-        # Define the view
-        canvas = view(tui, radius, MARKERS[marker_index], COLORS[bg_index], show_labels:)
-
-        tui.draw do |frame|
-          frame.render_widget(canvas, frame.area)
-        end
-
-        event = tui.poll_event
-        case event
-        in { type: :key, code: "q" } | { type: :key, code: :ctrl_c }
-          break
-        in type: :key, code: "b"
-          bg_index = (bg_index + 1) % COLORS.size
-        in type: :key, code: "m"
-          marker_index = (marker_index + 1) % MARKERS.size
-        in type: :key, code: "l"
-          show_labels = !show_labels
-        else
-          # Ignore other events
-        end
-
-        sleep 0.05
-      end
-    end
-  end
-end
-
-WidgetMap.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_overlay/README.md

@@ -1,45 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-# Overlay Example
-
-[![](../../doc/images/widget_overlay.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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_overlay/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)

data/examples/widget_overlay/app.rb

@@ -1,250 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$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 Example
-# Demonstrates the Overlay widget for layering widgets with depth.
-class WidgetOverlay
-  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
-
-WidgetOverlay.new.run if __FILE__ == $PROGRAM_NAME

data/examples/widget_popup/README.md

@@ -1,45 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Clear (Popup, Modal) Example
-
-[![widget_popup](../../doc/images/widget_popup.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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_popup/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)

data/examples/widget_popup/app.rb

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-require "ratatui_ruby"
-
-# Popup Example
-# Demonstrates the Clear widget for creating opaque popups.
-
-class WidgetPopup
-  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 (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
-
-WidgetPopup.new.run if __FILE__ == $0

data/examples/widget_ratatui_logo/README.md

@@ -1,43 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Ratatui Logo Example
-
-[![widget_ratatui_logo](../../doc/images/widget_ratatui_logo.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
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_ratatui_logo/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## 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.
-
-[Read the source code →](app.rb)