Documentation

Appearance

Composants dataviz — HGauge, HSparkline, HWaterfall ​

Spécification technique pour intégration au design-system Heriade (Vue 3, <script setup>), dans le prolongement des composants existants (HButton, HModal, HCard, HInput, TreePicker, FilterGear).

0. Principe commun aux trois composants ​

  • Chaque composant est autonome, sans dépendance à une logique métier spécifique (pas de référence directe à "TO" ou "EHPAD" dans le composant lui-même) — il reçoit des données déjà calculées en props.
  • Couleur de marque : variable CSS --primary-500 (base #573A7D, échelle --primary-25 à --primary-900 déjà définie dans le thème) ; rouge/vert/orange réservés exclusivement à la sémantique (favorable/défavorable/alerte), jamais utilisés comme couleur décorative.
  • Chaque composant doit gérer explicitement l'état "donnée manquante" (ex. référentiel non saisi) — jamais un 0 ou un graphique vide silencieux.
  • Accessibilité : role="img" + aria-label descriptif sur les éléments graphiques (canvas, svg).
  • Se conforme au pattern de KPI générique défini dans docs/spec-bibliotheque-kpi.md : ces composants sont les visuels par défaut associés aux KpiDefinition.

1. HGauge — jauge de taux (remplissage/rendement) ​

Usage ​

Visuel par défaut pour tout KPI de type pattern: "remplissage_rendement" (TO, TO permanent/temporaire, TRS, taux d'avancement...).

Props ​

ts
interface HGaugeProps {
  value: number              // valeur actuelle, en % (0-100), ou null si donnée manquante
  target?: number             // objectif optionnel, affiché en label sous la jauge
  seuils?: {                  // bornes de coloration
    bon: number                // ex: 90 → vert au-dessus
    alerte: number              // ex: 75 → orange entre alerte et bon, rouge en-dessous
  }
  label: string                // nom métier du KPI, ex: "Taux d'occupation"
  size?: 'sm' | 'md' | 'lg'    // par défaut 'md'
}

Comportement ​

  • Arc de jauge (demi-cercle), couleur dynamique selon la position de value par rapport aux seuils.
  • Si value est null : afficher un état neutre explicite ("Donnée non disponible"), jamais un arc à 0%.
  • Si target est fourni, afficher un repère visuel sur l'arc (trait ou marqueur) en plus du label texte.
  • Couleurs de seuil réutilisées du composant Écarts existant si possible, pour cohérence visuelle avec l'écran CDG déjà en place.

Intégration ​

  • S'insère dans une HCard pour les dashboards (Synthèse, TDB).
  • Consomme directement le résultat de calcul d'un KpiDefinition (voir spec bibliothèque KPI, section 5 moteur de calcul) — aucune logique de calcul dans le composant.

2. HSparkline — mini-courbe de tendance inline ​

Usage ​

Accompagner un chiffre clé (montant, effectif, KPI) d'une tendance visuelle sur N périodes, sans occuper l'espace d'un graphique complet. Utilisable dans les tableaux (une ligne = un compte/segment) et dans les cartes KPI.

Props ​

ts
interface HSparklineProps {
  data: number[]               // série de valeurs, ordre chronologique
  labels?: string[]             // labels de période (mois), optionnel, pour tooltip uniquement
  trend?: 'up' | 'down' | 'neutral'  // calculé automatiquement si non fourni (comparaison premier/dernier point)
  height?: number                // par défaut 40px
  showFill?: boolean             // aire sous la courbe, par défaut true
}

Comportement ​

  • Pas d'axes visibles, pas de grille — c'est une indication de tendance, pas un graphique d'analyse.
  • Couleur de la ligne : vert/rouge si un sens métier favorable/défavorable est déterminable (ex. CA en hausse = positif), sinon couleur de marque neutre (violet/magenta) si le sens n'a pas de connotation univoque (ex. nombre de segments actifs).
  • Tooltip au survol si labels fourni, sinon pas d'interaction (composant purement visuel).
  • Si data contient moins de 2 points : ne pas afficher de sparkline, afficher un tiret ou "—".

Intégration ​

  • Utilisable directement dans une cellule de tableau (HTable existant, si applicable) à côté d'une valeur agrégée.
  • Utilisable dans une carte KPI à côté d'un montant (cf. maquette validée en amont).

3. HWaterfall — cascade / graphique en escalier ​

Usage ​

Remplacer ou compléter la présentation en tableau de la cascade P&L (CA → charges variables → marge brute → charges fixes → résultat), déjà existante dans l'écran Vues.

Props ​

ts
interface HWaterfallStep {
  label: string                 // nom de l'étape, ex: "Charges variables"
  value: number                  // delta (positif ou négatif) ; les totaux (CA, marge brute, résultat) passent value = montant absolu et isTotal = true
  isTotal?: boolean              // true pour CA, marge brute, résultat — barre pleine depuis 0
}

interface HWaterfallProps {
  steps: HWaterfallStep[]
  unit?: '€' | 'k€' | 'M€'       // réutilise la logique de format.ts existante
  height?: number
}

Comportement ​

  • Barres flottantes pour les deltas (départ = cumul précédent, arrivée = cumul + delta), barres pleines depuis 0 pour les totaux (isTotal: true).
  • Couleur : bleu de marque pour les totaux, vert pour delta positif, rouge pour delta négatif — jamais l'inverse (rouge = toujours défavorable, cohérence avec HGauge et l'écran Écarts).
  • Toutes les étapes affichées sans troncature d'étiquette (rotation des labels si nécessaire), car en nombre limité (5-8 étapes typiquement pour une cascade P&L).
  • Tooltip par barre avec la valeur exacte formatée selon unit.

Intégration ​

  • Remplace ou complète le tableau de cascade existant dans l'écran Vues — recommandé de garder le tableau en option d'affichage (bascule tableau/graphique) plutôt que de le supprimer, certains DAF préfèrent le detail chiffré.
  • Réutilise format.ts pour la mise en forme des unités (cohérence avec le reste de l'application).

Modes de waterfall (mise à jour) ​

Le composant HWaterfall reste inchangé (il consomme des steps déjà calculés). Le calcul des étapes, lui, se décline en deux modes, choisis à la création d'un graphique de bibliothèque (onglet Graphique de l'éditeur de Vue, type « Waterfall ») :

  1. cascade_hierarchique (existant, à conserver tel quel) — décomposition d'un total sur un seul scénario. On déroule la chaîne à enfant unique jusqu'au premier niveau à composants multiples ; chaque composant est un delta et le nœud parent une barre de total (P&L : CA → charges → résultat). C'est le mode de la bascule Cascade déjà présente sur les Vues.

  2. pont_comparatif (nouveau) — pont entre deux scénarios/phases, choisis via deux sélecteurs origine et destination (ex. Budget → Réel, ou N-1 → N). Structure des barres :

    • barre de borne = total origine (isTotal),
    • une barre intermédiaire par poste = contribution du poste à l'écart, soit valeur_destination(poste) − valeur_origine(poste) (et non un cumul hiérarchique),
    • barre de borne = total destination (isTotal).

    Les deltas somment de la borne origine à la borne destination dès lors que les postes partitionnent le total. Les mesures comparables (Budget / Réel / N-1) dérivent des clés de valeur des nœuds pivot selon la période de la vue (cumul / mois).

4. Phasage suggéré ​

  1. HGauge en premier : dépendance directe de la bibliothèque KPI (spec déjà écrite), impact démo le plus fort pour le pattern remplissage/rendement.
  2. HWaterfall ensuite : remplace un affichage déjà existant (cascade P&L), périmètre bien délimité, fort impact visuel en démo commerciale.
  3. HSparkline en dernier : plus transverse (utilisable dans de nombreux écrans) mais moins urgent, peut s'ajouter progressivement écran par écran une fois les deux premiers validés.

5. Point de vigilance technique ​

Le rendu graphique (Chart.js suggéré pour cohérence avec l'écosystème Vue, ou SVG natif pour HGauge qui est simple) doit rester compatible avec l'export Excel stylé déjà existant — vérifier si une cellule Excel doit reproduire une version simplifiée (ex. barre de progression conditionnelle) de ces visuels, ou si l'export reste au format tableau classique pour ces cas.