@optique/core 1.0.0-dev.1470 → 1.0.0-dev.1484

package/dist/doc.cjs

@@ -248,7 +248,7 @@ function formatDocPage(programName, page, options = {}) {
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
 		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
-		const usageMin = page.usage != null ? 8 + programName.length : 1;
+		const usageMin = page.usage != null ? 7 + Math.max(programName.length, Math.min(maxVisibleAtomicWidth(page.usage), programName.length + 7)) : 1;
 		let sectionMin = 1;
 		if (page.examples != null) sectionMin = Math.max(sectionMin, 9);
 		if (page.author != null) sectionMin = Math.max(sectionMin, 7);
@@ -451,6 +451,54 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+/**
+* Returns the width of the widest non-breakable segment among visible
+* (non-usage-hidden) terms in a usage tree.  Hidden terms are excluded
+* because they are filtered out before rendering, so they do not
+* contribute to the rendered width.
+*/
+function maxVisibleAtomicWidth(usage) {
+	let max = 0;
+	for (const term of usage) switch (term.type) {
+		case "argument":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, term.metavar.length);
+			break;
+		case "option":
+			if (!require_usage.isUsageHidden(term.hidden) && term.names.length > 0) {
+				for (const name of term.names) max = Math.max(max, name.length);
+				if (term.metavar != null) max = Math.max(max, term.metavar.length);
+			}
+			break;
+		case "command":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, term.name.length);
+			break;
+		case "passthrough":
+			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, 5);
+			break;
+		case "optional":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
+		case "multiple": {
+			const innerMax = maxVisibleAtomicWidth(term.terms);
+			if (innerMax > 0) max = Math.max(max, 3, innerMax);
+			break;
+		}
+		case "exclusive":
+			for (const branch of term.terms) {
+				const first = branch[0];
+				if (first?.type === "command" && require_usage.isUsageHidden(first.hidden)) continue;
+				max = Math.max(max, maxVisibleAtomicWidth(branch));
+			}
+			break;
+		case "literal":
+			if (term.value !== "") max = Math.max(max, term.value.length);
+			break;
+		case "ellipsis":
+			max = Math.max(max, 3);
+			break;
+	}
+	return max;
+}
 const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 function ansiAwareRightPad(text$1, length, char = " ") {
 	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");

package/dist/doc.js

@@ -1,6 +1,6 @@
 import { cloneMessage, formatMessage, text } from "./message.js";
 import { validateProgramName } from "./validate.js";
-import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
+import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden, isUsageHidden } from "./usage.js";
 
 //#region src/doc.ts
 /**
@@ -248,7 +248,7 @@ function formatDocPage(programName, page, options = {}) {
 		const splitEntryMin = termIndent + 2 + Math.max(2, 2 * minDescWidth - 1);
 		const fixedEntryMin = termIndent + 2 + termWidth + minDescWidth;
 		const entryMin = needsDescColumn ? Math.min(splitEntryMin, fixedEntryMin) : hasEntries ? termIndent + 1 : 1;
-		const usageMin = page.usage != null ? 8 + programName.length : 1;
+		const usageMin = page.usage != null ? 7 + Math.max(programName.length, Math.min(maxVisibleAtomicWidth(page.usage), programName.length + 7)) : 1;
 		let sectionMin = 1;
 		if (page.examples != null) sectionMin = Math.max(sectionMin, 9);
 		if (page.author != null) sectionMin = Math.max(sectionMin, 7);
@@ -451,6 +451,54 @@ function formatDocPage(programName, page, options = {}) {
 function indentLines(text$1, indent) {
 	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
+/**
+* Returns the width of the widest non-breakable segment among visible
+* (non-usage-hidden) terms in a usage tree.  Hidden terms are excluded
+* because they are filtered out before rendering, so they do not
+* contribute to the rendered width.
+*/
+function maxVisibleAtomicWidth(usage) {
+	let max = 0;
+	for (const term of usage) switch (term.type) {
+		case "argument":
+			if (!isUsageHidden(term.hidden)) max = Math.max(max, term.metavar.length);
+			break;
+		case "option":
+			if (!isUsageHidden(term.hidden) && term.names.length > 0) {
+				for (const name of term.names) max = Math.max(max, name.length);
+				if (term.metavar != null) max = Math.max(max, term.metavar.length);
+			}
+			break;
+		case "command":
+			if (!isUsageHidden(term.hidden)) max = Math.max(max, term.name.length);
+			break;
+		case "passthrough":
+			if (!isUsageHidden(term.hidden)) max = Math.max(max, 5);
+			break;
+		case "optional":
+			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
+			break;
+		case "multiple": {
+			const innerMax = maxVisibleAtomicWidth(term.terms);
+			if (innerMax > 0) max = Math.max(max, 3, innerMax);
+			break;
+		}
+		case "exclusive":
+			for (const branch of term.terms) {
+				const first = branch[0];
+				if (first?.type === "command" && isUsageHidden(first.hidden)) continue;
+				max = Math.max(max, maxVisibleAtomicWidth(branch));
+			}
+			break;
+		case "literal":
+			if (term.value !== "") max = Math.max(max, term.value.length);
+			break;
+		case "ellipsis":
+			max = Math.max(max, 3);
+			break;
+	}
+	return max;
+}
 const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
 function ansiAwareRightPad(text$1, length, char = " ") {
 	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");

package/dist/usage.cjs

@@ -164,13 +164,24 @@ function formatUsage(programName, usage, options = {}) {
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
-			return lines.join("\n");
+			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	let output = options.colors ? `\x1b[1m${programName}\x1b[0m ` : `${programName} `;
-	let lineWidth = programName.length + 1;
+	let output = options.colors ? `\x1b[1m${programName}\x1b[0m` : programName;
+	let lineWidth = programName.length;
+	let first = true;
 	for (const { text, width } of formatUsageTerms(usage, options)) {
-		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+		if (first) {
+			first = false;
+			if (options.maxWidth != null && lineWidth + 1 + width > options.maxWidth) {
+				output += "\n";
+				lineWidth = 0;
+			} else {
+				output += " ";
+				lineWidth += 1;
+			}
+		} else if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;
@@ -408,6 +419,7 @@ function formatUsageTerm(term, options = {}) {
 	let output = "";
 	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
 		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;

package/dist/usage.js

@@ -164,13 +164,24 @@ function formatUsage(programName, usage, options = {}) {
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
-			return lines.join("\n");
+			if (lines.length > 0) return lines.join("\n");
 		}
 	}
-	let output = options.colors ? `\x1b[1m${programName}\x1b[0m ` : `${programName} `;
-	let lineWidth = programName.length + 1;
+	let output = options.colors ? `\x1b[1m${programName}\x1b[0m` : programName;
+	let lineWidth = programName.length;
+	let first = true;
 	for (const { text, width } of formatUsageTerms(usage, options)) {
-		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+		if (first) {
+			first = false;
+			if (options.maxWidth != null && lineWidth + 1 + width > options.maxWidth) {
+				output += "\n";
+				lineWidth = 0;
+			} else {
+				output += " ";
+				lineWidth += 1;
+			}
+		} else if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;
@@ -408,6 +419,7 @@ function formatUsageTerm(term, options = {}) {
 	let output = "";
 	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
 		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			if (output.endsWith(" ")) output = output.slice(0, -1);
 			output += "\n";
 			lineWidth = 0;
 			if (text === " ") continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1470+e7499369",
+  "version": "1.0.0-dev.1484+220c0bfd",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",