npm package: @ng-shangjc/alert
Description: Alert component source package for ng-shangjc angular components
Author: jc-develop
Latest version: 1.0.2-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>

# Alert Component

A flexible alert component built with Angular that provides a way to display notification messages with multiple variants, dismissible functionality, and icon integration. The component follows the shadcn/ui design principles and is fully customizable with modern signal-based reactivity.

## Official Documentation

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

## Features

- 🎨 **Multiple Variants**: Default, destructive, warning, success, and info styles with proper dark mode support
- ❌ **Dismissible**: Optional close button functionality with fade and collapse animations
- 🔧 **Composition**: Built with separate components for title, content, icon, and action
- 🎯 **Accessibility**: Proper ARIA attributes, screen reader support, and keyboard navigation
- 📝 **Rich Content**: Support for titles, descriptions, and action buttons
- 🎭 **Customizable**: Additional CSS classes and styling options
- ⚡ **Performance**: Signal-based reactivity with OnPush change detection
- 🎪 **Animations**: Smooth fade and collapse animations when dismissing
- ⌨️ **Keyboard Navigation**: Full keyboard support for interactive elements
- 🎯 **Type-Safe**: Complete TypeScript support with proper type definitions

## Installation

### Step 1: Install the CLI

First, install the ng-shangjc CLI globally or use npx:

```bash
# Install globally
npm install -g @ng-shangjc/cli

# or with yarn
yarn global add @ng-shangjc/cli

# or with pnpm
pnpm install -g @ng-shangjc/cli

# Or use npx without installation
npx @ng-shangjc/cli <command>
```

### Step 2: Initialize your project

If you haven't already, initialize your Angular project for ng-shangjc components:

```bash
ng-shangjc init
```

This will create a `shangjc.config.json` file and set up your project for component installations.

### Step 3: Install the component

Install the alert component into your project:

```bash
ng-shangjc install alert
```

The component will be installed in the configured path (default: `src/ui/shangjc`). Adjust the import path in your components based on your project structure and the configured installation path.

## Import

After installation, import the components from your configured installation path. The examples below use the default path `src/ui/shangjc` - adjust the path according to your project structure and configuration.

### Standalone Components (Recommended)

Import and use the individual components directly in your standalone components:

```typescript
import { Component } from '@angular/core';
import { CommonModule } from '@angular/common';
import { 
  AlertComponent,
  AlertTitleComponent,
  AlertContentComponent,
  AlertActionComponent,
  AlertIconComponent
} from './ui/shangjc/alert';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    AlertComponent,
    AlertTitleComponent,
    AlertContentComponent,
    AlertActionComponent,
    AlertIconComponent
  ],
  template: `
    <ng-shangjc-alert variant="success">
      <ng-shangjc-alert-title>Success!</ng-shangjc-alert-title>
      <ng-shangjc-alert-content>Your action was completed successfully.</ng-shangjc-alert-content>
      <ng-shangjc-alert-action (onClick)="onAction()">Undo</ng-shangjc-alert-action>
    </ng-shangjc-alert>
  `
})
export class ExampleComponent {
  onAction() {
    console.log('Action clicked!');
  }
}
```

### Using NgModule (Legacy)

If you're using NgModules, import the `AlertModule`:

```typescript
import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { AlertModule } from './ui/shangjc/alert';

@NgModule({
  declarations: [YourComponent],
  imports: [
    CommonModule,
    AlertModule
  ]
})
export class YourModule { }
```

Then use the components in your templates:

```html
<ng-shangjc-alert>
  <!-- Component content -->
</ng-shangjc-alert>
```

## Basic Usage

### Default Example

```typescript
import { Component } from '@angular/core';
import { 
  AlertComponent,
  AlertTitleComponent,
  AlertContentComponent,
  AlertActionComponent,
  AlertIconComponent
} from './ui/shangjc/alert';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    AlertComponent,
    AlertTitleComponent,
    AlertContentComponent,
    AlertActionComponent,
    AlertIconComponent
  ],
  template: `
    <ng-shangjc-alert variant="success">
      <ng-shangjc-alert-title>Success!</ng-shangjc-alert-title>
      <ng-shangjc-alert-content>Your action was completed successfully.</ng-shangjc-alert-content>
      <ng-shangjc-alert-action (onClick)="onAction()">Undo</ng-shangjc-alert-action>
    </ng-shangjc-alert>
  `
})
export class ExampleComponent {
  onAction() {
    console.log('Action clicked!');
  }
}
```

### Alternative Usage Patterns

#### Different Variants

```html
<!-- Default -->
<ng-shangjc-alert>
  <ng-shangjc-alert-content>Default alert for general information.</ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Destructive -->
<ng-shangjc-alert variant="destructive">
  <ng-shangjc-alert-content>Error alert for critical issues.</ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Warning -->
<ng-shangjc-alert variant="warning">
  <ng-shangjc-alert-content>Warning alert for important notices.</ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Success -->
<ng-shangjc-alert variant="success">
  <ng-shangjc-alert-content>Success alert for completed actions.</ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Info -->
<ng-shangjc-alert variant="info">
  <ng-shangjc-alert-content>Info alert for helpful information.</ng-shangjc-alert-content>
</ng-shangjc-alert>
```

#### Dismissible Alerts

```html
<!-- With fade animation -->
<ng-shangjc-alert 
  variant="info" 
  [dismissible]="true"
  [fade]="true"
  (dismissed)="onAlertDismissed()">
  <ng-shangjc-alert-content>
    This alert will fade out when dismissed.
  </ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- With collapse animation -->
<ng-shangjc-alert 
  variant="warning" 
  [dismissible]="true"
  [collapse]="true"
  (dismissed)="onAlertDismissed()">
  <ng-shangjc-alert-content>
    This alert will collapse when dismissed.
  </ng-shangjc-alert-content>
</ng-shangjc-alert>

<!-- Without animation -->
<ng-shangjc-alert 
  variant="success"
  [dismissible]="true"
  (dismissed)="onAlertDismissed()">
  <ng-shangjc-alert-content>
    This alert will be hidden immediately when dismissed.
  </ng-shangjc-alert-content>
</ng-shangjc-alert>
```

#### Custom Icons

```html
<ng-shangjc-alert variant="success">
  <ng-shangjc-alert-icon>
    <svg class="h-4 w-4" fill="currentColor" viewBox="0 0 20 20">
      <path fill-rule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z" clip-rule="evenodd" />
    </svg>
  </ng-shangjc-alert-icon>
  <ng-shangjc-alert-content>Custom success icon alert.</ng-shangjc-alert-content>
</ng-shangjc-alert>
```

## Advanced Usage

### Controlled Component

```typescript
import { Component, signal } from '@angular/core';
import { AlertComponent } from './ui/shangjc/alert';

@Component({
  selector: 'app-controlled-example',
  standalone: true,
  imports: [AlertComponent],
  template: `
    <ng-shangjc-alert 
      variant="info" 
      [dismissible]="true"
      (dismissed)="onDismissed()"
      #alertRef>
      <ng-shangjc-alert-content>
        This is a controlled alert with dismiss functionality.
      </ng-shangjc-alert-content>
    </ng-shangjc-alert>
    
    <button (click)="alertRef.dismiss()">Dismiss Programmatically</button>
  `
})
export class ControlledExampleComponent {
  isDismissed = signal(false);
  
  onDismissed() {
    this.isDismissed.set(true);
    console.log('Alert was dismissed');
  }
}
```

### Complex Alert with Multiple Actions

```html
<ng-shangjc-alert variant="warning">
  <ng-shangjc-alert-title>Update Available</ng-shangjc-alert-title>
  <ng-shangjc-alert-content>
    A new version of the application is available. Would you like to update now?
  </ng-shangjc-alert-content>
  <div class="mt-2 flex gap-2">
    <ng-shangjc-alert-action (onClick)="updateNow()">Update Now</ng-shangjc-alert-action>
    <ng-shangjc-alert-action (onClick)="learnMore()">Learn More</ng-shangjc-alert-action>
  </div>
</ng-shangjc-alert>
```

### Form Validation Integration

```html
<ng-shangjc-alert variant="destructive" [dismissible]="true">
  <ng-shangjc-alert-title>Validation Error</ng-shangjc-alert-title>
  <ng-shangjc-alert-content>
    <ul class="mt-2 list-disc list-inside">
      <li>Email is required</li>
      <li>Password must be at least 8 characters</li>
    </ul>
  </ng-shangjc-alert-content>
</ng-shangjc-alert>
```

## API Reference

### AlertComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `variant` | `'default' \| 'destructive' \| 'warning' \| 'success' \| 'info'` | `'default'` | Alert style variant |
| `dismissible` | `boolean` | `false` | Whether the alert can be dismissed |
| `fade` | `boolean` | `false` | Whether to use fade animation when dismissing |
| `collapse` | `boolean` | `false` | Whether to use collapse animation when dismissing |
| `showIcon` | `boolean` | `true` | Whether to show the default variant icon |
| `class` | `string` | `''` | Additional CSS classes |
| `ariaLive` | `'polite' \| 'assertive' \| 'off'` | `'polite'` | ARIA live region behavior |
| `ariaAtomic` | `boolean` | `true` | ARIA atomic attribute |
| `ariaLabel` | `string` | `undefined` | ARIA label for the alert |
| `ariaDescribedBy` | `string` | `undefined` | ARIA described by for the alert |
| `role` | `string` | `'alert'` | ARIA role for the alert |
| `dismissed` | `EventEmitter<void>` | - | Emitted when alert is dismissed |
| `onAlertAction` | `EventEmitter<MouseEvent>` | - | Emitted when action button is clicked |

### AlertTitleComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes |

### AlertContentComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes |

### AlertIconComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes |

### AlertActionComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `class` | `string` | `''` | Additional CSS classes |
| `onClick` | `EventEmitter<MouseEvent>` | - | Emitted when action button is clicked |

## Accessibility

- **Keyboard Navigation**: Full support for Tab, Shift+Tab, Enter, Space, and Arrow keys
- **ARIA Attributes**: Proper ARIA labels, roles, and states
- **Focus Management**: Visible focus indicators and proper focus handling
- **Screen Reader**: Compatible with screen readers
- **Semantic Structure**: Uses proper HTML semantic elements

### ARIA Features

- `role="alert"` on alert containers
- `aria-live` regions for screen reader announcements
- `aria-atomic` for complete message reading
- `aria-label` and `aria-describedby` for enhanced accessibility
- Keyboard accessible dismiss button with proper focus management

## Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## Contributing

See the main project [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

---

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