m-truncate/README.md

`mTruncate` is a **lightweight, flexible, and fully standalone Angular directive** that truncates text dynamically and optionally displays a **tooltip** with the full text. It supports **character-based**, **line-based**, and **width-based** truncation

# 🧩 mTruncate — Angular Text Truncation Directive

`mTruncate` is a **lightweight, flexible, and fully standalone Angular directive** that truncates text dynamically and optionally displays a **tooltip** with the full text.  
It supports **character-based**, **line-based**, and **width-based** truncation, while ensuring excellent performance and responsiveness.

---


## 🚀 Features

✅ **Dynamic Truncation** – Truncate text by character count, width, or number of lines.  
💬 **Tooltip Support** – Displays the full text when hovered.  
⚙️ **Customizable** – Control tooltip color, direction, position, and suffix.  
⚡ **Performance Optimized** – Uses event debouncing and efficient DOM updates.  
📱 **Responsive** – Automatically adjusts on window resize.  
🌍 **RTL/LTR Support** – Seamless for Arabic and multilingual applications.  
🧠 **Standalone Directive** – No need for NgModules; works in any Angular component.

---


## 📦 Installation

Install via **npm**:

```bash
npm install m-truncate
```

or via **yarn**:

```bash
yarn add m-truncate
```

---


## 🧠 Quick Start

### 1. Import the Directive

Since `mTruncate` is a **standalone directive**, simply import it into your component:

```typescript
import { MTruncateDirective } from "m-truncate";
```

### 2. Apply It in a Component

```typescript
import { Component } from "@angular/core";
import { MTruncateDirective } from "m-truncate";

@Component({
  selector: "app-example",
  standalone: true,
  imports: [MTruncateDirective],
  template: ` <div mTruncate>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus lacinia.</div> `,
})
export class ExampleComponent {}
```

---


## 💡 Usage Examples

### 🔹 Automatic / Dynamic Truncation

```html
<p mTruncate>This text will be truncated if it exceeds the element width.</p>
```

### 🔹 Truncate by Characters

```html
<p mTruncate [truncateChar]="40">This text will be truncated after 40 characters.</p>
```

### 🔹 Truncate by Number of Lines

```html
<div mTruncate [truncateLines]="2">This paragraph will be truncated after two lines of text.</div>
```

### 🔹 Truncate by Element Width

```html
<span mTruncate [maxTruncateWidth]="120"> This text will be truncated if it exceeds 120px in width. </span>
```

### 🔹 Tooltip Position

```html
<p mTruncate [truncateChar]="30" [tooltipPosition]="'bottom'">This tooltip appears below the text.</p>
```

---


| Input Property     | Type      | Default     | Description                                                                                                             |
| ------------------ | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
| `truncateChar`     | `number`  | `0`         | Maximum number of characters before truncation occurs.                                                                  |
| `truncateLines`    | `number`  | `0`         | Number of lines before truncation.                                                                                      |
| `maxTruncateWidth` | `number`  | `0`         | Maximum width (in pixels) before truncation is applied.                                                                 |
| `maxTooltipWidth`  | `number`  | `0`         | Maximum width for tooltip.                                                                                              |
| `showTooltip`      | `boolean` | `true`      | Show tooltip on hover.                                                                                                  |
| `tooltipPosition`  | `string`  | `'top'`     | Tooltip position (`top`, `bottom`, `left`, or `right`).                                                                 |
| `tooltipDirection` | `string`  | `'ltr'`     | Tooltip text direction (`ltr` or `rtl`).                                                                                |
| `bgColor`          | `string`  | `'#fff'`    | Tooltip background color.                                                                                               |
| `color`            | `string`  | `'#1c1c28'` | Tooltip text color.                                                                                                     |
| `id`               | `string`  | `'mId'`     | ID for the tooltip element.                                                                                             |
| `truncateSuffix`   | `string`  | `'...'`     | Suffix appended when text is truncated.                                                                                 |
| `resize`           | `boolean` | `false`     | If `true`, the directive automatically re-evaluates truncation when the window is resized.                              |
| `textChange`       | `string`  | `''`        | When this input value changes, the directive re-checks and re-applies truncation (useful for dynamically updated text). |

---


## 🎨 Styling

You can customize the tooltip globally using CSS:

```css
.mTooltip {
  font-family: "Arial", sans-serif;
  font-size: 13px;
  padding: 8px 10px;
  border-radius: 8px;
  background: #1c1c28;
  color: #fff;
  box-shadow: 0 4px 10px rgba(0, 0, 0, 0.25);
  transition: opacity 0.2s ease;
}
```

---


## 🌍 Direction Support (LTR / RTL)

If your application supports **multiple languages** or you want to **set tooltip direction globally**, you can use the provided service.

### Example: Set Global Tooltip Direction

```typescript
import { Component } from "@angular/core";
import { MTruncateService } from "m-truncate";

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrl: "./app.component.scss",
})
export class AppComponent {
  constructor(private mTruncateService: MTruncateService) {}

  ngOnInit() {
    this.mTruncateService.setDirection("rtl"); // Global RTL support
  }
}
```

---


## 🧾 License

MIT License © 2025 [Mo'men Waled](https://github.com/MomenWalid)

---


## 📬 Contact

If you have questions, feedback, or would like to contribute:

- 📧 **Email:** [momenwaled60@gmail.com](mailto:momenwaled60@gmail.com)
- 🐙 **GitHub:** [MomenWalid](https://github.com/MomenWalid)
- 🌐 **Portfolio:** [https://momenwalid.github.io/Portfolio/](https://momenwalid.github.io/Portfolio/)

---


> Made with ❤️ by **Mo'men Waled**