charming 0.1.0 → 0.1.2

data/lib/charming/presentation/ui/theme.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Charming
+  module Presentation
+    module UI
+      class Theme
+        BUILT_IN_ROOT = File.expand_path("themes", __dir__)
+
+        DEFAULT_TOKENS = {
+          text: {foreground: :bright_white},
+          title: {foreground: :bright_cyan, bold: true},
+          muted: {foreground: :bright_black},
+          border: {foreground: :bright_magenta},
+          selected: {reverse: true},
+          info: {foreground: :bright_cyan},
+          warn: {foreground: :yellow}
+        }.freeze
+
+        def self.default
+          @default ||= load_builtin("phosphor")
+        end
+
+        def self.load_file(path)
+          from_hash(JSON.parse(File.read(path)))
+        end
+
+        def self.load_builtin(name)
+          load_file(built_in_path(name))
+        end
+
+        def self.built_in_names
+          Dir.glob(File.join(BUILT_IN_ROOT, "*.json")).map { |path| File.basename(path, ".json") }.sort
+        end
+
+        def self.from_hash(value)
+          raise ArgumentError, "theme file must contain an object" unless value.is_a?(Hash)
+
+          styles = value.fetch("styles") do
+            raise ArgumentError, "theme file must contain styles"
+          end
+
+          palette = value.fetch("palette", {})
+          new(
+            resolve_palette_references(styles, palette),
+            background: resolve_background(value["background"], palette)
+          )
+        end
+
+        def self.resolve_background(value, palette)
+          return unless value
+
+          deep_resolve_colors(value, normalize_colors(palette))
+        end
+
+        def self.built_in_path(name)
+          slug = name.to_s
+          raise ArgumentError, "unknown built-in theme: #{name.inspect}" unless built_in_names.include?(slug)
+
+          File.join(BUILT_IN_ROOT, "#{slug}.json")
+        end
+
+        def self.resolve_palette_references(styles, palette)
+          palette = normalize_colors(palette)
+          deep_resolve_colors(styles, palette)
+        end
+
+        def self.deep_resolve_colors(value, palette)
+          case value
+          when Hash
+            value.transform_values { |item| deep_resolve_colors(item, palette) }
+          when Array
+            value.map { |item| deep_resolve_colors(item, palette) }
+          when String
+            palette.fetch(value, normalize_color(value) || value)
+          else
+            value
+          end
+        end
+
+        def self.normalize_colors(values)
+          values.transform_values { |value| normalize_color(value) }.compact
+        end
+
+        def self.normalize_color(value)
+          return unless value.is_a?(String)
+
+          case value
+          when /\A#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])(?:[0-9a-fA-F])?\z/
+            "#{$1 * 2}#{$2 * 2}#{$3 * 2}".prepend("#")
+          when /\A#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?\z/
+            value[0, 7]
+          end
+        end
+
+        attr_reader :background
+
+        def initialize(tokens = {}, background: nil)
+          @tokens = symbolize_keys(tokens)
+          @background = background
+        end
+
+        def style(name)
+          spec = @tokens.fetch(name.to_sym) do
+            raise ArgumentError, "unknown theme token: #{name.inspect}"
+          end
+
+          build_style(spec)
+        end
+        alias_method :[], :style
+
+        def method_missing(name, ...)
+          return style(name) if @tokens.key?(name)
+
+          super
+        end
+
+        def respond_to_missing?(name, include_private = false)
+          @tokens.key?(name) || super
+        end
+
+        private
+
+        def build_style(spec)
+          return spec if spec.is_a?(Style)
+          return UI.style.foreground(spec) unless spec.is_a?(Hash)
+
+          apply_options(UI.style, symbolize_keys(spec))
+        end
+
+        def apply_options(base_style, spec)
+          styled = apply_colors(base_style, spec)
+          styled = apply_attributes(styled, spec)
+          apply_layout(styled, spec)
+        end
+
+        def apply_colors(base_style, spec)
+          styled = base_style
+          styled = styled.foreground(spec[:foreground] || spec[:fg]) if spec.key?(:foreground) || spec.key?(:fg)
+          styled = styled.background(spec[:background] || spec[:bg]) if spec.key?(:background) || spec.key?(:bg)
+          styled
+        end
+
+        def apply_attributes(base_style, spec)
+          Style::ATTRIBUTES.each_key.reduce(base_style) do |styled, attribute|
+            spec[attribute] ? styled.public_send(attribute) : styled
+          end
+        end
+
+        def apply_layout(base_style, spec)
+          styled = base_style
+          styled = styled.padding(*Array(spec[:padding])) if spec.key?(:padding)
+          styled = apply_border(styled, spec[:border]) if spec.key?(:border)
+          styled = styled.width(spec[:width]) if spec.key?(:width)
+          styled = styled.height(spec[:height]) if spec.key?(:height)
+          styled = styled.align(spec[:align].to_sym) if spec.key?(:align)
+          styled
+        end
+
+        def apply_border(base_style, border_spec)
+          return base_style.border(border_spec) unless border_spec.is_a?(Hash)
+
+          border_spec = symbolize_keys(border_spec)
+          base_style.border(
+            border_spec.fetch(:style, :normal),
+            sides: border_spec[:sides],
+            foreground: border_spec[:foreground] || border_spec[:fg]
+          )
+        end
+
+        def symbolize_keys(value)
+          value.each_with_object({}) do |(key, item), result|
+            result[key.to_sym] = item.is_a?(Hash) ? symbolize_keys(item) : item
+          end
+        end
+      end
+    end
+  end
+end

data/lib/charming/{ui → presentation/ui}/themes/phosphor.json

@@ -4,11 +4,11 @@
   "background": "background",
   "palette": {
     "bright": "#9FE8B0",
-    "muted": "#5A8A68",
+    "muted": "#7FB98C",
     "subtle": "#788E80",
     "background": "#111A2C",
     "selected": "#18233D",
-    "divider": "#2A3752",
+    "divider": "#536B91",
     "amber": "#FFB347",
     "cyan": "#6FD0E3"
   },

data/lib/charming/presentation/ui/width.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "unicode/display_width"
+
+module Charming
+  module Presentation
+    module UI
+      # Width is a namespace for measuring and normalising the visual width of strings that may contain
+      # ANSI escape sequences. It delegates to `Unicode::DisplayWidth` while automatically stripping
+      # formatting codes so layout primitives can calculate exact character positions.
+      module Width
+        ANSI_PATTERN = /\e\[[0-9;]*m/
+
+        module_function
+
+        def measure(value)
+          Unicode::DisplayWidth.of(strip_ansi(value.to_s))
+        end
+
+        def strip_ansi(value)
+          value.to_s.gsub(ANSI_PATTERN, "")
+        end
+      end
+    end
+  end
+end

data/lib/charming/presentation/ui.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    # UI is a module of layout primitives for composing and positioning ANSI-styled
+    # terminal text. It provides functions to join blocks horizontally or vertically,
+    # place content on fixed-size canvases, overlay elements, and slice strings that
+    # contain ANSI escape sequences while preserving their styling.
+    module UI
+      module_function
+
+      # Builds a new {Style} instance for chaining color, padding, alignment, and other visual properties.
+      def style
+        Style.new
+      end
+
+      # Horizontally concatenates *blocks* into a single multi-line string, padding each block's
+      # rows to match the widest row. A *gap* argument (in spaces) can separate adjacent columns.
+      def join_horizontal(*blocks, gap: 0)
+        normalized = normalize_blocks(blocks)
+        widths = block_widths(normalized)
+        separator = " " * gap
+
+        Array.new(block_height(normalized)) do |index|
+          horizontal_line(normalized, widths, index).join(separator)
+        end.join("\n")
+      end
+
+      # Stacks *blocks* vertically separated by one or more blank lines. A *gap* of N inserts N
+      # extra newline characters between blocks (1 gap = 1 blank line, 2 gaps = 2 blank lines, etc.).
+      def join_vertical(*blocks, gap: 0)
+        blocks.join("\n" * (gap + 1))
+      end
+
+      # 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)
+        Canvas.parse(base).overlay(overlay, top: top, left: left).to_s
+      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)
+      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)
+        ANSISlicer.slice(line, start_column, width)
+      end
+
+      # Normalizes an array of mixed objects into arrays of lines by calling `#to_s` on each element.
+      def normalize_blocks(blocks)
+        blocks.map { |block| block.to_s.lines(chomp: true) }
+      end
+
+      # Measures the displayed (visual) width of each normalised block, returning an array of integer widths.
+      def block_widths(blocks)
+        blocks.map { |lines| lines.map { |line| Width.measure(line) }.max || 0 }
+      end
+
+      # Returns the maximum visual character width across all *lines*, accounting for multi-column characters
+      # (e.g., full-width CJK glyphs) and invisible ANSI escape sequences.
+      def block_width(lines)
+        lines.map { |line| Width.measure(line) }.max || 0
+      end
+
+      # Returns the height in rows of each normalised block, taking the maximum across all blocks.
+      def block_height(blocks)
+        blocks.map(&:length).max || 0
+      end
+
+      # Builds a single horizontal row by concatenating one line from each *block* at index *index*, padding
+      # every segment to its corresponding *width* in spaces. Returns the assembled array of padded segments.
+      def horizontal_line(blocks, widths, index)
+        blocks.each_with_index.map do |lines, block_index|
+          line = lines[index] || ""
+          line + (" " * (widths[block_index] - Width.measure(line)))
+        end
+      end
+    end
+  end
+end

data/lib/charming/presentation/view.rb

@@ -0,0 +1,135 @@
+# 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
+
+      # 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
+
+      # 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
+
+      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 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
+
+      # 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
+
+      # 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 partial view component. An alias for `render_component` used in layout templates.
+      def render_partial(partial)
+        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, "")
+      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
+
+      # 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
+
+      # 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
+
+      # 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
+end

data/lib/charming/runtime.rb

@@ -75,17 +75,19 @@ 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.controller_class.new(application: @application, event: event, params: @route.params, screen: screen, route: @route)
     end
 
     # Type-based dispatcher: routes resize, task, timer, mouse, and key events
     # to the appropriate handler. Falls back to key dispatch for unclassified events.
     def dispatch_event(event)
-      return dispatch_resize(event) if event.is_a?(ResizeEvent)
-      return dispatch_task(event) if event.is_a?(TaskEvent)
-      return dispatch_timer(event) if event.is_a?(TimerEvent)
-      return dispatch_mouse(event) if event.is_a?(MouseEvent)
+      return dispatch_resize(event) if event.is_a?(Events::ResizeEvent)
+      return dispatch_task(event) if event.is_a?(Events::TaskEvent)
+      return dispatch_timer(event) if event.is_a?(Events::TimerEvent)
+      return dispatch_mouse(event) if event.is_a?(Events::MouseEvent)
 
       dispatch_key(event)
     end
@@ -133,7 +135,7 @@ module Charming
 
       now = clock_now
       timer[:next_at] = now + timer.fetch(:binding).interval
-      TimerEvent.new(name: timer.fetch(:binding).name, now: now)
+      Events::TimerEvent.new(name: timer.fetch(:binding).name, now: now)
     end
 
     # Pops a task event from the thread-safe queue if one is available.
@@ -161,7 +163,7 @@ module Charming
 
     # Constructs a task executor: supports explicit instances, callable factories, or the default Threaded executor.
     def build_task_executor(task_executor)
-      return TaskExecutor::Threaded.new(@task_queue) unless task_executor
+      return Tasks::ThreadedExecutor.new(@task_queue) unless task_executor
       return task_executor if task_executor.respond_to?(:submit)
       return task_executor.call(@task_queue) if task_executor.respond_to?(:call) && !task_executor.respond_to?(:new)
 

data/lib/charming/screen.rb

@@ -4,5 +4,9 @@ module Charming
   # Screen represents the terminal viewport dimensions as a simple Data class.
   # The `width` and `height` values flow from the backend through the runtime
   # loop into every controller dispatch for layout calculations.
-  Screen = Data.define(:width, :height)
+  Screen = Data.define(:width, :height) do
+    def narrow?(below:, min_height: nil)
+      width < below && (min_height.nil? || height >= min_height)
+    end
+  end
 end

data/lib/charming/tasks/inline_executor.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+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
+        Events::TaskEvent.new(name: task.name, error: e)
+      end
+    end
+  end
+end

data/lib/charming/tasks/task.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+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
+end

data/lib/charming/tasks/threaded_executor.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+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) }
+        @mutex.synchronize { @threads << thread }
+        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) }
+        threads.each do |thread|
+          next unless thread.alive?
+
+          thread.kill
+          thread.join(0)
+        end
+      end
+
+      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
+        Events::TaskEvent.new(name: task.name, error: e)
+      end
+    end
+  end
+end

data/lib/charming/version.rb

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

data/lib/charming.rb

@@ -6,19 +6,36 @@ 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
   end
 end
+
+Charming::Presentation::Templates.register ".tui.erb", Charming::Presentation::Templates::ErbHandler
+Charming::Presentation::Templates.register ".txt.erb", Charming::Presentation::Templates::ErbHandler