charming 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 739b00d7bbbe867e98ec93bc614157e59650eb5ecd45a48127139fb5ea11adb1
-  data.tar.gz: 8c7008f8bcd6eba1464d01e317c23a37d93a47cf272cc617295c5a4f6f50e379
+  metadata.gz: 2bc5c3942786d07631d42361391e76f4f42275cc472c8ff7e37669880263b978
+  data.tar.gz: b6dc9eef28cf8eb6849a9ae34a4af8e6902a0e263529762cce9a3e591ed06396
 SHA512:
-  metadata.gz: 69179596724fc972425aa5c47cd449d31278ea51671c6afc25543d5db58ea2b2edcb035843cc76f53c663f65bbda24e9990cc5cab90142036a228bb68e9cf9e9
-  data.tar.gz: 55b113fa7a8a0208559716a30d18ec070e6c0b070032f16a9d66daa67273b9c3d81ab5aefe231b36240b783c200d9eff4321f7df9596a845b43f2343f4754f8e
+  metadata.gz: e772a624b0f4a51d722ed40863bfae85161ac9bc1b508d7accb6cc7a4fc8f30352a79b66a9d42416992d38477c145f5ecc55c953b77aca1cf787a03a5f2f0e64
+  data.tar.gz: 61dc03c8e8ade6e62fbc86c6f76e382063cc13aa1f60cc8afa161f6a646d1e4836483f9ca9a2e8446881f5b5a65d4b8e5107e39300c5844034dbbcb33f37a47f

data/README.md

@@ -52,8 +52,8 @@ The generator produces a Bundler gem with a Rails-like structure:
 app/controllers/                         # controller actions and input bindings
 app/state/                               # session-backed TUI state
 app/models/                              # optional Active Record models
-app/views/home/show.tui.erb              # screen templates
-app/views/layouts/application.tui.erb    # layout template
+app/views/home/show_view.rb              # screen view classes
+app/views/layouts/application_layout.rb  # layout view class
 app/components/                          # reusable components
 config/routes.rb                         # route definitions
 lib/my_app.rb                            # namespace loader (Zeitwerk)

data/lib/charming/application.rb

@@ -22,12 +22,16 @@ module Charming
         name&.split("::")&.then { |parts| parts[0...-1].join("::") }
       end
 
+      # Returns the app's filesystem root, used to resolve relative theme and template paths.
+      # Pass *path* to set it; without arguments it returns the current value (or nil if unset).
       def root(path = THEME_READER)
         return @root if path == THEME_READER
 
         @root = File.expand_path(path)
       end
 
+      # Registers a named theme. Provide either *from:* (path to a JSON file relative to the app root)
+      # or *built_in:* (name of a bundled theme such as "phosphor"). Raises when neither or both are given.
       def theme(name, from: nil, built_in: nil)
         raise ArgumentError, "theme expects from: or built_in:" unless from || built_in
         raise ArgumentError, "theme expects either from: or built_in:, not both" if from && built_in
@@ -39,16 +43,21 @@ module Charming
         end
       end
 
+      # Hash of all registered themes keyed by symbol, including those inherited from superclasses.
       def themes
         @themes ||= superclass.respond_to?(:themes) ? superclass.themes.dup : {}
       end
 
+      # Returns the default theme name, or sets it when *name* is given. When unset, falls back
+      # to the first registered theme. Used by `theme_for` when no name is provided.
       def default_theme(name = THEME_READER)
         return @default_theme || themes.keys.first if name == THEME_READER
 
         @default_theme = name.to_sym
       end
 
+      # Resolves a theme by *name* (or the default theme when *name* is nil). Returns the default
+      # built-in theme if no name is given and no default is registered.
       def theme_for(name = nil)
         theme_name = name || default_theme
         return Presentation::UI::Theme.default unless theme_name
@@ -58,6 +67,8 @@ module Charming
 
       private
 
+      # Expands a relative theme path against the app root (or the current working directory
+      # when no root is configured). Returns *path* unchanged when it is already absolute.
       def resolve_theme_path(path)
         return path if File.absolute_path?(path)
 

data/lib/charming/cli.rb

@@ -1,13 +1,23 @@
 # frozen_string_literal: true
 
 module Charming
+  # CLI dispatches the `charming` executable's subcommands to the appropriate generators
+  # or database commands. Subcommands:
+  # - `charming new NAME [--database sqlite3] [--force]` — scaffolds a new app
+  # - `charming generate TYPE NAME [args]` — runs a sub-generator (controller, model, screen, view, component)
+  # - `charming db:COMMAND` — runs a database command (db:create, db:migrate, db:rollback, db:drop, db:seed, db:install)
+  #
+  # Generator errors are caught and printed to stderr; the process exits with status 1.
   class CLI
+    # *out* defaults to `$stdout`, *err* to `$stderr`, *pwd* to `Dir.pwd` (overridable for tests).
     def initialize(out: $stdout, err: $stderr, pwd: Dir.pwd)
       @out = out
       @err = err
       @pwd = pwd
     end
 
+    # Runs the CLI with the given *argv* array. Returns 0 on success, 1 on a generator error,
+    # or the status from `usage` for unknown subcommands.
     def call(argv)
       command, *args = argv
       case command
@@ -23,8 +33,11 @@ module Charming
 
     private
 
+    # Standard output, standard error, and working directory used for generator destinations.
     attr_reader :out, :err, :pwd
 
+    # Handles `charming new`. Validates args, extracts `--database=` and `--force`,
+    # and runs AppGenerator. Returns 0 on success, raises Generators::Error on bad input.
     def new_app(args)
       force = args.delete("--force")
       database = extract_database(args)
@@ -35,6 +48,8 @@ module Charming
       0
     end
 
+    # Handles `charming generate TYPE NAME [args]`. Extracts `--force` and dispatches to
+    # the generator class for the requested type.
     def generate(args)
       force = args.delete("--force")
       type = args.shift || raise(Generators::Error, "Usage: charming generate TYPE NAME [actions]")
@@ -42,11 +57,13 @@ module Charming
       0
     end
 
+    # Builds the generator instance for the given *type*, popping the name from *args*.
     def generator(type, args, force)
       name = args.shift || raise(Generators::Error, "Usage: charming generate #{type} NAME")
       generator_class(type).new(name, args, out: out, destination: pwd, force: force)
     end
 
+    # Returns the generator class for a *type* string (controller, model, screen, view, component).
     def generator_class(type)
       {
         "controller" => Generators::ControllerGenerator,
@@ -57,6 +74,8 @@ module Charming
       }.fetch(type) { raise Generators::Error, "Unknown generator: #{type}" }
     end
 
+    # Routes `db:*` commands to either the install path (db:install) or the generic
+    # DatabaseCommands dispatcher.
     def database(command, args)
       if command == "db:install"
         database = args.shift || raise(Generators::Error, "Usage: charming db:install sqlite3")
@@ -71,6 +90,8 @@ module Charming
       0
     end
 
+    # Extracts the optional `--database=<value>` argument from *args*, removing it in place.
+    # Returns the validated database name (currently only "sqlite3") or nil when not given.
     def extract_database(args)
       inline = args.find { |arg| arg.start_with?("--database=") }
       return validate_database(args.delete(inline).split("=", 2).last) if inline
@@ -82,12 +103,14 @@ module Charming
       validate_database(args.delete_at(index) || raise(Generators::Error, "Usage: charming new NAME [--database sqlite3] [--force]"))
     end
 
+    # Validates that *database* is a supported adapter name. Currently only "sqlite3".
     def validate_database(database)
       return database if database == "sqlite3"
 
       raise Generators::Error, "Unsupported database: #{database.inspect}"
     end
 
+    # Prints a usage banner to stderr and returns *status* (1 for unknown commands).
     def usage(status)
       err.puts "Usage: charming new NAME | charming generate TYPE NAME [args] | charming db:COMMAND"
       status

data/lib/charming/controller/class_methods.rb

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

data/lib/charming/controller/command_palette.rb

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

data/lib/charming/controller/component_dispatching.rb

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

data/lib/charming/controller/dispatching.rb

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

data/lib/charming/controller/focus_management.rb

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