### Ruby Quickstart DSL Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/verify_quickstart_dsl/README.md

Initializes the terminal, creates a UI with methods, draws the UI, and polls for events. Press 'q' to quit.

```ruby
# 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",
        title_alignment: :center,
        borders: [:all],
        border_color: "cyan",
        style: { fg: "white" }
      )
    )

    # 3. Use RatatuiRuby methods, too.
    tui.draw do |frame|
      frame.render_widget(view, frame.area)
    end

    # 4. Poll for events with pattern matching
    case tui.poll_event
    in { type: :key, code: "q" }
      break
    else
      # Ignore other events
    end
  end
end

```

--------------------------------

### Run Block Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_box/README.md

Execute the Block example application to interactively explore its features. This command starts the application from the project root.

```bash
ruby examples/widget_box/app.rb
```

--------------------------------

### Ruby Quickstart Layout Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/verify_quickstart_layout/README.md

Demonstrates splitting the screen vertically with percentage constraints, rendering a paragraph widget in the top section, and another paragraph with styled text in the bottom section for controls. It polls for key events and breaks the loop when 'q' is pressed.

```ruby
loop do
  tui.draw do |frame|
    # 1. Split the screen
    top, bottom = tui.layout_split(
      frame.area,
      direction: :vertical,
      constraints: [
        tui.constraint_percentage(75),
        tui.constraint_percentage(25),
      ]
    )

    # 2. Render Top Widget
    frame.render_widget(
      tui.paragraph(
        text: "Hello, Ratatui!",
        alignment: :center,
        block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
      ),
      top
    )

    # 3. Render Bottom Widget with Styled Text
    # We use a Line of Spans to style specific characters
    text_line = tui.text_line(
      spans: [
        tui.text_span(content: "Press '"),
        tui.text_span(
          content: "q",
          style: tui.style(modifiers: [:bold, :underlined])
        ),
        tui.text_span(content: "' to quit."),
      ],
      alignment: :center
    )

    frame.render_widget(
      tui.paragraph(
        text: text_line,
        block: tui.block(title: "Controls", borders: [:all])
      ),
      bottom
    )
  end

  case tui.poll_event
  in { type: :key, code: "q" }
    break
  else
    # Ignore other events
  end
end
```

--------------------------------

### Run Rect Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_rect/README.md

Execute the Rect example application from the command line.

```bash
ruby examples/widget_rect/app.rb
```

--------------------------------

### Example Test Setup with RatatuiRuby::TestHelper

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/developing_examples.md

This Ruby test file sets up an example application for testing. It includes loading the library, helper modules, and the application code, preparing for test execution.

```ruby
$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
require "ratatui_ruby"
require "ratatui_ruby/test_helper"
require "minitest/autorun"
require_relative "app"

class TestMyExampleApp < Minitest::Test
  include RatatuiRuby::TestHelper

  def setup
    @app = MyExampleApp.new
  end

  def test_initial_render
    with_test_terminal do
      inject_key(:q)
      @app.run
      assert_snapshots("initial_render")
    end
  end
end
```

--------------------------------

### Run Sparkline Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_sparkline/README.md

Execute the Sparkline widget example application. This command starts the demonstration of the sparkline widget's features.

```bash
ruby examples/widget_sparkline/app.rb
```

--------------------------------

### Run List Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_list/README.md

Execute the List widget example application from the command line.

```bash
ruby examples/widget_list/app.rb
```

--------------------------------

### Run Login Form Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/app_login_form/README.md

Execute the login form example application from the command line.

```bash
ruby examples/app_login_form/app.rb
```

--------------------------------

### Setup Script for macOS and Linux

Source: https://github.com/setdef/ratatuiruby/blob/stable/CONTRIBUTING.md

Run this script to set up the development environment on macOS and Linux. It installs necessary dependencies like Rust, Python, and Bundler.

```shell
bin/setup
```

--------------------------------

### Run Calendar Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_calendar/README.md

Execute the calendar widget example script using Ruby. This command starts the application demonstrating the calendar's features.

```bash
ruby examples/widget_calendar/app.rb
```

--------------------------------

### Run Chart Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_chart/README.md

Execute the chart example application using Ruby.

```bash
ruby examples/widget_chart/app.rb
```

--------------------------------

### Run Widget Overlay Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_overlay/README.md

Execute the widget overlay example application using Ruby.

```bash
ruby examples/widget_overlay/app.rb
```

--------------------------------

### Setup Script for Windows (PowerShell)

Source: https://github.com/setdef/ratatuiruby/blob/stable/CONTRIBUTING.md

Execute this PowerShell script to set up the development environment on Windows. It handles Ruby installation via RubyInstaller and installs other required tools.

```powershell
bin/setup.ps1
```

--------------------------------

### Run Example Application

Source: https://github.com/setdef/ratatuiruby/blob/stable/CONTRIBUTING.md

Use this command to run any example application. Bundler ensures the development version of the gem is loaded.

```shell
bundle exec ruby examples/app_all_events/app.rb
```

--------------------------------

### Run Ratatui Mascot Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_ratatui_mascot/README.md

Execute the example application to see the Ratatui mascot widget in action. This command starts the Ruby script that demonstrates the widget's integration.

```bash
ruby examples/widget_ratatui_mascot/app.rb
```

--------------------------------

### Run Clear Popup Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_popup/README.md

Execute the main application file for the popup widget example.

```bash
ruby examples/widget_popup/app.rb
```

--------------------------------

### Run Scrollbar Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_scrollbar/README.md

Execute the scrollbar example application using Ruby.

```bash
ruby examples/widget_scrollbar/app.rb
```

--------------------------------

### Run External Editor Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/app_external_editor/README.md

Execute the external editor example application.

```bash
ruby examples/app_external_editor/app.rb
```

--------------------------------

### Method and Attribute Documentation Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/documentation_style.md

This example illustrates the recommended syntax for documenting attributes and the initialize method, including parameter definitions and RDoc formatting.

```ruby
  # The styling to apply to the content.
  attr_reader :style

  # Creates a new List.
  #
  # [items] Array of Strings.
  # [selected_index] Integer (nullable).
  def initialize(items: [], selected_index: nil)
    super
  end

```

--------------------------------

### Run Layout Split Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_layout_split/README.md

Execute the layout split example application using Ruby.

```bash
ruby examples/widget_layout_split/app.rb
```

--------------------------------

### Example Directory Structure

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/developing_examples.md

This illustrates the standard directory layout for an example, including the runnable code, README, tests, and type signatures.

```text
examples/
  my_example/
    app.rb              ← REQUIRED: The runnable example code
    README.md           ← REQUIRED: Purpose, architecture, hotkeys, usage

test/examples/
  my_example/
    test_app.rb         ← REQUIRED: Tests (centralized, not local to example)
    snapshots/          ← Auto-created by snapshot assertions
      initial_render.txt

sig/examples/
  my_example/
    app.rbs             ← REQUIRED: Type signatures (centralized, not local to example)

```

--------------------------------

### Run the Map Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_map/README.md

Execute the main application script for the map widget example.

```bash
ruby examples/widget_map/app.rb
```

--------------------------------

### Run Table Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_table/README.md

Execute the Table widget example application from the command line. Ensure you are in the project root directory.

```bash
ruby examples/widget_table/app.rb
```

--------------------------------

### RatatuiRuby Quickstart Lifecycle Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/verify_quickstart_lifecycle/README.md

This Ruby code demonstrates the basic lifecycle of a RatatuiRuby application. It initializes the terminal, enters a main loop to draw a UI, polls for user input to quit, and ensures the terminal is restored upon exit. Use this as a foundational example for building TUI applications.

```ruby
# 1. Initialize the terminal
RatatuiRuby.init_terminal

begin
  # The Main Loop
  loop do
    # 2. Create your UI (Immediate Mode)
    # We define a Paragraph widget inside a Block with a title and borders.
    view = RatatuiRuby::Widgets::Paragraph.new(
      text: "Hello, Ratatui! Press 'q' to quit.",
      alignment: :center,
      block: RatatuiRuby::Widgets::Block.new(
        title: "My Ruby TUI App",
        title_alignment: :center,
        borders: [:all],
        border_color: "cyan",
        style: { fg: "white" }
      )
    )

    # 3. Draw the UI
    RatatuiRuby.draw do |frame|
      frame.render_widget(view, frame.area)
    end

    # 4. Poll for events
    case RatatuiRuby.poll_event
    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
      break
    else
      nil
    end

    # 5. Guard against accidental output (optional but recommended)
    # Wrap any code that might puts/warn to prevent screen corruption.
    RatatuiRuby.guard_io do
      # SomeChattyGem.do_something
    end
  end
ensure
  # 6. Restore the terminal to its original state
  RatatuiRuby.restore_terminal
end
```

--------------------------------

### Run CLI Rich Moments Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/app_cli_rich_moments/README.md

Navigate to the example directory and execute the application script to see the rich moments in action.

```bash
cd examples/app_cli_rich_moments
ruby app.rb
```

--------------------------------

### Run Tabs Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_tabs/README.md

Execute the Tabs Widget example application using Ruby.

```bash
ruby examples/widget_tabs/app.rb
```

--------------------------------

### Run BarChart Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_barchart/README.md

Execute the BarChart example application using Ruby.

```bash
ruby examples/widget_barchart/app.rb
```

--------------------------------

### Run Rich Text Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_rich_text/README.md

Execute the rich text example application using Ruby.

```bash
ruby examples/widget_rich_text/app.rb
```

--------------------------------

### Run Custom Widget Render Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_render/README.md

Execute the custom widget rendering example application using Ruby.

```bash
ruby examples/widget_render/app.rb
```

--------------------------------

### Run Block Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_block/README.md

Execute the block widget example application using Ruby.

```bash
ruby examples/widget_block/app.rb
```

--------------------------------

### Run Ratatui Logo Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_ratatui_logo/README.md

Execute the Ratatui logo example application using Ruby.

```bash
ruby examples/widget_ratatui_logo/app.rb
```

--------------------------------

### Run Gauge Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_gauge/README.md

Execute the Gauge widget example application using Ruby.

```bash
ruby examples/widget_gauge/app.rb
```

--------------------------------

### Run Line Gauge Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_line_gauge/README.md

Execute the Line Gauge widget example application using Ruby.

```bash
ruby examples/widget_line_gauge/app.rb
```

--------------------------------

### Run Style Colors Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_style_colors/README.md

Execute the widget style colors application from the command line.

```bash
ruby examples/widget_style_colors/app.rb
```

--------------------------------

### Run Scroll Text Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_scroll_text/README.md

Execute the scroll text example application using Ruby.

```bash
ruby examples/widget_scroll_text/app.rb
```

--------------------------------

### Run Cell Widget Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_cell/README.md

Execute the `app.rb` script to run the Cell Widget example. This is the primary way to interact with the demonstration.

```bash
ruby examples/widget_cell/app.rb
```

--------------------------------

### Full-Screen Application Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/README.rdoc

This example shows how to create a full-screen TUI application. It includes a loop that renders a centered 'Hello, RatatuiRuby!' message and breaks when the 'q' key is pressed. The managed loop ensures the terminal is restored on exit.

```ruby
RatatuiRuby.run do |tui|
  loop do
    tui.draw do |frame|
      frame.render_widget(
        tui.paragraph(text: "Hello, RatatuiRuby!", alignment: :center),
        frame.area
      )
    end

    case tui.poll_event
    in { type: :key, code: "q" } then break
    else nil
    end
  end
end
```

--------------------------------

### Bad Class Documentation Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/documentation_style.md

This example shows a generic and descriptive approach to documenting a class, which is discouraged.

```ruby
# A widget for displaying list items.
# It allows the user to select an item from an array of strings.
# Supports scrolling and custom styling.

```

--------------------------------

### Ruby Example Application Structure

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/developing_examples.md

This is the standard structure for an interactive Ratatui Ruby example application. It includes initialization, a run loop, rendering logic, and input handling.

```ruby
$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
require "ratatui_ruby"

class MyExampleApp
  def initialize
    # Initialize state (styles must be initialized in run when @tui is available)
  end

  def run
    RatatuiRuby.run do |tui|
      @tui = tui  # Store for use in private methods
      loop do
        render
        break if handle_input == :quit
      end
    end
  end

  private

  def render
    @tui.draw do |frame|
      # 1. Split layout using Session helpers
      areas = @tui.layout_split(frame.area, constraints: [@tui.constraint_fill(1)])
      # 2. Create and render widgets
      widget = @tui.paragraph(text: "Hello", block: @tui.block(borders: [:all]))
      frame.render_widget(widget, areas[0])
    end
  end

  def handle_input
    case @tui.poll_event
    in { type: :key, code: "q" }
      :quit
    in { type: :key, code: code }
      # Handle other keys
    else
      # Ignore unhandled events
    end
  end
end

MyExampleApp.new.run if __FILE__ == $PROGRAM_NAME

```

--------------------------------

### Running the Color Picker App

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/app_color_picker/README.md

Command to launch the Ratatuiruby color picker example application from the terminal.

```bash
ruby examples/app_color_picker/app.rb
```

--------------------------------

### Good Class Documentation Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/documentation_style.md

This example demonstrates the preferred Alexandrian, Zinsser, and Plain Language approach for class documentation, focusing on context, problem, solution, and usage.

```ruby
# Displays a selectable list of items.
#
# Users need to choose from options. Menus, file explorers, and selectors are everywhere.
# Implementing navigation, highlighting, and scrolling state from scratch is tedious.
#
# This widget manages the list. It renders the items. It highlights the selection. It handles the scrolling window.
#
# Use it to build main menus, navigation sidebars, or logs.

```

--------------------------------

### Example: Debugging a Running TUI (App Terminal)

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/concepts/debugging.md

Start your TUI application with debugging enabled in one terminal. The application will pause and wait for a debugger to attach.

```sh
$ ruby my_tui_app.rb
# App starts, TUI is running
# In your code: RatatuiRuby.debug_mode!
# Console shows: DEBUGGER: Debugger can attach via UNIX domain socket (...)
```

--------------------------------

### Enable RatatuiRuby Debug Mode

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/concepts/debugging.md

Enables debug mode programmatically to get Rust backtraces for panics. Alternatively, use the RR_DEBUG=1 environment variable before starting the application.

```ruby
# Option 1: Environment variable
# $ RR_DEBUG=1 ruby my_app.rb

# Option 2: Programmatic
RatatuiRuby.debug_mode!

# Now Rust panics show meaningful stack traces
```

--------------------------------

### Install Gems with Bundler

Source: https://github.com/setdef/ratatuiruby/blob/stable/README.md

Execute this command after adding the gem to your Gemfile to install dependencies.

```bash
bundle install
```

--------------------------------

### Example Widget, Layout, and Style Instantiation

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/design/ruby_frontend.md

Demonstrates how to instantiate core Ratatui components using their explicit, deep namespaces. These classes mirror the upstream Rust Ratatui API.

```ruby
RatatuiRuby::Widgets::Paragraph.new(text: "Hello")
RatatuiRuby::Layout::Constraint.length(20)
RatatuiRuby::Style::Style.new(fg: :red)
```

--------------------------------

### Immediate Mode UI Loop Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/design/ruby_frontend.md

Demonstrates the immediate mode UI paradigm where a fresh view tree is constructed and passed to `draw` every frame. The loop breaks when the 'q' key is pressed.

```ruby
loop do
  tui.draw do |frame|
    # Fresh tree every frame
    frame.render_widget(tui.paragraph(text: "Time: #{Time.now}"), frame.area)
  end
  break if tui.poll_event.key? && tui.poll_event.code == "q"
end
```

--------------------------------

### Install RatatuiRuby Gem

Source: https://github.com/setdef/ratatuiruby/blob/stable/README.md

Alternatively, install the ratatui_ruby gem directly using the gem command.

```bash
gem install ratatui_ruby
```

--------------------------------

### Run Text Width Calculator Example

Source: https://github.com/setdef/ratatuiruby/blob/stable/examples/widget_text_width/README.md

Execute the text width calculator application from the command line. This will launch an interactive TUI demonstrating Unicode width calculations.

```bash
ruby examples/widget_text_width/app.rb
```

--------------------------------

### RBS Type Signature for Example Application

Source: https://github.com/setdef/ratatuiruby/blob/stable/doc/contributors/developing_examples.md

This RBS file defines the public type signatures for the example application, ensuring type safety and clarity for its public interface.

```rbs
class MyExampleApp
  # @public
  def self.new: () -> MyExampleApp

  # @public
  def run: () -> void
end

```