@optique/core 1.1.0-dev.2054 → 1.1.0-dev.2065

package/dist/valueparser.cjs

@@ -504,6 +504,1467 @@ function float(options = {}) {
 		}
 	};
 }
+const SI_MULTIPLIERS = {
+	b: 1,
+	kb: 1e3,
+	mb: 1e6,
+	gb: 1e9,
+	tb: 1e12,
+	pb: 1e15,
+	eb: 1e18
+};
+const IEC_MULTIPLIERS = {
+	b: 1,
+	kb: 1024,
+	mb: 1024 ** 2,
+	gb: 1024 ** 3,
+	tb: 1024 ** 4,
+	pb: 1024 ** 5,
+	eb: 1024 ** 6,
+	kib: 1024,
+	mib: 1024 ** 2,
+	gib: 1024 ** 3,
+	tib: 1024 ** 4,
+	pib: 1024 ** 5,
+	eib: 1024 ** 6
+};
+const IEC_ONLY_MULTIPLIERS = {
+	kib: 1024,
+	mib: 1024 ** 2,
+	gib: 1024 ** 3,
+	tib: 1024 ** 4,
+	pib: 1024 ** 5,
+	eib: 1024 ** 6
+};
+const FILE_SIZE_REGEX = /^([+-]?(?:\d+\.?\d*|\d*\.\d+))\s*([a-zA-Z]*)$/;
+/**
+* Formats `bytes` using the most readable unit from the given ordered list.
+* Falls back to `"${bytes}B"`.
+*
+* A unit is chosen only when the formatted value round-trips exactly: the
+* rounded quotient must lie in [1, 1000) and `rounded * size === bytes` must
+* hold in float64 arithmetic.  This guarantees `parse(format(x)) === x`.
+*/
+function formatWithUnits(bytes, units) {
+	if (bytes === 0) return "0B";
+	const absBytes = Math.abs(bytes);
+	for (const [unit, size] of units) {
+		if (absBytes < size) continue;
+		const v = bytes / size;
+		const rounded = Math.round(v * 100) / 100;
+		const absRounded = Math.abs(rounded);
+		if (absRounded >= 1 && absRounded < 1e3 && rounded * size === bytes) return `${rounded}${unit}`;
+	}
+	return `${bytes}B`;
+}
+const FORMAT_UNITS_DEFAULT = [
+	["EiB", 1024 ** 6],
+	["PiB", 1024 ** 5],
+	["TiB", 1024 ** 4],
+	["GiB", 1024 ** 3],
+	["MiB", 1024 ** 2],
+	["KiB", 1024],
+	["EB", 1e18],
+	["PB", 1e15],
+	["TB", 1e12],
+	["GB", 1e9],
+	["MB", 1e6],
+	["KB", 1e3]
+];
+const FORMAT_UNITS_SI_AS_BINARY = [
+	["EB", 1024 ** 6],
+	["PB", 1024 ** 5],
+	["TB", 1024 ** 4],
+	["GB", 1024 ** 3],
+	["MB", 1024 ** 2],
+	["KB", 1024]
+];
+const BIGINT_SI_MULTIPLIERS = {
+	b: 1n,
+	kb: 1000n,
+	mb: 1000000n,
+	gb: 1000000000n,
+	tb: 1000000000000n,
+	pb: 1000000000000000n,
+	eb: 1000000000000000000n
+};
+const BIGINT_IEC_MULTIPLIERS = {
+	b: 1n,
+	kb: 1024n,
+	mb: 1024n ** 2n,
+	gb: 1024n ** 3n,
+	tb: 1024n ** 4n,
+	pb: 1024n ** 5n,
+	eb: 1024n ** 6n,
+	kib: 1024n,
+	mib: 1024n ** 2n,
+	gib: 1024n ** 3n,
+	tib: 1024n ** 4n,
+	pib: 1024n ** 5n,
+	eib: 1024n ** 6n
+};
+const BIGINT_IEC_ONLY_MULTIPLIERS = {
+	kib: 1024n,
+	mib: 1024n ** 2n,
+	gib: 1024n ** 3n,
+	tib: 1024n ** 4n,
+	pib: 1024n ** 5n,
+	eib: 1024n ** 6n
+};
+const BIGINT_FORMAT_UNITS_DEFAULT = [
+	["EiB", 1024n ** 6n],
+	["PiB", 1024n ** 5n],
+	["TiB", 1024n ** 4n],
+	["GiB", 1024n ** 3n],
+	["MiB", 1024n ** 2n],
+	["KiB", 1024n],
+	["EB", 1000000000000000000n],
+	["PB", 1000000000000000n],
+	["TB", 1000000000000n],
+	["GB", 1000000000n],
+	["MB", 1000000n],
+	["KB", 1000n]
+];
+const BIGINT_FORMAT_UNITS_SI_AS_BINARY = [
+	["EB", 1024n ** 6n],
+	["PB", 1024n ** 5n],
+	["TB", 1024n ** 4n],
+	["GB", 1024n ** 3n],
+	["MB", 1024n ** 2n],
+	["KB", 1024n]
+];
+/**
+* Formats a bigint byte count using the most readable unit.  Falls back to
+* `"${value}B"`.  Tries exact integers, then 1 and 2 decimal places.
+*/
+function formatBigIntBytes(value, units) {
+	if (value === 0n) return "0B";
+	const absValue = value < 0n ? -value : value;
+	for (const [unit, size] of units) {
+		if (absValue < size) continue;
+		if (value % size === 0n) {
+			const v = value / size;
+			const absV = v < 0n ? -v : v;
+			if (absV >= 1n && absV < 1000n) return `${v}${unit}`;
+		}
+		const v100 = value * 100n;
+		if (v100 % size === 0n) {
+			const q = v100 / size;
+			const absQ = q < 0n ? -q : q;
+			if (absQ >= 100n && absQ < 100000n) {
+				const intPart = q / 100n;
+				const decPart = absQ % 100n;
+				if (decPart % 10n === 0n) return `${intPart}.${decPart / 10n}${unit}`;
+				return `${intPart}.${String(decPart).padStart(2, "0")}${unit}`;
+			}
+		}
+	}
+	return `${value}B`;
+}
+/**
+* Core computation: parses `numStr` as a decimal rational, multiplies by
+* `mBig`, and returns the exact integer result as a `bigint`, or `null` when
+* the result would be fractional.  The safe-integer range check is NOT applied
+* here; callers add it as needed.
+*/
+function parseExactBytesRaw(numStr, mBig) {
+	const negative = numStr.startsWith("-");
+	const absStr = numStr.startsWith("+") || numStr.startsWith("-") ? numStr.slice(1) : numStr;
+	const dotIdx = absStr.indexOf(".");
+	const intPart = dotIdx < 0 ? absStr : absStr.slice(0, dotIdx);
+	const fracPart = dotIdx < 0 ? "" : absStr.slice(dotIdx + 1);
+	const numeratorStr = ((intPart || "0") + fracPart).replace(/^0+/, "") || "0";
+	const numerator = BigInt(numeratorStr) * (negative ? -1n : 1n);
+	const denominator = 10n ** BigInt(fracPart.length);
+	const bytesNumerator = numerator * mBig;
+	if (bytesNumerator % denominator !== 0n) return null;
+	return bytesNumerator / denominator;
+}
+/**
+* Parses `numStr` as a decimal rational and multiplies by `multiplier`,
+* returning the exact integer result as a safe `number`, or `null` when the
+* result would be fractional or outside `Number.MAX_SAFE_INTEGER`.
+*
+* All arithmetic is performed with `bigint` to avoid float64 precision loss
+* (e.g. `"1.0000000000000001"` must not silently round to `1`).
+*/
+function parseExactBytes(numStr, multiplier) {
+	const bytes = parseExactBytesRaw(numStr, BigInt(multiplier));
+	if (bytes == null) return null;
+	const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+	if (bytes < -maxSafe || bytes > maxSafe) return null;
+	return Number(bytes);
+}
+const FILE_SIZE_UNITS = [
+	"B",
+	"KB",
+	"MB",
+	"GB",
+	"TB",
+	"PB",
+	"EB",
+	"KiB",
+	"MiB",
+	"GiB",
+	"TiB",
+	"PiB",
+	"EiB"
+];
+/**
+* Creates a {@link ValueParser} for human-readable file/data size strings such
+* as `"10MB"`, `"1.5GiB"`, or `"512B"`.  The parsed value is a `number` or
+* `bigint` representing the equivalent byte count.
+*
+* Supported units:
+*
+* | Unit | Bytes (default) |
+* |------|----------------|
+* | B    | 1              |
+* | KB   | 1 000          |
+* | MB   | 1 000 000      |
+* | GB   | 1 000 000 000  |
+* | KiB  | 1 024          |
+* | MiB  | 1 048 576      |
+* | GiB  | 1 073 741 824  |
+* | …    | …              |
+*
+* Unit suffixes are matched case-insensitively, so `"1kb"`, `"1KB"`, and
+* `"1Kb"` are all equivalent.
+*
+* @param options Configuration options for the file size parser.
+* @returns A {@link ValueParser} that parses file size strings into byte
+*          counts.
+* @throws {TypeError} If `type` is neither `"number"` nor `"bigint"`, if
+*   `metavar` is an empty string, if `allowNegative` or `siAsBinary` is not
+*   a boolean, or if `defaultUnit` is not a valid {@link FileSizeUnit}.
+* @since 1.1.0
+*/
+function fileSize(options = {}) {
+	if (options.type !== void 0 && options.type !== "number" && options.type !== "bigint") throw new TypeError(`Expected type to be "number" or "bigint", but got: ${String(options.type)}.`);
+	const metavar = options.metavar ?? "SIZE";
+	require_nonempty.ensureNonEmptyString(metavar);
+	checkBooleanOption(options, "allowNegative");
+	checkBooleanOption(options, "siAsBinary");
+	checkEnumOption(options, "defaultUnit", FILE_SIZE_UNITS);
+	const siAsBinary = options.siAsBinary ?? false;
+	function invalidFormatError(input) {
+		return {
+			success: false,
+			error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : require_message.message`Expected a file size like ${"10MB"} or ${"1.5GiB"}, but got ${input}.`
+		};
+	}
+	if (options.type === "bigint") {
+		const bigintMultiplierMap = siAsBinary ? BIGINT_IEC_MULTIPLIERS : {
+			...BIGINT_SI_MULTIPLIERS,
+			...BIGINT_IEC_ONLY_MULTIPLIERS
+		};
+		const bigintFormatUnits = siAsBinary ? BIGINT_FORMAT_UNITS_SI_AS_BINARY : BIGINT_FORMAT_UNITS_DEFAULT;
+		const numberFormatUnits = siAsBinary ? FORMAT_UNITS_SI_AS_BINARY : FORMAT_UNITS_DEFAULT;
+		return {
+			mode: "sync",
+			metavar,
+			placeholder: options.placeholder ?? 0n,
+			parse(input) {
+				const match = FILE_SIZE_REGEX.exec(input.trim());
+				if (match == null) return invalidFormatError(input);
+				const numStr = match[1];
+				const unitStr = match[2].toLowerCase();
+				let mBig;
+				if (unitStr === "") {
+					if (options.defaultUnit == null) return invalidFormatError(input);
+					mBig = bigintMultiplierMap[options.defaultUnit.toLowerCase()];
+				} else {
+					const m = bigintMultiplierMap[unitStr];
+					if (m == null) return invalidFormatError(input);
+					mBig = m;
+				}
+				const bytes = parseExactBytesRaw(numStr, mBig);
+				if (bytes == null) return invalidFormatError(input);
+				if (!(options.allowNegative ?? false) && bytes < 0n) return {
+					success: false,
+					error: options.errors?.negativeNotAllowed ? typeof options.errors.negativeNotAllowed === "function" ? options.errors.negativeNotAllowed(bytes) : options.errors.negativeNotAllowed : require_message.message`Expected a non-negative file size, but got ${input}.`
+				};
+				return {
+					success: true,
+					value: bytes
+				};
+			},
+			format(value) {
+				const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+				if (value >= -maxSafe && value <= maxSafe) return formatWithUnits(Number(value), numberFormatUnits);
+				return formatBigIntBytes(value, bigintFormatUnits);
+			}
+		};
+	}
+	const multiplierMap = siAsBinary ? IEC_MULTIPLIERS : {
+		...SI_MULTIPLIERS,
+		...IEC_ONLY_MULTIPLIERS
+	};
+	const formatUnits = siAsBinary ? FORMAT_UNITS_SI_AS_BINARY : FORMAT_UNITS_DEFAULT;
+	return {
+		mode: "sync",
+		metavar,
+		placeholder: options.placeholder ?? 0,
+		parse(input) {
+			const match = FILE_SIZE_REGEX.exec(input.trim());
+			if (match == null) return invalidFormatError(input);
+			const numStr = match[1];
+			const unitStr = match[2].toLowerCase();
+			let multiplier;
+			if (unitStr === "") {
+				if (options.defaultUnit == null) return invalidFormatError(input);
+				multiplier = multiplierMap[options.defaultUnit.toLowerCase()];
+			} else {
+				const m = multiplierMap[unitStr];
+				if (m == null) return invalidFormatError(input);
+				multiplier = m;
+			}
+			const bytes = parseExactBytes(numStr, multiplier);
+			if (bytes == null) return invalidFormatError(input);
+			if (!(options.allowNegative ?? false) && bytes < 0) return {
+				success: false,
+				error: options.errors?.negativeNotAllowed ? typeof options.errors.negativeNotAllowed === "function" ? options.errors.negativeNotAllowed(bytes) : options.errors.negativeNotAllowed : require_message.message`Expected a non-negative file size, but got ${input}.`
+			};
+			return {
+				success: true,
+				value: bytes
+			};
+		},
+		format(value) {
+			return formatWithUnits(value, formatUnits);
+		}
+	};
+}
+const CSS_NAMED_COLORS = {
+	aliceblue: {
+		r: 240,
+		g: 248,
+		b: 255,
+		a: 1
+	},
+	antiquewhite: {
+		r: 250,
+		g: 235,
+		b: 215,
+		a: 1
+	},
+	aqua: {
+		r: 0,
+		g: 255,
+		b: 255,
+		a: 1
+	},
+	aquamarine: {
+		r: 127,
+		g: 255,
+		b: 212,
+		a: 1
+	},
+	azure: {
+		r: 240,
+		g: 255,
+		b: 255,
+		a: 1
+	},
+	beige: {
+		r: 245,
+		g: 245,
+		b: 220,
+		a: 1
+	},
+	bisque: {
+		r: 255,
+		g: 228,
+		b: 196,
+		a: 1
+	},
+	black: {
+		r: 0,
+		g: 0,
+		b: 0,
+		a: 1
+	},
+	blanchedalmond: {
+		r: 255,
+		g: 235,
+		b: 205,
+		a: 1
+	},
+	blue: {
+		r: 0,
+		g: 0,
+		b: 255,
+		a: 1
+	},
+	blueviolet: {
+		r: 138,
+		g: 43,
+		b: 226,
+		a: 1
+	},
+	brown: {
+		r: 165,
+		g: 42,
+		b: 42,
+		a: 1
+	},
+	burlywood: {
+		r: 222,
+		g: 184,
+		b: 135,
+		a: 1
+	},
+	cadetblue: {
+		r: 95,
+		g: 158,
+		b: 160,
+		a: 1
+	},
+	chartreuse: {
+		r: 127,
+		g: 255,
+		b: 0,
+		a: 1
+	},
+	chocolate: {
+		r: 210,
+		g: 105,
+		b: 30,
+		a: 1
+	},
+	coral: {
+		r: 255,
+		g: 127,
+		b: 80,
+		a: 1
+	},
+	cornflowerblue: {
+		r: 100,
+		g: 149,
+		b: 237,
+		a: 1
+	},
+	cornsilk: {
+		r: 255,
+		g: 248,
+		b: 220,
+		a: 1
+	},
+	crimson: {
+		r: 220,
+		g: 20,
+		b: 60,
+		a: 1
+	},
+	cyan: {
+		r: 0,
+		g: 255,
+		b: 255,
+		a: 1
+	},
+	darkblue: {
+		r: 0,
+		g: 0,
+		b: 139,
+		a: 1
+	},
+	darkcyan: {
+		r: 0,
+		g: 139,
+		b: 139,
+		a: 1
+	},
+	darkgoldenrod: {
+		r: 184,
+		g: 134,
+		b: 11,
+		a: 1
+	},
+	darkgray: {
+		r: 169,
+		g: 169,
+		b: 169,
+		a: 1
+	},
+	darkgreen: {
+		r: 0,
+		g: 100,
+		b: 0,
+		a: 1
+	},
+	darkgrey: {
+		r: 169,
+		g: 169,
+		b: 169,
+		a: 1
+	},
+	darkkhaki: {
+		r: 189,
+		g: 183,
+		b: 107,
+		a: 1
+	},
+	darkmagenta: {
+		r: 139,
+		g: 0,
+		b: 139,
+		a: 1
+	},
+	darkolivegreen: {
+		r: 85,
+		g: 107,
+		b: 47,
+		a: 1
+	},
+	darkorange: {
+		r: 255,
+		g: 140,
+		b: 0,
+		a: 1
+	},
+	darkorchid: {
+		r: 153,
+		g: 50,
+		b: 204,
+		a: 1
+	},
+	darkred: {
+		r: 139,
+		g: 0,
+		b: 0,
+		a: 1
+	},
+	darksalmon: {
+		r: 233,
+		g: 150,
+		b: 122,
+		a: 1
+	},
+	darkseagreen: {
+		r: 143,
+		g: 188,
+		b: 143,
+		a: 1
+	},
+	darkslateblue: {
+		r: 72,
+		g: 61,
+		b: 139,
+		a: 1
+	},
+	darkslategray: {
+		r: 47,
+		g: 79,
+		b: 79,
+		a: 1
+	},
+	darkslategrey: {
+		r: 47,
+		g: 79,
+		b: 79,
+		a: 1
+	},
+	darkturquoise: {
+		r: 0,
+		g: 206,
+		b: 209,
+		a: 1
+	},
+	darkviolet: {
+		r: 148,
+		g: 0,
+		b: 211,
+		a: 1
+	},
+	deeppink: {
+		r: 255,
+		g: 20,
+		b: 147,
+		a: 1
+	},
+	deepskyblue: {
+		r: 0,
+		g: 191,
+		b: 255,
+		a: 1
+	},
+	dimgray: {
+		r: 105,
+		g: 105,
+		b: 105,
+		a: 1
+	},
+	dimgrey: {
+		r: 105,
+		g: 105,
+		b: 105,
+		a: 1
+	},
+	dodgerblue: {
+		r: 30,
+		g: 144,
+		b: 255,
+		a: 1
+	},
+	firebrick: {
+		r: 178,
+		g: 34,
+		b: 34,
+		a: 1
+	},
+	floralwhite: {
+		r: 255,
+		g: 250,
+		b: 240,
+		a: 1
+	},
+	forestgreen: {
+		r: 34,
+		g: 139,
+		b: 34,
+		a: 1
+	},
+	fuchsia: {
+		r: 255,
+		g: 0,
+		b: 255,
+		a: 1
+	},
+	gainsboro: {
+		r: 220,
+		g: 220,
+		b: 220,
+		a: 1
+	},
+	ghostwhite: {
+		r: 248,
+		g: 248,
+		b: 255,
+		a: 1
+	},
+	gold: {
+		r: 255,
+		g: 215,
+		b: 0,
+		a: 1
+	},
+	goldenrod: {
+		r: 218,
+		g: 165,
+		b: 32,
+		a: 1
+	},
+	gray: {
+		r: 128,
+		g: 128,
+		b: 128,
+		a: 1
+	},
+	green: {
+		r: 0,
+		g: 128,
+		b: 0,
+		a: 1
+	},
+	greenyellow: {
+		r: 173,
+		g: 255,
+		b: 47,
+		a: 1
+	},
+	grey: {
+		r: 128,
+		g: 128,
+		b: 128,
+		a: 1
+	},
+	honeydew: {
+		r: 240,
+		g: 255,
+		b: 240,
+		a: 1
+	},
+	hotpink: {
+		r: 255,
+		g: 105,
+		b: 180,
+		a: 1
+	},
+	indianred: {
+		r: 205,
+		g: 92,
+		b: 92,
+		a: 1
+	},
+	indigo: {
+		r: 75,
+		g: 0,
+		b: 130,
+		a: 1
+	},
+	ivory: {
+		r: 255,
+		g: 255,
+		b: 240,
+		a: 1
+	},
+	khaki: {
+		r: 240,
+		g: 230,
+		b: 140,
+		a: 1
+	},
+	lavender: {
+		r: 230,
+		g: 230,
+		b: 250,
+		a: 1
+	},
+	lavenderblush: {
+		r: 255,
+		g: 240,
+		b: 245,
+		a: 1
+	},
+	lawngreen: {
+		r: 124,
+		g: 252,
+		b: 0,
+		a: 1
+	},
+	lemonchiffon: {
+		r: 255,
+		g: 250,
+		b: 205,
+		a: 1
+	},
+	lightblue: {
+		r: 173,
+		g: 216,
+		b: 230,
+		a: 1
+	},
+	lightcoral: {
+		r: 240,
+		g: 128,
+		b: 128,
+		a: 1
+	},
+	lightcyan: {
+		r: 224,
+		g: 255,
+		b: 255,
+		a: 1
+	},
+	lightgoldenrodyellow: {
+		r: 250,
+		g: 250,
+		b: 210,
+		a: 1
+	},
+	lightgray: {
+		r: 211,
+		g: 211,
+		b: 211,
+		a: 1
+	},
+	lightgreen: {
+		r: 144,
+		g: 238,
+		b: 144,
+		a: 1
+	},
+	lightgrey: {
+		r: 211,
+		g: 211,
+		b: 211,
+		a: 1
+	},
+	lightpink: {
+		r: 255,
+		g: 182,
+		b: 193,
+		a: 1
+	},
+	lightsalmon: {
+		r: 255,
+		g: 160,
+		b: 122,
+		a: 1
+	},
+	lightseagreen: {
+		r: 32,
+		g: 178,
+		b: 170,
+		a: 1
+	},
+	lightskyblue: {
+		r: 135,
+		g: 206,
+		b: 250,
+		a: 1
+	},
+	lightslategray: {
+		r: 119,
+		g: 136,
+		b: 153,
+		a: 1
+	},
+	lightslategrey: {
+		r: 119,
+		g: 136,
+		b: 153,
+		a: 1
+	},
+	lightsteelblue: {
+		r: 176,
+		g: 196,
+		b: 222,
+		a: 1
+	},
+	lightyellow: {
+		r: 255,
+		g: 255,
+		b: 224,
+		a: 1
+	},
+	lime: {
+		r: 0,
+		g: 255,
+		b: 0,
+		a: 1
+	},
+	limegreen: {
+		r: 50,
+		g: 205,
+		b: 50,
+		a: 1
+	},
+	linen: {
+		r: 250,
+		g: 240,
+		b: 230,
+		a: 1
+	},
+	magenta: {
+		r: 255,
+		g: 0,
+		b: 255,
+		a: 1
+	},
+	maroon: {
+		r: 128,
+		g: 0,
+		b: 0,
+		a: 1
+	},
+	mediumaquamarine: {
+		r: 102,
+		g: 205,
+		b: 170,
+		a: 1
+	},
+	mediumblue: {
+		r: 0,
+		g: 0,
+		b: 205,
+		a: 1
+	},
+	mediumorchid: {
+		r: 186,
+		g: 85,
+		b: 211,
+		a: 1
+	},
+	mediumpurple: {
+		r: 147,
+		g: 112,
+		b: 219,
+		a: 1
+	},
+	mediumseagreen: {
+		r: 60,
+		g: 179,
+		b: 113,
+		a: 1
+	},
+	mediumslateblue: {
+		r: 123,
+		g: 104,
+		b: 238,
+		a: 1
+	},
+	mediumspringgreen: {
+		r: 0,
+		g: 250,
+		b: 154,
+		a: 1
+	},
+	mediumturquoise: {
+		r: 72,
+		g: 209,
+		b: 204,
+		a: 1
+	},
+	mediumvioletred: {
+		r: 199,
+		g: 21,
+		b: 133,
+		a: 1
+	},
+	midnightblue: {
+		r: 25,
+		g: 25,
+		b: 112,
+		a: 1
+	},
+	mintcream: {
+		r: 245,
+		g: 255,
+		b: 250,
+		a: 1
+	},
+	mistyrose: {
+		r: 255,
+		g: 228,
+		b: 225,
+		a: 1
+	},
+	moccasin: {
+		r: 255,
+		g: 228,
+		b: 181,
+		a: 1
+	},
+	navajowhite: {
+		r: 255,
+		g: 222,
+		b: 173,
+		a: 1
+	},
+	navy: {
+		r: 0,
+		g: 0,
+		b: 128,
+		a: 1
+	},
+	oldlace: {
+		r: 253,
+		g: 245,
+		b: 230,
+		a: 1
+	},
+	olive: {
+		r: 128,
+		g: 128,
+		b: 0,
+		a: 1
+	},
+	olivedrab: {
+		r: 107,
+		g: 142,
+		b: 35,
+		a: 1
+	},
+	orange: {
+		r: 255,
+		g: 165,
+		b: 0,
+		a: 1
+	},
+	orangered: {
+		r: 255,
+		g: 69,
+		b: 0,
+		a: 1
+	},
+	orchid: {
+		r: 218,
+		g: 112,
+		b: 214,
+		a: 1
+	},
+	palegoldenrod: {
+		r: 238,
+		g: 232,
+		b: 170,
+		a: 1
+	},
+	palegreen: {
+		r: 152,
+		g: 251,
+		b: 152,
+		a: 1
+	},
+	paleturquoise: {
+		r: 175,
+		g: 238,
+		b: 238,
+		a: 1
+	},
+	palevioletred: {
+		r: 219,
+		g: 112,
+		b: 147,
+		a: 1
+	},
+	papayawhip: {
+		r: 255,
+		g: 239,
+		b: 213,
+		a: 1
+	},
+	peachpuff: {
+		r: 255,
+		g: 218,
+		b: 185,
+		a: 1
+	},
+	peru: {
+		r: 205,
+		g: 133,
+		b: 63,
+		a: 1
+	},
+	pink: {
+		r: 255,
+		g: 192,
+		b: 203,
+		a: 1
+	},
+	plum: {
+		r: 221,
+		g: 160,
+		b: 221,
+		a: 1
+	},
+	powderblue: {
+		r: 176,
+		g: 224,
+		b: 230,
+		a: 1
+	},
+	purple: {
+		r: 128,
+		g: 0,
+		b: 128,
+		a: 1
+	},
+	rebeccapurple: {
+		r: 102,
+		g: 51,
+		b: 153,
+		a: 1
+	},
+	red: {
+		r: 255,
+		g: 0,
+		b: 0,
+		a: 1
+	},
+	rosybrown: {
+		r: 188,
+		g: 143,
+		b: 143,
+		a: 1
+	},
+	royalblue: {
+		r: 65,
+		g: 105,
+		b: 225,
+		a: 1
+	},
+	saddlebrown: {
+		r: 139,
+		g: 69,
+		b: 19,
+		a: 1
+	},
+	salmon: {
+		r: 250,
+		g: 128,
+		b: 114,
+		a: 1
+	},
+	sandybrown: {
+		r: 244,
+		g: 164,
+		b: 96,
+		a: 1
+	},
+	seagreen: {
+		r: 46,
+		g: 139,
+		b: 87,
+		a: 1
+	},
+	seashell: {
+		r: 255,
+		g: 245,
+		b: 238,
+		a: 1
+	},
+	sienna: {
+		r: 160,
+		g: 82,
+		b: 45,
+		a: 1
+	},
+	silver: {
+		r: 192,
+		g: 192,
+		b: 192,
+		a: 1
+	},
+	skyblue: {
+		r: 135,
+		g: 206,
+		b: 235,
+		a: 1
+	},
+	slateblue: {
+		r: 106,
+		g: 90,
+		b: 205,
+		a: 1
+	},
+	slategray: {
+		r: 112,
+		g: 128,
+		b: 144,
+		a: 1
+	},
+	slategrey: {
+		r: 112,
+		g: 128,
+		b: 144,
+		a: 1
+	},
+	snow: {
+		r: 255,
+		g: 250,
+		b: 250,
+		a: 1
+	},
+	springgreen: {
+		r: 0,
+		g: 255,
+		b: 127,
+		a: 1
+	},
+	steelblue: {
+		r: 70,
+		g: 130,
+		b: 180,
+		a: 1
+	},
+	tan: {
+		r: 210,
+		g: 180,
+		b: 140,
+		a: 1
+	},
+	teal: {
+		r: 0,
+		g: 128,
+		b: 128,
+		a: 1
+	},
+	thistle: {
+		r: 216,
+		g: 191,
+		b: 216,
+		a: 1
+	},
+	tomato: {
+		r: 255,
+		g: 99,
+		b: 71,
+		a: 1
+	},
+	transparent: {
+		r: 0,
+		g: 0,
+		b: 0,
+		a: 0
+	},
+	turquoise: {
+		r: 64,
+		g: 224,
+		b: 208,
+		a: 1
+	},
+	violet: {
+		r: 238,
+		g: 130,
+		b: 238,
+		a: 1
+	},
+	wheat: {
+		r: 245,
+		g: 222,
+		b: 179,
+		a: 1
+	},
+	white: {
+		r: 255,
+		g: 255,
+		b: 255,
+		a: 1
+	},
+	whitesmoke: {
+		r: 245,
+		g: 245,
+		b: 245,
+		a: 1
+	},
+	yellow: {
+		r: 255,
+		g: 255,
+		b: 0,
+		a: 1
+	},
+	yellowgreen: {
+		r: 154,
+		g: 205,
+		b: 50,
+		a: 1
+	}
+};
+const CSS_NAMED_COLOR_KEYS = Object.keys(CSS_NAMED_COLORS);
+function hslToRgb(h, s, l) {
+	h = (h % 360 + 360) % 360;
+	const a = s * Math.min(l, 1 - l);
+	const f = (n) => {
+		const k = (n + h / 30) % 12;
+		return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+	};
+	return [
+		Math.round(f(0) * 255),
+		Math.round(f(8) * 255),
+		Math.round(f(4) * 255)
+	];
+}
+function rgbToHsl(r, g, b) {
+	const rn = r / 255, gn = g / 255, bn = b / 255;
+	const max = Math.max(rn, gn, bn);
+	const min = Math.min(rn, gn, bn);
+	const l = (max + min) / 2;
+	if (max === min) return [
+		0,
+		0,
+		l * 100
+	];
+	const d = max - min;
+	const s = l > .5 ? d / (2 - max - min) : d / (max + min);
+	let h;
+	if (max === rn) h = ((gn - bn) / d + (gn < bn ? 6 : 0)) / 6;
+	else if (max === gn) h = ((bn - rn) / d + 2) / 6;
+	else h = ((rn - gn) / d + 4) / 6;
+	return [
+		h * 360,
+		s * 100,
+		l * 100
+	];
+}
+const COLOR_HEX_SHORT_REGEX = /^#([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])([0-9a-fA-F])?$/;
+const COLOR_HEX_LONG_REGEX = /^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})?$/;
+const COLOR_NUM_PATTERN = "(?:\\d+(?:\\.\\d*)?|\\d*\\.\\d+)";
+const COLOR_HUE_PATTERN = `(?:-?${COLOR_NUM_PATTERN})`;
+const COLOR_RGB_REGEX = new RegExp(`^rgba?\\(\\s*(\\d{1,3})\\s*,\\s*(\\d{1,3})\\s*,\\s*(\\d{1,3})\\s*(?:,\\s*(${COLOR_NUM_PATTERN}))?\\s*\\)$`, "i");
+const COLOR_HSL_REGEX = new RegExp(`^hsla?\\(\\s*(${COLOR_HUE_PATTERN})\\s*,\\s*(${COLOR_NUM_PATTERN})%\\s*,\\s*(${COLOR_NUM_PATTERN})%\\s*(?:,\\s*(${COLOR_NUM_PATTERN}))?\\s*\\)$`, "i");
+const VALID_COLOR_FORMATS = [
+	"hex",
+	"rgb",
+	"hsl",
+	"named"
+];
+/**
+* Creates a value parser that accepts CSS color strings and returns a
+* structured {@link Color} object with normalized RGBA components.
+*
+* Supported input notations by default:
+* - Hex: `#rgb`, `#rrggbb`, `#rgba`, `#rrggbbaa`
+* - RGB: `rgb(r, g, b)`, `rgba(r, g, b, a)`
+* - HSL: `hsl(h, s%, l%)`, `hsla(h, s%, l%, a)`
+* - Named: all 148 CSS Level 4 named colors (e.g., `red`, `rebeccapurple`)
+*
+* The `format()` method always outputs canonical lowercase hex
+* (`#rrggbb` when fully opaque, `#rrggbbaa` otherwise).
+*
+* @param options Configuration options for the parser.
+* @returns A sync value parser producing {@link Color} objects.
+* @throws {TypeError} If {@link ColorOptions.metavar} is an empty string, or
+*   if {@link ColorOptions.formats} contains an invalid format name.
+* @throws {RangeError} If {@link ValueParser.format} is called with a
+*   {@link Color} whose `r`, `g`, or `b` channel is not an integer in
+*   0–255, or whose `a` channel is not a finite number in 0–1.
+* @since 1.1.0
+*/
+function color(options = {}) {
+	const metavar = options.metavar ?? "COLOR";
+	require_nonempty.ensureNonEmptyString(metavar);
+	if (options.formats !== void 0) {
+		for (const fmt of options.formats) if (!VALID_COLOR_FORMATS.includes(fmt)) throw new TypeError(`Expected formats to contain only ${VALID_COLOR_FORMATS.map((v) => JSON.stringify(v)).join(", ")}, but got: ${JSON.stringify(fmt)}.`);
+	}
+	const allowedFormats = options.formats ?? VALID_COLOR_FORMATS;
+	const allowHex = allowedFormats.includes("hex");
+	const allowRgb = allowedFormats.includes("rgb");
+	const allowHsl = allowedFormats.includes("hsl");
+	const allowNamed = allowedFormats.includes("named");
+	const defaultPlaceholder = {
+		r: 0,
+		g: 0,
+		b: 0,
+		a: 1
+	};
+	const formatExamples = [
+		...allowHex ? ["#ff0000"] : [],
+		...allowRgb ? ["rgb(255, 0, 0)"] : [],
+		...allowHsl ? ["hsl(0, 100%, 50%)"] : [],
+		...allowNamed ? ["red"] : []
+	];
+	function invalidFormatError(input) {
+		return {
+			success: false,
+			error: options.errors?.invalidFormat ? typeof options.errors.invalidFormat === "function" ? options.errors.invalidFormat(input) : options.errors.invalidFormat : require_message.message`Expected a CSS color like ${require_message.valueSet(formatExamples, {
+				fallback: "a valid color",
+				type: "disjunction"
+			})}, but got ${input}.`
+		};
+	}
+	return {
+		mode: "sync",
+		metavar,
+		placeholder: options.placeholder ?? defaultPlaceholder,
+		parse(input) {
+			const trimmed = input.trim();
+			if (allowHex) {
+				let m = COLOR_HEX_LONG_REGEX.exec(trimmed);
+				if (m != null) {
+					const r = parseInt(m[1], 16);
+					const g = parseInt(m[2], 16);
+					const b = parseInt(m[3], 16);
+					const a = m[4] !== void 0 ? parseInt(m[4], 16) / 255 : 1;
+					return {
+						success: true,
+						value: {
+							r,
+							g,
+							b,
+							a
+						}
+					};
+				}
+				m = COLOR_HEX_SHORT_REGEX.exec(trimmed);
+				if (m != null) {
+					const r = parseInt(m[1] + m[1], 16);
+					const g = parseInt(m[2] + m[2], 16);
+					const b = parseInt(m[3] + m[3], 16);
+					const a = m[4] !== void 0 ? parseInt(m[4] + m[4], 16) / 255 : 1;
+					return {
+						success: true,
+						value: {
+							r,
+							g,
+							b,
+							a
+						}
+					};
+				}
+			}
+			if (allowRgb) {
+				const m = COLOR_RGB_REGEX.exec(trimmed);
+				if (m != null) {
+					const r = parseInt(m[1], 10);
+					const g = parseInt(m[2], 10);
+					const b = parseInt(m[3], 10);
+					const aRaw = m[4] !== void 0 ? parseFloat(m[4]) : 1;
+					if (r > 255 || g > 255 || b > 255 || !Number.isFinite(aRaw) || aRaw < 0 || aRaw > 1) return invalidFormatError(input);
+					const a = Math.round(aRaw * 255) / 255;
+					return {
+						success: true,
+						value: {
+							r,
+							g,
+							b,
+							a
+						}
+					};
+				}
+			}
+			if (allowHsl) {
+				const m = COLOR_HSL_REGEX.exec(trimmed);
+				if (m != null) {
+					const h = parseFloat(m[1]);
+					const s = parseFloat(m[2]);
+					const l = parseFloat(m[3]);
+					const aRaw = m[4] !== void 0 ? parseFloat(m[4]) : 1;
+					if (!Number.isFinite(h) || !Number.isFinite(s) || s < 0 || s > 100 || !Number.isFinite(l) || l < 0 || l > 100 || !Number.isFinite(aRaw) || aRaw < 0 || aRaw > 1) return invalidFormatError(input);
+					const [r, g, b] = hslToRgb(h, s / 100, l / 100);
+					const a = Math.round(aRaw * 255) / 255;
+					return {
+						success: true,
+						value: {
+							r,
+							g,
+							b,
+							a
+						}
+					};
+				}
+			}
+			if (allowNamed) {
+				const key = trimmed.toLowerCase();
+				if (Object.hasOwn(CSS_NAMED_COLORS, key)) return {
+					success: true,
+					value: { ...CSS_NAMED_COLORS[key] }
+				};
+			}
+			return invalidFormatError(input);
+		},
+		format(value) {
+			const { r, g, b, a } = value;
+			if (!Number.isInteger(r) || r < 0 || r > 255 || !Number.isInteger(g) || g < 0 || g > 255 || !Number.isInteger(b) || b < 0 || b > 255 || !Number.isFinite(a) || a < 0 || a > 1) throw new RangeError(`Color components out of range: r=${r}, g=${g}, b=${b}, a=${a}.`);
+			const aStr = parseFloat(a.toFixed(4));
+			if (allowHex) {
+				const rh = r.toString(16).padStart(2, "0");
+				const gh = g.toString(16).padStart(2, "0");
+				const bh = b.toString(16).padStart(2, "0");
+				if (a === 1) return `#${rh}${gh}${bh}`;
+				const ah = Math.round(a * 255).toString(16).padStart(2, "0");
+				return `#${rh}${gh}${bh}${ah}`;
+			}
+			if (allowRgb) return a === 1 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${aStr})`;
+			if (allowHsl) {
+				const [h, s, l] = rgbToHsl(r, g, b);
+				const hStr = parseFloat(h.toFixed(4));
+				const sStr = parseFloat(s.toFixed(4));
+				const lStr = parseFloat(l.toFixed(4));
+				return a === 1 ? `hsl(${hStr}, ${sStr}%, ${lStr}%)` : `hsla(${hStr}, ${sStr}%, ${lStr}%, ${aStr})`;
+			}
+			for (const [name, c] of Object.entries(CSS_NAMED_COLORS)) if (c.r === r && c.g === g && c.b === b && c.a === a) return name;
+			throw new RangeError(`No CSS named color matches { r: ${r}, g: ${g}, b: ${b}, a: ${a} }.`);
+		},
+		normalize(value) {
+			if (!Number.isInteger(value.r) || value.r < 0 || value.r > 255 || !Number.isInteger(value.g) || value.g < 0 || value.g > 255 || !Number.isInteger(value.b) || value.b < 0 || value.b > 255 || !Number.isFinite(value.a) || value.a < 0 || value.a > 1) return value;
+			const a = Math.round(value.a * 255) / 255;
+			return a === value.a ? value : {
+				...value,
+				a
+			};
+		},
+		*suggest(prefix) {
+			if (allowNamed) {
+				const lowerPrefix = prefix.toLowerCase();
+				for (const name of CSS_NAMED_COLOR_KEYS) if (name.startsWith(lowerPrefix)) yield {
+					kind: "literal",
+					text: name
+				};
+			}
+		}
+	};
+}
 /**
 * The set of URL schemes that are considered "special" by the WHATWG URL
 * Standard.  These schemes always use the `://` authority syntax.
@@ -3689,9 +5150,11 @@ exports.checkBooleanOption = checkBooleanOption;
 exports.checkEnumOption = checkEnumOption;
 exports.choice = choice;
 exports.cidr = cidr;
+exports.color = color;
 exports.domain = domain;
 exports.email = email;
 exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
+exports.fileSize = fileSize;
 exports.float = float;
 exports.hostname = hostname;
 exports.integer = integer;