coastdigitalgroup/coastai-skills

Système de Mise en Page Maître-Détail

Objectif

Le système de mise en page Maître-Détail (également connu sous le nom d'interface Split-Pane ou Liste-Détail) fournit une mise en page visuelle standardisée et un cadre d'interaction pour parcourir une liste principale d'éléments (le panneau "Maître") tout en affichant des attributs complets, des actions contextuelles et un historique profondément imbriqué pour l'enregistrement actuellement sélectionné dans un espace de travail adjacent et synchronisé (le panneau "Détail").

Les motifs maître-détail sont fondamentaux pour les applications de productivité web à haute efficacité, telles que les clients de messagerie, les helpdesks de support client, les visualiseurs de deals CRM, les plateformes de revue de code, les journaux d'audit et les consoles de ressources cloud.

Concevoir une interface Maître-Détail efficace nécessite d'établir des proportions spatiales précises, un confinement vertical indépendant (empêchant le défilement global de la page), des états de sélection visuelle clairs, une synchronisation transparente entre les panneaux et des transitions fluides du viewport mobile, passant d'une vue split côte à côte à une navigation single-pane avec pile arrière, le tout en adhérant strictement aux directives d'accessibilité WCAG 2.1 AA pour la gestion du focus et la navigation au clavier.

Cas d'Utilisation

• Portails de Helpdesk et de Support Client : Parcourir une liste de tickets ouverts dans le panneau maître tout en lisant les conversations complètes, l'historique client et les notes internes dans le panneau détail.
• CRM d'Entreprise et Pipelines de Vente : Scanner les contacts ou comptes dans un panneau maître tout en inspectant l'historique des étapes du deal, les activités à venir et les détails du contact dans le panneau détail.
• Applications de Messagerie Web et de Messagerie : Consulter un flux de boîte de réception dans la colonne maître gauche tout en lisant, répondant ou archivant le message actif dans le panneau détail droit.
• Tableaux de Bord Devops et Inspecteurs Cloud : Filtrer les instances de serveur, les flux de logs ou les pipelines de déploiement dans le panneau maître tout en inspectant les métriques en temps réel, les traces d'erreur et les configurations YAML dans le panneau détail.
• Systèmes de Suivi des Candidats (ATS) RH : Naviguer dans les candidatures tout en consultant les CV, les évaluations des recruteurs et les outils de planification côte à côte.

Quand Ne PAS Utiliser

• Espaces de Travail de Données Tabulaires Nécessitant des Comparaisons Multi-Lignes : Si les utilisateurs ont besoin de comparer des dizaines d'enregistrements simultanément sur plusieurs attributs structurés, utilisez data-table-ui-system.
• Tableaux de Pipeline de Flux de Travail : Pour les workflows à colonnes de statut où les cartes sont déplacées horizontalement à travers des étapes de pipeline discrètes, utilisez kanban-board-ui-system.
• Arborescences de Documents Hiérarchiques : Pour la navigation dans des documents profondément imbriqués en forme d'arbre (par exemple, les arborescences de répertoires de système de fichiers), utilisez tree-view-navigation-system.
• Assistants Pas-à-Pas Linéaires : Pour les formulaires séquentiels en plusieurs étapes où chaque vue s'appuie sur la précédente, utilisez step-progress-system ou multi-step-form-implementation.
• Pages de Destination Autonomes Simples : Pour les pages de destination marketing ou les flux d'articles linéaires simples où le contenu s'écoule verticalement dans une seule colonne, utilisez article-layout-system ou section-composition-system.

Entrées

1. Architecture de l'Information et Schéma des Éléments : Attributs à afficher dans la carte d'élément Maître (par exemple, Badge de Statut, Titre/Sujet, Métadonnées Primaires, Horodatage) par rapport à l'espace de travail Détail (Corps Complet de l'Enregistrement, Historique des Activités, Enregistrements Connexes, Barres d'Actions Contextuelles).
2. Contexte de Coque du Viewport : Limites de mise en page fournies par la coque d'application externe (dashboard-layout-system ou sidebar-navigation-system).
3. Préférences de Proportion de Largeur des Panneaux : Exigences de dimensionnement des colonnes (par exemple, Largeur Maître Fixe 360px + Détail Fluide flex: 1, ou Fraction de Pourcentage 35% / 65%).
4. Jetons de Conception : Élévations de surface, bordures neutres, indicateurs d'anneau de focus et échelles typographiques (accessible-color-system, elevation-and-depth-system, fluid-spacing-system).

Sorties

1. Spécification de Mise en Page Split-Pane : Définitions spatiales CSS Grid / Flexbox pour des proportions de panneaux fixes vs. fluides, conteneurs de défilement vertical indépendants (overflow-y: auto), et séparateurs visuels.
2. Sélection d'Élément Maître et Plan d'État Actif : Spécifications visuelles pour les états non lu, survolé, focalisé, sélectionné (aria-selected="true"), et case à cocher de sélection multiple dans la liste.
3. Hiérarchie de l'Espace de Travail Détail et Anatomie de l'En-tête : Mise en page spatiale pour la barre d'actions de la vue détail (en-tête collant, bouton retour, contrôles de statut, déclencheurs d'actions primaires/secondaires) et onglets/sections de contenu.
4. Modèle d'Adaptation du Viewport Réactif : Règles de transition de mise en page étape par étape passant d'une vue split à deux panneaux sur bureau/portable à une navigation à pile arrière à panneau unique avec diapositives de panneau animées sur les écrans de tablette/mobile.
5. Modèle d'Interaction Accessible au Clavier et ARIA : Piégeage du focus, tabindex mobile ou routage du focus de la listbox APG, points de repère ARIA (role="region", aria-controls), et notifications de statut du lecteur d'écran via aria-live="polite".

---

Workflow

1. Établir le Conteneur de Canevas à Deux Panneaux

Construire le wrapper maître-détail externe dans la coque d'application (dashboard-layout-system) :

• Verrouillage du Viewport du Conteneur : Définir le wrapper externe sur display: flex; height: 100vh; max-height: 100vh; overflow: hidden; (ou l'adapter à l'intérieur de la zone de contenu du tableau de bord parent) pour verrouiller la hauteur globale de la mise en page et éliminer le défilement de la fenêtre au niveau du navigateur.
• Grille de Colonnes à Rapport de Fraction : Définir la proportion du split-pane à l'aide de CSS Grid ou Flexbox :
  • Motif Maître Fixe (Recommandé pour les Boîtes de Réception/CRM) : grid-template-columns: minmax(300px, 380px) 1fr; (Le panneau Maître reste à une largeur de numérisation confortable entre 300px et 380px ; le panneau Détail consomme tout l'espace horizontal restant).
  • Motif de Fraction Proportionnelle : grid-template-columns: 35% 65%; ou 40% 60% pour les outils d'inspection denses.
• Séparateur Visuel de Panneau : Insérer une bordure pleine de 1px (border-right: 1px solid var(--border-subtle)) ou une barre de fractionnement redimensionnable accessible (accessible-split-pane-implementation) entre les panneaux.

2. Concevoir la Structure du Panneau de Liste Maître

Le panneau Maître sert d'index à numérisation rapide pour la collection d'enregistrements :

• Région d'En-tête Collante : Positionner une barre de contrôle de recherche et de filtre fixe en haut du panneau Maître (flex-shrink: 0; padding: 12px 16px; border-bottom: 1px solid var(--border-subtle); background: var(--surface-card)). Inclure un champ de recherche rapide (search-interface-system), des chips de filtre et des déclencheurs d'actions en masse.
• Liste d'Éléments à Défilement Indépendant : Envelopper les éléments de liste dans un conteneur avec flex: 1; overflow-y: auto; overflow-x: hidden; -webkit-overflow-scrolling: touch; (role="list" ou role="listbox").
• Anatomie de la Carte d'Élément Maître :
  1. Ligne du Haut : Identifiant Principal / Auteur (font-weight: 600; font-size: 0.875rem; color: var(--text-primary)), Badge/Statut, et Horodatage (font-size: 0.75rem; color: var(--text-muted)).
  2. Ligne du Milieu : Sujet ou Titre de l'Élément (font-weight: 500; font-size: 0.875rem; color: var(--text-primary); text-truncate: 1 line).
  3. Ligne du Bas : Texte d'Extrait ou d'Aperçu (font-size: 0.8125rem; color: var(--text-secondary); line-clamp: 2), Étiquettes/Catégorie, et Avatar de l'Assigné (user-avatar-system).
• Règles de Style d'État :
  • État Non Lu / Non Traité : Texte du titre en gras avec un indice visuel subtil (par exemple, un point d'accentuation primaire 8x8px sur la gauche).
  • État de Survol : Surbrillance de fond (background: var(--surface-hover); cursor: pointer).
  • État Actif / Sélectionné : Fond de surface actif distinct (background: var(--surface-active-subtle)), une bande indicatrice d'accentuation primaire pleine de 3px sur la bordure gauche (border-left: 3px solid var(--brand-primary)), et aria-selected="true".
  • État de Focus Visible : Contour de focus très visible (outline: 2px solid var(--focus-ring); outline-offset: -2px).

3. Construire la Structure du Panneau de l'Espace de Travail Détail

Le panneau Détail rend le contexte complet et l'espace de travail de l'enregistrement actif :

• Affichage d'État Vide : Lorsqu'aucun enregistrement n'est sélectionné dans le panneau maître, afficher un état vide accessible (empty-state-system) dans le panneau détail avec une icône subtile, un titre clair ("Aucun enregistrement sélectionné") et une astuce utile ("Sélectionnez un élément dans la liste pour voir les détails").
• Barre d'Actions de Détail Collante : Afficher une barre d'en-tête persistante en haut du panneau détail (position: sticky; top: 0; z-index: 10; display: flex; align-items: center; justify-content: space-between; padding: 12px 24px; border-bottom: 1px solid var(--border-subtle); background: var(--surface-card)) :
  • Déclencheur de Retour Mobile : Inclure un bouton "Retour à la liste" caché sur le bureau (<button class="mobile-back-btn">← Retour</button>).
  • Identification de l'Enregistrement : Résumé de l'ID du Titre de l'Enregistrement (font-weight: 600; font-size: 1rem).
  • Contrôles d'Action : Boutons d'action principaux (par exemple, "Répondre", "Modifier", "Assigner", "Supprimer") stylisés à l'aide de button-and-action-system.
• Région de Défilement de Contenu Indépendant : Envelopper le corps du contenu principal du détail dans un conteneur de défilement (flex: 1; overflow-y: auto; padding: 24px).
• Mise en Page du Contenu Détail :
  • Section d'En-tête : Titre de l'Enregistrement H1, Badge de Statut, Grille de Métadonnées (Date de Création, Auteur, Priorité, Assigné).
  • Zone de Corps Principal : Description complète, message de fil HTML ou bloc de code de configuration.
  • Sous-Sections à Onglets : Utiliser des onglets (tab-ui-system) pour séparer "Historique des Activités", "Pièces Jointes", "Journaux d'Audit", et "Enregistrements Connexes".

4. Implémenter la Navigation Mobile et Tablette avec Pile Arrière Responsive

Sur les écrans de moins de 768px (ou 1024px pour les applications denses), l'affichage côte à côte des panneaux donne un texte illisible et des boutons à l'étroit. Transformer la mise en page en un modèle de pile arrière à panneau unique :

• Vue Mobile à Panneau Unique : Afficher un seul panneau à la fois sur toute la largeur du viewport (width: 100%).
• Machine à États de Navigation :
  • État A (Maître Actif) : Le panneau de liste Maître occupe 100% de la largeur. Le panneau Détail est visuellement masqué (display: none ou déplacé hors écran avec transform: translateX(100%)).
  • État B (Détail Actif) : Lorsque l'utilisateur tape sur un élément maître, basculez les viewports. Le panneau Détail prend 100% de la largeur et le panneau Maître est masqué.
• Bouton Retour Mobile : Dans l'État B, le panneau Détail affiche un bouton "Retour à la liste" proéminent en haut à gauche. Appuyer dessus réinitialise la machine à États vers l'État A et ramène le focus clavier à l'élément de liste maître précédemment sélectionné.
• Animation du Viewport : Utiliser des transitions de diapositive fluides (view-transitions-implementation ou des transformations CSS horizontales transform 0.25s ease-in-out) pour renforcer le repérage directionnel (glisser vers la gauche pour le détail, glisser vers la droite pour revenir à la liste maître).

5. Assurer un Focus Accessible et une Interaction avec le Lecteur d'Écran

• Rôles de Point de Repère et de Région ARIA : Attribuer role="region" aria-label="Liste des éléments" au conteneur du panneau Maître et role="region" aria-label="Espace de travail de l'élément Détail" au conteneur du panneau Détail.
• Balise de Sélection / Listbox : Si la liste maître se comporte comme un widget de sélection unique, appliquer role="listbox" aria-label="..." à la liste et role="option" aria-selected="true|false" aux éléments de la liste. Alternativement, utiliser une <nav> standard avec aria-current="page" ou aria-current="true".
• Gestion du Focus lors de la Sélection d'un Enregistrement : Lorsqu'un utilisateur sélectionne un élément maître à l'aide d'un clavier ou d'un pointeur :
  • Maintenir le focus clavier à l'intérieur de la liste maître si l'utilisateur scanne rapidement avec les touches fléchées (Haut / Bas).
  • Mettre à jour le DOM du panneau Détail de manière asynchrone et annoncer le chargement de l'enregistrement via une région de statut aria-live="polite" : "Ticket chargé #1042 : Erreur de traitement du paiement".
  • Lorsque l'utilisateur appuie sur Entrée ou Tab à partir d'un élément de liste sélectionné, déplacer de manière transparente le focus vers l'action principale ou l'en-tête H1 du panneau Détail (tabindex="-1").
• Piégeage et Restauration du Focus sur le Viewport Mobile : Lors du passage à la vue Détail sur mobile, déplacer automatiquement le focus vers le bouton Retour Mobile ou l'en-tête Détail. Lors du retour à la vue Maître, restaurer le focus sur l'élément maître qui était précédemment actif.

---

Règles de Décision

Mise en Page des Panneaux et Stratégie de Split

Largeur du Viewport	Motif de Mise en Page Recommandé	Largeur du Panneau Maître	Largeur du Panneau Détail
Grand Bureau (>1280px)	Vue Split à Deux Panneaux (ou 3 Panneaux avec Barre Latérale)	Fixe 360px - 400px	Fluide flex: 1 (min-width: 600px)
Bureau Standard (1024px - 1279px)	Vue Split à Deux Panneaux	Fixe 320px - 350px	Fluide flex: 1 (min-width: 480px)
Tablette (768px - 1023px)	Deux Panneaux Étroits OU Pile à Panneau Unique	Fixe 280px - 300px (ou Pliant)	Fluide flex: 1
Mobile (<768px)	Vue Pile Arrière à Panneau Unique	100% (État A)	100% (État B)

Sélection de la Liste Maître vs Modèle de Focus

• Auto-Sélection au Focus (Numérisation Rapide) : Appuyer sur les touches fléchées Haut ou Bas change immédiatement la sélection active et met à jour le panneau Détail en temps réel. Recommandé pour la lecture des e-mails, la vérification des journaux et le filtrage des tickets à volume élevé.
• Sélection Explicite sur Action (Appuyer sur Entrée / Cliquer) : Naviguer dans les éléments maîtres avec les touches fléchées déplace un anneau de focus visuel sans mettre à jour le panneau Détail. Le panneau Détail se met à jour uniquement lorsque l'utilisateur appuie explicitement sur Entrée, Espace ou clique. Recommandé lorsque le chargement des enregistrements détaillés implique des requêtes API réseau lourdes ou des modifications d'état de formulaire.

---

Contraintes

• Accessibilité (WCAG 2.1 AA) :
  • SC 2.1.1 Clavier : Les utilisateurs doivent pouvoir faire défiler les éléments maîtres, sélectionner des enregistrements, naviguer dans l'espace de travail détail, déclencher des actions et revenir à la liste maître en utilisant uniquement les commandes clavier.
  • SC 2.4.7 Focus Visible : Les éléments maîtres actifs et focalisés doivent comporter un anneau de focus non rogné avec un rapport de contraste d'au moins 3:1 par rapport à l'arrière-plan.
  • SC 4.1.2 Nom, Rôle, Valeur : Les éléments maîtres doivent communiquer explicitement leur état actif/sélectionné à la technologie d'assistance via aria-selected="true" ou aria-current="true".
  • SC 2.5.8 Taille des Cibles : Les cibles tactiles sur les éléments de la liste maître et les boutons d'action du détail doivent fournir une zone cible minimale de 24x24px (44x44px de préférence sur les écrans tactiles mobiles).
• Confinement de la Mise en Page et CLS : Le