ratatui_ruby 0.1.0

data/Rakefile

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+# Ruby tests are handled by test:ruby
+# Cargo tests are handled by test:rust
+
+require "rake/extensiontask"
+
+spec = Gem::Specification.load("ratatui_ruby.gemspec")
+Rake::ExtensionTask.new("ratatui_ruby", spec) do |ext|
+  ext.lib_dir = "lib/ratatui_ruby"
+  ext.ext_dir = "ext/ratatui_ruby"
+end
+
+# The :compile task is now provided by rake-compiler
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require "rdoc/task"
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "doc"
+  rdoc.main = "README.md"
+  rdoc.rdoc_files.include("**/*.md", "**/*.rdoc", "lib/**/*.rb", "exe/**/*")
+end
+
+Rake::Task[:rdoc].enhance do
+  FileUtils.mkdir_p "doc/docs/images"
+  FileUtils.cp_r FileList["docs/images/*.png"], "doc/docs/images"
+end
+
+Rake::Task[:rerdoc].enhance do
+  FileUtils.mkdir_p "doc/docs/images"
+  FileUtils.cp_r FileList["docs/images/*.png"], "doc/docs/images"
+end
+
+require "rubycritic/rake_task"
+
+RubyCritic::RakeTask.new do |task|
+  task.options = "--no-browser"
+  task.paths = FileList.new.include("exe/**/*.rb", "lib/**/*.rb", "sig/**/*.rbs")
+end
+
+require "inch/rake"
+
+Inch::Rake::Suggest.new("doc:suggest", "exe/**/*.rb", "lib/**/*.rb", "sig/**/*.rbs") do |suggest|
+  suggest.args << ""
+end
+
+namespace :cargo do
+  desc "Run cargo fmt"
+  task :fmt do
+    sh "cd ext/ratatui_ruby && cargo fmt --all -- --check"
+  end
+
+  desc "Run cargo clippy"
+  task :clippy do
+    sh "cd ext/ratatui_ruby && cargo clippy -- -D warnings"
+  end
+
+  desc "Run cargo tests"
+  task :test do
+    sh "cd ext/ratatui_ruby && cargo test"
+  end
+end
+
+namespace :reuse do
+  desc "Run the REUSE Tool to confirm REUSE compliance"
+  task :lint do
+    sh "pipx run reuse lint"
+  end
+end
+task(:reuse) { Rake::Task["reuse:lint"].invoke }
+
+namespace :lint do
+  multitask docs: %i[rubycritic rdoc:coverage reuse:lint]
+  multitask code: %i[rubocop rubycritic cargo:fmt cargo:clippy cargo:test]
+  multitask licenses: %i[reuse:lint]
+  multitask all: %i[docs code licenses]
+end
+task(:lint) { Rake::Task["lint:all"].invoke }
+
+# Clear the default test task created by Minitest::TestTask
+Rake::Task["test"].clear
+
+desc "Run all tests (Ruby and Rust)"
+task test: %w[test:ruby test:rust]
+
+namespace :test do
+  desc "Run Rust tests"
+  task :rust do
+    Rake::Task["cargo:test"].invoke
+  end
+
+  # Create a specific Minitest task for Ruby tests
+  Minitest::TestTask.create(:ruby) do |t|
+    t.test_globs = ["test/**/test_*.rb", "examples/**/test_*.rb"]
+  end
+end
+
+multitask default: %i[test lint]

data/docs/application_testing.md

@@ -0,0 +1,96 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Application Testing Guide
+
+This guide explains how to test your RatatuiRuby applications using the provided `RatatuiRuby::TestHelper`.
+
+## Overview
+
+RatatuiRuby includes a `TestHelper` module designed to simplify unit testing of TUI applications. It allows you to:
+
+- Initialize a virtual "test terminal" with specific dimensions.
+
+- Capture the rendered output (the "buffer") to assert against expected text.
+
+- Inspect the cursor position.
+
+- Simulate user input (using `inject_event`).
+
+## Setup
+
+First, require the test helper in your test file or `test_helper.rb`:
+
+```ruby
+require "ratatui_ruby/test_helper"
+require "minitest/autorun" # or your preferred test framework
+```
+
+Then, include the module in your test class:
+
+```ruby
+class MyApplicationTest < Minitest::Test
+  include RatatuiRuby::TestHelper
+  # ...
+end
+```
+
+## Basic Usage
+
+### `with_test_terminal`
+
+Wrap your test assertions in `with_test_terminal`. This sets up a temporary, in-memory backend for Ratatui to draw to, instead of the real terminal. It automatically cleans up afterwards.
+
+```ruby
+def test_rendering
+  # Create a 80x24 terminal
+  with_test_terminal(80, 24) do
+    # 1. Instantiate your app/component
+    widget = RatatuiRuby::Paragraph.new(text: "Hello World")
+    
+    # 2. Render it
+    RatatuiRuby.draw(widget)
+    
+    # 3. Assert on the output
+    assert_includes buffer_content[0], "Hello World"
+  end
+end
+```
+
+### `buffer_content`
+
+Returns the current state of the terminal as an Array of Strings. Useful for verifying that specific text appears where you expect it.
+
+```ruby
+rows = buffer_content
+assert_equal "Title", rows[0].strip
+assert_match /Results: \d+/, rows[2]
+```
+
+### `cursor_position`
+
+Returns the current cursor coordinates as `{ x: Integer, y: Integer }`. Useful for forms or ensuring focus is correct.
+
+```ruby
+pos = cursor_position
+assert_equal 5, pos[:x]
+assert_equal 2, pos[:y]
+```
+
+### `inject_event`
+
+Injects a mock event into the event queue. This is the preferred way to simulate user input instead of stubbing `poll_event`.
+
+```ruby
+# Simulate 'q' key press
+inject_event("key", { code: "q" })
+
+# Now poll_event will return the 'q' key event
+event = RatatuiRuby.poll_event
+assert_equal "q", event[:code]
+```
+
+## Example
+
+Be sure to check out the [examples directory](../examples/) in the repository, which contains several fully tested example applications showcasing these patterns.

data/docs/contributors/design/ruby_frontend.md

@@ -0,0 +1,100 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Ruby Frontend Design (`ratatui_ruby`)
+
+This document describes the design philosophy and structure of the Ruby layer in `ratatui_ruby`.
+
+## Core Philosophy: Data-Driven UI
+
+The Ruby frontend is designed as a **thin, declarative layer** over the Rust backend. It uses an **Immediate Mode** paradigm where the user constructs a tree of pure data objects every frame to represent the desired UI state.
+
+### 1. View Tree as Data
+
+Unlike traditional OO GUI toolkits (like Qt or Swing) where widgets are retained objects with internal state, `ratatui_ruby` widgets are immutable value objects.
+
+*   Implemented using Ruby 3.2+ `Data` classes.
+*   Located in `lib/ratatui_ruby/schema/`.
+*   These objects act as a Schema or Interface Definition Language (IDL) between Ruby and Rust.
+
+**Example:**
+```ruby
+# This is just a piece of data, not a "live" widget
+paragraph = RatatuiRuby::Paragraph.new(
+  text: "Hello World",
+  style: RatatuiRuby::Style.new(fg: :red),
+  block: nil
+)
+```
+
+### 2. Immediate Mode Rendering
+
+The application loop typically looks like this:
+
+1.  **Poll Event**: Ruby asks Rust for the next event.
+2.  **Update State**: Ruby application code updates its own domain state (e.g., `counter += 1`).
+3.  **Render**: Ruby constructs a fresh View Tree based on the current domain state and passes the root node to `RatatuiRuby.draw`.
+
+```ruby
+loop do
+  # 1. & 2. Handle events and update state
+  event = RatatuiRuby.poll_event
+  break if event[:type] == :key && event[:code] == "esc"
+
+  # 3. Construct View Tree
+  ui = RatatuiRuby::Paragraph.new(text: "Time: #{Time.now}")
+
+  # 4. Draw
+  RatatuiRuby.draw(ui)
+end
+```
+
+### 3. No render logic in Ruby
+
+The Ruby classes in `lib/ratatui_ruby/schema/` should **not** contain rendering logic. They are strictly for structural definition and validation. All rendering logic resides in the Rust extension (`ext/ratatui_ruby/`), which walks this Ruby object tree and produces Ratatui primitives.
+
+## Adding a New Widget
+
+To add a new widget to the Ruby frontend:
+
+1.  Define the class in `lib/ratatui_ruby/schema/`.
+2.  Use `Data.define`.
+3.  Ensure attribute names match what the Rust rendering logic expects (see `ext/ratatui_ruby/src/widgets/`).
+
+```ruby
+# lib/ratatui_ruby/schema/my_widget.rb
+module RatatuiRuby
+  # A widget that does something specific.
+  #
+  # [some_property] The description of the property.
+  # [style] The style to apply.
+  # [block] Optional block widget.
+  class MyWidget < Data.define(:some_property, :style, :block)
+    # Creates a new MyWidget.
+    #
+    # [some_property] The description of the property.
+    # [style] The style to apply.
+    # [block] Optional block widget.
+    def initialize(some_property:, style: nil, block: nil)
+      super
+    end
+  end
+end
+```
+
+And define the types in the corresponding `.rbs` file:
+
+```rbs
+# sig/ratatui_ruby/schema/my_widget.rbs
+module RatatuiRuby
+  class MyWidget < Data
+    attr_reader some_property: String
+    attr_reader style: Style?
+    attr_reader block: Block?
+
+    def self.new: (some_property: String, ?style: Style?, ?block: Block?) -> MyWidget
+  end
+end
+```

data/docs/contributors/design/rust_backend.md

@@ -0,0 +1,61 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Rust Backend Design (`ratatui_ruby` extension)
+
+This document describes the internal architecture of the `ratatui_ruby` Rust extension.
+
+## Architecture Guidelines
+
+The project follows a **Structured Design** approach, separating concerns into modules to improve cohesiveness and testability.
+
+### Core Principles
+
+1.  **Single Generic Renderer**: The backend implements a single generic renderer that accepts a Ruby `Value` representing the root of the view tree.
+2.  **No Custom Rust Structs for UI**: Do not define custom Rust structs that mirror Ruby UI components. Instead, extract data directly from Ruby objects using `funcall`.
+3.  **Dynamic Dispatch**: Use `value.class().name()` (e.g., `"RatatuiRuby::Paragraph"`) to dynamically dispatch rendering logic to the appropriate widget module.
+4.  **Immediate Mode**: The renderer traverses the Ruby object tree every frame and rebuilds the Ratatui widget tree on the fly.
+
+### Module Structure
+
+The Rust extension is located in `ext/ratatui_ruby/src/` and is organized as follows:
+
+*   **`lib.rs`**: The entry point for the compiled extension. It defines the Ruby module structure using `magnus` and exports public functions (`init_terminal`, `draw`, `poll_event`). It wires together the submodules.
+*   **`terminal.rs`**: Encapsulates the global `TERMINAL` state (mutex-wrapped `CrosstermBackend`). It provides functions to initialize and restore the terminal to raw mode.
+*   **`events.rs`**: Handles keyboard input polling and mapping Crossterm events to Ruby hashes.
+*   **`style.rs`**: Provides pure functions for parsing styling information (Colors, Styles, Blocks) from Ruby values.
+*   **`rendering.rs`**: The central dispatcher for the render loop. It takes the top-level Ruby View Tree node and recursively delegates to specific widget implementations based on the Ruby class name.
+*   **`widgets/`**: A directory containing individual modules for each Ratatui widget (e.g., `paragraph.rs`, `list.rs`).
+
+### Adding a New Widget
+
+To add a new widget:
+
+1.  Create a new file `src/widgets/my_widget.rs`.
+2.  Implement a public `render` function:
+    ```rust
+    /// Renders the widget to the given area.
+    ///
+    /// # Arguments
+    ///
+    /// * `frame` - The Ratatui frame to render to.
+    /// * `area` - The rectangular area within the frame to draw the widget.
+    /// * `node` - The Ruby object (Value) containing the widget's properties.
+    pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error>
+    ```
+3.  Inside `render`:
+    *   Extract properties from the `node` (Ruby value) using `.funcall("method_name", ())?`.
+    *   Construct the Ratatui widget.
+    *   Render it using `frame.render_widget`.
+4.  Register the module in `src/widgets/mod.rs`.
+5.  Add a dispatch arm in `src/rendering.rs` matching the Ruby class name (e.g., `RatatuiRuby::MyWidget`).
+
+### Testing Strategy
+
+*   **Unit Tests (`cargo test`)**:
+    *   **Logic**: Test pure logic like `parse_color` in `style.rs` without needing a terminal or Ruby VM if possible (though `magnus::Value` usually requires it).
+    *   **Rendering**: Verify that widgets render *something* to a buffer. Ratatui's `TestBackend` or `Buffer` can be used to assert that cells are filled.
+*   **Integration Tests (`rake test`)**:
+    *   Run Ruby scripts that exercise the full stack. Verify no crashes and expected return values.

data/docs/contributors/design.md

@@ -0,0 +1,11 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Design Documentation
+
+This directory contains detailed design documents for the `ratatui_ruby` project.
+
+*   [Rust Backend Design](design/rust_backend.md): Details on the internal architecture of the Rust extension (`ext/ratatui_ruby`), including module structure, rendering pipeline, and widget implementation guide.
+*   [Ruby Frontend Design](design/ruby_frontend.md): Explains the Data-Driven UI, Immediate Mode paradigm, and the View Tree structure.

data/docs/contributors/index.md

@@ -0,0 +1,16 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# **ratatui_ruby** Contributors’ Documentation
+
+
+## Documentation for Contributors
+
+- [Contributing Guidelines](../../CONTRIBUTING.md)
+- [The Design of **ratatui_ruby**](./design.md)
+
+## Documentation for Users
+
+- [README](../../README.md)
+- [More Documentation for Users](../index.md)

data/docs/index.md

@@ -0,0 +1,18 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# **ratatui_ruby** Documentation
+
+
+## Documentation for Users
+
+- [README](../README.md)
+- [Quickstart](./quickstart.md)
+- [Testing Your Application](./application_testing.md)
+
+
+## Documentation for Contributors
+
+- [Contributing Guidelines](../CONTRIBUTING.md)
+- [More Documentation for Contributors](./contributors/index.md)

data/docs/quickstart.md

@@ -0,0 +1,126 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Quickstart
+
+Welcome to **ratatui_ruby**! This guide will help you get up and running with your first Terminal User Interface in Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ratatui_ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install ratatui_ruby
+```
+
+## Basic Application
+
+Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby** app.
+
+```ruby
+require "ratatui_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::Paragraph.new(
+      text: "Hello, Ratatui! Press 'q' to quit.",
+      block: RatatuiRuby::Block.new(
+        title: "My First App",
+        borders: [:all],
+        border_style: "cyan"
+      ),
+      alignment: :center
+    )
+
+    # 3. Draw the UI
+    RatatuiRuby.draw(view)
+
+    # 4. Poll for events
+    event = RatatuiRuby.poll_event
+    if event && event[:type] == :key && event[:code] == "q"
+      break
+    end
+  end
+ensure
+  # 5. Restore the terminal to its original state
+  RatatuiRuby.restore_terminal
+end
+```
+
+### How it works
+
+1.  **`RatatuiRuby.init_terminal`**: Enters raw mode and switches to the alternate screen.
+2.  **Immediate Mode UI**: On every iteration of the loop, you describe what the UI should look like by creating `Data` objects (like `Paragraph` and `Block`).
+3.  **`RatatuiRuby.draw(view)`**: The Ruby UI tree is passed to the Rust backend, which renders it to the terminal.
+4.  **`RatatuiRuby.poll_event`**: Checks for keyboard, mouse, or resize events.
+5.  **`RatatuiRuby.restore_terminal`**: Crucial for leaving raw mode and returning the user to their shell properly. Always wrap your loop in a `begin...ensure` block to guarantee this runs.
+6.  **`sleep 0.05`**: In a real app, you'd want to control your frame rate to avoid consuming 100% CPU.
+
+## Examples
+
+To see more complex layouts and widget usage, check out the `examples/` directory in the repository.
+
+### [Analytics](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/analytics.rb)
+Demonstrates the use of `Tabs` and `BarChart` widgets with a simple data-switching mechanism.
+
+![Analytics Screenshot](./images/examples-analytics.rb.png)
+
+### [Box Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/box_demo.rb)
+A simple demonstration of `Block` and `Paragraph` widgets, reacting to arrow key presses to change colors.
+
+![Box Demo Screenshot](./images/examples-box_demo.rb.png)
+
+### [Dashboard](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/dashboard.rb)
+Uses `Layout`, `List`, and `Paragraph` to create a classic sidebar-and-content interface.
+
+![Dashboard Screenshot](./images/examples-dashboard.rb.png)
+
+### [Login Form](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/login_form.rb)
+Shows how to use `Overlay`, `Center`, and `Cursor` to build a modal login form with text input.
+
+![Login Form Screenshot](./images/examples-login_form.rb.png)
+
+### [Map Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/map_demo.rb)
+Exhibits the `Canvas` widget's power, rendering a world map along with animated circles and lines.
+
+![Map Demo Screenshot](./images/examples-map_demo.rb.png)
+
+### [Mouse Events](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/mouse_events.rb)
+Detailed plumbing of mouse events, including clicks, drags, and movement tracking.
+
+![Mouse Events Screenshot](./images/examples-mouse_events.rb.png)
+
+### [Scrollbar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scrollbar_demo.rb)
+A simple example of integrating the `Scrollbar` widget and handling mouse wheel events for scrolling.
+
+![Scrollbar Demo Screenshot](./images/examples-scrollbar_demo.rb.png)
+
+### [Stock Ticker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/stock_ticker.rb)
+Utilizes `Sparkline` and `LineChart` widgets to visualize real-time (simulated) data.
+
+![Stock Ticker Screenshot](./images/examples-stock_ticker.rb.png)
+
+### [System Monitor](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/system_monitor.rb)
+Combines `Table` and `Gauge` widgets in a vertical layout to create a functional system overview.
+
+![System Monitor Screenshot](./images/examples-system_monitor.rb.png)
+

data/examples/analytics.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+require_relative "../lib/ratatui_ruby"
+
+# Analytics Dashboard Example
+# Demonstrates Tabs and BarChart widgets.
+
+class AnalyticsApp
+  def initialize
+    @selected_tab = 0
+    @tabs = ["Revenue", "Traffic", "Errors"]
+  end
+
+  def run
+    RatatuiRuby.init_terminal
+    begin
+      loop do
+        render
+        break if handle_input == :quit
+        sleep 0.05
+      end
+    ensure
+      RatatuiRuby.restore_terminal
+    end
+  end
+
+  def render
+    # Data for different tabs
+    data = case @selected_tab
+           when 0 # Revenue
+             { "Q1" => 50, "Q2" => 80 }
+           when 1 # Traffic
+             { "Mon" => 120, "Tue" => 150 }
+           when 2 # Errors
+             { "DB" => 5, "UI" => 2 }
+    end
+
+    style = case @selected_tab
+            when 0 then RatatuiRuby::Style.new(fg: "green")
+            when 1 then RatatuiRuby::Style.new(fg: "blue")
+            when 2 then RatatuiRuby::Style.new(fg: "red")
+    end
+
+    # Build the UI
+    ui = RatatuiRuby::Layout.new(
+      direction: :vertical,
+      constraints: [
+        RatatuiRuby::Constraint.new(type: :length, value: 3),
+        RatatuiRuby::Constraint.new(type: :min, value: 0),
+      ],
+      children: [
+        RatatuiRuby::Tabs.new(
+          titles: @tabs,
+          selected_index: @selected_tab,
+          block: RatatuiRuby::Block.new(title: "Views", borders: [:all])
+        ),
+        RatatuiRuby::BarChart.new(
+          data:,
+          bar_width: 10,
+          style:,
+          block: RatatuiRuby::Block.new(title: "Analytics: #{@tabs[@selected_tab]}", borders: [:all])
+        ),
+      ]
+    )
+
+    RatatuiRuby.draw(ui)
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    if event
+      case event[:code]
+      when "q"
+        :quit
+      when "right"
+        @selected_tab = (@selected_tab + 1) % @tabs.size
+      when "left"
+        @selected_tab = (@selected_tab - 1) % @tabs.size
+      end
+    end
+  end
+end
+
+AnalyticsApp.new.run if __FILE__ == $0