wrap_ansi/

lib.rs

//! # 🎨 wrap-ansi
//!
//! [![Crates.io](https://img.shields.io/crates/v/wrap-ansi.svg)](https://crates.io/crates/wrap-ansi)
//! [![Documentation](https://docs.rs/wrap-ansi/badge.svg)](https://docs.rs/wrap-ansi)
//! [![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)
//! [![Build Status](https://github.com/sabry-awad97/wrap-ansi/workflows/CI/badge.svg)](https://github.com/sabry-awad97/wrap-ansi/actions)
//!
//! A **high-performance**, **Unicode-aware** Rust library for intelligently wrapping text while
//! preserving ANSI escape sequences, colors, styles, and hyperlinks.
//!
//! This library is a faithful Rust port of the popular JavaScript
//! [wrap-ansi](https://github.com/chalk/wrap-ansi) library, designed for terminal applications,
//! CLI tools, and any software that needs to display formatted text in constrained widths.
//!
//! ## ✨ Key Features
//!
//! | Feature | Description |
//! |---------|-------------|
//! | 🎨 **ANSI-Aware Wrapping** | Preserves colors, styles, and formatting across line breaks |
//! | 🔗 **Hyperlink Support** | Maintains clickable OSC 8 hyperlinks when wrapping |
//! | 🌍 **Unicode Ready** | Correctly handles CJK characters, emojis, and combining marks |
//! | ⚡ **High Performance** | Optimized algorithms with pre-compiled regex patterns |
//! | 🛠️ **Flexible Options** | Hard/soft wrapping, trimming, word boundaries control |
//! | 🔒 **Memory Safe** | Built-in protection against `DoS` attacks with input size limits |
//! | 📚 **Rich API** | Fluent builder pattern and comprehensive error handling |
//!
//! ## 🚀 Quick Start
//!
//! Add this to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! wrap-ansi = "0.1.0"
//! ```
//!
//! ### Basic Text Wrapping
//!
//! ```rust
//! use wrap_ansi::wrap_ansi;
//!
//! let text = "The quick brown fox jumps over the lazy dog";
//! let wrapped = wrap_ansi(text, 20, None);
//! println!("{}", wrapped);
//! // Output:
//! // The quick brown fox
//! // jumps over the lazy
//! // dog
//! ```
//!
//! ### ANSI Colors & Styles
//!
//! ```rust
//! use wrap_ansi::wrap_ansi;
//!
//! // Colors are preserved across line breaks!
//! let colored = "\u{001B}[31mThis is red text that will be wrapped properly\u{001B}[39m";
//! let wrapped = wrap_ansi(colored, 15, None);
//! println!("{}", wrapped);
//! // Each line will have proper color codes: \u{001B}[31m...\u{001B}[39m
//! ```
//!
//! ### Advanced Configuration
//!
//! ```rust
//! use wrap_ansi::{wrap_ansi, WrapOptions};
//!
//! // Using the builder pattern for clean configuration
//! let options = WrapOptions::builder()
//!     .hard_wrap(true)           // Break long words
//!     .trim_whitespace(false)    // Preserve whitespace
//!     .word_wrap(true)           // Respect word boundaries
//!     .build();
//!
//! let text = "supercalifragilisticexpialidocious word";
//! let wrapped = wrap_ansi(text, 10, Some(options));
//! println!("{}", wrapped);
//! // Output:
//! // supercalif
//! // ragilistic
//! // expialidoc
//! // ious word
//! ```
//!
//! ## 🎯 Use Cases
//!
//! Perfect for:
//!
//! - **CLI Applications**: Format help text, error messages, and output
//! - **Terminal UIs**: Create responsive layouts that adapt to terminal width
//! - **Documentation Tools**: Generate formatted text with preserved styling
//! - **Log Processing**: Wrap log entries while maintaining color coding
//! - **Code Formatters**: Handle syntax-highlighted code with proper wrapping
//!
//! ## 🌟 Advanced Features
//!
//! ### Wrapping Modes
//!
//! | Mode | Behavior | Use Case |
//! |------|----------|----------|
//! | **Soft Wrap** (default) | Long words move to next line intact | Natural text flow |
//! | **Hard Wrap** | Long words break at column boundary | Strict width constraints |
//! | **Character Wrap** | Break anywhere, ignore word boundaries | Monospace layouts |
//!
//! ### ANSI Sequence Support
//!
//! ✅ **Foreground Colors**: Standard (30-37) and bright (90-97)
//! ✅ **Background Colors**: Standard (40-47) and bright (100-107)
//! ✅ **Text Styles**: Bold, italic, underline, strikethrough
//! ✅ **Color Resets**: Proper handling of reset sequences (39, 49)
//! ✅ **Hyperlinks**: OSC 8 sequences for clickable terminal links
//! ✅ **Custom SGR**: Support for any Select Graphic Rendition codes  
//!
//! ### Unicode & Internationalization
//!
//! ```rust
//! use wrap_ansi::{wrap_ansi, WrapOptions};
//!
//! // CJK characters are properly counted as 2 columns
//! let chinese = "你好世界，这是一个测试";
//! let wrapped = wrap_ansi(chinese, 8, None);
//!
//! // Emojis and combining characters work correctly
//! let emoji = "Hello 👋 World 🌍 with emojis";
//! let options = WrapOptions::builder().hard_wrap(true).build();
//! let wrapped = wrap_ansi(emoji, 10, Some(options));
//! ```
//!
//! ## 🔧 Error Handling
//!
//! For applications requiring robust error handling:
//!
//! ```rust
//! use wrap_ansi::{wrap_ansi_checked, WrapError};
//!
//! let text = "Hello, world!";
//! match wrap_ansi_checked(text, 0, None) {
//!     Ok(wrapped) => println!("Wrapped: {}", wrapped),
//!     Err(WrapError::InvalidColumnWidth(width)) => {
//!         eprintln!("Invalid width: {}", width);
//!     }
//!     Err(WrapError::InputTooLarge(size, max)) => {
//!         eprintln!("Input too large: {} bytes (max: {})", size, max);
//!     }
//!     _ => {}
//! }
//! ```
//!
//! ## 📊 Performance
//!
//! - **Zero-copy operations** where possible
//! - **Pre-compiled regex patterns** for ANSI sequence parsing
//! - **Efficient string operations** with capacity pre-allocation
//! - **`DoS` protection** with configurable input size limits
//! - **Minimal allocations** through careful memory management
//!
//! ## 🤝 Compatibility
//!
//! - **Rust Edition**: 2021+
//! - **MSRV**: 1.70.0
//! - **Platforms**: All platforms supported by Rust
//! - **Terminal Compatibility**: Works with all ANSI-compatible terminals
//!
//! ## 📚 Examples
//!
//! Check out the [examples directory](https://github.com/sabry-awad97/wrap-ansi/tree/main/examples)
//! for more comprehensive usage examples, including:
//!
//! - Terminal UI layouts
//! - Progress bars with colors
//! - Syntax highlighting preservation
//! - Interactive CLI applications

#![cfg_attr(docsrs, feature(doc_cfg))]
#![deny(missing_docs)]
#![warn(clippy::all)]
#![warn(clippy::pedantic)]
#![warn(clippy::nursery)]
#![warn(clippy::cargo)]

use ansi_escape_sequences::strip_ansi;
use regex::Regex;
use string_width::string_width;

/// ANSI SGR (Select Graphic Rendition) codes and escape sequences
mod ansi_codes {
    /// ANSI escape characters
    pub const ESCAPE_ESC: char = '\u{001B}';
    pub const ESCAPE_CSI: char = '\u{009B}';
    pub const ANSI_ESCAPE_BELL: char = '\u{0007}';
    pub const ANSI_CSI: &str = "[";
    pub const ANSI_SGR_TERMINATOR: char = 'm';
    pub const ANSI_ESCAPE_LINK: &str = "]8;;";

    // Foreground colors (standard)
    pub const FG_BLACK: u8 = 30;
    // pub const FG_RED: u8 = 31;
    // pub const FG_GREEN: u8 = 32;
    // pub const FG_YELLOW: u8 = 33;
    // pub const FG_BLUE: u8 = 34;
    // pub const FG_MAGENTA: u8 = 35;
    // pub const FG_CYAN: u8 = 36;
    pub const FG_WHITE: u8 = 37;
    pub const FG_RESET: u8 = 39;

    // Background colors (standard)
    pub const BG_BLACK: u8 = 40;
    // pub const BG_RED: u8 = 41;
    // pub const BG_GREEN: u8 = 42;
    // pub const BG_YELLOW: u8 = 43;
    // pub const BG_BLUE: u8 = 44;
    // pub const BG_MAGENTA: u8 = 45;
    // pub const BG_CYAN: u8 = 46;
    pub const BG_WHITE: u8 = 47;
    pub const BG_RESET: u8 = 49;

    // Bright foreground colors
    pub const FG_BRIGHT_BLACK: u8 = 90;
    // pub const FG_BRIGHT_RED: u8 = 91;
    // pub const FG_BRIGHT_GREEN: u8 = 92;
    // pub const FG_BRIGHT_YELLOW: u8 = 93;
    // pub const FG_BRIGHT_BLUE: u8 = 94;
    // pub const FG_BRIGHT_MAGENTA: u8 = 95;
    // pub const FG_BRIGHT_CYAN: u8 = 96;
    pub const FG_BRIGHT_WHITE: u8 = 97;

    // Bright background colors
    pub const BG_BRIGHT_BLACK: u8 = 100;
    // pub const BG_BRIGHT_RED: u8 = 101;
    // pub const BG_BRIGHT_GREEN: u8 = 102;
    // pub const BG_BRIGHT_YELLOW: u8 = 103;
    // pub const BG_BRIGHT_BLUE: u8 = 104;
    // pub const BG_BRIGHT_MAGENTA: u8 = 105;
    // pub const BG_BRIGHT_CYAN: u8 = 106;
    pub const BG_BRIGHT_WHITE: u8 = 107;

    // Ranges for easier checking
    pub const FG_STANDARD_RANGE: std::ops::RangeInclusive<u8> = FG_BLACK..=FG_WHITE;
    pub const BG_STANDARD_RANGE: std::ops::RangeInclusive<u8> = BG_BLACK..=BG_WHITE;
    pub const FG_BRIGHT_RANGE: std::ops::RangeInclusive<u8> = FG_BRIGHT_BLACK..=FG_BRIGHT_WHITE;
    pub const BG_BRIGHT_RANGE: std::ops::RangeInclusive<u8> = BG_BRIGHT_BLACK..=BG_BRIGHT_WHITE;
}

/// Comprehensive error types for wrap-ansi operations.
///
/// This enum provides detailed error information for various failure modes
/// that can occur during text wrapping operations.
///
/// # Examples
///
/// ```rust
/// use wrap_ansi::{wrap_ansi_checked, WrapError};
///
/// // Handle invalid column width
/// match wrap_ansi_checked("test", 0, None) {
///     Err(WrapError::InvalidColumnWidth(width)) => {
///         println!("Column width {} is invalid, must be > 0", width);
///     }
///     Ok(result) => println!("Wrapped: {}", result),
///     _ => {}
/// }
///
/// // Handle input size limits
/// let huge_input = "x".repeat(20_000_000);
/// match wrap_ansi_checked(&huge_input, 80, None) {
///     Err(WrapError::InputTooLarge(size, max_size)) => {
///         println!("Input {} bytes exceeds limit of {} bytes", size, max_size);
///     }
///     Ok(result) => println!("Wrapped successfully"),
///     _ => {}
/// }
/// ```
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum WrapError {
    /// Column width must be greater than 0.
    ///
    /// This error occurs when attempting to wrap text with a column width of 0,
    /// which would be impossible to satisfy.
    #[error("Column width must be greater than 0, got {0}")]
    InvalidColumnWidth(usize),

    /// Input string is too large to process safely.
    ///
    /// This error provides protection against potential `DoS` attacks by limiting
    /// the maximum input size that can be processed.
    #[error("Input string is too large: {0} characters (max: {1})")]
    InputTooLarge(usize, usize),
}

/// Classification of ANSI SGR codes for proper handling
#[derive(Debug, Clone, PartialEq)]
enum AnsiCodeType {
    /// Foreground color code
    Foreground(u8),
    /// Background color code
    Background(u8),
    /// Foreground color reset
    ForegroundReset,
    /// Background color reset
    BackgroundReset,
    /// Other SGR code (bold, italic, etc.)
    Other(u8),
}

/// Represents the current ANSI state while processing text
#[derive(Debug, Default, Clone)]
struct AnsiState {
    /// Current foreground color code
    foreground_code: Option<u8>,
    /// Current background color code
    background_code: Option<u8>,
    /// Current hyperlink URL
    hyperlink_url: Option<String>,
}

impl AnsiState {
    /// Reset the foreground color
    const fn reset_foreground(&mut self) {
        self.foreground_code = None;
    }

    /// Reset the background color
    const fn reset_background(&mut self) {
        self.background_code = None;
    }

    /// Close the current hyperlink
    #[allow(unused)]
    fn close_hyperlink(&mut self) {
        self.hyperlink_url = None;
    }

    /// Generate ANSI codes to apply before a newline (closing codes)
    fn apply_before_newline(&self) -> String {
        let mut result = String::new();

        if self.hyperlink_url.is_some() {
            result.push_str(&wrap_ansi_hyperlink(""));
        }
        if self.foreground_code.is_some() {
            result.push_str(&wrap_ansi_code(ansi_codes::FG_RESET));
        }
        if self.background_code.is_some() {
            result.push_str(&wrap_ansi_code(ansi_codes::BG_RESET));
        }

        result
    }

    /// Generate ANSI codes to apply after a newline (opening codes)
    fn apply_after_newline(&self) -> String {
        let mut result = String::new();

        if let Some(code) = self.foreground_code {
            result.push_str(&wrap_ansi_code(code));
        }
        if let Some(code) = self.background_code {
            result.push_str(&wrap_ansi_code(code));
        }
        if let Some(ref url) = self.hyperlink_url {
            result.push_str(&wrap_ansi_hyperlink(url));
        }

        result
    }

    /// Update state based on an ANSI code
    fn update_with_code(&mut self, code: u8) {
        match classify_ansi_code(code) {
            AnsiCodeType::Foreground(c) => self.foreground_code = Some(c),
            AnsiCodeType::Background(c) => self.background_code = Some(c),
            AnsiCodeType::ForegroundReset => self.reset_foreground(),
            AnsiCodeType::BackgroundReset => self.reset_background(),
            AnsiCodeType::Other(_) => {
                // Handle other codes as needed
                // For now, treat unknown codes as foreground for backward compatibility
                self.foreground_code = Some(code);
            }
        }
    }

    /// Update state with a hyperlink URL
    fn update_with_hyperlink(&mut self, url: &str) {
        self.hyperlink_url = if url.is_empty() {
            None
        } else {
            Some(url.to_string())
        };
    }
}

/// State machine for parsing ANSI escape sequences
#[derive(Debug, PartialEq)]
enum ParseState {
    /// Normal text processing
    Normal,
    /// Inside an escape sequence (after ESC)
    InEscape,
    /// Inside a CSI sequence (after ESC[)
    InCsi,
    /// Inside an OSC sequence (after ESC])
    InOsc,
}

/// ANSI escape sequence parser
struct AnsiParser {
    state: ParseState,
}

impl AnsiParser {
    /// Create a new ANSI parser
    const fn new() -> Self {
        Self {
            state: ParseState::Normal,
        }
    }

    /// Check if currently inside an ANSI sequence
    fn is_in_sequence(&self) -> bool {
        self.state != ParseState::Normal
    }

    /// Process a character and update parser state
    const fn process_char(&mut self, ch: char) {
        use ansi_codes::{ANSI_ESCAPE_BELL, ANSI_SGR_TERMINATOR, ESCAPE_ESC};

        match (&self.state, ch) {
            (ParseState::Normal, ESCAPE_ESC) => {
                self.state = ParseState::InEscape;
            }
            (ParseState::InEscape, '[') => {
                self.state = ParseState::InCsi;
            }
            (ParseState::InEscape, ']') => {
                self.state = ParseState::InOsc;
            }
            (ParseState::InCsi, ANSI_SGR_TERMINATOR) | (ParseState::InOsc, ANSI_ESCAPE_BELL) => {
                self.state = ParseState::Normal;
            }
            _ => {}
        }
    }
}

/// Classify an ANSI SGR code for proper handling
fn classify_ansi_code(code: u8) -> AnsiCodeType {
    use ansi_codes::{
        BG_BRIGHT_RANGE, BG_RESET, BG_STANDARD_RANGE, FG_BRIGHT_RANGE, FG_RESET, FG_STANDARD_RANGE,
    };

    match code {
        FG_RESET => AnsiCodeType::ForegroundReset,
        BG_RESET => AnsiCodeType::BackgroundReset,
        code if FG_STANDARD_RANGE.contains(&code) || FG_BRIGHT_RANGE.contains(&code) => {
            AnsiCodeType::Foreground(code)
        }
        code if BG_STANDARD_RANGE.contains(&code) || BG_BRIGHT_RANGE.contains(&code) => {
            AnsiCodeType::Background(code)
        }
        code => AnsiCodeType::Other(code),
    }
}

/// 🎛️ Configuration options for advanced text wrapping behavior.
///
/// This struct provides fine-grained control over how text is wrapped, including
/// whitespace handling, word breaking strategies, and wrapping modes. All options
/// work seamlessly with ANSI escape sequences and Unicode text.
///
/// # Quick Reference
///
/// | Option | Default | Description |
/// |--------|---------|-------------|
/// | `trim` | `true` | Remove leading/trailing whitespace from wrapped lines |
/// | `hard` | `false` | Break long words at column boundary (vs. moving to next line) |
/// | `word_wrap` | `true` | Respect word boundaries when wrapping |
///
/// # Examples
///
/// ## Default Configuration
/// ```rust
/// use wrap_ansi::{wrap_ansi, WrapOptions};
///
/// // These are equivalent
/// let result1 = wrap_ansi("Hello world", 10, None);
/// let result2 = wrap_ansi("Hello world", 10, Some(WrapOptions::default()));
/// assert_eq!(result1, result2);
/// ```
///
/// ## Builder Pattern (Recommended)
/// ```rust
/// use wrap_ansi::{wrap_ansi, WrapOptions};
///
/// let options = WrapOptions::builder()
///     .hard_wrap(true)           // Break long words
///     .trim_whitespace(false)    // Preserve all whitespace
///     .word_wrap(true)           // Still respect word boundaries where possible
///     .build();
///
/// let text = "supercalifragilisticexpialidocious";
/// let wrapped = wrap_ansi(text, 10, Some(options));
/// // Result: "supercalif\nragilistic\nexpialidoc\nious"
/// ```
///
/// ## Struct Initialization
/// ```rust
/// use wrap_ansi::{wrap_ansi, WrapOptions};
///
/// // Character-level wrapping for monospace layouts
/// let char_wrap = WrapOptions {
///     hard: true,
///     trim: true,
///     word_wrap: false,  // Break anywhere, ignore word boundaries
/// };
///
/// let text = "hello world";
/// let wrapped = wrap_ansi(text, 7, Some(char_wrap));
/// // Result: "hello w\norld"
/// ```
///
/// ## Common Configurations
///
/// ### Terminal Output (Default)
/// ```rust
/// # use wrap_ansi::WrapOptions;
/// let terminal = WrapOptions::default(); // Soft wrap, trim spaces, respect words
/// ```
///
/// ### Code/Monospace Text
/// ```rust
/// # use wrap_ansi::WrapOptions;
/// let code = WrapOptions {
///     hard: true,        // Break long identifiers
///     trim: false,       // Preserve indentation
///     word_wrap: false,  // Break anywhere for consistent columns
/// };
/// ```
///
/// ### Natural Language
/// ```rust
/// # use wrap_ansi::WrapOptions;
/// let prose = WrapOptions {
///     hard: false,       // Keep words intact
///     trim: true,        // Clean up spacing
///     word_wrap: true,   // Break at word boundaries
/// };
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct WrapOptions {
    /// 🧹 **Whitespace trimming control**
    ///
    /// When `true` (default), leading and trailing spaces are automatically removed
    /// from lines that result from wrapping, creating clean, left-aligned text.
    /// When `false`, all whitespace is preserved exactly as in the input.
    ///
    /// # Use Cases
    /// - `true`: Clean terminal output, formatted text display
    /// - `false`: Code formatting, preserving indentation, ASCII art
    ///
    /// # Examples
    /// ```rust
    /// use wrap_ansi::{wrap_ansi, WrapOptions};
    ///
    /// let text = "   hello    world   ";
    ///
    /// // With trimming (default)
    /// let trimmed = wrap_ansi(text, 8, None);
    /// assert_eq!(trimmed, "hello\nworld");
    ///
    /// // Without trimming - preserves all spaces
    /// let options = WrapOptions { trim: false, ..Default::default() };
    /// let untrimmed = wrap_ansi(text, 8, Some(options));
    /// assert_eq!(untrimmed, "   hello\n    \nworld   ");
    /// ```
    pub trim: bool,

    /// ⚡ **Word breaking strategy**
    ///
    /// Controls how long words that exceed the column limit are handled:
    /// - `false` (default, **soft wrapping**): Long words move to the next line intact
    /// - `true` (**hard wrapping**): Long words are broken at the column boundary
    ///
    /// # Use Cases
    /// - Soft wrap: Natural text flow, readability, terminal output
    /// - Hard wrap: Strict width constraints, tabular data, code formatting
    ///
    /// # Examples
    /// ```rust
    /// use wrap_ansi::{wrap_ansi, WrapOptions};
    ///
    /// let long_word = "supercalifragilisticexpialidocious";
    ///
    /// // Soft wrapping - word stays intact
    /// let soft = wrap_ansi(long_word, 10, None);
    /// assert_eq!(soft, "supercalifragilisticexpialidocious"); // No wrapping!
    ///
    /// // Hard wrapping - word is broken
    /// let options = WrapOptions { hard: true, ..Default::default() };
    /// let hard = wrap_ansi(long_word, 10, Some(options));
    /// assert_eq!(hard, "supercalif\nragilistic\nexpialidoc\nious");
    /// ```
    pub hard: bool,

    /// 🔤 **Word boundary respect**
    ///
    /// Determines whether wrapping should occur at word boundaries (spaces) or
    /// can break anywhere within the text:
    /// - `true` (default): Text wraps at word boundaries, preserving word integrity
    /// - `false`: Text can wrap at any character position (character-level wrapping)
    ///
    /// # Use Cases
    /// - Word boundaries: Natural language, readable text, most terminal output
    /// - Character boundaries: Monospace layouts, code, precise column control
    ///
    /// # Examples
    /// ```rust
    /// use wrap_ansi::{wrap_ansi, WrapOptions};
    ///
    /// let text = "hello world";
    ///
    /// // Word wrapping (default) - breaks at spaces
    /// let word_wrap = wrap_ansi(text, 7, None);
    /// assert_eq!(word_wrap, "hello\nworld");
    ///
    /// // Character wrapping - breaks anywhere
    /// let options = WrapOptions { word_wrap: false, ..Default::default() };
    /// let char_wrap = wrap_ansi(text, 7, Some(options));
    /// assert_eq!(char_wrap, "hello w\norld");
    /// ```
    pub word_wrap: bool,
}

impl Default for WrapOptions {
    fn default() -> Self {
        Self {
            trim: true,
            hard: false,
            word_wrap: true,
        }
    }
}

/// 🏗️ Fluent builder for creating `WrapOptions` with a clean, readable interface.
///
/// This builder provides a more ergonomic way to configure wrapping options
/// compared to struct initialization, especially when you only need to change
/// a few settings from the defaults.
///
/// # Examples
///
/// ## Basic Usage
/// ```rust
/// use wrap_ansi::WrapOptions;
///
/// let options = WrapOptions::builder()
///     .hard_wrap(true)
///     .build();
/// ```
///
/// ## Method Chaining
/// ```rust
/// use wrap_ansi::{wrap_ansi, WrapOptions};
///
/// let result = wrap_ansi(
///     "Some long text that needs wrapping",
///     15,
///     Some(WrapOptions::builder()
///         .hard_wrap(true)
///         .trim_whitespace(false)
///         .word_wrap(true)
///         .build())
/// );
/// ```
///
/// ## Conditional Configuration
/// ```rust
/// use wrap_ansi::WrapOptions;
///
/// let preserve_formatting = true;
/// let strict_width = false;
///
/// let options = WrapOptions::builder()
///     .trim_whitespace(!preserve_formatting)
///     .hard_wrap(strict_width)
///     .build();
/// ```
#[derive(Debug, Default, Clone)]
pub struct WrapOptionsBuilder {
    options: WrapOptions,
}

impl WrapOptionsBuilder {
    /// ⚡ Configure hard wrapping behavior.
    ///
    /// When enabled, long words that exceed the column limit will be broken
    /// at the boundary. When disabled (default), long words move to the next line.
    ///
    /// # Examples
    /// ```rust
    /// use wrap_ansi::WrapOptions;
    ///
    /// let strict = WrapOptions::builder().hard_wrap(true).build();
    /// let flexible = WrapOptions::builder().hard_wrap(false).build();
    /// ```
    #[must_use]
    pub const fn hard_wrap(mut self, enabled: bool) -> Self {
        self.options.hard = enabled;
        self
    }

    /// 🧹 Configure whitespace trimming behavior.
    ///
    /// When enabled (default), leading and trailing whitespace is removed from
    /// wrapped lines. When disabled, all whitespace is preserved.
    ///
    /// # Examples
    /// ```rust
    /// use wrap_ansi::WrapOptions;
    ///
    /// let clean = WrapOptions::builder().trim_whitespace(true).build();
    /// let preserve = WrapOptions::builder().trim_whitespace(false).build();
    /// ```
    #[must_use]
    pub const fn trim_whitespace(mut self, enabled: bool) -> Self {
        self.options.trim = enabled;
        self
    }

    /// 🔤 Configure word boundary respect.
    ///
    /// When enabled (default), text wraps at word boundaries (spaces).
    /// When disabled, text can wrap at any character position.
    ///
    /// # Examples
    /// ```rust
    /// use wrap_ansi::WrapOptions;
    ///
    /// let word_aware = WrapOptions::builder().word_wrap(true).build();
    /// let char_level = WrapOptions::builder().word_wrap(false).build();
    /// ```
    #[must_use]
    pub const fn word_wrap(mut self, enabled: bool) -> Self {
        self.options.word_wrap = enabled;
        self
    }

    /// 🏁 Build the final `WrapOptions` configuration.
    ///
    /// Consumes the builder and returns the configured `WrapOptions` struct.
    ///
    /// # Examples
    /// ```rust
    /// use wrap_ansi::WrapOptions;
    ///
    /// let options = WrapOptions::builder()
    ///     .hard_wrap(true)
    ///     .trim_whitespace(false)
    ///     .build();
    /// ```
    #[must_use]
    pub const fn build(self) -> WrapOptions {
        self.options
    }
}

impl WrapOptions {
    /// 🏗️ Create a new fluent builder for `WrapOptions`.
    ///
    /// This is the recommended way to create custom `WrapOptions` configurations
    /// as it provides a clean, readable interface with method chaining.
    ///
    /// # Examples
    /// ```rust
    /// use wrap_ansi::WrapOptions;
    ///
    /// // Simple configuration
    /// let options = WrapOptions::builder()
    ///     .hard_wrap(true)
    ///     .build();
    ///
    /// // Complex configuration
    /// let advanced = WrapOptions::builder()
    ///     .hard_wrap(false)        // Soft wrapping
    ///     .trim_whitespace(true)   // Clean output
    ///     .word_wrap(true)         // Respect word boundaries
    ///     .build();
    /// ```
    #[must_use]
    pub fn builder() -> WrapOptionsBuilder {
        WrapOptionsBuilder::default()
    }
}

/// Check if character is an ANSI escape character
const fn is_escape_char(ch: char) -> bool {
    ch == ansi_codes::ESCAPE_ESC || ch == ansi_codes::ESCAPE_CSI
}

/// Wrap ANSI code with escape sequence
///
/// Creates a complete ANSI escape sequence for the given SGR (Select Graphic Rendition) code.
fn wrap_ansi_code(code: u8) -> String {
    format!(
        "{}{}{}{}",
        ansi_codes::ESCAPE_ESC,
        ansi_codes::ANSI_CSI,
        code,
        ansi_codes::ANSI_SGR_TERMINATOR
    )
}

/// Wrap ANSI hyperlink with escape sequence
///
/// Creates an OSC 8 hyperlink escape sequence for the given URL.
fn wrap_ansi_hyperlink(url: &str) -> String {
    format!(
        "{}{}{}{}",
        ansi_codes::ESCAPE_ESC,
        ansi_codes::ANSI_ESCAPE_LINK,
        url,
        ansi_codes::ANSI_ESCAPE_BELL
    )
}

/// Calculate the visual width of each word in the input string.
///
/// Words are split on whitespace, and their visual width is calculated
/// taking into account ANSI escape sequences and Unicode characters.
fn calculate_word_visual_widths(text: &str) -> Vec<usize> {
    text.split(' ').map(string_width).collect()
}

/// 🔒 Maximum input size to prevent potential `DoS` attacks.
///
/// This limit protects against malicious inputs that could cause excessive
/// memory usage or processing time. The limit is set to 10MB, which should
/// be sufficient for most legitimate use cases while preventing abuse.
const MAX_INPUT_SIZE: usize = 10_000_000; // 10MB

/// 🛡️ **Wrap text with comprehensive error handling and input validation.**
///
/// This is the safe, production-ready version of [`wrap_ansi`] that provides robust
/// error handling for edge cases and validates input parameters to prevent potential
/// security issues or unexpected behavior.
///
/// # 🔒 Safety Features
///
/// - **Input size validation**: Prevents `DoS` attacks from extremely large inputs
/// - **Parameter validation**: Ensures column width is valid (> 0)
/// - **Memory protection**: Built-in limits to prevent excessive memory usage
///
/// # Parameters
///
/// - `string`: The input text to wrap (may contain ANSI escape sequences)
/// - `columns`: Target column width (must be > 0)
/// - `options`: Optional wrapping configuration (uses defaults if `None`)
///
/// # Returns
///
/// - `Ok(String)`: Successfully wrapped text with preserved ANSI sequences
/// - `Err(WrapError)`: Detailed error information for invalid inputs
///
/// # Errors
///
/// | Error | Condition | Solution |
/// |-------|-----------|----------|
/// | `InvalidColumnWidth` | `columns == 0` | Use a positive column width |
/// | `InputTooLarge` | Input exceeds 10MB | Split input or increase limit |
///
/// # Examples
///
/// ## Basic Usage with Error Handling
/// ```rust
/// use wrap_ansi::{wrap_ansi_checked, WrapError};
///
/// let text = "Hello, world! This is a test of error handling.";
/// match wrap_ansi_checked(text, 20, None) {
///     Ok(wrapped) => println!("Success: {}", wrapped),
///     Err(e) => eprintln!("Error: {}", e),
/// }
/// ```
///
/// ## Handling Invalid Column Width
/// ```rust
/// use wrap_ansi::{wrap_ansi_checked, WrapError};
///
/// match wrap_ansi_checked("test", 0, None) {
///     Err(WrapError::InvalidColumnWidth(width)) => {
///         println!("Invalid width: {}. Must be greater than 0.", width);
///     }
///     Ok(_) => unreachable!(),
///     _ => {}
/// }
/// ```
///
/// ## Handling Large Input Protection
/// ```rust
/// use wrap_ansi::{wrap_ansi_checked, WrapError};
///
/// let huge_input = "x".repeat(15_000_000); // 15MB
/// match wrap_ansi_checked(&huge_input, 80, None) {
///     Err(WrapError::InputTooLarge(size, max)) => {
///         println!("Input {} bytes exceeds limit of {} bytes", size, max);
///         // Consider splitting the input or processing in chunks
///     }
///     Ok(result) => println!("Wrapped {} characters", result.len()),
///     _ => {}
/// }
/// ```
///
/// ## Production Error Handling Pattern
/// ```rust
/// use wrap_ansi::{wrap_ansi_checked, WrapOptions, WrapError};
///
/// fn safe_wrap_text(text: &str, width: usize) -> Result<String, String> {
///     let options = WrapOptions::builder()
///         .hard_wrap(true)
///         .trim_whitespace(true)
///         .build();
///
///     wrap_ansi_checked(text, width, Some(options))
///         .map_err(|e| match e {
///             WrapError::InvalidColumnWidth(w) => {
///                 format!("Invalid column width: {}. Must be > 0.", w)
///             }
///             WrapError::InputTooLarge(size, max) => {
///                 format!("Input too large: {} bytes (max: {} bytes)", size, max)
///             }
///         })
/// }
/// ```
///
/// # Performance Notes
///
/// - Input validation adds minimal overhead (O(1) for most checks)
/// - Large input detection is O(1) as it checks string length
/// - Consider using [`wrap_ansi`] directly if you can guarantee valid inputs
///
/// # See Also
///
/// - [`wrap_ansi`]: The unchecked version for maximum performance
/// - [`WrapError`]: Detailed error type documentation
/// - [`WrapOptions`]: Configuration options
pub fn wrap_ansi_checked(
    string: &str,
    columns: usize,
    options: Option<WrapOptions>,
) -> Result<String, WrapError> {
    if columns == 0 {
        return Err(WrapError::InvalidColumnWidth(columns));
    }

    if string.len() > MAX_INPUT_SIZE {
        return Err(WrapError::InputTooLarge(string.len(), MAX_INPUT_SIZE));
    }

    Ok(wrap_ansi(string, columns, options))
}

/// Wrap a long word across multiple rows with ANSI-aware processing
///
/// This function handles wrapping of individual words that exceed the column limit,
/// taking into account ANSI escape sequences that don't contribute to visual width.
fn wrap_word_with_ansi_awareness(rows: &mut Vec<String>, word: &str, columns: usize) {
    if word.is_empty() {
        return;
    }

    // Pre-allocate capacity to reduce reallocations
    let estimated_lines = (string_width(word) / columns.max(1)) + 1;
    if rows.capacity() < rows.len() + estimated_lines {
        rows.reserve(estimated_lines);
    }

    let mut current_line = rows.last().cloned().unwrap_or_default();
    let mut visible_width = string_width(&strip_ansi(&current_line));
    let chars = word.chars();
    let mut ansi_parser = AnsiParser::new();

    for ch in chars {
        let char_width = if ansi_parser.is_in_sequence() {
            ansi_parser.process_char(ch);
            0 // ANSI characters don't contribute to visible width
        } else {
            ansi_parser.process_char(ch);
            if ansi_parser.is_in_sequence() {
                0 // Just entered an ANSI sequence
            } else {
                string_width(&ch.to_string())
            }
        };

        if visible_width + char_width > columns && visible_width > 0 {
            // Start new line
            if let Some(last_row) = rows.last_mut() {
                *last_row = current_line;
            }
            rows.push(String::new());
            current_line = String::new();
            visible_width = 0;
        }

        current_line.push(ch);
        visible_width += char_width;
    }

    // Update the last row
    if let Some(last_row) = rows.last_mut() {
        *last_row = current_line;
    } else {
        rows.push(current_line);
    }
}

/// Remove trailing spaces while preserving ANSI escape sequences.
///
/// This function is ANSI-aware, meaning it won't trim spaces that are
/// part of ANSI escape sequences or that come after invisible sequences.
fn trim_trailing_spaces_ansi_aware(text: &str) -> String {
    let words: Vec<&str> = text.split(' ').collect();
    let mut last_visible = words.len();

    // Find the last word with visible content
    while last_visible > 0 {
        if string_width(words[last_visible - 1]) > 0 {
            break;
        }
        last_visible -= 1;
    }

    if last_visible == words.len() {
        return text.to_string();
    }

    // Reconstruct string: visible words joined with spaces + invisible words concatenated
    let mut result = words[..last_visible].join(" ");
    result.push_str(&words[last_visible..].join(""));
    result
}

/// Core text wrapping implementation that handles both text layout and ANSI sequence preservation.
///
/// This function processes a single line of text and wraps it according to the specified
/// options while maintaining ANSI escape sequences across line boundaries.
fn wrap_text_preserving_ansi_sequences(
    text: &str,
    max_columns: usize,
    wrap_options: WrapOptions,
) -> String {
    if wrap_options.trim && text.trim().is_empty() {
        return String::new();
    }

    let word_widths = calculate_word_visual_widths(text);
    let mut rows = vec![String::new()];

    // Process each word
    for (word_index, word) in text.split(' ').enumerate() {
        process_word_for_wrapping(
            &mut rows,
            word,
            word_index,
            &word_widths,
            max_columns,
            wrap_options,
        );
    }

    // Apply trimming if requested
    if wrap_options.trim {
        rows = rows
            .into_iter()
            .map(|row| trim_trailing_spaces_ansi_aware(&row))
            .collect();
    }

    let wrapped_text = rows.join("\n");
    apply_ansi_preservation_across_lines(&wrapped_text)
}

/// Process a single word for wrapping, handling spacing and line breaks
fn process_word_for_wrapping(
    rows: &mut Vec<String>,
    word: &str,
    word_index: usize,
    word_widths: &[usize],
    max_columns: usize,
    options: WrapOptions,
) {
    // Handle trimming for the current row
    if options.trim {
        if let Some(last_row) = rows.last_mut() {
            *last_row = last_row.trim_start().to_string();
        }
    }

    let mut current_row_width = string_width(rows.last().unwrap_or(&String::new()));

    // Add space between words (except for the first word)
    if word_index != 0 {
        if current_row_width >= max_columns && (!options.word_wrap || !options.trim) {
            rows.push(String::new());
            current_row_width = 0;
        }

        if current_row_width > 0 || !options.trim {
            if let Some(last_row) = rows.last_mut() {
                last_row.push(' ');
                current_row_width += 1;
            }
        }
    }

    let word_width = word_widths[word_index];

    // Handle hard wrapping for long words
    if options.hard && word_width > max_columns {
        let remaining_columns = max_columns - current_row_width;
        let breaks_starting_this_line = 1 + (word_width - remaining_columns - 1) / max_columns;
        let breaks_starting_next_line = (word_width - 1) / max_columns;

        if breaks_starting_next_line < breaks_starting_this_line {
            rows.push(String::new());
        }

        wrap_word_with_ansi_awareness(rows, word, max_columns);
        return;
    }

    // Check if word fits on current line
    if current_row_width + word_width > max_columns && current_row_width > 0 && word_width > 0 {
        if !options.word_wrap && current_row_width < max_columns {
            wrap_word_with_ansi_awareness(rows, word, max_columns);
            return;
        }
        rows.push(String::new());
    }

    // Handle character-level wrapping
    if current_row_width + word_width > max_columns && !options.word_wrap {
        wrap_word_with_ansi_awareness(rows, word, max_columns);
        return;
    }

    // Add word to current row
    if let Some(last_row) = rows.last_mut() {
        last_row.push_str(word);
    }
}

// Pre-compiled regex patterns for better performance
static CSI_REGEX: std::sync::LazyLock<Regex> =
    std::sync::LazyLock::new(|| Regex::new(r"^\u{001B}\[(\d+)m").unwrap());
static OSC_REGEX: std::sync::LazyLock<Regex> =
    std::sync::LazyLock::new(|| Regex::new(r"^\u{001B}\]8;;([^\u{0007}]*)\u{0007}").unwrap());

/// Apply ANSI sequence preservation across line boundaries
///
/// This function processes the wrapped text and ensures that ANSI escape sequences
/// are properly closed before newlines and reopened after newlines.
fn apply_ansi_preservation_across_lines(text: &str) -> String {
    let mut result = String::with_capacity(text.len() * 2); // Pre-allocate for efficiency
    let mut ansi_state = AnsiState::default();
    let chars: Vec<char> = text.chars().collect();
    let mut char_index = 0;

    for (index, &character) in chars.iter().enumerate() {
        result.push(character);

        if is_escape_char(character) {
            let remaining = &text[char_index..];

            // Try to match CSI sequence (e.g., \u001B[31m)
            if let Some(caps) = CSI_REGEX.captures(remaining) {
                if let Some(code_match) = caps.get(1) {
                    if let Ok(code) = code_match.as_str().parse::<u8>() {
                        ansi_state.update_with_code(code);
                    }
                }
            }
            // Try to match OSC hyperlink sequence
            else if let Some(caps) = OSC_REGEX.captures(remaining) {
                if let Some(uri_match) = caps.get(1) {
                    ansi_state.update_with_hyperlink(uri_match.as_str());
                }
            }
        }

        // Handle newlines: close styles before, reopen after
        if index + 1 < chars.len() && chars[index + 1] == '\n' {
            result.push_str(&ansi_state.apply_before_newline());
        } else if character == '\n' {
            result.push_str(&ansi_state.apply_after_newline());
        }

        char_index += character.len_utf8();
    }

    result
}

/// 🎨 **The main text wrapping function with full ANSI escape sequence support.**
///
/// This is the primary function for wrapping text while intelligently preserving
/// ANSI escape sequences for colors, styles, and hyperlinks. It handles Unicode
/// characters correctly and provides flexible wrapping options for any use case.
///
/// # ✨ Key Features
///
/// - **🎨 ANSI Preservation**: Colors and styles are maintained across line breaks
/// - **🌍 Unicode Aware**: Proper handling of CJK characters, emojis, and combining marks
/// - **🔗 Hyperlink Support**: OSC 8 sequences remain clickable after wrapping
/// - **⚡ High Performance**: Optimized algorithms with pre-compiled regex patterns
/// - **🛠️ Flexible Options**: Customizable wrapping behavior via [`WrapOptions`]
///
/// # Parameters
///
/// | Parameter | Type | Description |
/// |-----------|------|-------------|
/// | `string` | `&str` | Input text (may contain ANSI sequences) |
/// | `columns` | `usize` | Maximum width in columns per line |
/// | `options` | `Option<WrapOptions>` | Wrapping configuration (uses defaults if `None`) |
///
/// # Returns
///
/// A `String` with text wrapped to the specified width, with all ANSI sequences
/// properly preserved and applied to each line as needed.
///
/// # Examples
///
/// ## 📝 Basic Text Wrapping
/// ```rust
/// use wrap_ansi::wrap_ansi;
///
/// let text = "The quick brown fox jumps over the lazy dog";
/// let wrapped = wrap_ansi(text, 20, None);
/// println!("{}", wrapped);
/// // Output:
/// // The quick brown fox
/// // jumps over the lazy
/// // dog
/// ```
///
/// ## 🎨 Colored Text Wrapping
/// ```rust
/// use wrap_ansi::wrap_ansi;
///
/// // Red text that maintains color across line breaks
/// let colored = "\u{001B}[31mThis is a long red text that will be wrapped properly\u{001B}[39m";
/// let wrapped = wrap_ansi(colored, 15, None);
/// println!("{}", wrapped);
/// // Each line will have: \u{001B}[31m[text]\u{001B}[39m
/// // Output (with colors):
/// // This is a long
/// // red text that
/// // will be wrapped
/// // properly
/// ```
///
/// ## 🔗 Hyperlink Preservation
/// ```rust
/// use wrap_ansi::wrap_ansi;
///
/// let link = "Visit \u{001B}]8;;https://example.com\u{0007}my website\u{001B}]8;;\u{0007} for more info";
/// let wrapped = wrap_ansi(link, 20, None);
/// // Hyperlinks remain clickable across line breaks
/// ```
///
/// ## 🌍 Unicode and Emoji Support
/// ```rust
/// use wrap_ansi::wrap_ansi;
///
/// // CJK characters are counted as 2 columns each
/// let chinese = "你好世界！这是一个测试。";
/// let wrapped = wrap_ansi(chinese, 10, None);
///
/// // Emojis work correctly too
/// let emoji = "Hello 👋 World 🌍 with emojis 🎉";
/// let wrapped_emoji = wrap_ansi(emoji, 15, None);
/// ```
///
/// ## ⚙️ Advanced Configuration
/// ```rust
/// use wrap_ansi::{wrap_ansi, WrapOptions};
///
/// // Using builder pattern for clean configuration
/// let options = WrapOptions::builder()
///     .hard_wrap(true)           // Break long words at boundary
///     .trim_whitespace(false)    // Preserve all whitespace
///     .word_wrap(true)           // Still respect word boundaries where possible
///     .build();
///
/// let text = "supercalifragilisticexpialidocious word";
/// let wrapped = wrap_ansi(text, 10, Some(options));
/// // Output:
/// // supercalif
/// // ragilistic
/// // expialidoc
/// // ious word
/// ```
///
/// ## 🎯 Real-World Use Cases
///
/// ### Terminal Application Help Text
/// ```rust
/// use wrap_ansi::{wrap_ansi, WrapOptions};
///
/// fn format_help_text(text: &str, terminal_width: usize) -> String {
///     let options = WrapOptions::builder()
///         .hard_wrap(false)  // Keep words intact for readability
///         .trim_whitespace(true)  // Clean formatting
///         .build();
///     
///     wrap_ansi(text, terminal_width.saturating_sub(4), Some(options))
/// }
/// ```
///
/// ### Code Syntax Highlighting
/// ```rust
/// use wrap_ansi::wrap_ansi;
///
/// // Preserve syntax highlighting colors when wrapping code
/// let highlighted_code = "\u{001B}[34mfunction\u{001B}[39m \u{001B}[33mhello\u{001B}[39m() { \u{001B}[32m'world'\u{001B}[39m }";
/// let wrapped = wrap_ansi(highlighted_code, 25, None);
/// // Colors are preserved on each line
/// ```
///
/// # 🎨 ANSI Sequence Support
///
/// | Type | Codes | Description |
/// |------|-------|-------------|
/// | **Foreground Colors** | 30-37, 90-97 | Standard and bright text colors |
/// | **Background Colors** | 40-47, 100-107 | Standard and bright background colors |
/// | **Text Styles** | 1, 3, 4, 9 | Bold, italic, underline, strikethrough |
/// | **Color Resets** | 39, 49, 0 | Foreground, background, and full reset |
/// | **Hyperlinks** | OSC 8 | Clickable terminal links (OSC 8 sequences) |
/// | **Custom SGR** | Any | Support for any Select Graphic Rendition codes |
///
/// When text with ANSI codes is wrapped across multiple lines, each line gets
/// complete escape sequences (opening codes at the start, closing codes at the end).
///
/// # 🌍 Unicode Support Details
///
/// | Feature | Support | Description |
/// |---------|---------|-------------|
/// | **Fullwidth Characters** | ✅ | CJK characters counted as 2 columns |
/// | **Surrogate Pairs** | ✅ | Proper handling of 4-byte Unicode sequences |
/// | **Combining Characters** | ✅ | Don't add to visual width |
/// | **Emoji** | ✅ | Correct width calculation for emoji sequences |
/// | **RTL Text** | ⚠️ | Basic support (visual width only) |
///
/// # ⚡ Performance Characteristics
///
/// - **Time Complexity**: O(n) where n is input length
/// - **Space Complexity**: O(n) for output string
/// - **Regex Compilation**: Pre-compiled patterns for optimal performance
/// - **Memory Usage**: Efficient string operations with capacity pre-allocation
/// - **ANSI Parsing**: Optimized state machine for escape sequence detection
///
/// # 🔧 Performance Tips
///
/// ```rust
/// use wrap_ansi::{wrap_ansi, WrapOptions};
///
/// // For maximum performance with trusted input:
/// let fast_options = WrapOptions {
///     trim: false,      // Skip trimming operations
///     hard: false,      // Avoid complex word breaking
///     word_wrap: true,  // Use efficient word boundary detection
/// };
///
/// // For memory-constrained environments, process in chunks:
/// fn wrap_large_text(text: &str, columns: usize) -> String {
///     text.lines()
///         .map(|line| wrap_ansi(line, columns, None))
///         .collect::<Vec<_>>()
///         .join("\n")
/// }
/// ```
///
/// # 🚨 Important Notes
///
/// - **Column Width**: Must be > 0 (use [`wrap_ansi_checked`] for validation)
/// - **Input Size**: No built-in limits (use [`wrap_ansi_checked`] for protection)
/// - **Line Endings**: `\r\n` is normalized to `\n` automatically
/// - **ANSI Sequences**: Malformed sequences are passed through unchanged
///
/// # See Also
///
/// - [`wrap_ansi_checked`]: Safe version with input validation and error handling
/// - [`WrapOptions`]: Detailed configuration options
/// - [`WrapOptionsBuilder`]: Fluent interface for creating options
/// - [`WrapError`]: Error types for the checked version
#[must_use]
pub fn wrap_ansi(string: &str, columns: usize, options: Option<WrapOptions>) -> String {
    let opts = options.unwrap_or_default();

    string
        .replace("\r\n", "\n")
        .split('\n')
        .map(|line| wrap_text_preserving_ansi_sequences(line, columns, opts))
        .collect::<Vec<_>>()
        .join("\n")
}

#[cfg(test)]
mod tests;