charming 0.1.0

data/lib/charming/generators/name.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Charming
+  module Generators
+    class Name
+      VALID_NAME = /\A[a-z][a-z0-9_]*\z/
+
+      attr_reader :snake_name
+
+      def initialize(value)
+        @snake_name = value.to_s
+        raise Error, "Invalid name: #{value}" unless VALID_NAME.match?(@snake_name)
+      end
+
+      def class_name
+        snake_name.split("_").map(&:capitalize).join
+      end
+
+      def controller_class_name
+        "#{class_name}Controller"
+      end
+
+      def view_class_name
+        "#{class_name}View"
+      end
+
+      def component_class_name
+        "#{class_name}Component"
+      end
+    end
+  end
+end

data/lib/charming/generators/screen_generator.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Charming
+  module Generators
+    class ScreenGenerator < AppFileGenerator
+      include AppGenerator::ScreenSpecTemplates
+
+      def initialize(name, args, out:, destination:, force: false)
+        super
+        raise Error, "Usage: charming generate screen NAME" if args.any?
+      end
+
+      def generate
+        create_file(model_path, model)
+        create_file(controller_path, controller)
+        create_file(view_path, view)
+        create_file(spec_model_path, spec_model)
+        create_file(spec_controller_path, spec_controller)
+        create_file(spec_view_path, spec_view)
+        insert_route
+        insert_command
+      end
+
+      private
+
+      def suffix
+        "screen"
+      end
+
+      def model_path
+        File.join("app", "models", "#{name.snake_name}_model.rb")
+      end
+
+      def controller_path
+        File.join("app", "controllers", "#{name.snake_name}_controller.rb")
+      end
+
+      def view_path
+        File.join("app", "views", "#{name.snake_name}_view.rb")
+      end
+
+      def spec_model_path
+        File.join("spec", "models", "#{name.snake_name}_model_spec.rb")
+      end
+
+      def spec_controller_path
+        File.join("spec", "controllers", "#{name.snake_name}_controller_spec.rb")
+      end
+
+      def spec_view_path
+        File.join("spec", "views", "#{name.snake_name}_view_spec.rb")
+      end
+
+      def route_path
+        File.join(destination, "config", "routes.rb")
+      end
+
+      def application_controller_path
+        File.join(destination, "app", "controllers", "application_controller.rb")
+      end
+
+      def model
+        %(# frozen_string_literal: true
+
+module #{app_name.class_name}
+  class #{name.class_name}Model < ApplicationModel
+    attribute :title, :string, default: "#{name.class_name}"
+  end
+end
+)
+      end
+
+      def controller
+        %(# frozen_string_literal: true
+
+module #{app_name.class_name}
+  class #{name.controller_class_name} < ApplicationController
+#{controller_body}
+  end
+end
+)
+      end
+
+      def controller_body
+        %(    def show
+      render #{name.view_class_name}.new(
+        #{name.snake_name}: #{name.snake_name},
+        palette: command_palette,
+        screen: screen
+      )
+    end
+
+    private
+
+    def #{name.snake_name}
+      model(:#{name.snake_name}, #{name.class_name}Model)
+    end)
+      end
+
+      def view
+        %(# frozen_string_literal: true
+
+module #{app_name.class_name}
+  class #{name.view_class_name} < Charming::View
+#{view_body}
+  end
+end
+)
+      end
+
+      def view_body
+        %(    def render
+      #{name.snake_name}.title
+    end)
+      end
+
+      def insert_route
+        route = %(  screen "/#{name.snake_name}", to: "#{name.snake_name}#show", title: "#{name.class_name}")
+        insert_before_end(route_path, route, "route", "end")
+      end
+
+      def insert_command
+        command = %(    command "#{name.class_name}" do
+      navigate_to "/#{name.snake_name}"
+    end)
+        insert_before_end(application_controller_path, command, "command", "  end")
+      end
+
+      def insert_before_end(path, content, label, end_line)
+        raise Error, "Missing file: #{relative_path(path)}" unless File.exist?(path)
+
+        current = File.read(path)
+        return if current.include?(content)
+
+        lines = current.lines
+        index = insertion_index(lines, path, end_line)
+        lines.insert(index, "#{content}\n")
+        File.write(path, lines.join)
+        out.puts "insert #{label} #{relative_path(path)}"
+      end
+
+      def insertion_index(lines, path, end_line)
+        index = lines.rindex { |line| line.chomp == end_line }
+        raise Error, "Could not update #{relative_path(path)}" unless index
+
+        index
+      end
+
+      def relative_path(path)
+        path.delete_prefix("#{destination}/")
+      end
+    end
+  end
+end

data/lib/charming/generators/view_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Charming
+  module Generators
+    class ViewGenerator < AppFileGenerator
+      def generate
+        create_file(app_path("app", "views"), view)
+      end
+
+      private
+
+      def suffix
+        "view"
+      end
+
+      def view
+        %(# frozen_string_literal: true
+
+module #{app_name.class_name}
+  class #{name.view_class_name} < Charming::View
+#{view_body}
+  end
+end
+)
+      end
+
+      def view_body
+        %(    def render
+      "#{name.class_name}"
+    end)
+      end
+    end
+  end
+end

data/lib/charming/generators.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Charming
+  module Generators
+    class Error < StandardError; end
+  end
+end

data/lib/charming/internal/renderer/differential.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Renderer
+      class Differential
+        def initialize(output, full_renderer: FullRepaint.new(output))
+          @output = output
+          @full_renderer = full_renderer
+          @previous_frame = nil
+        end
+
+        def render(frame)
+          frame = frame.to_s
+          return render_initial(frame) unless @previous_frame
+          return if frame == @previous_frame
+
+          render_changes(frame)
+        end
+
+        private
+
+        def render_initial(frame)
+          @full_renderer.render(frame)
+          @previous_frame = frame
+        end
+
+        def render_changes(frame)
+          changes = changed_lines(@previous_frame, frame)
+          return @previous_frame = frame if changes.empty?
+
+          if @output.respond_to?(:write_lines)
+            @output.write_lines(changes, frame: frame)
+          else
+            @full_renderer.render(frame)
+          end
+          @previous_frame = frame
+        end
+
+        def changed_lines(previous_frame, frame)
+          previous_lines = previous_frame.lines(chomp: true)
+          lines = frame.lines(chomp: true)
+          line_count = [previous_lines.length, lines.length].max
+
+          line_count.times.filter_map do |index|
+            line = lines[index] || ""
+            [index + 1, line] unless previous_lines[index] == line
+          end
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/renderer/full_repaint.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Renderer
+      class FullRepaint
+        def initialize(output)
+          @output = output
+        end
+
+        def render(frame)
+          @output.clear
+          @output.move_cursor(1, 1)
+          @output.write_frame(frame)
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/adapter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      # Contract for terminal adapters used by Runtime and renderers.
+      # Concrete adapters provide input events, terminal dimensions, and output
+      # primitives for full or partial frame rendering.
+      module Adapter
+        def read_event(timeout: nil)
+          raise NotImplementedError, "#{self.class} must implement #read_event"
+        end
+
+        def size
+          raise NotImplementedError, "#{self.class} must implement #size"
+        end
+
+        def enter_alt_screen
+          raise NotImplementedError, "#{self.class} must implement #enter_alt_screen"
+        end
+
+        def leave_alt_screen
+          raise NotImplementedError, "#{self.class} must implement #leave_alt_screen"
+        end
+
+        def hide_cursor
+          raise NotImplementedError, "#{self.class} must implement #hide_cursor"
+        end
+
+        def show_cursor
+          raise NotImplementedError, "#{self.class} must implement #show_cursor"
+        end
+
+        def clear
+          raise NotImplementedError, "#{self.class} must implement #clear"
+        end
+
+        def move_cursor(row, column)
+          raise NotImplementedError, "#{self.class} must implement #move_cursor"
+        end
+
+        def write_frame(frame)
+          raise NotImplementedError, "#{self.class} must implement #write_frame"
+        end
+
+        def write_lines(line_changes, frame: nil)
+          raise NotImplementedError, "#{self.class} must implement #write_lines"
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/memory_backend.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Charming
+  module Internal
+    module Terminal
+      class MemoryBackend
+        include Adapter
+
+        attr_reader :frames, :operations
+
+        def initialize(events: [], width: 80, height: 24)
+          @events = events.dup
+          @width = width
+          @height = height
+          @frames = []
+          @operations = []
+          @mouse_enabled = false
+        end
+
+        def read_event(timeout: nil)
+          @operations << [:read_event, timeout]
+          @events.shift
+        end
+
+        def write_frame(frame)
+          @current_frame = frame
+          @frames << frame
+          @operations << [:write_frame, frame]
+        end
+
+        def write_lines(line_changes, frame: nil)
+          @current_frame = frame || apply_line_changes(line_changes)
+          @frames << @current_frame
+          @operations << [:write_lines, line_changes]
+        end
+
+        def enter_alt_screen
+          @operations << :enter_alt_screen
+        end
+
+        def leave_alt_screen
+          @operations << :leave_alt_screen
+        end
+
+        def show_cursor
+          @operations << :show_cursor
+        end
+
+        def hide_cursor
+          @operations << :hide_cursor
+        end
+
+        def clear
+          @operations << :clear
+        end
+
+        def move_cursor(row, column)
+          @operations << [:move_cursor, row, column]
+        end
+
+        def size
+          [@width, @height]
+        end
+
+        def enable_mouse_tracking
+          @mouse_enabled = true
+          @operations << :enable_mouse_tracking
+        end
+
+        def disable_mouse_tracking
+          @mouse_enabled = false
+          @operations << :disable_mouse_tracking
+        end
+
+        def mouse_enabled?
+          @mouse_enabled
+        end
+
+        private
+
+        def apply_line_changes(line_changes)
+          lines = @current_frame.to_s.lines(chomp: true)
+          line_changes.each do |row, line|
+            lines[row - 1] = line
+          end
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/charming/internal/terminal/tty_backend.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require "tty-cursor"
+require "tty-reader"
+require "tty-screen"
+
+module Charming
+  module Internal
+    module Terminal
+      class TTYBackend
+        include Adapter
+
+        ALT_SCREEN_ON = "\e[?1049h"
+        ALT_SCREEN_OFF = "\e[?1049l"
+        CTRL_KEY_PATTERN = /\Actrl_(?<key>.+)\z/
+        MOUSE_SGR_PATTERN = /\e\[<(\d+);(\d+);(\d+)([HmMhCc]?)(M|m)/
+        MOUSE_LEGACY_PATTERN = /\e\[M(.{3})/
+        MOUSE_BUTTON_MAP = {
+          0 => :left, 1 => :middle, 2 => :right, 3 => :release,
+          64 => :scroll_up, 65 => :scroll_down,
+          66 => :scroll_up, 67 => :scroll_down
+        }.freeze
+
+        def initialize(input: $stdin, output: $stdout, reader: nil, cursor: TTY::Cursor)
+          @input = input
+          @output = output
+          @reader = reader || TTY::Reader.new(input: input, output: output)
+          @cursor = cursor
+          @resized = false
+          @previous_winch_handler = nil
+          @mouse_enabled = false
+        end
+
+        def read_event(timeout: nil)
+          return resize_event if resized?
+
+          raw = @reader.read_keypress(echo: false, raw: true, nonblock: timeout)
+          return nil unless raw
+
+          return mouse_event(raw) if mouse_sequence?(raw)
+
+          normalize_keypress(raw)
+        rescue Errno::EAGAIN, IO::WaitReadable
+          nil
+        end
+
+        def install_resize_handler
+          @previous_winch_handler = Signal.trap("WINCH") { @resized = true }
+        end
+
+        def install_focus_handler
+          # Terminal focus change: some terminals send a special sequence
+          # when focus changes. We use this to throttle rendering.
+          @previous_focus_handler = Signal.trap("INFO") { @focused = true }
+        end
+
+        def restore_focus_handler
+          Signal.trap("INFO", @previous_focus_handler) if @previous_focus_handler
+          @previous_focus_handler = nil
+        end
+
+        def restore_resize_handler
+          Signal.trap("WINCH", @previous_winch_handler) if @previous_winch_handler
+          @previous_winch_handler = nil
+        end
+
+        def enable_mouse_tracking
+          return if @mouse_enabled
+
+          write_control("\e[?1000h")
+          write_control("\e[?1002h")
+          write_control("\e[?1006h")
+          @mouse_enabled = true
+        end
+
+        def disable_mouse_tracking
+          return unless @mouse_enabled
+
+          write_control("\e[?1000l")
+          write_control("\e[?1002l")
+          write_control("\e[?1003l")
+          write_control("\e[?1006l")
+          @mouse_enabled = false
+        end
+
+        def mouse_enabled?
+          @mouse_enabled
+        end
+
+        def notify_resize
+          @resized = true
+        end
+
+        def write_frame(frame)
+          @output.write(frame)
+          @output.flush
+        end
+
+        def write_lines(line_changes, **)
+          write_control(line_changes.map { |row, line| "\e[#{row};1H\e[2K#{line}" }.join)
+        end
+
+        def enter_alt_screen
+          write_control(ALT_SCREEN_ON)
+        end
+
+        def leave_alt_screen
+          write_control(ALT_SCREEN_OFF)
+        end
+
+        def show_cursor
+          write_control(@cursor.show)
+        end
+
+        def hide_cursor
+          write_control(@cursor.hide)
+        end
+
+        def clear
+          write_control(@cursor.clear_screen)
+        end
+
+        def move_cursor(row, column)
+          write_control(@cursor.move_to(column - 1, row - 1))
+        end
+
+        def size = [TTY::Screen.width, TTY::Screen.height]
+
+        private
+
+        def mouse_sequence?(raw)
+          return false unless raw.is_a?(String)
+          return true if raw.match?(MOUSE_SGR_PATTERN)
+          return true if raw.start_with?("\e[M")
+
+          false
+        end
+
+        def mouse_event(raw)
+          if raw.match?(MOUSE_SGR_PATTERN)
+            parse_sgr_mouse(raw)
+          else
+            parse_legacy_mouse(raw)
+          end
+        end
+
+        def parse_sgr_mouse(raw)
+          match = raw.match(MOUSE_SGR_PATTERN)
+          return nil unless match
+
+          # \e[<button>;<col>;<row><mode>M
+          button_code = match[1].to_i
+          col = match[2].to_i - 1
+          row = match[3].to_i - 1
+          mode = match[4]
+
+          ctrl = mode == "C"
+          alt = raw.include?("\e[38;5;")
+          shift = mode == "M"
+
+          MouseEvent.new(button: button_code, x: col, y: row, ctrl: ctrl, alt: alt, shift: shift)
+        end
+
+        def parse_legacy_mouse(raw)
+          # Legacy format: \e[M + 3 bytes (button, col, row)
+          # Each byte is 32 + value (space offset)
+          match = raw.match(MOUSE_LEGACY_PATTERN)
+          return nil unless match
+
+          bytes = match[1].bytes
+          return nil unless bytes.length == 3
+
+          button_code = bytes[0] - 32
+          col = bytes[1] - 32
+          row = bytes[2] - 32
+
+          MouseEvent.new(button: button_code, x: col, y: row)
+        end
+
+        def resized?
+          @resized
+        end
+
+        def resize_event
+          @resized = false
+          width, height = size
+          ResizeEvent.new(width: width, height: height)
+        end
+
+        def normalize_keypress(keypress)
+          return nil unless keypress
+
+          key_name = @reader.console.keys[keypress]
+          return character_event(keypress) unless key_name
+
+          named_event(key_name)
+        end
+
+        def character_event(keypress)
+          KeyEvent.new(key: keypress.to_sym, char: keypress)
+        end
+
+        def named_event(key_name)
+          normalized = normalize_key_name(key_name)
+          KeyEvent.new(
+            key: normalized.fetch(:key),
+            char: normalized.fetch(:char, nil),
+            ctrl: normalized.fetch(:ctrl, false),
+            alt: normalized.fetch(:alt, false),
+            shift: normalized.fetch(:shift, false)
+          )
+        end
+
+        def normalize_key_name(key_name)
+          name = key_name.to_s
+          return ctrl_key(name) if name.match?(CTRL_KEY_PATTERN)
+          return {key: :tab, shift: true} if name == "back_tab"
+
+          {key: normalized_key(name), char: printable_char(name)}
+        end
+
+        def normalized_key(name)
+          return :enter if name == "return"
+
+          name.to_sym
+        end
+
+        def ctrl_key(name)
+          match = name.match(CTRL_KEY_PATTERN)
+          {key: match[:key].to_sym, ctrl: true}
+        end
+
+        def printable_char(name)
+          case name
+          when "space" then " "
+          when "enter", "return" then "\n"
+          when "tab" then "\t"
+          else
+            name if name.length == 1 && !name.match?(/[[:cntrl:]]/)
+          end
+        end
+
+        def write_control(sequence)
+          @output.write(sequence)
+          @output.flush
+        end
+      end
+    end
+  end
+end

data/lib/charming/key_event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Charming
+  # KeyEvent represents a terminal key press parsed by the backend. *key* is the normalized semantic
+  # action name (e.g., `:up`, `:down`, `:q`), while *char*, *ctrl*, *alt*, and *shift* capture raw
+  # input details for custom bindings.
+  KeyEvent = Data.define(:key, :char, :ctrl, :alt, :shift) do
+    # Constructs a key event with the required *key* symbol, plus optional *char* string and modifier booleans.
+    def initialize(key:, char: nil, ctrl: false, alt: false, shift: false)
+      super(key: key.to_sym, char: char, ctrl: ctrl, alt: alt, shift: shift)
+    end
+  end
+end