unmagic-color 0.1.0 → 0.2.1

data/lib/unmagic/color/hsl/gradient/linear.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    class HSL
+      # Gradient generation in HSL color space.
+      module Gradient
+        # Linear gradient interpolation in HSL color space.
+        #
+        # Creates smooth color transitions by interpolating hue, saturation, and
+        # lightness separately. HSL gradients often produce more visually pleasing
+        # results than RGB for transitions across the color wheel.
+        #
+        # ## HSL Interpolation
+        #
+        # HSL gradients interpolate through the color wheel (hue), which can create
+        # smoother transitions through vivid colors. The hue component uses shortest-arc
+        # interpolation via the existing blend method.
+        #
+        # ## Examples
+        #
+        #   # Rainbow gradient
+        #   gradient = Unmagic::Color::HSL::Gradient::Linear.build(
+        #     [
+        #       ["hsl(0, 100%, 50%)", 0.0],     # Red
+        #       ["hsl(120, 100%, 50%)", 0.5],   # Green
+        #       ["hsl(240, 100%, 50%)", 1.0]    # Blue
+        #     ],
+        #     direction: "to right"
+        #   )
+        #   bitmap = gradient.rasterize(width: 100)
+        #
+        #   # Simple two-color gradient
+        #   gradient = Unmagic::Color::HSL::Gradient::Linear.build(
+        #     ["hsl(0, 100%, 50%)", "hsl(240, 100%, 50%)"],
+        #     direction: "to bottom"
+        #   )
+        #   bitmap = gradient.rasterize(width: 1, height: 50)
+        #
+        #   # Angled gradient with color objects
+        #   gradient = Unmagic::Color::HSL::Gradient::Linear.build(
+        #     [
+        #       Unmagic::Color::HSL.new(hue: 0, saturation: 100, lightness: 50),
+        #       Unmagic::Color::HSL.new(hue: 240, saturation: 100, lightness: 50)
+        #     ],
+        #     direction: "45deg"
+        #   )
+        #   bitmap = gradient.rasterize(width: 100, height: 100)
+        class Linear < Unmagic::Color::Gradient::Base
+          class << self
+            # Get the HSL color class.
+            #
+            # @return [Class] Unmagic::Color::HSL
+            def color_class
+              Unmagic::Color::HSL
+            end
+          end
+
+          # Rasterize the gradient to a bitmap.
+          #
+          # Generates a bitmap containing the gradient with support for angled directions.
+          # Hue interpolation uses shortest-arc blending for smooth color wheel transitions.
+          #
+          # @param width [Integer] Width of the bitmap (default 1)
+          # @param height [Integer] Height of the bitmap (default 1)
+          # @return [Bitmap] A bitmap with the specified dimensions
+          #
+          # @raise [Error] If width or height is less than 1
+          def rasterize(width: 1, height: 1)
+            raise self.class::Error, "width must be at least 1" if width < 1
+            raise self.class::Error, "height must be at least 1" if height < 1
+
+            # Get the angle from the direction's "to" component
+            degrees = @direction.to.value
+
+            # Generate pixels row by row
+            pixels = Array.new(height) do |y|
+              Array.new(width) do |x|
+                position = calculate_position(x, y, width, height, degrees)
+                color_at_position(position)
+              end
+            end
+
+            Unmagic::Color::Gradient::Bitmap.new(
+              width: width,
+              height: height,
+              pixels: pixels,
+            )
+          end
+
+          private
+
+          def validate_color_types(stops)
+            stops.each_with_index do |stop, i|
+              unless stop.color.is_a?(Unmagic::Color::HSL)
+                raise self.class::Error, "stops[#{i}].color must be an HSL color"
+              end
+            end
+          end
+
+          # Calculate the position (0-1) of a pixel in the gradient.
+          #
+          # @param x [Integer] X coordinate
+          # @param y [Integer] Y coordinate
+          # @param width [Integer] Bitmap width
+          # @param height [Integer] Bitmap height
+          # @param degrees [Float] Gradient angle in degrees
+          # @return [Float] Position along gradient (0.0 to 1.0)
+          def calculate_position(x, y, width, height, degrees)
+            # Normalize coordinates to 0-1 range
+            nx = width > 1 ? x / (width - 1).to_f : 0.5
+            ny = height > 1 ? y / (height - 1).to_f : 0.5
+
+            # Calculate position based on angle
+            angle_rad = degrees * Math::PI / 180.0
+
+            # The gradient line goes in the direction of the angle
+            # 0° = to top (upward)
+            # 90° = to right
+            # 180° = to bottom (downward)
+            # 270° = to left
+            dx = Math.sin(angle_rad)
+            dy = Math.cos(angle_rad)
+
+            # Calculate position by projecting pixel onto gradient direction
+            # We want position 0 at the start and position 1 at the end
+            position = (nx - 0.5) * dx + (0.5 - ny) * dy + 0.5
+
+            # Clamp to valid range
+            position.clamp(0.0, 1.0)
+          end
+
+          # Get the color at a specific position in the gradient.
+          #
+          # @param position [Float] Position along gradient (0.0 to 1.0)
+          # @return [Color] The interpolated color at this position
+          def color_at_position(position)
+            start_stop, end_stop = find_bracket_stops(position)
+
+            if start_stop.position == end_stop.position
+              start_stop.color
+            else
+              segment_length = end_stop.position - start_stop.position
+              blend_amount = (position - start_stop.position) / segment_length
+              start_stop.color.blend(end_stop.color, blend_amount)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/hsl.rb

@@ -75,31 +75,37 @@ module Unmagic
       # Error raised when parsing HSL color strings fails
       class ParseError < Color::Error; end
 
-      attr_reader :hue, :saturation, :lightness
+      attr_reader :hue, :saturation, :lightness, :alpha
 
       # Create a new HSL color.
       #
       # @param hue [Numeric] Hue in degrees (0-360), wraps around if outside range
       # @param saturation [Numeric] Saturation percentage (0-100), clamped to range
       # @param lightness [Numeric] Lightness percentage (0-100), clamped to range
+      # @param alpha [Numeric, Color::Alpha, nil] Alpha channel (0-100%), defaults to 100 (fully opaque)
       #
       # @example Create a pure red
       #   HSL.new(hue: 0, saturation: 100, lightness: 50)
       #
+      # @example Create a semi-transparent blue
+      #   HSL.new(hue: 240, saturation: 40, lightness: 80, alpha: 50)
+      #
       # @example Create a pastel blue
       #   HSL.new(hue: 240, saturation: 40, lightness: 80)
-      def initialize(hue:, saturation:, lightness:)
+      def initialize(hue:, saturation:, lightness:, alpha: nil)
         super()
         @hue = Color::Hue.new(value: hue)
-        @saturation = Color::Saturation.new(saturation)
-        @lightness = Color::Lightness.new(lightness)
+        @saturation = Color::Saturation.new(value: saturation)
+        @lightness = Color::Lightness.new(value: lightness)
+        @alpha = Color::Alpha.build(alpha) || Color::Alpha::DEFAULT
       end
 
       class << self
         # Parse an HSL color from a string.
         #
         # Accepts formats:
-        # - CSS format: "hsl(120, 100%, 50%)"
+        # - Legacy: "hsl(120, 100%, 50%)" or "hsla(120, 100%, 50%, 0.5)"
+        # - Modern: "hsl(120 100% 50% / 0.5)" or "hsl(120 100% 50% / 50%)"
         # - Raw values: "120, 100%, 50%" or "120, 100, 50"
         # - Percentages optional for saturation and lightness
         #
@@ -110,18 +116,51 @@ module Unmagic
         # @example Parse CSS format
         #   HSL.parse("hsl(120, 100%, 50%)")
         #
+        # @example Parse with alpha
+        #   HSL.parse("hsl(120 100% 50% / 0.5)")
+        #
         # @example Parse without function wrapper
         #   HSL.parse("240, 50%, 75%")
         def parse(input)
           raise ParseError, "Input must be a string" unless input.is_a?(::String)
 
-          # Remove hsl() wrapper if present
-          clean = input.gsub(/^hsl\s*\(\s*|\s*\)$/, "").strip
+          # Remove hsl() or hsla() wrapper if present
+          clean = input.gsub(/^hsla?\s*\(\s*|\s*\)$/, "").strip
+
+          # Check for modern format with slash (space-separated with / for alpha)
+          # Example: "120 100% 50% / 0.5"
+          # Note: Modern format is only used WITH the hsl() wrapper
+          alpha = nil
+          has_slash = clean.include?("/")
+          if has_slash
+            parts = clean.split("/").map(&:strip)
+            raise ParseError, "Invalid format with /: expected 'H S% L% / alpha'" unless parts.length == 2
+
+            clean = parts[0]
+            alpha = Color::Alpha.parse(parts[1])
+          end
+
+          # Split HSL values
+          # - Comma-separated: legacy format (with or without hsl() wrapper)
+          # - Space-separated: only valid WITH hsl() wrapper (modern format)
+          parts = if clean.include?(",")
+            # Legacy comma-separated format
+            clean.split(/\s*,\s*/)
+          elsif has_slash || input.match?(/^hsla?\s*\(/)
+            # Modern space-separated format (only with hsl() wrapper or slash)
+            clean.split(/\s+/)
+          else
+            # No commas and no hsl() wrapper - invalid
+            raise ParseError, "Space-separated values require hsl() wrapper, use commas for raw values"
+          end
+
+          unless [3, 4].include?(parts.length)
+            raise ParseError, "Expected 3 or 4 HSL values, got #{parts.length}"
+          end
 
-          # Split and parse values
-          parts = clean.split(/\s*,\s*/)
-          unless parts.length == 3
-            raise ParseError, "Expected 3 HSL values, got #{parts.length}"
+          # Parse alpha from 4th value if present (legacy format)
+          if parts.length == 4 && alpha.nil?
+            alpha = Color::Alpha.parse(parts[3])
           end
 
           # Check if hue is numeric
@@ -159,7 +198,36 @@ module Unmagic
             raise ParseError, "Lightness must be between 0 and 100, got #{l}"
           end
 
-          new(hue: h, saturation: s, lightness: l)
+          new(hue: h, saturation: s, lightness: l, alpha: alpha)
+        end
+
+        # Build an HSL color from a string, positional values, or keyword arguments.
+        #
+        # @param args [String, Numeric] Either a color string or 3 component values
+        # @option kwargs [Numeric] :hue Hue in degrees (0-360)
+        # @option kwargs [Numeric] :saturation Saturation percentage (0-100)
+        # @option kwargs [Numeric] :lightness Lightness percentage (0-100)
+        # @return [HSL] The constructed HSL color
+        #
+        # @example From string
+        #   HSL.build("hsl(120, 100%, 50%)")
+        #
+        # @example From positional values
+        #   HSL.build(120, 100, 50)
+        #
+        # @example From keyword arguments
+        #   HSL.build(hue: 120, saturation: 100, lightness: 50)
+        def build(*args, **kwargs)
+          if kwargs.any?
+            new(**kwargs)
+          elsif args.length == 1
+            parse(args[0])
+          elsif args.length == 3
+            values = args.map { |v| v.is_a?(::String) ? v.to_f : v }
+            new(hue: values[0], saturation: values[1], lightness: values[2])
+          else
+            raise ArgumentError, "Expected 1 or 3 arguments, got #{args.length}"
+          end
         end
 
         # Generate a deterministic HSL color from an integer seed.
@@ -211,7 +279,7 @@ module Unmagic
       def to_rgb
         rgb = hsl_to_rgb
         require_relative "rgb"
-        Unmagic::Color::RGB.new(red: rgb[0], green: rgb[1], blue: rgb[2])
+        Unmagic::Color::RGB.new(red: rgb[0], green: rgb[1], blue: rgb[2], alpha: @alpha)
       end
 
       # Convert to OKLCH color space.
@@ -223,6 +291,15 @@ module Unmagic
         to_rgb.to_oklch
       end
 
+      # Convert to hex string.
+      #
+      # Converts via RGB as an intermediate step.
+      #
+      # @return [String] The color as a hex string (e.g., "#ff5733")
+      def to_hex
+        to_rgb.to_hex
+      end
+
       # Calculate the relative luminance.
       #
       # Converts to RGB first, then calculates luminance.
@@ -254,7 +331,12 @@ module Unmagic
         new_saturation = @saturation.value * (1 - amount) + other_hsl.saturation.value * amount
         new_lightness = @lightness.value * (1 - amount) + other_hsl.lightness.value * amount
 
-        Unmagic::Color::HSL.new(hue: new_hue, saturation: new_saturation, lightness: new_lightness)
+        Unmagic::Color::HSL.new(
+          hue: new_hue,
+          saturation: new_saturation,
+          lightness: new_lightness,
+          alpha: @alpha.value * (1 - amount) + other_hsl.alpha.value * amount,
+        )
       end
 
       # Create a lighter version by increasing lightness.
@@ -271,7 +353,7 @@ module Unmagic
       def lighten(amount = 0.1)
         amount = amount.to_f.clamp(0, 1)
         new_lightness = @lightness.value + (100 - @lightness.value) * amount
-        Unmagic::Color::HSL.new(hue: @hue.value, saturation: @saturation.value, lightness: new_lightness)
+        Unmagic::Color::HSL.new(hue: @hue.value, saturation: @saturation.value, lightness: new_lightness, alpha: @alpha.value)
       end
 
       # Create a darker version by decreasing lightness.
@@ -288,7 +370,7 @@ module Unmagic
       def darken(amount = 0.1)
         amount = amount.to_f.clamp(0, 1)
         new_lightness = @lightness.value * (1 - amount)
-        Unmagic::Color::HSL.new(hue: @hue.value, saturation: @saturation.value, lightness: new_lightness)
+        Unmagic::Color::HSL.new(hue: @hue.value, saturation: @saturation.value, lightness: new_lightness, alpha: @alpha.value)
       end
 
       # Check if two HSL colors are equal.
@@ -358,7 +440,7 @@ module Unmagic
           end
 
           # Create new HSL color with computed values
-          color = self.class.new(hue: @hue.value, saturation: new_saturation, lightness: new_lightness)
+          color = self.class.build(hue: @hue.value, saturation: new_saturation, lightness: new_lightness, alpha: @alpha.value)
           colors << color
         end
 
@@ -367,16 +449,58 @@ module Unmagic
 
       # Convert to string representation.
       #
-      # Returns the CSS hsl() function format.
+      # Returns the CSS hsl() function format. If alpha is less than 100%,
+      # includes alpha value using modern CSS syntax with / separator.
       #
-      # @return [String] HSL string like "hsl(240, 80%, 50%)"
+      # @return [String] HSL string like "hsl(240, 80%, 50%)" or "hsl(240, 80%, 50% / 0.5)"
       #
-      # @example
+      # @example Fully opaque
       #   color = HSL.new(hue: 240, saturation: 80, lightness: 50)
       #   color.to_s
       #   # => "hsl(240, 80.0%, 50.0%)"
+      #
+      # @example Semi-transparent
+      #   color = HSL.new(hue: 240, saturation: 80, lightness: 50, alpha: 50)
+      #   color.to_s
+      #   # => "hsl(240, 80.0%, 50.0% / 0.5)"
       def to_s
-        "hsl(#{@hue.value.round}, #{@saturation.value}%, #{@lightness.value}%)"
+        if @alpha.value < 100
+          "hsl(#{@hue.value.round}, #{@saturation.value}%, #{@lightness.value}% / #{@alpha.to_css})"
+        else
+          "hsl(#{@hue.value.round}, #{@saturation.value}%, #{@lightness.value}%)"
+        end
+      end
+
+      # Convert to ANSI SGR color code.
+      #
+      # Converts to RGB first, then generates the ANSI code.
+      #
+      # @param layer [Symbol] Whether to generate foreground (:foreground) or background (:background) code
+      # @param mode [Symbol] Color format mode (:truecolor, :palette256, :palette16)
+      # @return [String] ANSI SGR code like "31" or "38;2;255;0;0"
+      #
+      # @example
+      #   color = HSL.new(hue: 0, saturation: 100, lightness: 50)
+      #   color.to_ansi
+      #   # => "31"
+      def to_ansi(layer: :foreground, mode: :truecolor)
+        to_rgb.to_ansi(layer: layer, mode: mode)
+      end
+
+      # 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
+      #   hsl = HSL.new(hue: 9, saturation: 100, lightness: 60)
+      #   pp hsl
+      #   # Outputs: #<Unmagic::Color::HSL[█] @hue=9 @saturation=100 @lightness=60>
+      #   # (with colored █ block)
+      def pretty_print(pp)
+        pp.text("#<#{self.class.name}[\x1b[#{to_ansi(mode: :truecolor)}m█\x1b[0m] @hue=#{@hue.value.round} @saturation=#{@saturation.value.round} @lightness=#{@lightness.value.round}>")
       end
 
       private

data/lib/unmagic/color/oklch/gradient/linear.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    class OKLCH
+      # Gradient generation in OKLCH color space.
+      module Gradient
+        # Linear gradient interpolation in OKLCH color space.
+        #
+        # Creates perceptually uniform color transitions by interpolating lightness,
+        # chroma, and hue in the OKLCH color space. OKLCH gradients maintain consistent
+        # perceived brightness across the gradient.
+        #
+        # ## OKLCH Interpolation
+        #
+        # OKLCH is a perceptually uniform color space, meaning equal steps in OKLCH
+        # values produce equal perceived differences in color. This makes OKLCH gradients
+        # ideal for UI design where consistent visual weight is important.
+        #
+        # ## Examples
+        #
+        #   # Perceptually uniform gradient
+        #   gradient = Unmagic::Color::OKLCH::Gradient::Linear.build(
+        #     [
+        #       ["oklch(0.5 0.15 30)", 0.0],
+        #       ["oklch(0.7 0.15 240)", 1.0]
+        #     ],
+        #     direction: "to right"
+        #   )
+        #   bitmap = gradient.rasterize(width: 100)
+        #
+        #   # Simple two-color gradient
+        #   gradient = Unmagic::Color::OKLCH::Gradient::Linear.build(
+        #     ["oklch(0.3 0.15 30)", "oklch(0.7 0.15 240)"],
+        #     direction: "to bottom"
+        #   )
+        #   bitmap = gradient.rasterize(width: 1, height: 50)
+        #
+        #   # Angled gradient with color objects
+        #   gradient = Unmagic::Color::OKLCH::Gradient::Linear.build(
+        #     [
+        #       Unmagic::Color::OKLCH.new(lightness: 0.3, chroma: 0.15, hue: 30),
+        #       Unmagic::Color::OKLCH.new(lightness: 0.7, chroma: 0.15, hue: 240)
+        #     ],
+        #     direction: "45deg"
+        #   )
+        #   bitmap = gradient.rasterize(width: 100, height: 100)
+        class Linear < Unmagic::Color::Gradient::Base
+          class << self
+            # Get the OKLCH color class.
+            #
+            # @return [Class] Unmagic::Color::OKLCH
+            def color_class
+              Unmagic::Color::OKLCH
+            end
+          end
+
+          # Rasterize the gradient to a bitmap.
+          #
+          # Generates a bitmap containing the gradient with support for angled directions.
+          # Colors are interpolated in perceptually uniform OKLCH space.
+          #
+          # @param width [Integer] Width of the bitmap (default 1)
+          # @param height [Integer] Height of the bitmap (default 1)
+          # @return [Bitmap] A bitmap with the specified dimensions
+          #
+          # @raise [Error] If width or height is less than 1
+          def rasterize(width: 1, height: 1)
+            raise self.class::Error, "width must be at least 1" if width < 1
+            raise self.class::Error, "height must be at least 1" if height < 1
+
+            # Get the angle from the direction's "to" component
+            degrees = @direction.to.value
+
+            # Generate pixels row by row
+            pixels = Array.new(height) do |y|
+              Array.new(width) do |x|
+                position = calculate_position(x, y, width, height, degrees)
+                color_at_position(position)
+              end
+            end
+
+            Unmagic::Color::Gradient::Bitmap.new(
+              width: width,
+              height: height,
+              pixels: pixels,
+            )
+          end
+
+          private
+
+          def validate_color_types(stops)
+            stops.each_with_index do |stop, i|
+              unless stop.color.is_a?(Unmagic::Color::OKLCH)
+                raise self.class::Error, "stops[#{i}].color must be an OKLCH color"
+              end
+            end
+          end
+
+          # Calculate the position (0-1) of a pixel in the gradient.
+          #
+          # @param x [Integer] X coordinate
+          # @param y [Integer] Y coordinate
+          # @param width [Integer] Bitmap width
+          # @param height [Integer] Bitmap height
+          # @param degrees [Float] Gradient angle in degrees
+          # @return [Float] Position along gradient (0.0 to 1.0)
+          def calculate_position(x, y, width, height, degrees)
+            # Normalize coordinates to 0-1 range
+            nx = width > 1 ? x / (width - 1).to_f : 0.5
+            ny = height > 1 ? y / (height - 1).to_f : 0.5
+
+            # Calculate position based on angle
+            angle_rad = degrees * Math::PI / 180.0
+
+            # The gradient line goes in the direction of the angle
+            # 0° = to top (upward)
+            # 90° = to right
+            # 180° = to bottom (downward)
+            # 270° = to left
+            dx = Math.sin(angle_rad)
+            dy = Math.cos(angle_rad)
+
+            # Calculate position by projecting pixel onto gradient direction
+            # We want position 0 at the start and position 1 at the end
+            position = (nx - 0.5) * dx + (0.5 - ny) * dy + 0.5
+
+            # Clamp to valid range
+            position.clamp(0.0, 1.0)
+          end
+
+          # Get the color at a specific position in the gradient.
+          #
+          # @param position [Float] Position along gradient (0.0 to 1.0)
+          # @return [Color] The interpolated color at this position
+          def color_at_position(position)
+            start_stop, end_stop = find_bracket_stops(position)
+
+            if start_stop.position == end_stop.position
+              start_stop.color
+            else
+              segment_length = end_stop.position - start_stop.position
+              blend_amount = (position - start_stop.position) / segment_length
+              start_stop.color.blend(end_stop.color, blend_amount)
+            end
+          end
+        end
+      end
+    end
+  end
+end