Catalogue Community : champs, statiques et structures

QForm Builder Community fournit un catalogue extensible construit exclusivement avec Quasar 2, FormKit et Vue 3. Les familles reprennent l'organisation habituelle d'un form builder professionnel : champs de saisie, contenus statiques et structures.

Champs inclus

• texte, zone de texte, nombre, e-mail, téléphone, mot de passe, URL et couleur ;
• éditeur de texte riche ;
• case à cocher, interrupteur, groupe de cases, groupe radio ;
• liste simple, liste multiple et boutons à choix ;
• date, dates multiples, plage de dates, heure et date/heure ;
• curseur, plage numérique et notation ;
• fichier, fichiers multiples et champ caché.

Chaque champ est rendu par un adaptateur FormKit utilisant un composant Quasar 2. Le schéma reste sérialisable en JSON.

Données du champ caché

Le champ q-hidden possède un panneau Données dédié. Il permet de définir :

Le layer pré-bundle @formkit/inputs, utilisé par la coercition numérique, afin que le premier affichage du panneau ne déclenche aucun rechargement Vite sous Windows.

• une valeur littérale texte ou numérique ;
• une expression FormKit commençant par $ ;
• la conversion numérique via la propriété FormKit number ;
• l’inclusion ou l’exclusion de la donnée soumise via ignore.

Les valeurs littérales sont conservées avec la clé de schéma __raw__value afin qu’une chaîne commençant par $ ne soit pas interprétée comme une expression. Le préfixe __raw__ appartient au schéma FormKit et n’est pas transmis comme nom de propriété au composant rendu. Les expressions sont bornées, validées et refusent les tokens globaux ou de prototype dangereux. Aucun code JavaScript libre n’est accepté par le panneau.

Exemple :

{
  $formkit: 'q-hidden',
  name: 'version',
  __raw__value: 1,
  number: 'float',
}

Pour exclure temporairement cette donnée du modèle soumis :

{
  $formkit: 'q-hidden',
  name: 'version',
  __raw__value: 1,
  ignore: true,
}

Contrôles dédiés :

bun run hidden-data:check
bun run e2e:hidden-data

Les champs fichier utilisent le type FormKit dédié q-file / QFile. Ils disposent d’un rendu Quasar cohérent, du glisser-déposer natif, des restrictions accept, maxFileSize, maxTotalSize et maxFiles, des chips et du compteur. Les schémas historiques basés sur q-input avec inputType: 'file' restent pris en charge par l’adaptateur de compatibilité. Les valeurs runtime sont des objets File ou File[] : le transfert vers Feathers/NFZ ou un stockage objet relève de l’application hôte et ne doit pas être confondu avec le schéma JSON du formulaire.

Contrat des adaptateurs Quasar 2

Les adaptateurs du catalogue suivent le contrat réel des composants Quasar 2 et ne transmettent plus de propriétés sans effet :

• QCheckbox, QToggle, QOptionGroup, QBtnToggle, QSlider, QRange, QRating et QEditor affichent libellé, aide et erreurs dans une couche de feedback commune, accessible et compatible dark mode ;
• les cases et interrupteurs conservent les valeurs personnalisées true-value / false-value au lieu de convertir systématiquement le modèle en booléen ;
• readonly est converti en disable pour les composants Quasar qui ne possèdent pas de propriété de lecture seule ;
• les curseurs normalisent min, max et step, y compris pour les schémas importés ;
• l’éditeur riche garde une valeur vide réelle : son placeholder n’est jamais enregistré comme contenu ;
• les champs date/heure respectent disable et readonly, exposent leur libellé et empêchent l’ouverture ou l’effacement depuis un picker verrouillé ;
• les boutons utilisent exclusivement les types natifs button, submit ou reset et ne stockent jamais l’événement de clic dans le modèle ;
• les attributs dynamiques commençant par on ainsi que les clés actives comme innerHTML sont filtrés avant transmission aux composants Quasar.

Les onglets activent les flèches de débordement sur petit écran et conservent l’état de leurs panneaux. Les colonnes, sections, fieldsets, champs cachés et textes d’aide disposent également d’un rendu clair/sombre harmonisé.

Contrôles dédiés :

bun run quasar-adapters:check
bun run quasar-adapters:runtime:check

Éléments statiques

• consentement de confidentialité obligatoire (privacy_consent) ;
• boutons submit, primaire, secondaire et danger ;
• séparateur et espaceur ;
• titres H1 à H6, paragraphe et citation ;
• lien et image ;
• bannières d'information et d'avertissement ;
• bloc de code.

Les liens, images et espaceurs disposent d'options dédiées dans le panneau de propriétés.

Structures

• section sous forme de QCard ;
• groupe sémantique fieldset ;
• colonnes responsives Quasar ;
• onglets Quasar ;
• formulaire en plusieurs étapes avec QStepper.

Les structures sont de vrais conteneurs éditables. Les sections, fieldsets, colonnes et onglets exposent des zones de dépôt imbriquées. Un champ peut être ajouté depuis le catalogue, déplacé d’une colonne vers une autre, remonté à la racine ou déplacé dans une autre structure, tout en conservant un schéma JSON sérialisable.

Glisser-déposer dans les conteneurs

Le type q-columns représente un conteneur composé de colonnes Quasar. Chaque colonne possède sa propre collection fields :

{
  $formkit: 'q-columns',
  name: 'contactColumns',
  columnsDefinition: [
    { name: 'identity', label: 'Identité', width: 6, fields: [] },
    { name: 'contact', label: 'Contact', width: 6, fields: [] },
  ],
}

Dans le builder :

1. déposer la structure Deux colonnes sur le canvas ;
2. déposer un champ directement dans la zone vide d’une colonne ;
3. déplacer ensuite le champ entre la racine, les colonnes, les sections, les fieldsets et les onglets ;
4. utiliser le libellé vert du conteneur pour sélectionner, déplacer ou supprimer la structure elle-même.

Le store localise récursivement chaque champ par son nom et bloque les déplacements cycliques, par exemple le déplacement d’un conteneur dans l’un de ses propres descendants. Les noms des champs ajoutés ou dupliqués sont normalisés récursivement pour rester uniques.

Contrôle dédié :

bun run nested:check

Sélectionner et configurer une colonne

Chaque colonne est maintenant un nœud éditable indépendant du conteneur q-columns. Cliquez sur son bandeau dans le canvas, ou sélectionnez-la depuis l’arborescence, pour ouvrir son panneau de configuration.

Options disponibles :

• nom technique unique dans le conteneur ;
• libellé, infobulle et description ;
• données imbriquées sous le nom de la colonne ;
• décorateurs texte avant, entre et après les champs ;
• largeur responsive distincte pour les vues par défaut, tablette et bureau ;
• héritage de largeur entre les breakpoints ;
• duplication et suppression de la colonne.

Le modèle JSON reste rétrocompatible avec l’ancienne propriété width et utilise désormais widths pour les breakpoints :

{
  name: 'identity',
  label: 'Identité',
  info: 'Informations personnelles',
  description: 'Champs relatifs à l’identité.',
  nestedData: true,
  before: 'Début de la colonne',
  between: 'Séparateur',
  after: 'Fin de la colonne',
  width: 6,
  widths: {
    default: 12,
    sm: 6,
    lg: 4,
  },
  fields: [],
}

Lorsque nestedData vaut true, les valeurs des champs de la colonne sont regroupées sous son nom dans le modèle FormKit.

Contrôle dédié :

bun run column:check

Enregistrement runtime FormKit

Les 24 types q-* du catalogue sont enregistrés par le formkit.config.ts du layer. Le nuxt.config.ts publié utilise un chemin absolu résolu depuis import.meta.url, ce qui empêche un fichier de configuration implicite du playground de masquer les nouveaux adaptateurs.

Contrôle :

bun run formkit:check

Personnaliser le catalogue

La prop catalog ajoute ou remplace des éléments :

<script setup lang="ts">
import { defineQFormElement } from '@vevedh/qform-builder-layer/catalog'

const customCatalog = [
  defineQFormElement({
    key: 'employeeId',
    category: 'fields',
    icon: 'badge',
    title: 'Matricule',
    description: 'Identifiant interne',
    schema: {
      $formkit: 'q-input',
      name: 'employeeId',
      label: 'Matricule',
      inputType: 'text',
    },
  }),
]
</script>

<template>
  <FormBuilder
    builder-id="employees"
    :catalog="customCatalog"
    catalog-mode="append"
  />
</template>

Modes disponibles :

• append : conserve le catalogue Community et surcharge les clés identiques ;
• replace : utilise uniquement le catalogue fourni par l'application.

Tester dans le playground

bun run clean && bun i && bun run typecheck && bun dev

Ouvrir ensuite :

http://localhost:3000/catalog

Designer de disposition des colonnes

Lorsque le conteneur q-columns est sélectionné, le panneau Disposition des colonnes permet maintenant de gérer la structure sans modifier le JSON manuellement.

Presets disponibles pour le viewport actif :

• une colonne 12/12 ;
• deux colonnes égales 6/12 + 6/12 ;
• colonne gauche étroite 4/12 + 8/12 ;
• colonne droite étroite 8/12 + 4/12 ;
• trois colonnes égales 4/12 ;
• quatre colonnes égales 3/12.

Le nombre de colonnes est ajusté automatiquement. Lorsqu'un preset réduit le nombre de colonnes, les champs des colonnes retirées sont déplacés dans la dernière colonne conservée : aucune donnée du schéma n'est supprimée.

Le panneau permet aussi de :

• ajouter une colonne ;
• déplacer une colonne vers la gauche ou la droite ;
• dupliquer une colonne et ses champs ;
• supprimer une colonne, sauf la dernière ;
• ouvrir directement les propriétés détaillées d'une colonne ;
• appliquer des largeurs différentes pour mobile, tablette et bureau.

Contrôle dédié :

bun run columns-layout:check

Les boutons de viewport sous Édition/Aperçu pilotent le même contexte responsive que le designer de colonnes.

Boutons QBtn : libellé, infobulle et description

Depuis la version 0.1.3, le panneau d’un bouton n’affiche plus deux propriétés concurrentes pour son texte. Le contenu visible du bouton est piloté uniquement par buttonLabel via Libellé du bouton.

La propriété Infobulle est enregistrée dans info et rendue avec un vrai composant Quasar enfant du bouton :

<q-btn :label="buttonLabel">
  <q-tooltip v-if="buttonTooltip">
    {{ buttonTooltip }}
  </q-tooltip>
</q-btn>

La valeur est interpolée par Vue et n’est jamais injectée comme HTML. description reste affichée séparément sous le bouton. Pour les anciens schémas, label reste accepté uniquement comme repli runtime lorsque buttonLabel est absent.

Infobulles communes à tous les éléments

Depuis la version 0.1.5, le champ Infobulle est disponible par défaut dans les panneaux de propriétés. Sa valeur est stockée dans info.

Dans l’aperçu du builder, dans les conteneurs imbriqués, dans les étapes et dans FormViewer, le survol de l’élément complet déclenche un composant Quasar natif :

<div class="form-field">
  <FormKitSchema :schema="field" />
  <q-tooltip v-if="field.info">
    {{ field.info }}
  </q-tooltip>
</div>

Le QTooltip est enfant direct de sa cible DOM ou Quasar. Les champs ordinaires utilisent le conteneur .form-field. Les éléments qui contiennent eux-mêmes des champs — q-section, q-fieldset, q-columns, q-tabs-structure et q-stepper — possèdent une cible dédiée dans leur en-tête ou légende afin qu’une infobulle parente ne concurrence pas celles des enfants. q-btn conserve également sa cible spécialisée : le QTooltip reste enfant direct du QBtn. Les textes statiques et les colonnes n’utilisent plus une petite icône d’information séparée ; toute leur surface pertinente devient la cible de survol.

La route de playground /qtooltip-audit et le scénario Playwright associé vérifient les familles génériques, QBtn, QBtnToggle, les contenus statiques et toutes les structures. Le gate tooltip:check analyse aussi chaque SFC pour interdire v-show sur QTooltip et détecter une infobulle placée sous un <template> au lieu d’une cible concrète.

Le contenu est trimé, borné et interpolé par Vue. Ne jamais utiliser v-html pour une valeur provenant d’un schéma.

Options avancées QEditor, QSelect et QRating

La version 0.1.2 ajoute des panneaux dédiés aux trois composants dont le contrat Quasar est le plus riche.

QEditor

• presets de barre d'outils minimal, standard et full ;
• balise de paragraphe div ou p ;
• hauteur minimale, maximale ou fixe avec tailles CSS contrôlées ;
• mode dense, plat, carré et styles des boutons de toolbar ;
• couleurs de fond, texte, état actif et couleur générale.

QSelect

• sélection simple ou multiple et normalisation automatique du modèle ;
• chips, recherche locale, debounce et nombre maximal de valeurs ;
• emit-value, map-options, option-label, option-value et option-disable ;
• comportement automatique, menu ou dialogue ;
• création contrôlée de nouvelles valeurs ;
• rendu HTML des options volontairement désactivé pour éviter qu'un schéma sérialisable introduise du contenu actif.

QRating

• nombre d'icônes de 1 à 100 ;
• taille, icône vide, sélectionnée et intermédiaire ;
• couleurs distinctes ;
• libellé ARIA ;
• options no-reset et no-dimming.

Les helpers de normalisation sont publics :

import {
  filterQFormBuilderSelectOptions,
  normalizeQFormBuilderCssSize,
  normalizeQFormBuilderSelectModel,
  resolveQFormBuilderEditorToolbar,
} from '@vevedh/qform-builder-layer/quasar-options'

Contrôles dédiés :

bun run quasar-advanced:check
bun run quasar-advanced:runtime:check

Indicateur de dépôt unique

À la frontière de deux champs, une même position logique pouvait auparavant être représentée par la zone « après » du premier champ et la zone « avant » du second. Les deux libellés Déposez ici pouvaient alors être visibles simultanément.

Ce comportement n'était pas normal. L'indicateur actif est maintenant identifié par le conteneur cible, le champ de référence et sa position exacte before ou after. Une seule ligne est rendue pour une destination de dépôt.

Contrôle dédié :

bun run drop-indicator:check

Scénarios visuels Playwright

La route de playground suivante couvre le rendu runtime, les panneaux avancés et l'indicateur de dépôt :

http://localhost:3000/quasar-advanced

Commandes :

bun run e2e:visual:update  # créer ou valider de nouvelles références
bun run e2e:visual         # détecter une régression visuelle
bun run e2e:report         # ouvrir le rapport HTML

Les captures de référence ne doivent être régénérées qu'après vérification visuelle intentionnelle. Pour créer un composant métier et son panneau associé, consultez le guide composants et panneaux custom.