Bricks

Une brick est un nœud d’un spec de formulaire — un champ, un conteneur de mise en page, ou un élément d’affichage. Trente sont livrées d’origine, et le registre qui les contient est ouvert : vos propres bricks s’enregistrent de la même façon et apparaissent dans la même palette.

Le catalogue intégré

Inputs

id de brick	Type de données	Notes
text, textarea, password	string	text accepte les masques et les adornments
email, url, phone	string	à associer aux validateurs correspondants
number	number	min / max / step
date, time, datetime	string	sélecteurs natifs
select, radio	string	choix unique
multi-select, select-boxes, tags	array	choix multiple
checkbox	boolean	libellé en ligne
signature	string	canvas, stocké en data URL
address	object	champ composite
code	string	CodeMirror, chargé en lazy
geo-point	object	Point GeoJSON : clic sur la carte ou saisie latitude / longitude ; Leaflet chargé à la demande, tuiles OpenStreetMap par défaut
geo-area	object	Polygon ou LineString GeoJSON (shape) : clic pour ajouter des sommets, glisser pour déplacer, clic droit pour retirer
geo-address	object	recherche d’adresse pendant la frappe (Nominatim par défaut, searchUrl avec {q}), stockée en Feature GeoJSON avec l’adresse normalisée et son point, ajustable sur une carte
geo-layer	object	une zone choisie sur une couche de référence (layerUrl, FeatureCollection GeoJSON ; codeProperty / nameProperty), stockée en { code, name }, en tableau avec multiple ; une liste déroulante propose les zones sans la carte
national-id	string	identifiant national contrôlé par idFormat : fr-nir (13 chiffres + clé), bj-npi (10 chiffres), digits-<n>
mrz	object	zone de lecture d’un passeport (2 × 44) ou d’une carte d’identité (3 × 30) : champs lus, chaque chiffre de contrôle ICAO 9303 vérifié, le formulaire refuse une zone incohérente
tax-id	string	identifiant fiscal contrôlé par idFormat : bj-ifu (13 chiffres), fr-siren / fr-siret (clé de Luhn), digits-<n>
iban	string	IBAN contrôlé selon ISO 7064 mod 97-10, groupé par quatre à la sortie du champ
money	object	{ amount, currency }, la devise choisie parmi currencies, currency par défaut
appointment	object	un créneau { id, start, end } choisi jour par jour, depuis slotsUrl (liste avec remaining) ou généré par des règles d’ouverture (days, from, to, duration, horizonDays, noticeHours, exclude)
date-range	object	{ from, to }, la fin jamais avant le début
document	object	un document scanné ou déposé, lu par l’hôte (services.documentReaderService, readUrl) : le texte lu, les fields demandés (`clé
measure	object	{ value, unit, base } : un nombre et son unité dans une family (length, area, mass, volume, duration), units restreignant le choix, base gardant la valeur dans l’unité de base de la famille (m, m², kg, l, h) pour totaliser des unités différentes
vehicle-plate	string	immatriculation contrôlée par plateFormat (fr, bj, ci, sn, generic), en majuscules à la saisie et mise en forme à la sortie du champ
company-registry	string	numéro d’immatriculation d’entreprise contrôlé par registryFormat (ohada-rccm, fr-rcs, generic)

Data

id de brick	Type	Notes
file	input / object	upload pluggable, uploadUrl par brick, mode multiple
data-grid	collection / array	lignes répétées avec validation par ligne
key-value	input / object	un objet plat édité ligne par ligne (keyLabel, valueLabel) ; les valeurs acceptent les variables du contexte comme un champ texte
hidden	input / string	porte une valeur sans rien afficher

Layout

id de brick	Type	Notes
group, row, column	panel	conteneurs fieldset et flex
stepper	panel	wizard avec validation par étape
tabs	panel	validation optionnelle avant de quitter l’onglet
nested-form	panel	référence un autre formulaire par specRef
content	output	texte riche statique
recap	output	résumé vivant de tout le formulaire

Comportements à connaître

Select et multi-select

Un combobox avec recherche qui implémente le pattern WAI-ARIA complet — navigation clavier, gestion du focus, annonces aux lecteurs d’écran. Les options proviennent de cinq sources :

optionsSource	D’où viennent les options
static	une chaîne séparée par des retours à la ligne, ou des objets { label, value }
dataMap	la valeur d’un autre champ du même formulaire
remote	une URL, avec interpolation {key} et {a.b} depuis le contexte et les données, plus recherche côté serveur optionnelle
catalog	une liste partagée résolue via optionSourceService
js	un snippet sandboxé qui renvoie la liste

labelKey et valueKey acceptent les chemins pointés : name.common lit donc une propriété imbriquée de chaque objet option.

Astuce

Pour les listes longues — pays, professions — préférez remote ou catalog à static. Cela garde le spec léger et la liste éditable à un seul endroit. Le convertisseur Form.io émet un avertissement au-delà de 100 options statiques.

Data grid

Le template de ligne s’édite comme n’importe quel panel ; au rendu, chaque ligne scope ses propres données. minItems / maxItems valident le nombre de lignes, les lignes se réordonnent avec des boutons haut/bas accessibles, et les erreurs sont rapportées sous la forme contacts[0].email.

Stepper et tabs

Les deux conditionnent la navigation à la validation. stepper valide l’étape courante avant d’avancer et peut émettre formSubmit depuis un bouton Submit final. tabs propose la même chose en option, plus la navigation aux flèches entre onglets.

Text et phone

Adornments prefix / suffix optionnels, plus une config mask :

Jeton de masque	Accepte
9	un chiffre
a	une lettre
A	une lettre, mise en majuscule
*	alphanumérique

Tout autre caractère est un littéral et s’insère tout seul — avec le masque +229 99 99 99 99, l’utilisateur ne tape que les chiffres : le préfixe et les espaces apparaissent d’eux-mêmes.

Recap

Un résumé vivant, en lecture seule, de tout ce qui a été rempli jusqu’ici. groupBySections transforme les panels labellisés en sections titrées, et les collections se rendent en tableaux — pratique comme dernière étape d’un wizard.

Enregistrer votre propre brick

createBrick renvoie une brick que le registre accepte. La fonction render reçoit les props de la brick et renvoie un nœud virtuel :

1. Décrivez-la et rendez-la.

   rating-brick.tsx

   import { createBrick, h, registerBrick } from '@streamline-pulse/formkrafter-wc'
   
   export const ratingBrick = createBrick({
     type: 'input',
     dataType: 'number',
     id: 'rating',
     name: 'Rating',
     category: 'Inputs',
     defaultConfigs: { label: 'Note' },
     render: (props) =>
       h(
         'div',
         { class: { 'fk-field': true } },
         ...[1, 2, 3, 4, 5].map((star) =>
           h(
             'button',
             {
               type: 'button',
               'aria-label': `${star} étoiles`,
               onClick: () => props.onDataChange?.(star),
             },
             star <= Number(props.data ?? 0) ? '★' : '☆'
           )
         )
       ),
   })

2. Enregistrez-la une fois, avant le montage du builder.

   registerBrick(ratingBrick)

3. Elle apparaît désormais dans la palette sous sa category, et se rend partout où un spec utilise "id": "rating".

Note

h et le type VNode sont réexportés par formkrafter-wc : votre application n’a besoin d’aucune dépendance Stencil. renderBuilder est optionnel — fournissez-le quand la brick doit avoir une apparence différente en cours d’édition.

Attention

Le registre est un singleton à l’échelle de la page (partagé via globalThis, comme les services). Enregistrez une brick une seule fois au démarrage ; enregistrer deux fois le même type:id remplace le premier.

Étapes suivantes

Specs de formulaireComment les bricks se composent en arbre, et les ops qui l'éditent.

ValidationAttacher des validateurs à n'importe quelle brick, intégrée ou personnalisée.

ServicesLes sources d'upload, d'options et de specs que les bricks consomment.

ThemingLes noms de classes fk-* que votre brick personnalisée doit réutiliser.