📝 docs: update README documentation for 13 libraries

2025-12-28 22:42:11 +01:00 · 2025-11-25 14:13:44 +01:00
parent b93e39068c
commit bc1f6a42e6
14 changed files with 3591 additions and 2317 deletions
--- a/libs/icons/README.md
+++ b/libs/icons/README.md
@@ -1,8 +1,16 @@
-# icons
+# @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 **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.
+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

@@ -11,7 +19,7 @@ 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` |
+| **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` |
@@ -27,45 +35,77 @@ The library contains **9 distinct categories** of icons:
 - **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

-### Import Individual Icons
+### Using Individual Icons with @ng-icons/core
+
+Import and register icons with `@ng-icons/core` (recommended):

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

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

-### Import Icon Group
+### 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-display',
-  template: `<div [innerHTML]="getProductIcon(product.format)"></div>`,
+  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 ProductDisplayComponent {
-  getProductIcon(format: string): string {
-    return ProductFormatIconGroup[format] || ProductFormatIconGroup['ka'];
-  }
+export class ProductInfoComponent {
+  product = input.required<Product>();
 }
 ```

-### Import All Icons
+### Using All Icons via Namespace

 ```typescript
 import { IsaIcons } from '@isa/icons';
@@ -74,16 +114,31 @@ const searchIcon = IsaIcons.isaActionSearch;
 const cartIcon = IsaIcons.isaNavigationCart;
 ```

-## Color Customization
+### Direct SVG String Usage

-All icons use `currentColor`, allowing easy theming via CSS color inheritance:
+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
-<!-- Icon inherits text color from parent -->
-<div class="text-isa-accent-500" [innerHTML]="isaActionSearch"></div>
+<button class="text-primary">
+  <ng-icon name="isaActionCheck" />
+  <!-- Icon will be colored with text-primary color -->
+</button>

-<!-- Icon inherits from inline style -->
-<div style="color: #FF5733;" [innerHTML]="isaNavigationCart"></div>
+<!-- Using Tailwind classes -->
+<div class="text-isa-accent-500">
+  <ng-icon name="isaActionSearch" />
+</div>
 ```

 ## Icon Groups
@@ -110,76 +165,133 @@ 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 (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`

-### Action Icons (15)
- `isaActionChevron` / `isaActionChevronDown`, `isaActionChevronUp`, `isaActionChevronLeft`, `isaActionChevronRight`
- `isaActionPlus`, `isaActionMinus`, `isaActionSearch`, `isaActionEdit`, `isaActionDelete`
- `isaActionSave`, `isaActionCancel`, `isaActionRefresh`, `isaActionFilter`, `isaActionExport`
+### 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)
- `isaReviewsStarSmall`, `isaReviewsStarHalfSmall`, `isaReviewsStarEmptySmall`
- `isaReviewsChevronSmall`, `isaReviewsCheckSmall`, `isaReviewsCloseSmall`
- And 7 more small variants...
+Small-sized icons for reviews and ratings:
+- `isaReviewsCartSmall`, `isaReviewsCheckSmall`
+- `isaReviewsChevronDownSmall`, `isaReviewsChevronLeftSmall`
+- `isaReviewsChevronRightSmall`, `isaReviewsChevronSmall`
+- `isaReviewsChevronUpSmall`, `isaReviewsCloseSmall`
+- `isaReviewsMinusSmall`, `isaReviewsPlusSmall`
+- `isaReviewsSearchSmall`, `isaReviewsStarFilledSmall`, `isaReviewsStarSmall`

-### Product Format Icons (8)
- `isaArtikelTaschenbuch`, `isaArtikelKartoniert`, `isaArtikelCd`, `isaArtikelDvd`
- `isaArtikelEbook`, `isaArtikelGame`, `isaArtikelSonstige`, `isaArtikelVinyl`
+### Other Icons (3)
+Miscellaneous icons:
+- `isaOtherGift`, `isaOtherHeart`, `isaOtherInfo`

-### Delivery Method Icons (7)
- `isaDeliveryWarenausgabe`, `isaDeliveryVersand`, `isaDeliveryDownload`
- `isaDeliveryRuecklage1`, `isaDeliveryRuecklage2`, `isaDeliveryAbholfach`
- `isaDeliveryExpress`
+### Store/Location Icons (2)
+- `isaFiliale`, `isaFilialeLocation`

-## Size Variants
+### Loading Icons (2)
+- `isaLoading`, `isaLoadingSmall`

-The library provides size variants for specific use cases:
+### Sorting Icons (2)
+- `isaSortByDownMedium`, `isaSortByUpMedium`

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

-## 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>
+**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
 ```

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

-Run unit tests with Jest:
+## 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
-npx nx test icons
+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