charming 0.1.1 → 0.1.2

data/lib/charming/presentation/ui.rb

@@ -32,36 +32,29 @@ module Charming
         blocks.join("\n" * (gap + 1))
       end
 
-      # Centers a *block* within a canvas of the given *width* and *height*, then returns the result.
-      def center(block, width:, height:, background: nil)
-        place(block, width: width, height: height, top: :center, left: :center, background: background)
+      # Places *block* onto a blank canvas of *width* × *height* at an offset determined by *top* (row)
+      # and *left* (column). Non-:center values are treated as absolute positions. When *background* is
+      # given, the assembled frame is wrapped so the theme bg paints the entire canvas — overlay content
+      # with its own bg overrides per-cell; resets re-apply the canvas bg.
+      def place(block, width:, height:, top: 0, left: 0, background: nil)
+        Canvas.new(width, height).place(block, top: top, left: left, background: background)
       end
 
       # Draws *overlay* on top of a base at the specified *top* (row) and *left* (column) coordinates,
       # defaulting to center in both directions. ANSI styling on the base content is preserved underneath.
       def overlay(base, overlay, top: :center, left: :center)
-        base_lines = base.to_s.lines(chomp: true)
-        overlay_lines = overlay.to_s.lines(chomp: true)
-        width = block_width(base_lines)
-        row = offset(top, base_lines.length, overlay_lines.length)
-        column = offset(left, width, block_width(overlay_lines))
-
-        draw_lines(base_lines, overlay_lines, row: row, column: column, width: width)
+        Canvas.parse(base).overlay(overlay, top: top, left: left).to_s
       end
 
-      # Places a *block* onto a blank canvas of *width* × *height* at an offset determined by *top* (row)
-      # and *left* (column). Non-:center values are treated as absolute positions. When *background* is
-      # given, the assembled frame is wrapped so the theme bg paints the entire canvas — overlay content
-      # with its own bg overrides per-cell; resets re-apply the canvas bg.
-      def place(block, width:, height:, top: 0, left: 0, background: nil)
-        lines = block.to_s.lines(chomp: true)
-        row = offset(top, height, lines.length)
-        column = offset(left, width, block_width(lines))
-        canvas = Array.new(height) { " " * width }
-        composed = draw_lines(canvas, lines, row: row, column: column, width: width)
-        return composed unless background
+      # Centers a *block* within a canvas of the given *width* and *height*, then returns the result.
+      def center(block, width:, height:, background: nil)
+        place(block, width: width, height: height, top: :center, left: :center, background: background)
+      end
 
-        Style.new.background(background).render(composed)
+      # Returns a visible-slice of *line* starting at *start_column* spanning *width* characters, preserving any
+      # ANSI escape sequences that were active at the start of the slice. Non-positive widths return `""`.
+      def visible_slice(line, start_column, width)
+        ANSISlicer.slice(line, start_column, width)
       end
 
       # Normalizes an array of mixed objects into arrays of lines by calling `#to_s` on each element.
@@ -93,140 +86,6 @@ module Charming
           line + (" " * (widths[block_index] - Width.measure(line)))
         end
       end
-
-      # Computes a placement coordinate: if *value* is `:center` the result centres the *size* within *available*;
-      # otherwise *value* is returned verbatim as an absolute integer position.
-      def offset(value, available, size)
-        return [(available - size) / 2, 0].max if value == :center
-
-        value
-      end
-
-      # Merges an *overlay_line* into a *base_line* at the given *column*, returning the combined string. The
-      # overlay replaces (covers) underlying characters; anything to the right that exceeds *width* is truncated.
-      def composed_overlay_line(base_line, overlay_line, column, width)
-        return visible_slice(base_line, 0, width) if column >= width
-        return visible_slice(base_line, 0, width) if column + Width.measure(overlay_line) <= 0
-
-        target_column = [column, 0].max
-        overlay_start = [0 - column, 0].max
-        overlay = visible_slice(overlay_line, overlay_start, width - target_column)
-        overlay_width = Width.measure(overlay)
-        return visible_slice(base_line, 0, width) if overlay_width.zero?
-
-        right_column = target_column + overlay_width
-
-        visible_slice(base_line, 0, target_column) +
-          overlay +
-          visible_slice(base_line, right_column, [width - right_column, 0].max)
-      end
-
-      # Returns a visible-slice of *line* starting at *start_column* spanning *width* characters, preserving any
-      # ANSI escape sequences that were active at the start of the slice. Non-positive widths return `""`.
-      def visible_slice(line, start_column, width)
-        return "" unless width.positive?
-
-        slice_visible_text(line.to_s, start_column, start_column + width)
-      end
-
-      # Slices a string by visible terminal columns while preserving ANSI style state.
-      def slice_visible_text(line, start_column, end_column)
-        state = {column: 0, output: +"", active: [], started: false, styled: false}
-
-        each_ansi_or_char(line) do |token, ansi|
-          if ansi
-            slice_ansi(token, state, start_column, end_column)
-          else
-            slice_char(token, state, start_column, end_column)
-          end
-        end
-
-        terminate_slice(state)
-      end
-
-      # Splits a *line* into token-range pieces bounded by *start_column* and *end_column*, preserving ANSI escapes
-      # that fall within the visible range. Yields each character or escape sequence along with whether it is ANSI.
-      def each_ansi_or_char(line)
-        index = 0
-        while index < line.length
-          match = line.match(Width::ANSI_PATTERN, index)
-          if match&.begin(0) == index
-            yield match[0], true
-            index = match.end(0)
-          else
-            char = line[index]
-            yield char, false
-            index += 1
-          end
-        end
-      end
-
-      # Slices an ANSI *token* (escape sequence) into *state*, writing active markers to the output if the current
-      # *column* falls within the [start_column, end_column) range. Resets styles on `[0m` sequences.
-      def slice_ansi(token, state, start_column, end_column)
-        started = state[:started]
-        update_active_styles(state[:active], token)
-        return unless state[:column].between?(start_column, end_column - 1)
-
-        start_slice(state)
-        if started
-          state[:output] << token
-          state[:styled] = !token.include?("[0m")
-        end
-      end
-
-      # Slices a plain *char* into *state*, advancing the column tracker by the character's visual width. If the
-      # character overlaps with the [start_column, end_column) range it is appended to the output.
-      def slice_char(char, state, start_column, end_column)
-        char_width = Width.measure(char)
-        char_start = state[:column]
-        char_end = char_start + char_width
-        state[:column] = char_end
-        return unless char_end > start_column && char_start < end_column
-
-        start_slice(state)
-        state[:output] << char
-      end
-
-      # Starts writing to the output buffer, flushing any active ANSI markers if this is the first character placed.
-      def start_slice(state)
-        return if state[:started]
-
-        state[:output] << state[:active].join
-        state[:styled] = true unless state[:active].empty?
-        state[:started] = true
-      end
-
-      # Closes the slice by appending a final `[0m` reset escape to the output unless no active styling exists or
-      # nothing was written. Returns the fully constructed output string with trailing reset applied.
-      def terminate_slice(state)
-        return state[:output] if !state[:styled] || state[:output].empty?
-
-        "#{state[:output]}\e[0m"
-      end
-
-      # Updates *state*[:active] with an ANSI *token*: resets all active styles on `[0m` or appends the token as a
-      # new active marker otherwise. Called during each_ansi_or_char iteration.
-      def update_active_styles(active, token)
-        if token.include?("[0m")
-          active.clear
-        else
-          active << token
-        end
-      end
-
-      # Overlays *lines* onto a *canvas* starting at (*row*, *column*), writing each overlaid line into the canvas
-      # via `composed_overlay_line`. Returns the final canvas joined by newlines.
-      def draw_lines(canvas, lines, row:, column:, width:)
-        lines.each_with_index do |line, index|
-          line_index = row + index
-          next if line_index.negative? || line_index >= canvas.length
-
-          canvas[line_index] = composed_overlay_line(canvas[line_index], line, column, width)
-        end
-
-        canvas.join("\n")
-      end
     end
   end
 end

data/lib/charming/presentation/view.rb

@@ -78,6 +78,13 @@ module Charming
         render_component(partial)
       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
+
       # 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, "")
@@ -113,6 +120,16 @@ module Charming
           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
 end

data/lib/charming/runtime.rb

@@ -75,6 +75,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

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.2"
 end

data/lib/charming.rb

@@ -6,18 +6,31 @@ 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.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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: charming
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 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,11 +231,48 @@ 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
@@ -261,14 +297,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

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

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module Charming
-  module Generators
-    class AppGenerator
-      module BasicTemplates
-        def gemfile
-          %(# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-gemspec
-)
-        end
-
-        def rakefile
-          %(# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-)
-        end
-
-        def readme
-          %(# #{name.class_name}
-
-A Charming terminal user interface.
-
-Run it with:
-
-```sh
-bundle exec #{name.snake_name}
-```
-)
-        end
-
-        def gemspec
-          %(# frozen_string_literal: true
-
-require_relative "lib/#{name.snake_name}/version"
-
-Gem::Specification.new do |spec|
-#{gemspec_attributes}
-#{gemspec_dependencies}
-end
-)
-        end
-
-        def gemspec_attributes
-          %(  spec.name = "#{name.snake_name}"
-  spec.version = #{name.class_name}::VERSION
-  spec.summary = "A Charming terminal user interface."
-  spec.authors = ["TODO: Your name"]
-  spec.email = ["TODO: Your email"]
-  spec.files = Dir.glob("#{gemspec_file_glob}/**/*") + %w[README.md]
-  spec.bindir = "exe"
-  spec.executables = ["#{name.snake_name}"]
-  spec.require_paths = ["lib"]
-  spec.required_ruby_version = ">= 4.0.0"
-  spec.metadata["rubygems_mfa_required"] = "true")
-        end
-
-        def gemspec_dependencies
-          %(
-  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
-  end
-end