@optique/core 1.0.0-dev.1216 → 1.0.0-dev.1227

package/dist/doc.cjs

@@ -47,9 +47,11 @@ function defaultSectionOrder(a, b) {
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
-* @throws {TypeError} If `programName` contains a CR or LF character, or if
+* @throws {TypeError} If `programName` contains a CR or LF character, if
 * any non-empty section's title is empty, whitespace-only, or contains a CR
-* or LF character.
+* or LF character, or if `maxWidth` is not a finite integer.
+* @throws {RangeError} If any entry needs a description column and `maxWidth`
+* is too small to fit the minimum layout (less than `termIndent + 4`).
 *
 * @example
 * ```typescript
@@ -73,6 +75,20 @@ function formatDocPage(programName, page, options = {}) {
 	if (/[\r\n]/.test(programName)) throw new TypeError("Program name must not contain newlines.");
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
+	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
+	if (options.maxWidth != null) {
+		const hasEntries = page.sections.some((s) => s.entries.length > 0);
+		const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
+		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
+		const minWidth = needsDescColumn ? termIndent + 4 : hasEntries ? termIndent + 1 : 1;
+		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
+	}
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
+	}
 	let output = "";
 	if (page.brief != null) {
 		output += require_message.formatMessage(page.brief, {
@@ -124,9 +140,9 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
-			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2;
+			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - effectiveTermWidth - 2;
 			const termVisibleWidth = lastLineVisibleLength(term);
-			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - termWidth) : 0;
+			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - effectiveTermWidth) : 0;
 			const currentExtraOffset = () => description.includes("\n") ? 0 : extraTermOffset;
 			const descFormatOptions = {
 				colors: options.colors,
@@ -200,7 +216,7 @@ function formatDocPage(programName, page, options = {}) {
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
 			}
-			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
+			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, effectiveTermWidth)}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
 		}
 	}
 	if (page.examples != null) {

package/dist/doc.d.cts

@@ -263,9 +263,11 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
- * @throws {TypeError} If `programName` contains a CR or LF character, or if
+ * @throws {TypeError} If `programName` contains a CR or LF character, if
  * any non-empty section's title is empty, whitespace-only, or contains a CR
- * or LF character.
+ * or LF character, or if `maxWidth` is not a finite integer.
+ * @throws {RangeError} If any entry needs a description column and `maxWidth`
+ * is too small to fit the minimum layout (less than `termIndent + 4`).
  *
  * @example
  * ```typescript

package/dist/doc.d.ts

@@ -263,9 +263,11 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
- * @throws {TypeError} If `programName` contains a CR or LF character, or if
+ * @throws {TypeError} If `programName` contains a CR or LF character, if
  * any non-empty section's title is empty, whitespace-only, or contains a CR
- * or LF character.
+ * or LF character, or if `maxWidth` is not a finite integer.
+ * @throws {RangeError} If any entry needs a description column and `maxWidth`
+ * is too small to fit the minimum layout (less than `termIndent + 4`).
  *
  * @example
  * ```typescript

package/dist/doc.js

@@ -47,9 +47,11 @@ function defaultSectionOrder(a, b) {
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
-* @throws {TypeError} If `programName` contains a CR or LF character, or if
+* @throws {TypeError} If `programName` contains a CR or LF character, if
 * any non-empty section's title is empty, whitespace-only, or contains a CR
-* or LF character.
+* or LF character, or if `maxWidth` is not a finite integer.
+* @throws {RangeError} If any entry needs a description column and `maxWidth`
+* is too small to fit the minimum layout (less than `termIndent + 4`).
 *
 * @example
 * ```typescript
@@ -73,6 +75,20 @@ function formatDocPage(programName, page, options = {}) {
 	if (/[\r\n]/.test(programName)) throw new TypeError("Program name must not contain newlines.");
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
+	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
+	if (options.maxWidth != null) {
+		const hasEntries = page.sections.some((s) => s.entries.length > 0);
+		const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
+		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
+		const minWidth = needsDescColumn ? termIndent + 4 : hasEntries ? termIndent + 1 : 1;
+		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
+	}
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
+	}
 	let output = "";
 	if (page.brief != null) {
 		output += formatMessage(page.brief, {
@@ -124,9 +140,9 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
-			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2;
+			const descColumnWidth = options.maxWidth == null ? void 0 : options.maxWidth - termIndent - effectiveTermWidth - 2;
 			const termVisibleWidth = lastLineVisibleLength(term);
-			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - termWidth) : 0;
+			const extraTermOffset = descColumnWidth != null ? Math.max(0, termVisibleWidth - effectiveTermWidth) : 0;
 			const currentExtraOffset = () => description.includes("\n") ? 0 : extraTermOffset;
 			const descFormatOptions = {
 				colors: options.colors,
@@ -200,7 +216,7 @@ function formatDocPage(programName, page, options = {}) {
 				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
 				description += formattedChoices;
 			}
-			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
+			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, effectiveTermWidth)}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
 		}
 	}
 	if (page.examples != null) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1216+3e445dce",
+  "version": "1.0.0-dev.1227+f9861245",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",