Audit global produit et préparation du module Nuxt — 0.1.29

Date de référence : 28 juin 2026
Version auditée : QForm Builder Community 0.1.29
Nature de l’audit : produit, architecture, packaging Community, frontières Pro/serveur et préparation d’un module Nuxt 4.

Conclusion exécutive

QForm Builder Community n’est plus un prototype. Le dépôt contient un constructeur visuel complet, un viewer runtime, un contrat public gelé, des moteurs purs exportés, une documentation bilingue et une chaîne de qualité significative.

La situation peut être résumée ainsi :

Périmètre	État	Décision
Fonctionnalités Community	complet sur le périmètre Phase 2	exploitable comme Nuxt Layer
API publique	gel candidat	base suffisamment stable pour une seconde distribution
Packaging Nuxt Layer	mature	conserver comme branche/package de compatibilité
Packaging module Nuxt	non implémenté	la phase M1 peut commencer maintenant
Publication immédiate d’un module stable	prématurée	commencer en 0.x/alpha, sans remplacer le layer
Code Pro caché dans Community	absent	frontière open-core saine
Reproductibilité RC	incomplète	régénérer bun.lock, CI distante et preuves navigateur

Décision recommandée : ouvrir maintenant un nouveau package module sous un autre nom, sans modifier le contrat fonctionnel et sans déprécier le layer actuel. La première version du module doit être une migration de packaging, pas une nouvelle phase fonctionnelle.

1. Inventaire technique vérifié

Le dépôt audité contient :

• 85 composants Vue ;
• 72 fichiers TypeScript dans app/ ;
• environ 25 000 lignes Vue/TypeScript/SCSS dans le runtime ;
• 51 éléments Community ;
• 24 adaptateurs FormKit/Quasar ;
• 29 props, 30 événements et 27 méthodes publiques pour FormBuilder ;
• 149 types publics ;
• 20 sous-chemins npm ;
• 9 scénarios E2E, 1 scénario documentaire Playwright ;
• 22 pages de playground ;
• 82 pages Markdown FR/EN dans le dépôt ;
• 101 documents de mémoire de patch ;
• 335 fichiers dans le tarball npm prévu.

L’architecture actuelle est celle d’un Nuxt Layer :

app/
├── accessibility/
├── catalog/
├── components/
│   ├── builder/
│   ├── quasar/
│   └── settings/
├── composables/
├── conditions/
├── contract/
├── history/
├── locales/
├── migrations/
├── quasar-options/
├── stores/
├── templates/
├── theme/
├── tree/
├── types/
├── utils/
└── validation/

Cette séparation est déjà proche d’un futur src/runtime/, mais elle dépend encore de la convention de scan d’un layer.

2. Fonctionnalités incluses dans Community

2.1 Intégration et composants publics

Community fournit :

• installation comme Nuxt Layer npm via extends ;
• FormBuilder autonome ;
• FormViewer indépendant ;
• isolation multi-instance par builder-id ;
• modèles contrôlés schema, values, settings, thème et ouverture des panneaux ;
• API impérative via ref ;
• événements complets de sauvegarde, import/export, champs, historique, templates et erreurs ;
• application hôte de validation avec SSR activé ;
• styles scoped et dépendances déclarées en peer dependencies.

2.2 Catalogue Community : 51 éléments

27 champs

Famille	Éléments
Saisie	texte, zone de texte, nombre, e-mail, téléphone, mot de passe, URL
Couleur et contenu	couleur QColor, éditeur riche QEditor
Booléens et choix	case à cocher, interrupteur, groupe de cases, groupe radio, liste, liste multiple, boutons toggle
Dates et temps	date, dates multiples, plage de dates, heure, date-heure
Valeurs numériques	slider, range slider, rating
Fichiers et technique	fichier, fichiers multiples, champ caché

19 contenus statiques

• bouton de soumission ;
• bouton primaire ;
• bouton secondaire ;
• bouton destructif ;
• séparateur ;
• espaceur ;
• titres H1 à H6 ;
• paragraphe ;
• citation ;
• lien sécurisé ;
• image ;
• bannière d’information ;
• bannière d’avertissement ;
• bloc de code.

5 structures

• section ;
• fieldset ;
• colonnes responsives ;
• onglets ;
• stepper/pages.

2.3 Éditeur visuel

Le builder inclut :

• catalogue Champs/Statiques/Structures ;
• ajout et drag-and-drop racine ou imbriqué ;
• déplacement et copie entre conteneurs ;
• prévention des cycles ;
• indicateur de dépôt unique avant/après ;
• sélection du champ par overlay et délégation d’événements ;
• panneau de propriétés spécifique au type ;
• renommage atomique et maintien des références ;
• simulation mobile/tablette/bureau ;
• designer de colonnes avec presets, duplication, réordonnancement et conservation des enfants ;
• modes édition et aperçu ;
• panneau Informations synchronisé avec les valeurs runtime ;
• conservation des données après finalisation.

2.4 Steps/pages

Community gère :

• ajout et renommage ;
• réordonnancement ;
• duplication récursive ;
• suppression sûre ;
• validation de l’étape ;
• état valide/invalide visible ;
• blocage du passage à l’étape suivante ;
• bouton final de soumission ;
• retour aux étapes avec valeurs conservées ;
• conditions sur les étapes.

2.5 Conditions avancées

Le moteur Community inclut :

• arbre logique sérialisable ;
• groupes ET/OU récursifs ;
• opérateurs selon le type de champ ;
• éditeurs de valeurs typés ;
• normalisation, parsing, sérialisation et évaluation purs ;
• simulateur sans mutation des données réelles ;
• trace récursive explicable ;
• maintenance des références lors du renommage/suppression ;
• intégration aux propriétés FormKit if, disabled, readonly et validation conditionnelle.

2.6 Validation avancée

Community inclut :

• règles FormKit natives typées ;
• required, longueurs, minimum, maximum, format et consentement ;
• expressions régulières contrôlées ;
• rejet de motifs dangereux courants ;
• messages personnalisés et localisés ;
• comparaison inter-champs ;
• registre public de règles personnalisées ;
• handlers synchrones ou asynchrones ;
• protection des règles natives internes contre le remplacement par le consommateur.

2.7 Historique et arborescence

L’historique fournit :

• undo/redo ;
• timeline visible et localisée ;
• coalescence des modifications rapides ;
• branches futures supprimées après une nouvelle mutation ;
• profondeur configurable de 2 à 500 ;
• raccourcis clavier protégés ;
• restauration explicite créant une nouvelle action annulable ;
• isolation par instance.

L’arborescence fournit :

• représentation récursive via QTree ;
• synchronisation de la sélection ;
• drag-and-drop inter-conteneurs ;
• prévention des cycles ;
• menus contextuels ;
• actions accessibles ;
• réordonnancement clavier avec restitution du focus.

2.8 Theme Builder

La fonctionnalité est déjà Community, malgré certaines anciennes pages de roadmap qui la présentaient encore comme Pro.

Elle inclut :

• cinq presets plus un mode personnalisé ;
• palette et variantes ;
• typographie ;
• espacements et densité ;
• rayons ;
• dégradés linéaires/radiaux ;
• effets de profondeur ;
• mouvement compatible prefers-reduced-motion ;
• six rôles d’icônes ;
• Quasar/Iconify/MDI hors ligne ;
• QIconPicker avec catalogue contrôlé ;
• preview en direct ;
• mêmes tokens pour Builder et Viewer ;
• cohérence clair/sombre.

2.9 Templates, import/export et migrations

Community inclut quatre templates :

1. contact simple ;
2. enquête de satisfaction ;
3. formulaire d’administration CRUD ;
4. onboarding multi-étapes.

Le registre supporte append/replace, la recherche, les collisions de noms et la réécriture des références.

La persistance frontend fournit :

• import/export du schéma ;
• document canonique complet : schéma, valeurs, réglages, thème ;
• presse-papiers, texte et fichier ;
• autosave local ;
• assainissement des entrées ;
• limites de taille et profondeur ;
• blocage de __proto__, prototype, constructor ;
• versions indépendantes document/schéma/thème ;
• registre public de migrations ;
• rejet des versions futures.

2.10 Extensibilité publique

Community expose déjà les points nécessaires à des extensions séparées :

• catalog et catalog-mode ;
• defineQFormElement() ;
• config-panels avec matcher, priorité et composant hôte ;
• registre de validation ;
• registre de templates ;
• registre de locales ;
• moteur de thème ;
• moteur de conditions ;
• moteur de migrations ;
• helpers d’historique et d’arborescence ;
• props, événements et méthodes impératives.

2.11 Qualité, accessibilité et documentation

Le dépôt inclut :

• TypeScript strict séparé Nuxt/E2E/contrat consommateur ;
• contrat API machine-readable et empreintes SHA-256 ;
• tests runtime purs ;
• Playwright Chromium ;
• snapshots visuels ;
• audit axe WCAG A/AA jusqu’à 2.2 AA ;
• navigation clavier ;
• régions live et restitution du focus ;
• matrice GitHub Actions Windows/Linux ;
• build d’une application Nuxt hôte SSR ;
• budget de bundle ;
• génération d’un tarball vérifié ;
• documentation VitePress FR/EN ;
• guide illustré Playwright FR/EN avec manifeste SHA-256.

3. Fonctionnalités gérées par le dépôt mais non livrées comme fonctionnalités runtime Community

Cette catégorie ne correspond pas à du code Pro caché. Il s’agit d’outillage, de contrats d’extension ou de patterns présents dans le dépôt sans devenir une fonctionnalité autonome pour l’utilisateur final.

3.1 Outillage exclu du tarball runtime

Les éléments suivants sont gérés et testés dans le dépôt, mais volontairement exclus du package npm :

• .playground et ses 22 routes ;
• les tests E2E et documentaires ;
• l’application hôte SSR de test ;
• les workflows GitHub Actions ;
• la mémoire détaillée des patchs ;
• les traces et rapports Playwright ;
• les archives de diagnostic ;
• les fichiers de consignes internes.

Le tarball publie le runtime, les types, les moteurs, les scripts de vérification et la documentation, mais pas les applications de test.

3.2 Persistance Feathers/NFZ

Le cycle est géré au niveau du contrat :

• payload save ;
• import/export versionné ;
• événements ;
• documentation de repository ;
• exemple RBAC/verrouillage optimiste ;
• modèle de service forms.

En revanche, Community ne livre pas :

• service Feathers prêt à déployer ;
• modèle MongoDB ;
• hooks RBAC ;
• validation Zod serveur ;
• gestion des propriétaires/workspaces ;
• versioning métier persistant ;
• journal d’audit serveur.

Cette séparation est saine : le package frontend ne doit pas imposer une architecture backend.

3.3 Upload de fichiers

Le champ QFile gère :

• sélection simple/multiple ;
• limites de taille/nombre ;
• types acceptés ;
• capture ;
• chips, compteur et nettoyage ;
• normalisation du modèle.

Il ne livre pas :

• stockage S3/MinIO ;
• upload multipart ;
• antivirus ;
• reprise d’upload ;
• service Feathers de fichiers ;
• URLs signées.

3.4 Règles asynchrones

Le registre accepte des handlers asynchrones, mais le package ne fournit pas un orchestrateur métier distant : debounce réseau, annulation, authentification, cache, observabilité et mapping d’erreurs backend restent à la charge de l’application hôte.

3.5 Actions des boutons

Les boutons sont rendus, configurables et accessibles. Le package ne fournit pas de moteur de workflow générique pour associer un bouton à :

• un appel de service ;
• une navigation ;
• un webhook ;
• une approbation ;
• une action métier transactionnelle.

3.6 SSR

Le dépôt valide qu’une application hôte avec ssr: true peut construire le layer. Cela constitue une compatibilité de build. Le builder reste fortement interactif et utilise drag-and-drop, stockage navigateur et APIs DOM ; son usage SSR doit donc rester encapsulé ou hydraté côté client selon le contexte. Le viewer est le meilleur candidat pour un rendu SSR plus ambitieux.

3.7 Extensions futures déjà anticipées

Les points d’extension actuels permettent déjà d’ajouter dans un package séparé :

• éléments métier ;
• panneaux spécialisés ;
• règles distantes ;
• packs de templates ;
• presets de thème ;
• migrations additionnelles ;
• opérateurs métier.

La mécanique d’accueil existe ; le contenu Pro/métier n’est pas dans Community.

4. Fonctionnalités non incluses et non encore implémentées

Les éléments suivants restent de vraies phases futures :

Domaine	État réel
Module Nuxt 4 modules: []	non implémenté ; seul le layer existe
Adaptateur Zod → schéma QForm	non implémenté
Import JSON Schema → schéma QForm	non implémenté
Service NFZ/Feathers → formulaire	non implémenté
Formulaire → service CRUD NFZ	non implémenté
Export de composant Vue/TypeScript	non implémenté
Génération de page Nuxt/Quasar	non implémentée
Mode headless/canvas seul	non implémenté
Packs métier versionnés	non implémentés hors quatre templates génériques
description métier → formulaire	non implémentée
Collaboration temps réel	non implémentée
Publication/approbation multi-acteurs	non implémentée
RBAC et audit persistant	documentés mais non livrés
Marketplace de composants	non implémentée
Workflow/webhooks	non implémentés

5. Frontière Community / Pro recommandée

Aucun contrôle de licence ni code commercial dormant n’a été détecté dans app/. La licence du package reste MIT et le code Community est directement utilisable.

La frontière recommandée est :

Community

• builder et viewer ;
• catalogue générique ;
• structures, validation, conditions, historique, arbre, thème ;
• import/export/migrations ;
• extensibilité publique ;
• accessibilité ;
• docs et outils de qualité.

Package métier ou Pro séparé

• adaptateurs Zod/JSON Schema/NFZ ;
• générateur CRUD ;
• packs métier avec ressources et miniatures ;
• export de code/page ;
• moteur de workflow ;
• collaboration ;
• audit/versioning serveur ;
• Génération guidée ;
• fonctions de gouvernance entreprise.

Backend séparé

• licences ;
• RBAC ;
• audit immuable ;
• stockage de fichiers ;
• antivirus ;
• exécution de règles sensibles ;
• webhooks ;
• publication et approbation ;
• secrets et intégrations tierces.

6. Incohérences documentaires identifiées

Trois documents historiques avaient pris du retard sur le code :

1. pro-roadmap.md listait encore Theme Builder, conditions, validation avancée, templates et historique comme priorités Pro alors qu’ils sont maintenant inclus dans Community ;
2. future-nuxt-module.md proposait encore installModule() et présentait certaines fonctions déjà terminées comme futures ;
3. features-vs-vueform-builder.md indiquait encore que le projet forçait ssr:false, alors que le layer ne le force plus et qu’une application hôte SSR est construite dans la CI.

Ces pages doivent être maintenues comme des documents de l’état courant, pas comme des archives de décisions anciennes.

7. Le projet est-il prêt à entrer en phase module Nuxt ?

Réponse : oui pour démarrer M1, non pour publier immédiatement une version stable

Forces permettant de commencer maintenant

• API publique gelée et surveillée ;
• composants publics clairement identifiés ;
• moteurs purs déjà séparés ;
• types et sous-chemins exportés ;
• aucune dépendance backend obligatoire ;
• package Community sans code de licence caché ;
• application hôte indépendante ;
• tests multi-OS et Chromium ;
• documentation d’intégration ;
• séparation Builder/Viewer déjà conceptuelle ;
• runtime majoritairement dans app/, donc migration mécanique possible vers src/runtime/.

Bloqueurs avant une publication module stable

1. Lockfile obsolète : le contrôle détecte encore des dépendances absentes et des entrées racine périmées.
2. Absence de src/module.ts compilé : l’entrée actuelle est un nuxt.config.ts de layer publié brut.
3. Enregistrement FormKit lié à #components : il faut garantir l’ordre d’enregistrement dans le module ou générer une configuration runtime dédiée.
4. Auto-imports hérités du layer : stores, composables et utils doivent être déclarés explicitement avec Nuxt Kit ou importés directement.
5. Composants internes globalement scannés : le module doit n’exposer globalement que l’API voulue et éviter de polluer l’application hôte avec 85 noms.
6. Chemins de styles : remplacer la normalisation manuelle d’URL Windows par createResolver(import.meta.url) dans le module.
7. Dépendances de modules : déclarer Pinia, FormKit, Quasar et UnoCSS via le contrat moderne de dépendances du module, avec options et compatibilités.
8. Sortie npm : publier dist/module.mjs, types et runtime compilés plutôt que des sources layer comme entrée principale.
9. Imports publics et renommage : migrer tous les exemples, tests de contrat, docs et manifests vers le nouveau nom sans casser l’ancien package.
10. Validation consommateur : ajouter des tests d’installation du tarball module dans une application Nuxt vierge, avec SSR, Windows et Linux.

8. Architecture cible recommandée

Le meilleur compromis est un monorepo ou un dépôt multi-packages :

packages/
├── qform-core/
│   ├── catalog/
│   ├── conditions/
│   ├── history/
│   ├── migrations/
│   ├── schema-transfer/
│   ├── templates/
│   ├── theme/
│   ├── tree/
│   ├── types/
│   └── validation/
├── qform-runtime/
│   ├── components/
│   ├── composables/
│   ├── stores/
│   └── assets/
├── nuxt-form-builder/
│   ├── src/module.ts
│   └── src/runtime/
└── qform-builder-layer/
    └── wrapper de compatibilité temporaire

playground/
docs/
tests/

Une migration plus simple peut garder un seul package module avec src/runtime/, mais l’extraction du core pur réduit le couplage et prépare les extensions Pro/serveur.

9. Nom du futur module

Le nom actuel peut être confondu avec le composant QForm de Quasar. Une distribution module distincte peut utiliser un nom plus explicite.

Recommandation technique :

@vevedh/nuxt-form-builder

Alternatives de marque :

@vevedh/nuxt-form-studio
@vevedh/nuxt-schema-form
@vevedh/nfz-form-studio

Le choix recommandé pour un produit générique est @vevedh/nuxt-form-builder. NFZ Form Studio convient mieux à une édition métier intégrée à NFZ Studio. La disponibilité npm et les conflits de marque doivent être vérifiés avant publication.

10. Options du futur module

export interface NuxtFormBuilderModuleOptions {
  prefix?: string
  locale?: 'fr' | 'en'
  injectCss?: boolean
  components?: {
    builder?: boolean
    viewer?: boolean
  }
  dependencies?: {
    pinia?: boolean
    formkit?: boolean
    quasar?: boolean
    unocss?: boolean
  }
  quasar?: {
    iconSet?: string
    animations?: 'all' | string[]
  }
}

Principes :

• options sérialisables ;
• pas de code métier dans module.ts ;
• dépendances installées/configurées de façon déclarative ;
• FormBuilder et FormViewer activables séparément ;
• préfixe public configurable ;
• composants internes non exposés globalement ;
• CSS injectable ou importable manuellement ;
• aucune décision SSR imposée à l’hôte.

11. Plan de migration proposé

M0 — sécuriser la référence layer

• régénérer et valider bun.lock ;
• obtenir plusieurs CI distantes vertes ;
• générer les vraies baselines et captures documentaires ;
• publier 1.0.0-rc.1 du layer ou figer une référence 0.1.x documentée.

M1 — créer le squelette module

• nouveau package et nouveau nom ;
• module starter officiel ;
• src/module.ts ;
• src/runtime/ ;
• build avec module-builder ;
• playground module minimal ;
• aucun changement fonctionnel.

M2 — migrer le runtime

• moteurs purs ;
• types ;
• composants ;
• stores/composables ;
• styles ;
• configuration FormKit ;
• enregistrement Quasar/UnoCSS.

M3 — options et distribution sélective

• préfixe ;
• CSS ;
• locales ;
• Builder/Viewer séparés ;
• dépendances optionnelles ;
• alias runtime publics contrôlés.

M4 — compatibilité

• test d’une application vierge ;
• test SSR ;
• test Windows/Linux ;
• test tarball installé ;
• comparaison du contrat public layer/module ;
• guide de migration.

M5 — publication

• 0.1.0-alpha.x du module ;
• intégration dans une application métier réelle ;
• 0.1.0-rc.x ;
• version stable seulement après retours réels.

12. Verdict final

Le produit est fonctionnellement prêt pour entrer dans la phase module. Les risques ne sont plus principalement fonctionnels ; ils concernent le packaging, l’ordre d’installation des dépendances, l’enregistrement FormKit/Quasar, les auto-imports et la compatibilité de distribution.

La stratégie recommandée est donc :

conserver le layer stable
        +
créer un module sous un nouveau nom
        +
réutiliser exactement le même runtime et le même contrat
        +
ne commencer les fonctions Phase 3 qu’après la parité module

Le module ne doit pas être présenté comme une réécriture. Il doit être une nouvelle enveloppe officielle autour d’un cœur Community déjà mature.