Stabilité de l’API publique

QForm Builder Community 0.1.20 a introduit le gel candidat de son API publique avant 1.0.0-rc.1. Les versions 0.1.21 à 0.1.30 conservent cette surface à l’identique. 0.1.21 ajoute sa vérification dans le registre de preuves de release ; 0.1.22 corrige la synchronisation interne des valeurs d’aperçu ; 0.1.23 stabilise la transition interne du panneau droit ; 0.1.24 fiabilise la sélection interne des champs interactifs du canvas ; 0.1.25 conserve les valeurs après soumission ; 0.1.26 stabilise uniquement le harness Playwright et les chemins Windows, 0.1.27 ajoute le pipeline documentaire Playwright et des sélecteurs DOM internes, et 0.1.28 stabilise sa fixture, ses délais et la publication atomique. 0.1.29 ne modifie que le cadrage Playwright de la timeline. 0.1.30 stabilise le packaging et la publication npm sans ajouter de prop, événement, méthode ni type public.

Le gel couvre les frontières consommées par une application Nuxt hôte :

• les sous-chemins déclarés dans package.json#exports ;
• les props, événements et méthodes exposées par FormBuilder ;
• les props, le modèle et l’événement submit de FormViewer ;
• les types exportés par @vevedh/qform-builder-layer/types ;
• le sous-chemin runtime @vevedh/qform-builder-layer/contract.

Manifeste machine-readable

Le fichier canonique est publié dans le package :

public-api.manifest.json

Il est également accessible avec le sous-chemin :

import manifest from '@vevedh/qform-builder-layer/contract-manifest'

Selon la configuration TypeScript du consommateur, l’import JSON peut nécessiter resolveJsonModule ou un attribut d’import JSON. Pour un usage runtime sans JSON, employer :

import {
  QFORM_BUILDER_PUBLIC_API_CONTRACT_VERSION,
  QFORM_BUILDER_PUBLIC_API_STATUS,
  qFormBuilderPublicApiContract,
} from '@vevedh/qform-builder-layer/contract'

Contrats de composants réutilisables

Les props et événements ne sont plus définis uniquement dans le SFC. Ils sont exportés comme types publics :

import type {
  FormBuilderEvents,
  FormBuilderProps,
  FormBuilderPublicApi,
  FormViewerEvents,
  FormViewerProps,
} from '@vevedh/qform-builder-layer/types'

Le composant FormBuilder.vue consomme directement FormBuilderProps et FormBuilderEvents. Le type FormBuilderPublicApi est comparé aux méthodes réelles de defineExpose(). Le manifeste conserve aussi des empreintes SHA-256 normalisées des cinq interfaces de composants et de chaque source publique dans app/types*. Une modification d’optionalité, de type ou de signature est donc détectée même si le nom du membre reste identique.

Contrôle automatique

bun run api:contract:check
bun run typecheck:contract

api:contract:check reconstruit la surface réelle depuis le code et la compare exactement au manifeste commité. Il échoue en cas :

• de suppression ou ajout non examiné d’un sous-chemin npm ;
• de modification des props ou événements ;
• de dérive entre FormBuilderPublicApi et defineExpose() ;
• de modification de la liste ou de la signature des types publics ;
• de manifeste non synchronisé avec la version du package.

Les empreintes des sources de types sont volontairement conservatrices : une modification d’un fichier public doit être revue et acceptée explicitement, même lorsque le changement semble compatible.

typecheck:contract compile un consommateur externe qui n’importe que les sous-chemins publics. Il empêche un export déclaré mais inutilisable de passer la release.

Mise à jour intentionnelle

Une évolution volontaire suit ce processus :

bun run api:contract:update
git diff -- public-api.manifest.json
bun run api:contract:check
bun run typecheck:contract

La commande de mise à jour n’est jamais appelée par la CI ou par une gate de release. Le diff doit être revu explicitement.

Politique SemVer

Avant 1.0.0, le statut est candidate-frozen :

• une correction interne sans changement de surface reste un patch ;
• une addition publique compatible exige une revue du manifeste et du contrat consommateur ;
• une suppression, un renommage ou une incompatibilité de type est interdit avant la RC, sauf décision explicite accompagnée d’une migration.

À partir de 1.0.0, une rupture de cette surface exige une version majeure. Les formats persistés restent gouvernés séparément par les versions de document, schéma et thème.

Gate de release candidate

bun run release:candidate:check

Cette commande enchaîne la qualité complète, les baselines, les scénarios Chromium et la création du package npm vérifié. Le workflow GitHub Actions expose aussi un job final Release candidate gate, qui ne devient vert qu’après les jobs qualité, navigateur et package.