ps-helix 0.1.0 → 2.0.1

package/README.md

@@ -1,50 +1,162 @@
-# ps-helix
+# Helix Design System
+
+A comprehensive Angular component library built with Angular 20+ featuring modern design patterns, accessibility-first development, and optimal developer experience.
+
+[![npm version](https://img.shields.io/badge/npm-2.0.0-blue.svg)](https://www.npmjs.com/package/ps-helix)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Angular](https://img.shields.io/badge/Angular-20.0.0-red.svg)](https://angular.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.0-blue.svg)](https://www.typescriptlang.org/)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+  - [Global Styles](#global-styles)
+  - [Phosphor Icons Setup](#phosphor-icons-setup)
+  - [Theme Service](#theme-service)
+  - [Translation Service](#translation-service)
+  - [Scroll Service](#scroll-service)
+- [Core Concepts](#core-concepts)
+  - [Standalone Components](#standalone-components)
+  - [Signal-Based Reactivity](#signal-based-reactivity)
+  - [Type Safety](#type-safety)
+  - [Dependency Injection](#dependency-injection)
+- [Available Components](#available-components)
+- [Service APIs](#service-apis)
+  - [ThemeService](#themeservice)
+  - [ToastService](#toastservice)
+  - [ScrollService](#scrollservice)
+  - [TranslationService](#translationservice)
+- [Exported Types](#exported-types)
+- [Theming](#theming)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+- [Browser Support](#browser-support)
+- [Development Scripts](#development-scripts)
+- [Contributing](#contributing)
+- [License](#license)
+- [Resources](#resources)
+
+## Overview
+
+Helix is a production-ready design system that provides:
+
+- **28 Standalone Components** - All components are standalone, no NgModules required
+- **Signal-Based Reactivity** - Built with Angular 20 signals for optimal performance
+- **Accessibility First** - WCAG 2.1 AA compliant out of the box
+- **TypeScript Strict Mode** - Full type safety and IntelliSense support
+- **Complete Type Exports** - All component types and enums exported for type-safe development
+- **Customizable Theming** - Light/dark modes with brand color customization
+- **Phosphor Icons** - 6000+ icons with multiple weight variants
+- **i18n Support** - Built-in internationalization with ngx-translate
+- **Responsive Design** - Mobile-first approach with comprehensive breakpoint system
+- **Modern Architecture** - Built with Angular 20 standalone components and signals
+
+## Prerequisites
+
+Before installing Helix, ensure your development environment meets these requirements:
+
+- **Node.js**: 18.x or higher
+- **npm**: 9.x or higher
+- **Angular**: 20.0.0 or higher
+- **Angular CLI**: 20.0.0 or higher
+- **TypeScript**: 5.8.0 or higher
+
+### Required Peer Dependencies
 
-Helix Design System - A comprehensive Angular component library built with Angular 19+ and modern best practices.
+```json
+{
+  "@angular/common": "^20.0.0",
+  "@angular/core": "^20.0.0",
+  "@angular/forms": "^20.0.0",
+  "@ngx-translate/core": "^15.0.0",
+  "rxjs": "^7.8.0"
+}
+```
+
+### Included Dependencies
+
+The following dependencies are bundled with ps-helix:
+
+- **@phosphor-icons/web**: 2.0.3 - Icon library
+- **date-fns**: ^3.3.1 - Date utility functions
+- **tslib**: ^2.6.0 - TypeScript runtime library
 
 ## Installation
 
+Install the package via npm:
+
 ```bash
 npm install ps-helix
 ```
 
-## Peer Dependencies
+All peer dependencies should be automatically installed. If not, install them manually:
+
+```bash
+npm install @angular/common@^20.0.0 @angular/core@^20.0.0 @angular/forms@^20.0.0 @ngx-translate/core@^15.0.0 rxjs@^7.8.0
+```
 
-This library requires the following peer dependencies:
+### Verify Installation
+
+After installation, verify that ps-helix is in your `package.json`:
 
 ```json
 {
-  "@angular/common": "^19.0.0",
-  "@angular/core": "^19.0.0",
-  "@angular/forms": "^19.0.0",
-  "@ngx-translate/core": "^15.0.0",
-  "rxjs": "^7.8.0"
+  "dependencies": {
+    "ps-helix": "^2.0.0"
+  }
 }
 ```
 
-## Getting Started
+## Quick Start
 
-### 1. Import Global Styles
+### Step 1: Import Global Styles
 
-In your `styles.css` or `styles.scss` file, import the Helix Design System styles:
+In your main `styles.css` file, import the Helix stylesheet:
 
 ```css
 @import 'ps-helix/styles.css';
 ```
 
-This will include:
-- CSS Reset
-- Theme variables (light and dark modes)
-- Typography utilities
-- Spacing system
-- Layout utilities
+This single import includes:
+- CSS Reset (normalize styles across browsers)
+- Design Tokens (spacing, typography, colors, etc.)
+- Light and Dark theme variables
+- Utility classes (spacing, typography, layout, etc.)
+- Responsive breakpoints and grid system
 - Animation utilities
-- Focus styles
-- Responsive breakpoints
+- Focus management styles
+
+### Step 2: Configure Phosphor Icons
+
+Add Phosphor Icons CDN links to your `src/index.html` in the `<head>` section:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Your App</title>
+
+  <!-- Phosphor Icons CDN -->
+  <link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.0.3/src/regular/style.css">
+  <link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.0.3/src/fill/style.css">
+  <link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.0.3/src/bold/style.css">
+  <link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.0.3/src/light/style.css">
+</head>
+<body>
+  <app-root></app-root>
+</body>
+</html>
+```
 
-### 2. Import Components
+### Step 3: Import and Use Components
 
-All components are standalone and can be imported directly:
+All components are standalone. Import them directly where needed:
 
 ```typescript
 import { Component } from '@angular/core';
@@ -52,24 +164,119 @@ import { PshButtonComponent } from 'ps-helix';
 
 @Component({
   selector: 'app-root',
-  standalone: true,
   imports: [PshButtonComponent],
   template: `
     <psh-button
-      [variant]="'primary'"
-      [size]="'medium'">
-      Click me
+      variant="primary"
+      size="medium"
+      (clicked)="handleClick()">
+      Click Me
     </psh-button>
   `
 })
-export class AppComponent {}
+export class AppComponent {
+  handleClick() {
+    console.log('Button clicked!');
+  }
+}
+```
+
+### Step 4: Initialize Theme Service (Optional)
+
+If you want to use theme switching, inject the ThemeService:
+
+```typescript
+import { Component, inject, OnInit } from '@angular/core';
+import { ThemeService } from 'ps-helix';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <button (click)="themeService.toggleTheme()">
+      Toggle Theme ({{ themeService.themeName() }})
+    </button>
+  `
+})
+export class AppComponent implements OnInit {
+  themeService = inject(ThemeService);
+
+  ngOnInit() {
+    // Theme is initialized automatically
+    console.log('Current theme:', this.themeService.themeName());
+  }
+}
+```
+
+### Step 5: Verify Everything Works
+
+Create a simple test component to ensure the library is working:
+
+```typescript
+import { Component } from '@angular/core';
+import { PshButtonComponent, PshCardComponent, PshAlertComponent } from 'ps-helix';
+
+@Component({
+  selector: 'app-test',
+  imports: [PshButtonComponent, PshCardComponent, PshAlertComponent],
+  template: `
+    <psh-card>
+      <h2>Helix Design System</h2>
+      <psh-alert type="success" message="Installation successful!" />
+      <psh-button variant="primary">Test Button</psh-button>
+    </psh-card>
+  `
+})
+export class TestComponent {}
+```
+
+## Configuration
+
+### Global Styles
+
+The design system provides a comprehensive set of CSS custom properties (CSS variables) that you can use in your own styles:
+
+```css
+/* Using design tokens in your custom styles */
+.my-custom-component {
+  padding: var(--spacing-md);
+  margin-bottom: var(--spacing-lg);
+  background: var(--surface-card);
+  color: var(--text-color);
+  border-radius: var(--border-radius);
+  box-shadow: var(--shadow-md);
+}
 ```
 
-### 3. Configure Services (Optional)
+### Phosphor Icons Setup
+
+After adding the CDN links, use icons in your templates:
+
+```html
+<!-- Regular weight (default) -->
+<i class="ph ph-heart"></i>
+
+<!-- Fill weight -->
+<i class="ph-fill ph-heart"></i>
+
+<!-- Bold weight -->
+<i class="ph-bold ph-heart"></i>
+
+<!-- Light weight -->
+<i class="ph-light ph-heart"></i>
+
+<!-- With accessibility label for icon-only buttons -->
+<button aria-label="Like this item">
+  <i class="ph ph-heart" aria-hidden="true"></i>
+</button>
+```
 
-#### Theme Service
+Browse all 6000+ icons at: [https://phosphoricons.com/](https://phosphoricons.com/)
 
-The ThemeService allows you to manage light/dark theme switching:
+### Theme Service
+
+The `ThemeService` manages light/dark theme switching and custom brand colors.
+
+#### Basic Theme Switching
 
 ```typescript
 import { Component, inject } from '@angular/core';
@@ -77,7 +284,6 @@ import { ThemeService } from 'ps-helix';
 
 @Component({
   selector: 'app-root',
-  standalone: true,
   template: `
     <button (click)="toggleTheme()">
       Current theme: {{ themeService.themeName() }}
@@ -93,194 +299,848 @@ export class AppComponent {
 }
 ```
 
-#### Translation Service
+For complete theming documentation including custom brand colors, see [THEME.md](./THEME.md).
+
+### Translation Service
 
-Configure internationalization with the TranslationService:
+Configure internationalization with ngx-translate:
 
 ```typescript
-import { ApplicationConfig } from '@angular/core';
-import { TranslationService } from 'ps-helix';
+// src/main.ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideHttpClient } from '@angular/common/http';
+import { TranslateModule, TranslateLoader, TranslateService } from '@ngx-translate/core';
+import { TranslateHttpLoader } from '@ngx-translate/http-loader';
+import { HttpClient } from '@angular/common/http';
+import { AppComponent } from './app/app.component';
+
+export function HttpLoaderFactory(http: HttpClient) {
+  return new TranslateHttpLoader(http, './assets/i18n/', '.json');
+}
 
-export const appConfig: ApplicationConfig = {
+bootstrapApplication(AppComponent, {
   providers: [
-    TranslationService
+    provideHttpClient(),
+    ...TranslateModule.forRoot({
+      defaultLanguage: 'en',
+      loader: {
+        provide: TranslateLoader,
+        useFactory: HttpLoaderFactory,
+        deps: [HttpClient]
+      }
+    }).providers || []
   ]
-};
+}).then(ref => {
+  const translateService = ref.injector.get(TranslateService);
+  translateService.use('en');
+});
 ```
 
-## Available Components
-
-### Form Components
-- `PshButtonComponent` - Versatile button with multiple variants and states
-- `PshInputComponent` - Text input with validation support
-- `PshCheckboxComponent` - Checkbox with customizable states
-- `PshRadioComponent` - Radio button for single selection
-- `PshSelectComponent` - Dropdown select with search
-- `PshSwitchComponent` - Toggle switch component
-
-### Layout Components
-- `PshCardComponent` - Content container with variants
-- `PshModalComponent` - Modal dialog overlay
-- `PshSidebarComponent` - Collapsible sidebar navigation
-- `PshCollapseComponent` - Expandable content section
-- `PshTabsComponent` - Tabbed content organization
-- `PshTabBarComponent` - Bottom tab bar navigation
-
-### Feedback Components
-- `PshAlertComponent` - Alert messages with severity levels
-- `PshToastComponent` - Toast notifications
-- `PshSpinloaderComponent` - Loading spinner
-- `PshProgressbarComponent` - Progress indicator
-- `PshTooltipComponent` - Contextual tooltips
-
-### Data Display Components
-- `PshTableComponent` - Data table with sorting and pagination
-- `PshBadgeComponent` - Status badges and indicators
-- `PshTagComponent` - Removable tags
-- `PshAvatarComponent` - User avatar with fallback
-- `PshPieChartComponent` - Pie chart visualization
-
-### Navigation Components
-- `PshMenuComponent` - Dropdown menu
-- `PshPaginationComponent` - Pagination controls
-- `PshStepperComponent` - Step-by-step wizard
-- `PshDropdownComponent` - Dropdown trigger and content
-
-## Component Usage Examples
-
-### Button
+#### Using TranslationService in Components
 
 ```typescript
-import { PshButtonComponent } from 'ps-helix';
+import { Component, inject } from '@angular/core';
+import { TranslationService } from 'ps-helix';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <select (change)="changeLanguage($event)">
+      <option value="en">English</option>
+      <option value="fr">Français</option>
+      <option value="es">Español</option>
+    </select>
+  `
+})
+export class ExampleComponent {
+  private translationService = inject(TranslationService);
 
-<psh-button
-  [variant]="'primary'"
-  [size]="'medium'"
-  [appearance]="'filled'"
-  [disabled]="false"
-  [loading]="false"
-  (clicked)="handleClick($event)">
-  Submit
-</psh-button>
+  changeLanguage(event: Event) {
+    const lang = (event.target as HTMLSelectElement).value;
+    this.translationService.setLanguage(lang);
+  }
+}
 ```
 
-### Input
+### Scroll Service
+
+The `ScrollService` provides utilities for scroll management:
 
 ```typescript
-import { PshInputComponent } from 'ps-helix';
-import { FormControl } from '@angular/forms';
+import { Component, inject } from '@angular/core';
+import { ScrollService } from 'ps-helix';
 
-export class MyComponent {
-  emailControl = new FormControl('');
+@Component({
+  selector: 'app-example',
+  template: `
+    <button (click)="scrollToTop()">Back to Top</button>
+    <button (click)="scrollToElement('#section-2')">Go to Section 2</button>
+  `
+})
+export class ExampleComponent {
+  private scrollService = inject(ScrollService);
+
+  scrollToTop() {
+    this.scrollService.scrollToTop();
+  }
+
+  scrollToElement(selector: string) {
+    this.scrollService.scrollToElement(selector);
+  }
 }
+```
 
-<psh-input
-  [label]="'Email'"
-  [placeholder]="'Enter your email'"
-  [type]="'email'"
-  [formControl]="emailControl"
-  [required]="true">
-</psh-input>
+## Core Concepts
+
+### Standalone Components
+
+All Helix components are standalone (no NgModules required):
+
+```typescript
+import { Component } from '@angular/core';
+import {
+  PshButtonComponent,
+  PshInputComponent,
+  PshCardComponent
+} from 'ps-helix';
+
+@Component({
+  selector: 'app-form',
+  imports: [
+    PshButtonComponent,
+    PshInputComponent,
+    PshCardComponent
+  ],
+  template: `
+    <psh-card>
+      <psh-input label="Email" />
+      <psh-button variant="primary">Submit</psh-button>
+    </psh-card>
+  `
+})
+export class FormComponent {}
 ```
 
-### Modal
+### Signal-Based Reactivity
+
+Components use Angular signals for optimal change detection:
 
 ```typescript
+import { Component, signal } from '@angular/core';
 import { PshModalComponent } from 'ps-helix';
-import { signal } from '@angular/core';
 
-export class MyComponent {
+@Component({
+  selector: 'app-example',
+  imports: [PshModalComponent],
+  template: `
+    <button (click)="isOpen.set(true)">Open Modal</button>
+
+    <psh-modal [(open)]="isOpen" title="Confirmation">
+      <p>Are you sure?</p>
+    </psh-modal>
+  `
+})
+export class ExampleComponent {
   isOpen = signal(false);
 }
+```
+
+### Type Safety
+
+All components export TypeScript types for type-safe development:
 
-<psh-modal
-  [(open)]="isOpen"
-  [title]="'Confirm Action'"
-  [size]="'medium'">
-  <p>Are you sure you want to proceed?</p>
-  <div class="actions">
-    <psh-button (clicked)="isOpen.set(false)">Cancel</psh-button>
-    <psh-button [variant]="'primary'" (clicked)="confirm()">Confirm</psh-button>
-  </div>
-</psh-modal>
+```typescript
+import { Component } from '@angular/core';
+import { PshButtonComponent, ButtonVariant, ButtonSize } from 'ps-helix';
+
+@Component({
+  selector: 'app-example',
+  imports: [PshButtonComponent],
+  template: `
+    <psh-button [variant]="variant" [size]="size">
+      {{ buttonText }}
+    </psh-button>
+  `
+})
+export class ExampleComponent {
+  variant: ButtonVariant = 'primary';  // Type-safe
+  size: ButtonSize = 'medium';         // Type-safe
+  buttonText = 'Click Me';
+}
 ```
 
-### Toast Notifications
+### Dependency Injection
+
+Use modern `inject()` function instead of constructor injection:
 
 ```typescript
 import { Component, inject } from '@angular/core';
+import { ThemeService, ToastService } from 'ps-helix';
+
+@Component({
+  selector: 'app-example',
+  template: `<button (click)="showToast()">Show Toast</button>`
+})
+export class ExampleComponent {
+  // Modern injection syntax
+  private themeService = inject(ThemeService);
+  private toastService = inject(ToastService);
+
+  showToast() {
+    this.toastService.success('Hello from Helix!');
+  }
+}
+```
+
+## Available Components
+
+Helix provides **28 production-ready components** organized by category:
+
+### Form Components (6)
+
+- **PshButtonComponent** - Versatile button with multiple variants, sizes, and states
+- **PshInputComponent** - Text input with validation, error messages, and form control integration
+- **PshCheckboxComponent** - Checkbox with customizable states and labels
+- **PshRadioComponent** - Radio button for single selection from a group
+- **PshSelectComponent** - Dropdown select with search, filtering, and custom rendering
+- **PshSwitchComponent** - Toggle switch with on/off states
+
+### Layout Components (6)
+
+- **PshCardComponent** - Flexible content container with header, body, and footer sections
+- **PshModalComponent** - Modal dialog overlay with backdrop and keyboard navigation
+- **PshSidebarComponent** - Collapsible sidebar navigation with responsive behavior
+- **PshCollapseComponent** - Expandable/collapsible content section with animation
+- **PshTabsComponent** + **PshTabComponent** - Tabbed content organization with keyboard navigation
+- **PshTabBarComponent** - Bottom tab bar navigation for mobile-first applications
+
+### Feedback Components (5)
+
+- **PshAlertComponent** - Alert messages with severity levels (success, info, warning, error)
+- **PshToastComponent** + **ToastService** - Toast notification system with queue management
+- **PshSpinloaderComponent** - Loading spinner with various sizes
+- **PshProgressbarComponent** - Progress indicator with percentage display
+- **PshTooltipComponent** - Contextual tooltips with multiple positions
+
+### Data Display Components (7)
+
+- **PshTableComponent** - Data table with sorting, pagination, and custom rendering
+- **PshBadgeComponent** - Status badges and indicators with various colors
+- **PshTagComponent** - Removable tags for labels and filters
+- **PshAvatarComponent** - User avatar with image, initials, or icon fallback
+- **PshStatCardComponent** - Statistical card for dashboards
+- **PshInfoCardComponent** - Information card with icon and content
+- **PshHorizontalCardComponent** - Horizontal layout card component
+
+### Navigation Components (4)
+
+- **PshMenuComponent** - Dropdown menu with nested items
+- **PshPaginationComponent** - Pagination controls with page numbers
+- **PshStepperComponent** + **PshStepComponent** - Step-by-step wizard navigation with validation
+- **PshDropdownComponent** - Dropdown trigger and content container
+
+## Service APIs
+
+### ThemeService
+
+Manage application themes and custom brand colors.
+
+**Methods:**
+- `setDarkTheme(isDark: boolean)` - Set theme mode
+- `toggleTheme()` - Toggle between light and dark
+- `updateTheme(name: 'light' | 'dark')` - Update theme by name
+- `applyInsurerTheme()` - Apply custom brand colors
+
+**Computed Signals:**
+- `themeName()` - Returns current theme name
+- `isDarkTheme()` - Returns boolean for dark mode
+- `themeInfo()` - Returns complete theme information
+
+**Example:**
+
+```typescript
+import { inject } from '@angular/core';
+import { ThemeService } from 'ps-helix';
+
+export class MyComponent {
+  themeService = inject(ThemeService);
+
+  get currentTheme() {
+    return this.themeService.themeName(); // 'light' or 'dark'
+  }
+
+  get isDark() {
+    return this.themeService.isDarkTheme(); // boolean
+  }
+
+  switchTheme() {
+    this.themeService.toggleTheme();
+  }
+}
+```
+
+### ToastService
+
+Display temporary notification messages.
+
+**Methods:**
+- `success(message: string, options?)` - Show success toast
+- `error(message: string, options?)` - Show error toast
+- `warning(message: string, options?)` - Show warning toast
+- `info(message: string, options?)` - Show info toast
+
+**Options:**
+- `duration?: number` - Display duration in milliseconds (default: 3000)
+- `position?: ToastPosition` - 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
+
+**Example:**
+
+```typescript
+import { inject } from '@angular/core';
 import { ToastService } from 'ps-helix';
 
 export class MyComponent {
   private toastService = inject(ToastService);
 
-  showSuccess() {
-    this.toastService.success('Operation completed successfully!');
+  saveData() {
+    try {
+      // Save logic
+      this.toastService.success('Data saved successfully!');
+    } catch (error) {
+      this.toastService.error('Failed to save data');
+    }
+  }
+
+  showCustom() {
+    this.toastService.info('Processing...', {
+      duration: 5000,
+      position: 'bottom-right'
+    });
+  }
+}
+```
+
+### ScrollService
+
+Utility service for scroll management and smooth scrolling.
+
+**Methods:**
+- `scrollToTop()` - Scroll to page top smoothly
+- `scrollToElement(selector: string)` - Scroll to specific element
+- `disableScroll()` - Disable page scrolling (useful for modals)
+- `enableScroll()` - Re-enable page scrolling
+
+**Example:**
+
+```typescript
+import { inject } from '@angular/core';
+import { ScrollService } from 'ps-helix';
+
+export class MyComponent {
+  private scrollService = inject(ScrollService);
+
+  backToTop() {
+    this.scrollService.scrollToTop();
+  }
+
+  goToSection(sectionId: string) {
+    this.scrollService.scrollToElement(`#${sectionId}`);
   }
 
-  showError() {
-    this.toastService.error('An error occurred');
+  openModal() {
+    this.scrollService.disableScroll();
+    // Show modal
   }
 
-  showInfo() {
-    this.toastService.info('Information message', { duration: 5000 });
+  closeModal() {
+    this.scrollService.enableScroll();
+    // Hide modal
   }
 }
 ```
 
-## Theming
+### TranslationService
 
-The design system includes built-in support for light and dark themes. Theme switching is handled automatically through the ThemeService.
+Wrapper service for ngx-translate functionality.
 
-### Custom Theme Colors
+**Methods:**
+- `setLanguage(lang: string)` - Change application language
+- `getTranslation(key: string)` - Get translation for a key
+- `instant(key: string)` - Get instant translation (synchronous)
 
-You can customize theme colors by providing an InsurerContextService:
+**Example:**
 
 ```typescript
-import { InjectionToken } from '@angular/core';
-import { INSURER_CONTEXT_SERVICE } from 'ps-helix';
+import { Component, inject } from '@angular/core';
+import { TranslationService } from 'ps-helix';
 
-const myContextService = {
-  primaryColor: () => '#0F02C4',
-  secondaryColor: () => '#7B3AEC'
-};
+@Component({
+  selector: 'app-language-selector',
+  template: `
+    <select (change)="changeLanguage($event)">
+      <option value="en">English</option>
+      <option value="fr">Français</option>
+      <option value="es">Español</option>
+      <option value="de">Deutsch</option>
+    </select>
+  `
+})
+export class LanguageSelectorComponent {
+  private translationService = inject(TranslationService);
 
-export const appConfig: ApplicationConfig = {
-  providers: [
-    {
-      provide: INSURER_CONTEXT_SERVICE,
-      useValue: myContextService
-    }
-  ]
-};
+  changeLanguage(event: Event) {
+    const selectedLang = (event.target as HTMLSelectElement).value;
+    this.translationService.setLanguage(selectedLang);
+  }
+}
 ```
 
-## TypeScript Support
+## Exported Types
+
+All component types and enums are exported for type-safe development:
 
-All components are fully typed with TypeScript. Import types as needed:
+### Alert Types
 
 ```typescript
-import {
-  ButtonVariant,
-  ButtonSize,
-  ButtonAppearance
-} from 'ps-helix';
+import { AlertType, AlertVariant } from 'ps-helix';
+
+const type: AlertType = 'success' | 'error' | 'warning' | 'info';
+const variant: AlertVariant = 'solid' | 'outlined' | 'soft';
+```
+
+### Avatar Types
+
+```typescript
+import { AvatarSize, AvatarShape } from 'ps-helix';
+
+const size: AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+const shape: AvatarShape = 'circle' | 'square';
+```
+
+### Badge Types
+
+```typescript
+import { BadgeSize, BadgeVariant } from 'ps-helix';
+
+const size: BadgeSize = 'sm' | 'md' | 'lg';
+const variant: BadgeVariant = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info';
+```
+
+### Button Types
+
+```typescript
+import { ButtonAppearance, ButtonSize, ButtonVariant } from 'ps-helix';
+
+const appearance: ButtonAppearance = 'filled' | 'outlined' | 'text' | 'ghost';
+const size: ButtonSize = 'small' | 'medium' | 'large';
+const variant: ButtonVariant = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info';
+```
+
+### Input Types
+
+```typescript
+import { InputSize, InputType } from 'ps-helix';
+
+const size: InputSize = 'small' | 'medium' | 'large';
+const type: InputType = 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search';
+```
+
+### Modal Types
+
+```typescript
+import { ModalSize } from 'ps-helix';
+
+const size: ModalSize = 'small' | 'medium' | 'large' | 'fullscreen';
+```
+
+### Select Types
+
+```typescript
+import { SelectFilterMode, SelectPlacement, SelectSize } from 'ps-helix';
+
+const filterMode: SelectFilterMode = 'none' | 'startsWith' | 'contains';
+const placement: SelectPlacement = 'bottom' | 'top';
+const size: SelectSize = 'small' | 'medium' | 'large';
+```
+
+### Stepper Types
+
+```typescript
+import { StepperVariant } from 'ps-helix';
+
+const variant: StepperVariant = 'default' | 'numbered' | 'progress';
+```
+
+### Table Types
+
+```typescript
+import { TableColumn, TableSortDirection } from 'ps-helix';
+
+const sortDirection: TableSortDirection = 'asc' | 'desc' | null;
+
+interface TableColumn<T> {
+  key: string;
+  label: string;
+  sortable?: boolean;
+  width?: string;
+  align?: 'left' | 'center' | 'right';
+  render?: (item: T) => string;
+}
+```
+
+### Toast Types
+
+```typescript
+import { ToastPosition, ToastVariant } from 'ps-helix';
+
+const position: ToastPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+const variant: ToastVariant = 'success' | 'error' | 'warning' | 'info';
+```
+
+### Tooltip Types
+
+```typescript
+import { TooltipPlacement, TooltipTrigger } from 'ps-helix';
+
+const placement: TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+const trigger: TooltipTrigger = 'hover' | 'click' | 'focus';
+```
+
+For a complete list of all exported types, see the [type definitions](./src/public-api.ts).
+
+## Theming
+
+### Default Colors
+
+Helix provides default theme colors:
+- **Primary**: `#0F02C4` (Deep Blue)
+- **Secondary**: `#7B3AEC` (Purple)
+
+### Custom Brand Colors
+
+Customize to match your brand identity using the injection token pattern. See the complete guide in [THEME.md](./THEME.md).
+
+### Available CSS Variables
+
+Once configured, numerous CSS variables are available:
+
+**Primary Color:**
+- `--primary-color`
+- `--primary-color-light`
+- `--primary-color-lighter`
+- `--primary-color-dark`
+- `--primary-color-darker`
+- `--primary-color-text`
+- `--primary-color-rgb`
+
+**Secondary Color:**
+- `--secondary-color`
+- `--secondary-color-light`
+- `--secondary-color-lighter`
+- `--secondary-color-dark`
+- `--secondary-color-darker`
+- `--secondary-color-text`
+- `--secondary-color-rgb`
+
+### Using Custom Variables
+
+```css
+.my-button {
+  background: var(--primary-color);
+  color: var(--primary-color-text);
+}
+
+.my-button:hover {
+  background: var(--primary-color-light);
+}
+```
+
+For complete theming guide including custom colors, dynamic changes, and advanced configurations, see [THEME.md](./THEME.md).
+
+## Best Practices
+
+### Component Organization
+
+```typescript
+// ✅ Good: Import only what you need
+import { PshButtonComponent, PshInputComponent } from 'ps-helix';
+
+// ❌ Avoid: Don't import entire module
+import * as Helix from 'ps-helix';
+```
+
+### Type Safety
+
+```typescript
+// ✅ Good: Use exported types
+import { ButtonVariant, ButtonSize } from 'ps-helix';
 
 const variant: ButtonVariant = 'primary';
 const size: ButtonSize = 'medium';
+
+// ❌ Avoid: Magic strings without types
+const variant = 'primary'; // No type checking
+```
+
+### Signal Usage
+
+```typescript
+// ✅ Good: Use signals for reactive state
+import { signal } from '@angular/core';
+
+export class MyComponent {
+  isVisible = signal(false);
+
+  toggle() {
+    this.isVisible.update(v => !v);
+  }
+}
+
+// ❌ Avoid: Traditional properties for reactive UI
+export class MyComponent {
+  isVisible = false; // Won't trigger change detection optimally
+}
+```
+
+### Accessibility
+
+```html
+<!-- ✅ Good: Proper ARIA labels for icon-only buttons -->
+<button aria-label="Delete item" (click)="delete()">
+  <i class="ph ph-trash" aria-hidden="true"></i>
+</button>
+
+<!-- ❌ Avoid: Icon buttons without labels -->
+<button (click)="delete()">
+  <i class="ph ph-trash"></i>
+</button>
+```
+
+### Form Integration
+
+```typescript
+// ✅ Good: Reactive forms with FormControl
+import { FormControl, Validators } from '@angular/forms';
+
+export class MyComponent {
+  emailControl = new FormControl('', [
+    Validators.required,
+    Validators.email
+  ]);
+}
+```
+
+```html
+<psh-input
+  label="Email"
+  [formControl]="emailControl"
+  [required]="true">
+</psh-input>
 ```
 
+### Performance Optimization
+
+```typescript
+// ✅ Good: Use OnPush change detection
+import { ChangeDetectionStrategy } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `...`
+})
+export class ExampleComponent {}
+
+// ✅ Good: Use trackBy for lists
+@Component({
+  template: `
+    @for (item of items(); track item.id) {
+      <psh-card>{{ item.name }}</psh-card>
+    }
+  `
+})
+export class ListComponent {
+  items = signal<Item[]>([]);
+}
+```
+
+### Testing
+
+```typescript
+// ✅ Good: Test components with TestBed
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { PshButtonComponent } from 'ps-helix';
+
+describe('MyComponent', () => {
+  let component: MyComponent;
+  let fixture: ComponentFixture<MyComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [MyComponent, PshButtonComponent]
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(MyComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it('should create', () => {
+    expect(component).toBeTruthy();
+  });
+});
+```
+
+## Troubleshooting
+
+### Styles Not Applied
+
+**Problem**: Components appear unstyled or broken.
+
+**Solution**: Ensure you've imported the global stylesheet:
+
+```css
+/* In src/styles.css */
+@import 'ps-helix/styles.css';
+```
+
+### Icons Not Displaying
+
+**Problem**: Icons show as empty squares or missing glyphs.
+
+**Solution**: Verify Phosphor Icons CDN links are in `index.html`:
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.0.3/src/regular/style.css">
+<link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.0.3/src/fill/style.css">
+<link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.0.3/src/bold/style.css">
+<link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.0.3/src/light/style.css">
+```
+
+### Custom Colors Not Applying
+
+**Problem**: Brand colors aren't being used.
+
+**Solution**:
+1. Verify your theme context service implements `InsurerContextService`
+2. Check the provider configuration in `main.ts` or `app.config.ts`
+3. Ensure you're using valid hex color codes (e.g., `#FF0000`)
+4. Call `themeService.applyInsurerTheme()` after color changes
+
+See [THEME.md](./THEME.md) for complete theming documentation.
+
+### TypeScript Errors
+
+**Problem**: TypeScript compilation errors with component imports.
+
+**Solution**:
+1. Verify Angular version is 20.0.0 or higher
+2. Check `tsconfig.json` has `"strict": true`
+3. Ensure all peer dependencies are installed
+4. Clear node_modules and reinstall: `rm -rf node_modules && npm install`
+
+### Performance Issues
+
+**Problem**: Application feels slow or unresponsive.
+
+**Solution**:
+1. Use `OnPush` change detection strategy
+2. Implement proper signal usage
+3. Avoid unnecessary component re-renders
+4. Use `trackBy` functions in `@for` loops
+5. Lazy load routes and components where possible
+
+### Build Errors
+
+**Problem**: Build fails with module resolution errors.
+
+**Solution**:
+1. Verify package.json includes ps-helix in dependencies
+2. Clear Angular cache: `ng cache clean`
+3. Delete .angular folder and rebuild
+4. Check that all peer dependencies match required versions
+
+### Runtime Errors
+
+**Problem**: Errors in browser console at runtime.
+
+**Solution**:
+1. Check browser console for specific error messages
+2. Verify all required services are provided
+3. Ensure ThemeService is initialized if using custom themes
+4. Check that ngx-translate is properly configured if using i18n
+
 ## Browser Support
 
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
+Helix Design System supports:
 
-## License
+- **Chrome**: Latest 2 versions
+- **Firefox**: Latest 2 versions
+- **Safari**: Latest 2 versions
+- **Edge**: Latest 2 versions
+- **Mobile browsers**: iOS Safari 14+, Chrome Android latest
+
+**Note**: Internet Explorer is not supported.
+
+## Development Scripts
+
+The following npm scripts are available for library development:
+
+```bash
+# Build the library
+npm run build:lib
+
+# Watch for changes and rebuild
+npm run watch:lib
+
+# Publish to npm registry
+npm run publish:lib
+
+# Build demo application
+npm run build
 
-MIT
+# Run demo application in dev mode
+npm run dev
+```
 
 ## Contributing
 
-Issues and pull requests are welcome on the repository.
+We welcome contributions! To contribute to Helix Design System:
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes and commit: `git commit -am 'Add new feature'`
+4. Push to the branch: `git push origin feature/my-feature`
+5. Submit a pull request
+
+### Development Guidelines
+
+- Follow Angular style guide
+- Use TypeScript strict mode
+- Write tests for new components
+- Document all public APIs
+- Ensure accessibility compliance (WCAG 2.1 AA)
+- Keep components small and focused
+- Use signals for reactive state
+
+## License
+
+MIT License - see LICENSE file for details.
+
+Copyright (c) 2025 PACK Solutions
+
+## Resources
+
+- **Theme Customization Guide**: [THEME.md](./THEME.md)
+- **Component Documentation**: Individual component README files in `/lib/components/`
+- **Phosphor Icons**: [https://phosphoricons.com/](https://phosphoricons.com/)
+- **Angular Documentation**: [https://angular.dev/](https://angular.dev/)
+- **TypeScript Documentation**: [https://www.typescriptlang.org/](https://www.typescriptlang.org/)
+- **ngx-translate**: [https://github.com/ngx-translate/core](https://github.com/ngx-translate/core)
+
+---
+
+**Version**: 2.0.0
+**Built with**: Angular 20.0.0, TypeScript 5.8.0, Phosphor Icons 2.0.3
+**Author**: Fabrice PEREZ | Product Designer at PACK Solutions
+**Last Updated**: November 2025