charming 0.1.0 → 0.1.2

data/lib/charming/ui/style.rb

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

data/lib/charming/ui/theme.rb

@@ -1,178 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Charming
-  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

data/lib/charming/ui/width.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-require "unicode/display_width"
-
-module Charming
-  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

data/lib/charming/ui.rb

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