npm package: @ng-shangjc/utils
Description: <p align="center"> <a href="https://juliancallejas.github.io/ng-shangjc-docs">   <img src="https://res.cloudinary.com/dphleqb5t/image/upload/v1772819746/shangjc/shangjc-64-bg-dark_kwzs81.svg" width="307" alt="Shangjc"  />  </a> </p>
Latest version: 0.0.5-beta

<p align="center">
<a href="https://juliancallejas.github.io/ng-shangjc-docs">
  <img src="https://res.cloudinary.com/dphleqb5t/image/upload/v1772819746/shangjc/shangjc-64-bg-dark_kwzs81.svg" width="307" alt="Shangjc"  /> 
</a>
</p>


# @ng-shangjc/utils

A comprehensive utility library for Angular Shangjc Components that provides essential tools for building modern UI components with Tailwind CSS.


## Official Documentation

<a href="https://juliancallejas.github.io/ng-shangjc-docs">
    ng-Shangjc docs
</a>

## 🚀 Features

- **Class Name Utility (`cn`)** - Smart Tailwind CSS class merging with conflict resolution
- **Portal Host Directive** - Angular directive for managing portal elements
- **Animation Styles** - Pre-built CSS animations for smooth transitions

## 📦 Installation

```bash
npm install @ng-shangjc/utils
```

### Peer Dependencies

This package requires the following peer dependencies:

```bash
npm install @angular/common @angular/core clsx tailwind-merge
```

**Compatible Angular versions:** `^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0`

## 🔧 Usage

### Class Name Utility (`cn`)

The `cn` function combines `clsx` and `tailwind-merge` to provide intelligent class merging that respects Tailwind CSS specificity rules.

```typescript
import { cn } from '@ng-shangjc/utils';

// Basic usage
const classes = cn('text-red-500', 'bg-blue-500');

// With conditional classes
const isActive = true;
const isDisabled = false;
const classes = cn(
  'base-class',
  isActive && 'text-blue-500',
  isDisabled ? 'opacity-50' : 'opacity-100'
);

// Handles class conflicts automatically
const classes = cn('text-red-500', 'text-blue-500'); // Result: 'text-blue-500'
```

### Portal Host Directive

The `portalHost` directive allows you to render elements outside their normal DOM hierarchy, useful for modals, tooltips, and overlays.

```typescript
import { Component } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <div portalHost class="modal-content">
      <!-- This content will be moved to document.body -->
      <h2>Modal Content</h2>
      <p>This is rendered outside the normal DOM flow</p>
    </div>
  `
})
export class ExampleComponent {}
```

**Features:**
- Automatically moves the element to `document.body` on initialization
- Handles Escape key events to prevent unwanted behavior
- Cleans up the element when the directive is destroyed

### Animation Styles

Import the CSS animation files to use pre-built animations:

```css
/* In your global styles or component styles */
@import '@ng-shangjc/utils/styles/fade-scale-in.css';
@import '@ng-shangjc/utils/styles/fade-in.css';
@import '@ng-shangjc/utils/styles/fade-out.css';
@import '@ng-shangjc/utils/styles/collapse.css';
@import '@ng-shangjc/utils/styles/expand.css';
```

#### Available Animations

- **fade-scale-in** - Fade in with scale effect (0 to 1)
- **fade-in** - Simple fade in animation
- **fade-out** - Simple fade out animation
- **collapse** - Collapse animation
- **expand** - Expand animation

## 🎯 API Reference

### `cn(...inputs: ClassValue[]): string`

Merges class names using clsx and tailwind-merge.

**Parameters:**
- `inputs` - Variable number of class values (strings, objects, arrays)

**Returns:**
- Merged class name string with conflicts resolved

### `portalHost` Directive

**Selector:** `[portalHost]`

**Properties:**
- `element: HTMLElement` - Reference to the native DOM element

**Lifecycle Hooks:**
- `ngAfterViewInit()` - Moves element to document.body and sets up event handlers
- `ngOnDestroy()` - Removes element from DOM

## 🏗️ Development

This package is built with Angular's library format using ng-packagr.

### Building

```bash
npm run build
```

### Testing

```bash
npm run test
```

## 📄 License

This package is part of the ng-shadcn project. See the main project license for details.

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

## 📝 Changelog

### 0.0.1
- Initial release
- Added `cn` utility function
- Added `portalHost` directive
- Added basic animation styles


**Part of ng-shangjc component library** • [Documentation](https://juliancallejas.github.io/ng-shangjc-docs/)

<p align="center">
<a href="https://github.com/JulianCallejas">
  <img src="https://res.cloudinary.com/dphleqb5t/image/upload/v1740784502/github-jc-develop/JC-LOGO-Horizontal-170-50-thin-github_uu3b5n.svg" width="170" alt="{ jc - develop }"  /> 
</a>
</p>