rubytui 1.2.3

data/lib/rubytui/app.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Optional Model-View-Update (Elm Architecture) framework.
+  # Provides a structured pattern for building TUI applications.
+  #
+  # @example Counter app
+  #   class MyApp
+  #     include RubyTUI::App
+  #
+  #     def init
+  #       { counter: 0 }   # initial model
+  #     end
+  #
+  #     def update(model, msg)
+  #       case msg
+  #       when :increment then model.merge(counter: model[:counter] + 1)
+  #       when :quit      then throw(:quit)
+  #       else model
+  #       end
+  #     end
+  #
+  #     def view(model, frame)
+  #       frame.buffer.set_string(0, 0, "Count: #{model[:counter]}")
+  #     end
+  #
+  #     def handle_event(event)
+  #       case event
+  #       when KeyEvent
+  #         case event.char
+  #         when "+" then :increment
+  #         when "q" then :quit
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  #   MyApp.new.run!
+  #
+  module App
+    # Extend the including class with {ClassMethods}.
+    #
+    # @param base [Class] the class that includes App
+    # @return [void]
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class-level methods added to every class that includes {App}.
+    module ClassMethods
+      # Convenience: create and run the app
+      #
+      # Instantiates the class with no arguments and calls {App#run!}.
+      #
+      # @param opts [Hash{Symbol => Object}] keyword options forwarded to {App#run!}
+      # @return [void]
+      def run!(**opts)
+        new.run!(**opts)
+      end
+    end
+
+    # Override: return the initial model (a Hash or any object)
+    #
+    # @return [Object] the initial model (default: empty Hash)
+    def init
+      {}
+    end
+
+    # Override: given the current model and a message, return the next model.
+    # Call <tt>throw(:quit)</tt> from update to exit the app loop.
+    #
+    # @param model [Object] the current model
+    # @param msg [Object] non-nil message from {#handle_event} or {#handle_tick}
+    # @return [Object] the next model (default: +model+ unchanged)
+    def update(model, msg)
+      model
+    end
+
+    # Override: render the UI for the current model
+    #
+    # Called inside {Terminal#draw} once per loop iteration.
+    #
+    # @param model [Object] the current model
+    # @param frame [Frame] the frame to render into
+    # @return [void]
+    def view(model, frame)
+    end
+
+    # Override: convert an Event into a message (or nil to ignore)
+    #
+    # @param event [Event] the event returned by {Input::Reader#poll}
+    # @return [Object, nil] message passed to {#update}, or nil to ignore
+    #   (default: nil)
+    def handle_event(event)
+      nil
+    end
+
+    # Optional: called once before the main loop with [terminal, reader]
+    #
+    # Called after {#init}, with the terminal already set up.
+    #
+    # @param terminal [Terminal] the initialized terminal
+    # @param reader [Input::Reader] the input reader
+    # @return [void]
+    def on_start(terminal, reader)
+    end
+
+    # Optional: called once after the main loop exits
+    #
+    # Called before the terminal is restored.
+    #
+    # @param model [Object, nil] the result of the <tt>catch(:quit)</tt> block:
+    #   the value passed as <tt>throw(:quit, value)</tt>, or nil for a bare
+    #   <tt>throw(:quit)</tt>
+    # @return [void]
+    def on_stop(model)
+    end
+
+    # Run the application.
+    #
+    # The main loop renders, polls for events, and dispatches messages.
+    # Call <tt>throw(:quit)</tt> from {#update} to exit the loop cleanly.
+    #
+    # Wraps {RubyTUI.run} (raw mode, hidden cursor, alternate screen), so
+    # the terminal is restored when the loop exits or raises. Each
+    # iteration draws via {#view}, waits up to +tick_ms+ for an event
+    # (passed through {#handle_event}), then calls {#handle_tick}; non-nil
+    # messages from either are passed to {#update}.
+    #
+    # @param mouse [Boolean] enable mouse event reporting (default: false)
+    # @param tick_ms [Integer] event poll timeout per loop iteration, in
+    #   milliseconds (default: 50)
+    # @param output [IO] output stream (default: $stdout)
+    # @param input [IO] input stream (default: $stdin)
+    # @return [void]
+    def run!(mouse: false, tick_ms: 50, output: $stdout, input: $stdin)
+      RubyTUI.run(output: output, input: input, mouse: mouse) do |terminal, reader|
+        model = init
+        on_start(terminal, reader)
+
+        model = catch(:quit) do
+          loop do
+            terminal.draw do |frame|
+              view(model, frame)
+            end
+
+            event = reader.poll(timeout_ms: tick_ms)
+
+            if event
+              msg = handle_event(event)
+              model = update(model, msg) if msg
+            end
+
+            tick_msg = handle_tick(model)
+            model = update(model, tick_msg) if tick_msg
+          end
+        end
+
+        on_stop(model)
+      end
+    end
+
+    # Override: return a message on each tick, or nil
+    #
+    # Called once per loop iteration after polling, whether or not an
+    # event arrived.
+    #
+    # @param model [Object] the current model
+    # @return [Object, nil] message passed to {#update}, or nil (default: nil)
+    def handle_tick(model)
+      nil
+    end
+  end
+end

data/lib/rubytui/backend.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Backend interface contract.
+  # A backend translates buffer diffs into terminal output.
+  #
+  # Including classes must override every method that raises
+  # +NotImplementedError+; the image-related methods have defaults.
+  #
+  # @see AnsiBackend
+  # @see TestBackend
+  module Backend
+    # Write changed cells to the terminal.
+    # @param changes [Array<Array(Integer, Integer, Cell)>] array of [x, y, cell]
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def draw(changes)
+      raise NotImplementedError
+    end
+
+    # Hide the cursor
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def hide_cursor
+      raise NotImplementedError
+    end
+
+    # Show the cursor
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def show_cursor
+      raise NotImplementedError
+    end
+
+    # Move cursor to position
+    #
+    # @param x [Integer] zero-based column
+    # @param y [Integer] zero-based row
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def move_cursor(x, y)
+      raise NotImplementedError
+    end
+
+    # Clear the entire screen
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def clear
+      raise NotImplementedError
+    end
+
+    # Enter alternate screen buffer
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def enter_alternate_screen
+      raise NotImplementedError
+    end
+
+    # Leave alternate screen buffer
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def leave_alternate_screen
+      raise NotImplementedError
+    end
+
+    # Enable raw mode (no echo, no line buffering)
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def enable_raw_mode
+      raise NotImplementedError
+    end
+
+    # Disable raw mode
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def disable_raw_mode
+      raise NotImplementedError
+    end
+
+    # Get terminal size as [width, height]
+    #
+    # @return [Array(Integer, Integer)] [width, height] in cells
+    # @raise [NotImplementedError] unless overridden by the including class
+    def size
+      raise NotImplementedError
+    end
+
+    # Flush output
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def flush
+      raise NotImplementedError
+    end
+
+    # Enable mouse event reporting
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def enable_mouse
+      raise NotImplementedError
+    end
+
+    # Disable mouse event reporting
+    #
+    # @return [void]
+    # @raise [NotImplementedError] unless overridden by the including class
+    def disable_mouse
+      raise NotImplementedError
+    end
+
+    # Draw an image using the Kitty graphics protocol.
+    # No-op by default; backends that support images override it.
+    # @param placement [Hash{Symbol => Object}] image placement data with keys
+    #   +:x+, +:y+, +:cols+, +:rows+, +:data+, +:pixel_width+, +:pixel_height+, +:format+,
+    #   +:content_hash+, +:src_x+, +:src_y+, +:src_w+, +:src_h+
+    # @return [void]
+    def draw_kitty_image(placement)
+      # no-op by default (not all backends support images)
+    end
+
+    # Delete a Kitty graphics protocol image.
+    # No-op by default.
+    # @param placement [Hash{Symbol => Object}] the image placement to delete
+    # @return [void]
+    def delete_kitty_image(placement)
+      # no-op by default
+    end
+
+    # Delete all Kitty graphics protocol images.
+    # No-op by default.
+    # @return [void]
+    def clear_all_images!
+      # no-op by default
+    end
+
+    # Query terminal for cell pixel dimensions.
+    # The default implementation returns [9, 18] without querying.
+    # @return [Array(Integer, Integer)] cell dimensions [width_px, height_px]
+    def query_cell_pixel_size
+      [9, 18]
+    end
+
+    # Cached cell pixel dimensions; the default implementation returns nil.
+    #
+    # @return [Array(Integer, Integer), nil] cached cell dimensions
+    def cell_pixel_size
+      nil
+    end
+  end
+end