charming 0.1.0

data/lib/charming/mouse_event.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Charming
+  # MOUSE_BUTTON_MAP encodes terminal mouse button codes to semantic symbols. The constant is frozen and private.
+  MOUSE_BUTTON_MAP = {
+    0 => :left, 1 => :middle, 2 => :right, 3 => :release,
+    64 => :scroll_up, 65 => :scroll_down,
+    66 => :scroll_up, 67 => :scroll_down
+  }.freeze
+  private_constant :MOUSE_BUTTON_MAP
+
+  # MouseEvent represents a mouse input event. *button* encodes which button or action was triggered (left,
+  # right, scroll), while *x* and *y* provide the cursor position. Modifier booleans (*ctrl*, *alt*, *shift*)
+  # capture key state at the time of the event.
+  MouseEvent = Data.define(:button, :x, :y, :ctrl, :alt, :shift) do
+    def initialize(button:, x:, y:, ctrl: false, alt: false, shift: false)
+      super
+    end
+
+    # Returns the semantic symbol for *button* — one of `left`, `right`, `scroll_up`, etc. or `:unknown`.
+    def button_name
+      MOUSE_BUTTON_MAP.fetch(button, :unknown)
+    end
+
+    # Returns `true` when the current event is a click (left, middle, or right button).
+    def click?
+      %i[left middle right].include?(button_name)
+    end
+
+    # Returns `true` when the button name maps to either direction of scroll.
+    def scroll?
+      %i[scroll_up scroll_down].include?(button_name)
+    end
+
+    # Returns `true` when the current event is a mouse release action.
+    def release?
+      button_name == :release
+    end
+  end
+end

data/lib/charming/resize_event.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Charming
+  # ResizeEvent represents a terminal window resize. *width* and *height* carry the new terminal dimensions
+  # in screen cells, replacing the previous Screen dimensions for all subsequent rendering.
+  ResizeEvent = Data.define(:width, :height)
+end

data/lib/charming/response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Charming
+  # Response encapsulates a controller's dispatch outcome — one of render text, navigate to another route, or quit.
+  # Rails-style factories (`render`, `navigate`, `quit`) serve as the public API and map to :kind values
+  # that the Runtime interprets at the end of each event loop iteration.
+  Response = Data.define(:kind, :body, :path) do
+    # Factory constructing a Render response for displaying *body* text on the current screen.
+    def self.render(body)
+      new(kind: :render, body: body, path: nil)
+    end
+
+    # Factory constructing a NavigateResponse routing to the named *path* (string).
+    def self.navigate(path)
+      new(kind: :navigate, body: "", path: path)
+    end
+
+    # Factory constructing a QuitResponse signalling termination of the top-level event loop.
+    def self.quit
+      new(kind: :quit, body: "", path: nil)
+    end
+
+    # Returns `true` when this response is navigating to another screen or route.
+    def navigate?
+      kind == :navigate
+    end
+
+    # Returns `true` when this response requests quitting the application.
+    def quit?
+      kind == :quit
+    end
+  end
+end

data/lib/charming/router.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Charming
+  # Router manages an application's route table and provides a Rails-inspired DSL for defining routes.
+  # Each route maps a URL path to a controller, action (implicitly :show), and title (for sidebar display).
+  class Router
+    # Route is a Data object holding a route's path template, target controller/action, title, and resolved params.
+    Route = Data.define(:path, :controller_class, :action, :title, :params) do
+      def with_params(params)
+        self.class.new(
+          path: path,
+          controller_class: controller_class,
+          action: action,
+          title: title,
+          params: params
+        )
+      end
+    end
+
+    DynamicRoute = Data.define(:route, :pattern, :param_names)
+
+    # Initializes a new router with an optional namespace prefix for controller constant lookups.
+    def initialize(namespace: nil)
+      @namespace = namespace
+      @routes = {}
+      @dynamic_routes = []
+    end
+
+    # Evaluates a block in the context of this Router instance using instance_eval, allowing DSL calls like screen and root to register routes.
+    # This is how `routes.draw { screen "/", to: "HomeController", title: "Home" }` works.
+    def draw(&)
+      instance_eval(&)
+    end
+
+    # Registers the home screen at "/" with a given title. Shorthand for `screen path, to: target`.
+    # Example: `root "HomeController"` maps `/` → HomeController#show with title "Home".
+    def root(target, title: "Home")
+      screen("/", to: target, title: title)
+    end
+
+    # Maps a URL path to a controller and action (e.g. "HomeController" for HomeController#show).
+    # Builds a Route object from the path, resolved controller constant, parsed action, and an optional or derived title.
+    def screen(path, to:, title: nil)
+      controller_name, action = to.split("#", 2)
+      route = Route.new(
+        path: path,
+        controller_class: constantize(controller_constant_name(controller_name)),
+        action: action.to_sym,
+        title: title || derive_title(path),
+        params: {}
+      )
+      @routes[path] = route
+      @dynamic_routes.reject! { |dynamic_route| dynamic_route.route.path == path }
+      @dynamic_routes << compile_dynamic_route(route) if dynamic_path?(path)
+    end
+
+    # Resolves a route by path from the router's table. Exact routes win over dynamic routes.
+    # Raises KeyError if no route matches.
+    # Used at runtime to look up the controller class and action for incoming requests.
+    def resolve(path = "/")
+      @routes[path] || resolve_dynamic(path) || raise(KeyError, "key not found: #{path.inspect}")
+    end
+
+    # Returns all registered routes as Route objects, ordered by insertion.
+    # Consumed by the application loop to populate the sidebar and by controllers for navigation context.
+    def all
+      @routes.values
+    end
+
+    private
+
+    # The namespace prefix from initialization — used to scope controller constant lookups.
+    # For example, namespace "Admin" means HomeController resolves as Admin::HomeController.
+    attr_reader :namespace
+
+    def dynamic_path?(path)
+      path.split("/").any? { |segment| segment.start_with?(":") && segment.length > 1 }
+    end
+
+    def compile_dynamic_route(route)
+      param_names = []
+      segments = route.path.split("/", -1).map do |segment|
+        if segment.start_with?(":") && segment.length > 1
+          param_names << segment.delete_prefix(":").to_sym
+          "([^/]+)"
+        else
+          Regexp.escape(segment)
+        end
+      end
+
+      DynamicRoute.new(route: route, pattern: /\A#{segments.join("/")}\z/, param_names: param_names)
+    end
+
+    def resolve_dynamic(path)
+      @dynamic_routes.each do |dynamic_route|
+        match = dynamic_route.pattern.match(path)
+        return dynamic_route.route.with_params(extract_params(dynamic_route.param_names, match.captures)) if match
+      end
+
+      nil
+    end
+
+    def extract_params(names, values)
+      names.zip(values).to_h do |name, value|
+        [name, URI.decode_www_form_component(value)]
+      end
+    end
+
+    # Splits a camel-case string into words for title derivation (e.g., "my_route" → ["my", "route"]).
+    def camelize(value)
+      value.split("_").map(&:capitalize).join
+    end
+
+    # Looks up a constant by name in Object. Used to resolve controller strings from route definitions.
+    def constantize(name)
+      Object.const_get(name)
+    end
+
+    # Builds the full controller constant name, prepending the namespace if present.
+    # For example: "HomeController" with namespace "Admin" → "Admin::HomeController".
+    def controller_constant_name(controller_name)
+      name = "#{camelize(controller_name)}Controller"
+      @namespace.to_s.empty? ? name : "#{@namespace}::#{name}"
+    end
+
+    # Derives a human-readable title from a URL path by stripping the leading slash,
+    # splitting on underscores/hyphens/slashes, capitalizing each segment, and joining with spaces.
+    # Examples: "/projects" → "Projects", "/projects/list" → "Projects List".
+    def derive_title(path)
+      return "Home" if path == "/"
+
+      path.delete_prefix("/").split(%r{[_\-/]}).map(&:capitalize).join(" ")
+    end
+  end
+end

data/lib/charming/runtime.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Charming
+  # Runtime manages a terminal UI application's lifecycle: setting up an
+  # alternative-screen terminal with cursor hiding, running an event loop that
+  # reads keyboard, mouse, timer, and task events, dispatching them to
+  # controllers, rendering responses, and tearing down cleanly on exit.
+  class Runtime
+    DEFAULT_READ_TIMEOUT = 0.05
+
+    def initialize(application, backend: nil, renderer: nil, clock: nil, task_executor: nil)
+      @application = application
+      @backend = backend || Internal::Terminal::TTYBackend.new
+      @renderer = renderer || Internal::Renderer::Differential.new(@backend)
+      @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @task_queue = Thread::Queue.new
+      @task_executor = build_task_executor(task_executor)
+      @application.task_executor = @task_executor
+      @route = @application.routes.resolve("/")
+      @screen = backend_screen
+      @timers = build_timers
+    end
+
+    # Runs the event loop: enters alt-screen, dispatches incoming events
+    # (key, mouse, timer, async task), renders controller responses, and
+    # restores terminal state on exit.
+    def run
+      setup_terminal
+      render(resolve_response(dispatch(@route.action)))
+      loop do
+        event = next_task_event || next_timer_event || @backend.read_event(timeout: read_timeout)
+        next unless event
+
+        response = dispatch_event(event)
+        next unless response
+        break if response.quit?
+
+        response = resolve_response(response)
+        break if response.quit?
+
+        render(response)
+      end
+    ensure
+      @task_executor&.shutdown(timeout: 0.0)
+      restore_terminal
+    end
+
+    private
+
+    attr_reader :screen
+
+    # Dispatches an action on the current route's controller with an optional event.
+    # Entry point from the event loop into controllers.
+    def dispatch(action, event: nil)
+      controller(event: event).dispatch(action)
+    end
+
+    # Dispatches a key press to the current route's controller.
+    def dispatch_key(event)
+      controller(event: event).dispatch_key
+    end
+
+    # Dispatches a timer tick to the current route's controller.
+    def dispatch_timer(event)
+      controller(event: event).dispatch_timer
+    end
+
+    # Dispatches an async task result to the current route's controller.
+    def dispatch_task(event)
+      controller(event: event).dispatch_task
+    end
+
+    # Dispatches a mouse action (click, drag, scroll) to the current route's controller.
+    def dispatch_mouse(event)
+      controller(event: event).dispatch_mouse
+    end
+
+    def controller(event: nil)
+      @route.controller_class.new(application: @application, event: event, params: @route.params, screen: screen)
+    end
+
+    # Type-based dispatcher: routes resize, task, timer, mouse, and key events
+    # to the appropriate handler. Falls back to key dispatch for unclassified events.
+    def dispatch_event(event)
+      return dispatch_resize(event) if event.is_a?(ResizeEvent)
+      return dispatch_task(event) if event.is_a?(TaskEvent)
+      return dispatch_timer(event) if event.is_a?(TimerEvent)
+      return dispatch_mouse(event) if event.is_a?(MouseEvent)
+
+      dispatch_key(event)
+    end
+
+    # Dispatches a resize event: updates screen dimensions and re-renders the current action.
+    def dispatch_resize(event)
+      @screen = Screen.new(width: event.width, height: event.height)
+      dispatch(@route.action, event: event)
+    end
+
+    # Follows navigation responses: resolves the new route from the router,
+    # resets timers for the new route, and dispatches that route's action.
+    def resolve_response(response)
+      return response unless response.navigate?
+
+      @route = @application.routes.resolve(response.path)
+      @timers = build_timers
+      dispatch(@route.action)
+    end
+
+    # Derives Screen dimensions (width, height) from the terminal backend.
+    def backend_screen
+      width, height = @backend.size
+      Screen.new(width: width, height: height)
+    end
+
+    # Renders the body portion of a response through the renderer.
+    def render(response)
+      @renderer.render(response.body)
+    end
+
+    # Builds the initial set of timer states from controller bindings and the current clock time.
+    def build_timers
+      now = clock_now
+      @route.controller_class.timer_bindings.values.map do |binding|
+        {binding: binding, next_at: now + binding.interval}
+      end
+    end
+
+    # Returns a TimerEvent for the first due timer and advances its next fire time.
+    # Returns nil if no timers are ready or registered.
+    def next_timer_event
+      timer = due_timer
+      return unless timer
+
+      now = clock_now
+      timer[:next_at] = now + timer.fetch(:binding).interval
+      TimerEvent.new(name: timer.fetch(:binding).name, now: now)
+    end
+
+    # Pops a task event from the thread-safe queue if one is available.
+    # Non-blocking — returns nil immediately when the queue is empty.
+    def next_task_event
+      @task_queue.pop(true)
+    rescue ThreadError
+      nil
+    end
+
+    # Returns timer values due at or before `now`, sorted by next fire time.
+    def due_timer
+      now = clock_now
+      @timers.select { |timer| timer.fetch(:next_at) <= now }.min_by { |timer| timer.fetch(:next_at) }
+    end
+
+    # Computes how long to block waiting for input based on when the next timer is due,
+    # clamped between 0 and DEFAULT_READ_TIMEOUT (0.05s). Returns DEFAULT when no timers exist.
+    def read_timeout
+      next_at = @timers.map { |timer| timer.fetch(:next_at) }.min
+      return DEFAULT_READ_TIMEOUT unless next_at
+
+      (next_at - clock_now).clamp(0, DEFAULT_READ_TIMEOUT)
+    end
+
+    # Constructs a task executor: supports explicit instances, callable factories, or the default Threaded executor.
+    def build_task_executor(task_executor)
+      return TaskExecutor::Threaded.new(@task_queue) unless task_executor
+      return task_executor if task_executor.respond_to?(:submit)
+      return task_executor.call(@task_queue) if task_executor.respond_to?(:call) && !task_executor.respond_to?(:new)
+
+      task_executor.new(@task_queue)
+    end
+
+    # Returns the clock proc, providing a single point of access for time in the event loop.
+    def clock_now
+      @clock.call
+    end
+
+    # Enters an alternative screen buffer, hides the cursor, and installs
+    # a terminal resize signal handler if supported by the backend.
+    def setup_terminal
+      @backend.enter_alt_screen
+      @backend.hide_cursor
+      @backend.install_resize_handler if @backend.respond_to?(:install_resize_handler)
+    end
+
+    # Restores terminal state: reinstalls any previous resize handler, shows
+    # the cursor, and leaves the alternative screen buffer.
+    def restore_terminal
+      @backend.restore_resize_handler if @backend.respond_to?(:restore_resize_handler)
+      @backend.show_cursor
+      @backend.leave_alt_screen
+    end
+  end
+end

data/lib/charming/screen.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Charming
+  # Screen represents the terminal viewport dimensions as a simple Data class.
+  # The `width` and `height` values flow from the backend through the runtime
+  # loop into every controller dispatch for layout calculations.
+  Screen = Data.define(:width, :height)
+end

data/lib/charming/task.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Charming
+  Task = Data.define(:name, :block) do
+    def call = block.call
+  end
+end

data/lib/charming/task_event.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Charming
+  # TaskEvent represents background task completion. *name* is the declared task identifier, *value* carries
+  # the return result and *error* captures any exception raised during execution. The `error?` predicate
+  # simplifies error handling in controller handlers.
+  TaskEvent = Data.define(:name, :value, :error) do
+    def initialize(name:, value: nil, error: nil)
+      super
+    end
+
+    # Returns `true` when the task finished with a non-nil exception.
+    def error?
+      !error.nil?
+    end
+  end
+end

data/lib/charming/task_executor.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Charming
+  module TaskExecutor
+    class Threaded
+      def initialize(queue)
+        @queue = queue
+        @threads = []
+        @mutex = Mutex.new
+      end
+
+      def submit(name, &block)
+        task = Task.new(name: name.to_sym, block: block)
+        thread = Thread.new(task) { |t| @queue << run(t) }
+        @mutex.synchronize { @threads << thread }
+        nil
+      end
+
+      def shutdown(timeout: 0.0)
+        threads = @mutex.synchronize { @threads.dup }
+        threads.each { |thread| thread.join(timeout) }
+        threads.each do |thread|
+          next unless thread.alive?
+
+          thread.kill
+          thread.join(0)
+        end
+      end
+
+      private
+
+      def run(task)
+        TaskEvent.new(name: task.name, value: task.call)
+      rescue StandardError, ScriptError => e
+        TaskEvent.new(name: task.name, error: e)
+      end
+    end
+
+    class Inline
+      def initialize(queue)
+        @queue = queue
+      end
+
+      def submit(name, &block)
+        task = Task.new(name: name.to_sym, block: block)
+        @queue << run(task)
+        nil
+      end
+
+      def shutdown(timeout: 0.0)
+      end
+
+      private
+
+      def run(task)
+        TaskEvent.new(name: task.name, value: task.call)
+      rescue StandardError, ScriptError => e
+        TaskEvent.new(name: task.name, error: e)
+      end
+    end
+  end
+end

data/lib/charming/timer_event.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Charming
+  # TimerEvent represents a timed dispatch from the runtime loop. *name* is the declared timer identifier;
+  # *now* is the monotonically rising clock value at emission for throttle comparisons.
+  TimerEvent = Data.define(:name, :now)
+end

data/lib/charming/ui/border.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    class Border
+      attr_reader :top_left, :top_right, :bottom_left, :bottom_right, :horizontal, :vertical
+
+      def initialize(corners:, edges:)
+        @top_left, @top_right, @bottom_left, @bottom_right = corners
+        @horizontal, @vertical = edges
+      end
+
+      def self.fetch(name)
+        STYLES.fetch(name.to_sym)
+      end
+    end
+
+    Border::STYLES = {
+      normal: Border.new(
+        corners: ["+", "+", "+", "+"], edges: ["-", "|"]
+      ),
+      rounded: Border.new(
+        corners: ["╭", "╮", "╰", "╯"], edges: ["─", "│"]
+      ),
+      thick: Border.new(
+        corners: ["┏", "┓", "┗", "┛"], edges: ["━", "┃"]
+      ),
+      double: Border.new(
+        corners: ["╔", "╗", "╚", "╝"], edges: ["═", "║"]
+      )
+    }.freeze
+  end
+end