# Badge Component

The `ccl-badge` component is a versatile UI element used for status indicators, category tags, count displays, and labels. It supports multiple variants, sizes, and interactive states while maintaining full accessibility compliance.

## Features

- **Multiple Variants**: Default, success, error, warning, info, and custom
- **Flexible Sizing**: Small, medium, and large sizes
- **Interactive States**: Clickable and dismissible options
- **Count Support**: Numeric badges with automatic overflow handling (999+)
- **Accessibility**: Full ARIA support and keyboard navigation
- **Design Tokens**: Consistent theming with design system tokens
- **Responsive**: Mobile-optimized sizing and behavior

## Usage

### Basic Import

```typescript
import { BadgeComponent } from '@Crystal-Code-Labs/ccl-ui-components';

@Component({
  imports: [BadgeComponent],
  // ...
})
export class MyComponent {}
```

### Basic Examples

```html
<!-- Status Badges -->
<ccl-badge variant="success" label="Active"></ccl-badge>
<ccl-badge variant="error" label="Failed"></ccl-badge>
<ccl-badge variant="warning" label="Pending"></ccl-badge>
<ccl-badge variant="info" label="Processing"></ccl-badge>

<!-- Count Badges -->
<ccl-badge count="5"></ccl-badge>
<ccl-badge count="42" variant="success"></ccl-badge>

<!-- Dismissible Badges -->
<ccl-badge 
  variant="info" 
  label="Beta Feature" 
  dismissible 
  (onDismiss)="onDismiss($event)">
</ccl-badge>

<!-- Clickable Badges -->
<ccl-badge 
  variant="default" 
  label="Click Me" 
  clickable 
  (onClick)="onBadgeClick($event)">
</ccl-badge>

<!-- Custom Color Badge -->
<ccl-badge 
  variant="custom" 
  label="Custom" 
  customColor="#ff6b6b">
</ccl-badge>
```

## API Reference

### Inputs

| Input | Type | Default | Description |
|-------|------|---------|-------------|
| `variant` | `'default' \| 'success' \| 'error' \| 'warning' \| 'info' \| 'custom'` | `'default'` | Visual variant of the badge |
| `label` | `string` | `''` | Text content of the badge |
| `icon` | `string` | `''` | Leading icon (emoji or character) |
| `dismissible` | `boolean` | `false` | Whether the badge can be dismissed |
| `count` | `number \| null` | `null` | Numeric value for count badges |
| `clickable` | `boolean` | `false` | Whether the badge is clickable |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the badge |
| `customColor` | `string` | `''` | Custom background color (when variant is 'custom') |
| `disabled` | `boolean` | `false` | Whether the badge is disabled |

### Outputs

| Output | Type | Description |
|--------|------|-------------|
| `onDismiss` | `EventEmitter<void>` | Emitted when dismiss button is clicked |
| `onClick` | `EventEmitter<void>` | Emitted when badge is clicked (if clickable) |

## Variants

### Default Variant
```html
<ccl-badge label="Default Badge"></ccl-badge>
```
- Gray background with dark text
- Used for general labels and tags

### Success Variant
```html
<ccl-badge variant="success" label="Active"></ccl-badge>
```
- Green background with white text
- Used for positive states and confirmations

### Error Variant
```html
<ccl-badge variant="error" label="Failed"></ccl-badge>
```
- Red background with white text
- Used for errors and critical states

### Warning Variant
```html
<ccl-badge variant="warning" label="Pending"></ccl-badge>
```
- Orange background with white text
- Used for warnings and caution states

### Info Variant
```html
<ccl-badge variant="info" label="Processing"></ccl-badge>
```
- Blue background with white text
- Used for informational states

### Custom Variant
```html
<ccl-badge 
  variant="custom" 
  label="Custom" 
  customColor="#ff6b6b">
</ccl-badge>
```
- Custom background color with white text
- Used for brand-specific or unique styling

## Sizes

### Small (sm)
```html
<ccl-badge size="sm" label="Small"></ccl-badge>
```
- Compact size for tight spaces
- Smaller font and padding

### Medium (md) - Default
```html
<ccl-badge size="md" label="Medium"></ccl-badge>
```
- Standard size for most use cases
- Balanced font and padding

### Large (lg)
```html
<ccl-badge size="lg" label="Large"></ccl-badge>
```
- Larger size for emphasis
- Bigger font and padding

## Interactive States

### Clickable Badges
```html
<ccl-badge 
  variant="success" 
  label="Click Me" 
  clickable 
  (onClick)="handleClick()">
</ccl-badge>
```

Features:
- Renders as a button element
- Keyboard accessible (Enter/Space)
- Hover and focus states
- Click event emission

### Dismissible Badges
```html
<ccl-badge 
  variant="info" 
  label="Dismissible" 
  dismissible 
  (onDismiss)="handleDismiss()">
</ccl-badge>
```

Features:
- Close button (×) on the right
- Keyboard accessible dismiss button
- Dismiss event emission
- Prevents event bubbling

## Count Badges

### Basic Count
```html
<ccl-badge count="5"></ccl-badge>
<ccl-badge count="42" variant="success"></ccl-badge>
```

### Large Counts
```html
<ccl-badge count="1500"></ccl-badge>
<!-- Displays as "999+" -->
```

Features:
- Automatic overflow handling (999+)
- Pill-shaped design
- Minimal width for small numbers
- Can be combined with variants

## Icons

### Leading Icon
```html
<ccl-badge 
  variant="success" 
  label="Starred" 
  icon="★">
</ccl-badge>
```

Features:
- Supports emoji and Unicode characters
- Only shown when count is null
- Positioned before the label text

## Accessibility

### ARIA Support
- **Role**: `button` (interactive), `status` (non-interactive)
- **aria-label**: Descriptive label for screen readers
- **tabindex**: `0` (interactive), `-1` (non-interactive)

### Keyboard Navigation
- **Enter/Space**: Activates clickable badges
- **Enter/Space**: Triggers dismiss button
- **Tab**: Focuses interactive badges

### Screen Reader Support
```html
<!-- Screen reader announces: "Active, success badge" -->
<ccl-badge variant="success" label="Active"></ccl-badge>

<!-- Screen reader announces: "Count: 5" -->
<ccl-badge count="5"></ccl-badge>

<!-- Screen reader announces: "Remove Beta Feature" -->
<ccl-badge 
  variant="info" 
  label="Beta Feature" 
  dismissible>
</ccl-badge>
```

## Styling

### Design Tokens
The component uses design tokens for consistent theming:

```css
/* Colors */
--color-success-500
--color-error-500
--color-warning-500
--color-info-500
--color-surface
--color-text

/* Typography */
--typography-font-family-sans
--typography-font-size-xs
--typography-font-size-sm
--typography-font-size-md
--typography-font-weight-semibold

/* Spacing */
--spacing-xs
--spacing-sm
--spacing-md

/* Radius */
--radius-pill
--radius-md

/* Motion */
--motion-fast
```

### Custom Styling
```css
/* Custom badge styling */
.ccl-badge--custom {
  background: linear-gradient(45deg, #ff6b6b, #4ecdc4);
  color: white;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
```

## Real-World Examples

### Status Dashboard
```html
<div class="status-dashboard">
  <h3>System Status</h3>
  <div class="status-badges">
    <ccl-badge variant="success" label="API Online"></ccl-badge>
    <ccl-badge variant="warning" label="Database Slow"></ccl-badge>
    <ccl-badge variant="error" label="Cache Down"></ccl-badge>
  </div>
</div>
```

### Notification Counter
```html
<div class="notification-header">
  <h2>Notifications</h2>
  <ccl-badge count="3" variant="error"></ccl-badge>
</div>
```

### Tag Cloud
```html
<div class="tag-cloud">
  <ccl-badge variant="default" label="JavaScript"></ccl-badge>
  <ccl-badge variant="default" label="TypeScript"></ccl-badge>
  <ccl-badge variant="default" label="Angular"></ccl-badge>
  <ccl-badge variant="default" label="React"></ccl-badge>
  <ccl-badge variant="default" label="Vue"></ccl-badge>
</div>
```

### Filter Tags
```html
<div class="active-filters">
  <span>Active Filters:</span>
  <ccl-badge 
    variant="info" 
    label="Category: Electronics" 
    dismissible 
    (onDismiss)="removeFilter('category')">
  </ccl-badge>
  <ccl-badge 
    variant="info" 
    label="Price: $0-$100" 
    dismissible 
    (onDismiss)="removeFilter('price')">
  </ccl-badge>
</div>
```

### Action Buttons
```html
<div class="action-buttons">
  <ccl-badge 
    variant="success" 
    label="Approve" 
    clickable 
    (onClick)="approveItem()">
  </ccl-badge>
  <ccl-badge 
    variant="error" 
    label="Reject" 
    clickable 
    (onClick)="rejectItem()">
  </ccl-badge>
</div>
```

## Integration with Forms

### Form Field Tags
```html
<ccl-form-field-wrapper label="Skills" hint="Add your technical skills">
  <div class="skills-container">
    <input 
      type="text" 
      placeholder="Add a skill..."
      (keyup.enter)="addSkill($event)">
    
    <div class="skill-tags">
      @for (skill of skills; track skill) {
        <ccl-badge 
          variant="default" 
          [label]="skill" 
          dismissible 
          (onDismiss)="removeSkill(skill)">
        </ccl-badge>
      }
    </div>
  </div>
</ccl-form-field-wrapper>
```

## Testing

### Unit Testing
```typescript
import { ComponentFixture, TestBed } from '@angular/core/testing';
import { BadgeComponent } from '@Crystal-Code-Labs/ccl-ui-components';

describe('BadgeComponent', () => {
  let component: BadgeComponent;
  let fixture: ComponentFixture<BadgeComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [BadgeComponent],
    }).compileComponents();

    fixture = TestBed.createComponent(BadgeComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });

  it('should emit onClick when clicked and clickable', () => {
    component.clickable = true;
    spyOn(component.onClick, 'emit');
    
    const badgeElement = fixture.debugElement.query(By.css('.ccl-badge'));
    badgeElement.nativeElement.click();
    
    expect(component.onClick.emit).toHaveBeenCalled();
  });

  it('should display count correctly', () => {
    component.count = 42;
    fixture.detectChanges();
    
    const contentElement = fixture.debugElement.query(By.css('.ccl-badge__content'));
    expect(contentElement.nativeElement.textContent.trim()).toBe('42');
  });
});
```

### Integration Testing
```typescript
it('should work with reactive forms', () => {
  const form = new FormGroup({
    tags: new FormControl(['tag1', 'tag2'])
  });
  
  // Test form integration
  expect(form.get('tags')?.value).toEqual(['tag1', 'tag2']);
});
```

## Migration Guide

### From HTML Badges
```html
<!-- Before -->
<span class="badge badge-success">Active</span>

<!-- After -->
<ccl-badge variant="success" label="Active"></ccl-badge>
```

### From Custom Components
```html
<!-- Before -->
<my-custom-tag [text]="'Beta'" [color]="'blue'"></my-custom-tag>

<!-- After -->
<ccl-badge variant="info" label="Beta"></ccl-badge>
```

## Browser Support

- **Modern Browsers**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
- **Mobile**: iOS Safari 14+, Chrome Mobile 90+
- **Accessibility**: Screen readers, keyboard navigation
- **Responsive**: Mobile-optimized sizing and behavior

## Performance

- **Bundle Size**: ~2KB minified + gzipped
- **Runtime**: Minimal overhead, efficient change detection
- **Memory**: Lightweight component with minimal memory footprint
- **Rendering**: Optimized for frequent updates and animations

## Troubleshooting

### Common Issues

**Badge not showing custom color:**
```html
<!-- Make sure to set variant="custom" -->
<ccl-badge 
  variant="custom" 
  customColor="#ff6b6b" 
  label="Custom">
</ccl-badge>
```

**Click events not working:**
```html
<!-- Ensure clickable is set to true -->
<ccl-badge 
  clickable="true" 
  (onClick)="handleClick()" 
  label="Clickable">
</ccl-badge>
```

**Accessibility issues:**
- Ensure proper ARIA labels
- Test with screen readers
- Verify keyboard navigation
- Check color contrast ratios

## Best Practices

1. **Use appropriate variants** for different states
2. **Keep labels concise** for better readability
3. **Provide meaningful ARIA labels** for screen readers
4. **Use count badges sparingly** to avoid visual clutter
5. **Test keyboard navigation** for interactive badges
6. **Consider mobile sizing** for responsive design
7. **Use consistent sizing** within the same context
8. **Provide clear dismiss actions** for dismissible badges