charming 0.2.0 → 0.2.2

data/lib/charming/controller/dispatching.rb

@@ -12,6 +12,11 @@ module Charming
         Charming.key_of(event)
       end
 
+      # Returns the normalized key signature for controller-declared bindings.
+      def binding_key_name
+        Charming.key_signature(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
@@ -38,10 +43,11 @@ module Charming
         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).
+      # Returns false when the focus ring includes a content slot that isn't currently
+      # focused (e.g., the sidebar has focus). Controllers whose ring has no :content slot
+      # always have content keys active.
       def content_key_scope_active?
-        return content_focused? if focus_ring_slot?(:content)
+        return content_focused? if focus.ring.include?(:content)
 
         true
       end
@@ -49,12 +55,32 @@ module Charming
       # 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]
+        action = self.class.key_bindings[binding_key_name]
         return nil unless action
-        return nil unless self.class.key_binding_scopes.fetch(key_name, :content) == scope
+        return nil unless self.class.key_binding_scopes.fetch(binding_key_name, :content) == scope
 
         action
       end
+
+      # True when the current event is a plain printable character: a single
+      # non-control char with no ctrl/alt modifier (ctrl+p etc. stay shortcuts).
+      def printable_text_event?
+        return false unless event.respond_to?(:char) && event.char
+        return false if event.respond_to?(:ctrl) && event.ctrl
+        return false if event.respond_to?(:alt) && event.alt
+
+        event.char.length == 1 && !event.char.match?(/[[:cntrl:]]/)
+      end
+
+      # True when the focus ring's current slot resolves to a component that accepts
+      # free-typed text (see Component#captures_text?).
+      def focused_component_captures_text?
+        slot = focus.current
+        return false unless slot && respond_to?(slot, true)
+
+        component = send(slot)
+        component.respond_to?(:captures_text?) && component.captures_text?
+      end
     end
   end
 end

data/lib/charming/controller/focus.rb

@@ -83,6 +83,15 @@ module Charming
         current == slot
       end
 
+      # True when the topmost scope is an overlay (modal, command palette, or any
+      # pushed scope) rather than the structural ring/layout. While an overlay scope
+      # is active, the controller routes keys to the focused component instead of
+      # content/sidebar key bindings.
+      def overlay?
+        scope = top
+        !!scope && !%i[ring layout].include?(scope[:origin])
+      end
+
       private
 
       # Returns the topmost scope hash (the last entry pushed onto `@state[:scopes]`).

data/lib/charming/controller/focus_management.rb

@@ -18,13 +18,6 @@ module Charming
       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/key_dispatch.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # KeyDispatch resolves which handler claims a key event — the capture/bubble
+    # ladder a browser would own in a web MVC app. Priority order:
+    #
+    # 1. Command palette (when open) consumes everything.
+    # 2. A focused text-capturing component (TextInput, TextArea, Form, …) gets
+    #    printable characters BEFORE key bindings — typing "q" into a field must
+    #    insert a q, not quit the app.
+    # 3. Global key bindings.
+    # 4. An overlay focus scope (a pushed modal) captures all remaining keys.
+    # 5. Sidebar keys (when focused), content bindings, then the focused component —
+    #    which sees Tab before ring traversal so forms can do field navigation.
+    #
+    # Tiers differ in how they terminate: the palette, overlay, sidebar, and binding
+    # tiers consume the key outright once their condition holds, while the component
+    # tiers only consume it when the component reports :handled and otherwise let it
+    # fall through to the next tier.
+    class KeyDispatch
+      def initialize(controller)
+        @controller = controller
+      end
+
+      # Runs the ladder for the controller's current event. Returns the winning
+      # tier's response, or nil when no tier claims the key.
+      def call
+        return palette_response if palette_open?
+        return response if typed_text_claimed?
+        return binding_response(global_action) if global_action
+        return overlay_response if overlay?
+        return sidebar_response if sidebar_focused?
+        return binding_response(content_action) if content_action
+        return response if component_or_ring_claimed?
+
+        nil
+      end
+
+      private
+
+      attr_reader :controller
+
+      def palette_open?
+        controller.command_palette_open?
+      end
+
+      def palette_response
+        controller.send(:dispatch_command_palette_key)
+      end
+
+      # True when a printable character was typed into a focused text-capturing
+      # component and the component consumed it.
+      def typed_text_claimed?
+        controller.send(:printable_text_event?) &&
+          controller.send(:focused_component_captures_text?) &&
+          component_claimed?
+      end
+
+      def global_action
+        controller.send(:global_key_action)
+      end
+
+      def content_action
+        controller.send(:content_key_action)
+      end
+
+      def binding_response(action)
+        controller.dispatch(action)
+      end
+
+      def overlay?
+        controller.focus.overlay?
+      end
+
+      # An overlay consumes the key whether or not the component handled it.
+      def overlay_response
+        controller.send(:dispatch_to_focused_component)
+        response
+      end
+
+      def sidebar_focused?
+        controller.sidebar_focused?
+      end
+
+      def sidebar_response
+        controller.send(:dispatch_sidebar_key)
+      end
+
+      # Text-capturing components own their remaining keys — Tab included, so forms
+      # do field navigation. Everything else keeps ring traversal ahead of the component.
+      def component_or_ring_claimed?
+        if controller.send(:focused_component_captures_text?)
+          component_claimed? || ring_claimed?
+        else
+          ring_claimed? || component_claimed?
+        end
+      end
+
+      def component_claimed?
+        controller.send(:dispatch_to_focused_component) == :handled
+      end
+
+      def ring_claimed?
+        controller.send(:dispatch_tab_traversal) == :handled
+      end
+
+      def response
+        controller.send(:response)
+      end
+    end
+  end
+end

data/lib/charming/controller/session_state.rb

@@ -30,6 +30,17 @@ module Charming
         session[:states][name.to_sym] ||= state_class.new(**attributes)
       end
 
+      # Returns the named mutable widget-state hash stored under `session[:component_state]`,
+      # seeding it from *defaults* on first access. This is the blessed way to keep an interactive
+      # component's state across ephemeral controller instances: store only JSON-safe primitives,
+      # rebuild the component from the hash each event, and write changed values back after
+      # `handle_key`. (Live component objects don't belong in the session — `save_session` drops
+      # anything that can't survive a JSON round-trip.)
+      def component_state(name, **defaults)
+        session[:component_state] ||= {}
+        session[:component_state][name.to_sym] ||= defaults
+      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.
@@ -44,9 +55,24 @@ module Charming
       # 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)
+      #
+      # Blocks that accept an argument receive a Tasks::Progress reporter whose `report`
+      # calls dispatch the matching `on_task_progress` handler. *timeout:* (seconds)
+      # cancels the task with Tasks::Cancelled when exceeded.
+      def run_task(name, timeout: nil, &block)
+        return application.task_executor.submit(name, timeout: timeout, &block) if timeout
+
+        # Without a timeout, use the plain signature so simple custom executors
+        # (`def submit(name, &block)`) remain compatible.
         application.task_executor.submit(name, &block)
       end
+
+      # Cancels the named in-flight background task (raises Tasks::Cancelled inside it).
+      # No-op when the task already finished or the executor doesn't support cancellation.
+      def cancel_task(name)
+        executor = application.task_executor
+        executor.cancel(name) if executor.respond_to?(:cancel)
+      end
     end
   end
 end

data/lib/charming/controller/sidebar_navigation.rb

@@ -4,41 +4,36 @@ 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.
+    #
+    # Sidebar/content focus is driven entirely by the controller's Focus object. Controllers
+    # that want Tab-driven sidebar navigation declare `focus_ring :sidebar, :content` (generated
+    # apps do); without those slots in the ring, `focus_sidebar`/`focus_content` are no-ops.
     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.
+      # Moves focus to the sidebar slot and remembers the highlighted route.
       def focus_sidebar
-        if focus_ring_slot?(:sidebar)
-          focus.focus(:sidebar)
-        else
-          session[:focus] = :sidebar
-        end
+        focus.focus(:sidebar)
         session[:sidebar_index] ||= current_route_index
         render_default_action
       end
 
-      # Moves focus to the content pane (the inverse of `focus_sidebar`).
+      # Moves focus to the content side (the inverse of `focus_sidebar`). "Content" is
+      # the :content slot when the ring declares one, otherwise the first non-sidebar
+      # slot — so `focus_ring :sidebar, :entries` works without a literal :content.
       def focus_content
-        if focus_ring_slot?(:content)
-          focus.focus(:content)
-        else
-          session[:focus] = :content
-        end
+        slot = content_slot
+        focus.focus(slot) if slot
         render_default_action
       end
 
-      # True when the sidebar is the current focus target. Uses the focus ring when defined.
+      # True when the sidebar slot is the current focus target.
       def sidebar_focused?
-        return focused?(:sidebar) if focus_ring_slot?(:sidebar)
-
-        session[:focus] == :sidebar
+        focused?(:sidebar)
       end
 
-      # True when the content pane is the current focus target. Uses the focus ring when defined.
+      # True when focus is on the content side: any current slot other than :sidebar.
       def content_focused?
-        return focused?(:content) if focus_ring_slot?(:content)
-
-        session[:focus] == :content
+        current = focus.current
+        !current.nil? && current != :sidebar
       end
 
       # Returns the index of the currently selected route in `sidebar_routes`, defaulting to the
@@ -82,9 +77,43 @@ module Charming
         response
       end
 
-      # Mouse dispatch for the sidebar. Reserved for future use; returns nil.
+      # Mouse dispatch for the sidebar: a click on a route row selects it and navigates
+      # immediately; a click elsewhere in the sidebar pane focuses the sidebar. Uses the
+      # :sidebar pane's inner rect from the latest render to translate screen coordinates
+      # to nav rows. Returns nil when the click missed the sidebar entirely.
       def dispatch_sidebar_mouse
-        nil
+        return nil unless event.respond_to?(:click?) && event.click?
+
+        row = sidebar_row_at(event.x, event.y)
+        return nil unless row
+
+        if row.between?(0, sidebar_routes.length - 1)
+          session[:sidebar_index] = row
+          sidebar_select
+        else
+          focus.focus(:sidebar)
+          render_default_action
+        end
+        response
+      end
+
+      # The number of rows above the first nav item inside the sidebar pane's content
+      # area (the generated layout renders the app title plus a blank gap line).
+      # Override in controllers whose sidebar layout differs.
+      def sidebar_nav_offset
+        2
+      end
+
+      # Maps screen coordinates to a nav-row index inside the :sidebar pane's inner
+      # rect, or nil when the click missed the sidebar.
+      def sidebar_row_at(x, y)
+        target = mouse_targets.find { |candidate| candidate[:name] == :sidebar }
+        return nil unless target
+
+        inner = target.fetch(:inner_rect)
+        return nil unless inner.cover?(x, y)
+
+        y - inner.y - sidebar_nav_offset
       end
 
       # Moves the sidebar cursor by *delta* positions, clamped to the route list bounds.
@@ -96,14 +125,20 @@ module Charming
         render_default_action
       end
 
+      # The slot focus_content targets: :content when declared, else the first
+      # non-sidebar slot in the active ring.
+      def content_slot
+        ring = focus.ring
+        return :content if ring.include?(:content)
+
+        ring.find { |slot| slot != :sidebar }
+      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
+        slot = content_slot
+        focus.focus(slot) if slot
         route ? navigate_to(route.path) : render_default_action
       end
     end

data/lib/charming/controller/terminal.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Charming
+  class Controller
+    # Terminal mixes imperative out-of-band terminal effects into Controller: writing the system
+    # clipboard, raising desktop notifications, ringing the bell, and setting the window title. Each
+    # registers an {Charming::Escape} sequence onto the dispatch's collection; the Runtime flushes it
+    # to the backend before the next frame. They compose freely with a normal `render` — e.g.
+    # `def copy_url; copy(state.url); notify("Copied!"); render(:show); end`.
+    module Terminal
+      # Writes *text* to the system clipboard (OSC 52). *target* selects the selection (`"c"`
+      # clipboard, `"p"` primary). Works across Ghostty/Kitty/iTerm2 (and tmux with passthrough).
+      def copy(text, target: "c")
+        Escape.register(Escape.clipboard(text, target: target))
+      end
+
+      # Raises a desktop notification showing *body* (and *title* when given).
+      def notify(body, title: nil)
+        Escape.register(Escape.notification(body, title: title))
+      end
+
+      # Rings the terminal bell.
+      def bell
+        Escape.register(Escape.bell)
+      end
+
+      # Sets the terminal window/tab title to *text* (OSC 0).
+      def set_title(text)
+        Escape.register(Escape.title(text))
+      end
+    end
+  end
+end

data/lib/charming/controller.rb

@@ -9,6 +9,7 @@ module Charming
     TaskBinding = Data.define(:name, :action)
 
     extend ClassMethods
+    include ActionHooks
     include Rendering
     include SessionState
     include FocusManagement
@@ -16,6 +17,7 @@ module Charming
     include CommandPalette
     include ComponentDispatching
     include Dispatching
+    include Terminal
 
     attr_reader :application, :event, :params, :screen, :route
 
@@ -30,31 +32,29 @@ module Charming
       @response = nil
     end
 
-    # Dispatches a named action on this controller (e.g. :show).
+    # Dispatches a named action on this controller (e.g. :show), running all
+    # before/around/after hooks and rescue_from handlers.
     def dispatch(action)
-      public_send(action)
+      run_action_with_hooks(action)
       render_default_action if response.nil? && auto_render_after?(action)
       response || render("")
     end
 
-    # Key event dispatch: checks command palette first, then global bindings,
-    # sidebar (if focused), content bindings, tab traversal, and focused component.
+    # Key event dispatch. The precedence ladder (palette → focused text capture →
+    # global bindings → overlay → sidebar/content/component) lives in KeyDispatch.
     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
+      KeyDispatch.new(self).call
     end
 
-    # Timer event dispatcher: looks up the named action in timer bindings.
+    # Timer event dispatcher: looks up the named action in timer bindings and runs it
+    # with the full hook chain. Unlike #dispatch there is no render("") fallback — a
+    # timer action that renders nothing yields a nil response, so silent ticks skip
+    # the repaint instead of blanking the screen.
     def dispatch_timer
       b = self.class.timer_bindings[event.name.to_sym]
       return nil unless b
 
-      public_send(b.action)
+      run_action_with_hooks(b.action)
       response
     end
 
@@ -64,17 +64,42 @@ module Charming
       b ? dispatch(b.action) : nil
     end
 
-    # Mouse event dispatcher: checks command palette (if open), sidebar (if focused).
+    # Task progress dispatcher: looks up the handler in task progress bindings.
+    def dispatch_task_progress
+      b = self.class.task_progress_bindings[event.name.to_sym]
+      b ? dispatch(b.action) : nil
+    end
+
+    # Paste event dispatcher: forwards pasted text to the focused component's
+    # `handle_paste` (TextInput, TextArea, and form fields support it).
+    def dispatch_paste
+      slot = focus.current
+      return nil unless slot && respond_to?(slot, true)
+
+      component = send(slot)
+      return nil unless component.respond_to?(:handle_paste)
+
+      result = component.handle_paste(event)
+      return nil if result.nil?
+
+      dispatch_component_result(slot, result)
+      response
+    end
+
+    # Mouse event dispatcher: command palette (if open) wins, then sidebar clicks
+    # (route rows navigate directly), then named layout panes/components.
     def dispatch_mouse
       return dispatch_command_palette_mouse if command_palette_open?
 
-      mouse_response = dispatch_component_mouse
-      return mouse_response if mouse_response
+      sidebar_response = dispatch_sidebar_mouse
+      return sidebar_response if sidebar_response
 
-      dispatch_sidebar_mouse if sidebar_focused?
+      dispatch_component_mouse
     end
 
-    # Renders a body or template wrapped in the controller's layout.
+    # Renders a body or template wrapped in the controller's layout. Out-of-band escape sequences
+    # registered while rendering (e.g. image transmissions) are collected by the Runtime around the
+    # whole dispatch and attached to the response.
     def render(body = "", **assigns)
       body = view_body(default_template_name(body), **assigns) if body.is_a?(Symbol)
       @response = Response.render(render_with_layout(body))