charming 0.1.0 → 0.1.1

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

@@ -0,0 +1,246 @@
+# 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
+
+          UI.visible_slice(line, 0, width)
+        end
+
+        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
+
+        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
+
+        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
+        end
+
+        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)
+        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)
+        end
+
+        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")
+        end
+
+        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}"
+        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
+
+        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
+
+        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

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,232 @@
+# 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
+
+      # 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
+
+      # 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)
+        base_lines = base.to_s.lines(chomp: true)
+        overlay_lines = overlay.to_s.lines(chomp: true)
+        width = block_width(base_lines)
+        row = offset(top, base_lines.length, overlay_lines.length)
+        column = offset(left, width, block_width(overlay_lines))
+
+        draw_lines(base_lines, overlay_lines, row: row, column: column, width: width)
+      end
+
+      # Places a *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)
+        lines = block.to_s.lines(chomp: true)
+        row = offset(top, height, lines.length)
+        column = offset(left, width, block_width(lines))
+        canvas = Array.new(height) { " " * width }
+        composed = draw_lines(canvas, lines, row: row, column: column, width: width)
+        return composed unless background
+
+        Style.new.background(background).render(composed)
+      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
+
+      # Computes a placement coordinate: if *value* is `:center` the result centres the *size* within *available*;
+      # otherwise *value* is returned verbatim as an absolute integer position.
+      def offset(value, available, size)
+        return [(available - size) / 2, 0].max if value == :center
+
+        value
+      end
+
+      # Merges an *overlay_line* into a *base_line* at the given *column*, returning the combined string. The
+      # overlay replaces (covers) underlying characters; anything to the right that exceeds *width* is truncated.
+      def composed_overlay_line(base_line, overlay_line, column, width)
+        return visible_slice(base_line, 0, width) if column >= width
+        return visible_slice(base_line, 0, width) if column + Width.measure(overlay_line) <= 0
+
+        target_column = [column, 0].max
+        overlay_start = [0 - column, 0].max
+        overlay = visible_slice(overlay_line, overlay_start, width - target_column)
+        overlay_width = Width.measure(overlay)
+        return visible_slice(base_line, 0, width) if overlay_width.zero?
+
+        right_column = target_column + overlay_width
+
+        visible_slice(base_line, 0, target_column) +
+          overlay +
+          visible_slice(base_line, right_column, [width - right_column, 0].max)
+      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)
+        return "" unless width.positive?
+
+        slice_visible_text(line.to_s, start_column, start_column + width)
+      end
+
+      # Slices a string by visible terminal columns while preserving ANSI style state.
+      def slice_visible_text(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, state, start_column, end_column)
+          else
+            slice_char(token, state, start_column, end_column)
+          end
+        end
+
+        terminate_slice(state)
+      end
+
+      # Splits a *line* into token-range pieces bounded by *start_column* and *end_column*, preserving ANSI escapes
+      # that fall within the visible range. Yields each character or escape sequence along with whether it is ANSI.
+      def 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
+            char = line[index]
+            yield char, false
+            index += 1
+          end
+        end
+      end
+
+      # Slices an ANSI *token* (escape sequence) into *state*, writing active markers to the output if the current
+      # *column* falls within the [start_column, end_column) range. Resets styles on `[0m` sequences.
+      def slice_ansi(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
+
+      # Slices a plain *char* into *state*, advancing the column tracker by the character's visual width. If the
+      # character overlaps with the [start_column, end_column) range it is appended to the output.
+      def 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
+
+      # Starts writing to the output buffer, flushing any active ANSI markers if this is the first character placed.
+      def start_slice(state)
+        return if state[:started]
+
+        state[:output] << state[:active].join
+        state[:styled] = true unless state[:active].empty?
+        state[:started] = true
+      end
+
+      # Closes the slice by appending a final `[0m` reset escape to the output unless no active styling exists or
+      # nothing was written. Returns the fully constructed output string with trailing reset applied.
+      def terminate_slice(state)
+        return state[:output] if !state[:styled] || state[:output].empty?
+
+        "#{state[:output]}\e[0m"
+      end
+
+      # Updates *state*[:active] with an ANSI *token*: resets all active styles on `[0m` or appends the token as a
+      # new active marker otherwise. Called during each_ansi_or_char iteration.
+      def update_active_styles(active, token)
+        if token.include?("[0m")
+          active.clear
+        else
+          active << token
+        end
+      end
+
+      # Overlays *lines* onto a *canvas* starting at (*row*, *column*), writing each overlaid line into the canvas
+      # via `composed_overlay_line`. Returns the final canvas joined by newlines.
+      def draw_lines(canvas, lines, row:, column:, width:)
+        lines.each_with_index do |line, index|
+          line_index = row + index
+          next if line_index.negative? || line_index >= canvas.length
+
+          canvas[line_index] = composed_overlay_line(canvas[line_index], line, column, width)
+        end
+
+        canvas.join("\n")
+      end
+    end
+  end
+end