unmagic-color 0.1.0 → 0.2.1

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

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require_relative "degrees"
+
+module Unmagic
+  class Color
+    module Units
+      class Degrees
+        # Represents a gradient direction as a from/to tuple of Degrees.
+        #
+        # Direction defines a gradient's angle by specifying where it starts (from)
+        # and where it ends (to). Supports CSS-style direction strings with flexible
+        # parsing that infers missing components.
+        #
+        # ## Supported Formats
+        #
+        # - Full directions: `"from left to right"`, `"from bottom left to top right"`
+        # - Implicit from: `"to top"` → infers `"from bottom to top"`
+        # - Implicit to: `"from bottom"` → infers `"from bottom to top"`
+        # - Without "from": `"left to right"` → `"from left to right"`
+        # - Mixed formats: `"from 45deg to top right"`, `"from south to 90deg"`, `"from 45° to 90°"`
+        # - Hash: `{ from: "north", to: "south" }`
+        #
+        # @example Parse direction strings
+        #   Direction.parse("from left to right")
+        #   Direction.parse("to top")                    # Infers from bottom
+        #   Direction.parse("from bottom")               # Infers to top
+        #   Direction.parse("left to right")             # Implicit "from"
+        #   Direction.parse("from 45deg to 90deg")       # Numeric degrees
+        #   Direction.parse("from 45° to 90°")           # With ° symbol
+        #   Direction.parse("from south to top right")   # Mixed
+        #
+        # @example Build from various inputs
+        #   Direction.build("from left to right")
+        #   Direction.build(from: "north", to: "south")
+        #   Direction.build(from: 45, to: 90)
+        #
+        # @example Direct construction
+        #   direction = Direction.new(from: Degrees::LEFT, to: Degrees::RIGHT)
+        #   direction.from.value  #=> 270.0
+        #   direction.to.value    #=> 90.0
+        #
+        # @example Constants
+        #   Direction::LEFT_TO_RIGHT
+        #   Direction::BOTTOM_LEFT_TO_TOP_RIGHT
+        #
+        # @example String output
+        #   Direction::LEFT_TO_RIGHT.to_s    #=> "from left to right"
+        #   Direction::LEFT_TO_RIGHT.to_css  #=> "from left to right"
+        class Direction
+          attr_reader :from, :to
+
+          class << self
+            # All predefined direction constants
+            #
+            # @return [Array<Direction>] All constant directions
+            def all
+              all_constants
+            end
+
+            private
+
+            # Array of all predefined direction constants
+            #
+            # @return [Array<Direction>] All constant directions
+            def all_constants
+              @all_constants ||= [
+                BOTTOM_TO_TOP,
+                LEFT_TO_RIGHT,
+                TOP_TO_BOTTOM,
+                RIGHT_TO_LEFT,
+                BOTTOM_LEFT_TO_TOP_RIGHT,
+                TOP_LEFT_TO_BOTTOM_RIGHT,
+                TOP_RIGHT_TO_BOTTOM_LEFT,
+                BOTTOM_RIGHT_TO_TOP_LEFT,
+              ]
+            end
+
+            public
+
+            # Check if a string looks like a direction keyword.
+            #
+            # @param input [String] The string to check
+            # @return [Boolean] true if the string appears to be a direction keyword
+            def matches?(input)
+              return false unless input.is_a?(::String)
+
+              normalized = input.strip.downcase
+
+              # Check if it contains "from" or "to" keywords
+              normalized.start_with?("to ") || normalized.start_with?("from ") || normalized.include?(" to ")
+            end
+
+            # Build a Direction from various input formats.
+            #
+            # @param input [String, Direction, Hash] Direction string, instance, or hash with :from and :to keys
+            # @return [Direction] Direction instance
+            def build(input)
+              return input if input.is_a?(Direction)
+
+              if input.is_a?(::Hash)
+                raise Degrees::ParseError, "Hash must have :from and :to keys" unless input.key?(:from) && input.key?(:to)
+
+                from_degree = Degrees.build(input[:from])
+                to_degree = Degrees.build(input[:to])
+                return new(from: from_degree, to: to_degree)
+              end
+
+              parse(input)
+            end
+
+            # Parse a direction string into a Direction instance.
+            #
+            # Supports mixed formats like:
+            # - "from 275deg to 45deg"
+            # - "from south to 90"
+            # - "from north to top right"
+            # - "to top" (infers from as opposite)
+            # - "from bottom" (infers to as opposite)
+            #
+            # @param input [String] Direction string
+            # @return [Direction] Parsed direction
+            # @raise [Degrees::ParseError] If direction is invalid
+            def parse(input)
+              # Normalize: strip, downcase, and collapse whitespace
+              normalized = input.strip.downcase.gsub(/\s+/, " ")
+
+              # Remove "from " prefix if present, then split on "to "
+              parts = normalized.delete_prefix("from ").split("to ", 2).map(&:strip)
+              left = parts[0]
+              right = parts[1]
+
+              if left.empty? && right
+                # Only right side specified: "to top"
+                to_degree = Degrees.build(right)
+                from_degree = to_degree.opposite
+              elsif right.nil?
+                # Only left side specified: "from bottom"
+                from_degree = Degrees.build(left)
+                to_degree = from_degree.opposite
+              else
+                # Both sides specified: "left to right" or "from left to right"
+                from_degree = Degrees.build(left)
+                to_degree = Degrees.build(right)
+              end
+
+              new(from: from_degree, to: to_degree)
+            end
+          end
+
+          # Create a new Direction instance.
+          #
+          # @param from [Degrees] Starting degree
+          # @param to [Degrees] Ending degree
+          def initialize(from:, to:)
+            @from = from
+            @to = to
+          end
+
+          # Convert to CSS string format.
+          #
+          # @return [String] CSS direction string (e.g., "from left to right")
+          def to_css
+            from_str = @from.name || @from.to_css
+            to_str = @to.name || @to.to_css
+            "from #{from_str} to #{to_str}"
+          end
+
+          # Convert to string representation.
+          #
+          # @return [String] Canonical string format that can be parsed back
+          def to_s
+            from_str = @from.name || @from.to_s
+            to_str = @to.name || @to.to_s
+            "from #{from_str} to #{to_str}"
+          end
+
+          # Check equality.
+          #
+          # @param other [Object] Value to compare
+          # @return [Boolean] true if from and to are equal
+          def ==(other)
+            other.is_a?(Direction) && @from == other.from && @to == other.to
+          end
+
+          # Predefined direction constants
+          BOTTOM_TO_TOP = new(from: Degrees::BOTTOM, to: Degrees::TOP).freeze
+          # Left to right direction (horizontal)
+          LEFT_TO_RIGHT = new(from: Degrees::LEFT, to: Degrees::RIGHT).freeze
+          # Top to bottom direction (vertical, default)
+          TOP_TO_BOTTOM = new(from: Degrees::TOP, to: Degrees::BOTTOM).freeze
+          # Right to left direction (horizontal)
+          RIGHT_TO_LEFT = new(from: Degrees::RIGHT, to: Degrees::LEFT).freeze
+          # Bottom-left to top-right diagonal direction
+          BOTTOM_LEFT_TO_TOP_RIGHT = new(from: Degrees::BOTTOM_LEFT, to: Degrees::TOP_RIGHT).freeze
+          # Top-left to bottom-right diagonal direction
+          TOP_LEFT_TO_BOTTOM_RIGHT = new(from: Degrees::TOP_LEFT, to: Degrees::BOTTOM_RIGHT).freeze
+          # Top-right to bottom-left diagonal direction
+          TOP_RIGHT_TO_BOTTOM_LEFT = new(from: Degrees::TOP_RIGHT, to: Degrees::BOTTOM_LEFT).freeze
+          # Bottom-right to top-left diagonal direction
+          BOTTOM_RIGHT_TO_TOP_LEFT = new(from: Degrees::BOTTOM_RIGHT, to: Degrees::TOP_LEFT).freeze
+        end
+      end
+    end
+  end
+end

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

@@ -7,19 +7,19 @@ module Unmagic
     # Handles both direct percentage values and ratio calculations.
     #
     # @example Direct percentage value
-    #   percentage = Percentage.new(75.5)
+    #   percentage = Percentage.build(75.5)
     #   percentage.to_s
     #   #=> "75.5%"
     #   percentage.value
     #   #=> 75.5
     #
     # @example Calculated from ratio
-    #   percentage = Percentage.new(50, 100)
+    #   percentage = Percentage.build(50, 100)
     #   percentage.to_s
     #   #=> "50.0%"
     #
     # @example Progress tracking
-    #   percentage = Percentage.new(current_item, total_items)
+    #   percentage = Percentage.build(current_item, total_items)
     #   percentage.to_s
     #   #=> "25.0%"
     class Percentage
@@ -29,24 +29,130 @@ module Unmagic
 
       # 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
+      # @param value [Numeric] The percentage value (0-100)
+      def initialize(value:)
+        @value = value.to_f.clamp(0.0, 100.0)
+      end
+
+      class << self
+        # Build a percentage from various input types.
+        #
+        # Handles both single value and numerator/denominator ratio inputs.
+        #
+        # @param args [Array<Numeric>] Either a single percentage value (0-100) or numerator and denominator
+        # @option kwargs [Numeric] :value The percentage value (0-100)
+        # @return [Percentage, nil] The created percentage or nil if passed nil
+        #
+        # @example Single value
+        #   Percentage.build(75.5)
+        #   #=> Percentage with value 75.5
+        #
+        # @example Ratio
+        #   Percentage.build(50, 100)
+        #   #=> Percentage with value 50.0
+        #
+        # @example Keyword argument
+        #   Percentage.build(value: 75.5)
+        #   #=> Percentage with value 75.5
+        #
+        # @example Pass through existing instance
+        #   existing = Percentage.new(value: 50)
+        #   Percentage.build(existing)
+        #   #=> Returns the same instance
+        def build(*args, **kwargs)
+          return new(**kwargs) if kwargs.any?
+
+          case args.length
+          when 1
+            input = args[0]
+            return if input.nil?
+            return input if input.is_a?(self)
+
+            # Handle strings by parsing
+            return parse(input) if input.is_a?(::String)
+
+            # Handle Rational
+            if input.is_a?(Rational)
+              return new(value: input.to_f * 100)
+            end
+
+            # Handle numeric values
+            # If value is <= 1.0, treat as ratio (multiply by 100)
+            # If value is > 1.0, treat as literal percentage value
+            value = input.to_f
+            if value <= 1.0
+              new(value: value * 100)
+            else
+              new(value: value)
+            end
+          when 2
+            numerator, denominator = args
+            value = if denominator.to_f.zero?
+              0.0
+            else
+              (numerator.to_f / denominator.to_f * 100.0)
+            end
+            new(value: value)
           else
-            (numerator.to_f / denominator.to_f * 100.0)
+            raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 1..2)"
           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)
+        # Parse a percentage from string format.
+        #
+        # Handles multiple formats:
+        # - Explicit percentage: "50%" → 50.0
+        # - Fraction notation: "10/100" → 10.0
+        # - Bare decimal ≤ 1.0: "0.5" → 50.0 (treated as ratio)
+        # - Bare decimal > 1.0: "75" → 75.0 (treated as literal percentage)
+        #
+        # @param input [String] The string to parse
+        # @return [Percentage] The parsed percentage
+        # @raise [ArgumentError] If input is not a string or format is invalid
+        #
+        # @example Parse explicit percentage
+        #   Percentage.parse("23.5%")
+        #   #=> Percentage with value 23.5
+        #
+        # @example Parse ratio
+        #   Percentage.parse("0.5")
+        #   #=> Percentage with value 50.0
+        #
+        # @example Parse fraction
+        #   Percentage.parse("1/4")
+        #   #=> Percentage with value 25.0
+        def parse(input)
+          raise ArgumentError, "Input must be a string" unless input.is_a?(::String)
+
+          input = input.strip
+
+          # Handle explicit percentage format
+          if input.end_with?("%")
+            value = input.chomp("%").to_f
+            return new(value: value)
+          end
+
+          # Handle fraction notation
+          if input.include?("/")
+            parts = input.split("/").map(&:strip)
+            raise ArgumentError, "Invalid fraction format" unless parts.length == 2
+
+            numerator = parts[0].to_f
+            denominator = parts[1].to_f
+            return build(numerator, denominator)
+          end
+
+          # Handle bare numeric values
+          value = input.to_f
+
+          # If value is <= 1.0, treat as ratio (multiply by 100)
+          # If value is > 1.0, treat as literal percentage value
+          if value <= 1.0
+            new(value: value * 100)
+          else
+            new(value: value)
+          end
+        end
       end
 
       # Format as percentage string with configurable decimal places
@@ -102,9 +208,9 @@ module Unmagic
       def +(other)
         case other
         when Percentage
-          Percentage.new([value + other.value, 100.0].min)
+          Percentage.new(value: [value + other.value, 100.0].min)
         when Numeric
-          Percentage.new([value + other.to_f, 100.0].min)
+          Percentage.new(value: [value + other.to_f, 100.0].min)
         else
           raise TypeError, "can't add #{other.class} to Percentage"
         end
@@ -117,9 +223,9 @@ module Unmagic
       def -(other)
         case other
         when Percentage
-          Percentage.new([value - other.value, 0.0].max)
+          Percentage.new(value: [value - other.value, 0.0].max)
         when Numeric
-          Percentage.new([value - other.to_f, 0.0].max)
+          Percentage.new(value: [value - other.to_f, 0.0].max)
         else
           raise TypeError, "can't subtract #{other.class} from Percentage"
         end
@@ -129,7 +235,7 @@ module Unmagic
       #
       # @return [Percentage] New percentage with absolute value
       def abs
-        self.class.new(@value.abs)
+        self.class.new(value: @value.abs)
       end
 
       # Check if percentage is zero
@@ -138,6 +244,28 @@ module Unmagic
       def zero?
         @value.zero?
       end
+
+      # Pretty print format for debugging
+      #
+      # @param pp [PP] The pretty printer
+      # @return [void]
+      def pretty_print(pp)
+        pp.group(1, "#<#{self.class}(", ")>") do
+          pp.text("\"#{self}\"")
+        end
+      end
+    end
+
+    # Constructor-style method for creating Percentage instances
+    #
+    # Handles both string parsing and numeric building.
+    #
+    # @param args [Array] Arguments to pass to Percentage.build
+    # @option kwargs [Numeric] :value The percentage value (0-100)
+    # @return [Percentage, nil] The created percentage
+    def Percentage(*args, **kwargs) # rubocop:disable Naming/MethodName
+      Percentage.build(*args, **kwargs)
     end
+    module_function :Percentage
   end
 end

data/lib/unmagic/color/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    # Current version of the Unmagic::Color gem
+    VERSION = "0.2.1"
+  end
+end

data/lib/unmagic/color.rb

@@ -37,18 +37,38 @@ module Unmagic
   #     darker = color.darken(0.1)
   #     mixed = color.blend(other_color, 0.5)
   class Color
+    # Base error class for color-related errors.
     # @private
     class Error < StandardError; end
+
+    # Error raised when a color string cannot be parsed.
     # @private
     class ParseError < Error; end
 
+    # Path to the data directory containing color databases.
+    # @api private
+    DATA_PATH = File.join(__dir__, "..", "..", "data")
+
+    require_relative "color/version"
     require_relative "color/rgb"
     require_relative "color/rgb/hex"
     require_relative "color/rgb/named"
+    require_relative "color/rgb/ansi"
     require_relative "color/hsl"
     require_relative "color/oklch"
     require_relative "color/string/hash_function"
     require_relative "color/util/percentage"
+    require_relative "color/units/degrees"
+    require_relative "color/gradient"
+    require_relative "color/gradient/stop"
+    require_relative "color/gradient/bitmap"
+    require_relative "color/gradient/base"
+    require_relative "color/rgb/gradient/linear"
+    require_relative "color/hsl/gradient/linear"
+    require_relative "color/oklch/gradient/linear"
+    require_relative "color/harmony"
+
+    include Harmony
 
     class << self
       # Parse a color string into the appropriate color space object.
@@ -92,6 +112,8 @@ module Unmagic
           HSL.parse(input)
         elsif input.start_with?("oklch")
           OKLCH.parse(input)
+        elsif input.match?(/\A\d+(?:;\d+)*\z/) && RGB::ANSI.valid?(input)
+          RGB::ANSI.parse(input)
         elsif RGB::Named.valid?(input)
           RGB::Named.parse(input)
         else
@@ -124,7 +146,10 @@ module Unmagic
         super(value: value.to_i.clamp(0, 255))
       end
 
+      # @return [Integer] Component value as integer
       def to_i = value
+
+      # @return [Float] Component value as float
       def to_f = value.to_f
 
       # @param other [Component, Numeric] Value to compare
@@ -182,7 +207,10 @@ module Unmagic
         super(value: value.to_f % 360)
       end
 
+      # @return [Float] Hue value as float
       def to_f = value
+
+      # @return [Float] Hue value in degrees
       def degrees = value
 
       # @param other [Hue, Numeric] Value to compare
@@ -281,6 +309,53 @@ module Unmagic
     # Lightness percentage (0-100%)
     class Lightness < Unmagic::Util::Percentage; end
 
+    # Alpha channel for transparency. Stored internally as percentage (0-100%)
+    # where 100% is fully opaque and 0% is fully transparent. Use to_css to
+    # output as ratio (0.0-1.0) for CSS formats.
+    #
+    # Inherits parse method from Percentage which handles:
+    # - Explicit percentage: "50%" → Alpha with value 50.0
+    # - Fraction notation: "1/2" → Alpha with value 50.0
+    # - Bare decimal ≤ 1.0: "0.5" → Alpha with value 50.0 (treated as CSS ratio)
+    # - Bare decimal > 1.0: "75" → Alpha with value 75.0
+    #
+    # @example Parse CSS ratio
+    #   alpha = Unmagic::Color::Alpha.parse("0.5")
+    #   alpha.value
+    #   #=> 50.0
+    #
+    # @example Parse percentage
+    #   alpha = Unmagic::Color::Alpha.parse("50%")
+    #   alpha.value
+    #   #=> 50.0
+    class Alpha < Unmagic::Util::Percentage
+      # Default alpha value (fully opaque)
+      DEFAULT = new(value: 100).freeze
+
+      # Convert to CSS output format (as ratio 0.0-1.0, not percentage).
+      #
+      # Returns "1" for fully opaque, "0" for fully transparent, and decimal
+      # values for semi-transparent colors (e.g., "0.5", "0.75").
+      #
+      # @return [String] The alpha value as a CSS ratio string
+      #
+      # @example Fully opaque
+      #   Unmagic::Color::Alpha.new(value: 100).to_css
+      #   #=> "1"
+      #
+      # @example Semi-transparent
+      #   Unmagic::Color::Alpha.new(value: 50).to_css
+      #   #=> "0.5"
+      #
+      # @example Fully transparent
+      #   Unmagic::Color::Alpha.new(value: 0).to_css
+      #   #=> "0"
+      def to_css
+        ratio = to_ratio
+        ratio == 1.0 ? "1" : ratio.to_s.sub(/\.?0+$/, "")
+      end
+    end
+
     # Convert this color to RGB color space.
     #
     # RGB represents colors as a combination of Red, Green, and Blue light,
@@ -311,6 +386,26 @@ module Unmagic
       raise NotImplementedError
     end
 
+    # Convert this color to an ANSI SGR color code.
+    #
+    # Returns an ANSI Select Graphic Rendition (SGR) parameter string that can be used
+    # in terminal output. The returned string does not include the escape sequence prefix
+    # (\x1b[) or the trailing 'm'.
+    #
+    # @param layer [Symbol] Whether to generate foreground (:foreground) or background (:background) code
+    # @return [String] ANSI SGR code like "31" or "38;2;255;0;0"
+    #
+    # @example Output red text
+    #   color = Unmagic::Color.parse("red")
+    #   puts "\x1b[#{color.to_ansi}mHello\x1b[0m"
+    #
+    # @example Set background color
+    #   color = Unmagic::Color.parse("#336699")
+    #   puts "\x1b[#{color.to_ansi(layer: :background)}mText\x1b[0m"
+    def to_ansi(layer: :foreground)
+      raise NotImplementedError
+    end
+
     # Calculate the perceptual luminance of this color.
     #
     # Luminance represents how bright the color appears to the human eye,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: unmagic-color
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Keith Pitt
@@ -17,16 +17,36 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
-- data/rgb.txt
+- data/css.jsonc
+- data/css.txt
+- data/x11.jsonc
+- data/x11.txt
 - lib/unmagic/color.rb
+- lib/unmagic/color/console/banner.rb
+- lib/unmagic/color/console/card.rb
+- lib/unmagic/color/console/help.rb
+- lib/unmagic/color/console/highlighter.rb
+- lib/unmagic/color/gradient.rb
+- lib/unmagic/color/gradient/base.rb
+- lib/unmagic/color/gradient/bitmap.rb
+- lib/unmagic/color/gradient/stop.rb
+- lib/unmagic/color/harmony.rb
 - lib/unmagic/color/hsl.rb
+- lib/unmagic/color/hsl/gradient/linear.rb
 - lib/unmagic/color/oklch.rb
+- lib/unmagic/color/oklch/gradient/linear.rb
 - lib/unmagic/color/rgb.rb
+- lib/unmagic/color/rgb/ansi.rb
+- lib/unmagic/color/rgb/gradient/linear.rb
 - lib/unmagic/color/rgb/hex.rb
 - lib/unmagic/color/rgb/named.rb
 - lib/unmagic/color/string/hash_function.rb
+- lib/unmagic/color/units/degrees.rb
+- lib/unmagic/color/units/direction.rb
 - lib/unmagic/color/util/percentage.rb
+- lib/unmagic/color/version.rb
 - lib/unmagic_color.rb
 homepage: https://github.com/unreasonable-magic/unmagic-color
 licenses:
@@ -49,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Comprehensive color manipulation library
 test_files: []