@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

🚀 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

npm install @ng-shangjc/utils

Peer Dependencies

This package requires the following peer dependencies:

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.

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.

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:

/* 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

npm run build

Testing

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