ratatui_ruby 1.0.0 → 1.0.1

data/examples/app_debugging_showcase/app.rb

@@ -1,318 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-# SPDX-License-Identifier: MIT-0
-#++
-
-$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
-
-require "ratatui_ruby"
-
-##
-# Interactive demonstration of RatatuiRuby debugging features.
-#
-# This example lets you trigger each debugging feature with a hotkey to verify
-# your setup works before encountering a real bug.
-#
-# == Hotkeys
-#
-# [d] Enable debug_mode! — Shows the debug socket path for remote attachment
-# [p] Trigger test_panic! — Deliberately crashes to verify Rust backtrace visibility
-# [t] Cause TypeError — Passes wrong type to widget factory to show Rust stack frames
-# [b] Show backtrace status — Displays current debug configuration
-# [q] Quit
-#
-# == Usage
-#
-#   # Normal mode (no backtraces):
-#   ruby examples/verify_debugging_usage/app.rb
-#
-#   # With Rust backtraces only:
-#   RUST_BACKTRACE=1 ruby examples/verify_debugging_usage/app.rb
-#
-#   # Full debug mode (stops at startup for debugger attachment):
-#   RR_DEBUG=1 ruby examples/verify_debugging_usage/app.rb
-#
-# == Remote Debugging
-#
-# When you press [d] to enable debug_mode!, the app continues running but
-# prints a socket path. From another terminal:
-#
-#   rdbg --attach
-#
-# This gives you a full debugger REPL while the TUI keeps running.
-class VerifyDebuggingUsage
-  def initialize
-    @status_message = "Press a key to test debugging features"
-    @show_debug_info = false
-    @quit = false
-
-    # If debug mode was enabled via RR_DEBUG=1 at startup, capture the socket path
-    if RatatuiRuby::Debug.enabled?
-      @socket_path = begin
-        ::DEBUGGER__.create_unix_domain_socket_name
-      rescue NameError
-        nil
-      end
-      @show_debug_info = true
-      @status_message = "RR_DEBUG=1 detected — debug mode active"
-    end
-  end
-
-  def run
-    RatatuiRuby.run do |tui|
-      @tui = tui
-      @loop_count = 0
-
-      loop do
-        @loop_count += 1
-
-        # 🎯 Breakpoint every 250 loops. Try: p @status_message
-        if RatatuiRuby::Debug.enabled? && (@loop_count % 250).zero?
-          you_found_me = "🎉 You found me! Loop ##{@loop_count}"
-          # rubocop:disable Lint/Debugger
-          debugger
-          # rubocop:enable Lint/Debugger
-          _ = you_found_me # Suppress unused variable warning
-        end
-
-        render
-        break if @quit || handle_input == :quit
-      end
-    end
-  end
-
-  private def render
-    @tui.draw do |frame|
-      constraints = [
-        @tui.constraint_length(3),  # Status
-        @tui.constraint_length(5),  # Config
-        @tui.constraint_length(6),  # Actions
-      ]
-
-      if @show_debug_info
-        constraints << @tui.constraint_length(6) # Debug info
-      end
-
-      constraints << @tui.constraint_fill(1)    # Spacer
-      constraints << @tui.constraint_length(3)  # Help
-
-      chunks = @tui.layout_split(frame.area, direction: :vertical, constraints:)
-
-      idx = 0
-      render_status(frame, chunks[idx])
-      idx += 1
-      render_config(frame, chunks[idx])
-      idx += 1
-      render_actions(frame, chunks[idx])
-      idx += 1
-
-      if @show_debug_info
-        render_debug_info(frame, chunks[idx])
-        idx += 1
-      end
-
-      # Skip spacer
-      idx += 1
-      render_help(frame, chunks[idx])
-    end
-  end
-
-  private def render_status(frame, area)
-    frame.render_widget(
-      @tui.paragraph(
-        text: @status_message,
-        alignment: :center,
-        block: @tui.block(
-          title: " Status ",
-          title_alignment: :center,
-          borders: [:all],
-          border_style: { fg: :yellow }
-        )
-      ),
-      area
-    )
-  end
-
-  private def render_config(frame, area)
-    config_lines = [
-      "Rust Backtraces:  #{flag(RatatuiRuby::Debug.rust_backtrace_enabled?)}",
-      "Full Debug Mode:  #{flag(RatatuiRuby::Debug.enabled?)}",
-      "Remote Debugging: #{remote_mode_description}",
-    ].join("\n")
-
-    frame.render_widget(
-      @tui.paragraph(
-        text: config_lines,
-        block: @tui.block(
-          title: " Current Debug Configuration ",
-          borders: [:all],
-          border_style: { fg: :cyan }
-        )
-      ),
-      area
-    )
-  end
-
-  private def render_actions(frame, area)
-    actions_lines = [
-      "[d] Enable debug_mode! and show socket info",
-      "[p] Trigger test_panic! to verify backtrace visibility",
-      "[t] Cause TypeError (pass wrong type to widget)",
-      "[b] Refresh debug status",
-    ].join("\n")
-
-    frame.render_widget(
-      @tui.paragraph(
-        text: actions_lines,
-        block: @tui.block(
-          title: " Available Actions ",
-          borders: [:all],
-          border_style: { fg: :green }
-        )
-      ),
-      area
-    )
-  end
-
-  private def render_debug_info(frame, area)
-    socket_display = @socket_path || "(socket not available)"
-    info_lines = [
-      "Socket: #{socket_display}",
-      "Attach: rdbg --attach",
-      "Hint: type 'continue' if you see SIGURG",
-    ]
-
-    frame.render_widget(
-      @tui.paragraph(
-        text: info_lines.join("\n"),
-        block: @tui.block(
-          title: " Remote Debugging ",
-          borders: [:all],
-          border_style: { fg: :magenta }
-        )
-      ),
-      area
-    )
-  end
-
-  private def render_help(frame, area)
-    frame.render_widget(
-      @tui.paragraph(
-        text: "[d] debug_mode!  [p] test_panic!  [t] TypeError  [b] status  [q] quit",
-        alignment: :center,
-        block: @tui.block(
-          borders: [:all],
-          border_style: { fg: :dark_gray }
-        )
-      ),
-      area
-    )
-  end
-
-  private def flag(value)
-    value ? "✓ enabled" : "✗ disabled"
-  end
-
-  private def remote_mode_description
-    case RatatuiRuby::Debug.remote_debugging_mode
-    when :open
-      attached = debugger_attached? ? " — ATTACHED" : " — waiting"
-      "✓ open#{attached}"
-    when :open_nonstop
-      attached = debugger_attached? ? " — ATTACHED" : ""
-      "✓ open_nonstop#{attached}"
-    else
-      "✗ not configured"
-    end
-  end
-
-  # ☣️  FRAGILE: This pokes at debug gem internals.
-  #
-  # Private instance variables can change between gem versions. This code
-  # may silently break. We accept that risk here because this showcase
-  # exists specifically to demonstrate debugger attachment status.
-  #
-  # For production apps, checking Debug.enabled? is sufficient — knowing
-  # whether a client has attached rarely matters.
-  private def debugger_attached?
-    return false unless defined?(::DEBUGGER__::SESSION)
-
-    ui = ::DEBUGGER__::SESSION.instance_variable_get(:@ui)
-    return false unless ui
-
-    # The @sock instance variable is set when a client connects
-    sock = ui.instance_variable_get(:@sock)
-    !sock.nil?
-  rescue
-    false
-  end
-
-  private def handle_input
-    case @tui.poll_event
-    in { type: :key, code: "q" } | { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-
-    in { type: :key, code: "d" }
-      enable_debug_mode!
-
-    in { type: :key, code: "p" }
-      trigger_test_panic!
-
-    in { type: :key, code: "t" }
-      trigger_type_error!
-
-    in { type: :key, code: "b" }
-      @status_message = "Debug status refreshed at #{Time.now.strftime('%H:%M:%S')}"
-
-    else
-      nil
-    end
-  end
-
-  private def enable_debug_mode!
-    if RatatuiRuby::Debug.enabled?
-      @status_message = "Debug mode already enabled!"
-    else
-      # debug_mode! returns the socket path and suppresses the debug gem's output
-      @socket_path = RatatuiRuby.debug_mode!
-      @status_message = "debug_mode! enabled"
-      @show_debug_info = true
-    end
-  end
-
-  private def trigger_test_panic!
-    if RatatuiRuby::Debug.rust_backtrace_enabled?
-      @status_message = "Triggering test_panic! — check stderr for backtrace..."
-    else
-      @status_message = "Triggering test_panic! — backtrace hidden (set RUST_BACKTRACE=1)"
-    end
-    render # Show the message before crashing
-
-    # Give a moment for the render to complete
-    sleep 0.1
-
-    # This will crash the app with a Rust panic. If RUST_BACKTRACE=1 or
-    # debug mode is enabled, you'll see the full Rust stack trace after
-    # the terminal is restored.
-    RatatuiRuby::Debug.test_panic!
-  end
-
-  private def trigger_type_error!
-    if RatatuiRuby::Debug.rust_backtrace_enabled?
-      @status_message = "Triggering TypeError — check stderr for error message..."
-    else
-      @status_message = "Triggering TypeError — set RUST_BACKTRACE=1 for stack trace"
-    end
-    render # Show the message before crashing
-    sleep 0.1
-
-    # Bypass the factory's DWIM coercion to trigger a real Rust TypeError.
-    # Uses Widgets::Table.new directly with invalid rows type.
-    bad_table = RatatuiRuby::Widgets::Table.new(rows: 42, widths: [])
-    @tui.draw { |f| f.render_widget(bad_table, f.area) }
-  end
-end
-
-VerifyDebuggingUsage.new.run if __FILE__ == $PROGRAM_NAME

data/examples/app_login_form/README.md

@@ -1,58 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Login Form Example
-
-[![Login Form](../../doc/images/app_login_form.png)](app.rb)
-
-Demonstrates how to create a modal overlay for user input.
-
-Many applications need to block interaction with the main UI while collecting specific information, like a login prompt or confirmation dialog. Managing the z-index and input focus for these overlays can be tricky.
-
-This example solves this by using the `Overlay` widget to stack a centered popup on top of a base layer, conditionally rendering the popup based on state.
-
-## Features Demonstrated
-
-- **Overlays:** Stacking widgets on top of each other using `tui.overlay`.
-- **Centering:** Positioning a widget in the center of the screen using `tui.center`.
-- **State Management:** Switching between "Base" and "Popup" views.
-- **Input Handling:** Capturing text input and handling specific keys (Enter, Esc) to trigger state changes.
-- **Cursor Positioning:** Manually calculating cursor position within a `Paragraph`.
-
-## Hotkeys
-
-### Form Mode
-- **Text Input**: Type to enter username (supports all characters including 'q').
-- **Backspace**: Deletes the last character.
-- **Enter**: Submits the form and opens the success popup.
-- **Esc**: Quits the application.
-- **Ctrl+C**: Quits the application.
-
-### Popup Mode
-- **q**: Closes the popup and quits the application.
-- **Ctrl+C**: Quits the application.
-
-## 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
-
-Use this example if you need to...
-
-- Create a modal dialog or popup.
-- Center a widget on the screen (vertically and horizontally).
-- Implement a simple text input field with cursor management.
-- layer widgets using the `Overlay` widget.
-
-[Read the source code →](app.rb)

data/examples/app_login_form/app.rb

@@ -1,109 +0,0 @@
-# frozen_string_literal: true
-
-#--
-# SPDX-FileCopyrightText: 2026 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 AppLoginForm
-  PREFIX = "Enter Username: [ "
-  SUFFIX = " ]"
-
-  def initialize
-    @username = ""
-    @show_popup = false
-  end
-
-  def run
-    RatatuiRuby.run do |tui|
-      @tui = tui
-      loop do
-        render
-        break if handle_input == :quit
-      end
-    end
-  end
-
-  private def render
-    # 1. Base Layer Construction
-    # We want a cursor relative to the paragraph.
-    # So we wrap Paragraph and Cursor in an Overlay, and put that Overlay in a Center.
-
-    # Calculate cursor position
-    # Border takes 1 cell.
-    # Cursor X = 1 (border) + PREFIX.length + username.length
-    # Cursor Y = 1 (border + line 0)
-    cursor_x = 1 + PREFIX.length + @username.length
-    cursor_y = 1
-
-    # The content of the base form
-    form_content = @tui.overlay(layers: [
-      @tui.paragraph(
-        text: "#{PREFIX}#{@username}#{SUFFIX}",
-        block: @tui.block(borders: :all, title: "Login Form"),
-        alignment: :left
-      ),
-      @tui.cursor(x: cursor_x, y: cursor_y),
-    ])
-
-    # Center the form on screen
-    base_layer = @tui.center(
-      child: form_content,
-      width_percent: 50,
-      height_percent: 20
-    )
-
-    # 2. Popup Layer Construction
-    final_view = if @show_popup
-      popup_message = @tui.center(
-        child: @tui.paragraph(
-          text: "Login Successful!\nPress 'q' to quit.",
-          style: @tui.style(fg: :green, bg: :black),
-          block: @tui.block(borders: :all),
-          alignment: :center,
-          wrap: true
-        ),
-        width_percent: 30,
-        height_percent: 20
-      )
-
-      # Render Base Layer (background) THEN Popup Layer
-      @tui.overlay(layers: [base_layer, popup_message])
-    else
-      base_layer
-    end
-
-    # 3. Draw
-    @tui.draw do |frame|
-      frame.render_widget(final_view, frame.area)
-    end
-  end
-
-  private def handle_input
-    case @tui.poll_event
-    in { type: :key, code: "c", modifiers: ["ctrl"] }
-      :quit
-    in { type: :key, code: "q" } if @show_popup
-      :quit
-    in { type: :key, code: "enter" }
-      @show_popup ||= true
-      nil
-    in { type: :key, code: "backspace" }
-      @username.chop! unless @show_popup
-      nil
-    in { type: :key, code: "esc" }
-      :quit unless @show_popup
-    in { type: :key, code:, modifiers: [] }
-      # Simple text input (single character, no modifiers)
-      @username += code if !@show_popup && code.length == 1
-      nil
-    else
-      nil
-    end
-  end
-end
-
-AppLoginForm.new.run if __FILE__ == $0

data/examples/app_stateful_interaction/README.md

@@ -1,35 +0,0 @@
-<!--
-  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-  SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# Stateful Interaction Example
-
-[![Stateful Interaction](../../doc/images/app_stateful_interaction.png)](app.rb)
-
-This example demonstrates High-Fidelity Interaction using **Stateful Widget Rendering**.
-
-It showcases a "Database Viewer" layout where:
-1.  **Selection Persistence:** `ListState` and `TableState` objects persist across frames, maintaining selection without manual index tracking variables.
-2.  **Offset Read-back:** The application reads `state.offset` *after* rendering to know exactly which items were visible on screen.
-3.  **Mouse Interaction:** Using the read-back offset, we can calculate exactly which row was clicked, even when the specific item wasn't drawn at that absolute Y position due to scrolling.
-
-## Key Concept: The "Read-back" Loop
-
-Standard immediate-mode interaction often requires you to re-calculate layout logic to determine what was clicked.
-
-In `ratatui_ruby`'s Stateful Rendering:
-1.  **Update**: You modify `state` (e.g., `state.select(1)`).
-2.  **Render**: You pass `state` to `render_stateful_widget`. Ratatui's Rust backend calculates layout and **updates** `state.offset` in-place if scrolling happened.
-3.  **Interact**: On the next event loop, you use `state.offset` to correctly map mouse coordinates to data indices.
-
-## Hotkeys
-
-| Key | Action |
-| --- | --- |
-| `↑` / `↓` | Scroll the active pane |
-| `Tab` / `←` / `→` | Switch active pane (List vs Table) |
-| `Mouse Click` | Select the clicked row (Works with scrolling!) |
-| `q` | Quit |
-
-[Read the source code →](app.rb)