FluidWidth 1.1.1

FluidWidth 📏

Advanced Terminal-Aware String Display Width Calculator

Cross-Platform Terminal-Aware String Display Width Calculator

Professional-grade library for accurate string width calculation in terminal/console applications with full Unicode support.

✨ Features

• ✅ ANSI Escape Codes - Automatically stripped, width calculated correctly
• ✅ Emoji & ZWJ Sequences - 👨‍👩‍👧‍👦, 👩‍⚕️, 🐕‍🦺, ❤️‍🔥, with VS15/VS16 support
• ✅ East Asian Characters - 中文, 日本語, 한국어 with proper width (Fullwidth/Halfwidth)
• ✅ Unicode Grapheme Clusters - Correct handling of combined characters
• ✅ Tab Characters - Configurable tab stops
• ✅ Zero-Width Characters - Proper detection and exclusion
• ✅ Performance Optimized - LRU caching, fast paths for ASCII
• ✅ Strongly Named Assembly - Ready for enterprise deployment
• ✅ No External Dependencies - Self-contained

🌍 Cross-Platform Support

FluidWidth works seamlessly on all major platforms:

🚀 Quick Start

using FluidWidth.Public;

// Calculate display width with emoji
int width = AnsiHelper.GetDisplayWidth("Hello 👨‍👩‍👧‍👦 World!");
// Returns: 14 cells

// Strip ANSI escape codes
string clean = AnsiHelper.StripAnsiCodes("\x1B[31mRed\x1B[0m Text");
// Returns: "Red Text"

// Configure
AnsiHelper.EmojiWidthMode = EmojiWidthMode.ModernTerminal;

🎯 Basic Examples

// Various text examples
string[] texts = {
    "ASCII Only",                    // 10 cells
    "With emoji 👋",                 // 13 cells
    "With flag 🇺🇸",                  // 12 cells
    "With skin tone 👍🏻",            // 17 cells
    "Japanese 日本語",                // 15 cells
    "Keycap #️⃣",                     // 9 cells
    "Heart ❤️",                       // 8 cells
    "Family 👨‍👩‍👧‍👦"                  // 8 cells
};

foreach (string text in texts)
{
    int width = AnsiHelper.GetDisplayWidth(text);
    Console.WriteLine($"'{text}' → {width} cells");
}

⚙️ Configuration

// Emoji Width Modes
AnsiHelper.EmojiWidthMode = EmojiWidthMode.Conservative;      // All emoji = 2 cells
AnsiHelper.EmojiWidthMode = EmojiWidthMode.ModernTerminal;    // ZWJ sequences = 1 cell (Default)
AnsiHelper.EmojiWidthMode = EmojiWidthMode.TextPresentation;  // Respect VS15/VS16

// East Asian Support
AnsiHelper.UseEastAsianFullwidth = true;  // Treat East Asian chars as 2 cells

🚀 Advanced Usage

1. Progress Bars

public static string CreateProgressBar(int totalWidth, double percentage, string label = "")
{
    int barWidth = totalWidth - 10;
    int filled = (int)(barWidth * percentage);
    
    string bar = new string('█', filled);
    string empty = new string('░', barWidth - filled);
    
    return $"[{bar}{empty}] {(percentage * 100):F1}% {label}";
}
// Output: [████████████████████████████████████░░░░░░░░] 75.0% Loading

2. Text Alignment

string[] items = { "Apple", "Banana 🍌", "Orange 🍊" };
int columnWidth = 20;

foreach (string item in items)
{
    int itemWidth = AnsiHelper.GetDisplayWidth(item);
    int padding = columnWidth - itemWidth;
    string aligned = item + new string(' ', padding) + "|";
    Console.WriteLine($"|{aligned}");
}

3. Text Truncation

public static string TruncateToWidth(string text, int maxWidth, string ellipsis = "…")
{
    int textWidth = AnsiHelper.GetDisplayWidth(text);
    if (textWidth <= maxWidth) return text;
    
    int ellipsisWidth = AnsiHelper.GetDisplayWidth(ellipsis);
    int targetWidth = maxWidth - ellipsisWidth;
    
    StringBuilder result = new StringBuilder();
    int currentWidth = 0;
    
    foreach (char c in text)
    {
        string charStr = c.ToString();
        int charWidth = AnsiHelper.GetDisplayWidth(charStr);
        
        if (currentWidth + charWidth > targetWidth)
            break;
            
        result.Append(charStr);
        currentWidth += charWidth;
    }
    
    return result.ToString() + ellipsis;
}

// Usage
string truncated = TruncateToWidth("Long text with emoji 👨‍👩‍👧‍👦", 30);
// Returns: "Long text with emoji…"

📊 Test Output Example

=== FluidWidth Library Test ===

1. QUICK START TESTS
📏 Text: 'Hello 👨‍👩‍👧‍👦 World!'
   Width: 14 cells

🎨 ANSI Text: '←[31mRed←[0m and ←[32mGreen←[0m'
   Clean: 'Red and Green'
   Width: 13 cells

2. BASIC EXAMPLES
📊 Text Width Calculations:
   'ASCII Only' → 10 cells
   'With emoji 👋' → 13 cells
   'With flag 🇺🇸' → 12 cells
   'With skin tone 👍🏻' → 17 cells
   'Japanese 日本語' → 15 cells
   'Keycap #️⃣' → 9 cells
   'Heart ❤️' → 8 cells
   'Family 👨‍👩‍👧‍👦' → 8 cells

3. CONFIGURATION TESTS
Testing EmojiWidthMode for 👨‍👩‍👧‍👦:
   Conservative: 2 cells
   ModernTerminal: 1 cells
   TextPresentation: 1 cells

4. COMMON USE CASES
🔄 Progress Bar Example:
   [░░░░░░░░░░░░░░░░░░░░░░░]   0%
   [█████░░░░░░░░░░░░░░░░░░]  25%
   [███████████░░░░░░░░░░░░]  50%
   [█████████████████░░░░░░]  75%
   [███████████████████████] 100%

📐 Text Alignment Example:
   |Apple               |
   |Banana 🍌           |
   |Orange 🍊           |
   |Grapes 🍇           |

✂️ Text Truncation Example:
   Original: 'This is a very long text with emoji 👨‍👩‍👧‍👦...'
   Width: 65 cells
   Truncated: 'This is a very long text with…'
   Truncated Width: 30 cells

Installation

dotnet add package FluidWidth