charming 0.1.1 → 0.1.2

data/lib/charming/controller.rb

@@ -8,115 +8,19 @@ module Charming
     TimerBinding = Data.define(:name, :interval, :action)
     TaskBinding = Data.define(:name, :action)
 
-    class << self
-      # Registers a key binding (string or symbol key name → method symbol).
-      # Content-scoped bindings run from the main content pane; global bindings run from any pane.
-      def key(name, action, scope: :content)
-        normalized_scope = validate_key_scope(scope)
-        key_name = name.to_sym
-        key_bindings[key_name] = action
-        key_binding_scopes[key_name] = normalized_scope
-      end
-
-      # Registers a command palette entry — visible in fuzzy search when Ctrl+K is pressed.
-      # Accepts either a method symbol or an inline callable block.
-      def command(label, action = nil, &block)
-        command_bindings << Presentation::Components::CommandPalette::Command.new(label: label, value: block || action)
-      end
-
-      # Registers a periodic timer that fires at `every`-second intervals.
-      # The named action is dispatched on the current route's controller each time.
-      def timer(name, every:, action:)
-        timer_bindings[name.to_sym] = TimerBinding.new(name: name.to_sym, interval: every, action: action)
-      end
-
-      # Registers an async task handler that runs when a TaskEvent arrives from the task executor.
-      def on_task(name, action:)
-        task_bindings[name.to_sym] = TaskBinding.new(name: name.to_sym, action: action)
-      end
-
-      # Re-renders the given action after dispatched actions that do not set a response.
-      # This is opt-in so existing controllers keep explicit render semantics.
-      def auto_render(action = :show)
-        @auto_render_action = action.to_sym
-      end
-
-      def auto_render_action
-        return @auto_render_action if instance_variable_defined?(:@auto_render_action)
-        return superclass.auto_render_action if superclass.respond_to?(:auto_render_action)
-
-        nil
-      end
-
-      # Sets the layout class to wrap this controller's rendered output (e.g., for sidebar + main content).
-      # Accepts a special `:__charming_layout_reader__` sentinel to query — without setting — the current layout.
-      def layout(layout_class = :__charming_layout_reader__)
-        return resolved_layout if layout_class == :__charming_layout_reader__
-
-        @layout = layout_class
-      end
-
-      # Returns inherited key bindings merged from the class hierarchy.
-      # Each subclass gets a fresh copy of its parent's key bindings to avoid cross-controller pollution.
-      def key_bindings
-        @key_bindings ||= superclass.respond_to?(:key_bindings) ? superclass.key_bindings.dup : {}
-      end
-
-      # Returns inherited key binding scopes merged from the class hierarchy.
-      # Each subclass gets a fresh copy of its parent's scopes to match key binding inheritance.
-      def key_binding_scopes
-        @key_binding_scopes ||= superclass.respond_to?(:key_binding_scopes) ? superclass.key_binding_scopes.dup : {}
-      end
-
-      # Registers a focus ring slot for this controller — slots participate in Tab/Shift+Tab traversal.
-      # Example: `focus_ring :sidebar, :content` makes sidebar and content tabbable.
-      def focus_ring(*slots)
-        @focus_ring_slots = slots
-      end
-
-      # Returns inherited focus ring slots merged from the class hierarchy.
-      def focus_ring_slots
-        @focus_ring_slots ||= superclass.respond_to?(:focus_ring_slots) ? superclass.focus_ring_slots.dup : []
-      end
-
-      # Returns inherited command bindings (command palette entries) from this controller and its ancestors.
-      def command_bindings
-        @command_bindings ||= superclass.respond_to?(:command_bindings) ? superclass.command_bindings.dup : []
-      end
-
-      # Returns inherited timer bindings from this controller and its ancestors.
-      def timer_bindings
-        @timer_bindings ||= superclass.respond_to?(:timer_bindings) ? superclass.timer_bindings.dup : {}
-      end
-
-      # Returns inherited task bindings (async task handlers) from this controller and its ancestors.
-      def task_bindings
-        @task_bindings ||= superclass.respond_to?(:task_bindings) ? superclass.task_bindings.dup : {}
-      end
-
-      private
-
-      def validate_key_scope(scope)
-        normalized_scope = scope.to_sym
-        return normalized_scope if %i[content global].include?(normalized_scope)
-
-        raise ArgumentError, "unknown key scope: #{scope.inspect}"
-      end
-
-      # Returns the layout class for this controller, walking up the inheritance chain until one is found or nil.
-      # Used internally by `layout` when called without args (getter mode).
-      def resolved_layout
-        return @layout if instance_variable_defined?(:@layout)
-        return superclass.layout if superclass.respond_to?(:layout)
-
-        nil
-      end
-    end
+    extend ClassMethods
+    include Rendering
+    include SessionState
+    include FocusManagement
+    include SidebarNavigation
+    include CommandPalette
+    include ComponentDispatching
+    include Dispatching
 
     attr_reader :application, :event, :params, :screen, :route
 
-    # Initializes the controller with its parent application and an optional event (key/mouse/timer/task data).
-    # Defaults to a 80x24 screen when no backend size is available.
+    # Initializes the controller with its parent application and optional event.
+    # Defaults to an 80x24 screen when no backend size is available.
     def initialize(application:, event: nil, params: {}, screen: nil, route: nil)
       @application = application
       @event = event
@@ -126,80 +30,81 @@ module Charming
       @response = nil
     end
 
-    # Dispatches a named action on this controller (e.g., :show). Calls the method via public_send,
-    # returning a default empty render if the action produces no response.
+    # Dispatches a named action on this controller (e.g. :show).
     def dispatch(action)
       public_send(action)
       render_default_action if response.nil? && auto_render_after?(action)
       response || render("")
     end
 
-    # Key event dispatch pipeline for controllers: checks command palette first (if open),
-    # then global key bindings, then sidebar (if focused), then content-scoped key bindings,
-    # then tab traversal, then focused component handling. Returns nil if no handler consumed the event.
+    # Key event dispatch: checks command palette first, then global bindings,
+    # sidebar (if focused), content bindings, tab traversal, and focused component.
     def dispatch_key
       return dispatch_command_palette_key if command_palette_open?
       return dispatch(global_key_action) if global_key_action
       return dispatch_sidebar_key if sidebar_focused?
-
       return dispatch(content_key_action) if content_key_action
       return response if dispatch_tab_traversal == :handled
       return response if dispatch_to_focused_component == :handled
-
       nil
     end
 
-    # Timer event dispatcher: looks up the event's named action in this controller's timer bindings
-    # and dispatches it. Returns nil if no binding exists for this timer name.
+    # Timer event dispatcher: looks up the named action in timer bindings.
     def dispatch_timer
-      binding = self.class.timer_bindings[event.name.to_sym]
-      binding ? dispatch(binding.action) : nil
+      b = self.class.timer_bindings[event.name.to_sym]
+      return nil unless b
+
+      public_send(b.action)
+      response
     end
 
-    # Task event dispatcher: looks up the event's named handler in this controller's task bindings
-    # and dispatches it. Used by async tasks submitted via `run_task`.
+    # Task event dispatcher: looks up the handler in task bindings.
     def dispatch_task
-      binding = self.class.task_bindings[event.name.to_sym]
-      binding ? dispatch(binding.action) : nil
+      b = self.class.task_bindings[event.name.to_sym]
+      b ? dispatch(b.action) : nil
     end
 
-    # Mouse event dispatcher: checks command palette (if open), then sidebar (if focused),
-    # then falls through to component mouse dispatch. Always returns nil in the base controller —
-    # subclasses override as needed.
+    # Mouse event dispatcher: checks command palette (if open), sidebar (if focused).
     def dispatch_mouse
       return dispatch_command_palette_mouse if command_palette_open?
       return dispatch_sidebar_mouse if sidebar_focused?
-
       dispatch_component_mouse
     end
 
-    # Renders a body or template wrapped in this controller's layout (if one is defined) and stores the response.
-    # Symbols render `app/views/<controller>/<symbol>.tui.erb` (or `.txt.erb`); strings render as literal bodies.
+    # Renders a body or template wrapped in the controller's layout.
     def render(body = "", **assigns)
-      body = template_body(default_template_name(body), **assigns) if body.is_a?(Symbol)
+      body = view_body(default_template_name(body), **assigns) if body.is_a?(Symbol)
       @response = Response.render(render_with_layout(body))
     end
 
+    def render_view(view_class, **assigns)
+      @response = Response.render(render_with_layout(view_class.new(**template_assigns(assigns))))
+    end
+
+    # Renders a template from `app/views` by name, applying the controller's layout. *name* is the
+    # template path (e.g., "home/show") and additional keyword *assigns* are forwarded to the view.
     def render_template(name, **assigns)
       @response = Response.render(render_with_layout(template_body(name, **assigns)))
     end
 
+    # Returns the active theme for this request, delegated to the application.
     def theme
       application.theme
     end
 
+    # Switches the active theme to *name* and persists the choice in the application session.
     def use_theme(name)
       application.use_theme(name)
     end
 
+    # Opens the theme picker (a CommandPalette populated with the registered themes) and renders.
     def open_theme_palette
       session[:command_palette] = command_palette_state(:themes)
       focus.push_scope([:command_palette], origin: :command_palette)
       render_default_action
     end
 
-    # Responds with a navigation redirect to the given URL path.
-    # Used for route transitions triggered from controllers (e.g., sidebar selection).
+    # Navigates to the given URL path.
     def navigate_to(path)
       @response = Response.navigate(path)
     end
@@ -209,437 +114,8 @@ module Charming
       @response = Response.quit
     end
 
-    # Returns the parent application's session hash for per-request state storage (e.g., form data, flags).
-    def session
-      application.session
-    end
-
-    # Lazily instantiates a state class and caches it in the session under `:states`.
-    # Subsequent calls with the same name return the cached instance. Used like: state(:home, HomeState)
-    def state(name, state_class, **attributes)
-      session[:states] ||= {}
-      session[:states][name.to_sym] ||= state_class.new(**attributes)
-    end
-
-    def form(name, &block)
-      session[:forms] ||= {}
-      form_state = session[:forms][name.to_sym] ||= {}
-      builder = Presentation::Components::Form::Builder.new(theme: theme)
-      block.arity.zero? ? builder.instance_eval(&block) : block.call(builder)
-      builder.build(state: form_state, theme: theme)
-    end
-
-    # Submits an async task to the application's task executor (threaded or inline).
-    # The task runs in a background thread; results arrive as TaskEvents in `dispatch_task`.
-    def run_task(name, &block)
-      application.task_executor.submit(name, &block)
-    end
-
-    # Opens the command palette (fuzzy search UI): stores primitive palette state and pushes a palette
-    # scope onto the focus ring so input is captured inside it. Renders the default action afterward.
-    def open_command_palette
-      session[:command_palette] = command_palette_state(:commands)
-      focus.push_scope([:command_palette], origin: :command_palette)
-      render_default_action
-    end
-
-    # Closes the command palette: removes its state from the session, pops its scope from the focus ring,
-    # and re-renders the default action. Pops all nested scopes until only the palette remains.
-    def close_command_palette
-      session.delete(:command_palette)
-      pop_command_palette_scope
-      render_default_action
-    end
-
-    # Returns or lazily initializes the Focus instance for this controller, which manages
-    # keyboard-driven focus traversal between components (sidebar, content, etc.).
-    # Defines focus ring slots from class-level declarations on first access.
-    def focus
-      @focus ||= Focus.for(session, self.class).tap do |f|
-        f.define(self.class.focus_ring_slots) unless self.class.focus_ring_slots.empty?
-      end
-    end
-
-    # Checks whether the given focus slot (e.g., :sidebar, :content) is currently focused.
-    def focused?(slot)
-      focus.focused?(slot)
-    end
-
-    # Returns whether the command palette is active in the current session.
-    def command_palette_open?
-      session.key?(:command_palette)
-    end
-
-    # Returns a command palette component rebuilt from the current primitive session state, if open.
-    def command_palette
-      build_command_palette_from_state(session[:command_palette]) if command_palette_open?
-    end
-
-    # Shifts focus to the sidebar: moves the focus ring cursor or sets `session[:focus]` to :sidebar,
-    # highlights the current route index, and re-renders. Sidebar selection uses j/k keys.
-    def focus_sidebar
-      if focus_ring_slot?(:sidebar)
-        focus.focus(:sidebar)
-      else
-        session[:focus] = :sidebar
-      end
-      session[:sidebar_index] ||= current_route_index
-      render_default_action
-    end
-
-    # Shifts focus back to the main content area: moves the focus ring cursor or sets `session[:focus]` to :content,
-    # and re-renders. Used by Escape key from sidebar and other navigation transitions.
-    def focus_content
-      if focus_ring_slot?(:content)
-        focus.focus(:content)
-      else
-        session[:focus] = :content
-      end
-      render_default_action
-    end
-
-    # Returns whether the sidebar currently has focus (from focus ring or session state).
-    def sidebar_focused?
-      return focused?(:sidebar) if focus_ring_slot?(:sidebar)
-
-      session[:focus] == :sidebar
-    end
-
-    # Returns whether the main content area currently has focus (from focus ring or session state).
-    def content_focused?
-      return focused?(:content) if focus_ring_slot?(:content)
-
-      session[:focus] == :content
-    end
-
-    # Returns the currently highlighted sidebar item index, falling back to the current route's position
-    # when no explicit sidebar selection has been made yet.
-    def sidebar_index
-      session[:sidebar_index] || current_route_index
-    end
-
-    def sidebar_routes
-      application.routes.all
-    end
-
-    def current_route?(candidate)
-      return candidate.controller_class == self.class && candidate.action == :show unless route
-
-      candidate.path == route.path &&
-        candidate.controller_class == route.controller_class &&
-        candidate.action == route.action
-    end
-
     private
 
-    # Finds the position of this controller among all registered routes (for sidebar highlighting).
-    # Returns 0 if no matching route is found.
-    def current_route_index
-      sidebar_routes.index { |candidate| current_route?(candidate) } || 0
-    end
-
-    # Checks whether the given slot is registered as a focus ring slot for this controller.
-    def focus_ring_slot?(slot)
-      self.class.focus_ring_slots.include?(slot)
-    end
-
     attr_reader :response
-
-    # Renders `body` as a string: calls `#render` if body responds to it (component), otherwise `#to_s`.
-    def render_body(body)
-      body.respond_to?(:render) ? body.render.to_s : body.to_s
-    end
-
-    # Wraps `body` rendering in this controller's layout (if one is defined).
-    # If no layout is set, returns body as-is. Provides content, screen, and controller to the layout for composition.
-    def render_with_layout(body)
-      rendered = render_body(body)
-      layout = self.class.layout
-      return rendered unless layout
-
-      render_body(layout_body(layout, body, rendered))
-    end
-
-    def layout_body(layout, body, rendered)
-      assigns = layout_assigns(body, rendered)
-      return template_body(layout, **assigns) if layout.is_a?(String) || layout.is_a?(Symbol)
-
-      layout.new(**assigns)
-    end
-
-    # Provides view assigns for layout rendering: merges body-specific assigns with standard `content`, `screen`, and `controller`.
-    def layout_assigns(body, rendered)
-      view_assigns(body).merge(content: rendered, screen: screen, controller: self, theme: theme)
-    end
-
-    # Extracts layout assigns from the body if it responds to `#layout_assigns` (e.g., a component),
-    # otherwise returns an empty hash. Used by layout rendering for composition.
-    def view_assigns(body)
-      body.respond_to?(:layout_assigns) ? body.layout_assigns : {}
-    end
-
-    def template_body(name, **assigns)
-      Presentation::TemplateView.new(template: resolve_template(name), namespace: template_namespace, **template_assigns(assigns))
-    end
-
-    def resolve_template(name)
-      Presentation::Templates.resolve(name, root: application.class.root)
-    end
-
-    def template_assigns(assigns)
-      {screen: screen, controller: self, theme: theme}.merge(assigns)
-    end
-
-    def template_namespace
-      namespace_name = application.class.namespace
-      return nil if namespace_name.to_s.empty?
-
-      Object.const_get(namespace_name)
-    end
-
-    def default_template_name(action)
-      "#{controller_template_path}/#{action}"
-    end
-
-    def controller_template_path
-      underscore(self.class.name.split("::").last.delete_suffix("Controller"))
-    end
-
-    def underscore(value)
-      value
-        .gsub(/([A-Z]+)([A-Z][a-z])/, "\\1_\\2")
-        .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
-        .tr("-", "_")
-        .downcase
-    end
-
-    # Extracts the normalized key from the current event, handling both KeyEvent objects and raw key strings.
-    # Delegates to `Charming.key_of(event)` for event-to-key resolution.
-    def key_name
-      Charming.key_of(event)
-    end
-
-    # Dispatches a key event to the currently focused component (e.g., text input, list) by calling `#handle_key` on it.
-    # Returns nil if no focused component or no handler consumed the key, otherwise :handled.
-    def dispatch_to_focused_component
-      slot = focus.current
-      return nil unless slot && respond_to?(slot, true)
-
-      component = send(slot)
-      return nil unless component.respond_to?(:handle_key)
-
-      result = component.handle_key(event)
-      return nil if result.nil?
-
-      dispatch_component_result(slot, result)
-      :handled
-    end
-
-    def dispatch_component_result(slot, result)
-      action, arguments = component_result_action(slot, result)
-      action ? send(action, *arguments) : render_default_action
-      render_default_action unless response
-    end
-
-    def component_result_action(slot, result)
-      case result
-      when :cancelled
-        component_action(slot, :cancelled)
-      when Array
-        component_array_action(slot, result)
-      end
-    end
-
-    def component_array_action(slot, result)
-      event_name, value = result
-      return component_action(slot, :submitted, value) if event_name == :submitted
-      return component_action(slot, :selected, value) if event_name == :selected
-
-      nil
-    end
-
-    def component_action(slot, suffix, *arguments)
-      action = :"#{slot}_#{suffix}"
-      return unless respond_to?(action, true)
-
-      [action, arguments]
-    end
-
-    # Handles Tab/Shift-Tab traversal: moves focus forward or backward through the focus ring.
-    # Only processes events that are actually Tab keypresses on an empty focus ring. Returns :handled when consumed.
-    def dispatch_tab_traversal
-      return nil unless key_name == :tab
-      return nil if focus.ring.empty?
-
-      focus.cycle(event.shift ? -1 : +1)
-      render_default_action
-      :handled
-    end
-
-    # Dispatches key events to an open command palette (fuzzy search). Handles cancellation (Escape),
-    # command execution when a selection is made, and renders the default action if no response was produced.
-    def dispatch_command_palette_key
-      palette = command_palette
-      result = palette.handle_key(event)
-
-      if result == :cancelled
-        close_command_palette
-      elsif selected_command?(result)
-        perform_command(result.last)
-      else
-        save_command_palette_state(palette)
-        render_default_action unless response
-      end
-
-      response
-    end
-
-    # Mouse event handler for an open command palette. No-op — the command palette handles mouse internally.
-    def dispatch_command_palette_mouse
-      nil
-    end
-
-    # Dispatches keys within sidebar navigation: j/k or down/up move selection, Enter selects and navigates,
-    # Escape/Tab shifts focus to content. Other keys are ignored while sidebar owns focus.
-    def dispatch_sidebar_key
-      case key_name
-      when :j, :down then sidebar_move(+1)
-      when :k, :up then sidebar_move(-1)
-      when :enter then sidebar_select
-      when :escape, :tab then focus_content
-      else render_default_action
-      end
-      response
-    end
-
-    # Mouse event handler for the base controller. No-op — mouse events bubble through to focused components instead.
-    def dispatch_component_mouse
-      nil
-    end
-
-    # Moves sidebar selection up or down by `delta`. Does nothing if there are no routes.
-    def sidebar_move(delta)
-      count = sidebar_routes.length
-      return render_default_action if count.zero?
-
-      session[:sidebar_index] = (sidebar_index + delta).clamp(0, count - 1)
-      render_default_action
-    end
-
-    # Selects the currently highlighted sidebar route and navigates to it — shifting focus to content area.
-    # If no route is found at the current index, falls back to default action.
-    def sidebar_select
-      route = sidebar_routes[sidebar_index]
-      if focus_ring_slot?(:content)
-        focus.focus(:content)
-      else
-        session[:focus] = :content
-      end
-      route ? navigate_to(route.path) : render_default_action
-    end
-
-    def build_command_palette_from_state(state)
-      case state.fetch(:type)
-      when :commands
-        build_command_palette_with_state(self.class.command_bindings, state, height: 6)
-      when :themes
-        build_command_palette_with_state(theme_commands, state, placeholder: "Search themes", height: 10)
-      end
-    end
-
-    def build_command_palette_with_state(commands, state, placeholder: "Search commands", height: nil)
-      Presentation::Components::CommandPalette.new(
-        commands: commands,
-        placeholder: placeholder,
-        height: height,
-        value: state.fetch(:value),
-        cursor: state.fetch(:cursor),
-        selected_index: state.fetch(:selected_index),
-        theme: theme
-      )
-    end
-
-    def command_palette_state(type)
-      {type: type, value: "", cursor: 0, selected_index: 0}
-    end
-
-    def save_command_palette_state(palette)
-      session[:command_palette] = session.fetch(:command_palette).merge(palette.state)
-    end
-
-    # Checks if a command palette result indicates a selected command (as opposed to cancel or no-op).
-    def selected_command?(result)
-      result.is_a?(Array) && result.first == :selected
-    end
-
-    # Executes a command value — either a callable block (inline command) or a method name (bound action).
-    # Pops the command palette scope and re-renders unless the result is navigation or quit.
-    def perform_command(command)
-      current_palette_state = session[:command_palette]
-      pop_command_palette_scope
-      perform_command_value(command.value)
-      if command.value != :quit && session[:command_palette].equal?(current_palette_state)
-        session.delete(:command_palette)
-      end
-      render_default_action unless response&.navigate? || response&.quit?
-    end
-
-    def theme_commands
-      application.class.themes.keys.map do |name|
-        Presentation::Components::CommandPalette::Command.new(label: theme_label(name), value: -> { use_theme(name) })
-      end
-    end
-
-    def theme_label(name)
-      name.to_s.tr("_", "-").split("-").map(&:capitalize).join(" ")
-    end
-
-    # Pops the command palette scope from the focus ring until it is no longer the topmost scope.
-    # Called when a command executes or is cancelled.
-    def pop_command_palette_scope
-      focus.pop_scope while focus.ring == [:command_palette]
-    end
-
-    # Executes a command value — either calling a callable (inline block) or sending a method name to self.
-    # Used for both inline commands and bound action methods from the palette.
-    def perform_command_value(value)
-      value.respond_to?(:call) ? instance_exec(&value) : send(value)
-    end
-
-    # Renders the default action if this controller defines it. Called after navigation, command execution,
-    # or key handling when no explicit response was produced — ensures the view stays rendered.
-    def render_default_action
-      action = self.class.auto_render_action || :show
-      public_send(action) if respond_to?(action)
-    end
-
-    def auto_render_after?(action)
-      auto_render_action = self.class.auto_render_action
-      auto_render_action && action.to_sym != auto_render_action
-    end
-
-    def global_key_action
-      key_action_for_scope(:global)
-    end
-
-    def content_key_action
-      return nil unless content_key_scope_active?
-
-      key_action_for_scope(:content)
-    end
-
-    def content_key_scope_active?
-      return content_focused? if focus_ring_slot?(:content)
-
-      true
-    end
-
-    def key_action_for_scope(scope)
-      action = self.class.key_bindings[key_name]
-      return nil unless action
-      return nil unless self.class.key_binding_scopes.fetch(key_name, :content) == scope
-
-      action
-    end
   end
 end