Composants

Deux composants portent toute la surface publique de l’UI : le builder qui produit un spec, et le renderer qui transforme un spec en formulaire fonctionnel. Tout le reste du package n’est qu’une brick interne qu’ils composent.

Le nommage dans les trois intégrations

Le même composant est exposé de trois façons. Les props sont identiques ; seule la syntaxe des événements change :

React

<FkFormRender spec={spec} onFormSubmit={(e) => save(e.detail.data)} />

Les props sont en camelCase, les événements sont des handlers onXxx.

Vue

<FkFormRender :spec="spec" @form-submit="save($event.detail.data)" />

Vue 3 camélise les noms d’événements dans les templates, donc @form-submit et @formSubmit se résolvent tous deux vers l’événement émis formSubmit.

Web Components

el.spec = spec
el.addEventListener('formSubmit', (e) => save(e.detail.data))

Les événements gardent leur nom camelCase brut sur l’élément DOM.

<fk-form-render> stable

Rend un spec sous forme de formulaire fonctionnel.

Props

Prop	Type	Défaut	Rôle
spec	BrickSpec	—	Obligatoire. Le formulaire à afficher.
data	Record<string, unknown>	{}	Valeurs initiales, indexées par la key des bricks.
context	Record<string, unknown>	—	Valeurs d’exécution pour les règles et l’interpolation d’URL. Jamais une valeur de champ, jamais émis.
readOnly	boolean	false	Les valeurs ne peuvent plus changer : readonly sur les contrôles texte, disabled ailleurs ; masque l’action intégrée.
disabled	boolean	false	Rend tous les contrôles indisponibles — attribut disabled partout.
showSubmit	boolean	false	Affiche un bouton de soumission intégré.
submitLabel	string	—	Remplace le libellé de ce bouton.
editable	boolean	false	Rendu en mode builder (contours de sélection, zones de dépôt). Utilisé par le builder lui-même.
selectedPath	string	—	Quelle brick apparaît sélectionnée en mode editable, par chemin.
locale	string	—	Locale utilisée pour résoudre les libellés et messages de validation localisés.
annotations	FieldAnnotations	—	Notes du réviseur, indexées par la key des bricks : { incorrect?, comment? }. Affichées sous les champs concernés.
editableKeys	string[]	—	Si défini, seules ces clés restent modifiables ; tous les autres champs sont en lecture seule.
notes	FieldAnnotations	—	Les verdicts d’une revue antérieure, affichés en rappel discret sous les champs, quel que soit le mode.

Correction guidée

Le verdict d’un réviseur (voir <fk-form-review> plus bas) revient sous forme d’une carte d’annotations. Passez-la au rendu et verrouillez tout ce qui n’a pas été signalé :

import { flaggedKeys } from '@streamline-pulse/formkrafter-core'

<FkFormRender spec={spec} data={previous} annotations={reviews} editableKeys={flaggedKeys(reviews)} />

Les champs signalés affichent un badge « À corriger » et le commentaire sous le contrôle. editableKeys s’applique aux champs et aux collections ; les lignes d’une collection modifiable restent entièrement modifiables.

Contexte d’exécution

Un formulaire a souvent besoin de valeurs que l’hôte connaît et que l’utilisateur ne doit pas fournir : une adresse d’API, un plan client, un jeton d’authentification. Passez-les via context, un sac tenu séparé des données du formulaire :

<FkFormRender spec={spec} data={values} context={{ apiBase, tenant }} />

Les règles et l’interpolation de optionsUrl / optionsHeaders lisent context et data comme une seule map, context l’emportant en cas de collision de nom. Rien de ce que contient context n’est validé, écrit par un effet de valeur, ou présent dans formDataChange / formSubmit. La même prop existe sur fk-form-builder, où elle alimente l’aperçu.

Astuce

Les clés préfixées d’un underscore — data={{ _authToken }} — se comportent de la même façon et restent supportées. Préférez context pour le nouveau code : il dit ce qu’est la valeur au lieu de reposer sur une convention de nommage.

Note

Une brick portant une validation required est marquée automatiquement : un astérisque après son libellé, un « (obligatoire) » réservé aux lecteurs d’écran, et aria-required sur le contrôle. Rien à configurer.

Note

readOnly signifie cette valeur ne peut pas changer, disabled signifie ce contrôle est indisponible — et le rendu diffère. readOnly pose l’attribut HTML readonly sur les champs texte et les zones de texte : la valeur reste sélectionnable, copiable et atteignable au clavier, ce qu’exige un panneau de consultation. Les contrôles pour lesquels HTML ne définit pas readonly — select, case à cocher, radio, fichier — retombent sur disabled et portent aria-readonly, pour que les technologies d’assistance entendent la nuance. Les actions de collection (ajout, suppression, réordonnancement) restent disabled dans les deux cas : ce sont des actions, pas des valeurs. La soumission est neutralisée dans les deux cas.

Variables de gabarit

Les champs texte et zone de texte peuvent proposer des variables de gabarit pendant la saisie. Passez la liste dans le contexte du formulaire sous _variables ; taper {{ ouvre la liste, les caractères suivants filtrent par nom ou par libellé, Entrée ou un clic insère {{nom}}. variables: false dans les configs d’une brique la désactive. Les champs mot de passe ne proposent jamais rien.

render.context = {
  _variables: [
    { name: 'S1$email', label: 'Demande · Email' },
    { name: 'RECORD_ID', label: 'Référence du dossier' },
  ],
};

Événements

Événement	Detail	Se déclenche quand
formDataChange	{ data, isValid, errors }	Un champ change, et après validate()
formSubmit	{ data, isValid, errors }	Le formulaire est soumis et valide. Un formulaire invalide ne l’émet jamais : isValid vaut donc toujours true et errors est toujours vide.
validityChange	{ valid, errors }	Au premier rendu et à chaque changement de verdict

interface DataChangeDetail {
  data: Record<string, unknown>
  isValid: boolean
  errors: Record<string, string>   // indexé par key de brick, ex. "contacts[0].email"
}

Méthodes

await element.validate(): Promise<ValidationResult>

await element.submit(): Promise<ValidationResult>

submit() valide, n’émet formSubmit que si le formulaire est valide, et renvoie le verdict dans les deux cas.

Sans ref

fk-form-render est un custom element associé aux formulaires et remonte sa validité en continu : un écran complet n’a donc besoin ni de ref ni d’appel à validate() :

<form id="checkout">
  <fk-form-render id="form"></fk-form-render>
</form>
<button type="submit" form="checkout">Envoyer</button>

Le bouton externe pilote l’élément via la plateforme, et checkValidity() sur le formulaire reflète les règles du spec. Lier le disabled d’un bouton à validityChange fonctionne pareil, sans formulaire du tout. Là où ElementInternals n’est pas disponible, l’élément se comporte comme avant.

validate() marque chaque brick porteuse d’une key comme touchée (pour que les erreurs deviennent visibles), valide les données à plat, attend la validation ligne par ligne de chaque data grid, fusionne les résultats et émet formDataChange. Il retourne { valid, errors }.

React

import { useRef } from 'react'
import { FkFormRender } from '@streamline-pulse/formkrafter-react'

const ref = useRef<HTMLFkFormRenderElement>(null)
const verdict = await ref.current?.validate()

Vue

<script setup lang="ts">
import { ref } from 'vue'
const form = ref()
// Un ref de template renvoie l'instance Vue, pas le custom element —
// les méthodes du composant vivent sur $el.
const check = async () => (await form.value.$el.validate()).valid
</script>

<template>
  <FkFormRender ref="form" :spec="spec" />
</template>

Web Components

const verdict = await document.querySelector('fk-form-render').validate()

<fk-form-review> nouveau

Affiche un formulaire rempli en lecture seule et laisse un réviseur signaler chaque champ comme incorrect et le commenter. Le rendu est délégué à <fk-form-render> : formulaires imbriqués, règles et libellés localisés se comportent de la même façon.

Props

Prop	Type	Défaut	Rôle
spec	BrickSpec	—	Obligatoire. Le formulaire qui a été rempli.
data	Record<string, unknown>	{}	Les valeurs à relire.
context	Record<string, unknown>	—	Comme sur le rendu.
reviews	FieldAnnotations	{}	Annotations de départ, par exemple un brouillon de cette relecture.
notes	FieldAnnotations	—	Les verdicts de la relecture précédente, affichés en rappel pour que le réviseur regarde à nouveau ces champs ; la nouvelle revue part vide.
locale	string	—	Locale des libellés.

Événements

Événement	Detail	Se déclenche quand
reviewChange	{ reviews, flagged }	Un signalement ou un commentaire change. reviews est la carte complète, flagged les clés marquées incorrectes.

<FkFormReview spec={spec} data={submitted} onReviewChange={(e) => setReviews(e.detail.reviews)} />

Dans une grille, chaque cellule est relue séparément : les clés s’écrivent contacts[0].email, comme les erreurs de validation, et la grille entière peut aussi être signalée. editableKeys accepte ces clés de cellule ; quand seules certaines cellules sont listées, les actions de ligne (ajouter, retirer, réordonner) sont verrouillées. Le rendu natif offre la même chose avec FormReview et les props annotations, notes et editableKeys de FormRenderer.

<fk-form-builder> stable

L’éditeur en glisser-déposer. Il rend sa propre palette, son canvas et son panneau de propriétés.

Props

Prop	Type	Défaut	Rôle
spec	BrickSpec	—	Spec à charger dans le canvas. Omettez-le pour partir d’un formulaire vide.
data	Record<string, unknown>	{}	Valeurs d’aperçu utilisées pendant l’édition.
context	Record<string, unknown>	—	Valeurs d’exécution pour l’aperçu, même contrat que sur le renderer.
locales	string[]	[]	Active le sélecteur de langue d’édition ; les champs du panneau lisent et écrivent alors par locale.
locale	string	—	La langue du chrome du builder : associée à setFkTranslations, la toolbar, la palette et le panneau se re-rendent à la volée — sans remontage. Distincte de la langue d’édition.

Attention

locales est un tableau : il doit donc être défini comme propriété DOM, pas comme attribut. <fk-form-builder locales='["en","fr"]'> échoue silencieusement — affectez el.locales = ['en', 'fr'] à la place. Les wrappers React et Vue s’en chargent pour vous.

Événements

Événement	Detail	Se déclenche quand
specChange	{ spec, patches, inverse }	Toute édition : dépôt, réordonnancement, changement de config, undo, redo, import

interface SpecChangeDetail {
  spec?: BrickSpec
  patches: Operation[]    // RFC 6902, avant
  inverse: Operation[]    // RFC 6902, arrière
}

Sur un undo, un redo et un remplacement complet du spec, patches et inverse sont émis sous forme de tableaux vides — le spec lui-même fait autorité dans ces cas-là.

Brancher les deux ensemble

React

import { useState } from 'react'
import { FkFormBuilder, FkFormRender } from '@streamline-pulse/formkrafter-react'
import '@streamline-pulse/formkrafter-wc/styles.css'
import type { BrickSpec } from '@streamline-pulse/formkrafter-core'

export function Studio() {
  const [spec, setSpec] = useState<BrickSpec>()

  return (
    <>
      <FkFormBuilder onSpecChange={(e) => setSpec(e.detail.spec)} />
      {spec && (
        <FkFormRender spec={spec} onFormSubmit={(e) => console.log(e.detail.data)} />
      )}
    </>
  )
}

Vue

<script setup lang="ts">
import { ref } from 'vue'
import { FkFormBuilder, FkFormRender } from '@streamline-pulse/formkrafter-vue'
import '@streamline-pulse/formkrafter-wc/styles.css'
import type { BrickSpec } from '@streamline-pulse/formkrafter-core'

const spec = ref<BrickSpec>()
</script>

<template>
  <FkFormBuilder @spec-change="spec = $event.detail.spec" />
  <FkFormRender v-if="spec" :spec="spec" @form-submit="onSubmit($event.detail.data)" />
</template>

Web Components

<fk-form-builder></fk-form-builder>
<fk-form-render></fk-form-render>

<script type="module">
  import '@streamline-pulse/formkrafter-wc/dist/formkrafter-wc/formkrafter-wc.esm.js'
  import '@streamline-pulse/formkrafter-wc/styles.css'

  const builder = document.querySelector('fk-form-builder')
  const preview = document.querySelector('fk-form-render')

  builder.addEventListener('specChange', (e) => {
    preview.spec = e.detail.spec
  })
  preview.addEventListener('formSubmit', (e) => console.log(e.detail.data))
</script>

Étapes suivantes

Specs de formulaireCe que contiennent réellement le spec et les patches de specChange.

PackagesPoints d'entrée, exports et relations entre les cinq packages.

ServicesPoints d'injection pour les uploads, les options distantes et les sources de spec.

BricksEnregistrer votre propre brick et faire en sorte que le builder la reprenne.