@ansh-ui/core 0.2.0

package/dist/color.cjs

@@ -0,0 +1,257 @@
+'use strict';
+
+var chunkGHBRGMSO_cjs = require('./chunk-GHBRGMSO.cjs');
+var chunk23GSSIMK_cjs = require('./chunk-23GSSIMK.cjs');
+require('./chunk-FNR35HTL.cjs');
+var chunkLGA3N3YJ_cjs = require('./chunk-LGA3N3YJ.cjs');
+require('./chunk-GJRIHN76.cjs');
+require('./chunk-ILKUL7GD.cjs');
+
+
+
+Object.defineProperty(exports, "checkContrast", {
+  enumerable: true,
+  get: function () { return chunkGHBRGMSO_cjs.checkContrast; }
+});
+Object.defineProperty(exports, "contrastRatio", {
+  enumerable: true,
+  get: function () { return chunkGHBRGMSO_cjs.contrastRatio; }
+});
+Object.defineProperty(exports, "ensureContrast", {
+  enumerable: true,
+  get: function () { return chunkGHBRGMSO_cjs.ensureContrast; }
+});
+Object.defineProperty(exports, "perceivedLightness", {
+  enumerable: true,
+  get: function () { return chunkGHBRGMSO_cjs.perceivedLightness; }
+});
+Object.defineProperty(exports, "pickReadable", {
+  enumerable: true,
+  get: function () { return chunkGHBRGMSO_cjs.pickReadable; }
+});
+Object.defineProperty(exports, "requiredRatio", {
+  enumerable: true,
+  get: function () { return chunkGHBRGMSO_cjs.requiredRatio; }
+});
+Object.defineProperty(exports, "worstContrast", {
+  enumerable: true,
+  get: function () { return chunkGHBRGMSO_cjs.worstContrast; }
+});
+Object.defineProperty(exports, "applyGradientStops", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.applyGradientStops; }
+});
+Object.defineProperty(exports, "blend", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.blend; }
+});
+Object.defineProperty(exports, "composite", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.composite; }
+});
+Object.defineProperty(exports, "createGradient", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.createGradient; }
+});
+Object.defineProperty(exports, "createScale", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.createScale; }
+});
+Object.defineProperty(exports, "expandPalette", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.expandPalette; }
+});
+Object.defineProperty(exports, "fadeBy", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.fadeBy; }
+});
+Object.defineProperty(exports, "fromUint32", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.fromUint32; }
+});
+Object.defineProperty(exports, "gamutError", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.gamutError; }
+});
+Object.defineProperty(exports, "gamutMapOklch", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.gamutMapOklch; }
+});
+Object.defineProperty(exports, "generatePalette", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.generatePalette; }
+});
+Object.defineProperty(exports, "harmony", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.harmony; }
+});
+Object.defineProperty(exports, "inSrgbGamut", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.inSrgbGamut; }
+});
+Object.defineProperty(exports, "invertForSurface", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.invertForSurface; }
+});
+Object.defineProperty(exports, "isGamutStable", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.isGamutStable; }
+});
+Object.defineProperty(exports, "lerpHue", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.lerpHue; }
+});
+Object.defineProperty(exports, "maxChroma", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.maxChroma; }
+});
+Object.defineProperty(exports, "mixColors", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.mixColors; }
+});
+Object.defineProperty(exports, "mixParsed", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.mixParsed; }
+});
+Object.defineProperty(exports, "oklchToRgbMapped", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.oklchToRgbMapped; }
+});
+Object.defineProperty(exports, "palettes", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.palettes; }
+});
+Object.defineProperty(exports, "resolvePalette", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.resolvePalette; }
+});
+Object.defineProperty(exports, "sortByLightness", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.sortByLightness; }
+});
+Object.defineProperty(exports, "toHex", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.toHex; }
+});
+Object.defineProperty(exports, "toHslString", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.toHslString; }
+});
+Object.defineProperty(exports, "toOklchString", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.toOklchString; }
+});
+Object.defineProperty(exports, "toRgbString", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.toRgbString; }
+});
+Object.defineProperty(exports, "toUint32", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.toUint32; }
+});
+Object.defineProperty(exports, "withAlpha", {
+  enumerable: true,
+  get: function () { return chunk23GSSIMK_cjs.withAlpha; }
+});
+Object.defineProperty(exports, "ColorParseError", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.ColorParseError; }
+});
+Object.defineProperty(exports, "clearColorCache", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.clearColorCache; }
+});
+Object.defineProperty(exports, "hslToRgb", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.hslToRgb; }
+});
+Object.defineProperty(exports, "hsvToRgb", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.hsvToRgb; }
+});
+Object.defineProperty(exports, "linearToOklab", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.linearToOklab; }
+});
+Object.defineProperty(exports, "linearToRgb", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.linearToRgb; }
+});
+Object.defineProperty(exports, "linearToSrgbChannel", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.linearToSrgbChannel; }
+});
+Object.defineProperty(exports, "listNamedColors", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.listNamedColors; }
+});
+Object.defineProperty(exports, "namedColorToHex", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.namedColorToHex; }
+});
+Object.defineProperty(exports, "oklabToLinear", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.oklabToLinear; }
+});
+Object.defineProperty(exports, "oklabToOklch", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.oklabToOklch; }
+});
+Object.defineProperty(exports, "oklabToRgb", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.oklabToRgb; }
+});
+Object.defineProperty(exports, "oklchToOklab", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.oklchToOklab; }
+});
+Object.defineProperty(exports, "oklchToRgb", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.oklchToRgb; }
+});
+Object.defineProperty(exports, "parseColor", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.parseColor; }
+});
+Object.defineProperty(exports, "relativeLuminance", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.relativeLuminance; }
+});
+Object.defineProperty(exports, "resolveComputed", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.resolveComputed; }
+});
+Object.defineProperty(exports, "resolveCssVariable", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.resolveCssVariable; }
+});
+Object.defineProperty(exports, "rgbToHsl", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.rgbToHsl; }
+});
+Object.defineProperty(exports, "rgbToHsv", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.rgbToHsv; }
+});
+Object.defineProperty(exports, "rgbToLinear", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.rgbToLinear; }
+});
+Object.defineProperty(exports, "rgbToOklab", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.rgbToOklab; }
+});
+Object.defineProperty(exports, "rgbToOklch", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.rgbToOklch; }
+});
+Object.defineProperty(exports, "srgbToLinearChannel", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.srgbToLinearChannel; }
+});
+Object.defineProperty(exports, "tryParseColor", {
+  enumerable: true,
+  get: function () { return chunkLGA3N3YJ_cjs.tryParseColor; }
+});
+//# sourceMappingURL=color.cjs.map
+//# sourceMappingURL=color.cjs.map

package/dist/color.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"color.cjs"}

package/dist/color.d.cts

@@ -0,0 +1,303 @@
+import { c as Hsl, R as Rgb, d as Hsv, L as LinearRgb, O as Oklab, f as Oklch, a as ColorInput, C as ColorSpace, e as HueDirection } from './palette-6HkVltYU.cjs';
+export { b as ColorScale, H as HarmonyKind, P as PaletteName, g as PaletteOptions, S as ScaleOptions, h as createScale, i as expandPalette, j as generatePalette, k as harmony, l as invertForSurface, p as palettes, r as resolvePalette, s as sortByLightness } from './palette-6HkVltYU.cjs';
+import { E as EasingInput } from './types-B1FLLf3-.cjs';
+
+/**
+ * Colour space conversions.
+ *
+ * Matrices for OKLab are Björn Ottosson's published values. They are reproduced to full
+ * precision deliberately — truncating them introduces a visible hue shift in saturated blues.
+ */
+/** Remove the sRGB gamma curve from a single channel. */
+declare function srgbToLinearChannel(c: number): number;
+/** Apply the sRGB gamma curve to a single channel. */
+declare function linearToSrgbChannel(c: number): number;
+declare function rgbToLinear(rgb: Rgb): LinearRgb;
+declare function linearToRgb(lin: LinearRgb): Rgb;
+declare function linearToOklab(lin: LinearRgb): Oklab;
+declare function oklabToLinear(lab: Oklab): LinearRgb;
+declare function rgbToOklab(rgb: Rgb): Oklab;
+/**
+ * OKLab → sRGB.
+ *
+ * The result may fall outside the sRGB gamut, in which case channels are simply clipped.
+ * Use {@link import('./gamut').gamutMapOklch} when you need a perceptually sensible
+ * in-gamut colour rather than a clipped one.
+ */
+declare function oklabToRgb(lab: Oklab): Rgb;
+declare function oklabToOklch(lab: Oklab): Oklch;
+declare function oklchToOklab(lch: Oklch): Oklab;
+declare function rgbToOklch(rgb: Rgb): Oklch;
+declare function oklchToRgb(lch: Oklch): Rgb;
+declare function rgbToHsl(rgb: Rgb): Hsl;
+declare function hslToRgb(hsl: Hsl): Rgb;
+declare function rgbToHsv(rgb: Rgb): Hsv;
+declare function hsvToRgb(hsv: Hsv): Rgb;
+/**
+ * Relative luminance per WCAG 2.x — the Y component of CIEXYZ from linear sRGB.
+ * This is the quantity contrast ratios are built from.
+ */
+declare function relativeLuminance(rgb: Rgb): number;
+
+declare class ColorParseError extends Error {
+    readonly input: string;
+    constructor(input: string);
+}
+/**
+ * Parse any accepted colour into {@link Rgb}.
+ *
+ * @throws {ColorParseError} on unparseable input. Ansh throws here rather than falling back
+ * to black: a silently-black gradient is far harder to debug than a thrown error pointing at
+ * the offending string, and colour props are validated at mount, not inside a frame loop.
+ */
+declare function parseColor(input: ColorInput): Rgb;
+/** Like {@link parseColor} but returns `null` instead of throwing. */
+declare function tryParseColor(input: ColorInput): Rgb | null;
+/**
+ * Resolve a colour the parser can't handle itself by asking the browser.
+ *
+ * Covers `var(--token)`, `currentcolor`, `color-mix()`, `lab()` and anything else CSS gains
+ * in future. We set the value on a detached element and read back the computed style — the
+ * browser normalises it to `rgb()`/`rgba()`, which we can then parse.
+ *
+ * Returns `null` during SSR, where there is no document to consult. Callers should keep the
+ * original string in that case and let CSS resolve it at paint time; only effects that need
+ * numeric colour access (canvas gradients) require a resolved value, and those run client-side.
+ */
+declare function resolveComputed(value: string): Rgb | null;
+/**
+ * Resolve a CSS custom property against a specific element's cascade.
+ *
+ * Needed because `var(--surface)` means different things inside a `.dark` subtree. Effects
+ * pass their own host element so themed colours resolve correctly.
+ */
+declare function resolveCssVariable(name: string, element?: Element | null): Rgb | null;
+/** Clear the parse cache. Exposed for tests and for theme switches that change `var()` output. */
+declare function clearColorCache(): void;
+
+/** `#rrggbb`, or `#rrggbbaa` when not fully opaque (or when `forceAlpha` is set). */
+declare function toHex(color: Rgb, forceAlpha?: boolean): string;
+/**
+ * `rgb(r g b)` / `rgb(r g b / a)`.
+ *
+ * Uses the legacy comma form because it is what every canvas implementation and every
+ * browser back to 2015 accepts; the space-separated form is newer than our support target.
+ */
+declare function toRgbString(color: Rgb): string;
+declare function toHslString(color: Rgb): string;
+/** `oklch(l% c h)` — the modern authoring form, and what the theme generator emits. */
+declare function toOklchString(color: Rgb): string;
+/**
+ * Pack into a 32-bit integer as `0xAABBGGRR`.
+ *
+ * This is the byte order a `Uint32Array` view over `ImageData` expects on little-endian
+ * machines, which is every platform we target. Effects that write pixels directly — the noise
+ * layer, the grain overlay — use this to fill a row with one store per pixel instead of four.
+ */
+declare function toUint32(color: Rgb): number;
+declare function fromUint32(packed: number): Rgb;
+/** Replace a colour's alpha, leaving its hue and lightness untouched. */
+declare function withAlpha(color: Rgb, alpha: number): Rgb;
+/** Scale a colour's existing alpha — useful for fading a whole palette at once. */
+declare function fadeBy(color: Rgb, factor: number): Rgb;
+
+/** Is this OKLCH colour displayable in sRGB? */
+declare function inSrgbGamut(lch: Oklch): boolean;
+/**
+ * Reduce chroma until the colour fits in sRGB, preserving lightness and hue.
+ *
+ * Returns the input unchanged when it is already in gamut, so this is safe to call
+ * unconditionally.
+ */
+declare function gamutMapOklch(lch: Oklch): Oklch;
+/**
+ * The maximum chroma sRGB can display at a given lightness and hue.
+ *
+ * This is what makes "vivid" palette generation possible: rather than picking an arbitrary
+ * chroma and hoping, you can ask for the most saturated colour available at each hue and get
+ * a palette with consistent, maximal punch.
+ */
+declare function maxChroma(l: number, h: number): number;
+/** Gamut-map, then convert to sRGB. The safe path from OKLCH to a displayable colour. */
+declare function oklchToRgbMapped(lch: Oklch): Rgb;
+/**
+ * How far outside sRGB a colour sits, as a rough distance in chroma units.
+ * `0` means in gamut. Used by the docs site to warn about unrenderable theme colours.
+ */
+declare function gamutError(lch: Oklch): number;
+/** Does this sRGB colour survive a round trip through OKLCH unchanged? Diagnostic helper. */
+declare function isGamutStable(rgb: Rgb): boolean;
+
+/**
+ * Colour interpolation and gradient construction.
+ *
+ * The default space is OKLab, and that default is load-bearing — but it is worth being precise
+ * about *when* it matters, because the difference is not uniform.
+ *
+ * **Where sRGB fails badly: opposing hues.** Interpolating `#0000ff → #ffff00` in sRGB passes
+ * through exactly `#808080` — a dead grey — because the channels cancel. In OKLab the same
+ * transition keeps measurable chroma the whole way across. Any gradient spanning more than about a
+ * quadrant of the hue circle hits some version of this.
+ *
+ * **Where sRGB merely differs: neighbouring hues.** For `#0275f4 → #9f0550` (blue to crimson,
+ * ~104° apart) sRGB actually produces a *more* saturated midpoint, because it cuts the chord
+ * straight through the colour solid. What it does not preserve is perceived *lightness* — the sRGB
+ * path dips darker in the middle, so the transition reads as uneven even though it is vivid. OKLab
+ * holds lightness steady, which is what makes a gradient feel smooth rather than lumpy.
+ *
+ * Use `oklch` when you want maximum vividness across distant hues; it travels the hue circle rather
+ * than cutting across it, keeping chroma high throughout.
+ */
+interface MixOptions {
+    /** Space to interpolate through. Default `'oklab'`. */
+    space?: ColorSpace;
+    /** Which way around the hue circle, for cylindrical spaces. Default `'shorter'`. */
+    hue?: HueDirection;
+    /**
+     * Gamut-map the result rather than clipping it.
+     *
+     * Slightly more expensive (a short binary search) but preserves hue and lightness for
+     * out-of-gamut intermediates. Default `true` for `oklch`, `false` otherwise — `oklch`
+     * interpolation is the one that routinely leaves the gamut.
+     */
+    gamutMap?: boolean;
+}
+/**
+ * Interpolate between two colours.
+ *
+ * `t` is clamped to `[0, 1]`. Alpha is always interpolated linearly, independent of space —
+ * premultiplying would darken transitions to transparent, which is almost never wanted for
+ * UI gradients.
+ */
+declare function mixColors(from: ColorInput, to: ColorInput, t: number, options?: MixOptions): Rgb;
+/** The allocation-light path used by gradients, which have already parsed their stops. */
+declare function mixParsed(a: Rgb, b: Rgb, t: number, options?: MixOptions): Rgb;
+/** Interpolate two hue angles, honouring the requested direction of travel. */
+declare function lerpHue(from: number, to: number, t: number, direction: HueDirection): number;
+interface GradientStop {
+    /** Position in `[0, 1]`. */
+    offset: number;
+    color: ColorInput;
+}
+interface GradientOptions extends MixOptions {
+    /**
+     * Easing applied to the position *within each segment*, not across the whole gradient.
+     *
+     * This is how you get a gradient that lingers near one colour: `easeInQuad` compresses
+     * the transition toward the end of each segment. Default linear.
+     */
+    easing?: EasingInput;
+}
+interface Gradient {
+    /** Colour at position `t` in `[0, 1]`. */
+    at(t: number): Rgb;
+    /** Colour at position `t`, formatted for `fillStyle`. */
+    cssAt(t: number): string;
+    /** Evenly sample the gradient into `count` colours. */
+    sample(count: number): Rgb[];
+    /** A `linear-gradient(...)` string with `count` stops, for CSS backgrounds. */
+    toCss(direction?: string, count?: number): string;
+    readonly stops: readonly GradientStop[];
+}
+/**
+ * Build a multi-stop gradient.
+ *
+ * Accepts either a flat list of colours (distributed evenly) or explicit stops. Any number of
+ * colours is supported — there is no cap, and no assumption of two.
+ */
+declare function createGradient(input: readonly ColorInput[] | readonly GradientStop[], options?: GradientOptions): Gradient;
+/**
+ * Apply the gradient's stops to a native canvas gradient object.
+ *
+ * We can't hand the canvas our stops directly — it would interpolate them in sRGB and undo
+ * the whole point. Instead we sample our own interpolation into `resolution` intermediate
+ * stops, so the browser only ever interpolates over tiny intervals where the space barely
+ * matters. 24 stops is visually indistinguishable from continuous.
+ */
+declare function applyGradientStops(target: CanvasGradient, gradient: Gradient, resolution?: number): CanvasGradient;
+/**
+ * Blend a colour toward another by a fixed amount, in a chosen space.
+ * Shorthand for the common "10% lighter" adjustment.
+ */
+declare function blend(base: ColorInput, over: ColorInput, amount?: number, space?: ColorSpace): Rgb;
+/**
+ * Composite `over` onto `base` using its alpha — the "source-over" Porter-Duff operator,
+ * evaluated in linear light so it matches what the GPU does.
+ */
+declare function composite(base: ColorInput, over: ColorInput): Rgb;
+
+/**
+ * Contrast and legibility.
+ *
+ * Animated backgrounds are the single most common way a design ends up failing WCAG: the text
+ * was legible against the mockup's midpoint and illegible against the animation's brightest
+ * frame. These helpers let components check contrast against the *extremes* of their own
+ * palette and adapt, rather than hoping.
+ */
+type WcagLevel = 'AA' | 'AAA';
+type TextSize = 'normal' | 'large';
+/**
+ * WCAG 2.x contrast ratio, from 1 (identical) to 21 (black on white).
+ *
+ * Semi-transparent colours are composited over `background` first, because a ratio computed
+ * from a colour's own alpha is meaningless — what matters is what the eye actually receives.
+ */
+declare function contrastRatio(foreground: ColorInput, background: ColorInput): number;
+/** Minimum ratio required by WCAG 2.2 for the given level and text size. */
+declare function requiredRatio(level: WcagLevel, size: TextSize): number;
+interface ContrastResult {
+    ratio: number;
+    passes: boolean;
+    required: number;
+    level: WcagLevel;
+    size: TextSize;
+}
+/** Check a foreground/background pair against a WCAG threshold. */
+declare function checkContrast(foreground: ColorInput, background: ColorInput, level?: WcagLevel, size?: TextSize): ContrastResult;
+/**
+ * Pick whichever of `light`/`dark` reads better on `background`.
+ *
+ * This is the function to reach for when a component renders text over a user-supplied
+ * colour, which is most of them.
+ */
+declare function pickReadable(background: ColorInput, light?: ColorInput, dark?: ColorInput): Rgb;
+/**
+ * Adjust a colour's lightness until it meets a contrast target against `background`.
+ *
+ * Works in OKLCH so hue and chroma survive the adjustment — the brand colour stays
+ * recognisably itself, it just gets light or dark enough to read. Searches in whichever
+ * direction has more headroom, and returns the best achievable colour if the target is
+ * unreachable (a mid-grey background cannot support 7:1 with a saturated hue at any lightness).
+ */
+declare function ensureContrast(foreground: ColorInput, background: ColorInput, target?: number): {
+    color: Rgb;
+    ratio: number;
+    achieved: boolean;
+};
+/**
+ * Worst-case contrast of a foreground against every colour in a set.
+ *
+ * An animated gradient background cycles through many colours; text must be legible against
+ * all of them. Components call this with their resolved palette and surface a dev warning when
+ * it fails, which turns an invisible accessibility bug into a console message during development.
+ */
+declare function worstContrast(foreground: ColorInput, backgrounds: readonly ColorInput[]): {
+    ratio: number;
+    against: Rgb | null;
+};
+/**
+ * APCA-style perceptual lightness, used for ordering colours by visual weight.
+ *
+ * Not a WCAG 3 implementation — that specification is still in flux and we won't ship a
+ * moving target as if it were stable. This is OKLab's `L`, which is a better predictor of
+ * perceived lightness than WCAG's relative luminance and is entirely sufficient for the
+ * internal job of sorting a palette light-to-dark.
+ */
+declare function perceivedLightness(color: ColorInput): number;
+
+/** Resolve a CSS colour keyword to its hex value, or `undefined` if it isn't one. */
+declare function namedColorToHex(name: string): string | undefined;
+/** Every recognised colour keyword. Powers autocomplete in the docs playground. */
+declare function listNamedColors(): string[];
+
+export { ColorInput, ColorParseError, ColorSpace, type ContrastResult, type Gradient, type GradientOptions, type GradientStop, Hsl, Hsv, HueDirection, LinearRgb, type MixOptions, Oklab, Oklch, Rgb, type TextSize, type WcagLevel, applyGradientStops, blend, checkContrast, clearColorCache, composite, contrastRatio, createGradient, ensureContrast, fadeBy, fromUint32, gamutError, gamutMapOklch, hslToRgb, hsvToRgb, inSrgbGamut, isGamutStable, lerpHue, linearToOklab, linearToRgb, linearToSrgbChannel, listNamedColors, maxChroma, mixColors, mixParsed, namedColorToHex, oklabToLinear, oklabToOklch, oklabToRgb, oklchToOklab, oklchToRgb, oklchToRgbMapped, parseColor, perceivedLightness, pickReadable, relativeLuminance, requiredRatio, resolveComputed, resolveCssVariable, rgbToHsl, rgbToHsv, rgbToLinear, rgbToOklab, rgbToOklch, srgbToLinearChannel, toHex, toHslString, toOklchString, toRgbString, toUint32, tryParseColor, withAlpha, worstContrast };