charming 0.1.0 → 0.1.2

data/lib/charming/controller/sidebar_navigation.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Sidebar-navigation helpers mixed into Controller. Tracks the sidebar's current route index,
+    # routes j/k/enter/tab keys when the sidebar is focused, and exposes `sidebar_focused?` for views.
+    module SidebarNavigation
+      # Moves focus to the sidebar. When the controller declared a focus ring, the focus object
+      # is updated; otherwise a fallback session key tracks focus.
+      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
+
+      # Moves focus to the content pane (the inverse of `focus_sidebar`).
+      def focus_content
+        if focus_ring_slot?(:content)
+          focus.focus(:content)
+        else
+          session[:focus] = :content
+        end
+        render_default_action
+      end
+
+      # True when the sidebar is the current focus target. Uses the focus ring when defined.
+      def sidebar_focused?
+        return focused?(:sidebar) if focus_ring_slot?(:sidebar)
+
+        session[:focus] == :sidebar
+      end
+
+      # True when the content pane is the current focus target. Uses the focus ring when defined.
+      def content_focused?
+        return focused?(:content) if focus_ring_slot?(:content)
+
+        session[:focus] == :content
+      end
+
+      # Returns the index of the currently selected route in `sidebar_routes`, defaulting to the
+      # active route when the session index is unset.
+      def sidebar_index
+        session[:sidebar_index] || current_route_index
+      end
+
+      # Returns all routes from the application's router, in registration order.
+      def sidebar_routes
+        application.routes.all
+      end
+
+      # True when *candidate* route matches the controller's currently active route (used to
+      # highlight the current row in the sidebar).
+      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
+
+      # Returns the index of the route that matches `current_route?`, defaulting to 0.
+      def current_route_index
+        sidebar_routes.index { |candidate| current_route?(candidate) } || 0
+      end
+
+      # Dispatches j/k/enter/tab/escape to sidebar movement and selection; falls through to
+      # a default render for any other key.
+      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 dispatch for the sidebar. Reserved for future use; returns nil.
+      def dispatch_sidebar_mouse
+        nil
+      end
+
+      # Moves the sidebar cursor by *delta* positions, clamped to the route list bounds.
+      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 route currently highlighted in the sidebar and navigates to it.
+      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
+    end
+  end
+end

data/lib/charming/controller.rb

@@ -8,178 +8,103 @@ 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 << 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
-
-      # 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
-
-    attr_reader :application, :event, :params, :screen
-
-    # 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.
-    def initialize(application:, event: nil, params: {}, screen: nil)
+    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 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
       @params = params
       @screen = screen || Screen.new(width: 80, height: 24)
+      @route = route
       @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 `body` wrapped in this controller's layout (if one is defined) and stores the response.
-    # If no layout is set, renders body bare. Called by controllers after rendering a view.
-    def render(body = "")
+    # Renders a body or template wrapped in the controller's layout.
+    def render(body = "", **assigns)
+      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
@@ -189,335 +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 model class and caches it in the session under `:models`.
-    # Subsequent calls with the same name return the cached instance. Used like: model(:user, UserModel)
-    def model(name, model_class, **attributes)
-      session[:models] ||= {}
-      session[:models][name.to_sym] ||= model_class.new(**attributes)
-    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
-
     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
-      application.routes.all.index { |route| route.controller_class == self.class && route.action == :show } || 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 class (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_class = self.class.layout
-      return rendered unless layout_class
-
-      render_body(layout_class.new(**layout_assigns(body, rendered)))
-    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
-
-    # 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?
-
-      render_default_action
-      :handled
-    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 = application.routes.all.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 = application.routes.all[sidebar_index]
-      session[:focus] = :content
-      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)
-      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|
-        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 `:show` 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
-      show if respond_to?(:show)
-    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