ratatui_ruby 0.3.1 → 0.4.0

data/examples/map_demo/app.rb

@@ -0,0 +1,90 @@
+# 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"
+
+# An example of the Canvas widget showing a world map and animated shapes.
+class MapDemoApp
+  include RatatuiRuby
+
+  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.
+  #
+  # +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)
+    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),
+    ]
+
+    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)),
+      ]
+    end
+
+    Canvas.new(
+      shapes: 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
+    )
+  end
+
+  # Runs the map demo loop.
+  def run
+    RatatuiRuby.run do
+      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
+        v = view(radius, MARKERS[marker_index], COLORS[bg_index], show_labels:)
+
+        RatatuiRuby.draw(v)
+
+        event = RatatuiRuby.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
+
+MapDemoApp.new.run if __FILE__ == $PROGRAM_NAME

data/examples/map_demo/app.rbs

@@ -0,0 +1,7 @@
+class MapDemoApp
+  # @public
+  def self.new: () -> MapDemoApp
+
+  # @public
+  def run: () -> void
+end

data/examples/map_demo/test_app.rb

@@ -0,0 +1,149 @@
+# 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"
+require "ratatui_ruby/test_helper"
+require "minitest/autorun"
+require "minitest/mock"
+require_relative "app"
+
+class TestMapDemoApp < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def setup
+    @app = MapDemoApp.new
+  end
+
+  def test_map_demo_renders
+    with_test_terminal do
+      # Queue events: turn off labels so buffer matches original, then quit
+      inject_keys("l", "q")
+
+      # Stub sleep to speed up test
+      @app.stub :sleep, nil do
+        @app.run
+      end
+
+      # Verify the buffer content reflects the rendered map (with labels off)
+      expected_buffer = [
+        "┌World Map ['b' bg, 'm' marker: braille, 'l' labels: off]──────────────────────┐",
+        "│                     ⣀⢀⣀⣀⡀   ⢀⣀⡀ ⡀                                            │",
+        "│            ⢠⣤⣰⣦⣶⣶⣿⣭⣿⣣⠶⠶⣿⣉⣉⠉⠉⠁  ⠁⠉⢽⠎⠁    ⠲⠶⠶⠖   ⠐⠛⢃⡀⣀⢤   ⢀⣐⣋⣷⠶⡤⣀    ⣀⡀⣀⡀      │",
+        "│⢖⡀⡀⣤⡖⠒⠒⠤⠤⠤⠤⠶⠿⠿⣿⣹⢿⣿⣿⢿⣭⣽⣿⡒⣦⣀⠘⣷⠄  ⢀⡀⢼⣏⢀      ⡠⠤⠒⠶⡤⢀⣄⡀⢻⠯⠤⢾⣻⡗⠛⠉    ⠈⠉⠈⠈⠙⠒⠚⠋ ⠒⠐⠦⠤⠤⠤⠶│",
+        "│⠉⠉⠻⣿⣃⣀⣤⡤⣄⣀⡀       ⢠⠒⠛⠳⡟⠳⣿⣏ ⠙⠦⠴⠋⠁ ⠈⠛⠋⠁⢀⡀ ⣖⡉⢰⢾⣥⡄⠙⠉⠁     ⠈              ⢀⣀⣀⡠⣤⣦⢤⠤⠛│",
+        "│   ⠒⠛⠉⠁   ⠿⣄⡀      ⠉⠓⢖⠎ ⢀⣘⣲⡄        ⠰⣾⣟⣄⠼⠛⠟⠚⠁                       ⠺⣶  ⢪⠜⠁   │",
+        "│           ⠈⡟          ⢸⠭⠿⠛⠛        ⢀⡤⣿⢀⣠⣴⣆⡀⢀⣴⣶⢆ ⡶⣆               ⢀⣀⡔⣽⡅       │",
+        "│            ⠳⣀       ⢀⣺⠉            ⠘⣧⢴⠧⠼⡿⠟⠻⣿⢭⣬⠉ ⠸⠿             ⢺⠟⣿⣠⣶⡟        │",
+        "│             ⠘⢿⣄  ⡔⠒⠒⣿⡄            ⢀⡼    ⠈⠙⠋⠉⠛⣿⡀ ⢶⣤⣄⣀⡀          ⢠⡇⠈⠋          │",
+        "│    ⠐⠦        ⠈⠉⢧⣘⢆⣴⡞⠛⣷⣤⣄          ⣯          ⣸⣷⡊⠉⣉⡽ ⠙⢲ ⢀⡴⠻⣄ ⢰⣶⠚⢙⡁            │",
+        "│                 ⠈⠉⠛⢯⣇⣠⣴⢤⣤⡀        ⢧⡀      ⡠⠔⠊ ⠙⠷⢮⠅   ⠈⣇⣏  ⠉⣷⢄⠵ ⣸⣷⡄           │",
+        "│                     ⢉⡇   ⠙⠲⡄       ⠙⠒⢒⣊⡲⡔⠉     ⣀⠎     ⠈⠋  ⠰⡿⡆⣠⠔⣗⣙⣣           │",
+        "│                     ⢼      ⠉⠓⠲⣄      ⠈⠁⠈⢢     ⡼⠁           ⠘⢽⣝⣒⣻⡯⡛⢻⣮⢒⣦⡶⣄⡀    │",
+        "│⡀                    ⠈⢢⡀      ⢰⠃         ⢸     ⢹⢀⣴             ⠉⠉⣙⣥⠖⣎⣽⡌⠃ ⠙⢀⡀ ⢀│",
+        "│⠁                      ⢸    ⢀⣀⠏          ⠸⡄   ⣲⠁⡝⡞             ⣤⠖⠋  ⠈⠁⠑⣆  ⠶⠁ ⠉│",
+        "│                       ⢸   ⢀⠞             ⢳  ⡰⠃ ⠉⠁             ⢹ ⢀⣀⣀⢀  ⢸⠆     │",
+        "│                       ⡎⢀⣠⠽⠉              ⠈⠉⠉                  ⠈⠉⠉ ⠈⠛⠦⣤⠎    ⣷⡄│",
+        "│                      ⢸⠇⢴⠁                           ⢀⡀               ⠛   ⠰⠾⠋ │",
+        "│                      ⠘⠶⠧⠐⠛                          ⠈⠁                       │",
+        "│                        ⢀⣠⡤                       ⣀⡀         ⡀ ⣀    ⡀         │",
+        "│         ⢀⣀⣀⣀⣀⣀⡀⢠⣤⣄⣀⣀⣀⣠⣴⡿⢳         ⣀⡤⠤⠤⠤⠔⠶⠖⠲⠤⠒⠒⠒⠋⠉⠁⠉⠉⠹⠶⠒⠋⠉⠉⠉⠉⠈⠉⠈⠉⠉⠉⠉⠉⠉⠉⠒⠒⠲⢤⣤  │",
+        "│   ⠰⠶⣶⣶⠏⠉⠉  ⠉ ⠈⠉⠉⠁    ⠶⢞⣩⣥⡄⣤⣶⣶⣀⣶⡶⠉⠉⠉                                     ⣠⣿   │",
+        "│⠉⠉⠉⠉⠒⠘⠙⠓⠃                 ⠉                                               ⠈⠁⠉⠉│",
+        "└──────────────────────────────────────────────────────────────────────────────┘",
+      ]
+
+      expected_buffer.each_with_index do |line, i|
+        assert_equal line, buffer_content[i], "Line #{i} should match"
+      end
+
+      # Verify the background color is set on the view (Unit test of the view method)
+      view = @app.view(0.0, :braille, nil)
+      assert_nil view.background_color
+
+      # Verify labels are included in the shapes (default show_labels: true)
+      label_shapes = view.shapes.select { |s| s.is_a?(RatatuiRuby::Shape::Label) }
+      assert_equal 5, label_shapes.size, "Should have 5 city labels"
+      assert label_shapes.any? { |l| l.text == "London" }, "Should have London label"
+      assert label_shapes.any? { |l| l.text == "Tokyo" }, "Should have Tokyo label"
+    end
+  end
+
+  def test_labels_visible
+    with_test_terminal do
+      # Don't toggle labels - they're on by default
+      inject_keys("q")
+      @app.stub :sleep, nil do
+        @app.run
+      end
+      # Labels should be visible - check for a city name in the buffer
+      buffer_text = buffer_content.join
+      assert_includes buffer_text, "London", "London label should be visible"
+    end
+  end
+
+  def test_labels_toggle
+    with_test_terminal do
+      inject_keys("l", "q")
+      @app.stub :sleep, nil do
+        @app.run
+      end
+      # After pressing 'l', labels should be off - check title
+      assert_includes buffer_content[0], "labels: off"
+    end
+  end
+
+  def test_background_default
+    with_test_terminal(timeout: 5) do
+      inject_keys("q")
+      @app.stub :sleep, nil do
+        @app.run
+      end
+      # View is roughly at (1,1) to (18,8) inside borders. (10, 5) is safely inside.
+      assert_cell_style(10, 5, bg: :black)
+    end
+  end
+
+  def test_background_blue
+    with_test_terminal(timeout: 5) do
+      inject_keys("b", "q")
+      @app.stub :sleep, nil do
+        @app.run
+      end
+      assert_cell_style(10, 5, bg: :blue)
+    end
+  end
+
+  def test_background_white
+    with_test_terminal(timeout: 5) do
+      inject_keys("b", "b", "q")
+      @app.stub :sleep, nil do
+        @app.run
+      end
+      assert_cell_style(10, 5, bg: :white)
+    end
+  end
+
+  def test_background_transparent
+    with_test_terminal(timeout: 5) do
+      inject_keys("b", "b", "b", "q")
+      @app.stub :sleep, nil do
+        @app.run
+      end
+      # Transparent typically means no bg color set on the cell
+      assert_cell_style(10, 5, bg: nil)
+    end
+  end
+
+  def test_quit
+    with_test_terminal do
+      inject_key(:q)
+      
+      @app.stub :sleep, nil do
+        @app.run
+      end
+    end
+  end
+end

data/examples/{mouse_events.rb → mouse_events/app.rb}

@@ -3,7 +3,7 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 
 class MouseEventsApp
@@ -14,17 +14,16 @@ class MouseEventsApp
   end
 
   def run
-    RatatuiRuby.init_terminal
-    begin
+    RatatuiRuby.run do
       loop do
         render
         break if handle_input == :quit
       end
-    ensure
-      RatatuiRuby.restore_terminal
     end
   end
 
+  private
+
   def render
     # Create a centered block with the mouse event details
     block = RatatuiRuby::Block.new(
@@ -35,7 +34,7 @@ class MouseEventsApp
 
     content = RatatuiRuby::Paragraph.new(
       text: "#{@message}\n#{@details}",
-      align: :center,
+      alignment: :center,
       block:
     )
 
@@ -61,32 +60,35 @@ class MouseEventsApp
     event = RatatuiRuby.poll_event
     return unless event
 
-    if event[:type] == :key && event[:code] == "q"
+    case event
+    in {type: :key, code: "q"} | {type: :key, code: "c", modifiers: ["ctrl"]}
       return :quit
-    end
-
-    if event[:type] == :mouse
+    in type: :mouse, kind:, button:, x:, y:, modifiers:
       @color = "green"
-      case event[:kind]
-      when :down
-        @message = "#{event[:button].to_s.capitalize} Click at [#{event[:x]}, #{event[:y]}]"
-        @details = "Modifiers: #{event[:modifiers].join(', ')}"
-      when :up
-        @message = "#{event[:button].to_s.capitalize} Release at [#{event[:x]}, #{event[:y]}]"
-        @details = "Modifiers: #{event[:modifiers].join(', ')}"
-      when :drag
-        @message = "Dragging #{event[:button].to_s.capitalize} Button at [#{event[:x]}, #{event[:y]}]"
-        @details = "Modifiers: #{event[:modifiers].join(', ')}"
-      when :moved
-        @message = "Mouse Moved to [#{event[:x]}, #{event[:y]}]"
-        @details = "Modifiers: #{event[:modifiers].join(', ')}"
-      when :scroll_down
+      case kind
+      when "down"
+        @message = "#{button.capitalize} Click at [#{x}, #{y}]"
+        @details = "Modifiers: #{modifiers.join(', ')}"
+      when "up"
+        @message = "#{button.capitalize} Release at [#{x}, #{y}]"
+        @details = "Modifiers: #{modifiers.join(', ')}"
+      when "drag"
+        @message = "Dragging #{button.capitalize} Button at [#{x}, #{y}]"
+        @details = "Modifiers: #{modifiers.join(', ')}"
+      when "moved"
+        @message = "Mouse Moved to [#{x}, #{y}]"
+        @details = "Modifiers: #{modifiers.join(', ')}"
+      when "scroll_down"
         @message = "Scrolled Down"
-        @details = "Position: [#{event[:x]}, #{event[:y]}]"
-      when :scroll_up
+        @details = "Position: [#{x}, #{y}]"
+      when "scroll_up"
         @message = "Scrolled Up"
-        @details = "Position: [#{event[:x]}, #{event[:y]}]"
+        @details = "Position: [#{x}, #{y}]"
+      else
+        nil
       end
+    else
+      nil
     end
     nil
   end

data/examples/mouse_events/app.rbs

@@ -0,0 +1,7 @@
+class MouseEventsApp
+  # @public
+  def self.new: () -> MouseEventsApp
+
+  # @public
+  def run: () -> void
+end

data/examples/mouse_events/test_app.rb

@@ -0,0 +1,53 @@
+# 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"
+require "ratatui_ruby/test_helper"
+require "minitest/autorun"
+require_relative "app"
+
+class TestMouseEvents < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def setup
+    @app = MouseEventsApp.new
+  end
+
+  def test_initial_render
+    with_test_terminal do
+      inject_key(:q)
+      @app.run
+      
+      content = buffer_content.join("\n")
+      assert_includes content, "Mouse Event Plumbing"
+      assert_includes content, "Waiting for Mouse..."
+    end
+  end
+
+  def test_mouse_click
+    with_test_terminal do
+      # Click left button at 10, 5
+      inject_event(RatatuiRuby::Event::Mouse.new(kind: "down", button: "left", x: 10, y: 5))
+      inject_key(:q)
+      @app.run
+      
+      content = buffer_content.join("\n")
+      assert_includes content, "Left Click at [10, 5]"
+    end
+  end
+
+  def test_mouse_scroll
+    with_test_terminal do
+      inject_event(RatatuiRuby::Event::Mouse.new(kind: "scroll_down", button: "none", x: 20, y: 15))
+      inject_key(:q)
+      @app.run
+      
+      content = buffer_content.join("\n")
+      assert_includes content, "Scrolled Down"
+      assert_includes content, "Position: [20, 15]"
+    end
+  end
+end

data/examples/{popup_demo.rb → popup_demo/app.rb}

@@ -3,30 +3,29 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 
 # Popup Demo Example
 # Demonstrates the Clear widget for creating opaque popups.
 
-class PopupDemo
+class PopupDemoApp
   def initialize
     @clear_enabled = false
   end
 
   def run
-    RatatuiRuby.init_terminal
-    begin
+    RatatuiRuby.run do
       loop do
         render
         break if handle_input == :quit
         sleep 0.05
       end
-    ensure
-      RatatuiRuby.restore_terminal
     end
   end
 
+  private
+
   def render
     # 1. Background: Loud Red Background
     # This demonstrates "Style Bleed" where the background color persists
@@ -47,9 +46,9 @@ class PopupDemo
 
     popup_content = RatatuiRuby::Paragraph.new(
       text: popup_text,
-      align: :center,
+      alignment: :center,
       block: RatatuiRuby::Block.new(
-        title: "Popup Demo (Press 'q' to quit)",
+        title: "Popup Demo (q to quit, space to toggle)",
         borders: [:all]
       )
     )
@@ -90,16 +89,15 @@ class PopupDemo
   end
 
   def handle_input
-    event = RatatuiRuby.poll_event
-    if event
-      case event[:code]
-      when "q"
-        :quit
-      when " "
-        @clear_enabled = !@clear_enabled
-      end
+    case RatatuiRuby.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
 
-PopupDemo.new.run if __FILE__ == $0
+PopupDemoApp.new.run if __FILE__ == $0

data/examples/popup_demo/app.rbs

@@ -0,0 +1,7 @@
+class PopupDemoApp
+  # @public
+  def self.new: () -> PopupDemoApp
+
+  # @public
+  def run: () -> void
+end

data/examples/{test_popup_demo.rb → popup_demo/test_app.rb}

@@ -3,24 +3,25 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 require "ratatui_ruby"
 require "ratatui_ruby/test_helper"
 require "minitest/autorun"
-require_relative "popup_demo"
+require_relative "app"
 
-class Minitest::Test
+class TestPopupDemoApp < Minitest::Test
   include RatatuiRuby::TestHelper
-end
 
-class TestPopupDemo < Minitest::Test
   def setup
-    @app = PopupDemo.new
+    @app = PopupDemoApp.new
   end
 
   def test_render_initial_state
-    with_test_terminal(60, 20) do
-      @app.render
+    with_test_terminal do
+      # Queue quit
+      inject_key(:q)
+
+      @app.run
 
       # Should have background text
       assert buffer_content.any? { |line| line.include?("BACKGROUND RED") }
@@ -32,31 +33,22 @@ class TestPopupDemo < Minitest::Test
   end
 
   def test_toggle_clear
-    with_test_terminal(60, 20) do
-      # Initial state: Clear disabled
-      @app.render
-      assert buffer_content.any? { |line| line.include?("Clear is DISABLED") }
+    with_test_terminal do
+      # Toggle Clear on then quit
+      inject_keys(" ", :q)
 
-      # Toggle Clear on
-      inject_event("key", { code: " " })
-      @app.handle_input
+      @app.run
 
-      @app.render
       assert buffer_content.any? { |line| line.include?("Clear is ENABLED") }
       assert buffer_content.any? { |line| line.include?("Resets background to default") }
-
-      # Toggle Clear off
-      inject_event("key", { code: " " })
-      @app.handle_input
-
-      @app.render
-      assert buffer_content.any? { |line| line.include?("Clear is DISABLED") }
     end
   end
 
   def test_quit
-    inject_event("key", { code: "q" })
-    status = @app.handle_input
-    assert_equal :quit, status
+    with_test_terminal do
+      inject_key(:q)
+      @app.run
+      # Success
+    end
   end
 end

data/examples/quickstart_dsl/app.rb

@@ -0,0 +1,36 @@
+# 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"
+
+class QuickstartDslApp
+  def run
+    # 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
+    RatatuiRuby.run do |tui|
+      loop do
+        # 2. Create your UI with methods instead of classes.
+        view = tui.paragraph(
+          text: "Hello, Ratatui! Press 'q' to quit.",
+          alignment: :center,
+          block: tui.block(
+            title: "My Ruby TUI App",
+            borders: [:all],
+            border_color: "cyan"
+          )
+        )
+
+        # 3. Use RatatuiRuby methods, too.
+        tui.draw(view)
+        event = tui.poll_event
+
+        break if event == "q" || event == :ctrl_c
+      end
+    end
+  end
+end
+
+QuickstartDslApp.new.run if __FILE__ == $PROGRAM_NAME

data/examples/quickstart_dsl/app.rbs

@@ -0,0 +1,7 @@
+class QuickstartDslApp
+  # @public
+  def self.new: () -> QuickstartDslApp
+
+  # @public
+  def run: () -> void
+end

data/examples/quickstart_dsl/test_app.rb

@@ -0,0 +1,29 @@
+# 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"
+require "ratatui_ruby/test_helper"
+require "minitest/autorun"
+require_relative "app"
+
+class TestQuickstartDsl < Minitest::Test
+  include RatatuiRuby::TestHelper
+
+  def setup
+    @app = QuickstartDslApp.new
+  end
+
+  def test_render
+    with_test_terminal do
+      inject_key(:q)
+      @app.run
+      
+      content = buffer_content.join("\n")
+      assert_includes content, "Hello, Ratatui!"
+      assert_includes content, "My Ruby TUI App"
+    end
+  end
+end

data/examples/quickstart_lifecycle/app.rb

@@ -0,0 +1,39 @@
+# 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"
+
+class QuickstartLifecycleApp
+  def run
+    # Using the RatatuiRuby.run block for automatic terminal setup/teardown
+    RatatuiRuby.run do |tui|
+      # The Main Loop
+      loop do
+        # 1. Create your UI (Immediate Mode)
+        # We define a Paragraph widget inside a Block with a title and borders.
+        view = RatatuiRuby::Paragraph.new(
+          text: "Hello, Ratatui! Press 'q' to quit.",
+          alignment: :center,
+          block: RatatuiRuby::Block.new(
+            title: "My Ruby TUI App",
+            borders: [:all],
+            border_color: "cyan"
+          )
+        )
+
+        # 2. Draw the UI
+        tui.draw(view)
+
+        # 3. Poll for events
+        event = RatatuiRuby.poll_event
+        break if event == "q" || event == :ctrl_c
+      end
+    end
+  end
+end
+
+QuickstartLifecycleApp.new.run if __FILE__ == $PROGRAM_NAME