fatty 0.99.0 → 0.99.3

data/lib/fatty/colors/color.rb

@@ -34,6 +34,25 @@ module Fatty
       "default" => DEFAULT_INDEX,
     }.freeze
 
+    CANONICAL_ANSI_COLORS = {
+      "black" => 0,
+      "red" => 1,
+      "green" => 2,
+      "yellow" => 3,
+      "blue" => 4,
+      "magenta" => 5,
+      "cyan" => 6,
+      "white" => 7,
+      "bright_black" => 8,
+      "bright_red" => 9,
+      "bright_green" => 10,
+      "bright_yellow" => 11,
+      "bright_blue" => 12,
+      "bright_magenta" => 13,
+      "bright_cyan" => 14,
+      "bright_white" => 15,
+    }.freeze
+
     # Small alias set (xterm-256 indices). Keep this small + opinionated.
     # Users can always use integers/hex/X11 names.
     ALIASES_256 = {
@@ -74,306 +93,421 @@ module Fatty
       15 => [255, 255, 255],
     }.freeze
 
-    # Resolve a color specification to an integer color index suitable for curses init_pair.
-    #
-    # Accepts:
-    # - Integer (e.g. 17, 226, -1)
-    # - ANSI name (e.g. "yellow", "bright_blue", "default")
-    # - Alias (e.g. "navy")
-    # - Hex string (#RRGGBB or #RGB)
-    # - X11 name (e.g. "MidnightBlue") resolved via bundled rgb.txt
-    #
-    # available_colors:
-    # - If <= 16, any resolved 256-color index is down-mapped to nearest ANSI 0..15.
-    # - If > 16, returns xterm-256 indices 0..255 (or -1 for default).
-    def self.resolve(spec, available_colors: 256)
-      spec_norm = spec
-
-      idx =
-        if spec_norm.is_a?(Integer)
-          spec_norm
-        elsif spec_norm.nil?
-          DEFAULT_INDEX
-        else
-          resolve_stringish(spec_norm.to_s, available_colors: available_colors)
+    class << self
+      def ansi_colors
+        CANONICAL_ANSI_COLORS.dup
+      end
+
+      def xterm_colors
+        (0..255).to_h do |index|
+          [xterm_color_name(index), index]
         end
+      end
 
-      if idx == DEFAULT_INDEX
-        idx
-      else
-        clamp_index(idx, available_colors: available_colors)
+      def x11_colors
+        x11_table.dup
+      end
+
+      def x11_colors_by_name
+        x11_colors.sort_by do |name, _rgb|
+          color_name_sort_key(name)
+        end.to_h
       end
-    end
 
-    def self.resolve_stringish(str, available_colors: 256)
-      s = normalize_name(str)
-      # Disambiguation prefixes:
-      # - "ansi:yellow" forces ANSI 0..15 names
-      # - "x11:yellow" forces X11 rgb.txt lookup
+      def xterm_color_name(index)
+        if index.between?(0, 15)
+          CANONICAL_ANSI_COLORS.key(index)
+        elsif index.between?(16, 231)
+          "xterm_#{index}"
+        elsif index.between?(232, 255)
+          "gray_#{index}"
+        else
+          "color_#{index}"
+        end
+      end
+
+      # Resolve a color specification to an integer color index suitable for curses init_pair.
+      #
+      # Accepts:
+      # - Integer (e.g. 17, 226, -1)
+      # - ANSI name (e.g. "yellow", "bright_blue", "default")
+      # - Alias (e.g. "navy")
+      # - Hex string (#RRGGBB or #RGB)
+      # - X11 name (e.g. "MidnightBlue") resolved via bundled rgb.txt
       #
-      # Without a prefix, prefer X11 names when 256 colors are available so
-      # common names like "yellow" match X11 "#FFFF00" rather than ANSI 3.
-      mode = nil
-      if s.start_with?("ansi:")
-        mode = :ansi
-        s = s.delete_prefix("ansi:")
-      elsif s.start_with?("x11:")
-        mode = :x11
-        s = s.delete_prefix("x11:")
+      # available_colors:
+      # - If <= 16, any resolved 256-color index is down-mapped to nearest ANSI 0..15.
+      # - If > 16, returns xterm-256 indices 0..255 (or -1 for default).
+      def resolve(spec, available_colors: 256)
+        spec_norm = spec
+
+        idx =
+          if spec_norm.is_a?(Integer)
+            spec_norm
+          elsif spec_norm.nil?
+            DEFAULT_INDEX
+          else
+            resolve_stringish(spec_norm.to_s, available_colors: available_colors)
+          end
+
+        if idx == DEFAULT_INDEX
+          idx
+        else
+          clamp_index(idx, available_colors: available_colors)
+        end
+      end
+
+      def rgb(spec)
+        if spec.is_a?(Integer)
+          xterm_rgb_for_index(spec)
+        elsif spec.nil?
+          nil
+        else
+          s = normalize_name(spec.to_s)
+
+          if s.start_with?("ansi:")
+            s = s.delete_prefix("ansi:")
+          elsif s.start_with?("x11:")
+            s = s.delete_prefix("x11:")
+          end
+
+          idx = ALIASES_256[s]
+          if idx
+            xterm_rgb_for_index(idx)
+          else
+            parsed = parse_hex(s)
+            parsed ||= x11_rgb_for_name(s)
+            parsed ||= begin
+                         ansi = ANSI_NAMES[s]
+                         xterm_rgb_for_index(ansi) unless ansi == DEFAULT_INDEX || ansi.nil?
+                       end
+            parsed
+          end
+        end
       end
 
-      idx = ALIASES_256[s]
-      return idx unless idx.nil?
+      # Convert any RGB to an xterm-256 index (16..255).
+      # We consider both the 6x6x6 cube and the grayscale ramp and pick the closer.
+      def xterm_index_for_rgb(r, g, b)
+        rr = clamp_byte(r)
+        gg = clamp_byte(g)
+        bb = clamp_byte(b)
 
-      rgb = parse_hex(s)
-      return xterm_index_for_rgb(rgb[0], rgb[1], rgb[2]) if rgb
+        cube = xterm_cube_index(rr, gg, bb)
+        gray = xterm_gray_index(rr, gg, bb)
 
-      prefer_x11 = (mode == :x11) || (mode.nil? && available_colors.to_i >= 256)
+        cube_rgb = xterm_rgb_for_index(cube)
+        gray_rgb = xterm_rgb_for_index(gray)
 
-      if prefer_x11
-        rgb2 = x11_rgb_for_name(s)
-        return xterm_index_for_rgb(rgb2[0], rgb2[1], rgb2[2]) if rgb2
+        if dist2(rr, gg, bb, gray_rgb[0], gray_rgb[1], gray_rgb[2]) <
+           dist2(rr, gg, bb, cube_rgb[0], cube_rgb[1], cube_rgb[2])
+          gray
+        else
+          cube
+        end
       end
 
-      idx = ANSI_NAMES[s]
-      return idx unless idx.nil?
+      def xterm_rgb_for_index(idx)
+        i = idx.to_i
+
+        if i.between?(232, 255)
+          v = 8 + (i - 232) * 10
+          [v, v, v]
+        elsif i.between?(16, 231)
+          j = i - 16
+          r = j / 36
+          g = (j % 36) / 6
+          b = j % 6
+          levels = [0, 95, 135, 175, 215, 255]
+          [levels[r], levels[g], levels[b]]
+        else
+          # for 0..15 we use ANSI_RGB as an approximation
+          ANSI_RGB[i] || [0, 0, 0]
+        end
+      end
+
+      def clamp_index(idx, available_colors:)
+        i = idx.to_i
+
+        result =
+          if available_colors.to_i <= 0
+            0
+          elsif available_colors.to_i <= 16
+            downmap_to_ansi16(i)
+          else
+            i.clamp(0, 255)
+          end
 
-      unless prefer_x11
-        rgb2 = x11_rgb_for_name(s)
-        return xterm_index_for_rgb(rgb2[0], rgb2[1], rgb2[2]) if rgb2
+        result
       end
 
-      # Unknown name: treat as default.
-      DEFAULT_INDEX
-    end
+      def contrasting_ansi_index_for_rgb(rgb)
+        luminance = ((rgb[0] * 299) + (rgb[1] * 587) + (rgb[2] * 114)) / 1000
+        luminance >= 140 ? 0 : 15
+      end
 
-    def self.normalize_name(str)
-      # normalize spaces/underscores/hyphens and case, so:
-      # "Light Sky Blue" == "light_sky_blue" == "lightskyblue"
-      s = str.to_s.strip.downcase
-      s = s.tr("-", "_")
-      s = s.gsub(/\s+/, "")
-      s
-    end
+      def hex_for_rgb(rgb)
+        format("#%02x%02x%02x", *rgb)
+      end
 
-    def self.parse_hex(s)
-      # Accept "#rgb" or "#rrggbb"
-      hex = s
-      if hex.start_with?("#")
-        hex = hex[1..]
+      def hex_for_index(index)
+        hex_for_rgb(xterm_rgb_for_index(index))
       end
 
-      if hex.match?(/\A[0-9a-f]{3}\z/i)
-        r = (hex[0] * 2).to_i(16)
-        g = (hex[1] * 2).to_i(16)
-        b = (hex[2] * 2).to_i(16)
-        [r, g, b]
-      elsif hex.match?(/\A[0-9a-f]{6}\z/i)
-        r = hex[0, 2].to_i(16)
-        g = hex[2, 2].to_i(16)
-        b = hex[4, 2].to_i(16)
-        [r, g, b]
+      def luminance_for_rgb(rgb)
+        ((rgb[0] * 299) + (rgb[1] * 587) + (rgb[2] * 114)) / 1000
       end
-    end
 
-    def self.clamp_index(idx, available_colors:)
-      max = available_colors.to_i - 1
-      0 if max < 0
+      def contrasting_rgb(rgb)
+        if luminance_for_rgb(rgb) >= 140
+          [0, 0, 0]
+        else
+          [255, 255, 255]
+        end
+      end
 
-      i = idx.to_i
+      def contrasting_ansi_index(index)
+        rgb = xterm_rgb_for_index(index)
+        fg = contrasting_rgb(rgb)
 
-      if available_colors.to_i <= 16
-        downmap_to_ansi16(i)
-      else
-        i.clamp(0, 255)
+        if fg == [0, 0, 0]
+          0
+        else
+          15
+        end
       end
-    end
 
-    def self.rgb(spec)
-      if spec.is_a?(Integer)
-        xterm_rgb_for_index(spec)
-      elsif spec.nil?
-        nil
-      else
-        s = normalize_name(spec.to_s)
+      private
+
+      def color_name_sort_key(name)
+        name.to_s.split(/(\d+)/).map do |part|
+          if part.match?(/\A\d+\z/)
+            [0, part.to_i]
+          else
+            [1, part]
+          end
+        end
+      end
 
+      def resolve_stringish(str, available_colors: 256)
+        s = normalize_name(str)
+        # Disambiguation prefixes:
+        # - "ansi:yellow" forces ANSI 0..15 names
+        # - "x11:yellow" forces X11 rgb.txt lookup
+        #
+        # Without a prefix, prefer X11 names when 256 colors are available so
+        # common names like "yellow" match X11 "#FFFF00" rather than ANSI 3.
+        mode = nil
         if s.start_with?("ansi:")
+          mode = :ansi
           s = s.delete_prefix("ansi:")
         elsif s.start_with?("x11:")
+          mode = :x11
           s = s.delete_prefix("x11:")
         end
 
         idx = ALIASES_256[s]
-        if idx
-          xterm_rgb_for_index(idx)
-        else
-          parsed = parse_hex(s)
-          parsed ||= x11_rgb_for_name(s)
-          parsed ||= begin
-            ansi = ANSI_NAMES[s]
-            xterm_rgb_for_index(ansi) unless ansi == DEFAULT_INDEX || ansi.nil?
-          end
-          parsed
+        return idx unless idx.nil?
+
+        rgb = parse_hex(s)
+        return xterm_index_for_rgb(rgb[0], rgb[1], rgb[2]) if rgb
+
+        prefer_x11 = (mode == :x11) || (mode.nil? && available_colors.to_i >= 256)
+
+        if prefer_x11
+          rgb2 = x11_rgb_for_name(s)
+          return xterm_index_for_rgb(rgb2[0], rgb2[1], rgb2[2]) if rgb2
         end
-      end
-    end
 
-    # Convert any RGB to an xterm-256 index (16..255).
-    # We consider both the 6x6x6 cube and the grayscale ramp and pick the closer.
-    def self.xterm_index_for_rgb(r, g, b)
-      rr = clamp_byte(r)
-      gg = clamp_byte(g)
-      bb = clamp_byte(b)
+        idx = ANSI_NAMES[s]
+        return idx unless idx.nil?
 
-      cube = xterm_cube_index(rr, gg, bb)
-      gray = xterm_gray_index(rr, gg, bb)
+        unless prefer_x11
+          rgb2 = x11_rgb_for_name(s)
+          return xterm_index_for_rgb(rgb2[0], rgb2[1], rgb2[2]) if rgb2
+        end
 
-      cube_rgb = xterm_rgb_for_index(cube)
-      gray_rgb = xterm_rgb_for_index(gray)
+        # Unknown name: treat as default.
+        DEFAULT_INDEX
+      end
 
-      if dist2(rr, gg, bb, gray_rgb[0], gray_rgb[1], gray_rgb[2]) <
-         dist2(rr, gg, bb, cube_rgb[0], cube_rgb[1], cube_rgb[2])
-        gray
-      else
-        cube
+      def normalize_name(str)
+        # normalize spaces/underscores/hyphens and case, so:
+        # "Light Sky Blue" == "light_sky_blue" == "lightskyblue"
+        s = str.to_s.strip.downcase
+        s = s.tr("-", "_")
+        s = s.gsub(/\s+/, "")
+        s
       end
-    end
 
-    def self.xterm_cube_index(r, g, b)
-      levels = [0, 95, 135, 175, 215, 255]
-      ri = nearest_index(levels, r)
-      gi = nearest_index(levels, g)
-      bi = nearest_index(levels, b)
-      16 + (36 * ri) + (6 * gi) + bi
-    end
+      def parse_hex(s)
+        # Accept "#rgb" or "#rrggbb"
+        hex = s
+        if hex.start_with?("#")
+          hex = hex[1..]
+        end
 
-    def self.xterm_gray_index(r, g, b)
-      # grayscale ramp 232..255 maps to levels 8 + 10*n
-      avg = (r + g + b) / 3
-      if avg < 8
-        16 # near black; keep in extended palette, not ANSI black
-      elsif avg > 238
-        231 # near white; a cube white
-      else
-        n = ((avg - 8) / 10.0).round
-        n = 0 if n < 0
-        n = 23 if n > 23
-        232 + n
+        if hex.match?(/\A[0-9a-f]{3}\z/i)
+          r = (hex[0] * 2).to_i(16)
+          g = (hex[1] * 2).to_i(16)
+          b = (hex[2] * 2).to_i(16)
+          [r, g, b]
+        elsif hex.match?(/\A[0-9a-f]{6}\z/i)
+          r = hex[0, 2].to_i(16)
+          g = hex[2, 2].to_i(16)
+          b = hex[4, 2].to_i(16)
+          [r, g, b]
+        end
       end
-    end
 
-    def self.xterm_rgb_for_index(idx)
-      i = idx.to_i
-
-      if i.between?(232, 255)
-        v = 8 + (i - 232) * 10
-        [v, v, v]
-      elsif i.between?(16, 231)
-        j = i - 16
-        r = j / 36
-        g = (j % 36) / 6
-        b = j % 6
+      def xterm_cube_index(r, g, b)
         levels = [0, 95, 135, 175, 215, 255]
-        [levels[r], levels[g], levels[b]]
-      else
-        # for 0..15 we use ANSI_RGB as an approximation
-        ANSI_RGB[i] || [0, 0, 0]
+        ri = nearest_index(levels, r)
+        gi = nearest_index(levels, g)
+        bi = nearest_index(levels, b)
+        16 + (36 * ri) + (6 * gi) + bi
       end
-    end
 
-    def self.downmap_to_ansi16(idx)
-      if idx == DEFAULT_INDEX
-        DEFAULT_INDEX
-      elsif idx.between?(0, 15)
-        idx
-      else
-        rgb = xterm_rgb_for_index(idx)
-        nearest_ansi_index(rgb[0], rgb[1], rgb[2])
+      def xterm_gray_index(r, g, b)
+        # grayscale ramp 232..255 maps to levels 8 + 10*n
+        avg = (r + g + b) / 3
+        if avg < 8
+          16 # near black; keep in extended palette, not ANSI black
+        elsif avg > 238
+          231 # near white; a cube white
+        else
+          n = ((avg - 8) / 10.0).round
+          n = 0 if n < 0
+          n = 23 if n > 23
+          232 + n
+        end
       end
-    end
-
-    def self.nearest_ansi_index(r, g, b)
-      best = 0
-      best_d = nil
 
-      ANSI_RGB.each do |i, rgb|
-        d = dist2(r, g, b, rgb[0], rgb[1], rgb[2])
-        if best_d.nil? || d < best_d
-          best_d = d
-          best = i
+      def downmap_to_ansi16(idx)
+        if idx == DEFAULT_INDEX
+          DEFAULT_INDEX
+        elsif idx.between?(0, 15)
+          idx
+        else
+          rgb = xterm_rgb_for_index(idx)
+          nearest_ansi_index(rgb[0], rgb[1], rgb[2])
         end
       end
 
-      best
-    end
-
-    def self.nearest_index(levels, value)
-      v = value.to_i
-      best_i = 0
-      best_d = nil
+      def nearest_ansi_index(r, g, b)
+        best = 0
+        best_d = nil
 
-      levels.each_with_index do |lvl, i|
-        d = (lvl - v).abs
-        if best_d.nil? || d < best_d
-          best_d = d
-          best_i = i
+        ANSI_RGB.each do |i, rgb|
+          d = dist2(r, g, b, rgb[0], rgb[1], rgb[2])
+          if best_d.nil? || d < best_d
+            best_d = d
+            best = i
+          end
         end
+
+        best
       end
 
-      best_i
-    end
+      def nearest_index(levels, value)
+        v = value.to_i
+        best_i = 0
+        best_d = nil
 
-    def self.clamp_byte(v)
-      x = v.to_i
-      x = 0 if x < 0
-      x = 255 if x > 255
-      x
-    end
+        levels.each_with_index do |lvl, i|
+          d = (lvl - v).abs
+          if best_d.nil? || d < best_d
+            best_d = d
+            best_i = i
+          end
+        end
 
-    def self.dist2(r1, g1, b1, r2, g2, b2)
-      dr = r1 - r2
-      dg = g1 - g2
-      db = b1 - b2
-      (dr * dr) + (dg * dg) + (db * db)
-    end
+        best_i
+      end
 
-    def self.x11_rgb_for_name(name_norm)
-      table = x11_table
-      table[name_norm]
-    end
+      def clamp_byte(v)
+        x = v.to_i
+        x = 0 if x < 0
+        x = 255 if x > 255
+        x
+      end
 
-    def self.x11_table
-      path = RGB_TXT_PATH
+      def dist2(r1, g1, b1, r2, g2, b2)
+        dr = r1 - r2
+        dg = g1 - g2
+        db = b1 - b2
+        (dr * dr) + (dg * dg) + (db * db)
+      end
 
-      if @x11_table_path != path
-        @x11_table = load_x11_rgb_txt(path)
-        @x11_table_path = path
+      def x11_rgb_for_name(name_norm)
+        table = x11_table
+        table[name_norm]
+      end
+
+      def x11_table
+        path = RGB_TXT_PATH
+
+        if @x11_table_path != path
+          @x11_table = load_x11_rgb_txt(path)
+          @x11_table_path = path
+        end
+        @x11_table
       end
-      @x11_table
-    end
 
-    def self.load_x11_rgb_txt(path)
-      table = {}
+      def load_x11_rgb_txt(path)
+        table = {}
 
-      if File.file?(path)
-        File.foreach(path) do |line|
-          next if line.strip.empty?
-          next if line.lstrip.start_with?("!")
+        if File.file?(path)
+          File.foreach(path) do |line|
+            next if line.strip.empty?
+            next if line.lstrip.start_with?("!")
 
-          # Format: R G B <name...>
-          parts = line.strip.split(/\s+/)
-          next if parts.length < 4
+            # Format: R G B <name...>
+            parts = line.strip.split(/\s+/)
+            next if parts.length < 4
 
-          r = parts[0].to_i
-          g = parts[1].to_i
-          b = parts[2].to_i
-          name = parts[3..].join(" ")
-          key = normalize_name(name)
-          table[key] = [r, g, b]
+            r = parts[0].to_i
+            g = parts[1].to_i
+            b = parts[2].to_i
+            name = parts[3..].join(" ")
+            key = normalize_name(name)
+            table[key] = [r, g, b]
+          end
         end
+
+        table
       end
 
-      table
+      def load_x11_rgb_txt(path)
+        table = {}
+
+        if File.file?(path)
+          File.foreach(path) do |line|
+            next if line.strip.empty?
+            next if line.lstrip.start_with?("!")
+            next if line.lstrip.start_with?("#")
+
+            parts = line.strip.split(/\s+/, 4)
+            next unless parts.length == 4
+            next unless parts[0].match?(/\A\d+\z/)
+            next unless parts[1].match?(/\A\d+\z/)
+            next unless parts[2].match?(/\A\d+\z/)
+
+            r = parts[0].to_i
+            g = parts[1].to_i
+            b = parts[2].to_i
+            next unless r.between?(0, 255)
+            next unless g.between?(0, 255)
+            next unless b.between?(0, 255)
+
+            name = parts[3]
+            key = normalize_name(name)
+            table[key] = [r, g, b]
+          end
+        end
+
+        table
+      end
     end
   end
 end