charming 0.1.1 → 0.1.3

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

@@ -1,244 +1,209 @@
 # frozen_string_literal: true
 
 module Charming
-  module Presentation
-    module UI
-      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
-
-        def initialize(options = {})
-          @options = {
-            attributes: [],
-            padding: [0, 0, 0, 0],
-            align: :left
-          }.merge(options)
-        end
-
-        def foreground(color)
-          with(foreground: color)
-        end
-        alias_method :fg, :foreground
-
-        def background(color)
-          with(background: color)
-        end
-        alias_method :bg, :background
-
-        ATTRIBUTES.each_key do |attribute|
-          define_method(attribute) do
-            with(attributes: (@options.fetch(:attributes) + [attribute]).uniq)
-          end
-        end
-
-        def padding(*values)
-          with(padding: expand_box_values(values))
-        end
-
-        def border(style = :normal, sides: nil, foreground: nil)
-          with(border: style, border_sides: sides, border_foreground: foreground)
-        end
-
-        def width(value)
-          with(width: value)
-        end
-
-        def height(value)
-          with(height: value)
-        end
-
-        def align(value)
-          with(align: value)
-        end
-
-        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
-
-        def with(changes)
-          self.class.new(@options.merge(changes))
-        end
-
-        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
-
-        def target_content_width(lines)
-          explicit_width = @options[:width]
-          natural_width = lines.map { |line| Width.measure(line) }.max || 0
-          explicit_width || natural_width
-        end
-
-        def fit_line(line, width)
-          return line if Width.measure(line) <= width
+  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
 
-          UI.visible_slice(line, 0, width)
-        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
 
-        def apply_height(lines, width)
-          height = @options[:height]
-          return lines unless height
+      # Returns a new Style with the background *color* set.
+      def background(color)
+        with(background: color)
+      end
+      alias_method :bg, :background
 
-          visible = lines.first(height)
-          visible + Array.new([height - visible.length, 0].max) { " " * width }
+      # 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
 
-        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
+      # 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
 
-          Array.new(top, empty) + padded + Array.new(bottom, empty)
-        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
 
-        def apply_border(lines)
-          border_name = @options[:border]
-          return lines unless border_name
+      # Returns a new Style that fixes the rendered width to *value* (in display columns).
+      def width(value)
+        with(width: value)
+      end
 
-          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) }
+      # Returns a new Style that fixes the rendered height to *value* (in rows).
+      def height(value)
+        with(height: value)
+      end
 
-          [top_border(border, horizontal, sides), *body, bottom_border(border, horizontal, sides)].compact
-        end
+      # Returns a new Style with horizontal alignment set (`:left`, `:right`, or `:center`).
+      def align(value)
+        with(align: value)
+      end
 
-        def pad_line(line, inner_width, left, right)
-          (" " * left) + line + (" " * (inner_width - Width.measure(line) + right))
-        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
 
-        def border_line(line, width, border, sides)
-          left = sides.include?(:left) ? render_border(border.vertical) : ""
-          right = sides.include?(:right) ? render_border(border.vertical) : ""
+      private
 
-          "#{left}#{line}#{" " * (width - Width.measure(line))}#{right}"
-        end
+      # Returns a copy of self with *changes* merged into the options hash.
+      def with(changes)
+        self.class.new(@options.merge(changes))
+      end
 
-        def top_border(border, horizontal, sides)
-          return unless sides.include?(:top)
-          return render_border(horizontal) unless full_horizontal_border?(sides)
+      # 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
 
-          render_border("#{border.top_left}#{horizontal}#{border.top_right}")
-        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
 
-        def bottom_border(border, horizontal, sides)
-          return unless sides.include?(:bottom)
-          return render_border(horizontal) unless full_horizontal_border?(sides)
+      # Clips *line* to *width* display columns, preserving ANSI styling where possible.
+      def fit_line(line, width)
+        return line if Width.measure(line) <= width
 
-          render_border("#{border.bottom_left}#{horizontal}#{border.bottom_right}")
-        end
+        UI.visible_slice(line, 0, width)
+      end
 
-        def full_horizontal_border?(sides)
-          sides.include?(:left) && sides.include?(:right)
-        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
 
-        def render_border(value)
-          border_foreground = @options[:border_foreground]
-          return value unless border_foreground
+        visible = lines.first(height)
+        visible + Array.new([height - visible.length, 0].max) { " " * width }
+      end
 
-          Style.new(foreground: border_foreground, background: @options[:background]).render(value)
+      # 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
 
-        def apply_ansi(value)
-          codes = ansi_codes
-          return value if codes.empty?
+        Array.new(top, empty) + padded + Array.new(bottom, empty)
+      end
 
-          start = "\e[#{codes.join(";")}m"
-          value.split("\n", -1).map { |line| "#{start}#{line.gsub("\e[0m", "\e[0m#{start}")}\e[0m" }.join("\n")
-        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
 
-        def ansi_codes
-          @options.fetch(:attributes).map { |attribute| ATTRIBUTES.fetch(attribute) } +
-            color_codes(@options[:foreground], foreground: true) +
-            color_codes(@options[:background], foreground: false)
-        end
+        border_painter(border_name).paint(lines, content_width(lines))
+      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?("#")
+      # 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
 
-          raise ArgumentError, "unknown color: #{color.inspect}"
-        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
 
-        def named_color_code(color, foreground:)
-          code = COLORS.fetch(color.to_sym)
-          [foreground ? code : code + 10]
-        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
 
-        def indexed_color_code(color, foreground:)
-          raise ArgumentError, "indexed color must be between 0 and 255" unless color.between?(0, 255)
+      # Applies the active ANSI attribute/foreground/background codes to *value*.
+      def apply_ansi(value)
+        ansi_codes_obj.apply(value)
+      end
 
-          [foreground ? 38 : 48, 5, color]
-        end
+      # The list of active ANSI escape sequence strings (attribute + foreground + background).
+      def ansi_codes
+        ansi_codes_obj.codes
+      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/)
+      # 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
 
-          [foreground ? 38 : 48, 2, hex[0..1].to_i(16), hex[2..3].to_i(16), hex[4..5].to_i(16)]
-        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
 
-        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
+        case @options.fetch(:align)
+        when :right
+          (" " * remaining) + line
+        when :center
+          left = remaining / 2
+          (" " * left) + line + (" " * (remaining - left))
+        else
+          line + (" " * remaining)
         end
+      end
 
-        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
+      # 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