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

# Badge Component

A flexible badge component for status indicators, labels, and notifications with multiple variants, sizes, and icon support. Perfect for displaying status information, notification counts, and categorical tags with built-in accessibility and dismissible functionality.

## Official Documentation

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

## Features

- 🎨 **Multiple Variants**: Default, secondary, destructive, outline, success, warning, and info styles
- 📏 **Size Options**: Small, default, and large variants with responsive sizing
- 🔧 **Icon Support**: Leading and trailing icon slots with automatic sizing
- ❌ **Dismissible**: Optional close button functionality with fade animation support
- ♿ **Accessibility**: Proper ARIA attributes, keyboard navigation, and screen reader support
- ⌨️ **Keyboard Navigation**: Full keyboard accessibility for interactive elements
- 🎯 **Type-Safe**: Complete TypeScript support with typed variants and properties
- � **Customizable**: Additional CSS classes and styling options
- ⚡ **Performance**: Optimized with OnPush change detection and computed properties

## 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 badge component into your project:

```bash
ng-shangjc install badge
```

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 { BadgeComponent } from './ui/shangjc/badge';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [
    CommonModule,
    BadgeComponent,
  ],
  template: `
    <ng-shangjc-badge>
      Badge content
    </ng-shangjc-badge>
  `
})
export class ExampleComponent { }
```

### Using NgModule (Legacy)

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

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

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

Then use the components in your templates:

```html
<ng-shangjc-badge>
  Badge content
</ng-shangjc-badge>
```

## Basic Usage

### Default Example

```typescript
import { Component } from '@angular/core';
import { BadgeComponent } from './ui/shangjc/badge';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [BadgeComponent],
  template: `
    <ng-shangjc-badge>New</ng-shangjc-badge>
    <ng-shangjc-badge variant="secondary">Updated</ng-shangjc-badge>
    <ng-shangjc-badge variant="destructive">Error</ng-shangjc-badge>
  `,
})
export class ExampleComponent {}
```

### Alternative Usage Patterns

#### Status Indicators
```typescript
<ng-shangjc-badge variant="success">Active</ng-shangjc-badge>
<ng-shangjc-badge variant="warning">Pending</ng-shangjc-badge>
<ng-shangjc-badge variant="destructive">Blocked</ng-shangjc-badge>
```

#### Notification Badges
```typescript
<div class="relative">
  <button>Messages</button>
  <ng-shangjc-badge 
    variant="destructive" 
    size="sm" 
    [dismissible]="true"
    (dismissed)="clearNotification()"
    class="absolute -top-2 -right-2">
    5
  </ng-shangjc-badge>
</div>
```

## Advanced Usage

### Dismissible Badge

```typescript
import { Component } from '@angular/core';
import { BadgeComponent } from './ui/shangjc/badge';

@Component({
  selector: 'app-dismissible-example',
  standalone: true,
  imports: [BadgeComponent],
  template: `
    <!-- Basic dismissible badge -->
    <ng-shangjc-badge 
      [dismissible]="true"
      (dismissed)="onBadgeDismiss()">
      Dismissible badge
    </ng-shangjc-badge>

    <!-- With fade animation on dismiss -->
    <ng-shangjc-badge
      [dismissible]="true"
      [fade]="true"
      (dismissed)="onBadgeDismiss()">
      Fade out on dismiss
    </ng-shangjc-badge>
  `
})
export class DismissibleExampleComponent {
  onBadgeDismiss() {
    console.log('Badge dismissed');
  }
}
```

### Badge with Icons

```typescript
@Component({
  selector: 'app-icon-example',
  standalone: true,
  imports: [BadgeComponent],
  template: `
    <!-- Leading icon -->
    <ng-shangjc-badge>
      <svg leadingIcon class="h-3 w-3" 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>
      Verified
    </ng-shangjc-badge>

    <!-- Trailing icon -->
    <ng-shangjc-badge>
      Online
      <div trailingIcon class="h-2 w-2 bg-green-400 rounded-full"></div>
    </ng-shangjc-badge>
  `
})
export class IconExampleComponent {}
```

### Custom Styling

```typescript
@Component({
  selector: 'app-custom-example',
  standalone: true,
  imports: [BadgeComponent],
  template: `
    <ng-shangjc-badge 
      class="bg-purple-500 text-white hover:bg-purple-600">
      Custom
    </ng-shangjc-badge>
  `
})
export class CustomExampleComponent {}
```

## API Reference

### BadgeComponent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning' \| 'info'` | `'default'` | Badge style variant |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Badge size |
| `dismissible` | `boolean` | `false` | When true, shows a close button that removes the badge from the DOM when clicked |
| `fade` | `boolean` | `false` | Whether to use fade animation when dismissing (only applies when `dismissible` is true) |
| `class` | `string` | `''` | Additional CSS classes |
| `role` | `string` | `'status'` | ARIA role attribute |
| `ariaLabel` | `string` | `undefined` | ARIA label for accessibility |
| `dismissed` | `EventEmitter<void>` | - | Emitted when a dismissible badge is closed |

## Accessibility

- **Keyboard Navigation**: Full support for Tab, Shift+Tab, Enter, and Space keys on dismiss button
- **ARIA Attributes**: Proper ARIA labels, roles, and states for screen readers
- **Focus Management**: Visible focus indicators and proper focus handling on interactive elements
- **Screen Reader**: Compatible with screen readers and properly announces badge content and dismiss actions
- **Semantic Structure**: Uses proper HTML semantic elements with appropriate role attributes

### ARIA Features

- `role="status"` by default for non-interactive badges
- `aria-label` support for custom badge descriptions
- `aria-label` on dismiss button with context-aware text
- Focus management for dismissible badges
- Screen reader announcements for dismiss actions

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