charming 0.1.0 → 0.1.2

data/lib/charming/controller/class_methods.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # DSL for declaring controller-level event bindings and configuration: keys, commands,
+    # timers, task handlers, the auto-rendered action, layout wrapper, and focus ring.
+    # Mixed into Controller as class methods; also exposed for tests and shared base controllers.
+    module ClassMethods
+      # Binds a key press to a controller action. *name* is the normalized key symbol (e.g., "up",
+      # "q", "ctrl+c"). *scope* is :content (default) for content-pane keys or :global for app-wide
+      # shortcuts that fire regardless of focus. Raises ArgumentError for any other scope.
+      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
+
+      # Adds a CommandPalette entry with the given *label*. *action* is a method name to send on
+      # the controller, or a block to instance_exec when selected.
+      def command(label, action = nil, &block)
+        command_bindings << Presentation::Components::CommandPalette::Command.new(label: label, value: block || action)
+      end
+
+      # Declares a timer that fires every *every* seconds and dispatches *action* on the controller.
+      # The runtime builds a TimerEvent and routes it to the active controller's dispatch_timer.
+      def timer(name, every:, action:)
+        timer_bindings[name.to_sym] = TimerBinding.new(name: name.to_sym, interval: every, action: action)
+      end
+
+      # Declares a task handler for async work submitted via `run_task(:name)`. When the task emits
+      # a TaskEvent with the matching name, the runtime dispatches *action* on the controller.
+      def on_task(name, action:)
+        task_bindings[name.to_sym] = TaskBinding.new(name: name.to_sym, action: action)
+      end
+
+      # Sets the action that the controller should auto-render after a non-rendering action runs.
+      # Defaults to :show when unset.
+      def auto_render(action = :show)
+        @auto_render_action = action.to_sym
+      end
+
+      # Returns the configured auto-render action, walking the superclass chain when undefined locally.
+      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 or returns the controller's layout. Pass a layout class (instantiated per request),
+      # a String/Symbol template name (resolved through Presentation::Templates), or `false` to
+      # disable inherited layout wrapping. Called with no arguments returns the resolved layout.
+      def layout(layout_class = :__charming_layout_reader__)
+        return resolved_layout if layout_class == :__charming_layout_reader__
+
+        @layout = layout_class
+      end
+
+      # Hash of registered key bindings (symbol key name => action method name), inherited from
+      # superclass controllers.
+      def key_bindings
+        @key_bindings ||= superclass.respond_to?(:key_bindings) ? superclass.key_bindings.dup : {}
+      end
+
+      # Hash of key scopes paralleling `key_bindings` (symbol key name => :content or :global).
+      def key_binding_scopes
+        @key_binding_scopes ||= superclass.respond_to?(:key_binding_scopes) ? superclass.key_binding_scopes.dup : {}
+      end
+
+      # Defines the named focus slots cycled by Tab/Shift+Tab traversal.
+      def focus_ring(*slots)
+        @focus_ring_slots = slots
+      end
+
+      # Returns the focus ring slots, inherited from superclass when undefined.
+      def focus_ring_slots
+        @focus_ring_slots ||= superclass.respond_to?(:focus_ring_slots) ? superclass.focus_ring_slots.dup : []
+      end
+
+      # Array of registered command palette entries, inherited from superclass when undefined.
+      def command_bindings
+        @command_bindings ||= superclass.respond_to?(:command_bindings) ? superclass.command_bindings.dup : []
+      end
+
+      # Hash of timer name => TimerBinding, inherited from superclass when undefined.
+      def timer_bindings
+        @timer_bindings ||= superclass.respond_to?(:timer_bindings) ? superclass.timer_bindings.dup : {}
+      end
+
+      # Hash of task name => TaskBinding, inherited from superclass when undefined.
+      def task_bindings
+        @task_bindings ||= superclass.respond_to?(:task_bindings) ? superclass.task_bindings.dup : {}
+      end
+
+      private
+
+      # Validates that *scope* is :content or :global; otherwise raises ArgumentError.
+      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
+
+      # Walks the superclass chain to find a configured layout, returning nil if none is set.
+      def resolved_layout
+        return @layout if instance_variable_defined?(:@layout)
+        return superclass.layout if superclass.respond_to?(:layout)
+
+        nil
+      end
+    end
+  end
+end

data/lib/charming/controller/command_palette.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Command palette helpers mixed into Controller. Opens/closes the palette, builds the
+    # palette from registered command bindings or theme list, and routes key/mouse events
+    # through it. Supports both the standard command palette (:commands) and the theme picker
+    # (:themes) via a discriminated `session[:command_palette]` state hash.
+    module CommandPalette
+      # Opens the command palette populated with the controller's `command_bindings`. Pushes
+      # a focus scope so subsequent keys are routed to the palette.
+      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, pops its focus scope, and renders the current action.
+      def close_command_palette
+        session.delete(:command_palette)
+        pop_command_palette_scope
+        render_default_action
+      end
+
+      # True when either the command palette or theme picker is currently open.
+      def command_palette_open?
+        session.key?(:command_palette)
+      end
+
+      # Returns the active CommandPalette component, or nil when the palette is closed.
+      def command_palette
+        build_command_palette_from_state(session[:command_palette]) if command_palette_open?
+      end
+
+      private
+
+      # Routes the current key event to the open palette. Cancels on Escape, performs the
+      # selected command on Enter, otherwise persists the palette's state and re-renders.
+      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 dispatch for the command palette. Reserved for future use; returns nil.
+      def dispatch_command_palette_mouse
+        nil
+      end
+
+      # Builds a CommandPalette component from the persisted palette *state* hash, dispatching
+      # to command-list or theme-list construction based on the state's `:type`.
+      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
+
+      # Constructs the CommandPalette widget with a *commands* list and persisted *state* hash.
+      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
+
+      # Initial palette state hash used when opening either palette type.
+      def command_palette_state(type)
+        {type: type, value: "", cursor: 0, selected_index: 0}
+      end
+
+      # Merges the in-memory palette's state back into the session hash so the search query,
+      # cursor, and selected index survive across renders.
+      def save_command_palette_state(palette)
+        session[:command_palette] = session.fetch(:command_palette).merge(palette.state)
+      end
+
+      # True when a component result is the `[:selected, command]` array shape.
+      def selected_command?(result)
+        result.is_a?(Array) && result.first == :selected
+      end
+
+      # Invokes the value (proc, lambda, or method symbol) of the selected *command*, then
+      # closes the palette unless the command was :quit or the user has re-opened it.
+      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
+
+      # Returns the theme-switching commands used by the theme picker palette.
+      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
+
+      # Converts a theme name symbol (e.g., :dracula_dark) to a human-readable label ("Dracula Dark").
+      def theme_label(name)
+        name.to_s.tr("_", "-").split("-").map(&:capitalize).join(" ")
+      end
+
+      # Pops focus scopes while the top of the stack is the command palette.
+      def pop_command_palette_scope
+        focus.pop_scope while focus.ring == [:command_palette]
+      end
+
+      # Invokes a palette command *value* — a proc gets instance_exec'd on self, a symbol gets sent.
+      def perform_command_value(value)
+        value.respond_to?(:call) ? instance_exec(&value) : send(value)
+      end
+    end
+  end
+end

data/lib/charming/controller/component_dispatching.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Component-dispatch helpers mixed into Controller. Forwards key events to the currently
+    # focused component (the slot returned by `focus.current`) and translates component return
+    # values into controller hook calls (e.g., `slot_submitted`, `slot_selected`, `slot_cancelled`).
+    module ComponentDispatching
+      private
+
+      # Sends the current key event to the focused component (if it responds to `handle_key`).
+      # Returns `:handled` after dispatching, or nil when no component is focused.
+      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
+
+      # Translates a component `handle_key` *result* into a controller hook call. `:cancelled`
+      # triggers `<slot>_cancelled`, `[:submitted, value]` triggers `<slot>_submitted(value)`,
+      # `[:selected, value]` triggers `<slot>_selected(value)`. Falls back to a default render
+      # when no matching hook exists.
+      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
+
+      # Resolves which controller hook (if any) corresponds to the *result* from a component.
+      def component_result_action(slot, result)
+        case result
+        when :cancelled
+          component_action(slot, :cancelled)
+        when Array
+          component_array_action(slot, result)
+        end
+      end
+
+      # Handles array-shaped component results, currently `[:submitted, value]` and `[:selected, value]`.
+      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
+
+      # Returns `[action, arguments]` for the `<slot>_<suffix>` controller hook if defined, or nil.
+      def component_action(slot, suffix, *arguments)
+        action = :"#{slot}_#{suffix}"
+        return unless respond_to?(action, true)
+
+        [action, arguments]
+      end
+
+      # Handles Tab/Shift+Tab by cycling through the focus ring. Returns :handled after rendering.
+      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
+
+      # Default mouse dispatch hook: subclasses/components may override by including their own
+      # mouse logic via the controller's `dispatch_component_mouse` override.
+      def dispatch_component_mouse
+        nil
+      end
+    end
+  end
+end

data/lib/charming/controller/dispatching.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Key-dispatch helpers mixed into Controller. Resolves the current event's key symbol and
+    # looks up bindings by scope (content vs. global) before they are sent to controller actions.
+    module Dispatching
+      private
+
+      # Returns the normalized key symbol for the current controller event.
+      def key_name
+        Charming.key_of(event)
+      end
+
+      # Calls the auto-render action if one is configured. No-op when the action method is undefined.
+      def render_default_action
+        action = self.class.auto_render_action || :show
+        public_send(action) if respond_to?(action)
+      end
+
+      # True when an explicit auto-render action is configured and the just-completed *action* is
+      # not itself the auto-render action (to avoid infinite loops).
+      def auto_render_after?(action)
+        auto_render_action = self.class.auto_render_action
+        auto_render_action && action.to_sym != auto_render_action
+      end
+
+      # Returns the action method bound to the current key at :global scope, or nil if none.
+      def global_key_action
+        key_action_for_scope(:global)
+      end
+
+      # Returns the action method bound to the current key at :content scope, or nil if the
+      # content scope is not active (e.g., sidebar has focus).
+      def content_key_action
+        return nil unless content_key_scope_active?
+
+        key_action_for_scope(:content)
+      end
+
+      # Returns false when the controller declared a content focus ring slot and the sidebar
+      # is currently focused. Otherwise true (the default behavior for non-declarative controllers).
+      def content_key_scope_active?
+        return content_focused? if focus_ring_slot?(:content)
+
+        true
+      end
+
+      # Looks up the current key in the class bindings and returns the action only if its
+      # registered scope matches *scope*. Returns nil otherwise.
+      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
+end

data/lib/charming/controller/focus_management.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Focus helpers mixed into Controller: lazily-allocated per-controller Focus object and
+    # predicates for `focused?(:slot)` checks from views. The Focus object is keyed by controller
+    # class name in the session, so it survives across controller dispatches for the same class.
+    module FocusManagement
+      # Returns the per-controller Focus object, defining the focus ring from class-level DSL
+      # 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
+
+      # Returns true when the named *slot* is the currently focused slot in this controller's focus ring.
+      def focused?(slot)
+        focus.focused?(slot)
+      end
+
+      private
+
+      # True when the controller class declared *slot* as part of its focus_ring DSL.
+      def focus_ring_slot?(slot)
+        self.class.focus_ring_slots.include?(slot)
+      end
+    end
+  end
+end

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