charming 0.1.1 → 0.1.2

data/lib/charming/presentation/templates.rb

@@ -2,20 +2,31 @@
 
 module Charming
   module Presentation
+    # 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
 
+      # Raised when no template file matches the given name under the application root.
       MissingTemplateError = Class.new(Error)
 
       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
 
+        # 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)
@@ -29,12 +40,16 @@ module Charming
           raise MissingTemplateError, "Missing template #{name.inspect}. Searched: #{searched_paths.join(", ")}"
         end
 
+        # Hash of registered handlers keyed by extension. Populated by `register`.
         def handlers
           @handlers ||= {}
         end
 
         private
 
+        # 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)
@@ -42,6 +57,8 @@ module Charming
           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

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Charming
+  module Presentation
+    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
+end

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

@@ -3,35 +3,18 @@
 module Charming
   module Presentation
     module UI
+      # Style is an immutable builder for terminal text styling. Every method returns a new
+      # Style instance with the requested attribute added, so styles can be safely chained and
+      # shared across views. `render(value)` applies the accumulated style to a string.
       class Style
-        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
+        ATTRIBUTES = ANSICodes::ATTRIBUTES
 
+        COLORS = ANSICodes::COLORS
+
+        # Initializes a new style with an optional options hash. Recognized keys: `:attributes`
+        # (array of attribute symbols), `:padding` ([top, right, bottom, left]), `:align`
+        # (`:left`/`:right`/`:center`), and any of `:foreground`, `:background`, `:border`,
+        # `:border_sides`, `:border_foreground`, `:width`, `:height`.
         def initialize(options = {})
           @options = {
             attributes: [],
@@ -40,42 +23,58 @@ module Charming
           }.merge(options)
         end
 
+        # Returns a new Style with the foreground *color* set. *color* is a color name (":red"),
+        # 256-color index (integer), or hex string ("#rrggbb").
         def foreground(color)
           with(foreground: color)
         end
         alias_method :fg, :foreground
 
+        # Returns a new Style with the background *color* set.
         def background(color)
           with(background: color)
         end
         alias_method :bg, :background
 
+        # Attribute methods (bold, italic, underline, …) are defined dynamically by the
+        # metaprogramming loop below. Each toggles a single text attribute on the style.
         ATTRIBUTES.each_key do |attribute|
           define_method(attribute) do
             with(attributes: (@options.fetch(:attributes) + [attribute]).uniq)
           end
         end
 
+        # Returns a new Style with the padding set. Accepts 1, 2, or 4 values following CSS-style
+        # shorthand: 1 → all sides, 2 → [vertical, horizontal], 4 → [top, right, bottom, left].
         def padding(*values)
           with(padding: expand_box_values(values))
         end
 
+        # Returns a new Style with the border set. *style* is a border name (e.g., :normal,
+        # :rounded). *sides* optionally restricts the border to specific sides. *foreground*
+        # sets the border color.
         def border(style = :normal, sides: nil, foreground: nil)
           with(border: style, border_sides: sides, border_foreground: foreground)
         end
 
+        # Returns a new Style that fixes the rendered width to *value* (in display columns).
         def width(value)
           with(width: value)
         end
 
+        # Returns a new Style that fixes the rendered height to *value* (in rows).
         def height(value)
           with(height: value)
         end
 
+        # Returns a new Style with horizontal alignment set (`:left`, `:right`, or `:center`).
         def align(value)
           with(align: value)
         end
 
+        # Applies the configured style to *value* and returns the styled string. Steps:
+        # 1. wrap to `:width`, 2. align horizontally, 3. expand to `:height`, 4. apply padding,
+        # 5. paint border, 6. emit ANSI attribute/foreground/background escapes.
         def render(value)
           lines = apply_dimensions(value.to_s.lines(chomp: true))
           lines = apply_padding(lines)
@@ -85,28 +84,35 @@ module Charming
 
         private
 
+        # Returns a copy of self with *changes* merged into the options hash.
         def with(changes)
           self.class.new(@options.merge(changes))
         end
 
+        # Wraps each line to the target width and applies horizontal alignment, then expands
+        # to the target height.
         def apply_dimensions(lines)
           content_width = target_content_width(lines)
           dimensioned = lines.map { |line| align_line(fit_line(line, content_width), content_width) }
           apply_height(dimensioned, content_width)
         end
 
+        # Returns the target content width: the explicit :width if set, otherwise the natural
+        # max display width of the lines.
         def target_content_width(lines)
           explicit_width = @options[:width]
           natural_width = lines.map { |line| Width.measure(line) }.max || 0
           explicit_width || natural_width
         end
 
+        # Clips *line* to *width* display columns, preserving ANSI styling where possible.
         def fit_line(line, width)
           return line if Width.measure(line) <= width
 
           UI.visible_slice(line, 0, width)
         end
 
+        # Truncates or pads the lines array to *height* rows, filling with blank rows.
         def apply_height(lines, width)
           height = @options[:height]
           return lines unless height
@@ -115,6 +121,8 @@ module Charming
           visible + Array.new([height - visible.length, 0].max) { " " * width }
         end
 
+        # Applies padding by prepending/appending blank rows (vertical) and indenting each
+        # line (horizontal).
         def apply_padding(lines)
           top, right, bottom, left = @options.fetch(:padding)
           inner_width = lines.map { |line| Width.measure(line) }.max || 0
@@ -126,96 +134,54 @@ module Charming
           Array.new(top, empty) + padded + Array.new(bottom, empty)
         end
 
+        # Paints the configured border around the lines, when :border is set.
         def apply_border(lines)
           border_name = @options[:border]
           return lines unless border_name
 
-          border = Border.fetch(border_name)
-          sides = Array(@options[:border_sides] || %i[top right bottom left]).map(&:to_sym)
-          width = lines.map { |line| Width.measure(line) }.max || 0
-          horizontal = border.horizontal * width
-          body = lines.map { |line| border_line(line, width, border, sides) }
-
-          [top_border(border, horizontal, sides), *body, bottom_border(border, horizontal, sides)].compact
+          border_painter(border_name).paint(lines, content_width(lines))
         end
 
+        # Pads a single line to *inner_width*, with *left* and *right* padding spaces.
         def pad_line(line, inner_width, left, right)
           (" " * left) + line + (" " * (inner_width - Width.measure(line) + right))
         end
 
-        def border_line(line, width, border, sides)
-          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(border, horizontal, sides)
-          return unless sides.include?(:top)
-          return render_border(horizontal) unless full_horizontal_border?(sides)
-
-          render_border("#{border.top_left}#{horizontal}#{border.top_right}")
-        end
-
-        def bottom_border(border, horizontal, sides)
-          return unless sides.include?(:bottom)
-          return render_border(horizontal) unless full_horizontal_border?(sides)
-
-          render_border("#{border.bottom_left}#{horizontal}#{border.bottom_right}")
-        end
-
-        def full_horizontal_border?(sides)
-          sides.include?(:left) && sides.include?(:right)
+        # Builds a BorderPainter configured for the current border options.
+        def border_painter(border_name)
+          BorderPainter.new(
+            border: Border.fetch(border_name),
+            sides: @options[:border_sides],
+            foreground: @options[:border_foreground],
+            background: @options[:background]
+          )
         end
 
-        def render_border(value)
-          border_foreground = @options[:border_foreground]
-          return value unless border_foreground
-
-          Style.new(foreground: border_foreground, background: @options[:background]).render(value)
+        # Returns the natural display width of the longest line in *lines*.
+        def content_width(lines)
+          lines.map { |line| Width.measure(line) }.max || 0
         end
 
+        # Applies the active ANSI attribute/foreground/background codes to *value*.
         def apply_ansi(value)
-          codes = ansi_codes
-          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")
+          ansi_codes_obj.apply(value)
         end
 
+        # The list of active ANSI escape sequence strings (attribute + foreground + background).
         def ansi_codes
-          @options.fetch(:attributes).map { |attribute| ATTRIBUTES.fetch(attribute) } +
-            color_codes(@options[:foreground], foreground: true) +
-            color_codes(@options[:background], foreground: false)
-        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}"
+          ansi_codes_obj.codes
         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)]
+        # Builds an ANSICodes object from the active attributes, foreground, and background.
+        def ansi_codes_obj
+          ANSICodes.new(
+            attributes: @options.fetch(:attributes),
+            foreground: @options[:foreground],
+            background: @options[:background]
+          )
         end
 
+        # Pads *line* on the left or right (or both, for :center) according to :align.
         def align_line(line, width)
           remaining = width - Width.measure(line)
           return line if remaining <= 0
@@ -231,6 +197,7 @@ module Charming
           end
         end
 
+        # Normalizes 1/2/4 padding value arguments into a [top, right, bottom, left] array.
         def expand_box_values(values)
           case values.length
           when 1 then [values[0], values[0], values[0], values[0]]