feat: enhance textToColor with color interpolation and variation modes

Author: tomloprod

README.md

@@ -223,6 +223,27 @@ Generate a fixed color based on a string.
 /** @var HslColor $hslColor */
 $hslColor = colority()->textToColor("Hi, I'm Tomás");
 ```
+
+You can also pass a `fromColor`. In that case, only colors within the same color range as that color will be generated.
+
+```php
+/** @var HslColor $hslColor - Only colors within the grayscale range. */
+$hslColor = colority()->textToColor("Hi, I'm Tomás", colority()->fromHex('#CCC'));
+```
+
+On the other hand, if you pass both `fromColor` and `toColor`, the method performs a **linear interpolation** between the two colors. The same text will always map to the same position in the gradient between the colors, creating a deterministic color that falls somewhere on the line connecting the two provided colors.
+
+```php
+/** @var HslColor $hslColor - Color interpolated between light green and dark teal */
+$hslColor = colority()->textToColor(
+    "Hi, I'm Tomás",
+    colority()->fromHex('#85d5a4'), // Light green (start point)
+    colority()->fromHex('#165a59')  // Dark teal (end point)
+);
+```
+
+This interpolation approach is particularly useful for creating **consistent color themes** where you want all generated colors to harmonize within a specific palette range.
+
 > **🧙 Advise** 
 > Useful for generating a color associated with, for example, **a username, mail address, etc**, since a string will always return the same color.
 
@@ -273,7 +294,7 @@ Colority::fromRgb(string|array<int> $rgbValue): RgbColor
 
 Colority::fromHsl(string|array<float> $hslValue): HslColor
 
-Colority::textToColor(string $text): 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
 ```

src/Services/ColorityManager.php

@@ -42,18 +42,72 @@ public static function instance(): self
         return self::$instance;
     }
 
-    public function textToColor(string $text): HslColor
+    /**
+     * Generates a deterministic color from a text string.
+     *
+     * This method creates a consistent color representation of any given text by using
+     * SHA256 hashing to ensure the same text always produces the same color.
+     *
+     * Behavior modes:
+     * - If both `fromColor` and `toColor` are provided: interpolates between
+     *   the two colors using the text hash to determine the position in the
+     *   gradient (0-1)
+     *
+     * - If only `fromColor` is provided: generates color variations around the
+     *   base color with small random offsets (±30° hue, ±10% saturation/lightness)
+     *
+     * - If no colors are provided: generates a completely random color based on
+     *   the hash
+     *
+     * @param  string  $text  The input text to convert to a color
+     * @param  Color|null  $fromColor  Optional base color for variations or interpolation start
+     * @param  Color|null  $toColor  Optional end color for interpolation
+     * @return HslColor The generated color in HSL format
+     */
+    public function textToColor(string $text, ?Color $fromColor = null, ?Color $toColor = null): HslColor
     {
         $hash = hash('sha256', $text);
 
-        // between 0 and 360deg
-        $hue = hexdec(mb_substr($hash, 0, 8)) % 361;
-
-        // between 0 and 100%
-        $saturation = hexdec(mb_substr($hash, 8, 8)) % 101;
-
-        // between 0 and 100%
-        $lightness = hexdec(mb_substr($hash, 16, 8)) % 101;
+        if ($fromColor instanceof Color && $toColor instanceof Color) {
+            // Interpolar entre dos colores base
+            $startHslColor = $fromColor->toHsl();
+            $endHslColor = $toColor->toHsl();
+
+            [$startH, $startS, $startL] = $startHslColor->getArrayValueColor();
+            [$endH, $endS, $endL] = $endHslColor->getArrayValueColor();
+
+            // Use the hash to determine the position in the gradient (0-1)
+            $interpolationFactor = (hexdec(mb_substr($hash, 0, 8)) % 1000) / 1000;
+
+            // Interpolate each HSL component
+            $hue = $startH + ($endH - $startH) * $interpolationFactor;
+            $saturation = $startS + ($endS - $startS) * $interpolationFactor;
+            $lightness = $startL + ($endL - $startL) * $interpolationFactor;
+
+            // Ensure the values are within valid ranges
+            $hue = max(0, min(360, $hue));
+            $saturation = max(0, min(100, $saturation));
+            $lightness = max(0, min(100, $lightness));
+
+        } elseif ($fromColor instanceof Color) {
+            // Use only the start color to generate variations within that palette
+            $baseHslColor = $fromColor->toHsl();
+            [$baseH, $baseS, $baseL] = $baseHslColor->getArrayValueColor();
+
+            // Generate small variations around the base color using the hash
+            $hueVariation = (hexdec(mb_substr($hash, 0, 8)) % 61) - 30; // ±30 degrees
+            $saturationVariation = (hexdec(mb_substr($hash, 8, 8)) % 21) - 10; // ±10%
+            $lightnessVariation = (hexdec(mb_substr($hash, 16, 8)) % 21) - 10; // ±10%
+
+            $hue = max(0, min(360, $baseH + $hueVariation));
+            $saturation = max(0, min(100, $baseS + $saturationVariation));
+            $lightness = max(0, min(100, $baseL + $lightnessVariation));
+
+        } else {
+            $hue = hexdec(mb_substr($hash, 0, 8)) % 361;
+            $saturation = hexdec(mb_substr($hash, 8, 8)) % 101;
+            $lightness = hexdec(mb_substr($hash, 16, 8)) % 101;
+        }
 
         return $this->fromHsl([$hue, $saturation, $lightness]);
     }

src/Support/Facades/Colority.php

@@ -15,7 +15,7 @@
  * @method static HexColor fromHex(string $hexValue)
  * @method static RgbColor fromRgb(string|array<int> $rgbValue)
  * @method static HslColor fromHsl(string|array<float> $hslValue)
- * @method static HslColor textToColor(string $text)
+ * @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
  */
 final class Colority

tests/Services/ColorityManagerTest.php

@@ -40,6 +40,52 @@
     ['Colority', 'hsl(315deg,73%,64%)'],
 ]);
 
+test('textToColor with fromColor and toColor interpolates between colors', function (): void {
+    $instance = ColorityManager::instance();
+
+    $fromColor = new HslColor('hsl(0deg,100%,50%)'); // Red
+    $toColor = new HslColor('hsl(240deg,100%,50%)'); // Blue
+
+    $result = $instance->textToColor('test', $fromColor, $toColor);
+
+    expect($result)->toBeInstanceOf(HslColor::class);
+
+    // The result should be deterministic for the same input
+    $result2 = $instance->textToColor('test', $fromColor, $toColor);
+    expect($result->getValueColorWithMeasureUnits())->toBe($result2->getValueColorWithMeasureUnits());
+
+    // Different texts should produce different results
+    $result3 = $instance->textToColor('different text', $fromColor, $toColor);
+    expect($result->getValueColorWithMeasureUnits())->not()->toBe($result3->getValueColorWithMeasureUnits());
+});
+
+test('textToColor with fromColor generates variations around base color', function (): void {
+    $instance = ColorityManager::instance();
+
+    $baseColor = new HslColor('hsl(120deg,60%,40%)'); // Green base
+
+    $result = $instance->textToColor('test', $baseColor);
+
+    expect($result)->toBeInstanceOf(HslColor::class);
+
+    // The result should be deterministic for the same input
+    $result2 = $instance->textToColor('test', $baseColor);
+    expect($result->getValueColorWithMeasureUnits())->toBe($result2->getValueColorWithMeasureUnits());
+
+    // Different texts should produce different variations
+    $result3 = $instance->textToColor('different text', $baseColor);
+    expect($result->getValueColorWithMeasureUnits())->not()->toBe($result3->getValueColorWithMeasureUnits());
+
+    // The result should be reasonably close to the base color
+    [$resultH, $resultS, $resultL] = $result->getArrayValueColor();
+    [$baseH, $baseS, $baseL] = $baseColor->getArrayValueColor();
+
+    // Verify variations are within expected ranges (±30° hue, ±10% saturation/lightness)
+    expect(abs($resultH - $baseH))->toBeLessThanOrEqual(30);
+    expect(abs($resultS - $baseS))->toBeLessThanOrEqual(10);
+    expect(abs($resultL - $baseL))->toBeLessThanOrEqual(10);
+});
+
 test('getSimilarColor', function (): void {
     $instance = ColorityManager::instance();