ISA-Frontend/libs/icons/README.md

# @isa/icons

A centralized icon library for the ISA-Frontend monorepo providing inline SVG icons as string constants.

## Overview

The `@isa/icons` library is a centralized icon repository for the ISA Frontend monorepo. It provides **78 inline SVG icons** as string constants, organized by functional categories. All icons are exported as ready-to-use SVG markup strings designed to work seamlessly with the `@ng-icons/core` library in Angular components.

Each icon is:
- Exported as a TypeScript constant with SVG string content
- Named with a semantic prefix indicating its category
- Ready for use with `@ng-icons/core`'s `provideIcons()` function
- Styled with `fill="currentColor"` to inherit text color from parent elements

## 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** | 18 | 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`)

## Installation

Import icons directly from the library:

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

## Usage

### Using Individual Icons with @ng-icons/core

Import and register icons with `@ng-icons/core` (recommended):

```typescript
import { Component } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { isaActionClose, isaActionSearch } from '@isa/icons';

@Component({
  selector: 'app-search-dialog',
  standalone: true,
  imports: [NgIcon],
  providers: [
    provideIcons({
      isaActionClose,
      isaActionSearch
    })
  ],
  template: `
    <button>
      <ng-icon name="isaActionSearch" />
      Search
    </button>
    <button>
      <ng-icon name="isaActionClose" />
      Close
    </button>
  `
})
export class SearchDialogComponent {}
```

### Using Icon Groups

The library exports `ProductFormatIconGroup`, a pre-configured mapping of product format codes to their corresponding icons:

```typescript
import { Component, input } from '@angular/core';
import { NgIcon, provideIcons } from '@ng-icons/core';
import { ProductFormatIconGroup } from '@isa/icons';
import type { Product } from '@isa/oms/data-access';

@Component({
  selector: 'app-product-info',
  standalone: true,
  imports: [NgIcon],
  providers: [provideIcons({ ...ProductFormatIconGroup })],
  template: `
    <div class="product">
      <ng-icon [name]="product().format" />
      <span>{{ product().name }}</span>
    </div>
  `
})
export class ProductInfoComponent {
  product = input.required<Product>();
}
```

### Using All Icons via Namespace

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

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

### Direct SVG String Usage

Icons can be used directly as SVG strings (use with caution):

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

// Direct HTML insertion (use with [innerHTML] and DomSanitizer)
const checkIconSvg = isaActionCheck;
```

## Styling Icons

Icons use `fill="currentColor"` and inherit the text color from their parent element:

```html
<button class="text-primary">
  <ng-icon name="isaActionCheck" />
  <!-- Icon will be colored with text-primary color -->
</button>

<!-- Using Tailwind classes -->
<div class="text-isa-accent-500">
  <ng-icon name="isaActionSearch" />
</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

### Action Icons (18)
Icons for common user actions and interactions:
- `isaActionChevron` / `isaActionChevronDown`
- `isaActionChevronUp`, `isaActionChevronRight`, `isaActionChevronLeft`
- `isaActionPolygonDown`, `isaActionPolygonUp`
- `isaActionMinus`, `isaActionPlus`
- `isaActionClose`, `isaActionCheck`
- `isaActionFilter`, `isaActionSort`
- `isaActionRefresh`, `isaActionSearch`
- `isaActionPrinter`, `isaActionScanner`, `isaActionEdit`

### Navigation Icons (23)
Icons for navigation elements and menus:
- `isaNavigationSidemenu`, `isaNavigationMore`
- `isaNavigationFontsizeDecrease`, `isaNavigationFontsizeIncrease`
- `isaNavigationFontsizeChange1`, `isaNavigationFontsizeChange2`
- `isaNavigationDashboard`, `isaNavigationAbholfach`
- `isaNavigationArtikelsuche`, `isaNavigationBell`
- `isaNavigationCalender`, `isaNavigationCalenderEmpty`
- `isaNavigationCart`, `isaNavigationKunden`
- `isaNavigationLogout`, `isaNavigationMessage`
- `isaNavigationRemission`, `isaNavigationReturn`
- `isaNavigationSortiment`, `isaNavigationWarenausgabe`, `isaNavigationWareneingang`

### Product/Artikel Icons (8)
Icons representing different product formats:
- `isaArtikelCd`, `isaArtikelDigital`
- `isaArtikelEbook`, `isaArtikelGame`
- `isaArtikelKartoniert`, `isaArtikelSonstige`
- `isaArtikelTaschenbuch`, `isaArtikelTolino`

### Delivery Icons (7)
Icons for delivery and shipping methods:
- `isaDeliveryB`, `isaDeliveryDownload`
- `isaDeliveryRuecklage`, `isaDeliveryVersand`, `isaDeliveryWarenausgabe`

### Reviews Icons (13)
Small-sized icons for reviews and ratings:
- `isaReviewsCartSmall`, `isaReviewsCheckSmall`
- `isaReviewsChevronDownSmall`, `isaReviewsChevronLeftSmall`
- `isaReviewsChevronRightSmall`, `isaReviewsChevronSmall`
- `isaReviewsChevronUpSmall`, `isaReviewsCloseSmall`
- `isaReviewsMinusSmall`, `isaReviewsPlusSmall`
- `isaReviewsSearchSmall`, `isaReviewsStarFilledSmall`, `isaReviewsStarSmall`

### Other Icons (3)
Miscellaneous icons:
- `isaOtherGift`, `isaOtherHeart`, `isaOtherInfo`

### Store/Location Icons (2)
- `isaFiliale`, `isaFilialeLocation`

### Loading Icons (2)
- `isaLoading`, `isaLoadingSmall`

### Sorting Icons (2)
- `isaSortByDownMedium`, `isaSortByUpMedium`

## Architecture

**Library Structure:**
```
libs/icons/
├── src/
│   ├── lib/
│   │   ├── icons.ts           # All icon constants (78 icons)
│   │   └── icon-groups.ts     # Pre-configured icon groups
│   └── index.ts               # Public API exports
├── package.json
├── project.json
└── README.md
```

**Exports:**
- `IsaIcons` - Namespace export containing all icons
- `ProductFormatIconGroup` - Pre-configured product format icon mapping
- Individual icon constants (e.g., `isaActionClose`, `isaNavigationDashboard`)

## Adding New Icons

To add a new icon to the library:

1. **Choose a category** based on the icon's purpose:
   - `isaAction*` - User actions (close, open, edit, etc.)
   - `isaNavigation*` - Navigation elements
   - `isaArtikel*` - Product formats
   - `isaDelivery*` - Delivery methods
   - `isaReviews*` - Small icons for reviews
   - `isaOther*` - Miscellaneous icons
   - `isaFiliale*` - Store/location icons
   - `isaLoading*` - Loading indicators
   - `isaSortBy*` - Sorting controls

2. **Add the SVG constant** to `/libs/icons/src/lib/icons.ts`:
   ```typescript
   export const isaActionNewIcon =
     '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor">...</svg>';
   ```

3. **Ensure SVG attributes**:
   - Use `fill="currentColor"` for color inheritance
   - Standard dimensions: `24x24` (or `11x7` for small icons)
   - Include proper viewBox for scaling

4. **Export from library** - Icons are automatically exported via `export * from './lib/icons'` in `index.ts`

5. **Add to icon groups** (if applicable) in `/libs/icons/src/lib/icon-groups.ts`

6. **Update this README** with the new icon name in the appropriate category

## Best Practices

- Use semantic icon names that describe the action or element (e.g., `isaActionClose` not `isaActionX`)
- Register only the icons you need in component providers for optimal bundle size
- Use icon groups (`ProductFormatIconGroup`) when working with multiple related icons
- Let icons inherit color from parent text color using `currentColor`
- Prefer `@ng-icons/core` integration over direct SVG string usage for better Angular integration

## Dependencies

- **Runtime**: None (pure SVG string constants)
- **Usage**: `@ng-icons/core` (peer dependency for Angular integration)

## Testing

Run tests for this library:

```bash
nx test icons
```