ratatui_ruby 0.4.0 → 0.6.0

data/examples/app_stateful_interaction/app.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+require "ratatui_ruby"
+require "faker"
+
+# A "Master Class" example demonstrating Stateful Widget Rendering and Interaction.
+#
+# This example shows how to:
+# 1. Use mutable State objects (ListState, TableState) for selection and scrolling
+# 2. Read back the calculated scroll offset from the backend (state.offset)
+# 3. Implement precise mouse-click-to-row interaction using that offset
+class AppStatefulInteraction
+  def initialize
+    # Data Models
+    # Tables are the categories on the left
+    @tables = ["Users", "Orders", "Products", "Invoices", "Audit Logs"]
+    @headers = {
+      "Users" => ["Name", "Email", "Role"],
+      "Orders" => ["Order ID", "Status", "Amount"],
+      "Products" => ["Product", "SKU", "Status"],
+      "Invoices" => ["Invoice #", "Status", "Amount"],
+      "Audit Logs" => ["Event", "Action", "IP Address"],
+    }
+
+    # Generate dummy data for each table
+    # Use fixed seed for deterministic behavior in CI/Tests
+    if ENV["CI"] == "true" || ENV["RATA_SEED"]
+      seed = (ENV["RATA_SEED"] || 12345).to_i
+      Faker::Config.random = Random.new(seed)
+      # Also seed Kernel.rand/Array#sample just in case
+      srand(seed)
+    end
+    rand_price = -> { "$#{Faker::Commerce.price(range: 10..500.0)}" }
+
+    @data = {
+      "Users" => Array.new(50) { [Faker::Name.name, Faker::Internet.email, %w[Admin Editor Viewer].sample] },
+      "Orders" => Array.new(50) { [Faker::Commerce.promotion_code(digits: 4), ["Completed", "Pending", "Failed"].sample, rand_price.call] },
+      "Products" => Array.new(50) { [Faker::Commerce.product_name, "SKU-#{Faker::Number.number(digits: 4)}", ["In Stock", "Low Stock"].sample] },
+      "Invoices" => Array.new(50) { ["INV-#{Faker::Number.number(digits: 6)}", ["Paid", "Unpaid"].sample, rand_price.call] },
+      "Audit Logs" => Array.new(50) { ["Log #{Faker::Number.unique.number(digits: 3)}", ["Login Success", "Login Failed", "Logout"].sample, Faker::Internet.ip_v4_address] },
+    }
+
+    # State Objects - These are mutable and persist across frames!
+    @list_state = RatatuiRuby::ListState.new(nil)
+    @table_state = RatatuiRuby::TableState.new(nil)
+
+    # Initialize selection
+    @list_state.select(0)
+    @table_state.select(0)
+
+    # Active Pane Focus (:list or :table)
+    @active_pane = :list
+  end
+
+  def run
+    RatatuiRuby.run do |tui|
+      @tui = tui
+
+      # Styles can only be created once TUI is initialized
+      @style_active = @tui.style(fg: :yellow, modifiers: [:bold])
+      @style_inactive = @tui.style(fg: :dark_gray)
+      @style_highlight = @tui.style(bg: :blue, fg: :white, modifiers: [:bold])
+
+      loop do
+        render
+        break if handle_input == :quit
+      end
+    end
+  end
+
+  private def render
+    @tui.draw do |frame|
+      # 1. Layout
+      main_area, help_area = @tui.layout_split(
+        frame.area,
+        direction: :vertical,
+        constraints: [
+          @tui.constraint_fill(1),
+          @tui.constraint_length(1),
+        ]
+      )
+
+      list_area, table_area = @tui.layout_split(
+        main_area,
+        direction: :horizontal,
+        constraints: [
+          @tui.constraint_percentage(30),
+          @tui.constraint_percentage(70),
+        ]
+      )
+
+      # Save areas for hit testing
+      @list_area = list_area
+      @table_area = table_area
+
+      # 2. Render List (Left Pane)
+      render_list(frame, list_area)
+
+      # 3. Render Table (Right Pane)
+      render_table(frame, table_area)
+
+      # 4. Render Help
+      help_text = "q: Quit | Tab/Arrows: Nav | Mouse: Click rows (Try it!)"
+      frame.render_widget(@tui.paragraph(text: help_text), help_area)
+    end
+  end
+
+  private def render_list(frame, area)
+    is_active = @active_pane == :list
+
+    # Render main list
+    list = @tui.list(
+      items: @tables,
+      block: @tui.block(
+        title: " Tables ",
+        borders: [:all],
+        border_style: is_active ? @style_active : @style_inactive
+      ),
+      highlight_style: @style_highlight
+    )
+    # KEY STEP: Pass the state object!
+    frame.render_stateful_widget(list, area, @list_state)
+
+    # Render Scrollbar
+    scrollbar = @tui.scrollbar(
+      content_length: 0,
+      position: 0,
+      orientation: :vertical_right,
+      track_symbol: nil,
+      thumb_symbol: "▐"
+    )
+    scrollbar_state = RatatuiRuby::ScrollbarState.new(@tables.size)
+    scrollbar_state.position = @list_state.offset
+    scrollbar_state.viewport_content_length = area.height - 2
+
+    frame.render_stateful_widget(scrollbar, area, scrollbar_state)
+  end
+
+  private def render_table(frame, area)
+    is_active = @active_pane == :table
+
+    # Get current data based on list selection
+    current_table = @tables[@list_state.selected || 0]
+    rows = @data[current_table]
+
+    # Render table
+    table = @tui.table(
+      rows:,
+      header: @headers[current_table],
+      widths: [
+        @tui.constraint_percentage(30),
+        @tui.constraint_percentage(40),
+        @tui.constraint_percentage(30),
+      ],
+      block: @tui.block(
+        title: " #{current_table} Data ",
+        borders: [:all],
+        border_style: is_active ? @style_active : @style_inactive
+      ),
+      highlight_style: @style_highlight
+    )
+
+    frame.render_stateful_widget(table, area, @table_state)
+
+    # Render Scrollbar
+    scrollbar = @tui.scrollbar(
+      content_length: 0,
+      position: 0,
+      orientation: :vertical_right,
+      track_symbol: nil,
+      thumb_symbol: "▐"
+    )
+    scrollbar_state = RatatuiRuby::ScrollbarState.new(rows.size)
+    scrollbar_state.position = @table_state.offset
+    scrollbar_state.viewport_content_length = area.height - 4 # borders + header + margin
+
+    frame.render_stateful_widget(scrollbar, area, scrollbar_state)
+  end
+
+  private def handle_input
+    case @tui.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      :quit
+
+    # Navigation
+    in { type: :key, code: "tab" } | { type: :key, code: "right" } | { type: :key, code: "left" }
+      @active_pane = (@active_pane == :list) ? :table : :list
+
+    in { type: :key, code: "down" }
+      scroll_active(1)
+
+    in { type: :key, code: "up" }
+      scroll_active(-1)
+
+    # Mouse Interaction
+    in { type: :mouse, kind: "down", x:, y: }
+      handle_click(x, y)
+
+    else
+      # no-op
+    end
+  end
+
+  private def scroll_active(delta)
+    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
+    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)
+    end
+  end
+
+  private def handle_click(x, y)
+    if @list_area.contains?(x, y)
+      handle_list_click(y)
+    elsif @table_area.contains?(x, y)
+      handle_table_click(y)
+    end
+  end
+
+  private def handle_list_click(mouse_y)
+    @active_pane = :list
+
+    # CRITICAL: Read back the offset!
+    # Formula: clicked_index = (mouse_y - list_top - border_width) + offset
+    offset = @list_state.offset
+    list_top = @list_area.y
+    border_width = 1 # Top border
+
+    clicked_row = (mouse_y - list_top - border_width) + offset
+
+    if clicked_row >= 0 && clicked_row < @tables.size
+      @list_state.select(clicked_row)
+      @table_state.select(0) # Reset table when category changes
+    end
+  end
+
+  private def handle_table_click(mouse_y)
+    @active_pane = :table
+
+    # CRITICAL: Read back the offset!
+    # Formula: clicked_index = (mouse_y - table_top - border - header_height - margin) + offset
+    offset = @table_state.offset
+    table_top = @table_area.y
+    border_width = 1
+    header_height = 1
+    # No header_margin without Row margin
+    effective_top = table_top + border_width + header_height
+
+    clicked_row = (mouse_y - effective_top) + offset
+
+    current_table_data = @data[@tables[@list_state.selected || 0]]
+    if clicked_row >= 0 && clicked_row < current_table_data.size
+      @table_state.select(clicked_row)
+    end
+  end
+end
+
+AppStatefulInteraction.new.run if __FILE__ == $PROGRAM_NAME

data/examples/timeout_demo.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# Timeout Demo: Non-Blocking Event Polling
+#
+# This demo shows how to use poll_event with a timeout for game loops
+# and animation systems that need to update at a fixed frame rate
+# regardless of user input.
+#
+# Run: bundle exec ruby examples/timeout_demo.rb
+#
+# Expected behavior:
+# - "Tick..." prints every 100ms continuously
+# - Pressing a key prints "Key Pressed: [key]" immediately
+# - Press 'q' to quit
+
+require "bundler/setup"
+require "ratatui_ruby"
+
+puts "Timeout Demo - Press 'q' to quit"
+puts "Watch: continuous ticks with responsive key handling"
+puts
+
+tick_count = 0
+running = true
+
+while running
+  # Poll with 100ms timeout (~10 FPS tick rate)
+  event = RatatuiRuby.poll_event(timeout: 0.1)
+
+  if event.none?
+    # No input, just tick
+    tick_count += 1
+    puts "Tick #{tick_count}..."
+  elsif event.key?
+    puts "Key Pressed: #{event.code}"
+    running = false if event.code == "q"
+  end
+end
+
+puts "\nGoodbye!"

data/examples/verify_quickstart_dsl/README.md

@@ -0,0 +1,48 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Quickstart DSL Verification
+
+Verifies the "Idiomatic Session" tutorial in the [Quickstart](../../doc/quickstart.md#idiomatic-session).
+
+This example exists as a documentation regression test. It ensures the recommended DSL and session-based workflow remains functional.
+
+## Usage
+
+<!-- SYNC:START:app.rb:main -->
+```ruby
+RatatuiRuby.run do |tui|
+  loop do
+    # 2. Create your UI with methods instead of classes.
+    view = tui.paragraph(
+      text: "Hello, Ratatui! Press 'q' to quit.",
+      alignment: :center,
+      block: tui.block(
+        title: "My Ruby TUI App",
+        title_alignment: :center,
+        borders: [:all],
+        border_color: "cyan",
+        style: { fg: "white" }
+      )
+    )
+
+    # 3. Use RatatuiRuby methods, too.
+    tui.draw do |frame|
+      frame.render_widget(view, frame.area)
+    end
+
+    # 4. Poll for events with pattern matching
+    case tui.poll_event
+    in { type: :key, code: "q" }
+      break
+    else
+      # Ignore other events
+    end
+  end
+end
+```
+<!-- SYNC:END -->
+
+![verify_quickstart_dsl](../../doc/images/verify_quickstart_dsl.png)

data/examples/{quickstart_dsl → verify_quickstart_dsl}/app.rb

@@ -7,9 +7,10 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
 
 require "ratatui_ruby"
 
-class QuickstartDslApp
+class VerifyQuickstartDsl
   def run
     # 1. Initialize the terminal, start the run loop, and ensure the terminal is restored.
+    # [SYNC:START:main]
     RatatuiRuby.run do |tui|
       loop do
         # 2. Create your UI with methods instead of classes.
@@ -18,19 +19,29 @@ class QuickstartDslApp
           alignment: :center,
           block: tui.block(
             title: "My Ruby TUI App",
+            title_alignment: :center,
             borders: [:all],
-            border_color: "cyan"
+            border_color: "cyan",
+            style: { fg: "white" }
           )
         )
 
         # 3. Use RatatuiRuby methods, too.
-        tui.draw(view)
-        event = tui.poll_event
+        tui.draw do |frame|
+          frame.render_widget(view, frame.area)
+        end
 
-        break if event == "q" || event == :ctrl_c
+        # 4. Poll for events with pattern matching
+        case tui.poll_event
+        in { type: :key, code: "q" }
+          break
+        else
+          # Ignore other events
+        end
       end
     end
+    # [SYNC:END:main]
   end
 end
 
-QuickstartDslApp.new.run if __FILE__ == $PROGRAM_NAME
+VerifyQuickstartDsl.new.run if __FILE__ == $PROGRAM_NAME

data/examples/verify_quickstart_layout/README.md

@@ -0,0 +1,71 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Quickstart Layout Verification
+
+Verifies the "Adding Layouts" tutorial in the [Quickstart](../../doc/quickstart.md#adding-layouts).
+
+This example exists as a documentation regression test. It ensures the layout and constraints examples remain functional.
+
+## Usage
+
+<!-- SYNC:START:app.rb:main -->
+```ruby
+loop do
+  tui.draw do |frame|
+    # 1. Split the screen
+    top, bottom = tui.layout_split(
+      frame.area,
+      direction: :vertical,
+      constraints: [
+        tui.constraint_percentage(75),
+        tui.constraint_percentage(25),
+      ]
+    )
+
+    # 2. Render Top Widget
+    frame.render_widget(
+      tui.paragraph(
+        text: "Hello, Ratatui!",
+        alignment: :center,
+        block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
+      ),
+      top
+    )
+
+    # 3. Render Bottom Widget with Styled Text
+    # We use a Line of Spans to style specific characters
+    text_line = tui.text_line(
+      spans: [
+        tui.text_span(content: "Press '"),
+        tui.text_span(
+          content: "q",
+          style: tui.style(modifiers: [:bold, :underlined])
+        ),
+        tui.text_span(content: "' to quit."),
+      ],
+      alignment: :center
+    )
+
+    frame.render_widget(
+      tui.paragraph(
+        text: text_line,
+        block: tui.block(title: "Controls", borders: [:all])
+      ),
+      bottom
+    )
+  end
+
+  case tui.poll_event
+  in { type: :key, code: "q" }
+    break
+  else
+    # Ignore other events
+  end
+end
+```
+<!-- SYNC:END -->
+
+![verify_quickstart_layout](../../doc/images/verify_quickstart_layout.png)

data/examples/verify_quickstart_layout/app.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "ratatui_ruby"
+
+class VerifyQuickstartLayout
+  def run
+    RatatuiRuby.run do |tui|
+      # [SYNC:START:main]
+      loop do
+        tui.draw do |frame|
+          # 1. Split the screen
+          top, bottom = tui.layout_split(
+            frame.area,
+            direction: :vertical,
+            constraints: [
+              tui.constraint_percentage(75),
+              tui.constraint_percentage(25),
+            ]
+          )
+
+          # 2. Render Top Widget
+          frame.render_widget(
+            tui.paragraph(
+              text: "Hello, Ratatui!",
+              alignment: :center,
+              block: tui.block(title: "Content", borders: [:all], border_color: "cyan")
+            ),
+            top
+          )
+
+          # 3. Render Bottom Widget with Styled Text
+          # We use a Line of Spans to style specific characters
+          text_line = tui.text_line(
+            spans: [
+              tui.text_span(content: "Press '"),
+              tui.text_span(
+                content: "q",
+                style: tui.style(modifiers: [:bold, :underlined])
+              ),
+              tui.text_span(content: "' to quit."),
+            ],
+            alignment: :center
+          )
+
+          frame.render_widget(
+            tui.paragraph(
+              text: text_line,
+              block: tui.block(title: "Controls", borders: [:all])
+            ),
+            bottom
+          )
+        end
+
+        case tui.poll_event
+        in { type: :key, code: "q" }
+          break
+        else
+          # Ignore other events
+        end
+      end
+      # [SYNC:END:main]
+    end
+  end
+end
+
+VerifyQuickstartLayout.new.run if __FILE__ == $PROGRAM_NAME

data/examples/verify_quickstart_lifecycle/README.md

@@ -0,0 +1,56 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Quickstart Lifecycle Verification
+
+Verifies the "Basic Application" tutorial in the [Quickstart](../../doc/quickstart.md#basic-application).
+
+This example exists as a documentation regression test. It ensures the core lifecycle example presented to new users remains functional.
+
+## Usage
+
+<!-- SYNC:START:app.rb:main -->
+```ruby
+# 1. Initialize the terminal
+RatatuiRuby.init_terminal
+
+begin
+  # The Main Loop
+  loop do
+    # 2. Create your UI (Immediate Mode)
+    # We define a Paragraph widget inside a Block with a title and borders.
+    view = RatatuiRuby::Paragraph.new(
+      text: "Hello, Ratatui! Press 'q' to quit.",
+      alignment: :center,
+      block: RatatuiRuby::Block.new(
+        title: "My Ruby TUI App",
+        title_alignment: :center,
+        borders: [:all],
+        border_color: "cyan",
+        style: { fg: "white" }
+      )
+    )
+
+    # 3. Draw the UI
+    RatatuiRuby.draw do |frame|
+      frame.render_widget(view, frame.area)
+    end
+
+    # 4. Poll for events
+    case RatatuiRuby.poll_event
+    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+      break
+    else
+      nil
+    end
+  end
+ensure
+  # 5. Restore the terminal to its original state
+  RatatuiRuby.restore_terminal
+end
+```
+<!-- SYNC:END -->
+
+![verify_quickstart_lifecycle](../../doc/images/verify_quickstart_lifecycle.png)

data/examples/verify_quickstart_lifecycle/app.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "ratatui_ruby"
+
+class VerifyQuickstartLifecycle
+  def run
+    # [SYNC:START:main]
+    # 1. Initialize the terminal
+    RatatuiRuby.init_terminal
+
+    begin
+      # The Main Loop
+      loop do
+        # 2. Create your UI (Immediate Mode)
+        # We define a Paragraph widget inside a Block with a title and borders.
+        view = RatatuiRuby::Paragraph.new(
+          text: "Hello, Ratatui! Press 'q' to quit.",
+          alignment: :center,
+          block: RatatuiRuby::Block.new(
+            title: "My Ruby TUI App",
+            title_alignment: :center,
+            borders: [:all],
+            border_color: "cyan",
+            style: { fg: "white" }
+          )
+        )
+
+        # 3. Draw the UI
+        RatatuiRuby.draw do |frame|
+          frame.render_widget(view, frame.area)
+        end
+
+        # 4. Poll for events
+        case RatatuiRuby.poll_event
+        in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
+          break
+        else
+          nil
+        end
+      end
+    ensure
+      # 5. Restore the terminal to its original state
+      RatatuiRuby.restore_terminal
+    end
+    # [SYNC:END:main]
+  end
+end
+
+VerifyQuickstartLifecycle.new.run if __FILE__ == $PROGRAM_NAME