Respect maxWidth in showDefault and showChoices

formatDocPage() did not apply maxWidth word-wrapping to the default
value and choices annotations appended by showDefault and showChoices.
Both were concatenated directly onto the already-wrapped description
string with no awareness of how many characters were already on the
current line, so lines could far exceed maxWidth.

Fixed by tracking the visible width of the last line of the description
and passing it as an internal startWidth hint to formatMessage(), which
now initializes its line-width counter from that value instead of
always starting from zero.  startWidth is kept out of the public
MessageFormatOptions type via a function overload: only the
implementation signature accepts it.

Regression tests added.

Fixes #129

Co-Authored-By: Claude <claude@anthropic.com>

Author: dahlia

CHANGES.md

@@ -8,6 +8,17 @@ Version 0.10.5
 
 To be released.
 
+### @optique/core
+
+ -  Fixed `formatDocPage()` to respect `maxWidth` when appending default values
+    and available choices via `showDefault` and `showChoices`.  Previously,
+    the appended text was concatenated onto the description string after
+    word-wrapping had already been applied, with no awareness of how much of
+    the current line was already occupied, so lines could far exceed `maxWidth`.
+    [[#129]]
+
+[#129]: https://github.com/dahlia/optique/issues/129
+
 
 Version 0.10.4
 --------------

packages/core/src/doc.test.ts

@@ -857,4 +857,86 @@ describe("formatDocPage", () => {
       "commas should be between value color sequences",
     );
   });
+
+  describe("maxWidth with showDefault and showChoices", () => {
+    it("should not exceed maxWidth when showDefault overflows the line", () => {
+      const page: DocPage = {
+        sections: [{
+          entries: [{
+            term: { type: "option", names: ["--opt"] },
+            description: [{ type: "text", text: "Some option" }],
+            default: [{ type: "text", text: "a very long default value" }],
+          }],
+        }],
+      };
+
+      const result = formatDocPage("myapp", page, {
+        showDefault: true,
+        maxWidth: 50,
+      });
+
+      for (const line of result.split("\n")) {
+        assert.ok(
+          line.length <= 50,
+          `Line exceeds maxWidth 50: "${line}" (${line.length} chars)`,
+        );
+      }
+    });
+
+    it("should not exceed maxWidth when showChoices overflows the line", () => {
+      const page: DocPage = {
+        sections: [{
+          entries: [{
+            term: { type: "option", names: ["-f", "--format"] },
+            description: [{ type: "text", text: "Output format" }],
+            choices: valueSet(
+              ["json", "yaml", "toml", "xml", "csv", "tsv", "html", "markdown"],
+              { type: "unit" },
+            ),
+          }],
+        }],
+      };
+
+      const result = formatDocPage("myapp", page, {
+        showChoices: true,
+        maxWidth: 60,
+      });
+
+      for (const line of result.split("\n")) {
+        assert.ok(
+          line.length <= 60,
+          `Line exceeds maxWidth 60: "${line}" (${line.length} chars)`,
+        );
+      }
+    });
+
+    it("should not exceed maxWidth when both showDefault and showChoices overflow", () => {
+      const page: DocPage = {
+        sections: [{
+          entries: [{
+            term: { type: "option", names: ["-f", "--format"] },
+            description: [{ type: "text", text: "Output format" }],
+            default: [{ type: "text", text: "json" }],
+            choices: valueSet(
+              ["json", "yaml", "toml", "xml", "csv", "tsv", "html", "markdown"],
+              { type: "unit" },
+            ),
+          }],
+        }],
+      };
+
+      const result = formatDocPage("myapp", page, {
+        showDefault: true,
+        showChoices: true,
+        maxWidth: 60,
+      });
+
+      for (const line of result.split("\n")) {
+        assert.ok(
+          line.length <= 60,
+          `Line exceeds maxWidth 60: "${line}" (${line.length} chars)`,
+        );
+      }
+    });
+  });
 });

packages/core/src/doc.ts

@@ -1,6 +1,7 @@
 import {
   formatMessage,
   type Message,
+  type MessageFormatOptions,
   type MessageTerm,
   text,
 } from "./message.ts";
@@ -349,14 +350,16 @@ export function formatDocPage(
           : options.maxWidth - termIndent,
       });
 
+      const descColumnWidth = options.maxWidth == null
+        ? undefined
+        : options.maxWidth - termIndent - termWidth - 2;
+
       let description = entry.description == null
         ? ""
         : formatMessage(entry.description, {
           colors: options.colors,
           quotes: !options.colors,
-          maxWidth: options.maxWidth == null
-            ? undefined
-            : options.maxWidth - termIndent - termWidth - 2,
+          maxWidth: descColumnWidth,
         });
 
       // Append default value if showDefault is enabled and default exists
@@ -367,12 +370,39 @@ export function formatDocPage(
         const suffix = typeof options.showDefault === "object"
           ? options.showDefault.suffix ?? "]"
           : "]";
-        const defaultText = `${prefix}${
-          formatMessage(entry.default, {
-            colors: options.colors ? { resetSuffix: "\x1b[2m" } : false,
-            quotes: !options.colors,
-          })
-        }${suffix}`;
+
+        // Determine startWidth so that word-wrapping in the default value
+        // continues correctly from the current line position.
+        let defaultStartWidth: number | undefined;
+        if (descColumnWidth != null) {
+          const lastW = lastLineVisibleLength(description);
+          if (lastW + prefix.length >= descColumnWidth) {
+            description += "\n";
+            defaultStartWidth = prefix.length;
+          } else {
+            defaultStartWidth = lastW + prefix.length;
+          }
+        }
+
+        // `startWidth` is accepted by the formatMessage() implementation but
+        // is absent from the public MessageFormatOptions type.  The inline
+        // intersection type makes TypeScript accept the field here while
+        // keeping it out of the public API.  Because the intersection type is
+        // a subtype of MessageFormatOptions, the call below remains
+        // type-safe.
+        const defaultFormatOptions: MessageFormatOptions & {
+          readonly startWidth?: number;
+        } = {
+          colors: options.colors ? { resetSuffix: "\x1b[2m" } : false,
+          quotes: !options.colors,
+          maxWidth: descColumnWidth,
+          startWidth: defaultStartWidth,
+        };
+        const defaultContent = formatMessage(
+          entry.default,
+          defaultFormatOptions,
+        );
+        const defaultText = `${prefix}${defaultContent}${suffix}`;
         const formattedDefault = options.colors
           ? `\x1b[2m${defaultText}\x1b[0m`
           : defaultText;
@@ -418,10 +448,35 @@ export function formatDocPage(
             ];
           }
         }
-        const choicesDisplay = formatMessage(truncatedTerms, {
+        // Determine startWidth so that word-wrapping in the choices list
+        // continues correctly from the current line position.
+        let choicesStartWidth: number | undefined;
+        if (descColumnWidth != null) {
+          const lastW = lastLineVisibleLength(description);
+          const prefixLabelLen = prefix.length + label.length;
+          if (lastW + prefixLabelLen >= descColumnWidth) {
+            description += "\n";
+            choicesStartWidth = prefixLabelLen;
+          } else {
+            choicesStartWidth = lastW + prefixLabelLen;
+          }
+        }
+
+        // See the comment above the defaultFormatOptions variable for why
+        // startWidth is passed via a typed variable rather than an inline
+        // object literal.
+        const choicesFormatOptions: MessageFormatOptions & {
+          readonly startWidth?: number;
+        } = {
           colors: options.colors ? { resetSuffix: "\x1b[2m" } : false,
           quotes: false,
-        });
+          maxWidth: descColumnWidth,
+          startWidth: choicesStartWidth,
+        };
+        const choicesDisplay = formatMessage(
+          truncatedTerms,
+          choicesFormatOptions,
+        );
         const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
         const formattedChoices = options.colors
           ? `\x1b[2m${choicesText}\x1b[0m`
@@ -494,16 +549,23 @@ function indentLines(text: string, indent: number): string {
   return text.split("\n").join("\n" + " ".repeat(indent));
 }
 
+// deno-lint-ignore no-control-regex
+const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
+
 function ansiAwareRightPad(
   text: string,
   length: number,
   char: string = " ",
 ): string {
-  // deno-lint-ignore no-control-regex
-  const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
   const strippedText = text.replace(ansiEscapeCodeRegex, "");
   if (strippedText.length >= length) {
     return text;
   }
   return text + char.repeat(length - strippedText.length);
 }
+
+function lastLineVisibleLength(text: string): number {
+  const lastNewline = text.lastIndexOf("\n");
+  const lastLine = lastNewline === -1 ? text : text.slice(lastNewline + 1);
+  return lastLine.replace(ansiEscapeCodeRegex, "").length;
+}

packages/core/src/message.ts

@@ -496,7 +496,17 @@ export interface MessageFormatOptions {
  */
 export function formatMessage(
   msg: Message,
-  options: MessageFormatOptions = {},
+  options?: MessageFormatOptions,
+): string;
+// The implementation accepts an additional `startWidth` field that is not
+// part of the public API.  Other formatters within this package (e.g.,
+// formatDocPage() in doc.ts) pass it as a plain object variable — not as
+// an inline object literal — so TypeScript's excess-property check does not
+// apply and the field reaches the implementation without being part of the
+// declared public type.
+export function formatMessage(
+  msg: Message,
+  options: MessageFormatOptions & { readonly startWidth?: number } = {},
 ): string {
   // Apply defaults
   const colorConfig = options.colors ?? false;
@@ -671,7 +681,7 @@ export function formatMessage(
   }
 
   let output = "";
-  let totalWidth = 0;
+  let totalWidth = options.startWidth ?? 0;
   for (const { text, width } of stream()) {
     // Handle hard line breaks (marked with width -1)
     if (width === -1) {