charming 0.1.0 → 0.1.1

data/lib/charming/controller.rb

@@ -21,7 +21,7 @@ module Charming
       # Registers a command palette entry — visible in fuzzy search when Ctrl+K is pressed.
       # Accepts either a method symbol or an inline callable block.
       def command(label, action = nil, &block)
-        command_bindings << Components::CommandPalette::Command.new(label: label, value: block || action)
+        command_bindings << Presentation::Components::CommandPalette::Command.new(label: label, value: block || action)
       end
 
       # Registers a periodic timer that fires at `every`-second intervals.
@@ -35,6 +35,19 @@ module Charming
         task_bindings[name.to_sym] = TaskBinding.new(name: name.to_sym, action: action)
       end
 
+      # Re-renders the given action after dispatched actions that do not set a response.
+      # This is opt-in so existing controllers keep explicit render semantics.
+      def auto_render(action = :show)
+        @auto_render_action = action.to_sym
+      end
+
+      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 the layout class to wrap this controller's rendered output (e.g., for sidebar + main content).
       # Accepts a special `:__charming_layout_reader__` sentinel to query — without setting — the current layout.
       def layout(layout_class = :__charming_layout_reader__)
@@ -100,15 +113,16 @@ module Charming
       end
     end
 
-    attr_reader :application, :event, :params, :screen
+    attr_reader :application, :event, :params, :screen, :route
 
     # Initializes the controller with its parent application and an optional event (key/mouse/timer/task data).
     # Defaults to a 80x24 screen when no backend size is available.
-    def initialize(application:, event: nil, params: {}, screen: nil)
+    def initialize(application:, event: nil, params: {}, screen: nil, route: nil)
       @application = application
       @event = event
       @params = params
       @screen = screen || Screen.new(width: 80, height: 24)
+      @route = route
       @response = nil
     end
 
@@ -116,6 +130,7 @@ module Charming
     # returning a default empty render if the action produces no response.
     def dispatch(action)
       public_send(action)
+      render_default_action if response.nil? && auto_render_after?(action)
       response || render("")
     end
 
@@ -158,12 +173,17 @@ module Charming
       dispatch_component_mouse
     end
 
-    # Renders `body` wrapped in this controller's layout (if one is defined) and stores the response.
-    # If no layout is set, renders body bare. Called by controllers after rendering a view.
-    def render(body = "")
+    # Renders a body or template wrapped in this controller's layout (if one is defined) and stores the response.
+    # Symbols render `app/views/<controller>/<symbol>.tui.erb` (or `.txt.erb`); strings render as literal bodies.
+    def render(body = "", **assigns)
+      body = template_body(default_template_name(body), **assigns) if body.is_a?(Symbol)
       @response = Response.render(render_with_layout(body))
     end
 
+    def render_template(name, **assigns)
+      @response = Response.render(render_with_layout(template_body(name, **assigns)))
+    end
+
     def theme
       application.theme
     end
@@ -194,11 +214,19 @@ module Charming
       application.session
     end
 
-    # Lazily instantiates a model class and caches it in the session under `:models`.
-    # Subsequent calls with the same name return the cached instance. Used like: model(:user, UserModel)
-    def model(name, model_class, **attributes)
-      session[:models] ||= {}
-      session[:models][name.to_sym] ||= model_class.new(**attributes)
+    # Lazily instantiates a state class and caches it in the session under `:states`.
+    # Subsequent calls with the same name return the cached instance. Used like: state(:home, HomeState)
+    def state(name, state_class, **attributes)
+      session[:states] ||= {}
+      session[:states][name.to_sym] ||= state_class.new(**attributes)
+    end
+
+    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 an async task to the application's task executor (threaded or inline).
@@ -290,12 +318,24 @@ module Charming
       session[:sidebar_index] || current_route_index
     end
 
+    def sidebar_routes
+      application.routes.all
+    end
+
+    def current_route?(candidate)
+      return candidate.controller_class == self.class && candidate.action == :show unless route
+
+      candidate.path == route.path &&
+        candidate.controller_class == route.controller_class &&
+        candidate.action == route.action
+    end
+
     private
 
     # Finds the position of this controller among all registered routes (for sidebar highlighting).
     # Returns 0 if no matching route is found.
     def current_route_index
-      application.routes.all.index { |route| route.controller_class == self.class && route.action == :show } || 0
+      sidebar_routes.index { |candidate| current_route?(candidate) } || 0
     end
 
     # Checks whether the given slot is registered as a focus ring slot for this controller.
@@ -310,14 +350,21 @@ module Charming
       body.respond_to?(:render) ? body.render.to_s : body.to_s
     end
 
-    # Wraps `body` rendering in this controller's layout class (if one is defined).
+    # Wraps `body` rendering in this controller's layout (if one is defined).
     # If no layout is set, returns body as-is. Provides content, screen, and controller to the layout for composition.
     def render_with_layout(body)
       rendered = render_body(body)
-      layout_class = self.class.layout
-      return rendered unless layout_class
+      layout = self.class.layout
+      return rendered unless layout
+
+      render_body(layout_body(layout, body, rendered))
+    end
+
+    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)
 
-      render_body(layout_class.new(**layout_assigns(body, rendered)))
+      layout.new(**assigns)
     end
 
     # Provides view assigns for layout rendering: merges body-specific assigns with standard `content`, `screen`, and `controller`.
@@ -331,6 +378,41 @@ module Charming
       body.respond_to?(:layout_assigns) ? body.layout_assigns : {}
     end
 
+    def template_body(name, **assigns)
+      Presentation::TemplateView.new(template: resolve_template(name), namespace: template_namespace, **template_assigns(assigns))
+    end
+
+    def resolve_template(name)
+      Presentation::Templates.resolve(name, root: application.class.root)
+    end
+
+    def template_assigns(assigns)
+      {screen: screen, controller: self, theme: theme}.merge(assigns)
+    end
+
+    def template_namespace
+      namespace_name = application.class.namespace
+      return nil if namespace_name.to_s.empty?
+
+      Object.const_get(namespace_name)
+    end
+
+    def default_template_name(action)
+      "#{controller_template_path}/#{action}"
+    end
+
+    def controller_template_path
+      underscore(self.class.name.split("::").last.delete_suffix("Controller"))
+    end
+
+    def underscore(value)
+      value
+        .gsub(/([A-Z]+)([A-Z][a-z])/, "\\1_\\2")
+        .gsub(/([a-z\d])([A-Z])/, "\\1_\\2")
+        .tr("-", "_")
+        .downcase
+    end
+
     # Extracts the normalized key from the current event, handling both KeyEvent objects and raw key strings.
     # Delegates to `Charming.key_of(event)` for event-to-key resolution.
     def key_name
@@ -349,10 +431,40 @@ module Charming
       result = component.handle_key(event)
       return nil if result.nil?
 
-      render_default_action
+      dispatch_component_result(slot, result)
       :handled
     end
 
+    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
+
+    def component_result_action(slot, result)
+      case result
+      when :cancelled
+        component_action(slot, :cancelled)
+      when Array
+        component_array_action(slot, result)
+      end
+    end
+
+    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
+
+    def component_action(slot, suffix, *arguments)
+      action = :"#{slot}_#{suffix}"
+      return unless respond_to?(action, true)
+
+      [action, arguments]
+    end
+
     # Handles Tab/Shift-Tab traversal: moves focus forward or backward through the focus ring.
     # Only processes events that are actually Tab keypresses on an empty focus ring. Returns :handled when consumed.
     def dispatch_tab_traversal
@@ -407,7 +519,7 @@ module Charming
 
     # Moves sidebar selection up or down by `delta`. Does nothing if there are no routes.
     def sidebar_move(delta)
-      count = application.routes.all.length
+      count = sidebar_routes.length
       return render_default_action if count.zero?
 
       session[:sidebar_index] = (sidebar_index + delta).clamp(0, count - 1)
@@ -417,8 +529,12 @@ module Charming
     # Selects the currently highlighted sidebar route and navigates to it — shifting focus to content area.
     # If no route is found at the current index, falls back to default action.
     def sidebar_select
-      route = application.routes.all[sidebar_index]
-      session[:focus] = :content
+      route = sidebar_routes[sidebar_index]
+      if focus_ring_slot?(:content)
+        focus.focus(:content)
+      else
+        session[:focus] = :content
+      end
       route ? navigate_to(route.path) : render_default_action
     end
 
@@ -432,7 +548,7 @@ module Charming
     end
 
     def build_command_palette_with_state(commands, state, placeholder: "Search commands", height: nil)
-      Components::CommandPalette.new(
+      Presentation::Components::CommandPalette.new(
         commands: commands,
         placeholder: placeholder,
         height: height,
@@ -470,7 +586,7 @@ module Charming
 
     def theme_commands
       application.class.themes.keys.map do |name|
-        Components::CommandPalette::Command.new(label: theme_label(name), value: -> { use_theme(name) })
+        Presentation::Components::CommandPalette::Command.new(label: theme_label(name), value: -> { use_theme(name) })
       end
     end
 
@@ -490,10 +606,16 @@ module Charming
       value.respond_to?(:call) ? instance_exec(&value) : send(value)
     end
 
-    # Renders the default `:show` action if this controller defines it. Called after navigation, command execution,
+    # Renders the default action if this controller defines it. Called after navigation, command execution,
     # or key handling when no explicit response was produced — ensures the view stays rendered.
     def render_default_action
-      show if respond_to?(:show)
+      action = self.class.auto_render_action || :show
+      public_send(action) if respond_to?(action)
+    end
+
+    def auto_render_after?(action)
+      auto_render_action = self.class.auto_render_action
+      auto_render_action && action.to_sym != auto_render_action
     end
 
     def global_key_action

data/lib/charming/database_commands.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Charming
+  class DatabaseCommands
+    def initialize(command, out:, destination:)
+      @command = command
+      @out = out
+      @destination = destination
+    end
+
+    def run
+      case command
+      when "db:create" then create
+      when "db:migrate" then migrate
+      when "db:rollback" then rollback
+      when "db:drop" then drop
+      when "db:seed" then seed
+      else raise Generators::Error, "Unknown database command: #{command}"
+      end
+    end
+
+    private
+
+    attr_reader :command, :out, :destination
+
+    def create
+      load_database
+      FileUtils.mkdir_p(File.dirname(database_path)) if database_path
+      FileUtils.touch(database_path) if database_path
+      ActiveRecord::Base.connection
+      out.puts "create #{relative_database_path}"
+    end
+
+    def migrate
+      load_database
+      migration_context.migrate
+      out.puts "migrate db/migrate"
+    end
+
+    def rollback
+      load_database
+      migration_context.rollback(1)
+      out.puts "rollback db/migrate"
+    end
+
+    def drop
+      load_database
+      ActiveRecord::Base.connection.disconnect!
+      File.delete(database_path) if database_path && File.exist?(database_path)
+      out.puts "drop #{relative_database_path}"
+    end
+
+    def seed
+      load_database
+      seed_path = File.join(destination, "db", "seeds.rb")
+      raise Generators::Error, "Missing file: db/seeds.rb" unless File.exist?(seed_path)
+
+      load seed_path
+      out.puts "seed db/seeds.rb"
+    end
+
+    def load_database
+      database_config = File.join(destination, "config", "database.rb")
+      raise Generators::Error, "Database support is not configured. Missing config/database.rb." unless File.exist?(database_config)
+
+      require database_config
+    end
+
+    def migration_context
+      ActiveRecord::MigrationContext.new(File.join(destination, "db", "migrate"))
+    end
+
+    def database_path
+      ActiveRecord::Base.connection_db_config.database
+    end
+
+    def relative_database_path
+      return "database" unless database_path
+
+      base = File.realpath(destination)
+      path = File.expand_path(database_path)
+      path.start_with?("#{base}/") ? path.delete_prefix("#{base}/") : path
+    end
+  end
+end

data/lib/charming/database_installer.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Charming
+  class DatabaseInstaller
+    def initialize(database, out:, destination:)
+      @database = database
+      @out = out
+      @destination = destination
+      @app_name = Generators::Name.new(app_name_from_gemspec)
+    end
+
+    def install
+      raise Generators::Error, "Unsupported database: #{database.inspect}" unless database == "sqlite3"
+
+      create_file("config/database.rb", database_config)
+      create_file("app/models/application_record.rb", application_record)
+      create_file("db/migrate/.keep", "")
+      create_file("db/seeds.rb", %(# frozen_string_literal: true
+))
+      update_gemspec
+      update_root_file
+    end
+
+    private
+
+    attr_reader :database, :out, :destination, :app_name
+
+    def create_file(path, content)
+      absolute_path = File.join(destination, path)
+      if File.exist?(absolute_path)
+        out.puts "exist #{path}"
+        return
+      end
+
+      FileUtils.mkdir_p(File.dirname(absolute_path))
+      File.write(absolute_path, content)
+      out.puts "create #{path}"
+    end
+
+    def update_gemspec
+      update_file(gemspec_path) do |current|
+        updated = current.sub('Dir.glob("{app,config,exe,lib}/**/*")', 'Dir.glob("{app,config,db,exe,lib}/**/*")')
+        updated = insert_dependency(updated, "activerecord", "~> 8.1")
+        insert_dependency(updated, "sqlite3", "~> 2.0")
+      end
+    end
+
+    def update_root_file
+      update_file(root_file_path) do |current|
+        updated = current
+        updated = updated.sub(%(require "zeitwerk"\n), %(require "zeitwerk"\nrequire_relative "../config/database"\n)) unless updated.include?(%(require_relative "../config/database"))
+        unless updated.include?(%[loader.push_dir(File.expand_path("../app/models", __dir__), namespace: #{app_name.class_name})])
+          updated = updated.sub(
+            %[loader.push_dir(File.expand_path("../app/state", __dir__), namespace: #{app_name.class_name})\n],
+            %[loader.push_dir(File.expand_path("../app/models", __dir__), namespace: #{app_name.class_name})\nloader.push_dir(File.expand_path("../app/state", __dir__), namespace: #{app_name.class_name})\n]
+          )
+        end
+        updated
+      end
+    end
+
+    def update_file(path)
+      raise Generators::Error, "Missing file: #{relative_path(path)}" unless File.exist?(path)
+
+      current = File.read(path)
+      updated = yield current
+      return if updated == current
+
+      File.write(path, updated)
+      out.puts "update #{relative_path(path)}"
+    end
+
+    def insert_dependency(content, gem_name, version)
+      return content if content.include?(%(spec.add_dependency "#{gem_name}"))
+
+      dependency = %(  spec.add_dependency "#{gem_name}", "#{version}")
+      content.sub(%(  spec.add_dependency "charming"\n), %(  spec.add_dependency "charming"\n#{dependency}\n))
+    end
+
+    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
+)
+)
+    end
+
+    def application_record
+      %(# frozen_string_literal: true
+
+module #{app_name.class_name}
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end
+)
+    end
+
+    def app_name_from_gemspec
+      File.basename(gemspec_path, ".gemspec")
+    end
+
+    def gemspec_path
+      @gemspec_path ||= Dir.glob(File.join(destination, "*.gemspec")).first || raise(Generators::Error, "Run this command from a Charming app root")
+    end
+
+    def root_file_path
+      File.join(destination, "lib", "#{app_name.snake_name}.rb")
+    end
+
+    def relative_path(path)
+      path.delete_prefix("#{destination}/")
+    end
+  end
+end

data/lib/charming/events/key_event.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # KeyEvent represents a terminal key press parsed by the backend. *key* is the normalized semantic
+    # action name (e.g., `:up`, `:down`, `:q`), while *char*, *ctrl*, *alt*, and *shift* capture raw
+    # input details for custom bindings.
+    KeyEvent = Data.define(:key, :char, :ctrl, :alt, :shift) do
+      # Constructs a key event with the required *key* symbol, plus optional *char* string and modifier booleans.
+      def initialize(key:, char: nil, ctrl: false, alt: false, shift: false)
+        super(key: key.to_sym, char: char, ctrl: ctrl, alt: alt, shift: shift)
+      end
+    end
+  end
+end

data/lib/charming/events/mouse_event.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # MOUSE_BUTTON_MAP encodes terminal mouse button codes to semantic symbols. The constant is frozen and private.
+    MOUSE_BUTTON_MAP = {
+      0 => :left, 1 => :middle, 2 => :right, 3 => :release,
+      64 => :scroll_up, 65 => :scroll_down,
+      66 => :scroll_up, 67 => :scroll_down
+    }.freeze
+    private_constant :MOUSE_BUTTON_MAP
+
+    # MouseEvent represents a mouse input event. *button* encodes which button or action was triggered (left,
+    # right, scroll), while *x* and *y* provide the cursor position. Modifier booleans (*ctrl*, *alt*, *shift*)
+    # capture key state at the time of the event.
+    MouseEvent = Data.define(:button, :x, :y, :ctrl, :alt, :shift) do
+      def initialize(button:, x:, y:, ctrl: false, alt: false, shift: false)
+        super
+      end
+
+      # Returns the semantic symbol for *button* — one of `left`, `right`, `scroll_up`, etc. or `:unknown`.
+      def button_name
+        MOUSE_BUTTON_MAP.fetch(button, :unknown)
+      end
+
+      # Returns `true` when the current event is a click (left, middle, or right button).
+      def click?
+        %i[left middle right].include?(button_name)
+      end
+
+      # Returns `true` when the button name maps to either direction of scroll.
+      def scroll?
+        %i[scroll_up scroll_down].include?(button_name)
+      end
+
+      # Returns `true` when the current event is a mouse release action.
+      def release?
+        button_name == :release
+      end
+    end
+  end
+end

data/lib/charming/events/resize_event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # ResizeEvent represents a terminal window resize. *width* and *height* carry the new terminal dimensions
+    # in screen cells, replacing the previous Screen dimensions for all subsequent rendering.
+    ResizeEvent = Data.define(:width, :height)
+  end
+end

data/lib/charming/events/task_event.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # TaskEvent represents background task completion. *name* is the declared task identifier, *value* carries
+    # the return result and *error* captures any exception raised during execution. The `error?` predicate
+    # simplifies error handling in controller handlers.
+    TaskEvent = Data.define(:name, :value, :error) do
+      def initialize(name:, value: nil, error: nil)
+        super
+      end
+
+      # Returns `true` when the task finished with a non-nil exception.
+      def error?
+        !error.nil?
+      end
+    end
+  end
+end

data/lib/charming/events/timer_event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Charming
+  module Events
+    # TimerEvent represents a timed dispatch from the runtime loop. *name* is the declared timer identifier;
+    # *now* is the monotonically rising clock value at emission for throttle comparisons.
+    TimerEvent = Data.define(:name, :now)
+  end
+end

data/lib/charming/generators/app_generator/app_spec_templates.rb

@@ -4,12 +4,12 @@ module Charming
   module Generators
     class AppGenerator
       module AppSpecTemplates
-        def spec_model
+        def spec_state
           %(# frozen_string_literal: true
 
 require "#{app_name.snake_name}"
 
-RSpec.describe #{app_name.class_name}::HomeModel do
+RSpec.describe #{app_name.class_name}::HomeState do
   describe "#title" do
     it "has the correct default string value" do
       instance = described_class.new
@@ -36,7 +36,7 @@ RSpec.describe #{app_name.class_name}::HomeController do
   subject(:controller) { described_class.new(application: application) }
 
   describe "#show" do
-    it "renders the view with the model" do
+    it "renders the view with the state" do
       response = controller.dispatch(:show)
 
       expect(response).to respond_to(:body)
@@ -51,12 +51,16 @@ end
 
 require "#{app_name.snake_name}"
 
-RSpec.describe #{app_name.class_name}::HomeView do
+RSpec.describe "home/show template" do
   describe "#render" do
-    it "renders the model title" do
-      view = described_class.new(
-         home: double(title: "#{app_name.class_name}")
-       )
+    it "renders the state title" do
+      template = Charming::Presentation::Templates.resolve("home/show", root: #{app_name.class_name}::Application.root)
+      view = Charming::Presentation::TemplateView.new(
+        template: template,
+        namespace: #{app_name.class_name},
+        home: double(title: "#{app_name.class_name}"),
+        theme: #{app_name.class_name}::Application.new.theme
+      )
 
       expect(view.render).to include("#{app_name.class_name}")
     end

data/lib/charming/generators/app_generator/basic_templates.rb

@@ -51,7 +51,7 @@ end
   spec.summary = "A Charming terminal user interface."
   spec.authors = ["TODO: Your name"]
   spec.email = ["TODO: Your email"]
-  spec.files = Dir.glob("{app,config,exe,lib}/**/*") + %w[README.md]
+  spec.files = Dir.glob("#{gemspec_file_glob}/**/*") + %w[README.md]
   spec.bindir = "exe"
   spec.executables = ["#{name.snake_name}"]
   spec.require_paths = ["lib"]
@@ -61,7 +61,19 @@ end
 
         def gemspec_dependencies
           %(
-  spec.add_dependency "charming")
+  spec.add_dependency "charming"#{database_dependencies})
+        end
+
+        def gemspec_file_glob
+          database? ? "{app,config,db,exe,lib}" : "{app,config,exe,lib}"
+        end
+
+        def database_dependencies
+          return "" unless database?
+
+          %(
+  spec.add_dependency "activerecord", "~> 8.1"
+  spec.add_dependency "sqlite3", "~> 2.0")
         end
       end
     end