ColorInterface

Returns an array of colors that are near this color on the color wheel,
creating harmonious color schemes. Colors are spaced 30° apart, alternating
between positive and negative rotations.

The returned array includes this color as the first element, followed by
the requested number of analogous colors.

Examples:
- Color::parse('red')->analogous(2) // [red, red+30°, red-30°]
- Color::parse('blue')->analogous(4) // [blue, blue+30°, blue-30°, blue+60°, blue-60°]

Implements CSS/Photoshop-style blend modes, compositing this color (source) over
the backdrop color using the specified blend mode. All blending calculations happen
in sRGB space with proper alpha compositing.

Supported blend modes:
- 'normal': Source color (default)
- 'multiply': Darkens by multiplying colors
- 'screen': Lightens by inverting, multiplying, and inverting again
- 'overlay': Combines multiply and screen based on backdrop
- 'darken': Selects darker of source/backdrop per channel
- 'lighten': Selects lighter of source/backdrop per channel
- 'color-dodge': Brightens backdrop based on source
- 'color-burn': Darkens backdrop based on source
- 'hard-light': Combines multiply and screen based on source
- 'soft-light': Softer version of overlay
- 'difference': Absolute difference between colors
- 'exclusion': Similar to difference but lower contrast

Examples:
- Color::parse('red')->blend(Color::parse('blue'), 'multiply')
- Color::parse('#ff0000')->blend('#0000ff', 'screen')
- Color::parse('rgba(255 0 0 / 0.5)')->blend('blue', 'normal')

Returns the color that is 180° opposite on the color wheel in perceptually uniform
Oklch space. Complementary colors create high contrast and visual interest.

Examples:
- Color::parse('red')->complementary() // Returns cyan-like color
- Color::parse('blue')->complementary() // Returns yellow-like color
- Color::parse('#2ecc71')->complementary() // Returns magenta-like color

Adjusts the hue to make the color appear cooler, shifting toward blue and cyan
tones in perceptually uniform Oklch space. The amount controls how much the
color shifts toward cool tones.

Examples:
- Color::parse('red')->cool(0.5) // Shift red toward purple/blue
- Color::parse('yellow')->cool(0.8) // Shift yellow toward green-cyan

Adjusts lightness in perceptually uniform Oklch space. Positive values darken,
negative values lighten. This is equivalent to lighten() with a negated amount.

Examples:
- Color::parse('red')->darken(0.2) // Decrease lightness by 20%
- Color::parse('blue')->darken(0.5) // Decrease lightness by 50%
- Color::parse('green')->darken(-0.1) // Actually lightens by 10%

Adjusts chroma in perceptually uniform Oklch space. Lower chroma values make colors
less vivid, moving toward gray. The amount is always treated as a reduction.

Examples:
- Color::parse('red')->desaturate(0.5) // Make much less saturated
- Color::parse('blue')->desaturate(0.2) // Slightly less vivid

Returns true when both the current color and the $other argument are from the
same color space and have the same component values.

Accepts either a ColorInterface instance or a CSS color string. If a string is provided,
it is parsed and converted to this exact color space type.

This is the primary conversion method used by the library. All color space conversions
go through sRGB as an intermediate step when necessary.

Returns the alpha/opacity value of the color as a float in the range [0, 1],
where 0 is fully transparent and 1 is fully opaque.

Examples:
- Color::parse('rgb(255 0 0)')->getAlpha() // 1.0 (opaque)
- Color::parse('rgba(255 0 0 / 0.5)')->getAlpha() // 0.5 (semi-transparent)
- Color::parse('rgb(0 255 0 / 0)')->getAlpha() // 0.0 (transparent)

Returns the color's channel values in its native color space. The channel names
and value ranges depend on the color space:
- sRGB: ['r', 'g', 'b'] (0-1)
- Oklab: ['l', 'a', 'b'] (l: 0-1, a/b: unbounded)
- Oklch: ['l', 'c', 'h'] (l: 0-1, c: 0+, h: 0-360)
- Lab: ['l', 'a', 'b'] (l: 0-100, a/b: unbounded)
- Lch: ['l', 'c', 'h'] (l: 0-100, c: 0+, h: 0-360)
- XYZ: ['x', 'y', 'z'] (unbounded)
- Display P3: ['r', 'g', 'b'] (0-1)

The alpha channel is accessed separately via getAlpha().

This is particularly useful for CSS Relative Color Syntax or custom color
manipulations where you need direct access to channel values.

Examples:
- Color::parse('red')->getChannels() // ['r' => 1.0, 'g' => 0.0, 'b' => 0.0]
- Color::parse('oklab(0.5 0.1 -0.2)')->getChannels() // ['l' => 0.5, 'a' => 0.1, 'b' => -0.2]

Returns the hue angle in degrees [0, 360). Returns 0 for achromatic colors.

Calculates the WCAG relative luminance in sRGB space, returning a value between 0 and 1.

This is an alias for getAlpha().

Returns a lowercase identifier for the color space (e.g., 'srgb', 'oklab', 'oklch').
This name can be used with the to() method to convert between spaces.

Removes all chroma (colorfulness) by setting chroma to 0 in Oklch space,
resulting in a gray color with the same perceived brightness as the original.

Examples:
- Color::parse('red')->grayscale() // Gray with same luminance as red
- Color::parse('blue')->grayscale() // Gray with same luminance as blue
- Color::parse('#3498db')->grayscale() // Converts to equivalent gray

Inverts each RGB channel: new = 1 - old. Performs inversion in sRGB space
regardless of the original color space. Alpha channel is preserved unchanged.

Examples:
- Color::parse('#ffffff')->invert() // #000000 (white to black)
- Color::parse('#ff0000')->invert() // #00ffff (red to cyan)
- Color::parse('rgb(100 200 50)')->invert() // rgb(155 55 205)

Returns true if the color temperature is less than 0.

Inverse of isLight().

Returns true if the color temperature is greater than 0.

Returns true if the luminance is greater than or equal to 0.179.

Adjusts lightness in perceptually uniform Oklch space. Positive values lighten,
negative values darken. Values are clamped to keep lightness in valid range [0, 1].

Examples:
- Color::parse('red')->lighten(0.2) // Increase lightness by 20%
- Color::parse('blue')->lighten(0.5) // Increase lightness by 50%
- Color::parse('green')->lighten(-0.1) // Actually darkens by 10%

Performs hue rotation in perceptually uniform Oklch space, preserving lightness
and chroma while changing the hue. Positive values rotate clockwise on the color wheel,
negative values rotate counter-clockwise.

Examples:
- Color::parse('red')->rotateHue(120) // Shift to green region
- Color::parse('blue')->rotateHue(-60) // Shift toward purple
- Color::parse('green')->rotateHue(180) // Complementary color

Adjusts chroma in perceptually uniform Oklch space. Higher chroma values make colors
more vivid and saturated. Positive amounts increase saturation, negative amounts
decrease it (desaturate).

Examples:
- Color::parse('red')->saturate(0.1) // Make more saturated
- Color::parse('blue')->saturate(0.05) // Slightly more vivid
- Color::parse('green')->saturate(-0.1) // Actually desaturates

Creates a shade by mixing with pure black in perceptually uniform Oklab space.
The amount parameter controls the mixing ratio: 0 returns the original color,
1 returns black, 0.5 is an equal mix.

This is perceptually more accurate than simple darkening operations.

Examples:
- Color::parse('red')->shade(0.5) // 50% mix with black (dark red)
- Color::parse('yellow')->shade(0.8) // 80% mix with black (very dark yellow)

Returns three colors: this color plus the two colors adjacent to its complement.
This creates a harmonious scheme with strong visual contrast, similar to
complementary but with more nuance (at 150° and 210° from base).

Examples:
- Color::parse('red')->splitComplementary() // [red, cyan+30°, cyan-30°]
- Color::parse('#9b59b6')->splitComplementary() // Three harmonious colors

Returns a value from -1 (cool) to +1 (warm) based on the hue in perceptually
uniform Oklch space. Warm colors (reds, oranges, yellows) have positive values,
cool colors (cyans, blues) have negative values, and neutral colors (greens,
magentas) are near zero.

Temperature mapping:
- Red to Orange (0-90°): +1 to 0 (warm)
- Yellow to Cyan (90-180°): 0 to -1 (neutral to cool)
- Cyan to Blue (180-270°): -1 to 0 (cool)
- Blue to Red (270-360°): 0 to +1 (cool to warm)

Examples:
- Color::parse('red')->temperature() // ~1.0 (very warm)
- Color::parse('blue')->temperature() // ~-0.5 (cool)
- Color::parse('green')->temperature() // ~0.0 (neutral)

Returns four colors evenly spaced around the color wheel at 90° intervals.
Tetradic harmonies offer the most color variety while maintaining balance,
suitable for rich, complex designs.

Examples:
- Color::parse('red')->tetradic() // [red, orange-ish, cyan-ish, blue-ish]
- Color::parse('#e74c3c')->tetradic() // Four balanced colors

Creates a tint by mixing with pure white in perceptually uniform Oklab space.
The amount parameter controls the mixing ratio: 0 returns the original color,
1 returns white, 0.5 is an equal mix.

This is perceptually more accurate than simple lightening operations.

Examples:
- Color::parse('red')->tint(0.5) // 50% mix with white (light red/pink)
- Color::parse('blue')->tint(0.8) // 80% mix with white (very pale blue)

Accepts either a space name as a string (e.g., 'oklab', 'oklch', 'srgb') or a
ColorInterface instance to use as a template for the target space.

Examples:
- $color->to('oklab') // Convert to Oklab
- $color->to('oklch') // Convert to Oklch
- $color->to(new OklabColor(0, 0, 0)) // Convert using template instance

Supported space names: 'srgb', 'rgb', 'oklab', 'oklch', 'lab', 'lch',
'xyz', 'xyz-d65', 'display-p3', 'displayp3'

Returns a CSS-compatible color string. The output format depends on the space parameter:
- null (auto): Uses the most appropriate format for this color space
- 'srgb' or 'rgb': rgb() function
- 'hsl': hsl() function (for sRGB colors)
- 'color': color() function with explicit color space
- 'oklab', 'oklch', 'lab', 'lch': Respective CSS color functions

Examples:
- ->toCss() => 'rgb(255 0 0)' or 'oklab(0.628 0.225 0.126)'
- ->toCss('hsl') => 'hsl(0 100% 50%)'
- ->toCss('srgb') => 'rgb(255 0 0)'
- ->toCss('color') => 'color(srgb 1 0 0)'

Alpha channel is included in output when not fully opaque (< 1.0):
- 'rgb(255 0 0 / 0.5)' or 'oklab(0.628 0.225 0.126 / 0.8)'

Converts the color to sRGB (if necessary) and returns a hex color string.
Channel values are clamped to [0, 255] and rounded to integers.

Examples:
- ->toHex() => '#ff0000'
- ->toHex(true) => '#ff0000ff' (with alpha)
- ->toHex(false) => '#0099cc'

Convenience method for converting to sRGB, the most common color space for web use.
This method is used internally by many operations that need to work in sRGB space.

Concrete color implementations MUST call this method when
implementing __toString()

Returns three colors evenly spaced around the color wheel at 120° intervals.
Triadic harmonies are vibrant and balanced, offering strong visual contrast
while retaining color harmony.

Examples:
- Color::parse('red')->triadic() // [red, green-ish, blue-ish]
- Color::parse('#3498db')->triadic() // Three balanced colors

Returns null if parsing fails. When successful, returns an instance of this exact type.

Adjusts the hue to make the color appear warmer, shifting toward red and orange
tones in perceptually uniform Oklch space. The amount controls how much the
color shifts toward warm tones.

Examples:
- Color::parse('blue')->warm(0.5) // Shift blue toward purple/magenta
- Color::parse('green')->warm(0.8) // Shift green toward yellow-orange

Defines the alpha/opacity value of the color as a float in the range [0, 1],
where 0 is fully transparent and 1 is fully opaque.

Generic channel patching helper. Merges provided subset with current channels.