charming 0.1.0 → 0.1.2

data/lib/charming/presentation/templates.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+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)
+
+          searched_paths.each do |path|
+            next unless File.file?(path)
+
+            return ResolvedTemplate.new(path: path, handler: handler_for(path))
+          end
+
+          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)
+
+          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
+  end
+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.rb

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

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+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 = 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: [],
+            padding: [0, 0, 0, 0],
+            align: :left
+          }.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)
+          lines = apply_border(lines)
+          apply_ansi(lines.join("\n"))
+        end
+
+        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
+
+          visible = lines.first(height)
+          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
+          empty = " " * (left + inner_width + right)
+          padded = lines.map do |line|
+            pad_line(line, inner_width, left, right)
+          end
+
+          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_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
+
+        # 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
+
+        # 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)
+          ansi_codes_obj.apply(value)
+        end
+
+        # The list of active ANSI escape sequence strings (attribute + foreground + background).
+        def ansi_codes
+          ansi_codes_obj.codes
+        end
+
+        # 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
+
+          case @options.fetch(:align)
+          when :right
+            (" " * remaining) + line
+          when :center
+            left = remaining / 2
+            (" " * left) + line + (" " * (remaining - left))
+          else
+            line + (" " * remaining)
+          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]]
+          when 2 then [values[0], values[1], values[0], values[1]]
+          when 4 then values
+          else
+            raise ArgumentError, "padding expects 1, 2, or 4 values"
+          end
+        end
+      end
+    end
+  end
+end