chroma-panel 0.2.0 → 1.0.0

package/README.md

@@ -8,7 +8,7 @@
 
 # chroma-panel — React color picker
 
-A lightweight, accessible React color picker component with the look and feel of the macOS color panel. It includes a color wheel, precise RGB, HSL and HSV sliders, searchable swatches, image color sampling, opacity and an eyedropper—with zero runtime dependencies and TypeScript types included.
+A lightweight, accessible React color picker component with the look and feel of the macOS color panel. Version 1 adds CSS Color 4, a gradient editor, accessible contrast suggestions and design-token exports alongside the color wheel, precise sliders, searchable swatches, image sampling, opacity and eyedropper—with zero runtime dependencies and TypeScript types included.
 
 **[Documentation and live demo](https://chroma-panel.jscrate.dev)** · [Quick start](https://chroma-panel.jscrate.dev/react/overview/quick-start) · [Comparison](https://chroma-panel.jscrate.dev/react/overview/comparison) · [FAQ](https://chroma-panel.jscrate.dev/react/overview/faq) · [Releases](https://chroma-panel.jscrate.dev/react/overview/releases)
 
@@ -18,6 +18,9 @@ A lightweight, accessible React color picker component with the look and feel of
 - Drops into a [form](https://chroma-panel.jscrate.dev/react/handbook/forms) like an `<input>`, with `name`, `required` and `form.reset()`
 - [Accessible](https://chroma-panel.jscrate.dev/react/overview/accessibility): every color channel is a real range input, so keyboards and screen readers work
 - No runtime dependencies, TypeScript types included, ESM and CommonJS
+- CSS Color 4: OKLCH, OKLab, Lab, LCH and Display P3 parsing, conversion and gamut mapping
+- A standalone, keyboard-accessible gradient editor with perceptual interpolation
+- Alpha-aware contrast checks, accessible-color suggestions and CSS/SCSS/design-token exports
 
 ## Install
 
@@ -60,7 +63,7 @@ import { ChromaPanel } from 'chroma-panel';
 
 ## Pick colors from an image
 
-The image mode takes a dropped or chosen file, shows its dominant colors as swatches, and lets you click an exact pixel through a zoom lens. The sampler behind it is exported too, for when you want the palette without the panel:
+The image mode takes a dropped, pasted or chosen file, shows its dominant colors as swatches, and lets you click an exact pixel through a zoom lens. Palettes can be ordered by population, luminance or hue. The sampler behind it is exported too, for when you want the palette without the panel:
 
 ```ts
 import { extractPalette } from 'chroma-panel';
@@ -73,16 +76,51 @@ It takes a `File`, a `Blob` or an image URL, validates safe size limits, and rea
 
 ## Smaller bundle
 
-Importing `chroma-panel` registers all five modes. If you only need one or two, import the shell and add them yourself:
+Importing `chroma-panel` registers all five modes. If you only need one or two, import the shell and pass explicit mode objects:
 
 ```tsx
 import { ChromaPanel } from 'chroma-panel/panel';
-import 'chroma-panel/wheel';
+import { wheelMode } from 'chroma-panel/modes';
 
-<ChromaPanel modes={['wheel']} />
+<ChromaPanel modes={[wheelMode]} />
 ```
 
-That is 13.0 kB instead of 20.6 kB. Every mode has its own entry point — see [entry points](https://chroma-panel.jscrate.dev/react/utils/entry-points).
+The original side-effect import (`import 'chroma-panel/wheel'`) remains supported. Explicit mode objects are easier for bundlers to analyze. Every mode also has its own entry point — see [entry points](https://chroma-panel.jscrate.dev/react/utils/entry-points).
+
+## CSS Color 4 and wide gamut
+
+The dependency-free color engine reads and converts `oklch()`, `oklab()`, `lab()`, `lch()`, `color(srgb …)` and `color(display-p3 …)`. Gamut checks do not silently clip wide-gamut input:
+
+```ts
+import { parseColor, convertColor, isInGamut, mapToGamut, serializeColor } from 'chroma-panel/color';
+
+const color = parseColor('oklch(72% 0.18 250)')!;
+isInGamut(color, 'srgb');
+serializeColor(mapToGamut(color, 'display-p3'));
+```
+
+## Gradient editor
+
+```tsx
+import { GradientEditor, type GradientValue } from 'chroma-panel/gradient';
+
+<GradientEditor defaultValue={gradient} onChangeComplete={(value) => save(value)} />
+```
+
+The same entry exports `gradientToCss`, `sampleGradient`, `normalizeGradient` and `addGradientStop`. It supports linear and radial gradients, movable color stops and OKLab/OKLCH interpolation.
+
+## Reliable change events
+
+The original `onChange` and `onChangeComplete` callbacks remain unchanged. The new callbacks include interaction metadata:
+
+```tsx
+<ColorInput
+  onValueChange={(color, meta) => preview(color.css, meta.source)}
+  onValueCommit={(color, meta) => save(color.css, meta.source)}
+/>
+```
+
+`meta.source` distinguishes pointer, keyboard, field, swatch, image, eyedropper, recent-color and programmatic changes.
 
 ## Theming
 
@@ -108,8 +146,8 @@ Measured as the increase in a real Vite production build, gzipped, with React ex
 
 | What you import | Added to your app |
 | --- | --- |
-| all five modes | 19.3 kB |
-| shell plus one mode | 12.5 kB |
+| all five modes | 22.9 kB |
+| shell plus one mode | 14.9 kB |
 
 `dependencies` is empty. `react` and `react-dom` are peer dependencies, so the copy already in your app is the one that gets used.
 

package/dist/a11y/contrast.cjs

@@ -1,6 +1,9 @@
 const require_dev = require("../core/dev.cjs");
 const require_convert = require("../color/convert.cjs");
+const require_css4 = require("../color/css4.cjs");
 const require_parse = require("../color/parse.cjs");
+const require_serialize = require("../color/serialize.cjs");
+const require_value = require("../color/value.cjs");
 //#region src/a11y/contrast.ts
 function toRgb(input) {
 	if (typeof input !== "string") return require_convert.hsvaToRgba(input);
@@ -23,6 +26,94 @@ function contrastRatio(a, b) {
 	const dark = Math.min(la, lb);
 	return (light + .05) / (dark + .05);
 }
+function compositeColor(foreground, background) {
+	const fg = typeof foreground === "string" ? require_parse.parse(foreground) : foreground;
+	const bg = typeof background === "string" ? require_parse.parse(background) : background;
+	if (fg === null || bg === null) return null;
+	const f = require_convert.hsvaToRgba(fg);
+	const b = require_convert.hsvaToRgba(bg);
+	const alpha = f.a + b.a * (1 - f.a);
+	if (alpha === 0) return {
+		h: 0,
+		s: 0,
+		v: 0,
+		a: 0
+	};
+	return require_convert.rgbaToHsva({
+		r: (f.r * f.a + b.r * b.a * (1 - f.a)) / alpha,
+		g: (f.g * f.a + b.g * b.a * (1 - f.a)) / alpha,
+		b: (f.b * f.a + b.b * b.a * (1 - f.a)) / alpha,
+		a: alpha
+	});
+}
+function contrastRatioWithAlpha(foreground, background, canvas = "#ffffff") {
+	const opaqueBackground = compositeColor(background, canvas);
+	if (opaqueBackground === null) return 1;
+	const opaqueForeground = compositeColor(foreground, opaqueBackground);
+	return opaqueForeground === null ? 1 : contrastRatio(opaqueForeground, opaqueBackground);
+}
+function suggestAccessibleColor(foreground, background, targetRatio = 4.5) {
+	const source = require_value.parseColor(foreground);
+	if (source === null || require_parse.parse(background) === null || !Number.isFinite(targetRatio) || targetRatio < 1) return null;
+	const currentRatio = contrastRatioWithAlpha(foreground, background);
+	if (currentRatio >= targetRatio) return {
+		color: foreground,
+		ratio: currentRatio,
+		changed: false
+	};
+	const oklch = require_css4.convertColor(source, "oklch");
+	const candidates = [];
+	for (const endpoint of [0, 1]) {
+		let passing = endpoint;
+		let failing = oklch.channels[0];
+		if (contrastRatio(toHexColor({
+			...oklch,
+			channels: [
+				endpoint,
+				oklch.channels[1],
+				oklch.channels[2]
+			],
+			alpha: 1
+		}), background) < targetRatio) continue;
+		for (let index = 0; index < 24; index++) {
+			const lightness = (passing + failing) / 2;
+			if (contrastRatio(toHexColor({
+				...oklch,
+				channels: [
+					lightness,
+					oklch.channels[1],
+					oklch.channels[2]
+				],
+				alpha: 1
+			}), background) >= targetRatio) passing = lightness;
+			else failing = lightness;
+		}
+		const color = toHexColor({
+			...oklch,
+			channels: [
+				passing,
+				oklch.channels[1],
+				oklch.channels[2]
+			],
+			alpha: 1
+		});
+		candidates.push({
+			color,
+			ratio: contrastRatio(color, background),
+			changed: true
+		});
+	}
+	return candidates.sort((a, b) => Math.abs(require_css4.convertColor(require_value.parseColor(a.color), "oklch").channels[0] - oklch.channels[0]) - Math.abs(require_css4.convertColor(require_value.parseColor(b.color), "oklch").channels[0] - oklch.channels[0]))[0] ?? null;
+}
+function toHexColor(color) {
+	const srgb = require_css4.mapToGamut(color, "srgb");
+	return require_serialize.toHex(require_convert.rgbaToHsva({
+		r: srgb.channels[0] * 255,
+		g: srgb.channels[1] * 255,
+		b: srgb.channels[2] * 255,
+		a: 1
+	}));
+}
 function meetsContrast(a, b, options) {
 	const { level, size = "normal" } = options;
 	const ratio = contrastRatio(a, b);
@@ -98,10 +189,13 @@ function readableTextColor(background, options = {}) {
 }
 //#endregion
 exports.apcaContrast = apcaContrast;
+exports.compositeColor = compositeColor;
 exports.contrastRatio = contrastRatio;
+exports.contrastRatioWithAlpha = contrastRatioWithAlpha;
 exports.contrastReport = contrastReport;
 exports.meetsContrast = meetsContrast;
 exports.meetsNonTextContrast = meetsNonTextContrast;
 exports.readableTextColor = readableTextColor;
 exports.relativeLuminance = relativeLuminance;
+exports.suggestAccessibleColor = suggestAccessibleColor;
 exports.wcagLevel = wcagLevel;

package/dist/a11y/contrast.d.cts

@@ -2,6 +2,14 @@ import { Hsva } from "../color/types.cjs";
 //#region src/a11y/contrast.d.ts
 export declare function relativeLuminance(color: string | Hsva): number;
 export declare function contrastRatio(a: string | Hsva, b: string | Hsva): number;
+export declare function compositeColor(foreground: string | Hsva, background: string | Hsva): Hsva | null;
+export declare function contrastRatioWithAlpha(foreground: string | Hsva, background: string | Hsva, canvas?: string | Hsva): number;
+export interface AccessibleColorSuggestion {
+  color: string;
+  ratio: number;
+  changed: boolean;
+}
+export declare function suggestAccessibleColor(foreground: string, background: string, targetRatio?: number): AccessibleColorSuggestion | null;
 export type TextSize = "normal" | "large";
 export interface ContrastOptions {
   level: "AA" | "AAA";

package/dist/a11y/contrast.d.ts

@@ -2,6 +2,14 @@ import { Hsva } from "../color/types.js";
 //#region src/a11y/contrast.d.ts
 export declare function relativeLuminance(color: string | Hsva): number;
 export declare function contrastRatio(a: string | Hsva, b: string | Hsva): number;
+export declare function compositeColor(foreground: string | Hsva, background: string | Hsva): Hsva | null;
+export declare function contrastRatioWithAlpha(foreground: string | Hsva, background: string | Hsva, canvas?: string | Hsva): number;
+export interface AccessibleColorSuggestion {
+  color: string;
+  ratio: number;
+  changed: boolean;
+}
+export declare function suggestAccessibleColor(foreground: string, background: string, targetRatio?: number): AccessibleColorSuggestion | null;
 export type TextSize = "normal" | "large";
 export interface ContrastOptions {
   level: "AA" | "AAA";

package/dist/a11y/contrast.js

@@ -1,6 +1,9 @@
 import { warnOnce } from "../core/dev.js";
-import { hsvaToRgba } from "../color/convert.js";
+import { hsvaToRgba, rgbaToHsva } from "../color/convert.js";
+import { convertColor, mapToGamut } from "../color/css4.js";
 import { parse } from "../color/parse.js";
+import { toHex } from "../color/serialize.js";
+import { parseColor } from "../color/value.js";
 //#region src/a11y/contrast.ts
 function toRgb(input) {
 	if (typeof input !== "string") return hsvaToRgba(input);
@@ -23,6 +26,94 @@ function contrastRatio(a, b) {
 	const dark = Math.min(la, lb);
 	return (light + .05) / (dark + .05);
 }
+function compositeColor(foreground, background) {
+	const fg = typeof foreground === "string" ? parse(foreground) : foreground;
+	const bg = typeof background === "string" ? parse(background) : background;
+	if (fg === null || bg === null) return null;
+	const f = hsvaToRgba(fg);
+	const b = hsvaToRgba(bg);
+	const alpha = f.a + b.a * (1 - f.a);
+	if (alpha === 0) return {
+		h: 0,
+		s: 0,
+		v: 0,
+		a: 0
+	};
+	return rgbaToHsva({
+		r: (f.r * f.a + b.r * b.a * (1 - f.a)) / alpha,
+		g: (f.g * f.a + b.g * b.a * (1 - f.a)) / alpha,
+		b: (f.b * f.a + b.b * b.a * (1 - f.a)) / alpha,
+		a: alpha
+	});
+}
+function contrastRatioWithAlpha(foreground, background, canvas = "#ffffff") {
+	const opaqueBackground = compositeColor(background, canvas);
+	if (opaqueBackground === null) return 1;
+	const opaqueForeground = compositeColor(foreground, opaqueBackground);
+	return opaqueForeground === null ? 1 : contrastRatio(opaqueForeground, opaqueBackground);
+}
+function suggestAccessibleColor(foreground, background, targetRatio = 4.5) {
+	const source = parseColor(foreground);
+	if (source === null || parse(background) === null || !Number.isFinite(targetRatio) || targetRatio < 1) return null;
+	const currentRatio = contrastRatioWithAlpha(foreground, background);
+	if (currentRatio >= targetRatio) return {
+		color: foreground,
+		ratio: currentRatio,
+		changed: false
+	};
+	const oklch = convertColor(source, "oklch");
+	const candidates = [];
+	for (const endpoint of [0, 1]) {
+		let passing = endpoint;
+		let failing = oklch.channels[0];
+		if (contrastRatio(toHexColor({
+			...oklch,
+			channels: [
+				endpoint,
+				oklch.channels[1],
+				oklch.channels[2]
+			],
+			alpha: 1
+		}), background) < targetRatio) continue;
+		for (let index = 0; index < 24; index++) {
+			const lightness = (passing + failing) / 2;
+			if (contrastRatio(toHexColor({
+				...oklch,
+				channels: [
+					lightness,
+					oklch.channels[1],
+					oklch.channels[2]
+				],
+				alpha: 1
+			}), background) >= targetRatio) passing = lightness;
+			else failing = lightness;
+		}
+		const color = toHexColor({
+			...oklch,
+			channels: [
+				passing,
+				oklch.channels[1],
+				oklch.channels[2]
+			],
+			alpha: 1
+		});
+		candidates.push({
+			color,
+			ratio: contrastRatio(color, background),
+			changed: true
+		});
+	}
+	return candidates.sort((a, b) => Math.abs(convertColor(parseColor(a.color), "oklch").channels[0] - oklch.channels[0]) - Math.abs(convertColor(parseColor(b.color), "oklch").channels[0] - oklch.channels[0]))[0] ?? null;
+}
+function toHexColor(color) {
+	const srgb = mapToGamut(color, "srgb");
+	return toHex(rgbaToHsva({
+		r: srgb.channels[0] * 255,
+		g: srgb.channels[1] * 255,
+		b: srgb.channels[2] * 255,
+		a: 1
+	}));
+}
 function meetsContrast(a, b, options) {
 	const { level, size = "normal" } = options;
 	const ratio = contrastRatio(a, b);
@@ -97,5 +188,5 @@ function readableTextColor(background, options = {}) {
 	return Math.abs(apcaContrast(dark, background)) >= Math.abs(apcaContrast(light, background)) ? dark : light;
 }
 //#endregion
-export { apcaContrast, contrastRatio, contrastReport, meetsContrast, meetsNonTextContrast, readableTextColor, relativeLuminance, wcagLevel };
+export { apcaContrast, compositeColor, contrastRatio, contrastRatioWithAlpha, contrastReport, meetsContrast, meetsNonTextContrast, readableTextColor, relativeLuminance, suggestAccessibleColor, wcagLevel };