npm package: @muid-io/neat-tables
Description: Smart Markdown table formatter with emoji support, visual width calculations, and precise alignment for AI-friendly documentation
Author: muid.io / LifeAiTools.com team 2025
Latest version: 1.4.2

# 📊 neat-tables

**Smart Markdown table formatter with emoji support and visual width calculations**

Perfect alignment for AI-friendly documentation with proper handling of:
- ✨ Emoji characters
- 🌏 CJK (Chinese/Japanese/Korean) characters
- 🔤 Combining characters
- 📏 Accurate visual width calculations

## 🚀 Quick Start

```bash
# Use with npx (no installation needed)
npx @muid-io/neat-tables document.md

# Or install globally
npm install -g @muid-io/neat-tables
neat-tables document.md

# Short alias
ntables document.md
```

## ✨ Features

- **Smart Visual Width**: Accurate calculations for emoji, CJK, and combining characters
- **Emoji Compensation**: Configurable compensation for different font renderings
- **Alignment Support**: Left, center, and right alignment in tables
- **Universal Table Support** 🆕: Handles group headers and variable column counts
- **Context-Aware Parsing** 🆕: Strict validation for table start, relaxed for continuation
- **Auto-Padding** 🆕: Automatically fills missing columns with empty cells
- **In-Place Formatting**: Overwrites original file (backup recommended)
- **Dry-Run Mode**: Preview changes without modifying files
- **Custom Output**: Save formatted tables to a different file

## 📖 Usage

### Basic Usage

```bash
# Format tables in-place (overwrites file)
neat-tables document.md

# Preview without modifying
neat-tables document.md --dry-run

# Save to different file
neat-tables document.md --output formatted.md
```

### Emoji Compensation

Different fonts render emoji with different widths. Use compensation if your tables look misaligned:

```bash
# No compensation (emoji = 2.0 visual width)
neat-tables document.md

# Light compensation (emoji = 2.1)
neat-tables document.md --emoji-compensation 0.1

# Medium compensation (emoji = 2.2)
neat-tables document.md --emoji-compensation 0.2
```

### Configuration File

Create `.table-format.config` (JSON) in your project:

```json
{
  "emoji_compensation": 0.1
}
```

Then run:

```bash
neat-tables document.md --config .table-format.config
```

## 🎯 Examples

### Example 1: Basic Alignment

**Input (misaligned):**

```markdown
| Feature | Status | Description |
|---|---|---|
| 🚀 Speed | ✅ Done | Fast processing |
| 📊 Tables | 🔄 WIP | Smart alignment |
```

**Output (perfectly aligned):**

```markdown
| Feature    | Status  | Description      |
|------------|---------|------------------|
| 🚀 Speed   | ✅ Done | Fast processing  |
| 📊 Tables  | 🔄 WIP  | Smart alignment  |
```

### Example 2: Group Headers (NEW in v1.1.0) 🆕

**Input (with single-column group headers):**

```markdown
| Field | Type | Description |
| ----- | ---- | ----------- |
| **IDENTIFICATION** |
| user_id | int | User ID |
| email | string | Email address |
| **METADATA** |
| created_at | timestamp | Creation time |
```

**Output (auto-padded with empty cells):**

```markdown
| Field              | Type      | Description   |
| ------------------ | --------- | ------------- |
| **IDENTIFICATION** |           |               |
| user_id            | int       | User ID       |
| email              | string    | Email address |
| **METADATA**       |           |               |
| created_at         | timestamp | Creation time |
```

The tool now automatically:
- Detects group header rows with fewer columns
- Pads them with empty cells to match table width
- Maintains perfect alignment across all rows

## 🔧 Command-Line Options

```
Usage: neat-tables INPUT_FILE [OPTIONS]

Options:
  --output, -o FILE          Output to specific file (default: overwrite input)
  --dry-run, -d             Show result without writing file
  --emoji-compensation, -e  Emoji width compensation (0.0-0.5)
  --config, -c FILE         Load settings from JSON config file
  --help                    Show this help message
```

## 🧠 How It Works

### Visual Width Calculation

The tool calculates accurate visual width considering:

1. **ASCII characters**: width = 1
2. **Emoji**: width = 2.0 + compensation
3. **Wide characters (CJK)**: width = 2
4. **Combining characters**: width = 0
5. **Zero-width characters**: width = 0

### Alignment Strategies

- **Left align** (default): `content + padding`
- **Right align**: `padding + content`
- **Center align**: `left_padding + content + right_padding`

### Separator Detection

Recognizes standard Markdown table separators:
- `|---|---|---|` (left align)
- `|:---|:---|:---|` (left align explicit)
- `|:---:|:---:|:---:|` (center align)
- `|---:|---:|---:|` (right align)

## 📚 Integration with Other Tools

### Use with smart-toc

Combine with [@muid-io/smart-toc](https://www.npmjs.com/package/@muid-io/smart-toc) for complete documentation formatting:

```bash
# Generate TOC
npx @muid-io/smart-toc document.md

# Format tables
npx @muid-io/neat-tables document.md
```

### Git Pre-commit Hook

```bash
#!/bin/bash
# .git/hooks/pre-commit
npx @muid-io/neat-tables **/*.md
```

### CI/CD Pipeline

```yaml
# .github/workflows/format-tables.yml
name: Format Tables
on: [push]
jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npx @muid-io/neat-tables **/*.md
```

## 🤝 Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details

## 🔗 Links

- **NPM Package**: https://www.npmjs.com/package/@muid-io/neat-tables
- **GitHub**: https://github.com/muid-io/neat-tables
- **Homepage**: https://muid.io
- **Related Tools**: [@muid-io/smart-toc](https://www.npmjs.com/package/@muid-io/smart-toc)

## 👨‍💻 Author

**LifeAiTools** - [muid.io](https://muid.io)

---

*Generated with ❤️ by LifeAiTools for AI-friendly documentation*