@ariaui/color 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * A color in the OKLCH color space.
+ * - `l`: Lightness, 0–1 (0 = black, 1 = white)
+ * - `c`: Chroma, 0–~0.4 (0 = gray, higher = more saturated)
+ * - `h`: Hue, 0–360 degrees
+ * - `alpha`: Opacity, 0–1
+ */
+interface OklchColor {
+    readonly l: number;
+    readonly c: number;
+    readonly h: number;
+    readonly alpha: number;
+}
+/**
+ * A color in the OKLab color space (intermediate for conversions).
+ */
+interface OklabColor {
+    readonly L: number;
+    readonly a: number;
+    readonly b: number;
+    readonly alpha: number;
+}
+/**
+ * A color in the sRGB color space.
+ * - `r`, `g`, `b`: 0–1 range (not 0–255)
+ * - `alpha`: 0–1
+ */
+interface SrgbColor {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly alpha: number;
+}
+/** A CSS hex color string. */
+type HexString = `#${string}`;
+/** Semantic color mode. */
+type ColorMode = "light" | "dark";
+
+/**
+ * Parse an OKLCH channel string as used by `@ariaui/tokens` primitives.
+ *
+ * Accepts formats:
+ * - `"55.2% 0.014 286"`  (L with %)
+ * - `"0.552 0.014 286"`  (L as decimal)
+ * - `"55.2% 0.014 286 / 0.5"` (with alpha)
+ *
+ * @throws if the string cannot be parsed.
+ */
+declare function parseOklchChannels(channels: string): OklchColor;
+/**
+ * Parse an `oklch(...)` CSS function string.
+ *
+ * Accepts: `oklch(55.2% 0.014 286)`, `oklch(55.2% 0.014 286 / 0.5)`
+ */
+declare function parseOklchCss(css: string): OklchColor;
+/**
+ * Parse a hex color string.
+ *
+ * Accepts: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`
+ */
+declare function parseHex(hex: string): SrgbColor;
+/**
+ * Parse an `rgb(...)` or `rgba(...)` CSS function string.
+ *
+ * Accepts modern space-separated (`rgb(139 92 246)`, `rgb(139 92 246 / 0.5)`)
+ * and legacy comma-separated (`rgb(139, 92, 246)`, `rgba(139, 92, 246, 0.5)`).
+ */
+declare function parseRgb(css: string): SrgbColor;
+
+/** Convert OKLCH → OKLab */
+declare function oklchToOklab(c: OklchColor): OklabColor;
+/** Convert OKLab → OKLCH */
+declare function oklabToOklch(lab: OklabColor): OklchColor;
+/**
+ * Convert OKLCH → sRGB with CSS Color Level 4 gamut mapping.
+ * Out-of-gamut colors are mapped by reducing chroma while preserving
+ * lightness and hue, per the spec.
+ */
+declare function oklchToSrgb(color: OklchColor): SrgbColor;
+/**
+ * Convert sRGB → OKLCH.
+ */
+declare function srgbToOklch(color: SrgbColor): OklchColor;
+/**
+ * Convert sRGB → hex string.
+ * Values are clamped to [0, 255]. Alpha is included only if < 1.
+ */
+declare function srgbToHex(color: SrgbColor): HexString;
+/**
+ * Convert OKLCH → hex string (via sRGB with gamut mapping).
+ */
+declare function oklchToHex(color: OklchColor): HexString;
+/**
+ * Convert hex string → OKLCH.
+ */
+declare function hexToOklch(hex: string): OklchColor;
+
+/**
+ * Increase lightness by `amount` (0–1).
+ * `lighten(color, 0.1)` adds 0.1 to lightness (clamped to 1).
+ */
+declare function lighten(color: OklchColor, amount: number): OklchColor;
+/**
+ * Decrease lightness by `amount` (0–1).
+ * `darken(color, 0.1)` subtracts 0.1 from lightness (clamped to 0).
+ */
+declare function darken(color: OklchColor, amount: number): OklchColor;
+/**
+ * Increase chroma by `amount`.
+ * `saturate(color, 0.05)` adds 0.05 to chroma (clamped to 0).
+ */
+declare function saturate(color: OklchColor, amount: number): OklchColor;
+/**
+ * Decrease chroma by `amount`.
+ * `desaturate(color, 0.05)` subtracts 0.05 from chroma (clamped to 0).
+ */
+declare function desaturate(color: OklchColor, amount: number): OklchColor;
+/**
+ * Set the alpha channel.
+ */
+declare function setAlpha(color: OklchColor, alpha: number): OklchColor;
+/**
+ * Rotate the hue by `degrees`.
+ * `adjustHue(color, 30)` rotates hue by +30°.
+ */
+declare function adjustHue(color: OklchColor, degrees: number): OklchColor;
+/**
+ * Mix two OKLCH colors by linear interpolation.
+ *
+ * @param color1 - First color
+ * @param color2 - Second color
+ * @param ratio  - 0 = 100% color1, 1 = 100% color2 (default 0.5)
+ *
+ * Hue interpolation uses the shorter arc.
+ */
+declare function mix(color1: OklchColor, color2: OklchColor, ratio?: number): OklchColor;
+/**
+ * Create a complement (hue + 180°).
+ */
+declare function complement(color: OklchColor): OklchColor;
+/**
+ * Invert a color (flip lightness).
+ */
+declare function invert(color: OklchColor): OklchColor;
+/**
+ * Convert to grayscale (set chroma to 0).
+ */
+declare function grayscale(color: OklchColor): OklchColor;
+
+/**
+ * Calculate WCAG 2.1 contrast ratio between two colors.
+ * Returns a value between 1 and 21.
+ *
+ * Accepts either OKLCH or sRGB colors (OKLCH are converted via gamut mapping).
+ */
+declare function contrastRatio(fg: OklchColor | SrgbColor, bg: OklchColor | SrgbColor): number;
+/**
+ * Check if a fg/bg pair meets WCAG 2.1 AA contrast requirements.
+ *
+ * - Normal text: ratio ≥ 4.5
+ * - Large text (≥18pt or ≥14pt bold): ratio ≥ 3
+ */
+declare function meetsAA(fg: OklchColor | SrgbColor, bg: OklchColor | SrgbColor, size?: "normal" | "large"): boolean;
+/**
+ * Check if a fg/bg pair meets WCAG 2.1 AAA contrast requirements.
+ *
+ * - Normal text: ratio ≥ 7
+ * - Large text: ratio ≥ 4.5
+ */
+declare function meetsAAA(fg: OklchColor | SrgbColor, bg: OklchColor | SrgbColor, size?: "normal" | "large"): boolean;
+/**
+ * Suggest an accessible foreground color by adjusting lightness to meet
+ * the target contrast level against the given background.
+ *
+ * Tries darkening first, then lightening. Returns the closest accessible
+ * OklchColor, or the original if it already passes.
+ *
+ * @param fg - Foreground color to adjust (OKLCH)
+ * @param bg - Background color (OKLCH or sRGB)
+ * @param target - "AA" (4.5:1) or "AAA" (7:1), default "AA"
+ * @param size - "normal" or "large" text
+ */
+declare function suggestAccessible(fg: OklchColor, bg: OklchColor | SrgbColor, target?: "AA" | "AAA", size?: "normal" | "large"): OklchColor;
+
+/**
+ * Format an OKLCH color as a CSS `oklch()` string.
+ *
+ * @example toOklchString({ l: 0.552, c: 0.014, h: 286, alpha: 1 })
+ *          → "oklch(55.2% 0.014 286)"
+ */
+declare function toOklchString(color: OklchColor): string;
+/**
+ * Format an sRGB color as a CSS `rgb()` string (modern syntax).
+ *
+ * @example toRgbString({ r: 0.545, g: 0.361, b: 0.965, alpha: 1 })
+ *          → "rgb(139 92 246)"
+ */
+declare function toRgbString(color: SrgbColor): string;
+/**
+ * Format a color as a hex string.
+ * Accepts OKLCH (converts via gamut mapping) or sRGB.
+ */
+declare function toHexString(color: OklchColor | SrgbColor): HexString;
+/**
+ * Format an OKLCH color back to the bare channel string format
+ * used by `@ariaui/tokens` primitives: `"L% C H"`.
+ *
+ * @example toCssChannels({ l: 0.552, c: 0.014, h: 286, alpha: 1 })
+ *          → "55.2% 0.014 286"
+ */
+declare function toCssChannels(color: OklchColor): string;
+
+export { type ColorMode, type HexString, type OklabColor, type OklchColor, type SrgbColor, adjustHue, complement, contrastRatio, darken, desaturate, grayscale, hexToOklch, invert, lighten, meetsAA, meetsAAA, mix, oklabToOklch, oklchToHex, oklchToOklab, oklchToSrgb, parseHex, parseOklchChannels, parseOklchCss, parseRgb, saturate, setAlpha, srgbToHex, srgbToOklch, suggestAccessible, toCssChannels, toHexString, toOklchString, toRgbString };

package/dist/index.js

@@ -0,0 +1,62 @@
+import {
+  adjustHue,
+  complement,
+  contrastRatio,
+  darken,
+  desaturate,
+  grayscale,
+  hexToOklch,
+  invert,
+  lighten,
+  meetsAA,
+  meetsAAA,
+  mix,
+  oklabToOklch,
+  oklchToHex,
+  oklchToOklab,
+  oklchToSrgb,
+  parseHex,
+  parseOklchChannels,
+  parseOklchCss,
+  parseRgb,
+  saturate,
+  setAlpha,
+  srgbToHex,
+  srgbToOklch,
+  suggestAccessible,
+  toCssChannels,
+  toHexString,
+  toOklchString,
+  toRgbString
+} from "./chunk-3BGTZVEU.js";
+export {
+  adjustHue,
+  complement,
+  contrastRatio,
+  darken,
+  desaturate,
+  grayscale,
+  hexToOklch,
+  invert,
+  lighten,
+  meetsAA,
+  meetsAAA,
+  mix,
+  oklabToOklch,
+  oklchToHex,
+  oklchToOklab,
+  oklchToSrgb,
+  parseHex,
+  parseOklchChannels,
+  parseOklchCss,
+  parseRgb,
+  saturate,
+  setAlpha,
+  srgbToHex,
+  srgbToOklch,
+  suggestAccessible,
+  toCssChannels,
+  toHexString,
+  toOklchString,
+  toRgbString
+};