# Spécification – Cards Advance & Form Wizard ESTAIR > Basé sur `pages/cards/card-advance` et `forms/form-wizard-numbered` --- ## Partie 1 – Cards Advance ### Les 4 types observés sur la page La page `card-advance` présente un **catalogue de cards réutilisables**. Chaque type a une structure précise. --- #### Type A — Liste icônes colorées + valeur + % variation > Référence : **Monthly Campaign State** ``` ┌─ Titre ──────────────────────────────── ⋮ ─┐ │ Titre │ │ Sous-titre (ex: 38.4k Visitors) │ ├─────────────────────────────────────────────┤ │ [🟩 icône] Label 12 346 0.3% │ │ [🟦 icône] Label 8 734 2.1% │ │ [🟧 icône] Label 967 1.4% │ │ [🟣 icône] Label 345 8.5% │ │ [⬜ icône] Label 10 1.5% │ │ [🟥 icône] Label 86 0.8% │ └─────────────────────────────────────────────┘ ``` **Structure d'une ligne :** - Icône arrondie (fond coloré clair, icône colorée assortie, 36×36px) - Label (texte principal, 14px) - Valeur (nombre, aligné droite, 14px bold) - % variation (coloré : vert si positif, rouge si négatif, 13px) --- #### Type B — Liste logo + titre + sous-titre + progress bar + % > Référence : **Active Projects** ``` ┌─ Titre ──────────────────────────────── ⋮ ─┐ │ Titre │ │ Sous-titre (ex: Average 72% completed) │ ├─────────────────────────────────────────────┤ │ [Logo] Titre ████░░ 65% │ │ Sous-titre │ │ [Logo] Titre ██████ 86% │ │ Sous-titre │ └─────────────────────────────────────────────┘ ``` **Structure d'une ligne :** - Logo carré arrondi (icône app/brand, 38×38px) - Titre (bold, 14px) + sous-titre (gris, 12px) - Barre de progression colorée (couleur variable par ligne, hauteur 6px) - % (14px, aligné droite) --- #### Type C — Liste icône neutre + label + sous-label + valeur + badge % > Référence : **Source Visits** ``` ┌─ Titre ──────────────────────────────── ⋮ ─┐ │ Titre │ │ Sous-titre │ ├─────────────────────────────────────────────┤ │ [⬜ icône] Label 1.2k [+4.2%] │ │ Sous-label │ │ [⬜ icône] Label 31.5k [+8.2%] │ │ Sous-label │ └─────────────────────────────────────────────┘ ``` **Structure d'une ligne :** - Icône gris neutre (fond gris très clair, 36×36px) - Label (bold, 14px) + sous-label (gris, 12px) - Valeur (14px, aligné droite) - Badge % (fond coloré clair, texte coloré : vert ou rouge) --- #### Type D — Liste avatar/drapeau + montant + label + flèche + % > Référence : **Sales by Countries** ``` ┌─ Titre ──────────────────────────────── ⋮ ─┐ │ Titre │ │ Sous-titre │ ├─────────────────────────────────────────────┤ │ [🇺🇸] $8 567k ↑ 25.8% │ │ United States │ │ [🇧🇷] $2 415k ↓ 6.2% │ │ Brazil │ └─────────────────────────────────────────────┘ ``` **Structure d'une ligne :** - Avatar circulaire (drapeau, logo, ou initiales, 38×38px) - Montant (bold, 14px) + label (gris, 12px) - Flèche ↑ verte / ↓ rouge + % variation (14px) --- ### Cas d'usage ESTAIR — où utiliser chaque type #### Dans la Vue Détail (panneau droit) Certains **blocs contextuels** d'un objet peuvent être présentés sous forme de cards advance plutôt qu'une simple liste de champs label/valeur, selon leur nature. | Module | Bloc | Type de card | Contenu | |--------|------|-------------|---------| | `accounts` | Activité financière | **Type A** | Solde / Crédit utilisé / Transactions / Remboursements en attente | | `accounts` | Modules actifs par BSP | **Type B** | Chaque BSP avec barre de progression du montant consommé vs limite | | `etats-de-ventes` | Répartition compagnies | **Type D** | Logo compagnie + nb tickets + % variation | | `helpdesk` | État des tickets | **Type A** | Nouveaux / En cours / Résolus / Escaladés — avec icône colorée | | `remboursement` | Pipeline remboursements | **Type A** | Initié / En cours / Validé / Rejeté + montants | | `emds` | Répartition EMDs | **Type C** | Par type de service + montant + badge statut | | `bsps` | BSP par agence | **Type D** | Avatar agence + montant BSP + variation période | #### Dans la Zone KPI (bande au-dessus du tableau, vue liste) Pour les modules avec `hasPeriod: true`, les 3–4 KPI badges de la bande supérieure peuvent être enrichis en **mini-cards de type A ou C** : ``` ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ [🟩] │ │ [🟦] │ │ [🟧] │ │ [🟣] │ │ 1 245 │ │ 142 300 € │ │ 56 │ │ 12.4% │ │ Tickets émis│ │ CA total │ │ En attente │ │ Var. période│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ ``` #### Dans le Dashboard (déjà documenté dans SPEC_Dashboard) Cards de types A, C, D directement réutilisées pour W8 (BSP), W9 (compagnies), W6 (agences). --- ### Interface backend → frontend pour les cards advance ```typescript interface AdvanceCardDef { cardType: 'A' | 'B' | 'C' | 'D' title: string subtitle?: string items: AdvanceCardItem[] } interface AdvanceCardItem { // Commun à tous les types label: string sublabel?: string value: string | number // Type A & C icon?: string // nom icône iconBgColor?: string // ex: "#e8f5e9" iconColor?: string // ex: "#4caf50" // Type B logoUrl?: string // URL logo ou initiales progress?: number // 0-100 progressColor?: string // hex couleur barre // Type C badgeValue?: string // ex: "+4.2%" badgeColor?: 'success' | 'error' | 'warning' | 'info' // Type D avatarUrl?: string // URL avatar ou drapeau avatarInitials?: string // fallback variation?: number // valeur variation variationDirection?: 'up' | 'down' } ``` --- ## Partie 2 – Form Wizard (Create / Update) ### Ce que montre le template Vuexy **Composant `VuexyWizardNumbered` :** ``` ┌─ Header stepper ─────────────────────────────────────────────────┐ │ [1] Account Details > [2] Personal Info > [3] Social │ │ Setup Account Dtls Add personal info Add links │ └──────────────────────────────────────────────────────────────────┘ ┌─ Body (étape active) ────────────────────────────────────────────┐ │ Account Details │ │ Enter your Account Details │ │ │ │ [Username ] [Email ] │ │ [Password 👁 ] [Confirm Password 👁 ] │ │ │ └──────────────────────────────────────────────────────────────────┘ ┌─ Footer ─────────────────────────────────────────────────────────┐ │ [← Previous] [Next →] │ └──────────────────────────────────────────────────────────────────┘ ``` **Stepper header :** - Étape active : numéro dans carré violet (`border-radius: 6px`), titre bold, sous-titre gris - Étapes futures : numéro dans carré gris outline, titre gris, sous-titre gris clair - Étapes validées : numéro remplacé par ✓ vert, titre gris - Séparateur : chevron `>` entre chaque étape - Cliquable : on peut naviguer vers une étape déjà validée (pas vers une étape future) **Footer :** - `← Précédent` : bouton outline gris, désactivé sur l'étape 1 - `Suivant →` : bouton violet, remplacé par `Enregistrer ✓` sur la dernière étape - Validation avant passage à l'étape suivante (vuelidate/yup selon config) --- ### Adaptation ESTAIR — Form Wizard dans le panneau droit #### Principe clé > **Chaque étape du wizard = un `BlockDef` dans les métadonnées du module** Le wizard est **entièrement piloté par les métadonnées** : le frontend ne connaît pas la structure du formulaire à l'avance. #### Contrat de données ```typescript // Dans ModuleMetadata (déjà défini) interface BlockDef { id: string label: string // Titre de l'étape description?: string // Sous-titre de l'étape icon?: string // Icône optionnelle (affichée dans le stepper) order: number // Ordre dans le wizard required: boolean // Étape obligatoire ou skippable fields: FieldDef[] // Champs du formulaire de cette étape advanceCard?: AdvanceCardDef // Card advance optionnelle (résumé en lecture seule) } interface FieldDef { key: string label: string type: FormFieldType placeholder?: string required: boolean readonly?: boolean colSpan?: 1 | 2 // 1 = demi-largeur, 2 = pleine largeur (défaut: 1) options?: SelectOption[] // Pour select, radio, checkbox validation?: ValidationRule[] dependsOn?: { // Affichage conditionnel field: string value: unknown } } type FormFieldType = | 'text' | 'email' | 'tel' | 'number' | 'password' | 'textarea' | 'select' | 'multiselect' | 'autocomplete' | 'date' | 'datetime' | 'radio' | 'checkbox' | 'switch' | 'file' | 'currency' | 'readonly' // Champ affiché mais non éditable ``` --- ### Comportement du wizard dans le panneau droit #### En mode Create ``` Panneau droit (480px, slide-in depuis droite) ┌─ Header ────────────────────────────────────┐ │ ✏ Nouveau {label_module} ✕ │ ├─ Stepper ───────────────────────────────────┤ │ [1] Bloc A > [2] Bloc B > [3] Bloc C │ ├─ Body étape active ─────────────────────────┤ │ {label bloc} │ │ {description bloc} │ │ │ │ [Champ 1 ] [Champ 2 ] │ │ [Champ 3 ] │ │ ... │ ├─ Footer ────────────────────────────────────┤ │ [← Précédent] [Suivant →] │ │ (ou) [Enregistrer ✓] │ └─────────────────────────────────────────────┘ ``` #### En mode Update - Tous les champs pré-remplis avec les valeurs existantes - Navigation directe vers n'importe quelle étape (toutes déjà "validées") - Bouton final : `Mettre à jour ✓` au lieu de `Enregistrer ✓` - Indicateur de modifications : badge `Modifié` sur les étapes touchées --- ### Règles de layout des champs | `colSpan` | Rendu | |-----------|-------| | 1 (défaut) | Grille 2 colonnes — 2 champs par ligne | | 2 | Champ pleine largeur — 1 champ par ligne | **Champs toujours en pleine largeur (`colSpan: 2`) :** - `textarea` - `multiselect` avec plus de 4 options - Tout champ avec `dependsOn` (pour éviter les trous visuels) --- ### Validation par étape - Validation **avant** de passer à l'étape suivante (pas en temps réel pour ne pas perturber la saisie) - Erreurs affichées sous chaque champ invalide - L'étape devient ✓ dans le stepper seulement si tous les champs requis sont valides - Sur `Enregistrer` : validation globale de toutes les étapes avant soumission ```typescript // Règles de validation dans FieldDef interface ValidationRule { type: 'required' | 'min' | 'max' | 'minLength' | 'maxLength' | 'email' | 'pattern' | 'custom' value?: number | string | RegExp message: string // Message d'erreur en français } ``` --- ### Gestion des étapes optionnelles Si `BlockDef.required = false` : - Le stepper affiche un badge `optionnel` en gris sous le sous-titre - Le bouton `Suivant →` devient `Suivant →` avec un lien discret `Ignorer` à droite - Une étape ignorée reste dans un état "gris" dans le stepper (ni validé ✓ ni en erreur) --- ### Récapitulatif — Où chaque composant est utilisé dans ESTAIR | Composant | Contexte d'utilisation | |-----------|----------------------| | **Card Type A** | KPI bande liste · blocs détail (finances, statuts, helpdesk) | | **Card Type B** | Objets avec progression (BSP/limite · modules actifs) | | **Card Type C** | Source visits → répartition par canal/compagnie | | **Card Type D** | Classements avec avatar (agences, compagnies, bénéficiaires) | | **Form Wizard** | Panneau droit Create · Panneau droit Update (tous modules) | --- ### Fichiers Vuexy de référence ``` src/components/cards/AdvanceCard.vue → réutiliser tel quel, données dynamiques src/views/wizard-examples/NumberedSteps.vue → adapter pour données metadata ```