npm package: @kittle/slugify
Description: An ultra-robust Unicode-aware slug generator with smart normalization, emoji removal, duplicate dash compression, and fallback protection.
Author: kittle
Latest version: 1.0.1

# @kittle/slugify

A production-grade, Unicode-aware slug generator with advanced text normalization, emoji removal, symbol handling, duplicate-dash compression, custom separators, and SEO-safe fallback generation.

Designed for real-world production apps where slugs must be clean, predictable, language-friendly, and SEO-optimized.

---

## ✨ Features

- ✔ **Unicode support** (Tamil, Hindi, Japanese, Arabic, etc.)
- ✔ **Emoji & symbol removal**
- ✔ **Smart normalization** (removes accents, apostrophes, diacritics)
- ✔ **Converts "&" → "and"**
- ✔ **Duplicate dash compression**
- ✔ **Trims leading/trailing separators**
- ✔ **Custom separator support**
- ✔ **SEO-safe fallback for empty input**
- ✔ **Lightweight, fast, and dependency-free**
- ✔ Works in **Node**, **React**, **Next.js**, **Vite**, **Browser**, etc.

---

## 📦 Installation

```bash
npm install @kittle/slugify
```

or

```bash
yarn add @kittle/slugify
```

or

```bash
pnpm add @kittle/slugify
```

---

## 📘 Usage Examples

### 🔹 Basic Usage

```js
import { slugify } from "@kittle/slugify";

const title = "Senior Software Engineer";
console.log(slugify(title));
// → "senior-software-engineer"
```

---

### 🔹 Unicode / Multi-Language Support

```js
slugify("விற்பனை மேலாளர்");   
// → "விற்பனை-மேலாளர்"

slugify("東京 支社 マネージャー");  
// → "東京-支社-マネージャー"

slugify("مدير المبيعات");  
// → "مدير-المبيعات"
```

---

### 🔹 Smart Symbol & Emoji Handling

```js
slugify("Manager's Office!");
// → "managers-office"

slugify("QA & R&D Team");
// → "qa-and-r-d-team"

slugify("Boss 😎🔥");
// → "boss"
```

---

### 🔹 Custom Separator

```js
slugify("Senior Manager", "_");
// → "senior_manager"
```

---

### 🔹 SEO-Safe Fallback

If the string becomes empty after cleaning (for example, only emojis):

```js
slugify("");
// → "item-x8hg2k"  // example fallback

slugify("💯🔥😎");
// → "item-aj29dp"  // example fallback
```

---

### 🔹 Programmatic Usage

```js
const positions = [
  "CEO",
  "CTO",
  "GM Sales",
  "HOD - Mechanical Dept",
  "Lead QA & Testing",
];

const slugs = positions.map((p) => slugify(p));

console.log(slugs);
// → ["ceo", "cto", "gm-sales", "hod-mechanical-dept", "lead-qa-and-testing"]
```

---

## 🔧 API Reference

### `slugify(input: string, separator?: string): string`

| Parameter   | Type     | Default | Description                          |
| ----------- | -------- | ------- | ------------------------------------ |
| `input`     | `string` | —       | The string to convert into a slug.   |
| `separator` | `string` | `"-"`   | Optional custom separator character. |

---

## 🧠 How It Works

The slug generation pipeline includes:

1. **Unicode normalization (NFKD)**
2. **Accent/diacritic removal**
3. **Apostrophe cleanup**
4. **Emoji & pictograph stripping**
5. **`&` → `and` conversion**
6. **Sanitization using Unicode-aware RegExp**
7. **Multiple-separator compression**
8. **Trim separators from start & end**
9. **Safe fallback when output becomes empty**

This ensures consistent and SEO-friendly slug output across all languages.

---

## ⚙️ Examples of Transformations

| Input                        | Output                     |
| ---------------------------- | -------------------------- |
| `"Senior Software Engineer"` | `senior-software-engineer` |
| `"HOD / Principal"`          | `hod-principal`            |
| `"R&D + QA"`                 | `r-and-d-qa`               |
| `"Manager's Office"`         | `managers-office`          |
| `"CEO — Level 1"`            | `ceo-level-1`              |
| `"Lead 🏗️ Engineer"`         | `lead-engineer`            |
| `"東京 支社"`                | `東京-支社`                |
| `"விற்பனை மேலாளர்"`        | `விற்பனை-மேலாளர்`        |

---

## 🌐 Browser Usage (CDN)

```html
<script type="module">
  import { slugify } from "https://cdn.jsdelivr.net/npm/@kittle/slugify/dist/index.js";

  console.log(slugify("Front-End Developer"));
  // → front-end-developer
</script>
```

---

## 🛠 Build Tools Compatibility

| Tool / Runtime | Supported                     |
| -------------- | ----------------------------- |
| Node.js        | ✅ YES                         |
| React          | ✅ YES                         |
| Next.js        | ✅ YES                         |
| Vite           | ✅ YES                         |
| Webpack        | ✅ YES                         |
| Browser ESM    | ✅ YES                         |
| TypeScript     | ✅ YES (with typings included) |

---

## 📄 License

**MIT License**
Copyright © kittle

---