ratatui_ruby 0.1.0 → 0.2.0

checksums.yaml

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

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.2.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
+      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.2.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
+      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.2.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
+      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-preview3.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.2.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-preview3"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler
+      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-preview3"
+      mise x -- bundle exec rake test || true
+  - lint: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      echo "Linting Ruby 4.0.0-preview3"
+      mise x -- bundle exec rake lint || true
+  - package: |
+      . ~/.buildenv
+      cd ratatui_ruby
+      mise x -- bundle exec rake build

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).
+-   **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 `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.
 

data/README.md

@@ -4,13 +4,21 @@
 -->
 # 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.
@@ -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/),
+plus the latest preview of the next version.
+
 
 ## 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,16 +61,22 @@ 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
 ```
 
@@ -83,4 +101,6 @@ Want to help develop **ratatui_ruby**? Check out our [contribution guide](./CONT
 
 **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 = 'docs/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/quickstart.md

@@ -11,7 +11,7 @@ Welcome to **ratatui_ruby**! This guide will help you get up and running with yo
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'ratatui_ruby'
+gem "ratatui_ruby"
 ```
 
 And then execute:
@@ -32,10 +32,10 @@ Here is a "Hello World" application that demonstrates the core lifecycle of a **
 
 ```ruby
 require "ratatui_ruby"
-
+ 
 # 1. Initialize the terminal
 RatatuiRuby.init_terminal
-
+ 
 begin
   # The Main Loop
   loop do
@@ -43,17 +43,17 @@ begin
     # We define a Paragraph widget inside a Block with a title and borders.
     view = RatatuiRuby::Paragraph.new(
       text: "Hello, Ratatui! Press 'q' to quit.",
+      align: :center,
       block: RatatuiRuby::Block.new(
-        title: "My First App",
+        title: "My Ruby TUI App",
         borders: [:all],
-        border_style: "cyan"
-      ),
-      alignment: :center
+        border_color: "cyan"
+      )
     )
-
+ 
     # 3. Draw the UI
     RatatuiRuby.draw(view)
-
+ 
     # 4. Poll for events
     event = RatatuiRuby.poll_event
     if event && event[:type] == :key && event[:code] == "q"
@@ -66,6 +66,8 @@ ensure
 end
 ```
 
+![Basic Application Screenshot](./images/examples-quickstart_lifecycle.rb.png)
+
 ### How it works
 
 1.  **`RatatuiRuby.init_terminal`**: Enters raw mode and switches to the alternate screen.
@@ -73,7 +75,42 @@ end
 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.
+
+### DSL
+
+A small DSL is provided for convenience when writing scripts.
+
+```rb
+require "ratatui_ruby"
+
+# 1. Initialize the terminal, start the main loop, and ensure the terminal is restored.
+RatatuiRuby.main_loop do |tui|
+  # 2. Create your UI with methods instead of classes.
+  view = tui.paragraph(
+    text: "Hello, Ratatui! Press 'q' to quit.",
+    align: :center,
+    block: tui.block(
+      title: "My Ruby TUI App",
+      borders: [:all],
+      border_color: "cyan"
+    )
+  )
+
+  # 3. Use RatatuiRuby methods, too.
+  tui.draw(view)
+  event = tui.poll_event
+  
+  if event && event[:type] == :key && event[:code] == "q"
+    break
+  end
+end
+```
+
+#### How it works
+
+1.  **`RatatuiRuby.main_loop`**: This helper method manages the entire terminal lifecycle for you. It initializes the terminal before the block starts and ensures `restore_terminal` is called when the block exits (even if an error occurs).
+2.  **Widget Shorthand**: The block yields a special DSL object (here named `tui`). This object provides factory methods for every widget, allowing you to write `tui.paragraph(...)` instead of the more verbose `RatatuiRuby::Paragraph.new(...)`.
+3.  **Method SHorthand**: The DSL object also provides aliases for module functions of `RatatuiRuby`, allowing you to write `tui.draw(...)` instead of the more verbose `RatatuiRuby::draw(...)`.
 
 ## Examples
 
@@ -89,11 +126,20 @@ A simple demonstration of `Block` and `Paragraph` widgets, reacting to arrow key
 
 ![Box Demo Screenshot](./images/examples-box_demo.rb.png)
 
+### [Calendar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/calendar_demo.rb)
+A simple demo application for the `Calendar` widget.
+
+### [Chart Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/chart_demo.rb)
+Demonstrates the `Chart` widget with both scatter and line datasets, including custom axes.
+
 ### [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)
 
+### [List Styles](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/list_styles.rb)
+Showcases advanced styling options for the `List` widget, including selection highlighting.
+
 ### [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.
 
@@ -115,7 +161,7 @@ A simple example of integrating the `Scrollbar` widget and handling mouse wheel
 ![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.
+Utilizes `Sparkline` and `Chart` widgets to visualize real-time (simulated) data.
 
 ![Stock Ticker Screenshot](./images/examples-stock_ticker.rb.png)
 

data/examples/analytics.rb

@@ -3,7 +3,8 @@
 # SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-require_relative "../lib/ratatui_ruby"
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
 
 # Analytics Dashboard Example
 # Demonstrates Tabs and BarChart widgets.

data/examples/calendar_demo.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "ratatui_ruby"
+
+# A demo application for the Calendar widget.
+module CalendarDemo
+  def self.run
+    RatatuiRuby.init_terminal
+
+    loop do
+      now = Time.now
+      calendar = RatatuiRuby::Calendar.new(
+        year: now.year,
+        month: now.month,
+        header_style: RatatuiRuby::Style.new(fg: "yellow", modifiers: [:bold]),
+        block: RatatuiRuby::Block.new(title: " Calendar (q = quit) ", borders: [:all])
+      )
+
+      # Constrain the calendar to 24x10 characters
+      view = RatatuiRuby::Layout.new(
+        direction: :vertical,
+        constraints: [
+          RatatuiRuby::Constraint.length(10),
+          RatatuiRuby::Constraint.min(0),
+        ],
+        children: [
+          RatatuiRuby::Layout.new(
+            direction: :horizontal,
+            constraints: [
+              RatatuiRuby::Constraint.length(24),
+              RatatuiRuby::Constraint.min(0),
+            ],
+            children: [calendar, nil],
+          ),
+          nil,
+        ],
+      )
+
+      RatatuiRuby.draw(view)
+
+      event = RatatuiRuby.poll_event
+      break if event && event[:type] == :key && event[:code] == "q"
+
+      sleep 0.1
+    end
+  ensure
+    RatatuiRuby.restore_terminal
+  end
+end
+
+CalendarDemo.run if __FILE__ == $PROGRAM_NAME