@optique/core 1.2.9 → 1.2.10

package/dist/displaywidth.cjs

@@ -16,6 +16,17 @@ function getDisplayWidth(text) {
 	for (const { segment } of segmenter.segment(stripped)) width += graphemeWidth(segment);
 	return width;
 }
+/**
+* Removes ANSI escape sequences (CSI and OSC) from a string, leaving only
+* the text a terminal would print.
+*
+* @param text The string to strip.
+* @returns The string without ANSI escape sequences.
+* @internal
+*/
+function stripAnsi(text) {
+	return text.replace(ansiRegex, "");
+}
 const zeroWidthRegex = /^[\p{Cf}\p{Mn}\p{Me}]+$/u;
 const emojiPresentationRegex = /\p{Emoji_Presentation}/u;
 const emojiWithVS16Regex = /\p{Emoji}\uFE0F/u;
@@ -41,4 +52,5 @@ function isEastAsianWide(cp) {
 }
 
 //#endregion
-exports.getDisplayWidth = getDisplayWidth;
+exports.getDisplayWidth = getDisplayWidth;
+exports.stripAnsi = stripAnsi;

package/dist/displaywidth.d.cts

@@ -8,5 +8,14 @@
  * @internal
  */
 declare function getDisplayWidth(text: string): number;
+/**
+ * Removes ANSI escape sequences (CSI and OSC) from a string, leaving only
+ * the text a terminal would print.
+ *
+ * @param text The string to strip.
+ * @returns The string without ANSI escape sequences.
+ * @internal
+ */
+declare function stripAnsi(text: string): string;
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/displaywidth.d.ts

@@ -8,5 +8,14 @@
  * @internal
  */
 declare function getDisplayWidth(text: string): number;
+/**
+ * Removes ANSI escape sequences (CSI and OSC) from a string, leaving only
+ * the text a terminal would print.
+ *
+ * @param text The string to strip.
+ * @returns The string without ANSI escape sequences.
+ * @internal
+ */
+declare function stripAnsi(text: string): string;
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/displaywidth.js

@@ -15,6 +15,17 @@ function getDisplayWidth(text) {
 	for (const { segment } of segmenter.segment(stripped)) width += graphemeWidth(segment);
 	return width;
 }
+/**
+* Removes ANSI escape sequences (CSI and OSC) from a string, leaving only
+* the text a terminal would print.
+*
+* @param text The string to strip.
+* @returns The string without ANSI escape sequences.
+* @internal
+*/
+function stripAnsi(text) {
+	return text.replace(ansiRegex, "");
+}
 const zeroWidthRegex = /^[\p{Cf}\p{Mn}\p{Me}]+$/u;
 const emojiPresentationRegex = /\p{Emoji_Presentation}/u;
 const emojiWithVS16Regex = /\p{Emoji}\uFE0F/u;
@@ -40,4 +51,4 @@ function isEastAsianWide(cp) {
 }
 
 //#endregion
-export { getDisplayWidth };
+export { getDisplayWidth, stripAnsi };

package/dist/doc.cjs

@@ -342,13 +342,15 @@ function formatDocPage(programName, page, options = {}) {
 				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
 				const prefixWidth = require_displaywidth.getDisplayWidth(prefix);
 				const suffixWidth = require_displaywidth.getDisplayWidth(suffix);
+				let defaultPrefix = prefix;
 				let defaultStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
 					const effectiveLastW = lastW + currentExtraOffset();
 					if (effectiveLastW + prefixWidth >= descColumnWidth) {
 						description += "\n";
-						defaultStartWidth = prefixWidth;
+						defaultPrefix = prefix.trimStart();
+						defaultStartWidth = require_displaywidth.getDisplayWidth(defaultPrefix);
 					} else defaultStartWidth = effectiveLastW + prefixWidth;
 				}
 				const defaultFormatOptions = {
@@ -358,7 +360,7 @@ function formatDocPage(programName, page, options = {}) {
 					startWidth: defaultStartWidth
 				};
 				const defaultContent = require_message.formatMessage(entry.default, defaultFormatOptions);
-				const defaultText = `${prefix}${defaultContent}${suffix}`;
+				const defaultText = `${defaultPrefix}${defaultContent}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
@@ -386,6 +388,7 @@ function formatDocPage(programName, page, options = {}) {
 				const choicesPrefixWidth = require_displaywidth.getDisplayWidth(prefix);
 				const choicesSuffixWidth = require_displaywidth.getDisplayWidth(suffix);
 				const choicesLabelWidth = require_displaywidth.getDisplayWidth(label);
+				let choicesHeading = `${prefix}${label}`;
 				let choicesStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
@@ -393,7 +396,8 @@ function formatDocPage(programName, page, options = {}) {
 					const prefixLabelLen = choicesPrefixWidth + choicesLabelWidth;
 					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
 						description += "\n";
-						choicesStartWidth = prefixLabelLen;
+						choicesHeading = choicesHeading.trimStart();
+						choicesStartWidth = require_displaywidth.getDisplayWidth(choicesHeading);
 					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
 				}
 				const choicesFormatOptions = {
@@ -403,7 +407,7 @@ function formatDocPage(programName, page, options = {}) {
 					startWidth: choicesStartWidth
 				};
 				const choicesDisplay = require_message.formatMessage(truncatedTerms, choicesFormatOptions);
-				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
+				const choicesText = `${choicesHeading}${choicesDisplay}${suffix}`;
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
 			}

package/dist/doc.js

@@ -342,13 +342,15 @@ function formatDocPage(programName, page, options = {}) {
 				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
 				const prefixWidth = getDisplayWidth(prefix);
 				const suffixWidth = getDisplayWidth(suffix);
+				let defaultPrefix = prefix;
 				let defaultStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
 					const effectiveLastW = lastW + currentExtraOffset();
 					if (effectiveLastW + prefixWidth >= descColumnWidth) {
 						description += "\n";
-						defaultStartWidth = prefixWidth;
+						defaultPrefix = prefix.trimStart();
+						defaultStartWidth = getDisplayWidth(defaultPrefix);
 					} else defaultStartWidth = effectiveLastW + prefixWidth;
 				}
 				const defaultFormatOptions = {
@@ -358,7 +360,7 @@ function formatDocPage(programName, page, options = {}) {
 					startWidth: defaultStartWidth
 				};
 				const defaultContent = formatMessage(entry.default, defaultFormatOptions);
-				const defaultText = `${prefix}${defaultContent}${suffix}`;
+				const defaultText = `${defaultPrefix}${defaultContent}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
@@ -386,6 +388,7 @@ function formatDocPage(programName, page, options = {}) {
 				const choicesPrefixWidth = getDisplayWidth(prefix);
 				const choicesSuffixWidth = getDisplayWidth(suffix);
 				const choicesLabelWidth = getDisplayWidth(label);
+				let choicesHeading = `${prefix}${label}`;
 				let choicesStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
@@ -393,7 +396,8 @@ function formatDocPage(programName, page, options = {}) {
 					const prefixLabelLen = choicesPrefixWidth + choicesLabelWidth;
 					if (effectiveLastW + prefixLabelLen >= descColumnWidth) {
 						description += "\n";
-						choicesStartWidth = prefixLabelLen;
+						choicesHeading = choicesHeading.trimStart();
+						choicesStartWidth = getDisplayWidth(choicesHeading);
 					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
 				}
 				const choicesFormatOptions = {
@@ -403,7 +407,7 @@ function formatDocPage(programName, page, options = {}) {
 					startWidth: choicesStartWidth
 				};
 				const choicesDisplay = formatMessage(truncatedTerms, choicesFormatOptions);
-				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
+				const choicesText = `${choicesHeading}${choicesDisplay}${suffix}`;
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
 			}

package/dist/message.cjs

@@ -324,7 +324,8 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: require_displaywidth.getDisplayWidth(match[0])
+								width: require_displaywidth.getDisplayWidth(match[0]),
+								trimOnWrap: true
 							};
 						}
 					}
@@ -332,7 +333,8 @@ function formatMessage(msg, options = {}) {
 					const normalizedText = rawText.replace(/\n/g, " ");
 					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
 						text: " ",
-						width: 1
+						width: 1,
+						trimOnWrap: true
 					};
 					else {
 						wordPattern.lastIndex = 0;
@@ -341,7 +343,8 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: require_displaywidth.getDisplayWidth(match[0])
+								width: require_displaywidth.getDisplayWidth(match[0]),
+								trimOnWrap: true
 							};
 						}
 					}
@@ -381,7 +384,8 @@ function formatMessage(msg, options = {}) {
 			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
 				if (i > 0) yield {
 					text: " ",
-					width: 1
+					width: 1,
+					trimOnWrap: true
 				};
 				const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 				yield {
@@ -425,18 +429,40 @@ function formatMessage(msg, options = {}) {
 	}
 	let output = "";
 	let totalWidth = options.startWidth ?? 0;
-	for (const { text: text$1, width } of stream()) {
+	let pendingWrap = false;
+	let atWrappedLineStart = false;
+	for (const token of stream()) {
+		let { text: text$1, width } = token;
 		if (width === -1) {
 			output += text$1;
 			totalWidth = 0;
+			pendingWrap = false;
+			atWrappedLineStart = false;
+			continue;
+		}
+		const wraps = pendingWrap || options.maxWidth != null && totalWidth > 0 && totalWidth + width > options.maxWidth;
+		if ((wraps || atWrappedLineStart) && token.trimOnWrap) {
+			const trimmed = text$1.trimStart();
+			width -= require_displaywidth.getDisplayWidth(text$1.slice(0, text$1.length - trimmed.length));
+			text$1 = trimmed;
+			if (text$1 === "") {
+				if (wraps) pendingWrap = true;
+				continue;
+			}
+		}
+		if (pendingWrap && require_displaywidth.stripAnsi(text$1) === "") {
+			output += text$1;
 			continue;
 		}
-		if (options.maxWidth != null && totalWidth > 0 && totalWidth + width > options.maxWidth) {
+		if (wraps) {
 			output += "\n";
 			totalWidth = 0;
+			pendingWrap = false;
+			atWrappedLineStart = true;
 		}
 		output += text$1;
 		totalWidth += width;
+		if (width > 0) atWrappedLineStart = false;
 	}
 	return output;
 }

package/dist/message.js

@@ -1,4 +1,4 @@
-import { getDisplayWidth } from "./displaywidth.js";
+import { getDisplayWidth, stripAnsi } from "./displaywidth.js";
 
 //#region src/message.ts
 /**
@@ -324,7 +324,8 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: getDisplayWidth(match[0])
+								width: getDisplayWidth(match[0]),
+								trimOnWrap: true
 							};
 						}
 					}
@@ -332,7 +333,8 @@ function formatMessage(msg, options = {}) {
 					const normalizedText = rawText.replace(/\n/g, " ");
 					if (normalizedText.trim() === "" && normalizedText.length > 0) yield {
 						text: " ",
-						width: 1
+						width: 1,
+						trimOnWrap: true
 					};
 					else {
 						wordPattern.lastIndex = 0;
@@ -341,7 +343,8 @@ function formatMessage(msg, options = {}) {
 							if (match == null) break;
 							yield {
 								text: match[0],
-								width: getDisplayWidth(match[0])
+								width: getDisplayWidth(match[0]),
+								trimOnWrap: true
 							};
 						}
 					}
@@ -381,7 +384,8 @@ function formatMessage(msg, options = {}) {
 			} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
 				if (i > 0) yield {
 					text: " ",
-					width: 1
+					width: 1,
+					trimOnWrap: true
 				};
 				const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 				yield {
@@ -425,18 +429,40 @@ function formatMessage(msg, options = {}) {
 	}
 	let output = "";
 	let totalWidth = options.startWidth ?? 0;
-	for (const { text: text$1, width } of stream()) {
+	let pendingWrap = false;
+	let atWrappedLineStart = false;
+	for (const token of stream()) {
+		let { text: text$1, width } = token;
 		if (width === -1) {
 			output += text$1;
 			totalWidth = 0;
+			pendingWrap = false;
+			atWrappedLineStart = false;
+			continue;
+		}
+		const wraps = pendingWrap || options.maxWidth != null && totalWidth > 0 && totalWidth + width > options.maxWidth;
+		if ((wraps || atWrappedLineStart) && token.trimOnWrap) {
+			const trimmed = text$1.trimStart();
+			width -= getDisplayWidth(text$1.slice(0, text$1.length - trimmed.length));
+			text$1 = trimmed;
+			if (text$1 === "") {
+				if (wraps) pendingWrap = true;
+				continue;
+			}
+		}
+		if (pendingWrap && stripAnsi(text$1) === "") {
+			output += text$1;
 			continue;
 		}
-		if (options.maxWidth != null && totalWidth > 0 && totalWidth + width > options.maxWidth) {
+		if (wraps) {
 			output += "\n";
 			totalWidth = 0;
+			pendingWrap = false;
+			atWrappedLineStart = true;
 		}
 		output += text$1;
 		totalWidth += width;
+		if (width > 0) atWrappedLineStart = false;
 	}
 	return output;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.9",
+  "version": "1.2.10",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.2.9",
+    "@optique/env": "1.2.10",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",