ratatui_ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 996cd8cc08b1f95614ad8ff31c735fcee9150cebaa35ced2d844088e34730390
+  data.tar.gz: 4156030673a39867c6a99036cb6618910110c0d287c94500d601047163d87524
+SHA512:
+  metadata.gz: 9d08516a876ec1265246ebbb2855e647e2fc50846756abb07a466a8506aaf1acf5b0547276faedc017b44795b9d237b4ac1003796209094868e627a482a0fbd3
+  data.tar.gz: 573b6c07ba542e1f5399da620b502a09cc999f70ae4dfa14f49974994e3b22d3bff2458c2076aa920281c418a232984834fbb6f6fd306f1a2a951ac308158f91

data/.build.yml

@@ -0,0 +1,34 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - ruby
+  - rust
+  - cargo
+  - make
+  - gcc
+  - clang
+sources:
+  - https://git.sr.ht/~kerrick/ratatui_ruby
+tasks:
+  - setup: |
+      cd ratatui_ruby
+      export PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin"
+      gem install --user-install bundler -v 2.6.9
+      bundle config set --local path 'vendor/bundle'
+      bundle install
+  - test: |
+      cd ratatui_ruby
+      export PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin"
+      bundle config set --local path 'vendor/bundle'
+      # Compile the extension before running tests
+      bundle exec rake compile
+      # Run the test suite (Headless)
+      bundle exec rake test
+  - package: |
+      cd ratatui_ruby
+      export PATH="$PATH:$(ruby -e 'puts Gem.user_dir')/bin"
+      bundle config set --local path 'vendor/bundle'
+      # Verify packaging works
+      gem build ratatui_ruby.gemspec

data/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2020 Free Software Foundation Europe e.V.
+# SPDX-License-Identifier: CC0-1.0
+repos:
+  - repo: local
+    hooks:
+      -   id: rake
+          name: rake
+          entry: rake
+          language: ruby

data/.rubocop.yml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+inherit_from:
+  - ./vendor/goodcop/base.yml
+
+AllCops:
+  TargetRubyVersion: "3.3"

data/.ruby-version

@@ -0,0 +1 @@
+3.4.7

data/AGENTS.md

@@ -0,0 +1,119 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+# AGENTS.md
+
+## Project Identity
+
+Project Name: ratatui_ruby
+
+Description: A high-performance Ruby wrapper for the Ratatui TUI library.
+
+Architecture:
+
+-   **Frontend (Ruby):** Pure `Data` objects (Ruby 3.2+) defining the View Tree. Immediate mode.
+-   **Backend (Rust):** A generic renderer using `ratatui` and `magnus` that traverses the Ruby `Data` tree and renders to the terminal buffer.
+
+## 1. File & Coding Standards
+
+### Licensing & Copyright (Strict)
+
+Every file must begin with an SPDX-compliant header. Use the following format:
+
+```ruby
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+```
+
+-   **Ruby/Rust/Config files:** Use comments appropriate for the language (`#` or `//`).
+-   **Markdown:** Use HTML comment style `<!-- -->`.
+-   **Exceptions:** `REUSE.toml` manages exceptions (e.g., binary files or `.gitignore`).
+
+### 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.
+-   **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 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.
+
+### Rust Standards
+
+-   **Crate Type:** `cdylib`.
+-   **Linter:** `clippy` and `rustfmt`.
+-   **Bindings:** Use [magnus](https://github.com/matsadler/magnus).
+-   **Platform:** Support macOS (Apple Silicon), Linux, and Windows.
+-   **Linker Flags:** Must handle macOS `-undefined dynamic_lookup`.
+-   Every line of Rust must be covered by tests that would stand up to mutation testing. This includes every widget implementation in `ext/ratatui_ruby/src/widgets/`; each must have a `tests` module with unit tests verifying basic rendering. Tests must be meaningful; simply verifying that code "doesn't crash" or "compiles" is insufficient.
+
+## 2. Directory Structure Convention
+
+The project follows a standard Gem layout with an `ext/` directory for Rust code.
+
+```plaintext
+/
+├── .cargo/                 # Cargo configuration (linker flags)
+├── .github/                # CI/CD workflows
+├── bin/                    # Executables (console, setup)
+├── docs/                   # Documentation tree
+│   ├── contributors/       # Design docs, ecosystem notes
+│   └── index.md
+├── ext/
+│   └── ratatui_ruby/       # RUST SOURCE CODE GOES HERE
+│       ├── src/
+│       │   └── lib.rs      # Entry point
+│       ├── Cargo.toml
+│       └── extconf.rb      # Makefile generator
+├── lib/
+│   ├── ratatui_ruby/
+│   │   ├── schema/         # Ruby Data definitions
+│   │   └── version.rb
+│   └── ratatui_ruby.rb     # Main loader
+├── test/
+│   ├── data/               # Data-driven test files
+│   └── ratatui_ruby/       # Unit tests
+├── vendor/                 # Vendorized style configs (goodcop)
+├── AGENTS.md               # Context for AI agents
+├── Gemfile
+├── Rakefile
+├── REUSE.toml              # Compliance definition
+└── ratatui_ruby.gemspec
+```
+
+## 3. Configuration & Tooling
+
+### 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`.
+
+### 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.
+
+## 4. The Ruby <-> Rust Bridge Contract
+
+### The Ruby Side (`lib/`)
+
+-   Refer to [docs/contributors/design/ruby_frontend.md](docs/contributors/design/ruby_frontend.md) for detailed design philosophy regarding the Data-Driven UI and Immediate Mode paradigm.
+
+### The Rust Side (`ext/`)
+
+-   Refer to [docs/contributors/design/rust_backend.md](docs/contributors/design/rust_backend.md) for detailed implementation guidelines, module structure, and rendering logic.
+
+## 5. Deployment / Release
+
+-   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`).

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Created the gem

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# **ratatui_ruby** Code of Conduct
+
+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/).
+
+For your convenience, it is reproduced below. If this document ever falls out of date and/or conflicts with the linked [Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct/) document, the linked document takes precedence.
+
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2016 Yukihiro Matsumoto <matz@netlab.jp>
+  SPDX-License-Identifier: BSD-2-Clause
+-->
+
+
+## The Ruby Community Conduct Guideline
+
+> **We have picked the following conduct guideline based on an early proposed draft of the PostgreSQL CoC, for Ruby developers community for safe, productive collaboration. Each Ruby related community (conference etc.) may pick their own Code of Conduct.**
+> 
+> This document provides community guidelines for a safe, respectful, productive, and collaborative place for any person who is willing to contribute to the Ruby community. It applies to all “collaborative space”, which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.).
+> 
+> - Participants will be tolerant of opposing views.
+> - Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+> - When interpreting the words and actions of others, participants should always assume good intentions.
+> - Behaviour which can be reasonably considered harassment will not be tolerated.
+
+<!-- SPDX-SnippetEnd -->

data/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+<!--
+  SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Contribution Guide
+
+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/).
+
+
+## Reporting Issues
+
+Bug reports are welcome on [sourcehut](https://sourcehut.org) at https://todo.sr.ht/~kerrick/ratatui_ruby.
+
+Issues for Ratatui should be filed at [ratatui/ratatui](https://github.com/ratatui/ratatui).
+
+
+## Requesting Features
+
+ratatui_ruby aims to wrap all [Ratatui](https://ratatui.rs) features. Please request new features there.
+
+
+## Pull Requests
+
+Please join our **devel** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-devel. Then, send a pull request via email to the mailing list. 
+
+The easiest way to send a pull request via email is to use [git-send-email](https://git-scm.com/docs/git-send-email). If you are unfamiliar with using git to send a pull request via email, read the [four-step tutorial at git-send-email.io](https://git-send-email.io).
+
+Alternatively, [sourcehut](https://sourcehut.org) has a web UI you can use to prepare the email to send. [Read their documentation](https://man.sr.ht/git.sr.ht/#sending-patches-upstream) to find out if this is right for you.
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+## Contributors’ Documentation
+
+We have documentation on how **ratatui_ruby** works internally, how it is designed, and how it interacts with the official Ratatui projects. See the [contributors’ documentation index](docs/contributors/index.md) for more information.

data/LICENSE

@@ -0,0 +1,15 @@
+    ratatui_ruby -- Unofficial Ruby wrapper for Ratatui
+    Copyright (C) 2025  Kerrick Long
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published
+    by the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.