ratatui_ruby 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5a3b028ff3dc634d6b77c5c0b13d63dcc1dc501f0cca3fd541499dbab8ca3a9
-  data.tar.gz: a8e6f86565a4dec484935444fa3f2a2e5e1691aaa8db5c5bd244c92f07e082fc
+  metadata.gz: 0e4a0958532fe7b493fcf0d9ee971bbc94194f5ff03fd420f895197597dac1c8
+  data.tar.gz: 480c3a5a467d478626a12c739064f894952e23d7a4574d0ad73a21dcc7b80ff5
 SHA512:
-  metadata.gz: efcd43721bd3db1f115529deaabc40d7ec0549490b4bc899b0b0e9120399be5201892fd213dd799aa19c99d120674ecd2cea54afb53c58bfbb14a3bef3ceb6b2
-  data.tar.gz: 7b3abbb0dcefbab609c5fdeff706b28421215f15d48c272c065b47469d1095073686fdbd85045594c82bc7f528fe9bd2511b09984314ec44f5d2358adfec8827
+  metadata.gz: 28f9f71581859a3ddaecb62df012e942fa3617dfcac1634af88e84b676b13802d3bb0bf7443ebba96f2bc1a00f503e86b8a2e2d3d6f613864d35b7002d432dac
+  data.tar.gz: f08716e00372054fcbee63e44ecb39e692ec2cc0b23d6e5596243b6df5c248274bf5b750b376d004644d8cf7a91993bde3e7c5dc980856befe84e0ce680de7b5

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang-dev
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.2.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.3.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:
@@ -31,7 +31,7 @@ tasks:
       sed -i 's/ruby = .*/ruby = "3.2"/' mise.toml
       mise install
       mise x -- pip install reuse
-      mise x -- gem install bundler
+      mise x -- gem install bundler:2.6.9
       mise reshim
       mise x -- bundle config set --local frozen 'true'
       mise x -- bundle install

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang-dev
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.2.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.3.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:
@@ -31,7 +31,7 @@ tasks:
       sed -i 's/ruby = .*/ruby = "3.3"/' mise.toml
       mise install
       mise x -- pip install reuse
-      mise x -- gem install bundler
+      mise x -- gem install bundler:2.6.9
       mise reshim
       mise x -- bundle config set --local frozen 'true'
       mise x -- bundle install

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang-dev
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.2.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.3.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:
@@ -31,7 +31,7 @@ tasks:
       sed -i 's/ruby = .*/ruby = "3.4"/' mise.toml
       mise install
       mise x -- pip install reuse
-      mise x -- gem install bundler
+      mise x -- gem install bundler:2.6.9
       mise reshim
       mise x -- bundle config set --local frozen 'true'
       mise x -- bundle install

data/.builds/{ruby-4.0.0-preview3.yml → ruby-4.0.0.yml}

@@ -16,7 +16,7 @@ packages:
   - clang-dev
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.2.0.gem
+  - ratatui_ruby/pkg/ratatui_ruby-0.3.0.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:
@@ -28,10 +28,10 @@ tasks:
       export RUSTFLAGS="-C target-feature=-crt-static"
       export CI="true"
       cd ratatui_ruby
-      sed -i 's/ruby = .*/ruby = "4.0.0-preview3"/' mise.toml
+      sed -i 's/ruby = .*/ruby = "4.0.0"/' mise.toml
       mise install
       mise x -- pip install reuse
-      mise x -- gem install bundler
+      mise x -- gem install bundler:2.6.9
       mise reshim
       mise x -- bundle config set --local frozen 'true'
       mise x -- bundle install
@@ -40,12 +40,12 @@ tasks:
   - test: |
       . ~/.buildenv
       cd ratatui_ruby
-      echo "Testing Ruby 4.0.0-preview3"
+      echo "Testing Ruby 4.0.0"
       mise x -- bundle exec rake test || true
   - lint: |
       . ~/.buildenv
       cd ratatui_ruby
-      echo "Linting Ruby 4.0.0-preview3"
+      echo "Linting Ruby 4.0.0"
       mise x -- bundle exec rake lint || true
   - package: |
       . ~/.buildenv

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

@@ -36,7 +36,7 @@ Every file must begin with an SPDX-compliant header. Use the following format:
 ### Ruby Standards
 
 -   **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.
+-   **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`.
@@ -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

@@ -23,7 +23,7 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 > [!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
@@ -34,8 +34,8 @@ Please join our **announce** mailing list at https://lists.sr.ht/~kerrick/ratatu
 - 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.
+[non-eol Ruby version](https://www.ruby-lang.org/en/downloads/branches/).
+Support for Ruby 4 is coming soon.
 
 
 ## Installation
@@ -80,21 +80,21 @@ RatatuiRuby.main_loop do |tui|
 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

data/REUSE.toml

@@ -17,6 +17,6 @@ SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "CC0-1.0"
 
 [[annotations]]
-path = 'docs/images/*.png'
+path = 'doc/images/*.png'
 SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "CC-BY-SA-4.0"

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;
+}

data/{docs → doc}/index.md

@@ -14,5 +14,5 @@
 
 ## Documentation for Contributors
 
-- [Contributing Guidelines](../CONTRIBUTING.md)
+- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md)
 - [More Documentation for Contributors](./contributors/index.md)

data/{docs → doc}/quickstart.md

@@ -129,9 +129,18 @@ A simple demonstration of `Block` and `Paragraph` widgets, reacting to arrow key
 ### [Calendar Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/calendar_demo.rb)
 A simple demo application for the `Calendar` widget.
 
+![Calendar Screenshot](./images/examples-calendar_demo.rb.png)
+
 ### [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.
 
+![Chart Screenshot](./images/examples-chart_demo.rb.png)
+
+### [Custom Widget (Escape Hatch)](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/custom_widget.rb)
+Demonstrates how to define a custom widget in pure Ruby using the `render(area, buffer)` escape hatch for low-level drawing.
+
+![Custom Widget Screenshot](./images/examples-custom_widget.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.
 
@@ -155,11 +164,21 @@ Detailed plumbing of mouse events, including clicks, drags, and movement trackin
 
 ![Mouse Events Screenshot](./images/examples-mouse_events.rb.png)
 
+### [Popup Demo](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/popup_demo.rb)
+Demonstrates the `Clear` widget and how to prevent "style bleed" when rendering opaque popups over colored backgrounds.
+
+![Popup Demo Screenshot](./images/examples-popup_demo.rb.gif)
+
 ### [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)
 
+### [Scroll Text](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/scroll_text.rb)
+Demonstrates the `Paragraph` widget's scroll functionality, allowing navigation through long text content using arrow keys for both horizontal and vertical scrolling.
+
+![Scroll Text Screenshot](./images/examples-scroll_text.rb.png)
+
 ### [Stock Ticker](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/stock_ticker.rb)
 Utilizes `Sparkline` and `Chart` widgets to visualize real-time (simulated) data.
 
@@ -170,3 +189,8 @@ Combines `Table` and `Gauge` widgets in a vertical layout to create a functional
 
 ![System Monitor Screenshot](./images/examples-system_monitor.rb.png)
 
+### [Table Select](https://git.sr.ht/~kerrick/ratatui_ruby/tree/main/item/examples/table_select.rb)
+Demonstrates interactive row selection in the `Table` widget with keyboard navigation, highlighting selected rows with custom styles and symbols.
+
+![Table Select Screenshot](./images/examples-table_select.rb.png)
+

data/examples/custom_widget.rb

@@ -0,0 +1,43 @@
+# 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 custom widget that draws a diagonal line.
+class DiagonalWidget
+  def render(area, buffer)
+    # Draw a diagonal line within the area
+    (0..10).each do |i|
+      next if area.x + i >= area.x + area.width || area.y + i >= area.y + area.height
+
+      buffer.set_string(
+        area.x + i,
+        area.y + i,
+        "\\",
+        RatatuiRuby::Style.new(fg: :red, modifiers: [:bold])
+      )
+    end
+  end
+end
+
+RatatuiRuby.main_loop do |tui|
+  tui.draw(
+    RatatuiRuby::Layout.new(
+      direction: :vertical,
+      constraints: [
+        RatatuiRuby::Constraint.percentage(50),
+        RatatuiRuby::Constraint.percentage(50),
+      ],
+      children: [
+        RatatuiRuby::Paragraph.new(text: "Above custom widget"),
+        DiagonalWidget.new,
+      ]
+    )
+  )
+
+  event = RatatuiRuby.poll_event
+  break if event && event[:type] == :key && event[:code] == "q"
+end

data/examples/popup_demo.rb

@@ -0,0 +1,105 @@
+# 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"
+
+# Popup Demo Example
+# Demonstrates the Clear widget for creating opaque popups.
+
+class PopupDemo
+  def initialize
+    @clear_enabled = false
+  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
+    # 1. Background: Loud Red Background
+    # This demonstrates "Style Bleed" where the background color persists
+    # unless explicitly cleared or overwritten.
+    background = RatatuiRuby::Paragraph.new(
+      text: "BACKGROUND RED " * 100,
+      style: RatatuiRuby::Style.new(bg: :red, fg: :white),
+      wrap: true
+    )
+
+    # 2. Popup Content: No specific background set (Style.default)
+    # Without Clear, this will "inherit" the red background from underneath.
+    popup_text = if @clear_enabled
+                   "✓ Clear is ENABLED\n\nResets background to default\n(Usually Black/Transparent)\n\nPress Space to toggle"
+                 else
+                   "✗ Clear is DISABLED\n\nStyle Bleed: Popup is RED!\n(Inherits background style)\n\nPress Space to toggle"
+                 end
+
+    popup_content = RatatuiRuby::Paragraph.new(
+      text: popup_text,
+      align: :center,
+      block: RatatuiRuby::Block.new(
+        title: "Popup Demo (Press 'q' to quit)",
+        borders: [:all]
+      )
+    )
+
+    # Build the UI with or without Clear
+    if @clear_enabled
+      # With Clear: Resets the style in the popup area before rendering content
+      ui = RatatuiRuby::Overlay.new(
+        layers: [
+          background,
+          RatatuiRuby::Center.new(
+            child: RatatuiRuby::Overlay.new(
+              layers: [
+                RatatuiRuby::Clear.new,
+                popup_content
+              ]
+            ),
+            width_percent: 60,
+            height_percent: 50
+          )
+        ]
+      )
+    else
+      # Without Clear: Background style (RED) bleeds through the popup
+      ui = RatatuiRuby::Overlay.new(
+        layers: [
+          background,
+          RatatuiRuby::Center.new(
+            child: popup_content,
+            width_percent: 60,
+            height_percent: 50
+          )
+        ]
+      )
+    end
+
+    RatatuiRuby.draw(ui)
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    if event
+      case event[:code]
+      when "q"
+        :quit
+      when " "
+        @clear_enabled = !@clear_enabled
+      end
+    end
+  end
+end
+
+PopupDemo.new.run if __FILE__ == $0

data/examples/scroll_text.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# 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"
+
+# Demo: Scrollable Paragraph
+# Shows how to scroll through long text content using arrow keys
+class ScrollTextDemo
+  def initialize
+    @scroll_x = 0
+    @scroll_y = 0
+    @lines = (1..100).map { |i| "Line #{i}: This is a long line of text that can be scrolled horizontally" }
+  end
+
+  def run
+    RatatuiRuby.init_terminal
+    begin
+      loop do
+        draw
+        break if handle_input == :quit
+      end
+    ensure
+      RatatuiRuby.restore_terminal
+    end
+  end
+
+  def render
+    draw
+  end
+
+  def handle_input
+    event = RatatuiRuby.poll_event
+    return nil unless event
+
+    if event[:type] == :key
+      case event[:code]
+      when "up"
+        @scroll_y = [@scroll_y - 1, 0].max
+      when "down"
+        @scroll_y = [@scroll_y + 1, @lines.length].min
+      when "left"
+        @scroll_x = [@scroll_x - 1, 0].max
+      when "right"
+        @scroll_x = [@scroll_x + 1, 100].min
+      when "q"
+        return :quit
+      end
+    end
+    nil
+  end
+
+  private
+
+  def draw
+    text = @lines.join("\n")
+    
+    paragraph = RatatuiRuby::Paragraph.new(
+      text: text,
+      scroll: [@scroll_y, @scroll_x],
+      block: RatatuiRuby::Block.new(
+        title: "Scrollable Text (X: #{@scroll_x}, Y: #{@scroll_y}) - Arrow keys to scroll, 'q' to quit",
+        borders: [:all]
+      )
+    )
+
+    RatatuiRuby.draw(paragraph)
+  end
+end
+
+ScrollTextDemo.new.run if __FILE__ == $PROGRAM_NAME