ratatui_ruby 0.8.0 → 0.9.1

data/examples/app_all_events/README.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # App All Events Example
@@ -33,9 +33,15 @@ Semantic value objects that decouple raw terminal events from business logic:
 ### 3. Update (`update.rb`)
 A **pure function** that computes the next state:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 Update.call(msg, model) -> Model
 ```
+<!-- SPDX-SnippetEnd -->
 
 All logic previously in `Events.record` now lives here. The function never mutates, never draws, never performs IO.
 
@@ -47,6 +53,11 @@ Pure rendering logic. Views accept the immutable `AppModel` and draw to the scre
 ### 5. Runtime (`app.rb`)
 The MVU loop:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 loop do
   tui.draw { |f| view.call(model, tui, f, f.area) }
@@ -55,6 +66,7 @@ loop do
   model = Update.call(msg, model)
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Library Features Showcased
 

data/examples/app_all_events/app.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/app_model.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/event_color_cycle.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/event_entry.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/msg.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/model/timestamp.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/update.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/app_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/controls_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/counts_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/live_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view/log_view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_all_events/view.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/README.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Color Picker Example
@@ -23,6 +23,11 @@ This app uses a **Strict Component-Based Architecture** where every UI element e
 
 Every component implements this duck-type interface:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 # Renders the component into the given area
 # Caches `area` for hit testing
@@ -40,6 +45,7 @@ end
 def tick
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### 1. The MainContainer (Orchestrator)
 
@@ -85,6 +91,11 @@ Components return semantic symbols instead of just `:consumed`:
 
 The `MainContainer` interprets these signals to coordinate cross-component communication:
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```ruby
 result = @input.handle_event(event)
 case result
@@ -93,6 +104,7 @@ when :submitted
   return :consumed
 end
 ```
+<!-- SPDX-SnippetEnd -->
 
 ### ⏱️ Lifecycle Hooks (`tick`)
 
@@ -109,9 +121,15 @@ Read this example if you are trying to solve:
 
 ## Usage
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 ruby examples/app_color_picker/app.rb
 ```
+<!-- SPDX-SnippetEnd -->
 
 -   Type a hex code (e.g., `#FF0055`) or color name (`cyan`).
 -   Press `Enter` to generate the palette.

data/examples/app_color_picker/app.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/clipboard.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/color.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/controls.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/copy_dialog.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/export_pane.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/harmony.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/input.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/main_container.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_color_picker/palette.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_login_form/README.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Login Form Example
@@ -36,9 +36,15 @@ This example solves this by using the `Overlay` widget to stack a centered popup
 
 ## Usage
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 ```bash
 ruby examples/app_login_form/app.rb
 ```
+<!-- SPDX-SnippetEnd -->
 
 ## Learning Outcomes
 

data/examples/app_login_form/app.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/app_stateful_interaction/README.md

@@ -1,6 +1,6 @@
 <!--
-SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-SPDX-License-Identifier: CC-BY-SA-4.0
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
 -->
 
 # Stateful Interaction Example

data/examples/app_stateful_interaction/app.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 
@@ -106,7 +106,7 @@ class AppStatefulInteraction
       render_table(frame, table_area)
 
       # 4. Render Help
-      help_text = "q: Quit | Tab/Arrows: Nav | Mouse: Click rows (Try it!)"
+      help_text = "q: Quit | Tab/Arrows: Nav | Home/End: Jump | Mouse: Click rows"
       frame.render_widget(@tui.paragraph(text: help_text), help_area)
     end
   end
@@ -193,10 +193,16 @@ class AppStatefulInteraction
       @active_pane = (@active_pane == :list) ? :table : :list
 
     in { type: :key, code: "down" }
-      scroll_active(1)
+      move_selection_next
 
     in { type: :key, code: "up" }
-      scroll_active(-1)
+      move_selection_previous
+
+    in { type: :key, code: "home" }
+      move_selection_first
+
+    in { type: :key, code: "end" }
+      move_selection_last
 
     # Mouse Interaction
     in { type: :mouse, kind: "down", x:, y: }
@@ -207,24 +213,72 @@ class AppStatefulInteraction
     end
   end
 
-  private def scroll_active(delta)
+  private def move_selection_next
     if @active_pane == :list
-      i = @list_state.selected || 0
-      new_i = (i + delta).clamp(0, @tables.size - 1)
-      @list_state.select(new_i)
-      # Reset table selection when switching categories
-      if i != new_i
-        @table_state.select(0)
-        @table_state.select_column(nil) # Ensure clean slate
-      end
+      current = @list_state.selected || 0
+      max_index = @tables.size - 1
+      return if current >= max_index # Already at end
+
+      @list_state.select_next
+      reset_table_selection
     else
-      current_rows = @data[@tables[@list_state.selected || 0]].size
-      i = @table_state.selected || 0
-      new_i = (i + delta).clamp(0, current_rows - 1)
-      @table_state.select(new_i)
+      current = @table_state.selected || 0
+      max_index = current_table_rows.size - 1
+      return if current >= max_index
+
+      @table_state.select_next
     end
   end
 
+  private def move_selection_previous
+    if @active_pane == :list
+      current = @list_state.selected || 0
+      return if current <= 0 # Already at start
+
+      @list_state.select_previous
+      reset_table_selection
+    else
+      current = @table_state.selected || 0
+      return if current <= 0
+
+      @table_state.select_previous
+    end
+  end
+
+  private def move_selection_first
+    if @active_pane == :list
+      current = @list_state.selected || 0
+      return if current == 0 # Already at first
+
+      @list_state.select_first
+      reset_table_selection
+    else
+      @table_state.select_first
+    end
+  end
+
+  private def move_selection_last
+    if @active_pane == :list
+      current = @list_state.selected || 0
+      max_index = @tables.size - 1
+      return if current == max_index # Already at last
+
+      @list_state.select(max_index)
+      reset_table_selection
+    else
+      @table_state.select(current_table_rows.size - 1)
+    end
+  end
+
+  private def reset_table_selection
+    @table_state.select(0)
+    @table_state.select_column(nil)
+  end
+
+  private def current_table_rows
+    @data[@tables[@list_state.selected || 0]]
+  end
+
   private def handle_click(x, y)
     if @list_area.contains?(x, y)
       handle_list_click(y)

data/examples/timeout_demo.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
 # SPDX-License-Identifier: AGPL-3.0-or-later
 #++
 

data/examples/verify_quickstart_dsl/README.md

@@ -11,6 +11,11 @@ This example exists as a documentation regression test. It ensures the recommend
 
 ## Usage
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 <!-- SYNC:START:app.rb:main -->
 ```ruby
 # 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
@@ -45,5 +50,6 @@ RatatuiRuby.run do |tui|
 end
 ```
 <!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
 
 [![verify_quickstart_dsl](../../doc/images/verify_quickstart_dsl.png)](../../doc/getting_started/quickstart.md#simplified-api)

data/examples/verify_quickstart_dsl/app.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
 #++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
@@ -23,7 +23,7 @@ class VerifyQuickstartDsl
             title: "My Ruby TUI App",
             title_alignment: :center,
             borders: [:all],
-            border_color: "cyan",
+            border_style: { fg: "cyan" },
             style: { fg: "white" }
           )
         )

data/examples/verify_quickstart_layout/README.md

@@ -11,6 +11,11 @@ This example exists as a documentation regression test. It ensures the layout an
 
 ## Usage
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 <!-- SYNC:START:app.rb:main -->
 ```ruby
 loop do
@@ -67,5 +72,6 @@ loop do
 end
 ```
 <!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
 
 [![verify_quickstart_layout](../../doc/images/verify_quickstart_layout.png)](../../doc/getting_started/quickstart.md#adding-layouts)

data/examples/verify_quickstart_layout/app.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
 #++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
@@ -30,7 +30,7 @@ class VerifyQuickstartLayout
             tui.paragraph(
               text: "Hello, Ratatui!",
               alignment: :center,
-              block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
+              block: tui.block(title: "Content", borders: [:all], border_style: { fg: "cyan" })
             ),
             top
           )

data/examples/verify_quickstart_lifecycle/README.md

@@ -11,6 +11,11 @@ This example exists as a documentation regression test. It ensures the core life
 
 ## Usage
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 <!-- SYNC:START:app.rb:main -->
 ```ruby
 # 1. Initialize the terminal
@@ -58,5 +63,6 @@ ensure
 end
 ```
 <!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
 
 [![verify_quickstart_lifecycle](../../doc/images/verify_quickstart_lifecycle.png)](../../doc/getting_started/quickstart.md#basic-application)

data/examples/verify_quickstart_lifecycle/app.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 #--
-# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: AGPL-3.0-or-later
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
 #++
 
 $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
@@ -27,7 +27,7 @@ class VerifyQuickstartLifecycle
             title: "My Ruby TUI App",
             title_alignment: :center,
             borders: [:all],
-            border_color: "cyan",
+            border_style: { fg: "cyan" },
             style: { fg: "white" }
           )
         )

data/examples/verify_readme_usage/README.md

@@ -11,6 +11,11 @@ This example exists as a documentation regression test. It ensures that the very
 
 ## Usage
 
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
 <!-- SYNC:START:app.rb:main -->
 ```ruby
 RatatuiRuby.run do |tui|
@@ -39,5 +44,6 @@ RatatuiRuby.run do |tui|
 end
 ```
 <!-- SYNC:END -->
+<!-- SPDX-SnippetEnd -->
 
 [![verify_readme_usage](../../doc/images/verify_readme_usage.png)](../../README.md#usage)