HSL Color Space

class Hsl {
  /** Hue angle in degrees (0-360, values outside range are valid) */
  h: number;
  /** Saturation level (0-1, values outside range are valid) */
  s: number;
  /** Lightness level (0-1, values outside range are valid) */
  l: number;
  /** Opacity/alpha channel (0-1) */
  opacity: number;
  
  constructor(h: number, s: number, l: number, opacity: number);
}

/**
 * Returns a brighter copy by increasing lightness
 * @param k - Brightening factor, defaults to 1/0.7 ≈ 1.43
 * @returns New HSL color instance
 */
brighter(k?: number): Hsl;

/**
 * Returns a darker copy by decreasing lightness
 * @param k - Darkening factor, defaults to 0.7  
 * @returns New HSL color instance
 */
darker(k?: number): Hsl;

import { hsl } from "d3-color";

const blue = hsl(240, 1, 0.5); // Pure blue

// Brightness adjustments affect lightness channel
const lighterBlue = blue.brighter();   // Increases lightness
const darkerBlue = blue.darker();      // Decreases lightness

// Custom brightness factors
const veryBright = blue.brighter(2);   // Much lighter
const subtle = blue.darker(0.9);       // Slightly darker

console.log(blue.l);         // 0.5 (original)
console.log(lighterBlue.l);  // ~0.71 (brighter)
console.log(darkerBlue.l);   // ~0.35 (darker)

/**
 * Converts HSL color to RGB color space
 * @returns New RGB color instance
 */
rgb(): Rgb;

import { hsl } from "d3-color";

const hslRed = hsl(0, 1, 0.5);        // Pure red in HSL
const rgbRed = hslRed.rgb();          // Convert to RGB

console.log(rgbRed.r, rgbRed.g, rgbRed.b); // 255, 0, 0

/**
 * Clamps HSL values to standard ranges
 * @returns New HSL color with clamped values
 */
clamp(): Hsl;

/**
 * Checks if color is displayable when converted to RGB
 * @returns True if RGB equivalent is displayable
 */
displayable(): boolean;

import { hsl } from "d3-color";

// Create HSL with out-of-range values
const invalidHsl = hsl(450, 1.5, -0.2, 2);

// Check displayability (checks RGB conversion)
console.log(invalidHsl.displayable()); // false

// Clamp to valid ranges
const validHsl = invalidHsl.clamp();
console.log(validHsl.h, validHsl.s, validHsl.l, validHsl.opacity);
// 90, 1, 0, 1 (hue wrapped, others clamped)

/**
 * Returns CSS hsl() or hsla() string representation
 * @returns HSL string like "hsl(240, 100%, 50%)" or "hsla(240, 100%, 50%, 0.8)"
 */
formatHsl(): string;

import { hsl } from "d3-color";

const blue = hsl(240, 1, 0.5);
const blueAlpha = hsl(240, 1, 0.5, 0.8);

console.log(blue.formatHsl());      // "hsl(240, 100%, 50%)"
console.log(blueAlpha.formatHsl()); // "hsla(240, 100%, 50%, 0.8)"

// Also available via toString()
console.log(blue.toString());       // "rgb(0, 0, 255)" (via RGB conversion)

/**
 * Creates a copy of this color with optional property overrides
 * @param values - Object with properties to override
 * @returns New HSL color instance  
 */
copy(values?: {h?: number, s?: number, l?: number, opacity?: number}): Hsl;

import { hsl } from "d3-color";

const blue = hsl(240, 1, 0.5);

// Hue variations (color wheel rotation)
const red = blue.copy({h: 0});        // Rotate to red
const green = blue.copy({h: 120});    // Rotate to green  
const cyan = blue.copy({h: 180});     // Rotate to cyan

// Saturation variations (intensity)
const grayBlue = blue.copy({s: 0.3}); // Desaturated
const vibrant = blue.copy({s: 1});    // Fully saturated

// Lightness variations (brightness)
const darkBlue = blue.copy({l: 0.2}); // Darker
const lightBlue = blue.copy({l: 0.8}); // Lighter

// Opacity variations
const transparent = blue.copy({opacity: 0.5});

/**
 * Returns 6-digit hexadecimal string (via RGB conversion)
 * @returns Hex string like "#0000ff"
 */
formatHex(): string;

/**
 * Returns CSS rgb() string (via RGB conversion)  
 * @returns RGB string like "rgb(0, 0, 255)"
 */
formatRgb(): string;

/**
 * Alias for formatRgb()
 * @returns RGB string representation
 */
toString(): string;

import { hsl } from "d3-color";

const purple = hsl(270, 1, 0.5);

// Multiple output formats available
console.log(purple.formatHsl()); // "hsl(270, 100%, 50%)"
console.log(purple.formatHex()); // "#8000ff" 
console.log(purple.formatRgb()); // "rgb(128, 0, 255)"
console.log(purple.toString());  // "rgb(128, 0, 255)"

import { hsl } from "d3-color";

const baseColor = hsl(200, 0.8, 0.5); // Bright blue

// Create color scheme variations
const complementary = baseColor.copy({h: baseColor.h + 180}); // Opposite hue
const analogous1 = baseColor.copy({h: baseColor.h + 30});     // Adjacent hue
const analogous2 = baseColor.copy({h: baseColor.h - 30});     // Adjacent hue

// Create tonal variations  
const tint = baseColor.copy({l: 0.7});    // Lighter (add white)
const shade = baseColor.copy({l: 0.3});   // Darker (add black)
const tone = baseColor.copy({s: 0.4});    // Less saturated (add gray)

// Create transparency variations
const colors = [0.2, 0.4, 0.6, 0.8, 1.0].map(opacity => 
  baseColor.copy({opacity})
);