ratatui_ruby 0.10.2 → 1.0.0.pre.beta.1

data/examples/verify_website_spinner/README.md

@@ -0,0 +1,44 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Website Spinner Verification
+
+Verifies the inline spinner example on the [RatatuiRuby website](https://ratatui-ruby.dev).
+
+This example exists as a documentation regression test. It ensures the website's inline viewport spinner demo remains functional.
+
+## Usage
+
+```ruby
+class Spinner
+  def main
+    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) }
+        return ending(tui, "Canceled!", :red) if tui.poll_event.ctrl_c?
+      end
+      ending(tui, "Connected!", :green)
+    end
+  end
+
+  def ending(tui, message, color) = tui.draw do |frame|
+    frame.render_widget(tui.paragraph(text: message, fg: color), frame.area)
+  end
+
+  def initialize = (@i, @end = 0, Time.now + 2)
+  def connected? = Time.now >= @end
+  def spin = SPINNER[(@i += 1) % SPINNER.length]
+  SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏]
+end
+Spinner.new.main; puts
+```
+
+## Features Demonstrated
+
+- **Inline viewport**: 1-line viewport that preserves terminal scrollback
+- **Ctrl+C handling**: Graceful cancellation with `poll_event.ctrl_c?`
+- **Colored output**: Status messages with `:red` and `:green` colors
+- **Timeout pattern**: Uses `Time.now` for connection simulation

data/examples/verify_website_spinner/app.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#++
+
+# Test 1: Inline spinner example
+require "ratatui_ruby"
+
+class Spinner
+  def main
+    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) }
+        return ending(tui, "Canceled!", :red) if tui.poll_event.ctrl_c?
+      end
+      ending(tui, "Connected!", :green)
+    end
+  end
+
+  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 + 2)
+  def connected? = Time.now >= @finish # Simulate work
+  def spin = SPINNER[(@frame += 1) % SPINNER.length]
+  SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏]
+end
+Spinner.new.main

data/ext/ratatui_ruby/Cargo.lock

@@ -1059,7 +1059,7 @@ dependencies = [
 
 [[package]]
 name = "ratatui_ruby"
-version = "0.10.2"
+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.2"
+version = "1.0.0-beta.1"
 edition = "2021"
 
 [lib]

data/lib/ratatui_ruby/labs/a11y.rb

@@ -6,7 +6,6 @@
 #++
 
 require "tmpdir"
-require "rexml/document"
 
 module RatatuiRuby
   module Labs
@@ -21,6 +20,7 @@ module RatatuiRuby
       class << self
         # Dumps the widget tree to XML (single widget for tree mode).
         def dump_widget_tree(widget, _area = nil)
+          ensure_rexml_loaded
           doc = REXML::Document.new
           doc.add(REXML::XMLDecl.new("1.0", "UTF-8"))
           doc.add(build_element(widget))
@@ -42,6 +42,7 @@ module RatatuiRuby
 
         # Dumps multiple widgets captured from Frame API mode.
         def dump_widgets(widgets_with_areas)
+          ensure_rexml_loaded
           Labs.warn_once!("Labs::A11y (RR_LABS=A11Y)")
 
           # Reset counter each frame for stable IDs
@@ -167,6 +168,14 @@ module RatatuiRuby
 
           element
         end
+
+        # Lazily loads REXML when first needed.
+        private def ensure_rexml_loaded
+          return if defined?(@rexml_loaded) && @rexml_loaded
+
+          require "rexml/document"
+          @rexml_loaded = true
+        end
       end
     end
   end

data/lib/ratatui_ruby/layout/rect.rb

@@ -701,6 +701,30 @@ module RatatuiRuby
         centered_horizontally(horizontal_constraint).centered_vertically(vertical_constraint)
       end
 
+      # Enables array destructuring of the rectangle.
+      #
+      # Inline viewports and layout code often need position and size together.
+      # Accessing x, y, width, height individually is verbose.
+      #
+      # This method allows convenient array destructuring.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   area = tui.viewport_area
+      #   x, y, width, height = area
+      #   # Now you can use x, y, width, height directly
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def to_ary
+        [x, y, width, height]
+      end
+
       # Ruby-idiomatic aliases (TIMTOWTDI)
       alias position as_position
       alias size as_size

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.2"
+  VERSION = "1.0.0-beta.1"
 end

data/sig/ratatui_ruby/labs.rbs

@@ -58,6 +58,8 @@ module RatatuiRuby
     module A11y
       OUTPUT_PATH: String
 
+      @rexml_loaded: bool?
+
       def self.dump_widget_tree: ((_CustomWidget | widget) widget, ?Layout::Rect? area) -> void
       def self.dump_widgets: (Array[[(_CustomWidget | widget), Layout::Rect]] widgets_with_areas) -> void
       def self.startup_message: () -> String
@@ -70,6 +72,7 @@ module RatatuiRuby
       def self.add_members: (REXML::Element element, untyped node, ?parent_id: String?) -> void
       def self.scalar?: (untyped value) -> bool
       def self.build_child_element: (Symbol key, untyped value, ?is_wrapper: bool, ?parent_id: String?) -> REXML::Element
+      def self.ensure_rexml_loaded: () -> void
     end
   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/resources/index.html.erb

@@ -5,40 +5,137 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 -->
 
 <!DOCTYPE html>
-<html>
+<html lang="en">
 <head>
+  <meta charset="UTF-8">
   <title><%= project_name %> documentation</title>
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <style>
-    :root { color-scheme: light dark; }
-    body { font-family: system-ui, sans-serif; max-width: 800px; margin: 0 auto; padding: 2rem; line-height: 1.5; color: light-dark(#111, #eee); background: light-dark(#fff, #111); }
-    h1 { border-bottom: 2px solid light-dark(#eee, #333); padding-bottom: 0.5rem; }
-    ul { list-style: none; padding: 0; }
-    li { margin: 0.5rem 0; border: 1px solid light-dark(#ddd, #444); border-radius: 4px; }
-    a { display: block; padding: 1rem; text-decoration: none; color: light-dark(#0055aa, #44aaff); font-weight: bold; }
-    a:hover { background: light-dark(#f5f5f5, #222); }
-    .meta { font-weight: normal; color: light-dark(#666, #aaa); font-size: 0.9em; float: right; }
-  </style>
+  <meta name="description" content="API documentation and guides for <%= project_name %>, organized by version.">
+  <link rel="stylesheet" href="../styles.css">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link
+    href="https://fonts.googleapis.com/css2?family=Fraunces:ital,opsz,wght@0,9..144,300..900;1,9..144,300..900&family=Source+Sans+3:ital,wght@0,300..900;1,300..900&display=swap"
+    rel="stylesheet">
 </head>
 <body>
-  <h1><%= project_name %> documentation</h1>
-  <ul>
-    <% versions.each do |version| %>
-      <li>
-        <a href='<%= version.slug %>/index.html'>
-          <%= version.name %>
-          <span class='meta'>
-            <% if version.latest? %>
-              Latest
-            <% elsif version.edge? %>
-              Edge
-            <% else %>
-              Historical
-            <% end %>
-          </span>
-        </a>
-      </li>
-    <% end %>
-  </ul>
+  <header class="header">
+    <div class="header__inner">
+      <a href="/" class="header__brand">
+        <img src="../logo-small.png" alt="RatatuiRuby Logo" class="header__logo" width="48" height="48">
+        <span class="header__wordmark">RatatuiRuby</span>
+      </a>
+      <nav class="header__nav" aria-label="Primary">
+        <a href="/#rich-moments">Better <abbr title="Command Line Interfaces">CLIs</abbr></a>
+        <a href="/#build">Full <abbr title="Terminal User Interfaces">TUIs</abbr></a>
+        <a href="/#frameworks">Frameworks</a>
+        <a href="/docs/v0.10/" class="header__nav-external">API →</a>
+        <a href="/docs/v0.10/doc/index_md.html" class="header__nav-external">Guides →</a>
+      </nav>
+    </div>
+  </header>
+
+  <main>
+    <section class="section">
+      <div class="section__inner">
+        <header class="section__header">
+          <span class="section__eyebrow">Reference</span>
+          <h1 class="section__title">Documentation</h1>
+          <p class="section__intro">API reference, guides, and examples for current and past versions of <%= project_name %>.</p>
+        </header>
+
+        <ul class="version-list">
+          <% versions.each do |version| %>
+            <li class="version-list__item<%= ' version-list__item--latest' if version.latest? %>">
+              <a href="<%= version.slug %>/index.html" class="version-list__link">
+                <span class="version-list__name"><%= version.name %></span>
+                <span class="version-list__meta">
+                  <% if version.latest? %>
+                    Latest release via RubyGems
+                  <% elsif version.edge? %>
+                    Pre-release via git
+                  <% else %>
+                    Historical
+                  <% end %>
+                </span>
+              </a>
+            </li>
+          <% end %>
+        </ul>
+      </div>
+    </section>
+  </main>
+
+  <footer class="footer">
+    <div class="footer__inner">
+      <!-- Megafooter columns -->
+      <div class="footer__columns">
+        <div class="footer__column">
+          <h3 class="footer__heading">Get Started</h3>
+          <ul class="footer__list">
+            <li><a href="/docs/v0.10/doc/getting_started/quickstart_md.html">Quickstart <span
+                  class="footer__tag">Alpha</span></a>
+            </li>
+            <li><a href="/docs/v0.10/examples/app_cli_rich_moments/README_md.html">Examples</a></li>
+            <li><a href="/docs/v0.10/"><abbr title="Application Programming Interface">API</abbr> Reference</a></li>
+            <li><a href="/docs/v0.10/doc/index_md.html">Guides</a></li>
+          </ul>
+        </div>
+
+        <div class="footer__column">
+          <h3 class="footer__heading">Ecosystem</h3>
+          <ul class="footer__list">
+            <li><a href="https://git.sr.ht/~kerrick/ratatui_ruby-tea">Tea <span
+                  class="footer__tag">Alpha</span></a></li>
+            <li><a href="https://sr.ht/~kerrick/ratatui_ruby/#chapter-3-the-object-path--kit">Kit <span
+                  class="footer__tag footer__tag--muted">Planned</span></a></li>
+            <li><a href="https://sr.ht/~kerrick/ratatui_ruby/#chapter-5-the-framework">Framework <span
+                  class="footer__tag footer__tag--muted">Planned</span></a></li>
+            <li><a href="https://sr.ht/~kerrick/ratatui_ruby/#chapter-6-licensing"><abbr
+                  title="User Interface">UI</abbr> Widgets
+                <span class="footer__tag footer__tag--muted">Planned</span></a></li>
+          </ul>
+        </div>
+
+        <div class="footer__column">
+          <h3 class="footer__heading">Community</h3>
+          <ul class="footer__list">
+            <li><a href="https://lists.sr.ht/~kerrick/ratatui_ruby-discuss">Discuss and Chat</a></li>
+            <li><a href="https://lists.sr.ht/~kerrick/ratatui_ruby-announce">Announcements</a></li>
+            <li><a href="https://lists.sr.ht/~kerrick/ratatui_ruby-devel">Development</a></li>
+            <li><a href="https://todo.sr.ht/~kerrick/ratatui_ruby">Bug Tracker</a></li>
+          </ul>
+        </div>
+
+        <div class="footer__column">
+          <h3 class="footer__heading">Contribute</h3>
+          <ul class="footer__list">
+            <li><a href="https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md">Contributing Guide</a></li>
+            <li><a href="https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md">Code of Conduct</a></li>
+            <li><a href="https://man.sr.ht/~kerrick/ratatui_ruby/history/index.md">Project History</a></li>
+            <li><a href="https://lists.sr.ht/~kerrick/ratatui_ruby-devel/patches">Pull Requests</a></li>
+          </ul>
+        </div>
+      </div>
+
+      <!-- Bottom bar -->
+      <div class="footer__bottom">
+        <div class="footer__brand">
+          <img src="../logo-small.png" alt="" class="footer__logo" width="32" height="32" aria-hidden="true">
+          <span class="footer__wordmark">RatatuiRuby</span>
+        </div>
+        <nav class="footer__meta" aria-label="Meta links">
+          <a href="https://git.sr.ht/~kerrick/ratatui_ruby">Source</a>
+          <a href="https://rubygems.org/gems/ratatui_ruby">RubyGems</a>
+          <a href="https://ratatui.rs">Ratatui</a>
+          <a href="https://builds.sr.ht/~kerrick/ratatui_ruby?">Build Status</a>
+        </nav>
+        <p class="footer__copy">© 2026&nbsp;Kerrick&nbsp;Long · Library:&nbsp;<a
+            href="https://spdx.org/licenses/LGPL-3.0-or-later.html">LGPL-3.0-or-later</a> · Website:&nbsp;<a
+            href="https://spdx.org/licenses/CC-BY-NC-ND-4.0.html">CC-BY-NC-ND-4.0</a> · Snippets:&nbsp;<a
+            href="https://spdx.org/licenses/MIT-0.html">MIT-0</a></p>
+      </div>
+    </div>
+  </footer>
 </body>
 </html>

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")
 

data/tasks/website/version.rb

@@ -52,11 +52,11 @@ end
 
 class Edge < Version
   def slug
-    "main"
+    "trunk"
   end
 
   def name
-    "main"
+    "trunk"
   end
 
   def type

data/tasks/website/versioned_documentation.rb

@@ -29,7 +29,7 @@ class VersionedDocumentation
 
       Dir.chdir(source_path) do
         title = "#{project_name} #{@version.name}"
-        title = "#{project_name} (main)" if @version.edge?
+        title = "#{project_name} (trunk)" if @version.edge?
 
         # Use rake rerdoc to ensure copy_examples runs
         # Set environment variables to override rdoc settings

data/tasks/website.rake

@@ -11,7 +11,7 @@ require "tmpdir"
 require_relative "rdoc_config"
 
 namespace :website do
-  desc "Build documentation for main (current dir) and all git tags"
+  desc "Build documentation for trunk (current dir) and all git tags"
   task :build do
     require_relative "website/website"