ratatui_ruby-kit 0.1.0

data/doc/getting_started/quickstart.md

@@ -0,0 +1,56 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Quickstart
+
+Welcome to **ratatui_ruby-kit**! This guide will help you get up and running with your first Terminal User Interface in Ruby.
+
+## Installation
+
+See [Installation in the README](../README.md#installation) for setup instructions.
+
+
+## Tutorials
+
+### Basic Application
+
+Here is a "Hello World" application that demonstrates the core lifecycle of a **ratatui_ruby-kit** app.
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+
+#### How it works
+
+_Because this gem is in pre-release, it lacks documentation. Please check the source files.
+
+## Examples
+
+These examples showcase the full power of **ratatui_ruby-kit**. You can find their source code in the [examples directory](../examples).
+
+### Widget Demos
+
+Focused examples for individual concepts. Each demonstrates a single concept and ways to interact with it.
+
+| Widget | What it demonstrates |
+|--------|---------------------|
+| _Automated Tests_ | _Because this gem is in pre-release, it lacks documentation. Please check the automated tests for details._ |
+
+### Sample Applications
+
+These larger examples combine concepts into complete applications, demonstrating real-world TUI patterns and architectures.
+
+| Application | Architecture | What you'll learn |
+|-------------|--------------|-------------------|
+| _Automated Tests_ | _Because this gem is in pre-release, it lacks documentation. Please check the automated tests for details._ |
+
+
+## Next Steps
+
+Now that you've seen what **ratatui_ruby-kit** can do:
+
+- **Deep dive**: Read the [Application Architecture](../concepts/application_architecture.md) guide for scaling patterns
+- **Test your TUI**: See the [Testing Guide](../concepts/application_testing.md) for snapshot and style assertions
+- **Avoid common mistakes**: See [Terminal Output During TUI Sessions](https://man.sr.ht/~kerrick/ratatui_ruby/troubleshooting/tui_output.md) to prevent screen corruption
+- **Explore the API**: Browse the [full documentation](../index.md)
+- **Learn the philosophy**: Read [Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md) for comparisons and design decisions
+- **Get help**: Join the [discussion mailing list](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss)

data/doc/index.md

@@ -0,0 +1,25 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+# Start Here
+
+
+## Documentation for Users
+
+- [README](../README.md): Project overview and installation
+
+### Getting Started
+
+- [Why RatatuiRuby?](https://man.sr.ht/~kerrick/ratatui_ruby/why.md): Philosophy, comparisons, and what makes us different
+- [Quickstart](./getting_started/quickstart.md): Build your first TUI app
+
+### Concepts
+
+- [Application Architecture](./concepts/application_architecture.md): Lifecycle patterns and API choices
+- [Testing Your Application](./concepts/application_testing.md): Snapshot testing and style assertions
+
+
+## Documentation for Contributors
+
+- [Contributing Guidelines](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md): How to contribute patches and features

data/lib/ratatui_ruby/kit/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
+  module Kit
+    # The version of this gem.
+    # See https://semver.org/spec/v2.0.0.html
+    VERSION = "0.1.0"
+  end
+end

data/lib/ratatui_ruby/kit.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require_relative "kit/version"
+
+# Entry point for the ratatui_ruby-kit gem.
+#
+# Ruby libraries benefit from a clear namespace. Gems need a central module.
+#
+# This module serves as the namespace root. All classes and utilities live here.
+#
+# Require this file to load the library.
+module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
+  # Namespace for library functionality.
+  module Kit
+  end
+end

data/mise.toml

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[tools]
+ruby = "4.0.0"
+python = "3.12"
+pre-commit = "latest"

data/tasks/example_viewer.html.erb

@@ -0,0 +1,172 @@
+<%#
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: AGPL-3.0-or-later
+%>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title><%= page_title %> - Example Viewer</title>
+  
+  <script>
+  var rdoc_rel_prefix = "<%= doc_root_link.sub('index.html', '') %>";
+  var index_rel_prefix = "<%= '../' * (relative_path.split('/').size - 1) %>";
+  </script>
+
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/search_navigation.js" defer></script>
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/search_data.js" defer></script>
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/search_ranker.js" defer></script>
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/search_controller.js" defer></script>
+  <script src="<%= '../' * (relative_path.split('/').size - 1) %>js/aliki.js" defer></script>
+
+  <link href="<%= doc_root_link.sub('index.html', '') %>css/rdoc.css" rel="stylesheet">
+  <link href="<%= doc_root_link.sub('index.html', '') %>custom.css" rel="stylesheet">
+</head>
+<body class="file<%= ' has-toc' unless toc_items.empty? %>">
+<%= icons_svg %>
+  <header class="top-navbar">
+    <div class="navbar-brand">
+      Example Viewer
+    </div>
+    
+    <!-- Desktop search bar -->
+    <div class="navbar-search navbar-search-desktop" role="search">
+      <form action="#" method="get" accept-charset="utf-8">
+        <input id="search-field" role="combobox" aria-label="Search"
+               aria-autocomplete="list" aria-controls="search-results-desktop"
+               type="text" name="search" placeholder="Search (/) examples..."
+               spellcheck="false" autocomplete="off"
+               title="Type to search, Up and Down to navigate, Enter to load">
+        <ul id="search-results-desktop" aria-label="Search Results"
+            aria-busy="false" aria-expanded="false"
+            aria-atomic="false" class="initially-hidden search-results"></ul>
+      </form>
+    </div>
+
+    <!-- Mobile search icon button -->
+    <button id="search-toggle" class="navbar-search-mobile" aria-label="Open search" type="button">
+      <span aria-hidden="true">🔍</span>
+    </button>
+
+    <button id="theme-toggle" class="theme-toggle" aria-label="Switch to dark mode" type="button" onclick="cycleColorMode()">
+      <span class="theme-toggle-icon" aria-hidden="true">🌙</span>
+    </button>
+  </header>
+
+  <!-- Search Modal (Mobile) -->
+  <div id="search-modal" class="search-modal" hidden aria-modal="true" role="dialog" aria-label="Search">
+    <div class="search-modal-backdrop"></div>
+    <div class="search-modal-content">
+      <div class="search-modal-header">
+        <form class="search-modal-form" action="#" method="get" accept-charset="utf-8">
+          <span class="search-modal-icon" aria-hidden="true">🔍</span>
+          <input id="search-field-mobile" role="combobox" aria-label="Search"
+                 aria-autocomplete="list" aria-controls="search-results-mobile"
+                 type="text" name="search" placeholder="Search examples"
+                 spellcheck="false" autocomplete="off">
+          <button type="button" class="search-modal-close" aria-label="Close search" id="search-modal-close">
+            <span aria-hidden="true">esc</span>
+          </button>
+        </form>
+      </div>
+      <div class="search-modal-body">
+        <ul id="search-results-mobile" aria-label="Search Results"
+            aria-busy="false" aria-expanded="false"
+            aria-atomic="false" class="search-results search-modal-results initially-hidden"></ul>
+        <div class="search-modal-empty">
+          <p>No recent searches</p>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <nav id="navigation" role="navigation">
+    <div id="fileindex-section" class="nav-section">
+      <details class="nav-section-collapsible" open>
+        <summary class="nav-section-header">
+          <span class="nav-section-icon">
+             <svg><use href="#icon-file"></use></svg>
+          </span>
+          <span class="nav-section-title">Examples</span>
+          <span class="nav-section-chevron">
+            <svg><use href="#icon-chevron"></use></svg>
+          </span>
+        </summary>
+        <ul class="nav-list">
+          <li><a href="<%= doc_root_link %>">← Back to Docs</a></li>
+        </ul>
+      </details>
+    </div>
+    <div class="nav-section">
+      <details class="nav-section-collapsible" open>
+        <summary class="nav-section-header">
+          <span class="nav-section-icon">
+            <svg><use href="#icon-layers"></use></svg>
+          </span>
+          <span class="nav-section-title">Files</span>
+          <span class="nav-section-chevron">
+            <svg><use href="#icon-chevron"></use></svg>
+          </span>
+        </summary>
+        <ul class="link-list nav-list">
+          <%= render_tree(tree_data, relative_path, current_file_html) %>
+        </ul>
+      </details>
+    </div>
+  </nav>
+
+  <main role="main">
+    <div class="breadcrumb">
+      <%= breadcrumb_path %>
+    </div>
+    <%= file_header_html %>
+    <div class="content">
+      <%= file_content_html %>
+    </div>
+  </main>
+
+  <% unless toc_items.empty? %>
+  <aside class="table-of-contents" role="complementary" aria-label="Table of Contents">
+    <div class="toc-sticky">
+      <div class="toc-list">
+        <h3>On This Page</h3>
+        <%= render_toc(toc_items) %>
+      </div>
+    </div>
+  </aside>
+  <% end %>
+
+
+  <script>
+    const modes = ['auto', 'light', 'dark'];
+    const icons = { auto: '🌓', light: '☀️', dark: '🌙' };
+    
+    function setColorMode(mode) {
+      if (mode === 'auto') {
+        document.documentElement.removeAttribute('data-theme');
+        const systemTheme = (window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches) ? 'dark' : 'light';
+        document.documentElement.setAttribute('data-theme', systemTheme);
+      } else {
+        document.documentElement.setAttribute('data-theme', mode);
+      }
+      
+      const icon = icons[mode];
+      const toggle = document.getElementById('theme-toggle');
+      toggle.querySelector('.theme-toggle-icon').textContent = icon;
+      
+      localStorage.setItem('rdoc-theme', mode);
+    }
+    
+    function cycleColorMode() {
+      const current = localStorage.getItem('rdoc-theme') || 'auto';
+      const currentIndex = modes.indexOf(current);
+      const nextMode = modes[(currentIndex + 1) % modes.length];
+      setColorMode(nextMode);
+    }
+    
+    const savedMode = localStorage.getItem('rdoc-theme') || 'auto';
+    setColorMode(savedMode);
+  </script>
+</body>
+</html>

data/tasks/resources/build.yml.erb

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+<%- if has_rust -%>
+  - clang
+<%- end -%>
+  - git
+artifacts:
+  - <%= gem_name %>/pkg/<%= gem_filename %>
+sources:
+  - https://git.sr.ht/~kerrick/<%= gem_name %>
+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
+      echo 'export LANG="en_US.UTF-8"' >> ~/.buildenv
+      echo 'export LC_ALL="en_US.UTF-8"' >> ~/.buildenv
+<%- if has_rust -%>
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
+<%- end -%>
+      . ~/.buildenv
+      export CI="true"
+      cd <%= gem_name %>
+      sed -i 's/ruby = .*/ruby = "<%= ruby_version %>"/' mise.toml
+      mise install
+      mise x -- pip install reuse
+      mise x -- gem install bundler:<%= bundler_version %>
+      mise reshim
+      mise x -- bundle config set --local frozen 'true'
+      mise x -- bundle install
+<%- if has_rust -%>
+      mise x -- bundle exec rake compile
+<%- end -%>
+  - test: |
+      . ~/.buildenv
+      cd <%= gem_name %>
+      echo "Testing Ruby <%= ruby_version %>"
+      mise x -- bundle exec rake test
+  - lint: |
+      . ~/.buildenv
+      cd <%= gem_name %>
+      echo "Linting Ruby <%= ruby_version %>"
+      mise x -- bundle exec rake lint
+  - package: |
+      . ~/.buildenv
+      cd <%= gem_name %>
+      mise x -- bundle exec rake build

data/tasks/resources/index.html.erb

@@ -0,0 +1,44 @@
+<!--
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+<!DOCTYPE html>
+<html>
+<head>
+  <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>
+</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>
+</body>
+</html>

data/tasks/resources/rubies.yml

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+- "3.2"
+- "3.3"
+- "3.4"
+- "4.0.0"