ratatui_ruby 0.9.1 → 0.10.1

data/examples/app_debugging_showcase/app.rb

@@ -0,0 +1,318 @@
+# 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/widget_canvas/app.rb

@@ -37,24 +37,26 @@ class WidgetCanvas
 
   private def render
     @tui.draw do |frame|
-      # Define shapes
+      # Define shapes using terse aliases (circle, rectangle, point, map, label)
+      # These are shorter forms of shape_circle, shape_rectangle, etc.
       shapes = []
 
-      # 1. Static Grid (Lines)
+      # 1. Static Grid (Lines) - using shape_line (no terse alias for line)
       (-100..100).step(20) do |i|
         shapes << @tui.shape_line(x1: i.to_f, y1: -100.0, x2: i.to_f, y2: 100.0, color: :gray)
         shapes << @tui.shape_line(x1: -100.0, y1: i.to_f, x2: 100.0, y2: i.to_f, color: :gray)
       end
 
-      # 2. Moving Circle (The "Player")
-      shapes << @tui.shape_circle(
+      # 2. Moving Circle (The "Player") - using terse 'circle' alias
+      shapes << @tui.circle(
         x: @x_offset,
         y: @y_offset,
         radius: 10.0,
         color: :green
       )
 
-      # 3. Static Rectangle (Target)
+      # 3. Static Rectangle (Target) - using shape_rectangle (no 'rectangle' alias
+      #    to avoid confusion with Layout::Rect)
       shapes << @tui.shape_rectangle(
         x: 30.0,
         y: 30.0,
@@ -63,16 +65,16 @@ class WidgetCanvas
         color: :red
       )
 
-      # 4. Points (Starfield)
+      # 4. Points (Starfield) - using terse 'point' alias
       # Deterministic "random" points
       10.times do |i|
-        shapes << @tui.shape_point(
+        shapes << @tui.point(
           x: ((i * 37) % 200) - 100.0,
           y: ((i * 19) % 200) - 100.0
         )
       end
 
-      # 5. Label
+      # 5. Connecting line from origin to player position
       shapes << @tui.shape_line(x1: 0.0, y1: 0.0, x2: @x_offset, y2: @y_offset, color: :yellow)
 
       canvas = @tui.canvas(
@@ -89,21 +91,24 @@ class WidgetCanvas
         direction: :vertical,
         constraints: [
           @tui.constraint_fill(1),
-          @tui.constraint_length(3),
+          @tui.constraint_length(2),
         ]
       )
 
       frame.render_widget(canvas, layout[0])
 
-      # Controls
+      # Query: Canvas#get_point maps canvas coordinates to normalized [0.0, 1.0] grid
+      normalized = canvas.get_point(@x_offset, @y_offset)
+      norm_str = normalized ? format("[%.2f, %.2f]", normalized[0], normalized[1]) : "nil"
+
+      # Controls showing query method demonstration (single concise line)
       controls = @tui.paragraph(
         text: [
-          @tui.text_line(spans: [
-            @tui.text_span(content: "Canvas auto-animates.", style: @tui.style(fg: :yellow)),
-          ]),
           @tui.text_line(spans: [
             @tui.text_span(content: "q", style: @tui.style(modifiers: [:bold, :underlined])),
-            @tui.text_span(content: ": Quit"),
+            @tui.text_span(content: ": Quit  "),
+            @tui.text_span(content: "get_point → ", style: @tui.style(fg: :dark_gray)),
+            @tui.text_span(content: norm_str, style: @tui.style(fg: :cyan)),
           ]),
         ],
         block: @tui.block(borders: [:top])

data/examples/widget_gauge/app.rb

@@ -29,6 +29,10 @@ class WidgetGauge
     @ratios = [0.0, 0.25, 0.5, 0.65, 0.8, 0.95, 1.0]
     @ratio_index = 3
 
+    # Demonstrates both ratio (0.0-1.0) and percent (0-100) input modes
+    @input_modes = [:ratio, :percent]
+    @input_mode_index = 0
+
     @gauge_colors = [
       { name: "Green", color: :green },
       { name: "Yellow", color: :yellow },
@@ -116,13 +120,20 @@ class WidgetGauge
       frame.render_widget(title, title_area)
 
       # Gauge 1: Main interactive gauge
+      # Demonstrates both ratio (0.0-1.0) and percent (0-100) input modes
+      input_mode = @input_modes[@input_mode_index]
+      gauge_opts = if input_mode == :percent
+        { percent: (@ratio * 100).to_i } # percent: accepts 0-100
+      else
+        { ratio: @ratio } # ratio: accepts 0.0-1.0
+      end
       gauge1 = @tui.gauge(
-        ratio: @ratio,
+        **gauge_opts,
         label:,
         style: bg_style,
         gauge_style:,
         use_unicode:,
-        block: @tui.block(title: "Interactive Gauge")
+        block: @tui.block(title: "Interactive Gauge (#{input_mode}:)")
       )
       frame.render_widget(gauge1, gauge1_area)
 
@@ -178,7 +189,9 @@ class WidgetGauge
                 @tui.text_span(content: "u", style: @hotkey_style),
                 @tui.text_span(content: ": Unicode (#{use_unicode ? 'On' : 'Off'})  "),
                 @tui.text_span(content: "l", style: @hotkey_style),
-                @tui.text_span(content: ": Label (#{@label_modes[@label_mode_index][:name]})"),
+                @tui.text_span(content: ": Label (#{@label_modes[@label_mode_index][:name]})  "),
+                @tui.text_span(content: "i", style: @hotkey_style),
+                @tui.text_span(content: ": Input (#{@input_modes[@input_mode_index]}:)"),
               ]),
             ]
           ),
@@ -204,6 +217,8 @@ class WidgetGauge
       @use_unicode_index = (@use_unicode_index + 1) % @use_unicode_options.length
     in type: :key, code: "l"
       @label_mode_index = (@label_mode_index + 1) % @label_modes.length
+    in type: :key, code: "i"
+      @input_mode_index = (@input_mode_index + 1) % @input_modes.length
     else
       # Ignore other events
       nil

data/examples/widget_layout_split/app.rb

@@ -206,6 +206,11 @@ class WidgetLayoutSplit
   end
 
   private def render_controls(frame, area)
+    # Demonstrate Constraint#call - show computed sizes for 100 units
+    constraints = current_constraints
+    applied = constraints.map { |c| c.(100) } # proc-like invocation
+    apply_str = "constraint.(100): #{applied.join(', ')}"
+
     controls = @tui.block(
       title: "Controls",
       borders: [:all],
@@ -221,13 +226,14 @@ class WidgetLayoutSplit
             ]),
             @tui.text_line(spans: [
               @tui.text_span(content: "c", style: @hotkey_style),
-              @tui.text_span(content: ": Constraints (#{current_constraint_name})"),
-            ]),
-            # Row 3: Quit
-            @tui.text_line(spans: [
+              @tui.text_span(content: ": Constraints (#{current_constraint_name})  "),
               @tui.text_span(content: "q", style: @hotkey_style),
               @tui.text_span(content: ": Quit"),
             ]),
+            # Row 3: Apply demonstration
+            @tui.text_line(spans: [
+              @tui.text_span(content: apply_str, style: @tui.style(fg: :dark_gray)),
+            ]),
           ]
         ),
       ]

data/examples/widget_list/app.rb

@@ -230,8 +230,6 @@ class WidgetList
     # Determine selection/offset based on mode
     effective_selection = offset_mode_config[:allow_selection] ? @selected_index : nil
     effective_offset = offset_mode_config[:offset]
-    selection_label = effective_selection.nil? ? "none" : effective_selection.to_s
-    offset_label = effective_offset.nil? ? "auto" : effective_offset.to_s
 
     @tui.draw do |frame|
       # Split into main content and control panel
@@ -258,8 +256,11 @@ class WidgetList
       title = @tui.paragraph(text: "List Widget - Interactive Attribute Cycling")
       frame.render_widget(title, title_area)
 
-      # Render list
-      list = @tui.list(
+      # Build list first to demonstrate query methods:
+      # - List#len (with #length, #size aliases)
+      # - List#selection (alias for #selected_index)
+      # - List#selected_item (returns item at selection, or nil)
+      base_list = @tui.list(
         items:,
         selected_index: effective_selection,
         offset: effective_offset,
@@ -269,9 +270,24 @@ class WidgetList
         repeat_highlight_symbol: repeat_config[:repeat],
         highlight_spacing: spacing_config[:spacing],
         direction: direction_config[:direction],
-        scroll_padding: scroll_padding_config[:padding],
+        scroll_padding: scroll_padding_config[:padding]
+      )
+
+      # Demonstrate query methods: len, selected_index, selected_item
+      item_count = base_list.len
+      current_index = base_list.selected_index  # Explicit name - returns index
+      current_item = base_list.selected_item    # Explicit name - returns item
+
+      # Format the selected item for display (handle rich text objects)
+      item_preview = case current_item
+      when nil then "none"
+      when String then (current_item.length > 12) ? "#{current_item[0..11]}…" : current_item
+      else current_item.class.name.split("::").last # Show type for rich text
+      end
+
+      list = base_list.with(
         block: @tui.block(
-          title: "#{@item_sets[@item_set_index][:name]} | Sel: #{selection_label} | Offset: #{offset_label}",
+          title: "#{@item_sets[@item_set_index][:name]} (len: #{item_count}) | index: #{current_index.inspect} → #{item_preview}",
           borders: [:all]
         )
       )

data/examples/widget_rect/app.rb

@@ -97,6 +97,10 @@ class WidgetRect
     clamped = r.clamp(bounds)
     union_r = r.union(@sidebar_rect)
 
+    # Extract position and size from rect
+    pos = r.position # => Position(x:, y:)
+    size = r.size    # => Size(width:, height:)
+
     text_content = [
       @tui.text_line(spans: [
         @tui.text_span(content: "Active View: ", style: @label_style),
@@ -112,19 +116,16 @@ class WidgetRect
       ]),
       "  left:#{r.left} right:#{r.right} top:#{r.top} bottom:#{r.bottom}",
       @tui.text_line(spans: [
-        @tui.text_span(content: "Size Methods:", style: @label_style),
+        @tui.text_span(content: "Conversion Methods ", style: @label_style),
+        @tui.text_span(content: "(as_position/as_size):", style: @dim_style),
       ]),
-      "  area:#{r.area} empty?:#{r.empty?}",
+      "  Position: x=#{pos.x} y=#{pos.y}  Size: #{size.width}x#{size.height}",
       @tui.text_line(spans: [
         @tui.text_span(content: "Geometry Transformations:", style: @label_style),
       ]),
       "  inner(2): x:#{inner_r.x} y:#{inner_r.y} w:#{inner_r.width} h:#{inner_r.height}",
       "  offset(3,2): x:#{offset_r.x} y:#{offset_r.y}  clamp: x:#{clamped.x} y:#{clamped.y}",
       "  union(sidebar): w:#{union_r.width} h:#{union_r.height}",
-      @tui.text_line(spans: [
-        @tui.text_span(content: "Iterators:", style: @label_style),
-      ]),
-      "  rows:#{r.height} columns:#{r.width} positions:#{r.area}",
       @tui.text_line(spans: [
         @tui.text_span(content: "Hit Testing ", style: @label_style),
         @tui.text_span(content: "(Rect#contains?):", style: @dim_style),