ISA-Frontend/libs/icons/README.md

# icons

## Overview

The `@isa/icons` library is a centralized icon repository for the ISA Frontend monorepo. It provides **75 inline SVG icons** as string constants, organized by functional categories. All icons are exported as ready-to-use SVG markup strings that can be embedded directly in Angular templates.

## Icon Categories

The library contains **9 distinct categories** of icons:

| Category | Count | Purpose | Examples |
|----------|-------|---------|----------|
| **Navigation** | 23 | Main navigation, UI controls, menu items | `isaNavigationSidemenu`, `isaNavigationCart`, `isaNavigationKunden` |
| **Action** | 15 | User actions, buttons, interactive elements | `isaActionChevron`, `isaActionPlus`, `isaActionSearch`, `isaActionEdit` |
| **Reviews** | 13 | Small-sized icons for reviews/ratings UI | `isaReviewsStarSmall`, `isaReviewsChevronSmall`, `isaReviewsCheckSmall` |
| **Artikel** | 8 | Product format indicators | `isaArtikelTaschenbuch`, `isaArtikelCd`, `isaArtikelEbook`, `isaArtikelGame` |
| **Delivery** | 7 | Delivery/fulfillment methods | `isaDeliveryWarenausgabe`, `isaDeliveryVersand`, `isaDeliveryDownload` |
| **Other** | 3 | Miscellaneous UI elements | `isaOtherHeart`, `isaOtherGift`, `isaOtherInfo` |
| **Sort** | 2 | Sorting indicators | `isaSortByUpMedium`, `isaSortByDownMedium` |
| **Loading** | 2 | Loading/spinner animations | `isaLoading`, `isaLoadingSmall` |
| **Filiale** | 2 | Store/branch location icons | `isaFiliale`, `isaFilialeLocation` |

## Icon Format & Technical Details

- **Format:** Inline SVG markup strings
- **Size:** Most icons are 24×24px, with "Small" variants at 12×12px
- **Style:** All icons use `fill="currentColor"` or `stroke="currentColor"` for easy color customization via CSS
- **Naming Convention:** `isa[Category][Name]` (e.g., `isaActionChevron`, `isaNavigationCart`)

## Usage

### Import Individual Icons

```typescript
import { isaActionSearch, isaNavigationCart } from '@isa/icons';

@Component({
  selector: 'app-my-component',
  template: `
    <div [innerHTML]="searchIcon"></div>
    <div [innerHTML]="cartIcon"></div>
  `,
  standalone: true,
})
export class MyComponent {
  searchIcon = isaActionSearch;
  cartIcon = isaNavigationCart;
}
```

### Import Icon Group

```typescript
import { ProductFormatIconGroup } from '@isa/icons';

@Component({
  selector: 'app-product-display',
  template: `<div [innerHTML]="getProductIcon(product.format)"></div>`,
  standalone: true,
})
export class ProductDisplayComponent {
  getProductIcon(format: string): string {
    return ProductFormatIconGroup[format] || ProductFormatIconGroup['ka'];
  }
}
```

### Import All Icons

```typescript
import { IsaIcons } from '@isa/icons';

const searchIcon = IsaIcons.isaActionSearch;
const cartIcon = IsaIcons.isaNavigationCart;
```

## Color Customization

All icons use `currentColor`, allowing easy theming via CSS color inheritance:

```html
<!-- Icon inherits text color from parent -->
<div class="text-isa-accent-500" [innerHTML]="isaActionSearch"></div>

<!-- Icon inherits from inline style -->
<div style="color: #FF5733;" [innerHTML]="isaNavigationCart"></div>
```

## Icon Groups

### ProductFormatIconGroup

Maps product format codes to appropriate icons:

```typescript
export const ProductFormatIconGroup = {
  tb: icons.isaArtikelTaschenbuch,  // Taschenbuch (paperback)
  hc: icons.isaArtikelKartoniert,   // Kartoniert (hardcover)
  au: icons.isaArtikelCd,           // Audio CD
  ka: icons.isaArtikelSonstige,     // Sonstige (other)
  sw: icons.isaArtikelCd,           // Software CD
  nb: icons.isaArtikelGame,         // Game
};
```

**Usage:**
```typescript
const icon = ProductFormatIconGroup['tb']; // Gets paperback icon
```

## Available Icons

### Navigation Icons (23)
- `isaNavigationSidemenu`, `isaNavigationCart`, `isaNavigationKunden`, `isaNavigationFilialen`
- `isaNavigationRuecklage`, `isaNavigationRemission`, `isaNavigationWareneingang`, `isaNavigationWws`
- `isaNavigationOrder`, `isaNavigationFile`, `isaNavigationDownload`, `isaNavigationPrint`
- `isaNavigationCalendar`, `isaNavigationScan`, `isaNavigationSettings`, `isaNavigationHelp`
- `isaNavigationLogout`, `isaNavigationHome`, `isaNavigationBack`, `isaNavigationForward`
- `isaNavigationClose`, `isaNavigationMenu`, `isaNavigationMore`

### Action Icons (15)
- `isaActionChevron` / `isaActionChevronDown`, `isaActionChevronUp`, `isaActionChevronLeft`, `isaActionChevronRight`
- `isaActionPlus`, `isaActionMinus`, `isaActionSearch`, `isaActionEdit`, `isaActionDelete`
- `isaActionSave`, `isaActionCancel`, `isaActionRefresh`, `isaActionFilter`, `isaActionExport`

### Reviews Icons (13)
- `isaReviewsStarSmall`, `isaReviewsStarHalfSmall`, `isaReviewsStarEmptySmall`
- `isaReviewsChevronSmall`, `isaReviewsCheckSmall`, `isaReviewsCloseSmall`
- And 7 more small variants...

### Product Format Icons (8)
- `isaArtikelTaschenbuch`, `isaArtikelKartoniert`, `isaArtikelCd`, `isaArtikelDvd`
- `isaArtikelEbook`, `isaArtikelGame`, `isaArtikelSonstige`, `isaArtikelVinyl`

### Delivery Method Icons (7)
- `isaDeliveryWarenausgabe`, `isaDeliveryVersand`, `isaDeliveryDownload`
- `isaDeliveryRuecklage1`, `isaDeliveryRuecklage2`, `isaDeliveryAbholfach`
- `isaDeliveryExpress`

## Size Variants

The library provides size variants for specific use cases:

- **Standard:** 24×24px (most icons)
- **Small:** 12×12px (icons with `Small` suffix, e.g., `isaReviewsStarSmall`)

## Security Considerations

When using icons with `[innerHTML]`, Angular's DomSanitizer automatically handles security. However, if you bypass sanitization, ensure icons come from trusted sources.

## Performance Notes

- **Bundle Size:** All 75 icons are included in consuming bundles when imported
- **Inline SVGs:** Avoid HTTP requests but increase bundle size
- **Tree Shaking:** Only import the icons you need to minimize bundle impact

## E2E Testing

When using icons in clickable elements, ensure proper `data-what` and `data-which` attributes on parent elements:

```html
<button
  data-what="button"
  data-which="search-action"
  (click)="search()"
>
  <span [innerHTML]="isaActionSearch"></span>
  Search
</button>
```

## Running Tests

Run unit tests with Jest:

```bash
npx nx test icons
```

## Related Libraries

The icons library integrates with:
- **UI Component Libraries:** Used extensively in `@isa/ui/*` components
- **Feature Libraries:** Referenced in domain features for contextual icons
- **Shared Components:** Used in `@isa/shared/*` for product displays and navigation