charming 0.3.0 → 0.4.0

data/lib/charming/{controller/sidebar_navigation.rb → shell/sidebar.rb}

@@ -1,14 +1,13 @@
 # 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.
-    #
-    # 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
+  # Shell::Sidebar is the opt-in app-shell sidebar: route listing, sidebar/content focus
+  # split, j/k/enter navigation, and mouse clicks on route rows. Generated apps include it
+  # in ApplicationController when generated with the sidebar layout
+  # (`include Charming::Shell::Sidebar`). Controllers that want Tab-driven sidebar
+  # navigation declare `focus_ring :sidebar, :content`.
+  module Shell
+    module Sidebar
       # Moves focus to the sidebar slot and remembers the highlighted route.
       def focus_sidebar
         focus.focus(:sidebar)
@@ -37,7 +36,8 @@ module Charming
       end
 
       # Returns the index of the currently selected route in `sidebar_routes`, defaulting to the
-      # active route when the session index is unset.
+      # active route when the session index is unset. Stored in the session: the sidebar cursor
+      # is app-global — it should keep its position as the user moves between screens.
       def sidebar_index
         session[:sidebar_index] || current_route_index
       end
@@ -52,7 +52,7 @@ module Charming
       def current_route?(candidate)
         return candidate.controller_class == self.class && candidate.action == :show unless route
 
-        candidate.path == route.path &&
+        candidate.name == route.name &&
           candidate.controller_class == route.controller_class &&
           candidate.action == route.action
       end
@@ -139,7 +139,7 @@ module Charming
         route = sidebar_routes[sidebar_index]
         slot = content_slot
         focus.focus(slot) if slot
-        route ? navigate_to(route.path) : render_default_action
+        route ? navigate(route.name) : render_default_action
       end
     end
   end

data/lib/charming/tasks/context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Charming
+  module Tasks
+    # Context is the object a task block receives as its argument. It carries the
+    # task's inputs (the `with:` hash given to `run_task`, deep-frozen at submit time)
+    # and the progress reporter:
+    #
+    #   run_task(:search, with: {query: query.value}) do |ctx|
+    #     results = Api.search(ctx[:query])
+    #     ctx.report(1, of: 1)
+    #     results
+    #   end
+    #
+    # Task blocks receive data in via `with:` and return data out as the block value.
+    # They touch nothing else: the `on_task` handler on the loop thread is the only
+    # place task results become state.
+    class Context
+      def initialize(data, progress)
+        @data = data
+        @progress = progress
+      end
+
+      # Returns the input value for *key* from the `with:` hash.
+      def [](key)
+        @data[key]
+      end
+
+      # Reports progress to the matching `on_task_progress` handler on the loop thread.
+      def report(current, of: nil, message: nil)
+        @progress.report(current, of: of, message: message)
+      end
+    end
+  end
+end

data/lib/charming/test_helper.rb

@@ -18,27 +18,28 @@ module Charming
   #     end
   #
   #     it "quits on q" do
-  #       expect(press(ctrl_class: HomeController, key: "q")).to be_quit
+  #       expect(press(ctrl, "q")).to be_quit
   #     end
   #   end
   #
   # Helpers:
-  # - `build_controller(klass, app:, screen:, route:)` — controller instance wired to an app
+  # - `build_controller(klass, app:, screen:, route:, params:)` — controller instance wired to an app
   # - `key_event("ctrl+p")` — build a KeyEvent from a human-readable string
-  # - `press(controller_or_class, "down")` — dispatch a key press, returns the Response
-  # - `press_sequence(klass, ["down", "down", "enter"], app:)` — dispatch several presses
+  # - `press(controller, "down")` — dispatch a key press at the instance, returns the Response
+  # - `press_sequence(controller, ["down", "down", "enter"])` — dispatch several presses at one instance
   #
   # RSpec matchers (when RSpec is loaded):
   # - `expect(response).to render_text("...")` / `render_match(/.../)`
   # - `expect(response).to be_quit` / `be_navigate` (predicate matchers on Response)
-  # - `expect(response).to navigate_to("/path")`
+  # - `expect(response).to navigate_to(:projects)`
   module TestHelper
-    # Builds a controller instance with sensible test defaults: a fresh Application,
-    # an 80x24 screen, and no event.
-    def build_controller(controller_class, app: nil, screen: nil, route: nil, event: nil)
+    # Builds a controller instance with sensible test defaults: a fresh Application and
+    # an 80x24 screen. Runs the screen_entered lifecycle hook, mirroring the Runtime's
+    # persistent-controller lifecycle.
+    def build_controller(controller_class, app: nil, screen: nil, route: nil, params: {})
       app ||= Charming::Application.new
       screen ||= Charming::Screen.new(width: 80, height: 24)
-      controller_class.new(application: app, event: event, screen: screen, route: route)
+      controller_class.new(application: app, params: params, screen: screen, route: route).tap(&:screen_entered)
     end
 
     # Builds a KeyEvent from a human-readable string like "q", "down", "ctrl+p",
@@ -57,18 +58,16 @@ module Charming
       )
     end
 
-    # Dispatches a single key press against *controller_class* and returns the Response.
-    # Pass `app:` to share session state across presses.
-    def press(controller_class, key, app:, screen: nil, route: nil)
-      controller = build_controller(controller_class, app: app, screen: screen, route: route, event: key_event(key))
-      controller.dispatch_key
+    # Dispatches a single key press at *controller* (an instance from build_controller)
+    # and returns the Response. Accepts a human-readable string or a ready KeyEvent.
+    def press(controller, key)
+      controller.dispatch_key(key.is_a?(String) ? key_event(key) : key)
     end
 
-    # Dispatches each key in *keys* in order against fresh controller instances sharing
-    # *app*'s session (mirroring the runtime's controller-per-event model). Returns the
-    # last Response.
-    def press_sequence(controller_class, keys, app:, screen: nil, route: nil)
-      keys.map { |key| press(controller_class, key, app: app, screen: screen, route: route) }.last
+    # Dispatches each key in *keys* in order at the same controller instance (mirroring
+    # the runtime's persistent-controller model). Returns the last Response.
+    def press_sequence(controller, keys)
+      keys.map { |key| press(controller, key) }.last
     end
 
     # Builds a MemoryBackend pre-seeded with KeyEvents parsed from *keys*, ready to be
@@ -77,6 +76,24 @@ module Charming
       events = keys.map { |key| key.is_a?(String) ? key_event(key) : key }
       Charming::Internal::Terminal::MemoryBackend.new(events: events, width: width, height: height)
     end
+
+    # Renders a view class standalone — no controller needed — and returns a hash with
+    # the painted :frame plus the layout's registration data (:focus_slots,
+    # :mouse_targets). Rendering is pure: registrations only commit when a response
+    # paints, so unit-testing a view means asserting on these artifacts.
+    #
+    #   result = render_view(Home::ShowView, screen: Charming::Screen.new(width: 40, height: 10))
+    #   expect(result[:focus_slots]).to eq([:entries])
+    def render_view(view_class, **assigns)
+      view = view_class.new(**assigns)
+      frame = view.render
+      artifacts = view.render_artifacts
+      {
+        frame: frame,
+        focus_slots: artifacts.last&.focus_slots || [],
+        mouse_targets: artifacts.flat_map(&:mouse_targets)
+      }
+    end
   end
 end
 
@@ -108,13 +125,16 @@ if defined?(RSpec)
     end
   end
 
-  RSpec::Matchers.define :navigate_to do |expected_path|
+  RSpec::Matchers.define :navigate_to do |expected_name, **expected_params|
     match do |response|
-      response.respond_to?(:navigate?) && response.navigate? && response.path == expected_path
+      next false unless response.respond_to?(:navigate?) && response.navigate?
+      next false unless response.name == expected_name.to_sym
+
+      expected_params.empty? || response.params == expected_params
     end
 
     failure_message do |response|
-      "expected a navigation response to #{expected_path.inspect}, got: #{response.inspect}"
+      "expected a navigation response to #{expected_name.inspect}, got: #{response.inspect}"
     end
   end
 end

data/lib/charming/unhandled_component_event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  # Raised when a component emits a result (`[:submitted, value]`, `[:selected, value]`,
+  # or `:cancelled`) and the controller has neither an `on_submit`/`on_select`/`on_cancel`
+  # registration nor a legacy `<slot>_<event>` hook for it. Raised in development and test;
+  # production logs a warning and falls back to the default render instead.
+  class UnhandledComponentEvent < Error; end
+end

data/lib/charming/unknown_slot.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  # Raised when a rendered layout names a focusable pane, or an `on_*` registration
+  # references a slot, that nothing declares — not a `slot` declaration, not a
+  # `focus_ring` entry, not a same-named method. Raised in development and test;
+  # production logs a warning. The message names the fix and lists declared slots.
+  class UnknownSlot < Error; end
+end

data/lib/charming/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Charming
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/charming/welcome.rb

@@ -7,7 +7,7 @@ module Charming
   module Welcome
     # The fallback route the Runtime uses when the application has no routes.
     def self.route
-      Router::Route.new(path: "/", controller_class: Controller, action: :show, title: "Welcome", params: {})
+      Router::Route.new(name: :root, controller_class: Controller, action: :show, title: "Welcome", params: {})
     end
   end
 end

data/lib/charming.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "active_support/inflector"
-require "active_support/string_inquirer"
 require "logger"
 require "zeitwerk"
 
@@ -26,15 +24,15 @@ module Charming
   # Base error class for all Charming-specific exceptions (used by templates, generators, runtime, etc.).
   class Error < StandardError; end
 
-  # The current environment, read from CHARMING_ENV (default "development"). Returns a
-  # StringInquirer so callers can write `Charming.env.test?` / `Charming.env.production?`.
+  # The current environment, read from CHARMING_ENV (default "development"). Returns an
+  # EnvInquirer so callers can write `Charming.env.test?` / `Charming.env.production?`.
   def self.env
-    @env ||= ActiveSupport::StringInquirer.new(ENV["CHARMING_ENV"] || "development")
+    @env ||= Internal::EnvInquirer.new(ENV["CHARMING_ENV"] || "development")
   end
 
   # Overrides the environment (used by tests and the CLI).
   def self.env=(value)
-    @env = value.nil? ? nil : ActiveSupport::StringInquirer.new(value.to_s)
+    @env = value.nil? ? nil : Internal::EnvInquirer.new(value.to_s)
   end
 
   # Entry point for running a Charming application. Instantiates a Runtime for *application* and starts
@@ -84,6 +82,16 @@ module Charming
 
     :"#{(ordered_modifiers + [key]).join("+")}"
   end
+
+  # Emits a deprecation warning once per process per *category*, prefixed
+  # "[charming deprecation]". Warnings go to stderr.
+  def self.deprecate(message, category:)
+    @deprecation_emitted ||= {}
+    return if @deprecation_emitted[category]
+
+    @deprecation_emitted[category] = true
+    warn("[charming deprecation] #{message}")
+  end
 end
 
 Charming::Templates.register ".tui.erb", Charming::Templates::ErbHandler

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: charming
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - pando
@@ -29,26 +29,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 8.1.2
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 8.1.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '8.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 8.1.2
 - !ruby/object:Gem::Dependency
   name: commonmarker
   requirement: !ruby/object:Gem::Requirement
@@ -91,48 +71,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: tty-cursor
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-- !ruby/object:Gem::Dependency
-  name: zeitwerk
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.6'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.6'
-- !ruby/object:Gem::Dependency
-  name: tty-table
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.12'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.12'
 - !ruby/object:Gem::Dependency
   name: tty-reader
   requirement: !ruby/object:Gem::Requirement
@@ -148,21 +86,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.9'
 - !ruby/object:Gem::Dependency
-  name: tty-screen
+  name: unicode-display_width
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '2.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.8'
+        version: '2.6'
 - !ruby/object:Gem::Dependency
-  name: unicode-display_width
+  name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -196,18 +134,18 @@ files:
 - lib/charming/controller.rb
 - lib/charming/controller/action_hooks.rb
 - lib/charming/controller/class_methods.rb
-- lib/charming/controller/command_palette.rb
-- lib/charming/controller/component_dispatching.rb
+- lib/charming/controller/component_dispatch.rb
 - lib/charming/controller/dispatching.rb
 - lib/charming/controller/focus.rb
 - lib/charming/controller/focus_management.rb
 - lib/charming/controller/key_dispatch.rb
 - lib/charming/controller/rendering.rb
 - lib/charming/controller/session_state.rb
-- lib/charming/controller/sidebar_navigation.rb
 - lib/charming/controller/terminal.rb
 - lib/charming/controller/timers.rb
+- lib/charming/cross_thread_access.rb
 - lib/charming/database/commands.rb
+- lib/charming/double_render_error.rb
 - lib/charming/escape.rb
 - lib/charming/events/focus_event.rb
 - lib/charming/events/key_event.rb
@@ -268,14 +206,20 @@ files:
 - lib/charming/image/source.rb
 - lib/charming/image/terminal.rb
 - lib/charming/image/transmit.rb
+- lib/charming/internal/deep_freeze.rb
+- lib/charming/internal/env_inquirer.rb
 - lib/charming/internal/event_loop.rb
+- lib/charming/internal/inflections.rb
 - lib/charming/internal/renderer/differential.rb
 - lib/charming/internal/renderer/full_repaint.rb
+- lib/charming/internal/session_guard.rb
 - lib/charming/internal/terminal/adapter.rb
+- lib/charming/internal/terminal/cursor.rb
 - lib/charming/internal/terminal/key_normalizer.rb
 - lib/charming/internal/terminal/memory_backend.rb
 - lib/charming/internal/terminal/modified_key_parser.rb
 - lib/charming/internal/terminal/mouse_parser.rb
+- lib/charming/internal/terminal/size.rb
 - lib/charming/internal/terminal/tty_backend.rb
 - lib/charming/internal/timer_control.rb
 - lib/charming/presentation/component.rb
@@ -309,6 +253,7 @@ files:
 - lib/charming/presentation/components/multi_select_list.rb
 - lib/charming/presentation/components/paginator.rb
 - lib/charming/presentation/components/progressbar.rb
+- lib/charming/presentation/components/result.rb
 - lib/charming/presentation/components/sparkline.rb
 - lib/charming/presentation/components/spinner.rb
 - lib/charming/presentation/components/status_bar.rb
@@ -369,17 +314,23 @@ files:
 - lib/charming/presentation/ui/width.rb
 - lib/charming/presentation/view.rb
 - lib/charming/projectile.rb
+- lib/charming/render_artifacts.rb
 - lib/charming/response.rb
 - lib/charming/router.rb
 - lib/charming/runtime.rb
 - lib/charming/screen.rb
+- lib/charming/shell/palette.rb
+- lib/charming/shell/sidebar.rb
 - lib/charming/spring.rb
 - lib/charming/tasks/cancelled.rb
+- lib/charming/tasks/context.rb
 - lib/charming/tasks/inline_executor.rb
 - lib/charming/tasks/progress.rb
 - lib/charming/tasks/task.rb
 - lib/charming/tasks/threaded_executor.rb
 - lib/charming/test_helper.rb
+- lib/charming/unhandled_component_event.rb
+- lib/charming/unknown_slot.rb
 - lib/charming/version.rb
 - lib/charming/welcome.rb
 - lib/charming/welcome/controller.rb

data/lib/charming/controller/component_dispatching.rb

@@ -1,125 +0,0 @@
-# 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
-
-      # Hit-tests the current mouse event against named layout panes from the latest render.
-      # Clicks move focus to matching slots; components in clicked panes receive local coordinates.
-      def dispatch_component_mouse
-        target = mouse_target_for_event
-        return nil unless target
-
-        slot = target.fetch(:name)
-        previous_focus = focus.current
-        focus.focus(slot) if focusable_click?(slot)
-
-        result = dispatch_mouse_to_target_component(slot, target)
-        return response if result.nil? && previous_focus == focus.current
-
-        result ? dispatch_component_result(slot, result) : render_default_action
-        response
-      end
-
-      def mouse_target_for_event
-        mouse_targets.rfind { |target| target.fetch(:rect).cover?(event.x, event.y) }
-      end
-
-      def focusable_click?(slot)
-        event.respond_to?(:click?) && event.click? && focus.ring.include?(slot)
-      end
-
-      def dispatch_mouse_to_target_component(slot, target)
-        return nil unless respond_to?(slot, true)
-
-        component = send(slot)
-        return nil unless component.respond_to?(:handle_mouse)
-
-        local_event = local_mouse_event(target.fetch(:inner_rect))
-        return nil unless local_event
-
-        component.handle_mouse(local_event)
-      end
-
-      def local_mouse_event(rect)
-        return nil unless rect.cover?(event.x, event.y)
-
-        Events::MouseEvent.new(
-          button: event.button,
-          x: event.x - rect.x,
-          y: event.y - rect.y,
-          ctrl: event.ctrl,
-          alt: event.alt,
-          shift: event.shift
-        )
-      end
-    end
-  end
-end