feat: support gradient generation

Functionality that addresses the need described in #5

Author: tomloprod

README.md

@@ -260,6 +260,23 @@ $hexColor = colority()->fromHex('#51B389');
 $similarHexColor = colority()->getSimilarColor($hexColor);
 ```
 
+#### gradient
+
+Generates a gradient of colors between multiple colors.
+
+```php
+/** @var array<HexColor> $gradient */
+$gradient = colority()->gradient(
+    colors: [
+        colority()->fromHex('#ff0000'), // Red
+        colority()->fromHex('#00ff00'), // Green
+        colority()->fromHex('#0000ff')  // Blue
+    ],
+    steps: 10
+);
+```
+
+
 ### Ways of using Colority
 You can use Colority either with the aliases `colority()` 
 ```php
@@ -297,6 +314,8 @@ Colority::fromHsl(string|array<float> $hslValue): HslColor
 Colority::textToColor(string $text, ?Color $fromColor = null, ?Color $toColor = null): HslColor
 
 Colority::getSimilarColor(Color $color, int $hueRange = 30, int $saturationRange = 10, int $lightnessRange = 10): Color
+
+Colority::gradient(array<Color> $colors, int $steps = 5): array<HexColor>
 ```
 
 ### `Color`

src/Services/ColorityManager.php

@@ -112,6 +112,64 @@ public function textToColor(string $text, ?Color $fromColor = null, ?Color $toCo
         return $this->fromHsl([$hue, $saturation, $lightness]);
     }
 
+    /**
+     * Generates a gradient of colors between multiple colors.
+     *
+     * @param  array<Color>  $colors  The array of colors to create the gradient from
+     * @param  int  $steps  The number of steps in the gradient
+     * @return array<HexColor> An array of HexColor objects representing the gradient
+     */
+    public function gradient(array $colors, int $steps = 5): array
+    {
+        if ($colors === []) {
+            return [];
+        }
+
+        if ($steps < 2 || count($colors) === 1) {
+            return [$colors[0]->toHsl()->toHex()];
+        }
+
+        $gradientColors = [];
+        $totalSegments = count($colors) - 1;
+
+        for ($i = 0; $i < $steps; $i++) {
+            // Calculate global progress (0 to 1)
+            $t = $i / ($steps - 1);
+
+            // Calculate which segment we are in
+            $segment = (int) floor($t * $totalSegments);
+
+            // Handle the last point explicitly to avoid out of bounds
+            if ($segment >= $totalSegments) {
+                $segment = $totalSegments - 1;
+            }
+
+            // Calculate local progress within the segment (0 to 1)
+            $segmentStart = $segment / $totalSegments;
+            $segmentEnd = ($segment + 1) / $totalSegments;
+            $localT = ($t - $segmentStart) / ($segmentEnd - $segmentStart);
+
+            $startHsl = $colors[$segment]->toHsl();
+            $endHsl = $colors[$segment + 1]->toHsl();
+
+            [$startH, $startS, $startL] = $startHsl->getArrayValueColor();
+            [$endH, $endS, $endL] = $endHsl->getArrayValueColor();
+
+            $hue = $startH + ($endH - $startH) * $localT;
+            $saturation = $startS + ($endS - $startS) * $localT;
+            $lightness = $startL + ($endL - $startL) * $localT;
+
+            // Ensure values are within valid ranges and rounded to avoid precision issues
+            $hue = round(max(0, min(360, $hue)), 2);
+            $saturation = round(max(0, min(100, $saturation)), 2);
+            $lightness = round(max(0, min(100, $lightness)), 2);
+
+            $gradientColors[] = $this->fromHsl([$hue, $saturation, $lightness])->toHex();
+        }
+
+        return $gradientColors;
+    }
+
     public function getSimilarColor(Color $color, int $hueRange = 30, int $saturationRange = 10, int $lightnessRange = 10): Color
     {
         [$baseH, $baseS, $baseL] = $color->toHsl()->getArrayValueColor();

src/Support/Facades/Colority.php

@@ -17,6 +17,7 @@
  * @method static HslColor fromHsl(string|array<float> $hslValue)
  * @method static HslColor textToColor(string $text, ?Color $fromColor = null, ?Color $toColor = null)
  * @method static getSimilarColor(Color $color, int $hueRange = 30, int $saturationRange = 10, int $lightnessRange = 10): Color
+ * @method static array<HexColor> gradient(array<Color> $colors, int $steps = 5): array
  */
 final class Colority
 {

tests/Services/ColorityManagerTest.php

@@ -186,3 +186,103 @@
     expect($colority->parse($hslColor))->toBeNull();
 
 })->with(['xxx(0,0,0)', 't,o,m', '(-255,-255,-255)', '0,0,0,0', 'hsl(0,0,0,0)']);
+
+/**
+ * Gradient
+ */
+it('generates a gradient between two colors', function (): void {
+    $colority = ColorityManager::instance();
+
+    $start = $colority->fromHex('#000000');
+
+    $end = $colority->fromHex('#ffffff');
+
+    $gradient = $colority->gradient([$start, $end], 3);
+
+    expect($gradient)->toHaveCount(3);
+
+    // Start color should be black
+    expect(strtolower($gradient[0]->toHex()->getValueColor()))->toBe('#000000');
+
+    // Middle color should be gray
+    // HSL interpolation of black (0,0,0) and white (0,0,100) -> (0,0,50) -> #808080
+    expect(strtolower($gradient[1]->toHex()->getValueColor()))->toBe('#808080');
+
+    // End color should be white
+    expect(strtolower($gradient[2]->toHex()->getValueColor()))->toBe('#ffffff');
+});
+
+it('generates a gradient with default steps', function (): void {
+    $colority = ColorityManager::instance();
+
+    $start = $colority->fromHex('#ff0000');
+
+    $end = $colority->fromHex('#0000ff');
+
+    $gradient = $colority->gradient([$start, $end]);
+
+    expect($gradient)->toHaveCount(5);
+});
+
+it('handles single step gradient request', function (): void {
+    $colority = ColorityManager::instance();
+
+    $start = $colority->fromHex('#ff0000');
+
+    $end = $colority->fromHex('#0000ff');
+
+    $gradient = $colority->gradient([$start, $end], 1);
+
+    expect($gradient)->toHaveCount(1);
+
+    expect(strtolower($gradient[0]->toHex()->getValueColor()))->toBe('#ff0000');
+});
+
+it('generates a gradient through multiple colors', function (): void {
+
+    $colority = ColorityManager::instance();
+
+    $red = $colority->fromHex('#ff0000');
+
+    $green = $colority->fromHex('#00ff00');
+
+    $blue = $colority->fromHex('#0000ff');
+
+    // 5 steps: Red -> (Red-Green) -> Green -> (Green-Blue) -> Blue
+    $gradient = $colority->gradient([$red, $green, $blue], 5);
+
+    expect($gradient)->toHaveCount(5);
+
+    expect($gradient)->each->toBeInstanceOf(HexColor::class);
+
+    $hexes = array_map(fn ($c) => strtolower($c->toHex()->getValueColor()), $gradient);
+
+    // Check start
+    expect($hexes[0])->toBe('#ff0000');
+
+    // Check middle
+    expect($hexes[2])->toBe('#00ff00');
+
+    // Check end
+    expect($hexes[4])->toBe('#0000ff');
+});
+
+it('handles empty array of colors', function (): void {
+    $colority = ColorityManager::instance();
+
+    $gradient = $colority->gradient([]);
+
+    expect($gradient)->toBeEmpty();
+});
+
+it('handles single color array', function (): void {
+    $colority = ColorityManager::instance();
+
+    $red = $colority->fromHex('#ff0000');
+
+    $gradient = $colority->gradient([$red], 5);
+
+    expect($gradient)->toHaveCount(1);
+
+    expect(strtolower($gradient[0]->toHex()->getValueColor()))->toBe('#ff0000');
+});