ps-helix 4.1.0 → 5.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 A comprehensive Angular component library built with Angular 21+ featuring modern design patterns, accessibility-first development, and optimal developer experience.
 
-[![npm version](https://img.shields.io/badge/npm-4.1.0-blue.svg)](https://www.npmjs.com/package/ps-helix)
+[![npm version](https://img.shields.io/badge/npm-5.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-21.0.3-red.svg)](https://angular.dev/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9.0-blue.svg)](https://www.typescriptlang.org/)
@@ -106,7 +106,7 @@ After installation, verify that ps-helix is in your `package.json`:
 ```json
 {
   "dependencies": {
-    "ps-helix": "^4.1.0"
+    "ps-helix": "^5.0.0"
   }
 }
 ```
@@ -1182,7 +1182,7 @@ Copyright (c) 2025 PACK Solutions
 
 ---
 
-**Version**: 4.1.0
+**Version**: 5.0.0
 **Built with**: Angular 21.0.3, TypeScript 5.9.0, Phosphor Icons 2.0.3
 **Author**: Fabrice PEREZ | Product Designer at PACK Solutions
 **Last Updated**: January 2026

package/THEME.md

@@ -8,19 +8,21 @@ This guide explains how to customize the colors and theme of the Helix Design Sy
 - [Quick Start](#quick-start)
 - [Theme Service](#theme-service)
 - [Custom Colors with Injection Token](#custom-colors-with-injection-token)
+- [Accessibility Safeguard (WCAG)](#accessibility-safeguard-wcag)
 - [Available CSS Variables](#available-css-variables)
 - [Dynamic Color Changes](#dynamic-color-changes)
 - [Examples](#examples)
 
 ## Overview
 
-The Helix Design System uses a sophisticated theming system that supports:
+The Helix Design System uses a signal-based theming system that supports:
 
 - Light and dark themes
-- Custom primary and secondary colors
-- Automatic color variant generation (lighter, darker)
-- Automatic text color calculation for accessibility
+- Custom primary and secondary brand colors (customer context)
+- Automatic variant generation in OKLCH (hue and chroma preserved, lightness adjusted per mode)
+- WCAG contrast safeguard: a brand color that does not meet the target contrast ratio against the current theme background is silently adjusted before being applied to UI components
 - Dynamic theme switching at runtime
+- Theme preference persistence in `localStorage` (key: `helix-theme-preference`)
 
 ## Quick Start
 
@@ -34,7 +36,6 @@ import { ThemeService } from 'ps-helix';
 
 @Component({
   selector: 'app-root',
-  standalone: true,
   template: `
     <button (click)="toggleTheme()">
       Current theme: {{ themeService.themeName() }}
@@ -58,59 +59,67 @@ The `ThemeService` provides the following API:
 
 - `setDarkTheme(isDark: boolean)` - Set the theme to dark or light
 - `toggleTheme()` - Toggle between light and dark themes
-- `updateTheme(name: Theme)` - Update theme by name ('light' or 'dark')
-- `applyInsurerTheme()` - Apply custom colors (usually called automatically)
+- `updateTheme(name: Theme)` - Update theme by name (`'light'` or `'dark'`) and persist it in localStorage
+- `applyCustomerTheme()` - Re-apply brand colors from the customer context (usually called automatically after theme changes or when the context updates)
 
 ### Computed Signals
 
-- `themeName()` - Returns current theme name ('light' or 'dark')
-- `isDarkTheme()` - Returns boolean indicating if dark theme is active
-- `themeInfo()` - Returns complete theme information including last change date
+- `themeName()` - Returns current theme name (`'light'` or `'dark'`)
+- `isDarkTheme()` - Returns a boolean indicating whether dark theme is active
+- `themeInfo()` - Returns complete theme information including the last change date
 
-## Default Colors
+### Types
 
-If you don't provide custom colors, the design system uses the following default theme colors:
+```typescript
+export type Theme = 'light' | 'dark';
+
+export interface ThemeConfig {
+  isDark: boolean;
+  name: Theme;
+  customerTheme?: {
+    primaryColor: string;
+    secondaryColor?: string;
+  };
+}
+```
 
-- **Primary Color**: `#0F02C4` (Deep Blue)
-- **Secondary Color**: `#7B3AEC` (Purple)
+## Default Colors
 
-These colors are used across all components and automatically generate variants (lighter/darker shades) and accessible text colors.
+If you don't provide custom colors, the design system falls back to the CSS defaults defined in the theme files:
 
-## Custom Colors with Injection Token
+- Light mode primary: `#0B0191`
+- Dark mode primary: `#8178F7`
+- Light mode secondary: `#5E5E5E`
+- Dark mode secondary: `#5B5A5A`
 
-To customize the primary and secondary colors of your design system to match your brand, you need to provide a service that implements the color interface using Angular's dependency injection system.
+These defaults are defined in `projects/ps-helix/src/lib/styles/themes/light.css` and `dark.css`.
 
-### Why Not Just CSS Variables?
+## Custom Colors with Injection Token
 
-The design system uses an **injection token system** instead of simple CSS variable overrides because:
+To customize the primary and secondary colors of your design system to match your brand, provide a service that implements `CustomerContextService` through the `CUSTOMER_CONTEXT_SERVICE` injection token.
 
-1. Colors are dynamically calculated with variants (lighter, darker, etc.)
-2. Text colors are automatically determined based on background luminance for accessibility
-3. Changes can be reactive and propagate through the application
-4. It provides type safety and better Angular integration
+### Why an Injection Token and not just CSS variables?
 
-### Step 1: Create a Theme Context Service
+1. Variants (light, lighter, dark, darker) are computed in OKLCH at runtime and depend on the current theme (light vs dark).
+2. Text color on top of brand colors is computed from real WCAG contrast ratios.
+3. Brand colors are verified against a minimum contrast ratio and silently adjusted for UI usage when needed; the original color is still exposed as `-source` for decorative contexts.
+4. The token keeps everything type-safe and reactive via Angular DI.
 
-Create a service in your application that implements the `InsurerContextService` interface:
+### Step 1: Create a Customer Context Service
 
 ```typescript
 // src/app/services/app-theme-context.service.ts
 import { Injectable, signal } from '@angular/core';
-import { InsurerContextService } from 'ps-helix';
+import { CustomerContextService } from 'ps-helix';
 
-@Injectable({
-  providedIn: 'root'
-})
-export class AppThemeContextService implements InsurerContextService {
-  // Define your custom colors using signals for reactivity
-  private primaryColorSignal = signal('#FF0000');    // Your primary color
-  private secondaryColorSignal = signal('#00AA00');  // Your secondary color
+@Injectable({ providedIn: 'root' })
+export class AppThemeContextService implements CustomerContextService {
+  private primaryColorSignal = signal('#FF0000');
+  private secondaryColorSignal = signal('#00AA00');
 
-  // Expose as readonly signals - required by InsurerContextService interface
   primaryColor = this.primaryColorSignal.asReadonly();
   secondaryColor = this.secondaryColorSignal.asReadonly();
 
-  // Optional: Methods to change colors dynamically
   setPrimaryColor(color: string) {
     this.primaryColorSignal.set(color);
   }
@@ -121,121 +130,143 @@ export class AppThemeContextService implements InsurerContextService {
 }
 ```
 
-The `InsurerContextService` interface requires two methods:
-- `primaryColor(): string` - Returns the primary brand color
-- `secondaryColor(): string` - Returns the secondary brand color
+The `CustomerContextService` interface requires two methods:
 
-### Step 2: Provide the Service with the Injection Token
+- `primaryColor(): string` - Returns the primary brand color (hex)
+- `secondaryColor(): string` - Returns the secondary brand color (hex)
 
-In your application configuration (usually `app.config.ts` or `main.ts`), provide your service using the `INSURER_CONTEXT_SERVICE` token:
+### Step 2: Provide the Service with the Injection Token
 
 ```typescript
 // src/app/app.config.ts
 import { ApplicationConfig } from '@angular/core';
 import { provideRouter } from '@angular/router';
-import { INSURER_CONTEXT_SERVICE } from 'ps-helix';
+import { CUSTOMER_CONTEXT_SERVICE } from 'ps-helix';
 import { AppThemeContextService } from './services/app-theme-context.service';
 import { routes } from './app.routes';
 
 export const appConfig: ApplicationConfig = {
   providers: [
     provideRouter(routes),
-    // Connect your service to the design system's injection token
     {
-      provide: INSURER_CONTEXT_SERVICE,
+      provide: CUSTOMER_CONTEXT_SERVICE,
       useExisting: AppThemeContextService
     }
   ]
 };
 ```
 
-### Step 3: Initialize the Theme (Optional)
-
-In your root component, you can inject the `ThemeService` to ensure the theme is applied:
+### Step 3: Re-apply the Theme (Optional)
 
 ```typescript
-// src/app/app.component.ts
 import { Component, inject, OnInit } from '@angular/core';
 import { ThemeService } from 'ps-helix';
 
 @Component({
   selector: 'app-root',
-  standalone: true,
   template: `<router-outlet />`
 })
 export class AppComponent implements OnInit {
   private themeService = inject(ThemeService);
 
   ngOnInit() {
-    // Theme is applied automatically, but you can force it if needed
-    this.themeService.applyInsurerTheme();
+    this.themeService.applyCustomerTheme();
   }
 }
 ```
 
 ### Alternative: Simple Non-Reactive Service
 
-If you don't need dynamic color changes, you can use a simpler implementation without signals:
-
 ```typescript
 import { Injectable } from '@angular/core';
-import { InsurerContextService } from 'ps-helix';
-
-@Injectable({
-  providedIn: 'root'
-})
-export class AppThemeContextService implements InsurerContextService {
-  primaryColor() {
-    return '#FF0000';
-  }
+import { CustomerContextService } from 'ps-helix';
 
-  secondaryColor() {
-    return '#00AA00';
-  }
+@Injectable({ providedIn: 'root' })
+export class AppThemeContextService implements CustomerContextService {
+  primaryColor() { return '#FF0000'; }
+  secondaryColor() { return '#00AA00'; }
 }
 ```
 
-This approach returns static colors and is perfect when you don't need runtime color changes.
+## Accessibility Safeguard (WCAG)
+
+When `applyCustomerTheme()` runs, each brand color is evaluated against the current theme background:
+
+- Contrast is computed using the true WCAG 2.1 relative luminance formula.
+- If the ratio is below the target (AA by default, AAA if configured), the color is adjusted in OKLCH: the luminance is shifted (darker on light backgrounds, lighter on dark backgrounds) while hue and chroma are preserved as much as possible.
+- The adjusted color is written into `--customer-primary-color` / `--customer-secondary-color` and consumed by every UI component.
+- The original, unmodified brand color is written into `--customer-primary-color-source` / `--customer-secondary-color-source`, available for decorative surfaces (logos, marketing images) where the contrast rule does not apply.
+- The service never logs or warns: the adjustment is silent by design.
+
+### Configuring the Target Ratio
+
+Use the `PSH_THEME_OPTIONS` injection token to opt into AAA:
+
+```typescript
+import { PSH_THEME_OPTIONS, PshThemeOptions } from 'ps-helix';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: PSH_THEME_OPTIONS,
+      useValue: { targetContrast: 'AAA' } satisfies PshThemeOptions
+    }
+  ]
+};
+```
+
+Default is `'AA'` (ratio 4.5:1). `'AAA'` raises the requirement to 7:1.
+
+### OKLCH Variant Derivation
+
+The four tonal variants (`light`, `lighter`, `dark`, `darker`) are generated by shifting the OKLCH lightness of the accessible base color with mode-aware deltas:
+
+| Mode  | light | lighter | dark  | darker |
+|-------|-------|---------|-------|--------|
+| Light | +0.08 | +0.18   | -0.08 | -0.16  |
+| Dark  | +0.06 | +0.14   | -0.06 | -0.14  |
+
+Hue and chroma are preserved so the color palette stays perceptually consistent. Fixed percentage RGB lightening/darkening is no longer used.
 
 ## Available CSS Variables
 
-Once configured, the `ThemeService` automatically generates the following CSS variables:
+Once configured, `ThemeService` writes the following CSS variables on `:root`:
 
 ### Primary Color Variables
 
-- `--insurer-primary-color` - Your primary color
-- `--insurer-primary-color-light` - Lightened by 20%
-- `--insurer-primary-color-lighter` - Lightened by 40%
-- `--insurer-primary-color-dark` - Darkened by 20%
-- `--insurer-primary-color-darker` - Darkened by 40%
-- `--insurer-primary-color-text` - Calculated text color (black or white) for accessibility
-- `--insurer-primary-color-rgb` - RGB values for transparency usage
+- `--customer-primary-color` - Accessibility-adjusted primary color (used by components)
+- `--customer-primary-color-source` - Original brand color, unmodified (for decorative use only)
+- `--customer-primary-color-light` - OKLCH-derived lighter variant
+- `--customer-primary-color-lighter` - OKLCH-derived extra light variant
+- `--customer-primary-color-dark` - OKLCH-derived darker variant
+- `--customer-primary-color-darker` - OKLCH-derived extra dark variant
+- `--customer-primary-color-text` - Readable text color (black or white) picked via WCAG contrast against the adjusted primary
+- `--customer-primary-color-rgb` - `r, g, b` triplet of the adjusted primary for `rgba()` usage
 
 ### Secondary Color Variables
 
-- `--insurer-secondary-color`
-- `--insurer-secondary-color-light`
-- `--insurer-secondary-color-lighter`
-- `--insurer-secondary-color-dark`
-- `--insurer-secondary-color-darker`
-- `--insurer-secondary-color-text`
-- `--insurer-secondary-color-rgb`
+- `--customer-secondary-color`
+- `--customer-secondary-color-source`
+- `--customer-secondary-color-light`
+- `--customer-secondary-color-lighter`
+- `--customer-secondary-color-dark`
+- `--customer-secondary-color-darker`
+- `--customer-secondary-color-text`
+- `--customer-secondary-color-rgb`
 
 ### Component Usage
 
-These variables are automatically used by design system components through fallback chains:
+Design system components consume the stable abstract variables, which fall back to the defaults when no customer context is provided:
 
 ```css
-/* Example from the design system */
---primary-color: var(--insurer-primary-color, #1002C5);
---primary-color-light: var(--insurer-primary-color-light, #8080FF);
+/* From projects/ps-helix/src/lib/styles/themes/light.css */
+--primary-color: var(--customer-primary-color, #0B0191);
+--primary-color-light: var(--customer-primary-color-light, #0F02C4);
 ```
 
-If you provide a custom color through the injection token, it takes precedence. Otherwise, the default color is used.
-
 ### Using in Your Custom Styles
 
-You can also use these variables in your own components:
+Use the abstract variables (`--primary-color`, `--secondary-color`, ...) in your own components so you automatically inherit the accessibility-adjusted palette:
 
 ```css
 .my-custom-button {
@@ -248,9 +279,17 @@ You can also use these variables in your own components:
 }
 ```
 
+For decorative brand elements that must match the literal brand color (e.g. a logo background), use the `-source` variable:
+
+```css
+.brand-logo-surface {
+  background-color: var(--customer-primary-color-source);
+}
+```
+
 ## Dynamic Color Changes
 
-Since the theme context service uses signals, you can change colors dynamically at runtime:
+Since the customer context service uses signals, you can change colors at runtime:
 
 ```typescript
 import { Component, inject } from '@angular/core';
@@ -259,13 +298,10 @@ import { AppThemeContextService } from './services/app-theme-context.service';
 
 @Component({
   selector: 'app-theme-switcher',
-  standalone: true,
   template: `
-    <div>
-      <button (click)="setRedTheme()">Red Theme</button>
-      <button (click)="setBlueTheme()">Blue Theme</button>
-      <button (click)="setGreenTheme()">Green Theme</button>
-    </div>
+    <button (click)="setRedTheme()">Red</button>
+    <button (click)="setBlueTheme()">Blue</button>
+    <button (click)="setGreenTheme()">Green</button>
   `
 })
 export class ThemeSwitcherComponent {
@@ -275,19 +311,19 @@ export class ThemeSwitcherComponent {
   setRedTheme() {
     this.themeContext.setPrimaryColor('#DC2626');
     this.themeContext.setSecondaryColor('#EF4444');
-    this.themeService.applyInsurerTheme();
+    this.themeService.applyCustomerTheme();
   }
 
   setBlueTheme() {
     this.themeContext.setPrimaryColor('#2563EB');
     this.themeContext.setSecondaryColor('#3B82F6');
-    this.themeService.applyInsurerTheme();
+    this.themeService.applyCustomerTheme();
   }
 
   setGreenTheme() {
     this.themeContext.setPrimaryColor('#16A34A');
     this.themeContext.setSecondaryColor('#22C55E');
-    this.themeService.applyInsurerTheme();
+    this.themeService.applyCustomerTheme();
   }
 }
 ```
@@ -296,15 +332,11 @@ export class ThemeSwitcherComponent {
 
 ### Example 1: Brand Colors from Configuration
 
-Load colors from a configuration file or environment:
-
 ```typescript
 import { Injectable, signal } from '@angular/core';
 import { environment } from '../environments/environment';
 
-@Injectable({
-  providedIn: 'root'
-})
+@Injectable({ providedIn: 'root' })
 export class AppThemeContextService {
   private primaryColorSignal = signal(environment.brandPrimaryColor);
   private secondaryColorSignal = signal(environment.brandSecondaryColor);
@@ -316,51 +348,36 @@ export class AppThemeContextService {
 
 ### Example 2: User-Selected Theme
 
-Allow users to customize their theme:
-
 ```typescript
 import { Injectable, signal, effect } from '@angular/core';
 
-@Injectable({
-  providedIn: 'root'
-})
+@Injectable({ providedIn: 'root' })
 export class AppThemeContextService {
-  private primaryColorSignal = signal(this.loadFromStorage('primaryColor', '#1002C5'));
-  private secondaryColorSignal = signal(this.loadFromStorage('secondaryColor', '#7B3AEC'));
+  private primaryColorSignal = signal(this.loadFromStorage('primaryColor', '#0B0191'));
+  private secondaryColorSignal = signal(this.loadFromStorage('secondaryColor', '#5E5E5E'));
 
   primaryColor = this.primaryColorSignal.asReadonly();
   secondaryColor = this.secondaryColorSignal.asReadonly();
 
   constructor() {
-    // Save to localStorage when colors change
     effect(() => {
       localStorage.setItem('primaryColor', this.primaryColorSignal());
       localStorage.setItem('secondaryColor', this.secondaryColorSignal());
     });
   }
 
-  setPrimaryColor(color: string) {
-    this.primaryColorSignal.set(color);
-  }
-
-  setSecondaryColor(color: string) {
-    this.secondaryColorSignal.set(color);
-  }
+  setPrimaryColor(color: string) { this.primaryColorSignal.set(color); }
+  setSecondaryColor(color: string) { this.secondaryColorSignal.set(color); }
 
   private loadFromStorage(key: string, defaultValue: string): string {
-    try {
-      return localStorage.getItem(key) || defaultValue;
-    } catch {
-      return defaultValue;
-    }
+    try { return localStorage.getItem(key) || defaultValue; }
+    catch { return defaultValue; }
   }
 }
 ```
 
 ### Example 3: Multi-Tenant Application
 
-Different colors per tenant/client:
-
 ```typescript
 import { Injectable, signal } from '@angular/core';
 
@@ -375,9 +392,7 @@ const TENANT_THEMES: Record<string, TenantTheme> = {
   'tenant-c': { primary: '#16A34A', secondary: '#22C55E' }
 };
 
-@Injectable({
-  providedIn: 'root'
-})
+@Injectable({ providedIn: 'root' })
 export class AppThemeContextService {
   private currentTenantId = signal<string>('tenant-a');
   private primaryColorSignal = signal(TENANT_THEMES['tenant-a'].primary);
@@ -399,45 +414,33 @@ export class AppThemeContextService {
 
 ## Troubleshooting
 
-### Colors Not Applying
-
-1. **Check if the service is provided correctly**: Verify that you've provided your service with the `INSURER_CONTEXT_SERVICE` token in your app config.
-
-2. **Check the console**: The `ThemeService` logs information about color application. Look for messages like:
-   ```
-   Applying theme colors: { primaryColor: '#FF0000', ... }
-   Applied insurer theme with primary color: #FF0000
-   ```
-
-3. **Verify the service implementation**: Make sure your service has `primaryColor()` and `secondaryColor()` methods that return strings.
-
-### Default Colors Showing Instead of Custom Colors
+### Colors not applying
 
-If you see the default blue colors (`#1002C5`) instead of your custom colors:
+1. Verify that your service is provided with the `CUSTOMER_CONTEXT_SERVICE` token in your app config.
+2. Confirm your service implements `primaryColor()` and `secondaryColor()` returning valid hex strings.
+3. `ThemeService` is silent by design; if a brand color looks different from the one you provided, it is because the WCAG safeguard adjusted it. Read the adjusted color via `getComputedStyle(document.documentElement).getPropertyValue('--customer-primary-color')` and the original via `--customer-primary-color-source`.
 
-1. The service might not be injected properly
-2. The methods might not be returning valid hex color codes
-3. Check the browser console for error messages
+### Default colors showing instead of custom colors
 
-### Colors Not Updating Dynamically
+- The context service is not provided, or
+- `primaryColor()` / `secondaryColor()` return an invalid hex string.
 
-If colors don't update when you call `setPrimaryColor()`:
+### Colors not updating dynamically
 
-1. Make sure you're calling `this.themeService.applyInsurerTheme()` after changing the colors
-2. Verify that your signals are updating correctly
-3. Check that the ThemeService is injected in your component
+1. Make sure you call `this.themeService.applyCustomerTheme()` after changing a color.
+2. Verify that your signals are actually updating.
+3. Confirm `ThemeService` is injected in the component driving the change.
 
 ## Best Practices
 
-1. **Use Signals**: Always use Angular signals for reactive color management
-2. **Validate Colors**: Ensure color values are valid hex codes (e.g., `#FF0000`)
-3. **Accessibility**: Let the ThemeService calculate text colors automatically for proper contrast
-4. **Persistence**: Consider saving user color preferences to localStorage
-5. **Defaults**: Always provide sensible default colors as fallbacks
-6. **Documentation**: Document your color choices and brand guidelines
+1. Use signals in your customer context service for reactivity.
+2. Provide valid hex colors (`#RRGGBB`).
+3. Trust the WCAG safeguard; do not hand-tune base colors for contrast.
+4. For decorative brand surfaces, use `--customer-*-color-source`. For every other UI use case, use the abstract variables (`--primary-color`, ...).
+5. Persist user preferences in `localStorage` when relevant.
+6. Document brand color choices alongside your app's style guide.
 
 ## Related Documentation
 
 - [Component Documentation](./README.md)
 - [Translation Guide](./lib/services/translation/README.md)
-- [Accessibility Guidelines](./ACCESSIBILITY.md)