# @isa/ui/label

A flexible label component for displaying tags and notices with configurable priority levels across Angular applications.

## Overview

The Label UI library provides a standalone Angular component for displaying visual labels with semantic meaning. It supports two distinct label types (Tag and Notice) and three priority levels (High, Medium, Low), enabling consistent visual communication of information status, categorization, and importance throughout the ISA application.

## Table of Contents

- [Features](#features)
- [Quick Start](#quick-start)
- [Core Concepts](#core-concepts)
- [API Reference](#api-reference)
- [Usage Examples](#usage-examples)
- [Styling and Customization](#styling-and-customization)
- [Testing](#testing)
- [Architecture Notes](#architecture-notes)

## Features

- **Two label types** - Tag and Notice for different semantic contexts
- **Three priority levels** - High, Medium, and Low for visual hierarchy
- **Standalone component** - Modern Angular architecture with explicit imports
- **Signal-based reactivity** - Uses Angular signals for efficient updates
- **Type-safe API** - TypeScript enums for label type and priority configuration
- **CSS class composition** - Dynamic class generation based on type and priority
- **OnPush change detection** - Optimized rendering performance
- **ViewEncapsulation.None** - Flexible styling with global CSS classes
- **Content projection** - Full control over label content via ng-content
- **Computed classes** - Reactive CSS class computation using Angular signals

## Quick Start

### 1. Import the Component

```typescript
import { Component } from '@angular/core';
import { LabelComponent, Labeltype, LabelPriority } from '@isa/ui/label';

@Component({
  selector: 'app-product-status',
  template: `
    <ui-label [type]="Labeltype.Tag" [priority]="LabelPriority.High">
      In Stock
    </ui-label>
  `,
  imports: [LabelComponent]
})
export class ProductStatusComponent {
  Labeltype = Labeltype;
  LabelPriority = LabelPriority;
}
```

### 2. Basic Tag Label

```typescript
@Component({
  template: `
    <ui-label [type]="Labeltype.Tag" [priority]="LabelPriority.Medium">
      New Arrival
    </ui-label>
  `,
  imports: [LabelComponent]
})
export class ProductBadgeComponent {
  Labeltype = Labeltype;
  LabelPriority = LabelPriority;
}
```

### 3. Notice Label

```typescript
@Component({
  template: `
    <ui-label [type]="Labeltype.Notice" [priority]="LabelPriority.High">
      Action Required
    </ui-label>
  `,
  imports: [LabelComponent]
})
export class AlertComponent {
  Labeltype = Labeltype;
  LabelPriority = LabelPriority;
}
```

## Core Concepts

### Label Types

The component supports two distinct label types, each with specific semantic meaning:

#### 1. Tag (Default)
- **Purpose**: Categorization, status indication, metadata display
- **Use Cases**: Product categories, order status, item tags, filters
- **Visual Style**: Typically compact, pill-shaped design
- **CSS Class**: `ui-label__tag`

#### 2. Notice
- **Purpose**: Notifications, alerts, important messages
- **Use Cases**: Error messages, warnings, system notifications, user alerts
- **Visual Style**: Typically more prominent, attention-grabbing design
- **CSS Class**: `ui-label__notice`

### Priority Levels

Each label type can have one of three priority levels that control visual hierarchy:

#### 1. High Priority (Default)
- **Purpose**: Critical information, urgent status, primary actions
- **Visual Characteristics**: Most prominent styling, often with bold colors
- **Use Cases**: Error states, critical alerts, primary status
- **CSS Classes**:
  - `ui-label__tag-priority-high` (for Tag type)
  - `ui-label__notice-priority-high` (for Notice type)

#### 2. Medium Priority
- **Purpose**: Important but non-critical information
- **Visual Characteristics**: Moderate emphasis, balanced contrast
- **Use Cases**: Warnings, secondary status, informational notices
- **CSS Classes**:
  - `ui-label__tag-priority-medium` (for Tag type)
  - `ui-label__notice-priority-medium` (for Notice type)

#### 3. Low Priority
- **Purpose**: Supplementary information, subtle indicators
- **Visual Characteristics**: Minimal emphasis, subtle colors
- **Use Cases**: Hints, optional metadata, background information
- **CSS Classes**:
  - `ui-label__tag-priority-low` (for Tag type)
  - `ui-label__notice-priority-low` (for Notice type)

### Signal-Based Reactivity

The component uses Angular signals for reactive CSS class computation:

```typescript
// Signal inputs
type = input<Labeltype>(Labeltype.Tag);
priority = input<LabelPriority>(LabelPriority.High);

// Computed signal for type class
typeClass = computed(() => `ui-label__${this.type()}`);

// Computed signal for priority class (combines type and priority)
priorityClass = computed(() => `${this.typeClass()}-priority-${this.priority()}`);
```

This approach provides:
- **Automatic updates** - Classes update when inputs change
- **Efficient rendering** - Only recomputes when dependencies change
- **Type safety** - TypeScript ensures valid type/priority combinations

### CSS Class Structure

The component applies a hierarchical class structure:

```
ui-label                                  (base class)
├── ui-label__tag                         (type class for Tag)
│   ├── ui-label__tag-priority-high       (Tag + High priority)
│   ├── ui-label__tag-priority-medium     (Tag + Medium priority)
│   └── ui-label__tag-priority-low        (Tag + Low priority)
└── ui-label__notice                      (type class for Notice)
    ├── ui-label__notice-priority-high    (Notice + High priority)
    ├── ui-label__notice-priority-medium  (Notice + Medium priority)
    └── ui-label__notice-priority-low     (Notice + Low priority)
```

## API Reference

### LabelComponent

Standalone component for displaying labels with type and priority.

#### Selector
```html
<ui-label>Content</ui-label>
```

#### Inputs

##### `type`
- **Type**: `Labeltype`
- **Default**: `Labeltype.Tag`
- **Description**: The semantic type of the label
- **Values**:
  - `Labeltype.Tag` - For categorization and status
  - `Labeltype.Notice` - For notifications and alerts

**Example:**
```html
<ui-label [type]="Labeltype.Notice">Important Notice</ui-label>
```

##### `priority`
- **Type**: `LabelPriority`
- **Default**: `LabelPriority.High`
- **Description**: The visual priority level of the label
- **Values**:
  - `LabelPriority.High` - Highest visual emphasis
  - `LabelPriority.Medium` - Moderate visual emphasis
  - `LabelPriority.Low` - Subtle visual emphasis

**Example:**
```html
<ui-label [priority]="LabelPriority.Medium">Optional Info</ui-label>
```

#### Computed Properties

##### `typeClass()`
- **Type**: `Signal<string>`
- **Returns**: CSS class string based on current type
- **Format**: `ui-label__${type}`
- **Example**: `"ui-label__tag"` or `"ui-label__notice"`

##### `priorityClass()`
- **Type**: `Signal<string>`
- **Returns**: CSS class string combining type and priority
- **Format**: `ui-label__${type}-priority-${priority}`
- **Example**: `"ui-label__tag-priority-high"`

#### Host Classes

The component automatically applies the following classes to its host element:

```typescript
['ui-label', typeClass(), priorityClass()]
```

Example rendered classes:
```html
<ui-label class="ui-label ui-label__tag ui-label__tag-priority-high">
  Content
</ui-label>
```

### Type Definitions

#### Labeltype

TypeScript enum for label type values:

```typescript
export const Labeltype = {
  Tag: 'tag',
  Notice: 'notice',
} as const;

export type Labeltype = (typeof Labeltype)[keyof typeof Labeltype];
```

**Usage:**
```typescript
import { Labeltype } from '@isa/ui/label';

// In template
[type]="Labeltype.Tag"
[type]="Labeltype.Notice"

// In component class
readonly labelType = Labeltype.Tag;
```

#### LabelPriority

TypeScript enum for priority level values:

```typescript
export const LabelPriority = {
  High: 'high',
  Medium: 'medium',
  Low: 'low',
} as const;

export type LabelPriority = (typeof LabelPriority)[keyof typeof LabelPriority];
```

**Usage:**
```typescript
import { LabelPriority } from '@isa/ui/label';

// In template
[priority]="LabelPriority.High"
[priority]="LabelPriority.Medium"
[priority]="LabelPriority.Low"

// In component class
readonly priority = LabelPriority.Medium;
```

## Usage Examples

### Product Status Tags

```typescript
import { Component } from '@angular/core';
import { LabelComponent, Labeltype, LabelPriority } from '@isa/ui/label';

@Component({
  selector: 'app-product-card',
  template: `
    <div class="product-card">
      <h3>{{ product.name }}</h3>

      <!-- In Stock - High priority tag -->
      <ui-label
        [type]="Labeltype.Tag"
        [priority]="LabelPriority.High">
        In Stock
      </ui-label>

      <!-- Category - Medium priority tag -->
      <ui-label
        [type]="Labeltype.Tag"
        [priority]="LabelPriority.Medium">
        Electronics
      </ui-label>

      <!-- Condition - Low priority tag -->
      <ui-label
        [type]="Labeltype.Tag"
        [priority]="LabelPriority.Low">
        New
      </ui-label>
    </div>
  `,
  imports: [LabelComponent]
})
export class ProductCardComponent {
  Labeltype = Labeltype;
  LabelPriority = LabelPriority;

  product = {
    name: 'Wireless Headphones',
    inStock: true,
    category: 'Electronics'
  };
}
```

### Order Status Indicators

```typescript
import { Component, input, computed } from '@angular/core';
import { LabelComponent, Labeltype, LabelPriority } from '@isa/ui/label';

@Component({
  selector: 'app-order-status',
  template: `
    <ui-label
      [type]="Labeltype.Tag"
      [priority]="statusPriority()">
      {{ statusText() }}
    </ui-label>
  `,
  imports: [LabelComponent]
})
export class OrderStatusComponent {
  Labeltype = Labeltype;

  status = input.required<'pending' | 'processing' | 'shipped' | 'delivered'>();

  statusText = computed(() => {
    const statusMap = {
      pending: 'Pending',
      processing: 'Processing',
      shipped: 'Shipped',
      delivered: 'Delivered'
    };
    return statusMap[this.status()];
  });

  statusPriority = computed(() => {
    const priorityMap = {
      pending: LabelPriority.High,
      processing: LabelPriority.High,
      shipped: LabelPriority.Medium,
      delivered: LabelPriority.Low
    };
    return priorityMap[this.status()];
  });
}
```

### System Notifications

```typescript
import { Component, input } from '@angular/core';
import { LabelComponent, Labeltype, LabelPriority } from '@isa/ui/label';

interface Notification {
  id: number;
  message: string;
  type: 'error' | 'warning' | 'info';
}

@Component({
  selector: 'app-notification-item',
  template: `
    <div class="notification">
      <ui-label
        [type]="Labeltype.Notice"
        [priority]="getNotificationPriority()">
        {{ getNotificationLabel() }}
      </ui-label>
      <p>{{ notification().message }}</p>
    </div>
  `,
  imports: [LabelComponent]
})
export class NotificationItemComponent {
  Labeltype = Labeltype;
  LabelPriority = LabelPriority;

  notification = input.required<Notification>();

  getNotificationPriority(): LabelPriority {
    const type = this.notification().type;
    switch (type) {
      case 'error':
        return LabelPriority.High;
      case 'warning':
        return LabelPriority.Medium;
      case 'info':
        return LabelPriority.Low;
    }
  }

  getNotificationLabel(): string {
    const type = this.notification().type;
    return type.charAt(0).toUpperCase() + type.slice(1);
  }
}
```

### Dynamic Labels with NgFor

```typescript
import { Component } from '@angular/core';
import { LabelComponent, Labeltype, LabelPriority } from '@isa/ui/label';

@Component({
  selector: 'app-product-tags',
  template: `
    <div class="tags-container">
      @for (tag of tags; track tag.id) {
        <ui-label
          [type]="Labeltype.Tag"
          [priority]="tag.priority">
          {{ tag.label }}
        </ui-label>
      }
    </div>
  `,
  imports: [LabelComponent]
})
export class ProductTagsComponent {
  Labeltype = Labeltype;

  tags = [
    { id: 1, label: 'Sale', priority: LabelPriority.High },
    { id: 2, label: 'Free Shipping', priority: LabelPriority.Medium },
    { id: 3, label: 'Eco-Friendly', priority: LabelPriority.Low },
  ];
}
```

### Conditional Label Display

```typescript
import { Component, input, computed } from '@angular/core';
import { LabelComponent, Labeltype, LabelPriority } from '@isa/ui/label';

@Component({
  selector: 'app-inventory-status',
  template: `
    @if (showStockLabel()) {
      <ui-label
        [type]="Labeltype.Tag"
        [priority]="stockPriority()">
        {{ stockLabel() }}
      </ui-label>
    }
  `,
  imports: [LabelComponent]
})
export class InventoryStatusComponent {
  Labeltype = Labeltype;
  LabelPriority = LabelPriority;

  stockQuantity = input.required<number>();

  showStockLabel = computed(() => this.stockQuantity() < 10);

  stockLabel = computed(() => {
    const qty = this.stockQuantity();
    if (qty === 0) return 'Out of Stock';
    if (qty < 5) return 'Low Stock';
    return 'Limited Stock';
  });

  stockPriority = computed(() => {
    const qty = this.stockQuantity();
    if (qty === 0) return LabelPriority.High;
    if (qty < 5) return LabelPriority.High;
    return LabelPriority.Medium;
  });
}
```

## Styling and Customization

### CSS Class Hierarchy

The component generates a predictable class structure for styling:

```css
/* Base class applied to all labels */
.ui-label {
  display: inline-block;
  font-family: var(--isa-font-family);
  /* Base styles */
}

/* Type-specific base styles */
.ui-label__tag {
  /* Tag-specific base styles */
}

.ui-label__notice {
  /* Notice-specific base styles */
}

/* Priority-specific styles for Tags */
.ui-label__tag-priority-high {
  background-color: var(--isa-accent-red);
  color: white;
  font-weight: 600;
}

.ui-label__tag-priority-medium {
  background-color: var(--isa-accent-yellow);
  color: var(--isa-text-primary);
  font-weight: 500;
}

.ui-label__tag-priority-low {
  background-color: var(--isa-neutral-200);
  color: var(--isa-text-secondary);
  font-weight: 400;
}

/* Priority-specific styles for Notices */
.ui-label__notice-priority-high {
  border-left: 4px solid var(--isa-accent-red);
  background-color: var(--isa-accent-red-light);
  padding: 0.5rem 1rem;
}

.ui-label__notice-priority-medium {
  border-left: 4px solid var(--isa-accent-yellow);
  background-color: var(--isa-accent-yellow-light);
  padding: 0.5rem 1rem;
}

.ui-label__notice-priority-low {
  border-left: 4px solid var(--isa-neutral-300);
  background-color: var(--isa-neutral-100);
  padding: 0.5rem 1rem;
}
```

### Custom Styling Example

```scss
// Override specific label styles
.product-card {
  ui-label {
    border-radius: 4px;
    padding: 0.25rem 0.75rem;
    font-size: 0.875rem;
    text-transform: uppercase;
    letter-spacing: 0.05em;
  }

  // Custom high-priority tag style
  .ui-label__tag-priority-high {
    animation: pulse 2s infinite;
  }

  // Custom notice styles
  .ui-label__notice {
    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  }
}
```

### Tailwind CSS Integration

The component works seamlessly with Tailwind's design system:

```html
<!-- Using Tailwind utility classes alongside the component -->
<ui-label
  [type]="Labeltype.Tag"
  [priority]="LabelPriority.High"
  class="rounded-full px-3 py-1 text-xs font-semibold">
  Featured
</ui-label>
```

## Testing

The library uses **Vitest** with **Angular Testing Utilities** for testing.

### Running Tests

```bash
# Run tests for this library
npx nx test label --skip-nx-cache

# Run tests with coverage
npx nx test label --code-coverage --skip-nx-cache

# Run tests in watch mode
npx nx test label --watch
```

### Test Structure

The library includes comprehensive unit tests covering:

- **Type input** - Validates correct CSS class generation for each type
- **Priority input** - Validates correct CSS class generation for each priority
- **Default values** - Tests default type and priority behavior
- **Content projection** - Tests ng-content rendering
- **Signal reactivity** - Tests computed class updates when inputs change
- **Class composition** - Tests correct combination of base, type, and priority classes

### Example Test

```typescript
import { ComponentFixture, TestBed } from '@angular/core/testing';
import { describe, it, expect, beforeEach } from 'vitest';
import { LabelComponent, Labeltype, LabelPriority } from './label.component';

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

  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [LabelComponent]
    });
    fixture = TestBed.createComponent(LabelComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

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

  it('should have default type as Tag', () => {
    expect(component.type()).toBe(Labeltype.Tag);
  });

  it('should have default priority as High', () => {
    expect(component.priority()).toBe(LabelPriority.High);
  });

  it('should generate correct type class for Tag', () => {
    fixture.componentRef.setInput('type', Labeltype.Tag);
    expect(component.typeClass()).toBe('ui-label__tag');
  });

  it('should generate correct priority class', () => {
    fixture.componentRef.setInput('type', Labeltype.Tag);
    fixture.componentRef.setInput('priority', LabelPriority.Medium);
    expect(component.priorityClass()).toBe('ui-label__tag-priority-medium');
  });

  it('should apply all classes to host element', () => {
    fixture.componentRef.setInput('type', Labeltype.Notice);
    fixture.componentRef.setInput('priority', LabelPriority.Low);
    fixture.detectChanges();

    const element = fixture.nativeElement as HTMLElement;
    expect(element.classList.contains('ui-label')).toBe(true);
    expect(element.classList.contains('ui-label__notice')).toBe(true);
    expect(element.classList.contains('ui-label__notice-priority-low')).toBe(true);
  });
});
```

## Architecture Notes

### Current Architecture

The library follows Angular standalone component architecture:

```
LabelComponent (Standalone)
├── Signal Inputs
│   ├── type: Signal<Labeltype>
│   └── priority: Signal<LabelPriority>
├── Computed Signals
│   ├── typeClass(): string
│   └── priorityClass(): string
└── Host Binding
    └── [class]: computed classes array
```

### Design Decisions

#### 1. Standalone Component Architecture

**Decision**: Use standalone component instead of NgModule
**Rationale**:
- Aligns with Angular 20.1.2 best practices
- Reduces boilerplate and complexity
- Improves tree-shaking and bundle optimization
- Enables explicit, localized imports

**Impact**: Simpler consumption in feature modules

#### 2. Signal-Based Reactivity

**Decision**: Use `input()` and `computed()` signals instead of traditional inputs
**Rationale**:
- Modern Angular reactivity model
- Automatic dependency tracking
- Better performance with change detection
- Type-safe reactive transformations

**Impact**: Efficient CSS class updates without manual change detection

#### 3. ViewEncapsulation.None

**Decision**: Use ViewEncapsulation.None instead of Emulated or ShadowDOM
**Rationale**:
- Enables global styling through BEM-like class naming
- Consistent with ISA design system approach
- Easier integration with Tailwind CSS
- Flexible theming capabilities

**Impact**: Requires careful CSS class naming to avoid conflicts

#### 4. OnPush Change Detection

**Decision**: Use OnPush change detection strategy
**Rationale**:
- Optimal performance with signal-based inputs
- Reduces unnecessary change detection cycles
- Signals automatically trigger required updates
- Best practice for presentational components

**Impact**: Better performance, especially in large lists

#### 5. TypeScript Const Assertions for Enums

**Decision**: Use const objects with type inference instead of traditional enums
**Rationale**:
- Better type safety with literal types
- Improved autocomplete in IDEs
- Smaller JavaScript bundle size
- More flexible than traditional TypeScript enums

**Impact**: Type-safe API with minimal runtime overhead

### Performance Considerations

1. **Signal-based inputs** - Only recompute classes when inputs actually change
2. **OnPush change detection** - Minimal change detection overhead
3. **Computed signals** - Efficient memoization of class strings
4. **No template logic** - All computation in component class
5. **Lightweight DOM** - Simple ng-content projection with no wrapper elements

### Future Enhancements

Potential improvements identified:

1. **Icon Support** - Add optional icon input for visual enhancement
2. **Dismissible Labels** - Add optional close button with output event
3. **Animation Support** - Add entry/exit animations for dynamic labels
4. **Theme Variants** - Support custom color themes via injection tokens
5. **Size Variants** - Add size input (small, medium, large)
6. **Accessibility Improvements** - Add ARIA attributes for screen readers
7. **Tooltip Integration** - Built-in tooltip support for truncated content

## Dependencies

### Required Libraries

- `@angular/core` - Angular framework (20.1.2)
- `@angular/common` - CommonModule for basic directives

### Optional Libraries

None - this is a pure presentation component with no external dependencies.

### Path Alias

Import from: `@isa/ui/label`

## License

Internal ISA Frontend library - not for external distribution.
