Skip to content

PACK-Solutions/ps-helix

BranchesTags

Repository files navigation

Helix Design System

Bibliothèque de composants Angular moderne et complète avec 28 composants standalone, système de thèmes, internationalisation et accessibilité optimale.

Version License Angular TypeScript

Table des matières

Vue d'ensemble

Helix est un design system professionnel construit avec Angular 21+, offrant une collection complète de composants réutilisables pour créer des applications web modernes et accessibles.

Auteur

PACK Solutions

Points clés

  • 28 composants standalone prêts à l'emploi
  • Architecture basée sur les signals Angular
  • Conformité WCAG 2.1 AA pour l'accessibilité
  • Support complet TypeScript en mode strict
  • Système de thèmes personnalisable (clair/sombre)
  • Internationalisation intégrée avec ngx-translate
  • 6000+ icônes Phosphor avec variantes de poids
  • Design responsive mobile-first
  • Aucun module NgModule requis

Structure du projet

Le projet est organisé en deux parties principales :

helix-design-system/
├── projects/ps-helix/          # Bibliothèque de composants (npm package)
│   ├── src/
│   │   ├── lib/
│   │   │   ├── components/     # 28 composants standalone
│   │   │   ├── services/       # Services (Theme, Translation, Toast, Scroll)
│   │   │   └── styles/         # Tokens CSS, thèmes et utilitaires
│   │   └── public-api.ts       # Exports publics de la bibliothèque
│   ├── package.json            # Configuration npm de la lib
│   ├── README.md               # Documentation de la bibliothèque
│   └── THEME.md                # Guide de personnalisation des thèmes
│
└── src/                        # Application de démonstration
    ├── app/
    │   ├── demo/               # Pages de démo pour chaque composant
    │   │   ├── components/     # Composants de démo réutilisables
    │   │   ├── layout/         # Layouts de l'app de démo
    │   │   ├── pages/          # Pages pour chaque composant
    │   │   ├── services/       # Services de navigation et raccourcis
    │   │   └── shared/         # Composants partagés (code snippet, search)
    │   ├── home/               # Page d'accueil
    │   └── i18n/               # Traductions pour la démo
    └── index.html

Bibliothèque (ps-helix)

La bibliothèque contient tous les composants, services et styles réutilisables. Elle est publiée sur npm et peut être installée dans n'importe quel projet Angular.

Application de démonstration

L'application de démonstration présente tous les composants avec :

  • Exemples d'utilisation interactifs
  • Documentation de chaque composant
  • Snippets de code copiables
  • Navigation entre composants
  • Recherche rapide avec raccourcis clavier (Ctrl+K)
  • Support multilingue (EN/FR/ES/DE)
  • Toggle thème clair/sombre

Fonctionnalités principales

Composants (28)

  • Formulaires : Button, Input, Checkbox, Radio, Select, Switch
  • Layout : Card, Modal, Sidebar, Collapse, Tabs, TabBar
  • Feedback : Alert, Toast, Spinloader, Progressbar, Tooltip
  • Données : Table, Badge, Tag, Avatar, StatCard, InfoCard, HorizontalCard
  • Navigation : Menu, Pagination, Stepper, Dropdown

Services

  • ThemeService : Gestion des thèmes clair/sombre et couleurs personnalisées
  • ToastService : Notifications toast avec file d'attente
  • TranslationService : Wrapper pour ngx-translate
  • ScrollService : Utilitaires de scroll et gestion du défilement

Design Tokens

  • Système d'espacement cohérent (8px base)
  • Palette de couleurs avec rampes complètes
  • Typographie responsive
  • Animations et transitions
  • Breakpoints responsive
  • Variables CSS personnalisables

Accessibilité

  • Navigation clavier complète
  • Support lecteurs d'écran
  • Gestion du focus visible
  • Rôles ARIA appropriés
  • Contraste de couleurs conforme
  • Labels et descriptions accessibles

Prérequis

Versions requises

  • Node.js : 18.x ou supérieur
  • npm : 9.x ou supérieur
  • Angular : 21.0.3 ou supérieur
  • Angular CLI : 21.0.3 ou supérieur
  • TypeScript : 5.9.0 ou supérieur

Dépendances peer

{
  "@angular/common": "^21.0.3",
  "@angular/core": "^21.0.3",
  "@angular/forms": "^21.0.3",
  "@ngx-translate/core": "^15.0.0",
  "rxjs": "^7.8.0"
}

Dépendances incluses

  • @phosphor-icons/web : 2.0.3 - Bibliothèque d'icônes
  • date-fns : ^3.3.1 - Utilitaires de dates
  • tslib : ^2.6.0 - Runtime TypeScript

Installation et développement

Cloner le projet

git clone <repository-url>
cd helix-design-system

Installer les dépendances

npm install

Lancer l'application de démonstration

npm run dev

L'application sera accessible sur http://localhost:4200

Construire la bibliothèque

npm run build:lib

La bibliothèque sera générée dans dist/ps-helix/

Mode développement de la bibliothèque

npm run watch:lib

Reconstruction automatique à chaque modification

Publier la bibliothèque

npm run publish:lib

Publie la bibliothèque sur npm (nécessite les droits d'accès)

Architecture technique

Composants Standalone

Tous les composants sont standalone (pas de NgModules) :

import { Component } from '@angular/core';
import { PshButtonComponent, PshCardComponent } from 'ps-helix';

@Component({
  selector: 'app-example',
  imports: [PshButtonComponent, PshCardComponent],
  template: `
    <psh-card>
      <psh-button variant="primary">Action</psh-button>
    </psh-card>
  `
})
export class ExampleComponent {}

Réactivité par Signals

Utilisation des signals Angular pour une performance optimale :

import { Component, signal } from '@angular/core';
import { PshModalComponent } from 'ps-helix';

@Component({
  selector: 'app-example',
  imports: [PshModalComponent],
  template: `
    <button (click)="isOpen.set(true)">Ouvrir</button>
    <psh-modal [(open)]="isOpen" title="Confirmation">
      <p>Êtes-vous sûr ?</p>
    </psh-modal>
  `
})
export class ExampleComponent {
  isOpen = signal(false);
}

Type Safety

Tous les types sont exportés pour un développement type-safe :

import { ButtonVariant, ButtonSize, AlertType } from 'ps-helix';

const variant: ButtonVariant = 'primary';  // Type-safe
const size: ButtonSize = 'medium';         // Type-safe
const alertType: AlertType = 'success';    // Type-safe

Signal Forms et Reactive Forms

Les composants de formulaire (input, checkbox, select, switch) supportent nativement les Signal Forms d'Angular 21 via les interfaces FormValueControl et FormCheckboxControl, tout en conservant la rétrocompatibilité avec les Reactive Forms classiques via ControlValueAccessor.

Trois modes d'utilisation sont supportés :

// 1. Signal Forms (recommandé pour les nouveaux projets)
import { signal } from '@angular/core';
import { form, FormField, required, email } from '@angular/forms/signals';

model = signal({ email: '', password: '' });
loginForm = form(this.model, (p) => {
  required(p.email);
  email(p.email);
});

// Template : <psh-input [formField]="loginForm.email" />

// 2. Reactive Forms (rétrocompatible)
// Template : <psh-input [formControl]="emailControl" />

// 3. Two-way binding
// Template : <psh-input [(value)]="myValue" />

Injection de dépendances moderne

Utilisation de inject() au lieu du constructeur :

import { Component, inject } from '@angular/core';
import { ThemeService, ToastService } from 'ps-helix';

@Component({
  selector: 'app-example',
  template: `<button (click)="afficherToast()">Toast</button>`
})
export class ExampleComponent {
  private themeService = inject(ThemeService);
  private toastService = inject(ToastService);

  afficherToast() {
    this.toastService.success('Message envoyé !');
  }
}

Zoneless Change Detection

Angular 21 introduit la détection de changement zoneless par défaut, ce qui représente une amélioration majeure des performances. Cette application utilise provideZonelessChangeDetection() au lieu de zone.js pour la détection des changements.

Avantages :

  • Performance améliorée : Pas de surcharge liée à zone.js qui intercepte toutes les opérations asynchrones
  • Bundle plus léger : Réduction de la taille du bundle en éliminant zone.js de la production
  • Modèle mental simplifié : La détection de changement est déclenchée explicitement via les signals et les événements Angular
  • Meilleure prévisibilité : Contrôle plus fin sur le moment où la détection de changement se produit

Configuration :

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideZonelessChangeDetection } from '@angular/core';
import { AppComponent } from './app/app.component';

bootstrapApplication(AppComponent, {
  providers: [
    provideZonelessChangeDetection()
  ]
});

Note : zone.js reste dans les devDependencies uniquement pour les tests unitaires avec Jest, mais n'est pas utilisé en production.

Composants disponibles

Composants de formulaire (6)

PshButtonComponent

Bouton versatile avec variantes, tailles et états multiples.

<psh-button
  variant="primary"
  size="medium"
  [disabled]="false"
  (clicked)="handleClick()">
  Cliquez ici
</psh-button>

PshInputComponent

Champ de saisie avec validation, messages d'erreur et intégration FormControl.

<psh-input
  label="Email"
  type="email"
  [formControl]="emailControl"
  [required]="true">
</psh-input>

PshCheckboxComponent

Case à cocher avec états personnalisables.

PshRadioComponent

Bouton radio pour sélection unique.

PshSelectComponent

Menu déroulant avec recherche, filtrage et rendu personnalisé.

PshSwitchComponent

Interrupteur bascule avec états on/off.

Composants de layout (6)

PshCardComponent

Conteneur de contenu flexible avec header, body et footer.

PshModalComponent

Dialogue modal avec overlay et navigation clavier.

PshSidebarComponent

Barre latérale pliable avec comportement responsive.

PshCollapseComponent

Section de contenu extensible/réductible avec animation.

PshTabsComponent + PshTabComponent

Organisation de contenu par onglets avec navigation clavier.

PshTabBarComponent

Barre de navigation inférieure pour applications mobile-first.

Composants de feedback (5)

PshAlertComponent

Messages d'alerte avec niveaux de gravité.

<psh-alert
  type="success"
  message="Opération réussie !">
</psh-alert>

PshToastComponent + ToastService

Système de notifications toast avec gestion de file.

PshSpinloaderComponent

Spinner de chargement avec différentes tailles.

PshProgressbarComponent

Indicateur de progression avec affichage du pourcentage.

PshTooltipComponent

Info-bulles contextuelles avec positions multiples.

Composants d'affichage de données (7)

PshTableComponent

Tableau de données avec tri, pagination et rendu personnalisé.

PshBadgeComponent

Badges et indicateurs de statut avec couleurs variées.

PshTagComponent

Tags supprimables pour labels et filtres.

PshAvatarComponent

Avatar utilisateur avec image, initiales ou icône de secours.

PshStatCardComponent

Carte statistique pour tableaux de bord.

PshInfoCardComponent

Carte d'information avec icône et contenu.

PshHorizontalCardComponent

Composant de carte à disposition horizontale.

Composants de navigation (4)

PshMenuComponent

Menu déroulant avec éléments imbriqués.

PshPaginationComponent

Contrôles de pagination avec numéros de page.

PshStepperComponent + PshStepComponent

Navigation wizard étape par étape avec validation.

PshDropdownComponent

Conteneur de déclencheur et contenu déroulant.

Services

ThemeService

Gestion des thèmes d'application et couleurs de marque personnalisées.

Méthodes :

  • setDarkTheme(isDark: boolean) - Définir le mode thème
  • toggleTheme() - Basculer entre clair et sombre
  • updateTheme(name: 'light' | 'dark') - Mettre à jour le thème par nom
  • applyInsurerTheme() - Appliquer les couleurs de marque personnalisées

Signals calculés :

  • themeName() - Retourne le nom du thème actuel
  • isDarkTheme() - Retourne un booléen pour le mode sombre
  • themeInfo() - Retourne les informations complètes du thème

Exemple :

import { Component, inject } from '@angular/core';
import { ThemeService } from 'ps-helix';

@Component({
  template: `
    <button (click)="themeService.toggleTheme()">
      Thème : {{ themeService.themeName() }}
    </button>
  `
})
export class ExempleComponent {
  themeService = inject(ThemeService);
}

ToastService

Affichage de messages de notification temporaires.

Méthodes :

  • success(message: string, options?) - Toast de succès
  • error(message: string, options?) - Toast d'erreur
  • warning(message: string, options?) - Toast d'avertissement
  • info(message: string, options?) - Toast d'information

Options :

  • duration?: number - Durée d'affichage en millisecondes (défaut: 3000)
  • position?: ToastPosition - Position du toast

Exemple :

import { Component, inject } from '@angular/core';
import { ToastService } from 'ps-helix';

@Component({
  template: `<button (click)="sauvegarder()">Sauvegarder</button>`
})
export class ExempleComponent {
  private toastService = inject(ToastService);

  sauvegarder() {
    this.toastService.success('Données sauvegardées avec succès !');
  }
}

ScrollService

Service utilitaire pour la gestion du scroll.

Méthodes :

  • scrollToTop() - Scroll vers le haut de page
  • scrollToElement(selector: string) - Scroll vers un élément spécifique
  • disableScroll() - Désactiver le scroll (utile pour les modales)
  • enableScroll() - Réactiver le scroll

TranslationService

Service wrapper pour la fonctionnalité ngx-translate.

Méthodes :

  • setLanguage(lang: string) - Changer la langue de l'application
  • getTranslation(key: string) - Obtenir une traduction
  • instant(key: string) - Obtenir une traduction instantanée (synchrone)

Système de thèmes

Couleurs par défaut

  • Couleur primaire : #0F02C4 (Bleu profond)
  • Couleur secondaire : #7B3AEC (Violet)

Personnalisation des couleurs

Le système utilise un système d'injection token pour la personnalisation :

// 1. Créer un service de contexte thème
import { Injectable, signal } from '@angular/core';
import { InsurerContextService } from 'ps-helix';

@Injectable({
  providedIn: 'root'
})
export class AppThemeContextService implements InsurerContextService {
  private primaryColorSignal = signal('#FF0000');
  private secondaryColorSignal = signal('#00AA00');

  primaryColor = this.primaryColorSignal.asReadonly();
  secondaryColor = this.secondaryColorSignal.asReadonly();
}

// 2. Fournir le service avec le token
import { INSURER_CONTEXT_SERVICE } from 'ps-helix';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: INSURER_CONTEXT_SERVICE,
      useExisting: AppThemeContextService
    }
  ]
};

Variables CSS disponibles

Le système génère automatiquement des variables CSS :

Couleur primaire :

  • --primary-color
  • --primary-color-light
  • --primary-color-lighter
  • --primary-color-dark
  • --primary-color-darker
  • --primary-color-text
  • --primary-color-rgb

Couleur secondaire :

  • --secondary-color
  • --secondary-color-light
  • --secondary-color-lighter
  • --secondary-color-dark
  • --secondary-color-darker
  • --secondary-color-text
  • --secondary-color-rgb

Pour plus de détails, consultez THEME.md

Internationalisation

Configuration

Le système utilise ngx-translate pour l'internationalisation :

// main.ts
import { TranslateModule } from '@ngx-translate/core';

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(),
    ...TranslateModule.forRoot({
      defaultLanguage: 'fr',
      loader: {
        provide: TranslateLoader,
        useFactory: HttpLoaderFactory,
        deps: [HttpClient]
      }
    }).providers || []
  ]
});

Utilisation

import { Component, inject } from '@angular/core';
import { TranslationService } from 'ps-helix';

@Component({
  template: `
    <select (change)="changerLangue($event)">
      <option value="fr">Français</option>
      <option value="en">English</option>
      <option value="es">Español</option>
    </select>
  `
})
export class SelecteurLangueComponent {
  private translationService = inject(TranslationService);

  changerLangue(event: Event) {
    const langue = (event.target as HTMLSelectElement).value;
    this.translationService.setLanguage(langue);
  }
}

Langues supportées dans la démo

  • Français (fr)
  • Anglais (en)
  • Espagnol (es)
  • Allemand (de)

Scripts disponibles

Développement

npm run dev         # Lancer l'application de démonstration
npm run build       # Construire l'application de démonstration
npm test            # Lancer les tests

Bibliothèque

npm run build:lib     # Construire la bibliothèque
npm run watch:lib     # Mode watch (reconstruction auto)
npm run publish:lib   # Publier sur npm

Documentation

Documentation de la bibliothèque

Documentation des composants

Chaque composant possède sa propre documentation dans son dossier :

  • Fichiers .md dans projects/ps-helix/src/lib/components/[composant]/

Application de démonstration

L'application de démonstration est la meilleure source d'exemples :

  • Exemples interactifs pour chaque composant
  • Code source complet dans src/app/demo/pages/
  • Snippets de code copiables
  • Documentation visuelle

Ressources externes

Contribution

Les contributions sont les bienvenues ! Pour contribuer :

  1. Forkez le dépôt
  2. Créez une branche feature : git checkout -b feature/ma-feature
  3. Committez vos changements : git commit -am 'Ajout nouvelle feature'
  4. Poussez vers la branche : git push origin feature/ma-feature
  5. Soumettez une pull request

Guidelines de développement

  • Suivre le guide de style Angular
  • Utiliser TypeScript en mode strict
  • Écrire des tests pour les nouveaux composants
  • Documenter toutes les APIs publiques
  • Assurer la conformité accessibilité (WCAG 2.1 AA)
  • Garder les composants petits et focalisés
  • Utiliser les signals pour l'état réactif

Support navigateurs

Le design system supporte :

  • Chrome : 2 dernières versions
  • Firefox : 2 dernières versions
  • Safari : 2 dernières versions
  • Edge : 2 dernières versions
  • Mobile : iOS Safari 14+, Chrome Android dernière version

Note : Internet Explorer n'est pas supporté.

Licence

MIT License

Copyright (c) 2025 PACK Solutions

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Version : 4.1.1 Construit avec : Angular 21.0.3, TypeScript 5.9.0, Phosphor Icons 2.0.3 Auteur : Fabrice PEREZ | Product Designer chez PACK Solutions Dernière mise à jour : Janvier 2026

About

Helix Design System: A modern Angular component library providing a comprehensive set of UI components and utilities.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages