@kern-ux-annex/kern-angular-kit/COMPONENTS.md

Angular-Umsetzung der KERN UX-Standard Komponenten

# KERN Angular Kit Components

This document provides comprehensive documentation for all components available in the `@kern-ux-annex/kern-angular-kit` library. The library follows the KERN Design System and provides Angular 20.1+ compatible components with InputSignal support and modern patterns.

**Current Version:** 0.1.2 (July 25, 2025)

## Table of Contents

- [Installation](#installation)
- [Getting Started](#getting-started)
- [Form Input Components](#form-input-components)
- [UI Components](#ui-components)
- [Services](#services)
- [Common Patterns](#common-patterns)
- [Examples](#examples)

## Installation

Install the library via npm:

```bash
npm install @kern-ux-annex/kern-angular-kit
```

## Getting Started

### Import the Module

You can import the entire module or individual components:

```typescript
// Option 1: Import the entire module (NgModule approach)
import { NgModule } from '@angular/core';
import { KernAngularKitModule } from '@kern-ux-annex/kern-angular-kit';

@NgModule({
  imports: [KernAngularKitModule]
  // ...
})
export class AppModule {}

// Option 2: Import individual components (Standalone approach - Recommended)
import { Component } from '@angular/core';
import {
  KernInputText,
  KernInputCheckbox,
  KernAlert
} from '@kern-ux-annex/kern-angular-kit';

@Component({
  selector: 'app-example',
  imports: [KernInputText, KernInputCheckbox, KernAlert],
  template: `...`
})
export class ExampleComponent {}
```

### Required CSS

Make sure to include the KERN UX CSS framework:

```bash
npm install @kern-ux/native
```

Add to your `angular.json` or main CSS file:

```css
@import '@kern-ux/native/dist/kern.min.css';
```

### Peer Dependencies

The library requires these Angular packages:

- `@angular/core`: ^20.1.0
- `@angular/common`: ^20.1.0
- `@angular/forms`: ^20.1.0

## Form Input Components

All form input components implement Angular's `ControlValueAccessor` interface and support Angular Forms (Template-driven and Reactive).

### Common Properties

All form input components share these common properties:

| Property    | Type             | Required | Default        | Description                          |
| ----------- | ---------------- | -------- | -------------- | ------------------------------------ |
| `inputId`   | `string`         | No       | Auto-generated | Custom ID for the input element      |
| `labelText` | `string`         | **Yes**  | -              | Label text for the input             |
| `optional`  | `boolean`        | No       | `false`        | Shows "Optional" indicator           |
| `required`  | `boolean`        | No       | `false`        | Marks field as required              |
| `readonly`  | `boolean`        | No       | `false`        | Makes input read-only                |
| `hintText`  | `string \| null` | No       | `null`         | Helper text below the input          |
| `errorText` | `string \| null` | No       | `null`         | Error message (triggers error state) |

### KernInputText

Text input component for general text input.

**Selector:** `kern-input-text`

**Additional Properties:**

| Property       | Type                             | Default | Description              |
| -------------- | -------------------------------- | ------- | ------------------------ |
| `inputmode`    | `'decimal' \| 'numeric' \| null` | `null`  | Virtual keyboard hint    |
| `maxlength`    | `number \| null`                 | `null`  | Maximum character length |
| `autocomplete` | `string \| null`                 | `null`  | Autocomplete attribute   |

**Example:**

```html
<kern-input-text
  labelText="Full Name"
  hintText="Enter your first and last name"
  [maxlength]="50"
  autocomplete="name"
  [(ngModel)]="fullName"
>
</kern-input-text>

<!-- With Reactive Forms -->
<kern-input-text
  labelText="Username"
  autocomplete="username"
  [formControl]="usernameControl"
>
</kern-input-text>
```

### KernInputEmail

Email input component with built-in email validation.

**Selector:** `kern-input-email`

**Additional Properties:**

| Property    | Type             | Default | Description              |
| ----------- | ---------------- | ------- | ------------------------ |
| `maxlength` | `number \| null` | `null`  | Maximum character length |

**Example:**

```html
<kern-input-email
  labelText="Email Address"
  autocomplete="email"
  [required]="true"
  [(ngModel)]="email"
>
</kern-input-email>
```

### KernInputPassword

Password input component with visibility toggle.

**Selector:** `kern-input-password`

**Additional Properties:**

| Property       | Type             | Default | Description            |
| -------------- | ---------------- | ------- | ---------------------- |
| `autocomplete` | `string \| null` | `null`  | Autocomplete attribute |

**Example:**

```html
<kern-input-password
  labelText="Password"
  autocomplete="current-password"
  [required]="true"
  [(ngModel)]="password"
>
</kern-input-password>
```

### KernInputTextarea

Multi-line text input component.

**Selector:** `kern-input-textarea`

**Additional Properties:**

| Property    | Type             | Default | Description              |
| ----------- | ---------------- | ------- | ------------------------ |
| `rows`      | `number \| null` | `null`  | Number of visible rows   |
| `maxlength` | `number \| null` | `null`  | Maximum character length |

**Example:**

```html
<kern-input-textarea
  labelText="Description"
  hintText="Provide a detailed description"
  [rows]="4"
  [maxlength]="500"
  [(ngModel)]="description"
>
</kern-input-textarea>
```

### KernInputCheckbox

Checkbox input component.

**Selector:** `kern-input-checkbox`

**Properties:**

| Property    | Type      | Required | Default        | Description                 |
| ----------- | --------- | -------- | -------------- | --------------------------- |
| `inputId`   | `string`  | No       | Auto-generated | Custom ID for the input     |
| `labelText` | `string`  | **Yes**  | -              | Label text for the checkbox |
| `error`     | `boolean` | No       | `false`        | Shows error state           |

**Example:**

```html
<kern-input-checkbox
  labelText="I agree to the terms and conditions"
  [(ngModel)]="agreedToTerms"
>
</kern-input-checkbox>

<kern-input-checkbox
  labelText="Subscribe to newsletter"
  [error]="newsletterError"
  [formControl]="newsletterControl"
>
</kern-input-checkbox>
```

### KernInputRadio

Radio button group component.

**Selector:** `kern-input-radio`

**Additional Properties:**

| Property              | Type                                    | Default      | Description       |
| --------------------- | --------------------------------------- | ------------ | ----------------- |
| `options`             | `Array<{value: string, label: string}>` | **Required** | Radio options     |
| `horizontalAlignment` | `boolean`                               | `false`      | Horizontal layout |

**Example:**

```html
<kern-input-radio
  labelText="Preferred Contact Method"
  [options]="contactOptions"
  [horizontalAlignment]="true"
  [(ngModel)]="contactMethod"
>
</kern-input-radio>
```

````typescript
```typescript
export class MyComponent {
  contactOptions = [
    { value: 'email', label: 'Email' },
    { value: 'phone', label: 'Phone' },
    { value: 'sms', label: 'SMS' }
  ];
  contactMethod = 'email';
}
````

### KernInputSelect

Select dropdown component.

**Selector:** `kern-input-select`

**Additional Properties:**

| Property  | Type                                    | Default      | Description    |
| --------- | --------------------------------------- | ------------ | -------------- |
| `options` | `Array<{value: string, label: string}>` | **Required** | Select options |

**Example:**

```html
<kern-input-select
  labelText="Country"
  [options]="countryOptions"
  hintText="Select your country of residence"
  [(ngModel)]="selectedCountry"
>
</kern-input-select>
```

````typescript
export class MyComponent {
  countryOptions = [
    { value: 'de', label: 'Germany' },
    { value: 'at', label: 'Austria' },
    { value: 'ch', label: 'Switzerland' }
  ];
  selectedCountry = 'de';
}

### KernInputDate

Date input component with separate fields for day, month, and year.

**Selector:** `kern-input-date`

**Additional Properties:**

| Property | Type             | Default | Description               |
| -------- | ---------------- | ------- | ------------------------- |
| `min`    | `string \| null` | `null`  | Minimum date (YYYY-MM-DD) |
| `max`    | `string \| null` | `null`  | Maximum date (YYYY-MM-DD) |

**Example:**

```html
<kern-input-date
  labelText="Birth Date"
  hintText="For example: 17 10 2015"
  [max]="maxDate"
  [(ngModel)]="birthDate"
>
</kern-input-date>
````

```typescript
export class MyComponent {
  maxDate = '2025-12-31';
  birthDate: string | null = null;
}
```

### KernInputTel

Telephone number input component with autocomplete support.

**Selector:** `kern-input-tel`

**Additional Properties:**

| Property    | Type             | Default | Description              |
| ----------- | ---------------- | ------- | ------------------------ |
| `maxlength` | `number \| null` | `null`  | Maximum character length |

**Example:**

```html
<kern-input-tel
  labelText="Phone Number"
  autocomplete="tel"
  hintText="Include country code if applicable"
  [(ngModel)]="phoneNumber"
>
</kern-input-tel>
```

### KernInputUrl

URL input component with validation.

**Selector:** `kern-input-url`

**Additional Properties:**

| Property    | Type             | Default | Description              |
| ----------- | ---------------- | ------- | ------------------------ |
| `maxlength` | `number \| null` | `null`  | Maximum character length |

**Example:**

```html
<kern-input-url
  labelText="Website"
  hintText="Enter your website URL (e.g., https://example.com)"
  [(ngModel)]="website"
>
</kern-input-url>
```

### KernInputFile

File upload input component.

**Selector:** `kern-input-file`

**Additional Properties:**

| Property   | Type             | Default | Description          |
| ---------- | ---------------- | ------- | -------------------- |
| `accept`   | `string \| null` | `null`  | Accepted file types  |
| `multiple` | `boolean`        | `false` | Allow multiple files |

**Example:**

```html
<kern-input-file
  labelText="Upload Documents"
  accept=".pdf,.doc,.docx"
  [multiple]="true"
  [(ngModel)]="uploadedFiles"
>
</kern-input-file>
```

## UI Components

### KernAlert

Alert/notification component for displaying messages.

**Selector:** `kern-alert`

**Properties:**

| Property | Type                                           | Default      | Description |
| -------- | ---------------------------------------------- | ------------ | ----------- |
| `title`  | `string`                                       | **Required** | Alert title |
| `type`   | `'info' \| 'success' \| 'warning' \| 'danger'` | `'info'`     | Alert type  |

**Example:**

```html
<kern-alert title="Success!" type="success">
  Your form has been submitted successfully.
</kern-alert>

<kern-alert title="Warning" type="warning">
  Please check your input before proceeding.
</kern-alert>
```

### KernAccordion

Collapsible content component.

**Selector:** `kern-accordion`

**Properties:**

| Property | Type      | Default      | Description          |
| -------- | --------- | ------------ | -------------------- |
| `title`  | `string`  | **Required** | Accordion title      |
| `open`   | `boolean` | `false`      | Initially open state |

**Example:**

```html
<kern-accordion title="Frequently Asked Questions" [open]="true">
  <p>This is the accordion content that can be collapsed or expanded.</p>
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
</kern-accordion>
```

### KernDialog

Modal dialog component.

**Selector:** `kern-dialog`

**Properties:**

| Property                | Type             | Default        | Description           |
| ----------------------- | ---------------- | -------------- | --------------------- |
| `dialogId`              | `string`         | Auto-generated | Custom dialog ID      |
| `title`                 | `string`         | **Required**   | Dialog title          |
| `btnCloseLabelText`     | `string`         | `'Schließen'`  | Close button text     |
| `btnPrimaryLabelText`   | `string \| null` | `null`         | Primary button text   |
| `btnSecondaryLabelText` | `string \| null` | `null`         | Secondary button text |

**Events:**

| Event                    | Type    | Description                           |
| ------------------------ | ------- | ------------------------------------- |
| `cancelEvent`            | `Event` | Emitted when dialog is cancelled      |
| `btnPrimaryClickEvent`   | `Event` | Emitted when primary button clicked   |
| `btnSecondaryClickEvent` | `Event` | Emitted when secondary button clicked |

**Example:**

```html
<kern-dialog
  title="Confirm Action"
  btnPrimaryLabelText="Confirm"
  btnSecondaryLabelText="Cancel"
  (btnPrimaryClickEvent)="onConfirm($event)"
  (btnSecondaryClickEvent)="onCancel($event)"
>
  <p>Are you sure you want to perform this action?</p>
</kern-dialog>
```

```typescript
export class MyComponent {
  onConfirm(event: Event) {
    console.log('User confirmed');
  }

  onCancel(event: Event) {
    console.log('User cancelled');
  }
}
```

### KernLoader

Loading spinner component.

**Selector:** `kern-loader`

**Properties:**

| Property | Type     | Default        | Description        |
| -------- | -------- | -------------- | ------------------ |
| `text`   | `string` | `'Loading...'` | Screen reader text |

**Example:**

```html
<kern-loader text="Loading data..."></kern-loader>

<!-- Show conditionally -->
@if (isLoading) {
<kern-loader text="Saving your changes..."></kern-loader>
}
```

## Services

### UniqueIdService

Service for generating unique IDs for form elements and accessibility.

**Methods:**

| Method          | Parameters        | Returns  | Description                              |
| --------------- | ----------------- | -------- | ---------------------------------------- |
| `getUniqueId()` | `prefix?: string` | `string` | Generates unique ID with optional prefix |

**Example:**

```typescript
import { UniqueIdService } from '@kern-ux-annex/kern-angular-kit';

export class MyComponent {
  constructor(private uniqueIdService: UniqueIdService) {
    const id = this.uniqueIdService.getUniqueId('my-component');
    console.log(id); // "my-component_0"

    const anotherId = this.uniqueIdService.getUniqueId('input');
    console.log(anotherId); // "input_1"
  }
}
```

## Common Patterns

### Form Validation

```typescript
import { Component } from '@angular/core';
import { FormBuilder, FormGroup, Validators } from '@angular/forms';
import { KernInputText, KernInputEmail } from '@kern-ux-annex/kern-angular-kit';

@Component({
  selector: 'app-user-form',
  imports: [ReactiveFormsModule, KernInputText, KernInputEmail],
  template: `
    <form [formGroup]="userForm" (ngSubmit)="onSubmit()">
      <kern-input-text
        labelText="Full Name"
        [required]="true"
        [errorText]="getErrorText('name')"
        formControlName="name"
      >
      </kern-input-text>

      <kern-input-email
        labelText="Email"
        [required]="true"
        [errorText]="getErrorText('email')"
        formControlName="email"
      >
      </kern-input-email>

      <button type="submit" [disabled]="userForm.invalid">Submit</button>
    </form>
  `
})
export class UserFormComponent {
  userForm: FormGroup;

  constructor(private fb: FormBuilder) {
    this.userForm = this.fb.group({
      name: ['', [Validators.required, Validators.minLength(2)]],
      email: ['', [Validators.required, Validators.email]]
    });
  }

  getErrorText(fieldName: string): string | null {
    const field = this.userForm.get(fieldName);
    if (field?.invalid && field?.touched) {
      if (field.errors?.['required']) return 'This field is required';
      if (field.errors?.['email']) return 'Please enter a valid email';
      if (field.errors?.['minlength']) return 'Minimum 2 characters required';
    }
    return null;
  }

  onSubmit() {
    if (this.userForm.valid) {
      console.log(this.userForm.value);
    }
  }
}
```

### Dynamic Forms

```typescript
@Component({
  template: `
    @for (field of formFields; track field.name) {
      @switch (field.type) {
        @case ('text') {
          <kern-input-text
            [labelText]="field.label"
            [required]="field.required"
            [(ngModel)]="formData[field.name]"
          >
          </kern-input-text>
        }
        @case ('email') {
          <kern-input-email
            [labelText]="field.label"
            [required]="field.required"
            [(ngModel)]="formData[field.name]"
          >
          </kern-input-email>
        }
        @case ('select') {
          <kern-input-select
            [labelText]="field.label"
            [options]="field.options"
            [required]="field.required"
            [(ngModel)]="formData[field.name]"
          >
          </kern-input-select>
        }
      }
    }
  `
})
export class DynamicFormComponent {
  formFields = [
    { name: 'firstName', type: 'text', label: 'First Name', required: true },
    { name: 'email', type: 'email', label: 'Email', required: true },
    {
      name: 'country',
      type: 'select',
      label: 'Country',
      required: false,
      options: [
        { value: 'de', label: 'Germany' },
        { value: 'at', label: 'Austria' }
      ]
    }
  ];

  formData: Record<string, any> = {};
}
```

## Examples

### Complete Registration Form

```typescript
import { Component } from '@angular/core';
import {
  KernInputText,
  KernInputEmail,
  KernInputPassword,
  KernInputCheckbox,
  KernInputSelect,
  KernAlert
} from '@kern-ux-annex/kern-angular-kit';

@Component({
  selector: 'app-registration',
  imports: [
    FormsModule,
    KernInputText,
    KernInputEmail,
    KernInputPassword,
    KernInputCheckbox,
    KernInputSelect,
    KernAlert
  ],
  template: `
    @if (showSuccess) {
      <kern-alert title="Registration Successful!" type="success">
        Welcome to our platform!
      </kern-alert>
    }

    <form (ngSubmit)="onSubmit()" #form="ngForm">
      <kern-input-text
        labelText="Full Name"
        [required]="true"
        [(ngModel)]="user.fullName"
        name="fullName"
      >
      </kern-input-text>

      <kern-input-email
        labelText="Email Address"
        [required]="true"
        [(ngModel)]="user.email"
        name="email"
      >
      </kern-input-email>

      <kern-input-password
        labelText="Password"
        [required]="true"
        [(ngModel)]="user.password"
        name="password"
      >
      </kern-input-password>

      <kern-input-select
        labelText="Country"
        [options]="countryOptions"
        [(ngModel)]="user.country"
        name="country"
      >
      </kern-input-select>

      <kern-input-checkbox
        labelText="I agree to the Terms of Service"
        [required]="true"
        [(ngModel)]="user.agreedToTerms"
        name="agreedToTerms"
      >
      </kern-input-checkbox>

      <button
        type="submit"
        [disabled]="form.invalid"
        class="kern-btn kern-btn--primary"
      >
        Register
      </button>
    </form>
  `
})
export class RegistrationComponent {
  showSuccess = false;

  user = {
    fullName: '',
    email: '',
    password: '',
    country: '',
    agreedToTerms: false
  };

  countryOptions = [
    { value: 'de', label: 'Germany' },
    { value: 'at', label: 'Austria' },
    { value: 'ch', label: 'Switzerland' }
  ];

  onSubmit() {
    console.log('User registration:', this.user);
    this.showSuccess = true;
  }
}
```

## Browser Support

- Chrome 90+
- Firefox 90+
- Safari 14+
- Edge 90+

## Accessibility

All components follow WCAG 2.1 AA guidelines and include:

- Proper ARIA attributes
- Keyboard navigation support
- Screen reader compatibility
- Focus management
- High contrast support
- Unique IDs for form associations

## Contributing

For contributing guidelines, please see the [CONTRIBUTING.md](./CONTRIBUTING.md) file in the repository.

## License

This library is licensed under the EUPL-1.2 license.