unmagic-color 0.1.0

data/lib/unmagic/color/util/percentage.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Unmagic
+  # Utility classes for color manipulation
+  module Util
+    # Represents a percentage value with validation and formatting capabilities.
+    # Handles both direct percentage values and ratio calculations.
+    #
+    # @example Direct percentage value
+    #   percentage = Percentage.new(75.5)
+    #   percentage.to_s
+    #   #=> "75.5%"
+    #   percentage.value
+    #   #=> 75.5
+    #
+    # @example Calculated from ratio
+    #   percentage = Percentage.new(50, 100)
+    #   percentage.to_s
+    #   #=> "50.0%"
+    #
+    # @example Progress tracking
+    #   percentage = Percentage.new(current_item, total_items)
+    #   percentage.to_s
+    #   #=> "25.0%"
+    class Percentage
+      include Comparable
+
+      attr_reader :value
+
+      # Create a new percentage
+      #
+      # @param args [Array<Numeric>] Either a single percentage value (0-100) or numerator and denominator
+      def initialize(*args)
+        case args.length
+        when 1
+          @value = args[0].to_f
+        when 2
+          numerator, denominator = args
+          @value = if denominator.to_f.zero?
+            0.0
+          else
+            (numerator.to_f / denominator.to_f * 100.0)
+          end
+        else
+          raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 1..2)"
+        end
+
+        # Clamp to valid percentage range
+        @value = @value.clamp(0.0, 100.0)
+      end
+
+      # Format as percentage string with configurable decimal places
+      #
+      # @param decimal_places [Integer] Number of decimal places to display
+      # @return [String] Formatted percentage string
+      def to_s(decimal_places: 1)
+        "#{@value.round(decimal_places)}%"
+      end
+
+      # Get the raw percentage value (0.0 to 100.0)
+      def to_f
+        @value
+      end
+
+      # Get the percentage as a ratio (0.0 to 1.0)
+      def to_ratio
+        @value / 100.0
+      end
+
+      # Comparison operator for Comparable
+      #
+      # @param other [Percentage, Numeric] Value to compare with
+      # @return [Integer, nil] -1, 0, 1, or nil
+      def <=>(other)
+        case other
+        when Percentage
+          @value <=> other.value
+        when Numeric
+          @value <=> other.to_f
+        end
+      end
+
+      # Equality comparison
+      #
+      # @param other [Object] Value to compare with
+      # @return [Boolean] true if values are equal
+      def ==(other)
+        case other
+        when Percentage
+          @value == other.value
+        when Numeric
+          @value == other.to_f
+        else
+          false
+        end
+      end
+
+      # Add percentages (clamped to 100%)
+      #
+      # @param other [Percentage, Numeric] Value to add
+      # @return [Percentage] New percentage with sum of values
+      def +(other)
+        case other
+        when Percentage
+          Percentage.new([value + other.value, 100.0].min)
+        when Numeric
+          Percentage.new([value + other.to_f, 100.0].min)
+        else
+          raise TypeError, "can't add #{other.class} to Percentage"
+        end
+      end
+
+      # Subtract percentages (clamped to 0%)
+      #
+      # @param other [Percentage, Numeric] Value to subtract
+      # @return [Percentage] New percentage with difference of values
+      def -(other)
+        case other
+        when Percentage
+          Percentage.new([value - other.value, 0.0].max)
+        when Numeric
+          Percentage.new([value - other.to_f, 0.0].max)
+        else
+          raise TypeError, "can't subtract #{other.class} from Percentage"
+        end
+      end
+
+      # Absolute value
+      #
+      # @return [Percentage] New percentage with absolute value
+      def abs
+        self.class.new(@value.abs)
+      end
+
+      # Check if percentage is zero
+      #
+      # @return [Boolean] true if percentage is 0.0
+      def zero?
+        @value.zero?
+      end
+    end
+  end
+end

data/lib/unmagic/color.rb

@@ -0,0 +1,402 @@
+# frozen_string_literal: true
+
+# @private
+module Unmagic
+  # Base class for working with colors in different color spaces.
+  #
+  # ## Understanding Colors
+  #
+  # A color is simply a way to describe what we see. Just like you can describe
+  # a location using different coordinate systems (street address, latitude/longitude, etc.),
+  # you can describe colors using different "color spaces."
+  #
+  # This library supports three main color spaces:
+  #
+  # - {RGB}: Describes colors as a mix of Red, Green, and Blue light (like your screen)
+  # - {HSL}: Describes colors using Hue (color wheel position), Saturation (intensity),
+  #   and Lightness (brightness)
+  # - {OKLCH}: A modern color space that matches how humans perceive color differences
+  #
+  # ## Basic Usage
+  #
+  # Parse a color from a string:
+  #
+  #     color = Unmagic::Color.parse("#FF5733")
+  #     color = Unmagic::Color["rgb(255, 87, 51)"]
+  #     color = Unmagic::Color.parse("hsl(9, 100%, 60%)")
+  #
+  # Convert between color spaces:
+  #
+  #     rgb = Unmagic::Color.parse("#FF5733")
+  #     hsl = rgb.to_hsl
+  #     oklch = rgb.to_oklch
+  #
+  # Manipulate colors:
+  #
+  #     lighter = color.lighten(0.2)
+  #     darker = color.darken(0.1)
+  #     mixed = color.blend(other_color, 0.5)
+  class Color
+    # @private
+    class Error < StandardError; end
+    # @private
+    class ParseError < Error; end
+
+    require_relative "color/rgb"
+    require_relative "color/rgb/hex"
+    require_relative "color/rgb/named"
+    require_relative "color/hsl"
+    require_relative "color/oklch"
+    require_relative "color/string/hash_function"
+    require_relative "color/util/percentage"
+
+    class << self
+      # Parse a color string into the appropriate color space object.
+      #
+      # This method automatically detects the format and returns the correct color type.
+      # Supported formats include hex colors, RGB, HSL, OKLCH, and named colors.
+      #
+      # @param input [String, Color] The color string to parse, or an existing Color object
+      # @return [RGB, HSL, OKLCH] A color object in the appropriate color space
+      # @raise [ParseError] If the input is nil, empty, or in an unrecognized format
+      #
+      # @example Parse a hex color
+      #   Unmagic::Color.parse("#FF5733")
+      #
+      # @example Parse an RGB color
+      #   Unmagic::Color.parse("rgb(255, 87, 51)")
+      #
+      # @example Parse an HSL color
+      #   Unmagic::Color.parse("hsl(9, 100%, 60%)")
+      #
+      # @example Parse an OKLCH color
+      #   Unmagic::Color.parse("oklch(0.65 0.15 30)")
+      #
+      # @example Parse a named color
+      #   Unmagic::Color.parse("goldenrod")
+      #
+      # @example Pass through an existing color
+      #   color = Unmagic::Color.parse("#FF5733")
+      #   Unmagic::Color.parse(color)
+      def parse(input)
+        return input if input.is_a?(self)
+        raise ParseError, "Can't pass nil as a color" if input.nil?
+
+        input = input.strip
+        raise ParseError, "Can't parse empty string" if input == ""
+
+        # Try hex or RGB format
+        if input.start_with?("#") || input.match?(/\A[0-9A-Fa-f]{3,6}\z/) || input.start_with?("rgb")
+          RGB.parse(input)
+        elsif input.start_with?("hsl")
+          HSL.parse(input)
+        elsif input.start_with?("oklch")
+          OKLCH.parse(input)
+        elsif RGB::Named.valid?(input)
+          RGB::Named.parse(input)
+        else
+          raise ParseError, "Unknown color #{input.inspect}"
+        end
+      end
+
+      # Parse a color string using bracket notation.
+      #
+      # This is a convenient alias for {parse}.
+      #
+      # @param value [String, Color] The color string to parse
+      # @return [RGB, HSL, OKLCH] A color object in the appropriate color space
+      # @raise [ParseError] If the input is invalid
+      #
+      # @example
+      #   Unmagic::Color["#FF5733"]
+      #   Unmagic::Color["hsl(9, 100%, 60%)"]
+      def [](value)
+        parse(value)
+      end
+    end
+
+    # Base unit for RGB components (0-255)
+    Component = Data.define(:value) do
+      include Comparable
+
+      # @param value [Numeric] Component value (0-255)
+      def initialize(value:)
+        super(value: value.to_i.clamp(0, 255))
+      end
+
+      def to_i = value
+      def to_f = value.to_f
+
+      # @param other [Component, Numeric] Value to compare
+      # @return [Integer, nil] Comparison result
+      def <=>(other)
+        case other
+        when Component, Numeric
+          value <=> other.to_f
+        end
+      end
+
+      # @param other [Numeric] Multiplier
+      # @return [Component] New component
+      def *(other)
+        self.class.new(value: value * other.to_f)
+      end
+
+      # @param other [Numeric] Divisor
+      # @return [Component] New component
+      def /(other)
+        self.class.new(value: value / other.to_f)
+      end
+
+      # @param other [Numeric] Value to add
+      # @return [Component] New component
+      def +(other)
+        self.class.new(value: value + other.to_f)
+      end
+
+      # @param other [Numeric] Value to subtract
+      # @return [Component] New component
+      def -(other)
+        self.class.new(value: value - other.to_f)
+      end
+
+      # @return [Component] Absolute value
+      def abs
+        self.class.new(value: value.abs)
+      end
+    end
+
+    # Type alias for red component
+    Red = Component
+    # Type alias for green component
+    Green = Component
+    # Type alias for blue component
+    Blue = Component
+
+    # Angular unit for hue (0-360 degrees, wrapping)
+    Hue = Data.define(:value) do
+      include Comparable
+
+      # @param value [Numeric] Hue value in degrees
+      def initialize(value:)
+        super(value: value.to_f % 360)
+      end
+
+      def to_f = value
+      def degrees = value
+
+      # @param other [Hue, Numeric] Value to compare
+      # @return [Integer, nil] Comparison result
+      def <=>(other)
+        case other
+        when Hue, Numeric
+          value <=> other.to_f
+        end
+      end
+
+      # @param other [Numeric] Multiplier
+      # @return [Hue] New hue
+      def *(other)
+        self.class.new(value: value * other.to_f)
+      end
+
+      # @param other [Numeric] Divisor
+      # @return [Hue] New hue
+      def /(other)
+        self.class.new(value: value / other.to_f)
+      end
+
+      # @param other [Numeric] Value to add
+      # @return [Hue] New hue
+      def +(other)
+        self.class.new(value: value + other.to_f)
+      end
+
+      # @param other [Numeric] Value to subtract
+      # @return [Hue] New hue
+      def -(other)
+        self.class.new(value: value - other.to_f)
+      end
+
+      # @return [Hue] Absolute value
+      def abs
+        self.class.new(value: value.abs)
+      end
+    end
+
+    # OKLCH chroma unit (0-0.5)
+    Chroma = Data.define(:value) do
+      include Comparable
+
+      # @param value [Numeric] Chroma value (0-0.5)
+      def initialize(value:)
+        super(value: value.to_f.clamp(0, 0.5))
+      end
+
+      # @return [Float] Chroma value
+      def to_f = value
+
+      # @param other [Chroma, Numeric] Value to compare
+      # @return [Integer, nil] Comparison result
+      def <=>(other)
+        case other
+        when Chroma, Numeric
+          value <=> other.to_f
+        end
+      end
+
+      # @param other [Numeric] Multiplier
+      # @return [Chroma] New chroma
+      def *(other)
+        self.class.new(value: value * other.to_f)
+      end
+
+      # @param other [Numeric] Divisor
+      # @return [Chroma] New chroma
+      def /(other)
+        self.class.new(value: value / other.to_f)
+      end
+
+      # @param other [Numeric] Value to add
+      # @return [Chroma] New chroma
+      def +(other)
+        self.class.new(value: value + other.to_f)
+      end
+
+      # @param other [Numeric] Value to subtract
+      # @return [Chroma] New chroma
+      def -(other)
+        self.class.new(value: value - other.to_f)
+      end
+
+      # @return [Chroma] Absolute value
+      def abs
+        self.class.new(value: value.abs)
+      end
+    end
+
+    # Percentage-based units
+    # Saturation percentage (0-100%)
+    class Saturation < Unmagic::Util::Percentage; end
+    # Lightness percentage (0-100%)
+    class Lightness < Unmagic::Util::Percentage; end
+
+    # Convert this color to RGB color space.
+    #
+    # RGB represents colors as a combination of Red, Green, and Blue light,
+    # with each component ranging from 0-255.
+    #
+    # @return [RGB] The color in RGB color space
+    def to_rgb
+      raise NotImplementedError
+    end
+
+    # Convert this color to HSL color space.
+    #
+    # HSL represents colors using Hue (0-360°), Saturation (0-100%),
+    # and Lightness (0-100%).
+    #
+    # @return [HSL] The color in HSL color space
+    def to_hsl
+      raise NotImplementedError
+    end
+
+    # Convert this color to OKLCH color space.
+    #
+    # OKLCH is a perceptually uniform color space that better matches
+    # how humans perceive color differences.
+    #
+    # @return [OKLCH] The color in OKLCH color space
+    def to_oklch
+      raise NotImplementedError
+    end
+
+    # Calculate the perceptual luminance of this color.
+    #
+    # Luminance represents how bright the color appears to the human eye,
+    # accounting for the fact that we perceive green as brighter than red,
+    # and red as brighter than blue.
+    #
+    # @return [Float] The luminance value from 0.0 (black) to 1.0 (white)
+    def luminance
+      raise NotImplementedError
+    end
+
+    # Blend this color with another color.
+    #
+    # Creates a new color by mixing this color with another. The amount
+    # parameter controls how much of the other color to mix in.
+    #
+    # @param other [Color] The color to blend with
+    # @param amount [Float] How much of the other color to use (0.0 to 1.0)
+    # @return [Color] A new color that is a blend of the two colors
+    #
+    # @example Mix two colors equally
+    #   red = Unmagic::Color.parse("#FF0000")
+    #   blue = Unmagic::Color.parse("#0000FF")
+    #   red.blend(blue, 0.5)
+    #
+    # @example Add a hint of another color
+    #   base = Unmagic::Color.parse("#336699")
+    #   base.blend(Unmagic::Color.parse("#FF0000"), 0.1)
+    def blend(other, amount = 0.5)
+      raise NotImplementedError
+    end
+
+    # Create a lighter version of this color.
+    #
+    # Returns a new color that is lighter than the original. The exact
+    # implementation depends on the color space.
+    #
+    # @param amount [Float] How much to lighten (0.0 to 1.0)
+    # @return [Color] A new, lighter color
+    #
+    # @example Make a color 20% lighter
+    #   dark = Unmagic::Color.parse("#336699")
+    #   dark.lighten(0.2)
+    def lighten(amount = 0.1)
+      raise NotImplementedError
+    end
+
+    # Create a darker version of this color.
+    #
+    # Returns a new color that is darker than the original. The exact
+    # implementation depends on the color space.
+    #
+    # @param amount [Float] How much to darken (0.0 to 1.0)
+    # @return [Color] A new, darker color
+    #
+    # @example Make a color 10% darker
+    #   bright = Unmagic::Color.parse("#FF9966")
+    #   bright.darken(0.1)
+    def darken(amount = 0.1)
+      raise NotImplementedError
+    end
+
+    # Check if this is a light color.
+    #
+    # A color is considered light if its luminance is greater than 0.5.
+    # This is useful for determining whether to use dark or light text
+    # on a colored background.
+    #
+    # @return [Boolean] true if the color is light, false otherwise
+    #
+    # @example Choose text color based on background
+    #   bg = Unmagic::Color.parse("#FFFF00")  # Yellow
+    #   text_color = bg.light? ? "#000000" : "#FFFFFF"
+    #   # => "#000000"
+    def light?
+      luminance > 0.5
+    end
+
+    # Check if this is a dark color.
+    #
+    # A color is considered dark if its luminance is 0.5 or less.
+    # This is the opposite of {#light?}.
+    #
+    # @return [Boolean] true if the color is dark, false otherwise
+    def dark?
+      !light?
+    end
+  end
+end

data/lib/unmagic_color.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "unmagic/color"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: unmagic-color
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Keith Pitt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Parse, convert, and manipulate colors with support for RGB, Hex, HSL
+  formats, contrast calculations, and color blending
+email:
+- keith@unreasonable-magic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- data/rgb.txt
+- lib/unmagic/color.rb
+- lib/unmagic/color/hsl.rb
+- lib/unmagic/color/oklch.rb
+- lib/unmagic/color/rgb.rb
+- lib/unmagic/color/rgb/hex.rb
+- lib/unmagic/color/rgb/named.rb
+- lib/unmagic/color/string/hash_function.rb
+- lib/unmagic/color/util/percentage.rb
+- lib/unmagic_color.rb
+homepage: https://github.com/unreasonable-magic/unmagic-color
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/unreasonable-magic/unmagic-color
+  source_code_uri: https://github.com/unreasonable-magic/unmagic-color
+  changelog_uri: https://github.com/unreasonable-magic/unmagic-color/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Comprehensive color manipulation library
+test_files: []