npm package: @ferdifighter/ng-multiselect
Description: Eine flexible Angular Multiselect-Komponente mit Gruppierungsfunktion und anpassbarem Styling
Author: M. Wrase
Latest version: 1.2.5

# NgMultiselect

Eine Angular Multiselect-Komponente mit Gruppierungsfunktion. Die Komponente unterstützt:
- Mehrfachauswahl von Elementen
- Gruppierung von Optionen
- Suchfunktion
- Anpassbare Anzeige der Elemente
- Responsive Design
- Vorauswahl von Elementen
- Flexibles Styling durch CSS-Variablen
- Einfache Integration in bestehende Projekte

## Installation

```bash
npm install @ferdifighter/ng-multiselect
```

## Verwendung

```typescript
import { NgMultiselectComponent, MultiSelectOption, MultiSelectOptgroup } from '@ferdifighter/ng-multiselect';

@Component({
  // ...
  imports: [NgMultiselectComponent]
})
export class AppComponent {
  // Beispiel für gruppierte Optionen
  gruppen: MultiSelectOptgroup[] = [
    {
      label: 'Gruppe 1',
      options: [
        { value: '1', label: 'Option 1' },
        { value: '2', label: 'Option 2' }
      ]
    },
    {
      label: 'Gruppe 2',
      options: [
        { value: '3', label: 'Option 3' },
        { value: '4', label: 'Option 4' }
      ]
    }
  ];

  // Vorauswahl von Elementen
  vorauswahl: MultiSelectOption[] = [
    { value: '1', label: 'Option 1' }
  ];

  // Optionale Anzeige-Funktion
  anzeigeFunktion = (option: MultiSelectOption) => option.label;

  // Event-Handler für Auswahländerungen
  onSelection(auswahl: MultiSelectOption[]) {
    console.log('Ausgewählte Elemente:', auswahl);
  }
}
```

```html
<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [placeholder]="'Bitte wählen...'"
  [selectedTitle]="'Meine Auswahl'"
  [selected]="vorauswahl"
  [displayWith]="anzeigeFunktion"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>
```

## Responsive Design

Die Komponente unterstützt verschiedene responsive Modi:

### Responsive Modus
```html
<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [responsive]="true"
  [maxHeight]="'400px'"
  [minHeight]="'200px'"
  [containerHeight]="'100%'"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>
```

### Automatische Höhe
```html
<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [autoHeight]="true"
  [maxHeight]="'none'"
  [containerHeight]="'auto'"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>
```

### Feste Höhe mit Scrollbalken
```html
<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [maxHeight]="'300px'"
  [minHeight]="'150px'"
  [containerHeight]="'400px'"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>
```

## Styling

Die Komponente verwendet CSS-Variablen für einfache Anpassung an Ihr Design-System:

```css
lib-ng-multiselect {
  /* Farben */
  --ms-border-color: #your-border-color;
  --ms-background-color: #your-background;
  --ms-header-background: #your-header-background;
  --ms-hover-background: #your-hover-color;
  --ms-selected-background: #your-selected-color;
  --ms-optgroup-background: #your-optgroup-background;
  --ms-optgroup-hover: #your-optgroup-hover;

  /* Typografie */
  --ms-font-family: your-font-family;
  --ms-font-size: your-font-size;

  /* Layout */
  --ms-border-radius: your-border-radius;
  --ms-padding: your-padding;
  --ms-gap: your-gap;
  --ms-list-max-height: your-max-height;
  --ms-disabled-opacity: your-disabled-opacity;
}
```

### Standardwerte

```css
:host {
  --ms-border-color: #ccc;
  --ms-border-radius: 4px;
  --ms-background-color: #fff;
  --ms-header-background: #f5f5f5;
  --ms-hover-background: #f0f0f0;
  --ms-selected-background: #e3f2fd;
  --ms-disabled-opacity: 0.5;
  --ms-font-family: inherit;
  --ms-font-size: inherit;
  --ms-padding: 0.5rem;
  --ms-gap: 1rem;
  --ms-list-max-height: 300px;
  --ms-optgroup-background: #f8f9fa;
  --ms-optgroup-hover: #e9ecef;
}
```

## Optionen

### Inputs

| Option              | Typ                       | Standardwert           | Beschreibung                                  |
|---------------------|--------------------------|------------------------|------------------------------------------------|
| options             | MultiSelectOption[]       | []                     | Flache Liste von Optionen                      |
| optgroups           | MultiSelectOptgroup[]     | []                     | Gruppierte Optionen                            |
| useOptgroups        | boolean                  | false                  | true = Gruppenmodus, false = flache Liste      |
| placeholder         | string                   | 'Suchen...'            | Platzhaltertext für die Suche                  |
| selectedTitle       | string                   | 'Ausgewählte Elemente' | Titel für den Bereich der ausgewählten Elemente |
| selected            | MultiSelectOption[]       | []                     | Vorauswahl von Elementen                       |
| displayWith         | Funktion                 | undefined              | Optionale Anzeige-Funktion für Labels          |
| optgroupStyle       | MultiSelectStyles        | {...}                  | Styling für Optgroup-Labels                    |
| optionStyle         | MultiSelectStyles        | {...}                  | Styling für Optionen                           |
| selectedOptionStyle | MultiSelectStyles        | {...}                  | Styling für ausgewählte Optionen               |
| maxHeight           | string                   | '300px'                | Maximale Höhe der Listen                       |
| minHeight           | string                   | '100px'                | Minimale Höhe der Listen                       |
| responsive          | boolean                  | false                  | Aktiviert responsive Modus                      |
| autoHeight          | boolean                  | false                  | Automatische Höhenanpassung                     |
| containerHeight     | string                   | 'auto'                 | Höhe des Hauptcontainers                       |

### Outputs

| Event           | Typ                       | Beschreibung                                  |
|-----------------|--------------------------|------------------------------------------------|
| selectionChange | MultiSelectOption[]       | Wird bei jeder Auswahländerung ausgelöst       |

### Interfaces

```typescript
interface MultiSelectOption {
  value: string | number;
  label: string;
  disabled?: boolean;
  groupLabel?: string;
}

interface MultiSelectOptgroup {
  label: string;
  options: MultiSelectOption[];
  disabled?: boolean;
}

interface MultiSelectStyles {
  [key: string]: string;
}
```

### Beispiel: Styling anpassen

```typescript
@Component({
  // ...
})
export class AppComponent {
  optgroupStyle = {
    'padding': '0.4rem 0.7rem',
    'fontWeight': 'bold',
    'background': '#f8f9fa',
    'borderBottom': '1px solid #eee',
    'fontSize': '1rem',
    'margin': '0'
  };

  optionStyle = {
    'paddingLeft': '1.5rem',
    'paddingTop': '0.2rem',
    'paddingBottom': '0.2rem',
    'margin': '0',
    'background': '#fff',
    'fontWeight': 'normal',
    'borderBottom': 'none'
  };

  selectedOptionStyle = {
    'paddingLeft': '1.5rem',
    'paddingTop': '0.2rem',
    'paddingBottom': '0.2rem',
    'margin': '0',
    'background': '#fff',
    'fontWeight': 'normal',
    'borderBottom': 'none'
  };
}
```

```html
<lib-ng-multiselect
  [optgroups]="gruppen"
  [useOptgroups]="true"
  [optgroupStyle]="optgroupStyle"
  [optionStyle]="optionStyle"
  [selectedOptionStyle]="selectedOptionStyle"
  (selectionChange)="onSelection($event)">
</lib-ng-multiselect>
```

## Beispiel: Statische Daten

```typescript
// Komponente
import { MultiSelectOptgroup, MultiSelectOption } from 'ng-multiselect';

export class ExampleComponent {
  gruppen: MultiSelectOptgroup[] = [
    {
      label: 'Gruppe A',
      options: [
        { value: 1, label: 'Option 1' },
        { value: 2, label: 'Option 2' }
      ]
    },
    {
      label: 'Gruppe B',
      options: [
        { value: 3, label: 'Option 3' }
      ]
    }
  ];
  anzeigeFunktion = (option: MultiSelectOption) => option.label;
  onSelection(auswahl: MultiSelectOption[]) {
    console.log(auswahl);
  }
}
```

## Beispiel: Asynchrone Daten (z.B. REST, TypeORM)

```typescript
import { NgMultiselectService, MultiSelectOption } from 'ng-multiselect';

export class ExampleComponent {
  optionen: MultiSelectOption[] = [];
  constructor(private msService: NgMultiselectService) {}

  ngOnInit() {
    this.msService.loadFromDatabase({
      type: 'mysql',
      host: 'localhost',
      database: 'test',
      table: 'users',
      valueField: 'id',
      labelField: 'name'
    }).subscribe(data => this.optionen = data);
  }
}
```

## Integration in bestehende Projekte

Die Komponente ist so konzipiert, dass sie sich nahtlos in bestehende Projekte integrieren lässt:

1. **Styling-Integration**:
   - Verwendet CSS-Variablen für einfache Anpassung
   - Erbt Schriftart und -größe vom übergeordneten Element
   - BEM-Methodologie für Styling-Isolation

2. **Responsive Design**:
   - Flexibles Layout
   - Anpassbare Höhen und Breiten
   - Mobile-freundlich

3. **Barrierefreiheit**:
   - Semantische HTML-Struktur
   - Tastatur-Navigation
   - ARIA-Attribute

## Weitere Hinweise
- Die Komponente ist für die Nutzung in eigenen Projekten und als npm-Paket vorbereitet
- Für Backend-Anbindung (z.B. TypeORM/NestJS) siehe Beispiel im `example`-Ordner
- Die Komponente verwendet BEM-Methodologie für bessere Styling-Isolation
- Alle Styling-Eigenschaften können über CSS-Variablen angepasst werden

## CHANGELOG

### [1.2.4] - 2025-09-18
#### Behoben
- **Daten korrigiert**: Alle Changelog-Daten auf korrekte Daten aktualisiert (2025-09-18)
- **Konsistenz**: Einheitliche Datumsformatierung im gesamten Changelog

### [1.2.3] - 2025-09-18
#### Behoben
- **README.md**: Changelog in README.md aktualisiert für npmjs-Anzeige
- **Dokumentation**: Neue responsive Input-Properties zur Dokumentation hinzugefügt
- **Beispiele**: Responsive Design-Beispiele zur README.md hinzugefügt

### [1.2.2] - 2025-09-18
#### Behoben
- **Changelog**: Korrektur des Datums für Version 1.2.1

### [1.2.1] - 2025-09-18
#### Hinzugefügt
- **Responsive Design**: Neue Input-Properties für responsive Verhalten
  - `responsive`: Aktiviert responsive Modus (boolean)
  - `autoHeight`: Automatische Höhenanpassung (boolean)
  - `maxHeight`: Maximale Höhe der Listen (string, Standard: '300px')
  - `minHeight`: Minimale Höhe der Listen (string, Standard: '100px')
  - `containerHeight`: Höhe des Hauptcontainers (string, Standard: 'auto')
- **Verbesserte Scrollbalken**: Dünne, ansprechende Scrollbalken mit Hover-Effekten
- **Sticky Optgroup-Labels**: Gruppen-Überschriften bleiben beim Scrollen sichtbar
- **Responsive Breakpoints**: Automatische Anpassung für mobile Geräte
  - Tablet: ≤ 768px (vertikales Layout)
  - Mobile: ≤ 480px (optimierte Höhen)
- **Dynamische CSS-Variablen**: Automatische Anpassung der Styling-Parameter
- **Flexible Container**: Container passen sich automatisch an umliegende Elemente an

#### Verbessert
- **CSS-Architektur**: Erweiterte CSS-Variablen für bessere Anpassbarkeit
- **Mobile Experience**: Optimiertes Layout für kleinere Bildschirme
- **Scroll-Verhalten**: Verbesserte Benutzerfreundlichkeit bei vielen Einträgen
- **Performance**: Effizientere CSS-Klassen-Verwaltung

#### Technische Details
- Neue CSS-Klassen: `ng-multiselect--responsive`, `ng-multiselect--auto-height`, `ng-multiselect--fixed-height`
- Erweiterte CSS-Variablen: `--ms-list-min-height`, `--ms-container-height`
- Responsive Media Queries für verschiedene Bildschirmgrößen
- Verbesserte Scrollbar-Styling für Webkit und Firefox

### [1.2.0] - 2025-09-18
#### Hinzugefügt
- Neue Styling-Inputs für feinere Anpassung:
  - `optgroupStyle` für Optgroup-Labels
  - `optionStyle` für Optionen
  - `selectedOptionStyle` für ausgewählte Optionen
- Verbesserte Styling-Dokumentation
- Beispiel für die Verwendung der neuen Styling-Optionen

### [1.1.1] - 2025-09-18
#### Geändert
- README.md um CHANGELOG erweitert
- Verbesserte Dokumentation der Versionshistorie

### [1.1.0] - 2025-09-18
#### Hinzugefügt
- Flexibles Styling-System mit CSS-Variablen
- BEM-Methodologie für bessere Styling-Isolation
- Verbesserte Integration in bestehende Projekte
- Anpassbare Typografie und Layout-Eigenschaften
- Detaillierte Styling-Dokumentation

### [1.0.4] - 2025-09-17
#### Geändert
- Verbesserte Fehlerbehandlung
- Optimierte Performance bei großen Datenmengen

### [1.0.3] - 2025-09-16
#### Hinzugefügt
- Unterstützung für TypeORM/NestJS
- Verbesserte Dokumentation

### [1.0.2] - 2025-09-15
#### Geändert
- Bugfixes für Gruppierungsfunktion
- Verbesserte Suchfunktion

### [1.0.1] - 2025-09-14
#### Hinzugefügt
- Gruppierungsfunktion
- Suchfunktion
- Vorauswahl von Elementen

### [1.0.0] - 2025-09-13
#### Hinzugefügt
- Erste Version der Multiselect-Komponente
- Basis-Funktionalität für Mehrfachauswahl
- Responsive Design