rooibos 0.5.0

data/sig/rooibos/router.rbs

@@ -0,0 +1,153 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  # Declarative DSL for Fractal Architecture.
+  module Router
+  def self.included: (Class base) -> void
+
+  # Duck type for Data-like models that support `with`.
+  interface _DataModel
+    def public_send: (Symbol, *Object) -> Object
+    def with: (**Object) -> self
+  end
+
+  # Interface for fractal child modules (fragments).
+  # Routed modules must have an UPDATE constant that handles child messages.
+  # NOTE: We use Module here because RBS interfaces can't declare class methods.
+
+  # Configuration for key handlers.
+  class KeyHandlerConfig < Data
+    attr_reader handler: (^() -> Command::execution?)?
+    attr_reader action: Symbol?
+    attr_reader route: Symbol?
+    attr_reader guard: (^(_DataModel) -> bool)?
+
+    def initialize: (?handler: (^() -> Command::execution?)?, ?action: Symbol?, ?route: Symbol?, ?guard: (^(_DataModel) -> bool)?) -> void
+  end
+
+  # Configuration for scroll handlers (no coordinates).
+  class ScrollHandlerConfig < Data
+    attr_reader handler: (^() -> Command::execution?)?
+    attr_reader action: Symbol?
+
+    def initialize: (?handler: (^() -> Command::execution?)?, ?action: Symbol?) -> void
+  end
+
+  # Configuration for click handlers (x, y coordinates).
+  class ClickHandlerConfig < Data
+    attr_reader handler: (^(Integer, Integer) -> Command::execution?)?
+    attr_reader action: Symbol?
+
+    def initialize: (?handler: (^(Integer, Integer) -> Command::execution?)?, ?action: Symbol?) -> void
+  end
+
+  # Class methods added when Router is included.
+  module ClassMethods : Module
+    @routes: Hash[Symbol, Module]
+    @actions: Hash[Symbol, ^() -> Command::execution?]
+    @key_handlers: Hash[String, KeyHandlerConfig]
+    @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+    @click_handler: ClickHandlerConfig?
+
+    def route: (Symbol | String prefix, to: Module) -> void
+    def routes: () -> Hash[Symbol, Module]
+
+    def action: (Symbol | String name, ^() -> Command::execution? handler) -> void
+    def actions: () -> Hash[Symbol, ^() -> Command::execution?]
+
+    def keymap: () { (KeymapBuilder) [self: KeymapBuilder] -> void } -> void
+    def key_handlers: () -> Hash[String, KeyHandlerConfig]
+
+    def mousemap: () { (MousemapBuilder) [self: MousemapBuilder] -> void } -> void
+    def scroll_handlers: () -> Hash[Symbol, ScrollHandlerConfig]
+    def click_handler: () -> ClickHandlerConfig?
+
+    # Returns UPDATE callable that handles routing.
+    # Uses is_a? checks for Event::Key and Event::Mouse type narrowing.
+    # Model must be Data-like with `with` and field accessors.
+    def from_router: () -> RouterUpdate
+  end
+
+  # UPDATE callable returned by from_router with proper typing.
+  # Implements #call to satisfy Proc-like interfaces.
+  class RouterUpdate
+    @routes: Hash[Symbol, Module]
+    @actions: Hash[Symbol, ^() -> Command::execution?]
+    @key_handlers: Hash[String, KeyHandlerConfig]
+    @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+    @click_handler: ClickHandlerConfig?
+
+    def initialize: (
+      routes: Hash[Symbol, Module],
+      actions: Hash[Symbol, ^() -> Command::execution?],
+      key_handlers: Hash[String, KeyHandlerConfig],
+      scroll_handlers: Hash[Symbol, ScrollHandlerConfig],
+      click_handler: ClickHandlerConfig?
+    ) -> void
+
+    # Process message and return [model, command] tuple.
+    def call: (
+      (RatatuiRuby::Event::Key | RatatuiRuby::Event::Mouse | Array[Object]) message,
+      _DataModel model
+    ) -> [_DataModel, Command::execution?]
+  end
+
+  # Builder for keymap DSL.
+  class KeymapBuilder
+    @handlers: Hash[String, KeyHandlerConfig]
+    @guard_stack: Array[^(_DataModel) -> bool]
+
+    attr_reader handlers: Hash[String, KeyHandlerConfig]
+
+    def initialize: () -> void
+
+    def key: (
+      String | Symbol key_name,
+      (^() -> Command::execution?) | Symbol handler_or_action,
+      ?route: Symbol?,
+      ?when: (^(_DataModel) -> bool)?,
+      ?if: (^(_DataModel) -> bool)?,
+      ?only: (^(_DataModel) -> bool)?,
+      ?guard: (^(_DataModel) -> bool)?,
+      ?unless: (^(_DataModel) -> bool)?,
+      ?except: (^(_DataModel) -> bool)?,
+      ?skip: (^(_DataModel) -> bool)?
+    ) -> void
+
+    def only: (
+      ?when: (^(_DataModel) -> bool)?,
+      ?if: (^(_DataModel) -> bool)?,
+      ?only: (^(_DataModel) -> bool)?,
+      ?guard: (^(_DataModel) -> bool)?
+    ) { () -> void } -> void
+
+    def skip: (
+      ?when: (^(_DataModel) -> bool)?,
+      ?if: (^(_DataModel) -> bool)?,
+      ?skip: (^(_DataModel) -> bool)?,
+      ?guard: (^(_DataModel) -> bool)?
+    ) { () -> void } -> void
+
+    private
+
+    def with_guard: ((^(_DataModel) -> bool)?) { () -> void } -> void
+  end
+
+  # Builder for mousemap DSL.
+  class MousemapBuilder
+    @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+    @click_handler: ClickHandlerConfig?
+
+    attr_reader scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+    attr_reader click_handler: ClickHandlerConfig?
+
+    def initialize: () -> void
+
+    def click: ((^(Integer, Integer) -> Command::execution?) | Symbol handler_or_action) -> void
+    def scroll: (:up | :down direction, (^() -> Command::execution?) | Symbol handler_or_action) -> void
+  end
+end
+end

data/sig/rooibos/runtime.rbs

@@ -0,0 +1,75 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  # MVU runtime event loop.
+  class Runtime
+  # Active command tracking entry.
+  type active_entry = { future: Concurrent::Promises::Future[void], origin: Concurrent::Promises::ResolvableEvent }
+
+  # Widget type accepted by view functions.
+  type renderable = RatatuiRuby::_CustomWidget | RatatuiRuby::widget
+
+  # Duck type for update result that can be normalized.
+  # Steep needs a union type (not interface) for is_a? narrowing.
+  type update_result = [Object, Command::execution?] | Command::execution | Object
+
+  # Duck type for init result that can be normalized.
+  type init_result = [Object, Command::execution?] | Command::execution | Object
+
+  # Duck type for values that can be queried for command-ness.
+  interface _MaybeCommand
+    def nil?: () -> bool
+    def class: () -> Class
+    def respond_to?: (Symbol, ?bool) -> bool
+    def rooibos_command?: () -> bool
+  end
+
+  # Starts the MVU event loop (positional fragment).
+  def self.run: [Model] (
+    ?Module? root_fragment,
+    ?fps: Integer
+  ) -> Model
+
+  # Starts the MVU event loop (explicit parameters).
+  | [Model] (
+    ?Module? root_fragment,
+    ?fps: Integer,
+    model: Model,
+    view: ^(Model, RatatuiRuby::TUI) -> renderable,
+    update: ^(RatatuiRuby::Event, Model) -> update_result?,
+    ?command: Command::execution?
+  ) -> Model
+
+  # Starts the MVU event loop (explicit parameters without fps).
+  | [Model] (
+    ?Module? root_fragment,
+    model: Model,
+    view: ^(Model, RatatuiRuby::TUI) -> renderable,
+    update: ^(RatatuiRuby::Event, Model) -> update_result?,
+    ?command: Command::execution?
+  ) -> Model
+
+  # Normalizes Init callable return value to [model, command] tuple.
+  def self.normalize_init: [Model] (init_result result) -> [Model?, Command::execution?]
+  QUIT: Object
+
+  private
+
+  def self.validate_view_return!: (renderable? widget) -> void
+  def self.normalize_update_return: [Model] (update_result? result, Model? previous_model) -> [Model?, Command::execution?]
+  def self.validate_ractor_shareable!: [T] (T object, String name) -> void
+  def self.fragment_from_kwargs: (Module? root_fragment, ?model: untyped, ?view: untyped, ?update: untyped, ?command: untyped) -> Module
+  def self.fragment_invariant!: (String param) -> void
+  def self.init_callable: [Model] () -> ^() -> [Model?, Command::execution?]
+  def self.start_runtime: () -> untyped
+  def self.draw_view: () -> void
+  def self.handle_ratatui_event: () -> void
+  def self.handle_sync: () -> void
+  QUEUE_EMPTY: Object
+  def self.send_pending_messages: (?dispatch: bool) -> void
+  def self.dispatch_command: () -> void
+end
+end

data/sig/rooibos/shortcuts.rbs

@@ -0,0 +1,16 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  # Convenient short aliases for Rooibos APIs.
+  module Shortcuts
+  # Short alias for Command.
+  module Cmd
+    def self.exit: () -> Command::Exit
+    def self.sh: (String command, Symbol | Class tag) -> Command::System
+    def self.map: (Command::execution inner_command) { (Array[untyped]) -> Array[untyped] } -> Command::Mapped
+  end
+end
+end

data/sig/rooibos/test_helper.rbs

@@ -0,0 +1,10 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module TestHelper
+  def validate_rooibos_command!: (Runtime::_MaybeCommand) -> nil
+end
+end

data/sig/rooibos/version.rbs

@@ -0,0 +1,8 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  VERSION: String
+end

data/sig/rooibos.rbs

@@ -0,0 +1,46 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# The Elm Architecture for Ruby.
+module Rooibos
+  # Starts the MVU event loop (positional fragment).
+  def self.run: [Model] (
+    ?Module? root_fragment,
+    ?fps: Integer
+  ) -> Model
+
+  # Starts the MVU event loop (explicit parameters).
+  | [Model] (
+    ?Module? root_fragment,
+    ?fps: Integer,
+    model: Model,
+    view: ^(Model, RatatuiRuby::TUI) -> Runtime::renderable,
+    update: ^(RatatuiRuby::Event, Model) -> Runtime::update_result?,
+    ?command: Command::execution?
+  ) -> Model
+
+  # Starts the MVU event loop (explicit parameters without fps).
+  | [Model] (
+    ?Module? root_fragment,
+    model: Model,
+    view: ^(Model, RatatuiRuby::TUI) -> Runtime::renderable,
+    update: ^(RatatuiRuby::Event, Model) -> Runtime::update_result?,
+    ?command: Command::execution?
+  ) -> Model
+
+  # Wraps a command with a routing prefix.
+  def self.route: (Command::execution command, Symbol prefix) -> Command::Mapped
+
+  # Delegates a prefixed message to a child fragment's UPDATE.
+  def self.delegate: (
+    untyped message,
+    Symbol prefix,
+    ^(Array[untyped]?, untyped) -> [untyped, Command::execution?] child_update,
+    untyped child_model
+  ) -> ([untyped, Command::execution?] | nil)
+
+  # Normalizes Init callable return value to [model, command] tuple.
+  def self.normalize_init: [Model] (Runtime::init_result result) -> [Model?, Command::execution?]
+end

data/tasks/example_viewer.html.erb

@@ -0,0 +1,172 @@
+<%#
+SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: LGPL-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,53 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+image: archlinux
+packages:
+  - bash
+  - base-devel
+  - curl
+  - openssl
+  - libyaml
+  - zlib
+  - readline
+  - gdbm
+  - ncurses
+  - libffi
+  - clang
+  - 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
+      echo 'export BINDGEN_EXTRA_CLANG_ARGS="-include stdbool.h"' >> ~/.buildenv
+      . ~/.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
+  - 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: LGPL-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: LGPL-3.0-or-later
+
+- "3.2"
+- "3.3"
+- "3.4"
+- "4.0.0"

data/tasks/steep.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+desc "Run Steep type checker"
+task :steep do
+  sh "bundle exec steep check"
+end