@optique/core 1.3.0-dev.2524 → 1.3.0-dev.2530

package/dist/doc.cjs

@@ -1,5 +1,8 @@
+const require_message_registry = require('./message-registry.cjs');
 const require_displaywidth = require('./displaywidth.cjs');
+const require_terminal_internal = require('./terminal-internal.cjs');
 const require_message = require('./message.cjs');
+const require_message_renderer = require('./message-renderer.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 
@@ -211,6 +214,46 @@ function defaultSectionOrder(a, b) {
 * ```
 */
 function formatDocPage(programName, page, options = {}) {
+	options = {
+		...options,
+		theme: require_terminal_internal.cacheTerminalTheme(options.theme)
+	};
+	const formatMessage = require_message_renderer.resolveMessageFormatter(options);
+	const opaqueFormatter = options.messageFormatter != null && !require_message_registry.messageRenderers.has(options.messageFormatter);
+	const defaultAmbient = options.theme?.annotationStyles?.default ?? { dim: true };
+	const choicesAmbient = options.theme?.annotationStyles?.choices ?? { dim: true };
+	const labelCache = /* @__PURE__ */ new Map();
+	const label = (label$1, kind) => {
+		const key = `${kind}:${label$1}`;
+		let rendered = labelCache.get(key);
+		if (rendered == null) {
+			rendered = require_terminal_internal.renderTerminalTerm({
+				type: "label",
+				label: label$1,
+				kind
+			}, options.theme, options.colors, void 0, kind === "choices" ? choicesAmbient : void 0);
+			labelCache.set(key, rendered);
+		}
+		return rendered;
+	};
+	const punctuationCache = /* @__PURE__ */ new Map();
+	const punctuation = (punctuation$1, kind) => {
+		const key = `${kind}:${punctuation$1}`;
+		let rendered = punctuationCache.get(key);
+		if (rendered == null) {
+			rendered = require_terminal_internal.renderTerminalTerm({
+				type: "syntaxPunctuation",
+				punctuation: punctuation$1,
+				kind
+			}, options.theme, options.colors, void 0, kind.startsWith("default") ? defaultAmbient : kind.startsWith("choices") ? choicesAmbient : void 0);
+			punctuationCache.set(key, rendered);
+		}
+		return rendered;
+	};
+	const usageLabel = page.usage != null && options.showUsage !== false ? label("Usage:", "usage") + " " : "";
+	const usageLabelWidth = require_displaywidth.getDisplayWidth(usageLabel);
+	const defaultStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.default ?? { dim: true });
+	const choicesStyle = require_terminal_internal.styleCode(options.theme?.annotationStyles?.choices ?? { dim: true });
 	require_validate.validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
 	const showUsage = options.showUsage ?? true;
@@ -238,6 +281,7 @@ function formatDocPage(programName, page, options = {}) {
 			if (!needsDescriptionColumn(entry)) continue;
 			const rendered = require_usage.formatUsageTerm(entry.term, {
 				colors: options.colors,
+				theme: options.theme,
 				optionsSeparator: ", ",
 				context: "doc"
 			});
@@ -260,24 +304,27 @@ function formatDocPage(programName, page, options = {}) {
 		let minDescWidth = 1;
 		if (needsDescColumn) {
 			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
-				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
+				const prefix = punctuation(typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [", "defaultPrefix");
 				minDescWidth = Math.max(minDescWidth, require_displaywidth.getDisplayWidth(prefix));
 			}
 			if (options.showChoices && page.sections.some((s) => s.entries.some((e) => hasContent(e.choices)))) {
-				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
-				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
-				minDescWidth = Math.max(minDescWidth, require_displaywidth.getDisplayWidth(prefix) + require_displaywidth.getDisplayWidth(label));
+				const prefix = punctuation(typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (", "choicesPrefix");
+				const choicesLabelText = label(typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ", "choices");
+				minDescWidth = Math.max(minDescWidth, require_displaywidth.getDisplayWidth(prefix) + require_displaywidth.getDisplayWidth(choicesLabelText));
 			}
 		}
 		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 programNameWidth = require_displaywidth.getDisplayWidth(programName);
-		const usageMin = page.usage != null && showUsage ? 7 + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage), programNameWidth + 7)) : 1;
+		const programNameWidth = page.usage != null && showUsage ? Math.max(0, ...[...require_terminal_internal.fragmentTokens(require_terminal_internal.formatTerminalTerm({
+			type: "programName",
+			programName
+		}, options.theme))].map((token) => token.width)) : 0;
+		const usageMin = page.usage != null && showUsage ? usageLabelWidth + Math.max(programNameWidth, Math.min(maxVisibleAtomicWidth(page.usage, options.theme), programNameWidth + usageLabelWidth)) : 1;
 		let sectionMin = 1;
-		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, 9);
-		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, 7);
-		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, 5);
+		if (hasContent(page.examples)) sectionMin = Math.max(sectionMin, require_displaywidth.getDisplayWidth(label("Examples:", "examples")));
+		if (hasContent(page.author)) sectionMin = Math.max(sectionMin, require_displaywidth.getDisplayWidth(label("Author:", "author")));
+		if (hasContent(page.bugs)) sectionMin = Math.max(sectionMin, require_displaywidth.getDisplayWidth(label("Bugs:", "bugs")));
 		const minWidth = Math.max(entryMin, usageMin, sectionMin);
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {
@@ -291,7 +338,7 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	let output = "";
 	if (hasContent(page.brief)) {
-		output += require_message.formatMessage(page.brief, {
+		output += formatMessage(page.brief, {
 			colors: options.colors,
 			maxWidth: options.maxWidth,
 			quotes: !options.colors
@@ -299,18 +346,18 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 	}
 	if (page.usage != null && showUsage) {
-		const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
 		output += usageLabel;
 		output += indentLines(require_usage.formatUsage(programName, page.usage, {
 			colors: options.colors,
-			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
+			theme: options.theme,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - usageLabelWidth,
 			expandCommands: true
-		}), 7);
+		}), usageLabelWidth);
 		output += "\n";
 	}
 	if (hasContent(page.description)) {
 		output += "\n";
-		output += require_message.formatMessage(page.description, {
+		output += formatMessage(page.description, {
 			colors: options.colors,
 			maxWidth: options.maxWidth,
 			quotes: !options.colors
@@ -331,12 +378,13 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 		if (section.title != null) {
 			require_validate.validateLabel(section.title);
-			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
+			const sectionLabel = label(`${section.title}:`, "section") + "\n";
 			output += sectionLabel;
 		}
 		for (const entry of section.entries) {
 			const term = require_usage.formatUsageTerm(entry.term, {
 				colors: options.colors,
+				theme: options.theme,
 				optionsSeparator: ", ",
 				context: "doc",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
@@ -349,12 +397,12 @@ function formatDocPage(programName, page, options = {}) {
 				colors: options.colors,
 				quotes: !options.colors,
 				maxWidth: descColumnWidth,
-				startWidth: extraTermOffset > 0 ? extraTermOffset : void 0
+				initialWidth: extraTermOffset > 0 ? extraTermOffset : void 0
 			};
-			let description = entry.description == null ? "" : require_message.formatMessage(entry.description, descFormatOptions);
+			let description = entry.description == null ? "" : formatMessage(entry.description, descFormatOptions);
 			if (options.showDefault && hasContent(entry.default)) {
-				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
-				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
+				const prefix = punctuation(typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [", "defaultPrefix");
+				const suffix = punctuation(typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]", "defaultSuffix");
 				const prefixWidth = require_displaywidth.getDisplayWidth(prefix);
 				const suffixWidth = require_displaywidth.getDisplayWidth(suffix);
 				let defaultStartWidth;
@@ -367,20 +415,20 @@ function formatDocPage(programName, page, options = {}) {
 					} else defaultStartWidth = effectiveLastW + prefixWidth;
 				}
 				const defaultFormatOptions = {
-					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
+					colors: options.colors ? { resetSuffix: defaultStyle } : false,
 					quotes: !options.colors,
 					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - suffixWidth,
-					startWidth: defaultStartWidth
+					initialWidth: defaultStartWidth
 				};
-				const defaultContent = require_message.formatMessage(entry.default, defaultFormatOptions);
-				const defaultText = `${prefix}${defaultContent}${suffix}`;
-				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
+				const defaultContent = formatMessage(entry.default, defaultFormatOptions, options.theme?.annotationStyles?.default ?? { dim: true });
+				const defaultText = `${prefix}${defaultContent}${opaqueFormatter && options.colors ? defaultStyle : ""}${suffix}`;
+				const formattedDefault = options.colors ? `${defaultStyle}${defaultText}${defaultStyle ? "\x1B[0m" : ""}` : defaultText;
 				description += formattedDefault;
 			}
 			if (options.showChoices && hasContent(entry.choices)) {
-				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
-				const suffix = typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")";
-				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
+				const prefix = punctuation(typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (", "choicesPrefix");
+				const suffix = punctuation(typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")", "choicesSuffix");
+				const choicesLabelText = label(typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ", "choices");
 				const maxItems = typeof options.showChoices === "object" ? options.showChoices.maxItems ?? 8 : 8;
 				const terms = Array.isArray(entry.choices) ? entry.choices : [];
 				let truncatedTerms = terms;
@@ -400,7 +448,7 @@ function formatDocPage(programName, page, options = {}) {
 				}
 				const choicesPrefixWidth = require_displaywidth.getDisplayWidth(prefix);
 				const choicesSuffixWidth = require_displaywidth.getDisplayWidth(suffix);
-				const choicesLabelWidth = require_displaywidth.getDisplayWidth(label);
+				const choicesLabelWidth = require_displaywidth.getDisplayWidth(choicesLabelText);
 				let choicesStartWidth;
 				if (descColumnWidth != null) {
 					const lastW = lastLineVisibleLength(description);
@@ -412,14 +460,14 @@ function formatDocPage(programName, page, options = {}) {
 					} else choicesStartWidth = effectiveLastW + prefixLabelLen;
 				}
 				const choicesFormatOptions = {
-					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
+					colors: options.colors ? { resetSuffix: choicesStyle } : false,
 					quotes: false,
 					maxWidth: descColumnWidth == null ? void 0 : descColumnWidth - choicesSuffixWidth,
-					startWidth: choicesStartWidth
+					initialWidth: choicesStartWidth
 				};
-				const choicesDisplay = require_message.formatMessage(truncatedTerms, choicesFormatOptions);
-				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
-				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
+				const choicesDisplay = formatMessage(truncatedTerms, choicesFormatOptions, options.theme?.annotationStyles?.choices ?? { dim: true });
+				const choicesText = `${prefix}${choicesLabelText}${choicesDisplay}${opaqueFormatter && options.colors ? choicesStyle : ""}${suffix}`;
+				const formattedChoices = options.colors ? `${choicesStyle}${choicesText}${choicesStyle ? "\x1B[0m" : ""}` : choicesText;
 				description += formattedChoices;
 			}
 			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, effectiveTermWidth)}${description === "" ? "" : `  ${indentLines(description, termIndent + effectiveTermWidth + 2)}`}\n`;
@@ -427,9 +475,9 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (hasContent(page.examples)) {
 		output += "\n";
-		const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
+		const examplesLabel = label("Examples:", "examples") + "\n";
 		output += examplesLabel;
-		const examplesContent = require_message.formatMessage(page.examples, {
+		const examplesContent = formatMessage(page.examples, {
 			colors: options.colors,
 			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
 			quotes: !options.colors
@@ -439,9 +487,9 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (hasContent(page.author)) {
 		output += "\n";
-		const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
+		const authorLabel = label("Author:", "author") + "\n";
 		output += authorLabel;
-		const authorContent = require_message.formatMessage(page.author, {
+		const authorContent = formatMessage(page.author, {
 			colors: options.colors,
 			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
 			quotes: !options.colors
@@ -451,9 +499,9 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (hasContent(page.bugs)) {
 		output += "\n";
-		const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
+		const bugsLabel = label("Bugs:", "bugs") + "\n";
 		output += bugsLabel;
-		const bugsContent = require_message.formatMessage(page.bugs, {
+		const bugsContent = formatMessage(page.bugs, {
 			colors: options.colors,
 			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
 			quotes: !options.colors
@@ -463,7 +511,7 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	if (hasContent(page.footer)) {
 		output += "\n";
-		output += require_message.formatMessage(page.footer, {
+		output += formatMessage(page.footer, {
 			colors: options.colors,
 			maxWidth: options.maxWidth,
 			quotes: !options.colors
@@ -480,50 +528,11 @@ function indentLines(text$1, indent) {
 * 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, require_displaywidth.getDisplayWidth(term.metavar));
-			break;
-		case "option":
-			if (!require_usage.isUsageHidden(term.hidden) && term.names.length > 0) {
-				for (const name of term.names) max = Math.max(max, require_displaywidth.getDisplayWidth(name));
-				if (term.metavar != null) max = Math.max(max, require_displaywidth.getDisplayWidth(term.metavar));
-			}
-			break;
-		case "command":
-			if (!require_usage.isUsageHidden(term.hidden)) max = Math.max(max, require_displaywidth.getDisplayWidth(term.name));
-			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 "sequence":
-			max = Math.max(max, maxVisibleAtomicWidth(term.terms));
-			break;
-		case "literal":
-			if (term.value !== "") max = Math.max(max, require_displaywidth.getDisplayWidth(term.value));
-			break;
-		case "ellipsis":
-			max = Math.max(max, 3);
-			break;
-	}
-	return max;
+function maxVisibleAtomicWidth(usage, theme) {
+	return Math.max(0, ...usage.flatMap((term) => require_usage.formatUsageTerm(term, {
+		theme,
+		maxWidth: 1
+	}).split("\n").map(require_displaywidth.getDisplayWidth)));
 }
 function ansiAwareRightPad(text$1, length, char = " ") {
 	const visibleWidth = lastLineVisibleLength(text$1);

package/dist/doc.d.cts

@@ -1,4 +1,5 @@
-import { Message } from "./message.cjs";
+import { Message, MessageFormatter } from "./message.cjs";
+import { TerminalTheme } from "./terminal.cjs";
 import { Usage, UsageTerm } from "./usage.cjs";
 
 //#region src/doc.d.ts
@@ -206,6 +207,16 @@ interface ShowChoicesOptions {
  * Options for formatting a documentation page.
  */
 interface DocPageFormatOptions {
+  /**
+   * Custom message renderer, taking precedence over theme for messages.
+   * @since 1.3.0
+   */
+  readonly messageFormatter?: MessageFormatter;
+  /**
+   * Semantic terminal theme.
+   * @since 1.3.0
+   */
+  readonly theme?: TerminalTheme;
   /**
    * Whether to include ANSI color codes in the output.
    * @default `false`

package/dist/doc.d.ts

@@ -1,4 +1,5 @@
-import { Message } from "./message.js";
+import { Message, MessageFormatter } from "./message.js";
+import { TerminalTheme } from "./terminal.js";
 import { Usage, UsageTerm } from "./usage.js";
 
 //#region src/doc.d.ts
@@ -206,6 +207,16 @@ interface ShowChoicesOptions {
  * Options for formatting a documentation page.
  */
 interface DocPageFormatOptions {
+  /**
+   * Custom message renderer, taking precedence over theme for messages.
+   * @since 1.3.0
+   */
+  readonly messageFormatter?: MessageFormatter;
+  /**
+   * Semantic terminal theme.
+   * @since 1.3.0
+   */
+  readonly theme?: TerminalTheme;
   /**
    * Whether to include ANSI color codes in the output.
    * @default `false`