ropav 0.2.0 → 0.3.0

package/dist/utils/color.js

@@ -0,0 +1,665 @@
+import { colorStrings } from "../i18n/color.js";
+import { MAX_DARK_LIGHTNESS, OKLCH_HUES, ORANGE_LIGHTNESS_THRESHOLD, rgbToOKLCH } from "./color-oklch.js";
+import { clamp, toFixedNumber } from "./number.js";
+import { LocalizedStringDictionary, LocalizedStringFormatter } from "@internationalized/string";
+import { NumberFormatter } from "@internationalized/number";
+//#region src/utils/color.ts
+/**
+* The colour model.
+*
+* Ported from React Stately's `color/Color.ts` (react-stately 3.49.0). `@internationalized/color`
+* does not exist — the implementation lives inside `react-stately`, which peer-depends React — so
+* there is no package to depend on and this is a hand port. The parse regexes, the channel ranges
+* and the conversion arithmetic are reproduced exactly, and the localised strings go through this
+* package's own locale layer via `i18n/color.ts`.
+*
+* Reproduced exactly includes the warts. `parseColor("rgb(1.5, 2.4, 3)")` really does stringify to
+* `"#1.82.666666666666603"`, because `rgb()` parsing clamps but never rounds. Tests pin those, so
+* a later "fix" shows up as a deliberate divergence rather than a silent one.
+*/
+/**
+* One dictionary for the whole module, exactly as upstream keeps one.
+*
+* A colour is a plain class, not a component, so it cannot reach the locale in force through
+* `useLocale` — which is why every naming method takes a `locale` argument instead. Upstream also
+* consults a global dictionary a server may have pre-loaded; this package has no such handoff, and
+* `useLocalizedStringFormatter` drops that lookup for the same reason.
+*/
+var dictionary = new LocalizedStringDictionary(colorStrings);
+/**
+* Read one plain string out of the table.
+*
+* The cast is the honest shape of the lookup: hue names are composed at runtime
+* (`` `${hueName} ${nextName}` ``), so the key is only known to be one of the table's keys by
+* construction. Every name the buckets can compose is present in the table.
+*/
+var stringFor = (key, locale) => dictionary.getStringForLocale(key, locale);
+/**
+* Read and write channels by name without giving up type safety.
+*
+* Upstream does `channel in this` then `this[channel]`, which needs the channels to be public
+* index-signature properties. Under this repo's `strict` + `noPropertyAccessFromIndexSignature`
+* that does not typecheck, so each subclass answers for its own channels instead. Behaviour is
+* identical: an unsupported channel reads as `undefined`, which is what raises the error.
+*/
+var ColorBase = class {
+	toHexInt() {
+		return this.toFormat("rgb").toHexInt();
+	}
+	getChannelValue(channel) {
+		const value = this.readChannel(channel);
+		if (value === void 0) throw new Error("Unsupported color channel: " + channel);
+		return value;
+	}
+	withChannelValue(channel, value) {
+		if (this.readChannel(channel) === void 0) throw new Error("Unsupported color channel: " + channel);
+		const next = this.clone();
+		next.writeChannel(channel, value);
+		return next;
+	}
+	getChannelName(channel, locale) {
+		return stringFor(channel, locale);
+	}
+	/**
+	* Resolve the three channels a two dimensional control needs.
+	*
+	* With neither channel given, x is the first channel of the space and y the next — so `hsb`
+	* yields hue × saturation with brightness held, and `rgb` yields red × green with blue held.
+	*/
+	getColorSpaceAxes(xyChannels) {
+		const { xChannel, yChannel } = xyChannels;
+		const channels = this.getColorChannels();
+		const xCh = xChannel ?? channels.find((c) => c !== yChannel);
+		const yCh = yChannel ?? channels.find((c) => c !== xCh);
+		return {
+			xChannel: xCh,
+			yChannel: yCh,
+			zChannel: channels.find((c) => c !== xCh && c !== yCh)
+		};
+	}
+	/**
+	* Name the colour: a lightness word, a chroma word and a hue word, any of which may be empty.
+	*
+	* Both thresholds and buckets are read in OKLCH, where lightness means the same thing at every
+	* hue — see `color-oklch.ts`.
+	*/
+	getColorName(locale) {
+		const rgb = this.toFormat("rgb");
+		const [lightnessValue, chromaValue, hueValue] = rgbToOKLCH(rgb.getChannelValue("red"), rgb.getChannelValue("green"), rgb.getChannelValue("blue"));
+		if (lightnessValue > .999) return stringFor("white", locale);
+		if (lightnessValue < .001) return stringFor("black", locale);
+		const [hue, l] = this.getOklchHue(lightnessValue, chromaValue, hueValue, locale);
+		let lightness = "";
+		let chroma = "";
+		if (chromaValue <= .1 && chromaValue >= .001) chroma = l >= .7 ? "pale" : "grayish";
+		else if (chromaValue >= .15) chroma = "vibrant";
+		if (l < .3) lightness = "very dark";
+		else if (l < .55) lightness = "dark";
+		else if (l < .7) {} else if (l < .85) lightness = "light";
+		else lightness = "very light";
+		if (chroma) chroma = stringFor(chroma, locale);
+		if (lightness) lightness = stringFor(lightness, locale);
+		const alpha = this.getChannelValue("alpha");
+		const formatter = new LocalizedStringFormatter(locale, dictionary);
+		/**
+		* The collapse matters: any of the three words may be empty — a mid-lightness, mid-chroma
+		* colour is named by its hue alone — and the message template joins them with spaces
+		* regardless, so without it a screen reader would read `"  orange"`.
+		*/
+		if (alpha < 1) {
+			const percentTransparent = new NumberFormatter(locale, { style: "percent" }).format(1 - alpha);
+			return formatter.format("transparentColorName", {
+				chroma,
+				hue,
+				lightness,
+				percentTransparent
+			}).replace(/\s+/g, " ").trim();
+		}
+		return formatter.format("colorName", {
+			chroma,
+			hue,
+			lightness
+		}).replace(/\s+/g, " ").trim();
+	}
+	getHueName(locale) {
+		const rgb = this.toFormat("rgb");
+		const [l, c, h] = rgbToOKLCH(rgb.getChannelValue("red"), rgb.getChannelValue("green"), rgb.getChannelValue("blue"));
+		const [name] = this.getOklchHue(l, c, h, locale);
+		return name;
+	}
+	/**
+	* Bucket an OKLCH triple into a hue name, and hand back a lightness that may have moved.
+	*
+	* Three adjustments, all upstream's: below the chroma threshold there is no hue at all, only
+	* gray; orange splits into brown or orange by lightness, and the orange branch *shifts* the
+	* lightness so the words that follow describe the orange range rather than the absolute one;
+	* and a hue past the midpoint of its bucket takes the next hue's name as well, which is where
+	* "cyan blue" and "yellow green" come from.
+	*/
+	getOklchHue(l, c, h, locale) {
+		if (c < .001) return [stringFor("gray", locale), l];
+		let lightness = l;
+		for (let i = 0; i < OKLCH_HUES.length; i++) {
+			const [hue, name] = OKLCH_HUES[i];
+			const [nextHue, nextName] = OKLCH_HUES[i + 1] ?? [360, "pink"];
+			if (h >= hue && h < nextHue) {
+				let hueName = name;
+				if (hueName === "orange") {
+					if (lightness < .68) hueName = "brown";
+					else lightness = lightness - ORANGE_LIGHTNESS_THRESHOLD + MAX_DARK_LIGHTNESS;
+				}
+				if (h > hue + (nextHue - hue) / 2 && hueName !== nextName) hueName = `${hueName} ${nextName}`;
+				else if (hueName === "yellow" && lightness < .85) hueName = "yellow green";
+				return [stringFor(hueName, locale).toLocaleLowerCase(locale), lightness];
+			}
+		}
+		throw new Error("Unexpected hue");
+	}
+};
+var RGBColor = class RGBColor extends ColorBase {
+	red;
+	green;
+	blue;
+	alpha;
+	static colorChannels = [
+		"red",
+		"green",
+		"blue"
+	];
+	constructor(red, green, blue, alpha) {
+		super();
+		this.red = red;
+		this.green = green;
+		this.blue = blue;
+		this.alpha = alpha;
+	}
+	/**
+	* Parse `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` and `rgba()`.
+	*
+	* Shorthand is expanded by doubling every character, and hex alpha is divided by 255 without
+	* rounding — `#abcd` really does carry an alpha of `0.8666666666666667`. The `rgb()` branch
+	* clamps per position (0–255 for the first three, 0–1 for alpha) and ignores anything past the
+	* fourth value, so `rgb(0,0,0,0,0)` parses.
+	*/
+	static parse(value) {
+		let colors = [];
+		if (/^#[\da-f]+$/i.test(value) && [
+			4,
+			5,
+			7,
+			9
+		].includes(value.length)) {
+			const values = (value.length < 6 ? value.replace(/[^#]/gi, "$&$&") : value).slice(1).split("");
+			while (values.length > 0) colors.push(parseInt(values.splice(0, 2).join(""), 16));
+			colors[3] = colors[3] !== void 0 ? colors[3] / 255 : void 0;
+		}
+		const match = value.match(/^rgba?\((.*)\)$/);
+		if (match?.[1]) {
+			colors = match[1].split(",").map((part) => Number(part.trim()));
+			colors = colors.map((num, i) => clamp(num ?? 0, 0, i < 3 ? 255 : 1));
+		}
+		if (colors[0] === void 0 || colors[1] === void 0 || colors[2] === void 0) return;
+		return colors.length < 3 ? void 0 : new RGBColor(colors[0], colors[1], colors[2], colors[3] ?? 1);
+	}
+	readChannel(channel) {
+		switch (channel) {
+			case "red": return this.red;
+			case "green": return this.green;
+			case "blue": return this.blue;
+			case "alpha": return this.alpha;
+			default: return;
+		}
+	}
+	writeChannel(channel, value) {
+		switch (channel) {
+			case "red":
+				this.red = value;
+				break;
+			case "green":
+				this.green = value;
+				break;
+			case "blue":
+				this.blue = value;
+				break;
+			case "alpha": this.alpha = value;
+		}
+	}
+	toString(format = "css") {
+		switch (format) {
+			case "hex": return "#" + (this.red.toString(16).padStart(2, "0") + this.green.toString(16).padStart(2, "0") + this.blue.toString(16).padStart(2, "0")).toUpperCase();
+			case "hexa": return "#" + (this.red.toString(16).padStart(2, "0") + this.green.toString(16).padStart(2, "0") + this.blue.toString(16).padStart(2, "0") + Math.round(this.alpha * 255).toString(16).padStart(2, "0")).toUpperCase();
+			case "rgb": return `rgb(${this.red}, ${this.green}, ${this.blue})`;
+			case "css":
+			case "rgba": return `rgba(${this.red}, ${this.green}, ${this.blue}, ${this.alpha})`;
+			default: return this.toFormat(format).toString(format);
+		}
+	}
+	toFormat(format) {
+		switch (format) {
+			case "hex":
+			case "hexa":
+			case "rgb":
+			case "rgba": return this;
+			case "hsb":
+			case "hsba": return this.toHSB();
+			case "hsl":
+			case "hsla": return this.toHSL();
+			default: throw new Error("Unsupported color conversion: rgb -> " + format);
+		}
+	}
+	toHexInt() {
+		return this.red << 16 | this.green << 8 | this.blue;
+	}
+	/** Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#From_RGB. */
+	toHSB() {
+		const red = this.red / 255;
+		const green = this.green / 255;
+		const blue = this.blue / 255;
+		const min = Math.min(red, green, blue);
+		const brightness = Math.max(red, green, blue);
+		const chroma = brightness - min;
+		const saturation = brightness === 0 ? 0 : chroma / brightness;
+		let hue = 0;
+		if (chroma !== 0) {
+			switch (brightness) {
+				case red:
+					hue = (green - blue) / chroma + (green < blue ? 6 : 0);
+					break;
+				case green:
+					hue = (blue - red) / chroma + 2;
+					break;
+				case blue: hue = (red - green) / chroma + 4;
+			}
+			hue /= 6;
+		}
+		return new HSBColor(toFixedNumber(hue * 360, 2), toFixedNumber(saturation * 100, 2), toFixedNumber(brightness * 100, 2), this.alpha);
+	}
+	/** Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#From_RGB. */
+	toHSL() {
+		const red = this.red / 255;
+		const green = this.green / 255;
+		const blue = this.blue / 255;
+		const min = Math.min(red, green, blue);
+		const max = Math.max(red, green, blue);
+		const lightness = (max + min) / 2;
+		const chroma = max - min;
+		let hue;
+		let saturation;
+		if (chroma === 0) hue = saturation = 0;
+		else {
+			saturation = chroma / (lightness < .5 ? max + min : 2 - max - min);
+			switch (max) {
+				case red:
+					hue = (green - blue) / chroma + (green < blue ? 6 : 0);
+					break;
+				case green:
+					hue = (blue - red) / chroma + 2;
+					break;
+				case blue:
+				default: hue = (red - green) / chroma + 4;
+			}
+			hue /= 6;
+		}
+		return new HSLColor(toFixedNumber(hue * 360, 2), toFixedNumber(saturation * 100, 2), toFixedNumber(lightness * 100, 2), this.alpha);
+	}
+	clone() {
+		return new RGBColor(this.red, this.green, this.blue, this.alpha);
+	}
+	getChannelRange(channel) {
+		switch (channel) {
+			case "red":
+			case "green":
+			case "blue": return {
+				maxValue: 255,
+				minValue: 0,
+				pageSize: 17,
+				step: 1
+			};
+			case "alpha": return {
+				maxValue: 1,
+				minValue: 0,
+				pageSize: .1,
+				step: .01
+			};
+			default: throw new Error("Unknown color channel: " + channel);
+		}
+	}
+	getChannelFormatOptions(channel) {
+		switch (channel) {
+			case "red":
+			case "green":
+			case "blue": return { style: "decimal" };
+			case "alpha": return { style: "percent" };
+			default: throw new Error("Unknown color channel: " + channel);
+		}
+	}
+	formatChannelValue(channel, locale) {
+		const options = this.getChannelFormatOptions(channel);
+		const value = this.getChannelValue(channel);
+		return new NumberFormatter(locale, options).format(value);
+	}
+	getColorSpace() {
+		return "rgb";
+	}
+	getColorChannels() {
+		return RGBColor.colorChannels;
+	}
+};
+/**
+* `hsb(X, X%, X%)` and `hsba(X, X%, X%, X)`.
+*
+* Not anchored, unlike the `rgb()` pattern — so `"garbage hsb(0, 0%, 0%) trailing"` parses. That
+* is upstream's behaviour and consumers may rely on it, so the pattern is copied verbatim rather
+* than tightened.
+*/
+var HSB_REGEX = /hsb\(([-+]?\d+(?:.\d+)?\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d+(?:.\d+)?%)\)|hsba\(([-+]?\d+(?:.\d+)?\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d(.\d+)?)\)/;
+var HSBColor = class HSBColor extends ColorBase {
+	hue;
+	saturation;
+	brightness;
+	alpha;
+	static colorChannels = [
+		"hue",
+		"saturation",
+		"brightness"
+	];
+	constructor(hue, saturation, brightness, alpha) {
+		super();
+		this.hue = hue;
+		this.saturation = saturation;
+		this.brightness = brightness;
+		this.alpha = alpha;
+	}
+	static parse(value) {
+		const m = value.match(HSB_REGEX);
+		if (!m) return void 0;
+		const [h, s, b, a] = (m[1] ?? m[2] ?? "").split(",").map((n) => Number(n.trim().replace("%", "")));
+		return new HSBColor(normalizeHue(h), clamp(s, 0, 100), clamp(b, 0, 100), clamp(a ?? 1, 0, 1));
+	}
+	readChannel(channel) {
+		switch (channel) {
+			case "hue": return this.hue;
+			case "saturation": return this.saturation;
+			case "brightness": return this.brightness;
+			case "alpha": return this.alpha;
+			default: return;
+		}
+	}
+	writeChannel(channel, value) {
+		switch (channel) {
+			case "hue":
+				this.hue = value;
+				break;
+			case "saturation":
+				this.saturation = value;
+				break;
+			case "brightness":
+				this.brightness = value;
+				break;
+			case "alpha": this.alpha = value;
+		}
+	}
+	toString(format = "css") {
+		switch (format) {
+			case "css": return this.toHSL().toString("css");
+			case "hex": return this.toRGB().toString("hex");
+			case "hexa": return this.toRGB().toString("hexa");
+			case "hsb": return `hsb(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.brightness, 2)}%)`;
+			case "hsba": return `hsba(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.brightness, 2)}%, ${this.alpha})`;
+			default: return this.toFormat(format).toString(format);
+		}
+	}
+	toFormat(format) {
+		switch (format) {
+			case "hsb":
+			case "hsba": return this;
+			case "hsl":
+			case "hsla": return this.toHSL();
+			case "rgb":
+			case "rgba": return this.toRGB();
+			default: throw new Error("Unsupported color conversion: hsb -> " + format);
+		}
+	}
+	/** Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_HSL. */
+	toHSL() {
+		const brightness = this.brightness / 100;
+		const lightness = brightness * (1 - this.saturation / 100 / 2);
+		const saturation = lightness === 0 || lightness === 1 ? 0 : (brightness - lightness) / Math.min(lightness, 1 - lightness);
+		return new HSLColor(toFixedNumber(this.hue, 2), toFixedNumber(saturation * 100, 2), toFixedNumber(lightness * 100, 2), this.alpha);
+	}
+	/**
+	* Conversion formula adapted from
+	* https://en.wikipedia.org/wiki/HSL_and_HSV#HSV_to_RGB_alternative.
+	*/
+	toRGB() {
+		const hue = this.hue;
+		const saturation = this.saturation / 100;
+		const brightness = this.brightness / 100;
+		const fn = (n, k = (n + hue / 60) % 6) => brightness - saturation * brightness * Math.max(Math.min(k, 4 - k, 1), 0);
+		return new RGBColor(Math.round(fn(5) * 255), Math.round(fn(3) * 255), Math.round(fn(1) * 255), this.alpha);
+	}
+	clone() {
+		return new HSBColor(this.hue, this.saturation, this.brightness, this.alpha);
+	}
+	getChannelRange(channel) {
+		switch (channel) {
+			case "hue": return {
+				maxValue: 360,
+				minValue: 0,
+				pageSize: 15,
+				step: 1
+			};
+			case "saturation":
+			case "brightness": return {
+				maxValue: 100,
+				minValue: 0,
+				pageSize: 10,
+				step: 1
+			};
+			case "alpha": return {
+				maxValue: 1,
+				minValue: 0,
+				pageSize: .1,
+				step: .01
+			};
+			default: throw new Error("Unknown color channel: " + channel);
+		}
+	}
+	getChannelFormatOptions(channel) {
+		switch (channel) {
+			case "hue": return {
+				style: "unit",
+				unit: "degree",
+				unitDisplay: "narrow"
+			};
+			case "saturation":
+			case "brightness":
+			case "alpha": return { style: "percent" };
+			default: throw new Error("Unknown color channel: " + channel);
+		}
+	}
+	/**
+	* Saturation and brightness are stored 0–100 but formatted as percentages, so they are divided
+	* first. Alpha is already 0–1 and must not be.
+	*/
+	formatChannelValue(channel, locale) {
+		const options = this.getChannelFormatOptions(channel);
+		const raw = this.getChannelValue(channel);
+		const value = channel === "saturation" || channel === "brightness" ? raw / 100 : raw;
+		return new NumberFormatter(locale, options).format(value);
+	}
+	getColorSpace() {
+		return "hsb";
+	}
+	getColorChannels() {
+		return HSBColor.colorChannels;
+	}
+};
+/** `hsl(X, X%, X%)` and `hsla(X, X%, X%, X)`. Unanchored for the same reason as `HSB_REGEX`. */
+var HSL_REGEX = /hsl\(([-+]?\d+(?:.\d+)?\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d+(?:.\d+)?%)\)|hsla\(([-+]?\d+(?:.\d+)?\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d+(?:.\d+)?%\s*,\s*[-+]?\d(.\d+)?)\)/;
+var HSLColor = class HSLColor extends ColorBase {
+	hue;
+	saturation;
+	lightness;
+	alpha;
+	static colorChannels = [
+		"hue",
+		"saturation",
+		"lightness"
+	];
+	constructor(hue, saturation, lightness, alpha) {
+		super();
+		this.hue = hue;
+		this.saturation = saturation;
+		this.lightness = lightness;
+		this.alpha = alpha;
+	}
+	static parse(value) {
+		const m = value.match(HSL_REGEX);
+		if (!m) return void 0;
+		const [h, s, l, a] = (m[1] ?? m[2] ?? "").split(",").map((n) => Number(n.trim().replace("%", "")));
+		return new HSLColor(normalizeHue(h), clamp(s, 0, 100), clamp(l, 0, 100), clamp(a ?? 1, 0, 1));
+	}
+	readChannel(channel) {
+		switch (channel) {
+			case "hue": return this.hue;
+			case "saturation": return this.saturation;
+			case "lightness": return this.lightness;
+			case "alpha": return this.alpha;
+			default: return;
+		}
+	}
+	writeChannel(channel, value) {
+		switch (channel) {
+			case "hue":
+				this.hue = value;
+				break;
+			case "saturation":
+				this.saturation = value;
+				break;
+			case "lightness":
+				this.lightness = value;
+				break;
+			case "alpha": this.alpha = value;
+		}
+	}
+	toString(format = "css") {
+		switch (format) {
+			case "hex": return this.toRGB().toString("hex");
+			case "hexa": return this.toRGB().toString("hexa");
+			case "hsl": return `hsl(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.lightness, 2)}%)`;
+			case "css":
+			case "hsla": return `hsla(${this.hue}, ${toFixedNumber(this.saturation, 2)}%, ${toFixedNumber(this.lightness, 2)}%, ${this.alpha})`;
+			default: return this.toFormat(format).toString(format);
+		}
+	}
+	toFormat(format) {
+		switch (format) {
+			case "hsl":
+			case "hsla": return this;
+			case "hsb":
+			case "hsba": return this.toHSB();
+			case "rgb":
+			case "rgba": return this.toRGB();
+			default: throw new Error("Unsupported color conversion: hsl -> " + format);
+		}
+	}
+	/** Conversion formula adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_HSV. */
+	toHSB() {
+		const lightness = this.lightness / 100;
+		const brightness = lightness + this.saturation / 100 * Math.min(lightness, 1 - lightness);
+		const saturation = brightness === 0 ? 0 : 2 * (1 - lightness / brightness);
+		return new HSBColor(toFixedNumber(this.hue, 2), toFixedNumber(saturation * 100, 2), toFixedNumber(brightness * 100, 2), this.alpha);
+	}
+	/**
+	* Conversion formula adapted from
+	* https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_RGB_alternative.
+	*/
+	toRGB() {
+		const hue = this.hue;
+		const lightness = this.lightness / 100;
+		const a = this.saturation / 100 * Math.min(lightness, 1 - lightness);
+		const fn = (n, k = (n + hue / 30) % 12) => lightness - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+		return new RGBColor(Math.round(fn(0) * 255), Math.round(fn(8) * 255), Math.round(fn(4) * 255), this.alpha);
+	}
+	clone() {
+		return new HSLColor(this.hue, this.saturation, this.lightness, this.alpha);
+	}
+	getChannelRange(channel) {
+		switch (channel) {
+			case "hue": return {
+				maxValue: 360,
+				minValue: 0,
+				pageSize: 15,
+				step: 1
+			};
+			case "saturation":
+			case "lightness": return {
+				maxValue: 100,
+				minValue: 0,
+				pageSize: 10,
+				step: 1
+			};
+			case "alpha": return {
+				maxValue: 1,
+				minValue: 0,
+				pageSize: .1,
+				step: .01
+			};
+			default: throw new Error("Unknown color channel: " + channel);
+		}
+	}
+	getChannelFormatOptions(channel) {
+		switch (channel) {
+			case "hue": return {
+				style: "unit",
+				unit: "degree",
+				unitDisplay: "narrow"
+			};
+			case "saturation":
+			case "lightness":
+			case "alpha": return { style: "percent" };
+			default: throw new Error("Unknown color channel: " + channel);
+		}
+	}
+	formatChannelValue(channel, locale) {
+		const options = this.getChannelFormatOptions(channel);
+		const raw = this.getChannelValue(channel);
+		const value = channel === "saturation" || channel === "lightness" ? raw / 100 : raw;
+		return new NumberFormatter(locale, options).format(value);
+	}
+	getColorSpace() {
+		return "hsl";
+	}
+	getColorChannels() {
+		return HSLColor.colorChannels;
+	}
+};
+/**
+* Wrap a hue into 0–360.
+*
+* `360` is special-cased rather than wrapped to `0`: a slider sitting at its maximum should read
+* as 360, not jump back to the other end.
+*/
+var normalizeHue = (hue) => {
+	if (hue === 360) return hue;
+	return (hue % 360 + 360) % 360;
+};
+/** Parses a color from a string value. Throws an error if the string could not be parsed. */
+var parseColor = (value) => {
+	const res = RGBColor.parse(value) ?? HSBColor.parse(value) ?? HSLColor.parse(value);
+	if (res) return res;
+	throw new Error("Invalid color value: " + value);
+};
+/** Accept either a string or an already-parsed colour. */
+var normalizeColor = (v) => typeof v === "string" ? parseColor(v) : v;
+/** Returns a list of color channels for a given color space. */
+var getColorChannels = (colorSpace) => {
+	switch (colorSpace) {
+		case "rgb": return RGBColor.colorChannels;
+		case "hsl": return HSLColor.colorChannels;
+		case "hsb": return HSBColor.colorChannels;
+	}
+};
+//#endregion
+export { getColorChannels, normalizeColor, normalizeHue, parseColor };

package/dist/utils/compose.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve a `tv()` slot function into a class string, merging in a caller `class`.
+ *
+ * Feeding the caller class through `tv()` is what lets it *override* conflicting
+ * utilities, since `tailwind-variants` runs `tailwind-merge` over the result. Vue's
+ * own attribute fallthrough would only concatenate, which does not override anything.
+ *
+ * `class` rather than `className`: `tv()` accepts either, and `class` is the Vue idiom.
+ *
+ * @example
+ * ```ts
+ * composeSlotClassName(slots.indicator, props.class);
+ * composeSlotClassName(slots.fallback, props.class, {color: props.color});
+ * ```
+ */
+export declare const composeSlotClassName: (slotFn: ((args?: {
+    class?: string;
+    [key: string]: any;
+}) => string) | undefined, className?: string, variants?: Record<string, any>) => string | undefined;

package/dist/utils/compose.js

@@ -0,0 +1,22 @@
+//#region src/utils/compose.ts
+/**
+* Resolve a `tv()` slot function into a class string, merging in a caller `class`.
+*
+* Feeding the caller class through `tv()` is what lets it *override* conflicting
+* utilities, since `tailwind-variants` runs `tailwind-merge` over the result. Vue's
+* own attribute fallthrough would only concatenate, which does not override anything.
+*
+* `class` rather than `className`: `tv()` accepts either, and `class` is the Vue idiom.
+*
+* @example
+* ```ts
+* composeSlotClassName(slots.indicator, props.class);
+* composeSlotClassName(slots.fallback, props.class, {color: props.color});
+* ```
+*/
+var composeSlotClassName = (slotFn, className, variants) => typeof slotFn === "function" ? slotFn({
+	...variants ?? {},
+	class: className
+}) : className;
+//#endregion
+export { composeSlotClassName };