ratatui_ruby 1.4.0-x86_64-linux

data/lib/ratatui_ruby/event/sync.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Event
+    # Synthetic event for synchronizing async operations in tests.
+    #
+    # Testing async behavior is tricky. You inject an event, but results arrive
+    # later. By the time you assert, the async work may not have completed.
+    #
+    # When a runtime (Tea, Kit) encounters this event, it should wait for all
+    # pending async operations to complete before processing the next event.
+    # This enables deterministic testing without changing production code paths.
+    #
+    # Inject this event between user actions and assertions to ensure async
+    # results have been processed:
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   inject_key("s")           # Triggers async command
+    #   inject_sync               # Wait for command to complete
+    #   inject_key(:q)            # Quit after seeing results
+    #   Tea.run(...)
+    #   assert_snapshots("after_s_with_results")
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # This is not "test mode"—it's a real event that runtimes handle.
+    # Production apps could use it too (e.g., "ensure saves complete before quit").
+    class Sync < Event
+      # Returns true for Sync events.
+      def sync?
+        true
+      end
+
+      # Deconstructs the event for pattern matching.
+      def deconstruct_keys(keys)
+        { type: :sync }
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Base class for all RatatuiRuby events.
+  #
+  # Events represent terminal input: keyboard, mouse, resize, paste, focus changes.
+  # Returned by RatatuiRuby.poll_event. All events support Ruby 3.0+ pattern matching.
+  #
+  # == Event Types
+  #
+  # * <tt>Key</tt> — keyboard input
+  # * <tt>Mouse</tt> — mouse clicks, movement, wheel
+  # * <tt>Resize</tt> — terminal resized
+  # * <tt>Paste</tt> — clipboard paste
+  # * <tt>FocusGained</tt> — terminal gained focus
+  # * <tt>FocusLost</tt> — terminal lost focus
+  # * <tt>None</tt> — no event available (Null Object)
+  #
+  # == Pattern Matching (Exhaustive)
+  #
+  # Use <tt>case...in</tt> to dispatch on every possible event type. This ensures
+  # you handle every case without needing an +else+ clause:
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   case RatatuiRuby.poll_event
+  #   in { type: :key, code: "q" }
+  #     break
+  #   in { type: :key, code: code, modifiers: }
+  #     handle_key(code, modifiers)
+  #   in { type: :mouse, kind: "down", x:, y: }
+  #     handle_click(x, y)
+  #   in { type: :mouse, kind:, x:, y: }
+  #     # handle other mouse activities
+  #   in { type: :resize, width:, height: }
+  #     handle_resize(width, height)
+  #   in { type: :paste, content: }
+  #     handle_paste(content)
+  #   in { type: :focus_gained }
+  #     handle_focus_gain
+  #   in { type: :focus_lost }
+  #     handle_focus_loss
+  #   in { type: :none }
+  #     # Idle
+  #   end
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  # == Predicates
+  #
+  # Check event types with predicates without pattern matching:
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2025 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   event = RatatuiRuby.poll_event
+  #   if event.key?
+  #     puts "Key pressed"
+  #   elsif event.none?
+  #     # Idle
+  #   elsif event.mouse?
+  #     puts "Mouse event"
+  #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
+  class Event
+    # Returns true if this is a None event.
+    def none?
+      false
+    end
+
+    # Returns true if this is a Key event.
+    def key?
+      false
+    end
+
+    # Returns true if this is a Mouse event.
+    def mouse?
+      false
+    end
+
+    # Returns true if this is a Resize event.
+    def resize?
+      false
+    end
+
+    # Returns true if this is a Paste event.
+    def paste?
+      false
+    end
+
+    # Returns true if this is a FocusGained event.
+    def focus_gained?
+      false
+    end
+
+    # Returns true if this is a FocusLost event.
+    def focus_lost?
+      false
+    end
+
+    # Returns true if this is a Sync event.
+    def sync?
+      false
+    end
+
+    # Responds to dynamic predicate methods for key checks.
+    # All non-Key events return false for any key predicate.
+    def method_missing(name, *args, **kwargs, &block)
+      if name.to_s.end_with?("?")
+        false
+      else
+        super
+      end
+    end
+
+    # Declares that this class responds to dynamic predicate methods.
+    def respond_to_missing?(name, *args)
+      name.to_s.end_with?("?") || super
+    end
+
+    # Deconstructs the event for pattern matching.
+    #
+    # Keys argument is unused but required by the protocol.
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   case event
+    #   in type: :key, code:
+    #     puts "Key: #{code}"
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def deconstruct_keys(keys)
+      {}
+    end
+  end
+end
+
+require_relative "event/none"
+require_relative "event/key"
+require_relative "event/mouse"
+require_relative "event/resize"
+require_relative "event/paste"
+require_relative "event/focus_gained"
+require_relative "event/focus_lost"
+require_relative "event/sync"

data/lib/ratatui_ruby/frame.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Provides access to the terminal buffer for rendering widgets.
+  #
+  # Rendering in immediate-mode TUIs requires knowing the terminal dimensions and
+  # placing widgets at specific positions. Without explicit control, layout
+  # calculations become duplicated between rendering and hit testing.
+  #
+  # This class exposes the terminal frame during a draw call. It provides the
+  # current area and methods to render widgets at precise locations.
+  #
+  # Use it inside a <tt>RatatuiRuby.draw</tt> block to render widgets with full
+  # control over placement.
+  #
+  # == Thread/Ractor Safety
+  #
+  # Frame is an *I/O handle*, not a data object. It has side effects
+  # (render_widget, set_cursor_position) and is intentionally *not*
+  # Ractor-shareable. Passing it to helper methods during the draw block is
+  # fine. However, do not include it in immutable Models/Messages or pass
+  # it to other Ractors. Frame is only valid during the draw block's execution.
+  #
+  # === Examples
+  #
+  # Basic usage with a single widget:
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   RatatuiRuby.draw do |frame|
+  #     paragraph = RatatuiRuby::Widgets::Paragraph.new(text: "Hello, world!")
+  #     frame.render_widget(paragraph, frame.area)
+  #   end
+  #
+  #--
+  # SPDX-SnippetEnd
+  #++
+  # Using Layout.split for multi-region layouts:
+  #
+  #--
+  # SPDX-SnippetBegin
+  # SPDX-FileCopyrightText: 2026 Kerrick Long
+  # SPDX-License-Identifier: MIT-0
+  #++
+  #   RatatuiRuby.draw do |frame|
+  #     sidebar, main = RatatuiRuby::Layout.split(
+  #       frame.area,
+  #       direction: :horizontal,
+  #       constraints: [
+  #         RatatuiRuby::Layout::Constraint.length(20),
+  #         RatatuiRuby::Layout::Constraint.fill(1)
+  #       ]
+  #     )
+  #
+  #     frame.render_widget(sidebar_widget, sidebar)
+  #     frame.render_widget(main_widget, main)
+  #
+  #     # Store rects for hit testing — no duplication!
+  #     @regions = { sidebar: sidebar, main: main }
+  #   end
+  #--
+  # SPDX-SnippetEnd
+  #++
+  class Frame
+    ##
+    # :method: area
+    # :call-seq: area() -> Rect
+    #
+    # Returns the full terminal area as a Rect.
+    #
+    # The returned Rect represents the entire drawable area of the terminal.
+    # Use it as the starting point for layout calculations.
+    #
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   RatatuiRuby.draw do |frame|
+    #     puts "Terminal size: #{frame.area.width}x#{frame.area.height}"
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: render_widget
+    # :call-seq: render_widget(widget, area) -> nil
+    #
+    # Renders a widget at the specified area.
+    #
+    # Widgets in RatatuiRuby are immutable Data objects. This method takes a
+    # widget and a Rect, rendering the widget's content within that region.
+    #
+    # [widget]
+    #   The widget to render (Paragraph, Layout, List, Table, etc.).
+    # [area]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2025 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   A Rect specifying where to render the widget.
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   RatatuiRuby.draw do |frame|
+    #     para = RatatuiRuby::Widgets::Paragraph.new(text: "Content")
+    #     frame.render_widget(para, frame.area)
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: render_stateful_widget
+    # :call-seq: render_stateful_widget(widget, area, state) -> nil
+    #
+    # Renders a widget with persistent state.
+    #
+    # Some UI components (like List or Table) have **runtime status** (Status) that
+    # changes during rendering, such as the current scroll offset.
+    #
+    # Since Widget definitions (Configuration Definition) are immutable inputs,
+    # you must pass a separate mutable State object (Output Status) to capture
+    # these changes.
+    #
+    # Note: The Widget configuration is *always* required. The State object is
+    # only used for specific widgets that need to persist runtime status.
+    #
+    #
+    # [widget]
+    #   The immutable widget configuration (Input) (e.g., RatatuiRuby::List).
+    # [area]
+    #   The Rect area to render into.
+    # [state]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   The mutable state object (Output) (e.g., RatatuiRuby::ListState).
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # === Example
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Initialize state once (outside the loop)
+    #   @list_state = RatatuiRuby::ListState.new
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     list = RatatuiRuby::Widgets::List.new(items: ["A", "B"])
+    #     frame.render_stateful_widget(list, frame.area, @list_state)
+    #   end
+    #
+    #   # Read back the offset calculated by Ratatui
+    #   puts @list_state.offset
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # (Native method implemented in Rust)
+
+    ##
+    # :method: set_cursor_position
+    # :call-seq: set_cursor_position(x, y) -> nil
+    #
+    # Positions the blinking cursor at the given coordinates.
+    #
+    # Text input fields show users where typed characters will appear. Without
+    # a visible cursor, users cannot tell if the input is focused or where text
+    # will insert.
+    #
+    # This method moves the terminal cursor to a specific cell. Coordinates are
+    # 0-indexed from the terminal's top-left corner.
+    #
+    # Use it when building login forms, search bars, or command palettes.
+    #
+    # [x]
+    #   Column position (<tt>0</tt> = leftmost column).
+    # [y]
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   Row position (<tt>0</tt> = topmost row).
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # === Example
+    #
+    # Position the cursor at the end of typed text in a login form:
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   PREFIX = "Username: [ "
+    #   username = "alice"
+    #
+    #   RatatuiRuby.draw do |frame|
+    #     # Render the input field
+    #     prompt = RatatuiRuby::Widgets::Paragraph.new(
+    #       text: "#{PREFIX}#{username} ]",
+    #       block: RatatuiRuby::Widgets::Block.new(borders: :all)
+    #     )
+    #     frame.render_widget(prompt, frame.area)
+    #
+    #     # Position cursor after the typed text
+    #     # Account for border (1) + prefix length + username length
+    #     cursor_x = 1 + PREFIX.length + username.length
+    #     cursor_y = 1  # First line inside border
+    #     frame.set_cursor_position(cursor_x, cursor_y)
+    #   end
+    #
+    #--
+    # SPDX-SnippetEnd
+    #++
+    # See also:
+    # - {Component-based implementation using Frame API}[link:/examples/app_color_picker/app_rb.html]
+    # - {Declarative implementation using Tree API}[link:/examples/app_login_form/app_rb.html]
+    # - RatatuiRuby::Cursor (Tree API alternative)
+    #
+    # (Native method implemented in Rust)
+  end
+end

data/lib/ratatui_ruby/labs/a11y.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "tmpdir"
+
+module RatatuiRuby
+  module Labs
+    # A11Y lab: exports widget tree as XML.
+    #
+    # Writes an XML representation of the widget tree to a temporary file
+    # every frame when enabled.
+    module A11y
+      # Path to the XML output file in the system temp directory.
+      OUTPUT_PATH = File.join(Dir.tmpdir, "ratatui_ruby_a11y.xml").freeze
+
+      class << self
+        # Dumps the widget tree to XML (single widget for tree mode).
+        def dump_widget_tree(widget, _area = nil)
+          ensure_rexml_loaded
+          doc = REXML::Document.new
+          doc.add(REXML::XMLDecl.new("1.0", "UTF-8"))
+          doc.add(build_element(widget))
+          write_document(doc)
+        end
+
+        # Returns startup message for users to see before TUI launches.
+        #
+        # Since stdout is captured during TUI rendering, users need to know
+        # where the XML file will be written before the app starts.
+        def startup_message
+          <<~MSG
+            A11Y Lab enabled! Widget tree will be written to:
+              #{OUTPUT_PATH}
+
+            Press Enter to launch the TUI...
+          MSG
+        end
+
+        # Dumps multiple widgets captured from Frame API mode.
+        def dump_widgets(widgets_with_areas)
+          ensure_rexml_loaded
+          Labs.warn_once!("Labs::A11y (RR_LABS=A11Y)")
+
+          # Reset counter each frame for stable IDs
+          @widget_id_counter = 0
+
+          doc = REXML::Document.new
+          doc.add(REXML::XMLDecl.new("1.0", "UTF-8"))
+
+          frame = REXML::Element.new("RatatuiFrame")
+          widgets_with_areas.each do |widget, area|
+            frame.add(build_element_with_area(widget, area))
+          end
+          doc.add(frame)
+
+          write_document(doc)
+        end
+
+        private def write_document(doc)
+          output = +""
+          formatter = REXML::Formatters::Pretty.new(2)
+          formatter.compact = true
+          formatter.write(doc, output)
+          File.write(OUTPUT_PATH, output)
+        end
+
+        private def build_element_with_area(widget, area)
+          class_name = widget.class.name&.split("::")&.last || "Unknown"
+          element = REXML::Element.new(class_name)
+
+          # Generate unique id for this widget
+          @widget_id_counter ||= 0
+          @widget_id_counter += 1
+          widget_id = "w#{@widget_id_counter}"
+          element.add_attribute("id", widget_id)
+
+          # Add area attributes
+          element.add_attribute("x", area.x.to_s)
+          element.add_attribute("y", area.y.to_s)
+          element.add_attribute("width", area.width.to_s)
+          element.add_attribute("height", area.height.to_s)
+
+          add_members(element, widget, parent_id: widget_id)
+          element
+        end
+
+        private def build_element(node)
+          class_name = node.class.name&.split("::")&.last || "Unknown"
+          element = REXML::Element.new(class_name)
+
+          if node.respond_to?(:to_h) && node.respond_to?(:members)
+            add_members(element, node)
+          else
+            element.text = node.to_s
+          end
+
+          element
+        end
+
+        private def add_members(element, node, parent_id: nil)
+          return unless node.respond_to?(:to_h) && node.respond_to?(:members)
+
+          node.to_h.each do |key, value|
+            # Skip nil and empty values entirely (no noise in output)
+            next if value.nil?
+            next if value.respond_to?(:empty?) && value.empty?
+
+            # Skip objects where all members are nil/empty (like default Style)
+            if value.respond_to?(:to_h) && value.respond_to?(:members)
+              attrs = value.to_h.compact
+              next if attrs.empty? || attrs.values.all? { |v| v.respond_to?(:empty?) && v.empty? }
+            end
+
+            # Scalar values → XML attributes
+            # Exception: 'text' and 'content' accept Text (multi-line capable)
+            # Complex values → XML child elements
+            multiline_keys = %w[text content]
+            if scalar?(value) && !multiline_keys.include?(key.to_s)
+              element.add_attribute(key.to_s, value.to_s)
+            else
+              # Special handling for 'block' wrapper - add ARIA role and id/for
+              is_block_wrapper = key.to_s == "block" && parent_id
+              child = build_child_element(key, value, is_wrapper: is_block_wrapper, parent_id:)
+              element.add(child) if child
+            end
+          end
+        end
+
+        private def scalar?(value)
+          case value
+          when String, Symbol, Numeric, TrueClass, FalseClass
+            true
+          else
+            false
+          end
+        end
+
+        private def build_child_element(key, value, is_wrapper: false, parent_id: nil)
+          element = REXML::Element.new(key.to_s)
+
+          # Add ARIA role and id/for association for block wrappers
+          if is_wrapper && parent_id
+            element.add_attribute("role", "group")
+            element.add_attribute("for", parent_id)
+          end
+
+          case value
+          when Array
+            value.each { |item| element.add(build_element(item)) }
+          when Hash
+            # Plain Hash: serialize keys as attributes
+            value.each do |k, v|
+              next if v.nil?
+              next if v.respond_to?(:empty?) && v.empty?
+              element.add_attribute(k.to_s, v.to_s)
+            end
+          else
+            if value.respond_to?(:to_h) && value.respond_to?(:members)
+              add_members(element, value)
+            else
+              element.text = value.to_s
+            end
+          end
+
+          element
+        end
+
+        # Lazily loads REXML when first needed.
+        private def ensure_rexml_loaded
+          return if defined?(@rexml_loaded) && @rexml_loaded
+
+          require "rexml/document"
+          @rexml_loaded = true
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/labs/frame_a11y_capture.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Frame
+    # A11Y Lab Integration
+    #
+    # When the A11Y lab is enabled, we capture widgets as they are rendered
+    # and write the tree to XML when flush_a11y_capture is called.
+    module A11yCapture
+      # Intercepts render_widget to capture widgets for A11Y export.
+      # @param widget [widget] The widget being rendered
+      # @param area [Layout::Rect] The area to render into
+      def render_widget(widget, area)
+        if Labs.enabled?(:a11y)
+          widgets = (@a11y_widgets ||= []) #: Array[[(_CustomWidget | widget), Layout::Rect]]
+          widgets << [widget, area]
+        end
+        super
+      end
+
+      # Intercepts render_stateful_widget to capture widgets for A11Y export.
+      # @param widget [widget] The widget being rendered
+      # @param area [Layout::Rect] The area to render into
+      # @param state [Object] The widget state
+      def render_stateful_widget(widget, area, state)
+        if Labs.enabled?(:a11y)
+          widgets = (@a11y_widgets ||= []) #: Array[[(_CustomWidget | widget), Layout::Rect]]
+          widgets << [widget, area]
+        end
+        super
+      end
+
+      # Called at end of draw block to flush captured widgets
+      def flush_a11y_capture
+        widgets = @a11y_widgets
+        return unless Labs.enabled?(:a11y) && widgets&.any?
+
+        Labs::A11y.dump_widgets(widgets)
+        @a11y_widgets = nil
+      end
+    end
+
+    prepend A11yCapture
+  end
+end