fix(help): Correctly calculate wrap points with ANSI escape codes

clap_builder/Cargo.toml

@@ -71,6 +71,7 @@ unicode-width = { version = "0.2.0", optional = true }
 static_assertions = "1.1.0"
 unic-emoji-char = "0.9.0"
 color-print = "0.3.6"
+snapbox = { version = "0.6.16" }
 
 [lints]
 workspace = true

clap_builder/src/builder/styled_str.rs

@@ -209,3 +209,46 @@ impl std::fmt::Display for StyledStr {
         Ok(())
     }
 }
+
+#[cfg(test)]
+#[cfg(feature = "wrap_help")]
+mod wrap_tests {
+    use super::*;
+
+    use snapbox::assert_data_eq;
+    use snapbox::str;
+
+    #[test]
+    #[cfg(feature = "wrap_help")]
+    fn wrap_unstyled() {
+        let style = anstyle::Style::new();
+        let input = format!("{style}12345{style:#} {style}12345{style:#} {style}12345{style:#} {style}12345{style:#}");
+        let mut actual = StyledStr::new();
+        actual.push_string(input);
+        actual.wrap(20);
+        assert_data_eq!(
+            actual.ansi().to_string(),
+            str![[r#"
+12345 12345 12345
+12345
+"#]]
+        );
+    }
+
+    #[test]
+    #[cfg(feature = "wrap_help")]
+    fn wrap_styled() {
+        let style = anstyle::Style::new().bold();
+        let input = format!("{style}12345{style:#} {style}12345{style:#} {style}12345{style:#} {style}12345{style:#}");
+        let mut actual = StyledStr::new();
+        actual.push_string(input);
+        actual.wrap(20);
+        assert_data_eq!(
+            actual.ansi().to_string(),
+            str![[r#"
+12345 12345 12345 
+12345
+"#]]
+        );
+    }
+}

clap_builder/src/output/textwrap/mod.rs

@@ -92,7 +92,7 @@ mod test {
         // will be empty. This is because the string is split into
         // words like [" ", "foobar ", "baz"], which puts "foobar " on
         // the second line. We never output trailing whitespace
-        assert_eq!(wrap(" foobar baz", 6), vec!["", " foobar", " baz"]);
+        assert_eq!(wrap(" foobar baz", 6), vec![" foobar", " baz"]);
     }
 
     #[test]

clap_builder/src/output/textwrap/wrap_algorithms.rs

@@ -4,30 +4,32 @@ use super::core::display_width;
 pub(crate) struct LineWrapper<'w> {
     hard_width: usize,
     line_width: usize,
-    carryover: Option<&'w str>,
+    indentation: Option<&'w str>,
 }
 
 impl<'w> LineWrapper<'w> {
     pub(crate) fn new(hard_width: usize) -> Self {
         Self {
             hard_width,
             line_width: 0,
-            carryover: None,
+            indentation: None,
         }
     }
 
     pub(crate) fn reset(&mut self) {
         self.line_width = 0;
-        self.carryover = None;
+        self.indentation = None;
     }
 
     pub(crate) fn wrap(&mut self, mut words: Vec<&'w str>) -> Vec<&'w str> {
-        if self.carryover.is_none() {
+        let mut first_word = false;
+        if self.indentation.is_none() {
+            first_word = true;
             if let Some(word) = words.first() {
                 if word.trim().is_empty() {
-                    self.carryover = Some(*word);
+                    self.indentation = Some(*word);
                 } else {
-                    self.carryover = Some("");
+                    self.indentation = Some("");
                 }
             }
         }
@@ -38,19 +40,22 @@ impl<'w> LineWrapper<'w> {
             let trimmed = word.trim_end();
             let word_width = display_width(trimmed);
             let trimmed_delta = word.len() - trimmed.len();
-            if i != 0 && self.hard_width < self.line_width + word_width {
+            if first_word && 0 < word_width {
+                // Never try to wrap the first word
+                first_word = false;
+            } else if self.hard_width < self.line_width + word_width {
                 if 0 < i {
-                    let last = i - 1;
-                    let trimmed = words[last].trim_end();
-                    words[last] = trimmed;
+                    let prev = i - 1;
+                    let trimmed = words[prev].trim_end();
+                    words[prev] = trimmed;
                 }
 
                 self.line_width = 0;
                 words.insert(i, "\n");
                 i += 1;
-                if let Some(carryover) = self.carryover {
-                    words.insert(i, carryover);
-                    self.line_width += carryover.len();
+                if let Some(indentation) = self.indentation {
+                    words.insert(i, indentation);
+                    self.line_width += indentation.len();
                     i += 1;
                 }
             }

src/bin/stdio-fixture.rs

@@ -5,6 +5,8 @@ fn main() {
     let mut cmd = Command::new("stdio-fixture")
         .version("1.0")
         .long_version("1.0 - a2132c")
+        .term_width(0)
+        .max_term_width(0)
         .arg_required_else_help(true)
         .subcommand(Command::new("more"))
         .subcommand(