CIELAB Color Space

/**
 * Creates Lab color from numeric values
 * @param l - Lightness (typically 0-100, values outside range are valid)
 * @param a - Green-red axis (typically -160 to +160)
 * @param b - Blue-yellow axis (typically -160 to +160)
 * @param opacity - Alpha channel (0-1), defaults to 1
 * @returns Lab color object
 */
function lab(l: number, a: number, b: number, opacity?: number): Lab;

/**
 * Creates Lab color from CSS color string
 * @param specifier - CSS color string
 * @returns Lab color object
 */
function lab(specifier: string): Lab;

/**
 * Converts any color object to Lab
 * @param color - Color object to convert
 * @returns Lab color object
 */
function lab(color: Color): Lab;

import { lab, rgb } from "d3-color";

// Direct Lab construction
const white = lab(100, 0, 0);        // Pure white
const black = lab(0, 0, 0);          // Pure black
const red = lab(53, 80, 67);         // Approximate red
const green = lab(46, -51, 49);      // Approximate green

// Convert from other formats
const blue = lab("blue");            // From named color
const yellow = lab("#ffff00");       // From hex
const rgbColor = rgb(128, 64, 192);
const labColor = lab(rgbColor);      // RGB to Lab conversion

/**
 * Creates a grayscale Lab color with a=0, b=0
 * @param l - Lightness value (typically 0-100)  
 * @param opacity - Alpha channel (0-1), defaults to 1
 * @returns Lab color object with no chroma
 */
function gray(l: number, opacity?: number): Lab;

import { gray } from "d3-color";

// Create grayscale colors
const black = gray(0);          // Pure black
const darkGray = gray(25);      // Dark gray  
const mediumGray = gray(50);    // Medium gray
const lightGray = gray(75);     // Light gray
const white = gray(100);        // Pure white

// With transparency
const semiTransparentGray = gray(50, 0.5);

// Convert to other formats
console.log(mediumGray.formatHex());  // "#777777" (approximately)
console.log(lightGray.formatRgb());   // "rgb(191, 191, 191)" (approximately)

class Lab {
  /** Lightness (0=black, 100=white, values outside range are valid) */
  l: number;
  /** Green-red axis (negative=green, positive=red) */
  a: number;
  /** Blue-yellow axis (negative=blue, positive=yellow) */
  b: number;
  /** Opacity/alpha channel (0-1) */
  opacity: number;
  
  constructor(l: number, a: number, b: number, opacity: number);
  
  brighter(k?: number): Lab;
  darker(k?: number): Lab;
  rgb(): Rgb;
  displayable(): boolean;
  copy(values?: object): Lab;
  formatHex(): string;
  formatHex8(): string;
  formatRgb(): string;
  formatHsl(): string;
  toString(): string;
}

/**
 * Returns a brighter copy by increasing L* channel
 * @param k - Brightening factor, defaults to 1
 * @returns New Lab color instance
 */
brighter(k?: number): Lab;

/**
 * Returns a darker copy by decreasing L* channel  
 * @param k - Darkening factor, defaults to 1
 * @returns New Lab color instance
 */
darker(k?: number): Lab;

import { lab } from "d3-color";

const blue = lab(32, 79, -108);     // A blue color

// Perceptually uniform brightness adjustments
const lighterBlue = blue.brighter();     // L* + 18
const darkerBlue = blue.darker();        // L* - 18

// Custom brightness steps
const muchBrighter = blue.brighter(2);   // L* + 36
const slightlyDarker = blue.darker(0.5); // L* - 9

console.log(blue.l);           // 32 (original)
console.log(lighterBlue.l);    // 50 (brighter)
console.log(darkerBlue.l);     // 14 (darker)

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

import { lab } from "d3-color";

const labRed = lab(53, 80, 67);     // Red in Lab space
const rgbRed = labRed.rgb();        // Convert to RGB

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

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

import { lab } from "d3-color";

const baseColor = lab(50, 20, 30);

// Lightness variations (perceptually uniform)
const lighter = baseColor.copy({l: 70});   // Brighter
const darker = baseColor.copy({l: 30});    // Darker

// Chroma variations (color intensity)
const moreVibrant = baseColor.copy({a: 40, b: 60});  // More colorful
const lessVibrant = baseColor.copy({a: 10, b: 15});  // Less colorful
const neutral = baseColor.copy({a: 0, b: 0});        // Grayscale

// Hue shifts (by adjusting a/b relationship)
const shifted = baseColor.copy({a: -20, b: 30});     // Different hue

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

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

/**
 * Returns CSS hsl() string (via RGB conversion)
 * @returns HSL string like "hsl(0, 100%, 50%)"
 */
formatHsl(): string;

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

import { lab } from "d3-color";

const labColor = lab(53, 80, 67);   // Red-ish in Lab

// All output formats available via conversion
console.log(labColor.formatHex());  // "#ff0000" (approximately)
console.log(labColor.formatRgb());  // "rgb(255, 0, 0)" (approximately)
console.log(labColor.formatHsl());  // "hsl(0, 100%, 50%)" (approximately)
console.log(labColor.toString());   // "rgb(255, 0, 0)" (approximately)

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

import { lab } from "d3-color";

const normalLab = lab(50, 20, 30);     // Typical Lab color
const extremeLab = lab(50, 200, 200);  // Very saturated, might be out of RGB gamut

console.log(normalLab.displayable());  // true (likely)
console.log(extremeLab.displayable()); // false (likely, depends on exact values)

// If not displayable, RGB conversion will clamp values
const rgbExtreme = extremeLab.rgb();
console.log(rgbExtreme.displayable()); // true (clamped to valid RGB)

import { lab, gray } from "d3-color";

// Create perceptually uniform color scales
const startColor = lab(20, 30, 40);   // Dark color
const endColor = lab(80, 30, 40);     // Light color with same chroma

// Interpolate lightness for uniform brightness steps
const steps = [];
for (let i = 0; i <= 10; i++) {
  const t = i / 10;
  const l = startColor.l + (endColor.l - startColor.l) * t;
  steps.push(startColor.copy({l}));
}

// Create achromatic (grayscale) versions
const colorful = lab(50, 40, 30);
const grayscale = gray(colorful.l);    // Same lightness, no chroma

// Analyze color properties
console.log("Lightness:", colorful.l);
console.log("Chroma:", Math.sqrt(colorful.a ** 2 + colorful.b ** 2));
console.log("Hue angle:", Math.atan2(colorful.b, colorful.a) * 180 / Math.PI);