/* @ts-self-types="./manipulation.d.ts" */ import { Color, ColorFormat } from "./types.js"; /** * Like {@link parseColor} but returns `undefined` instead of throwing for invalid input. * * @example * ```ts * tryParseColor("#3264C8") // Color * tryParseColor("nope") // undefined * ``` */ export declare function tryParseColor(value: string): Color | undefined; /** * Returns `true` if `value` is a parseable color string. * * @example * ```ts * isValidColor("#3264C8") // true * isValidColor("nope") // false * ``` */ export declare function isValidColor(value: string): boolean; /** * Detects the format of a color string without parsing it. * Returns `undefined` for strings that do not match any known format. * * The returned format reflects the **syntax** of the string (e.g. `"rgb"` for * `rgb(...)` even if an alpha channel is present via slash notation). * * @example * ```ts * detectColorFormat("#3264C8") // "hex" * detectColorFormat("#3264C8FF") // "hexa" * detectColorFormat("rgb(50, 100, 200)") // "rgb" * detectColorFormat("hsla(220, 60%, 49%, 0.5)") // "hsla" * detectColorFormat("nope") // undefined * ``` */ export declare function detectColorFormat(value: string): ColorFormat | undefined; /** * Returns a new color with lightness increased by `amount` (0–1 ratio = percentage points). * Operates in HSL space; the returned color is in HSL. * * @example * ```ts * lighten(parseColor("hsl(220, 60%, 50%)"), 0.1).getChannelValue("lightness") // 60 * ``` */ export declare function lighten(color: Color, amount: number): Color; /** * Returns a new color with lightness decreased by `amount` (0–1 ratio = percentage points). * Operates in HSL space; the returned color is in HSL. */ export declare function darken(color: Color, amount: number): Color; /** * Returns a new color with saturation increased by `amount` (0–1 ratio = percentage points). * Operates in HSL space; the returned color is in HSL. */ export declare function saturate(color: Color, amount: number): Color; /** * Returns a new color with saturation decreased by `amount` (0–1 ratio = percentage points). * Operates in HSL space; the returned color is in HSL. */ export declare function desaturate(color: Color, amount: number): Color; /** * Returns the complementary color (hue rotated 180°), preserving saturation, lightness, and alpha. * The returned color is in HSL. * * @example * ```ts * complement(parseColor("hsl(60, 50%, 50%)")).getChannelValue("hue") // 240 * ``` */ export declare function complement(color: Color): Color; /** * Mixes two colors in RGB space at the given `ratio` (0 = fully `a`, 1 = fully `b`). * Alpha is also interpolated. The returned color is in RGB. * * @example * ```ts * mix(parseColor("#000000"), parseColor("#ffffff")).toString("hex") // "#808080" * mix(parseColor("#000000"), parseColor("#ffffff"), 0.25).toString("hex") // "#404040" * ``` */ export declare function mix(a: Color, b: Color, ratio?: number): Color; /** * Returns the WCAG 2.1 contrast ratio between two colors (1–21). * The order of arguments does not matter. * * - Black on white: `21` * - Same color: `1` * * @example * ```ts * contrastRatio(parseColor("#000"), parseColor("#fff")) // 21 * ``` */ export declare function contrastRatio(a: Color, b: Color): number; /** * Returns whether the contrast between `foreground` and `background` meets the * specified WCAG 2.1 conformance level and text size. * * | Level | Normal text | Large text (≥18pt / ≥14pt bold) | * |-------|-------------|----------------------------------| * | AA | 4.5 : 1 | 3 : 1 | * | AAA | 7 : 1 | 4.5 : 1 | * * @example * ```ts * isReadable(parseColor("#fff"), parseColor("#000")) // true (AA, normal) * isReadable(parseColor("#fff"), parseColor("#000"), "AAA") // true * isReadable(parseColor("#777"), parseColor("#fff"), "AAA") // false * ``` */ export declare function isReadable(foreground: Color, background: Color, level?: "AA" | "AAA", size?: "normal" | "large"): boolean; /** * Returns an array of `steps` colors linearly interpolated in RGB space between * `from` and `to`. The first element is `from`, the last is `to`. * * @throws if `steps` is not a finite integer >= 2. * * @example * ```ts * colorScale(parseColor("#000"), parseColor("#fff"), 3) * // [#000000, #808080, #FFFFFF] * ``` */ export declare function colorScale(from: Color, to: Color, steps: number): Color[]; /** * Returns an array of `steps` colors interpolated in OKLCH space between `from` and `to`. * OKLCH is a perceptually uniform color space, so the steps appear more evenly distributed * to the human eye than a plain RGB scale. * * Hue interpolation takes the shortest arc around the color wheel. * Alpha is linearly interpolated. The returned colors are in RGB. * * @throws if `steps` is not a finite integer >= 2. * * @example * ```ts * // A scale from red to blue that passes through purple rather than through green * perceptualColorScale(parseColor("hsl(0, 80%, 50%)"), parseColor("hsl(240, 80%, 50%)"), 5) * ``` */ export declare function perceptualColorScale(from: Color, to: Color, steps: number): Color[];