# @versini/ui-truncate

[![npm version](https://img.shields.io/npm/v/@versini/ui-truncate?style=flat-square)](https://www.npmjs.com/package/@versini/ui-truncate)
![npm package minimized gzipped size](<https://img.shields.io/bundlejs/size/%40versini%2Fui-truncate?style=flat-square&label=size%20(gzip)>)

> A lightweight and accessible React text truncation component built with TypeScript and TailwindCSS.

The Truncate component provides intelligent text truncation with toggle functionality for managing long text content. Perfect for article previews, descriptions, and any content that needs length management.

## Table of Contents

- [Table of Contents](#table-of-contents)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Props](#props)
- [Example](#example)
- [Behavior](#behavior)
- [Rich Content Truncation](#rich-content-truncation)
- [License](#license)

## Features

- **🎯 Smart Truncation**: Intelligent text truncation with customizable character limits
- **🔍 Expandable**: Built-in expand/collapse toggle functionality
- **♿ Accessible**: Screen reader friendly with proper button semantics
- **🌲 Tree-shakeable**: Lightweight and optimized for bundle size
- **🔧 TypeScript**: Fully typed with comprehensive prop definitions
- **🎭 Theme Support**: Built-in support for light, dark, and system themes

## Installation

```bash
npm install @versini/ui-truncate
```

> **Note**: This component requires TailwindCSS and the `@versini/ui-styles` plugin for proper styling. See the [installation documentation](https://versini-org.github.io/ui-components/?path=/docs/getting-started-installation--docs) for complete setup instructions.

## Usage

```tsx
import { Truncate } from "@versini/ui-truncate";

function App() {
  return (
    <Truncate length={100} mode="dark">
      This is a very long text that needs to be truncated.
    </Truncate>
  );
}
```

## Props

| Prop                   | Type                                            | Default    | Description                                                                                                                                               |
| ---------------------- | ----------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`             | `React.ReactNode`                               | `null`     | The content to render. If not a string, it will be rendered as-is.                                                                                        |
| `length`               | `number`                                        | `200`      | The maximum number of characters to display before truncating.                                                                                            |
| `mode`                 | `"dark" \| "light" \| "system" \| "alt-system"` | `"system"` | The mode of the button used for toggling truncated text.                                                                                                  |
| `enableRichTruncation` | `boolean`                                       | `false`    | When `true`, measures nested React content text and truncates it. Collapsed view is plain text (styling removed); expanded view restores full formatting. |

## Example

```tsx
import { Truncate } from "@versini/ui-truncate";

function App() {
  return (
    <div>
      <Truncate length={50} mode="light">
        Lorem ipsum dolor sit amet. Sed do ut labore et dolore magna. Sed do ut
        labore et dolore magna. Lorem ipsum dolor sit amet.
      </Truncate>
    </div>
  );
}
```

## Behavior

- If the `children` prop is not a string, the component will render the `children` as-is without truncation.
- If the text exceeds the specified `length`, it will be truncated, and a button will appear to toggle between the truncated and full text.
- The button's appearance can be customized using the `mode` prop.
- When `enableRichTruncation` is `true`, the component traverses nested React nodes, measures their combined textual content, and in the collapsed state renders a flattened plain text slice (no markup) so the toggle button appears immediately after the text. Expanding restores the original rich markup.

## Rich Content Truncation

By default, only plain string children are truncated. Complex React node trees (e.g. with `<strong>`, `<em>`, or other inline components) are rendered in full to avoid unexpected structural changes.

If you need truncation that spans across nested elements, opt in with `enableRichTruncation`. Collapsed output is intentionally flattened to avoid layout shifts and orphaned inline elements; expanded output preserves original styling:

```tsx
<Truncate length={80} enableRichTruncation>
  <p>
    <strong>Design systems</strong> help teams build consistent, accessible
    interfaces. They reduce duplication, improve quality, and accelerate
    delivery. <em>However</em>, maintaining them requires clear ownership and
    strong governance.
  </p>
</Truncate>
```

What happens when enabled:

- The textual content of all descendants is concatenated (whitespace preserved within text nodes)
- The truncation algorithm finds a word-aware boundary within the requested `length`
- Collapsed state: a flat plain-text slice is rendered (all markup removed)
- Expanded state: the original rich React node tree is rendered untouched
- The toggle button ("more..." / "less...") sits directly after the truncated text ensuring it stays on the same line when possible

Limitations / Notes:

- Collapsed view drops all formatting (no inline styles, marks, or semantic tags) by design
- If inline formatting splits a word across elements (e.g. `<b>su</b><i>per</i>`), truncation still respects word boundaries based on combined text
- Does not sanitize HTML; sanitize before passing any raw HTML via `dangerouslySetInnerHTML`
- Performance is O(N) over text nodes; suitable for typical UI fragments (< a few thousand characters)

## License

MIT