Terminal Text Formatter

Build a text formatter that wraps styled terminal text while providing precise control over whitespace handling.

Requirements

Your formatter should wrap text to fit within a specified column width. The key requirement is to provide users with control over how leading and trailing whitespace is handled on wrapped lines.

Implement two whitespace handling modes:

1. Clean mode (default): Remove leading and trailing whitespace from each wrapped line, resulting in cleaner output
2. Preserve mode: Keep all whitespace exactly as provided in the input, including leading and trailing spaces

The formatter must correctly handle text containing terminal styling codes (ANSI escape sequences) - these should not affect width calculations or be removed during wrapping.

Behavior

When text wraps across multiple lines:

• Clean mode: Each resulting line should have whitespace trimmed from both ends
• Preserve mode: Spaces are preserved and count toward the column width; preserved spaces can appear on their own lines

Single-line text (text that fits within the column width without wrapping) should maintain its original formatting regardless of mode.

Implementation

@generates

API

/**
 * Wraps text to specified column width with configurable whitespace handling
 * @param {string} text - The text to wrap (may contain ANSI styling codes)
 * @param {number} columns - Maximum column width
 * @param {object} options - Configuration options
 * @param {boolean} options.preserveWhitespace - If true, preserve all whitespace; if false (default), trim whitespace from wrapped lines
 * @returns {string} The wrapped text
 */
function formatText(text, columns, options) {
  // Implementation here
}

module.exports = { formatText };

Test Cases

Clean mode (default behavior)

• When wrapping text " hello world " at 8 columns with default options, the output is "hello\nworld" (whitespace trimmed from each line) @test
• When wrapping text " foo bar baz " at 6 columns with default options, the output is "foo\nbar\nbaz" (all whitespace removed) @test

Preserve mode

• When wrapping text " hello world " at 8 columns with preserveWhitespace set to true, the output preserves all spaces (e.g., " hello\n world\n ") @test
• When wrapping text "a b" at 3 columns with preserveWhitespace set to true, spaces are preserved and count toward width @test

Styled text handling

• When wrapping styled text containing ANSI color codes with clean mode, the output has trimmed whitespace while preserving styling @test
• When wrapping styled text with preserve mode, both styling and whitespace are maintained @test

Dependencies { .dependencies }

wrap-ansi { .dependency }

Provides text wrapping with ANSI escape code support.

@satisfied-by