@kern-ux-annex/kern-angular-kit 0.3.4 → 0.3.7

package/COMPONENTS.md

@@ -0,0 +1,816 @@
+# 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.