charming 0.2.0 → 0.2.1

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/session_state.rb

@@ -44,9 +44,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.rb

@@ -9,6 +9,7 @@ module Charming
     TaskBinding = Data.define(:name, :action)
 
     extend ClassMethods
+    include ActionHooks
     include Rendering
     include SessionState
     include FocusManagement
@@ -30,22 +31,50 @@ 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, in 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.
     def dispatch_key
       return dispatch_command_palette_key if command_palette_open?
+
+      if printable_text_event? && focused_component_captures_text?
+        return response if dispatch_to_focused_component == :handled
+      end
+
       return dispatch(global_key_action) if global_key_action
+
+      if focus.overlay?
+        dispatch_to_focused_component
+        return response
+      end
+
       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
+
+      # Text-capturing components (forms, editors) own their remaining keys — Tab
+      # included, so forms do field navigation. Everything else keeps ring traversal
+      # ahead of the component.
+      if focused_component_captures_text?
+        return response if dispatch_to_focused_component == :handled
+        return response if dispatch_tab_traversal == :handled
+      else
+        return response if dispatch_tab_traversal == :handled
+        return response if dispatch_to_focused_component == :handled
+      end
       nil
     end
 
@@ -64,14 +93,37 @@ 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.

data/lib/charming/database/commands.rb

@@ -8,11 +8,17 @@ module Charming
     # `db:install`, which lives in Generators::DatabaseInstaller). It loads the app's
     # `config/database.rb`, delegates the actual work to ActiveRecord, and prints a short
     # status line on success.
+    #
+    # Supported commands: db:create, db:migrate, db:rollback [STEP=n], db:drop, db:seed,
+    # db:setup, db:reset, db:prepare, db:status, db:version, db:schema:dump, db:schema:load.
+    # The target database file is selected by CHARMING_ENV (development, test, production).
     class Commands
-      # *command* is the subcommand string (e.g., "db:create"). *out* is the status-output
-      # stream. *destination* is the app root for resolving `config/database.rb` and `db/`.
-      def initialize(command, out:, destination:)
+      # *command* is the subcommand string (e.g., "db:create"). *args* holds extra CLI
+      # arguments such as "STEP=2". *out* is the status-output stream. *destination* is the
+      # app root for resolving `config/database.rb` and `db/`.
+      def initialize(command, out:, destination:, args: [])
         @command = command
+        @args = args
         @out = out
         @destination = destination
       end
@@ -25,14 +31,21 @@ module Charming
         when "db:rollback" then rollback
         when "db:drop" then drop
         when "db:seed" then seed
+        when "db:setup" then setup
+        when "db:reset" then reset
+        when "db:prepare" then prepare
+        when "db:status" then status
+        when "db:version" then version
+        when "db:schema:dump" then schema_dump
+        when "db:schema:load" then schema_load
         else raise Generators::Error, "Unknown database command: #{command}"
         end
       end
 
       private
 
-      # The subcommand, output stream, and app destination.
-      attr_reader :command, :out, :destination
+      # The subcommand, extra arguments, output stream, and app destination.
+      attr_reader :command, :args, :out, :destination
 
       # Creates the SQLite database file (touch) and establishes the connection.
       def create
@@ -43,18 +56,21 @@ module Charming
         out.puts "create #{relative_database_path}"
       end
 
-      # Runs all pending migrations from `db/migrate`.
+      # Runs all pending migrations from `db/migrate`, then refreshes `db/schema.rb`.
       def migrate
         load_database
         migration_context.migrate
+        dump_schema
         out.puts "migrate db/migrate"
       end
 
-      # Rolls back the most recent migration.
+      # Rolls back the most recent migration(s). Accepts `STEP=n` (default 1), then
+      # refreshes `db/schema.rb`.
       def rollback
         load_database
-        migration_context.rollback(1)
-        out.puts "rollback db/migrate"
+        migration_context.rollback(step_argument)
+        dump_schema
+        out.puts "rollback db/migrate (#{step_argument} step#{"s" if step_argument > 1})"
       end
 
       # Disconnects ActiveRecord, then deletes the database file.
@@ -65,16 +81,92 @@ module Charming
         out.puts "drop #{relative_database_path}"
       end
 
-      # Loads `db/seeds.rb` (raises if missing).
+      # Loads `db/seeds.rb` (raises if missing). The full application is loaded first so
+      # seeds can reference app models.
       def seed
         load_database
-        seed_path = File.join(destination, "db", "seeds.rb")
+        load_application
         raise Generators::Error, "Missing file: db/seeds.rb" unless File.exist?(seed_path)
 
         load seed_path
         out.puts "seed db/seeds.rb"
       end
 
+      # Creates the database, loads the schema when one exists (otherwise migrates), and seeds.
+      def setup
+        create
+        File.exist?(schema_path) ? schema_load : migrate
+        seed if File.exist?(seed_path)
+        out.puts "setup #{relative_database_path}"
+      end
+
+      # Drops and re-creates the database from scratch (drop + setup).
+      def reset
+        load_database
+        drop
+        setup
+      end
+
+      # CI-friendly: sets up the database when it doesn't exist, otherwise just migrates.
+      def prepare
+        load_database
+        if database_path && File.exist?(database_path)
+          migrate
+        else
+          setup
+        end
+      end
+
+      # Prints a Rails-style migration status table (status, version, name).
+      def status
+        load_database
+        out.puts "Status   Version          Name"
+        out.puts "-" * 48
+        migration_context.migrations_status.each do |migration_status, version, name|
+          out.puts format("%-8s %-16s %s", migration_status, version, name)
+        end
+      end
+
+      # Prints the current schema version.
+      def version
+        load_database
+        out.puts "version #{migration_context.current_version}"
+      end
+
+      # Writes the current database structure to `db/schema.rb`.
+      def schema_dump
+        load_database
+        dump_schema
+        out.puts "dump db/schema.rb"
+      end
+
+      # Loads `db/schema.rb` into the database (fast alternative to replaying migrations).
+      def schema_load
+        load_database
+        raise Generators::Error, "Missing file: db/schema.rb. Run `charming db:schema:dump` first." unless File.exist?(schema_path)
+
+        load schema_path
+        out.puts "load db/schema.rb"
+      end
+
+      # Dumps the connected database's structure to `db/schema.rb` via ActiveRecord.
+      def dump_schema
+        File.open(schema_path, "w") do |file|
+          ActiveRecord::SchemaDumper.dump(ActiveRecord::Base.connection_pool, file)
+        end
+      end
+
+      # Parses the `STEP=n` argument for db:rollback (defaults to 1).
+      def step_argument
+        step = args.find { |arg| arg.start_with?("STEP=") }
+        return 1 unless step
+
+        value = step.delete_prefix("STEP=").to_i
+        raise Generators::Error, "STEP must be a positive integer" unless value.positive?
+
+        value
+      end
+
       # Loads the app's `config/database.rb` (raises if missing) which establishes the connection.
       def load_database
         database_config = File.join(destination, "config", "database.rb")
@@ -83,11 +175,31 @@ module Charming
         require database_config
       end
 
+      # Requires the app's root loader (`lib/<app>.rb`, derived from the gemspec name) so
+      # app constants — models in particular — are available. No-op when not in an app root.
+      def load_application
+        gemspec = Dir.glob(File.join(destination, "*.gemspec")).first
+        return unless gemspec
+
+        root_file = File.join(destination, "lib", "#{File.basename(gemspec, ".gemspec")}.rb")
+        require root_file if File.exist?(root_file)
+      end
+
       # The ActiveRecord migration context rooted at `db/migrate` inside the app.
       def migration_context
         ActiveRecord::MigrationContext.new(File.join(destination, "db", "migrate"))
       end
 
+      # Path to the app's `db/schema.rb`.
+      def schema_path
+        File.join(destination, "db", "schema.rb")
+      end
+
+      # Path to the app's `db/seeds.rb`.
+      def seed_path
+        File.join(destination, "db", "seeds.rb")
+      end
+
       # The configured database file path (nil when ActiveRecord isn't connected to a file).
       def database_path
         ActiveRecord::Base.connection_db_config.database

data/lib/charming/events/focus_event.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # FocusEvent reports the terminal window gaining or losing focus (focus reporting
+    # mode `\e[?1004h`, markers `\e[I` / `\e[O`). Controllers opt in by defining a
+    # `focus_changed` action; apps can use it to pause timers or dim the UI.
+    FocusEvent = Data.define(:focused) do
+      def focused? = focused
+    end
+  end
+end

data/lib/charming/events/paste_event.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # PasteEvent carries text pasted via the terminal's bracketed-paste mode
+    # (`\e[200~ ... \e[201~`). Without bracketed paste, pasted text arrives as a storm
+    # of individual key events; with it, components receive the whole string at once
+    # via `handle_paste`.
+    PasteEvent = Data.define(:text)
+  end
+end

data/lib/charming/events/task_progress_event.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # TaskProgressEvent reports incremental progress from a running background task.
+    # *name* matches the task name, *current*/*total* describe completion (total may be
+    # nil for indeterminate work), and *message* is an optional human-readable status.
+    TaskProgressEvent = Data.define(:name, :current, :total, :message) do
+      def initialize(name:, current:, total: nil, message: nil)
+        super
+      end
+
+      # Completion as a 0.0..1.0 fraction, or nil when the total is unknown.
+      def fraction
+        return nil unless total&.positive?
+
+        (current.to_f / total).clamp(0.0, 1.0)
+      end
+    end
+  end
+end

data/lib/charming/generators/app_generator.rb

@@ -98,10 +98,47 @@ module Charming
           controller_actions: controller_actions,
           controller_helpers: controller_helpers,
           database_require: database_require,
-          model_loader: model_loader
+          model_loader: model_loader,
+          env_setup: env_setup,
+          database_spec_setup: database_spec_setup
         }
       end
 
+      # Pins CHARMING_ENV to "test" before the app (and its database config) loads, so
+      # specs hit db/test.sqlite3. Empty for non-database apps.
+      def env_setup
+        return "" unless database?
+
+        "ENV[\"CHARMING_ENV\"] ||= \"test\"\n\n"
+      end
+
+      # Prepares the test database schema before the suite and rolls back each example's
+      # writes in a transaction. Empty for non-database apps.
+      def database_spec_setup
+        return "" unless database?
+
+        <<~RUBY
+
+          # Prepare the test database, preferring the dumped schema over replaying migrations.
+          schema = File.expand_path("../db/schema.rb", __dir__)
+          if File.exist?(schema)
+            load schema
+          else
+            ActiveRecord::MigrationContext.new(File.expand_path("../db/migrate", __dir__)).migrate
+          end
+
+          RSpec.configure do |config|
+            # Roll back database writes after each example so tests stay isolated.
+            config.around(:each) do |example|
+              ActiveRecord::Base.transaction(requires_new: true) do
+                example.run
+                raise ActiveRecord::Rollback
+              end
+            end
+          end
+        RUBY
+      end
+
       # The `Gem::Specification` attributes block (indented two spaces to match the wrapping
       # `Gem::Specification.new do |spec|`).
       def gemspec_attributes

data/lib/charming/generators/database_installer.rb

@@ -100,22 +100,11 @@ module Charming
         content.sub(%(  spec.add_dependency "charming"\n), %(  spec.add_dependency "charming"\n#{dependency}\n))
       end
 
-      # The contents of the new `config/database.rb` (establishes an SQLite connection to
-      # `db/development.sqlite3`).
+      # The contents of the new `config/database.rb` — read from the shared app template so
+      # `charming new --database` and `charming db:install` stay in sync. Environment-aware:
+      # the database file is `db/<CHARMING_ENV>.sqlite3`.
       def database_config
-        %(# frozen_string_literal: true
-
-require "active_record"
-require "fileutils"
-
-database_path = File.expand_path("../db/development.sqlite3", __dir__)
-FileUtils.mkdir_p(File.dirname(database_path))
-
-ActiveRecord::Base.establish_connection(
-  adapter: "sqlite3",
-  database: database_path
-)
-)
+        File.read(File.join(__dir__, "templates", "app", "database_config.template"))
       end
 
       # The contents of the new `app/models/application_record.rb` (abstract ActiveRecord base).