_Assistant_Lead_Tech/knowledge/frontend/patterns/general.md

Frontend — Patterns : Général

Extrait de la base de connaissance Lead_tech. Voir knowledge/frontend/patterns/README.md pour l'index complet.

---

Pattern : Focus visible interne pour champs sous overflow clip

Synthèse

• Objectif : préserver le focus visible des champs <input> / <select> quand l'app applique overflow-x: clip sur ses conteneurs (PageShell, panel, layout) — le focus outline natif est dessiné hors de la box du champ et se fait clipper.
• Contexte : app mobile-first où overflow-x: clip (ou hidden) est fréquent sur les conteneurs pour empêcher le débordement horizontal.
• Quand l'utiliser : tout projet avec une chaîne de parents en overflow: hidden|clip autour des champs de saisie.
• Quand l'éviter : si la chaîne de parents n'a pas d'overflow: hidden|clip — l'outline natif suffit.

Analyse

• Avantages :
  • aucun pixel ne sort de la box, donc aucun clip possible
  • box-shadow: inset + border-color est portable Chrome/Firefox/Safari
• Limites / vigilance :
  • outline-offset: -2px marche sur Chrome mais le rendu varie : Firefox/Safari peuvent ignorer selon la combinaison outline-style

Validation

• Validé le : 27-04-2026
• Contexte technique : CSS / mobile-first — RL799_V2

Pattern correctif (par composant)

.my-input:focus-visible,
.my-select:focus-visible {
  outline: none;
  border-color: var(--color-accent);
  box-shadow: inset 0 0 0 1px var(--color-accent);
}

Application globale au thème (recommandée pour mobile-first)

Plutôt que de répéter le pattern dans chaque composant, le pousser dans le fichier de thème global. Tous les inputs/selects/textareas en bénéficient automatiquement.

/* Dans theme/<theme>.css ou globals.css, hors :root */
input[type='text']:focus-visible,
input[type='search']:focus-visible,
input[type='email']:focus-visible,
input[type='tel']:focus-visible,
input[type='url']:focus-visible,
input[type='number']:focus-visible,
input[type='password']:focus-visible,
input[type='date']:focus-visible,
input[type='datetime-local']:focus-visible,
input[type='time']:focus-visible,
input[type='month']:focus-visible,
input[type='week']:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: none;
  border-color: var(--color-accent);
  box-shadow: inset 0 0 0 1px var(--color-accent);
}

Pourquoi sélecteurs d'attribut explicites et pas input:focus-visible

input couvre aussi type='checkbox', type='radio', type='file', type='range', type='color' qui ont leur propre design natif. La règle pourrait casser leur rendu (carrés or autour des cases à cocher, etc.). On liste explicitement les types texte/saisie.

Conflits avec composants ayant leur propre :focus

Un composant qui a déjà .my-input:focus { ... } (sans -visible) gardera la priorité par spécificité (classe > tag). La règle globale ne joue que pour les composants qui n'ont rien défini → sûr à introduire en mid-projet.

---

Pattern : Restyle global de <input type="date"> sans wrapper JS

Synthèse

• Objectif : aligner les inputs date HTML5 sur l'identité visuelle du thème via une règle CSS globale, sans wrapper JS custom.
• Contexte : projet avec un thème dark/light custom où les inputs date natifs (icône calendrier blanche, placeholder gris OS, popover light par défaut) cassent le design.
• Quand l'utiliser : 80 % des cas (audit log, formulaires admin, profils) où la datepicker custom serait du sur-engineering.
• Quand l'éviter :
  • validation custom synchrone (range, dates blackout, format spécifique)
  • format d'affichage différent (DD/MM vs MM/DD vs ISO)
  • intégration profonde dans un design system

Analyse

• Avantages :
  • color-scheme + accent-color donnent un popover natif cohérent gratuitement
  • filtre SVG pour teinter l'icône calendrier
  • zéro JavaScript, zéro bundle additionnel
• Limites / vigilance :
  • Firefox : accent-color respecté, mais pas de pseudo-element pour customiser le placeholder
  • Safari iOS : popover sheet OS, peu personnalisable. Acceptable car cohérent avec le reste des UI iOS natives
  • filtre filter() à calibrer pour matcher la couleur du thème — chaque thème nécessite son tuning

Validation

• Validé le : 27-04-2026
• Contexte technique : CSS / inputs date HTML5 — RL799_V2

Pattern minimal

/* Toutes les variantes de pickers HTML5 */
input[type='date'],
input[type='datetime-local'],
input[type='time'],
input[type='month'],
input[type='week'] {
  color-scheme: dark; /* ou 'light' selon le thème de l'app */
  accent-color: var(--color-accent);
}

/* Place-holder OS (jj/mm/aaaa) — couleur soft */
input[type='date']::-webkit-datetime-edit-fields-wrapper,
input[type='datetime-local']::-webkit-datetime-edit-fields-wrapper {
  color: var(--color-text-soft);
}

/* Une fois saisie, couleur normale */
input[type='date']:not(:placeholder-shown)::-webkit-datetime-edit-fields-wrapper {
  color: var(--color-text-primary);
}

/* Icône calendrier teintée (filtre SVG noir → couleur d'accent soft) */
input[type='date']::-webkit-calendar-picker-indicator,
input[type='datetime-local']::-webkit-calendar-picker-indicator,
input[type='time']::-webkit-calendar-picker-indicator,
input[type='month']::-webkit-calendar-picker-indicator,
input[type='week']::-webkit-calendar-picker-indicator {
  /* Calibrer pour matcher la couleur du thème */
  filter: invert(70%) sepia(40%) saturate(450%) hue-rotate(5deg) brightness(95%);
  cursor: pointer;
  opacity: 0.85;
  transition: opacity 0.15s ease;
}

Anti-patterns

• Construire un mini calendrier JS custom pour gagner 5 % d'esthétique → effort énorme (a11y clavier, focus management, mobile, edge cases), bénéfice marginal
• Hardcoder les couleurs filter() au lieu d'utiliser des tokens du thème
• Restyler sans color-scheme: dark/light → le popover natif reste en mode clair sur thème sombre

---

Pattern : UI pour journaux / audit logs / timelines

Synthèse

• Objectif : passer d'un rendu naïf en cards uniformes "acteur · code · cible (uuid) · metadata" à une lecture rapide pour l'admin en surveillance, sans toucher au backend.
• Contexte : tout projet finit par afficher un journal d'événements (audit, activité, historique, timeline) avec metadata variable.
• Quand l'utiliser : journal avec ≥ 10 types d'actions et besoin de scanner rapidement.
• Quand l'éviter : log technique brut destiné aux devs (un <pre> peut suffire).

Analyse

• Avantages :
  • 5 patterns combinables qui améliorent radicalement la scanabilité
  • aucun changement backend (le DTO reste plat)
• Limites / vigilance :
  • reset de l'état d'expansion à chaque rechargement (l'expansion est éphémère, pas une préférence durable)

Validation

• Validé le : 27-04-2026
• Contexte technique : Vue 3 / CSS — RL799_V2 (Journal d'audit admin, 45+ types d'actions)

1. <optgroup> dérivé du préfixe label

Quand l'API retourne un catalogue d'actions avec convention Catégorie — Libellé (ex : Soirée — annulation, Tenue — création), dériver les groupes côté front au lieu de modifier le DTO.

const groupsFromLabels = computed(() => {
  const groups = new Map<string, Entry[]>();
  for (const opt of catalog.value) {
    const sep = opt.label.indexOf(' — ');
    const category = sep > 0 ? opt.label.slice(0, sep) : 'Divers';
    groups.set(category, [...(groups.get(category) ?? []), opt]);
  }
  return Array.from(groups.entries())
    .sort(([a], [b]) => a.localeCompare(b, 'fr', { sensitivity: 'base' }));
});

<select>
  <option value="">Toutes les actions</option>
  <optgroup v-for="[cat, opts] in groupsFromLabels" :label="cat" :key="cat">
    <option v-for="o in opts" :value="o.value" :key="o.value">{{ o.label }}</option>
  </optgroup>
</select>

Bénéfice : 1 seul clic pour filtrer (vs cascade 2 selects), accessible natif, zéro modif backend.

2. Code couleur sémantique par catégorie

Barre de couleur de 3 px à gauche de chaque card de la liste, mappée sur la catégorie de l'événement. Transforme un mur de cards uniformes en lecture instantanée.

.log-item {
  border-left: 3px solid var(--log-cat-color, var(--color-border));
}
.log-item--cat-soiree { --log-cat-color: var(--color-accent-primary); }
.log-item--cat-rgpd   { --log-cat-color: var(--color-accent-danger); }

Pourquoi pas le fond complet : trop bruyant, perd la sobriété d'un journal admin. La barre latérale signale sans crier.

3. UUIDs rétrogradés en monospace soft

Les UUIDs / IDs techniques affichés en plein texte cassent la lecture humaine. Les détecter via regex et les rendre en font monospace + couleur soft + taille réduite, sans les masquer (utiles pour forensics).

const UUID_RE = /[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}/gi;

.uuid {
  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
  font-size: 0.78em;
  color: var(--color-text-soft);
  word-break: break-all;
}

4. Date relative + absolue en tooltip

Pour la lecture humaine, "il y a 5 min" / "hier" / "il y a 3 j" bat toujours "27 avril 2026 à 08:37". La date absolue reste accessible en title du <time> pour les forensics.

const formatRelative = (iso: string) => {
  const diff = (Date.now() - new Date(iso).getTime()) / 1000;
  if (diff < 60) return 'à l\'instant';
  if (diff < 3600) return `il y a ${Math.round(diff / 60)} min`;
  if (diff < 86400) return `il y a ${Math.round(diff / 3600)} h`;
  if (diff < 172800) return 'hier';
  if (diff < 604800) return `il y a ${Math.round(diff / 86400)} j`;
  return new Date(iso).toLocaleDateString('fr-FR', {
    day: 'numeric', month: 'short', year: 'numeric',
  });
};

5. Détails techniques repliables

La metadata détaillée (clés/valeurs verboses, IDs internes, raisons null) sert à l'investigation, pas à la lecture courante. La masquer derrière un Voir les détails / Masquer les détails, et reset l'état d'expansion à chaque rechargement.

const expanded = ref<Set<string>>(new Set());
const toggle = (id: string) => {
  const next = new Set(expanded.value);
  next.has(id) ? next.delete(id) : next.add(id);
  expanded.value = next;
};
// Reset après chaque load
const loadList = async () => {
  /* … */
  expanded.value = new Set();
};

Le bouton "voir détails" n'apparaît que si la card a effectivement de la metadata. Un toggle vide pollue la grille visuelle.

Anti-patterns à éviter

• Cards uniformes en couleur/border quel que soit le type d'événement → tue la scanabilité
• Date absolue toujours visible (27 avril 2026 à 08:37) sur des cards serrées → bruit cognitif inutile
• UUIDs en plein texte sans rétrogradation visuelle
• Cascade 2 selects quand un <optgroup> natif suffit
• Bouton "voir détails" affiché même sans détails à voir
• Persister l'expansion entre navigations / paginations → état orphelin

---

Pattern : Structuration de pages admin (eyebrows + grille filtres + variante danger)

Synthèse

• Objectif : poser une grammaire visuelle commune sur les écrans admin (filtres + liste/form + sections multiples) sans framework lourd.
• Contexte : module Admin avec plusieurs panels (Audit, Utilisateurs, Corbeille, etc.) qui partagent la même structure.
• Quand l'utiliser : ≥ 3 panels admin avec structure similaire.
• Quand l'éviter : page admin unique sans cohérence inter-panels à maintenir.

Validation

• Validé le : 27-04-2026
• Contexte technique : Vue 3 / CSS — RL799_V2 (5 panels admin)

1. Eyebrows de section

Au lieu de titres H2/H3 trop forts, utiliser des "eyebrows" : mini-labels uppercase, letter-spacing élargi, taille caption, couleur d'accent.

.eyebrow {
  text-transform: uppercase;
  letter-spacing: 0.2em;
  font-size: var(--font-size-caption);
  color: var(--color-accent);
  margin: 0;
}

<p class="eyebrow">Filtres</p>
<div class="my-filters"><!-- … --></div>

<p class="eyebrow">Résultats <span class="eyebrow-count">· {{ total }} entrées</span></p>
<div class="my-list"><!-- … --></div>

Le compteur (· N entrées) est en font-weight: normal, sans uppercase, en color-text-secondary — typographie en cascade.

Bénéfice : structure visuelle sans concurrencer un éventuel titre de page. Cohérence inter-écrans dans tout un module si l'eyebrow est utilisé partout.

Quand ne pas afficher l'eyebrow Résultats : sur loading / error / empty state. Le StateBlock (ou équivalent) prend le relais.

2. Grille de filtres hiérarchique

Quand 3+ filtres dont l'un est dominant (typiquement une recherche), au lieu d'un flex-wrap chaotique, utiliser une grille avec le filtre primaire en pleine largeur :

<div class="filters">
  <label class="filters__label filters__label--full">Recherche
    <input type="search">
  </label>
  <label class="filters__label">Statut <select><!-- … --></select></label>
  <label class="filters__label">Rôle <select><!-- … --></select></label>
</div>

.filters {
  display: grid;
  grid-template-columns: 1fr 1fr;
  align-items: end;
  gap: var(--space-2);
}
.filters__label--full {
  grid-column: 1 / -1;
}

3. Variante danger pour actions destructives

Sur un écran qui mélange actions constructives et destructives (ex : saisie initiale + bypass admin) :

.btn--danger {
  border-color: color-mix(in srgb, var(--color-danger) 48%, transparent);
  background: color-mix(in srgb, var(--color-danger) 12%, transparent);
  color: var(--color-danger);
}

.card--danger {
  border-left: 3px solid var(--color-danger);
}

color-mix produit un rouge soft (12-20 % saturation), pas un flash rouge violent.

Anti-pattern : background: red / color: red directs ou hex hardcodés (#ef4444). Toujours via tokens du thème.

Anti-patterns à éviter

• Filtres en flex-wrap qui produisent 3 lignes asymétriques selon le viewport
• Hint général qui répète ce que l'empty state dit déjà → 1 message, 1 niveau d'info
• Confondre "titre de page" (l'onglet actif suffit souvent) et "structure de section" (eyebrows)
• Action destructive en variant primary or → danger explicite