ratatui_ruby 1.0.0 → 1.0.1

data/examples/verify_quickstart_lifecycle/app.rb

@@ -1,62 +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"
-
-class VerifyQuickstartLifecycle
-  def run
-    # [SYNC:START:main]
-    # 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_style: { fg: "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
-    # [SYNC:END:main]
-  end
-end
-
-VerifyQuickstartLifecycle.new.run if __FILE__ == $PROGRAM_NAME

data/examples/verify_readme_usage/README.md

@@ -1,49 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# README Usage Verification
-
-Verifies the primary usage example in the project [README](../../README.md#usage).
-
-This example exists as a documentation regression test. It ensures that the very first code snippet a user sees actually works.
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-<!-- SYNC:START:app.rb:main -->
-```ruby
-RatatuiRuby.run do |tui|
-  loop do
-    tui.draw do |frame|
-      frame.render_widget(
-        tui.paragraph(
-          text: "Hello, Ratatui! Press 'q' to quit.",
-          alignment: :center,
-          block: tui.block(
-            title: "My Ruby TUI App",
-            borders: [:all],
-            border_color: "cyan"
-          )
-        ),
-        frame.area
-      )
-    end
-    case tui.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      break
-    else
-      nil
-    end
-  end
-end
-```
-<!-- SYNC:END -->
-<!-- SPDX-SnippetEnd -->
-
-[![verify_readme_usage](../../doc/images/verify_readme_usage.png)](../../README.md#usage)

data/examples/verify_readme_usage/app.rb

@@ -1,42 +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"
-class VerifyReadmeUsage
-  def run
-    # [SYNC:START:main]
-    RatatuiRuby.run do |tui|
-      loop do
-        tui.draw do |frame|
-          frame.render_widget(
-            tui.paragraph(
-              text: "Hello, Ratatui! Press 'q' to quit.",
-              alignment: :center,
-              block: tui.block(
-                title: "My Ruby TUI App",
-                borders: [:all],
-                border_style: { fg: "cyan" }
-              )
-            ),
-            frame.area
-          )
-        end
-        case tui.poll_event
-        in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-          break
-        else
-          nil
-        end
-      end
-    end
-    # [SYNC:END:main]
-  end
-end
-
-VerifyReadmeUsage.new.run if __FILE__ == $PROGRAM_NAME

data/examples/verify_website_managed/README.md

@@ -1,48 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Website Managed Loop Verification
-
-Verifies the full-screen managed loop example on the [RatatuiRuby website](https://ratatui-ruby.dev).
-
-This example exists as a documentation regression test. It ensures the website's "Build Something Real" managed loop demo remains functional.
-
-## Usage
-
-```ruby
-RatatuiRuby.run do |tui|
-  loop do
-    tui.draw do |frame|
-      frame.render_widget(
-        tui.paragraph(
-          text: "Hello, RatatuiRuby!",
-          alignment: :center,
-          block: tui.block(
-            title: "My App",
-            titles: [{ content: "q: Quit", position: :bottom, alignment: :right }],
-            borders: [:all],
-            border_style: { fg: "cyan" }
-          )
-        ),
-        frame.area
-      )
-    end
-
-    case tui.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      break
-    else nil
-    end
-  end
-end
-```
-
-## Features Demonstrated
-
-- **Full-screen mode**: Alternate screen with automatic terminal restoration
-- **Managed lifecycle**: `RatatuiRuby.run` handles setup/teardown
-- **Block with titles**: Top title and bottom key hints
-- **Keyboard handling**: `q` and `Ctrl+C` to quit
-- **Pattern matching**: Ruby 3.x pattern matching for event handling

data/examples/verify_website_managed/app.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-#
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# Test 3: Managed loop example
-require "ratatui_ruby"
-
-RatatuiRuby.run do |tui|
-  loop do
-    tui.draw do |frame|
-      frame.render_widget(
-        tui.paragraph(
-          text: "Hello, RatatuiRuby!",
-          alignment: :center,
-          block: tui.block(
-            title: "My App",
-            titles: [{ content: "q: Quit", position: :bottom, alignment: :right }],
-            borders: [:all],
-            border_style: { fg: "cyan" }
-          )
-        ),
-        frame.area
-      )
-    end
-
-    case tui.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      break
-    else nil
-    end
-  end
-end

data/examples/verify_website_menu/README.md

@@ -1,60 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Website Menu Verification
-
-Verifies the inline menu example on the [RatatuiRuby website](https://ratatui-ruby.dev).
-
-This example exists as a documentation regression test. It ensures the website's inline viewport menu demo remains functional.
-
-## Usage
-
-```ruby
-choices = ["Production", "Staging", "Development"]
-index = 0
-
-RatatuiRuby.run(viewport: :inline, height: 5) do |tui|
-  loop do
-    tui.draw do |frame|
-      items = choices.map.with_index do |c, i|
-        prefix = i == index ? "● " : "○ "
-        "#{prefix}#{c}"
-      end
-      widget = tui.paragraph(
-        text: items.join("\n"),
-        block: tui.block(
-          borders: :all,
-          title: "Select Environment",
-          titles: [{ content: "↑/↓ Enter | Ctrl+C", position: :bottom, alignment: :right }]
-        )
-      )
-      frame.render_widget(widget, frame.area)
-    end
-
-    case tui.poll_event
-    in { type: :key, code: "up" }
-      index = (index - 1) % choices.size
-    in { type: :key, code: "down" }
-      index = (index + 1) % choices.size
-    in { type: :key, code: "enter" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      area = tui.viewport_area
-      RatatuiRuby.cursor_position = [0, area.y + area.height]
-      break
-    else nil
-    end
-  end
-end
-
-puts
-puts "Deploying to #{choices[index]}..."
-```
-
-## Features Demonstrated
-
-- **Inline viewport**: 5-line viewport with bordered menu
-- **Keyboard navigation**: Arrow keys for selection, Enter to confirm
-- **Ctrl+C handling**: Graceful exit on cancellation
-- **Bottom title**: Key hints rendered on the bottom border
-- **Cursor positioning**: Proper cursor placement after inline viewport exit

data/examples/verify_website_menu/app.rb

@@ -1,84 +0,0 @@
-# frozen_string_literal: true
-# rubocop:disable all
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-#
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-require "ratatui_ruby"
-
-# This example renders an inline menu. Arrow keys select, enter confirms.
-# The menu appears in-place, preserving scrollback. When the user chooses,
-# the TUI closes and the script continues with the selected value.
-class RadioMenu
-  CHOICES = ["Production", "Staging", "Development"]         # ASCII strings are universally supported.
-  PREFIXES = { active: "●", inactive: "○" }                  # Some terminals may not support Unicode.
-  CONTROLS = "↑/↓: Select | Enter: Choose | Ctrl+C: Cancel"  # Let users know what keys you handle.
-  TITLES = ["Select Environment",                            # The default title position is top left.
-            { content: CONTROLS,                             # Multiple titles can save space.
-              position: :bottom,                             # Titles go on the top or bottom,
-              alignment: :right }]                           # aligned left, right, or center
-
-  def call                                                   # This method blocks until a choice is made.
-    RatatuiRuby.run(viewport: :inline, height: 5) do |tui|   # RatauiRuby.run manages the terminal.
-      @tui = tui                                             # The TUI instance is safe to store.
-      show_menu until chosen?                                # You can use any loop keyword you like.
-    end                                                      # `run` won't return until your block does,
-    RadioMenu::CHOICES[@choice]                              # so you can use it synchronously.
-  end
-                                                             # Classes like RadioMenu are convenient for
-  private                                                    # CLI authors to offer "rich moments."
-
-  def show_menu = @tui.draw do |frame|                       # RatatuiRuby gives you low-level access.
-    widget = @tui.paragraph(                                 # But the TUI facade makes it easy to use.
-      text: menu_items,                                      # Text can be spans, lines, or paragraphs.
-      block: @tui.block(borders: :all, titles: TITLES)       # Blocks give you boxes and titles, and hold
-    )                                                        # one or more widgets. We only use one here,
-    frame.render_widget(widget, frame.area)                  # but "area" lets you compose sub-views.
-  end
-
-  def chosen?                                                # You are responsible for handling input.
-    interaction = @tui.poll_event                            # Every frame, you receive an event object:
-    return choose if interaction.enter?                      # Key, Mouse, Resize, Paste, FocusGained,
-                                                             # FocusLost, or None objects. They come with
-    move_by(-1) if interaction.up?                           # predicates, support pattern matching, and
-    move_by(1) if interaction.down?                          # can be inspected for properties directly.
-    quit! if interaction.ctrl_c?                             # Your application must handle every input,
-    false                                                    # even interrupts and other exit patterns.
-  end
-
-  def choose                                                 # Here, the loop is about to exit, and the
-    prepare_next_line                                        # block will return. The inline viewport
-    @choice                                                  # will be torn down and the terminal will
-  end                                                        # be restored, but you are responsible for
-                                                             # positioning the cursor.
-  def prepare_next_line                                      # To ensure the next output is on a new
-    area = @tui.viewport_area                                # line, query the viewport area and move
-    RatatuiRuby.cursor_position = [0, area.y + area.height]  # the cursor to the start of the last line.
-    puts                                                     # Then print a newline.
-  end
-
-  def quit!                                                  # All of your familiar Ruby control flow
-    prepare_next_line                                        # keywords work as expected, so we can
-    exit 0                                                   # use them to leave the TUI.
-  end
-
-  def move_by(line_count)                                    # You are in full control of your UX, so
-    @choice = (@choice + line_count) % CHOICES.size          # you can implement any logic you need:
-  end                                                        # Would you "wrap around" here, or not?
-                                                             #
-  def menu_items = CHOICES.map.with_index do |choice, i|     # Notably, RatatuiRuby has no concept of
-    "#{prefix_for(i)} #{choice}"                             # "menus" or "radio buttons". You are in
-  end                                                        # full control, but it also means you must
-  def prefix_for(choice_index)                               # implement the logic yourself. For larger
-    return PREFIXES[:active] if choice_index == @choice      # applications, consider using Rooibos,
-    PREFIXES[:inactive]                                      # an MVU framework built with RatatuiRuby.
-  end                                                        # Or, use the upcoming ratatui-ruby-kit,
-                                                             # our object-oriented component library.
-  def initialize = @choice = 0                               # However, those are both optional, and
-end                                                          # designed for full-screen Terminal UIs.
-                                                             # RatatuiRuby will always give you the most
-choice = RadioMenu.new.call                                  # control, and is enough for "rich CLI
-puts "You chose #{choice}!"                                  # moments" like this one.

data/examples/verify_website_spinner/README.md

@@ -1,44 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Website Spinner Verification
-
-Verifies the inline spinner example on the [RatatuiRuby website](https://ratatui-ruby.dev).
-
-This example exists as a documentation regression test. It ensures the website's inline viewport spinner demo remains functional.
-
-## Usage
-
-```ruby
-class Spinner
-  def main
-    RatatuiRuby.run(viewport: :inline, height: 1) do |tui|
-      until connected?
-        status = tui.paragraph(text: "#{spin} Connecting...")
-        tui.draw { |frame| frame.render_widget(status, frame.area) }
-        return ending(tui, "Canceled!", :red) if tui.poll_event.ctrl_c?
-      end
-      ending(tui, "Connected!", :green)
-    end
-  end
-
-  def ending(tui, message, color) = tui.draw do |frame|
-    frame.render_widget(tui.paragraph(text: message, fg: color), frame.area)
-  end
-
-  def initialize = (@i, @end = 0, Time.now + 2)
-  def connected? = Time.now >= @end
-  def spin = SPINNER[(@i += 1) % SPINNER.length]
-  SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏]
-end
-Spinner.new.main; puts
-```
-
-## Features Demonstrated
-
-- **Inline viewport**: 1-line viewport that preserves terminal scrollback
-- **Ctrl+C handling**: Graceful cancellation with `poll_event.ctrl_c?`
-- **Colored output**: Status messages with `:red` and `:green` colors
-- **Timeout pattern**: Uses `Time.now` for connection simulation

data/examples/verify_website_spinner/app.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-#
-# SPDX-License-Identifier: AGPL-3.0-or-later
-#++
-
-# Test 1: Inline spinner example
-require "ratatui_ruby"
-
-class Spinner
-  def main
-    RatatuiRuby.run(viewport: :inline, height: 1) do |tui|
-      until connected?
-        status = tui.paragraph(text: "#{spin} Connecting...")
-        tui.draw { |frame| frame.render_widget(status, frame.area) }
-        return ending(tui, "Canceled!", :red) if tui.poll_event.ctrl_c?
-      end
-      ending(tui, "Connected!", :green)
-    end
-  end
-
-  def ending(tui, text, fg) = tui.draw do |frame|
-    frame.render_widget(tui.paragraph(text:, fg:), frame.area)
-    puts # Prepare a new line for the shell prompt
-  end
-
-  def initialize = (@frame, @finish = 0, Time.now + 2)
-  def connected? = Time.now >= @finish # Simulate work
-  def spin = SPINNER[(@frame += 1) % SPINNER.length]
-  SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏]
-end
-Spinner.new.main

data/examples/widget_barchart/README.md

@@ -1,58 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# BarChart (Bar, BarGroup) Example
-
-[![](../../doc/images/widget_barchart.png)](app.rb)
-
-Visualizes categorical data with interactive attribute cycling.
-
-Comparing magnitudes in raw tables requires mental arithmetic. Bar charts make these comparisons instant and intuitive.
-
-## Features Demonstrated
-
-- **Data Formats**: Supports simple Hashes, Arrays with individual styles, and Groups (stacked/grouped bars).
-- **Orientation**: Switch between Vertical and Horizontal layouts.
-- **Customization**:
-    - Adjustable bar widths and gaps.
-    - Custom characters for bars (ASCII art support).
-    - Detailed styling for labels and values.
-- **Mini Mode**: Compact rendering for dashboard widgets.
-
-## Hotkeys
-
-- **d**: Cycle Data Source (`data`)
-- **v**: Toggle Direction (`direction`)
-- **w**: Adjust Bar Width (`bar_width`)
-- **a**: Adjust Bar Gap (`bar_gap`)
-- **g**: Adjust Group Gap (`group_gap`)
-- **b**: Cycle Bar Character Set (`bar_set`)
-- **s**: Cycle Chart Style (`style`)
-- **x**: Cycle Label Style (`label_style`)
-- **z**: Cycle Value Style (`value_style`)
-- **m**: Toggle Mini Mode (Compact View)
-- **q**: Quit
-
-## Usage
-
-<!-- SPDX-SnippetBegin -->
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long
-  SPDX-License-Identifier: MIT-0
--->
-```bash
-ruby examples/widget_barchart/app.rb
-```
-<!-- SPDX-SnippetEnd -->
-
-## Learning Outcomes
-
-Use this example if you need to...
-
-- Visualize categorical data (e.g., sales by quarter, CPU usage by core).
-- Create "stats" dashboards with compact visualizations.
-- Understand how `RatatuiRuby::BarChart` handles different data structures.
-
-[Read the source code →](app.rb)