charming 0.1.1 → 0.1.2

data/lib/charming/controller/rendering.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Rendering pipeline mixed into Controller. Resolves view classes, template paths, layouts,
+    # and assigns. Most helpers are private — only `render`/`render_view`/`render_template` are
+    # part of the public controller API and live in `controller.rb` itself.
+    module Rendering
+      private
+
+      # Returns the string body for *body* — if it responds to `render` (e.g., a View or Component),
+      # delegates to that; otherwise calls `to_s`.
+      def render_body(body)
+        body.respond_to?(:render) ? body.render.to_s : body.to_s
+      end
+
+      # Wraps *body* (a string) in the controller's configured layout, if any. When no layout is set
+      # the body is returned as-is.
+      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
+
+      # Builds the layout wrapper for *body* / *rendered* content. String/Symbol layouts are
+      # resolved as templates; other values are treated as layout view classes.
+      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
+
+      # Returns a view object for *name* — a conventional view class when one exists under the
+      # application namespace, otherwise a TemplateView rendered from `app/views`.
+      def view_body(name, **assigns)
+        view_class = conventional_view_class(name)
+        return view_class.new(**template_assigns(assigns)) if view_class
+
+        template_body(name, **assigns)
+      end
+
+      # Builds the assigns hash passed to layout view constructors: view's own assigns, plus
+      # `content:`, `screen:`, `controller:`, and `theme:`.
+      def layout_assigns(body, rendered)
+        view_assigns(body).merge(content: rendered, screen: screen, controller: self, theme: theme)
+      end
+
+      # Returns the assigns hash from *body* (a View), or an empty hash when *body* doesn't expose them.
+      def view_assigns(body)
+        body.respond_to?(:layout_assigns) ? body.layout_assigns : {}
+      end
+
+      # Resolves a template by *name* and returns a TemplateView bound to the application's namespace.
+      def template_body(name, **assigns)
+        Presentation::TemplateView.new(template: resolve_template(name), namespace: template_namespace, **template_assigns(assigns))
+      end
+
+      # Looks up the template file under `app/views` relative to the application root.
+      def resolve_template(name)
+        Presentation::Templates.resolve(name, root: application.class.root)
+      end
+
+      # Returns the assigns hash passed to templates: `screen:`, `controller:`, `theme:` plus user *assigns*.
+      def template_assigns(assigns)
+        {screen: screen, controller: self, theme: theme}.merge(assigns)
+      end
+
+      # Returns the application namespace constant (e.g., `MyApp`) used for view-class lookup,
+      # or nil when the application has no namespace.
+      def template_namespace
+        namespace_name = application.class.namespace
+        return nil if namespace_name.to_s.empty?
+
+        Object.const_get(namespace_name)
+      end
+
+      # Returns the conventional view class for *name* (e.g., `MyApp::Home::ShowView`) when defined
+      # under the application namespace. Returns nil when no such class exists.
+      def conventional_view_class(name)
+        namespace = template_namespace
+        return unless namespace
+
+        constant_path = conventional_view_constant_path(name)
+        constant_path.reduce(namespace) do |scope, constant_name|
+          break unless scope.const_defined?(constant_name, false)
+
+          scope.const_get(constant_name, false)
+        end
+      end
+
+      # Builds the constant lookup path (array of strings) for a conventional view class from *name*.
+      # Splits "home/show" → ["Home", "ShowView"].
+      def conventional_view_constant_path(name)
+        parts = name.to_s.split("/")
+        action = parts.pop
+        parts.map { |part| camelize(part) } + ["#{camelize(action)}View"]
+      end
+
+      # Converts a snake_case string to CamelCase. Used to build conventional view constant names.
+      def camelize(value)
+        value.to_s.split("_").map(&:capitalize).join
+      end
+
+      # Returns the default template path for a given *action* (e.g., "home/show" for HomeController#show).
+      def default_template_name(action)
+        "#{controller_template_path}/#{action}"
+      end
+
+      # Returns the underscored controller path (e.g., "home" for HomeController) used for view lookup.
+      def controller_template_path
+        underscore(self.class.name.split("::").last.delete_suffix("Controller"))
+      end
+
+      # Converts CamelCase to snake_case.
+      def underscore(value)
+        value
+          .gsub(/([A-Z]+)([A-Z][a-z])/, "\\1_\\2")
+          .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+          .tr("-", "_")
+          .downcase
+      end
+    end
+  end
+end

data/lib/charming/controller/session_state.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Session-state helpers mixed into Controller: accessing the application session hash, lazy
+    # state-object lookup by name/class, form builder invocation, and async task submission.
+    module SessionState
+      # Returns the application session hash for this controller. All persistent state (focus,
+      # sidebar index, command palette, user state objects) lives here.
+      def session
+        application.session
+      end
+
+      # Returns the named session-backed state object, creating it on first access. *name* is a
+      # symbol key under `session[:states]`. *state_class* is an ApplicationState subclass whose
+      # constructor receives *attributes* on first creation. Subsequent calls return the same object.
+      def state(name, state_class, **attributes)
+        session[:states] ||= {}
+        session[:states][name.to_sym] ||= state_class.new(**attributes)
+      end
+
+      # Builds a Form component scoped to the named form slot in `session[:forms]`. The block is
+      # evaluated against a Form::Builder (or invoked with the builder as its argument for arity-1 blocks)
+      # and returns a Form component pre-bound to the per-form mutable state hash.
+      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 a background task with the given *name*. The block is executed by the configured
+      # task executor; its return value (or any raised exception) is delivered to the controller
+      # as a TaskEvent dispatched to the matching `on_task` handler.
+      def run_task(name, &block)
+        application.task_executor.submit(name, &block)
+      end
+    end
+  end
+end

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