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	Rend tous les contrôles désactivés et 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.

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.

É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-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.