charming 0.2.0 → 0.2.2

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

@@ -56,8 +56,13 @@ module Charming
         @attributes.map { |attribute| ATTRIBUTES.fetch(attribute) }
       end
 
+      # Resolves *color* to SGR codes, downconverting to the terminal's capability
+      # (see UI::ColorSupport): truecolor → 256 → 16 → none. Adaptive colors
+      # resolve against the terminal background first.
       def color_codes(color, foreground:)
+        color = color.resolve if color.respond_to?(:resolve)
         return [] unless color
+        return [] if ColorSupport.level == :none
         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?("#")
@@ -72,16 +77,25 @@ module Charming
 
       def indexed_color_code(color, foreground:)
         raise ArgumentError, "indexed color must be between 0 and 255" unless color.between?(0, 255)
+        return basic_color_code(ColorSupport.index_to_16(color), foreground: foreground) unless ColorSupport.at_least?(:color256)
 
         [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/)
+        hex = hex.chars.map { |digit| digit * 2 }.join if hex.match?(/\A[0-9a-fA-F]{3}\z/)
+        raise ArgumentError, "truecolor must be #rgb or #rrggbb" unless hex.match?(/\A[0-9a-fA-F]{6}\z/)
+        return [foreground ? 38 : 48, 5, ColorSupport.hex_to_256(hex)] if ColorSupport.level == :color256
+        return basic_color_code(ColorSupport.hex_to_16(hex), foreground: foreground) if ColorSupport.level == :color16
 
         [foreground ? 38 : 48, 2, hex[0..1].to_i(16), hex[2..3].to_i(16), hex[4..5].to_i(16)]
       end
+
+      # Wraps a basic SGR foreground code (30-37/90-97) for the requested plane.
+      def basic_color_code(code, foreground:)
+        [foreground ? code : code + 10]
+      end
     end
   end
 end

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

@@ -6,6 +6,10 @@ module Charming
     # 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
+      # One ANSI escape sequence or one grapheme cluster (`\X`). The ANSI branch
+      # comes first so a valid escape is consumed whole rather than as graphemes.
+      TOKEN_PATTERN = /#{Width::ANSI_PATTERN}|\X/
+
       def self.slice(line, start_column, width)
         return "" unless width.positive?
 
@@ -27,16 +31,12 @@ module Charming
       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
+        # Iterate one ANSI escape or one *grapheme cluster* (`\X`) at a time. A
+        # single emoji may be several codepoints (ZWJ sequences, skin-tone and
+        # variation selectors, e.g. "🧙‍♂️"); treating it as one unit keeps its full
+        # display width together so a slice never splits it mid-glyph.
+        line.scan(TOKEN_PATTERN) do |token|
+          yield token, token.start_with?("\e")
         end
       end
 
@@ -57,10 +57,17 @@ module Charming
         char_start = state[:column]
         char_end = char_start + char_width
         state[:column] = char_end
-        return unless char_end > start_column && char_start < end_column
+
+        visible = [char_end, end_column].min - [char_start, start_column].max
+        return unless visible.positive?
 
         start_slice(state)
-        state[:output] << char
+        # A multi-column glyph cut by a slice boundary cannot be partially drawn,
+        # so render the in-range columns as spaces (standard terminal behavior).
+        # This keeps the slice exactly *width* columns wide regardless of where
+        # the boundaries fall relative to wide glyphs.
+        fits = char_start >= start_column && char_end <= end_column
+        state[:output] << (fits ? char : " " * visible)
       end
 
       def self.start_slice(state)
@@ -81,7 +88,7 @@ module Charming
         if token.include?("[0m")
           active.clear
         else
-          active << token
+          active << token unless active.include?(token)
         end
       end
 

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # Background tracks whether the terminal has a dark or light background so
+    # adaptive colors and the markdown :auto style can pick the readable variant.
+    #
+    # The runtime feeds a definitive answer from an OSC 11 query when the
+    # terminal replies to one (see TTYBackend#query_background_color); otherwise
+    # detection falls back to the COLORFGBG convention and finally assumes dark —
+    # the overwhelmingly common terminal default. `Background.assume = :light`
+    # overrides everything (useful in tests and for user preference).
+    module Background
+      MODES = %i[dark light].freeze
+
+      # ITU-R BT.601 luma threshold on 8-bit channels: below this is "dark".
+      LUMA_THRESHOLD = 128
+
+      module_function
+
+      # True when the terminal background is dark (the assumed mode, or detection).
+      def dark?
+        (@assumed || detect(ENV)) == :dark
+      end
+
+      # Overrides detection with :dark or :light; nil returns to auto-detection.
+      def assume=(value)
+        raise ArgumentError, "unknown background: #{value.inspect}" if value && !MODES.include?(value)
+
+        @assumed = value
+      end
+
+      # Detects the background from an environment hash via the COLORFGBG
+      # convention ("<fg>;<bg>", where bg 7 or 15 means a light background).
+      # Defaults to :dark when the environment says nothing.
+      def detect(env)
+        bg_index = env["COLORFGBG"].to_s.split(";").last
+        %w[7 15].include?(bg_index) ? :light : :dark
+      end
+
+      # Classifies an 8-bit RGB triple as :dark or :light by luma.
+      def classify(red, green, blue)
+        luma = (0.299 * red) + (0.587 * green) + (0.114 * blue)
+        (luma < LUMA_THRESHOLD) ? :dark : :light
+      end
+
+      # Parses an OSC 11 reply ("\e]11;rgb:RRRR/GGGG/BBBB" + BEL or ST) and
+      # classifies the reported color. Returns nil for anything unparseable.
+      def parse_osc11(reply)
+        match = reply.to_s.match(%r{\e\]11;rgb:(\h{2,4})/(\h{2,4})/(\h{2,4})})
+        return unless match
+
+        red, green, blue = match.captures.map { |channel| channel[0, 2].to_i(16) }
+        classify(red, green, blue)
+      end
+    end
+  end
+end

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

@@ -10,7 +10,11 @@ module Charming
         @horizontal, @vertical = edges
       end
 
+      # Resolves *name* to a Border: a Border instance passes through (custom
+      # borders), anything else is looked up in the built-in STYLES.
       def self.fetch(name)
+        return name if name.is_a?(Border)
+
         STYLES.fetch(name.to_sym)
       end
     end
@@ -27,7 +31,16 @@ module Charming
       ),
       double: Border.new(
         corners: ["╔", "╗", "╚", "╝"], edges: ["═", "║"]
+      ),
+      square: Border.new(
+        corners: ["┌", "┐", "└", "┘"], edges: ["─", "│"]
+      ),
+      hidden: Border.new(
+        corners: [" ", " ", " ", " "], edges: [" ", " "]
+      ),
+      block: Border.new(
+        corners: ["█", "█", "█", "█"], edges: ["█", "█"]
       )
-    }.freeze
+    }.tap { |styles| styles[:ascii] = styles[:normal] }.freeze
   end
 end

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

@@ -2,14 +2,21 @@
 
 module Charming
   module UI
+    # BorderPainter draws a Border's glyphs around content lines, optionally
+    # coloring the border. *foreground* is a single color or a per-side hash
+    # (`{top:, right:, bottom:, left:}`); corners take the top/bottom row's
+    # color. *background* colors border cells; when it merely inherits the box
+    # background (background_explicit: false) it only paints alongside a
+    # foreground, preserving unstyled borders on unstyled boxes.
     class BorderPainter
       DEFAULT_SIDES = %i[top right bottom left].freeze
 
-      def initialize(border:, sides: nil, foreground: nil, background: nil)
+      def initialize(border:, sides: nil, foreground: nil, background: nil, background_explicit: false)
         @border = border
         @sides = Array(sides || DEFAULT_SIDES).map(&:to_sym)
         @foreground = foreground
         @background = background
+        @background_explicit = background_explicit
       end
 
       def paint(lines, inner_width)
@@ -22,34 +29,39 @@ module Charming
       private
 
       def border_line(line, width)
-        left = @sides.include?(:left) ? render_border(@border.vertical) : ""
-        right = @sides.include?(:right) ? render_border(@border.vertical) : ""
+        left = @sides.include?(:left) ? render_border(@border.vertical, :left) : ""
+        right = @sides.include?(:right) ? render_border(@border.vertical, :right) : ""
 
-        "#{left}#{line}#{" " * (width - Width.measure(line))}#{right}"
+        "#{left}#{Width.pad_to(line, width)}#{right}"
       end
 
       def top_border(horizontal)
         return unless @sides.include?(:top)
-        return render_border(horizontal) unless full_horizontal?
+        return render_border(horizontal, :top) unless full_horizontal?
 
-        render_border("#{@border.top_left}#{horizontal}#{@border.top_right}")
+        render_border("#{@border.top_left}#{horizontal}#{@border.top_right}", :top)
       end
 
       def bottom_border(horizontal)
         return unless @sides.include?(:bottom)
-        return render_border(horizontal) unless full_horizontal?
+        return render_border(horizontal, :bottom) unless full_horizontal?
 
-        render_border("#{@border.bottom_left}#{horizontal}#{@border.bottom_right}")
+        render_border("#{@border.bottom_left}#{horizontal}#{@border.bottom_right}", :bottom)
       end
 
       def full_horizontal?
         @sides.include?(:left) && @sides.include?(:right)
       end
 
-      def render_border(value)
-        return value unless @foreground
+      def render_border(value, side)
+        foreground = side_foreground(side)
+        return value unless foreground || @background_explicit
 
-        Style.new(foreground: @foreground, background: @background).render(value)
+        Style.new(foreground: foreground, background: @background).render(value)
+      end
+
+      def side_foreground(side)
+        @foreground.is_a?(Hash) ? @foreground[side] : @foreground
       end
     end
   end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # BrailleCanvas is a monochrome subpixel drawing surface backed by Unicode braille glyphs
+    # (U+2800–U+28FF). Each character cell packs a 2×4 grid of dots, so the canvas addresses
+    # `width`×`height` *pixels* while rendering to `cols`×`rows` *cells* — 8× the vertical and 2× the
+    # horizontal resolution of plain text. It's pure text (works on every terminal) and composes via
+    # `row`/`column`/`Canvas` like any other block. Used by {Charming::Components::Chart}.
+    class BrailleCanvas
+      # The first braille code point; OR-ing dot bits onto it yields the glyph for a cell.
+      BASE = 0x2800
+
+      # Dot bit for each (x%2, y%4) position within a cell, indexed `DOTS[y % 4][x % 2]`.
+      DOTS = [[0x01, 0x08], [0x02, 0x10], [0x04, 0x20], [0x40, 0x80]].freeze
+
+      # *width* and *height* are the drawable area in pixels (dots).
+      def initialize(width, height)
+        @width = width
+        @height = height
+        @cols = (width + 1) / 2
+        @rows = (height + 3) / 4
+        @cells = Array.new(@rows) { Array.new(@cols, 0) }
+      end
+
+      attr_reader :width, :height, :cols, :rows
+
+      # Turns the dot at pixel (*x*, *y*) on (or off when `on: false`). Out-of-range points are
+      # ignored. Returns self for chaining.
+      def set(x, y, on: true)
+        return self unless x.between?(0, @width - 1) && y.between?(0, @height - 1)
+
+        bit = DOTS[y % 4][x % 2]
+        if on
+          @cells[y / 4][x / 2] |= bit
+        else
+          @cells[y / 4][x / 2] &= ~bit
+        end
+        self
+      end
+
+      # Turns the dot at pixel (*x*, *y*) off. Returns self.
+      def unset(x, y)
+        set(x, y, on: false)
+      end
+
+      # Draws a straight line between (*x0*, *y0*) and (*x1*, *y1*) with Bresenham's algorithm.
+      # Returns self.
+      def line(x0, y0, x1, y1)
+        dx = (x1 - x0).abs
+        dy = -(y1 - y0).abs
+        sx = (x0 < x1) ? 1 : -1
+        sy = (y0 < y1) ? 1 : -1
+        err = dx + dy
+        x = x0
+        y = y0
+        loop do
+          set(x, y)
+          break if x == x1 && y == y1
+
+          e2 = 2 * err
+          if e2 >= dy
+            err += dy
+            x += sx
+          end
+          if e2 <= dx
+            err += dx
+            y += sy
+          end
+        end
+        self
+      end
+
+      # Renders the canvas as `rows` lines of `cols` braille glyphs.
+      def to_s
+        @cells.map { |row| row.map { |bits| (BASE + bits).chr(Encoding::UTF_8) }.join }.join("\n")
+      end
+    end
+  end
+end

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

@@ -44,6 +44,7 @@ module Charming
 
       def self.offset(value, available, size)
         return [(available - size) / 2, 0].max if value == :center
+        return [((available - size) * value).round, 0].max if value.is_a?(Float)
 
         value
       end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # ColorSupport detects the terminal's color capability and downconverts colors so
+    # themes written in truecolor degrade gracefully on less-capable terminals.
+    #
+    # Levels (best to worst): :truecolor, :color256, :color16, :none.
+    #
+    # Detection honors NO_COLOR, then COLORTERM (truecolor/24bit), then TERM.
+    # `UI::ColorSupport.level = :color256` overrides detection (useful in tests and
+    # for user preference).
+    module ColorSupport
+      LEVELS = %i[none color16 color256 truecolor].freeze
+
+      # The 6-level RGB ramp used by the xterm 256-color cube (indices 16-231).
+      CUBE_LEVELS = [0, 95, 135, 175, 215, 255].freeze
+
+      module_function
+
+      # The active color level: the explicit override or the detected level (memoized).
+      def level
+        @level ||= detect(ENV)
+      end
+
+      # Overrides the detected level (nil resets to auto-detection on next access).
+      def level=(value)
+        raise ArgumentError, "unknown color level: #{value.inspect}" if value && !LEVELS.include?(value)
+
+        @level = value
+      end
+
+      # Detects the color capability from an environment hash.
+      def detect(env)
+        return :none if env["NO_COLOR"] && !env["NO_COLOR"].empty?
+        return :truecolor if %w[truecolor 24bit].include?(env["COLORTERM"])
+
+        term = env["TERM"].to_s
+        return :none if term.empty? || term == "dumb"
+        return :truecolor if term.include?("direct")
+        return :color256 if term.include?("256color")
+
+        :color16
+      end
+
+      # True when the active level is at least *required* (e.g., `at_least?(:color256)`).
+      def at_least?(required)
+        LEVELS.index(level) >= LEVELS.index(required)
+      end
+
+      # Converts "#rrggbb" to the nearest xterm 256-color index (cube or grayscale ramp).
+      def hex_to_256(hex)
+        r, g, b = hex_components(hex)
+        cube = cube_index(r, g, b)
+        gray = gray_index(r, g, b)
+        (color_distance([r, g, b], index_to_rgb(cube)) <= color_distance([r, g, b], index_to_rgb(gray))) ? cube : gray
+      end
+
+      # Converts "#rrggbb" to the nearest of the 16 basic ANSI colors, returned as the
+      # SGR foreground code (30-37 or 90-97).
+      def hex_to_16(hex)
+        rgb = hex_components(hex)
+        best = basic_palette.min_by { |_code, basic_rgb| color_distance(rgb, basic_rgb) }
+        best.first
+      end
+
+      # Converts a 256-color index to the nearest basic ANSI SGR foreground code.
+      def index_to_16(index)
+        rgb = index_to_rgb(index)
+        best = basic_palette.min_by { |_code, basic_rgb| color_distance(rgb, basic_rgb) }
+        best.first
+      end
+
+      # -- conversion internals ----------------------------------------------------
+
+      def hex_components(hex)
+        digits = hex.to_s.delete_prefix("#")
+        [digits[0..1].to_i(16), digits[2..3].to_i(16), digits[4..5].to_i(16)]
+      end
+
+      # Index in the 6x6x6 cube (16-231) closest to the RGB triple.
+      def cube_index(r, g, b)
+        16 + (36 * nearest_cube_level(r)) + (6 * nearest_cube_level(g)) + nearest_cube_level(b)
+      end
+
+      # Index in the grayscale ramp (232-255) closest to the RGB triple's luminance.
+      def gray_index(r, g, b)
+        gray = ((r + g + b) / 3.0).round
+        step = ((gray - 8) / 10.0).round.clamp(0, 23)
+        232 + step
+      end
+
+      def nearest_cube_level(component)
+        CUBE_LEVELS.each_index.min_by { |index| (CUBE_LEVELS[index] - component).abs }
+      end
+
+      # The RGB triple a 256-color *index* renders as.
+      def index_to_rgb(index)
+        if index >= 232
+          gray = 8 + (index - 232) * 10
+          [gray, gray, gray]
+        elsif index >= 16
+          offset = index - 16
+          [CUBE_LEVELS[offset / 36], CUBE_LEVELS[(offset / 6) % 6], CUBE_LEVELS[offset % 6]]
+        else
+          basic_palette.find { |code, _| basic_index_for_code(code) == index }&.last || [0, 0, 0]
+        end
+      end
+
+      def color_distance(a, b)
+        (a[0] - b[0])**2 + (a[1] - b[1])**2 + (a[2] - b[2])**2
+      end
+
+      # The 16 basic ANSI colors as [SGR foreground code, RGB] pairs.
+      def basic_palette
+        @basic_palette ||= {
+          30 => [0, 0, 0], 31 => [205, 49, 49], 32 => [13, 188, 121], 33 => [229, 229, 16],
+          34 => [36, 114, 200], 35 => [188, 63, 188], 36 => [17, 168, 205], 37 => [229, 229, 229],
+          90 => [102, 102, 102], 91 => [241, 76, 76], 92 => [35, 209, 139], 93 => [245, 245, 67],
+          94 => [59, 142, 234], 95 => [214, 112, 214], 96 => [41, 184, 219], 97 => [255, 255, 255]
+        }
+      end
+
+      def basic_index_for_code(code)
+        (code < 90) ? code - 30 : code - 90 + 8
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Charming
+  module UI
+    # Gradient interpolates between two hex colors: blend a single point, build
+    # an evenly spaced ramp, or paint text with a per-character color sweep.
+    module Gradient
+      module_function
+
+      # Blends *start_hex* and *end_hex* ("#rrggbb") at fractional *amount*
+      # (0.0 → start, 1.0 → end), returning a "#rrggbb" string.
+      def blend(start_hex, end_hex, amount)
+        mixed = rgb(start_hex).zip(rgb(end_hex)).map do |from, to|
+          (from + ((to - from) * amount)).round
+        end
+        format("#%02x%02x%02x", *mixed)
+      end
+
+      # An evenly spaced ramp of *count* colors from *start_hex* to *end_hex*,
+      # endpoints included.
+      def steps(start_hex, end_hex, count)
+        return [blend(start_hex, end_hex, 0.0)] if count <= 1
+
+        Array.new(count) { |index| blend(start_hex, end_hex, index.to_f / (count - 1)) }
+      end
+
+      # Paints each grapheme cluster of plain-text *text* with a foreground color
+      # swept from *from* to *to* across its visible characters.
+      def colorize(text, from:, to:)
+        clusters = text.to_s.scan(Width::GRAPHEME)
+        span = [clusters.length - 1, 1].max
+
+        clusters.each_with_index.map do |cluster, index|
+          Style.new(foreground: blend(from, to, index.to_f / span)).render(cluster)
+        end.join
+      end
+
+      # Decomposes "#rrggbb" into [r, g, b] integers.
+      def rgb(hex)
+        value = hex.to_s.delete_prefix("#")
+        raise ArgumentError, "gradient colors must be #rrggbb" unless value.match?(/\A[0-9a-fA-F]{6}\z/)
+
+        [value[0..1], value[2..3], value[4..5]].map { |part| part.to_i(16) }
+      end
+    end
+  end
+end