color-value-tools 1.1.0 → 1.1.1

package/README.md

@@ -56,22 +56,29 @@ const { normalizeColor, mixColors } = require('color-value-tools');
 
 | Function | Description |
 |---|---|
-| `getColorType(value)` | Returns `'hex'`, `'css-var'`, `'rgb'`, `'hsl'`, `'named'`, or `'unknown'` |
-| `isHexColor(value)` | Detects 3- or 6-digit hex strings (with or without `#`) |
+| `getColorType(value)` | Returns `'hex'` \| `'css-var'` \| `'rgb'` \| `'hsl'` \| `'named'` \| `'oklch'` \| `'color'` \| `'unknown'` |
+| `isHexColor(value)` | Detects 3-, 4-, 6- or 8-digit hex strings (with or without `#`) |
 | `isRgbColor(value)` | Detects `rgb()` / `rgba()` strings |
 | `isHslColor(value)` | Detects `hsl()` / `hsla()` strings |
+| `isOklchColor(value)` | Detects `oklch()` / `oklcha()` strings |
+| `isColorFunction(value)` | Detects `color(display-p3 ...)` / `color(srgb ...)` strings |
 | `isCssVariable(value)` | Checks for `var(--name)` pattern |
-| `extractCssVariableName(value)` | Extracts `--name` from `var(--name)` |
+| `extractCssVariableName(value)` | Extracts `--name` from `var(--name, fallback)` |
 
 ### Parsing & Normalization
 
 | Function | Description |
 |---|---|
-| `normalizeColor(input)` | Universal parser. Accepts hex string, `rgb()`, `hsl()`, named color, or `{r,g,b}` / `{h,s,l}` object. Returns `{ type, hex, r, g, b, a, h, s, l, v }` |
+| `normalizeColor(input)` | Universal parser. Accepts hex, `rgb()`, `hsl()`, `oklch()`, `color()`, named color, `{r,g,b}` / `{h,s,l}`. Returns `{ type, hex, r, g, b, a, h, s, l, v }` |
+| `normalizeColorCached(input)` | Same as `normalizeColor` but uses an internal LRU-style cache |
 | `normalizeHex(hex)` | Normalizes 3- or 6-digit hex to lowercase 6-digit with `#` |
 | `rgbaStringToRgba(str)` | Parses `rgb()` / `rgba()` string to `{r, g, b, a}` |
 | `hex8ToRgba(hex)` | Parses 8-digit hex (`#rrggbbaa`) to `{r, g, b, a}` |
+| `shortHexToRgba(hex)` | Parses 4-digit hex (`#rgba`) to `{r, g, b, a}` — e.g. `#f0f0` → `{r:255,g:0,b:255,a:0}` |
 | `parseHwbString(str)` | Parses `hwb()` string to `{H, W, B, alpha}` |
+| `parseOklchString(str)` | Parses `oklch(L C H / alpha)` to `{L, C, H, alpha}` |
+| `parseColorFn(str)` | Parses `color(display-p3 r g b / alpha)` to `{space, r, g, b, alpha}` |
+| `parseCssVar(value)` | Parses `var(--name, fallback)` to `{variableName, fallback?}` |
 
 ### Conversions
 
@@ -102,40 +109,54 @@ const { normalizeColor, mixColors } = require('color-value-tools');
 | `oklabToRgb({L,a,b})` | `→ {r, g, b}` |
 | `rgbToOklch({r,g,b})` | `→ {L, C, H}` (Oklch) |
 | `oklchToRgb({L,C,H})` | `→ {r, g, b}` |
+| `rgbToDisplayP3({r,g,b})` | `→ {r, g, b}` in Display P3 space (0–1 per channel) |
+| `displayP3ToRgb({r,g,b})` | `→ {r, g, b}` sRGB (0–255) |
+| `toDisplayP3Hex(color)` | Converts any color → Display P3 → hex |
 | `rgbaToHex8({r,g,b,a})` | Alias for `rgbaToHex` |
 
 ### Manipulation
 
 | Function | Description |
 |---|---|
-| `lighten(color, amount)` | Increase lightness by `amount` (0–100) |
-| `darken(color, amount)` | Decrease lightness by `amount` (0–100) |
-| `saturate(color, amount)` | Increase saturation by `amount` (0–100) |
-| `desaturate(color, amount)` | Decrease saturation by `amount` (0–100) |
+| `lighten(color, amount)` | Increase HSL lightness by `amount` (0–100) |
+| `darken(color, amount)` | Decrease HSL lightness by `amount` (0–100) |
+| `saturate(color, amount)` | Increase HSL saturation by `amount` (0–100) |
+| `desaturate(color, amount)` | Decrease HSL saturation by `amount` (0–100) |
 | `setAlpha(color, alpha)` | Returns `rgba(...)` with the given alpha (0–1) |
 | `getAlpha(color)` | Returns the alpha channel value (0–1) |
 | `invertColor(color)` | Inverts RGB channels |
 | `grayscale(color)` | Converts to grayscale using ITU-R BT.709 weights |
 | `rotateHue(hex, degrees)` | Rotates hue by degrees (supports negative values) |
 | `adjustHexBrightness(hex, offsetPercent)` | Lightens (positive) or darkens (negative) by percentage |
-| `mixColors(c1, c2, t, opts?)` | Linearly interpolates between two colors. `t` = 0–1. Options: `mode: 'rgb'|'hsl'`, `format: 'hex'|'rgb'|'rgba'|'hsl'` |
+| `mixColors(c1, c2, t, opts?)` | Interpolates between two colors. `t` = 0–1. `mode`: `'rgb'`\|`'hsl'`\|`'lab'`\|`'lch'`\|`'oklab'`\|`'oklch'`. `hueInterpolation`: `'shorter'`\|`'longer'`\|`'increasing'`\|`'decreasing'` |
+
+### Interpolation & Scales
+
+| Function | Description |
+|---|---|
+| `interpolateColors(c1, c2, steps, opts?)` | Returns array of `steps` colors from `c1` to `c2`. Same `space`/`format`/`hueInterpolation` options as `mixColors` |
+| `createColorScale(anchors, steps, opts?)` | Generates a `steps`-color scale across multiple anchor colors with optional positions (0–1) |
+| `midpointColor(c1, c2, opts?)` | Perceptual midpoint between two colors (default space: `'oklab'`) |
 
 ### Color Harmonies
 
 | Function | Description |
 |---|---|
-| `complement(color)` | Returns the complementary color (180° rotation) |
-| `triadic(color)` | Returns 3 colors evenly spaced 120° apart |
-| `analogous(color, angle?)` | Returns 3 neighboring colors (default ±30°) |
-| `splitComplementary(color)` | Returns the base + two colors at 150° and 210° |
-| `tetradic(color)` | Returns 4 colors evenly spaced 90° apart |
+| `complement(color)` | Complementary color (180° rotation) |
+| `triadic(color)` | 3 colors evenly spaced 120° apart |
+| `analogous(color, angle?)` | 3 neighboring colors (default ±30°) |
+| `splitComplementary(color)` | Base + two colors at 150° and 210° |
+| `tetradic(color)` | 4 colors evenly spaced 90° apart |
 
 ### Palette Generation
 
 | Function | Description |
 |---|---|
-| `colorShades(color, steps?)` | Generates a light-to-dark scale (default 9 steps) |
-| `monochromatic(color, steps?)` | Generates shades by varying saturation (default 5 steps) |
+| `colorShades(color, steps?)` | Light-to-dark HSL scale (default 9 steps) |
+| `monochromatic(color, steps?)` | Varying saturation at fixed lightness (default 5 steps) |
+| `tints(color, steps?)` | Mix toward white in Oklab (default 5 steps) |
+| `shades(color, steps?)` | Mix toward black in Oklab (default 5 steps) |
+| `tones(color, steps?, gray?)` | Mix toward gray in Oklab (default 5 steps, gray `#808080`) |
 
 ### Accessibility (WCAG)
 
@@ -143,18 +164,52 @@ const { normalizeColor, mixColors } = require('color-value-tools');
 |---|---|
 | `relativeLuminance(color)` | WCAG relative luminance (0–1) |
 | `contrastRatio(c1, c2)` | WCAG contrast ratio (1–21) |
-| `wcagLevel(fg, bg)` | Returns `'AAA'`, `'AA'`, `'AA-large'`, or `'fail'` |
+| `wcagLevel(fg, bg)` | Returns `'AAA'` \| `'AA'` \| `'AA-large'` \| `'fail'` |
 | `bestTextColor(bg)` | Returns `'#000000'` or `'#ffffff'` for best contrast on `bg` |
-| `bestContrastColor(bg, candidates)` | Picks the most readable color from `candidates` |
+| `bestContrastColor(bg, candidates)` | Picks the most readable color from an array of candidates |
+| `bestContrastPalette(bg, palettes, opts?)` | Picks the palette with best overall contrast. Returns `{paletteIndex, palette, minContrastRatio, avgContrastRatio}` |
+| `isReadableOnBackground(text, bg, opts?)` | Checks readability on solid, semi-transparent, or gradient backgrounds. Returns `{readable, minContrastRatio, wcagLevel}` |
 | `isDark(color, threshold?)` | `true` if luminance is below threshold (default 0.5) |
 | `isLight(color, threshold?)` | Inverse of `isDark` |
 
+### Color Blindness Simulation
+
+Simulates perception using Vienot 1999 matrices applied to linear RGB.
+
+| Function | Description |
+|---|---|
+| `simulateProtanopia(color)` | No L-cones (red-blind) |
+| `simulateDeuteranopia(color)` | No M-cones (green-blind) |
+| `simulateTritanopia(color)` | No S-cones (blue-blind) |
+| `simulateColorBlindness(color, type)` | Generic — `type`: `'protanopia'` \| `'deuteranopia'` \| `'tritanopia'` |
+
 ### Formatting
 
 | Function | Description |
 |---|---|
 | `toHslString(h, s, l, alpha?)` | Formats as `hsl(...)` or `hsla(...)` |
 | `toHwbString(H, W, B, alpha?)` | Formats as `hwb(...)` with optional alpha |
+| `toOklchString(color, alpha?)` | Converts any color to `oklch(L C H)` CSS string |
+| `toColorP3String(color, alpha?)` | Converts any color to `color(display-p3 r g b)` CSS string |
+
+### Cache Management
+
+| Function | Description |
+|---|---|
+| `normalizeColorCached(input)` | Cached version of `normalizeColor` for repeated calls |
+| `clearColorCache()` | Clears the normalization cache |
+| `getCacheStats()` | Returns `{size, hits}` |
+| `enableCache()` / `disableCache()` | Toggle caching on/off |
+
+### Generator Functions
+
+Useful for large palettes and frame-by-frame animations without allocating full arrays.
+
+| Function | Description |
+|---|---|
+| `generateGradientColors*(start, end, steps, opts?)` | Yields `steps` colors from `start` to `end` |
+| `generateTints*(color, steps, opts?)` | Yields tints toward white |
+| `generateShades*(color, steps, opts?)` | Yields shades toward black |
 
 ### Utilities
 
@@ -166,6 +221,115 @@ const { normalizeColor, mixColors } = require('color-value-tools');
 
 ---
 
+## CLI
+
+After installing globally or via `npx`, you can inspect colors directly from the terminal:
+
+```bash
+npm install -g color-value-tools
+```
+
+```bash
+# Full info (default)
+cvt "#3498db"
+
+# All format conversions
+cvt "#3498db" convert
+
+# Contrast ratio and WCAG level
+cvt "#3498db" contrast "#ffffff"
+
+# Generate 7 shades
+cvt "#3498db" shades 7
+
+# All harmonies
+cvt "#3498db" harmonies
+
+# Nearest CSS named color
+cvt "cornflowerblue" nearest
+```
+
+---
+
+## Cookbook
+
+### Generate an accessible button palette
+
+```ts
+import { colorShades, bestTextColor, wcagLevel } from 'color-value-tools';
+
+function buttonPalette(base: string) {
+  const shades = colorShades(base, 9);
+  return shades.map(shade => ({
+    bg: shade,
+    text: bestTextColor(shade),
+    wcag: wcagLevel(bestTextColor(shade), shade),
+  }));
+}
+
+buttonPalette('#3498db');
+// [{ bg: '#ffffff', text: '#000000', wcag: 'AAA' }, ...]
+```
+
+### Theme-aware dark/light color
+
+```ts
+import { isDark, lighten, darken } from 'color-value-tools';
+
+function adaptToTheme(color: string, isDarkTheme: boolean): string {
+  return isDarkTheme ? lighten(color, 20) : darken(color, 10);
+}
+```
+
+### Mix two brand colors at a midpoint
+
+```ts
+import { mixColors } from 'color-value-tools';
+
+const mid = mixColors('#e74c3c', '#3498db', 0.5, { mode: 'hsl', format: 'hex' });
+// Perceptually even blend between red and blue
+```
+
+### Build a triadic color scheme and check contrast
+
+```ts
+import { triadic, contrastRatio } from 'color-value-tools';
+
+const [base, second, third] = triadic('#6c3483');
+console.log(contrastRatio(base, '#ffffff')); // e.g. 8.4
+console.log(contrastRatio(second, '#ffffff'));
+```
+
+### Convert a CSS color string to all formats at once
+
+```ts
+import { normalizeColor, rgbToOklch, rgbToCmyk } from 'color-value-tools';
+
+const n = normalizeColor('hsl(204, 70%, 53%)');
+const oklch = rgbToOklch({ r: n.r!, g: n.g!, b: n.b! });
+const cmyk  = rgbToCmyk({ r: n.r!, g: n.g!, b: n.b! });
+console.log(n.hex, oklch, cmyk);
+```
+
+### Find the perceptually nearest named CSS color
+
+```ts
+import { toNearestNamedColor } from 'color-value-tools';
+
+toNearestNamedColor('#1a8ccc'); // 'steelblue'
+```
+
+### Random palette within a hue range
+
+```ts
+import { randomColor, colorShades } from 'color-value-tools';
+
+const accent = randomColor({ hRange: [200, 260], sRange: [60, 80], lRange: [40, 60] });
+const palette = colorShades(accent, 5);
+```
+
+---
+
 ## Author
 
 Danil Lisin Vladimirovich aka Macrulez

package/dist/cjs/index.d.ts

@@ -1,10 +1,54 @@
-export type ColorType = 'hex' | 'css-var' | 'rgb' | 'hsl' | 'named' | 'unknown';
+export type ColorType = 'hex' | 'css-var' | 'rgb' | 'hsl' | 'named' | 'oklch' | 'color' | 'unknown';
 export declare function isCssVariable(value: string): boolean;
 export declare function isHexColor(value: string): boolean;
+export declare function isOklchColor(value: string): boolean;
+export declare function isColorFunction(value: string): boolean;
 export declare function isRgbColor(value: string): boolean;
 export declare function isHslColor(value: string): boolean;
 export declare function getColorType(value: string): ColorType;
 export declare function extractCssVariableName(value: string): string;
+export declare function parseCssVar(value: string): {
+    variableName: string;
+    fallback?: string;
+} | null;
+export declare function parseOklchString(str: string): {
+    L: number;
+    C: number;
+    H: number;
+    alpha: number;
+} | null;
+export declare function parseColorFn(str: string): {
+    space: string;
+    r: number;
+    g: number;
+    b: number;
+    alpha: number;
+} | null;
+export declare function rgbToDisplayP3(rgb: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function displayP3ToRgb(p3: {
+    r: number;
+    g: number;
+    b: number;
+}): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function toDisplayP3Hex(color: string): string;
+export declare function shortHexToRgba(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+} | null;
 export declare function normalizeHex(hex: string): string;
 export declare function hexToRgb(hex: string): [number, number, number];
 export declare function hexToRgba(hex: string, opacity?: number): string;
@@ -153,8 +197,9 @@ export declare function tetradic(color: string): [string, string, string, string
 export declare function colorShades(color: string, steps?: number): string[];
 export declare function monochromatic(color: string, steps?: number): string[];
 export declare function mixColors(c1: string, c2: string, t: number, opts?: {
-    mode?: 'rgb' | 'hsl';
+    mode?: 'rgb' | 'hsl' | 'lab' | 'lch' | 'oklab' | 'oklch';
     format?: 'hex' | 'rgb' | 'rgba' | 'hsl';
+    hueInterpolation?: 'shorter' | 'longer' | 'increasing' | 'decreasing';
 }): string;
 export declare function relativeLuminance(color: string): number;
 export declare function contrastRatio(a: string, b: string): number;
@@ -281,3 +326,72 @@ export declare function randomColor(options?: {
     lRange?: [number, number];
 }): string;
 export declare function toNearestNamedColor(color: string): string;
+export declare function toOklchString(color: string, alpha?: number): string;
+export declare function toColorP3String(color: string, alpha?: number): string;
+export declare function interpolateColors(color1: string, color2: string, steps: number, options?: {
+    space?: 'rgb' | 'hsl' | 'lab' | 'lch' | 'oklab' | 'oklch';
+    format?: 'hex' | 'rgb' | 'rgba' | 'hsl';
+    hueInterpolation?: 'shorter' | 'longer' | 'increasing' | 'decreasing';
+}): string[];
+export declare function createColorScale(anchors: string[] | Array<{
+    color: string;
+    position?: number;
+}>, steps: number, options?: {
+    space?: 'rgb' | 'hsl' | 'oklab' | 'oklch';
+    format?: 'hex' | 'rgb' | 'hsl';
+}): string[];
+export declare function midpointColor(color1: string, color2: string, options?: {
+    space?: 'lab' | 'lch' | 'oklab' | 'oklch';
+}): string;
+export declare function tints(color: string, steps?: number): string[];
+export declare function shades(color: string, steps?: number): string[];
+export declare function tones(color: string, steps?: number, gray?: string): string[];
+export type ColorBlindnessType = 'protanopia' | 'deuteranopia' | 'tritanopia';
+export declare function simulateProtanopia(color: string): string;
+export declare function simulateDeuteranopia(color: string): string;
+export declare function simulateTritanopia(color: string): string;
+export declare function simulateColorBlindness(color: string, type: ColorBlindnessType): string;
+export type BackgroundSpec = string | {
+    type: 'semi-transparent';
+    color: string;
+    underlay?: string;
+} | {
+    type: 'gradient';
+    stops: string[];
+};
+export declare function isReadableOnBackground(textColor: string, background: BackgroundSpec, options?: {
+    level?: 'AA' | 'AAA';
+    largeText?: boolean;
+}): {
+    readable: boolean;
+    minContrastRatio: number;
+    wcagLevel: WcagLevel;
+};
+export interface PaletteScore {
+    palette: string[];
+    minContrastRatio: number;
+    avgContrastRatio: number;
+}
+export declare function bestContrastPalette(background: string, palettes: string[][], options?: {
+    weights?: number[];
+}): PaletteScore & {
+    paletteIndex: number;
+};
+export declare function clearColorCache(): void;
+export declare function getCacheStats(): {
+    size: number;
+    hits: number;
+};
+export declare function enableCache(): void;
+export declare function disableCache(): void;
+export declare function normalizeColorCached(input: string): ReturnType<typeof normalizeColor>;
+export declare function generateGradientColors(start: string, end: string, steps: number, options?: {
+    mode?: 'rgb' | 'hsl' | 'oklab' | 'oklch';
+    format?: 'hex' | 'rgb' | 'hsl';
+}): Generator<string>;
+export declare function generateTints(color: string, steps: number, options?: {
+    format?: 'hex' | 'rgb' | 'hsl';
+}): Generator<string>;
+export declare function generateShades(color: string, steps: number, options?: {
+    format?: 'hex' | 'rgb' | 'hsl';
+}): Generator<string>;