@optique/core 1.3.0-dev.2542 → 1.3.0-dev.2558

package/dist/usage.js

@@ -1,5 +1,5 @@
 import { getDisplayWidth } from "./displaywidth.js";
-import { cacheTerminalTheme, formatTerminalTerm, fragmentTokens, serializeTokens } from "./terminal-internal.js";
+import { cacheTerminalTheme, formatTerminalLeaf, fragmentTokens, serializeTokens } from "./terminal-internal.js";
 import { validateProgramName } from "./validate.js";
 
 //#region src/usage.ts
@@ -204,23 +204,17 @@ function formatUsage(programName, usage, options = {}) {
 			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	const programTokens = layoutUsageTokens(fragmentTokens(formatTerminalTerm({
-		type: "programName",
-		programName
-	}, options.theme)), options);
-	const terms = [...formatUsageTerms(usage, options)];
-	if (terms.length === 0) return serializeTokens(programTokens, options.colors);
-	const width = programTokens.reduce((n, token) => token.width === -1 ? 0 : n + token.width, 0);
-	const separator = options.maxWidth != null && width + 1 + terms[0].width > options.maxWidth ? {
-		text: "\n",
-		width: -1,
-		scopes: []
-	} : {
-		text: " ",
-		width: 1,
-		scopes: []
-	};
-	return serializeTokens([...programTokens, separator], options.colors) + wrapUsageTokens(terms, options, separator.width === -1 ? 0 : width + 1);
+	return wrapUsageTokens(function* () {
+		yield* usageLeafTokens({
+			type: "programName",
+			programName
+		}, options);
+		yield {
+			...usageSpace,
+			programBoundary: true
+		};
+		yield* formatUsageTerms(usage, options);
+	}(), options);
 }
 /**
 * Normalizes a usage description by flattening nested exclusive terms,
@@ -450,14 +444,23 @@ function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	}
 	return terms;
 }
+const usageSpace = {
+	text: " ",
+	width: 1,
+	scopes: [],
+	separator: true
+};
+function* usageLeafTokens(term, options, usage) {
+	const { fragment, defaultOrigin } = formatTerminalLeaf(term, options.theme, false, usage);
+	for (const token of fragmentTokens(fragment)) yield {
+		...token,
+		legacyWhitespace: defaultOrigin
+	};
+}
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
-		if (i > 0) yield {
-			text: " ",
-			width: 1,
-			scopes: []
-		};
+		if (i > 0) yield usageSpace;
 		yield* formatUsageTermInternal(t, options);
 		i++;
 	}
@@ -483,21 +486,57 @@ function formatUsageTerm(term, options = {}) {
 	if (visibleTerms.length < 1) return "";
 	return wrapUsageTokens(formatUsageTermInternal(visibleTerms[0], options), options);
 }
-function wrapUsageTokens(input, options, initialWidth = 0) {
-	return serializeTokens(layoutUsageTokens(input, options, initialWidth), options.colors);
+function wrapUsageTokens(input, options) {
+	return serializeTokens(layoutUsageTokens(input, options), options.colors);
 }
-function layoutUsageTokens(input, options, initialWidth = 0) {
-	let lineWidth = initialWidth;
-	const output = [];
+/** Keeps one layout-owned space between nonempty outputs on the same line. */
+function* normalizeUsageSeparators(input) {
+	let previous;
+	let pending = [];
 	for (const token of input) {
+		if (token.separator || token.text === "") {
+			pending.push(token);
+			continue;
+		}
+		let separated = false;
+		for (const item of pending) if (!item.separator) yield item;
+		else if (!separated && previous != null && previous.width !== -1 && token.width !== -1) {
+			yield item;
+			separated = true;
+		}
+		pending = [];
+		yield token;
+		previous = token;
+	}
+	for (const item of pending) if (!item.separator) yield item;
+}
+function layoutUsageTokens(input, options) {
+	let lineWidth = 0;
+	const output = [];
+	const tokens = [...normalizeUsageSeparators(input)];
+	for (const [index, token] of tokens.entries()) {
+		if (token.programBoundary && options.maxWidth != null) {
+			const next = tokens.find((item, i) => i > index && item.text !== "");
+			if (next != null && lineWidth + token.width + next.width > options.maxWidth) {
+				output.push({
+					text: "\n",
+					width: -1,
+					scopes: []
+				});
+				lineWidth = 0;
+				continue;
+			}
+		}
 		if (token.width === -1) {
 			output.push(token);
 			lineWidth = 0;
 			continue;
 		}
-		if (options.maxWidth != null && lineWidth > 0 && lineWidth + token.width > options.maxWidth) {
-			const last = output.at(-1);
-			if (last?.text.endsWith(" ") && (!options.colors || last.scopes.length === 0)) output[output.length - 1] = {
+		if (options.maxWidth != null && lineWidth > 0 && token.width > 0 && lineWidth + token.width > options.maxWidth) {
+			let lastIndex = output.length - 1;
+			while (lastIndex >= 0 && output[lastIndex].text === "") lastIndex--;
+			const last = output[lastIndex];
+			if (last?.text.endsWith(" ") && (last.separator || last.legacyWhitespace && (!options.colors || last.scopes.length === 0))) output[lastIndex] = {
 				...last,
 				text: last.text.slice(0, -1),
 				width: last.width - 1
@@ -508,7 +547,7 @@ function layoutUsageTokens(input, options, initialWidth = 0) {
 				scopes: []
 			});
 			lineWidth = 0;
-			if (token.text === " ") continue;
+			if (token.separator || token.legacyWhitespace && token.text === " ") continue;
 		}
 		output.push(token);
 		lineWidth += token.width;
@@ -517,7 +556,7 @@ function layoutUsageTokens(input, options, initialWidth = 0) {
 }
 function* formatUsageTermInternal(term, options) {
 	function leaf(t, usage) {
-		return fragmentTokens(formatTerminalTerm(t, options.theme, false, usage));
+		return usageLeafTokens(t, options, usage);
 	}
 	function punctuation(punctuation$1, kind) {
 		return leaf({
@@ -526,11 +565,7 @@ function* formatUsageTermInternal(term, options) {
 			kind
 		});
 	}
-	const space = {
-		text: " ",
-		width: 1,
-		scopes: []
-	};
+	const space = usageSpace;
 	if (term.type === "argument") yield* leaf({
 		type: "metavar",
 		metavar: term.metavar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2542",
+  "version": "1.3.0-dev.2558",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2542+1201b1a0",
+    "@optique/env": "1.3.0-dev.2558+85f681ee",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",