Guide utilisateur illustré automatisé

Ce guide présente le parcours principal de QForm Builder avec des captures produites par Playwright depuis une fixture déterministe. Les images ne sont pas des baselines de non-régression : elles constituent les illustrations publiées dans VitePress.

Captures reproductibles

Exécutez bun run docs:screenshots après une évolution visible de l’interface. Le scénario régénère les versions française et anglaise, puis recalcule le manifeste SHA-256. Les images existantes restent intactes tant que les deux parcours Playwright ne sont pas terminés avec succès.

1. Comprendre l’interface

Le constructeur est organisé autour de trois zones : le catalogue à gauche, le canvas central et le panneau de configuration à droite. La barre supérieure regroupe l’import, l’export, le thème, l’historique et l’enregistrement.

2. Sélectionner et configurer un champ

En mode Édition, sélectionnez un champ dans le canvas. Le panneau droit affiche immédiatement les propriétés du champ actif : identité technique, libellé, données, disposition responsive et validation.

Les interactions runtime des contrôles Quasar sont neutralisées pendant l’édition. Un clic sur un QSelect, un QInput, une case à cocher ou un slider sélectionne donc le composant sans modifier sa valeur.

3. Tester le formulaire en aperçu

Passez en mode Aperçu pour utiliser les contrôles comme un utilisateur final. Le panneau Informations suit le registre canonique des valeurs, y compris les objets imbriqués et les étapes.

La finalisation d’un formulaire émet le payload submit sans vider implicitement les données. Une nouvelle saisie doit être déclenchée explicitement par l’application hôte.

4. Personnaliser le Theme Builder

Le Theme Builder centralise les préréglages, couleurs, typographie, disposition, effets, animations et icônes Quasar/Iconify. La prévisualisation est mise à jour avant validation du thème.

5. Restaurer une version avec l’historique

L’historique visible affiche une timeline métier. Les actions d’annulation, de rétablissement et de restauration restent isolées par builder-id.

6. Exporter un document versionné

L’export recommandé produit un document canonique contenant le schéma, les valeurs et les réglages. Le mode « schéma uniquement » reste disponible pour les intégrations historiques.

Régénérer et vérifier les images

bun run docs:screenshots
bun run docs:screenshots:check
bun run docs:build

La vérification stricte, utilisée avant une release candidate, refuse les images de bootstrap et exige une génération Playwright réelle :

bun run docs:screenshots:strict

Les métadonnées sont enregistrées dans docs/public/guide/screenshots/manifest.json : version du package, locale, dimensions, taille et empreinte SHA-256 de chaque PNG.

La génération utilise un dossier de staging isolé sous test-results/guide-screenshots-staging. Les dossiers publics fr/ et en/ sont remplacés ensemble uniquement après validation des douze PNG. En cas d’échec ou d’interruption, les images déjà publiées et leur manifeste restent utilisables.

Bonnes pratiques

• utilisez uniquement des données anonymisées ou des domaines réservés comme example.invalid ;
• conservez un viewport, un thème et une police déterministes ;
• désactivez animations, transitions et curseurs de saisie ;
• ciblez les éléments avec des attributs data-qform-* stables ;
• ne mélangez pas ces images éditoriales avec les baselines toHaveScreenshot().