charming 0.1.1 → 0.1.3

data/lib/charming/presentation/template_view.rb

@@ -1,27 +1,32 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    class TemplateView < View
-      def initialize(template:, namespace: nil, **assigns)
-        super(**assigns)
-        @template = template
-        @namespace = namespace
-      end
+  # TemplateView wraps a resolved ERB template and exposes it as a renderable View. The
+  # template is rendered with the view's helpers (`text`, `box`, `row`, `column`, `style`,
+  # `theme`, etc.) and the view's assigns available as reader methods inside the template.
+  class TemplateView < View
+    def initialize(template:, namespace: nil, **assigns)
+      super(**assigns)
+      @template = template
+      @namespace = namespace
+    end
 
-      def render
-        template.render(self).to_s
-      end
+    # Renders the wrapped template to a string, evaluated in the view's binding context.
+    def render
+      template.render(self).to_s
+    end
 
-      def template_binding
-        return binding unless namespace
+    # Returns the binding used by ERB handlers to evaluate the template body. When *namespace*
+    # is set, the binding is created by a proc generated in the namespace's context so the
+    # template can resolve constants relative to the application.
+    def template_binding
+      return binding unless namespace
 
-        namespace.module_eval("->(view) { view.instance_eval { binding } }", __FILE__, __LINE__).call(self)
-      end
+      namespace.module_eval("->(view) { view.instance_eval { binding } }", __FILE__, __LINE__).call(self)
+    end
 
-      private
+    private
 
-      attr_reader :template, :namespace
-    end
+    attr_reader :template, :namespace
   end
 end

data/lib/charming/presentation/templates/erb_handler.rb

@@ -3,12 +3,10 @@
 require "erb"
 
 module Charming
-  module Presentation
-    module Templates
-      class ErbHandler
-        def self.render(path, view)
-          ERB.new(File.read(path), trim_mode: "-").result(view.template_binding)
-        end
+  module Templates
+    class ErbHandler
+      def self.render(path, view)
+        ERB.new(File.read(path), trim_mode: "-").result(view.template_binding)
       end
     end
   end

data/lib/charming/presentation/templates.rb

@@ -1,50 +1,65 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module Templates
-      ResolvedTemplate = Data.define(:path, :handler) do
-        def render(view)
-          handler.render(path, view)
-        end
+  # Templates resolves and renders view templates by name. Template handlers are registered
+  # for file extensions (e.g., `.tui.erb`) and the resolver searches `app/views/<name><ext>`
+  # under the application root, falling back through registered extensions when the first
+  # match is not found.
+  module Templates
+    # A resolved template: an on-disk *path* paired with the *handler* responsible for rendering it.
+    ResolvedTemplate = Data.define(:path, :handler) do
+      # Renders the template against *view* by delegating to the registered handler.
+      def render(view)
+        handler.render(path, view)
       end
+    end
 
-      MissingTemplateError = Class.new(Error)
-
-      class << self
-        def register(extension, handler)
-          handlers[extension] = handler
-        end
+    # Raised when no template file matches the given name under the application root.
+    MissingTemplateError = Class.new(Error)
 
-        def resolve(name, root: nil)
-          views_root = File.join(root || Dir.pwd, "app", "views")
-          searched_paths = candidate_paths(views_root, name.to_s)
+    class << self
+      # Registers a template *handler* for a file *extension* (e.g., ".tui.erb" => ErbHandler).
+      # The handler responds to `.render(path, view)`.
+      def register(extension, handler)
+        handlers[extension] = handler
+      end
 
-          searched_paths.each do |path|
-            next unless File.file?(path)
+      # Resolves a template by *name* under `app/views` of *root* (defaults to the current
+      # working directory). Raises MissingTemplateError when no matching file exists.
+      def resolve(name, root: nil)
+        views_root = File.join(root || Dir.pwd, "app", "views")
+        searched_paths = candidate_paths(views_root, name.to_s)
 
-            return ResolvedTemplate.new(path: path, handler: handler_for(path))
-          end
+        searched_paths.each do |path|
+          next unless File.file?(path)
 
-          raise MissingTemplateError, "Missing template #{name.inspect}. Searched: #{searched_paths.join(", ")}"
+          return ResolvedTemplate.new(path: path, handler: handler_for(path))
         end
 
-        def handlers
-          @handlers ||= {}
-        end
+        raise MissingTemplateError, "Missing template #{name.inspect}. Searched: #{searched_paths.join(", ")}"
+      end
 
-        private
+      # Hash of registered handlers keyed by extension. Populated by `register`.
+      def handlers
+        @handlers ||= {}
+      end
 
-        def candidate_paths(views_root, name)
-          path = File.expand_path(name, views_root)
-          return [path] if handler_for(path)
+      private
 
-          handlers.keys.map { |extension| "#{path}#{extension}" }
-        end
+      # Returns candidate paths under *views_root* for *name*. When the bare path has a known
+      # extension, returns it directly; otherwise returns the path with each registered extension
+      # appended (in registration order).
+      def candidate_paths(views_root, name)
+        path = File.expand_path(name, views_root)
+        return [path] if handler_for(path)
 
-        def handler_for(path)
-          handlers.find { |extension, _handler| path.end_with?(extension) }&.last
-        end
+        handlers.keys.map { |extension| "#{path}#{extension}" }
+      end
+
+      # Looks up the handler whose registered extension matches the end of *path*. Returns nil
+      # when no handler matches.
+      def handler_for(path)
+        handlers.find { |extension, _handler| path.end_with?(extension) }&.last
       end
     end
   end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    class ANSICodes
+      ATTRIBUTES = {
+        bold: 1,
+        faint: 2,
+        italic: 3,
+        underline: 4,
+        reverse: 7,
+        strikethrough: 9
+      }.freeze
+
+      COLORS = {
+        black: 30,
+        red: 31,
+        green: 32,
+        yellow: 33,
+        blue: 34,
+        magenta: 35,
+        cyan: 36,
+        white: 37,
+        bright_black: 90,
+        bright_red: 91,
+        bright_green: 92,
+        bright_yellow: 93,
+        bright_blue: 94,
+        bright_magenta: 95,
+        bright_cyan: 96,
+        bright_white: 97
+      }.freeze
+
+      def initialize(attributes:, foreground:, background:)
+        @attributes = attributes
+        @foreground = foreground
+        @background = background
+      end
+
+      def codes
+        @codes ||= attribute_codes +
+          color_codes(@foreground, foreground: true) +
+          color_codes(@background, foreground: false)
+      end
+
+      def apply(value)
+        return value if codes.empty?
+
+        start = "\e[#{codes.join(";")}m"
+        value.split("\n", -1).map { |line| "#{start}#{line.gsub("\e[0m", "\e[0m#{start}")}\e[0m" }.join("\n")
+      end
+
+      private
+
+      def attribute_codes
+        @attributes.map { |attribute| ATTRIBUTES.fetch(attribute) }
+      end
+
+      def color_codes(color, foreground:)
+        return [] unless color
+        return indexed_color_code(color, foreground: foreground) if color.is_a?(Integer)
+        return named_color_code(color, foreground: foreground) if COLORS.key?(color.to_sym)
+        return truecolor_codes(color, foreground: foreground) if color.to_s.start_with?("#")
+
+        raise ArgumentError, "unknown color: #{color.inspect}"
+      end
+
+      def named_color_code(color, foreground:)
+        code = COLORS.fetch(color.to_sym)
+        [foreground ? code : code + 10]
+      end
+
+      def indexed_color_code(color, foreground:)
+        raise ArgumentError, "indexed color must be between 0 and 255" unless color.between?(0, 255)
+
+        [foreground ? 38 : 48, 5, color]
+      end
+
+      def truecolor_codes(color, foreground:)
+        hex = color.to_s.delete_prefix("#")
+        raise ArgumentError, "truecolor must be #rrggbb" unless hex.match?(/\A[0-9a-fA-F]{6}\z/)
+
+        [foreground ? 38 : 48, 2, hex[0..1].to_i(16), hex[2..3].to_i(16), hex[4..5].to_i(16)]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # ANSISlicer extracts a visible substring from a string that may contain ANSI
+    # escape sequences, preserving the styling that is active at the start of
+    # the slice and emitting a trailing reset if any styled content was copied.
+    class ANSISlicer
+      def self.slice(line, start_column, width)
+        return "" unless width.positive?
+
+        slice_range(line.to_s, start_column, start_column + width)
+      end
+
+      def self.slice_range(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(token, state, start_column, end_column)
+          else
+            slice_char(token, state, start_column, end_column)
+          end
+        end
+
+        terminate_slice(state)
+      end
+
+      def self.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
+            yield line[index], false
+            index += 1
+          end
+        end
+      end
+
+      def self.slice_ansi_token(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
+
+      def self.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
+
+      def self.start_slice(state)
+        return if state[:started]
+
+        state[:output] << state[:active].join
+        state[:styled] = true unless state[:active].empty?
+        state[:started] = true
+      end
+
+      def self.terminate_slice(state)
+        return state[:output] if !state[:styled] || state[:output].empty?
+
+        "#{state[:output]}\e[0m"
+      end
+
+      def self.update_active_styles(active, token)
+        if token.include?("[0m")
+          active.clear
+        else
+          active << token
+        end
+      end
+
+      private_class_method :each_ansi_or_char, :slice_ansi_token, :slice_char,
+        :start_slice, :terminate_slice, :update_active_styles
+    end
+  end
+end

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

@@ -1,35 +1,33 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module UI
-      class Border
-        attr_reader :top_left, :top_right, :bottom_left, :bottom_right, :horizontal, :vertical
+  module UI
+    class Border
+      attr_reader :top_left, :top_right, :bottom_left, :bottom_right, :horizontal, :vertical
 
-        def initialize(corners:, edges:)
-          @top_left, @top_right, @bottom_left, @bottom_right = corners
-          @horizontal, @vertical = edges
-        end
-
-        def self.fetch(name)
-          STYLES.fetch(name.to_sym)
-        end
+      def initialize(corners:, edges:)
+        @top_left, @top_right, @bottom_left, @bottom_right = corners
+        @horizontal, @vertical = edges
       end
 
-      Border::STYLES = {
-        normal: Border.new(
-          corners: ["+", "+", "+", "+"], edges: ["-", "|"]
-        ),
-        rounded: Border.new(
-          corners: ["╭", "╮", "╰", "╯"], edges: ["─", "│"]
-        ),
-        thick: Border.new(
-          corners: ["┏", "┓", "┗", "┛"], edges: ["━", "┃"]
-        ),
-        double: Border.new(
-          corners: ["╔", "╗", "╚", "╝"], edges: ["═", "║"]
-        )
-      }.freeze
+      def self.fetch(name)
+        STYLES.fetch(name.to_sym)
+      end
     end
+
+    Border::STYLES = {
+      normal: Border.new(
+        corners: ["+", "+", "+", "+"], edges: ["-", "|"]
+      ),
+      rounded: Border.new(
+        corners: ["╭", "╮", "╰", "╯"], edges: ["─", "│"]
+      ),
+      thick: Border.new(
+        corners: ["┏", "┓", "┗", "┛"], edges: ["━", "┃"]
+      ),
+      double: Border.new(
+        corners: ["╔", "╗", "╚", "╝"], edges: ["═", "║"]
+      )
+    }.freeze
   end
 end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    class BorderPainter
+      DEFAULT_SIDES = %i[top right bottom left].freeze
+
+      def initialize(border:, sides: nil, foreground: nil, background: nil)
+        @border = border
+        @sides = Array(sides || DEFAULT_SIDES).map(&:to_sym)
+        @foreground = foreground
+        @background = background
+      end
+
+      def paint(lines, inner_width)
+        horizontal = @border.horizontal * inner_width
+        body = lines.map { |line| border_line(line, inner_width) }
+
+        [top_border(horizontal), *body, bottom_border(horizontal)].compact
+      end
+
+      private
+
+      def border_line(line, width)
+        left = @sides.include?(:left) ? render_border(@border.vertical) : ""
+        right = @sides.include?(:right) ? render_border(@border.vertical) : ""
+
+        "#{left}#{line}#{" " * (width - Width.measure(line))}#{right}"
+      end
+
+      def top_border(horizontal)
+        return unless @sides.include?(:top)
+        return render_border(horizontal) unless full_horizontal?
+
+        render_border("#{@border.top_left}#{horizontal}#{@border.top_right}")
+      end
+
+      def bottom_border(horizontal)
+        return unless @sides.include?(:bottom)
+        return render_border(horizontal) unless full_horizontal?
+
+        render_border("#{@border.bottom_left}#{horizontal}#{@border.bottom_right}")
+      end
+
+      def full_horizontal?
+        @sides.include?(:left) && @sides.include?(:right)
+      end
+
+      def render_border(value)
+        return value unless @foreground
+
+        Style.new(foreground: @foreground, background: @background).render(value)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # Canvas is a 2D character grid of fixed width and height that supports
+    # placing content at (row, column) coordinates and overlaying one block
+    # on top of another. Construct via .new(width, height) for a blank grid
+    # or .parse(string) to reconstruct from rendered output.
+    class Canvas
+      def initialize(width, height)
+        @width = width
+        @height = height
+        @grid = Array.new(height) { " " * width }
+      end
+
+      def self.parse(string)
+        lines = string.to_s.lines(chomp: true)
+        width = UI.block_width(lines)
+        canvas = new(width, lines.length)
+        lines.each_with_index { |line, i| canvas.instance_variable_get(:@grid)[i] = line }
+        canvas
+      end
+
+      def to_s
+        @grid.join("\n")
+      end
+
+      def place(block, top: 0, left: 0, background: nil)
+        lines = block.to_s.lines(chomp: true)
+        row = Canvas.offset(top, @height, lines.length)
+        column = Canvas.offset(left, @width, UI.block_width(lines))
+        draw_lines(lines, row: row, column: column, onto: @grid)
+        rendered = to_s
+        background ? UI::Style.new.background(background).render(rendered) : rendered
+      end
+
+      def overlay(other, top: :center, left: :center)
+        overlay_lines = other.to_s.lines(chomp: true)
+        row = Canvas.offset(top, @grid.length, overlay_lines.length)
+        column = Canvas.offset(left, @width, UI.block_width(overlay_lines))
+        draw_lines(overlay_lines, row: row, column: column, onto: @grid)
+        self
+      end
+
+      def self.offset(value, available, size)
+        return [(available - size) / 2, 0].max if value == :center
+
+        value
+      end
+
+      private
+
+      def draw_lines(lines, row:, column:, onto:)
+        lines.each_with_index do |line, index|
+          line_index = row + index
+          next if line_index.negative? || line_index >= onto.length
+
+          onto[line_index] = compose_line(onto[line_index], line, column)
+        end
+      end
+
+      def compose_line(base_line, overlay_line, column)
+        return ANSISlicer.slice(base_line, 0, @width) if column >= @width
+        return ANSISlicer.slice(base_line, 0, @width) if column + Width.measure(overlay_line) <= 0
+
+        target_column = [column, 0].max
+        overlay_start = [0 - column, 0].max
+        overlay = ANSISlicer.slice(overlay_line, overlay_start, @width - target_column)
+        overlay_width = Width.measure(overlay)
+        return ANSISlicer.slice(base_line, 0, @width) if overlay_width.zero?
+
+        right_column = target_column + overlay_width
+
+        ANSISlicer.slice(base_line, 0, target_column) +
+          overlay +
+          ANSISlicer.slice(base_line, right_column, [@width - right_column, 0].max)
+      end
+    end
+  end
+end