m-truncate/README.md

`mTruncate` is a lightweight and customizable Angular directive for truncating text with support for tooltips. It allows you to truncate text based on width or a specified number of lines and display a tooltip when the full text is not visible.

# mTruncate - Angular Truncate Directive

`mTruncate` is a lightweight and customizable Angular directive for truncating text with support for tooltips. It allows you to truncate text based on width or a specified number of lines and display a tooltip when the full text is not visible.

## 🚀 Features

- **Dynamic Truncation** – Truncate text based on characters, lines, or width.
- **Tooltip Support** – Shows full text when hovered.
- **Customizable** – Change styles, position, colors, and more.
- **Performance Optimized** – Uses event debouncing and efficient calculations.
- **Responsive** – Adapts to different screen sizes.

## 📦 Installation

Install the package via npm:

```sh
npm install m-truncate
```

Or using yarn:

```sh
yarn add m-truncate
```

## 📖 Usage

### 1. Import the Directive

The directive is `standalone`, so you can use it directly in your component.

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

#### Apply to a Component Example

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

@Component({
  selector: "app-example",
  standalone: true,
  imports: [MTruncateDirective],
  template: `<div mTruncate>This text will be truncated</div>`,
})
export class ExampleComponent {}
```

### 2. Apply to an Element

```html
<div mTruncate>This is a long text that will be truncated based on the specified conditions.</div>
```

## 🔹 Inputs

| 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'`     | Position of the tooltip (`top`, `bottom`, `left`, `right`). |
| `tooltipDirection` | `string`  | `'ltr'`     | Text direction (`ltr`, `rtl`).                              |
| `bgColor`          | `string`  | `'#fff'`    | Tooltip background color.                                   |
| `color`            | `string`  | `'#1c1c28'` | Tooltip text color.                                         |
| `id`               | `string`  | `mId`       | ID for the tooltip element.                                 |
| `truncateSuffix`   | `string`  | `...`       | Suffix to append when text is truncated.                    |

## ⚡ Examples

### Truncate by Characters

```html
<p mTruncate [truncateChar]="50">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ut purus neque.</p>
```

### Truncate by Lines

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

### Tooltip Position

```html
<span mTruncate [truncateChar]="20" [tooltipPosition]="'bottom'"> This tooltip will appear at the bottom </span>
```

### Maximum Truncated Width

```html
<p mTruncate [maxTruncateWidth]="150">This is a long text that will be truncated if it exceeds 150px.</p>
```

## 🎨 Styling

You can customize the tooltip using CSS:

```css
.mTooltip {
  font-family: Arial, sans-serif;
  padding: 8px;
  border-radius: 6px;
  box-shadow: 0 4px 10px rgba(0, 0, 0, 0.2);
}
```

## 📌 Note

If you have an **Arabic version** of your application or need to **dynamically change the tooltip direction across your project**, you can use the `mTruncate` service to set the direction globally.

#### Use the Service in `app.component.ts`

```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"); // Change direction globally
  }
}
```

## 📜 License

Copyright (c) 2025 Mo'men Waled Licensed under the MIT license.

## 📬 Contact

If you have any questions, need support, or want to contribute, feel free to reach out:

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