@ng-shangjc/utils 0.0.1 → 0.0.2-beta

package/README.md

@@ -0,0 +1,155 @@
+# @ng-shangjc/utils
+
+A comprehensive utility library for Angular Shangjc Components that provides essential tools for building modern UI components with Tailwind CSS.
+
+## 🚀 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.
+
+## 🔗 Related Packages
+
+- [@ng-shangjc/components](https://www.npmjs.com/package/@ng-shangjc/components) - UI components built with these utilities
+
+## 🤝 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-shangjc/utils",
-  "version": "0.0.1",
+  "version": "0.0.2-beta",
   "peerDependencies": {
     "@angular/common": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0",
     "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0",
@@ -11,9 +11,8 @@
     "tslib": "^2.3.0"
   },
   "sideEffects": false,
-  "module": "fesm2022/ng-shangjc-utils.mjs",
-  "typings": "index.d.ts",
   "exports": {
+    "./styles/*": "./styles/*",
     "./package.json": {
       "default": "./package.json"
     },
@@ -21,5 +20,7 @@
       "types": "./index.d.ts",
       "default": "./fesm2022/ng-shangjc-utils.mjs"
     }
-  }
+  },
+  "module": "fesm2022/ng-shangjc-utils.mjs",
+  "typings": "index.d.ts"
 }

package/styles/collapse.css

@@ -0,0 +1,15 @@
+@layer utilities {
+  @keyframes collapse {
+    from { 
+      display: grid;
+      grid-template-rows: 1fr;
+      overflow: hidden;
+    }
+    to { 
+      height: 0; 
+      overflow: hidden;
+      grid-template-rows: 0fr;
+      padding: 0;
+    }
+  }
+}

package/styles/expand.css

@@ -0,0 +1,14 @@
+@layer utilities {
+  @keyframes expand {
+    from { 
+      height: 0;
+      overflow: hidden;
+      grid-template-rows: 0fr;
+    }
+    to {
+      height: var(--radix-accordion-content-height);
+      overflow: hidden;
+      grid-template-rows: 1fr;
+    }
+  }
+}

package/styles/fade-in.css

@@ -0,0 +1,12 @@
+@layer utilities {
+  @keyframes fade-in {
+    from { opacity: 0 }
+    to { opacity: 0 }
+  }
+}
+
+
+
+
+
+

package/styles/fade-out.css

@@ -0,0 +1,12 @@
+@layer utilities {
+  @keyframes fade-out {
+    0% { opacity: 100%; }
+    99.9% { 
+      opacity: 0%; 
+    }
+    100% { 
+      opacity: 0%;
+      display: none;
+    }
+  }
+}

package/styles/fade-scale-in.css

@@ -0,0 +1,18 @@
+@layer utilities {
+  @keyframes fade-scale-in {
+    from { 
+      opacity: 0;
+      transform: scale(0);
+    }
+    to { 
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+}
+
+
+
+
+
+