ratatui_ruby 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 996cd8cc08b1f95614ad8ff31c735fcee9150cebaa35ced2d844088e34730390
-  data.tar.gz: 4156030673a39867c6a99036cb6618910110c0d287c94500d601047163d87524
+  metadata.gz: 0e4a0958532fe7b493fcf0d9ee971bbc94194f5ff03fd420f895197597dac1c8
+  data.tar.gz: 480c3a5a467d478626a12c739064f894952e23d7a4574d0ad73a21dcc7b80ff5
 SHA512:
-  metadata.gz: 9d08516a876ec1265246ebbb2855e647e2fc50846756abb07a466a8506aaf1acf5b0547276faedc017b44795b9d237b4ac1003796209094868e627a482a0fbd3
-  data.tar.gz: 573b6c07ba542e1f5399da620b502a09cc999f70ae4dfa14f49974994e3b22d3bff2458c2076aa920281c418a232984834fbb6f6fd306f1a2a951ac308158f91
+  metadata.gz: 28f9f71581859a3ddaecb62df012e942fa3617dfcac1634af88e84b676b13802d3bb0bf7443ebba96f2bc1a00f503e86b8a2e2d3d6f613864d35b7002d432dac
+  data.tar.gz: f08716e00372054fcbee63e44ecb39e692ec2cc0b23d6e5596243b6df5c248274bf5b750b376d004644d8cf7a91993bde3e7c5dc980856befe84e0ce680de7b5

data/.builds/ruby-3.2.yml

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+image: alpine/edge
+packages:
+  - bash
+  - build-base
+  - curl
+  - openssl-dev
+  - yaml-dev
+  - zlib-dev
+  - readline-dev
+  - gdbm-dev
+  - ncurses-dev
+  - libffi-dev
+  - clang-dev
+  - git
+artifacts:
+  - ratatui_ruby/pkg/ratatui_ruby-0.3.0.gem
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby
+tasks:
+  - setup: |
+      curl https://mise.jdx.dev/install.sh | sh
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
+      echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      . ~/.buildenv
+      export RUSTFLAGS="-C target-feature=-crt-static"
+      export CI="true"
+      cd ratatui_ruby
+      sed -i 's/ruby = .*/ruby = "3.2"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:2.6.9
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+      mise x -- bundle exec rake compile
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Testing Ruby 3.2"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Linting Ruby 3.2"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      mise x -- bundle exec rake build

data/.builds/ruby-3.3.yml

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+image: alpine/edge
+packages:
+  - bash
+  - build-base
+  - curl
+  - openssl-dev
+  - yaml-dev
+  - zlib-dev
+  - readline-dev
+  - gdbm-dev
+  - ncurses-dev
+  - libffi-dev
+  - clang-dev
+  - git
+artifacts:
+  - ratatui_ruby/pkg/ratatui_ruby-0.3.0.gem
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby
+tasks:
+  - setup: |
+      curl https://mise.jdx.dev/install.sh | sh
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
+      echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      . ~/.buildenv
+      export RUSTFLAGS="-C target-feature=-crt-static"
+      export CI="true"
+      cd ratatui_ruby
+      sed -i 's/ruby = .*/ruby = "3.3"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:2.6.9
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+      mise x -- bundle exec rake compile
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Testing Ruby 3.3"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Linting Ruby 3.3"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      mise x -- bundle exec rake build

data/.builds/ruby-3.4.yml

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+image: alpine/edge
+packages:
+  - bash
+  - build-base
+  - curl
+  - openssl-dev
+  - yaml-dev
+  - zlib-dev
+  - readline-dev
+  - gdbm-dev
+  - ncurses-dev
+  - libffi-dev
+  - clang-dev
+  - git
+artifacts:
+  - ratatui_ruby/pkg/ratatui_ruby-0.3.0.gem
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby
+tasks:
+  - setup: |
+      curl https://mise.jdx.dev/install.sh | sh
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
+      echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      . ~/.buildenv
+      export RUSTFLAGS="-C target-feature=-crt-static"
+      export CI="true"
+      cd ratatui_ruby
+      sed -i 's/ruby = .*/ruby = "3.4"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:2.6.9
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+      mise x -- bundle exec rake compile
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Testing Ruby 3.4"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Linting Ruby 3.4"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      mise x -- bundle exec rake build

data/.builds/ruby-4.0.0.yml

@@ -0,0 +1,53 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+image: alpine/edge
+packages:
+  - bash
+  - build-base
+  - curl
+  - openssl-dev
+  - yaml-dev
+  - zlib-dev
+  - readline-dev
+  - gdbm-dev
+  - ncurses-dev
+  - libffi-dev
+  - clang-dev
+  - git
+artifacts:
+  - ratatui_ruby/pkg/ratatui_ruby-0.3.0.gem
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby
+tasks:
+  - setup: |
+      curl https://mise.jdx.dev/install.sh | sh
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
+      echo 'eval "$($HOME/.local/bin/mise activate bash)"' >> ~/.buildenv
+      . ~/.buildenv
+      export RUSTFLAGS="-C target-feature=-crt-static"
+      export CI="true"
+      cd ratatui_ruby
+      sed -i 's/ruby = .*/ruby = "4.0.0"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:2.6.9
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+      # We allow this to fail so we can see logs without stopping the CI pipeline
+      mise x -- bundle exec rake compile || echo "⚠️ Compilation failed (Allowed Failure)"
+  - test: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Testing Ruby 4.0.0"
+      mise x -- bundle exec rake test || true
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Linting Ruby 4.0.0"
+      mise x -- bundle exec rake lint || true
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      mise x -- bundle exec rake build

data/.pre-commit-config.yaml

@@ -3,7 +3,14 @@
 repos:
   - repo: local
     hooks:
+      -   id: bundle-check
+          name: Check Gemfile.lock
+          entry: bundle check
+          language: system
+          files: (Gemfile|Gemfile\.lock|ratatui_ruby\.gemspec)
+          pass_filenames: false
       -   id: rake
           name: rake
-          entry: rake
-          language: ruby
+          entry: bundle exec rake
+          language: system
+          pass_filenames: false

data/AGENTS.md

@@ -35,14 +35,14 @@ Every file must begin with an SPDX-compliant header. Use the following format:
 
 ### Ruby Standards
 
--   **Version:** Strict Ruby 3.4 compatibility (Target `3.4.7` as per cosmoruby).
--   **Linter:** Run via `rake lint`. You are not done until all linting passes.
+-   **Version:** Tested against the latest releases of Ruby 3.2, 3.3, and 3.4, and must work. Also tested in CI (with allowed failures) against the latest preview Ruby 4.0 to prepare for its release. Local development happens on the latest stable release.
+-   **Linter:** Run via `bundle exec rake lint`. You are not done until all linting passes.
 -   **Style:**
     -   Use `Data.define` for all value objects (UI Nodes). (Prefer `class Foo < Data.define()` over `Foo = Data.define() do`).
     -   Prefer `frozen_string_literal: true`.
     -   Use `Minitest` for testing.
     -   Define types in `.rbs` files. Don't use `untyped` just because it's easy; be comprehensive and accurate. Do not include `initialize` in `.rbs` files; use `self.new` for constructors instead.
-    -   Every line of Ruby must be covered by tests that would stand up to mutation testing. This includes all examples in the `examples/` directory; they should have corresponding tests in `examples/` to ensure they continue to work as intended and serve as reliable documentation. Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code "doesn't crash" is insufficient and unacceptable.
+    -   Every line of Ruby must be covered by tests that would stand up to mutation testing. This includes all examples in the `examples/` directory; they should have corresponding tests in `examples/` to ensure they continue to work as intended and serve as reliable documentation. Tests must be meaningful and verify specific behavior or rendering output; simply verifying that code "doesn't crash" is insufficient and unacceptable. For UI widgets, this means using `with_test_terminal` to verify every character of the terminal buffer's content.
     -   Every public Ruby class/method must be documented for humans in RDoc (preferred)--**not** YARD--or markdown files (fallback), and must have `*.rbs` types defined.
     -   Every significant architectural and design decision must be documented for contributors in markdown files. Mermaid is allowed.
 
@@ -94,14 +94,15 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 ### Development Environment
 
 -   **Setup:** `bin/setup` must handle both Bundler and Cargo dependencies.
--   **Pre-commit:** Use `.pre-commit-config.yaml` to enforce `rake` and `cargo fmt`.
+-   **Pre-commit:** Use `.pre-commit-config.yaml` to enforce `bundle exec rake` and `cargo fmt`.
 
 ### Documentation
 
 -   Follow the `docs/` structure: `index.md` -> `contributors/` | `quickstart.md`.
 -   Documentation should separate "User Guide" (Ruby API for TUI developers) from "Contributor Guide" (Ruby/Rust/Magnus internals).
 -   Don't write .md files for something RDoc (Ruby) or rustdoc (Rust) can generate.
--   **Never edit the `doc/` folder directly.** It is automatically generated by `rake rerdoc`. If you need to refresh the generated documentation, run that command instead.
+-   **The `doc/` folder contains source markdown files** that are included in RDoc output. You can edit these files.
+-   **The `tmp/rdoc/` folder is auto-generated** by `bundle exec rake rerdoc`. Never edit files in `tmp/rdoc/` directly.
 
 ## 4. The Ruby <-> Rust Bridge Contract
 
@@ -117,3 +118,50 @@ The project follows a standard Gem layout with an `ext/` directory for Rust code
 
 -   The gem builds a native extension.
 -   Artifact naming: Ensure the output shared library matches Ruby's expectation on macOS (rename `.dylib`to `.bundle` if necessary during the build process in `extconf.rb` or `Rakefile`).
+
+## 6. Source Control Standards
+
+-   **Commits:**
+    -   Who commits: Only humans should affect the git index and history. Rather than staging and/or committing, you should suggest a commit message.
+    -   When: At the end of each task, before reporting the task as complete to the user, suggest the commit message.
+-   **Format:**
+    -   Subject line: Concise summary (50 chars or less).
+    -   Body: Detailed explanation if necessary (wrap at 72 chars). Explain why this is the implementation, as opposed to other possible implementations. Skip the body entirely if it's rote, a duplication of the diff, or otherwise unhelpful. **Do not simply list the files changed or the minor edits made to them.** Do not use markdown, except as required in AI Attribution.
+    -   Footer: AI attribution if generated by an agent, sourcehut ticket if implemented by a ticket, or both.
+-   **AI Attribution:**
+    -   **Antigravity:**
+        Specify the model used in the footer. Examples:
+        ```
+        Generated with [Antigravity](https://antigravity.google)
+
+        Co-Authored-By: Gemini 3 Pro (High) <noreply@google.com>
+        ```
+        ```
+        Generated with [Antigravity](https://antigravity.google)
+
+        Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
+        ```
+    -   **Gemini 3:**
+        ```
+        Generated with [Gemini 3 Pro](https://gemini.google.com/)
+
+        Co-Authored-By: Gemini 3 Pro <noreply@google.com>
+        ```
+    -   **JetBrains Junie:**
+        ```
+        Generated with [JetBrains Junie](https://www.jetbrains.com/ai/)
+
+        Co-Authored-By: Junie <junie@jetbrains.com>
+        ```
+-   **Sourcehut Tickets:**
+    - If the commit implements a specific ticket, include a footer: `Implements: https://todo.sr.ht/~kerrick/ratatui_ruby/<id>`
+    - This must be the **last** item in the footer, if present.
+
+## 7. Definition of Done
+
+Before considering a task complete and returning control to the user, you **MUST** ensure:
+
+1.  **Tests & Linting Pass:** Run `bundle exec rake` and confirm it passes. No new errors **or warnings** should be introduced.
+2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files,.
+3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section according to the [Semantic Versioning](https://semver.org/) and [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) specifications. Changelogs should be useful to human users of the library, not simple restatements of diffs or commit messages. **Do not add entries for internal tooling, CI, or build configuration changes that do not affect the distributed gem.**
+4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.

data/CHANGELOG.md

@@ -12,4 +12,54 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
-- Created the gem
+### Changed
+
+### Fixed
+
+### Removed
+
+## [0.3.0] - 2025-12-28
+
+### Added
+
+- **The Escape Hatch (Ruby Render Callback)**: Added the ability to define custom widgets in pure Ruby by implementing a `render(area, buffer)` method. The `Buffer` object provides low-level drawing primitives like `set_string`, allowing developers to create custom TUI components without writing Rust code.
+- **Clear Widget**: Added the `Clear` widget, which resets the terminal buffer in the area it is rendered. This is essential for creating opaque popups and modals that prevent background styles from "bleeding" through transparent widgets.
+- **Interactive Table Selection**: The `Table` widget now supports row selection with `selected_row`, `highlight_style`, and `highlight_symbol` parameters. This enables building interactive data grids and file explorers where users can navigate through rows using keyboard input.
+- **Scrollable Paragraphs**: The `Paragraph` widget now supports a `scroll` parameter that accepts a `(y, x)` array to scroll content vertically and horizontally. This enables viewing long text content that exceeds the visible area, such as logs or documents. The parameter order matches ratatui's convention.
+
+### Changed
+
+- **Center Widget**: Removed the implicit `Clear` call from the `Center` widget. `Center` is now a pure layout widget, requiring an explicit `Clear` widget if background clearing is desired. This restores correct behavior for transparent overlays.
+
+## [0.2.0] - 2025-12-24
+
+### Added
+
+- **DSL for Simpler Apps**: Introduced `RatatuiRuby.main_loop`, a new entrypoint that simplifies application structure when you don't need control of the event loop or application lifecycle.
+- **Calendar Widget**: Added the `Calendar` widget, allowing you to display monthly views and visualize date-based information.
+- **Generic Charts**: Implemented the full `Chart` widget, which supersedes the now-deprecated `LineChart` and `BarChart` widgets, giving you more freedom to visualize data sets.
+- **Enhanced List Styling**: You can now customize the appearance of selected items in a `List` using `highlight_style` and `highlight_symbol`.
+- **Broader Ruby Support**: Added support for a wider range of Ruby versions: every non-EOL version. The latest preview of Ruby 4.0 is tested in CI, but not supported.
+- **Dev Tools**: Added internal Rake tasks for managing historical documentation and SemVer checks.
+
+## [0.1.0] - 2025-12-22
+
+### Added
+
+- **First Release**: Initial public release of `ratatui_ruby`, bringing the power of the Rust [ratatui](https://github.com/ratatui-org/ratatui) library to Rubyists!
+- **Core Widget Set**: Includes a comprehensive suite of widgets to get you started:
+  - `Block`, `Borders`, and `Paragraph` for basic content.
+  - `List` and `Table` for structured data.
+  - `Gauge` and `Sparkline` for progress and metrics.
+  - `Tabs` for navigation.
+  - `Canvas` for drawing shapes (Lines, Circles, Rectangles, Maps).
+- **Layout System**: A flexible layout engine using `Flex`, `Layout`, and `Constraints` to build responsive interfaces that adapt to any terminal size.
+- **Forms & Layers**: Primitives like `Overlay` and `Center` for creating modal dialogs, plus a `Cursor` widget for text input interactions.
+- **Styling**: Full support for `Ratatui`'s styling primitives, including modifiers and RGB/ANSI colors.
+- **Input Handling**: Robust handling for both Keyboard and Mouse events.
+- **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
+
+[Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.3.0...HEAD
+[0.3.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.2.0...v0.3.0
+[0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby/compare/v0.1.0...v0.2.0
+[0.1.0]: https://git.sr.ht/~kerrick/ratatui_ruby/tree/v0.1.0

data/README.md

@@ -4,18 +4,26 @@
 -->
 # ratatui_ruby
 
-> [!NOTE]  
-> **ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
+[![
+builds.sr.ht status](https://builds.sr.ht/~kerrick/ratatui_ruby.svg)](https://builds.sr.ht/~kerrick/ratatui_ruby?) [![
+License](https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fratatui_ruby.gemspec&search=spec%5C.license%20%3D%20%22(.*)%22&replace=%241&label=License&color=a2c93e)](https://spdx.org/licenses/AGPL-3.0-or-later.html) [![
+Gem Total Downloads](https://img.shields.io/gem/dt/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
+Gem Version](https://img.shields.io/gem/v/ratatui_ruby)](https://rubygems.org/gems/ratatui_ruby) [![
+Ratatui Version](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fgit.sr.ht%2F~kerrick%2Fratatui_ruby%2Fblob%2Fmain%2Fext%2Fratatui_ruby%2FCargo.toml&query=%24.dependencies.ratatui.version&prefix=v&logo=ratatui&label=Ratatui)](https://crates.io/crates/ratatui/0.26.3) [![
+Mailing List: Discussion](https://img.shields.io/badge/mailing_list-discussion-5865F2.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) [![
+Mailing List: Development](https://img.shields.io/badge/mailing_list-development-4954d5.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) [![
+Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcements-3b44ac.svg?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmZmZmYiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBjbGFzcz0iaWNvbiBpY29uLXRhYmxlciBpY29ucy10YWJsZXItb3V0bGluZSBpY29uLXRhYmxlci1tYWlsIj48cGF0aCBzdHJva2U9Im5vbmUiIGQ9Ik0wIDBoMjR2MjRIMHoiIGZpbGw9Im5vbmUiLz48cGF0aCBkPSJNMyA3YTIgMiAwIDAgMSAyIC0yaDE0YTIgMiAwIDAgMSAyIDJ2MTBhMiAyIDAgMCAxIC0yIDJoLTE0YTIgMiAwIDAgMSAtMiAtMnYtMTB6IiAvPjxwYXRoIGQ9Ik0zIDdsOSA2bDkgLTYiIC8+PC9zdmc+Cg==)](https://lists.sr.ht/~kerrick/ratatui_ruby-announce)
 
 
 ## Introduction
 
 **ratatui_ruby** is a Ruby wrapper for [Ratatui](https://ratatui.rs). It allows you to cook up Terminal User Interfaces in Ruby.
+**ratatui_ruby** is a community wrapper that is not affiliated with [the Ratatui team](https://github.com/orgs/ratatui/people).
 
 > [!WARNING]  
 > **ratatui_ruby** is currently in an early stage of development. Use at your own risk.
 
-Please join our **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements.
+Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements.
 
 
 ## Compatibility
@@ -25,13 +33,17 @@ Please join our **announce** mailing list at https://lists.sr.ht/~kerrick/ratatu
 - GNU/Linux, macOS, Windows, OpenBSD, and FreeBSD; and
 - x86_64 (AMD, Intel) and ARM (Apple Silicon, Raspberry Pi).
 
+We support the latest minor version of every
+[non-eol Ruby version](https://www.ruby-lang.org/en/downloads/branches/).
+Support for Ruby 4 is coming soon.
+
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'ratatui_ruby'
+gem "ratatui_ruby"
 ```
 
 And then execute:
@@ -40,7 +52,7 @@ And then execute:
 bundle install
 ```
 
-Or install it yourself as:
+Or install it yourself with:
 
 ```bash
 gem install ratatui_ruby
@@ -49,38 +61,46 @@ gem install ratatui_ruby
 
 ## Usage
 
-**ratatui_ruby** uses an immediate-mode API. You describe your UI using Ruby `Data` objects and call `draw` in a loop.
+**ratatui_ruby** uses an immediate-mode API. You describe your UI using Ruby objects and call `draw` in a loop.
 
 ```ruby
-RatatuiRuby.init_terminal
-begin
-  view = RatatuiRuby::Paragraph.new(text: "Hello World", block: RatatuiRuby::Block.new(borders: [:all]))
-  RatatuiRuby.draw(view)
-  sleep 2
-ensure
-  RatatuiRuby.restore_terminal
+require "ratatui_ruby"
+RatatuiRuby.main_loop do |tui|
+  tui.draw \
+    tui.paragraph \
+        text: "Hello, Ratatui! Press 'q' to quit.",
+        align: :center,
+        block: tui.block(
+          title: "My Ruby TUI App",
+          borders: [:all],
+          border_color: "cyan"
+        )
+  event = tui.poll_event
+  break if event && event[:type] == :key && event[:code] == "q"
 end
 ```
 
-For a full tutorial, see [the Quickstart](./docs/quickstart.md).
+For a full tutorial, see [the Quickstart](./doc/quickstart.md).
 
 
 ## Documentation
 
-For the full documentation on how to use **ratatui_ruby**, see our [docs](./docs/index.md).
+For the full documentation on how to use **ratatui_ruby**, see the [documentation](./doc/index.md).  For other information, see the [wiki](https://man.sr.ht/~kerrick/ratatui_ruby).
 
 
 ## Contributing
 
-Bug reports and pull requests are welcome on [sourcehut](https://sourcehut.org) at https://sr.ht/~kerrick/ratatui_ruby/. This project is intended to be a safe, productive collaboration, and contributors are expected to adhere to the [Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct/).
+Bug reports and pull requests are welcome on [sourcehut](https://sourcehut.org) at https://sr.ht/~kerrick/ratatui_ruby/. This project is intended to be a safe, productive collaboration, and contributors are expected to adhere to the [Code of Conduct](https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md).
 
 Issues for the underlying Rust library should be filed at [ratatui/ratatui](https://github.com/ratatui/ratatui).
 
-Want to help develop **ratatui_ruby**? Check out our [contribution guide](./CONTRIBUTING.md).
+Want to help develop **ratatui_ruby**? Check out the [contribution guide on the wiki](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md).
 
 
 ## Copyright & License
 
 **ratatui_ruby** is copyright 2025, Kerrick Long. **ratatui_ruby** is licensed under the GNU Affero General Public License v3.0 or later; see [LICENSES/AGPL-3.0-or-later.txt](./LICENSES/AGPL-3.0-or-later) for the full text.
 
-Some parts of this program are copied from other sources under appropriate reuse licenses, and the copyright belongs to their respective owners. See the [REUSE Specification – Version 3.3](https://reuse.software/spec-3.3/) for information about how we comply with attribution and licensing requirements.
+Some parts of this program are copied from other sources under appropriate reuse licenses, and the copyright belongs to their respective owners. See the [REUSE Specification – Version 3.3](https://reuse.software/spec-3.3/) for information about how we comply with attribution and licensing requirements.
+
+This program was created with significant assistance from multiple LLMs. The process was human-controlled through creative prompts, with human contributions to each commit. See commit footers for model attribution. [declare-ai.org](https://declare-ai.org/1.0.0/creative.html)

data/REUSE.toml

@@ -15,3 +15,8 @@ SPDX-License-Identifier = "CC0-1.0"
 path = 'ext/ratatui_ruby/Cargo.lock'
 SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "CC0-1.0"
+
+[[annotations]]
+path = 'doc/images/*.png'
+SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "CC-BY-SA-4.0"

data/Rakefile

@@ -4,105 +4,8 @@
 # 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
+# Import all tasks from the tasks/ directory
+Dir.glob("tasks/*.rake").each { |r| import r }
 
-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]
+task default: %w[sourcehut test lint]

data/{docs → doc}/contributors/index.md

@@ -7,7 +7,8 @@
 
 ## Documentation for Contributors
 
-- [Contributing Guidelines](../../CONTRIBUTING.md)
+- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md)
+- [Documentation Guide](https://man.sr.ht/~kerrick/ratatui_ruby/documentation_guide.md)
 - [The Design of **ratatui_ruby**](./design.md)
 
 ## Documentation for Users

data/doc/custom.css

@@ -0,0 +1,8 @@
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+.theme-toggle {
+  margin-left: 0 !important;
+}