feat(builder): réglages de lecture du graphique — unité, bornes, lignes de référence, cibles, couleurs fixées, catégories vides, synthèse de carte (#1218)

[bmatge]

Refs #1218 — suite ouverte : #1263

#1220 avait posé le garde-fou de couverture du Builder « Créer un graphique » et renvoyé à #1218 vingt-sept attributs de dsfr-data-chart sans contrôle. Cette PR en livre quatorze, ceux qui changent ce que l'usager LIT, et renvoie les treize autres (plus deux composants) à l'issue de suite #1263, que citent désormais les exclusions.

Réglages livrés

Tous dans la section 4 · Apparence du volet. Un réglage n'apparaît que pour les types qui le lisent ; masqué, il garde sa valeur mais n'est pas écrit dans le code.

Réglage	Contrôle	Attribut(s)	Types
Unité des infobulles	champ « Unité » sous le titre (« Unité de la ligne » + « Unité des barres » pour un barres + ligne)	unit-tooltip, unit-tooltip-bar	barres, barres H, lignes, camembert, anneau, radar, nuage, barres + ligne
Couleur fixée	divulgation « Couleurs par catégorie », sous la palette : lignes « Série ou catégorie » + « Couleur », bouton « Ajouter une couleur »	color-map	les mêmes huit types
Catégories vides	champ « Libellé des catégories vides »	empty-label	barres, barres H, lignes, camembert, anneau, radar, barres + ligne
Synthèse d'une carte	liste « Chiffre affiché sous le titre » : moyenne (défaut), somme, valeur publiée (+ champ), aucun chiffre	map-summary, map-summary-value	les quatre cartes
Bornes de l'axe des valeurs	divulgation « Axes et repères » : « Minimum / Maximum de l'axe des valeurs »	y-min, y-max — x-min, x-max pour des barres horizontales	barres, barres H, lignes, nuage, radar
Bornes de l'axe horizontal	même divulgation : « Minimum / Maximum de l'axe horizontal »	x-min, x-max	nuage
Lignes de référence	même divulgation : lignes « Position » (sur une valeur / sur une étiquette), « Valeur », « Libellé », bouton « Ajouter une ligne de référence »	reference-lines	barres, barres H, lignes, barres + ligne, nuage
Cibles	même divulgation : lignes « Échéance », « Valeur visée », « Libellé » (+ « Mesure » pour un barres + ligne), bouton « Ajouter une cible », cases « Griser la période à venir » et « Afficher la légende »	targets, targets-zone, targets-legend	lignes, barres + ligne

La table « quel réglage pour quel type » (apps/builder/src/lecture.ts) est mesurée dans le navigateur (échelles Chart.js lues après rendu, DSFR Chart 2.1.1), pas déduite du manifeste. Ce que la mesure a montré est dans « Vu en chemin ».

Couverture des attributs de dsfr-data-chart — avant / après

Le manifeste déclare 49 attributs, le même nombre qu'à #1220 : les versions 0.44 à 0.47 n'en ont ajouté aucun à dsfr-data-chart (0.45 : color-map recolore les points ; 0.47 : label-field accepte champ:Libellé — une grammaire, pas un attribut). Mesure : tests/apps/builder/couverture.test.ts.

	Avant	Après
Contrôle dans le volet	17	31
Écrit sans contrôle (déduit d'un autre réglage)	4	4
Exclu, à exposer plus tard	27 (→ #1218)	13 (→ #1263)
Exclu, hors périmètre	1	1

Attribut	Avant	Après
type, label-field, value-field, value-field-2, value-fields, series-field, code-field, stacked, selected-palette	contrôle	contrôle
databox, databox-title, databox-source, databox-date, databox-trend, databox-download, databox-screenshot, databox-fullscreen	contrôle	contrôle
source, name, horizontal, fill	écrit sans contrôle	écrit sans contrôle
unit-tooltip, unit-tooltip-bar	exclu → #1218	contrôle
x-min, x-max, y-min, y-max	exclu → #1218	contrôle
reference-lines	exclu → #1218	contrôle
targets, targets-zone, targets-legend	exclu → #1218	contrôle
color-map	exclu → #1218	contrôle
empty-label	exclu → #1218	contrôle
map-summary, map-summary-value	exclu → #1218	contrôle
map-summary-weight, map-summary-field	exclu → #1218	exclu → #1263
highlight-index, map-highlight	exclu → #1218	exclu → #1263
heading-level, databox-date-field, databox-tooltip-title, databox-tooltip-content, databox-modal-title, databox-modal-content, databox-actions, databox-default-source	exclu → #1218	exclu → #1263
idle-message	exclu → #1218	exclu → #1263
gauge-value	exclu, hors périmètre	exclu, hors périmètre

Composants d'affichage : inchangé — dsfr-data-kpi-group et dsfr-data-display restent exclus, désormais vers #1263.

Ce qui est laissé, et pourquoi

• Cadre officiel (heading-level, databox-date-field, infobulle, fenêtre d'information, actions, source par défaut) : réglage fin d'un cadre déjà exposé, à traiter d'un bloc — avec la case « Plein écran », que seul databox-modal-title rendrait utile (fix(builder): cadre officiel DSFR — vue tableau avec noms de champs techniques, et « Plein écran » sans effet (DSFR Chart 2.1.1) #1179).
• map-summary-weight, map-summary-field : la moyenne pondérée demande que la requête générée agrège une seconde colonne (l'effectif), dans les quatre chemins du générateur. Le lot livre la somme, la valeur publiée et « aucun chiffre ».
• highlight-index : désigne un rang, pas une catégorie — instable dès que les données ou le tri changent. « Couleurs par catégorie » couvre le besoin par le nom. À arbitrer.
• map-highlight, idle-message (sans effet tant que le Builder ne génère pas de require-where), dsfr-data-kpi-group, dsfr-data-display.
• Tri : déjà là (« Trier par », « Ordre »). Limite (limit de dsfr-data-query) et hauteur / ratio : ni dans feat(builder): réglages de dsfr-data-chart encore absents du Builder — suite de #1204 #1218 ni attributs de dsfr-data-chart ; non traités.

Code généré

• Chargement dynamique (Grist, OpenDataSoft, Tabular, API générique) : les attributs s'ajoutent à <dsfr-data-chart> dans la fonction unique visualElement. La requête n'est pas touchée.
• Données intégrées : dès qu'un réglage de lecture est posé, le graphique passe par la bibliothèque (<dsfr-data-source data='…'> + <dsfr-data-chart>), comme le format long de feat(builder): podium, barres + ligne, cartes régions/académies/monde, format long et garde-fou de couverture (#1204) #1220 — une balise DSFR Chart nue ne connaît ni les lignes de référence, ni les cibles, ni color-map, ni la synthèse de carte.
• Rien de posé, rien de changé : sans réglage, aucun attribut n'est écrit et les types historiques gardent leur balise DSFR Chart nue. La suite existante, qui épingle ce code, passe sans modification.

Favoris et états déposés

Les quatorze clés d'état entrent dans l'instantané (getBuilderStateToSave) et dans la détection « Modifications non générées ». À la réouverture (favoris, Playground, Pipeline, tableau de bord), elles sont remises en forme par normalizeLecture : un favori enregistré avant ce lot n'en porte aucune, se rouvre sans réglage et régénère le même code, y compris quand la session en cours en portait. Une clé mal formée prend sa valeur par défaut. Un réglage rouvert déplie la divulgation qui le porte.

Assistant

Chaque contrôle a son repère (builder.apparence.unite, builder.apparence.axes.reference.ajouter…), quatre zones nouvelles (couleurs, axes, axes.reference, axes.cibles), des synonymes (« seuil », « objectif », « borne », « total national »…). reperes.generated.ts est régénéré ; check:reperes et la complétude par le rendu (reperes-completude.test.ts, qui rend désormais une ligne de chaque éditeur) sont verts.

Vérification des données (ADR-122)

Aucun contrôle ajouté à tests/verif-donnees/, pour ces raisons :

• Le Builder ne calcule aucun des chiffres en jeu : il écrit un attribut, la bibliothèque calcule. La synthèse de carte en somme est gardée par carte-resume-somme-927 et carte-resume-dit-ce-quil-ecarte (domaine affichages).
• Aucun manifeste ne pilote le Builder graphique (son aperçu est une iframe srcdoc), et un manifeste ne peut pas importer son générateur (test-garde de l'oracle) : y recopier le balisage attendu contrôlerait une copie, pas le générateur.
• À la place : la forme du code est épinglée par les tests unitaires, et la recette à l'écran lit le chiffre rendu (somme de cinq départements = 3 950, valeur publiée = 310 480).

À noter pour le propriétaire : map-summary-value n'a pas de contrôle dans tests/verif-donnees/ (c'est un littéral, non calculé).

Tests

• tests/apps/builder/lecture-1218.test.ts (84 cas) : module pur, code généré dans les chemins du générateur, instantané, formulaire par type. Cinq preuves de mutation, vues rouges puis retirées.
• tests/apps/builder/retour-playground-champs.test.ts (+3) : réouverture par loadFavoriteState, ancien favori, statut « modifié ». Trois preuves de mutation.
• tests/apps/builder/couverture.test.ts : les quatorze attributs ne sont plus exclus et ont chacun leur contrôle.
• tests/builder-e2e/builder-lecture-recette.spec.ts (11 cas, recette manuelle hors CI — l'aperçu charge DSFR Chart depuis son CDN) : réglages posés par l'interface, puis lus dans l'aperçu (échelles Chart.js, étiquettes, calques, synthèse de carte), ancien favori, 375 px, absence de défilement de page. Preuve de mutation vue rouge.

Commande	Résultat
npm run test:run	469 fichiers, 9 612 tests verts (après fusion de main)
npm run typecheck:tests, npm run lint, npm run check:accents	verts
npm run check:reperes, check:specs-tables, check:studio-couverture	verts
npm run build, build du Builder	verts
npm run verif	313 verts, 1 ignoré (avant fusion de main)
export-html-api-recette + layout-diagnostic-recette	89 verts
e2e/buttons.spec.ts + e2e/mobile-chrome.spec.ts	39 verts, 6 ignorés
builder-lecture-recette	11 verts

Les specs Playwright ont tourné contre le serveur de dev de cette branche sur le port 5241, avec des copies temporaires des configurations : le port 5173 était tenu par un autre worktree. La CI les rejoue telles quelles.

Choix d'interface à valider

1. Emplacement : tout dans « Apparence ». Unité et catégories vides visibles d'emblée ; couleurs fixées et « Axes et repères » derrière deux divulgations repliées (même patron que « Requête avancée »).
2. Une seule paire de bornes « axe des valeurs », que le Builder traduit en y-* ou en x-* (barres horizontales). L'axe horizontal n'a ses propres bornes que pour le nuage.
3. Pas de bornes pour un barres + ligne ni pour l'axe des étiquettes d'une courbe : sans effet dans la bibliothèque (voir ci-dessous).
4. Aide sur les bornes : « Les bornes sont arrondies à la graduation voisine. Des barres partent toujours de zéro : seul un minimum négatif est pris en compte. »
5. Ligne de référence : deux positions, « Sur une valeur (seuil) » et « Sur une étiquette (date, catégorie) ». Couleur, pointillé et position du libellé gardent leurs défauts.
6. Cible : vise la première série d'une courbe ; pour un barres + ligne, « La ligne » par défaut. Zone grisée et légende cochées par défaut, affichées seulement quand une cible existe.
7. Couleur : <input type="color"> natif (comme le Builder carto), bleu France proposé ; noms suggérés depuis les séries et les données générées.
8. Catégories vides, données intégrées : le libellé choisi remplace « N/A », le repli historique du Builder, dans les lignes intégrées (donc aussi dans le tableau accessible).
9. Synthèse de carte : libellés « Moyenne des territoires (par défaut) », « Somme des territoires (carte de volumes) », « Valeur publiée, saisie ci-dessous », « Aucun chiffre ».
10. Saisie des nombres : champs texte acceptant 5,6 et 310 480 ; une saisie illisible n'écrit aucun attribut, sans message.
11. Données intégrées + réglage de lecture = passage par la bibliothèque, y compris pour une source OpenDataSoft, dont le script de chargement à l'ouverture disparaît alors au profit des lignes agrégées intégrées (même arbitrage que celui laissé ouvert par feat(builder): podium, barres + ligne, cartes régions/académies/monde, format long et garde-fou de couverture (#1204) #1220).

Vu en chemin, non corrigé

Bibliothèque (packages/core n'est pas touché, pas de changeset) :

• y-min / y-max sur type="bar" horizontal ajoutent deux catégories fantômes à l'axe des étiquettes ; ce sont x-min / x-max qui bornent les valeurs.
• y-min / y-max sans effet sur type="bar-line" ; x-min / x-max sans effet sur type="line", que leur description cite.
• Une borne minimale positive est arrondie à la graduation inférieure (y-min="5" → axe depuis 0).

Builder :

• Le champ « Libellé » des étiquettes (labelFieldLabel) est enregistré mais n'est écrit nulle part dans le code généré.
• Les réglages du cadre officiel et extraSeries ne sont pas dans l'instantané des favoris.

Le détail est dans #1263.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FrLwzPx5CG4VsPHEdo5ZVs