unmagic-color 0.1.0 → 0.2.0

data/lib/unmagic/color/gradient/bitmap.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    module Gradient
+      # A 2D grid of color pixels representing a rasterized gradient.
+      #
+      # Bitmap represents the output of gradient rasterization as a grid of colors.
+      # For linear gradients, this is a single row (height=1). The 2D structure
+      # allows for future gradient types that need multiple rows.
+      #
+      # ## Pixel Storage
+      #
+      # Pixels are stored as a 2D array: `pixels[y][x] = color`
+      #
+      # - Linear gradients: `pixels = [[color1, color2, ...]]` (single row)
+      # - Multi-row gradients: `pixels = [[row1...], [row2...], ...]`
+      #
+      # ## Examples
+      #
+      #   # Create a 1D bitmap (from linear gradient)
+      #   bitmap = Unmagic::Color::Gradient::Bitmap.new(
+      #     width: 5,
+      #     height: 1,
+      #     pixels: [[red, orange, yellow, green, blue]]
+      #   )
+      #
+      #   # Access pixels
+      #   bitmap.at(0, 0)  # => red (first pixel)
+      #   bitmap.at(4, 0)  # => blue (last pixel)
+      #   bitmap[]         # => red (shortcut for first pixel)
+      #
+      #   # Convert to flat array
+      #   bitmap.to_a   # => [red, orange, yellow, green, blue]
+      class Bitmap
+        attr_reader :width, :height, :pixels
+
+        # Create a new bitmap.
+        #
+        # @param width [Integer] Number of pixels horizontally
+        # @param height [Integer] Number of pixels vertically
+        # @param pixels [Array<Array<Color>>] 2D array of colors (pixels[y][x])
+        def initialize(width:, height:, pixels:)
+          @width = width
+          @height = height
+          @pixels = pixels
+        end
+
+        # Access a pixel at the given coordinates.
+        #
+        # @param x [Integer] Horizontal position (0 to width-1)
+        # @param y [Integer] Vertical position (0 to height-1), defaults to 0
+        # @return [Color] The color at the specified position
+        def at(x, y = 0)
+          @pixels[y][x]
+        end
+
+        # Shortcut to access a pixel.
+        #
+        # When called without arguments, returns the first pixel (0, 0).
+        # When called with arguments, delegates to `at`.
+        #
+        # @param args [Array] Optional x and y coordinates
+        # @return [Color] The color at the specified position
+        #
+        # @example Get first pixel
+        #   bitmap[]  # => color at (0, 0)
+        #
+        # @example Get specific pixel
+        #   bitmap[5, 0]  # => color at (5, 0)
+        def [](*args)
+          if args.empty?
+            at(0, 0)
+          else
+            at(*args)
+          end
+        end
+
+        # Convert to a flat 1D array of colors.
+        #
+        # Flattens the 2D pixel grid into a single array, reading left-to-right,
+        # top-to-bottom.
+        #
+        # @return [Array<Color>] Flattened array of all colors
+        def to_a
+          @pixels.flatten
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/gradient/stop.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    module Gradient
+      # A color stop at a specific position in a gradient.
+      #
+      # Represents a single color at a position along a gradient. Positions are
+      # normalized from 0.0 (start) to 1.0 (end). Multiple stops define the
+      # color transitions in a gradient.
+      #
+      # ## Usage
+      #
+      # Stop objects are typically created automatically by gradient classes
+      # using the `.build()` method, but can be created directly for more control.
+      #
+      # ## Examples
+      #
+      #   # Create a stop directly
+      #   stop = Unmagic::Color::Gradient::Stop.new(
+      #     color: Unmagic::Color::RGB.parse("#FF0000"),
+      #     position: 0.5
+      #   )
+      #
+      #   # Access stop properties
+      #   stop.color      # => #<RGB...>
+      #   stop.position   # => 0.5
+      class Stop
+        attr_reader :color, :position
+
+        # Create a new color stop.
+        #
+        # @param color [Color] The color at this stop (must be a Color instance)
+        # @param position [Numeric] Position along gradient (0.0-1.0)
+        #
+        # @raise [ArgumentError] If color is not a Color instance
+        # @raise [ArgumentError] If position is not between 0.0 and 1.0
+        def initialize(color:, position:)
+          raise ArgumentError, "color must be a Color instance" unless color.is_a?(Unmagic::Color)
+          raise ArgumentError, "position must be between 0.0 and 1.0" if position < 0.0 || position > 1.0
+
+          @color = color
+          @position = position.to_f
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/gradient.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "units/direction"
+
+module Unmagic
+  class Color
+    # Gradient generation for smooth color transitions.
+    #
+    # Provides classes for creating linear color gradients in RGB, HSL, or
+    # OKLCH color spaces.
+    #
+    # ## Core Classes
+    #
+    # - {Stop} - Represents a color at a specific position
+    # - {Bitmap} - A 2D grid of colors (output from rasterization)
+    # - {Base} - Base class for gradient implementations
+    #
+    # ## Gradient Types
+    #
+    # - `RGB::Gradient::Linear` - Linear gradient in RGB space
+    # - `HSL::Gradient::Linear` - Linear gradient in HSL space
+    # - `OKLCH::Gradient::Linear` - Linear gradient in OKLCH space
+    #
+    # @example Auto-detect color space, auto-balance positions
+    #   gradient = Unmagic::Color::Gradient.linear(["#FF0000", "#0000FF"])
+    #   bitmap = gradient.rasterize(width: 10)
+    #
+    # @example Use explicit positions
+    #   gradient = Unmagic::Color::Gradient.linear([["#FF0000", 0.0], ["#0000FF", 1.0]])
+    #   bitmap = gradient.rasterize(width: 10)
+    #
+    # @example Works with HSL and OKLCH too
+    #   gradient = Unmagic::Color::Gradient.linear(["hsl(0, 100%, 50%)", "hsl(240, 100%, 50%)"])
+    #   bitmap = gradient.rasterize(width: 10)
+    #
+    # @example Three colors are evenly spaced (0.0, 0.5, 1.0)
+    #   gradient = Unmagic::Color::Gradient.linear(["#FF0000", "#00FF00", "#0000FF"])
+    #
+    # @example Rasterize at different resolutions
+    #   colors = gradient.rasterize(width: 5).pixels[0]   # 5 colors
+    #   colors = gradient.rasterize(width: 100).pixels[0] # 100 colors
+    #
+    # @example Angled gradients
+    #   gradient = Unmagic::Color::Gradient.linear(["#FF0000", "#0000FF"], direction: "45deg")
+    #   bitmap = gradient.rasterize(width: 10, height: 10)
+    #
+    # @example Direction keywords
+    #   gradient = Unmagic::Color::Gradient.linear(["#FF0000", "#0000FF"], direction: "to right")
+    #   bitmap = gradient.rasterize(width: 10, height: 1)
+    module Gradient
+      # Base error class for gradient-related errors.
+      class Error < Color::Error; end
+
+      class << self
+        # Create a linear gradient, auto-detecting color space from input.
+        #
+        # Examines the first color to determine which color space to use (RGB, HSL, or OKLCH),
+        # then delegates to the appropriate Linear gradient class.
+        #
+        # Works like CSS linear-gradient - you can mix positioned and non-positioned colors.
+        # Non-positioned colors auto-balance between their surrounding positioned neighbors.
+        #
+        # Color space detection:
+        # - Strings starting with "hsl(" use HSL color space
+        # - Strings starting with "oklch(" use OKLCH color space
+        # - All other strings (hex, rgb()) use RGB color space
+        # - Color objects use their class directly
+        #
+        # @param colors [Array] Colors or [color, position] pairs
+        # @param direction [String, Numeric, Degrees, Direction, nil] Optional gradient direction
+        #   - Direction strings: "to top", "from left to right", "45deg", "90°"
+        #   - Numeric degrees: 45, 90, 180
+        #   - Degrees/Direction instances
+        #   - Defaults to "to bottom" (180°) if omitted
+        # @return [Linear] A gradient instance in the detected color space
+        #
+        # @example Simple gradient
+        #   Gradient.linear(["#FF0000", "#0000FF"])
+        #
+        # @example With direction keyword
+        #   Gradient.linear(["#FF0000", "#0000FF"], direction: "to right")
+        #   Gradient.linear(["blue", "red"], direction: "from left to right")
+        #
+        # @example With numeric direction
+        #   Gradient.linear(["#FF0000", "#0000FF"], direction: 45)
+        #   Gradient.linear(["#FF0000", "#0000FF"], direction: "90°")
+        #
+        # @example Mixed positions (like CSS linear-gradient)
+        #   Gradient.linear(["#FF0000", ["#FFFF00", 0.3], "#00FF00", ["#0000FF", 0.9], "#FF00FF"])
+        def linear(colors, direction: nil)
+          # Convert direction to Direction instance
+          direction_instance = if direction.nil?
+            # Default to "to bottom" (CSS default)
+            Unmagic::Color::Units::Degrees::Direction::TOP_TO_BOTTOM
+          elsif direction.is_a?(Unmagic::Color::Units::Degrees::Direction)
+            direction
+          elsif direction.is_a?(Unmagic::Color::Units::Degrees)
+            # Degrees instance - convert to Direction (from opposite to this degree)
+            Unmagic::Color::Units::Degrees::Direction.new(from: direction.opposite, to: direction)
+          elsif direction.is_a?(::Numeric)
+            # Numeric - convert to Degrees, then to Direction
+            degrees = Unmagic::Color::Units::Degrees.new(value: direction)
+            Unmagic::Color::Units::Degrees::Direction.new(from: degrees.opposite, to: degrees)
+          elsif direction.is_a?(::String)
+            # String - parse as Direction or Degrees
+            if Unmagic::Color::Units::Degrees::Direction.matches?(direction)
+              Unmagic::Color::Units::Degrees::Direction.parse(direction)
+            else
+              degrees = Unmagic::Color::Units::Degrees.parse(direction)
+              Unmagic::Color::Units::Degrees::Direction.new(from: degrees.opposite, to: degrees)
+            end
+          else
+            raise Error, "Invalid direction type: #{direction.class}"
+          end
+
+          raise Error, "colors must have at least one color" if colors.empty?
+
+          # Extract first color for color space detection (handle both positioned and non-positioned)
+          first = colors.first
+          first_color_or_string = first.is_a?(::Array) ? first.first : first
+
+          # Determine color class from first color
+          color_class = if first_color_or_string.is_a?(Unmagic::Color)
+            first_color_or_string.class
+          elsif first_color_or_string.is_a?(::String)
+            if first_color_or_string.match?(/^\s*hsl\s*\(/)
+              Unmagic::Color::HSL
+            elsif first_color_or_string.match?(/^\s*oklch\s*\(/)
+              Unmagic::Color::OKLCH
+            else
+              Unmagic::Color::RGB
+            end
+          else
+            raise Error, "First color must be a Color instance or String"
+          end
+
+          # Delegate to appropriate Linear class
+          gradient_class = case color_class.name
+          when "Unmagic::Color::RGB"
+            Unmagic::Color::RGB::Gradient::Linear
+          when "Unmagic::Color::HSL"
+            Unmagic::Color::HSL::Gradient::Linear
+          when "Unmagic::Color::OKLCH"
+            Unmagic::Color::OKLCH::Gradient::Linear
+          else
+            raise Error, "Unsupported color class: #{color_class}"
+          end
+
+          gradient_class.build(colors, direction: direction_instance)
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/harmony.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    # Color harmony and variations module.
+    #
+    # Provides methods for generating harmonious color palettes based on
+    # color theory principles. All calculations are performed in HSL color space
+    # for accurate hue-based relationships.
+    #
+    # Included in the base Color class, making these methods available to
+    # RGB, HSL, and OKLCH color spaces via inheritance.
+    #
+    # ## Color Harmonies
+    #
+    # Color harmonies are combinations of colors that are aesthetically pleasing
+    # based on their positions on the color wheel:
+    #
+    # - **Complementary**: Colors opposite on the wheel (180° apart)
+    # - **Analogous**: Colors adjacent on the wheel (typically 30° apart)
+    # - **Triadic**: Three colors evenly spaced (120° apart)
+    # - **Split-complementary**: Base color plus two colors adjacent to its complement
+    # - **Tetradic**: Four colors forming a rectangle or square on the wheel
+    #
+    # ## Color Variations
+    #
+    # Create related colors by adjusting lightness or saturation:
+    #
+    # - **Shades**: Darker versions (reducing lightness)
+    # - **Tints**: Lighter versions (increasing lightness)
+    # - **Tones**: Less saturated versions (reducing saturation)
+    #
+    # @example Basic harmony usage
+    #   red = Unmagic::Color.parse("#FF0000")
+    #   red.complementary          # => #<RGB #00ffff>
+    #   red.triadic                # => [#<RGB ...>, #<RGB ...>]
+    #
+    # @example Color variations
+    #   blue = Unmagic::Color.parse("#0000FF")
+    #   blue.shades(steps: 3)      # => [darker1, darker2, darker3]
+    #   blue.tints(steps: 3)       # => [lighter1, lighter2, lighter3]
+    module Harmony
+      # Returns the complementary color (180° opposite on the color wheel).
+      #
+      # Complementary colors create high contrast and visual tension.
+      # They're effective for creating emphasis and drawing attention.
+      #
+      # @return [RGB, HSL, OKLCH] The complementary color (same type as self)
+      #
+      # @example
+      #   red = Unmagic::Color.parse("#FF0000")
+      #   red.complementary
+      #   # => #<RGB #00ffff> (cyan)
+      def complementary
+        rotate_hue(180)
+      end
+
+      # Returns two analogous colors (adjacent on the color wheel).
+      #
+      # Analogous colors create harmonious, cohesive designs. They're often
+      # found in nature and produce a calm, comfortable feel.
+      #
+      # @param angle [Numeric] Degrees of separation from the base color (default: 30)
+      # @return [Array<RGB, HSL, OKLCH>] Two colors [-angle, +angle] from the base
+      #
+      # @example Default 30° separation
+      #   red = Unmagic::Color.parse("#FF0000")
+      #   red.analogous
+      #   # => [#<RGB ...>, #<RGB ...>] (red-violet, red-orange)
+      #
+      # @example Custom 15° separation
+      #   red.analogous(angle: 15)
+      def analogous(angle: 30)
+        [rotate_hue(-angle), rotate_hue(angle)]
+      end
+
+      # Returns two triadic colors (evenly spaced 120° on the color wheel).
+      #
+      # Triadic colors offer strong visual contrast while retaining harmony.
+      # They tend to be vibrant even when using pale or unsaturated versions.
+      #
+      # @return [Array<RGB, HSL, OKLCH>] Two colors at +120° and +240°
+      #
+      # @example
+      #   red = Unmagic::Color.parse("#FF0000")
+      #   red.triadic
+      #   # => [#<RGB ...>, #<RGB ...>] (green-ish, blue-ish)
+      def triadic
+        [rotate_hue(120), rotate_hue(240)]
+      end
+
+      # Returns two split-complementary colors.
+      #
+      # Split-complementary uses the two colors adjacent to the complement,
+      # providing high contrast with less tension than pure complementary.
+      #
+      # @param angle [Numeric] Degrees from the complement (default: 30)
+      # @return [Array<RGB, HSL, OKLCH>] Two colors at (180-angle)° and (180+angle)°
+      #
+      # @example
+      #   red = Unmagic::Color.parse("#FF0000")
+      #   red.split_complementary
+      #   # => [#<RGB ...>, #<RGB ...>] (cyan-blue, cyan-green)
+      def split_complementary(angle: 30)
+        [rotate_hue(180 - angle), rotate_hue(180 + angle)]
+      end
+
+      # Returns three tetradic colors forming a square on the color wheel.
+      #
+      # Square tetradic uses four colors evenly spaced (90° apart).
+      # This creates a rich, bold color scheme with equal visual weight.
+      #
+      # @return [Array<RGB, HSL, OKLCH>] Three colors at +90°, +180°, +270°
+      #
+      # @example
+      #   red = Unmagic::Color.parse("#FF0000")
+      #   red.tetradic_square
+      #   # => [#<RGB ...>, #<RGB ...>, #<RGB ...>]
+      def tetradic_square
+        [rotate_hue(90), rotate_hue(180), rotate_hue(270)]
+      end
+
+      # Returns three tetradic colors forming a rectangle on the color wheel.
+      #
+      # Rectangular tetradic uses two complementary pairs with configurable
+      # spacing. This provides flexibility between harmony and contrast.
+      #
+      # @param angle [Numeric] Degrees between first pair (default: 60)
+      # @return [Array<RGB, HSL, OKLCH>] Three colors at +angle°, +180°, +(180+angle)°
+      #
+      # @example
+      #   red = Unmagic::Color.parse("#FF0000")
+      #   red.tetradic_rectangle(angle: 60)
+      def tetradic_rectangle(angle: 60)
+        [rotate_hue(angle), rotate_hue(180), rotate_hue(180 + angle)]
+      end
+
+      # Returns an array of colors with varying lightness (same hue).
+      #
+      # Creates a monochromatic palette by generating colors across a
+      # lightness range while preserving hue and saturation.
+      #
+      # @param steps [Integer] Number of colors to generate (default: 5)
+      # @return [Array<RGB, HSL, OKLCH>] Colors with lightness from 15% to 85%
+      #
+      # @example
+      #   blue = Unmagic::Color.parse("#0000FF")
+      #   blue.monochromatic(steps: 5)
+      #   # => [very dark blue, dark blue, medium blue, light blue, very light blue]
+      def monochromatic(steps: 5)
+        raise ArgumentError, "steps must be at least 1" if steps < 1
+
+        hsl = to_hsl
+        min_lightness = 15.0
+        max_lightness = 85.0
+        step_size = (max_lightness - min_lightness) / (steps - 1).to_f
+
+        (0...steps).map do |i|
+          lightness = min_lightness + (i * step_size)
+          result = HSL.new(
+            hue: hsl.hue.value,
+            saturation: hsl.saturation.value,
+            lightness: lightness,
+            alpha: hsl.alpha.value,
+          )
+          convert_harmony_result(result)
+        end
+      end
+
+      # Returns an array of progressively darker colors (shades).
+      #
+      # Shades are created by reducing lightness, simulating the effect
+      # of adding black to the original color.
+      #
+      # @param steps [Integer] Number of shades to generate (default: 5)
+      # @param amount [Float] Total amount of darkening 0.0-1.0 (default: 0.5)
+      # @return [Array<RGB, HSL, OKLCH>] Progressively darker colors
+      #
+      # @example
+      #   red = Unmagic::Color.parse("#FF0000")
+      #   red.shades(steps: 3)
+      #   # => [slightly darker red, darker red, darkest red]
+      def shades(steps: 5, amount: 0.5)
+        raise ArgumentError, "steps must be at least 1" if steps < 1
+
+        hsl = to_hsl
+        step_amount = amount / steps.to_f
+
+        (1..steps).map do |i|
+          new_lightness = hsl.lightness.value * (1 - (step_amount * i))
+          result = HSL.new(
+            hue: hsl.hue.value,
+            saturation: hsl.saturation.value,
+            lightness: new_lightness.clamp(0, 100),
+            alpha: hsl.alpha.value,
+          )
+          convert_harmony_result(result)
+        end
+      end
+
+      # Returns an array of progressively lighter colors (tints).
+      #
+      # Tints are created by increasing lightness, simulating the effect
+      # of adding white to the original color.
+      #
+      # @param steps [Integer] Number of tints to generate (default: 5)
+      # @param amount [Float] Total amount of lightening 0.0-1.0 (default: 0.5)
+      # @return [Array<RGB, HSL, OKLCH>] Progressively lighter colors
+      #
+      # @example
+      #   blue = Unmagic::Color.parse("#0000FF")
+      #   blue.tints(steps: 3)
+      #   # => [slightly lighter blue, lighter blue, lightest blue]
+      def tints(steps: 5, amount: 0.5)
+        raise ArgumentError, "steps must be at least 1" if steps < 1
+
+        hsl = to_hsl
+        step_amount = amount / steps.to_f
+
+        (1..steps).map do |i|
+          new_lightness = hsl.lightness.value + (100 - hsl.lightness.value) * (step_amount * i)
+          result = HSL.new(
+            hue: hsl.hue.value,
+            saturation: hsl.saturation.value,
+            lightness: new_lightness.clamp(0, 100),
+            alpha: hsl.alpha.value,
+          )
+          convert_harmony_result(result)
+        end
+      end
+
+      # Returns an array of progressively desaturated colors (tones).
+      #
+      # Tones are created by reducing saturation, simulating the effect
+      # of adding gray to the original color.
+      #
+      # @param steps [Integer] Number of tones to generate (default: 5)
+      # @param amount [Float] Total amount of desaturation 0.0-1.0 (default: 0.5)
+      # @return [Array<RGB, HSL, OKLCH>] Progressively less saturated colors
+      #
+      # @example
+      #   red = Unmagic::Color.parse("#FF0000")
+      #   red.tones(steps: 3)
+      #   # => [slightly muted red, more muted red, grayish red]
+      def tones(steps: 5, amount: 0.5)
+        raise ArgumentError, "steps must be at least 1" if steps < 1
+
+        hsl = to_hsl
+        step_amount = amount / steps.to_f
+
+        (1..steps).map do |i|
+          new_saturation = hsl.saturation.value * (1 - (step_amount * i))
+          result = HSL.new(
+            hue: hsl.hue.value,
+            saturation: new_saturation.clamp(0, 100),
+            lightness: hsl.lightness.value,
+            alpha: hsl.alpha.value,
+          )
+          convert_harmony_result(result)
+        end
+      end
+
+      private
+
+      # Rotate the hue by the specified degrees and return a new color.
+      #
+      # @param degrees [Numeric] Degrees to rotate (positive = clockwise)
+      # @return [RGB, HSL, OKLCH] New color with rotated hue (same type as self)
+      def rotate_hue(degrees)
+        hsl = to_hsl
+        result = HSL.new(
+          hue: hsl.hue.value + degrees,
+          saturation: hsl.saturation.value,
+          lightness: hsl.lightness.value,
+          alpha: hsl.alpha.value,
+        )
+        convert_harmony_result(result)
+      end
+
+      # Convert an HSL result back to the original color space.
+      #
+      # @param hsl_color [HSL] The HSL color to convert
+      # @return [RGB, HSL, OKLCH] Color in the same space as self
+      def convert_harmony_result(hsl_color)
+        case self
+        when RGB then hsl_color.to_rgb
+        when OKLCH then hsl_color.to_oklch
+        else hsl_color
+        end
+      end
+    end
+  end
+end