unmagic-color 0.1.0 → 0.2.1

data/lib/unmagic/color/rgb.rb

@@ -62,24 +62,29 @@ module Unmagic
       # Error raised when parsing RGB color strings fails
       class ParseError < Color::Error; end
 
-      attr_reader :red, :green, :blue
+      attr_reader :red, :green, :blue, :alpha
 
       # Create a new RGB color.
       #
       # @param red [Integer] Red component (0-255), values outside this range are clamped
       # @param green [Integer] Green component (0-255), values outside this range are clamped
       # @param blue [Integer] Blue component (0-255), values outside this range are clamped
+      # @param alpha [Numeric, Color::Alpha, nil] Alpha channel (0-100%), defaults to 100 (fully opaque)
       #
       # @example Create a red color
       #   RGB.new(red: 255, green: 0, blue: 0)
       #
+      # @example Create a semi-transparent red
+      #   RGB.new(red: 255, green: 0, blue: 0, alpha: 50)
+      #
       # @example Values are automatically clamped
       #   RGB.new(red: 300, green: -10, blue: 128)
-      def initialize(red:, green:, blue:)
+      def initialize(red:, green:, blue:, alpha: nil)
         super()
         @red = Color::Red.new(value: red)
         @green = Color::Green.new(value: green)
         @blue = Color::Blue.new(value: blue)
+        @alpha = Color::Alpha.build(alpha) || Color::Alpha::DEFAULT
       end
 
       class << self
@@ -107,6 +112,11 @@ module Unmagic
 
           input = input.strip
 
+          # Check for ANSI format first (numeric with optional semicolons)
+          if input.match?(/\A\d+(?:;\d+)*\z/) && ANSI.valid?(input)
+            return ANSI.parse(input)
+          end
+
           # Check if it looks like a hex color (starts with # or only contains hex digits)
           if input.start_with?("#") || input.match?(/\A[0-9A-Fa-f]{3,6}\z/)
             return Hex.parse(input)
@@ -116,6 +126,58 @@ module Unmagic
           parse_rgb_format(input)
         end
 
+        # Build an RGB color from an integer, string, positional values, or keyword arguments.
+        #
+        # @param args [Integer, String, Array<Integer>] Either an integer (0xRRGGBB), color string, or 3 component values
+        # @option kwargs [Integer] :red Red component (0-255)
+        # @option kwargs [Integer] :green Green component (0-255)
+        # @option kwargs [Integer] :blue Blue component (0-255)
+        # @return [RGB] The constructed RGB color
+        #
+        # @example From integer (packed RGB)
+        #   RGB.build(0xDAA520)        # goldenrod
+        #   RGB.build(14329120)        # same as 0xDAA520
+        #
+        # @example From string
+        #   RGB.build("#FF8800")
+        #
+        # @example From positional values
+        #   RGB.build(255, 128, 0)
+        #
+        # @example From keyword arguments
+        #   RGB.build(red: 255, green: 128, blue: 0)
+        def build(*args, **kwargs)
+          # Handle keyword arguments
+          return new(**kwargs) if kwargs.any?
+
+          # Handle single argument
+          if args.length == 1
+            value = args[0]
+
+            # Integer: extract RGB components via bit operations
+            if value.is_a?(::Integer)
+              return new(
+                red: (value >> 16) & 0xFF,
+                green: (value >> 8) & 0xFF,
+                blue: value & 0xFF,
+              )
+            end
+
+            # String: delegate to parse
+            return parse(value) if value.is_a?(::String)
+
+            raise ArgumentError, "Expected Integer or String, got #{value.class}"
+          end
+
+          # Handle three positional arguments (r, g, b)
+          if args.length == 3
+            values = args.map { |v| v.is_a?(::String) ? v.to_i : v }
+            return new(red: values[0], green: values[1], blue: values[2])
+          end
+
+          raise ArgumentError, "Expected 1 or 3 arguments, got #{args.length}"
+        end
+
         # Generate a deterministic RGB color from an integer seed.
         #
         # This creates consistent, visually distinct colors from hash values or IDs.
@@ -169,33 +231,64 @@ module Unmagic
           new(red: r, green: g, blue: b)
         end
 
-        # Parse RGB format like "rgb(255, 128, 0)" or "255, 128, 0"
+        # Parse RGB format like "rgb(255, 128, 0)" or "rgb(255 128 0 / 0.5)"
+        #
+        # Supports both legacy comma-separated format and modern space-separated
+        # format with optional alpha value.
         #
         # @param input [String] RGB string to parse
         # @return [RGB] Parsed RGB color
         # @raise [ParseError] If format is invalid
         def parse_rgb_format(input)
-          # Remove rgb() wrapper if present
-          clean = input.gsub(/^rgb\s*\(\s*|\s*\)$/, "").strip
+          # Remove rgb() or rgba() wrapper if present
+          clean = input.gsub(/^rgba?\s*\(\s*|\s*\)$/, "").strip
+
+          # Check for modern format with slash (space-separated with / for alpha)
+          # Example: "255 128 0 / 0.5" or "255 128 0 / 50%"
+          if clean.include?("/")
+            parts = clean.split("/").map(&:strip)
+            raise ParseError, "Invalid format with /: expected 'R G B / alpha'" unless parts.length == 2
+
+            rgb_values = parts[0].split(/\s+/)
+            alpha_str = parts[1]
+
+            unless rgb_values.length == 3
+              raise ParseError, "Expected 3 RGB values before /, got #{rgb_values.length}"
+            end
 
-          # Split values
+            alpha = Color::Alpha.parse(alpha_str)
+            r, g, b = parse_rgb_values(rgb_values)
+
+            return new(red: r, green: g, blue: b, alpha: alpha)
+          end
+
+          # Legacy comma-separated format (with or without alpha)
+          # Example: "255, 128, 0" or "255, 128, 0, 0.5"
           values = clean.split(/\s*,\s*/)
-          unless values.length == 3
-            raise ParseError, "Expected 3 RGB values, got #{values.length}"
+
+          unless [3, 4].include?(values.length)
+            raise ParseError, "Expected 3 or 4 RGB values, got #{values.length}"
           end
 
-          # Check if all values are numeric (allow negative for clamping)
-          values.each_with_index do |v, i|
+          r, g, b = parse_rgb_values(values[0..2])
+          alpha = values.length == 4 ? Color::Alpha.parse(values[3]) : nil
+
+          new(red: r, green: g, blue: b, alpha: alpha)
+        end
+
+        # Parse RGB component values
+        #
+        # @param values [Array<String>] Array of 3 RGB value strings
+        # @return [Array<Integer>] Array of 3 integers (0-255)
+        # @raise [ParseError] If values are invalid
+        def parse_rgb_values(values)
+          values.map.with_index do |v, i|
             unless v.match?(/\A-?\d+\z/)
               component = ["red", "green", "blue"][i]
               raise ParseError, "Invalid #{component} value: #{v.inspect} (must be a number)"
             end
+            v.to_i
           end
-
-          # Convert to integers (constructor will clamp)
-          parsed = values.map(&:to_i)
-
-          new(red: parsed[0], green: parsed[1], blue: parsed[2])
         end
       end
 
@@ -211,16 +304,27 @@ module Unmagic
       # Convert to hexadecimal color string.
       #
       # Returns a lowercase hex string with hash prefix, always 6 characters
-      # (2 per component).
+      # (2 per component). If alpha is less than 100%, includes 8 characters
+      # with alpha as the last 2 hex digits.
       #
-      # @return [String] Hex color string like "#ff5733"
+      # @return [String] Hex color string like "#ff5733" or "#ff5733 80" with alpha
       #
-      # @example
+      # @example Fully opaque color
       #   rgb = RGB.new(red: 255, green: 87, blue: 51)
       #   rgb.to_hex
       #   # => "#ff5733"
+      #
+      # @example Semi-transparent color
+      #   rgb = RGB.new(red: 255, green: 87, blue: 51, alpha: 50)
+      #   rgb.to_hex
+      #   # => "#ff573380"
       def to_hex
-        format("#%02x%02x%02x", @red.value, @green.value, @blue.value)
+        if @alpha.value < 100
+          alpha_hex = (@alpha.to_ratio * 255).round.to_s(16).rjust(2, "0")
+          format("#%02x%02x%02x%s", @red.value, @green.value, @blue.value, alpha_hex)
+        else
+          format("#%02x%02x%02x", @red.value, @green.value, @blue.value)
+        end
       end
 
       # Convert to HSL color space.
@@ -265,7 +369,12 @@ module Unmagic
           end
         end
 
-        Unmagic::Color::HSL.new(hue: (h * 360).round, saturation: (s * 100).round, lightness: (l * 100).round)
+        Unmagic::Color::HSL.new(
+          hue: (h * 360).round,
+          saturation: (s * 100).round,
+          lightness: (l * 100).round,
+          alpha: @alpha,
+        )
       end
 
       # Convert to OKLCH color space.
@@ -282,9 +391,9 @@ module Unmagic
         l = luminance
         # Approximate chroma from saturation and lightness
         hsl = to_hsl
-        c = (hsl.saturation / 100.0) * 0.2 * (1 - (l - 0.5).abs * 2)
+        c = hsl.saturation.to_ratio * 0.2 * (1 - (l - 0.5).abs * 2)
         h = hsl.hue
-        Unmagic::Color::OKLCH.new(lightness: l, chroma: c, hue: h)
+        Unmagic::Color::OKLCH.new(lightness: l, chroma: c, hue: h, alpha: @alpha)
       end
 
       # Calculate the relative luminance.
@@ -339,6 +448,7 @@ module Unmagic
           red: (@red.value * (1 - amount) + other_rgb.red.value * amount).round,
           green: (@green.value * (1 - amount) + other_rgb.green.value * amount).round,
           blue: (@blue.value * (1 - amount) + other_rgb.blue.value * amount).round,
+          alpha: @alpha.value * (1 - amount) + other_rgb.alpha.value * amount,
         )
       end
 
@@ -385,6 +495,199 @@ module Unmagic
       def to_s
         to_hex
       end
+
+      # Convert to ANSI SGR color code.
+      #
+      # Returns an ANSI Select Graphic Rendition (SGR) parameter string for terminal output.
+      # Supports multiple color modes for different terminal capabilities.
+      #
+      # @param layer [Symbol] Whether to generate foreground (:foreground) or background (:background) code
+      # @param mode [Symbol] Color format mode:
+      #   - :truecolor (default) - 24-bit RGB (38;2;R;G;B or 48;2;R;G;B)
+      #   - :palette256 - 256-color palette (38;5;N or 48;5;N)
+      #   - :palette16 - 16-color palette (30-37, 90-97, 40-47, 100-107)
+      # @return [String] ANSI SGR code
+      # @raise [ArgumentError] If layer or mode is invalid
+      #
+      # @example Default mode (truecolor)
+      #   red = RGB.new(red: 255, green: 0, blue: 0)
+      #   red.to_ansi
+      #   # => "38;2;255;0;0"
+      #
+      # @example Background color
+      #   red = RGB.new(red: 255, green: 0, blue: 0)
+      #   red.to_ansi(layer: :background)
+      #   # => "48;2;255;0;0"
+      #
+      # @example True color mode (explicit)
+      #   custom = RGB.new(red: 100, green: 150, blue: 200)
+      #   custom.to_ansi(mode: :truecolor)
+      #   # => "38;2;100;150;200"
+      #
+      # @example 256-color palette mode
+      #   custom = RGB.new(red: 100, green: 150, blue: 200)
+      #   custom.to_ansi(mode: :palette256)
+      #   # => "38;5;67"
+      #
+      # @example 16-color palette mode
+      #   custom = RGB.new(red: 100, green: 150, blue: 200)
+      #   custom.to_ansi(mode: :palette16)
+      #   # => "34"
+      def to_ansi(layer: :foreground, mode: :truecolor)
+        raise ArgumentError, "layer must be :foreground or :background" unless [:foreground, :background].include?(layer)
+        raise ArgumentError, "mode must be :truecolor, :palette256, or :palette16" unless [:truecolor, :palette256, :palette16].include?(mode)
+
+        case mode
+        when :truecolor
+          to_ansi_truecolor(layer)
+        when :palette256
+          to_ansi_palette256(layer)
+        when :palette16
+          to_ansi_palette16(layer)
+        end
+      end
+
+      private
+
+      # Convert to ANSI true color format (24-bit RGB).
+      #
+      # @param layer [Symbol] Foreground or background layer
+      # @return [String] ANSI SGR code
+      def to_ansi_truecolor(layer)
+        prefix = layer == :foreground ? 38 : 48
+        "#{prefix};2;#{@red.value};#{@green.value};#{@blue.value}"
+      end
+
+      # Convert to ANSI 256-color palette format.
+      #
+      # Finds the nearest color in the 256-color palette.
+      #
+      # @param layer [Symbol] Foreground or background layer
+      # @return [String] ANSI SGR code
+      def to_ansi_palette256(layer)
+        index = rgb_to_palette256
+        prefix = layer == :foreground ? 38 : 48
+        "#{prefix};5;#{index}"
+      end
+
+      # Convert to 16-color palette ANSI format.
+      #
+      # Finds the nearest of the 8 basic colors and uses bright variants.
+      #
+      # @param layer [Symbol] Foreground or background layer
+      # @return [String] ANSI SGR code
+      def to_ansi_palette16(layer)
+        index = rgb_to_palette16
+        prefix = layer == :foreground ? 90 : 100
+        (prefix + index).to_s
+      end
+
+      # Find the nearest color in the 256-color palette.
+      #
+      # @return [Integer] Palette index (0-255)
+      def rgb_to_palette256
+        r = @red.value
+        g = @green.value
+        b = @blue.value
+
+        # Check if it's grayscale (all components within small threshold)
+        if (r - g).abs < 10 && (r - b).abs < 10 && (g - b).abs < 10
+          # Use grayscale ramp (232-255)
+          gray = (r + g + b) / 3
+          if gray < 8
+            return 16 # Use first RGB cube entry for very dark
+          elsif gray > 238
+            return 231 # Use last RGB cube entry for very light
+          else
+            # Map to grayscale ramp: 232 + (0-23)
+            index = ((gray - 8) / 10.0).round
+            return 232 + index.clamp(0, 23)
+          end
+        end
+
+        # Find nearest in 6x6x6 RGB cube (16-231)
+        # Each component: 0, 95, 135, 175, 215, 255 (values 0-5)
+        r_index = rgb_to_cube_index(r)
+        g_index = rgb_to_cube_index(g)
+        b_index = rgb_to_cube_index(b)
+
+        16 + (r_index * 36) + (g_index * 6) + b_index
+      end
+
+      # Convert RGB component to 6x6x6 cube index.
+      #
+      # @param value [Integer] RGB component value (0-255)
+      # @return [Integer] Cube index (0-5)
+      def rgb_to_cube_index(value)
+        # Cube values: 0, 95, 135, 175, 215, 255
+        # Thresholds: 47.5, 115, 155, 195, 235
+        if value < 48
+          0
+        elsif value < 115
+          1
+        elsif value < 155
+          2
+        elsif value < 195
+          3
+        elsif value < 235
+          4
+        else
+          5
+        end
+      end
+
+      # Find the nearest color in the 16-color palette (0-7).
+      #
+      # @return [Integer] Color index (0-7)
+      def rgb_to_palette16
+        # Standard ANSI colors
+        colors = [
+          [0, 0, 0],       # 0: black
+          [255, 0, 0],     # 1: red
+          [0, 255, 0],     # 2: green
+          [255, 255, 0],   # 3: yellow
+          [0, 0, 255],     # 4: blue
+          [255, 0, 255],   # 5: magenta
+          [0, 255, 255],   # 6: cyan
+          [255, 255, 255], # 7: white
+        ]
+
+        r = @red.value
+        g = @green.value
+        b = @blue.value
+
+        min_distance = Float::INFINITY
+        nearest_index = 0
+
+        colors.each_with_index do |color, index|
+          cr, cg, cb = color
+          distance = ((r - cr)**2 + (g - cg)**2 + (b - cb)**2)
+          if distance < min_distance
+            min_distance = distance
+            nearest_index = index
+          end
+        end
+
+        nearest_index
+      end
+
+      public
+
+      # Pretty print support with colored swatch in class name.
+      #
+      # Outputs standard Ruby object format with a colored block character
+      # embedded in the class name area.
+      #
+      # @param pp [PrettyPrint] The pretty printer instance
+      #
+      # @example
+      #   rgb = RGB.new(red: 255, green: 87, blue: 51)
+      #   pp rgb
+      #   # Outputs: #<Unmagic::Color::RGB[█] @red=255 @green=87 @blue=51>
+      #   # (with colored █ block)
+      def pretty_print(pp)
+        pp.text("#<#{self.class.name}[\x1b[#{to_ansi(mode: :truecolor)}m█\x1b[0m] @red=#{@red.value} @green=#{@green.value} @blue=#{@blue.value}>")
+      end
     end
   end
 end

data/lib/unmagic/color/units/degrees.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    # Unit types for color manipulation.
+    module Units
+      # Represents an angle in degrees (0-360°).
+      #
+      # Supports numeric values, degree strings, and named direction keywords.
+      # Values are automatically wrapped to the 0-360 range.
+      #
+      # ## Supported Formats
+      #
+      # - Numeric: `225`, `45.5`
+      # - Degree strings: `"225deg"`, `"45.5deg"`, `"-45deg"`, `"225°"`, `"45.5°"`
+      # - Named directions: `"top"`, `"bottom left"`, `"north"`, `"southwest"`, etc.
+      #
+      # ## Named Direction Keywords
+      #
+      # - Cardinal: `"top"` (0°), `"right"` (90°), `"bottom"` (180°), `"left"` (270°)
+      # - Diagonal: `"top right"` (45°), `"bottom right"` (135°), `"bottom left"` (225°), `"top left"` (315°)
+      # - Aliases: `"north"`, `"south"`, `"east"`, `"west"`, `"northeast"`, etc.
+      #
+      # @example Numeric values
+      #   Degrees.build(225)           #=> 225.0°
+      #   Degrees.build(45.5)          #=> 45.5°
+      #   Degrees.build(-45)           #=> 315.0° (wrapped)
+      #
+      # @example Degree strings
+      #   Degrees.build("225deg")      #=> 225.0°
+      #   Degrees.build("45.5deg")     #=> 45.5°
+      #   Degrees.build("225°")        #=> 225.0°
+      #
+      # @example Named directions
+      #   Degrees.build("top")         #=> 0.0°
+      #   Degrees.build("bottom left") #=> 225.0°
+      #   Degrees.build("north")       #=> 0.0° (alias for "top")
+      #
+      # @example Constants
+      #   Degrees::TOP                 #=> 0.0°
+      #   Degrees::BOTTOM_LEFT         #=> 225.0°
+      #
+      # @example String output
+      #   Degrees::TOP.to_s            #=> "top"
+      #   Degrees::TOP.to_css          #=> "0.0deg"
+      #   Degrees.new(value: 123).to_s #=> "123.0°"
+      class Degrees
+        include Comparable
+
+        # Error raised when parsing invalid degree values.
+        class ParseError < Color::Error; end
+
+        attr_reader :value, :name, :aliases
+
+        class << self
+          # All predefined degree constants
+          #
+          # @return [Array<Degrees>] All constant degree values
+          def all
+            all_by_name.values.uniq
+          end
+
+          # Find a constant by name or alias
+          #
+          # @param search [String] Name or alias to search for
+          # @return [Degrees, nil] Matching constant or nil
+          def find_by_name(search)
+            normalized = search.strip.downcase
+            all_by_name.fetch(normalized)
+          rescue KeyError
+            nil
+          end
+
+          private
+
+          # Hash mapping all names and aliases to their constants
+          #
+          # @return [Hash<String, Degrees>] Name/alias to constant mapping
+          def all_by_name
+            @all_by_name ||= begin
+              constants = [TOP, RIGHT, BOTTOM, LEFT, TOP_RIGHT, BOTTOM_RIGHT, BOTTOM_LEFT, TOP_LEFT]
+              hash = {}
+              constants.each do |constant|
+                hash[constant.name] = constant
+                constant.aliases.each { |alias_name| hash[alias_name] = constant }
+              end
+              hash
+            end
+          end
+
+          public
+
+          # Build a Degrees instance from various input formats.
+          #
+          # @param input [Numeric, String, Degrees] The angle to parse
+          # @return [Degrees] Normalized degrees instance
+          # @raise [ParseError] If input format is invalid
+          #
+          # @example From number
+          #   Degrees.build(225)
+          #
+          # @example From degree string
+          #   Degrees.build("225deg")
+          #
+          # @example From CSS direction
+          #   Degrees.build("to left top")
+          def build(input)
+            case input
+            when Degrees
+              input
+            when ::Numeric
+              new(value: input)
+            when ::String
+              parse(input)
+            else
+              raise ParseError, "Expected Numeric, String, or Degrees, got #{input.class}"
+            end
+          end
+
+          # Parse a degrees string.
+          #
+          # @param input [String] The string to parse
+          # @return [Degrees] Parsed degrees instance
+          # @raise [ParseError] If format is invalid
+          def parse(input)
+            raise ParseError, "Input must be a string" unless input.is_a?(::String)
+
+            input = input.strip
+
+            # Try to find a named constant first
+            constant = find_by_name(input)
+            return constant if constant
+
+            # Remove "deg" or "°" suffix if present
+            input = input.sub(/deg\z/i, "").sub(/°\z/, "")
+
+            # Try parsing as number
+            if input.match?(/\A-?\d+(?:\.\d+)?\z/)
+              return new(value: input.to_f)
+            end
+
+            raise ParseError, "Invalid degrees format: #{input.inspect}"
+          end
+        end
+
+        # Create a new Degrees instance.
+        #
+        # @param value [Numeric] Angle in degrees (wraps to 0-360 range)
+        # @param name [String, nil] Optional name for this degree (e.g., "top", "bottom")
+        # @param aliases [Array<String>] Optional aliases for this degree (e.g., ["north"])
+        def initialize(value:, name: nil, aliases: [])
+          @value = value.to_f % 360
+          @name = name
+          @aliases = aliases
+        end
+
+        # Convert to float value.
+        #
+        # @return [Float] Degrees value (0-360)
+        def to_f
+          @value
+        end
+
+        # Get the opposite direction (180 degrees away).
+        #
+        # @return [Degrees] Opposite degree
+        def opposite
+          opposite_value = (@value + 180) % 360
+          self.class.all.find { |d| d.value == opposite_value } || self.class.new(value: opposite_value)
+        end
+
+        # Convert to CSS string format.
+        #
+        # @return [String] CSS degree string (e.g., "225.0deg")
+        def to_css
+          "#{@value}deg"
+        end
+
+        # Convert to string representation.
+        #
+        # @return [String] Canonical string format that can be parsed back
+        def to_s
+          @name || "#{@value}°"
+        end
+
+        # Compare two Degrees instances.
+        #
+        # @param other [Degrees, Numeric] Value to compare
+        # @return [Integer, nil] Comparison result
+        def <=>(other)
+          case other
+          when Degrees
+            @value <=> other.value
+          when ::Numeric
+            @value <=> other.to_f
+          end
+        end
+
+        # Check equality.
+        #
+        # @param other [Object] Value to compare
+        # @return [Boolean] true if values are equal
+        def ==(other)
+          case other
+          when Degrees
+            @value == other.value
+          when ::Numeric
+            @value == other.to_f
+          else
+            false
+          end
+        end
+
+        # Predefined degree constants
+        TOP = new(value: 0, name: "top", aliases: ["north"]).freeze
+        # Right direction (90°, east)
+        RIGHT = new(value: 90, name: "right", aliases: ["east"]).freeze
+        # Bottom direction (180°, south)
+        BOTTOM = new(value: 180, name: "bottom", aliases: ["south"]).freeze
+        # Left direction (270°, west)
+        LEFT = new(value: 270, name: "left", aliases: ["west"]).freeze
+        # Top-right diagonal direction (45°, northeast)
+        TOP_RIGHT = new(value: 45, name: "top right", aliases: ["topright", "northeast", "north east"]).freeze
+        # Bottom-right diagonal direction (135°, southeast)
+        BOTTOM_RIGHT = new(value: 135, name: "bottom right", aliases: ["bottomright", "southeast", "south east"]).freeze
+        # Bottom-left diagonal direction (225°, southwest)
+        BOTTOM_LEFT = new(value: 225, name: "bottom left", aliases: ["bottomleft", "southwest", "south west"]).freeze
+        # Top-left diagonal direction (315°, northwest)
+        TOP_LEFT = new(value: 315, name: "top left", aliases: ["topleft", "northwest", "north west"]).freeze
+      end
+    end
+  end
+end