ratatui_ruby 0.10.3 → 1.0.0.pre.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45627e7b77b76ba56a7cb5bb3b0cb578d282a26782c6702abdc87893d89e14a9
-  data.tar.gz: b401cd48eb576970a74c8efc7bf22dba20a9bbd4d4378ff85b4a3f45797a3e31
+  metadata.gz: c251e31a8aea8d5e84bc0969f8f6c95f690a2ce94d0cbd3538856bfbdafd055a
+  data.tar.gz: ee38d86ebdc50612ba5a32990e7f1c3757e9f35ced6d621fc92203836c938793
 SHA512:
-  metadata.gz: 8ef1ed4f7c6c35df19e7955fd9fc752e5b73da316380fe21c9927b3f5c5fbc3d959948821b0c795572edf58cd43627be65922452f93dfa51dd54f93e1a2b164b
-  data.tar.gz: 13c4cb8c1de48f10920128527222f4ae94db9ac98f0ec1b3b975b3edd0a221859f352a2ddc570b0d955f566a393341413ea2e0ed9ea4e1e12f596973bf657723
+  metadata.gz: 4f555dd2eddeef420df2512c53e26a136a791cfabd72bfe74ac1c5bd3f652d317bc9c60d47a78611f3a20e76ae72925494d867fcd992a17f0dcd29b3bb18b33d
+  data.tar.gz: 47d21c6a4e5969a5457705eb088efaa45dd29ee5d6fac1f67166f3a4c2114aa65d54b926b05191fcf8f2a20b8a1c6481d19ffed195f0e2ee045bfaf561589dc5

data/.builds/ruby-3.2.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.10.3.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.pre.beta.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.3.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.10.3.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.pre.beta.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-3.4.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.10.3.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.pre.beta.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/.builds/ruby-4.0.0.yml

@@ -16,7 +16,7 @@ packages:
   - clang
   - git
 artifacts:
-  - ratatui_ruby/pkg/ratatui_ruby-0.10.3.gem
+  - ratatui_ruby/pkg/ratatui_ruby-1.0.0.pre.beta.1.gem
 sources:
   - https://git.sr.ht/~kerrick/ratatui_ruby
 tasks:

data/CHANGELOG.md

@@ -18,6 +18,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Removed
 
+## [1.0.0-beta.1] - 2026-01-20
+This release is functionally equivalent to v0.10.3. The version bump signals the beginning of the 1.0 release series.
+
 ## [0.10.3] - 2026-01-16
 
 ### Added
@@ -667,6 +670,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - **Testing Support**: Included `RatatuiRuby::TestHelper` and RSpec integration to make testing your TUI applications possible.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/HEAD
+[1.0.0-beta.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v1.0.0-beta.1
 [0.10.3]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.10.3
 [0.10.2]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.10.2
 [0.10.1]: https://git.sr.ht/~kerrick/ratatui_ruby/refs/v0.10.1

data/README.rdoc

@@ -0,0 +1,302 @@
+
+== Terminal UIs, the Ruby Way
+
+RatatuiRuby[https://rubygems.org/gems/ratatui_ruby] is a RubyGem built on
+Ratatui[https://ratatui.rs], a leading TUI library written in
+Rust[https://rust-lang.org]. You get native performance with the joy of Ruby.
+
+  gem install ratatui_ruby
+
+{rdoc-image:https://ratatui-ruby.dev/hero.gif}[https://www.ratatui-ruby.dev/docs/v0.10/examples/app_cli_rich_moments/README_md.html]
+
+=== Rich Moments
+
+Add a spinner, a progress bar, or an inline menu to your CLI script. No
+full-screen takeover. Your terminal history stays intact.
+
+==== Inline Viewports
+
+Standard TUIs erase themselves on exit. Your carefully formatted CLI output
+disappears. Users lose their scrollback.
+
+<b>Inline viewports</b> solve this. They occupy a fixed number of lines, render
+rich UI, then leave the output in place when done.
+
+Perfect for spinners, menus, progress indicators—any brief moment of richness.
+
+  require "ratatui_ruby"
+
+  RatatuiRuby.run(viewport: :inline, height: 1) do |tui|
+    until connected?
+      status = tui.paragraph(text: "\#{spin} Connecting...")
+      tui.draw { |frame| frame.render_widget(status, frame.area) }
+    end
+  end
+
+=== Build Something Real
+
+Full-screen applications with {keyboard and mouse input}[https://www.ratatui-ruby.dev/docs/v0.10/examples/app_all_events/README_md.html]. The managed loop
+sets up the terminal and restores it on exit, even after crashes.
+
+  RatatuiRuby.run do |tui|
+    loop do
+      tui.draw do |frame|
+        frame.render_widget(
+          tui.paragraph(text: "Hello, RatatuiRuby!", alignment: :center),
+          frame.area
+        )
+      end
+
+      case tui.poll_event
+      in { type: :key, code: "q" } then break
+      else nil
+      end
+    end
+  end
+
+==== Widgets included:
+
+[Layout]
+  {Block}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_block/README_md.html],
+  {Center}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_center/README_md.html],
+  {Clear (Popup, Modal)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_popup/README_md.html],
+  {Layout (Split, Grid)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_layout_split/README_md.html],
+  {Overlay}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_overlay/README_md.html]
+[Data]
+  {Bar Chart}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_barchart/README_md.html],
+  {Chart}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_chart/README_md.html],
+  {Gauge}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_gauge/README_md.html],
+  {Line Gauge}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_line_gauge/README_md.html],
+  {Sparkline}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_sparkline/README_md.html],
+  {Table}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_table/README_md.html]
+[Text]
+  {Cell}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_cell/README_md.html],
+  {List}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_list/README_md.html],
+  {Rich Text (Line, Span)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_rich_text/README_md.html],
+  {Scrollbar (Scroll)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_scrollbar/README_md.html],
+  {Tabs}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_tabs/README_md.html]
+[Graphics]
+  {Calendar}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_calendar/README_md.html],
+  {Canvas}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_canvas/README_md.html],
+  {Map (World Map)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_map/README_md.html]
+
+Need something else? {Build custom widgets}[https://www.ratatui-ruby.dev/docs/v0.10/doc/concepts/custom_widgets_md.html] in Ruby!
+
+
+---
+
+=== Testing Built In
+
+TUI testing is tedious. You need a headless terminal, event injection,
+snapshot comparisons, and style assertions. RatatuiRuby bundles all of it.
+
+  require "ratatui_ruby/test_helper"
+
+  class TestColorPicker < Minitest::Test
+    include RatatuiRuby::TestHelper
+
+    def test_swatch_widget
+      with_test_terminal(10, 3) do
+        RatatuiRuby.draw do |frame|
+          frame.render_widget(Swatch.new(:red), frame.area)
+        end
+        assert_cell_style 2, 1, char: "█", bg: :red
+      end
+    end
+  end
+
+==== What's inside:
+
+- <b>Headless terminal</b> — No real TTY needed
+- <b>Snapshots</b> — Plain text and rich (ANSI colors)
+- <b>Event injection</b> — Keys, mouse, paste, resize
+- <b>Style assertions</b> — Color, bold, underline at any cell
+- <b>Test doubles</b> — Mock frames and stub rects
+- <b>UPDATE_SNAPSHOTS=1</b> — Regenerate baselines in one command
+
+
+---
+
+==== Inline Menu Example
+
+  require "ratatui_ruby"
+
+  # This example renders an inline menu. Arrow keys select, enter confirms.
+  # The menu appears in-place, preserving scrollback. When the user chooses,
+  # the TUI closes and the script continues with the selected value.
+  class RadioMenu
+    CHOICES = ["Production", "Staging", "Development"]         # ASCII strings are universally supported.
+    PREFIXES = { active: "●", inactive: "○" }                  # Some terminals may not support Unicode.
+    CONTROLS = "↑/↓: Select | Enter: Choose | Ctrl+C: Cancel"  # Let users know what keys you handle.
+    TITLES = ["Select Environment",                            # The default title position is top left.
+              { content: CONTROLS,                             # Multiple titles can save space.
+                position: :bottom,                             # Titles go on the top or bottom,
+                alignment: :right }]                           # aligned left, right, or center
+
+    def call                                                   # This method blocks until a choice is made.
+      RatatuiRuby.run(viewport: :inline, height: 5) do |tui|   # RatauiRuby.run manages the terminal.
+        @tui = tui                                             # The TUI instance is safe to store.
+        show_menu until chosen?                                # You can use any loop keyword you like.
+      end                                                      # `run` won't return until your block does,
+      RadioMenu::CHOICES[@choice]                              # so you can use it synchronously.
+    end
+                                                               # Classes like RadioMenu are convenient for
+    private                                                    # CLI authors to offer "rich moments."
+
+    def show_menu = @tui.draw do |frame|                       # RatatuiRuby gives you low-level access.
+      widget = @tui.paragraph(                                 # But the TUI facade makes it easy to use.
+        text: menu_items,                                      # Text can be spans, lines, or paragraphs.
+        block: @tui.block(borders: :all, titles: TITLES)       # Blocks give you boxes and titles, and hold
+      )                                                        # one or more widgets. We only use one here,
+      frame.render_widget(widget, frame.area)                  # but "area" lets you compose sub-views.
+    end
+
+    def chosen?                                                # You are responsible for handling input.
+      interaction = @tui.poll_event                            # Every frame, you receive an event object:
+      return choose if interaction.enter?                      # Key, Mouse, Resize, Paste, FocusGained,
+                                                               # FocusLost, or None objects. They come with
+      move_by(-1) if interaction.up?                           # predicates, support pattern matching, and
+      move_by(1) if interaction.down?                          # can be inspected for properties directly.
+      quit! if interaction.ctrl_c?                             # Your application must handle every input,
+      false                                                    # even interrupts and other exit patterns.
+    end
+
+    def choose                                                 # Here, the loop is about to exit, and the
+      prepare_next_line                                        # block will return. The inline viewport
+      @choice                                                  # will be torn down and the terminal will
+    end                                                        # be restored, but you are responsible for
+                                                               # positioning the cursor.
+    def prepare_next_line                                      # To ensure the next output is on a new
+      area = @tui.viewport_area                                # line, query the viewport area and move
+      RatatuiRuby.cursor_position = [0, area.y + area.height]  # the cursor to the start of the last line.
+      puts                                                     # Then print a newline.
+    end
+
+    def quit!                                                  # All of your familiar Ruby control flow
+      prepare_next_line                                        # keywords work as expected, so we can
+      exit 0                                                   # use them to leave the TUI.
+    end
+
+    def move_by(line_count)                                    # You are in full control of your UX, so
+      @choice = (@choice + line_count) % CHOICES.size          # you can implement any logic you need:
+    end                                                        # Would you "wrap around" here, or not?
+                                                               #
+    def menu_items = CHOICES.map.with_index do |choice, i|     # Notably, RatatuiRuby has no concept of
+      "\#{prefix_for(i)} \#{choice}"                             # "menus" or "radio buttons". You are in
+    end                                                        # full control, but it also means you must
+    def prefix_for(choice_index)                               # implement the logic yourself. For larger
+      return PREFIXES[:active] if choice_index == @choice      # applications, consider using Rooibos,
+      PREFIXES[:inactive]                                      # an MVU framework built with RatatuiRuby.
+    end                                                        # Or, use the upcoming ratatui-ruby-kit,
+                                                               # our object-oriented component library.
+    def initialize = @choice = 0                               # However, those are both optional, and
+  end                                                          # designed for full-screen Terminal UIs.
+                                                               # RatatuiRuby will always give you the most
+  choice = RadioMenu.new.call                                  # control, and is enough for "rich CLI
+  puts "You chose \#{choice}!"                                  # moments" like this one.
+
+---
+
+=== Full App Solutions
+
+RatatuiRuby renders. For complex applications, add a framework that manages
+state and composition.
+
+==== Rooibos[https://git.sr.ht/~kerrick/rooibos] (Framework)
+
+Model-View-Update architecture. Inspired by Elm, Bubble Tea, and React +
+Redux. Your UI is a pure function of state.
+
+- Functional programming with MVU
+- Commands work off the main thread
+- Messages, not callbacks, drive updates
+
+==== {Kit}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit] (Coming Soon)
+
+Component-based architecture. Encapsulate state, input handling, and
+rendering in reusable pieces.
+
+- OOP with stateful components
+- Separate UI state from domain logic
+- Built-in focus management & click handling
+
+Both use the same widget library and rendering engine. Pick the paradigm
+that fits your brain.
+
+
+---
+
+=== Why RatatuiRuby?
+
+Ruby deserves world-class terminal user interfaces. TUI developers deserve
+a world-class language.
+
+RatatuiRuby wraps Rust's Ratatui via native extension. The Rust library
+handles rendering. Your Ruby code handles design.
+
+>>>
+  "Text UIs are seeing a renaissance with many new TUI libraries popping up.
+  The Ratatui bindings have proven to be full featured and stable."
+
+  — {Mike Perham}[https://www.mikeperham.com/], creator of
+  Sidekiq[https://sidekiq.org/] and Faktory[https://contribsys.com/faktory/]
+
+==== Why Rust? Why Ruby?
+
+Rust excels at low-level rendering. Ruby excels at expressing domain logic
+and UI. RatatuiRuby puts each language where it performs best.
+
+==== Versus CharmRuby
+
+CharmRuby[https://charm-ruby.dev/] wraps Charm's Go libraries. Both projects
+give Ruby developers TUI options.
+
+[Integration]
+  CharmRuby: Two runtimes, one process.
+  RatatuiRuby: Native extension in Rust.
+[Runtime]
+  CharmRuby: Go + Ruby (competing).
+  RatatuiRuby: Ruby (Rust has no runtime).
+[Memory]
+  CharmRuby: Two uncoordinated GCs.
+  RatatuiRuby: One Garbage Collector.
+[Style]
+  CharmRuby: The Elm Architecture (TEA).
+  RatatuiRuby: TEA, OOP, or Imperative.
+
+
+---
+
+=== Links
+
+[Get Started]
+  {Quickstart}[https://www.ratatui-ruby.dev/docs/v0.10/doc/getting_started/quickstart_md.html],
+  {Examples}[https://www.ratatui-ruby.dev/docs/v0.10/examples/app_cli_rich_moments/README_md.html],
+  {API Reference}[https://www.ratatui-ruby.dev/docs/v0.10/],
+  {Guides}[https://www.ratatui-ruby.dev/docs/v0.10/doc/index_md.html]
+[Ecosystem]
+  Rooibos[https://git.sr.ht/~kerrick/rooibos],
+  {Kit}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit] (Planned),
+  {Framework}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-5-the-framework] (Planned),
+  {UI Widgets}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-6-licensing] (Planned)
+[Community]
+  {Discuss and Chat}[https://lists.sr.ht/~kerrick/ratatui_ruby-discuss],
+  {Announcements}[https://lists.sr.ht/~kerrick/ratatui_ruby-announce],
+  {Development}[https://lists.sr.ht/~kerrick/ratatui_ruby-devel],
+  {Bug Tracker}[https://todo.sr.ht/~kerrick/ratatui_ruby]
+[Contribute]
+  {Contributing Guide}[https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md],
+  {Code of Conduct}[https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md],
+  {Project History}[https://man.sr.ht/~kerrick/ratatui_ruby/history/index.md],
+  {Pull Requests}[https://lists.sr.ht/~kerrick/ratatui_ruby-devel/patches]
+
+
+---
+
+[Website] https://www.ratatui-ruby.dev
+[Source] https://git.sr.ht/~kerrick/ratatui_ruby
+[RubyGems] https://rubygems.org/gems/ratatui_ruby
+[Upstream] https://ratatui.rs
+[Build Status] https://builds.sr.ht/~kerrick/ratatui_ruby
+
+© 2026 Kerrick Long · Library: LGPL-3.0-or-later · Website: CC-BY-NC-ND-4.0 · Snippets: MIT-0

data/REUSE.toml

@@ -5,6 +5,11 @@ path = 'Gemfile.lock'
 SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "CC0-1.0"
 
+[[annotations]]
+path = 'README.rdoc'
+SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "CC-BY-SA-4.0"
+
 
 [[annotations]]
 path = 'ext/ratatui_ruby/Cargo.lock'

data/examples/verify_website_menu/app.rb

@@ -6,52 +6,84 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 
-# Test 2: Inline menu example (fixed)
 require "ratatui_ruby"
 
-choices = ["Production", "Staging", "Development"]
-index = 0
-
-RatatuiRuby.run(viewport: :inline, height: 5) do |tui|
-  loop do
-    tui.draw do |frame|
-      items = choices.map.with_index do |c, i|
-        prefix = (i == index) ? "● " : "○ "
-        "#{prefix}#{c}"
-      end
-      widget = tui.paragraph(
-        text: items.join("\n"),
-        block: tui.block(
-          borders: :all,
-          title: "Select Environment",
-          titles: [{ content: "↑/↓ Enter | Ctrl+C: Cancel", position: :bottom, alignment: :right }]
-        )
-      )
-      frame.render_widget(widget, frame.area)
-    end
-
-    case tui.poll_event
-    in { type: :key, code: "up" }
-      index = (index - 1) % choices.size
-    in { type: :key, code: "down" }
-      index = (index + 1) % choices.size
-    in { type: :key, code: "enter" }
-      area = tui.viewport_area
-      RatatuiRuby.cursor_position = [0, area.y + area.height]
-      break
-    in { type: :key, code: "c", modifiers: ["ctrl"] }
-      area = tui.viewport_area
-      RatatuiRuby.cursor_position = [0, area.y + area.height]
-      index = nil
-      break
-    else nil
-    end
+# This example renders an inline menu. Arrow keys select, enter confirms.
+# The menu appears in-place, preserving scrollback. When the user chooses,
+# the TUI closes and the script continues with the selected value.
+class RadioMenu
+  CHOICES = ["Production", "Staging", "Development"]         # ASCII strings are universally supported.
+  PREFIXES = { active: "●", inactive: "○" }                  # Some terminals may not support Unicode.
+  CONTROLS = "↑/↓: Select | Enter: Choose | Ctrl+C: Cancel"  # Let users know what keys you handle.
+  TITLES = [
+    "Select Environment", # The default title position is top left.
+    {
+content: CONTROLS, # Multiple titles can save space.
+position: :bottom, # Titles go on the top or bottom,
+alignment: :right,
+},
+] # aligned left, right, or center
+
+  def call                                                   # This method blocks until a choice is made.
+    RatatuiRuby.run(viewport: :inline, height: 5) do |tui|   # RatauiRuby.run manages the terminal.
+      @tui = tui                                             # The TUI instance is safe to store.
+      show_menu until chosen?                                # You can use any loop keyword you like.
+    end                                                      # `run` won't return until your block does,
+    RadioMenu::CHOICES[@choice]                              # so you can use it synchronously.
+  end
+                                                             # Classes like RadioMenu are convenient for
+
+  private def show_menu = @tui.draw do |frame| # RatatuiRuby gives you low-level access.
+    widget = @tui.paragraph(                                 # But the TUI facade makes it easy to use.
+      text: menu_items,                                      # Text can be spans, lines, or paragraphs.
+      block: @tui.block(borders: :all, titles: TITLES)       # Blocks give you boxes and titles, and hold
+    )                                                        # one or more widgets. We only use one here,
+    frame.render_widget(widget, frame.area)                  # but "area" lets you compose sub-views.
+  end
+
+  private def chosen? # You are responsible for handling input.
+    interaction = @tui.poll_event                            # Every frame, you receive an event object:
+    return choose if interaction.enter?                      # Key, Mouse, Resize, Paste, FocusGained,
+                                                             # FocusLost, or None objects. They come with
+    move_by(-1) if interaction.up?                           # predicates, support pattern matching, and
+    move_by(1) if interaction.down?                          # can be inspected for properties directly.
+    quit! if interaction.ctrl_c?                             # Your application must handle every input,
+    false                                                    # even interrupts and other exit patterns.
+  end
+
+  private def choose # Here, the loop is about to exit, and the
+    prepare_next_line                                        # block will return. The inline viewport
+    @choice                                                  # will be torn down and the terminal will
+  end                                                        # be restored, but you are responsible for
+
+                                                             # positioning the cursor.
+  private def prepare_next_line # To ensure the next output is on a new
+    area = @tui.viewport_area                                # line, query the viewport area and move
+    RatatuiRuby.cursor_position = [0, area.y + area.height]  # the cursor to the start of the last line.
+    puts                                                     # Then print a newline.
+  end
+
+  private def quit! # All of your familiar Ruby control flow
+    prepare_next_line                                        # keywords work as expected, so we can
+    exit 0                                                   # use them to leave the TUI.
   end
-end
-
-puts
-if index
-  puts "Deploying to #{choices[index]}..."
-else
-  puts "Cancelled."
-end
+
+  private def move_by(line_count) # You are in full control of your UX, so
+    @choice = (@choice + line_count) % CHOICES.size          # you can implement any logic you need:
+  end                                                        # Would you "wrap around" here, or not?
+
+  private def menu_items = CHOICES.map.with_index do |choice, i| # Notably, RatatuiRuby has no concept of
+    "#{prefix_for(i)} #{choice}"                             # "menus" or "radio buttons". You are in
+  end                                                        # full control, but it also means you must
+
+  private def prefix_for(choice_index) # implement the logic yourself. For larger
+    return PREFIXES[:active] if choice_index == @choice      # applications, consider using Rooibos,
+    PREFIXES[:inactive]                                      # an MVU framework built with RatatuiRuby.
+  end                                                        # Or, use the upcoming ratatui-ruby-kit,
+
+                                                             # our object-oriented component library.
+  private def initialize = @choice = 0 # However, those are both optional, and
+end                                                          # designed for full-screen Terminal UIs.
+                                                             # RatatuiRuby will always give you the most
+choice = RadioMenu.new.call                                  # control, and is enough for "rich CLI
+puts "You chose #{choice}!"                                  # moments" like this one.

data/examples/verify_website_spinner/app.rb

@@ -21,13 +21,14 @@ class Spinner
     end
   end
 
-  def ending(tui, message, color) = tui.draw do |frame|
-    frame.render_widget(tui.paragraph(text: message, fg: color), frame.area)
+  def ending(tui, text, fg) = tui.draw do |frame|
+    frame.render_widget(tui.paragraph(text:, fg:), frame.area)
+    puts # Prepare a new line for the shell prompt
   end
 
-  def initialize = (@frame, @finish = 0, Time.now + 1)
+  def initialize = (@frame, @finish = 0, Time.now + 2)
   def connected? = Time.now >= @finish # Simulate work
   def spin = SPINNER[(@frame += 1) % SPINNER.length]
   SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏]
 end
-Spinner.new.main; puts
+Spinner.new.main

data/ext/ratatui_ruby/Cargo.lock

@@ -1059,7 +1059,7 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "0.10.3"
+version = "1.0.0-beta.1"
 dependencies = [
  "bumpalo",
  "lazy_static",

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "0.10.3"
+version = "1.0.0-beta.1"
 edition = "2021"
 
 [lib]

data/lib/ratatui_ruby/version.rb

@@ -8,5 +8,5 @@
 module RatatuiRuby
   # The version of the ratatui_ruby gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.10.3"
+  VERSION = "1.0.0-beta.1"
 end

data/tasks/bump/sem_ver.rb

@@ -11,12 +11,15 @@ class SemVer
 
   def self.parse(string)
     require "rubygems"
-    segments = Gem::Version.new(string).segments.fill(0, 3).first(3)
-    new(segments)
+    # Extract prerelease suffix (e.g., "-beta.1", "-alpha.2", "-rc.1")
+    base, prerelease = string.split("-", 2)
+    segments = Gem::Version.new(base).segments.fill(0, 3).first(3)
+    new(segments, prerelease:)
   end
 
-  def initialize(segments)
+  def initialize(segments, prerelease: nil)
     @segments = segments
+    @prerelease = prerelease
   end
 
   def next(segment)
@@ -31,6 +34,7 @@ class SemVer
   end
 
   def to_s
-    @segments.join(".")
+    base = @segments.join(".")
+    @prerelease ? "#{base}-#{@prerelease}" : base
   end
 end

data/tasks/sourcehut.rake

@@ -25,7 +25,11 @@ namespace :sourcehut do
       version_content = File.read("lib/ratatui_ruby/version.rb")
       version = version_content.match(/VERSION = "(.+?)"/)[1]
 
-      gem_filename = "#{spec.name}-#{version}.gem"
+      # Normalize version using Gem::Version - RubyGems converts hyphens
+      # (e.g., "1.0.0-beta.1" -> "1.0.0.pre.beta.1")
+      normalized_version = Gem::Version.new(version).to_s
+
+      gem_filename = "#{spec.name}-#{normalized_version}.gem"
 
       rubies = YAML.load_file("tasks/resources/rubies.yml")
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 1.0.0.pre.beta.1
 platform: ruby
 authors:
 - Kerrick Long
@@ -93,8 +93,309 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
-description: ratatui_ruby is a wrapper for the Ratatui Rust crate <https://ratatui.rs>.
-  It allows you to cook up Terminal User Interfaces in Ruby.
+description: |2-
+
+  == Terminal UIs, the Ruby Way
+
+  RatatuiRuby[https://rubygems.org/gems/ratatui_ruby] is a RubyGem built on
+  Ratatui[https://ratatui.rs], a leading TUI library written in
+  Rust[https://rust-lang.org]. You get native performance with the joy of Ruby.
+
+    gem install ratatui_ruby
+
+  {rdoc-image:https://ratatui-ruby.dev/hero.gif}[https://www.ratatui-ruby.dev/docs/v0.10/examples/app_cli_rich_moments/README_md.html]
+
+  === Rich Moments
+
+  Add a spinner, a progress bar, or an inline menu to your CLI script. No
+  full-screen takeover. Your terminal history stays intact.
+
+  ==== Inline Viewports
+
+  Standard TUIs erase themselves on exit. Your carefully formatted CLI output
+  disappears. Users lose their scrollback.
+
+  <b>Inline viewports</b> solve this. They occupy a fixed number of lines, render
+  rich UI, then leave the output in place when done.
+
+  Perfect for spinners, menus, progress indicators—any brief moment of richness.
+
+    require "ratatui_ruby"
+
+    RatatuiRuby.run(viewport: :inline, height: 1) do |tui|
+      until connected?
+        status = tui.paragraph(text: "\#{spin} Connecting...")
+        tui.draw { |frame| frame.render_widget(status, frame.area) }
+      end
+    end
+
+  === Build Something Real
+
+  Full-screen applications with {keyboard and mouse input}[https://www.ratatui-ruby.dev/docs/v0.10/examples/app_all_events/README_md.html]. The managed loop
+  sets up the terminal and restores it on exit, even after crashes.
+
+    RatatuiRuby.run do |tui|
+      loop do
+        tui.draw do |frame|
+          frame.render_widget(
+            tui.paragraph(text: "Hello, RatatuiRuby!", alignment: :center),
+            frame.area
+          )
+        end
+
+        case tui.poll_event
+        in { type: :key, code: "q" } then break
+        else nil
+        end
+      end
+    end
+
+  ==== Widgets included:
+
+  [Layout]
+    {Block}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_block/README_md.html],
+    {Center}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_center/README_md.html],
+    {Clear (Popup, Modal)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_popup/README_md.html],
+    {Layout (Split, Grid)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_layout_split/README_md.html],
+    {Overlay}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_overlay/README_md.html]
+  [Data]
+    {Bar Chart}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_barchart/README_md.html],
+    {Chart}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_chart/README_md.html],
+    {Gauge}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_gauge/README_md.html],
+    {Line Gauge}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_line_gauge/README_md.html],
+    {Sparkline}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_sparkline/README_md.html],
+    {Table}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_table/README_md.html]
+  [Text]
+    {Cell}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_cell/README_md.html],
+    {List}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_list/README_md.html],
+    {Rich Text (Line, Span)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_rich_text/README_md.html],
+    {Scrollbar (Scroll)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_scrollbar/README_md.html],
+    {Tabs}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_tabs/README_md.html]
+  [Graphics]
+    {Calendar}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_calendar/README_md.html],
+    {Canvas}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_canvas/README_md.html],
+    {Map (World Map)}[https://www.ratatui-ruby.dev/docs/v0.10/examples/widget_map/README_md.html]
+
+  Need something else? {Build custom widgets}[https://www.ratatui-ruby.dev/docs/v0.10/doc/concepts/custom_widgets_md.html] in Ruby!
+
+
+  ---
+
+  === Testing Built In
+
+  TUI testing is tedious. You need a headless terminal, event injection,
+  snapshot comparisons, and style assertions. RatatuiRuby bundles all of it.
+
+    require "ratatui_ruby/test_helper"
+
+    class TestColorPicker < Minitest::Test
+      include RatatuiRuby::TestHelper
+
+      def test_swatch_widget
+        with_test_terminal(10, 3) do
+          RatatuiRuby.draw do |frame|
+            frame.render_widget(Swatch.new(:red), frame.area)
+          end
+          assert_cell_style 2, 1, char: "█", bg: :red
+        end
+      end
+    end
+
+  ==== What's inside:
+
+  - <b>Headless terminal</b> — No real TTY needed
+  - <b>Snapshots</b> — Plain text and rich (ANSI colors)
+  - <b>Event injection</b> — Keys, mouse, paste, resize
+  - <b>Style assertions</b> — Color, bold, underline at any cell
+  - <b>Test doubles</b> — Mock frames and stub rects
+  - <b>UPDATE_SNAPSHOTS=1</b> — Regenerate baselines in one command
+
+
+  ---
+
+  ==== Inline Menu Example
+
+    require "ratatui_ruby"
+
+    # This example renders an inline menu. Arrow keys select, enter confirms.
+    # The menu appears in-place, preserving scrollback. When the user chooses,
+    # the TUI closes and the script continues with the selected value.
+    class RadioMenu
+      CHOICES = ["Production", "Staging", "Development"]         # ASCII strings are universally supported.
+      PREFIXES = { active: "●", inactive: "○" }                  # Some terminals may not support Unicode.
+      CONTROLS = "↑/↓: Select | Enter: Choose | Ctrl+C: Cancel"  # Let users know what keys you handle.
+      TITLES = ["Select Environment",                            # The default title position is top left.
+                { content: CONTROLS,                             # Multiple titles can save space.
+                  position: :bottom,                             # Titles go on the top or bottom,
+                  alignment: :right }]                           # aligned left, right, or center
+
+      def call                                                   # This method blocks until a choice is made.
+        RatatuiRuby.run(viewport: :inline, height: 5) do |tui|   # RatauiRuby.run manages the terminal.
+          @tui = tui                                             # The TUI instance is safe to store.
+          show_menu until chosen?                                # You can use any loop keyword you like.
+        end                                                      # `run` won't return until your block does,
+        RadioMenu::CHOICES[@choice]                              # so you can use it synchronously.
+      end
+                                                                 # Classes like RadioMenu are convenient for
+      private                                                    # CLI authors to offer "rich moments."
+
+      def show_menu = @tui.draw do |frame|                       # RatatuiRuby gives you low-level access.
+        widget = @tui.paragraph(                                 # But the TUI facade makes it easy to use.
+          text: menu_items,                                      # Text can be spans, lines, or paragraphs.
+          block: @tui.block(borders: :all, titles: TITLES)       # Blocks give you boxes and titles, and hold
+        )                                                        # one or more widgets. We only use one here,
+        frame.render_widget(widget, frame.area)                  # but "area" lets you compose sub-views.
+      end
+
+      def chosen?                                                # You are responsible for handling input.
+        interaction = @tui.poll_event                            # Every frame, you receive an event object:
+        return choose if interaction.enter?                      # Key, Mouse, Resize, Paste, FocusGained,
+                                                                 # FocusLost, or None objects. They come with
+        move_by(-1) if interaction.up?                           # predicates, support pattern matching, and
+        move_by(1) if interaction.down?                          # can be inspected for properties directly.
+        quit! if interaction.ctrl_c?                             # Your application must handle every input,
+        false                                                    # even interrupts and other exit patterns.
+      end
+
+      def choose                                                 # Here, the loop is about to exit, and the
+        prepare_next_line                                        # block will return. The inline viewport
+        @choice                                                  # will be torn down and the terminal will
+      end                                                        # be restored, but you are responsible for
+                                                                 # positioning the cursor.
+      def prepare_next_line                                      # To ensure the next output is on a new
+        area = @tui.viewport_area                                # line, query the viewport area and move
+        RatatuiRuby.cursor_position = [0, area.y + area.height]  # the cursor to the start of the last line.
+        puts                                                     # Then print a newline.
+      end
+
+      def quit!                                                  # All of your familiar Ruby control flow
+        prepare_next_line                                        # keywords work as expected, so we can
+        exit 0                                                   # use them to leave the TUI.
+      end
+
+      def move_by(line_count)                                    # You are in full control of your UX, so
+        @choice = (@choice + line_count) % CHOICES.size          # you can implement any logic you need:
+      end                                                        # Would you "wrap around" here, or not?
+                                                                 #
+      def menu_items = CHOICES.map.with_index do |choice, i|     # Notably, RatatuiRuby has no concept of
+        "\#{prefix_for(i)} \#{choice}"                             # "menus" or "radio buttons". You are in
+      end                                                        # full control, but it also means you must
+      def prefix_for(choice_index)                               # implement the logic yourself. For larger
+        return PREFIXES[:active] if choice_index == @choice      # applications, consider using Rooibos,
+        PREFIXES[:inactive]                                      # an MVU framework built with RatatuiRuby.
+      end                                                        # Or, use the upcoming ratatui-ruby-kit,
+                                                                 # our object-oriented component library.
+      def initialize = @choice = 0                               # However, those are both optional, and
+    end                                                          # designed for full-screen Terminal UIs.
+                                                                 # RatatuiRuby will always give you the most
+    choice = RadioMenu.new.call                                  # control, and is enough for "rich CLI
+    puts "You chose \#{choice}!"                                  # moments" like this one.
+
+  ---
+
+  === Full App Solutions
+
+  RatatuiRuby renders. For complex applications, add a framework that manages
+  state and composition.
+
+  ==== Rooibos[https://git.sr.ht/~kerrick/rooibos] (Framework)
+
+  Model-View-Update architecture. Inspired by Elm, Bubble Tea, and React +
+  Redux. Your UI is a pure function of state.
+
+  - Functional programming with MVU
+  - Commands work off the main thread
+  - Messages, not callbacks, drive updates
+
+  ==== {Kit}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit] (Coming Soon)
+
+  Component-based architecture. Encapsulate state, input handling, and
+  rendering in reusable pieces.
+
+  - OOP with stateful components
+  - Separate UI state from domain logic
+  - Built-in focus management & click handling
+
+  Both use the same widget library and rendering engine. Pick the paradigm
+  that fits your brain.
+
+
+  ---
+
+  === Why RatatuiRuby?
+
+  Ruby deserves world-class terminal user interfaces. TUI developers deserve
+  a world-class language.
+
+  RatatuiRuby wraps Rust's Ratatui via native extension. The Rust library
+  handles rendering. Your Ruby code handles design.
+
+  >>>
+    "Text UIs are seeing a renaissance with many new TUI libraries popping up.
+    The Ratatui bindings have proven to be full featured and stable."
+
+    — {Mike Perham}[https://www.mikeperham.com/], creator of
+    Sidekiq[https://sidekiq.org/] and Faktory[https://contribsys.com/faktory/]
+
+  ==== Why Rust? Why Ruby?
+
+  Rust excels at low-level rendering. Ruby excels at expressing domain logic
+  and UI. RatatuiRuby puts each language where it performs best.
+
+  ==== Versus CharmRuby
+
+  CharmRuby[https://charm-ruby.dev/] wraps Charm's Go libraries. Both projects
+  give Ruby developers TUI options.
+
+  [Integration]
+    CharmRuby: Two runtimes, one process.
+    RatatuiRuby: Native extension in Rust.
+  [Runtime]
+    CharmRuby: Go + Ruby (competing).
+    RatatuiRuby: Ruby (Rust has no runtime).
+  [Memory]
+    CharmRuby: Two uncoordinated GCs.
+    RatatuiRuby: One Garbage Collector.
+  [Style]
+    CharmRuby: The Elm Architecture (TEA).
+    RatatuiRuby: TEA, OOP, or Imperative.
+
+
+  ---
+
+  === Links
+
+  [Get Started]
+    {Quickstart}[https://www.ratatui-ruby.dev/docs/v0.10/doc/getting_started/quickstart_md.html],
+    {Examples}[https://www.ratatui-ruby.dev/docs/v0.10/examples/app_cli_rich_moments/README_md.html],
+    {API Reference}[https://www.ratatui-ruby.dev/docs/v0.10/],
+    {Guides}[https://www.ratatui-ruby.dev/docs/v0.10/doc/index_md.html]
+  [Ecosystem]
+    Rooibos[https://git.sr.ht/~kerrick/rooibos],
+    {Kit}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit] (Planned),
+    {Framework}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-5-the-framework] (Planned),
+    {UI Widgets}[https://sr.ht/~kerrick/ratatui_ruby/#chapter-6-licensing] (Planned)
+  [Community]
+    {Discuss and Chat}[https://lists.sr.ht/~kerrick/ratatui_ruby-discuss],
+    {Announcements}[https://lists.sr.ht/~kerrick/ratatui_ruby-announce],
+    {Development}[https://lists.sr.ht/~kerrick/ratatui_ruby-devel],
+    {Bug Tracker}[https://todo.sr.ht/~kerrick/ratatui_ruby]
+  [Contribute]
+    {Contributing Guide}[https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md],
+    {Code of Conduct}[https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md],
+    {Project History}[https://man.sr.ht/~kerrick/ratatui_ruby/history/index.md],
+    {Pull Requests}[https://lists.sr.ht/~kerrick/ratatui_ruby-devel/patches]
+
+
+  ---
+
+  [Website] https://www.ratatui-ruby.dev
+  [Source] https://git.sr.ht/~kerrick/ratatui_ruby
+  [RubyGems] https://rubygems.org/gems/ratatui_ruby
+  [Upstream] https://ratatui.rs
+  [Build Status] https://builds.sr.ht/~kerrick/ratatui_ruby
+
+  © 2026 Kerrick Long · Library: LGPL-3.0-or-later · Website: CC-BY-NC-ND-4.0 · Snippets: MIT-0
 email:
 - me@kerricklong.com
 executables:
@@ -119,6 +420,7 @@ files:
 - LICENSES/MIT-0.txt
 - LICENSES/MIT.txt
 - README.md
+- README.rdoc
 - REUSE.toml
 - Rakefile
 - Steepfile