charming 0.1.1 → 0.1.3

data/lib/charming/presentation/view.rb

@@ -1,118 +1,133 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    # View is the base class for all screen view implementations. It provides assign injection (via `initialize`),
-    # rendering hooks, layout composition helpers (`row`, `column`, `render_component`, `yield_content`),
-    # and access to controller theme, style, and focus state from within views.
-    class View
-      # Initializes the view with named assigns injected as instance-local accessor methods via
-      # `define_singleton_method`. Called when a controller instantiates a view for rendering.
-      def initialize(**assigns)
-        @assigns = assigns
-        define_assign_readers
-      end
+  # View is the base class for all screen view implementations. It provides assign injection (via `initialize`),
+  # rendering hooks, layout composition helpers (`row`, `column`, `render_component`, `yield_content`),
+  # and access to controller theme, style, and focus state from within views.
+  class View
+    # Initializes the view with named assigns injected as instance-local accessor methods via
+    # `define_singleton_method`. Called when a controller instantiates a view for rendering.
+    def initialize(**assigns)
+      @assigns = assigns
+      define_assign_readers
+    end
 
-      # Returns all view assigns as a hash, used by layouts to compose the full template (content + screen + controller).
-      def layout_assigns
-        assigns
-      end
+    # Returns all view assigns as a hash, used by layouts to compose the full template (content + screen + controller).
+    def layout_assigns
+      assigns
+    end
 
-      # Renders the view's body. Default is empty — subclasses override to return visible text.
-      def render
-        ""
-      end
+    # Renders the view's body. Default is empty — subclasses override to return visible text.
+    def render
+      ""
+    end
 
-      # Delegates focus checking to the controller in assigns, allowing views to determine which slot (sidebar, content) has focus.
-      def focused?(slot)
-        ctrl = assigns[:focus_controller] || assigns[:controller]
-        ctrl ? ctrl.focused?(slot) : false
-      end
+    # Delegates focus checking to the controller in assigns, allowing views to determine which slot (sidebar, content) has focus.
+    def focused?(slot)
+      ctrl = assigns[:focus_controller] || assigns[:controller]
+      ctrl ? ctrl.focused?(slot) : false
+    end
 
-      private
+    private
 
-      attr_reader :assigns
+    attr_reader :assigns
 
-      # Returns the shared UI style configuration used by components and views for visual rendering (colors, borders).
-      def style
-        UI.style
-      end
+    # Returns the shared UI style configuration used by components and views for visual rendering (colors, borders).
+    def style
+      UI.style
+    end
 
-      # Returns the active theme: uses `theme` from assigns or controller, falling back to `UI::Theme.default`.
-      def theme
-        assigns[:theme] || assigns[:controller]&.theme || UI::Theme.default
-      end
+    # Returns the active theme: uses `theme` from assigns or controller, falling back to `UI::Theme.default`.
+    def theme
+      assigns[:theme] || assigns[:controller]&.theme || UI::Theme.default
+    end
 
-      # Outputs styled text through the view's rendering pipeline. Accepts a named `style:` for inline formatting.
-      # Appends the rendered value to the output buffer and returns it.
-      def text(value, style: nil)
-        rendered = apply_style(value.to_s, style)
-        append_to_buffer(rendered)
-        rendered
-      end
+    # Outputs styled text through the view's rendering pipeline. Accepts a named `style:` for inline formatting.
+    # Appends the rendered value to the output buffer and returns it.
+    def text(value, style: nil)
+      rendered = apply_style(value.to_s, style)
+      append_to_buffer(rendered)
+      rendered
+    end
 
-      # Renders a box with optional styling. Accepts an inline block for complex content or a plain value.
-      # Used for bordered containers and field groups in views.
-      def box(value = nil, style: nil, &)
-        content = block_given? ? capture(&) : value.to_s
-        apply_style(content, style)
-      end
+    # Renders a box with optional styling. Accepts an inline block for complex content or a plain value.
+    # Used for bordered containers and field groups in views.
+    def box(value = nil, style: nil, &)
+      content = block_given? ? capture(&) : value.to_s
+      apply_style(content, style)
+    end
 
-      # Joins items horizontally (side-by-side) using the UI rendering engine. Supports a `gap:` parameter.
-      def row(*items, gap: 0)
-        UI.join_horizontal(*items, gap: gap)
-      end
+    # Joins items horizontally (side-by-side) using the UI rendering engine. Supports a `gap:` parameter.
+    def row(*items, gap: 0)
+      UI.join_horizontal(*items, gap: gap)
+    end
 
-      # Stacks items vertically using the UI rendering engine. Supports a `gap:` parameter for spacing.
-      def column(*items, gap: 0)
-        UI.join_vertical(*items, gap: gap)
-      end
+    # Stacks items vertically using the UI rendering engine. Supports a `gap:` parameter for spacing.
+    def column(*items, gap: 0)
+      UI.join_vertical(*items, gap: gap)
+    end
 
-      # Renders a component (e.g., a ProgressBar, Spinner, Modal) and returns its string output.
-      def render_component(component)
-        component.render.to_s
-      end
+    # Renders a component (e.g., a ProgressBar, Spinner, Modal) and returns its string output.
+    def render_component(component)
+      component.render.to_s
+    end
 
-      # Renders a partial view component. An alias for `render_component` used in layout templates.
-      def render_partial(partial)
-        render_component(partial)
-      end
+    # Renders a partial view component. An alias for `render_component` used in layout templates.
+    def render_partial(partial)
+      render_component(partial)
+    end
 
-      # Yields the layout's `content` slot — used by view templates to inject their body into a layout wrapper (e.g., sidebar).
-      def yield_content
-        assigns.fetch(:content, "")
-      end
+    # Builds a declarative layout tree for the current terminal screen and renders it.
+    def screen_layout(background: nil, &)
+      layout = Layout::Builder.build(screen: layout_screen, view: self, background: background, &)
+      register_layout_focus(layout)
+      layout.render
+    end
 
-      # Evaluates a block in the view's context with a clean output buffer. Captures text written via `text`/`box`
-      # and returns joined content. Resets buffer afterward for parent rendering.
-      def capture(&)
-        previous_buffer = @output_buffer
-        @output_buffer = []
-        result = instance_eval(&)
-        @output_buffer.empty? ? result.to_s : @output_buffer.join("\n")
-      ensure
-        @output_buffer = previous_buffer
-      end
+    # Yields the layout's `content` slot — used by view templates to inject their body into a layout wrapper (e.g., sidebar).
+    def yield_content
+      assigns.fetch(:content, "")
+    end
 
-      # Appends a value to the current output buffer (if one is active). Used by rendering helpers.
-      def append_to_buffer(value)
-        @output_buffer << value if @output_buffer
-      end
+    # Evaluates a block in the view's context with a clean output buffer. Captures text written via `text`/`box`
+    # and returns joined content. Resets buffer afterward for parent rendering.
+    def capture(&)
+      previous_buffer = @output_buffer
+      @output_buffer = []
+      result = instance_eval(&)
+      @output_buffer.empty? ? result.to_s : @output_buffer.join("\n")
+    ensure
+      @output_buffer = previous_buffer
+    end
 
-      # Applies a style object's `render` method to a string, returning styled output or raw text when style is nil.
-      def apply_style(value, style_object)
-        style_object ? style_object.render(value) : value
-      end
+    # Appends a value to the current output buffer (if one is active). Used by rendering helpers.
+    def append_to_buffer(value)
+      @output_buffer << value if @output_buffer
+    end
 
-      # Dynamically defines read-only accessor methods for each assign key as singleton methods on self.
-      # Skips keys where the view already responds (controller methods take precedence).
-      def define_assign_readers
-        assigns.each_key do |name|
-          next if respond_to?(name, true)
+    # Applies a style object's `render` method to a string, returning styled output or raw text when style is nil.
+    def apply_style(value, style_object)
+      style_object ? style_object.render(value) : value
+    end
 
-          define_singleton_method(name) { assigns.fetch(name) }
-        end
+    # Dynamically defines read-only accessor methods for each assign key as singleton methods on self.
+    # Skips keys where the view already responds (controller methods take precedence).
+    def define_assign_readers
+      assigns.each_key do |name|
+        next if respond_to?(name, true)
+
+        define_singleton_method(name) { assigns.fetch(name) }
       end
     end
+
+    def layout_screen
+      assigns[:screen] || assigns[:controller]&.screen || Charming::Screen.new(width: 80, height: 24)
+    end
+
+    def register_layout_focus(layout)
+      return unless assigns[:controller]
+
+      assigns[:controller].focus.define_layout(layout.focusable_names)
+    end
   end
 end

data/lib/charming/runtime.rb

@@ -26,19 +26,21 @@ module Charming
     # restores terminal state on exit.
     def run
       setup_terminal
-      render(resolve_response(dispatch(@route.action)))
-      loop do
-        event = next_task_event || next_timer_event || @backend.read_event(timeout: read_timeout)
-        next unless event
+      with_raw_input do
+        render(resolve_response(dispatch(@route.action)))
+        loop do
+          event = next_task_event || next_timer_event || @backend.read_event(timeout: read_timeout)
+          next unless event
 
-        response = dispatch_event(event)
-        next unless response
-        break if response.quit?
+          response = dispatch_event(event)
+          next unless response
+          break if response.quit?
 
-        response = resolve_response(response)
-        break if response.quit?
+          response = resolve_response(response)
+          break if response.quit?
 
-        render(response)
+          render(response)
+        end
       end
     ensure
       @task_executor&.shutdown(timeout: 0.0)
@@ -75,6 +77,8 @@ module Charming
       controller(event: event).dispatch_mouse
     end
 
+    # Instantiates a fresh controller for the active route, passing the application, current *event*,
+    # route params, screen dimensions, and route object. Called by every dispatch path.
     def controller(event: nil)
       @route.controller_class.new(application: @application, event: event, params: @route.params, screen: screen, route: @route)
     end
@@ -91,8 +95,12 @@ module Charming
     end
 
     # Dispatches a resize event: updates screen dimensions and re-renders the current action.
+    # The renderer's cached previous frame is invalidated and the backend is cleared so the
+    # new-dimension frame paints onto a clean alt-screen instead of overlaying stale rows.
     def dispatch_resize(event)
       @screen = Screen.new(width: event.width, height: event.height)
+      @renderer.invalidate if @renderer.respond_to?(:invalidate)
+      @backend.clear if @backend.respond_to?(:clear)
       dispatch(@route.action, event: event)
     end
 
@@ -181,6 +189,13 @@ module Charming
       @backend.install_resize_handler if @backend.respond_to?(:install_resize_handler)
     end
 
+    # Keeps input raw/no-echo across rendering and dispatch, not just during reads.
+    def with_raw_input(&block)
+      return yield unless @backend.respond_to?(:with_raw_input)
+
+      @backend.with_raw_input(&block)
+    end
+
     # Restores terminal state: reinstalls any previous resize handler, shows
     # the cursor, and leaves the alternative screen buffer.
     def restore_terminal

data/lib/charming/tasks/inline_executor.rb

@@ -2,22 +2,31 @@
 
 module Charming
   module Tasks
+    # InlineExecutor runs submitted tasks synchronously on the calling thread, pushing
+    # the resulting TaskEvent directly into the runtime's *queue*. Used for testing and
+    # for environments where spawning background threads is undesirable.
     class InlineExecutor
+      # *queue* is the thread-safe Queue (typically `runtime.@task_queue`) into which
+      # completed TaskEvents are pushed.
       def initialize(queue)
         @queue = queue
       end
 
+      # Wraps *block* in a Task, invokes it immediately, and pushes the resulting
+      # TaskEvent (value or error) onto the queue. Returns nil.
       def submit(name, &block)
         task = Task.new(name: name.to_sym, block: block)
         @queue << run(task)
         nil
       end
 
+      # No-op stub for the shutdown contract; nothing to join since tasks run on the caller.
       def shutdown(timeout: 0.0)
       end
 
       private
 
+      # Invokes the task's block and wraps the result (or raised exception) in a TaskEvent.
       def run(task)
         Events::TaskEvent.new(name: task.name, value: task.call)
       rescue StandardError, ScriptError => e

data/lib/charming/tasks/task.rb

@@ -2,7 +2,10 @@
 
 module Charming
   module Tasks
+    # Task is the unit of work submitted to a task executor. It pairs a *name* (used by
+    # `on_task` handlers to route the result) with a *block* to invoke on the executor.
     Task = Data.define(:name, :block) do
+      # Invokes the task's block in the executor's thread and returns its value (or raises).
       def call = block.call
     end
   end

data/lib/charming/tasks/threaded_executor.rb

@@ -2,13 +2,22 @@
 
 module Charming
   module Tasks
+    # ThreadedExecutor runs submitted tasks on background Ruby threads. Each submission
+    # creates a new thread that invokes the block and pushes the resulting TaskEvent
+    # onto the shared *queue*. Threads are tracked so `shutdown` can wait (or kill)
+    # in-flight work.
     class ThreadedExecutor
+      # *queue* is the thread-safe Queue (typically `runtime.@task_queue`) into which
+      # completed TaskEvents are pushed.
       def initialize(queue)
         @queue = queue
         @threads = []
         @mutex = Mutex.new
       end
 
+      # Wraps *block* in a Task and spawns a new thread to invoke it. The thread's
+      # return value (or rescued exception) is pushed onto the queue as a TaskEvent.
+      # Returns nil immediately.
       def submit(name, &block)
         task = Task.new(name: name.to_sym, block: block)
         thread = Thread.new(task) { |t| @queue << run(t) }
@@ -16,6 +25,8 @@ module Charming
         nil
       end
 
+      # Waits up to *timeout* seconds for in-flight threads to finish, then kills any
+      # remaining live threads. Used by Runtime during teardown.
       def shutdown(timeout: 0.0)
         threads = @mutex.synchronize { @threads.dup }
         threads.each { |thread| thread.join(timeout) }
@@ -29,6 +40,7 @@ module Charming
 
       private
 
+      # Invokes the task's block and wraps the result (or rescued exception) in a TaskEvent.
       def run(task)
         Events::TaskEvent.new(name: task.name, value: task.call)
       rescue StandardError, ScriptError => e

data/lib/charming/version.rb

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

data/lib/charming.rb

@@ -6,23 +6,37 @@ loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "cli" => "CLI",
   "ui" => "UI",
+  "ansi_codes" => "ANSICodes",
+  "ansi_slicer" => "ANSISlicer",
+  "border_painter" => "BorderPainter",
+  "block_renderers" => "BlockRenderer",
+  "inline_renderers" => "InlineRenderer",
+  "render_context" => "RenderContext",
   "erb_handler" => "ErbHandler",
+  "key_normalizer" => "KeyNormalizer",
+  "mouse_parser" => "MouseParser",
   "tty_backend" => "TTYBackend"
 )
+loader.collapse("#{__dir__}/charming/presentation")
 loader.setup
 
 module Charming
+  # Base error class for all Charming-specific exceptions (used by templates, generators, runtime, etc.).
   class Error < StandardError; end
 
+  # Entry point for running a Charming application. Instantiates a Runtime for *application* and starts
+  # the event loop. *backend* defaults to TTYBackend; tests pass MemoryBackend directly via `Charming::Runtime.new`.
   def self.run(application, backend: nil)
     Runtime.new(application, backend: backend).run
   end
 
+  # Returns the normalized key symbol for an event-like object — `event.key` when the object responds
+  # to it, otherwise `event.to_sym`. Lets components treat raw strings and KeyEvent objects uniformly.
   def self.key_of(event)
     key = event.respond_to?(:key) ? event.key : event
     key.to_sym
   end
 end
 
-Charming::Presentation::Templates.register ".tui.erb", Charming::Presentation::Templates::ErbHandler
-Charming::Presentation::Templates.register ".txt.erb", Charming::Presentation::Templates::ErbHandler
+Charming::Templates.register ".tui.erb", Charming::Templates::ErbHandler
+Charming::Templates.register ".txt.erb", Charming::Templates::ErbHandler

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: charming
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - pando
@@ -206,6 +206,14 @@ files:
 - lib/charming/application_state.rb
 - lib/charming/cli.rb
 - lib/charming/controller.rb
+- lib/charming/controller/class_methods.rb
+- lib/charming/controller/command_palette.rb
+- lib/charming/controller/component_dispatching.rb
+- lib/charming/controller/dispatching.rb
+- lib/charming/controller/focus_management.rb
+- lib/charming/controller/rendering.rb
+- lib/charming/controller/session_state.rb
+- lib/charming/controller/sidebar_navigation.rb
 - lib/charming/database_commands.rb
 - lib/charming/database_installer.rb
 - lib/charming/events/key_event.rb
@@ -216,15 +224,6 @@ files:
 - lib/charming/focus.rb
 - lib/charming/generators/app_file_generator.rb
 - lib/charming/generators/app_generator.rb
-- lib/charming/generators/app_generator/app_spec_templates.rb
-- lib/charming/generators/app_generator/basic_templates.rb
-- lib/charming/generators/app_generator/component_templates.rb
-- lib/charming/generators/app_generator/controller_template.rb
-- lib/charming/generators/app_generator/database_templates.rb
-- lib/charming/generators/app_generator/layout_template.rb
-- lib/charming/generators/app_generator/screen_spec_templates.rb
-- lib/charming/generators/app_generator/state_templates.rb
-- lib/charming/generators/app_generator/view_template.rb
 - lib/charming/generators/base.rb
 - lib/charming/generators/component_generator.rb
 - lib/charming/generators/controller_generator.rb
@@ -232,15 +231,53 @@ files:
 - lib/charming/generators/model_generator.rb
 - lib/charming/generators/name.rb
 - lib/charming/generators/screen_generator.rb
+- lib/charming/generators/templates/app/Gemfile.template
+- lib/charming/generators/templates/app/README.md.template
+- lib/charming/generators/templates/app/Rakefile.template
+- lib/charming/generators/templates/app/application.template
+- lib/charming/generators/templates/app/application_controller.template
+- lib/charming/generators/templates/app/application_record.template
+- lib/charming/generators/templates/app/application_state.template
+- lib/charming/generators/templates/app/database_config.template
+- lib/charming/generators/templates/app/executable.template
+- lib/charming/generators/templates/app/gemspec.template
+- lib/charming/generators/templates/app/home_controller.template
+- lib/charming/generators/templates/app/home_state.template
+- lib/charming/generators/templates/app/keep.template
+- lib/charming/generators/templates/app/layout.template
+- lib/charming/generators/templates/app/root_file.template
+- lib/charming/generators/templates/app/routes.template
+- lib/charming/generators/templates/app/seeds.template
+- lib/charming/generators/templates/app/spec_controller.template
+- lib/charming/generators/templates/app/spec_helper.template
+- lib/charming/generators/templates/app/spec_state.template
+- lib/charming/generators/templates/app/spec_view.template
+- lib/charming/generators/templates/app/version.template
+- lib/charming/generators/templates/app/view.template
+- lib/charming/generators/templates/component/component.rb.template
+- lib/charming/generators/templates/controller/controller.rb.template
+- lib/charming/generators/templates/model/migration.rb.template
+- lib/charming/generators/templates/model/model.rb.template
+- lib/charming/generators/templates/model/spec.rb.template
+- lib/charming/generators/templates/screen/controller.rb.template
+- lib/charming/generators/templates/screen/spec_controller.rb.template
+- lib/charming/generators/templates/screen/spec_state.rb.template
+- lib/charming/generators/templates/screen/spec_view.rb.template
+- lib/charming/generators/templates/screen/state.rb.template
+- lib/charming/generators/templates/screen/view.rb.template
+- lib/charming/generators/templates/view/view.rb.template
 - lib/charming/generators/view_generator.rb
 - lib/charming/internal/renderer/differential.rb
 - lib/charming/internal/renderer/full_repaint.rb
 - lib/charming/internal/terminal/adapter.rb
+- lib/charming/internal/terminal/key_normalizer.rb
 - lib/charming/internal/terminal/memory_backend.rb
+- lib/charming/internal/terminal/mouse_parser.rb
 - lib/charming/internal/terminal/tty_backend.rb
 - lib/charming/presentation/component.rb
 - lib/charming/presentation/components/activity_indicator.rb
 - lib/charming/presentation/components/command_palette.rb
+- lib/charming/presentation/components/command_palette_modal.rb
 - lib/charming/presentation/components/empty_state.rb
 - lib/charming/presentation/components/form.rb
 - lib/charming/presentation/components/form/builder.rb
@@ -261,14 +298,27 @@ files:
 - lib/charming/presentation/components/text_input.rb
 - lib/charming/presentation/components/viewport.rb
 - lib/charming/presentation/layout.rb
+- lib/charming/presentation/layout/builder.rb
+- lib/charming/presentation/layout/overlay.rb
+- lib/charming/presentation/layout/pane.rb
+- lib/charming/presentation/layout/rect.rb
+- lib/charming/presentation/layout/screen_layout.rb
+- lib/charming/presentation/layout/split.rb
 - lib/charming/presentation/markdown.rb
+- lib/charming/presentation/markdown/block_renderers.rb
+- lib/charming/presentation/markdown/inline_renderers.rb
+- lib/charming/presentation/markdown/render_context.rb
 - lib/charming/presentation/markdown/renderer.rb
 - lib/charming/presentation/markdown/syntax_highlighter.rb
 - lib/charming/presentation/template_view.rb
 - lib/charming/presentation/templates.rb
 - lib/charming/presentation/templates/erb_handler.rb
 - lib/charming/presentation/ui.rb
+- lib/charming/presentation/ui/ansi_codes.rb
+- lib/charming/presentation/ui/ansi_slicer.rb
 - lib/charming/presentation/ui/border.rb
+- lib/charming/presentation/ui/border_painter.rb
+- lib/charming/presentation/ui/canvas.rb
 - lib/charming/presentation/ui/style.rb
 - lib/charming/presentation/ui/theme.rb
 - lib/charming/presentation/ui/themes/phosphor.json

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

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Charming
-  module Generators
-    class AppGenerator
-      module AppSpecTemplates
-        def spec_state
-          %(# frozen_string_literal: true
-
-require "#{app_name.snake_name}"
-
-RSpec.describe #{app_name.class_name}::HomeState do
-  describe "#title" do
-    it "has the correct default string value" do
-      instance = described_class.new
-      expect(instance.title).to eq("#{app_name.class_name}")
-    end
-
-    it "accepts overridden title values" do
-      instance = described_class.new(title: "Alternative")
-      expect(instance.title).to eq("Alternative")
-    end
-  end
-end
-)
-        end
-
-        def spec_controller
-          %(# frozen_string_literal: true
-
-require "#{app_name.snake_name}"
-
-RSpec.describe #{app_name.class_name}::HomeController do
-  let(:application) { #{app_name.class_name}::Application.new }
-
-  subject(:controller) { described_class.new(application: application) }
-
-  describe "#show" do
-    it "renders the view with the state" do
-      response = controller.dispatch(:show)
-
-      expect(response).to respond_to(:body)
-    end
-  end
-end
-)
-        end
-
-        def spec_view
-          %(# frozen_string_literal: true
-
-require "#{app_name.snake_name}"
-
-RSpec.describe "home/show template" do
-  describe "#render" do
-    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
-  end
-end
-)
-        end
-
-        def spec_component
-          %(# frozen_string_literal: true
-
-require "#{app_name.snake_name}"
-
-RSpec.describe #{app_name.class_name}::AppFrameComponent do
-  describe "#render" do
-    it "returns a string" do
-      component = described_class.new(title: "#{app_name.class_name}")
-      expect(component.render).to be_a(String)
-    end
-  end
-end
-)
-        end
-      end
-    end
-  end
-end