ps-helix 6.2.3 → 7.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 A comprehensive Angular component library built with Angular 22+ featuring modern design patterns, accessibility-first development, and optimal developer experience.
 
-[![npm version](https://img.shields.io/badge/npm-6.2.3-blue.svg)](https://www.npmjs.com/package/ps-helix)
+[![npm version](https://img.shields.io/badge/npm-7.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-22.0.0-red.svg)](https://angular.dev/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0.0-blue.svg)](https://www.typescriptlang.org/)
@@ -14,10 +14,11 @@ A comprehensive Angular component library built with Angular 22+ featuring moder
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
+  - [`provideHelix()`](#providehelix)
   - [Global Styles](#global-styles)
   - [Phosphor Icons Setup](#phosphor-icons-setup)
   - [Theme Service](#theme-service)
-  - [Translation Service](#translation-service)
+  - [Internationalization](#internationalization)
   - [Scroll Service](#scroll-service)
 - [Core Concepts](#core-concepts)
   - [Standalone Components](#standalone-components)
@@ -29,7 +30,6 @@ A comprehensive Angular component library built with Angular 22+ featuring moder
   - [ThemeService](#themeservice)
   - [ToastService](#toastservice)
   - [ScrollService](#scrollservice)
-  - [TranslationService](#translationservice)
 - [Exported Types](#exported-types)
 - [Theming](#theming)
 - [Best Practices](#best-practices)
@@ -51,7 +51,7 @@ Helix is a production-ready design system that provides:
 - **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
+- **i18n Support** - Every visible string is a configurable default, with a French preset included
 - **Responsive Design** - Mobile-first approach with comprehensive breakpoint system
 - **Modern Architecture** - Built with Angular 22 standalone components and signals
 
@@ -72,7 +72,6 @@ Before installing Helix, ensure your development environment meets these require
   "@angular/common": "^22.0.0",
   "@angular/core": "^22.0.0",
   "@angular/forms": "^22.0.0",
-  "@ngx-translate/core": "^15.0.0",
   "rxjs": "^7.8.0"
 }
 ```
@@ -82,9 +81,12 @@ Before installing Helix, ensure your development environment meets these require
 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
 
+The library has no i18n dependency. Every string it renders is a configurable default —
+see [Internationalization](#internationalization) — so you translate it with whatever your
+application already uses, or with nothing at all.
+
 ## Installation
 
 Install the package:
@@ -96,7 +98,7 @@ npm install ps-helix
 All peer dependencies should be automatically installed. If not, install them manually:
 
 ```bash
-npm install @angular/common@^22.0.0 @angular/core@^22.0.0 @angular/forms@^22.0.0 @ngx-translate/core@^15.0.0 rxjs@^7.8.0
+npm install @angular/common@^22.0.0 @angular/core@^22.0.0 @angular/forms@^22.0.0 rxjs@^7.8.0
 ```
 
 ### Verify Installation
@@ -106,7 +108,7 @@ After installation, verify that ps-helix is in your `package.json`:
 ```json
 {
   "dependencies": {
-    "ps-helix": "^6.2.3"
+    "ps-helix": "^7.0.0"
   }
 }
 ```
@@ -121,14 +123,21 @@ In your main `styles.css` file, import the Helix stylesheet:
 @import 'ps-helix/styles.css';
 ```
 
-This single import includes:
-- CSS Reset (normalize styles across browsers)
+This import includes:
 - 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 management styles
+- Utility classes and the responsive system
+- Accessibility guarantees (forced-colors focus fallback, reduced-motion guard) and the
+  modal scroll lock — these always ship, whatever else you opt into
+
+**It does not include a CSS reset or page-level styling since 7.0.0.** Importing a
+component library used to also zero every margin and padding in your application, strip
+your list markers and paint a gradient on your `<body>`. If you want that — typically an
+application with no reset of its own — import the bundle instead:
+
+```css
+@import 'ps-helix/styles-full.css';   /* styles.css + reset.css + global.css */
+```
 
 ### Step 2: Configure Phosphor Icons
 
@@ -167,7 +176,7 @@ import { PshButtonComponent } from 'ps-helix';
   imports: [PshButtonComponent],
   template: `
     <psh-button
-      variant="primary"
+      color="primary"
       size="medium"
       (clicked)="handleClick()">
       Click Me
@@ -221,8 +230,8 @@ import { PshButtonComponent, PshCardComponent, PshAlertComponent } from 'ps-heli
   template: `
     <psh-card>
       <h2>Helix Design System</h2>
-      <psh-alert type="success" message="Installation successful!" />
-      <psh-button variant="primary">Test Button</psh-button>
+      <psh-alert color="success" message="Installation successful!" />
+      <psh-button color="primary">Test Button</psh-button>
     </psh-card>
   `
 })
@@ -231,6 +240,43 @@ export class TestComponent {}
 
 ## Configuration
 
+### `provideHelix()`
+
+One call sets the theme and every component default. Full list of the 201 settable defaults:
+[CONFIGURATION.md](./CONFIGURATION.md).
+
+```typescript
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideHelix } from 'ps-helix';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideHelix({
+      theme: { targetContrast: 'AAA', customerContext: BrandService },
+      components: {
+        button: { size: 'large', appearance: 'outline' },
+        modal: { dismissLabel: 'Fermer', confirmLabel: 'Valider', cancelLabel: 'Annuler' },
+        toast: { position: 'bottom-right', duration: 3000 },
+      },
+    }),
+  ],
+});
+```
+
+A partial override stays partial — `{ button: { size: 'large' } }` leaves the button's colour
+and appearance where they were — and an attribute written on an element always wins over the
+configuration.
+
+`provideHelixTheme()`, `provideHelixComponentDefaults()` and `provideHelixToast()` cover one
+part each, and every token is exported by name for a component-level override:
+
+```typescript
+import { BUTTON_CONFIG } from 'ps-helix';
+
+@Component({ providers: [{ provide: BUTTON_CONFIG, useValue: { size: 'small' } }] })
+export class ToolbarComponent {}
+```
+
 ### Global Styles
 
 The design system provides a comprehensive set of CSS custom properties (CSS variables) that you can use in your own styles:
@@ -238,12 +284,12 @@ The design system provides a comprehensive set of CSS custom properties (CSS var
 ```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);
+  padding: var(--psh-spacing-md);
+  margin-bottom: var(--psh-spacing-lg);
+  background: var(--psh-surface-card);
+  color: var(--psh-text-color);
+  border-radius: var(--psh-radius-lg);
+  box-shadow: var(--psh-shadow-md);
 }
 ```
 
@@ -301,67 +347,64 @@ export class AppComponent {
 
 For complete theming documentation including custom brand colors, see [THEME.md](./THEME.md).
 
-### Translation Service
+### Internationalization
 
-Configure internationalization with ngx-translate:
+Every string the library renders — placeholders, button labels, `aria-label`s — is a
+configurable default. There is no i18n dependency: you set them from whatever your
+application already uses.
+
+The defaults are English. `PSH_FRENCH_DEFAULTS` puts all 46 of them back into French:
 
 ```typescript
-// 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');
-}
+import { provideHelix, PSH_FRENCH_DEFAULTS } from 'ps-helix';
 
 bootstrapApplication(AppComponent, {
-  providers: [
-    provideHttpClient(),
-    ...TranslateModule.forRoot({
-      defaultLanguage: 'en',
-      loader: {
-        provide: TranslateLoader,
-        useFactory: HttpLoaderFactory,
-        deps: [HttpClient]
-      }
-    }).providers || []
-  ]
-}).then(ref => {
-  const translateService = ref.injector.get(TranslateService);
-  translateService.use('en');
+  providers: [provideHelix({ components: PSH_FRENCH_DEFAULTS })],
 });
 ```
 
-#### Using TranslationService in Components
+Merge your own on top rather than replacing it:
 
 ```typescript
-import { Component, inject } from '@angular/core';
-import { TranslationService } from 'ps-helix';
+provideHelix({
+  components: {
+    ...PSH_FRENCH_DEFAULTS,
+    modal: { ...PSH_FRENCH_DEFAULTS.modal, confirmLabel: 'Envoyer' },
+  },
+})
+```
 
-@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>
-  `
+#### Another language, or a language that changes
+
+Pass the strings from your own catalogue. A **function** is re-read whenever it changes, so a
+language switcher updates the labels of components that are already on screen:
+
+```typescript
+const t = inject(TranslateService);   // ngx-translate, transloco, $localize, your own…
+
+provideHelix({
+  components: {
+    select: { placeholder: () => t.instant('psh.select.placeholder') },
+    modal: { dismissLabel: () => t.instant('psh.modal.close') },
+  },
 })
-export class ExampleComponent {
-  private translationService = inject(TranslationService);
+```
 
-  changeLanguage(event: Event) {
-    const lang = (event.target as HTMLSelectElement).value;
-    this.translationService.setLanguage(lang);
-  }
-}
+A plain string is read once, when a component is built — right for a language fixed at
+startup, and the common case. A function is read every time the value is needed, so anything
+it reads that is a signal makes the label follow.
+
+Per element, bind the input as you would any other:
+
+```html
+<psh-select [placeholder]="'psh.select.placeholder' | translate" />
 ```
 
+An input always wins over the configuration.
+
+The full list of configurable strings is in [CONFIGURATION.md](./CONFIGURATION.md).
+
 ### Scroll Service
 
 The `ScrollService` provides utilities for scroll management:
@@ -414,7 +457,7 @@ import {
   template: `
     <psh-card>
       <psh-input label="Email" />
-      <psh-button variant="primary">Submit</psh-button>
+      <psh-button color="primary">Submit</psh-button>
     </psh-card>
   `
 })
@@ -671,42 +714,6 @@ export class MyComponent {
 }
 ```
 
-### TranslationService
-
-Wrapper service for ngx-translate functionality.
-
-**Methods:**
-- `setLanguage(lang: string)` - Change application language
-- `getTranslation(key: string)` - Get translation for a key
-- `instant(key: string)` - Get instant translation (synchronous)
-
-**Example:**
-
-```typescript
-import { Component, inject } from '@angular/core';
-import { TranslationService } from 'ps-helix';
-
-@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);
-
-  changeLanguage(event: Event) {
-    const selectedLang = (event.target as HTMLSelectElement).value;
-    this.translationService.setLanguage(selectedLang);
-  }
-}
-```
-
 ## Exported Types
 
 All component types and enums are exported for type-safe development:
@@ -855,33 +862,33 @@ Customize to match your brand identity using the injection token pattern. See th
 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`
+- `--psh-primary-color`
+- `--psh-primary-color-light`
+- `--psh-primary-color-lighter`
+- `--psh-primary-color-dark`
+- `--psh-primary-color-darker`
+- `--psh-primary-color-text`
+- `--psh-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`
+- `--psh-secondary-color`
+- `--psh-secondary-color-light`
+- `--psh-secondary-color-lighter`
+- `--psh-secondary-color-dark`
+- `--psh-secondary-color-darker`
+- `--psh-secondary-color-text`
+- `--psh-secondary-color-rgb`
 
 ### Using Custom Variables
 
 ```css
 .my-button {
-  background: var(--primary-color);
-  color: var(--primary-color-text);
+  background: var(--psh-primary-color);
+  color: var(--psh-primary-color-text);
 }
 
 .my-button:hover {
-  background: var(--primary-color-light);
+  background: var(--psh-primary-color-light);
 }
 ```
 
@@ -1119,7 +1126,7 @@ See [THEME.md](./THEME.md) for complete theming documentation.
 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
+4. Check that the strings you expect are set through `provideHelix` — see CONFIGURATION.md
 
 ## Browser Support
 
@@ -1178,11 +1185,10 @@ Copyright (c) 2025 PACK Solutions
 - **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**: 6.2.3
+**Version**: 7.0.0
 **Built with**: Angular 22.0.0, TypeScript 6.0.0, Phosphor Icons 2.0.3
 **Author**: Fabrice PEREZ | Design Engineer at PACK Solutions
 **Last Updated**: January 2026

package/THEME.md

@@ -194,8 +194,8 @@ When `applyCustomerTheme()` runs, each brand color is evaluated against the curr
 
 - 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 adjusted color is written into `--psh-customer-primary-color` / `--psh-customer-secondary-color` and consumed by every UI component.
+- The original, unmodified brand color is written into `--psh-customer-primary-color-source` / `--psh-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
@@ -230,29 +230,39 @@ Hue and chroma are preserved so the color palette stays perceptually consistent.
 
 ## Available CSS Variables
 
+> **Every token is namespaced `--psh-*` since 7.0.0.** The complete, always-current list —
+> 398 tokens with their light and dark values — lives in **[TOKENS.md](./TOKENS.md)**,
+> generated from the stylesheets so it cannot drift. This page covers only the theming
+> hooks; `TOKENS.md` covers the whole surface.
+>
+> Migrating from an earlier version? Import `ps-helix/src/lib/styles/compat.css` to keep
+> the old unprefixed names working while you move over, then drop it. The legacy
+> `--customer-*-color*` hooks keep working with no shim at all: both themes read the
+> namespaced name first and fall back to the old one.
+
 Once configured, `ThemeService` writes the following CSS variables on `:root`:
 
 ### Primary Color Variables
 
-- `--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
+- `--psh-customer-primary-color` - Accessibility-adjusted primary color (used by components)
+- `--psh-customer-primary-color-source` - Original brand color, unmodified (for decorative use only)
+- `--psh-customer-primary-color-light` - OKLCH-derived lighter variant
+- `--psh-customer-primary-color-lighter` - OKLCH-derived extra light variant
+- `--psh-customer-primary-color-dark` - OKLCH-derived darker variant
+- `--psh-customer-primary-color-darker` - OKLCH-derived extra dark variant
+- `--psh-customer-primary-color-text` - Readable text color (black or white) picked via WCAG contrast against the adjusted primary
+- `--psh-customer-primary-color-rgb` - `r, g, b` triplet of the adjusted primary for `rgba()` usage
 
 ### Secondary Color Variables
 
-- `--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`
+- `--psh-customer-secondary-color`
+- `--psh-customer-secondary-color-source`
+- `--psh-customer-secondary-color-light`
+- `--psh-customer-secondary-color-lighter`
+- `--psh-customer-secondary-color-dark`
+- `--psh-customer-secondary-color-darker`
+- `--psh-customer-secondary-color-text`
+- `--psh-customer-secondary-color-rgb`
 
 ### Component Usage
 
@@ -260,22 +270,22 @@ Design system components consume the stable abstract variables, which fall back
 
 ```css
 /* 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);
+--psh-primary-color: var(--psh-customer-primary-color, #0B0191);
+--psh-primary-color-light: var(--psh-customer-primary-color-light, #0F02C4);
 ```
 
 ### Using in Your Custom Styles
 
-Use the abstract variables (`--primary-color`, `--secondary-color`, ...) in your own components so you automatically inherit the accessibility-adjusted palette:
+Use the abstract variables (`--psh-primary-color`, `--psh-secondary-color`, ...) in your own components so you automatically inherit the accessibility-adjusted palette:
 
 ```css
 .my-custom-button {
-  background-color: var(--primary-color);
-  color: var(--primary-color-text);
+  background-color: var(--psh-primary-color);
+  color: var(--psh-primary-color-text);
 }
 
 .my-custom-button:hover {
-  background-color: var(--primary-color-light);
+  background-color: var(--psh-primary-color-light);
 }
 ```
 
@@ -283,7 +293,7 @@ For decorative brand elements that must match the literal brand color (e.g. a lo
 
 ```css
 .brand-logo-surface {
-  background-color: var(--customer-primary-color-source);
+  background-color: var(--psh-customer-primary-color-source);
 }
 ```
 
@@ -418,7 +428,7 @@ export class AppThemeContextService {
 
 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`.
+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('--psh-customer-primary-color')` and the original via `--psh-customer-primary-color-source`.
 
 ### Default colors showing instead of custom colors
 
@@ -436,7 +446,7 @@ export class AppThemeContextService {
 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`, ...).
+4. For decorative brand surfaces, use `--customer-*-color-source`. For every other UI use case, use the abstract variables (`--psh-primary-color`, ...).
 5. Persist user preferences in `localStorage` when relevant.
 6. Document brand color choices alongside your app's style guide.